From 1d5bc81b386e3b6f726f6052d8f17c6000e719e3 Mon Sep 17 00:00:00 2001 From: gongzhiyong Date: Sun, 31 May 2026 22:50:24 +0800 Subject: [PATCH] docs: refresh sub runtime verification Record the 2026-05-31 production Manager smoke result for ordinary sub mode after the Agent Manager Runtime image update. Constraint: Keep ordinary sub mode separate from swarm mode and document real production ids only Confidence: high Scope-risk: narrow Not-tested: Documentation-only change; git diff --check passed --- ...de-manager-sub-swarm-progress-checklist.md | 4 +- .../heicode-desktop-sub-agile-api.md | 71 +++++++++++++------ ...通sub敏捷模式-AgentManager对接任务清单.md | 8 +-- 3 files changed, 57 insertions(+), 26 deletions(-) diff --git a/docs/heicode-manager-sub-swarm-progress-checklist.md b/docs/heicode-manager-sub-swarm-progress-checklist.md index 212ba3aa..82e20ee0 100644 --- a/docs/heicode-manager-sub-swarm-progress-checklist.md +++ b/docs/heicode-manager-sub-swarm-progress-checklist.md @@ -71,8 +71,8 @@ Heicode 桌面客户端 | timeline 聚合 | 用户态 timeline 聚合 audit、callbacks、artifacts、sk_snapshots | `AgnetGetUserDeploymentTimeline` | | SK snapshot 持久化 | 已有 `agnet_sk_snapshots` 模型和列表查询 | `heicode/model/agnet_sk_snapshot.go` | | 本地模拟事件 | 已有用户态 `simulate-events`；默认模拟会写入 callback、artifact、approval、timeline 记录，用于 Manager 自测展示链路和脱敏检查 | `AgnetSimulateUserDeploymentEvents` | -| V2 body 加密 | `/api/agnet/user/*`、`/api/heicode-auth/*` 已在生产支持；`/api/swarms` 代码已补齐同一套 V2 加密鉴权，需随下一次生产部署生效 | `heicode/middleware/auth.go`、`heicode/router/api-router.go` | -| 生产普通 sub 烟测记录 | 已有 create/detail/metrics/events/logs/artifacts/sk-snapshots/timeline/stop 链路烟测记录；本次核查确认生产 `api/status` 返回 Manager `1.4.9`，但公开 callback schema 路径当前返回 404，需重新上线或复核路由后再跑完整生产烟测 | `docs/integration/heicode-desktop-sub-agile-api.md` | +| V2 body 加密 | `/api/agnet/user/*`、`/api/heicode-auth/*`、`/api/swarms` 已按同一套 V2 设备签名和 body 加密路径设计；未加密 Web 控制台仍兼容 session + `New-Api-User` | `heicode/middleware/auth.go`、`heicode/router/api-router.go` | +| 生产普通 sub 烟测记录 | 2026-05-31 已用生产 Manager 入口完成真实普通 sub 复核：`dep_1d6d66896cc6` -> `swm_03995f7c7a27`，`gpt-5.4`，`tokens_used=2682`，`newapi_request_id=chatcmpl-DlbZce3VZnsv5DptBILFoiRYy5ZHN`，业务 `code_patch` artifact 可通过 Manager content 接口下载 | `docs/integration/heicode-desktop-sub-agile-api.md` | | PayPal/计费边界文档 | 已明确 PayPal 只是收款渠道；模型调用仍走 Heicode/NewAPI 的钱包或订阅额度；Agent 运行费用目前只有预算字段，真实收费需 Runtime usage 回传 | `docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.md` | ## 四、Manager 端还需要继续做的蜂群任务 diff --git a/docs/integration/heicode-desktop-sub-agile-api.md b/docs/integration/heicode-desktop-sub-agile-api.md index 78221d4f..c63b64ca 100644 --- a/docs/integration/heicode-desktop-sub-agile-api.md +++ b/docs/integration/heicode-desktop-sub-agile-api.md @@ -1,19 +1,20 @@ # Heicode 桌面客户端 sub 敏捷流程 API 对接文档 -更新时间：2026-05-30 +更新时间：2026-05-31 适用范围：Heicode Desktop / 本地服务对接 Heicode Manager，跑通普通 sub 模式敏捷开发流程。 Manager 生产地址：`https://code.xinghanlab.com` ## 0. 当前生产联调结论 -截至 2026-05-30，普通 sub 敏捷链路已按生产地址完成端到端联调： +截至 2026-05-31，普通 sub 敏捷链路已按生产地址完成端到端联调，并已用 Heicode Manager 生产入口复核 Runtime 新镜像修复后的真实生成链路： | 项目 | 状态 | 生产验证 | |---|---|---| -| Manager 创建 deployment | 已通过 | `POST /api/agnet/user/deployments` 返回 `accepted` | -| Agent Manager Runtime 执行 | 已通过 | Runtime 返回 `completed`，Agent 返回 `completed` | -| 模型调用 | 已通过 | 使用生产 NewAPI 已存在模型 `claude-sonnet-4-6`，渠道日志显示调用成功 | -| Callback / timeline | 已通过 | Manager 可查询 Runtime timeline 和状态 | +| Manager 创建 deployment | 已通过 | `POST /api/swarms` 返回 Manager deployment 并写入 Runtime 映射 | +| Agent Manager Runtime 执行 | 已通过 | Runtime 返回 `completed`，backend Agent 返回 `completed` | +| 模型调用 | 已通过 | `gpt-5.4` 通过生产 NewAPI 调用成功，Runtime 回传 `newapi_request_id` | +| 用量回传 | 已通过 | Runtime metrics 返回 `tokens_used=2682`，日志包含 prompt/completion/total tokens | +| Callback / timeline | 已通过 | Manager 可查询 Runtime timeline、task.completed、sk_tool.completed、artifact.created 和状态 | | Artifact 列表 | 已通过 | `GET /artifacts` 返回业务交付 artifact | | Artifact 完整内容下载 | 已通过 | `GET /artifacts/{artifact_id}/content` 返回 `HTTP 200` 和完整文本内容 | @@ -21,17 +22,23 @@ Manager 生产地址：`https://code.xinghanlab.com` | 字段 | 值 | |---|---| -| `deployment_id` | `dep_829dd2da7494` | -| `runtime_swarm_id` | `swm_0a2b712b0023` | -| `artifact_id` | `art_swm_0a2b712b0023_fullstack_1` | -| artifact content | `HTTP 200`，`text/plain; charset=utf-8`，`2436 bytes` | +| `deployment_id` | `dep_1d6d66896cc6` | +| `runtime_swarm_id` | `swm_03995f7c7a27` | +| `model` | `gpt-5.4` | +| `runtime_state` | `completed` | +| `tokens_used` | `2682` | +| `newapi_request_id` | `chatcmpl-DlbZce3VZnsv5DptBILFoiRYy5ZHN` | +| `artifact_id` | `art_swm_03995f7c7a27_backend_1` | +| `artifact_type` | `code_patch` | +| artifact content | `HTTP 200`，`text/plain; charset=utf-8`，约 `7.8 KB`，内容为多文件 Python CLI 项目交付物 | 重要修正： 1. 桌面客户端不要再使用 `agnet-model-builder`、`agnet-model-reviewer`、`agnet-model-product` 这类占位模型名。生产 NewAPI 没有这些模型，会返回 `No available channel for model ...`。 -2. 普通 sub 默认模型建议使用 `claude-sonnet-4-6`；审核类角色可使用 `claude-opus-4-7`。这两个模型当前生产 NewAPI 已有可用渠道。 +2. 普通 sub 当前优先建议使用生产已复核通过的 `gpt-5.4`。`claude-sonnet-4-6` 仍可作为 NewAPI 模型存在，但当前普通 sub Runtime 若按普通 `/v1/chat/completions` 方式调用 Claude Code 类模型，可能返回上游 400；客户端不要把该错误误判为加密或 Manager 创建失败。 3. `orchestration_plan.metadata.correlation_id` 是创建 deployment 的必填字段，必须放在 `orchestration_plan` 内，不是顶层 `metadata`。 -4. `runtime-diagnostics.warnings` 目前可能包含 `runtime_zero_model_usage`，表示 Runtime 还没有完整回传 usage/token 统计；不影响任务执行和 artifact 获取，但计费统计展示应标记为“等待 Runtime usage 回传”。 +4. 成功态不能只看 `status=completed`。客户端还应确认 `runtime_state=completed`、`artifacts.length > 0`、artifact 不是失败摘要、`tokens_used > 0`，并优先展示可下载的业务交付物。 +5. Runtime 日志已支持回传 `newapi_request_id` 和 `model_usage`。客户端应把这些字段展示在调试信息或错误详情中，便于定位模型调用问题。 ## 1. 对接目标 @@ -287,20 +294,22 @@ Manager 登录 | 对象 | ID / 结果 | |---|---| -| Manager deployment | `dep_be665a25f6bc` | -| Runtime swarm | `swm_4c471d60972f` | +| Manager deployment | `dep_1d6d66896cc6` | +| Runtime swarm | `swm_03995f7c7a27` | | detail status | `completed` | | detail phase | `deploy` | | runtime_state | `completed` | | agent state | `completed` | -| callback 数 | `9` | -| event 数 | `12` | +| model | `gpt-5.4` | +| tokens_used | `2682` | +| newapi_request_id | `chatcmpl-DlbZce3VZnsv5DptBILFoiRYy5ZHN` | +| artifact | `art_swm_03995f7c7a27_backend_1`，`code_patch` | 已确认事实： - Manager 端普通 sub 控制面已经可创建 deployment、调用 Runtime、接收 callback、反写 deployment 状态、聚合 events/timeline。 - Manager 端 callback 支持 HMAC 和旧 token 两种校验；生产当前 HMAC fallback 和 legacy token 均使用同一个值，由运维私下提供给 Agent Manager，不写入本文。 -- Agent Manager / Runtime 仍需补真实 artifact、真实 usage/cost、真实日志、失败原因和高危审批闭环；这些是 Runtime 执行数据质量，不阻塞桌面客户端按本文接口开始联调。 +- Agent Manager / Runtime 新镜像已完成真实业务 artifact、非零 usage、`newapi_request_id` 和 Runtime 日志回传的生产复核。高危审批闭环仍需按真实高危任务单独验收。 本次未由 Codex 直接跑通的步骤： @@ -312,7 +321,7 @@ Manager 登录 - 如果客户端已经有 HeicodeTask snapshot，可以直接从 `deployment-draft` 开始跑，生产已验证可通。 - 如果客户端需要从自然语言创建任务，必须先完成 Heicode 登录并拿到 `heicode_access_token`。 -- 当前 create / callback / detail / metrics / events / timeline / stop 已真实有效；artifacts / sk-snapshots 需要 Runtime 在真实任务中回写 `artifact.created` / `sk_tool.*` 后才会有数据。 +- 当前 create / callback / detail / metrics / events / timeline / artifacts / artifact content 已真实有效；SK snapshots 需要 Runtime 在真实任务中回写 `sk_tool.*` 或 snapshot 字段后才会有数据。 ### 3.4 桌面客户端联调结论 @@ -1439,9 +1448,31 @@ async function refreshSubDelivery(deploymentId: string) { 2. Manager 本地控制面可创建 `sub_mode=agile/waterfall` deployment。 3. 生产 Manager 已配置 Agent Manager Runtime，当前直接走 `http://20.212.121.126`；域名和 HTTPS 后续单独处理，不作为客户端当前接入阻塞项。 4. V2 加密 `deployment-draft` 已在生产验证通过：真实构造 `Content-Encoding: heicode-aead-v1` 请求返回 200，`sub_mode=agile`，`user_id=22`。 -5. `deployment-draft -> create -> Runtime callback -> detail -> events/timeline -> stop` 已在生产验证通过，客户端可按本文参数形状接入。 -6. `events/logs/artifacts/sk-snapshots/timeline` 查询接口已验证不报错；真实 artifact、SK 调用结果和真实成本金额需要 Agent Manager / Runtime 在真实任务中回传。 +5. `deployment-draft -> create -> Runtime callback -> detail -> events/timeline -> artifacts -> artifact content` 已在生产验证通过，客户端可按本文参数形状接入。 +6. `events/logs/artifacts/timeline` 查询接口已验证不报错；真实 artifact、`tokens_used`、`newapi_request_id` 已可从 Runtime / Manager 查询到。SK snapshots 仍取决于 Runtime 是否回写 snapshot 字段。 7. `POST /api/heicode-auth/api/user/tasks/intent` 需要桌面客户端提供 `heicode_access_token`；没有该 token 会返回 401。 8. malformed V2 请求已在生产验证会返回 `X-Heicode-Auth-Error`，客户端应把该头转成可读错误提示。 9. 当前 `GET` 查询接口没有请求 body，仍按 session + `New-Api-User` 验证；这不影响 body 加密要求，但客户端若要全链路无 cookie，需要后续补无 body 签名 GET。 10. macOS 联调前必须确认客户端已完成设备绑定；若 Manager 设备页没有 macOS 设备，模型列表 401 应优先处理客户端本地凭据和 Keychain，而不是改 Manager 模型配置。 + +### 15.1 成功和失败判断 + +客户端展示普通 sub 结果时建议使用以下判断： + +| 判断项 | 成功标准 | +|---|---| +| deployment | `status=completed` 且 `runtime_state=completed` | +| Runtime | `runtime_swarm_id` 非空，Runtime status 为 `completed` | +| Agent | 至少一个目标 Agent 为 `completed`，没有 failed agent | +| usage | `tokens_used > 0`，日志中可见 `newapi_request_id` 或 `model_usage` | +| artifact | `artifacts.length > 0`，且业务产物 `artifact_type` 为 `code_patch`、`document`、`test_report`、`deployment_manifest` 等 | +| artifact content | `GET /artifacts/{artifact_id}/content` 返回 200，内容不是 `Runtime execution failed` / `Runtime execution summary` 兜底摘要 | + +失败场景示例： + +| 场景 | 客户端提示 | +|---|---| +| `artifact_type=other` 且标题为 `Runtime execution failed` | Runtime Agent 执行失败，当前 artifact 只是失败摘要，不是业务交付物 | +| `tokens_used=0` | 模型调用未成功或 Runtime 未回传用量，需查看 logs / newapi_request_id | +| Runtime 日志出现 `504 Gateway Time-out` | Agent 调模型超时，通常不是客户端发参或加密问题 | +| Runtime 日志出现上游 `400 Bad Request` | Agent 模型调用参数/模型适配问题，需由 Runtime / Agent Manager 处理 | diff --git a/docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md b/docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md index 5cbb6f4e..0e16bfcd 100644 --- a/docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md +++ b/docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md @@ -507,10 +507,10 @@ Agent Manager 回传 usage 时建议至少包含： | 缺口 | 属于谁 | 说明 | |---|---|---| | 真实 Runtime 是否完整消费 `agile_context` | Agent Manager | 需要确认字段被使用，不只是透传 | -| 阶段状态持续回传 | Agent Manager | 当前 Manager 有接收能力，缺真实数据 | -| artifact 真实产出 | Agent Manager | 需要 Runtime 输出 Git/存储/报告 URI | +| 阶段状态持续回传 | Agent Manager | 2026-05-31 生产复核已收到 running/completed、phase、timeline、task.completed 等真实回调；后续需在更复杂多阶段任务中继续验证 | +| artifact 真实产出 | Agent Manager | 2026-05-31 生产复核已收到业务 `code_patch` artifact，并可通过 Manager content 代理下载；Git/部署 URL 类产物仍按具体任务继续验证 | | approval decision 接收路径 | Agent Manager + Manager 配置 | 需确认最终路径是 `/api/swarms/...` 还是 `/api/agnet/deployments/...` | -| 用量回传 | Agent Manager + NewAPI/CodeGW | 需要按 user/deployment/task/role 归属 | -| Agent 运行费用真实结算 | Agent Manager + Manager | 当前 Manager 有预算字段和文档口径，缺 Runtime 真实 usage，不能只按预算估算扣费 | +| 用量回传 | Agent Manager + NewAPI/CodeGW | 2026-05-31 生产复核已回传 `tokens_used=2682`、`newapi_request_id=chatcmpl-DlbZce3VZnsv5DptBILFoiRYy5ZHN`；后续需继续按 user/deployment/task/role 归属 | +| Agent 运行费用真实结算 | Agent Manager + Manager | Runtime 已能回传 token usage；真实费用结算仍需按 Manager/NewAPI 订阅/钱包规则和 Runtime usage 口径统一 | | 生产 callback schema 路由 | Manager 部署/路由 | 本地代码和测试已覆盖，2026-05-28 生产公开访问 `/api/agnet/callbacks/swarm-events/schema` 返回 404，需要重新上线或核对生产镜像/路由 | | 无 body GET 的 V2 签名 | 客户端 + Manager | 这是客户端全链路无 cookie 的后续项，不阻塞 Agent Manager 创建/回调联调 |