# 笔临 Master Completion 全量对齐设计规格 **版本**:1.0 **日期**:2026-07-08 **范围**:`design/readme.md` v1.1 全部未实现/占位/部分实现能力,分 5 波连续交付至 100% 对齐 **前置**:v1.1.0 已交付(`adf8778`:模板 + txt/md/docx 导入 + 投稿导出 + 全局灵感) **参考**:`design/readme.md` 全文、`design/ui_pc.html`、v1.1 spec §1.4 推迟项 **目标版本**:v1.2.0 → v1.3.0 → v1.4.0 → v1.5.0 → v2.0.0(五波合一 Master Program) --- ## 1. 背景与目标 ### 1.1 阶段定位 v1.1.0 完成作家日更工具包后,代码库与 `design/readme.md` 仍存在: - **5 处硬占位**(`comingSoon` / placeholder-box) - **v1.1 明确推迟的 9 类能力**(项目包、导出矩阵、时间线、阅读模式等) - **~15 个零代码大模块**(云同步、自动更新、撤销堆栈、扩展 API 等) - **大量 IPC 已有、UI 缺失**(删书、分卷管理、会话归档等) - **部分实现与设计差距**(章节标签、发布日期、模板变量自动填充等) Brainstorming 2026-07-08 用户确认 **方案 A:全量对齐**,包含 Wave 5 平台基建。 ### 1.2 已确认决策 | 维度 | 决策 | |------|------| | 交付策略 | **Master Program 五波连续交付**(非单版本大爆炸) | | 范围 | Waves 1–5 全做,对齐 `design/readme.md` | | 永久排除 | 平台 API 直连投稿(YAGNI) | | 可选排除 | SQLCipher 本地库加密(§12.4 标注可选项,本 Program **不做**) | | 大依赖拆分 | 仿 v1.1 `import-bootstrap`:`pack-bootstrap`(archiver)、`pdf-bootstrap`(puppeteer 或 pdf-lib) | | `.novel` 格式 | 自研 ZIP + `manifest.json` v1,带 `appVersion` 兼容检查 | | PDF 方案 | **Puppeteer** 渲染 HTML → PDF(对齐设计 §11.2.2 页眉页脚);开发/E2E 用 mock 或 skip | | docx 导出 | **docx** npm 包或 HTML→docx 转换 | | 云同步 | WebDAV + 本地目录双模式;AES-256-GCM + PBKDF2 派生密钥 | | 自动更新 | `electron-updater`;开发模式禁用;无代码签名时保留 IPC 通道 | | 扩展 API | **骨架 + 类型 + 注册表 + 文档**;不实现完整插件市场/沙箱加载 | | Skill/MCP | 设置页展示内置 Skill 列表 + MCP 连接器 **配置占位** + 接口类型预留 | | 撤销堆栈 | 每章最多 50 条,存 `undo_stack` 表;与 TipTap History 协同 | | 测试 | 每波补齐 design 对应用例;AI 相关 IT 240s / E2E 300s | ### 1.3 总体验收标准 Master Program 完成后: 1. 代码库中 **无** `feature.comingSoon` 用于真实功能入口(仅文档/关于页说明性文案除外) 2. `design/readme.md` 各章测试表用例 **均有对应 UT/IT/E2E**(PDF/更新/同步可用 mock 或集成桩) 3. 用户可完成:书籍全生命周期管理、项目包备份恢复、多格式导出、连续阅读、时间线、合规检查、云同步、崩溃日志、检查更新 4. README 版本号升至 **v2.0.0** ### 1.4 明确不实现 | 项 | 原因 | |----|------| | 平台后台 API 直连投稿 | 永久 YAGNI | | SQLCipher 数据库加密 | §12.4 可选,复杂度高 | | 完整第三方插件市场 / 动态加载未签名扩展 | Wave 5 仅骨架 | | 崩溃报告上传到远端 API | 保留按钮,调用 stub | | macOS/Linux 代码签名 | 保留渠道,不实施签名 | --- ## 2. 波次规划 ``` Wave 1 (v1.2.0) 基础治理 — 占位清零 + 书籍/章节/分卷/AI 会话 UI 补全 Wave 2 (v1.3.0) 项目包 — .novel / .novel-all 导入导出 Wave 3 (v1.4.0) 导出阅读 — 导出矩阵 + 连续阅读 + 专注/TTS + 驾驶舱补全 Wave 4 (v1.5.0) 创作深化 — 时间线 + 角色弧线 + 敏感词 + AI 文风/附件/骨架 Wave 5 (v2.0.0) 平台基建 — 撤销堆栈 + 云同步 + 日志 + 自动更新 + 扩展 API ``` **依赖**:W1 → W2 → W3;W1 → W4;W2 → W5(同步依赖 .novel);W3/W4 → W5。 --- ## 3. 架构 ### 3.1 进程模型(目标态) ``` ┌──────────────────────────────────────────────────────────────────────────┐ │ 渲染进程 │ │ BookSettingsTab / ReadModeView / TimelineView / CharacterArcTab │ │ ExportModal(扩展)/ ExportAllModal / SyncSettingsTab │ │ FocusMode overlay / TTS controller / StyleMemoryPanel │ │ ExtensionRegistry (types only, dev docs) │ └────────────────────────────┬─────────────────────────────────────────────┘ │ IPC ┌────────────────────────────▼─────────────────────────────────────────────┐ │ 主进程 index.js(核心) │ │ BookRegistry / GlobalSettings / 现有 handlers │ ├────────────────────────────────────────────────────────────────────────────┤ │ 独立 bootstrap chunks(按需 dynamic import) │ │ · import-bootstrap.js (已有) │ │ · pack-bootstrap.js archiver, .novel/.novel-all pack/unpack │ │ · export-bootstrap.js docx, pdf, batch export │ │ · sync-bootstrap.js webdav-client, crypto encrypt │ └────────────────────────────────────────────────────────────────────────────┘ ``` ### 3.2 模块边界(新增) | 模块 | 职责 | 进程 | |------|------|------| | `PackService` | `.novel` / `.novel-all` 打包与解包 | main (pack-bootstrap) | | `ExportMatrixService` | txt/md/docx/pdf/批量 | main (export-bootstrap) | | `ReadModeService` | 拼合卷章节纯文本、虚拟分页元数据 | main | | `TimelineService` | `timeline_events` CRUD、冲突检测 | main | | `ComplianceService` | 词库匹配、导出前扫描 | main | | `CharacterArcService` | 从 knowledge 聚合角色节点 | main | | `StyleMemoryService` | 章节抽样分析文风特征 | main | | `UndoStackService` | 持久化 ProseMirror steps JSON | main | | `SyncService` | 加密上传/下载 .novel | main (sync-bootstrap) | | `LogService` | electron-log 初始化、崩溃检测 | main | | `UpdateService` | electron-updater 封装 | main | | `ExtensionRegistry` | 扩展点类型与空注册表 | shared + main stub | ### 3.3 构建配置 `electron.vite.config.ts` 增加入口: - `pack-bootstrap` - `export-bootstrap` - `sync-bootstrap` `rollupOptions.external` 包含:`archiver`、`puppeteer`(或 `pdf-lib`)、`docx`、`webdav`(或自实现 fetch WebDAV)。 `src/main/index.ts` 在 `app.whenReady` 中 **不** 预加载所有 bootstrap;各 handler 首次调用时 `import()` 对应 chunk(与 import 模式一致)。 --- ## 4. 数据模型 ### 4.1 Schema v9(Wave 1–2) **`book_preferences` 扩展**(已有表): ```sql ALTER TABLE book_preferences ADD COLUMN always_show_cockpit INTEGER NOT NULL DEFAULT 0; ALTER TABLE book_preferences ADD COLUMN cover_path TEXT DEFAULT NULL; ALTER TABLE book_preferences ADD COLUMN synopsis TEXT DEFAULT ''; ``` **`chapters` 扩展**(部分列 migrate 已有): ```sql -- 已有: summary, story_time, publish_status ALTER TABLE chapters ADD COLUMN published_at TEXT DEFAULT NULL; ALTER TABLE chapters ADD COLUMN word_count_threshold INTEGER DEFAULT NULL; ``` **`chapter_tags` 新表**(设计 readme 已有 DDL): ```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 ); ``` **`volumes` 扩展**: ```sql -- description 列若不存在则 ADD ``` **`BookMeta`(registry JSON)扩展**: ```typescript interface BookMeta { // 已有字段 coverPath?: string | null synopsis?: string } ``` ### 4.2 Schema v10(Wave 4) ```sql CREATE TABLE IF NOT EXISTS timeline_events ( id TEXT PRIMARY KEY, book_id TEXT NOT NULL, -- 冗余便于查询;实际存 book db 内可不存 book_id kind TEXT NOT NULL, -- chapter | event | conflict title TEXT NOT NULL, description TEXT DEFAULT '', story_time TEXT NOT NULL, -- 绝对或相对表达式 chapter_id TEXT, sort_order INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL DEFAULT (datetime('now')), FOREIGN KEY (chapter_id) REFERENCES chapters(id) ON DELETE SET NULL ); ``` > 注:`timeline_events` 存于**每书 SQLite**(与 chapters 同库),非全局库。 ### 4.3 Schema v11(Wave 4) ```sql CREATE TABLE IF NOT EXISTS compliance_words ( id TEXT PRIMARY KEY, word TEXT NOT NULL UNIQUE, builtin INTEGER NOT NULL DEFAULT 0 ); ``` 全局词库可放 `global_settings.json` 的 `complianceWords: string[]`;内置词库用 JSON 文件 `src/shared/builtin-compliance-words.json`。 ### 4.4 Schema v12(Wave 5) ```sql CREATE TABLE IF NOT EXISTS undo_stack ( id INTEGER PRIMARY KEY AUTOINCREMENT, chapter_id TEXT NOT NULL, operation TEXT NOT NULL, timestamp TEXT NOT NULL DEFAULT (datetime('now')), FOREIGN KEY (chapter_id) REFERENCES chapters(id) ON DELETE CASCADE ); ``` ### 4.5 GlobalSettings 扩展 ```typescript interface GlobalSettings { // 已有 complianceCheckEnabled?: boolean syncConfig?: SyncConfig | null customSlashCommands?: { trigger: string; template: string }[] styleMemoryPresets?: StylePreset[] readModeFontTheme?: 'serif' | 'sans' | 'eye-care' readModeDeviceWidth?: 'phone' | 'tablet' | 'desktop' extensionDevMode?: boolean } interface SyncConfig { mode: 'webdav' | 'local-folder' webdavUrl?: string webdavUser?: string localFolderPath?: string schedule: 'manual' | 'hourly' | 'daily' | 'weekly' lastSyncAt?: string | null lastSyncStatus?: 'ok' | 'error' | 'syncing' } interface SubmissionPreset { // 已有字段 sensitiveReplacements?: { from: string; to: string }[] } ``` ### 4.6 `.novel` 包格式 v1 ``` book.novel (ZIP) ├── manifest.json │ { │ "formatVersion": 1, │ "appVersion": "2.0.0", │ "exportedAt": "ISO8601", │ "bookId": "uuid", │ "bookName": "书名" │ } ├── meta.json # BookMeta 快照 ├── book.sqlite # 完整书籍 DB └── attachments/ # 封面等(可选) ``` **`.novel-all` v1**: ``` archive.novel-all (ZIP) ├── manifest.json # bookCount, appVersion, exportedAt ├── global_settings.json └── books/ └── {bookId}/ ├── meta.json └── book.sqlite ``` **导入策略**: - `.novel`:默认新建书(新 UUID),`meta.name` 可冲突时追加后缀 - `.novel-all`:合并导入;`bookId` 冲突时提示跳过/覆盖/新建 - `formatVersion` 不匹配时拒绝并提示升级应用 --- ## 5. Wave 1 — 基础治理(v1.2.0) ### 5.1 书籍设置 Tab 替换 `RightPanel` `book-settings` 占位为 `BookSettingsTab`: - 书名(只读或改 meta)、分类、目标字数、封面路径、简介 - 「每次打开显示驾驶舱」开关 → `book_preferences.always_show_cockpit` - 删书按钮(二次确认)→ `book.delete` - IPC:`book.updateMeta` ### 5.2 分卷管理 - 分卷右键菜单:重命名、删除(章节移入默认卷或一并删除—**默认:禁止删除非空卷,需先移章**) - 分卷简述编辑 - `volume.update` / `volume.delete` UI 接入 ### 5.3 章节管理补全 - 双击章节标题 inline 编辑 → `chapter.update` - 章节删除(右键或图标)→ `chapter.delete` - 章节标签 CRUD + 侧栏按标签筛选 - `summary` / `story_time` 字段:章节属性面板或状态栏入口 - 发布状态切换时,若变为 `published` 写入 `published_at = now()` - 可选每章 `word_count_threshold`;状态栏字数变色(绿/橙规则同 design §5.2) ### 5.4 模板变量 `TemplateQuickCreateModal.buildContext`: - `{outlineItem}`:当前卷中关联 `chapterId` 的大纲条目标题,无则 `''` - `{characterList}`:从 `settings` 中 type=character 且 `setting_chapter_refs` 含当前章(或 POV 角色)拼接名称 ### 5.5 AI 会话 UI `AiPanel` 会话栏增加: - 重命名(inline 或模态) - 归档 / 取消归档(`ai.session.update { archived: true }`) - 导出为 `.txt` / `.md`(主进程写文件对话框) - 删除会话(确认) ### 5.6 快捷键落地 | 快捷键 | 实现 | |--------|------| | `focusMode` Ctrl+Alt+F | 全屏隐藏侧栏/右栏,Esc 退出;`#app.focus-mode` CSS | | `toggleTTS` Ctrl+Shift+R | 朗读当前章选中段落或全文;Web Speech API / 系统 TTS | ### 5.7 用词分析 - 底部「AI 命名建议」→ 打开已有 `NamingCheckModal`(非 comingSoon) ### 5.8 Wave 1 验收 - [ ] 无 Wave 1 范围内 comingSoon - [ ] E2E-TEMPL-05 `{characterList}` 通过 - [ ] 书籍设置/删书/分卷/章删改 E2E 各 1 --- ## 6. Wave 2 — 项目包(v1.3.0) ### 6.1 PackService - `pack.exportBook(bookId, destPath)` → `.novel` - `pack.importBook(filePath)` → newBookId - `pack.exportAll(destPath)` → `.novel-all` - `pack.importAll(filePath, strategy)` → 导入报告 - 进度 IPC:`PACK_PROGRESS { current, total, phase }` - >500MB 导出前估算并确认(§11.2.3) ### 6.2 UI - `HomePage`「导出所有书籍」→ `ExportAllModal` - `ExportModal` 增加「笔临项目包 .novel」选项 - `ImportBookModal` 支持 `.novel` 文件过滤 - 设置页「备份」区:手动导出当前书/全部 ### 6.3 大文件 - 导入 `.novel-all` 显示进度条,支持取消(AbortController) ### 6.4 Wave 2 验收 - [ ] IT-ALL-02:导出 3 书 → 删库 → 导入恢复 - [ ] E2E-ALL-03:主页导出全部 - [ ] E2E:单书 .novel 导出再导入 --- ## 7. Wave 3 — 导出矩阵与阅读(v1.4.0) ### 7.1 ExportMatrixService | 格式 | 范围 | 技术 | |------|------|------| | txt | 章/卷/全书 | 已有 formatter 扩展 | | md | 章/卷/全书 | marked 逆向或模板 | | docx | 章/卷/全书 | docx 库 + 目录 | | pdf | 章/卷/全书 | HTML 模板 + puppeteer | | 投稿复制 | 单章 | 已有 | **导出选项**(模态复选框): - 包含批注/地标 - 标注 AI 生成内容(查 snapshot type=ai) - 历史版本导出为独立文件(可选 zip 内多文件) ### 7.2 连续阅读模式 - 顶栏 👁 → `ReadModeOverlay` 全屏 - 选择当前卷;虚拟 3 章窗口;scroll-snap 翻页 - 设备宽度:360 / 768 / 100% - 字体主题:serif / sans / eye-care(`readModeFontTheme` 持久化) - 分卷右键「阅读模式」 - Esc 退出 ### 7.3 专注模式与顶栏进度 - `focusMode` 快捷键(W1 已有)增加可选环境音效(设置开关,本地 wav) - 顶栏 `dailyWordGoal` 进度细条(与 EditorLayout 状态栏同源 `writingStats`) ### 7.4 驾驶舱补全 - `always_show_cockpit` 书籍偏好生效 - 快速入口「今日大纲任务」:列出 status=pending 且 expected_word_count 的大纲 Top 5 ### 7.5 Wave 3 验收 - [ ] E2E-PDF-01(mock puppeteer 或 headless 短超时) - [ ] E2E-READ-01~03 - [ ] 导出 docx 含目录 IT --- ## 8. Wave 4 — 创作深化(v1.5.0) ### 8.1 故事时间线 - `TimelineView` 模态或侧栏全页;Canvas 或 CSS 时间轴 - 章节 `story_time` 自动出现在轴上;手动添加关键事件 - 相对时间 `+Nd` 解析;角色出生日期来自 `settings.properties.birthDate` - 冲突检测:年龄不一致标红(规则见 design §5.7.1) - 点击跳转章节 ### 8.2 角色弧线简报 - 设定面板 character 类型 → Tab「弧线」 - 聚合 `knowledge_entries` 中该角色 state 变更 + 关联章节 - 驾驶舱角色摘要可下钻 ### 8.3 敏感词合规 - 设置 → 编辑器 → 合规检查开关 - 内置 + 用户词库;编辑器装饰下划线(TipTap Decoration) - `SubmissionPreset.sensitiveReplacements` 导出时替换 - 导出前可选扫描确认对话框 ### 8.4 AI 扩展 | 功能 | 实现要点 | |------|----------| | 文风记忆 §6.3 | 分析选中范围章节 → 特征 JSON → 滑杆 UI → 保存预设 | | 自定义快捷命令 §6.2 | `GlobalSettings.customSlashCommands` + 设置编辑 | | 大纲展开骨架 §6.6 | 大纲项右键「展开为章节骨架」→ AI 生成多章标题+摘要 → 批量 create | | 附件上传 §6.10 | AI 上下文增加 `attachments[]`;文件存 userData/attachments/{bookId}/ | ### 8.5 其他补全 - 引用面板点击展开详情抽屉 - 章节列表悬停预览(首段 + summary) - 分卷/章字数阈值提醒 ### 8.6 Wave 4 验收 - [ ] E2E-TL-01~03 - [ ] 合规词下划线 UT - [ ] 弧线 Tab 有数据时展示节点 --- ## 9. Wave 5 — 平台基建(v2.0.0) ### 9.1 撤销堆栈 - TipTap `editor.on('update')` 防抖写入 `undo_stack`(JSON step) - 启动章时加载最近 50 条;与内存 history 合并策略:**仅持久化 manual 断点或每 N 步** - 超出 50 删最旧 ### 9.2 云同步 - 设置页「备份与同步」Tab:`SyncSettingsTab` - WebDAV:PUT/GET 加密 `.novel`;本地目录:复制加密文件 - 定时:`node-cron` 或 `setInterval`(hourly/daily/weekly) - 状态栏同步图标;冲突时模态三选一(本地/远程/取消) - 首次配置同步密码(≥8 位),密钥不落盘明文 ### 9.3 崩溃报告与日志 - `electron-log` 写 `{userData}/logs/bilin.log`,保留 7 天 - `app.getLastCrashReport` 或标记异常退出;下次启动提示 - 「发送报告」→ stub 记录日志 ### 9.4 自动更新 - `electron-updater`;`feedURL` 来自环境或 package.json publish 配置 - IPC:`update:check` / `update:download` / 事件推送 - 顶栏或状态栏「新版本可用」;开发模式 `BILIN_E2E` 禁用 ### 9.5 扩展 API 骨架 - `src/shared/extension-api.ts`:`BilinExtension` 类型(同 design §15.3) - `src/main/services/extension-registry.ts`:空注册表 + `registerImporter` 等 stub - `docs/extensions/README.md`:贡献者文档 - 设置页「扩展」:列出已声明扩展(dev 模式可从文件夹加载 manifest 校验,**不执行**第三方代码) ### 9.6 Skill / MCP 占位 - 设置 → AI → 内置 Skill 列表(静态 JSON) - MCP 连接器 URL 配置字段 + 测试连接 stub ### 9.7 无障碍与 i18n - 关键模态 `aria-*` 复查;键盘 Tab 顺序 - 首次启动语言默认:读 `app.getLocale()`,非 zh/en 则 zh-CN ### 9.8 Wave 5 验收 - [ ] IT-SYNC-01(WebDAV mock server 或 local-folder) - [ ] UT-LOG-01 - [ ] IT-UPDATE-01(mock feed) --- ## 10. IPC 通道(新增汇总) ```typescript // pack.* PACK_EXPORT_BOOK / PACK_IMPORT_BOOK / PACK_EXPORT_ALL / PACK_IMPORT_ALL / PACK_PROGRESS // export matrix EXPORT_CHAPTER_TXT / EXPORT_VOLUME / EXPORT_BOOK / EXPORT_PDF / EXPORT_DOCX // read mode READ_GET_VOLUME_CONTENT // timeline TIMELINE_LIST / TIMELINE_UPSERT / TIMELINE_DELETE / TIMELINE_CONFLICTS // compliance COMPLIANCE_CHECK_TEXT / COMPLIANCE_GET_WORDS / COMPLIANCE_SET_WORDS // character arc ARC_GET_FOR_CHARACTER // style memory STYLE_ANALYZE / STYLE_GET_PRESETS / STYLE_SAVE_PRESET // undo UNDO_PUSH / UNDO_LIST / UNDO_APPLY // sync SYNC_CONFIGURE / SYNC_RUN / SYNC_STATUS / SYNC_PROGRESS // update UPDATE_CHECK / UPDATE_DOWNLOAD / UPDATE_INSTALL // attachments ATTACHMENT_UPLOAD / ATTACHMENT_LIST / ATTACHMENT_DELETE ``` 所有通道使用现有 `wrap()` + `IpcResult` 信封。 --- ## 11. 测试策略 | 波次 | 新增测试约计 | |------|-------------| | W1 | 8 E2E + 6 UT | | W2 | 4 IT + 3 E2E | | W3 | 6 E2E + 4 UT | | W4 | 10 E2E + 8 UT | | W5 | 4 IT + 3 E2E + 4 UT | **原则**: - 每波合并前 `npm run build && npm run test && npm run test:e2e`(该波新增 spec) - Puppeteer/Updater/WebDAV 测试使用 mock 或 `vitest` 桩,不依赖外网 - 延续 `BILIN_E2E` / `BILIN_E2E_USER_DATA` 模式 --- ## 12. 版本与文档 | 波次 | 版本 | CHANGELOG 要点 | |------|------|----------------| | W1 | v1.2.0 | 书籍设置、删改、模板变量、会话管理、专注/TTS | | W2 | v1.3.0 | .novel / .novel-all | | W3 | v1.4.0 | 导出矩阵、连续阅读 | | W4 | v1.5.0 | 时间线、弧线、合规、AI 文风 | | W5 | v2.0.0 | 同步、日志、更新、扩展 API | 每波更新:`package.json`、`README.md`、Settings 关于页、`design/readme.md` 实施状态表(可选)。 --- ## 13. 实施计划文档 Master Program 拆为 5 份 implementation plan(brainstorming 下一阶段): 1. `docs/superpowers/plans/2026-07-08-bilin-w1-foundation.md` 2. `docs/superpowers/plans/2026-07-08-bilin-w2-project-pack.md` 3. `docs/superpowers/plans/2026-07-08-bilin-w3-export-read.md` 4. `docs/superpowers/plans/2026-07-08-bilin-w4-creative-depth.md` 5. `docs/superpowers/plans/2026-07-08-bilin-w5-platform.md` --- ## 14. Spec 自检(2026-07-08) | 检查项 | 结果 | |--------|------| | TBD/占位段 | 无 | | 内部矛盾 | Wave 依赖与 v1.1 推迟项已对齐 | | 范围 | 大但已拆 5 波;单 plan 可执行 | | 歧义 | PDF 用 Puppeteer;SQLCipher 明确排除;插件不执行第三方代码 | | YAGNI | 平台投稿 API、SQLCipher、远端崩溃上传已排除 |