taijibaga/heicode-mananger
9
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

feat(agent): unify agnet→agent and implement client/runtime unification spec v0.1 core

Browse Source 
按桌面客户端统一方案 v0.1 + agent_management Sub Mode Runtime 对接,强制全量统一,不留兼容。

命名统一(强制,无兼容):
- 全仓 agnet/Agnet/AGNET → agent/Agent/AGENT:后端 Go(路由 /api/agent/*、env AGENT_*、
  结构体/函数、19 个文件改名)、前端(agent-console/agent-hub、/api/agent 调用、i18n)、
  DB(表 agent_*、列 agent_id)、compose/.env、文档、脚本。
- DB 加幂等迁移 renameAgnetTablesToAgent():启动时 rename 老 agnet_* 表/列,保住生产数据。

统一方案核心(10 项):
- callback 统一 /api/agent/callbacks/runtime-events(路由/广播URL/函数名)。
- artifact 兜底判定改用 Runtime 权威信号 metadata.synthesized(§7.2)+ 结构化 artifact_type。
- Manager→Runtime 路径对齐 /api/agent/sub-agile/deployments(§2.2),{deployment_id} 回退 swarm_id。
- 状态裁决 display_status:Manager 唯一裁判,completed 无有效产物→needs_codegen/
  completed_without_deliverable(§10.6),接入 detail/timeline/workflow。
- GET /api/heicode/capabilities 能力发现(§6)。
- 模型策略 per_role(role_models)+ 收集 allowed_model_ids(§9)。
- resource_binding_id→secret_ref 服务端解析,客户端不再 inline secret_ref(§17.6)。
- 客户端统一路由层 /api/heicode/sub-agile|swarm/*(task≡deployment,复用控制面)+ workflow 投影。
- 日志分层 user_logs/debug_logs(§13)。

验证:go build ./... + go test(controller/router/model/middleware)全绿;前端 tsc -b + rsbuild build 通过。
待部署:VM .env 的 AGNET_*→AGENT_*;启动迁移自动 rename 表;其他三仓库需同步切到 /api/agent。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
chenchen
2026-06-01 23:45:10 +08:00
co-authored by Claude Opus 4.8
parent 12602ebcd6
commit 0fe1d20d67
112 changed files with 4305 additions and 3139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/integration/AgentManager普通sub产物回调缺失问题.md
+10 -10
View File
@@ -1,7 +1,7 @@
# Agent Manager 普通 sub 产物回调缺失问题
更新时间：2026-05-29
发给：Agent Manager / Agnet Runtime 负责人
发给：Agent Manager / Agent Runtime 负责人
范围：普通 sub 敏捷模式，不包含 HeiCode-Swarm 独立蜂群 Runtime。
## 1. 问题现象
@@ -36,8 +36,8 @@ SK SNAPSHOTS = 0
Heicode Manager 生产配置确认当前普通 sub 走：
```text
AGNET_RUNTIME_BASE_URL=http://20.212.121.126
AGNET_RUNTIME_CREATE_PATH=/api/swarms
AGENT_RUNTIME_BASE_URL=http://20.212.121.126
AGENT_RUNTIME_CREATE_PATH=/api/swarms
```
`SWARM_RUNTIME_BASE_URL` 当前为空。
@@ -47,7 +47,7 @@ AGNET_RUNTIME_CREATE_PATH=/api/swarms
```text
Heicode 桌面客户端
-> Heicode Manager 生产
-> Agent Manager / Agnet Runtime 普通 sub 入口
-> Agent Manager / Agent Runtime 普通 sub 入口
-> Heicode Manager callback
-> 桌面客户端查询 artifacts/timeline
```
@@ -102,7 +102,7 @@ sk_tool.completed = 0
Heicode Manager artifact 表查询结果：
```text
agnet_artifacts where deployment_id = 'dep_fa4f43da9e0a'
agent_artifacts where deployment_id = 'dep_fa4f43da9e0a'
=> 0 rows
```
@@ -113,7 +113,7 @@ agnet_artifacts where deployment_id = 'dep_fa4f43da9e0a'
生产日志中，Agent Manager 在任务完成时间段连续请求：
```text
POST /api/agnet/callbacks/swarm-events
POST /api/agent/callbacks/swarm-events
```
HTTP 状态均为：
@@ -188,7 +188,7 @@ Logs will be fetched from K8s in Phase 2
本问题根因不在 Heicode Manager，也不在桌面客户端。
当前证据指向 Agent Manager / Agnet Runtime：
当前证据指向 Agent Manager / Agent Runtime：
1. Runtime 将 deployment 标记为 `completed`。
2. Runtime 自身返回 `artifacts: []`。
@@ -206,7 +206,7 @@ Logs will be fetched from K8s in Phase 2
普通 sub 任务完成时，Agent Manager 必须向 Heicode Manager callback：
```text
POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
event_type = artifact.created
```
@@ -370,7 +370,7 @@ Logs will be fetched from K8s in Phase 2
|---|---|
| Runtime 状态 | deployment 和 agents 状态一致 |
| callback | Heicode Manager 收到 `artifact.created` |
| Manager artifacts | `/api/agnet/user/deployments/{deployment_id}/artifacts` 返回 total > 0 |
| Manager artifacts | `/api/agent/user/deployments/{deployment_id}/artifacts` 返回 total > 0 |
| 客户端展示 | 右侧 `ARTIFACTS` 不再是 0 |
| 交付物 | 能看到 Git 分支、提交、预览地址、部署清单或最终结果文档 |
| usage | 如果真实调用模型，tokens/cost 不应一直为 0 |
@@ -380,7 +380,7 @@ Logs will be fetched from K8s in Phase 2
Heicode Manager 和桌面客户端当前表现是正确反映 Runtime 数据。
真正缺口在 Agent Manager / Agnet Runtime：
真正缺口在 Agent Manager / Agent Runtime：
```text
任务被标记 completed，但 Runtime 没有生成或回传 artifact.created。
docs/integration/AgentManager普通sub剩余补充要求.md
+3 -3
View File
@@ -1,7 +1,7 @@
# Agent Manager 普通 sub 剩余补充要求
更新时间：2026-05-28
发给：Agent Manager / Agnet Runtime 负责人
发给：Agent Manager / Agent Runtime 负责人
范围：普通 sub 敏捷开发模式，不包含蜂群模式完整 task graph。
## 1. 当前已验证事实
@@ -59,7 +59,7 @@ Heicode Manager 生产版本 `1.4.19` 已完成并验证以下链路：
Manager callback 地址：
```text
https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
https://code.xinghanlab.com/api/agent/callbacks/swarm-events
```
创建 run 后，Agent Manager 至少需要主动回调这些事件：
@@ -224,7 +224,7 @@ Agent Manager 补完后，按以下步骤验收：
- `artifact.created`
- `budget.alert`
5. Manager 查询：
- `/api/agnet/user/deployments/{deployment_id}`
- `/api/agent/user/deployments/{deployment_id}`
- `/events`
- `/timeline`
- `/artifacts`
docs/integration/AgentManager普通sub联调整改要求.md
+46 -46
View File
@@ -1,7 +1,7 @@
# Agent Manager 普通 sub 联调整改要求
更新时间：2026-05-28
发给：Agent Manager / Agnet Runtime 负责人
发给：Agent Manager / Agent Runtime 负责人
范围：Heicode Manager 普通 sub 敏捷模式联调，不包含蜂群模式完整 task graph 的额外能力。
## 1. 当前结论
@@ -10,7 +10,7 @@ Agent Manager 新版文档 `HEICODE_API_INTEGRATION(5).md` 已经补充了 Runti
按 2026-05-28 生产实测，Manager 与 Agent Manager 的普通 sub 核心通讯链路已经跑通，但还不能认为“真实开发执行结果”完整闭环。当前结论是：
1. Agent Manager 当前联调统一使用 IP `http://20.212.121.126`；域名 `https://agent-manager.taijiagnet.com` 后续解析和证书就绪后再切换，不作为当前联调阻塞项。
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` 的状态不一致。
@@ -18,9 +18,9 @@ Agent Manager 新版文档 `HEICODE_API_INTEGRATION(5).md` 已经补充了 Runti
Heicode Manager 侧已确认：
- `POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events` 生产路由在线。
- `POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events` 生产路由在线。
- callback 支持 HMAC 和旧 token 兼容；当前生产为了先跑通自动 callback，已配置 HMAC fallback。
- `GET https://code.xinghanlab.com/api/agnet/callbacks/swarm-events/schema` 已由 Manager 提供，用于联调前核对事件类型和必填字段。
- `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
@@ -30,7 +30,7 @@ Heicode Manager 侧已确认：
| 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/agnet/deployments/{deployment_id}/stop` 已可用 | 停止后 Runtime 真实停止，并回调 stopped 事件 |
| 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、成本、运行时长、资源使用 |
@@ -39,7 +39,7 @@ Heicode Manager 侧已确认：
### 3.1 健康检查
```http
GET /api/agnet/health
GET /api/agent/health
```
要求：
@@ -50,10 +50,10 @@ GET /api/agnet/health
### 3.2 创建普通 sub 运行
普通 sub 当前生产联调使用 Agent Manager `/api/agnet/deployments`，蜂群 `/api/swarms` 另见 `AgentManager蜂群Runtime接口实现要求.md`。
普通 sub 当前生产联调使用 Agent Manager `/api/agent/deployments`，蜂群 `/api/swarms` 另见 `AgentManager蜂群Runtime接口实现要求.md`。
```http
POST /api/agnet/deployments
POST /api/agent/deployments
Authorization: Bearer <HEICODE_SERVICE_TOKEN>
Content-Type: application/json
X-User-ID: <user_id>
@@ -115,8 +115,8 @@ X-Idempotency-Key: <idempotency_key>
"resource_grants": []
},
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key",
"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",
@@ -154,14 +154,14 @@ X-Idempotency-Key: <idempotency_key>
要求：
1. `deployment_id` 必须可用于 `/api/agnet/deployments/{deployment_id}`、`/api/agnet/deployments/{deployment_id}/stop`。
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/agnet/deployments/{deployment_id}
GET /api/agent/deployments/{deployment_id}
Authorization: Bearer <HEICODE_SERVICE_TOKEN>
```
@@ -188,7 +188,7 @@ Authorization: Bearer <HEICODE_SERVICE_TOKEN>
### 3.4 停止普通 sub deployment
```http
POST /api/agnet/deployments/{deployment_id}/stop
POST /api/agent/deployments/{deployment_id}/stop
Authorization: Bearer <HEICODE_SERVICE_TOKEN>
Content-Type: application/json
```
@@ -223,7 +223,7 @@ Content-Type: application/json
Manager 生产 callback 地址：
```text
https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
https://code.xinghanlab.com/api/agent/callbacks/swarm-events
```
### 4.1 认证方式
@@ -231,9 +231,9 @@ https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
优先使用 HMAC：
```http
X-Agnet-Event-Id: evt_xxx
X-Agnet-Timestamp: <unix_ms>
X-Agnet-Signature: sha256=<hex>
X-Agent-Event-Id: evt_xxx
X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>
X-Correlation-ID: <correlation_id>
Content-Type: application/json
```
@@ -248,7 +248,7 @@ signature = HMAC_SHA256(callback_signing_secret, signature_payload)
过渡期可使用旧 token：
```http
X-Agnet-Service-Token: <HEICODE_SERVICE_TOKEN>
X-Agent-Service-Token: <HEICODE_SERVICE_TOKEN>
```
不要把真实 token 写入文档、日志或 artifact。
@@ -397,7 +397,7 @@ Manager 端已有 approval、credential lease、approve/reject 和 Runtime decis
推荐接口：
```http
POST /api/agnet/deployments/{deployment_id}/approvals/{approval_id}
POST /api/agent/deployments/{deployment_id}/approvals/{approval_id}
Authorization: Bearer <HEICODE_SERVICE_TOKEN>
Content-Type: application/json
```
@@ -415,7 +415,7 @@ Content-Type: application/json
"resource_id": "repo_main",
"risk_level": "high",
"requires_credential": true,
"credential_ref": "lease://agnet/cred_123",
"credential_ref": "lease://agent/cred_123",
"lease_id": "lease_123",
"lease_expires_at": 1770000000000,
"decided_by": "user_123",
@@ -454,10 +454,10 @@ Agent Manager 改完后，按下面步骤验收。
| 步骤 | 操作 | 通过标准 |
|---:|---|---|
| 1 | `GET /api/agnet/health` | 返回 healthy |
| 2 | `POST /api/agnet/deployments` 创建普通 sub run | 返回 `deployment_id`、`status` |
| 1 | `GET /api/agent/health` | 返回 healthy |
| 2 | `POST /api/agent/deployments` 创建普通 sub run | 返回 `deployment_id`、`status` |
| 3 | 重复同一个 `X-Idempotency-Key` 创建 | 不重复创建，返回同一个 ID |
| 4 | `GET /api/agnet/deployments/{deployment_id}` | 返回真实状态和 agents |
| 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 可查到 |
@@ -465,7 +465,7 @@ Agent Manager 改完后，按下面步骤验收。
| 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/agnet/deployments/{deployment_id}/stop` | Runtime 停止，状态变为 stopped |
| 12 | `POST /api/agent/deployments/{deployment_id}/stop` | Runtime 停止，状态变为 stopped |
| 13 | 检查日志和 artifact metadata | 不包含明文密钥 |
## 9. 当前实测记录
@@ -474,12 +474,12 @@ Agent Manager 改完后，按下面步骤验收。
| 接口 | 结果 | 说明 |
|---|---|---|
| `GET http://20.212.121.126/api/agnet/health` | 200 | Agent Manager IP 健康检查正常 |
| `GET https://agent-manager.taijiagnet.com/api/agnet/health` | 暂不作为当前验收项 | 当前约定先走 IP，域名后续再切换 |
| `POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events` 无认证 | 业务返回 `CALLBACK_UNAUTHORIZED` | Manager callback 路由在线 |
| `POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events` 带旧 token 但空 body | 业务返回 `CALLBACK_INVALID` | 认证通过，进入事件校验 |
| `GET https://code.xinghanlab.com/api/agnet/callbacks/swarm-events/schema` | 404 | Manager schema GET 生产未通，Manager 侧需复核 |
| `POST http://20.212.121.126/api/agnet/deployments` | 200 | 普通 sub Runtime deployment 创建可用 |
| `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 追加联调记录
@@ -491,17 +491,17 @@ Agent Manager 改完后，按下面步骤验收。
- 因此本次没有宣称“桌面客户端登录后走 Manager 用户态创建 deployment”完整通过。
- 本次完成的是服务到服务联调：Manager/客户端等价 payload -> Agent Manager IP，以及 Agent Manager callback 协议 -> Heicode Manager callback 接收端。
Agent Manager `/api/agnet/deployments` 服务到服务链路：
Agent Manager `/api/agent/deployments` 服务到服务链路：
| 步骤 | 结果 | 证据 |
|---|---|---|
| `GET /api/agnet/health` | 通过 | 返回 `success=true`、`status=healthy` |
| `POST /api/agnet/deployments` | 通过 | 返回 `deployment_id=dep_dbafd1ac37c3`，状态 `pending` |
| `GET /api/agnet/deployments/{deployment_id}` | 通过 | 能查到 `user_id`、`binding_scope`、`sub_mode=agile`、`callback_configured=true` |
| `GET /api/agnet/deployments/{deployment_id}/events` | 部分通过 | 只看到 `deployment.accepted`，未看到 `phase.changed/timeline.updated/artifact.created/sk_tool.*` |
| `GET /api/agnet/deployments/{deployment_id}/logs` | 部分通过 | 返回系统日志 `Pod ... has no logs yet` |
| `GET /api/agnet/deployments/{deployment_id}/metrics` | 通过但疑似占位 | 返回 CPU/内存/网络指标，但值看起来是固定模拟值，需要 Runtime 说明来源 |
| `POST /api/agnet/deployments/{deployment_id}/stop` | 通过 | `dep_dbafd1ac37c3` 停止成功，返回 `status=stopped` |
| `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` |
长等待测试：
@@ -535,7 +535,7 @@ source=agent-manager-ip-smoke
结论：
1. Heicode Manager callback 接收端可用，旧 token 认证和幂等可用。
2. Agent Manager IP 的 `/api/agnet/deployments` 创建、查询、停止可用。
2. Agent Manager IP 的 `/api/agent/deployments` 创建、查询、停止可用。
3. Agent Manager 当前没有在实测中产生普通 sub 所需的 phase/timeline/artifact/SK 主动回调。
4. 因没有可用生产 Manager 用户 session，本次没有完成“客户端登录态 -> Manager 用户态 deployment -> Runtime”的完整端到端测试。
@@ -558,15 +558,15 @@ group: default
|---|---|---|
| 登录生产 Manager | 通过 | `/api/user/login` 返回 `success=true`，用户 `id=22` |
| 查询用户信息 | 通过 | `/api/user/self` 返回用户 `chenchen`、`group=default` |
| 查询 Runtime 健康 | 通过 | `/api/agnet/runtime/health` 返回 `enabled=true`、`configured=true`、`status=healthy`、`create_path=/api/agnet/deployments`、远端为 Agent Manager IP |
| 客户端模拟创建 deployment | 通过 | `POST /api/agnet/user/deployments` 返回 Manager deployment `dep_1ba14ccfb558` |
| 查询 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/agnet/user/deployments/dep_1ba14ccfb558/stop` 返回 `status=stopped` |
| Manager stop | 通过 | `POST /api/agent/user/deployments/dep_1ba14ccfb558/stop` 返回 `status=stopped` |
| Runtime stop 结果 | 通过 | 直查 Agent Manager `dep_3335e54e9bdf`，状态为 `stopped` |
本次真实 ID：
@@ -582,10 +582,10 @@ Agent Manager 侧直查 `dep_3335e54e9bdf`：
| 接口 | 结果 |
|---|---|
| `GET /api/agnet/deployments/dep_3335e54e9bdf` | 200，状态 `stopped`，`user_id=22` |
| `GET /api/agnet/deployments/dep_3335e54e9bdf/events` | 200，仅有 `deployment.accepted`、`deployment.stopped` |
| `GET /api/agnet/deployments/dep_3335e54e9bdf/logs` | 200，仅有 `Pod ... has no logs yet` |
| `GET /api/agnet/deployments/dep_3335e54e9bdf/metrics` | 200，返回 CPU/内存/网络固定值 |
| `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/内存/网络固定值 |
本次客户端模拟链路结论：
docs/integration/AgentManager蜂群Runtime接口实现要求.md
+21 -21
View File
@@ -31,18 +31,18 @@ Agent Manager / Swarm Runtime 需要负责执行层：
当前生产 Manager Runtime 配置实际为：
```text
AGNET_RUNTIME_BASE_URL=http://20.212.121.126
AGNET_RUNTIME_CREATE_PATH=/api/agnet/deployments
AGNET_RUNTIME_STOP_PATH=/api/agnet/deployments/{deployment_id}/stop
AGENT_RUNTIME_BASE_URL=http://20.212.121.126
AGENT_RUNTIME_CREATE_PATH=/api/agent/deployments
AGENT_RUNTIME_STOP_PATH=/api/agent/deployments/{deployment_id}/stop
```
实测结果：
| 项 | 结果 |
|---|---|
| `GET /api/agnet/runtime/health` | 通过，远端 Agent Manager IP healthy |
| `POST /api/swarms` 使用 `agent_runtime.platform=agnet-swarm` | 失败，Manager 返回 `agent_runtime.platform must be agnet when runtime context is present` |
| `POST /api/swarms` 使用 `agent_runtime.platform=agnet` | 通过 |
| `GET /api/agent/runtime/health` | 通过，远端 Agent Manager IP healthy |
| `POST /api/swarms` 使用 `agent_runtime.platform=agent-swarm` | 失败，Manager 返回 `agent_runtime.platform must be agent when runtime context is present` |
| `POST /api/swarms` 使用 `agent_runtime.platform=agent` | 通过 |
| Manager deployment | `dep_72cdc138b9c8` |
| Manager 返回 swarm_id | `dep_72cdc138b9c8`，当前是 Manager 本地 deployment id |
| Runtime deployment | `dep_77370f27186f` |
@@ -58,7 +58,7 @@ AGNET_RUNTIME_STOP_PATH=/api/agnet/deployments/{deployment_id}/stop
结论：
1. Heicode Manager 的 `/api/swarms` adapter 能接收用户态蜂群请求，并能通过当前 Runtime bridge 调 Agent Manager IP。
2. 当前生产链路实际走的是 Agent Manager `/api/agnet/deployments`，不是 Agent Manager `/api/swarms`。
2. 当前生产链路实际走的是 Agent Manager `/api/agent/deployments`，不是 Agent Manager `/api/swarms`。
3. Manager stop 可以传递到 Agent Manager deployment stop。
4. 当前还没有真实蜂群 Runtime callback、task graph、artifact、SK、usage。
5. Agent Manager 如果要满足正式蜂群模式，仍需实现本文后续定义的 `/api/swarms`、`/api/swarms/{swarm_id}`、`/api/swarms/{swarm_id}/stop`、callback 和 usage 约束。
@@ -68,13 +68,13 @@ AGNET_RUNTIME_STOP_PATH=/api/agnet/deployments/{deployment_id}/stop
```text
Heicode Desktop Client
-> Heicode Manager
POST /api/swarms 或 /api/agnet/user/deployments
POST /api/swarms 或 /api/agent/user/deployments
-> Agent Manager / Swarm Runtime
POST /api/swarms
<- Runtime response
runtime_deployment_id / swarm_id / status
<- Runtime callback
POST /api/agnet/callbacks/swarm-events
POST /api/agent/callbacks/swarm-events
-> Runtime approval decision
POST /api/swarms/{swarm_id}/approvals/{approval_id}
```
@@ -98,11 +98,11 @@ Content-Type: application/json
| 优先级 | 方法 | 路径 | 必须 | 用途 |
|---|---|---|---:|---|
| P0 | `GET` | `/api/agnet/health` | 是 | 健康检查 |
| P0 | `GET` | `/api/agent/health` | 是 | 健康检查 |
| P0 | `POST` | `/api/swarms` | 是 | 创建真实 Swarm Run |
| P0 | `POST` | `/api/swarms/{swarm_id}/stop` | 是 | 停止 Swarm Run |
| P0 | `POST` | `/api/swarms/{swarm_id}/approvals/{approval_id}` | 是 | 接收 Manager 审批决定 |
| P0 | callback | Manager `/api/agnet/callbacks/swarm-events` | 是 | 回写状态、task、handoff、artifact、approval |
| P0 | callback | Manager `/api/agent/callbacks/swarm-events` | 是 | 回写状态、task、handoff、artifact、approval |
| P1 | `GET` | `/api/swarms/{swarm_id}` | 建议 | 查询 Runtime 详情 |
| P1 | `GET` | `/api/swarms/{swarm_id}/tasks` | 建议 | 查询 task graph |
| P1 | `GET` | `/api/swarms/{swarm_id}/logs` | 建议 | 查询日志 |
@@ -130,7 +130,7 @@ Content-Type: application/json
3. `X-Idempotency-Key` 必须支持幂等；重复创建请求不能生成多个真实 Swarm Run。
4. Agent Manager 不得要求 Manager 传长期明文密钥。
## 5. `GET /api/agnet/health`
## 5. `GET /api/agent/health`
### 响应
@@ -227,8 +227,8 @@ Content-Type: application/json
}
],
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key",
"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",
"task.created",
@@ -342,9 +342,9 @@ Agent Manager 创建 Swarm Run 后，必须在 Runtime 内部生成任务图，
Manager 回调地址：
```http
POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
X-Agnet-Service-Token: <callback_token>
X-Agnet-Event-Id: <event_id>
POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
X-Agent-Service-Token: <callback_token>
X-Agent-Event-Id: <event_id>
X-Correlation-ID: <correlation_id>
Content-Type: application/json
```
@@ -352,8 +352,8 @@ Content-Type: application/json
也支持 HMAC：
```http
X-Agnet-Timestamp: <unix_ms>
X-Agnet-Signature: sha256=<hex>
X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>
```
HMAC 签名内容：
@@ -365,7 +365,7 @@ timestamp + "." + event_id + "." + raw_body
联调前可拉取 Manager 当前接受的事件 schema：
```http
GET https://code.xinghanlab.com/api/agnet/callbacks/swarm-events/schema
GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
```
### 通用 callback envelope
@@ -647,7 +647,7 @@ Runtime 可通过 `budget.alert` 或 `timeline.updated` 回传用量摘要。
| 步骤 | 操作 | 通过标准 |
|---:|---|---|
| 1 | Manager 调 `GET /api/agnet/health` | 返回 healthy |
| 1 | Manager 调 `GET /api/agent/health` | 返回 healthy |
| 2 | Manager 调 `POST /api/swarms` | 返回真实 `deployment_id` 和 `swarm_id` |
| 3 | Runtime 回调 `deployment.status_changed` | Manager timeline 可见 |
| 4 | Runtime 回调 `task.created` | Manager task flow / Agent task map 可见 |
docs/integration/AgentManager蜂群Runtime联调待确认与补充要求.md
+13 -13
View File
@@ -10,10 +10,10 @@
| 模式 | Runtime | 当前已知地址 | 说明 |
|---|---|---|---|
| 普通 sub 敏捷模式 | Agent Manager / Agnet Runtime | `http://20.212.121.126` | 用于普通子 Agent 敏捷开发流程 |
| 普通 sub 敏捷模式 | Agent Manager / Agent Runtime | `http://20.212.121.126` | 用于普通子 Agent 敏捷开发流程 |
| 蜂群模式 | HeiCode-Swarm Orchestrator | `http://52.139.240.116:8000` | 用于蜂群任务图、Agent 协作、handoff、task graph |
注意：两套服务可能都提供 `/api/swarms` 这类路径，但业务含义不同。Heicode Manager 后续需要按模式分别配置，不应只用一套 `AGNET_RUNTIME_BASE_URL` 混跑。
注意：两套服务可能都提供 `/api/swarms` 这类路径，但业务含义不同。Heicode Manager 后续需要按模式分别配置，不应只用一套 `AGENT_RUNTIME_BASE_URL` 混跑。
## 2. 本次读取到的蜂群 Runtime 新能力
@@ -21,9 +21,9 @@
| 能力 | 路径 | 当前判断 |
|---|---|---|
| 健康检查 | `GET /api/agnet/health` | 已提供 |
| 健康检查 | `GET /api/agent/health` | 已提供 |
| 创建蜂群 run | `POST /api/swarms` | 已提供 |
| 兼容创建入口 | `POST /api/agnet/deployments` | 已提供 |
| 兼容创建入口 | `POST /api/agent/deployments` | 已提供 |
| 查询 swarm 详情 | `GET /api/swarms/{swarm_id}` | 已提供 |
| 查询任务图 | `GET /api/swarms/{swarm_id}/tasks` | 已提供 |
| 查询日志 | `GET /api/swarms/{swarm_id}/logs` | 已提供 |
@@ -48,7 +48,7 @@ runtime contract checks passed
请求：
```bash
curl http://52.139.240.116:8000/api/agnet/health
curl http://52.139.240.116:8000/api/agent/health
```
返回核心内容：
@@ -247,7 +247,7 @@ allow_handoff=false
| 项 | 需要提供 / 确认 | 原因 |
|---|---|---|
| 蜂群 Runtime 调用 token | 已提供并验证可用；后续需要通过安全渠道配置到 Manager，不写入 Git | Manager 调 `POST /api/swarms` 需要 Bearer 鉴权 |
| callback 凭据配置 | Runtime 配置 Manager 认可的 `AGNET_CALLBACK_SERVICE_TOKEN` 或 `AGNET_CALLBACK_SIGNING_SECRET` | Runtime 回调 Manager 必须通过鉴权 |
| callback 凭据配置 | Runtime 配置 Manager 认可的 `AGENT_CALLBACK_SERVICE_TOKEN` 或 `AGENT_CALLBACK_SIGNING_SECRET` | Runtime 回调 Manager 必须通过鉴权 |
| 两套部署边界 | 明确普通 sub 继续走 `20.212.121.126`，蜂群走 `52.139.240.116:8000` | 防止普通 sub 和蜂群混用 |
| 创建响应字段 | `deployment_id`、`runtime_deployment_id`、`swarm_id`、`status` 字段保持稳定 | Manager 需要保存映射 |
| callback deployment id 规则 | callback 中 `deployment_id` 应为 Manager deployment id，`runtime_deployment_id` 为 Runtime id，`swarm_id` 为 Runtime swarm id | Manager 根据这些字段落库和展示 |
@@ -255,13 +255,13 @@ allow_handoff=false
callback 地址：
```text
https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
https://code.xinghanlab.com/api/agent/callbacks/swarm-events
```
callback schema 查询：
```text
GET https://code.xinghanlab.com/api/agnet/callbacks/swarm-events/schema
GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
```
说明：具体 token / signing secret 不应写入 Markdown 或 Git，请通过安全渠道提供。
@@ -340,8 +340,8 @@ Content-Type: application/json
]
},
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key",
"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",
"task.created",
@@ -416,8 +416,8 @@ Heicode Manager 需要保留普通 sub 和蜂群两套 Runtime 配置。建议
```text
# 普通 sub 敏捷模式
AGNET_RUNTIME_BASE_URL=http://20.212.121.126
AGNET_RUNTIME_CREATE_PATH=/api/swarms
AGENT_RUNTIME_BASE_URL=http://20.212.121.126
AGENT_RUNTIME_CREATE_PATH=/api/swarms
# 蜂群模式
SWARM_RUNTIME_BASE_URL=http://52.139.240.116:8000
@@ -427,7 +427,7 @@ SWARM_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_
SWARM_RUNTIME_SERVICE_TOKEN=<runtime-service-token>
```
如果短期 Manager 还只有一套 `AGNET_RUNTIME_*`，只能临时切换到蜂群 Runtime 做专项联调，不能同时代表普通 sub 和蜂群都在线。
如果短期 Manager 还只有一套 `AGENT_RUNTIME_*`，只能临时切换到蜂群 Runtime 做专项联调，不能同时代表普通 sub 和蜂群都在线。
## 8. 蜂群 MVP 验收口径
docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.md
+5 -5
View File
@@ -137,13 +137,13 @@ PayPal 接入时有两种做法：
| 文档口径 | 含义 |
|---|---|
| `budget.max_tokens` | 本次 Agent / Agnet 部署允许消耗的 token 上限。 |
| `budget.max_cost_usd` | 本次 Agent / Agnet 部署允许消耗的美元成本上限。 |
| `budget.max_duration_sec` | 本次 Agent / Agnet 部署允许运行的时间上限。 |
| `budget.max_tokens` | 本次 Agent / Agent 部署允许消耗的 token 上限。 |
| `budget.max_cost_usd` | 本次 Agent / Agent 部署允许消耗的美元成本上限。 |
| `budget.max_duration_sec` | 本次 Agent / Agent 部署允许运行的时间上限。 |
| `billing_context.provider = newapi` | 表示模型调用费用应映射到 NewAPI 用户、Token、Group 或 quota。 |
| `agent_runtime` | 表示子 Agent 角色、模型 profile、实例数，不能和 NewAPI 扣费对象混在一起。 |
产品文档明确：子 Agnet 的运行模型属于 Agnet 平台部署配置，不等同于 CodeGW 后台模型供应商配置。NewAPI 负责模型网关、余额、用量、日志和扣费；Agnet 平台负责真实执行和运行态。
产品文档明确：子 Agent 的运行模型属于 Agent 平台部署配置，不等同于 CodeGW 后台模型供应商配置。NewAPI 负责模型网关、余额、用量、日志和扣费；Agent 平台负责真实执行和运行态。
所以当前要分成两类费用：
@@ -378,7 +378,7 @@ Heicode Manager 当前已有余额和订阅计费闭环。PayPal 接入不改变
- Heicode 产品资料包：`docs/product-package/`
- NewAPI / CodeGW 边界：`docs/heicode-runtime-auth-newapi-secret-design.md`
- Agnet 请求契约：`docs/integration/agnet-platform-request-contract.md`
- Agent 请求契约：`docs/integration/agent-platform-request-contract.md`
- PayPal Orders v2：`https://developer.paypal.com/docs/api/orders/v2/`
- PayPal Subscriptions：`https://developer.paypal.com/docs/subscriptions/reference/`
- PayPal Webhook 事件：`https://developer.paypal.com/api/rest/webhooks/event-names`
docs/integration/agent-manager-swarm-runtime-change-request.md
+21 -21
View File
@@ -8,11 +8,11 @@
| 能力 | Manager 状态 |
|---|---|
| 用户态创建 | `POST /api/agnet/user/deployments`、`POST /api/swarms` 已可创建 Manager deployment |
| Runtime 创建桥接 | 可通过 `AGNET_RUNTIME_BASE_URL` + `AGNET_RUNTIME_CREATE_PATH` 调用 Runtime |
| Runtime 停止桥接 | 可通过 `AGNET_RUNTIME_STOP_PATH` 停止 Runtime deployment |
| 回调接收 | `POST /api/agnet/callbacks/swarm-events` 已支持事件、artifact、approval、timeline 回调 |
| 回调安全 | 支持 `X-Agnet-Service-Token` 或 `X-Agnet-Signature` HMAC |
| 用户态创建 | `POST /api/agent/user/deployments`、`POST /api/swarms` 已可创建 Manager deployment |
| Runtime 创建桥接 | 可通过 `AGENT_RUNTIME_BASE_URL` + `AGENT_RUNTIME_CREATE_PATH` 调用 Runtime |
| Runtime 停止桥接 | 可通过 `AGENT_RUNTIME_STOP_PATH` 停止 Runtime deployment |
| 回调接收 | `POST /api/agent/callbacks/swarm-events` 已支持事件、artifact、approval、timeline 回调 |
| 回调安全 | 支持 `X-Agent-Service-Token` 或 `X-Agent-Signature` HMAC |
| 幂等 | `event_id` / `idempotency_key` 去重 |
| 审批结果回传 | 用户 approve/reject 后，Manager 可调用 Runtime approval decision 接口 |
| 密钥边界 | Manager 只传 `secret_ref` / `credential_ref`，不传长期明文密钥 |
@@ -22,7 +22,7 @@
### 1. 健康检查
```http
GET /api/agnet/health
GET /api/agent/health
```
如果蜂群侧沿用现有 Orchestrator，也可以临时配置为：
@@ -59,7 +59,7 @@ Content-Type: application/json
Manager 当前也可兼容配置：
```text
AGNET_RUNTIME_CREATE_PATH=/api/swarms
AGENT_RUNTIME_CREATE_PATH=/api/swarms
```
请求核心字段：
@@ -97,8 +97,8 @@ AGNET_RUNTIME_CREATE_PATH=/api/swarms
}
],
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key",
"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",
"task.created",
@@ -145,7 +145,7 @@ AGNET_RUNTIME_CREATE_PATH=/api/swarms
默认路径：
```http
POST /api/agnet/deployments/{deployment_id}/stop
POST /api/agent/deployments/{deployment_id}/stop
Authorization: Bearer <service_token>
Content-Type: application/json
```
@@ -181,7 +181,7 @@ POST /api/swarms/{swarm_id}/stop
则 Manager 可通过环境变量配置：
```text
AGNET_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
AGENT_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
```
## 三、Runtime 回调 Manager
@@ -189,9 +189,9 @@ AGNET_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
统一回调入口：
```http
POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
X-Agnet-Service-Token: <callback_token>
X-Agnet-Event-Id: <event_id>
POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
X-Agent-Service-Token: <callback_token>
X-Agent-Event-Id: <event_id>
X-Correlation-ID: <correlation_id>
Content-Type: application/json
```
@@ -199,8 +199,8 @@ Content-Type: application/json
也支持 HMAC：
```http
X-Agnet-Timestamp: <unix_ms>
X-Agnet-Signature: sha256=<hex>
X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>
```
签名内容：
@@ -310,7 +310,7 @@ Content-Type: application/json
Manager 可配置：
```text
AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
```
请求：
@@ -329,7 +329,7 @@ AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_
"target_role": "ops",
"risk_level": "high",
"requires_credential": true,
"credential_ref": "lease://agnet/lease_xxx",
"credential_ref": "lease://agent/lease_xxx",
"lease_id": "lease_xxx",
"lease_expires_at": 1770000000000,
"decided_by": "user:22",
@@ -356,7 +356,7 @@ AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_
安全要求：
1. Manager 不会在该请求中发送 `secret_ref`。
2. 如果审批通过且需要凭证，只发送短期 `credential_ref = lease://agnet/...`。
2. 如果审批通过且需要凭证，只发送短期 `credential_ref = lease://agent/...`。
3. Runtime 不得把 `credential_ref`、service token、签名密钥写入日志或 artifact metadata。
4. Runtime 收到 `approved` 后继续原高危动作；收到 `rejected` 后停止该动作并回调 `timeline.updated` 或 `task.failed/blocked`。
@@ -378,7 +378,7 @@ AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_
| 当前入口 | 可用性 | 建议 |
|---|---|---|
| `GET /health` | 可直接作为健康检查 | Manager `AGNET_RUNTIME_HEALTH_PATH=/health` |
| `GET /health` | 可直接作为健康检查 | Manager `AGENT_RUNTIME_HEALTH_PATH=/health` |
| `POST /tasks` | 可临时创建任务 | 只能做兼容桥接，不建议作为最终生产契约 |
| `GET /tasks` | 可查任务 | 后续需要映射到 callback/timeline |
| `GET /agents` | 可查 Agent | 后续需要回调 agent status |
@@ -392,7 +392,7 @@ AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_
最小验收顺序：
1. Manager 调 `GET /api/agnet/health` 或 `/health` 返回 healthy。
1. Manager 调 `GET /api/agent/health` 或 `/health` 返回 healthy。
2. Manager 调 Runtime create，拿到 `runtime_deployment_id` 和 `swarm_id`。
3. Runtime 回调 `deployment.status_changed`，Manager timeline 可见。
4. Runtime 回调 `task.claimed`、`task.completed`，Manager timeline 可见。
docs/integration/agnet-platform-request-contract.md → docs/integration/agent-platform-request-contract.md
+74 -74
View File
@@ -1,15 +1,15 @@
# Manager → Agnet 平台接口参数文档
# Manager → Agent 平台接口参数文档
**版本**: v0.3（P1/P5 联调契约）
**生效日期**: 2026-05-03
**状态**: 联调准备；当前仓库提供 Manager 侧最小验证端点，生产 Agnet 平台部署尚未在本文档中宣称完成。
**方向**: Heicode Manager 主动请求 Agnet 平台；Agnet 平台返回部署、日志、监控与审计状态。
**范围**: 创建/停止子 Agent 部署、查询部署、获取事件/日志/监控快照、解析 SK 快照、查询审计日志，以及 Agnet 辅助 NewAPI 重建/部署的参数约定。
**状态**: 联调准备；当前仓库提供 Manager 侧最小验证端点，生产 Agent 平台部署尚未在本文档中宣称完成。
**方向**: Heicode Manager 主动请求 Agent 平台；Agent 平台返回部署、日志、监控与审计状态。
**范围**: 创建/停止子 Agent 部署、查询部署、获取事件/日志/监控快照、解析 SK 快照、查询审计日志，以及 Agent 辅助 NewAPI 重建/部署的参数约定。
> 2026-05-04 边界修正：Manager 当前不把 `tenant/project` 作为产品、认证或扣费主轴。新请求应使用 `user_context.user_id`、`user_context.channel_id`、`resource_grants[].binding_scope`、`billing_context(newapi)` 和 `agent_runtime(agnet)`。本文中仍出现的 `tenant_id/project_id` 只表示旧字段兼容或历史接口命名，不应作为新功能设计依据。
> 2026-05-04 边界修正：Manager 当前不把 `tenant/project` 作为产品、认证或扣费主轴。新请求应使用 `user_context.user_id`、`user_context.channel_id`、`resource_grants[].binding_scope`、`billing_context(newapi)` 和 `agent_runtime(agent)`。本文中仍出现的 `tenant_id/project_id` 只表示旧字段兼容或历史接口命名，不应作为新功能设计依据。
**安全红线**: 请求体只允许传资源元数据、权限范围与 `secret_ref`/环境变量名；不得传明文密码、Token、私钥、连接串或云访问密钥。
> 本文档描述 Manager 对 Agnet 平台的出站集成契约。当前仓库中 `/api/agnet/*` 是 Manager 侧最小控制面/模拟端点，用于校验同一套 payload 结构；生产接入时，Manager 应将下列请求发送到 Agnet 平台网关。
> 本文档描述 Manager 对 Agent 平台的出站集成契约。当前仓库中 `/api/agent/*` 是 Manager 侧最小控制面/模拟端点，用于校验同一套 payload 结构；生产接入时，Manager 应将下列请求发送到 Agent 平台网关。
## 0. 概述
@@ -17,18 +17,18 @@
| 接口 | 用途 | 当前性质 |
|---|---|---|
| `POST /api/agnet/deployments` | 创建子 Agent/运维任务部署，含 NewAPI 重建/部署场景 | 必需 |
| `GET /api/agnet/deployments` | 查询部署列表 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}` | 查询单个部署详情 | 必需 |
| `POST /api/agnet/deployments/{deployment_id}/stop` | 停止部署或取消排队任务 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}/logs` | 拉取部署日志 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}/logs/stream` | 实时日志 SSE | 可选 |
| `GET /api/agnet/projects/{project_id}/dashboard-snapshot` | 资源作用域监控快照；路径名保留旧兼容，参数值按 `binding_scope` 解释 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}/metrics` | 单部署指标序列 | 建议 |
| `GET /api/agnet/deployments/{deployment_id}/events` | 部署事件 | 必需 |
| `GET /api/agnet/audit-logs` | 审计日志 | 必需 |
| `POST /api/agnet/sk-snapshots/resolve` | 触发 SK 快照解析 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}/sk-snapshots` | 查询 SK 快照 | 必需 |
| `POST /api/agent/deployments` | 创建子 Agent/运维任务部署，含 NewAPI 重建/部署场景 | 必需 |
| `GET /api/agent/deployments` | 查询部署列表 | 必需 |
| `GET /api/agent/deployments/{deployment_id}` | 查询单个部署详情 | 必需 |
| `POST /api/agent/deployments/{deployment_id}/stop` | 停止部署或取消排队任务 | 必需 |
| `GET /api/agent/deployments/{deployment_id}/logs` | 拉取部署日志 | 必需 |
| `GET /api/agent/deployments/{deployment_id}/logs/stream` | 实时日志 SSE | 可选 |
| `GET /api/agent/projects/{project_id}/dashboard-snapshot` | 资源作用域监控快照；路径名保留旧兼容，参数值按 `binding_scope` 解释 | 必需 |
| `GET /api/agent/deployments/{deployment_id}/metrics` | 单部署指标序列 | 建议 |
| `GET /api/agent/deployments/{deployment_id}/events` | 部署事件 | 必需 |
| `GET /api/agent/audit-logs` | 审计日志 | 必需 |
| `POST /api/agent/sk-snapshots/resolve` | 触发 SK 快照解析 | 必需 |
| `GET /api/agent/deployments/{deployment_id}/sk-snapshots` | 查询 SK 快照 | 必需 |
> 不在本文档范围：真实 Secret Store 写入、生产 SSH 登录、云账号授权回调、NewAPI 管理后台开放。生产部署动作只有实际执行并通过日志/监控/审计验证后，才能在报告中标记为“已部署”。
@@ -41,20 +41,20 @@
由部署环境配置，不写入仓库。例如：
```text
AGNET_PLATFORM_BASE_URL=https://agnet-platform.example.com
AGENT_PLATFORM_BASE_URL=https://agent-platform.example.com
```
联调环境建议使用独立域名或内网网关，示例不得包含真实凭据：
```text
AGNET_PLATFORM_BASE_URL=https://staging-agnet.example.com
MANAGER_SERVICE_TOKEN_SECRET_REF=azkv://heicode-kv.vault.azure.net/secrets/manager-service-agnet-platform-service-token
AGENT_PLATFORM_BASE_URL=https://staging-agent.example.com
MANAGER_SERVICE_TOKEN_SECRET_REF=azkv://heicode-kv.vault.azure.net/secrets/manager-service-agent-platform-service-token
```
完整路径示例：
```http
POST https://agnet-platform.example.com/api/agnet/deployments
POST https://agent-platform.example.com/api/agent/deployments
```
### 1.2 通用 Header
@@ -133,7 +133,7 @@ POST https://agnet-platform.example.com/api/agnet/deployments
### 2.1 Endpoint
```http
POST /api/agnet/deployments
POST /api/agent/deployments
```
### 2.2 请求体
@@ -164,11 +164,11 @@ POST /api/agnet/deployments
"quota_ref": "newapi_token_or_group_quota_ref"
},
"agent_runtime": {
"platform": "agnet",
"platform": "agent",
"agents": [
{
"role": "builder",
"model_ref": "agnet_model_profile_builder",
"model_ref": "agent_model_profile_builder",
"instance_count": 1
}
]
@@ -200,7 +200,7 @@ POST /api/agnet/deployments
],
"runtime_execution": {
"profile_id": "aks-codex-standard",
"cloud_principal_refs": ["principal://users/user_123/agnet-runtime"],
"cloud_principal_refs": ["principal://users/user_123/agent-runtime"],
"network_policy_ref": "netpol://bindings/repo_default/restricted-egress"
},
"sk_access_policy": {
@@ -272,15 +272,15 @@ POST /api/agnet/deployments
| 字段 | 类型 | 必填 | 约束/说明 |
|---|---|---:|---|
| `intent_id` | string | 是 | Manager 侧意图 ID，用于幂等、审计和追踪。 |
| `template_hint` | string | 是 | Agnet 平台选择编排模板的提示，如 `manager-resource-binding`。 |
| `template_hint` | string | 是 | Agent 平台选择编排模板的提示，如 `manager-resource-binding`。 |
| `objective` | string | 是 | 本次部署目标，应是自然语言但不能含密钥。 |
| `risk_level` | enum | 是 | `low` / `medium` / `high`。高风险必须携带客户端审批证据；缺失或不匹配时只能只读或拒绝执行。 |
| `budget.max_tokens` | int | 是 | 当前策略上限建议不超过 `500000`。 |
| `budget.max_cost_usd` | number | 是 | 当前策略上限建议不超过 `200`。 |
| `budget.max_duration_sec` | int | 是 | 当前策略上限建议不超过 `86400`。 |
| `user_context` | object | 建议 | 登录用户上下文，优先使用 Heicode/Agnet 登录返回的 `user.id`/`channelId`。 |
| `billing_context` | object | 条件 | NewAPI 扣费上下文；只表达 user/token/group/quota 映射，不表达子 Agnet 模型或实例数。 |
| `agent_runtime` | object | 条件 | Agnet 平台运行时上下文；表达子 Agnet 角色、模型 profile 和实例数，不承载 NewAPI key 或扣费对象。 |
| `user_context` | object | 建议 | 登录用户上下文，优先使用 Heicode/Agent 登录返回的 `user.id`/`channelId`。 |
| `billing_context` | object | 条件 | NewAPI 扣费上下文；只表达 user/token/group/quota 映射，不表达子 Agent 模型或实例数。 |
| `agent_runtime` | object | 条件 | Agent 平台运行时上下文；表达子 Agent 角色、模型 profile 和实例数，不承载 NewAPI key 或扣费对象。 |
| `constraints.allowed_model_ids` | string[] | 否 | agent 的 `default_model_id` 如填写，必须在此列表内。 |
| `metadata.tenant_id` | string | 否 | 旧兼容字段；新实现不得作为产品租户边界。 |
| `metadata.project_id` | string | 否 | 旧兼容字段；新实现不得作为项目账本边界。 |
@@ -297,10 +297,10 @@ POST /api/agnet/deployments
| `billing_context.newapi_user_ref` | string | 否 | NewAPI 用户映射引用，不是 NewAPI key。 |
| `billing_context.newapi_group` | string | 否 | NewAPI Group 映射，用于额度或策略选择。 |
| `billing_context.quota_ref` | string | 否 | Token 或 Group 额度引用，不得包含真实 Token 原文。 |
| `agent_runtime.platform` | enum | 条件 | 当前只允许 `agnet`。 |
| `agent_runtime.platform` | enum | 条件 | 当前只允许 `agent`。 |
| `agent_runtime.agents[].role` | string | 条件 | 必须匹配 `agents[].role_template`。 |
| `agent_runtime.agents[].model_ref` | string | 条件 | Agnet 平台模型 profile 引用；不是 NewAPI 扣费字段。 |
| `agent_runtime.agents[].instance_count` | int | 条件 | 子 Agnet 实例数量，必须大于 0。 |
| `agent_runtime.agents[].model_ref` | string | 条件 | Agent 平台模型 profile 引用；不是 NewAPI 扣费字段。 |
| `agent_runtime.agents[].instance_count` | int | 条件 | 子 Agent 实例数量，必须大于 0。 |
#### agents[]
@@ -330,7 +330,7 @@ POST /api/agnet/deployments
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `profile_id` | string | 条件必填 | Agnet 平台运行规格，如 AKS profile。 |
| `profile_id` | string | 条件必填 | Agent 平台运行规格，如 AKS profile。 |
| `cloud_principal_refs` | string[] | 否 | 运行身份引用，不是明文凭据。 |
| `network_policy_ref` | string | 否 | 网络策略引用，用于限制出站/入站。 |
@@ -354,9 +354,9 @@ POST /api/agnet/deployments
| `secret_ref` | string | 条件必填 | `git`、`sk`、`cloud_account`、`cloud_resource` 必填；`project_doc` 可为空。 |
| `audit` | object<string,string> | 否 | 审计上下文；不得含密钥字段。 |
### 2.4 典型场景：Agnet 辅助 NewAPI 重建/部署
### 2.4 典型场景：Agent 辅助 NewAPI 重建/部署
当 Manager 需要让 Agnet 平台协助重建或部署 NewAPI 时，仍使用 `POST /api/agnet/deployments`，但必须把任务表达为受控运维部署，不得把 VM、PostgreSQL、Redis、NewAPI key 等真实凭据写入请求体。
当 Manager 需要让 Agent 平台协助重建或部署 NewAPI 时，仍使用 `POST /api/agent/deployments`，但必须把任务表达为受控运维部署，不得把 VM、PostgreSQL、Redis、NewAPI key 等真实凭据写入请求体。
请求体示例：
@@ -394,7 +394,7 @@ POST /api/agnet/deployments
"default_model_id": "gpt-5.4",
"runtime_execution": {
"profile_id": "aks-codex-ops",
"cloud_principal_refs": ["principal://users/user_123/agnet-ops"],
"cloud_principal_refs": ["principal://users/user_123/agent-ops"],
"network_policy_ref": "netpol://bindings/newapi-prod/ops-egress"
},
"resource_grants": [
@@ -458,7 +458,7 @@ POST /api/agnet/deployments
}
```
Agnet 平台返回的部署详情、日志、监控和审计中应至少能证明：构建版本/commit、服务重启结果、健康检查结果、资源使用情况、失败回滚状态。未执行真实 SSH/生产动作时，只能返回 `phase=planned` 或 `phase=pending_approval`。
Agent 平台返回的部署详情、日志、监控和审计中应至少能证明：构建版本/commit、服务重启结果、健康检查结果、资源使用情况、失败回滚状态。未执行真实 SSH/生产动作时，只能返回 `phase=planned` 或 `phase=pending_approval`。
NewAPI 重建/部署的完成判定必须同时满足：
@@ -494,7 +494,7 @@ NewAPI 重建/部署的完成判定必须同时满足：
### 3.1 查询部署列表
```http
GET /api/agnet/deployments?user_id=user_123&binding_scope=repo_default
GET /api/agent/deployments?user_id=user_123&binding_scope=repo_default
```
返回：
@@ -520,15 +520,15 @@ GET /api/agnet/deployments?user_id=user_123&binding_scope=repo_default
### 3.2 查询单个部署
```http
GET /api/agnet/deployments/{deployment_id}
GET /api/agent/deployments/{deployment_id}
```
返回应包含部署状态、phase、agent_instances、最近错误、资源授权摘要和预算消耗摘要。Agnet 平台返回时必须对 `secret_ref` 以外的凭据信息做脱敏；原则上不返回任何明文凭据。
返回应包含部署状态、phase、agent_instances、最近错误、资源授权摘要和预算消耗摘要。Agent 平台返回时必须对 `secret_ref` 以外的凭据信息做脱敏；原则上不返回任何明文凭据。
### 3.3 停止部署
```http
POST /api/agnet/deployments/{deployment_id}/stop
POST /api/agent/deployments/{deployment_id}/stop
```
请求体可为空；如需原因可扩展：
@@ -565,12 +565,12 @@ POST /api/agnet/deployments/{deployment_id}/stop
---
## 4. 日志接口（Manager 拉取 Agnet 平台）
## 4. 日志接口（Manager 拉取 Agent 平台）
### 4.1 获取部署日志
```http
GET /api/agnet/deployments/{deployment_id}/logs?agent_instance_id=agi_abc123&stream=stdout&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
GET /api/agent/deployments/{deployment_id}/logs?agent_instance_id=agi_abc123&stream=stdout&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
```
Query：
@@ -609,14 +609,14 @@ Query：
日志要求：
- Agnet 平台必须在返回前完成密钥脱敏。
- Agent 平台必须在返回前完成密钥脱敏。
- `message` 不得包含密码、Token、私钥、连接串、云访问密钥。
- Manager 只保存必要摘要和审计索引；长日志建议落对象存储并设置保留期。
### 4.2 实时日志流（可选）
```http
GET /api/agnet/deployments/{deployment_id}/logs/stream?agent_instance_id=agi_abc123
GET /api/agent/deployments/{deployment_id}/logs/stream?agent_instance_id=agi_abc123
Accept: text/event-stream
```
@@ -646,12 +646,12 @@ SSE 事件类型：
---
## 5. 监控接口（Manager 拉取 Agnet 平台）
## 5. 监控接口（Manager 拉取 Agent 平台）
### 5.1 项目监控快照
```http
GET /api/agnet/projects/{binding_scope}/dashboard-snapshot?window=1h
GET /api/agent/projects/{binding_scope}/dashboard-snapshot?window=1h
```
响应：
@@ -689,7 +689,7 @@ GET /api/agnet/projects/{binding_scope}/dashboard-snapshot?window=1h
### 5.2 单部署监控快照（建议平台实现）
```http
GET /api/agnet/deployments/{deployment_id}/metrics?window=15m&step=60s
GET /api/agent/deployments/{deployment_id}/metrics?window=15m&step=60s
```
响应：
@@ -725,7 +725,7 @@ GET /api/agnet/deployments/{deployment_id}/metrics?window=15m&step=60s
### 6.1 部署事件
```http
GET /api/agnet/deployments/{deployment_id}/events?since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
GET /api/agent/deployments/{deployment_id}/events?since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
```
响应：
@@ -768,7 +768,7 @@ GET /api/agnet/deployments/{deployment_id}/events?since=2026-05-02T00:00:00Z&lim
### 6.2 审计日志
```http
GET /api/agnet/audit-logs?user_id=user_123&binding_scope=repo_default&actor=agnet_control_plane&action=deployment.accepted&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
GET /api/agent/audit-logs?user_id=user_123&binding_scope=repo_default&actor=agent_control_plane&action=deployment.accepted&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
```
响应：
@@ -780,7 +780,7 @@ GET /api/agnet/audit-logs?user_id=user_123&binding_scope=repo_default&actor=agne
"items": [
{
"audit_id": "aud_001",
"actor": "agnet_control_plane",
"actor": "agent_control_plane",
"action": "deployment.accepted",
"resource": "dep_abc123",
"user_id": "user_123",
@@ -805,7 +805,7 @@ GET /api/agnet/audit-logs?user_id=user_123&binding_scope=repo_default&actor=agne
### 7.1 触发解析/刷新
```http
POST /api/agnet/sk-snapshots/resolve
POST /api/agent/sk-snapshots/resolve
```
请求：
@@ -842,7 +842,7 @@ POST /api/agnet/sk-snapshots/resolve
### 7.2 查询部署 SK 快照
```http
GET /api/agnet/deployments/{deployment_id}/sk-snapshots
GET /api/agent/deployments/{deployment_id}/sk-snapshots
```
Query：
@@ -893,17 +893,17 @@ Query：
## 8. 安全校验清单
Manager 发给 Agnet 平台前必须执行：
Manager 发给 Agent 平台前必须执行：
1. `user_id`、`binding_scope`、`target_role` 与部署计划一致。
2. 凭据型资源只传 `secret_ref`，不传明文凭据。
3. `metadata`、`constraints`、`audit` 的 key 中不得出现 `password`、`token`、`secret`、`private_key`、`access_key`、`credential` 等敏感词。
4. `repo_url` 不得包含用户名、密码或访问 Token。
5. `permission_scope` 使用最小权限；生产写操作必须携带客户端审批记录，Agnet 平台不得自行补批。
6. 高风险操作（生产部署、云资源修改、删除、扩容）必须设置 `risk_level=high`，Agnet 平台执行前只校验客户端审批证据。
5. `permission_scope` 使用最小权限；生产写操作必须携带客户端审批记录，Agent 平台不得自行补批。
6. 高风险操作（生产部署、云资源修改、删除、扩容）必须设置 `risk_level=high`，Agent 平台执行前只校验客户端审批证据。
7. 所有日志/事件/审计返回给 Manager 前必须脱敏。
Agnet 平台不承担高危操作审批主体。审批只发生在客户端；Agnet 平台只能在执行前校验以下字段和策略是否一致：
Agent 平台不承担高危操作审批主体。审批只发生在客户端；Agent 平台只能在执行前校验以下字段和策略是否一致：
| 校验项 | 要求 |
|---|---|
@@ -914,14 +914,14 @@ Agnet 平台不承担高危操作审批主体。审批只发生在客户端；Ag
| `risk_level` | 高危资源写入、生产部署、云资源修改、删除和扩容必须为 `high`。 |
| 策略 | 平台 policy、Key Vault 访问策略、Kubernetes/Workload Identity、网络策略和最小权限约束均必须允许本次动作。 |
任一校验不通过时，Agnet 平台应返回 `POLICY_REJECTED` 或 `FORBIDDEN_SCOPE`，不得发起额外批准流程。
任一校验不通过时，Agent 平台应返回 `POLICY_REJECTED` 或 `FORBIDDEN_SCOPE`，不得发起额外批准流程。
### 8.1 字段级约束速查
| 对象/接口 | 必填最小集合 | 禁止内容 |
|---|---|---|
| `orchestration_plan` | `intent_id`、`template_hint`、`objective`、`risk_level`、`budget`、`user_context`、`billing_context`、`agent_runtime`、`metadata.correlation_id`、`agents[]` | 密钥、连接串、真实主机登录密码、NewAPI key 原文。 |
| `agents[]` | `role_template`、`goal` | 让子 Agent 绕过 Manager/Agnet 审计的指令。 |
| `agents[]` | `role_template`、`goal` | 让子 Agent 绕过 Manager/Agent 审计的指令。 |
| `runtime_execution` | 任一字段存在时 `profile_id` 必填 | 明文 kubeconfig、SSH key、云访问密钥。 |
| `resource_grants[]` | `grant_id`、`resource_id`、`resource_type`、`user_id`、`binding_scope`、`target_role`、`target_agent_ref`、`permission_scope`、`status` | 明文 `password`、`token`、`private_key`、`access_key`、`credential`、数据库 DSN。 |
| 日志/事件/审计返回 | `request_id` 或 `correlation_id`，以及发生时间 | 未脱敏命令行、环境变量 dump、密钥片段。 |
@@ -934,7 +934,7 @@ Agnet 平台不承担高危操作审批主体。审批只发生在客户端；Ag
- `risk_level=high` 的生产运维任务包含 `approval_id` 和回滚引用。
- 日志、事件、监控、审计接口都能通过 `correlation_id` 串联。
- NewAPI 重建/部署只在实际执行并通过健康检查后标记为已部署；未执行时状态只能是 `planned`、`pending_approval`、`accepted` 或 `running`。
- Manager 本地 `/api/agnet/*` 占位端点通过 payload 校验不等于生产 Agnet 平台已上线。
- Manager 本地 `/api/agent/*` 占位端点通过 payload 校验不等于生产 Agent 平台已上线。
---
@@ -944,18 +944,18 @@ Agnet 平台不承担高危操作审批主体。审批只发生在客户端；Ag
| Manager 路由 | 用途 |
|---|---|
| `POST /api/agnet/deployments` | 校验并接受 orchestration_plan。 |
| `GET /api/agnet/deployments` | 按 user/binding scope 查询部署。 |
| `GET /api/agnet/deployments/:deployment_id` | 查询部署详情。 |
| `POST /api/agnet/deployments/:deployment_id/stop` | 停止部署。 |
| `GET /api/agnet/deployments/:deployment_id/logs` | 查询脱敏日志占位/联调日志。 |
| `GET /api/agnet/deployments/:deployment_id/metrics` | 查询单部署指标占位/联调指标。 |
| `GET /api/agnet/deployments/:deployment_id/events` | 查询事件。 |
| `POST /api/agnet/sk-snapshots/resolve` | 解析 SK 快照。 |
| `GET /api/agnet/deployments/:deployment_id/sk-snapshots` | 查询 SK 快照。 |
| `GET /api/agnet/projects/:project_id/dashboard-snapshot` | 资源作用域监控快照；路径名保留旧兼容。 |
| `GET /api/agnet/audit-logs` | 审计日志。 |
| `POST /api/agent/deployments` | 校验并接受 orchestration_plan。 |
| `GET /api/agent/deployments` | 按 user/binding scope 查询部署。 |
| `GET /api/agent/deployments/:deployment_id` | 查询部署详情。 |
| `POST /api/agent/deployments/:deployment_id/stop` | 停止部署。 |
| `GET /api/agent/deployments/:deployment_id/logs` | 查询脱敏日志占位/联调日志。 |
| `GET /api/agent/deployments/:deployment_id/metrics` | 查询单部署指标占位/联调指标。 |
| `GET /api/agent/deployments/:deployment_id/events` | 查询事件。 |
| `POST /api/agent/sk-snapshots/resolve` | 解析 SK 快照。 |
| `GET /api/agent/deployments/:deployment_id/sk-snapshots` | 查询 SK 快照。 |
| `GET /api/agent/projects/:project_id/dashboard-snapshot` | 资源作用域监控快照；路径名保留旧兼容。 |
| `GET /api/agent/audit-logs` | 审计日志。 |
生产对接时，Manager 应把相同契约的请求发送给 Agnet 平台；本地 Manager 端点仅作为最小验证与控制面占位，不代表所有日志/监控平台能力已完整实现。
生产对接时，Manager 应把相同契约的请求发送给 Agent 平台；本地 Manager 端点仅作为最小验证与控制面占位，不代表所有日志/监控平台能力已完整实现。
当前本地 `logs` 与 `metrics` 端点只返回脱敏占位/联调数据，用于验证 Manager ↔ Agnet payload、路由和验收流程。生产级实时日志流 `GET /api/agnet/deployments/{deployment_id}/logs/stream` 仍属于 Agnet 平台能力；Manager 不得把“本地占位通过”误报为“生产日志/监控已上线”。
当前本地 `logs` 与 `metrics` 端点只返回脱敏占位/联调数据，用于验证 Manager ↔ Agent payload、路由和验收流程。生产级实时日志流 `GET /api/agent/deployments/{deployment_id}/logs/stream` 仍属于 Agent 平台能力；Manager 不得把“本地占位通过”误报为“生产日志/监控已上线”。
docs/integration/heicode-desktop-sub-agile-api.md
+70 -70
View File
@@ -45,7 +45,7 @@ Manager 生产地址：`https://code.xinghanlab.com`
重要修正：
1. 桌面客户端不要再使用 `agnet-model-builder`、`agnet-model-reviewer`、`agnet-model-product` 这类占位模型名。生产 NewAPI 没有这些模型，会返回 `No available channel for model ...`。
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`，并优先展示可下载的业务交付物。
@@ -56,7 +56,7 @@ Manager 生产地址：`https://code.xinghanlab.com`
桌面客户端负责用户主体验：输入想法、回答追问、持续推进任务、查看子环节反馈、处理高危审批、接收交付结果。
Manager 负责辅助控制面：任务草稿桥接、资源/权限、Agnet deployment、状态/timeline/artifact/SK 查询、审批记录和短期凭证 lease。
Manager 负责辅助控制面：任务草稿桥接、资源/权限、Agent deployment、状态/timeline/artifact/SK 查询、审批记录和短期凭证 lease。
本文只描述普通 sub 敏捷流程，不包含蜂群 task graph、claim、heartbeat、handoff 等蜂群模式能力。
@@ -67,7 +67,7 @@ Manager 负责辅助控制面：任务草稿桥接、资源/权限、Agnet deplo
| API 前缀 | 用途 | 认证 |
|---|---|---|
| `/api/heicode-auth/api/user/tasks/*` | HeicodeTask 任务编排代理，创建任务、追问、查询任务 | V2 加密 body + `Authorization: Bearer <heicode_access_token>` |
| `/api/agnet/user/*` | Manager 用户态 Agnet 控制面，deployment、timeline、artifact、审批 | V2 加密 body；未加密 Web 控制台请求继续使用 Manager session + `New-Api-User` |
| `/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 |
@@ -79,7 +79,7 @@ Manager 负责辅助控制面：任务草稿桥接、资源/权限、Agnet deplo
| API 前缀 | V2 加密 body | 说明 |
|---|---|---|
| `/api/agnet/user/*` | 支持 | Manager 解密并校验设备签名后，按当前设备对应用户执行 |
| `/api/agent/user/*` | 支持 | Manager 解密并校验设备签名后，按当前设备对应用户执行 |
| `/api/swarms` | 支持 | Manager 解密并校验设备签名后，按当前设备对应用户创建蜂群/Runtime adapter deployment |
| `/api/heicode-auth/*` | 支持 | Manager 解密并校验设备签名后，把明文 body 代理给上游 HeicodeTask 服务；仍需携带 `heicode_access_token` |
| 浏览器后台普通页面请求 | 兼容未加密 JSON | 不影响现有 Manager Web 控制台 |
@@ -127,14 +127,14 @@ Authorization: Bearer <heicode_access_token>
客户端实现要求：
1. sub 流程调用不要新增一套加密协议，直接复用模型调用的 `encryptedFetch` / V2 设备签名实现。
2. `aad` 和 `canonical` 中的 `path_with_query` 必须是 Manager 实际收到的 path，例如 `/api/agnet/user/tasks/task-1/deployment-draft`，不能把 origin 写进去。
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/agnet/user/*` 或 `/api/swarms` 时必须带：
未加密 Web 控制台请求调用 `/api/agent/user/*` 或 `/api/swarms` 时必须带：
```http
Cookie: session=<manager-session>
@@ -145,7 +145,7 @@ Accept: application/json
`New-Api-User` 必须等于当前登录用户 ID，否则会返回未授权。
使用 V2 加密 body 时，`/api/agnet/user/*` 和 `/api/swarms` 不依赖浏览器 session cookie，也不需要 `New-Api-User`；Manager 会从设备绑定 token 中解析用户身份。为兼容当前 Web 控制台，未加密请求仍按 session cookie + `New-Api-User` 处理。
使用 V2 加密 body 时，`/api/agent/user/*` 和 `/api/swarms` 不依赖浏览器 session cookie，也不需要 `New-Api-User`；Manager 会从设备绑定 token 中解析用户身份。为兼容当前 Web 控制台，未加密请求仍按 session cookie + `New-Api-User` 处理。
### 2.4 蜂群入口加密边界
@@ -153,8 +153,8 @@ Accept: application/json
| 接口 | 所属模式 | 加密要求 |
|---|---|---|
| `POST /api/agnet/user/tasks/{task_id}/deployment-draft` | 普通 sub 敏捷 | V2 body 加密 |
| `POST /api/agnet/user/deployments` | 普通 sub 敏捷 | V2 body 加密 |
| `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 等字段以单独蜂群对接文档为准。
@@ -190,8 +190,8 @@ Accept: application/json
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/agnet/user/tasks/{task_id}/deployment-draft
5. 创建 Manager deployment：POST /api/agnet/user/deployments
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 代理接口下载
@@ -205,14 +205,14 @@ Accept: application/json
客户端展示普通 sub 结果时，不能只看 deployment `status=completed`。Manager 已提供只读诊断接口，用来识别 Runtime 是否真的完成、是否有 failed agent、是否只返回兜底摘要 artifact。
```http
GET /api/agnet/user/deployments/{deployment_id}/runtime-diagnostics
GET /api/agent/user/deployments/{deployment_id}/runtime-diagnostics
```
返回核心字段：
| 字段 | 说明 |
|---|---|
| `runtime_mode` | `agnet` 表示普通 sub Runtime；`swarm` 表示蜂群 Runtime |
| `runtime_mode` | `agent` 表示普通 sub Runtime；`swarm` 表示蜂群 Runtime |
| `runtime_swarm_id` / `runtime_deployment_id` | Manager 保存的 Runtime 映射 |
| `data_source` | 当前诊断来源，正常为 `runtime_status` |
| `status` / `phase` | Runtime 直接返回的状态和阶段 |
@@ -235,7 +235,7 @@ GET /api/agnet/user/deployments/{deployment_id}/runtime-diagnostics
1. deployment detail / timeline / artifacts 仍按原接口展示。
2. 若 `warnings` 包含 `runtime_summary_artifact_only`，需要提示“当前没有最终交付产物，请查看运行日志/等待 Runtime 修复”。
3. 若 `runtime_mode=agnet`，按普通 sub 敏捷展示；若 `runtime_mode=swarm`，按蜂群模式展示任务图/Agent 编队，不能混用两套文案。
3. 若 `runtime_mode=agent`，按普通 sub 敏捷展示；若 `runtime_mode=swarm`，按蜂群模式展示任务图/Agent 编队，不能混用两套文案。
4. 该接口只读，失败时不应中断已有 timeline/artifact 展示。
### 3.2 Artifact 完整内容下载
@@ -245,13 +245,13 @@ GET /api/agnet/user/deployments/{deployment_id}/runtime-diagnostics
列表：
```http
GET /api/agnet/user/deployments/{deployment_id}/artifacts
GET /api/agent/user/deployments/{deployment_id}/artifacts
```
下载：
```http
GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content
GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content
```
Manager 行为：
@@ -339,26 +339,26 @@ function classifyArtifact(item: Artifact, content: string, contentType?: string)
| Manager 版本 | `1.4.19` |
| Agent Manager Runtime | `http://20.212.121.126` |
| Runtime health | `healthy` |
| Manager callback | `https://code.xinghanlab.com/api/agnet/callbacks/swarm-events` |
| Manager callback | `https://code.xinghanlab.com/api/agent/callbacks/swarm-events` |
已验证成功的链路：
```text
Manager 登录
-> /api/user/self
-> /api/agnet/runtime/health
-> /api/agnet/user/tasks/{task_id}/deployment-draft
-> /api/agnet/user/deployments
-> /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/agnet/user/deployments/{deployment_id}
-> /api/agnet/user/deployments/{deployment_id}/metrics
-> /api/agnet/user/deployments/{deployment_id}/events
-> /api/agnet/user/deployments/{deployment_id}/logs
-> /api/agnet/user/deployments/{deployment_id}/artifacts
-> /api/agnet/user/deployments/{deployment_id}/sk-snapshots
-> /api/agnet/user/deployments/{deployment_id}/timeline
-> /api/agnet/user/deployments/{deployment_id}/stop
-> /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：
@@ -431,7 +431,7 @@ Manager 登录
客户端处理：
- 保存 `data.id`。
- 后续 `/api/agnet/user/*` 请求带 `New-Api-User: <id>`。
- 后续 `/api/agent/user/*` 请求带 `New-Api-User: <id>`。
## 5. HeicodeTask 任务编排
@@ -594,11 +594,11 @@ Authorization: Bearer <heicode_access_token>
- `status=awaiting_approval`：轮询审批接口。
- `status=completed/failed/paused`：停止高频轮询。
## 6. 从任务生成 Agnet Deployment Draft
## 6. 从任务生成 Agent Deployment Draft
### `POST /api/agnet/user/tasks/{task_id}/deployment-draft`
### `POST /api/agent/user/tasks/{task_id}/deployment-draft`
把 HeicodeTask 快照转换成 Manager 可创建的 Agnet orchestration plan。
把 HeicodeTask 快照转换成 Manager 可创建的 Agent orchestration plan。
生产已验证：客户端只要能提供 task snapshot，就可以不依赖 Manager 再去拉 task，直接调用本接口生成 draft。
@@ -685,7 +685,7 @@ Authorization: Bearer <heicode_access_token>
| `sub_mode` | string | 是 | `agile` 或 `waterfall`，桌面客户端默认传 `agile` |
| `binding_scope` | string | 否 | 建议 `task-<task_id>` |
| `role_templates` | string[] | 否 | 默认 `["backend"]` |
| `default_model_id` | string | 否 | 子 Agnet 默认运行模型；生产默认建议 `claude-sonnet-4-6` |
| `default_model_id` | string | 否 | 子 Agent 默认运行模型；生产默认建议 `claude-sonnet-4-6` |
| `budget` | object | 否 | 不传使用默认预算 |
| `resource_grants` | array | 否 | 不传时 Manager 生成只读 task context grant |
@@ -717,7 +717,7 @@ Authorization: Bearer <heicode_access_token>
"newapi_group": "default"
},
"agent_runtime": {
"platform": "agnet",
"platform": "agent",
"agents": [
{
"role": "backend",
@@ -747,7 +747,7 @@ Authorization: Bearer <heicode_access_token>
## 7. 创建 Manager Deployment
### `POST /api/agnet/user/deployments`
### `POST /api/agent/user/deployments`
使用上一步 `orchestration_plan` 创建 Manager deployment。
@@ -783,7 +783,7 @@ Authorization: Bearer <heicode_access_token>
"newapi_group": "default"
},
"agent_runtime": {
"platform": "agnet",
"platform": "agent",
"agents": [
{
"role": "backend",
@@ -910,7 +910,7 @@ Authorization: Bearer <heicode_access_token>
### 8.1 列表
#### `GET /api/agnet/user/deployments`
#### `GET /api/agent/user/deployments`
响应：
@@ -938,13 +938,13 @@ Authorization: Bearer <heicode_access_token>
### 8.2 详情
#### `GET /api/agnet/user/deployments/{deployment_id}`
#### `GET /api/agent/user/deployments/{deployment_id}`
响应字段同列表单项，包含完整 `orchestration_plan`。
### 8.3 停止
#### `POST /api/agnet/user/deployments/{deployment_id}/stop`
#### `POST /api/agent/user/deployments/{deployment_id}/stop`
请求：
@@ -971,7 +971,7 @@ Authorization: Bearer <heicode_access_token>
### 9.1 Events
#### `GET /api/agnet/user/deployments/{deployment_id}/events`
#### `GET /api/agent/user/deployments/{deployment_id}/events`
用于展示 deployment 事件流。
@@ -996,7 +996,7 @@ Authorization: Bearer <heicode_access_token>
### 9.2 Logs
#### `GET /api/agnet/user/deployments/{deployment_id}/logs`
#### `GET /api/agent/user/deployments/{deployment_id}/logs`
用于展示最近日志。当前 Manager 未接真实 Runtime 时主要是审计日志。
@@ -1020,7 +1020,7 @@ Authorization: Bearer <heicode_access_token>
### 9.3 Metrics
#### `GET /api/agnet/user/deployments/{deployment_id}/metrics`
#### `GET /api/agent/user/deployments/{deployment_id}/metrics`
用于展示成本、耗时、token、资源指标。真实 Runtime 未接入时可能为空或为本地占位。
@@ -1039,7 +1039,7 @@ Authorization: Bearer <heicode_access_token>
### 9.4 Artifacts
#### `GET /api/agnet/user/deployments/{deployment_id}/artifacts`
#### `GET /api/agent/user/deployments/{deployment_id}/artifacts`
查询中间交付物和最终交付物摘要。注意：列表接口只返回摘要和引用，不能证明代码内容有效；客户端需要按需调用 content 接口并按“Artifact 展示和有效性判断”继续分类。
@@ -1070,7 +1070,7 @@ Authorization: Bearer <heicode_access_token>
}
```
#### `GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content`
#### `GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content`
读取完整产物正文。客户端必须通过该接口判断产物是否真的是代码，而不是只看 `artifact_type`。
@@ -1113,7 +1113,7 @@ summary-only 示例片段：
### 9.5 SK Snapshots
#### `GET /api/agnet/user/deployments/{deployment_id}/sk-snapshots`
#### `GET /api/agent/user/deployments/{deployment_id}/sk-snapshots`
查询本轮任务使用的 SK 快照。
@@ -1147,7 +1147,7 @@ summary-only 示例片段：
### 9.6 Timeline
#### `GET /api/agnet/user/deployments/{deployment_id}/timeline`
#### `GET /api/agent/user/deployments/{deployment_id}/timeline`
聚合审计事件、Runtime callback、artifact、SK snapshot。桌面客户端推荐优先使用这个接口渲染“当前子环节进度”。
@@ -1206,7 +1206,7 @@ summary-only 示例片段：
### 10.1 查询待审批
#### `GET /api/agnet/approvals?status=pending&deployment_id={deployment_id}`
#### `GET /api/agent/approvals?status=pending&deployment_id={deployment_id}`
查询参数：
@@ -1236,7 +1236,7 @@ summary-only 示例片段：
"requires_credential": true,
"credential_lease_id": "",
"status": "pending",
"requested_by": "agnet-runtime",
"requested_by": "agent-runtime",
"request_reason": "需要写入功能分支",
"ttl_seconds": 900,
"expires_at": 1779850900000,
@@ -1249,7 +1249,7 @@ summary-only 示例片段：
### 10.2 同意审批
#### `POST /api/agnet/approvals/{approval_id}/approve`
#### `POST /api/agent/approvals/{approval_id}/approve`
请求：
@@ -1270,7 +1270,7 @@ summary-only 示例片段：
"credential_lease_id": "lease_xxx",
"credential_lease": {
"lease_id": "lease_xxx",
"credential_ref": "lease://agnet/lease_xxx",
"credential_ref": "lease://agent/lease_xxx",
"status": "active",
"expires_at": 1779850900000
}
@@ -1282,7 +1282,7 @@ summary-only 示例片段：
### 10.3 拒绝审批
#### `POST /api/agnet/approvals/{approval_id}/reject`
#### `POST /api/agent/approvals/{approval_id}/reject`
请求：
@@ -1307,7 +1307,7 @@ summary-only 示例片段：
### 10.4 查询 lease
#### `GET /api/agnet/credential-leases?status=active&deployment_id={deployment_id}`
#### `GET /api/agent/credential-leases?status=active&deployment_id={deployment_id}`
响应：
@@ -1318,7 +1318,7 @@ summary-only 示例片段：
"items": [
{
"lease_id": "lease_xxx",
"credential_ref": "lease://agnet/lease_xxx",
"credential_ref": "lease://agent/lease_xxx",
"approval_id": "appr_xxx",
"deployment_id": "dep_464a08b7b751",
"resource_id": "res_git_main",
@@ -1334,7 +1334,7 @@ summary-only 示例片段：
### 10.5 撤销 lease
#### `POST /api/agnet/credential-leases/{lease_id}/revoke`
#### `POST /api/agent/credential-leases/{lease_id}/revoke`
请求：
@@ -1358,9 +1358,9 @@ summary-only 示例片段：
## 11. 角色模板
### `GET /api/agnet/role-templates`
### `GET /api/agent/role-templates`
获取推荐子 Agnet 角色，桌面端可用于角色选择页。
获取推荐子 Agent 角色，桌面端可用于角色选择页。
响应：
@@ -1371,7 +1371,7 @@ summary-only 示例片段：
"items": [
{
"key": "backend",
"display_name": "Backend Agnet",
"display_name": "Backend Agent",
"summary": "实现后端接口、数据模型和服务逻辑",
"default_model": "gpt-5.4",
"default_permissions": ["repo:read", "repo:write"],
@@ -1382,7 +1382,7 @@ summary-only 示例片段：
}
```
> `default_model` 由 Manager 单一来源 `defaultAgnetModelID()` 提供（环境变量 `AGNET_DEFAULT_MODEL_ID`，默认生产已验证的 `gpt-5.4`）。Manager 不再回退 `agnet-model-<role>` 占位名；客户端如不指定 `default_model_id`，draft/runtime agent 会自动采用该单一默认值。
> `default_model` 由 Manager 单一来源 `defaultAgentModelID()` 提供（环境变量 `AGENT_DEFAULT_MODEL_ID`，默认生产已验证的 `gpt-5.4`）。Manager 不再回退 `agent-model-<role>` 占位名；客户端如不指定 `default_model_id`，draft/runtime agent 会自动采用该单一默认值。
## 12. 状态枚举
@@ -1393,12 +1393,12 @@ summary-only 示例片段：
| `draft` | 草稿 | 可继续编辑 |
| `configuring` | 等待回答追问 | 展示 followups |
| `running` | 可推进/运行中 | 创建 deployment 或展示 timeline |
| `awaiting_approval` | 等待审批 | 拉取 `/api/agnet/approvals` |
| `awaiting_approval` | 等待审批 | 拉取 `/api/agent/approvals` |
| `completed` | 完成 | 展示交付物 |
| `failed` | 失败 | 展示失败原因 |
| `paused` | 暂停 | 允许继续或停止 |
### Agnet Deployment.status
### Agent Deployment.status
| 状态 | 说明 |
|---|---|
@@ -1410,7 +1410,7 @@ summary-only 示例片段：
> 注意：`status` 由 Manager 接收 Runtime `deployment.status_changed` 后镜像写入。除上述规范值外，Runtime 若回传其他自定义状态字符串，Manager 会透传保存，客户端应对未知值做兜底（按非终态处理或显示原值）。
### Agnet Deployment.runtime_state
### Agent Deployment.runtime_state
| 状态 | 说明 |
|---|---|
@@ -1508,7 +1508,7 @@ while (current.status === 'configuring') {
const draft = await encryptedManagerRequest<Envelope<DeploymentDraft>>(
'POST',
`/api/agnet/user/tasks/${current.id}/deployment-draft`,
`/api/agent/user/tasks/${current.id}/deployment-draft`,
{
task: current,
sub_mode: 'agile',
@@ -1520,7 +1520,7 @@ const draft = await encryptedManagerRequest<Envelope<DeploymentDraft>>(
const deployment = await encryptedManagerRequest<Envelope<Deployment>>(
'POST',
'/api/agnet/user/deployments',
'/api/agent/user/deployments',
{ orchestration_plan: draft.data.orchestration_plan }
)
@@ -1528,13 +1528,13 @@ const deploymentId = deployment.data.deployment_id
setInterval(async () => {
const timeline = await manager.get<Envelope<DeploymentTimeline>>(
`/api/agnet/user/deployments/${deploymentId}/timeline`,
`/api/agent/user/deployments/${deploymentId}/timeline`,
{ headers: { 'New-Api-User': String(userId) } }
)
renderTimeline(timeline.data.timeline)
const approvals = await manager.get<Envelope<ApprovalList>>(
`/api/agnet/approvals?status=pending&deployment_id=${deploymentId}`,
`/api/agent/approvals?status=pending&deployment_id=${deploymentId}`,
{ headers: { 'New-Api-User': String(userId) } }
)
renderApprovals(approvals.data.items)
@@ -1542,13 +1542,13 @@ setInterval(async () => {
async function refreshSubDelivery(deploymentId: string) {
const diagnostics = await manager.get<Envelope<RuntimeDiagnostics>>(
`/api/agnet/user/deployments/${deploymentId}/runtime-diagnostics`,
`/api/agent/user/deployments/${deploymentId}/runtime-diagnostics`,
{ headers: { 'New-Api-User': String(userId) } }
)
renderRuntimeDiagnostics(diagnostics.data)
const artifacts = await manager.get<Envelope<ArtifactList>>(
`/api/agnet/user/deployments/${deploymentId}/artifacts`,
`/api/agent/user/deployments/${deploymentId}/artifacts`,
{ headers: { 'New-Api-User': String(userId) } }
)
renderArtifacts(artifacts.data.artifacts)
@@ -1558,7 +1558,7 @@ async function refreshSubDelivery(deploymentId: string) {
)
if (firstDeliverable) {
const content = await manager.get<string>(
`/api/agnet/user/deployments/${deploymentId}/artifacts/${firstDeliverable.artifact_id}/content`,
`/api/agent/user/deployments/${deploymentId}/artifacts/${firstDeliverable.artifact_id}/content`,
{
headers: { 'New-Api-User': String(userId) },
responseType: 'text',
@@ -1571,10 +1571,10 @@ async function refreshSubDelivery(deploymentId: string) {
兼容说明：
- 桌面客户端对 `POST` 等有 body 的 sub 请求走 V2 加密时，`/api/agnet/user/*` 不需要 `New-Api-User`，也不依赖浏览器 cookie。
- 桌面客户端对 `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 <heicode_access_token>`，该 token 只用于上游 HeicodeTask 认证。
- 如果客户端临时还没有接入 V2 加密，只能作为调试兼容路径使用 Manager session + `New-Api-User` 调 `/api/agnet/user/*`；正式桌面流程不要依赖该路径。
- 如果客户端临时还没有接入 V2 加密，只能作为调试兼容路径使用 Manager session + `New-Api-User` 调 `/api/agent/user/*`；正式桌面流程不要依赖该路径。
## 15. 当前生产注意事项
docs/integration/heicode-manager-swarm-runtime-env-template.md
+35 -35
View File
@@ -8,24 +8,24 @@
当 Runtime 提供正式 `POST /api/swarms` 时，Manager 建议配置：
```bash
AGNET_RUNTIME_ENABLED=true
AGNET_RUNTIME_ASYNC=false
AGNET_RUNTIME_BASE_URL=http://<runtime-host>
AGNET_RUNTIME_SERVICE_TOKEN=<service-token>
AGNET_RUNTIME_HEALTH_PATH=/api/agnet/health
AGNET_RUNTIME_CREATE_PATH=/api/swarms
AGNET_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGNET_RUNTIME_TIMEOUT_SECONDS=10
AGENT_RUNTIME_ENABLED=true
AGENT_RUNTIME_ASYNC=false
AGENT_RUNTIME_BASE_URL=http://<runtime-host>
AGENT_RUNTIME_SERVICE_TOKEN=<service-token>
AGENT_RUNTIME_HEALTH_PATH=/api/agent/health
AGENT_RUNTIME_CREATE_PATH=/api/swarms
AGENT_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGENT_RUNTIME_TIMEOUT_SECONDS=10
HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
AGNET_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
AGNET_CALLBACK_TOKEN=<callback-token>
AGENT_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agent/callbacks/swarm-events
AGENT_CALLBACK_TOKEN=<callback-token>
```
说明：
1. `AGNET_RUNTIME_SERVICE_TOKEN` 是 Manager 调 Runtime 的 Bearer token。
2. `AGNET_CALLBACK_TOKEN` 是 Runtime 回调 Manager 时放在 `X-Agnet-Service-Token` 的 token。
1. `AGENT_RUNTIME_SERVICE_TOKEN` 是 Manager 调 Runtime 的 Bearer token。
2. `AGENT_CALLBACK_TOKEN` 是 Runtime 回调 Manager 时放在 `X-Agent-Service-Token` 的 token。
3. 两个 token 可以不同，不要写进前端或日志。
4. 如果 Runtime 返回 `swarm_id`，Manager 会保存到 `runtime_swarm_id`。
5. 如果 Runtime 返回 `deployment_id`，Manager 会保存到 `runtime_deployment_id`。
@@ -35,18 +35,18 @@ AGNET_CALLBACK_TOKEN=<callback-token>
如果短期只用现有 Orchestrator 的 `/health` 和 `/tasks` 先做连通性测试，可以临时配置：
```bash
AGNET_RUNTIME_ENABLED=true
AGNET_RUNTIME_ASYNC=false
AGNET_RUNTIME_BASE_URL=http://52.139.240.116:8000
AGNET_RUNTIME_SERVICE_TOKEN=<optional-if-supported>
AGNET_RUNTIME_HEALTH_PATH=/health
AGNET_RUNTIME_CREATE_PATH=/tasks
AGNET_RUNTIME_STOP_PATH=/tasks/{runtime_deployment_id}/stop
AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGNET_RUNTIME_TIMEOUT_SECONDS=10
AGENT_RUNTIME_ENABLED=true
AGENT_RUNTIME_ASYNC=false
AGENT_RUNTIME_BASE_URL=http://52.139.240.116:8000
AGENT_RUNTIME_SERVICE_TOKEN=<optional-if-supported>
AGENT_RUNTIME_HEALTH_PATH=/health
AGENT_RUNTIME_CREATE_PATH=/tasks
AGENT_RUNTIME_STOP_PATH=/tasks/{runtime_deployment_id}/stop
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGENT_RUNTIME_TIMEOUT_SECONDS=10
HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
AGNET_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
AGNET_CALLBACK_TOKEN=<callback-token>
AGENT_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agent/callbacks/swarm-events
AGENT_CALLBACK_TOKEN=<callback-token>
```
注意：
@@ -60,9 +60,9 @@ AGNET_CALLBACK_TOKEN=<callback-token>
推荐使用 service token：
```http
POST /api/agnet/callbacks/swarm-events
X-Agnet-Service-Token: <callback-token>
X-Agnet-Event-Id: <event-id>
POST /api/agent/callbacks/swarm-events
X-Agent-Service-Token: <callback-token>
X-Agent-Event-Id: <event-id>
X-Correlation-ID: <correlation-id>
Content-Type: application/json
```
@@ -70,9 +70,9 @@ Content-Type: application/json
也支持 HMAC：
```http
X-Agnet-Event-Id: <event-id>
X-Agnet-Timestamp: <unix-ms>
X-Agnet-Signature: sha256=<hex>
X-Agent-Event-Id: <event-id>
X-Agent-Timestamp: <unix-ms>
X-Agent-Signature: sha256=<hex>
X-Correlation-ID: <correlation-id>
Content-Type: application/json
```
@@ -88,13 +88,13 @@ timestamp + "." + event_id + "." + raw_body
健康检查：
```bash
curl -sS "$AGNET_RUNTIME_BASE_URL$AGNET_RUNTIME_HEALTH_PATH"
curl -sS "$AGENT_RUNTIME_BASE_URL$AGENT_RUNTIME_HEALTH_PATH"
```
Manager 本地默认模拟链路：
```bash
curl -sS -X POST "https://code.xinghanlab.com/api/agnet/user/deployments/<manager-deployment-id>/simulate-events" \
curl -sS -X POST "https://code.xinghanlab.com/api/agent/user/deployments/<manager-deployment-id>/simulate-events" \
-H "Authorization: Bearer <manager-user-token>" \
-H "Content-Type: application/json" \
-d '{}'
@@ -105,10 +105,10 @@ curl -sS -X POST "https://code.xinghanlab.com/api/agnet/user/deployments/<manage
模拟 Runtime 回调 Manager：
```bash
curl -sS -X POST "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events" \
curl -sS -X POST "https://code.xinghanlab.com/api/agent/callbacks/swarm-events" \
-H "Content-Type: application/json" \
-H "X-Agnet-Service-Token: $AGNET_CALLBACK_TOKEN" \
-H "X-Agnet-Event-Id: evt-smoke-001" \
-H "X-Agent-Service-Token: $AGENT_CALLBACK_TOKEN" \
-H "X-Agent-Event-Id: evt-smoke-001" \
-H "X-Correlation-ID: corr-smoke-001" \
-d '{
"event_id": "evt-smoke-001",
docs/integration/manager-side-contract-patches.md
+4 -4
View File
@@ -21,9 +21,9 @@
## 2. §5 审计日志的敏感字段 redact
**当前现象**：mcp-server `/api/agnet/audit` 返回的条目里 `payload` 字段可能包含 token / secret 原文（按 §5 设计应在服务端 mask）。
**当前现象**：mcp-server `/api/agent/audit` 返回的条目里 `payload` 字段可能包含 token / secret 原文（按 §5 设计应在服务端 mask）。
**前端兜底**：`src/features/agnet-console/pages.tsx::maskIfSecret()` 做了第二层 mask（按 key 名匹配 `secret|token|password|api_key`）。
**前端兜底**：`src/features/agent-console/pages.tsx::maskIfSecret()` 做了第二层 mask（按 key 名匹配 `secret|token|password|api_key`）。
**建议**：mcp-server 在写审计或读出时统一 mask，前端可以删掉那一层。
@@ -41,13 +41,13 @@
**建议**：维持当前字段名即可。如果未来引入按模型聚合，建议另起 endpoint，不要在 `items` 里混。
## 5. §5 `/api/agnet/*` stub 数据
## 5. §5 `/api/agent/*` stub 数据
**当前**：mcp-server 内存 dict（按 §5.0 设计），无 agent-manager 真实转发。
**阻塞解除条件**：
- agent-manager 侧给 mcp-server 派发 service token
- mcp-server 把 stub 换成对 `http://20.212.121.126` 的真实转发；域名 `agent-manager.taijiagnet.com` 的 DNS / HTTPS 后续单独修复，不作为当前联调阻塞项
- mcp-server 把 stub 换成对 `http://20.212.121.126` 的真实转发；域名 `agent-manager.taijiagent.com` 的 DNS / HTTPS 后续单独修复，不作为当前联调阻塞项
Manager 前端已按 §5 契约消费，stub → 真实数据无需前端改动。
docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md
+17 -17
View File
@@ -27,14 +27,14 @@ Agent Manager 需要做的是：接收 Manager 生成的 deployment payload，
| 能力 | 状态 | 说明 |
|---|---|---|
| HeicodeTask -> deployment draft | 已完成 | `POST /api/agnet/user/tasks/{task_id}/deployment-draft` |
| 用户态 deployment 创建 | 已完成 | `POST /api/agnet/user/deployments` |
| 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/agnet/callbacks/swarm-events` |
| callback 接收 | 已完成 | `POST /api/agent/callbacks/swarm-events` |
| phase / timeline 聚合 | 已完成 | deployment timeline 聚合 audit、callback、artifact、SK |
| artifact 查询 | 已完成 | `GET /api/agnet/user/deployments/{deployment_id}/artifacts` |
| approval 查询/approve/reject | 已完成 | `/api/agnet/approvals` |
| 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` |
@@ -44,7 +44,7 @@ Agent Manager 需要做的是：接收 Manager 生成的 deployment payload，
| 任务 | 必需 | 原因 | 验收 |
|---|---:|---|---|
| 接收 Manager 创建请求 | 是 | Manager 会把普通 sub deployment 发送给 Agent Manager | `POST /api/agnet/deployments` 或配置的 create path 返回 2xx |
| 接收 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` |
@@ -60,13 +60,13 @@ Agent Manager 需要做的是：接收 Manager 生成的 deployment payload，
Manager 当前默认 create path：
```text
AGNET_RUNTIME_CREATE_PATH=/api/agnet/deployments
AGENT_RUNTIME_CREATE_PATH=/api/agent/deployments
```
如果 Agent Manager 统一使用 `/api/swarms`，Manager 也可以配置切过去。但普通 sub 敏捷模式建议先支持：
```http
POST /api/agnet/deployments
POST /api/agent/deployments
Authorization: Bearer <service_token>
X-User-ID: <manager_user_id>
X-Binding-Scope: <binding_scope>
@@ -114,7 +114,7 @@ Content-Type: application/json
"requires_user_approval": false
},
"agent_runtime": {
"platform": "agnet",
"platform": "agent",
"agents": [
{
"role": "backend",
@@ -163,8 +163,8 @@ Content-Type: application/json
}
],
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key",
"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",
@@ -260,7 +260,7 @@ Agent Manager 至少要支持以下阶段语义，并通过 callback 回写当
联调前可以先请求 Manager 当前接受的 callback schema：
```http
GET https://code.xinghanlab.com/api/agnet/callbacks/swarm-events/schema
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`。
@@ -364,7 +364,7 @@ POST /api/swarms/{swarm_id}/approvals/{approval_id}
如果普通 sub 不使用 `swarm_id`，可让 Manager 配置为：
```text
AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/agnet/deployments/{deployment_id}/approvals/{approval_id}
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/agent/deployments/{deployment_id}/approvals/{approval_id}
```
Runtime 需要接收：
@@ -380,7 +380,7 @@ Runtime 需要接收：
"resource_type": "git",
"target_role": "backend",
"requires_credential": true,
"credential_ref": "lease://agnet/lease_xxx",
"credential_ref": "lease://agent/lease_xxx",
"lease_id": "lease_xxx",
"lease_expires_at": 1779850900000
}
@@ -489,7 +489,7 @@ Agent Manager 回传 usage 时建议至少包含：
| 9 | Runtime 回调 completed/failed | Manager detail/timeline 显示终态 |
| 10 | Runtime 回调用量 | Manager 能看到 model token/cost 或 usage 摘要，且与 deployment/task/role/correlation 关联 |
| 11 | 查日志 | 不出现明文密钥，不丢 `correlation_id` |
| 12 | 生产路由复核 | `GET /api/agnet/callbacks/swarm-events/schema` 返回 200，用户态/后台态接口使用有效登录态通过 smoke |
| 12 | 生产路由复核 | `GET /api/agent/callbacks/swarm-events/schema` 返回 200，用户态/后台态接口使用有效登录态通过 smoke |
## 13. Agent Manager 不需要处理的内容
@@ -509,8 +509,8 @@ Agent Manager 回传 usage 时建议至少包含：
| 真实 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/agnet/deployments/...` |
| 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/agnet/callbacks/swarm-events/schema` 返回 404，需要重新上线或核对生产镜像/路由 |
| 生产 callback schema 路由 | Manager 部署/路由 | 本地代码和测试已覆盖，2026-05-28 生产公开访问 `/api/agent/callbacks/swarm-events/schema` 返回 404，需要重新上线或核对生产镜像/路由 |
| 无 body GET 的 V2 签名 | 客户端 + Manager | 这是客户端全链路无 cookie 的后续项，不阻塞 Agent Manager 创建/回调联调 |
docs/integration/蜂群模式-AgentManager对接任务清单.md
+20 -20
View File
@@ -14,10 +14,10 @@ Agent Manager / Swarm Runtime 当前还需要补齐或确认的是：真实创
| 能力 | 状态 | 说明 |
|---|---|---|
| Runtime 创建桥接 | 已完成 | Manager 可通过 `AGNET_RUNTIME_BASE_URL` + `AGNET_RUNTIME_CREATE_PATH` 调 Agent Manager |
| Runtime 停止桥接 | 已完成 | 默认 `POST /api/agnet/deployments/{deployment_id}/stop` |
| Runtime 创建桥接 | 已完成 | Manager 可通过 `AGENT_RUNTIME_BASE_URL` + `AGENT_RUNTIME_CREATE_PATH` 调 Agent Manager |
| Runtime 停止桥接 | 已完成 | 默认 `POST /api/agent/deployments/{deployment_id}/stop` |
| `/api/swarms` adapter | 已完成 | Manager 用户态入口已存在，后续可切真实 Runtime |
| callback 接收 | 已完成 | `POST /api/agnet/callbacks/swarm-events` |
| callback 接收 | 已完成 | `POST /api/agent/callbacks/swarm-events` |
| callback 鉴权 | 已完成 | 支持 service token 或 HMAC |
| callback 幂等 | 已完成 | 按 `event_id` / `idempotency_key` 去重 |
| task flow 校验 | 已完成 | `task.*` / `handoff.*` 缺关键字段会返回 `CALLBACK_SCHEMA_INVALID` |
@@ -58,11 +58,11 @@ Content-Type: application/json
Manager 当前可通过环境变量切换：
```text
AGNET_RUNTIME_BASE_URL=http://20.212.121.126
AGNET_RUNTIME_CREATE_PATH=/api/swarms
AGNET_RUNTIME_HEALTH_PATH=/api/agnet/health
AGNET_RUNTIME_STOP_PATH=/api/agnet/deployments/{deployment_id}/stop
AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGENT_RUNTIME_BASE_URL=http://20.212.121.126
AGENT_RUNTIME_CREATE_PATH=/api/swarms
AGENT_RUNTIME_HEALTH_PATH=/api/agent/health
AGENT_RUNTIME_STOP_PATH=/api/agent/deployments/{deployment_id}/stop
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
```
请求体核心形状：
@@ -116,8 +116,8 @@ AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_
}
],
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key",
"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",
"task.created",
@@ -180,9 +180,9 @@ Manager 解析规则：
统一入口：
```http
POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
X-Agnet-Service-Token: <callback_token>
X-Agnet-Event-Id: <event_id>
POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
X-Agent-Service-Token: <callback_token>
X-Agent-Event-Id: <event_id>
X-Correlation-ID: <correlation_id>
Content-Type: application/json
```
@@ -190,8 +190,8 @@ Content-Type: application/json
也支持 HMAC：
```http
X-Agnet-Timestamp: <unix_ms>
X-Agnet-Signature: sha256=<hex>
X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>
```
签名内容：
@@ -203,7 +203,7 @@ timestamp + "." + event_id + "." + raw_body
Agent Manager / 蜂群侧可以先拉取 Manager 当前接受的事件 schema：
```http
GET https://code.xinghanlab.com/api/agnet/callbacks/swarm-events/schema
GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
```
该接口不返回任何 token 或密钥，只返回事件类型、分类和必填字段，用于联调前核对 `task.*`、`handoff.*`、`artifact.created`、`approval.requested` 等 callback payload 是否符合 Manager 接收规则。
@@ -366,7 +366,7 @@ Content-Type: application/json
"risk_level": "high",
"requires_credential": true,
"user_id": "22",
"credential_ref": "lease://agnet/lease_xxx",
"credential_ref": "lease://agent/lease_xxx",
"lease_id": "lease_xxx",
"lease_expires_at": 1779850900000
}
@@ -379,7 +379,7 @@ Content-Type: application/json
默认：
```http
POST /api/agnet/deployments/{runtime_deployment_id}/stop
POST /api/agent/deployments/{runtime_deployment_id}/stop
Authorization: Bearer <service_token>
Content-Type: application/json
```
@@ -410,7 +410,7 @@ Content-Type: application/json
| 用例 | 操作 | 期望 |
|---|---|---|
| health | `GET /api/agnet/health` | 200，`status=healthy` |
| health | `GET /api/agent/health` | 200，`status=healthy` |
| create | Manager 创建 deployment | Runtime 返回 `deployment_id` 和 `swarm_id` |
| task flow | Runtime 回调 `task.created/claimed/heartbeat/blocked/retried/completed` | Manager timeline 和页面 Sub task flow 可见 |
| handoff | Runtime 回调 `handoff.requested/completed` | Manager 页面可见 from/to role |
@@ -433,7 +433,7 @@ Content-Type: application/json
## 12. 联调顺序建议
1. Agent Manager 确认 health、create、stop、approval decision 路径。
2. Manager 配置 `AGNET_RUNTIME_CREATE_PATH=/api/swarms` 后创建一个真实 deployment。
2. Manager 配置 `AGENT_RUNTIME_CREATE_PATH=/api/swarms` 后创建一个真实 deployment。
3. Agent Manager 回调 `task.created`、`task.claimed`、`task.heartbeat`。
4. 回调 `task.blocked`、`handoff.requested`、`handoff.completed`、`task.retried`。
5. 回调 `artifact.created`。