claude-code/docs/task/task-016-backward-compat-tests.md

Task 016: 向后兼容 + 测试

设计文档: daemon-restructure-design.md § 五 依赖: Task 014, Task 015 分支: feat/integrate-5-branches

目标

确保旧命令向后兼容 (deprecation 警告 + 正常代理)，并为重构后的命令结构编写测试。

文件清单

新增

文件	说明
src/daemon/__tests__/daemonMain.test.ts	daemonMain 子命令路由测试
src/cli/bg/__tests__/engine.test.ts	BgEngine 选择逻辑测试
src/cli/bg/__tests__/detached.test.ts	DetachedEngine 启动/停止测试
src/cli/bg/__tests__/tail.test.ts	日志 tail 功能测试

修改

文件	变更
src/entrypoints/cli.tsx	确认 deprecation 路径正确代理

实现方案

1. 向后兼容矩阵

旧命令	新命令	处理方式
claude ps	claude daemon status	stderr 输出 [deprecated] Use: claude daemon status，然后执行
claude logs <x>	claude daemon logs <x>	同上
claude attach <x>	claude daemon attach <x>	同上
claude kill <x>	claude daemon kill <x>	同上
claude --bg	claude daemon bg	保留为快捷方式，不 deprecate (太常用)
claude new <t>	claude job new <t>	stderr deprecation + 执行
claude list	claude job list	stderr deprecation + 执行
claude reply <id>	claude job reply <id>	stderr deprecation + 执行

关键: deprecation 输出到 stderr 而非 stdout，不影响脚本管道。

2. 测试计划

2.1 daemonMain 路由测试

describe('daemonMain', () => {
  test('无参数默认 status', async () => { ... })
  test('start 调用 runSupervisor', async () => { ... })
  test('stop 调用 handleDaemonStop', async () => { ... })
  test('bg 委托给 bg.handleBgStart', async () => { ... })
  test('attach 委托给 bg.attachHandler', async () => { ... })
  test('logs 委托给 bg.logsHandler', async () => { ... })
  test('kill 委托给 bg.killHandler', async () => { ... })
  test('未知子命令设置 exitCode=1', async () => { ... })
})

2.2 引擎选择测试

describe('selectEngine', () => {
  test('win32 返回 DetachedEngine', async () => { ... })
  test('darwin + tmux 可用返回 TmuxEngine', async () => { ... })
  test('darwin + tmux 不可用返回 DetachedEngine', async () => { ... })
  test('linux + tmux 可用返回 TmuxEngine', async () => { ... })
})

2.3 DetachedEngine 测试

describe('DetachedEngine', () => {
  test('available 始终返回 true', async () => { ... })
  test('start 创建 detached 子进程并写入日志', async () => { ... })
  test('start 返回的 PID 文件存在', async () => { ... })
})

2.4 Tail 测试

describe('tailLog', () => {
  test('输出已有日志内容', async () => { ... })
  test('追加内容时实时输出', async () => { ... })
  test('SIGINT 退出 tail', async () => { ... })
})

3. 集成验证脚本

可选: 在 scripts/ 下添加一个手动验证脚本:

#!/bin/bash
# scripts/verify-daemon-restructure.sh
echo "=== 1. claude daemon status ==="
bun run dev -- daemon status

echo "=== 2. claude daemon bg (should start) ==="
bun run dev -- daemon bg --help

echo "=== 3. claude ps (deprecated) ==="
bun run dev -- ps 2>&1 | head -1

echo "=== 4. claude job list ==="
bun run dev -- job list

echo "=== 5. claude list (deprecated) ==="
bun run dev -- list 2>&1 | head -1

验证清单

• 旧命令全部正常工作 (仅多一行 stderr 警告)
• --bg 保持无警告
• 所有新增测试通过
• 现有 2695 个测试无回归
• tsc --noEmit 零错误
• 手动在 Windows + macOS/Linux 上验证关键路径