主题
编码 Harness 接入
一句话：编码 Agent 是目前最成熟的 Harness，平台不该重造一套，而应把它当成“可租用的执行器”：用能力协商确定它能做什么，用工作区隔离限制它碰什么，用审批与轨迹留下证据。
Harness 与 Runtime 的分层见 Harness 与 Agent 参考架构，编码工具链的工程实践见 AI Coding；本篇只讲怎么把现成 Harness 接进平台。
拼装位置：上游是 Scheduler 与 Dataplane → 本篇把任务交给 Runtime Host 与编码 Harness → 下游是工作区、模型网关与 OTel；交界字段是 enrollment token、capabilities、事件流、退出码与产物引用。
为什么需要
平台自研编码 Harness 的代价被低估了：工具集、文件编辑、终端、补丁应用、上下文压缩、权限询问、会话恢复，每一项都要长期打磨；而 OpenCode、Claude Code、Codex 已经把这条路走了很久。企业真正缺的不是“再写一个编码 Agent”，而是：
- 把任务派到某台开发机或构建机，而不是让每个人手工开终端；
- 限定它能读哪些仓库、能访问哪些网络、能执行哪些命令；
- 任务失败时知道停在哪一步，产物在哪里，谁批准过；
- 换一个 Harness 时，平台侧调度与审计不用重写。
所以接入的目标是把 Harness 变成标准执行器，而不是把它藏进平台内部。
核心机制
一、三种接入面，先选信任边界
| 模式 | 执行位置 | 平台拿到什么 | 适合 |
|---|---|---|---|
| Hosted Runtime | 你的电脑或服务器 | 任务状态、产物、有限事件 | 复用现成 CLI，代码不出内网 |
| External SDK | 你的应用进程 | 注册身份、会话事件 | 已有服务，保留框架控制权 |
| Managed | 平台 Dataplane | 完整会话与工具轨迹 | 零代码托管、统一运维 |
三者的能力承诺不同。Hosted 模式里，平台负责调度与工作目录准备，Harness 负责执行；它不是 Managed Agent 的 self_hosted 工具 Worker，也不等于把整个 Service 部署到你的机器。把三者混用，会在恢复、审批和产物管理上出现“以为有、其实没有”的落差。
二、Harness 选型：先看治理，再看能力
| 维度 | OpenCode | Claude Code | Codex CLI |
|---|---|---|---|
| 许可 | MIT | 闭源商业条款 | Apache-2.0（仅 Harness） |
| 模型 | 模型无关，可指向企业网关 | 仅 Claude，可经网关转发 | OpenAI 为主，也支持自定义 provider |
| 集成面 | 本地 server + HTTP API / SDK | Agent SDK + -p headless | exec / SDK / app-server JSON-RPC |
| 沙箱 | 依赖宿主与配置 | 权限模式 + Bash/文件沙箱 | read-only / workspace-write / full，默认断网 |
| 企业治理 | 较弱，需平台补 | managed settings、hooks、SSO/SCIM、审计 | requirements 锁定、OTel 审计、沙箱最严 |
| 适合 | 可替换执行器、模型自由 | 合规要求高、接受供应商锁定 | 高风险代码执行、可控沙箱 |
选型不是“谁最强”，而是“谁的限制你能接受”。模型自由通常意味着治理要自己补；治理完整通常意味着模型与许可被锁定。
三、Runtime Host：把执行器挂到平台上
Host 的职责是“准备、启动、回报”，不是“替 Harness 思考”。任务目录必须由 Host 准备，默认不要使用用户正在编辑的 Git checkout；否则一次自动修改可能覆盖未提交的改动。容量（通常 1–50）要显式配置，排空时停止接新任务、等在途任务结束。
四、能力协商：不要假设它支持恢复
接入前先读 /capabilities 的 available_commands，确认三件事：
- 能不能取消：取消通常只停止本次运行，不撤销已写入的文件与外部操作；
- 能不能补充输入/审批：部分 Hosted 会话只支持取消，不支持暂停后补充；
- 能不能恢复：统一 invocation 的
checkpoint_restore当前可能为 false，部分适配器不提供 Session resume。
平台侧要按“最小能力集”设计流程：没有恢复能力时，任务失败就重新派发并带幂等键，而不是假装能断点续跑；没有审批能力时，把高风险命令限制在沙箱或只读模式。
五、工作区隔离：目录不是沙箱
Hosted 模式常见的误解是“任务在独立目录里跑，所以安全”。目录只解决文件覆盖，不解决：
- 进程能读宿主的其他目录与环境变量；
- 命令能访问内网与公网；
- Harness 的 approve-all 策略允许它执行任意命令；
- 多个任务共享同一工作目录时仍可能互相覆盖。
正确做法是分层：独立目录解决串扰；容器/VM 解决文件系统与进程隔离；网络策略解决出站；凭据注入解决最小权限；审批策略解决高风险动作。不要用目录隔离替代沙箱。
六、审批、凭据与证据
- 审批：把“需要人确认的命令/文件操作”映射为平台审批项；审批的是动作，不是结果。
- 凭据：通过环境变量或 Vault 短时注入，任务结束即失效；不要把长期 Token 写进仓库或 Harness 配置。
- 证据：收集退出码、stderr、变更文件、测试结果、模型与工具事件；只收集“成功/失败”无法归因。
- 产物：补丁、报告、构建产物上传对象存储，消息与账本只留引用。
最小上手
先接一台 Host，只跑只读任务：
text
1. 在目标机器安装 Harness 并完成登录/模型配置；
2. 用 enrollment token 执行 as connect，注册 Runtime Host；
3. as runtime probe 读取能力，确认 cancel / approval / resume 支持情况；
4. 提交一个“阅读仓库并输出摘要”的只读任务；
5. 检查任务目录、事件流、产物与退出码；
6. 再提交一个写入任务，验证审批与变更文件清单。验收判据：任务不使用用户当前 checkout；取消后进程真正停止；高风险命令触发审批；失败任务能拿到 stderr 与退出码；产物可按 trace 找回。
生产动作
- 版本钉住：Harness、适配器、模型配置都记录版本；升级前跑固定任务集，比较工具调用格式与事件。
- 网络最小化：默认禁止出站，按任务开白名单；模型调用走企业网关，不直连供应商。
- 凭据短时化：任务级注入、到期失效；禁止把个人订阅凭据用于平台任务。
- 工作区清理：任务结束保留产物、删除临时文件；敏感仓库设置保留期与访问审计。
- 容量与排空：按宿主机 CPU/内存设置并发上限；发布与维护前先 drain，等在途任务结束。
- 审计对齐：Harness 自带 hooks/OTel 与平台 trace 使用同一
traceparent，避免两套证据对不上。
边界
- 不是多租户沙箱：Hosted 执行在用户机器上，隔离强度取决于宿主与容器，不是平台承诺。
- 不是无限能力：取消、审批、恢复因适配器而异；接入前必须读能力清单。
- 许可有约束：闭源 Harness 的商用、转售、凭证使用都有条款；开源 Harness 也只开源运行时，不含模型。
- 代码可能出内网：模型调用会把上下文发到模型端点；敏感仓库要么走私有模型，要么限制可发送的文件范围。
- 不要把所有 Harness 抽象成同一套 API：能力差异是事实，抽象层只统一“任务、事件、产物”，不要假装取消/恢复/审批都一样。
讲清楚
编码 Harness 接入的本质是把成熟执行器变成平台可调度的资源：Host 准备独立工作区、按租约接任务、流式回报事件与审批，平台负责调度、凭据、审计与产物。
三种接入面按信任边界选：Hosted 把代码留在内网，External 保留应用控制权，Managed 把执行交给平台。选型先看许可、沙箱与企业治理，再看模型与功能。
四条边界不能忘：目录不是沙箱，取消不等于回滚，能力要协商不能假设，闭源许可与代码出网都有约束。判断接入是否成立，看五条：任务不碰用户 checkout、高风险动作有审批、失败有 stderr 与退出码、产物可追回、换 Harness 不用重写调度。
适用：OpenCode / Claude Code / Codex CLI 2026 年版本 | 初稿 2026-10