# 文档导航 这个目录里有两类文档，混在一起容易迷路： | 类别 | 目录 | 读者 | 什么时候看 | | --- | --- | --- | --- | | **使用类** | [库结构.md](库结构.md)、[metrics.md](metrics.md) | 库的作者、插件的使用者 | 想知道「我的笔记该怎么写」「插件到底怎么打分」 | | **设计类** | [契约-stage0/](契约-stage0/) | 改插件的人、审方案的人 | 想知道「知识网关为什么长这样」「某个字段为什么这么定」 | **只想用插件** → 读仓库根目录的 [README.md](../README.md) 就够了，这页是给要动手改的人看的。 --- ## 使用类 ### [库结构.md](库结构.md) · 163 行 **一份目录 + 一堆 `.md` 就能用**，其余全是加分项。文档按四层写：第 0 层最小可用 → 第 1 层 frontmatter 七字段 → 第 2 层 `index.md` 摘要目录 → 第 3 层 `总览-overview.md`。 想知道「`别名` 到底有什么用」「`来源数量` 为什么是证据强度的唯一代理」，看这份。 ### [metrics.md](metrics.md) · 107 行 检索**一致性**指标的定义：Recall@5（micro）、Top-1 一致率、Top-5 集合一致率（Jaccard）。 文档开头有一句话值得抄下来贴在墙上：*「这些指标不回答『检索得准不准』。名字选错，后面所有人都会拿它当正确答案。」* ### [superpowers/specs/](superpowers/specs/) `2026-11-04-wiki-search-panel-design.md` —— 检索面板的设计稿（113 行）。改面板样式前先看它。 --- ## 设计类：契约-stage0 这一组是**知识网关**（`wiki_context` / `wiki_verify` / `wiki_observe` 三个工具）的设计与验收记录，按阶段推进，每份都以「已实现 + 已验收」的状态定稿。 | 阶段 | 文档 | 行数 | 回答什么问题 | | --- | --- | --- | --- | | 0 | [阶段0-审计与契约.md](契约-stage0/阶段0-审计与契约.md) | 204 | 现有能力怎么映射成契约？实测发现哪 6 个缺口（F1–F6）？错误码与超时预算怎么定？ | | 1 | [阶段1-数值判据与引擎状态.md](契约-stage0/阶段1-数值判据与引擎状态.md) | 107 | 「答案里的数字和库里对不上」怎么判定？引擎坏了怎么在输出里看得见？ | | 2 | [阶段2-快照与TTL.md](契约-stage0/阶段2-快照与TTL.md) | 84 | `wiki_verify` 不重新检索，怎么拿到当初那份证据？快照存什么、多久过期？ | | 3 | [阶段3-支持原因.md](契约-stage0/阶段3-支持原因.md) | 98 | `support_status` 为什么是这个值？11 个原因码分别什么意思？ | | 4 | [阶段4-插件接入.md](契约-stage0/阶段4-插件接入.md) | 143 | 插件怎么调 Python 桥？进程协议、文件清单、配置、降级矩阵、踩过的坑 | | 5 | [阶段5-观察闭环与实战验收.md](契约-stage0/阶段5-观察闭环与实战验收.md) | 109 | 五类问题（直接事实/证据不足/范围混淆/证据冲突/错误答案）实战验收结果，三层能力对照 | | — | [观察期方案.md](契约-stage0/观察期方案.md) | 81 | 真实使用中怎么观察「模型会不会用、用得对不对」？五个观察点怎么测？ | ### 配套产物 - **[knowledge-gateway.v1.schema.json](契约-stage0/knowledge-gateway.v1.schema.json)** —— 契约的机器可读定义（28 KB），`context` / `verify` / `observe_stats` 三种输出的完整字段。 - **[samples/](契约-stage0/samples/)** —— 8 份真实样例：`context.cq-shenlun.json`（一份完整的 context）、6 份 verify 场景（答对但有缺口 / 编引文 / 范围错 / 数字错 / 快照过期 / 快照损坏）、`_verify_probe.json`。 改判据前，先拿样例跑一遍 `wiki_verify` 看行为有没有变。 --- ## 阅读顺序建议 | 你的目的 | 顺序 | | --- | --- | | 第一次用这个插件 | README → [库结构.md](库结构.md) | | 想知道插件为什么这么打分 | README「检索质量」节 → [metrics.md](metrics.md) → 阶段 1 | | 要加一个新工具 | 阶段 0 → 阶段 4 → `knowledge-gateway.v1.schema.json` | | 要改判定逻辑（会拦答案的那种） | 阶段 1（数值判据）→ 阶段 3（支持原因）→ `samples/` | | 要看这套东西到底行不行 | 阶段 5 → [观察期方案.md](契约-stage0/观察期方案.md) | --- ## 一条规矩 **这些文档记的是「当时的结论」，不是「永久有效的规则」。** 每份文档末尾都有「已知局限」一节 —— 那是设计者自己写下的边界，比正文更值得读。真要改设计，先看局限那一节，多数坑已经写在纸上了。