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：

同时使用多个 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；在 user scope 下只处理支持用户级配置的客户端。

配置完成后重启客户端；如果出现“信任项目”或“批准 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"]
  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 不会默认安装。

只接入部分能力：

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 支持 --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 确认。

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

直接启动 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。
• usage 与 lint 聚焦 .vue 文件中的 `` 标签及相关 import。
• 提取脚本优先从 SCSS 解析 CSS 变量，必要时回退到 Markdown 表格。

License

MIT License © wot-ui