# 笔临 P2.1 + P3 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 交付 v0.3.0：P2 遗留（章节拖拽、搜索替换、灵感模态+语音、@跳转、引用钉住）+ P3 严格（LM Studio 对话、上下文注入、快捷命令、离线降级、命名检查、AI 快照）。

**Architecture:** 延续 electron-vite 单体；主进程 schema v3 + `AiClientService`（OpenAI 兼容 `fetch` 至 LM Studio）+ 流式 IPC 事件；渲染进程 `AiPanel` 替换占位；测试 **禁止 Mock**，集成/E2E 必须打真实 `http://127.0.0.1:1234`。

**Tech Stack:** Electron 36、electron-vite、React 18、TypeScript、TipTap、node:sqlite、Zustand、Jotai、i18next、Vitest、Playwright

**Spec:** `docs/superpowers/specs/2026-07-07-bilin-p21-p3-design.md`

**LM Studio 默认：** `baseUrl=http://127.0.0.1:1234`，`model=gemma-4-e4b-it`（可用 `BILIN_AI_BASE_URL` / `BILIN_AI_MODEL` 覆盖）

---

## File Map

| 文件 | 职责 |
|------|------|
| `src/main/db/schema-v3.sql` | `ai_sessions` / `ai_messages` |
| `src/main/db/migrate.ts` | v2→v3 迁移 |
| `src/main/db/repositories/chapter.repo.ts` | `move()` |
| `src/main/db/repositories/ai-session.repo.ts` | 会话/消息 CRUD |
| `src/main/services/ai-client.service.ts` | LM Studio HTTP + SSE 流 |
| `src/main/services/ai-context-builder.service.ts` | 上下文拼接 |
| `src/main/services/network-monitor.service.ts` | online/offline 推送 |
| `src/main/ipc/handlers/ai.handler.ts` | AI IPC + 流式 |
| `src/main/ipc/handlers/chapter.handler.ts` | `chapter:move` |
| `src/shared/types.ts` | AiConfig / AiSession / NamingConflict |
| `src/shared/ipc-channels.ts` | P2.1/P3 IPC |
| `src/preload/index.ts` | AI API + 事件订阅 |
| `src/renderer/stores/useAiStore.ts` | 会话/流式/disabled |
| `src/renderer/components/ai/AiPanel.tsx` | 右栏 AI 主 UI |
| `src/renderer/components/ai/ContextEditorModal.tsx` | 上下文勾选 |
| `src/renderer/components/ai/NamingCheckModal.tsx` | 命名检查 |
| `src/renderer/components/inspiration/InspirationModal.tsx` | 灵感捕获 |
| `src/renderer/components/settings/AiSettingsPage.tsx` | AI 配置 Tab |
| `src/renderer/components/search/SearchModal.tsx` | 替换区 |
| `src/renderer/components/layout/EditorLayout.tsx` | 章节 drag |
| `e2e/p21-features.spec.ts` | P2.1 E2E |
| `e2e/ai-chat.spec.ts` | P3 对话 E2E |

---

## Task 1: 章节拖拽（P2.1a）

**Files:**
- Modify: `src/main/db/repositories/chapter.repo.ts`
- Modify: `src/main/ipc/handlers/chapter.handler.ts`
- Modify: `src/shared/ipc-channels.ts`
- Modify: `src/preload/index.ts`, `src/shared/electron-api.d.ts`
- Modify: `src/renderer/components/layout/EditorLayout.tsx`
- Modify: `src/renderer/styles/layout.css`
- Create: `tests/main/chapter-move.test.ts`
- Create: `e2e/p21-features.spec.ts`（DRAG 用例）

- [ ] **Step 1: 写 chapter.move 失败测试**

`tests/main/chapter-move.test.ts`：

```typescript
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
import { DatabaseSync } from 'node:sqlite'
import { migrate } from '../../src/main/db/migrate'
import { ChapterRepository } from '../../src/main/db/repositories/chapter.repo'
import { VolumeRepository } from '../../src/main/db/repositories/volume.repo'
import type { SqliteDb } from '../../src/main/db/types'

describe('ChapterRepository.move', () => {
  let db: SqliteDb
  let chapters: ChapterRepository
  let volId: string

  beforeEach(() => {
    db = new DatabaseSync(':memory:')
    migrate(db)
    const vols = new VolumeRepository(db)
    volId = vols.create('卷一', 0).id
    chapters = new ChapterRepository(db)
    chapters.create(volId, 'A', 0)
    chapters.create(volId, 'B', 1)
    chapters.create(volId, 'C', 2)
  })

  afterEach(() => db.close())

  it('reorders within volume', () => {
    const list = chapters.listByVolume(volId)
    const idC = list.find((x) => x.title === 'C')!.id
    chapters.move(idC, volId, 0)
    chapters.reorderVolume(volId, [idC, list.find((x) => x.title === 'A')!.id, list.find((x) => x.title === 'B')!.id])
    const titles = chapters.listByVolume(volId).map((x) => x.title)
    expect(titles).toEqual(['C', 'A', 'B'])
  })
})
```

- [ ] **Step 2: 运行确认 FAIL**

```bash
npm run test -- tests/main/chapter-move.test.ts
```

Expected: FAIL `chapters.move is not a function`

- [ ] **Step 3: 实现 `ChapterRepository.move`**

```typescript
move(chapterId: string, volumeId: string, sortOrder: number): Chapter {
  this.db
    .prepare(
      `UPDATE chapters SET volume_id = ?, sort_order = ?, updated_at = datetime('now') WHERE id = ?`
    )
    .run(volumeId, sortOrder, chapterId)
  return this.get(chapterId)!
}

reorderVolume(volumeId: string, orderedIds: string[]): void {
  const stmt = this.db.prepare(
    `UPDATE chapters SET sort_order = ? WHERE id = ? AND volume_id = ?`
  )
  orderedIds.forEach((id, idx) => stmt.run(idx, id, volumeId))
}
```

- [ ] **Step 4: IPC `CHAPTER_MOVE`**

`ipc-channels.ts` 追加 `CHAPTER_MOVE: 'chapter:move'`。

`chapter.handler.ts`：

```typescript
ipcMain.handle(
  IPC.CHAPTER_MOVE,
  (_e, { bookId, chapterId, volumeId, sortOrder }: { bookId: string; chapterId: string; volumeId: string; sortOrder: number }) =>
    wrap(() => registry.getChapterRepo(bookId).move(chapterId, volumeId, sortOrder))
)
```

preload / electron-api.d.ts 暴露 `chapter.move(bookId, chapterId, volumeId, sortOrder)`。

- [ ] **Step 5: EditorLayout 拖拽 UI**

章节 `.chapter-item` 增加 `draggable`；`onDragStart` 设 `chapterId`；`onDragOver` preventDefault；`onDrop` 计算新 `sortOrder` 调 IPC。

同卷：根据 drop 目标 index 调用 `reorderVolume`（新增 IPC `chapter:reorder` 或在 move 后批量 reorder）。

跨卷：drop 到另一卷 header → `move(chapterId, targetVolId, targetLen)`。

- [ ] **Step 6: E2E E2E-P21-DRAG-01**

`e2e/p21-features.spec.ts`：两章 → drag 交换顺序 → 重启 → 顺序保持。

- [ ] **Step 7: 验证**

```bash
npm run test -- tests/main/chapter-move.test.ts
npm run build
npm run test:e2e -- e2e/p21-features.spec.ts
```

- [ ] **Step 8: Commit**

```bash
git commit -am "feat: add chapter drag reorder within and across volumes"
```

---

## Task 2: 搜索替换 UI（P2.1b）

**Files:**
- Modify: `src/renderer/components/search/SearchModal.tsx`
- Modify: `src/renderer/styles/layout.css`
- Modify: `public/locales/zh-CN/translation.json`, `public/locales/en/translation.json`
- Extend: `e2e/p21-features.spec.ts`

- [ ] **Step 1: SearchModal 替换折叠区**

在 `search-results` 下方增加：

```tsx
<details className="search-replace-panel" data-testid="search-replace-panel">
  <summary>{t('search.replace')}</summary>
  <input data-testid="search-replace-input" value={replacement} onChange={...} />
  <button data-testid="search-replace-preview" onClick={() => void previewReplace()}>
    {t('search.replacePreview')}
  </button>
  <button data-testid="search-replace-execute" onClick={() => void executeReplace()}>
    {t('search.replaceExecute')}
  </button>
</details>
```

`previewReplace`：

```typescript
const result = await ipcCall(() =>
  window.electronAPI.search.replace(bookId, query, replacement, true, { regex, caseSensitive })
)
setReplacePreviews(result.previews)
```

`executeReplace`：`dryRun: false` → `refreshChapters()` + toast。

- [ ] **Step 2: i18n 键**

`search.replace`, `search.replacePreview`, `search.replaceExecute`, `search.replaceConfirm`, `search.replaceDone`

- [ ] **Step 3: E2E E2E-P21-REP-01**

写入章节唯一词 → 搜索 → 预览 → 执行 → `editor` 含新词。

- [ ] **Step 4: 验证 + Commit**

```bash
npm run test:e2e -- e2e/p21-features.spec.ts
git commit -am "feat: add global search replace preview and execute UI"
```

---

## Task 3: 灵感模态 + @跳转 + 引用钉住（P2.1c）

**Files:**
- Create: `src/renderer/components/inspiration/InspirationModal.tsx`
- Modify: `src/renderer/App.tsx`
- Modify: `src/renderer/components/editor/TipTapEditor.tsx`
- Modify: `src/renderer/extensions/mention.ts`
- Modify: `src/renderer/stores/useReferenceStore.ts`
- Modify: `src/renderer/components/reference/ReferencePanel.tsx`
- Modify: `src/renderer/styles/layout.css`
- Extend: `e2e/p21-features.spec.ts`

- [ ] **Step 1: InspirationModal**

对齐 `design/ui_pc.html` `#inspirationModal`：title、content、tags；保存调 `inspiration.create`；`data-testid="inspiration-modal"`。

语音按钮：

```typescript
const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition
if (SpeechRecognition) {
  const rec = new SpeechRecognition()
  rec.lang = 'zh-CN'
  rec.onresult = (e) => setContent((c) => c + e.results[0][0].transcript)
  rec.start()
}
```

不可用时 `disabled` + `title={t('inspiration.voiceUnavailable')}`。

- [ ] **Step 2: App.tsx 改 captureInspiration**

`captureInspiration` 快捷键 → `useAppStore.setInspirationModalOpen(true)`，不再直接 create。

- [ ] **Step 3: Mention 点击跳转**

`TipTapEditor` `editorProps`：

```typescript
handleClick: (view, pos, event) => {
  const el = (event.target as HTMLElement).closest('[data-setting-mention]')
  if (!el) return false
  const id = el.getAttribute('data-id')
  if (id) void useEditStore.getState().switchTarget({ kind: 'setting', id })
  return true
}
```

确保 `applyMention` 插入 HTML 含 `data-id`。

- [ ] **Step 4: 引用钉住**

`useReferenceStore`：`pinned: boolean`, `setPinned`。

`ReferencePanel`：`pinned` 时关闭按钮改为取消钉住；`setOpen(false)` 若 `pinned` 则忽略。

- [ ] **Step 5: E2E E2E-P21-INSP-01**

`Control+Shift+I` → 填内容 → 保存 → `inspiration-list` 可见。

- [ ] **Step 6: Commit**

```bash
git commit -am "feat: add inspiration modal, mention navigation, reference pin"
```

---

## Task 4: Schema v3 + 共享类型 + AI 配置（P3.0）

**Files:**
- Create: `src/main/db/schema-v3.sql`
- Modify: `src/main/db/migrate.ts`
- Create: `tests/main/migrate-v3.test.ts`
- Modify: `src/shared/types.ts`
- Modify: `src/shared/ipc-channels.ts`
- Modify: `src/main/services/global-settings.ts`

- [ ] **Step 1: schema-v3.sql**

内容同 spec §3.1 `ai_sessions` / `ai_messages` / index。

- [ ] **Step 2: migrate.ts**

`CURRENT_VERSION = 3`；`current < 3` 时 `db.exec(schemaV3)` + insert version 3。

- [ ] **Step 3: migrate-v3.test.ts**

v2 库 migrate 后 `SELECT name FROM sqlite_master` 含 `ai_sessions`。

- [ ] **Step 4: types.ts 扩展**

```typescript
export interface AiConfig {
  backend: AiBackend
  baseUrl: string
  model: string
  apiKey?: string
  timeoutMs: number
  maxTokens: number
}

export const DEFAULT_AI_CONFIG: AiConfig = {
  backend: 'lmstudio',
  baseUrl: process.env.BILIN_AI_BASE_URL ?? 'http://127.0.0.1:1234',
  model: process.env.BILIN_AI_MODEL ?? 'gemma-4-e4b-it',
  timeoutMs: 60_000,
  maxTokens: 2048
}
```

`GlobalSettings` 追加 `aiConfig`, `namingIgnoreWords: string[]`。

- [ ] **Step 5: global-settings defaults()**

合并 `aiConfig: DEFAULT_AI_CONFIG`, `namingIgnoreWords: []`。

- [ ] **Step 6: 验证 + Commit**

```bash
npm run test -- tests/main/migrate-v3.test.ts
git commit -am "feat: add schema v3 and AI config types"
```

---

## Task 5: AiClientService（P3.0）

**Files:**
- Create: `src/main/services/ai-client.service.ts`
- Create: `tests/main/ai-client.test.ts`

- [ ] **Step 1: 写真实 LM Studio 集成测试（禁止 skip）**

```typescript
import { describe, it, expect } from 'vitest'
import { AiClientService } from '../../src/main/services/ai-client.service'
import { DEFAULT_AI_CONFIG } from '../../src/shared/types'

describe('AiClientService', () => {
  const client = new AiClientService(() => DEFAULT_AI_CONFIG)

  it('IT-AI-01: chat returns non-empty content from LM Studio', async () => {
    const content = await client.chat([
      { role: 'user', content: '回复一个字：好' }
    ])
    expect(content.trim().length).toBeGreaterThan(0)
  }, 90_000)
})
```

- [ ] **Step 2: 运行确认 FAIL**

```bash
npm run test -- tests/main/ai-client.test.ts
```

- [ ] **Step 3: 实现 AiClientService**

```typescript
export interface ChatMessage {
  role: 'system' | 'user' | 'assistant'
  content: string
}

export class AiClientService {
  constructor(private getConfig: () => AiConfig) {}

  private endpoint(): string {
    const { baseUrl } = this.getConfig()
    return `${baseUrl.replace(/\/$/, '')}/v1/chat/completions`
  }

  async chat(messages: ChatMessage[], onChunk?: (delta: string) => void): Promise<string> {
    const config = this.getConfig()
    const controller = new AbortController()
    const timer = setTimeout(() => controller.abort(), config.timeoutMs)
    const res = await fetch(this.endpoint(), {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {})
      },
      body: JSON.stringify({
        model: config.model,
        messages,
        max_tokens: config.maxTokens,
        stream: Boolean(onChunk)
      }),
      signal: controller.signal
    })
    clearTimeout(timer)
    if (!res.ok) throw new Error(`AI ${res.status}: ${await res.text()}`)
    if (!onChunk) {
      const json = await res.json()
      return json.choices[0].message.content as string
    }
    // SSE parse: data: {...}\n\n
    let full = ''
    const reader = res.body!.getReader()
    const decoder = new TextDecoder()
    let buf = ''
    while (true) {
      const { done, value } = await reader.read()
      if (done) break
      buf += decoder.decode(value, { stream: true })
      const lines = buf.split('\n')
      buf = lines.pop() ?? ''
      for (const line of lines) {
        if (!line.startsWith('data: ')) continue
        const payload = line.slice(6).trim()
        if (payload === '[DONE]') continue
        const parsed = JSON.parse(payload)
        const delta = parsed.choices?.[0]?.delta?.content ?? ''
        if (delta) {
          full += delta
          onChunk(delta)
        }
      }
    }
    return full
  }
}
```

- [ ] **Step 4: 验证 PASS（需 LM Studio 运行）**

```bash
npm run test -- tests/main/ai-client.test.ts
```

- [ ] **Step 5: Commit**

```bash
git commit -am "feat: add AiClientService with LM Studio OpenAI compatibility"
```

---

## Task 6: AiSessionRepository + IPC（P3.1）

**Files:**
- Create: `src/main/db/repositories/ai-session.repo.ts`
- Create: `tests/main/ai-session.repo.test.ts`
- Create: `src/main/ipc/handlers/ai.handler.ts`
- Modify: `src/main/ipc/register.ts`
- Modify: `src/main/services/book-registry.ts`
- Modify: `src/preload/index.ts`, `src/shared/electron-api.d.ts`

- [ ] **Step 1: ai-session.repo 测试 + 实现**

CRUD：`list`, `create`, `update`, `delete`, `listMessages`, `addMessage`。

`context_json` ↔ `AiContextBinding` JSON 序列化。

- [ ] **Step 2: ai.handler.ts**

注册 spec §4.1 全部 `ai:session*` / `ai:messageList`。

`ai:chat` 骨架（暂同步，Task 7 接流式）：

```typescript
ipcMain.handle(IPC.AI_CHAT, async (event, { bookId, sessionId, content }) => {
  return wrap(async () => {
    const repo = registry.getAiSessionRepo(bookId)
    const settings = globalSettings.get()
    repo.addMessage(sessionId, 'user', content)
    const history = repo.listMessages(sessionId)
    const assistantId = randomUUID()
    const reply = await aiClient.chat(history.map(...))
    repo.addMessage(sessionId, 'assistant', reply, assistantId)
    return { messageId: assistantId }
  })
})
```

- [ ] **Step 3: book-registry getAiSessionRepo**

- [ ] **Step 4: preload 暴露 `window.electronAPI.ai.*`**

- [ ] **Step 5: 验证**

```bash
npm run test -- tests/main/ai-session.repo.test.ts
```

- [ ] **Step 6: Commit**

```bash
git commit -am "feat: add AI session repository and IPC handlers"
```

---

## Task 7: 流式 IPC + NetworkMonitor（P3.1）

**Files:**
- Create: `src/main/services/network-monitor.service.ts`
- Modify: `src/main/ipc/handlers/ai.handler.ts`
- Modify: `src/main/index.ts`
- Modify: `src/preload/index.ts`

- [ ] **Step 1: 改造 ai:chat 为流式**

`ai:chat` 内：

```typescript
const win = BrowserWindow.fromWebContents(event.sender)
let full = ''
await aiClient.chat(messages, (delta) => {
  full += delta
  win?.webContents.send(IPC.AI_STREAM_CHUNK, { messageId: assistantId, delta, done: false })
})
win?.webContents.send(IPC.AI_STREAM_CHUNK, { messageId: assistantId, delta: '', done: true })
repo.addMessage(sessionId, 'assistant', full, assistantId)
```

`ai:abort`：维护 `Map<messageId, AbortController>`。

- [ ] **Step 2: preload 订阅**

```typescript
onAiStreamChunk: (cb) => {
  const handler = (_e, payload) => cb(payload)
  ipcRenderer.on(IPC.AI_STREAM_CHUNK, handler)
  return () => ipcRenderer.removeListener(IPC.AI_STREAM_CHUNK, handler)
}
```

- [ ] **Step 3: NetworkMonitor**

`net.isOnline()` + 每 30s 检测；变化时 `webContents.send(IPC.AI_NETWORK_STATUS, { online })`。

- [ ] **Step 4: Commit**

```bash
git commit -am "feat: add AI streaming IPC and network monitor"
```

---

## Task 8: AiPanel UI + useAiStore（P3.1）

**Files:**
- Create: `src/renderer/stores/useAiStore.ts`
- Create: `src/renderer/components/ai/AiPanel.tsx`
- Modify: `src/renderer/components/layout/RightPanel.tsx`
- Modify: `src/renderer/styles/layout.css`

- [ ] **Step 1: useAiStore**

```typescript
interface AiStore {
  sessions: AiSession[]
  activeSessionId: string | null
  messages: AiMessage[]
  streamingMessageId: string | null
  streamingBuffer: string
  disabled: boolean
  writingMode: AiWritingMode // default 'chat'
  loadSessions(bookId: string): Promise<void>
  sendMessage(content: string): Promise<void>
  appendStreamChunk(payload: StreamChunk): void
}
```

挂载时订阅 `onAiStreamChunk` / `onAiNetworkStatus`。

- [ ] **Step 2: AiPanel 结构**

对齐 `ui_pc.html`：`ai-session-bar`、`ai-mode-tabs`（非 chat 调 `showToast(comingSoon)`）、`context-preview`（Task 9）、`offline-banner`、`chat-messages`、`quick-cmds`、`chat-input-area`。

`data-testid`：`ai-panel`, `ai-session-select`, `ai-chat-input`, `ai-send`, `chat-message-assistant`.

- [ ] **Step 3: RightPanel 替换 AI 占位**

`panel-content` AI Tab 渲染 `<AiPanel />`。

- [ ] **Step 4: E2E E2E-P3-CHAT-01**

`e2e/ai-chat.spec.ts`：打开书 → 新建会话 → 输入「你好」→ Enter → `chat-message-assistant` 非空（timeout 90s）。

- [ ] **Step 5: 验证 + Commit**

```bash
npm run test:e2e -- e2e/ai-chat.spec.ts
git commit -am "feat: add AiPanel with streaming chat UI"
```

---

## Task 9: 上下文编辑器 + 快捷命令（P3.2）

**Files:**
- Create: `src/main/services/ai-context-builder.service.ts`
- Create: `tests/main/ai-context-builder.test.ts`
- Create: `src/renderer/components/ai/ContextEditorModal.tsx`
- Modify: `src/main/ipc/handlers/ai.handler.ts`
- Modify: `src/renderer/components/ai/AiPanel.tsx`

- [ ] **Step 1: AiContextBuilder 测试**

截断：超长 chapter content → 块 ≤ 2000 字；总量 ≤ 16KB。

- [ ] **Step 2: 实现 build(binding, bookId)**

返回 `{ systemPrompt, preview: ContextPreviewItem[] }`。

- [ ] **Step 3: ContextEditorModal**

四 Tab 勾选列表（chapters/outlines/settings/inspirations）；保存 → `ai:sessionUpdate` patch `context_json`；「更新上下文」→ `ai:buildContext`。

- [ ] **Step 4: 快捷命令**

`src/renderer/lib/ai-slash-commands.ts`：

```typescript
export function resolveSlashCommand(cmd: string, t: TFunction): string | null {
  const map: Record<string, string> = {
    '/续写': t('ai.slash.continue'),
    '/扩写': t('ai.slash.expand'),
    // ...
  }
  return map[cmd.split(/\s/)[0]] ?? null
}
```

发送前：若匹配 slash，用模板替换实际 prompt。

- [ ] **Step 5: E2E E2E-P3-CTX-01 / E2E-P3-CMD-01**

- [ ] **Step 6: Commit**

```bash
git commit -am "feat: add AI context editor and slash commands"
```

---

## Task 10: AI 设置页（P3.0 续）

**Files:**
- Create: `src/renderer/components/settings/AiSettingsPage.tsx`
- Modify: `src/renderer/components/settings/SettingsPage.tsx`
- Modify: `src/main/ipc/handlers/ai.handler.ts`（`ai:testConnection`）
- Modify: `public/locales/*/translation.json`

- [ ] **Step 1: AiSettingsPage**

字段：backend select、baseUrl、model、apiKey（非 lmstudio 显示）、timeout。

云端 backend 显示 §6.9 许可链接。

「测试连接」→ `ai:testConnection` → 最小 chat → toast。

- [ ] **Step 2: Settings 导航增加 AI Tab**

- [ ] **Step 3: Commit**

```bash
git commit -am "feat: add AI settings page with connection test"
```

---

## Task 11: 离线降级 + 命名检查 + AI 快照（P3.3）

**Files:**
- Create: `src/renderer/components/ai/NamingCheckModal.tsx`
- Create: `src/main/services/naming-check.service.ts`
- Create: `tests/main/naming-parse.test.ts`
- Modify: `src/renderer/components/layout/RightPanel.tsx`（知识库 Tab 按钮）
- Modify: `src/renderer/lib/editor-commands.ts`
- Modify: `src/renderer/components/ai/AiPanel.tsx`

- [ ] **Step 1: 离线规则**

`useAiStore`：`disabled = aiConfig.backend !== 'lmstudio' && !networkOnline`。

`AiPanel` 显示 `#offlineBanner`；网络恢复 toast。

- [ ] **Step 2: naming-check.service**

`buildPrompt(settings, chaptersPlain)` → 调 `AiClientService.chat` → `parseNamingJson(response)`。

解析器单测（不 mock HTTP）：`tests/main/naming-parse.test.ts`。

- [ ] **Step 3: NamingCheckModal**

列表 + 忽略/替换；替换调 `search.replace`。

- [ ] **Step 4: AI 快照**

`insertToEditor(text)`：

```typescript
await ipcCall(() => window.electronAPI.snapshot.create(bookId, chapterId, 'ai', t('snapshot.ai'), currentHtml))
// then insert text at cursor
```

- [ ] **Step 5: E2E E2E-P3-NAME-01**

种子：设定「林远」+ 正文「林悦」→ 命名检查 → 至少一行结果。

- [ ] **Step 6: Commit**

```bash
git commit -am "feat: add offline fallback, naming check, and AI snapshots"
```

---

## Task 12: i18n + CSS + 全量测试 + v0.3.0（P3.4）

**Files:**
- Modify: `public/locales/zh-CN/translation.json`, `public/locales/en/translation.json`
- Modify: `src/renderer/styles/layout.css`
- Modify: `package.json`, `README.md`
- Create: `e2e/ai-chat.spec.ts`（补全 CTX/CMD/OFF）
- Extend: `e2e/p21-features.spec.ts`

- [ ] **Step 1: i18n 全量键**

`ai.*`, `naming.*`, `inspiration.voice*`, `search.replace*`, `snapshot.ai`

- [ ] **Step 2: layout.css**

`.ai-session-bar`, `.ai-mode-tabs`, `.chat-msg.user/.ai`, `.quick-cmd`, `.offline-banner`, `.naming-modal`, `.search-replace-panel`

- [ ] **Step 3: 全量测试**

```bash
npm run test
npm run build
npm run test:e2e
```

Expected: 全部 PASS（**LM Studio 必须在 127.0.0.1:1234 运行**）

- [ ] **Step 4: package.json version 0.3.0 + README**

- [ ] **Step 5: Commit + tag**

```bash
git commit -am "chore: prepare v0.3.0 release"
git tag v0.3.0
```

---

## Plan Self-Review

| Spec 章节 | 对应用 Task |
|-----------|-------------|
| §5.1 章节拖拽 | Task 1 |
| §5.2 搜索替换 | Task 2 |
| §5.3 灵感模态+语音 | Task 3 |
| §5.4 @跳转 | Task 3 |
| §5.5 引用钉住 | Task 3 |
| §3 Schema v3 | Task 4 |
| §2.2 AiClientService | Task 5 |
| §4 AI IPC | Task 6–7 |
| §6.1 AiPanel | Task 8 |
| §6.2 上下文+快捷命令 | Task 9 |
| §6.7 AI 设置 | Task 10 |
| §6.4 离线 | Task 11 |
| §6.5 命名检查 | Task 11 |
| §6.6 AI 快照 | Task 11 |
| §7 测试 | Task 1–12 |
| §10 DoD | Task 12 |

| 检查项 | 结果 |
|--------|------|
| Placeholder 扫描 | 无 TBD；写作模式 Tab 在 Task 8 明确 comingSoon |
| 测试 Mock | 全文禁止 skip；ai-client.test 真实 HTTP |
| 类型一致 | `AiContextBinding` / `context_json` / IPC 命名一致 |

---

## 执行方式

Plan 已保存至 `docs/superpowers/plans/2026-07-07-bilin-p21-p3.md`。

**两种执行选项：**

1. **Subagent-Driven（推荐）** — 每个 Task 派发独立 subagent，任务间 review，迭代快
2. **Inline Execution** — 在本会话按 Task 顺序直接实现，批次间设检查点

你选哪种？