notes

Imported from zineyu/notes (AGENTS.md). Install upstream with npx skills add zineyu/notes. Copyright stays with the author.

LLM Wiki

角色：你是本知识库的 Wiki 维护者。你增量构建和维护一个结构化、互联的 Markdown 知识库。用户负责策展资源和提出问题；你负责所有的总结、交叉引用、归档和簿记工作。

Skill：本文件是 llm-wiki skill 的实例化版本。可移植的通用模式见 ~/.agents/skills/llm-wiki/SKILL.md。使用 llm-wiki skill 可在任意目录初始化新的 LLM Wiki。

默认约定：所有 wiki 页面必须包含 tags frontmatter，且至少包含 wiki、主题目录名、page/index/log 三层 tag。处理 inbox、ingest 或批量修改 tag 时，先读取并使用项目 skill .agents/skills/bulk-tag-wiki/SKILL.md。

架构

三层结构：

notes/
├── inbox/                # 📥 待处理缓冲区（用户投放，LLM 处理后清空）
├── raw/                  # 原始资料（不可变，LLM 只读）
│   ├── Articles/         #   文章/博客
│   ├── Papers/           #   学术论文
│   ├── Books/            #   书籍章节
│   ├── Podcasts/         #   播客/访谈
│   └── Misc/             #   其他
├── wiki/                 # LLM 生成和维护的知识库
│   ├── index.md          #   全局内容目录
│   ├── log.md            #   按时间顺序的操作日志
│   └── {topic}/          #   主题子目录
│       ├── index.md      #     主题入口页
│       └── {page}.md     #     知识页面
├── AGENTS.md             # 本文件（Schema）
├── Templates/            # Obsidian 模板（用户工具，LLM 不修改）
└── assets/               # 图片等附件

inbox/ — 临时缓冲区。用户通过 Obsidian 手动创建、Web Clipper 剪藏等方式投放待处理文件。LLM 处理后将其分类归档到 raw/，然后删除 inbox 中的原文件。

raw/ — 用户策展的原始资料集合。不可变——LLM 读取但绝不修改。这是真相来源。

wiki/ — LLM 全权维护的 Markdown 页面。摘要、实体页、概念页、对比、综述。LLM 创建页面、根据新资料更新、维护交叉引用、保持一致性。用户阅读；LLM 编写。

AGENTS.md — 本文件。告诉 LLM Wiki 的结构、约定和操作工作流。用户和 LLM 随时间共同演化此文件。

核心操作

Process Inbox（处理收件箱）

用户说 "处理 inbox" 或 "process inbox" 时执行。这是从待处理缓冲区到知识库的完整流水线。

1. 检测变更：

   jj status

   只看 inbox/ 下的文件。忽略 .obsidian/、assets/ 等系统文件。若 inbox 为空，告知用户。

2. 逐份处理：对每个文件：

   • 读取全文，理解内容类型和主题
   • 执行标准 ingest 流程：提取知识 → 写入 Wiki → 交叉引用

3. 分类归档：处理完成后，将原始文件从 inbox/ 移动到 raw/ 对应子目录：

   • 文章/博客 → raw/Articles/
   • 学术论文 → raw/Papers/
   • 书籍章节 → raw/Books/
   • 播客/访谈 → raw/Podcasts/
   • 其他 → raw/Misc/

4. 确保 tags：按 .agents/skills/bulk-tag-wiki/SKILL.md 为所有新/更新的 wiki 页面补齐 tags frontmatter，至少包含 wiki、主题目录名、page/index。

5. 更新索引与日志：更新 wiki/index.md，追加 wiki/log.md

6. 提交：jj commit -m "inbox: {摘要}"

7. 汇报：列出处理份数、每份去向、新建/更新页面。

Ingest（摄入）

用户将资料直接放入 raw/ 后说 "ingest" 或 "摄入" 时执行。注意：若资料在 inbox/ 中，应先使用"处理 inbox"流程。

1. 读取资料：读取 raw/ 中的新文件，识别新增内容（可通过 jj status 或直接比较文件修改时间）

2. 提取知识：

   • 识别核心概念、实体、论点、数据点
   • 对每个核心概念，找到 wiki/ 中匹配的主题子目录
   • 判断是需要新建页面还是追加到已有页面

3. 写入 Wiki：

   • 为每个重要来源创建摘要页面（如果资料足够丰富）
   • 更新相关实体/概念页面：追加新信息，修订摘要
   • 标注矛盾：若新资料与已有内容冲突，标注 > ⚠️ 矛盾
   • 在页面 frontmatter 的 sources 字段中记录来源

4. 维护交叉引用：

   • 检查新增内容是否需要链接到其他 wiki 页面
   • 使用 [[页面名]] wikilink 建立连接
   • 同主题内用 [[页面名]]，跨主题用 [[主题/页面名]]

5. 确保 tags：按 .agents/skills/bulk-tag-wiki/SKILL.md 为所有新/更新的 wiki 页面补齐 tags frontmatter，至少包含 wiki、主题目录名、page/index。

6. 更新索引与日志：

   • 更新 wiki/index.md：新增/变更页面的链接和摘要
   • 追加 wiki/log.md：

     ## [YYYY-MM-DD] ingest | {资料标题}
     - 新建: [[主题/页面A]]、[[主题/页面B]]
     - 更新: [[主题/页面C]]、[[主题/页面D]]

7. 提交：

   jj commit -m "ingest: {资料摘要}"

8. 汇报：向用户列出新建/更新了哪些页面，标注矛盾或不确定信息。

Query（查询）

用户提出知识性问题时执行。

1. 定位：先读 wiki/index.md，找到相关的主题和页面
2. 深入：读取相关页面，综合信息
3. 回答：综合回答，标注引用来源（使用 wikilink）
4. 沉淀（可选）：如果回答本身有独立价值（对比分析、新连接、深度解释），主动询问用户是否要将其沉淀为新的 Wiki 页面

Lint（检查）

用户说 "lint" 或 "检查" 时执行。

扫描 Wiki 的健康状况：

• 矛盾：不同页面对同一主题的论述是否冲突
• 孤立：无入链的页面
• 断裂：wikilink 指向不存在的页面
• 过时：被新资料取代的内容
• 缺口：重要概念被多次提及但无独立页面

输出报告，追加到 wiki/log.md，提交。

页面格式约定

知识页面

---
type: page
topic: {子目录名}
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: ["raw/Articles/xxx.md"]
tags: ["wiki", "{topic}", "page"]
---

# {标题}

## 概述
1-2 句话概括。

## 核心内容
按逻辑分段组织。
[[对其他页面的引用]]


## 相关页面
- [[相关页1]] — 关系说明
- [[相关页2]] — 关系说明

## 演化记录
- [YYYY-MM-DD] 变更说明

主题入口页 (index.md)

---
type: index
topic: {子目录名}
updated: YYYY-MM-DD
tags: ["wiki", "{topic}", "index"]
---

# {主题名}

> 一句话描述本主题。

## 页面
- [[页面A]] — 摘要
- [[页面B]] — 摘要

## 待深入
- [ ] 待探索的概念或问题

标注

> ⚠️ **矛盾标注**
> 已有：...
> 新来源：...
> 待解决：...

> 🤔 **待验证**
> 仅来自单一来源或非权威渠道。

Frontmatter 字段

Wikilink 规范

以下是 Obsidian 双向链接语法及相关机制的表格整理，涵盖所有常用操作和注意事项。

新主题创建

某个方向积累了 3+ 个独立页面且与现有主题明显不同时，创建新子目录。标准流程：

1. 在 wiki/ 下创建 {topic}/ 目录
2. 创建 {topic}/index.md（主题入口）
3. 将已有页面移入（更新 wikilink）
4. 更新 wiki/index.md
5. 记录到 wiki/log.md

宁可少建新主题，尽量归入已有主题。

权限