已废弃（2026-09-11 批 1 裁决 · 2026-09-12 落地，退役修订） —— 原「已接受（2026-08-18，六轮头脑风暴轮 6 产出；0.5.0 做协议前置构建，V1.0 实装云端）」。
退役依据：前端重设计规格 §9/§10（批 1「删除批」）· 控制方 2026-09-11 裁决。状态词取自 ADR 标准 的状态流转 Proposed → Accepted → (Deprecated | Superseded) 与本目录索引词表：已废弃 =「不再适用，但保留供历史追溯」；取「已废弃」而非「已取代」，因为没有任何新 ADR 取代它（本决策是被撤回，不是被替代）。
本文档保留供历史追溯，不删除（ADR 纪律：被废弃的 ADR 不删除，见 ADR 标准）。
2026-08-18
课堂助手本地提取链路（ASR/OCR/规则重建）存在能力边界（无云端 AI 提取极限文档 L4 层）：手写公式、复杂表格、流程图、图表数据语义等"必须理解才能产生"的信息，纯本地无法还原。
约束：
- 本地优先铁律：用户学习数据不出本机；AI 调用须用户授权且默认关闭；所有云端能力必须有本地兜底
- MVP 成功标准对标通义听悟/讯飞，但竞品模式（全量上传音视频）与本地优先架构冲突
- V1.0 已有云端多模态（Qwen-VL 系）规划，但"全量上传 vs 不上传"之间缺少中间形态
要回答的问题：AI 增强以什么粒度、什么触发条件、什么返回契约接入，才能在保住隐私与成本的同时补齐本地能力边界？
我们将采用补缝式 AI（Gap-filling AI）：本地管线全量运行，只有明确判定为"本地做不了/做不好"的内容块（ai_candidate）才上传云端多模态理解，云端返回与本地块同构的结构化内容，本地直接渲染。分两阶段实施：
- 0.5.0（协议前置构建，REQ-055）：本地失败判定器（版面 unknown 区 / 规则重建失败 / 低置信 / 用户手动）+
ai_candidate块 + 返回协议 schema + mock 适配器（验证渲染链路）+ 配额/缓存/审计骨架；不接云端 - V1.0（实装，REQ-056）：Qwen-VL 接入、用户授权（默认关闭）、上传前预览、计费配额、审计 UI
- 块级粒度：上传单块裁剪图 + 最小上下文（前后 ASR 文本，可关）；不上传整段视频/整帧
- 结构化返回：
AiEnhanceResponse { type: table|formula_latex|flowchart|diagram|handwriting|chart_data, content, confidence }；serde 强校验，失败丢弃 AI 结果 - 本地结果保留：AI 是叠加层非替代层；原结果带"低置信/未重建"标记并存（B3"可校对原料"定位）
- 来源标记：AI 产物永远标
ai-enhanced，可辨认；全局"仅本地"视图开关 - 护栏：同图 hash 缓存 / 每日配额 / 超时重试 / 审计日志表
- 优点：AI 理解上下文完整，摘要/问答质量上限最高
- 缺点：违反本地优先铁律（整段音频/画面出机）；按分钟计费长期成本高；隐私暴露面最大
- 适用场景：无隐私顾虑的轻度用户——与本项目定位冲突，否决
- 优点：隐私/成本最优
- 缺点：手写公式/复杂表格/流程图等永远做不好，MVP 对标"市场级"（通义听悟/讯飞）存在质量缺口
- 适用场景：严格离线环境——作为降级路径保留
- 优点：隐私暴露面缩小几个数量级（单块裁剪图 + 最小上下文）；成本按块计费而非按分钟；触发点收敛（本地失败块）；离线降级自然（AI 失败→本地结果照常渲染）；协议先行可 mock 验证产品假设
- 缺点：判定器质量决定体验上限（误判→多余上传/漏判→补缝失败）；AI 块与本地块质量参差需来源标记
- 适用场景：本地优先架构下的"AI 为增强层"定位
- 唯一同时满足三条铁律（数据不出本机 / AI 默认关闭用户授权 / 离线降级）的形态
- 与 L1-L4 能力分层自洽：L4 语义层"必须理解才能产生"的信息，用最小必要数据换取
- 0.5.0 协议前置的成本低（无云端依赖），且能提前验证"用户对 AI 块的接受度、触发率"产品假设
- V1.0 实装只是"填适配器"，协议与渲染链路已由 mock 验证，改动面收敛
- 补上"技能自学"真实高频场景（手写板书、白板公式、复杂图表）的能力缺口
- 上传数据量比竞品模式小 2-3 个数量级（块 vs 全片），隐私叙事成立
- 产物体系统一：AI 块与本地块同构，渲染器单一处理路径
- 判定器 + 协议 + mock + 护栏骨架的开发成本（0.5.0 约 1 个里程碑）
- 前端渲染器必须先升级（LaTeX/表格/图集）才能渲染 AI 返回结构
- 同页笔记混排本地块与 AI 块，需来源标记与"仅本地"视图
- 判定器误判 → 阈值可配置 + 用户逐块拒绝并"记住拒绝"（D1 回路）
- 上传块可能含敏感信息（代码密钥/会议白板）→ 上传前预览 + 全局开关 + 默认关
- 网络依赖 → AI 失败降级为本地结果 + "AI 增强待网络"占位，永不阻断
- 0.5.0：判定器决策矩阵单测；协议 schema 校验（合法/非法响应）；mock 适配器 → 产物块合并单测；配额/缓存/审计骨架存在性检查；云端按钮显示"V1.0 开放"
- V1.0：真实 Qwen-VL 接入后对照测试（同块 AI 结果 vs 本地结果的结构化程度）；用户授权流程审计；上传内容最小化检查（无整段音频/整帧）
- ADR-009: OCR 推理 GPU 卸载（本地推理后端可配，AI 补缝不改变本地推理栈）
- ADR-006: 会话段派生视图（产物块引用原料、可重算的地基，V1.0 内优先排期）
- 头脑风暴：视频类型 × 提取优化（轮 6，[ ] 已归档）
- 头脑风暴：无云端 AI 的内容提取极限
- v0.5.0 版本计划（M8 补缝前置 / 七、远期规划）
「补缝式 AI」这一具体形态退役：块级 ai_candidate 判定器 · 上传协议 schema 与 mock 适配器 · 三条前置 IPC 命令（scan_ai_candidates / ai_enhance_mock / ai_enhance_status）· ai_judge 判定器模块。
落地于批 1（删除批，规格日期 2026-09-11 / 提交日期 2026-09-12），逐条可复现：
| 事实 | 实测（2026-09-12） | 复现命令 |
|---|---|---|
| 注册命令总数 | 312（334 → 312；本批共删 22 条，其中补缝三连 3 条） | node scripts/check-command-registry.mjs → ✅ 命令注册一致：定义 312 / 注册 312 / 重复 0 |
| 被删命令名（全批 22 条） | ai_enhance_mock · ai_enhance_status · scan_ai_candidates + 另 19 条 |
对 e96ab63d（批 1 开工前）与 HEAD 各取 app/src-tauri/src/app_commands.rs 的 generate_handler! 清单，按 scripts/check-command-registry.mjs 的官方逐行解析口径做集合差；探针 .superpowers/sdd/2026-09-11-frontend-redesign-batch1-deletions/tmp/diff-registry.js（未入库）→ before=334 after=312 removed=22 added=0 |
| 被删模块/符号（补缝面） | ai_judge.rs（158 行，整文件）· ai_judge_tests.rs（139 行 / 9 用例）· ai_mock_tests.rs（7 用例）· AiMockAdapter::enhance · ai_protocol.rs 的 AiEnhance* 半边（AiEnhanceRequest/AiEnhanceResponse/AiResponseContent/AiNode/AiRequestType 等 8 符号 + 10 用例） |
git diff --name-status --diff-filter=D e96ab63d HEAD · git grep -nF AiEnhance -- app/ → 只剩持久化来源标记 BlockSource::AiEnhanced（不是协议类型） |
| 主提交 | fd9dd8f9 chore(rust): 删补缝三连及连带死模块与协议半边（10 文件 +22 / −904） |
git show --stat fd9dd8f9 |
| 本 ADR 的修订史 | 仅 2 次提交（0a4dabf0 创建 / 1cbb56bf 归档搬移）⇒ 本次退役是它自创建以来的第一次实质修订（"从未被实质修订"这一主张因此可查） |
git log --oneline -- docs/adr/ADR-010-gap-filling-ai.md |
| 仍然活着的替代通道 | review_text_filter / text_filter_status（REQ-085 文本复核）仍注册；ai_protocol.rs 现为 TextFilter* 单一协议；ai_mock.rs 仍在（review_text 离线 mock） |
git grep -nF TextFilter -- app/src-tauri/src/ai_protocol.rs · Select-String -Path app/src-tauri/src/app_commands.rs -Pattern 'review_text_filter' |
- 宿主特性已下线：本决策的渲染宿主「产物视图」在 v0.11.5 已删除 ⇒
ai_candidate块与AiEnhanceResponse的渲染链路没有消费端。（批 1 Task 3 随后删掉整个产物子系统：commands_artifacts.rs/artifact_templates*.rs/narrative_detect*.rs。） - 能力已被更好的通道覆盖：本地失败块的「文本侧」由 REQ-085 文本复核（
review_text_filter/text_filter_status，活）承载；「图像侧」由 ADR-023 的精修图片理解承载；二者都不依赖ai_candidate判定器。 - 从未实装且不再排期：V1.0 云端实装（REQ-056）从未开工，规格 §9 已把三条命令归入「删」。
下列条款继续有效，其出处仍在本文档（因此其他 ADR 对本 ADR 的引用不失效、不悬空）：
- 本地优先：数据不出本机；本地结果永远保留（AI 是叠加层而非替代层）。
- AI 默认关闭 + 用户授权：任何上传必须用户显式授权，上传前可见、可拒绝。
- 必须有本地降级路径：云端不可用/未授权/超配额 ⇒ 回退纯本地结果，永不阻断主链路（现由
review_text_filter的降级链与ai_refine_task的纯文本降级承载）。 - 上传最小化：只传完成本次理解所必需的最小内容（现由精修切片与文本复核批次承载）——ADR-023 的图片授权契约是它在图像侧的扩展。
- 凭据与隐私：密钥走 DPAPI 凭据库（ADR-016），审计留痕（
ai_guardrails，现服务活着的精修/文本复核链路）。
⇒ 本 ADR 退役 ≠ 本地优先红线放松。红线全文见 AGENTS.md §4 与规格 §3；引用本 ADR 的 ADR-016 / 017 / 021 / 023 / 026 / 027 / 028 / 029 / 030 引用的是上述仍然生效的条款（另 ADR-033 的「登记」节与本目录索引已同步为「已废弃 / 批 1 已落」）。
计划原文曾把 ai_protocol.rs 的 AiEnhance* 半边登记为「未随本批删除的残留，给批 8」；该判断已被控制方 2026-09-12 裁决推翻 —— 半边与 TextFilter 半边已物理切开并随 fd9dd8f9 一起删除 ⇒ 本决策「判定器 / 协议 / mock / 三命令」这一面的在码残留为 0。不在删除面内、因此仍然存在的只有 artifact.rs 的持久化来源标记 BlockSource::AiEnhanced（历史数据的格式契约，不可删，与协议类型无关）。