bilin/docs/superpowers/specs/2026-07-07-bilin-p6-ai-context-design.md

# 笔临 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 超时执行