Skip to content

v0.8.0.md

Latest commit

 

History

History
121 lines (93 loc) · 19.8 KB

v0.8.0.md

File metadata and controls

121 lines (93 loc) · 19.8 KB
Raw

v0.8.0 — 第八阶段：AI 接入——会话→笔记精修 + 知识补充 + 信任基建

状态: 开发中（2026-08-19 头脑风暴完成，范围已收敛；M0 验收总清为用户主导前置（REQ-146），代理侧已按用户裁决先行启动代码建设——M1 AI 使能层（REQ-138/139/140）、M2 会话→笔记 AI 精修（REQ-141/145 + REQ-143 基础版）、M3 知识补充（REQ-142）、M4 版本管理 + 成本完整（REQ-144 + REQ-143 完整）均已交付；M5 契约测试（REQ-147）与端到端验收待后续轮次） 目标: 打通"AI 为增强层"的第一条用户可见能力线——用 SiliconFlow（硅基流动）API 对 ASR 结果做去非知识内容 + 结构化的笔记精修（会话转笔记时规则/AI 双模式可选），并提供知识补充入口（深度/广度）与余额查询；配套密钥管理、授权审计、成本透明、git 式版本管理四块信任基建，把 AI 从 v0.6.0 REQ-085 的"实验开关"升级为"用户功能"。 关联: 头脑风暴 v0.8 AI 精修（[ ] 已归档） · ADR-010（AI 为增强层·本地兜底铁律）· REQ-085（既有 AI 管道：适配器/护栏/提示词/审计骨架）· REQ-025（AI 笔记精修云端部分提前兑现）· 需求池 v0.8.0 · REQ-055（AiEnhance 协议/判定器/护栏复用）· ADR-016（密钥凭据存储 DPAPI 裁决）

一、阶段目标

  1. AI 使能层（REQ-138~140）：密钥管理 UI + Windows Credential Manager 安全存储（明文红线）；余额查询与展示（含成本确认弹窗内联）；授权默认关 + 上传说明 + 审计可见化（REQ-085 骨架 → 用户可见）
  2. 会话→笔记 AI 精修（REQ-141）：转笔记提供规则/AI 双模式——AI 模式 = note_filter 本地草稿 → 云端结构化精修（去非知识内容 + 层级组织）→ diff 预览 → 落库；失败降级纯规则输出（不丢不假）
  3. 知识补充入口（REQ-142，可选能力）：深度（概念展开/步骤补全/例子补全）+ 广度（前置知识/进阶方向/横向关联/对比辨析/实践建议/资源推荐）九子项；深度就近插入、广度聚合扩展区（混合落位）；"AI 补充·非课程内容·需核实"信任标注
  4. 成本与生成体验（REQ-143/145）：精修/补充前 token 预估 + 费用确认（弹窗内联显示当前余额）；成本落库；余额不足拦截引导；生成异步任务化（切片进度/完成通知/失败保留+重试）——禁止同步阻塞
  5. git 式版本管理（REQ-144）：notes_versions 快照链（source 标记：本地规则/AI 精修/AI 补充/用户编辑）+ 任意两版段级 diff + 回滚（不破坏历史）+ 版本时间线——核心提供可回溯能力，"重新生成"从覆盖变为新版本
  6. M0 验收总清（REQ-146）：v0.5.0 M9 / v0.6.0 M7 / v0.7.0 M4 / v0.7.1 四版真机验收系统执行 + 缺陷清零——AI 线不盖在未验收地基上

本版本不做：AI 问答（REQ-024）、补缝式 VLM 实装（REQ-056，仍 V1.0）、AI 闪卡生成、AI 周报/速览、笔记编辑器大改、闪卡系统、段落级"对这段补充"（锚点接口预留）、多轮追问、跨笔记知识检索、分支/合并版本管理、逐会话成本报表 UI、前端 Vitest 全量基建。

二、范围（需求追溯）

REQ 内容 验收要点 规划状态
REQ-138 AI 密钥管理：设置面板密钥输入 + Windows Credential Manager 安全存储（keyring）+ 掩码显示 + 一键连通性验证（余额接口试通）+ 端点/模型可配置（SiliconFlow 默认，OpenAI 兼容） 密钥不落 SQLite/明文文件（安全红线）；重启后可用；错误密钥验证失败有明确提示；环境变量注入保留为开发路径 已排期
REQ-139 余额查询与展示：GET /v1/user/balance（total/grants/topped_up 分项）+ 设置页余额卡片 + 成本确认弹窗内联余额 + 低余额提醒（<¥1） 余额实时可查；确认弹窗可见"当前余额 ××，本次预估 ××"；低余额有提醒 已排期
REQ-140 AI 授权与审计可见化：全局"AI 功能"开关（默认关——授权红线）+ 首次使用授权确认（上传内容说明：仅文本+最小上下文，不上传音视频/图像）+ 审计列表 UI（REQ-085 审计骨架消费：时间/类型/费用/结果） 默认关；授权前任何 AI 调用不可达；审计列表可查可清空 已排期
REQ-141 会话→笔记 AI 精修（规则/AI 双模式）：convert_to_note 增 mode 参数；AI 模式=note_filter 草稿 → AiRefine 协议（去非知识内容+结构化层级）→ diff 预览（本地版为基线，AI 变化点高亮）→ 采纳/放弃 → 落库；按档案提示词模板（12 档案分组）；失败降级纯规则输出；单条转换可选 AI，批量保持规则 双模式产出可对比；AI 版结构（标题层级/段落/术语/重点）优于规则版；降级路径单测（无密钥/超配额/网络失败/超时 → 纯规则原样）；单测：协议校验/mock 全链路/提示词 golden 已排期
REQ-142 知识补充入口：深度 D1 概念展开/D2 步骤补全/D3 例子补全 + 广度 B1 前置知识/B2 进阶方向/B3 横向关联/B4 对比辨析/B5 实践建议/B6 资源推荐；AiEnrich 协议（一次批量返回块数组）；混合落位（深度就近插入引用章节+锚点溯源、广度聚合笔记尾部扩展区）；信任标注（"AI 补充·非课程内容·需核实"徽标+可折叠）；B6 仅推荐标题不输出链接（防幻觉）；补充块可整体删除 九子项按勾选产出；深度块可溯源到原文段（锚点强校验）；广度块与课程内容物理隔离+徽标；B6 响应无链接（schema 校验）；删除无残留 已排期
REQ-143 成本机制：精修/补充前 token 预估 + 费用确认（首次必显、可"记住此选择"）+ 弹窗内联余额（REQ-139 消费）+ 成本落库（token/费用/模型/操作）+ 余额不足拦截引导（充值/切免费档模型/跳过） 预估与实际偏差可接受（记录对比）；拦截引导三出口可用；成本逐条落库 已排期
REQ-144 笔记版本管理（git-like）：notes_versions 快照表（content/source/parent_id/created_at/meta{ai_cost,model,enrich_kinds}）；每次变更（转笔记/AI 精修/AI 补充/手动保存/回滚）=新版本，线性历史；每笔记上限 50 版超限合并最旧；任意两版段级 diff；回滚=内容=旧版的新版本；笔记详情页版本时间线面板 快照链完整（迁移兼容旧笔记：首个快照=当前内容）；diff 高亮正确；回滚不破坏历史链；50 版上限生效；手动保存也产生版本 已排期
REQ-145 AI 生成异步任务交互：任务状态机（进行中/成功/失败）+ 长笔记按章节切片（每片≤8000 字，并发 2-3，按片进度）+ 完成通知 + 失败保留本地版 + 原因提示（未授权/网络/余额/配额四类）+ 重试入口 长会话精修不阻塞 UI（30s+ 无感）；切片进度可见；部分失败可单独重试；无"卡死"体验 已排期
REQ-146 多版本真机验收总清（M0 前置）：v0.5.0 M9 / v0.6.0 M7 / v0.7.0 M4 / v0.7.1 验收清单系统执行 + 缺陷清零 + 干净基线 四版验收清单逐项执行记录；发现缺陷登记即修；未通过不启动 AI 开发 已排期
REQ-147 AI 链路契约测试：AiRefine/AiEnrich 协议 schema 强校验（非法响应丢弃回退）；mock 适配器全链路（沿用 ai_mock.rs 模式）；降级路径四类（无密钥/超配额/网络失败/超时）；提示词模板 golden 冒烟回归（固定样本断言结构不漂移）；前端无 Vitest 基建维持真机手动清单 契约/降级/golden 三类测试齐备；提示词改动有回归护栏 已排期

注：REQ-085 的适配器/护栏/审计骨架全部复用——ai_text_filter.rs 模式泛化为共享 AI client（REQ-138 落地后环境变量路径保留为开发后门）；prompts/ 目录扩展 note_refine.json / note_enrich.json 模板。

三、技术方案

M0 验收总清 + 基线（REQ-146，未通过不启动开发）

  • 四版本真机验收清单系统执行（用户主导，代理辅助记录）：v0.5.0 M9（档案/版面/专项 OCR/图片/产物/补缝前置）、v0.6.0 M7（提取纯度/融合/画面/音频/性能/会话体验，含 REQ-085 AI 复核三态判定真机）、v0.7.0 M4（信任/存储/类型/信号/平台）、v0.7.1（管理台/批量/互跳/事件刷新）
  • 发现缺陷登记 tech-debt → 即修批次 → 干净基线（git tag 基线点）
  • v0.7.1 发布收尾：CHANGELOG + 版本文档状态更新

M1 AI 使能层（REQ-138/139/140）

  1. 密钥管理（REQ-138）：设置页"AI 服务"卡片——密钥输入（掩码）+ 保存到 Windows Credential Manager（keyring crate spike 前置；spike 失败则 DPAPI 直写 fallback）+ 一键"测试连接"（调余额接口验证密钥有效性）+ 模型/端点可配（默认 https://api.siliconflow.cn/v1，模型默认档见开放问题）；保留环境变量注入（开发路径，优先级：环境变量 > 凭据库）
  2. 余额查询（REQ-139）：ai_balance.rs 新模块——GET /v1/user/balance（Bearer 密钥）→ {total_balance, grants_balance, topped_up_balance, currency}；超时+重试沿用适配器模式；设置页余额卡片（含刷新）+ 低余额阈值常量可配；前端余额展示组件
  3. 授权与审计（REQ-140）：全局开关（设置页 + 状态持久化，默认关）；首次触发 AI 功能的授权对话框（上传内容说明：仅转写文本与最小上下文，音视频/图像永不上传——本地优先铁律）；审计 UI 消费 REQ-085 AiAuditEntry 缓冲（列表 + 清空）；上传前预览（"将发送 N 段文本至 SiliconFlow"）已有雏形随 REQ-141 完整化
  4. 共享 AI client 抽取：ai_client.rs（够用抽象，非平台化）——base_url/api_key/model 配置聚合 + 请求/重试/超时模板 + 审计/配额/缓存挂钩；ai_text_filter.rs 与新增 ai_note_refine.rs/ai_enrich.rs 共用

M2 会话→笔记 AI 精修（REQ-141/145 + REQ-143 基础版）

  1. 转笔记双模式（REQ-141）：convert_to_note/session_to_note 管线加 NoteMode { Rule, AiRefine }——Rule 保持现状（行内一键、批量默认）；AI 模式在笔记预览视图（REQ-081）与单条转换入口提供选择；AI 模式流程：note_filter 草稿（已有）→ 切片（REQ-145）→ AiRefineRequest { content, profile, glossary, chapters } → 云端返回结构化 Markdown 块数组 → 强校验 → diff 预览 → 用户采纳/放弃
  2. 协议与提示词：ai_protocol.rs 扩展 AiRequestType::NoteRefine + NoteRefineResponse { sections: [{heading, blocks: [{type: paragraph|list|term|highlight|quote, content, anchor_ref?}]}] }；prompts/note_refine.json（按档案分组模板：网课=讲义式/实操=步骤式/口播=摘要式/访谈=问答式/会议=纪要式 + 扩展类回退讲义式）；提示词核心指令：去非知识内容（寒暄/废话/重复） + 层级结构化 + 不增补课程外事实（精修=整理不是创作——与知识补充严格区分）
  3. 异步任务基建（REQ-145）：ai_task.rs 任务状态机（Pending/Running(SliceProgress)/Succeeded/Failed(reason)）+ 切片（按章节，每片 ≤8000 字，并发 2-3，配额计数并发安全）+ 前端任务卡片（进度/完成通知/重试按钮）+ 失败原因四类映射（未授权→引导授权/网络→重试/余额→引导充值/配额→明日再试）
  4. 成本确认基础版（REQ-143 前置）：触发前按字符数估算 token → 费用 = token×单价（模型单价表可配）→ 确认弹窗（首次必显 + 内联余额）→ "记住此选择"偏好持久化
  5. 降级链：AI 不可用/超配额/无授权 → 纯规则结果原样输出（不丢不假）+ 明确提示原因（不静默降级）

M3 知识补充（REQ-142）

  1. 入口：笔记详情页「✨ 知识补充」按钮（与精修语义分开：精修=处理已有内容，补充=生成新内容）→ 子项勾选面板（深度 3 + 广度 6，记忆上次选择）→ 成本预估确认 → 异步任务
  2. 协议：AiEnrichRequest { note_content, selected_kinds, profile } → AiEnrichResponse { blocks: [{kind, anchor_ref?, heading, content, confidence}] }；一次批量返回全部选定子项（省请求）；schema 强校验（kind 枚举/锚点必须引用真实段 id/内容非空/B6 块 content 禁止 URL 模式——防幻觉约束）
  3. 落位（混合式）：深度块按 anchor_ref 就近插入引用章节之下（引用风边框 + "AI 展开"徽标 + hover 显示引用原句）；广度块聚合到笔记尾部"扩展区"（前置知识/进阶/关联/对比/实践/资源各自成节 + "AI 补充·非课程内容·需核实"徽标 + 整体可折叠）；渲染器支持两种落位与标注样式
  4. 删除与重补：补充块可整体删除（无残留）；重补=新版本（REQ-144 消费）；不强制先精修（本地版可用标题粗锚点）
  5. 切片复用：长笔记按章节切片（REQ-145 基建复用），锚点跨片校验（引用全局段 id）

M4 版本管理与成本完整（REQ-144 + REQ-143 完整）

  1. notes_versions 表（REQ-144）：(id, note_id, content, source: rule|ai_refine|ai_enrich|user_edit, parent_id, created_at, meta JSON)；迁移兼容旧数据（旧笔记首快照=当前内容，parent NULL）；写路径：所有变更入口统一走 versioned 保存（转笔记/精修采纳/补充采纳/手动保存/回滚）
    • 实施注记（2026-08-21）：回滚新版本的 parent 取最新版本（线性链语义：每个新提交 parent=HEAD，git-like）而非目标版本——"parent=目标版本"会使 v1 出现两个子版本、破坏"线性历史"验收口径；回滚语义（content=目标版本、source=user_edit、历史链不破坏）不受影响。
  2. diff 与回滚：段级 diff（markdown 分块比较，纯函数可单测）；回滚=新版本（content=目标版本内容，source=user_edit 标记，parent=目标版本）——历史链不破坏；每笔记 50 版上限，超限合并最旧两版（保留 meta 摘要）
  3. 版本时间线 UI：笔记详情页版本面板（列表：时间/source 徽标/费用）+ 两版对比视图（采纳/回滚按钮）
  4. 成本完整（REQ-143）：成本记录表（note_ai_usage：操作类型/token 输入输出/费用/模型/切片数）落库；余额不足拦截完整（预估后校验余额 → 拦截 + 三出口引导）；预估与实际偏差记录（校准单价表）

M5 测试与发布（REQ-147）

  • 契约测试：AiRefine/AiEnrich schema 校验（合法/非法响应）；mock 适配器全链路（ai_mock.rs 扩展）；降级四路径单测；提示词 golden 冒烟（固定样本断言输出结构，防漂移）
  • 版本管理单测：快照链/上限合并/diff/回滚（AAA + 边界）
  • 密钥与余额：凭据库 roundtrip（mock 层）；余额解析容错（字段缺失/汇率单位）
  • 前端：构建通过 + 真机手动验证清单（异步任务/双模式/diff/时间线/审计/余额）
  • 端到端：一条真实会话走通"转笔记(规则) → AI 精修 → 知识补充 → 版本对比 → 回滚"全链

四、验收标准

  • 使能层：密钥安全存储（非明文落库）+ 重启可用 + 错误密钥明确报错；余额可查可展示（设置页 + 确认弹窗内联）；全局开关默认关、授权前不可达、审计可查
  • 精修：规则/AI 双模式产出可对比；AI 版去噪+结构化生效（对照样本）；失败四路径均降级纯规则且原因可见；diff 预览采纳/放弃正确
  • 补充：九子项勾选产出；深度块可溯源、广度块隔离+徽标；B6 无链接（schema 保证）；删除无残留
  • 成本：预估/确认/拦截/引导闭环；成本逐条落库；弹窗显示余额
  • 生成体验：长笔记精修不阻塞 UI；切片进度可见；失败可重试；无"卡死"感知
  • 版本：快照链完整；diff/回滚正确；50 版上限生效；手动保存入版本；重新生成不再覆盖
  • 验收总清：四版本验收清单执行记录齐备、缺陷清零、干净基线
  • 回归：v0.7.1 验收项不劣化；cargo test + cargo clippy 全绿；前端构建通过

五、里程碑

步骤 内容 产出
M0 四版本真机验收总清（REQ-146）+ v0.7.1 发布收尾（用户主导） 干净基线（未通过不启动）
M1 AI 使能层（REQ-138/139/140） 密钥管理（DPAPI）/余额查询/授权审计 + 共享 AI client —— ✅ 已交付（2026-08-21，代理侧）
M2 会话→笔记 AI 精修（REQ-141/145 + REQ-143 基础版） 双模式转笔记/diff 预览/异步任务/成本确认 —— ✅ 已交付（2026-08-21，代理侧）
M3 知识补充（REQ-142） 九子项补充/混合落位/信任标注 —— ✅ 已交付（2026-08-21，代理侧）
M4 版本管理 + 成本完整（REQ-144 + REQ-143 完整） 快照链/diff/回滚/时间线/成本落库 —— ✅ 已交付（2026-08-21，代理侧）
M5 测试与发布（REQ-147 + 端到端验收） v0.8.0（待推进）

六、开放问题 / 风险

  • 精修/补充模型选型（spike 前置）：REQ-085 免费档（DeepSeek-R1-0528-Qwen3-8B，¥0/M）做三态判定够用，但笔记精修/补充质量存疑——固定样本对比免费档 vs 付费质量档（Qwen3-235B-A22B / DeepSeek-V3-0324，价格实测定档）；默认档先免费验证，质量不达标切质量档；模型可配置零代码改动
  • Credential Manager 集成（已裁决，ADR-016）：keyring crate 因本机 TLS 拦截（新依赖下载失败）跳过 spike，直接采用 DPAPI 直写 fallback（windows crate 既有依赖 Win32_Security_Cryptography，零新增依赖）——密钥加密存 ai_credentials.bin，环境变量 > 凭据库优先级
  • 切片并发 vs 每日配额：并发切片计数与 DailyQuota 原子性——需并发安全改造（现有计数器非并发）
  • 广度补充幻觉：B3/B4/B6 是模型外部知识——标注"需核实" + B6 无链接约束 + 建议质量档；golden 冒烟含广度样本
  • 版本表膨胀（已裁决实施）：全量快照 × 50 版上限——超限合并最旧两版（删最旧 + 次旧 meta 追加 merged_from 摘要），磁盘占用有界；实测体积校准随真机验收
  • 验收总清体量：四版本清单执行是用户时间大头——按版本分批执行，M0 至少完成 v0.6.0 M7 + v0.7.x 再启动 AI 开发（v0.5.0 M9 可并行）
  • 范围纪律：本版 10 项 REQ 全为新建——按里程碑可裁剪（M4 版本管理可简化上线：先快照链+回滚，diff 视图可后补；M3 广度子项可裁至 B1/B2/B5）

七、明确不做（2026-08-19 头脑风暴裁决）

  • 其他 AI 能力：AI 多轮问答（REQ-024）、补缝式 VLM 实装（REQ-056，Qwen-VL 系仍 V1.0）、AI 闪卡生成（随闪卡系统）、AI 周报/速览（V1.0 闭环轴）
  • 知识补充边界：段落级"对这段补充"（锚点机制保留接口，随 V1.0）、多轮追问（单轮批量）
  • 知识库：跨笔记知识检索/图谱（B3 横向关联仅靠模型自有知识，检索本地库 = V1.0 知识图谱方向）
  • 版本管理边界：分支/合并（复制为副本覆盖）、逐会话成本报表 UI（成本数据已备，UI 待需求）
  • 平台/基建：前端 Vitest 全量基建（只补 Rust 侧契约测试）、共享 AI client 平台化（够用抽象）
  • 笔记本体：笔记编辑器大改（编辑器增强非本版主题）