企业官网建设流程全解析

• 开发工具
• CLI
• 构建工具
• MCP 服务

本指南围绕 Bit 开源仓库中的 contrib/claude-skill-bit-cli 目录展开，讲解其核心文档 SKILL.md 的设计思路、命令全景与使用方式。你将理解为什么 AI Agent 不应凭记忆猜测 Bit 命令、这套「渐进式披露」的层级化参考如何以最小 Token 成本提供最准确的命令语法，并掌握安装、更新、自动再生成技能文件以及切换到 Bit MCP Server 的完整方案。

一、为什么需要这份技能：AI 不该凭记忆猜 Bit 命令

Bit 是一个基于组件的开发平台，其 CLI 拥有 90+ 个公开命令、数十个带子命令的命令族（如lane、deps、envs、scope、ci）以及大量 flags。对于接入 Claude Code 等 AI 编码助手的开发者来说，最大的风险不是找不到命令，而是让模型从训练记忆里"猜"一个命令——猜出来的语法可能是旧版、错位甚至根本不存在的，最终导致误操作或反复失败。

SKILL.md 的 front-matter 对此做了强制约束：

name: bit-cli description: 'MUST consult before running ANY bit command. Do NOT guess bit commands from memory. This skill tells you the right command, correct syntax, subcommands, and flags.'

即：在运行任何bit命令之前，必须先查阅本技能；不得凭记忆猜测命令。这份 description 会被 Claude Code 在相关场景下自动加载，从而把"先查参考、再执行"变成 Agent 的默认行为，而非依赖用户的提醒。

二、渐进式披露设计：三层结构控制 Token 开销

整个技能按"渐进式披露（progressive disclosure）"设计，来自 README.md 的说明，分为三个层级：

这种设计没有使用任何 bash 脚本、不触发权限弹窗，SKILL.md末尾明确指示 Agent 的读取策略：

IMPORTANT: When you need flags, arguments, or subcommand details, READ the file CLI_REFERENCE.md in this same directory using the Read tool. Only fall back to 'bit <command> --help' if the reference file doesn't cover what you need.

也就是说：先看索引（SKILL.md），需要细节时用 Read 工具读同目录下的 CLI_REFERENCE.md，只有参考文件没覆盖的内容才回退到bit --help。三层各司其职，避免了把全量参考一次性塞进上下文的高昂开销。

三、SKILL.md 命令索引全景：按类别继承全部命令

SKILL.md是bit --help风格的无色命令索引（其注释标明This content is auto-generated by: bit cli generate --skill commands）。它开篇给出统一用法：

usage: bit [--version] [--help] <command> [<args>]

以下按原文的分类，完整罗列每个命令及其一句话描述（括号内为子命令），方便读者直接作为速查表使用。

3.1 系统与工具（System & Utility）

• help- 显示可用命令与用法信息
• version- 显示已安装的 Bit 版本
• config- 管理 Bit 配置项；子命令：set, del, get, list
• globals- 显示 Bit 使用的全局目录与路径
• system <sub-command>- 访问系统级操作与调试工具；子命令：log, tail-log
• doctor [diagnosis-name]- 诊断并排查工作区问题
• clear-cache- 清除缓存数据以解决数据过期问题

3.2 工作区命令（Workspace commands）

• details- 显示上一条命令（如 tag、snap）提供的扩展详情

3.3 信息与分析（Information & Analysis）

• show <component-name>- 显示组件元数据、依赖与配置
• cat <component-id>- 打印指定版本组件的源码文件或配置
• graph [id]- 将组件依赖关系可视化为图（图片）
• pattern <pattern>- 测试并校验组件 pattern 语法
• list [remote-scope]- 显示工作区或远程 scope 中的组件
• search <query...>- 在本地工作区与远程 bit cloud 中按关键字搜索组件
• schema <pattern>- 显示组件 API schema 与类型定义；子命令：diff
• diff [component-pattern] [version] [to-version]- 对比组件在版本间或与当前工作区之间的变更
• status- 显示工作区组件状态与问题

3.4 组件配置（Component Configuration）

• envs- 显示组件及其分配的环境；子命令：list, get, set, unset, replace, update
• scope <sub-command>- 管理组件 scope 名称与归属；子命令：set, trust, rename, rename-owner, fork
• eject-conf <pattern>- 为组件生成 component.json 配置文件
• local-only <sub-command>- 管理仅存在于工作区的组件；子命令：set, unset, list
• aspect <sub-command>- 管理组件 aspect 及其配置；子命令：list, list-core, get, set, unset, update

3.5 协作与远程（Collaboration & Remote）

• remote- 为自托管环境管理远程 scope；子命令：add, del, list
• ripple <sub-command>- 管理 bit.cloud 上的 Ripple CI 任务；子命令：list, log, errors, retry, stop, simulate
• deprecate <component-pattern>- 标记组件已弃用以提示不要继续使用
• undeprecate <component-pattern>- 移除组件的弃用状态
• import [component-patterns...]- 将远程 scope 中的组件导入工作区
• delete <component-pattern>- 对远程 scope 中的组件执行软删除
• recover <component-pattern>- 恢复被软删除的组件
• export [component-patterns...]- 将组件上传到远程 scope
• lane [sub-command]- 管理 lane 以支持并行开发；子命令：list, show, create, remove, change-scope, alias, rename, remove-readme, import, remove-comp, fetch, eject, current, history, history-diff, checkout, revert, updates, merge-move
• ci <sub-command>- 面向自动化工作流的持续集成命令；子命令：verify, pr, merge, sync
• fork <pattern> [target-component-name]- 复制现有组件以创建新组件
• internalize [component-pattern]- 将组件标记为 internal，使其在 UI 中默认隐藏

3.6 运行与服务（Run & Serve）

• start [component-pattern]- 启动 Bit 开发服务器
• run [app-name]- 本地启动应用组件
• app [sub-command]- 管理应用组件；子命令：list, run

3.7 高级/调试（Advanced/Debug）

• capsule- 管理隔离的组件环境；子命令：list, create, delete, prune
• mcp-server [sub-command]- 为 AI 助手启动 Model Context Protocol 服务器；子命令：start, setup, rules

3.8 开发组件（Develop components）

• script [script-name]- 运行由环境定义的脚本

3.9 认证与云端（Authentication & Cloud）

• login- 认证 Bit Cloud 以发布组件与协作
• logout- 登出 Bit Cloud 并清除认证令牌
• whoami- 显示当前已认证的 Bit Cloud 用户
• npmrc [sub-command]- 用 Bit Cloud registry 与认证配置生成 .npmrc；子命令：generate

3.10 工作区工具（Workspace Tools）

• ws-config <sub-command>- 生成 IDE 配置文件；子命令：write, clean, list
• git <sub-command>- Bit 仓库的 Git 工具；子命令：set-merge-driver
• refactor <sub-command>- 自动重构组件源码；子命令：dependency-name

3.11 组件开发（Component Development）

• add [path...]- 将现有目录内容跟踪为工作区新组件
• create <template-name> <component-names...>- 从模板脚手架生成新组件（源码、配置与环境）
• templates- 列出可用于创建组件与工作区的模板
• watch- 监听文件变化并编译组件
• build [component-pattern]- 在隔离环境中运行构建流水线任务
• compile [component-names...]- 转译组件源文件
• move <current-component-dir> <new-component-dir>- 将组件移动到不同目录
• remove <component-pattern>- 从工作区取消跟踪组件
• rename <current-name> <new-name>- 修改组件名称

3.12 工作区与项目搭建（Workspace & Project Setup）

• new <template-name> <workspace-name>- 从模板创建新的 Bit 工作区
• init [path]- 在现有项目中初始化 Bit 工作区

3.13 测试与质量（Testing & Quality）

• artifacts <component-pattern>- 查看并下载构建产物
• test [pattern-or-test-file...]- 运行组件测试
• check-types [component-pattern]- 校验 TypeScript 类型正确性
• lint [component-pattern]- 分析组件代码问题与风格违规
• validate [component-pattern]- 依次执行类型检查、lint 与测试
• format [component-pattern]- 自动格式化组件源码

3.14 依赖与包（Dependencies & Packages）

• install [packages...]- 安装工作区依赖
• uninstall [packages...]- 从工作区移除依赖
• update [package-patterns...]- 将工作区依赖更新到较新版本
• link [component-names...]- 在组件与 node_modules 之间建立链接
• eject <component-pattern>- 将组件移出工作区并作为 npm 包安装
• deps <sub-command>- 管理组件依赖；子命令：get, remove, unset, debug, set, reset, eject, blame, usage, diagnose, circular, write
• why <dependency-name>- 查找使用指定依赖的组件
• set-peer <component-id> <range>- 配置组件始终以 peer dependency 方式安装
• unset-peer <component-id>- 移除组件的 always-peer 配置
• dependents <component-name>- 显示依赖指定组件的组件

3.15 版本控制（Version Control）

• checkout <to> [component-pattern]- 切换组件版本或移除本地变更
• revert <component-pattern> <to>- 用指定版本替换组件文件但保留当前版本
• tag [component-patterns...]- 以语义化版本标签创建不可变组件快照
• snap [component-pattern]- 为开发版本创建不可变组件快照
• reset [component-pattern]- 将本地 tag 与 snap 回退到先前版本
• merge [component-pattern]- 当本地与远程版本不同时合并分叉的组件历史
• stash <sub-command>- 临时保存与恢复组件变更；子命令：save, load, list
• log <id>- 显示组件版本历史
• log-file <filepath>- EXPERIMENTAL：显示特定文件的变更历史
• blame <filepath>- EXPERIMENTAL：按行显示作者与修改历史

四、第二层参考 CLI_REFERENCE.md：子命令、参数与 flags 的权威来源

当索引层不足以支撑执行时，Agent 应读取 CLI_REFERENCE.md。这份文件为每个命令生成## bit <command>章节，包含：用法行（usage）、一句话描述与扩展描述、以及Flags 列表；有子命令的命令族（如bit lane ...、bit deps ...）会为每个子命令递归生成独立小节。以几个高频命令为例：

4.1bit tag—— 语义化版本发布

## bit tag [component-patterns...] creates tagged versions using semantic versioning (semver) for component releases. tags are immutable and exportable. by default tags all new and modified components. supports version specification per pattern using "@" (e.g. foo@1.0.0, bar@minor). use for official releases. for development versions, use 'bit snap' instead.

• 按 pattern 指定版本：bit tag foo@1.0.0 bar@minor
• 版本递进 flags：--patch、--minor、--major、--increment <level>、--prerelease-id <id>、--pre-release [identifier]、--auto-tag-increment <level>
• 构建与流水线：--build、--skip-tests、--skip-tasks <string>、--disable-tag-pipeline、--ignore-build-errors、--rebuild-deps-graph
• 其他：--message <message>、--unmodified、--editor [editor]、--versions-file <path>、--soft、--fail-fast、--loose、--ignore-issues <issues>等

4.2bit checkout <to>—— 版本切换的核心语义

checkout的<to>参数接受五类取值，参考文档给出了精确语义：

• head：切到最后一次 snap/tag（最常见用法）
• 具体版本号：切到精确版本，如bit checkout 1.0.5 component-name
• head~x：从 head 回退 x 代，如head~2
• latest：切到最新的 semver tag
• reset：移除本地修改并恢复原始文件（同时恢复被删除的组件目录）

在 lane 上，checkout head只影响 lane 组件；要更新 main 组件需运行bit lane merge main。合并相关 flags 包括--interactive-merge、--auto-merge-resolve <merge-strategy>、--force-ours、--force-theirs、--manual等。

4.3bit deps—— 依赖治理全家桶

deps族覆盖依赖的读、写、查、诊：

• bit deps get <component-name>：显示直接与间接依赖（--scope、--tree）
• bit deps set / remove / unset <pattern> <package...>：配置或移除依赖（--dev、--peer、--optional）
• bit deps debug <component-name>：显示直接依赖及其版本是如何确定的
• bit deps blame <component-name> <dependency-name>：定位哪个 snap/tag 改变了依赖版本
• bit deps usage <dependency-name>：查找使用该依赖的组件（--depth <number>）
• bit deps diagnose：分析工作区依赖的版本扩散、peer 排列组合与冗余（扫描node_modules/.pnpm，--package <string>可下钻）
• bit deps circular：查找组件图中的循环依赖
• bit deps write：将工作区所有组件依赖写入 package.json 或 workspace.jsonc（--target）

4.4bit ci—— 面向 Git 工作流的 CI 命令

ci族专门为 CI/CD 流水线设计：

• bit ci verify：每次提交时运行 lint、build 与 status 检查，任一环节失败即返回非零退出码，适合作为 pre-push 钩子或 CI 早期任务
• bit ci pr：PR 打开/更新时把 feature lane 导出到 Bit Cloud，支持--lane、--build、--skip-tasks <tasks>、--skip-cleanup等 flags；可在提交信息中加[skip-tasks: ...]令牌跳过指定任务
• bit ci merge：PR 合入 main 后打 tag 并导出新语义化版本，默认 bump patch，可通过 flags（--patch、--minor、--major、--increment <level>、--prerelease-id <id>等）控制版本递进
• bit ci sync [lane]：无状态协调器，将 Bit lane 与 git 分支、PR 双向收敛；映射关系在workspace.jsonc的"teambit.git/ci": { "sync": { ... } }下配置

4.5 调试三件套：system、doctor、capsule

• bit system log打印debug.log到屏幕；bit system tail-log类似tail -f实时跟踪
• bit doctor [diagnosis-name]运行全面健康检查，--list列出全部诊断项，--save [filePath]生成诊断报告，--archive [filePath]打包工作区归档（可--include-node-modules）
• bit capsule list / create / delete / prune管理隔离构建环境；prune默认清理 30 天（--older-than <days>）未使用的 aspect-version 与 scope capsule，--dry-run可先预览

4.6 认证与远端配置

• bit login打开浏览器认证 bit.cloud 并自动更新.npmrc（--cloud-domain <domain>、--machine-name <name>支持自建域与机器认证）；bit logout清除令牌但保留.npmrc配置
• bit npmrc generate用 scope、registry 与 token 信息更新.npmrc（--dry-run、--force）
• bit remote add <url>支持file与http协议，例如http://localhost:3000、file:///tmp/local-scope（仅自托管场景需要，bit.cloud 会自动配置）

4.7 pattern 语法：几乎所有命令共用的过滤语言

参考文档反复强调 pattern 的用法，这也是 Bit CLI 命令的通用语言：

• 简单组件 ID：'ui/button'
• 通配多组件：'org.scope/utils/**'或'**/utils/**'
• 多 pattern 逗号分隔、!排除：'ui/**, !ui/button'（务必用引号包裹避免 shell 展开）
• $前缀按状态/属性过滤：'$deprecated'、'$modified'、'$env:teambit.react/react'；支持的状态有new, modified, deprecated, deleted, internal, snappedOnMain, softTagged, codeModified, localOnly
• AND组合：'$modified AND teambit.workspace/** AND $env:teambit.react/react'

bit pattern <pattern>命令本身即可用于在执行前校验 pattern 是否有效。

五、安装、更新与再生成

5.1 快速安装（Quick Install）

README.md 提供了标准安装方式，把两个文件放进 Claude Code 的 skills 目录：

mkdir -p ~/.claude/skills/bit-cli curl -fsL <SKILL.md 原始地址> -o ~/.claude/skills/bit-cli/SKILL.md curl -fsL <CLI_REFERENCE.md 原始地址> -o ~/.claude/skills/bit-cli/CLI_REFERENCE.md

也可以使用一行式安装（先建目录、进入目录、再用curl -fsLO下载同名文件）。安装后目录结构为：

~/.claude/skills/bit-cli/ ├── SKILL.md # L2 命令索引（约 800 token） └── CLI_REFERENCE.md # L3 完整参考（约 2000 token）

5.2 保持更新

Bit CLI 会随版本迭代新增命令与 flags，技能文件需要同步刷新：

cd ~/.claude/skills/bit-cli # 重新拉取 SKILL.md 与 CLI_REFERENCE.md 即可覆盖更新

5.3 再生成（针对 Bit 开发者）

两个文件并非手写维护，而是由 Bit CLI 自身的generate命令自动产出。在仓库源码 scopes/harmony/cli/cli.cmd.ts 中，CliGenerateCmd定义了--skill <type>选项，type取commands（生成 SKILL.md 正文）或reference（生成 CLI_REFERENCE.md）：

# 生成命令列表（SKILL.md 正文） bit cli generate --skill commands # 生成命令参考（CLI_REFERENCE.md） bit cli generate --skill reference

从源码实现看，真正干活的类在 scopes/harmony/cli/generate-doc-md.ts：

• generateSkillCommands()：按group字段把公开命令分组（groupCommandsByGroup()），对每条命令做名称右对齐（padEnd(30)）、拼装一句话描述，并提取非私有子命令追加Subcommands:行；最后套上带name: bit-cli的 YAML front-matter。这与 SKILL.md 中<!-- This content is auto-generated by: bit cli generate --skill commands -->的注释完全对应。
• generateSkillReference()：递归遍历命令树（collectSkillCommandSections），对每个命令/子命令生成## bit <cmd>标题、usage 行（自动补全<arg>/[arg...]参数）、描述与 Flags 列表；生成 flags 时会过滤掉描述以DEPRECATED或UNSUPPORTED开头的选项，确保参考文件只暴露当前有效的接口。

这意味着：只要 Bit CLI 的命令定义（Command 对象的name、description、extendedDescription、options、arguments、commands、private、group字段）更新，技能文件就能以同一套模板重新生成，人工维护成本趋近于零。

六、Token 开销量化

README 给出了技能各场景的 Token 用量对照，这也是渐进式披露的核心价值：

对比一次性加载全量参考，三层设计把绝大多数查询场景的开销限制在 1000 Token 以内，且完全无需 bash 脚本或权限弹窗，对长会话的上下文预算非常友好。

七、更强的替代方案：Bit MCP Server

如果需求超越"查命令语法"，需要实时命令发现、跨工具调用与规则注入，技能包还给出了更完整的升级路径——Bit MCP Server。在bit mcp-server命令族（源码位于 scopes/mcp/cli-mcp-server）中：

bit mcp-server setup claude-code

• bit mcp-server setup [editor]：为 VS Code、Cursor、Windsurf、Roo Code、Cline、Claude Code 等编辑器创建/更新 MCP 集成配置
• bit mcp-server rules [editor]：写入/打印 AI 助手的指导规则文件（对 Claude Code 生成.claude/bit.md，避免覆盖已有CLAUDE.md；--print可仅查看内容）
• bit mcp-server start：以 stdio 启动 MCP 服务器，支持--include-additional <commands>扩展可用命令集

MCP 服务器提供标准化的工具接口，让 AI Agent 可以动态发现并执行 Bit 命令、访问组件信息，并支持自定义指令约束 Agent 行为。它的能力更全面，但资源占用也更高——这与技能包"轻量、零权限、低 Token"的定位形成互补，读者可根据自身工作流在两者间选择。

八、使用建议与注意事项

1. 遵循参考优先级：AI Agent 应严格按「SKILL.md 索引 → CLI_REFERENCE.md 细节 →bit <command> --help兜底」的顺序取信息，避免在参考已覆盖的情况下绕道运行时帮助。
2. pattern 务必加引号：涉及*、!、$的 pattern（如'ui/**, !ui/button'）在 shell 中会被展开，建议统一用单引号包裹，并用bit pattern <pattern>先行校验。
3. 区分易混淆命令：remove仅从本地工作区取消跟踪，远程删除用delete；reset回退未导出的本地 tag/snap，已导出版本不可回退；eject把组件变成 npm 包，eject-conf则是为组件生成 component.json。
4. 版本对应：技能文件由当前版本的 Bit CLI 自动生成，若本地 Bit 版本与技能文件来源版本差异较大，建议执行 5.2 节的更新流程保持同步。
5. 本仓库中的对应物：读者可在 contrib/claude-skill-bit-cli/SKILL.md、contrib/claude-skill-bit-cli/CLI_REFERENCE.md 查看技能全文，在 scopes/harmony/cli/generate-doc-md.ts 与 scopes/harmony/cli/cli.cmd.ts 查看生成逻辑，在 scopes/mcp/cli-mcp-server 查看 MCP 服务器实现，形成「文档 → 生成器 → 运行时」的完整闭环。

九、小结

claude-skill-bit-cli是 Bit 官方为 AI 编码助手打造的"命令防呆层"：它以渐进式披露把完整的 Bit CLI 命令空间压缩进约 2800 Token 的可检索参考，用「先查再执行」的强约束替代模型记忆，并且全部内容由bit cli generate --skill从命令定义自动生成、随版本同步更新。对于任何希望在 Claude Code 等 Agent 环境中安全、准确地驱动 Bit 工作流的团队，这套技能包（或能力更强的 MCP Server）都是值得优先接入的基建。

• 开发工具
• CLI
• 构建工具
• MCP 服务