القائمة
StoryMoss 失败模式的症状→分诊表、卡时间的陷阱与区分实验。何时加载：报告了 bug、续写卡死、Genesis 第一章重复、生成无输出、启动崩溃、CI 失败、JSON 解析空对象、超时、白屏、或被问“为什么 X 失败/卡住”时。先建反馈回路再下结论（见 diagnose 技能 Phase 1）。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
运行/部署 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、或被问“在哪配/默认是什么/这个开关干啥”时。
| name | sf-debugging-playbook |
| description | StoryMoss 失败模式的症状→分诊表、卡时间的陷阱与区分实验。何时加载：报告了 bug、续写卡死、Genesis 第一章重复、生成无输出、启动崩溃、CI 失败、JSON 解析空对象、超时、白屏、或被问“为什么 X 失败/卡住”时。先建反馈回路再下结论（见 diagnose 技能 Phase 1）。 |
铁律：先建反馈回路再下结论。本项目大多数“卡死/重复/无输出”都是竞态或同步阻塞，肉眼盯代码无效。参考 diagnose 技能 Phase 1 构造回路；本项目特有回路见下文。
修复必须走门禁：下表给出的是历史已验证的修复方向（用于快速分诊），不是允许跳过门禁。任何新修复在合并前必须走
sf-change-control（变更门禁）+sf-validation-and-qa（证据标准，含回归测试）+ 推送门（docs 同步 + CI 必查）。
creative_workflow.log 时间线对照法（本项目最有效）：读 <app_data_dir>/logs/creative_workflow.log，把用户感知的“卡住时刻”对齐到日志的阶段标记（genesis.first_chapter.generated/smart_execute.start/trishot.call3.done/trishot.bgp4.spawn/done/llm.record_call.spawn）。卡点 = 时间线断点。v0.26.23 续写卡死就是用 creative_workflow.log 时间线定位到 auto_contract 阻塞 6 分钟。注：候选模型实时探测（5s）走标准 log::debug!（[Gateway] 候选 [N] 实时探测通过/失败/超时），不进 creative_workflow.log——查探测去标准日志 sink。[DEBUG-dup]/[DEBUG-act] console.warn；frontstage:rich_editor_diag（前 20 帧 + 幽灵状态变化 + 200ms IPC 节流）。select_first_chapter_content/world_concept_for_character_prompt 模式）写契约测试。tests/fixtures/trim_golden.json Rust+TS 双跑锁定。genesis-duplicate.spec.ts 验证自动接受后幽灵段落隐藏。| 症状 | 最可能根因 | 区分实验 / 首查 | 优先级 |
|---|---|---|---|
| 续写卡死，正文已返回但界面不动 | 后台 LLM 调用未静默化，进度事件覆盖主活动 | 查 is_silent_background 白名单（llm/service.rs）是否含该 context_label；读日志看是否后台 label 触发前端 activity | P0 |
| 续写结果新旧竞争 / 幽灵文本混乱 | handleSmartGeneration 重入，旧幽灵未丢弃 | 入口重入守卫：存在未接受幽灵时先丢弃并提示（v0.26.23 Bug D） | P0 |
| 幽灵文本 10s 后才消失 | force-hide-ghost 类移除未触发重渲染 | RichTextEditor 用 bodyForceHideGhost state 镜像类（v0.26.23 Bug A） | P1 |
| 新小说第一章内容重复 | 多路径并发叠加：DB 正文 + 幽灵 + smart_execute final_content 竞态；或 LLM 输出本身首尾回环；或 format.ts 正则翻倍 | 先看日志确认是数据层重复、LLM 自重复、还是精确 2× 翻倍（splitChineseSentences lastIndex 重置，v0.26.18）；v0.26.14 日志证实数据层只追加一次，重复来自 LLM 正文自身 | P0 |
| 第一章字数精确翻倍（≈2×） | src-frontend/src/utils/format.ts splitChineseSentences 全局正则 lastIndex 在 exec 返回 null 时重置为 0，循环外读取导致整段被当末句再 push | 看日志 afterLen ≈ 2×beforeLen；修复在循环内捕获 lastIndex（v0.26.18） | P0 |
| 第一章 LLM 输出首尾段落相同 | 模型自重复 | trimSelfRepetition/trim_self_repetition（KMP 最长 border，≥30 字且 ≥8% 裁尾）；生成侧 8% 闸门重试 | P0 |
生成无输出 / 空 {} JSON | 推理模型思考链里花括号被 find('{') 误判 | strip_reasoning_blocks + extract_first_json_object 跳过空对象（v0.23.49） | P1 |
| JSON 解析 trailing characters | rfind('}') 在 JSON 后含 } 文本时误提取 | 括号匹配精确提取（v0.23.48） | P1 |
| 600s 超时 | record_llm_call DB 写入阻塞 tokio worker / pool.get() 无限阻塞 | 连接池 .connection_timeout(5s)；record_llm_call 改 spawn_blocking fire-and-forget（v0.23.19） | P0 |
| select_candidates / Call3 必死锁 | std::sync::Mutex 不可重入，持锁期间再 lock | health 锁移入嵌套块作用域（v0.23.34）；中毒锁 unwrap_or_else(|e| e.into_inner()) | P0 |
| BGP-4 卡住 / 自死锁 | spawn_blocking().await 等 DB 与 BGP-1/3 竞争同 Mutex | 改 tokio::spawn fire-and-forget（v0.23.42） | P0 |
术语：BGP = Background Pipeline（后台管线阶段，BGP-1/2/3/4 为创世后台的 4 个阶段，如 BGP-2 自动改写、BGP-3 后台 Ingest、BGP-4 后台审计+洞察）。 | macOS 启动 panic
state() called before manage()| VectorStore State 注入顺序 |LanceVectorStore创建与app.manage提前（v0.23.6） | P0 | | 启动 panic / Windows 闪退（Issue #4） |init_db不可写目录失败；GatewayExecutor::new读未 manage 的 pool |setup显式传 pool，仅 pool 可用时初始化（v0.26.16）；打包迁移资源（v0.26.17） | P0 | | 幕前白屏 |useCharacters返回 null 时访问.length| null 防护（v0.26.12）；ErrorBoundary增强诊断 | P1 | | React #185 无限循环 |FrontstageApppipeline-complete effect 回调不稳定化 | 回调稳定化 + Zustand selector 同步 isGenerating（v0.26.2–.7） | P0 | | Windows MSI 构建挂掉 | 迁移文件名含中文/全角/破折号/过长 | 重命名 ASCII 短名（v0.26.21） | P0 | | macOS 公证失败 | 协议过期 / 证书密码尾随空格 | 续签；Secret 必须 28 字符无尾随 | P0（外部） | | CIcargo +nightly fmt -- --check跨平台不一致 |format_stringsmacOS/Win nightly 不同 | 不要启用format_strings| P1 | | 本地模型并发崩溃页面空白 | IngestPipeline 并发 LLM 未静默 | 三个 label 加入is_silent_background（v0.23.45） | P0 |
editorRef.getText()）滞后 DOM + 多写者并发。教训：竞态必须有单写者状态机 + 双重基准，散布布尔守卫必复发。rustfmt.toml 的 format_strings 会引入跨平台 CI 差异。diagnose 技能。sf-failure-archaeology。sf-architecture-contract。sf-diagnostics-and-tooling。rg -n 'is_silent_background|BACKGROUND_LLM_SEMAPHORE|connection_timeout' src-tauri/src/llmrg -n 'spawn_blocking|tokio::spawn' src-tauri/src/llm src-tauri/src/task_system | headls tests/fixtures/（golden 在仓库根 tests/，非 src-tauri/）git log --oneline --all | rg 'fix|revert|重复|卡死|死锁|panic' | head -30