# dsh-turnscope 开发实施计划

> ⚠️ **已废弃（superseded）** —— 本文件描述的是 v0.1 的「record-only trace」方向，已被
> v0.2 取代（见 `docs/PRD.md` 与 `docs/ARCHITECTURE.md`）。当前执行中的计划是
> `docs/superpowers/plans/2026-09-11-v0.1-turn-safety-inspector.md`。
>
> 具体被推翻的前提：产品核心从「记录」改为「证据采集 → 变化归属 → 安全判定 → 恢复决策」；
> Checkpoint 必须保存 relevant path 的原始内容（否则 V0.2/V0.3 的字节级恢复不可能）；
> 脱敏边界改为诊断负载脱敏、recovery blob 原字节（v0.2 §12.3 / 决策 6）。
> 保留本文仅作历史记录。

| 字段 | 内容 |
| --- | --- |
| 文档版本 | 0.1 |
| 状态 | 已废弃 |
| 周期 | 2–3 周 |
| 依据 | `docs/PRD.md`、`docs/ARCHITECTURE.md` |

## 1. 交付目标

在 2–3 周内交付一个可安装、可演示、可验证的 DSH Web MVP：用户能查看按轮次组织的活动与文件变化；系统在安全条件满足时提供 Restore；用户能从历史检查点创建隔离 Worktree 与新会话；所有数据默认仅存本地且写入前脱敏。

## 2. 开发原则

1. 先锁定 DSH 兼容版本和公开扩展面，再开发业务能力。
2. 先建立事件模型、存储与安全边界，再做 UI。
3. Restore 必须 preview-first、conflict-refusing，绝不以 `git reset --hard` 实现。
4. Fork 与 Restore 使用独立引擎和验收用例。
5. 每个阶段都保持插件可禁用、主会话可继续。
6. 新能力必须带固定输入测试或临时 Git 仓库集成测试。

## 2.1 已确定的原生技术栈

- TypeScript 6，ESM；
- Node.js 22.19 或更高版本；
- React 18 与 DSH Client UI Slots；
- Cordis Plugin `apply` / `inject` 生命周期；
- pnpm 11.7；
- tsdown 构建 Node 与 Web Client 双入口；
- Vitest 4、Testing Library 和 jsdom；
- DSH `0.1.1-rc.2` 公共包作为首个兼容基线；
- Node 内置 `node:sqlite` 与 DSH Storage 接口用于后续 Host 持久化。

首个可运行切片先交付原生 `conversation.view` 只读时间线；SQLite、Checkpoint、Restore 和 Fork 分别进入后续独立实施计划。

## 3. 建议目录

```text
packages/turnscope/
├── src/
│   ├── adapter/          # DSH 事件与服务适配
│   ├── domain/           # Turn、Activity、Checkpoint、Finding
│   ├── redaction/        # 写入前脱敏与截断
│   ├── storage/          # SQLite、对象存储、迁移、保留策略
│   ├── git/              # GitPort、观察、快照、Diff
│   ├── restore/          # 安全检查、预览、应用、审计
│   ├── fork/             # Worktree、会话关联、清理
│   ├── rules/            # 确定性问题提示
│   ├── ui/               # 面板、时间线、详情、设置
│   └── plugin/           # Bundle 入口与生命周期
├── test/
│   ├── fixtures/events/
│   ├── integration/
│   └── e2e/
└── migrations/
```

最终目录应服从 DSH Bundle 规范；上述结构表达模块边界，不预设具体构建工具。

## 4. Phase 0：兼容性探针与工程基线（第 1–2 天）

### 任务

- 固定一个 DSH 开发者预览版本，记录支持范围；
- 验证插件安装、启用、禁用和卸载生命周期；
- 建立最小 Bundle、开发命令、测试命令和 CI；
- 枚举可用 Session Event、工具事件、工作区与新会话 API；
- 用真实会话捕获完成、失败、中断三类脱敏事件夹具；
- 建立错误边界，确认插件抛错不会阻断主会话。

### 交付物

- 可加载的空面板插件；
- DSH 兼容性说明；
- 三组版本化事件夹具；
- CI 基线与最小冒烟测试。

### 退出条件

- 插件可重复安装/启停；
- 事件夹具包含稳定轮次边界；
- 插件入口故意失败时 DSH 主会话仍可使用。

## 5. Phase 1：Trace 核心（第 3–5 天）

### 任务 1：领域模型与适配器

- 定义 `NormalizedEvent`、`TurnRecord`、`ActivityRecord` 和 schema version；
- 实现事件映射、未知事件降级、幂等 ID 和乱序缓冲；
- 实现轮次状态机以及完成、失败、中断闭合逻辑。

### 任务 2：脱敏与存储

- 实现 Token、Authorization Header、私钥和用户规则脱敏；
- 实现输出字节上限与截断元数据；
- 建立 SQLite 初始迁移与 WAL 配置；
- 建立内容寻址对象存储、临时写入、哈希校验和原子改名；
- 实现 `TraceRepository` 查询接口。

### 任务 3：基础时间线

- 实现面板入口、轮次列表与 Activity 列表；
- 支持实时更新和重开会话后的持久化恢复；
- 支持全部、文件、命令、测试、异常过滤。

### 测试

- 固定事件夹具快照测试；
- 重复/乱序事件与未知字段测试；
- SQLite 重启恢复与事务中断测试；
- 敏感内容落盘扫描；
- 1,000 条 Activity 列表性能基线。

### 退出条件

- 三类轮次都形成完整 Trace；
- 最近失败活动可在两次点击内定位；
- 测试密钥不出现在 SQLite、对象文件或诊断日志中。

## 6. Phase 2：Git 变化与 Checkpoint（第 6–7 天）

### 任务

- 定义结构化 `GitPort`，禁止业务层拼接 Shell；
- 实现仓库身份、HEAD、分支、索引与工作树观察；
- 实现 pre/post checkpoint 和内容指纹；
- 计算新增、修改、删除、重命名和二进制变化；
- 标记轮次前 baseline 改动和归属不确定变化；
- 实现 Diff 对象的截断、延迟读取和 UI 展示。

### 测试矩阵

- 干净工作区；
- 未暂存与已暂存改动；
- 新增、删除、重命名、文件模式变化；
- 二进制文件、大文件、符号链接；
- 轮次期间用户并发编辑；
- checkpoint 创建失败。

### 退出条件

- 干净工作区的轮次文件列表与 Git Diff 一致；
- baseline 改动不归因给 Agent；
- 创建 checkpoint 不改变 HEAD、分支、索引或工作树；
- checkpoint 失败只使该轮不可恢复，不阻断主任务。

## 7. Phase 3：安全 Restore（第 8–10 天）

### 任务 1：安全判定

- 实现同仓库、完整 checkpoint、干净起点、HEAD 一致、内容指纹一致等检查；
- 检测合并/变基/冲突状态与未知文件；
- 生成结构化拒绝原因和 UI 文案。

### 任务 2：预览与执行

- 生成逆向 Diff、影响文件列表与一次性 operation ID；
- 执行前重新验证，防止确认期间状态漂移；
- 创建 recovery-checkpoint；
- 在临时目录应用并校验后再原子更新目标文件；
- 将 Restore 结果作为新 Activity 追加。

### 测试矩阵

- 正常恢复新增、修改、删除文件；
- checkpoint 后用户又修改同一文件；
- HEAD 改变、分支改变、索引改变；
- 文件权限、二进制、大文件和补丁冲突；
- 应用中途故障与 recovery-checkpoint 恢复；
- 静态检查确保实现中不存在危险 Git 重置。

### 退出条件

- 只有全量安全检查通过时才允许确认；
- 漂移、冲突和对象缺失时零文件修改；
- Restore 不移动 HEAD、不改写分支历史；
- 失败后工作区保持原状态或给出可执行恢复说明。

## 8. Phase 4：隔离 Fork（第 11–12 天）

### 任务

- 从 checkpoint 创建插件管理的临时引用与 Git Worktree；
- 创建包含 parent session/turn/checkpoint 关联的新 DSH 会话；
- 打开新会话，预填可编辑提示，不自动调用模型；
- 实现 Fork 列表、磁盘占用与生命周期状态；
- 实现只清理受管 Worktree 的安全流程；
- 在未提交改动、路径不匹配或仓库身份不匹配时拒绝自动清理。

### 测试

- 从多个历史 checkpoint 创建 Fork；
- Fork 中修改、提交和工具调用不影响原工作区；
- 创建 Worktree 成功但创建会话失败的补偿；
- 路径碰撞、对象缺失和磁盘不足；
- 脏 Worktree 清理拒绝与干净 Worktree 清理。

### 退出条件

- 新会话关联可追溯；
- Fork 不改变原工作区当前分支和文件；
- 清理不能触及非插件创建的 Worktree。

## 9. Phase 5：规则、设置与产品化（第 13–15 天）

### 任务

- 实现六类确定性规则和 Finding 证据链接；
- 完成概览/变化/活动三个详情标签页；
- 完成保留期限、容量上限、忽略路径和规则开关；
- 实现 30 天或 100 MB 先到者为准的最旧优先清理；
- 完成存储位置、占用空间、兼容性和最近错误诊断；
- 补齐加载、空状态、失败状态、键盘操作和无障碍名称；
- 完成安装、升级、卸载、安全和 Worktree 清理文档。

### 退出条件

- 相同事件输入稳定产生相同 Finding；
- 被 Fork 或固定记录引用的 checkpoint 不会被自动清理；
- 状态表达不只依赖颜色；
- 设置无效时回退到安全默认值。

## 10. 测试与验证计划

### 自动化层级

- **单元测试**：状态机、脱敏、规则、路径验证、安全判定、保留策略；
- **集成测试**：SQLite/对象存储、真实临时 Git 仓库、checkpoint、Restore、Fork；
- **契约测试**：每个支持 DSH 版本使用同一组事件夹具；
- **端到端测试**：安装后完成一次正常轮次、失败轮次、Restore 与 Fork；
- **故障注入**：磁盘不可写、对象丢失、进程中断、Git 锁与插件 UI 崩溃。

### 发布前必须通过

1. 所有 P0 需求对应自动化测试或可重复验收步骤；
2. 数据丢失、分支改写、越界路径和明文密钥测试零失败；
3. 在支持的 DSH 版本及 macOS/Linux 上完成冒烟测试；
4. 1,000 条 Activity 场景达到首屏 2 秒目标；
5. Restore/Fork 全部拒绝路径确认无副作用；
6. 禁用或卸载插件后 DSH 核心功能正常。

## 11. 每日合并纪律

- 每个 PR 只跨一个清晰模块边界；
- 领域接口先于具体存储、Git 或 UI 实现合并；
- Git 写操作必须附安全判定和失败测试；
- 数据模型变化必须带迁移与旧数据测试；
- UI 不直接引用上游 Harness 事件字段；
- 所有诊断示例使用合成数据，不提交真实会话载荷或密钥。

## 12. 风险与降级策略

| 风险 | 触发信号 | 降级策略 |
| --- | --- | --- |
| DSH API 在开发期变化 | 契约测试失败 | 只修改 Adapter，并缩小声明的兼容版本 |
| Git 快照不稳定 | checkpoint 集成测试失败 | 保留 Trace/Diff，禁用 Restore/Fork |
| Restore 风险无法消除 | 漂移场景出现误覆盖 | MVP 移除原地 Restore，仅保留预览与 Fork |
| UI 性能不足 | 1,000 条记录超过目标 | 分页、虚拟列表、延迟加载 Diff |
| 进度落后 | 第 10 天未完成 Restore | 冻结 P1，设置页只保留 P0，优先安全测试 |
| Windows 差异 | Worktree 测试不稳定 | 首版只声明 macOS/Linux 支持 |

## 13. Release Checklist

### 功能

- [ ] 完成、失败、中断轮次可正确关闭并重开恢复
- [ ] 文件列表和 Diff 正确，baseline 不被错误归因
- [ ] 六类问题提示均有证据链接
- [ ] Restore 预览、确认、重新验证和审计完整
- [ ] Fork 创建、关联、打开和清理完整

### 安全与隐私

- [ ] 无 `git reset --hard`、强制覆盖或分支历史改写
- [ ] 路径越界和符号链接逃逸测试通过
- [ ] 敏感信息在持久化前完成遮盖
- [ ] 诊断和导出不包含环境变量或真实凭据
- [ ] 插件故障不阻断 DSH 主任务

### 兼容与发布

- [ ] README 标明状态、支持版本、平台和限制
- [ ] 安装、升级、禁用、卸载步骤已验证
- [ ] macOS/Linux 支持矩阵完成
- [ ] License、版本号和变更记录就绪
- [ ] 演示脚本覆盖 Timeline、Diff、Restore 拒绝与 Fork

## 14. Demo 验收脚本

1. 在干净 Git 示例仓库启动 DSH，并让 Agent 修改一个文件、运行一次成功测试；
2. 打开 Turnscope，10 秒内展示该轮摘要、文件 Diff 和验证结果；
3. 再执行一个失败命令，确认 Finding 跳转到证据；
4. 修改受影响文件后尝试 Restore，确认系统因漂移拒绝且零副作用；
5. 恢复到可验证状态后预览并执行 Restore，确认 HEAD 未移动；
6. 从原轮次创建 Fork，在新 Worktree 中修改并提交，确认原工作区不变；
7. 打开诊断与磁盘占用，随后安全清理干净 Fork；
8. 禁用 Turnscope，再运行一轮 DSH 任务，确认主流程不受影响。

完成以上步骤并保留测试证据后，MVP 才进入发布候选状态。