القائمة
StoryMoss 变更门禁与不可破坏项。何时加载：要提交/推送代码、要 bump 版本、要改架构边界、要动数据库迁移、要改 CI、要发布 tag、要合并 feature 分支、或被问“能不能直接改/直接推”时。也用于判断一个改动是否需要用户授权（R10）。
التثبيت باستخدام 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 全部配置轴：选项、默认值、生产 vs 实验、守卫、如何新增。何时加载：要改生成模式、要改并发/超时、要加 PromptRegistry 覆盖、要调体裁模板、要改 silent_background 白名单、要动 rustfmt、或被问“在哪配/默认是什么/这个开关干啥”时。
StoryMoss 失败模式的症状→分诊表、卡时间的陷阱与区分实验。何时加载：报告了 bug、续写卡死、Genesis 第一章重复、生成无输出、启动崩溃、CI 失败、JSON 解析空对象、超时、白屏、或被问“为什么 X 失败/卡住”时。先建反馈回路再下结论（见 diagnose 技能 Phase 1）。
| name | sf-change-control |
| description | StoryMoss 变更门禁与不可破坏项。何时加载：要提交/推送代码、要 bump 版本、要改架构边界、要动数据库迁移、要改 CI、要发布 tag、要合并 feature 分支、或被问“能不能直接改/直接推”时。也用于判断一个改动是否需要用户授权（R10）。 |
本项目已有一套带血泪史的强制规则。先读这一条再动手：违反任何一条都会触发 CI 失败、用户返工、或已修复的 bug 复活。
| 规则 | 要求 | 违反的代价（已发生） |
|---|---|---|
| 版本号四源统一 | git tag、src-tauri/Cargo.toml、src-tauri/tauri.conf.json、src-frontend/package.json 版本一致 | 升级器/CI 版本探测错位；release 产物版本与 tag 不符 |
| 每次推送必更新文档 | 同步更新 README.md、CHANGELOG.md、AGENTS.md、PROJECT_STATUS.md、ROADMAP.md、ARCHITECTURE.md、TESTING.md、docs/USER_GUIDE.md | 用户依据陈旧文档诊断，反复返工 |
| 推送后必查 CI | 推送后立即 gh run list --limit 3，监控到全绿（见 sf-validation-and-qa） | v0.26.19–.21 多版本积压的 macOS 公证过期、Windows WiX 中文文件名问题，因“推完就走”拖了多版才被发现 |
| tag 不覆盖 | git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z，禁止 force push 已有 tag | 升级器 latest.json 指向错乱 |
| 迁移文件名 ASCII 短名 | 新迁移文件名只允许 V###__ascii_short.sql，禁止中文/全角标点/破折号，长度尽量短 | v0.26.21：WiX light.exe 标识符生成失败导致 Windows MSI 整个构建挂掉 |
| 后台 LLM 调用必须静默化 | 任何后台（非用户等待路径）LLM 调用的 context_label 必须加入 is_silent_background 白名单（src-tauri/src/llm/service.rs） | v0.23.45 / v0.26.23：后台 Ingest/auto_contract 进度事件覆盖前端主活动，导致“正文已返回但界面卡死” |
| 不要把后台 DB 写入同步阻塞 tokio worker | record_llm_call 等高频 DB 写入走 spawn_blocking fire-and-forget | v0.23.19：600s 超时，pool.get() 无限阻塞 |
std::sync::Mutex 不可重入 | 同一线程持锁期间禁止再次 lock 同一锁；中毒锁用 unwrap_or_else(|e| e.into_inner()) 恢复 | v0.23.34 select_candidates 自死锁；v0.23.42 BGP-4 自死锁 |
不动 rustfmt.toml 跨平台行为 | 不要开启 format_strings（macOS/Windows nightly 行为不一致） | CI cargo +nightly fmt -- --check 在不同平台结果不同 |
| 架构边界 | python3 scripts/architecture_guard.py 必须通过；db 禁止依赖 narrative/agents/memory/creative_engine/story_system/pipeline；domain 禁止依赖任何业务模块；禁止重新引入 FORBIDDEN_GLOBALS（VECTOR_STORE/DB_POOL/LLM_SERVICE/APP_CONFIG/SKILL_MANAGER/...） | v0.23.1 单例清零与循环依赖斩断的成果回潮 |
提交门 vs 推送门：下表是提交门禁（能否 commit）。推送一律触发推送门：四源版本号统一 + docs of record 同步（AGENTS.md 强制规则 4）+ 推送后必查 CI（
sf-validation-and-qa/.cursor/rules/post-push-ci-check.mdc），与变更类别无关。即便是"可逆/本地"类，一旦 push 就走完整推送门。
| 类别 | 例子 | 提交门 |
|---|---|---|
| 可逆 / 本地 | 单文件 bug 修复、新增测试、注释 | 本地 cargo test --lib + npx tsc --noEmit + cargo +nightly fmt -- --check + npm run format:check 全绿即可提交 |
| 跨层 | 改 IPC 命令、SyncEvent variant、DTO | 必须跑 scripts/verify-ipc-manifest.py；前端 assertUnreachable 兜底；ts-rs 重新生成 |
| 跨层共享算法 | 改 trim_self_repetition（Rust）或 trimSelfRepetition（TS） | 必须双跑 tests/fixtures/trim_golden.json（Rust trim_self_repetition_matches_shared_golden_fixture + TS textCleanup.golden.test.ts） |
| 架构边界 | 改 db ↔ narrative 依赖、重新引入全局单例 | architecture_guard.py 必须通过；HIGH 风险需用户授权（R10） |
| 数据库迁移 | 新增 .sql 文件 | 文件名 ASCII 短名 V###__*.sql；幂等（duplicate column/already exists 跳过）；本地 cargo test --lib 跑迁移测试 |
| 用户契约 / 不可逆 | 改 quick phase 30-60s 返回首章的承诺、改 tag 策略、改升级器端点 | R10：必须用户授权；先在 ROADMAP 记录为债务并量化 |
<type>: <subject>
type: feat / fix / docs / style / refactor / test / chore
历史风格见 git log --oneline -30：fix: v0.26.23 修复...、feat: v0.26.19 ...。
sf-architecture-contract 或 sf-reference。sf-debugging-playbook。sf-validation-and-qa。sf-run-and-operate。CLAUDE.md（META charter + Zero-Pause）、AGENTS.md（强制构建规则）、.cursor/rules/post-push-ci-check.mdc。git log --oneline -5（看最近提交风格与版本号）grep -rE '^version' src-tauri/Cargo.toml src-frontend/package.json（四源版本是否一致；另查 tauri.conf.json 的 "version"）python3 scripts/architecture_guard.py（边界是否仍通过）gh run list --limit 3（最近 CI 状态）.github/workflows/build.yml）、is_silent_background 白名单（src-tauri/src/llm/service.rs）。