# Agent 业务层（生产级保证） · 路线图

> 日期：2026-10-27｜对外发布版。
> 定位一句话：**Agent 业务层是跨框架的抽象核心能力——会话卫生、可回溯、可审计、
> 可恢复，全部带生产级保证；`dsh-retrace` 是它在 DeepSeek Harness 上的第一个实现。**

> 近期/下一步计划（产品级）：[PLAN.md](./PLAN.md)

---

## 命名与分层（抽象核心 ≠ 具体实现）

| 层 | 是什么 | 绑定平台？ |
|---|---|---|
| **Agent 业务层（生产级保证）** | 抽象核心能力：会话卫生 / 可回溯 / 可审计 / 可恢复——与模型、工具、UI、宿主框架无关 | ❌ 不绑定任何平台 |
| **dsh-retrace** | Agent 业务层在 **DeepSeek Harness** 上的一个实现（插件） | ✅ 绑定 DSH |

**含义**：`dsh-retrace` 这个名字属于 DSH 生态；但**业务层本身不是任何框架的附属**。
它描述的是「任何 agent 会话都需要的运营能力」——只要一个 agent 有「会话/状态/历史」
这三个概念，业务层的机制就有落点。dsh-retrace 是第一个实现，**不是唯一的实现**：
同一套机制可以服务其他 agent 框架、headless、自托管部署。

---

## 为什么是「业务层」，不是「功能」

任何 agent 运行时都可以分为三层：

- **数据层**——会话与历史怎么存（DSH 的 append-only 事件日志只是其中一种存储）
- **执行层**——模型循环、工具调用怎么跑
- **业务层**——「会话怎么保持健康、怎么回退、怎么审计、坏了怎么修」

业务层与模型、工具、UI、甚至存储格式都无关。**只要一个 agent 有「会话」这个概念，
就有业务层的需求**——这正是它跨框架成立的原因。

| 业务层机制 | 回答的问题（通用表述） | DSH 上的现状 |
|---|---|---|
| **卫生**（写安全/中断/并发守护） | 修改会话会不会破坏一致性？中断会不会留脏状态？并发写会不会冲突？ | ✅ dsh-retrace 已实现 |
| **可回溯**（版本/时间线/回退） | 每次改动属于哪个版本？能不能回到任意点？连带状态能不能一起回退？ | ✅ 已实现 |
| **可审计**（考古/谱系/历史） | 会话做过什么？输入输出去哪了？分支从哪来？ | ✅ 已实现（考古 CLI） |
| **可恢复**（体检/修复/快照） | 会话坏了吗？坏了能修吗？坏的那一刻有备份吗？ | ✅ 已实现（离线修复） |

**一句话**：模型决定 agent 有多聪明，业务层决定 agent 的会话能不能被信任。

---

## 抽象机制 ↔ DSH 实现（业务层不绑 DSH 的证据）

| 抽象机制（任何框架都需要） | DSH 上的具体实现 |
|---|---|
| 写前校验：修改会话前验证其合法性 | 写前多层校验（持久化/引擎/插件） |
| 中断治理：打断进行中的任务必须干净收尾 | 修改前自动停止任务并等待空闲 |
| 状态一致性：会话内不得出现半写状态 | 临时 step 包裹编辑 marker（对 DSH token-meter 合法） |
| 并发守护：检测外部写入冲突 | 看门狗检测外部写入冲突，异常即快照 |
| 体检：离线验证会话可加载/可继续/可压缩 | `dsh-log-contract` 30+ 契约规则（含深层 token-meter 配对） |
| 修复：原地恢复损坏的会话 | `fix --neutralize` / `--clip-crossstep`（帧级、先备份） |
| 回退：回到任意历史点并恢复连带状态 | 版本时间线 + 产物回退（git 优先 + 快照兜底） |
| 审计：会话行为可追溯 | 考古 CLI（工具调用索引/输出提取/谱系） |

**读法**：左列是业务层的**契约**（任何 agent 框架实现它即获得生产级保证）；右列是
dsh-retrace 在 DSH 上对每个契约的落地。换一个框架，右列换实现，左列不变。

---

## 生产级保证（差异化承诺，通用表述）

以下每一条在 dsh-retrace 里**已实现并验证**（验证方式见每条末尾），不是口号：

### 1. 写安全 —— 修改会话永不破坏一致性
- 每次修改都过**写前校验**（合法性验证），违约即拦、不落盘
- 修改前自动停止运行中的任务（干净收尾），杜绝半写状态
- 会话内的替换操作以**框架合法的最小形态**写入——永不触发消费端的拒绝
- 这是其他「undo / verify」工具没有的维度：它们只读，dsh-retrace 保证写也干净
- *验证方式*：契约运行时断言 + 端到端面序列回归（见 CHANGELOG 各版本条目）

### 2. 深层体检 —— 不是浅层扫描
- 30+ 契约规则，覆盖会话可加载/可继续/可压缩的全部消费路径
- **以真实损坏会话当测试集**——能找出让会话「永久不可压缩/不可恢复」的那类深层问题
- 通用「孤儿调用」扫描器看不到的那一层，它能看到
- *验证方式*：`dsh-log-contract` 的规则测试 + 真实损坏会话测试数据

### 3. 检测 → 修复 → 守护 闭环
- **检测**：离线全量规则 + 实时看门狗
- **修复**：原地修复问题状态、裁剪非法引用、重编号——帧级、先备份
- **守护**：并发冲突第一时间快照现场
- *验证方式*：闭环各环节的独立用例 + 真实会话测试数据回归

---

## 路线图（分期）

### ✅ 已上线（dsh-retrace 0.4.x）
- 撤回 / 编辑重发 / 重新生成（写安全，三层校验）
- 版本时间线 + 产物回退（git 优先 + 快照兜底）+ 从版本跳回对话
- 分叉图 + 会话谱系（lineage）
- 实时看门狗（并发写入即快照现场）
- 离线体检 30+ 规则 + 修复原语（neutralize / clip-crossstep）
- **关闭守卫**：运行中会话检测（agent 活动 / 排队 / 后台任务 / 未闭合轮）+
  退出提示 + 运行中横幅 + Web 页面关闭阻止（`beforeunload` 强拦 / 轻确认）+
  查询面（host RPC 与 HTTP 同形状）
- dsh-market 一键安装

### 🗺️ 计划中（**尚未发布**，方向性说明）

> 本节内容**没有**在任何已发布版本里可用；写出方向是为了让读者判断这个项目往哪走。

- **运行时守护**：订阅会话事件流做实时校验，违规即刻标记（不再只在离线体检时发现）
- **中断轮次治理增强**：关闭守卫的「运行中徽标 + 关闭前弹窗」需要宿主侧的 pre-close
  钩子；检测与查询面（运行状态查询接口）已就绪，等待宿主 seam
- **业务层接口抽象**：把「写前校验 / 中断治理 / 体检修复 / 回退 / 审计」固化为
  **框架无关的接口契约**（见上一节的左列），任何 agent 框架可实现之
- **跨框架实现**：同一套契约在非 DSH 的 agent 形态上落地
  （其他 Harness、headless、自托管、自主运行时）——dsh-retrace 作为参考实现
- **更深的可审计**：版本归因报告、把回退次数当作反馈信号

---

## 与社区的关系（诚实）

社区已有 dsh-shelf（verify/tree）、dsh-fork-graph、dsh-negative-ledger 等优秀插件。
dsh-retrace 的位置不是「又一个同类工具」，而是：

> **它们各自做业务层的一块；dsh-retrace 把它当作一整层来做，并以框架无关的方式定义它。
> 工具可以被替换；层是基础设施。**

---

## 发布节奏

- dsh-retrace 跟随版本发布（0.4.x → 0.5.x 引入运行时守护）
- 业务层接口抽象随 0.5.x+ 逐步公开（先在 DSH 内可用，再跨框架）
- 每个里程碑配真实验证（真实会话测试数据回归，非演示）
- 社区 PR / issue 欢迎，路线图随反馈调整

---

## 关联文档

- [README](../README.md)（dsh-retrace 安装与使用）
- [CHANGELOG](../CHANGELOG.md)（版本记录）
- `dsh-log-contract`（业务层「医生」组件：体检/修复）