loletranga/个人知识库与知识图谱

个人知识库 × 知识图谱（文件式，可迭代）

把一批 Markdown 文档变成"可回忆、可追溯"的知识网络：每篇文档加一层 frontmatter 元数据，用三类关系连成图谱，脚本重建蒸馏层（决策登记簿 + 图谱邻接表），供 Agent 在分析与决策前调取过往思路与历史背景。

核心理念（先读懂再动手）

1. 文档本体是唯一事实源。图谱不是独立系统，frontmatter 和双链就长在用户的 md 文件里；graph/ 目录是纯生成物，删掉可随时重建。任何修改都只发生在源文档上。
2. 写入必须先确认。frontmatter 由你起草，但批量写回前必须给用户看样本并确认；supersedes（谁推翻了谁）这类判断性关系必须列清单确认，不允许静默写入。
3. 宁降级不硬写。读不出结论的文档标 status: reference，不要编造 conclusion。一个错误的"一句话结论"会在决策时误导用户，比缺失危害大得多。

本技能目录下有两个随行文件（位于本 SKILL.md 所在目录）：

• scripts/gen_kb_graph.py —— 图谱生成脚本（纯标准库，离线可用）
• references/schema.md —— frontmatter 完整规范、三类边语义、输出模板、回忆输出格式。首次建库或对字段拿不准时先读它。

---

运行流程

第 0 步：确定范围，向用户说明将要发生什么

• 用户给的是文件夹 → 该文件夹即知识库根目录。
• 用户给的是单个或几个文件 → 询问：以这些文件所在文件夹为知识库根目录（推荐，历史文档能互相连成图谱），还是新建一个独立知识库文件夹存放它们。
• 用户没有任何文件，想先建库 → 走第 2 步"空库骨架"。
• 开工前用两三句话向用户确认：根目录是哪个、会修改哪些文件（源文档 frontmatter + 新增 graph/ 目录）、不会动文档正文。

第 1 步：检测知识库状态

读根目录：

• 已存在 <根>/gen_kb_graph.py 或 <根>/graph/INDEX.md → 迭代模式（已有库）
• 否则 → 建库模式（新库）

第 2 步 A：建库模式（含空库骨架）

1. 空库骨架（用户没有历史文件时）：创建以下文件后跳到第 3 步告知即可——
   • <根>/知识库规范速览.md：从 references/schema.md 摘取 frontmatter 模板与三条核心规则，方便用户日常写作时对照（自带 status: reference）
   • <根>/模板-分析文档.md：带完整 frontmatter 的空白模板（同上自带 frontmatter）
2. 安装脚本：把技能目录的 scripts/gen_kb_graph.py 复制为 <根>/gen_kb_graph.py（已存在则跳过）。装进知识库是为了它自包含——用户或其他 Agent 不依赖本技能也能重建图谱。
3. 试运行：python3 <根>/gen_kb_graph.py <根>。读 <根>/graph/report.md 的总览，向用户报告规模（几篇文档、几篇缺 frontmatter）。
4. 起草元数据（核心工作量）：先读 references/schema.md，然后按子目录或领域分批处理：
   • 逐篇读文档，起草 frontmatter：date（结论产生日）、domain、status（active/superseded/reference）、conclusion（一句话结论，只写"这篇最终主张什么"，不写内容摘要）
   • 先给样本：挑 2-3 篇有代表性的（一篇决策文档、一篇资料），展示你将写入的 frontmatter，用户确认口径后再批量
   • 识别演进关系：文件名含 v2/新版/副本/修订、或内容上前后推翻的文档对，建议 supersedes 指向，列成清单让用户确认后写入
   • 每写完一批报告进度；正文一个字都不动，只加 frontmatter
5. 重建与交付：重跑脚本（自动生成 graph/kb-graph.html 可视化页面），向用户展示 INDEX.md 的前几行和 report.md 剩余缺口，并告知可用浏览器打开 kb-graph.html 查看交互式图谱。

第 2 步 B：迭代模式（已有库）

1. 运行已有的 <根>/gen_kb_graph.py（不在了就从技能目录重新复制）
2. 读 graph/report.md，只处理增量：缺 frontmatter 的新文档、缺 date/conclusion 的文档、断链。起草 → 确认 → 写回
3. 语义边补充：对新增文档，通读后提议它与既有文档的 related（"同一件事的两个侧面"）和 supersedes（"这篇修正了那篇"），附一句话理由，确认后写入
4. 重建（含 kb-graph.html 可视化页面刷新），向用户报告变化量（新增节点/边数、剩余缺口）

第 3 步：告知用户如何使用

每次建库/迭代结束时，提示用户今后这样用（原话可参考）：

以后做分析或决策前，直接对我说："回忆一下我之前关于 XX 的思路和结论"，我会检索图谱、顺演进链核对时效后给你参考报告。想直观看图谱，用浏览器打开 graph/kb-graph.html 即可（可搜索、筛选、点节点看详情）。文档继续按老习惯写，写完说一声"更新知识库"即可，新文档我会自动补元数据、连关系。

---

回忆模式（决策前检索）

用户要求回忆过往思路时，且目标目录已有 graph/ 生成物，按此流程执行，全程只读：

1. 读 graph/INDEX.md，用主题关键词匹配文档标题与结论，初筛相关项（宁多勿漏）
2. 需要扩展时读 graph/GRAPH.md：顺初筛文档的 supersedes 演进链、related 邻居补齐背景
3. 精读相关文档的 frontmatter 与结论段（不必全文通读）
4. 按固定格式输出（完整示例见 references/schema.md）：
   • 相关思路清单：每条 = 日期 | 一句话结论 | 状态 | 文档链接
   • 演进链：该问题上的思路变化轨迹，注明何时应什么被推翻/修正
   • 对当前问题的参考点：哪些结论可直接沿用、哪些已过时须注意
   • 无先例声明：若图谱中查不到该问题的历史决策，明确说"这是全新决策，无过往先例可依"——这同样是有价值的输出

---

与用户的确认检查点（必须停下来）

1. 建库前：根目录范围、忽略规则（可用 <根>/.kbignore 排除目录，每行一个通配）
2. 批量写 frontmatter 前：2-3 篇样本确认
3. 写入 supersedes 关系前：成对清单确认
4. 任何正文内容的修改：默认禁止，用户明确要求才做

脚本用法

python3 gen_kb_graph.py <知识库根目录> [--output graph] [--ignore "books,old,*_old"] [--no-html]

默认忽略：隐藏目录、.venv、venv、node_modules、pycache、.git、输出目录自身。幂等，随时可重跑；输出 5 个文件（INDEX.md / GRAPH.md / kb-graph.json / report.md / kb-graph.html），格式见 references/schema.md。kb-graph.html 是零依赖的单文件可视化页面（力导向图谱 + 决策清单表格，支持搜索/筛选/点击详情/双击打开源文件），环境允许可直接用浏览器打开向用户展示。

升级边界

文档超过约 500 篇、GRAPH.md 无法一次读完、或需要频繁多跳推理时，文件式图谱到达上限，建议用户迁移 LightRAG（图谱+向量混合检索）——frontmatter 与双链就是最好的迁移语料，迁移无损。在那之前不要引入数据库或外部服务。