把 Coding Agent Harness 用到业务里：我们能复用什么，又该自己建设什么

上一篇把 OpenCode、Pi、DeepSeek Harness 等工具放在一起做了比较。这一篇接着讨论一个更实际的问题：如果已经有业务系统、内部 API 和一批 CLI，能不能直接利用这些 Harness，而不是再从头写一套 Agent？

我的答案是可以，而且早期很值得这样做。

Agent Loop、上下文、Session、工具调用、流式事件这些能力，自己写一遍并不难，难的是把各种异常情况都补齐。现成 Harness 已经替我们做了不少工作。业务团队真正应该投入的地方，是工具是否好用、数据是否可信、权限是否清楚，以及最后的结果能不能对业务负责。

不过这里有一条边界：Harness 可以替我们执行任务，不能替我们管理业务。

接触这些工具，能给业务团队带来什么

先用较小成本判断任务值不值得做

很多 Agent 项目一开始就讨论模型网关、记忆、多 Agent、向量库和调度平台，但最基本的问题还没有答案：模型拿到现有工具以后，到底能不能完成任务？

用 OpenCode 或 Pi 先搭一个 Runtime，可以很快验证几件事：

• 模型能不能理解业务目标；
• 现有 API、CLI 和文档够不够用；
• 任务是否真的需要动态规划；
• 哪些步骤适合自动执行，哪些必须让人确认；
• 完成一次任务需要多少时间和成本。

这个阶段最重要的产出不是界面，而是一批真实任务和失败记录。跑完几十个任务，通常就能看出问题主要出在模型、工具、数据，还是任务本身根本不适合 Agent。

少写一遍通用 Agent Loop

模型要完成一个多步骤任务，背后至少会经历这些事情：

1. 组装 Prompt、Skill、历史消息和工具说明；
2. 调用模型；
3. 解析 Tool Call；
4. 执行工具并收集结果；
5. 把结果放回上下文；
6. 继续调用模型，直到任务结束；
7. 处理中断、超时、权限确认和上下文过长。

这些工作和具体业务关系不大，却会消耗不少开发时间。OpenCode、Pi、DeepSeek Harness 已经提供了不同程度的实现。使用它们，相当于先拿到一个能工作的执行内核，再把精力放在业务工具和结果质量上。

让已有系统变得更容易被自动化使用

不少内部 CLI 是给人写的：帮助信息很长，参数名不统一，错误全部打印成文本，输出格式随版本变化。人用的时候可以临场判断，Agent 批量调用时就容易出问题。

接入 Harness 后，团队往往会开始补这些细节：

• 参数有没有明确类型和范围；
• 输出能不能统一成 JSON；
• 错误能不能区分权限不足、参数错误、暂时失败；
• 查询和修改是不是两个独立命令；
• 一次调用读取了哪些数据；
• 结果太大时怎样分页或裁剪。

最后得到的其实不只是“给 Agent 用的工具”，也是一套更规范的自动化接口。

把经验整理成 Skill、Tool 和评测集

业务 SOP 经常散落在文档和专家经验里。接入 Agent 后，可以把这些内容拆得更清楚：

• Skill 说明遇到某类任务时应该怎样判断；
• Tool 负责查询或修改真实系统；
• Policy 约束哪些操作允许自动执行；
• Eval 判断输出是否正确、证据是否充分。

这样做比把所有内容塞进一个很长的 Prompt 更容易维护。以后替换模型或 Runtime 时，也能继续使用同一套工具和评测任务。

Harness 能替我们做什么

把 OpenCode、Pi 或 DeepSeek Harness 放在业务系统后面，我会把它们当成执行面。一次 Run 内部的事情，尽量交给 Harness：

• 调用模型并维护 Agent Loop；
• 保存本轮会话上下文；
• 注册和调用工具；
• 载入 Skill、Agent 或扩展；
• 处理文件、Shell 和工作目录；
• 发送消息、工具和错误事件；
• 做基础的权限确认和任务取消；
• 在支持的情况下约束结构化输出。

这些能力足以让一个业务想法快速跑起来。例如客服助手可以先查订单和历史工单，再组织回复；数据助手可以先查指标，发现异常后继续查询明细；研发助手可以修改代码并运行测试。

哪些东西不能交给 Harness

真正进入业务以后，仍然有一批事情必须由自己的系统负责。

业务任务状态

Harness 认识的是 Session 和 Message，业务认识的是工单、审核单、报表任务、订单或代码变更。两者不能直接画等号。

一次业务任务可能因为超时重跑两次，也可能先由 OpenCode 执行，后来再交给 Pi 做复核。因此更合适的关系是：

BusinessTask 1 ── N AgentRun 1 ── N HarnessSession

我会保留三个 ID：

• task_id：业务任务；
• run_id：一次执行尝试；
• session_id：具体 Runtime 内的会话。

这样以后做重试、回放或替换 Runtime，不需要改变业务数据模型。

身份和权限

Harness 不知道某个用户属于哪个部门，也不知道他能不能查看某个客户、数据集或项目。它提供的工具权限通常只是第一层，真正的资源级授权仍然要在业务系统或 Tool Gateway 里完成。

最好给每次 Run 签发短期身份，让工具按租户、用户和任务检查权限，而不是把一个长期管理员 Token 放进 Agent 容器。

幂等、重试和审批

模型调用失败可以重试，查询工具超时也可以重试，但“提交退款”“发布内容”“修改配置”不能简单重放。

业务侧需要知道一个操作有没有执行过，是否允许再次执行，以及由谁审批。Harness 的确认弹窗可以承载交互，但审批规则和最终状态仍然应保存在业务系统。

结果是否正确

Harness 能让模型输出一份报告，却不知道这份报告是否符合公司的业务定义。

例如一份数据分析结果可能必须包含统计周期、数据口径和样本量；一份审核结果需要规则编号和证据；一次代码修改必须通过指定测试。最终结果应该经过 Schema 和业务规则校验，不能只看文字是否通顺。

调度、容量和高可用

任务队列、Worker、限流、优先级、失败补偿、成本配额、跨机房部署，这些通常也不属于单个 Harness 的职责。把 Harness 当作 Worker 使用会比较清楚，而不是让业务请求一直同步等待某个 CLI 进程退出。

一个比较稳妥的分层

我倾向于把系统拆成四层：

┌───────────────────────────────────────────┐
│           Business Control Plane          │
│ API / Tenant / Task / Retry / Approval    │
│ Result / Notification / Billing           │
└──────────────────┬────────────────────────┘
                   │ internal API
┌──────────────────▼────────────────────────┐
│             Harness Adapter               │
│ OpenCode / Pi / DeepSeek / Codex          │
│ event normalize / capability / routing    │
└──────────────────┬────────────────────────┘
                   │ run
┌──────────────────▼────────────────────────┐
│             Execution Runtime             │
│ Session / Context / Skill / Workspace     │
└──────────────────┬────────────────────────┘
                   │ tool call
┌──────────────────▼────────────────────────┐
│                Tool Plane                 │
│ CLI / Native Tool / MCP / Workflow API    │
│ Auth / Schema / Timeout / Audit            │
└───────────────────────────────────────────┘

控制面保存业务事实；Adapter 屏蔽 Runtime 差异；Harness 完成一次执行；工具层访问真实系统。

这个分层的好处是边界比较清楚。模型可以决定下一步查什么，但不能决定用户有没有权限；Harness 可以保存 Session，但不能把 Session 状态当成业务最终状态；工具可以执行操作，但高风险写入仍要经过审批。

已有 CLI 能不能直接放进去

可以，尤其适合 PoC。

最简单的做法是把 CLI 固化到 Runtime 镜像并加入 PATH：

biz-ticket get --id TICKET-001 --output json
biz-data query --dataset sales --range 7d --output json
biz-content inspect --content-id C-1001 --output json

再写一份 Skill，说明每个命令什么时候用、需要哪些参数、返回值是什么。OpenCode、Pi 这类工具都可以通过 Shell 执行它们。

但我不建议把二进制临时复制到每个任务目录，然后让模型自由组合命令。目录只是文件位置，不是权限边界。至少要处理下面几件事：

• CLI 版本固定，镜像可追溯；
• 只开放允许执行的命令；
• 参数经过校验，不直接拼接 Shell；
• 默认只读，写操作使用独立入口；
• 统一 JSON 输出和错误码；
• 设置超时、输出大小和资源限制；
• 使用短期凭证；
• 记录调用人、参数、耗时和结果摘要。

CLI、Native Tool 和 MCP 怎么选

这三种方式不是互斥关系，通常会同时存在。

CLI：最快接入

如果团队已经有成熟 CLI，先复用它最省时间。文件处理、本地脚本、一次性迁移任务也很适合 CLI。

问题是模型需要理解命令行语法，参数转义、长输出和错误文本也容易带来不确定性。进入试生产后，最好在 CLI 外面增加 Wrapper，把结构化参数转换成命令参数。

例如模型调用的是：

{
  "tool": "get_ticket",
  "arguments": {
    "ticket_id": "TICKET-001"
  }
}

Wrapper 再执行固定命令，而不是把一整段 Shell 交给模型生成。

Native Tool：单个 Runtime 内体验最好

OpenCode Custom Tool、Pi Extension 或厂商 SDK 的进程内工具，可以直接使用类型、事件、权限和错误处理能力。

对于调用频率高、交互复杂的核心工具，Native Tool 会比 Shell 顺手。不过这种实现通常和 Runtime 绑定，工具太多以后，替换成本会逐渐上升。

MCP：更适合共享能力

如果日志、订单、知识库、数据查询等能力要同时提供给多个 Agent 客户端，MCP 更合适。业务接口和凭证留在独立服务里，OpenCode、Pi、Codex 或 Claude 都通过同一套工具协议访问。

OpenCode ─┐
Pi ───────┼── MCP / Tool Gateway ── Business APIs
Codex ────┘

MCP 解决连接方式，企业通常还需要在它前后补身份、资源授权、限流、缓存、脱敏和审计。

我的实际选择

我会按下面的顺序推进：

1. 已有 CLI 先接进来，把任务跑通；
2. 高频 CLI 增加 Schema Wrapper；
3. 少量强交互能力做成 Native Tool；
4. 跨团队、跨 Runtime 的公共能力迁到 MCP 或 Tool Gateway；
5. 高风险写操作仍走确定性 Workflow API 和人工审批。

这样不用一开始就建设一个很重的平台，也不会长期停留在“模型随便执行 Shell”的状态。

哪些业务值得先试

客服和工单

先查询客户信息、订单和历史工单，再做分类、补充信息和建议回复，是比较适合的切入点。退款、补偿和封禁不要直接自动执行。

数据分析和报告

这类任务经常需要根据中间结果继续查数据，Agent 比固定问答更有优势。但数据库应通过只读数据集、查询模板和扫描量限制开放，不能让模型直接拿生产库管理员权限。

内容审核

Agent 擅长理解上下文、整理规则和证据，可以用来做风险分类和复核辅助。最终裁决仍应保留规则引擎或人工审核，特别是影响用户权益的场景。

运维和问题诊断

日志、指标、Trace、变更记录本来就分散在多个系统中，很适合通过工具让 Agent 动态查询。诊断和执行修复需要分开，前者可以逐步自动化，后者要设置更严格的审批。

研发自动化

读代码、修改文件、运行测试正是 Coding Agent Harness 最熟悉的任务。如果需要完整仓库、容器和浏览器，运行环境的重要性甚至会超过模型本身。

企业流程助手

制度查询、材料检查、表单准备和流程导航也能受益。这里要特别注意区分“给出建议”和“业务已经办理完成”，不能让模型的文字回复替代真实系统状态。

反过来，如果任务步骤固定、规则能完全枚举、延迟要求很高，或者一次错误就会产生不可逆损失，普通程序和工作流往往更合适。Agent 可以放在某个需要理解和判断的节点，不必接管整个流程。

OpenCode、Pi、DeepSeek Harness 怎么放进这套架构

详细的产品比较放在上一篇，这里只保留和落地有关的区别：

情况	可以先试
希望通过 HTTP/SSE 接到现有服务	OpenCode
希望把 Runtime 嵌进自己的 Node.js 产品	Pi SDK
非 Node 服务，但可以管理长驻子进程	Pi RPC
Python 团队，围绕 DeepSeek 和训练评测建设	DeepSeek Harness
已确定 OpenAI 或 Claude 平台	Codex / Claude Agent SDK
需要完整远程软件开发环境	OpenHands

不管先选哪一个，业务服务最好只依赖自己的接口：

type Harness interface {
    CreateRun(ctx context.Context, req CreateRunRequest) (Run, error)
    Send(ctx context.Context, runID string, input Input) error
    Subscribe(ctx context.Context, runID string) (<-chan Event, error)
    GetResult(ctx context.Context, runID string) (Result, error)
    Approve(ctx context.Context, runID string, approval Approval) error
    Cancel(ctx context.Context, runID string) error
}

然后分别实现 OpenCodeAdapter、PiAdapter 或 DeepSeekAdapter。

Adapter 不需要把所有产品抹成完全一样，只统一业务真正依赖的部分，例如 Run 状态、事件、取消和最终结果。Structured Output、Session Fork、特定 Sandbox 等能力可以通过 capability 标记暴露。

从 PoC 走到生产

我会分四步，而不是第一天就把所有基础设施建齐。

第一步：只证明任务有价值

选一个 Runtime、一个模型和几项只读工具，跑一批真实任务。记录成功率、人工接管、耗时、Token 和工具调用情况。

这一步先不要追求多模型和多 Agent。如果单 Agent 加几个工具都无法稳定完成任务，增加更多角色通常只会让问题更难定位。

第二步：把工具和结果收紧

让 CLI 输出稳定 JSON，给高频工具增加 Schema，限制参数和资源范围。最终结果也用 Schema 校验，并明确区分事实、证据、推断和建议。

有副作用的工具先全部放到审批后面。

第三步：补业务控制面

增加任务表、队列、异步 Worker、幂等、分层重试和取消。把 task_id、run_id、session_id 串起来，并记录模型、工具和审批事件。

到这一步，Harness 才真正从个人工具变成业务执行器。

第四步：再考虑 Runtime 替换和共享工具层

准备固定回放集，让候选 Runtime 跑影子任务，对比质量、成本、耗时和失败恢复。如果公共工具越来越多，再建设 MCP 或 Tool Gateway。

不要因为社区里出现了一个新项目就立刻迁移。Adapter 和回放集的意义，就是让切换建立在数据上。

上生产前我会检查这些问题

• 用户取消后，模型请求和子进程是否真的停止；
• Runtime 崩溃后，任务能否安全恢复或重试；
• 不同租户的目录、Session 和凭证是否隔离；
• 工具参数和资源范围是否可限制；
• 工具返回超长内容或恶意文本时怎样处理；
• 最终结果是否经过 Schema 和业务规则校验；
• 写操作是否有幂等键和审批记录；
• 一次 Run 的模型、工具、审批和结果能否完整追踪；
• 单任务的时间、Token、工具次数和资源是否有限额；
• Runtime 升级失败时能否回滚。

这些问题没有处理完，系统可以做内部试用，但不适合承担重要业务动作。

总结

OpenCode、Pi、DeepSeek Harness 这类工具最适合放在“执行”这个位置。它们让模型能够使用上下文、Skill 和工具完成一次任务，省掉了很多重复的 Agent Loop 开发。

业务系统仍然要握住几样东西：任务状态、身份权限、幂等审批、结果标准和审计记录。这些内容一旦跟某个 Harness 的 Session 和消息格式绑在一起，后面升级或换工具都会很麻烦。

所以比较实际的做法是：先用现成 Harness 和已有 CLI 把任务跑通；确认有价值后，再逐步把 CLI 收紧成结构化工具，把公共能力放进 MCP 或 Tool Gateway，并在业务和 Runtime 之间加一层 Adapter。

这样做既利用了 OpenCode、Pi、DeepSeek Harness 已经完成的工作，也不会把自己的业务平台变成某个 Agent 项目的附属品。

上一篇 《OpenCode、Pi、DeepSeek Harness 怎么选：Coding Agent Harness 全景与服务化对比》 对主要工具的接口和取舍做了更完整的比较。

参考资料

• OpenCode Server
• OpenCode SDK
• OpenCode Custom Tools
• OpenCode Permissions
• OpenCode MCP Servers
• Pi RPC Mode
• Pi SDK
• Pi Extensions
• DeepSeek Harness GitHub Repository
• DeepSeek Harness Interaction Modes
• Codex as a Platform
• Claude Agent SDK Overview
• OpenHands Software Agent SDK
• OpenHands Agent Server

常见问题

能不能把企业已有 CLI 放进 OpenCode、Pi 或 DeepSeek Harness 的运行环境，让它们直接调用？

可以，尤其适合早期验证。正式使用时应把 CLI 固化进版本化镜像并加入 PATH，限制命令和参数，统一 JSON 输出、超时、错误码、凭证与审计。公共或高频能力可以继续封装为 Native Tool 或 MCP。

使用现成 Harness 后，业务 Agent 平台还需要建设什么？

仍需建设任务状态机、多租户和 ACL、幂等与重试、审批、隔离、审计、评测、成本治理和结果校验。Harness 主要解决一次 Agent 执行，不会自动理解业务责任。