docs: add P6 AI knowledge context integration design spec for v0.7.0

Define semi-auto knowledge retrieval, unified AiContextBuilder injection across all four AI modes, and systemPrompt fix for writing flows. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-07 14:19:56 +08:00
parent b33d2e7b34
commit b5ae04af18
1 changed files with 389 additions and 0 deletions
@@ -0,0 +1,389 @@
+# 笔临 P6 AI 知识上下文整合 设计规格
+
+**版本**：1.0  
+**日期**：2026-07-07  
+**范围**：P6 — 已审核知识库条目半自动推荐 + 用户确认 + 注入四种 AI 入口（对话 / 交互 / 自动 / 向导）  
+**前置**：P5 作家工作流 + 知识库 MVP 已交付（v0.6.0，`b33d2e7`）  
+**参考**：`design/readme.md` v1.1 §6.1 / §6.5 / §6.7、`docs/superpowers/specs/2026-07-06-bilin-p5-workflow-knowledge-design.md`
+
+**目标版本**：v0.7.0
+
+---
+
+## 1. 背景与目标
+
+### 1.1 阶段定位
+
+v0.6.0 已交付知识库 MVP（手动 CRUD、审核、伏笔追踪）与作家工作流，但 `AiContextBuilder` 仍仅支持章节/大纲/设定/灵感四类手动勾选，**知识条目未参与任何 AI 调用**。交互/自动/向导写作流还存在技术债：`contextJson` 只存标题拼接的短摘要，而非完整 `systemPrompt`。
+
+本阶段（P6）交付 **知识上下文整合**：半自动检索推荐 + 用户勾选确认 + 统一注入四种 AI 模式，对齐 `design/readme.md` §6.1「在每轮对话前检索高重要度知识条目注入」与 §6.5 各写作模式的上下文确认步骤。
+
+### 1.2 已确认决策（Brainstorming 2026-07-07）
+
+| 维度 | 决策 |
+|------|------|
+| 总范围 | **A AI 上下文整合**，v0.7.0 单阶段交付 |
+| 注入策略 | **半自动 + 确认**：系统推荐，用户勾选后注入 |
+| AI 入口 | **四种全做**：对话、交互写作、自动写作、向导模式 |
+| 检索排序 | **重要度 + 章节相关性 + 目标文本匹配**（方案 C） |
+| 对话 UX | **会话级确认 + 发送静默注入**（不在每条消息前弹窗） |
+| 架构 | **方案 1**：`KnowledgeRetrievalService` + 扩展 `AiContextBuilder` |
+| schema | **无 v7 迁移**（纯服务层与 UI 扩展） |
+| AI 测试 | 集成/E2E 含 AI 时禁止 Mock，走 LM Studio |
+
+### 1.3 验收标准
+
+用户能完成：
+
+1. 在 **AI 上下文编辑器** 看到系统推荐的知识条目（带推荐理由），默认勾选 Top 推荐，可手动增删
+2. **对话模式**：保存上下文后发送消息，AI 回复能体现已选知识（如伏笔、角色状态）
+3. **交互写作**：`context_confirm` 步骤展示知识推荐列表；确认后剧情建议/场景生成使用完整上下文
+4. **自动写作**：设定章节目标后确认知识上下文；场景规划与生成携带知识块
+5. **向导模式**：第 4 步「确认知识条目与伏笔」展示推荐列表；策略预览列出将注入的知识标题
+6. 仅 **`approved`** 知识条目参与推荐与注入；`pending`/`rejected` 不可选
+
+### 1.4 本规格不实现（明确排除）
+
+| 项 | 归属 |
+|----|------|
+| 注入历史 / 反向链接（§5.2「被 AI 用作上下文注入的轮次」） | P6.1+ |
+| AI 语义检索 / embedding | 后续 |
+| 知识自动抽取（§6.7 全自动） | P5.2+ |
+| 文风学习 / 风格控制面板（§6.3） | 后续 |
+| `writing_logs`、热力图（§8） | P5.2 |
+| 角色关系图谱 Cytoscape（§7） | P6+ |
+| schema v7 迁移 | 不需要 |
+
+---
+
+## 2. 架构
+
+### 2.1 进程模型
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ 主进程                                                        │
+│  · KnowledgeRetrievalService（打分 + 推荐）                   │
+│  · AiContextBuilderService（扩展 knowledgeIds 块）            │
+│  · KnowledgeService（只读 list approved）                     │
+│  · 各 handler：AI_CHAT / INTERACTIVE_* / AUTO_* / WIZARD_*  │
+│    confirmContext 时 build() → 存 systemPrompt 全文           │
+└───────────────────────────┬──────────────────────────────────┘
+                            │ IPC
+                            │  knowledge.suggestContext
+                            │  ai.buildContext（扩展 preview）
+┌───────────────────────────▼──────────────────────────────────┐
+│ 渲染进程                                                      │
+│  · ContextEditorModal（+知识 Tab + 推荐区）                   │
+│  · KnowledgeSuggestList（共享勾选组件）                       │
+│  · InteractivePanel context_confirm                           │
+│  · AutoPanel goal 后知识确认区                                │
+│  · WizardPanel wizard_context 步骤                            │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 模块边界
+
+| 模块 | 职责 | 依赖 |
+|------|------|------|
+| `KnowledgeRetrievalService` | 对 `approved` 条目综合打分，返回 `ScoredKnowledge[]` | `KnowledgeRepository`, `ChapterRepository` |
+| `AiContextBuilderService` | 合并传统四类 + 知识块 → `systemPrompt` + `preview` | `BookRegistryService` |
+| `KnowledgeSuggestList` | 推荐列表 UI、checkbox、reason badge | 无 IPC，由父组件传 props |
+| `ContextEditorModal` | 五 Tab 编辑 binding；打开时拉 suggest | preload |
+
+**原则**：
+
+- 推荐可忽略，注入以用户最终勾选为准
+- 知识块与传统上下文共享总字符预算
+- 写作流修复：`contextJson` 必须存 `systemPrompt` 全文，禁止仅存标题摘要
+
+---
+
+## 3. 检索算法
+
+### 3.1 输入
+
+```typescript
+interface KnowledgeSuggestOptions {
+  currentChapterId?: string
+  goalText?: string        // 章节目标、大纲描述拼接、用户备注
+  topN?: number            // default 8
+}
+```
+
+### 3.2 候选集
+
+- `status = 'approved'` 的全部 `knowledge_entries`
+- 无 approved 条目时返回 `[]`
+
+### 3.3 打分公式
+
+对每条 entry 计算 `score`（整数，越高越优先）：
+
+| 因子 | 计算 | 上限 |
+|------|------|------|
+| 重要度 | `importance × 20` | 100 |
+| 章节接近度 | 取 `sourceChapterId` 与 `lastMentionChapterId` 中距当前章 `sortOrder` 差值的最小值 `d`；`d=0→30`，`d≤3→20`，`d≤10→10`，否则 0 | 30 |
+| 伏笔加权 | `foreshadow` 且 `buried→25`，`partial→15`，`resolved→0`；非伏笔 0 | 25 |
+| 目标匹配 | `goalText` 与 `title+content` 做简单分词重合（去停用词后），`overlapRatio × 30` | 30 |
+
+`reasons` 数组（供 UI badge，i18n key）：
+
+- `importance ≥ 4` → `knowledge.reason.highImportance`
+- 章节接近度 > 0 → `knowledge.reason.chapterRelevant`
+- `foreshadow` 且 `buried` → `knowledge.reason.foreshadowBuried`
+- 目标匹配 > 0.2 → `knowledge.reason.goalMatch`
+
+按 `score` 降序取 Top `topN`（默认 8）。
+
+### 3.4 默认勾选策略
+
+- 打开上下文编辑器时，推荐区 **默认全选** Top N
+- 合并进 `binding.knowledgeIds`（与用户已有手动选择取并集，去重）
+- 用户取消勾选后立即从 `knowledgeIds` 移除
+
+---
+
+## 4. 上下文构建
+
+### 4.1 `AiContextBinding` 扩展
+
+```typescript
+export interface AiContextBinding {
+  chapterIds: string[]
+  outlineIds: string[]
+  settingIds: string[]
+  inspirationIds: string[]
+  knowledgeIds: string[]   // 新增，默认 []
+}
+```
+
+持久化位置：
+
+- AI 会话：`ai_sessions.context` JSON
+- 写作流：`interactive_flows.context_json` 内 `binding` 字段
+
+### 4.2 知识块格式
+
+```
+【知识·{类型标签}】{title}
+{content 截断至 500 字}
+```
+
+类型标签映射：`character→角色`，`foreshadow→伏笔`，`location→地点`，`relationship→关系`，`fact→事实`。
+
+### 4.3 字符预算
+
+| 限制 | 值 |
+|------|-----|
+| 单条知识 content | 500 字 |
+| 知识区合计 | 4000 字 |
+| 章节块 | 2000 字（现有） |
+| 其它块 | 500 字（现有） |
+| **总 systemPrompt** | 16 × 1024 字（现有） |
+
+裁剪顺序：候选块按 score（知识）或 sortKey（其它）排序，超出总预算时从低优先级移除。
+
+### 4.4 `ContextPreviewItem` 扩展
+
+```typescript
+export type ContextPreviewKind =
+  | 'chapter' | 'outline' | 'setting' | 'inspiration' | 'knowledge'
+
+export interface ContextPreviewItem {
+  kind: ContextPreviewKind
+  id: string
+  title: string
+  excerpt: string
+  charCount: number
+  knowledgeType?: KnowledgeType  // kind=knowledge 时
+}
+```
+
+### 4.5 写作流 `contextJson` 结构（统一）
+
+```typescript
+interface FlowContextPayload {
+  binding: AiContextBinding
+  systemPrompt: string      // build() 完整输出，供 AI 调用
+  contextSummary: string    // UI 短摘要，如「3章·2设定·5知识」
+}
+```
+
+**修复范围**：`InteractiveWritingService.readContextText()`、`auto.handler` 的 `readContextText()` 改为返回 `systemPrompt`，不再仅返回标题拼接。
+
+---
+
+## 5. IPC
+
+### 5.1 新增通道
+
+| 通道 | 参数 | 返回 |
+|------|------|------|
+| `knowledge:suggestContext` | `{ bookId, opts: KnowledgeSuggestOptions }` | `ScoredKnowledge[]` |
+
+### 5.2 变更通道
+
+| 通道 | 变更 |
+|------|------|
+| `ai:buildContext` | binding 含 `knowledgeIds`；preview 含 knowledge 项 |
+| `interactive:confirmContext` | 存 `FlowContextPayload`；`suggestPlots` 用 `systemPrompt` |
+| `wizard:confirmContext` | 同上 |
+| `auto:*`（plan/generate） | 读 `systemPrompt` |
+
+preload / `electron-api.d.ts` 同步扩展。
+
+---
+
+## 6. UI 规格
+
+### 6.1 共享组件 `KnowledgeSuggestList`
+
+- `data-testid="knowledge-suggest-list"`
+- 每行：`checkbox` + 标题 + 类型 + `reason` badge
+- 单项 `data-testid={`knowledge-suggest-${id}`}`
+
+### 6.2 `ContextEditorModal` 扩展
+
+- 新增 Tab：`knowledge`（`data-testid="context-tab-knowledge"`）
+- 顶部 **推荐区**：调用 `suggestContext`；展示 `KnowledgeSuggestList`
+- 下方 **全部 approved 列表**：可手动搜索/勾选（简单 filter 即可）
+- 「刷新推荐」按钮：`data-testid="context-refresh-suggest"`
+- 保存时写入 `session.context` 含 `knowledgeIds`
+
+**goalText 来源**（打开 Modal 时传入 props）：
+
+| 调用方 | goalText |
+|--------|----------|
+| AiPanel | 空（仅章节相关性） |
+| InteractivePanel | 空 |
+| AutoPanel | `chapterGoal` + 勾选大纲 `description` 拼接 |
+| WizardPanel | `chapterGoal` + `styleNote` |
+
+**currentChapterId**：`useBookStore.selectedChapterId`
+
+### 6.3 对话模式（AiPanel）
+
+- 上下文摘要行点击 → Modal（现有）
+- 发送消息：不弹窗；`AI_CHAT` 用最新 binding build 的 `systemPrompt`
+- 摘要行展示知识数量，如「2章·3知识」
+
+### 6.4 交互写作（InteractivePanel）
+
+- `context_confirm` 步骤：
+  - 展示 `KnowledgeSuggestList`（内联，非必须开 Modal）
+  - 「编辑完整上下文」→ Modal
+  - 「确认并开始」→ `confirmContext(binding)` → `suggestPlots`
+- `data-testid="interactive-knowledge-suggest"`
+
+### 6.5 自动写作（AutoPanel）
+
+- `goal_setup` 提交目标后，或 goal 区域下方展示折叠「知识上下文」
+- 展示推荐 + 勾选；`planScenes` 前确保 `confirmContext` 已执行（可自动用 session binding + 推荐默认勾选）
+- `data-testid="auto-knowledge-suggest"`
+
+### 6.6 向导模式（WizardPanel）
+
+- `wizard_context` 步骤：展示推荐列表 + 「编辑上下文」
+- `buildPreview` 返回的 preview 文本追加「将注入知识：…」列表
+- `data-testid="wizard-knowledge-suggest"`
+
+---
+
+## 7. 全局设置（可选扩展）
+
+```typescript
+// GlobalSettings 新增，均有默认值
+knowledgeAutoSuggest: boolean   // default true
+knowledgeSuggestTopN: number      // default 8，范围 3–15
+```
+
+SettingsPage AI 分区或通用分区增加开关（本阶段可仅后端默认值，UI 设置项为 Nice-to-have；若时间紧可 Phase 2 补 UI）。
+
+---
+
+## 8. 测试
+
+### 8.1 测试 ID
+
+| ID | 层级 | 场景 | 预期 |
+|----|------|------|------|
+| UT-CTX-01 | 单元 | 打分：高重要度 + 近章 + 目标匹配 | 得分最高条目排第一 |
+| UT-CTX-02 | 单元 | `build()` 含 knowledgeIds | preview 有 `kind=knowledge` |
+| UT-CTX-03 | 单元 | 知识区超 4000 字 | 按 score 裁剪 |
+| UT-CTX-04 | 单元 | resolved 伏笔 | 分数低于 buried 同重要度条目 |
+| IT-CTX-01 | 集成 | `suggestContext` 有 approved 数据 | 返回 ≥1 条 |
+| IT-CTX-02 | 集成 | `AI_CHAT` | systemPrompt 含 `【知识·` |
+| IT-CTX-03 | 集成 | 交互 confirm → suggestPlots | 使用完整 prompt（240s LM Studio） |
+| E2E-CTX-01 | E2E | 打开上下文编辑器知识 Tab | 推荐列表可见 |
+| E2E-CTX-02 | E2E | 交互 context_confirm | 知识勾选区可见 |
+| E2E-CTX-03 | E2E | 对话发送含知识上下文 | AI 回复非空（300s） |
+
+### 8.2 超时
+
+- IT-CTX-03：**240s**
+- E2E-CTX-03：**300s**
+
+---
+
+## 9. i18n 键（节选）
+
+```json
+"context.tab.knowledge": "知识库",
+"context.refreshSuggest": "刷新推荐",
+"context.knowledgeCount": "{{count}} 条知识",
+"knowledge.reason.highImportance": "高重要度",
+"knowledge.reason.chapterRelevant": "与当前章相关",
+"knowledge.reason.foreshadowBuried": "伏笔待回收",
+"knowledge.reason.goalMatch": "匹配章节目标",
+"interactive.confirmKnowledge": "确认知识上下文",
+"wizard.knowledgeList": "将注入知识"
+```
+
+---
+
+## 10. 文件映射
+
+| 文件 | 职责 |
+|------|------|
+| `src/main/services/knowledge-retrieval.service.ts` | 检索打分 |
+| `src/main/services/ai-context-builder.service.ts` | 扩展 knowledge 块 |
+| `src/main/services/interactive-writing.service.ts` | readContextText 修复 |
+| `src/main/ipc/handlers/knowledge.handler.ts` | suggestContext |
+| `src/main/ipc/handlers/interactive.handler.ts` | FlowContextPayload |
+| `src/main/ipc/handlers/auto.handler.ts` | systemPrompt 读取 |
+| `src/main/ipc/handlers/wizard.handler.ts` | 同上 |
+| `src/main/ipc/handlers/ai.handler.ts` | binding 默认 knowledgeIds |
+| `src/shared/types.ts` | 类型扩展 |
+| `src/shared/ipc-channels.ts` | KNOWLEDGE_SUGGEST_CONTEXT |
+| `src/preload/index.ts` | knowledge.suggestContext |
+| `src/renderer/components/ai/KnowledgeSuggestList.tsx` | 共享 UI |
+| `src/renderer/components/ai/ContextEditorModal.tsx` | 知识 Tab + 推荐 |
+| `src/renderer/components/ai/InteractivePanel.tsx` | context_confirm 知识区 |
+| `src/renderer/components/ai/AutoPanel.tsx` | 知识确认区 |
+| `src/renderer/components/ai/WizardPanel.tsx` | wizard_context 知识区 |
+| `tests/main/knowledge-retrieval.test.ts` | UT-CTX-* |
+| `tests/main/ai-context-builder.test.ts` | UT-CTX-02/03 |
+| `e2e/ai-context.spec.ts` | E2E-CTX-* |
+
+---
+
+## 11. Spec Coverage Checklist
+
+| design/readme 要求 | 本规格 |
+|--------------------|--------|
+| §6.1 知识条目按重要度检索注入 | §3 检索 + §4 构建 |
+| §6.1 上下文预览可删减 | ContextEditorModal 勾选 |
+| §6.5.1 交互上下文确认 | §6.4 |
+| §6.5.3 向导确认知识条目 | §6.6 |
+| §6.7 重要度影响注入优先级 | §3.3 打分 |
+| P5 延后项「知识注入 AI 上下文」 | 本阶段交付 |
+
+---
+
+## 12. 版本与 DoD
+
+- `package.json` → **0.7.0**
+- `README.md` 功能概览追加 P6 一行
+- `npm run build && npm run test && npm run test:e2e` 全绿
+- LM Studio 集成测试按 §8.2 超时执行