b2ornot2b/dsh-claude-code

dsh-claude-code

Claude Code 作为 DeepSeek Harness 的一等公民。

三个 cordis 插件，让 dsh 组合能够打开、驱动、监视并拆除真实的
Claude Code 会话——Claude Code 的权限
提示、澄清问题和计划审查被路由到 dsh 自身的人类介入（human-in-the-loop）接缝中，
会话所做的一切都被镜像到 dsh 会话日志中，供 UI 渲染。

有两件事它不是。它不是一次性的“让 Claude 写这个函数”调用——harness 已经为此提供了
@deepseek-ai/dsh-subagent-claude-code，而本集成刻意不替代它。它也不是重新实现 Claude Code
agent 循环的封装：CLI 保留自己的转录、自己的压缩和自己的工具。本仓库构建的是两个系统之间的
接缝。

状态：完整且经过生产验证。 全部八个阶段均已完成。该集成通过真实的 dsh Web UI 在
13 步验收测试中端到端驱动，每一步提示都由人工手动应答，并且它拥有针对真实 Claude Code
子进程的 654 个离线测试（39 个文件）加上 49 个可选启用的实时测试（33 个文件）。

| 从这里开始 | |
|---|---|
| 🚀 docs/QUICKSTART.md | 从零到“我的 dsh agent 刚刚把任务委托给了 Claude Code” |
| 🔧 docs/TROUBLESHOOTING.md | 我们实际遇到的每一种失败模式，以症状为先 |

你需要什么： Node.js >= 20、pnpm，以及可用的 claude CLI 登录。然后
pnpm install && pnpm run build && node examples/delegation-demo/run.mjs 就是全部验证——
完整路径见快速入门，包括挂载到真实的 dsh
profile 中。

你需要自备 Claude Code 访问权限。 需要 claude.ai 订阅登录（claude auth login）
或 Anthropic API 密钥；本项目既不提供、也不代理、也不共享这两者。

分发说明。 Anthropic 的 Agent SDK 条款规定，第三方开发者未经事先批准，不得在自己的产品中
提供 claude.ai 登录或订阅速率限制。在你自己的机器上针对你自己的订阅运行属于正常使用；
发布一个将其他人的 Max 套餐指向它的产品，才是该说明所指的情况。如果你要再分发基于此构建的
东西，请配置 auth: 'api-key'（配合 ctx.credentials）。

未发布到 npm。 三个包都是 private: true，并保留
@deepseek-ai/dsh- 名称，纯粹是为了让上游合并到 harness monorepo 时是一次
移动而不是重命名——我们并不拥有那个 npm scope。npm install
@deepseek-ai/dsh-claude-code 不会生效，也并非有意如此。在树外针对已发布的
@deepseek-ai/dsh-@0.1.0-rc.7 包进行开发。

你能得到什么

| | |
|---|---|
| 交互式会话 | 打开会话、发送后续消息、引导、打断、恢复、分叉。会话的生命周期长于打开它的那次调用。 |
| 人在回路中，接入 dsh | Claude Code 的 canUseTool 提示变为 ctx.approval.request()；AskUserQuestion 变为 ctx.userQuestions.ask()；ExitPlanMode 变为计划审查，使用 dsh 自己的计划模式约定。 |
| 可读的转录记录 | 每个会话都被镜像到一个真实的 dsh Session 日志中——轮次、步骤、流式文本和推理块、工具调用和结果——与 Claude Code 会话共享同一个 id。 |
| 面向模型的委托 | 七个 claude_code_ 工具——open / send / wait / status / list / cancel / close——使 dsh 智能体的模型可以将编码工作委托给 Claude Code 并读回答案。 |
| 可轮询的等待，而非超时 | 因人类尚未点击批准而未完成的轮次是一个值，而不是错误：claude_code_wait 默认为 60 秒，并以 status: 'running' 加上 pending_ask_details 来 RESOLVE，其中指明工具以及此人正在阅读的确切句子。渲染出的文本告诉模型继续轮询，而不是取消并重新打开。 |
| 人类决策回执 | 已解决的询问以 human_decisions 返回，每个都标记为 decided_by: 'human' 或 'policy'——因此智能体可以区分“某人拒绝了此操作”和“超时拒绝了此操作”，而不是根据是否发生了工具调用来推断同意。 |
| 能自我解释的错误 | SESSION_LIMIT 拒绝会附带一份所有活动会话的清单——cwd、状态、年龄、空闲时间、每个会话被什么阻塞，以及哪个是可以安全关闭的——因为该上限是服务范围的，而槽位可能被调用者从未打开过的会话占用。claude_code_list 按需暴露同样的视图。 |
| 作为 dsh 作业的后台工作 | claude_code_open({ background: true }) 将该会话注册为一个 ctx.jobs 作业：job_list / job_output / job_kill 都对其有效。 |
| 由 CC 支持的 dsh 智能体 | 将 Claude Code 会话发布为一个 ctx.agents 条目，这样人类就可以像对待任何其他智能体一样，在 dsh UI 中与它交谈。 |

架构

该 harness 的能力准则是 Definition / Provider / Consumer。此集成是一个接缝和两个消费者——dsh-claude-code 既是定义又是提供者，因为 Claude Agent SDK 就是后端，且没有计划替代的提供者。

graph TB
subgraph dsh["dsh composition (cordis)"]
approval["ctx.approvaldsh-user-approval"]
questions["ctx.userQuestionsdsh-user-questions"]
sessions["ctx.sessionsdsh-session"]
agents["ctx.agentsdsh-agent"]
jobs["ctx.jobsdsh-jobs-local"]
tools["ctx.toolsdsh-tools"]
end

subgraph repo["this repo"]
seam["@deepseek-ai/dsh-claude-codectx.claudeCode — the seamdefinition + providerthe only package that mayimport the Claude Agent SDK"]
toolpkg["@deepseek-ai/dsh-tool-claude-codeconsumer: seven claude_code_ tools"]
agentpkg["@deepseek-ai/dsh-claude-code-agentconsumer：Agent 适配器"]
end

cli["Claude Code CLI 子进程自有 transcript、自有工具、自有压缩"]

toolpkg -->|"inject: tools, claudeCode"| seam
agentpkg -->|"inject: agents, claudeCode, sessions"| seam
toolpkg --> tools
agentpkg --> agents

seam -->|"ask 通道（§4）canUseTool / AskUserQuestion / ExitPlanMode"| approval
seam --> questions
seam -->|"镜像（§5），只写"| sessions
toolpkg -->|"background: true"| jobs

seam |"@anthropic-ai/claude-agent-sdk流式输入，永不结束"| cli

这张图编码了两条规则，二者都是承重的：

- 指向 ctx.sessions 的箭头是单向的。 镜像只写。Claude Code 会话中没有任何东西由
dsh 日志驱动，因为 Claude Code 拥有自己的历史——这就是为什么 replay、seed-fork 和
deriveMessages() 对于 CC 支持的会话全都无效。
- 只有 seam 导入 SDK。 两个 consumer 仅依赖 seam 的类型，并且
tests/composition/composition.spec.ts 对全部三个包构建后的 lib/types//.d.ts
断言：没有任何 SDK 说明符出现在类型位置。

三个包

| 包 | 提供 | 读取 |
|---|---|---|
| packages/claude-code | ctx.claudeCode — 会话、ask 通道、镜像、配置、预热池 | seam + provider |
| packages/tool-claude-code | claude_code_open / _send / _wait / _status / _list / _cancel / _close | consumer |
| packages/claude-code-agent | ctx.claudeCodeAgents — CC 支持的 ctx.agents 条目 | consumer |

快速开始

docs/QUICKSTART.md 是完整路径——前置条件、演示，以及
使用 scripts/install-into-dsh-profile.sh 挂载到真实的 dsh profile。简版如下：

委托演示

验收产物。一个替身的“DeepSeek agent”通过 claude_code_open 将真实的编码任务委托给
Claude Code，脚本会打印镜像会话的完整事件时间线以及被创建的文件。

pnpm install
pnpm run build                            # Loader 导入 lib/，所以先构建
node examples/delegation-demo/run.mjs     # 需要已登录的 claude CLI

它通过真实的 cordis Loader 启动 examples/delegation-demo/cordis.yml
——没有测试替身，没有 mock 的 SDK——在一个自动应答器下运行委托，该应答器会记录它授予的每一项权限，
验证所创建文件的确切内容，并以 0 退出。关于标志，请参阅它的 README；
关于运行期间会发生什么，请参阅快速开始。

自行挂载

每个包一行 cordis.yml——最小形态：

- id: claude-code
name: '@deepseek-ai/dsh-claude-code'
config:
defaults: { model: claude-haiku-4-5-20251001, settingSources: [] }

- id: tool-claude-code           # 面向模型的委托工具
name: '@deepseek-ai/dsh-tool-claude-code'

- id: claude-code-agent          # 由 CC 支持的 dsh 代理
name: '@deepseek-ai/dsh-claude-code-agent'

@deepseek-ai/dsh-jobs-local 和 @deepseek-ai/dsh-tool-jobs 是
background: true 所必需的；dsh-user-approval / dsh-user-questions 是可选的，但一个
没有询问目标的会话会拒绝每一次工具调用，按设计采用故障关闭（fail-closed）策略。

挂载到 dsh profile 中则不同——这些行必须位于 insert: 之下，并且
该 profile 的 cordis.patch.yml 可能是一个已部署的产物，会还原你的编辑。请使用
scripts/install-into-dsh-profile.sh，并将这些行放在
scripts/rows.snippet.yml 中，并先阅读
快速开始第 4 步。

测试矩阵

pnpm run typecheck   # 每个包 + 每个 spec，NodeNext strict，skipLibCheck: false
pnpm run build       # 每个包执行 tsc -b -> lib/index.js + lib/types/index.d.ts
pnpm test            # 构建，然后运行全部三个 vitest 项目。离线。
pnpm run test:live   # 可选启用：DSH_CC_LIVE=1，真实子进程，真实订阅

| 项目 | 它解析的内容 | 网络 / 子进程 | 内容 |
|---|---|---|---|
| unit | TypeScript 源码（通过 tsconfig 路径） | 无 | 每个包自己的 spec——伪造后端、录制的 fixtures、黄金转录 |
| composition | 通过真实 Loader 启动解析出的包的已构建 lib/ | 无 | cordis.yml 和 cordis-no-jobs.yml 验收测试：exports 映射、inject 列表、Config schema、无 SDK 的类型表面、干净释放 |
| examples | 作为真实子进程运行的 run.mjs | 仅实时 | 委托演示，端到端 |

这两个平面从不在同一个进程中相遇：模块单例的第二份副本会破坏 cordis
服务解析，因此源码平面和已构建平面的测试套件被刻意拆分为不同的
项目。

当前总计：39 个文件中共有 654 个离线测试（另有 33 个实时文件被收集并
跳过），以及这 33 个文件中的 49 个实时测试。

离线是默认行为，并将保持为默认行为。 pnpm test 不会启动任何子进程，也不会发起任何
网络调用；每个实时 spec 都是 describe.skipIf(!LIVE)，并且会被收集并跳过。
实时套件在隔离的临时工作目录中，以 claude-haiku-4-5-20251001 驱动一句话提示，
并且每个 spec 都会断言会话范围内的 pgrep 增量，以确保没有子进程比其测试存活更久。

有一个实时套件的行为是符合预期而非失败：
record-fixtures.live.spec.ts 在每次实时运行时重写三个镜像 fixture——这是
记录器在履行其职责，而 mirror-golden.spec.ts 则是检查该投影
相对于新录制内容是否仍然具有确定性。

构建： .tsbuildinfo 已被 gitignore，因此全新克隆可以正确构建。如果你删除
手动删除 lib/ 时，也要删除同级的 tsconfig.tsbuildinfo（或者运行 pnpm run clean，它等价于
tsc -b --clean）——否则 tsc -b 会认为它已是最新，不输出任何内容，依赖它的包就会以一连串令人困惑的 TS6305 报错失败。

上游缺口

以下所有内容都受阻于 SDK 或 dsh rc.7，而非本仓库中的工作。每一行都是一个经过深思熟虑、有据可查的立场——没有一行是我们跳过的待办事项。

| 缺口 | 影响之处 | 当前行为 | 如何解决 |
|---|---|---|---|
| Session.append() 上没有 ignorable | 镜像的 claude-code/compact 事件 | 自定义事件类型必须在其信封上携带 ignorable: true，否则旧版本构建会拒绝整个日志；append() 会自行构建并冻结信封 | 上游提供 append(type, data, { ignorable: true })。缓解措施已发布：mirror: { compaction: 'skip' }，以及在 seed/restore 边界处的 markEventIgnorable() |
| SDK 未暴露 cancel_queued | claude_code_cancel({ keep_queued: false })、agent.cancel({ keepInbox: false }) | CLI 声明了 interrupt_cancel_queued_v1，但在 SDK 0.3.233 中 interrupt() 不接受任何参数。在我们这一层进行模拟：在每个存活的轮次开始时重新中断，设有上限，并标记被停止的内容 | 一个能驱动所声明能力的 SDK 调用 |
| dsh 审批没有 'always' 结果 | UI 中的“始终允许此命令” | 结果词汇表为 allowed-once \| rejected \| cancelled \| unavailable，因此人类点击的任何操作都无法写入规则。规则来自 ask.rules 配置或 CcAskRules.add() | 一个 'always' 结果。届时 UI 路径距离一次 add() 调用仅一步之遥 |
| CC 自身工具的卡片无法表示 | 渲染 Claude Code 运行过的 Bash / Write / Edit / Read | tool/call 没有视图槽位，而卡片是通过工具注册表的名称查找来派生的——CC 的名称（Bash）未注册，而 dsh 的名称是小写的（bash）。这些投影已发布，纯净且经过测试，位于 packages/claude-code/src/cards.ts；不会向日志写入任何内容，因为它们所需的每一项输入都已在日志中持久化 | 在 ToolRegistry 上注册 presentation-only（提供呈现器，无 execute，从 schemas() 中排除），或在 viewFor() 中提供与名称无关的视图路径 |
| 仅循环的水瀑布是惰性的 | 任何为 CC 支持的 agent 挂接 agent/pre-step、agent/request、agent/request-error、tools/pre-execute、agent/turn-stopping 的插件 | 这些仅由 ReactLoopAgent / ctx.tools 派发，而 CC 支持的 agent 从不经过它们。已作为 INERT_DSH_MECHANISMS 导出，并附有文档化的替代方案 | 此处无解；这是一个诚实的架构后果 |
| AgentOptions 没有 setModel / maxTokens | 切换 CC 支持的 agent 的模型 | 模型更改通过包级别的 setModel() → query.setModel() 进行；maxTokens 从未被填充，因为 Claude Code 拥有自己的请求配置 | 此处无解 |
| 始终允许规则是我们的，不是 SDK 的 | 由本集成写入的规则 | 无头 canUseTool 从不写入 .claude/settings.local.json（已在 spike 中验证，使用 settingSources: [] 以及 ['local']）——因此我们的规则缓存与用户的交互式 CLI 是两个互不同步的存储 | 用于持久化 updatedPermissions 的 SDK 契约 |

这是横切性的，在基于此进行构建之前值得了解：dsh 中 CC 会话的会话日志是一条记录，而不是上下文。 Claude Code 会压缩自己的转录，而镜像不会重写以匹配，因此在压缩之后，镜像反而是更完整的历史，而 CLI 的实时上下文则是一个摘要。将二者视为可互换是一种范畴错误，而不是 bug。

与 harness monorepo 的关系

在本仓库中以树外方式开发——Phase 0 的 spike 证明了单纯的
@deepseek-ai/cordis@4.0.1 + dsh-@0.1.0-rc.7 安装可以以两种方式启动（裸 ctx.plugin()
以及 Loader + cordis.yml），并且在 skipLibCheck: false 下通过类型检查。这换来了快速
迭代，代价是失去了 monorepo 的免费关卡（文档同步、逐文件 100% 覆盖率、
组装快照套件），本仓库用自己的组合 + 实时套件替代了这些。

不过仍然遵循了 monorepo 约定，因此向上游合并是机械性的：

- 仅使用具名导出，绝不使用 export default（harness 事后分析 0001：默认导出
会静默丢弃插件的 inject 列表）；
- src/ → lib/ + lib/types/ 布局、exports 映射、schemastery Config；
- @deepseek-ai/cordis 在所有地方都是 peer 依赖——两份副本会破坏服务
解析；
- 全程使用精确锁定（@anthropic-ai/claude-agent-sdk@0.3.233、dsh-@0.1.0-rc.7）。

向上游合并路径。 将 packages/claude-code 移动到 packages/claude-code/claude-code/，
将 packages/tool-claude-code 移动到 packages/claude-code/tool-claude-code/，并将
packages/claude-code-agent 移动到 packages/claude-code/claude-code-agent/；将每个精确的
0.1.0-rc.7 锁定替换为 workspace:^；去掉 private: true 标志。剩余工作是
monorepo 自身的关卡（逐文件 100% 覆盖率、文档同步、针对模型可见工具表面的
组装快照场景）——这些都不需要在此处更改代码。现有的
@deepseek-ai/dsh-subagent-claude-code 保持原样：它是一次性委托，而本
集成是交互式补充，不是替代品。

文档

| 文档 | 内容 |
|---|---|
| docs/QUICKSTART.md | 从这里开始。 前置条件 → 构建 → 演示 → 挂载到真实的 dsh profile → 你的第一次委托 → 在 dsh UI 中回答提示 |
| docs/TROUBLESHOOTING.md | 本集成实际遇到的每一种故障模式：症状、原因、修复 |
| docs/phase1-api-contract.md | 事实来源。 完整的导出表面、每个阶段的修正与偏差，以及验证标准 |
| docs/spec-review-and-plan.md | 规范审查（SDK 差异 S1–S14、dsh 差异 D1–D16）、阶段计划、Phase 0 探针结果，以及 §8 项目完成状态 |
| docs/dsh-claude-code-integration.md | 本项目的原始设计规范 |
| spikes/ | Phase 0 探针脚本及其日志——一个独立的 npm 项目，不属于构建的一部分 |

许可与分发

许可。 MIT——参见仓库根目录下的 LICENSE；工作区 package.json 中声明了相同的许可。

分发说明。 Anthropic 的 Agent SDK 条款规定，第三方开发者未经事先批准，不得在自己的产品中提供 claude.ai 登录或订阅速率限制。在你自己的机器上通过此集成使用你自己的 claude.ai 订阅，属于正常使用。发布一个将他人的 Max 套餐指向它的产品，才是该说明所针对的情形——如果你要再分发基于此构建的东西，请配置 API 密钥认证（auth: 'api-key' + ctx.credentials），而不是提供订阅登录。参见 docs/dsh-claude-code-integration.md 的 §9。

不在 npm 上。 三个包均为 private: true。它们保留 @deepseek-ai/dsh-* 名称，只是为了上游合并时是移动而非重命名——本项目并不拥有该 npm 作用域，且 npm install @deepseek-ai/dsh-claude-code 预计无法正常工作。