my-wiki

name	my-wiki
description	用户提到"知识库"、"wiki"、"消化素材"、"整理到知识库"，或对已初始化的知识库执行查询、健康检查、统计、lint、去重等操作。

my-wiki — 个人知识库构建系统

把碎片化的信息变成持续积累、互相链接的知识库。知识被编译一次，持续维护；不是每次查询都从原始文档重新推导。

核心理念

传统 RAG 的问题：每次问问题，AI 从头读原始文件，没有积累。知识库的价值在于编译一次，持续维护——你只需要提供素材，AI 做所有的整理工作。

思维模式

处理任何请求时，先在脑中过三道判断：

1. 判断素材价值：这条信息值得永久保存吗？值→完整处理；不值但有关键概念→简化处理；纯噪音→跳过
2. 判断处理深度：素材是 10000 字的深度文章还是 200 字的碎片？前者需要提取实体、关联主题页、生成摘要；后者只需记录关键概念
3. 判断关联强度：新素材里的概念和已有实体是同一个东西，还是恰好同名？高价值关联→合并到已有实体页；弱关联→在素材页标记 [待创建]

工具选择框架

flowchart TD
    A[用户请求] --> B{知识库存在？}
    B -->|否| C[→ init]
    B -->|是| D{请求类型？}
    D -->|URL/文件/粘贴文本| E[→ ingest]
    D -->|疑问句/定义/查询| F[→ query]
    D -->|综述/深度分析/对比| G[→ digest]
    D -->|健康检查/lint| H[→ lint]
    D -->|状态/统计/有什么| I[→ status]
    D -->|图谱/关联图| J[→ graph]
    E --> K{素材类型？}
    K -->|> 1000字| L[完整处理：实体+主题+摘要]
    K -->|≤ 1000字| M[简化处理：摘要+标记待创建]
    F --> N[先读 index → search.py 搜索 → 综合回答]
    G --> O[读 index → search.py 全量搜索 → 生成深度报告]

兜底规则：直接给 URL/文件但没说做什么 → 默认走 ingest。搜不到相关内容 → 建议补充素材。

边界与防坑

知识库大了，index 会过时。 index.md 是手动维护的目录，wiki 页面多了之后 inevitably 会漏。搜不到不代表知识库里没有——query 工作流要同时查 index 和用 search.py 全文搜索，不能只看 index。

[[双向链接]] 不代表语义关联。 两个页面互相链接可能只是因为它们恰好提到了同一个词（比如"模型"在 ML 和时尚领域含义完全不同）。关联实体页时，判断"是不是同一个东西"比"有没有提到这个词"重要得多。

短素材也可能有高价值概念。 一条 200 字的推文可能包含一个全新的框架/术语，值得创建实体页。不要用字数作为"值不值得深入处理"的唯一标准——概念密度比字数更重要。

经验积累

references/source-patterns/ 目录存放不同素材来源的处理经验。当 AI 在处理某类来源（如微信公众号、Twitter、PDF 论文）时踩了坑或发现了更好的提取策略，将经验追加到对应文件中。

• 已有经验文件：按素材来源域名命名，如 mp.weixin.qq.com.md、twitter.com.md
• 新来源首次处理时创建经验文件，记录"这个站点的页面结构特点"和"提取时的注意事项"

这些经验文件会在后续 ingest 相同来源时被自动读取，帮助 AI 更精准地提取知识。

Script Directory

Scripts located in scripts/ subdirectory (Python 3.10+, zero external dependencies). SKILL_DIR = this SKILL.md's directory. Script path = ${SKILL_DIR}/scripts/<script-name>.

跨平台兼容：所有脚本使用 pathlib.Path，Windows/Linux/macOS 通用。 调用时统一使用 python3（Linux/macOS）或 python（Windows），根据当前环境选择。

多平台 Skill 目录

平台	Skill 安装路径
WorkBuddy	~/.workbuddy/skills/my-wiki/
Claude Code	~/.claude/skills/my-wiki/
OpenCode	~/.config/opencode/skills/my-wiki/
OpenClaw	~/.openclaw/skills/my-wiki/

SKILL_DIR 的解析方式因平台而异，但脚本内部的路径处理完全跨平台。 如果平台不支持 {SKILL_DIR} 变量，可用 __FILE__ 等价机制获取当前 SKILL.md 所在目录。

---

通用前置检查

除 init 外，其他工作流先执行：

1. 检查当前工作目录是否有 .wiki-schema.md → 有就用当前目录
2. 没有 → 读取 {SKILL_DIR}/wiki-config.json，取 wikis[current] 的路径
3. 都没有 → fallback 检查 ~/.my-wiki-path 文件获取默认路径（向后兼容）
4. 都没有 → ingest 自动先 init，其他工作流提示用户先初始化

---

工作流 1：init（初始化知识库）[PROCEDURE]

1. 询问主题："知识库围绕什么主题？比如'AI 学习笔记'、'DevOps 实践'"
2. 询问路径：默认 ~/Documents/my-wiki/，用户可自定义
3. 询问名称："给这个知识库起个名字方便切换？比如'devops'、'reading'。不填则用目录名。"
4. 运行脚本：

   python {SKILL_DIR}/scripts/init.py --wiki-root "<路径>" --topic "<主题>" --name "<名称>"
   

5. 脚本会自动更新 {SKILL_DIR}/wiki-config.json，记录名称、路径、主题
6. 输出引导：告知用户可以给链接、文件、粘贴文本，或说"查询 XX"来搜索

wiki-config.json 支持多个知识库，current 字段标记当前活跃的知识库。前置检查按此文件定位知识库路径。

---

工作流 2：ingest（消化素材）[MIXED]

这是最核心的工作流。确定性操作用脚本，知识提取用 AI 判断。

第一段：确定性操作 [PROCEDURE]

1. 执行前置检查，确定知识库路径
2. 调用 ingest_prepare.py 处理素材：

   # URL 类素材
   python {SKILL_DIR}/scripts/ingest_prepare.py --wiki-root "<路径>" --url "<URL>" --title "<标题>"
   
   # 本地文件
   python {SKILL_DIR}/scripts/ingest_prepare.py --wiki-root "<路径>" --file "<文件路径>" --title "<标题>"
   
   # 粘贴文本
   python {SKILL_DIR}/scripts/ingest_prepare.py --wiki-root "<路径>" --text "<文本内容>" --title "<标题>"
   
   # 强制覆盖重复素材
   python {SKILL_DIR}/scripts/ingest_prepare.py --wiki-root "<路径>" --url "<URL>" --force
   

   脚本输出 JSON，关键字段：is_long（是否 > 1000 字）、raw_path、status
3. 如果素材是 URL → 先检查 references/source-patterns/ 下是否有该域名的经验文件，有则读取；然后用 web 工具提取网页内容

第二段：AI 知识提取 [REASONING]

根据脚本返回的 is_long 判断处理深度，但不要机械执行——用你的判断力调整：

完整处理（is_long: true，或素材虽然短但概念密度极高）：

• 提取核心观点（3-5 个）和关键概念（3-5 个）
• 生成素材摘要页 → wiki/sources/{日期}-{标题}.md
• 对每个关键概念，判断它和已有实体页的关系：
  • 是同一个东西 → 读取实体页，在"不同素材中的观点"section 追加新信息，更新 updated 日期
  • 恰好同名但含义不同 → 创建新实体页，加 disambiguation 说明
  • 新概念，知识库没有 → 创建新实体页 → wiki/entities/{概念名}.md
• 判断是否需要创建或更新主题页（只有当素材提供了足够多新信息来丰富一个主题时才值得）

简化处理（is_long: false 且概念密度一般）：

• 提取核心观点（1-3 个）和关键概念（1-3 个）
• 生成素材摘要页 → wiki/sources/{日期}-{标题}.md
• 概念没有对应实体页时，在摘要页标记 [待创建: [[概念名]]]，不主动创建实体页
• 跳过主题页创建/更新

第三段：收尾 [PROCEDURE]

1. 每个新创建/更新的页面做格式校验：

   python {SKILL_DIR}/scripts/validate_page.py --wiki-root "<路径>" --page-path "<页面路径>" --page-type <entity|topic|source>
   

2. 更新 index.md（在对应分类下添加条目）和 log.md（添加操作记录）
3. 如果素材来自之前没处理过的域名，在 references/source-patterns/ 下创建经验文件，记录提取时的发现

---

工作流 3：query（查询知识库）[REASONING]

这是需要判断的工作流——搜索只是手段，综合回答才是目标。

1. 执行前置检查
2. 先读 index.md 快速定位相关条目——index 是人工维护的精华目录，优先级高于全文搜索
3. 用 search.py 全文搜索补充：

   python {SKILL_DIR}/scripts/search.py --wiki-root "<路径>" --query "<关键词>"
   

   不要只看 index。知识库大了之后 index 会过时，search.py 能找到 index 没收录的页面。

4. 阅读相关页面后综合回答，不要简单罗列搜索结果
5. 回答中标注来源页面（用 [[链接]] 或 [来源](路径) 格式）
6. 判断：如果查询触发了有价值的分析，建议保存为新页面

搜索技巧：多词查询用空格分隔（AND 逻辑）；用 --type entity 只搜实体页；用 --include-raw 搜原始素材。

---

工作流 4：digest（深度综合分析）[REASONING]

digest 的价值在于跨素材的综合分析，不是简单拼接。

1. 执行前置检查
2. 读 index.md 定位所有相关素材和页面
3. 用 search.py 全量搜索相关关键词，确保不遗漏：

   python {SKILL_DIR}/scripts/search.py --wiki-root "<路径>" --query "<关键词>" --include-raw
   

4. 综合分析（不是拼接）：阅读所有相关页面后，判断：
   • 不同素材之间的观点是一致的还是有冲突？
   • 哪些观点有多个素材支持（可信度高）？
   • 哪些观点只有单一来源（需要更多证据）？
   • 知识脉络是什么（按时间线或逻辑链）？
   • 还有哪些问题没有解决？
5. 生成结构化深度报告 → wiki/synthesis/{主题}-深度报告.md
6. 更新 index.md 和 log.md

---

工作流 5：lint（知识库健康检查）[MIXED]

脚本负责结构检查，AI 负责语义检查。

第一段：结构检查 [PROCEDURE]

python {SKILL_DIR}/scripts/lint.py --wiki-root "<路径>"

脚本返回 JSON：orphan_pages（孤立页面）、broken_links（断链）、index_mismatches（索引不一致）、registry_mismatches（注册表不一致）。

第二段：语义检查 [REASONING]

根据脚本报告，AI 额外做：

1. 矛盾检测：随机抽取 5-10 个页面，检查不同页面对同一概念是否存在矛盾描述
2. 交叉引用建议：检查相关页面之间是否缺少互相链接
3. 过时判断：判断是否有页面内容已经过时（基于素材来源的时间戳和知识时效性）

---

工作流 6：status（知识库状态）[PROCEDURE]

1. 执行前置检查
2. 运行脚本：

   python {SKILL_DIR}/scripts/status.py --wiki-root "<路径>"
   

3. 根据脚本输出的 JSON，生成用户友好的状态报告
4. 根据当前状态给出建议（如"你可能想深入了解 X，或者对 Y 做一次 digest"）

---

工作流 7：graph（知识图谱）[MIXED]

脚本生成 Mermaid 代码，AI 在聊天中直接渲染给用户看。

第一段：生成图谱 [PROCEDURE]

python {SKILL_DIR}/scripts/graph.py --wiki-root "<路径>" --max-nodes 30

脚本输出 JSON，关键字段：nodes（节点数）、edges（关系数）、mermaid（Mermaid 代码）、truncated（是否截断）。

第二段：展示图谱 [REASONING]

1. 从脚本输出中提取 mermaid 字段
2. 直接在聊天中输出 Mermaid 代码块（WorkBuddy/VS Code 会渲染为可视化图谱）：

   ```mermaid
   {mermaid 代码}
   ```
   

3. 附带文字摘要：节点数、关系数、类型分布
4. 如果 truncated: true，告知用户"图谱较大，仅展示最核心的 {N} 个节点，可通过 --max-nodes 50 扩大范围"
5. 如果用户要求详细交互（缩放/拖拽/搜索），生成 HTML 版本：

   python {SKILL_DIR}/scripts/graph.py --wiki-root "<路径>" --max-nodes 50 --format html
   

   然后用浏览器预览生成的 wiki/knowledge-graph.html

---

页面生成规范

所有 wiki 页面必须遵循以下格式。

Frontmatter（必须）

---
tags: [标签1, 标签2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [素材引用]
---

内容结构

• # 一级标题：页面名称
• > 引用块：一句话摘要（紧跟标题下方）
• ## 二级标题：各 section
• [[双向链接]]：页面间引用（Obsidian 兼容）
• [待创建: [[概念名]]]：标记尚未创建的实体

实体页必须包含的 section

• 简介
• 关键信息
• 详细内容
• 不同素材中的观点（核心价值 section——这里存放跨素材的交叉验证和观点对比）
• 相关页面

素材摘要页必须包含的 section

• 基本信息
• 核心观点
• 关键概念
• 与其他素材的关联
• 原文精彩摘录
• 相关页面