docs: add P5.2 writing logs and AI knowledge extraction design spec for v0.8.0

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-07 16:42:04 +08:00
parent aa2c7dfed3
commit 72c8e13210
1 changed files with 452 additions and 0 deletions
@@ -0,0 +1,452 @@
+# 笔临 P5.2 写作日志 + AI 知识抽取 设计规格
+
+**版本**：1.0  
+**日期**：2026-07-07  
+**范围**：P5.2 — `writing_logs` 日更追踪 + 驾驶舱热力图/连更 + AI 章节知识自动抽取与审核增强  
+**前置**：P6 AI 知识上下文已交付（v0.7.0，`aa2c7df`）  
+**参考**：`design/readme.md` v1.1 §6.7 / §8 / §9、`docs/superpowers/specs/2026-07-06-bilin-p5-workflow-knowledge-design.md`、`docs/superpowers/specs/2026-07-07-bilin-p6-ai-context-design.md`
+
+**目标版本**：v0.8.0
+
+---
+
+## 1. 背景与目标
+
+### 1.1 阶段定位
+
+v0.7.0 已交付知识半自动推荐与四种 AI 模式注入，但知识库条目仍依赖**手动录入**；驾驶舱缺少日更写作数据（`writing_logs`、热力图、连更），`dailyWordGoal` 仅有设置项未驱动 UI。本阶段（P5.2）补齐 **写作数据闭环** 与 **AI 知识抽取上游**，形成「成章/保存 → 抽取 → 审核 → P6 注入」完整链路。
+
+### 1.2 已确认决策（Brainstorming 2026-07-07）
+
+| 维度 | 决策 |
+|------|------|
+| 交付范围 | **核心包**：`writing_logs` + 热力图 + 连更 + AI 抽取；**不含**番茄钟 / 里程碑徽章 / 预计完本 |
+| 抽取触发 | **成章自动**（默认开）+ 手动「抽取本章」+ 全局 `knowledgeAutoExtract` 开关 |
+| 统计范围 | **当前书籍**：热力图、连更、`dailyWordGoal` 达标均按本书当日净增 |
+| 日更累计 | **保存差分 + 成章补计**：`CHAPTER_UPDATE` 记录净增；`finishChapter` 补计未入账字数 |
+| 重复处理 | **AI 合并建议 + 预填更新**：`suggestedMergeId` + `proposedPatch`；确认后 patch 已有条目或另存为新条目 |
+| 架构 | **方案 2**：全局 `writing_logs` + 每书 `chapter_writing_snapshots` + 独立 `KnowledgeExtractionService` |
+| schema | **v7** 迁移（每书）；全局 `writing_logs.sqlite`（userData） |
+| AI 测试 | 集成/E2E 含抽取时禁止 Mock，走 LM Studio |
+
+### 1.3 验收标准
+
+用户能完成：
+
+1. 编辑章节并保存后，驾驶舱**今日字数**与 **365 天热力图**更新；`dailyWordGoal > 0` 时状态栏进度条反映本书当日进度（绿≥100%，橙≥80%）
+2. 连更天数在驾驶舱展示（仅当 `dailyWordGoal > 0`）；中断后归零
+3. 交互/自动/向导 **成章落盘**后，若 `knowledgeAutoExtract` 开启，知识库「待审核」出现本批 AI 抽取项（含置信度）
+4. 在知识库或章节操作区点击 **「抽取本章」** 手动触发；设置中可关闭自动抽取
+5. 待审核项含 **合并建议** 时，打开预填编辑器；确认后更新已有 `approved` 条目，或选择「作为新条目」
+6. 「全部采纳高置信度」批量通过 ≥ 阈值（默认 0.8）的纯新建条目；含合并建议的条目不自动批量采纳
+7. 采纳后的条目可被 P6 `suggestContext` 推荐并注入 AI 上下文
+
+### 1.4 本规格不实现（明确排除）
+
+| 项 | 归属 |
+|----|------|
+| 番茄钟、7/30/100 天里程碑徽章、达标推送通知 | §8 延后 |
+| 预计完本、写作速度仪表盘、时段热力图 | §9 延后 |
+| 角色弧线简报、Cytoscape 关系图谱 | P6+ / §20.3 |
+| 语义 embedding 检索 | 后续 |
+| 注入历史 / 反向链接 | P6.1 |
+| 导入导出、平台投稿预设 | P7 |
+| 关系「建议」自动写入 `settings` 表 | P6+（本阶段仅 `relationship` 类型知识条目） |
+
+---
+
+## 2. 架构
+
+### 2.1 进程模型
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ 主进程                                                            │
+│  · WritingLogService（userData/writing_logs.sqlite）              │
+│  · ChapterWritingTracker（差分 + 成章补计）                        │
+│  · KnowledgeExtractionService（AiClient + 解析 JSON）               │
+│  · KnowledgeService 扩展（合并 patch、批量高置信度采纳）           │
+│  · CockpitService 扩展（热力图、连更、今日进度）                   │
+│  · chapter.handler / interactive|auto finishChapter 挂钩          │
+└────────────────────────────┬─────────────────────────────────────┘
+                             │ IPC
+┌────────────────────────────▼─────────────────────────────────────┐
+│ 渲染进程                                                          │
+│  · CockpitModal 热力图 + 连更 + 今日进度                          │
+│  · EditorLayout 状态栏日更进度条                                  │
+│  · KnowledgePanel 抽取批次、合并建议 UI、批量高置信度             │
+│  · SettingsPage knowledgeAutoExtract / 置信度阈值                 │
+│  · 章节列表/编辑器「抽取本章」入口                                 │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 模块边界
+
+| 模块 | 职责 | 依赖 |
+|------|------|------|
+| `WritingLogService` | 按 `(date, bookId)` 读写/累加日字数 | 全局 sqlite |
+| `ChapterWritingTracker` | 维护 `chapter_writing_snapshots`，计算 delta | 每书 DB、`WritingLogService` |
+| `KnowledgeExtractionService` | 构建 prompt、调用 AI、解析、落库 pending | `AiClientService`, `KnowledgeRepository` |
+| `KnowledgeService` | 合并 patch、批量采纳、拒绝 | 现有 CRUD |
+| `CockpitService` | 扩展 `WritingStats` 聚合 | `WritingLogService`, `GlobalSettings` |
+
+**原则**：抽取异步不阻塞成章；抽取失败 toast + 可重试；写作追踪同步、轻量。
+
+---
+
+## 3. 数据模型
+
+### 3.1 全局 userData：`writing_logs.sqlite`
+
+```sql
+CREATE TABLE writing_logs (
+  date       TEXT NOT NULL,   -- YYYY-MM-DD，本地时区
+  book_id    TEXT NOT NULL,
+  word_count INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (date, book_id)
+);
+```
+
+由 `WritingLogService` 在 `userDataDir` 管理，与 `books_registry.json` 同级。
+
+### 3.2 每书 schema v7
+
+新文件 `schema-v7.sql`：
+
+```sql
+CREATE TABLE chapter_writing_snapshots (
+  chapter_id            TEXT PRIMARY KEY,
+  logged_word_count     INTEGER NOT NULL DEFAULT 0,
+  finish_supplemented   INTEGER NOT NULL DEFAULT 0,
+  FOREIGN KEY (chapter_id) REFERENCES chapters(id) ON DELETE CASCADE
+);
+
+-- knowledge_entries 扩展列（迁移时 ALTER 或重建后拷贝）
+-- extraction_confidence REAL
+-- merge_target_id       TEXT   -- 建议合并的 approved 条目 id
+-- extraction_batch_id   TEXT   -- 同次抽取 UUID，便于 UI 分组
+```
+
+`migrate.ts`：`CURRENT_VERSION = 7`；v6→v7 对已有 `knowledge_entries` 执行 `ALTER TABLE ADD COLUMN`（三列均可 NULL）。
+
+### 3.3 类型扩展（`src/shared/types.ts`）
+
+```typescript
+export interface WritingDayLog {
+  date: string
+  bookId: string
+  wordCount: number
+}
+
+export interface WritingStats {
+  todayWords: number
+  dailyGoal: number
+  goalProgress: number      // 0–1+，goal=0 时为 0
+  streakDays: number        // goal=0 时为 0
+  heatmap: WritingDayLog[]  // 最近 365 天，含 wordCount=0 的日期
+}
+
+export interface ExtractedKnowledgeItem {
+  type: KnowledgeType
+  title: string
+  content: string
+  importance?: number
+  confidence: number
+  foreshadowStatus?: ForeshadowStatus
+  suggestedMergeId?: string
+  proposedPatch?: Partial<CreateKnowledgeInput>
+}
+
+export interface KnowledgeExtractionResult {
+  batchId: string
+  chapterId: string
+  items: ExtractedKnowledgeItem[]
+}
+```
+
+扩展 `CockpitSummary`：
+
+```typescript
+writingStats?: WritingStats
+```
+
+扩展 `KnowledgeEntry`：
+
+```typescript
+extractionConfidence?: number
+mergeTargetId?: string
+extractionBatchId?: string
+```
+
+扩展 `GlobalSettings`：
+
+```typescript
+knowledgeAutoExtract: boolean           // default true
+knowledgeExtractConfidenceThreshold: number  // default 0.8
+```
+
+---
+
+## 4. 日更追踪
+
+### 4.1 差分算法（`ChapterWritingTracker`）
+
+**`recordDelta(bookId, chapterId, newWordCount)`**（在 `CHAPTER_UPDATE` 成功后调用）：
+
+1. 读取 `chapter_writing_snapshots.logged_word_count`（无则 0）
+2. `delta = newWordCount - logged`
+3. 若 `delta !== 0`：`WritingLogService.addToday(bookId, delta)`（当日累计不低于 0）
+4. 更新 snapshot：`logged_word_count = newWordCount`
+
+**`supplementOnFinish(bookId, chapterId, wordCount)`**（在 `finishChapter` 创建章节后调用）：
+
+1. 若 snapshot 不存在，创建 `logged=0, finish_supplemented=0`
+2. `gap = wordCount - snapshot.logged_word_count`
+3. 若 `gap > 0`：`addToday(bookId, gap)`，更新 `logged = wordCount`
+4. 设 `finish_supplemented = 1`
+
+删除章节时 CASCADE 删除 snapshot；`writing_logs` 历史不回溯修正（接受已知限制）。
+
+### 4.2 连更计算
+
+- 仅当 `dailyWordGoal > 0` 时计算
+- 从今日向前遍历 `writing_logs`（本书），连续天数满足 `word_count >= dailyWordGoal`
+- 今日未达标时 streak 不计入今日（展示为截至昨日的连更）
+
+### 4.3 时区
+
+使用主进程 `Intl` 或 `toLocaleDateString('sv-SE')` 生成本地 `YYYY-MM-DD`，与作者所在系统时区一致。
+
+---
+
+## 5. AI 知识抽取
+
+### 5.1 触发点
+
+| 触发 | 条件 | 行为 |
+|------|------|------|
+| 成章落盘 | `finishChapter` 成功且 `knowledgeAutoExtract` | 入队 `extractForChapter(bookId, chapterId)` |
+| 手动 | `knowledge:extractChapter` IPC | 同上 |
+| 设置关闭 | `knowledgeAutoExtract === false` | 仅手动触发 |
+
+抽取在 `setImmediate` / 微任务队列异步执行，不延长成章 IPC 响应时间。
+
+### 5.2 Prompt 与解析
+
+**输入**：章节标题 + 正文纯文本（`stripHtml`，上限 12000 字，超出截断并注明）+ 本书已有 `approved` 条目标题列表（上限 30 条，供合并判断）。
+
+**输出 JSON 数组**（严格解析，失败重试一次「仅返回 JSON」）：
+
+```json
+[
+  {
+    "type": "foreshadow",
+    "title": "测灵石异常",
+    "content": "入门考核时石头发热，暗示主角特殊灵根",
+    "importance": 4,
+    "confidence": 0.92,
+    "foreshadowStatus": "buried",
+    "suggestedMergeId": null,
+    "proposedPatch": null
+  },
+  {
+    "type": "character",
+    "title": "林远状态更新",
+    "content": "通过入门考核，声望上升",
+    "importance": 3,
+    "confidence": 0.85,
+    "suggestedMergeId": "uuid-of-existing-entry",
+    "proposedPatch": {
+      "content": "已通过入门考核，同门态度由轻视转为敬畏",
+      "importance": 4,
+      "lastMentionChapterId": "<chapterId>"
+    }
+  }
+]
+```
+
+**类型**：五种全做 — `character` / `foreshadow` / `relationship` / `location` / `fact`。
+
+**落库**：每条 → `knowledge_entries`，`status=pending`，`source_chapter_id=chapterId`，`extraction_confidence`，`extraction_batch_id`，`merge_target_id`（若有）。
+
+### 5.3 合并审核 UX（决策 D）
+
+| 场景 | UI |
+|------|-----|
+| 无 `mergeTargetId` | 待审核列表常规展示；采纳 → `approve` |
+| 有 `mergeTargetId` | 卡片标注「建议更新：{目标标题}」；点击打开 `KnowledgeEditorDialog` **预填** `proposedPatch` + 目标条目只读摘要 |
+| 确认更新 | `knowledge:approveMerge` → patch 目标 `approved` 条目，删除或标记本 pending 为 `rejected` |
+| 作为新条目 | 清除 `mergeTargetId`，保留 pending，用户编辑后采纳 |
+
+**批量「全部采纳高置信度」**：仅处理 `mergeTargetId IS NULL` 且 `confidence >= threshold` 的 pending 项。
+
+### 5.4 IPC 新增
+
+| 通道 | 参数 | 返回 |
+|------|------|------|
+| `writing:getStats` | `{ bookId }` | `WritingStats` |
+| `knowledge:extractChapter` | `{ bookId, chapterId }` | `KnowledgeExtractionResult` |
+| `knowledge:approveMerge` | `{ bookId, pendingId }` | `KnowledgeEntry`（更新后的目标） |
+| `knowledge:batchApproveHighConfidence` | `{ bookId, threshold? }` | `number`（采纳条数） |
+
+`CHAPTER_UPDATE` handler 内联调用 `ChapterWritingTracker`（无需新 IPC）。
+
+---
+
+## 6. UI 规格
+
+### 6.1 驾驶舱（`CockpitModal`）
+
+在现有四卡片下方新增：
+
+- **今日进度**：`todayWords / dailyGoal` 文字 + 细进度条（`data-testid="cockpit-today-progress"`）
+- **连更**：`🔥 {streakDays} 天`（`dailyGoal=0` 时隐藏，`data-testid="cockpit-streak"`）
+- **热力图**：Canvas 52×7 格，365 天；颜色深浅按 `word_count` 分档（0 / 1–999 / 1000–2999 / ≥3000）；今天描边高亮（`data-testid="cockpit-heatmap"`）
+
+### 6.2 状态栏（`EditorLayout` `#editor-statusbar`）
+
+当 `dailyWordGoal > 0` 且当前有打开书籍：
+
+- 显示 `今日 1234 / 3000 字` + 迷你进度条
+- CSS class：`goal-met`（≥100%）、`goal-near`（≥80%）
+- `data-testid="status-daily-goal"`
+
+### 6.3 知识库（`KnowledgePanel`）
+
+- 待审核 Tab 顶部：本批抽取分组（按 `extractionBatchId` 折叠，显示来源章节）
+- 条目卡片：置信度徽章、合并建议标签
+- 工具栏：「全部采纳高置信度」`data-testid="knowledge-batch-high-confidence"`
+- 合并项：「查看更新建议」`data-testid="knowledge-merge-review-{id}"`
+
+### 6.4 抽取入口
+
+- 章节列表项右键或编辑器菜单：**「抽取本章知识」** `data-testid="chapter-extract-knowledge"`
+- 知识库工具栏：**「从当前章抽取」**（无选中章时 disabled）
+
+### 6.5 设置（`SettingsPage`）
+
+写作 / AI 分区：
+
+- `knowledgeAutoExtract` 开关 `data-testid="settings-knowledge-auto-extract"`
+- `knowledgeExtractConfidenceThreshold` 数字输入（0.5–1.0，步进 0.05）`data-testid="settings-extract-threshold"`
+
+---
+
+## 7. 错误处理
+
+| 场景 | 处理 |
+|------|------|
+| AI 抽取 JSON 解析失败 | 重试一次；仍失败 toast「抽取失败，请稍后重试」，写 `console.error` |
+| 章节正文为空 | 跳过抽取，toast「章节无内容」 |
+| `suggestedMergeId` 指向已删除条目 | 视为无合并建议，按新建处理 |
+| `addToday` 扣减后当日 < 0 | 钳制为 0 |
+| 成章时抽取进行中 | 允许并行；同章多次抽取生成新 `batchId`，旧 pending 保留 |
+
+---
+
+## 8. 测试
+
+### 8.1 测试 ID
+
+| ID | 层级 | 场景 | 预期 |
+|----|------|------|------|
+| UT-LOG-01 | 单元 | `recordDelta` 保存 +200 字 | 当日 +200 |
+| UT-LOG-02 | 单元 | `recordDelta` 删 100 字 | 当日 -100（不低于 0） |
+| UT-LOG-03 | 单元 | `supplementOnFinish` gap=500 | 当日 +500，`finish_supplemented=1` |
+| UT-LOG-04 | 单元 | 连更 3 天达标 | `streakDays=3` |
+| UT-EXT-01 | 单元 | 解析合法抽取 JSON | 返回 N 条 `ExtractedKnowledgeItem` |
+| UT-EXT-02 | 单元 | 含 `suggestedMergeId` | `merge_target_id` 正确写入 |
+| IT-LOG-01 | 集成 | `CHAPTER_UPDATE` 两次 | `writing_logs` 累计正确 |
+| IT-EXT-01 | 集成 | `extractChapter` 有正文 | 返回 ≥1 pending |
+| IT-EXT-02 | 集成 | `approveMerge` | 目标 `approved` 内容更新 |
+| IT-EXT-03 | 集成 | 抽取 + P6 `suggestContext` | 新采纳条目出现在推荐中 |
+| E2E-LOG-01 | E2E | 写 100 字保存 | 驾驶舱今日字数更新 |
+| E2E-LOG-02 | E2E | 热力图可见 | `cockpit-heatmap` 存在 |
+| E2E-EXT-01 | E2E | 成章后待审核有抽取项 | pending 列表非空 |
+| E2E-EXT-02 | E2E | 手动抽取本章 | 待审核增加 |
+| E2E-EXT-03 | E2E | 合并建议确认更新 | 目标条目内容变化 |
+
+### 8.2 超时
+
+- IT-EXT-01 / IT-EXT-02 / IT-EXT-03：**240s**
+- E2E-EXT-01 / E2E-EXT-03：**300s**
+
+### 8.3 原则
+
+集成/E2E 含 AI 抽取时 **禁止 Mock**，使用 LM Studio 默认配置。
+
+---
+
+## 9. i18n 键（节选）
+
+```json
+"cockpit.todayProgress": "今日 {{current}} / {{goal}} 字",
+"cockpit.streak": "连更 {{days}} 天",
+"cockpit.heatmap": "写作热力图",
+"status.dailyGoal": "今日 {{current}} / {{goal}}",
+"knowledge.extractChapter": "抽取本章知识",
+"knowledge.extractFromCurrent": "从当前章抽取",
+"knowledge.batchHighConfidence": "全部采纳高置信度",
+"knowledge.mergeSuggest": "建议更新：{{title}}",
+"knowledge.approveMerge": "确认更新",
+"knowledge.saveAsNew": "作为新条目",
+"knowledge.extracting": "正在抽取知识…",
+"knowledge.extractFailed": "知识抽取失败，请稍后重试",
+"settings.knowledgeAutoExtract": "成章后自动抽取知识",
+"settings.extractThreshold": "高置信度阈值"
+```
+
+---
+
+## 10. 文件映射
+
+| 文件 | 职责 |
+|------|------|
+| `src/main/db/schema-v7.sql` | snapshots + knowledge 扩展列 |
+| `src/main/db/migrate.ts` | v7 迁移 |
+| `src/main/db/repositories/writing-log.repo.ts` | 全局 writing_logs CRUD |
+| `src/main/db/repositories/chapter-writing-snapshot.repo.ts` | 每书 snapshot |
+| `src/main/services/writing-log.service.ts` | 日更累加、连更、热力图数据 |
+| `src/main/services/chapter-writing-tracker.service.ts` | 差分 + 补计 |
+| `src/main/services/knowledge-extraction.service.ts` | AI 抽取 |
+| `src/main/services/knowledge-extraction-prompt.ts` | prompt 构建 + JSON 解析 |
+| `src/main/services/cockpit.service.ts` | 扩展 WritingStats |
+| `src/main/ipc/handlers/writing.handler.ts` | `writing:getStats` |
+| `src/main/ipc/handlers/knowledge.handler.ts` | 抽取/合并 IPC |
+| `src/main/ipc/handlers/chapter.handler.ts` | 挂钩 tracker |
+| `src/renderer/components/cockpit/WritingHeatmap.tsx` | Canvas 热力图 |
+| `src/renderer/components/cockpit/CockpitModal.tsx` | 扩展布局 |
+| `src/renderer/components/knowledge/KnowledgePanel.tsx` | 批次/合并 UI |
+| `tests/main/writing-log.test.ts` | UT-LOG-* |
+| `tests/main/knowledge-extraction.test.ts` | UT-EXT-* / IT-EXT-* |
+| `e2e/writing-logs.spec.ts` | E2E-LOG-* |
+| `e2e/knowledge-extraction.spec.ts` | E2E-EXT-* |
+
+---
+
+## 11. Spec Coverage Checklist
+
+| design/readme 要求 | 本规格 |
+|--------------------|--------|
+| §6.7 每章自动抽取 + 审核 | §5 |
+| §6.7 合并/忽略/批量采纳 | §5.3 |
+| §8 writing_logs + 热力图 + 连更 | §3–§4、§6.1 |
+| §8 番茄钟/里程碑 | 排除 §1.4 |
+| §9 驾驶舱内嵌分析 | 热力图 + 今日进度（轻量） |
+| P5 延后「AI 抽取」 | 本阶段交付 |
+| P5 延后 writing_logs | 本阶段交付 |
+| P6 知识注入上游 | §5 + IT-EXT-03 |
+
+---
+
+## 12. 版本与 DoD
+
+- `package.json` → **0.8.0**
+- `README.md` 功能概览追加 P5.2 一行
+- `SettingsPage` about 版本号更新
+- `npm run build && npm run test && npm run test:e2e` 全绿
+- LM Studio 集成测试按 §8.2 超时执行
+
+---
+
+*本规格为笔临 P5.2 子项目。角色弧线、关系图谱、导入导出等各自在后续 spec 中增量修订。*