dsh-checkpoint-rewind AGENTS.md

AGENTS.md

dsh-checkpoint-rewind 是 DeepSeek Harness 的能力接缝插件：为 DSH 补上 Claude Code /rewind 等价能力 —— git 优先的工作区文件快照 + 会话边界回退（fork 种子会话）+ 一键恢复。别的回退插件卖 Change Ledger（Anionex/dsh-turn-rewind）或纯上下文回退（LingLambda/dsh-undo），本插件卖 git 对象级快照 + fork 种子会话 + 三段式恢复事务（保护检查点 → 恢复 → fork）。DSH 哲学是 everything is a plugin——本仓库只做插件，不碰引擎。改代码前先读 README.md（对外契约）、ARCHITECTURE.md（设计决策）与 test/（现有行为）。

仓库布局：发布面 / 本地工程面

根目录只放发布到 GitHub / npm 的文件；本地工程文件一律收进 dev/（gitignore，永不提交）。

index.mjs            插件入口（唯一 host 面文件）：provider 注册/事件监听//rewind 命令
types.d.ts           类型契约：checkpoint/* SessionEventMap 声明合并 + 配置类型
lib/constants.mjs    词汇表与协议常量（provider/事件名/错误码/默认值，零依赖）
lib/errors.mjs       结构化领域错误（code + details，零依赖）
lib/workspace.mjs    工作区键规范化 + 快照目录解析（零依赖）
lib/checkpoints.mjs  检查点纯函数：≤N 映射、清理计划、列表/预览渲染（零依赖）
lib/glob.mjs         轻量 glob → 相对路径匹配器（copy provider 排除项用，零依赖）
lib/gate.mjs         回退确认门 + 会话事件自适应门（零依赖）
lib/lock.mjs         按键串行化互斥（零依赖）
lib/domain.mjs       'checkpoints' 存储领域 spec（唯一允许 zod/DSH 包的 lib 模块）
lib/projection.mjs   会话投影单元 checkpoints（持久边界校验器，允许 zod）
lib/providers/       provider seam：definition（契约）/ registry / git / copy
cordis.patch.yml     bundle 声明（insert checkpoint-rewind）
package.json         npm 元数据；files 白名单 = 发布内容
README.md            英文主介绍（GitHub 默认页；五语源文）
README.{zh,es,pt,hi}.md   中/西/葡/印地语介绍（顶部互链，与英文同 commit 更新）
ARCHITECTURE.md      三角色 seam 架构图与全部设计决策
CHANGELOG.md / SECURITY.md   变更记录 + 安全政策（含安全面矩阵）
.github/workflows/ci.yml     单元测试 + 组装式集成验证（Windows/Linux × Node 22/24）
.github/workflows/publish.yml   tag v* → 测试 + npm publish（NPM_TOKEN secret）
LICENSE / THIRD_PARTY_NOTICES.md   Apache-2.0 + 复用出处标注
test/                单测 + test/integration/ 组装式集成验证（进 GitHub，不进 npm 包）
dev/                 ❌ 本地工程面：冒烟脚本、夹具、演示——永不提交

• 新增被 index.mjs import 的模块必须同步加进 package.json 的 files。
• 行为变更需同步五语 README：以 README.md（英文）为源，中/西/葡/印地四语同 commit 更新；顶部互链行与 Topics 行保持五语一致。
• 永不提交：dev/、node_modules/、真实用户工作区快照（含敏感内容）、任何凭据/密钥。

命令

npm install          # 安装 peer 依赖（@deepseek-ai/[email protected]、schemastery、zod 等）
npm test             # node --test 跑 test/**/*.test.mjs（含 test/providers/ 单测套件；集成验证单独跑）
npm run test:integration   # 组装式 headless 集成验证（test/integration/，不进发布包）