Open Wot 1.0.5 发布：让 AI 接入 wot-ui，只需要两条命令

大家好，我是不如摸鱼去，wot-ui 的发起人，欢迎来到我的 AI Coding 分享专栏。

前段时间我们发布了 Open Wot，把 wot-ui v2 的组件 API、Demo、CSS 变量和更新记录整理成离线知识库，再通过 CLI、MCP 和 Skills 交给开发者与 AI。

原本以为知识准备好了，AI 应该就能愉快开工。结果工具真正交到大家手里以后，新的问题马上来了：

MCP 到底要怎么配进 Cursor？Codex 为什么用的是 TOML？配置写进去了，为什么客户端里还是看不到？

好消息是，AI 不用继续猜组件 API 了。

坏消息是，人类开始猜 MCP 配置了。

所以 Open Wot 1.0.5 做的事情很直接：把 wot-ui 的 AI 接入，从"请手动修改配置文件"，变成一套可以初始化、检查、诊断和卸载的完整流程。

先看最短答案：两条命令

安装或更新到 1.0.5：

bash 复制代码

npm install -g @wot-ui/cli@1.0.5

如果你正在使用 Cursor，在项目根目录执行：

bash 复制代码

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 在生成代码前主动查询真实组件知识

这里不是把三个时髦名词打包到一起。它们解决的是三个不同问题：

MCP 负责提供真实的组件数据。
Skill 负责告诉 Agent 什么时候查、按什么顺序查、查完以后怎么用。
Instructions 负责把"生成代码前先查组件知识"固定成项目协作习惯。

只装其中一块当然也能工作，但三者组合起来，才更接近我们想要的体验：AI 写代码前先查，写完以后再检查。

四种客户端，不用再背四种配置

1.0.5 首批支持四种常见的 AI 编程客户端：

客户端	client id	项目配置文件
Claude Code	`claude`	`.mcp.json`
Cursor	`cursor`	`.cursor/mcp.json`
VS Code	`vscode`	`.vscode/mcp.json`
Codex	`codex`	`.codex/config.toml`

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

bash 复制代码

wot agent init --client claude
wot agent init --client vscode
wot agent init --client codex

如果一个项目里同时使用多个 AI 客户端，也可以一次处理：

bash 复制代码

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

--client all 在项目级配置中会处理 Claude Code、Cursor、VS Code 和 Codex。用户级配置则只处理支持 user scope 的客户端。

这看起来只是少写了几段 JSON 和 TOML，但真正省下来的，是查配置路径、确认字段名称、处理不同作用域，再反复重启客户端排错的时间。

毕竟我们的目标是让 AI 帮忙写业务，不是让每个开发者先考一张《主流 AI 客户端配置文件格式》证书。

`init` 不只配置 MCP

wot agent init 是 1.0.5 推荐的接入入口。

它默认会准备一份变更计划，其中包括：

为目标客户端写入 wot-ui MCP Server。
在项目中安装 wot-ui-v2 Skill。
写入由 Open Wot 管理的 Agent Instructions。

如果你对自动修改文件比较谨慎，可以先 dry-run：

bash 复制代码

wot agent init --client cursor --dry-run

CLI 会把准备修改的文件和字段完整列出来：

text 复制代码

Initialize wot-ui Agent integration
write-file: .cursor/mcp.json
  Add or update mcp server "wot-ui" under mcpServers
  + mcpServers.wot-ui
    command: npx
    args: -y @wot-ui/cli mcp
write-file: .agents/skills/wot-ui-v2/SKILL.md
  Install bundled Skill file SKILL.md
write-file: .agents/skills/wot-ui-v2/references/overview.md
  Install bundled Skill file references/overview.md
write-file: AGENTS.md
  Update only the open-wot managed instructions block
Dry run: no files were changed.

确认没有问题以后，再去掉 --dry-run 正式执行。

也可以只接入自己需要的部分：

bash 复制代码

# 只接入 MCP
wot agent init --client codex --with mcp

# 只安装 Skill 和 Instructions
wot agent init --client claude --with skill,instructions

自动化不应该等于"悄悄改文件"。所以 1.0.5 会先计算 ChangePlan，再请求确认或执行；Agent 和 CI 这类非交互环境必须显式传入 --yes，不会因为没有人输入 n 就默认同意。

配置写进去了，不代表真的能用

这是 1.0.5 里我很在意的一点。

做 MCP 接入时，我们很容易看到配置文件里多了一段 JSON，就宣布任务完成。但真实环境里还有很多可能：

桌面客户端读取不到终端里的全局 PATH。
项目还没有被信任。
MCP Server 等待用户批准。
Server 能启动，但缺少必需工具。
Codex 中的工具过滤规则把某些工具禁用了。
配置写在 project scope，客户端却在读取 user scope。

所以我们没有把"文件写入成功"当成最终结果，而是新增了 doctor：

bash 复制代码

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

status 负责检查 MCP、Skill 和 Instructions 是否存在、配置是否匹配。

doctor 会继续完成真实的 MCP handshake：启动 Server、执行初始化，并确认 8 个 wot-ui 工具是否存在。

对提供稳定查询能力的客户端，它还会继续检查客户端侧的注册状态。目前 Claude Code 和 Codex 可以自动做这一步；Cursor 和 VS Code 暂时没有稳定的 CLI 注册查询接口，因此会提示你重启客户端，并在 MCP 面板中确认。

换句话说，1.0.5 尽量把：

text 复制代码

"看起来配好了"

变成：

text 复制代码

"配置正确，Server 能启动，工具也确实存在"

剩下必须由客户端界面完成的项目信任和审批，也会明确告诉你下一步该做什么。

为什么自动配置默认使用 `npx`

如果已经全局安装了 @wot-ui/cli，最直观的 MCP 配置可能是：

json 复制代码

{
  "mcpServers": {
    "wot-ui": {
      "command": "wot",
      "args": ["mcp"]
    }
  }
}

但桌面应用启动时拿到的环境变量，经常和终端不同。你在终端里可以运行 wot，不代表 Cursor 或其他客户端也能找到它。

因此自动配置默认使用：

json 复制代码

{
  "mcpServers": {
    "wot-ui": {
      "command": "npx",
      "args": ["-y", "@wot-ui/cli", "mcp"]
    }
  }
}

这个选择不算多酷，但能少制造一批"我明明安装了，为什么客户端说 command not found"的问题。

如果希望固定版本，也可以使用 --pin：

bash 复制代码

wot mcp init --client cursor --pin
wot mcp init --client cursor --pin 1.0.5

自动改配置，怎样避免误伤用户内容

当一个工具开始修改 .mcp.json、AGENTS.md 和 .codex/config.toml 时，安全边界就比"命令能不能跑通"更重要。

1.0.5 在写入流程里做了这些限制：

支持 --dry-run，先展示计划，不修改文件。
交互式写操作默认请求确认。
JSON 配置按 JSONC 结构修改，保留已有 Server 和用户字段。
Codex TOML 使用明确的 Open Wot 托管区块，不接管无关配置。
Agent Instructions 也带有托管标记。
重复执行 init 保持幂等，不会不停追加相同内容。
remove 只删除 Open Wot 管理的内容。
写入使用临时文件和原子替换，中途失败会尝试回滚。
如果文件在生成计划后又被其他进程修改，会停止执行。
遇到非法配置、符号链接目标或无法安全接管的结构，会直接报错。

简单来说就是：能确认安全边界时只改最小范围，不能确认时宁可停下来，也不通过覆盖文件来"保证成功"。

完整生命周期可以这样管理：

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

MCP 也有了完整管理命令

1.0.4 以前，wot mcp 主要负责启动 stdio Server。

1.0.5 保留了原来的用法，同时增加了一组完整的管理命令：

bash 复制代码

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 serve

如果你只想使用 MCP，不需要 Skill 和 Instructions，可以直接走这套命令。

其中 print 只打印目标客户端的配置片段，不修改文件，适合希望自己维护配置的人：

bash 复制代码

wot mcp print --client codex

serve 是语义更明确的 Server 启动方式，原来的 wot mcp 继续兼容，不需要改已有配置。

几个不大，但很实用的变化

除了 Agent 与 MCP 接入，1.0.5 还补了几项日常使用体验。

`wot list` 支持关键词搜索

以前查看组件列表：

bash 复制代码

wot list

现在可以直接搜索：

bash 复制代码

wot list button

输出类似：

text 复制代码

- Button 按钮 (wd-button): 按钮用于触发一个操作，如提交表单或打开链接。
- SortButton 排序按钮 (wd-sort-button): 用于展示排序按钮，支持升序、降序、重置三种状态。

关键词会匹配组件名、中文名、标签、分类和描述。

MCP 返回结果更精简

过去让 Agent 调用 wot_list 时，列表结果可能携带每个组件的完整数据。信息虽然多，但 Agent 在"先找一个合适组件"的阶段，其实并不需要一次拿到所有 props、Demo 源码和完整文档。

1.0.5 改成摘要优先：

wot_list 只返回组件名称、标签、分类和描述等摘要。
wot_demo 未指定 Demo 时，只返回 Demo 名称、标题和描述。
真正需要源码时，再按组件和 Demo 名称继续查询。

先发现，再展开，最后取源码。工具调用的上下文更干净，也更符合 Agent 渐进查询的方式。

新增 `starter-cleaner` Skill

如果你使用 wot-starter v2 开始业务开发，但不需要仓库中的文档站、演示分包和 monorepo 配置，可以安装 Open Wot Skills：

bash 复制代码

pnpx skills add wot-ui/open-wot

其中的 starter-cleaner 会先预览清理范围，再把模板整理成最小可开发状态，同时保留 Wot UI、uni-echarts 和 echarts 能力。

这里需要说明一下：starter-cleaner 是独立 Skill，不是 wot agent init 默认安装的内容。Agent 初始化默认安装的是面向组件使用者的 wot-ui-v2 Skill。

我们也给 Open Wot 做了一个官网

1.0.5 还把官网作为 Monorepo 子包接入了 Open Wot 仓库：

官网、CLI 和 MCP 在同一仓库维护。
中文文档页面直接读取根目录 README.md。
CLI 使用说明只维护一次，官网自动展示同一份内容。
官网和标准 Next.js 构建都会进入 CI。

官网地址：

cli.wot-ui.cn

文档同步这件事，我们最终还是选择了最朴素的方法：不要复制。

根 README 继续作为 CLI 文档的数据源，官网负责把它渲染成更适合阅读的页面。这样 CLI 更新以后，不需要再提醒某个人"记得去官网复制一遍"。

1.0.5 到底改了多少

从 1.0.4 到 1.0.5，一共涉及 89 个文件，新增 19741 行、删除 649 行。

其中既包括 Agent 接入、ChangePlan、MCP 客户端适配器和真实 handshake，也包括官网、中文文档与 starter-cleaner Skill。

当前测试结果：

text 复制代码

Test Files  33 passed | 1 skipped
Tests       177 passed | 1 skipped

测试覆盖了 JSONC 与 TOML 配置修改、幂等写入、回滚、客户端检测、MCP handshake、注册状态判断和命令输出等场景。

数字本身不代表质量，但对于一个会修改用户配置文件的 CLI 来说，多写一些边界测试，总比上线以后让用户帮我们测试回滚流程好。

现在就可以试试

需要 Node.js 20 或更高版本：

bash 复制代码

npm install -g @wot-ui/cli@1.0.5

根据你正在使用的客户端，选择一个 client id：

bash 复制代码

# Claude Code
wot agent init --client claude

# Cursor
wot agent init --client cursor

# VS Code
wot agent init --client vscode

# Codex
wot agent init --client codex

然后执行：

bash 复制代码

wot agent doctor --client <client-id>

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

接下来可以直接把这段需求交给 AI：

text 复制代码

使用 wot-ui v2 实现一个登录页面，
包含手机号、密码、协议勾选和登录按钮。
写代码前先查询相关组件的 API 和 Demo，
完成后检查项目中的 wot-ui 用法。

我们不能保证 AI 一次写对所有业务逻辑，但至少组件属性、事件和示例不需要再靠它现场发挥。

少猜一个 API，就少修一个问题。

最后

Wot UI v2 的 slogan 是"轻量、美观、AI 友好"。

我们理解的 AI 友好，不只是准备一份 Prompt 或 llms.txt。组件知识需要结构化、版本需要对齐、Agent 需要知道什么时候查询，接入过程也需要可安装、可诊断、可回退。

Open Wot 1.0.5 只是这条路上的一步。后面我们还会继续补充客户端适配、项目检查规则和更具体的 Agent Skills。

如果你正在使用 wot-ui v2，欢迎试试 1.0.5。遇到问题可以提交 Issue，有新的 Skill 或客户端接入想法也欢迎一起贡献。

觉得项目有点意思的话，也请帮我们点个 Star。

开源项目的快乐，有时候就这么朴素。

Open Wot 1.0.5 发布：让 AI 接入 wot-ui，只需要两条命令

先看最短答案：两条命令

四种客户端，不用再背四种配置

init 不只配置 MCP

配置写进去了，不代表真的能用

为什么自动配置默认使用 npx

自动改配置，怎样避免误伤用户内容

MCP 也有了完整管理命令

几个不大，但很实用的变化

wot list 支持关键词搜索

MCP 返回结果更精简

新增 starter-cleaner Skill

我们也给 Open Wot 做了一个官网

1.0.5 到底改了多少

现在就可以试试

最后

相关资源

`init` 不只配置 MCP

为什么自动配置默认使用 `npx`

`wot list` 支持关键词搜索

新增 `starter-cleaner` Skill