# 上下文构建协议

本协议用于在 `grounded_workflows` 知识驱动工作流中，**从本地 `.deepwiki/` 知识库构建与当前任务强相关的上下文**。目标是：在不过载模型上下文的前提下，让智能体获得可引用、可追溯、结构化的领域知识，为后续推理、设计与实现提供依据。

**适用范围**：仓库或工作区已存在由 DeepWiki 或同类工具生成的 `.deepwiki/` 目录（含 `README.md`、`_outline.md` 与 `pages/*.md`）。

**不适用**：当 `.deepwiki/` 不存在或严重过时，应先更新知识库或改用其他知识来源，并在本协议第五步中显式标记缺口。

---

## 五步构建流程

智能体必须按顺序执行下列步骤；不得跳过「大纲匹配」直接通读全部页面。

### 步骤 1：读取 `.deepwiki/README.md` 获取知识库概览

- 打开并完整阅读 `.deepwiki/README.md`。
- 提取：知识库定位、维护约定、术语表入口（若有）、已知限制、与代码仓库的对应关系说明。
- **产出**：用 2～4 条要点概括「这份知识库是什么、覆盖什么边界」，写入后续上下文的元认知摘要（可放在首个 `[DW]` 块之前的一句说明中）。

### 步骤 2：读取 `.deepwiki/_outline.md` 了解知识分布

- 打开并阅读 `.deepwiki/_outline.md`。
- 识别：每个 `pages/*.md` 条目的标题、路径、摘要/关键词行（以大纲实际格式为准）。
- **禁止**：在此步骤加载 `pages/` 下任意正文文件（除非大纲本身通过引用要求先读某页——仍以大纲为索引，不替代步骤 3 的选择逻辑）。

### 步骤 3：根据当前任务关键词匹配大纲，并选择性加载 `pages/*.md`

1. 从用户任务、验收标准、涉及模块名、接口名、错误信息中抽取**关键词与同义词**（例如：任务「为 API 添加缓存层」→ `API`、`HTTP`、`路由`、`中间件`、`缓存`、`Redis`、`失效策略`、`一致性` 等）。
2. 在 `_outline.md` 中逐条比对：摘要与标题是否与关键词**语义相关**（允许同义词与上下位概念，避免仅字面匹配）。
3. 为每个相关条目记录对应文件路径（如 `pages/03-architecture.md`），形成**候选列表**。
4. **只读取候选列表中的页面**；未入选的 `pages/*.md` 一律不读。
5. 若候选超过「上下文规模指导」中的上限，按该节规则做**优先级裁剪**，再读取。
6. 若大纲中无任何匹配项：在步骤 5 中标记「大纲无命中」，并考虑扩大关键词或请求人工补充知识库；仍不得无差别加载全部页面。

### 步骤 4：将知识组织为结构化上下文块

对**每一个已加载的** `pages/*.md` 文件，输出一个独立块，格式严格如下（标题层级、前缀 `[DW]`、来源路径须一致，便于检索与审计）：

```
### [DW] 来源：pages/03-architecture.md
- 关键点 1
- 关键点 2
```

**编写要求**：

- **关键点**应来自该页正文，是对当前任务有直接支撑作用的命题（设计决策、约束、流程、术语定义、已知坑等），避免整段复制粘贴；每条宜为一句可检验的陈述。
- 若一页内容较多，只抽取与任务相关的子集；可在同一块内用次级短列表分组（仍保持块级标题不变）。
- 默认**不**在块内混入仓库源码内容；源码引用遵循「与 Grounding 协议的集成」一节。
- 多个页面则重复上述结构，按**与任务相关度从高到低**排列。

### 步骤 5：充分性检查

针对当前任务，逐条自问并给出明确结论（可在回复中用简短小节或列表写出）：

1. **覆盖度**：已加载页面是否解释清楚任务涉及的架构位置、数据流、扩展点、配置与运维约束？
2. **决策依据**：是否足以在「不臆测」的前提下做出主要设计选择（例如缓存放置层级、键设计、失效策略）？
3. **风险与边界**：是否标出知识库中已记载的边界条件、性能与安全注意点？

**结论处理**：

- 若**充分**：声明「当前 `[DW]` 上下文充分」，可进入下游工作流（如 grounding 或实现）。
- 若**不足**：列出**需补充的领域**（例如「缺少 API 网关与鉴权章节」「缺少现有中间件列表」），并说明是知识库缺口还是裁剪过严；必要时建议回到步骤 3 增加 1～2 个页面重读（仍遵守页数上限与优先级规则），或触发知识库更新/人工输入。

---

## 上下文规模指导

**建议**：单次任务从 `.deepwiki/pages/` 中**最多加载 2～5 个页面**；常规复杂度任务优先控制在 **3 页以内**。

**为何过载有害**：

- **注意力稀释**：上下文过长时，模型对远端信息的遵循度下降，易忽略约束或与任务无关的段落被误当作重点。
- **成本与延迟**：更多 token 增加费用与响应时间，且不一定提高正确率。
- **虚假确定感**：堆砌无关页面可能让模型「看起来有依据」地编造跨页不存在的联系，违背 grounded 原则。

**如何优先裁剪**（当候选多于 5 页时，按序保留）：

1. 与任务**核心动词/对象**直接相关的页（如「架构」「API 设计」优先于泛泛的「概述」）。
2. 描述**当前修改点所在模块**的页优于周边背景页。
3. **操作类**（部署、配置、迁移）仅在任务显式涉及运维时纳入。
4. 剔除与任务**仅名称相似但语义无关**的页。

若裁剪后仍无法覆盖任务，应在步骤 5 标记不足，而不是无上限加页。

---

## 与 Grounding 协议的集成

- 经本协议从 `.deepwiki/` 加载并整理进上下文的陈述，默认视为 **`[DW]` 来源**（DeepWiki 知识库），在步骤 4 的块标题中已标明路径。
- **默认规则**：实现细节、接口签名、配置项默认值等，若知识库与源码可能不一致，**以经 Grounding 核验的源码/配置为准**；`[DW]` 用于理解领域与历史决策，不自动等同于「当前仓库真相」。
- 当智能体需要**从源代码、配置文件或运行时行为**补充或验证信息时，必须遵循 **`protocols/grounding.md`** 中的引用格式、读取范围与「可验证」要求，将此类内容标为 Grounding 产出（与 `[DW]` 区分），避免与 DeepWiki 块混为一谈。
- 推荐工作流：先按本协议构建 `[DW]` 上下文 → 对关键断言用 Grounding 在仓库中**定点验证** → 再输出最终方案或补丁。

---

## DeepWiki 目录结构参考

典型 `.deepwiki/` 布局如下（实际文件名序号与数量可能不同，以仓库为准）：

```
.deepwiki/
├── README.md          # 知识库概览
├── _outline.md        # 知识大纲（页面列表 + 摘要）
└── pages/
    ├── 01-overview.md
    ├── 02-getting-started.md
    ├── 03-architecture.md
    └── ...
```

- **`README.md`**：面向读者的总览与使用说明。
- **`_outline.md`**：机器与智能体共用的**索引**；上下文构建的**路由表**。
- **`pages/*.md`**：主题化正文；**按需加载**，非全量加载。

---

## 示例

**假设任务**：为 API 添加缓存层。

**步骤 1～2（摘要）**：读完 `README.md` 与 `_outline.md` 后可知：知识库描述某后端服务的模块划分与请求路径；大纲中 `03-architecture.md` 讲分层与中间件扩展点，`05-api-design.md` 讲 REST 约定与版本策略，`08-operations.md` 讲 Redis 与限流（部分段落与缓存运维相关）。

**步骤 3（匹配与选页）**：关键词命中 `架构`、`API`、`Redis`；裁剪后加载：`pages/03-architecture.md`、`pages/05-api-design.md`、`pages/08-operations.md`（共 3 页，符合 2～5 页指导）。

**步骤 4（结构化输出示例）**：

```
### [DW] 来源：pages/03-architecture.md
- HTTP 入口经统一路由层分发至业务 Handler，中间件链在路由之前按固定顺序执行。
- 对外缓存建议放在「路由之后、业务之前」的独立中间件，便于按路径粒度配置 TTL 与跳过规则。
- 写路径默认需经过领域服务层，避免 Handler 直接写缓存导致与领域事件不一致。

### [DW] 来源：pages/05-api-design.md
- 公开 API 版本前缀为 `/v1`，破坏性变更须递增主版本；缓存键设计应包含版本号与路径模板。
- 对 `GET` 幂等读接口允许短期缓存；`POST/PUT/PATCH` 默认不可缓存，文档中列有例外白名单路径。

### [DW] 来源：pages/08-operations.md
- 生产环境 Redis 集群由运维托管，应用侧仅使用已注入的连接串与 DB 索引规范；禁止在业务代码硬编码实例地址。
- 部署流水线在发布后会触发短期缓存预热任务；新增缓存层须评估与预热脚本的键集合是否对齐。
```

**步骤 5（充分性检查）**：

- **覆盖度**：已明确中间件挂载位置、API 版本与缓存键约束、生产 Redis 使用边界，足以支撑「在何处加缓存、如何命名键、哪些方法可缓存」的初版设计。
- **不足（示例）**：知识库未描述「用户私有数据的缓存隔离」细则 → **需补充领域**：安全与多租户数据隔离章节；若 `_outline` 中存在 `09-security.md` 但未读，应在不超出页数上限前提下优先补读该页，或转 Grounding 在代码中检索鉴权与租户中间件实现。

此后若需确认具体 Handler 或现有中间件注册顺序，应按 `protocols/grounding.md` 对相应源码做定点读取与标注。