按执行顺序查证
不要假设 SDK 版本能证明所有服务端构建兼容。核对运行中 catalog 与安装 SDK 的实际签名。专门参考页尚在补齐期间,精确请求可查仓库中的 TypeScript SDK、Python SDK与 HTTP 实现。这些是源码参考,不代表提供 OpenAPI 端点。
构造调用之前先选择契约
按具体资源参考核对参数、权限、响应形状和副作用。指南负责解释如何将调用组合成应用流程,不能代替接口契约。
不能确定资源时,从 HTTP 参考索引开始。它们是与版本相关的仓库参考;改变契约时按当前检出源码核对,不通过猜测 SDK 方法名来构造端点。
journal 中的事实必须跨进程重启保留
以下是应用自己的数据要求,不是新增 Hexagon JSON schema:- 原始提交包含 Session ID、精确 input、精确 origin 和稳定幂等 key;在网络调用前保存,才能恢复丢失响应。
- Run ID 和十进制字符串事件游标分别标识已接受工作与观察进度。事件和新游标应原子保存;内存 map 不能跨 worker 重启保留。
- 创建/关闭意图与确认结果分开。operation ID、远程 resource ID 和未知结果是对账依据,不是重复变更操作的指令。
- 普通 journal 不保存鉴权材料。若必须保留预览 URL,应使用有适当访问控制的私有存储;URL 本身可能授予访问权。
104,意味着“从 104 之后观察 R”,不是“重新提交任务”。只留有 Session 创建意图,则意味着“调查是否已经创建成功”,不是“再分配一个 Session”。缺失不同字段,对应不同恢复动作。
仓库开发规则仍由 AGENTS.md约束,本集成指南不替代它。下一步:组合选择、HTTP 索引或对账。
带持久记录的集成算法
以下为伪代码。journal、业务授权与事务由应用实现,不是 Hexagon SDK 方法。具体 Python、TypeScript 调用见上表的构建指南及首个 Session 示例。
stream.end 等没有持久 ID 的事件不作游标检查点。事件流结束或事件分页为空,都不能替代 Run 终态查询。网络断开不取消执行。
遇到分支时改变下一步动作
正确使用示例和证据
示例有完整教程、依赖既有变量的 SDK 片段、结构示意和确定性 fixture 等不同范围,执行前先看标注和前置条件。占位连接 ID、.invalid 域名、本地镜像标签不是已部署服务。fixture 模型不证明真实模型行为,注册 Harness 不证明其镜像、Provider、协议组合可运行。
每次集成改动报告修改文件、实际命令与结果、精确测试范围、限制和清理状态,保留失败尝试。遵循测试与证据;影响共享契约时覆盖两种 SDK 旅程。不能以 Agent 生成的“测试通过”文字作为证据,应检查真实测试输出与产物。
这里链接的是仓库内文档草稿,仅链接已存在文件,不宣称公开站点、llms.txt 服务或全部规划参考页已经发布。覆盖台账用于识别尚未完成的内容,不能据此推断运行能力。
下一步:第一个 Session、后端集成、对账。