# Proposal C1: 用 codemod 一次性删除 AppDatabase 80+ legacy pass-through

> 来源：问题.md C1（行 114-127）、附录 F 样本 5（行 495-507）、附录 C（行 390-391）
> 状态：proposed（可与 B2 共享 migration 窗口）
> 提出：Roundtable 2026-04-20（Linus + Karpathy + Steve Jobs）
> Owner: TBD
> 估计工时：1 周（含 codemod 脚本 + 逐个 PR 验证）
> Blocking dependencies：无强依赖，但建议 B2 完成后再做（B2 会修改 tasks 模块 API）

## 问题陈述

数据库访问层有两层 pass-through：

**第一层**：`src/main/database-base.ts` 的 `AppDatabaseBase` 持有 26 个领域模块（`threads` / `company` / `agents` / `tasks` / `runs` / ...），在 226-336 行为这些模块的 80+ 方法手写薄委托。

**第二层**：`src/main/database.ts` 的 `AppDatabase`（`AppDatabaseBase` 的子类），在 13-192 行又手写一层更薄的委托，例如：

```ts
// src/main/database.ts:13-23
listComments(taskId: string) { return this.activityMod.listComments(taskId); }
sendAgentMessage(input: {...}) { return this.messages.sendAgentMessage(input); }
// 共计 192 行，几乎全是这种 one-liner
```

作者在 `database-base.ts:49-51` 自己承认：

> "Domain modules. New code should prefer `db.tasks.saveTask(...)` over the legacy pass-through methods on AppDatabase. Pass-through remains for back-compat until all call sites migrate."

没有迁移计划，没有 deadline，没有 ESLint rule 禁止新代码走 pass-through。

## 根因分析

Linus 视角（好品味原则第六条：代码是否可读）：**两层委托是认知税**。

读代码路径：`caller → AppDatabase.saveTask → AppDatabaseBase.saveTask → tasks.saveTask → SQL`。每一层都没有任何增值逻辑，纯粹的字符串转发。这是典型的"架构师幻觉"——觉得加一层抽象就是解耦，实际是把同一个事情说三遍。

**真正的解耦**是：call site 和 SQL 之间存在一层做 validation / caching / observability 的东西。当前架构里那一层是空的。

Karpathy 视角补充：AI coding agent 读这个 codebase 时，每次想保存 task 都看到三个等价的 API（`db.saveTask` / `db.saveTask` 继承 / `db.tasks.saveTask`），完全不知道该用哪个。这种 ambiguity 会让 agent 每次选得不一样，导致代码风格 drift——"我之前写过 db.saveTask，这次也写这个" vs "我之前写过 db.tasks.saveTask，这次也写这个"——最后仓库里三种风格并存，review 成本陡增。

根本问题：**"back-compat until all call sites migrate" 没有触发条件**。谁来触发？触发日期？指标？——都没有。所以它就是永远存在。

## 设计方案

### 目标最终形态

```ts
// src/main/database.ts（重写后 ~30 行）
export class AppDatabase extends AppDatabaseBase {
  // 保留只有 AppDatabase 才有的逻辑（如果有）
  // 没有任何 pass-through
}

// src/main/database-base.ts（删除 226-336 的 pass-through 段落）
export class AppDatabaseBase {
  public readonly threads: ThreadsModule;
  public readonly company: CompanyModule;
  public readonly agents: AgentsModule;
  // ... 26 个模块
  // 没有 pass-through 方法
}
```

### 所有 call site 强制走命名空间

```ts
// Before
db.saveTask(task)
db.listComments(taskId)
db.sendAgentMessage(input)

// After
db.tasks.saveTask(task)
db.activity.listComments(taskId)
db.messages.sendAgentMessage(input)
```

### Codemod 脚本

新建 `scripts/codemod/remove-appdatabase-passthrough.mjs`：

1. 构建方法名 → 模块名的映射表（从 `database-base.ts:226-336` 和 `database.ts:13-192` 逆向抽取）。例如：
   ```
   saveTask → tasks.saveTask
   listTasks → tasks.listTasks
   sendAgentMessage → messages.sendAgentMessage
   listComments → activity.listComments
   … (~80 条)
   ```
2. 用 ts-morph 或 jscodeshift 扫 `src/` 和 `tests/`，匹配 `db.<method>(...)`，替换为 `db.<module>.<method>(...)`。
3. 对每次替换做 typecheck 验证：`pnpm typecheck` 必须通过。
4. 产出 migration report（每个文件改了几处）。

### ESLint rule 锁死

新规则：`no-appdatabase-passthrough`——禁止在类型为 `AppDatabase` 的对象上调用领域方法（只允许访问 `db.tasks` / `db.agents` 等 getter）。

## Migration 计划

1. **Step 1（1 天）**：写 codemod 脚本 + dry-run 出 report，评估影响面（预计 500-800 处 call site）。
2. **Step 2（2 天）**：按模块分批跑 codemod，每个模块一个 PR：
   - `db.threads.*` 一个 PR
   - `db.tasks.*` 一个 PR
   - `db.messages.*` 一个 PR
   - ...
   每个 PR 跑 typecheck + 相关 unit/integration test。
3. **Step 3（1 天）**：所有 call site 迁移完后，删 `database-base.ts:226-336` 的 pass-through 段落 + 删 `database.ts:13-192`。
4. **Step 4（半天）**：合并 `AppDatabase` 到 `AppDatabaseBase`，改名为 `AppDatabase`。删除无用的继承层。
5. **Step 5（半天）**：打开 ESLint rule，新 PR 无法再走 pass-through。

不需要 schema migration——这是纯代码结构重构，二进制行为零变化。

## 风险与回滚

| 风险 | 触发条件 | 回滚方法 |
|------|---------|---------|
| Codemod 误改 | 动态 property access `db[name]` | codemod 检测到 computed access 时跳过并 warn |
| Typecheck 通过但 runtime 错 | 模块 getter 返回 undefined | `AppDatabaseBase` constructor 里逐个 assert 模块已 init |
| 测试 mock 失效 | 测试 stub 了 `db.saveTask` | 测试改为 stub `db.tasks.saveTask`——codemod 同时处理 |
| 第三方 plugin 依赖 | builtin-skills 或外部代码调 `db.saveTask` | 当前没有第三方 plugin 路径，如发现再加 deprecation proxy |

**回滚路径**：任何 step PR 可单独 revert。final cleanup（step 3-4）前代码层面保持 dual API，任何时候都可暂停。

## 验证标准

1. **Typecheck 通过**：每个 codemod PR + final cleanup PR
2. **所有测试绿**：typecheck / unit / integration / e2e
3. **静态扫描**：最终 `grep -rn "db\.saveTask\|db\.listTasks\|…" src/` 应无命中（除了 `db.tasks.saveTask` 这种合法 namespaced 调用）
4. **ESLint CI 门禁**：新 PR 引入 pass-through 风格被 CI 拒绝
5. **Line count**：`database.ts` 从 192 行 → ≤30 行；`database-base.ts` 从 472 行 → ≤200 行

## 不在范围

- **不重构领域模块内部 API**：只是把 pass-through 删掉，模块内部实现不动。
- **不改 IPC 接口**：renderer 看到的还是相同 shape。
- **不引入 ORM**：SQLite 直接 prepare + run 的风格保留。
- **不做 query builder**：领域模块内部写 SQL 的方式不变。
- **不拆分领域模块到独立文件**：已经在 `src/main/database/` 子目录了，不动。

## 参考文件清单

- `src/main/database.ts:13-192`（第二层 pass-through，待删除）
- `src/main/database-base.ts:40-472`（域模块装配 + 第一层 pass-through）
- `src/main/database-base.ts:49-51`（作者自白注释）
- `src/main/database-base.ts:226-336`（80+ pass-through 方法段）
- `src/main/database/*`（26 个域模块，API 不变）
- `src/renderer/**/*.ts`（主要 call site 消费方）
- `src/main/ipc-*.ts`（IPC handler call site）

## 附：为什么现在修

**broken-window 效应**：只要注释写着"pass-through remains for back-compat"且没有 deadline，新代码就会继续加新的 pass-through。当前 80+ 方法是一天的 codemod，拖到 150+ 就是一周，拖到 300+ 就没人敢动了。

Linus 原话精神：当你发现自己写注释"我知道这很糟但是…"的时候，你就已经在积累技术债。技术债不会自己消失，只会复利。

C1 和 B2 可以共享 migration 窗口——B2 要改 tasks 的状态机 API，codemod 正好顺带把 `db.saveTask → db.tasks.saveTask` 处理掉，两件事一起做比先后做省一半 PR review 工夫。

C1 改完后代码的可读性/可教性明显提升，这个直接影响 AI coding agent 的产出质量——agent 不再在"三个等价 API 选哪个"上浪费 token 和时间。

## 附：codemod 脚本草稿

```js
// scripts/codemod/remove-appdatabase-passthrough.mjs
import { Project, SyntaxKind } from "ts-morph";

const PASSTHROUGH_MAP = {
  // 从 database.ts:13-192 和 database-base.ts:226-336 抽取
  saveTask: "tasks",
  listTasks: "tasks",
  deleteTask: "tasks",
  saveAgent: "agents",
  listAgents: "agents",
  sendAgentMessage: "messages",
  listComments: "activity",
  // ... ~80 条
};

const project = new Project({ tsConfigFilePath: "tsconfig.json" });
const sourceFiles = project.getSourceFiles(["src/**/*.ts", "tests/**/*.ts"]);

for (const sf of sourceFiles) {
  const calls = sf.getDescendantsOfKind(SyntaxKind.CallExpression);
  for (const call of calls) {
    const expr = call.getExpression();
    if (expr.getKind() !== SyntaxKind.PropertyAccessExpression) continue;
    const prop = expr.asKindOrThrow(SyntaxKind.PropertyAccessExpression);
    const obj = prop.getExpression().getText();
    const method = prop.getName();

    // 只改 db.xxx(...) 形式
    if (obj === "db" && method in PASSTHROUGH_MAP) {
      const module = PASSTHROUGH_MAP[method];
      prop.setExpression(`${obj}.${module}`);
    }
  }
}

await project.save();
```

## 附：gating matrix

| Gate | 条件 | 放行判断人 |
|------|------|----------|
| G1 | Codemod dry-run report 显示预期影响面（500-800 call sites） | Linus |
| G2 | 每个模块的迁移 PR 单独跑 typecheck + unit test 绿 | Owner |
| G3 | 所有模块迁完后 `grep -rn 'db\.saveTask\|db\.listTasks' src/` 无命中 | Linus |
| G4 | `database.ts` 行数 < 30 | Linus |
| G5 | ESLint rule `no-appdatabase-passthrough` 启用，CI 捕获新违规 | Owner |

## 附：call site 分布（预估）

基于 grep：
- `src/main/ipc-*.ts`：~200 处
- `src/main/orchestration/`：~100 处
- `src/main/worker/`：~50 处
- `src/main/agent-runtime/`：~80 处
- `src/renderer/`：~0 处（renderer 通过 IPC，不直接访问 db）
- `tests/`：~100 处

总计 ~530 处。codemod 一次性全改，分批 PR 按文件提交。

## 附：与 B2 的协同

B2 的 phase/lease 重构需要改 `src/main/database/tasks-status.ts` 的 API。codemod 可同时处理两件事：
1. 把 `db.saveTask → db.tasks.saveTask`（C1）
2. 把 `db.tasks.saveTask → db.tasks.advanceTaskPhase`（B2 的新 API）

一个 PR 两件事。节约 review 一次成本。

## 附：为什么不选其他方案

**方案 A（当前 proposal）**：一次性 codemod 迁移。优点：彻底；缺点：一次大 PR。

**方案 B（渐进式，新代码用新 API，旧代码原样）**：broken-window 加剧，永远迁不完（过去两年证明了）。

**方案 C（只删 database.ts 的第二层，保留 database-base.ts 的第一层）**：治标不治本，仍有 pass-through 层。

方案 A 是**真的解决问题**的方案。

## 附：PR 拆分策略

按"同一领域的 call site 一批 PR"拆分：

| PR | 迁移范围 | 预计大小 | 评估 |
|----|---------|---------|-----|
| PR-1 | `db.tasks.*` 迁移 | ~150 处 | 跟 B2 合并最省力 |
| PR-2 | `db.agents.*` 迁移 | ~80 处 | 独立 |
| PR-3 | `db.messages.*` 迁移 | ~70 处 | 独立 |
| PR-4 | `db.approvals.*` 迁移 | ~60 处 | 独立 |
| PR-5 | `db.runs.*` 迁移 | ~50 处 | 独立 |
| PR-6 | 其他 21 个模块分 5 批 | ~170 处 | 独立 |
| PR-7 | Final cleanup（删 database.ts pass-through） | - | 所有前置完成后 |

每个 PR 单独跑 typecheck + 相关单测，review 一次 < 1 小时。

## 附：自动 import 优化

Codemod 跑完后，同 file 内如果 `db.tasks.*` 多处调用，可以抽成本地 alias：

```ts
const { tasks } = db;
tasks.saveTask(t);
tasks.listTasks();
```

但这是 optional 优化，由 reviewer 决定是否采纳。