跳转到主要内容
Harness 适配器把 Agent 实现接入 Hexagon 已有的 Runtime、模型访问与 Tool broker,负责启动配置、结果解释和连续对话状态转换。Runtime 管理进程;控制平面负责 Session、Run、持久化事件、凭据、审批和云资源清理。不要另起控制平面服务,也不要把 Harness 执行放进 API 进程。 先阅读接入契约与架构。本文是实际实现的扩展流程;注册成功不代表兼容性验证完成。

分别选择分发方式与协议

新接入优先采用 OCI 镜像,固定解释器和依赖,并解析为 linux/amd64 manifest digest。Dockerfile 配方不等于已发布镜像,已发布镜像也不等于已执行组合。私有仓库支持还取决于 Sandbox Provider。 源码包保留为 Python、Node 使用 hexagon-json-v1 的兼容路径,不负责编排依赖安装。两种路径都保存租户所属的注册并固定版本,控制平面不会导入上传的源码。相同 id/version 修改内容会冲突;改变固定定义时使用新版本和新 Session。 模型协议、Tool 支持及连续对话语义以 protocols.ts为准。例如当前 Codex 声明 Responses,Hermes 声明 Chat Completions,Aider 不声明远程 Tools。镜像标签不能增加协议实现;扩展协议需要实现与拒绝测试,不能只增加 catalog 值。

理解适配器的三个方法

权威接口是 HarnessAdapter: 已有分发逻辑见 runtime-adapter.ts,受管 CLI 结果处理见 managed-cli.ts。OCI 提供依赖;适配器补充 bridge 和配置,不应静默替换镜像中固定的 CLI。argv 保持独立字符串,并针对固定版本测试真实参数。契约要求单次受监督调用时,不要使用 daemon 入口。 模型访问由 worker 提供作用域受限的配置。保留代理 URL 和委托认证安排,不要替换为供应商端点或账户密钥。CLI 要求 /v1 前缀时保留它。原始模型与 Provider 密钥留在控制平面;不要记录环境凭据、导出到产物,或隐式启用其他账户集成。

从最小 Python Harness 开始

现有 Python Agent提供真实模型驱动循环、shell 执行、Tool mailbox、有界步数与本地对话历史。对应 OCI Dockerfile固定基础镜像并选择 hexagon-json-v1。修改前阅读两者;shell 是 guest 的执行能力,不构成额外隔离边界。 在仓库根目录可以准备本地镜像:
命令需要 Docker,可能下载依赖,只创建本地镜像;云 Provider 通常无法消费这个本地标签。镜像发布是单独操作。按 OCI 指南的双语注册示例操作时使用可访问的不可变引用,不能为本地构建编造 digest。 hexagon-json-v1 程序从 stdin 接收一个 JSON 对象,随后收到 EOF。输入包括 run_id、input、作用域受限的 model 端点和名称、可选 native_session、本轮 artifact_directory 以及声明的 tools;当前适配器也可传递初始化信息。使用传入配置,在 Session workspace 保存历史,将导出文件写入给定的产物目录。 成功的最终结果是一行 JSON:
恰好输出一个最终结果,text 非空,可选原生标识不超过 512 字符。源码包解析器使用严格 schema,不要额外加入诊断字段。当前示例的异常输出包含诊断字段,源码包解析器会拒绝它,不能视为成功;派生实现时应审查并测试错误输出。普通日志不能替代回复。共享 worker 还要求进程结果与产物导出成功,单独一条看似正确的 JSON 不代表 Run 完成。

可跨分发路径使用的失败记录

派生 hexagon-json-v1 实现时,输出仅含契约字段、内容有界的失败记录,然后以非零状态退出:
这是失败处理片段,不是完整 Harness。不要把异常对象、上游响应体或凭据序列化到最终记录。没有有效继续标识时,明确省略 native_session。失败标志与退出状态都保留失败语义,不能生成兜底成功结果。对每条目标解析路径测试该片段,并单独验证 worker 的退出状态处理。链接的 Python Agent 异常分支目前带额外诊断字段;需要同时适配两条分发路径时,使用这里更严格的结构。 下一步:OCI 注册、源码包兼容路径、测试与证据。

使用 Tool bridge 与连续对话契约

已绑定 Tools 通过既有 mailbox 或 bridge 访问,不能直接取上游凭据调用。自定义循环向 http://127.0.0.1:8765/tools/<run_id>/call 发送 Run 作用域的 HEXAGON_TOOL_TOKEN、稳定调用 ID、声明的名称和参数。在授权、审批等待期间,继续使用相同 ID 和参数查询,最终检查结果及 isError。等待期间换调用 ID 可能创建不同 invocation。原生支持 MCP 的 CLI 通过适配器配置使用 tool_bridge.py。 支持原生连续对话时,返回真实原生标识并在下一轮传回。上游 CLI 要求自己的 Session 标识时,不能从 Run ID 编造。通用 Python 示例自己管理历史,其标识契约不同。使用依赖前文的追问验证状态保持;支持文件系统恢复时,还需在恢复后验证。初始化要明确首轮与后续轮次的处理;声明能力不等于实现。 取消由 Runtime 管理。适配器不能启动逃离监督的独立 Agent daemon。阅读 Runtime,测试子进程、Tool 等待期间取消和迟到输出。客户端事件连接断开不取消 Run。进程丢失时保留不确定状态,不要盲目启动第二次调用。不同 CLI 的原生事件可见性不同,只展示真实事件,不伪造隐藏推理。

注册与验证需要一起维护

新增 OCI 协议时,一起审查协议声明、镜像 schema 与注册、Runtime 适配器、结果解析、catalog、模板和证据。使用已有协议时通常可复用注册机制,无需新增内置分支。相关源码包括 images.ts、catalog.ts、templates.ts、verification.ts。源码包注册位于 harness-packages.ts。定义、仓库 Secret 与 Session 绑定必须检查租户所有权。 从确定性的解析与配置检查开始:
为新适配器添加自己的测试,不能假设现有测试已经覆盖它。验证畸形、缺失、重复最终输出,非零退出,上游错误,不兼容模型绑定,以及初始化与原生状态映射。使用真实上游二进制配合 fixture 模型响应,可以证明 CLI 参数和 bridge 行为,仍不能证明真实模型与云端兼容性。 最后,两种 SDK 分别完成镜像注册、创建云 Session、保持上下文的两轮对话、调用已分配 Tool、导出并下载产物、取消活动轮次,以及 Provider 确认清理。按声明能力加入授权审批等待、持久化事件和跨语言继续。仅支持对话的契约明确排除不支持的 Tool、产物能力,不能记作通过。按测试指南记录精确 digest、命令、Provider、模型协议与名称、SDK、场景和日期,保留失败与未决资源 ID。只有对应证据才能更新已验证组合。

将成功判据拆成独立检查

不要只为 result(stdout) 准备一条成功 JSON。适配器解析、进程退出和平台终态是不同判断,下面的输入应在新实现的测试中分别出现: 源码包的严格结果 schema 与 OCI 通用解析器不是同一段代码。源码包拒绝额外字段;当前 OCI 通用 hexagon-json-v1 分支没有使用同一严格 schema。为了跨分发方式复用,最终结果只输出约定字段,并分别测试两条注册路径。不要因一种分发方式接受了诊断字段,就把这种接受行为写成通用协议保证。 对一次最终失败,还要检查原始可观察原因。worker 会结合已持久化的模型传输记录,将部分失败区分为 model_transport_failed、model_authentication_failed、model_rate_limited 或 model_request_failed;否则可能是 harness_execution_failed。贡献者不应把所有非零退出都改写成用户 key 错误,也不应将上游原始响应泄露进公共错误。

为最小 Harness 设计验收脚本

先固定一个明确支持的 Provider、镜像 digest、模型协议和 SDK 版本,再按以下顺序记录观察;这些是待执行的验收步骤,不是本页新增的通过记录。
  1. 第一轮要求读取一个可验证的模型响应、保存已知文件并导出产物;核对退出、最终结果与下载摘要。
  2. 第二轮沿用同一 Session,用新 Run ID 与新提交幂等键,要求引用前轮对话事实并读取该文件,不能在第二轮输入中直接给出答案。
  3. 对声明支持 Tools 的 Harness,让一次调用经过既有 bridge;分别验证正常返回与 isError,并保持调用 ID 和参数稳定。
  4. 在授权或审批等待时确认原 Run 仍是等待状态;决定后继续原调用,核对外部操作次数,不能用第二个 Run 冒充续跑。
  5. 取消一个活动轮次,确认 Runtime 管理的进程状态、Run 终态与已派发外部操作结果;取消不能撤回既有副作用。
  6. 关闭 Session,确认云资源及关联对象清理,再下载已导出的产物。另一套 SDK 独立走完所需旅程,跨语言继续另作明确记录。
仅支持对话的适配器保留较窄的声明,并明确标记上述哪些能力不支持;它不能被计入完整 Tool / 产物旅程通过。协议兼容、真实模型使用和故障恢复分别记录,见能力与证据。