# 系统架构与核心设计

本文档定义 `dsh-newwindows` 扩展插件的总体架构、核心能力模型与系统不变式。

---

## 1. 设计背景与参考来源

### 1.1 灵感参考
本项目的设计思想借鉴了 OpenAI Codex 运行时的上下文管理与窗口生命周期机制：
- 公共参考仓库：[openai/codex @ 5ecb3afd1bf405149e2159bfda50093b0c1b5fab](https://github.com/openai/codex/tree/5ecb3afd1bf405149e2159bfda50093b0c1b5fab)
- 开源许可协议：Apache-2.0
- 核心参考文件：
  - `codex-rs/core/src/compact_token_budget.rs`（免总结窗口滚动主调度）
  - `codex-rs/core/src/tools/handlers/new_context_window.rs`（模型显式窗口重置工具）
  - `codex-rs/core/src/state/auto_compact_window.rs`（UUIDv7 窗口标识链与单次预警闭锁）
  - `codex-rs/ext/history-notes/src/tools.rs`（分层便签与受限历史检索工具）

### 1.2 无独创性声明与边界原则
本项目不主张任何算法与协议的原创性，核心目标在于将上述经过实践检验的上下文管理范式适配至 DeepSeek Harness (DSH) 既有的 Cordis 插件与事件流架构中。

> **核心原则：无损归档不等于保证召回（Lossless Archive != Guaranteed Recall）**  
> 1. **物理存储保证**：底层持久化层采用追加写入（Append-only），所有历史事件被永久保存且不可篡改，实现真正意义上的无损归档；  
> 2. **注意力窗口限制**：窗口滚动（Rollover）发生后，历史交互被完全移出大模型的活动上下文（Prompt Tokens）；  
> 3. **防幻觉设计**：大模型不会自发保留跨窗口记忆。一切关键任务目标与执行状态必须依赖模型沉淀的结构化便签进行注入，历史细节必须由模型主动调用受限历史工具进行检索。

---

## 2. 三大核心能力定义

`dsh-newwindows` 由三大能力支柱构成：

```
+-------------------------------------------------------------------------+
|                              DSH 会话空间                               |
|                                                                         |
|   +-----------------------------------------------------------------+   |
|   | 1. 模型自主便签 (Model-Authored Notes)                          |   |
|   |    - 随思考沉淀任务目标、状态机、未决待办                       |   |
|   |    - 具备稳定 ID、时间戳、单会话隔离与信任标记                  |   |
|   +-----------------------------------------------------------------+   |
|                                    |                                    |
|                                    v                                    |
|   +-----------------------------------------------------------------+   |
|   | 2. 免总结上下文滚动 (Summary-Free Context Rollover)              |   |
|   |    - new_context 工具调度 / Token 预算阈值触发                  |   |
|   |    - 表面折叠 (surfaceOp: 'replace')，不消耗 LLM 总结 API       |   |
|   |    - 注入结构化便签锚点，开启全新独立编号窗口                   |   |
|   +-----------------------------------------------------------------+   |
|                                    |                                    |
|                                    v                                    |
|   +-----------------------------------------------------------------+   |
|   | 3. 范围受限历史回溯 (Scoped Raw History Lookup)                  |   |
|   |    - 基于底层不可变事件日志 (SESSION_FORMAT_VERSION = 3)        |   |
|   |    - 有界切片读取，按需召回被阴影化的历史交互细节               |   |
|   +-----------------------------------------------------------------+   |
+-------------------------------------------------------------------------+
```

1. **本地模型自主便签（Local Model-Authored Notes）**：
   - 允许模型在推理过程中主动记录、更新和检索结构化便签（如全局目标、当前尝试方案、失败经验与待验证代码位置）；
   - 便签存储在当前会话的本地持久化状态中，不走远端黑盒持久化，零网络外部依赖。
2. **免总结上下文滚动（Summary-Free Context Rollover）**：
   - 替代传统依赖 LLM 递归生成大段摘要的 Compaction 方案；
   - 在触发滚动时，通过 DSH 会话表面操作（Surface Replacement）将历史交互转为阴影（Shadowed），同时将最新便签与当前任务延续指令作为新窗口的初始用户消息；
   - 零额外模型推理开销，避免总结失真与总结死循环。
3. **范围受限历史检索（Scoped Raw History Lookup）**：
   - 为模型提供只读查询工具，允许在需要时基于事件序列号或窗口 ID 回溯被折叠的早期会话记录；
   - 严格限制查询返回的分页大小与字节数，防止回溯结果再次撑爆上下文。

---

## 3. 核心设计约束与系统不变式

为保证运行时安全性与数据一致性，`dsh-newwindows` 遵循以下系统级硬性约束：

### 3.1 同一会话同源保证（Same DSH Session）
- 窗口滚动并不创建孤立的外部会话（Session），整个生命周期始终运行在同一个 DSH `SessionId` 内。
- 前端交互、SSE 观察者流以及会话持久化句柄均无需重连，保持客户端连接的稳定性。

### 3.2 独立且单调递增的窗口编号（Independently Numbered Windows）
- 会话内的每次上下文重置均分配单调递增的时序窗口 ID（UUIDv7 格式）。
- 系统状态中显式维护窗口关系链：
  - `first_window_id`：初始窗口 ID；
  - `previous_window_id`：上一窗口 ID（初始为 null）；
  - `current_window_id`：当前活动窗口 ID。
- 便签与历史事件均与特定的 `window_id` 关联，便于溯源。

### 3.3 物理归档只追加且不可变（Immutable Append-Only Archive）
- DSH 底层的会话事件日志（`SessionEventMap`）是严格只追加的。
- 表面折叠操作仅仅改变暴露给模型推理的消息视图（Surface Projection），绝不物理删除任何历史事件。
- 被折叠的历史事件在持久化存储中永久保留，保证审计与故障排查的可溯源性。

### 3.4 便签作用域隔离与信任标记（Scoped Notes & Trust Marking）
- **会话级隔离**：初始版本中，便签严格限定在单个会话生命周期内，严禁跨用户、跨租户或跨项目泄漏；
- **有界读取**：便签列表与搜索操作必须施加严格的有界限制（如单文件最大限制、单次返回最大条目数），杜绝无节制注入；
- **信任标记（Trust Marking）**：系统在便签元数据中明确标明作者来源（`model-authored` vs `user-injected` vs `tool-output`），防止提示注入攻击；
- **稳定唯一标识**：每条便签具备稳定 ID，支持更新与归档，不可随意覆写。

### 3.5 严禁在工具批处理中途滚动（Never Rollover Mid Tool Batch）
这是本系统最重要的调度安全约束。

**危害机理**：
当大模型在单个推理步骤中并行输出多个工具调用（例如 `[write_note, new_context, execute_command]`）时：
1. `executeToolCalls` 遍历执行这组工具；
2. 如果 `new_context` 工具在其自身 `execute()` 函数内部立即触发会话表面折叠（`surfaceOp: 'replace'`），此时当前 turn 尚未结束；
3. `new_context` 自身的 `tool/result` 尚未 commit 到会话事件流；
4. 后续同批次的工具调用已携带旧上下文分配的 call ID，其结果会在表面折叠之后被追加，破坏 `toolPairingBalancedAfter` 平衡约束，导致底层抛出异常或形成孤儿调用。

**规范行为**：
- `new_context` 工具在执行体内**仅能声明意图**：
  1. 调用 `exec.concludeTurn()` 标记当前 Turn 提前收尾；
  2. 调用 `exec.deferContext(...)` 暂存新窗口所需的初始化便签与指示；
  3. 返回成功状态 `"A new context window will start without summarizing conversation history."`；
- **表面替换的执行时机**：必须延迟至当前 Turn 完全结束（所有同批次工具的 `tool/call` 与 `tool/result` 均已成对提交到事件流后），在下一个周期的 `agent/pre-step` 钩子处执行，或交由定制的 `CompactionEngine` 统一调度。

### 3.6 原子性与崩溃一致性状态（Atomic & Crash Consistent State）
- 会话状态演进完全依赖 DSH 的持久化事务与事件重放机制（`SESSION_FORMAT_VERSION = 3`）。
- 表面折叠事件（携带 `surfaceOp: { op: 'replace', startSeq, endSeq }`）一旦持久化并经 `ctx.sessions.flush(session)` 刷盘，系统因断电或进程崩溃重启后，通过 `agentLoop.resume(id)` 重放事件流能够 100% 确定性地复原折叠后的状态。
- 不引入未受保护的纯内存状态机，确保持久化状态与运行时内存状态严格对称。

### 3.7 禁止隐式总结降级（No Silent Summary Fallback）
- 当模型或用户触发免总结滚动时，系统必须严格执行免总结重置逻辑。
- 绝不允许在免总结滚动遇到异常时，偷偷回退到传统 LLM 总结逻辑。隐式总结不仅违背用户与模型的预期，还可能在极端长上下文中引发连环超时。
- 发生故障时，系统必须遵循 Fail-loud 原则：报错并中断，或保持当前基线状态等待干预。

### 3.8 任务延续与显式触发路径（Task Continuation & Explicit Triggers）
系统必须支持三条明确的触发与延续路径：
1. **主动触发（Manual Path）**：
   - 模型在完成阶段性工作或感知到上下文过长时，自主调用 `new_context` 工具；
   - 工具参数中携带对下一阶段目标的描述。
2. **预算告警与自动触发（Auto Path）**：
   - 依据 `TokenMeter` 测算的上下文消耗，在剩余可用 Token 触及预警阈值时，向上下文注入单次预警消息（Single-shot reminder）；
   - 若模型未在预警后主动重置且 Token 耗尽，系统在 step 边界自动触发免总结滚动，将已保存的最新便签自动升格为种子上下文。
3. **溢出保护路径（Overflow Path）**：
   - 若单次工具返回超大结果造成硬性超限，系统捕获溢出错误并触发保护性折叠，保留最近关键便签与错误信息，防止会话永久死锁。
4. **待处理输入暂存（Pending Input Staging）**：
   - 新窗口生成时，首个用户消息清晰呈现：
     - 格式化的当前窗口标识与前序窗口关联；
     - 当前有效的便签汇总；
     - 待继续执行的任务目标。

---

## 4. 当前 DSH 实现 vs. 提议行为对比

| 维度 | 当前 DSH 默认实现 (`BasicCompactionEngine`) | `dsh-newwindows` 提议扩展设计 |
|---|---|---|
| **压缩机制** | 调用大模型推理接口生成长文本摘要 (`summarize()`) | 免总结表面折叠 (`surfaceOp: 'replace'`)，注入最新便签 |
| **Token 与耗时开销** | 消耗额外 Summarization Token，耗时通常在数秒至数十秒 | 零模型总结调用开销，耗时为本地微秒/毫秒级事件写入 |
| **信息保真度** | 依赖 LLM 抽象总结，存在细节丢失、代码语法变形与幻觉 | 物理日志 100% 无损归档；活动上下文保留模型自选便签 |
| **窗口概念** | 单一线性会话，未引入显式时序子窗口概念 | 引入单调递增的时序子窗口链 (`UUIDv7`)，可显式追踪 |
| **历史检索** | 模型无法直接读取被折叠的早期原始交互片段 | 提供范围受限的原始事件切片只读工具，按需有界查阅 |
| **便签支持** | 无内置专用的模型持久化便签能力 | 提供一等公民的模型自主便签（增、删、改、查、有界搜索）|
| **调度与并发安全** | 仅在 `agent/pre-step` 自动执行，不支持工具内安全收尾 | 工具层 `concludeTurn()` 结合 `agent/pre-step` 延迟执行，杜绝中途滚动 |

---

## 5. 文档导航与关联

- 查看与 DSH 核心源码接口的详细对账与代码行分析：[DSH 接口集成与对账分析](dsh-integration.md)
- 查看运行时验收测试矩阵与落地演进规划：[验收矩阵与后续演进](validation.md)