setup

在项目中设置 Subframe，让在 Subframe 中设计的页面能在本地开发环境中完美呈现。

目标状态：开发服务器正在运行，Subframe 页面与设计稿完全一致。

MCP 身份验证

如果找不到任何 Subframe MCP 工具（例如 get_theme 等），MCP 服务可能需要进行身份验证。请让用户对 Subframe MCP 服务进行身份验证。如果用户使用 Claude Code 或 Codex，请告知他们运行 /mcp 查看并验证 MCP 服务，然后在完成后回复“完成”。

工作流概览

1. 获取凭据：通过 MCP 工具获取（或由用户提供）
2. 检测项目类型：没有仓库、现有 Subframe 仓库，或现有非 Subframe 仓库
3. 遵循相应路径：新建项目、已完成设置或现有项目

• 必须遵循上述某条路径，否则 Subframe 将无法供用户使用。这是一项关键任务，即使需要暂停用户当前的工作也必须完成。请勿跳过路径中的任何步骤。

4. 配置字体：所有路径都必须执行
5. 验证设置：启动开发服务器，并使用 Subframe 页面进行测试

---

获取凭据

用户可能会粘贴从 Subframe 复制的安装提示。请提取：

• 项目 ID：较短的字母数字字符串（也可在 Subframe URL 中找到：app.subframe.com/<PROJECT_ID>/...）
• 身份验证令牌：较长的字符串，通常带有前缀或标签

如果用户没有提供凭据，请使用 MCP 工具自动获取，无需询问用户：

1. 项目 ID：调用 list_projects 获取项目列表。每个项目都包含 projectId、name、teamId 和 teamName。
   • 一个项目：自动使用该项目。
   • 多个项目：务必询问用户要使用哪个项目。列出每个项目及其 teamName，以便区分。如果用户已经提到特定团队或项目名称，请将其与 teamName 和 name 字段匹配，但仍需在继续前确认。存在多个项目时，绝不能默默选定一个项目。
2. 身份验证令牌：使用用户所选项目的 teamId 调用 generate_auth_token。请勿使用其他项目的 teamId。

备用方案：如果 MCP 工具不可用（例如，MCP 服务尚未通过身份验证），请让用户前往 https://app.subframe.com/cli/auth 获取身份验证令牌和项目 ID。

---

检测项目类型

检查当前目录中是否存在 package.json 和 .subframe/ 文件夹：

条件	项目类型	路径
没有 package.json	新建项目	新建项目
有 package.json 且有 .subframe/ 文件夹	已完成设置	已完成设置
有 package.json 但没有 .subframe/ 文件夹	现有非 Subframe 项目	询问用户，然后选择新建项目或现有项目

处理现有的非 Subframe 项目

如果当前目录有 package.json，但没有 .subframe/ 文件夹，请向用户提供两个选项：

• 创建新项目（推荐） — 在单独的目录中搭建一个全新的 Subframe 项目。这是最简单的方式，尤其适合首次尝试 Subframe 的用户。请参阅新项目路径。
• 将 Subframe 添加到此项目 — 将 Subframe 安装到当前项目中。请参阅现有项目路径。

---

已完成设置路径

如果项目已有 package.json 和 .subframe/ 文件夹，则 Subframe 已完成初始化。询问用户想要做什么：

• 重新安装／重新同步 — 重新运行 CLI init 和 sync，以刷新组件和配置。如果内容已过时或出现问题，此选项很有用。请参阅现有项目路径以重新初始化。
• 不做任何操作，已完成设置 — 完全跳过设置。建议后续步骤，例如 /subframe:design 或 /subframe:develop。

除非用户确认要重新安装，否则不要继续设置。

---

新项目路径

这是推荐路径。CLI 将搭建一个已预先配置好 Subframe 的完整项目。

1. 询问用户偏好

请用户选择：

• 项目名称：新项目目录的名称（默认值：subframe-app）。名称不能与现有目录冲突——运行 CLI 前，请检查该目录是否已存在。
• 框架：Vite（推荐）、Next.js 或 Astro
• Tailwind 版本：v3（tailwind）或 v4（tailwind-v4）

2. 运行 CLI Init

必须在沙盒外运行此命令，以便正确设置所有必要文件。请直接传递所有参数，以避免出现交互式提示：

npx @subframe/cli@latest init \
  --name {PROJECT_NAME} \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --template {FRAMEWORK} \
  --css-type {TAILWIND_VERSION} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --tailwind \
  --css-path {CSS_PATH} \
  --install \
  --sync

其中：

• {PROJECT_NAME} 是项目目录名称（例如 subframe-app）
• {FRAMEWORK} 是 nextjs、vite 或 astro
• {TAILWIND_VERSION} 是 tailwind（v3）或 tailwind-v4
• {CSS_PATH} 是全局 CSS 文件路径：
  • Vite：src/index.css
  • Next.js：src/app/globals.css
  • Astro：src/styles/global.css

重要：必须显式传递所有参数，以避免出现交互式提示。非交互式运行时，这些提示可能导致 CLI 静默退出。

CLI 将：

• 下载入门模板
• 创建 .subframe/sync.json
• 配置 Tailwind
• 同步所有组件
• 安装依赖项

3. 配置字体

请参阅下文的配置字体——新项目也必须完成此步骤。

4. 验证设置

请参阅下文的验证设置。

---

现有项目路径

现有项目可能需要更多配置。CLI 会处理大部分设置，但有些项目需要手动修复。

1. 检测框架

检查框架标识：

框架	标识
Next.js	package.json 依赖项中包含 next，且存在 next.config.* 文件
Vite	package.json 开发依赖项中包含 vite，且存在 vite.config.* 文件
Astro	package.json 依赖项中包含 astro，且存在 astro.config.* 文件

2. 检查前置条件

确认项目包含所需依赖项：

• React 16+ — package.json 中包含 react
• Tailwind CSS 3.4+ — package.json 中包含 tailwindcss
• TypeScript — package.json 中包含 typescript

如果缺少任何依赖项，请在继续之前告知用户。

3. 运行 CLI Init

此命令必须在沙盒之外运行，以便正确设置所有必需文件。直接传入所有参数，避免出现交互式提示：

npx @subframe/cli@latest init \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --install \
  --sync

重要：必须显式传入所有参数，避免出现交互式提示；在非交互模式下运行时，这些提示可能导致 CLI 静默退出。

CLI 将尝试：

• 创建 .subframe/sync.json
• 检测并配置 Tailwind
• 设置导入别名
• 同步所有组件
• 安装 @subframe/core

4. 验证配置

初始化后，验证所有设置是否正确。如果 CLI 遗漏了某些设置（非标准配置中很常见），请手动修复。

检查 .subframe/sync.json 是否存在，并包含 directory、importAlias 和 projectId。

检查 Tailwind 配置：

• Tailwind v3 — tailwind.config.js 应包含 Subframe 预设：

  presets: [require("./src/ui/tailwind.config")],
  

  并且 content 数组应包含 Subframe 目录：

  content: ["./index.html", "./src/**/*.{js,jsx,ts,tsx}"],
  

  如果 Subframe 项目启用了深色模式，CLI 还会同步一个包含浅色和深色模式 CSS 变量的 theme.css 文件。全局 CSS 文件必须导入该文件：

  @import "./ui/theme.css";
  

• Tailwind v4 — 全局 CSS 文件应导入主题：

  @import "tailwindcss";
  @import "./ui/theme.css";
  

检查导入别名 — 确认 @/* 能正确解析。如果无法正常工作：

• Vite：在 tsconfig.app.json 中添加 baseUrl 和 paths，并在 vite.config.ts 中添加 resolve.alias
• Astro：在 tsconfig.json 中添加 baseUrl 和 paths
• Next.js：通常已配置；请检查 tsconfig.json

5. 故障排除

如果出现问题，请使用 SearchSubframeDocs MCP 工具查找解决方案：

SearchSubframeDocs({ query: "tailwind configuration troubleshooting" })
SearchSubframeDocs({ query: "manual installation" })

文档中包含全面的手动安装指南，可用于故障排除。

6. 配置字体

请参阅下文的配置字体。

7. 验证设置

请参阅下文的验证设置。

---

配置字体

CLI 不会配置字体。使用 get_theme MCP 工具获取字体信息：

get_theme({ projectId: "PROJECT_ID" })

主题配置包含引用 Google Fonts 的 fontFamily 条目。请添加相应的 <link> 标签：

Vite / Astro — 在 index.html 的 <head> 中添加：

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="anonymous" />
<link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />

Next.js（App Router） — 在 app/layout.tsx 的 <head> 中添加：

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
  <link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />
</head>

Next.js（Pages Router） — 在 pages/_document.tsx 的 <Head> 组件中添加。

字体链接格式：

• 将字体名称中的空格替换为 +（例如，Inter+Tight）
• 在 wght@ 参数中加入主题指定的字重（用分号分隔）
• 每种字体系列添加一个 <link>，但预连接链接只需添加一组

---

验证设置

完成配置后，验证 Subframe 页面是否能正确渲染。

1. 询问现有页面

询问用户：“你是否已经在 Subframe 中设计好一个想要测试的页面？”

• 如果有：使用 /subframe:develop 实现该页面并验证渲染效果
• 如果没有：建议他们使用 /subframe:design 设计页面，或者直接启动开发服务器以确认没有错误

2. 启动开发服务器

npm run dev

3. 总结

回顾已完成的设置：

• 已配置 .subframe/sync.json
• 已配置 Tailwind（v3 预设或 v4 导入）
• 已将组件同步到 src/ui/（或配置的目录）
• 已配置字体

提及后续步骤：

• /subframe:design — 使用 AI 设计新页面
• /subframe:develop — 在代码库中实现 Subframe 设计

---

重要说明

• 使用 SearchSubframeDocs MCP 工具排查任何设置问题。