# My Wiki

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

- Skill: `modoojunko/my-wiki` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add modoojunko/my-wiki`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modoojunko/my-wiki/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: modoojunko (https://skillmd.com/u/modoojunko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/modoojunko/my-wiki

---


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

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

## 核心理念

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

### 思维模式

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

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

## 工具选择框架

```mermaid
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. **运行脚本**：
   ```bash
   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` 处理素材：
   ```bash
   # 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. 每个新创建/更新的页面做格式校验：
   ```bash
   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 全文搜索补充：
   ```bash
   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 全量搜索相关关键词，确保不遗漏：
   ```bash
   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]

```bash
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. 运行脚本：
   ```bash
   python {SKILL_DIR}/scripts/status.py --wiki-root "<路径>"
   ```
3. 根据脚本输出的 JSON，生成用户友好的状态报告
4. 根据当前状态给出建议（如"你可能想深入了解 X，或者对 Y 做一次 digest"）

---

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

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

### 第一段：生成图谱 [PROCEDURE]

```bash
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 会渲染为可视化图谱）：
   ````markdown
   ```mermaid
   {mermaid 代码}
   ```
   ````
3. 附带文字摘要：节点数、关系数、类型分布
4. 如果 `truncated: true`，告知用户"图谱较大，仅展示最核心的 {N} 个节点，可通过 `--max-nodes 50` 扩大范围"
5. 如果用户要求详细交互（缩放/拖拽/搜索），生成 HTML 版本：
   ```bash
   python {SKILL_DIR}/scripts/graph.py --wiki-root "<路径>" --max-nodes 50 --format html
   ```
   然后用浏览器预览生成的 `wiki/knowledge-graph.html`

---

## 页面生成规范

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

### Frontmatter（必须）

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

### 内容结构

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

### 实体页必须包含的 section

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

### 素材摘要页必须包含的 section

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