project-hy/dsh-claude-delegate

dsh-claude-delegate

DeepSeek Harness（以下简称 DSH）工具插件：将边界清晰、自包含的编码子任务委派给本机 Claude Code 执行，并回收结构化结果。

插件安装后向 DSH 注册一个工具 claude_code 与一个监控面板。DSH 负责定义任务目标与验收标准，Claude Code 负责在指定工作目录内完成代码阅读、修改与验证。插件通过官方 Claude Agent SDK 驱动本机安装的 claude CLI，不提取、不转发任何 OAuth 凭据。

本文档依次说明功能特性、安装与配置、参数语义、运行机制、故障处置与开发方式。

---

目录

1. 功能特性
2. 系统要求与兼容性
3. 安装
4. 快速开始
5. 工具参数参考
6. 插件配置参考
7. 监控面板
8. 长命令实时输出通道
9. 内置技能
10. 安全与合规
11. 运行机制
12. 故障排查
13. 常见问题
14. 派生来源与改动说明
15. 开发与发布
16. 许可证

---

1. 功能特性

2. 系统要求与兼容性

3. 安装

推荐通过 DSH 插件命令安装（包内自带 dsh.bundle 接线清单，安装后自动接线）：

dsh plugin --profile <profile> add dsh-claude-delegate

等价的手动方式：

cd ~/.dsh/profiles
npm install dsh-claude-delegate

随后在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中确认存在以下接线：

- insert:
    - id: claude-code
      name: dsh-claude-delegate
      config:
        model: sonnet
        permissionMode: acceptEdits
        maxTurns: 100
        timeoutMs: 7200000

安装后需要重启 DSH。插件自带的接线为安全默认值：权限模式为 acceptEdits，且不预设代理；仅当本机出网 IP 被判定为数据中心 IP、Anthropic 返回 403 时，才需要自行配置 proxy。

从源码安装

npm install --legacy-peer-deps   # 直接 npm install 会因 dsh-system-prompt → dsh-invariants 的 peer 冲突失败
npm run build
cp -R lib/* ~/.dsh/profiles/<profile>/node_modules/dsh-claude-delegate/lib/

4. 快速开始

在需要委派的工作目录中调用工具：

{
  "task": "修复 src/parser.ts 中 parse() 对空输入崩溃的问题，并补充对应单元测试",
  "cwd": "/absolute/path/to/repo"
}

后台执行：

{
  "task": "将 src/ 全量迁移到新的 logger API，并确保 npm run build 通过",
  "cwd": "/absolute/path/to/repo",
  "run_in_background": true
}

返回值为 { "kind": "background", "jobId": "claude-code-1" }。随后可使用 DSH 原生作业工具读取增量输出：

job_output  { "jobId": "claude-code-1" }   # 读取上次调用之后的新输出
job_list    { }                            # 列出当前作业
job_kill    { "jobId": "claude-code-1" }   # 终止作业

作业完成时 DSH 会推送完成通知，无需轮询。继续上一轮会话：

{
  "task": "上一步的修复遗漏了边界情况，请补充并重新运行测试",
  "resume": "<上一轮结果中的 session id>"
}

5. 工具参数参考

工具名：claude_code

返回内容包含：最终文本、sessionId、Token 用量、费用、轮次、耗时与调用过的工具；提供 outputSchema 时额外返回 structuredOutput。

权限说明：permissionMode: acceptEdits 仅自动放行文件编辑，命令执行仍需通过 allowedTools 预授权。本插件未实现审批桥（canUseTool），未授权的操作会直接失败，不会等待人工确认。

6. 插件配置参考

在 profile 的 cordis.patch.yml 中配置：

- insert:
    - id: claude-code
      name: dsh-claude-delegate
      config:
        model: sonnet                # sonnet | opus | haiku | 完整模型 ID
        permissionMode: acceptEdits  # default | acceptEdits | bypassPermissions | plan | dontAsk | auto
        maxTurns: 100
        timeoutMs: 600000
        # cwd: /absolute/path/to/repo
        # maxBudgetUsd: 2
        # appendSystemPrompt: 提交信息一律使用中文；不要修改 lib/ 目录。
        # proxy: http://127.0.0.1:7890
        # allowDangerouslySkipPermissions: true
        # subagents:
        #   reviewer:
        #     description: 复核补丁，仅报告实质问题
        #     prompt: 你是严格的代码复核者，按严重程度排序输出结论。
        #     tools: [Read, Grep, Glob]

7. 监控面板

DSH 会话顶部「对话 / 轨迹」旁新增 Claude Code 标签页，用于观察当前会话内所有后台委派任务。

• 任务列表：每条后台作业一个标签，颜色指示状态（运行中、完成、失败、已取消）；运行中的任务排在最前，已结束的任务按时间倒序排列。
• 详情弹窗：标签上的 ⓘ 打开，显示完整任务文本、模型、状态、起止时间、耗时、费用、轮次、Claude Code 会话 ID（可复制后直接用作 resume）与失败原因。
• 过程视图：助手文本以 Markdown 渲染（标题、粗体、行内代码、代码块、列表、引用、链接，可切换原文/预览）；思考块默认折叠；每次工具调用显示为一张卡片（工具名、参数、结果、运行时长），任务结束时显示汇总行。
• 实时输出块：经实时通道执行的命令显示为终端块，包含命令行、逐行输出（stderr 单独着色）与退出码、耗时。
• 取消：确认后终止子进程树，作业按 killed 结算，模型侧同样收到完成通知。

实现约定：

• 面板按绝对偏移读取输出，与模型侧 job_output 的游标相互独立，各自翻阅互不影响。
• 作业记录保存在当前 DSH 进程内，每个会话保留最近 20 条，进程重启后清空；历史结果仍可在对话的工具卡片中查看。
• 修改插件的客户端部分后必须重启 DSH，桌面端不提供硬刷新。

8. 长命令实时输出通道

设计动因

Claude Agent SDK 的消息联合中不包含工具输出帧：工具执行期间只产生进度心跳（tool_progress），执行结束后才返回一次 tool_result。CLI 自身持有 Bash 的管道，不向 SDK 转发增量输出。因此，若要让用户看到长时间命令的实时输出，插件必须自行创建执行通道。

实现方式

插件注册一个进程内 MCP Server（名称 dsh），对外提供工具 mcp__dsh__shell。命令由插件自身 spawn（bash -lc），输出因此可以先进入插件的事件流，再按需提供给模型。插件的系统提示会提示模型：预计运行超过 20 秒的命令应通过该通道执行。

行为约束

• 通道输出仅进入面板，不进入 job_output，避免大量构建日志占用模型上下文；因此无论执行何种命令，结论与关键输出必须在回复正文中给出。
• 输出解码优先使用 UTF-8，出现替换字符时回退到 GBK，以适配中文 Windows 环境。
• 每次调用均为独立进程，cd、export 等状态不跨调用保留；短命令与需要保持 shell 状态的命令仍应使用内置 Bash。
• 将 shellChannelOnly 设为 true 可禁用内置 Bash，使所有命令都经实时通道执行，代价是失去 shell 状态连续性。
• 未检测到可用 bash 时，工具会明确提示模型改用内置 Bash，不会静默失败。

9. 内置技能

插件在运行时注册以下技能（source: runtime），因此无需向 ~/.dsh/skills/ 放置副本，避免出现两份内容不一致的说明：

派遣节奏：按需派遣，同一任务走多轮会话（用名字登记）

上面那个技能里写明的两条节奏规则，插件本身也按此设计，装完即生效，不需要额外配置：

• 按需派遣：claude_code 是慢而贵的一次性外包，只在「要读遍仓库才能定位 / 实现」时用；同一件事不要拆成多次派遣去"并行提速"，正确做法是串行推进同一条会话。
• 续接靠名字：同一个任务的后续轮次（继续下一步、改需求、修上一轮的产出、追问它的结论）照传同一个 conversation: <名字>，同一名字 + 同一 cwd 就命中同一条 Claude 会话，结果里以 [continued] <id>（第 N 轮） 交代。实测接续因缓存命中反而更便宜（接续 1723 in / 7 out，新开 9876 in / 9 out）。
• 不传名字 = 新开：插件无法从任务文本可靠判断「这属于哪条工作流」，判错等于把上一条线的历史悄悄带过来，所以默认取安全的一侧——新开会话、绝不接历史；此时结果会列出该目录已注册的工作流（名字 / 描述 / 轮次 / 最后使用），照抄一个名字继续即可。换任务、上一条线被带偏、或要干净对照（如复核它自己的结论）时传 fresh: true；只有要钉死某个 id 才传 resume。
• 多条工作流各给一个名字：同一个 DSH 会话里同时推进前端 / 后端 / 两个仓库，甚至同一目录下的 PPT 与周报，都各用各的 conversation: 名字（frontend / backend / weekly-report / deck-2026q4）。名字先到先立、之后照传同名；一工作流一名字，别中途换名。
• 注册表在 ~/.dsh/claude-delegate-sessions.json（每条线记：名字、描述、最近一轮任务摘要、cwd、轮次、首次与最后使用时间），DSH 重启后依然有效；上一次的会话已被清理时会自动新开一次并说明，不会因此失败。面板顶部的「已注册的工作流」列表读的就是它。

如果希望主代理在所有会话里都遵守这套节奏（而不只是在读技能时），把下面这段加进你自己的 AGENTS.md：

- 同一任务的后续轮次照传同一个 `conversation: <名字>`，插件会接上那条 Claude 会话（结果里出现 `[continued] <id>` 并报轮次）；
- 不传名字就是新开会话、绝不接历史——一个 DSH 会话里并行多条工作流时，每条都用自己的名字（PPT 与周报同目录也算两条线）；
  换任务/换话题或要干净对照时传 `fresh: true`；只有要钉死某个 id 才传 `resume`。一次派遣只推进一件事。

10. 安全与合规

• 插件通过官方 CLI 与官方 Agent SDK 调用 Claude Code，符合 Anthropic 的认证与订阅要求。
• 插件不读取、不转发、不落盘任何 OAuth 凭据；不存在将 Claude 订阅当作裸模型接入的实现。
• Claude Code 在本地以当前用户权限执行工具，DSH 的沙箱与权限策略不作用于其工具调用。请将 cwd 与 permissionMode 限制在可信范围内。
• 插件没有审批交互：未授权的操作直接失败，不会暂停等待人工确认。审核应体现在任务书的验收标准中。
• 模型来源须如实说明：插件驱动的是 Claude Code CLI 外壳，其底层模型由本机 ~/.claude/settings.json（ANTHROPIC_BASE_URL 与模型别名映射）决定，不一定是 Anthropic 的模型。因此不应将结果表述为「来自 Claude」，准确表述是「以 Claude Code 方式（外壳）运行」。

11. 运行机制

• 委派执行：宿主侧创建 SDK 会话，将 SDK 消息转写为面板事件（文本、思考块、工具卡片、进度、结果），并把实时输出增量镜像到事件流。
• 作业管理：后台作业通过 DSH 作业服务登记，插件自有的 tracker 维护每个作业的元数据与输出缓冲；面板行数据由作业服务名册、0.1.x 镜像与插件 tracker 三路合并得到。
• 客户端侧仅允许 require DSH shell 提供的白名单依赖（react、react/jsx-runtime、@deepseek-ai/dsh-client-ui-primitives 等），其余依赖必须打包进产物；构建脚本会对此进行断言。
• scripts/assert-artifacts.mjs 逐个断言产物存在；新增模块时必须同步更新该清单，否则遗漏文件不会被发现。

12. 故障排查

13. 常见问题

是否必须指定 cwd？ 建议始终指定。省略时会使用宿主进程的工作目录，可能加载到与目标项目无关的配置。

为什么 acceptEdits 下无法执行构建或测试？ acceptEdits 仅放行文件编辑。需要在调用中通过 allowedTools 显式预授权命令执行。

执行过程中会请求确认吗？ 不会。插件未实现审批桥，未授权的操作直接失败。审核应在任务书的验收标准中完成。

为什么某些长命令在面板中没有实时输出？ 该命令经内置 Bash 执行，而 SDK 不转发内置 Bash 的输出，面板只能显示运行中状态。将 shellChannelOnly 设为 true 可强制所有命令经实时通道执行。

重启后任务列表为什么为空？ 作业记录保存在进程内，每个会话保留最近 20 条。历史结果可在对话的工具卡片中查看。

可以指定其他模型吗？ 可以，但最终生效的模型由本机 ~/.claude/settings.json 的别名映射决定。model 参数传入的是别名或完整 ID。

14. 派生来源与改动说明

本仓库是衍生项目，上游为 zhangjunjesse/dsh-claude-code（其 npm 包仅发布至 0.1.2），本仓库在其 0.6.0 基础上继续开发。为避免与上游重名，包名与仓库名均改为 dsh-claude-delegate；上游保留在 upstream remote，可通过 git fetch upstream 获取。

相对上游的主要改动：

15. 开发与发布

npm install --legacy-peer-deps
npm run typecheck     # 宿主侧与客户端侧类型检查
npm run build         # 构建两侧并断言产物完整

本地部署与发布：

npm run build
cp -R lib/* ~/.dsh/profiles/<profile>/node_modules/dsh-claude-delegate/lib/   # 新增模块文件需一并复制
# 重启 DSH
npm publish --access public

发布后建议为 GitHub 仓库添加 dsh-plugin 主题标签，以便出现在 github.com/topics/dsh-plugin；如需进入社区插件市场（dshmarket），需向精选列表 awesome-dsh-plugin 提交条目。

变更记录见 CHANGELOG.md。

16. 许可证

MIT