xiaohei/heicode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
15b17f39b003431c5430ade47da1272dbbb0df77
heicode/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

9.9 KiB
Raw Blame History

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. 生产拓扑

用户/桌面客户端
  -> 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 当前主流程

桌面客户端创建/补充任务
  -> 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 规则

生产部署原则：

本地修改
-> 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