# 验收矩阵与后续演进

本文档包含脚手架分级裁剪决策表、运行时的验收测试矩阵以及下一阶段代码实现的具体切片规划。

---

## 1. 架构与脚手架裁剪决策表

按照 Agent 脚手架工程规范（Harness Engineering），针对当前仓库的定位与复杂度选择 **Lite 档位** 起点，并逐节点明确生成、复用或跳过的理由：

| 节点 | 决策 | 理由说明 | 验证方式与何时该补 |
|---|---|---|---|
| AGENTS.md | 生成 | 仓库顶层指令与知识路由的唯一必需入口，承载核心红线与两跳内地图 | `npm run docs:lint`（行数 ≤ 120 行） |
| README.md | 生成 | 声明项目定位、设计阶段、不可安装状态、开源规范待定及灵感参考 | 人工查验与文档规范核对 |
| docs/design.md | 生成 | 详述三大核心能力、核心不变式、并发调度约束与防总结降级设计 | 文档链接可达与规范核对 |
| docs/dsh-integration.md | 生成 | 记录 DSH 核心源码审计细节、已验证接口缝隙与已知风险边界 | 对照 DSH 源码基线核验 |
| docs/validation.md | 生成 | 本文件，提供清晰可执行的验收矩阵、决策记录与下一阶段切片 | 文档链接可达与规范核对 |
| package.json | 生成 | 声明 `"private": true` 与本地 `docs:lint` 脚本入口 | 原生 Node 脚本直接执行 |
| .gitignore | 生成 | 严密保护环境凭据、敏感密钥、运行时会话日志与中间产物 | `git status` 确认未跟踪敏感项 |
| scripts/docs-lint.mjs | 生成 | 零外部依赖的原生 Node 脚本，提供秒级确定性的文档与链接检查 | `npm run docs:lint` 自动化测试 |
| ARCHITECTURE.md | 跳过 | 当前仓库为纯设计阶段脚手架，尚无业务源码与多层复杂调用目录 | 待业务源码建立且跨模块难以自解释时补充 |
| docs/exec-plans/ | 跳过 | 当前任务为单一切片初始化，暂无跨多会话的复杂未决计划 | 后续进入大规模长周期特性开发时按需创建 |
| docs/generated/ | 跳过 | 当前暂无可由自动化脚本输出的派生事实文档 | 后续若引入工具 Schema 或代码提取文档时按需创建 |
| docs/doc-gardening.prompt.md | 跳过 | 处于初始 Lite 阶段，文档规模紧凑，暂无周期性文档园艺负担 | 仓库升级至 Core 档位且文档演进加速时补充 |
| .github/workflows/ | 跳过 (建议但未启用) | 开源归属与组织审批仍处于待定评审状态，避免预置无效 CI 流程 | 待组织审批与公开发布流程启动后配置 CI 门禁 |

---

## 2. 运行时验收测试矩阵（Runtime Acceptance Matrix）

当后续进入代码实现阶段时，必须通过以下 6 类验收测试用例：

| 编号 | 测试用例名称 | 测试层级 | 验证目标与断言条件 |
|---|---|---|---|
| **TC-01** | `new_context` 工具执行模式与收尾 | 单元测试 | 验证 `executionMode` 返回 `{ kind: 'exclusive' }`；调用 `exec.concludeTurn()` 后正确标记 `concluded: true`，且当前步骤不产生未提交表面折叠 |
| **TC-02** | 工具批处理并发与平衡提交 | 集成测试 | 在单个回复中同时发出 `[save_note, new_context, grep]`，验证三个工具的 `tool/call` 与 `tool/result` 均完成物理日志提交，满足 `toolPairingBalancedAfter` |
| **TC-03** | `agent/pre-step` 安全表面替换 | 集成测试 | 触发滚动后，验证实际的 `surfaceOp: 'replace'` 准确在下一周期的 `agent/pre-step` 发生，历史交互被正确阴影化，新窗口初始化消息到位 |
| **TC-04** | Node 0 系统提示保护与连续性 | 集成测试 | 验证表面替换的起始节点 `startSeq` 严格位于 Node 0 之后；断言 `sourceEventSeqs` 数组连续包含所有被折叠的表面节点序列号 |
| **TC-05** | 持久化写入与断电重启重放 | 恢复测试 | 调用 `ctx.sessions.flush(session)` 强制刷盘后杀死运行时；使用 `ctx.agentLoop.resume(id)` 重启，断言表面消息与折叠前完全一致，且 `session.snapshotEvents()` 可完整读取全部原始事件 |
| **TC-06** | 日志全局不变量门禁 | 门禁测试 | 挂载 `@deepseek-ai/dsh-compaction/invariant`，跑通完整的多窗口滚动会话流，断言全过程零不变量违背报错（Zero invariant failure） |
| **TC-07** | 预算预警与超限显式挂起 | 边界测试 | 构造长上下文会话，验证在剩余 Token 低于阈值时触发单次预警（Single-shot reminder）；超限时触发免总结滚动，异常时显式挂起，无隐式 LLM 总结回退 |

---

## 3. 下一阶段实现切片（Next Implementation Slice）

本仓库完成设计初始化后，后续代码实现将分为以下紧凑切片增量推进：

```
+-----------------------------------------------------------------------------+
| 切片 1: 插件基础骨架建立                                                     |
| - 创建 packages/plugin-newwindows 目录与 package.json                       |
| - 定义 Cordis 插件生命周期与配置 Schema                                      |
+-----------------------------------------------------------------------------+
                                       |
                                       v
+-----------------------------------------------------------------------------+
| 切片 2: 工具集定义与注册                                                     |
| - 实现 save_note / read_notes 便签工具                                       |
| - 实现 new_context 滚动声明工具（配置 exclusive 与 concludeTurn）            |
+-----------------------------------------------------------------------------+
                                       |
                                       v
+-----------------------------------------------------------------------------+
| 切片 3: 调度引擎与表面替换 (CompactionEngine)                                |
| - 实现 NewWindowsCompactionEngine 继承 CompactionEngine                     |
| - 监听 agent/pre-step 钩子，执行免总结表面折叠与种子便签注入                 |
+-----------------------------------------------------------------------------+
                                       |
                                       v
+-----------------------------------------------------------------------------+
| 切片 4: 范围受限历史回溯与验收闭环                                           |
| - 实现 history_lookup 工具，基于 SessionHandle 进行有界切片读取               |
| - 跑通上述 7 项运行时验收测试用例                                            |
+-----------------------------------------------------------------------------+
```

---

## 4. 文档导航与关联

- 返回查看架构设计理念与核心不变式：[系统架构与核心设计](design.md)
- 返回查看 DSH 源码机制对账与接口分析：[DSH 接口集成与对账分析](dsh-integration.md)