一键在 Manus 中运行任何 Skill

sf-debugging-playbook

星标57

分支14

更新时间2026年7月11日 01:38

StoryMoss 失败模式的症状→分诊表、卡时间的陷阱与区分实验。何时加载：报告了 bug、续写卡死、Genesis 第一章重复、生成无输出、启动崩溃、CI 失败、JSON 解析空对象、超时、白屏、或被问“为什么 X 失败/卡住”时。先建反馈回路再下结论（见 diagnose 技能 Phase 1）。

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

91zgaoge

91zgaoge/StoryMoss

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

StoryMoss 调试手册

铁律：先建反馈回路再下结论。本项目大多数“卡死/重复/无输出”都是竞态或同步阻塞，肉眼盯代码无效。参考 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 模式）写契约测试。
跨层 golden 双跑：算法 bug 用 tests/fixtures/trim_golden.json Rust+TS 双跑锁定。
E2E：仅前端行为；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 无限循环 | FrontstageApp pipeline-complete effect 回调不稳定化 | 回调稳定化 + Zustand selector 同步 isGenerating（v0.26.2–.7） | P0 | | Windows MSI 构建挂掉 | 迁移文件名含中文/全角/破折号/过长 | 重命名 ASCII 短名（v0.26.21） | P0 | | macOS 公证失败 | 协议过期 / 证书密码尾随空格 | 续签；Secret 必须 28 字符无尾随 | P0（外部） | | CI cargo +nightly fmt -- --check 跨平台不一致 | format_strings macOS/Win nightly 不同 | 不要启用 format_strings | P1 | | 本地模型并发崩溃页面空白 | IngestPipeline 并发 LLM 未静默 | 三个 label 加入 is_silent_background（v0.23.45） | P0 |

卡时间的陷阱（每个都真实踩过）

盯代码找竞态：第一章重复 saga 从 v0.26.7 到 v0.26.16 反复 9 次，每次都“看起来修了”。根因是单一基准（editorRef.getText()）滞后 DOM + 多写者并发。教训：竞态必须有单写者状态机 + 双重基准，散布布尔守卫必复发。
不读日志就猜：v0.26.14 用户感知“第一章重复”，不读日志会以为是前端追加了两次；日志证实数据层只追加一次，重复来自 LLM 正文自身首尾回环。
把后台当同步：后台 LLM/DB 调用同步化是本项目卡死的最常见根因（600s、BGP-4、Ingest、auto_contract）。
改 fmt 配置：动 rustfmt.toml 的 format_strings 会引入跨平台 CI 差异。

何时 NOT 用本技能

通用调试纪律（建回路→复现→假设→仪器化→修+回归）→ diagnose 技能。
已修复战役的完整编年史 → sf-failure-archaeology。
架构不变量 → sf-architecture-contract。
诊断工具具体用法 → sf-diagnostics-and-tooling。

出处与维护

重验证命令：
- rg -n 'is_silent_background|BACKGROUND_LLM_SEMAPHORE|connection_timeout' src-tauri/src/llm
- rg -n 'spawn_blocking|tokio::spawn' src-tauri/src/llm src-tauri/src/task_system | head
- ls tests/fixtures/（golden 在仓库根 tests/，非 src-tauri/）
- git log --oneline --all | rg 'fix|revert|重复|卡死|死锁|panic' | head -30
易漂移项：白名单 label、超时常量、State 注入顺序、rustfmt 配置。
最后核对：2026-07-07，v0.26.23。

同仓库更多 Skills

同仓库

sf-run-and-operate

91zgaoge/StoryMoss

运行/部署 StoryMoss 的命令解剖、运行时数据与产物落点。何时加载：要启动应用、要找日志、要找数据库/配置文件、要发布 tag、要看生成链路日志、或被问“日志在哪/数据在哪/怎么发布”时。

2026-07-1357

diagnose

91zgaoge/StoryMoss

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.

2026-07-1157

sf-architecture-contract

91zgaoge/StoryMoss

StoryMoss 承重设计决策与 WHY、必须成立的不变量、已知弱点。何时加载：要改架构、要动数据真相源、要改生成链路、要改 IPC/SyncEvent、要动数据库层、要评估“能不能这样改”、或被问“为什么这样设计/哪些不能动”时。改任何符号前先用 gitnexus impact。

2026-07-1157

sf-build-and-env

91zgaoge/StoryMoss

从零重建 StoryMoss 开发与构建环境，含已知陷阱。何时加载：首次 clone 后要跑起来、换机器、CI 本地复现、`cargo tauri dev/build` 报环境错、前端起不来、跨平台构建失败、或被问“怎么构建/怎么跑”时。

2026-07-1157

sf-change-control

91zgaoge/StoryMoss

StoryMoss 变更门禁与不可破坏项。何时加载：要提交/推送代码、要 bump 版本、要改架构边界、要动数据库迁移、要改 CI、要发布 tag、要合并 feature 分支、或被问“能不能直接改/直接推”时。也用于判断一个改动是否需要用户授权（R10）。

2026-07-1157

sf-config-and-flags

91zgaoge/StoryMoss

StoryMoss 全部配置轴：选项、默认值、生产 vs 实验、守卫、如何新增。何时加载：要改生成模式、要改并发/超时、要加 PromptRegistry 覆盖、要调体裁模板、要改 silent_background 白名单、要动 rustfmt、或被问“在哪配/默认是什么/这个开关干啥”时。

2026-07-1157

name	sf-debugging-playbook
description	StoryMoss 失败模式的症状→分诊表、卡时间的陷阱与区分实验。何时加载：报告了 bug、续写卡死、Genesis 第一章重复、生成无输出、启动崩溃、CI 失败、JSON 解析空对象、超时、白屏、或被问“为什么 X 失败/卡住”时。先建反馈回路再下结论（见 diagnose 技能 Phase 1）。

StoryMoss 调试手册

修复必须走门禁：下表给出的是历史已验证的修复方向（用于快速分诊），不是允许跳过门禁。任何新修复在合并前必须走 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 模式）写契约测试。
跨层 golden 双跑：算法 bug 用 tests/fixtures/trim_golden.json Rust+TS 双跑锁定。
E2E：仅前端行为；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 无限循环 | FrontstageApp pipeline-complete effect 回调不稳定化 | 回调稳定化 + Zustand selector 同步 isGenerating（v0.26.2–.7） | P0 | | Windows MSI 构建挂掉 | 迁移文件名含中文/全角/破折号/过长 | 重命名 ASCII 短名（v0.26.21） | P0 | | macOS 公证失败 | 协议过期 / 证书密码尾随空格 | 续签；Secret 必须 28 字符无尾随 | P0（外部） | | CI cargo +nightly fmt -- --check 跨平台不一致 | format_strings macOS/Win nightly 不同 | 不要启用 format_strings | P1 | | 本地模型并发崩溃页面空白 | IngestPipeline 并发 LLM 未静默 | 三个 label 加入 is_silent_background（v0.23.45） | P0 |

卡时间的陷阱（每个都真实踩过）

盯代码找竞态：第一章重复 saga 从 v0.26.7 到 v0.26.16 反复 9 次，每次都“看起来修了”。根因是单一基准（editorRef.getText()）滞后 DOM + 多写者并发。教训：竞态必须有单写者状态机 + 双重基准，散布布尔守卫必复发。
不读日志就猜：v0.26.14 用户感知“第一章重复”，不读日志会以为是前端追加了两次；日志证实数据层只追加一次，重复来自 LLM 正文自身首尾回环。
把后台当同步：后台 LLM/DB 调用同步化是本项目卡死的最常见根因（600s、BGP-4、Ingest、auto_contract）。
改 fmt 配置：动 rustfmt.toml 的 format_strings 会引入跨平台 CI 差异。

何时 NOT 用本技能

通用调试纪律（建回路→复现→假设→仪器化→修+回归）→ diagnose 技能。
已修复战役的完整编年史 → sf-failure-archaeology。
架构不变量 → sf-architecture-contract。
诊断工具具体用法 → sf-diagnostics-and-tooling。

出处与维护

重验证命令：
- rg -n 'is_silent_background|BACKGROUND_LLM_SEMAPHORE|connection_timeout' src-tauri/src/llm
- rg -n 'spawn_blocking|tokio::spawn' src-tauri/src/llm src-tauri/src/task_system | head
- ls tests/fixtures/（golden 在仓库根 tests/，非 src-tauri/）
- git log --oneline --all | rg 'fix|revert|重复|卡死|死锁|panic' | head -30
易漂移项：白名单 label、超时常量、State 注入顺序、rustfmt 配置。
最后核对：2026-07-07，v0.26.23。