تشغيل أي مهارة في Manus بنقرة واحدة

ابدأ الآن

sf-build-and-env

النجوم٥٧

التفرعات١٤

آخر تحديث١١ يوليو ٢٠٢٦ في ٠١:٣٨

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

التثبيت

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

تشغيل في Manus

المصدر

91zgaoge

91zgaoge/StoryMoss

فتح مستودع GitHub عرض مستودعات المنشئ

تنزيل

تشغيل في Manus

المهن ذات الصلةSOC

استنادا إلى تصنيف SOC المهني

مطوّرو البرمجياتمهن الحاسوب والرياضيات·SOC 15-1252

SKILL.md

readonly

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

StoryMoss 构建与环境

前置依赖

工具	版本	来源	备注
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）。

何时 NOT 用本技能

跑测试的具体命令与门槛 → sf-validation-and-qa。
运行时日志/产物落点 → sf-run-and-operate。
CI 失败排查 → 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/密钥名、系统包列表。
最后核对：2026-07-07，v0.26.23。

المزيد من هذا المستودع

نفس المستودع

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-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

sf-debugging-playbook

91zgaoge/StoryMoss

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

2026-07-1157

StoryMoss 构建与环境

前置依赖

工具

版本

来源

备注

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 跳过空对象

跨平台构建产物

何时 NOT 用本技能

跑测试的具体命令与门槛 → sf-validation-and-qa。

运行时日志/产物落点 → sf-run-and-operate。

CI 失败排查 → 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/密钥名、系统包列表。

最后核对：2026-07-07，v0.26.23。