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 是否还在用，逐个确认再摘。