# 知识优先级协议 (Knowledge Grounding Protocol)

本协议定义 **grounded_workflows** 体系中一切推理、规划、实现建议与最终输出的 **知识来源优先级与可追溯标注规范**。任何技能（Skill）、工作流步骤、评审结论或交付物，凡涉及事实判断、架构决策、性能数字、接口契约、运行行为与最佳实践推荐，均必须按本协议选择证据链并标注来源层级；不得以“常识”“经验直觉”替代可核验依据。所有下游协议与技能文档在引用知识时，应以本文件为 **唯一根规范**，并在冲突时以本协议的优先级与门控规则为准。

## 优先级层次

知识来源分为三个互斥层级，数字越小优先级越高。满足高层级证据时，**禁止**用低层级证据“覆盖”或弱化高层级结论；低层级仅用于 **补充、解释边界条件、或在高层级缺失时的受限推断**。

### Level 1：`[DW]`（Deep Wiki / 项目知识库）

- **定义**：仓库内 `.deepwiki/` 目录及其约定子路径中的权威文档（如架构说明、运行手册、数据模型、接口约定、运维策略等），经项目维护者审阅、版本化管理的 **项目内知识基线**。
- **处理原则**：视为 **默认可信（trusted baseline）**；可直接引用其中的事实陈述与约束；在存在 `[DW]` 证据链时，不得用 `[EXT]` 与之矛盾。
- **典型用途**：回答“系统如何设计”“官方推荐怎么做”“已知限制是什么”等问题时的 **首选依据**。

### Level 2：`[SRC]`（项目源码）

- **定义**：本仓库及关联 monorepo 中 **可编译、可执行、可静态阅读** 的源代码与配置（如 `src/`、`lib/`、`pkg/`、`configs/`、`Dockerfile`、`terraform/` 等），以当前分支/提交为准。
- **处理原则**：当 `[DW]` **未覆盖、过时、或与运行态不一致** 时，以源码为 **事实仲裁**；用于补齐实现细节、参数默认值、边界分支与真实调用链。
- **典型用途**：核对函数签名、中间件顺序、错误码、缓存键命名、实际超时配置等 **实现层真相**。

### Level 3：`[EXT]`（扩展知识 / 外部推理）

- **定义**：模型训练期知识、公开网页、第三方库通用文档、行业惯例、启发式建议，以及 **在 `[DW]` 与 `[SRC]` 均无法支撑** 时进行的合理外推。
- **处理原则**：**最低优先级**；仅当 Level 1 与 Level 2 经门控确认 **仍不足** 时启用；启用后必须在输出中 **显式说明缺口** 与 **不确定性**，并遵守本文件「扩展门控」与「输出校验」。

**层级速记**：`[DW]` 管“官方叙事与约束”，`[SRC]` 管“代码真值”，`[EXT]` 管“在证据缺口下的受限补全”。

## 标注规则

### 基本义务

1. **逐条标注**：每一条独立 **结论**、**可执行建议**、**数值断言**（含阈值、版本、性能指标）、**因果解释**（“因为…所以…”）都必须带 **来源层级标签**。
2. **默认不混用隐式来源**：若同一段话合并了多个层级，应拆分为多条 bullet，或合并为 **混合标签**（见下）。
3. **可追溯**：凡标注为 `[DW]` 或 `[SRC]` 的条目，必须在同一条目末尾给出 **可定位引用**（见「引用格式」）。`[EXT]` 条目必须给出 **为何 L1/L2 不足** 的一句话说明（可与扩展门控段落呼应）。

### 单一来源标签

- `[DW]`：证据完全来自 `.deepwiki/`。
- `[SRC]`：证据完全来自项目源码/配置，且 `.deepwiki/` 未提供等价陈述。
- `[EXT]`：证据来自外部知识或推理补全，且已通过扩展门控。

### 混合来源标签（主 + 次）

当一条结论 **同时** 依赖两类证据时，使用 **`[主+次]`** 形式，**左侧为主要依据**（决定结论可信度上限），右侧为补强：

- `[DW+SRC]`：结论主干来自 `[DW]`，关键细节由 `[SRC]` 校验或补齐（例如文档写“使用 Redis”，源码确认连接参数与 key 前缀）。
- `[SRC+DW]`：结论主干来自 `[SRC]`（实现已变更），`[DW]` 仅作背景或历史说明（应在文中提示文档可能过期）。
- `[DW+EXT]`：事实与约束来自 `[DW]`，模式/命名/库选型等 **文档未写清** 的部分由 `[EXT]` 补全。
- `[SRC+EXT]`：行为由源码证实，但 **策略层**（如容量规划、灰度节奏）在 L1/L2 缺失，由 `[EXT]` 给出 **明确标注为建议** 的内容。

**禁止**使用模糊标签（如“参考网络”而不写 `[EXT]`），也 **禁止** 用 `[EXT]` 单独支撑与 `[DW]` 直接冲突的“事实断言”。

### 引用格式（可点击 / 可检索）

对 `[DW]` 与 `[SRC]`，在同一条目末尾追加引用片段，统一采用：

`—— 来源: <相对仓库根路径>[:<行号或行范围>]`

- **单行**：`—— 来源: src/middleware/cache.py:120`
- **行范围**：`—— 来源: pages/05-performance.md:14-36`
- **多文件并列**：用 ` + ` 连接：`—— 来源: pages/03-architecture.md:8-22 + src/config/cache.ts:40-55`

若你的输出环境支持 Markdown 链接，可将路径包装为 **空链接或文件 URI**，但 **可见文本必须保留** `来源:` 前缀以便检索与审计，例如：

`[来源:pages/03-architecture.md:8-22](pages/03-architecture.md)`

> 约定：**路径始终相对仓库根目录**；Windows 环境仍使用 `/` 作为分隔符以保持与 CI 日志一致。

### 列表与段落中的最小合规写法

- 推荐 **一条 bullet = 一个可验证断言 + 一个标签 + 一个引用（如适用）**。
- 若必须输出长段落，在段首用标签声明该段最高证据层级，例如：`[DW+EXT] 本段：…`，且段内不得夹带无标签的新增事实。

## 扩展门控（Hard Gate）

`[EXT]` 不是“写起来方便”的标签，而是 **受控降级通道**。在输出任何 `[EXT]` 结论前，必须完成以下 **硬性门控**；任一条件不满足，则 **不得输出 `[EXT]`**，应改为：补充检索 `.deepwiki/`、阅读相关源码、或向人类请求缺失材料。

### 门控检查步骤（必须逐步执行并可在审计中复述）

1. **DW 覆盖性检查**：在 `.deepwiki/` 中针对当前问题主题，执行等价于“目录检索 + 关键词检索 + 交叉引用相关页”的查找；记录 **命中文件列表** 与 **是否直接回答问题**。
2. **SRC 可证性检查**：对涉及实现/配置/接口的问题，在源码树中定位 **调用链入口、配置读取点、默认值定义处**；记录 **是否读到与问题同粒度的证据**。
3. **缺口声明**：用 **一条独立 bullet** 写明：`[EXT]` 所填补的是哪类信息缺口（例如：“`.deepwiki/` 未描述缓存失效策略”“源码未包含压测数据”），并说明 **已检查的路径/关键词**（避免空泛）。
4. **反事实约束**：若步骤 1 已找到相关 `[DW]` 内容，则 **禁止** 用 `[EXT]` 推翻或忽略 `[DW]`；只能：
   - 在 `[DW]` 框架内做 `[DW+EXT]` 的 **非冲突补全**，或
   - 明确标注 `[DW]` 与 `[SRC]` **彼此矛盾** 时，以 `[SRC]` 为事实、以 `[DW]` 为待更新文档，并 **不得** 单独用 `[EXT]` 解决该矛盾。
5. **不确定性与可验证性**：`[EXT]` 内容必须标注 **置信度**（高/中/低）或 **需人类确认** 的触发条件；若存在 **可执行验证命令**（测试、构建、查询接口），应写出以便复核。

### 绝对禁止项

- **禁止绕过 `[DW]`**：当 `.deepwiki/` 存在与问题 **同主题** 的页面时，不得跳过阅读直接用 `[EXT]` 给架构级结论。
- **禁止伪造成本**：不得虚构 `来源:` 路径、行号或仓库中不存在的文件。
- **禁止 silent EXT**：不得将明显属于外部常识的建议藏在无标签文本中；无标签即视为 **协议违规**。

## 输出校验

在 **每一次** 面向人类或下游系统的完整回复末尾（或交付文档的固定页脚），追加 **来源统计** 行，对本次输出中 **带标签的断言条目** 计数：

`> **来源统计**: [DW]: X 条 | [SRC]: Y 条 | [EXT]: Z 条`

### 计数规则

- **只统计带层级标签的条目**（含混合标签 `[DW+EXT]` 等）：每条计 **1**。
- 同一标签在 **同一结论** 的标题与正文重复出现时 **去重**：以 **最小可独立验证单元** 计数。
- 若全文 **无任何** `[DW]`/`[SRC]`/`[EXT]` 标签（例如纯提问澄清），应输出：`> **来源统计**: [DW]: 0 条 | [SRC]: 0 条 | [EXT]: 0 条`，并说明 **未产生可标注结论**。

### 质量阈值（警告，不自动失败）

令 `T = X + Y + Z`。若 `T > 0` 且 `Z / T > 0.4`（即 **`[EXT]` 超过 40%**），必须在统计行下追加 **警告**，例如：

`> ⚠️ **警告**: [EXT] 占比 45%（>40%），请优先补充 .deepwiki/ 文档或源码证据后再做关键决策。`

当触发警告时，执行者应 **优先**：

1. 回到 `.deepwiki/` 增补或修正文档；或
2. 增加 `[SRC]` 级别的代码引用；或
3. 将 `[EXT]` 降级为 **明确待确认** 的行动项，而非既定方案。

## 示例

下列示例展示：**分层标签**、**混合来源**、**可定位引用**、**扩展门控说明** 与 **页脚统计** 的最小合规组合（内容为演示性质，路径与数字仅用于说明格式）。

```markdown
### 缓存策略设计

- [DW] 项目将会话状态存储在 Redis，并要求会话键带租户前缀 —— 来源: pages/03-architecture.md:18-27
- [DW+SRC] 线上中间件对 `/api/v1/session` 的 P99 延迟为 200ms；开启读缓存后同路径 P99 为 50ms（压测配置与采样窗口见性能页与中间件实现） —— 来源: pages/05-performance.md:41-48 + src/middleware/cache.py:10-88
- [EXT] 建议在热路径采用 Cache-Aside，并将会话与业务实体缓存分库键前缀隔离（已检索 `.deepwiki/` 未给出具体缓存模式选择；`src/middleware/cache.py` 仅体现读缓存开关，不含模式说明） —— 置信度: 中；需人类确认峰值写放大与失效策略

> **来源统计**: [DW]: 8 条 | [SRC]: 3 条 | [EXT]: 2 条
```

**解读要点**：

- 前两条将 **可验证事实** 锚定在 `[DW]` / `[DW+SRC]`，并给出 **精确引用**。
- `[EXT]` 条目同时包含 **缺口原因** 与 **不确定性**，满足扩展门控。
- 页脚统计用于快速审计：若 `[EXT]` 占比升高，应回到「输出校验」触发补救流程。