# 知识图谱与链接契约

> 本文件是业务仓 `knowledge/` **内部链接、关系字段、回链与孤儿检测**的唯一细则参考。OKF 保留名与 `type` 枚举见 [kb-okf.md](kb-okf.md)；内容十一段结构见 `knowledge/AGENTS.md`。

## 1. 链接分层

| 场景 | 写法 | 示例 |
|------|------|------|
| 知识库内部互指 | **仅** `[[wikilink]]` | `[[业务域/礼物/02-送礼]]`、`[[01-概览]]`、`[[知识地图\|知识地图]]` |
| 外部 URL | **仅** Markdown 链接 | `[OKF 规范](https://example.com/okf)` |

1. **禁止**在 `knowledge/` 内用 `[标题](相对路径.md)` 互链（历史存量须迁移）。
2. wikilink 目标**不写** `.md` 后缀；同目录可用短名 `[[02-子模块]]`，跨目录用相对路径 `[[业务域/礼物/02-送礼]]`。
3. 显示名：`[[path/note|显示名]]`；目标与显示名相同时可省略管道。
4. frontmatter 的 `related` / `depends_on` 存**无括号**的 wikilink 目标字符串，与正文 `[[…]]` 内路径一致。

## 2. 与官方 OKF 的差异（有意扩展）

官方 OKF v0.1 推荐「标准 Markdown 链接」。本仓**有意**改为内部仅 wikilink，原因：

1. 已在用的 **Obsidian 关系图谱**与双向浏览体验；
2. **Agent 检索**：出链/入链可机器聚合，配合 `related` / `depends_on` 与 `## 相关` 段做一致性校验。

OKF 在本仓是**参考布局**（`index.md` / `log.md`、frontmatter `type` 等仍沿用），**非强制标准**；链接层以本文件为准。

## 3. 概念文件 frontmatter 关系字段

适用于 `knowledge/` 下**非保留名**概念文件（含 `AGENTS.md`、`知识地图.md`、业务域/工程平台概览与子模块；**不含**各目录 `index.md`、`log.md`；变更目录 `01`～`07` 暂不强制）。

| 字段 | 类型 | 必填 | 语义 |
|------|------|------|------|
| `related` | `string[]` | **是**（可为 `[]`） | 语义关联；wikilink 目标，无括号 |
| `depends_on` | `string[]` | **是**（可为 `[]`） | 硬依赖；被依赖方删除前须先处理依赖方 |
| `status` | `current` \| `superseded` | 否 | 时效状态；**缺省 = `current`** |
| `supersedes` | `string[]` | 否 | 本文件取代的概念 wikilink 目标 |
| `keywords` | `string[]` | 否 | 检索注记（写时可选） |

1. `related` / `depends_on` **必须存在**；缺字段视为违规（空数组合法）。
2. 机器校验 schema：`schema/kb-concept-frontmatter.schema.json`（bootstrap 后位于业务仓 `.kb/` 或由脚本引用插件包路径）。
3. `depends_on` 条目应同时在正文或概览依赖图中体现；纯语义邻接放 `related`。
4. `status` / `supersedes` / `keywords` 为可选扩展；出现时须符合上表类型。

## 3.1 时效与取代（Graphiti-lite）

1. **当前生效**：日常检索与归档合并默认只消费 `status` 缺省或 `current` 的概念正文。
2. **被取代**：明确拆分/合并导致旧模块不再代表现状时：
   - 新文件（或保留文件）写 `supersedes: [<旧 wikilink>, …]`；
   - 旧文件标 `status: superseded`（或删除旧文件并修断链）；
   - 结构性说明追加同目录 `log.md`，**禁止**在正文堆「变更记录」段。
3. **就地更新**：多数归档仍直接改写「当前生效」正文，不必新建 superseded 文件；仅当旧结论需保留为可追溯独立笔记时才用 `superseded`。
4. **检索**：`/kb-query` 默认降权或跳过 `superseded`；需考古时显式声明「含已取代」。
5. **校验**：`supersedes` 目标须可解析；非法 `status` 阻断；`superseded` 节点在 `/kb-health` 作残留警告（见 [kb-knowledge-evolve.md](kb-knowledge-evolve.md)）。

## 4. 正文 `## 相关` 段（强制）

| 文件类型 | 位置 |
|----------|------|
| 编号子模块（十段式） | 「九、已知限制与 TODO」之后 **「十、相关」** |
| `01-概览.md` | 「十、文档入口」之后 **「十一、相关」** |
| 顶级概念（`知识地图.md`、`AGENTS.md` 等） | 文末独立 **`## 相关`**（固定标题，不用中文序号） |

段内用 `[[wikilink]]` 列表，须满足：

**正文链接集合 ⊇ `related` ∪ `depends_on`**

允许在段内增加仅正文出现的补充链接（并同步回写 frontmatter 或保持为超集说明）；不得少于 frontmatter 已声明的并集。

## 5. 回链与孤儿

1. **可发现性**：文件 A 出链到概念 B 时，B 须能通过以下**至少一种**途径被人工或 Agent 发现：
   - 某级 `index.md` 列表；
   - 某概览「子模块清单 / 文档入口」；
   - 其他概念的 `## 相关` 或 frontmatter `related` / `depends_on` 反向提及。
2. **不强求**两两互链；**禁止长期孤儿**：除根 `knowledge/index.md` 与各领域/分区 `index.md` 入口自身外，任何概念文件不得长期无任何入边（不被 index、wikilink、`related` 引用）。
3. 新建概念时：同步更新所属 `index.md` 或父概览链接，并在相关方的 `related` / `## 相关` 中补反向引用（若存在语义关联）。

## 6. `index.md` 列表格式

保留名 `index.md` **无** frontmatter（根目录除外可有 `okf_version`）。列表项使用 wikilink：

```markdown
* [[知识地图]] - 项目定位与文档入口
* [[业务域/礼物/index|礼物]] - 礼物业务域入口
* [[工程平台/index|工程平台]] - 跨业务域工程能力入口
* [[01-概览]] - 本目录概览（同目录相对解析）
```

分节标题可保留 `## A 产品地图` 等；描述后缀 `- description` 不变。

## 7. 校验与迁移

| 动作 | 说明 |
|------|------|
| `kb-okf-check.mjs` / `/kb-check` | 图谱节：frontmatter 关系字段、`## 相关` 与 wikilink 一致性、断链、内部 Markdown 内链阻断、孤儿警告、index 覆盖警告、`status`/`supersedes` 校验 |
| `kb-okf-migrate.mjs` / `/kb-okf-migrate` | 存量 `[text](path.md)` → `[[wikilink]]`；补空 `related`/`depends_on` 与「相关」段；入口重命名 |
| `/kb-health` | 孤儿节点、断链、关系集不一致、superseded 残留、效用分低分/零命中（Agent 巡检 + 脚本复述） |
| `kb-knowledge-utility.mjs` | 贡献分 bump/penalize/rank；细则 [kb-knowledge-evolve.md](kb-knowledge-evolve.md) |

```bash
node "${PI_KB_ROOT}/scripts/kb-okf-migrate.mjs" --target "$(pwd)" --dry-run
node "${PI_KB_ROOT}/scripts/kb-okf-migrate.mjs" --target "$(pwd)" --apply
node "${PI_KB_ROOT}/scripts/kb-okf-check.mjs" --target "$(pwd)"
```