Sf Failure Archaeology

StoryMoss 失败考古

目的：每个已定胜负的战役写清 symptom→root cause→evidence→status，让后来者不再重打。改一个“似曾相识”的 bug 前先查这里。

战役 1：Genesis 新小说第一章内容重复（v0.26.7–.23，9 轮）

• symptom：新写小说第一章正文出现首尾重复 / 整段叠加。
• root cause（最终，多层）：(R1) 前端多路径并发写（DB 正文 + 幽灵 + smart_execute final_content）无单写者；(R2) LLM 输出自重复未被生成侧拦截；(R3) format.ts splitChineseSentences 正则 lastIndex 重置导致 autoFormatText 内容翻倍（v0.26.18 才发现，前 11 轮所有前端守卫都挡不住这条）。
• evidence：creative_workflow.log 显示 append_ai_done 触发一次、append_text_check.occurrences=1；v0.26.18 日志数学矛盾 0+1446→2933≈2×1446 证实 format 层翻倍。
• status：已胜。死路：散布布尔守卫（v0.26.7–.14 共 6+ 轮）必复发——禁止回退。*_future 已重命名为 *_gen（澄清顺序 await 非 tokio::join! 并行）。

战役 2：600s 超时（v0.23.17–.19）

• symptom：生成请求挂到 600s 超时。
• root cause：record_llm_call DB 写入阻塞 tokio worker；pool.get() 无 .connection_timeout 无限阻塞。
• evidence：行级诊断 12+ 标记定位到 db_write/emit_completed 阻塞。
• status：已胜。record_llm_call 改 spawn_blocking fire-and-forget；连接池 .connection_timeout(5s)。死路：在热路径同步等 DB。

战役 3：Mutex 自死锁（v0.23.34 / .42）

• symptom：select_candidates（Call3）必死锁；BGP-4 卡住。
• root cause：std::sync::Mutex 不可重入——health_registry.lock() 持锁期间 is_model_available 再 lock；BGP-4 spawn_blocking().await 与 BGP-1/3 竞争同 Mutex。
• evidence：15 个诊断标记精确定位自死锁位置。
• status：已胜。health 锁移入嵌套块作用域；BGP-4 改 tokio::spawn。死路：持 std::sync::Mutex 期间再 lock 同锁。

战役 4：推理模型 JSON 空 {}（v0.23.48–.49）

• symptom：推理模型生成 missing field 'title' / 空 {}。
• root cause：思考链 önh.../<thinking> 里的花括号被 find('{') 误判为 JSON 对象，提取出空 {}。
• evidence：strip_reasoning_blocks 剥离思考链后正常。
• status：已胜。strip_reasoning_blocks + extract_first_json_object（括号匹配）跳过空对象继续扫描。死路：find('{')/rfind('}') 简单查找。

战役 5：Issue #4 启动 panic / Windows 闪退（v0.26.16–.17）

• symptom：应用启动 panic；Windows 闪退。
• root cause：init_db 在不可写 app data 目录失败；GatewayExecutor::new 通过 state::<DbPool>() 读未 manage 的 pool 在启动时 panic。
• evidence：不可写应用目录回归测试复现。
• status：已胜。GatewayExecutor::new 显式接收 pool，setup 仅在 pool 可用时初始化网关；打包 src/db/migrations/ 为 Tauri resource；init_db 启动前 create_dir_all。

战役 6：Windows MSI 构建（v0.26.21）

• symptom：WiX light.exe 标识符生成失败。
• root cause：24 个迁移文件名含中文/全角逗号/破折号且最长 102 字符。
• status：已胜。重命名为 ASCII 短名（保留 V### 前缀与排序）。schema_migrations 按 version 跟踪，已应用迁移不受影响。死路：wix.language: zh-CN（v0.26.20 尝试无效，问题在标识符生成而非代码页；该配置项仍在 tauri.conf.json 但已无效，可清理）。

战役 7：续写卡死与幽灵文本混乱（v0.26.23，4 根因）

• symptom：续写卡死 6 分钟；新旧续写结果竞争；幽灵 10s 渲染延迟。
• root cause（4 项）：
  • Bug B（卡死主因）：auto_contract 4 label 未静默化，后台补合同阻塞 isAnyBackendActive 6 分钟。
  • Bug D（混乱主因）：handleSmartGeneration 重入，旧幽灵未丢弃。
  • Bug A：force-hide-ghost 类移除未触发重渲染。
  • Bug C：续写 call3 超时 120s，慢模型不 fail-fast。
• status：已胜。4 label 加入 is_silent_background；重入守卫；bodyForceHideGhost state 镜像；call3 超时 120s→60s 慢模型回退快模型。

战役 8：macOS 启动崩溃（v0.23.6）

• symptom：state() called before manage() for Arc<dyn VectorStore>。
• root cause：Tauri State 注入顺序。
• status：已胜。LanceVectorStore 创建与 app.manage 提前到依赖组件之前。

Reverts（死路标记，避免重走）

历史教训总集

更多条目见 docs/archive/LESSONS_LEARNED.md 与 docs/archive/AGENTS_HISTORY.md（完整历史版本记录）。

何时 NOT 用本技能

• 当前 bug 分诊 → sf-debugging-playbook。
• 架构不变量 → sf-architecture-contract。
• 要推进的活问题 campaign → sf-genesis-campaign。

出处与维护

• 重验证命令：
  • git log --oneline --all | rg 'fix|revert|重复|卡死|死锁|panic|超时' | head -40
  • ls docs/archive/
  • git tag --sort=-creatordate | head -20（版本→战役对照）
• 易漂移项：版本号映射、新增战役需追加。
• 最后核对：2026-07-07，v0.26.23。