sino-bc-cli 1.0.0

package/dist/SKILL.md

@@ -0,0 +1,466 @@
+---
+name: sino-bc-cli
+description: >
+  BeyondClick CLI 项目说明、命令用法、扩展新命令与 npm 发布/回滚步骤。
+  Use when 开发或使用 sino-bc-cli、执行 /homepage /nexus-swagger /bc-mcp、扩展命令、
+  npm publish、release:patch/minor/major、切 registry、排查 ENEEDAUTH/E403/EPUBLISHCONFLICT，
+  或发布到私有 Nexus / 企业私服。
+---
+
+# sino-bc-cli
+
+BeyondClick 命令行工具集合 — 提供快捷访问 BeyondClick 平台的命令行接口。
+
+适用：`sino-bc-cli`（Node.js v24 + TypeScript v5 CLI）
+
+## 目录
+
+- [技术栈](#技术栈)
+- [项目结构](#项目结构)
+- [环境与安装](#环境与安装)
+- [命令说明](#命令说明)
+- [扩展新命令](#扩展新命令)
+- [npm 发布](#npm-发布)
+  - [发布前检查清单](#一发布前检查清单必须全部通过)
+  - [前置条件](#二前置条件准备)
+  - [发布流程](#三发布流程按顺序执行)
+  - [后续版本迭代](#四后续版本迭代一行命令)
+  - [私有 Nexus / 企业私服](#五发布到私有-nexus--企业私服可选)
+  - [常见报错](#六常见报错速查表)
+  - [回滚 / 撤销](#七回滚--撤销发布)
+
+---
+
+## 技术栈
+
+| 技术/依赖      | 版本要求     | 用途说明                                                |
+| :------------- | :----------- | :------------------------------------------------------ |
+| **Node.js**    | `>= v24.0.0` | CLI 运行时环境，要求使用 v24 及以上版本                 |
+| **TypeScript** | `^v5.5.0`    | 开发语言，提供静态类型检查和更好的可维护性              |
+| **lodash**     | `^4.17.21`   | 工具函数库，提供对象/数组/字符串处理等高效方法          |
+| **dayjs**      | `^1.11.11`   | 轻量级日期处理库，替代 Moment.js 处理日期时间格式化     |
+| **axios**      | `^1.7.0`     | HTTP 客户端库，用于网络请求、连通性检测等               |
+| **crypto-js**  | `^4.2.0`     | 加密算法库，提供 MD5、SHA-256、AES、Base64 等加解密能力 |
+| **commander**  | `^12.1.0`    | 命令行参数解析框架（预留，当前采用自研注册器模式）      |
+| **chalk**      | `^4.1.2`     | 终端彩色输出库，用于美化日志和帮助信息                  |
+| **open**       | `^8.4.2`     | 跨平台文件/URL 打开工具（兼容备用方案）                 |
+
+### 开发依赖
+
+| 依赖               | 版本      | 用途                              |
+| :----------------- | :-------- | :-------------------------------- |
+| `@types/node`      | `^22.0.0` | Node.js 类型声明                  |
+| `@types/lodash`    | `^4.17.5` | lodash 类型声明                   |
+| `@types/crypto-js` | `^4.2.2`  | crypto-js 类型声明                |
+| `ts-node`          | `^10.9.2` | 开发阶段直接运行 TypeScript 代码  |
+| `rimraf`           | `^5.0.7`  | 跨平台目录清理工具，替代 `rm -rf` |
+
+---
+
+## 项目结构
+
+项目采用 **模块化、低耦合、高内聚** 的分层设计。
+
+```
+sino-bc-cli/
+├── src/
+│   ├── index.ts                  # CLI 入口，bin 关联点
+│   ├── core/                     # 核心模块（参数解析、帮助、命令分发、注册器）
+│   ├── commands/                 # 命令实现（每命令一个文件）
+│   ├── utils/                    # 可复用工具（logger / browser / crypto / http / common）
+│   ├── types/                    # 全局接口、枚举（ICommand、LogLevel）
+│   └── constants/                # CLI 配置、URL、命令名称、默认值
+├── dist/                         # 编译产物（js + d.ts + SourceMap）
+├── package.json
+├── tsconfig.json
+└── .gitignore
+```
+
+### 架构原则
+
+1. **分层清晰**：`core → commands → utils → types/constants`，上层依赖下层，单向依赖无循环
+2. **低耦合**：命令互相独立，通过注册器统一管理；新增命令只需在 `commands/` 下新建文件并加入 `commands/index.ts` 数组
+3. **高内聚**：每个工具类只负责单一职责
+4. **可扩展**：实现 `ICommand` → 放入 `commands/index.ts` 即可自动注册；注册器支持运行时动态注册/注销
+
+---
+
+## 环境与安装
+
+### 环境要求
+
+确保已安装 **Node.js v24** 或更高版本（`npm` 建议 v10+）：
+
+```bash
+node -v   # 要求 v24.x.x 或更高
+npm -v
+```
+
+版本不符时，用 [nvm](https://github.com/nvm-sh/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 管理。
+
+### 安装与编译
+
+```bash
+npm install
+npm run build      # 生成 dist/
+npm run rebuild    # 清理后重新编译
+```
+
+`dist/` 包含：`*.js`、`*.d.ts`、`*.js.map`。
+
+### 开发模式（免编译）
+
+```bash
+npm run dev -- --help
+npm run dev -- /homepage
+```
+
+### 全局安装（推荐）
+
+```bash
+# 方式一：源码目录全局链接（须先 build；Windows 下 npm link 需要管理员权限）
+npm run build
+npm link
+
+# 方式二：从 npm 安装
+npm i sino-bc-cli -g
+```
+
+```bash
+sino-bc-cli --help
+sino-bc-cli /homepage
+```
+
+卸载：`npm unlink` 或 `npm uninstall -g sino-bc-cli`
+
+### NPM 脚本
+
+```bash
+npm run build              # 编译到 dist/
+npm run dev -- [参数]      # ts-node 直接跑源码
+npm start -- [参数]        # 运行已编译 CLI（需先 build）
+npm run clean              # 删除 dist/
+npm run rebuild            # clean + tsc
+```
+
+---
+
+## 命令说明
+
+### 可用命令
+
+| 命令             | 说明                                                                                                               |
+| :--------------- | :----------------------------------------------------------------------------------------------------------------- |
+| `/homepage`      | 使用默认浏览器打开 BeyondClick 业务平台主页 (`https://business.beyondclick.com/`)                                  |
+| `/nexus-swagger` | 使用默认浏览器打开 BeyondClick Nexus Swagger 文档页 (`https://o-test-sino-bc-nexus.meetsocial.com/doc.html#/home`) |
+| `/bc-mcp`        | 交互选择并调用 iCenter MCP 接口；`ENV` 默认 `prod`，`API_KEY` 默认使用网关常量                                      |
+
+### 全局选项
+
+| 选项        | 短选项 | 说明                                      |
+| :---------- | :----- | :---------------------------------------- |
+| `--version` | `-v`   | 显示版本信息                              |
+| `--help`    | `-h`   | 显示帮助信息                              |
+| `--debug`   | `-d`   | 启用 Debug 日志模式，输出更详细的运行信息 |
+
+### 使用示例
+
+```bash
+sino-bc-cli --version
+sino-bc-cli --help
+sino-bc-cli /homepage
+sino-bc-cli /nexus-swagger
+sino-bc-cli /bc-mcp
+sino-bc-cli /bc-mcp test
+sino-bc-cli --debug /homepage
+sino-bc-cli -d /nexus-swagger
+```
+
+- `/homepage`：打开 `https://business.beyondclick.com/`
+- `/nexus-swagger`：打开 Nexus Swagger 文档页
+- Debug 会输出参数解析、命令注册、URL 打开过程
+
+### 跨平台兼容性
+
+| 操作系统                     | 测试状态 | 打开浏览器方式                                                     |
+| :--------------------------- | :------- | :----------------------------------------------------------------- |
+| **Windows** (10/11)          | ✅ 支持  | 使用 `cmd /c start "" "url"`，已处理 URL 中 `&`/`^` 等特殊字符转义 |
+| **macOS**                    | ✅ 支持  | 使用系统 `open` 命令                                               |
+| **Linux** (Ubuntu/CentOS 等) | ✅ 支持  | 使用 `xdg-open` 命令                                               |
+
+所有平台均通过 Node.js 内置 `child_process.exec` 调用，**不依赖任何 native 模块**。
+
+---
+
+## 扩展新命令
+
+1. 在 `src/commands/` 下创建 `xxx.command.ts`
+2. 实现 `ICommand`：`name`、`description`、`execute()`
+3. 在 `src/commands/index.ts` 的 `commands` 数组中添加实例
+
+```typescript
+// src/commands/example.command.ts
+import { ICommand } from "../types";
+import { logger, BrowserUtils } from "../utils";
+
+export class ExampleCommand implements ICommand {
+  public readonly name = "example";
+  public readonly description = "示例命令 - 打开示例网站";
+
+  public async execute(args: string[]): Promise<void> {
+    logger.info("执行示例命令，参数：", args);
+    await BrowserUtils.openUrl("https://example.com/");
+  }
+}
+```
+
+```typescript
+// src/commands/index.ts
+import { ExampleCommand } from "./example.command";
+
+export const commands: ICommand[] = [
+  new HomepageCommand(),
+  new NexusSwaggerCommand(),
+  new ExampleCommand(),
+];
+```
+
+完成后 `npm run build`，即可使用 `sino-bc-cli /example`。
+
+---
+
+## npm 发布
+
+### 一、发布前检查清单（必须全部通过）
+
+首次发版请逐一核对（已在 `package.json` 和构建配置中落实）：
+
+| # | 检查项 | 如何验证 | 期望结果 |
+| :--- | :--- | :--- | :--- |
+| 1 | 包名 `sino-bc-cli` 未被占用 | `npm view sino-bc-cli version` | 返回 `E404`（首次发布前）或已有版本号 |
+| 2 | `dist/index.js` 首行带 shebang | 打开 `dist/index.js` 看首行 | `#!/usr/bin/env node`（CLI 全局安装必须要有） |
+| 3 | `package.json` 含 `files` 白名单 | 查看 `package.json` 的 `files` 数组 | 只包含 `dist/`、`README.md` 等，**不要包含 `src/`、`node_modules/`、`tsconfig.json`** |
+| 4 | `package.json` 含 `bin` 映射 | `package.json` 的 `bin` 字段 | `"sino-bc-cli": "./dist/index.js"` |
+| 5 | `prepublishOnly` 钩子存在 | `package.json` scripts | `"prepublishOnly": "npm run rebuild"`（防止发布旧 dist） |
+| 6 | `publishConfig.access` = public | `package.json` | `"access": "public"` |
+| 7 | TypeScript 编译无错误 | `npm run rebuild` | 退出码 `0`，无 TS error |
+| 8 | CLI 冒烟测试通过 | `node dist/index.js --version` / `--help` | 正常输出版本号 / 帮助信息 |
+| 9 | npm 登录态 | `npm whoami` | 返回 npm 用户名（ENEEDAUTH=未登录） |
+| 10 | 本地无未提交脏改动（建议） | `git status` | `nothing to commit, working tree clean` |
+
+### 二、前置条件准备
+
+1. **npm 官方账号**：<https://www.npmjs.com/signup>，准备用户名 / 密码 / 邮箱
+2. **邮箱必须已验证**：未验证发布会报 `403 Forbidden`。官网头像 → Profile，看不到 "Verify your email" 即为通过
+3. **2FA（强烈建议）**：官网 Access Tokens / 2FA → Authentication Code，用 Authenticator 绑定。发布时输入 6 位 OTP
+4. **Node.js**：`node -v` 建议 v24+；`npm -v` 建议 v10+
+
+### 三、发布流程（按顺序执行）
+
+#### Step 0：切到项目目录并拉取最新代码
+
+```powershell
+cd d:\Project\demo\sino-bc-cli
+
+git checkout main
+git pull origin main
+```
+
+#### Step 1：确认 registry 指向 npm 官方（最容易踩坑）
+
+很多开发者默认把 registry 设为淘宝镜像或公司 Nexus。发布时不切回官方，要么失败，要么发到私服而不自知。
+
+```powershell
+npm config get registry
+```
+
+| 输出 | 状态 | 下一步 |
+| :--- | :--- | :--- |
+| `https://registry.npmjs.org/` | ✅ 正确 | 跳到 Step 2 |
+| `https://registry.npmmirror.com/` | ⚠️ 淘宝镜像 | 执行下方切换 |
+| `http://nexus.xxx.com/...` | ⚠️ 公司私服 | 执行下方切换（发完再切回） |
+| 其他 | ⚠️ 自定义源 | 执行下方切换 |
+
+```powershell
+npm config set registry "https://registry.npmjs.org/"
+npm config get registry
+# 输出: https://registry.npmjs.org/
+```
+
+既要发官方 npm 又要保留镜像加速：平时保持淘宝镜像，发布时用 `npm publish --registry=https://registry.npmjs.org/` **单次指定**，不改全局配置。
+
+#### Step 2：登录 npm 账号
+
+Windows 下必须加 `--auth-type=legacy`。不加时新版 npm (v9+) 会走浏览器扫码/回环回调，在 PowerShell/企业终端下经常卡死。
+
+```powershell
+npm login --auth-type=legacy --registry=https://registry.npmjs.org/
+```
+
+按提示手动输入（脚本无法自动化）：
+
+```
+Username: 你的 npm 用户名（区分大小写）
+Password: 你的 npm 密码          （输入时不显示任何字符，正常）
+Email: (this IS public) 你注册的邮箱
+Enter one-time password: 123456  （只有开了 2FA 才会出现，没开跳过）
+```
+
+```powershell
+npm whoami
+```
+
+仍报 `ENEEDAUTH` → registry 对不上，重做 Step 1 + Step 2。
+
+#### Step 3：确认 / 升级版本号
+
+**首次发布**：`package.json` 中 `1.0.0` 可直接用。
+
+**后续迭代**：同一版本号一旦发布就不能覆盖（立刻 unpublish 也不行），必须严格递增。
+
+| 升级类型 | 含义 | 示例 | 命令 |
+| :--- | :--- | :--- | :--- |
+| **patch** 补丁 | 修 bug、微调文档 | `1.0.0 → 1.0.1` | `npm version patch` |
+| **minor** 次版本 | 新增功能，向下兼容 | `1.0.0 → 1.1.0` | `npm version minor` |
+| **major** 主版本 | 破坏性变更 / 架构升级 | `1.0.0 → 2.0.0` | `npm version major` |
+
+日常发版优先用下方「一行命令」脚本。
+
+#### Step 4：Dry-Run 打包预览（强烈建议）
+
+```powershell
+npm pack --dry-run
+```
+
+正常末尾类似：`sino-bc-cli@1.0.0`、约 47 个文件、包大小约 30.7 kB。
+
+不合格则暂停：
+
+- 出现 `src/`、`tsconfig.json`、`.gitignore`、`node_modules/` → 漏配 `files` 白名单
+- 包大小 > 500KB → 很可能打包了不该打包的内容
+- `dist/` 文件数量 < 10 → 编译不完整，执行 `npm run rebuild`
+
+#### Step 5：执行发布
+
+```powershell
+npm publish --access public
+```
+
+开了 2FA 会再要 6 位 OTP。正常 10~30 秒：
+
+1. 触发 `prepublishOnly` → `npm run rebuild`
+2. checksum → 上传 tgz
+3. 成功时出现 `+ sino-bc-cli@x.y.z`
+
+#### Step 6：发布后验证（3 步不可省）
+
+**① 官网版本**
+
+```powershell
+npm view sino-bc-cli version
+```
+
+仍 E404：等 1 分钟；确认 registry 是官方源；或打开 <https://www.npmjs.com/package/sino-bc-cli>
+
+**② npx 远程试用**
+
+```powershell
+npx sino-bc-cli@latest --version
+npx sino-bc-cli@latest --help
+# npx sino-bc-cli@latest /homepage
+```
+
+**③ 浏览器打开包页**，确认 README 渲染、Version / License / Keywords、Dependencies（lodash、dayjs、axios、crypto-js、chalk、commander、open）
+
+发布完成后把 registry 切回平时镜像：
+
+```powershell
+npm config set registry https://registry.npmmirror.com
+```
+
+### 四、后续版本迭代（一行命令）
+
+`package.json` 已内置「升级版本号 + 自动编译 + 发布」脚本：
+
+```powershell
+npm run release:patch    # 1.0.0 → 1.0.1
+npm run release:minor    # 1.0.0 → 1.1.0
+npm run release:major    # 1.0.0 → 2.0.0
+```
+
+等价于：`npm version <type>`（升版本 + Git Tag）→ `prepublishOnly` / `rebuild` → `npm publish --access public`
+
+发布完执行 `git push origin main --tags`。
+
+### 五、发布到私有 Nexus / 企业私服（可选）
+
+#### 5.1 发布侧
+
+确认私服是 **npm-hosted**（不要用 raw-release / maven 仓库）：
+
+```powershell
+npm login --auth-type=legacy --registry=https://nexus.your-company.com/repository/npm-hosted/
+npm publish --access restricted --registry=https://nexus.your-company.com/repository/npm-hosted/
+```
+
+`--registry` 只对这一次生效，避免污染全局。
+
+#### 5.2 安装侧
+
+**不要只设 `--registry=私服地址`**，否则公共依赖也会去私服解析，未代理时 `lodash/dayjs/axios` 会 404。
+
+**推荐（Nexus 侧）**：运维建 **npm-group**，把 `npm-hosted` + `npm-proxy(代理 https://registry.npmjs.org/)` 加入 group。客户端 registry 只指向 npm-group；发布用 npm-hosted，安装用 npm-group。
+
+**应急（未做 group）**：平时 registry 保持官方 / 淘宝镜像；私有包用 `@company/sino-bc-cli` scope，客户端 `.npmrc`：
+
+```ini
+@company:registry=https://nexus.your-company.com/repository/npm-hosted/
+```
+
+这样 scoped 包走私服，公共依赖走官方。
+
+### 六、常见报错速查表
+
+| 错误码 / 关键字 | 原因 | 解决方案 |
+| :--- | :--- | :--- |
+| **`ENEEDAUTH`** | 未登录或登录态过期 | `npm login --auth-type=legacy`；确认 registry 一致 |
+| **`E403 Forbidden`** | ① 邮箱未验证 ② 无该包权限 ③ OTP 错 ④ 包名被占用 | ① 官网验证邮箱 ② owner 加 Maintainer ③ 等 30 秒重输 OTP ④ 改名或发 `@你的用户名/sino-bc-cli` |
+| **`EPUBLISHCONFLICT`** / `cannot publish over previously published version` | 版本号已发过 | `npm version patch` 再发（npm 不允许覆盖同版本） |
+| **`E404`（发布时）** | registry 指向私服且没权限 | 切到 `https://registry.npmjs.org/` |
+| **`E404`（安装时，包已发成功）** | 安装方 registry 不在官方 / 私服没同步 | `npm i sino-bc-cli -g --registry=https://registry.npmjs.org/` |
+| **`E500` / `ETIMEDOUT` / `ECONNRESET`** | 网络抖动、被墙、内网限流 | 重试 2~3 次；开代理；`npm config set proxy http://x.x.x.x:port` |
+| **登录时浏览器弹出但终端卡住** | npm v9+ web auth 被防火墙/终端拦 | `npm login --auth-type=legacy` |
+| **`You cannot publish over previously published version`** | unpublish 后同一天重发同版本 | unpublish 后 **24 小时内不能重发同版本**，升版本或等 24h |
+| **Windows 下 `cmd /c start` 打开浏览器失败** | 本地 `open` / `child_process` 权限 | CLI 已用 `child_process.exec(cmd /c start)` 兼容；仍失败则手动访问命令 URL |
+
+### 七、回滚 / 撤销发布
+
+谨慎：同一版本 unpublish 后 24h 禁发；整包 unpublish 72h 后还不能重发同名。能靠升版本号修复就不要 unpublish。
+
+```powershell
+# 撤销某一个版本
+npm unpublish sino-bc-cli@1.0.0
+
+# 撤销整个包
+npm unpublish sino-bc-cli --force
+
+# 更温和：废弃（推荐）
+npm deprecate sino-bc-cli@1.0.0 "严重 Bug，请升级到 1.0.1"
+npm deprecate sino-bc-cli@* "此包已废弃，请使用 @newscope/sino-bc-cli"
+```
+
+### 附录：关键配置位置
+
+| 配置项 | 位置 |
+| :--- | :--- |
+| 项目版本号 / 依赖 / scripts | `package.json` |
+| 发版白名单 files / publishConfig | `package.json` 的 `files` + `publishConfig` |
+| TypeScript 编译配置 | `tsconfig.json` |
+| CLI 入口（带 shebang） | `src/index.ts` → 编译后 `dist/index.js` |
+| 命令 URL 配置 | `src/constants/index.ts` 的 `PLATFORM_URLS` |
+
+---
+
+## License
+
+MIT License

package/dist/commands/bc-mcp.command.d.ts

@@ -0,0 +1,53 @@
+import { ICommand } from '../types';
+/**
+ * 调用 iCenter MCP 接口命令
+ * 命令名称: /bc-mcp
+ * 功能: 交互选择 api-doc 中的接口，使用文档默认请求体发起调用
+ */
+export declare class BcMcpCommand implements ICommand {
+    /** 命令名称 */
+    readonly name: string;
+    /** 命令描述 */
+    readonly description: string;
+    /** 命令使用示例 */
+    readonly usage: string;
+    /**
+     * 命令执行函数
+     * @param args 位置参数：[ENV] [API_KEY]
+     * @param options 解析后的选项，支持 --env / --api-key
+     */
+    execute(args: string[], options?: Record<string, unknown>): Promise<void>;
+    /**
+     * 解析环境参数，优先级：--env > 位置参数中的合法 ENV > 默认 prod
+     */
+    private resolveEnv;
+    /**
+     * 解析 API Key，优先级：--api-key > 非 ENV 的位置参数 > 默认值
+     */
+    private resolveApiKey;
+    /**
+     * 从 options 中按候选 key 取第一个有效值
+     */
+    private pickOption;
+    /**
+     * 打印接口清单并让用户选择
+     */
+    private selectApi;
+    /**
+     * 打印即将发起的请求概要
+     */
+    private printRequestPreview;
+    /**
+     * 按接口方法发起请求并打印响应
+     */
+    private callApi;
+    /**
+     * 将响应格式化为可读 JSON 文本
+     * version 接口可能返回 text/plain，需兜底解析
+     */
+    private formatResponse;
+    /**
+     * 统一处理 HTTP 失败：优先打印服务端响应体
+     */
+    private handleRequestError;
+}