{
  "markdown": "<p align=\"center\">\n  <a href=\"https://cli.wot-ui.cn\">\n    <img src=\"https://cli.wot-ui.cn/favicon.svg\" width=\"96\" alt=\"Open Wot\">\n  </a>\n</p>\n\n<h1 align=\"center\">@wot-ui/cli</h1>\n\n<p align=\"center\"><strong>让 AI 真正懂 wot-ui。</strong></p>\n\n<p align=\"center\">\n  把组件 API、文档、示例和版本知识，接入你的终端与 AI 编程工具。\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@wot-ui/cli\"><img src=\"https://img.shields.io/npm/v/%40wot-ui%2Fcli?style=flat-square&color=1c64fd\" alt=\"npm version\"></a>\n  <a href=\"https://www.npmjs.com/package/@wot-ui/cli\"><img src=\"https://img.shields.io/npm/dm/%40wot-ui%2Fcli?style=flat-square&color=12b886\" alt=\"npm downloads\"></a>\n  <a href=\"https://github.com/wot-ui/open-wot/actions/workflows/ci.yml\"><img src=\"https://img.shields.io/github/actions/workflow/status/wot-ui/open-wot/ci.yml?branch=main&style=flat-square&label=CI\" alt=\"CI\"></a>\n  <a href=\"./LICENSE.md\"><img src=\"https://img.shields.io/npm/l/%40wot-ui%2Fcli?style=flat-square\" alt=\"license\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://cli.wot-ui.cn\">官方网站</a>\n  · <a href=\"#-30-秒接入\">快速开始</a>\n  · <a href=\"#给-ai-使用推荐\">Agent 接入</a>\n  · <a href=\"#在终端使用\">CLI</a>\n  · <a href=\"#只配置-mcp\">MCP</a>\n  · <a href=\"./CONTRIBUTING.md\">参与贡献</a>\n</p>\n\n---\n\n组件文档不应该只能被人阅读。Open Wot 将 wot-ui v2 的组件知识打包成离线数据，并通过 CLI、MCP 和 Skills 提供给开发者与 AI Agent。\n\n- **不猜 API**：查询真实的 props、events、slots、CSS 变量和 demo 源码。\n- **版本对得上**：自动识别项目依赖，也可以精确查询指定的 wot-ui 版本。\n- **知识离线可用**：组件数据随 npm 包发布，无需文档 API 或密钥。\n- **配置安全可控**：支持 dry-run、幂等写入、原子更新和失败保护。\n\n## 🚀 30 秒接入\n\n需要 Node.js `>= 20`。\n\n```bash\nnpm install -g @wot-ui/cli@latest\nwot agent init --client cursor\nwot agent doctor --client cursor\n```\n\n完成后，当前项目会获得：\n\n```text\nMCP Server       AI 可以按需调用 8 个 wot-ui tools\nwot-ui-v2 Skill  AI 知道何时、如何选择和使用组件\nInstructions     AI 在生成代码前主动查询真实组件知识\n```\n\n使用其他客户端时，只需替换 client id：\n\n| Claude Code | Cursor | VS Code | Codex | OpenCode | Antigravity |\n| --- | --- | --- | --- | --- | --- |\n| `claude` | `cursor` | `vscode` | `codex` | `opencode` | `antigravity` |\n\n同时使用多个 AI 客户端时，可以一次完成全部项目级配置：\n\n```bash\nwot agent init --client all\nwot agent doctor --client all --timeout 30000\n```\n\n`--client all` 在 project scope 下会处理 Claude Code、Cursor、VS Code、Codex、OpenCode 和 Antigravity；在 user scope 下只处理支持用户级配置的客户端。\n\n配置完成后重启客户端；如果出现“信任项目”或“批准 MCP Server”的提示，请按客户端指引确认。\n\n## ✨ 它解决什么问题\n\n没有上下文的 AI 容易混用 Vue 组件库 API、使用不存在的属性，或者生成与项目版本不匹配的代码。Open Wot 在 AI 写代码前补上准确的 wot-ui 上下文：\n\n```mermaid\nflowchart LR\n  A[\"wot-ui 文档 · API · Demo · Changelog\"] --> B[\"Open Wot 离线知识库\"]\n  B --> C[\"CLI\"]\n  B --> D[\"MCP · 8 tools\"]\n  B --> E[\"Skills + Instructions\"]\n  D --> F[\"Cursor · Claude Code · VS Code · Codex · OpenCode · Antigravity\"]\n  E --> F\n```\n\n它也可以单独作为一个快速的组件知识 CLI：\n\n```console\n$ wot info Button\n\nButton 按钮 (wd-button)\n按钮用于触发一个操作，如提交表单或打开链接。\n\nProps:\n- type: string = primary\n- variant: string = base\n- size: string = medium\n- disabled: boolean = false\n- loading: boolean = false\n\nEvents:\n- click (`event`): 点击事件\n\nSlots:\n- default: 按钮内容\n```\n\n## 给 AI 使用（推荐）\n\n`agent init` 是推荐入口，它会同时配置 MCP、安装 Skill，并写入由 open-wot 管理的项目 Instructions。\n\n```bash\nwot agent init --client cursor\nwot agent status --client cursor\nwot agent doctor --client cursor\n```\n\n整个生命周期都可以通过 CLI 管理：\n\n```bash\nwot agent list\nwot agent init --client cursor --dry-run\nwot agent init --client cursor\nwot agent status --client cursor\nwot agent doctor --client cursor\nwot agent remove --client cursor\n```\n\n多客户端项目：\n\n```bash\nwot agent init --client all\nwot agent status --client all\nwot agent doctor --client all --timeout 30000\nwot agent remove --client all --dry-run\n```\n\n- `--dry-run` 只展示变更计划，不写文件。\n- 交互式写操作会请求确认；Agent 或 CI 中显式传入 `--yes`。\n- 重复执行 `init` 不会重复插入配置。\n- `remove` 只移除 open-wot 管理的内容，不覆盖其他 Server 或用户配置。\n- 默认安装面向组件使用者的 `wot-ui-v2` Skill；仓库维护 Skill `wot-ui-cli` 不会默认安装。\n\n只接入部分能力：\n\n```bash\nwot agent init --client codex --with mcp\nwot agent init --client claude --with skill,instructions\n```\n\n<details>\n<summary><strong>不想自己操作？复制这段话给 AI</strong></summary>\n\n```text\n请在当前项目中接入 wot-ui 的 AI 开发能力：\n\n1. 确认 Node.js >= 20。\n2. 安装或更新 `@wot-ui/cli@latest`；优先全局安装，不要使用 sudo。权限受限时改用 `npx -y @wot-ui/cli@latest` 执行后续命令。\n3. 识别当前客户端：Claude Code=claude、Cursor=cursor、VS Code=vscode、Codex=codex、OpenCode=opencode、Antigravity=antigravity。无法确定时先询问我。\n4. 执行 `wot agent init --client <client-id> --scope project --with mcp,skill,instructions --yes`。\n5. 执行 `wot agent doctor --client <client-id> --scope project --with mcp,skill,instructions`。\n6. 告诉我修改了哪些文件、doctor 结果，以及是否需要重启客户端或批准 MCP。\n\n请保留已有 MCP Server 和用户内容；如果安全检查失败，说明原因，不要绕过。\n```\n\n</details>\n\n## 在终端使用\n\n推荐全局安装：\n\n```bash\nnpm install -g @wot-ui/cli@latest\nwot -V\n```\n\n一次性查询也可以直接使用 package runner：\n\n```bash\nnpx -y @wot-ui/cli@latest info Button\npnpm dlx @wot-ui/cli@latest info Button\n```\n\n### 组件知识\n\n| 命令 | 用途 |\n| --- | --- |\n| `wot list [keyword]` | 按名称、中文名、标签、分类或描述查找组件 |\n| `wot info <component>` | 查询 props、events、slots 和 CSS 变量 |\n| `wot doc <component>` | 获取完整 Markdown 文档 |\n| `wot demo <component> [name]` | 查看 demo 列表或指定 demo 源码 |\n| `wot token [component]` | 查询组件 CSS 变量 |\n| `wot changelog [versionOrComponent] [component]` | 按版本或组件查询更新记录 |\n\n```bash\nwot list button\nwot info Button\nwot demo Button demo-1\nwot token Button\n```\n\n### 项目分析\n\n| 命令 | 用途 |\n| --- | --- |\n| `wot doctor [dir]` | 检查依赖、运行环境和基础集成 |\n| `wot usage [dir]` | 统计 `.vue` 文件中的 `wd-*` 使用情况 |\n| `wot lint [dir]` | 检查未知组件、空按钮等问题 |\n\n### 版本与结构化输出\n\n```bash\nwot info Button --version 2.0\nwot info Button --version 2.0.4\nwot list --version latest --format json\n```\n\n不传 `--version` 时，CLI 会依次检查项目安装版本、依赖声明和最新离线数据。查询命令支持 `--format text|json|markdown`；结构化结果写入 stdout，诊断信息保持在 stderr。\n\n## 只配置 MCP\n\n如果只需要 MCP，不需要 Skill 和 Instructions：\n\n```bash\nwot mcp list\nwot mcp init --client cursor\nwot mcp status --client cursor\nwot mcp doctor --client cursor\nwot mcp remove --client cursor\n```\n\n支持的项目配置：\n\n| Client | 文件 | 配置根字段 |\n| --- | --- | --- |\n| Claude Code | `.mcp.json` | `mcpServers` |\n| Cursor | `.cursor/mcp.json` | `mcpServers` |\n| VS Code | `.vscode/mcp.json` | `servers` |\n| Codex | `.codex/config.toml` | `mcp_servers.wot-ui` |\n| OpenCode | `opencode.json[c]` / `.opencode/opencode.json[c]` | `mcp.wot-ui` |\n| Antigravity | `.agents/mcp_config.json` | `mcpServers` |\n\n```bash\nwot mcp print --client cursor             # 只预览配置\nwot mcp init --client cursor --dry-run    # 预览文件变更\nwot mcp init --client all                 # 配置所有客户端\nwot mcp init --client codex --pin         # 固定当前 CLI 版本\n```\n\nClaude 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` 确认。\n\nAgent 接入时，OpenCode 和 Antigravity 都复用 `.agents/skills/wot-ui-v2` 与项目根目录的 `AGENTS.md`；Antigravity 1.20.5 及以上版本会读取其中的项目规则。\n\n直接启动 stdio Server：\n\n```bash\nwot mcp                                  # 默认启动\nwot mcp serve                            # 语义明确的等价写法\n```\n\n<details>\n<summary><strong>手动配置 MCP</strong></summary>\n\n自动配置默认使用 `npx` 启动 Server，避免桌面应用读取不到终端的全局 `PATH`：\n\n```json\n{\n  \"mcpServers\": {\n    \"wot-ui\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wot-ui/cli\", \"mcp\"]\n    }\n  }\n}\n```\n\n已全局安装且客户端能够找到 `wot` 时，也可以使用：\n\n```json\n{\n  \"mcpServers\": {\n    \"wot-ui\": {\n      \"command\": \"wot\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>8 个 MCP tools</strong></summary>\n\n| Tool | 能力 |\n| --- | --- |\n| `wot_status` | Server、CLI 版本与更新状态 |\n| `wot_list` | 组件发现与摘要 |\n| `wot_info` | props、events、slots、CSS 变量 |\n| `wot_doc` | 完整组件文档 |\n| `wot_demo` | demo 摘要或指定示例源码 |\n| `wot_token` | 组件 CSS 变量 |\n| `wot_changelog` | 版本与组件更新记录 |\n| `wot_lint` | 项目中的 wot-ui 使用问题 |\n\n</details>\n\n## 完整命令速查\n\n<details>\n<summary><strong>展开全部命令和参数</strong></summary>\n\n### 组件知识与项目分析\n\n| 命令 | 说明 |\n| --- | --- |\n| `wot list [keyword]` | 查找组件 |\n| `wot info <component>` | 查询组件 API |\n| `wot doc <component>` | 获取完整文档 |\n| `wot demo <component> [name]` | 查询 demo |\n| `wot token [component]` | 查询 CSS 变量 |\n| `wot changelog [versionOrComponent] [component]` | 查询更新记录 |\n| `wot doctor [dir]` | 诊断项目环境 |\n| `wot usage [dir]` | 分析组件使用情况 |\n| `wot lint [dir]` | 检查组件使用问题 |\n\n以上查询命令都支持 `--version <version>` 和 `--format text|json|markdown`。\n\n### Agent\n\n| 命令 | 说明 |\n| --- | --- |\n| `wot agent list` | 列出支持和检测到的客户端 |\n| `wot agent init` | 初始化 MCP、Skill 和 Instructions |\n| `wot agent status` | 检查三类能力的配置状态 |\n| `wot agent doctor` | 检查文件并执行真实 MCP handshake |\n| `wot agent remove` | 删除 open-wot 管理的接入内容 |\n\n`init`、`status`、`doctor` 和 `remove` 支持：\n\n- `--client auto|all|claude|cursor|vscode|codex|opencode|antigravity`\n- `--scope project|user`\n- `--with mcp,skill,instructions`\n- `--cwd <directory>`\n- `--format text|json`\n- `--pin [version]`\n\n其中 `init`、`remove` 额外支持 `--dry-run` 和 `--yes`，`doctor` 支持 `--timeout <milliseconds>`。\n\n### MCP\n\n| 命令 | 说明 |\n| --- | --- |\n| `wot mcp` | 启动 stdio Server |\n| `wot mcp serve` | 显式启动 stdio Server |\n| `wot mcp list` | 列出客户端和检测结果 |\n| `wot mcp init` | 写入 MCP 配置 |\n| `wot mcp status` | 检查 MCP 配置 |\n| `wot mcp doctor` | 验证配置、handshake 和客户端状态 |\n| `wot mcp remove` | 删除托管的 MCP 配置 |\n| `wot mcp print` | 输出单个客户端的配置片段 |\n\n`init`、`status`、`doctor`、`remove` 和 `print` 支持 `--client`、`--scope`、`--cwd`、`--format` 和 `--pin`；`init`、`remove` 额外支持 `--dry-run`、`--yes`，`doctor` 支持 `--timeout`。`list` 支持 `--cwd` 和 `--format`；`print` 必须指定一个具体客户端，不能使用 `auto` 或 `all`。\n\n随时可以查看 CLI 自带帮助：\n\n```bash\nwot --help\nwot agent init --help\nwot mcp doctor --help\n```\n\n</details>\n\n## 安全设计\n\nopen-wot 会修改客户端配置，因此写入流程默认保守：\n\n- 先计算 ChangePlan，再确认或执行。\n- 支持 `--dry-run` 和 JSON 预览。\n- 保留已有 Server、JSONC 注释和非托管 TOML。\n- 使用原子写入，并在失败时回滚。\n- 遇到非法配置或无法安全接管的结构时直接停止。\n- Agent Instructions 使用明确的托管标记，避免误删用户内容。\n\n## 开发 open-wot\n\n环境要求：Node.js `>= 20`、pnpm `10.25.x`。\n\n本仓库自身的 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。\n\n检出仓库时需要保留 Git 符号链接；不要通过对 open-wot 自身执行 `wot agent init` 来建立或验证这些链接。\n\n### 安装与开发\n\n```bash\npnpm install\npnpm dev          # 监听源码并持续构建 dist/\n```\n\n也可以直接运行 TypeScript 源码：\n\n```bash\npnpm exec tsx src/index.ts list\npnpm exec tsx src/index.ts info Button --version 2.0\npnpm exec tsx src/index.ts mcp\n```\n\n调试最终构建产物：\n\n```bash\npnpm build\nnode dist/index.mjs list\nnode dist/index.mjs mcp doctor --client cursor\n```\n\n### 提交前验证\n\n```bash\npnpm lint\npnpm typecheck\npnpm test\npnpm build\n```\n\n测试开发：\n\n```bash\npnpm test:watch\npnpm test:coverage\n```\n\nCI 会在 Node.js 20/22 以及 Ubuntu、Windows、macOS 上执行对应检查。\n\n### 更新离线数据\n\n```bash\npnpm sync:clone       # 同步全部 stable 快照\npnpm extract:clone    # 只提取最新版本\n```\n\n已有本地 wot-ui 仓库时：\n\n```bash\npnpm sync --wot-dir ../wot-ui\npnpm extract --wot-dir ../wot-ui --output data/v2.0.4.json\n```\n\n修改 CLI、MCP、数据提取、Skill 或发布文件时，需要执行的定向验证不同。完整仓库结构、验证矩阵、打包与提交流程见 [CONTRIBUTING.md](./CONTRIBUTING.md)。\n\n## 当前边界\n\n- 当前仅支持 wot-ui v2。\n- `usage` 与 `lint` 聚焦 `.vue` 文件中的 `<wd-*>` 标签及相关 import。\n- 提取脚本优先从 SCSS 解析 CSS 变量，必要时回退到 Markdown 表格。\n\n## License\n\n[MIT](./LICENSE.md) License © wot-ui\n",
  "bytes": 11093,
  "sha": "65a881e1f4948270eea4f3ef12d73d7e6d4bfe5893503e31cf41647f78353b3c",
  "repo_slug": "wot-ui/open-wot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_wot_ui_open_wot_wot_ui_v2_dafe41de/readme"
}