From b5ae04af18a436a8ac5577730cb21dd92325a9ab Mon Sep 17 00:00:00 2001 From: kun1h Date: Tue, 7 Jul 2026 14:19:56 +0800 Subject: [PATCH] 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 --- .../2026-07-07-bilin-p6-ai-context-design.md | 389 ++++++++++++++++++ 1 file changed, 389 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-07-bilin-p6-ai-context-design.md diff --git a/docs/superpowers/specs/2026-07-07-bilin-p6-ai-context-design.md b/docs/superpowers/specs/2026-07-07-bilin-p6-ai-context-design.md new file mode 100644 index 0000000..e2b9ccf --- /dev/null +++ b/docs/superpowers/specs/2026-07-07-bilin-p6-ai-context-design.md @@ -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 超时执行