project-init-orchestrator

项目初始化编排器

选择最小且安全的设置路线。对于新的 Shipshit.dev 产品仓库，优先使用 npx @shipshitdev/v0 作为主要脚手架生成工具，然后自定义并验证生成的工作区。对于现有仓库、修复任务或 v0 未涵盖的项目类型， 使用较底层的初始化技能。

授权范围

仅在用户请求和现有授权范围内操作；加载此技能不会赋予任何新权限。仅报告的请求必须保持仅报告， 遵守调用方对目标、主机、提供商和成本的限制，扩展范围前先询问，并将这些限制转达给委派对象。

约定

输入：

• 目标项目路径和项目名称
• 项目类型：新的 Shipshit.dev 产品、现有仓库、仅文档、库或自定义项目
• 项目目录和产品名称；产品范围或 PRD 风格的简介
• 所需的应用界面、路由、Agent 交接方式（codex、claude 或 skip-agent）以及 GitHub 设置

输出：

• 选定的初始化路线
• 已委派的技能列表或使用的 v0 命令（v0 命令或交互路线）
• 生成的工作区摘要；创建或修改的文件/目录
• 质量门禁和启动状态
• 应用专属自定义的后续任务和剩余的手动设置

创建/修改：

• 通过 npx @shipshitdev/v0 创建的新产品仓库：由 v0 生成的 Bun/Turbo 仓库，包含 .agents/skills、 .agents/memory、.claude、.codex、apps、packages 和 .v0 文件
• v0 生成完成后仅在自定义过程中创建应用专属文件
• 委派后修改现有仓库中的 .agents/、.claude/、.codex/、lint、test 和脚手架文件

外部副作用：

• 使用 v0 或委派的设置技能时，可能会安装依赖项并启动 apps/web
• 仅在运行带有 GitHub 标志的 v0 命令时，才可能创建 GitHub 仓库或议题

需要确认：

• 创建 GitHub 仓库或议题之前
• 在当前工作区之外或非空目录中运行设置之前
• 覆盖现有 Agent/配置文件，或 v0 完成后生成的应用文件之前

委派给：

• agent-folder-init：适用于仅需 AI 项目上下文的现有仓库（不适用于 v0 生成的仓库）
• linter-formatter-init、testing-cicd-init、husky-test-coverage 和 shadcn（设置模式）：适用于仓库修复或 v0 后的自定义
• scaffold：适用于在现有代码库中添加小型模块/组件

适用场景

当用户执行以下操作时，此技能会自动激活：

• 从零开始启动新项目
• 希望通过一条命令完成 Shipshit.dev 产品的完整设置
• 需要 AI 优先的开发基础设施和代码质量工具
• 表示“初始化项目”“设置新项目”“引导项目”
• 希望在多个项目中保持一致的设置

编排的技能

顺序	技能	用途	必需
1	npx @shipshitdev/v0	新的 Shipshit.dev 产品仓库	有条件
2	agent-folder-init	为现有仓库添加 AI 文档和规范	有条件
3	linter-formatter-init	ESLint/Biome + 格式化工具 + 提交前修复	有条件
4	testing-cicd-init / husky-test-coverage	测试和 CI 门禁	可选
5	scaffold	增量添加模块/组件	可选

路线选择

按以下顺序选择：

1. 新的 Shipshit.dev 产品仓库：运行 npx @shipshitdev/v0。
2. 新的非产品仓库：仅搭建所需的仓库结构，然后添加 Agent 文档和门禁。
3. 缺少 AI 上下文的现有仓库：运行 agent-folder-init。
4. 质量门禁薄弱的现有仓库：仅运行 lint/test/CI 技能。
5. 需要添加单个功能/模块的现有仓库：找到 3 个以上示例后运行 scaffold。

对于由 v0 支持的设置，除非用户提供了所有输入，否则使用交互模式：

npx @shipshitdev/v0 <project-directory>

对于非交互式 Shipshit.dev 产品设置：

npx @shipshitdev/v0 <project-directory> \
  --scope "<product scope>" \
  --agent codex \
  --apps web,app,desktop,mobile,extension,cli \
  --routes overview,new-task,search,inbox,activities \
  --no-github

在 CI/冒烟测试中，或用户只希望写入脚手架时，使用 --skip-agent、--no-install 和 --no-start。

传统手动路线

仅在 v0 不适用或需要增强现有工作区时使用。除非 v0 不可用或用户明确绕过 v0，否则不要用于新的 Shipshit.dev 产品仓库。

技术栈：Next.js 16（proxy.ts）+ React 19 + TypeScript 6 + Tailwind v4 CSS-first（前端），NestJS 12 + Prisma 7/Postgres + Better Auth + Swagger（后端），Vitest 80% 覆盖率 + Biome + GitHub Actions CI，Bun 包管理器。所有依赖项的固定版本都位于 scripts/init-workspace.py 顶部的 V 表中；使用 npm view <pkg> version 刷新版本（Expo 包遵循 SDK 的 bundledNativeModules.json，而非最新版本）。

加载 references/legacy-manual-route.md，查看完整的分步工作流、生成的结构、关键代码模式和开发命令。辅助脚本位于 scripts/（init-workspace.py、add-api-collection.py、add-frontend-app.py）。生成后，运行 bun install，将 .env.example 复制到 api/.env，在 api/ 中运行 bun run prisma:migrate，运行 bun run prisma:generate（Prisma 7 的 migrate 不再构建客户端；每次更改架构后都要重新运行），并运行一次 bun run lint:fix，让 Biome 格式化生成的文件。使用 add-api-collection.py 添加的集合受 AuthGuard 保护，并根据会话限定为已登录用户，绝不使用请求输入中的用户信息。

用法

快速开始（推荐）

当用户说“初始化我的项目”或“设置新项目”时：

1. Ask for project context:
   - Project path (default: current directory)
   - New Shipshit.dev product or existing repo repair?
   - Product scope if using v0
   - App surfaces and routes if non-default
   - Agent to hand off to: codex or claude
   - Need existing-repo repair or incremental scaffolding?

2. Execute phases in order:
   v0 route OR existing-repo phases → verification

修复现有仓库

确定 v0 不是合适的路线后，才使用较低层级的技能：

1. agent-folder-init，用于 AI 文档和 Agent 配置。
2. linter-formatter-init，用于修复 lint/格式化偏差。
3. testing-cicd-init 或 husky-test-coverage，用于测试和 CI 门禁。
4. scaffold，用于用户要求的模块、端点、组件或包。

路线对照表

请求	首选路线	备注
新的 Shipshit.dev 产品仓库	npx @shipshitdev/v0	默认路线。包含应用界面和 Agent 设置。
新的非产品仓库	最小化脚手架 + agent-folder-init	设置规模应与所请求的仓库相称。
现有仓库的 AI 上下文	agent-folder-init	不生成应用源代码。
现有仓库的质量门禁	Linter/test/CI 技能	仅修复缺失的门禁。
现有仓库的功能/模块	scaffold	先找到至少 3 个本地示例。

最佳实践

顺序安排

• 对于新的 Shipshit.dev 产品，先运行 v0。
• 对于现有仓库，先添加 AI 文档，再进行仓库专属修复。
• 如果 lint 和格式化设置都缺失，先设置 linter 和 formatter，再设置测试钩子。
• 只有在了解目标代码库的模式后，才运行 scaffold。

自定义

• 如果某个阶段已配置，可以跳过
• 各阶段均为幂等（可安全地重复运行）
• 编排完成后可以自定义配置

验证清单

编排完成后，验证：

• 所选路线符合用户请求
• 除非明确豁免，否则新产品仓库均通过 v0 创建
• 对现有仓库所做的更改仅限于委派的修复/添加
• 在适用时，bun lint、bun test 或仓库文档中说明的等效命令均可正常运行

交互示例

用户：“在 ~/projects/my-saas 设置我的新产品”

编排器响应：

Route: new Shipshit.dev product repo → v0.

npx @shipshitdev/v0 ~/projects/my-saas --agent codex --no-github

参考资料

• references/legacy-manual-route.md - 手动工作区工作流
• references/templates/ - 代码生成模板（NestJS 服务/控制器/e2e 测试规范、Better Auth guard/service/client、proxy.ts、React 组件/hook 测试规范、使用模拟身份验证客户端的前端测试设置）
• references/vitest.config.ts - 后端 Vitest 配置（80% 覆盖率，unplugin-swc）
• references/vitest.config.frontend.ts - 前端 Vitest 配置（jsdom）
• references/github-actions/ci.yml - CI/CD 工作流
• references/architecture-guide.md - 架构决策
• references/coding-standards.md - 编码规范
• references/deployment-guide.md - 部署指南

故障排除

阶段无法完成

• 检查是否已安装依赖项（node、python3）
• 确认对项目目录具有写入权限
• 检查是否存在冲突的配置

设置后出现 Lint 错误

• 运行 bun run lint:fix 自动修复
• 检查根目录中的 biome.json 是否与所用技术栈匹配
• 如果使用 TS，请检查 TypeScript 配置

预提交钩子未运行

• 手动运行 bunx husky install
• 检查 .husky/pre-commit 是否存在且可执行
• 确认 package.json 中的 prepare 脚本

prisma generate 或 bun run build 要求提供 DATABASE_URL

• 脚手架中的 api/prisma.config.ts 会直接读取 process.env.DATABASE_URL，因此 无需 .env 文件，generate 和 build 也能正常运行；只有 prisma migrate 和运行中的 API 需要该 URL。不要将其改为 env("DATABASE_URL")，否则未设置该变量时会抛出错误。