bing/bilin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a02a665b0f88d0b7bdeaf1aeff26a771c151cd05
bilin/docs/superpowers/specs/2026-07-06-bilin-p5-workflow-knowledge-design.md
T

18 KiB
Raw Blame History

笔临 P5 作家工作流 + 知识库 MVP 设计规格

版本：1.0
日期：2026-07-06
范围：P5 — 驾驶舱 + 更新计划/存稿 + 章间衔接 + 知识库 MVP（手动 CRUD / 审核 / 伏笔追踪）
前置：P4.1 自动/向导写作已交付（v0.5.0，5d3e264）
参考：design/readme.md v1.1 §4.3 / §6.7 / §20.1 / §20.4、design/ui_pc.html #dashboardModal / #bridgeModal / #knowledge

目标版本：v0.6.0

1. 背景与目标

1.1 阶段定位

v0.5.0 已交付四种 AI 写作模式；知识库 Tab 仍为占位（仅命名检查入口），顶栏驾驶舱/章间衔接为 comingSoon。本阶段交付 作家日更工作流 与 知识库 MVP，对齐 design/readme.md §20 作家专项能力，为后续 AI 知识抽取（P5.2+）与 AI 上下文注入（P6）打基础。

1.2 已确认决策（Brainstorming 2026-07-06）

维度 决策
总范围 A 作家工作流 + B 知识库 MVP，统一 v0.6.0 交付（方案 1）
知识库 MVP B：knowledge_entries 手动 CRUD + 审核流 + 地标 foreshadow 同步；不做 AI 自动抽取
驾驶舱 MVP B：现有字数聚合 + publish_status 存稿缓冲 + 快速入口；不含 writing_logs / 热力图 / 预计完本
章间衔接 B：上一章末 + 本章开头文本；LM Studio 可用时追加 AI 建议；离线降级纯文本
架构 schema v6；CockpitService / KnowledgeService / ChapterBridgeService 分层
首次打开书籍 展示驾驶舱一次；日常打开恢复上次编辑位（§4.3）
AI 后端 衔接建议走现有 AiClientService（LM Studio）；集成测试禁止 Mock
测试超时 衔接 AI 集成 240s；E2E 含 AI 300s

1.3 验收标准

用户能完成：

  1. 顶栏打开驾驶舱，查看全书/本卷字数、存稿缓冲、伏笔摘要（已埋/已回收/疑似遗忘）
  2. 在设置中配置更新频率与存稿阈值；章节列表修改 publish_status（草稿/待发布/已发布）；存稿不足时状态栏软性提醒
  3. 新章字数 < 200 时自动弹出章间衔接卡片（可「本章不再提示」）；或从驾驶舱手动触发；LM Studio 可用时看到 AI 衔接建议
  4. 在知识库手动新建/编辑条目，在「待审核」Tab 采纳或拒绝；伏笔类型可标记状态；从地标创建 foreshadow 时可同步为待审核条目
  5. 驾驶舱「处理遗忘伏笔」跳转知识库并筛选疑似遗忘项；命名一致性检查入口保留

1.4 本规格不实现（明确排除）

项 归属
AI 每章自动知识抽取（§6.7 全自动） P5.2+
知识条目注入 AI 写作上下文 P6
writing_logs、365 天热力图、预计完本、番茄钟（§8） P5.2 / §8
角色弧线简报、Cytoscape 关系图谱（§7 / §20.3） P6+
导入导出、平台投稿预设（§11 / §20.2） P7
书籍设置面板「文风控制」（ui 原型占位） 后续

2. 架构

2.1 进程模型

┌─────────────────────────────────────────────────────────────┐
│ 主进程（schema v6）                                          │
│  · KnowledgeRepository / KnowledgeService                    │
│  · CockpitService（只读聚合）                                 │
│  · ChapterBridgeService（文本提取 + 可选 AiClient）           │
│  · ChapterRepository 扩展 publish_status 读写               │
│  · GlobalSettings 扩展 updateSchedule / stockBufferThreshold │
│  · book_preferences（cockpitSeen、bridge 免打扰）            │
└───────────────────────────┬─────────────────────────────────┘
                            │ IPC
┌───────────────────────────▼─────────────────────────────────┐
│ 渲染进程                                                         │
│  · CockpitModal / ChapterBridgeModal                           │
│  · KnowledgePanel（待审核 | 全部 | 伏笔）                        │
│  · ChapterList 发布状态 + StatusBar 存稿提醒                     │
│  · SettingsPage 更新计划                                       │
│  · TopBar 驾驶舱按钮（替换 comingSoon）                          │
└─────────────────────────────────────────────────────────────┘

2.2 模块边界

模块 职责 依赖
KnowledgeService CRUD、审核、批量操作、伏笔统计、遗忘判定 KnowledgeRepository, ChapterRepository
CockpitService 聚合字数、存稿数、伏笔摘要、卷占比 ChapterRepository, KnowledgeService
ChapterBridgeService 提取相邻章片段、生成/缓存 AI 建议 ChapterRepository, AiClientService
KnowledgePanel 列表 UI、编辑对话框、审核操作 useKnowledgeStore
useKnowledgeStore IPC 封装、Tab 筛选状态 preload knowledge.*

原则：驾驶舱只读不写；知识审核后才计入伏笔统计；衔接 AI 失败不阻断文本展示。

3. 数据模型（schema v6）

3.1 迁移

  • CURRENT_VERSION = 6
  • 新文件 schema-v6.sql：
CREATE TABLE knowledge_entries (
    id              TEXT PRIMARY KEY,
    type            TEXT NOT NULL,  -- character/foreshadow/location/relationship/fact
    title           TEXT NOT NULL,
    content         TEXT NOT NULL DEFAULT '',
    importance      INTEGER NOT NULL DEFAULT 3,  -- 1-5
    status          TEXT NOT NULL DEFAULT 'pending',  -- pending/approved/rejected
    foreshadow_status TEXT,  -- buried/partial/resolved (type=foreshadow)
    source_chapter_id TEXT,
    last_mention_chapter_id TEXT,
    linked_bookmark_id TEXT,
    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at      TEXT NOT NULL DEFAULT (datetime('now')),
    FOREIGN KEY (source_chapter_id) REFERENCES chapters(id) ON DELETE SET NULL,
    FOREIGN KEY (last_mention_chapter_id) REFERENCES chapters(id) ON DELETE SET NULL
);

CREATE INDEX idx_knowledge_status ON knowledge_entries(status);
CREATE INDEX idx_knowledge_type ON knowledge_entries(type);

CREATE TABLE book_preferences (
    key   TEXT PRIMARY KEY,
    value TEXT NOT NULL  -- JSON
);

CREATE TABLE chapter_bridge_dismiss (
    chapter_id TEXT PRIMARY KEY,
    dismissed_at TEXT NOT NULL DEFAULT (datetime('now')),
    FOREIGN KEY (chapter_id) REFERENCES chapters(id) ON DELETE CASCADE
);
  • v5→v6 迁移测试：UT-MIG-06

3.2 TypeScript 类型（src/shared/types.ts）

export type KnowledgeType = 'character' | 'foreshadow' | 'location' | 'relationship' | 'fact'
export type KnowledgeStatus = 'pending' | 'approved' | 'rejected'
export type ForeshadowStatus = 'buried' | 'partial' | 'resolved'
export type UpdateSchedule = 'daily' | 'alternate' | 'weekly' | 'none'

export interface KnowledgeEntry { /* 字段与表一致 */ }

export interface CockpitSummary {
  totalWords: number
  volumeWords: number
  stockReadyCount: number
  stockThreshold: number
  foreshadowBuried: number
  foreshadowResolved: number
  foreshadowForgotten: number
  volumeBreakdown: { volumeId: string; name: string; words: number }[]
}

export interface ChapterBridgeResult {
  previousChapterId: string | null
  previousTail: string
  currentHead: string
  aiSuggestion?: string
}

3.3 GlobalSettings 扩展

updateSchedule: UpdateSchedule      // default 'none'
stockBufferThreshold: number        // default 3

publish_status 列已在 migrate v2 尝试添加；本阶段确保 ChapterRepository 读写并在 UI 暴露。

3.4 书籍偏好（book_preferences）

key value 说明
cockpitSeen "true" 首次驾驶舱已展示
openCockpitEveryTime "true" 可选：书籍级「每次打开显示驾驶舱」（默认 false，全局可在后续扩展）

3.5 伏笔「疑似遗忘」判定（MVP）

同时满足：

  1. type = 'foreshadow' 且 status = 'approved' 且 foreshadow_status = 'buried'
  2. 取 last_mention_chapter_id ?? source_chapter_id 对应章节的 sort_order 为 mentionOrder
  3. 全书最大 sort_order 为 latestOrder
  4. latestOrder - mentionOrder >= 20 → 计入 foreshadowForgotten

用户可在编辑条目时更新 lastMentionChapterId 或改为 resolved 以清除遗忘标记。

3.6 地标同步

创建或编辑 bookmark.landmarkType = 'foreshadow' 时，UI 提供 checkbox「同步到知识库」：

  • 调用 knowledge.createFromBookmark(bookmarkId) → 新建 pending 条目，linked_bookmark_id 关联，title 取自地标 label

4. IPC 与 Preload

4.1 通道（src/shared/ipc-channels.ts）

// knowledge
KNOWLEDGE_LIST: 'knowledge:list'
KNOWLEDGE_CREATE: 'knowledge:create'
KNOWLEDGE_UPDATE: 'knowledge:update'
KNOWLEDGE_DELETE: 'knowledge:delete'
KNOWLEDGE_APPROVE: 'knowledge:approve'
KNOWLEDGE_REJECT: 'knowledge:reject'
KNOWLEDGE_BATCH_APPROVE: 'knowledge:batchApprove'
KNOWLEDGE_CREATE_FROM_BOOKMARK: 'knowledge:createFromBookmark'
KNOWLEDGE_STATS: 'knowledge:foreshadowStats'

// cockpit
COCKPIT_SUMMARY: 'cockpit:summary'
COCKPIT_MARK_SEEN: 'cockpit:markSeen'
COCKPIT_SHOULD_SHOW: 'cockpit:shouldShowOnOpen'

// bridge
BRIDGE_GET: 'bridge:get'
BRIDGE_DISMISS: 'bridge:dismiss'
BRIDGE_SHOULD_PROMPT: 'bridge:shouldPrompt'

// chapter 扩展
CHAPTER_SET_PUBLISH_STATUS: 'chapter:setPublishStatus'  // 或合并进现有 update

4.2 Preload 命名空间

knowledge: { list, create, update, delete, approve, reject, batchApprove, createFromBookmark, stats }
cockpit: { getSummary, markSeen, shouldShowOnOpen }
bridge: { get, dismiss, shouldPrompt }

5. 服务层

5.1 KnowledgeService

list(filter?: { status?: KnowledgeStatus; type?: KnowledgeType; forgottenOnly?: boolean })
create(input: CreateKnowledgeInput): KnowledgeEntry
update(id, patch): KnowledgeEntry
delete(id): void
approve(id) / reject(id) / batchApprove(ids[])
createFromBookmark(bookmarkId): KnowledgeEntry
getForeshadowStats(): { buried, resolved, forgotten }
countPending(): number

新建条目默认 status='pending'；用户可在对话框勾选「直接采纳」→ approved。

5.2 CockpitService

getSummary(bookId, activeVolumeId?): CockpitSummary
shouldShowOnOpen(bookId): boolean   // !cockpitSeen
markSeen(bookId): void

字数：stripHtml 后求和现有 chapters.content；不引入 writing_logs。

5.3 ChapterBridgeService

shouldPrompt(chapterId): boolean
  // 本章字数 < 200 && 存在上一章 && 未 dismiss

getBridge(chapterId, withAi?: boolean): Promise<ChapterBridgeResult>
  // previousTail: 上一章 stripHtml 末 300 字
  // currentHead: 本章 stripHtml 前 200 字（有则展示）
  // withAi && AiClient 可用 → chat 单轮建议（240s timeout）

dismiss(chapterId): void

AI Prompt 模板（简体）：

你是连载小说编辑。上一章末尾：「{tail}」。本章开头：「{head}」。用 2–3 句话指出衔接是否顺畅，并给出一个开头方向建议。不要续写正文。

失败时返回无 aiSuggestion，UI 隐藏 AI 区块。

6. 渲染进程 UI

6.1 TopBar

  • 驾驶舱按钮（data-testid="topbar-cockpit"）打开 CockpitModal；移除 comingSoon

6.2 CockpitModal（对齐 #dashboardModal）

data-testid 元素
cockpit-modal 根 overlay
cockpit-total-words 全书总字数
cockpit-volume-words 本卷字数
cockpit-stock-count 存稿 ready 数
cockpit-foreshadow-summary 伏笔摘要行
cockpit-resume-edit 回到上次编辑
cockpit-bridge-check 检查章间衔接
cockpit-forgotten-foreshadow 跳转知识库筛选

打开书籍时：若 cockpit.shouldShowOnOpen → 自动弹出并 markSeen。

6.3 ChapterBridgeModal（对齐 #bridgeModal）

data-testid 元素
bridge-modal 根
bridge-previous-tail 上一章末尾
bridge-current-head 本章开头
bridge-ai-suggestion AI 建议（可选）
bridge-dismiss-checkbox 本章不再提示
bridge-start-writing 开始写作

触发：EditorLayout 在 openChapter 后若 bridge.shouldPrompt → 延迟 500ms 弹出（避免与加载冲突）。

6.4 KnowledgePanel（替换 placeholder）

布局：

  1. 工具栏：「新建条目」「命名一致性检查」（保留）
  2. 摘要条：伏笔统计（同 cockpit）
  3. Tab：待审核 | 全部 | 伏笔
  4. 列表项：类型图标、标题、重要度星、来源章、状态标签
  5. 点击 → KnowledgeEditorDialog（标题、类型、内容、重要度、伏笔状态、关联章）
data-testid 元素
knowledge-panel 根
knowledge-tab-pending / -all / -foreshadow Tab
knowledge-new 新建
knowledge-item-{id} 列表项
knowledge-approve-{id} 单条采纳
knowledge-batch-approve 批量采纳待审核

6.5 章节发布状态

  • 章节列表项右键或状态图标循环：draft → ready → published
  • data-testid="chapter-publish-{id}"

6.6 StatusBar 存稿提醒

  • 当 stockReadyCount < stockBufferThreshold 且 updateSchedule !== 'none' → 显示橙色提示文案（不阻断）
  • data-testid="status-stock-warning"

6.7 SettingsPage

  • 更新频率下拉：updateSchedule
  • 存稿阈值数字输入：stockBufferThreshold（1–20，默认 3）

6.8 i18n

新增键：cockpit.*、bridge.*、knowledge.*、publish.status.*、settings.updateSchedule.*、stock.warning

7. 错误处理

场景 行为
无上一章时 bridge shouldPrompt=false；手动打开显示「无上一章」
AI 建议超时/失败 仅展示文本片段；toast 可选「AI 建议不可用」
删除已关联 bookmark 的 knowledge 保留条目，linked_bookmark_id 置 null
空知识库 cockpit 伏笔 显示 0，不报错
publish 更新失败 IPC 错误 toast

8. 测试

8.1 单元 / 集成（Vitest）

ID 场景 AI
UT-MIG-06 v5→v6，knowledge_entries 存在 —
UT-KNOW-01 CRUD + approve 后 status 正确 —
UT-KNOW-02 遗忘判定：sort_order 差 ≥20 —
UT-KNOW-03 createFromBookmark 创建 pending —
UT-COCK-01 getSummary 字数与存稿计数 —
UT-BRIDGE-01 提取 tail/head 长度正确 —
IT-BRIDGE-01 getBridge 含非空 aiSuggestion 240s LM Studio
IT-KNOW-04 批量 approve 后 pending 清零 —

vitest.config.ts 保持 fileParallelism: false。

8.2 E2E（Playwright）

ID 场景 超时
E2E-COCK-01 打开驾驶舱，统计卡片可见 30s
E2E-COCK-02 首次开书自动弹驾驶舱，二次不再自动 30s
E2E-PUB-01 章节改 publish_status 为 ready，cockpit 存稿 +1 30s
E2E-KNOW-01 新建 → 待审核 → 采纳 → 列表可见 30s
E2E-KNOW-02 地标 foreshadow 同步知识库 30s
E2E-BRIDGE-01 新章触发衔接 modal，文本非空 30s
E2E-BRIDGE-02 衔接含 AI 建议（LM Studio） 300s
E2E-STOCK-01 存稿低于阈值，status bar 警告可见 30s

9. 文件清单（实现参考）

文件 职责
src/main/db/schema-v6.sql 新表
src/main/db/repositories/knowledge.repo.ts 数据访问
src/main/services/knowledge.service.ts 业务 + 遗忘判定
src/main/services/cockpit.service.ts 聚合
src/main/services/chapter-bridge.service.ts 衔接 + AI
src/main/ipc/handlers/knowledge.handler.ts IPC
src/main/ipc/handlers/cockpit.handler.ts IPC
src/main/ipc/handlers/bridge.handler.ts IPC
src/renderer/components/cockpit/CockpitModal.tsx UI
src/renderer/components/bridge/ChapterBridgeModal.tsx UI
src/renderer/components/knowledge/KnowledgePanel.tsx 重写
src/renderer/components/knowledge/KnowledgeEditorDialog.tsx 编辑
src/renderer/stores/useKnowledgeStore.ts 状态
tests/main/migrate-v6.test.ts 迁移
tests/main/knowledge.repo.test.ts CRUD
tests/main/cockpit.service.test.ts 聚合
e2e/cockpit-knowledge.spec.ts E2E

10. Definition of Done（v0.6.0）

  • schema v6 迁移 + 类型 + IPC + preload
  • KnowledgeService + Panel 完整 CRUD / 审核
  • CockpitModal + 首次打开逻辑
  • ChapterBridgeModal + 自动/手动触发 + AI 建议
  • publish_status UI + 存稿提醒 + updateSchedule 设置
  • 全量测试通过（含 LM Studio IT-BRIDGE-01 / E2E-BRIDGE-02）
  • README / SettingsPage 版本号 → 0.6.0

11. Spec Self-Review

检查项 结果
Placeholder 扫描 无 TBD；排除项见 §1.4
内部一致性 驾驶舱不依赖 writing_logs；伏笔统计仅 approved
范围 单 spec 可支撑一份 implementation plan
歧义 遗忘阈值固定 20 章；存稿阈值默认 3；MVP 不做 AI 抽取

本规格为笔临 P5 子项目。AI 知识抽取、writing_logs 热力图等在 P5.2+ spec 中增量修订。

Reference in New Issue View Git Blame Copy Permalink