跳转到主要内容
在 Hexagon 上开发应用时,从这里开始阅读。这是产品集成指南,不是仓库 AGENTS.md 开发指令;当前 checkout 中的仓库指令仍约束编辑、测试、凭据与发布。本 Markdown 文件提供阅读入口,不代表已有托管文档端点或单独的机器 API。

按执行顺序查证

不要假设 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 本身可能授予访问权。
例如,客户端崩溃后 journal 留有 Run R 和已提交游标 104,意味着“从 104 之后观察 R”,不是“重新提交任务”。只留有 Session 创建意图,则意味着“调查是否已经创建成功”,不是“再分配一个 Session”。缺失不同字段,对应不同恢复动作。 仓库开发规则仍由 AGENTS.md约束,本集成指南不替代它。下一步:组合选择、HTTP 索引或对账。

带持久记录的集成算法

以下为伪代码。journal、业务授权与事务由应用实现,不是 Hexagon SDK 方法。具体 Python、TypeScript 调用见上表的构建指南及首个 Session 示例。
至少记录业务请求与所有者、Session ID、Run ID、精确提交内容和 key、事件游标、清理意图与状态、未决操作引用。资源标识保存为私有证据,不写进公开示例输出。记录时间与错误时排除 Token 和原始账户凭据。即使多个业务用户共享一个 Hexagon 租户,每次外部查询和结果交付仍需应用授权。 Run 提交幂等性不自动扩展到 Session 创建或任意 Provider 操作。事件 ID 保持数字字符串,不转换成 JavaScript Number。stream.end 等没有持久 ID 的事件不作游标检查点。事件流结束或事件分页为空,都不能替代 Run 终态查询。网络断开不取消执行。

遇到分支时改变下一步动作

正确使用示例和证据

示例有完整教程、依赖既有变量的 SDK 片段、结构示意和确定性 fixture 等不同范围,执行前先看标注和前置条件。占位连接 ID、.invalid 域名、本地镜像标签不是已部署服务。fixture 模型不证明真实模型行为,注册 Harness 不证明其镜像、Provider、协议组合可运行。 每次集成改动报告修改文件、实际命令与结果、精确测试范围、限制和清理状态,保留失败尝试。遵循测试与证据;影响共享契约时覆盖两种 SDK 旅程。不能以 Agent 生成的“测试通过”文字作为证据,应检查真实测试输出与产物。 这里链接的是仓库内文档草稿,仅链接已存在文件,不宣称公开站点、llms.txt 服务或全部规划参考页已经发布。覆盖台账用于识别尚未完成的内容,不能据此推断运行能力。 下一步:第一个 Session、后端集成、对账。