install

在项目中安装 Subframe，让在 Subframe 中设计的页面能够在本地开发环境中像素级精准地呈现。

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

无需安装即可进行设计。 /subframe:design 可直接对云端 Subframe 项目进行操作，无需本地配置。准备好使用 /subframe:develop 将这些设计实现为代码时，再使用 /subframe:install。

MCP 身份验证

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

工作流概览

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

此命令必须在沙盒外运行，以便正确设置所有必需文件。请直接传入所有参数，避免 CLI 提示输入。对于未指定的内容，--yes 会采用安全的默认值：

npx @subframe/cli@latest init \
  --yes \
  --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 无需提示输入。在非交互模式下运行时（无 TTY，或使用 --yes），CLI 会使用你提供的标志和安全默认值；如果确实缺少必需值，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

此命令必须在沙盒外运行，以便正确设置所有必要文件。直接传入所有参数，避免 CLI 提示输入。对于未指定的内容，--yes 会采用安全的默认值：

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

重要：明确传入参数，避免 CLI 提示输入。在非交互模式下运行（没有 TTY，或使用 --yes）时，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 还会同步一个 theme.css 文件，其中包含浅色和深色模式的 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. 故障排除

如果遇到问题，请使用 search_docs MCP 工具查找解决方案：

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

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

6. 配置字体

请参阅下文的配置字体。

7. 验证安装

请参阅下文的验证安装。

---

配置字体

CLI 不会配置字体。调用 list_fonts({ projectId: "PROJECT_ID" }) 获取项目中的所有字体 — Google 字体（包含字重）和自定义字体（包含每个字面的字重、样式、格式和公开 url）。

Google 字体 — 只有 list_fonts 返回且 kind: "google" 的字体才能通过名称使用；请为它们添加 <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>，但只添加一组 preconnect 链接

自定义字体 — 在项目的全局 CSS 文件中为每个字面添加一条 @font-face 规则，并将其指向 list_fonts 返回的该字面的 url。将 format 映射为：woff → format("woff")，woff2 → format("woff2")，ttf → format("truetype")，otf → format("opentype")。

@font-face {
  font-family: "Font Name";
  src: url("https://.../font.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
}

可变字面的 weight 是 { min, max } 范围 — 使用这两个数字作为 font-weight 的值：

font-weight: 100 900;

为要添加的每个字面各写一条规则。

---

验证安装

配置完成后，验证 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 设计

---

重要说明

• 使用 search_docs MCP 工具排查安装问题。