Venture CLI

面向设计人员和开发者的设计脚手架 CLI —— 创建设计工作区、管理 design token、AI 驱动页面生成、打包设计交付物，以及搭建生产级 Next.js 项目。

Venture CLI 提供三种工作模式：

1. 导入模式（vt init + vt import）：从旧项目导入原型包，在工作区中精调后打包交付
2. 独立模式（vt new）：从零创建独立设计工作区，包含 52 个 shadcn 组件（覆盖 shadcn/ui 全量组件）、默认 token、文档系统和双层 AI skill 体系（4 个编排型 blueprint + 8 个执行型 skill），支持 Figma URL 自动导入 token、截图/草图原型生成页面、需求文档渐进式完善
3. 生产项目模式（vt create）：创建生产级 Next.js 项目，内置 i18n（next-intl）、认证（Clerk）、支付（Stripe）、分析（PostHog + Meta Pixel + Firebase）和 design token 体系

旧项目 AI Agent                 设计人员                       旧项目 AI Agent
     │                            │                              │
     │  /export-prototype         │                              │
     │  ──── .vt 原型包 ────→   │                              │
     │                            │  vt init                   │
     │                            │  vt import                 │
     │                            │  在 Cursor 中用 AI 精调       │
     │                            │  vt pack                   │
     │                            │  ──── 交付包 ────────────→   │
     │                            │                              │  集成样式和逻辑

安装

npm install -g venture-cli

如果之前通过源码安装过（npm link），需要加 --force 覆盖已有命令：

npm install -g venture-cli --force

要求：Node.js >= 20.0.0。安装完成后终端即可使用 vt 命令。

从源码安装（开发者）

git clone <repo-url>
cd venture-cli
pnpm bootstrap    # 安装依赖 → 构建 → 全局注册 vt 命令

快速开始

模式 A：独立设计工作区（从零开始）

1. 创建工作区

vt new my-design
cd my-design

在当前目录下会生成 my-design/ 独立工作区（自动执行 pnpm install），目录结构如下：

my-design/
├── components/ui/       52 个 shadcn/ui 组件
├── components/blocks/   可复用复合组件
├── tokens/              颜色、字体、间距 token
├── pages/               设计页面
├── docs/                按功能组织的文档（需求、决策）+ 共享资源（Figma、截图）
└── assets/              图片和资产

直接运行 vt new 或 vt new my-design 均可，未提供的参数会通过交互式提示询问（可回车跳过可选项）：

vt new
# ? Workspace name: my-design
# ? Briefly describe what you want to design (optional): 一个SaaS产品的首页
# ? Figma file URL to import Design Tokens (optional): https://www.figma.com/design/abc123/...

vt new my-design     # 跳过名称提问，仍会提示 description 和 figma URL

2. 预览设计系统

vt preview

启动后可访问两个入口页面：

• index.html：token 色板、字体样式、间距刻度，支持暗色模式切换
• component-demo.html：52 个组件的交互式 Demo 库

3. 用 AI 对话驱动设计

在 Claude Code / Cursor / Codex 中打开工作区，通过对话完成所有设计工作：

你: "首页需要一个 hero section，包含主标题、副标题和 CTA 按钮"
AI: （自动创建 docs/homepage/ 功能目录，写入 requirements.md，然后生成页面到 pages/）

你: "这是我的 Figma 文件 https://www.figma.com/design/abc123/MyDesign，帮我导入 token"
AI: （自动拉取 Figma Design Tokens，更新 tokens/colors.css 和 tokens/typography.css）

你: "根据 docs/prototypes/homepage-sketch.png 这张草图生成页面"
AI: （识别截图布局，映射到 shadcn 组件，生成 pages/homepage.tsx）

独立工作区内置双层 AI skill 体系：

编排层（Blueprint Skills） — 定义设计生产流程中的角色与阶段：

• landing-page-designer-coder — 基于产品架构与文案生成 landing page
• dashboard-product-ux-planner — 将竞品分析收敛为 dashboard 产品与 UX 规划
• dashboard-designer-coder — 生成 dashboard 多页面界面与 layout
• dashboard-design-review — 评审 dashboard 导航、任务流与状态覆盖

执行层（Execution Skills） — 具体的页面生成与审查操作：

• requirements-refine — 按功能自动创建文档目录，渐进式完善需求
• figma-token-import — 从 Figma URL 自动导入 Design Token
• screenshot-to-page — 从截图/草图生成页面
• page-from-requirements — 从需求文档生成页面
• figma-to-page — 从 Figma 原型数据生成页面
• feature-iterate — 在已有页面上迭代功能，保持文档同步
• design-review — 审查设计一致性
• style-refine — 精调样式合规性

4. 其他设计输入方式（可选）

# 导入本地 Lukas Oppermann 格式 token
vt tokens import ./design-tokens.json

# 拉取 Figma 设计数据到 docs/figma/
export FIGMA_API_TOKEN=your-token
vt figma fetch <file-key>

# 将截图/草图直接复制到 docs/prototypes/ 目录

5. 打包设计交付

vt pack

交付物生成到 output/。在 standalone 模式下，交付包除了页面外还会额外包含组件源码、token 定义和设计文档，便于开发团队直接接入。

模式 B：生产项目（Next.js 全栈）

vt create my-app
cd my-app

在当前目录下创建一个生产级 Next.js 项目，自动安装依赖。项目内置：

• i18n：next-intl（中英双语，messages/en.json + messages/zh.json）
• 认证：Clerk（@clerk/nextjs，需配置 .env）
• 支付：Stripe Checkout（/api/checkout 路由桩）
• 分析：PostHog + Meta Pixel + Firebase Analytics
• Design Token：复用 Venture token 体系（tokens/）
• UI 组件：15 个 shadcn/ui 组件

vt create my-app --description "SaaS 产品" --pixel-id "123456"

模式 C：导入模式（从旧项目原型开始）

1. 创建设计工作区

vt init my-project

在当前目录下生成 my-project/，包含 design token、React UI 组件、AI 规则的完整工作区，自动安装依赖并启动预览服务器（浏览器打开设计系统概览页）。

2. 导入原型包

收到开发团队的 .vt 原型包后，在工作区目录内导入：

cd my-project
vt import ../prototype.vt

TSX 页面、UI 组件、npm 依赖会被自动复制和安装。

3. 用 AI 精调页面

在 Cursor IDE 中打开工作区目录，通过对话调整页面视觉：

你: "把这个页面的主按钮改成品牌色，标题用 H2 样式"
AI: （自动使用 bg-button-primary 和 typo-h2 类名修改 TSX）

预览服务器已在 init 时启动。如需重新启动，运行 vt preview。

4. 打包设计交付

精调完成后，打包交付给开发团队：

vt pack

交付物生成到 output/ 目录，命令完成后会输出旧项目的导入命令。

工作区内还有一份详细的设计人员使用指南 README.md（通过 vt init 自动生成），包含 token 用法、组件列表、AI 协作技巧等。

交互式引导

不熟悉命令行？直接输入 vt（不带参数）即可进入可视化菜单：

? What would you like to do?
❯ Create a production project
  Create a standalone design workspace
  Create a new design workspace
  Update workspace to latest template
  Import a prototype package
  Start preview server
  Import/update Design Tokens (Figma)
  Pack design delivery

按上下箭头选择，回车确认。后续步骤会通过交互式提示引导完成。

选择 "Import/update Design Tokens (Figma)" 后，粘贴 Figma 文件 URL 即可自动导入或更新工作区的 Design Token（需设置 FIGMA_API_TOKEN 环境变量）。

命令参考

vt new [name]

创建独立设计工作区（不依赖旧项目原型）。不传 name 参数时会进入交互式提示。

| 选项 | 说明 | 默认值 | |------|------|--------| | --description <text> | 简要描述设计需求（自动创建需求文档） | 无 | | --figma-url <url> | Figma 文件 URL（自动导入 Design Token） | 无 | | --force | 覆盖已存在的目录 | false | | --skip-install | 跳过 pnpm install | false |

vt new my-design
vt new my-design --description "SaaS 产品落地页" --figma-url "https://www.figma.com/design/abc123/..."
vt new my-design --skip-install

工作区包含：52 个 shadcn 组件（覆盖 shadcn/ui 全量组件）、默认 design token、按功能组织的文档系统（docs// 功能目录 + docs/_shared/ 共享文档 + docs/figma/ + docs/prototypes/）、双层 AI skill 体系（4 个编排型 blueprint + 8 个执行型 skill，.claude/skills/ + .codex/skills/ + .cursor/rules/）。

交互式创建时，--description 和 --figma-url 通过提示输入（可回车跳过）。

vt create [name]

创建生产级 Next.js 项目（i18n + 认证 + 支付 + 分析 + design token）。不传 name 参数时会进入交互式提示。

| 选项 | 说明 | 默认值 | |------|------|--------| | --description <text> | 项目描述 | 无 | | --pixel-id <id> | Meta Pixel ID（预配置到分析组件） | 无 | | --force | 覆盖已存在的目录 | false | | --skip-install | 跳过 pnpm install | false | | --skip-prompt | 跳过交互式提示 | false |

vt create my-app
vt create my-app --description "SaaS 产品" --pixel-id "123456"

vt update

将当前工作区同步到最新模板版本。在 standalone 或 project 工作区目录内运行，自动检测并更新 AI skills、UI 组件和配置文件。

通过 npm 全局安装时，vt update 会自动检查是否有新版本 CLI，有则提示升级后重新执行，确保模板始终是最新的。

| 选项 | 说明 | 默认值 | |------|------|--------| | --dry-run | 预览变更但不实际修改文件 | false | | --only <category> | 仅更新指定类别（skills、components、configs） | 全部 | | --force | 跳过确认提示，强制覆盖冲突文件 | false | | --skip-self-update | 跳过 CLI 自更新检查（供 CI 或离线环境使用） | false |

文件按类别处理：

• Skills & Rules（.claude/skills/、.codex/skills/、.cursor/rules/、CLAUDE.md）：直接覆盖
• Components（components/ui/*.tsx、package.json 依赖）：本地已修改时交互式确认
• Configs（构建配置、lib/utils.ts）：直接覆盖
• 用户内容（pages/、docs/、tokens/、assets/）：永不修改

vt update                    # 交互式更新
vt update --dry-run          # 预览变更
vt update --only skills      # 仅更新 AI skills
vt update --force            # 强制全量更新

vt init <project-name>

创建一个新的设计工作区。

| 选项 | 说明 | 默认值 | |------|------|--------| | --force | 覆盖已存在的目录 | false | | --no-preview | 初始化后不自动启动预览 | 启动 |

vt init my-project
vt init my-project --force

vt preview

启动 Vite 开发服务器，实时预览设计页面。必须在工作区目录内运行。

| 选项 | 说明 | 默认值 | |------|------|--------| | --port <number> | 指定端口号 | 5678 | | --no-open | 不自动打开浏览器 | 打开 |

vt import <path-to-vt>

导入 .vt 原型包到当前工作区。必须在工作区目录内运行。

| 选项 | 说明 | 默认值 | |------|------|--------| | --no-overwrite | 跳过已存在的同名文件 | 覆盖 |

导入时自动执行：按包名创建 pages/<package-name>/ 子目录 → 复制页面入口和 _deps/ 子组件 → 复制 UI 组件 → 合并 npm 依赖并安装 → 复制上下文文档和资产。

vt pack

将精调后的设计页面打包为 .vt 交付包。必须在工作区目录内运行。

| 选项 | 说明 | 默认值 | |------|------|--------| | --pages <files> | 指定要打包的页面（逗号分隔） | 全部 | | --output <dir> | 输出路径 | pack/<workspace-name>.vt | | --zip | 打包为 ZIP 压缩文件（而非目录） | 目录 | | --designer <name> | 设计人员名称 | git user |

所有交付包统一输出到 pack/ 目录下。默认生成 pack/<name>.vt/ 目录结构；加 --zip 则生成 pack/<name>.vt ZIP 压缩文件，方便通过邮件或聊天工具传输。打包时会自动扫描 TSX 页面中的 token 引用，硬编码样式值会触发警告提示。standalone 模式下会额外包含组件源码、token 定义和设计文档。

vt tokens import <path>

从 Lukas Oppermann 格式 JSON 导入 design token 到当前工作区。必须在工作区目录内运行。

vt tokens import ./design-tokens.json

解析三层 token 结构（primitive → semantic → typography），生成 tokens/colors.css（:root + .dark）和 tokens/typography.css，更新 tokens/tokens.json。spacing.css 保留默认不变。

vt tokens fetch <figma-url>

从 Figma 文件 URL 通过 Variables API 自动拉取 Design Token。必须在工作区目录内运行，需要设置 FIGMA_API_TOKEN 环境变量。

export FIGMA_API_TOKEN=your-token
vt tokens fetch "https://www.figma.com/design/abc123XYZ/MyDesign"

从 Figma Variables API 读取颜色和字体变量，经 Figma → Lukas Oppermann 格式适配后，转换为 CSS 自定义属性。此命令通常由 AI skill 自动调用，设计师也可通过交互式菜单使用。

vt figma fetch <file-key>

通过 Figma REST API 获取设计文件完整节点树。必须在工作区目录内运行。

| 选项 | 说明 | 默认值 | |------|------|--------| | --depth <n> | 限制节点树深度 | 无限制 | | --output <path> | 自定义输出路径 | docs/figma/<file-name>.json |

export FIGMA_API_TOKEN=your-token
vt figma fetch abc123XYZ
vt figma fetch abc123XYZ --depth 3

全局选项

| 选项 | 说明 | |------|------| | --json | 以 JSON 格式输出结果 | | --version | 显示版本号 | | --help | 显示帮助信息 |

.vt 包格式

.vt 是新旧项目之间的唯一数据交换格式。支持两种物理格式：目录结构（默认）和 ZIP 压缩文件（--zip）。详细契约定义见 specs/001-design-scaffold-cli/contracts/vspk-format.md。

原型包（旧项目 → 设计工作区，v2.1.0）：

prototype.vt/
├── manifest.json          # 包元数据（name, version, format_version, pages, page_deps, components, dependencies）
├── context/
│   └── product-spec.md    # 产品说明书
├── pages/
│   ├── PricingPage.tsx    # 页面入口（可独立渲染的顶层组件）
│   └── _deps/             # 被页面入口引用的子组件和数据文件
│       ├── PricingTable.tsx
│       └── plans.ts
├── components/ui/
│   └── custom-card.tsx    # 自定义 UI 组件（如有）
└── assets/                # 图片/图标

页面入口中引用子组件的 import 路径指向 ./_deps/。导入工作区后按包名创建子目录（如 pages/pricing-demo/），保留 _deps/ 结构。

交付包（设计工作区 → 旧项目，v2.1.0）：

pack/
└── <name>.vt/           # 目录格式（默认），或 <name>.vt ZIP 文件（--zip）
    ├── manifest.json      # 交付元数据（name, designer, format_version, pages, page_deps, tokens_version）
    ├── pages/
    │   ├── PricingPage.tsx    # 精调后的页面入口
    │   └── _deps/             # 精调后的子组件
    │       └── PricingTable.tsx
    ├── tokens-used.json   # 使用的 token 清单
    ├── design-notes.md    # 设计决策说明
    └── assets/

与旧项目集成

旧项目侧（venture-next）

旧项目通过两个 Claude Code 自定义命令与设计工作区交互：

导出原型（旧项目 → 设计工作区）：

/export-prototype

直接导出 React/TSX 源码（移除 Next.js/业务逻辑/i18n，保留 UI 状态和组件结构），打包为 .vt v2.1.0 格式。页面入口放 pages/，子组件放 pages/_deps/，导出时自动改写 import 路径。命令定义：.claude/commands/export-prototype.md

导入交付（设计工作区 → 旧项目）：

/import-delivery <交付包路径>

读取交付包中的精调 TSX，与原始导出的 TSX 直接对比差异（className 变更、新增/删除元素、文案修改等），将视觉变更还原到 React/TSX 源码。只修改视觉层，不触碰业务逻辑。新增文案以 i18n key 形式引用。命令定义：.claude/commands/import-delivery.md

Token 同步

Design token 的 single source of truth 是旧项目的 tools/design-tokens.tokens.json。更新 token 后需重新生成 CLI 模板中的 CSS 文件：

1. 从旧项目复制 generated-theme.css → src/templates/workspace/tokens/colors.css
2. 从旧项目复制 generated-typography.css → src/templates/workspace/tokens/typography.css
3. 更新 tokens.json 版本号
4. 重新构建：pnpm build

Design Token 体系

Token 从 Venture Next 项目的 design-tokens.tokens.json 提取并标准化，分为两层：

Primitive Token（原始值）     Semantic Token（语义引用）        CSS 变量 / Tailwind 类
─────────────────────      ──────────────────────         ────────────────────
brand-000: #ff7a00    ──→  button-primary: #ff7a00   ──→  var(--color-button-primary)
                                                         bg-button-primary
netural-090: #ffffff  ──→  background-primary: #fff  ──→  var(--color-background-primary)
                                                         bg-background-primary

暗色模式通过 .dark 类切换 semantic token 值。工作区包含 101 个颜色 token（light/dark）、28 种字体样式、13 级间距。

所有 token CSS 通过 tokens/main.css 统一入口加载（@import "tailwindcss" + 各 token 文件），确保 Tailwind CSS v4 的 @theme 和 @utility 指令在同一个处理上下文中生效。

架构

架构总览

graph TB
    subgraph CLI["CLI 入口 (cli.ts)"]
        MainMenu["交互式菜单<br/>(@inquirer/prompts)"]
        Commander["Commander.js<br/>命令路由"]
    end

    subgraph Commands["命令层 (commands/)"]
        CmdNew["new.ts"]
        CmdCreate["create.ts"]
        CmdInit["init.ts"]
        CmdUpdate["update.ts"]
        CmdPreview["preview.ts"]
        CmdImport["import.ts"]
        CmdPack["pack.ts"]
        CmdTokens["tokens.ts"]
        CmdFigma["figma.ts"]
    end

    subgraph Lib["核心库 (lib/)"]
        Workspace["workspace.ts<br/>工作区检测"]
        TemplateDiff["template-diff.ts<br/>文件分类+比对+合并"]
        TokenTransformer["token-transformer.ts<br/>JSON→CSS 转换"]
        FigmaAdapter["figma-token-adapter.ts<br/>Figma→Oppermann 适配"]
        FigmaUrl["figma-url.ts<br/>URL 解析+导入编排"]
        TokenScanner["token-scanner.ts<br/>token 引用扫描"]
        Manifest["manifest.ts<br/>manifest 校验"]
        ContractValidator["contract-validator.ts<br/>包契约校验"]
        Logger["logger.ts<br/>彩色日志+JSON"]
    end

    subgraph Templates["模板 (templates/)"]
        TplWorkspace["workspace/<br/>15 组件 + token"]
        TplStandalone["standalone/<br/>52 组件 + 12 AI skills"]
        TplProject["project/<br/>Next.js + i18n + Auth"]
    end

    subgraph Output["产出"]
        Workspaces["cwd/<br/>设计工作区"]
        Projects["cwd/<br/>生产项目"]
        Packs["pack/<br/>交付包 (.vt)"]
    end

    MainMenu --> Commander
    Commander --> Commands

    CmdNew --> TplStandalone
    CmdCreate --> TplProject
    CmdInit --> TplWorkspace
    CmdUpdate --> TemplateDiff
    CmdPack --> TokenScanner
    CmdImport --> Manifest
    CmdTokens --> TokenTransformer
    CmdTokens --> FigmaUrl
    FigmaUrl --> FigmaAdapter
    FigmaAdapter --> TokenTransformer

    TplStandalone --> Workspaces
    TplProject --> Projects
    CmdPack --> Packs

Token 处理管线

Design Token 从 Figma 或本地 JSON 经过多阶段处理，最终转换为 CSS 自定义属性：

graph LR
    subgraph Input["输入源"]
        FigmaAPI["Figma Variables API"]
        LocalJSON["本地 JSON<br/>(Lukas Oppermann 格式)"]
    end

    subgraph Pipeline["处理管线"]
        URLParser["figma-url.ts<br/>URL 解析 + file key 提取"]
        APIFetch["HTTP GET<br/>/v1/files/{key}/variables/local"]
        Adapter["figma-token-adapter.ts<br/>Figma → Oppermann 格式"]
        Transformer["token-transformer.ts<br/>Oppermann → CSS"]
    end

    subgraph OutputFiles["输出文件"]
        ColorCSS["colors.css<br/>(:root + .dark)"]
        TypoCSS["typography.css<br/>(typo-* 工具类)"]
        TokenJSON["tokens.json<br/>(结构化索引)"]
    end

    FigmaAPI --> URLParser
    URLParser --> APIFetch
    APIFetch --> Adapter
    Adapter --> Transformer
    LocalJSON --> Transformer
    Transformer --> ColorCSS
    Transformer --> TypoCSS
    Transformer --> TokenJSON

Token 转换细节：

| 阶段 | 处理内容 | |------|---------| | Figma 适配 | 推断 token 层级（primitive/semantic/typography），解析变量别名引用，处理 Figma RGBA → hex，识别暗色模式 mode | | 格式转换 | 解析三层结构（primitive → semantic → typography），解析引用（{primitive.xxx} → var(--color-xxx)），跳过高对比度 token | | CSS 生成 | 颜色写入 :root（light）和 .dark（dark），字体生成 @utility typo-* 工具类（桌面 + 移动端 m 变体） |

模板版本系统

CLI 通过 template_version 字段跟踪模板更新，vt update 命令依赖此版本号判断工作区是否需要更新。

版本存储位置：

• 模板侧：src/templates/<type>/package.json → vt.template_version
• 工作区侧：工作区 package.json → vt.template_version

vt update 流程：

graph TD
    Detect["detectWorkspace()<br/>读取工作区 package.json"]
    VersionCheck["版本比对<br/>workspace.templateVersion vs template.templateVersion"]
    Compare["compareTemplateFiles()<br/>逐文件比对模板与工作区"]
    Classify["文件分类<br/>按 pattern 规则归类"]
    Stale["detectStaleFiles()<br/>检测废弃文件"]
    Resolve["resolveConflicts()<br/>处理冲突（交互式或 --force）"]
    Apply["applyChanges()<br/>写入文件 + 合并依赖"]
    UpdateVersion["更新 package.json<br/>vt.template_version"]

    Detect --> VersionCheck
    VersionCheck -->|"版本一致"| Skip["跳过（已是最新）"]
    VersionCheck -->|"版本不一致"| Compare
    Compare --> Classify
    Classify --> Stale
    Stale --> Resolve
    Resolve --> Apply
    Apply --> UpdateVersion

文件分类规则（standalone 为例）：

| 类别 | 匹配模式 | 更新策略 | |------|---------|---------| | Skills | .claude/skills/**, .codex/skills/**, .cursor/rules/**, CLAUDE.md | 直接覆盖 | | Configs | lib/utils.ts, vite.config.ts, tsconfig.json, index.html, component-demo.html, src/** | 直接覆盖 | | Components | components/ui/** | 条件覆盖（本地修改时交互式确认） | | 用户内容 | pages/**, docs/**, tokens/**, assets/**, README.md, .env* | 永不修改 |

冲突处理：当 --force 启用时直接覆盖；否则对 conditional 策略的文件（如已修改的组件）使用交互式选择（覆盖/跳过）。依赖通过 mergeDependencies() 合并（模板新增的依赖追加，已有依赖更新版本号）。

构建系统

CLI 使用 tsup（基于 esbuild）构建，支持秒级编译。

构建流程：

pnpm build
  │
  ├── tsup 编译 src/cli.ts → dist/cli.js（ESM 格式，target: node20）
  │
  ├── onSuccess 钩子
  │   ├── 复制 src/templates/ → dist/templates/（保留目录结构）
  │   ├── 清理 dist/templates/ 中已从 src/ 删除的文件
  │   └── 写入 dist/.build-version（当前 package.json version）
  │
  └── 输出 dist/cli.js（带 #!/usr/bin/env node shebang）

开发引导自动化：

cli.ts 启动时会执行 devBootstrapIfNeeded()，自动检测源码是否有未构建的变更：

1. 检查是否在开发环境（src/ 目录存在且 package.json name 为 venture-cli）
2. 读取 dist/.build-version 与 package.json version 比对
3. 版本不匹配时自动执行 pnpm bootstrap（安装依赖 + 构建 + 全局注册）
4. 构建完成后用新的 dist/cli.js 重新执行当前命令
5. 如果自动构建失败，降级使用当前 dist 继续执行

此机制确保开发者修改源码后无需手动构建，直接运行 vt 命令即可使用最新代码。

开发

开发命令

pnpm build        # 构建 CLI（tsup → dist/，自动复制 templates/）
pnpm dev          # 监听模式构建
pnpm test         # 运行测试（Vitest watch）
pnpm test:run     # 单次测试

项目结构

venture-cli/
├── src/
│   ├── cli.ts                       # CLI 入口（Commander.js + 交互式菜单）
│   ├── commands/
│   │   ├── new.ts                   # vt new — 创建独立设计工作区（52 组件 + token + docs + AI skills）
│   │   ├── create.ts                # vt create — 创建生产级 Next.js 项目（i18n + 认证 + 支付 + 分析）
│   │   ├── init.ts                  # vt init — 复制模板、替换项目名
│   │   ├── update.ts                # vt update — 同步工作区到最新模板（AI skills + 组件 + 配置）
│   │   ├── preview.ts               # vt preview — 调用工作区的 Vite
│   │   ├── import.ts                # vt import — 验证 manifest、复制文件、自动注入 token CSS
│   │   ├── pack.ts                  # vt pack — 扫描 token、生成交付物（支持 standalone 模式）
│   │   ├── tokens.ts                # vt tokens import/fetch — Lukas Oppermann JSON 或 Figma URL → CSS 变量转换
│   │   └── figma.ts                 # vt figma fetch — Figma REST API 节点树获取
│   ├── lib/
│   │   ├── logger.ts                # 彩色日志 + --json 输出
│   │   ├── workspace.ts             # 工作区检测 + 开发/npm 模式判断 + 脚手架输出路径 + CLI 自更新检查
│   │   ├── manifest.ts              # manifest.json 校验和读写（含 standalone 字段）
│   │   ├── interactive.ts           # @inquirer/prompts 交互式菜单
│   │   ├── template-diff.ts         # 模板文件分类 + 内容比对 + 依赖合并（update 命令核心引擎）
│   │   ├── token-scanner.ts         # TSX 中的 token 引用扫描 & 硬编码检测
│   │   ├── token-transformer.ts     # Lukas Oppermann JSON → CSS Custom Properties 转换
│   │   ├── figma-token-adapter.ts   # Figma Variables API → Lukas Oppermann 格式适配
│   │   ├── figma-url.ts             # Figma URL 解析 + token 导入编排
│   │   └── contract-validator.ts    # .vt 包契约校验（manifest schema + 文件完整性）
│   └── templates/
│       ├── workspace/               # init 命令复制到目标目录的模板文件
│       │   ├── index.html           # 设计系统起始页
│       │   ├── react-demo.html      # React 组件 Demo 入口
│       │   ├── pages.html           # 原型页面查看器入口（自动发现 pages/*/*.tsx）
│       │   ├── README.md            # 设计人员使用指南
│       │   ├── package.json         # 工作区 package.json（react + vite + tailwindcss）
│       │   ├── vite.config.ts       # Vite 多页面配置
│       │   ├── CLAUDE.md            # AI Agent 规则
│       │   ├── design-system.md     # 设计规范文档
│       │   ├── .cursor/rules/       # Cursor IDE 规则
│       │   ├── tokens/              # Design token CSS 文件
│       │   ├── components/ui/       # 15 个 React UI 组件（与源项目同源）
│       │   ├── lib/utils.ts         # cn() 工具函数
│       │   ├── src/                 # React 应用（Demo + 页面查看器）
│       │   └── pages/               # 设计页面目录
│       ├── standalone/              # new 命令创建的独立工作区模板
│       │   ├── components/ui/       # 52 个 shadcn 组件（覆盖全量 shadcn/ui）
│       │   ├── components/blocks/   # 复合组件目录（初始为空）
│       │   ├── tokens/              # 默认 design token（shadcn/ui 主题）
│       │   ├── docs/                # 按功能组织的文档系统（<feature>/, _shared/, figma/, prototypes/）
│       │   │   └── _shared/ai-workflows/  # AI 协作流程文档（skill-map + workflow-diagram）
│       │   ├── pages/               # 设计页面目录
│       │   ├── assets/              # 资产目录
│       │   ├── CLAUDE.md            # AI 规则（文档驱动 + 设计输入指引 + 双层 skill 体系）
│       │   ├── .claude/skills/      # 12 个 Claude Code AI skills（4 编排 + 8 执行）
│       │   ├── .codex/skills/       # 12 个 Codex AI skills（与 Claude skills 对齐）
│       │   ├── .cursor/rules/       # 13 个 Cursor rules（含 design-tokens + 12 skills）
│       │   ├── lib/utils.ts         # cn() 工具函数
│       │   ├── package.json         # 含 workspace_type: "standalone" + template_version 元数据
│       │   ├── vite.config.ts       # Vite 配置
│       │   └── index.html           # 设计系统预览入口
│       └── project/                 # create 命令创建的生产项目模板
│           ├── src/app/             # Next.js App Router（i18n + 分析 + 布局）
│           ├── src/i18n/            # next-intl 国际化配置
│           ├── src/config/          # 分析服务配置（PostHog + Meta Pixel + Firebase）
│           ├── src/store/           # Zustand 状态管理
│           ├── components/ui/       # 15 个 shadcn/ui 组件
│           ├── components/blocks/   # 复合组件目录（初始为空）
│           ├── tokens/              # Design token CSS
│           ├── messages/            # i18n 翻译文件（en.json + zh.json）
│           ├── docs/design/         # 设计文档
│           ├── CLAUDE.md            # AI 规则
│           └── package.json         # 含 workspace_type: "project" + template_version 元数据
├── tests/                           # 测试（Vitest）
│   ├── commands/                    # 命令测试（import, pack）
│   ├── lib/                         # 库模块测试（manifest, workspace, token-scanner, contract-validator）
│   ├── e2e/                         # 端到端测试（init → import → pack 全流程）
│   ├── fixtures/                    # 测试固件（golden prototype / delivery）
│   └── helpers/                     # 测试工具函数
├── docs/                            # 开发文档
│   └── testing.md                   # 测试策略和编写指南
├── vitest.config.ts                 # 测试配置（Vitest）
├── workspaces/                      # 本地开发时创建的工作区（.gitignore 已忽略）
├── specs/                           # Spec Kit 规格文档
├── .specify/                        # Spec Kit 配置和模板
├── .claude/commands/                # Spec Kit 命令定义
├── tsup.config.ts                   # 构建配置（tsup + 模板复制）
├── tsconfig.json
└── package.json

技术栈

| 层面 | 技术选择 | 理由 | |------|---------|------| | 语言 | TypeScript 5.8+ (strict) | 类型安全 | | CLI 框架 | Commander.js | 轻量、团队熟悉 | | 交互引导 | @inquirer/prompts | 非技术用户友好，无参数时显示可视化菜单 | | 日志 | chalk | 彩色终端输出 | | 文件操作 | fs-extra | 递归复制、JSON 读写 | | 构建 | tsup (esbuild) | 零配置、构建秒级 | | 测试 | Vitest | 与 Vite 生态统一、原生 TypeScript 支持 | | 工作区预览 | Vite + @tailwindcss/vite | HMR 热更新、原生 Tailwind CSS v4 |

模块依赖关系

cli.ts
├── commands/new.ts ────── lib/workspace.ts, lib/logger.ts, lib/figma-url.ts
├── commands/create.ts ─── lib/workspace.ts, lib/logger.ts
├── commands/init.ts ──── lib/workspace.ts, lib/logger.ts
├── commands/update.ts ─── lib/workspace.ts, lib/template-diff.ts, lib/logger.ts
├── commands/preview.ts ── lib/workspace.ts, lib/logger.ts
├── commands/import.ts ─── lib/workspace.ts, lib/manifest.ts, lib/logger.ts
├── commands/pack.ts ───── lib/workspace.ts, lib/manifest.ts, lib/token-scanner.ts, lib/logger.ts
├── commands/tokens.ts ─── lib/workspace.ts, lib/token-transformer.ts, lib/figma-url.ts, lib/logger.ts
├── commands/figma.ts ──── lib/workspace.ts, lib/logger.ts
├── lib/interactive.ts     (@inquirer/prompts)
├── lib/template-diff.ts   （模板文件分类 + 内容比对 + 依赖合并）
├── lib/figma-url.ts ───── lib/figma-token-adapter.ts, lib/token-transformer.ts
├── lib/figma-token-adapter.ts  （Figma Variables API → Lukas Oppermann 格式）
└── lib/contract-validator.ts ── lib/manifest.ts（独立校验模块，供测试和未来集成使用）

Spec Kit 规范驱动开发

本项目使用 Spec Kit 进行规范驱动开发（Specification-Driven Development）。每个功能从需求定义到代码实现，都通过结构化的 AI 命令流水线驱动，确保设计文档、技术计划和实现代码三者始终一致。

什么是 Spec Kit

Spec Kit 是一套 Claude Code / Cursor 自定义命令集（.claude/commands/speckit.*.md），将软件开发拆解为 9 个可追溯的阶段。每个阶段产出明确的文档制品，下一阶段以上一阶段的产出为输入，形成闭环。

开发阶段与命令

阶段 1                    阶段 2                  阶段 3
/speckit.constitution ──→ /speckit.specify ──→ /speckit.clarify
建立项目宪法               定义功能规格             消除模糊点
     │                        │                       │
     ▼                        ▼                       ▼
constitution.md            spec.md                spec.md（更新）

阶段 4                    阶段 5                  阶段 6
/speckit.plan ──────────→ /speckit.tasks ───────→ /speckit.analyze
制定技术计划               生成任务列表             一致性检查
     │                        │                       │
     ▼                        ▼                       ▼
plan.md, research.md       tasks.md               分析报告（只读）
data-model.md, contracts/

阶段 7                    阶段 8                  阶段 9
/speckit.checklist ─────→ /speckit.implement ───→ /speckit.taskstoissues
质量检查清单               逐步实现代码             任务转 Issue
     │                        │                       │
     ▼                        ▼                       ▼
checklists/*.md            源代码                  GitHub Issues

各阶段详解

1. /speckit.constitution — 建立项目宪法

定义项目不可违背的核心原则和技术约束。宪法是所有后续设计和实现决策的最高准则。

• 产出：.specify/memory/constitution.md
• 内容：核心原则（MUST/SHOULD 规则）、技术约束、治理规则
• 本项目定义了 5 条原则：Design-Token-First、AI-Agent-Friendly、Designer-Centric、Contract-Driven、Simplicity

2. /speckit.specify — 定义功能规格

将自然语言的功能描述转化为结构化的功能规格，包含用户故事、验收场景和可衡量的成功标准。

• 产出：specs/<编号>-<名称>/spec.md
• 内容：用户故事（按优先级排序）、验收场景（Given/When/Then）、边界情况、功能需求列表、成功标准
• 示例：本项目定义了 3 个用户故事（init P1、import P2、pack P3）和 11 个功能需求

3. /speckit.clarify — 消除模糊点

对 spec.md 中的模糊点提出问题并记录答案，确保规格无歧义。

• 产出：spec.md 中新增 Clarifications 章节
• 运作方式：AI 分析 spec 后提出关键问题，用户回答后更新 spec

4. /speckit.plan — 制定技术计划

基于功能规格和项目宪法，制定具体的技术实现方案。

• 产出：
  • plan.md — 技术栈、项目结构、宪法对齐检查
  • research.md — 关键技术决策（选型理由 + 被拒方案）
  • data-model.md — 核心实体定义
  • contracts/ — 接口契约（CLI 命令契约、.vt 格式契约）
  • quickstart.md — 快速入门

5. /speckit.tasks — 生成任务列表

将技术计划拆解为可执行的任务清单，按用户故事组织，标注依赖和并行关系。

• 产出：tasks.md
• 格式：- [ ] T001 [P] [US1] 描述 — 文件路径
  • [P] = 可并行执行
  • [US1] = 所属用户故事
• 分为 Setup → Foundational → US1 → US2 → US3 → Polish 六个 Phase

6. /speckit.analyze — 一致性检查

只读分析 spec.md、plan.md、tasks.md 三份文档的一致性，检测覆盖率、宪法对齐、术语漂移等问题。

• 产出：终端输出分析报告（不修改文件）
• 检测项：需求覆盖率、宪法违规（自动标记为 CRITICAL）、重复需求、模糊描述、未映射任务
• 严重级别：CRITICAL / HIGH / MEDIUM / LOW

7. /speckit.checklist — 质量检查清单

根据功能类型生成专项质量检查清单（需求完整性、UX、安全性等）。

• 产出：checklists/*.md
• 在 implement 前必须通过所有检查项

8. /speckit.implement — 逐步实现

按 tasks.md 的 Phase 顺序逐步实现代码，完成一个任务标记一个 [x]。

• 运作方式：加载所有设计文档 → 按 Phase 执行 → 每个 checkpoint 验证功能
• 遵循 MVP 策略：Phase 1-3（US1）完成即可使用

9. /speckit.taskstoissues — 任务转 Issue

将 tasks.md 中的任务批量创建为 GitHub Issues，保留依赖关系和标签。

规格文档目录结构

specs/001-design-scaffold-cli/
├── spec.md                    # 功能规格（用户故事 + 需求）
├── plan.md                    # 技术计划（架构 + 项目结构）
├── research.md                # 技术决策记录
├── data-model.md              # 实体模型
├── tasks.md                   # 可执行任务列表
├── quickstart.md              # 快速入门
├── contracts/
│   ├── cli-commands.md        # CLI 命令接口契约
│   └── vt-format.md         # .vt 包格式契约
└── checklists/
    └── requirements.md        # 需求检查清单

新增功能的标准流程

以新增一个 vt lint 命令为例：

# 1. 定义功能规格
/speckit.specify "添加 lint 命令，检查设计页面中的 token 使用规范性"

# 2. 消除模糊点
/speckit.clarify

# 3. 制定技术计划
/speckit.plan

# 4. 生成任务列表
/speckit.tasks

# 5. 一致性检查
/speckit.analyze

# 6. 逐步实现
/speckit.implement

每一步都有明确的输入和输出，AI Agent 可以独立完成或与人协作。

核心原则

1. Design-Token-First — 所有视觉样式必须基于 token 系统，禁止硬编码
2. AI-Agent-Friendly — 所有格式对 AI Agent 可解析、人类可阅读
3. Designer-Centric — 面向非技术用户，操作简洁，反馈清晰
4. Contract-Driven — 新旧项目通过 .vt 契约交互，严格遵循语义化版本
5. Simplicity — YAGNI 原则，只实现当前必需功能，拒绝过度设计

完整原则定义见 .specify/memory/constitution.md。

许可证

MIT