init-tauri-app

init-tauri-app

初始化一个新的 Tauri v2 项目，其中预先载入了在两个生产应用（cenno、cull）中验证过的惯例。将随版本更新的样板代码交给官方脚手架生成器，然后应用一层持久的惯例，并添加用户选择启用的可选模块。

适用场景

• “启动一个新的 Tauri 应用”“初始化一个 Tauri 项目”“搭建一个 Tauri 桌面应用”。

前置条件（搭建前验证）

• node 和 npm 在 PATH 中（node --version）
• cargo 和 rustc 在 PATH 中（cargo --version）
• 仅在选择 Swift sidecar 模块时需要 macOS 和 Xcode CLT

流程

1. 收集输入（AskUserQuestion）

一次性询问：

• 应用名称（kebab-case）。验证 ^[a-z][a-z0-9-]*$。
• 标识符（反向 DNS 格式，默认为 com.glebkalinin.<name>）。
• 目标目录（默认为 ~/ai_projects/<name>）。如果该目录存在且非空，则中止。
• 前端框架： react-ts | svelte-kit | vanilla-ts。
• 模块（多选）：CLI+MCP · SQLite · Tray/Updater · Release/Preflight · Swift sidecar。
• JTBD 产物（可选）： jtbd.json 的路径。如果未提供，该技能会自动查找 ./jtbd.json，然后查找 ~/jtbd/<name>/jtbd.json。请参阅步骤 1.5。

如果选择了 Swift sidecar，但主机不是 macOS，或 xcrun --find swift 执行失败：发出警告并移除该模块。

1.5 导入 JTBD（可选，增补）

1. 解析产物路径，采用第一个命中的路径：显式路径 → ./jtbd.json → ~/jtbd/<name>/jtbd.json。 如果均未找到，则跳过整个步骤（搭建过程将使用空的产品上下文，不报错）。
2. **确认：**展示产物的 hook，并在使用前询问用户是否确认。若用户拒绝，则跳过。
3. **验证：**产物必须能解析，并包含 name、hook、jtbd。否则发出警告并跳过 导入（绝不中止搭建）。render-jtbd.sh 在输入无效时会退出并返回 3——将此情况视为“跳过”。
4. **预填：**如果产物有效，则将应用名称默认设为 name，将标识符默认设为 com.glebkalinin.<name> （如果尚未选择，仍需在步骤 1 中向用户确认）。
5. 这些产物会在步骤 3（核心层）中写入——请参阅其中的 JTBD 部分。

2. 搭建基础项目

cd <parent-of-target>
npm create tauri-app@latest <name> -- --template <framework> --manager npm --yes

然后运行 cd <target> && npm install。

**已知上游问题（当前 rustc + Tauri 2.11.x）：**裸搭建项目首次执行 cargo check 时，可能会因 cookie/time 报错 error[E0119]（传递依赖 cookie 0.18.1 与 time 0.3.48）。 这不是技能缺陷——所有全新的 create-tauri-app 项目都可能遇到此问题。如果发生，请在 src-tauri/ 中执行一次：cargo update -p time --precise 0.3.47，然后重新检查。

3. 应用核心层

将 assets/core/ 中的每个文件复制到项目中，并按照下表重命名， 然后运行基线门禁。在 AGENTS.md 和 README 中替换 <name>（以及令牌出现时的 <identifier>）。

资源	目标路径
core/AGENTS.md	AGENTS.md
core/CLAUDE.md	.claude/CLAUDE.md
core/gitignore	.gitignore（合并：仅追加尚未存在的项目专用行；跳过已存在的行，包括注释标题）
core/rust-toolchain.toml	src-tauri/rust-toolchain.toml
core/node-version	.node-version
core/mcp.json	.mcp.json
core/capabilities/default.json	src-tauri/capabilities/default.json（覆盖）
core/scripts/check-versions.sh	scripts/check-versions.sh（chmod +x）
core/README.md	README.md
core/CONTRIBUTING.md	CONTRIBUTING.md

如果在步骤 1.5 中确认了 JTBD 文档，还需：

• 通过 scripts/render-jtbd.sh <artifact> assets/jtbd/PRODUCT.md.template <artifact-path>， 将 assets/jtbd/PRODUCT.md.template 渲染为 docs/PRODUCT.md。
• 将 assets/jtbd/guardrails-check.md.template 渲染为 docs/internal/guardrails-check.md。
• 渲染 assets/jtbd/agents-product-section.md.template，并将其插入 AGENTS.md 中第一个标题之后（让产品上下文位于文件开头）。
• 将该文档原样复制到项目根目录的 jtbd.json（绝不修改源文件）。
• 字段与目标路径的对应详情：assets/jtbd/jtbd-map.md。

创建空的受版本控制目录 docs/internal/.gitkeep 和 docs/.gitkeep。 启用 TS 严格模式：确保 tsconfig.json 中的 strict、noUnusedLocals、noUnusedParameters 均为 true。

**门禁：**运行 cd src-tauri && cargo check 和 cd .. && npm run build。两项都必须通过后才能添加模块。

4. 组合所选模块

对每个所选模块，按以下顺序——cli-mcp、sqlite、tray-updater、swift-sidecar、 release-preflight——打开 assets/modules/<m>/INSERT.md 并严格按其中说明操作：该文件列出了要复制的文件、要合并到 src-tauri/Cargo.toml [dependencies] 的 Cargo 依赖项，以及 src-tauri/src/lib.rs（tauri::generate_handler![...]）和 src-tauri/src/main.rs 中的插入位置。

**每个模块应用后：**运行 cd src-tauri && cargo check。如果失败，请在继续之前修复刚应用的合并内容（失败原因会定位到当前模块）。对于包含前端或脚本部分的模块，还要运行相应 INSERT.md 中指定的检查。

5. 最终验证与交接

• cd src-tauri && cargo check → 必须通过
• npm run build → 必须通过
• bash scripts/check-versions.sh → 必须通过
• 提供以下命令选项：git init && git add -A && git commit -m "chore: scaffold via init-tauri-app"。
• 打印摘要：框架、已应用的模块、跳过的模块（附原因）、后续命令（npm run tauri dev）。