bing/bilin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
64da95f7e1779edea5c6298730e1d060ee6886c9
bilin/docs/superpowers/specs/2026-07-07-bilin-p6-ai-context-design.md
T
bing b5ae04af18 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

15 KiB
Raw Blame History

笔临 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 输入

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 扩展

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 扩展

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 结构（统一）

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. 全局设置（可选扩展）

// 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 键（节选）

"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 超时执行
Reference in New Issue View Git Blame Copy Permalink