外部代理接入 Lawrence7y/dsh-harness-pilot

@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 真实窗口：定位 → 聚焦 → 注入键盘 → 无障碍树或控制台缓冲区读文本

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

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

| 事实 | 证据 |
| Electron harness 的 UIA 树基本是空的 | 对 ZCode / 小米 MiMo 深挖 UIA：只有 Chrome Legacy Window + 4 个窗口按钮，对话文本一个字都不暴露 |
| GUI harness 往往另有 CLI | mimo（Bun SEA）、ZCode 的 zcode.cjs（ELECTRON_RUN_AS_NODE）、WorkBuddy 的 codebuddy、kimi、grok |
| 终端类 harness 能直接读屏幕缓冲区 | AttachConsole + ReadConsoleOutputCharacterW 拿到真实屏幕文本，无需 OCR |
| ConPTY 已在宿主里 | ctx.subprocess.spawnTerminal 已挂载，白拿一个伪终端 + 整树回收 |

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

通道与能力矩阵

| 通道 | 适用 | 读 | 写 | 依赖 |
| headless | 有一次性模式的 CLI | stdout | 参数 / stdin | 无 |
| acp | 支持 ACP 的 harness（opencode acp） | 流式 agent_message_chunk | session/prompt | @agentclientprotocol/sdk（宿主随 dsh-acp 自带） |
| pty | 只有全屏 TUI 的 CLI | PTY 输出（xterm 渲染成屏幕文本） | 写入 pty（等于人敲键盘） | ctx.subprocess.spawnTerminal |
| cdp | Electron / Chromium harness | document.body.innerText（可配选择器） | Input.insertText + 回车 / 点发送按钮 | --remote-debugging-port，ws |
| window | 任意有窗口的 harness | UIA 无障碍树 → 控制台缓冲区 → 截图 | pyautogui 键盘注入（非 ASCII 走剪贴板） | python + pyautogui/uiautomation/pywin32/Pillow |

目标登记表（内置目录）

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

| target | 类型 | 入口 | 通道 |
| opencode | CLI | opencode | acp → headless(run) → pty |
| opencode-flash | CLI | opencode run --model opencode-go/deepseek-v4.1-flash | headless → pty（演示「每个目标绑定不同模型」） |
| opencode-tui | CLI | opencode | pty（交互会话用） |
| agy | CLI | agy（Antigravity CLI） | headless(--print) → pty |
| claude / codex / gemini / qwen | CLI | 同名命令 | headless → pty |
| zcode | Electron | D:\zai\ZCode\ZCode.exe | cdp → window |
| mimo | Electron | D:\mimo\Xiaomi MiMo\Xiaomi MiMo.exe | cdp → window |
| workbuddy | Electron | D:\workbuddy\WorkBuddy.exe | cdp → window |
| cursor | VSCode fork | D:\cursor\Cursor.exe | cdp → window |
| qoder / qoder-cn | VSCode fork | D:\Qoder\Qoder.exe / D:\Qoder CN IDE\Qoder CN IDE.exe | cdp → window |
| antigravity | Electron IDE | ...\Programs\antigravity\Antigravity.exe | cdp → window |
| minimax | Electron | D:\minimax\MiniMax Code\MiniMax Code.exe | cdp → window |
| grok | Electron | D:\Grok bot\Grok Bot.exe | cdp → window |

工具

| 工具 | 用途 |
| harness_list | 列出目标与可用性；probe=true 时逐个通道实测（会碰窗口/端口，稍慢） |
| harness_dispatch | 一次性派发任务，返回 harness 的回答。可 transport= 强制通道、extra_args= 追加参数（如换模型） |
| harness_agent | 以 DSH 子代理语义派发：稳定 runId、stopReason、partial output、diagnostic |
| harness_open | 打开/附着交互会话（CDP / 窗口 / PTY），返回 session id + 当前屏幕文本 |
| harness_send | 向会话注入文本或按键；不带输入时就是「读当前屏幕」；model= 切模型、click= 点元素 |
| harness_sessions | 列出 / 关闭会话 |
| harness_task_start | 后台派发长任务，立即回 task_id；完成后自动回执唤醒本会话 |
| harness_task_status | 任务状态 / 进度（增量日志）/ 终态交付内容 |
| harness_task_list | 列出最近任务（状态、回执投递情况） |
| harness_task_cancel | 取消在跑任务 |

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

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 打开模型选择器逐项枚举。

| harness | 供应商 | 可用模型 | 当前/默认 |
| Qoder CN IDE（账号 <redacted>，IDE 已登录） | Qoder CN 网关（UI 只有一个 provider） | 13 + Auto（界面实时枚举）：Qwen 5 · DeepSeek 2 · GLM 3 · Kimi 2 · MiniMax 1 —— Qwen3.8-Max/Qwen3.8-Flash/Qwen3.7-Max/Qwen3.7-Plus/Qwen3.7-Flash、DeepSeek-V4-Pro/DeepSeek-Flash、GLM-5.3/GLM-5.3-Flash/GLM-5.2、Kimi-K3/Kimi-K2.8-Preview、MiniMax-M2.7（带倍率，如 Qwen3.8-Flash 0x、Kimi-K3 1.4x） | Qwen3.8-Flash |
| MiMo 桌面端（账号 <redacted> · CN） | xiaomi @ api.xiaomimimo.com | 7：文本 mimo-v2.6-pro/mimo-v2.6-flash · TTS ×3 · ASR mimo-v2.5-asr · 图像 Doubao-Seedream-5.0-pro | mimo-v2.6-pro |
| MiMo 桌面端 AI（账号 <redacted> · SGP） | 同上 | 7，与上表唯一差异：图像是 gpt-image-2 | mimo-v2.6-pro |
| ZCode 桌面端 | 5 家（账号级；四套 coding plan 均 coding_plan_not_entitled） | 8：opencode→deepseek-v4.1-flash,mimo-v2.6-flash · xiaomi-mimo→mimo-v2.6-pro,mimo-v2.6-flash · step→step-5-preview · synapse→claude-opus-5-5 · bigmodel→GLM-5.3,GLM-5.3-Flash | 最近用 step-5-preview |
| Antigravity IDE（账号 <redacted>） | Google / Anthropic / OpenAI-oss（UI 不标 provider） | 7（选择器实时枚举）：Gemini 3.8 Flash(High)、3.7 Flash(Medium)、3.6 Flash(Medium)、3.1 Pro(Low)、Claude Sonnet 4.6(Thinking)、Claude Opus 4.6(Thinking)、GPT-OSS 120B(Medium) | Gemini 3.8 Flash (High) |
| Antigravity CLI（agy，同账号） | 同上 | 目录 14：Gemini 11 · Claude 2 · GPT-OSS 1（agy models 是目录，当前登录态下 entitlement 拉取被跳过，实际可用以运行为准） | gemini-3.8-flash-high |

要点与坑：

- 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）。

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

| 缺陷 | 症状 | 修法 |
| ctypes.wintypes.COORD 在 Py3.12 不存在 | 控制台读取全部抛错 → window 通道报废 | 用 getattr(wt,'COORD',wt._COORD) |
| 文本来源启发式按长度比较 | 113 字的标题栏装饰压过 46 字真实终端内容 | 只要控制台读到非空文本就优先控制台 |
| GlobalAlloc/GlobalLock/SetClipboardData 没声明 restype | 64 位 HGLOBAL 被截断 → 非 ASCII/多行 prompt 打不进去 | 声明 c_void_p restype/argtypes |
| 中文 IME 改写注入按键 | >→》、空格被吃、回车只提交候选词 | 一律剪贴板粘贴 + 打字期间 ImmAssociateContext(hwnd,NULL) |
| shot 用屏幕区域抓取 | 窗口被遮挡时拍到的是前面的浏览器 | 优先 PrintWindow(PW_RENDERFULLCONTENT)，失败才回退 |
| .cmd argv 二次转义 | cmd.exe 报「不是内部或外部命令」 | 双形态 argv + windowsVerbatimArguments（headless/acp/cdp 都改） |
| ACP 无法选模型 | opencode ACP 默认模型走 OpenRouter（余额不足） | 新增 acpModel，session/new 后发 session/set_config_option |

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

| 目标 | 通道 | 结果 | 证据 |
| Antigravity CLI (agy) | headless -p | ✅ 27.5s 回复 HARNESS-OK | stdout |
| Qoder CN IDE | cdp（端口 9336） | ✅ 回复 HARNESS-OK | DOM 里同时出现我的消息与回复 |
| MiMo 桌面端（账号 <redacted>） | cdp（9334，先重启带端口） | ✅ 回复 HARNESS-OK，已处理 14s | DOM 时间戳 + 回复 |
| MiMo 桌面端 AI（账号 <redacted>） | cdp（9333） | ✅ 回复 HARNESS-OK，已处理 6s | DOM 时间戳 + 回复 |
| ZCode 桌面端 | window（UIA） | ✅ 已送达并被处理 | 任务名自动生成 + HARNESS-OK 落在 ~\.zcode\cli\db\db.sqlite |
| Antigravity IDE | cdp（9337） | ✅ 新建会话并回复 HARNESS-OK | DOM：Thought for 2s + 回复 |

本次为打通 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 通道。