taijibaga/heicode-mananger
9
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
0fe1d20d676d9a04d82d0e3cdfe89bff262fe3e0
heicode-mananger/Heicode-Manager-项目说明与踩坑交接.md
T
chenchenandClaude Opus 4.8 0fe1d20d67 feat(agent): unify agnet→agent and implement client/runtime unification spec v0.1 core 
按桌面客户端统一方案 v0.1 + agent_management Sub Mode Runtime 对接,强制全量统一,不留兼容。

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

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

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

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-01 23:45:10 +08:00

209 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Heicode Manager 项目说明与踩坑交接
更新时间：2026-06-01
用途：给下一位 AI / 工程师快速理解 Heicode Manager 的项目边界、生产拓扑、普通 sub、蜂群、NewAPI 和已踩过的坑。
## 1. 一句话说明
Heicode Manager 是 Heicode 的服务端控制面和网页管理台，负责用户登录、模型网关配置、用户/设备/模型/渠道管理、普通 sub 敏捷任务控制、Runtime callback 落库、artifact/timeline 展示，以及和桌面客户端、Agent Manager Runtime、NewAPI、Azure Key Vault 之间的编排。
它不是桌面客户端本体，也不是 Agent Runtime 本体，也不是 NewAPI 本体。
## 2. 仓库结构
| 路径 | 作用 | 说明 |
|------|------|------|
| `heicode/` | Manager 后端和默认前端 | Go + Gin/GORM，`web/default` 是当前网页端 |
| `cc-haha/` | Heicode 桌面客户端和本地服务 | Tauri + React + Bun，客户端到 Manager 的请求 body 会走加密/签名流程 |
| `docs/` | 项目文档、部署、集成、进度清单 | 后续交接优先看这里 |
| `docs/deployment/` | 生产部署和迁移文档 | VM、Azure、配置交接 |
| `docs/integration/` | Runtime、桌面客户端、蜂群、普通 sub 对接文档 | 联调时优先看 |
开发前先看：
| 范围 | 文档 |
|------|------|
| 根仓库规则 | `AGENTS.md` |
| Manager 规则 | `heicode/AGENTS.md` |
| 生产配置 | `docs/deployment/Heicode-Manager-生产配置与账号交接清单.md` |
| 普通 sub 桌面客户端对接 | `docs/integration/heicode-desktop-sub-agile-api.md` |
| 普通 sub Agent Manager 对接 | `docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md` |
| 蜂群 Agent Manager 对接 | `docs/integration/蜂群模式-AgentManager对接任务清单.md` |
## 3. 生产拓扑
```text
用户/桌面客户端
-> https://code.xinghanlab.com
-> Heicode Manager Docker container on Azure VM
-> Azure PostgreSQL / Azure Redis
-> NewAPI model gateway
-> 普通 sub Agent Manager Runtime: http://20.212.121.126
-> 蜂群 Runtime / Orchestrator: http://52.139.240.116:8000
-> Azure Key Vault: https://heicode-kv.vault.azure.net
```
当前 Manager 部署在 Azure VM 上，容器名 `heicode`，端口 `3000:3000`。VM 上也能看到 `new-api`、`postgres`、`redis`、`heicode-openbao` 容器，但正式业务数据库和缓存应以 Azure 托管 PostgreSQL / Redis 配置为准，不要误用 VM 本地容器判断生产数据。
## 4. 普通 sub 和蜂群必须分开
这是最容易踩坑的点。
| 模式 | 含义 | Manager 当前配置 | Runtime |
|------|------|------------------|---------|
| 普通 sub 敏捷模式 | 桌面客户端把一个开发任务拆给若干子 Agent，按需求、设计、开发、测试、部署等阶段推进 | `AGENT_RUNTIME_ENABLED=true` | `http://20.212.121.126` |
| 蜂群模式 | HeiCode-Swarm 的多 Agent swarm run / task graph 模式 | `SWARM_RUNTIME_ENABLED=false` | `http://52.139.240.116:8000`，需单独启用和联调 |
不要因为两个接口都可能叫 `/api/swarms` 就把它们混成一个概念。普通 sub 是 Heicode 的任务组织方式；蜂群是独立 swarm runtime 形态。
## 5. 普通 sub 当前主流程
```text
桌面客户端创建/补充任务
-> Manager 用户态接口生成 deployment draft
-> Manager 调 Agent Manager Runtime POST /api/swarms
-> Runtime 创建 run 并启动子 Agent
-> Runtime 执行中 callback Manager
-> Manager 保存 timeline / events / logs / artifacts / usage
-> 桌面客户端从 Manager 查询展示
```
关键点：
1. Runtime 执行过程会回调状态、日志、timeline、用量。
2. 最终业务交付物不是直接塞在聊天文本里，而是通过 `artifact.created` 落库。
3. 客户端应先查 artifact 列表，再通过 content 接口下载完整产物。
4. 如果 `usage=0` 或只有失败摘要 artifact，不能算真实业务交付完成。
## 6. artifact 展示坑
桌面客户端曾出现“以下是作为 Frontend 角色...”这种内容，看起来像交付物，其实多半只是 Runtime 的摘要文本。
正常设计应该是：
| 层级 | 应展示什么 |
|------|------------|
| 聊天时间线 | 阶段进度、Agent 状态、摘要说明 |
| 交付产物卡片 | `artifact_id`、标题、类型、摘要、大小、hash、下载入口 |
| 完整代码/文件 | 通过 `GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content` 下载 |
如果 artifact 里有 `azblob://...` 或 `runtime://...`，客户端不应该直接暴露云凭据或要求用户自己访问 Blob，而应通过 Manager / Runtime content 代理接口拿完整内容。
## 7. NewAPI / 模型调用边界
NewAPI 是模型网关和用量计费入口，不是 Heicode Manager 自己的模型执行器。
排查模型问题时要区分三条链路：
| 链路 | 调用方 | 常见问题 |
|------|--------|----------|
| 桌面普通聊天 | 桌面客户端 -> Manager/NewAPI | 用户 token、模型列表、渠道权限、body 加密 |
| 普通 sub Runtime Agent | Runtime 子 Agent -> NewAPI/Manager 模型网关 | Runtime 环境变量、模型名、base_url、请求路径、上游超时 |
| Manager 后台模型配置 | 管理员网页 -> Manager/NewAPI | 渠道配置、分组、可用模型、价格表达式 |
曾踩过的坑：
- 某个模型 503/504 时，不一定是客户端参数错，也可能是 Runtime 子 Agent 使用的模型、base_url 或请求格式不对。
- Runtime 需要回传 `newapi_request_id` 和非零 token usage，方便定位 NewAPI 日志。
- 一个模型失败时可以切换模型验证，但不能把失败摘要 artifact 当成业务完成。
## 8. Azure Key Vault / OpenBao 边界
当前正式方向是 Azure Key Vault，不是 OpenBao。
| 项目 | 结论 |
|------|------|
| Azure Key Vault | 正式长期密钥托管方案 |
| OpenBao | VM 上存在历史/兼容容器，不作为当前正式方案 |
| Managed Identity | Manager 访问 Key Vault 的推荐方式 |
| 当前已知问题 | 之前健康检查出现过 `Identity not found`，说明 VM 身份或 `AZURE_CLIENT_ID`/Vault 权限未配好 |
如果后续迁移到 Container Apps / AKS / App Service，不能只切域名。必须重新配置 Managed Identity、Key Vault 权限、环境变量、持久化、数据库/Redis 网络、Runtime callback 地址。
## 9. 登录、设备、模型列表问题排查
之前遇到过用户登录成功但设备看不到、模型列表拿不到的问题。排查顺序：
1. Manager 是否有该用户记录。
2. JWT/session 是否能通过 Manager 校验。
3. 设备注册/心跳是否入库。
4. 用户是否绑定 NewAPI channel/group/token。
5. NewAPI 返回是否 401/403/模型列表为空。
6. Mac/Windows 客户端请求是否走同一 base_url、同一加密/签名逻辑。
不要只看“客户端显示已登录”，已登录不代表模型、设备、NewAPI 绑定都完整。
## 10. 网页端 Manager 已做过的重点
已处理过的方向包括：
- 注册页国内邮箱提示。
- Manager 登录后菜单跳转问题。
- 任务总览 / deployments 页面部分英文文案中文化。
- 普通 sub 控制面、部署草稿、运行状态、timeline、events、logs、artifacts 展示。
- artifact content 获取链路文档。
- Azure Key Vault secret_ref 接入方向。
- PayPal 充值和 NewAPI 模型费用关系说明文档。
继续改网页端时必须真实点击验证，尤其是：
- 登录后左侧菜单。
- 模型、渠道、供应商、支付、部署、任务总览。
- 创建新运行弹窗/抽屉。
- 产物卡片和下载入口。
## 11. 部署和 git 规则
生产部署原则：
```text
本地修改
-> git commit
-> git push 到 heicode-mananger main
-> VM 上 git pull
-> docker compose ... up -d --build
-> sudo docker image prune -f
-> 真实接口/页面冒烟
```
注意：
- 不要用 `scp` 传整份源码到 VM。
- `HeiCode-issues.git` 已废弃，后续不用再更新。
- VM 构建后必须清理 Docker 镜像，避免磁盘被旧层占满。
- 不要提交 `.env`、密钥、token、数据库连接串。
## 12. 新 AI 接手建议顺序
1. 读 `AGENTS.md` 和 `heicode/AGENTS.md`。
2. 读 `docs/deployment/Heicode-Manager-生产配置与账号交接清单.md`。
3. 用 `git status` 确认是否有未提交变更，不要动无关文件。
4. 区分当前任务是普通 sub、蜂群、网页端、NewAPI、Azure 还是桌面客户端。
5. 先用接口确认真实状态，再下结论。
6. 涉及生产前先确认是否需要部署，部署后必须真实冒烟。
7. 涉及密码、token、连接串时只写配置名和获取位置，不写明文。
## 13. 已踩过的典型坑
| 坑 | 正确处理 |
|----|----------|
| 把普通 sub 和蜂群混在一起 | 两套模式、两套配置、两套联调清单 |
| artifact 摘要当完整交付 | 必须通过 content 接口拿完整产物 |
| Runtime 返回 completed 就算成功 | 还要看 usage、artifact、日志、是否失败摘要 |
| Key Vault health 报错只改代码 | 先查 Managed Identity 和 Vault 权限 |
| NewAPI 一个模型失败就判 Manager 错 | 查 Runtime 请求路径、模型名、request id、上游状态 |
| VM 上有 postgres/redis 容器就当生产库 | 以 `SQL_DSN`、`REDIS_CONN_STRING` 和 Azure 托管服务为准 |
| 修改网页后不点击验证 | 必须真实打开页面、点菜单、点按钮 |
| 把密钥写入 md 方便交接 | 只能写配置名、用途、位置，不能写明文 |
## 14. 当前后续重点
| 方向 | 后续任务 |
|------|----------|
| 普通 sub | 持续和桌面客户端联调真实开发任务，确认 artifact content 是完整业务产物 |
| 蜂群 | 如需启用，先配置 `SWARM_RUNTIME_*`，单独跑蜂群 E2E |
| Key Vault | 修复 Managed Identity / `AZURE_CLIENT_ID` / Key Vault 权限 |
| NewAPI | 保持 Runtime 回传 `newapi_request_id`、usage、成本信息 |
| 网页端 | 继续中文化、交互完善、真实点击测试 |
| 生产部署 | 每次部署后检查 `/api/status`、登录、deployments、Runtime health |
Reference in New Issue View Git Blame Copy Permalink