From 64da95f7e1779edea5c6298730e1d060ee6886c9 Mon Sep 17 00:00:00 2001 From: kun1h Date: Wed, 8 Jul 2026 14:23:19 +0800 Subject: [PATCH] docs: add Wave 1 foundation implementation plan for v1.2.0 Covers schema v9, book settings, volume/chapter management UI, template context, AI session menu, focus mode, and TTS per master completion spec. Co-authored-by: Cursor --- .../plans/2026-07-08-bilin-w1-foundation.md | 452 ++++++++++++++++++ 1 file changed, 452 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-08-bilin-w1-foundation.md diff --git a/docs/superpowers/plans/2026-07-08-bilin-w1-foundation.md b/docs/superpowers/plans/2026-07-08-bilin-w1-foundation.md new file mode 100644 index 0000000..ac4f02b --- /dev/null +++ b/docs/superpowers/plans/2026-07-08-bilin-w1-foundation.md @@ -0,0 +1,452 @@ +# 笔临 Wave 1 基础治理 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:** 交付 v1.2.0：清除 Wave 1 范围内全部 `comingSoon` 占位，补全书籍/分卷/章节管理 UI，模板变量自动填充，AI 会话管理，专注模式与 TTS 快捷键。 + +**Architecture:** schema v9 扩展 `chapter_tags` / `published_at` / `book_preferences.always_show_cockpit`；扩展 `BookMeta` 与 `BOOK_UPDATE_META`；渲染进程新增 `BookSettingsTab`、`FocusMode` overlay、`ChapterMetaPanel`；复用已有 `volume.*` / `chapter.delete` IPC；`chapter-template` 上下文从 outlines/settings 聚合。 + +**Tech Stack:** Electron 36、electron-vite、React 18、TypeScript、node:sqlite、Zustand、i18next、Vitest、Playwright + +**Spec:** `docs/superpowers/specs/2026-07-08-bilin-master-completion-design.md` §5 + +**Master Program:** Wave 1/5 → v1.2.0 + +--- + +## File Map + +| 文件 | 职责 | +|------|------| +| `src/main/db/schema-v9.sql` | chapter_tags 表 | +| `src/main/db/migrate.ts` | CURRENT_VERSION=9，published_at/word_count_threshold | +| `src/main/db/repositories/chapter-tag.repo.ts` | 章节标签 CRUD | +| `src/main/db/repositories/chapter.repo.ts` | published_at、summary、story_time、threshold 读写 | +| `src/main/services/book-registry.ts` | updateMeta 扩展 name/category/targetWordCount/coverPath/synopsis | +| `src/main/services/cockpit.service.ts` | always_show_cockpit 逻辑 | +| `src/main/ipc/handlers/book.handler.ts` | BOOK_UPDATE_META 扩展 | +| `src/main/ipc/handlers/chapter.handler.ts` | CHAPTER_TAG_*、published_at on setPublishStatus | +| `src/main/ipc/handlers/ai.handler.ts` | AI_SESSION_EXPORT | +| `src/shared/types.ts` | BookMeta、UpdateBookMetaParams、ChapterTag | +| `src/shared/ipc-channels.ts` | 新 IPC 常量 | +| `src/preload/index.ts` + `electron-api.d.ts` | bookPrefs、chapterTags、sessionExport | +| `src/shared/chapter-template.ts` | `buildTemplateContext()` 含 outlineItem/characterList | +| `src/renderer/components/book/BookSettingsTab.tsx` | 右栏书籍设置 | +| `src/renderer/components/chapter/ChapterMetaPanel.tsx` | summary/story_time/tags | +| `src/renderer/components/volume/VolumeContextMenu.tsx` | 分卷右键 | +| `src/renderer/components/focus/FocusModeOverlay.tsx` | 专注模式 | +| `src/renderer/lib/tts-controller.ts` | TTS 朗读 | +| `src/renderer/components/layout/RightPanel.tsx` | 接入 BookSettingsTab | +| `src/renderer/components/layout/EditorLayout.tsx` | 章双击改名、删除、meta、阈值变色 | +| `src/renderer/components/layout/TopBar.tsx` | 日更进度条（细条） | +| `src/renderer/components/ai/AiSessionMenu.tsx` | 会话重命名/归档/导出/删除 | +| `src/renderer/components/ai/AiPanel.tsx` | 接入 AiSessionMenu | +| `src/renderer/components/wordfreq/WordFreqPanel.tsx` | 命名检查入口 | +| `src/renderer/App.tsx` | focusMode / toggleTTS 快捷键 | +| `src/renderer/stores/useBookPrefsStore.ts` | alwaysShowCockpit | +| `public/locales/*/translation.json` | bookSettings / chapterMeta / focus / tts | +| `tests/main/chapter-template-context.test.ts` | UT outlineItem/characterList | +| `tests/main/chapter-tag.repo.test.ts` | IT 标签 | +| `e2e/book-settings.spec.ts` | E2E 书籍设置+删书 | +| `e2e/chapter-management.spec.ts` | E2E 章改名+删除 | +| `e2e/focus-tts.spec.ts` | E2E 专注+TTS | +| `e2e/chapter-template.spec.ts` | 扩展 E2E-TEMPL-05 | + +--- + +## Task 1: Schema v9 + 类型扩展 + +**Files:** +- Create: `src/main/db/schema-v9.sql` +- Modify: `src/main/db/migrate.ts` +- Modify: `src/shared/types.ts` +- Modify: `src/shared/ipc-channels.ts` + +- [ ] **Step 1: schema-v9.sql** + +```sql +CREATE TABLE IF NOT EXISTS chapter_tags ( + chapter_id TEXT NOT NULL, + tag TEXT NOT NULL, + color TEXT DEFAULT '', + PRIMARY KEY (chapter_id, tag), + FOREIGN KEY (chapter_id) REFERENCES chapters(id) ON DELETE CASCADE +); +``` + +- [ ] **Step 2: migrate.ts** — `CURRENT_VERSION = 9`，新增 block： + +```typescript +if (current < 9) { + tryAlter(db, 'ALTER TABLE chapters ADD COLUMN published_at TEXT DEFAULT NULL') + tryAlter(db, 'ALTER TABLE chapters ADD COLUMN word_count_threshold INTEGER DEFAULT NULL') + db.exec(schemaV9) + db.prepare('INSERT INTO schema_version (version, description) VALUES (?, ?)').run(9, 'W1 foundation') +} +``` + +- [ ] **Step 3: types.ts** — 扩展： + +```typescript +export interface BookMeta { + // existing... + coverPath?: string | null + synopsis?: string +} + +export interface UpdateBookMetaParams { + name?: string + category?: string + targetWordCount?: number | null + coverPath?: string | null + synopsis?: string + lastChapterId?: string | null + status?: BookStatus +} + +export interface ChapterTag { + chapterId: string + tag: string + color: string +} + +// Chapter 已有 summary?, storyTime? — 确保 chapter.update IPC 接受它们 +``` + +- [ ] **Step 4: ipc-channels.ts** + +```typescript +CHAPTER_TAG_LIST: 'chapter:tagList', +CHAPTER_TAG_SET: 'chapter:tagSet', +CHAPTER_TAG_REMOVE: 'chapter:tagRemove', +BOOK_PREFS_GET: 'book:prefsGet', +BOOK_PREFS_SET: 'book:prefsSet', +AI_SESSION_EXPORT: 'ai:sessionExport', +``` + +- [ ] **Step 5: 运行** `npm run build` — 应通过 + +--- + +## Task 2: Repository + BookRegistry 扩展 + +**Files:** +- Create: `src/main/db/repositories/chapter-tag.repo.ts` +- Modify: `src/main/db/repositories/chapter.repo.ts` +- Modify: `src/main/services/book-registry.ts` +- Modify: `src/main/services/cockpit.service.ts` + +- [ ] **Step 1: ChapterTagRepository** + +```typescript +export class ChapterTagRepository { + constructor(private db: SqliteDb) {} + list(chapterId: string): ChapterTag[] { /* SELECT */ } + set(chapterId: string, tag: string, color = ''): void { /* INSERT OR REPLACE */ } + remove(chapterId: string, tag: string): void { /* DELETE */ } + listAll(): ChapterTag[] { /* for book open */ } +} +``` + +- [ ] **Step 2: chapter.repo update** — `update()` 与 `setPublishStatus()` 支持 `summary`, `storyTime`, `wordCountThreshold`, `publishedAt`： + +```typescript +setPublishStatus(id: string, publishStatus: PublishStatus): Chapter { + const patch: Parameters[1] = { publishStatus } + if (publishStatus === 'published') { + patch.publishedAt = new Date().toISOString() + } + return this.update(id, patch) +} +``` + +- [ ] **Step 3: book-registry.updateMeta** — 签名改为 `Partial>` + +- [ ] **Step 4: cockpit.service** + +```typescript +shouldShowOnOpen(): boolean { + const prefs = new BookPrefsRepository(this.db) + if (prefs.get('alwaysShowCockpit') === 'true') return true + return prefs.get('cockpitSeen') !== 'true' +} +``` + +- [ ] **Step 5: UT** `tests/main/chapter-tag.repo.test.ts` — 创建章+标签+列表 + +Run: `npm run test -- --run tests/main/chapter-tag.repo.test.ts` + +--- + +## Task 3: IPC handlers + preload + +**Files:** +- Modify: `src/main/ipc/handlers/book.handler.ts` +- Modify: `src/main/ipc/handlers/chapter.handler.ts` +- Create: `src/main/ipc/handlers/book-prefs.handler.ts` +- Modify: `src/main/ipc/handlers/ai.handler.ts` +- Modify: `src/main/ipc/register.ts` +- Modify: `src/preload/index.ts` +- Modify: `src/shared/electron-api.d.ts` + +- [ ] **Step 1: book.handler** — `BOOK_UPDATE_META` 接受 `UpdateBookMetaParams` + +- [ ] **Step 2: chapter.handler** — 扩展 `CHAPTER_UPDATE` 接受 `summary`, `storyTime`, `wordCountThreshold`；新增： + +```typescript +ipcMain.handle(IPC.CHAPTER_TAG_LIST, (_e, { bookId, chapterId }) => + wrap(() => new ChapterTagRepository(registry.getDb(bookId)).list(chapterId))) +// TAG_SET / TAG_REMOVE 同理 +``` + +- [ ] **Step 3: book-prefs.handler** + +```typescript +ipcMain.handle(IPC.BOOK_PREFS_GET, (_e, { bookId, key }) => + wrap(() => new BookPrefsRepository(registry.getDb(bookId)).get(key))) +ipcMain.handle(IPC.BOOK_PREFS_SET, (_e, { bookId, key, value }) => + wrap(() => { new BookPrefsRepository(registry.getDb(bookId)).set(key, value) })) +``` + +- [ ] **Step 4: ai.handler** — `AI_SESSION_EXPORT`：读 messages，格式化 markdown，`dialog.showSaveDialog`，写文件 + +- [ ] **Step 5: preload** — `book.updateMeta` 扩展；`bookPrefs.get/set`；`chapterTag.list/set/remove`；`ai.session.export(bookId, sessionId, format)` + +- [ ] **Step 6: build** `npm run build` + +--- + +## Task 4: 模板上下文 enrich + +**Files:** +- Modify: `src/shared/chapter-template.ts` +- Modify: `src/renderer/components/chapter/TemplateQuickCreateModal.tsx` +- Create: `tests/main/chapter-template-context.test.ts` + +- [ ] **Step 1: 新增 `buildTemplateContext()`** + +```typescript +export function buildTemplateContext(input: { + chapterTitle: string + penName: string + volumes: Volume[] + chapters: Chapter[] + outlines: OutlineItem[] + settings: SettingEntry[] + activeVolumeId: string | null + selectedChapterId?: string | null +}): TemplateContext { + const volChapters = input.chapters + .filter((c) => c.volumeId === input.activeVolumeId) + .sort((a, b) => a.sortOrder - b.sortOrder) + const chapterNumber = volChapters.length + 1 + const outlineItem = + input.outlines.find((o) => o.chapterId === input.selectedChapterId)?.title ?? '' + const characterList = input.settings + .filter((s) => s.type === 'character') + .slice(0, 8) + .map((s) => s.name) + .join('、') + return { + chapterNumber, + chapterTitle: input.chapterTitle, + penName: input.penName, + date: new Date().toLocaleDateString('zh-CN'), + volumeName: input.volumes.find((v) => v.id === input.activeVolumeId)?.name ?? '', + previousChapterTitle: volChapters.at(-1)?.title ?? '', + outlineItem, + characterList + } +} +``` + +- [ ] **Step 2: TemplateQuickCreateModal** — 用 `buildTemplateContext` 替换内联 `buildContext` + +- [ ] **Step 3: UT** + +```typescript +it('UT-TEMPL-05: characterList from settings', () => { + const ctx = buildTemplateContext({ /* 2 characters */ }) + expect(ctx.characterList).toContain('林远') +}) +``` + +Run: `npm run test -- --run tests/main/chapter-template-context.test.ts` + +--- + +## Task 5: BookSettingsTab + +**Files:** +- Create: `src/renderer/components/book/BookSettingsTab.tsx` +- Create: `src/renderer/stores/useBookPrefsStore.ts` +- Modify: `src/renderer/components/layout/RightPanel.tsx` + +- [ ] **Step 1: BookSettingsTab** — 表单字段： + - 书名、分类、目标字数、简介（textarea） + - 封面：按钮选文件 → 存 `userData/covers/{bookId}.jpg` 路径到 meta.coverPath + - 「每次打开显示驾驶舱」checkbox → `bookPrefs.set('alwaysShowCockpit', 'true'|'false')` + - 危险区：删书 → confirm → `book.delete` → `loadBooks` → `setView('home')` + +- [ ] **Step 2: RightPanel** — `book-settings` panel 渲染 `` + +- [ ] **Step 3: i18n** — `bookSettings.*` 键（中英） + +--- + +## Task 6: 分卷右键 + 章节管理 UI + +**Files:** +- Create: `src/renderer/components/volume/VolumeContextMenu.tsx` +- Create: `src/renderer/components/chapter/ChapterMetaPanel.tsx` +- Modify: `src/renderer/components/layout/EditorLayout.tsx` + +- [ ] **Step 1: VolumeContextMenu** — 绑定分卷标题 `onContextMenu`： + - 重命名：prompt → `volume.update` + - 编辑简述：prompt → `volume.update({ description })` + - 删除：若卷内无章 → `volume.delete`；有章则 toast 错误 + +- [ ] **Step 2: 章节双击改名** — `chapter-item` `onDoubleClick` → input inline → `chapter.update({ title })` + +- [ ] **Step 3: 章节删除** — 右键或 hover 图标 → confirm → `chapter.delete` → `refreshChapters` + +- [ ] **Step 4: ChapterMetaPanel** — 侧栏或状态栏按钮打开： + - summary、story_time 输入 + - 标签 chips + 添加输入 + - word_count_threshold 数字 + +- [ ] **Step 5: 发布日期** — `setPublishStatus` 后本地 chapter 显示 `published_at`（只读） + +- [ ] **Step 6: 字数阈值变色** — 状态栏 `wordCount.chapter` 与 `currentChapter.wordCountThreshold` 比较，超则橙色 class + +--- + +## Task 7: AI 会话菜单 + +**Files:** +- Create: `src/renderer/components/ai/AiSessionMenu.tsx` +- Modify: `src/renderer/components/ai/AiPanel.tsx` +- Modify: `src/renderer/stores/useAiStore.ts` + +- [ ] **Step 1: AiSessionMenu** — 会话选择器旁「⋯」按钮： + - 重命名 → `ai.session.update({ title })` + - 归档/取消归档 → `{ archived: true/false }` + - 导出 → 子菜单 txt/md → `ai.session.export` + - 删除 → confirm → `ai.session.delete` + +- [ ] **Step 2: useAiStore** — `loadSessions(bookId, true)` 加载含归档；归档会话 optgroup 或折叠区 + +- [ ] **Step 3: i18n** — `ai.session.*` + +--- + +## Task 8: 专注模式 + TTS + +**Files:** +- Create: `src/renderer/components/focus/FocusModeOverlay.tsx` +- Create: `src/renderer/lib/tts-controller.ts` +- Modify: `src/renderer/App.tsx` +- Modify: `src/renderer/styles/layout.css` + +- [ ] **Step 1: FocusModeOverlay** — `useAppStore.focusMode` boolean： + - true 时 `#app` 加 `focus-mode` class（CSS 隐藏 sidebars/right-panel/topbar 非必要按钮） + - Esc 或按钮退出 + +- [ ] **Step 2: App.tsx** — `focusMode` 动作调用 `setFocusMode(true)`；再次按退出 + +- [ ] **Step 3: tts-controller.ts** + +```typescript +export function speakText(text: string, lang = 'zh-CN'): void { + const u = new SpeechSynthesisUtterance(text) + u.lang = lang + window.speechSynthesis.cancel() + window.speechSynthesis.speak(u) +} +export function stopSpeaking(): void { + window.speechSynthesis.cancel() +} +``` + +- [ ] **Step 4: App.tsx** — `toggleTTS`：若正在朗读则 stop；否则读当前章 `editor.getText()` 或选区 + +- [ ] **Step 5: i18n** — `focus.*` / `tts.*` + +--- + +## Task 9: 占位清零 + 顶栏进度 + +**Files:** +- Modify: `src/renderer/components/wordfreq/WordFreqPanel.tsx` +- Modify: `src/renderer/components/layout/TopBar.tsx` +- Modify: `src/renderer/stores/useAppStore.ts` + +- [ ] **Step 1: WordFreqPanel** — 底部按钮 `onClick` 改为 `setNamingOpen(true)` 或触发 KnowledgePanel 命名检查（与 `NamingCheckModal` 联动） + +- [ ] **Step 2: TopBar** — 在 `top-spacer` 前加细进度条： + - 读 `useWritingStatsStore` + `dailyWordGoal` + - `goalProgress` 映射 width%；≥100% 绿色，≥80% 橙色 + +- [ ] **Step 3: 全局 grep** `feature.comingSoon` — Wave 1 范围内应无功能入口残留 + +--- + +## Task 10: E2E + 版本 v1.2.0 + +**Files:** +- Create: `e2e/book-settings.spec.ts` +- Create: `e2e/chapter-management.spec.ts` +- Create: `e2e/focus-tts.spec.ts` +- Modify: `e2e/chapter-template.spec.ts` +- Modify: `e2e/helpers.ts` +- Modify: `package.json`, `README.md`, `SettingsPage.tsx` + +- [ ] **Step 1: e2e/helpers.ts** — `openBookSettings(page)` helper + +- [ ] **Step 2: E2E-BOOK-01** — 改书名、勾选 always cockpit、删书 + +- [ ] **Step 3: E2E-CHAP-01** — 双击改标题、删除章 + +- [ ] **Step 4: E2E-FOCUS-01** — Ctrl+Alt+F 进入专注，Esc 退出 + +- [ ] **Step 5: E2E-TEMPL-05** — 模板含 `{characterList}` 的自定义模板（设置页创建）→ 快速新建 → 编辑器含角色名 + +- [ ] **Step 6: 全量验证** + +```bash +npm run build +npm run test +npm run test:e2e -- e2e/book-settings.spec.ts e2e/chapter-management.spec.ts e2e/focus-tts.spec.ts e2e/chapter-template.spec.ts +``` + +- [ ] **Step 7: 版本** — `package.json` / README / Settings 关于页 → **v1.2.0** + +- [ ] **Step 8: 勾选本 plan 全部 checkbox** + +--- + +## Plan 自检 + +| Spec §5 要求 | Task | +|-------------|------| +| 5.1 书籍设置 Tab | Task 5 | +| 5.2 分卷管理 | Task 6 | +| 5.3 章节管理 | Task 6 | +| 5.4 模板变量 | Task 4 | +| 5.5 AI 会话 UI | Task 7 | +| 5.6 快捷键 | Task 8 | +| 5.7 用词分析 | Task 9 | +| 5.8 验收 E2E | Task 10 | + +无 TBD 占位。 + +--- + +## 后续波次计划（待 W1 完成后编写） + +| 文件 | 版本 | +|------|------| +| `docs/superpowers/plans/2026-07-08-bilin-w2-project-pack.md` | v1.3.0 | +| `docs/superpowers/plans/2026-07-08-bilin-w3-export-read.md` | v1.4.0 | +| `docs/superpowers/plans/2026-07-08-bilin-w4-creative-depth.md` | v1.5.0 | +| `docs/superpowers/plans/2026-07-08-bilin-w5-platform.md` | v2.0.0 |