From c9767eb6bb12f2effb74ceb08516065a234f518a Mon Sep 17 00:00:00 2001 From: chenchen Date: Mon, 8 Jun 2026 13:03:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E5=88=B0=E5=BD=93=E5=89=8D=E5=AE=9E=E9=99=85=EF=BC=88HM-only?= =?UTF-8?q?=20=E4=BB=93=20+=20=E6=A8=A1=E6=9D=BF=20Agent=20=E6=A8=A1?= =?UTF-8?q?=E5=9E=8B=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 根 README/CLAUDE/AGENTS：本仓已从 monorepo 拆分，只剩 Heicode Manager（heicode/ Go 网关 + docs/）。重写仓库地图为 HM-only；客户端指向 heicode-{mac,win}os-release-dev 独立仓；移除指向已删文档的死链（vision/milestones/agent-platform-api-design/cc-haha-AGENTS）；开发闭环改为 heicode/。 - 删除 docs/integration/agent-platform-request-contract.md（已被 AM 契约取代）；docs/README 索引去掉该条。 - product-package 03/12：执行闭环去掉「Heicode 生成/判断子环节」旧编排说法，改为客户端直连 agent、agent 自驱、模型走 HM /v1。 影响面：仅文档。 Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 86 +- CLAUDE.md | 86 +- README.md | 64 +- docs/README.md | 10 +- .../agent-platform-request-contract.md | 961 ------------------ .../03-user-journey-and-core-flow.md | 17 +- .../12-narrated-user-operation-flow.md | 10 +- 7 files changed, 89 insertions(+), 1145 deletions(-) delete mode 100644 docs/integration/agent-platform-request-contract.md diff --git a/AGENTS.md b/AGENTS.md index 6f4eda33..4ac152e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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**：网关 + 管理控制台 | Go（Gin/GORM）+ `web/default` 前端（Bun/Rsbuild/React） | -| `website/` | 产品介绍站点 | Next.js；根 `docker-compose.yml` 提供 `heicode-www` :8888 | -| `docs/` | 愿景、**里程碑**（`docs/milestones/`）、**Agent 集成**（`docs/integration/`） | Markdown | - -根 `package.json` 仅少量 workspace 级依赖（如适配器用到的包）；**主要开发依赖在 `cc-haha/package.json`**。 +| `heicode/` | **Heicode Manager**：基于 new-api 的模型网关 + 管理控制台 | Go（Gin/GORM）后端 + `web/default` 前端（Bun/Rsbuild/React） | +| `docs/` | 产品共识 / 实施计划 / 集成契约 | Markdown，索引见 [`docs/README.md`](./docs/README.md) | ## 权威子文档（改代码前先打开对应一篇） -- **客户端（cc-haha）**：[`cc-haha/AGENTS.md`](./cc-haha/AGENTS.md) — 目录结构、运行命令、测试、提交约定。 -- **网关（heicode）**：[`heicode/AGENTS.md`](./heicode/AGENTS.md) — Go 分层、JSON/i18n/DB 规则等。 -- **产品愿景与交付节奏**：[`docs/vision-heicode-full-stack-agentic-dev.md`](./docs/vision-heicode-full-stack-agentic-dev.md)、[`docs/milestones/README.md`](./docs/milestones/README.md)。 +- **网关后端（`heicode/`，Go）**：[`heicode/AGENTS.md`](./heicode/AGENTS.md) — Go 分层、JSON / i18n / DB 规则、计费表达式等。 +- **产品共识与实施计划**：[`docs/heicode.md`](./docs/heicode.md)、[`docs/plan.md`](./docs/plan.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 -# 依赖（客户端主体） -cd cc-haha && bun install +Heicode Manager = `heicode/`（Go 后端 + `web/default` 前端）。构建 / 运行命令与分层规则以 [`heicode/AGENTS.md`](./heicode/AGENTS.md) 与 `heicode/README.md` 为准。 -# 终端 A：本地 API（桌面端依赖） -bun run src/server/index.ts +## 关键触摸点（代码索引） -# 终端 B：桌面 -cd desktop && bun run tauri dev -``` - -联调本机 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__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`）。 +- **客户端登录**：客户端走 HM 的 `/api/heicode-auth/*`（转发到登录服务）+ V2 设备签名；详见 `docs/integration/heicode-desktop-client-api.md`。 +- **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`。 ## 协作约定（根级） -1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/AGENTS.md` 为准；客户端 TS/React 以 `cc-haha/AGENTS.md` 为准。 -2. **小步提交**：沿用历史风格（如 `feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。 -3. **集成与「SK」边界**：平台契约见 [`docs/integration/agent-platform-api-design.md`](./docs/integration/agent-platform-api-design.md)，里程碑见 `docs/milestones/`。 -4. **不要臆测计费**：计费与订阅在平台侧，不在 Heicode 客户端内实现。 +1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/AGENTS.md` 为准；产品 / 架构以 `docs/heicode.md` + `docs/plan.md` 为准。 +2. **小步提交**：沿用历史风格（`feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。 +3. **不要臆测计费**：计费在平台侧（new-api 计量），按 `docs/` 契约对接，不在本仓臆造扣费逻辑。 -## 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/` -官网中的主按钮（登录/开始使用/CTA）默认应跳转到 `https://code.xinghanlab.com/`，避免出现历史 IP 地址。 - ## Manager 生产拓扑（Azure） -- 应用层：Azure VM 上运行 `heicode`（当前用 Docker 容器承载应用进程）。 -- 数据库与缓存：使用 Azure 托管服务（不在 VM 上跑 PostgreSQL/Redis 容器） - - PostgreSQL: `heicode.postgres.database.azure.com` / DB `heicode` - - Redis: `heicode.redis.cache.windows.net:6380`（TLS） -- 容器落盘：VM 仅承载应用进程；**容器内产生的文件**（如 `/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘，便于备份与重建容器后不丢。编排见 `heicode/docker-compose.azure-vm.yml`，目录由环境变量 `HEICODE_DATA_ROOT` 指定。 -- 说明：不要在生产 VM 上再启本地 `postgres`/`redis` 容器并指向业务库，避免与托管实例混淆。 -- 镜像清理：发版构建后删除悬空/旧镜像层（见上文「VM 部署后清镜像」），防止 OS 盘被 Docker 占满。 +- 应用层：Azure VM 上运行 `heicode`（Docker 容器承载应用进程）。 +- 数据库与缓存：Azure 托管服务（不在 VM 上跑 PostgreSQL / Redis 容器） + - PostgreSQL：`heicode.postgres.database.azure.com` / DB `heicode` + - Redis：`heicode.redis.cache.windows.net:6380`（TLS） +- 容器落盘：容器内产生的文件（`/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘。编排见 `heicode/docker-compose.azure-vm.yml`，目录由 `HEICODE_DATA_ROOT` 指定。 +- **VM 部署后清镜像**：每次 `docker compose ... up -d --build` 后执行 `sudo docker image prune -f`；定期 `sudo docker system prune -f`（不删在用卷），避免旧层占满磁盘。 +- **VM / 生产同步代码**：优先在目标机 `git clone` / `git pull` 与远程一致；不要用 `scp` 传整份源码（紧急热修例外）。 --- -*若本文件与子目录 `AGENTS.md` / `AGENTS.md` 冲突，以子目录为准并及时更新根文件摘要。* +*若本文件与 `heicode/AGENTS.md` 或 `docs/` 冲突，以子目录 / `docs` 为准并及时更新本文件。* diff --git a/CLAUDE.md b/CLAUDE.md index 2b25f1b0..0899eba9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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**：网关 + 管理控制台 | Go（Gin/GORM）+ `web/default` 前端（Bun/Rsbuild/React） | -| `website/` | 产品介绍站点 | Next.js；根 `docker-compose.yml` 提供 `heicode-www` :8888 | -| `docs/` | 愿景、**里程碑**（`docs/milestones/`）、**Agent 集成**（`docs/integration/`） | Markdown | - -根 `package.json` 仅少量 workspace 级依赖（如适配器用到的包）；**主要开发依赖在 `cc-haha/package.json`**。 +| `heicode/` | **Heicode Manager**：基于 new-api 的模型网关 + 管理控制台 | Go（Gin/GORM）后端 + `web/default` 前端（Bun/Rsbuild/React） | +| `docs/` | 产品共识 / 实施计划 / 集成契约 | Markdown，索引见 [`docs/README.md`](./docs/README.md) | ## 权威子文档（改代码前先打开对应一篇） -- **客户端（cc-haha）**：[`cc-haha/AGENTS.md`](./cc-haha/AGENTS.md) — 目录结构、运行命令、测试、提交约定。 -- **网关（heicode）**：[`heicode/CLAUDE.md`](./heicode/CLAUDE.md) — Go 分层、JSON/i18n/DB 规则等。 -- **产品愿景与交付节奏**：[`docs/vision-heicode-full-stack-agentic-dev.md`](./docs/vision-heicode-full-stack-agentic-dev.md)、[`docs/milestones/README.md`](./docs/milestones/README.md)。 +- **网关后端（`heicode/`，Go）**：[`heicode/CLAUDE.md`](./heicode/CLAUDE.md) — Go 分层、JSON / i18n / DB 规则、计费表达式等。 +- **产品共识与实施计划**：[`docs/heicode.md`](./docs/heicode.md)、[`docs/plan.md`](./docs/plan.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 -# 依赖（客户端主体） -cd cc-haha && bun install +Heicode Manager = `heicode/`（Go 后端 + `web/default` 前端）。构建 / 运行命令与分层规则以 [`heicode/CLAUDE.md`](./heicode/CLAUDE.md) 与 `heicode/README.md` 为准。 -# 终端 A：本地 API（桌面端依赖） -bun run src/server/index.ts +## 关键触摸点（代码索引） -# 终端 B：桌面 -cd desktop && bun run tauri dev -``` - -联调本机 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__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`）。 +- **客户端登录**：客户端走 HM 的 `/api/heicode-auth/*`（转发到登录服务）+ V2 设备签名；详见 `docs/integration/heicode-desktop-client-api.md`。 +- **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`。 ## 协作约定（根级） -1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/CLAUDE.md` 为准；客户端 TS/React 以 `cc-haha/AGENTS.md` 为准。 -2. **小步提交**：沿用历史风格（如 `feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。 -3. **集成与「SK」边界**：平台契约见 [`docs/integration/agent-platform-api-design.md`](./docs/integration/agent-platform-api-design.md)，里程碑见 `docs/milestones/`。 -4. **不要臆测计费**：计费与订阅在平台侧，不在 Heicode 客户端内实现。 +1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/CLAUDE.md` 为准；产品 / 架构以 `docs/heicode.md` + `docs/plan.md` 为准。 +2. **小步提交**：沿用历史风格（`feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。 +3. **不要臆测计费**：计费在平台侧（new-api 计量），按 `docs/` 契约对接，不在本仓臆造扣费逻辑。 -## 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/` -官网中的主按钮（登录/开始使用/CTA）默认应跳转到 `https://code.xinghanlab.com/`，避免出现历史 IP 地址。 - ## Manager 生产拓扑（Azure） -- 应用层：Azure VM 上运行 `heicode`（当前用 Docker 容器承载应用进程）。 -- 数据库与缓存：使用 Azure 托管服务（不在 VM 上跑 PostgreSQL/Redis 容器） - - PostgreSQL: `heicode.postgres.database.azure.com` / DB `heicode` - - Redis: `heicode.redis.cache.windows.net:6380`（TLS） -- 容器落盘：VM 仅承载应用进程；**容器内产生的文件**（如 `/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘，便于备份与重建容器后不丢。编排见 `heicode/docker-compose.azure-vm.yml`，目录由环境变量 `HEICODE_DATA_ROOT` 指定。 -- 说明：不要在生产 VM 上再启本地 `postgres`/`redis` 容器并指向业务库，避免与托管实例混淆。 -- 镜像清理：发版构建后删除悬空/旧镜像层（见上文「VM 部署后清镜像」），防止 OS 盘被 Docker 占满。 +- 应用层：Azure VM 上运行 `heicode`（Docker 容器承载应用进程）。 +- 数据库与缓存：Azure 托管服务（不在 VM 上跑 PostgreSQL / Redis 容器） + - PostgreSQL：`heicode.postgres.database.azure.com` / DB `heicode` + - Redis：`heicode.redis.cache.windows.net:6380`（TLS） +- 容器落盘：容器内产生的文件（`/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘。编排见 `heicode/docker-compose.azure-vm.yml`，目录由 `HEICODE_DATA_ROOT` 指定。 +- **VM 部署后清镜像**：每次 `docker compose ... up -d --build` 后执行 `sudo docker image prune -f`；定期 `sudo docker system prune -f`（不删在用卷），避免旧层占满磁盘。 +- **VM / 生产同步代码**：优先在目标机 `git clone` / `git pull` 与远程一致；不要用 `scp` 传整份源码（紧急热修例外）。 --- -*若本文件与子目录 `AGENTS.md` / `CLAUDE.md` 冲突，以子目录为准并及时更新根文件摘要。* +*若本文件与 `heicode/CLAUDE.md` 或 `docs/` 冲突，以子目录 / `docs` 为准并及时更新本文件。* diff --git a/README.md b/README.md index 8f90bbe5..05fa61b9 100644 --- a/README.md +++ b/README.md @@ -2,74 +2,40 @@ 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**（网关与管理控制台服务端；此为源码目录名）。 | -| `website/` | 产品介绍站点（Next.js；可 `pnpm dev` 或 Docker 预览）。 | -| `docs/` | 愿景与范式；**[`docs/milestones/`](./docs/milestones/README.md)** 交付里程碑；**[`docs/integration/`](./docs/integration/README.md)** Agent 等平台接口设计。 | +| `heicode/` | **Heicode Manager**：基于 new-api 的模型网关 + 管理控制台。Go（Gin/GORM）后端 + `web/default` 前端（Bun/Rsbuild/React）。 | +| `docs/` | 产品共识、实施计划与集成契约（索引见 [`docs/README.md`](./docs/README.md)）。 | + +> 客户端与官网不在本仓。 ## 产品在解决什么问题 -- **协作范式**：把瀑布 / 敏捷下的角色分工落到可复述的闸门与智能体承接边界（**方向与原则**见 `docs/vision-heicode-full-stack-agentic-dev.md`；编队明细在文档附录）。 +- **协作范式**：把瀑布 / 敏捷下的角色分工落到可复述的闸门与智能体承接边界。 - **交付可追溯**：文档、沟通与变更尽量与版本、发布对齐，便于复盘与合规。 -- **工程上**：同一仓库便于客户端与服务端**同步发版、统一回归**，减少「谁和谁版本对不上」的摩擦。 +- **模型与执行分层**：HM 提供模型网关与权限 / 计费；云端 agent 由 agent_management（AM）部署，客户端拿到 agent 公网地址后**直连 agent 使用**。 -## 详细愿景与范式 - -**[docs/vision-heicode-full-stack-agentic-dev.md](./docs/vision-heicode-full-stack-agentic-dev.md)** +产品定位与架构共识见 [`docs/heicode.md`](./docs/heicode.md)，实施计划见 [`docs/plan.md`](./docs/plan.md)。 ## 快速启动（开发联调） -```bash -# 根依赖（Bun monorepo 根目录） -bun install +Heicode Manager 在 `heicode/` 子目录：Go 后端 + `web/default` 前端。完整构建 / 运行命令与分层规则见 [`heicode/CLAUDE.md`](./heicode/CLAUDE.md) 与 `heicode/README.md`。 -# Heicode 客户端本地服务（目录 cc-haha） -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 登录相关的路由（最小集，以实际代码为准）： +与 Heicode 登录相关的最小路由（以实际代码为准）： - `GET /heicode/oauth/authorize` - `GET /heicode/oauth/session` -平台侧能力还包括模型发现（如 `GET /v1/models`）与 Anthropic Messages 兼容入口等，详见 **Heicode Manager**（`heicode/`）与 **Heicode 客户端**（`cc-haha/`）各自 README。 +平台侧能力还包括模型发现（如 `GET /v1/models`）与 Anthropic Messages 兼容入口等。 -## 官网（Next.js） - -```bash -cd website && pnpm install && pnpm dev -``` - -若根目录提供 `docker compose`，可按 compose 说明构建预览镜像（以仓库内 `docker-compose.yml` 为准）。 - -## 发版与回归建议 - -- 同一版本标签发布客户端与网关镜像。 -- 每次发版至少回归：**登录**、**模型拉取**、**对话请求**。 -- 先在本地 Docker / 本地联调通过，再做外网域名与证书。 - -## 相关外部参考（概念） - -- [oh-my-claudecode](https://ohmyclaudecode.com/) — Claude Code 类工具的高效实践参考。 -- Agent 平台以实际部署环境与文档为准。 +集成与对接契约见 [`docs/integration/`](./docs/integration/)（HM↔AM、桌面客户端对接等）。 ## 许可证 -各子项目许可证见各子目录内 `LICENSE`（例如 Heicode Manager / `heicode/` 侧常见为 AGPLv3）。 +`heicode/`（Heicode Manager，基于 new-api）许可证见 `heicode/LICENSE`（常见为 AGPLv3）。 diff --git a/docs/README.md b/docs/README.md index f0cd8fc8..13bd16ab 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,12 +7,12 @@ | [`heicode.md`](./heicode.md) | Heicode 当前产品定位、系统边界和架构共识 | | [`plan.md`](./plan.md) | 按当前共识拆出的实施计划 | | [`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 模式、瀑布/敏捷、蜂群模式的已完成/未完成/依赖/风险/下一步进度清单 | -| [`heicode-manager-standalone-execution-plan.md`](./heicode-manager-standalone-execution-plan.md) | Heicode Manager 端可独立完成任务的执行计划、顺序、验收标准和边界 | -| [`integration/Heicode-登录接口对接文档.md`](./integration/Heicode-登录接口对接文档.md) | 已上线登录接口对接文档 | -| [`integration/agent-platform-request-contract.md`](./integration/agent-platform-request-contract.md) | Manager 请求 Agent 平台时携带的部署、日志、监控、事件与审计接口参数 | +| [`integration/heicode-hm-template-agent-model.md`](./integration/heicode-hm-template-agent-model.md) | **当前模型**：模板 Agent + 客户端直连，HM 端后端/前端改造说明 | +| [`integration/heicode-hm-legacy-teardown.md`](./integration/heicode-hm-legacy-teardown.md) | 旧 sub 任务编排模型的代码/表/前端删除清单 | +| [`integration/heicode-desktop-client-api.md`](./integration/heicode-desktop-client-api.md) | 桌面客户端对接 HM（模板 Agent 模型），已生产验证 | +| [`integration/heicode-am-contract.md`](./integration/heicode-am-contract.md) | HM ↔ AM（agent_management）接口契约 | | [`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 / 蜂群任务编排、旧里程碑、旧架构说明和旧上手材料不再作为实施依据（相关文档已删除）。当前实施模型以 `heicode.md`、`plan.md` 与 `integration/heicode-hm-template-agent-model.md` 为准；生产部署操作以安全守卫文档约束，且不得覆盖产品/架构主线。 代码中的过渡期命名、旧接口注释或旧 UI 文案只作为现状参考；若与 `heicode.md` / `plan.md` 冲突，应先更新实现或另行补充当前主线文档，不得恢复旧 Agent/M1-M5 草案作为依据。 diff --git a/docs/integration/agent-platform-request-contract.md b/docs/integration/agent-platform-request-contract.md deleted file mode 100644 index 05e77bcc..00000000 --- a/docs/integration/agent-platform-request-contract.md +++ /dev/null @@ -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 服务身份令牌，由 Secret Store/运行环境注入。 | -| `Content-Type: application/json` | POST/PUT 是 | JSON 请求体。 | -| `X-User-Id: ` | 建议 | 登录用户边界；也可从 Manager 服务端 token 或 body `user_context.user_id` 推导。 | -| `X-Binding-Scope: ` | 建议 | Git/SK/云资源作用域；也可从 `resource_grants[].binding_scope` 推导。 | -| `X-Correlation-Id: ` | 是 | Manager 生成，全链路追踪。 | -| `X-Request-Id: ` | 建议 | 单次 HTTP 请求追踪 ID，可与 correlation_id 不同。 | -| `Idempotency-Key: ` | 创建类接口建议 | 避免重试造成重复部署。 | - -### 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 | 否 | 路径、分支、区域、超时等限制；不得含密钥字段。 | -| `metadata` | object | 否 | 资源展示/审计元数据；不得含密钥字段。 | -| `status` | enum | 是 | `pending` / `active` / `disabled` / `revoked`。 | -| `secret_ref` | string | 条件必填 | `git`、`sk`、`cloud_account`、`cloud_resource` 必填；`project_doc` 可为空。 | -| `audit` | object | 否 | 审计上下文；不得含密钥字段。 | - -### 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 不得把“本地占位通过”误报为“生产日志/监控已上线”。 diff --git a/docs/product-package/03-user-journey-and-core-flow.md b/docs/product-package/03-user-journey-and-core-flow.md index 955f0f9e..fdbba623 100644 --- a/docs/product-package/03-user-journey-and-core-flow.md +++ b/docs/product-package/03-user-journey-and-core-flow.md @@ -129,19 +129,18 @@ Backend Agent ### 7. Agent 执行闭环 -Heicode 不是只把任务丢给 Agent 一次就结束，而是会在开发过程中持续调用 Agent 完成子环节。 +部署后客户端拿到 agent 的公网地址，**直连 agent 持续对话推进开发**（HM 不在对话回路；agent 用模型时走 HM `/v1`）。 闭环应表达为： ```text -客户端输入目标或追加需求 --> Heicode 生成下一步任务 --> Agent 执行需求/设计/开发/测试/修复中的当前子环节 --> Agent 按需要调用已授权的 SK 工具 --> Heicode 回传中间结果给客户端 --> 用户继续追问、修正或审批 --> Agent 继续下一子环节 --> 最终由 Agent 完成交付整理与部署 +客户端直连 agent，输入目标或追加需求 +-> agent 自行推进需求/设计/开发/测试/修复 +-> agent 按需要调用已授权的 SK 工具 +-> agent 用模型时走 HM /v1（计费到用户） +-> 中间结果与产物回到客户端 +-> 用户继续追问、修正或审批高危动作 +-> agent 继续推进，直至交付整理与部署 ``` 这意味着用户看到的不是一次性“已部署 Agent”，而是一个可连续推进的开发循环。 diff --git a/docs/product-package/12-narrated-user-operation-flow.md b/docs/product-package/12-narrated-user-operation-flow.md index d37c4d27..a40113cd 100644 --- a/docs/product-package/12-narrated-user-operation-flow.md +++ b/docs/product-package/12-narrated-user-operation-flow.md @@ -246,13 +246,13 @@ Ops Agent 请求部署到生产环境。 这里的真实闭环是： ```text -我在客户端补充要求 --> Heicode 判断下一步要推进哪个子环节 --> Agent 执行需求、开发、测试、修复或部署中的当前任务 --> Agent 按权限调用已绑定的 SK 工具 +我在客户端直连 agent、补充要求 +-> agent 自行推进需求、开发、测试、修复或部署中的当前任务 +-> agent 按权限调用已绑定的 SK 工具 +-> agent 用模型时走 HM /v1 -> 中间结果回到客户端 -> 我继续修正方向或批准高危动作 --> Agent 继续推进直到交付和部署完成 +-> agent 继续推进直到交付和部署完成 ``` ### 18. 查看执行状态