hexagon-json-v1 源码 Harness 时使用本页。新集成优先采用 OCI 镜像,以明确解释器和依赖环境。源码包注册只存储租户所属的数据,控制平面不会导入或执行这些代码;实际安装和执行发生在云 Sandbox。
前提与格式
准备有管理权限的客户端、已验证并启用的 Sandbox / 模型连接,以及能运行python3 或 node 的 Sandbox。当前源码包 schema 只接受 model_providers: ["anthropic-compatible"],不能通过修改标签获得 Chat Completions 或 Responses 支持。
包包含 1—32 个 UTF-8 源文件,内容合计不超过 512 KiB;每个 content 字符串还受 262144 个 JavaScript 字符单元限制。文件路径最长 240 个字符,必须是符合 schema 的相对路径,不允许空段、.、..、重复路径或文件与目录冲突。入口文件必须实际包含在 files 中。
这个格式没有 npm / pip lockfile 安装编排,也不是二进制归档上传接口。控制平面只检查结构和内容完整性,不证明代码能正确执行。依赖必须在 Sandbox 中可用,或由你明确管理。
注册与选择版本
以下是接入片段,复用首个 Session 教程中的已初始化客户端和连接 ID。从仓库根目录读取现成的 Python Harness 示例;它使用标准库调用 Messages 模型,支持 shell、声明的远程 Tools 和对话历史。harness_version_conflict。更新代码需使用新版本,并创建选择新版本的 Session,现有 Session 保持固定版本。当前没有源码包删除接口。能力字段是作者声明,不是平台对任意源码的认证。
stdin、凭据和工具调用
Runtime 在 Session 工作区运行入口,并通过 stdin 传入一个 JSON 对象,然后关闭 stdin。对象包含 protocol、run_id、input、initialization、model、native_session、artifact_directory 和 tools;首轮 native_session 可能缺省。Harness 需要自行保存历史,后续通过返回的 opaque native_session 找回同一会话。 使用传入的model.base_url 和 model.model;不要将其替换为硬编码服务地址。当前 worker 提供的 HEXAGON_MODEL_KEY 是保护通道的委托访问凭据,原始模型账户密钥留在控制平面。HEXAGON_TOOL_TOKEN 只用于本 Run 的本地 Tool 邮箱。不要将这些值写到日志、模型上下文或产物。
远程 Tool 通过 http://127.0.0.1:8765/tools/<run_id>/call 调用,Authorization 为 Bearer <HEXAGON_TOOL_TOKEN>,JSON 为 {"id":"<UUID>","name":"<declared name>","arguments":{}}。同一逻辑调用使用相同 id 与参数轮询,直到 state 为 completed,再处理 result 和 isError。授权与审批等待由控制平面处理。为同一次调用重新生成 UUID 可能创建新的操作;不能以此重试未知外部副作用,也不能绕过邮箱直接获取绑定 Tool 凭据。
最终结果与失败
stdout 必须有且仅有一条有效的最终结果 JSON 行:升级时不改变已有工作
将每个 package id/version 视为不可变。服务端为内容 digest 规范化文件顺序与能力集合;同版本改变可执行内容或其他定义字段属于冲突,不是更新。新内容注册为新版本,再由新 Session 选择,不要修改既有 Session 安装的源码来模拟版本升级。 package API 验证源码布局与内容大小,不验证依赖是否存在或模型行为是否正确。应分别检查解释器、实际 import、委托模型访问、最终结果解析和对话历史。仅打印成功形状 JSON、却没有实际执行工作的脚本不能充当有效验收 fixture。 程序失败时,使用契约支持的失败字段,并在适用时以非零退出;不要向严格的最终结果对象添加任意诊断键。诊断作为独立普通日志输出并脱敏。中断后保留原 invocation,调查 Tool 副作用再决定恢复操作。正确判断结果失败
这些场景检查结果契约,不调用模型。本地源码包测试还会损坏上传字节,要求安装失败。数据库版本测试覆盖相同内容注册、内容变化冲突、注册表重建与租户隔离;必须实际连接测试数据库执行,才能宣称持久化检查通过。早期审阅执行了本地结果与完整性检查,数据库用例因缺少配置而跳过。后续合并证据复核记录了隔离 PostgreSQL 执行:所选四个文件、16 项测试均通过,其中包含包版本持久化检查,临时 schema 已删除。兼容 API 仍受支持,本页不设定弃用或删除日期。