DevFlow/docs/02-架构设计/功能决策记录-归档.md

功能决策记录 — 归档

从 功能决策记录.md 归档的条目——纯实现流水、老 Sprint 决策、UX 微调、已被取代或合并的细节。这些条目在「3 个月回看是否仍影响系统/功能设计理解」判断下已不再需要常驻主文档，但完整保留以备回溯。

创建：2026-06-14 | 性质：归档只读，不再维护更新

归档判断标准

• 一次性代码审查流水（甄别落地、骨架删除、列表查询过滤）
• UX 微调（工具卡片折叠、对话滚动、错误友好化、空白屏修复）
• 实现细节（参数解析抽函数、token 记录策略、model 追溯）
• 老 Sprint 决策已被新设计取代或合并

其中架构级结论已提炼一句留在主文档对应小节，归档条目为细节展开。

---

一、AI Chat 上下文窗口与并发控制 [任务 #43 系列]

主文档保留一句架构结论：ContextManager 类型替换为 messages 真相源 + 双层 Semaphore 并发控制（全局 3 / 单对话 2）。以下为实现细节归档。

ContextManager 接线方式：类型替换而非 Wrapper [任务 #43]

• 决策：AiSession.messages 字段类型从 Vec<ChatMessage> 直接改为 ContextManager，后者成为消息的唯一持有者（内含 Vec<TrackedMessage> + token 缓存 + 裁剪能力）。不引入 Wrapper 包装层。
• 原因/取舍：Wrapper 方案下 Vec 是真相、ContextManager 是临时视图——每次 build_for_request 都要 clone 给 ContextManager，token 缓存永远滞后一轮或每次重建（双重复制）。类型替换让 push 即刻更新 token 计数、零额外 clone、单一数据源。代价是 save_conversation 等需全量的场景要显式调 all_messages_clone()（多一行但语义明确）。13 处操作点中 6 处签名不变（push/clear）、4 处微调（clone→all_messages_clone/iter）、2 处需重写。
• 状态：✅ 已落地（2026-06-13，cargo check + vue-tsc 通过，待 tauri dev 实测）

Token 计数方案：字符粗估零依赖 [任务 #43]

• 决策：用 chars_count × 0.35 粗估单条消息 token 数（~2.8 字符/token），每条消息 +4 token 固定开销（role 标记），每个 tool_call +30 token（JSON 结构）。不引入 tiktoken-rs 或任何 tokenizer 依赖。
• 原因/取舍：用途是「发送前判断是否超限」做预算控制，误差 ±15% 完全可接受；tiktoken-rs 引入 BPE 数据文件约 5MB，对 Tauri 桌面应用打包不友好；provider 返回的 usage 可用于事后校准闭环暂不实施（原 calibrate 方法未接线，Review 时已删，留待未来按 provider usage 重做）。chars_ratio=0.35 对中英混合文本偏保守（纯英文 ~0.25，纯中文 ~0.5-0.7），宁可多算不少算。
• 状态：✅ context.rs 已落地（2026-06-13，校准闭环暂缓）

淘汰算法：分组滑动窗口 + 三元组保护 [任务 #43]

• 决策：超预算时从最旧消息开始按「淘汰单元」丢弃。Standalone 消息单独成单元；Assistant(tool_calls) + Tool(result)* + Assistant(final_text) 工具调用三元组作为原子整体要么全保留要么全丢弃。最后 6 条消息（≈2 个完整用户轮次）设为保护区永不淘汰。
• 原因/取舍：工具调用三元组若拆散会导致 LLM 看到工具调用但找不到对应结果（或反之），产生幻觉重复调用。保护区防止丢失即时上下文。替代方案是直接按消息数截断（简单但破坏三元组），或按 token 截断到某位置（可能从三元组中间切断）。分组滑动窗口在安全性和信息保留间取平衡。
• 状态：✅ 已落地（2026-06-13）

裁剪时机：build_for_request 时裁剪，push 不触发 [任务 #43]

• 决策：token 预算检查和消息裁剪仅在 build_for_request() 构建请求时执行。push() 只做追加+计缓存，不做任何淘汰。
• 原因/取舍：Agentic Loop 一轮执行中会多次 push（assistant 回复 → tool_result → 可能再 assistant），这些属于当前活跃轮次的消息绝不能被中途裁剪掉。只在「即将发给 LLM」这个时间点评估并裁剪旧消息，语义清晰且安全。
• 状态：✅ 已落地（2026-06-13）

持久化策略：裁剪仅影响发送视图，DB 存全量 [任务 #43]

• 决策：all_messages_clone() 返回全量未裁剪消息用于 save_conversation 落库；build_for_request() 返回裁剪后版本发给 LLM。两者解耦。
• 原因/取舍：用户切换对话回来期望看到完整历史，不应因自动裁剪而永久丢失。裁剪是临时的「发送时压缩」类似 gzip。未来若要做永久摘要压缩（将旧对话提炼为 summary 消息插入），那是独立 feature 不影响此设计。
• 状态：✅ 已落地（2026-06-13）

多工具调用并行化：join_all 无上限 [任务 #43]

• 决策：process_tool_calls 中 Low 风险工具收集后用 futures::future::join_all 并行执行，Med/High 审批工具仍串行（需用户交互）。工具执行本身不限并发数（本地操作）。
• 原因/取舍：LLM 一次返回 N 个独立工具调用（如同时读 3 个文件）时，串行执行 = O(N×T)，并行 = O(T)。N=3 时节省 ~600ms/轮。工具执行是本地 I/O（read_file/grep 等），无外部限流风险故不加 Semaphore。仅 LLM 调用受并发控制。
• 状态：✅ 已落地（2026-06-13）

LLM 并发控制：双层 Semaphore [任务 #43]

• 决策：AppState 新增 LlmConcurrency（封装两个双层 Arc<Mutex<Arc<Semaphore>>>——全局并发默认 3 / 单对话默认 2）。permit 在 3 个叶子 LLM 调用点 acquire（run_agentic_loop 内 stream_llm 前、generate_title_via_llm、extract_knowledge_from_conversation），作用域结束自动释放；工具执行不受控。LlmConcurrency: Clone（两 Arc，cheap）作为参数串到底，spawn 函数收 by-value move、叶子收 &ref。acquire 顺序固定 global→per_conv，所有调用点一致防死锁。
• 原因/取舍：多对话场景下同时跑 2-3 个对话可能撞 provider RPM 限制导致 429。双层控制：全局防总并发失控，单对话防单对话独占（标题生成 + 主循环 + 提炼并发）。用 Arc<Mutex<Arc<Semaphore>>> 双层包装而非裸 Arc<Semaphore>——tokio Semaphore permits 构造时固定不可增减，替换内层 Arc 即重建，已持有旧 permit 不受影响。permit 放叶子调用点（最接近真实 HTTP 调用）而非 command 入口，限流粒度精准且不阻塞非 LLM 路径。
• 状态：✅ 已落地（2026-06-13）

per_conv 实为应用级单一信号量（非 per-conv map）[任务 #43 / Review 修正]

• 决策：LlmConcurrency.per_conv 字段命名暗示「单对话」并发，但实现是应用级单一 Semaphore（非 HashMap<conv_id, Semaphore>）。当前不修实现，仅在 state.rs 结构体 doc 标注真实语义 + 未来重构路径。
• 原因/取舍：AiSession 为 Arc<Mutex<AiSession>> 单例，且 generating 互斥保证同一时刻仅一个对话的 run_agentic_loop 在跑。故 per_conv 实际退化为「单对话内并发」（主循环 stream_llm + 标题生成 + 知识提炼三者受限流约束）——命名虽宽泛但当前语义恰好正确，非 bug。改 HashMap 是过度设计（单例会话下多 map 项永不被并发访问）。风险留待未来：若支持多对话并发 loop，per_conv 需随之改 HashMap<conv_id, Semaphore> 才名副其实。揭示 LlmConcurrency 与 AiSession 单例的隐式耦合——本次 review 最有价值的发现。
• 状态：✅ 注释留痕（2026-06-13 Review 修正，state.rs 结构体 doc 标注；实现未改，非 bug，多对话路线时重构）

裁剪策略与模型选择正交 [任务 #43 / 架构边界]

• 决策：上下文窗口管理的 ContextConfig 不含 mode/模型选择字段。「高精度/低精度对话」（深度思考/reasoning_effort/模型选择）属于 LLM 调用层参数（CompletionRequest 层面），与裁剪策略（sliding_window / 未来 summarization）是正交维度，不混入 ContextManager。未来摘要压缩作为独立模块实现。
• 原因/取舍：避免把不同层面的控制拧到一个配置对象里——ContextConfig 只管「窗口多大、怎么裁」，模型/推理模式由调用方在构建 CompletionRequest 时决定。职责单一，后续扩展任一维度不影响另一侧。
• 状态：✅ 架构边界已划定（2026-06-13 讨论确认）

save_conversation 异步化 [任务 #43]

• 决策：循环结束时 spawn 异步落库，先释放 generating=false + emit AiCompleted，不阻塞前端收到完成事件。
• 原因/取舍：当前 save_conversation 同步执行（upsert + JSON 序列化），阻塞 Completed 事件几十~几百毫秒。落库失败不影响已完成的结果展示，异步化提升用户感知响应速度。代价是进程崩溃时最后一轮可能未落库（概率极低且下次启动可从 LLM provider 侧无法恢复 anyway）。
• 状态：✅ 已落地（2026-06-13）

build_for_request 只传 token 数值，不传 system_prompt 文本 [任务 #43 / Review 修正]

• 决策：build_for_request(sys_tokens: u32) -> (Vec<ChatMessage>, bool) 只接收 system prompt 的预估 token 数，不接收 &str 文本。system_prompt 的 token 估算在调用方（ai.rs）完成。
• 原因/取舍：职责单一——ContextManager 负责裁剪和消息管理，不需要知道 system prompt 的文本内容。避免每次调用传递可能很长的字符串（含知识库+技能注入后可达几千字符），且 build_for_request 内部不混入估算逻辑。
• 状态：✅ 已落地（2026-06-13）

join_all 不对 tool_calls 做 sort，保留原始 index [任务 #43 / Review 修正]

• 决策：收集 Low 风险工具时保留原始 (index, draft) 元组，不额外 sort_unstable_by_key。LLM 返回的 tool_calls 已按 index 有序，sort 是多余且可能打乱语义顺序。
• 原因/取舍：futures::join_all 保证结果顺序与输入一致，只要输入有序输出就有序。去掉 sort 减少一次 O(n log n) 且避免意外重排。回填 session.messages 时按原始 tool_call_id 匹配即可，不依赖数组位置。
• 状态：✅ 已落地（2026-06-13）

build_for_request 视图裁剪，不 mutate self.messages [任务 #43 / Review 修正]

• 决策：build_for_request(&self) 改不可变借用，超预算时构造裁剪视图返回（self.messages[trim_end..] clone），不 drain 修改自身。删除原会 self.messages.drain(0..trim_end) 的 trim_to_budget 方法。
• 原因/取舍：原 mutate 实现违背「裁剪仅影响发送视图」契约——drain 后 all_messages_clone()（save_conversation 数据源）也返回裁剪版，长对话每轮丢历史、累积性数据丢失。视图裁剪每轮 build 重算 trim_end（O(n) 遍历淘汰单元，n 通常 <50 可忽略），换全量持久化不被破坏。
• 状态：✅ context.rs 已落地（2026-06-13 Review 修正，5 单测通过）

AiSession.messages 类型替换为 ContextManager + 13 处接线 [任务 #43 / Part A 第二块]

• 决策：AiSession.messages 从 Vec<ChatMessage> 直接替换为 ContextManager（类型替换，非 wrapper 包装层）。13 处操作点适配：push/clear/len/iter 签名天然兼容零改动；switch 对话改 restore_from_messages(Vec)；replace_tool_result 自由函数删除改走 ContextManager::replace_tool_result_content 方法（DRY 收敛，方法已含 token 重估）；save_conversation 与 ensure_conversation_title 改 all_messages_clone() 取全量。
• 原因/取舍：类型替换而非 wrapper 层——消息真相源唯一，避免 Vec + ContextManager 双存导致状态分裂；ContextManager 方法签名刻意与原 Vec 操作对齐（push/clear/len/iter），13 处中 6 处零改动，改动面最小。核心改造点 run_agentic_loop 由 session.messages.clone() 全量塞入改为 build_for_request(sys_tokens)：调用方用 TokenEstimator::estimate_text(&system_prompt) 估算 system prompt token，ContextManager 只接收数值不接触 prompt 文本。
• 状态：✅ ai.rs 已落地（2026-06-13，cargo check 通过 + df-ai context 5 单测绿）

裁剪触发时不 emit 前端事件 [任务 #43 / Part A]

• 决策：build_for_request 返回的 trimmed: bool 暂忽略（let (history_msgs, _trimmed) = ...），裁剪发生时不向前端 emit 任何事件。
• 原因/取舍：裁剪是无损优化——内存 all_messages_clone 与 DB 持久化均保留全量历史，仅发送给 LLM 的视图裁掉旧消息。计划原拟用 AiError 通知前端，但 AiError 语义是「错误」，裁剪不是错误会误导用户以为出错；前端无需感知裁剪（对 UX 透明）。未来若需「已压缩早期历史」提示条，新增专用事件（如 AiContextTrimmed）而非复用 AiError。
• 状态：✅ ai.rs 已落地（2026-06-13）

B1 Low 风险工具 join_all 并行 + 串行回填 [任务 #43 / Part B]

• 决策：process_tool_calls 重写——批量发 Started 后，Low 风险工具 futures::future::join_all 并行 execute（闭包内完成即 emit Completed/Error，不持 session 锁），join_all 返回后串行 push tool_result + audit（持锁）。Med/High 审批逻辑不变。
• 原因/取舍：原 for 循环逐个串行 execute，N 个独立 Low 工具 = N 倍等待；并行化总耗时 ≈ 最慢一个。execute + emit 放闭包内（完成即通知前端，体感逐个出结果），push/audit 必须持 session 锁故留 join_all 后串行。join_all 保序——结果顺序 = 输入顺序 = tc_list sort 后的原始 index 顺序，tool_result 回填不乱序。
• 状态：✅ ai.rs 已落地（2026-06-13）

B1 附注：tool_result push 顺序变化无语义影响 [任务 #43 / Part B]

• 决策：Med/High 占位 tool_result 先于 Low 结果 push（分类阶段先处理审批占位，Low 结果 join_all 后回填），与原「按 tc_list 交错顺序 push」不同。
• 原因/取舍：LLM 按 tool_call_id 关联 tool_result，不看消息绝对位置；连续 tool_result 都是 ContextManager 的 ToolResultTail、归同一三元组，顺序不影响语义。两阶段（占位先行 + 结果后填）比交错处理实现简单。
• 状态：✅ ai.rs 已落地（2026-06-13）

B2+B3 正常完成：save/title/extract 打包后台 spawn [任务 #43 / Part B]

• 决策：run_agentic_loop 正常完成段，把 save_conversation + maybe_spawn_extraction + ensure_conversation_title 三者打包进同一 tauri::async_runtime::spawn 后台 task，主流程只做 generating=false + emit Completed。stop 路径（2 处）save 保持同步 await，title 改 spawn_ensure_title 后台。
• 原因/取舍：① 计划原拟裸 spawn save，但 maybe_spawn_extraction 明示「需在 save 之后（读已落库消息）」——裸 spawn save 与 extract 各自独立 task 顺序不保证，extract 可能读到旧 DB；打包同一 task 内 save → extract → title 串行 await 保顺序。② stop 路径 save 保持同步：stop 后用户可能立刻发新消息触发新 loop，两 loop 的 save 并发 upsert 会竞态（读旧值叠加丢 token）；正常完成段同风险但频次低、最多丢少量 token 累加（非功能错误），可接受。③ ensure_conversation_title 签名从 provider: &dyn LlmProvider 改收 provider_config: &AiProviderRecord、内部自建 provider——&dyn 非 'static 无法 move 进 spawn，收 config 克隆进 task 后自建。
• 状态：✅ ai.rs 已落地（2026-06-13；并发场景待实测）

Semaphore 重建采用「软收敛」策略 [任务 #43]

• 决策：用户在 Settings 调整并发上限时，通过 *semaphore = Arc::new(Semaphore::new(n)) 替换整个 Arc 内部值。已持有旧 permit 的任务不受影响，新请求走新限制。缩并发时实际并发 = 旧持有数 + 新上限（软收敛非硬切断）。
• 原因/取舍：tokio Semaphore 的 permits 数只能在构造时设定，运行时无法增减，这是标准限制。替代方案（如用 Mutex+计数器手动实现）复杂度高且易出错。「软收敛」行为可接受——用户调低并发后，进行中的请求不会被中断，只是新请求受控；待旧请求释放后新限制完全生效。UI 可提示「已有 N 个进行中请求」改善体验。
• 状态：✅ 已落地（2026-06-13）

protect_count=6 保护最近约 2 个用户轮次 [任务 #43]

• 决策：淘汰算法保护最后 6 条消息不纳入淘汰单元。依据：每轮典型产生 User + Assistant[±tools] + Tool* ≈ 2~5 条，6 条 ≈ 覆盖 2 个完整轮次。
• 原因/取舍：固定数值简单可靠。不改为动态轮次检测（增加复杂度且轮次边界模糊——Assistant 纯文本 vs 带 tools 的 Assistant 消息算同一轮还是不同轮？）。6 是保守值，宁可多保几条也不要误裁活跃上下文。未来可根据实测调整。
• 状态：✅ 已落地（2026-06-13）

syncConcurrencyConfig 加 debounce 防快速连续 IPC [任务 #43]

• 决策：Settings 页面修改并发数值后，通过 debounce（~300ms）延迟调用 ai_set_concurrency_config IPC，防止快速连续拖动滑块/按键时频繁重建 Semaphore。
• 原因/取舍：@change 在 input[type=number] 上只在失焦时触发已比 @input 好，但用户可能快速点「保存」或连续调整两个值。Semaphore 重建虽轻量（Arc::new）但不该无节制地做。手写简易 debounce（~5 行）即可，不需引入 lodash-es 依赖。
• 状态：✅ 已落地（2026-06-13）

spawn 异步 save_conversation 加 warn 日志 [任务 #43]

• 决策：tauri::async_runtime::spawn(save_conversation_inner) 内部用 if let Err(e) = ... .await 捕获错误并 tracing::warn! 记录，不静默吞掉。
• 原因/取舍：spawn 的 task 错误默认被 tokio 静默丢弃，调试时完全看不到落库失败。加一行 warn 零成本，出问题时能从日志定位。不影响用户体验（warn 不是 error）。
• 状态：✅ 已落地（2026-06-13）

---

二、AI Chat 工具卡片折叠 [Sprint 10 + 2026-06-13]

纯 UX 微调，全部归档。

双层折叠：卡片级 + 内容级分离

• 决策：expandedCards（整卡 body 显隐）与 expandedTools（read_file 代码预览级）两套独立状态。
• 原因：卡片折叠和文件内容预览是两个维度，合并会互相干扰。
• 状态：✅ Sprint 10

running/pending_approval 强制展开

• 决策：执行中、待审批卡片不可折叠，始终展开。
• 原因：用户需看到骨架屏（执行中）和审批按钮（待操作）。
• 状态：✅ Sprint 10

新内容追加自动收起旧卡

• 决策：deep watch messages + 轻量 JSON snapshot diff 检测新内容（新消息 / toolCall 状态变化 / 文本增长）→ 清除旧 completed/rejected 展开态，保留活跃卡。
• 原因：多步调用时旧结果折叠为单行 header，界面紧凑（类 ChatGPT/Cursor）。
• 状态：✅ Sprint 10

首次加载 / 切对话不触发收起

• 决策：isFirst guard，首次 snapshot 赋值后直接 return。
• 原因：防切换对话或初次加载时把当前可见卡片误折叠。
• 状态：✅ Sprint 10

短结果保持展开（审查①）

• 决策：rejected（拒绝原因）/ write_file（写入路径）短结果用 shouldKeepOpen(tc) 强制展开，仅 read_file/list_directory/通用 JSON 大体量结果折叠。
• 原因：短结果折叠无紧凑收益，反隐藏关键信息（拒绝原因/写入路径）。
• 状态：✅ Sprint 10

卡片宽度对齐气泡（审查②）

• 决策：工具卡片 max-width: 90%，与 AI 文本气泡（.ai-msg-bubble max-width 90%）一致，不撑满 content 区。
• 原因：卡片原默认 stretch 撑满 100%、气泡 90%，视觉宽度不一致（list projects 等卡片比回复气泡宽一截）。选限制卡片对齐气泡（非撑满气泡），保留气泡式留白；数据卡片 90% content 宽通常够展示文件树/代码（横向 overflow-x:auto 兜底）。
• 状态：✅ 2026-06-13

折叠态 header 显示结果摘要 [2026-06-13]

• 决策：completed 工具卡片在 header 的 .ai-tool-sub 槽位（原仅 running 显示「执行中...」）追加结果摘要 toolResultSummary(tc)，按工具返回结构提取一句话：list_tasks→「12 项任务」、list_projects→「5 个项目」、list_ideas→「8 条想法」、create_project→「已创建：xxx」、create_idea/task→「已创建：title」、update_project→「已更新 status」、delete_project→「已删除」、run_workflow→「请到工作流页面运行」。.ai-tool-sub 加 ellipsis 截断防长标题撑破。
• 原因：list_tasks/list_projects/list_ideas/run_workflow 等工具无路径参数（不像 read_file/list_directory header 带路径），折叠态 header 仅剩工具名，光秃秃、信息密度低。摘要放 header（非 body）使折叠态也能一眼看到核心信息，不必先展开。list_* 返回裸数组取 .length；create 取 .name（project）/.title（idea/task）——字段不对称是后端 model 既定，摘要层各自适配。
• 状态：✅ 2026-06-13

工具调用前 AI 总结文字去气泡 [2026-13]（已回滚）

• 决策：AI 消息同时含文字 content 和 toolCalls 时，文字气泡加 .ai-msg-bubble--plain（去背景/边框/padding/圆角/max-width）变紧凑纯文本紧贴卡片；纯文字消息（无工具卡片）保留完整气泡。→ 已回滚：恢复所有 AI 消息统一气泡。
• 原因：原想条件去气泡兼顾紧凑与长回复可读性。→ 回滚原因：用户实测后强调「所有 AI 消息都应在气泡里」，条件去气泡造成两种 AI 消息外观（纯文字有气泡、工具总结无气泡）不一致、突兀。紧凑不该靠去气泡实现——牺牲一致性换紧凑得不偿失。未来若要紧凑走「气泡与卡片视觉一体」（卡片纳入气泡 / 连一体块 / 仅压间距）。
• 状态：✅ 2026-06-13 落地 → 🔄 2026-06-13 回滚（一致性优先，布局方案待用户再定）

工具卡片区拆子组件：ToolCard + ToolCardList [2026-06-13]

• 决策：工具卡片区从 AiChat.vue（原 1983 行）拆为两个子组件——ToolCard.vue（单卡纯展示，props: tc/isExpanded/isContentExpanded；emits: toggle/expand-content/approve）+ ToolCardList.vue（列表容器，持有折叠态 expandedCards/expandedTools，defineExpose 出 collapseInactive）。AiChat.vue 仅 import + ref 持有列表 + 转发 @approve→store.approveToolCall。
• 原因/取舍：工具卡片占 AiChat.vue ~650 行（模板 107 + script 150 + CSS 392），是高修改频率区（折叠/摘要/时间轴等 UI 调整频发）。拆出后卡片相关变更隔离在两文件，1983 行主文件不再因 UI 调整反复动。auto-collapse 桥接选 expose+ref（方案 B）而非 prop+emit / provide+inject——前者是 Vue3 标准模式、子组件自治折叠态、父级只调一个 collapseInactive(activeIds)。附带：ToolCard 内用 parsed computed 缓存 parseResult（原模板 6 次重复 JSON.parse，每次 patch 都重解析）；气泡与卡片的 max-width:90% 提取为全局 --df-msg-max-width 变量（原跨文件靠注释维系对齐，改一处忘一处即错位，变量化单一来源）。深化（可维护性）：ToolCard.vue 再拆双 <script> 块——14 纯函数 + ToolResult 类型提模块顶层（只建一次，setup 聚焦 props/parsed），parseResult any→ToolResult|null（防模板字段名打错编译期不报），toolDisplayName 去 i18n fallback（path 几乎总有，属过度防御）。取舍：为可维护性/易迭代，不为微性能（省闭包可忽略）。
• 状态：✅ 2026-06-13 落地（重构 Step 1-5 完成，AiChat.vue 净减 ~650 行）

---

三、AI Chat Token 用量与模型记录 [2026-06-13]

主文档保留一句设计结论：Token 分账本——对话 / 工作流节点 / 标题生成三处独立记账。其余实现细节归档。

流式 token 落库走累加模式（非覆盖）

已移入 经验记录.md「约定」分组。

Anthropic 流式 output_tokens 当累计值直接覆盖

已移入 经验记录.md「约定」分组。

Token 展示默认关闭 + Settings 开关 [2026-06-13]

• 决策：AI 气泡底部 token 条默认不显示，加 df-show-token-usage 开关放 Settings 通用设置区，默认 false。
• 原因：token 是计量信息非核心；用户对「头顶信号」敏感度不一，日常默认隐藏减干扰，需要时开。开关关闭时 store 不写 lastTokenUsage、DOM 不渲染，零视觉干扰。
• 状态：✅ 2026-06-13

前端 token 双状态（单次 + 对话累计）[2026-06-13]

• 决策：store 维护 lastTokenUsage（最近一条回复）+ convTokenTotal（当前对话累计）两个状态，而非单一状态。
• 原因：单状态切对话会错乱——实时值（当前回复产生的 token）vs 历史总值（切回老对话应从 DB 读累计）混一起。双状态各司其职：切换时 convTokenTotal 从 summary 加载、lastTokenUsage 清空。
• 状态：✅ 2026-06-13

model 记录策略：取配置值 + 补填不覆盖 [2026-06-13]

• 决策：记录的 model 取 provider_config.default_model（非 stream 响应解析）；save_conversation insert 时写、update 时仅 rec.model 为 None 才补填。
• 原因：① stream chunk 未必带 model 字段；default_model 是确定配置值且即请求所用（request.model 就用它发），配置名比响应里的具体版本号（如 gpt-4o-2024-xx）对用户更有意义。② model 字段 DB 早存在但老代码 insert 一直填 None，补填兼容历史对话（下次活动自动回填），已有值不覆盖。
• 状态：✅ 2026-06-13

token 分账本：对话 / 工作流节点 / 标题生成 [2026-06-13]

此为设计结论，已在主文档保留一句：三处分属不同成本中心，混进 ai_conversations 会让对话 token 失真。

• 决策：① 对话主流程 token（run_agentic_loop 流式）落 ai_conversations；② 工作流 AI 节点 token 进 NodeOutput.usage（写 node_executions.output_json），不进对话表；③ 标题生成 token 刻意不记（generate_title_via_llm 的 resp.usage 丢弃）。
• 原因：三处分属不同成本中心——工作流节点消耗属工作流执行成本，与对话 token 是两个账本，混进 ai_conversations 会让对话 token 失真；标题生成是系统附带行为（max 30 token，量小），计入对话总量会让用户困惑（「只问一句怎么这么多 token」）。非流式 complete() 的 token Provider 层已返回，仅消费侧按账本分流。
• 状态：✅ 2026-06-13

model UI 展示暂缓，留后续升级 [2026-06-13]

• 决策：model 已落库（ai_conversations.model + 前端 AiConversationSummary.model 字段就绪），但暂不在对话旁展示，留作后续升级项。
• 原因：数据通路已打通（后端写值、前端字段在），展示是纯前端增量、随时可加；当前先把 token 用量展示做稳，model 展示留到后续 UI 升级（如对话头部 / token 条旁）统一考虑，避免零散加。
• 状态：📐 待实施（UI 展示，数据已就绪）

model 追溯：消息级 + 对话级多值（C+B）[2026-06-13]

• 决策：消息级 ChatMessage 加 model 字段（每条 assistant 消息记生成它的 model）+ 对话级加 models 字段（JSON 数组，去重存对话用过的所有 model）。model 单值字段保留存首个（兼容已就绪的前端字段 + 补填不覆盖策略不动）。
• 演进：[2026-06-13 初版 📋] 现状为对话级单值 + 补填不覆盖，中途切换只留首个、消息级无字段无法追溯 → [2026-06-13 同日落地] 用户拍板 C+B。A（对话级覆盖记最近）未选——中途历史仍丢；纯 C 不便快速看「用过哪些」，加 B（对话级聚合）互补。
• 原因：「每一条对话都能有效记录」需消息级追溯（每条 assistant 消息知道谁生成）；对话级 models 聚合便于不解析整条 messages 就知用过哪些（中途切换场景全覆盖）。model 单值保留是渐进兼容（前端 AiConversationSummary.model 已就绪，展示首个），不强删避免迁移破坏。
• 落地细节：① ChatMessage.model: Option<String>（serde default 兼容历史消息）；② run_agentic_loop 构造 assistant 消息时 msg.model = Some(provider_config.default_model)；③ save_conversation update 路径 models 去重追加（读旧 JSON 数组 + 新值去重）、insert 初始化 [model]；④ V6 迁移加 models 列；⑤ 前端 AiMessage.model? + Summary.models?，switchConversation 解析历史消息 model。展示仍暂缓（见上条）。
• 记录时机澄清 → [2026-06-13]：models 只追加实际生成过内容（本轮 stream_llm 跑过、产生 assistant 消息）的 save 调用，不记「配置但未实际用于生成」的 model。需求来自用户澄清：「对话集应该不是切换过都留住吧，只有实际发送过消息的才留」——首轮即 stop（无 stream）路径传 Some(model) 会把未生成的 model 误写进 models 数组。正确做法：run_agentic_loop 入口 stop_flag 路径（未 stream）save 传 None；仅 stream 后的退出路径（正常完成/stream 后 stop/审批暂停）传 Some(model)。
• 状态：✅ 2026-06-13（编译/类型双过，未 tauri dev 实测） | ✅ 记录时机已落地（2026-06-13）：入口 stop 路径 save 改传 None，cargo check + vue-tsc 双过

---

四、AI Chat 对话与滚动 UX

滚动/错误友好化/空白屏修复/markdown 缓存为 UX 微调，归档。审批「删全屏 Modal 保行内」为设计决策，已留在主文档。

智能滚动：isNearBottom < 80px

• 决策：仅当用户在底部 80px 内才自动滚动；上滑时不强制拉回。
• 原因：用户回看历史时被强制拉回底部体验差。
• 状态：✅ Sprint 8
• 演进 [2026-06-13]：上滑看历史时新消息/流式不滚 → 补「回到底部」浮动按钮。showBackToBottom（内容溢出 >100px 且不在底时显）+ onMessagesScroll 刷新 + onContentChange（在底则滚、上滑则只刷按钮不强制拉回）。沿用「不打断回看」原则，补一键回底入口。

错误友好化：friendlyError 正则映射

• 决策：404/401/timeout/network 正则映射为中文提示 + isError 红色气泡。
• 原因：原始错误信息对用户不友好。
• 状态：✅ Sprint 8

审批卡片显示参数内容 + 防双击 [2026-06-13]

• 决策：审批卡片（pending_approval）在按钮上方渲染工具参数键值对（toolArgsEntries 遍历 args，formatArgValue 截断超长）+ 风险提示（reason）；AiToolCallInfo 加 reason? 字段，AiApprovalRequired 回填。点击批准/拒绝后 store 乐观置 status='running' + 按钮 :disabled="status!=='pending_approval'"，等后端事件转 completed/rejected，IPC 失败回滚 pending_approval。
• 原因/取舍：原审批卡片只有「批准/拒绝」按钮 + 工具名（update_project/run_workflow），用户盲批——参数不可见等于放行未知操作。双击无防护则连发 IPC（后端 pending_approvals.remove() 有幂等不重复执行，但第二次报错弹窗）。乐观置 running 即时禁用按钮 + 回显参数，审批从「盲批」变「知情决策」。
• 状态：✅ 2026-06-13

空白屏修复：防 FOUC

• 决策：index.html 加主题防闪烁脚本（渲染前置 data-theme）+ __APP_T0 启动埋点 + body 背景色。
• 原因：Vite 启动慢（122s）期间 webview 白屏；前置主题脚本消除 FOUC。
• 状态：✅ Sprint 7

流式 markdown 渲染加结果缓存 [2026-06-13]

• 决策：renderMd 加 Map<text, html> 缓存（限 200 项超出清空）；mdReady 翻转（marked+DOMPurify 加载完成）时清缓存重渲。
• 原因/取舍：v-html="renderMd(...)" 每次响应式触发（折叠/状态变化/新 delta）都跑 marked.parse + DOMPurify.sanitize 全文。历史消息文本不变却重复全量解析（O(n) × 触发次数）。缓存后历史消息命中 O(1)；流式 currentText 中间态各缓存一项（≤200 后清）。未做「流式中降级纯文本」——会让流式无格式、完成后突变格式，体验差；缓存方案保留流式格式且消除重复解析。
• 状态：✅ 2026-06-13

---

五、AI Chat 对话管理 [Sprint 10]

侧边栏时间分组：日历日桶（today/yesterday/earlier）

• 决策：活跃对话按日历日分桶（今天/昨天/更早），归档对话单列可折叠区，而非滚动 24h 或纯时间倒序线。
• 原因：用户心智「今天的对话」指当天而非过去 24 小时；归档是冷区，单列折叠减少对活跃区的视觉干扰。
• 状态：✅ Sprint 10

归档分组默认折叠 + 持久化

• 决策：archivedCollapsed 默认 true（折叠），折叠态写入 df-ai-ui 持久化。
• 原因：归档为冷区，默认折叠让活跃对话优先可见；持久化记住用户展开偏好，不每次重启都收回。
• 状态：✅ Sprint 10

归档绕过 update_field（set_archived 走原始 SQL）

• 决策：归档用专用 set_archived 方法直接 UPDATE ai_conversations SET archived = ?1，不复用 update_field 宏。
• 原因：update_field 对任何字段操作都强制连带 SET updated_at = now，归档是元数据切换不应改对话时间——否则归档后侧栏时间全跳成「刚刚」，破坏时间分组排序。归档与内容更新是两类操作，时间戳语义须区分。
• 状态：✅ Sprint 10

恢复活跃对话加守卫 !state.activeConversationId

• 决策：loadConversations 自动恢复上次活跃对话时，加守卫（仅首次加载、ID 仍有效、当前无活跃对话才恢复）。
• 原因：若用户已手动 new/switch，恢复逻辑不应覆盖其当前意图；守卫保证恢复只在「冷启动无状态」时介入。
• 状态：✅ Sprint 10

---

六、AI Node（工作流节点）[任务 #44]

AI Node 参数解析抽纯函数，单测不 mock LLM [任务 #44]

• 决策：AiNode::execute 内的参数解析（config + 上游 inputs → AiNodeParams）剥离成独立纯函数 parse_params(config, inputs)，execute 调用后再 build_provider + complete。AiNodeParams 加 #[derive(Debug)]（unwrap_err 断言需要）。
• 原因/取舍：execute 原本 162 行硬编码 build_provider，直接单测会触真 HTTP——需 mock LlmProvider trait + 构造完整 NodeContext（event_bus/node_status/NodeId），重且脆弱。抽纯函数只接 config + inputs（execute 实际用到的），参数解析/缺参报错/prompt 上游优先回退/默认值（model 空→gpt-4o-mini、protocol→openai_compat）全可单测，零 mock 零网络。complete 调用正确性归 df-ai provider 层测试（职责分层）。副作用：execute 瘦身，parse 与 LLM 调用分离，可读性提升。
• 状态：✅ 已落地（2026-06-13，7 纯函数单测全过：缺参×3 / prompt 取值×2 / 默认值 / 显式参数；GLM 真调集成测试 glm_live_complete（#[ignore]+env var）通过：glm-4-flash 返回「通过」/usage 正确；GUI DAG 触发实测转 → #54 跟踪）

AI Node 参数边界值契约：空 model 走 provider 兜底 / prompt 双源 [任务 #44]

• 决策：config 无 model 时 parse_params 给空 model + default_model="gpt-4o-mini" 占位字段；build_provider 用 default_model（构造需非空），CompletionRequest.model 忠实传空串，由 provider convert_request（if req.model.is_empty() { self.default_model }）兜底。schema required 仅 ["base_url","api_key"]，不含 prompt（prompt 双源：上游 inputs["prompt"] > config.prompt）。
• 原因/取舍：① model/default_model 双字段分离「忠实值」与「构造兜底」——provider 构造要非空 model（空则后续无兜底锚点），故 default_model 占位防 panic；但 request 仍传真实 model（空）让 provider 兜底单点收敛（两 provider convert_request 统一 is_empty→default_model），避免 AiNode 自猜默认与 provider 不一致。② prompt 双源支持「prompt 由上游节点产出」（如 read_file→ai 分析），schema required 含 prompt 会误拦此合法配置。
• 状态：✅ 已落地（2026-06-13，两 provider convert_request 兜底经 review 核实自洽；schema required 改后 7 单测全过）

---

七、代码审查甄别（2026-06-13 一次性审查流水）

全模块代码审查后的甄别落地。原则性结论（「真实 bug 修、简单清理做、规模不到位的优化先不动」）已在主文档「需求澄清」保留。以下是具体落地条目。

df-evolve 骨架物理删除（连带三件套）

• 决策：删 KnowledgeStore + PatternExtractor + EvolveEngine 三件全 TODO 空壳；同步删 df-nodes 5 个空节点（docker/git/http/notify/subflow）。
• 原因/取舍：KnowledgeStore 被 EvolveEngine 唯一引用、PatternExtractor 同理——删前两者必连带删 EvolveEngine（编译依赖），原「删 2 个」甄别后扩为三件套。src-tauri Cargo.toml 声明依赖 df-evolve 但源码零 use df_evolve，整坨孤立骨架。Knowledge/PromptTemplate/ReviewRule 领域类型保留（有实现 + 测试，Tier 1 Service 复用）。
• 状态：✅ 2026-06-13（cargo check 通过）

列表查询加过滤（内存策略）

• 决策：ai_conversation_list 加 limit（默认 50）+ include_archived（默认 false）；AI 工具 list_projects/list_tasks/list_ideas 闭包加 truncate(50)；build_system_prompt 项目注入 take(20)；list_ideas 命令加 status 可选过滤。均用内存 filter/take 或现成 query，不加新 SQL 方法。
• 原因/取舍：dev 阶段数据量小，内存过滤零触碰通用 impl_repo! 宏（改宏风险高）。数据真到成千上万再加 Repo 的 list_limited SQL 方法。list_ideas 复用现成 query("status", v) 走白名单，零改 Repo。前端 API 加可选参数，旧无参调用兼容（后端默认值兜底）。
• 状态：✅ 2026-06-13

node_executions「全表 list」甄别为伪命题

• 决策：审查提出的「node_executions 全表 list 改按 execution_id 过滤」不成立——全仓仅 state.rs 注册 NodeExecutionRepo，无任何 list/query 命令对外暴露（只写不读，cargo dead_code warning 印证）。
• 原因：不存在「废弃全表 list」的对象。若未来前端要看某次工作流执行的节点明细，需新增 list_node_executions(execution_id) 命令，属新功能非清理。
• 状态：📐 待需求驱动新增

ALLOWED_COLUMNS 从全局共享演进为按表隔离

已移入 经验记录.md「约定」分组。

---

八、状态持久化（UX 偏好部分）

UI 布局：localStorage + 模块级恢复

• 决策：面板布局（panelOpen/maximized/sidebarOpen/archivedCollapsed）写 df-ai-ui；restoreUiState() 放模块顶层（state 单例定义后）执行一次，而非 useAiStore() 内部。
• 原因：state 是模块级单例，useAiStore() 被 App.vue/AiChat.vue/AiDetached.vue 多处调用——放内部会重复执行恢复、覆盖用户当次操作。模块级只跑一次才对。
• 状态：✅ Sprint 10

注：窗口位置/大小用 tauri-plugin-window-state、detached/docked 不持久化两条已在主文档保留（属设计决策）。

---

九、i18n（实现细节）

i18n 模块必须命名空间化导出

已移入 经验记录.md「踩坑」分组。

状态枚举 i18n：constants 存 key，view 包 $t

• 决策：constants/project.ts 的 PROJECT_STATUS_LABELS/TASK_STATUS_LABELS 值从中文文案改存 i18n key（planning: 'projects.status.planning'）；projectStatusLabel/taskStatusLabel 返回 key；view 显示处包 $t(projectStatusLabel(x))。PRIORITY_LABELS（P0/P1）是代号非文案，不动。
• 原因：constants 是纯数据/结构层，不应含展示文案（违反分层）；文案归 locale，constants 管映射结构。
• 状态：✅ 已落地

---

相关文档：

• 功能决策记录 — 需求规格 + 设计决策规格（当前真相源）
• 经验记录 — 踩坑/约定/技巧/bug 排查教训