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

Merge pull request #15 from xmindlab-heicode/docs/hm-only-doc-sync

Browse Source 
docs: 清理旧 HM 编排文档并新增蜂群 deferred 跟踪（HM-only 仓 + 模板 Agent 模型）
This commit is contained in:
Fasthei
2026-06-08 17:42:43 +08:00
committed by GitHub
parent b3d864b29b 09331752f2
commit 932b429a5d
18 changed files with 146 additions and 4368 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+28 -58
View File
@@ -1,83 +1,53 @@
# AGENTS.md — Heicode 单仓导航（给 Codex / 助手） # AGENTS.md — Heicode Manager 单仓导航（给 Codex / 助手）
本文是 **仓库根级** 的快速地图与协作约定。细分栈的规则请看各子目录自带文档（避免重复与漂移）。 本文是 **仓库根级** 的快速地图与协作约定。细分栈规则看子目录自带文档（避免重复与漂移）。
## 仓库地图（explore 摘要） > **本仓 = Heicode Manager（HM）端。** 历史上客户端（`cc-haha`）、官网（`website`）与 Manager 曾在同一 monorepo；现已拆分，**本仓只保留 Heicode Manager**。客户端（终端 + 桌面）在 `heicode-macos-release-dev` / `heicode-winos-release-dev` 独立仓，不在本仓。
## 仓库地图
| 路径 | 角色 | 栈 / 备注 | | 路径 | 角色 | 栈 / 备注 |
|------|------|-----------| |------|------|-----------|
| `cc-haha/` | **Heicode** 客户端：CLI（Ink）+ 本地 HTTP/WS 服务 + **Desktop**（Tauri + React） | Bun + TypeScript；产品入口 `bin/heicode` | | `heicode/` | **Heicode Manager**：基于 new-api 的模型网关 + 管理控制台 | Go（Gin/GORM）后端 + `web/default` 前端（Bun/Rsbuild/React） |
| `heicode/` | **Heicode Manager**：网关 + 管理控制台 | Go（Gin/GORM）+ `web/default` 前端（Bun/Rsbuild/React） | | `docs/` | 产品共识 / 实施计划 / 集成契约 | Markdown，索引见 [`docs/README.md`](./docs/README.md) |
| `website/` | 产品介绍站点 | Next.js；根 `docker-compose.yml` 提供 `heicode-www` :8888 |
| `docs/` | 愿景、**里程碑**（`docs/milestones/`）、**Agent 集成**（`docs/integration/`） | Markdown |
根 `package.json` 仅少量 workspace 级依赖（如适配器用到的包）；**主要开发依赖在 `cc-haha/package.json`**。
## 权威子文档（改代码前先打开对应一篇） ## 权威子文档（改代码前先打开对应一篇）
- **客户端（cc-haha）**：[`cc-haha/AGENTS.md`](./cc-haha/AGENTS.md) — 目录结构、运行命令、测试、提交约定。 - **网关后端（`heicode/`，Go）**：[`heicode/AGENTS.md`](./heicode/AGENTS.md) — Go 分层、JSON / i18n / DB 规则、计费表达式等。
- **网关（heicode）**：[`heicode/AGENTS.md`](./heicode/AGENTS.md) — Go 分层、JSON/i18n/DB 规则等。 - **产品共识与实施计划**：[`docs/heicode.md`](./docs/heicode.md)、[`docs/plan.md`](./docs/plan.md)。
- **产品愿景与交付节奏**：[`docs/vision-heicode-full-stack-agentic-dev.md`](./docs/vision-heicode-full-stack-agentic-dev.md)、[`docs/milestones/README.md`](./docs/milestones/README.md)。 - **集成契约**：[`docs/integration/`](./docs/integration/) —— 当前模型「模板 Agent」见 `heicode-hm-template-agent-model.md`；HM↔AM 见 `heicode-am-contract.md`；桌面客户端对接见 `heicode-desktop-client-api.md`。
- **客户端**：在 `heicode-macos-release-dev` / `heicode-winos-release-dev` 独立仓，不在本仓。
## 最小开发闭环 ## 最小开发闭环
```bash Heicode Manager = `heicode/`（Go 后端 + `web/default` 前端）。构建 / 运行命令与分层规则以 [`heicode/AGENTS.md`](./heicode/AGENTS.md) 与 `heicode/README.md` 为准。
# 依赖（客户端主体）
cd cc-haha && bun install
# 终端 A：本地 API（桌面端依赖） ## 关键触摸点（代码索引）
bun run src/server/index.ts
# 终端 B：桌面 - **客户端登录**：客户端走 HM 的 `/api/heicode-auth/*`（转发到登录服务）+ V2 设备签名；详见 `docs/integration/heicode-desktop-client-api.md`。
cd desktop && bun run tauri dev - **Manager 侧 Heicode OAuth**：`heicode/controller/heicode_oauth.go`，路由 `heicode/router/heicode-router.go`（如 `/heicode/oauth/authorize`、`/heicode/oauth/session`）。
``` - **HM↔AM（agent 部署）**：`heicode/controller/agent_template_runtime.go`、`agent_template_handlers.go`；契约见 `docs/integration/heicode-am-contract.md`。
联调本机 Manager（heicode）时常见：
```bash
HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 bun run src/server/index.ts
```
更多变量见 `cc-haha/src/server/config/providerPresets.ts` 与 `cc-haha/src/server/api/heicode-auth.ts`（如 `HEICODE_<PROVIDER>_OAUTH_*`）。
## Heicode ↔ Manager 关键触摸点（代码索引）
- **客户端登录 / Provider**：`cc-haha/src/server/api/heicode-auth.ts`，路由前缀 `/api/heicode-auth/*`（由 `cc-haha/src/server/router.ts` 挂载）。
- **模型发现**：`cc-haha/src/server/services/providerService.ts`、`cc-haha/src/server/api/providers.ts`。
- **Provider 预设**：`cc-haha/src/server/config/providerPresets.json` + `providerPresets.ts`。
- **Manager 侧 Heicode OAuth**：`heicode/controller/heicode_oauth.go`，路由 `heicode/router/heicode-router.go`（例如 `/heicode/oauth/authorize`、`/heicode/oauth/session`）。
## 协作约定（根级） ## 协作约定（根级）
1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/AGENTS.md` 为准；客户端 TS/React 以 `cc-haha/AGENTS.md` 为准。 1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/AGENTS.md` 为准；产品 / 架构以 `docs/heicode.md` + `docs/plan.md` 为准。
2. **小步提交**：沿用历史风格（如 `feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。 2. **小步提交**：沿用历史风格（`feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。
3. **集成与「SK」边界**：平台契约见 [`docs/integration/agent-platform-api-design.md`](./docs/integration/agent-platform-api-design.md)，里程碑见 `docs/milestones/`。 3. **不要臆测计费**：计费在平台侧（new-api 计量），按 `docs/` 契约对接，不在本仓臆造扣费逻辑。
4. **不要臆测计费**：计费与订阅在平台侧，不在 Heicode 客户端内实现。
## Docker / 站点 ## 当前线上入口
- 根目录 [`docker-compose.yml`](./docker-compose.yml)：构建 `website/` 静态站点镜像（端口 **8888**）。
- Manager 本地编排以 `heicode/docker-compose.yml` 及仓库内 override 为准（若存在）。
- **VM / 生产同步代码**：优先在目标机上 **`git clone` / `git pull`** 与本仓库远程一致；**不要**用 `scp` 传整份源码或 compose（仅在仓库不可用或紧急热修时例外）。
- **VM 部署后清镜像**：每次 `docker compose ... up -d --build` 后执行 **`sudo docker image prune -f`**，清掉重建产生的悬空层；定期可 **`sudo docker system prune -f`**（不删仍在使用的卷）。避免只叠新镜像、旧层占满磁盘。
## 当前线上入口（2026-04）
- **Heicode 官网（Azure Static Web Apps）**：`https://ashy-dune-0e22d7b00.7.azurestaticapps.net`
- **Heicode Manager（生产）**：`https://code.xinghanlab.com/` - **Heicode Manager（生产）**：`https://code.xinghanlab.com/`
官网中的主按钮（登录/开始使用/CTA）默认应跳转到 `https://code.xinghanlab.com/`，避免出现历史 IP 地址。
## Manager 生产拓扑（Azure） ## Manager 生产拓扑（Azure）
- 应用层：Azure VM 上运行 `heicode`（当前用 Docker 容器承载应用进程）。 - 应用层：Azure VM 上运行 `heicode`（Docker 容器承载应用进程）。
- 数据库与缓存：使用 Azure 托管服务（不在 VM 上跑 PostgreSQL/Redis 容器） - 数据库与缓存：Azure 托管服务（不在 VM 上跑 PostgreSQL / Redis 容器）
- PostgreSQL: `heicode.postgres.database.azure.com` / DB `heicode` - PostgreSQL：`heicode.postgres.database.azure.com` / DB `heicode`
- Redis: `heicode.redis.cache.windows.net:6380`（TLS） - Redis：`heicode.redis.cache.windows.net:6380`（TLS）
- 容器落盘：VM 仅承载应用进程；**容器内产生的文件**（如 `/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘，便于备份与重建容器后不丢。编排见 `heicode/docker-compose.azure-vm.yml`，目录由环境变量 `HEICODE_DATA_ROOT` 指定。 - 容器落盘：容器内产生的文件（`/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘。编排见 `heicode/docker-compose.azure-vm.yml`，目录由 `HEICODE_DATA_ROOT` 指定。
- 说明：不要在生产 VM 上再启本地 `postgres`/`redis` 容器并指向业务库，避免与托管实例混淆。 - **VM 部署后清镜像**：每次 `docker compose ... up -d --build` 后执行 `sudo docker image prune -f`；定期 `sudo docker system prune -f`（不删在用卷），避免旧层占满磁盘。
- 镜像清理：发版构建后删除悬空/旧镜像层（见上文「VM 部署后清镜像」），防止 OS 盘被 Docker 占满。 - **VM / 生产同步代码**：优先在目标机 `git clone` / `git pull` 与远程一致；不要用 `scp` 传整份源码（紧急热修例外）。
--- ---
*若本文件与子目录 `AGENTS.md` / `AGENTS.md` 冲突，以子目录为准并及时更新根文件摘要。* *若本文件与 `heicode/AGENTS.md` 或 `docs/` 冲突，以子目录 / `docs` 为准并及时更新本文件。*
CLAUDE.md
+28 -58
View File
@@ -1,83 +1,53 @@
# CLAUDE.md — Heicode 单仓导航（给 Claude Code / 助手） # CLAUDE.md — Heicode Manager 单仓导航（给 Claude Code / 助手）
本文是 **仓库根级** 的快速地图与协作约定。细分栈的规则请看各子目录自带文档（避免重复与漂移）。 本文是 **仓库根级** 的快速地图与协作约定。细分栈规则看子目录自带文档（避免重复与漂移）。
## 仓库地图（explore 摘要） > **本仓 = Heicode Manager（HM）端。** 历史上客户端（`cc-haha`）、官网（`website`）与 Manager 曾在同一 monorepo；现已拆分，**本仓只保留 Heicode Manager**。客户端（终端 + 桌面）在 `heicode-macos-release-dev` / `heicode-winos-release-dev` 独立仓，不在本仓。
## 仓库地图
| 路径 | 角色 | 栈 / 备注 | | 路径 | 角色 | 栈 / 备注 |
|------|------|-----------| |------|------|-----------|
| `cc-haha/` | **Heicode** 客户端：CLI（Ink）+ 本地 HTTP/WS 服务 + **Desktop**（Tauri + React） | Bun + TypeScript；产品入口 `bin/heicode` | | `heicode/` | **Heicode Manager**：基于 new-api 的模型网关 + 管理控制台 | Go（Gin/GORM）后端 + `web/default` 前端（Bun/Rsbuild/React） |
| `heicode/` | **Heicode Manager**：网关 + 管理控制台 | Go（Gin/GORM）+ `web/default` 前端（Bun/Rsbuild/React） | | `docs/` | 产品共识 / 实施计划 / 集成契约 | Markdown，索引见 [`docs/README.md`](./docs/README.md) |
| `website/` | 产品介绍站点 | Next.js；根 `docker-compose.yml` 提供 `heicode-www` :8888 |
| `docs/` | 愿景、**里程碑**（`docs/milestones/`）、**Agent 集成**（`docs/integration/`） | Markdown |
根 `package.json` 仅少量 workspace 级依赖（如适配器用到的包）；**主要开发依赖在 `cc-haha/package.json`**。
## 权威子文档（改代码前先打开对应一篇） ## 权威子文档（改代码前先打开对应一篇）
- **客户端（cc-haha）**：[`cc-haha/AGENTS.md`](./cc-haha/AGENTS.md) — 目录结构、运行命令、测试、提交约定。 - **网关后端（`heicode/`，Go）**：[`heicode/CLAUDE.md`](./heicode/CLAUDE.md) — Go 分层、JSON / i18n / DB 规则、计费表达式等。
- **网关（heicode）**：[`heicode/CLAUDE.md`](./heicode/CLAUDE.md) — Go 分层、JSON/i18n/DB 规则等。 - **产品共识与实施计划**：[`docs/heicode.md`](./docs/heicode.md)、[`docs/plan.md`](./docs/plan.md)。
- **产品愿景与交付节奏**：[`docs/vision-heicode-full-stack-agentic-dev.md`](./docs/vision-heicode-full-stack-agentic-dev.md)、[`docs/milestones/README.md`](./docs/milestones/README.md)。 - **集成契约**：[`docs/integration/`](./docs/integration/) —— 当前模型「模板 Agent」见 `heicode-hm-template-agent-model.md`；HM↔AM 见 `heicode-am-contract.md`；桌面客户端对接见 `heicode-desktop-client-api.md`。
- **客户端**：在 `heicode-macos-release-dev` / `heicode-winos-release-dev` 独立仓，不在本仓。
## 最小开发闭环 ## 最小开发闭环
```bash Heicode Manager = `heicode/`（Go 后端 + `web/default` 前端）。构建 / 运行命令与分层规则以 [`heicode/CLAUDE.md`](./heicode/CLAUDE.md) 与 `heicode/README.md` 为准。
# 依赖（客户端主体）
cd cc-haha && bun install
# 终端 A：本地 API（桌面端依赖） ## 关键触摸点（代码索引）
bun run src/server/index.ts
# 终端 B：桌面 - **客户端登录**：客户端走 HM 的 `/api/heicode-auth/*`（转发到登录服务）+ V2 设备签名；详见 `docs/integration/heicode-desktop-client-api.md`。
cd desktop && bun run tauri dev - **Manager 侧 Heicode OAuth**：`heicode/controller/heicode_oauth.go`，路由 `heicode/router/heicode-router.go`（如 `/heicode/oauth/authorize`、`/heicode/oauth/session`）。
``` - **HM↔AM（agent 部署）**：`heicode/controller/agent_template_runtime.go`、`agent_template_handlers.go`；契约见 `docs/integration/heicode-am-contract.md`。
联调本机 Manager（heicode）时常见：
```bash
HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 bun run src/server/index.ts
```
更多变量见 `cc-haha/src/server/config/providerPresets.ts` 与 `cc-haha/src/server/api/heicode-auth.ts`（如 `HEICODE_<PROVIDER>_OAUTH_*`）。
## Heicode ↔ Manager 关键触摸点（代码索引）
- **客户端登录 / Provider**：`cc-haha/src/server/api/heicode-auth.ts`，路由前缀 `/api/heicode-auth/*`（由 `cc-haha/src/server/router.ts` 挂载）。
- **模型发现**：`cc-haha/src/server/services/providerService.ts`、`cc-haha/src/server/api/providers.ts`。
- **Provider 预设**：`cc-haha/src/server/config/providerPresets.json` + `providerPresets.ts`。
- **Manager 侧 Heicode OAuth**：`heicode/controller/heicode_oauth.go`，路由 `heicode/router/heicode-router.go`（例如 `/heicode/oauth/authorize`、`/heicode/oauth/session`）。
## 协作约定（根级） ## 协作约定（根级）
1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/CLAUDE.md` 为准；客户端 TS/React 以 `cc-haha/AGENTS.md` 为准。 1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/CLAUDE.md` 为准；产品 / 架构以 `docs/heicode.md` + `docs/plan.md` 为准。
2. **小步提交**：沿用历史风格（如 `feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。 2. **小步提交**：沿用历史风格（`feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。
3. **集成与「SK」边界**：平台契约见 [`docs/integration/agent-platform-api-design.md`](./docs/integration/agent-platform-api-design.md)，里程碑见 `docs/milestones/`。 3. **不要臆测计费**：计费在平台侧（new-api 计量），按 `docs/` 契约对接，不在本仓臆造扣费逻辑。
4. **不要臆测计费**：计费与订阅在平台侧，不在 Heicode 客户端内实现。
## Docker / 站点 ## 当前线上入口
- 根目录 [`docker-compose.yml`](./docker-compose.yml)：构建 `website/` 静态站点镜像（端口 **8888**）。
- Manager 本地编排以 `heicode/docker-compose.yml` 及仓库内 override 为准（若存在）。
- **VM / 生产同步代码**：优先在目标机上 **`git clone` / `git pull`** 与本仓库远程一致；**不要**用 `scp` 传整份源码或 compose（仅在仓库不可用或紧急热修时例外）。
- **VM 部署后清镜像**：每次 `docker compose ... up -d --build` 后执行 **`sudo docker image prune -f`**，清掉重建产生的悬空层；定期可 **`sudo docker system prune -f`**（不删仍在使用的卷）。避免只叠新镜像、旧层占满磁盘。
## 当前线上入口（2026-04）
- **Heicode 官网（Azure Static Web Apps）**：`https://ashy-dune-0e22d7b00.7.azurestaticapps.net`
- **Heicode Manager（生产）**：`https://code.xinghanlab.com/` - **Heicode Manager（生产）**：`https://code.xinghanlab.com/`
官网中的主按钮（登录/开始使用/CTA）默认应跳转到 `https://code.xinghanlab.com/`，避免出现历史 IP 地址。
## Manager 生产拓扑（Azure） ## Manager 生产拓扑（Azure）
- 应用层：Azure VM 上运行 `heicode`（当前用 Docker 容器承载应用进程）。 - 应用层：Azure VM 上运行 `heicode`（Docker 容器承载应用进程）。
- 数据库与缓存：使用 Azure 托管服务（不在 VM 上跑 PostgreSQL/Redis 容器） - 数据库与缓存：Azure 托管服务（不在 VM 上跑 PostgreSQL / Redis 容器）
- PostgreSQL: `heicode.postgres.database.azure.com` / DB `heicode` - PostgreSQL：`heicode.postgres.database.azure.com` / DB `heicode`
- Redis: `heicode.redis.cache.windows.net:6380`（TLS） - Redis：`heicode.redis.cache.windows.net:6380`（TLS）
- 容器落盘：VM 仅承载应用进程；**容器内产生的文件**（如 `/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘，便于备份与重建容器后不丢。编排见 `heicode/docker-compose.azure-vm.yml`，目录由环境变量 `HEICODE_DATA_ROOT` 指定。 - 容器落盘：容器内产生的文件（`/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘。编排见 `heicode/docker-compose.azure-vm.yml`，目录由 `HEICODE_DATA_ROOT` 指定。
- 说明：不要在生产 VM 上再启本地 `postgres`/`redis` 容器并指向业务库，避免与托管实例混淆。 - **VM 部署后清镜像**：每次 `docker compose ... up -d --build` 后执行 `sudo docker image prune -f`；定期 `sudo docker system prune -f`（不删在用卷），避免旧层占满磁盘。
- 镜像清理：发版构建后删除悬空/旧镜像层（见上文「VM 部署后清镜像」），防止 OS 盘被 Docker 占满。 - **VM / 生产同步代码**：优先在目标机 `git clone` / `git pull` 与远程一致；不要用 `scp` 传整份源码（紧急热修例外）。
--- ---
*若本文件与子目录 `AGENTS.md` / `CLAUDE.md` 冲突，以子目录为准并及时更新根文件摘要。* *若本文件与 `heicode/CLAUDE.md` 或 `docs/` 冲突，以子目录 / `docs` 为准并及时更新本文件。*
Heicode-Manager-项目说明与踩坑交接.md
-208
View File
@@ -1,208 +0,0 @@
# Heicode Manager 项目说明与踩坑交接
更新时间：2026-06-01
用途：给下一位 AI / 工程师快速理解 Heicode Manager 的项目边界、生产拓扑、普通 sub、蜂群、NewAPI 和已踩过的坑。
## 1. 一句话说明
Heicode Manager 是 Heicode 的服务端控制面和网页管理台，负责用户登录、模型网关配置、用户/设备/模型/渠道管理、普通 sub 敏捷任务控制、Runtime callback 落库、artifact/timeline 展示，以及和桌面客户端、Agent Manager Runtime、NewAPI、Azure Key Vault 之间的编排。
它不是桌面客户端本体，也不是 Agent Runtime 本体，也不是 NewAPI 本体。
## 2. 仓库结构
| 路径 | 作用 | 说明 |
|------|------|------|
| `heicode/` | Manager 后端和默认前端 | Go + Gin/GORM，`web/default` 是当前网页端 |
| `cc-haha/` | Heicode 桌面客户端和本地服务 | Tauri + React + Bun，客户端到 Manager 的请求 body 会走加密/签名流程 |
| `docs/` | 项目文档、部署、集成、进度清单 | 后续交接优先看这里 |
| `docs/deployment/` | 生产部署和迁移文档 | VM、Azure、配置交接 |
| `docs/integration/` | Runtime、桌面客户端、蜂群、普通 sub 对接文档 | 联调时优先看 |
开发前先看：
| 范围 | 文档 |
|------|------|
| 根仓库规则 | `AGENTS.md` |
| Manager 规则 | `heicode/AGENTS.md` |
| 生产配置 | `docs/deployment/Heicode-Manager-生产配置与账号交接清单.md` |
| 普通 sub 桌面客户端对接 | `docs/integration/heicode-desktop-sub-agile-api.md` |
| 普通 sub Agent Manager 对接 | `docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md` |
| 蜂群 Agent Manager 对接 | `docs/integration/蜂群模式-AgentManager对接任务清单.md` |
## 3. 生产拓扑
```text
用户/桌面客户端
-> https://code.xinghanlab.com
-> Heicode Manager Docker container on Azure VM
-> Azure PostgreSQL / Azure Redis
-> NewAPI model gateway
-> 普通 sub Agent Manager Runtime: http://20.212.121.126
-> 蜂群 Runtime / Orchestrator: http://52.139.240.116:8000
-> Azure Key Vault: https://heicode-kv.vault.azure.net
```
当前 Manager 部署在 Azure VM 上，容器名 `heicode`，端口 `3000:3000`。VM 上也能看到 `new-api`、`postgres`、`redis`、`heicode-openbao` 容器，但正式业务数据库和缓存应以 Azure 托管 PostgreSQL / Redis 配置为准，不要误用 VM 本地容器判断生产数据。
## 4. 普通 sub 和蜂群必须分开
这是最容易踩坑的点。
| 模式 | 含义 | Manager 当前配置 | Runtime |
|------|------|------------------|---------|
| 普通 sub 敏捷模式 | 桌面客户端把一个开发任务拆给若干子 Agent，按需求、设计、开发、测试、部署等阶段推进 | `AGENT_RUNTIME_ENABLED=true` | `http://20.212.121.126` |
| 蜂群模式 | HeiCode-Swarm 的多 Agent swarm run / task graph 模式 | `SWARM_RUNTIME_ENABLED=false` | `http://52.139.240.116:8000`，需单独启用和联调 |
不要因为两个接口都可能叫 `/api/swarms` 就把它们混成一个概念。普通 sub 是 Heicode 的任务组织方式；蜂群是独立 swarm runtime 形态。
## 5. 普通 sub 当前主流程
```text
桌面客户端创建/补充任务
-> Manager 用户态接口生成 deployment draft
-> Manager 调 Agent Manager Runtime POST /api/swarms
-> Runtime 创建 run 并启动子 Agent
-> Runtime 执行中 callback Manager
-> Manager 保存 timeline / events / logs / artifacts / usage
-> 桌面客户端从 Manager 查询展示
```
关键点：
1. Runtime 执行过程会回调状态、日志、timeline、用量。
2. 最终业务交付物不是直接塞在聊天文本里，而是通过 `artifact.created` 落库。
3. 客户端应先查 artifact 列表，再通过 content 接口下载完整产物。
4. 如果 `usage=0` 或只有失败摘要 artifact，不能算真实业务交付完成。
## 6. artifact 展示坑
桌面客户端曾出现“以下是作为 Frontend 角色...”这种内容，看起来像交付物，其实多半只是 Runtime 的摘要文本。
正常设计应该是：
| 层级 | 应展示什么 |
|------|------------|
| 聊天时间线 | 阶段进度、Agent 状态、摘要说明 |
| 交付产物卡片 | `artifact_id`、标题、类型、摘要、大小、hash、下载入口 |
| 完整代码/文件 | 通过 `GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content` 下载 |
如果 artifact 里有 `azblob://...` 或 `runtime://...`，客户端不应该直接暴露云凭据或要求用户自己访问 Blob，而应通过 Manager / Runtime content 代理接口拿完整内容。
## 7. NewAPI / 模型调用边界
NewAPI 是模型网关和用量计费入口，不是 Heicode Manager 自己的模型执行器。
排查模型问题时要区分三条链路：
| 链路 | 调用方 | 常见问题 |
|------|--------|----------|
| 桌面普通聊天 | 桌面客户端 -> Manager/NewAPI | 用户 token、模型列表、渠道权限、body 加密 |
| 普通 sub Runtime Agent | Runtime 子 Agent -> NewAPI/Manager 模型网关 | Runtime 环境变量、模型名、base_url、请求路径、上游超时 |
| Manager 后台模型配置 | 管理员网页 -> Manager/NewAPI | 渠道配置、分组、可用模型、价格表达式 |
曾踩过的坑：
- 某个模型 503/504 时，不一定是客户端参数错，也可能是 Runtime 子 Agent 使用的模型、base_url 或请求格式不对。
- Runtime 需要回传 `newapi_request_id` 和非零 token usage，方便定位 NewAPI 日志。
- 一个模型失败时可以切换模型验证，但不能把失败摘要 artifact 当成业务完成。
## 8. Azure Key Vault / OpenBao 边界
当前正式方向是 Azure Key Vault，不是 OpenBao。
| 项目 | 结论 |
|------|------|
| Azure Key Vault | 正式长期密钥托管方案 |
| OpenBao | VM 上存在历史/兼容容器，不作为当前正式方案 |
| Managed Identity | Manager 访问 Key Vault 的推荐方式 |
| 当前已知问题 | 之前健康检查出现过 `Identity not found`，说明 VM 身份或 `AZURE_CLIENT_ID`/Vault 权限未配好 |
如果后续迁移到 Container Apps / AKS / App Service，不能只切域名。必须重新配置 Managed Identity、Key Vault 权限、环境变量、持久化、数据库/Redis 网络、Runtime callback 地址。
## 9. 登录、设备、模型列表问题排查
之前遇到过用户登录成功但设备看不到、模型列表拿不到的问题。排查顺序：
1. Manager 是否有该用户记录。
2. JWT/session 是否能通过 Manager 校验。
3. 设备注册/心跳是否入库。
4. 用户是否绑定 NewAPI channel/group/token。
5. NewAPI 返回是否 401/403/模型列表为空。
6. Mac/Windows 客户端请求是否走同一 base_url、同一加密/签名逻辑。
不要只看“客户端显示已登录”，已登录不代表模型、设备、NewAPI 绑定都完整。
## 10. 网页端 Manager 已做过的重点
已处理过的方向包括：
- 注册页国内邮箱提示。
- Manager 登录后菜单跳转问题。
- 任务总览 / deployments 页面部分英文文案中文化。
- 普通 sub 控制面、部署草稿、运行状态、timeline、events、logs、artifacts 展示。
- artifact content 获取链路文档。
- Azure Key Vault secret_ref 接入方向。
- PayPal 充值和 NewAPI 模型费用关系说明文档。
继续改网页端时必须真实点击验证，尤其是：
- 登录后左侧菜单。
- 模型、渠道、供应商、支付、部署、任务总览。
- 创建新运行弹窗/抽屉。
- 产物卡片和下载入口。
## 11. 部署和 git 规则
生产部署原则：
```text
本地修改
-> git commit
-> git push 到 heicode-mananger main
-> VM 上 git pull
-> docker compose ... up -d --build
-> sudo docker image prune -f
-> 真实接口/页面冒烟
```
注意：
- 不要用 `scp` 传整份源码到 VM。
- `HeiCode-issues.git` 已废弃，后续不用再更新。
- VM 构建后必须清理 Docker 镜像，避免磁盘被旧层占满。
- 不要提交 `.env`、密钥、token、数据库连接串。
## 12. 新 AI 接手建议顺序
1. 读 `AGENTS.md` 和 `heicode/AGENTS.md`。
2. 读 `docs/deployment/Heicode-Manager-生产配置与账号交接清单.md`。
3. 用 `git status` 确认是否有未提交变更，不要动无关文件。
4. 区分当前任务是普通 sub、蜂群、网页端、NewAPI、Azure 还是桌面客户端。
5. 先用接口确认真实状态，再下结论。
6. 涉及生产前先确认是否需要部署，部署后必须真实冒烟。
7. 涉及密码、token、连接串时只写配置名和获取位置，不写明文。
## 13. 已踩过的典型坑
| 坑 | 正确处理 |
|----|----------|
| 把普通 sub 和蜂群混在一起 | 两套模式、两套配置、两套联调清单 |
| artifact 摘要当完整交付 | 必须通过 content 接口拿完整产物 |
| Runtime 返回 completed 就算成功 | 还要看 usage、artifact、日志、是否失败摘要 |
| Key Vault health 报错只改代码 | 先查 Managed Identity 和 Vault 权限 |
| NewAPI 一个模型失败就判 Manager 错 | 查 Runtime 请求路径、模型名、request id、上游状态 |
| VM 上有 postgres/redis 容器就当生产库 | 以 `SQL_DSN`、`REDIS_CONN_STRING` 和 Azure 托管服务为准 |
| 修改网页后不点击验证 | 必须真实打开页面、点菜单、点按钮 |
| 把密钥写入 md 方便交接 | 只能写配置名、用途、位置，不能写明文 |
## 14. 当前后续重点
| 方向 | 后续任务 |
|------|----------|
| 普通 sub | 持续和桌面客户端联调真实开发任务，确认 artifact content 是完整业务产物 |
| 蜂群 | 如需启用，先配置 `SWARM_RUNTIME_*`，单独跑蜂群 E2E |
| Key Vault | 修复 Managed Identity / `AZURE_CLIENT_ID` / Key Vault 权限 |
| NewAPI | 保持 Runtime 回传 `newapi_request_id`、usage、成本信息 |
| 网页端 | 继续中文化、交互完善、真实点击测试 |
| 生产部署 | 每次部署后检查 `/api/status`、登录、deployments、Runtime health |
README.md
+15 -49
View File
@@ -2,74 +2,40 @@
Heicode 面向**多人协作、可追溯交付**的软件团队：把需求对齐、实现、验证、发布和持续运营连成一条少断层的链路，并用**可编排的智能体角色**承接其中可标准化的环节——强调「能复盘、能审计、能按团队规模裁剪」，而不是罗列某一家的工具栈。 Heicode 面向**多人协作、可追溯交付**的软件团队：把需求对齐、实现、验证、发布和持续运营连成一条少断层的链路，并用**可编排的智能体角色**承接其中可标准化的环节——强调「能复盘、能审计、能按团队规模裁剪」，而不是罗列某一家的工具栈。
下面的目录表仅供工程查阅；**不代表对外产品承诺、路线图或你必须采用的集成方式。 ** 下面的目录表仅供工程查阅；**不代表对外产品承诺、路线图或你必须采用的集成方式。**
> **本仓 = Heicode Manager（HM）端。** 历史上终端/桌面客户端（`cc-haha`）、官网（`website`）与 Manager 曾同处一个 monorepo；现已拆分，**本仓只保留 Heicode Manager**（基于 new-api 的模型网关 + 管理控制台）。客户端（终端 + 桌面）在 `heicode-macos-release-dev` / `heicode-winos-release-dev` 独立仓。
## 这个仓库里有什么（工程布局） ## 这个仓库里有什么（工程布局）
| 目录 | 大致含义 | | 目录 | 大致含义 |
|------|----------| |------|----------|
| `cc-haha/` | **Heicode**（终端与桌面客户端及本地服务；此为源码目录名）。 | | `heicode/` | **Heicode Manager**：基于 new-api 的模型网关 + 管理控制台。Go（Gin/GORM）后端 + `web/default` 前端（Bun/Rsbuild/React）。 |
| `heicode/` | **Heicode Manager**（网关与管理控制台服务端；此为源码目录名）。 | | `docs/` | 产品共识、实施计划与集成契约（索引见 [`docs/README.md`](./docs/README.md)）。 |
| `website/` | 产品介绍站点（Next.js；可 `pnpm dev` 或 Docker 预览）。 |
| `docs/` | 愿景与范式；**[`docs/milestones/`](./docs/milestones/README.md)** 交付里程碑；**[`docs/integration/`](./docs/integration/README.md)** Agent 等平台接口设计。 | > 客户端与官网不在本仓。
## 产品在解决什么问题 ## 产品在解决什么问题
- **协作范式**：把瀑布 / 敏捷下的角色分工落到可复述的闸门与智能体承接边界（**方向与原则**见 `docs/vision-heicode-full-stack-agentic-dev.md`；编队明细在文档附录）。 - **协作范式**：把瀑布 / 敏捷下的角色分工落到可复述的闸门与智能体承接边界。
- **交付可追溯**：文档、沟通与变更尽量与版本、发布对齐，便于复盘与合规。 - **交付可追溯**：文档、沟通与变更尽量与版本、发布对齐，便于复盘与合规。
- **工程上**：同一仓库便于客户端与服务端**同步发版、统一回归**，减少「谁和谁版本对不上」的摩擦。 - **模型与执行分层**：HM 提供模型网关与权限 / 计费；云端 agent 由 agent_management（AM）部署，客户端拿到 agent 公网地址后**直连 agent 使用**。
## 详细愿景与范式 产品定位与架构共识见 [`docs/heicode.md`](./docs/heicode.md)，实施计划见 [`docs/plan.md`](./docs/plan.md)。
**[docs/vision-heicode-full-stack-agentic-dev.md](./docs/vision-heicode-full-stack-agentic-dev.md)**
## 快速启动（开发联调） ## 快速启动（开发联调）
```bash Heicode Manager 在 `heicode/` 子目录：Go 后端 + `web/default` 前端。完整构建 / 运行命令与分层规则见 [`heicode/CLAUDE.md`](./heicode/CLAUDE.md) 与 `heicode/README.md`。
# 根依赖（Bun monorepo 根目录）
bun install
# Heicode 客户端本地服务（目录 cc-haha） 与 Heicode 登录相关的最小路由（以实际代码为准）：
cd cc-haha
bun run src/server/index.ts
# 另开终端：桌面端
cd cc-haha/desktop
bun run tauri dev
```
联调网关时示例：
```bash
HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 bun run src/server/index.ts
```
**Heicode Manager**（`heicode/`）中与 Heicode 登录相关的路由（最小集，以实际代码为准）：
- `GET /heicode/oauth/authorize` - `GET /heicode/oauth/authorize`
- `GET /heicode/oauth/session` - `GET /heicode/oauth/session`
平台侧能力还包括模型发现（如 `GET /v1/models`）与 Anthropic Messages 兼容入口等，详见 **Heicode Manager**（`heicode/`）与 **Heicode 客户端**（`cc-haha/`）各自 README。 平台侧能力还包括模型发现（如 `GET /v1/models`）与 Anthropic Messages 兼容入口等。
## 官网（Next.js） 集成与对接契约见 [`docs/integration/`](./docs/integration/)（HM↔AM、桌面客户端对接等）。
```bash
cd website && pnpm install && pnpm dev
```
若根目录提供 `docker compose`，可按 compose 说明构建预览镜像（以仓库内 `docker-compose.yml` 为准）。
## 发版与回归建议
- 同一版本标签发布客户端与网关镜像。
- 每次发版至少回归：**登录**、**模型拉取**、**对话请求**。
- 先在本地 Docker / 本地联调通过，再做外网域名与证书。
## 相关外部参考（概念）
- [oh-my-claudecode](https://ohmyclaudecode.com/) — Claude Code 类工具的高效实践参考。
- Agent 平台以实际部署环境与文档为准。
## 许可证 ## 许可证
各子项目许可证见各子目录内 `LICENSE`（例如 Heicode Manager / `heicode/` 侧常见为 AGPLv3）。 `heicode/`（Heicode Manager，基于 new-api）许可证见 `heicode/LICENSE`（常见为 AGPLv3）。
docs/Heicode-Manager-agent统一改造落地计划.md
-183
View File
@@ -1,183 +0,0 @@
# Heicode Manager 统一改造落地计划（Manager 侧）
> 版本：v0.1（初稿）
> 日期：2026-06-01
> 负责范围：仅 `heicode-mananger`（Manager 控制面 + `web/default` 前端）
> 性质：内部落地计划，随实现推进持续更新。不代表对外承诺。
> **状态更新（2026-06-01）：`agnet → agent` 已按"强制全量、不留兼容"完成。**
> 后端 Go（路由 `/api/agent/*`、env `AGENT_*`、结构体/函数/文件名）、前端（`agent-console`/`agent-hub`、`/api/agent` 调用、i18n）、DB（表 `agent_*`、列 `agent_id`，并加幂等迁移 `renameAgnetTablesToAgent` 保住老数据）、文档、compose/.env、脚本均已统一为 `agent`。
> `go build ./...` 与 `go test ./controller ./model ./router ./middleware` 全绿；前端 `tsc -b` 通过。
> 本文 §3 原描述的"保留 `agnet` 兼容别名/线缆令牌"策略已**作废**——实际采用一次性硬切。唯一保留 `agnet` 字样的是 `model/main.go` 的迁移源表名（迁移所必需）。
> **部署待办**：① VM `.env` 的 `AGNET_*` 改名 `AGENT_*`；② 启动时迁移自动 rename 老表（已就绪）；③ 其他三仓库（agent_management / HeiCode-Swarm / 客户端）需同步切到 `/api/agent` 与新 env，否则跨服务对接在它们切换前会中断（按你的要求强制先行）。
## 0. 基准文档
本计划是以下两份的 **Manager 侧拆解执行版**，结论以原文为准：
| 来源 | 位置 | 作用 |
|---|---|---|
| 统一调用方案 v0.1 | gitee `taijibaga/heicodedebug` → `2026-06-01_heicode客户端相关定义.md` | 四仓库总纲：接口归口、模式拆分、状态裁决、产物、回调 |
| 全链路代码评审报告 | gitee `taijibaga/heicodedebug` → `2026-06-01_Heicode全链路代码评审报告.md` | P1–P7 问题与证据 |
| 桌面 sub 对接文档 | `docs/integration/heicode-desktop-sub-agile-api.md` | 现行普通 sub 契约 |
四仓库分工（总纲 §4）：客户端只调 Manager；**Manager 是唯一接口入口 + Runtime 路由器 + 唯一状态裁判**；`agent_management` 执行 Sub Agile；`HeiCode-Swarm` 执行 Swarm。
## 1. 贯穿全局的原则（来自总纲）
1. `agnet` 是历史拼写错误，统一为 `agent`；旧接口兼容期只做转发。
2. Sub Agile 与 Swarm 是两套运行时，**不再复用 `/api/swarms` 表达两种模式**，按 `mode` 路由。
3. Runtime 只上报**结构化事实**；Manager 据结构化字段裁决 `display_status`；客户端只消费结论，**不再用正则自判产物**。
4. 安全红线：只传 `azkv://` 等 `secret_ref`，禁明文密钥；高危操作 Manager 先审批再下发。
## 2. 已完成（分支 `fix/manager-deliverable-and-secret-validation`，commit `12602eb`，已推送）
| 项 | 文件 | 内容 | 对应总纲 |
|---|---|---|---|
| P2 交付物判定 | `controller/agnet_runtime_client.go` | `runtimeArtifactsAreSummaryOnly` 改读结构化 `artifact_type`+文件信号，弃脆弱正则 | §10.6 |
| P6a secret_ref 校验 | `controller/resource.go` | Resource CRUD 强制 `azkv://` | §16/§17.6 |
| P6b 值级密钥扫描 | `controller/resource.go`、`controller/agnet_control_plane.go` | `containsPlaintextSecret`/`containsSensitiveGrantField` 扫字符串值（sk-/JWT/PEM） | §16 |
| P5 默认模型收敛 | `controller/agnet_role_template.go`、`controller/agnet_task_bridge.go` | 单一来源 `defaultAgnetModelID()`（env `AGNET_DEFAULT_MODEL_ID`，默认 `gpt-5.4`）；移除 `agnet-model-<role>` 占位回退 | §9 |
| P3 状态枚举 | `docs/integration/heicode-desktop-sub-agile-api.md` | 补 `completed` 终态 + runtime_state 镜像 + 未知值兜底 | §10.4 |
| 单测 | `controller/agnet_deliverable_secret_test.go` | 覆盖以上行为 | — |
> 注：`defaultAgnetModelID` 在后续命名统一中应改名 `defaultAgentModelID`，env 改 `AGENT_DEFAULT_MODEL_ID`（保留 `AGNET_*` 回退）。
## 3. 命名统一 `agnet → agent`
### 3.1 爆炸半径（仅本仓库，不含另三仓库与跨团队契约）
**2155 处 / 63 文件**（`rg -i agnet`）。按「客户端/其他服务是否依赖」分类：
| 类别 | 规模 | 对外可见 | 处理策略 | 风险 |
|---|---|---|---|---|
| HTTP 路由 `/api/agnet/*` | 路由表 | ✅ 客户端+Runtime | 新增 `/api/agent/*` 别名，旧保留转发 | 🔴 |
| JSON 字段 | 仅 `agnet_id`（3 处，含 DB 列） | ✅ resource grant 契约 | 响应 dual-emit `agent_id`，请求 dual-accept | 🟠 |
| env 变量 `AGNET_*` | compose + 代码读取 | ✅ 部署配置 | 代码先读 `AGENT_*` 回退 `AGNET_*` | 🟠 |
| DB 表 `agnet_*` / `agnet_id` 列 | ~6 表 | ❌ 内部 | **用 GORM `TableName()` 钉住物理名不动**，物理改名作为最后单独迁移 | 🔴 |
| Go 内部标识（`AgnetXxx`、函数、文件名 `agnet_*.go`） | ~1800 | ❌ 编译期可查 | 纯重构，分模块小步改 | 🟢 |
| 前端（`agnet-console/`、组件、i18n key） | ~250 | ❌ 内部（调的是路由） | 重构，随路由切换 | 🟢 |
| 文档 | 多处 | — | 新文档写 `agent`，`agnet` 标 deprecated | 🟢 |
### 3.2 兼容期规则（总纲 §19）
1. 旧接口只做转发。2. 新文档只写新接口。3. 新客户端只调新接口。4. Manager 内部存储统一 `agent` 命名。5. 日志可记 legacy route，不展示给普通用户。
## 4. 路由拆分与归口（总纲 §5）
### 4.1 客户端 → Manager（新增）
```
/api/heicode/capabilities
/api/heicode/sub-agile/tasks/... （或统一 /api/heicode/tasks + body.mode）
/api/heicode/swarm/tasks/...
```
### 4.2 Manager → Runtime（新增，按 mode 分流）
```
/api/agent/sub-agile/deployments -> agent_management (AGENT_RUNTIME_* / 现 AGNET_RUNTIME_*)
/api/agent/swarm/deployments -> HeiCode-Swarm (SWARM_RUNTIME_*)
```
Manager 已具备双 env 前缀分流机制（`agnetRuntimeClientConfigForMode`）；蜂群侧配置就绪只差 `SWARM_RUNTIME_SERVICE_TOKEN`。
### 4.3 回调（新增 + 旧转发）
```
新：POST /api/agent/callbacks/runtime-events
旧：POST /api/agnet/callbacks/swarm-events （兼容转发到同一 handler）
```
## 5. 状态裁决：Manager 成为唯一裁判（总纲 §10，关联评审 P1）
### 5.1 三层状态 + display_status
- `client_task_status`（客户端本地）/ `cloud_deployment_status`（Manager）/ `runtime_execution_status`（Runtime）
- Manager 输出唯一 `display_status` 给客户端。
### 5.2 Runtime 必须上报的结构化交付物事实（契约）
```json
"deliverable": {
"has_deliverable": true,
"summary_only": false,
"artifact_ids": ["art_xxx"],
"files_modified": ["src/app.ts"],
"has_diff": true,
"commit_sha": ""
}
```
### 5.3 Manager 裁决规则
| Runtime 事实 | display_status |
|---|---|
| `completed` + has_deliverable + !summary_only | `completed` |
| `completed` + summary_only / 无 artifact | `completed_without_deliverable` 或 `needs_codegen` |
| `failed` | `failed` / `stopped` / `waiting_approval` 同名透传 |
### 5.4 Manager 落点
- `controller/agnet_callback.go`（`applyAgnetCallbackDeploymentState` 消费 `deliverable`，算 verdict）
- `model/agnet_deployment.go`（加 `DeliveryVerdict` / display_status 列，三库兼容 `varchar`）
- `controller/agnet_control_plane.go`（detail/timeline 暴露字段）
- 复用已就绪的 `artifactIsSummaryOnly`（P2）+ usage
- **阶段化**：先加派生字段不改 `status`（向后兼容）→ 客户端跟进后再引入新终态值。
## 6. 模型策略（总纲 §9）
- Sub Agile：`per_role` / `default`；Swarm：`primary`。
- 单一来源默认模型（P5 已起步，待改名 `defaultAgentModelID`）。
- Manager 校验：模型存在 / 套餐允许 / 角色允许 / 预算 / Runtime 支持。
## 7. 项目文件夹产物 `project_folder`（总纲 §12）—— 中期大件
- artifact 升为两级：`Project Artifact` → `File Artifacts / Directory Entries`。
- 新 artifact_type：`project_folder` / `project_archive`（现有 `code_patch/document/...` 保留）。
- 新增接口：`.../artifacts/{id}/manifest`、`.../files/{path}`、`.../archive`。
- **本地修改回传 + revision 协议**（§12.7）：`local-edits` / `batch` / 冲突 `ARTIFACT_REVISION_CONFLICT` / Manager 维护 current accepted revision。
- 影响：新 model（artifact revision / project entries）、新 controller、content 代理扩展。**工程量大，单独立项。**
## 8. 云部署生命周期（总纲 §18）—— 远期
`project_folder` → 选 target(Azure/阿里云/AWS) → Manager 校验/审批/凭证/预算 → Deploy Worker/Runtime 执行 → `deployment_manifest` artifact 回传。**远期，本轮不展开。**
## 9. 安全与审计（总纲 §16/§17）
| 项 | 现状 | 待办 |
|---|---|---|
| `secret_ref` 强制 `azkv://` | ✅ agnet 路径 + Resource CRUD（P6a） | 覆盖其余写入路径 |
| 值级密钥扫描 | ✅ P6b | — |
| 高危操作 Manager gate | ❌ 现为立即 `accepted`，阻断依赖 Runtime | Manager 侧加 risk_level/pending 审批 gate（关联 P1/§17.1） |
| 短期凭证 lease 真派生 | ❌ 占位（只发 `lease://`，不 mint） | 接 Key Vault 派生短期凭证 |
| revoke 同步 Runtime | ⚠️ approve 有 sync，revoke 无 | 补 revoke→Runtime 通知 |
| 审计 fail-closed | ⚠️ best-effort | 关键审计改 fail-closed 或告警 |
| 客户端禁 inline secret_ref | — | Manager 改为接受 `resource_binding_id`，内部映射 secret_ref（§17.6） |
## 10. 落地阶段（总纲 §20，Manager 承担）
| 阶段 | Manager 任务 | 自主性 | 依赖 | 状态 |
|---|---|---|---|---|
| **1 接口/命名** | `/api/agent/*` 别名、`/api/heicode/{sub-agile,swarm}/*`、callback 新路由、`AGENT_*` env 回退、`agnet_id`→`agent_id` 双字段 | ✅ 加法自主 | — | 待开始 |
| **2 模式路由** | 按 `mode` 路由两套 `*_RUNTIME_*` | ✅ | 蜂群 token | 机制已就绪 |
| **3 模型策略** | per_role/primary 校验 | ✅ | — | P5 起步 |
| **4 状态/产物裁决** | display_status + deliverable 字段 + project_folder + revision | 🟡 | Runtime 发结构化事实 | P1/P2 起步 |
| **5 日志/回调/调试** | user_logs/debug_logs 分层 + diagnostics + 统一 callback | ✅ | Runtime callback 切换 | diagnostics 已有雏形 |
## 11. 跨团队依赖（Manager 做不了，需协调）
1. **agent_management / HeiCode-Swarm**：上报结构化 `deliverable` 事实；接入 `/api/agent/{sub-agile,swarm}/*` 路由；callback 切 `/api/agent/callbacks/runtime-events`；产出真实 `project_folder`。
2. **蜂群 Runtime**：`SWARM_RUNTIME_SERVICE_TOKEN` 安全配置 + 修复 single-agent fallback（评审 P7）。
3. **客户端（macOS/Windows）**：切新接口、消费 display_status、project 文件树展示、本地 edit 上传、禁 mock/直连（§17）。
## 12. 风险与红线
- **`agnet` 是 load-bearing**（路由/env/DB/跨服务契约）——**严禁全局 sed**，必须加法别名 + 兼容期。
- DB 物理表/列名暂不改，用 `TableName()` 钉住，避免迁移风险。
- 跨服务契约字段改动一律 **dual-emit + dual-accept**，且需与调用方协调切换节奏。
- 状态裁决先加字段不覆盖 `status`，避免误伤「真完成但 Runtime 未回 artifact」的任务。
## 13. 待确认事项
1. 统一方案仍是 **v0.1**，落地前需与作者对齐版本/范围。
2. approval decision 回传路径：`/api/agent/{mode}/deployments/{id}/approvals/{approval_id}` 的最终形态。
3. 客户端→Manager 路由用「分模式」还是「统一 `/api/heicode/tasks` + body.mode」。
4. `needs_codegen` 与 `completed_without_deliverable` 的判定边界（何时用哪个）。
5. project_folder / 云部署的优先级与排期（是否本阶段做）。
---
*维护：本文件随实现进度更新；每完成一项在「已完成/状态」列标注 commit。*
docs/README.md
+6 -5
View File
@@ -7,12 +7,13 @@
| [`heicode.md`](./heicode.md) | Heicode 当前产品定位、系统边界和架构共识 | | [`heicode.md`](./heicode.md) | Heicode 当前产品定位、系统边界和架构共识 |
| [`plan.md`](./plan.md) | 按当前共识拆出的实施计划 | | [`plan.md`](./plan.md) | 按当前共识拆出的实施计划 |
| [`heicode-runtime-auth-newapi-secret-design.md`](./heicode-runtime-auth-newapi-secret-design.md) | 用户输入、登录用户复用、NewAPI 扣费映射、Azure Key Vault 凭证托管与短期凭证注入边界 | | [`heicode-runtime-auth-newapi-secret-design.md`](./heicode-runtime-auth-newapi-secret-design.md) | 用户输入、登录用户复用、NewAPI 扣费映射、Azure Key Vault 凭证托管与短期凭证注入边界 |
| [`heicode-manager-sub-swarm-progress-checklist.md`](./heicode-manager-sub-swarm-progress-checklist.md) | Heicode Manager sub 模式、瀑布/敏捷、蜂群模式的已完成/未完成/依赖/风险/下一步进度清单 | | [`integration/heicode-hm-template-agent-model.md`](./integration/heicode-hm-template-agent-model.md) | **当前模型**：模板 Agent + 客户端直连，HM 端后端/前端改造说明 |
| [`heicode-manager-standalone-execution-plan.md`](./heicode-manager-standalone-execution-plan.md) | Heicode Manager 端可独立完成任务的执行计划、顺序、验收标准和边界 | | [`integration/heicode-hm-legacy-teardown.md`](./integration/heicode-hm-legacy-teardown.md) | 旧 sub 任务编排模型的代码/表/前端删除清单 |
| [`integration/Heicode-登录接口对接文档.md`](./integration/Heicode-登录接口对接文档.md) | 已上线登录接口对接文档 | | [`integration/heicode-desktop-client-api.md`](./integration/heicode-desktop-client-api.md) | 桌面客户端对接 HM（模板 Agent 模型），已生产验证 |
| [`integration/agent-platform-request-contract.md`](./integration/agent-platform-request-contract.md) | Manager 请求 Agent 平台时携带的部署、日志、监控、事件与审计接口参数 | | [`integration/heicode-am-contract.md`](./integration/heicode-am-contract.md) | HM ↔ AM（agent_management）接口契约 |
| [`integration/heicode-swarm-deferred.md`](./integration/heicode-swarm-deferred.md) | **蜂群（Swarm）现状裁定与后续跟踪入口**：HM 当前不实现 swarm runtime，旧 sub/蜂群文档作废后的上下文迁移映射与归属（AM/Swarm 侧） |
| [`deployment/azure-production-deploy-guardrails.md`](./deployment/azure-production-deploy-guardrails.md) | Azure VM / PostgreSQL / Redis / Agent / NewAPI 生产部署前的安全守卫、环境变量注入和验证计划 | | [`deployment/azure-production-deploy-guardrails.md`](./deployment/azure-production-deploy-guardrails.md) | Azure VM / PostgreSQL / Redis / Agent / NewAPI 生产部署前的安全守卫、环境变量注入和验证计划 |
旧 Agent API 草案、旧里程碑、旧架构说明和旧上手材料不再作为实施依据。后续文档和实现以 `heicode.md` 与 `plan.md` 为准；生产部署操作以安全守卫文档约束，且不得覆盖产品/架构主线。 旧 Agent API 草案、旧 sub / 蜂群任务编排、旧里程碑、旧架构说明和旧上手材料不再作为实施依据（相关文档已删除）。**蜂群相关文档的作废/迁移映射与「HM 不实现 swarm runtime、新能力归 AM/Swarm 侧跟踪」的结论见 [`integration/heicode-swarm-deferred.md`](./integration/heicode-swarm-deferred.md)（删除≠丢上下文，迁移到此追踪入口）。** 当前实施模型以 `heicode.md`、`plan.md` 与 `integration/heicode-hm-template-agent-model.md` 为准；生产部署操作以安全守卫文档约束，且不得覆盖产品/架构主线。
代码中的过渡期命名、旧接口注释或旧 UI 文案只作为现状参考；若与 `heicode.md` / `plan.md` 冲突，应先更新实现或另行补充当前主线文档，不得恢复旧 Agent/M1-M5 草案作为依据。 代码中的过渡期命名、旧接口注释或旧 UI 文案只作为现状参考；若与 `heicode.md` / `plan.md` 冲突，应先更新实现或另行补充当前主线文档，不得恢复旧 Agent/M1-M5 草案作为依据。
docs/heicode-manager-standalone-execution-plan.md
-413
View File
@@ -1,413 +0,0 @@
# Heicode Manager 可独立执行任务计划
更新时间：2026-05-30
负责人范围：Heicode Manager 端
用途：后续开发按本文逐项执行、验收和更新状态。
## 一、核查结论
本文只列 Manager 端能独立完成的任务。判断标准是：不要求 Heicode 客户端新增功能、不要求蜂群 / Agent Runtime 提供真实接口、不要求 AKS / NATS / Prometheus 等基础设施先上线。
| 结论 | 说明 |
|---|---|
| 可以独立做 | Manager 自己的 DB 模型、Go API、前端页面、权限校验、回调接收骨架、artifact 数据模型、幂等、模拟事件和文档口径 |
| 不能独立做 | 真实 `swarm_id`、worker claim / heartbeat、真实 handoff / retry、真实 Runtime 日志指标、客户端审批弹窗、短期凭证注入 runtime、SK 工具真实调用结果 |
| 当前最大问题 | Manager 本地闭环已基本形成；剩余主要是等待真实 Runtime/客户端产生数据后联调验证 |
## 二、排除项
以下任务不放入 Manager 独立开发计划，避免把外部依赖误报为 Manager 可完成。
| 事项 | 排除原因 | 需要谁配合 |
|---|---|---|
| 真实创建 Swarm Run 并返回 `swarm_id` | 需要蜂群平台提供 `POST /api/swarms` 或等价生产接口 | 蜂群 / Agent Runtime |
| 子 Agent claim、heartbeat、release、timeout | 需要 worker runtime 和任务池 | 蜂群 / Agent Runtime |
| handoff、retry、blocked 的真实状态机 | 需要 Runtime 产生任务事件 | 蜂群 / Agent Runtime |
| 真实日志流和 CPU/内存/耗时指标 | 需要日志/指标源 | 蜂群 / 基础设施 |
| 客户端高危审批主弹窗 | 产品要求审批主体验在客户端 | Heicode 客户端 |
| 短期凭证真实注入子 Agent | 需要受控 runtime、身份和网络通道 | 蜂群 / 基础设施 |
| SK 工具真实调用结果 | 需要 SK 平台或 Runtime 上报 invocation event | 蜂群 / SK 平台 |
| 交付结果回到客户端 | 需要客户端展示和 Runtime artifact 输出 | 客户端 + 蜂群 |
## 三、执行顺序总览
| 顺序 | 任务 | 优先级 | 是否 Manager 独立 | 完成后价值 |
|---:|---|---|---|---|
| 1 | 增加 sub 模式字段 | P0 | 是 | 已完成：明确任务组织方式，支撑瀑布/敏捷状态展示 |
| 2 | 打通 HeicodeTask 到 Agent deployment 的 Manager 桥接 | P0 | 是 | 已完成：任务可生成 deployment draft |
| 3 | 增加用户态 Agent deployment API | P0 | 是 | 已完成：普通用户可以在自己资源范围内创建/查看/停止 deployment |
| 4 | 统一 `/api/swarms` 与 `/api/agent/deployments` 边界 | P0 | 是 | 已完成：为后续蜂群联调留稳定 adapter |
| 5 | 建 callback 接收端骨架 | P0 | 是 | 已完成：先接住事件、artifact、审批请求、timeline |
| 6 | 建 artifact 数据模型和 API | P0 | 是 | 已完成：交付物/产物摘要落库并可展示 |
| 7 | 增加回调幂等和签名/服务身份校验骨架 | P1 | 是 | 已完成：重复回调不重复写入，支持 token/HMAC |
| 8 | 持久化 SK snapshot | P1 | 是 | 已完成：容器重启后任务上下文和审计不丢 |
| 9 | 任务视角审计聚合 | P1 | 是 | 已完成：按 deployment 聚合 audit/callback/artifact/SK |
| 10 | 本地模拟蜂群事件冒烟入口 | P1 | 是 | 已完成：默认模拟 task/blocked/retry/handoff/artifact/approval/timeline |
| 11 | 前端页面补齐独立闭环展示 | P1 | 是 | 已完成：展示任务流、deployment、事件、artifact、审批和审计关系 |
| 12 | 文档口径清理 | P2 | 是 | 已完成：当前口径以 Azure Key Vault / secret_ref 为准 |
| 13 | AWS/GCP 占位提示 | P2 | 是 | 已完成：避免用户误以为 AWS/GCP 已可用 |
| 14 | 请求 body 加密策略确认 | P2 | 是 | 已完成：桌面端 sub POST 复用模型调用 V2 body 加密 |
| 15 | Runtime 状态诊断与兜底产物识别 | P1 | 是 | 已完成：Manager 可独立查询 Runtime 状态，页面明确区分普通 sub / 蜂群，并提示兜底摘要不是最终交付物 |
| 16 | Artifact 完整内容代理下载 | P1 | 是 | 已完成：Manager 校验用户和 artifact 后，通过 Runtime content 接口代理下载完整产物 |
## 四、任务明细
### 任务 1：增加 sub 模式字段
| 项 | 内容 |
|---|---|
| 目标 | Manager 能记录任务或部署计划采用 `waterfall` / `agile` 哪种组织方式 |
| 修改文件 | `heicode/model/agent_deployment.go`、`heicode/controller/agent_control_plane.go`、`heicode/web/default/src/features/agent-console/api.ts`、`heicode/web/default/src/features/agent-console/create-agent-deployment-sheet.tsx` |
| 建议字段 | `sub_mode`，枚举：`waterfall`、`agile`，默认 `agile` |
| 验收 | 创建 deployment 后 DB、API response、前端详情都能看到 `sub_mode` |
| 测试 | `go test ./controller -run 'TestAgent.*SubMode|TestAgentDeployment'`；`cd web/default && bun run typecheck` |
验收标准：
- 不允许写成自由文本。
- 旧数据无字段时默认按 `agile` 展示。
- 不能把 `sub_mode` 当成蜂群 Runtime 流程，只表示 Heicode 任务组织方式。
### 任务 2：HeicodeTask 到 Agent deployment 桥接
| 项 | 内容 |
|---|---|
| 目标 | Manager 能从 HeicodeTask 的任务卡生成本地 Agent deployment payload |
| 修改文件 | `heicode/controller/agent_control_plane.go`、新增 `heicode/controller/agent_task_bridge.go`、`heicode/web/default/src/lib/heicode-mcp.ts`、`heicode/web/default/src/features/tasks/task-card-view.tsx` |
| 新增 API | `POST /api/agent/tasks/:task_id/deployment-draft` 或等价 user-scoped endpoint |
| 输入 | task id、sub_mode、预算、资源范围、角色模板 |
| 输出 | deployment draft 或创建后的 `deployment_id` |
| 测试 | 新增 controller 单测；前端 typecheck |
验收标准：
- 任务能关联 `deployment_id` 或返回可提交的 deployment draft。
- draft 中不能包含明文密钥，只能出现 `secret_ref`。
- 找不到 task 或资源授权不足时返回明确错误。
### 任务 3：用户态 Agent deployment API
| 项 | 内容 |
|---|---|
| 目标 | 普通用户可以创建、查询、停止自己资源范围内的 deployment |
| 修改文件 | `heicode/router/api-router.go`、`heicode/controller/agent_control_plane.go`、`heicode/controller/agent_control_plane_test.go` |
| 当前问题 | `/api/agent/deployments` 走 `AdminAuth` |
| 新增建议 | 保留 admin route；新增 user route：`/api/agent/user/deployments` 或在同一路由中按 user scope 限制 |
| 测试 | 普通用户创建成功；越权查询别人 deployment 失败；停止别人 deployment 失败 |
验收标准：
- 用户只能看到自己的 deployment。
- `user_context.user_id` 为空时用登录用户 id 填充。
- 请求体伪造别人 `user_context.user_id` 必须被覆盖或拒绝。
- resource grant 必须属于当前用户。
### 任务 4：统一 `/api/swarms` 与 `/api/agent/deployments` 边界
| 项 | 内容 |
|---|---|
| 目标 | Manager 内部形成生产蜂群接口 adapter，不再让调用方混淆两个口径 |
| 修改文件 | 新增 `heicode/controller/agent_swarm_adapter.go` 或 `heicode/service/agent_swarm_adapter.go`，更新 `docs/integration/agent-platform-request-contract.md` |
| 当前现实 | 本地已有 `/api/agent/deployments`，蜂群资料包目标接口是 `/api/swarms` |
| 独立做法 | 先实现 Manager 内部 adapter 和统一 DTO，真实外呼先留配置开关，默认走本地 control-plane |
| 测试 | adapter 单测验证 payload 字段、`secret_ref`、correlation_id、sub_mode |
验收标准：
- 文档明确本地 control-plane 与生产 Runtime 的关系。
- 未来切换真实蜂群平台时，不需要重写前端页面。
- adapter 默认不外呼，避免误触发不存在的生产 Runtime。
### 任务 5：callback 接收端骨架
| 项 | 内容 |
|---|---|
| 目标 | Manager 先具备接收蜂群平台回调的 API 和落库能力 |
| 修改文件 | `heicode/model/agent_callback.go`、`heicode/controller/agent_callback.go`、`heicode/router/api-router.go` |
| 新增接口 | `POST /api/agent/callbacks/swarm-events` |
| 独立能力 | 本地模拟 payload 可保存、去重、查询；已补普通 sub 任务事件 schema 校验 |
| 测试 | controller 单测覆盖正常保存、重复 event_id 幂等、明文密钥拒绝、handoff 缺字段拒绝 |
验收标准：
- 请求体不得出现 token/password/private_key/access_key/connection_string 明文字段。
- 每个回调都有 `event_id` 或 `idempotency_key`。
- 重复回调返回成功但不重复写入。
- `task.*` / `handoff.*` 关键事件缺少必填字段时返回 `CALLBACK_SCHEMA_INVALID`。
### 任务 6：artifact 数据模型和 API
| 项 | 内容 |
|---|---|
| 目标 | Manager 保存和展示 artifact 摘要，不等 Runtime 真实输出 |
| 修改文件 | 新增 `heicode/model/agent_artifact.go`、`heicode/controller/agent_artifact.go`、`heicode/web/default/src/features/agent-console/api.ts`、`heicode/web/default/src/features/agent-console/pages.tsx` |
| 字段 | `artifact_id`、`deployment_id`、`task_id`、`correlation_id`、`artifact_type`、`title`、`summary`、`uri`、`checksum`、`metadata_json`、`created_at` |
| 测试 | model/controller 单测；前端 typecheck |
验收标准：
- artifact 只保存摘要和引用，不保存大文件正文。
- `uri` 支持 `artifact://`、`git://`、`azblob://`、`https://`，但页面只展示安全摘要。
- 能按 `deployment_id` 查询 artifact 列表。
### 任务 7：回调幂等和服务身份校验骨架
| 项 | 内容 |
|---|---|
| 目标 | 生产联调前先有幂等和认证形状 |
| 修改文件 | `heicode/controller/agent_callback.go`、新增 `heicode/middleware/agent_callback_auth.go` |
| 机制 | `X-Request-Id`、`X-Correlation-Id`、`Idempotency-Key`、可选 `X-Agent-Signature` |
| 当前阶段 | 可以先用配置开关和本地测试 token，不接真实 Key Vault service token |
| 测试 | 缺少服务 token 时拒绝；重复 key 不重复写入 |
验收标准：
- 开发环境可配置跳过严格签名，但生产默认要求服务身份。
- 日志不打印 token 或签名原文。
- 幂等冲突能返回已有记录摘要。
### 任务 8：持久化 SK snapshot
| 项 | 内容 |
|---|---|
| 目标 | 替换当前 `agentSnapshots` 内存 map |
| 修改文件 | 新增 `heicode/model/agent_sk_snapshot.go`，修改 `heicode/controller/agent_control_plane.go` |
| 当前问题 | 容器重启后 `/sk-snapshots` 丢失 |
| 测试 | 创建 snapshot 后清空内存，再从 DB 查询仍存在 |
验收标准：
- `deployment_id`、`snapshot_id` 有索引。
- 查询按创建时间倒序或稳定顺序返回。
- 不保存 SK 内容正文，只保存来源和版本引用。
### 任务 9：任务视角审计聚合
| 项 | 内容 |
|---|---|
| 目标 | 按 task/deployment/correlation_id 聚合 Manager 已有记录 |
| 修改文件 | `heicode/controller/agent_control_plane.go`、`heicode/model/agent_audit.go`、`heicode/web/default/src/features/agent-console/pages.tsx` |
| 聚合内容 | deployment、audit events、approvals、leases、artifacts、callbacks、resource grants |
| 新增接口 | `GET /api/agent/tasks/:task_id/timeline` 或 `GET /api/agent/deployments/:id/timeline` |
| 测试 | 同一 correlation_id 下能聚合多类事件 |
验收标准：
- 缺少某类数据时返回空数组，不报错。
- 时间线按时间排序。
- 敏感字段统一脱敏。
### 任务 10：本地模拟蜂群事件冒烟入口
| 项 | 内容 |
|---|---|
| 目标 | 在蜂群 Runtime 未接入前，Manager 能用模拟事件自测完整链路 |
| 修改文件 | `heicode/controller/agent_callback.go`、`heicode/router/api-router.go`、可选新增 `heicode/controller/agent_smoke.go` |
| 接口建议 | admin-only `POST /api/agent/dev/simulate-run` |
| 生成内容 | deployment accepted、task.created、task.claimed、task.heartbeat、task.blocked、handoff.requested、handoff.completed、task.retried、task.completed、artifact.created、approval.requested、timeline.updated |
| 测试 | 单测验证模拟后 timeline/artifacts/audit 可查；`scripts/agent_sub_mode_smoke.py` 可跑生产健康和 deployment timeline 冒烟 |
验收标准：
- 该接口必须 admin-only 或 dev-only。
- 响应明确 `simulated: true`。
- 线上页面不能把模拟事件显示成真实 Runtime 事件。
- task/blocked/retry/handoff 事件能在 timeline 中看到，来源标记为 `simulated`。
### 任务 11：前端页面补齐独立闭环展示
| 项 | 内容 |
|---|---|
| 目标 | 用户能看到 Manager 自己可提供的闭环信息 |
| 修改文件 | `heicode/web/default/src/features/agent-console/pages.tsx`、`api.ts`、必要时新增组件 |
| 展示内容 | sub_mode、deployment 来源 task、callbacks、artifacts、timeline、SK snapshots 持久化状态 |
| 测试 | `cd heicode/web/default && bun run typecheck`；本地页面点击冒烟 |
验收标准：
- 页面明确区分 `control-plane placeholder`、`simulated`、`runtime` 来源。
- 没有 artifact/callback 时有空态。
- 文案不宣称真实蜂群已完成。
### 任务 12：文档口径清理
| 项 | 内容 |
|---|---|
| 目标 | 清理旧 Vault/OpenBao/Secret Provider 误导表述 |
| 修改文件 | `docs/heicode.md`、`docs/plan.md`、`docs/heicode-manager-sub-swarm-progress-checklist.md` |
| 规则 | 用户侧叫“密钥保管器”，当前实现侧写 Azure Key Vault |
| 验收 | `rg -n "OpenBao|HashiCorp Vault|Secret Provider" docs` 后剩余内容必须是历史说明或明确非当前实现 |
验收标准：
- 不把 Azure Key Vault 写成普通用户要进入的后台。
- 不删除历史架构背景时，必须标注“历史/非当前实现”。
### 任务 13：AWS/GCP 占位提示
| 项 | 内容 |
|---|---|
| 目标 | 避免用户误以为 AWS/GCP 已完成 |
| 修改文件 | 资源绑定相关前端页面、`heicode/controller/resource.go` 如需补充状态字段 |
| 当前现实 | Azure 已有第一阶段发现，AWS/GCP 未实现 |
| 验收 | UI 明确显示 AWS/GCP “即将支持”或禁用状态 |
验收标准：
- 禁用项不能提交到后端创建真实资源发现。
- 已有 Azure 流程不受影响。
### 任务 14：请求 body 加密策略确认
| 项 | 内容 |
|---|---|
| 目标 | 桌面客户端调用 Manager 的 sub 流程接口时，支持与模型调用一致的 V2 应用层 body 加密；浏览器后台页面继续兼容普通 HTTPS JSON |
| 修改文件 | `docs/integration/heicode-desktop-sub-agile-api.md`、`docs/heicode-runtime-auth-newapi-secret-design.md`、必要时补充 `heicode/middleware` 或客户端 SDK 加解密模块 |
| 当前现实 | `/api/agent/user/*` 与 `/api/heicode-auth/*` 已支持 `Content-Encoding: heicode-aead-v1`；Manager 会先解密并校验设备签名，再把明文 JSON 交给业务处理或代理给上游 |
| 安全红线 | 请求体、回调、日志、artifact metadata、timeline 中禁止出现明文密码、Token、私钥、连接串、云 access key、模型 key；长期凭证只传 `secret_ref` |
| 后续判断 | 桌面客户端需要在 sub 流程调用中复用模型调用的 encryptedFetch/V2 签名能力；服务端保留未加密 JSON 只用于 Manager Web 控制台兼容 |
| 测试 | 单测覆盖 V2 malformed 请求拒绝、普通代理请求兼容；生产需用真实已配对设备发起加密 sub 请求冒烟 |
验收标准：
- 文档明确桌面端优先走 V2 应用层 body 加密，且保留浏览器后台未加密 JSON 兼容。
- 客户端对接文档明确禁止传明文长期凭据，只允许 `secret_ref` / `lease://...` / 资源元数据。
- 服务端日志不打印请求 body 中的敏感字段。
- V2 加密失败时返回 `X-Heicode-Auth-Error` 和 `X-Heicode-Server-Time`，便于客户端排障。
### 任务 15：Runtime 状态诊断与兜底产物识别
| 项 | 内容 |
|---|---|
| 目标 | Manager 不依赖客户端或 Runtime 改接口，也能把“callback 已到”和“Runtime/Agent 是否真的产出交付物”分开展示 |
| 修改文件 | `heicode/controller/agent_runtime_client.go`、`heicode/router/api-router.go`、`heicode/web/default/src/features/agent-console/api.ts`、`heicode/web/default/src/features/agent-console/pages.tsx` |
| 新增 API | `GET /api/agent/user/deployments/:deployment_id/runtime-diagnostics` |
| 诊断来源 | 用 deployment 记录里的 `runtime_swarm_id` / `runtime_deployment_id` 查询 Runtime status；默认路径 `/api/swarms/{swarm_id}/status`，可用 `AGENT_RUNTIME_STATUS_PATH` / `SWARM_RUNTIME_STATUS_PATH` 配置 |
| 普通 sub / 蜂群边界 | 返回 `runtime_mode`，页面分别显示“普通 sub 模式”或“蜂群模式”，不把二者合并成一个流程 |
| 已识别异常 | Runtime agent failed、completed 但存在 failed agents、只有 `Runtime execution summary` 兜底产物、模型 token 用量为 0、Runtime 状态查询失败 |
| 测试 | `go test ./controller -run TestAgentRuntimeDiagnosticsWarnsOnCompletedRuntimeWithFailedAgents -count=1`；前端 `bun run build:check` |
验收标准：
- 诊断接口只读，不改 deployment 状态，不伪造 artifact。
- 页面中的兜底摘要必须明确提示“不是最终业务交付物”。
- 普通 sub 与蜂群模式必须通过 `runtime_mode` 区分展示。
- Runtime 状态查不到时返回可读 warning，不能影响 Manager 已落库 callback/timeline/artifact 查询。
### 任务 16：Artifact 完整内容代理下载
| 项 | 内容 |
|---|---|
| 目标 | 对齐 Agent Manager v2.1.10 的产物获取流程：Manager / 前端先查 artifact 列表，再通过用户态 content 代理接口获取完整文件 |
| 修改文件 | `heicode/model/agent_artifact.go`、`heicode/controller/agent_callback.go`、`heicode/controller/agent_runtime_client.go`、`heicode/router/api-router.go`、`heicode/web/default/src/features/agent-console/pages.tsx` |
| 新增 API | `GET /api/agent/user/deployments/:deployment_id/artifacts/:artifact_id/content` |
| Runtime 目标路径 | 默认 `GET /api/swarms/{swarm_id}/artifacts/{artifact_id}/content`，可用 `AGENT_RUNTIME_ARTIFACT_CONTENT_PATH` / `SWARM_RUNTIME_ARTIFACT_CONTENT_PATH` 配置 |
| 安全边界 | Manager 先校验当前用户拥有 deployment，再校验 artifact 属于该 deployment；不暴露 Azure Blob 凭据、SAS URL 或 Runtime 内网信息 |
| 测试 | `go test ./controller -run TestAgentArtifactContentProxiesRuntimeContent -count=1` |
验收标准：
- 不能直接用用户传入的 URI 下载，必须以 Manager 已落库 artifact 为准。
- 响应透传 Runtime 的文件正文、`Content-Type` 和 `Content-Disposition`。
- Runtime 未配置或 content 拉取失败时返回明确业务错误。
- 页面 artifact 卡片提供“下载产物”，但兜底摘要仍需标记为非最终业务交付物。
## 五、推荐执行批次
### 批次 A：最小 Manager 闭环
| 顺序 | 任务 |
|---:|---|
| 1 | sub 模式字段 |
| 2 | 用户态 Agent deployment API |
| 3 | HeicodeTask 到 deployment 桥接 |
| 4 | 本地模拟蜂群事件冒烟入口 |
完成批次 A 后，Manager 应能做到：普通用户从任务卡发起一个本地 deployment，并通过模拟事件看到任务进展，不依赖真实 Runtime。
### 批次 B：生产联调准备
| 顺序 | 任务 |
|---:|---|
| 1 | `/api/swarms` 与 `/api/agent/deployments` adapter |
| 2 | callback 接收端骨架 |
| 3 | artifact 数据模型和 API |
| 4 | 回调幂等和服务身份校验骨架 |
完成批次 B 后，Manager 应能接收蜂群平台未来回调，并能用模拟 payload 证明幂等、落库、查询和脱敏正确。
### 批次 C：可观测与收尾
| 顺序 | 任务 |
|---:|---|
| 1 | SK snapshot 持久化 |
| 2 | 任务视角审计聚合 |
| 3 | 前端闭环展示 |
| 4 | 文档口径清理 |
| 5 | AWS/GCP 占位提示 |
| 6 | 请求 body 加密策略确认 |
| 7 | Runtime 状态诊断与兜底产物识别 |
| 8 | Artifact 完整内容代理下载 |
完成批次 C 后，Manager 端应具备清晰的任务视角、持久化上下文、准确页面口径和更少误导。
## 六、统一自测命令
每个批次完成后至少执行：
```bash
cd /Users/gongzhiyong/go/heicode-mananger/heicode
go test ./controller ./model
```
前端有改动时执行：
```bash
cd /Users/gongzhiyong/go/heicode-mananger/heicode/web/default
bun run typecheck
bun run build
```
文档有改动时执行：
```bash
cd /Users/gongzhiyong/go/heicode-mananger
git diff --check -- docs
```
如果涉及生产部署，必须再按：
```bash
cd /Users/gongzhiyong/go/heicode-mananger
sed -n '1,220p' docs/deployment/azure-production-deploy-guardrails.md
```
## 七、完成定义
Manager 独立任务完成，不等于蜂群生产闭环完成。本文完成的定义是：
| 条件 | 标准 |
|---|---|
| 普通用户路径 | 非管理员用户可以基于自己的任务和资源创建/查看/停止本地 deployment |
| 任务关联 | HeicodeTask 能关联 deployment 或 deployment draft |
| sub 模式 | `waterfall` / `agile` 在 DB、API、UI 可追踪 |
| 回调骨架 | 事件、artifact、approval-request、usage、status 可模拟回调落库 |
| artifact | artifact 摘要可保存、查询、展示 |
| 幂等 | 重复回调不重复写入 |
| 审计 | task/deployment/correlation_id 下能聚合审计、审批、artifact、callback |
| 安全 | API、日志、页面不出现明文长期密钥 |
| 请求加密 | 桌面端 sub 请求支持与模型调用一致的 V2 body 加密；浏览器后台普通 JSON 兼容路径不受影响 |
| Runtime 诊断 | Manager 页面能显示 Runtime 真实状态来源、失败 Agent、兜底产物和普通 sub / 蜂群模式归属 |
| Artifact 内容 | Manager 用户态接口能代理下载 Runtime 保存的完整 artifact 内容，且不暴露存储凭据 |
| 口径 | 页面和文档不把本地占位/模拟事件说成真实 Runtime |
## 八、执行时不能突破的边界
1. 不在 Manager 中保存长期明文密钥。
2. 不让普通用户看到 CodeGW 管理后台能力。
3. 不把 Manager 做成网页编码主体验。
4. 不把 `sub_mode` 解释成蜂群 Runtime 固定流程。
5. 不把本地模拟事件当真实蜂群完成证据。
6. 不把 Azure Key Vault 暴露成普通用户要直接操作的后台。
7. 不绕过客户端高危审批的产品边界；Manager 只能先提供记录和 API。
8. 不破坏 V2 body 加密的版本字段、诊断头、重放保护和未加密 Web 控制台兼容路径，避免客户端和 Manager 联调不可排障。
docs/heicode-manager-sub-swarm-progress-checklist.md
-144
View File
@@ -1,144 +0,0 @@
# Heicode Manager 普通 sub 与蜂群模式进度清单
更新时间：2026-05-30
负责人范围：Heicode Manager 端
用途：给负责人、上级和联调同学快速确认 Manager 端在普通 sub 与蜂群模式下已经具备什么、还要做什么、哪些需要客户端或 Agent Manager / 蜂群项目配合。
## 资料来源
| 来源 | 用途 |
|---|---|
| `http://gitee.ath.cx:3000/taijibaga/fengqun/src/branch/main/docs` | 蜂群设计资料包，定义目标驱动蜂群、任务图、claim、heartbeat、handoff、artifact、审批、审计和三方分工 |
| `http://gitee.ath.cx:3000/taijibaga/HeiCode-Swarm` | 蜂群项目实现资料，当前 Orchestrator/Agent/Redis/K8s/桌面演示客户端的实际结构 |
| `docs/product-package/07-integration-boundaries.md` | Heicode、Manager、Agent 平台、CodeGW、Azure Key Vault 的边界 |
| `docs/integration/heicode-desktop-sub-agile-api.md` | Heicode 桌面客户端接 Manager 的普通 sub 敏捷流程 |
| `docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.md` | PayPal 收款、Heicode 余额/订阅、NewAPI 模型扣费和 Agent 运行费用边界 |
| 当前仓库 `heicode/` 代码 | Manager 端实际实现核查 |
## 一、核心边界
蜂群模式不是普通 sub 敏捷/瀑布本身。普通 sub 是 Heicode 的任务组织方式；蜂群是 Agent/Swarm Runtime 的执行方式。
| 模式 | Manager 当前职责 | Runtime / Agent Manager 当前职责 | 不能混淆的点 |
|---|---|---|---|
| 普通 sub 敏捷/瀑布 | 从任务卡生成 deployment、保存 `sub_mode`、权限清单、预算、callback、timeline、artifact、审批记录和运行时诊断 | 执行普通 sub 任务，回传阶段、日志、工具调用、artifact、usage、失败原因 | 普通 sub 不等于蜂群 task graph；`/api/swarms` 可作为 Runtime 兼容入口，但页面和文档必须按普通 sub 展示 |
| 蜂群模式 | 生成 swarm adapter 请求、保存 `deployment_id <-> swarm_id` 映射、接回调、审批、审计、artifact 展示和运行时诊断 | 创建 Swarm Run、任务图、claim、heartbeat、handoff、Agent 编队、真实执行与结果回传 | 蜂群是执行形态；不能把普通 sub 的阶段状态误写成蜂群已完成 |
| 系统 | 定位 | 应该做什么 | 不应该做什么 |
|---|---|---|---|
| Heicode 桌面客户端 | 用户主体验 | 输入目标、持续补充需求、查看反馈、审批高危操作、接收交付结果 | 直接配置 AKS、模型供应商、完整蜂群 payload |
| Heicode Manager | 控制面、记录面和用户侧账本入口 | 资源绑定、`secret_ref`、权限清单、生成启动请求、记录 deployment/swarm 映射、回调、artifact、timeline、审批、审计、余额/订阅展示 | 替代客户端做主开发对话，替代 Runtime 执行任务，或把 PayPal 收款当成模型扣费链路 |
| HeiCode-Swarm / Agent Runtime | 执行层 | 创建 Swarm Run、任务图、Agent 编队、claim、heartbeat、handoff、执行、结果回传、真实运行 usage 回传 | 保存长期明文密钥，直接暴露给普通用户，或自行决定用户账本扣费 |
## 二、目标调用链
```text
Heicode 桌面客户端
-> Heicode Manager
- V2 加密请求 body
- task/deployment draft
- resource_grants / secret_ref / budget / approval_policy
-> Agent Runtime 或 HeiCode-Swarm
- POST /api/swarms 或兼容创建入口
- 返回 swarm_id / runtime_deployment_id
<- Runtime callback
- swarm-events / artifact.created / approval.requested / timeline.updated
<- Manager 查询接口
- deployment detail / events / logs / metrics / artifacts / sk-snapshots / timeline
<- 桌面客户端展示和审批
```
## 三、当前 Manager 已完成项
以下只按当前仓库代码确认，不把规划项写成已完成。
| 能力 | 当前状态 | 代码证据 |
|---|---|---|
| sub 模式字段 | 已支持 `sub_mode`，默认 `agile`，校验 `agile/waterfall` | `heicode/controller/agent_control_plane.go`、`heicode/model/agent_deployment.go` |
| 用户态 deployment | 已有 `/api/agent/user/deployments` 创建、查询、停止、日志、事件、指标、artifact、SK snapshot、timeline | `heicode/router/api-router.go` |
| 任务到 deployment draft | 已有 `/api/agent/user/tasks/:task_id/deployment-draft` | `heicode/controller/agent_task_bridge.go` |
| `/api/swarms` 兼容入口 | 已有用户态 `POST /api/swarms`，内部走 Manager deployment 创建，并作为 adapter source 记录 | `heicode/router/api-router.go`、`AgentCreateUserSwarm` |
| Runtime 创建桥接 | 已能按配置调用 Runtime 创建接口，默认路径 `/api/agent/deployments`，可用环境变量改为蜂群创建路径 | `heicode/controller/agent_runtime_client.go` |
| Runtime stop 桥接 | 已能在停止 Manager deployment 时调用 Runtime stop | `heicode/controller/agent_runtime_client.go` |
| Runtime 状态诊断 | 已新增用户态只读诊断接口，按 `runtime_mode` 区分普通 sub / 蜂群，查询 Runtime status 并识别 failed agent、兜底摘要 artifact、零 token 用量等异常 | `heicode/controller/agent_runtime_client.go`、`AgentGetUserDeploymentRuntimeDiagnostics` |
| callback 接收 | 已有 `POST /api/agent/callbacks/swarm-events` | `heicode/controller/agent_callback.go` |
| callback 鉴权 | 支持 `X-Agent-Service-Token` 和 HMAC 签名校验，并可从 Key Vault ref 读取签名密钥 | `heicode/controller/agent_callback.go` |
| callback 幂等 | `event_id` / `idempotency_key` 去重，重复回调返回成功但不重复写 | `heicode/model/agent_callback.go` |
| artifact 落库 | `artifact.created` 可生成 artifact 记录，支持用户态列表查询 | `heicode/model/agent_artifact.go`、`AgentListUserDeploymentArtifacts` |
| artifact 完整内容代理 | 已新增用户态 content 下载接口，Manager 校验 deployment/artifact 权限后代理 Runtime content 接口读取完整产物 | `AgentGetUserDeploymentArtifactContent`、`callAgentRuntimeArtifactContent` |
| approval 回调 | `approval.requested` 可转成 Manager 审批记录 | `heicode/controller/agent_callback.go` |
| 审批结果回传 Runtime | 用户 approve/reject 后，Manager 可按配置 POST 回 Runtime approval decision，且不发送 `secret_ref` | `heicode/controller/agent_approval.go`、`heicode/controller/agent_runtime_client.go` |
| timeline 聚合 | 用户态 timeline 聚合 audit、callbacks、artifacts、sk_snapshots | `AgentGetUserDeploymentTimeline` |
| SK snapshot 持久化 | 已有 `agent_sk_snapshots` 模型和列表查询 | `heicode/model/agent_sk_snapshot.go` |
| 本地模拟事件 | 已有用户态 `simulate-events`；默认模拟会写入 callback、artifact、approval、timeline 记录，用于 Manager 自测展示链路和脱敏检查 | `AgentSimulateUserDeploymentEvents` |
| V2 body 加密 | `/api/agent/user/*`、`/api/heicode-auth/*`、`/api/swarms` 已按同一套 V2 设备签名和 body 加密路径设计；未加密 Web 控制台仍兼容 session + `New-Api-User` | `heicode/middleware/auth.go`、`heicode/router/api-router.go` |
| 生产普通 sub 烟测记录 | 2026-05-31 已用生产 Manager 入口完成真实普通 sub 复核：`dep_1d6d66896cc6` -> `swm_03995f7c7a27`，`gpt-5.4`，`tokens_used=2682`，`newapi_request_id=chatcmpl-DlbZce3VZnsv5DptBILFoiRYy5ZHN`，业务 `code_patch` artifact 可通过 Manager content 接口下载 | `docs/integration/heicode-desktop-sub-agile-api.md` |
| PayPal/计费边界文档 | 已明确 PayPal 只是收款渠道；模型调用仍走 Heicode/NewAPI 的钱包或订阅额度；Agent 运行费用目前只有预算字段，真实收费需 Runtime usage 回传 | `docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.md` |
## 四、Manager 端还需要继续做的蜂群任务
| 优先级 | 任务 | 当前缺口 | 是否 Manager 可独立做 | 验收标准 |
|---|---|---|---|---|
| P0 | 把 `/api/swarms` adapter 文档化并固定字段 | 已完成：`docs/integration/蜂群模式-AgentManager对接任务清单.md` 和 `docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md` 已写清 Runtime create、callback、source、`deployment_id <-> swarm_id` 映射 | 是 | 文档可直接发给 Agent Manager / 蜂群侧核对 |
| P0 | 增加 Swarm Run 显示字段 | 已完成：用户态 deployment 详情展示 `runtime_deployment_id`、`runtime_swarm_id`、`runtime_state`，并在相关记录里展示 source | 是 | 用户态 deployment 详情和后台页面能看到 Runtime 映射 |
| P0 | 回调事件类型收敛 | 已完成：`GET /api/agent/callbacks/swarm-events/schema` 输出事件类型、分类和必填字段；callback 接收端按 schema 校验关键 task/handoff/artifact/approval 字段 | 是 | `task.created/claimed/running/completed/failed/handoff/approval/artifact` 都有 schema |
| P0 | Runtime 联调配置模板 | 已完成：两份 Agent Manager 对接任务清单已写清 `AGENT_RUNTIME_*`、callback URL、service token/HMAC 方式和验收步骤 | 是 | 蜂群项目按模板能调用 Manager callback |
| P1 | 审批结果回传 Runtime 联调 | Manager adapter 已有；仍需要 Runtime 提供接收接口并验证状态继续/停止 | 需要 Runtime 接口 | 审批通过/拒绝后 Runtime 状态能继续或停止 |
| P1 | Artifact 展示优化 | Manager 端已完成：页面展示 artifact 类型、摘要和 URI；真实 `code_patch/document/test_report/deployment_manifest` 仍需 Runtime 输出 | 需要 Runtime 数据 | artifact 页面/详情能按类型展示摘要和链接 |
| P1 | Artifact 完整内容下载 | 已完成：用户态 `/artifacts/{artifact_id}/content` 代理 Runtime content，页面提供下载入口 | 是 | artifact 属于当前用户 deployment 才能下载，响应透传 Runtime 文件内容 |
| P1 | 任务图/Agent 状态展示占位 | 已完成：页面从 `task.*` / `handoff.*` callback 聚合 Agent task map；无真实数据时显示 Runtime callback 空态 | Manager 可先做展示结构，真实数据需 Runtime | 有空态和字段，不宣称真实已运行 |
| P1 | Runtime 状态诊断展示 | 已完成：任务总览详情页显示运行模式、运行状态、数据来源和异常 warning；兜底摘要产物会提示“不是最终业务交付物” | 是 | 页面能识别 callback 已到但 Runtime agent 失败、只返回兜底摘要的情况 |
| P1 | 日志/指标真实来源标识 | 已完成：logs/metrics API 返回 `data_source`、`runtime_source`，当前明确是 Manager control-plane / estimated，不伪装 Runtime 真实指标 | 需要 Runtime 数据 | 页面和 API 响应能区分来源 |
| P1 | Agent 运行费用口径收敛 | 已完成文档口径：`budget.max_tokens/max_cost_usd/max_duration_sec` 是预算约束，不等于真实扣费账本；真实收费必须依赖 Runtime 回传 usage | Manager 已完成文档，真实数据需 Runtime | 页面/文档不把 estimated budget 说成真实扣费 |
| P1 | 高危审批客户端联动文档 | 已完成：`docs/integration/heicode-desktop-sub-agile-api.md` 已包含 approval 查询、approve/reject、awaiting_approval 流程 | 是 | 客户端文档补齐 approval flow |
| P2 | 蜂群模式验收脚本 | 已完成：`scripts/agent_sub_mode_smoke.py` 支持 schema 检查、生产健康检查、可选 simulate-events、可选真实 callback smoke | 是 | 本地/生产能跑出 callback、artifact、approval、timeline 可见 |
| P2 | 生产 schema / 认证链路复测 | 本地代码和测试已覆盖；生产公开 `GET /api/agent/callbacks/swarm-events/schema` 当前返回 404，认证接口需有效登录态或后台 token 才能测 | 是，部署后复测 | 生产 schema 返回 200，用户态/后台态 smoke 能拿到真实数据 |
## 五、需要蜂群项目配合的事项
| 事项 | 为什么 Manager 不能单独完成 | 蜂群侧需要提供 |
|---|---|---|
| 真实 Swarm Run | Manager 只能发起请求和记录，不能替 Runtime 创建任务图 | 生产 `POST /api/swarms` 或确认使用现有 `/tasks` 兼容方式 |
| 真实 task graph | 任务拆解、依赖、状态机在 Runtime 内部产生 | `swarm_tasks`、依赖关系、状态枚举 |
| claim / heartbeat / release | 这是 worker runtime 行为 | 事件回调或查询接口 |
| handoff / retry / blocked | 任务交接和失败恢复属于 Runtime | 标准事件、重试次数、失败原因、下一步动作 |
| Agent 执行结果 | Manager 不能生成真实代码产物 | artifact schema、Git branch/commit、测试报告、部署结果 |
| Runtime 指标 | CPU、内存、耗时、Agent 存活、任务耗时来自集群 | metrics 查询或 Prometheus 指标映射 |
| Runtime 真实用量和成本 | Manager 只能保存预算和回传结果，不能凭本地估算扣真实 Agent 运行费用 | `model_tokens`、`model_cost_usd`、`runtime_seconds`、`cpu_core_seconds`、`memory_mb_seconds` 等 usage callback |
| 审批等待状态机 | Runtime 要能暂停高危动作并等待 Manager/客户端审批 | approval request 和 approval decision API |
## 六、需要桌面客户端配合的事项
| 事项 | Manager 已有基础 | 客户端需要做 |
|---|---|---|
| V2 加密请求 | Manager 已支持 | sub/蜂群相关 POST 请求复用模型调用加密 |
| 任务创建和追问 | Manager 有 `/api/heicode-auth/*` 代理 | 带 Heicode access token 调用任务接口 |
| deployment draft | Manager 有用户态接口 | 从任务卡调用 draft，再创建 deployment/swarm |
| 进度展示 | Manager 有 detail/events/timeline/artifacts 接口 | 做用户主体验展示，不暴露底层 payload |
| 高危审批 | Manager 有 approval API 和回调转审批记录 | 弹窗展示风险、资源、TTL，并提交 approve/reject |
## 七、当前不应误报为完成的项
| 项 | 当前真实状态 |
|---|---|
| 蜂群生产闭环 | 未完成。Manager 有控制面和回调骨架，但真实 Runtime 任务图/Agent 执行仍需蜂群项目联调 |
| HeiCode-Swarm 项目等于正式 Heicode 桌面客户端 | 不是。它有自己的 `desktop-client` 演示端，正式链路应走 Heicode 桌面客户端 -> Manager -> Runtime |
| `/api/swarms` 已等于真实 Runtime Swarm Run | 不是。Manager 侧已有 adapter 入口，但是否真实创建 Swarm Run 取决于 Runtime 配置和蜂群接口 |
| artifact/timeline 有接口就等于有真实产物 | 不是。Manager 能接和展示，真实产物必须由 Runtime 回调 |
| `Runtime execution summary` 就等于最终交付物 | 不是。Manager 页面会标记这是兜底摘要；真实最终交付物必须是 Runtime/Agent 返回的 `code_patch`、`document`、`test_report`、Git branch/commit、部署地址等可核对 artifact |
| 高危审批在 Manager 里点完就闭环 | 不是。产品要求桌面客户端主审批，并且 Runtime 要收到 decision |
| 本地测试通过就等于生产接口全通 | 不是。本地 router/controller/middleware 测试能证明代码能力；生产仍必须确认对应镜像、路由和认证配置已生效 |
| Agent budget 就等于真实收费 | 不是。当前 `budget` 是执行上限和审计字段；真实收费需要 Runtime/Agent Manager 回传可核对 usage |
| PayPal 接入会改变模型扣费方式 | 不是。PayPal 只是充值/购买订阅的收款渠道，模型调用仍从钱包余额或内部订阅额度扣 |
## 八、后续执行顺序
| 顺序 | 任务 | 负责人范围 | 备注 |
|---:|---|---|---|
| 1 | 固定 Manager -> Swarm adapter 契约 | Manager | 先把 `/api/swarms`、Runtime create path、callback 字段写死成可联调文档 |
| 2 | 跑一次本地模拟 Runtime callback | Manager | 已有默认模拟链路；继续用于验证 callback/artifact/timeline/approval 去重和脱敏 |
| 3 | 给蜂群项目配置 callback URL 和 service token | Manager + 蜂群 | 不传明文长期密钥 |
| 4 | 用 HeiCode-Swarm 当前 Orchestrator 做兼容测试 | Manager + 蜂群 | 先判断是否走 `/tasks` 适配，还是蜂群侧补 `/api/swarms` |
| 5 | 桌面客户端按文档跑任务 -> draft -> create -> timeline -> approval | 客户端 + Manager | 使用 V2 加密 POST |
| 6 | 核对 Runtime usage 回传字段 | Manager + 蜂群 | 至少覆盖模型 token/cost、运行时长、Agent role、deployment/task/correlation |
| 7 | 补页面来源标识和任务图空态 | Manager | 防止把 simulated/control-plane 误认为 runtime |
docs/heicode-manager-swarm-gap-analysis.md
-112
View File
@@ -1,112 +0,0 @@
# Heicode Manager 蜂群模式缺失对照文档
更新时间：2026-05-27
对照范围：`fengqun` 设计资料、`HeiCode-Swarm` 项目现状、Heicode 产品资料包、当前 Heicode Manager 代码。
## 一、对照结论
Manager 端已经具备蜂群联调需要的控制面基础：用户态 deployment、task draft、`/api/swarms` adapter、Runtime 创建/停止桥接、callback 接收、artifact、approval、approval decision 回传 adapter、timeline、SK snapshot、V2 加密请求。本地 `simulate-events` 默认链路也能写入 task、blocked、retry、handoff、artifact、approval、timeline 记录，便于 Manager 自测页面展示和脱敏。
仍然缺的是“真实蜂群 Runtime 产生的数据和状态机”。也就是说，Manager 不是完全没写；缺口主要集中在 Runtime 真正创建 Swarm Run、任务图、Agent 执行、handoff、产物和审批继续/停止闭环。
## 二、按文档要求逐项对照
| 文档要求 | 当前 Manager 状态 | 是否满足 | 缺失原因 | 需要谁 |
|---|---|---|---|---|
| Heicode 客户端是主体验 | Manager 文档和接口已按客户端调用设计，V2 加密 POST 已支持 | 部分满足 | 桌面客户端还需按文档接任务、展示进度和审批 | 客户端 |
| Manager 是受控入口，不暴露完整 payload 给普通用户 | 用户态 draft/create 已有，可由任务卡生成 plan | 部分满足 | 页面还需要更弱化底层 payload，突出启动摘要和状态 | Manager |
| Manager 调用 `POST /api/swarms` 创建 Swarm Run | Manager 已有 `/api/swarms` adapter，Runtime create path 可配置 | 部分满足 | 是否真实创建 Swarm Run 取决于蜂群 Runtime 是否提供生产接口 | 蜂群 + Manager |
| 保存 `swarm_id`、状态、请求摘要、`correlation_id` | 模型已有 `runtime_swarm_id`、`runtime_state`、payload JSON、correlation metadata | 基本满足 | 真实 `swarm_id` 需要 Runtime 返回 | 蜂群 |
| 接收 `swarm-events` 回调 | 已有 `POST /api/agent/callbacks/swarm-events` | 满足接收能力 | 还缺真实 Runtime 持续回调 | 蜂群 |
| 重复回调幂等 | 已按 `event_id` / `idempotency_key` 去重 | 满足 | 需要蜂群侧稳定传唯一事件 ID | 蜂群 |
| 接收 artifact 回调 | `artifact.created` 可落库并查询 | 满足接收能力 | 真实 artifact schema 和文件/分支引用需 Runtime 输出 | 蜂群 |
| 展示 Swarm 状态、事件、产物 | deployment detail/events/artifacts/timeline 已有，页面已强化 runtime/simulated 来源和 artifact 类型/URI | 基本满足 | 真实展示内容仍依赖 Runtime 回调真实数据 | 蜂群 |
| 展示 task graph、claim、heartbeat | Manager 已可接收并展示普通 task flow callback；没有独立 task graph 状态表 | 部分满足 | 真实任务图仍需要 Runtime 产出 task/agent 事件 | 蜂群 |
| 展示 handoff、blocked、retry | 已补 `task.*` / `handoff.*` schema 校验和页面任务流展示 | 基本满足接收和展示 | 真实数据仍需要 Runtime 持续回调 | 蜂群 |
| 高危审批请求进入 Manager | `approval.requested` callback 可转审批记录；用户 approve/reject 后可按配置 POST 回 Runtime | 部分满足 | 还需要蜂群 Runtime 提供并验证 approval decision 接收接口 | Manager + 蜂群 |
| 高危审批在客户端主体验完成 | Manager 有审批 API | 部分满足 | 桌面客户端要弹窗、轮询/订阅、提交决定 | 客户端 |
| 短期凭证和长期密钥隔离 | Manager 使用 `secret_ref` / `lease://` 记录，不传明文 | 基本满足 | Runtime 侧短期凭证派生/注入未验证 | 蜂群 + 基础设施 |
| CodeGW 用量归属 | Manager 有模型/余额基础，Runtime payload 带 billing_context | 部分满足 | 子 Agent 调用用量按 task/deployment/role 回流未验证 | 蜂群 + CodeGW + Manager |
| 日志和指标 | Manager 有 logs/metrics 接口占位和 runtime state | 部分满足 | CPU/内存/Agent 存活/任务耗时等真实指标来自 Runtime/AKS | 蜂群 + 基础设施 |
| 最终交付回流 | artifact/timeline 接收能力已有 | 部分满足 | 最终交付结果、Git branch/commit、部署 URL 需要 Runtime 输出，客户端展示 | 蜂群 + 客户端 |
## 三、HeiCode-Swarm 项目现状对 Manager 的影响
从 `HeiCode-Swarm` 项目 README 和代码看，当前项目结构是：
```text
desktop-client -> Orchestrator(FastAPI) -> Redis -> Agent Pods
```
当前 Orchestrator 主要入口：
| 入口 | 当前作用 | 与 Manager 目标契约差异 |
|---|---|---|
| `GET /health` | 健康检查 | 可直接用于 Runtime health |
| `POST /tasks` | 创建任务 | 不是文档要求的 `POST /api/swarms`，字段也不是 Heicode task/resource/secret/budget 结构 |
| `GET /tasks` / `GET /tasks/{id}` | 查询任务 | 可作为早期状态查询，但缺 `swarm_id` 维度 |
| `GET /agents` | Agent 列表 | 可映射到 Agent 状态 |
| `GET /handoffs` | handoff 历史 | 可映射到 Manager timeline |
| `GET /metrics` | Prometheus 指标 | 可映射到 Manager metrics |
| `WS /ws/{agent_id}` | Agent 注册、心跳、任务、结果 | Manager 不应直接接 Agent WS，应该由 Runtime 汇总后回调 Manager |
因此，Manager 后续联调有两种路线：
| 路线 | 说明 | 风险 |
|---|---|---|
| 蜂群侧补正式 `POST /api/swarms` | 最符合设计文档，Manager adapter 直接对接 | 需要蜂群项目改接口 |
| Manager 临时适配 `POST /tasks` | 可以先跑通现有 Orchestrator | 字段语义不足，无法完整覆盖 resource_grants、secret_ref、approval_policy、budget、artifact callback |
建议：生产目标仍以 `POST /api/swarms` 为准；短期可以做 `/tasks` 兼容测试，但必须标记为兼容桥接，不作为最终契约。
## 四、缺失项清单
### P0：影响蜂群主流程
| 缺失项 | 当前状态 | 处理建议 |
|---|---|---|
| 真实 `POST /api/swarms` 联调 | Manager 有 adapter，蜂群当前可见接口是 `/tasks` | 蜂群侧确认是否补 `/api/swarms`；Manager 固定 adapter 文档 |
| `deployment_id <-> swarm_id` 真实映射 | Manager 字段已准备，真实值需 Runtime 返回 | Runtime create response 必须返回 `swarm_id` |
| task graph / claim / heartbeat 事件 | Manager 可接收/展示 task flow callback；缺真实 Runtime 数据 | 蜂群侧定义并回调 `task.created/claimed/heartbeat/released/completed/failed` |
| artifact 真实产出 | Manager 能落库，缺 Runtime 产出 | 蜂群侧回调 `artifact.created`，带 Git branch/commit 或存储 URI |
| 审批结果回传 Runtime | Manager adapter 已完成，真实闭环未验证 | 蜂群侧提供接收接口并验证 approved/rejected 后继续或停止 |
### P1：影响可观测和验收
| 缺失项 | 当前状态 | 处理建议 |
|---|---|---|
| handoff/retry/blocked 展示 | Manager 已有 schema 校验、模拟事件和页面任务流展示 | 用真实 Runtime callback 做生产联调验证 |
| Runtime 日志/指标 | Manager 有 logs/metrics 位置，缺真实数据源 | 蜂群侧提供日志摘要或查询接口；指标对齐 Prometheus |
| 事件来源标识 | API 有部分 runtime/simulated 状态，页面还需强化 | Manager 页面区分 `manager`、`runtime`、`simulated` |
| 桌面客户端审批主流程 | Manager 有 API，客户端未完成主体验 | 客户端按 Manager approval API 接入 |
| 子 Agent 用量归属 | billing_context 有，真实用量未回流 | Runtime 调模型时带 task/deployment/role correlation |
### P2：完善项
| 缺失项 | 当前状态 | 处理建议 |
|---|---|---|
| 蜂群验收脚本 | 已新增 `scripts/agent_sub_mode_smoke.py`，可检查生产 Manager、Agent health 和指定 deployment timeline | 后续按真实 Runtime deployment 固化执行参数 |
| 页面术语统一 | sub/蜂群容易混淆 | 页面和文档统一：sub 是任务组织，swarm 是执行层 |
| 兼容 `HeiCode-Swarm` demo client 的说明 | 容易误认为正式 Heicode 桌面客户端 | 文档明确 demo client 不等于 `cc-haha` 正式客户端 |
## 五、验收口径
蜂群模式不能只看 Manager 页面有没有数据。必须同时满足：
1. 桌面客户端能通过 Manager 发起任务，POST 请求体走 V2 加密。
2. Manager 创建或桥接 Swarm Run，并保存 `deployment_id`、`runtime_deployment_id`、`swarm_id`。
3. Runtime 真实生成任务图，并回传任务状态、Agent 状态、handoff、artifact、审批请求。
4. Manager 对 callback 去重、落库、脱敏，并能按 deployment/timeline/artifact 查询。
5. 高危审批由客户端展示并提交，Manager 记录，Runtime 收到决定后继续或停止。
6. 交付物能回到 Manager 和客户端，不能只停留在 Runtime Redis 或 Agent 日志里。
7. 全链路日志和页面不得出现长期明文密钥、模型 key、云 access key、私钥或连接串。
## 六、下一步建议
| 顺序 | 动作 | 目标 |
|---:|---|---|
| 1 | 把 `docs/heicode-manager-sub-swarm-progress-checklist.md` 发给蜂群侧确认 | 让对方知道 Manager 已有什么、需要他们回什么 |
| 2 | 确认蜂群侧最终入口是 `/api/swarms` 还是先兼容 `/tasks` | 避免双方接口错位 |
| 3 | 用 Manager callback 接口跑一次蜂群侧真实 `artifact.created` / `approval.requested` | 证明回调、artifact、approval、timeline 有真实数据 |
| 4 | 客户端按 `docs/integration/heicode-desktop-sub-agile-api.md` 接入审批和 timeline | 跑通用户主体验 |
| 5 | 根据真实联调结果更新本文状态 | 把缺失项从“缺接口/未联调”改为“已验证/阻塞/延期” |
docs/integration/AgentManager蜂群Runtime接口实现要求.md
-677
View File
@@ -1,677 +0,0 @@
# Agent Manager 蜂群 Runtime 接口实现要求
更新时间：2026-05-28
面向对象：Agent Manager / HeiCode-Swarm Runtime 开发负责人
用途：Agent Manager 按本文实现接口、字段和回调后，Heicode Manager 可直接联调蜂群模式。
## 1. 结论
Heicode Manager 已负责控制面和记录面：
- 生成 deployment / swarm 创建请求。
- 传递 `resource_grants`、`secret_ref`、预算、模型网关上下文和 callback 地址。
- 保存 `deployment_id <-> runtime_deployment_id <-> swarm_id` 映射。
- 接收 Runtime callback，落库 artifact / approval / timeline / audit。
- 用户 approve/reject 后，把审批决定回传 Runtime。
Agent Manager / Swarm Runtime 需要负责执行层：
- 创建真实 Swarm Run。
- 生成真实 task graph。
- 管理 Agent claim / heartbeat / handoff / retry / blocked / failed 状态机。
- 真实执行任务并产出 artifact。
- 在高危动作前暂停并回调审批请求。
- 接收审批结果后继续或停止。
- 回传日志、指标、用量和最终结果。
### 1.1 2026-05-28 生产联调实测结论
使用测试用户 `zsbgnw@gmail.com`（Manager 用户 `chenchen`，`user_id=22`）在生产 Manager 上实测蜂群入口。
当前生产 Manager Runtime 配置实际为：
```text
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/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` |
| Manager events | `deployment.accepted`、`runtime.sync.started`、`runtime.sync.accepted` |
| Manager stop | 通过 |
| Runtime stop | 通过，Agent Manager 侧 `dep_77370f27186f` 状态为 `stopped` |
| Runtime callback | 未观察到，生产 Manager callback 表 0 条对应记录 |
| artifact / timeline callback | 未产出 |
| SK / usage callback | 未产出 |
| Runtime logs | 仅 `Pod ... has no logs yet` |
| Runtime metrics | 返回固定 CPU/内存/网络汇总，看起来仍是占位值 |
结论：
1. Heicode Manager 的 `/api/swarms` adapter 能接收用户态蜂群请求，并能通过当前 Runtime bridge 调 Agent Manager IP。
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 约束。
## 2. 总体调用链
```text
Heicode Desktop Client
-> Heicode Manager
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/agent/callbacks/swarm-events
-> Runtime approval decision
POST /api/swarms/{swarm_id}/approvals/{approval_id}
```
客户端到 Heicode Manager 的 `POST /api/swarms` 与普通 sub 用户态接口一样，必须支持 V2 body 加密：
```http
Content-Encoding: heicode-aead-v1
X-Heicode-Device-Id: <device_id>
X-Heicode-Timestamp: <unix_ms>
X-Heicode-Nonce: <nonce_hex>
X-Heicode-Fingerprint: <device_fingerprint>
X-Heicode-Eph-Pubkey: <base64_x25519_ephemeral_pubkey>
X-Heicode-Signature: <base64_ed25519_signature>
Content-Type: application/json
```
未加密 Web 控制台请求仍按 Manager session cookie + `New-Api-User` 兼容处理。Manager 调 Agent Manager / Swarm Runtime 的服务间请求不使用该客户端 body 加密协议，而使用 `Authorization: Bearer <service_token>` 和公共追踪 Header。
## 3. Agent Manager 必须提供的接口
| 优先级 | 方法 | 路径 | 必须 | 用途 |
|---|---|---|---:|---|
| 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/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` | 建议 | 查询日志 |
| P1 | `GET` | `/api/swarms/{swarm_id}/metrics` | 建议 | 查询指标 |
如果短期无法提供 `/api/swarms`，可以临时确认兼容路径，例如 `/tasks`。但这只能作为联调过渡，不作为最终生产契约。
## 4. 认证与公共 Header
Manager 调 Agent Manager 时携带：
```http
Authorization: Bearer <service_token>
X-User-ID: <manager_user_id>
X-Binding-Scope: <binding_scope>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: manager-<manager_deployment_id>
Content-Type: application/json
```
要求：
1. `Authorization` 用于服务间鉴权。
2. `X-Correlation-ID` 必须贯穿 create、callback、approval decision、logs、metrics。
3. `X-Idempotency-Key` 必须支持幂等；重复创建请求不能生成多个真实 Swarm Run。
4. Agent Manager 不得要求 Manager 传长期明文密钥。
## 5. `GET /api/agent/health`
### 响应
```json
{
"success": true,
"data": {
"status": "healthy",
"service": "agent-manager-swarm-runtime",
"version": "1.0.0",
"runtime": "aks",
"time": "2026-05-28T10:00:00Z"
}
}
```
验收：
- HTTP 200。
- `status` 为 `healthy` / `ok` / `up` 之一。
- 不返回密钥、Token、连接串。
## 6. `POST /api/swarms`
### 请求体
```json
{
"orchestration_plan": {
"intent_id": "task_123",
"template_hint": "heicode-task",
"objective": "完成本轮用户目标",
"sub_mode": "agile",
"risk_level": "medium",
"budget": {
"max_tokens": 120000,
"max_cost_usd": 8,
"max_duration_sec": 3600
},
"user_context": {
"user_id": "22",
"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": [
"接口返回成功",
"artifact 可回写到 timeline",
"不出现明文密钥"
],
"next_action": "continue",
"requires_user_approval": false
},
"agents": [
{
"role_template": "backend",
"goal": "完成后端实现和测试",
"default_model_id": "model_xxx",
"resource_grants": []
}
],
"resource_grants": []
},
"agents": [
{
"role": "backend",
"resource_grants": []
}
],
"resource_grants": [
{
"grant_id": "grant-task-123-git",
"resource_id": "repo-main",
"resource_type": "git",
"permission_scope": ["repo:read", "repo:write:feature-branches"],
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
"ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
"target_role": "backend",
"constraints": {
"allowed_paths": "heicode/**"
},
"metadata": {
"repo": "heicode-manager"
}
}
],
"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",
"task.created",
"task.claimed",
"task.heartbeat",
"task.blocked",
"task.retried",
"task.failed",
"task.completed",
"handoff.requested",
"handoff.completed",
"approval.requested",
"artifact.created",
"timeline.updated",
"budget.alert"
]
},
"metadata": {
"manager_deployment_id": "dep_xxx",
"heicode_deployment_id": "dep_xxx",
"heicode_runtime_bridge": true,
"correlation_id": "corr_xxx"
}
}
```
### Agent Manager 必须消费的字段
| 字段 | 必须 | 说明 |
|---|---:|---|
| `orchestration_plan.objective` | 是 | 用户目标 |
| `orchestration_plan.sub_mode` | 是 | `agile` / `waterfall`；蜂群执行时也要保留此组织方式 |
| `orchestration_plan.risk_level` | 是 | 高危动作必须走审批 |
| `orchestration_plan.budget` | 是 | token / cost / duration 上限 |
| `billing_context.provider` | 是 | 当前为 `newapi` |
| `billing_context.secret_ref` | 是 | 模型网关密钥引用，只能是 `azkv://...` |
| `agents[].role` 或 `role_template` | 是 | 子 Agent 角色 |
| `resource_grants[]` | 是 | 资源授权清单 |
| `resource_grants[].secret_ref` | 凭据资源必填 | 只允许 Key Vault 引用，不允许明文 |
| `callback.url` | 是 | Runtime 回调 Manager 的地址 |
| `callback.signing_secret_ref` | 建议 | HMAC 签名密钥引用 |
| `metadata.manager_deployment_id` | 是 | Manager 侧 deployment id |
| `metadata.correlation_id` | 是 | 全链路追踪 |
### 响应
```json
{
"success": true,
"data": {
"deployment_id": "runtime-dep-123",
"swarm_id": "swarm-123",
"status": "running",
"created_at": "2026-05-28T10:00:00Z",
"estimated_ready_at": "2026-05-28T10:02:00Z"
}
}
```
兼容响应：
```json
{
"deployment_id": "runtime-dep-123",
"swarm_id": "swarm-123",
"status": "running"
}
```
Manager 映射规则：
| Agent Manager 返回字段 | Manager 保存字段 |
|---|---|
| `data.deployment_id` / `deployment_id` / `id` | `runtime_deployment_id` |
| `data.swarm_id` / `swarm_id` / `runtime_swarm_id` | `runtime_swarm_id` |
| `data.status` / `status` / `runtime_status` | `runtime_state` |
## 7. Runtime 必须生成的 task graph
Agent Manager 创建 Swarm Run 后，必须在 Runtime 内部生成任务图，并通过 callback 回写。
每个 task 至少包含：
```json
{
"task_id": "task-backend-1",
"title": "实现后端接口",
"description": "完成 API、校验和测试",
"agent_role": "backend",
"status": "pending",
"depends_on": ["task-design-1"],
"attempt": 1
}
```
状态建议：
| status | 说明 |
|---|---|
| `pending` | 等待执行 |
| `claimed` | 已被 Agent 领取 |
| `running` | 执行中 |
| `blocked` | 阻塞 |
| `handoff_requested` | 等待交接 |
| `retrying` | 重试中 |
| `completed` | 完成 |
| `failed` | 失败 |
## 8. Runtime 回调 Manager
Manager 回调地址：
```http
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
```
也支持 HMAC：
```http
X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>
```
HMAC 签名内容：
```text
timestamp + "." + event_id + "." + raw_body
```
联调前可拉取 Manager 当前接受的事件 schema：
```http
GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
```
### 通用 callback envelope
```json
{
"event_id": "evt_123",
"idempotency_key": "evt_123",
"event_type": "task.claimed",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"agent_instance_id": "agent-backend-1",
"task_id": "task-backend-1",
"occurred_at": "2026-05-28T10:10:00Z",
"correlation_id": "corr_xxx",
"source": "agent-manager-runtime",
"payload": {}
}
```
要求：
1. `event_id` 全局唯一。
2. 重试同一事件必须复用相同 `event_id` 或 `idempotency_key`。
3. `deployment_id` 优先使用 Manager deployment id。
4. 如果只知道 `swarm_id`，Manager 也会按 `runtime_swarm_id` 查找 deployment。
5. `source` 要能区分真实 Runtime，例如 `agent-manager-runtime`，不要写 `simulated`。
## 9. 必须回调的事件和字段
| event_type | 必填字段 | 说明 |
|---|---|---|
| `deployment.status_changed` | `payload.status` | Runtime 整体状态变化 |
| `task.created` | `task_id`, `payload.title` | 任务图新增任务 |
| `task.claimed` | `task_id`, `payload.agent_role` | Agent 领取任务 |
| `task.running` | `task_id`, `payload.agent_role` | Agent 开始执行 |
| `task.heartbeat` | `task_id`, `payload.agent_role` | Agent 心跳 |
| `task.blocked` | `task_id`, `payload.reason` | 任务阻塞 |
| `task.retried` | `task_id`, `payload.attempt` | 任务重试 |
| `task.failed` | `task_id`, `payload.reason` | 任务失败 |
| `task.completed` | `task_id` | 任务完成 |
| `handoff.requested` | `task_id`, `payload.from_role`, `payload.to_role` | 请求交接 |
| `handoff.completed` | `task_id`, `payload.from_role`, `payload.to_role` | 完成交接 |
| `artifact.created` | `artifact.artifact_id` 或 `payload.artifact_id` | 产物生成 |
| `approval.requested` | `payload.approval_id`, `payload.operation`, `payload.risk_level` | 高危审批 |
| `timeline.updated` | `payload.title` | 用户可见时间线 |
| `budget.alert` | `payload.threshold_pct` | 预算告警 |
## 10. artifact.created
Runtime 产生中间产物或最终交付物时回调：
```json
{
"event_id": "evt_artifact_1",
"event_type": "artifact.created",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"task_id": "task-backend-1",
"source": "agent-manager-runtime",
"artifact": {
"artifact_id": "art_backend_patch_1",
"artifact_type": "code_patch",
"title": "Backend API patch",
"summary": "新增任务创建和状态查询接口",
"uri": "git://heicode-manager/branches/feature/task-api",
"checksum": "sha256:abc123",
"metadata": {
"agent_role": "backend",
"redacted": true
}
}
}
```
支持的 `artifact_type`：
| 类型 | 说明 |
|---|---|
| `code_patch` | 代码补丁或分支 |
| `document` | 文档 |
| `test_report` | 测试报告 |
| `deployment_manifest` | 部署清单 |
| `log_bundle` | 日志包 |
| `other` | 其他 |
要求：
1. 大文件不要内联到 callback body。
2. `summary` 可展示给用户，不得包含密钥。
3. `uri` 可以是 `git://`、`artifact://`、`azblob://`、`https://`。
4. metadata 必须脱敏。
## 11. approval.requested 与审批结果
高危动作前 Runtime 必须暂停，并回调：
```json
{
"event_id": "evt_approval_1",
"event_type": "approval.requested",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"task_id": "task-deploy-1",
"source": "agent-manager-runtime",
"payload": {
"approval_id": "runtime-approval-1",
"operation": "deploy.production",
"resource_id": "prod-env",
"resource_type": "azure",
"resource_scope": "resource-group/heicode-prod",
"target_role": "ops",
"risk_level": "high",
"requires_credential": true,
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/prod-deploy",
"ttl_seconds": 600,
"reason": "需要部署到生产环境"
}
}
```
Manager / 客户端审批后，Manager 调 Runtime：
```http
POST /api/swarms/{swarm_id}/approvals/{approval_id}
Authorization: Bearer <service_token>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: approval-decision-<approval_id>-<decision>
Content-Type: application/json
```
请求：
```json
{
"approval_id": "runtime-approval-1",
"decision": "approved",
"reason": "用户已确认",
"manager_deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"decided_by": "user:22",
"decided_at": "2026-05-28T10:20:00Z",
"credential_lease": {
"lease_id": "lease_xxx",
"credential_ref": "lease://runtime/runtime-approval-1",
"expires_at": "2026-05-28T10:30:00Z"
}
}
```
`decision` 枚举：
| decision | Runtime 行为 |
|---|---|
| `approved` | 继续原高危动作 |
| `rejected` | 停止该动作，回调 `timeline.updated` 或 `task.failed` |
要求：
1. Runtime 收到 `approved` 后才可以继续高危动作。
2. Runtime 收到 `rejected` 后不能继续执行该动作。
3. Runtime 不得把 `credential_ref` 展开写入日志或 artifact metadata。
4. Runtime 必须把审批结果后的状态继续通过 callback 回写。
## 12. 日志、指标和用量
### 日志
建议提供：
```http
GET /api/swarms/{swarm_id}/logs?limit=100&cursor=<cursor>
```
响应：
```json
{
"success": true,
"data": {
"items": [
{
"timestamp": "2026-05-28T10:21:00Z",
"level": "info",
"agent_role": "backend",
"task_id": "task-backend-1",
"message": "test completed",
"redacted": true
}
],
"next_cursor": ""
}
}
```
### 指标
建议提供：
```http
GET /api/swarms/{swarm_id}/metrics?window=15m&step=60s
```
响应：
```json
{
"success": true,
"data": {
"swarm_id": "swarm-123",
"agent_metrics": [
{
"agent_instance_id": "agent-backend-1",
"agent_role": "backend",
"task_id": "task-backend-1",
"status": "running",
"cpu_percent": 12.5,
"memory_bytes": 268435456,
"uptime_seconds": 300
}
]
}
}
```
### 用量
Runtime 调模型时必须带关联字段：
| 字段 | 说明 |
|---|---|
| `manager_deployment_id` | Manager deployment id |
| `swarm_id` | Runtime swarm id |
| `task_id` | 当前任务 |
| `agent_role` | Agent 角色 |
| `model_id` | 使用模型 |
| `correlation_id` | 全链路追踪 |
Runtime 可通过 `budget.alert` 或 `timeline.updated` 回传用量摘要。
## 13. 安全约束
必须遵守：
1. 禁止在请求、callback、日志、artifact metadata 中出现明文密码、Token、私钥、连接串、云 access key、模型 key。
2. 长期凭据只能通过 `azkv://<vault>/secrets/<name>` 传引用。
3. Runtime 可以把短期租约写成 `lease://...`，但不能写真实密钥。
4. `secret_ref`、`credential_ref` 只能作为引用使用，不能在用户可见内容中展开。
5. 所有 callback payload 必须脱敏。
6. 高危动作必须先 `approval.requested`，不能先执行后补审批。
## 14. 错误码建议
| HTTP | code | 场景 |
|---:|---|---|
| 401 | `UNAUTHORIZED` | service token 无效 |
| 403 | `FORBIDDEN` | 权限不足 |
| 404 | `SWARM_NOT_FOUND` | swarm 不存在 |
| 409 | `IDEMPOTENCY_CONFLICT` | 幂等键冲突 |
| 422 | `VALIDATION_ERROR` | 请求字段缺失 |
| 422 | `SECRET_REF_INVALID` | `secret_ref` 非 `azkv://...` |
| 422 | `POLICY_REJECTED` | 高危策略拒绝 |
| 500 | `INTERNAL_ERROR` | Runtime 内部错误 |
错误响应：
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "resource_grants[0].secret_ref is required",
"request_id": "corr_xxx"
}
}
```
## 15. 联调验收清单
| 步骤 | 操作 | 通过标准 |
|---:|---|---|
| 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 可见 |
| 5 | Runtime 回调 `task.claimed` / `task.heartbeat` | Manager 可看到 Agent 领取和心跳 |
| 6 | Runtime 回调 `handoff.requested` / `handoff.completed` | Manager 可看到交接 |
| 7 | Runtime 回调 `artifact.created` | Manager artifact 列表可见 |
| 8 | Runtime 回调 `approval.requested` | Manager approval 列表出现 pending |
| 9 | 客户端 / Manager approve | Runtime 收到 decision 并继续 |
| 10 | 客户端 / Manager reject | Runtime 收到 decision 并停止对应动作 |
| 11 | Runtime 回传 logs / metrics / usage | Manager 可查询或 timeline 可见 |
| 12 | Runtime 回调最终 `deployment.status_changed=completed` | Manager 和客户端看到完成 |
## 16. 当前不能误报完成的项
以下项只有在 Agent Manager 真实实现并联调后才能算完成：
1. 真实 Swarm Run 创建成功。
2. 真实 task graph 生成。
3. 真实 Agent claim / heartbeat。
4. 真实 handoff / retry / blocked。
5. 真实 artifact 产出。
6. 审批后 Runtime 继续或停止。
7. Runtime 真实日志和指标。
8. 子 Agent 模型用量归属。
9. 最终交付物回到客户端。
Manager 本地模拟事件、测试桩、空态页面和 schema 校验只能证明 Manager 接收和展示能力，不能证明蜂群生产闭环完成。
docs/integration/AgentManager蜂群Runtime联调待确认与补充要求.md
-491
View File
@@ -1,491 +0,0 @@
# Agent Manager 蜂群 Runtime 联调待确认与补充要求
更新时间：2026-05-29
发给：Agent Manager / HeiCode-Swarm Runtime 负责人
范围：仅针对蜂群模式，不包含普通 sub 敏捷模式。
## 1. 先明确边界
普通 sub 模式和蜂群模式是两套不同的运行时部署，不能混用。
| 模式 | Runtime | 当前已知地址 | 说明 |
|---|---|---|---|
| 普通 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 后续需要按模式分别配置，不应只用一套 `AGENT_RUNTIME_BASE_URL` 混跑。
## 2. 本次读取到的蜂群 Runtime 新能力
根据 HeiCode-Swarm 最新 `蜂群对接文档.md` 和代码，蜂群 Runtime 已经补充以下接口：
| 能力 | 路径 | 当前判断 |
|---|---|---|
| 健康检查 | `GET /api/agent/health` | 已提供 |
| 创建蜂群 run | `POST /api/swarms` | 已提供 |
| 兼容创建入口 | `POST /api/agent/deployments` | 已提供 |
| 查询 swarm 详情 | `GET /api/swarms/{swarm_id}` | 已提供 |
| 查询任务图 | `GET /api/swarms/{swarm_id}/tasks` | 已提供 |
| 查询日志 | `GET /api/swarms/{swarm_id}/logs` | 已提供 |
| 查询指标 | `GET /api/swarms/{swarm_id}/metrics` | 已提供 |
| 停止 swarm | `POST /api/swarms/{swarm_id}/stop` | 已提供 |
| 审批结果回传 | `POST /api/swarms/{swarm_id}/approvals/{approval_id}` | 已提供 |
| callback token / HMAC | Runtime callback Manager | 代码支持 |
| `azkv://` 校验 | 请求体 secret 引用 | 代码支持 |
| 幂等创建 | `X-Idempotency-Key` | 代码支持 |
本地契约测试也已确认通过：
```text
python3 scripts/test-runtime-contract.py
runtime contract checks passed
```
## 3. 实测结果
### 3.1 健康检查通过
请求：
```bash
curl http://52.139.240.116:8000/api/agent/health
```
返回核心内容：
```json
{
"success": true,
"data": {
"status": "healthy",
"service": "heicode-swarm-runtime",
"version": "1.0.0",
"runtime": "aks",
"capabilities": [
"swarm.create",
"task.flow",
"handoff.events",
"artifact.events",
"approval.pause_resume",
"deployment.stop",
"runtime.tasks.query",
"runtime.logs.query",
"runtime.metrics.query"
]
}
}
```
### 3.2 创建接口鉴权已通过
Agent Manager / 蜂群 Runtime 已提供当前部署认可的 Runtime Bearer token。使用该 token 后，`POST /api/swarms` 不再返回 401。
```bash
curl -X POST http://52.139.240.116:8000/api/swarms \
-H "Authorization: Bearer <runtime-service-token>" \
-H "Content-Type: application/json" \
-H "X-Correlation-Id: corr_token_check_local" \
-H "X-Idempotency-Key: codex-swarm-token-check" \
-d '<valid-swarm-create-body>'
```
返回：
```json
{
"success": true,
"data": {
"deployment_id": "runtime-dep-e9ef617146fd",
"runtime_deployment_id": "runtime-dep-e9ef617146fd",
"manager_deployment_id": "dep_token_check_local",
"swarm_id": "swarm-64004a6aaf67",
"status": "running",
"created": true
}
}
```
结论：Runtime token 阻塞已解决。具体 token 不写入 Markdown 或 Git。
### 3.3 查询和停止接口已通过
对 `swarm-64004a6aaf67` 查询结果：
| 接口 | 结果 |
|---|---|
| `GET /api/swarms/{swarm_id}` | 成功，返回 Runtime run 详情 |
| `GET /api/swarms/{swarm_id}/tasks` | 成功 |
| `GET /api/swarms/{swarm_id}/logs` | 成功，返回 Runtime event 列表 |
| `GET /api/swarms/{swarm_id}/metrics` | 成功，返回任务数、运行时长、Agent 数等轻量指标 |
| `POST /api/swarms/{swarm_id}/stop` | 成功，状态变为 `stopped` |
### 3.4 新发现：线上蜂群 Runtime 仍只生成单任务
2026-05-29 已按 `HeiCode-Swarm/蜂群对接文档.md` 的结构真实请求线上蜂群 Runtime：
```text
POST http://52.139.240.116:8000/api/swarms
Authorization: Bearer <runtime-service-token>
```
第一组使用文档中的单 Agent 结构，`agents` 放在 `orchestration_plan.agents`，角色为 `backend`。创建成功：
```json
{
"success": true,
"data": {
"runtime_deployment_id": "runtime-dep-fc99510eb2c5",
"manager_deployment_id": "dep_doc_single",
"swarm_id": "swarm-004f1ae3a114",
"status": "running"
}
}
```
但查询任务后，线上 Runtime 没有保留文档请求中的 `backend` 角色，而是生成 `general` 单任务：
```json
{
"task_id": "swarm-004f1ae3a114-task-1",
"title": "Swarm objective",
"agent_role": "general",
"context": {
"workflow_mode": "single_agent",
"allow_handoff": false
}
}
```
第二组使用同样文档结构，但传入 3 个 agents：`planner`、`builder`、`reviewer`。创建成功：
```json
{
"success": true,
"data": {
"runtime_deployment_id": "runtime-dep-ba9de6fe1df3",
"manager_deployment_id": "dep_doc_multi",
"swarm_id": "swarm-ee319f1d4705",
"status": "running"
}
}
```
但查询任务后仍只生成 1 个 `general` 任务：
```json
{
"tasks": [
{
"title": "Swarm objective",
"agent_role": "general",
"status": "pending",
"task_graph_id": "task-1",
"context": {
"workflow_mode": "single_agent",
"allow_handoff": false
}
}
]
}
```
两组测试的日志均只出现 `Created 1 task(s)`，停止接口均返回 `status=stopped`。
这与蜂群设计要求的“动态任务图、能力编队、handoff、协作任务链”仍有差距。当前线上 Runtime 看起来仍是 single-agent fallback 路径，尚未按请求中的 3 个 planner/builder/reviewer 任务生成真实 task graph。
### 3.5 Gitee main 与线上 Runtime 行为不一致
已检查项目地址：
```text
http://gitee.ath.cx:3000/taijibaga/HeiCode-Swarm
```
当前 main commit：
```text
802bbe97ca278d2da3c70a3e471219db62c01c98 对接文档
```
仓库 main 中 `orchestrator/swarm_runtime.py` 的 `build_task_descriptions()` 逻辑会读取：
```python
agents = plan.get("agents") or body.get("agents") or []
```
如果请求里传入 3 个 agents，本地按同样 payload 测试该函数，结果会生成 3 个任务：
```text
plan-1 planner
build-1 builder
verify-1 reviewer
count=3
```
但线上 `http://52.139.240.116:8000` 对同样结构只生成：
```text
task-1 general
workflow_mode=single_agent
allow_handoff=false
```
另外，线上返回中的 `workflow_mode`、`allow_handoff`、`required_capabilities`、`source=runtime_bridge` 等字段，在当前 Gitee main 的 `orchestrator/swarm_runtime.py` 中没有对应代码。
因此当前判断是：
1. 线上 `52.139.240.116:8000` 运行的镜像/代码不是 Gitee main 当前代码；或
2. 线上部署使用了未提交到 Gitee main 的分支/镜像；或
3. 线上通过环境变量或另一套 runtime bridge 强制走 single-agent fallback。
请 Agent Manager / HeiCode-Swarm 负责人确认线上部署的镜像 tag、代码 commit、分支，以及是否启用了 single-agent fallback 配置。
## 4. Agent Manager / 蜂群 Runtime 需要提供或确认
### P0 必须先提供
| 项 | 需要提供 / 确认 | 原因 |
|---|---|---|
| 蜂群 Runtime 调用 token | 已提供并验证可用；后续需要通过安全渠道配置到 Manager，不写入 Git | Manager 调 `POST /api/swarms` 需要 Bearer 鉴权 |
| 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 根据这些字段落库和展示 |
callback 地址：
```text
https://code.xinghanlab.com/api/agent/callbacks/swarm-events
```
callback schema 查询：
```text
GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
```
说明：具体 token / signing secret 不应写入 Markdown 或 Git，请通过安全渠道提供。
### P0 端到端能力
| 能力 | 当前情况 | 需要补充或证明 |
|---|---|---|
| Manager 创建蜂群 run | Runtime 直连创建已跑通；Manager 生产尚未切蜂群专用配置 | 将 Runtime token 安全配置到 Manager 后跑真实 Manager 创建 |
| 动态任务图 | 当前线上 Runtime 只生成 1 个 `general` 任务，`workflow_mode=single_agent` | 至少根据目标生成 2-3 个可追踪任务，并回调多条 `task.created` |
| Agent claim / running / heartbeat | 代码里有 dispatch 和事件能力 | 需要真实 Agent 连接、claim、running、heartbeat 证据 |
| handoff | 事件类型和部分逻辑存在 | 需要真实 `handoff.requested` / `handoff.completed` 场景 |
| 失败回流 | 有 `task.blocked`、`task.failed`、`task.retried` 事件类型 | 需要一次真实失败、重试或 blocked 证据 |
| artifact | Agent 返回 `git_branch` 时会发 artifact | 需要真实 `artifact.created` 回 Manager，带 `uri`、`summary`、`artifact_type` |
| 审批暂停 / 恢复 | high risk 会 `waiting_approval`，支持 decision 接口 | 需要真实 `approval.requested` -> Manager approve/reject -> Runtime 继续/阻塞 |
| 日志 | `/logs` 当前主要来自 Runtime 事件 | 需要说明是否提供真实 Agent / Pod 日志，或至少返回可排障日志摘要 |
| 指标 | `/metrics` 返回轻量聚合 | 需要补充真实运行时长、任务耗时、Agent 数、失败数、资源用量 |
| 用量 / 成本 | 只有 Agent result 带 `usage` 时才回传 | 需要真实 NewAPI token、model_cost_usd、runtime_seconds 或明确暂无 |
| callback 可靠性 | 当前代码 callback 失败记录 warning | 需要确认是否有重试、死信、人工重放；没有则列为未完成 |
## 5. 建议双方统一的蜂群创建请求
Heicode Manager 调蜂群 Runtime：
```http
POST http://52.139.240.116:8000/api/swarms
Authorization: Bearer <runtime-service-token>
X-User-ID: <manager-user-id>
X-Binding-Scope: <binding-scope>
X-Correlation-ID: <correlation-id>
X-Idempotency-Key: manager-<manager-deployment-id>
Content-Type: application/json
```
请求体建议：
```json
{
"orchestration_plan": {
"intent_id": "task_xxx",
"objective": "完成本轮用户目标",
"sub_mode": "goal_driven_swarm",
"risk_level": "medium",
"budget": {
"duration_seconds": 3600,
"token_limit": 20000,
"max_cost_usd": 8
},
"user_context": {
"user_id": "22",
"channel_id": "heicode",
"binding_scope": "task-task-xxx"
},
"agents": [
{
"task_id": "plan-1",
"role": "planner",
"title": "目标理解与任务生成",
"description": "整理用户目标、资源约束和验收标准",
"depends_on": []
},
{
"task_id": "build-1",
"role": "builder",
"title": "代码或文档变更",
"description": "根据目标生成可验证交付物",
"depends_on": ["plan-1"]
},
{
"task_id": "verify-1",
"role": "reviewer",
"title": "验证与交付整理",
"description": "检查交付物并形成验收摘要",
"depends_on": ["build-1"]
}
]
},
"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",
"task.created",
"task.claimed",
"task.running",
"task.heartbeat",
"task.blocked",
"task.retried",
"task.failed",
"task.completed",
"handoff.requested",
"handoff.completed",
"approval.requested",
"artifact.created",
"budget.alert",
"timeline.updated"
]
},
"metadata": {
"manager_deployment_id": "dep_xxx",
"heicode_deployment_id": "dep_xxx",
"correlation_id": "corr_xxx",
"heicode_runtime_bridge": true,
"runtime_mode": "swarm"
},
"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"
},
"resource_grants": [
{
"grant_id": "grant-task-git",
"resource_id": "repo-main",
"resource_type": "git",
"permission_scope": ["repo:read", "repo:write:feature-branches"],
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
"ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
"target_role": "builder"
}
]
}
```
## 6. Secret 引用格式需要统一
Heicode Manager 当前正式约束建议使用：
```text
azkv://<vault>/secrets/<name>
```
例如：
```text
azkv://heicode-kv.vault.azure.net/secrets/repo-main
azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key
```
HeiCode-Swarm 文档中示例为：
```text
azkv://heicode/git-write-token
```
建议 Agent Manager / 蜂群 Runtime 确认是否可以接受标准 Key Vault 形式，并在示例文档中同步，避免后续联调时因为 `secret_ref` 格式不一致失败。
## 7. Manager 侧后续配置建议
Heicode Manager 需要保留普通 sub 和蜂群两套 Runtime 配置。建议后续拆成：
```text
# 普通 sub 敏捷模式
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
SWARM_RUNTIME_CREATE_PATH=/api/swarms
SWARM_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
SWARM_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
SWARM_RUNTIME_SERVICE_TOKEN=<runtime-service-token>
```
如果短期 Manager 还只有一套 `AGENT_RUNTIME_*`，只能临时切换到蜂群 Runtime 做专项联调，不能同时代表普通 sub 和蜂群都在线。
## 8. 蜂群 MVP 验收口径
根据蜂群设计文档和 Heicode 产品资料包，蜂群 MVP 不是“接口能创建一个 run”就完成。最小验收应至少满足：
| 验收项 | 成功标准 |
|---|---|
| 创建 | Manager 调 `POST /api/swarms` 成功，Runtime 返回真实 `swarm_id` |
| 任务图 | Runtime 至少生成 2 个可追踪任务，并可通过 `/tasks` 查询 |
| Agent 执行 | 至少一个真实 Agent claim、running、completed |
| 交接或失败回流 | 至少出现一次 handoff，或一次失败/blocked/retry 并可解释 |
| artifact | 至少 1 个真实 artifact 回 Manager，可在 Manager 查询 |
| 审批 | high risk 流程能 `approval.requested`，Manager approve/reject 后 Runtime 状态变化 |
| 日志 | Manager 或 Runtime 能查到可排障日志，不只是空占位 |
| 指标 | 能看到任务数、状态、耗时、Agent 数、失败数等真实指标 |
| 用量 | 能回传 token、模型成本或明确当前未接真实模型成本 |
| 安全 | 请求、callback、日志、artifact metadata 不出现明文长期密钥 |
| 幂等 | 同一个 `X-Idempotency-Key` 重试不会创建重复 swarm |
| 停止 | Manager stop 后 Runtime 状态为 `stopped`，不继续执行 |
## 9. 建议下一次联调步骤
1. Heicode Manager 新增或临时配置蜂群 Runtime base URL 和 Runtime Bearer token。
2. Agent Manager / 蜂群 Runtime 确认 callback token 或 HMAC secret 已和 Heicode Manager 生产端一致。
3. 使用测试用户通过 Manager 创建蜂群 run。
4. 验证 Manager 保存 `runtime_deployment_id` 和 `runtime_swarm_id`。
5. 验证 Runtime 不再只生成 single-agent fallback，而是生成多任务 task graph。
6. 验证 Runtime 主动 callback：
- `deployment.status_changed`
- `task.created`
- `task.claimed`
- `task.running`
- `task.completed`
- `artifact.created`
- `timeline.updated`
7. 验证查询：
- `GET /api/swarms/{swarm_id}`
- `GET /api/swarms/{swarm_id}/tasks`
- `GET /api/swarms/{swarm_id}/logs`
- `GET /api/swarms/{swarm_id}/metrics`
8. 验证 high risk 审批：
- Runtime 回调 `approval.requested`
- Manager approve
- Runtime 收到 decision 并继续
9. 验证 stop：
- Manager stop
- Runtime stopped
- 不再继续发 running/completed callback
## 10. 当前结论
蜂群 Runtime 当前已经具备可联调的接口骨架和一部分运行时能力，但还没有完成 Heicode 产品设计要求的完整蜂群 MVP 生产验收。
当前最优先阻塞项是：
1. 将已验证可用的蜂群 Runtime Bearer token 通过安全渠道配置到 Heicode Manager。
2. 确认 Runtime 回调 Manager 的 callback token 或 HMAC secret 已生效。
3. 修正线上 Runtime 只生成 1 个 `general` 任务的问题，使其按目标生成真实多任务 task graph。
4. 确认线上镜像/代码 commit 与 Gitee main 是否一致；如果不一致，需要先部署包含多任务 task graph 逻辑的版本。
5. 跑通一次真实 Manager -> 蜂群 Runtime -> Manager callback 的端到端链路。
6. 补齐真实 Agent 执行、handoff/失败回流、artifact、日志、指标、usage/cost 的生产证据。
docs/integration/agent-manager-swarm-runtime-change-request.md
-403
View File
@@ -1,403 +0,0 @@
# Agent Manager / HeiCode-Swarm 蜂群对接改造请求
更新时间：2026-05-27
发起方：Heicode Manager
用途：给 Agent Manager / HeiCode-Swarm 侧确认需要补齐或对齐的生产接口，便于 Heicode 桌面客户端 -> Manager -> 蜂群 Runtime 跑完整蜂群流程。
## 一、当前 Manager 已准备好的能力
| 能力 | Manager 状态 |
|---|---|
| 用户态创建 | `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`，不传长期明文密钥 |
## 二、Runtime 需要提供的接口
### 1. 健康检查
```http
GET /api/agent/health
```
如果蜂群侧沿用现有 Orchestrator，也可以临时配置为：
```http
GET /health
```
响应建议：
```json
{
"success": true,
"data": {
"status": "healthy",
"service": "heicode-swarm-runtime",
"version": "x.y.z"
}
}
```
### 2. 创建 Swarm Run
生产目标接口：
```http
POST /api/swarms
Authorization: Bearer <service_token>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: manager-<deployment_id>
Content-Type: application/json
```
Manager 当前也可兼容配置：
```text
AGENT_RUNTIME_CREATE_PATH=/api/swarms
```
请求核心字段：
```json
{
"orchestration_plan": {
"sub_mode": "agile",
"risk_level": "high",
"user_context": {
"user_id": "22",
"channel_id": "heicode"
},
"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"
},
"agents": [],
"resource_grants": []
},
"agents": [
{
"role": "backend",
"resource_grants": []
}
],
"resource_grants": [
{
"grant_id": "grant-task-backend",
"resource_type": "git",
"permission_scope": ["read", "write"],
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main"
}
],
"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",
"task.created",
"task.claimed",
"task.heartbeat",
"task.completed",
"task.failed",
"handoff.requested",
"approval.requested",
"artifact.created",
"timeline.updated"
]
},
"metadata": {
"manager_deployment_id": "dep_xxx",
"heicode_runtime_bridge": true,
"correlation_id": "corr_xxx"
}
}
```
响应必须返回至少一个 Runtime 标识：
```json
{
"success": true,
"data": {
"deployment_id": "runtime-dep-123",
"swarm_id": "swarm-123",
"status": "created"
}
}
```
兼容要求：
1. `deployment_id` 可作为 Runtime deployment id。
2. `swarm_id` 用于蜂群任务图、审批和事件关联。
3. 如果 Runtime 只返回顶层 JSON，不包 `data`，Manager 也能解析。
4. 不要要求 Manager 发送长期明文密钥。
### 3. 停止 Runtime Run
默认路径：
```http
POST /api/agent/deployments/{deployment_id}/stop
Authorization: Bearer <service_token>
Content-Type: application/json
```
请求：
```json
{
"reason": "Heicode Manager requested stop",
"manager_deployment_id": "dep_xxx"
}
```
响应：
```json
{
"success": true,
"data": {
"deployment_id": "runtime-dep-123",
"swarm_id": "swarm-123",
"status": "stopped"
}
}
```
如果蜂群侧希望使用：
```http
POST /api/swarms/{swarm_id}/stop
```
则 Manager 可通过环境变量配置：
```text
AGENT_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
```
## 三、Runtime 回调 Manager
统一回调入口：
```http
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
```
也支持 HMAC：
```http
X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>
```
签名内容：
```text
timestamp + "." + event_id + "." + raw_body
```
### 通用事件 envelope
```json
{
"event_id": "evt_123",
"idempotency_key": "evt_123",
"event_type": "task.completed",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"agent_instance_id": "agent-backend-1",
"task_id": "task-backend-1",
"occurred_at": "2026-05-27T10:00:00Z",
"correlation_id": "corr_xxx",
"source": "heicode-swarm-runtime",
"payload": {}
}
```
必须支持的事件类型：
| event_type | 用途 |
|---|---|
| `deployment.status_changed` | Runtime 整体状态变化 |
| `task.created` | 任务图新增任务 |
| `task.claimed` | Agent claim 任务 |
| `task.heartbeat` | Agent 执行心跳 |
| `task.completed` | 任务完成 |
| `task.failed` | 任务失败 |
| `handoff.requested` | 任务交接 |
| `handoff.completed` | 交接完成 |
| `approval.requested` | 请求用户审批 |
| `artifact.created` | 产物生成 |
| `timeline.updated` | 用户可见时间线 |
### artifact 回调
```json
{
"event_id": "evt_artifact_1",
"event_type": "artifact.created",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"task_id": "task-backend-1",
"artifact": {
"artifact_id": "art_backend_patch_1",
"artifact_type": "code_patch",
"title": "Backend patch",
"summary": "完成后端接口修改",
"uri": "git://repo#agent-backend-1-results",
"checksum": "sha256:xxx",
"metadata": {
"commit_sha": "abc123",
"branch": "agent-backend-1-results",
"redacted": true
}
}
}
```
### approval 请求回调
```json
{
"event_id": "evt_approval_1",
"event_type": "approval.requested",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"task_id": "task-deploy-1",
"payload": {
"approval_id": "runtime-approval-1",
"operation": "production_deploy",
"resource_id": "azure-prod",
"resource_type": "cloud_resource",
"resource_scope": "/subscriptions/.../resourceGroups/prod",
"target_role": "ops",
"risk_level": "high",
"requires_credential": true,
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/azure-prod-sp",
"ttl_seconds": 900,
"reason": "部署到生产环境需要用户确认"
}
}
```
## 四、Manager 回传审批结果给 Runtime
Manager 已支持调用该接口。蜂群侧需要实现接收。
默认路径：
```http
POST /api/swarms/{swarm_id}/approvals/{approval_id}
Authorization: Bearer <service_token>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: approval-decision-<approval_id>-<decision>
Content-Type: application/json
```
Manager 可配置：
```text
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
```
请求：
```json
{
"approval_id": "runtime-approval-1",
"decision": "approved",
"manager_deployment_id": "dep_xxx",
"runtime_deployment_id": "runtime-dep-123",
"swarm_id": "swarm-123",
"operation": "production_deploy",
"resource_id": "azure-prod",
"resource_type": "cloud_resource",
"resource_scope": "/subscriptions/.../resourceGroups/prod",
"target_role": "ops",
"risk_level": "high",
"requires_credential": true,
"credential_ref": "lease://agent/lease_xxx",
"lease_id": "lease_xxx",
"lease_expires_at": 1770000000000,
"decided_by": "user:22",
"reason": "用户确认部署",
"decided_at": 1770000000000
}
```
拒绝时：
```json
{
"approval_id": "runtime-approval-1",
"decision": "rejected",
"manager_deployment_id": "dep_xxx",
"runtime_deployment_id": "runtime-dep-123",
"swarm_id": "swarm-123",
"reason": "风险过高",
"decided_by": "user:22",
"decided_at": 1770000000000
}
```
安全要求：
1. Manager 不会在该请求中发送 `secret_ref`。
2. 如果审批通过且需要凭证，只发送短期 `credential_ref = lease://agent/...`。
3. Runtime 不得把 `credential_ref`、service token、签名密钥写入日志或 artifact metadata。
4. Runtime 收到 `approved` 后继续原高危动作；收到 `rejected` 后停止该动作并回调 `timeline.updated` 或 `task.failed/blocked`。
响应：
```json
{
"success": true,
"data": {
"approval_id": "runtime-approval-1",
"status": "accepted"
}
}
```
## 五、当前 HeiCode-Swarm 现状与建议
当前 `HeiCode-Swarm` 可见 Orchestrator 入口是：
| 当前入口 | 可用性 | 建议 |
|---|---|---|
| `GET /health` | 可直接作为健康检查 | Manager `AGENT_RUNTIME_HEALTH_PATH=/health` |
| `POST /tasks` | 可临时创建任务 | 只能做兼容桥接，不建议作为最终生产契约 |
| `GET /tasks` | 可查任务 | 后续需要映射到 callback/timeline |
| `GET /agents` | 可查 Agent | 后续需要回调 agent status |
| `GET /handoffs` | 可查 handoff | 后续需要回调 handoff events |
| `GET /metrics` | 可查指标 | 后续需要按 deployment/swarm 关联 |
| `WS /ws/{agent_id}` | Agent 内部通道 | Manager 不直接接 WS |
建议蜂群侧优先补正式 `POST /api/swarms` 和 approval decision 接口；如果短期只想先跑通，可由 Manager 临时把 create path 指到 `/tasks`，但这会缺少 `secret_ref`、resource grants、approval policy、artifact callback 等正式字段。
## 六、联调验收
最小验收顺序：
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 可见。
5. Runtime 回调 `artifact.created`，Manager artifacts 可见。
6. Runtime 回调 `approval.requested`，Manager/客户端能看到 pending approval。
7. 用户 approve/reject 后，Runtime 收到 approval decision。
8. Runtime 根据 decision 继续或停止，并回调最终结果。
9. 全链路无明文长期密钥、模型 key、云 access key、私钥、连接串。
docs/integration/agent-platform-request-contract.md
-961
View File
@@ -1,961 +0,0 @@
# Manager → Agent 平台接口参数文档
**版本**: v0.3（P1/P5 联调契约）
**生效日期**: 2026-05-03
**状态**: 联调准备；当前仓库提供 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(agent)`。本文中仍出现的 `tenant_id/project_id` 只表示旧字段兼容或历史接口命名，不应作为新功能设计依据。
**安全红线**: 请求体只允许传资源元数据、权限范围与 `secret_ref`/环境变量名；不得传明文密码、Token、私钥、连接串或云访问密钥。
> 本文档描述 Manager 对 Agent 平台的出站集成契约。当前仓库中 `/api/agent/*` 是 Manager 侧最小控制面/模拟端点，用于校验同一套 payload 结构；生产接入时，Manager 应将下列请求发送到 Agent 平台网关。
## 0. 概述
本文档按登录接口文档的对接方式组织：先定义接入信息，再逐个接口给出请求、响应、错误和安全约束。接口分组如下：
| 接口 | 用途 | 当前性质 |
|---|---|---|
| `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 管理后台开放。生产部署动作只有实际执行并通过日志/监控/审计验证后，才能在报告中标记为“已部署”。
---
## 1. 接入约定
### 1.1 Base URL
由部署环境配置，不写入仓库。例如：
```text
AGENT_PLATFORM_BASE_URL=https://agent-platform.example.com
```
联调环境建议使用独立域名或内网网关，示例不得包含真实凭据：
```text
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://agent-platform.example.com/api/agent/deployments
```
### 1.2 通用 Header
| Header | 必填 | 说明 |
|---|---:|---|
| `Authorization: Bearer <manager-service-token>` | 是 | Manager 服务身份令牌，由 Secret Store/运行环境注入。 |
| `Content-Type: application/json` | POST/PUT 是 | JSON 请求体。 |
| `X-User-Id: <user_id>` | 建议 | 登录用户边界；也可从 Manager 服务端 token 或 body `user_context.user_id` 推导。 |
| `X-Binding-Scope: <binding_scope>` | 建议 | Git/SK/云资源作用域；也可从 `resource_grants[].binding_scope` 推导。 |
| `X-Correlation-Id: <uuid>` | 是 | Manager 生成，全链路追踪。 |
| `X-Request-Id: <uuid>` | 建议 | 单次 HTTP 请求追踪 ID，可与 correlation_id 不同。 |
| `Idempotency-Key: <uuid>` | 创建类接口建议 | 避免重试造成重复部署。 |
### 1.3 通用响应包裹
成功：
```json
{
"success": true,
"data": {}
}
```
失败：
```json
{
"success": false,
"message": "human readable message",
"error": {
"code": "POLICY_REJECTED",
"message": "human readable message",
"request_id": "req_xxx"
}
}
```
建议错误码：
| code | 场景 |
|---|---|
| `POLICY_REJECTED` | 缺必填字段、权限策略不满足、风险等级非法。 |
| `BUDGET_EXCEEDED` | 超过 token/金额/时长预算。 |
| `MODEL_NOT_ALLOWED` | agent 默认模型不在允许列表内。 |
| `FORBIDDEN_SCOPE` | Header 与 body/query 的用户或资源作用域不一致。 |
| `RESOURCE_GRANT_INVALID` | Resource Grant 字段缺失、跨用户/跨资源作用域/角色不匹配。 |
| `RESOURCE_GRANT_SECRET_REF_REQUIRED` | 凭据型资源缺少 `secret_ref`。 |
| `RESOURCE_GRANT_SECRET_REJECTED` | 请求中出现明文密钥字段。 |
| `SK_SOURCE_UNRESOLVABLE` | SK 来源不可解析。 |
| `DEPLOYMENT_CONFLICT` | 部署不存在、状态冲突或重复提交。 |
| `NOT_FOUND` | deployment、agent instance、snapshot 或审计资源不存在。 |
| `CURSOR_EXPIRED` | 分页游标过期或不属于当前查询条件。 |
| `RATE_LIMITED` | 平台限流；响应头建议包含 `Retry-After`。 |
| `INTERNAL_ERROR` | 平台内部错误；Manager 应记录 request_id 并重试或提示稍后处理。 |
### 1.4 通用错误处理
| HTTP | business code | Manager 处理建议 |
|---:|---|---|
| 400 | `POLICY_REJECTED` / `RESOURCE_GRANT_INVALID` | 标记部署失败，展示校验原因，不自动重试。 |
| 401 | `UNAUTHORIZED` | 检查 Manager 服务令牌的 `secret_ref`/环境注入，不把令牌写入日志。 |
| 403 | `FORBIDDEN_SCOPE` / `MODEL_NOT_ALLOWED` | 阻断本次部署，写审计事件。 |
| 404 | `NOT_FOUND` | 对查询类接口返回空态；对控制类接口提示资源不存在。 |
| 409 | `DEPLOYMENT_CONFLICT` | 使用 `Idempotency-Key` 查询既有结果，避免重复创建。 |
| 410 | `CURSOR_EXPIRED` | 丢弃 cursor，使用 `since` 重新拉取。 |
| 422 | `RESOURCE_GRANT_SECRET_REF_REQUIRED` / `RESOURCE_GRANT_SECRET_REJECTED` | 要求 Manager 重新生成只含 `secret_ref` 的 payload。 |
| 429 | `RATE_LIMITED` | 按 `Retry-After` 退避重试。 |
| 500/503 | `INTERNAL_ERROR` | 指数退避重试；超过阈值后转人工排查。 |
---
## 2. 创建子 Agent 部署
### 2.1 Endpoint
```http
POST /api/agent/deployments
```
### 2.2 请求体
```json
{
"orchestration_plan": {
"intent_id": "intent_20260502_001",
"template_hint": "manager-resource-binding",
"objective": "为已绑定的代码仓库启动 builder 子 Agent，允许其读取 SK 并在限定路径内提交代码",
"risk_level": "low",
"budget": {
"max_tokens": 100000,
"max_cost_usd": 30,
"max_duration_sec": 7200
},
"user_context": {
"user_id": "user_123",
"email": "user@example.com",
"role": "user",
"channel_id": "channel_abc",
"subscription_tier": "pro"
},
"billing_context": {
"provider": "newapi",
"newapi_user_ref": "newapi_user_123",
"newapi_group": "development",
"quota_ref": "newapi_token_or_group_quota_ref"
},
"agent_runtime": {
"platform": "agent",
"agents": [
{
"role": "builder",
"model_ref": "agent_model_profile_builder",
"instance_count": 1
}
]
},
"constraints": {
"allowed_model_ids": ["gpt-5.4-mini", "gpt-5.4"]
},
"metadata": {
"tenant_id": "legacy-user-scope",
"project_id": "legacy-resource-scope",
"correlation_id": "corr_20260502_001"
},
"agents": [
{
"role_template": "builder",
"goal": "按 Manager 下发的任务在允许资源内完成实现、验证并回传状态",
"default_model_id": "gpt-5.4-mini",
"sk_sources": [
{
"type": "git",
"mime": "text/markdown",
"repo_ref": {
"connection_id": "conn_sk_repo_001",
"repo_url": "https://example.com/org/sk-repo.git",
"ref": "main",
"paths": ["skills/heicode/**", "AGENTS.md"]
}
}
],
"runtime_execution": {
"profile_id": "aks-codex-standard",
"cloud_principal_refs": ["principal://users/user_123/agent-runtime"],
"network_policy_ref": "netpol://bindings/repo_default/restricted-egress"
},
"sk_access_policy": {
"policy_ref": "sk-policy://bindings/repo_default/default-readonly",
"deny_skill_ids": ["dangerous-shell"],
"inherit_deployment_defaults": true
},
"resource_grants": [
{
"grant_id": "grant_git_repo_001",
"resource_id": "res_git_repo_001",
"resource_type": "git",
"user_id": "user_123",
"binding_scope": "repo_default",
"tenant_id": "legacy-user-scope",
"project_id": "legacy-resource-scope",
"target_role": "builder",
"target_agent_ref": "agent-builder-1",
"permission_scope": ["repo:read", "repo:write:current-branch"],
"constraints": {
"ref": "main",
"allowed_paths": "heicode/**,docs/**",
"forbid_branch_create": "true"
},
"metadata": {
"provider": "gitee",
"repo_url": "https://example.com/org/repo.git"
},
"status": "active",
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/user-123-repo-default-res-git-repo-001",
"audit": {
"created_by": "manager",
"approval_id": "approval_001"
}
},
{
"grant_id": "grant_doc_001",
"resource_id": "res_project_doc_001",
"resource_type": "project_doc",
"user_id": "user_123",
"binding_scope": "repo_default",
"tenant_id": "legacy-user-scope",
"project_id": "legacy-resource-scope",
"target_role": "builder",
"target_agent_ref": "agent-builder-1",
"permission_scope": ["doc:read"],
"constraints": {
"doc_paths": "docs/heicode.md,docs/plan.md"
},
"metadata": {
"doc_ref": "project-doc://project-a/docs-mainline"
},
"status": "active",
"audit": {
"created_by": "manager"
}
}
]
}
]
}
}
```
### 2.3 字段说明
#### orchestration_plan
| 字段 | 类型 | 必填 | 约束/说明 |
|---|---|---:|---|
| `intent_id` | string | 是 | Manager 侧意图 ID，用于幂等、审计和追踪。 |
| `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/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 | 否 | 旧兼容字段；新实现不得作为项目账本边界。 |
| `metadata.correlation_id` | string | 是 | 全链路追踪 ID。 |
| `agents` | array | 是 | 至少 1 个子 Agent。 |
#### user_context / billing_context / agent_runtime
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `user_context.user_id` | string | 建议 | Manager 业务用户 ID，来自登录接口 `id` 或 JWT `sub`。 |
| `user_context.channel_id` | string | 建议 | 用于关联 NewAPI 用户、Token、Group、余额或额度策略。 |
| `billing_context.provider` | enum | 条件 | 当前只允许 `newapi`。设置后必须提供 `channel_id`、`newapi_user_ref`、`newapi_group` 或 `quota_ref` 之一。 |
| `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 | 条件 | 当前只允许 `agent`。 |
| `agent_runtime.agents[].role` | string | 条件 | 必须匹配 `agents[].role_template`。 |
| `agent_runtime.agents[].model_ref` | string | 条件 | Agent 平台模型 profile 引用；不是 NewAPI 扣费字段。 |
| `agent_runtime.agents[].instance_count` | int | 条件 | 子 Agent 实例数量，必须大于 0。 |
#### agents[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `role_template` | string | 是 | 平台角色模板，如 `builder`/`reviewer`/`operator`。 |
| `goal` | string | 是 | 此 agent 的任务目标。 |
| `default_model_id` | string | 否 | 默认模型；若设置需满足 allowed_model_ids。 |
| `sk_sources` | array | 否 | SK 来源，平台应解析为只读快照。 |
| `runtime_execution` | object | 否 | 运行环境绑定；任一字段存在时 `profile_id` 必填。 |
| `sk_access_policy` | object | 否 | SK 权限策略。若 `deny_skill_ids` 非空，需 `policy_ref` 或继承默认策略。 |
| `resource_grants` | array | 否 | Manager 下发给子 Agent 的最小权限资源授权。 |
#### sk_sources[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `type` | enum | 否 | 空值表示不启用；支持 `git`、`upload`。 |
| `artifact_id` | string | upload 必填 | 上传型 SK 包 ID。 |
| `mime` | string | 否 | 内容类型，如 `text/markdown`。 |
| `repo_ref.connection_id` | string | git 建议 | Git 连接资源 ID。 |
| `repo_ref.repo_url` | string | git 建议 | 仓库 URL；不得带用户名密码。 |
| `repo_ref.ref` | string | git 必填 | 分支/标签/commit。 |
| `repo_ref.paths` | string[] | git 必填 | 允许读取的路径。 |
#### runtime_execution
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `profile_id` | string | 条件必填 | Agent 平台运行规格，如 AKS profile。 |
| `cloud_principal_refs` | string[] | 否 | 运行身份引用，不是明文凭据。 |
| `network_policy_ref` | string | 否 | 网络策略引用，用于限制出站/入站。 |
#### resource_grants[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `grant_id` | string | 是 | 授权记录 ID。 |
| `resource_id` | string | 是 | Manager 资源 ID。 |
| `resource_type` | enum | 是 | `git` / `sk` / `project_doc` / `cloud_account` / `cloud_resource`。 |
| `user_id` | string | 建议 | 与 `user_context.user_id` 一致；为空时平台可从部署上下文推导。 |
| `binding_scope` | string | 是 | Git/SK/云资源作用域，例如 repo/ref/path 或云资源引用。 |
| `tenant_id` | string | 否 | 旧兼容字段；新实现不应依赖。 |
| `project_id` | string | 否 | 旧兼容字段；新实现不应依赖。 |
| `target_role` | string | 是 | 必须等于当前 agent 的 `role_template`。 |
| `target_agent_ref` | string | 是 | Manager 侧对子 Agent 的逻辑引用。 |
| `permission_scope` | string[] | 是 | 最小权限列表，如 `repo:read`、`doc:read`。 |
| `constraints` | object<string,string> | 否 | 路径、分支、区域、超时等限制；不得含密钥字段。 |
| `metadata` | object<string,string> | 否 | 资源展示/审计元数据；不得含密钥字段。 |
| `status` | enum | 是 | `pending` / `active` / `disabled` / `revoked`。 |
| `secret_ref` | string | 条件必填 | `git`、`sk`、`cloud_account`、`cloud_resource` 必填；`project_doc` 可为空。 |
| `audit` | object<string,string> | 否 | 审计上下文；不得含密钥字段。 |
### 2.4 典型场景：Agent 辅助 NewAPI 重建/部署
当 Manager 需要让 Agent 平台协助重建或部署 NewAPI 时，仍使用 `POST /api/agent/deployments`，但必须把任务表达为受控运维部署，不得把 VM、PostgreSQL、Redis、NewAPI key 等真实凭据写入请求体。
请求体示例：
```json
{
"orchestration_plan": {
"intent_id": "intent_newapi_rebuild_20260503_001",
"template_hint": "newapi-rebuild-deploy",
"objective": "在批准窗口内重建 NewAPI 服务并回传健康检查、日志与资源使用摘要",
"risk_level": "high",
"budget": {
"max_tokens": 80000,
"max_cost_usd": 20,
"max_duration_sec": 3600
},
"constraints": {
"allowed_model_ids": ["gpt-5.4", "gpt-5.4-mini"],
"requires_approval": "true",
"rollback_required": "true",
"healthcheck_url_ref": "env://NEWAPI_HEALTHCHECK_URL"
},
"metadata": {
"tenant_id": "legacy-user-scope",
"project_id": "legacy-newapi-scope",
"correlation_id": "corr_newapi_20260503_001",
"service": "new-api",
"environment": "production",
"commit": "origin/main",
"runbook_ref": "heicode/docs/deploy/new-api-rebuild-deploy-runbook.md"
},
"agents": [
{
"role_template": "operator",
"goal": "按 runbook 执行构建、服务重启、健康检查和失败回滚；只通过 secret_ref/env 获取凭据",
"default_model_id": "gpt-5.4",
"runtime_execution": {
"profile_id": "aks-codex-ops",
"cloud_principal_refs": ["principal://users/user_123/agent-ops"],
"network_policy_ref": "netpol://bindings/newapi-prod/ops-egress"
},
"resource_grants": [
{
"grant_id": "grant_newapi_vm_ops",
"resource_id": "res_newapi_vm",
"resource_type": "cloud_resource",
"user_id": "user_123",
"binding_scope": "newapi-prod",
"tenant_id": "legacy-user-scope",
"project_id": "legacy-newapi-scope",
"target_role": "operator",
"target_agent_ref": "agent-operator-1",
"permission_scope": ["vm:ssh:approved-window", "service:restart", "log:read", "healthcheck:read"],
"constraints": {
"approval_id": "approval_newapi_001",
"window": "2026-05-03T10:00:00Z/2026-05-03T11:00:00Z",
"rollback_command_ref": "runbook://newapi/rollback"
},
"metadata": {
"host_ref": "env://NEWAPI_VM_HOST",
"service_name": "new-api"
},
"status": "active",
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/user-123-newapi-prod-res-newapi-vm",
"audit": {
"created_by": "manager",
"approval_id": "approval_newapi_001"
}
},
{
"grant_id": "grant_newapi_runtime_env",
"resource_id": "res_newapi_runtime_env",
"resource_type": "cloud_resource",
"user_id": "user_123",
"binding_scope": "newapi-prod",
"tenant_id": "legacy-user-scope",
"project_id": "legacy-newapi-scope",
"target_role": "operator",
"target_agent_ref": "agent-operator-1",
"permission_scope": ["env:read:runtime", "secret:read:scoped"],
"constraints": {
"allowed_env_refs": "DATABASE_DSN,REDIS_URL,NEWAPI_SERVICE_TOKEN",
"plaintext_export_forbidden": "true"
},
"metadata": {
"secret_provider": "azure_key_vault",
"scope": "newapi-runtime"
},
"status": "active",
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/user-123-newapi-prod-res-newapi-runtime-env",
"audit": {
"created_by": "manager",
"approval_id": "approval_newapi_001"
}
}
]
}
]
}
}
```
Agent 平台返回的部署详情、日志、监控和审计中应至少能证明：构建版本/commit、服务重启结果、健康检查结果、资源使用情况、失败回滚状态。未执行真实 SSH/生产动作时，只能返回 `phase=planned` 或 `phase=pending_approval`。
NewAPI 重建/部署的完成判定必须同时满足：
1. `metadata.commit` 或部署详情中的 resolved commit 已在 VM 仓库中生效。
2. 部署日志包含构建/compose/restart 的脱敏摘要。
3. 健康检查返回成功，且监控接口能返回本次 deployment 的状态或资源摘要。
4. 审计日志包含高风险审批 ID、执行者、目标环境和结果。
5. 回滚指针或回滚命令引用已记录。
### 2.5 成功响应
```json
{
"success": true,
"data": {
"deployment_id": "dep_abc123",
"status": "accepted",
"agent_instances": [
{
"instance_id": "agi_abc123",
"role": "builder",
"phase": "pending"
}
]
}
}
```
---
## 3. 部署状态与控制接口
### 3.1 查询部署列表
```http
GET /api/agent/deployments?user_id=user_123&binding_scope=repo_default
```
返回：
```json
{
"success": true,
"data": {
"items": [
{
"deployment_id": "dep_abc123",
"status": "accepted",
"phase": "pending",
"created_at": "2026-05-02T00:00:00Z",
"updated_at": "2026-05-02T00:00:00Z"
}
],
"total": 1
}
}
```
### 3.2 查询单个部署
```http
GET /api/agent/deployments/{deployment_id}
```
返回应包含部署状态、phase、agent_instances、最近错误、资源授权摘要和预算消耗摘要。Agent 平台返回时必须对 `secret_ref` 以外的凭据信息做脱敏；原则上不返回任何明文凭据。
### 3.3 停止部署
```http
POST /api/agent/deployments/{deployment_id}/stop
```
请求体可为空；如需原因可扩展：
```json
{
"reason": "user_requested",
"requested_by": "manager"
}
```
成功：
```json
{
"success": true,
"data": {
"deployment_id": "dep_abc123",
"status": "stopped"
}
}
```
错误与幂等：
| HTTP | business code | 说明 |
|---:|---|---|
| 200 | - | 已停止的部署重复停止也可返回 200，并保持 `status=stopped`。 |
| 404 | `NOT_FOUND` | 部署不存在或不属于当前租户/项目。 |
| 409 | `DEPLOYMENT_CONFLICT` | 部署已进入不可停止的终态，如 `completed` 且无运行实例。 |
| 422 | `POLICY_REJECTED` | 高风险停止缺少审批记录或 reason 不合法。 |
若停止请求触发异步回收，平台可返回 `status=stopping`；Manager 应继续通过事件、日志和监控接口确认最终状态。
---
## 4. 日志接口（Manager 拉取 Agent 平台）
### 4.1 获取部署日志
```http
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：
| 参数 | 必填 | 说明 |
|---|---:|---|
| `agent_instance_id` | 否 | 不传则返回该 deployment 下全部实例日志。 |
| `stream` | 否 | `stdout` / `stderr` / `system` / `audit`，默认全部。 |
| `since` | 否 | RFC3339 时间，增量拉取起点。 |
| `limit` | 否 | 默认 200，建议最大 1000。 |
| `cursor` | 否 | 分页游标。 |
响应：
```json
{
"success": true,
"data": {
"items": [
{
"log_id": "log_001",
"deployment_id": "dep_abc123",
"agent_instance_id": "agi_abc123",
"stream": "stdout",
"level": "info",
"message": "task started",
"redacted": true,
"occurred_at": "2026-05-02T00:00:01Z"
}
],
"next_cursor": "cur_002",
"total": 1
}
}
```
日志要求：
- Agent 平台必须在返回前完成密钥脱敏。
- `message` 不得包含密码、Token、私钥、连接串、云访问密钥。
- Manager 只保存必要摘要和审计索引；长日志建议落对象存储并设置保留期。
### 4.2 实时日志流（可选）
```http
GET /api/agent/deployments/{deployment_id}/logs/stream?agent_instance_id=agi_abc123
Accept: text/event-stream
```
SSE event 示例：
```text
event: log
data: {"log_id":"log_002","level":"info","message":"step completed","occurred_at":"2026-05-02T00:00:02Z"}
```
SSE 事件类型：
| event | 说明 |
|---|---|
| `log` | 普通日志行，必须已脱敏。 |
| `heartbeat` | 保活事件，建议 15-30 秒一次。 |
| `error` | 流式读取错误；不包含敏感上下文。 |
| `done` | 部署进入终态或服务端主动结束流。 |
错误处理：
| HTTP | business code | Manager 处理建议 |
|---:|---|---|
| 401/403 | `UNAUTHORIZED` / `FORBIDDEN_SCOPE` | 立即断开流并记录审计。 |
| 404 | `NOT_FOUND` | 停止订阅并刷新部署详情。 |
| 429 | `RATE_LIMITED` | 退避后重连，保留 `Last-Event-Id`。 |
---
## 5. 监控接口（Manager 拉取 Agent 平台）
### 5.1 项目监控快照
```http
GET /api/agent/projects/{binding_scope}/dashboard-snapshot?window=1h
```
响应：
```json
{
"success": true,
"data": {
"project_id": "project-a",
"active_instances": 3,
"phase_distribution": {
"pending": 1,
"running": 2,
"stopped": 0,
"failed": 0
},
"failure_rate_1h": 0.02,
"avg_task_duration": 185.3,
"budget": {
"tokens_used": 32000,
"cost_usd": 4.21,
"duration_sec": 930
},
"resource_usage": {
"cpu_millicores": 1200,
"memory_mb": 2048,
"network_rx_bytes": 102400,
"network_tx_bytes": 204800
},
"updated_at": "2026-05-02T00:05:00Z"
}
}
```
### 5.2 单部署监控快照（建议平台实现）
```http
GET /api/agent/deployments/{deployment_id}/metrics?window=15m&step=60s
```
响应：
```json
{
"success": true,
"data": {
"deployment_id": "dep_abc123",
"window": "15m",
"series": [
{
"metric": "tokens_used",
"unit": "count",
"points": [["2026-05-02T00:00:00Z", 1200]]
},
{
"metric": "cpu_millicores",
"unit": "millicore",
"points": [["2026-05-02T00:00:00Z", 500]]
}
]
}
}
```
建议指标：`tokens_used`、`cost_usd`、`duration_sec`、`cpu_millicores`、`memory_mb`、`restart_count`、`tool_call_count`、`error_count`、`queue_latency_ms`。
---
## 6. 事件与审计接口
### 6.1 部署事件
```http
GET /api/agent/deployments/{deployment_id}/events?since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
```
响应：
```json
{
"success": true,
"data": {
"items": [
{
"event_id": "evt_001",
"event": "deployment.accepted",
"schema_version": 1,
"user_id": "user_123",
"channel_id": "channel_abc",
"binding_scope": "repo_default",
"deployment_id": "dep_abc123",
"correlation_id": "corr_20260502_001",
"occurred_at": "2026-05-02T00:00:00Z"
}
],
"next_cursor": "cur_002",
"total": 1
}
}
```
常用事件名：
| event | 说明 |
|---|---|
| `deployment.accepted` | 平台接受部署请求。 |
| `instance.phase_changed` | 子 Agent phase 变化。 |
| `sk_snapshot_refreshed` | SK 快照解析/刷新完成。 |
| `resource_grant.attached` | 资源授权已绑定到实例。 |
| `resource_grant.revoked` | 授权被撤销或禁用。 |
| `budget.threshold_reached` | 预算阈值触发。 |
| `deployment.failed` | 部署失败。 |
### 6.2 审计日志
```http
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
```
响应：
```json
{
"success": true,
"data": {
"items": [
{
"audit_id": "aud_001",
"actor": "agent_control_plane",
"action": "deployment.accepted",
"resource": "dep_abc123",
"user_id": "user_123",
"channel_id": "channel_abc",
"binding_scope": "repo_default",
"request_id": "req_001",
"correlation_id": "corr_20260502_001",
"result": "ok",
"occurred_at": "2026-05-02T00:00:00Z"
}
],
"next_cursor": "cur_002",
"total": 1
}
}
```
---
## 7. SK 快照接口
### 7.1 触发解析/刷新
```http
POST /api/agent/sk-snapshots/resolve
```
请求：
```json
{
"deployment_id": "dep_abc123"
}
```
响应：
```json
{
"success": true,
"data": {
"deployment_id": "dep_abc123",
"items": [
{
"snapshot_id": "sks_001",
"deployment_id": "dep_abc123",
"user_id": "user_123",
"binding_scope": "repo_default",
"source_type": "git",
"source_ref": "main:skills/heicode/**@sha_xxx",
"resolved_at": "2026-05-02T00:00:00Z"
}
],
"total": 1
}
}
```
### 7.2 查询部署 SK 快照
```http
GET /api/agent/deployments/{deployment_id}/sk-snapshots
```
Query：
| 参数 | 必填 | 说明 |
|---|---:|---|
| `user_id` | 建议 | 与 `X-User-Id` 或 deployment 的 `user_context.user_id` 一致。 |
| `binding_scope` | 建议 | 与 `X-Binding-Scope` 或 deployment 的资源授权作用域一致。 |
| `source_type` | 否 | `git` / `upload`，用于筛选。 |
| `limit` | 否 | 默认 100，最大 500。 |
| `cursor` | 否 | 分页游标。 |
成功响应：
```json
{
"success": true,
"data": {
"items": [
{
"snapshot_id": "sks_001",
"deployment_id": "dep_abc123",
"user_id": "user_123",
"binding_scope": "repo_default",
"source_type": "git",
"source_ref": "main:skills/heicode/**@sha_xxx",
"artifact_ref": "artifact://bindings/repo_default/sk/sks_001",
"checksum": "sha256:example-redacted",
"status": "ready",
"resolved_at": "2026-05-02T00:00:00Z"
}
],
"next_cursor": "cur_002",
"total": 1
}
}
```
错误处理：
| HTTP | business code | 说明 |
|---:|---|---|
| 404 | `NOT_FOUND` | deployment 不存在或不属于当前租户/项目。 |
| 410 | `CURSOR_EXPIRED` | cursor 过期，使用不带 cursor 的查询重拉。 |
| 422 | `SK_SOURCE_UNRESOLVABLE` | 快照来源不可解析，详情在事件/日志中查看。 |
---
## 8. 安全校验清单
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` 使用最小权限；生产写操作必须携带客户端审批记录，Agent 平台不得自行补批。
6. 高风险操作（生产部署、云资源修改、删除、扩容）必须设置 `risk_level=high`，Agent 平台执行前只校验客户端审批证据。
7. 所有日志/事件/审计返回给 Manager 前必须脱敏。
Agent 平台不承担高危操作审批主体。审批只发生在客户端；Agent 平台只能在执行前校验以下字段和策略是否一致：
| 校验项 | 要求 |
|---|---|
| `approval_id` | 必须存在于高危任务的 `constraints` 或 `audit`，并可追溯到客户端审批记录。 |
| 审批主体 | 审批用户必须与 `user_context.user_id`、`resource_grants[].user_id` 或授权代理主体一致。 |
| 审批范围 | 审批范围必须覆盖 `binding_scope`、`permission_scope`、目标环境、资源 ID 和操作类型。 |
| TTL / 时间窗口 | 审批记录必须未过期；若使用 `window` 或 TTL，当前执行时间必须落在允许范围内。 |
| `risk_level` | 高危资源写入、生产部署、云资源修改、删除和扩容必须为 `high`。 |
| 策略 | 平台 policy、Key Vault 访问策略、Kubernetes/Workload Identity、网络策略和最小权限约束均必须允许本次动作。 |
任一校验不通过时，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/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、密钥片段。 |
| NewAPI 重建/部署场景 | `approval_id`、`rollback_command_ref`、健康检查引用、运行环境 `secret_ref` | 真实 VM 密码、PostgreSQL/Redis 连接串、NewAPI 服务令牌。 |
### 8.2 联调验收清单
- 创建部署请求只包含 `secret_ref`/`env://`/`runbook://` 引用，不包含真实凭据。
- `user_id` 与 `binding_scope` 在 user context、resource grant、事件和审计中一致。
- `risk_level=high` 的生产运维任务包含 `approval_id` 和回滚引用。
- 日志、事件、监控、审计接口都能通过 `correlation_id` 串联。
- NewAPI 重建/部署只在实际执行并通过健康检查后标记为已部署；未执行时状态只能是 `planned`、`pending_approval`、`accepted` 或 `running`。
- Manager 本地 `/api/agent/*` 占位端点通过 payload 校验不等于生产 Agent 平台已上线。
---
## 9. Manager 侧当前实现映射
当前代码中可用于对齐/验证 payload 的 Manager 侧端点：
| Manager 路由 | 用途 |
|---|---|
| `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 应把相同契约的请求发送给 Agent 平台；本地 Manager 端点仅作为最小验证与控制面占位，不代表所有日志/监控平台能力已完整实现。
当前本地 `logs` 与 `metrics` 端点只返回脱敏占位/联调数据，用于验证 Manager ↔ Agent payload、路由和验收流程。生产级实时日志流 `GET /api/agent/deployments/{deployment_id}/logs/stream` 仍属于 Agent 平台能力；Manager 不得把“本地占位通过”误报为“生产日志/监控已上线”。
docs/integration/heicode-manager-swarm-runtime-env-template.md
-151
View File
@@ -1,151 +0,0 @@
# Heicode Manager 蜂群 Runtime 联调配置模板
更新时间：2026-05-27
适用范围：Heicode Manager 调用 Agent Manager / HeiCode-Swarm Runtime。
## 一、标准 Agent Manager Runtime 配置
当 Runtime 提供正式 `POST /api/swarms` 时，Manager 建议配置：
```bash
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
AGENT_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agent/callbacks/swarm-events
AGENT_CALLBACK_TOKEN=<callback-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`。
## 二、当前 HeiCode-Swarm Orchestrator 兼容配置
如果短期只用现有 Orchestrator 的 `/health` 和 `/tasks` 先做连通性测试，可以临时配置：
```bash
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
AGENT_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agent/callbacks/swarm-events
AGENT_CALLBACK_TOKEN=<callback-token>
```
注意：
1. `/tasks` 不是最终生产契约，只能做临时兼容测试。
2. 当前 `/tasks` 字段不足以完整表达 `resource_grants`、`secret_ref`、`approval_policy`、`budget`。
3. 若 Orchestrator 不支持 stop 和 approval decision，Manager 会记录回传失败审计，但用户审批记录仍会保存。
## 三、Runtime 回调 Manager 的请求头
推荐使用 service token：
```http
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
```
也支持 HMAC：
```http
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
```
签名内容：
```text
timestamp + "." + event_id + "." + raw_body
```
## 四、最小联调命令
健康检查：
```bash
curl -sS "$AGENT_RUNTIME_BASE_URL$AGENT_RUNTIME_HEALTH_PATH"
```
Manager 本地默认模拟链路：
```bash
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 '{}'
```
该命令用于 Manager 自测，不代表真实 Runtime 已执行。默认模拟会落 callback、artifact、approval、timeline 记录，并用于检查页面展示和 `secret_ref` 脱敏。
模拟 Runtime 回调 Manager：
```bash
curl -sS -X POST "https://code.xinghanlab.com/api/agent/callbacks/swarm-events" \
-H "Content-Type: application/json" \
-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",
"event_type": "timeline.updated",
"deployment_id": "<manager-deployment-id>",
"swarm_id": "<runtime-swarm-id>",
"occurred_at": "2026-05-27T10:00:00Z",
"source": "heicode-swarm-runtime",
"payload": {
"title": "Runtime callback received",
"summary": "Manager callback pipeline is reachable",
"severity": "info"
}
}'
```
成功响应：
```json
{
"success": true,
"data": {
"event_id": "evt-smoke-001",
"inserted": true,
"deduplicated": false,
"deployment_id": "<manager-deployment-id>"
}
}
```
## 五、上线前必须确认
| 项 | 标准 |
|---|---|
| create | Manager 能拿到 `runtime_deployment_id` 和 `runtime_swarm_id` |
| callback | Runtime 至少回调 `deployment.status_changed`、`task.completed`、`artifact.created` |
| approval | Runtime 发 `approval.requested`，Manager 用户审批后 Runtime 收到 decision |
| artifact | Manager artifacts 页面能看到 artifact 类型、标题、摘要和 URI |
| timeline | Manager timeline 能区分 `manager`、`runtime`、`simulated` 来源 |
| secret | 请求、响应、日志、artifact metadata 中无长期明文密钥 |
docs/integration/heicode-swarm-deferred.md
+56
View File
@@ -0,0 +1,56 @@
# Heicode 蜂群（Swarm）—— 现状裁定与后续跟踪入口（HM 侧）
> 起草：2026-06-05 · 状态：跟踪占位（HM 侧不实现，归口 AM / Swarm）
>
> 本文是 PR #15「文档大同步」删除全部旧 sub/蜂群文档后留下的**追踪入口**，回答三件事：① 旧文档为什么作废、② 蜂群能力现在归谁、③ 未来对接/待定项在哪里跟踪。删除旧文档≠放弃蜂群能力，**上下文迁移到本文**。
---
## 1. 裁定（当前结论）
- **HM（Heicode Manager）当前不实现 swarm runtime。** HM 的职责边界是：模型网关（`/v1/*`）+ 资源/权限/计费/审计 + **模板 Agent 部署编排**（经 AM 启动常驻 agent、客户端直连）。多 agent 蜂群编排**不在 HM 端**。
- **旧的「HM 内部 sub/蜂群任务编排」模型已作废。** 那套（sub 任务、display_status、HM 侧蜂群 runtime 对接草案）随产品转向「模板 Agent + 客户端直连」一并下线，相关代码删除清单见 [`heicode-hm-legacy-teardown.md`](./heicode-hm-legacy-teardown.md)，当前模型见 [`heicode-hm-template-agent-model.md`](./heicode-hm-template-agent-model.md)。
- **新版蜂群能力仍在开发中，但在 AM / Swarm 侧，不在本仓。** 旧文档描述的是「HM 主导编排蜂群」的废弃设计；新蜂群若落地，HM 侧最多提供资源/计费/鉴权支撑面，runtime 与编排由 Swarm 承载。
---
## 2. 能力归属与后续跟踪入口
| 项 | 归属仓 / 负责人 | 说明 |
|---|---|---|
| Swarm runtime / 多 agent 编排 | **`agent_swarm` / `HeiCode-Swarm`**（@Songhaoz666） | 执行面、回调、Swarm Runtime |
| Manager ↔ Swarm 契约（若未来需要） | 待 Swarm 侧给出正式 `/api/agent/swarm/*` 接口后，在本目录 `docs/integration/` 另立契约文档跟踪 | 当前 Swarm 仅暴露 `/tasks`、缺 `deployment_id ↔ swarm_id` 映射（见 `agent_swarm#1`） |
| Agent 运行时（单 agent，已落地） | **`agent_management`（AM）**（@azgy） | 模板 Agent 启动/状态/停止/删除，契约见 [`heicode-am-contract.md`](./heicode-am-contract.md) |
> **HM 侧后续若要支撑蜂群**：不恢复旧文档，按当时 Swarm 的正式契约在 `docs/integration/` 新立文档；本文作为「蜂群在 HM 侧当前为 deferred」的唯一锚点。
---
## 3. 已删除文档的迁移映射（PR #15）
> 对照 Fasthei 复审要求：每份删除文档标明是「作废 / 迁移 / deferred」，以及上下文去向。
### 蜂群 / swarm 相关（7 份，上下文迁移至本文 + Swarm 仓）
| 删除的文档 | 处置 | 去向 |
|---|---|---|
| `docs/heicode-manager-sub-swarm-progress-checklist.md` | **deferred** | 旧 HM 内部 sub/蜂群编排进度；未完成事项随模型作废，新蜂群进度归 Swarm 仓跟踪 |
| `docs/heicode-manager-swarm-gap-analysis.md` | **作废** | 针对废弃的「HM 主导蜂群」模型的 gap 分析，前提不再成立 |
| `docs/integration/agent-manager-swarm-runtime-change-request.md` | **deferred → AM/Swarm** | 旧 HM→AM 蜂群 runtime 变更请求；如需重提，由 Swarm 侧按新契约发起 |
| `docs/integration/AgentManager蜂群Runtime接口实现要求.md` | **deferred → AM/Swarm** | 蜂群 runtime 接口要求归 Swarm 侧实现与跟踪 |
| `docs/integration/AgentManager蜂群Runtime联调待确认与补充要求.md` | **deferred → AM/Swarm** | 联调待确认项随新契约在 Swarm 侧重列 |
| `docs/integration/heicode-manager-swarm-runtime-env-template.md` | **作废** | 旧蜂群 runtime env 模板，对应废弃的 HM 编排路径 |
| `docs/integration/蜂群模式-AgentManager对接任务清单.md` | **deferred → AM/Swarm** | 对接任务清单随新契约在 Swarm 侧重建 |
### 其它旧文档（4 份，被新主线文档取代）
| 删除的文档 | 处置 | 取代者 |
|---|---|---|
| `Heicode-Manager-项目说明与踩坑交接.md` | **作废** | 被 HM-only 化的 `README.md` / `CLAUDE.md` / `AGENTS.md` 取代 |
| `docs/Heicode-Manager-agent统一改造落地计划.md` | **作废** | 被 `integration/heicode-hm-template-agent-model.md` 取代 |
| `docs/heicode-manager-standalone-execution-plan.md` | **作废** | 被 `plan.md` 取代 |
| `docs/integration/agent-platform-request-contract.md` | **作废** | 旧出站契约，被 `integration/heicode-am-contract.md` 取代 |
---
## 4. 给后续开发者的一句话
要找「蜂群在 HM 侧怎么对接」——**当前答案是「HM 不实现，等 Swarm 侧正式契约」**；旧设计已废，别从 git 历史里捞旧文档当依据，按本文与 Swarm 仓的最新结论走。
docs/integration/蜂群模式-AgentManager对接任务清单.md
-441
View File
@@ -1,441 +0,0 @@
# Agent Manager 蜂群模式对接任务清单
更新时间：2026-05-28
发给：Agent Manager / HeiCode-Swarm 负责人
来源：Heicode Manager 当前代码、生产 1.4.9 验证结果、蜂群资料包和 Heicode 产品资料包。
## 1. 结论
Heicode Manager 端已经具备蜂群模式所需的控制面能力：创建 deployment、桥接 Runtime、保存 `runtime_deployment_id` / `swarm_id`、接收 callback、落 artifact、落 approval、聚合 timeline、审批结果回传 Runtime、页面展示 task flow。
Agent Manager / Swarm Runtime 当前还需要补齐或确认的是：真实创建 Swarm Run、生成任务图、Agent claim/heartbeat/handoff/retry/blocked 状态机、artifact 真实产出、审批暂停和恢复、日志指标、用量回传。
## 2. 当前 Manager 已完成
| 能力 | 状态 | 说明 |
|---|---|---|
| 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/agent/callbacks/swarm-events` |
| callback 鉴权 | 已完成 | 支持 service token 或 HMAC |
| callback 幂等 | 已完成 | 按 `event_id` / `idempotency_key` 去重 |
| task flow 校验 | 已完成 | `task.*` / `handoff.*` 缺关键字段会返回 `CALLBACK_SCHEMA_INVALID` |
| artifact 落库 | 已完成 | `artifact.created` 可落库并在 deployment 详情展示 |
| approval 落库 | 已完成 | `approval.requested` 可转 Manager 审批记录 |
| approval decision 回传 | 已完成 | 用户 approve/reject 后 Manager 可回传 Runtime |
| 页面验证 | 已完成 | 生产 1.4.9 已验证 `Sub task flow` 展示 task/blocked/retry/handoff |
## 3. Agent Manager 需要实现或确认的 P0
| 任务 | 必需 | 原因 | 验收 |
|---|---:|---|---|
| 提供真实创建 Swarm Run 接口 | 是 | Manager 只能发起，不能替 Runtime 生成真实任务图 | `POST /api/swarms` 或配置等价接口返回真实 `deployment_id` / `swarm_id` |
| 返回稳定 Runtime 标识 | 是 | Manager 要保存 `deployment_id <-> runtime_deployment_id/swarm_id` 映射 | 创建响应包含 `deployment_id` 或 `id`，建议同时包含 `swarm_id` |
| 生成任务图 | 是 | 蜂群模式核心是 task graph，不是单个占位 deployment | Runtime 内部能创建任务节点，并回调 `task.created` |
| Agent claim / heartbeat | 是 | Manager 页面和客户端需要知道哪个 Agent 在做哪个任务 | 回调 `task.claimed`、`task.heartbeat` |
| blocked / retry / failed 状态机 | 是 | 失败恢复和阻塞是蜂群运行核心 | 回调 `task.blocked`、`task.retried`、`task.failed`，字段符合 schema |
| handoff 状态机 | 是 | 蜂群 Agent 间交接需要可审计 | 回调 `handoff.requested`、`handoff.completed` |
| artifact 真实产出 | 是 | Manager 只保存摘要和引用，真实产物来自 Runtime | 回调 `artifact.created`，带 `uri`、`summary`、`artifact_type` |
| 高危审批暂停/恢复 | 是 | 高危操作需要客户端审批后 Runtime 才能继续 | Runtime 回调 `approval.requested`，并接收 Manager decision |
| 日志/指标 | 是 | 线上排障和验收需要真实运行数据 | 提供 logs/metrics 查询或通过 callback 摘要回传 |
| 不记录明文长期密钥 | 是 | 安全红线 | Runtime 只消费 `secret_ref` / `credential_ref`，日志和 artifact metadata 不出现明文密钥 |
## 4. Runtime 创建接口
生产目标：
```http
POST /api/swarms
Authorization: Bearer <service_token>
X-User-ID: <manager_user_id>
X-Binding-Scope: <binding_scope>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: manager-<manager_deployment_id>
Content-Type: application/json
```
Manager 当前可通过环境变量切换：
```text
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}
```
请求体核心形状：
```json
{
"orchestration_plan": {
"intent_id": "task_xxx",
"objective": "完成本轮用户目标",
"sub_mode": "agile",
"risk_level": "medium",
"budget": {
"max_tokens": 120000,
"max_cost_usd": 8,
"max_duration_sec": 3600
},
"user_context": {
"user_id": "22",
"channel_id": "heicode"
},
"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",
"next_action": "continue",
"requires_user_approval": false
},
"agents": []
},
"agents": [
{
"role": "backend",
"resource_grants": []
}
],
"resource_grants": [
{
"grant_id": "grant-task-backend",
"resource_id": "repo-main",
"resource_type": "git",
"permission_scope": ["repo:read", "repo:write:feature-branches"],
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
"ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
"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",
"task.created",
"task.claimed",
"task.heartbeat",
"task.blocked",
"task.retried",
"task.failed",
"task.completed",
"handoff.requested",
"handoff.completed",
"approval.requested",
"artifact.created",
"timeline.updated"
]
},
"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",
"swarm_id": "swarm-123",
"status": "running"
}
}
```
或：
```json
{
"deployment_id": "runtime-dep-123",
"swarm_id": "swarm-123",
"status": "running"
}
```
Manager 解析规则：
| Runtime 字段 | Manager 保存到 |
|---|---|
| `data.deployment_id` / `deployment_id` / `id` | `runtime_deployment_id` |
| `data.swarm_id` / `swarm_id` / `runtime_swarm_id` | `runtime_swarm_id` |
| `data.status` / `status` | `runtime_state` |
## 5. Runtime 回调 Manager
统一入口：
```http
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
```
也支持 HMAC：
```http
X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>
```
签名内容：
```text
timestamp + "." + event_id + "." + raw_body
```
Agent Manager / 蜂群侧可以先拉取 Manager 当前接受的事件 schema：
```http
GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
```
该接口不返回任何 token 或密钥，只返回事件类型、分类和必填字段，用于联调前核对 `task.*`、`handoff.*`、`artifact.created`、`approval.requested` 等 callback payload 是否符合 Manager 接收规则。
统一 envelope：
```json
{
"event_id": "evt_xxx",
"idempotency_key": "evt_xxx",
"event_type": "task.blocked",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"agent_instance_id": "agent-backend-1",
"task_id": "task-backend-1",
"occurred_at": "2026-05-28T10:00:00Z",
"correlation_id": "corr_xxx",
"source": "heicode-swarm-runtime",
"payload": {}
}
```
## 6. task / handoff 事件 schema
Manager 已上线校验。以下字段缺失会拒绝，返回 `CALLBACK_SCHEMA_INVALID`。
| event_type | 必填字段 |
|---|---|
| `task.created` | `task_id`, `payload.title` |
| `task.claimed` | `task_id`, `payload.agent_role` |
| `task.running` | `task_id`, `payload.agent_role` |
| `task.heartbeat` | `task_id`, `payload.agent_role` |
| `task.blocked` | `task_id`, `payload.reason` |
| `task.retried` | `task_id`, `payload.attempt` |
| `task.released` | `task_id`, `payload.agent_role` |
| `task.failed` | `task_id`, `payload.reason` |
| `task.completed` | `task_id` |
| `handoff.requested` | `task_id`, `payload.from_role`, `payload.to_role` |
| `handoff.completed` | `task_id`, `payload.from_role`, `payload.to_role` |
| `artifact.created` | `artifact.artifact_id` 或 `payload.artifact_id` |
示例：
```json
{
"event_id": "evt_task_blocked_1",
"event_type": "task.blocked",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"agent_instance_id": "agent-backend-1",
"task_id": "task-backend-1",
"source": "heicode-swarm-runtime",
"payload": {
"task_id": "task-backend-1",
"agent_role": "backend",
"reason": "等待前端接口字段确认",
"severity": "warning",
"next_action": "handoff_to_frontend"
}
}
```
```json
{
"event_id": "evt_handoff_1",
"event_type": "handoff.requested",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"task_id": "task-backend-1",
"source": "heicode-swarm-runtime",
"payload": {
"task_id": "task-backend-1",
"from_role": "backend",
"to_role": "frontend",
"summary": "后端接口已完成，交给前端接页面"
}
}
```
## 7. artifact 回调
Runtime 不要把大文件正文塞进 callback。只回写摘要和可访问引用。
```json
{
"event_id": "evt_artifact_1",
"event_type": "artifact.created",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"task_id": "task-backend-1",
"source": "heicode-swarm-runtime",
"artifact": {
"artifact_id": "art_backend_patch_1",
"artifact_type": "code_patch",
"title": "Backend patch",
"summary": "完成工单列表和状态流转接口",
"uri": "git://repo#feature/task-backend-1",
"checksum": "sha256:abc123",
"metadata": {
"redacted": true,
"agent_role": "backend"
}
}
}
```
## 8. approval 回调和 decision 接口
Runtime 在高危动作前必须暂停，并回调 Manager：
```json
{
"event_id": "evt_approval_1",
"event_type": "approval.requested",
"deployment_id": "dep_xxx",
"swarm_id": "swarm-123",
"agent_instance_id": "agent-backend-1",
"task_id": "task-backend-1",
"source": "heicode-swarm-runtime",
"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 用户同意或拒绝后会调用 Runtime：
```http
POST /api/swarms/{swarm_id}/approvals/{approval_id}
Authorization: Bearer <service_token>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: approval-decision-<approval_id>-<approved|rejected>
Content-Type: application/json
```
请求：
```json
{
"approval_id": "appr_runtime_1",
"decision": "approved",
"manager_deployment_id": "dep_xxx",
"runtime_deployment_id": "runtime-dep-123",
"swarm_id": "swarm-123",
"operation": "git.write",
"resource_id": "repo-main",
"resource_type": "git",
"resource_scope": "feature/*",
"target_role": "backend",
"risk_level": "high",
"requires_credential": true,
"user_id": "22",
"credential_ref": "lease://agent/lease_xxx",
"lease_id": "lease_xxx",
"lease_expires_at": 1779850900000
}
```
注意：Manager 不会把长期 `secret_ref` 发回 decision，只会在同意时发短期 `credential_ref`。
## 9. 停止接口
默认：
```http
POST /api/agent/deployments/{runtime_deployment_id}/stop
Authorization: Bearer <service_token>
Content-Type: application/json
```
请求：
```json
{
"reason": "Heicode Manager requested stop",
"manager_deployment_id": "dep_xxx"
}
```
响应：
```json
{
"success": true,
"data": {
"deployment_id": "runtime-dep-123",
"swarm_id": "swarm-123",
"status": "stopped"
}
}
```
## 10. 验收用例
| 用例 | 操作 | 期望 |
|---|---|---|
| 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 |
| schema 拒绝 | 发送缺 `to_role` 的 `handoff.requested` | Manager 返回 `CALLBACK_SCHEMA_INVALID` |
| artifact | Runtime 回调 `artifact.created` | Manager artifacts 列表出现产物 |
| approval | Runtime 回调 `approval.requested` | Manager pending approval 出现 |
| decision | 用户 approve/reject | Runtime decision 接口收到 `approved/rejected` |
| stop | Manager stop deployment | Runtime 状态变为 stopped |
| 安全 | 搜索日志和回调 payload | 不出现 password/token/private_key/access_key/connection_string 明文 |
## 11. Agent Manager 不需要做的事
| 不需要做 | 原因 |
|---|---|
| 实现桌面客户端 V2 body 加密 | 这是客户端到 Manager 的协议，Manager 已支持 |
| 直接让普通用户访问 Azure Key Vault | 密钥入口由 Manager 控制，Runtime 只消费 `secret_ref` 或短期 `credential_ref` |
| 在 callback 中发送明文模型 key / Git token / 云密钥 | 安全红线，Manager 会拒绝疑似明文敏感字段 |
| 替 Manager 保存用户、资源绑定、审批主记录 | Manager 是控制面和记录面 |
## 12. 联调顺序建议
1. Agent Manager 确认 health、create、stop、approval decision 路径。
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`。
6. 回调 `approval.requested`，客户端/Manager approve 后 Runtime 接收 decision 并继续。
7. Manager stop，Runtime 停止任务并回调最终状态。
docs/product-package/03-user-journey-and-core-flow.md
+8 -9
View File
@@ -129,19 +129,18 @@ Backend Agent
### 7. Agent 执行闭环 ### 7. Agent 执行闭环
Heicode 不是只把任务丢给 Agent 一次就结束，而是会在开发过程中持续调用 Agent 完成子环节。 部署后客户端拿到 agent 的公网地址，**直连 agent 持续对话推进开发**（HM 不在对话回路；agent 用模型时走 HM `/v1`）。
闭环应表达为： 闭环应表达为：
```text ```text
客户端输入目标或追加需求 客户端直连 agent，输入目标或追加需求
-> Heicode 生成下一步任务 -> agent 自行推进需求/设计/开发/测试/修复
-> Agent 执行需求/设计/开发/测试/修复中的当前子环节 -> agent 按需要调用已授权的 SK 工具
-> Agent 按需要调用已授权的 SK 工具 -> agent 用模型时走 HM /v1（计费到用户）
-> Heicode 回传中间结果给客户端 -> 中间结果与产物回到客户端
-> 用户继续追问、修正或审批 -> 用户继续追问、修正或审批高危动作
-> Agent 继续下一子环节 -> agent 继续推进，直至交付整理与部署
-> 最终由 Agent 完成交付整理与部署
``` ```
这意味着用户看到的不是一次性“已部署 Agent”，而是一个可连续推进的开发循环。 这意味着用户看到的不是一次性“已部署 Agent”，而是一个可连续推进的开发循环。
docs/product-package/12-narrated-user-operation-flow.md
+5 -5
View File
@@ -246,13 +246,13 @@ Ops Agent 请求部署到生产环境。
这里的真实闭环是： 这里的真实闭环是：
```text ```text
我在客户端补充要求 我在客户端直连 agent、补充要求
-> Heicode 判断下一步要推进哪个子环节 -> agent 自行推进需求、开发、测试、修复或部署中的当前任务
-> Agent 执行需求、开发、测试、修复或部署中的当前任务 -> agent 按权限调用已绑定的 SK 工具
-> Agent 按权限调用已绑定的 SK 工具 -> agent 用模型时走 HM /v1
-> 中间结果回到客户端 -> 中间结果回到客户端
-> 我继续修正方向或批准高危动作 -> 我继续修正方向或批准高危动作
-> Agent 继续推进直到交付和部署完成 -> agent 继续推进直到交付和部署完成
``` ```
### 18. 查看执行状态 ### 18. 查看执行状态