菜单
从零重建 StoryMoss 开发与构建环境，含已知陷阱。何时加载：首次 clone 后要跑起来、换机器、CI 本地复现、`cargo tauri dev/build` 报环境错、前端起不来、跨平台构建失败、或被问“怎么构建/怎么跑”时。
用 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 变更门禁与不可破坏项。何时加载：要提交/推送代码、要 bump 版本、要改架构边界、要动数据库迁移、要改 CI、要发布 tag、要合并 feature 分支、或被问“能不能直接改/直接推”时。也用于判断一个改动是否需要用户授权（R10）。
StoryMoss 全部配置轴：选项、默认值、生产 vs 实验、守卫、如何新增。何时加载：要改生成模式、要改并发/超时、要加 PromptRegistry 覆盖、要调体裁模板、要改 silent_background 白名单、要动 rustfmt、或被问“在哪配/默认是什么/这个开关干啥”时。
StoryMoss 失败模式的症状→分诊表、卡时间的陷阱与区分实验。何时加载：报告了 bug、续写卡死、Genesis 第一章重复、生成无输出、启动崩溃、CI 失败、JSON 解析空对象、超时、白屏、或被问“为什么 X 失败/卡住”时。先建反馈回路再下结论（见 diagnose 技能 Phase 1）。
| name | sf-build-and-env |
| description | 从零重建 StoryMoss 开发与构建环境，含已知陷阱。何时加载：首次 clone 后要跑起来、换机器、CI 本地复现、`cargo tauri dev/build` 报环境错、前端起不来、跨平台构建失败、或被问“怎么构建/怎么跑”时。 |
| 工具 | 版本 | 来源 | 备注 |
|---|---|---|---|
| Node.js | 20 LTS | nodejs.org | CI 用 20；本地 18 也勉强可用但未保证 |
| Rust | 1.95.0（固定） | rust-toolchain.toml 自动固定 | rustup 会自动装；不要手动 rustup default 改版本 |
| protoc | 任意 | arduino/setup-protoc@v3 或系统安装 | Lancedb/embedding 依赖；缺失会编译失败 |
| Tauri CLI | @tauri-apps/cli ^2.10.1 | src-frontend devDependency | 用 npx tauri 或 cargo tauri 均可 |
| Playwright | latest | 根 package.json | 仅 E2E 需要 |
Ubuntu 额外系统包（CI 已验证）：
sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev patchelf
# 1. clone
git clone https://github.com/91zgaoge/StoryMoss.git
cd StoryMoss
# 2. 前端依赖
cd src-frontend && npm ci # 用 ci 而非 install，保证与 lockfile 一致
# 3. 仅前端调试（浏览器，无 Tauri 后端，IPC 会挂起——见陷阱）
npm run dev # http://localhost:5173/
# 4. 桌面应用（自动起前端 dev server + 开窗）
cd ..
npx tauri dev # 或 cd src-tauri && cargo tauri dev
# 5. 生产构建（本平台安装包）
cd src-tauri && cargo tauri build
README 写
npm install -g @tauri-apps/cli，但src-frontend已把@tauri-apps/cli列为 devDependency，用npx tauri即可，无需全局安装。
| 症状 | 根因 | 解决 |
|---|---|---|
cargo tauri dev 加载陈旧页面 / 崩溃 | tauri.conf.json 的 devUrl 必须指向 http://localhost:5173（dev server）；若指向 dist 会加载旧产物 | 确认 devUrl；先起 npm run dev 再 tauri dev |
state() called before manage() for Arc<dyn VectorStore> 启动 panic | Tauri State 注入顺序错 | v0.23.6 已修：LanceVectorStore 创建与 app.manage 提前到依赖组件之前。若复现说明有人改了 lib.rs/setup 顺序 |
| 启动 panic / Windows 闪退（Issue #4） | init_db 在不可写目录失败；GatewayExecutor::new 曾通过 state::<DbPool>() 读未 manage 的 pool | v0.26.16 已修：setup 显式传 pool，仅在 pool 可用时初始化网关。复现→检查 app data 目录权限 |
Windows MSI 构建挂掉 / light.exe 失败 | 迁移文件名含中文/全角标点/破折号或过长 | v0.26.21：迁移文件名必须 ASCII 短名 V###__*.sql |
| macOS 公证失败 | Apple Developer 协议过期 / 证书密码带尾随空格 | 续签协议；GitHub Secret APPLE_CERTIFICATE_PASSWORD 必须正好 28 字符无尾随空白 |
cargo +nightly fmt -- --check 跨平台不一致 | format_strings 在 macOS/Windows nightly 行为不同 | rustfmt.toml 已注释禁用 format_strings；不要重新启用 |
| LanceDB 持久化构建冲突 | Arrow 依赖与当前工具链冲突 | 长期 blocked；当前用 SQLite 向量持久化兜底 |
| 前端 E2E 在 settings 页 IPC 挂起 | E2E 跑在 Vite dev server 上，缺真实 Tauri 后端 | CI 中 E2E continue-on-error: true；本地 E2E 仅测前端行为 |
推理模型生成空 {} JSON | 思考链里的花括号被 find('{') 误判 | v0.23.49：strip_reasoning_blocks + extract_first_json_object 跳过空对象 |
cargo tauri build 在本机产出（macOS）：src-tauri/target/release/bundle/dmg/StoryMoss_<ver>_aarch64.dmg。
CI 矩阵：Ubuntu→.deb、Windows→.msi、macOS→.dmg（见 .github/workflows/build.yml 的 tauri-build job）。
sf-validation-and-qa。sf-run-and-operate。sf-debugging-playbook。cat rust-toolchain.toml（Rust 版本是否仍 1.95.0）node -v（是否 20）cd src-frontend && npm ci && npm run build（前端能否构建）cd src-tauri && cargo check（后端能否编译）grep devUrl src-tauri/tauri.conf.json（devUrl 是否指向 5173）rust-toolchain.toml、src-frontend/package.json 依赖版本、.github/workflows/build.yml 的 runner/密钥名、系统包列表。