sino-bc-cli 1.8.0 → 1.8.2

package/README.md

@@ -84,9 +84,9 @@ npm ls -g --depth=0 sino-bc-cli   # 确认全局安装的版本
 sino-bc-cli /init
 ```
 
-`/init` 会把 `SKILL.md` 写入用户主目录的 Agent 技能目录（`~/.agents/skills/sino-bc-cli` 等），Cursor / Claude / Codex / 飞书豆包工作 才能识别到本技能。飞书豆包工作侧还需：技能·连接器 → 管理 → **本地** → 刷新。
+`/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`，以刷新本地技能文件。
+> 每次升级版本后请重新执行一次 `sino-bc-cli /init`，以刷新本地技能文件。
 
 ### ⑥ 免安装临时执行
 
@@ -136,25 +136,40 @@ sino-bc-cli/
 │   ├── 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 命令实现（列出接口并打开文档）
-│   │   ├── api-endpoint.command.ts # 接口调用类命令基类（经网关 HTTP 调用）
-│   │   ├── bc-api.command.ts     # /bc-api 命令实现（调用业务线查询 / 业务线策略接口）
+│   │   ├── 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       # 变量配置读写（字段元信息 + 读 / 写 / 删）
@@ -167,10 +182,16 @@ sino-bc-cli/
 │   │   └── index.ts              # 全局接口、枚举定义（ICommand、LogLevel 等）
 │   │
 │   └── constants/                # 🔧 常量配置层
-│       └── index.ts              # CLI 配置、命令名称、默认值
+│       └── 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 + api-doc（不含 SourceMap）
+│   └── ...                       # 单文件混淆压缩产物 + SKILL.md + skills/ + affordance/ + api-doc（不含 SourceMap）
 │
 ├── package.json                  # 📄 项目配置（依赖、脚本、bin 命令）
 ├── tsconfig.json                 # 📄 TypeScript 编译配置
@@ -246,10 +267,24 @@ npm run dev -- [参数]
 # 示例：查看帮助
 npm run dev -- --help
 
-# 示例：执行 /bc-api 命令
-npm run dev -- /bc-api
+# 示例：执行业务命令
+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`：
@@ -270,10 +305,10 @@ npm i sino-bc-cli -g
 sino-bc-cli --help
 sino-bc-cli /init
 sino-bc-cli /api-list
-sino-bc-cli /bc-api
+sino-bc-cli biz-line +list --name <业务线名称>
 ```
 
-`npm i sino-bc-cli -g` 完成后会自动执行 `/init`，把 `SKILL.md` 写到用户主目录的 Agent 技能目录（`~/.agents/skills/sino-bc-cli` 等）。飞书豆包工作：技能·连接器 → 管理 → **本地** → 刷新。若未出现，手动执行：
+`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
@@ -285,17 +320,60 @@ sino-bc-cli /init
 
 ## 📖 命令说明
 
-### 可用命令一览
+命令分两类：**生命周期命令**用 `/` 前缀，负责安装与配置；**业务命令**是 Shortcut 执行面，形如 `<域> +<命令>`。
+
+### 生命周期命令
 
 | 命令        | 说明                                                                                          |
 | :---------- | :-------------------------------------------------------------------------------------------- |
-| `/init`       | 注册 `SKILL.md` 到 Agent 技能目录，交互设置环境 / `API_KEY`，并拉取启动 MCP |
-| `/api-list`   | 列出全部可调用接口；Cursor / VS Code 终端中 Ctrl+单击接口名或文档路径打开本地文档，也可输入序号或传入 name |
-| `/bc-api`     | 交互选择并调用业务线查询 / 业务线策略接口（共 22 个，路径统一带 `/sino-opti-hive` 前缀）；**不接收参数**。经网关 HTTP |
+| `/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`） |
 
 ### 变量配置文件
 
@@ -306,7 +384,7 @@ MCP Server 存放在 `<用户主目录>/.sino-bc-cli/mcp.json`，结构与 Curso
 | 字段 | 命令行键名 | 默认值 | 说明 |
 | :--- | :--------- | :----- | :--- |
 | `env` | `env` | `prod` | 目标环境，可选 `test` / `pre` / `prod` |
-| `apiKey` | `api-key` | 内置默认 Key | 网关鉴权用的 API Key（`/bc-api` 使用） |
+| `apiKey` | `api-key` | 内置默认 Key | 网关鉴权用的 API Key（业务命令使用） |
 
 ```bash
 # 查看（密钥打码）
@@ -351,7 +429,7 @@ sino-bc-cli /mcp-reload
 
 ### 环境与请求网关
 
-`/bc-api` 的请求地址由 [`src/constants/gateway.ts`](./src/constants/gateway.ts) 的 `GATEWAY_CONFIG` 决定，命令内部统一走 `joinGatewayUrl(env, path)` 拼接。业务线路径带 `/sino-opti-hive`。iCenter 请写入 `mcp.json` 后 `/mcp-reload`。
+业务命令的请求地址由 [`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`  | 说明     | 网关地址                             |
 | :----- | :------- | :----------------------------------- |
@@ -394,22 +472,46 @@ 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 /bc-api
+# 按名称查业务线
+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}'
 ```
 
-执行效果：按「业务线查询（5 个）」「业务线策略（17 个）」两组列出接口，输入序号后向配置文件指定环境的网关发起请求。所有路径统一带 `/sino-opti-hive` 路由前缀，接口清单见 [`src/api-doc/README.md`](./src/api-doc/README.md)。
+执行效果：向配置文件指定环境的网关发起请求，路径统一带 `/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
+```
 
-#### ⑤ 启用 Debug 模式运行
+> ⚠️ 写操作会变更线上数据。不加 `--yes` 时：交互式终端会展示环境与关键参数并询问；非交互式环境以退出码 `10` 返回 `confirmation_required`，需人工确认后再重试。
+
+#### ⑥ 启用 Debug 模式运行
 
 ```bash
-sino-bc-cli --debug /bc-api
+sino-bc-cli --debug /api-list
 # 或使用短选项
-sino-bc-cli -d /bc-api
+sino-bc-cli -d /api-list
 ```
 
 Debug 模式会输出详细的日志，包括参数解析、命令注册、接口调用过程等信息，便于排查问题。
@@ -438,6 +540,12 @@ Debug 模式会输出详细的日志，包括参数解析、命令注册、接
 # 编译 TypeScript 为 JavaScript（输出到 dist/）
 npm run build
 
+# 类型检查（不产出文件）
+npm run typecheck
+
+# 跑单元测试
+npm test
+
 # 开发模式：直接运行 TypeScript 源码（ts-node）
 npm run dev -- [参数]
 
@@ -455,7 +563,23 @@ 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()` 方法
@@ -486,7 +610,7 @@ import { ExampleCommand } from "./example.command"; // 新增导入
 export const commands: ICommand[] = [
   new InitCommand(),
   new ApiListCommand(),
-  new IcApiCommand(),
+  new GetConfigCommand(),
   new ExampleCommand(), // 新增注册
 ];
 ```

package/dist/SKILL.md

@@ -1,11 +1,8 @@
 ---
 name: sino-bc-cli
 description: >
-  Use when 查询或操作 BeyondClick 业务线数据：投放渠道、投放品类、
-  业务线列表/详情/策略与表现、Top 业务线、周策略增删改查、
-  红绿灯、客户满意度、消耗、ROAS；或用户提到 sino-bc-cli、/init、/api-list、
-  /bc-api、/get-config、/set-config、/mcp-reload、/uninstall、
-  sino-opti-hive、A2C-CLI。
+  Use when 查询或操作 BeyondClick 业务线，或配置 sino-bc-cli / MCP。
+  完整规则在 sino-bc-shared 与 sino-bc-biz-line；本文件只做入口。
 metadata:
   requires:
     bins: ["sino-bc-cli"]
@@ -13,110 +10,17 @@ metadata:
 
 # sino-bc-cli
 
-BeyondClick 业务线策略的 Agent 调用入口。用本 CLI 发现接口和文档，再按用户真实参数请求网关。
-iCenter 不走本 CLI 接口清单：用户把 MCP Server 写进 `~/.sino-bc-cli/mcp.json`，`/init` 或 `/mcp-reload` 会同步到 Cursor / Codex / Claude / VS Code。
+Agent 技能已拆成两份，**不要只读这一页**。
 
-## When to Use
+1. 配置、信封、确认门、禁止拼 HTTP、MCP：[`skills/sino-bc-shared/SKILL.md`](skills/sino-bc-shared/SKILL.md)
+2. 业务线意图与 Shortcut：[`skills/sino-bc-biz-line/SKILL.md`](skills/sino-bc-biz-line/SKILL.md)
 
-- 查投放渠道、投放行业/品类、业务线主数据、周策略与表现、行业 Top
-- 新建/编辑/删除业务线或周策略（须先确认环境和写操作意图）
-- 用户点名 `/api-list`、`/bc-api`、`/mcp-reload`、sino-opti-hive
-- 用户要给 Cursor / Codex / Claude / VS Code 增加或重启 MCP
-
-不要用本技能处理：本仓库源码开发、扩展命令、npm 发版（见 `README.md` / `ReleaseSteps.md`）。
-
-## 调用约定
-
-| 项 | 规则 |
-| --- | --- |
-| 环境 | `test` / `pre` / `prod`，取自变量配置文件，默认 `prod` |
-| 网关 | `https://test-agent.beyondclick.com`（当前三环境同一地址；`/bc-api` 走网关，不直连服务地址） |
-| 业务线前缀 | `/sino-opti-hive` |
-| 鉴权 | `Authorization: Bearer <API_KEY>`；取自变量配置文件，未设置时用 CLI 内置默认值 |
-| 来源头 | 必须带 `X-GATEWAY-TYPE: A2C-CLI`（CLI 固定写入，不开放配置） |
-| 请求体 | 按用户条件组装；禁止原样提交文档示例业务线 ID |
-| iCenter / 其他 MCP | 编辑 `~/.sino-bc-cli/mcp.json` 后执行 `sino-bc-cli /mcp-reload` |
-
-### 变量配置文件
-
-环境、`API_KEY` 存放在 `<用户主目录>/.sino-bc-cli/config.json`，由 `/init` 创建、`/set-config` 修改。
-MCP Server 存放在 `<用户主目录>/.sino-bc-cli/mcp.json`（与 Cursor 同结构），用户自行增删后执行 `/mcp-reload`。
-需要知道当前生效取值时执行 `sino-bc-cli /get-config --json`（密钥默认打码，加 `--show-secret` 才是明文）。
-
-`/bc-api` 不接收任何参数，且必须在交互式终端里选接口、只用文档默认 body。
-Agent 在非 TTY 下跑这条会直接报错退出；需要真实查询时用 `/api-list` 发现接口后直接 HTTP。
-
-## Agent 流程
-
-1. 对照下方意图表选定 `name`。拿不准先跑 `sino-bc-cli /api-list`。
-2. 读本地文档再组参。全局安装：`$(npm root -g)/sino-bc-cli/dist/api-doc/`；本仓库：`src/api-doc/`。`sino-bc-cli /api-list <name>` 会打开对应 markdown。
-3. 写操作（描述含 ⚠️）先向用户确认环境和意图，未确认不发。
-4. 按约定发 GET/POST，解析 `success` / `code` / `message` / `result`。
-5. 回复用业务语言摘要；文档路径写成 Markdown 链接。完整 Key 不要回显。
-6. 用户要查 iCenter 广告策略时，使用已配置的 MCP 工具，不要走 `/bc-api`。
+安装与刷新（会写入上述两份并删除旧的 `sino-bc-cli/` 技能目录）：
 
 ```bash
-curl -sS -X POST "https://test-agent.beyondclick.com/sino-opti-hive/biz-line-open/list" \
-  -H "Authorization: Bearer $API_KEY" \
-  -H "Content-Type: application/json" \
-  -H "X-GATEWAY-TYPE: A2C-CLI" \
-  -d '{"name":"用户给出的业务线名"}'
+sino-bc-cli /init
+sino-bc-cli /skill
 ```
 
-CLI 未安装：`npm i sino-bc-cli@latest -g`（需 Node.js >= 24）。技能未出现：`sino-bc-cli /init`；飞书豆包工作 → 技能·连接器 → 管理 → **本地** → 刷新。
-
-## 意图 → 接口
-
-### 业务线查询（只读，文档 `biz-line-query.md`）
-
-| 用户在问 | name | 注意 |
-| --- | --- | --- |
-| 有哪些投放渠道 | `biz-line-open-channels` | GET；`code` = 业务线里的 `mediaChannelId` |
-| 投放行业 / 品类树 | `biz-line-open-placement-categories` | GET；一级行业（1=APP / 2=ECBR / 3=游戏），二级=品类 |
-| 业务线有哪些 / 按名或渠道筛 | `biz-line-open-list` | POST；空 `{}` = 全部 |
-| 某几条业务线的周策略和表现 | `biz-line-open-strategies` | POST；必填 `bizLineIds` |
-| 行业/品类里表现最好的业务线 | `biz-line-open-strategy-top` | 行业、品类至少传一个；传了行业则忽略品类 |
-
-### 业务线策略（文档 `biz-line-strategy.md`）
-
-| 用户在问 | name | 注意 |
-| --- | --- | --- |
-| 业务线分页列表 | `biz-line-list` | |
-| 业务线详情 | `biz-line-detail` | `{ "id": <bizLineId> }` |
-| 新建 / 编辑 / 切状态 / 删除业务线 | `biz-line-save` / `update` / `status-update` / `del` | ⚠️ 写操作 |
-| 导出业务线列表 | `biz-line-list-export` | `result` 为文件 URL |
-| 周策略分页 / 详情 / 周期列表 | `biz-line-strategy-list` / `detail` / `period-list` | |
-| 新建策略前看上期摘要 | `biz-line-strategy-preview-info` | 周期为自然周 周一~周日 |
-| 新建 / 编辑 / 删除策略 | `biz-line-strategy-save` / `update` / `del` | ⚠️；编辑带 `version` 乐观锁 |
-| 两期策略对比 | `biz-line-strategy-compare` | |
-| 策略周期消耗 | `biz-line-strategy-spend` | |
-| 导出该业务线全部策略 | `biz-line-strategy-export-all` | 路径拼写是 `exprot-all`，不要改成 export |
-
-红绿灯：`1`/`6` 绿，`2`/`5` 黄，`3`/`4` 红。客户满意度：`1` 满意，`2` 不满意。业务线状态：`1` 进行中 / `2` 已完成 / `3` 已暂停。
-
-## 命令（给人用）
-
-```bash
-sino-bc-cli /api-list
-sino-bc-cli /api-list biz-line-open-list
-sino-bc-cli /bc-api
-
-sino-bc-cli /init                         # 注册技能 + 设置环境 / API_KEY，并拉取启动 MCP
-sino-bc-cli /get-config                   # 查看变量配置与 mcp.json（密钥打码）
-sino-bc-cli /set-config env prod          # 改单项；也支持 --env=prod、不带参数逐项交互
-sino-bc-cli /mcp-reload                   # 按 ~/.sino-bc-cli/mcp.json 重启 MCP
-sino-bc-cli /uninstall                    # 清理技能目录与配置文件并卸载 CLI
-```
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-| --- | --- |
-| 非 TTY 执行 `/bc-api` | 这条会报错退出；改直接 HTTP，只用 `/api-list` 发现接口 |
-| 给 `/bc-api` 传环境或 Key | 参数已下线；用 `/set-config` 改、`/get-config` 查 |
-| 用文档里的 `bizLineId: 1251` | 换成用户给出的业务线 |
-| 漏 `X-GATEWAY-TYPE` 或业务线路径前缀 | 带 `A2C-CLI` 与 `/sino-opti-hive` |
-| 直连 `o-test-sino-opti-hive` 等服务地址 | 请求网关 `https://test-agent.beyondclick.com` + `/sino-opti-hive` |
-| 改了 mcp.json 却不重启 | 执行 `sino-bc-cli /mcp-reload` |
-| 未确认就调 save/update/del | 先确认环境与写操作 |
-| 把 `exprot-all` 改成 `export-all` | 按服务端拼写调用 |
+列出包内技能：`sino-bc-cli /skill`。查看某条命令何时用：`sino-bc-cli biz-line --help`。
+升级 CLI 后请再跑一次 `/init`。

package/dist/affordance/biz-line.md

@@ -0,0 +1,63 @@
+# biz-line 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +channels
+
+- **WHEN**：用户问有哪些投放渠道、mediaChannelId 怎么填。
+- **别用**：查业务线列表（用 `+list`）。
+- **示例**：`sino-bc-cli biz-line +channels`
+
+## +categories
+
+- **WHEN**：用户问投放行业 / 品类树，或要把名称映射成字典 ID。
+- **别用**：已经有行业/品类 ID 且只要业务线（直接 `+list --industry` / `--category`）。
+- **示例**：`sino-bc-cli biz-line +categories`
+
+## +list
+
+- **WHEN**：按名称、ID、渠道、行业、品类筛业务线；不传条件 = 全部。
+- **别用**：只要某一条的周策略（用 `+strategies`）；只要行业 Top（用 `+top`）。
+- **示例**：`sino-bc-cli biz-line +list --name <业务线名称>`
+
+## +strategies
+
+- **WHEN**：查某条业务线的周策略和表现。
+- **别用**：`--name` 可能命中多条时不要猜，先 `+list` 收窄或改 `--id`。
+- **示例**：`sino-bc-cli biz-line +strategies --name <业务线名称>`
+
+## +top
+
+- **WHEN**：问某行业或品类里表现最好的业务线。
+- **别用**：行业和品类都没有时不要空跑；两个都传则只按行业。
+- **示例**：`sino-bc-cli biz-line +top --industry APP`
+
+## +save / +update
+
+- **WHEN**：新建或编辑业务线主数据。字段多用 `--data`。
+- **别用**：只改状态用 `+status`；没确认环境和意图不要加 `--yes`。
+- **示例**：`sino-bc-cli biz-line +save --data '{...}' --dry-run`
+
+## +status
+
+- **WHEN**：切换业务线状态（进行中 / 已完成 / 已暂停）。
+- **别用**：改名称或渠道用 `+update`。
+- **示例**：`sino-bc-cli biz-line +status --id 123 --status 3 --yes`
+
+## +delete
+
+- **WHEN**：删除业务线。
+- **别用**：只想停投放用 `+status --status 3`。
+- **示例**：`sino-bc-cli biz-line +delete --id 123 --dry-run`
+
+## +strategy-save / +strategy-update / +strategy-delete
+
+- **WHEN**：新建、编辑或删除周策略。编辑必须带 `version`。
+- **别用**：只对比两期用 `biz-line api biz-line-strategy-compare`。
+- **示例**：`sino-bc-cli biz-line +strategy-update --data '{...}' --yes`
+
+## api
+
+- **WHEN**：导出、对比、消耗、周期列表、上期摘要等没有 `+` 的接口。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli biz-line api biz-line-strategy-compare --data '{"bizLineId":123,"currentId":2,"prevId":1}'`

package/dist/api-doc/README.md

@@ -1,13 +1,13 @@
 # 接口文档索引
 
-本目录汇总 CLI 可交互调用的业务线接口。浏览清单用 `/api-list`（可点击打开本文档），发起调用用 `/bc-api`。
+本目录汇总 CLI 可调用的业务线接口（字段口径）。浏览清单用 `/api-list`（Shortcut 行带一句 WHEN）；何时用哪条命令见仓库 `affordance/biz-line.md` 或 `sino-bc-cli biz-line --help`。发起调用用 `biz-line +<shortcut>`；没有 Shortcut 的接口用 `biz-line api <name> --data '<json>'`。Agent 技能树在 `skills/`，自省用 `/skill`。
 
 iCenter 不再随 CLI 提供接口文档。需要 iCenter 时，把 MCP Server 写进 `~/.sino-bc-cli/mcp.json`，再执行 `/init` 或 `/mcp-reload`，CLI 会同步到 Cursor / Codex / Claude / VS Code。
 
 | 分组 | 命令 | 接口数 | 文档 |
 | --- | --- | --- | --- |
-| 业务线查询 | `/bc-api` | 5 | [biz-line-query.md](./biz-line-query.md) |
-| 业务线策略 | `/bc-api` | 17 | [biz-line-strategy.md](./biz-line-strategy.md) |
+| 业务线查询 | `biz-line +channels` / `+categories` / `+list` / `+strategies` / `+top` | 5 | [biz-line-query.md](./biz-line-query.md) |
+| 业务线策略 | `biz-line +save` / `+update` / `+status` / `+delete` / `+strategy-*`，其余 `biz-line api <name>` | 17 | [biz-line-strategy.md](./biz-line-strategy.md) |
 
 ---
 
@@ -15,7 +15,7 @@ iCenter 不再随 CLI 提供接口文档。需要 iCenter 时，把 MCP Server
 
 | 范围 | 通道 |
 | --- | --- |
-| `biz-line-query.md` / `biz-line-strategy.md` 与 `/bc-api` | 固定走网关 HTTP，路径带 `/sino-opti-hive` |
+| `biz-line-query.md` / `biz-line-strategy.md` 与 `biz-line` 命令 | 固定走网关 HTTP，路径带 `/sino-opti-hive` |
 | iCenter 及其他 MCP | 用户编辑 `~/.sino-bc-cli/mcp.json`，由 `/init`、`/mcp-reload` 同步并启动 |
 
 网关地址的唯一来源是 `src/constants/gateway.ts` 的 `GATEWAY_CONFIG`；各文档中出现的上游服务地址（`o-test-sino-opti-hive` 等）仅作接口文档出处，不作为请求地址。
@@ -41,9 +41,11 @@ iCenter 不再随 CLI 提供接口文档。需要 iCenter 时，把 MCP Server
 | [biz-line-query.md](./biz-line-query.md) | 业务线查询 | 5 | 对外开放的只读查询：渠道、品类字典、业务线列表、策略及表现、Top 业务线 |
 | [biz-line-strategy.md](./biz-line-strategy.md) | 业务线策略 | 17 | 业务线主数据与周策略的增删改查、导出 |
 
-对应命令：`/bc-api`，接口清单定义在 `src/constants/biz-line-api-doc.ts`。
+对应命令：`biz-line +<shortcut>` 与 `biz-line api <name>`，接口清单定义在 `src/constants/biz-line-api-doc.ts`。
 
-> ⚠️ 业务线策略组含新建 / 编辑 / 删除等写操作接口，`/bc-api` 会按文档示例请求体直接发起调用，调用前请确认环境。
+> ⚠️ 业务线策略组含新建 / 编辑 / 删除等写操作接口。写操作必须先确认：不加 `--yes` 时交互式终端会询问，非交互式环境以退出码 `10` 返回 `confirmation_required`；执行前可用 `--dry-run` 预览请求。
+>
+> 文档中的「请求示例」只用于说明字段口径，**不会**被任何命令当作默认请求体发送。
 
 ---
 
@@ -57,16 +59,27 @@ sino-bc-cli /api-list 1
 sino-bc-cli /api-list biz-line-open-channels
 ```
 
-`/bc-api` 交互选接口后经网关发起调用，请求体默认使用各文档「请求示例」；`GET` 接口无请求体。环境与鉴权取自变量配置文件，命令本身不接收参数。
+发起调用经网关 HTTP；环境与鉴权取自变量配置文件，无需在命令上传。
 
 ```bash
-# 业务线接口
-sino-bc-cli /bc-api
+# 有 Shortcut 的高频查询
+sino-bc-cli biz-line +list --name <业务线名称>
+sino-bc-cli biz-line +strategies --name <业务线名称>
+
+# 没有 Shortcut 的接口按 name 点名调用
+sino-bc-cli biz-line api biz-line-strategy-compare \
+  --data '{"bizLineId":123,"currentId":2,"prevId":1}'
+
+# 写操作：先预览，确认后追加 --yes
+sino-bc-cli biz-line +delete --id 123 --dry-run
+sino-bc-cli biz-line +delete --id 123 --yes
 
 # 切换环境
 sino-bc-cli /set-config env test
 ```
 
+输出格式：TTY 默认表格，非 TTY 默认 JSON 信封（`--format` 可覆盖）。成功 `{ ok: true, data }` 走 stdout，失败 `{ ok: false, error }` 走 stderr；退出码 `0` 成功、`10` 待确认、其余非 0 失败。
+
 | 配置 | 默认值 | 说明 |
 | --- | --- | --- |
 | `env` | `prod` | `test` / `pre` / `prod`，用于取 `src/constants/gateway.ts` 中的网关地址 |

package/dist/api-doc/biz-line-query.md

@@ -204,11 +204,15 @@
 ## 命令调用
 
 ```bash
-# 默认生产环境 + 内置 API Key，交互选择接口
-sino-bc-cli /bc-api
-
-# 指定环境（test / pre / prod）
-sino-bc-cli /bc-api test
+# 本组接口都有 Shortcut
+sino-bc-cli biz-line +channels
+sino-bc-cli biz-line +categories
+sino-bc-cli biz-line +list --name <业务线名称>
+sino-bc-cli biz-line +strategies --name <业务线名称>
+sino-bc-cli biz-line +top --industry APP --top-n 5
+
+# 切换环境（test / pre / prod）
+sino-bc-cli /set-config env test
 ```
 
 详见 [README.md](./README.md)。

package/dist/api-doc/biz-line-strategy.md

@@ -8,7 +8,7 @@
 >
 > **路由前缀**：经网关调用时所有路径需带 `/sino-opti-hive`，例如 `/sino-opti-hive/biz-line/list`。
 >
-> ⚠️ 标记为「写操作」的接口会变更线上数据，`/bc-api` 会按文档示例请求体直接发起调用，调用前请确认环境。
+> ⚠️ 标记为「写操作」的接口会变更线上数据。CLI 会强制确认：不加 `--yes` 时交互式终端询问，非交互式环境以退出码 `10` 返回 `confirmation_required`；执行前可用 `--dry-run` 预览。文档中的「请求示例」只说明字段口径，不会被当作默认请求体发送。
 
 | # | name | 展示名 | 方法 | 路径（含前缀） |
 | --- | --- | --- | --- | --- |
@@ -305,11 +305,15 @@
 ## 命令调用
 
 ```bash
-# 默认生产环境 + 内置 API Key，交互选择接口
-sino-bc-cli /bc-api
+# 写操作有 Shortcut：先预览，确认后追加 --yes
+sino-bc-cli biz-line +status --id <业务线 ID> --status 3 --dry-run
+sino-bc-cli biz-line +status --id <业务线 ID> --status 3 --yes
 
-# 指定环境（test / pre / prod）
-sino-bc-cli /bc-api test
+# 其余接口按 name 点名调用
+sino-bc-cli biz-line api biz-line-strategy-detail --data '{"bizLineId":123,"id":1}'
+
+# 切换环境（test / pre / prod）
+sino-bc-cli /set-config env test
 ```
 
 详见 [README.md](./README.md)。