deepseek-harnessed

deepseek-harnessed

将整个 DeepSeek Harness (DSH) 运行实例包装为可供 Cursor / Claude Code / Codex / Gemini CLI / Antigravity / Kiro / Qoder / VS Code (Copilot) / opencode 等调用方工具调用的子代理（subagent），并为 DSH Desktop 宿主界面提供实时状态监控悬浮卡片。

架构设计说明：使各类外部 Agent 工具能够将子任务分派给独立的本地 DSH 实例执行，而非仅在自身进程内运行轻量级函数调用。

系统由以下三部分组成：

快速导航文档

下文为系统架构设计、机制解析与实测记录（§1~§10）。

---

支持矩阵

---

DSH 版本兼容性

桥接层运行于 DSH 内部环境（包含一个 Profile 与两个宿主插件），上游接口变动将直接影响插件行为。以下为实测适配数据（基于从 app.asar 提取的实际运行源码验证，避免 app.asar.unpacked/ 中陈旧文件干扰）：

0.1.5-rc.1 的三处破坏性变化与处理方案

异常处理函数 fail() 现输出完整错误调用栈（此前仅输出 error.message），以便快速定位类似 presets.current() 参数签名变更的内部异常。

上游版本已知问题与规避措施

0.1.5-rc.1 发行版中附带的 lsp-stdio 与 tool-lsp 插件未同步更新 assertNever 引用路径，加载时抛出 does not provide an export named 'assertNever' 异常。由于插件树采用全量加载机制：

• dsh --profile web 启动失败。

• 桌面宿主不受影响：desktop profile 默认未包含上述两项插件（经 --dump-config 确认日志中无 assertNever 报错）。

• 若需运行 web profile，可在配置中禁用对应插件：

  - id: lsp-stdio
    disabled: true
  - id: tool-lsp
    disabled: true
  

  使用 --patch 传入包含上述两行 overlay 的配置即可正常启动。

升级后快速自检步骤

dsh --version                                  # 先看版本
node test/selftest.mjs                         # 协议级端到端:真拉 MCP + 真跑一轮(最能说明问题)
node test/launcher-heal-probe.mjs              # dsh 入口脚本指向的入口文件还在不在(Desktop 换打包形态时第一个红)
node test/leaf-only-probe.mjs                  # row id 有没有被改名/删掉
node test/monitor-live-probe.mjs               # 观察器 + 宿主判活

版本升级需重点验证两类项目：配置行 ID（row id）（共有 15 处 Patch 配置，变更会导致规则失配）与服务方法签名。测试脚本 test/leaf-only-probe.mjs 覆盖前者检查（已适配 0.1.5 起 tool-subagent-report（subagent-report）由加载行变更为协议内部消息 kind 的调整）。

---

安全与运行边界

• 网络边界：桥接层自身不发起外部网络连接，仅负责启动本地 dsh 子进程，并读写 $DSH_HOME 与本地工具配置文件。
• 默认权限：默认执行权限为 workspace-write（可读写目标工作空间，工作空间之外的文件操作由 DSH 沙箱拒绝）。需要全盘读写时在调用时显式传 permission: "danger-full-access"，要更紧可传 "read-only"；也可用环境变量 DSH_SUBAGENT_PERMISSION 改默认级别。
• 默认工具形态：叶子进程以 PTC（程序化工具调用） 形态运行——模型写一段 TypeScript、经 run_code 调度工具，而不是一次一个原生工具调用。该选择由起进程时的 DSH_TOOLS_MODE=ptc 给出（lib/tasks.mjs 默认设置，可用 DSH_SUBAGENT_TOOLS_MODE=native 改回）。
• 运行数据保护：state/ 目录存放私有运行时数据，已在 .gitignore 中排除。日志、心跳与任务记录文件（task.json / meta.json / stderr.log）包含本地绝对路径、工作空间名、提示词与任务输出。仓库内不包含任何真实任务现场数据。
• 配置写入安全：安装脚本在修改配置文件前均生成备份副本（.bak-dshsubagent-<时间戳> 或 <原文件>.bak-dshsubagent-<时间戳>），遇到无法解析的 JSON 文件自动跳过，不覆盖现有数据。
• 运行平台：当前仅针对 Windows 环境开发与验证，依赖 taskkill 与 PowerShell 进程管理机制。

---

系统工作原理

本机各 Agent 工具通过 MCP 协议将任务委派给独立的 DeepSeek Harness 实例，并在指定工作空间内获取执行结果。

Cursor / Claude Code / Codex / … 的对话
        │  ① 调用 MCP 工具 dsh_task(prompt, workspace, expected_seconds)
        ▼
dsh-subagent-mcp.mjs   (MCP stdio server,本目录 bin/)
        │  ② 分配 job id,把提示词从 stdin 交给子进程
        ▼
"DSH Desktop.exe" --profile subagent   ← 一台完整的 DSH 实例,一轮会话
        │  ③ 在 workspace 里真干活:读写文件、跑命令、跑测试、联网检索
        ▼
$DSH_HOME/sessions/<workspace>/session-<uuid>/   (会话落盘,可在 DSH GUI 里复查)
        │  ④ 最终答复 → result.txt / stdout
        ▼
dsh_task 返回 "status: ok" + DSH 的原文

与内置子代理的主要区别：任务作为独立的 DSH 系统进程运行，拥有独立的上下文窗口、模型配置、工具链以及持久化会话记录，而非宿主工具内的函数调用。

---

1. 一分钟自检

# 桥接是否可用(等价于 harness 里的 dsh_health 工具)
dsh-subagent --where

# 真跑一轮:在指定工作空间里让 DSH 干一件可验证的事
dsh-subagent -w D:\some\repo "列出后端路由文件,汇总最近改动"

# 协议级自检(会真的拉起 MCP server 并跑一轮任务)
node $env:USERPROFILE\.dsh\subagent\test\selftest.mjs

# 等待规则:默认短超时自己等、只有 running 才轮询(会真的派两个任务)
node $env:USERPROFILE\.dsh\subagent\test\wait-policy-probe.mjs

# 监控窗口自动拉起(假 exe + 临时 DSH_HOME,**不会真的启动 GUI**)
node $env:USERPROFILE\.dsh\subagent\test\monitor-autostart-probe.mjs

# 台账残留记录(记录说在跑、pid 早没了)→ 必须按 pid 判活
node $env:USERPROFILE\.dsh\subagent\test\ledger-liveness-probe.mjs

# 叶子检查:外部任务不能再生子代理(配置级 + 解出会话日志看真实工具表)
node $env:USERPROFILE\.dsh\subagent\test\leaf-only-probe.mjs <sessionId片段>

# 卡片底部状态条的数字:真实任务日志 → token 用量(逐帧解 zstd,只读)
node $env:USERPROFILE\.dsh\subagent\test\usage-fold-probe.mjs --all

---

2. 对外暴露的六个 MCP 工具

MCP 服务器名称统一为 dsh，在各客户端中工具名称形如 mcp__dsh__dsh_task（Claude Code）或 dsh.dsh_task（Codex / Cursor）。

dsh_task 参数详细定义

调用方标识识别：每个 MCP 连接在 initialize 请求中携带的 clientInfo.name 会记录至该连接创建的每个任务元数据中（task.json 的 caller 与 callerVersion，并在工具结果的 caller: 行显示）。未提供时默认为 "unknown"，命令行直接调用记录为 "cli"。GUI 监控面板与 dsh_health 均基于此标识进行分组。

等待执行策略说明：dsh_task 默认等待 45 秒。若任务在此期间完成，结果直接在当前调用中返回，无需额外轮询；若超过 45 秒未完成，返回 status: running 与 job_id，此时外部 Agent 应在同一会话中调用 dsh_task_status(job_id, wait_seconds=30) 进行等待与轮询（每次等待 30 秒），直至达到终态（ok / error / deadline / stalled / cancelled / killed）。请勿直接传入 wait_seconds=0，避免过早拆分成多次模型轮询往返。

委托说明前缀：桥接层默认在提示词前添加简要委托指引（明确为单次会话、无人交互应答、结束时汇报修改文件与结果结论），防止 DSH 进程因等待用户交互而挂起。

2.1 工具调用规范与 Schema 说明

操作约定已直接固化至 MCP 工具 Schema 定义中：

自检套件包含对上述 Schema 文案的完整断言校验，确保规范描述不丢失。

2.2 任务终止响应机制

当外部客户端取消当前轮次请求时，客户端会发送 MCP notifications/cancelled 通知。桥接层执行以下终止逻辑：

服务不依据轮询空闲时长猜测连接状态，仅响应明确的停止信号。在 Windows 环境下通过 taskkill /F 或 TerminateProcess 强制终止外部进程，并通过测试确保取消通知到达后子进程实际退出。

2.3 执行等待策略与超时控制

长任务若默认采用 wait_seconds=0 会被拆解为多次频繁的 dsh_task_status 轮询请求，增加额外的模型推理开销。

桥接层采用短超时优先机制：dsh_task 默认阻塞等待 45 秒。任务在 45 秒内完成则直接返回结果，零轮询；超时未完成则返回 status: running，转由调用方使用 dsh_task_status（默认单次等待 30 秒）按轮次推进。

默认等待时长的评估依据：

依据 60 秒阈值预留 25% 安全余量确定为 45 秒，状态轮询设置为 30 秒。实测短任务在 DSH 侧耗时 1.4~1.7 秒，dsh_task 在 3.5 秒内即可完成并带回终态结果（通过 test/wait-policy-probe.mjs 验证）。

如需支持长任务单次直接返回，需同步调整客户端工具超时与桥接层等待配置：

# ① 先把调用方的单次工具超时调大(Codex 为例;command/args 用安装器写好的那两行)
[mcp_servers.dsh]
command = "C:\\Program Files\\nodejs\\node.exe"
args = ["C:\\Users\\<you>\\.dsh\\subagent\\bin\\dsh-subagent-mcp.mjs"]
tool_timeout_sec = 600

# ② 再同步把桥接层的等待调大(两个都可单独调)
DSH_SUBAGENT_WAIT_SECONDS=540          # dsh_task 的短超时
DSH_SUBAGENT_STATUS_WAIT_SECONDS=540   # dsh_task_status 的默认等待

相关配置通过环境变量覆盖，可通过 dsh_health 返回的 defaultWaitSeconds、statusWaitSeconds、waitModel 查看生效值。修改后需重启客户端生效。

2.4 模型配置机制与策略文件

桥接层动态获取模型清单，模型选择规则保存在外部策略文件中：

在未配置默认模型时（策略文件中为 默认模型: (未指定)），dsh_task 与 dsh_health 返回内容末尾附带 6 行初始化指引（包含查询模型、获取用户选择、调用 dsh_setup 写入配置及提供策略文件链接四要素）。写入配置后指引自动停用。

// 落盘:只改策略文件里 `默认模型:` 那一行,其余内容与用户改动一律保留
{ "name": "dsh_setup", "arguments": { "default_model": "deepseek-v4.1-flash" } }   // 已接入的模型,裸 id 或 provider/id
{ "name": "dsh_setup", "arguments": { "preset": "本项目方案" } }                     // 用预设里声明的模型
{ "name": "dsh_setup", "arguments": { "policy_markdown": "…" } }                    // 整体替换正文(必须保留 `默认模型:` 行)

若传入未注册模型 ID 则返回 isError:true 并输出可用模型列表；若参数类型错误（如 default_model: 3）同样返回 isError:true 并指明错误参数名。可通过 dsh_setup(default_model: "…") 写入配置。

---

3. 本机配置注册详情

配置写入执行幂等更新，修改前备份为 <原文件>.bak-dshsubagent-<时间戳>，遇到无法解析的 JSON 文件自动跳过。

3.1 推理强度配置（固定为 high）

针对 llm-pi-ai 下你自己的路由，处理某个模型（例如 deepseek-v4.1-flash）的推理强度配置。在 DSH 的设置里声明支持档位与默认强度（0.1.7 之前是 ~/.dsh/settings.yaml；之后设置由 profile 的 patch 层承载，例如 $DSH_HOME/profiles/desktop/cordis.patch.yml 里 llm-pi-ai 条目的 config.providers）：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: MY_GATEWAY_API_KEY
      api: openai-responses
      baseURL: https://your-gateway.example.com/v1
      reasoning: high            # 路由默认推理强度:没有显式 --reasoning-effort 时就用它
      models:
        - id: deepseek-v4.1-flash
          reasoningEfforts:      # 声明"这个模型支持哪些档位",并给出各档位落到协议上的写法
            off: none            # 网关不接受空值,off 必须显式写成 none
            minimal: minimal
            low: low
            medium: medium
            high: high
            xhigh: xhigh
            max: max

要点解析：

• 没有 75 这个取值。 网关只认 none|minimal|low|medium|high|xhigh|max,传 75 会被拒 (unknown variant \75`,HTTP 400)。"75" 是 harness 侧的显示刻度,落到这个网关就是 high(与 Codex 的model_reasoning_effort = "high"同档)。本机的vision-toolkit`、以后新增的服务商都可以按此规则配置。
• reasoningEfforts 用于声明模型支持的档位列表，缺少声明时调用 --reasoning-effort high 会报 UNSUPPORTED_REASONING_EFFORT；reasoning 决定未传参时的默认级别（此处固定为 effort: "high"）。网关实测未声明时 reasoning_tokens = 103（reasoning_tokens=103），显式指定时 reasoning_tokens = 35（reasoning_tokens=35）。
• 配置文件在操作时动态重新读取，修改后无需重启 DSH Desktop。
• 单次调用可通过 dsh_task 的 model 参数或 dsh --profile subagent --reasoning-effort low --prompt ... 调整。

实测验证：

# 改之前:失败 —— 说明这个模型压根没声明推理能力(连 high 都不支持)
dsh --profile subagent --prompt "只回答两个字:好的" --reasoning-effort high
# → exit 1, {"code":"UNSUPPORTED_REASONING_EFFORT","message":"... does not support reasoning effort \"high\""}

# 改之后:成功
dsh --profile subagent --prompt "只回答两个字:好的" --reasoning-effort high
# → exit 0, meta.json 里 {"reasoningEffort":"high","stopReason":"completed"}

若配置出现格式错误，dsh-settings-file 将整段拒绝加载并直接报错（NO_ADAPTER: no adapter registered for provider "my-gateway"），不进行静默回退。

安装与卸载脚本（由 install.mjs 与 uninstall.mjs 托管，版本号同步于 package.json）：

node $env:USERPROFILE\.dsh\subagent\install.mjs              # 幂等重装(推荐)
node $env:USERPROFILE\.dsh\subagent\install.mjs --dry-run    # 只看会改什么
node $env:USERPROFILE\.dsh\subagent\uninstall.mjs            # 摘掉所有 MCP 注册

---

4. DSH subagent Profile 结构与限制

Profile 部署于 $DSH_HOME/profiles/subagent/（源码位于 profile/）：

package.json          bundles = dsh-base + dsh-headless,patchReload = startup
cordis.patch.yml      在 headless 基线上做的 7 处改动(逐条有注释)
subagent-startup.js   任务解析:--prompt / --prompt-stdin / --prompt-file / 位置参数
subagent-runner.js    一次性 runner:跑一轮 → 写 result.txt / meta.json → 退出

相对于官方 Headless 的调整：

1. 启动器支持 --prompt-stdin、--result-file、--metadata-file、--model。
2. 运行器输出最终答复与 {sessionId, model, stopReason, durationMs} 元数据，支持单次调用指定模型；模型没有点名 provider 时按推理档位选路（见 §2 的 model / provider 行）。
3. 停用标题自动生成插件以减少模型调用。
4. 审批策略固定为 never。
5. 沙箱模式由 DSH_SUBAGENT_PERMISSION 环境变量控制（默认 workspace-write，即工作区可读写、工作区外拒绝）。
6. 显式声明无人值守权限预设表（三种模式都对应 approval: never，workspace-write 不会因预设不匹配而启动失败）。
7. 工具形态默认 PTC：起叶子进程时设 DSH_TOOLS_MODE=ptc（tools 行读这个变量；可用 DSH_SUBAGENT_TOOLS_MODE=native 改回原生工具调用）。
8. 施加叶子节点限制条件，禁止外部任务递归分派子代理。

4.1 叶子限制条件（禁止外部任务递归派生子代理）

外部工具通过 dsh_task 调用的任务禁止递归创建子代理，Profile 禁用了以下插件：

会话下发的工具表比对（解压 jsonl.zstd 验证）：

自检验证命令：

node $env:USERPROFILE\.dsh\subagent\test\leaf-only-probe.mjs <sessionId片段>

命令行直接调用测试：

cd D:\some\repo
dsh --profile subagent --prompt "跑一遍单测并汇总失败项"
# 长提示词走管道,不受命令行长度限制:
type task.md | dsh --profile subagent --prompt-stdin

---

5. 权限管理与沙箱机制

权限生效机制：

1. Profile 显式定义完整的权限预设映射表（三种模式均对应 approval: never），避免 dsh-permission-presets 在构造期抛出 composed sandbox and approval defaults match no preset 异常导致进程退出。
2. 运行器在执行前通过 permissionPresets.set() 将目标权限写入当前会话事件流，工具层依据 ctx.sandboxPolicy.resolve({session}) 动态解析沙箱策略；若锁定失败则直接报错退出。

已知运行边界：两个 profile 的沙箱相关行集合一致（sandbox-local / sandbox-policy / pwsh-sandbox / fs-sandbox）。DSH 0.2.1 上 workspace-write 与 read-only 模式下 pwsh 工具可正常执行（实测 Write-Output SPAWN-PING 返回 "SPAWN-PING\r\n"、退出码 0、sandbox.mode=workspace-write、denied=false）；此前 0.1.x 出现过的「受限模式下 Shell 返回空文本」已在 0.2.1 消失，但 0.1.x 的旧实例仍可能复现。

5.1 沙箱模式下 Shell 空转检测（历史兜底，0.2.1 起不再触发）

0.1.x 的 workspace-write / read-only 曾出现 Shell 工具返回空内容（"\r\n"）且 isError: false、进程并未实际启动的情况：

桥接层仍保留这段兜底：任务结束时会解析会话日志，检测这类空转的 Shell 调用；若存在，会在答复末尾附加调用次数与命令样例的告警，并在元数据中记录 shellHollowCalls 与 shellHollowSamples。所以「任务跑了但命令没执行」不会被伪装成成功。

---

6. 并发控制与状态可视化

6.1 并发与任务生命周期管理

实测通过 node test/concurrency-probe.mjs <工作空间> 3（node test/concurrency-probe.mjs <ws> 3）验证 3 路并发正常并行执行。

任务取消与终止：

• dsh_task_cancel：优雅取消，对运行中及排队中的任务均有效。
• dsh_task_kill：强制终止指定 job_id 或指定 caller 在当前服务进程内的全部活跃任务进程树。

6.2 超时保护与停滞看门狗