sino-bc-cli 1.8.2 → 1.8.4

package/README.md

@@ -1,624 +1,588 @@
-# sino-bc-cli
-
-BeyondClick 命令行工具集合 - 提供快捷访问 BeyondClick 平台的命令行接口。
-
-## Install
-
-> ⚠️ 本包是**全局 CLI 工具**。npm 官网右侧 Install 框里的 `npm i sino-bc-cli` 是网站写死的固定文案，不是本包的推荐用法，请以下面的命令为准（注意 `-g`）。
->
-> 运行环境要求 Node.js >= 24.0.0。
-
-### ① 安装最新版本（推荐）
-
-```bash
-# npm
-npm i sino-bc-cli@latest -g
-
-# pnpm
-pnpm add -g sino-bc-cli@latest
-
-# yarn
-yarn global add sino-bc-cli@latest
-```
-
-已经装过旧版本时，执行同样的命令即可升级覆盖。想先确认远端最新版本号：
-
-```bash
-npm view sino-bc-cli version        # 查看 latest 版本号
-npm outdated -g sino-bc-cli         # 对比本地全局版本是否过期
-```
-
-### ② 安装指定版本
-
-把 `@latest` 换成目标版本号即可，适用于需要回退或锁定版本的场景：
-
-```bash
-# npm
-npm i sino-bc-cli@1.0.5 -g
-
-# pnpm
-pnpm add -g sino-bc-cli@1.0.5
-
-# yarn
-yarn global add sino-bc-cli@1.0.5
-```
-
-查看全部可安装版本：
-
-```bash
-npm view sino-bc-cli versions --json
-```
-
-### ③ 卸载
-
-```bash
-# npm
-npm uninstall -g sino-bc-cli
-
-# pnpm
-pnpm remove -g sino-bc-cli
-
-# yarn
-yarn global remove sino-bc-cli
-```
-
-> 如果当初是在源码目录用 `npm link` 做的开发链接，请改用 `npm unlink -g sino-bc-cli` 解除。
-
-### ④ 验证安装
-
-```bash
-sino-bc-cli --version    # 输出版本号，说明命令已可用
-sino-bc-cli --help       # 输出帮助信息和全部可用命令
-npm ls -g --depth=0 sino-bc-cli   # 确认全局安装的版本
-```
-
-若提示「command not found / 无法将 sino-bc-cli 项识别为命令」，说明 npm 全局 bin 目录不在 `PATH` 中。用 `npm prefix -g` 查看全局安装根目录（Windows 下该目录即 bin 目录，macOS / Linux 下为其 `bin` 子目录），把它加入环境变量后重开终端。
-
-### ⑤ 初始化（必须执行一次）
-
-**装完之后必须完成 `/init` 初始化，CLI 的 Agent 技能才会生效。**
-
-全局安装时 `postinstall` 会自动执行一次 `/init`。但在以下情况会被跳过，需要手动补执行：使用 `--ignore-scripts` 安装、安装目录权限不足、或通过 `npx` 临时运行。
-
-```bash
-sino-bc-cli /init
-```
-
-`/init` 会把 `skills/sino-bc-shared` 与 `skills/sino-bc-biz-line`（含 `references/`）写入用户主目录的 Agent 技能目录（`~/.agents/skills/sino-bc-shared` 等），并删除旧的 `sino-bc-cli/` 技能目录。根 `SKILL.md` 只做入口，不作为唯一安装源。Cursor / Claude / Codex / 飞书豆包工作 才能识别到本技能。飞书豆包工作侧还需：技能·连接器 → 管理 → **本地** → 刷新。查看包内技能：`sino-bc-cli /skill`。
-
-> 每次升级版本后请重新执行一次 `sino-bc-cli /init`，以刷新本地技能文件。
-
-### ⑥ 免安装临时执行
-
-```bash
-npx sino-bc-cli --help
-```
-
-注意 `npx` 方式不会持久注册 Agent 技能，需要技能能力时仍请走全局安装 + `/init`。
-
----
-
-## 📚 技术栈说明
-
-| 技术/依赖      | 版本要求     | 用途说明                                                |
-| :------------- | :----------- | :------------------------------------------------------ |
-| **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/                          # 源代码目录（TypeScript）
-│   ├── index.ts                  # 🚀 CLI 入口文件，bin 关联点
-│   │
-│   ├── core/                     # 🧠 核心模块层
-│   │   ├── index.ts              # 核心模块统一导出
-│   │   ├── cli-app.ts            # CLI 应用主类（参数解析、帮助展示、命令分发）
-│   │   ├── route.ts              # argv 路由（斜杠命令 / 域 + Shortcut）
-│   │   └── command-registry.ts   # 命令注册器（注册、查找、执行、注销命令）
-│   │
-│   ├── commands/                 # 📦 命令实现层（每命令一个文件，可独立扩展）
-│   │   ├── index.ts              # 命令批量注册入口
-│   │   ├── init.command.ts       # /init 命令实现（注册 Agent 技能 + 初始化变量配置 + 拉取启动 MCP）
-│   │   ├── api-list.command.ts   # /api-list 命令实现（列出接口、给出调用命令并打开文档）
-│   │   ├── bc-api.command.ts     # /bc-api 已下线，仅打印迁移提示并非 0 退出
-│   │   ├── get-config.command.ts # /get-config 命令实现（查看变量配置与 MCP 配置）
-│   │   ├── set-config.command.ts # /set-config 命令实现（修改变量配置）
-│   │   ├── mcp-reload.command.ts # /mcp-reload 命令实现（按 mcp.json 重启 MCP）
-│   │   ├── skill.command.ts      # /skill 命令实现（列出包内技能或打开 SKILL.md）
-│   │   └── uninstall.command.ts  # /uninstall 命令实现（关闭 MCP、清理技能目录与配置并卸载）
-│   │
-│   ├── shortcuts/                # ⚡ Shortcut 执行面（业务命令，域 + `+cmd`）
-│   │   ├── index.ts              # 注册表与执行器（flag 解析、输出格式、写确认门）
-│   │   ├── flags.ts              # Shortcut 面参数解析（含公共 flag）
-│   │   ├── types.ts              # Shortcut 声明与执行上下文类型
-│   │   └── biz-line/             # biz-line 域
-│   │       ├── index.ts          # 该域全部 Shortcut 登记处
-│   │       ├── read.ts           # 只读 Shortcut（+channels/+categories/+list/+strategies/+top）
-│   │       ├── write.ts          # 写 Shortcut（+save/+update/+status/+delete/+strategy-*）
-│   │       ├── raw-api.ts        # biz-line api <name> 点名调用
-│   │       └── helpers.ts        # 按名解析业务线、字典名称映射等编排
-│   │
-│   ├── utils/                    # 🛠 工具类层（高内聚的可复用工具）
-│   │   ├── index.ts              # 工具模块统一导出
-│   │   ├── logger.ts             # 日志工具（多级别彩色输出 + 时间戳）
-│   │   ├── browser.ts            # 浏览器工具（跨平台 URL 打开，兼容 Win/macOS/Linux）
-│   │   ├── crypto.ts             # 加密工具（MD5、SHA-256、AES、Base64、签名生成）
-│   │   ├── http.ts               # HTTP 工具（axios 封装：请求/响应拦截、自动重试）
-│   │   ├── gateway-client.ts     # 网关调用唯一出口（拼地址、注入鉴权与来源头、解包 result）
-│   │   ├── presenter.ts          # 输出与退出码（table / JSON 信封，stdout / stderr 分流）
-│   │   ├── cli-error.ts          # 带分类的 CLI 错误（validation / config / api / 待确认）
-│   │   ├── common.ts             # 通用工具（日期、深拷贝、防抖节流、ID 生成等）
-│   │   ├── prompt.ts             # 终端交互（复用单一 readline 会话：提问、选择、确认）
-│   │   ├── config-store.ts       # 变量配置读写（字段元信息 + 读 / 写 / 删）
-│   │   ├── config-prompt.ts      # 变量配置交互采集（/init 与 /set-config 共用）
-│   │   ├── mcp-store.ts          # ~/.sino-bc-cli/mcp.json 读写
-│   │   ├── mcp-service.ts        # MCP 同步到 Cursor / Codex / Claude / VS Code 并握手
-│   │   └── skill-install.ts      # Agent 技能目录的写入与清理
-│   │
-│   ├── types/                    # 📝 类型定义层
-│   │   └── index.ts              # 全局接口、枚举定义（ICommand、LogLevel 等）
-│   │
-│   └── constants/                # 🔧 常量配置层
-│       └── index.ts              # CLI 配置、命令名称、Shortcut 域、默认值
-│
-├── skills/                       # Agent 技能树（shared + biz-line，含 references）
-├── affordance/                   # 各 Shortcut 的 WHEN / 别用 / 示例
-├── tests/                        # ✅ 单元测试（node --test + ts-node）
-│   ├── helpers/                  # HTTP 执行器桩、输出流桩
-│   └── *.test.ts                 # 路由、flag、网关、输出契约、各类 Shortcut
-│
-├── dist/                         # 📤 构建输出目录（构建后自动生成）
-│   └── ...                       # 单文件混淆压缩产物 + SKILL.md + skills/ + affordance/ + api-doc（不含 SourceMap）
-│
-├── package.json                  # 📄 项目配置（依赖、脚本、bin 命令）
-├── tsconfig.json                 # 📄 TypeScript 编译配置
-├── .gitignore                    # 📄 Git 忽略配置
-└── README.md                     # 📖 项目说明文档
-```
-
-### 架构设计原则
-
-1. **分层清晰**：`core → commands → utils → types/constants`，上层依赖下层，单向依赖无循环
-2. **低耦合**：命令之间互相独立，通过注册器统一管理；新增命令只需在 `commands/` 下新建文件并加入 `commands/index.ts` 数组
-3. **高内聚**：每个工具类只负责单一职责（如 `BrowserUtils` 只处理浏览器打开，`CryptoUtils` 只处理加解密）
-4. **可扩展**：
-   - 新增命令：实现 `ICommand` 接口 → 放入 `commands/index.ts` 数组即可自动注册
-   - 新增工具：在 `utils/` 下新建类，通过 `utils/index.ts` 导出
-   - 命令注册器支持运行时动态注册/注销命令
-
----
-
-## 🚀 项目使用说明
-
-### 1. 环境要求
-
-确保已安装 **Node.js v24** 或更高版本：
-
-```bash
-# 查看 Node.js 版本
-node -v
-# 要求输出 v24.x.x 或更高
-
-# 查看 npm 版本
-npm -v
-```
-
-> 如果 Node.js 版本不符合要求，建议通过 [nvm (Node Version Manager)](https://github.com/nvm-sh/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 进行安装和版本管理。
-
-### 2. 安装依赖
-
-在项目根目录下执行：
-
-```bash
-npm install
-```
-
-依赖安装完成后，`node_modules/` 目录将生成。
-
-### 3. 编译项目
-
-项目使用 TypeScript 编写，需要编译为 JavaScript 后才能运行：
-
-```bash
-# 编译（生成 dist/ 目录）
-npm run build
-
-# 清理旧的编译产物并重新编译
-npm run rebuild
-```
-
-编译完成后，`dist/` 目录将包含：
-
-- `*.js` — 编译后的 JavaScript 代码
-- `*.d.ts` — TypeScript 类型声明文件
-- `*.js.map` — SourceMap 调试映射文件
-
-### 4. 开发模式（免编译运行）
-
-开发阶段可使用 `ts-node` 直接运行 TypeScript 代码，无需手动编译：
-
-```bash
-# 直接运行 TypeScript 源码
-npm run dev -- [参数]
-
-# 示例：查看帮助
-npm run dev -- --help
-
-# 示例：执行业务命令
-npm run dev -- biz-line +list --name <业务线名称>
-```
-
-### 4.1 运行测试
-
-单元测试用 Node 内置 runner（`node --test`）配 `ts-node`，不额外引入测试框架：
-
-```bash
-# 跑全部用例
-npm test
-
-# 类型检查（tsc --noEmit）
-npm run typecheck
-```
-
-用例放在 `tests/`，通过注入 HTTP 执行器桩断言请求，不产生真实网络调用。
-
-### 5. 全局安装（推荐）
-
-将 CLI 工具链接为全局命令，可在任意目录下直接使用 `sino-bc-cli`：
-
-```bash
-# 方式一：从源码目录全局链接（开发/测试场景）
-cd d:\Project\demo\sino-bc-cli
-npm run build      # 必须先编译
-npm link           # 全局链接（Windows 下需要管理员权限）
-
-# 方式二：后续发布到 npm 后
-npm i sino-bc-cli -g
-```
-
-安装完成后，即可在任意终端直接使用：
-
-```bash
-sino-bc-cli --help
-sino-bc-cli /init
-sino-bc-cli /api-list
-sino-bc-cli biz-line +list --name <业务线名称>
-```
-
-`npm i sino-bc-cli -g` 完成后会自动执行 `/init`，把 `sino-bc-shared` 与 `sino-bc-biz-line` 写到用户主目录的 Agent 技能目录（`~/.agents/skills/sino-bc-shared` 等），并清掉旧的 `sino-bc-cli/`。飞书豆包工作：技能·连接器 → 管理 → **本地** → 刷新。若未出现，手动执行：
-
-```bash
-sino-bc-cli /init
-```
-
-> 卸载全局链接：`npm unlink` 或 `npm uninstall -g sino-bc-cli`
-
----
-
-## 📖 命令说明
-
-命令分两类：**生命周期命令**用 `/` 前缀，负责安装与配置；**业务命令**是 Shortcut 执行面，形如 `<域> +<命令>`。
-
-### 生命周期命令
-
-| 命令        | 说明                                                                                          |
-| :---------- | :-------------------------------------------------------------------------------------------- |
-| `/init`       | 注册 `sino-bc-shared` / `sino-bc-biz-line` 到 Agent 技能目录（并删除旧 `sino-bc-cli/`），交互设置环境 / `API_KEY`，并拉取启动 MCP |
-| `/skill`      | 列出包内 Agent 技能；传入 name 打开对应 `SKILL.md` |
-| `/api-list`   | 列出全部可调用接口及其调用命令，Shortcut 行带一句 WHEN；Cursor / VS Code 终端中 Ctrl+单击接口名或文档路径打开本地文档，也可输入序号或传入 name |
-| `/get-config` | 查看变量配置与 `mcp.json`；密钥默认打码，`--show-secret` 显示明文，`--json` 输出 JSON |
-| `/set-config` | 修改变量配置（环境 / API_KEY）；不带参数时逐项交互修改 |
-| `/mcp-reload` | 重新读取 `~/.sino-bc-cli/mcp.json`，同步到 Cursor / Codex / Claude / VS Code 并重新握手 |
-| `/uninstall`  | 关闭本 CLI 写入的 MCP，删除技能目录与变量配置文件，并从全局 npm 卸载本 CLI |
-| `/bc-api`     | **已下线**。只打印迁移提示并非 0 退出，改用 `biz-line +<shortcut>` 或 `biz-line api <name>` |
-
-### 业务命令（`biz-line`）
-
-| 命令 | 说明 |
-| :--- | :--- |
-| `biz-line +channels` | 查询投放渠道列表（`code` 即业务线里的 `mediaChannelId`） |
-| `biz-line +categories` | 查询投放行业与品类字典树 |
-| `biz-line +list` | 查询业务线；`--name` / `--id` / `--channel` / `--industry` / `--category`，不传即查全部 |
-| `biz-line +strategies` | 查周策略与表现；`--name` 会先解析业务线 ID，也可直接 `--id` |
-| `biz-line +top` | 行业 / 品类 Top 业务线；两者至少传一个，同时传则只按行业 |
-| `biz-line +save` / `+update` / `+status` / `+delete` | ⚠️ 业务线写操作 |
-| `biz-line +strategy-save` / `+strategy-update` / `+strategy-delete` | ⚠️ 周策略写操作 |
-| `biz-line api <name> --data '<json>'` | 按接口 `name` 点名调用，覆盖导出、对比、消耗等长尾接口 |
-
-`--channel` / `--industry` / `--category` 同时接受数字 ID 与名称（如 `--channel TikTok`）；传名称时会先查字典再映射，映射不到会报错并列出可选值。
-
-### Shortcut 面公共参数
-
-| 参数 | 说明 |
-| :--- | :--- |
-| `--format json\|table` | 输出格式。TTY 默认 `table`，非 TTY 默认 `json` |
-| `--dry-run` | 只打印将要发起的 method / URL / 请求体，不发请求 |
-| `--yes` | 跳过写操作确认，直接发起请求 |
-
-### 输出契约与退出码
-
-非 TTY（管道 / CI / Agent）默认输出 JSON 信封。成功走 stdout，失败走 stderr：
-
-```json
-{ "ok": true,  "env": "prod", "command": "biz-line +list", "data": [], "meta": { "count": 0 } }
-{ "ok": false, "env": "prod", "command": "biz-line +delete", "error": { "type": "confirmation_required", "message": "...", "hint": "..." } }
-```
-
-`data` 只包含上游 `result`。**判断成功请看 `ok` 或进程退出码，不要看上游 `code`。**
-
-| 退出码 | 含义 |
-| :----- | :--- |
-| `0` | 成功 |
-| `10` | 写操作待确认，**不是错误**；向用户确认后在原命令末尾追加 `--yes` 重试 |
-| 其他非 0 | 失败，详见 `error.type`（`validation` / `config` / `api`） |
-
-### 变量配置文件
-
-环境、`API_KEY` 存放在 `<用户主目录>/.sino-bc-cli/config.json`。`X-GATEWAY-TYPE` 固定为 `A2C-CLI`，不开放配置。
-
-MCP Server 存放在 `<用户主目录>/.sino-bc-cli/mcp.json`，结构与 Cursor 的 `mcp.json` 一致。用户自行增删后执行 `/mcp-reload`，CLI 会同步到 Cursor、Codex、Claude Code、VS Code。
-
-| 字段 | 命令行键名 | 默认值 | 说明 |
-| :--- | :--------- | :----- | :--- |
-| `env` | `env` | `prod` | 目标环境，可选 `test` / `pre` / `prod` |
-| `apiKey` | `api-key` | 内置默认 Key | 网关鉴权用的 API Key（业务命令使用） |
-
-```bash
-# 查看（密钥打码）
-sino-bc-cli /get-config
-
-# 三种修改写法等价
-sino-bc-cli /set-config env test
-sino-bc-cli /set-config env=test
-sino-bc-cli /set-config --env=test
-
-# 不带参数则逐项交互修改，直接回车保留当前值
-sino-bc-cli /set-config
-
-# 改 MCP：编辑文件后重启
-# %USERPROFILE%\.sino-bc-cli\mcp.json
-sino-bc-cli /mcp-reload
-```
-
-```json
-{
-  "mcpServers": {
-    "example": {
-      "type": "streamable-http",
-      "url": "https://your-mcp-gateway/mcp/",
-      "headers": {
-        "Authorization": "Bearer <token>"
-      }
-    }
-  }
-}
-```
-
-> `/init` 结束时自动拉取并启动 `mcp.json`（文件不存在则创建空清单，已存在不覆盖）。非交互环境（npm `postinstall`、CI、Agent 调用）下不提问。MCP 失败只警告。
-
-### 全局选项
-
-| 选项        | 短选项 | 说明                                      |
-| :---------- | :----- | :---------------------------------------- |
-| `--version` | `-v`   | 显示版本信息                              |
-| `--help`    | `-h`   | 显示帮助信息                              |
-| `--debug`   | `-d`   | 启用 Debug 日志模式，输出更详细的运行信息 |
-
-### 环境与请求网关
-
-业务命令的请求地址由 [`src/constants/gateway.ts`](./src/constants/gateway.ts) 的 `GATEWAY_CONFIG` 决定，统一走 `joinGatewayUrl(env, path)` 拼接，实际请求由 [`src/utils/gateway-client.ts`](./src/utils/gateway-client.ts) 这一个出口发出。业务线路径带 `/sino-opti-hive`。iCenter 请写入 `mcp.json` 后 `/mcp-reload`。
-
-| `ENV`  | 说明     | 网关地址                             |
-| :----- | :------- | :----------------------------------- |
-| `test` | 测试环境 | `https://test-agent.beyondclick.com` |
-| `pre`  | 预发环境 | `https://test-agent.beyondclick.com` |
-| `prod` | 生产环境 | `https://test-agent.beyondclick.com` |
-
-> 当前三环境同一地址。换地址只需改 `GATEWAY_CONFIG`，同时同步 [`SKILL.md`](./SKILL.md) 与 [`src/api-doc/`](./src/api-doc/README.md) 中的示例地址。
-
-### 使用示例
-
-#### ① 查看版本和帮助
-
-```bash
-# 查看版本号
-sino-bc-cli --version
-sino-bc-cli -v
-
-# 查看帮助文档（含所有可用命令列表）
-sino-bc-cli --help
-sino-bc-cli -h
-```
-
-#### ② 列出可调用接口并打开文档
-
-```bash
-sino-bc-cli /api-list
-sino-bc-cli /api-list 3
-sino-bc-cli /api-list biz-line-open-list
-```
-
-执行效果：按「业务线查询 / 业务线策略」分组列出全部接口。接口名是终端超链接，文档路径可 Ctrl+单击打开对应 markdown；交互终端也可输入序号。传入序号或接口 `name` 则直接打开该文档。
-
-#### ③ 配置并重启 MCP
-
-```bash
-# 编辑 %USERPROFILE%\.sino-bc-cli\mcp.json 后
-sino-bc-cli /mcp-reload
-```
-
-执行效果：把 `mcp.json` 里的 Server 同步到 Cursor（`~/.cursor/mcp.json`）、Codex（`~/.codex/config.toml`）、Claude Code（`~/.claude.json`）、VS Code 用户级 `mcp.json`，并对带 `url` 的 Server 做 initialize 握手。
-
-#### ④ 查询业务线数据
-
-```bash
-# 按名称查业务线
-sino-bc-cli biz-line +list --name <业务线名称>
-
-# 按渠道筛选（接受名称或 ID）
-sino-bc-cli biz-line +list --channel TikTok
-
-# 查某条业务线的周策略与表现
-sino-bc-cli biz-line +strategies --name <业务线名称>
-
-# 行业 Top
-sino-bc-cli biz-line +top --industry APP --top-n 5
-
-# 没有 Shortcut 的长尾接口
-sino-bc-cli biz-line api biz-line-strategy-compare \
-  --data '{"bizLineId":123,"currentId":2,"prevId":1}'
-```
-
-执行效果：向配置文件指定环境的网关发起请求，路径统一带 `/sino-opti-hive` 前缀，自动注入 `Authorization` 与 `X-GATEWAY-TYPE: A2C-CLI`。接口清单见 [`src/api-doc/README.md`](./src/api-doc/README.md)。
-
-#### ⑤ 执行写操作（需确认）
-
-```bash
-# 先预览请求，不会真正发起
-sino-bc-cli biz-line +status --id 123 --status 3 --dry-run
-
-# 确认无误后追加 --yes
-sino-bc-cli biz-line +status --id 123 --status 3 --yes
-```
-
-> ⚠️ 写操作会变更线上数据。不加 `--yes` 时：交互式终端会展示环境与关键参数并询问；非交互式环境以退出码 `10` 返回 `confirmation_required`，需人工确认后再重试。
-
-#### ⑥ 启用 Debug 模式运行
-
-```bash
-sino-bc-cli --debug /api-list
-# 或使用短选项
-sino-bc-cli -d /api-list
-```
-
-Debug 模式会输出详细的日志，包括参数解析、命令注册、接口调用过程等信息，便于排查问题。
-
----
-
-## 🌐 跨平台兼容性
-
-本工具已针对以下操作系统进行兼容性处理：
-
-| 操作系统                     | 测试状态 | 打开浏览器方式                                                     |
-| :--------------------------- | :------- | :----------------------------------------------------------------- |
-| **Windows** (10/11)          | ✅ 支持  | 使用 `cmd /c start "" "url"`，已处理 URL 中 `&`/`^` 等特殊字符转义 |
-| **macOS**                    | ✅ 支持  | 使用系统 `open` 命令                                               |
-| **Linux** (Ubuntu/CentOS 等) | ✅ 支持  | 使用 `xdg-open` 命令                                               |
-
-> 所有平台均通过 Node.js 内置 `child_process.exec` 调用，**不依赖任何 native 模块**，确保跨平台一致性。
-
----
-
-## 📦 NPM 脚本说明
-
-在 `package.json` 中预定义了以下脚本：
-
-```bash
-# 编译 TypeScript 为 JavaScript（输出到 dist/）
-npm run build
-
-# 类型检查（不产出文件）
-npm run typecheck
-
-# 跑单元测试
-npm test
-
-# 开发模式：直接运行 TypeScript 源码（ts-node）
-npm run dev -- [参数]
-
-# 运行已编译的 CLI（需要先 build）
-npm start -- [参数]
-
-# 清理编译产物（删除 dist/ 目录）
-npm run clean
-
-# 清理后重新编译
-npm run rebuild
-```
-
----
-
-## 🔧 扩展新命令（开发者指南）
-
-先判断要加的是哪一类：
-
-- **生命周期命令**（安装、配置、维护，用 `/` 前缀）→ 加到 `src/commands/`
-- **业务命令**（调接口拿数据，形如 `biz-line +xxx`）→ 加到 `src/shortcuts/`
-
-### A. 新增业务 Shortcut
-
-1. **写声明**：在 `src/shortcuts/biz-line/read.ts` 或 `write.ts` 里新增一条 `IShortcutDefinition`，声明 `command`、`risk`、`flags`，并在 `resolve()` 里返回目标接口与请求体
-2. **登记**：加入 `src/shortcuts/biz-line/index.ts` 的 `BIZ_LINE_SHORTCUTS` 数组
-3. **补测试**：在 `tests/` 下用 HTTP 桩断言请求与输出
-4. **同步文档**：`skills/sino-bc-biz-line` 的意图表、`affordance/biz-line.md` 的 WHEN、`src/api-doc/` 的字段口径；根 `SKILL.md` 只做入口
-
-参数解析、输出格式、写操作确认门、错误归类都由 `src/shortcuts/index.ts` 统一承担，声明里不要自己发 HTTP。接口 `name` 一律取自 `src/constants/biz-line-api-doc.ts`，不要新造。
-
-> 只是想调一个已有接口，通常不需要写新 Shortcut——直接 `biz-line api <name> --data '<json>'` 即可。Shortcut 应当带来智能默认值、参数编排或更友好的输出，否则不值得新增。
-
-### B. 新增生命周期命令
-
-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 InitCommand(),
-  new ApiListCommand(),
-  new GetConfigCommand(),
-  new ExampleCommand(), // 新增注册
-];
-```
-
-完成后执行 `npm run build` 即可使用 `sino-bc-cli /example`。
-
----
-
-## 📄 License
-
-MIT License
+# sino-bc-cli
+
+BeyondClick 命令行工具集合 - 提供快捷访问 BeyondClick 平台的命令行接口。
+
+## Install
+
+> ⚠️ 本包是**全局 CLI 工具**。npm 官网右侧 Install 框里的 `npm i sino-bc-cli` 是网站写死的固定文案，不是本包的推荐用法，请以下面的命令为准（注意 `-g`）。
+>
+> 运行环境要求 Node.js >= 24.0.0。
+
+### ① 安装最新版本（推荐）
+
+```bash
+# npm
+npm i sino-bc-cli@latest -g
+
+# pnpm
+pnpm add -g sino-bc-cli@latest
+
+# yarn
+yarn global add sino-bc-cli@latest
+```
+
+已经装过旧版本时，执行同样的命令即可升级覆盖。想先确认远端最新版本号：
+
+```bash
+npm view sino-bc-cli version        # 查看 latest 版本号
+npm outdated -g sino-bc-cli         # 对比本地全局版本是否过期
+```
+
+### ② 安装指定版本
+
+把 `@latest` 换成目标版本号即可，适用于需要回退或锁定版本的场景：
+
+```bash
+# npm
+npm i sino-bc-cli@1.0.5 -g
+
+# pnpm
+pnpm add -g sino-bc-cli@1.0.5
+
+# yarn
+yarn global add sino-bc-cli@1.0.5
+```
+
+查看全部可安装版本：
+
+```bash
+npm view sino-bc-cli versions --json
+```
+
+### ③ 卸载
+
+```bash
+# npm
+npm uninstall -g sino-bc-cli
+
+# pnpm
+pnpm remove -g sino-bc-cli
+
+# yarn
+yarn global remove sino-bc-cli
+```
+
+> 如果当初是在源码目录用 `npm link` 做的开发链接，请改用 `npm unlink -g sino-bc-cli` 解除。
+
+### ④ 验证安装
+
+```bash
+sino-bc-cli --version    # 输出版本号，说明命令已可用
+sino-bc-cli --help       # 输出帮助信息和全部可用命令
+npm ls -g --depth=0 sino-bc-cli   # 确认全局安装的版本
+```
+
+若提示「command not found / 无法将 sino-bc-cli 项识别为命令」，说明 npm 全局 bin 目录不在 `PATH` 中。用 `npm prefix -g` 查看全局安装根目录（Windows 下该目录即 bin 目录，macOS / Linux 下为其 `bin` 子目录），把它加入环境变量后重开终端。
+
+### ⑤ 初始化（必须执行一次）
+
+**装完之后必须完成 `/init` 初始化，CLI 的 Agent 技能才会生效。**
+
+全局安装时 `postinstall` 会自动执行一次 `/init`。但在以下情况会被跳过，需要手动补执行：使用 `--ignore-scripts` 安装、安装目录权限不足、或通过 `npx` 临时运行。
+
+```bash
+sino-bc-cli /init
+```
+
+`/init` 会把根 `SKILL.md` 与 `skills/system/`、`skills/custom/` 下的标准子技能（`SKILL.md` + `references/`，同路径以 `custom` 为准）嵌进 `~/.agents/skills/sino-bc-cli/`，不出现 `system/` 或 `custom/` 这一层；同时删除旧的平级 `sino-bc-shared` / `sino-bc-<domain>` 技能目录。豆包本地列表里只应看到 **`sino-bc-cli`**。飞书豆包工作侧还需：技能·连接器 → 管理 → **本地** → 刷新。查看包内技能：`sino-bc-cli /skill`。
+
+> 每次升级版本后请重新执行一次 `sino-bc-cli /init`，以刷新本地技能文件。
+
+### ⑥ 免安装临时执行
+
+```bash
+npx sino-bc-cli --help
+```
+
+注意 `npx` 方式不会持久注册 Agent 技能，需要技能能力时仍请走全局安装 + `/init`。
+
+---
+
+## 📚 技术栈说明
+
+| 技术/依赖      | 版本要求     | 用途说明                                                |
+| :------------- | :----------- | :------------------------------------------------------ |
+| **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/                          # 源代码目录（TypeScript）
+│   ├── index.ts                  # 🚀 CLI 入口文件，bin 关联点
+│   │
+│   ├── core/                     # 🧠 核心模块层
+│   │   ├── index.ts              # 核心模块统一导出
+│   │   ├── cli-app.ts            # CLI 应用主类（参数解析、帮助展示、命令分发）
+│   │   ├── route.ts              # argv 路由（斜杠命令 / 域 + Shortcut）
+│   │   └── command-registry.ts   # 命令注册器（注册、查找、执行、注销命令）
+│   │
+│   ├── commands/                 # 📦 命令实现层（每命令一个文件，可独立扩展）
+│   │   ├── index.ts              # 命令批量注册入口
+│   │   ├── init.command.ts       # /init 命令实现（注册 Agent 技能 + 初始化变量配置）
+│   │   ├── bc-api.command.ts     # /bc-api 已下线，仅打印迁移提示并非 0 退出
+│   │   ├── get-config.command.ts # /get-config 命令实现（查看变量配置）
+│   │   ├── set-config.command.ts # /set-config 命令实现（修改变量配置）
+│   │   ├── skill.command.ts      # /skill 命令实现（列出包内技能或打开 SKILL.md）
+│   │   └── uninstall.command.ts  # /uninstall 命令实现（清理技能目录与配置并卸载）
+│   │
+│   ├── shortcuts/                # ⚡ Shortcut 执行面（业务命令，域 + `+cmd`）
+│   │   ├── index.ts              # 注册表与执行器（flag 解析、输出格式、写确认门）
+│   │   ├── flags.ts              # Shortcut 面参数解析（含公共 flag）
+│   │   ├── types.ts              # Shortcut 声明与执行上下文类型
+│   │   └── biz-line/             # biz-line 域
+│   │       ├── index.ts          # 该域全部 Shortcut 登记处
+│   │       ├── read.ts           # 只读 Shortcut（+channels/+categories/+list/+strategies）
+│   │       ├── write.ts          # 写 Shortcut（+save/+update/+status/+delete/+strategy-*）
+│   │       ├── raw-api.ts        # biz-line api <name> 点名调用
+│   │       └── helpers.ts        # 按名解析业务线、字典名称映射等编排
+│   │
+│   ├── utils/                    # 🛠 工具类层（高内聚的可复用工具）
+│   │   ├── index.ts              # 工具模块统一导出
+│   │   ├── logger.ts             # 日志工具（多级别彩色输出 + 时间戳）
+│   │   ├── browser.ts            # 浏览器工具（跨平台 URL 打开，兼容 Win/macOS/Linux）
+│   │   ├── crypto.ts             # 加密工具（MD5、SHA-256、AES、Base64、签名生成）
+│   │   ├── http.ts               # HTTP 工具（axios 封装：请求/响应拦截、自动重试）
+│   │   ├── gateway-client.ts     # 网关调用唯一出口（拼地址、注入鉴权与来源头、解包 result）
+│   │   ├── presenter.ts          # 输出与退出码（table / JSON 信封，stdout / stderr 分流）
+│   │   ├── cli-error.ts          # 带分类的 CLI 错误（validation / config / api / 待确认）
+│   │   ├── common.ts             # 通用工具（日期、深拷贝、防抖节流、ID 生成等）
+│   │   ├── prompt.ts             # 终端交互（复用单一 readline 会话：提问、选择、确认）
+│   │   ├── config-store.ts       # 变量配置读写（字段元信息 + 读 / 写 / 删）
+│   │   ├── config-prompt.ts      # 变量配置交互采集（/init 与 /set-config 共用）
+│   │   └── skill-install.ts      # Agent 技能目录的写入与清理
+│   │
+│   ├── types/                    # 📝 类型定义层
+│   │   └── index.ts              # 全局接口、枚举定义（ICommand、LogLevel 等）
+│   │
+│   └── constants/                # 🔧 常量配置层
+│       └── index.ts              # CLI 配置、命令名称、Shortcut 域、默认值
+│
+├── skills/                       # Agent 技能树（shared + biz-line，含 references）
+├── affordance/                   # 各 Shortcut 的 WHEN / 别用 / 示例
+├── tests/                        # ✅ 单元测试（node --test + ts-node）
+│   ├── helpers/                  # HTTP 执行器桩、输出流桩
+│   └── *.test.ts                 # 路由、flag、网关、输出契约、各类 Shortcut
+│
+├── dist/                         # 📤 构建输出目录（构建后自动生成）
+│   └── ...                       # 单文件混淆压缩产物 + SKILL.md + skills/ + affordance/ + api-doc（不含 SourceMap）
+│
+├── package.json                  # 📄 项目配置（依赖、脚本、bin 命令）
+├── tsconfig.json                 # 📄 TypeScript 编译配置
+├── .gitignore                    # 📄 Git 忽略配置
+└── README.md                     # 📖 项目说明文档
+```
+
+### 架构设计原则
+
+1. **分层清晰**：`core → commands → utils → types/constants`，上层依赖下层，单向依赖无循环
+2. **低耦合**：命令之间互相独立，通过注册器统一管理；新增命令只需在 `commands/` 下新建文件并加入 `commands/index.ts` 数组
+3. **高内聚**：每个工具类只负责单一职责（如 `BrowserUtils` 只处理浏览器打开，`CryptoUtils` 只处理加解密）
+4. **可扩展**：
+   - 新增命令：实现 `ICommand` 接口 → 放入 `commands/index.ts` 数组即可自动注册
+   - 新增工具：在 `utils/` 下新建类，通过 `utils/index.ts` 导出
+   - 命令注册器支持运行时动态注册/注销命令
+
+---
+
+## 🚀 项目使用说明
+
+### 1. 环境要求
+
+确保已安装 **Node.js v24** 或更高版本：
+
+```bash
+# 查看 Node.js 版本
+node -v
+# 要求输出 v24.x.x 或更高
+
+# 查看 npm 版本
+npm -v
+```
+
+> 如果 Node.js 版本不符合要求，建议通过 [nvm (Node Version Manager)](https://github.com/nvm-sh/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 进行安装和版本管理。
+
+### 2. 安装依赖
+
+在项目根目录下执行：
+
+```bash
+npm install
+```
+
+依赖安装完成后，`node_modules/` 目录将生成。
+
+### 3. 编译项目
+
+项目使用 TypeScript 编写，需要编译为 JavaScript 后才能运行：
+
+```bash
+# 编译（生成 dist/ 目录）
+npm run build
+
+# 清理旧的编译产物并重新编译
+npm run rebuild
+```
+
+编译完成后，`dist/` 目录将包含：
+
+- `*.js` — 编译后的 JavaScript 代码
+- `*.d.ts` — TypeScript 类型声明文件
+- `*.js.map` — SourceMap 调试映射文件
+
+### 4. 开发模式（免编译运行）
+
+开发阶段可使用 `ts-node` 直接运行 TypeScript 代码，无需手动编译：
+
+```bash
+# 直接运行 TypeScript 源码
+npm run dev -- [参数]
+
+# 示例：查看帮助
+npm run dev -- --help
+
+# 示例：执行业务命令
+npm run dev -- biz-line +list --name <业务线名称>
+```
+
+### 4.1 运行测试
+
+单元测试用 Node 内置 runner（`node --test`）配 `ts-node`，不额外引入测试框架：
+
+```bash
+# 跑全部用例
+npm test
+
+# 类型检查（tsc --noEmit）
+npm run typecheck
+```
+
+用例放在 `tests/`，通过注入 HTTP 执行器桩断言请求，不产生真实网络调用。
+
+### 5. 全局安装（推荐）
+
+将 CLI 工具链接为全局命令，可在任意目录下直接使用 `sino-bc-cli`：
+
+```bash
+# 方式一：从源码目录全局链接（开发/测试场景）
+cd d:\Project\demo\sino-bc-cli
+npm run build      # 必须先编译
+npm link           # 全局链接（Windows 下需要管理员权限）
+
+# 方式二：后续发布到 npm 后
+npm i sino-bc-cli -g
+```
+
+安装完成后，即可在任意终端直接使用：
+
+```bash
+sino-bc-cli --help
+sino-bc-cli /init
+sino-bc-cli biz-line --help
+sino-bc-cli biz-line +list --name <业务线名称>
+```
+
+`npm i sino-bc-cli -g` 完成后会自动执行 `/init`，把唯一技能 `sino-bc-cli` 写到 `~/.agents/skills/sino-bc-cli/`，并清掉旧的平级 `sino-bc-shared` / `sino-bc-<domain>`。飞书豆包工作：技能·连接器 → 管理 → **本地** → 刷新。若未出现，手动执行：
+
+```bash
+sino-bc-cli /init
+```
+
+> 卸载全局链接：`npm unlink` 或 `npm uninstall -g sino-bc-cli`
+
+---
+
+## 📖 命令说明
+
+命令分两类：**生命周期命令**用 `/` 前缀，负责安装与配置；**业务命令**是 Shortcut 执行面，形如 `<域> +<命令>`。
+
+### 生命周期命令
+
+| 命令        | 说明                                                                                          |
+| :---------- | :-------------------------------------------------------------------------------------------- |
+| `/init`       | 注册唯一技能 `sino-bc-cli` 到 Agent 技能目录（并删除旧平级 `sino-bc-shared` / `sino-bc-<domain>`），交互设置环境 / `API_KEY` |
+| `/skill`      | 列出包内 Agent 技能；传入 name 打开对应 `SKILL.md` |
+| `/get-config` | 查看变量配置；密钥默认打码，`--show-secret` 显示明文，`--json` 输出 JSON |
+| `/set-config` | 修改变量配置（环境 / API_KEY / 维护者的 `apifox-token`）；不带参数时逐项交互修改环境与 API_KEY |
+| `/uninstall`  | 删除技能目录与变量配置文件，并从全局 npm 卸载本 CLI |
+| `/bc-api`     | **已下线**。只打印迁移提示并非 0 退出，改用 `biz-line +<shortcut>` 或 `biz-line api <name>` |
+
+### 业务命令（`biz-line`）
+
+| 命令 | 说明 |
+| :--- | :--- |
+| `biz-line +channels` | 查询投放渠道列表（`code` 即业务线里的 `mediaChannelId`） |
+| `biz-line +categories` | 查询投放行业与品类字典树 |
+| `biz-line +list` | 查询业务线；`--name` / `--id` / `--category`，不传即查全部（`pagination: false`） |
+| `biz-line +strategies` | 查周策略与表现；`--name` 会先解析业务线 ID，或传单个 `--id` |
+| `biz-line +save` / `+update` / `+status` / `+delete` | ⚠️ 业务线写操作 |
+| `biz-line +strategy-save` / `+strategy-update` / `+strategy-delete` | ⚠️ 周策略写操作 |
+| `biz-line api <name> --data '<json>'` | 按接口 `name` 点名调用，覆盖导出、对比、消耗等长尾接口 |
+
+`+list --category` 同时接受数字 ID 与名称；传名称时会先查品类字典再映射，映射不到会报错并列出可选值。`+list` 不再接受 `--channel` / `--industry`。行业 / 品类 Top 没有 Shortcut。
+
+### Shortcut 面公共参数
+
+| 参数 | 说明 |
+| :--- | :--- |
+| `--format json\|table` | 输出格式。TTY 默认 `table`，非 TTY 默认 `json` |
+| `--dry-run` | 只打印将要发起的 method / URL / 请求体，不发请求 |
+| `--yes` | 跳过写操作确认，直接发起请求 |
+
+### 输出契约与退出码
+
+非 TTY（管道 / CI / Agent）默认输出 JSON 信封。成功走 stdout，失败走 stderr：
+
+```json
+{ "ok": true,  "env": "prod", "command": "biz-line +list", "data": [], "meta": { "count": 0 } }
+{ "ok": false, "env": "prod", "command": "biz-line +delete", "error": { "type": "confirmation_required", "message": "...", "hint": "..." } }
+```
+
+`data` 只包含上游 `result`。**判断成功请看 `ok` 或进程退出码，不要看上游 `code`。**
+
+| 退出码 | 含义 |
+| :----- | :--- |
+| `0` | 成功 |
+| `10` | 写操作待确认，**不是错误**；向用户确认后在原命令末尾追加 `--yes` 重试 |
+| 其他非 0 | 失败，详见 `error.type`（`validation` / `config` / `api`） |
+
+### 变量配置文件
+
+环境、`API_KEY` 与维护者用的 `apifoxToken` 存放在 `<用户主目录>/.sino-bc-cli/config.json`。`X-GATEWAY-TYPE` 固定为 `A2C-CLI`，不开放配置。
+
+| 字段 | 命令行键名 | 默认值 | 说明 |
+| :--- | :--------- | :----- | :--- |
+| `env` | `env` | `prod` | 目标环境，可选 `test` / `pre` / `prod` |
+| `apiKey` | `api-key` | 内置默认 Key | 网关鉴权用的 API Key（业务命令使用） |
+| `apifoxToken` | `apifox-token` | 空 | 仅维护者同步接口文档用（`npm run sync-api-doc`），与业务调用无关；`/init` 不会询问它 |
+
+```bash
+# 查看（密钥打码）
+sino-bc-cli /get-config
+
+# 三种修改写法等价
+sino-bc-cli /set-config env test
+sino-bc-cli /set-config env=test
+sino-bc-cli /set-config --env=test
+
+# 不带参数则逐项交互修改，直接回车保留当前值（只问环境与 API_KEY）
+sino-bc-cli /set-config
+
+# 维护者才需要：配置 Apifox token（默认打码，--show-secret 看明文）
+sino-bc-cli /set-config apifox-token <你的 token>
+```
+
+> `/init` 在非交互环境（npm `postinstall`、CI、Agent 调用）下不提问：配置文件已存在则保持不变，不存在则按默认值创建。
+
+### 全局选项
+
+| 选项        | 短选项 | 说明                                      |
+| :---------- | :----- | :---------------------------------------- |
+| `--version` | `-v`   | 显示版本信息                              |
+| `--help`    | `-h`   | 显示帮助信息                              |
+| `--debug`   | `-d`   | 启用 Debug 日志模式，输出更详细的运行信息 |
+
+### 环境与请求网关
+
+业务命令的请求地址由 [`src/constants/gateway.ts`](./src/constants/gateway.ts) 的 `GATEWAY_CONFIG` 决定，统一走 `joinGatewayUrl(env, path)` 拼接，实际请求由 [`src/utils/gateway-client.ts`](./src/utils/gateway-client.ts) 这一个出口发出。`path` 等于接口文档 / OpenAPI 路由，不再拼接 `/sino-opti-hive`。
+
+| `ENV`  | 说明     | 网关地址                             |
+| :----- | :------- | :----------------------------------- |
+| `test` | 测试环境 | `https://test-agent.beyondclick.com` |
+| `pre`  | 预发环境 | `https://test-agent.beyondclick.com` |
+| `prod` | 生产环境 | `https://test-agent.beyondclick.com` |
+
+> 当前三环境同一地址。换地址只需改 `GATEWAY_CONFIG`，同时同步 [`SKILL.md`](./SKILL.md) 与 [`src/api-doc/`](./src/api-doc/custom/README.md) 中的示例地址。
+
+### 使用示例
+
+#### ① 查看版本和帮助
+
+```bash
+# 查看版本号
+sino-bc-cli --version
+sino-bc-cli -v
+
+# 查看帮助文档（含所有可用命令列表）
+sino-bc-cli --help
+sino-bc-cli -h
+```
+
+#### ② 查看某域何时用哪条命令
+
+```bash
+sino-bc-cli biz-line --help
+```
+
+接口字段口径见 [`src/api-doc/custom/README.md`](./src/api-doc/custom/README.md)。
+
+#### ③ 查询业务线数据
+
+```bash
+# 按名称查业务线
+sino-bc-cli biz-line +list --name <业务线名称>
+
+# 按品类筛选（接受名称或 ID）
+sino-bc-cli biz-line +list --category <品类>
+
+# 查某条业务线的周策略与表现
+sino-bc-cli biz-line +strategies --name <业务线名称>
+
+# 没有 Shortcut 的长尾接口
+sino-bc-cli biz-line api biz-line-strategy-compare \
+  --data '{"bizLineId":123,"currentId":2,"prevId":1}'
+```
+
+执行效果：向配置文件指定环境的网关发起请求，路径等于接口文档路由，自动注入 `Authorization` 与 `X-GATEWAY-TYPE: A2C-CLI`。接口清单见 [`src/api-doc/custom/README.md`](./src/api-doc/custom/README.md)。
+
+#### ④ 执行写操作（需确认）
+
+```bash
+# 先预览请求，不会真正发起
+sino-bc-cli biz-line +status --id 123 --status 3 --dry-run
+
+# 确认无误后追加 --yes
+sino-bc-cli biz-line +status --id 123 --status 3 --yes
+```
+
+> ⚠️ 写操作会变更线上数据。不加 `--yes` 时：交互式终端会展示环境与关键参数并询问；非交互式环境以退出码 `10` 返回 `confirmation_required`，需人工确认后再重试。
+
+#### ⑤ 启用 Debug 模式运行
+
+```bash
+sino-bc-cli --debug biz-line --help
+# 或使用短选项
+sino-bc-cli -d biz-line --help
+```
+
+Debug 模式会输出详细的日志，包括参数解析、命令注册、接口调用过程等信息，便于排查问题。
+
+---
+
+## 🌐 跨平台兼容性
+
+本工具已针对以下操作系统进行兼容性处理：
+
+| 操作系统                     | 测试状态 | 打开浏览器方式                                                     |
+| :--------------------------- | :------- | :----------------------------------------------------------------- |
+| **Windows** (10/11)          | ✅ 支持  | 使用 `cmd /c start "" "url"`，已处理 URL 中 `&`/`^` 等特殊字符转义 |
+| **macOS**                    | ✅ 支持  | 使用系统 `open` 命令                                               |
+| **Linux** (Ubuntu/CentOS 等) | ✅ 支持  | 使用 `xdg-open` 命令                                               |
+
+> 所有平台均通过 Node.js 内置 `child_process.exec` 调用，**不依赖任何 native 模块**，确保跨平台一致性。
+
+---
+
+## 📦 NPM 脚本说明
+
+在 `package.json` 中预定义了以下脚本：
+
+```bash
+# 编译 TypeScript 为 JavaScript（输出到 dist/）
+npm run build
+
+# 类型检查（不产出文件）
+npm run typecheck
+
+# 跑单元测试
+npm test
+
+# 开发模式：直接运行 TypeScript 源码（ts-node）
+npm run dev -- [参数]
+
+# 运行已编译的 CLI（需要先 build）
+npm start -- [参数]
+
+# 清理编译产物（删除 dist/ 目录）
+npm run clean
+
+# 清理后重新编译
+npm run rebuild
+```
+
+---
+
+## 🔧 扩展新命令（开发者指南）
+
+先判断要加的是哪一类：
+
+- **生命周期命令**（安装、配置、维护，用 `/` 前缀）→ 加到 `src/commands/`
+- **业务命令**（调接口拿数据，形如 `biz-line +xxx`）→ 加到 `src/shortcuts/`
+
+### A. 新增业务 Shortcut
+
+1. **写声明**：在 `src/shortcuts/biz-line/read.ts` 或 `write.ts` 里新增一条 `IShortcutDefinition`，声明 `command`、`risk`、`flags`，并在 `resolve()` 里返回目标接口与请求体
+2. **登记**：加入 `src/shortcuts/biz-line/index.ts` 的 `BIZ_LINE_SHORTCUTS` 数组
+3. **补测试**：在 `tests/` 下用 HTTP 桩断言请求与输出
+4. **同步文档**：`skills/system/sino-bc-biz-line` 的意图表、`affordance/biz-line.md` 的 WHEN、`src/api-doc/system/` 的字段口径；手写补充放 `skills/custom/` 与 `src/api-doc/custom/`；根 `SKILL.md` 只做入口
+
+参数解析、输出格式、写操作确认门、错误归类都由 `src/shortcuts/index.ts` 统一承担，声明里不要自己发 HTTP。接口 `name` 一律取自 `src/generated/api-catalog.json`，不要新造。
+
+维护者同步 Apifox：`npm run sync-api-doc`。token 按三级回退取值——环境变量 `APIFOX_TOKEN` > `~/.sino-bc-cli/config.json` 的 `apifoxToken` > 终端交互输入；交互输入到的 token 会写回该配置文件，下次不再询问。三处都没有则非 0 退出。CI 用环境变量覆盖即可。**不要把 token 写入仓库任何文件。**
+
+> 只是想调一个已有接口，通常不需要写新 Shortcut——直接 `biz-line api <name> --data '<json>'` 即可。Shortcut 应当带来智能默认值、参数编排或更友好的输出，否则不值得新增。
+
+### B. 新增生命周期命令
+
+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 InitCommand(),
+  new GetConfigCommand(),
+  new ExampleCommand(), // 新增注册
+];
+```
+
+完成后执行 `npm run build` 即可使用 `sino-bc-cli /example`。
+
+---
+
+## 📄 License
+
+MIT License