@dsh-external/dsh-harness-pilot

把其他 agent harness 接入 DeepSeek Harness：既能作为 DSH 的子代理派发任务，也能以窗口级方式交互操控它们。不依赖截图 OCR —— 优先走协议与文本通道，截图只在最后兜底。

DSH Agent
├── 工具面  harness_list / harness_dispatch / harness_agent / harness_open / harness_send / harness_sessions
└── 子代理   ctx.subagents 上的 harness-<名字> provider（harness_agent 与标准 subagent 工具都能用）
        └── 通道梯子（自动选，选不到就如实报错，绝不悄悄重复执行）
            1. acp      ACP 协议（opencode acp …）—— 流式文本，最稳
            2. headless CLI 一次性打印（opencode run / agy --print / claude -p / codex exec）
            3. pty      宿主 ConPTY（ctx.subprocess.spawnTerminal）+ xterm 屏幕模拟
            4. cdp      Chromium DevTools 协议（Electron harness：读 DOM / 写输入框 / 点发送）
            5. window   真实窗口：定位 → 聚焦 → 注入键盘 → 无障碍树或控制台缓冲区读文本

为什么不是「截图 + 点击」

本机实测结论（决定了通道顺序）：

所以：能走协议就走协议；不行读文本（控制台缓冲区 / DOM / 无障碍树）；再不行才注入键盘；截图是最后手段。

通道与能力矩阵

目标登记表（内置目录）

内置一份本机实探过的 harness 目录；profile 里只写差异即可覆盖。CLI 类走协议，GUI 类走 CDP / 窗口。

工具

完成回执：任务完成 → 交付内容 → 唤醒会话（含会话重新启动）

harness_task_start（或 POST /harness-pilot/api/task/start）派发的后台任务到终态时， 插件主动把交付内容送回发起会话并触发新一轮：

1. 组装回执文本：回执 ID / 目标 / 终态 / 工作区 / 结果文件路径 / 交付内容正文（可配截断）/ 续办提示；
2. 注入发起会话并唤醒：sessionController.resolveAgent(sessionId) → agent.followup(userMessage) → sessions.flush() 落盘确认（与 dsh-schedule 同一条唤醒链）；
3. 会话重新启动：会话 agent 不在线时 resolveAgent 会先 resume（agents.resume）把会话拉起来， 再投递回执 —— 冷会话也能被唤醒继续任务；
4. 投递状态如实记账在任务的 callback.status：delivered / failed / uncertain / skipped （进程中断期间的投递不重发、不假装成功）。

回执行为在设置 → 外部 Harness → 插件设置里可调：notifyOnComplete（完成后唤醒）、 deliverResult（回执附带交付正文）、maxResultChars、maxConcurrent、defaultTaskTimeoutMs、 resumeInstruction。设置存 ~/.dsh/plugins/harness-pilot/runtime-settings.json，保存即生效； 任务三件套（.json/.log/.result.json）存 ~/.dsh/plugins/harness-pilot/tasks/。

配置示例（profile 覆盖差异）

- id: harness-pilot
  name: '@dsh-external/dsh-harness-pilot'
  config:
    defaultTarget: opencode
    pythonPath: ''            # 窗口助手用的 python；留空自动探测
    targets:
      - name: opencode
        args: ['run', '--model', 'opencode-go/deepseek-v4.1-flash']   # 固定模型
      - name: agy
        args: ['--print']
        promptViaStdin: true   # prompt 走 stdin 而不是命令行参数
        timeoutMs: 900000
      - name: zcode
        command: 'D:\zai\ZCode\ZCode.exe'
        cdp:
          launchArgs: ['--remote-debugging-port=<port>']
          inputSelector: 'textarea'

作为子代理使用

• 本插件为每个目标注册 harness-<名字>（默认目标额外注册 harness-pilot）。
• harness_agent 走这条路径；也可以用宿主的 tool-subagent 挂一个标准工具：

  - insert:
      - id: harness-subagent-opencode
        name: '@deepseek-ai/dsh-tool-subagent'
        config:
          provider: harness-opencode-flash
          toolName: harness_opencode

模型：跨 harness 用已配置的供应商模型

两层模型信息都能看到，也能在派发时指定：

• DSH 侧：harness_models 直接读 ctx.llm，列出本 profile 配置的供应商路由与模型 （实测 8 条：deepseek-official / opencode-go / opencode1 / xiaomi / step / synapse …）。
• harness 侧：目标配置里的 modelsCommand 会去问那个 CLI 自己有哪些模型并缓存。 实测 opencode models 返回 408 个、agy models 14 个、pi --list-models 45 个、mimo models 7 个。
• 派发时指定：harness_dispatch(model=…) / harness_agent(model=…)。落地方式按目标配置：
  • modelArgs: ['--model','{model}'] → 追加到 argv（opencode / agy / claude / mimo / pi / grok / kimi / qodercli…）
  • acpModel → ACP 会话内 session/set_config_option（opencode / mimo / kimi / codebuddy）
  • 两者都没有的 GUI harness（ZCode / Cursor / Qoder IDE / Antigravity…）只能在它们自己的 UI 里选模型，插件会如实说明。

每个目标绑定不同模型也很简单（内置 opencode-flash 就是例子）：把模型写进 args 即可。

设置界面（client 半边）

• 设置 → 外部 Harness：一张表列出全部 harness（名称、说明、通道、可用性 + 命令路径、默认模型、模型数、活跃会话）， 顶部汇总 N 个 harness · M 个可用 · K 个会话，下面还有「DSH 已配置供应商」清单与「刷新」按钮； 外加两个新区块：
  • 插件设置：可编辑表单（完成后唤醒会话 / 回执附带交付内容 / 交付截断 / 并发上限 / 默认超时 / 续办提示）， 「保存设置」写回 runtime-settings.json 并立即生效；
  • 后台任务：harness_task_start 任务列表（状态、回执投递状态、耗时），可展开「结果」看交付内容、 对在跑任务「取消」。
• 设置 → 插件：一张 Harness Pilot · 外部 harness 接入 卡片，让插件在插件管理里可见。
• 数据来自宿主 HTTP 接口（同源，无需鉴权配置）：
  • GET /harness-pilot/api/overview → 目标 + 会话 + 供应商模型（?models=1 才会去问各 CLI，慢）
    • runtimeSettings + 最近任务
  • GET /harness-pilot/api/probe?target=<name> → 该目标的通道梯子实测结果
  • GET /harness-pilot/api/settings、POST /harness-pilot/api/settings/save → 运行时设置读写
  • GET /harness-pilot/api/tasks、GET /harness-pilot/api/task?id=…&result=1、 POST /harness-pilot/api/task/start|cancel → 后台任务
• client 工件构建后落在包根 client.js（exports["./client"]）并同时拷到 lib/client.js； dsh.client = { platform: "web", immediately: true } 让它在页面启动时注册槽位。

若插件是运行时新装配的，页面需要刷新一次（客户端模块图在启动/文件变化时重组；刷新后即可看到上面两个界面）。

各 harness 实测可用模型（2026-10-01 审计）

审计方式：能列模型的 CLI 直接问它（harness_models）；GUI 应用读它自己的账号级模型目录，或在带调试端口启动后用 CDP 打开模型选择器逐项枚举。

要点与坑：

• GUI 应用只能在它自己的界面里选模型——插件能派发任务、能读界面，但不能替它切模型（canSelectModel=false）；CLI/ACP 类的目标可以（model= / acpModel）。
• Qoder CN：目录里有 21 个具体模型、账号实际只被授权 13 个（catalog-v6 是加密容器，过滤规则读不出来）；qoderclicn CLI 未登录（与 IDE 是两套凭据）。
• ZCode：桌面端模型来自 provider_config.json + models.dev，~/.zcode/cli/models/api.json（145 供应商/5264 模型）只是 CLI 自己的镜像，不是桌面端下拉框的来源。
• MiMo：账号级目录 model-catalog.json 会校验 account 字段（不匹配就返回空），所以它就是"当前登录账号能选什么"的权威答案；另有 BYOK 目录 models-with-claude.json（223 供应商 / 7958–8177 模型）属于"自定义模型"入口。
• Antigravity：agy models 的 14 个不等于 entitlement（其代码路径报了 not logged into Antigravity 并跳过 fetchAvailableModels）；IDE 与 CLI 目前指向同一个 Google 账号。

构建与安装

node scripts/build.mjs          # junction 链接依赖 + tsc 编译 src → lib + 拷 client 工件

• 依赖链接目标是正在运行的 DSH 安装（默认 C:\dsh\node_modules），保证编译期 .d.ts 与运行期模块实例都和 harness 一致；可用 DSH_INSTALL 覆盖。
• 开发期热注入：dev_inject_plugin <本仓库路径>；改完 dev_reload_package harness-pilot。
• 持久安装：dev_install_package（或 plugin_manager install_bundle），由 cordis.patch.yml 挂载。

已验证 / 未验证

已实测通过（2026-10-01，桌面端 desktop profile）

• 桌面端挂载：profiles/desktop/package.json 增加 link 依赖 + bundles 条目、 node_modules/@dsh-external/dsh-harness-pilot junction；经 pluginManager RPC 热切换 bundle（setBundleEnabled false→true）即可加载/重载新代码，无需重启 DSH。
• 服务时序修复（关键缺陷）：bundle 启动场景下主 fiber 只等 inject 声明的服务， ctx.get('webServer') 在 webServer 注册前抢跑拿到 undefined → HTTP 路由静默丢失（全 404）。 修复：webServer / subagents 走子 fiber（ctx.plugin({ inject })，服务到了才注册，永不抢跑）； 唤醒链服务（agents / sessionController / sessions）改为投递回执时惰性解析。 修后 GET /harness-pilot/api/overview 200、GET /settings 正常返回。
• 完成回执端到端：POST /task/start（target=opencode，notify=true，session_id=发起会话） → 后台跑完回 TASK-E2E-OK → 任务 callback.status=delivered（"completion receipt queued as a follow-up turn …; agent woken"）→ 回执（含交付内容）作为新 turn 出现在发起会话并唤醒 agent 继续任务。
• 离线测试 probe/verify-tasks-wake.mjs：23/23 PASS（设置读写/落盘、任务全生命周期、 回执文本与截断、failed/skipped 如实记账、resolveAgent→followup→flush 唤醒链、 惰性服务解析、agents.resume 会话重新启动回落）。

历史实测（web profile，0.3.x 时代）

• 工具面与子代理 provider 都真实注册进运行时（六个 harness_* 工具在工具表里）；已 dev_install_package 持久装配，重启后由 bundles 列表接管。
• harness_dispatch target=opencode headless → 真实 OpenCode CLI 返回 PILOT-E2E-OK（约 3.7s）。
• harness_dispatch target=opencode acp → PILOT-ACP-OK，stop=completed、acpStopReason=end_turn、acpModelNote=model set to opencode-go/deepseek-v4.1-flash（initialize agentName=OpenCode 2.0.14 / protocolVersion=1）。
• harness_agent target=opencode-flash → 子代理 provider 返回 PILOT-SUBAGENT-OK，stop=completed，带稳定 runId。
• harness_open target=opencode-tui + harness_send → 完整读到交互式 OpenCode TUI 屏幕（xterm 屏幕还原，200 列）。
• cdp：headless Chromium 全链路 PASS（/json/list → attach → Runtime.evaluate → Input.insertText → Enter 三事件 → 稳定判定 → 清理）；真实 Electron（MiniMax Code）成功附着 app://./archon 并读出 DOM 文本；对正在运行且无调试端口的 ZCode/MiMo 在 spawn 之前诚实拒绝（PID 集合前后一致，没偷偷再起实例）。
• window：模块 E2E 11/12 PASS（真实 conhost 窗口：launch → focus → 读控制台真实文本 → 注入 → 文本变化 → abort/timeout/错误路径），唯一 FAIL 是探针自带的「冻结 helper」断言（它专门验证已被修掉的 bug）。
• window 读真实 GUI：harness_open target=zcode 成功附着运行中的 ZCode（hwnd 1182200），读出 70+ 行真实 UI 文本（项目列表、任务名、命令面板、标签页）。注意：这是界面文本（导航/列表/按钮），不等于聊天正文；聊天正文建议走 cdp 或该 harness 的 CLI。
• .cmd shim 引号修复：带空格/冒号/&/内嵌引号的 prompt 作为单个 argv 原样送达（& 未被当命令分隔符）；双形态 argv（verbatim 给 child_process，普通形态给 node-pty）。

本轮修掉的本机缺陷（都有复现证据）

多账号实测（2026-09-30 当晚，6 个目标各发一条连通性消息）

本次为打通 GUI harness 补的能力（都在 harness_send / 目标配置里）：

• harness_send(click: "…") —— 按名字点元素：CDP 会话走 DOM 文字匹配，窗口会话走 UIA 名字匹配（打开面板、点「新建任务」/发送按钮）。
• window.openInputKeys —— 打字前先按快捷键把焦点带进输入框（ZCode 用 ctrl+n）。
• 每个 GUI 目标分配固定 CDP 端口 + 端点归属校验（避免 A 应用占了端口、B 目标误附着到 A 的页面上）。
• 关会话不再关用户窗口：只有插件自己启动的窗口才在 harness_sessions close 时关闭（附着来的窗口只脱手）。
• helper 关掉 pyautogui 角落自锁并在注入前把光标挪出角落，否则光标停角落时连键盘注入都会被误拒。

已知限制

• window 通道对 Electron harness 读取到的是界面文本（导航、列表、按钮），不保证包含聊天正文；需要正文请走 cdp，或干脆走它的 CLI（zcode-cli / mimo-cli / codebuddy）。
• cdp 需要 harness 以调试端口启动；已在运行且没带该端口的 Electron 应用是单实例，重新启动只会聚焦旧实例 —— 这种情况插件会明确报错，让你先关掉再用 harness_open 拉起。ZCode/MiMo 的 inputSelector / sendSelector / busySelector 仍为空（需在它们带端口启动后实测补上），当前靠 DOM 启发式定位输入框。
• send() 是光标处插入、不清空输入框（正文里原有草稿会被前缀拼接；note 里会报 N chars before）。
• pty 通道对全屏 TUI 的文本还原依赖 @xterm/headless；缺失时退化为「去 ANSI + 取尾部」。
• harness_dispatch 不会在运行中途换通道重跑（避免任务被执行两次）：通道选择发生在预检阶段。
• ZCode 的内置 CLI 需要 app 内的 provider 配置（本机该文件缺失），所以走 ELECTRON_RUN_AS_NODE 时 -p 仍可能报「无法定位 CLI ZCode Built-in Provider Config」；这种情况请用 GUI/CDP 通道。