darrien1998/dsh-ditto

Ditto

审查几个。其余的照做。

一个面向 DeepSeek Harness（DSH）的审查优先批量自动化插件。

npm
CI
License: MIT
dsh-plugin

English · 繁體中文

AI 很擅长处理单个文件。Ditto 则用于对 30 个文件做同样的事，而无需逐一照看这 30 个文件。

你像往常一样描述批量任务。Ditto 会挑选几个有代表性的样本，让你审查并编辑，直到它们看起来正确，然后将同样的标准应用到其余所有内容——在此之前会先向你展示完整预览并请求批准。在你确认之前，不会写入任何内容。

Code → Spec: discover → review 3 samples → approve → preview everything → apply
Files:       preview every proposed copy and deliverable → revise → approve → apply

dsh-ditto 演示：发现 16 个模块，审查 3 个样本，批准，预览全部内容，应用 16/16 且 0 个源文件被修改

安装

Ditto 是一个原生 DSH 插件。一条命令即可将其安装到 DSH profile 中：

dsh plugin --profile web add dsh-ditto

dsh plugin 会在 profile 目录内转发给 pnpm，因此 pnpm 必须在你的 PATH 中。根据需要，可以使用 --profile headless、--profile acp 或任何自定义 profile 名称来代替 web。

| | |
|---|---|
| 更新 | dsh plugin --profile web update dsh-ditto |
| 移除 | dsh plugin --profile web remove dsh-ditto |
| 验证 | dsh plugin --profile web exec dsh-ditto doctor |

doctor 会输出通俗易懂的检查结果：

✓ Ditto 0.3.0
✓ Node.js 22.23.1
✓ dsh 0.1.5-rc.1 detected
✓ pnpm 11.22.0 detected (used by "dsh plugin")
✓ dsh-ditto is installed in profile "web" and listed in its bundles
✓ 17 of 17 tools registered
✓ skill "ditto" registered
✓ stateRoot /your/project/.dsh-ditto is writable
✓ allowedSourceRoots /your/project
✓ allowedDestinationRoots /your/project
✓ approvalUnavailable deny

要求：Node.js 22 或更高版本，DSH 0.1.5-rc.1 或更高版本（参见兼容性）。如果宿主包尚无法解析，请先启动一次 profile（dsh web），以便 DSH 链接它们，然后再次运行 doctor。

快速开始

从你想要处理的仓库启动 DSH，并用自然语言请求批量工作：

为 src/ 中的每个模块编写一份一致的 Markdown 规范。先给我看三个样本。
你不必说“Ditto”，也不必学习任何工具名称。当一个请求涉及整个文件夹、许多相似模块、重复的转换，或值得审查的批量写入时，DSH agent 会通过 ditto skill 来路由它。单文件编辑和普通问题永远不会触发它。

想在安装任何东西之前先看看工作流程吗？该演示不需要模型，也不需要 API key：

npx dsh-ditto demo --headless   # terminal transcript, 16 synthetic modules
npx dsh-ditto demo              # the same batch in a local browser review page

示例：代码 → 规范

Ditto 的第一个用例是将 TypeScript/JavaScript 代码库转换为一致、有证据支持的 Markdown 规范。

1. 发现。 Ditto 扫描文件夹（跳过 node_modules、构建输出、测试、声明文件），并准确报告哪些内容在范围内、哪些被排除，以及原因。
2. 审查三个样本。 它挑选三个结构不同的模块——导出最多的模块、导入最多的模块、最小的模块——然后 agent 根据真实的、带行号的源代码证据为每个模块起草一份规范。你编辑 Markdown，直到它读起来符合你的期望。
3. 批准。 你批准的样本将成为其余批处理的标准。
4. 预览全部内容。 其余每个模块都会以相同风格获得一份规范。每一行事实性内容都会引用其来源的源代码行；源代码无法支持的任何内容都会被归入 Needs confirmation，而不是被陈述为事实。
5. 应用。 在你批准完整预览后，Ditto 会将 Markdown 文件写入单独的输出文件夹——绝不会写入你的源代码树，也绝不会覆盖现有文件。

一份写好的规范如下所示：

src/routes/webhooks.ts [ev_670d8499c08cf407cc283778]

- Source: src/routes/webhooks.ts

Purpose
- Provides registerWebhookRoutes. [ev_670d8499c08cf407cc283778]

Public API
- function registerWebhookRoutes(router, handlers): … [ev_670d8499c08cf407cc283778]

Needs confirmation
- Needs confirmation: Which event names does the webhook dispatcher accept at runtime? …

Evidence
- ev_670d8499c08cf407cc283778: src/routes/webhooks.ts:1-13

示例：文件组织与交付

文件工作流会在写入任何内容之前预览每一个拟议的副本和交付物：

C:\Users\me\Desktop\ftp-backup 中的 PDF 命名为 CODE_description.pdf。将它们复制到 D:\shared\PRO\PRO_FILES\CODE\CODE.pdf，显示每一个异常，并包含一个 CSV 映射、SHA-256 列表、SQL Server INSERT 文件和 ZIP。

配置文件所有者首先授权这些外部源根目录和目标根目录。相对工具路径永远不会使用该授权：它们仍然锚定到 workspaceRoot，并且 Code → Spec 仍然仅限工作区。
Recipe v2 可以匹配锚定的 RE2 表达式，例如 ^(?[^_]+)_.*\.pdf$，将 {match.code} 替换到安全的嵌套目标中，并将不匹配项、不安全捕获、无效名称和冲突保留为可见的逐项异常。ditto_revise_rule 会一次性更改规则并重新生成整个计划；ditto_revise 仍用于有意的一次性修正。

在批准之前，ditto_manifest 可以将完整映射导出为 CSV、JSON 或 Markdown，ditto_artifact_review 会公开每个 sidecar 经过审查的确切字节。支持的 sidecar 包括清单、校验和，以及带有已验证标识符和转义字面量的安全 SQL INSERT ... VALUES 文本。Ditto 从不连接数据库或执行 SQL。可选的确定性、流式 store-only ZIP 仅根据经过审查的输出允许列表构建，绝不通过遍历目标文件夹来构建。Classic-ZIP 限制会被显式强制执行（最多 65,535 个条目且小于 4 GiB）；归档崩溃恢复仅采用由持久写入意图所覆盖的确切哈希。

Apply 会在新文件夹中创建副本和经过审查的交付物。原始文件绝不会被移动或修改；现有文件绝不会被覆盖；保存的声明式 recipe 可以在下一批中重复使用。

工作原理

User
↓  "specs for every module, show me a few first"
DSH agent
↓  routes through the ditto skill
Ditto native tools (ditto_spec_create, …_module, …_submit, …_approve, …_apply, …)
↓  bounded evidence in, validated JSON drafts out
Deterministic core
↓  discovery · evidence ids · citation validation · rendering · hashes · digests
Preview → Human approval → Apply

- Agent 负责思考；Ditto 负责记录。 Ditto 本身从不调用模型，也从不存储模型 API 密钥。它向 DSH agent 提供有界的、带行号的证据，并且只接受结构化草稿，其中的每一项声明都必须引用该证据。
- 批次是持久的。 每个计划和批次都会随修订版本和摘要一起保存。编辑样本、指令、命名规则、sidecar 或归档都会改变经过审查的身份。中断的复制会记录持久意图，并且在恢复时只能采用确切经过审查的哈希；已完成的项目绝不会被重做或覆盖。
- 该 skill 是路由层，而不是产品。 skills/ditto/SKILL.md 是一个你可以直接阅读的普通文件；插件注册的正是该文件。完整的工具参考文档由 docs/TOOLS.md 中的实时 schema 生成。

为什么选择 Ditto

仅靠提示词的批处理工作往往会偏离方向、遗漏文件、格式不一致、编造细节、过早写入，并在会话中断时丢失进度。Ditto 为你提供：

- 代表性样本用于校准，而不是把格式重复解释 30 遍
- 对这些样本进行人工审查，你的编辑会被带入批次的其余部分
- 在写入任何内容之前，对每个项目进行完整预览
- 每项主张都有来源证据，例外集中收集在一处
- 明确批准是硬性门槛，而非建议
- 安全应用：仅复制和新建文件，重新校验哈希，不覆盖
- 中断后恢复，不产生重复工作

Ditto 不会让模型变得更聪明，也无法保证规范在语义上正确。它让批量操作可审查、一致且安全可应用。

设计即安全

你的源文件保持原样。在批准之前不会批量写入任何内容。Ditto 不会执行你的源代码。Ditto 不会存储你的模型 API 密钥。

以下每项保证都由代码强制执行，并由自动化测试覆盖；对应关系见 docs/SAFETY.md。

- 预览对源文件或输出执行零写入；仅保存本地审查元数据
- 源文件以文本形式读取，绝不执行、导入、修改、移动或删除
- 输出写入单独的文件夹；现有的目标、附属文件或归档绝不会被覆盖
- 每次应用都会重新校验源哈希以及确切的计划修订/摘要；源已更改或审查已过期都会被拒绝
- 路径遍历、符号链接/交接点逃逸、重复、大小写不敏感、祖先/后代以及产物冲突都会被拒绝
- 仅当配置文件所有者授权每个源/目标角色时，文件组织才能使用外部根目录；Code → Spec 和状态保留在 workspaceRoot 内
- 附属 SQL 是确定性文本，带有经过验证的标识符和转义字面量；Ditto 绝不连接数据库或执行它
- 已完成的项目在恢复时绝不会重新运行或被覆盖；只有先前记录的意图可以采用哈希完全一致的崩溃残留
- 源无法支持的主张会成为 需要确认 的问题，而非事实
- 当 approval: host 时，只有 allowed-once 会继续。拒绝和取消始终为拒绝；缺少审批服务/代理身份或宿主 unavailable 时默认拒绝。对话式回退需要配置文件所有者设置 approvalUnavailable: agent，且不构成人工批准的证明
- 无遥测，除 DSH 本身外无网络访问，不存储 API 密钥

插件架构

Ditto 是 DSH 插件，而非 Markdown 技能。该包包含：

| 层 | 它是什么 |
|---|---|
| Cordis 服务 | dsh-ditto/dsh — 一个服务，在宿主的公共 skills 和 tools 服务上注册技能和工具；卸载该捆绑包会移除所有内容 |
| 技能 | skills/ditto/SKILL.md — 代理读取的路由层（模型和用户均可调用） |
| 原生工具 | 17 个类型化工具：9 个用于 Code → Spec，8 个用于文件组织（参考） |
| 确定性核心 | 发现、RE2 匹配、安全路径渲染、证据/引用验证、附属文件和 ZIP 渲染、哈希、修订/摘要门槛、持久状态 |
| 本地审查页面 | 一个可选的仅限回环的浏览器页面，供演示和 dsh-ditto serve 使用 |
Ditto 仅依赖公开的 DSH API（@deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-skill），不对 DSH 做任何补丁。Recipe v2 使用 re2-wasm 进行线性时间匹配。配置（workspaceRoot、stateRoot、仅文件的外部允许列表、审批策略、分页限制）通过 profile 的 cordis.patch.yml 设置；参见 docs/ARCHITECTURE.md。

兼容性

| Ditto | DSH | Node.js | 状态 |
|---|---|---|---|
| 0.2.0 | 0.1.5-rc.1, 0.1.5-rc.2 | 22, 24 | 候选发布版 — 构建、测试、组件、tarball 以及真实隔离 profile 的安装/启动/doctor 门禁全部通过 |
| 0.2.0 | 0.1.6-alpha.1 | 22, 24 | 金丝雀 — 非阻塞 CI |
| 0.1.0 | 0.1.5-rc.1, 0.1.5-rc.2 | 22, 24 | 受支持的历史版本 |

DSH 发展迅速；关于具体测试内容以及如何报告破坏性变更，参见 docs/COMPATIBILITY.md。

开发

git clone https://github.com/darrien1998/dsh-ditto.git
cd dsh-ditto
npm ci
npm run build
npm test                 # unit, core safety, UI, plugin contract, CLI
npm run smoke:dsh        # real Cordis + ToolRuntime + SkillRegistry component host
npm run smoke:tarball    # pack, clean-install, mount, run the installed CLI
npm run smoke:profile    # real dsh plugin add into an isolated DSH_HOME (needs dsh + pnpm)

更多内容参见 docs/DEVELOPMENT.md。

贡献

欢迎提交 issue 和 pull request — 参见 CONTRIBUTING.md。不错的入手方向：为 Python、Java、C# 或 Go 编写语言适配器（接缝很小且有文档说明）、自定义 spec 模板、更好的样本选择、UI 本地化以及文档示例。请留意 good first issue 和 help wanted 标签。

路线图

参见 docs/ROADMAP.md。简而言之：保持 Ditto 小巧、易懂、安全、DSH 原生且审查优先。不做后台监视器，不做定时运行，不做无人值守的批量写入。

许可证

MIT