| name | t-init |
| description | Initialize a full-stack project skeleton with Rust backend (Axum + SeaORM + Redis) and React frontend (TypeScript + TanStack + Tailwind). |
| argument-hint | <project-name> |
| allowed-tools | ["AskUserQuestion","Read","Glob","Grep","Write","Bash","Agent","WebSearch","mcp__context7__resolve-library-id","mcp__context7__query-docs"] |
项目初始化
初始化一个全栈项目骨架：Rust 后端 (Axum + Sea-ORM + Redis) + React 前端 (TypeScript + TanStack + Tailwind)。
适用范围
仅在以下场景使用：
- 用户明确执行
/t-init <project-name>
- 用户要求创建新项目、初始化全栈项目骨架
- 用户提到 "搭建项目""新建项目""项目初始化"
不要用于：
- 已有项目的增量开发
- 代码修改或重构
- 单纯的前端或后端初始化（如果明确只做一侧，提示用户本 skill 生成完整全栈）
参数
$ARGUMENTS = 项目名称（必须）- 仅允许英文、数字、连字符、下划线
- 拒绝
..、/、\
- 长度限制 1-50 字符
如果参数不合法，终止并提示：
请提供合法的项目名称。例如：/t-init my-project
占位符
整个流程中使用以下占位符：
{{PROJECT_NAME}} — 项目名称（kebab-case，如 my-project）{{PROJECT_NAME_PASCAL}} — PascalCase（如 MyProject）{{PROJECT_NAME_SNAKE}} — snake_case（如 my_project）
生成流程
Step 1: 验证参数（主 Agent）
- 校验
$ARGUMENTS 非空且合法
- 检查目标目录是否已存在同名目录
- 如果目录已存在且非空，询问用户是否覆盖
- 创建所有目录结构：
<project-name>/
├── backend/
│ ├── .cargo/
│ │ └── config.toml
│ ├── .config/
│ │ └── nextest.toml
│ ├── core/
│ │ └── src/
│ │ ├── domain/
│ │ └── infrastructure/
│ ├── api/
│ │ └── src/
│ │ └── application/
│ │ └── http/
│ ├── app/
│ │ └── src/
│ └── migrations/
├── frontend/
│ └── src/
│ ├── routes/
│ ├── components/ui/
│ └── lib/
├── demo/
│ └── e2e/
│ ├── fixtures/
│ ├── helpers/
│ └── pages/
└── scripts/
└── lib/
Step 2: 查询文档（主 Agent）
使用 Context7 查询关键依赖的最新文档，确保生成的代码使用当前最佳实践。
必查依赖（按顺序）
-
Axum — 路由、状态共享、中间件写法
mcp__context7__resolve-library-id → query: "axum web framework"mcp__context7__query-docs → query: "router, state sharing, middleware, serve static files"
-
Sea-ORM — 数据库连接和实体定义
mcp__context7__resolve-library-id → query: "sea-orm rust database"mcp__context7__query-docs → query: "database connection, entity generation, migration"
-
utoipa — OpenAPI 文档生成
mcp__context7__resolve-library-id → query: "utoipa rust openapi"mcp__context7__query-docs → query: "OpenApi derive, swagger ui, axum integration"
-
TanStack Router — 前端文件路由
mcp__context7__resolve-library-id → query: "tanstack router react"mcp__context7__query-docs → query: "file-based routing setup, vite plugin, createRouter"
-
TanStack Query — 数据请求
mcp__context7__resolve-library-id → query: "tanstack query react"mcp__context7__query-docs → query: "QueryClient setup, useQuery, QueryClientProvider"
如果某个 Context7 查询失败，降级到 WebSearch 搜索官方文档。如果都无法获取，基于已有知识生成但标注可能需要调整版本。
将查询结果中的版本号和 API 用法保存，传递给后续 subagent。
Step 3: 生成后端（backend-dev subagent）
按 ${CLAUDE_PLUGIN_ROOT}/protocols/subagent-dispatch.md 使用 Agent 工具调度 t-tools:backend-dev subagent。后续 frontend-dev / demo-dev 调用同理。
Subagent Prompt 模板：
初始化后端项目 {{PROJECT_NAME}}。
工作目录：<project-name>/backend/
任务：
- 读取后端模板文件 C:\code\ai\skills\skills\t-init\references\backend-template.md
- 按模板生成所有文件，替换以下占位符：
- {{PROJECT_NAME}} → <实际项目名>
- {{PROJECT_NAME_PASCAL}} → <PascalCase>
- {{PROJECT_NAME_SNAKE}} → <snake_case>
- 注意目录名为 core/，Cargo crate 名为 {{PROJECT_NAME}}-core
- Rust 代码中使用 {{PROJECT_NAME_SNAKE}}_core:: 引用核心 crate
- 根据 Context7 查询结果调整依赖版本（版本信息：[附上 Step 2 收集的版本]）
- 生成构建和测试配置文件：
a. backend/.cargo/config.toml（sccache 加速 + dev/release/test profile 优化）
b. backend/.config/nextest.toml（nextest 测试运行器配置）
关键约束：
- sqlx::postgres::PgPoolOptions 没有 connect_timeout 方法，用 acquire_timeout 替代
- OpenAPI 开关：enable_openapi = true 时暴露 /swagger，否则返回 404
- 健康检查：GET /health 检查数据库和 Redis 连接
- 自动迁移：启动时运行 SQLx 迁移
完成后执行 cargo check 验证编译。
后端关键特性：
- OpenAPI 开关：通过
config.toml 中的 server.enable_openapi 控制
- 健康检查：
GET /health 检查数据库和 Redis 连接
- 自动迁移：启动时自动运行 SQLx 迁移
- 静态文件服务：开发环境可代理前端，生产环境从
static_dir 提供前端文件
Step 4: 生成前端（frontend-dev subagent）
使用 Agent 工具调度 t-tools:frontend-dev subagent。
Subagent Prompt 模板：
初始化前端项目 {{PROJECT_NAME}}。
工作目录：<project-name>/frontend/
任务分两阶段：
## 阶段一：写入配置和自定义文件
读取前端模板文件 C:\code\ai\skills\skills\t-init\references\frontend-template.md，
生成以下自定义文件（需要 AI 编写的内容）：
必须由 AI 编写的文件（从模板生成）：
- package.json（含所有依赖）
- tsconfig.json
- vite.config.ts（Tailwind + TanStack Router + React 插件）
- openapi-ts.config.ts
- index.html
- src/main.tsx（React Query + TanStack Router 初始化）
- src/styles.css（Tailwind v4 主题 + 暗色模式）
- src/routes/__root.tsx（根布局 + Toaster + DevTools）
- src/routes/index.tsx（首页）
- src/lib/api-client.ts（Axios 实例）
- src/routeTree.d.ts（类型声明占位）
替换占位符：
- {{PROJECT_NAME}} → <实际项目名>
- {{PROJECT_NAME_PASCAL}} → <PascalCase>
## 阶段二：CLI 驱动的组件初始化
这些文件不要 AI 手写，必须通过 CLI 命令生成：
- npm install（安装所有依赖）
- npx shadcn@latest init -d --defaults
- 自动生成 components.json、button.tsx、utils.ts，更新 styles.css
- 自动安装额外依赖（@base-ui/react、next-themes 等）
- npx shadcn@latest add sonner --overwrite（生成 sonner.tsx）
- 生成的 sonner.tsx 使用 next-themes，main.tsx 已包含 ThemeProvider
- npm run type-check 验证
注意：routeTree.gen.ts 在首次 npm run dev 时才会生成，type-check 可能因此报错，这是正常的。
关键约束：
- 每个关键文件都要有中文注释说明用途、技术选择、修改指南
- package.json 的 scripts 要有注释说明每个命令做什么
- 根据 Context7 查询结果调整依赖版本（版本信息：[附上 Step 2 收集的版本]）
前端文件要求：
- 代码注释：每个关键文件都要有注释，解释用途、技术选择、修改指南
- 路由文件 (
__root.tsx) 要有注释说明文件路由的工作方式
main.tsx 要有注释说明 React 应用启动流程vite.config.ts 要有注释说明每个插件的作用- UI 组件（sonner 等）不要 AI 手写，必须通过
npx shadcn@latest add 生成
Step 5: 生成 Demo E2E 测试（demo-dev subagent）
使用 Agent 工具调度 t-tools:demo-dev subagent。
Subagent Prompt 模板：
初始化 Demo E2E 测试项目 {{PROJECT_NAME}}。
工作目录：<project-name>/demo/
任务：
- 读取 demo 模板文件 C:\code\ai\skills\skills\t-init\references\demo-template.md
- 按模板生成所有文件，替换占位符
- 生成后执行 npm install 安装依赖
- 运行 smoke test 验证 demo 环境正常
替换占位符：
- {{PROJECT_NAME}} → <实际项目名>
- {{PROJECT_NAME_PASCAL}} → <PascalCase>
- {{BASE_URL}} → http://localhost:8080
必须包含的 smoke test（smoke.e2e.ts）：
- 不依赖后端服务
- 验证 Playwright 能启动浏览器
- 验证页面导航基本功能
- 验证测试基础设施（fixtures、helpers）可正常导入
- 这个测试必须在 npm install 后立即可运行通过
完成后执行 cd demo && npx playwright install chromium && npx playwright test e2e/smoke.e2e.ts
确保 smoke test 全部通过。
Step 6: 生成项目本地 scripts（主 Agent）
将插件运行时脚本复制到目标项目根目录 scripts/，作为该项目后续环境启动、测试执行和 Demo 运行的优先入口。
复制来源：${CLAUDE_PLUGIN_ROOT}/scripts/
必须复制：
backend-test.pytest-start.pytest-stop.pydemo-start.pydemo-stop.pydemo-test-runner.pydemo-run-all.pydebug-test.pycleanup-demo.pycleanup-test-logs.pydemo-failure-summary.pylib/*.py
复制后按当前项目调整脚本默认配置：
- Docker 镜像、容器名和端口必须使用当前项目语义，避免多个初始化项目互相冲突。
- 默认数据库名、Redis 端口、后端/前端启动命令应与本次生成的
backend/、frontend/、demo/ 保持一致。
- 脚本文件名、主要 CLI 参数和输出 JSON/日志契约保持稳定，便于
/t-tools:t-* 流程复用。
- 运行类命令优先使用
uv run scripts/<name>.py；只有目标项目缺少对应脚本时，才回退到 uv run ${CLAUDE_PLUGIN_ROOT}/scripts/<name>.py。
Step 7: 生成 AGENTS.md、CLAUDE.md 和 README.md（主 Agent）
读取 references/agents-template.md 获取模板内容。
生成三个根目录文件：
生成后提示用户填写 AGENTS.md 顶部的项目描述占位符。
Step 8: 验证（主 Agent）
收集各 subagent 的验证结果，汇总报告：
- 后端：
cargo check 是否通过
- 前端：
npm install + type-check 是否通过（routeTree.gen.ts 错误除外）
- Demo：
npm install + smoke test 是否通过
- 检查所有文件都已创建（Glob 验证）
如果验证工具不可用，跳过并提示用户手动验证。
项目结构
生成的项目结构如下：
<project-name>/
├── backend/
│ ├── Cargo.toml # Workspace 根配置
│ ├── .cargo/config.toml # Cargo 构建优化（sccache、profile）
│ ├── .config/nextest.toml # Nextest 测试运行器配置
│ ├── config.example.toml # 配置模板
│ ├── migrations/ # SQLx 数据库迁移
│ │ └── 00001_init.sql
│ ├── core/ # 领域核心（crate: {{PROJECT_NAME}}-core）
│ │ ├── Cargo.toml
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── config.rs
│ │ ├── domain/
│ │ │ └── health.rs
│ │ └── infrastructure/
│ │ └── redis.rs
│ ├── api/
│ │ ├── Cargo.toml
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── config.rs
│ │ └── application/
│ │ └── http/
│ │ ├── mod.rs
│ │ ├── handlers.rs
│ │ ├── openapi.rs
│ │ ├── routes.rs
│ │ └── state.rs
│ └── app/
│ ├── Cargo.toml
│ └── src/
│ └── main.rs
├── frontend/
│ ├── package.json
│ ├── tsconfig.json
│ ├── vite.config.ts
│ ├── openapi-ts.config.ts
│ ├── index.html
│ └── src/
│ ├── main.tsx
│ ├── styles.css
│ ├── routes/
│ │ ├── __root.tsx
│ │ └── index.tsx
│ ├── components/
│ │ └── ui/
│ │ └── sonner.tsx # 由 npx shadcn add sonner 生成
│ ├── lib/
│ │ └── api-client.ts
│ └── routeTree.d.ts
├── demo/
│ ├── package.json # 依赖 playwright-unified-logger
│ ├── tsconfig.json
│ ├── playwright.config.ts
│ ├── eslint.config.js
│ ├── .gitignore
│ └── e2e/
│ ├── smoke.e2e.ts # 冒烟测试（不依赖后端）
│ ├── demo-basic.e2e.ts # 基础验证测试
│ ├── fixtures/
│ │ ├── demo-auth.fixtures.ts
│ │ └── test-data.ts
│ ├── helpers/
│ │ ├── auth.ts
│ │ └── environment-setup.ts
│ ├── pages/
│ │ ├── base-page.ts
│ │ └── login-page.ts
│ └── selectors.ts
├── scripts/
│ ├── backend-test.py
│ ├── test-start.py
│ ├── test-stop.py
│ ├── demo-test-runner.py
│ ├── demo-run-all.py
│ └── lib/
├── AGENTS.md # Claude Code 行为准则 + 项目描述
├── CLAUDE.md # 引用 AGENTS.md
└── README.md
输出文件清单
完成后确认以下文件存在：
后端（必须）：
前端（必须）：
脚本和文档：
AI 辅助配置（必须）：
Demo E2E 测试（必须）：
收尾输出
完成后在响应中明确说明：
- 项目路径
- 已生成的文件数量
- 各 subagent 验证结果（cargo check / npm install / smoke test）
- OpenAPI 开关位置（
config.toml → server.enable_openapi）
- UnifiedLogger 通过
npm install playwright-unified-logger 安装
- 项目本地脚本已生成到
scripts/，后续优先执行 uv run scripts/<name>.py
- Demo smoke test 运行命令（
cd demo && npx playwright test e2e/smoke.e2e.ts）
- 日志环境变量说明（
UNIFIED_LOG_LEVEL 等）
- AGENTS.md 和 CLAUDE.md 已生成，提醒用户填写项目描述
- 快速启动命令
- 需要用户手动完成的步骤（如复制 config、安装 Docker 等）
- 下一步建议（如
/t-prd 开始功能规划）
质量门禁
生成前逐项自检：
- 是否查询了 Context7 确认依赖版本和用法
- 后端目录名为
core/，crate 名为 {{PROJECT_NAME}}-core，Rust 代码用 {{PROJECT_NAME_SNAKE}}_core::
- 后端
.cargo/config.toml 是否已生成（sccache + profile 优化）
- 后端
.config/nextest.toml 是否已生成（测试运行器配置）
- 后端 OpenAPI 开关逻辑是否正确（enable_openapi 控制路由注册）
- 后端是否能编译通过（
cargo check）
- 前端 sonner 等组件是否通过 CLI 命令生成（不是 AI 手写）
- 前端代码是否有足够的中文注释
- demo smoke test 是否不依赖后端且能独立运行通过
- demo 中 import 路径是否正确指向
playwright-unified-logger（npm 包）
- 配置文件是否有完整的注释说明每个字段
- 所有占位符是否已替换为实际项目名称
失败处理
- 参数缺失或非法：终止并给出
/t-init <project-name> 示例
- 目标目录已存在且非空：询问是否覆盖
- Context7 查询失败：降级到 WebSearch，最终降级到已有知识
- cargo/npm 不可用：生成文件但跳过验证，提示用户手动检查
- Docker 不可用：提示用户需自行安装 PostgreSQL 和 Redis
- Subagent 失败：报告错误，提示用户手动重试对应步骤
- shadcn CLI 失败：降级为手动写入 sonner.tsx（从模板）
附加资源
