bulk-import

通过发现磁盘上的文件、构建清单并通过 CLI 上传，将现有设计系统批量导入 Subframe。

仅当用户明确要求一次批量导入多个组件时，才使用此技能（例如：“使用批量导入技能上传我的所有组件”）。对于任何其他“将我的设计系统导入 Subframe”的请求，默认使用 /subframe:design 的增量式 design_component、design_snippet 和 write_design_document 工具。两种方式都会调用同一个底层 AI Agent，因此输出质量相同；只有当用户确实希望通过一次 CLI 调用批量提交多个组件时，批量导入才能节省编排时间。

可用性： 此功能目前仅对部分团队开放。如果 CLI 返回类似 "Design system import is not enabled for this team" 的错误，表示该功能尚未对用户的团队开放。请引导用户在此申请访问权限，或进行增量导入。不要重试或进一步排查——这是访问权限限制，不是 bug。

目标状态：所有设计系统文件都已上传到 Subframe 进行处理。

MCP 身份验证

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

凭据

CLI 需要身份验证令牌和项目 ID。如果用户尚未提供这些信息，请使用 MCP 工具自动获取：

1. 项目 ID — 调用 list_projects 获取项目列表。每个项目都包含 projectId、name、teamId 和 teamName。
   • 只有一个项目：自动使用该项目。
   • 有多个项目：始终询问用户要使用哪个项目。展示每个项目及其 teamName，以便区分。如果用户已经提到了特定团队或项目名称，请与 teamName 和 name 字段进行匹配，但仍须在继续操作前确认。存在多个项目时，切勿默默选择其中一个。
2. 身份验证令牌 — 使用用户所选项目的 teamId 调用 generate_auth_token。不要使用其他项目的 teamId。

项目 ID 也显示在任何 Subframe URL 中：app.subframe.com/<PROJECT_ID>/...

备用方案：如果 MCP 工具不可用，请引导用户访问 https://app.subframe.com/cli/auth 获取身份验证令牌和项目 ID。

---

工作流

1. 查找设计系统文件

我们只需要视觉／呈现层文件，也就是构成设计系统的可复用 UI 基元。跳过与业务逻辑、数据模型、API 调用或应用状态紧密耦合的内容。

包含：

• 纯 UI 组件（按钮、输入框、卡片、模态框、徽章等）
• 布局基元（容器、网格、堆栈等）
• 主题／样式文件
• Story 文件

排除：

• 获取数据、调用 API 或管理应用状态的组件
• 负责串联业务逻辑的页面级组件
• 非视觉类实用函数、钩子或辅助程序
• 测试文件（Story 文件除外）

使用 Glob 和 Read 工具查找文件。查找以下内容：

主题文件（全局样式）：

• tailwind.config.*
• 全局 CSS 文件（例如 globals.css、global.css、app.css、index.css）
• 设计令牌文件（例如 tokens.json、tokens.ts、theme.ts）

组件文件：

• 组件目录中的 React 组件文件（.tsx、.jsx）
• Story 文件（.stories.tsx、.stories.jsx、.stories.ts）
• 组件 CSS 模块

使用以下搜索策略：

1. 在项目根目录查找 tailwind.config.*
2. 在 src/styles/、src/、app/、styles/ 中查找全局 CSS
3. 在常见目录中查找组件：src/components/、components/、src/ui/、ui/、lib/components/

如果不确定某个组件是设计系统基元还是应用组件，请快速阅读文件；如果它导入了数据获取库、存储或 API 客户端，就跳过它。

2. 按组件分组文件

对于每个组件，将文件分为两类：

entrypoint — 主组件文件的路径。必须指向 sourceFiles 中的文件。

sourceFiles — 组件的主要实现：

• 包含标记和样式的组件源文件（.tsx、.jsx）

supportingFiles — 有助于了解组件的其他文件：

• Story 文件（.stories.tsx、.stories.jsx、.stories.ts）
• CSS 模块（.module.css、.module.scss）
• 文档文件（.md）

按逻辑上的设计系统组件分组，例如：Button.tsx 是源文件，而 Button.stories.tsx、Button.module.css 和 Button.md 是“Button”组件的支持文件。

3. 编写清单

如果 .subframe/ 目录不存在，则创建该目录，然后写入清单：

mkdir -p .subframe

将清单写入 .subframe/import-design-system.json：

{
  "theme": ["tailwind.config.ts", "src/styles/globals.css"],
  "components": [
    {
      "name": "Button",
      "entrypoint": "src/components/Button.tsx",
      "sourceFiles": ["src/components/Button.tsx"],
      "supportingFiles": ["src/components/Button.stories.tsx", "src/components/Button.module.css"]
    }
  ]
}

组件名称必须唯一。如果组件名称冲突，请询问用户希望如何解决，例如根据目录添加前缀。

4. 上传前显示摘要

运行 CLI 前，打印摘要，以便用户检查是否有问题：

• 组件名称列表
• 主题文件列表
• 文件总数

然后继续上传。如果发现问题，用户可以中断操作。

5. 提交导入

运行 CLI，提交设计系统以供导入。这会将文件上传到 Subframe，并启动异步导入任务——导入不会在当前操作中完成。

始终传递身份验证令牌，以免 CLI 进行交互式提示。

npx @subframe/cli@latest import -p {PROJECT_ID} --manifest .subframe/import-design-system.json --auth-token {TOKEN}

如果有文件缺失，CLI 将中止并报错。否则，告知用户导入已提交，将很快开始处理。

---

错误处理

• 如果 CLI 退出时出错，请向用户显示完整的错误输出
• 访问错误：如果 CLI 返回 "Design system import is not enabled for this team"，这不是 Bug 或身份验证问题——导入功能仅对特定团队开放。请告知用户，并引导他们在此处申请访问权限。不要尝试使用新令牌重试或采取变通方法。
• 身份验证错误：尝试使用 generate_auth_token 生成新令牌，或建议用户在 https://app.subframe.com/cli/auth 重新进行身份验证
• 网络错误：建议检查网络连接后重试
• 如果清单 JSON 格式错误，请修正后重试——不要让用户排查 JSON 问题