---
name: mywiki-ingest
description: "将素材摄入通用知识 wiki——保存原始素材、提炼理解、创建/更新节点、建立语义关系。"
---

# myWiki 摄入

用户给你素材（文件、URL、粘贴文本、口述、图片说明、对话记录等）。你的工作是把素材沉淀成 wiki 中可复用、可追溯、可演化的知识节点。

这不是机械摘要，也不是把素材按章节切碎。你要判断素材中哪些内容值得成为长期知识，哪些应该合并进已有节点，哪些只是 raw source 中的普通信息。

## 核心原则

- **理解优先**：节点存储的是一个可复用的理解、观察、判断、疑问或辨析，不是原文摘抄。
- **事实支撑**：被素材解释、补充、对比或用于推理的概念/事实，是 `observation` 节点候选。洞见不能悬空地建立在 raw 里未结构化的事实上。
- **洞察来源**：`insight` 要分 `explicit` / `inferred` / `mixed`。前者尊重原意，后者负责 wiki 自进化。
- **软数量**：字数和节点数只是信号，不是目标。不要为了凑数量拆节点，也不要为了凑字数扩写。
- **主题优先**：批量素材先按主题聚类，再决定节点；不要按文件、章节或标题机械地产生节点。
- **粒度校准**：节点要能被未来独立引用。宁可多建有清晰价值的 `growing` 节点，也不要把多个独立洞见压缩进一个综合节点。
- **保守状态**：状态由你自动判断。拿不准时用 `growing`，不要把首次摄入的节点轻易标成 `mature`。
- **最小改动**：只改本次素材直接相关的节点、index 和 log。不要顺手大面积重写旧节点。
- **变更预算**：预计新建超过 10 个节点、更新超过 5 个旧节点、改写 `mature` 节点、或重排多个主题簇时，先停下汇报计划，等用户确认。
- **可追溯**：新增/更新节点必须关联 raw source，或明确来自用户口述。

## Step 0 — 定位 wiki

按主 SKILL.md 的路径查找规则定位 wiki 目录（优先 `~/.mywiki/config.json` 中的 `wikiDir`，默认 `~/mywiki`）。以下用 `<wiki>` 指代实际路径。

```
<wiki>/
├── nodes/          # wiki 节点，平铺
├── raw/            # 原始素材，不修改已有文件
└── meta/
    ├── index.md    # 内容索引，必须维护
    └── log.md      # 操作日志，只追加
```

找不到时询问用户 wiki 目录位置。

## Step 1 — 保存素材

将原始素材保存到 `<wiki>/raw/`。已有 raw 文件不可修改。

- 单份素材：命名为 `YYYY-MM-DD-<简短标题>.md`，或保留用户已有文件名。
- 批量素材：保留原文件名更利于回源；必要时只做安全的文件名规范化。
- URL 素材：获取正文后保存，同时记录原 URL。
- 图片或附件：保存到 `<wiki>/raw/assets/`。
- 很短的用户口述可以不落 raw，但节点 source 中要说明来自本次口述。

## Step 2 — 读取已有上下文

写任何节点前，先了解已有 wiki，避免重复和误连。

使用漏斗，而不是通读大 wiki：

1. 读 `<wiki>/meta/index.md`，找可能相关的主题簇和节点 id。
2. 用素材标题、关键词、同义词、领域词在 `<wiki>/nodes/` 中 grep，补足 index 漏掉的候选。
3. 扫描候选节点的文件名、frontmatter、首屏正文，按重合度排序。
4. 精读最相关的旧节点正文，通常先读 top-5；只有发现强相关或冲突时才继续扩大。

wiki 很小时可以多读；wiki 大时不要把 50 个节点都塞进上下文。优先读同主题、上位概念、对照概念、开放问题和可能重复的节点。

## Step 3 — 分析素材并聚类

先通读素材，形成整体画面，再决定节点。批量素材尤其要先聚类，不要边读边按文件产节点。

### 批量摄入模式

当素材超过 5 份、来源跨度大，或预计新建/更新节点较多时，先进入批量模式：

1. 粗读全部素材，按主题簇整理候选节点。
2. 输出候选节点清单：`id 草案 / title 草案 / meta_type / 为什么独立 / 主要来源 / 可能关系`。
3. 输出跳过清单：说明主题是 `absorbed into <node-id>`、`left in raw`，还是 `deferred candidate`。
4. 等用户确认后再写节点；如果用户明确要求“直接处理”，可以跳过确认，但最终汇报必须包含这两张清单。
5. 分批执行时，以主题簇为断点；每批完成后更新 index/log，下一批从已确认清单继续。

对每个候选主题问：

- **是否值得长期保留**：半年后重读是否仍有价值？
- **是否是独立理解**：它是否承担一个清晰的认知单元，还是只是另一个节点的一段补充？
- **是否是支撑事实**：素材是否解释了这个概念/事实，并且其他节点会依赖它来形成判断？
- **是否已有节点承载**：如果已有节点能承载，优先更新旧节点，而不是新建。
- **是否有跨素材综合**：多个素材共同指向一个更高层主题时，考虑创建综合节点。
- **是否只是通用背景**：只有未被解释、未被应用、未参与推理的普通名词、孤立步骤和碎事实才留在 raw。被素材解释过且支撑后续理解的基础概念，不应因为“通用”而跳过。

节点数量由“独立认知单元”的数量决定，不由素材数量决定。一批素材可以产出 0 个、1 个、多个节点，也可以只更新旧节点。

### 独立认知单元判断

一个候选主题更可能应该独立成节点，如果它满足多项：

- 未来能被单独引用，而不是只能作为另一个节点的例子存在。
- 有自己的机制、判断、权衡、边界或反例。
- 素材对它做了定义之外的解释、补充、应用、风险分析、约束说明或业界对照。
- 在不同语境下会被独立问到或独立复用。
- 和旧节点会形成不同关系，例如一个是 `prerequisite`，另一个是 `contrasts`。
- 移出综合节点后，综合节点仍然成立，且它自己也能自足表达。
- 对其他项目、领域或后续素材有迁移价值。

一个候选主题更可能不该独立成节点，如果它只是未展开的名词、字典式定义、单个事实、操作步骤、代码细节、同一观点的证据、或暂时无法写出清晰主张。此时优先留在 raw、合并进已有节点，或标为 `seed`。

### 事实/概念节点

事实节点不是百科全书条目，也不是所有名词都建节点。它记录“素材如何解释这个概念，以及它在本 wiki 中支撑什么理解”。

当素材出现以下情况时，优先创建或更新 `observation` 节点：

- 素材专门解释某个概念、机制、协议、风险、约束、现象或术语。
- 素材把概念放进具体应用场景、项目实现、行业对照或失败案例中。
- 后续 insight / decision / comparison 需要先理解它，否则推理链会断。
- 多个候选节点都会引用它，或它能作为 `prerequisite` 连接多个主题。
- 用户给的素材本身带有“查漏补缺”“基础概念补齐”“概念解释”意图。

保持事实节点克制：

- 只写素材中给出的解释、边界、例子和 wiki 相关用途，不补成完整教科书。
- 只记录对本 wiki 有支撑作用的部分；纯词典定义、无上下文名词、一次性细节仍留 raw。
- 如果解释很薄但未来会被补充，可以建 `seed`；如果解释足以自足阅读，通常是 `growing`。
- insight 可以建立在 observation 上，但不要把支撑事实全部塞进 insight 正文里。

### 粒度校准

列出候选节点后必须自检：

- 如果一个节点正文需要 3 个以上小标题才能讲清，且小标题分别对应独立机制/判断/权衡，它可能该拆。
- 如果两个主题在不同语境下会被独立引用，它们该分开。
- 如果一个机制、模式或方法在其他素材中也能复用，它值得独立。
- 如果标题只能写成 “A + B + C” 或正文只是并列塞入多个洞见，优先拆分。
- 如果两个候选主题总是共享同一推理链、同一关系、同一来源证据，且单独拆开会变薄，优先合并。
- 宁可多建有来源、有主张的 `growing` 节点，也不要把多个独立洞见压成一个“综合节点”。但不要把普通定义和孤立事实强行节点化。

## Step 4 — 写/更新节点

每个节点是一个 markdown 文件：`<wiki>/nodes/<id>.md`。

### 文件命名

- `id` 与文件名一致，使用 kebab-case 英文。
- id 表达主题，不必追求标题式完整句。
- title 用中文，表达该节点的核心理解或问题。

### Frontmatter 模板

```yaml
---
id: <与文件名一致，不含 .md>
title: <中文标题>
meta_type: <observation | insight | decision | question | comparison>
insight_origin: <explicit | inferred | mixed | 可留空，非 insight 节点通常省略>
domains:
  - "#大类/细分"
status: <seed | growing | mature | needs-split | archived>
created: YYYY-MM-DD
updated: YYYY-MM-DD
wiki: <可选>

sources:
  - title: "来源标题"
    path: "raw/文件名.md"
    date: YYYY-MM-DD
    section: "可选：章节/段落/位置"

relations:
  - to: <目标节点 id>
    type: <关系类型>
    note: "可选补充说明"

derived_from: []
splits_into: []
---
```

### meta_type 判断

| 值 | 用途 |
|---|---|
| `observation` | 看到、读到、听到的事实或材料中的明确说法 |
| `insight` | 解释机制、因果、模式、权衡或可迁移理解 |
| `decision` | 某个主体基于理解作出的选择、判断、原则或立场 |
| `question` | 尚未解决但值得持续追踪的问题 |
| `comparison` | 两个或多个对象之间的差异、取舍、边界本身值得单列 |

判断要诚实。描述“是什么”通常是 observation；材料中对概念的解释、补充、应用和对照也通常先记为 observation。你自己综合出的“为什么/代价/机制/迁移”才可能是 insight；绑定具体情境的选择更像 decision。

### 洞察来源判断

| 值 | 用途 |
|---|---|
| `explicit` | 用户或素材作者已经显式写出的洞察，LLM 只做提炼、命名和结构化 |
| `inferred` | LLM 基于 observation 节点和关系推导出的新洞察，是 wiki 自进化的主要来源 |
| `mixed` | 显式洞察与推断洞察混在一起，暂时无法合理拆开 |

规则：

- `explicit` 要尽量忠实原意，不要把素材里的弱判断升级成更强结论。
- `inferred` 要能回到 observation / source / relation 链，正文里写清推理依据。
- `mixed` 只在确实拆不开时使用；能拆就拆成两个节点更好。

### status 判断

状态由你自动判断，不要求用户每次手工改。

| 状态 | 判断标准 |
|---|---|
| `seed` | 只有初步想法、问题或占位，暂时缺少材料支撑 |
| `growing` | 有价值但仍缺至少一项：自足性、稳定性、机制完整性、证据充分性 |
| `mature` | 同时满足：脱离 raw 可读懂；机制/判断链清楚；有足够来源或实践支撑；短期不太可能被轻易推翻 |
| `needs-split` | 节点承载多个子主题，且继续追加会降低可读性 |
| `archived` | 已拆分、合并、废弃或仅保留为演化痕迹 |

首次摄入默认保守：除非素材证据充分、机制清楚、节点自足，否则用 `growing`。lint 时可以自动建议升降状态，并说明原因。

### 正文写作

- 正文应服务于节点类型，不要求固定字数或固定段数。
- insight/decision/comparison 要写出推理链、约束、代价或边界；`insight` 还要标明是 `explicit` 还是 `inferred`。
- observation 可以更短，但要准确、可追溯，避免混入过度解释。
- question 要说明为什么这个问题重要、当前卡点是什么、可能关联哪些节点。
- 列表可以用于结构化信息，但不要让正文只是无解释的要点堆叠。

字数信号：

- 太短可能说明节点太薄，考虑合并、标 `seed`，或只更新 index/log。
- 太长可能说明节点过载，考虑拆分或保留为综合节点。
- 不要为了满足字数而填充泛泛解释。

## Step 5 — 建立关系

关系是 wiki 复利的关键。每个新建或实质更新的节点，都要尝试连接到已有节点，但不要为了“不能孤立”而制造弱关系。

### 关系方向

| type | 方向规则 |
|---|---|
| `implements` | 我是 X 的具体实现：`我 -> X` |
| `contradicts` | 我反驳或修正 X：`我 -> X` |
| `contrasts` | 我与 X 构成对照：写一条即可，反向由构建层生成 |
| `extends` | 我建立在 X 之上并深化它：`我 -> X` |
| `instance-of` | 我是 X 的实例：`我 -> X` |
| `prerequisite` | 理解我之前先理解 X：`我 -> X` |
| `evolves-from` | 我从 X 演化而来：`我 -> X` |
| `related` | 弱关联：只在没有更精确关系时使用 |

不要为同一语义手写双向边。`contrasts` 和 `related` 通常只保留一条显式边；系统会生成 back edge。

### 关系发现

- 新建节点前，用候选 id、中文标题关键词、同义词 grep `<wiki>/nodes/`，确认没有旧节点已经承载同一理解。
- 同主题：找 prerequisite、extends、implements、contradicts。
- 跨主题：找结构相似、问题相似、权衡相似的连接。
- 支撑事实：如果理解 A 之前需要先理解事实/概念 X，写 `A ->prerequisite-> X`。
- 开放问题：检查新节点是否部分回答了 question。
- 事实升级：检查新素材是否让旧 observation 具备机制解释。
- 冲突修正：如果新信息推翻旧判断，要显式写 `contradicts` 或更新旧节点。

写完 relations 后做一次关系审计：

- 每条关系都按方向表重读一遍，尤其检查 `extends`、`implements`、`prerequisite`、`instance-of`、`evolves-from`。
- 同一对节点不要写两条同义反向边；`contrasts` / `related` 通常只留一条显式边。
- log 和汇报中必须使用真实完整 node id，不要写简称或别名。

## Step 6 — 自检

写完节点后检查：

- 是否有 raw source 或口述来源说明？
- 是否与已有节点重复？重复则合并更新，而非新建。
- `insight` 是否标注了 `insight_origin`，且与素材来源一致？
- insight / decision / comparison 依赖的关键事实是否已有 observation 节点承载，或在本次新建/更新？
- meta_type 是否诚实？
- status 是否保守且有理由？
- 关系方向是否符合表格？
- 是否手写了不必要的双向边？
- 是否为高显著但未建节点的主题说明了 absorbed / raw / deferred 去向？
- 是否只改了本次任务相关文件？
- 是否超过了变更预算，需要先向用户确认？
- index 是否覆盖全部新增/更新节点？
- log 中的节点 id 是否都是真实完整 id？

任何不通过的项，先修正再汇报。

## Step 7 — 更新索引

在 `<wiki>/meta/index.md` 中添加/更新条目：

```markdown
- [[node-id]] — 一句话说明它承载的理解
```

索引应覆盖所有非 archived 节点。可以按 domain、meta_type、主题簇或本 wiki 既有结构分组，优先保持现有风格。

## Step 8 — 记录日志

在 `<wiki>/meta/log.md` 末尾追加：

```markdown
## [YYYY-MM-DD] ingest | <素材或批次摘要>
- 来源: raw/...
- 统计: 素材 N 份 / 约 X 字；新建 M；更新 K；跳过 J
- 新建: node-a, node-b
- 更新: node-c
- 跳过: <主题>（absorbed into node-x / left in raw / deferred candidate；原因）
- 关系: node-a ->extends-> node-x
- 洞察来源: node-a=explicit, node-b=inferred（仅 insight 节点）
- 状态: node-a=growing（原因简述）
```

log 只追加，不删除历史。log 中的 node id 必须与 frontmatter 完全一致，不写简称。

## Step 9 — 向用户汇报

汇报应简洁但可审阅：

- 处理了哪些素材。
- 新建/更新/跳过了什么。
- 每个新节点的 id、title、meta_type、status。
- 如果有 insight，说明它们是 `explicit`、`inferred` 还是 `mixed`。
- status 的关键理由，尤其是 `mature` 和不确定的 `growing`。
- 关键关系，特别是跨主题关系和冲突关系。
- 是否建议后续 lint 或 refactor。
- 建议人工抽检的节点，最多 3 个，并说明原因。

## 领域标签

domains 表示”这个理解在哪些领域有用或可迁移”，不是单纯表示素材来自哪里。优先复用已有标签；确有需要时新增标签或子层级。

标签支持**多层级**，用 `/` 分隔。层级数不限，但建议保持 2-4 层。格式：`#大类/细分/更细分`。

### 标签使用规则

- 优先复用已有标签路径。
- 新增子层级时，确认父层级已存在（如要加 `#技术/前端/React`，`#技术/前端` 须已存在）。
- 如果已有节点的标签过粗，可以在新节点中使用更细的子标签，但不要批量修改旧节点标签。
- 一个节点可以有多个标签，表示跨域理解。
- 标签是长期基础设施，命名必须面向"这个层级将来还会装什么"来设计，而不是"当前这几个节点叫什么"
- 需要新增顶层标签或重构层级关系时，先告知用户。

## 红线

- 不修改 `<wiki>/raw/` 下已有文件。
- 不删除节点文件，只能 archive 或 refactor。
- 不删除 log 历史条目。
- 不大面积重写成熟节点，除非用户明确要求或新证据直接冲突。
- 不在一次 ingest 中顺手重排多个主题簇；需要时改走 refactor 或先征求确认。
- 不用固定字数、固定节点数代替判断。
- 不按文件机械产节点。
- 不手写重复双向边。
- 不把无法回源的断言标成 `mature`。
