heicode/docs/integration/heicode-hm-legacy-teardown.md

Heicode Manager 旧 Sub 任务编排模型 — 删除清单（Teardown）

更新时间：2026-06-03 背景：sub 模式已切到「模板 agent + 客户端直连」新模型（见 heicode-hm-template-agent-model.md）。 本文列出要删除的旧代码 / 旧逻辑 / 旧数据 / 旧 DB 表与字段 / 旧前端，并标注共享/有依赖、需评估的部分。 图例：🗑️ 删整块 · ✂️ 改/裁剪保留 · ⚠️ 评估/待确认（有共享或外部依赖）

---

0.0 依赖与影响分析（已实查代码，2026-06-03）

⚠️ 结论先行：新模型「部署模板 agent」是现有部署控制面的演进，不是推倒重来。 多个文件是混合的——新模型要复用的「调 AM 客户端 / 部署记录 / 资源注入」管线，和旧任务逻辑同处一文件。只能外科式删旧分支，不能整文件删。

必须保留为骨架（新模型直接复用，删了新 API 就得重写）：

• agent_runtime_client.go 的 AM HTTP 客户端：agentRuntimeClientConfigForMode（heicode_capabilities.go 在用）、agentRuntimeURL/Headers/CreatePayload/StopPath/StatusPath、AgentRuntimeHealth → 新 StartAgent/StopAgent 靠这套。
• agent_control_plane.go 的 AgentCreateUserDeployment / List / Get / Stop + AgentDeployment 表 → 新 agent 记录复用/扩展它（加 subdomain/token/binding_ids 字段），不另起 heicode_agent 新表、不 DropTable。
• agent_task_bridge.go 的 resolveResourceBindingIntoGrant → 改造为「拼 env」，复用资源解析。

唯一纯旧、可删的核心函数： withDisplayStatus（agent_runtime_client.go:832）。被 agent_control_plane.go 的 1191/1200/1222 调用 → 删它要同步改这三处（Get/List 不再套 display_status）。

这修正了本文档早先两处过删：

1. agent_runtime_client.go / agent_control_plane.go 不是"删/整改"，是保留骨架 + 删旧 helper。
2. AgentDeployment 表不删——它就是新 agent 记录的载体（与 heicode-hm-template-agent-model.md §4 的 heicode_agent 二选一，建议复用 AgentDeployment 扩字段，两文档据此对齐）。

确认会被波及、需同步处理： router/agent_runtime_http_smoke_test.go（引用 tasks/deployments，删路由后编译失败 → 同步删/改）。

---

0. 删除原则

• 删之前先确认计费不依赖任务记录：计费走 /v1/* relay（携带用户身份），与 agent_deployments 无关 → 删任务表不影响计费。✅
• DB 注意：GORM AutoMigrate 只加列、不删表/列。删表用 DB.Migrator().DropTable(...)（三库通用、SQLite 可 DropTable）；废弃列可留着不动（无害）或 Migrator().DropColumn（SQLite 早期版不支持 DropColumn，保守做法是留列只停写）。
• 删除分两步走：先摘路由 + 删 handler（接口立即下线），再清 model/表 + 前端。
• 保护项（CLAUDE.md Rule 5）：new-api / QuantumNous 任何标识不动。

---

1. 后端路由（heicode/router/api-router.go）

标记	位置	内容
🗑️	registerHeicodeTaskRoutes（约 530–567 行）整个函数 + heicodeSubAgileRoute/heicodeSwarmRoute 两组注册	/api/heicode/{sub-agile,swarm}/tasks/* 全套（create/list/detail/messages/execute/stop/workflow/logs/events/metrics/diagnostics/artifacts*/approvals*/deployments）
🗑️	GET /heicode/deployment-targets（约 67 行）	HeicodeDeploymentTargets
✂️	agentApprovalRoute 下 /user/deployments*（约 510–523 行）	拆分：核心 GET 列表 / GET 详情 / POST 创建 / stop（AgentList/Get/Create/StopUserDeployment）→ 新模型复用（可保留或新增 /api/heicode/agents 走同一 handler）；旧任务子接口 logs/metrics/events/artifacts/timeline/sk-snapshots/deployment-draft → 🗑️ 删
✂️	apiRouter.POST("/agent/callbacks/runtime-events")（62–63 行）	保留路由，但 handler 收缩为只收 agent 生命周期（见 §3）

新模型新增的 /api/heicode/agent-templates、/api/heicode/agents* 见 model 文档 §4，不在本删除文档范围。

---

2. 后端 Controller

整文件删除 🗑️（均为旧 sub 任务编排专属）

文件	内容
controller/heicode_task_create.go	HeicodeCreateSubAgileTask/ListSubAgileTasks/CreateSwarmTask/ListSwarmTasks/HeicodeTaskMessage/HeicodeTaskExecute/HeicodeDeleteTask/consumeActiveRevision
controller/heicode_client_routes.go	HeicodeTaskWorkflow、HeicodeListTaskApprovals
controller/heicode_project_artifacts.go	HeicodeListTaskArtifacts/HeicodeArtifactManifest/Archive/File/Revisions
controller/heicode_artifact_edits.go	HeicodeArtifactLocalEdit（local-edits/revision 回传）
controller/heicode_cloud_deploy.go	HeicodeCreateDeployment/HeicodeListDeployments/HeicodeDeploymentTargets（旧代部署控制面）
对应 *_test.go	agent_deliverable_secret_test.go 等针对上述逻辑的测试

保留骨架 + 外科式删旧分支 ✂️（详见 §0.0；这些是新模型复用的底座，不可整删）

文件	保留（新模型复用）	删/改的旧分支
controller/agent_runtime_client.go	AM HTTP 客户端全套：agentRuntimeClientConfigForMode(capabilities 在用)/agentRuntimeURL/Headers/CreatePayload/StopPath/StatusPath/AgentRuntimeHealth	删 withDisplayStatus(832)、heicodeClientMode、agentRuntimeArtifactContentPathForRecord、agentRuntimeBudgetPayload；agentRuntimeRequest{Agents,SwarmAgents,ResourceGrants} 改造为模板 env 注入
controller/agent_control_plane.go	AgentCreateUserDeployment/List/Get/Stop + 记录 CRUD（新 agent 部署/列/停复用）	删 per-deployment 的 logs/metrics/diagnostics/events/artifacts/timeline/sk-snapshots/deployment-draft 子 handler；改 1191/1200/1222 三处去掉 withDisplayStatus 调用；删 agentDeploymentRecord.Mode/display_status 投影
controller/agent_task_bridge.go	resolveResourceBindingIntoGrant（资源绑定→真值解析，新模型拼 env 复用）	normalizeTaskDraftResourceGrants/buildAgentDraftAgentPlan/AgentCreateTaskDeploymentDraft 由"任务 grant"改造为"启动拼 env（非密+解 KV）"
controller/agent_callback.go	回调接收骨架	收缩为只收 agent 生命周期（started/stopped/unhealthy），删 work 事件流/artifact/phase 聚合与 AgentArtifact 写入
router/agent_runtime_http_smoke_test.go	—	引用 tasks/deployments，删路由后编译失败 → 同步删/改

评估 ⚠️

文件	说明
controller/agent_approval.go	审批：新模型审批在 agent↔客户端直接处理。若网页台/其它流程不再需要 → 删；待你确认
controller/agent_role_template.go	角色模板：新模型「模板 agent」可能复用此概念 → 可能保留/改造，不要直接删

---

3. 后端 Model + DB 表/字段（heicode/model/）

删表 🗑️（从 model/main.go 的 AutoMigrate 列表移除 + Migrator().DropTable）

Model / 表	文件	处理
AgentArtifact / agent_artifacts	agent_artifact.go	删（产物记录，旧模型）
AgentArtifactRevision / agent_artifact_revisions	agent_artifact_revision.go	删（含 LatestAcceptedRevisionForDeployment）
AgentCloudDeployment	agent_cloud_deployment.go	删（旧代部署）
AgentSKSnapshot	agent_sk_snapshot.go	⚠️ 评估（SK 快照是否其它处用）
AgentCallbackEvent	agent_callback.go(model)	✂️ 裁剪：若回调收缩，事件表可瘦身或保留生命周期事件

保留并扩展 ✅（修正：不删）

Model / 表	文件	处理
AgentDeployment / agent_deployments	agent_deployment.go	✅ 保留作新 agent 记录的载体：扩字段 subdomain/access_token/binding_ids(JSON)；停写旧任务态字段(SubMode/Phase/PlanJSON/AgentInstancesJSON/PayloadJSON 等，留列不动)。与 model 文档 §4 的 heicode_agent 二选一——建议复用本表，避免删重写。不 DropTable。

model/main.go 改动 ✂️

• 从 294 行起的 AutoMigrate(...) 列表移除：&AgentArtifact{}、&AgentArtifactRevision{}、&AgentCloudDeployment{}（及评估后的 AgentSKSnapshot/AgentDeployment）。
• 396 行起的 idempotent-migrate 列表同步移除对应项。
• ⚠️ 注意保留第 291 行附近的 agnet→agent 改名保数逻辑（历史数据保护，别误删）。

废弃字段（留列只停写，或 DropColumn）✂️

• AgentDeployment 上的：SubMode/Phase/RuntimeState/RuntimeSwarmID/PlanJSON/AgentInstancesJSON/PermissionManifestJSON/PayloadJSON 等任务态字段——若 AgentDeployment 整表保留作它用则停写这些列；整表删则随表去。

---

4. 前端（heicode/web/default/src/）

删路由/页面 🗑️

路径	内容
routes/_authenticated/deployments/index.tsx	部署列表页
routes/_authenticated/tasks/$id.tsx + routes/_authenticated/tasks/	任务详情页
features/agent-console/{api.ts,pages.tsx}	旧任务/部署控制台（AgentDeploymentsPage/RunDetailPanel 等）
features/tasks/task-card-view.tsx	任务卡片视图
features/agent-hub/index.tsx	⚠️ 评估（是否并入新 agent 管理页）
features/models/components/deployments-{columns,table}.tsx	⚠️ 评估（models 页里的 deployments 表，确认是否旧任务）

改 ✂️

• hooks/use-sidebar-data.ts / use-sidebar-config.ts / use-top-nav-links.ts：删「任务/部署」菜单项，加「Agent 管理」入口。
• features/dashboard/components/cockpit/index.tsx：listAgentDeployments 改为新 GET /api/heicode/agents（看板统计用 agent 数）。
• components/layout/components/footer.tsx、config/system-settings.config.ts、lib/heicode-mcp.ts：清掉对 deployments/tasks 的引用链接。
• routeTree.gen.ts：删页面后 bun run build 自动重新生成（勿手改）。

i18n ✂️

• 删 web/default/src/i18n/locales/{zh,en,...}.json 里仅任务/部署/产物页用到的 key（删完跑 bun run i18n:sync 校验，避免悬空 key）。

---

5. 删除顺序（安全推进）

1. 摘路由：注释/删除 §1 的路由注册 → go build 通过（接口立即 404 下线）。
2. 删 controller 整文件 + 裁剪共享文件（§2）→ go build 修引用直到通过。
3. 前端删页面 + 改菜单/看板（§4）→ bun run build（重生成 routeTree）+ tsc -b 清 noUnusedLocals。
4. model 停写 + 移出 AutoMigrate（§3）→ go build + 本地起服务跑 AutoMigrate 不报错。
5. DropTable 旧表（确认数据无用后，单独一步，可灰度）。
6. 全量回归：登录、绑资源、/v1/* 模型调用、（新模型）部署 agent 列表——确认未被误伤。

6. 验证清单

• go build ./... 与现有 *_test.go 通过（删测试同步）。
• bun run build + tsc -b 无错；routeTree.gen.ts 已重生成。
• 启动服务 AutoMigrate 无报错；三库（至少本地 SQLite + 生产 PG）跑通。
• 旧路由返回 404；保留接口（资源 CRUD、/v1/*、/api/user/self）正常。
• 生产部署后 docker image prune -f（CLAUDE.md 约定）。

7. 待你确认（删之前定）

1. 审批 agent_approval.go + /approvals*：新模型是否完全不需要 HM 侧审批？
2. AgentDeployment 表：是直接删，还是先保留作 agent 记录的过渡/迁移到 heicode_agent？
3. agent_role_template.go / AgentSKSnapshot：新模型「模板 agent」是否复用，决定删还是改造。
4. /api/agent/user/deployments* 与 agent_control_plane.go 的共享 handler：网页台/admin 是否还在用，逐个确认再摘。