模板开发和使用

使用 CLI 创建项目

AgentDock CLI 支持交互式和参数化两种方式创建项目。

交互式创建：

npx @cogito.ai/cli init

交互步骤：

1. 输入项目名称
2. 选择模板（web-nextjs）
3. 选择数据层（supabase 或 drizzle）
4. 输入 Supabase schema 名称（默认 public）
5. 选择包管理器
6. 确认后创建

参数化创建（适用于 CI/Agent 模式）：

npx @cogito.ai/cli init \
  --name my-app \
  --template web-nextjs \
  --data-layer supabase \
  --schema public

创建完成后进入项目目录，按 CLI 提示完成初始化。

本地设置

# 安装依赖
pnpm install

# 设置环境变量
cp .env.example .env.local
# 使用你的 Supabase 凭据编辑 .env.local：
# NEXT_PUBLIC_SUPABASE_URL=your-project-url
# NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
# SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# NEXT_PUBLIC_APP_URL=http://localhost:3000
# NEXT_PUBLIC_DOCS_URL=http://localhost:3002  # 文档站地址，用于应用内帮助链接

# 运行开发服务器
pnpm dev

NEXT_PUBLIC_DOCS_URL 环境变量用于应用内的帮助/文档链接指向正确的文档站地址。本地开发时设为本地文档站地址，生产部署时设为生产文档站地址。

验证命令

# 类型检查
pnpm check-types

# 代码检查（包含 Layer 2 约束检查）
pnpm lint

# 生产构建
pnpm build

# 格式检查
pnpm format

配置

Supabase 设置

1. 在 supabase.com 创建新的 Supabase 项目
2. 在 Authentication → Providers 中启用 Email 提供者
3. 启用 GitHub OAuth（可选）：
   • 注册 GitHub OAuth 应用
   • 将 Client ID 和 Secret 添加到 Supabase
4. 配置重定向 URL：
   • http://localhost:3000/auth/callback
   • https://your-domain.com/auth/callback

添加新的语言区域

1. 在 src/i18n/config.ts 中添加语言区域：

   export const locales = ['en', 'zh', 'ja'] as const

2. 创建翻译文件：messages/ja.json
3. 根据需要更新中间件

添加新功能

遵循四层模式：

1. 定义类型 于 src/core/types/
2. 定义仓库接口 于 src/core/repositories/（如需要）
3. 实现仓库 于 src/infra/db/
4. 创建 Server Actions 于 src/features/<feature>/actions.ts
5. 创建页面 于 src/app/[locale]/...
6. 添加翻译 于 messages/en.json 和 messages/zh.json

非目标（有意排除）

以下功能被有意排除，以保持模板的专注性：

• 数据库 ORM（Prisma、Drizzle）—— 直接使用 Supabase PostgREST 或自行添加
• 测试框架 —— 按需添加 Vitest/Jest
• 端到端测试 —— 按需添加 Playwright/Cypress
• 数据分析 —— 按需集成 PostHog、Plausible 等
• 支付/账单 —— 需要时添加 Stripe
• 实时功能 —— 需要时添加 Supabase Realtime
• 管理面板 —— 单独构建或需要时添加

迁移指南

从 Create Next App 迁移

1. 将你的 app/ 页面复制到 src/app/[locale]/
2. 将共享组件移至 src/components/
3. 将业务逻辑提取到 src/features/
4. 将类型定义移至 src/core/types/
5. 将外部服务封装到 src/infra/

从其他模板迁移

1. 了解四层架构
2. 将现有结构映射到层契约
3. 为外部服务添加仓库接口
4. 将 Server Actions 移至 src/features/
5. 更新导入以遵循层边界