docs(integration): legacy teardown checklist for old sub task-orchestration

Concrete deletion plan for the old sub task model now that sub uses the
template-agent + direct-connect model. Maps real code surface (verified against
the repo) into delete / trim / evaluate buckets:

- routes (registerHeicodeTaskRoutes, deployment-targets, old user/deployments)
- controllers (heicode_task_create/client_routes/project_artifacts/artifact_edits/
  cloud_deploy delete; agent_runtime_client/task_bridge/callback/control_plane trim)
- models + DB tables/columns (AgentArtifact/Revision/CloudDeployment drop;
  AgentDeployment/SKSnapshot/CallbackEvent evaluate) with GORM/cross-DB drop notes
- frontend pages/routes/sidebar/i18n
- ordered teardown steps + verification + open questions to confirm before deleting

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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

@@ -0,0 +1,129 @@
+# Heicode Manager 旧 Sub 任务编排模型 — 删除清单（Teardown）
+
+> 更新时间：2026-06-03
+> 背景：sub 模式已切到「模板 agent + 客户端直连」新模型（见 `heicode-hm-template-agent-model.md`）。
+> 本文列出**要删除的旧代码 / 旧逻辑 / 旧数据 / 旧 DB 表与字段 / 旧前端**，并标注共享/有依赖、需评估的部分。
+> 图例：🗑️ **删整块** ·  ✂️ **改/裁剪保留** ·  ⚠️ **评估/待确认（有共享或外部依赖）**
+
+---
+
+## 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 行） | 旧客户端部署控制面（logs/metrics/events/artifacts/timeline/sk-snapshots/deployment-draft）。新模型客户端不经 HM 看任务 → **建议删**；确认无网页台依赖后摘除 |
+| ✂️ | `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` 等针对上述逻辑的测试 |
+
+**裁剪保留 ✂️**
+
+| 文件 | 改动 |
+|---|---|
+| `controller/agent_runtime_client.go` | 删 `withDisplayStatus` 裁决逻辑、`heicodeClientMode`、display_status 相关；**保留** runtime 配置/健康探测、并新增 ListTemplates/StartAgent/StopAgent（新模型用） |
+| `controller/agent_task_bridge.go` | `resolveResourceBindingIntoGrant`/`normalizeTaskDraftResourceGrants` 由"任务注入 grant"**改造**为"agent 启动拼 env（非密 + 解 KV 密钥）" |
+| `controller/agent_callback.go` | `AgentReceiveRuntimeEventCallback` 收缩为**只收 agent 生命周期/状态**（started/stopped/unhealthy），删 work 事件流/artifact/phase 聚合 |
+| `controller/agent_control_plane.go` | 删 `HeicodeCreateDeployment`/`HeicodeListDeployments` 引用、`agentDeploymentRecord.Mode`、display_status 投影；评估 `AgentListUserDeployments`/`AgentGetUserDeployment` 是否仍被网页台/admin 用（⚠️ 共享，逐个确认） |
+
+**评估 ⚠️**
+
+| 文件 | 说明 |
+|---|---|
+| `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) | ✂️ 裁剪：若回调收缩，事件表可瘦身或保留生命周期事件 |
+| `AgentDeployment` / `agent_deployments` | `agent_deployment.go` | ⚠️ **核心旧表**：被新 `heicode_agent` 取代。删之前确认 `correlation_id` 等无外部依赖；可先停写、数据迁移后再 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 是否还在用，逐个确认再摘。