docs: 同步文档到当前实际（HM-only 仓 + 模板 Agent 模型）

- 根 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 <noreply@anthropic.com>

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_<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`）。
+- **客户端登录**：客户端走 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` 为准并及时更新本文件。*

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_<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`）。
+- **客户端登录**：客户端走 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` 为准并及时更新本文件。*

README.md

@@ -4,72 +4,38 @@ 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）。

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 草案作为依据。

docs/integration/agent-platform-request-contract.md

@@ -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/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”，而是一个可连续推进的开发循环。

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. 查看执行状态