菜单
StoryMoss 重大调查、死路、被拒修复、revert 的编年史（symptom→root cause→evidence→status），防止重打已定胜负的仗。何时加载：要修一个反复出现的 bug、要判断某修复方向是否已被试过、看到“第一章重复/卡死/死锁/超时/JSON 空/启动崩溃”等历史问题复现、或被问“这问题以前怎么修的”时。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | sf-failure-archaeology |
| description | StoryMoss 重大调查、死路、被拒修复、revert 的编年史（symptom→root cause→evidence→status），防止重打已定胜负的仗。何时加载：要修一个反复出现的 bug、要判断某修复方向是否已被试过、看到“第一章重复/卡死/死锁/超时/JSON 空/启动崩溃”等历史问题复现、或被问“这问题以前怎么修的”时。 |
目的：每个已定胜负的战役写清 symptom→root cause→evidence→status，让后来者不再重打。改一个“似曾相识”的 bug 前先查这里。
| 版本 | 尝试 | 结果 |
|---|---|---|
| v0.26.7 | React #185 回调稳定化 + ChapterSwitch 路径守卫 | 未根治 |
| v0.26.8 | isTextDuplicate + isTextAlreadyInEditor，覆盖 pipeline-complete/ChapterSwitch/smart_execute 竞态 | 未根治 |
| v0.26.9 | 重复检测基准从 editorRef.getText() 改 latestContentRef.current（DOM 滞后） | 未根治 |
| v0.26.10 | latestContentRef + editorRef.getText() 双重基准 + appendText 最终防线 | 未根治 |
| v0.26.11 | 追加后立即 editorRef.getHTML() 同步 store 与 latestContentRef；appendText 空文档分支标记外部同步 | 未根治 |
| v0.26.12 | 修 characters null 白屏；useSubscription 空值防护；E2E | 相关但非根因 |
| v0.26.13 | 渲染层：shouldShowGhostTree 改 !!generatedText（空幽灵容器残留）+ 自动接受先 setIsGenerating(false) | 视觉重复缓解 |
| v0.26.14 | 日志证实数据层只追加一次，重复来自 LLM 正文自身首尾回环；新增 trimSelfRepetition（段落级 + KMP border） | 治标：清 LLM 自重复 |
| v0.26.16 | 结构性根治：生成侧 8% 闸门 + anti-repeat 指令；前端单写者状态机 idle→generating→delivered | 胜 |
| v0.26.18 | 真正的独立根因被发现：src-frontend/src/utils/format.ts 的 splitChineseSentences 全局正则 lastIndex 在 exec 返回 null 时被重置为 0，循环外读取导致 text.slice(0)（整段）被当末句再 push → autoFormatText 段落分组后内容翻倍（日志：0+1446 → 2933 ≈ 2×1446）。修复：循环内捕获 lastIndex，3 个契约单测。Gap A/B/C 单写者加固作为正交防御保留 | 胜（format 层） |
| v0.26.23 | auto_contract 4 label 静默化（解除续写 6 分钟阻塞，根因非重复但同症状域） | 收尾 |
format.ts splitChineseSentences 正则 lastIndex 重置导致 autoFormatText 内容翻倍（v0.26.18 才发现，前 11 轮所有前端守卫都挡不住这条）。creative_workflow.log 显示 append_ai_done 触发一次、append_text_check.occurrences=1；v0.26.18 日志数学矛盾 0+1446→2933≈2×1446 证实 format 层翻倍。*_future 已重命名为 *_gen（澄清顺序 await 非 tokio::join! 并行）。record_llm_call DB 写入阻塞 tokio worker；pool.get() 无 .connection_timeout 无限阻塞。db_write/emit_completed 阻塞。record_llm_call 改 spawn_blocking fire-and-forget；连接池 .connection_timeout(5s)。死路：在热路径同步等 DB。select_candidates（Call3）必死锁；BGP-4 卡住。std::sync::Mutex 不可重入——health_registry.lock() 持锁期间 is_model_available 再 lock；BGP-4 spawn_blocking().await 与 BGP-1/3 竞争同 Mutex。tokio::spawn。死路：持 std::sync::Mutex 期间再 lock 同锁。{}（v0.23.48–.49）missing field 'title' / 空 {}。önh.../<thinking> 里的花括号被 find('{') 误判为 JSON 对象，提取出空 {}。strip_reasoning_blocks 剥离思考链后正常。strip_reasoning_blocks + extract_first_json_object（括号匹配）跳过空对象继续扫描。死路：find('{')/rfind('}') 简单查找。init_db 在不可写 app data 目录失败；GatewayExecutor::new 通过 state::<DbPool>() 读未 manage 的 pool 在启动时 panic。GatewayExecutor::new 显式接收 pool，setup 仅在 pool 可用时初始化网关；打包 src/db/migrations/ 为 Tauri resource；init_db 启动前 create_dir_all。light.exe 标识符生成失败。V### 前缀与排序）。schema_migrations 按 version 跟踪，已应用迁移不受影响。死路：wix.language: zh-CN（v0.26.20 尝试无效，问题在标识符生成而非代码页；该配置项仍在 tauri.conf.json 但已无效，可清理）。auto_contract 4 label 未静默化，后台补合同阻塞 isAnyBackendActive 6 分钟。handleSmartGeneration 重入，旧幽灵未丢弃。force-hide-ghost 类移除未触发重渲染。is_silent_background；重入守卫；bodyForceHideGhost state 镜像；call3 超时 120s→60s 慢模型回退快模型。state() called before manage() for Arc<dyn VectorStore>。LanceVectorStore 创建与 app.manage 提前到依赖组件之前。| commit | 回滚了什么 | 教训 |
|---|---|---|
a9114d2（v0.23.39） | 回滚激进前端守卫（selectChapter 同章跳过、移除 story_created selectChapter、isFirstChapterReady 时 setGeneratedText('')） | 过度守卫打破正常加载路径 → 白屏回归。保留诊断日志 + 后端 completed/error 修复。这是前端守卫的安全边界——v0.26.7–.14 的散布布尔守卫终将撞到这条 |
b444832 | 整个重构提交 | 366 个编译错误——过大的重构落地即碎 |
b775c2a | Cargo.lock 回退到 v0.14.4 | cargo update（v0.15.0 期间）破坏 SQLite 迁移行为（V25 scenes.execute_stage 未应用）→ 28 个 canonical_state 测试失败 |
更多条目见 docs/archive/LESSONS_LEARNED.md 与 docs/archive/AGENTS_HISTORY.md（完整历史版本记录）。
sf-debugging-playbook。sf-architecture-contract。sf-genesis-campaign。git log --oneline --all | rg 'fix|revert|重复|卡死|死锁|panic|超时' | head -40ls docs/archive/git tag --sort=-creatordate | head -20（版本→战役对照）运行/部署 StoryMoss 的命令解剖、运行时数据与产物落点。何时加载：要启动应用、要找日志、要找数据库/配置文件、要发布 tag、要看生成链路日志、或被问“日志在哪/数据在哪/怎么发布”时。
Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
StoryMoss 承重设计决策与 WHY、必须成立的不变量、已知弱点。何时加载：要改架构、要动数据真相源、要改生成链路、要改 IPC/SyncEvent、要动数据库层、要评估“能不能这样改”、或被问“为什么这样设计/哪些不能动”时。改任何符号前先用 gitnexus impact。
从零重建 StoryMoss 开发与构建环境，含已知陷阱。何时加载：首次 clone 后要跑起来、换机器、CI 本地复现、`cargo tauri dev/build` 报环境错、前端起不来、跨平台构建失败、或被问“怎么构建/怎么跑”时。
StoryMoss 变更门禁与不可破坏项。何时加载：要提交/推送代码、要 bump 版本、要改架构边界、要动数据库迁移、要改 CI、要发布 tag、要合并 feature 分支、或被问“能不能直接改/直接推”时。也用于判断一个改动是否需要用户授权（R10）。
StoryMoss 全部配置轴：选项、默认值、生产 vs 实验、守卫、如何新增。何时加载：要改生成模式、要改并发/超时、要加 PromptRegistry 覆盖、要调体裁模板、要改 silent_background 白名单、要动 rustfmt、或被问“在哪配/默认是什么/这个开关干啥”时。