分别选择分发方式与协议
新接入优先采用 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 的执行能力,不构成额外隔离边界。
在仓库根目录可以准备本地镜像:
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 实现时,输出仅含契约字段、内容有界的失败记录,然后以非零状态退出:
使用 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 绑定必须检查租户所有权。 从确定性的解析与配置检查开始:将成功判据拆成独立检查
不要只为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 版本,再按以下顺序记录观察;这些是待执行的验收步骤,不是本页新增的通过记录。- 第一轮要求读取一个可验证的模型响应、保存已知文件并导出产物;核对退出、最终结果与下载摘要。
- 第二轮沿用同一 Session,用新 Run ID 与新提交幂等键,要求引用前轮对话事实并读取该文件,不能在第二轮输入中直接给出答案。
- 对声明支持 Tools 的 Harness,让一次调用经过既有 bridge;分别验证正常返回与
isError,并保持调用 ID 和参数稳定。 - 在授权或审批等待时确认原 Run 仍是等待状态;决定后继续原调用,核对外部操作次数,不能用第二个 Run 冒充续跑。
- 取消一个活动轮次,确认 Runtime 管理的进程状态、Run 终态与已派发外部操作结果;取消不能撤回既有副作用。
- 关闭 Session,确认云资源及关联对象清理,再下载已导出的产物。另一套 SDK 独立走完所需旅程,跨语言继续另作明确记录。