@reglow/reui-mcp 0.1.0

package/README.md

@@ -0,0 +1,204 @@
+# @reglow/reui-mcp
+
+ReUI 组件库的 **MCP 服务器** 与 **Skills 知识包**，形态对标
+[Semi Design MCP/Skills](https://semi.design/zh-CN/start/mcp-skills)：
+MCP 负责「查得到」（组件文档 / 示例 / 源码 / 函数实现 / 检索 / 指南），
+Skills 负责「怎么用」（引入方式、主题、国际化、Nuxt、扩展规范与常见陷阱）。
+
+## 什么是 MCP？
+
+Model Context Protocol（MCP）是一种标准化协议，用于连接 AI 助手与外部数据源和工具。通过 MCP，AI 助手可以动态发现和调用各种能力，而无需为每个工具单独集成。
+MCP 的核心价值：
+
+- 统一接口：提供标准化的方式让 AI 与外部系统交互
+- 动态发现：AI 可以自动发现可用的工具和资源
+- 易于扩展：新增工具只需实现 MCP 协议即可被 AI 使用
+
+## 什么是 Skills？
+
+Skills（技能）是一种模块化的能力扩展方式，允许 AI 助手通过添加预定义的指令和工具来增强其功能。每个 Skill 包含详细的说明文档和相关的代码资源，使 AI 能够在特定任务中表现得更加专业和高效。
+Skills 的核心价值：
+
+- 领域专长：为 AI 添加特定领域的专业知识和最佳实践
+- 标准化：统一团队的开发流程和规范
+- 可复用：快速复用成功经验和解决方案
+
+## 快速开始
+
+### 0. 一键配置（推荐，Trae / CodeBuddy / Qoder / Cursor / Claude）
+
+一条命令同时写好 MCP 配置并安装 Skills：
+
+```bash
+npx -y -p @reglow/reui-mcp reui-setup                              # 默认 trae,codebuddy,qoder
+npx -y -p @reglow/reui-mcp reui-setup --tools trae,qoder           # 指定工具
+npx -y -p @reglow/reui-mcp reui-setup --tools all --scope user     # 全部工具 / 用户级
+npx -y -p @reglow/reui-mcp reui-setup --dry-run                    # 先预览再执行
+```
+
+等价写法：`npx -y @reglow/reui-mcp --setup trae,codebuddy,qoder`。
+
+各工具的项目级落地位置与仍需手动完成的步骤：
+
+| 工具                   | Skills 目录                                      | MCP 配置文件                             | 仍需手动完成                                                                                                                                             |
+| ---------------------- | ------------------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Trae**               | `.trae/skills/<skill>/`                          | `.trae/mcp.json`                         | 设置 → MCP 打开「启用项目级 MCP」；用户级为 `%APPDATA%/Trae/User/mcp.json`（macOS/Linux 见 `--list-tools`）                                              |
+| **CodeBuddy**          | `.codebuddy/skills/<skill>/`                     | `.mcp.json`（JSONC）                     | IDE 需在对话面板 CodeBuddy Settings → MCP → Add MCP 粘贴同一条目；CLI 直接生效；用户级 `~/.codebuddy/.mcp.json`                                          |
+| **Qoder**              | `.qoder/skills/<skill>/`                         | `.mcp.json`（或 `.qoder/settings.json`） | 项目级 MCP 默认需批准（或 `mcp.enableAllProjectMcpServers: true`）；CLI 可 `qoder mcp add reui-mcp -s project -- npx -y @reglow/reui-mcp`；`/mcp reload` |
+| Cursor / Claude / 通用 | `.cursor/skills/`、`.claude/skills/`、`.skills/` | `.cursor/mcp.json`、`.mcp.json`          | 见 `reui-setup --list-tools` 输出                                                                                                                        |
+
+- 写入是**幂等合并**：只增改 `mcpServers["reui-mcp"]`，其它服务器与顶层字段保持不变；
+  配置文件为非法 JSON 时默认报错不改动，`--force` 会先备份为 `*.bak` 再重写。
+- 查看支持的工具与路径：`npx -y @reglow/reui-mcp --list-tools`。
+
+### 1. 手动配置 MCP（任意客户端）
+
+在 Trae / CodeBuddy / Qoder / Cursor / Claude Desktop 等客户端的 `mcpServers` 中加入：
+
+```json
+{
+  "mcpServers": {
+    "reui-mcp": {
+      "command": "npx",
+      "args": ["-y", "@reglow/reui-mcp"]
+    }
+  }
+}
+```
+
+命令行方式（Trae / CodeBuddy / Qoder /Claude Code / Qoder CLI 等）：
+
+```bash
+claude mcp add reui-mcp -- npx -y @reglow/reui-mcp
+qoder mcp add reui-mcp -s project -- npx -y @reglow/reui-mcp
+```
+
+### 2. 仅安装 Skills 知识包
+
+```bash
+npx -y -p @reglow/reui-mcp reui-skills                          # 默认写入 .trae/skills
+npx -y -p @reglow/reui-mcp reui-skills --target qoder           # .qoder/skills
+npx -y -p @reglow/reui-mcp reui-skills --target codebuddy       # .codebuddy/skills
+npx -y -p @reglow/reui-mcp reui-skills --all                    # 全部已知工具目录
+npx -y -p @reglow/reui-mcp reui-skills --list                   # 查看可用目标
+```
+
+也可通过主命令安装：`npx -y @reglow/reui-mcp --install-skills --target trae`。
+
+安装后在项目中的位置：
+
+```
+<project>/.trae/skills/reui-components/
+├── SKILL.md            技能入口（何时使用 + 工具速查 + 硬性规则）
+├── WORKFLOWS.md        MCP 工具工作流与完整任务示例
+├── BEST_PRACTICES.md   引入方式、主题、i18n、Nuxt、扩展与常见陷阱
+└── COMPONENTS.md       按分类的组件选型清单（含官网文档链接）
+```
+
+## 工具（Tools）
+
+| 工具                     | 参数                                                  | 用途                                                                                                                 |
+| ------------------------ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `get_reui_document`      | `component?` `category?` `version?` `source?`         | 不传 `component` 返回按分类的组件总览；传则返回完整文档（README：用法、示例、Props/Events/Slots 表格、Semantic DOM） |
+| `get_reui_code_examples` | `component` `index?` `lang?` `version?`               | 提取文档中可复制的 Vue / TS 示例，保留小节标题                                                                       |
+| `list_component_files`   | `component` `version?`                                | 组件源码文件清单（路径 / 行数 / 字节）                                                                               |
+| `get_file_code`          | `component` `file` `startLine?` `endLine?` `version?` | 读取组件目录内文件内容（带路径穿越防护）                                                                             |
+| `get_function_code`      | `component` `name` `file?` `version?`                 | 提取函数 / 常量 / 类 / 接口的完整实现；未命中时返回相近与可用符号                                                    |
+| `search_reui_docs`       | `query` `component?` `category?` `limit?` `version?`  | 跨组件文档与源码检索（多关键词「全部命中」），返回 `文件:行号 + 上下文 + 文档链接`                                   |
+| `get_reui_guide`         | `topic?` `version?`                                   | 库级指南章节：`overview` / `install` / `theme` / `i18n` / `nuxt` / `build` / `conventions`                           |
+
+所有返回都以「知识源 + 组件库版本」开头（如 `知识源：项目本地已安装包｜组件库版本：0.1.10`），
+当内容来自官方文档站点兜底时会额外标注 ⚠️，避免 AI 误判文档版本。
+
+## 知识来源
+
+按优先级自动选择，均可用 `version` 参数切换：
+
+| 来源          | 触发条件                                              | 内容                                                                                                                          |
+| ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| 仓库工作区    | `--root <reui 仓库路径>` 或在本仓库内运行             | 组件 README + 全部源码 + 库级 `guide.md`                                                                                      |
+| 项目本地安装  | 项目已安装 `@reglow/reui`（默认）                     | 与项目版本完全一致的文档与源码                                                                                                |
+| 指定 npm 版本 | 工具的 `version` 参数 / 启动参数 `--default-version`  | 下载该版本 tarball 到缓存后离线读取：含 `components/**` 时为完整文档与源码；仅有 `dist/**` 时提供 `.d.ts` 类型 API 与编译产物 |
+| 官方文档站点  | 包内缺少 README 时自动兜底（`source: "site"` 可强制） | 抓取 <https://reglow.huoli.tech/components-library/reui> 组件页并转 Markdown                                                  |
+
+缓存目录：`os.tmpdir()/reui-mcp-cache/<version>`（可用环境变量 `REUI_MCP_CACHE` 覆盖）。
+
+## CLI 选项
+
+| 选项                           | 说明                                                                                                                                           |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--root <dir>`                 | 指定 ReUI 仓库工作区（开发组件库时使用）                                                                                                       |
+| `--default-version <ver>`      | 工具未传 `version` 时默认使用的版本（如 `0.1.10`、`latest`、`^0.1.0`）                                                                         |
+| `--no-site`                    | 禁用官方文档站点兜底（完全离线）                                                                                                               |
+| `--check`                      | 自检：打印知识源、版本、组件数量后退出                                                                                                         |
+| `--setup [tools]`              | 一键配置 AI 工具（MCP 配置 + Skills），默认 `trae,codebuddy,qoder`；支持 `--scope user`、`--dry-run`、`--force`、`--skills-only`、`--mcp-only` |
+| `--list-tools`                 | 列出支持的工具、MCP 配置路径（项目级 / 用户级）与 Skills 目录                                                                                  |
+| `--install-skills`             | 安装 Skills 知识包（可配合 `--target` / `--all` / `--force`）                                                                                  |
+| `--print-config`               | 打印 MCP 客户端配置片段                                                                                                                        |
+| `-v, --version` / `-h, --help` | 版本 / 帮助                                                                                                                                    |
+
+三个可执行入口（bin）：
+
+| 命令          | 作用                                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `reui-mcp`    | MCP stdio 服务器（默认行为）；另提供 `--check` / `--setup` / `--install-skills` / `--list-tools` |
+| `reui-setup`  | 为 Trae / CodeBuddy / Qoder 等一键写 MCP 配置 + 安装 Skills                                      |
+| `reui-skills` | 仅把 Skills 知识包装到指定工具目录                                                               |
+
+```bash
+# 自检示例
+npx -y @reglow/reui-mcp --check
+# 查看各工具路径
+npx -y @reglow/reui-mcp --list-tools
+```
+
+## 开发与测试
+
+```bash
+# 安装依赖（SDK 只在本子包内，@reglow/reui 消费方不受影响）
+cd mcp && npm install
+
+# 单测（包含直接用 SDK Client 连接真实 stdio 服务器的端到端用例）
+npx vitest run                                   # 在 mcp/ 目录
+npx vitest run --config mcp/vitest.config.mjs    # 或在仓库根目录
+
+# 需要联网验证「指定版本」链路时
+$env:REUI_MCP_NETWORK_TEST="1"; npx vitest run   # PowerShell
+```
+
+目录结构：
+
+```
+mcp/
+├── index.mjs        bin：reui-mcp（stdio 服务器入口 / --check / --setup / --install-skills）
+├── server.mjs       MCP 服务器与 7 个工具的实现
+├── knowledge.mjs    知识源：本地 / 指定版本 / 官网兜底 + 符号提取与检索
+├── catalog.mjs      内置组件目录（按官网分类，含中文说明与文档链接）
+├── tar.mjs          零依赖 tgz 解包（PAX / GNU 长文件名）
+├── site.mjs         官网 HTML → Markdown 兜底抓取
+├── integrations.mjs AI 工具集成规格（Trae / CodeBuddy / Qoder / Cursor / Claude 的 MCP 配置与 Skills 目录）
+├── setup.mjs        bin：reui-setup（一键写 MCP 配置 + 装 Skills，含 JSONC 解析与幂等合并）
+├── skills.mjs       bin：reui-skills（仅安装 Skills 知识包）
+├── skills/          内置 Skills 知识包（随包发布）
+└── __tests__/       单测（knowledge / tar / site / skills / setup / server 端到端）
+```
+
+> ⚠️ stdio 模式下 **stdout 仅供协议通信**，日志一律走 stderr。
+
+## 发布
+
+`@reglow/reui-mcp` 与 `@reglow/reui` 是两个独立包（同仓库、可分别发布，互不拖累依赖）：
+
+```bash
+cd mcp
+npm version patch        # 按需
+npm publish              # 需要 npm 登录且有 @reglow 权限
+```
+
+`files` 已包含 `skills/`，因此 Skills 知识包随 MCP 包一起发布，版本一致。
+
+## 相关资源
+
+- 官方文档站点：<https://reglow.huoli.tech/components-library/reui>
+- Model Context Protocol：<https://modelcontextprotocol.io/>
+- Agent Skills：<https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview>

package/catalog.mjs

@@ -0,0 +1,158 @@
+/**
+ * ReUI 组件目录（内置于 MCP 服务器）
+ *
+ * 数据来源：官方文档站点组件总览 https://reglow.huoli.tech/components-library/reui
+ * 用途：
+ * - 未指定 component 时返回「按分类的组件总览」；
+ * - 为每个组件生成官方文档深链（human 可读的权威来源）；
+ * - 本地 / 指定版本包内缺少文档时，作为回退抓取的路径映射。
+ */
+
+/** 官方文档站点基地址 */
+export const DOCS_BASE = "https://reglow.huoli.tech/components-library/reui";
+
+/** 分类清单：key 为官网路由段，label 为中文分类名 */
+export const CATEGORIES = [
+  {
+    key: "general",
+    label: "通用",
+    components: [
+      { name: "button", cn: "按钮", desc: "触发操作的基础按钮" },
+      { name: "divider", cn: "分割线", desc: "分隔内容区域" },
+      { name: "label", cn: "标签", desc: "表单字段文本标签" },
+      { name: "spinner", cn: "加载圈", desc: "基础加载指示" },
+      { name: "toggle", cn: "开关", desc: "简单布尔值开关" },
+    ],
+  },
+  {
+    key: "layout",
+    label: "布局",
+    components: [
+      { name: "border-beam", cn: "边框光束", desc: "边框发光动画" },
+      { name: "masonry-grid", cn: "瀑布流", desc: "瀑布流布局" },
+      { name: "splitter", cn: "面板分割", desc: "可拖拽分割面板" },
+    ],
+  },
+  {
+    key: "navigation",
+    label: "导航",
+    components: [
+      { name: "affix", cn: "固钉", desc: "滚动时固定元素位置" },
+      { name: "breadcrumb", cn: "面包屑", desc: "显示页面层级路径" },
+      { name: "dropdown-menu", cn: "下拉菜单", desc: "下拉操作菜单" },
+      { name: "tabs", cn: "标签页", desc: "多标签内容切换" },
+    ],
+  },
+  {
+    key: "data-entry",
+    label: "数据录入",
+    components: [
+      { name: "autocomplete", cn: "自动完成", desc: "输入时自动补全" },
+      { name: "cascader", cn: "级联选择", desc: "多级联动选择" },
+      { name: "checkbox", cn: "多选框", desc: "多项选择" },
+      { name: "combobox", cn: "组合框", desc: "可搜索选择框" },
+      { name: "command", cn: "命令面板", desc: "命令式菜单" },
+      { name: "date-picker", cn: "日期选择", desc: "选择日期" },
+      { name: "editor", cn: "富文本", desc: "富文本编辑器" },
+      { name: "input", cn: "输入框", desc: "基础文本输入" },
+      { name: "input-password", cn: "密码输入框", desc: "掩码显示与显隐切换" },
+      { name: "input-select", cn: "输入选择", desc: "输入与下拉结合" },
+      { name: "native-select", cn: "原生选择", desc: "原生下拉框" },
+      { name: "radio", cn: "单选框", desc: "单项选择" },
+      { name: "rate", cn: "评分", desc: "星级评分" },
+      { name: "segmented", cn: "分段控制", desc: "分段选择" },
+      { name: "select", cn: "选择器", desc: "下拉选择" },
+      { name: "slide-captcha", cn: "滑块验证", desc: "滑块验证码" },
+      { name: "switch", cn: "开关", desc: "受控开关" },
+      { name: "tags-input", cn: "标签输入", desc: "标签式输入" },
+      { name: "textarea", cn: "多行文本", desc: "多行文本输入" },
+      { name: "time-picker", cn: "时间选择", desc: "选择时间" },
+      { name: "transfer", cn: "穿梭框", desc: "双栏数据穿梭" },
+      { name: "treeselect", cn: "树选择", desc: "树形下拉选择" },
+      { name: "upload", cn: "上传", desc: "文件上传" },
+    ],
+  },
+  {
+    key: "data-display",
+    label: "数据展示",
+    components: [
+      { name: "audio-player", cn: "音频播放", desc: "音频播放器" },
+      { name: "avatar", cn: "头像", desc: "头像展示" },
+      { name: "badge", cn: "徽标", desc: "角标与状态点" },
+      { name: "calendar", cn: "日历", desc: "日历展示" },
+      { name: "card", cn: "卡片", desc: "内容容器卡片" },
+      { name: "chat", cn: "对话", desc: "对话气泡组件" },
+      { name: "collapsible", cn: "折叠面板", desc: "可折叠内容" },
+      { name: "empty", cn: "空状态", desc: "空数据占位" },
+      { name: "hover-card", cn: "悬停卡片", desc: "悬停展示详情" },
+      { name: "image-viewer", cn: "图片预览", desc: "图片放大预览" },
+      { name: "popover", cn: "气泡卡片", desc: "悬浮气泡内容" },
+      { name: "pricing-table", cn: "价格表", desc: "定价方案对比" },
+      { name: "qr-code", cn: "二维码", desc: "二维码生成" },
+      { name: "table", cn: "表格", desc: "数据表格" },
+      { name: "tag", cn: "标签", desc: "分类标签" },
+      { name: "timeline", cn: "时间轴", desc: "时间线展示" },
+      { name: "tooltip", cn: "文字提示", desc: "悬浮文字提示" },
+      { name: "tree", cn: "树形控件", desc: "树形结构展示" },
+      { name: "video-player", cn: "视频播放", desc: "视频播放器" },
+    ],
+  },
+  {
+    key: "feedback",
+    label: "反馈",
+    components: [
+      { name: "alert", cn: "警告提示", desc: "页面级警告提示" },
+      { name: "alert-dialog", cn: "警告对话框", desc: "强制确认对话框" },
+      { name: "dialog", cn: "对话框", desc: "模态对话框" },
+      { name: "drawer", cn: "抽屉", desc: "侧边抽屉面板" },
+      { name: "feedback", cn: "反馈", desc: "用户反馈组件" },
+      { name: "modal", cn: "模态框", desc: "模态窗口" },
+      { name: "notification", cn: "通知", desc: "全局通知" },
+      { name: "pop-confirm", cn: "气泡确认", desc: "气泡确认框" },
+      { name: "skeleton", cn: "骨架屏", desc: "加载骨架占位" },
+      { name: "spin", cn: "加载中", desc: "加载状态" },
+      { name: "toast", cn: "轻提示", desc: "轻量提示" },
+    ],
+  },
+  {
+    key: "others",
+    label: "其他",
+    components: [
+      { name: "backtop", cn: "回到顶部", desc: "一键回到顶部" },
+      { name: "config-provider", cn: "全局配置", desc: "语言与主题配置" },
+      { name: "cropper", cn: "图片裁切", desc: "图片裁切" },
+      { name: "float-button", cn: "悬浮按钮", desc: "悬浮操作按钮" },
+      { name: "overlay", cn: "浮层", desc: "浮层层级管理" },
+      { name: "tour", cn: "漫游引导", desc: "分步引导" },
+      { name: "watermark", cn: "水印", desc: "页面水印" },
+    ],
+  },
+];
+
+/** 扁平化的组件索引：name → { name, cn, desc, category, categoryLabel, docsUrl } */
+export const CATALOG = CATEGORIES.flatMap((category) =>
+  category.components.map((item) => ({
+    ...item,
+    category: category.key,
+    categoryLabel: category.label,
+    docsUrl: `${DOCS_BASE}/components/${category.key}/${item.name}`,
+  })),
+);
+
+const CATALOG_MAP = new Map(CATALOG.map((item) => [item.name, item]));
+
+/** 查询目录项（不存在时返回 undefined） */
+export function catalogItem(name) {
+  return CATALOG_MAP.get(String(name ?? "").toLowerCase());
+}
+
+/** 组件官网文档链接（未收录于官网的组件返回 null） */
+export function docsUrlFor(name) {
+  return catalogItem(name)?.docsUrl ?? null;
+}
+
+/** 组件中文名（未收录时回退为组件名） */
+export function componentLabel(name) {
+  const item = catalogItem(name);
+  return item ? `${item.name} ${item.cn}` : String(name ?? "");
+}

package/cli-utils.mjs

@@ -0,0 +1,29 @@
+/**
+ * CLI 通用工具（reui-mcp / reui-setup / reui-skills 共用）
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * 判断当前模块是否被「直接执行」（而非被 import）
+ *
+ * 兼容性说明：npm 安装的 bin 在软链场景（`npm link`、`npm i <本地目录>`）下，
+ * `process.argv[1]` 是软链路径，而 `import.meta.url` 指向真实路径，
+ * 直接字符串比较会判定失败并导致 CLI 静默不执行；因此两侧都做 realpath 归一化。
+ *
+ * @param {string} importMetaUrl 调用方传入的 `import.meta.url`
+ */
+export function isEntryModule(importMetaUrl) {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  const self = fileURLToPath(importMetaUrl);
+  const resolved = path.resolve(entry);
+  if (resolved === self) return true;
+  try {
+    return fs.realpathSync(resolved) === fs.realpathSync(self);
+  } catch {
+    return false;
+  }
+}

package/index.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * reui-mcp —— ReUI 组件库 MCP 服务器（stdio）
+ *
+ * 让 AI 助手在写 ReUI 代码时「有据可查」：组件文档、代码示例、源码文件、
+ * 函数实现、跨库检索与库级指南，全部来自项目本地已安装的 @reglow/reui
+ * （或指定 npm 版本 / 官方文档站点兜底）。
+ *
+ * 用法（客户端 mcpServers 配置中作为 command + args）：
+ *   npx -y @reglow/reui-mcp                    # 使用项目本地已安装版本
+ *   npx -y @reglow/reui-mcp --root D:/path/to/reui    # 指定工作区（开发组件库时）
+ *   npx -y @reglow/reui-mcp --default-version 0.1.10  # 固定知识版本
+ *   npx -y @reglow/reui-mcp --check            # 自检：打印知识源与组件数量后退出
+ *   npx -y @reglow/reui-mcp --setup            # 为 Trae/CodeBuddy/Qoder 一键写 MCP 配置 + 装 Skills
+ *   npx -y @reglow/reui-mcp --install-skills   # 仅安装 Skills 知识包（等价于 reui-skills）
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createKnowledgeResolver, createServer } from "./server.mjs";
+import { installSkills, mcpConfigSnippet, runSkillsCli } from "./skills.mjs";
+import { DEFAULT_SETUP_TOOLS } from "./integrations.mjs";
+import { renderToolList, runSetupCli } from "./setup.mjs";
+
+const PACKAGE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const OWN_PACKAGE = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf8"),
+);
+
+const USAGE = [
+  `reui-mcp v${OWN_PACKAGE.version} —— ReUI 组件库 MCP 服务器`,
+  "",
+  "用法：reui-mcp [选项]",
+  "",
+  "选项：",
+  "      --root <dir>              ReUI 仓库工作区路径（未指定时自动解析项目本地已安装的 @reglow/reui）",
+  "      --default-version <ver>   工具未传 version 时默认使用的 @reglow/reui 版本（如 0.1.10、latest）",
+  "      --no-site                 禁用官方文档站点兜底（完全离线）",
+  "      --check                   自检：打印知识源、版本与组件数量后退出",
+  `      --setup [tools]           一键配置 AI 工具（MCP 配置 + Skills），默认 ${DEFAULT_SETUP_TOOLS.join(",")}`,
+  "                                例：--setup trae,codebuddy,qoder / --setup all；支持 --scope user --dry-run --force",
+  "      --install-skills          仅安装 Skills 知识包（可配合 --target / --all / --force）",
+  "      --list-tools              列出支持的工具、MCP 配置路径与 Skills 目录",
+  "      --print-config            打印 MCP 客户端配置片段后退出",
+  "  -v, --version                 打印版本号",
+  "  -h, --help                    显示帮助",
+  "",
+  "MCP 客户端配置示例（Trae / Cursor / Claude Desktop 的 mcpServers）：",
+  JSON.stringify(mcpConfigSnippet(), null, 2),
+].join("\n");
+
+function parseArgs(argv) {
+  const options = {
+    root: undefined,
+    defaultVersion: undefined,
+    allowSite: true,
+  };
+  const passthrough = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--root") options.root = argv[++i];
+    else if (arg.startsWith("--root="))
+      options.root = arg.slice("--root=".length);
+    else if (arg === "--default-version") options.defaultVersion = argv[++i];
+    else if (arg.startsWith("--default-version="))
+      options.defaultVersion = arg.slice("--default-version=".length);
+    else if (arg === "--no-site") options.allowSite = false;
+    else if (arg === "--check") options.check = true;
+    else if (arg === "--print-config") options.printConfig = true;
+    else if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "-v" || arg === "--version") options.ownVersion = true;
+    else passthrough.push(arg);
+  }
+  options.passthrough = passthrough;
+  return options;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  // 工具配置命令（`--setup [tools]` / `setup [tools]`）
+  if (argv.includes("--setup") || argv[0] === "setup") {
+    const index = argv.findIndex((arg) => arg === "--setup" || arg === "setup");
+    // 去掉 --setup 本体，其余参数（含位置形式的目标工具清单）原样交给 reui-setup
+    process.exitCode = runSetupCli(argv.filter((_, i) => i !== index));
+    return;
+  }
+
+  if (argv.includes("--list-tools")) {
+    console.log(renderToolList({ cwd: process.cwd() }));
+    return;
+  }
+
+  // Skills 安装命令（支持 `--install-skills` 与 `install-skills` 两种写法）
+  if (argv.includes("--install-skills") || argv[0] === "install-skills") {
+    const rest = argv.filter(
+      (arg) => arg !== "--install-skills" && arg !== "install-skills",
+    );
+    process.exitCode = runSkillsCli(rest);
+    return;
+  }
+
+  const options = parseArgs(argv);
+  if (options.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (options.ownVersion) {
+    console.log(OWN_PACKAGE.version);
+    return;
+  }
+  if (options.printConfig) {
+    console.log(JSON.stringify(mcpConfigSnippet(), null, 2));
+    return;
+  }
+
+  const logger = (message) => console.error(message);
+  const resolveKnowledge = createKnowledgeResolver({
+    root: options.root,
+    logger,
+  });
+  const knowledge = await resolveKnowledge(options.defaultVersion);
+
+  if (options.check) {
+    const meta = knowledge.meta();
+    const components = knowledge.listComponents();
+    console.log(
+      JSON.stringify(
+        {
+          package: OWN_PACKAGE.name,
+          packageVersion: OWN_PACKAGE.version,
+          knowledgeSource: meta.source,
+          reuiVersion: meta.version,
+          root: meta.root,
+          warning: meta.warning,
+          componentCount: components.length,
+          components: components.map((entry) => entry.name),
+          allowSiteFallback: options.allowSite,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (options.allowSite === false) {
+    logger("[reui-mcp] 已禁用官方文档站点兜底（--no-site）");
+  }
+  const server = createServer({
+    resolveKnowledge,
+    defaultKnowledge: knowledge,
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger(
+    `[reui-mcp] 已启动：knowledge=${knowledge.meta().source} version=${knowledge.meta().version} ` +
+    `components=${knowledge.listComponents().length}`,
+  );
+}
+
+main().catch((error) => {
+  console.error(`[reui-mcp] 启动失败：${error?.stack ?? error}`);
+  process.exitCode = 1;
+});
+
+export { installSkills };