From 15b17f39b003431c5430ade47da1272dbbb0df77 Mon Sep 17 00:00:00 2001 From: chenchen Date: Thu, 4 Jun 2026 09:56:17 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20remove=20obsolete=20=E6=99=AE=E9=80=9A?= =?UTF-8?q?=20sub=20(old=20model)=20integration=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 普通 sub task-orchestration model was replaced by the template-agent model and its backend deleted. Removed the now-obsolete docs describing it: - heicode-desktop-sub-agile-api.md, heicode-desktop-subagile-e2e-demo.md - heicode-desktop-unified-api.md, heicode-sub-mode-flow-spec.md - 普通sub敏捷模式-AgentManager对接任务清单.md - AgentManager普通sub{产物回调缺失问题,剩余补充要求,联调整改要求}.md Fixed dangling references in the new docs (client-api / template-agent-model). Swarm (蜂群) docs kept — different mode, out of scope. Co-Authored-By: Claude Opus 4.8 --- .../AgentManager普通sub产物回调缺失问题.md | 389 ---- .../AgentManager普通sub剩余补充要求.md | 246 --- .../AgentManager普通sub联调整改要求.md | 609 ------- docs/integration/Heicode-登录接口对接文档.md | 372 ---- .../integration/heicode-desktop-client-api.md | 2 +- .../heicode-desktop-sub-agile-api.md | 1614 ----------------- .../heicode-desktop-subagile-e2e-demo.md | 232 --- .../heicode-desktop-unified-api.md | 601 ------ .../heicode-hm-template-agent-model.md | 2 +- .../integration/heicode-sub-mode-flow-spec.md | 487 ----- ...通sub敏捷模式-AgentManager对接任务清单.md | 516 ------ 11 files changed, 2 insertions(+), 5068 deletions(-) delete mode 100644 docs/integration/AgentManager普通sub产物回调缺失问题.md delete mode 100644 docs/integration/AgentManager普通sub剩余补充要求.md delete mode 100644 docs/integration/AgentManager普通sub联调整改要求.md delete mode 100644 docs/integration/Heicode-登录接口对接文档.md delete mode 100644 docs/integration/heicode-desktop-sub-agile-api.md delete mode 100644 docs/integration/heicode-desktop-subagile-e2e-demo.md delete mode 100644 docs/integration/heicode-desktop-unified-api.md delete mode 100644 docs/integration/heicode-sub-mode-flow-spec.md delete mode 100644 docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md diff --git a/docs/integration/AgentManager普通sub产物回调缺失问题.md b/docs/integration/AgentManager普通sub产物回调缺失问题.md deleted file mode 100644 index bee5ecf3..00000000 --- a/docs/integration/AgentManager普通sub产物回调缺失问题.md +++ /dev/null @@ -1,389 +0,0 @@ -# Agent Manager 普通 sub 产物回调缺失问题 - -更新时间：2026-05-29 -发给：Agent Manager / Agent Runtime 负责人 -范围：普通 sub 敏捷模式，不包含 HeiCode-Swarm 独立蜂群 Runtime。 - -## 1. 问题现象 - -Heicode 桌面客户端执行任务： - -```text -给我做一个 oracle 云的代理商网站，做前后端分离 -``` - -客户端最终只显示： - -```text -Swarm initialized and planning started -Swarm execution completed -completed -``` - -但右侧运行数据中： - -```text -ARTIFACTS = 0 -SK SNAPSHOTS = 0 -``` - -用户无法看到真正交付物，例如代码分支、提交、预览地址、部署清单、文档或最终结果摘要。 - -## 2. 本次链路归属 - -本次不是走 HeiCode-Swarm 独立蜂群 Runtime。 - -Heicode Manager 生产配置确认当前普通 sub 走： - -```text -AGENT_RUNTIME_BASE_URL=http://20.212.121.126 -AGENT_RUNTIME_CREATE_PATH=/api/swarms -``` - -`SWARM_RUNTIME_BASE_URL` 当前为空。 - -因此本问题归属： - -```text -Heicode 桌面客户端 - -> Heicode Manager 生产 - -> Agent Manager / Agent Runtime 普通 sub 入口 - -> Heicode Manager callback - -> 桌面客户端查询 artifacts/timeline -``` - -不是独立蜂群 Runtime `http://52.139.240.116:8000` 的问题。 - -## 3. Heicode Manager 生产侧实查结果 - -Heicode Manager deployment： - -```text -dep_fa4f43da9e0a -``` - -Runtime 返回并保存的 swarm/deployment id： - -```text -swm_f9ce3f6c90aa -``` - -Heicode Manager 生产库记录： - -| 字段 | 值 | -|---|---| -| `deployment_id` | `dep_fa4f43da9e0a` | -| `status` | `completed` | -| `phase` | `deploy` | -| `runtime_state` | `completed` | -| `runtime_deployment_id` | `swm_f9ce3f6c90aa` | -| `runtime_swarm_id` | `swm_f9ce3f6c90aa` | -| `created_at_text` | `2026-05-29T08:40:50Z` | -| `updated_at_text` | `2026-05-29T08:40:51Z` | - -Heicode Manager 收到的 callback 类型统计： - -| callback event_type | count | -|---|---:| -| `agent.started` | 2 | -| `budget.alert` | 1 | -| `deployment.status_changed` | 3 | -| `phase.changed` | 2 | -| `timeline.updated` | 2 | - -关键缺失： - -```text -artifact.created = 0 -task.completed = 0 -sk_tool.completed = 0 -``` - -Heicode Manager artifact 表查询结果： - -```text -agent_artifacts where deployment_id = 'dep_fa4f43da9e0a' -=> 0 rows -``` - -说明：Heicode Manager 没有收到任何产物事件，因此客户端显示 `ARTIFACTS 0` 是真实数据，不是客户端漏显示。 - -## 4. Heicode Manager callback 接收链路是通的 - -生产日志中，Agent Manager 在任务完成时间段连续请求： - -```text -POST /api/agent/callbacks/swarm-events -``` - -HTTP 状态均为： - -```text -200 -``` - -这说明： - -1. Agent Manager 能打到 Heicode Manager callback 地址。 -2. Heicode Manager 没有拒收这些 callback。 -3. 问题不是 callback 鉴权失败。 -4. 问题不是 Heicode Manager callback endpoint 不通。 - -但 callback 事件内容中没有 `artifact.created`，因此 Heicode Manager 无法落库 artifacts。 - -## 5. Agent Manager 侧直查结果 - -直查 Agent Manager Runtime： - -```http -GET http://20.212.121.126/api/swarms/swm_f9ce3f6c90aa -``` - -返回关键信息： - -```json -{ - "deployment_id": "swm_f9ce3f6c90aa", - "swarm_id": "swm_f9ce3f6c90aa", - "status": "completed", - "phase": "planning", - "progress": 100, - "agents": [ - { - "agent_id": "agi_backend_59717a71", - "role": "backend", - "status": "running", - "output": null - }, - { - "agent_id": "agi_frontend_3063c6c9", - "role": "frontend", - "status": "running", - "output": null - } - ], - "metrics": { - "total_messages": 0, - "tokens_used": 0 - }, - "artifacts": [] -} -``` - -直查日志： - -```http -GET http://20.212.121.126/api/swarms/swm_f9ce3f6c90aa/logs -``` - -返回： - -```text -Logs will be fetched from K8s in Phase 2 -``` - -这说明 Agent Manager 自己也没有保存或返回真实产物。 - -## 6. 当前判断 - -本问题根因不在 Heicode Manager，也不在桌面客户端。 - -当前证据指向 Agent Manager / Agent Runtime： - -1. Runtime 将 deployment 标记为 `completed`。 -2. Runtime 自身返回 `artifacts: []`。 -3. Runtime 没有 callback `artifact.created`。 -4. Runtime agents 仍显示 `running`，但 deployment 已 `completed`，状态不一致。 -5. Runtime metrics 中 `tokens_used=0`、`total_messages=0`，没有真实模型执行用量。 -6. Runtime logs 仍是占位文本，没有真实 K8s / Agent 日志。 - -因此客户端只能展示完成状态，不能展示交付结果。 - -## 7. Agent Manager 需要修复的内容 - -### P0：任务完成必须回调 artifact - -普通 sub 任务完成时，Agent Manager 必须向 Heicode Manager callback： - -```text -POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events -event_type = artifact.created -``` - -即使没有 Git 分支，也必须返回一个可展示的交付物。 - -建议 artifact 类型： - -| 场景 | artifact_type | uri / 内容 | -|---|---|---| -| 代码已提交 | `code_patch` | `git://repo#` 或 repo URL + branch + commit | -| 生成了前后端项目 | `deployment_manifest` | 项目结构、启动方式、服务端口、部署说明 | -| 只产出设计/说明 | `document` | 文档地址或文档摘要 | -| 无法生成正式产物 | `other` | 明确失败原因、已完成内容、下一步动作 | - -最低要求：不能只发 `completed`，必须有一个 `artifact.created` 或明确失败事件。 - -### P0：completed 状态与 Agent 状态一致 - -当前 Runtime 返回： - -```text -deployment.status = completed -agents[].status = running -``` - -需要修复为一致状态： - -1. 如果 deployment completed，则相关 agent 应为 `completed`、`stopped` 或明确的终态。 -2. 如果 agent 仍 running，则 deployment 不应为 completed。 -3. 如果任务未真实执行，应返回 `failed` 或 `blocked`，并说明原因。 - -### P0：回调 task.completed / task.failed - -当前 Heicode Manager 没收到： - -```text -task.completed -task.failed -task.blocked -``` - -Agent Manager 应在每个子 Agent / 子任务结束时回调任务状态，至少包含： - -```json -{ - "event_type": "task.completed", - "deployment_id": "dep_fa4f43da9e0a", - "swarm_id": "swm_f9ce3f6c90aa", - "task_id": "task-backend-xxx", - "agent_instance_id": "agi_backend_59717a71", - "payload": { - "task_id": "task-backend-xxx", - "agent_role": "backend", - "status": "completed", - "summary": "后端实现完成，产物见 artifact" - } -} -``` - -### P1：回传真实 usage / cost - -当前 Runtime 返回： - -```text -tokens_used = 0 -total_messages = 0 -``` - -如果任务真实调用了模型，应回传： - -```json -{ - "model_usage": { - "input_tokens": 1234, - "output_tokens": 5678, - "total_tokens": 6912, - "model_cost_usd": 0.0123, - "model_id": "xxx" - } -} -``` - -如果没有真实调用模型，应明确返回 `blocked` 或 `failed`，不能标记为正常 completed。 - -### P1：提供真实日志 - -当前日志仍是： - -```text -Logs will be fetched from K8s in Phase 2 -``` - -需要至少返回可排障日志摘要： - -1. Agent 是否启动成功。 -2. 是否领取任务。 -3. 是否调用模型。 -4. 是否生成文件/分支/产物。 -5. 失败原因。 - -## 8. 建议的 artifact.created callback 示例 - -```json -{ - "event_id": "evt_artifact_", - "event_type": "artifact.created", - "deployment_id": "dep_fa4f43da9e0a", - "swarm_id": "swm_f9ce3f6c90aa", - "agent_instance_id": "agi_backend_59717a71", - "task_id": "task-backend-001", - "occurred_at": "2026-05-29T08:40:51Z", - "correlation_id": "corr_xxx", - "source": "agent-manager", - "payload": { - "artifact_id": "art_swm_f9ce3f6c90aa_backend_001", - "artifact_type": "code_patch", - "title": "Oracle 云代理商网站后端实现", - "summary": "已生成后端接口、数据模型和启动说明", - "uri": "git://repo#feature/swm_f9ce3f6c90aa", - "checksum": "commit_sha_if_available", - "metadata": { - "redacted": true, - "agent_role": "backend", - "runtime_deployment_id": "swm_f9ce3f6c90aa" - } - } -} -``` - -如果没有 Git 分支，也可以先回： - -```json -{ - "event_type": "artifact.created", - "deployment_id": "dep_fa4f43da9e0a", - "swarm_id": "swm_f9ce3f6c90aa", - "payload": { - "artifact_id": "art_swm_f9ce3f6c90aa_summary", - "artifact_type": "document", - "title": "任务执行结果摘要", - "summary": "Runtime 已完成任务，但未返回 Git 分支。这里应写清生成内容、文件位置或未生成原因。", - "uri": "runtime://swm_f9ce3f6c90aa/artifacts/summary", - "metadata": { - "redacted": true - } - } -} -``` - -## 9. 验收标准 - -修复后请用同类任务重新跑一次： - -```text -给我做一个 oracle 云的代理商网站，做前后端分离 -``` - -必须满足： - -| 验收项 | 标准 | -|---|---| -| Runtime 状态 | deployment 和 agents 状态一致 | -| callback | Heicode Manager 收到 `artifact.created` | -| Manager artifacts | `/api/agent/user/deployments/{deployment_id}/artifacts` 返回 total > 0 | -| 客户端展示 | 右侧 `ARTIFACTS` 不再是 0 | -| 交付物 | 能看到 Git 分支、提交、预览地址、部署清单或最终结果文档 | -| usage | 如果真实调用模型，tokens/cost 不应一直为 0 | -| logs | 不再只有 Phase 2 占位文本 | - -## 10. 当前结论 - -Heicode Manager 和桌面客户端当前表现是正确反映 Runtime 数据。 - -真正缺口在 Agent Manager / Agent Runtime： - -```text -任务被标记 completed，但 Runtime 没有生成或回传 artifact.created。 -``` - -请 Agent Manager 优先修复任务完成后的产物生成、产物回调、状态一致性、usage 和日志回传。 diff --git a/docs/integration/AgentManager普通sub剩余补充要求.md b/docs/integration/AgentManager普通sub剩余补充要求.md deleted file mode 100644 index 1ffb0389..00000000 --- a/docs/integration/AgentManager普通sub剩余补充要求.md +++ /dev/null @@ -1,246 +0,0 @@ -# Agent Manager 普通 sub 剩余补充要求 - -更新时间：2026-05-28 -发给：Agent Manager / Agent Runtime 负责人 -范围：普通 sub 敏捷开发模式，不包含蜂群模式完整 task graph。 - -## 1. 当前已验证事实 - -Heicode Manager 生产版本 `1.4.19` 已完成并验证以下链路： - -| 项目 | 状态 | 生产验证 | -|------|------|----------| -| Manager 创建普通 sub run | 已跑通 | `POST https://code.xinghanlab.com/api/swarms` 返回 `dep_*` | -| Manager 调 Agent Manager | 已跑通 | Agent Manager 返回 `runtime_swarm_id=swm_*` | -| Agent Manager 自动 callback | 已跑通 | Manager `events/timeline` 可查到 callback | -| callback HMAC fallback | 已跑通 | 生产 callback 可验签入库 | -| Manager 状态反写 | 已跑通 | callback 后 `deployment.status/phase/runtime_state/agent_instances` 会更新 | -| billing_context 字段透传 | 已跑通 | `default_model_id/allowed_model_ids/secret_ref` 已保留 | - -最新生产烟测样例： - -| 字段 | 值 | -|------|----| -| Manager deployment | `dep_be665a25f6bc` | -| Runtime swarm | `swm_4c471d60972f` | -| Manager detail status | `completed` | -| Manager detail phase | `deploy` | -| Manager runtime_state | `completed` | -| Manager agent state | `completed` | -| Manager callback 数 | `9` | -| Manager event 数 | `12` | - -因此，当前剩余问题主要不在 Manager 接收链路，而在 Agent Manager 真实执行数据、状态一致性、产物和用量回传。 - -## 2. Agent Manager 必须补充的 P0 - -| 优先级 | 缺口 | 当前实测表现 | Agent Manager 需要补什么 | 验收标准 | -|--------|------|--------------|---------------------------|----------| -| P0 | Runtime 状态一致性 | 直连 `GET /api/swarms/{swarm_id}/status` 返回整体 `completed`，但 `agents[].status` 仍是 `running` | 整体完成时同步更新 agent 状态，或发送 `agent.completed` callback | status 接口中整体和 agent 状态一致；Manager 不再需要兜底收敛 | -| P0 | 真实 artifact 回传 | Manager 收到 callback，但 `/artifacts` 仍为 `[]` | 执行完成时回调 `artifact.created`，至少包含摘要型交付物 | Manager `/artifacts` 至少有 1 条真实 artifact | -| P0 | 真实 usage / cost 回传 | `tokens_used=0`，budget callback 中 token/cost/runtime 多为 0 | 回传模型 token、模型成本、runtime 秒数、资源使用 | Manager timeline 中能看到非 0 或明确的真实 usage 字段 | -| P0 | 真实日志 | `/logs` 返回占位文本 `Logs will be fetched from K8s in Phase 2` | 接入真实 Pod/Runtime 日志或回调日志摘要 | `GET /logs` 返回真实执行日志或明确失败原因 | -| P0 | 阶段推进语义 | callback 有 phase/timeline，但当前非常短，直接 completed | 普通 sub 应按需求、设计、开发、测试、部署阶段推进 | 至少能看到 `requirements/design/development/testing/deploy` 中的真实阶段变化 | -| P0 | 失败原因回传 | 当前成功场景没有问题，但失败链路未验证 | 失败时回调 `deployment.status_changed` + `agent.crashed` 或 `sk_tool.failed` | Manager detail 出现 `failed` 和可读 `failure_reason` | - -## 3. Agent Manager 应补充的 P1 - -| 优先级 | 缺口 | 要求 | 验收标准 | -|--------|------|------|----------| -| P1 | SK 工具调用展示 | 回调 `sk_tool.called/completed/failed`，参数和结果必须脱敏 | Manager `/sk-snapshots` 或 timeline 能看到工具调用记录 | -| P1 | 高危审批闭环 | 高危动作回调 `approval.requested`，等待 Manager/客户端 approve/reject 后继续或停止 | approve 后 Runtime 继续，reject 后 Runtime 停止或跳过高危动作 | -| P1 | stop 后真实停止 | Manager stop 会调用 Runtime stop | stop 后 status 为 `stopped`，不再继续发 running/completed callback | -| P1 | 幂等创建稳定性 | 同一个 `X-Idempotency-Key` 不重复创建 | 重放创建请求返回同一个 run | -| P1 | callback 重试/死信 | 文档写了重试/死信，但也写失败只 warning | 明确当前真实策略；失败后至少可人工重放 | -| P1 | runtime_id 字段稳定 | 当前 Manager 可兼容 `deployment_id=swm_*` | 后续响应和 callback 统一携带 `deployment_id`、`swarm_id`、`correlation_id` | - -## 4. Callback 最低要求 - -Manager callback 地址： - -```text -https://code.xinghanlab.com/api/agent/callbacks/swarm-events -``` - -创建 run 后，Agent Manager 至少需要主动回调这些事件： - -| 事件 | 何时发送 | payload 最低字段 | -|------|----------|------------------| -| `deployment.status_changed` | accepted/running/completed/failed/stopped | `status` | -| `phase.changed` | 普通 sub 阶段变化 | `stage`、`checkpoint`、`summary` | -| `timeline.updated` | 用户可读进度 | `title`、`summary`、`stage`、`checkpoint` | -| `agent.started` | 子 Agent 开始 | `agent_role`、`status` | -| `agent.completed` | 子 Agent 完成 | `agent_role`、`status` | -| `agent.crashed` | 子 Agent 异常 | `agent_role`、`reason` | -| `artifact.created` | 产生中间或最终交付物 | `artifact_id`、`artifact_type`、`title`、`summary`、`uri` | -| `budget.alert` | 用量更新或预算告警 | `model_tokens`、`model_cost_usd`、`runtime_seconds`、`consumed_usd` | -| `sk_tool.completed` | SK 工具成功 | `tool_name`、`tool_invocation_id`、`summary` | -| `sk_tool.failed` | SK 工具失败 | `tool_name`、`tool_invocation_id`、`reason` | -| `approval.requested` | 需要高危审批 | `approval_id`、`operation`、`risk_level`、`reason` | - -## 5. Artifact 最低格式 - -普通 sub 完成时至少回写一个 artifact： - -```json -{ - "event_type": "artifact.created", - "deployment_id": "dep_xxx", - "swarm_id": "swm_xxx", - "agent_instance_id": "agi_backend_001", - "payload": { - "artifact_id": "art_dep_xxx_summary", - "artifact_type": "test_report", - "title": "普通 sub 执行结果", - "summary": "本轮任务完成了哪些内容、测试结果、剩余风险", - "uri": "azblob://heicode-artifacts/dep_xxx/report.json", - "stage": "deploy", - "checkpoint": "completed", - "metadata": { - "agent_role": "backend", - "redacted": true - } - } -} -``` - -要求： - -- `summary` 可直接展示给用户。 -- 不允许出现明文 token、password、secret、private key、connection string。 -- 大文件只传 URI 和摘要，不在 callback body 内联完整内容。 - -## 6. Usage / Cost 最低格式 - -Agent Manager 需要让 Manager 能区分预算和真实消耗。 - -```json -{ - "event_type": "budget.alert", - "deployment_id": "dep_xxx", - "swarm_id": "swm_xxx", - "payload": { - "billing_source": "newapi", - "model_id": "model-runtime-smoke", - "prompt_tokens": 1200, - "completion_tokens": 800, - "model_tokens": 2000, - "model_cost_usd": 0.012, - "runtime_seconds": 42, - "cpu_core_seconds": 21, - "memory_mb_seconds": 86016, - "consumed_usd": 0.012, - "budget": { - "max_cost_usd": 0.05, - "remaining_usd": 0.038 - } - } -} -``` - -如果当前测试任务确实没有模型调用，也需要明确回传： - -```json -{ - "model_tokens": 0, - "model_cost_usd": 0, - "runtime_seconds": 42, - "billing_source": "runtime_no_model_call" -} -``` - -不能只返回全 0 又没有解释。 - -## 7. 状态一致性要求 - -当前实测中 Agent Manager 状态存在矛盾： - -```json -{ - "status": "completed", - "agents": [ - { - "status": "running" - } - ], - "tokens_used": 0, - "artifacts": [] -} -``` - -需要改为： - -```json -{ - "status": "completed", - "phase": "deploy", - "progress": 100, - "agents": [ - { - "status": "completed" - } - ], - "metrics": { - "tokens_used": 2000, - "elapsed_seconds": 42 - }, - "artifacts": [ - { - "artifact_id": "art_xxx", - "artifact_type": "test_report" - } - ] -} -``` - -如果执行失败，则整体和 agent 都要能表达失败： - -```json -{ - "status": "failed", - "error_message": "模型调用失败或资源授权不足", - "agents": [ - { - "status": "failed", - "error_message": "具体失败原因" - } - ] -} -``` - -## 8. 联调验收步骤 - -Agent Manager 补完后，按以下步骤验收： - -1. Heicode Manager 通过 `POST /api/swarms` 创建普通 sub run。 -2. Manager 返回 `deployment_id=dep_*`。 -3. Runtime 返回并持久化 `runtime_swarm_id=swm_*`。 -4. Agent Manager 主动 callback： - - `deployment.status_changed` - - `phase.changed` - - `timeline.updated` - - `agent.started` - - `agent.completed` - - `artifact.created` - - `budget.alert` -5. Manager 查询： - - `/api/agent/user/deployments/{deployment_id}` - - `/events` - - `/timeline` - - `/artifacts` - - `/sk-snapshots` -6. 期望结果： - - detail 状态为真实 Runtime 状态。 - - timeline 有阶段推进。 - - artifacts 有真实产物。 - - usage 有可解释的真实消耗。 - - 不出现明文密钥。 - -## 9. 当前非阻塞但需记录 - -| 项目 | 当前状态 | 说明 | -|------|----------|------| -| Agent Manager 域名 | 暂未作为联调依赖 | 当前统一使用 `http://20.212.121.126` | -| Azure Key Vault | Manager 侧 VM Managed Identity 未正式配好 | 当前 callback 使用 HMAC fallback 已跑通；正式 Key Vault 需后续云资源配置 | -| Manager 状态兜底 | 已完成 | Manager `1.4.19` 会根据 callback 收敛 detail 状态，但 Runtime 仍应修正自身状态 | - diff --git a/docs/integration/AgentManager普通sub联调整改要求.md b/docs/integration/AgentManager普通sub联调整改要求.md deleted file mode 100644 index 2bb7449e..00000000 --- a/docs/integration/AgentManager普通sub联调整改要求.md +++ /dev/null @@ -1,609 +0,0 @@ -# Agent Manager 普通 sub 联调整改要求 - -更新时间：2026-05-28 -发给：Agent Manager / Agent Runtime 负责人 -范围：Heicode Manager 普通 sub 敏捷模式联调，不包含蜂群模式完整 task graph 的额外能力。 - -## 1. 当前结论 - -Agent Manager 新版文档 `HEICODE_API_INTEGRATION(5).md` 已经补充了 Runtime 主动 callback、HMAC、artifact、timeline、SK snapshot 等内容，方向基本对齐 Heicode Manager。 - -按 2026-05-28 生产实测，Manager 与 Agent Manager 的普通 sub 核心通讯链路已经跑通，但还不能认为“真实开发执行结果”完整闭环。当前结论是： - -1. Agent Manager 当前联调统一使用 IP `http://20.212.121.126`；域名 `https://agent-manager.taijiagent.com` 后续解析和证书就绪后再切换，不作为当前联调阻塞项。 -2. Manager 生产已切到 `/api/swarms` 创建入口，并验证能拿到 `runtime_swarm_id=swm_*`。 -3. Agent Manager 自动 callback 已能写入 Manager `events/timeline`，Manager `1.4.19` 开始会把 callback 反写到 deployment 快照。 -4. 当前仍缺真实产物和真实用量：Agent Manager status 接口返回 `tokens_used=0`、`artifacts=[]`，并出现整体 `completed` 但 agent 仍 `running` 的状态不一致。 -5. 文档写了 callback 重试和死信，但同时又写“发送失败只 warning”，需要明确当前真实实现。 - -Heicode Manager 侧已确认： - -- `POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events` 生产路由在线。 -- callback 支持 HMAC 和旧 token 兼容；当前生产为了先跑通自动 callback，已配置 HMAC fallback。 -- `GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema` 已由 Manager 提供，用于联调前核对事件类型和必填字段。 -- Manager 可接收 `deployment.status_changed`、`phase.changed`、`timeline.updated`、`agent.started/completed/crashed`，并在 `1.4.19` 反写 deployment 详情状态。 - -## 2. Agent Manager 必须整改的 P0 - -| 优先级 | 事项 | 当前问题 | 要求 | -|---|---|---|---| -| P0 | 固定联调地址 | 当前阶段约定先走 IP，后续再切域名 | 文档和配置先统一使用 `http://20.212.121.126`；域名切换另行确认 | -| P0 | 创建普通 sub deployment | `/api/swarms` 已能创建并返回 `swm_*` | 保持幂等和字段稳定，后续域名切换不能破坏 | -| P0 | deployment detail | Manager 已能记录 callback；Agent Manager status 仍有 `completed` 与 agent `running` 不一致 | 返回真实 phase、agent 状态、失败原因和更新时间 | -| P0 | deployment stop | `/api/agent/deployments/{deployment_id}/stop` 已可用 | 停止后 Runtime 真实停止，并回调 stopped 事件 | -| P0 | callback 主动推送 | 已验证 status/phase/timeline/agent/budget callback 能进入 Manager | 继续补 artifact、SK、approval 的真实运行数据 | -| P0 | usage 回传 | 当前 budget callback 中 token/cost/runtime 多为 0 | 通过 callback 或事件接口回传真实 token、成本、运行时长、资源使用 | - -## 3. 推荐接口契约 - -### 3.1 健康检查 - -```http -GET /api/agent/health -``` - -要求： - -- 不要求业务认证。 -- 返回 200。 -- 响应中包含 `success=true` 和 `data.status=healthy`。 - -### 3.2 创建普通 sub 运行 - -普通 sub 当前生产联调使用 Agent Manager `/api/agent/deployments`，蜂群 `/api/swarms` 另见 `AgentManager蜂群Runtime接口实现要求.md`。 - -```http -POST /api/agent/deployments -Authorization: Bearer -Content-Type: application/json -X-User-ID: -X-Binding-Scope: -X-Correlation-ID: -X-Idempotency-Key: -``` - -请求体示例： - -```json -{ - "orchestration_plan": { - "intent_id": "task_123", - "template_hint": "heicode-task", - "objective": "完成本轮普通 sub 敏捷任务", - "sub_mode": "agile", - "risk_level": "medium", - "budget": { - "max_tokens": 120000, - "max_cost_usd": 8, - "max_duration_sec": 3600 - }, - "user_context": { - "user_id": "123", - "channel_id": "heicode", - "binding_scope": "task-task-123" - }, - "billing_context": { - "provider": "newapi", - "default_model_id": "model_xxx", - "allowed_model_ids": ["model_xxx"], - "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key" - }, - "agile_context": { - "iteration": "2026-05-28", - "stage": "development", - "checkpoint": "draft_created", - "acceptance_criteria": [ - "Runtime 接收创建请求", - "Runtime 主动回调 phase/timeline/artifact", - "Manager 页面和接口可查到回调数据", - "不出现明文密钥" - ], - "next_action": "continue", - "requires_user_approval": false - }, - "agents": [ - { - "role": "backend" - }, - { - "role": "frontend" - }, - { - "role": "reviewer" - } - ], - "resource_grants": [] - }, - "callback": { - "url": "https://code.xinghanlab.com/api/agent/callbacks/swarm-events", - "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key", - "subscribed_events": [ - "deployment.status_changed", - "phase.changed", - "timeline.updated", - "agent.started", - "agent.completed", - "sk_tool.called", - "sk_tool.completed", - "sk_tool.failed", - "approval.requested", - "budget.alert", - "artifact.created" - ] - } -} -``` - -成功响应必须包含： - -```json -{ - "deployment_id": "dep_runtime_123", - "status": "initializing", - "agent_instances": [ - { - "agent_instance_id": "agi_backend_001", - "role": "backend", - "status": "pending" - } - ], - "created_at": "2026-05-28T07:30:00Z", - "estimated_ready_at": "2026-05-28T07:32:00Z" -} -``` - -要求： - -1. `deployment_id` 必须可用于 `/api/agent/deployments/{deployment_id}`、`/api/agent/deployments/{deployment_id}/stop`。 -2. 同一个 `X-Idempotency-Key` 重复请求必须返回同一个运行，不应重复创建。 -3. 请求缺少 `orchestration_plan`、`callback.url`、`sub_mode`、`user_context` 时必须返回 4xx。 - -### 3.3 查询普通 sub deployment - -```http -GET /api/agent/deployments/{deployment_id} -Authorization: Bearer -``` - -响应示例： - -```json -{ - "deployment_id": "dep_runtime_123", - "status": "running", - "phase": "development", - "agent_instances": [ - { - "agent_instance_id": "agi_backend_001", - "role": "backend", - "status": "running", - "current_task": "实现接口" - } - ], - "created_at": "2026-05-28T07:30:00Z", - "updated_at": "2026-05-28T07:31:00Z" -} -``` - -### 3.4 停止普通 sub deployment - -```http -POST /api/agent/deployments/{deployment_id}/stop -Authorization: Bearer -Content-Type: application/json -``` - -请求体： - -```json -{ - "reason": "Heicode Manager requested stop", - "manager_deployment_id": "dep_manager_123" -} -``` - -响应示例： - -```json -{ - "deployment_id": "dep_runtime_123", - "status": "stopped", - "stopped_at": "2026-05-28T07:40:00Z" -} -``` - -要求： - -- 停止后不再继续执行任务。 -- 停止后可以继续查询状态。 -- 停止成功后建议 callback 一条 `deployment.status_changed`，状态为 `stopped`。 - -## 4. Callback 要求 - -Manager 生产 callback 地址： - -```text -https://code.xinghanlab.com/api/agent/callbacks/swarm-events -``` - -### 4.1 认证方式 - -优先使用 HMAC： - -```http -X-Agent-Event-Id: evt_xxx -X-Agent-Timestamp: -X-Agent-Signature: sha256= -X-Correlation-ID: -Content-Type: application/json -``` - -签名规则： - -```text -signature_payload = timestamp + "." + event_id + "." + raw_body -signature = HMAC_SHA256(callback_signing_secret, signature_payload) -``` - -过渡期可使用旧 token： - -```http -X-Agent-Service-Token: -``` - -不要把真实 token 写入文档、日志或 artifact。 - -### 4.2 必须回调的事件 - -普通 sub 最少需要以下事件： - -| 事件 | 目的 | 最低要求 | -|---|---|---| -| `deployment.status_changed` | 整体运行状态 | `status`、`stage`、`checkpoint` | -| `phase.changed` | 普通 sub 阶段推进 | `stage`、`checkpoint`、`progress_pct` | -| `timeline.updated` | 客户端可展示反馈 | `title`、`summary`、`stage`、`checkpoint` | -| `agent.started` | Agent 开始工作 | `agent_role`、`task_id` | -| `sk_tool.called` | 工具调用开始 | `tool_name`、脱敏参数摘要 | -| `sk_tool.completed` | 工具调用成功 | `tool_name`、耗时、摘要、可选 artifact 引用 | -| `sk_tool.failed` | 工具调用失败 | `tool_name`、脱敏错误 | -| `artifact.created` | 中间/最终产物 | `artifact_id`、`artifact_type`、`title`、`summary`、`uri` | -| `approval.requested` | 高危操作审批 | `operation`、`resource_type`、`risk_level`、`reason` | -| `budget.alert` | 预算告警/用量 | usage / cost 摘要 | - -### 4.3 Callback body 示例 - -```json -{ - "event_id": "evt_phase_001", - "event_type": "phase.changed", - "deployment_id": "dep_manager_123", - "agent_instance_id": "agi_backend_001", - "occurred_at": "2026-05-28T07:35:00Z", - "correlation_id": "corr_123", - "source": "agent-manager", - "payload": { - "stage": "development", - "checkpoint": "agent_running", - "progress_pct": 35, - "summary": "backend agent 已开始实现接口" - } -} -``` - -artifact 示例： - -```json -{ - "event_id": "evt_artifact_001", - "event_type": "artifact.created", - "deployment_id": "dep_manager_123", - "agent_instance_id": "agi_backend_001", - "occurred_at": "2026-05-28T07:38:00Z", - "correlation_id": "corr_123", - "source": "agent-manager", - "payload": { - "artifact_id": "art_backend_patch_001", - "artifact_type": "code_patch", - "title": "Backend API patch", - "summary": "新增普通 sub Runtime 联调接口", - "uri": "azblob://heicode-artifacts/task-123/backend.patch", - "mime_type": "text/x-diff", - "size_bytes": 18420, - "stage": "development", - "checkpoint": "artifact_ready", - "metadata": { - "agent_role": "backend", - "redacted": true - } - } -} -``` - -### 4.4 明文密钥禁止项 - -以下字段不能出现在 callback、artifact metadata、timeline、日志中： - -- `password` -- `token` -- `secret` -- `private_key` -- `connection_string` -- `access_key` -- 明文数据库连接串 -- 明文模型网关 key -- 明文 Git token - -长期凭据只能传： - -```text -azkv:///secrets/ -``` - -## 5. Usage / Cost 回传要求 - -Agent Manager 文档当前缺少真实 usage 字段。普通 sub 后续要支持模型费用、运行费用和审计归属，Runtime 必须回传至少以下字段。 - -可通过 `budget.alert`、`timeline.updated` 或专门的 `usage.updated` 事件回传。如果新增 `usage.updated`，需要提前和 Manager 对齐 schema。 - -```json -{ - "event_id": "evt_usage_001", - "event_type": "budget.alert", - "deployment_id": "dep_manager_123", - "agent_instance_id": "agi_backend_001", - "occurred_at": "2026-05-28T07:39:00Z", - "correlation_id": "corr_123", - "source": "agent-manager", - "payload": { - "model_id": "model_xxx", - "model_tokens": 12000, - "prompt_tokens": 8000, - "completion_tokens": 4000, - "model_cost_usd": 0.23, - "runtime_seconds": 180, - "cpu_core_seconds": 36, - "memory_mb_seconds": 92160, - "billing_source": "newapi", - "budget": { - "max_tokens": 120000, - "max_cost_usd": 8, - "consumed_usd": 0.23, - "remaining_usd": 7.77 - } - } -} -``` - -字段要求： - -| 字段 | 必需 | 说明 | -|---|---|---| -| `model_id` | 是 | 本次 Agent 调用的模型 | -| `model_tokens` | 是 | 总 token | -| `prompt_tokens` | 建议 | 输入 token | -| `completion_tokens` | 建议 | 输出 token | -| `model_cost_usd` | 是 | 可归属的模型成本 | -| `runtime_seconds` | 是 | Agent 实际运行秒数 | -| `cpu_core_seconds` | 建议 | 集群资源成本核算 | -| `memory_mb_seconds` | 建议 | 集群资源成本核算 | -| `billing_source` | 是 | `newapi` / `manager_wallet` / `manager_subscription` / 其他约定 | - -注意：`budget.max_cost_usd` 是预算上限，不是已扣费金额。不能把预算当真实账单。 - -## 6. Approval Decision 接收要求 - -Manager 端已有 approval、credential lease、approve/reject 和 Runtime decision adapter。Agent Manager 需要提供接收审批结果的接口。 - -推荐接口： - -```http -POST /api/agent/deployments/{deployment_id}/approvals/{approval_id} -Authorization: Bearer -Content-Type: application/json -``` - -请求体： - -```json -{ - "approval_id": "apr_123", - "decision": "approved", - "manager_deployment_id": "dep_manager_123", - "runtime_deployment_id": "dep_runtime_123", - "operation": "git.write", - "resource_type": "git", - "resource_id": "repo_main", - "risk_level": "high", - "requires_credential": true, - "credential_ref": "lease://agent/cred_123", - "lease_id": "lease_123", - "lease_expires_at": 1770000000000, - "decided_by": "user_123", - "reason": "允许本次写入", - "decided_at": 1770000000000 -} -``` - -要求： - -- `approved` 后 Runtime 继续对应高危动作。 -- `rejected` 后 Runtime 停止该动作并回调 `timeline.updated` 或 `sk_tool.failed`。 -- 不要求 Manager 回传明文密钥，只能使用 `credential_ref` 或 `lease://...`。 - -## 7. Callback 重试策略需要说清楚 - -Agent Manager 文档当前有两种说法： - -1. 当前发送失败只记录 warning，不阻塞任务执行。 -2. Runtime 推送失败时指数退避，最多重试 12 小时，超过进入死信队列。 - -请明确当前真实实现是哪一种： - -| 能力 | 当前是否已实现 | 需要说明 | -|---|---|---| -| 失败重试 | 是/否 | 重试次数、间隔、最大时长 | -| 死信队列 | 是/否 | 存储位置、人工重放方式 | -| 幂等重放 | 是/否 | 是否复用原 `event_id` | -| 失败告警 | 是/否 | 是否有日志、监控或告警 | - -如果当前只 warning，不重试，请在文档中写成“当前未实现重试/死信，后续增强”，不要把建议方案写成已完成。 - -## 8. 联调验收步骤 - -Agent Manager 改完后，按下面步骤验收。 - -| 步骤 | 操作 | 通过标准 | -|---:|---|---| -| 1 | `GET /api/agent/health` | 返回 healthy | -| 2 | `POST /api/agent/deployments` 创建普通 sub run | 返回 `deployment_id`、`status` | -| 3 | 重复同一个 `X-Idempotency-Key` 创建 | 不重复创建，返回同一个 ID | -| 4 | `GET /api/agent/deployments/{deployment_id}` | 返回真实状态和 agents | -| 5 | Runtime 主动 callback `phase.changed` | Manager callback 返回 success | -| 6 | Runtime 主动 callback `timeline.updated` | Manager timeline 可查到 | -| 7 | Runtime 主动 callback `artifact.created` | Manager artifacts 可查到 | -| 8 | Runtime 主动 callback `sk_tool.completed` | Manager SK/timeline 可查到 | -| 9 | Runtime 主动 callback usage | Manager 能看到 usage 摘要或 callback event | -| 10 | Runtime 主动 callback `approval.requested` | Manager pending approval 生成 | -| 11 | Manager approve/reject | Agent Manager 收到 decision | -| 12 | `POST /api/agent/deployments/{deployment_id}/stop` | Runtime 停止，状态变为 stopped | -| 13 | 检查日志和 artifact metadata | 不包含明文密钥 | - -## 9. 当前实测记录 - -2026-05-28 已测： - -| 接口 | 结果 | 说明 | -|---|---|---| -| `GET http://20.212.121.126/api/agent/health` | 200 | Agent Manager IP 健康检查正常 | -| `GET https://agent-manager.taijiagent.com/api/agent/health` | 暂不作为当前验收项 | 当前约定先走 IP，域名后续再切换 | -| `POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events` 无认证 | 业务返回 `CALLBACK_UNAUTHORIZED` | Manager callback 路由在线 | -| `POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events` 带旧 token 但空 body | 业务返回 `CALLBACK_INVALID` | 认证通过，进入事件校验 | -| `GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema` | 404 | Manager schema GET 生产未通，Manager 侧需复核 | -| `POST http://20.212.121.126/api/agent/deployments` | 200 | 普通 sub Runtime deployment 创建可用 | - -### 9.1 2026-05-28 追加联调记录 - -本次按当前约定使用 Agent Manager IP `http://20.212.121.126`。 - -客户端完整用户态链路说明： - -- 已尝试通过生产 Manager `/api/user/login` 获取用户 session，但手头用户名组合未登录成功。 -- 因此本次没有宣称“桌面客户端登录后走 Manager 用户态创建 deployment”完整通过。 -- 本次完成的是服务到服务联调：Manager/客户端等价 payload -> Agent Manager IP，以及 Agent Manager callback 协议 -> Heicode Manager callback 接收端。 - -Agent Manager `/api/agent/deployments` 服务到服务链路： - -| 步骤 | 结果 | 证据 | -|---|---|---| -| `GET /api/agent/health` | 通过 | 返回 `success=true`、`status=healthy` | -| `POST /api/agent/deployments` | 通过 | 返回 `deployment_id=dep_dbafd1ac37c3`，状态 `pending` | -| `GET /api/agent/deployments/{deployment_id}` | 通过 | 能查到 `user_id`、`binding_scope`、`sub_mode=agile`、`callback_configured=true` | -| `GET /api/agent/deployments/{deployment_id}/events` | 部分通过 | 只看到 `deployment.accepted`，未看到 `phase.changed/timeline.updated/artifact.created/sk_tool.*` | -| `GET /api/agent/deployments/{deployment_id}/logs` | 部分通过 | 返回系统日志 `Pod ... has no logs yet` | -| `GET /api/agent/deployments/{deployment_id}/metrics` | 通过但疑似占位 | 返回 CPU/内存/网络指标，但值看起来是固定模拟值，需要 Runtime 说明来源 | -| `POST /api/agent/deployments/{deployment_id}/stop` | 通过 | `dep_dbafd1ac37c3` 停止成功，返回 `status=stopped` | - -长等待测试： - -| 项 | 结果 | -|---|---| -| 测试 deployment | `dep_cd170573cf47` | -| 等待时间 | 约 2 分钟 | -| 最终状态 | 已清理停止 | -| 事件结果 | 只有 `deployment.accepted` 和 `deployment.stopped` | -| 未观察到 | `phase.changed`、`timeline.updated`、`artifact.created`、`agent.started/completed`、`sk_tool.called/completed` | -| 结论 | Agent Manager 文档声称的“Runtime 主动推送 status/phase/timeline/agent/tool/artifact 事件”在本次实测中没有跑出来，需要 Agent Manager 继续排查 | - -Heicode Manager callback 接收端： - -| 步骤 | 结果 | 证据 | -|---|---|---| -| 无认证 POST callback | 通过预期 | 返回 `CALLBACK_UNAUTHORIZED` | -| 带旧 token 但缺事件字段 | 通过预期 | 返回 `CALLBACK_INVALID`，说明认证通过并进入业务校验 | -| 带旧 token 发送合法 `timeline.updated` | 通过 | 返回 `success=true`、`inserted=true` | -| 重复发送同一 `event_id` | 通过 | 返回 `deduplicated=true`、`inserted=false` | - -本次合法 callback 测试事件： - -```text -event_id=evt_agent_manager_ip_smoke_1779954828884 -event_type=timeline.updated -runtime_deployment_id=dep_cd170573cf47 -source=agent-manager-ip-smoke -``` - -结论： - -1. Heicode Manager callback 接收端可用，旧 token 认证和幂等可用。 -2. Agent Manager IP 的 `/api/agent/deployments` 创建、查询、停止可用。 -3. Agent Manager 当前没有在实测中产生普通 sub 所需的 phase/timeline/artifact/SK 主动回调。 -4. 因没有可用生产 Manager 用户 session，本次没有完成“客户端登录态 -> Manager 用户态 deployment -> Runtime”的完整端到端测试。 - -### 9.2 2026-05-28 测试用户客户端模拟链路 - -测试用户： - -```text -email: zsbgnw@gmail.com -username: chenchen -user_id: 22 -group: default -``` - -说明：密码只用于本次登录测试，不写入本文档。 - -本次已完成“客户端模拟 -> Heicode Manager 生产用户态接口 -> Agent Manager IP Runtime”链路。 - -| 步骤 | 结果 | 证据 | -|---|---|---| -| 登录生产 Manager | 通过 | `/api/user/login` 返回 `success=true`，用户 `id=22` | -| 查询用户信息 | 通过 | `/api/user/self` 返回用户 `chenchen`、`group=default` | -| 查询 Runtime 健康 | 通过 | `/api/agent/runtime/health` 返回 `enabled=true`、`configured=true`、`status=healthy`、`create_path=/api/agent/deployments`、远端为 Agent Manager IP | -| 客户端模拟创建 deployment | 通过 | `POST /api/agent/user/deployments` 返回 Manager deployment `dep_1ba14ccfb558` | -| Manager -> Agent Manager create | 通过 | Manager detail 写回 `runtime_deployment_id=dep_3335e54e9bdf`，`runtime_state=pending` | -| Manager 用户态 events | 通过 | 出现 `deployment.accepted`、`runtime.sync.started`、`runtime.sync.accepted` | -| Manager 用户态 logs | 通过 | 出现 control-plane 日志和 runtime sync 日志，均为 redacted | -| Manager 用户态 metrics | 部分通过 | 返回 `platform_estimated=true`，说明是 Manager 估算/占位，不是 Runtime 真实资源指标 | -| Manager 用户态 artifacts | 未产出 | 返回空列表 | -| Manager 用户态 timeline | 部分通过 | 能返回 deployment/events，但 callbacks/artifacts 为空 | -| Manager stop | 通过 | `POST /api/agent/user/deployments/dep_1ba14ccfb558/stop` 返回 `status=stopped` | -| Runtime stop 结果 | 通过 | 直查 Agent Manager `dep_3335e54e9bdf`，状态为 `stopped` | - -本次真实 ID： - -```text -manager_deployment_id=dep_1ba14ccfb558 -runtime_deployment_id=dep_3335e54e9bdf -correlation_id=manager-client-sim-1779955103016 -runtime_agent_instance_id=agi_ed399bf8cc70 -``` - -Agent Manager 侧直查 `dep_3335e54e9bdf`： - -| 接口 | 结果 | -|---|---| -| `GET /api/agent/deployments/dep_3335e54e9bdf` | 200，状态 `stopped`，`user_id=22` | -| `GET /api/agent/deployments/dep_3335e54e9bdf/events` | 200，仅有 `deployment.accepted`、`deployment.stopped` | -| `GET /api/agent/deployments/dep_3335e54e9bdf/logs` | 200，仅有 `Pod ... has no logs yet` | -| `GET /api/agent/deployments/dep_3335e54e9bdf/metrics` | 200，返回 CPU/内存/网络固定值 | - -本次客户端模拟链路结论： - -1. 测试用户登录、Manager 用户态接口、Manager Runtime bridge、Agent Manager create、Agent Manager stop 均已真实跑通。 -2. Manager 能拿到 Runtime 健康状态，并能把用户态 deployment 同步到 Agent Manager IP。 -3. Manager stop 能传递到 Agent Manager，Runtime deployment 已停止。 -4. Agent Manager 仍未真实产生普通 sub 必需的阶段、timeline、artifact、SK 工具和 usage 回调。 -5. 当前 metrics/logs 更像 Runtime 占位数据：日志显示 `Pod ... has no logs yet`，metrics 为固定 CPU/内存/网络值。 -6. 本次 Manager 请求中的 agile context 没有在 Runtime 详情中表现为有效阶段推进，Runtime 事件里 `agile_context` 为空字段，需要双方继续核对字段解析和透传。 - -## 10. 完成定义 - -只有满足以下条件，才能认为普通 sub 敏捷 Runtime 联调完成： - -1. Manager 能创建 Runtime run，并保存 Runtime 返回的 `deployment_id`。 -2. Runtime 能主动回调 Manager，且 callback 通过认证、幂等、脱敏和 schema 校验。 -3. Manager 的 artifacts / timeline / sk-snapshots / events 能看到 Runtime 回传数据。 -4. Manager 发起 stop 后 Runtime 真实停止。 -5. Runtime 高危审批能暂停，Manager approve/reject 后 Runtime 收到 decision 并继续或停止。 -6. Runtime usage / cost 能按 user、deployment、task、agent role、model 归属。 -7. 整个流程不传递、不记录明文长期密钥。 diff --git a/docs/integration/Heicode-登录接口对接文档.md b/docs/integration/Heicode-登录接口对接文档.md deleted file mode 100644 index bc504446..00000000 --- a/docs/integration/Heicode-登录接口对接文档.md +++ /dev/null @@ -1,372 +0,0 @@ -# Heicode 客户端 — 登录接口对接文档 - -**版本**: v1.0 -**生效日期**: 2026-04-30 -**状态**: 已上线生产，已通过端到端测试 - ---- - -## 1. 概述 - -本文档描述 Heicode 客户端（桌面/CLI）与 Heicode Manager（即 mcp-server）之间的**登录认证接口**。共 4 个接口，覆盖完整登录生命周期： - - -| 接口 | 用途 | -| ------------------------ | ----------------------- | -| `POST /api/auth/login` | 账号密码登录，换取 token | -| `GET /api/auth/me` | 校验 token 有效性 + 获取当前用户资料 | -| `POST /api/auth/refresh` | access token 过期时换新的 | -| `POST /api/auth/logout` | 登出（token 加入黑名单） | - - -> 不在本期范围：注册、找回密码、改密码 — 这些走官网 web 端完成。 - ---- - -## 2. 接入信息 - -### 2.1 Base URL - -生产环境通过 Azure APIM 网关接入： - -``` -https://apimtaiji.azure-api.net/api/mcp -``` - -完整路径示例： - -``` -POST https://apimtaiji.azure-api.net/api/mcp/api/auth/login -``` - -### 2.2 通用请求头 - - -| Header | 必填 | 说明 | -| -------------------------------- | ----------- | -------------- | -| `Content-Type: application/json` | 是（POST/PUT） | 请求体 JSON | -| `Authorization: Bearer ` | 受保护接口必填 | 见 §3 | -| `X-Request-Id: ` | 建议 | 全链路追踪 ID，客户端生成 | - - -### 2.3 Token 模型 - -登录成功返回两个 token： - - -| Token | 用途 | 有效期 | -| ----------------- | ------------------------ | ----- | -| **Access Token** | 调业务接口（含 `/me`、`/logout`） | 24 小时 | -| **Refresh Token** | 仅用于 `/refresh` 换新 access | 7 天 | - - -JWT claims 包含：`sub`（user_id）、`email`、`role`、`channelId`、`type`（access/refresh）、`iat`、`exp`。 - ---- - -## 3. 接口详情 - -### 3.1 POST /api/auth/login — 登录 - -**请求** - -```http -POST /api/auth/login HTTP/1.1 -Content-Type: application/json - -{ - "email": "user@example.com", - "password": "YourPassword123", - "role": "user" -} -``` - -字段： - -- `email` (string, 必填) -- `password` (string, 必填) -- `role` (string, 必填)：Heicode 客户端**固定传 `"user"`** - -**成功响应 200** - -```json -{ - "success": true, - "data": { - "token": "eyJhbGciOiJIUzI1NiIs...", - "refreshToken": "eyJhbGciOiJIUzI1NiIs...", - "user": { - "id": "b00a7b8e-9e8b-463d-9593-a3b4d0006778", - "name": "张三", - "email": "user@example.com", - "role": "user", - "channelId": "6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6" - } - } -} -``` - -**错误响应** - - -| HTTP | 含义 | 客户端处理建议 | -| ---- | ------------------------- | -------------------------------- | -| 401 | 邮箱或密码错误 | 显示"账号或密码错误"，让用户重新输入 | -| 403 | 账户已被禁用 | 提示用户联系管理员 | -| 429 | 登录尝试过于频繁（**每 IP 5 次/分钟**） | 显示倒计时；响应头 `Retry-After: 60` 表示秒数 | -| 422 | 请求体校验失败（邮箱格式不合法等） | 检查 `detail` 字段 | -| 500 | 服务异常 | 重试或提示稍后再试 | - - -**重要：限流规则** - -- **每 IP 每分钟最多 5 次**登录尝试（不区分成功失败） -- 超出返回 **429 Too Many Requests**，含 `Retry-After` 头（秒） -- 计数滑动窗口，60 秒后自动恢复 - ---- - -### 3.2 GET /api/auth/me — 获取当前用户 - -客户端**启动时**应调用此接口校验本地缓存的 access token 是否仍有效，并刷新用户信息。 - -**请求** - -```http -GET /api/auth/me HTTP/1.1 -Authorization: Bearer -``` - -**成功响应 200** - -```json -{ - "success": true, - "data": { - "id": "b00a7b8e-9e8b-463d-9593-a3b4d0006778", - "email": "user@example.com", - "name": "张三", - "role": "user", - "channelId": "6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6", - "status": "active", - "subscriptionTier": "free", - "lastLoginAt": "2026-04-30T06:38:14.765457" - } -} -``` - -**错误响应** - - -| HTTP | 含义 | 客户端处理建议 | -| ---- | --------------------- | ------------------------------------------ | -| 401 | Token 无效/过期/已登出/用户不存在 | 调 `/refresh` 换新 token；若 refresh 也 401，跳登录页 | -| 403 | 账户已被禁用 | 强制登出，提示联系管理员 | - - ---- - -### 3.3 POST /api/auth/refresh — 刷新 token - -access token 接近或已过期时调用，使用 **refresh token** 换取新的 access + refresh token 对。 - -**请求** - -```http -POST /api/auth/refresh HTTP/1.1 -Authorization: Bearer -``` - -> ⚠️ **必须传 refresh token**，传 access token 会被拒绝。 - -**成功响应 200** - -```json -{ - "success": true, - "data": { - "token": "eyJhbGciOiJIUzI1NiIs...", - "refreshToken": "eyJhbGciOiJIUzI1NiIs..." - } -} -``` - -客户端收到新的 token 对后**应替换本地缓存**（包括 refresh token，旧的也作废）。 - -**错误响应** - - -| HTTP | 含义 | 客户端处理建议 | -| ---- | ---------------------------------------- | ------- | -| 401 | refresh token 无效 / 过期 / 错传了 access token | 跳登录页 | - - -实施细节： - -- 服务端会校验 token claims `type == "refresh"`，否则拒绝 -- 旧 refresh token 不会被立即吊销（容许并发换发期），但客户端应丢弃旧的 - ---- - -### 3.4 POST /api/auth/logout — 登出 - -将当前 access token 加入黑名单，使其立即失效。 - -**请求** - -```http -POST /api/auth/logout HTTP/1.1 -Authorization: Bearer -``` - -**成功响应 200** - -```json -{ - "success": true, - "data": null, - "message": "登出成功" -} -``` - -**错误响应** - -logout 容错性较强，token 黑名单写入失败也会返回 200（前端清理本地 token 即可）。 - -**客户端登出流程**： - -1. 调 `/api/auth/logout` -2. 清除本地存储的 access + refresh token -3. 清除当前用户资料缓存 -4. 跳转到登录页 - ---- - -## 4. 完整登录流程（示例） - -### 启动时 - -``` -┌─ 本地有 access token ? -│ -├─ 是 ─→ GET /me -│ ├─ 200 ─→ 进入主界面 -│ └─ 401 ─→ 本地有 refresh token ? -│ ├─ 是 ─→ POST /refresh -│ │ ├─ 200 ─→ 替换 token，进入主界面 -│ │ └─ 401 ─→ 跳登录页 -│ └─ 否 ─→ 跳登录页 -│ -└─ 否 ─→ 跳登录页 -``` - -### 登录页提交 - -``` -POST /login - ├─ 200 ─→ 存 token 对，进主界面 - ├─ 401 ─→ 显示"账号或密码错误" - ├─ 429 ─→ 显示"尝试过于频繁，请 N 秒后重试"（N 取响应头 Retry-After） - └─ 其他 ─→ 显示通用错误 -``` - -### 业务请求过程中 access token 过期 - -``` -任意业务接口返回 401 - └─→ POST /refresh (用 refresh token) - ├─ 200 ─→ 替换 token，重试原请求 - └─ 401 ─→ 清理 token，跳登录页 -``` - -### 登出按钮 - -``` -POST /logout - └─→ 不论结果都清理本地 token，跳登录页 -``` - ---- - -## 5. 错误响应格式 - -当前为 FastAPI 默认格式（下个版本 `/api/v1/*` 路径会改为标准 envelope，本期保留兼容）： - -```json -{ - "detail": "邮箱或密码错误" -} -``` - -422 校验错误格式（Pydantic）： - -```json -{ - "detail": [ - { - "type": "value_error", - "loc": ["body", "email"], - "msg": "value is not a valid email address: ...", - "input": "abc" - } - ] -} -``` - ---- - -## 6. 安全注意事项 - - -| 项 | 说明 | -| -------------- | -------------------------------------------------------------------------------------- | -| **token 存储** | 桌面应用建议存到 OS 安全凭据存储（Windows Credential Manager / macOS Keychain / Linux Secret Service） | -| **HTTPS 强制** | 生产 base URL 已是 HTTPS；客户端**禁止**回退 HTTP | -| **token 泄露应对** | 用户怀疑泄露时提示去官网 web 端改密码（改密会导致所有 session 黑名单） | -| **审计日志** | 所有 login 尝试（成功/失败）服务端均写审计 | -| **状态码不泄漏** | 错误信息已统一用"邮箱或密码错误"，不区分账号是否存在，防爆破 | - - ---- - -## 7. 测试账号（仅供联调） - - -| 角色 | 邮箱 | 密码 | -| ---- | ----------- | ------------ | -| 普通用户 | `55@55.com` | `By@123456.` | - - -> ⚠️ 测试账号仅用于联调阶段，正式上线前请务必关闭。 - ---- - -## 8. 已上线生产验证清单 - - -| 测试项 | 结果 | -| ------------------------------------------ | --- | -| login 200 + 返回 access/refresh token | ✅ | -| /me 用 access token → 200 + 完整 profile | ✅ | -| /refresh 用 refresh token → 200 + 新 token 对 | ✅ | -| /refresh 用 access token → 401 拒绝 | ✅ | -| logout → 200 | ✅ | -| logout 后旧 token 调 /me → 401（黑名单生效） | ✅ | -| 连续 7 次错密 → 第 6 次起 429（每 IP 5/min 限流） | ✅ | -| 服务器审计日志记录所有 login（含成功/失败） | ✅ | - - -镜像 digest: `sha256:339b64ae090dc81fa13cb29705958167e77fe0698e27ac227c05054ed5c42309` -镜像 tag: `taiji.azurecr.io/mcp-server:heicode-auth-fix2-20260430` -部署日期: 2026-04-30 - ---- - -## 9. 联系 - -如对接过程发现接口行为与本文档不一致，请联系 Heicode Manager 后端团队，附上： - -- 请求完整 URL / Headers / Body -- 响应 HTTP 状态 + Body -- `X-Request-Id` 头值（便于服务端按 ID 反查日志） - diff --git a/docs/integration/heicode-desktop-client-api.md b/docs/integration/heicode-desktop-client-api.md index fba2ee2f..e29d1c44 100644 --- a/docs/integration/heicode-desktop-client-api.md +++ b/docs/integration/heicode-desktop-client-api.md @@ -5,7 +5,7 @@ > 生产地址：`https://code.xinghanlab.com` > 状态图例：🟢 已实现并生产验证 · 🔴 待建（依赖 AM） -> **本文取代旧的 `heicode-desktop-unified-api.md`**（那份描述的是已下线的 sub 任务编排模型：tasks/workflow/display_status/git_ref/产物下载等，均已删除）。新客户端一律按本文对接。 +> **本文取代旧的桌面 sub 任务编排接口文档**（描述 tasks/workflow/display_status/git_ref/产物下载的那套已下线，相关 md 已删除）。新客户端一律按本文对接。 --- diff --git a/docs/integration/heicode-desktop-sub-agile-api.md b/docs/integration/heicode-desktop-sub-agile-api.md deleted file mode 100644 index a7ea6679..00000000 --- a/docs/integration/heicode-desktop-sub-agile-api.md +++ /dev/null @@ -1,1614 +0,0 @@ -# Heicode 桌面客户端 sub 敏捷流程 API 对接文档 - -更新时间：2026-06-01 -适用范围：Heicode Desktop / 本地服务对接 Heicode Manager，跑通普通 sub 模式敏捷开发流程。 -Manager 生产地址：`https://code.xinghanlab.com` - -## 0. 当前生产联调结论 - -截至 2026-05-31，普通 sub 敏捷链路已按生产地址完成端到端联调，并已用 Heicode Manager 生产入口复核 Runtime 新镜像修复后的真实生成链路： - -| 项目 | 状态 | 生产验证 | -|---|---|---| -| 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` 和完整文本内容 | - -本次真实生产烟测记录： - -| 字段 | 值 | -|---|---| -| `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 项目交付物 | - -补充生产验证： - -| 字段 | 值 | -|---|---| -| `runtime_swarm_id` | `swm_b60c8181bc79` | -| `objective` | 生成可运行的 Node.js Express REST API 小项目 | -| `artifact_id` | `art_swm_b60c8181bc79_backend_1` | -| `artifact_type` | `code_patch` | -| `tokens_used` | `2571` | -| artifact content | `HTTP 200`，`text/plain; charset=utf-8`，约 `8.2 KB`，包含 `package.json`、`src/index.js`、`README.md`、`test/smoke.test.js` 的 markdown 多文件代码内容 | - -重要修正： - -1. 桌面客户端不要再使用 `agent-model-builder`、`agent-model-reviewer`、`agent-model-product` 这类占位模型名。生产 NewAPI 没有这些模型，会返回 `No available channel for model ...`。 -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. 成功态不能只看 `status=completed`。客户端还应确认 `runtime_state=completed`、`artifacts.length > 0`、artifact 不是失败摘要、`tokens_used > 0`，并优先展示可下载的业务交付物。 -5. Runtime 日志已支持回传 `newapi_request_id` 和 `model_usage`。客户端应把这些字段展示在调试信息或错误详情中，便于定位模型调用问题。 -6. `artifact_type=code_patch` 不一定代表已经拿到 zip/git 工程包；当前 Runtime 可能返回 `.txt` markdown 多文件代码。客户端必须按 content 内容继续分类展示，不要把 artifact 原文整段刷到聊天区。 - -## 1. 对接目标 - -桌面客户端负责用户主体验：输入想法、回答追问、持续推进任务、查看子环节反馈、处理高危审批、接收交付结果。 - -Manager 负责辅助控制面：任务草稿桥接、资源/权限、Agent deployment、状态/timeline/artifact/SK 查询、审批记录和短期凭证 lease。 - -本文只描述普通 sub 敏捷流程，不包含蜂群 task graph、claim、heartbeat、handoff 等蜂群模式能力。 - -## 2. 认证与公共约定 - -### 2.1 API 分组 - -| API 前缀 | 用途 | 认证 | -|---|---|---| -| `/api/heicode-auth/api/user/tasks/*` | HeicodeTask 任务编排代理，创建任务、追问、查询任务 | V2 加密 body + `Authorization: Bearer ` | -| `/api/agent/user/*` | Manager 用户态 Agent 控制面，deployment、timeline、artifact、审批 | V2 加密 body；未加密 Web 控制台请求继续使用 Manager session + `New-Api-User` | -| `/api/swarms` | 蜂群模式创建入口 / Runtime adapter 入口 | V2 加密 body；未加密 Web 控制台请求继续使用 Manager session + `New-Api-User` | -| `/api/user/self` | 查询当前 Manager 用户 | Manager 登录 session cookie | - -### 2.2 桌面端请求 body 加密 - -桌面客户端调用 Manager 的 sub / 蜂群入口时，应使用与模型调用一致的 V2 加密请求协议。普通 sub 用户态接口在生产 Manager `1.4.7+` 已支持；`POST /api/swarms` 蜂群入口在本次 Manager 代码中补齐同一套 V2 body 加密鉴权，需随下一次生产部署生效。 - -适用接口： - -| API 前缀 | V2 加密 body | 说明 | -|---|---|---| -| `/api/agent/user/*` | 支持 | Manager 解密并校验设备签名后，按当前设备对应用户执行 | -| `/api/swarms` | 支持 | Manager 解密并校验设备签名后，按当前设备对应用户创建蜂群/Runtime adapter deployment | -| `/api/heicode-auth/*` | 支持 | Manager 解密并校验设备签名后，把明文 body 代理给上游 HeicodeTask 服务；仍需携带 `heicode_access_token` | -| 浏览器后台普通页面请求 | 兼容未加密 JSON | 不影响现有 Manager Web 控制台 | - -V2 请求头与模型调用一致： - -```http -Content-Encoding: heicode-aead-v1 -X-Heicode-Device-Id: -X-Heicode-Timestamp: -X-Heicode-Nonce: -X-Heicode-Fingerprint: -X-Heicode-Eph-Pubkey: -X-Heicode-Signature: -X-Heicode-Client-Version: -Content-Type: application/json -Accept: application/json -``` - -加密和签名协议沿用模型调用： - -```text -body = nonce || ChaCha20-Poly1305(plaintext_json, aad) -aad = device_id + "|" + timestamp + "|" + nonce + "|" + method + "|" + path_with_query - -canonical = method + "\n" - + path_with_query + "\n" - + timestamp_ms + "\n" - + nonce_hex + "\n" - + device_fingerprint + "\n" - + ephemeral_pubkey_b64 + "\n" - + sha256_hex(plaintext_body) - -signature = base64(ed25519_sign(device_private_key, sha256(canonical))) -``` - -`/api/heicode-auth/*` 额外要求： - -```http -Authorization: Bearer -``` - -原因：该 token 是上游 HeicodeTask 服务认证用；V2 设备签名只证明请求来自已配对的 Manager 桌面设备。 - -客户端实现要求： - -1. sub 流程调用不要新增一套加密协议，直接复用模型调用的 `encryptedFetch` / V2 设备签名实现。 -2. `aad` 和 `canonical` 中的 `path_with_query` 必须是 Manager 实际收到的 path，例如 `/api/agent/user/tasks/task-1/deployment-draft`，不能把 origin 写进去。 -3. 加密前的 plaintext 必须是最终 JSON body；签名里的 `sha256_hex(plaintext_body)` 必须和该 JSON 字节完全一致。 -4. 每次请求必须使用新的 `X-Heicode-Nonce` 和新的 X25519 ephemeral key。 -5. V2 请求失败时优先读取 `X-Heicode-Auth-Error` 和 `X-Heicode-Server-Time`，用于提示设备未配对、时间漂移、nonce 重放、签名错误或解密失败。 - -### 2.3 Manager 用户态 Header - -未加密 Web 控制台请求调用 `/api/agent/user/*` 或 `/api/swarms` 时必须带： - -```http -Cookie: session= -New-Api-User: -Content-Type: application/json -Accept: application/json -``` - -`New-Api-User` 必须等于当前登录用户 ID，否则会返回未授权。 - -使用 V2 加密 body 时，`/api/agent/user/*` 和 `/api/swarms` 不依赖浏览器 session cookie，也不需要 `New-Api-User`；Manager 会从设备绑定 token 中解析用户身份。为兼容当前 Web 控制台，未加密请求仍按 session cookie + `New-Api-User` 处理。 - -### 2.4 蜂群入口加密边界 - -蜂群模式的业务流程与普通 sub 敏捷流程分开对接，但客户端到 Manager 的请求加密规则一致。 - -| 接口 | 所属模式 | 加密要求 | -|---|---|---| -| `POST /api/agent/user/tasks/{task_id}/deployment-draft` | 普通 sub 敏捷 | V2 body 加密 | -| `POST /api/agent/user/deployments` | 普通 sub 敏捷 | V2 body 加密 | -| `POST /api/swarms` | 蜂群模式 | V2 body 加密 | - -注意：本文后续章节仍只描述普通 sub 敏捷主流程；蜂群 task graph、claim、heartbeat、handoff、approval decision 等字段以单独蜂群对接文档为准。 - -### 2.5 统一响应 Envelope - -成功： - -```json -{ - "success": true, - "message": "", - "data": {} -} -``` - -失败： - -```json -{ - "success": false, - "message": "human readable message", - "error": { - "code": "ERROR_CODE", - "message": "human readable message" - } -} -``` - -## 3. 推荐完整流程 - -```text -1. 桌面端确认 Manager 登录态，获取 /api/user/self -2. 创建 HeicodeTask：POST /api/heicode-auth/api/user/tasks/intent -3. 如果 status=configuring，回答追问：POST /api/heicode-auth/api/user/tasks/{task_id}/answer -4. 当任务卡生成后，创建 deployment draft：POST /api/agent/user/tasks/{task_id}/deployment-draft -5. 创建 Manager deployment：POST /api/agent/user/deployments -6. 轮询 deployment detail / events / timeline -7. 查询 runtime-diagnostics，区分 callback 已到、Runtime 状态、失败 Agent 和兜底摘要 artifact -8. 查询 artifacts 列表；如果需要完整文件，调用 artifact content 代理接口下载 -9. 展示 sk-snapshots / logs / metrics -10. 如出现 approval，桌面端展示审批并调用 approve/reject -11. 完成后继续迭代或停止 deployment -``` - -### 3.1 Runtime 诊断接口 - -客户端展示普通 sub 结果时，不能只看 deployment `status=completed`。Manager 已提供只读诊断接口，用来识别 Runtime 是否真的完成、是否有 failed agent、是否只返回兜底摘要 artifact。 - -```http -GET /api/agent/user/deployments/{deployment_id}/runtime-diagnostics -``` - -返回核心字段： - -| 字段 | 说明 | -|---|---| -| `runtime_mode` | `agent` 表示普通 sub Runtime；`swarm` 表示蜂群 Runtime | -| `runtime_swarm_id` / `runtime_deployment_id` | Manager 保存的 Runtime 映射 | -| `data_source` | 当前诊断来源，正常为 `runtime_status` | -| `status` / `phase` | Runtime 直接返回的状态和阶段 | -| `agents` | Runtime 返回的 Agent 状态列表 | -| `artifacts` | Runtime status 里的产物摘要 | -| `metrics` | Runtime status 里的 usage/耗时等指标 | -| `warnings` | Manager 根据 Runtime status 识别出的异常 | - -常见 `warnings`： - -| warning | 客户端展示含义 | -|---|---| -| `runtime_agent_failed` | 存在失败 Agent，不能把任务说成完整交付 | -| `runtime_completed_with_failed_agents` | Runtime 总状态 completed，但内部 Agent 有失败，需要提示“执行异常完成” | -| `runtime_summary_artifact_only` | 只有 `Runtime execution summary` 兜底摘要，不是最终业务交付物 | -| `runtime_zero_model_usage` | Runtime 回传模型 token 为 0，说明 Agent 可能没有真实调用模型 | -| `runtime_status_query_failed` | Manager 无法查询 Runtime status，只能展示已落库 callback | - -客户端建议： - -1. deployment detail / timeline / artifacts 仍按原接口展示。 -2. 若 `warnings` 包含 `runtime_summary_artifact_only`，需要提示“当前没有最终交付产物，请查看运行日志/等待 Runtime 修复”。 -3. 若 `runtime_mode=agent`，按普通 sub 敏捷展示；若 `runtime_mode=swarm`，按蜂群模式展示任务图/Agent 编队，不能混用两套文案。 -4. 该接口只读，失败时不应中断已有 timeline/artifact 展示。 - -### 3.2 Artifact 完整内容下载 - -普通 sub 的 `artifact.created` callback 只保存摘要、URI、大小、hash 和 metadata。客户端或 Manager 页面需要完整产物正文时，先查列表，再走 Manager 用户态 content 代理接口，不要直接暴露 Blob 凭据、SAS URL 或 Runtime 内网地址。 - -列表： - -```http -GET /api/agent/user/deployments/{deployment_id}/artifacts -``` - -下载： - -```http -GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content -``` - -Manager 行为： - -1. 校验当前用户拥有该 `deployment_id`。 -2. 校验 `artifact_id` 属于该 deployment。 -3. 使用 deployment 里保存的 `runtime_swarm_id` / `runtime_deployment_id` 请求 Runtime： - `GET /api/swarms/{swarm_id}/artifacts/{artifact_id}/content`。 -4. 透传 Runtime 返回的文件内容、`Content-Type`、`Content-Disposition` 等安全响应头。 -5. 如果 Runtime 未配置、artifact 不存在或 Runtime 返回错误，返回业务错误，不伪造内容。 - -页面说明： - -- Manager Web 任务总览中的 artifact 卡片会显示“下载产物”。 -- 如果 artifact 是 `Runtime execution summary` 兜底摘要，页面会明确提示它不是最终业务交付物。 - -### 3.3 Artifact 展示和有效性判断 - -桌面客户端不要把 artifact content 原文直接追加到聊天流里。聊天区只展示简短结论，完整产物放在右侧“交付产物”区域或独立详情页中。 - -推荐聊天区文案： - -```text -Sub Agile 执行完成，已生成 2 个交付产物： - -- 前端交付物 -- 后端交付物 - -请在右侧“交付产物”中查看、下载或应用到工作区。 -``` - -artifact 展示规则： - -| 情况 | 客户端展示 | 是否算代码交付 | -|---|---|---| -| `artifact_type=code_bundle`，content 是 zip/tar 或 metadata 有 git branch / commit | 显示“工程包”，提供下载 / 解压 / 应用到工作区 | 是 | -| `artifact_type=code_patch`，content 是 diff/patch | 显示“代码补丁”，提供查看 diff / 应用补丁 | 是 | -| `artifact_type=code_patch`，content 是 markdown 多文件代码块，包含 `package.json`、`src/...`、启动命令 | 显示“代码文档”，提供拆分文件 / 复制 / 保存到工作区 | 部分算，不能当作完整工程包 | -| `artifact_type=document` | 显示“方案文档” | 否 | -| content 以“以下是作为 Frontend 角色”“交付物总结”“交付物摘要”等开头，且只有方案描述 | 显示“方案总结，不是代码交付物” | 否 | -| title 为 `Runtime execution failed` 或 `Runtime execution summary` | 显示失败或兜底摘要 | 否 | - -客户端分类建议： - -```ts -function classifyArtifact(item: Artifact, content: string, contentType?: string) { - const lowerType = (item.artifact_type || '').toLowerCase() - const isZip = contentType?.includes('application/zip') - const hasGitRef = /https?:\/\/\S+\.git|git@|branch|commit/i.test(content) - const hasPatch = /^diff --git /m.test(content) || /^--- a\//m.test(content) - const hasCodeProject = - content.includes('package.json') && - /src\/[\w./-]+\.(js|ts|tsx|jsx|go|py)/.test(content) - const summaryOnly = - /以下是作为.*角色|交付物总结|交付物摘要|实现规划|目录建议/.test(content) && - !hasPatch && - !hasCodeProject - - if (isZip || lowerType === 'code_bundle' || hasGitRef) return 'code_bundle' - if (hasPatch) return 'code_patch' - if (hasCodeProject) return 'code_document' - if (summaryOnly) return 'summary_only' - if (lowerType === 'document') return 'document' - return 'unknown' -} -``` - -展示要求： - -1. `summary` 只作为卡片摘要，不要整段写进聊天。 -2. `uri` / `metadata.download_path` 只作为下载依据，不直接暴露给用户；客户端通过 Manager content 代理获取正文。 -3. 对用户要求“写代码 / 做网站 / 做前后端分离项目”的任务，只有 `code_bundle`、`code_patch`、`code_document` 可视为代码产出；`summary_only` 需要提示“Runtime 只返回了方案总结，需要继续生成代码”。 -4. 如果 content 是 markdown 多文件代码，客户端可提供“保存到工作区”能力：按标题 `## package.json`、`## src/index.js` 等拆分文件；拆分前必须让用户确认目标目录，避免覆盖本地文件。 -5. 如果 content 是 zip/git branch/patch，优先提供下载 / 应用按钮，而不是直接展示全部正文。 - -### 3.4 2026-05-28 生产验证结果 - -本节记录已经按“桌面客户端应调用的顺序”在生产环境跑过的结果，客户端可按同一顺序和参数形状对接。 - -生产环境： - -| 项 | 值 | -|---|---| -| Manager | `https://code.xinghanlab.com` | -| Manager 版本 | `1.4.19` | -| Agent Manager Runtime | `http://20.212.121.126` | -| Runtime health | `healthy` | -| Manager callback | `https://code.xinghanlab.com/api/agent/callbacks/swarm-events` | - -已验证成功的链路： - -```text -Manager 登录 --> /api/user/self --> /api/agent/runtime/health --> /api/agent/user/tasks/{task_id}/deployment-draft --> /api/agent/user/deployments --> Manager 调 Agent Manager Runtime create --> Runtime 自动 callback 到 Manager --> /api/agent/user/deployments/{deployment_id} --> /api/agent/user/deployments/{deployment_id}/metrics --> /api/agent/user/deployments/{deployment_id}/events --> /api/agent/user/deployments/{deployment_id}/logs --> /api/agent/user/deployments/{deployment_id}/artifacts --> /api/agent/user/deployments/{deployment_id}/sk-snapshots --> /api/agent/user/deployments/{deployment_id}/timeline --> /api/agent/user/deployments/{deployment_id}/stop -``` - -最新生产烟测 ID： - -| 对象 | ID / 结果 | -|---|---| -| Manager deployment | `dep_1d6d66896cc6` | -| Runtime swarm | `swm_03995f7c7a27` | -| detail status | `completed` | -| detail phase | `deploy` | -| runtime_state | `completed` | -| agent state | `completed` | -| 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、`newapi_request_id` 和 Runtime 日志回传的生产复核。高危审批闭环仍需按真实高危任务单独验收。 - -本次未由 Codex 直接跑通的步骤： - -| 步骤 | 结果 | 原因 | 客户端要求 | -|---|---|---|---| -| `POST /api/heicode-auth/api/user/tasks/intent` | 401 | Codex 没有桌面客户端持有的 `heicode_access_token` | 客户端必须带 `Authorization: Bearer ` | - -说明： - -- 如果客户端已经有 HeicodeTask snapshot，可以直接从 `deployment-draft` 开始跑，生产已验证可通。 -- 如果客户端需要从自然语言创建任务，必须先完成 Heicode 登录并拿到 `heicode_access_token`。 -- 当前 create / callback / detail / metrics / events / timeline / artifacts / artifact content 已真实有效；SK snapshots 需要 Runtime 在真实任务中回写 `sk_tool.*` 或 snapshot 字段后才会有数据。 - -### 3.5 桌面客户端联调结论 - -普通 sub 模式可以开始桌面客户端联调。建议先按 Windows 最新客户端跑通，因为生产已有 Windows 设备绑定记录；macOS 端必须先确认客户端版本和 Keychain 凭据。 - -| 项 | 当前结论 | 客户端动作 | -|---|---|---| -| Windows 设备绑定 | 生产已有 `windows` 设备绑定记录 | 可直接按本文流程联调 | -| macOS 设备绑定 | 生产库当前没有 `darwin/macOS` 设备绑定记录 | 升级到最新 macOS 包，清理 Keychain 中旧 Heicode 凭据后重新登录 | -| 用户模型列表 | Manager 端真实 token 请求 `/v1/models` 正常 | 如果桌面端 401，优先排查本地 token / device pair，不要先改模型配置 | -| 普通 sub POST 请求 | Manager 支持 V2 body 加密 | 复用模型调用的 `encryptedFetch` | -| 普通 sub GET 查询 | 当前仍建议使用 session + `New-Api-User` 兼容路径 | 后续如需完全无 cookie，再补无 body 签名 GET 协议 | - -## 4. 当前用户信息 - -### `GET /api/user/self` - -获取当前 Manager 登录用户，用于拿 `id` 并设置 `New-Api-User`。 - -响应关键字段： - -```json -{ - "success": true, - "data": { - "id": 22, - "username": "chenchen", - "email": "", - "group": "default", - "role": 1, - "status": 1 - } -} -``` - -客户端处理： - -- 保存 `data.id`。 -- 后续 `/api/agent/user/*` 请求带 `New-Api-User: `。 - -## 5. HeicodeTask 任务编排 - -这些接口通过 Manager 同源代理访问 mcp-server： - -```text -Base: /api/heicode-auth -``` - -### 5.1 创建任务 - -#### `POST /api/heicode-auth/api/user/tasks/intent` - -描述用户想做什么，创建 HeicodeTask。 - -请求头必须包含桌面客户端登录后持有的 Heicode access token： - -```http -Authorization: Bearer -Content-Type: application/json -Accept: application/json -``` - -请求： - -```json -{ - "intent": "做一个客户工单管理系统，支持登录、工单列表、状态流转和后台统计", - "name": "客户工单管理系统" -} -``` - -字段： - -| 字段 | 类型 | 必需 | 说明 | -|---|---|---:|---| -| `intent` | string | 是 | 用户自然语言目标 | -| `name` | string | 否 | 任务名称，不传则由服务端生成 | - -响应： - -```json -{ - "success": true, - "data": { - "id": "task_abc123", - "user_id": "22", - "name": "客户工单管理系统", - "status": "configuring", - "status_caption": "需要补充几个问题", - "intent": "做一个客户工单管理系统...", - "thread": [ - { - "kind": "user", - "text": "做一个客户工单管理系统...", - "at": 1779850000000 - }, - { - "kind": "heicode", - "text": "请选择第一版范围", - "at": 1779850001000, - "followups": [ - { - "id": "scope", - "question": "第一版优先做什么？", - "options": [ - { "id": "mvp", "label": "MVP 基础功能" } - ] - } - ] - } - ], - "card": null, - "created_at": 1779850000000, - "updated_at": 1779850001000 - } -} -``` - -### 5.2 查询任务列表 - -#### `GET /api/heicode-auth/api/user/tasks?status=running&limit=20&offset=0` - -查询当前用户任务。 - -查询参数： - -| 参数 | 类型 | 必需 | 说明 | -|---|---|---:|---| -| `status` | string | 否 | `draft/configuring/running/awaiting_approval/completed/failed/paused` | -| `limit` | number | 否 | 默认由服务端决定 | -| `offset` | number | 否 | 分页偏移 | - -响应： - -```json -{ - "success": true, - "data": { - "items": [], - "total": 0, - "offset": 0, - "limit": 20 - } -} -``` - -### 5.3 查询任务详情 - -#### `GET /api/heicode-auth/api/user/tasks/{task_id}` - -响应同 HeicodeTask。 - -### 5.4 回答追问 - -#### `POST /api/heicode-auth/api/user/tasks/{task_id}/answer` - -同样必须携带： - -```http -Authorization: Bearer -``` - -请求： - -```json -{ - "question_id": "scope", - "option_id": "mvp" -} -``` - -响应： - -```json -{ - "success": true, - "data": { - "id": "task_abc123", - "status": "running", - "card": { - "goal": "客户工单管理系统第一版", - "scope": ["登录", "工单列表", "状态流转"], - "generated_artifacts": ["产品说明", "接口草案", "开发任务"], - "manager_actions": [ - { - "label": "绑定 Git", - "deeplink": "/sk-sources" - } - ] - } - } -} -``` - -客户端处理： - -- `status=configuring`：继续展示 `thread[].followups`。 -- `status=running` 且 `card` 存在：允许用户创建 Manager deployment。 -- `status=awaiting_approval`：轮询审批接口。 -- `status=completed/failed/paused`：停止高频轮询。 - -## 6. 从任务生成 Agent Deployment Draft - -### `POST /api/agent/user/tasks/{task_id}/deployment-draft` - -把 HeicodeTask 快照转换成 Manager 可创建的 Agent orchestration plan。 - -生产已验证：客户端只要能提供 task snapshot，就可以不依赖 Manager 再去拉 task，直接调用本接口生成 draft。 - -请求： - -```json -{ - "task": { - "id": "task_abc123", - "name": "客户工单管理系统", - "intent": "做一个客户工单管理系统...", - "status": "running", - "card": { - "goal": "客户工单管理系统第一版", - "scope": ["登录", "工单列表", "状态流转"], - "generated_artifacts": ["产品说明", "接口草案", "开发任务"] - } - }, - "sub_mode": "agile", - "binding_scope": "task-task_abc123", - "role_templates": ["backend", "frontend", "reviewer"], - "default_model_id": "claude-sonnet-4-6", - "budget": { - "max_tokens": 120000, - "max_cost_usd": 8, - "max_duration_sec": 3600 - }, - "resource_grants": [] -} -``` - -生产烟测可用的最小请求形状： - -```json -{ - "task": { - "id": "task-client-sim-1779875397", - "name": "客户端模拟普通 sub 敏捷流程", - "intent": "做一个轻量待办系统，包含任务列表、状态流转、基础测试和上线说明", - "status": "running", - "card": { - "goal": "交付轻量待办系统 MVP", - "scope": "普通 sub 敏捷流程接口联调", - "generated_artifacts": [] - } - }, - "sub_mode": "agile", - "risk_level": "low", - "budget": { - "max_tokens": 20000, - "max_cost_usd": 1, - "max_duration_sec": 600 - }, - "binding_scope": "task-client-sim", - "role_templates": ["backend"], - "default_model_id": "claude-sonnet-4-6", - "resource_grants": [ - { - "grant_id": "grant-client-sim-git", - "resource_id": "git-client-sim", - "resource_type": "git", - "binding_scope": "task-client-sim", - "target_role": "backend", - "target_agent_ref": "agent-backend-1", - "permission_scope": ["repo:read"], - "metadata": { - "repo_url": "https://example.invalid/heicode/client-sim.git" - }, - "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/client-sim-git", - "status": "active" - } - ] -} -``` - -字段： - -| 字段 | 类型 | 必需 | 说明 | -|---|---|---:|---| -| `task.id` | string | 是 | 必须和 URL `{task_id}` 一致 | -| `task.name` | string | 否 | 任务名称 | -| `task.intent` | string | 否 | 用户原始目标 | -| `task.card.goal` | string | 否 | 优先作为 objective | -| `sub_mode` | string | 是 | `agile` 或 `waterfall`，桌面客户端默认传 `agile` | -| `binding_scope` | string | 否 | 建议 `task-` | -| `role_templates` | string[] | 否 | 默认 `["backend"]` | -| `default_model_id` | string | 否 | 子 Agent 默认运行模型；生产默认建议 `claude-sonnet-4-6` | -| `budget` | object | 否 | 不传使用默认预算 | -| `resource_grants` | array | 否 | 不传时 Manager 生成只读 task context grant | - -响应： - -```json -{ - "success": true, - "data": { - "task_id": "task_abc123", - "orchestration_plan": { - "intent_id": "task_abc123", - "template_hint": "heicode-task", - "objective": "客户工单管理系统第一版", - "sub_mode": "agile", - "risk_level": "low", - "budget": { - "max_tokens": 120000, - "max_cost_usd": 8, - "max_duration_sec": 3600 - }, - "user_context": { - "user_id": "22", - "role": "user", - "channel_id": "default" - }, - "billing_context": { - "provider": "newapi", - "newapi_group": "default" - }, - "agent_runtime": { - "platform": "agent", - "agents": [ - { - "role": "backend", - "model_ref": "claude-sonnet-4-6", - "instance_count": 1 - } - ] - }, - "agents": [ - { - "role_template": "backend", - "goal": "Execute the Heicode task as backend within the approved resource scope.", - "default_model_id": "claude-sonnet-4-6", - "resource_grants": [] - } - ], - "constraints": { - "allowed_model_ids": [] - }, - "metadata": { - "correlation_id": "task-task_abc123-xxxxxxxx" - } - } - } -} -``` - -## 7. 创建 Manager Deployment - -### `POST /api/agent/user/deployments` - -使用上一步 `orchestration_plan` 创建 Manager deployment。 - -必填注意： - -- `metadata.correlation_id` 必须在 `orchestration_plan.metadata` 内。 -- 如果客户端绕过 draft 接口直接创建 deployment，也必须自行生成该字段，例如 `task--`。 -- 不要把 `metadata` 放在请求顶层；顶层 metadata 不会满足创建校验。 -- `billing_context.default_model_id`、`agents[].default_model_id`、`constraints.allowed_model_ids` 必须使用生产 NewAPI 已存在模型。 - -请求： - -```json -{ - "orchestration_plan": { - "intent_id": "task_abc123", - "template_hint": "heicode-task", - "objective": "客户工单管理系统第一版", - "sub_mode": "agile", - "risk_level": "low", - "budget": { - "max_tokens": 120000, - "max_cost_usd": 8, - "max_duration_sec": 3600 - }, - "user_context": { - "user_id": "22", - "role": "user", - "channel_id": "default" - }, - "billing_context": { - "provider": "newapi", - "newapi_group": "default" - }, - "agent_runtime": { - "platform": "agent", - "agents": [ - { - "role": "backend", - "model_ref": "claude-sonnet-4-6", - "instance_count": 1 - } - ] - }, - "agents": [ - { - "role_template": "backend", - "goal": "Execute the Heicode task as backend within the approved resource scope.", - "default_model_id": "claude-sonnet-4-6", - "resource_grants": [] - } - ], - "constraints": { - "allowed_model_ids": [] - }, - "metadata": { - "correlation_id": "task-task_abc123-xxxxxxxx" - } - } -} -``` - -响应： - -```json -{ - "success": true, - "data": { - "deployment_id": "dep_464a08b7b751", - "sub_mode": "agile", - "status": "accepted", - "phase": "pending", - "runtime_state": "queued", - "runtime_deployment_id": "", - "runtime_swarm_id": "", - "failure_reason": "", - "agent_instances": [ - { - "instance_id": "agi_1fddac9cded5", - "role": "backend", - "phase": "pending", - "runtime_state": "queued", - "failure_reason": "" - } - ], - "permission_manifest": { - "user_id": "22", - "binding_scope": "task-task_abc123", - "agent_role": "backend", - "target_agent_ref": "agent-backend-1", - "resource_grants": [] - } - } -} -``` - -客户端处理： - -- 保存 `deployment_id`。 -- `runtime_state=queued` 表示 Manager 已建立本地控制面记录。 -- 如果生产 Runtime 未配置，deployment 仍可创建，但不会进入真实执行。 - -直接创建的最小可用生产示例： - -```json -{ - "orchestration_plan": { - "intent_id": "task-prod-smoke", - "template_hint": "heicode-task", - "objective": "生成一个极简 hello world 网站。必须返回真实代码文件内容，不接受只有方案总结。", - "sub_mode": "agile", - "risk_level": "low", - "budget": { - "max_tokens": 20000, - "max_cost_usd": 0.5, - "max_duration_sec": 900 - }, - "user_context": { - "user_id": "22", - "channel_id": "heicode", - "binding_scope": "task-prod-smoke" - }, - "billing_context": { - "provider": "newapi", - "default_model_id": "gpt-5.4", - "allowed_model_ids": ["gpt-5.4"], - "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key" - }, - "agile_context": { - "stage": "development", - "checkpoint": "artifact_required", - "acceptance_criteria": [ - "artifact content must include real source files", - "package.json or equivalent entry file must be present for code tasks", - "README must include run or smoke test commands", - "do not return only a delivery summary document" - ], - "next_action": "submit_artifact", - "requires_user_approval": false - }, - "agents": [ - { - "role_template": "fullstack", - "goal": "生成 hello world 网站真实代码 artifact，必须包含文件路径、源码内容、启动命令和冒烟说明，不要只写交付总结。", - "default_model_id": "gpt-5.4", - "resource_grants": [] - } - ], - "constraints": { - "allowed_model_ids": ["gpt-5.4"] - }, - "metadata": { - "correlation_id": "prod-smoke-" - } - } -} -``` - -## 8. 查询 Deployment - -### 8.1 列表 - -#### `GET /api/agent/user/deployments` - -响应： - -```json -{ - "success": true, - "data": { - "items": [ - { - "deployment_id": "dep_464a08b7b751", - "sub_mode": "agile", - "status": "accepted", - "phase": "pending", - "runtime_state": "queued", - "failure_reason": "", - "created_at": "2026-05-27T11:44:30+08:00", - "updated_at": "2026-05-27T11:44:30+08:00", - "permission_manifest": {}, - "orchestration_plan": {} - } - ] - } -} -``` - -### 8.2 详情 - -#### `GET /api/agent/user/deployments/{deployment_id}` - -响应字段同列表单项，包含完整 `orchestration_plan`。 - -### 8.3 停止 - -#### `POST /api/agent/user/deployments/{deployment_id}/stop` - -请求： - -```json -{ - "reason": "用户停止本轮 sub 敏捷任务" -} -``` - -响应： - -```json -{ - "success": true, - "data": { - "deployment_id": "dep_464a08b7b751", - "status": "stopped", - "phase": "stopped" - } -} -``` - -## 9. 执行反馈查询 - -### 9.1 Events - -#### `GET /api/agent/user/deployments/{deployment_id}/events` - -用于展示 deployment 事件流。 - -响应： - -```json -{ - "success": true, - "data": { - "items": [ - { - "event_id": "evt_xxx", - "event": "deployment.accepted", - "deployment_id": "dep_464a08b7b751", - "occurred_at": "2026-05-27T11:44:30+08:00", - "result": "ok" - } - ] - } -} -``` - -### 9.2 Logs - -#### `GET /api/agent/user/deployments/{deployment_id}/logs` - -用于展示最近日志。当前 Manager 未接真实 Runtime 时主要是审计日志。 - -响应： - -```json -{ - "success": true, - "data": { - "items": [ - { - "timestamp": "2026-05-27T11:44:30+08:00", - "level": "info", - "message": "deployment accepted", - "source": "manager-audit" - } - ] - } -} -``` - -### 9.3 Metrics - -#### `GET /api/agent/user/deployments/{deployment_id}/metrics` - -用于展示成本、耗时、token、资源指标。真实 Runtime 未接入时可能为空或为本地占位。 - -响应： - -```json -{ - "success": true, - "data": { - "deployment_id": "dep_464a08b7b751", - "runtime_state": "queued", - "metrics": {} - } -} -``` - -### 9.4 Artifacts - -#### `GET /api/agent/user/deployments/{deployment_id}/artifacts` - -查询中间交付物和最终交付物摘要。注意：列表接口只返回摘要和引用，不能证明代码内容有效；客户端需要按需调用 content 接口并按“Artifact 展示和有效性判断”继续分类。 - -响应： - -```json -{ - "success": true, - "data": { - "deployment_id": "dep_464a08b7b751", - "artifacts": [ - { - "artifact_id": "art_swm_b60c8181bc79_backend_1", - "artifact_type": "code_patch", - "title": "backend task delivery", - "summary": "下面给出一个可直接落地的 Node.js Express REST API 小项目交付物，包含真实代码文件内容...", - "uri": "azblob://heicode-artifacts/runtime-artifacts/swm_b60c8181bc79/art_swm_b60c8181bc79_backend_1.txt", - "metadata": { - "download_path": "/api/swarms/swm_b60c8181bc79/artifacts/art_swm_b60c8181bc79_backend_1/content", - "content_hash": "sha256:224cc3559cdfa6e607808a286cfa05a795c4331f61e776e58078471eb8ae45e1" - }, - "created_at": 1779850000000 - } - ], - "items": [], - "total": 1 - } -} -``` - -#### `GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content` - -读取完整产物正文。客户端必须通过该接口判断产物是否真的是代码，而不是只看 `artifact_type`。 - -真实代码文档示例片段： - -````text -## 1) package.json - -```json -{ - "name": "express-rest-api-demo", - "scripts": { - "start": "node src/index.js", - "test": "node --test" - }, - "dependencies": { - "express": "^4.19.2" - } -} -``` - -## 2) src/index.js - -```js -const express = require('express'); -const app = express(); -app.get('/health', (req, res) => res.json({ success: true, message: 'OK' })); -``` -```` - -summary-only 示例片段： - -```text -以下是作为 **Frontend 角色**，针对“Oracle 云代理商网站”可提交给 Heicode Manager artifacts 的具体交付物总结。 - -# 交付物总结：Oracle 云代理商网站（前端） -``` - -第二种只能显示为“方案总结 / 文档”，不能显示为代码生成完成。 - -### 9.5 SK Snapshots - -#### `GET /api/agent/user/deployments/{deployment_id}/sk-snapshots` - -查询本轮任务使用的 SK 快照。 - -响应： - -```json -{ - "success": true, - "data": { - "deployment_id": "dep_464a08b7b751", - "sk_snapshots": [ - { - "snapshot_id": "sks_task_abc123_backend_001", - "deployment_id": "dep_464a08b7b751", - "agent_role": "backend", - "source_type": "git", - "source_ref": "git:https://example.com/tools.git#main:backend", - "content_hash": "sha256:abc123", - "tool_name": "repo_write", - "created_at": "2026-05-27T11:45:00+08:00", - "metadata": { - "redacted": true - } - } - ], - "items": [], - "total": 1 - } -} -``` - -### 9.6 Timeline - -#### `GET /api/agent/user/deployments/{deployment_id}/timeline` - -聚合审计事件、Runtime callback、artifact、SK snapshot。桌面客户端推荐优先使用这个接口渲染“当前子环节进度”。 - -响应： - -```json -{ - "success": true, - "data": { - "deployment_id": "dep_464a08b7b751", - "deployment": { - "deployment_id": "dep_464a08b7b751", - "sub_mode": "agile", - "status": "accepted", - "phase": "pending", - "runtime_state": "queued" - }, - "events": [], - "callbacks": [], - "artifacts": [], - "sk_snapshots": [], - "timeline": [ - { - "kind": "audit", - "at": 1779850000000, - "event": "deployment.accepted" - }, - { - "kind": "callback", - "at": "2026-05-27T11:45:00+08:00", - "event": "phase.changed", - "event_id": "evt_phase_001", - "event_type": "phase.changed" - }, - { - "kind": "artifact", - "at": 1779850060000, - "event": "test_report", - "artifact_id": "art_test_report_001" - } - ] - } -} -``` - -客户端建议： - -- 轮询间隔：运行中 3-5 秒；终态 15-30 秒或停止。 -- 优先展示 `timeline[]`。 -- 如果存在 `artifact`，提供“查看交付物”入口。 -- 如果存在 `callback.event_type=approval.requested` 或任务状态 `awaiting_approval`，拉取审批接口。 - -## 10. 审批与短期凭证 - -高危操作审批必须由桌面客户端作为主体验展示。Manager 只提供记录、approve/reject 和 lease。 - -### 10.1 查询待审批 - -#### `GET /api/agent/approvals?status=pending&deployment_id={deployment_id}` - -查询参数： - -| 参数 | 类型 | 必需 | 说明 | -|---|---|---:|---| -| `status` | string | 否 | `pending/approved/rejected/expired` | -| `deployment_id` | string | 否 | 按 deployment 过滤 | - -响应： - -```json -{ - "success": true, - "data": { - "items": [ - { - "approval_id": "appr_xxx", - "user_id": 22, - "deployment_id": "dep_464a08b7b751", - "binding_scope": "task-task_abc123", - "operation": "git.write", - "resource_id": "res_git_main", - "resource_type": "git", - "resource_scope": "feature/*", - "target_role": "backend", - "risk_level": "high", - "requires_credential": true, - "credential_lease_id": "", - "status": "pending", - "requested_by": "agent-runtime", - "request_reason": "需要写入功能分支", - "ttl_seconds": 900, - "expires_at": 1779850900000, - "created_at": 1779850000000 - } - ] - } -} -``` - -### 10.2 同意审批 - -#### `POST /api/agent/approvals/{approval_id}/approve` - -请求： - -```json -{ - "reason": "用户确认允许本轮任务写入功能分支" -} -``` - -响应： - -```json -{ - "success": true, - "data": { - "approval_id": "appr_xxx", - "status": "approved", - "credential_lease_id": "lease_xxx", - "credential_lease": { - "lease_id": "lease_xxx", - "credential_ref": "lease://agent/lease_xxx", - "status": "active", - "expires_at": 1779850900000 - } - } -} -``` - -注意：响应只会返回 `lease://...` 引用，不返回明文凭证。 - -### 10.3 拒绝审批 - -#### `POST /api/agent/approvals/{approval_id}/reject` - -请求： - -```json -{ - "reason": "用户拒绝生产环境写入" -} -``` - -响应： - -```json -{ - "success": true, - "data": { - "approval_id": "appr_xxx", - "status": "rejected", - "decision_reason": "用户拒绝生产环境写入" - } -} -``` - -### 10.4 查询 lease - -#### `GET /api/agent/credential-leases?status=active&deployment_id={deployment_id}` - -响应： - -```json -{ - "success": true, - "data": { - "items": [ - { - "lease_id": "lease_xxx", - "credential_ref": "lease://agent/lease_xxx", - "approval_id": "appr_xxx", - "deployment_id": "dep_464a08b7b751", - "resource_id": "res_git_main", - "resource_type": "git", - "target_role": "backend", - "status": "active", - "expires_at": 1779850900000 - } - ] - } -} -``` - -### 10.5 撤销 lease - -#### `POST /api/agent/credential-leases/{lease_id}/revoke` - -请求： - -```json -{ - "reason": "用户停止任务" -} -``` - -响应： - -```json -{ - "success": true, - "data": { - "lease_id": "lease_xxx", - "status": "revoked" - } -} -``` - -## 11. 角色模板 - -### `GET /api/agent/role-templates` - -获取推荐子 Agent 角色，桌面端可用于角色选择页。 - -响应： - -```json -{ - "success": true, - "data": { - "items": [ - { - "key": "backend", - "display_name": "Backend Agent", - "summary": "实现后端接口、数据模型和服务逻辑", - "default_model": "gpt-5.4", - "default_permissions": ["repo:read", "repo:write"], - "risk_level": "medium" - } - ] - } -} -``` - -> `default_model` 由 Manager 单一来源 `defaultAgentModelID()` 提供（环境变量 `AGENT_DEFAULT_MODEL_ID`，默认生产已验证的 `gpt-5.4`）。Manager 不再回退 `agent-model-` 占位名；客户端如不指定 `default_model_id`，draft/runtime agent 会自动采用该单一默认值。 - -## 12. 状态枚举 - -### HeicodeTask.status - -| 状态 | 说明 | 客户端动作 | -|---|---|---| -| `draft` | 草稿 | 可继续编辑 | -| `configuring` | 等待回答追问 | 展示 followups | -| `running` | 可推进/运行中 | 创建 deployment 或展示 timeline | -| `awaiting_approval` | 等待审批 | 拉取 `/api/agent/approvals` | -| `completed` | 完成 | 展示交付物 | -| `failed` | 失败 | 展示失败原因 | -| `paused` | 暂停 | 允许继续或停止 | - -### Agent Deployment.status - -| 状态 | 说明 | -|---|---| -| `accepted` | Manager 已接受并落本地记录 | -| `running` | Runtime 已开始执行 | -| `completed` | Runtime 回调 `deployment.status_changed: completed` 后的成功终态（**真实终态，客户端状态机必须覆盖**；注意需结合 §15.1 成功四要素判断是否为有效交付，`completed` 本身不代表有业务产物） | -| `stopped` | 已停止 | -| `failed` | 失败 | - -> 注意：`status` 由 Manager 接收 Runtime `deployment.status_changed` 后镜像写入。除上述规范值外，Runtime 若回传其他自定义状态字符串，Manager 会透传保存，客户端应对未知值做兜底（按非终态处理或显示原值）。 - -### Agent Deployment.runtime_state - -| 状态 | 说明 | -|---|---| -| `queued` | Manager 本地队列/占位，尚未同步真实 Runtime | -| `runtime_syncing` | 正在同步 Runtime | -| `runtime_accepted` | Runtime 接受 | -| `runtime_sync_failed` | Runtime 同步失败 | -| `not_configured` | 生产 Runtime 未配置 | -| `running` / `completed` / `failed` / `stopped` | Runtime 回调后 `runtime_state` 会镜像 Runtime 上报的状态值；`phase.changed` 还会把 `checkpoint` 写入此字段。客户端不要假设其取值封闭，应做兜底 | - -### 普通 sub 子环节建议值 - -Runtime callback / timeline 中可使用： - -| 阶段 | 说明 | -|---|---| -| `requirements` | 需求 | -| `design` | 设计 | -| `backend` | 后端 | -| `frontend` | 前端 | -| `review` | 检查 | -| `test` | 测试 | -| `deploy` | 部署 | - -## 13. 错误码 - -| 错误码 | 场景 | 客户端处理 | -|---|---|---| -| `TASK_NOT_FOUND` | 任务不存在或 task snapshot 缺失 | 重新拉取任务 | -| `TASK_CONFLICT` | URL task_id 与 body task.id 不一致 | 修正请求 | -| `POLICY_REJECTED` | 参数不符合策略 | 展示错误并阻止继续 | -| `MODEL_NOT_ALLOWED` | 模型不在允许列表 | 让用户换模型或联系管理员 | -| `BUDGET_EXCEEDED` | 预算超过平台策略 | 调低预算 | -| `RESOURCE_GRANT_INVALID` | Resource Grant 字段缺失或角色不匹配 | 重新选择资源权限 | -| `RESOURCE_GRANT_SECRET_REF_REQUIRED` | 凭据型资源缺少 `secret_ref` | 引导用户绑定资源/密钥 | -| `SECRET_REF_INVALID` | `secret_ref` 不是 `azkv://...` | 禁止继续 | -| `RESOURCE_GRANT_SECRET_REJECTED` | metadata/constraints/audit 疑似包含明文密钥 | 禁止继续并提示脱敏 | -| `CALLBACK_SECRET_REJECTED` | Runtime 回调含明文密钥 | 展示安全错误 | - -## 14. 桌面端最小伪代码 - -```ts -type Json = Record - -// 复用模型调用已经使用的 V2 加密 fetch： -// - 自动拉取 /api/server-pubkey -// - 每次请求生成 nonce + X25519 ephemeral key -// - 用 ChaCha20-Poly1305 加密 body -// - 用设备 Ed25519 私钥签名 canonical -// - 设置 Content-Encoding: heicode-aead-v1 和所有 X-Heicode-* 头 -async function encryptedManagerRequest( - method: 'POST', - path: string, - body?: Json, - extraHeaders: Record = {} -): Promise { - return encryptedFetch(`${managerBaseUrl}${path}`, { - method, - plaintextJson: body, - headers: { - Accept: 'application/json', - ...extraHeaders, - }, - }) -} - -const self = await manager.get('/api/user/self') -const userId = self.data.id - -const task = await encryptedManagerRequest>( - 'POST', - '/api/heicode-auth/api/user/tasks/intent', - { intent: userInput }, - { - Authorization: `Bearer ${heicodeAccessToken}`, - } -) - -let current = task.data -while (current.status === 'configuring') { - const followup = findNextFollowup(current) - const answer = await askUser(followup) - current = await encryptedManagerRequest>( - 'POST', - `/api/heicode-auth/api/user/tasks/${current.id}/answer`, - { - question_id: followup.id, - option_id: answer.id, - }, - { - Authorization: `Bearer ${heicodeAccessToken}`, - } - ).then((r) => r.data) -} - -const draft = await encryptedManagerRequest>( - 'POST', - `/api/agent/user/tasks/${current.id}/deployment-draft`, - { - task: current, - sub_mode: 'agile', - binding_scope: `task-${current.id}`, - role_templates: ['backend', 'frontend', 'reviewer'], - default_model_id: 'claude-sonnet-4-6', - } -) - -const deployment = await encryptedManagerRequest>( - 'POST', - '/api/agent/user/deployments', - { orchestration_plan: draft.data.orchestration_plan } -) - -const deploymentId = deployment.data.deployment_id - -setInterval(async () => { - const timeline = await manager.get>( - `/api/agent/user/deployments/${deploymentId}/timeline`, - { headers: { 'New-Api-User': String(userId) } } - ) - renderTimeline(timeline.data.timeline) - - const approvals = await manager.get>( - `/api/agent/approvals?status=pending&deployment_id=${deploymentId}`, - { headers: { 'New-Api-User': String(userId) } } - ) - renderApprovals(approvals.data.items) -}, 5000) - -async function refreshSubDelivery(deploymentId: string) { - const diagnostics = await manager.get>( - `/api/agent/user/deployments/${deploymentId}/runtime-diagnostics`, - { headers: { 'New-Api-User': String(userId) } } - ) - renderRuntimeDiagnostics(diagnostics.data) - - const artifacts = await manager.get>( - `/api/agent/user/deployments/${deploymentId}/artifacts`, - { headers: { 'New-Api-User': String(userId) } } - ) - renderArtifacts(artifacts.data.artifacts) - - const firstDeliverable = artifacts.data.artifacts.find( - (item) => item.artifact_type !== 'log_bundle' - ) - if (firstDeliverable) { - const content = await manager.get( - `/api/agent/user/deployments/${deploymentId}/artifacts/${firstDeliverable.artifact_id}/content`, - { - headers: { 'New-Api-User': String(userId) }, - responseType: 'text', - } - ) - renderArtifactContent(content.data) - } -} -``` - -兼容说明： - -- 桌面客户端对 `POST` 等有 body 的 sub 请求走 V2 加密时，`/api/agent/user/*` 不需要 `New-Api-User`，也不依赖浏览器 cookie。 -- `GET` 查询接口本身没有请求 body，当前生产兼容路径仍使用 Manager session cookie + `New-Api-User`。如果桌面本地服务后续要完全脱离 session cookie 查询 timeline / artifact / approval，需要再补“无 body 的 V2 设备签名 GET”协议。 -- `/api/heicode-auth/*` 仍必须带 `Authorization: Bearer `，该 token 只用于上游 HeicodeTask 认证。 -- 如果客户端临时还没有接入 V2 加密，只能作为调试兼容路径使用 Manager session + `New-Api-User` 调 `/api/agent/user/*`；正式桌面流程不要依赖该路径。 - -## 15. 当前生产注意事项 - -1. `https://code.xinghanlab.com` 的 Manager 用户态接口已上线；当前生产版本为 `1.4.19`。 -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 -> 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`、`code_bundle`、`document`、`test_report`、`deployment_manifest` 等 | -| artifact content | `GET /artifacts/{artifact_id}/content` 返回 200，内容不是 `Runtime execution failed` / `Runtime execution summary` 兜底摘要 | -| 代码任务 | 若用户要求写代码，content 必须能分类为 `code_bundle`、`code_patch` 或 `code_document`，不能是 `summary_only` | - -失败场景示例： - -| 场景 | 客户端提示 | -|---|---| -| `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 处理 | -| artifact content 是“以下是作为 Frontend 角色...”这类角色口吻总结 | Runtime 只返回了方案总结，客户端应提示“未获得真实代码交付物”，并允许用户继续要求生成代码 | diff --git a/docs/integration/heicode-desktop-subagile-e2e-demo.md b/docs/integration/heicode-desktop-subagile-e2e-demo.md deleted file mode 100644 index 85e59e08..00000000 --- a/docs/integration/heicode-desktop-subagile-e2e-demo.md +++ /dev/null @@ -1,232 +0,0 @@ -# Heicode 桌面客户端 ↔ Manager Sub Agile 端到端联调演练（真实数据） - -> 更新时间：2026-06-02 -> 环境：Heicode Manager（生产同构 VM）→ agent_management（Sub Agile Runtime） -> 用途：给桌面客户端团队**逐步对照**接入实现。本文每一步都是**一次真实跑出来的请求 + 真实响应**（任务 `dep_39e53ee4c692`，模型 `gpt-5.4`）。 -> 配套：接口细节见同目录 [`heicode-desktop-unified-api.md`](./heicode-desktop-unified-api.md)。 - -本演练验证的核心结论：**Sub Agile 任务跑完后，agent_management 产出的是真实代码文件 + 目录结构**，Manager 解析成 `project_folder`，客户端可拿到「文件树 / 单文件正文 / 整包 zip」，zip 解压即真实文件夹。 - ---- - -## 0. 角色与链路 - -```text -桌面客户端 ──(只调 Manager)──> Heicode Manager ──(归口)──> agent_management(Sub Agile Runtime) -``` - -- 客户端**只**调 `https://code.xinghanlab.com/api/heicode/sub-agile/*`，不直连 Runtime。 -- Manager 是唯一状态裁判：客户端只看 `display_status`。 -- 认证：与模型调用同一套（写请求 V2 加密 body + 设备签名；GET 无 body 设备签名）。详见统一文档 §1。本演练为聚焦业务流程，示例用已登录态表示，不展开加密细节。 - ---- - -## 1. 创建任务（提交需求包） - -客户端提交**需求包**（不是 Runtime 原始参数），Manager 翻译成编排计划并创建。 - -**请求** -```http -POST /api/heicode/sub-agile/tasks -Content-Type: application/json -``` -```json -{ - "mode": "sub_agile", - "requirement": { - "objective": "做一个前后端分离的 Todo 应用。后端放在 backend/ 目录：backend/main.py (FastAPI, 提供 /todos 增删查) 和 backend/models.py (Todo 数据模型)。前端放在 frontend/ 目录：frontend/src/App.jsx 和 frontend/package.json。根目录加 README.md。每个文件用对应语言代码块, 文件名写在代码块第一行注释里。" - }, - "model_selection": { "type": "single", "default_model": "gpt-5.4" }, - "roles": ["backend"] -} -``` - -**响应（真实）** -```json -{ "success": true, "data": { - "deployment_id": "dep_39e53ee4c692", - "sub_mode": "agile", - "mode": "sub_agile", - "status": "accepted", - "display_status": "accepted", - "runtime_state": "runtime_syncing", - "agent_instances": [ { "instance_id": "agi_...", "role": "backend", "phase": "pending" } ] -}} -``` - -要点： -- `deployment_id` 就是后续所有接口的 `{task_id}`（`task_id ≡ deployment_id`）。 -- 客户端本地保存：`deployment_id` / `mode` / `display_status`，以便重启后恢复。 -- `roles` 决定起几个 agent / 出哪些目录：本例只起了 `backend`，所以只产出 `backend/` 下文件。要前后端并列目录，传 `["backend","frontend"]`。 - ---- - -## 2. 轮询工作流，直到终态 - -**请求** -```http -GET /api/heicode/sub-agile/tasks/dep_39e53ee4c692/workflow -``` - -运行中每 3–5 秒轮询一次，终态后停止。本次真实轨迹： - -```text -poll 1: display_status = accepted -poll 2: display_status = running -poll 3: display_status = completed <- 终态 -``` - -**workflow 响应（真实，节选）** -```json -{ "success": true, "data": { - "task_id": "dep_39e53ee4c692", - "mode": "sub_agile", - "sub_mode": "agile", - "display_status": "completed", - "cloud_deployment_status": "completed", - "runtime_execution_status": "completed", - "phase": "development", - "phases": [ { "phase_id": "development", "name": "development", "status": "completed", "agents": ["backend"] } ], - "agent_count": 1, - "agents": [ { "agent_id": "agi_...", "role": "backend", "status": "completed", - "tokens": 0, "tools": 0, "elapsed_seconds": 0, "artifact_ids": ["art_swm_826fe9814483_backend_1"] } ], - "metrics": { "tokens_used": 618, "tools": 0, "elapsed_seconds": 33, "total_messages": 2 }, - "artifact_ids": ["art_swm_826fe9814483_backend_1"] -}} -``` - -客户端判定规则： -- **只看 `display_status`**。`completed` = 完成且有有效交付物；`needs_codegen` / `completed_without_deliverable` = 没有效产物，别当成功。 -- per-agent 的 `tokens`/`tools` 当前为 `0`（agent_management 暂未上报 per-agent 指标，顶层 `metrics` 是真实值）。 - ---- - -## 3. 取产物列表（确认是项目而非文本） - -**请求** -```http -GET /api/heicode/sub-agile/tasks/dep_39e53ee4c692/artifacts -``` - -**响应（真实，节选）** -```json -{ "success": true, "data": { "items": [ - { - "artifact_id": "art_swm_826fe9814483_backend_1", - "artifact_type": "code_patch", - "is_project": true, - "display_artifact_type": "project_folder", - "manifest_path": ".../artifacts/art_swm_826fe9814483_backend_1/manifest", - "files_path": ".../artifacts/art_swm_826fe9814483_backend_1/files", - "archive_path": ".../artifacts/art_swm_826fe9814483_backend_1/archive" - } -] }} -``` - -要点：**主产物类型看 `display_artifact_type`**。即使 Runtime 原始 `artifact_type=code_patch`，Manager 归一化为 `project_folder` 且 `is_project=true`，并直接给出 manifest/files/archive 子路径，客户端不用自己猜。 - ---- - -## 4. 取文件树（manifest，含目录层级） - -**请求** -```http -GET /api/heicode/sub-agile/tasks/dep_39e53ee4c692/artifacts/art_swm_826fe9814483_backend_1/manifest -``` - -**响应（真实）** -```json -{ "success": true, "data": { - "artifact_id": "art_swm_826fe9814483_backend_1", - "artifact_type": "project_folder", - "root_dir": "project", - "file_count": 2, - "entries": [ - { "path": "backend/models.py", "type": "file", "mime_type": "text/x-python", "size_bytes": 228, - "content_path": ".../files?path=backend%2Fmodels.py" }, - { "path": "backend/main.py", "type": "file", "mime_type": "text/x-python", "size_bytes": 927, - "content_path": ".../files?path=backend%2Fmain.py" } - ], - "archive": { "format": "zip", "download_path": ".../archive" } -}} -``` - -要点：`entries[].path` 带**真实目录层级**（`backend/main.py`）。客户端用 `content_path`（已是 `?path=` URL 编码）直接取单文件，无需自己拼路径。 - ---- - -## 5. 取单文件正文（确认是真代码） - -**请求** -```http -GET /api/heicode/sub-agile/tasks/dep_39e53ee4c692/artifacts/art_swm_826fe9814483_backend_1/files?path=backend%2Fmain.py -``` - -**响应（真实，节选）** -```python -# backend/main.py -from fastapi import FastAPI, HTTPException -from fastapi.middleware.cors import CORSMiddleware -from .models import Todo, TodoCreate - -app = FastAPI(title="Todo API") -app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_credentials=True, - allow_methods=["*"], allow_headers=["*"]) - -todos: list[Todo] = [] -next_id = 1 - -@app.get("/todos", response_model=list[Todo]) -def list_todos(): - ... -``` - ---- - -## 6. 下载整包 zip（确认解压是真实文件夹） - -**请求** -```http -GET /api/heicode/sub-agile/tasks/dep_39e53ee4c692/artifacts/art_swm_826fe9814483_backend_1/archive -``` - -**响应头（真实）** -```text -HTTP/1.1 200 OK -Content-Type: application/zip -Content-Disposition: attachment; filename="art_swm_826fe9814483_backend_1.zip" -Content-Length: 896 -``` - -**解压后真实落盘结构** -```text -project/ -└── backend/ - ├── main.py - └── models.py -``` - -客户端下载契约（务必遵守）： -- 读 `Content-Disposition` 文件名、按 `Content-Length` 校验后再落盘，**保存成功才提示「已下载」**。 -- 产物未就绪时返回 `{"success":false,"error":{"code":"ARTIFACT_ARCHIVE_NOT_READY","retryable":true}}`，此时不要提示已下载。 - ---- - -## 7. 客户端核对清单（照此自检即三端对齐） - -- [ ] 创建任务用**需求包**（`requirement.objective` + `model_selection` + `roles`），从响应拿 `deployment_id`(=`task_id`)。 -- [ ] 运行中每 3–5 秒 `GET .../workflow`，**只读 `display_status`** 判断完成；不订阅 `/events/stream`（未提供）。 -- [ ] 列表/详情/workflow 都读顶层 `mode`（`sub_agile`|`swarm`）做模式标签与路由，重启后用它恢复。 -- [ ] 产物以 `display_artifact_type=project_folder` / `is_project=true` 为准，走 `manifest → files?path= → archive`。 -- [ ] `files?path=` 用 manifest 给的 `content_path`（已 URL 编码），支持 `backend/main.py` 这种嵌套路径。 -- [ ] `archive` 按响应头校验落盘；`ARTIFACT_ARCHIVE_NOT_READY` 时重试不报「已下载」。 -- [ ] 终态成功判据：`display_status=completed` 且 artifacts 非空（`is_project=true`）。 - ---- - -## 附：已知由 Runtime（agent_management）决定、非 Manager 缺陷的点 - -- **目录范围由 `roles` 决定**：只传 `["backend"]` 就只出 `backend/`；要 `frontend/` 等并列目录，传对应角色。 -- **per-agent `tokens`/`tools`/`elapsed_seconds`**：待 agent_management 在状态里上报 per-agent 指标，未上报时为 `0`（顶层 `metrics` 为真实值）。 -- **artifact 归属 agent**：依赖 Runtime 在 artifact metadata 标 `source_agent_role`，未标时 per-agent `artifact_ids` 可能为空。 -- **阶段细分 `phases[]`**：Runtime 现仅上报单个 `phase`，故默认是「当前阶段」一条；待上报阶段历史后展开。 diff --git a/docs/integration/heicode-desktop-unified-api.md b/docs/integration/heicode-desktop-unified-api.md deleted file mode 100644 index 02ba5fff..00000000 --- a/docs/integration/heicode-desktop-unified-api.md +++ /dev/null @@ -1,601 +0,0 @@ -# Heicode 桌面客户端统一接口对接文档（v0.1） - -> ⛔ **已废弃（2026-06-04）**：本文描述的是**已下线的 sub 任务编排模型**（tasks/workflow/display_status/git_ref/产物下载/部署租约等，相关后端已删除）。 -> **新客户端请改用 [`heicode-desktop-client-api.md`](./heicode-desktop-client-api.md)（模板 Agent 模型）。** 本文仅作历史留存。 - -更新时间：2026-06-03 -适用范围：Heicode Desktop 对接 Heicode Manager 的**统一接口层**（Sub Agile / Swarm 两模式）。端到端流程与三端职责以 [`heicode-sub-mode-flow-spec.md`](./heicode-sub-mode-flow-spec.md) 为准,本文是其接口层。 -Manager 生产地址：`https://code.xinghanlab.com` -基准：统一调用方案 v0.1 + agent_management Sub Mode Runtime 对接指南。 - -> 本文取代旧的 `heicode-desktop-sub-agile-api.md`（其 `/api/agnet/*` 路由已废弃）。新客户端一律使用本文的 `/api/heicode/*` 与 `/api/agent/*` 接口。 - -> **⚠️ 2026-06-03 流程对齐（权威端到端流程见 [`heicode-sub-mode-flow-spec.md`](./heicode-sub-mode-flow-spec.md)，本文是其接口层）。几处认知已纠正:** -> - **客户端是 Claude-Code 式智能体程序**(本地能跑 agent、执行命令、本地部署),不是无 AI 的壳;**HM = 模型网关(`/v1/*`)+ 控制面**,给客户端和 agent_management 两边都提供模型;**agent_management = 云端多 agent 运行时**。 -> - **sub 模式 = 把多 agent 任务派到云端 agent_management 跑**(区别于客户端本地自己跑小任务)。 -> - **`display_status` 只代表"跑完没/有没有真产物(防空壳)",不代表"代码对不对"**。代码对错 = **客户端(本地能跑能测)+ 用户 review** 判,**不是 HM 判**(HM 没 AI、不读代码)。详见 spec §6。 -> - **部署 = 客户端执行 + 用户必须确认**;HM 只把凭据从 Key Vault 安全发给客户端,**HM 不部署、不连 VM**(见 §7,已改)。 -> - **产物归宿是用户自己的 git 仓库**(github/gitea);先绑仓库(及 vm/db/blob)→ §8 资源绑定。 -> -> **2026-06-02 更新（gap-analysis P0/P1 闭环并实跑验证）**：GET 无 body 设备签名(§1)、审批列表(§3.2)、Swarm 同形(§3)。 -> -> **2026-06-03 更新（产物模型对齐）**：sub 模式**强制绑定 git** 才能用,否则只能本地跑——因此**代码产物的唯一归宿是用户自己的 git 仓库**(clone/pull)。早期"HM 把文本产物解析成项目文件夹(`project_folder`/manifest/files/archive)"是无 git 流程的残留,**不再作为代码交付路径**;artifacts 接口仅保留给**非代码产物**(test_report/摘要)。详见 §5。 - -## 0. 命名与总原则 - -- **命名统一**：`agnet` 是历史拼写错误，已全量改为 `agent`。所有新接口为 `/api/agent/*`、`/api/heicode/*`；旧 `/api/agnet/*` 已下线（404）。 -- **客户端只调 Heicode Manager(HM)**：任务/控制走 `/api/heicode/*`、`/api/agent/*`，模型走 `/v1/*`；禁止直连 agent_management / HeiCode-Swarm / Runtime artifact 接口。 -- **`display_status` 是 HM 的"进度/有无产物"裁决,不是"对错"裁决**：客户端用它判断"跑完没、是不是空交付"(防空壳),**但代码对不对由客户端自己拉下来跑/测 + 用户 review 决定**(HM 没 AI、不读代码、不编译)。 -- **task_id ≡ deployment_id**：统一任务接口里 `{task_id}` 即 HM 的 `deployment_id`。 - -## 0.1 推荐完整流程 - -```text -0. (★必做) 绑定 git 仓库 (github/gitea) + (可选) vm/db/blob -> 凭据进 Key Vault, 拿 resource_binding_id (§8) - 未绑 git 则禁用 sub 入口 (强制绑 git, §3.1) -1. GET /api/heicode/capabilities 取模式/模型，渲染模式与模型选择 -2. POST /api/heicode/sub-agile/tasks (需求包, 带 resource_bindings.git + X-Idempotency-Key) - 创建任务 -> 响应里拿 deployment_id(=task_id) (§3.1) -3. (可选) POST .../tasks/{id}/execute 若需"先建后跑"或重试派发 -4. 轮询 GET .../tasks/{id}/workflow (运行中 3-5s) / 将来 SSE 读 display_status + 三层状态 + agents + git_ref (§4b) -5. 出现 approval 时: GET .../approvals?status=pending -> approve/reject -6. display_status=completed 后: 按 workflow 里的 git_ref 做 git clone/pull (完整工程+历史+diff) (§5) - (非代码运行信息如 test_report/摘要 -> GET .../artifacts 查看; HM 不托管/不解析项目代码) -7. 不满意 -> 改/重做: POST .../messages|/execute 回云端改; 或 git pull 本地用客户端自己的 agent 改 (§6) -8. (可选) 部署: 用户确认 -> 客户端凭 resource_binding_id 取短期租约(V2) -> 客户端本地 git/ssh/部署 (§7, HM 不代执行) -``` - -> 成功判据：`display_status=completed` 且 `git_ref` 有新 commit = **跑完且有真东西**;但**"代码对不对"客户端自己拉下来跑/测 + 用户 review**(`completed` 不保证正确,见 §4)。 - -## 1. 认证与加密（重要） - -桌面客户端调用本文所有 `/api/heicode/*` 接口，**body 加密与签名和模型调用（`/v1/*`）完全一致**——直接复用同一套 `encryptedFetch` / V2 设备签名实现，无需新增协议。 - -| 方式 | 适用 | -|---|---| -| **V2 加密 body + 设备签名**（`Content-Encoding: heicode-aead-v1` + `X-Heicode-*`，ChaCha20-Poly1305 + Ed25519） | 有 body 的请求（POST/PUT/DELETE） | -| **V2 无 body 设备签名**（`X-Heicode-*` 签名头，**不带** `Content-Encoding`） | GET 等无 body 请求（fetch 规范禁止 GET 带 body） | -| Manager session cookie + `New-Api-User: ` | Web 控制台兼容路径（桌面端可不用） | - -要点（与模型调用相同，未变）： -- `aad` / `canonical` 里的 `path_with_query` 必须是 Manager 实际收到的 path，例如 `/api/heicode/sub-agile/tasks`，不含 origin。 -- 每次新 `X-Heicode-Nonce` + 新 X25519 临时 key；签名里 `sha256_hex(plaintext_body)` 与加密前 JSON 字节一致。 -- 服务端在新路由上用同一中间件 `UserOrV2DeviceAuth` 解密+验签，从设备绑定 token 解析用户身份；失败读响应头 `X-Heicode-Auth-Error`。 - -**GET 全程无 cookie 的设备签名（已支持）**：GET 没有 body，因此**不发** `Content-Encoding`、**不加密**，但仍发同一套签名头并用相同 canonical 公式签名，`sha256_hex(plaintext_body)` 处填**空 body 的哈希** `sha256("")`： -```text -canonical = method + "\n" # "GET" - + path_with_query + "\n" # 例如 /api/heicode/sub-agile/tasks/dep_x/workflow - + timestamp_ms + "\n" - + nonce_hex + "\n" - + device_fingerprint + "\n" - + ephemeral_pubkey_b64 + "\n" # GET 仍生成一对临时 X25519 key 并带 X-Heicode-Eph-Pubkey - + sha256_hex("") # e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 -signature = base64( ed25519_sign(device_priv, sha256(canonical)) ) -``` -即：GET 与写请求共用同一签名实现，区别仅是「不加密 body、body 哈希为空串哈希」。服务端凭 `X-Heicode-Signature` + `X-Heicode-Device-Id` + `X-Heicode-Eph-Pubkey` 三个头识别该模式（gap P0-1 已闭环）。客户端可用同一 `encryptedFetch`，对 GET 走「跳过加密、空 body」分支即可。 - -## 2. 能力发现 - -### `GET /api/heicode/capabilities` -无需登录，返回模式与模型目录。 - -```json -{ "success": true, "data": { - "modes": [ - {"id":"sub_agile","name":"Sub Agile","runtime_kind":"agent_management","model_selection":"per_role","supports_roles":true,"supports_task_graph":false,"supports_artifacts":true,"supports_continue_chat":true,"enabled":true}, - {"id":"swarm","name":"Swarm","runtime_kind":"heicode_swarm","model_selection":"primary","supports_roles":false,"supports_task_graph":true,"supports_artifacts":true,"supports_continue_chat":true,"enabled":false} - ], - "models": [{"id":"gpt-5.4","name":"gpt-5.4","available":true}] -}} -``` - -`enabled` 反映该模式 Runtime 当前是否接通（HM 探测 agent_management / HeiCode-Swarm 的健康；`enabled:false` 时**不要**让用户进该模式）。 -字段：`runtime_kind`（后端运行时）、`model_selection`（`default|per_role|primary`）、`supports_roles/task_graph/continue_chat`（UI 能力位）、`models[].available`（该模型当前可用）。 - -### 2.1 判断 sub 模式是否可用（就绪闸门）🟡 - -客户端在让用户点「sub 模式」前，必须先过**四道闸门**；任一不满足就**禁用 sub 入口**并提示对应引导。这是一个**客户端本地组合判断**（HM 不提供单一「ready」接口）： - -| # | 闸门 | 数据来源 | 不满足时 | -|---|---|---|---| -| 1 | **Runtime 接通** | `GET /api/heicode/capabilities` → `modes[id=sub_agile].enabled === true` | 灰掉 sub，提示「云端暂不可用」 | -| 2 | **已认证（设备已绑定）** | 本地有设备绑定 token（§1；无则先走 heicode-auth 登录/配对） | 引导登录 | -| 3 | **已绑有效 git 仓库** | `GET /api/heicode/resources?type=git&status=active`（§8.2）非空 | 引导去「资源绑定」绑 git，或改用本地模式 | -| 4 | **余额充足** | `GET /api/user/self` → `quota - used_quota > 0`（§2.2） | 引导充值 | - -```text -canUseSub = - capabilities.modes.find(m => m.id==='sub_agile')?.enabled - && isDeviceBound() - && gitBindings.some(b => b.status==='active') - && self.quota > self.used_quota -``` - -- 闸门 3「强制绑 git」对齐 spec §3.1；建任务时若仍没传有效 git binding，HM 也会兜底拒绝（`SUB_GIT_BINDING_REQUIRED`，§11）。 -- 闸门 1/4 用现有接口（🟢）；闸门 3 的客户端版资源列表是 🔴 待建（§8.2），上线前可临时用 `/api/resources/`（会话鉴权）联调。 -- **本地模式**（客户端自己跑 agent）不需要闸门 1/3，只需 2/4。 - -### 2.2 账户与余额（判断能不能跑 / 给概览用）🟢 - -| 方法 | 路径 | 鉴权 | 说明 | -|---|---|---|---| -| GET | `/api/user/self` | 会话/设备 | 当前用户：`quota`(剩余额度)、`used_quota`(累计已用)、`request_count`(调用次数)、分组等 | -| GET | `/api/user/self/groups` | 同上 | 用户可用模型分组 | -| GET | `/api/user/self/models` | 同上 | 当前用户**可用模型**列表（与 `capabilities.models` 互补，按分组过滤） | - -```json -// GET /api/user/self → data 摘要 -{ "id":22, "username":"...", "quota":160470000, "used_quota":39530000, "request_count":521, "group":"default" } -``` - -- 余额/用量单位是内部 quota（展示按汇率换算）；`quota` 为**剩余**，`used_quota` 为**累计已用**。 -- 建任务前应检查 `quota > used_quota`（闸门 4）；运行中若超预算 HM 会把任务标 `budget_exceeded`（§4）。 -- 模型选择（需求包 `model_selection`）只能用 `capabilities.models` ∩ `/api/user/self/models` 里 `available` 的模型。 - -## 3. 统一任务接口 - -两套前缀，按模式选择：`/api/heicode/sub-agile/*`（→ agent_management）、`/api/heicode/swarm/*`（→ HeiCode-Swarm）。**下表以 sub-agile 为例，swarm 路径把前缀 `sub-agile` 换成 `swarm` 后完全同形（approvals/deployments/workflow 等子接口）**——两组路由由同一注册函数生成，不存在「只实现了 sub-agile」的情况。（注：`files/archive/revisions/local-edits` 这些遗留子接口两侧也都还在，但已不作为代码交付路径，见 §5/§6。） - -| 方法 | 路径 | 说明 | -|---|---|---| -| POST | `/api/heicode/sub-agile/tasks` | 创建任务（body = **需求包**，见 §3.1） | -| GET | `/api/heicode/sub-agile/tasks` | 任务列表 | -| GET | `/api/heicode/sub-agile/tasks/{task_id}` | 任务详情（含 `display_status`，读取时自动从 Runtime 收敛） | -| POST | `/api/heicode/sub-agile/tasks/{task_id}/messages` | 持续对话：追加用户消息 | -| POST | `/api/heicode/sub-agile/tasks/{task_id}/execute` | 触发/确保执行（未派发则派发 Runtime） | -| DELETE | `/api/heicode/sub-agile/tasks/{task_id}` | 删除/停止任务 | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/workflow` | 工作流投影（右侧面板：mode/display_status/phases/agents(含 current_action/branch/tokens/tools/elapsed/artifact_ids)/metrics/**git_ref**/artifacts） | -| POST | `/api/heicode/sub-agile/tasks/{task_id}/stop` | 停止 | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/timeline` | 时间线（events/callbacks/artifacts 聚合） | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/logs` | 日志（含 `user_logs` 友好 + `debug_logs` 原始两层） | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/events` | 事件 | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/metrics` | 指标 | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/diagnostics` | 诊断（直查 Runtime 状态 + warnings） | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/sk-snapshots` | SK 快照 | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/artifacts` | 产物列表（**仅非代码产物**：test_report/摘要等；代码看 git，见 §5） | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/content` | 单产物正文（如测试报告） | -| ~~GET~~ | ~~`.../artifacts/{artifact_id}/{manifest,files,archive,revisions}`~~ | **遗留**：无 git 流程的"HM 解析项目文件夹"接口，sub 强制 git 后不再作为代码交付路径（后端仍在，见 §5） | -| ~~POST~~ | ~~`.../artifacts/{artifact_id}/local-edits[/batch]`~~ | **遗留**：本地改产物改用 git 提交 | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/approvals?status=pending` | 审批列表（gap P0-2） | -| POST | `/api/heicode/sub-agile/tasks/{task_id}/approvals/{approval_id}/approve` | 同意审批 | -| POST | `/api/heicode/sub-agile/tasks/{task_id}/approvals/{approval_id}/reject` | 拒绝审批 | -| GET | `/api/heicode/sub-agile/tasks/{task_id}/deployments` · POST 同路径 | ⚠️ 旧的「Manager 代部署」控制面,**不再作为部署主路径**;新部署=客户端执行(见 §7) | - -### 3.1 创建 body（需求包） - -客户端提交**需求包**，不提交 Runtime 原始参数；Manager 内部翻译成 orchestration_plan 并创建。 - -```json -{ - "mode": "sub_agile", - "client_role": "main_agent", - "conversation_id": "conv_xxx", - "requirement": { - "objective": "做一个 Oracle 云代理商网站，前后端分离", - "context": [], "attachments": [], "constraints": [], "acceptance_criteria": [] - }, - "model_selection": { - "type": "per_role", - "default_model": "gpt-5.4", - "roles": {"backend":"gpt-5.4","frontend":"gpt-5.4"} - }, - "roles": ["backend", "frontend"], - "resource_bindings": { - "git": "rb_git_xxx", // ★ 必填：用户绑定的 git 仓库（§8）。缺则拒绝建任务 - "vm": "rb_vm_xxx", // 可选：部署目标，仅在需要时 - "database": "rb_db_xxx", // 可选 - "blob": "rb_blob_xxx" // 可选 - }, - "git_options": { // 可选：覆盖 binding 默认 - "base_branch": "main", // 从哪个分支拉基线 - "mode": "existing", // greenfield(绿地新建) | existing(已有代码上增量改) - "allowed_paths": ["backend/", "frontend/"], // 限定 agent 工作目录，避免动无关代码 - "write_mode": "pr" // pr(开 PR/交付分支，建议) | branch | main - } -} -``` - -- **★ `resource_bindings.git` 必填**：sub 模式强制绑 git（spec §3.1 决策）。未传或 binding 失效 → HM 拒绝建任务，返回 `SUB_GIT_BINDING_REQUIRED`（见 §11）。客户端 UI 应在未绑 git 时**禁用 sub 入口**，引导先绑（§8）或改用本地模式。 -- 只传 `resource_binding_id`（如 `rb_git_xxx`），**绝不内联明文凭据**；HM 从 Key Vault 解出短期 PAT 注入 AM。 -- `model_selection.type`：`default`（全局 `default_model`）/ `per_role`（`roles` 映射）/ `primary`（Swarm 用 `primary_model`）。 -- `conversation_id` 作为任务关联键（落到 `correlation_id`）。 -- 模型必须用生产 NewAPI 已存在模型（当前推荐 `gpt-5.4`）。 -- 兼容：也接受直接传 `{ "orchestration_plan": {...} }`（高级用法）。 - -**幂等**：创建请求带 `X-Idempotency-Key: `（spec §9.3）。HM 对同 key 去重，网络重试不会建重复任务/重复 git 分支；重复命中返回首次的 `deployment_id`。 - -> 状态标注：`resource_bindings` / `git_options` / `SUB_GIT_BINDING_REQUIRED` / `X-Idempotency-Key` 均为 🔴 待建（随 git 化与客户端版资源接口一起上线，见 §8）。当前后端建任务尚未强制 git；客户端应**按本规范预留字段**，HM 侧补齐校验后即对齐。 - -`/messages` body：`{"message":"继续把测试补上","role":"user"}`。 -`/execute` body 可空；用于"创建后再触发"或重试派发。 - -**创建响应**（`deployment_id` 即后续所有 `{task_id}`）： - -```json -{ "success": true, "message": "", "data": { - "deployment_id": "dep_b5fab27e9255", - "sub_mode": "agile", - "status": "accepted", - "display_status": "accepted", - "runtime_state": "runtime_syncing", - "runtime_swarm_id": "", - "agent_instances": [ - {"instance_id":"agi_xxx","role":"backend","phase":"pending","runtime_state":"queued","failure_reason":""} - ], - "permission_manifest": {"user_id":"22","binding_scope":"","resource_grants":[]} -}} -``` - -**任务详情** `GET .../tasks/{task_id}` 返回同形 + 完整 `orchestration_plan`；**任务列表** `GET .../tasks` 返回 `{"items":[ ...同上... ],"total":N}`。客户端按 `display_status` 渲染，详情/列表读取时 Manager 会自动从 Runtime 收敛终态。 - -### 3.2 审批列表（gap P0-2） - -`GET .../tasks/{task_id}/approvals?status=pending`： - -```json -{ "success": true, "data": { - "task_id":"dep_xxx","total":1, - "items":[ - {"approval_id":"appr_xxx","deployment_id":"dep_xxx","type":"deploy","risk_level":"high", - "title":"生产部署审批","status":"pending","created_at":"2026-06-02T00:00:00Z"} - ] -}} -``` - -`status` 省略则返回全部；对每条 `pending` 项调 `.../approvals/{approval_id}/approve|reject` 闭环。 - -## 4. 状态模型（display_status） - -客户端只展示 `display_status`（Manager 裁决结果）： - -| display_status | 含义 | -|---|---| -| `accepted` / `running` / `waiting_approval` | 进行中 | -| `completed` | 跑完且**有真实产物**（非空、非兜底）—— 注意:**不代表代码正确** | -| `completed_without_deliverable` | Runtime 完成但无产物（无 git 提交） | -| `needs_codegen` | 只有方案/总结，需继续生成代码 | -| `budget_exceeded` 🔴 | 超 token/时长/成本上限，已暂停待用户决定续不续（spec §9.3） | -| `failed` / `stopped` | 终态 | - -裁决规则（对齐 spec §6.4）：AM 说 `completed` 后，HM 看**有没有真交付**—— -- **目标态**：回调带 `git_ref` 且有**真实提交**（commit/改了 N 个文件）→ `completed` ✅。 -- 只有方案/总结、没有提交 → `needs_codegen`；什么都没有 → `completed_without_deliverable`。 -- 过渡期（AM 未 git 化）：带"改了 N 个文件"信号的非兜底 artifact（`metadata.synthesized!=true` 且非纯总结）也按真交付算。 -HM 判的是**"有没有真东西"这个事实**，**不读代码、不判对错**。 - -> ⚠️ **`display_status` 的边界(重要,见 spec §6.6)**:HM 只判**事实**——跑完没、有没有真产物、是不是空壳/兜底;**HM 不读代码、不编译、不测试,判不了"代码对不对"**。`completed` 只保证"有真东西",**不保证代码正确**。**对错由客户端自己拉产物跑/测 + 用户 review 决定**。若 agent_management 跑了测试,会作为 `test_report` 产物给客户端看,**不是给 HM 裁决**。 - -### 4.1 三层状态（`GET .../workflow`） - -`GET /api/heicode/sub-agile/tasks/{task_id}/workflow` 返回客户端右侧面板需要的三层状态对象： - -```json -{ "success": true, "data": { - "task_id":"dep_xxx","conversation_id":"conv_xxx", - "mode":"sub_agile", // 顶层模式 sub_agile|swarm（与 capabilities 一致） - "sub_mode":"agile", // sub_agile 内的节奏 agile|waterfall - "cloud_deployment_status":"completed", // Manager 控制面状态 - "runtime_execution_status":"completed", // Runtime 上报状态 - "display_status":"completed", // 唯一展示状态（客户端只看这个） - "last_synced_at":"2026-06-02T...", - "title":"...","summary":"...","phase":"development","agent_count":1, - "phases":[ // 阶段列表（runtime 未给细分时为当前阶段单条） - {"phase_id":"development","name":"development","status":"completed","agents":["backend"]} - ], - "agents":[ - {"agent_id":"agi_x","name":"backend","role":"backend","status":"completed", - "current_action":"已合并到交付分支", // 🔴 一句话「现在在干啥」，给 work 视图滚动 - "branch":"agent/backend", // 🔴 该 agent 的分支（看单角色 diff） - "tokens":0,"tools":0,"elapsed_seconds":0,"artifact_ids":["art_x"]} - ], - "git_ref": { // 🔴 交付引用（见 §5.2）；未就绪时为 null - "provider":"github","repo_url":"https://github.com/owner/repo", - "branch":"delivery/dep_xxx","commit_sha":"a1b2c3d","tag":"delivery-dep_xxx-rev1", - "pull_request_url":null - }, - "artifacts":[{"artifact_id":"art_x","title":"测试报告","artifact_type":"test_report"}], // 仅非代码运行信息 - "artifact_ids":["art_x"], - "metrics":{"tokens_used":618,"tools":0,"elapsed_seconds":33,"total_messages":2}, - "tokens":618,"tools":0,"elapsed_seconds":33 -}} -``` - -字段说明（gap A/D/F）： -- `mode`：顶层 `sub_agile|swarm`，与 `capabilities` 一致；列表 `GET .../tasks` 的每个 item 也带 `mode` 和 `display_status`，重启后从列表恢复任务不会把 swarm 当成 sub-agile。`sub_mode` 是 sub_agile 内部节奏。 -- `git_ref`：**客户端据此 `git pull` 看产物**（§5.2）。`completed` + `git_ref` 有 `commit_sha` = 本轮真交付落到了用户仓库；续跑/重做后 `commit_sha` 会更新。🔴 待 AM 回调带 git_ref + HM 透出。 -- `phases[]`：始终是数组。当前 sub-mode runtime 只上报单个 `phase`，故默认是「当前阶段」一条；待 runtime 上报阶段细分后会展开。 -- `metrics` / 顶层 `tokens/tools/elapsed_seconds`：来自 runtime 状态指标（`tokens_used`/`elapsed_seconds`/`total_messages` 为真实值）。 -- 每个 agent 的 `current_action`/`branch`/`tokens`/`tools`/`elapsed_seconds`：**待 agent_management 上报 per-agent 富字段**（🔴），未上报时为空/`0`；`artifact_ids` 按 `source_agent_role` 归到对应 agent。 -- `artifacts[]`：只放**非代码运行信息**（test_report/summary）；代码看 `git_ref`，不在此处。 - -`client_task_status`（本地交互态）由客户端自己维护，不由 Manager 返回。 - -### 4.2 运行信息接口（日志 / 时间线 / 诊断 / 事件 / 指标）🟢 - -work 视图除 `/workflow` 外，下列接口给**过程信息**（都只读、GET、V2 无 body 签名）。**它们只承载"运行信息"，不承载代码产物**（代码看 git_ref，§5）。 - -| 方法 | 路径 | data 关键字段 | 用途 | -|---|---|---|---| -| GET | `.../tasks/{id}/logs` | `user_logs[]`（友好）、`debug_logs[]`（原始）| 日志面板分两层：普通用户看 user，调试面板看 debug | -| GET | `.../tasks/{id}/timeline` | `events[]`（task./agent./phase./handoff./delivery.）、`callbacks[]`、`artifacts[]` 聚合 | 任务时间线 | -| GET | `.../tasks/{id}/events` | `events[]`（原始事件流） | 细粒度事件 | -| GET | `.../tasks/{id}/metrics` | `tokens_used`、`elapsed_seconds`、`total_messages` | 指标卡 | -| GET | `.../tasks/{id}/diagnostics` | `runtime_status`、`warnings[]`（直查 Runtime） | 排障 | -| GET | `.../tasks/{id}/sk-snapshots` | `snapshots[]` | SK 快照 | - -```json -// GET .../logs → data -{ "task_id":"dep_xxx", - "user_logs":[{"ts":"2026-06-03T..","level":"info","agent":"backend","message":"开始实现登录接口"}], - "debug_logs":[{"ts":"2026-06-03T..","level":"debug","message":"tool: write_file path=backend/auth.go"}] } -``` -```json -// GET .../timeline → data -{ "task_id":"dep_xxx", - "events":[{"event_type":"phase.changed","occurred_at":"..","payload":{"phase":"development"}}, - {"event_type":"delivery.pushed","occurred_at":"..","payload":{"git_ref":{"branch":"delivery/dep_xxx","commit_sha":"a1b2c3d"}}}], - "callbacks":[], "artifacts":[{"artifact_id":"art_x","artifact_type":"test_report"}] } -``` - -> 轮询建议：work 视图主要轮询 `/workflow`（含 display_status + agents + git_ref，一次拿全）；需要日志/时间线明细时再单独拉 `/logs`、`/timeline`。SSE 上线后这些都可由事件流推送（§4b）。 - -## 4b. 响应 envelope 与实时刷新 - -**成功**：`{ "success": true, "message": "", "data": {...} }` -**失败**：`{ "success": false, "message": "...", "error": { "code": "...", "message": "...", "retryable": false, "request_id": "..." } }` - -`task_id` / `deployment_id` / `conversation_id` / `correlation_id` 在各接口的 `data` 内返回（无独立 `trace` 字段）。 - -**实时刷新（现状 🟢 轮询）**：当前**未提供 SSE**；客户端按统一方案 §17.3 兜底用**轮询**刷新： -- 运行中：每 3–5 秒 `GET .../workflow`（或 `.../timeline`）； -- 终态：降到 15–30 秒或停止。 -- 现在**不要**订阅 `.../events/stream`（未提供，会 404）。 - -**实时流（目标 🔴，对齐 spec §5）**：上线后 HM 提供 `GET /api/heicode/sub-agile/tasks/{id}/events/stream`（SSE），把 AM 回调实时转发给客户端，**只推运行信息**（不推产物文件）。统一事件信封： - -```json -{ "event_type":"agent.action", "deployment_id":"dep_xxx", "agent_id":"agi_x", - "phase":"development", "occurred_at":"2026-06-03T...", "payload":{ "...": "..." } } -``` - -事件类型（最小集）：`agent.action`（某 agent 现在在干啥）、`tool.call`（调了什么工具）、`phase.changed`（阶段切换）、`log.line`（日志行，分 user/debug）、`delivery.pushed`（**产物就绪通知，payload 带 `git_ref`，不是文件**）、`status.changed`（display_status 变化）、`approval.required`（出现待审批）。 - -- **断线重连**：用 `Last-Event-ID`（基于 HM 事件游标）续传。 -- **降级**：SSE 不可用自动回落轮询，UI 行为一致（只是延迟）；未上线前 `/events/stream` 返回未实现，客户端按 `capabilities`/探测决定走哪条，**别硬连**。 - -## 5. 产物（代码只在 git；artifacts 仅非代码运行信息） - -> **前提：sub 模式强制绑定 git 才能用**（未绑 git 只能本地跑，进不了 sub）。所以**代码产物的唯一归宿就是用户自己绑定的 git 仓库**。**没有"下载产物"这回事**（`project_folder`/manifest/files/archive zip 全部退役，见 5.4）。 - -### 5.1 代码产物 = git 仓库（唯一路径）🟡 - -`display_status=completed` 后，客户端直接对**用户自己绑定的仓库**（§8 资源绑定里的 `git` 类型）做 `git clone` / `git pull`，拿到完整工程 + 提交历史 + diff。本地改、重做、合并、部署都在工作副本上走标准 git，**不经 HM**——HM 不托管、不解析、不打包项目代码。 - -> 状态：AM 真正"git 入库 + 多 agent 分支 + 合并"为 🔴 待建；当前过渡实现见 spec §3.5。 - -### 5.2 交付引用 `git_ref`：客户端怎么知道去哪 pull 🔴 - -客户端**不需要自己猜分支**——HM 在任务详情 / `workflow` 里回带一个 `git_ref`，指明交付落在哪个仓库/分支/commit；客户端据此 `pull`： - -```json -"git_ref": { - "provider": "github", - "repo_url": "https://github.com/owner/repo", - "branch": "delivery/dep_b5fab27e9255", // 交付分支（或 PR 源分支） - "commit_sha": "a1b2c3d…", // 本轮交付的提交 - "tag": "delivery-dep_b5fab27e9255-rev2", // 可选：版本标签，便于回溯/指定版本部署 - "pull_request_url": "https://github.com/owner/repo/pull/12", // 若走 PR 模式 - "agent_branches": [ // 可选：各 agent 的分支，便于看单角色 diff - {"role":"backend","branch":"agent/backend"}, - {"role":"frontend","branch":"agent/frontend"} - ] -} -``` - -- `git_ref` 出现 = 本轮已 push 到用户仓库（配合 `display_status=completed`）。客户端 `git fetch && git checkout `（或 pull）即可。 -- **重做/续跑**会更新 `commit_sha`（及可能新的 `branch`/`tag`）；客户端 pull 最新即可。 -- HM 只**记录并回带这个引用**，自己不执行任何 git 操作（git 由 AM 用注入的短期 PAT 执行，见 spec §7）。 -- 状态：🔴 待建——需 AM 回调带 `git_ref`、HM 在 `workflow`/详情透出。当前过渡期 AM 还回 blob artifact（见 5.4）。 - -### 5.3 非代码产物 = artifacts 接口（运行信息，非下载交付物）🟡 - -agent_management 跑出的**非代码**东西（如 `test_report` 测试报告、`summary` 摘要、说明），通过 artifacts 列表给客户端在 work 视图里**查看**，**不是可下载的工程产物**： - -| 方法 | 路径 | 说明 | -|---|---|---| -| GET | `.../tasks/{task_id}/artifacts` | 非代码产物列表（test_report / summary 等运行信息记录） | -| GET | `.../artifacts/{artifact_id}/content` | 单条记录正文（如测试报告全文） | - -`test_report` 只是给客户端/用户**看**，**不参与 HM 的 `display_status` 裁决**（HM 不读代码、不判对错，见 §4 / spec §6.6）。 - -### 5.4 遗留接口（已退役，新集成勿用） - -早期「无 git 流程」里 runtime 只吐一坨 markdown 文本，HM 现解析成项目文件树（`project_folder` / `manifest` / `files?path=` / `archive` / `revisions` / `local-edits`）供浏览、下载、回传。**sub 强制 git 后这套全部退役**：看代码=git 工作副本，回传改动=`git commit/push`。后端实现暂保留（向后兼容），但**新集成不要依赖**，也不要再用 `is_project` / `display_artifact_type:"project_folder"` 判交付——交付以 `display_status=completed`（§4）+ `git_ref` 有新 commit 为准。 - -## 6. 修改 / 重做（基线 = git）🟡🔴 - -> **唯一基线 = 用户仓库的最新提交**。不存在 HM 侧 `local-edits`/revision 回传机制（已退役）。 - -| 动作 | 接口 | 谁干 | 状态 | -|---|---|---|---| -| **续跑/改**（路径 A，回云端） | `POST .../tasks/{id}/messages`（追加要求） | AM 先 `git pull` 取最新提交作基线 → 在其上改 → push；HM 转发 | 🟡 HM 转发已通；AM 中途续跑 🔴 | -| **重做** | `POST .../tasks/{id}/execute`（或将来 `/redo`） | AM 在**新分支**重新生成（旧交付分支保留可对比），回带新 `git_ref` | 🔴 待 AM 支持 redo 语义 | -| **本地改**（路径 B，回本地模式） | 客户端 `git pull` → 本地 agent 改 → `git push` | 客户端（模型仍走 HM `/v1/*`）；想让云端接力就 push 后再 `/messages`，AM `pull` 自然拿到 | 🟡 | -| **停止** | `POST .../tasks/{id}/stop` / `DELETE .../tasks/{id}` | 已 commit 的代码**保留在分支不回滚**，任务标 `stopped`；可在该分支续跑或丢弃 | 🟢/🟡 | - -`/messages` body：`{"message":"继续把测试补上","role":"user"}`。`/execute` body 可空。 - -## 7. 部署（✅ 客户端执行 + 用户必须确认；HM 只发凭据） - -> ⚠️ **流程已改(对齐 spec §3.8)**：**HM 不部署、不连 VM、不执行命令**。部署由**客户端**在用户机器上执行(客户端是 Claude-Code 式程序),且**必须用户显式确认**。HM 的角色仅是:**把绑定的凭据从 Key Vault 解出 → 经 V2 加密通道安全发给客户端 → 记审计**。下面这套「Manager 代部署/Deploy Worker」是**旧模型,已废弃**。 - -**新流程:** -1. 用户先在 HM **绑定** git/vm/db/blob 资源(§8),拿到 `resource_binding_id`(凭据已进 Key Vault,只留 `secret_ref`)。 -2. 客户端发起部署 → **弹窗让用户确认**(目标 VM / 环境 / 用哪条 binding / 影响范围)。 -3. 用户确认 → 客户端向 HM 的**凭据租约接口**(V2 加密)凭 `resource_binding_id` 换取**短期凭据租约**(经加密通道返回,带 TTL + 审计)。 -4. **客户端在用户机器上执行**:`git pull` 用户仓库 → ssh 到 VM → 跑部署命令 → 在 VM 上看日志。**全程 HM 不碰 VM。** - -**凭据租约接口（🔴 待建，对齐 spec §3.8/§4.5）：** - -`POST /api/heicode/resources/{binding_id}/lease`（V2 加密 + 设备签名） - -请求：`{ "purpose":"deploy", "target":"vm:rb_vm_xxx", "task_id":"dep_xxx", "ttl_seconds":600 }` - -响应： -```json -{ "success": true, "data": { - "lease_id": "lease_xxx", - "binding_id": "rb_vm_xxx", - "credential": { "type":"ssh_key", "username":"deploy", "private_key":"<经 V2 通道明文，仅本次>" }, - "expires_at": "2026-06-03T...Z", // 短 TTL - "revocable": true -}} -``` - -- 凭据**只在本次响应内**经 V2 加密通道下发，客户端**用完即弃、不落盘、不进日志**（§10）。 -- **高危目标**（如生产 VM）：HM 先建一条审批（`display_status=waiting_approval` / §3.2），**审批通过后才发租约**。 -- 吊销：`DELETE /api/heicode/resources/leases/{lease_id}`，或用户删 binding → 已发租约到期自然失效。 -- HM 只**发租约 + 记审计**（谁/哪条 binding/用途/时间/TTL，明文不入审计），**不代执行部署**。 - -> 旧的 `/deployment-targets`、`POST .../deployments`(executor:pending_worker)**已废弃，不再作为部署路径**。 - -## 8. 资源绑定（git/vm/db/blob → Key Vault） - -用户先把自己的资源绑定到 HM,凭据进 **Azure Key Vault**,库里只留 `secret_ref`;任务/部署只引用 `resource_binding_id`,**绝不传明文凭据**。详见 spec §4。 - -**5 种类型**:`git`(github/gitea,用 `provider` 区分,即用户**自己的仓库** URL + PAT)、`vm`(ssh)、`database`、`blob`。git 仓库是产物归宿(agent 在此 commit/合并,客户端 clone/pull)。 - -**8.1 网页控制台接口（🟢 已用，`UserAuth` 会话鉴权）** - -Manager 网页控制台「资源绑定」页已在用： - -| 方法 | 路径 | 说明 | -|---|---|---| -| GET | `/api/resources/?status=active` | 列出已绑资源 | -| POST | `/api/resources/` | 建绑定(非密字段进 metadata,不含凭据) | -| POST | `/api/resources/{id}/secret` | 写凭据 → Key Vault,返回 `secret_ref` | -| DELETE | `/api/resources/{id}` | 解绑(吊销) | - -建绑定示例(github)： -```json -{ "name":"my-repo", "resource_type":"git", "provider":"github", - "external_id":"https://github.com/owner/repo", - "metadata":{ "repo_url":"https://github.com/owner/repo", "default_branch":"main", - "api_base":null, // gitea 自建需填 API 地址 - "mode":"existing", // greenfield | existing - "allowed_paths":["backend/","frontend/"], - "permission_scope":"repo:write" } } -``` -→ 再 `POST /{id}/secret {"data":{"token":"ghp_..."}}`（PAT 进 KV，库里只留 `secret_ref`）。 - -- **provider 由 `repo_url` 推断**：`github.com` → github API；其他 → gitea（需 `api_base`）。 -- **凭据有效性预检**：HM 在用前对 git binding 做一次 `GET repo` 预检；失效则标 `status=invalid`，建任务/部署时报 `RESOURCE_BINDING_INVALID`，提示用户**重新绑定**，不静默失败。 -- vm：`{resource_type:"vm",metadata:{host,port,user,auth:"ssh_key|password"}}`；database：`{engine,host,port,db}`；blob：`{account,container}`。secret 一律走 `/{id}/secret` 进 KV。 - -**8.2 客户端接口（🔴 待建，V2 设备签名）** - -桌面客户端不走会话 cookie，需要一套 **V2 设备签名**版资源接口（与任务接口同一套加密/签名，§1）： - -| 方法 | 路径 | 说明 | 状态 | -|---|---|---|---| -| GET | `/api/heicode/resources?type=git&status=active` | 列已绑资源 → 让用户/任务选 `resource_binding_id` | 🔴 | -| GET | `/api/heicode/resources/{id}` | 单条详情（非密元数据 + status） | 🔴 | -| POST | `/api/heicode/resources` + `/{id}/secret` | 客户端内直接绑定（经 V2 加密传凭据） | 🔴 | -| DELETE | `/api/heicode/resources/{id}` | 解绑 | 🔴 | -| POST | `/api/heicode/resources/{id}/lease` | 取**短期凭据租约**（部署用，见 §7） | 🔴 | - -> 这两层（网页 8.1 / 客户端 8.2）操作的是**同一份绑定数据**，只是鉴权方式不同。8.2 上线后客户端即可"列绑定 → 建任务时引用 → 部署时取租约"全闭环。**当前客户端可先用 8.1 的会话路径联调**，待 8.2 就绪切换。 - -## 9. Runtime 回调（仅 Runtime 用，客户端无需关心） - -agent_management → HM 统一回调：`POST /api/agent/callbacks/runtime-events`。 -Schema 查询：`GET /api/agent/callbacks/runtime-events/schema`。 - -## 10. 客户端生产约束 - -- 审批 approve/reject 必须调 HM，禁止本地伪造。 -- 生产包禁用 mock 任务/审批/产物。 -- 用 HM 的 `display_status` 判**进度/有无产物**;**代码对错客户端自己跑/测 + 用户 review**(见 §4)。 -- 部署只在**用户确认后由客户端本地执行**;凭据凭 `resource_binding_id` 向 HM 取(§7),**不本地存明文凭据**。 -- 普通用户文案不出现 `newapi`、上游厂商、模型网关字眼。 -- 任务接口认证：写请求用 V2 加密 body + 设备签名，GET 用 V2 无 body 设备签名（见 §1），均复用模型调用同一套实现；base_url 来自 preset。 - -## 11. 错误码（新增） - -| code | 场景 | retryable | -|---|---|---| -| `SUB_GIT_BINDING_REQUIRED` 🔴 | sub 建任务未带（或失效的）`resource_bindings.git`——强制绑 git（§3.1） | false | -| `RESOURCE_BINDING_INVALID` | `resource_binding_id` 不存在/非本人/预检失效（提示重新绑定，§8.1） | false | -| `LEASE_EXPIRED` 🔴 | 凭据租约已过期（重新取，§7） | true | -| `LEASE_REVOKED` 🔴 | 租约已被吊销/binding 已删 | false | -| `APPROVAL_REQUIRED` 🔴 | 高危部署需先过审批（`waiting_approval`，§3.2/§7） | false | -| `BUDGET_EXCEEDED` 🔴 | 任务超 token/时长/成本上限，已暂停待用户决定（spec §9.3） | false | -| `DEPLOY_TARGET_DISABLED` | 目标未启用 | false | -| ~~`ARTIFACT_REVISION_CONFLICT`~~ / ~~`ARTIFACT_ARCHIVE_NOT_READY`~~ / ~~`ARTIFACT_ARCHIVE_FAILED`~~ / ~~`FILE_NOT_FOUND`~~ / ~~`FILE_PATH_REQUIRED`~~ | **遗留**（local-edits/archive/files 已退役，见 §5.4/§6） | — | - -其余错误码沿用旧文档 §13。所有错误统一形如 `{"success":false,"error":{"code","message","retryable"}}`，可读 `error.retryable` 决定是否重试。 - -## 12. 完整接口清单（按流程，覆盖核查） - -> 以**真实路由**为准（`router/api-router.go`）。`sub-agile` 路径把前缀换 `swarm` 即同形。状态：🟢 已实现 / 🟡 部分 / 🔴 待建。 - -**① 启动与就绪（§2）** - -| 接口 | 状态 | 章节 | -|---|---|---| -| `GET /api/heicode/capabilities` | 🟢 | §2 | -| `GET /api/user/self`、`/self/groups`、`/self/models` | 🟢 | §2.2 | -| sub 可用性组合判断（客户端本地） | 🟡 | §2.1 | -| 设备绑定 / 登录（`/api/heicode-auth/*`、`/api/user/...`） | 🟢 | 见 heicode-auth 文档 | - -**② 建任务与对话（§3）** - -| 接口 | 状态 | -|---|---| -| `POST /api/heicode/sub-agile/tasks`（需求包，含 resource_bindings、X-Idempotency-Key） | 🟢 建任务 / 🔴 强制 git 校验 + 幂等 | -| `GET .../tasks`、`GET .../tasks/{id}` | 🟢 | -| `POST .../tasks/{id}/messages`、`.../execute` | 🟢 | -| `POST .../tasks/{id}/stop`、`DELETE .../tasks/{id}` | 🟢 | - -**③ 运行监控 / work 视图（§4）** - -| 接口 | 状态 | -|---|---| -| `GET .../tasks/{id}/workflow`（含 git_ref、per-agent 富字段） | 🟢 本体 / 🔴 git_ref + per-agent 字段 | -| `GET .../tasks/{id}/logs`、`/timeline`、`/events`、`/metrics`、`/diagnostics`、`/sk-snapshots` | 🟢 | -| `GET .../tasks/{id}/events/stream`（SSE） | 🔴 §4b | - -**④ 审批（§3.2）** - -| 接口 | 状态 | -|---|---| -| `GET .../tasks/{id}/approvals?status=pending` | 🟢 | -| `POST .../approvals/{approval_id}/approve`、`/reject` | 🟢 | - -**⑤ 产物（§5）** - -| 接口 | 状态 | -|---|---| -| `git_ref`（在 workflow/详情里）→ 客户端 `git clone/pull` | 🔴 | -| `GET .../tasks/{id}/artifacts`、`.../artifacts/{aid}/content`（仅非代码运行信息） | 🟢 | -| ~~`.../artifacts/{aid}/{manifest,files,archive,revisions,local-edits}`~~ | 退役（§5.4） | - -**⑥ 修改 / 重做（§6）**：复用 ②的 `messages`/`execute`（+ 将来 `/redo` 🔴）；本地改走 git。 - -**⑦ 部署（§7）** - -| 接口 | 状态 | -|---|---| -| `POST /api/heicode/resources/{id}/lease`（短期凭据租约） | 🔴 | -| `DELETE /api/heicode/resources/leases/{lease_id}`（吊销） | 🔴 | -| ~~`GET /api/heicode/deployment-targets`、`POST/GET .../tasks/{id}/deployments`~~ | 废弃（旧代部署） | - -**⑧ 资源绑定（§8）** - -| 接口 | 状态 | -|---|---| -| `GET/POST /api/resources/`、`POST /{id}/secret`、`PUT/DELETE /{id}`（会话鉴权，网页台） | 🟢 §8.1 | -| `GET/POST/DELETE /api/heicode/resources*`、`/{id}/lease`（V2 设备签名，客户端） | 🔴 §8.2 | - -> 凡标 🔴 的，客户端**按本文契约预埋字段**即可；HM 侧补齐后无需改协议直接对齐。本清单即"整个流程要用到的接口"的核查表——发现遗漏请回填本表对应分组。 diff --git a/docs/integration/heicode-hm-template-agent-model.md b/docs/integration/heicode-hm-template-agent-model.md index 22c34456..3e703b5c 100644 --- a/docs/integration/heicode-hm-template-agent-model.md +++ b/docs/integration/heicode-hm-template-agent-model.md @@ -2,7 +2,7 @@ > 更新时间：2026-06-03 > 范围：**HM 端**（后端 + 网页控制台）在「模板 agent + 客户端直连」新模型下的改造清单。 -> 关联文档：`heicode-sub-mode-flow-spec.md`、`heicode-desktop-unified-api.md`（这两份的旧「sub 任务编排」内容将按本文裁剪）。 +> 关联文档：客户端对接见 `heicode-desktop-client-api.md`；旧代码清理见 `heicode-hm-legacy-teardown.md`。（旧的「sub 任务编排」设计文档 heicode-sub-mode-flow-spec.md / heicode-desktop-unified-api.md 等已删除。） --- diff --git a/docs/integration/heicode-sub-mode-flow-spec.md b/docs/integration/heicode-sub-mode-flow-spec.md deleted file mode 100644 index 0fd6a164..00000000 --- a/docs/integration/heicode-sub-mode-flow-spec.md +++ /dev/null @@ -1,487 +0,0 @@ -# Heicode Sub 模式 端到端流程与三端规范（v0.1 草案） - -> **2026-06-03 产物模型钉死（最重要的认知）**： -> - **sub 模式强制绑定 git** 才能用（未绑 git 只能走客户端本地模式，进不了 sub）。 -> - **最终产物只存在于用户自己的 git 仓库**。**没有"下载产物"这回事**——不存在 `project_folder` / `manifest` / `files` / `archive` zip / `local-edits` 回传这一整套（已全部退役）。要代码就 `git clone/pull`。 -> - **运行期间 HM 流式给客户端的，只有"运行信息"**：日志（user_logs/debug_logs）、状态（display_status + 三层状态）、work 视图杂项（每个 agent 在做什么、跑了什么工具、改了哪些文件、阶段进度、测试输出等）。这些是**给人看的过程信息，不是可下载交付物**。 -> - HM 眼里的 "artifact" 退化成**交付/完成记录**（带 `git_ref`、改了哪些文件、`source_agent_role` 等元数据），仅用于 ① `display_status` 的"有无真交付"防空壳核对、② 在 work 视图里展示；**客户端不从 HM 下载任何产物文件**。 -> -> 更新时间：2026-06-03（产物模型对齐）/ 2026-06-02（初稿） -> 范围：**Sub（普通子代理协作）模式**——桌面客户端（一个像 Claude Code 的智能体程序）把一个**多 agent 重活外包到云端 agent_management**：客户端发起 → 经 Heicode Manager（模型网关 + 控制面）→ agent_management 多 agent 并行执行 → 流式回客户端展示的**完整闭环**，含资源绑定、git 仓库、产物合并、修改/重做、部署。 -> 前提认知（**务必先读 §0**）：客户端本身能本地跑 agent；**sub 模式是把大任务派到云端,不是客户端唯一的干活方式**；**模型统一由 HM 的 `/v1/*` 提供给客户端和 AM 两边**。 -> 目的：**统筹三端（桌面客户端 / Heicode Manager / agent_management）的颗粒度与理解**，作为三方共同对齐的权威流程文档与契约规范。 -> 性质：本文是**目标设计** + **现状标注**。每节用标记区分： -> - 🟢 **已实现**（当前代码/线上已具备） -> - 🟡 **部分实现**（有基础，缺字段/流式/打通） -> - 🔴 **待建**（目标态，尚未实现） -> - ❓ **待决策**（需产品/三端确认的设计点，附我的建议） - -相关文档：客户端对接接口见 [`heicode-desktop-unified-api.md`](./heicode-desktop-unified-api.md)；runtime 契约见 agent_management《Sub Mode Runtime 对接指南》。 - ---- - -## 0. 术语与三端角色（先把名字钉死，避免歧义） - -> ⚠️ **名字钉死**：本文用 **HM** = Heicode Manager（那个 Go 网关），用 **AM** = agent_management（就是你口中的「Agent Manager / Sub Mode Runtime」）。两者**完全是两个不同的服务**，本文不再用模糊的「Manager」一词。三方按下表对号入座。 - -| 简称 | 全名 | 是什么 | 栈 | -|---|---|---|---| -| **客户端** | 桌面客户端 cc-haha / Desktop | **像 Claude Code 那样的智能体编程程序**:本地自己能跑 agent、写代码、执行命令。用模型时**调 HM 的模型接口** | TS（Tauri+React/CLI） | -| **HM** | **Heicode Manager** | **① 模型调用网关（new-api）**——给「客户端」和「AM」**两边都提供模型调用接口 `/v1/*`**（鉴权/计费/路由都在这）；**② 控制面 / 状态裁判 / 凭据中介**。HM 自己不跑 agent、不执行命令、不连 VM | Go(Gin/GORM) | -| **AM** | **agent_management**（= 你说的 Agent Manager / Sub Mode Runtime,在 `20.212.121.126`） | **云端多 agent 运行时**:把任务拆成多 agent 并行干活、写代码、git 入库；这些 agent **也是调 HM 的模型接口 `/v1/*`** 来用模型 | 独立服务 | - -> **「AI」从哪来**：AI = 模型。**模型统一由 HM 的 `/v1/*` 提供**。**智能体执行（跑 agent）发生在两处**：本地（桌面客户端,像 Claude Code）和云端（AM,sub 模式多 agent）。两边都**通过 HM 调模型**。HM 是大家共用的**模型网关**,自己不当 agent。 - -### 0.1 关键能力边界（谁跑 agent / 谁提供模型 / 谁执行命令） - -| 能力 | 客户端 | **HM** | **AM** | -|---|---|---|---| -| 智能体程序 / 跑 agent | ✅ 本地跑（像 Claude Code） | ❌ 不跑 agent | ✅ 云端跑多 agent | -| **提供模型调用接口 `/v1/*`** | ❌（是调用方） | ✅ **是模型网关,给客户端和 AM 都提供** | ❌（是调用方） | -| 调模型 | ✅ 调 HM `/v1/*` | —（被调方） | ✅ 调 HM `/v1/*` | -| 本地执行命令 / 部署 / 看 VM 日志 | ✅ 在用户机器上执行（像 Claude Code） | **❌ 从不执行、不连 VM** | ❌（AM 在自己沙箱产代码,不部署用户 VM） | -| 解密验签 / 鉴权 / 计费 | ❌ | ✅ | ❌ | -| 裁决 display_status | ❌ | ✅ **唯一裁判** | ❌（只报执行事实） | -| 托管凭据（KV）/ 发短期凭据 | ❌ | ✅ | ❌ | - -> **澄清几个之前易错的点**： -> - **HM 不部署、不执行命令、不连 VM、不看 VM 日志**——它是模型网关 + 控制面,不是执行器。 -> - **部署到用户 VM + 在 VM 看日志 = 客户端**自己在用户机器上干（像 Claude Code 本地执行；用户确认后 HM 只把短期凭据加密发给客户端）。 -> - **sub 模式 = 把多 agent 任务派到云端 AM 跑**（区别于客户端本地自己跑一个小任务）；AM 的 agent 调 HM 用模型,流式回 HM,HM 裁决后回客户端。 - -### 0.2 sub 模式是什么、什么时候用（既然客户端本地就能跑 agent） - -> 关键澄清：客户端本身能在**本地**跑智能体（像 Claude Code）完成小/快任务。那为什么还要 sub？ - -- **本地模式**（客户端自己）：在用户机器上跑单个/轻量 agent，适合小改动、即时、交互式。**计算在用户机器上**。 -- **sub 模式**（本文主题）：客户端把一个**更大的、需要多 agent 并行协作、或希望云端异步跑（关掉电脑也继续）**的任务，**派发到云端 AM** 执行。**计算在云端 AM**，多 agent 并行（backend/frontend/reviewer 同时干）。 -- **两种模式的模型都走 HM `/v1/*`**，鉴权 + 计费统一在 HM。 -- **sub 模式下客户端的角色** = **发起任务 + 实时看 work + 本地看/改产物 + 本地执行部署**；真正的 codegen 多 agent 在云端 AM。客户端不在 sub 模式里本地跑 codegen agent（那是本地模式）。 - -> 一句话：**sub = 把多 agent 重活外包到云端 AM；客户端当指挥台 + 取货 + 本地部署。本地模式 = 客户端自己干小活。模型两边都问 HM 要。** - -### 0.3 三端铁律 -1. 客户端**任务/控制走 HM**（`/api/heicode/*`、`/api/agent/*`），模型走 HM（`/v1/*`），**禁止直连 AM** / Runtime artifact。 -2. **HM 是唯一状态裁判**，客户端只消费 `display_status`（定义见 §6）。 -3. 凭据只进 **Azure Key Vault**，全链路只传/存 `secret_ref`，明文绝不落库/日志/回调。 -4. **HM 不执行任何命令、不部署、不连 VM、不跑 agent**；agent 执行在云端 AM（sub 任务期）或客户端本地（本地模式 / 部署期）。模型由 HM 提供给两边。 - ---- - -## 1. 端到端总体流程（时序） - -```text -┌── 桌面客户端 ──┐ ┌──── Heicode Manager ────┐ ┌── agent_management ──┐ -│ │ │ │ │ │ -│ 0 选 sub 模式 │ │ │ │ │ -│ 0.5 (可选)绑 git/vm/db ─┼─► 资源绑定→Key Vault │ │ │ -│ │ V2加密 │ 存 secret_ref │ │ │ -│ 1 填需求包 ────┼───────►│ 2 解密+验签+鉴权+配额 │ │ │ -│ │ │ 3 需求包→orchestration ├──────► │ 4 拆分多 agent │ -│ │ │ _plan + 注入资源授权 │ HMAC │ 分配角色/模型 │ -│ │ │ │ │ 5 各 agent 干活： │ -│ │ │ │ ◄──────┤ 流式回调状态/日志/ │ -│ 7 轮询/订阅 ◄──┼────────┤ 6 收敛三层状态+运行信息 │ callback│ 状态/日志/work + │ -│ 展示 work(只有 │ │ 裁决 display_status │ │ git 入库 + push │ -│ 日志/状态/work)│ │ (只转发运行信息) │ │ 8 各 agent 代码→分支 │ -│ │ │ │ │ 9 合并→交付分支(git) │ -│ 10 看产物 ─────┼──git──► (直接 git clone/pull 用户 │ ◄──────┤ push 用户仓库 + │ -│ 只走 git │ 自己的仓库; 不经 HM) │ git_ref │ 回调 git_ref 通知 HM │ -│ 11 不满意 ─────┼───────►│ /messages | /execute ├──────► │ 12 修改/重做(git) │ -│ │ │ │ │ │ -│ 13 本地 git │ ◄─git── (pull/改/push, 不经 HM) │ │ │ -│ 14 部署 VM ────┼───────►│ 取凭据(加密) → 客户端执行│ │ │ -└────────────────┘ └──────────────────────────┘ └──────────────────────┘ -``` - ---- - -## 2. 三端颗粒度契约（一图看清谁给谁什么） - -> 表头里 **HM = Heicode Manager**，**AM = agent_management**。 - -| 数据/动作 | 客户端 → **HM** | **HM → AM** | **AM → HM**（回调） | **HM → 客户端** | -|---|---|---|---|---| -| 建任务 | 需求包（objective/context/约束/验收/模型选择/角色） | orchestration_plan + 资源授权 grants | deployment_id/swarm_id | deployment_id(=task_id) + display_status | -| 运行状态 | — | — | `status`+`runtime_execution_status`+`phase` | **`display_status`**（裁决后） | -| 日志/work | — | — | 事件流（task./agent./phase./handoff./artifact.） | `user_logs`+`debug_logs` / work 视图（**只有运行信息**） | -| 每 agent 指标 | — | — | 🔴 per-agent tokens/tools/elapsed | workflow.agents[].* | -| 代码产物 | — | — | **git push + 回调 `git_ref`**（commit/分支/改了哪些文件 + `source_agent_role`，仅元数据） | **git_ref（让客户端去 git pull）**——HM 不提供产物文件下载 | -| 修改/重做 | message / execute | 续跑/重做指令 | 新 commit + git_ref + 状态 | 新 display_status + 新 git_ref | -| 凭据 | 只传 `resource_binding_id` | 注入 `secret_ref`（azkv://） | — | 只回 secret_ref（打码） | - -> ⚠️ **上表只画了「任务控制面」。还有一条独立的并行通道——模型调用：** -> - **客户端 → HM `/v1/*`**（客户端本地 agent 用模型） -> - **AM → HM `/v1/*`**（AM 的 agent 用模型） -> 两边用**同一套模型接口**,HM 统一做鉴权 + 计费 + 路由。模型调用与上面的任务控制面是**两条不同的通道**,别混在一起。 - ---- - -## 3. 阶段详解 - -### 3.0 完整执行流程（逐步，明确每一步谁做什么） - -> 全程三个主体：**客户端**（像 Claude Code 的智能体程序）、**HM**（模型网关 + 控制面，不跑 agent、不执行命令）、**AM**（云端多 agent 运行时）。**客户端和 AM 的 agent 用模型时都调 HM 的 `/v1/*`。** - -**A. 准备（一次性）** -1. 用户在**客户端**绑定自己的 **git 仓库**（github/gitea URL + 一个 PAT）。客户端经 V2 加密把 PAT 发给 **HM** → **HM** 把 PAT 写进 **Key Vault**，库里只留 `secret_ref`，返回一个 `resource_binding_id`。 -2. （需要部署时）同样绑定 **VM**（host + ssh key）、数据库、blob，凭据进 KV，各得一个 `resource_binding_id`。 - -**B. 发起任务** -3. 用户在**客户端**选 `sub` 模式、填**需求包**（目标/约束/验收/角色/模型/要用哪条 `resource_binding_id`）。 -4. **客户端** → `POST /api/heicode/sub-agile/tasks`（V2 加密 body + 设备签名）。 -5. **HM**：解密 → 验签 → 鉴权 → 查配额 → 把需求包译成 `orchestration_plan`，**从 KV 取出 git 凭据注入**（短期 token），落库，返回 `deployment_id`（= task_id）。**HM 不写代码、不跑 agent。** - -**C. 执行（AM 干活，HM 中转）** -6. **HM** → `POST /api/agent/sub-agile/deployments`（给 **AM**），带：需求、角色/模型、回调地址、HMAC 签名密钥、**git 仓库 + 短期凭据**。 -7. **AM**：把需求拆成多个 **agent**（如 backend / frontend / reviewer），各自分配模型，开始干活。**每个 agent 用模型时调 HM 的 `/v1/*`（和桌面客户端用同一套模型接口）。** -8. **AM** 的每个 agent：clone 用户仓库 → 在自己分支（`agent/`）写代码、跑工具/测试（调 HM `/v1/*` 用模型）→ **commit & push 到用户仓库**（用第 5/6 步注入的短期 PAT）。 -9. **AM** 持续把「每个 agent 在做什么 / 跑了什么工具 / 改了哪些文件 / 当前阶段 / 产物」**流式回调**给 **HM**（HMAC 签名）：`POST /api/agent/callbacks/runtime-events`。 -10. **HM** 收回调 → 聚合事件 + **裁决 `display_status`**（见 §6）+ 持久化。 - -**D. 客户端看 work** -11. **客户端**轮询 `GET .../tasks/{id}/workflow`（运行中 3–5s；将来 SSE）→ 拿 `display_status` + 各 agent 状态/动作 + 阶段 + 产物列表，渲染成「work 视图」（参考 Claude Code）。 - -**E. 合并与产物** -12. **AM** 阶段结束 → 把各 agent 分支**合并**成一个交付分支（`delivery/` 或 PR）→ push 到用户仓库 → 回调通知 **HM** 产物就绪（带 `git_ref` + artifact）。 -13. **客户端**看产物：直接 `git clone/pull` 用户自己的仓库（完整工程 + 历史 + diff）。**只此一条路**——产物在 git，HM 不托管/不打包/不提供产物文件下载；HM 给的只是 `git_ref`（告诉客户端去哪个仓库/分支/commit pull）。 - -**F. 不满意 → 改 / 重做** -14. **客户端** → `POST .../messages`（追加要求）或 `.../execute`（重跑）→ **HM** 取最新 accepted 基线转给 **AM** → **AM** 在原产物上改/重做 → 回到第 9 步。 - -**G. 部署（客户端执行 + 用户确认；HM 只发凭据）** -15. **客户端**发起部署 → **弹窗让用户确认**（目标 VM / 环境 / 用哪条 binding / 影响）。 -16. 用户确认 → **客户端**向 **HM** 换**短期凭据租约**（HM 从 KV 解出 VM ssh key，经 V2 加密发回客户端，带 TTL）。 -17. **客户端在用户自己机器上执行**部署：`git pull` 用户仓库 → ssh 到 VM → 跑部署命令 → **在 VM 上看日志**。**HM 全程不碰 VM、不执行命令、不看日志**；**HM 只记审计**（谁、哪条 binding、何时、TTL）。 - -> 一句话区分执行位:**写代码 = AM 沙箱里执行;部署到用户 VM + 看 VM 日志 = 客户端在用户机器上执行;HM 永远只做网关/裁判/凭据中介,不执行任何东西。** - ---- - -### 3.1 选择 sub + 准备（资源绑定前置） - -🟢 客户端选 `mode=sub_agile`（区别于 `swarm`）。 -✅ **决策（2026-06-02）**：**git 仓库 = 用户绑定自己的仓库**（gitea / github，用户提供 URL）。**没有 Heicode 托管仓库**。 -✅ **决策（2026-06-03）**：**sub 模式强制绑定 git**——未绑仓库则**不能进 sub**（UI 上禁用 sub，引导用户先绑 git 或改用客户端本地模式）。**不再有"未绑仓库走仅产物轻量路径"这种东西**（`project_folder`/manifest/files/archive 已退役）。代码产物的唯一归宿就是用户绑定的 git 仓库（§4.1）：agent 在此入库/合并，客户端 `git clone/pull` 看产物。 - -### 3.2 客户端 → HM（加密 + 鉴权 + 建任务） - -🟢 **加密链路**：与模型调用完全一致。 -- 写请求（POST/PUT/DELETE）：`Content-Encoding: heicode-aead-v1`，X25519-ECDH + HKDF + ChaCha20-Poly1305 加密 body，Ed25519 设备签名（`X-Heicode-*`）。 -- GET：无 body 设备签名（同 canonical，body 哈希为空串哈希）。 -- HM 中间件 `UserOrV2DeviceAuth` 解密 + 验签 + 从设备绑定 token 解析用户身份。 - -🟢 **鉴权/配额**：解析 user_id、绑定 scope、计费上下文。 -🟢 **建任务**：`POST /api/heicode/sub-agile/tasks`，body = **需求包**（见客户端接口文档 §3.1），HM 译成 `orchestration_plan` 并落库，返回 `deployment_id`（= task_id）。 - -### 3.3 HM → agent_management（分发） - -🟢 `POST /api/agent/sub-agile/deployments`（env 当前指向 `http://20.212.121.126`），Bearer service token。 -🟢 注入：callback URL（`/api/agent/callbacks/runtime-events`）+ HMAC 签名密钥引用 + metadata.manager_deployment_id + 角色/模型 + **资源授权 grants（secret_ref，不含明文）**。 -🟡 **回调竞态**：AM 回调可能早于 HM 存 runtime_id → HM 用「读时收敛」(`reconcileDeploymentFromRuntime`) 兜底（已实现）。 - -### 3.4 多 agent 执行 + 流式回传（work 视图，参考 Claude Code） - -🟡 **现状**：AM 通过回调上报 `deployment.status_changed / task.* / handoff.* / artifact.created / phase.changed` 等事件；HM 聚合成 timeline/events/logs；客户端**轮询**展示。 -🔴 **目标（work 视图）**：像 Claude Code 的 work 面板那样**实时流式**展示「每个 agent 正在做什么、跑了哪些工具、产了哪些文件、各阶段进度」。需要补： - -1. 🔴 **流式协议**：HM 提供 `GET .../tasks/{id}/events/stream`（SSE）或 WS，把 AM 回调实时转发给客户端。**现状无 SSE**，客户端轮询 `/workflow`（3–5s）兜底（见 §5）。 -2. 🔴 **per-agent 富字段**：AM 在状态/回调里上报每个 agent 的 `tokens / tools(工具调用数) / elapsed_seconds / 当前动作描述 / artifact_ids`。HM 的 `/workflow` 已预留这些字段（缺值时为 0/空），等 AM 填。 -3. 🔴 **artifact 来源角色**：AM 给 artifact 打 `source_agent_role`，HM 才能把产物准确归到对应 agent。 -4. 🔴 **阶段细分**：runtime 上报 `phases[]`（每阶段 status/agents），而非单个 `phase` 字符串。 - -> work 视图的最小可用版（不等 SSE）：客户端轮询 `/workflow` 拿 `agents[] + phases[] + metrics`，3–5s 刷新即可先跑起来；SSE 是体验升级项。 - -### 3.5 代码入 git + 多 agent 产物合并 - -🔴 **目标**：每个 agent 把自己产的代码 **commit 到 git 仓库的独立分支**（如 `agent/backend`、`agent/frontend`），最后 **合并成一个完整产物**（merge 到 `main` 或一个交付分支）。 - -❓ **关键决策（§7 详述）**： -- 仓库在哪？（Heicode 托管 vs 用户绑定的 git） -- 谁负责合并？（agent_management 合并后给一个最终分支/commit；HM 不碰 git 操作，只记录引用） -- 合并策略？（按目录隔离自然无冲突：backend/ + frontend/ 并列；同文件冲突由一个「集成 agent」或规则解决） - -🟡 **现状**：sub 模式 AM 当前还是把产物当 blob/文本 artifact 回传（每角色一个，多角色=多个），**尚未真正 git 入库 + 合并**——这是**待迁移的旧实现**，不是目标态。目标态（本节）是 AM 全程在用户 git 仓库里 commit/合并，产物只在 git。客户端不再"拼 manifest 展示产物"。 - -### 3.6 产物查看（只走 git） - -🔴 **唯一路径 = git**：sub 完成后客户端直接 `git clone/pull` 用户自己绑定的仓库，看完整工程 + 提交历史 + diff。HM 给的只是 `git_ref`（repo/branch/commit），告诉客户端去哪 pull。 - -> **退役**：旧的「经 HM 看产物」（`/artifacts`→`/manifest`→`/files?path=`→`/archive`）是无 git 流程的残留，**sub 强制 git 后不再使用**。HM 在运行期只向客户端流式推**运行信息**（日志/状态/work，见 §5），**不提供产物文件的浏览或下载**。HM 的 `/artifacts` 接口若保留，只列**非代码的运行信息记录**（如 `test_report` 测试报告、摘要），供 work 视图展示，**不是可下载交付物**。 - -### 3.7 不满意 → 修改 / 重做（**两条路：云端改 或 本地改**） - -> 因为客户端本身是智能体程序（像 Claude Code），迭代有**两条等价路径**,用户按场景选： - -> **基线就是 git**：两条路都以**用户仓库的最新提交**为唯一基线，不存在 HM 侧的 `local-edits`/revision 回传机制（已退役）。本地改完 `git push`，云端续跑前 `git pull`，冲突/历史/diff 全交给 git。 - -**路径 A — 回云端 AM 改（继续 sub）** -- 🟡 **修改（续跑）**：`POST .../tasks/{id}/messages`（追加要求）→ HM 转给 AM → AM 先 `git pull` 取用户仓库最新提交作基线 → 在其上改 → 再 push。（AM 真正「中途续跑」🔴待支持） -- 🔴 **重做**：`POST .../tasks/{id}/execute`（或新增 `/redo`）→ AM 在新分支上重新生成（旧交付分支保留可对比）。需 AM 支持「redo」语义。 - -**路径 B — 拉到本地用客户端自己的 agent 改（回到本地模式）** -- 🟢/🔴 客户端 `git pull` 用户仓库 → 用**客户端本地 agent**（像 Claude Code，模型仍走 HM `/v1/*`）在本地改 → `git push` 回仓库。**不必每次回云端**，适合小修小补。 -- 改完想让云端接力：直接 push 后再 `/messages`，AM `git pull` 自然拿到本地改动——**无需任何 HM 回传接口**。 - -### 3.8 部署（✅ 必须客户端执行 + 必须用户确认） - -✅ **决策（2026-06-02）**：**部署绝对走客户端,且必须用户显式确认才执行**。HM 不自动部署、AM 不自动部署。 -- 流程：客户端发起部署 → **弹用户确认**(目标/环境/影响) → 用户确认 → 客户端向 HM 的**加密密钥接口**换取**短期凭据租约**(VM SSH key / git PAT 等从 KV 解出,经 V2 加密通道回客户端,带 TTL) → **客户端本地执行**(git pull 用户仓库 → push/部署到 VM,或连库迁移)。 -- HM 角色:**只发短期凭据 + 记审计**(谁、哪条 binding、何时、TTL),不代执行。 -- 凭据租约:短 TTL、可吊销、用完即弃;高危目标(如生产)可叠加**审批门**(waiting_approval)后再发租约。 -🟡 **现状**:有云部署控制面占位(`/deployments`,返回 `executor:pending_worker`);凭据租约模型(approval→lease)有骨架。🔴 待建:客户端取凭据的加密接口 + 客户端本地执行器。 - ---- - -## 4. 资源绑定规范（git / vm / database / blob → Key Vault） - -> 🔴 **前置硬卡点**：Azure Key Vault 当前**托管身份取 token 400、不可达**。资源绑定的核心是「凭据进 KV、只存 secret_ref」，**KV 不通则整个功能不可用**。必须先由运维给 VM 托管身份在目标 KV 授 `Key Vault Secrets Officer` 角色（Phase 0）。 - -### 4.0 通用模型 - -每个资源绑定 = `{ resource_binding_id, type, name, metadata(非敏感), secret_ref(azkv://…), permission_scope, binding_scope(租户/工作区), status }`。 -- 客户端**只传 `resource_binding_id`** 给任务；HM 内部解析为凭据注入 AM。 -- 客户端**禁止 inline** secret_ref / AccessKey / 连接串。 -- 凭据录入**一次性**：客户端经 V2 加密通道把凭据传给 HM → HM 写 KV → 库里只留 `azkv://`。 - -### 4.1 Git 仓库绑定 ✅（已定方向） - -**模型**：**用户绑定自己的仓库**（gitea / github，用户提供 URL）。agent 在此仓库读写代码、git 入库、合并；客户端 clone/pull 看产物；后续从此仓库 git 到 VM 部署。 - -| 项 | 方案（已定 / 建议） | -|---|---| -| **仓库归属** | ✅ **用户自己的仓库**。用户提供 `repo_url`（github.com/... 或自建 gitea URL）。无 Heicode 托管仓库。 | -| **绑定鉴权（用户输入密钥）** | ✅ **HTTPS + 细粒度 PAT（个人访问令牌）为主**——github 与 gitea **通用**、用户只需粘贴一个 token、可按仓库范围授权、可随时吊销、不暴露账号密码。流程：用户在自己 git 生成范围化 PAT（建议 `repo` 读写）→ 客户端经 V2 加密通道把 PAT 传 HM → HM 写 KV，库里只留 `secret_ref`。**备选**：SSH deploy key（用户把 HM 出示的公钥加到仓库 Deploy keys；适合不愿发 PAT 的场景）。 | -| **provider 识别** | 由 `repo_url` 推断（github.com → github API；其他 → gitea，需带 `api_base`）。metadata：`provider / repo_url / default_branch / api_base?`。 | -| **绑定粒度** | 单仓库级（一个 binding = 一个 repo + 默认分支 + 允许路径 allowed_paths）。permission_scope：`repo:read` / `repo:write`。 | -| **凭据有效性/过期** | PAT 会过期/被吊销 → HM 在用前**预检**（一次 `GET repo`），失效则标记 binding `status=invalid` 并提示用户**重新绑定**，不静默失败。 | -| **工单 / 里程碑** | **可选增强**（默认关，用户显式开）：把 sub 子任务映射为 **issues**、阶段映射为 **milestone**、handoff/审批映射为 **issue 评论**，让用户在自己 git 看板跟踪 agent 进度。需要 PAT 额外授 issues 权限。 | -| **分支模型 / 合并** | 见 §7。 | - -### 4.2 VM 连接绑定 🔴 -`type=vm`，metadata：host/port/user/连接方式（ssh key / 密码）；secret 进 KV。用于部署/运维。高危,建议绑定时声明用途 + 部署需审批。 - -### 4.3 数据库绑定 🔴 -`type=database`，metadata：引擎/host/port/db 名；连接串/密码进 KV。用于 agent 生成需要连库的代码或迁移。 - -### 4.4 Blob 存储绑定 🔴 -`type=blob`，metadata：账号/容器；key/SAS 进 KV。用于大产物/数据集存取。 - -### 4.5 凭据生命周期 -- 录入 → KV（HM 写）→ 只存 secret_ref。 -- 使用 → 任务/部署时 HM 从 KV 解出注入 AM，或发**短期租约**（TTL + 可吊销）给客户端。 -- 审计 → 谁在什么 scope 用了哪条绑定、发了哪些租约、何时吊销（只记 secret_ref + 打码摘要）。 - ---- - -## 5. 流式协议规范（work 视图） - -| 阶段 | 协议 | 状态 | -|---|---|---| -| 现状 | 客户端轮询 `GET .../workflow`（运行中 3–5s、终态 15–30s） | 🟢 | -| 目标 | `GET .../tasks/{id}/events/stream`（SSE）：HM 把 AM 回调实时转发；事件含 `agent.action / tool.call / phase.changed / log.line / delivery.pushed`（产物就绪=带 `git_ref` 的通知，**不是文件**） | 🔴 | - -**规范**： -- SSE event 统一信封：`{ event_type, deployment_id, agent_id?, phase?, occurred_at, payload }`。 -- 客户端断线重连用 `Last-Event-ID`（基于 HM 的事件游标）。 -- **降级**：SSE 不可用时自动回落轮询，UI 行为一致（只是延迟）。 -- 客户端**不要**订阅不存在的流（未上线前 `/events/stream` 返回未实现，别硬连）。 - ---- - -## 6. 状态模型与 `display_status` 裁决（完整定义，给三方） - -🟢 已实现。**这是全文最关键的概念之一,三方必须一致理解。** - -### 6.1 HM 只做"事实透传 + 防空壳",**不判断代码对错** -- **AM 只上报执行事实**(`completed` 只代表"我跑完了")。 -- **HM 没 AI、不读代码、不跑代码、不编译、不测试。** 所以 **HM 不判断"代码对不对、有没有效"**——那不是 HM 能做、也不该做的事。 -- HM 的 `display_status` 只做两件事:**① 忠实透传 AM 的执行状态**;**② 防"空壳/兜底假成功"**——AM 说 `completed` 时,HM 顺手核对一下"**到底有没有产物**"(这是**事实层面**的核对:有/无、是不是兜底占位,**不是质量判断**)。 -- **真正"对不对、有没有效"由客户端 + 用户判断**(见 §6.6):客户端是 Claude-Code 式程序,**能把产物/git 拉下来自己跑、自己测、看 diff**,用户 review 拍板。 -- 客户端只看 `display_status` 决定**"这轮跑完了没、是不是空交付"**;**"代码好不好"客户端自己看产物。** - -### 6.2 三层状态（`GET .../tasks/{id}/workflow` 同时返回） -| 字段 | 含义 | 谁产生 | -|---|---|---| -| `cloud_deployment_status` | HM 控制面状态（accepted/running/stopped…） | HM | -| `runtime_execution_status` | **AM 上报的原始执行状态**（AM 说它自己到哪了） | AM | -| **`display_status`** | **HM 裁决后、给用户展示的唯一状态** | **HM** | - -### 6.3 `display_status` 的全部取值（枚举） -| 值 | 含义 | 客户端该怎么展示 | -|---|---|---| -| `accepted` | 已受理,排队中 | 进行中（灰/黄） | -| `running` | 正在执行 | 进行中（蓝，转圈） | -| `waiting_approval` | 等用户审批高风险操作 | 黄，弹审批 | -| `completed` | **完成,且有真实可交付的代码产物** | **绿,成功** | -| `needs_codegen` | AM 说完成了,但**只产了方案/总结、没有真实代码** → 需继续生成 | 黄,提示"需补充代码/继续" | -| `completed_without_deliverable` | AM 说完成了,但**完全没有产物** | 红/橙,**视为没成功** | -| `failed` | 执行失败 | 红,失败 | -| `stopped` | 被用户/系统停止 | 灰,已停止 | - -### 6.4 裁决算法（HM 收到 AM 状态后怎么算 `display_status`） -```text -输入: AM 的 runtime_status, 该任务的 artifacts 列表 -规则: - if runtime_status 不是 "completed": - display_status = runtime_status 原样透传 - (running / waiting_approval / failed / stopped / accepted ...) - else # AM 说 completed,进入"是否真有交付物"的裁决 - 遍历该任务的 artifacts: - 只要存在 1 个"真实交付物" → display_status = "completed" ✅ - 否则 if 有 artifacts 但全是总结/兜底 → display_status = "needs_codegen" - 否则 (一个 artifact 都没有) → display_status = "completed_without_deliverable" -``` -**"真实交付物"的判定**(逐条排除"假产物"):AM 回报的交付记录满足以下**才算真实**—— -- **目标态(git)**:回调带 **`git_ref`**(repo/branch/commit_sha)且有**真实提交**(commit 数 > 0 / 改了 N 个文件) → 真交付。HM 据此判"有没有真东西",**不下载、不读代码内容**。 -- `metadata.synthesized != true`(不是 AM 的兜底占位记录),**且** -- 不是纯总结类(标题/正文不含 "runtime execution summary"、"without per-agent artifacts" 等兜底标记;不是 `document`/`summary` 类)。 -- 兼容旧实现:在 AM 尚未 git 化前,带"改了 N 个文件"结构化信号的 `code_patch`/`diff` 记录也按真交付算(过渡期)。 - -> 注意:HM 判的是**"有没有真提交"这个事实**(防空壳),**不是判代码对不对**(§6.6)。`git_ref` 是元数据,不是可下载产物。 - -> 一句话:**`completed` 必须"AM 说完成 + 真的有代码产物"两个条件都满足;只有总结没代码 = `needs_codegen`;啥都没有 = `completed_without_deliverable`。客户端据此就能准确区分成败,不会被假成功骗到。** - -### 6.5 成功判据（客户端用） -> **`display_status == "completed"` 且 artifacts 非空 = 真成功**;其余都不是成功(各有不同处理)。 - -### 6.6 ⚠️ "对不对/有没有效"归谁判 —— **客户端 + 用户,不是 HM**（三方必读） - -| 谁 | 判什么 | 怎么判 | -|---|---|---| -| **HM** | 只判**事实**:这轮跑完没?有没有产物?是不是空壳/兜底? | 看 AM 状态 + artifact 有无（**不读代码、不编译、不测试、不判对错**） | -| **客户端**（Claude-Code 式） | 判**代码对不对、能不能跑、是不是要的** | **把产物/git 拉到本地,自己跑、自己测、看 diff**;有问题就本地改或回云端改 | -| **用户** | **终裁**:满不满意、收不收货 | 在客户端 review 产物,满意才算真完;不满意 → 改/重做（§3.7） | - -> **直接回答你的问题**: -> - **HM 不需要、也不该编译/测试/判断代码真伪**——那不合理。HM 是网关,没 AI。 -> - **完成后是对是错,客户端当然知道**:它是智能体程序,把代码拉下来一跑一测就清楚,用户也会 review。**这才是判"有效"的地方。** -> - HM 的 `display_status` 顶多帮客户端**省一步**:告诉它"这轮跑完了 / 是不是空交付",**避免把一个空壳当成功**;但**"代码好不好"绝不由 HM 判**。 - -**关于测试/编译**(纠正我之前的错误说法): -- 跑测试/编译是 **AM 在自己沙箱里做**(任务执行的一部分),或**客户端在本地做**。 -- 若 AM 跑了测试,**测试结果就是一个产物(`test_report` artifact)给客户端看**——**不是回传给 HM 去"裁决"**。HM 不参与对错判断。 - ---- - -## 7. Git 仓库与分支 / 合并模型 ❓ - -**目标流程**： -```text -任务开始 → 建/选仓库 → 拉基线分支 base -每个 agent → 自己分支 agent/ → 多次 commit（流式可见 diff） -阶段结束 → 集成：合并各 agent 分支 → 交付分支 delivery/（或 main） -完成 → 交付分支即「完整产物」；客户端 clone/pull 看；不满意 → 在交付分支上续跑/重做 -``` - -**决策点**： -| 点 | 方案（已定 / 建议） | -|---|---| -| 仓库归属 | ✅ **用户绑定的仓库**（github/gitea，用户给 URL）。无托管仓库。 | -| 谁执行 git | ✅ **agent_management 执行**所有 git 操作（clone 用户仓库、各 agent commit 到分支、合并到交付分支、push）——用 HM 注入的**短期 PAT**（从 KV 解出，最小权限）。HM **只记录引用**（repo_url/branch/commit_sha）并在 artifact metadata 带 `git_ref`，**不做 git**。 | -| 提交身份 | agent 提交用一个明确的 **bot 身份**（如 `heicode-agent `）+ commit message 带任务/agent/角色标注,便于用户在 git 历史里分辨人/机改动。 | -| 合并冲突 | 目录隔离（backend/、frontend/ 并列）天然无冲突；同文件冲突由「集成 agent」或规则化合并解决，无法自动解则上报 `needs_codegen` 让用户介入/再跑一轮。 | -| 写入方式 | ❓建议：agent **不直接 push 到用户的 `main`**,而是 push 到 `delivery/` 或开 **PR**,由用户在自己 git 上 review/merge → 既安全又复用用户的 PR/CI 工作流。是否强制 PR 模式待定。 | -| 客户端看产物 | **只走 git**：直接对用户自己的仓库 `git clone/pull`。HM 不提供 `/archive` 等产物下载（已退役）。 | - ---- - -## 8. 决策点（部分已定，2026-06-02） - -| # | 决策 | 结论 | -|---|---|---| -| 1 | git 归属 | ✅ **用户绑自己的仓库**(github/gitea,给 URL),无托管仓库 | -| 2 | git 鉴权 | ✅ **HTTPS + 细粒度 PAT 为主**(github/gitea 通用、用户粘贴 token)、SSH deploy key 备选 | -| 3 | 部署 | ✅ **必须客户端执行 + 必须用户确认**;HM 只发短期凭据 + 记审计 | -| 4 | git 执行方 | ✅ **agent_management 执行 git**(用注入的短期 PAT),HM 只记引用 | -| 5 | 工单/里程碑 | 可选增强,默认关 —— ❓ 是否纳入 v1? | -| 6 | 流式 | v1 先轮询 work、SSE 放 v1.1 —— ❓ 接受? | -| 7 | 写入方式 | ❓ agent 是 push 到 `delivery/` 分支 / 开 PR,还是直接进 main? 建议 PR/分支模式 | -| 8 | 未绑仓库 | ✅ **未绑 git 则禁用 sub**(强制绑 git)。不再有"仅产物"轻量路径;产物只在 git,无 project_folder/manifest/archive/local-edits | - ---- - -## 9. 更多需要考虑的细节（我补充的，超出已提问题） - -> 这些是我认为**必须在 v1 前定清**的边界/细节,大多附我的建议,标 ❓ 的需你拍板。 - -### 9.1 仓库与代码库状态 -- **空仓库 vs 已有代码**：agent 是在**已有代码库上增量改**,还是**绿地新建**? 建议 binding 时声明 `mode: greenfield | existing`;existing 时 agent 先读现有结构再改,且**只动 allowed_paths 内**的文件。 -- **多仓库任务**：一个任务是否可能跨多个仓库(前端仓 + 后端仓)? 建议 v1 **单仓库**,多仓库 v2。 -- **monorepo / 子目录**：用 `allowed_paths` 限定 agent 工作目录,避免动到无关代码。 -- **大文件 / LFS**：是否支持 git-lfs? v1 可不支持,但要**拒绝把大二进制/数据集塞进 git**(走 blob 绑定)。 -- **.gitignore + 防止误提交密钥**：agent **绝不能把任何凭据/secret_ref/.env 提交进仓库**;runtime 侧需有 secret 扫描,提交前拦截。 - -### 9.2 凭据与安全 -- **PAT 最小权限 + 短时效**：注入 AM 的 PAT 应尽量是**短期/单仓库范围**;若用户给的是长期 PAT,HM 至少做范围校验并提醒。 -- **凭据只在内存**：AM 用完 PAT 不落盘、不进日志;HM 注入走加密。 -- **scope 隔离**：一条 binding 的凭据**只能被该用户(binding_scope)的任务**使用,跨用户禁用。 -- **审计**：每次「解 KV、注入 AM、发客户端租约」都留审计(user / binding / 用途 / 时间 / TTL),明文不入审计。 -- **吊销**：用户删 binding 或吊销租约后,进行中的任务该如何? 建议:已注入的短期凭据自然过期,新操作立即失效。 - -### 9.3 任务执行与失败 -- **预算/配额**：每任务 token/时长/成本上限;**跑超预算**时如何? 建议:到上限**暂停 + 标 `needs_codegen`/`budget_exceeded`**,让用户决定续不续,不静默烧钱。 -- **中途停止(stop)**：停止时已 commit 的代码**保留在分支**(不回滚),任务标 stopped;用户可在该分支续跑或丢弃。 -- **agent 崩溃 / 部分失败**：多 agent 里某个失败 → 整体 `completed_without_deliverable`/部分交付? 建议:HM 裁决时若有 agent 失败但有有效产物,仍可 `completed` 但带 warning;全失败则 failed。 -- **幂等**：同一需求重复提交(网络重试)用 `X-Idempotency-Key` 去重,避免建重复任务/重复 git 分支。 -- **超时**：AM 长时间无回调 → HM 标 `stale`/超时,客户端可见。 - -### 9.4 产物与验收 -- **验收标准如何验证**：需求包里的 `acceptance_criteria` 谁来验? 建议:AM 跑测试(若有)并把**测试结果作为 `test_report` 产物给客户端**;**客户端 + 用户**据此判对错(**不经 HM 裁决**,§6.6)。 -- **产物版本/标签**：每次交付打 tag(`delivery--rev`)或记 commit_sha,便于回溯 + 部署指定版本。 -- **修改 vs 重做的边界**：`/messages`(在现有产物上改)与 `/redo`(重新生成)语义要清晰;redo 是否丢弃旧分支? 建议:redo 开新分支,旧的保留可对比。 - -### 9.5 协作与团队 -- **谁能看/操作一个任务**：binding_scope = 租户/工作区;同 scope 内成员可见,跨 scope 禁。 -- **并发任务同仓库**：两个任务同时改一个 repo → 用不同 `delivery/` 分支隔离,合并到 main 时各自 PR,冲突由用户处理。 - -### 9.6 git provider 细节 -- **rate limit**：github/gitea API 有限流,频繁 commit/查询要退避,避免触发封禁。 -- **私有 / 公开仓库**：都支持;私有仓库凭 PAT 访问。 -- **网络可达**：runtime 要能访问用户的 git(公网 github 没问题;自建 gitea 若在内网,需用户提供可达地址或白名单)。 -- **webhook 回写(可选)**：若用户在自己仓库手动改了代码,是否要 webhook 通知 HM 同步基线? v2 考虑。 - -### 9.7 部署细节(客户端执行 + 用户确认) -- **确认内容**：弹窗要清楚展示**部署目标、环境(prod/staging)、用哪条 binding、影响范围**,用户确认后才发凭据。 -- **目标多样性**：v1 先支持 **VM(SSH)**;k8s/serverless v2。 -- **回滚**：部署失败/效果不好 → 客户端能回滚到上一个交付 tag。 -- **租约最小化**：发给客户端的凭据是**单目标、短 TTL**;用完吊销。 - -### 9.8 体验(参考 Claude Code work) -- **work 视图最小信息**:每个 agent 的「当前在做什么(一句话)+ 正在改哪个文件 + 跑了什么命令/工具 + 产出」,实时滚动。 -- **可中断**:用户能在 work 视图里随时停/插话(`/messages`)。 -- **可读日志分层**:普通用户看 `user_logs`(友好),调试面板看 `debug_logs`(原始)。 - ---- - -## 10. 与现状的差距清单（三端 TODO） - -**Phase 0（运维，硬卡点）** -- 🔴 打通 Key Vault 托管身份（VM identity 授 KV Secrets Officer）——不通则资源绑定/凭据全链路不可用。 - -**Heicode Manager** -- 🟡→🟢 资源绑定 API（git/vm/db/blob CRUD + 凭据写 KV + secret_ref；KV 通后启用） -- 🔴 SSE 事件流转发（`/events/stream`） -- 🔴 给 agent/客户端的「绑定读取 + 短期租约」接口（部署取凭据用） -- 🟡 workflow per-agent 富字段（已预留，等 AM 填） -- 🔴 资源绑定 UI（重做干净版） - -**agent_management（runtime）** -- 🔴 真正 git 入库 + 多 agent 分支 + 合并成交付分支 -- 🔴 跑测试/编译并把结果作为 **`test_report` 产物给客户端看**（**不是给 HM 裁决**；对错由客户端+用户判，§6.6） -- 🔴 对照 `acceptance_criteria` 自检，结果同样作为产物给客户端 -- 🔴 per-agent 指标上报（tokens/tools/elapsed/当前动作） -- 🔴 artifact 带 `source_agent_role` + `git_ref` -- 🔴 phases[] 阶段细分上报 -- 🔴 中途续跑 / redo 语义 - -**桌面客户端**（本身是 Claude-Code 式智能体程序） -- 🟡 模式选择：本地模式（本地跑 agent）vs sub 模式（派云端 AM）；**未绑 git 时禁用 sub 入口** -- 🟡 work 视图（先轮询 workflow，SSE 后接）——**只展示运行信息**（日志/状态/work），不做产物下载 -- 🔴 **看产物 = git**：`git clone/pull` 用户仓库展示工程/历史/diff（不再拼 artifact 项目树） -- 🔴 迭代路径 B：`git pull` → 本地 agent 改 → push（复用本地能力，不必每次回云端） -- 🔴 部署：经 HM 取短期凭据 + 用户确认后本地执行 - ---- - -*本文为 v0.1 草案，决策点（§8）确认后转 v1。三端以本文对齐颗粒度与职责边界。* diff --git a/docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md b/docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md deleted file mode 100644 index d538bea1..00000000 --- a/docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md +++ /dev/null @@ -1,516 +0,0 @@ -# Agent Manager 普通 sub 敏捷模式对接任务清单 - -更新时间：2026-05-28 -发给：Agent Manager 负责人 -范围：普通 sub 模式，也就是 Heicode 的普通敏捷开发 Agent 模式。本文不要求 Agent Manager 实现完整蜂群 task graph；蜂群模式另见 `蜂群模式-AgentManager对接任务清单.md`。 - -## 1. 结论 - -普通 sub 敏捷模式下，Heicode 桌面客户端是用户主体验，Manager 是控制面，Agent Manager 是执行层。 - -Agent Manager 需要做的是：接收 Manager 生成的 deployment payload，按 `sub_mode=agile` 和 `agile_context` 执行阶段化开发，持续把阶段状态、日志、事件、artifact、审批请求、用量和最终结果回传给 Manager。 - -计费边界：PayPal 只作为 Heicode Manager 未来收款渠道，用于余额充值或购买 Heicode 内部订阅套餐；普通 sub 任务执行中的模型费用仍按 Manager/NewAPI 的钱包余额或订阅额度扣费。Agent Manager 不需要接 PayPal，但必须回传模型用量和运行 usage，方便 Manager/NewAPI 做归属和审计。 - -普通 sub 不等于蜂群模式： - -| 项 | 普通 sub 敏捷 | 蜂群模式 | -|---|---|---| -| 重点 | 需求、设计、开发、测试、修复、部署等阶段推进 | 多 Agent 任务图、claim、heartbeat、handoff | -| 是否必须 task graph | 否 | 是 | -| 是否需要 artifact 回流 | 是 | 是 | -| 是否需要高危审批 | 是 | 是 | -| 是否需要日志/事件/指标 | 是 | 是 | -| 客户端主体验 | 是 | 是 | - -## 2. 当前 Manager 已完成 - -| 能力 | 状态 | 说明 | -|---|---|---| -| HeicodeTask -> deployment draft | 已完成 | `POST /api/agent/user/tasks/{task_id}/deployment-draft` | -| 用户态 deployment 创建 | 已完成 | `POST /api/agent/user/deployments` | -| Runtime create bridge | 已完成 | 通过环境变量调用 Agent Manager | -| Runtime stop bridge | 已完成 | 停止时同步 Runtime | -| callback 接收 | 已完成 | `POST /api/agent/callbacks/swarm-events` | -| phase / timeline 聚合 | 已完成 | deployment timeline 聚合 audit、callback、artifact、SK | -| artifact 查询 | 已完成 | `GET /api/agent/user/deployments/{deployment_id}/artifacts` | -| approval 查询/approve/reject | 已完成 | `/api/agent/approvals` | -| V2 body 加密 | 已完成 | 桌面客户端到 Manager 的 POST 请求复用模型调用加密协议 | -| 生产验证 | 已完成核心链路 | 生产已验证 Manager `1.4.18` 可通过 `/api/swarms` 创建普通 sub run，持久化 `runtime_swarm_id=swm_*`，Agent Manager 自动 callback 可写入 `events/timeline`；`1.4.19` 补齐 callback 后反写 deployment 快照 | -| callback 状态反写 | 已完成 | Manager 接收 `deployment.status_changed`、`phase.changed`、`timeline.updated`、`agent.started/completed/crashed` 后，会同步更新 deployment `status/phase/runtime_state/agent_instances`，避免详情页长期停留 `initializing/pending` | -| PayPal/计费边界文档 | 已完成 | `docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.md` 已明确收款、余额、订阅、NewAPI 扣费和 Agent 运行预算关系 | - -## 3. Agent Manager 需要实现或确认的 P0 - -| 任务 | 必需 | 原因 | 验收 | -|---|---:|---|---| -| 接收 Manager 创建请求 | 是 | Manager 会把普通 sub deployment 发送给 Agent Manager | `POST /api/agent/deployments` 或配置的 create path 返回 2xx | -| 支持 `sub_mode=agile` | 是 | 普通敏捷模式核心标识 | 不认识时不能按蜂群 task graph 强制处理 | -| 支持 `agile_context` | 是 | 用于阶段、检查点、验收标准和下一步动作 | Runtime 能读取并在回调里更新 stage/checkpoint | -| 支持阶段状态回传 | 是 | 客户端需要知道当前处在需求/设计/开发/测试/修复/部署哪个环节 | 回调 `phase.changed` 或 `timeline.updated` | -| 支持 artifact 回写 | 是 | 中间交付物和最终结果必须回到 Heicode | 回调 `artifact.created` | -| 支持审批请求 | 是 | 高危操作必须客户端审批 | 回调 `approval.requested` 并等待 decision | -| 支持 stop | 是 | 用户停止任务时 Runtime 必须停止真实执行 | stop 接口返回 stopped | -| 支持日志/事件/指标 | 是 | 联调和验收需要排障数据 | 提供 callback 或查询接口 | -| 支持用量归属 | 是 | NewAPI / CodeGW 计费要按 deployment/task/role 归属 | 回传 usage/budget 事件或在模型调用中带 correlation | -| 支持 Runtime usage 回传 | 是 | `budget.max_cost_usd` 只是预算上限，真实 Agent 运行费用不能由 Manager 猜 | 回传模型 token/cost、runtime 秒数、CPU/内存等可核对 usage | - -## 4. Runtime 创建接口 - -Manager 当前默认 create path： - -```text -AGENT_RUNTIME_CREATE_PATH=/api/agent/deployments -``` - -如果 Agent Manager 统一使用 `/api/swarms`，Manager 也可以配置切过去。但普通 sub 敏捷模式建议先支持： - -```http -POST /api/agent/deployments -Authorization: Bearer -X-User-ID: -X-Binding-Scope: -X-Correlation-ID: -X-Idempotency-Key: manager- -Content-Type: application/json -``` - -请求体核心形状： - -```json -{ - "orchestration_plan": { - "intent_id": "task-client-sim-1779875397", - "template_hint": "heicode-task", - "objective": "交付轻量待办系统 MVP", - "sub_mode": "agile", - "risk_level": "low", - "budget": { - "max_tokens": 20000, - "max_cost_usd": 1, - "max_duration_sec": 600 - }, - "user_context": { - "user_id": "22", - "channel_id": "heicode", - "binding_scope": "task-client-sim" - }, - "billing_context": { - "provider": "newapi", - "default_model_id": "smoke-model", - "allowed_model_ids": ["smoke-model"], - "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key" - }, - "agile_context": { - "iteration": "2026-05-28", - "stage": "planning", - "checkpoint": "draft_created", - "acceptance_criteria": [ - "接口返回成功", - "artifact 可回写到 timeline", - "不出现明文密钥" - ], - "next_action": "continue", - "requires_user_approval": false - }, - "agent_runtime": { - "platform": "agent", - "agents": [ - { - "role": "backend", - "model_ref": "smoke-model", - "instance_count": 1 - } - ] - }, - "agents": [ - { - "role_template": "backend", - "goal": "完成本轮后端任务", - "default_model_id": "smoke-model", - "resource_grants": [] - } - ], - "resource_grants": [] - }, - "agents": [ - { - "role": "backend", - "resource_grants": [] - } - ], - "risk_level": "low", - "budget": { - "max_tokens": 20000, - "max_cost_usd": 1, - "max_duration_sec": 600 - }, - "billing_context": { - "provider": "newapi", - "default_model_id": "smoke-model", - "allowed_model_ids": ["smoke-model"], - "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key" - }, - "resource_grants": [ - { - "grant_id": "grant-client-sim-git", - "resource_id": "git-client-sim", - "resource_type": "git", - "permission_scope": ["repo:read"], - "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/client-sim-git", - "ref": "azkv://heicode-kv.vault.azure.net/secrets/client-sim-git", - "target_role": "backend" - } - ], - "callback": { - "url": "https://code.xinghanlab.com/api/agent/callbacks/swarm-events", - "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key", - "subscribed_events": [ - "deployment.status_changed", - "phase.changed", - "agent.started", - "agent.completed", - "agent.crashed", - "sk_tool.called", - "sk_tool.completed", - "sk_tool.failed", - "approval.requested", - "budget.alert", - "artifact.created", - "timeline.updated" - ] - }, - "agile_context": { - "iteration": "2026-05-28", - "stage": "planning", - "checkpoint": "draft_created", - "next_action": "continue", - "requires_user_approval": false - }, - "sub_mode": "agile", - "metadata": { - "manager_deployment_id": "dep_xxx", - "heicode_deployment_id": "dep_xxx", - "heicode_runtime_bridge": true, - "correlation_id": "corr_xxx" - } -} -``` - -响应： - -```json -{ - "success": true, - "data": { - "deployment_id": "runtime-dep-123", - "status": "running", - "estimated_ready_at": "2026-05-28T10:02:00Z" - } -} -``` - -建议也返回 `swarm_id`，即使普通 sub 不强依赖蜂群任务图，后续统一追踪会更方便。 - -## 5. 普通 sub 敏捷阶段 - -Agent Manager 至少要支持以下阶段语义，并通过 callback 回写当前阶段： - -| stage | 含义 | 建议 checkpoint | -|---|---|---| -| `planning` | 需求澄清/任务拆分 | `draft_created`, `requirements_confirmed` | -| `design` | 方案/API/数据结构设计 | `design_ready` | -| `development` | 编码实现 | `backend_done`, `frontend_done`, `artifact_ready` | -| `testing` | 自动测试/手工验证 | `ready_for_test`, `test_passed`, `test_failed` | -| `fixing` | 根据测试或用户反馈修复 | `fix_started`, `fix_ready` | -| `deployment` | 部署/发布准备 | `deploy_ready`, `deployed` | -| `review` | 复核/总结/交付 | `review_ready`, `completed` | -| `done` | 结束 | `completed` | -| `failed` | 失败 | `failed` | - -阶段回调示例： - -```json -{ - "event_id": "evt_phase_1", - "event_type": "phase.changed", - "deployment_id": "dep_xxx", - "agent_instance_id": "agent-backend-1", - "occurred_at": "2026-05-28T10:10:00Z", - "correlation_id": "corr_xxx", - "source": "agent-manager", - "payload": { - "stage": "development", - "checkpoint": "backend_done", - "title": "后端实现完成", - "summary": "已完成工单列表和状态流转接口，等待测试", - "agent_role": "backend", - "severity": "success", - "next_action": "submit_test_result" - } -} -``` - -如果 Agent Manager 暂时不支持 `phase.changed`，也可以先使用 `timeline.updated`，但 payload 中必须带 `stage` 和 `checkpoint`。 - -## 6. timeline.updated - -普通 sub 敏捷下，客户端主要看 timeline。Agent Manager 应持续回写可展示事件。 - -联调前可以先请求 Manager 当前接受的 callback schema： - -```http -GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema -``` - -该接口只返回事件类型、分类和必填字段，不返回任何 token 或密钥。普通 sub 敏捷重点核对 `phase.changed`、`timeline.updated`、`artifact.created`、`approval.requested`、`sk_tool.*` 和 `budget.alert`。 - -```json -{ - "event_id": "evt_timeline_1", - "event_type": "timeline.updated", - "deployment_id": "dep_xxx", - "occurred_at": "2026-05-28T10:11:00Z", - "source": "agent-manager", - "payload": { - "title": "测试完成", - "summary": "接口测试通过 12 项，未发现阻塞问题", - "stage": "testing", - "checkpoint": "test_passed", - "agent_role": "reviewer", - "severity": "success", - "next_action": "submit_artifact" - } -} -``` - -## 7. artifact.created - -普通 sub 模式必须回流中间交付物和最终交付结果。不要只写 Runtime 本地日志。 - -```json -{ - "event_id": "evt_artifact_1", - "event_type": "artifact.created", - "deployment_id": "dep_xxx", - "task_id": "task-backend-1", - "source": "agent-manager", - "payload": { - "artifact_id": "art_test_report_1", - "artifact_type": "test_report", - "title": "接口测试报告", - "summary": "12 项接口测试通过", - "uri": "artifact://runtime/dep_xxx/test-report", - "checksum": "sha256:abc123", - "stage": "testing", - "checkpoint": "test_passed" - } -} -``` - -支持的 `artifact_type` 建议： - -| artifact_type | 说明 | -|---|---| -| `code_patch` | 代码补丁或分支引用 | -| `document` | 需求/设计/说明文档 | -| `test_report` | 测试报告 | -| `deployment_manifest` | 部署清单 | -| `log_bundle` | 日志包 | -| `other` | 其他 | - -## 8. approval.requested 和 decision - -普通 sub 模式也需要高危审批。高危动作包括但不限于： - -| 操作 | 例子 | -|---|---| -| 写 Git 仓库 | push 分支、改配置、创建 PR | -| 改云资源 | 创建/删除 VM、AKS、存储、数据库 | -| 部署到生产 | 发布、迁移、重启服务 | -| 使用敏感凭据 | 需要从 `secret_ref` 派生短期凭证 | - -审批请求： - -```json -{ - "event_id": "evt_approval_1", - "event_type": "approval.requested", - "deployment_id": "dep_xxx", - "agent_instance_id": "agent-backend-1", - "source": "agent-manager", - "payload": { - "approval_id": "appr_runtime_1", - "operation": "git.write", - "resource_id": "repo-main", - "resource_type": "git", - "resource_scope": "feature/*", - "target_role": "backend", - "risk_level": "high", - "requires_credential": true, - "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main", - "ttl_seconds": 900, - "reason": "需要写入功能分支以提交本轮修改" - } -} -``` - -Manager 回传 decision： - -```http -POST /api/swarms/{swarm_id}/approvals/{approval_id} -``` - -如果普通 sub 不使用 `swarm_id`，可让 Manager 配置为： - -```text -AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/agent/deployments/{deployment_id}/approvals/{approval_id} -``` - -Runtime 需要接收： - -```json -{ - "approval_id": "appr_runtime_1", - "decision": "approved", - "manager_deployment_id": "dep_xxx", - "runtime_deployment_id": "runtime-dep-123", - "operation": "git.write", - "resource_id": "repo-main", - "resource_type": "git", - "target_role": "backend", - "requires_credential": true, - "credential_ref": "lease://agent/lease_xxx", - "lease_id": "lease_xxx", - "lease_expires_at": 1779850900000 -} -``` - -Runtime 收到： - -| decision | Runtime 动作 | -|---|---| -| `approved` | 继续该高危动作，只使用 `credential_ref` 对应的短期凭证 | -| `rejected` | 停止该动作，回调 `timeline.updated` 或 `phase.changed`，标记被拒绝 | - -## 9. logs / events / metrics - -Manager 当前有用户态查询位置，但真实数据需要 Agent Manager 产出。 - -Agent Manager 至少需要支持以下一种方式： - -| 方式 | 说明 | -|---|---| -| callback 摘要 | 用 `timeline.updated` 持续回写阶段、耗时、错误摘要 | -| 查询接口 | 提供 `/logs`、`/events`、`/metrics`，Manager 后续可拉取 | -| 混合 | 关键状态 callback，详细日志走查询接口 | - -建议指标： - -| 指标 | 用途 | -|---|---| -| `status` | running/stopped/failed/completed | -| `stage` / `checkpoint` | 当前敏捷阶段 | -| `agent_role` | 哪个角色在执行 | -| `tokens_used` / `cost_usd` | 用量归属 | -| `duration_ms` | 阶段耗时 | -| `error_code` / `error_message` | 失败排障 | -| `artifact_count` | 产物数量 | - -## 10. billing / NewAPI 用量归属 - -Agent Manager 调模型时，需要把 Manager 传入的上下文带上，便于 NewAPI / CodeGW 计费归属。 - -PayPal 不在这条链路里。PayPal 支付成功后只会把用户权益写入 Heicode 钱包余额或内部订阅；普通 sub 执行时，Agent Manager 仍然按 `billing_context.provider=newapi` 使用 Manager 传入的用户、deployment、role 和模型上下文。 - -至少保留： - -| 字段 | 来源 | 用途 | -|---|---|---| -| `user_id` | `user_context.user_id` | 用户归属 | -| `manager_deployment_id` | `metadata.manager_deployment_id` | deployment 归属 | -| `correlation_id` | header 或 metadata | 链路追踪 | -| `agent_role` | agents[].role | 角色归属 | -| `task_id` | Runtime 内部任务 | 子任务归属 | -| `model_id` | billing/default model | 模型用量 | - -Agent Manager 回传 usage 时建议至少包含： - -| 字段 | 说明 | -|---|---| -| `model_tokens` | 本 deployment/task/role 消耗的模型 token。 | -| `model_cost_usd` | Runtime 或 NewAPI 可确认的模型成本。 | -| `runtime_seconds` | Agent 实际运行秒数。 | -| `cpu_core_seconds` | 如 Runtime 具备集群指标，应回传 CPU 使用量。 | -| `memory_mb_seconds` | 如 Runtime 具备集群指标，应回传内存使用量。 | -| `billing_source` | 建议为 `newapi`、`manager_wallet`、`manager_subscription` 或 Runtime 约定值。 | - -注意：`budget.max_tokens`、`budget.max_cost_usd`、`budget.max_duration_sec` 是预算和拦截上限，不是已结算金额。Manager 只能展示和审计预算；真实扣费或成本归属必须基于 Agent Manager / Runtime 回传的 usage。 - -如果发生预算告警，回调： - -```json -{ - "event_id": "evt_budget_1", - "event_type": "budget.alert", - "deployment_id": "dep_xxx", - "source": "agent-manager", - "payload": { - "consumed_usd": 7.2, - "max_cost_usd": 8, - "threshold_pct": 90, - "severity": "warning" - } -} -``` - -## 11. 安全要求 - -| 要求 | 说明 | -|---|---| -| 不接收/不打印明文长期密钥 | password/token/private_key/access_key/connection_string/model key 都不能出现在日志、callback、artifact metadata | -| 只使用 `secret_ref` | 长期凭据引用统一 `azkv:///secrets/` | -| 只用 `credential_ref` 执行审批后的动作 | Manager 同意后返回 `lease://...`，不要要求长期密钥 | -| callback 必须幂等 | 重试同一个 `event_id` 不能重复创建 artifact/approval | -| callback 必须有来源 | `source=agent-manager` 或 `heicode-swarm-runtime` | - -## 12. 普通 sub 联调验收步骤 - -| 步骤 | 操作 | 期望 | -|---:|---|---| -| 1 | Manager 调 Agent Manager health | healthy | -| 2 | Manager 创建 `sub_mode=agile` deployment | Runtime 返回 `deployment_id`，建议返回 `swarm_id` | -| 3 | Runtime 回调 `phase.changed` planning/design/development/testing | Manager timeline 可见阶段推进 | -| 4 | Runtime 回调 `timeline.updated` | 客户端可展示当前子环节反馈 | -| 5 | Runtime 回调 `artifact.created` | Manager artifacts 列表出现中间产物 | -| 6 | Runtime 回调 `approval.requested` | Manager pending approval 出现 | -| 7 | Manager approve/reject | Runtime 收到 decision 并继续/停止对应动作 | -| 8 | Manager stop | Runtime deployment 真实停止 | -| 9 | Runtime 回调 completed/failed | Manager detail/timeline 显示终态 | -| 10 | Runtime 回调用量 | Manager 能看到 model token/cost 或 usage 摘要，且与 deployment/task/role/correlation 关联 | -| 11 | 查日志 | 不出现明文密钥，不丢 `correlation_id` | -| 12 | 生产路由复核 | `GET /api/agent/callbacks/swarm-events/schema` 返回 200，用户态/后台态接口使用有效登录态通过 smoke | - -## 13. Agent Manager 不需要处理的内容 - -| 不需要处理 | 原因 | -|---|---| -| 桌面客户端 V2 body 加密 | 这是客户端到 Manager，Manager 已处理 | -| Manager 用户登录/session | Manager 控制 | -| HeicodeTask 追问/任务卡生成 | 客户端和 Manager 代理处理 | -| Azure Key Vault 写入长期密钥 | Manager 负责资源绑定和 `secret_ref` 管理 | -| Web 控制台页面展示 | Manager 负责 | -| PayPal 收款和充值订单 | Manager 负责；Agent Manager 只需要回传执行和用量，不直接处理支付 | - -## 14. 当前已知缺口 - -| 缺口 | 属于谁 | 说明 | -|---|---|---| -| 真实 Runtime 是否完整消费 `agile_context` | Agent Manager | 需要确认字段被使用，不只是透传 | -| 阶段状态持续回传 | 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/agent/deployments/...` | -| 用量回传 | 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/agent/callbacks/swarm-events/schema` 返回 404，需要重新上线或核对生产镜像/路由 | -| 无 body GET 的 V2 签名 | 客户端 + Manager | 这是客户端全链路无 cookie 的后续项，不阻塞 Agent Manager 创建/回调联调 |