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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 94AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+<!-- common-ui-plus:brand:start -->
+<h1 align="center">
+  <a href="https://oss.xccjh.top/common-ui-plus/index.html">
+    <img src="https://cdn.jsdelivr.net/npm/@94ai-plus/cli@1.0.0-alpha.6/dist/readme/94logo.png" width="150" height="50" alt="94AI" />
+    &nbsp;
+    <img src="https://cdn.jsdelivr.net/npm/@94ai-plus/cli@1.0.0-alpha.6/dist/readme/common-plus.svg" width="300" height="50" alt="common-ui+" />
+  </a>
+</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@94ai-plus/cli"><img src="https://img.shields.io/npm/v/%4094ai-plus/cli/latest.svg?label=version" alt="npm latest 版本" /></a>
+  <a href="https://nodejs.org/en/blog/release/v22.13.0"><img src="https://img.shields.io/badge/Node.js-22.13.0-5FA04E.svg" alt="开发环境 Node.js 22.13.0" /></a>
+  <a href="https://vuejs.org/"><img src="https://img.shields.io/badge/Vue-3.5-42B883.svg" alt="Vue 3.5" /></a>
+  <a href="https://cdn.jsdelivr.net/npm/@94ai-plus/cli@1.0.0-alpha.6/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://oss.xccjh.top/common-ui-plus-badges/test-pass-rate.svg"><img src="https://oss.xccjh.top/common-ui-plus-badges/test-pass-rate.svg" alt="Repository test pass rate (default branch), not per-package results" /></a>
+  <a href="https://oss.xccjh.top/common-ui-plus-badges/coverage.svg"><img src="https://oss.xccjh.top/common-ui-plus-badges/coverage.svg" alt="Repository source line coverage (default branch), not per-package coverage" /></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@94ai-plus/cli"><img src="https://nodei.co/npm/@94ai-plus/cli.svg?downloads=true&amp;downloadRank=true" width="360" alt="NPM" /></a>
+</p>
+<!-- common-ui-plus:brand:end -->
+
+# @94ai-plus/cli
+
+Common UI 的离线知识和项目工具，提供只读 MCP 服务与组件使用 Skill，面向 Vue 3 / Element Plus 业务项目。运行环境需要 Node.js **22.13.0 或更高版本**及 npm/npx。
+
+## 安装与快速开始
+
+安装已发布版本作为项目开发依赖：
+
+```sh
+npm install -D @94ai-plus/cli
+npx common-ui --help
+npx common-ui info NfTable --lang zh-CN
+```
+
+也可全局安装后使用 `common-ui`，或不预先安装，临时执行：
+
+```sh
+npx --package @94ai-plus/cli common-ui list
+```
+
+组件库源码仓库先执行 `yarn build:components cli`，再使用 `node packages/cli/dist/index.mjs` 替代 `common-ui`，例如 `node packages/cli/dist/index.mjs info NfTable --lang zh-CN`。
+
+## 命令概览
+
+下表使用全局安装后的命令；项目内安装时改用 `npx common-ui`。
+
+| 命令 | 用途 |
+| --- | --- |
+| `list` | 列出组件、包及公开导出 |
+| `info NfTable` | 查询属性、事件、插槽、源码类型声明和来源 |
+| `doc NfTable --format markdown` | 获取单个组件完整 Markdown |
+| `demo NfTable` | 列出示例 ID；用 `demo NfTable <example-id>` 读取完整示例 |
+| `theme --theme chalk` | 查询 Chalk／OEM 主题变量 |
+| `token ElButton` | 查询 Element Plus 明暗 Design Token 与 Common UI 主题覆盖 |
+| `design` | 获取双主题设计规范 |
+| `semantic NfTable` | 查询文档公开的样式属性与插槽 |
+| `changelog <exact-version>` | 查询精确版本说明，也支持 `<from>..<to>` 区间 |
+| `versions` | 查看已发布的在线文档版本 |
+| `env` / `doctor` | 检查运行环境、依赖版本与项目接入 |
+| `usage ./src` / `lint ./src` | 统计组件用法、检查导入及旧 Vue 写法 |
+| `diff ./from.json ./to.json` | 比较两份明确提供的知识快照 |
+| `mcp` | 启动只读 MCP stdio 服务 |
+| `skills install` | 安装随包的 common-ui Skill |
+| `setup --client cursor --mode both` | 配置项目 MCP 与 Skill |
+| `upgrade <exact-cli-version> --dry-run` | 预览明确版本的 CLI 升级 |
+| `bug --title "Component issue" --dry-run` | 预览组件库问题报告 |
+| `bug-cli --title "CLI issue" --dry-run` | 预览 CLI 问题报告 |
+| `--help` / `--cli-version` | 查看帮助或 CLI 工具包版本 |
+
+知识查询默认输出 JSON；支持 `--format json|text|markdown`、`--lang` 和 `--theme chalk|oem`。`info` 等知识查询的 JSON 包含 `provenance` 与 `result`，可核对版本、来源提交和摘要。八语言标识为 `zh-CN`、`en-US`、`ja`、`es`、`id`、`th`、`tl`、`pt`。
+
+## 精确版本与离线资料
+
+先确认业务项目安装的组件库版本，再查询对应版本的属性、事件、插槽、实例方法与完整示例。CLI 可从项目依赖检测版本，也可通过 `--project <directory>` 指定项目、`--version <exact-version>` 显式选择资料版本；找不到匹配资料时明确报错，不编造接口，不擅自用其他版本的文档代替。
+
+```sh
+npx common-ui doc NfTable --version <exact-version> --offline --format markdown
+npx common-ui doc NfTable --version <exact-version> --refresh --format json
+npx common-ui versions --format json
+```
+
+优先使用匹配的随包知识或已验证缓存，缺失时从在线 `versions.json` 获取精确快照并校验 commit／digest。`--offline` 禁止联网，`--refresh` 重新获取资料；`--docs-url` 可选择 HTTPS 主站或 OEM base。未知语言同样明确报错。
+
+源码构建资料为 `local`；npm 发布预检在测试完成后生成 fixed version 快照。快照记录来源，不代表包已上传。在线历史按真实发布逐版保留，不能用当前源码补造旧版。完整知识也可通过 [LLMs.txt](https://oss.xccjh.top/common-ui-plus/ai/llms)、[单组件 LLMs.md](https://oss.xccjh.top/common-ui-plus/ai/docs/zh-CN/table.md) 和 [manifest.json](https://oss.xccjh.top/common-ui-plus/ai/manifest.json) 按需读取。
+
+## 主题与项目工具
+
+`token` 从锁定 Element Plus 的明暗 CSS 提取变量，保留选择器、原始值、版本及上游 SCSS 来源；Common UI Chalk／OEM 覆盖单独列出。`theme` 输出主题变量数据，不生成 CSS，也不修改项目主题。`semantic` 仅整理文档公开的样式属性和插槽。
+
+`env`／`doctor` 提供只读诊断；`usage`／`lint` 分析静态导入、Vue 模板与 JSX，排除依赖、隐藏目录、符号链接和生成目录，不执行业务源码。扫描不代替完整类型、属性、无障碍或运行时验证。`diff` 需要合法的 knowledge JSON；changelog 区间端点必须存在。
+
+`upgrade` 默认预览明确版本的项目级安装计划，`--global` 选择用户级范围，`--yes` 才安装，不自动升级组件运行时。`bug`／`bug-cli` 默认预览；审阅后以 `--submit --yes` 和 `GITHUB_TOKEN` 向 `94ai-plus/common-ui-plus` 创建 Issue。
+
+## 安装 Skill
+
+Skill 位于 `skills/common-ui/SKILL.md`，附带 `references/commands.md`、`workflows.md`、`integration.md`，将 Agent 定位为 common-ui 专家，指导其按匹配版本查询组件 API、完整示例与设计规范。
+
+```sh
+npx --package @94ai-plus/cli common-ui skills install
+```
+
+已安装 CLI 时：
+
+```sh
+npx common-ui skills install
+npx common-ui skills install --agent codex --yes
+npx common-ui skills install --dry-run
+```
+
+固定调用 `skills@1.7.6`，默认交互选择工具、项目级安装，以复制方式保留完整 Skill 与 references，不依赖 npx 临时缓存。支持 Claude Code、Cursor、Codex、Gemini CLI 及安装器兼容的其他 Agent。`--agent` 指定工具，`--global` 选择用户级，`--project <directory>` 指定目录，`--yes` 跳过交互确认；`--dry-run` 不联网、不安装。
+
+安装 Skill 不会永久安装 CLI、启动 MCP 或修改 MCP 配置。完整说明见 [For Agents](https://oss.xccjh.top/common-ui-plus/ai/for-agents)。
+
+## MCP 服务
+
+提供九个只读知识工具和两个提示词：`common-ui-expert`、`common-ui-page-generator`。服务与 CLI 共用版本资料，不调用模型 API、不修改业务项目；项目扫描、安装和问题提交由 CLI 单独提供。
+
+Claude Code／Cursor 等使用 `mcpServers` 的客户端可配置：
+
+```json
+{
+  "mcpServers": {
+    "common-ui": {
+      "command": "npx",
+      "args": ["--yes", "--package", "@94ai-plus/cli", "common-ui", "mcp", "--lang", "zh-CN"]
+    }
+  }
+}
+```
+
+客户端工作目录与项目不同时，在 args 中增加 `--project` 和项目绝对路径；`--version` 单独指定组件库资料版本。VS Code 使用 `servers`，Codex 使用 TOML，更多工具及示例见 [MCP 文档](https://oss.xccjh.top/common-ui-plus/ai/mcp)。
+
+## 项目接入配置
+
+```sh
+npx common-ui setup --client claude
+npx common-ui setup --client cursor --mode both
+npx common-ui setup --client vscode --write-instructions
+npx common-ui setup --client codex --dry-run
+npx common-ui setup --client codex --check
+```
+
+`--client` 支持 `claude`、`cursor`、`vscode`、`codex`；`--mode` 支持 `mcp`（默认）、`skill`、`both`。`setup` 只写所选项目，分别配置 `.mcp.json`、`.cursor/mcp.json`、`.vscode/mcp.json` 或 `.codex/config.toml`，完整复制 Skill 与 references。`--write-instructions` 只追加或更新带标记的说明，保留已有内容。
+
+生成的 MCP 配置固定当前 CLI 包版本，用 `mcp --project <绝对目录>` 识别项目；`--version` 指定资料版本、`--lang` 指定语言。`--dry-run` 预览，`--check` 只读检查，缺失或不一致返回 1；均不下载包、不启动 MCP。重复执行相同内容不变，同名服务或 Skill 冲突不覆盖。客户端仍需加载配置，Codex 项目配置需信任项目。
+
+## [HomePage](https://oss.xccjh.top/common-ui-plus/index.html)
+
+[官网](https://oss.xccjh.top/common-ui-plus/index.html) · [CLI 文档](https://oss.xccjh.top/common-ui-plus/ai/cli) · [项目仓库](http://gitlab.94ai.pro/ui/common-ui-plus)
+
+组件浏览器运行时不依赖本工具。
+
+<!-- common-ui-plus:footer:start -->
+## Contributors
+
+感谢每一位参与项目建设的贡献者！
+
+![最近三个月的贡献者气泡图](https://cdn.jsdelivr.net/npm/@94ai-plus/cli@1.0.0-alpha.6/dist/readme/contributors.svg)
+
+![最近三个月的贡献者头像墙（使用姓名首字母）](https://cdn.jsdelivr.net/npm/@94ai-plus/cli@1.0.0-alpha.6/dist/readme/contributors-wall.svg)
+
+以上为随本版本发布的贡献者统计快照，统计日期与分支见图中说明；仅统计 Git 非合并提交，头像使用姓名首字母，不是 GitLab 个人照片。
+
+## License
+
+本项目采用 [MIT License](https://cdn.jsdelivr.net/npm/@94ai-plus/cli@1.0.0-alpha.6/LICENSE) 开源许可。
+
+Copyright (c) 2026-present Jiahe Zou, 94 Intelligent Technology Co., Ltd.
+<!-- common-ui-plus:footer:end -->