vault backup: 2026-06-09 23:15:17

2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
@@ -1,36 +1,48 @@
+---
+tags: [task, daemon, status, stop, 状态管理]
+create time: 2026-06-09 22:30
+---
+
 # Task 001: daemon status / stop

-> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 1 项
+## 概述
+
+让 `claude daemon status` 和 `claude daemon stop` 在任意 CLI 进程中都能正确工作，不依赖 TUI 内存态。这是四项 stub 恢复设计中最适合首先实现的项目。
+
+> [!info]
+> 来源: [[claude-code-best/docs/features/stub-recovery-design-1-4]] 第 1 项
 > 优先级: P0 (首选实现项)
 > 工作量: 小
 > 状态: DONE

-## 目标
+## 正文
+
+### 目标

 让 `claude daemon status` 和 `claude daemon stop` 在任意 CLI 进程中都能正确工作，不依赖 TUI 内存态。

-## 背景
+### 背景

 - `start` 路径已有完整 supervisor + worker 生命周期 (`src/daemon/main.ts`, `src/daemon/workerRegistry.ts`)
 - `status` / `stop` 目前只是占位输出 (`src/daemon/main.ts:49`)
 - `/remote-control-server` 有自己的命令内 UI 状态，但只维护当前进程内的 `daemonProcess`，不适合跨进程管理

-## 实现方案
+### 实现方案

-### 新增文件
+#### 新增文件

 | 文件 | 说明 |
 |------|------|
 | `src/daemon/state.ts` | daemon 状态文件读写模块 |

-### 修改文件
+#### 修改文件

 | 文件 | 改动 |
 |------|------|
 | `src/daemon/main.ts` | `start` 写入状态文件；`status`/`stop` 调用 state 模块 |
 | `src/commands/remoteControlServer/remoteControlServer.tsx` | 读取同一份状态文件（轻量改动） |

-### 状态文件
+#### 状态文件

 路径: `~/.claude/daemon/remote-control.json`

@@ -44,14 +56,14 @@
 }
 ```

-### status 逻辑
+#### status 逻辑

 1. 读取状态文件
 2. 用进程探测验证 pid 是否存活
 3. 输出 `running` / `stopped` / `stale`
 4. stale 时自动清理状态文件

-### stop 逻辑
+#### stop 逻辑

 1. 读取 pid
 2. 发送 `SIGTERM`
@@ -59,7 +71,7 @@
 4. 超时后 `SIGKILL`
 5. 清理状态文件

-## 验证步骤
+### 验证步骤

 - [ ] `claude daemon start` 正常启动并写入状态文件
 - [ ] 新开终端执行 `claude daemon status`，显示 `running`
@@ -67,11 +79,16 @@
 - [ ] 再次执行 `claude daemon status`，返回 `stopped` 或 `stale cleaned`
 - [ ] Windows 下 stop 超时兜底正常工作

-## 风险
+### 风险

 - Windows 信号模型和 Unix 不同，`stop` 需要超时兜底
 - 当前设计默认单 supervisor，不处理多实例并发

-## 依赖
+### 依赖

 无外部依赖，可独立实施。
+
+## 关联笔记
+
+- [[claude-code-best/docs/features/stub-recovery-design-1-4]]
+- [[claude-code-best/docs/task/task-002-bg-sessions-ps-logs-kill]]
@@ -1,16 +1,28 @@
+---
+tags: [task, BG_SESSIONS, ps, logs, kill, 会话管理]
+create time: 2026-06-09 22:30
+---
+
 # Task 002: BG_SESSIONS — ps / logs / kill

-> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 2 项
+## 概述
+
+把 `ps` / `logs` / `kill` 做成真正有用的 session 管理命令。不在第一阶段补完 `attach` / `--bg`。
+
+> [!info]
+> 来源: [[claude-code-best/docs/features/stub-recovery-design-1-4]] 第 2 项
 > 优先级: P1
 > 工作量: 中等
 > 状态: DONE
 > 阶段: Phase 2A (MVP)

-## 目标
+## 正文
+
+### 目标

 把 `ps` / `logs` / `kill` 做成真正有用的 session 管理命令。不在第一阶段补完 `attach` / `--bg`。

-## 背景
+### 背景

 - fast-path 已接好 (`src/entrypoints/cli.tsx:218`)
 - session registry 已有真实实现 (`src/utils/concurrentSessions.ts`)
@@ -18,9 +30,9 @@
 - CLI handler 仍全空 (`src/cli/bg.ts`)
 - task summary 仍然是 stub (`src/utils/taskSummary.ts`)

-## 实现方案
+### 实现方案

-### 修改文件
+#### 修改文件

 | 文件 | 改动 |
 |------|------|
@@ -28,53 +40,58 @@
 | `src/utils/concurrentSessions.ts` | 扩展以便后续 attach/--bg 使用 |
 | `src/utils/taskSummary.ts` | 补充基础实现 |

-### 复用模块
+#### 复用模块

 - `src/utils/sessionStorage.ts` — session 存储
 - `src/utils/udsClient.ts` — UDS 通信

-### ps 命令
+#### ps 命令

 - 从 registry 读取 live sessions
 - 展示: pid, kind, sessionId, cwd, name, startedAt, bridgeSessionId
 - 如果有 activity/status，一并展示

-### logs 命令
+#### logs 命令

 - 支持按 `sessionId` / `pid` / `name` 查找
 - 优先复用本地 transcript/log 读取能力
 - 如果 registry 里存在 `logPath`，支持 tail 文件

-### kill 命令
+#### kill 命令

 - 解析目标 session
 - 发退出信号
 - 清理 stale registry

-## 验证步骤
+### 验证步骤

 - [ ] `ps` 能列出当前 live sessions
 - [ ] `logs <sessionId|pid|name>` 能输出对应日志
 - [ ] `kill <sessionId|pid|name>` 能结束目标 session 并清理 registry
 - [ ] 无 live session 时各命令有明确提示

-## Phase 2B (后续)
+### Phase 2B (后续)

 - [ ] 实现 `attach`
 - [ ] 实现 `--bg`
 - [ ] 实现 `taskSummary` 的中途状态更新

-### 为什么拆分
+#### 为什么拆分

 - 现有 registry 记录了 `pid / sessionId / name / logPath`
 - 但没有可靠的 tmux attach target
 - `attach` 和 `--bg` 需要补启动/附着元数据设计，不是简单补 handler

-## 风险
+### 风险

 - `attach` / `--bg` 第二阶段需要 tmux 元数据设计
 - Windows 下 tmux 路径需要明确降级策略

-## 依赖
+### 依赖

 - Task 001 (daemon 状态管理可复用模式，但非硬性依赖)
+
+## 关联笔记
+
+- [[claude-code-best/docs/features/stub-recovery-design-1-4]]
+- [[claude-code-best/docs/task/task-001-daemon-status-stop]]
@@ -1,16 +1,28 @@
+---
+tags: [task, TEMPLATES, job, 模板, MVP]
+create time: 2026-06-09 22:30
+---
+
 # Task 003: TEMPLATES — job 文件系统 MVP

-> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 3 项
+## 概述
+
+把 `new` / `list` / `reply` 做成可用的模板任务系统。第一阶段不碰复杂的自动分类与自动执行。
+
+> [!info]
+> 来源: [[claude-code-best/docs/features/stub-recovery-design-1-4]] 第 3 项
 > 优先级: P2
 > 工作量: 中等
 > 状态: DONE
 > 阶段: MVP

-## 目标
+## 正文
+
+### 目标

 把 `new` / `list` / `reply` 做成可用的模板任务系统。第一阶段不碰复杂的自动分类与自动执行。

-## 背景
+### 背景

 - 命令入口只有 fast-path (`src/entrypoints/cli.tsx:272`)
 - handler 是空的 (`src/cli/handlers/templateJobs.ts`)
@@ -18,70 +30,75 @@
 - `query/stopHooks` 已预留 job classifier 链路 (`src/query/stopHooks.ts:103`)
 - `jobs/classifier.ts` 仍是 stub (`src/jobs/classifier.ts`)

-## 实现方案
+### 实现方案

-### 新增文件
+#### 新增文件

 | 文件 | 说明 |
 |------|------|
 | `src/jobs/state.ts` | job 状态管理 |
 | `src/jobs/templates.ts` | 模板解析与列表 |

-### 修改文件
+#### 修改文件

 | 文件 | 改动 |
 |------|------|
 | `src/cli/handlers/templateJobs.ts` | 实现 `new` / `list` / `reply` handler |

-### 模板来源
+#### 模板来源

 `.claude/templates/*.md`

-### 模板格式
+#### 模板格式

 复用现有 markdown + frontmatter 解析，不另外设计 DSL。

-### list 命令
+#### list 命令

 - 列出所有模板
 - 显示: 模板名, description, 路径

-### new 命令
+#### new 命令

 - 解析模板
 - 在 `~/.claude/jobs/<job-id>/` 下创建 job 目录
 - 写入 `template.md`, `input.txt`, `state.json`
 - 返回 job id 与目录路径

-### reply 命令
+#### reply 命令

 - 将回复写入 `replies.jsonl` 或 `input.txt`
 - 更新 `state.json`

-## 验证步骤
+### 验证步骤

 - [ ] `list` 能列出 `.claude/templates` 下的所有模板
 - [ ] `new <template> [args...]` 能创建 job 目录和状态文件
 - [ ] `reply <job-id> <text>` 能更新 job 内容和状态
 - [ ] frontmatter schema 最小字段集已定义

-## Phase 2 (后续)
+### Phase 2 (后续)

 - [ ] 恢复 `src/jobs/classifier.ts`
 - [ ] 让带 `CLAUDE_JOB_DIR` 的 job session 在 turn 完成后自动更新 `state.json`
 - [ ] 再决定是否补自动 job runner

-### 为什么拆分
+#### 为什么拆分

 - 当前是 "template job commands"，不是单纯模板列表
 - 自动 job 运行链路没有足够现成实现
 - 先做文件系统 job lifecycle 更稳

-## 风险
+### 风险

 - frontmatter schema 需要先定义最小字段集
 - 一旦扩展到"自动运行 job"，范围会明显膨胀

-## 依赖
+### 依赖

 无硬性依赖，可独立实施。
+
+## 关联笔记
+
+- [[claude-code-best/docs/features/stub-recovery-design-1-4]]
+- [[claude-code-best/docs/task/task-015-job-command-hierarchy]]
@@ -1,15 +1,27 @@
+---
+tags: [task, assistant, session, attach, KAIROS]
+create time: 2026-06-09 22:30
+---
+
 # Task 004: assistant [sessionId] — 分阶段恢复

-> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 4 项
+## 概述
+
+不一次性恢复整个 KAIROS 助手系统。先做"明确 sessionId 的 viewer attach 可用"，再逐步补 discovery / chooser / install。
+
+> [!info]
+> 来源: [[claude-code-best/docs/features/stub-recovery-design-1-4]] 第 4 项
 > 优先级: P3
 > 工作量: Phase 4A 中等，4A-4D 全做完很大
 > 状态: Phase 4A DONE, 4B-4D TODO

-## 目标
+## 正文
+
+### 目标

 不一次性恢复整个 KAIROS 助手系统。先做"明确 sessionId 的 viewer attach 可用"，再逐步补 discovery / chooser / install。

-## 背景
+### 背景

 - attach 主流程已存在 (`src/main.tsx:4708`)
 - 远端 viewer 所需基础模块已存在:
@@ -22,9 +34,9 @@
  - `src/commands/assistant/assistant.tsx:7`
  - `src/assistant/index.ts`

-## 分阶段实现
+### 分阶段实现

-### Phase 4A: MVP — 显式 sessionId attach
+#### Phase 4A: MVP — 显式 sessionId attach

 **修改文件:**

@@ -42,7 +54,7 @@
 - [ ] 历史懒加载工作正常
 - [ ] 无参数模式给出明确提示

-### Phase 4B: session discovery
+#### Phase 4B: session discovery

 **修改文件:**

@@ -58,7 +70,7 @@
 - [ ] 无参数调用能列出可用 sessions
 - [ ] 数据来源复用现有通道

-### Phase 4C: session chooser
+#### Phase 4C: session chooser

 **修改文件:**

@@ -73,7 +85,7 @@
 - [ ] 多个 session 时弹出选择器
 - [ ] 选择后正确 attach

-### Phase 4D: install wizard
+#### Phase 4D: install wizard

 **修改文件:**

@@ -87,17 +99,22 @@
 **验证:**
 - [ ] 无可用 session 时引导用户创建/连接

-## 为什么拆分
+### 为什么拆分

 - attach 渲染层与远端消息通道大部分已在
 - 真正缺的是"如何发现目标 session"和"如何交互选择"
 - 如果把 `src/assistant/index.ts` 的整套 KAIROS 正常模式也一起拉进来，范围会失控

-## 风险
+### 风险

 - 这是四项里范围最大的
 - 一旦把 KAIROS 正常模式整体拉入，会从"viewer attach"膨胀成"完整 assistant mode 恢复"

-## 依赖
+### 依赖

 - Task 002 的 session registry 模式可复用
+
+## 关联笔记
+
+- [[claude-code-best/docs/features/stub-recovery-design-1-4]]
+- [[claude-code-best/docs/features/kairos]]
@@ -1,20 +1,32 @@
+---
+tags: [task, BgEngine, 后台引擎, 跨平台, tmux, detached]
+create time: 2026-06-09 22:30
+---
+
 # Task 013: BgEngine 跨平台后台引擎抽象

-> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 四
-> 依赖: 无
-> 分支: `feat/integrate-5-branches`
-
-## 目标
+## 概述

 将 `src/cli/bg.ts` 中硬编码的 tmux 逻辑提取为引擎抽象层，实现 TmuxEngine + DetachedEngine，使后台会话功能在 Windows / macOS / Linux 上都能工作。

-## 背景
+> [!info]
+> 设计文档: [[claude-code-best/docs/features/daemon-restructure-design]] § 四
+> 依赖: 无
+> 分支: `feat/integrate-5-branches`
+
+## 正文
+
+### 目标
+
+将 `src/cli/bg.ts` 中硬编码的 tmux 逻辑提取为引擎抽象层，实现 TmuxEngine + DetachedEngine，使后台会话功能在 Windows / macOS / Linux 上都能工作。
+
+### 背景

 当前 `bg.ts` 中 `handleBgFlag()` 和 `attachHandler()` 直接调用 tmux 命令。Windows 上 `--bg` 直接报错退出。需要一个引擎抽象层，根据平台和可用工具自动选择最佳方案。

-## 文件清单
+### 文件清单

-### 新增
+#### 新增

 | 文件 | 说明 |
 |------|------|
@@ -24,15 +36,15 @@
 | `src/cli/bg/engines/index.ts` | selectEngine() 自动选择 + re-export |
 | `src/cli/bg/tail.ts` | 跨平台日志 tail: fs.watch + 轮询 fallback |

-### 修改
+#### 修改

 | 文件 | 变更 |
 |------|------|
 | `src/cli/bg.ts` | `handleBgFlag()` 改为调用 `selectEngine().start()`；`attachHandler()` 改为调用 `engine.attach()` |

-## 实现方案
+### 实现方案

-### 1. BgEngine 接口 (`src/cli/bg/engine.ts`)
+#### 1. BgEngine 接口 (`src/cli/bg/engine.ts`)

 ```typescript
 export interface BgEngine {
@@ -58,14 +70,14 @@ export interface BgStartResult {
 }
 ```

-### 2. TmuxEngine (`src/cli/bg/engines/tmux.ts`)
+#### 2. TmuxEngine (`src/cli/bg/engines/tmux.ts`)

 从 `bg.ts:handleBgFlag()` 和 `bg.ts:attachHandler()` 提取:
 - `available()`: `execFileNoThrow('tmux', ['-V'])` 返回 code === 0
 - `start()`: `tmux new-session -d -s <name> <cmd>`
 - `attach()`: `tmux attach-session -t <session.tmuxSessionName>`

-### 3. DetachedEngine (`src/cli/bg/engines/detached.ts`)
+#### 3. DetachedEngine (`src/cli/bg/engines/detached.ts`)

 ```typescript
 export class DetachedEngine implements BgEngine {
@@ -101,7 +113,7 @@ export class DetachedEngine implements BgEngine {
 }
 ```

-### 4. 日志 Tail (`src/cli/bg/tail.ts`)
+#### 4. 日志 Tail (`src/cli/bg/tail.ts`)

 ```typescript
 /**
@@ -115,7 +127,7 @@ export class DetachedEngine implements BgEngine {
 export async function tailLog(logPath: string): Promise<void>
 ```

-### 5. 引擎选择 (`src/cli/bg/engines/index.ts`)
+#### 5. 引擎选择 (`src/cli/bg/engines/index.ts`)

 ```typescript
 export async function selectEngine(): Promise<BgEngine> {
@@ -130,9 +142,10 @@ export async function selectEngine(): Promise<BgEngine> {
 }
 ```

-### 6. bg.ts 重构
+#### 6. bg.ts 重构

 `handleBgFlag()` 改名为 `handleBgStart()`，内部逻辑:
+
 ```typescript
 export async function handleBgStart(args: string[]): Promise<void> {
  const engine = await selectEngine()
@@ -155,6 +168,7 @@ export async function handleBgStart(args: string[]): Promise<void> {
 ```

 `attachHandler()` 根据 `session.engine` 字段选择引擎:
+
 ```typescript
 export async function attachHandler(target: string | undefined): Promise<void> {
  // ... 找到 session
@@ -168,7 +182,7 @@ export async function attachHandler(target: string | undefined): Promise<void> {
 }
 ```

-## SessionEntry 扩展
+### SessionEntry 扩展

 `sessions/<PID>.json` 新增 `engine` 字段:

@@ -184,7 +198,7 @@ export async function attachHandler(target: string | undefined): Promise<void> {

 兼容旧格式: 如果 `engine` 字段缺失，检查 `tmuxSessionName` 存在则为 `tmux`，否则为 `detached`。

-## 验证清单
+### 验证清单

 - [ ] Windows: `claude daemon bg` 启动后台会话，无 tmux 依赖
 - [ ] Windows: `claude daemon attach <name>` 以 tail 模式附着，Ctrl+C 退出不杀进程
@@ -194,3 +208,8 @@ export async function attachHandler(target: string | undefined): Promise<void> {
 - [ ] 旧格式 session JSON (无 engine 字段) 兼容
 - [ ] tsc --noEmit 零错误
 - [ ] bun test 通过
+
+## 关联笔记
+
+- [[claude-code-best/docs/task/task-014-daemon-command-hierarchy]]
+- [[claude-code-best/docs/task/task-015-job-command-hierarchy]]
@@ -1,41 +1,53 @@
+---
+tags: [task, daemon, 命令层级化, REPL, CLI]
+create time: 2026-06-09 22:30
+---
+
 # Task 014: /daemon 命令层级化

-> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 三.1
-> 依赖: Task 013 (BgEngine 抽象)
-> 分支: `feat/integrate-5-branches`
-
-## 目标
+## 概述

 将散落的 `daemon start/stop/status` + `ps/logs/attach/kill` + `--bg` 统一收归 `/daemon` 命名空间，实现 CLI + REPL 双注册。

-## 背景
+> [!info]
+> 设计文档: [[claude-code-best/docs/features/daemon-restructure-design]] § 三.1
+> 依赖: Task 013 (BgEngine 抽象)
+> 分支: `feat/integrate-5-branches`
+
+## 正文
+
+### 目标
+
+将散落的 `daemon start/stop/status` + `ps/logs/attach/kill` + `--bg` 统一收归 `/daemon` 命名空间，实现 CLI + REPL 双注册。
+
+### 背景

 当前这些命令注册在两个互不关联的位置:
- `cli.tsx:203-212`: `daemon [start|status|stop]` → `daemon/main.ts`
- `cli.tsx:217-246`: `ps|logs|attach|kill|--bg` → `cli/bg.ts`
+- `cli.tsx:203-212`: `daemon [start|status|stop]` -> `daemon/main.ts`
+- `cli.tsx:217-246`: `ps|logs|attach|kill|--bg` -> `cli/bg.ts`

 需要合并为统一的 `claude daemon <subcommand>` 入口，并新增 REPL `/daemon` 斜杠命令。

-## 文件清单
+### 文件清单

-### 新增
+#### 新增

 | 文件 | 说明 |
 |------|------|
 | `src/commands/daemon/index.ts` | `/daemon` REPL 斜杠命令注册 (type: local-jsx) |
 | `src/commands/daemon/daemon.tsx` | `/daemon` 子命令路由 + status UI 组件 |

-### 修改
+#### 修改

 | 文件 | 变更 |
 |------|------|
 | `src/entrypoints/cli.tsx` | 统一 daemon 快速路径: `daemon <sub>` 路由到对应 handler。旧命令 `ps/logs/attach/kill` 保留但输出 deprecation 警告后代理 |
-| `src/commands.ts` | 注册 `/daemon` 斜杠命令 (feature-gated: DAEMON \|\| BG_SESSIONS) |
+| `src/commands.ts` | 注册 `/daemon` 斜杠命令 (feature-gated: DAEMON || BG_SESSIONS) |
 | `src/daemon/main.ts` | `daemonMain()` 扩展: 支持 `bg/attach/logs/kill/ps` 子命令 (委托给 bg.ts handlers) |

-## 实现方案
+### 实现方案

-### 1. CLI 快速路径统一 (`cli.tsx`)
+#### 1. CLI 快速路径统一 (`cli.tsx`)

 **改前** (两段独立路由):
 ```typescript
@@ -66,7 +78,7 @@ if (
  return
 }

-// --bg 快捷方式 → daemon bg
+// --bg 快捷方式 -> daemon bg
 if (
  feature('BG_SESSIONS') &&
  (args.includes('--bg') || args.includes('--background'))
@@ -79,7 +91,7 @@ if (
  return
 }

-// 向后兼容: ps/logs/attach/kill → daemon <sub> (deprecated)
+// 向后兼容: ps/logs/attach/kill -> daemon <sub> (deprecated)
 if (
  feature('BG_SESSIONS') &&
  ['ps', 'logs', 'attach', 'kill'].includes(args[0] ?? '')
@@ -94,7 +106,7 @@ if (
 }
 ```

-### 2. daemonMain 扩展 (`daemon/main.ts`)
+#### 2. daemonMain 扩展 (`daemon/main.ts`)

 ```typescript
 export async function daemonMain(args: string[]): Promise<void> {
@@ -142,7 +154,7 @@ export async function daemonMain(args: string[]): Promise<void> {
 }
 ```

-### 3. 统一状态面板 (`showUnifiedStatus`)
+#### 3. 统一状态面板 (`showUnifiedStatus`)

 ```typescript
 async function showUnifiedStatus(): Promise<void> {
@@ -169,7 +181,7 @@ async function showUnifiedStatus(): Promise<void> {
 }
 ```

-### 4. REPL 斜杠命令注册
+#### 4. REPL 斜杠命令注册

 **`src/commands/daemon/index.ts`**:
 ```typescript
@@ -237,7 +249,7 @@ const daemonCmd =
 ...(daemonCmd ? [daemonCmd] : []),
 ```

-### 5. 更新 help 文本 (`daemon/main.ts`)
+#### 5. 更新 help 文本 (`daemon/main.ts`)

 ```
 Claude Code Daemon — background process management
@@ -259,7 +271,7 @@ REPL
  /daemon [subcommand]    Same commands available in interactive mode
 ```

-## 验证清单
+### 验证清单

 - [ ] `claude daemon` (无参数) 显示统一状态面板
 - [ ] `claude daemon status` 显示 supervisor + 会话列表
@@ -273,3 +285,9 @@ REPL
 - [ ] REPL 中 `/daemon status` 显示状态信息
 - [ ] tsc --noEmit 零错误
 - [ ] bun test 通过
+
+## 关联笔记
+
+- [[claude-code-best/docs/task/task-013-bg-engine-abstraction]]
+- [[claude-code-best/docs/task/task-015-job-command-hierarchy]]
+- [[claude-code-best/docs/task/task-016-backward-compat-tests]]
@@ -1,34 +1,46 @@
+---
+tags: [task, job, 命令层级化, TEMPLATES, REPL, CLI]
+create time: 2026-06-09 22:30
+---
+
 # Task 015: /job 命令层级化

-> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 三.2
-> 依赖: 无 (可与 Task 013 并行)
-> 分支: `feat/integrate-5-branches`
-
-## 目标
+## 概述

 将 `claude new/list/reply` 收归 `/job` 命名空间，实现 CLI + REPL 双注册。

-## 背景
+> [!info]
+> 设计文档: [[claude-code-best/docs/features/daemon-restructure-design]] § 三.2
+> 依赖: 无 (可与 Task 013 并行)
+> 分支: `feat/integrate-5-branches`
+
+## 正文
+
+### 目标
+
+将 `claude new/list/reply` 收归 `/job` 命名空间，实现 CLI + REPL 双注册。
+
+### 背景

 当前 `new`, `list`, `reply` 是顶级 CLI 命令 (`cli.tsx:250-261`)，容易与其他命令冲突（特别是 `list` 这种通用词）。需要收归 `claude job <subcommand>` 并新增 REPL `/job` 入口。

-## 文件清单
+### 文件清单

-### 新增
+#### 新增

 | 文件 | 说明 |
 |------|------|
 | `src/commands/job/index.ts` | `/job` REPL 斜杠命令注册 |
 | `src/commands/job/job.tsx` | `/job` 子命令路由 |

-### 修改
+#### 修改

 | 文件 | 变更 |
 |------|------|
 | `src/entrypoints/cli.tsx` | 新增 `job` 快速路径 + 旧 `new/list/reply` deprecation 代理 |
 | `src/commands.ts` | 注册 `/job` 斜杠命令 |

-### 不动
+#### 不动

 | 文件 | 说明 |
 |------|------|
@@ -37,9 +49,9 @@
 | `src/jobs/templates.ts` | 模板发现不变 |
 | `src/jobs/classifier.ts` | 任务分类器不变 |

-## 实现方案
+### 实现方案

-### 1. CLI 快速路径 (`cli.tsx`)
+#### 1. CLI 快速路径 (`cli.tsx`)

 **改后**:
 ```typescript
@@ -67,7 +79,7 @@ if (
 }
 ```

-### 2. templateJobs.ts 新增 status 子命令
+#### 2. templateJobs.ts 新增 status 子命令

 在现有 `switch` 中增加:
 ```typescript
@@ -98,7 +110,7 @@ function handleStatus(args: string[]): void {
 }
 ```

-### 3. REPL 斜杠命令
+#### 3. REPL 斜杠命令

 **`src/commands/job/index.ts`**:
 ```typescript
@@ -152,7 +164,7 @@ export async function call(
 }
 ```

-### 4. commands.ts 注册
+#### 4. commands.ts 注册

 ```typescript
 const jobCmd = feature('TEMPLATES')
@@ -163,7 +175,7 @@ const jobCmd = feature('TEMPLATES')
 ...(jobCmd ? [jobCmd] : []),
 ```

-## 验证清单
+### 验证清单

 - [ ] `claude job list` 列出模板
 - [ ] `claude job new <template>` 创建任务
@@ -175,3 +187,9 @@ const jobCmd = feature('TEMPLATES')
 - [ ] REPL 中 `/job list` 显示模板列表
 - [ ] tsc --noEmit 零错误
 - [ ] bun test 通过
+
+## 关联笔记
+
+- [[claude-code-best/docs/task/task-003-templates-job-mvp]]
+- [[claude-code-best/docs/task/task-014-daemon-command-hierarchy]]
+- [[claude-code-best/docs/task/task-016-backward-compat-tests]]
@@ -1,16 +1,28 @@
+---
+tags: [task, 向后兼容, 测试, deprecation, 重构]
+create time: 2026-06-09 22:30
+---
+
 # Task 016: 向后兼容 + 测试

-> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 五
-> 依赖: Task 014, Task 015
-> 分支: `feat/integrate-5-branches`
-
-## 目标
+## 概述

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

-## 文件清单
+> [!info]
+> 设计文档: [[claude-code-best/docs/features/daemon-restructure-design]] § 五
+> 依赖: Task 014, Task 015
+> 分支: `feat/integrate-5-branches`

-### 新增
+## 正文
+
+### 目标
+
+确保旧命令向后兼容 (deprecation 警告 + 正常代理)，并为重构后的命令结构编写测试。
+
+### 文件清单
+
+#### 新增

 | 文件 | 说明 |
 |------|------|
@@ -19,15 +31,15 @@
 | `src/cli/bg/__tests__/detached.test.ts` | DetachedEngine 启动/停止测试 |
 | `src/cli/bg/__tests__/tail.test.ts` | 日志 tail 功能测试 |

-### 修改
+#### 修改

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

-## 实现方案
+### 实现方案

-### 1. 向后兼容矩阵
+#### 1. 向后兼容矩阵

 | 旧命令 | 新命令 | 处理方式 |
 |--------|--------|---------|
@@ -40,11 +52,12 @@
 | `claude list` | `claude job list` | stderr deprecation + 执行 |
 | `claude reply <id>` | `claude job reply <id>` | stderr deprecation + 执行 |

-**关键**: deprecation 输出到 stderr 而非 stdout，不影响脚本管道。
+> [!tip]
+> **关键**: deprecation 输出到 stderr 而非 stdout，不影响脚本管道。

-### 2. 测试计划
+#### 2. 测试计划

-#### 2.1 daemonMain 路由测试
+##### 2.1 daemonMain 路由测试

 ```typescript
 describe('daemonMain', () => {
@@ -59,7 +72,7 @@ describe('daemonMain', () => {
 })
 ```

-#### 2.2 引擎选择测试
+##### 2.2 引擎选择测试

 ```typescript
 describe('selectEngine', () => {
@@ -70,7 +83,7 @@ describe('selectEngine', () => {
 })
 ```

-#### 2.3 DetachedEngine 测试
+##### 2.3 DetachedEngine 测试

 ```typescript
 describe('DetachedEngine', () => {
@@ -80,7 +93,7 @@ describe('DetachedEngine', () => {
 })
 ```

-#### 2.4 Tail 测试
+##### 2.4 Tail 测试

 ```typescript
 describe('tailLog', () => {
@@ -90,7 +103,7 @@ describe('tailLog', () => {
 })
 ```

-### 3. 集成验证脚本
+#### 3. 集成验证脚本

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

@@ -113,7 +126,7 @@ echo "=== 5. claude list (deprecated) ==="
 bun run dev -- list 2>&1 | head -1
 ```

-## 验证清单
+### 验证清单

 - [ ] 旧命令全部正常工作 (仅多一行 stderr 警告)
 - [ ] `--bg` 保持无警告
@@ -121,3 +134,8 @@ bun run dev -- list 2>&1 | head -1
 - [ ] 现有 2695 个测试无回归
 - [ ] tsc --noEmit 零错误
 - [ ] 手动在 Windows + macOS/Linux 上验证关键路径
+
+## 关联笔记
+
+- [[claude-code-best/docs/task/task-014-daemon-command-hierarchy]]
+- [[claude-code-best/docs/task/task-015-job-command-hierarchy]]