docs: add P2.1 and P3 design spec for v0.3.0

Covers P2 backlog (chapter drag, search replace, inspiration voice, mention jump, reference pin) and strict P3-A (LM Studio chat, context injection, offline fallback, naming check) with no-mock testing requirements. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-06 14:26:56 +08:00
parent aac51bf183
commit fd04ca7ea2
1 changed files with 545 additions and 0 deletions
@@ -0,0 +1,545 @@
+# 笔临 P2.1 + P3 设计规格
+
+**版本**：1.0  
+**日期**：2026-07-07  
+**范围**：P2 遗留补完 + P3 AI 基础（严格 P3-A：对话模式实装，写作模式 Tab 占位）  
+**前置**：P2 已交付（v0.2.0，`aac51bf`）  
+**参考**：`design/readme.md` v1.1 §5.3.8 / §5.6 / §6.1–§6.2 / §6.8–§6.9、`design/ui_pc.html`
+
+**目标版本**：v0.3.0
+
+---
+
+## 1. 背景与目标
+
+### 1.1 阶段定位
+
+P2.1 补齐 P2 规格中明确延期的交互能力（章节拖拽、搜索替换、灵感语音、`@` 跳转、引用钉住）。P3 在 v0.2.0 信息管理能力之上，交付 **可对话的本地 AI 助手**：会话持久化、上下文注入、快捷命令、离线降级、命名一致性检查，以及 `ai` 类型快照。
+
+### 1.2 已确认决策（Brainstorming 2026-07-07）
+
+| 维度 | 决策 |
+|------|------|
+| 范围 | **P2.1 全量** + **P3 严格（选项 A）** |
+| P3 写作模式 | 「对话」实装；「交互 / 自动 / 向导」Tab **仅 UI 占位** → P4 |
+| AI 后端 | **LM Studio**（OpenAI 兼容 API），开发/测试/E2E 统一配置 |
+| 服务地址 | `http://127.0.0.1:1234` |
+| 模型 | `gemma-4-e4b-it` |
+| 测试原则 | **禁止 Mock**；不得以「本地服务未启动」为由 skip 测试 |
+| 架构 | **主进程直连**（`AiClientService` + IPC 流式推送） |
+| 平台 | Windows 优先（延续 P0–P2） |
+
+### 1.3 验收标准
+
+用户能完成：
+
+1. 左栏章节同卷/跨卷拖拽排序，重启后顺序保持
+2. 全局搜索：输入关键词 → 预览替换影响范围 → 确认后批量替换章节内容
+3. `Ctrl+Shift+I` 打开灵感捕获模态，文字/语音输入后保存到灵感列表
+4. 点击正文中 `@设定名` 跳转到对应设定编辑
+5. 引用面板钉住后保持可见，可与 AI 右栏互斥规则共存
+6. 设置页配置 LM Studio 地址与模型；右栏 AI 面板新建会话、发送消息、流式收到回复
+7. 勾选章节/大纲/设定/灵感作为上下文，点击「更新上下文」后下一轮对话携带最新摘要
+8. 使用 `/续写` 等快捷命令触发预设 prompt
+9. 云端后端配置下断网时 AI 输入禁用并显示离线横幅；LM Studio 配置下断网仍可用
+10. 知识库 Tab 运行命名一致性检查，逐条确认后可批量替换
+11. AI 内容写入章节前自动创建 `type='ai'` 快照
+
+### 1.4 本规格不实现（明确排除）
+
+| 项 | 归属 |
+|----|------|
+| §6.5 交互 / 自动 / 向导写作全流程 | P4 |
+| §6.3 文风学习与风格滑杆 | P4 |
+| §6.4 Skill / MCP 扩展 | P4+ |
+| §6.6 大纲生成章节骨架 | P4 |
+| §6.7 知识自动抽取与审核工作流（列表 UI） | P4 |
+| `knowledge_entries` / `timeline_events` 表 | P4/P5/P6 |
+| 导入导出（`#importModal`） | P7 |
+| 驾驶舱、章间衔接、更新计划 | P5 |
+
+---
+
+## 2. 架构
+
+### 2.1 进程模型（延续 P2）
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 主进程                                                   │
+│  · node:sqlite（每书 .sqlite，schema v3）                │
+│  · AiClientService → fetch LM Studio /v1/chat/completions│
+│  · AiSessionRepository / AiContextBuilder              │
+│  · NetworkMonitor → 推送 online/offline                  │
+│  · 既有 FTS / Search / Snapshot / Chapter 服务           │
+│  · IPC Handlers（IpcResult 信封 + ai:stream-chunk 事件）  │
+└───────────────────────────┬─────────────────────────────┘
+                            │ contextBridge
+┌───────────────────────────▼─────────────────────────────┐
+│ 渲染进程                                                   │
+│  · AiPanel（替换 RightPanel AI 占位）                     │
+│  · ContextEditorModal / NamingCheckModal                 │
+│  · InspirationModal（全局快捷键）                         │
+│  · useAiStore（会话、流式缓冲、disabled）                   │
+│  · SearchModal 替换区 / 章节 drag-and-drop               │
+└─────────────────────────────────────────────────────────┘
+```
+
+**约束**（延续 P0–P2）：
+
+- 禁止渲染进程直接 `fetch` AI API；所有推理请求经主进程
+- API Key 仅存 `global_settings.json`（主进程读写）
+- 流式输出通过 `webContents.send(IPC.AI_STREAM_CHUNK, payload)` 推送，不阻塞 IPC invoke
+
+### 2.2 AI 客户端（推荐方案）
+
+主进程 `AiClientService`：
+
+- 使用 Node.js 内置 `fetch` 调用 OpenAI Chat Completions 兼容端点
+- 支持 `stream: true`；解析 SSE `data: {...}` 行
+- `AbortController` 支持 `ai:abort`
+- 超时默认 60s（`GlobalSettings.aiConfig.timeoutMs`）
+- 错误映射为 `IpcError`，含 `recoverable: true`（超时/连接拒绝）
+
+**默认配置**（`global_settings.json`）：
+
+```typescript
+interface AiConfig {
+  backend: 'lmstudio' | 'openai' | 'anthropic'
+  baseUrl: string      // 默认 'http://127.0.0.1:1234'
+  model: string        // 默认 'gemma-4-e4b-it'
+  apiKey?: string      // openai/anthropic 时使用；lmstudio 可空
+  timeoutMs: number    // 默认 60_000
+  maxTokens: number    // 默认 2048
+}
+```
+
+**环境变量覆盖**（测试/CI，可选）：
+
+| 变量 | 作用 |
+|------|------|
+| `BILIN_AI_BASE_URL` | 覆盖 `baseUrl` |
+| `BILIN_AI_MODEL` | 覆盖 `model` |
+
+未设置时使用上述默认值；**测试不得 skip**。
+
+### 2.3 里程碑
+
+| 阶段 | 交付 | 周期 |
+|------|------|------|
+| **P2.1a** | 章节拖拽 + `chapter:move` IPC | ~2 天 |
+| **P2.1b** | 搜索替换 UI + E2E | ~1 天 |
+| **P2.1c** | 灵感模态 + 语音 + `@` 跳转 + 引用钉住 | ~2 天 |
+| **P3.0** | Schema v3 + AiClientService + AI 设置页 | ~2 天 |
+| **P3.1** | 会话 CRUD + 消息持久化 + 流式 IPC | ~3 天 |
+| **P3.2** | 上下文编辑器 + 快捷命令 | ~2 天 |
+| **P3.3** | 离线降级 + 命名检查 + AI 快照 | ~2 天 |
+| **P3.4** | 全量测试 + v0.3.0 | ~1 天 |
+
+---
+
+## 3. 数据模型
+
+### 3.1 Schema v3 迁移
+
+`schema_version` 2 → 3。增量 `schema-v3.sql` + `migrate.ts` 扩展。
+
+```sql
+CREATE TABLE ai_sessions (
+    id           TEXT PRIMARY KEY,
+    title        TEXT NOT NULL DEFAULT '',
+    model        TEXT NOT NULL DEFAULT '',
+    archived     INTEGER NOT NULL DEFAULT 0,
+    context_json TEXT NOT NULL DEFAULT '{}',
+    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at   TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE ai_messages (
+    id         TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    role       TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
+    content    TEXT NOT NULL DEFAULT '',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (session_id) REFERENCES ai_sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_ai_messages_session ON ai_messages(session_id, created_at);
+```
+
+**说明**：`ai_sessions` 存于**每本书**的 `.sqlite`（与章节等同库），非全局。
+
+**`context_json` 结构**：
+
+```typescript
+interface AiContextBinding {
+  chapterIds: string[]
+  outlineIds: string[]
+  settingIds: string[]
+  inspirationIds: string[]
+}
+```
+
+**全局 userData**（`global_settings.json` 扩展，非书籍 DB）：
+
+```typescript
+interface GlobalSettings {
+  // ...existing P2 fields
+  aiConfig: AiConfig
+  namingIgnoreWords: string[]
+}
+```
+
+### 3.2 共享类型扩展（`src/shared/types.ts`）
+
+```typescript
+export type AiBackend = 'lmstudio' | 'openai' | 'anthropic'
+export type AiMessageRole = 'user' | 'assistant' | 'system'
+export type AiWritingMode = 'chat' | 'interactive' | 'auto' | 'wizard' // UI only; P3 仅 chat 实装
+
+export interface AiSession {
+  id: string
+  title: string
+  model: string
+  archived: boolean
+  context: AiContextBinding
+  createdAt: string
+  updatedAt: string
+}
+
+export interface AiMessage {
+  id: string
+  sessionId: string
+  role: AiMessageRole
+  content: string
+  createdAt: string
+}
+
+export interface NamingConflict {
+  termA: string
+  termB: string
+  confidence: number
+  reason: string
+  suggestedCanonical?: string
+}
+```
+
+---
+
+## 4. IPC 通道
+
+### 4.1 新增常量（`ipc-channels.ts`）
+
+```typescript
+// Chapter
+CHAPTER_MOVE: 'chapter:move',
+
+// AI
+AI_SESSION_LIST: 'ai:sessionList',
+AI_SESSION_CREATE: 'ai:sessionCreate',
+AI_SESSION_UPDATE: 'ai:sessionUpdate',
+AI_SESSION_DELETE: 'ai:sessionDelete',
+AI_MESSAGE_LIST: 'ai:messageList',
+AI_CHAT: 'ai:chat',
+AI_ABORT: 'ai:abort',
+AI_BUILD_CONTEXT: 'ai:buildContext',
+AI_NAMING_CHECK: 'ai:namingCheck',
+AI_STREAM_CHUNK: 'ai:streamChunk',   // main → renderer event
+AI_NETWORK_STATUS: 'ai:networkStatus', // main → renderer event
+```
+
+### 4.2 Handler 契约
+
+| 通道 | 参数 | 返回 |
+|------|------|------|
+| `chapter:move` | `{ bookId, chapterId, volumeId, sortOrder }` | `Chapter` |
+| `ai:sessionList` | `{ bookId, includeArchived? }` | `AiSession[]` |
+| `ai:sessionCreate` | `{ bookId, title? }` | `AiSession` |
+| `ai:sessionUpdate` | `{ bookId, sessionId, patch }` | `AiSession` |
+| `ai:sessionDelete` | `{ bookId, sessionId }` | `void` |
+| `ai:messageList` | `{ bookId, sessionId }` | `AiMessage[]` |
+| `ai:chat` | `{ bookId, sessionId, content, slashCommand? }` | `{ messageId }` |
+| `ai:abort` | `{ messageId }` | `void` |
+| `ai:buildContext` | `{ bookId, binding }` | `{ preview: ContextPreviewItem[] }` |
+| `ai:namingCheck` | `{ bookId }` | `NamingConflict[]` |
+
+**`ai:chat` 流程**：
+
+1. 持久化 user message
+2. `AiContextBuilder` 组装 messages 数组（system + 历史 + user）
+3. 调用 `AiClientService.chatStream(...)`
+4. 流式推送 `ai:streamChunk`；完成后持久化 assistant message
+
+---
+
+## 5. P2.1 功能规格
+
+### 5.1 章节拖拽排序
+
+**UI**：左栏章节列表项 `draggable`；拖拽指示线（同卷内）。
+
+**逻辑**：
+
+- 同卷：重算 `sort_order`（0..n-1），批量 `chapter:move` 或单次 `chapter.repo.move`
+- 跨卷：更新 `volume_id` + 目标卷末尾 `sort_order`
+- 拖拽结束触发 `flushEditorSave()`（若当前章节被移动）
+
+**Repository**：
+
+```typescript
+move(chapterId: string, volumeId: string, sortOrder: number): Chapter
+```
+
+### 5.2 全局搜索替换
+
+对齐 `design/readme.md` §5.6.1 底部替换区。
+
+**UI**（`SearchModal` 扩展）：
+
+- 折叠区「替换」：替换文本输入 + 「预览变更」+ 「执行替换」
+- 预览调用 `search:replace(dryRun: true)` → 列表展示受影响条目
+- 确认后 `search:replace(dryRun: false)` → toast 显示替换数量
+- 替换后刷新 `useBookStore` 章节列表；若当前章被替换则刷新编辑器
+
+**范围**：P2 已支持全书；本阶段补 UI，不扩展 scope select（可后续加）。
+
+### 5.3 灵感快速捕获
+
+**UI**：`#inspirationModal`（对齐 `ui_pc.html`）
+
+- 标题、内容、标签（逗号分隔）
+- 语音按钮：`webkitSpeechRecognition`（`zh-CN`），实时填入内容框
+- 保存 → `inspiration:create` + 可选 `switchTarget`
+- 不打断编辑器：关闭后焦点回 `.ProseMirror`
+
+**快捷键**：`Ctrl+Shift+I`（`captureInspiration` 已有 handler，改为打开模态而非直接 create）
+
+### 5.4 `@提及` 反向跳转
+
+`SettingMention` Mark 增加 `onClick` / `editorProps` 处理：
+
+- 点击带 `data-setting-mention` 的 span → `switchTarget({ kind: 'setting', id })`
+- 光标样式 `pointer`
+
+### 5.5 引用面板钉住
+
+`useReferenceStore` 扩展：
+
+```typescript
+pinned: boolean
+setPinned(open: boolean): void
+```
+
+- 钉住按钮（📌）在 `ref-header`
+- `pinned === true` 时 `setOpen(false)` 不隐藏面板
+- 与 AI 右栏互斥：引用打开时仍隐藏 RightPanel（延续 P2）；钉住引用 + 需 AI 时用户手动关闭引用
+
+---
+
+## 6. P3 功能规格
+
+### 6.1 AI 面板 UI（`AiPanel.tsx`）
+
+对齐 `ui_pc.html` `#ai-chat`：
+
+| 区域 | 行为 |
+|------|------|
+| 会话栏 | `<select>` + 新建按钮；重命名（双击 inline）；右键归档/删除 |
+| 模式 Tab | 对话 **active**；交互/自动/向导 → `feature.comingSoon` |
+| 上下文预览行 | 显示摘要计数；点击打开 `ContextEditorModal` |
+| 离线横幅 | `aiStore.disabled` 时显示 `#offlineBanner` |
+| 消息区 | user/assistant 气泡；assistant 流式追加 |
+| 快捷命令 | `/续写` `/扩写` `/润色` `/总结` `/纠错` chip 点击填入 |
+| 输入区 | Enter 发送；生成中禁用 + 「停止」调 `ai:abort` |
+| 插入编辑器 | assistant 消息旁「插入」→ 纯文本插入章节光标（触发 AI 快照） |
+
+### 6.2 上下文注入（`AiContextBuilder`）
+
+**源数据**：
+
+| 类型 | 提取内容 | 单条上限 |
+|------|----------|----------|
+| chapter | `title` + `stripHtml(content)` 截断 | 2000 字符 |
+| outline | `title` + `description` 截断 | 500 字符 |
+| setting | `name` + `description` 截断 | 500 字符 |
+| inspiration | `title` + `content` 截断 | 500 字符 |
+
+**总量上限**：~16KB plain text；超出时按 sort_order 新近优先截断。
+
+**System prompt 模板**（i18n）：
+
+```
+你是笔临 AI 写作助手。作者笔名：{penName}。书籍：{bookName}。
+以下是与本书相关的上下文（由作者勾选）：
+{contextBlocks}
+请用简体中文回答，尊重作者的创作主权。
+```
+
+**「更新上下文」**：重新 `ai:buildContext` 并更新 `context_json` 勾选不变；仅刷新预览摘要。
+
+### 6.3 快捷命令
+
+| 命令 | 预设意图 |
+|------|----------|
+| `/续写` | 基于当前章节末尾续写 200–400 字 |
+| `/扩写` | 扩展选中或最近一段描写 |
+| `/润色` | 改善文笔，保持情节不变 |
+| `/总结` | 总结当前章节要点 |
+| `/纠错` | 指出语法/标点问题 |
+
+实现：解析以 `/` 开头的输入 → 映射 i18n 模板 → 作为 user message 发送（UI 仍显示原命令）。
+
+### 6.4 离线降级（§6.8）
+
+**主进程 `NetworkMonitor`**：
+
+- 监听 `net.isOnline()` + 定时探测（可选 `HEAD` 到 `https://1.1.1.1`）
+- 状态变化 → `AI_NETWORK_STATUS`
+
+**渲染进程规则**：
+
+```typescript
+const disabled =
+  settings.aiConfig.backend !== 'lmstudio' && !networkOnline
+```
+
+- `disabled` 时：输入框 `disabled`，快捷命令灰显，横幅可见
+- `lmstudio` 后端：**永不**因离线禁用
+- 网络恢复：toast `ai.networkRestored`
+
+### 6.5 命名一致性检查（§5.6.2）
+
+**入口**：知识库 Tab 顶部按钮「命名一致性检查」
+
+**流程**：
+
+1. 收集 `settings[].name` + 全书章节 plainText
+2. 构造 prompt，要求模型返回 **纯 JSON 数组** `NamingConflict[]`
+3. `NamingCheckModal` 列表：termA / termB / 置信度 / 原因
+4. 操作：忽略（加入 `namingIgnoreWords`）、替换为 canonical（调 `search:replace`）
+5. 解析失败：toast 错误，展示原始响应片段（调试用）
+
+### 6.6 AI 快照（§5.4.1）
+
+触发点：
+
+- `AiPanel`「插入到编辑器」
+- 任意将 AI 生成内容写入 `chapters.content` 的路径
+
+行为：`snapshot:create(chapterId, 'ai', 'AI 生成前', currentContent)` → 再写入新内容。
+
+### 6.7 AI 设置页
+
+**位置**：系统设置 → 新 Tab「AI 配置」
+
+| 字段 | 说明 |
+|------|------|
+| 后端类型 | select: LM Studio / OpenAI / Anthropic |
+| 服务地址 | text（LM Studio 默认 `http://127.0.0.1:1234`） |
+| 模型 | text（默认 `gemma-4-e4b-it`） |
+| API Key | password（云端后端时显示） |
+| 超时 | number，秒 |
+
+**§6.9 许可提示**：选择云端后端时显示服务条款链接文案。
+
+**测试连接**按钮：发送最小 chat 请求，toast 成功/失败。
+
+---
+
+## 7. 测试
+
+### 7.1 原则
+
+- **禁止 Mock** `fetch` / AI 响应
+- **禁止** `test.skipIf(!aiAvailable)` 或类似条件跳过
+- 集成/E2E 必须对 `http://127.0.0.1:1234` 发起真实请求
+- 服务未启动时测试 **失败**，迫使环境就绪
+
+### 7.2 单元 / 集成
+
+| 文件 | 场景 |
+|------|------|
+| `tests/main/migrate-v3.test.ts` | v2→v3 迁移 |
+| `tests/main/ai-session.repo.test.ts` | 会话/消息 CRUD |
+| `tests/main/chapter.repo.test.ts` | `move` 排序 |
+| `tests/main/ai-client.test.ts` | 真实 LM Studio 请求，响应非空 |
+| `tests/main/ai-context-builder.test.ts` | 上下文截断与拼接 |
+| `tests/main/naming-check.test.ts` | JSON 解析（mock 仅解析器，不 mock HTTP） |
+
+### 7.3 E2E
+
+| ID | 场景 |
+|----|------|
+| E2E-P21-DRAG-01 | 拖拽章节改变顺序，重启后保持 |
+| E2E-P21-REP-01 | 搜索 → 预览替换 → 执行 → 正文更新 |
+| E2E-P21-INSP-01 | Ctrl+Shift+I 模态保存灵感 |
+| E2E-P3-CHAT-01 | 新建会话 → 发送「你好」→ assistant 非空 |
+| E2E-P3-CTX-01 | 勾选设定 → 更新上下文 → 摘要行更新 |
+| E2E-P3-CMD-01 | 点击 `/总结` → 发送 → 收到回复 |
+| E2E-P3-NAME-01 | 命名检查模态出现 ≥1 行（需种子数据） |
+| E2E-P3-OFF-01 | 配置 openai + 模拟离线 → 输入禁用（可用 evaluate 设 `aiStore`） |
+
+### 7.4 手动验收
+
+1. LM Studio 运行 `gemma-4-e4b-it`，笔临设置页「测试连接」成功
+2. 右栏多轮对话，重启后会话与消息保留
+3. 上下文勾选后 AI 回答能引用设定名称
+4. 命名检查对「林远/林悦」类冲突给出建议
+
+---
+
+## 8. UI / CSS
+
+- 新增/扩展 `layout.css`：`.ai-session-bar`、`.ai-mode-tabs`、`.chat-messages`、`.chat-msg`、`.quick-cmds`、`.offline-banner`、`.naming-modal`
+- 对齐 `design/ui_pc.html` 行 1203–2076 结构与 class 命名
+- 灵感模态对齐 `#inspirationModal`
+- i18n：`ai.*`、`naming.*`、`inspiration.voice*` 等键
+
+---
+
+## 9. 风险与缓解
+
+| 风险 | 缓解 |
+|------|------|
+| LM Studio 未启动导致 CI 失败 | 文档明确前置条件；本地开发脚本检测端口 |
+| 流式 IPC 消息乱序 | `messageId` 关联；渲染进程按 id 缓冲 |
+| 大上下文超 token | 硬限制 16KB + 截断策略 |
+| 命名检查 JSON 解析失败 | 重试一次；失败 toast + 日志 |
+| Web Speech API 不可用 | 语音按钮 disabled + tooltip；E2E 不测语音 |
+| `gemma-4-e4b-it` 模型名变更 | 环境变量 `BILIN_AI_MODEL` 覆盖 |
+
+---
+
+## 10. Definition of Done（v0.3.0）
+
+- [ ] P2.1a–c + P3.0–3 全部里程碑完成
+- [ ] §7 测试全部 PASS（含真实 LM Studio 集成测试）
+- [ ] `npm run build` 无 error
+- [ ] 交互/自动/向导 Tab 为占位，不 crash
+- [ ] Windows 手动验收 §7.4 四项通过
+
+---
+
+## Spec Self-Review
+
+| 检查项 | 结果 |
+|--------|------|
+| Placeholder 扫描 | 交互/自动/向导/知识库列表明确 P4；无 TBD |
+| 内部一致性 | AI 主进程直连贯穿 IPC/测试；context_json 与 AiContextBinding 对齐 |
+| 范围 | 单规格可支撑一份 implementation plan；P2.1 与 P3 边界清晰 |
+| 歧义 | P3-A 已确认；LM Studio 默认值与环境变量覆盖已写明 |
+| 测试 | 禁止 Mock/skip 已作为硬性原则写入 §7.1 |
+
+---
+
+## 附录：与 P2 规格差异
+
+| 项 | P2 规格 | 本规格 |
+|----|---------|--------|
+| 搜索替换 UI | P2.6 规划 | P2.1b 实装 |
+| 灵感语音 | P2.1 占位 | P2.1c 实装 |
+| 章节拖拽 | P2.1 | P2.1a 实装 |
+| AI 命名检查 | P3 占位 | P3.3 实装 |
+| ai 快照 | P3 | P3.3 实装 |
+| ai_sessions 表 | P3/P5/P6 | P3.0 实装（每书 DB） |
+| 写作模式 | — | P3 UI 占位，P4 实装 |