bing/bilin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9f2b1ae3e0bec21f202d51f69cc92402c773acb5
bilin/docs/superpowers/specs/2026-07-08-bilin-master-completion-design.md
T
bing cc97c66d6f docs: add master completion design spec for full design/readme alignment 
Define five-wave Master Program (v1.2 through v2.0) covering foundation UI, project packs, export/read modes, creative depth features, and platform infrastructure per brainstorming option A.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-08 14:18:01 +08:00

22 KiB
Raw Blame History

笔临 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 扩展（已有表）：

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 已有）：

-- 已有: 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）：

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 扩展：

-- description 列若不存在则 ADD

BookMeta（registry JSON）扩展：

interface BookMeta {
  // 已有字段
  coverPath?: string | null
  synopsis?: string
}

4.2 Schema v10（Wave 4）

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）

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）

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 扩展

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 通道（新增汇总）

// 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<T> 信封。

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、远端崩溃上传已排除
Reference in New Issue View Git Blame Copy Permalink