lov-optimize-tauri-backend

# Tauri 后端调优 · Tauri Backend Tuner Use this skill to turn a growing Tauri backend into a smaller, more stable, more pleasant development surface. The goal is not magical Rust HMR. The goal is to reduce how often Rust changes are needed, make Rust restarts less disruptive, and keep the Tauri command boundary small, typed, and auditable. ## Triggers ### Activate when - “lib.rs 太大”“commands 太多”“降低到 100 个以内”“Tauri 后端优化” - "optimize-tauri-backend", "Tauri backend refactor", "Tauri dev reload", or a question about Tauri hot reload and Rust-side restarts. - The user is developing with `pnpm tauri dev` / `npm run tauri dev` and Rust file changes keep closing and reopening the app. - `src-tauri/src/lib.rs` has become a God file. - The app exposes 100+ or 200+ `#[tauri::command]` functions. - Frontend code scatters raw `invoke("command_name")` strings across many components. - Long-running `invoke` / `Channel` calls cause stale callback warnings after reload or HMR. - The user wants backend modularization, command consolidation, better dev scripts, or restart-state recovery. ### Do not activate when - The issue is frontend-only Vite/React HMR with no Rust or Tauri backend change. - A running app is slow, drains battery, or grows memory: use `lov-app-optimizer`. - The request is only to move frontend reads onto a shared query cache: use `lov-install-tanstack-query`. - Release builds, signing, or auto update: use `lov-app-release` or `lov-app-delta-updater`. ## Skill Group Composition Read `references/skill-composition.md` before routing to or extending an adjacent Skill. ## Core Position State this clearly when asked about hot reload: | Surface | Dev behavior | |---|---| | Frontend Vite / React | real HMR | | Rust / Tauri backend | recompile + restart native process | | Best optimization | separate stable Tauri shell from volatile domain logic, then make restarts cheap | Do not promise Rust backend HMR inside Tauri. Tauri's Rust-side "hot reload" means watch, rebuild, and restart. ## Workflow ### Step 1: Read Local Rules First Before changing files, inspect project instructions and config: ```bash pwd find .. -name AGENTS.md -print find .. -name CLAUDE.md -print rg -n "beforeDevCommand|devUrl|frontendDist|tauri dev|--no-watch|invoke\\(|#\\[tauri::command\\]|generate_handler" package.json src-tauri src 2>/dev/null ``` Honor local constraints. If the repo says not to run `pnpm build`, do not run it. Prefer `rg` and small file reads. Do not revert unrelated user changes. ### Step 2: Baseline the Backend Collect objective numbers before proposing or editing: ```bash wc -l src-tauri/src/lib.rs 2>/dev/null find src-tauri/src -maxdepth 3 -type f -name "*.rs" -print0 | xargs -0 wc -l | sort -n | tail rg -n "#\\[tauri::command\\]" src-tauri/src | wc -l rg -n "generate_handler!|invoke\\(" src-tauri/src src 2>/dev/null ``` Report: - `lib.rs` line count. - Largest Rust files. - Number of Tauri commands. - Whether command registration lives inside startup code. - Whether frontend uses a centralized invoke adapter. - Known long IPC streams or background tasks. ### Step 3: Classify the Problem Use these buckets: | Bucket | Symptom | Preferred fix | |---|---|---| | Dev loop | Rust edits restart the app during UI work | add no-watch dev script | | God module | `lib.rs` has thousands of lines | split into real Rust modules | | Command sprawl | 100+ command functions | consolidate by domain with typed routers | | Invoke sprawl | raw command strings everywhere | frontend invoke adapter / API layer | | Long IPC | stale callback warnings after reload | stream id + cancel + send-error stop | | Restart pain | route/session lost after app restart | dev resume state + flush pending saves | | Compile pain | small domain edits rebuild huge surfaces | move volatile logic out of Tauri shell | ### Step 4: Improve the Dev Loop Add scripts without removing the existing full dev command: ```json { "scripts": { "dev:web": "vite", "dev:app": "tauri dev", "dev:app:no-watch": "tauri dev --no-watch" } } ``` Document usage: - `dev:app`: full Tauri development with Rust watcher. - `dev:app:no-watch`: frontend-focused development; Vite HMR stays active and Rust file changes do not restart the app. - `dev:web`: pure web frontend when the app supports browser-only work. Keep the existing `pnpm tauri dev` route working unless the user explicitly asks to remove it. ### Step 5: Modularize the Rust Backend Goal: `src-tauri/src/lib.rs` should be a thin entrypoint. Target shape: ```rust mod app; mod diagnostics; mod pty_manager; pub use app::run; ``` Recommended backend shape: ```text src-tauri/src/ ├── lib.rs ├── app/ │ ├── mod.rs │ ├── run.rs │ ├── command_registry.rs │ ├── command_routers.rs │ ├── settings_core.rs │ ├── session_cache.rs │ ├── session_listing.rs │ └── ... └── shared_runtime_modules.rs ``` Rules: - Prefer real `mod` modules over long-term `include!`. - During large migrations, a temporary `include!` split is acceptable only as a compile-preserving checkpoint. Convert it to real modules before finishing. - Keep each file under roughly 1000 lines unless the user sets a stricter threshold. - Move `generate_handler!` out of `run.rs` into `command_registry.rs`. - Keep `run.rs` focused on app lifecycle, plugins, menus, windows, and watchers. ### Step 6: Reduce Commands Without Destroying the Boundary Do not replace 200 commands with `do_anything(action, payload)`. That removes type and permission boundaries. Good consolidation pattern: ```rust #[tauri::command] async fn settings_command(action: String, payload: serde_json::Value) -> Result<serde_json::Value, String> { match action.as_str() { "patch_settings" => { /* typed deserialize + validate */ } "get_settings" => { /* typed return */ } _ => Err(format!("unknown settings action: {action}")), } } ``` Better when possible: ```rust #[derive(Deserialize)] #[serde(rename_all = "camelCase", tag = "kind")] enum SettingsPatch { SetEnv { key: String, value: String }, DeleteEnv { key: String }, TogglePlugin { plugin_id: String, enabled: bool }, } ``` Recommended domains to consolidate: | Domain | Typical router | |---|---| | templates / marketplace install | `template_command` | | file utilities | `file_command` | | PTY lifecycle | `pty_command` | | workspace state | `workspace_command` | | MaaS/provider settings | `maas_command` | | settings/env/permissions/plugins | `patch_settings` or `settings_command` | Keep explicit commands for: - High-risk operations where an explicit name improves auditability. - Commands with distinct permission or capability requirements. - Public app API surfaces that should remain stable. Target: under 100 commands for medium-sized apps, lower only if domain routers stay typed and auditable. ### Step 7: Centralize Frontend Invokes Create one adapter such as `src/lib/tauri.ts`: ```ts import { invoke as tauriInvoke, type InvokeArgs, type InvokeOptions } from "@tauri-apps/api/core"; const COMMAND_ROUTES: Record<string, { command: string; action: string }> = { install_skill_template: { command: "template_command", action: "install_skill_template" }, pty_write: { command: "pty_command", action: "pty_write" }, }; export function invoke<T>(cmd: string, args?: InvokeArgs, options?: InvokeOptions): Promise<T> { const route = COMMAND_ROUTES[cmd]; if (!route) return tauriInvoke<T>(cmd, args, options); return tauriInvoke<T>(route.command, { action: route.action, payload: args ?? {} }, options); } ``` Then replace component imports from `@tauri-apps/api/core` with the app adapter. Use TanStack Query or a local query wrapper for server-state reads. Keep imperative side effects imperative. ### Step 8: Fix Long IPC and Reload Warnings When a command streams via `Channel`, use a request id and cancellation: Frontend: ```ts const streamId = crypto.randomUUID(); const channel = new Channel<Event>(); invoke("list_items_streamed", { streamId, onEvent: channel }); return () => { invoke("cancel_items_stream", { streamId }).catch(() => {}); }; ``` Also cancel on HMR / pagehide: ```ts if (import.meta.hot) { import.meta.hot.dispose(() => cancelStream("hmr-dispose")); } window.addEventListener("pagehide", () => cancelStream("pagehide")); ``` Rust: ```rust static STREAM_CANCELS: LazyLock<Mutex<HashMap<String, Arc<AtomicBool>>>> = LazyLock::new(|| Mutex::new(HashMap::new())); ``` Rules: - `invoke` should resolve quickly after starting a background stream. - Every stream has a `streamId`. - Cleanup removes the stream token. - Sending to a dead channel must stop the loop. - HMR / route unmount / pagehide should cancel active streams. - Do not hide stale callback warnings globally with `console.warn = ...`. ### Step 9: Restore State After Dev Restarts Make restarts less disruptive: - Persist current hash in development. - Persist active workspace conversation/session id. - Flush debounced workspace saves on `pagehide`, `visibilitychange`, and HMR dispose. - On reload, if the app lands on an empty/default hash, restore the last hash. - For expensive session lists, keep a memory/query cache and re-stream in the background. Keep this dev-oriented unless the product requires production resume semantics. ### Step 10: Verify Run only checks allowed by local instructions: ```bash cargo fmt CARGO_TARGET_DIR=target/codex-check cargo check pnpm exec tsc --noEmit --pretty false ``` Use a separate `CARGO_TARGET_DIR` when the user's `tauri dev` process holds the normal Cargo build lock. Report: - `lib.rs` line count. - Largest Rust file count. - Tauri command count. - Rust check result. - TypeScript check result, including unrelated existing blockers. - Scripts added and how to use them. ## Output Checklist Final answer must include: - What changed in dev scripts. - What changed in backend module/command structure. - What changed in IPC/restart lifecycle. - Exact verification commands run. - Any remaining warnings or blocked checks. ## Runtime context (shared) 运行前读取本 Skill 包的 `skill.yaml`，由宿主提供 `skill-runtime/v1` 上下文。字段解析顺序为：当前请求、项目上下文、个人 Preferences、品牌 Profile、通用默认值。 - 只使用 Manifest 声明的字段；Profile 保存公开品牌事实，Preferences 保存个人工作偏好。 - `required: true` 字段缺失时，按 Manifest 的问题配置向用户提出一个聚焦问题；用户明确同意后再保存回答。 - 报错提供可复制的 `context_id`、字段路径与来源，诊断内容避开秘密、完整私人路径和原始配置。 ## 通用反馈闭环 用户在 Skill 驱动任务中提出修改意见时，继续当前产物前必须执行： 1. 先判断意见是 `task-specific`（仅本次）还是 `reusable`（可跨任务复用）。 2. `task-specific` 只修改当前任务，不改 Skill。 3. `reusable` 先确定作用域：领域规则先更新对应 canonical Skill；适用于所有 Skill 的规则先更新共享规范。 4. 完成规则更新、版本、lint 与分发核验后，再把修改应用到当前任务。 5. `reusable` 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。