wot-ui/open-wot

@wot-ui/cli

让 AI 真正懂 wot-ui。

把组件 API、文档、示例和版本知识，接入你的终端与 AI 编程工具。

官方网站 · 快速开始 · Agent 接入 · CLI · MCP · 参与贡献

---

组件文档不应该只能被人阅读。Open Wot 将 wot-ui v2 的组件知识打包成离线数据，并通过 CLI、MCP 和 Skills 提供给开发者与 AI Agent。

• 不猜 API：查询真实的 props、events、slots、CSS 变量和 demo 源码。
• 版本对得上：自动识别项目依赖，也可以精确查询指定的 wot-ui 版本。
• 知识离线可用：组件数据随 npm 包发布，无需文档 API 或密钥。
• 配置安全可控：支持 dry-run、幂等写入、原子更新和失败保护。

🚀 30 秒接入

需要 Node.js >= 20。

npm install -g @wot-ui/cli@latest
wot agent init --client cursor
wot agent doctor --client cursor

完成后，当前项目会获得：

MCP Server       AI 可以按需调用 8 个 wot-ui tools
wot-ui-v2 Skill  AI 知道何时、如何选择和使用组件
Instructions     AI 在生成代码前主动查询真实组件知识

使用其他客户端时，只需替换 client id：

DeepSeek Harness 同样默认按项目接入；请在 Git 根目录执行，或加 --cwd 。首次安装后重启桌面版，并重新打开项目会话。

同时使用多个 AI 客户端时，可以一次完成全部项目级配置：

wot agent init --client all
wot agent doctor --client all --timeout 30000

--client all 在 project scope 下会处理 Claude Code、Cursor、VS Code、Codex、OpenCode、Antigravity 和 DeepSeek Harness；在 user scope 下只处理支持用户级配置的客户端，包括 DeepSeek Harness。若在 Git 子目录初始化或移除，DeepSeek 的项目 MCP 或 Skill 无法在该目录接入时，会提示并跳过 DeepSeek，继续处理其他客户端；可加 --cwd 接入全部客户端。

配置完成后重启客户端；如果出现“信任项目”或“批准 MCP Server”的提示，请按客户端指引确认。

✨ 它解决什么问题

没有上下文的 AI 容易混用 Vue 组件库 API、使用不存在的属性，或者生成与项目版本不匹配的代码。Open Wot 在 AI 写代码前补上准确的 wot-ui 上下文：

flowchart LR
  A["wot-ui 文档 · API · Demo · Changelog"] --> B["Open Wot 离线知识库"]
  B --> C["CLI"]
  B --> D["MCP · 8 tools"]
  B --> E["Skills + Instructions"]
  D --> F["Cursor · Claude Code · VS Code · Codex · OpenCode · Antigravity · DeepSeek Harness"]
  E --> F

它也可以单独作为一个快速的组件知识 CLI：

$ wot info Button

Button 按钮 (wd-button)
按钮用于触发一个操作，如提交表单或打开链接。

Props:
- type: string = primary
- variant: string = base
- size: string = medium
- disabled: boolean = false
- loading: boolean = false

Events:
- click (`event`): 点击事件

Slots:
- default: 按钮内容

给 AI 使用（推荐）

agent init 是推荐入口，它会同时配置 MCP、安装 Skill，并写入由 open-wot 管理的项目 Instructions。

wot agent init --client cursor
wot agent status --client cursor
wot agent doctor --client cursor

整个生命周期都可以通过 CLI 管理：

wot agent list
wot agent init --client cursor --dry-run
wot agent init --client cursor
wot agent status --client cursor
wot agent doctor --client cursor
wot agent remove --client cursor

多客户端项目：

wot agent init --client all
wot agent status --client all
wot agent doctor --client all --timeout 30000
wot agent remove --client all --dry-run

• --dry-run 只展示变更计划，不写文件。
• 交互式写操作会请求确认；Agent 或 CI 中显式传入 --yes。
• 重复执行 init 不会重复插入配置。
• remove 只移除 open-wot 管理的内容，不覆盖其他 Server 或用户配置。
• 默认安装面向组件使用者的 wot-ui-v2 Skill；仓库维护 Skill wot-ui-cli 不会默认安装。
• --scope user 只改变 MCP 位置；Skill 和 Instructions 仍在项目中，使用下文列出的客户端目录，可由多个 Agent 共用，移除会影响其他使用者，修改过的 Skill 文件会保留。

只接入部分能力：

wot agent init --client codex --with mcp
wot agent init --client claude --with skill,instructions

在终端使用

推荐全局安装：

npm install -g @wot-ui/cli@latest
wot -V

一次性查询也可以直接使用 package runner：

npx -y @wot-ui/cli@latest info Button
pnpm dlx @wot-ui/cli@latest info Button

组件知识

wot list button
wot info Button
wot demo Button demo-1
wot token Button

项目分析

版本与结构化输出

wot info Button --version 2.0
wot info Button --version 2.0.4
wot list --version latest --format json

不传 --version 时，CLI 会依次检查项目安装版本、依赖声明和最新离线数据。查询命令支持 --format text|json|markdown；结构化结果写入 stdout，诊断信息保持在 stderr。

只配置 MCP

如果只需要 MCP，不需要 Skill 和 Instructions：

wot mcp list
wot mcp init --client cursor
wot mcp status --client cursor
wot mcp doctor --client cursor
wot mcp remove --client cursor

支持的项目配置：

wot mcp print --client cursor             # 只预览配置
wot mcp init --client cursor --dry-run    # 预览文件变更
wot mcp init --client all                 # 配置所有客户端
wot mcp init --client codex --pin         # 固定当前 CLI 版本

Claude Code、Cursor、Codex、OpenCode、Antigravity 和 DeepSeek Harness 支持 --scope user；VS Code 当前使用 project scope。OpenCode 会按配置优先级复用项目中已有的 opencode.json[c] 或 .opencode/opencode.json[c]，用户配置写入 ~/.config/opencode/opencode.json；Antigravity 写入 ~/.gemini/config/mcp_config.json。doctor 会验证配置和真实 MCP handshake，并在客户端支持时继续检查注册状态；Antigravity 没有稳定的非交互式状态命令，因此会提示在客户端内执行 /mcp 确认。

DeepSeek 项目配置会在 $DSH_HOME（默认 ~/.dsh）登记本机项目，并安装共享加载桥接；标准模式按会话目录加载，各项目工具与版本独立。首次安装需重启，项目移动、新机器或声明改动后需重新 init，再打开会话。已有全局配置时，先执行 wot mcp remove --client deepseek --scope user，再按项目初始化；--scope user 仍写入 cordis.patch.yml 并对加载该用户层的 profiles 全局共享。doctor 的 server-ready 只验证服务可用，请在客户端调用 wot_status、wot_list 确认加载。

Agent 接入时，OpenCode 和 Antigravity 都复用 .agents/skills/wot-ui-v2 与项目根目录的 AGENTS.md；Antigravity 1.20.5 及以上版本会读取其中的项目规则。

Qoder 和 CodeBuddy 的 IDE、CLI 均支持 project / user scope，按产品形态选择 ID：

wot agent init --client qoder
wot agent init --client qoder-cli
wot agent init --client codebuddy
wot agent init --client codebuddy-cli
wot agent doctor --client qoder-cli
wot agent doctor --client codebuddy-cli

Qoder IDE 配置路径已核对官方 1.34.0 发行包，CodeBuddy IDE 已核对 4.12.1。旧版 IDE、远程 IDE 的自定义配置路径不在此适配范围内。Qoder CLI 的 QODER_CONFIG_DIR 可覆盖用户配置目录，建议设置为绝对路径；open-wot 将相对路径按 --cwd 解析，不展开环境变量值中的字面量 ~。本地 settings.local.json、会话参数和工具过滤设置仍可能影响加载。

CodeBuddy CLI 按当前官方 MCP 文档中的 ~/.codebuddy/.mcp.json → ~/.codebuddy/mcp.json → ~/.codebuddy.json 复用首个已有文件；项目中仅有 mcp.json 时也会复用，避免新建文件遮蔽原配置。这套路径规则不兼容 CLI 1.7.0：该版本的 user 配置固定为 ~/.codebuddy.json，project 配置固定为 .mcp.json，与 IDE 共存时尤其容易写入 CLI 不读取的文件。请升级后按下文确认加载，或为旧版手动配置 MCP；open-wot 不会自动识别版本并切换路径。目前尚未验证采用新规则的最低版本，不承诺所有高于 1.7.0 的版本均兼容。

如果 all 或其他客户端初始化将创建更高优先级的文件并遮蔽 CodeBuddy CLI 已有的 mcpServers，命令会在写入前报错。请先将旧文件的 MCP 服务合并或迁移到错误提示中的新路径，再重试原命令；--dry-run 也会检查此冲突。无关 JSON 对象、空文件或空 mcpServers 不阻断初始化，all 也不会在失去优先级的旧文件中重复写入服务。旧文件若只注册了与本次生成定义完全一致的 wot-ui，则自动迁移到新路径，并在同一事务中清理旧条目，保留注释和其他设置；版本、环境变量或其他字段不同仍按冲突处理。无法解析的旧文件仍需先修复或移走。

这些客户端的项目 .mcp.json 可能与 Claude Code 共用；同品牌 IDE / CLI 也共用项目 Skill 和 Instructions。all 会合并相同文件的变更，移除共享项会影响其他使用者。Qoder 与其他 Agent 共用 AGENTS.md 时，托管区块会同时保留 .agents 和 .qoder 的 Skill 引用，供对应客户端选择；移除时只删除所选客户端对应的引用，其余引用和区块外文本保留。使用同一个 Skill 路径的客户端仍共享该引用，移除会一并影响它们。CodeBuddy 使用 CODEBUDDY.md，已有 AGENTS.md 的项目应将仍需遵守的规则引用或合并到 CODEBUDDY.md 中。

doctor 对这四种客户端报告 server-ready 时，仅表示配置与独立 MCP 握手通过，客户端注册仍未验证。IDE 请重新加载项目或重启，在 MCP 面板确认并批准服务；CLI 请运行 qoder mcp list 或 codebuddy mcp get wot-ui，进入会话后使用 /mcp（Qoder 可用 /mcp reload），确认可以调用 wot_status、wot_list。CodeBuddy IDE 自动探测以 buddy 启动器为依据，不把 IDE / CLI 共用的旧配置文件当成 IDE 安装证据；未将启动器加入 PATH 或使用自定义启动器时，显式传入 --client。

Qoder 的 IDE 与 CLI 都可能提供 qoder 命令。自动探测只采用可识别的 IDE 启动器、CLI npm 包路径、qodercli 独立入口或各自专用的配置文件；未知原生可执行文件和自定义启动器不会仅凭名字被认作 CLI。未检测到时请显式使用 --client qoder 或 --client qoder-cli，这也适用于尚未生成配置文件的原生 Qoder CLI。

直接启动 stdio Server：

wot mcp                                  # 默认启动
wot mcp serve                            # 语义明确的等价写法

完整命令速查

安全设计

open-wot 会修改客户端配置，因此写入流程默认保守：

• 先计算 ChangePlan，再确认或执行。
• 支持 --dry-run 和 JSON 预览。
• 保留已有 Server、JSONC 注释和非托管 TOML。
• 使用原子写入，并在失败时回滚。
• 遇到非法配置或无法安全接管的结构时直接停止。
• Agent Instructions 使用明确的托管标记，避免误删用户内容。

开发 open-wot

环境要求：Node.js >= 20、pnpm 10.25.x。

本仓库自身的 Agent 资产统一维护在 AGENTS.md 与 .agents/skills/。为让 Claude Code 读取同一份内容，仓库提交了两个相对符号链接：CLAUDE.md -> AGENTS.md 和 .claude/skills -> ../.agents/skills。这些链接只服务于 open-wot 仓库的开发与维护，不是 wot agent init 的安装结果；wot agent init --client ... 仍用于向其他项目安装 open-wot 提供的 MCP、Skill 和 Instructions。

检出仓库时需要保留 Git 符号链接；不要通过对 open-wot 自身执行 wot agent init 来建立或验证这些链接。

安装与开发

pnpm install
pnpm dev          # 监听源码并持续构建 dist/

也可以直接运行 TypeScript 源码：

pnpm exec tsx src/index.ts list
pnpm exec tsx src/index.ts info Button --version 2.0
pnpm exec tsx src/index.ts mcp

调试最终构建产物：

pnpm build
node dist/index.mjs list
node dist/index.mjs mcp doctor --client cursor

提交前验证

pnpm lint
pnpm typecheck
pnpm test
pnpm build

测试开发：

pnpm test:watch
pnpm test:coverage

CI 会在 Node.js 20/22 以及 Ubuntu、Windows、macOS 上执行对应检查。

更新离线数据

pnpm sync:clone       # 同步全部 stable 快照
pnpm extract:clone    # 只提取最新版本

已有本地 wot-ui 仓库时：

pnpm sync --wot-dir ../wot-ui
pnpm extract --wot-dir ../wot-ui --output data/v2.0.4.json

修改 CLI、MCP、数据提取、Skill 或发布文件时，需要执行的定向验证不同。完整仓库结构、验证矩阵、打包与提交流程见 CONTRIBUTING.md。

当前边界

• 当前仅支持 wot-ui v2。
• DeepSeek Harness 不支持 MCP prompt templates；极简模式和自定义 profile 可能缺少 MCP、Skill 或 Instructions 能力。
• usage 与 lint 聚焦 .vue 文件中的 `` 标签及相关 import。
• 提取脚本优先从 SCSS 解析 CSS 变量，必要时回退到 Markdown 表格。

License

MIT License © wot-ui