使用指南

创建项目

CLI 会从模板元数据读取数据层选项。web-tanstackstart 默认使用 SQLite：

npx @cogito.ai/cli init \
  --name my-internal-app \
  --template web-tanstackstart \
  --data-layer sqlite \
  --pm pnpm

使用 --data-layer supabase 可生成 Supabase Postgres 的环境变量模板。选择结果会写入 .env.example 的 DATA_PROVIDER。

可通过以下参数追加可选的 Mastra agent/workflow runtime：

npx @cogito.ai/cli init \
  --name my-internal-app \
  --template web-tanstackstart \
  --data-layer sqlite \
  --integrations mastra

生成后的 Mastra API 挂载在 /api，包含一个 agent 和一个确定性 workflow；UI 与交互内核仍然是 Astryx。默认不加入 Mastra Memory、LibSQL、DuckDB 或第二套持久化层。

模板支持 pnpm >=10.34.5 <13，推荐 12.4.1。生成项目不写精确 packageManager pin，因此不会触发 pnpm 自动版本切换；CLI 仍会强制模板只使用 pnpm。

嵌入已有 pnpm workspace

当目标目录匹配已有 pnpm-workspace.yaml#packages 时，CLI 默认使用 workspace mode：

npx @cogito.ai/cli init \
  --name my-internal-app \
  --template web-tanstackstart \
  --dir apps/my-internal-app \
  --mode auto

workspace member 不保留自己的 pnpm-workspace.yaml、pnpm-lock.yaml、.npmrc、packageManager 或 engines.pnpm。依赖和 lockfile 由 workspace 根统一管理。CLI 会生成 .agentdock/workspace.json，并在 AGENTS.md 顶部说明应从根执行安装和 pnpm --filter <package> check。

根 allowBuilds 不会自动改写。先应用 JSON 输出或 CLI 提示中的 requiredRootChanges，解决 rootConfigConflicts 后再从根执行 pnpm install。

安装与运行

standalone 项目支持 pnpm 10.34.5–12.x。本机版本低于 10.34.5 时先更新，或直接使用推荐的 npx 命令：

pnpm self-update 10.34.5
# 推荐版本
pnpm self-update 12.4.1
# 不修改全局版本
npx --yes --registry=https://registry.npmjs.org pnpm@12.4.1 install

cd my-internal-app
cp .env.example .env
pnpm install
pnpm dev

pnpm dev 会在启动 Vite 前自动执行待应用的 SQLite migration。生产环境执行 pnpm start 时不会隐式迁移，应在部署流程中显式执行 migration。

启用 Mastra 后，只有 agent generate/stream 需要 OPENAI_API_KEY；GET /api/agents 与 GET /api/workflows 无需模型密钥即可工作。生成的 src/mastra/auth.ts 是开发态默认放行 hook，生产暴露 /api 前必须替换为真实授权检查。扩展和安全边界见生成项目内的 docs/mastra.md。

访问 http://localhost:3000，根路径会跳转到默认的简体中文页面 http://localhost:3000/zh-CN；一级落地页是 /zh-CN，二级参考页是 /zh-CN/hello，全局偏好位于 /zh-CN/settings。

壳层没有顶部栏：导航是底部 pill，外观与语言控件位于 /{locale}/settings 路由。外观偏好通过同源 Cookie 持久化，使 SSR 能直接输出已选主题、避免闪烁；语言由 URL 前缀表示（/zh-CN 为默认，/en 为备选）。

数据库命令

pnpm db:generate
pnpm db:migrate
pnpm db:studio
pnpm db:generate:supabase
pnpm db:migrate:supabase

修改仓储行为时，必须同步检查 SQLite 与 Postgres schema 以及两套仓储实现。当 DATA_PROVIDER=supabase 时，开发启动不会自动执行 SQLite migration，并会提示显式运行 pnpm db:migrate:supabase。

验证

pnpm format:check
pnpm lint
pnpm check-types
pnpm test
pnpm build

完整门禁运行 pnpm check。路由树会在类型感知 lint、类型检查和生产构建前自动生成，干净 checkout 不需要手工预处理。

新增 Feature

先阅读 LLM.md。其中包含 agent 需要的架构规则、文件目录模板、import 边界和验证流程。

在 src/core 添加共享类型或仓储契约。
创建 src/features/<name>/__contract__.ts。
在 src/features/<name>/index.ts 定义公开 API。
在 feature 内添加测试。
只有持久化行为变化时才新增或修改 infra 仓储。
在 src/routes/$locale/ 添加路由。
所有用户可见文案同步加入 src/i18n/messages.ts 的全部语言目录。
UI 与主题工作遵循 DESIGN.md，并加载对应 Agent Skill。
页面组合共享布局原语：一级路由用落地页形态（PageContainer + 模块入口），二级页用 PageShell，配置与表单放进 SideDrawer。

Feature 不得直接 import infra/db，必须通过 provider 和仓储契约访问数据。

部署边界

默认 SQLite 模式需要持久文件系统，应部署在长期运行的 Node 进程或带持久卷的容器中。无状态/边缘平台不属于首版 SQLite 支持范围；需要远程数据库时应切换 Supabase Postgres。

web-tanstackstart 使用指南