heicode-mananger/docs/Heicode-Manager-agent统一改造落地计划.md

Heicode Manager 统一改造落地计划（Manager 侧）

版本：v0.1（初稿） 日期：2026-06-01 负责范围：仅 heicode-mananger（Manager 控制面 + web/default 前端） 性质：内部落地计划，随实现推进持续更新。不代表对外承诺。

状态更新（2026-06-01）：agnet → agent 已按"强制全量、不留兼容"完成。 后端 Go（路由 /api/agent/*、env AGENT_*、结构体/函数/文件名）、前端（agent-console/agent-hub、/api/agent 调用、i18n）、DB（表 agent_*、列 agent_id，并加幂等迁移 renameAgnetTablesToAgent 保住老数据）、文档、compose/.env、脚本均已统一为 agent。 go build ./... 与 go test ./controller ./model ./router ./middleware 全绿；前端 tsc -b 通过。 本文 §3 原描述的"保留 agnet 兼容别名/线缆令牌"策略已作废——实际采用一次性硬切。唯一保留 agnet 字样的是 model/main.go 的迁移源表名（迁移所必需）。 部署待办：① VM .env 的 AGNET_* 改名 AGENT_*；② 启动时迁移自动 rename 老表（已就绪）；③ 其他三仓库（agent_management / HeiCode-Swarm / 客户端）需同步切到 /api/agent 与新 env，否则跨服务对接在它们切换前会中断（按你的要求强制先行）。

0. 基准文档

本计划是以下两份的 Manager 侧拆解执行版，结论以原文为准：

来源	位置	作用
统一调用方案 v0.1	gitee taijibaga/heicodedebug → 2026-06-01_heicode客户端相关定义.md	四仓库总纲：接口归口、模式拆分、状态裁决、产物、回调
全链路代码评审报告	gitee taijibaga/heicodedebug → 2026-06-01_Heicode全链路代码评审报告.md	P1–P7 问题与证据
桌面 sub 对接文档	docs/integration/heicode-desktop-sub-agile-api.md	现行普通 sub 契约

四仓库分工（总纲 §4）：客户端只调 Manager；Manager 是唯一接口入口 + Runtime 路由器 + 唯一状态裁判；agent_management 执行 Sub Agile；HeiCode-Swarm 执行 Swarm。

1. 贯穿全局的原则（来自总纲）

1. agnet 是历史拼写错误，统一为 agent；旧接口兼容期只做转发。
2. Sub Agile 与 Swarm 是两套运行时，不再复用 /api/swarms 表达两种模式，按 mode 路由。
3. Runtime 只上报结构化事实；Manager 据结构化字段裁决 display_status；客户端只消费结论，不再用正则自判产物。
4. 安全红线：只传 azkv:// 等 secret_ref，禁明文密钥；高危操作 Manager 先审批再下发。

2. 已完成（分支 fix/manager-deliverable-and-secret-validation，commit 12602eb，已推送）

项	文件	内容	对应总纲
P2 交付物判定	controller/agnet_runtime_client.go	runtimeArtifactsAreSummaryOnly 改读结构化 artifact_type+文件信号，弃脆弱正则	§10.6
P6a secret_ref 校验	controller/resource.go	Resource CRUD 强制 azkv://	§16/§17.6
P6b 值级密钥扫描	controller/resource.go、controller/agnet_control_plane.go	containsPlaintextSecret/containsSensitiveGrantField 扫字符串值（sk-/JWT/PEM）	§16
P5 默认模型收敛	controller/agnet_role_template.go、controller/agnet_task_bridge.go	单一来源 defaultAgnetModelID()（env AGNET_DEFAULT_MODEL_ID，默认 gpt-5.4）；移除 agnet-model-<role> 占位回退	§9
P3 状态枚举	docs/integration/heicode-desktop-sub-agile-api.md	补 completed 终态 + runtime_state 镜像 + 未知值兜底	§10.4
单测	controller/agnet_deliverable_secret_test.go	覆盖以上行为	—

注：defaultAgnetModelID 在后续命名统一中应改名 defaultAgentModelID，env 改 AGENT_DEFAULT_MODEL_ID（保留 AGNET_* 回退）。

3. 命名统一 agnet → agent

3.1 爆炸半径（仅本仓库，不含另三仓库与跨团队契约）

2155 处 / 63 文件（rg -i agnet）。按「客户端/其他服务是否依赖」分类：

类别	规模	对外可见	处理策略	风险
HTTP 路由 /api/agnet/*	路由表	✅ 客户端+Runtime	新增 /api/agent/* 别名，旧保留转发	🔴
JSON 字段	仅 agnet_id（3 处，含 DB 列）	✅ resource grant 契约	响应 dual-emit agent_id，请求 dual-accept	🟠
env 变量 AGNET_*	compose + 代码读取	✅ 部署配置	代码先读 AGENT_* 回退 AGNET_*	🟠
DB 表 agnet_* / agnet_id 列	~6 表	❌ 内部	用 GORM TableName() 钉住物理名不动，物理改名作为最后单独迁移	🔴
Go 内部标识（AgnetXxx、函数、文件名 agnet_*.go）	~1800	❌ 编译期可查	纯重构，分模块小步改	🟢
前端（agnet-console/、组件、i18n key）	~250	❌ 内部（调的是路由）	重构，随路由切换	🟢
文档	多处	—	新文档写 agent，agnet 标 deprecated	🟢

3.2 兼容期规则（总纲 §19）

1. 旧接口只做转发。2. 新文档只写新接口。3. 新客户端只调新接口。4. Manager 内部存储统一 agent 命名。5. 日志可记 legacy route，不展示给普通用户。

4. 路由拆分与归口（总纲 §5）

4.1 客户端 → Manager（新增）

/api/heicode/capabilities
/api/heicode/sub-agile/tasks/...     （或统一 /api/heicode/tasks + body.mode）
/api/heicode/swarm/tasks/...

4.2 Manager → Runtime（新增，按 mode 分流）

/api/agent/sub-agile/deployments  -> agent_management   (AGENT_RUNTIME_* / 现 AGNET_RUNTIME_*)
/api/agent/swarm/deployments      -> HeiCode-Swarm       (SWARM_RUNTIME_*)

Manager 已具备双 env 前缀分流机制（agnetRuntimeClientConfigForMode）；蜂群侧配置就绪只差 SWARM_RUNTIME_SERVICE_TOKEN。

4.3 回调（新增 + 旧转发）

新：POST /api/agent/callbacks/runtime-events
旧：POST /api/agnet/callbacks/swarm-events   （兼容转发到同一 handler）

5. 状态裁决：Manager 成为唯一裁判（总纲 §10，关联评审 P1）

5.1 三层状态 + display_status

• client_task_status（客户端本地）/ cloud_deployment_status（Manager）/ runtime_execution_status（Runtime）
• Manager 输出唯一 display_status 给客户端。

5.2 Runtime 必须上报的结构化交付物事实（契约）

"deliverable": {
  "has_deliverable": true,
  "summary_only": false,
  "artifact_ids": ["art_xxx"],
  "files_modified": ["src/app.ts"],
  "has_diff": true,
  "commit_sha": ""
}

5.3 Manager 裁决规则

Runtime 事实	display_status
completed + has_deliverable + !summary_only	completed
completed + summary_only / 无 artifact	completed_without_deliverable 或 needs_codegen
failed	failed / stopped / waiting_approval 同名透传

5.4 Manager 落点

• controller/agnet_callback.go（applyAgnetCallbackDeploymentState 消费 deliverable，算 verdict）
• model/agnet_deployment.go（加 DeliveryVerdict / display_status 列，三库兼容 varchar）
• controller/agnet_control_plane.go（detail/timeline 暴露字段）
• 复用已就绪的 artifactIsSummaryOnly（P2）+ usage
• 阶段化：先加派生字段不改 status（向后兼容）→ 客户端跟进后再引入新终态值。

6. 模型策略（总纲 §9）

• Sub Agile：per_role / default；Swarm：primary。
• 单一来源默认模型（P5 已起步，待改名 defaultAgentModelID）。
• Manager 校验：模型存在 / 套餐允许 / 角色允许 / 预算 / Runtime 支持。

7. 项目文件夹产物 project_folder（总纲 §12）—— 中期大件

• artifact 升为两级：Project Artifact → File Artifacts / Directory Entries。
• 新 artifact_type：project_folder / project_archive（现有 code_patch/document/... 保留）。
• 新增接口：.../artifacts/{id}/manifest、.../files/{path}、.../archive。
• 本地修改回传 + revision 协议（§12.7）：local-edits / batch / 冲突 ARTIFACT_REVISION_CONFLICT / Manager 维护 current accepted revision。
• 影响：新 model（artifact revision / project entries）、新 controller、content 代理扩展。工程量大，单独立项。

8. 云部署生命周期（总纲 §18）—— 远期

project_folder → 选 target(Azure/阿里云/AWS) → Manager 校验/审批/凭证/预算 → Deploy Worker/Runtime 执行 → deployment_manifest artifact 回传。远期，本轮不展开。

9. 安全与审计（总纲 §16/§17）

项	现状	待办
secret_ref 强制 azkv://	✅ agnet 路径 + Resource CRUD（P6a）	覆盖其余写入路径
值级密钥扫描	✅ P6b	—
高危操作 Manager gate	❌ 现为立即 accepted，阻断依赖 Runtime	Manager 侧加 risk_level/pending 审批 gate（关联 P1/§17.1）
短期凭证 lease 真派生	❌ 占位（只发 lease://，不 mint）	接 Key Vault 派生短期凭证
revoke 同步 Runtime	⚠️ approve 有 sync，revoke 无	补 revoke→Runtime 通知
审计 fail-closed	⚠️ best-effort	关键审计改 fail-closed 或告警
客户端禁 inline secret_ref	—	Manager 改为接受 resource_binding_id，内部映射 secret_ref（§17.6）

10. 落地阶段（总纲 §20，Manager 承担）

阶段	Manager 任务	自主性	依赖	状态
1 接口/命名	/api/agent/* 别名、/api/heicode/{sub-agile,swarm}/*、callback 新路由、AGENT_* env 回退、agnet_id→agent_id 双字段	✅ 加法自主	—	待开始
2 模式路由	按 mode 路由两套 *_RUNTIME_*	✅	蜂群 token	机制已就绪
3 模型策略	per_role/primary 校验	✅	—	P5 起步
4 状态/产物裁决	display_status + deliverable 字段 + project_folder + revision	🟡	Runtime 发结构化事实	P1/P2 起步
5 日志/回调/调试	user_logs/debug_logs 分层 + diagnostics + 统一 callback	✅	Runtime callback 切换	diagnostics 已有雏形

11. 跨团队依赖（Manager 做不了，需协调）

1. agent_management / HeiCode-Swarm：上报结构化 deliverable 事实；接入 /api/agent/{sub-agile,swarm}/* 路由；callback 切 /api/agent/callbacks/runtime-events；产出真实 project_folder。
2. 蜂群 Runtime：SWARM_RUNTIME_SERVICE_TOKEN 安全配置 + 修复 single-agent fallback（评审 P7）。
3. 客户端（macOS/Windows）：切新接口、消费 display_status、project 文件树展示、本地 edit 上传、禁 mock/直连（§17）。

12. 风险与红线

• agnet 是 load-bearing（路由/env/DB/跨服务契约）——严禁全局 sed，必须加法别名 + 兼容期。
• DB 物理表/列名暂不改，用 TableName() 钉住，避免迁移风险。
• 跨服务契约字段改动一律 dual-emit + dual-accept，且需与调用方协调切换节奏。
• 状态裁决先加字段不覆盖 status，避免误伤「真完成但 Runtime 未回 artifact」的任务。

13. 待确认事项

1. 统一方案仍是 v0.1，落地前需与作者对齐版本/范围。
2. approval decision 回传路径：/api/agent/{mode}/deployments/{id}/approvals/{approval_id} 的最终形态。
3. 客户端→Manager 路由用「分模式」还是「统一 /api/heicode/tasks + body.mode」。
4. needs_codegen 与 completed_without_deliverable 的判定边界（何时用哪个）。
5. project_folder / 云部署的优先级与排期（是否本阶段做）。

---

维护：本文件随实现进度更新；每完成一项在「已完成/状态」列标注 commit。