dsh-claude-delegate

dsh plugin --profile web add dsh-claude-delegate

  

dsh-claude-delegate

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

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

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

---

目录

1. [功能特性](#1-功能特性)

2. [系统要求与兼容性](#2-系统要求与兼容性)

3. [安装](#3-安装)

4. [快速开始](#4-快速开始)

5. [工具参数参考](#5-工具参数参考)

6. [插件配置参考](#6-插件配置参考)

7. [监控面板](#7-监控面板)

8. [长命令实时输出通道](#8-长命令实时输出通道)

9. [内置技能](#9-内置技能)

10. [安全与合规](#10-安全与合规)

11. [运行机制](#11-运行机制)

12. [故障排查](#12-故障排查)

13. [常见问题](#13-常见问题)

14. [派生来源与改动说明](#14-派生来源与改动说明)

15. [开发与发布](#15-开发与发布)

16. [许可证](#16-许可证)

---

1. 功能特性

特性 · 说明

完整参数控制 · 模型、思考强度、权限模式、允许工具、轮次上限、预算上限、超时、追加系统提示、自定义 subagent 均可按次指定

后台异步执行 · run_in_background: true 立即返回 jobId，通过 DSH 原生作业工具增量读取输出，完成后收到通知

跨轮次续跑 · 结果正文末尾回传 session: <id>，将其作为 resume 参数传回即可在同一 Claude Code 会话中继续

长命令实时输出 · 内置独立 shell 通道 mcp__dsh__shell，长时间运行的构建/测试命令逐行实时进入面板

结构化输出 · 传入 JSON Schema（outputSchema）即返回符合该模式的 structuredOutput

成本可计量 · 结果包含费用、Token 用量与轮次统计，支持 maxBudgetUsd 硬上限

监控面板 · 会话内新增「Claude Code」标签页：任务列表、结构化过程视图、实时输出块、一键取消

运行时技能注册 · 随插件注册 claude-code-delegation 与 parallel-dev 技能，安装插件即安装技能，无需在用户目录维护副本

2. 系统要求与兼容性

项 · 要求

DSH 版本 · >=0.1.0-rc.6 <0.3.0，已在 @deepseek-ai/dsh-*@0.2.0-rc.2 上完成类型检查与构建验证

Node.js · 与 DSH 运行时一致（本仓库使用 Node.js 24 验证）

Claude Code CLI · 需在本机安装并完成登录：npm install -g @anthropic-ai/claude-code

后台作业 · 依赖 DSH 的作业服务（dsh-tool-jobs）；未提供时后台模式返回 background jobs unavailable

Shell 通道 · 需要 POSIX bash；Windows 下建议安装 Git for Windows 并使用其 bash.exe

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

参数 · 类型 · 必填 · 默认值 · 说明

task · string · 是 · — · 任务描述。应包含目标、涉及文件、约束条件与验收标准

cwd · string · 否 · 宿主进程工作目录 · 执行目录，建议始终传入绝对路径

model · string · 否 · 配置值（默认 sonnet） · 模型别名或完整模型 ID

permissionMode · string · 否 · 配置值（默认 acceptEdits） · default / acceptEdits / bypassPermissions / plan / dontAsk / auto

allowedTools · string[] · 否 · 配置值 · 允许 Claude Code 使用的内置工具，例如 ["Read","Write","Edit","Bash","Glob","Grep"]

maxTurns · number · 否 · 配置值（默认 100） · 最大对话轮次

effort · string · 否 · 配置值（默认 high） · 思考强度

thinkingMode · string · 否 · 配置值 · adaptive 或 disabled

maxThinkingTokens · number · 否 · 配置值 · 思考 Token 上限

maxBudgetUsd · number · 否 · 配置值 · 美元成本上限，达到后停止

timeoutMs · number · 否 · 配置值（默认 7200000） · 单次执行硬超时

appendSystemPrompt · string · 否 · 配置值 · 追加到系统提示的指令

run_in_background · boolean · 否 · false · 是否作为后台作业运行

resume · string · 否 · — · 续跑指定的 Claude Code 会话 ID

outputSchema · object · 否 · — · 结构化输出模式（JSON Schema）

subagents · object · 否 · 配置值 · 自定义 subagent 定义

proxy · string · 否 · 配置值 · 传给 claude 子进程的代理地址

shellChannelOnly · boolean · 否 · 配置值（默认 false） · 设为 true 时禁用内置 Bash，所有命令必须经实时通道执行

返回内容包含：最终文本、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]

字段 · 默认值 · 说明

model · sonnet · 模型别名或完整 ID

effort · high · 思考强度

permissionMode · acceptEdits · 权限模式

allowDangerouslySkipPermissions · false · 显式开关；为 false 时 bypassPermissions 不生效

…(truncated)