@94ai-plus/cli 0.0.0-stage → 1.0.0-alpha.6

package/dist/readme/common-plus.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="360" height="60" viewBox="0 0 360 60" role="img" aria-labelledby="title">
+  <title id="title">common-ui+</title>
+  <g fill="#409eff" font-family="Verdana, Geneva, sans-serif" font-weight="600">
+    <text x="0" y="48" font-size="48" textLength="322" lengthAdjust="spacingAndGlyphs">common-ui</text>
+    <text x="328" y="31" font-size="36">+</text>
+  </g>
+</svg>

package/dist/readme/contributors-wall.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="176" viewBox="0 0 960 176" role="img" aria-labelledby="title desc">
+  <!-- Generated by utils/statistics/contributors.ts. Do not edit by hand. -->
+  <title id="title">Contributor wall</title>
+  <desc id="desc">Contributors on test, 2026-08-03 to 2026-11-03 (UTC). Initials are used instead of profile photos.</desc>
+  <rect width="960" height="176" rx="20" fill="#0b1020"/>
+  <g font-family="Arial, 'Microsoft YaHei', sans-serif">
+    <text x="32" y="36" fill="#cbd5e1" font-size="16">Thank you to everyone who contributes.</text>
+    <g transform="translate(62 82)">
+      <title>zoujiahe: 70 commits</title>
+      <circle r="25" fill="#172036" stroke="#a3e635" stroke-width="2"/>
+      <text text-anchor="middle" y="7" fill="#a3e635" font-size="20" font-weight="700">ZO</text>
+      <text text-anchor="middle" y="45" fill="#e2e8f0" font-size="11">zoujiahe</text>
+      <text text-anchor="middle" y="62" fill="#94a3b8" font-size="10">70 commits</text>
+    </g>
+  </g>
+</svg>

package/dist/readme/contributors.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="480" viewBox="0 0 960 480" role="img" aria-labelledby="title desc">
+  <!-- Generated by utils/statistics/contributors.ts. Do not edit by hand. -->
+  <title id="title">Meet Our Contributors!</title>
+  <desc id="desc">Non-merge commits on test, 2026-08-03 to 2026-11-03 (UTC). Bubble size indicates commits; initials are used instead of profile photos.</desc>
+  <rect width="960" height="480" rx="20" fill="#0b1020"/>
+  <g font-family="Arial, 'Microsoft YaHei', sans-serif">
+    <defs><pattern id="dots" width="20" height="20" patternUnits="userSpaceOnUse"><circle cx="2" cy="2" r="1" fill="#334155"/></pattern></defs>
+    <rect x="320" y="110" width="600" height="310" fill="url(#dots)" opacity=".45"/>
+    <path d="M 320 414 Q 650 240 918 330 M 320 430 Q 620 260 918 350" fill="none" stroke="#334155" stroke-opacity=".5"/>
+    <text x="40" y="54" fill="#f8fafc" font-size="30" font-weight="700">Meet Our Contributors!</text>
+    <text x="40" y="84" fill="#94a3b8" font-size="14">2026-08-03 → 2026-11-03 · UTC · test</text>
+    <text x="48" y="204" fill="#60a5fa" font-size="56" font-weight="700">70</text>
+    <text x="48" y="232" fill="#cbd5e1" font-size="16">non-merge commits</text>
+    <text x="48" y="304" fill="#f8fafc" font-size="36" font-weight="700">1</text>
+    <text x="48" y="332" fill="#cbd5e1" font-size="16">contributor · last 3 months</text>
+    <g transform="translate(622.00 268.00)">
+      <title>zoujiahe: 70 commits</title>
+      <defs><radialGradient id="bubble-0" cx="30%" cy="20%" r="85%"><stop stop-color="#a3e635" stop-opacity=".5"/><stop offset="1" stop-color="#10182e"/></radialGradient></defs>
+      <circle r="110.00" fill="url(#bubble-0)" stroke="#a3e635" stroke-width="2"/>
+      <circle r="105.00" fill="none" stroke="#a3e635" stroke-opacity=".2"/>
+      <text text-anchor="middle" y="-8" fill="#fff" font-size="42.00" font-weight="700">ZO</text>
+      <text text-anchor="middle" y="20" fill="#e2e8f0" font-size="14">zoujiahe</text>
+      <text text-anchor="middle" y="43" fill="#cbd5e1" font-size="13.00">70 commits</text>
+    </g>
+    <text x="40" y="452" fill="#94a3b8" font-size="12">Local Git history · Initials, not profile photos · common-ui-plus</text>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,47 @@
 {
+  "version": "1.0.0-alpha.6",
+  "license": "MIT",
+  "homepage": "https://oss.xccjh.top/common-ui-plus/index.html",
+  "keywords": [
+    "vue3组件库",
+    "拥抱最新技术生态，面向AI，九四智能下一代公共组件库",
+    "九四智能组件库",
+    "94ai 组件库",
+    "teleai 组件库",
+    "94 Intelligent Technology Co., Ltd. Component Library"
+  ],
+  "bugs": {
+    "url": "http://gitlab.94ai.pro/ui/common-ui-plus/-/issues"
+  },
   "name": "@94ai-plus/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Offline Common UI Plus knowledge CLI and read-only MCP server",
+  "type": "module",
+  "bin": {
+    "common-ui": "./dist/index.mjs"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./knowledge": "./dist/data/knowledge.json",
+    "./skill": "./skills/common-ui/SKILL.md"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+http://gitlab.94ai.pro/ui/common-ui-plus.git",
+    "directory": "packages/cli"
+  },
+  "commonUiPlus": {
+    "kind": "tooling"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "f677cf8b2bb4a43cc5d3c46f9b80403a8c121a93"
+}

package/skills/common-ui/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: common-ui
+description: >-
+  使用 Common UI Plus（@94ai-plus/*）开发 Vue 3 业务页面、查询组件 API 和示例、调整主题与国际化、诊断接入问题、分析项目用法、评估版本差异时使用。通过 common-ui CLI、MCP 或版本化 LLM 文档核实资料；组件库仓库维护仍遵循其 AGENTS.md。
+---
+
+# Common UI Plus
+
+面向 Vue 3 / Element Plus / `@94ai-plus/*` 业务项目。先核实版本和契约，再编写组件代码。旧 Vue 2 / Element UI 的 `@94ai/*` 是独立组件库，不混用运行时。
+
+## 首次接入
+
+1. 在业务项目根目录查看依赖与包管理器，优先使用已安装的 `common-ui`。`common-ui --help` 查看真实能力，`common-ui --cli-version` 查看工具自身版本。
+2. CLI 不在 PATH 时，使用项目包管理器执行本地 bin。组件库源码开发可运行 `yarn build:components cli`，再用 `node packages/cli/dist/index.mjs` 替代下文的 `common-ui`。
+3. 需要安装时，沿用项目包管理器及已有授权，选择已发布的 `@94ai-plus/cli`。不要自动全局安装或为了消除资料报错而升级组件运行时。
+4. 已有 MCP 时直接使用查询工具；没有 CLI/MCP 时，按 [文档与 MCP 接入](references/integration.md) 读取匹配版本的在线资料。
+
+Skill 本身不会安装 CLI、启动 MCP 或修改客户端配置。
+
+## 版本与来源
+
+- CLI 尝试解析当前项目安装的总包或独立组件包；未发现安装版本时使用随包快照。因此查询成功不等于已确认业务版本。
+- `--version` 指定精确资料版本。先用匹配的随包／缓存快照，缺失时从版本化在线文档下载并校验来源与摘要；`--offline` 禁止联网，`--refresh` 强制重新获取。
+- `local` 只用于匹配的组件库源码开发，不代表 npm 已发布版本。线上 `versions` 列表只包含实际构建并发布的文档快照，不能凭当前源码补造历史资料。
+- **找不到与项目版本匹配的资料时，会明确报错，不要擅自用其他版本的文档代替。** 混装版本先定位兼容问题，再确定目标版本。
+- 代理优先用 `--format json`，解析 `provenance` 和 `result`，核对 version、channel、commit、dirty、digest 与语言。Markdown 输出正文在 stdout，来源信息在 stderr，不能把来源或错误粘进 Vue 文件。
+
+参数、输出和错误处理见 [命令参考](references/commands.md)。
+
+## 根据任务选择流程
+
+| 用户任务 | 工具与资料 |
+| --- | --- |
+| 选组件、搭页面、写 SFC | `list` → `info` → `demo`，必要时 `doc`；见 [开发流程](references/workflows.md#开发页面与组件接入) |
+| 找完整或单组件文档 | `doc NfTable`、页面顶部 `LLMs.md`；见 [按需读取](references/integration.md#文档与版本) |
+| 颜色、尺寸、主题与样式 | `design`、`token`、`theme`、`semantic`；见 [主题与配置](references/workflows.md#主题全局配置与国际化) |
+| 排查渲染、默认值、表格或软电话 | `env`、`doctor`、匹配版本的 `info` / `doc`、`lint`；见 [诊断](references/workflows.md#诊断与业务回归) |
+| 统计组件使用情况 | `usage ./src`、`--filter`；见 [项目命令](references/commands.md#项目工具) |
+| 检查导入与旧 Vue 写法 | `lint ./src`；查看报告位置及 limitations，不代替类型检查 |
+| 升级评估、版本差异与日志 | `versions`、`diff`、`changelog`；见 [版本工具](references/commands.md#版本与维护) |
+| 配置 IDE 的 MCP 或 Skill | `setup --client` 配置项目；先核对计划及当前任务授权，见 [项目接入配置](references/integration.md#项目接入配置) |
+| 更新 CLI 或报告问题 | `upgrade`、`bug`、`bug-cli` 默认预览；先审阅再执行授权的写入 |
+
+只加载与当前任务有关的参考说明，不必一次读完全部文件。
+
+## 编写组件代码的起点
+
+```sh
+common-ui list --format json
+common-ui info NfSearchForm --lang zh-CN --format json
+common-ui demo NfSearchForm --lang zh-CN --format json
+common-ui doc NfSearchForm --lang zh-CN --format markdown
+```
+
+`demo` 不带示例 ID 时返回目录；从结果中选真实 `id`，再执行 `common-ui demo NfSearchForm <example-id> --format json`。尖括号是待替换参数，不要原样执行。读取返回的 `files` 与 `requires`，保留相关模块、语言上下文及全局注册前提，不只复制第一个片段就宣称完整可用。
+
+## 组件接入的关键约定
+
+- 从真实资料确认 props、默认值、events、slots、实例方法和导出名；文档与源码声明冲突时核实来源，不补造 API。
+- 总包、独立包、自动按需、CJS、ESM、HTML/UMD 各有接入前提。沿用业务工程方案和公开 exports／样式入口，不拼接旧 `lib` 路径。
+- `NfConfigProvider` 属于总包。默认属性、主题、语言分别配置；保留显式的 `false`、`0`、空字符串。服务按文档显式导入并使用匹配的应用／provider 上下文。
+- Design Token 是颜色、尺寸等设计变量。Element Plus 原始变量与 Common UI 的 Chalk/OEM 覆盖分别核对；白／黑页面外观与组件主题独立，不猜测内部 CSS 类名。
+- 表单绑定值、选择器异步分页、表格 loading／缓存标识、弹层挂载位置和服务销毁按组件文档验证。
+- 软电话先确认 SFC、单例还是多实例管理器，核实签名、初始化、loading、通知和卸载流程。远程服务成功与本地 Vue 渲染成功分别验证，不复制联调凭据到业务配置或报告。
+- 知识查询和静态扫描不代表运行验证。使用业务项目原有类型检查、构建及必要浏览器回归，说明实际执行的检查。
+
+## 权限与能力边界
+
+知识查询及项目扫描不执行项目源码，不自动修复业务文件。网络读取用于明确版本的官方文档；使用 `--offline` 可仅查随包／缓存。`doctor` / `lint` 的局限见每份报告的 `limitations`。
+
+`upgrade` 默认生成安装计划，`bug` / `bug-cli` 默认生成报告预览。只有用户已授权相应动作时，才运行 `upgrade --yes` 或报告的 `--submit --yes`；不以 Skill 本身代替授权。执行失败后查看依赖变化／远程状态，不盲目重试造成重复写入。
+
+本工具没有 `--fix` 或自动迁移 codemod；`semantic` 提供文档化样式入口，不仿造 antd 的内部语义 API。历史版本必须确有快照，不能承诺旧版本在此功能实施前已自动归档。
+
+库内维护遵循 `AGENTS.md`；未明确要求时不更新 changelog，不擅自提交、推送、发布或发送外部消息。

package/skills/common-ui/references/commands.md

@@ -0,0 +1,84 @@
+# 命令参考
+
+## 知识查询
+
+| 命令 | 用途 |
+| --- | --- |
+| `common-ui list` | 当前快照的组件、公开包及导出 |
+| `common-ui info NfTable` | API 表格、导入、样式、源码声明及来源 |
+| `common-ui doc NfTable` | 单组件完整 Markdown |
+| `common-ui demo NfTable` | 示例目录及真实 ID |
+| `common-ui demo NfTable <example-id>` | 指定示例的源码、相关文件和前提 |
+| `common-ui theme --theme chalk` | Common UI 主题变量；支持 Chalk/OEM |
+| `common-ui token --theme oem` | Element Plus 明暗主题 CSS 变量及 Common UI 覆盖 |
+| `common-ui token ElButton` | Element Plus Button 原始变量及共享根变量，保留 selector 和 var() |
+| `common-ui token NfButton` | 上游 Token 与 NfButton 的公开样式入口；不假定 NfButton 包装 ElButton |
+| `common-ui semantic NfTable` | 文档化的 class/style/size/theme 属性、插槽及样式入口 |
+| `common-ui design --theme chalk` | 设计语言及主题变量 |
+| `common-ui changelog` | 当前正式快照对应的版本说明；local 无版本日志 |
+
+默认 JSON 输出为 `{ provenance, result }`。`--format markdown` 或 `text` 在存在 Markdown 正文时输出正文，来源写 stderr；其他结果仍是 JSON。
+
+| 参数 | 约定 |
+| --- | --- |
+| `--version <exact-version>` | 指定精确快照；匹配随包／缓存，否则从已发布版本文档获取 |
+| `--offline` | 禁止联网，仅使用随包／缓存；缺失就报错 |
+| `--refresh` | 重新获取精确版本；不能与 `--offline` 同用 |
+| `--docs-url <https-site-base>` | 选择 HTTPS 主站或 OEM base，不能含凭据、查询或片段 |
+| `--lang zh-CN` | 支持 `zh-CN`、`en-US`、`ja`、`es`、`id`、`th`、`tl`、`pt`，不支持 `zh` / `en` 缩写 |
+| `--theme chalk` / `oem` | 用于 theme、token 和 design |
+| `--component NfTable` | 用于 diff 的组件过滤 |
+| `--cli-version` / `-V` | CLI 工具包版本，不等于业务组件库版本 |
+
+## 项目工具
+
+```sh
+common-ui env ./my-project --format json
+common-ui doctor ./my-project --format json
+common-ui usage ./src --project ./my-project --filter NfTable --format json
+common-ui lint ./src --project ./my-project --format json
+common-ui lint ./src --only migration --format json
+```
+
+- `env`：Node／平台／架构、包管理器声明、锁文件存在情况、相关依赖的声明范围与安装版本、知识快照身份。不读认证文件或环境文件，不执行业务依赖，也不扫描浏览器。
+- `doctor`：Vue 主版本、Vue/compiler 版本、Element Plus 是否可解析、旧运行时、混装版本、快照身份与多个锁文件；不是完整依赖求解器。错误级诊断导致非零退出。
+- `usage`：静态导入、Vue 模板和 JSX 分布，支持导入别名，返回文件位置及 imports/renders 统计；不是运行时调用次数。动态组件、命名空间成员、运行时注册可能漏检。
+- `lint`：已知包不存在的具名运行时导出、可识别旧包导入、组件 `.sync` / `slot-scope` 和解析失败。`--only` 支持 `imports`、`migration`、`parse`；不检查所有 props、性能或无障碍规则，无 `--fix`。错误级发现导致非零退出。
+
+扫描路径必须位于 `--project` 内。排除隐藏目录、符号链接、声明、依赖和常见构建输出，不声称完全遵循每个项目的 `.gitignore`。报告不返回源码和属性值；超过大小／文件数上限时缩小范围，不把失败当作完整结果。
+
+项目命令不接受 `--version`、`--lang`、`--theme`。usage/lint 根据可解析安装版本选择匹配知识；env/doctor 可以在冲突时先提供诊断。
+
+## 版本与维护
+
+```sh
+common-ui versions --format json
+common-ui changelog 1.0.0-alpha.5 --format json
+common-ui changelog 1.0.0-alpha.5..1.0.0-alpha.6 --format json
+common-ui diff ./from.json ./to.json --component NfTable --format json
+common-ui upgrade 1.0.0-alpha.6 --dry-run
+common-ui bug --title "问题标题" --steps "复现步骤" --expected "预期" --actual "实际" --dry-run
+common-ui bug-cli --title "CLI 问题" --description "诊断说明" --dry-run
+```
+
+上述版本号只演示语法，不代表这些版本已有在线快照。`versions` 读取已发布目录；changelog 范围端点必须都存在，按该目录的已归档版本输出，不静默跳过缺失端点。离线范围不自动发现目录，可改为逐个查缓存版本。
+
+`diff` 读取两份明确提供且摘要校验通过的 knowledge JSON，比较组件增删、导出、声明、API 表格、文档／示例和主题。它是结构比较，不自动判定所有 breaking changes。
+
+`upgrade <exact-cli-version>` 默认预览包管理器安装计划，只更新 CLI 工具，不自动选择 latest 或升级组件库。默认项目级安装，`--project` 选择目录，`--global` 显式选择 npm 全局安装。审阅且获得用户授权后加 `--yes` 执行；与 `--dry-run` 互斥。
+
+`bug` / `bug-cli` 支持 `--title`、`--description`、`--steps`、`--expected`、`--actual`、`--reproduction`、`--project`。默认仅返回报告和非敏感环境信息。检查不含凭据／无关业务数据，并获得用户提交授权后，才用 `--submit --yes` 向 `94ai-plus/common-ui-plus` 创建 GitHub Issue；认证使用专用 `GITHUB_TOKEN`。提交超时或失败先检查远程，避免重复报告。不做自动升级或自动上报。
+
+## 错误处理
+
+`VERSION_UNAVAILABLE`：获取匹配资料，不能换版本或改业务依赖来消除错误。`LOCALE_UNAVAILABLE`：使用支持的语言，说明缺失。`COMPONENT_NOT_FOUND` / `EXAMPLE_NOT_FOUND`：重新 list/demo 获取真实标识。`INVALID_ARGUMENT`：查看本命令帮助，不套用 antd 参数。`INVALID_DATA`：重新获取合法匹配包或构建，不能忽略摘要。`PROJECT_NOT_FOUND` / `INVALID_PROJECT`：核实项目根目录。`INVALID_SCAN_PATH` / `SCAN_LIMIT`：缩小允许的源码范围。其余失败保留错误和实际已完成步骤，停止有风险的写入重试。
+
+## 安装 Skill
+
+用户要求安装本包 Skill 时，使用 `common-ui skills install`，默认在当前项目交互选择 AI 工具；`--agent codex` 指定工具，`--global` 选择用户级范围，`--project <directory>` 指定项目。`--yes` 跳过 Skills 交互，`--dry-run` 只预览且不能与 `--yes` 同用。
+
+命令通过 npm/npx 调用固定的 `skills@1.7.6`，复制 CLI 自带的 `skills/common-ui/`（包含 references），不依赖 GitHub 分支或 npx 缓存长期保留。需要 npm registry 访问；不接受知识查询的 `--offline`、`--version` 等选项。不配置 MCP，不以 Skill 内容代替安装授权。
+
+## 配置项目接入
+
+`common-ui setup --client claude|cursor|vscode|codex` 写入项目配置；默认 `--mode mcp`，也支持 `skill`、`both`。`--project` 选择项目，`--version` 选择组件资料版本，`--lang` 选择语言，`--write-instructions` 追加客户端指令。`--dry-run` 仅预览；`--check` 只读检查，缺失或差异时退出码为 1；这两项互斥。命令不访问网络，不覆盖同名冲突内容；完整路径和行为见 [项目接入配置](integration.md#项目接入配置)。

package/skills/common-ui/references/integration.md

@@ -0,0 +1,52 @@
+# 文档与 MCP
+
+## 文档与版本
+
+主站 `https://oss.xccjh.top/common-ui-plus/`，OEM 站 `https://oss.xccjh.top/common-ui-plus-oem/`。根站点表示当前部署资料，`versions.json` 列出实际保存的版本；历史站点位于 `versions/<exact-version>/`，使用该目录下自己的组件示例、静态资源与知识快照。
+
+从实施后的真实发布建立快照，不能假设此前版本已自动存在。站点版本切换保留语言和页面；旧版没有该页面时明确提示并打开该版本首页，不偷偷替换成新版组件文档。
+
+| 版本目录内的资源 | 用途 |
+| --- | --- |
+| `llms.txt` | 文档及组件索引 |
+| `llms-full.txt` / `llms-full-cn.txt` | 英文／中文完整资料 |
+| `design.md` | 设计规范 |
+| `ai/manifest.json` | version、channel、commit、dirty、digest 和组件地址 |
+| `ai/knowledge.json` | 完整知识快照；可供 diff |
+| `ai/docs/zh-CN/table.md` | 单个组件 Markdown；按索引替换 ID 与语言 |
+| `ai/components/table.json` | 单组件结构化 API、声明与示例 |
+| `ai/examples/zh-CN/table/<example-id>.json` | 真实 ID 对应的完整示例 |
+
+组件页面顶部 LLMs.md 打开当前语言 Markdown。先读索引及相关组件／示例，不必为一个属性加载全文集合。核对 manifest 与业务版本，联网失败不能宣称读取成功。
+
+CLI 优先随包和本地缓存；远程按精确版本下载并校验目录身份／摘要后缓存。`--offline` 禁止联网，`--refresh` 强制刷新，`--docs-url` 可选择 HTTPS 主站或 OEM base。未知版本报错，不回退。
+
+## MCP
+
+PATH 中有 CLI 时可用以下配置，按客户端实际格式保存：
+
+```json
+{"mcpServers":{"common-ui":{"command":"common-ui","args":["mcp","--lang","zh-CN"]}}}
+```
+
+本地源码构建或客户端 PATH 不同，使用 Node 和真实绝对路径：
+
+```json
+{"mcpServers":{"common-ui":{"command":"node","args":["/absolute/path/common-ui-plus/packages/cli/dist/index.mjs","mcp","--lang","zh-CN"]}}}
+```
+
+路径示例需替换。Windows JSON 路径用正斜杠或正确转义。客户端工作目录可能不是业务根目录，确认后用 `--version` 指定真实精确版本。离线环境加 `--offline`，可用缓存。不要覆盖用户已有 MCP 配置。
+
+MCP 提供 `common_ui_list`、`common_ui_info`、`common_ui_doc`、`common_ui_demo`、`common_ui_theme`、`common_ui_token`、`common_ui_semantic`、`common_ui_design`、`common_ui_changelog`；提示词为 `common-ui-expert`、`common-ui-page-generator`。
+
+参数为字符串字段 component、example、version、lang、theme，只传本次查询需要的字段，例如 `{"component":"NfTable","lang":"zh-CN"}`。info/doc/demo/semantic 需要组件；demo 无 example 时先列目录，再选真实 ID。
+
+工具 `content[].text` 中是含 provenance/result 的 JSON；先检查 isError。MCP 通过 stdio JSON-RPC 工作，不是 HTTP 服务、不调用模型 API。项目扫描、双文件 diff、安装和报告提交仅为 CLI 功能，MCP 不开放任意文件路径或写入工具。启动命令不传 --format、--theme 或组件位置参数。
+
+## 项目接入配置
+
+用户要求配置客户端时，可先用 `common-ui setup --client <claude|cursor|vscode|codex> --dry-run` 查看具体计划。`--mode mcp|skill|both` 默认 mcp；普通命令会实际写项目文件，沿用当前任务已提供的授权，不把 Skill 自身视为授权。`--write-instructions` 按客户端追加 Common UI 指令块，保留原文。
+
+MCP 配置分别位于 `.mcp.json`、`.cursor/mcp.json`、`.vscode/mcp.json`、`.codex/config.toml`；前两者使用 mcpServers，VS Code 使用 servers，Codex 使用 mcp_servers TOML 表。Skill 复制当前 CLI 的完整随包目录到 `.claude/skills/common-ui/`、`.cursor/skills/common-ui/`、`.github/skills/common-ui/`、`.agents/skills/common-ui/`。不触碰用户级配置，不自动运行客户端。
+
+`--project` 指定目标项目；生成配置固定 CLI 工具版本并传入项目绝对目录，`--version` 可另外指定组件知识版本，`--lang` 指定语言。相同内容重复运行无改动，已有同名配置或 Skill 差异会报告冲突，不自动覆盖。`--check` 不联网、不写文件，缺失或差异返回非零退出码；检查通过只表示文件一致，客户端需自行加载／授权，Codex 的项目设置仅对受信任项目生效。JSON/JSONC 需合法且无重复服务键；Codex 不支持安全追加的内联 mcp_servers 表需要手动配置。

package/skills/common-ui/references/workflows.md

@@ -0,0 +1,36 @@
+# 开发与诊断流程
+
+## 开发页面与组件接入
+
+1. 用 list 选择真实组件，按业务契约读 info/doc；不要默认 Common UI 包含 Element Plus 的全部属性。
+2. demo 不带 ID 先列目录，再选真实 ID；保留 source、files、requires 中的相关模块与注册／语言前提。
+3. 沿用项目总包、独立包或自动按需方案，查对应快速上手说明。脚本中的 Message、Notification、Confirm 等服务仍需显式导入。
+4. 适配绑定值、事件、空值、禁用、loading、校验与浮层，运行业务项目的类型、构建和交互验证。
+
+表单核实字段类型、模型及验证；选择器核实异步分页、搜索重置和挂载上下文；表格核实前后端分页、loading 收尾、列设置与当前版本的缓存约定。不要从旧实现推断 IndexedDB/localStorage。Drawer 与服务组件核实关闭拦截、回调／Promise 和独立实例清理。
+
+## 主题全局配置与国际化
+
+用 design 获取规则，token 获取实际 Element Plus 的明暗 CSS 变量，theme 查看 Common UI Chalk/OEM 变量，semantic 查文档化样式属性与插槽。变量记录保留 selector 和 var()，不是全部计算后的最终颜色，也不是认证 Token。
+
+NfConfigProvider 的继承不覆盖实例显式 false/0/空字符串。Chalk/OEM 与白／黑外观独立；组件语言、Element Plus 语言及业务文本分别适配。保留组件尺寸契约，使用公开样式变量／入口，不猜内部 DOM 或 antd classNames API。
+
+## 诊断与业务回归
+
+根据问题选择 env → doctor → 匹配版本的 info/doc/demo → lint。env 中 declared 是声明范围，installed 是可解析安装版本。doctor/lint 是只读诊断，无发现不等于运行正确；解析警告意味着分析不完整。
+
+建立最小复现，区分依赖、API、样式、配置、数据和远程服务问题；修复后运行项目已有检查，记录预期／实际、复现步骤和验证范围。
+
+软电话先区分 NfSoftphone SFC、nfSoftphone 单例和 nfSoftphoneManager 多实例，读取匹配示例的初始化、签名／timestamp、autoStart、loading／ready、动作／通知及销毁契约。异步签名完成后确保属性更新再启动；卸载期间不能继续创建实例。多实例检查 name 和消息来源隔离。不要把文档联调配置当成业务凭据；本地渲染和远程登录／通话分别验证。
+
+## 版本比较
+
+用 usage 定位影响位置，用 lint 查支持的旧写法，再做业务回归。升级现有 @94ai-plus 项目时，从实际已发布的在线版本／CLI 包取得前后 knowledge JSON，再用 diff 和 changelog 判断影响；结构差异不自动等于 breaking change。没有历史快照时明确缺失，不用当前源码冒充旧 API。
+
+## 项目分析、升级与问题报告
+
+usage 的导入次数和渲染次数是静态指标；动态组件与命名空间调用需补充手工检索。lint 与原有 ESLint、Vue 类型检查配合，不替代后者。
+
+升级 CLI 前确认目标工具版本、项目包管理器、安装范围与现有授权。先预览 upgrade 计划，再执行获准的安装；失败检查依赖和锁文件变化，不无界重试。工具更新不等于业务运行时升级。
+
+用 bug/bug-cli 预览版本、环境、复现、预期／实际报告，先移除凭据与无关业务内容。只有明确授权后才提交；网络失败先检查是否已创建，避免重复。不能因 Skill 被加载就自动发外部消息。