# 知识图谱写时演化与贡献分（Pi）

> 本文件是业务仓 `knowledge/` **写时链接演化（A-MEM-lite）**、**时效取代（Graphiti-lite）**与**贡献分软降权（EvoRAG-lite）**的唯一细则。链接契约见 [kb-graph.md](kb-graph.md)；OKF 字段见 [kb-okf.md](kb-okf.md)。

## 1. 目标闭环

```
archive/sync 写知识 → 构笔记 + 建链 + 邻接回写 + 可选 supersede
        ↓
knowledge/（Markdown 图谱）
        ↓
/kb-query（index 导航 + utility rank；降权 superseded）
        ↓
成功回答 / apply 落地 → bump 贡献分
知识误导 / 与代码冲突 → penalize
```

不引入向量库；效用分落业务仓 `.kb/knowledge-utility.json`（默认**提交进 git**，团队共享）。

## 2. 写时三步（archive 步骤 6 / sync / kb-librarian 必遵）

凡新建或改写概念文件（`knowledge/知识地图.md`、业务域/工程平台非 `index.md`/`log.md`）：

### 2.1 Note construction

- 补齐 YAML：`type`、`related`、`depends_on`（可为 `[]`）。
- 可选：`keywords`（3～8 个短词，便于检索与 health）。
- 可选时效：`status`、`supersedes`（见 [kb-graph.md](kb-graph.md) §3.1）。
- 正文「相关」段 ⊇ `related` ∪ `depends_on`。

### 2.2 Link generation

- 与清单内外语义相关的概念写入 `related`；硬依赖写入 `depends_on`。
- 内部互链仅 `[[wikilink]]`。
- 同步所属 `index.md` wikilink 列表（新增/删除/重命名时）。

### 2.3 Memory evolution

- **同轮**回写邻接概念的 `related`（至少补反向入边，避免孤儿）。
- 结构性变更追加同目录 `log.md`，禁止正文「变更记录」段。
- **Supersede**：明确取代旧模块时：
  1. 新/保留文件写 `supersedes: [<旧目标>, …]`；
  2. 旧文件标 `status: superseded`，或删除并修断链；
  3. 默认仍就地更新「当前生效」正文；仅当旧结论需独立可追溯笔记时才拆 superseded 文件。

## 3. 贡献分文件

路径：业务仓 `.kb/knowledge-utility.json`

```json
{
  "version": 1,
  "updated_at": "2026-07-27T01:00:00.000Z",
  "nodes": {
    "knowledge/业务域/礼物/02-送礼.md": {
      "score": 2.5,
      "hits": 3,
      "last_used": "2026-07-27T01:00:00.000Z"
    }
  }
}
```

| 字段 | 说明 |
|------|------|
| `version` | 固定 `1` |
| `nodes` key | 相对仓库根的知识文件路径（含 `knowledge/` 前缀） |
| `score` | 软夹紧 **\[0, 10\]**；无记录视为中性 `0` |
| `hits` | 成功使用次数累加 |
| `last_used` | ISO-8601 |

**禁止**因低分硬删知识文件；仅检索软降权。

## 4. 脚本

```bash
# 成功检索/落地后抬分
node "${PI_KB_ROOT}/scripts/kb-knowledge-utility.mjs" bump \
  --target "$(pwd)" --paths "knowledge/业务域/礼物/02-送礼.md" --delta 1

# 知识误导或与代码冲突时降分
node "${PI_KB_ROOT}/scripts/kb-knowledge-utility.mjs" penalize \
  --target "$(pwd)" --paths "knowledge/业务域/礼物/02-送礼.md" --delta 0.5

# 候选路径按 score 降序（JSON）
node "${PI_KB_ROOT}/scripts/kb-knowledge-utility.mjs" rank \
  --target "$(pwd)" --query-files "a.md,b.md" --json

# 摘要（health）
node "${PI_KB_ROOT}/scripts/kb-knowledge-utility.mjs" summary \
  --target "$(pwd)" --json
```

- 写盘：由 **kb-librarian** / **kb-inspector**（或写入型子 Agent）经 shell 调用；**主 Agent 不直接写**该文件。
- `bump`：`/kb-query` 回答采用的知识路径；`/kb-archive` 或 apply 成功且实际使用的 `manifest.files` 中 `kind=knowledge` 路径。
- `penalize`：知识与 CodeGraph 冲突且确认知识过时/误导时（同轮宜触发 `/kb-sync`）。

## 5. 检索融合（/kb-query）

1. 仍按两级 `index.md` → 叶子导航（不得跳过 index 全盘遍历）。
2. 得到候选概念路径后，跑 `rank --query-files … --json`，**高分优先**深入阅读。
3. frontmatter `status: superseded`：**默认跳过或最后阅读**；用户明示「含已取代」时例外。
4. 回答采用后，对实际引用路径 `bump`（delta 默认 `1`）。

## 6. 健康巡检（/kb-health）

在既有 OKF/孤儿检查之外，报告：

- `status: superseded` 残留清单（是否仍被 index 主推）；
- `summary`：低分（score &lt; 1 且 hits ≥ 1）、零命中（存在文件但无 utility 记录且长期未触达——仅提示）、高分样例。

只读；不自动改分。