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

claude-code-best/docs/task/task-013-bg-engine-abstraction.md

@@ -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]]