Claude Code 委派 wanwulizhi/dsh-claude-code-sdk

dsh-claude-code-sdk

把自包含的编码任务委派给本机 Claude Code 执行，结果回传给 DSH。DSH 当 leader，Claude Code 当 worker。

走官方 Claude Agent SDK（@anthropic-ai/claude-agent-sdk 的 query()），不是简单 shell 调用，因此能拿到结构化的执行结果：最终文本、sessionId、token 用量，以及 worker 实际调用过的工具列表。

目标宿主是 DSH 0.2.x。

它解决什么问题

DSH 自己有一套工具循环，适合「边聊边做」。但有些任务更适合交给一个独立智能体整段跑完：

- 一次要改十几个文件、需要反复读代码再改的重构
- 需要自己跑测试、看失败、再修的长循环
- 你希望「派出去干完再回来」，而不是每一步都在主对话里来回确认

这类任务交给 Claude Code 更合适：它有自己的 Read/Edit/Bash/Grep/Glob 工具链和完整智能体循环。插件负责把任务交出去、把结果收回来。

关键特性：内层 Claude Code 的工具调用不会进入外层 DSH 会话的上下文。它读了二十个文件、跑了十次命令，回给 DSH 的只有一段最终结论。主对话不会被中间过程撑爆。

工作原理

┌──────────────────────────────────────────┐
│ DSH（leader） │ │ 用户：「让 Claude 去把 xxx 重构了」 │ │ ↓ 模型决定调用 claude_code 工具 │ │ ┌────────────────────────────────────┐ │ │ │ dsh-claude-code-sdk │ │ │ │ 1. 从 exec.agent.session 读历史 │ │ │ │ 2. 拼成 transcript + 任务文本 │ │ │ │ 3. query() 交给 Claude Agent SDK │ │ │ └────────────────────────────────────┘ │ └──────────────────┬───────────────────────┘ │ stdio ┌──────────────────▼───────────────────────┐ │ Claude Code（worker） │ │ 自己的 agent 循环：Read → Edit → Bash │ │ → 看测试结果 → 再改 → … │ │ 这些中间过程 DSH 看不到 │ └──────────────────┬───────────────────────┘ │ 只回一段最终文本 + 用量 ┌──────────────────▼───────────────────────┐ │ DSH 拿到 { output, sessionId, tokens } │ │ leader 负责 review 和验收 │ └──────────────────────────────────────────┘

插件内部对消息流的处理：

- msg.type === "assistant" → 累加 text 块、把 tool_use 的工具名收进集合
- msg.type === "result" → 取 total_cost_usd 与 usage.input_tokens / usage.output_tokens；正文为空时回退 msg.result
- 失败时按 msg.result ?? msg.error ?? msg.subtype 提取原因

与 zhangjunjesse/dsh-claude-code 的区别

实现思路来自 dsh-claude-code。核心逻辑（消息流处理、Config 字段、输出 schema、技能文案结构）与之等价，以下五点是有意改动：

| 差异 | 原因 |
| peer 范围是 >=0.2.0-rc.2 <0.3.0-0 | 上游钉在 ^0.1.0-rc.6，在 DSH 0.2.x 上装不进去 |
| allowedTools 有默认白名单，含 Bash / PowerShell | 上游留空时，acceptEdits 下所有 shell 命令会被拒，worker 实际干不了活（见「权限模型」） |
| 注入当前 DSH 对话历史 | 让 worker 知道前面聊了什么，不必每次重述背景 |
| 不内置可执行文件路径 | 由 SDK 解析自带的 CLI，跨平台可用；需要时可显式指定 |
| 技能里补充了权限与成本的实操说明 | 上游文案假设的是订阅计费，对第三方中转不成立 |

两个插件都注册 claude_code 这个工具名，同时安装会冲突（tool "claude_code" is already registered）。二选一。

安装

前提

- DSH 0.2.x（@deepseek-ai/dsh-tools >= 0.2.0-rc.2）
- 本机已安装并登录 Claude Code（claude 能跑起来）
- Node.js >= 22.19.0

方式

收录到 awesome-dsh-plugin 后，可在 DSH 的 设置 → 插件 里搜索安装，或：

dsh plugin --profile web add dsh-claude-code-sdk

安装顺序是「npm 包 → 作者提供的 GitHub Release tarball → 整仓 GitHub 源码」。本包目前只提供源码，因此走最后一条：克隆仓库后安装依赖。

首次安装需要拉取对应平台的 Claude Agent SDK 二进制，约 280 MB，耗时取决于到 GitHub 与 npm 的网络。

验证装好了

在 DSH 里发一句：

用 claude_code 工具执行：task = "只回复两个字：正常"

返回「正常」即通。

如果工具没出现，先确认 DSH 是否真的重启了——插件在启动时装载，改完配置不重启不生效。

快速开始

不需要特殊语法。工具注册后，DSH 的模型会在合适的时候自己调用；你也可以直接点名。

点名调用

用 claude_code 工具执行：task = "在 D:\proj 下把 utils.js 里的 callback 写法改成 async/await，改完跑 npm test 确认通过"

只说意图，让技能接管

让 Claude Code 去重构 src/parser.js，拆成三个函数，保持现有测试全绿

插件注册的 claude-code-delegation 技能会告诉模型什么时候该派活、任务该怎么写、结果怎么质检。

多轮迭代

第一次调用返回里有 sessionId。第二轮把它作为 resume 传回去，Claude Code 记得上一轮读过的文件，不用重新读一遍：

用 claude_code 继续上次 sessionId=76ab34e8-... 的工作，把刚才那两个测试失败修掉

任务描述怎么写

Claude Code 只能看到任务文本 + 注入的对话历史，看不到文件内容、也看不到 DSH 的工具输出。所以任务里要写清四件事：

1. 目标：一句话说清交付什么
2. 文件：相关文件的绝对路径（派活前先自己 grep 摸清结构，把结论写进去）
3. 约束：构建/验证命令、禁止事项、风格要求
4. 验收：做到什么算完成

对比：

❌ 把上面那个文件改一下（不知道"上面"是哪个，也不知道要改成什么）

✅ 把 D:\proj\src\utils.js 里的 debounce 函数改写成支持 cancel 方法。
要求：保持现有导出名不变，不引入新依赖，改完执行 npx vitest run utils 确认通过。

工具 claude_code

参数

| 参数 | 类型 | 必填 | 说明 |
| task | string | ✅ | 完整、自包含的任务描述 |
| cwd | string | | 工作目录。默认取配置值，再退到 DSH 进程目录 |
| model | string | | 本次覆盖模型（sonnet / opus / haiku 或完整 id） |
| permissionMode | string | | default / acceptEdits / bypassPermissions / plan / dontAsk |
| maxTurns | integer | | 本次最大 agentic 轮数 |
| allowedTools | string[] | | 预授权的内置工具（白名单放行，不是限制） |
| resume | string | | 上次返回的 sessionId，续接同一会话 |
| effort | string | | 思考强度 low / medium / high / xhigh / max |
| maxThinkingTokens | integer | | 思考 token 预算 |
| includeHistory | boolean | | 是否注入 DSH 对话历史，默认取配置值 |

返回

{
"ok": true,
"output": "最终文本", "sessionId": "76ab34e8-0069-4c2c-9a5b-33ee5ac8c812", "costUsd": 0.0700, "inputTokens": 12020, "outputTokens": 2,
"toolsUsed": ["Write", "PowerShell"]
}

toolsUsed 是 worker 实际调用过的工具名集合，可以用来判断它有没有真的动手（而不是只回了一段话）。

渲染到对话里时只显示 output，不显示金额和 token 数。

配置

默认值写在插件自带的 cordis.patch.yml。要覆盖就在 profile 的 cordis.patch.yml 里按 id 改：

- id: claude-code-sdk
config:
model: sonnet
permissionMode: acceptEdits
maxTurns: 100
timeoutMs: 600000
effort: high
cwd: '/path/to/project'
allowedTools: [Bash, PowerShell, Read, Write, Edit, Glob, Grep]
includeHistory: true
historyMaxMessages: 20
historyMaxChars: 12000
可选：指定某个 claude 可执行文件；留空则由 SDK 解析自带的 CLI pathToClaudeCodeExecutable: '/path/to/claude'

字段一览

| 字段 | 默认值 | 说明 |
| model | sonnet | 模型别名或完整 id。若 ~/.claude/settings.json 里配了模型映射，这里写的是映射前的别名 |
| permissionMode | acceptEdits | 权限模式，详见「权限模型」 |
| maxTurns | 100 | 单次委派的最大 agentic 轮数。到顶会报 Reached maximum number of turns |
| timeoutMs | 600000 | 工具级超时（10 分钟），同时作为 DSH 的工具超时声明 |
| cwd | 未设置 | 工作目录。建议显式指定，否则会落在 DSH 进程目录 |
| allowedTools | 见下 | 预授权工具白名单。默认 Bash, PowerShell, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch |
| pathToClaudeCodeExecutable | 未设置 | 留空时由 SDK 解析自己捆绑的 CLI（claude-agent-sdk-<platform>/claude.exe） |
| effort | high | 思考强度 |
| maxThinkingTokens | 未设置 | 思考 token 上限，与 effort 二选一即可 |
| includeHistory | true | 是否注入 DSH 对话历史 |
| historyMaxMessages | 20 | 最多注入最近多少条消息 |
| historyMaxChars | 12000 | 注入历史的字符预算 |

工具参数与配置同名时，工具参数优先（args.x ?? config.x）。注意空数组不会被默认值覆盖——[] 是有效值，?? 只对 null / undefined 生效，所以显式传 allowedTools: [] 就是「什么都不预授权」。

权限模型

这是最容易踩坑的地方，单独讲。

非交互模式没有「询问用户」

SDK 在非交互模式下运行时，没有 canUseTool 回调去问人。当 permissionMode 是 acceptEdits 时：

- 文件编辑（Write / Edit）→ 自动批准
- 其余工具（Bash / PowerShell 等）→ 直接拒绝，返回 requires approval，命令根本不执行

模型看到拒绝后通常会重试几次，最后耗尽 maxTurns 报错。表现出来就是「卡了很久然后失败」，而不是明确的权限错误。

实测对比

同一台 Windows 机器，同一个任务「执行 node --version 并把原始输出回报」：

| 配置 | 结果 |
| acceptEdits，allowedTools 为空 | 命令未运行；worker 回复「该命令需要你批准才能执行」；反复重试至 36 秒后报 Reached maximum number of turns (6) |
| acceptEdits + allowedTools: [Bash, PowerShell] | 9.6 秒返回 v22.22.2 |
| bypassPermissions | 9.4 秒返回 v22.22.2 |

结论：allowedTools 留空等于让 worker 只能改文件、不能跑命令。建不了项目、跑不了测试、执行不了 git，实际干不了活。

本插件的默认选择

把 shell 与读写检索工具放进默认白名单：

["Bash", "PowerShell", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]

这比开全局 bypassPermissions 保守：文件编辑照旧自动批准，shell 显式放行，其他工具仍然拒绝。

想更严格 / 更宽松

更严格：只读，不写不执行
allowedTools: [Read, Glob, Grep]

完全不给：只让它读任务、回文本（几乎没实用价值，仅用于验证连通）
allowedTools: []

更宽松：不推荐，等于不做任何限制 permissionMode: bypassPermissions

Bash 与 PowerShell 同时列出是刻意的：Windows 上 Claude Code 用 PowerShell，其他平台用 Bash。多列一个不存在的工具不会报错。

对话历史注入

默认开启。

数据通路

DSH 0.2.x 里，dsh-agent-loop 在执行工具时把 agent 实例塞进了执行上下文：

const agent = ctx.agents.requireInitiator();
exec = { callId, name, arguments, agent, signal }

而这个 agent 带着活会话，所以插件可以这样读：

exec.agent.session.deriveMessages()

返回的是与发给模型完全一致的消息数组（只读、纯派生，不修改会话）。

过滤规则

消息的 role 有 system / developer / user / assistant / tool，content 里的块类型有 text / reasoning / tool-call / tool-addition / tool-removal。

插件只取 user 与 assistant 的 text 块，其余全部丢弃：

| 丢弃 | 原因 |
| system | DSH 自己的系统提示，又长又和任务无关 |
| developer | 工具注册变更（tool-addition / tool-removal），纯噪音 |
| tool | 工具结果，体量大且通常无用 |
| reasoning 块 | 思考过程 |
| tool-call 块 | 工具调用记录（名字和参数） |

末尾那条「决定调用 claude_code」的 assistant 消息也会被去掉——对 worker 没有价值。

实际拼出来的样子

DSH 会话历史（背景上下文）

以下是本次 DSH 对话此前的记录，供你理解背景、用户偏好和已经做过的决定。
这不是你要执行的任务；你的实际任务在最后。

【用户】我这个项目的内部代号是 ORION-7，记住。

【助手】好的，已记住代号 ORION-7。

【用户】部署脚本放在 D:/deploy 目录下。

当前任务

把 D:/deploy 下的 build.sh 改成支持 --dry-run 参数。

截断策略

先按 historyMaxMessages 取最近的 N 条，再按 historyMaxChars 从新到旧累加：

- 超出字符预算时，从最早的消息开始丢
- 如果单条就超预算，截断保留（加 …（已截断）），而不是整段丢弃
- 被丢弃的条数会写在 transcript 里：（更早的 N 条消息已省略）

注意条数上限通常比字符上限更早生效。默认 20 条 × 中位数 700 字符 ≈ 14000 字符，已经超过 12000 的字符预算，实际生效约 16 条。

边界

- 历史是只读背景，不含文件内容和工具输出。相关文件的绝对路径仍然必须写进 task。
- 跨越很多轮的旧约定可能被截掉，关键约束要在任务里重述一遍。
- 读取失败（取不到 session、方法不存在、抛异常）一律静默降级为「不注入」，不会因为读历史把委派搞挂。

成本影响

见下节「成本与计费」。

成本与计费

实测 token 构成

用 SDK 直接探 usage，两档不同长度的文本反推：
| 输入文本 | input_tokens |
| 0（纯任务） | ≈ 12,100 ← Claude Code 自身的固定开销 |
| 5,044 字符 | 14,570 |
| 20,037 字符 | 21,907 |

斜率约 489 tokens / 千中文字符（≈ 2 字符/token）。反推得到固定开销 ≈ 12,100 tokens——那是 Claude Code 自己的系统提示（工具说明、行为规范），不注入历史也存在，无法通过配置消除。

历史注入的增量

| 场景 | 注入字符 | 注入 tokens | 总 input | 相对增幅 |
| 不注入 | 0 | 0 | 12,100 | 基线 |
| 短对话（20 条共 3,500 字符） | 3,500 | ~1,700 | 13,800 | +14% |
| 长对话（撞 12,000 字符上限） | 12,000 | ~5,900 | 18,000 | +49% |

真正的成本大头

历史注入只是小头。更大的开销来自：

- Claude Code 自身固定开销 12k tokens / 次
- 它自己的多轮循环：每轮都重发整个上下文。10 轮任务 ≈ 180k input tokens
- 读大文件：一次读 5,000 行就是 +20k tokens

关于 costUsd

costUsd 来自 SDK 的 total_cost_usd，按 Anthropic 官方价目折算。如果 ~/.claude/settings.json 把 ANTHROPIC_BASE_URL 指向了第三方中转，这个数字不代表真实花费，只反映 token 量级。渲染时只输出正文，不展示金额。

省成本的建议

| 场景 | 建议 |
| 改一行、问个技术问题 | 传 includeHistory: false |
| 需要接上下文 | 保持默认 |
| 特别在意成本 | historyMaxMessages: 8、historyMaxChars: 6000 |
| 大重构、跨几十轮 | 可放到 historyMaxMessages: 40，但要接受多轮乘法 |

不建议把 historyMaxChars 调到 30,000 以上——每次委派的基线成本会翻倍，而历史越长、有用比例越低。

故障排查

工具列表里没有 claude_code

1. 确认 DSH 真的重启过（插件在启动时装载）
2. 检查 profile 的 package.json 里 dsh.profile.bundles 是否包含本包
3. 看 %APPDATA%\DSH Desktop\lifecycle-events\startup.jsonl 有没有 profile-composition 失败

注意：DSH 的启动日志不记录插件明细，failOnStartupError: false 下插件加载失败是静默的。最可靠的验证方式是发一条消息，然后看会话文件里 request/header 的 tools 数组——那才是真正注册成功的清单。

报 requires approval 或反复重试到 maxTurns

需要的工具不在 allowedTools 白名单里。把该工具名加进去，或临时用 permissionMode: bypassPermissions。

报 Reached maximum number of turns

任务太大，或 worker 在某个被拒的工具上反复重试。前者调大 maxTurns，后者按上一条处理。

返回空

插件会抛 claude_code returned no output。常见原因是任务描述太模糊，worker 只回了一句空话或直接放弃。把目标和验收标准写具体。

中文输出乱码

检查 cwd 下的文件编码，以及终端的代码页。插件本身按 UTF-8 传递，不额外转码。

tool "claude_code" is already registered

同时装了 dsh-claude-code。卸载其中一个。

已知限制

- 工具名 claude_code 与 dsh-claude-code 冲突，二者不能同时安装。
- 依赖的 SDK 平台包体积约 280 MB，首次安装较慢。
- 依赖 DSH 0.2.x 的 exec.agent.session.deriveMessages() 读取历史；该接口变化时历史注入会静默降级（不影响委派本身）。
- 非交互模式下无法进行交互式权限确认，只能靠 allowedTools 预授权。
- 一次调用只返回最终文本，中间过程不可见。需要看过程就把 maxTurns 调小、让它分段交付。

安全说明

- 插件本身不发起任何网络请求，也不读写凭据。网络访问全部由 Claude Code 及其 SDK 完成。
- 插件会读取当前 DSH 会话的 user / assistant 文本并写进给 worker 的 prompt。如果对话里有敏感信息，用 includeHistory: false 关闭。
- allowedTools 决定 worker 能做什么。默认白名单包含 shell，等于给了 worker 在 cwd 下执行命令的能力——请只在你信任的目录里使用。
- bypassPermissions 会关闭全部限制，仅在你完全清楚后果时使用。

开发与本地联调

git clone https://github.com/wanwulizhi/dsh-claude-code-sdk
cd dsh-claude-code-sdk
npm install

本地联调：把目录放到 ~/.dsh/profiles/<profile>/local-plugins/ 下，在 profile 的 node_modules 建目录联接指向它，并在 profile package.json 的 dsh.profile.bundles 与 dependencies 里登记。

自检方式（不启动 DSH，直接用真实校验函数跑一遍注册）：

import { assertSupportedJsonSchema } from '@deepseek-ai/dsh-tools';
const mod = await import('./lib/index.js');
const cfg = mod.Config({ cwd: process.cwd() });

let tool, skill;
mod.apply({
tools: { register: (d) => { assertSupportedJsonSchema(d.output.schema); tool = d; return () => {}; } },
skills: { register: (s) => { skill = s; return () => {}; } },
}, cfg);

console.log(tool.name, Object.keys(tool.parameters.properties), skill.name);

这样能验证 schema 合法性、参数表、技能注册，而且不需要真实 DSH 实例。

License

MIT