@wot-ui/cli 1.0.4 → 1.0.5

package/README.md

@@ -1,91 +1,280 @@
-# Open Wot
+<p align="center">
+  <a href="https://wot-ui.cn">
+    <img src="./docs/assets/wot-ui-logo.svg" width="112" alt="Wot UI">
+  </a>
+</p>
 
-open-wot 是 wot-ui 的 AI 工具链仓库，当前对外发布的核心包为 `@wot-ui/cli`。它提供命令行工具、MCP Server、离线组件知识库与数据提取脚本，用于把 wot-ui v2 的组件知识接入编辑器、AI Agent 和本地工程分析流程。
+<h1 align="center">@wot-ui/cli</h1>
 
-## 仓库定位
+<p align="center"><strong>让 AI 真正懂 wot-ui。</strong></p>
 
-- 面向 wot-ui v2 的组件知识查询工具
-- 面向本地项目的组件使用分析与 lint 工具
-- 面向 AI 客户端的 MCP stdio 服务
-- 面向仓库维护者的数据提取与同步工作流
+<p align="center">
+  把组件 API、文档、示例和版本知识，接入你的终端与 AI 编程工具。
+</p>
 
-## 核心能力
+<p align="center">
+  <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>
+  <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>
+  <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>
+  <a href="./LICENSE.md"><img src="https://img.shields.io/npm/l/%40wot-ui%2Fcli?style=flat-square" alt="license"></a>
+</p>
 
-- 组件知识查询：`list`、`info`、`doc`、`demo`、`token`、`changelog`
-- 项目分析：`doctor`、`usage`、`lint`
-- MCP Server：`wot mcp`
-- 元数据提取：从 `wot-ui/wot-ui` 源码生成本地 `v2.json`
+<p align="center">
+  <a href="https://cli.wot-ui.cn">官方网站</a>
+  · <a href="#-30-秒接入">快速开始</a>
+  · <a href="#给-ai-使用推荐">Agent 接入</a>
+  · <a href="#在终端使用">CLI</a>
+  · <a href="#只配置-mcp">MCP</a>
+  · <a href="./CONTRIBUTING.md">参与贡献</a>
+</p>
 
-## 安装
+---
+
+组件文档不应该只能被人阅读。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`。
 
 ```bash
-npm install -g @wot-ui/cli
+npm install -g @wot-ui/cli@latest
+wot agent init --client cursor
+wot agent doctor --client cursor
+```
+
+完成后，当前项目会获得：
+
+```text
+MCP Server       AI 可以按需调用 8 个 wot-ui tools
+wot-ui-v2 Skill  AI 知道何时、如何选择和使用组件
+Instructions     AI 在生成代码前主动查询真实组件知识
 ```
 
-安装完成后可直接使用 `wot` 命令。
+使用其他客户端时，只需替换 client id：
 
-`wot` 在交互式终端启动时会自动检查 `@wot-ui/cli` 是否有新版本。检查结果最多缓存 24 小时，提示只写入 stderr，不会污染 `--format json` 的 stdout；CI 和非交互式环境会自动跳过。`wot mcp` 不会在启动时输出更新提示，MCP 客户端可通过 `wot_status` tool 查询 CLI 更新状态。若需要关闭检查，可设置 `WOT_DISABLE_UPDATE_CHECK=1` 或 `NO_UPDATE_NOTIFIER=1`。
+| Claude Code | Cursor | VS Code | Codex |
+| --- | --- | --- | --- |
+| `claude` | `cursor` | `vscode` | `codex` |
 
-如果你在仓库内本地调试，推荐直接运行源码入口，而不是依赖全局命令：
+同时使用多个 AI 客户端时，可以一次完成全部项目级配置：
 
 ```bash
-pnpm exec tsx src/index.ts list
+wot agent init --client all
+wot agent doctor --client all --timeout 30000
+```
+
+`--client all` 在 project scope 下会处理 Claude Code、Cursor、VS Code 和 Codex；在 user scope 下只处理支持用户级配置的客户端。
+
+配置完成后重启客户端；如果出现“信任项目”或“批准 MCP Server”的提示，请按客户端指引确认。
+
+## ✨ 它解决什么问题
+
+没有上下文的 AI 容易混用 Vue 组件库 API、使用不存在的属性，或者生成与项目版本不匹配的代码。Open Wot 在 AI 写代码前补上准确的 wot-ui 上下文：
+
+```mermaid
+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"]
+  E --> F
 ```
 
-## 快速开始
+它也可以单独作为一个快速的组件知识 CLI：
+
+```console
+$ 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。
 
 ```bash
-wot list
-wot info Button
-wot demo Button basic
-wot doc Button
-wot token Button
-wot changelog
-wot doctor ./my-project
-wot usage ./my-project
-wot lint ./my-project
-wot mcp
+wot agent init --client cursor
+wot agent status --client cursor
+wot agent doctor --client cursor
+```
+
+整个生命周期都可以通过 CLI 管理：
+
+```bash
+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
 ```
 
-## 命令说明
+多客户端项目：
+
+```bash
+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` 不会默认安装。
+
+只接入部分能力：
+
+```bash
+wot agent init --client codex --with mcp
+wot agent init --client claude --with skill,instructions
+```
+
+<details>
+<summary><strong>不想自己操作？复制这段话给 AI</strong></summary>
+
+```text
+请在当前项目中接入 wot-ui 的 AI 开发能力：
+
+1. 确认 Node.js >= 20。
+2. 安装或更新 `@wot-ui/cli@latest`；优先全局安装，不要使用 sudo。权限受限时改用 `npx -y @wot-ui/cli@latest` 执行后续命令。
+3. 识别当前客户端：Claude Code=claude、Cursor=cursor、VS Code=vscode、Codex=codex。无法确定时先询问我。
+4. 执行 `wot agent init --client <client-id> --scope project --with mcp,skill,instructions --yes`。
+5. 执行 `wot agent doctor --client <client-id> --scope project --with mcp,skill,instructions`。
+6. 告诉我修改了哪些文件、doctor 结果，以及是否需要重启客户端或批准 MCP。
+
+请保留已有 MCP Server 和用户内容；如果安全检查失败，说明原因，不要绕过。
+```
+
+</details>
+
+## 在终端使用
+
+推荐全局安装：
+
+```bash
+npm install -g @wot-ui/cli@latest
+wot -V
+```
+
+一次性查询也可以直接使用 package runner：
+
+```bash
+npx -y @wot-ui/cli@latest info Button
+pnpm dlx @wot-ui/cli@latest info Button
+```
 
 ### 组件知识
 
-- `wot list [keyword]`：列出可用的 wot-ui 组件，支持按名称过滤
-- `wot info <component>`：查看组件 props、events、slots、CSS 变量
-- `wot doc <component>`：输出组件 markdown 文档
-- `wot demo <component> [name]`：查看 demo 列表或指定 demo 源码
-- `wot token [component]`：查看组件 CSS 变量与默认值
-- `wot changelog [version] [component]`：查看版本更新记录
+| 命令 | 用途 |
+| --- | --- |
+| `wot list [keyword]` | 按名称、中文名、标签、分类或描述查找组件 |
+| `wot info <component>` | 查询 props、events、slots 和 CSS 变量 |
+| `wot doc <component>` | 获取完整 Markdown 文档 |
+| `wot demo <component> [name]` | 查看 demo 列表或指定 demo 源码 |
+| `wot token [component]` | 查询组件 CSS 变量 |
+| `wot changelog [versionOrComponent] [component]` | 按版本或组件查询更新记录 |
+
+```bash
+wot list button
+wot info Button
+wot demo Button demo-1
+wot token Button
+```
 
 ### 项目分析
 
-- `wot doctor [dir]`：检查项目依赖、运行环境与基础集成情况
-- `wot usage [dir]`：统计 `.vue` 文件中的 `wd-*` 使用情况
-- `wot lint [dir]`：检查未知组件、空按钮等规则
+| 命令 | 用途 |
+| --- | --- |
+| `wot doctor [dir]` | 检查依赖、运行环境和基础集成 |
+| `wot usage [dir]` | 统计 `.vue` 文件中的 `wd-*` 使用情况 |
+| `wot lint [dir]` | 检查未知组件、空按钮等问题 |
 
-### 通用参数
+### 版本与结构化输出
 
-多数查询命令支持以下参数：
+```bash
+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：
+
+```bash
+wot mcp list
+wot mcp init --client cursor
+wot mcp status --client cursor
+wot mcp doctor --client cursor
+wot mcp remove --client cursor
+```
+
+支持的项目配置：
+
+| Client | 文件 | 配置根字段 |
+| --- | --- | --- |
+| Claude Code | `.mcp.json` | `mcpServers` |
+| Cursor | `.cursor/mcp.json` | `mcpServers` |
+| VS Code | `.vscode/mcp.json` | `servers` |
+| Codex | `.codex/config.toml` | `mcp_servers.wot-ui` |
+
+```bash
+wot mcp print --client cursor             # 只预览配置
+wot mcp init --client cursor --dry-run    # 预览文件变更
+wot mcp init --client all                 # 配置所有客户端
+wot mcp init --client codex --pin         # 固定当前 CLI 版本
+```
 
-- `--format text`（默认）或 `--format json`：输出格式
-- `--version <ver>`：指定 wot-ui 版本，支持以下格式：
-  - `2.0`（minor，自动解析到最新 patch）
-  - `2.0.4`（exact patch）
-  - `latest`（始终使用最新稳定版）
-  - 不传时自动从项目 `node_modules/@wot-ui/ui` 或 `package.json` 依赖声明检测，检测不到则回退到最新版
+Claude Code、Cursor 和 Codex 支持 `--scope user`；VS Code 当前使用 project scope。`doctor` 会验证配置和真实 MCP handshake，并在客户端支持时继续检查注册状态。
 
-示例：
+直接启动 stdio Server：
 
 ```bash
-wot info Button --version 2.0.0
-wot doc Button --version 2.0
-wot list --format json --version latest
+wot mcp                                  # 默认启动
+wot mcp serve                            # 语义明确的等价写法
 ```
 
-## MCP 集成
+<details>
+<summary><strong>手动配置 MCP</strong></summary>
 
-将以下配置加入支持 MCP 的客户端：
+自动配置默认使用 `npx` 启动 Server，避免桌面应用读取不到终端的全局 `PATH`：
+
+```json
+{
+  "mcpServers": {
+    "wot-ui": {
+      "command": "npx",
+      "args": ["-y", "@wot-ui/cli", "mcp"]
+    }
+  }
+}
+```
+
+已全局安装且客户端能够找到 `wot` 时，也可以使用：
 
 ```json
 {
@@ -98,126 +287,169 @@ wot list --format json --version latest
 }
 ```
 
-当前 MCP Server 提供以下 tools：
+</details>
 
-| Tool | 功能 | 主要参数 |
-| --- | --- | --- |
-| `wot_status` | 查看 MCP Server 与 `@wot-ui/cli` 状态，包括当前版本、是否有 CLI 更新及更新命令。 | 无 |
-| `wot_list` | 列出当前离线知识库中的 wot-ui 组件元数据，适合在生成页面前发现可用组件。 | `version` |
-| `wot_info` | 查询单个组件的 props、events、slots、CSS 变量等结构化信息。 | `component`, `version` |
-| `wot_doc` | 获取单个组件的完整 markdown 文档，适合需要阅读用法细节或限制说明时调用。 | `component`, `version` |
-| `wot_demo` | 获取组件 demo 列表，或按 demo 名称获取指定示例源码。 | `component`, `demo`, `version` |
-| `wot_token` | 查询组件 CSS 变量；不传组件名时返回所有组件的 CSS 变量摘要。 | `component`, `version` |
-| `wot_changelog` | 查询 wot-ui v2 离线数据中的更新记录，可按版本或组件过滤。 | `version`, `component` |
-| `wot_lint` | 扫描本地项目中的 wot-ui 使用问题，例如未知组件、空按钮等规则。 | `dir`, `version` |
+<details>
+<summary><strong>8 个 MCP tools</strong></summary>
 
-其中 `version` 支持与 CLI 一致的写法，例如 `2.0`、`2.0.4`、`latest`；不传时会按项目依赖或离线数据自动解析。
+| Tool | 能力 |
+| --- | --- |
+| `wot_status` | Server、CLI 版本与更新状态 |
+| `wot_list` | 组件发现与摘要 |
+| `wot_info` | props、events、slots、CSS 变量 |
+| `wot_doc` | 完整组件文档 |
+| `wot_demo` | demo 摘要或指定示例源码 |
+| `wot_token` | 组件 CSS 变量 |
+| `wot_changelog` | 版本与组件更新记录 |
+| `wot_lint` | 项目中的 wot-ui 使用问题 |
 
-## 数据来源
+</details>
 
-当前版本聚焦 `wot-ui v2`。仓库内的离线数据来自 `wot-ui/wot-ui` 源码，主要提取自：
+## 完整命令速查
 
-- `docs/component/*.md`
-- `docs/guide/changelog.md`
-- `src/uni_modules/wot-ui/components/*/index.scss`
+<details>
+<summary><strong>展开全部命令和参数</strong></summary>
 
-`data/` 目录保存每个 stable patch 版本的独立快照（`v2.0.0.json`、`v2.0.1.json`、…），以及一个始终指向最新版的 `v2.json`。
+### 组件知识与项目分析
 
-### 更新数据
+| 命令 | 说明 |
+| --- | --- |
+| `wot list [keyword]` | 查找组件 |
+| `wot info <component>` | 查询组件 API |
+| `wot doc <component>` | 获取完整文档 |
+| `wot demo <component> [name]` | 查询 demo |
+| `wot token [component]` | 查询 CSS 变量 |
+| `wot changelog [versionOrComponent] [component]` | 查询更新记录 |
+| `wot doctor [dir]` | 诊断项目环境 |
+| `wot usage [dir]` | 分析组件使用情况 |
+| `wot lint [dir]` | 检查组件使用问题 |
 
-**全量同步所有历史 tag（推荐，首次或需要补全历史版本时使用）：**
+以上查询命令都支持 `--version <version>` 和 `--format text|json|markdown`。
 
-```bash
-pnpm sync:clone
-```
+### Agent
 
-克隆 wot-ui 仓库（`--filter=tree:0 --no-checkout`，不下载文件树），按所有 stable tag 逐一 checkout + 提取，已有快照自动跳过。
+| 命令 | 说明 |
+| --- | --- |
+| `wot agent list` | 列出支持和检测到的客户端 |
+| `wot agent init` | 初始化 MCP、Skill 和 Instructions |
+| `wot agent status` | 检查三类能力的配置状态 |
+| `wot agent doctor` | 检查文件并执行真实 MCP handshake |
+| `wot agent remove` | 删除 open-wot 管理的接入内容 |
 
-**仅更新最新版本（快速，CI 单版本触发时使用）：**
+`init`、`status`、`doctor` 和 `remove` 支持：
 
-```bash
-pnpm extract:clone
-```
+- `--client auto|all|claude|cursor|vscode|codex`
+- `--scope project|user`
+- `--with mcp,skill,instructions`
+- `--cwd <directory>`
+- `--format text|json`
+- `--pin [version]`
 
-**使用本地已有的 wot-ui 仓库：**
+其中 `init`、`remove` 额外支持 `--dry-run` 和 `--yes`，`doctor` 支持 `--timeout <milliseconds>`。
 
-```bash
-# 全量多版本
-pnpm sync --wot-dir ../wot-ui
+### MCP
 
-# 单个版本，手动指定 checkout 后提取
-pnpm extract --wot-dir ../wot-ui --output data/v2.0.4.json
+| 命令 | 说明 |
+| --- | --- |
+| `wot mcp` | 启动 stdio Server |
+| `wot mcp serve` | 显式启动 stdio Server |
+| `wot mcp list` | 列出客户端和检测结果 |
+| `wot mcp init` | 写入 MCP 配置 |
+| `wot mcp status` | 检查 MCP 配置 |
+| `wot mcp doctor` | 验证配置、handshake 和客户端状态 |
+| `wot mcp remove` | 删除托管的 MCP 配置 |
+| `wot mcp print` | 输出单个客户端的配置片段 |
+
+`init`、`status`、`doctor`、`remove` 和 `print` 支持 `--client`、`--scope`、`--cwd`、`--format` 和 `--pin`；`init`、`remove` 额外支持 `--dry-run`、`--yes`，`doctor` 支持 `--timeout`。`list` 支持 `--cwd` 和 `--format`；`print` 必须指定一个具体客户端，不能使用 `auto` 或 `all`。
+
+随时可以查看 CLI 自带帮助：
+
+```bash
+wot --help
+wot agent init --help
+wot mcp doctor --help
 ```
 
-## 开发本仓库
+</details>
+
+## 安全设计
 
-当前根目录就是主发布包，核心源码位于 `src`，离线数据位于 `data`，提取脚本位于 `scripts`。
+open-wot 会修改客户端配置，因此写入流程默认保守：
 
-### 环境要求
+- 先计算 ChangePlan，再确认或执行。
+- 支持 `--dry-run` 和 JSON 预览。
+- 保留已有 Server、JSONC 注释和非托管 TOML。
+- 使用原子写入，并在失败时回滚。
+- 遇到非法配置或无法安全接管的结构时直接停止。
+- Agent Instructions 使用明确的托管标记，避免误删用户内容。
 
-- Node.js `>= 20`
-- pnpm `10.x`
+## 开发 open-wot
 
-### 安装依赖
+环境要求：Node.js `>= 20`、pnpm `10.25.x`。
+
+### 安装与开发
 
 ```bash
 pnpm install
+pnpm dev          # 监听源码并持续构建 dist/
 ```
 
-### 常用开发命令
+也可以直接运行 TypeScript 源码：
 
 ```bash
-pnpm lint          # ESLint 检查
-pnpm typecheck     # TypeScript 类型检查
-pnpm test          # 单元测试
-pnpm build         # 构建产物到 dist/
-pnpm compress      # 压缩 data/*.json → data/*.json.gz（发布前自动执行）
+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
 ```
 
-### 本地调试 CLI
-
-直接运行源码入口最方便：
+调试最终构建产物：
 
 ```bash
-pnpm exec tsx src/index.ts list
-pnpm exec tsx src/index.ts info Button
-pnpm exec tsx src/index.ts info Button --version 2.0.0
-pnpm exec tsx src/index.ts doc Button --version 2.0
+pnpm build
+node dist/index.mjs list
+node dist/index.mjs mcp doctor --client cursor
 ```
 
-如果要调试构建产物：
+### 提交前验证
 
 ```bash
+pnpm lint
+pnpm typecheck
+pnpm test
 pnpm build
-node dist/index.mjs list
-node dist/index.mjs info Button --version 2.0.0
 ```
 
-### 本地调试 MCP
+测试开发：
 
 ```bash
-pnpm exec tsx src/index.ts mcp
+pnpm test:watch
+pnpm test:coverage
 ```
 
-MCP 走 stdio，终端无交互输出属于正常现象。若要查看 tools 与 prompts 的调用过程，建议配合 MCP Inspector 或编辑器内置 MCP 客户端调试。
+CI 会在 Node.js 20/22 以及 Ubuntu、Windows、macOS 上执行对应检查。
 
-## 自动化流程
+### 更新离线数据
 
-- `.github/workflows/ci.yml`：在 `push`/`PR` 时执行 lint、typecheck、build、test（多 OS × Node 版本矩阵）
-- `.github/workflows/sync.yml`：每日 02:00 UTC 自动检测 `@wot-ui/ui` 最新版本，有更新时拉取全量多版本快照并创建同步 PR；也可手动触发单版本提取
-- `.github/workflows/release.yml`：`v*` tag 触发自动发布 `@wot-ui/cli` 到 npm（发布前自动运行 `pnpm compress && pnpm build`，npm 包只含 `.json.gz`）
-- `.github/workflows/coverage-upload.yml`：`v*` tag 触发，上传测试覆盖率到 Codecov
+```bash
+pnpm sync:clone       # 同步全部 stable 快照
+pnpm extract:clone    # 只提取最新版本
+```
 
-## 当前边界
+已有本地 wot-ui 仓库时：
 
-- 当前仅支持 `wot-ui v2`
-- `usage` 与 `lint` 当前聚焦 `.vue` 文件中的 `<wd-*>` 标签及相关 import
-- 提取脚本优先从 SCSS 源码解析 CSS 变量，并在必要时回退到 markdown 表格
+```bash
+pnpm sync --wot-dir ../wot-ui
+pnpm extract --wot-dir ../wot-ui --output data/v2.0.4.json
+```
+
+修改 CLI、MCP、数据提取、Skill 或发布文件时，需要执行的定向验证不同。完整仓库结构、验证矩阵、打包与提交流程见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
-## 相关文档
+## 当前边界
 
-- [CONTRIBUTING.md](CONTRIBUTING.md)：贡献与开发流程
+- 当前仅支持 wot-ui v2。
+- `usage` 与 `lint` 聚焦 `.vue` 文件中的 `<wd-*>` 标签及相关 import。
+- 提取脚本优先从 SCSS 解析 CSS 变量，必要时回退到 Markdown 表格。
 
 ## License
 
-[MIT](./LICENSE) License © wot-ui
+[MIT](./LICENSE.md) License © wot-ui