sino-bc-cli 1.8.12 → 1.8.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +139 -542
  2. package/dist/api-doc/oapi/dashboard.md +18 -18
  3. package/dist/api-doc/oapi/delivery.md +13 -8
  4. package/dist/api-doc/oapi/im.md +5 -2
  5. package/dist/api-doc/oapi/project.md +17 -8
  6. package/dist/api-doc/oapi/task.md +10 -10
  7. package/dist/generated/api-catalog.json +697 -403
  8. package/dist/index.js +1 -1
  9. package/package.json +1 -1
package/README.md CHANGED
@@ -1,616 +1,213 @@
1
1
  # sino-bc-cli
2
2
 
3
- BeyondClick 命令行工具集合 - 提供快捷访问 BeyondClick 平台的命令行接口。
3
+ BeyondClick 全局命令行工具。用本机命令访问平台能力，**不要自己拼网关 HTTP**。
4
4
 
5
- ## Install
5
+ 已发布到 [npm](https://www.npmjs.com/package/sino-bc-cli)。官网右侧 Install 框里的 `npm i sino-bc-cli` 没有 `-g`，那是网站固定文案；本包请按下面的全局安装命令执行。
6
6
 
7
- > ⚠️ 本包是**全局 CLI 工具**。npm 官网右侧 Install 框里的 `npm i sino-bc-cli` 是网站写死的固定文案，不是本包的推荐用法，请以下面的命令为准（注意 `-g`）。
8
- >
9
- > 运行环境要求 Node.js >= 24.0.0。
7
+ ## 环境要求
10
8
 
11
- ### ① 安装最新版本（推荐）
9
+ - Node.js **>= 24.0.0**
10
+ - 能访问 npm 官方源 `https://registry.npmjs.org/`
12
11
 
13
12
  ```bash
14
- # npm
15
- npm i sino-bc-cli@latest -g
16
-
17
- # pnpm
18
- pnpm add -g sino-bc-cli@latest
19
-
20
- # yarn
21
- yarn global add sino-bc-cli@latest
13
+ node -v # 需要 v24.x 或更高
22
14
  ```
23
15
 
24
- 已经装过旧版本时，执行同样的命令即可升级覆盖。想先确认远端最新版本号：
16
+ ## 架构设计
25
17
 
26
- ```bash
27
- npm view sino-bc-cli version # 查看 latest 版本号
28
- npm outdated -g sino-bc-cli # 对比本地全局版本是否过期
29
- ```
18
+ 运行时只有两条执行面，外加一条**不参与用户调用**的维护者同步面。
30
19
 
31
- ### ② 安装指定版本
20
+ | 面 | 入口形态 | 职责 | 不做什么 |
21
+ | --- | --- | --- | --- |
22
+ | 斜杠命令 | `/init` `/auth` … | 安装技能、升级、配置、身份、租户列表 | 不调业务接口、不拼业务 URL |
23
+ | 业务 Shortcut | `<域> +<命令>` 或 `<域> api <name>` | 按接口清单调网关 | 不改技能目录、不定义配置字段 |
24
+ | 维护者同步 | `npm run sync-api-doc` | 从 Apifox 生成清单 / 文档 / 技能 | 不走网关客户端，用户安装后不会再打 Apifox |
32
25
 
33
- 把 `@latest` 换成目标版本号即可，适用于需要回退或锁定版本的场景：
26
+ 设计取舍：
34
27
 
35
- ```bash
36
- # npm
37
- npm i sino-bc-cli@1.0.5 -g
28
+ 1. **清单驱动**：运行时只认包内接口清单（name、path、域、风险、是否要主体）。命令里不写死 URL。
29
+ 2. **请求编排集中**：鉴权头、主体绑定、确认门、分页、输出信封由公共层做。域代码只回答「调哪条接口、请求体是什么」。
30
+ 3. **Shortcut 三层**：手写（名称解析、默认值）优先；其余一对一由清单生成薄命令；长尾用 `api <name>` 点名。
31
+ 4. **生成物与手写分层**：同步只覆盖生成层；专家口径和横切规则不随同步被冲掉。
38
32
 
39
- # pnpm
40
- pnpm add -g sino-bc-cli@1.0.5
33
+ ```mermaid
34
+ flowchart TB
35
+ subgraph runtime [用户运行时]
36
+ U[用户 / Agent] --> BIN[sino-bc-cli]
37
+ BIN --> APP[解析 argv 并分流]
38
+ APP -->|斜杠命令| CMD[生命周期命令]
39
+ APP -->|域 +命令 或 域 api| SC[Shortcut 执行器]
40
+ APP -->|只有域名| HELP[域帮助 不发 HTTP]
41
+ CMD --> LOCAL[本机：技能 / 配置 / 身份]
42
+ SC --> CAT[接口清单]
43
+ SC --> GW[网关客户端]
44
+ CAT --> GW
45
+ GW --> HTTP[HTTP]
46
+ HTTP --> API[BeyondClick 网关]
47
+ end
41
48
 
42
- # yarn
43
- yarn global add sino-bc-cli@1.0.5
49
+ subgraph maintainer [维护者同步 不在运行时触发]
50
+ AF[Apifox OpenAPI] --> SYNC[生成 catalog / 文档 / 技能]
51
+ SYNC --> CAT
52
+ end
44
53
  ```
45
54
 
46
- 查看全部可安装版本：
55
+ 身份令牌存在本机平台密钥存储，不进普通配置明文。业务请求统一带 `Authorization` 与 `X-GATEWAY-TYPE: A2C-CLI`，根地址是生效的 `gateway-url`（缺省 `https://agent.beyondclick.com`）。需要签约主体的接口必须在**这一次调用**传入 `--corporation-id` 与 `--auth-context-id`，没有全局当前主体。
47
56
 
48
- ```bash
49
- npm view sino-bc-cli versions --json
50
- ```
57
+ ## 代码执行流程
51
58
 
52
- ### ③ 卸载
59
+ 进程入口创建应用、跑完 `argv`、按退出码结束。全局选项（`--version` / `--help` / `--debug`）先扫一遍；是否走业务只看**位置参数**。
53
60
 
54
- ```bash
55
- # npm
56
- npm uninstall -g sino-bc-cli
61
+ ### 1. 路由
57
62
 
58
- # pnpm
59
- pnpm remove -g sino-bc-cli
63
+ ```mermaid
64
+ flowchart TD
65
+ START[process.argv] --> INIT[注册斜杠命令]
66
+ INIT --> GLOB{"全局 --version / --help?"}
67
+ GLOB -->|已处理且不是域帮助| EXIT1[退出]
68
+ GLOB -->|继续| POS{位置参数}
60
69
 
61
- # yarn
62
- yarn global remove sino-bc-cli
70
+ POS -->|无| BANNER[欢迎 + 全局帮助]
71
+ POS -->|首参是已知域 且 次参是 +xxx 或 api| SC[Shortcut 执行器]
72
+ POS -->|首参是已知域 否则| DH[打印域帮助 不发 HTTP]
73
+ POS -->|其它| SLASH[斜杠命令注册表]
63
74
  ```
64
75
 
65
- > 如果当初是在源码目录用 `npm link` 做的开发链接，请改用 `npm unlink -g sino-bc-cli` 解除。
76
+ 例如：`biz-line +list` 走 Shortcut；`biz-line --help` 走域帮助；`/auth login` 走斜杠命令。未知的 `+命令` 仍进 Shortcut，再以参数错误失败，不会悄悄变成帮助。
66
77
 
67
- ### ④ 验证安装
68
-
69
- ```bash
70
- sino-bc-cli --version # 输出版本号，说明命令已可用
71
- sino-bc-cli --help # 输出帮助信息和全部可用命令
72
- npm ls -g --depth=0 sino-bc-cli # 确认全局安装的版本
73
- ```
78
+ ### 2. 斜杠命令
74
79
 
75
- 若提示「command not found / 无法将 sino-bc-cli 项识别为命令」，说明 npm 全局 bin 目录不在 `PATH` 中。用 `npm prefix -g` 查看全局安装根目录（Windows 下该目录即 bin 目录，macOS / Linux 下为其 `bin` 子目录），把它加入环境变量后重开终端。
80
+ 去掉可选的 `/`，在注册表里查找并执行。这一面只动本机（技能目录、配置、身份），**不**走业务 Shortcut 执行器。
76
81
 
77
- ### ⑤ 初始化（必须执行一次）
78
-
79
- **装完之后必须完成 `/init` 初始化，CLI 的 Agent 技能才会生效。**
80
-
81
- 全局安装时 `postinstall` 会自动执行一次 `/init`。但在以下情况会被跳过，需要手动补执行：使用 `--ignore-scripts` 安装、安装目录权限不足、或通过 `npx` 临时运行。
82
-
83
- ```bash
84
- sino-bc-cli /init
82
+ ```mermaid
83
+ flowchart LR
84
+ A["/init /update /skill ..."] --> R[命令注册表]
85
+ R --> E[对应命令 execute]
86
+ E --> L[写技能 / 读配置 / 登录或列主体]
85
87
  ```
86
88
 
87
- `/init` 会把根 `SKILL.md` 与 `skills/oapi/`、`skills/custom/`、`skills/default/` 下的标准子技能（`SKILL.md` + `references/`，同路径以后写的层为准）嵌进各 Agent 技能目录下的 `sino-bc-cli/`，不出现 `oapi/` / `custom/` / `default/` 这一层；同时删除旧的平级 `sino-bc-shared` / `sino-bc-<domain>` 技能目录。
88
-
89
- **默认安装目标（带门控）：**
89
+ `/tenant list` 是身份面的主体查询，不是业务域里的随意写操作。
90
90
 
91
- | 目标 | 门控 |
92
- | :--- | :--- |
93
- | `~/.agents/skills` | 始终创建并写入（飞书豆包 / 通用） |
94
- | `~/.cursor/skills` | 仅当 `~/.cursor` 已存在时写入，否则标记 `skipped`（不创建 Agent 根） |
95
- | `~/.claude/skills` | 仅当 `~/.claude` 已存在 |
96
- | `~/.codex/skills` | 仅当 `~/.codex` 已存在 |
91
+ ### 3. 业务 Shortcut
97
92
 
98
- 结果区分 `written` / `skipped` / `failed`；`skipped` 不算失败。还可用 `/skill target add <dir>` 注册自定义目录（强制创建、写入 `config.json` 的 `extraSkillTargets`），`/init` 会一并刷新。豆包本地列表里只应看到 **`sino-bc-cli`**。飞书豆包工作侧还需：技能·连接器 → 管理 → **本地** → 刷新。查看包内技能：`sino-bc-cli /skill`；查看安装目标：`sino-bc-cli /skill target list`。
93
+ 执行器固定按下面顺序走。各条命令只提供「endpoint + 请求体」；能不能发、怎么确认、怎么输出由执行器决定。
99
94
 
100
- > 已安装用户升级请执行 `sino-bc-cli /update`（拉取 latest 并自动 `/init`）。仅刷新技能仍可单独执行 `/init`。
101
-
102
- ### ⑥ 免安装临时执行
103
-
104
- ```bash
105
- npx sino-bc-cli --help
95
+ ```mermaid
96
+ flowchart TD
97
+ A[查找 Shortcut 定义] --> B[解析 flag]
98
+ B --> C[域代码 resolve<br/>得到接口名和请求体]
99
+ C --> D[清单上的风险 / 分页 / 主体标记]
100
+ D --> E{已登录?}
101
+ E -->|否| FAIL1[参数/配置错误 不发请求]
102
+ E -->|是| F{角色是否允许该接口?}
103
+ F -->|否| FAIL1
104
+ F -->|是| G{"--dry-run?"}
105
+ G -->|是| PREP[本地组装 method / URL / 体] --> OUT1[打印预览 结束]
106
+ G -->|否| H{缺主体绑定?}
107
+ H -->|tenant 接口且未成对传入| PROBE[先查可用主体列表]
108
+ PROBE -->|列表空| FAIL2[阻断 不发业务请求]
109
+ PROBE -->|可继续| PREP2[本地组装]
110
+ H -->|已绑定或不需要| PREP2
111
+ PREP2 --> I{"高风险写 且未 --yes?"}
112
+ I -->|是 非 TTY| EXIT10[退出码 10 待确认]
113
+ I -->|是 TTY| ASK[终端询问]
114
+ I -->|否 普通写或读| SEND[发网关请求]
115
+ ASK -->|同意| SEND
116
+ ASK -->|拒绝| FAIL1
117
+ SEND --> PAGE{是否自动翻页}
118
+ PAGE --> FMT[按 --format 输出信封]
106
119
  ```
107
120
 
108
- 注意 `npx` 方式不会持久注册 Agent 技能，需要技能能力时仍请走全局安装 + `/init`。
109
-
110
- ---
111
-
112
- ## 📚 技术栈说明
121
+ 要点：
122
+
123
+ - `--dry-run` 与真实请求做**同一套**本地可组装校验，但不发 HTTP，也不探查主体列表。
124
+ - 只有清单标成高风险写的接口才要 `--yes`；普通写操作直接执行。
125
+ - 没有分页声明却传了翻页参数：直接校验失败，不发请求。
126
+ - 成功看退出码 `0` 或 JSON 的 `ok`，不要看上游业务 `code`。
113
127
 
114
- | 技术/依赖 | 版本要求 | 用途说明 |
115
- | :------------- | :----------- | :------------------------------------------------------ |
116
- | **Node.js** | `>= v24.0.0` | CLI 运行时环境，要求使用 v24 及以上版本 |
117
- | **TypeScript** | `^v5.5.0` | 开发语言，提供静态类型检查和更好的可维护性 |
118
- | **lodash** | `^4.17.21` | 工具函数库，提供对象/数组/字符串处理等高效方法 |
119
- | **dayjs** | `^1.11.11` | 轻量级日期处理库，替代 Moment.js 处理日期时间格式化 |
120
- | **axios** | `^1.7.0` | HTTP 客户端库，用于网络请求、连通性检测等 |
121
- | **chalk** | `^4.1.2` | 终端彩色输出库，用于美化日志和帮助信息 |
122
- | **open** | `^8.4.2` | 跨平台打开浏览器 / 本地文件（OAuth 登录、`/skill` 打开 SKILL.md） |
123
- | **@napi-rs/keyring** | `^2.0.0` | Windows 凭据库与 macOS 主密钥；令牌本体在 macOS/Linux 为 AES 文件 |
124
- | **fs-native-extensions** | `^1.5.1` | 跨进程文件锁（OAuth 刷新） |
125
-
126
- ### 开发依赖
127
-
128
- | 依赖 | 版本 | 用途 |
129
- | :----------------- | :-------- | :-------------------------------- |
130
- | `@types/node` | `^22.0.0` | Node.js 类型声明 |
131
- | `@types/lodash` | `^4.17.5` | lodash 类型声明 |
132
- | `ts-node` | `^10.9.2` | 开发阶段直接运行 TypeScript 代码 |
133
- | `rimraf` | `^5.0.7` | 跨平台目录清理工具，替代 `rm -rf` |
134
- | `esbuild` | `^0.28.2` | 打单文件 `dist/index.js` |
135
- | `javascript-obfuscator` | `^5.6.0` | 构建期轻量混淆 |
136
-
137
- ---
138
-
139
- ## 📁 项目结构说明
140
-
141
- 项目采用 **模块化、低耦合、高内聚** 的分层设计，便于后续扩展和维护。
142
-
143
- ```
144
- sino-bc-cli/
145
- ├── src/ # 源代码目录（TypeScript）
146
- │ ├── index.ts # 🚀 CLI 入口文件，bin 关联点
147
- │ │
148
- │ ├── core/ # 🧠 核心模块层
149
- │ │ ├── index.ts # 核心模块统一导出
150
- │ │ ├── cli-app.ts # CLI 应用主类（参数解析、帮助展示、命令分发）
151
- │ │ ├── route.ts # argv 路由（斜杠命令 / 域 + Shortcut）
152
- │ │ └── command-registry.ts # 命令注册器（注册、查找、执行、注销命令）
153
- │ │
154
- │ ├── commands/ # 📦 命令实现层（每命令一个文件，可独立扩展）
155
- │ │ ├── index.ts # 命令批量注册入口
156
- │ │ ├── init.command.ts # /init 命令实现（只注册 Agent 技能）
157
- │ │ ├── update.command.ts # /update 命令实现（装 latest，再用新包入口 /init）
158
- │ │ ├── auth.command.ts # /auth 命令实现（登录 / 状态 / 退出）
159
- │ │ ├── tenant.command.ts # /tenant 命令实现（仅 list）
160
- │ │ ├── schema.command.ts # /schema 命令实现（自省 catalog）
161
- │ │ ├── get-config.command.ts # /get-config 命令实现（查看变量配置）
162
- │ │ ├── set-config.command.ts # /set-config 命令实现（修改变量配置）
163
- │ │ ├── skill.command.ts # /skill 命令实现（列出包内技能或打开 SKILL.md）
164
- │ │ └── uninstall.command.ts # /uninstall 命令实现（清理技能目录与配置并卸载）
165
- │ │
166
- │ ├── shortcuts/ # ⚡ Shortcut 执行面（业务命令，域 + `+cmd`）
167
- │ │ ├── index.ts # 执行器（flag 解析、输出格式、写确认门）
168
- │ │ ├── registry.ts # 各业务域手写命令注册
169
- │ │ ├── raw-api.ts # 各域 api <name> 点名调用
170
- │ │ ├── helpers.ts # 共用接口查找与 flag 读取
171
- │ │ ├── flags.ts # Shortcut 面参数解析（含公共 flag）
172
- │ │ ├── types.ts # Shortcut 声明与执行上下文类型
173
- │ │ └── biz-line/ # biz-line 域
174
- │ │ ├── index.ts # 该域全部 Shortcut 登记处
175
- │ │ ├── read.ts # 只读 Shortcut（+channels/+categories/+list/+strategies）
176
- │ │ ├── write.ts # 写 Shortcut（+save/+update/+status/+delete/+strategy-*）
177
- │ │ └── helpers.ts # 按名解析业务线、字典名称映射等编排
178
- │ │
179
- │ ├── utils/ # 🛠 工具类层（高内聚的可复用工具）
180
- │ │ ├── index.ts # 工具模块统一导出
181
- │ │ ├── logger.ts # 日志工具（多级别彩色输出 + 时间戳）
182
- │ │ ├── browser.ts # 浏览器工具（跨平台 URL 打开，兼容 Win/macOS/Linux）
183
- │ │ ├── crypto.ts # 加密工具（MD5、SHA-256、AES、Base64、签名生成）
184
- │ │ ├── http.ts # HTTP 工具（axios 封装：请求/响应拦截、自动重试）
185
- │ │ ├── gateway-client.ts # 网关调用唯一出口（拼地址、注入鉴权与来源头、解包 result）
186
- │ │ ├── presenter.ts # 输出与退出码（json / table / ndjson / csv，stdout / stderr 分流）
187
- │ │ ├── cli-error.ts # 带分类的 CLI 错误（validation / config / api / 待确认）
188
- │ │ ├── common.ts # 通用工具（日期、深拷贝、防抖节流、ID 生成等）
189
- │ │ ├── prompt.ts # 终端交互（复用单一 readline 会话：提问、选择、确认）
190
- │ │ ├── config-store.ts # 变量配置读写（字段元信息 + 读 / 写 / 删）
191
- │ │ ├── config-prompt.ts # 变量配置交互采集（/set-config）
192
- │ │ └── skill-install.ts # Agent 技能目录的写入与清理
193
- │ │
194
- │ ├── types/ # 📝 类型定义层
195
- │ │ └── index.ts # 全局接口、枚举定义（ICommand、LogLevel 等）
196
- │ │
197
- │ └── constants/ # 🔧 常量配置层
198
- │ └── index.ts # CLI 配置、命令名称、Shortcut 域、默认值
199
- │
200
- ├── skills/ # Agent 技能树（shared + biz-line，含 references）
201
- ├── affordance/ # 各 Shortcut 的 WHEN / 别用 / 示例
202
- ├── tests/ # ✅ 单元测试（node --test + ts-node）
203
- │ ├── helpers/ # HTTP 执行器桩、输出流桩
204
- │ └── *.test.ts # 路由、flag、网关、输出契约、各类 Shortcut
205
- │
206
- ├── dist/ # 📤 构建输出目录（构建后自动生成）
207
- │ └── ... # 单文件混淆压缩产物 + SKILL.md + skills/ + affordance/ + api-doc（不含 SourceMap）
208
- │
209
- ├── package.json # 📄 项目配置（依赖、脚本、bin 命令）
210
- ├── tsconfig.json # 📄 TypeScript 编译配置
211
- ├── .gitignore # 📄 Git 忽略配置
212
- └── README.md # 📖 项目说明文档
213
- ```
214
-
215
- ### 架构设计原则
216
-
217
- 1. **分层清晰**：`core → commands → utils → types/constants`，上层依赖下层，单向依赖无循环
218
- 2. **低耦合**：命令之间互相独立，通过注册器统一管理；新增命令只需在 `commands/` 下新建文件并加入 `commands/index.ts` 数组
219
- 3. **高内聚**：每个工具类只负责单一职责（如 `BrowserUtils` 只处理浏览器打开，`CryptoUtils` 只处理加解密）
220
- 4. **可扩展**：
221
- - 新增命令：实现 `ICommand` 接口 → 放入 `commands/index.ts` 数组即可自动注册
222
- - 新增工具：在 `utils/` 下新建类，通过 `utils/index.ts` 导出
223
- - 命令注册器支持运行时动态注册/注销命令
224
-
225
- ---
226
-
227
- ## 🚀 项目使用说明
228
-
229
- ### 1. 环境要求
230
-
231
- 确保已安装 **Node.js v24** 或更高版本：
128
+ ## 安装
232
129
 
233
130
  ```bash
234
- # 查看 Node.js 版本
235
- node -v
236
- # 要求输出 v24.x.x 或更高
237
-
238
- # 查看 npm 版本
239
- npm -v
240
- ```
241
-
242
- > 如果 Node.js 版本不符合要求，建议通过 [nvm (Node Version Manager)](https://github.com/nvm-sh/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 进行安装和版本管理。
243
-
244
- ### 2. 安装依赖
245
-
246
- 在项目根目录下执行：
247
-
248
- ```bash
249
- npm install
250
- ```
251
-
252
- 依赖安装完成后，`node_modules/` 目录将生成。
253
-
254
- ### 3. 编译项目
255
-
256
- 项目使用 TypeScript 编写，需要编译为 JavaScript 后才能运行：
257
-
258
- ```bash
259
- # 编译（生成 dist/ 目录）
260
- npm run build
261
-
262
- # 清理旧的编译产物并重新编译
263
- npm run rebuild
264
- ```
265
-
266
- 编译完成后，`dist/` 目录将包含：
267
-
268
- - `*.js` — 编译后的 JavaScript 代码
269
- - `*.d.ts` — TypeScript 类型声明文件
270
- - `*.js.map` — SourceMap 调试映射文件
271
-
272
- ### 4. 开发模式（免编译运行）
273
-
274
- 开发阶段可使用 `ts-node` 直接运行 TypeScript 代码，无需手动编译：
275
-
276
- ```bash
277
- # 直接运行 TypeScript 源码
278
- npm run dev -- [参数]
279
-
280
- # 示例：查看帮助
281
- npm run dev -- --help
282
-
283
- # 示例：执行业务命令
284
- npm run dev -- biz-line +list --name <业务线名称>
285
- ```
286
-
287
- ### 4.1 运行测试
288
-
289
- 单元测试用 Node 内置 runner（`node --test`）配 `ts-node`，不额外引入测试框架：
290
-
291
- ```bash
292
- # 跑全部用例
293
- npm test
294
-
295
- # 类型检查（tsc --noEmit）
296
- npm run typecheck
297
- ```
298
-
299
- 用例放在 `tests/`，通过注入 HTTP 执行器桩断言请求，不产生真实网络调用。
300
-
301
- ### 5. 全局安装（推荐）
302
-
303
- 将 CLI 工具链接为全局命令，可在任意目录下直接使用 `sino-bc-cli`：
131
+ # 最新版（推荐）
132
+ npm i sino-bc-cli@latest -g
304
133
 
305
- ```bash
306
- # 方式一：从源码目录全局链接（开发/测试场景）
307
- cd d:\Project\demo\sino-bc-cli
308
- npm run build # 必须先编译
309
- npm link # 全局链接（Windows 下需要管理员权限）
134
+ # 指定版本
135
+ npm i sino-bc-cli@<version> -g
310
136
 
311
- # 方式二：后续发布到 npm 后
312
- npm i sino-bc-cli -g
137
+ # 已安装用户升级（装 latest 并自动 /init）
138
+ sino-bc-cli /update
313
139
  ```
314
140
 
315
- 安装完成后，即可在任意终端直接使用：
316
-
317
141
  ```bash
142
+ sino-bc-cli --version
318
143
  sino-bc-cli --help
319
- sino-bc-cli /init
320
- sino-bc-cli biz-line --help
321
- sino-bc-cli biz-line +list --name <业务线名称>
322
144
  ```
323
145
 
324
- `npm i sino-bc-cli -g` 完成后会自动执行 `/init`：向通过门控的默认目标写入唯一技能 `sino-bc-cli`，并清掉旧的平级 `sino-bc-shared` / `sino-bc-<domain>`。未安装对应 Agent 的目录会 `skipped`。飞书豆包工作：技能·连接器 → 管理 → **本地** → 刷新。若未出现，手动执行：
146
+ 装完会尝试自动 `/init`。技能没出现时再手动执行：
325
147
 
326
148
  ```bash
327
149
  sino-bc-cli /init
328
150
  ```
329
151
 
330
- 自定义安装路径：
331
-
332
- ```bash
333
- sino-bc-cli /skill target add ~/my-agent/skills
334
- sino-bc-cli /skill target list
335
- sino-bc-cli /skill target remove ~/my-agent/skills
336
- ```
337
-
338
- > 卸载：`sino-bc-cli /uninstall --yes`（删技能 + 配置 + 全局 npm 包）；`sino-bc-cli /uninstall --yes --keep-cli` 只保留全局 npm 包，**仍删除**技能与配置。
339
-
340
- ---
341
-
342
- ## 📖 命令说明
343
-
344
- 命令分两类：**生命周期命令**用 `/` 前缀，负责安装与配置；**业务命令**是 Shortcut 执行面，形如 `<域> +<命令>`。
345
-
346
- ### 生命周期命令
347
-
348
- | 命令 | 说明 |
349
- | :---------- | :-------------------------------------------------------------------------------------------- |
350
- | `/init` | 注册唯一技能 `sino-bc-cli` 到通过门控的默认 Agent 目录 + `extraSkillTargets`（整目录重建，不残留旧文件；不碰同级其它技能）；结果区分 written / skipped / failed。不询问、不写入身份令牌 |
351
- | `/update` | 全局安装 `sino-bc-cli@latest`，再用当前 Node 执行新包 `dist/index.js /init`。`--quiet` 抑制 npm 日志并传给该次 `/init`。npm link / 其它全局链接安装拒绝；探测失败则中止，以免覆盖未知安装 |
352
- | `/skill` | 列出包内 Agent 技能；传入 name 打开对应 `SKILL.md`；`target add\|remove\|list` 管理自定义安装目录 |
353
- | `/schema` | 自省 catalog：无参数列出 `name/domain/summary/risk/tenant`；`/schema <name>` 返回 `inputSchema` + `_meta`（含 tenant 与调用级主体参数；始终 JSON，默认不暴露 method/path；仅 high-risk-write 注入确认字段 `yes`） |
354
- | `/get-config` | 查看变量配置；密钥默认打码，`--show-secret` 显示明文，`--json` 输出 JSON |
355
- | `/set-config` | 只写身份令牌；不带参数时逐项交互修改 |
356
- | `/auth` | `status` 查看身份令牌、`authContextId` 与凭证类型（打码展示）；`logout` 清除整份身份面；`login` 发起浏览器设备授权；`keychain-downgrade` 把 macOS 主密钥落到文件；OAuth 令牌到期前自动刷新 |
357
- | `/tenant` | 只支持 `list`；tenant 接口每次调用传入 `--corporation-id` 与 `--auth-context-id` |
358
- | `/uninstall` | 先清身份面，再删除全部默认/自定义目标下的技能目录与 `~/.sino-bc-cli`，并从全局 npm 卸载；`--keep-cli` 仅跳过 npm 卸载（不保留配置与身份面） |
359
-
360
- ### 业务命令（`biz-line`）
361
-
362
- | 命令 | 说明 |
363
- | :--- | :--- |
364
- | `biz-line +channels` | 查询投放渠道列表（`code` 即业务线里的 `mediaChannelId`） |
365
- | `biz-line +categories` | 查询投放行业与品类字典树 |
366
- | `biz-line +list` | 查询业务线；`--name` / `--id` / `--category`，不传即查全部（`pagination: false`） |
367
- | `biz-line +strategies` | 查周策略与表现；`--name` 会先解析业务线 ID，或传单个 `--id` |
368
- | `biz-line +save` / `+update` / `+status` / `+delete` | ⚠️ 业务线写操作 |
369
- | `biz-line +strategy-save` / `+strategy-update` / `+strategy-delete` | ⚠️ 周策略写操作 |
370
- | `biz-line api <name> --data '<json>'` | 按接口 `name` 点名调用，覆盖导出、对比、消耗等长尾接口 |
371
-
372
- `+list --category` 同时接受数字 ID 与名称；传名称时会先查品类字典再映射，映射不到会报错并列出可选值。`+list` 不再接受 `--channel` / `--industry`。行业 / 品类 Top 没有 Shortcut。
373
-
374
- ### Shortcut 面公共参数
375
-
376
- | 参数 | 说明 |
377
- | :--- | :--- |
378
- | `--format json\|table\|ndjson\|csv` | 输出格式。TTY 默认 `table`，非 TTY 默认 `json`。**无 `pretty`** |
379
- | `--page-all` | 自动翻页直至按 `total` 取尽；仅分页接口可用 |
380
- | `--page-limit <n>` | 翻页页数上限，`0` = 不封顶（**默认不封顶**）；单独出现也会开启翻页 |
381
- | `--page-delay <ms>` | 翻页间隔毫秒（默认 200） |
382
- | `--dry-run` | 走与真实请求相同的本地 dry-run，只打印将要发起的 method / URL / 请求体，不发请求 |
383
- | `--yes` | 跳过写操作确认；本地 dry-run 通过后发起请求。不能绕过 tenant 主体门禁 |
384
- | `--corporation-id` | 本次调用的签约主体 ID；仅 catalog `tenant: true` 的接口需要，不放进 `--data`，不回退全局配置 |
385
- | `--auth-context-id` | 本次调用的认证上下文 ID，须与 `/auth status` 的 `authContextId` 成对；认证变化后必须整组重绑 |
386
-
387
- **格式与形状**：`json` 忠实保留上游形状（分页接口即 `total` + 条目数组）。`ndjson` / `csv` / `table` 面向记录，只认该接口分页 profile 声明的条目字段并下钻逐条渲染；没有该字段就不下钻（不会去猜"哪个数组字段是记录集"，详情类接口常带若干数组字段，猜错会把同级标量字段一起丢了）。`csv` 不会失败——没有记录数组时降级为 `key,value` 两列并按点号路径拍平，方便「查详情」也进表格工具。
388
-
389
- 单页调用若上游报告的总数大于本页条数，非 `json` 格式会向 stderr 提示「未取全，加 `--page-all`」；`json` 的 `data` 本身带总数，不额外提示。
390
-
391
- **自动翻页**：默认仍是单页，只有显式传 `--page-all` 或 `--page-limit` 才翻页。
392
-
393
- 能否翻页由接口在 OpenAPI 上的 `x-cli-pagination` 声明，同步期把字段名钉进 catalog，运行时不猜形状。网关上并存两套写法，CLI 都支持：
394
-
395
- | 请求字段 | 响应条目字段 | 典型接口 |
396
- | :--- | :--- | :--- |
397
- | `pageNum` / `pageSize` | `result` | `biz-line-list`、`biz-line-strategy-list`、`optimize-project-query-by-page` |
398
- | `page` / `size` | `data` | Facebook / Google / TikTok 的 `dimension`、`metrics` 列表 |
399
-
400
- 页码从 1 递增，页大小未传时 CLI 注入默认值。停止条件为「本页为空 / 累计条数达到 `total` / 达到显式页数上限 / 触及单次拉取硬上限 100 万条」——最后一条是给「上游忽略页码、每页返回同一批数据」这种异常场景的兜底，不影响正常接口。
401
-
402
- ```bash
403
- # 取尽（默认不封顶）
404
- sino-bc-cli biz-line api optimize-project-query-by-page --page-all --data '{"pageSize":100}'
405
- # 只抽前两页看看
406
- sino-bc-cli biz-line api optimize-project-query-by-page --page-limit 2
407
- ```
408
-
409
- 翻页成功时 `data` 保持单页调用的对象形状（条目字段替换为拼接后的全部条目），`meta` 额外给出 `count` / `pages` / `total`；只有显式传了 `--page-limit` 且被截断时 `meta.truncated` 才为 `true` 并在 stderr 提示——**看到 `truncated` 就说明数据不全**，请加大或去掉 `--page-limit`。
410
-
411
- 两类接口不能翻页，传分页 flag 会以 `validation` 失败且**不发起请求**：写操作（重复请求不可逆），以及 catalog 未声明分页的接口。用 `sino-bc-cli /schema <name>` 看 `_meta.pagination` 即可判断某接口能否翻页。
412
-
413
- 手写 Shortcut（`+list` / `+strategies`）默认请求体带 `pagination: false`（服务端一次返回全量）；传 `--page-all` / `--page-limit` 时 CLI 会去掉该字段并注入页码字段按页翻页。
152
+ `/init` 只注册技能，不写入令牌。技能落在各 Agent 目录下的 `sino-bc-cli/`（`~/.agents/skills` 始终写；Cursor / Claude / Codex 仅在对应 Agent 根已存在时写）。飞书豆包：技能·连接器 → 管理 → **本地** → 刷新。
414
153
 
415
- ### 输出契约与退出码
416
-
417
- 非 TTY（管道 / CI / Agent）默认输出 JSON 信封。成功走 stdout，失败走 stderr：
418
-
419
- ```json
420
- { "ok": true, "command": "biz-line +list", "data": [], "meta": { "count": 0 } }
421
- { "ok": false, "command": "biz-line +delete", "error": { "type": "confirmation_required", "message": "...", "hint": "..." } }
422
- ```
154
+ 命令找不到：`npm prefix -g` 把全局 bin 加入 `PATH` 后重开终端。临时试跑（不注册技能）：`npx sino-bc-cli --help`。
423
155
 
424
- `data` 只包含上游 `result`；`meta.count` 恒为主记录数组的长度，与是否翻页无关。**判断成功请看 `ok` 或进程退出码，不要看上游 `code`。**
156
+ 上手顺序：安装 → `/init` → `/auth login` → 需要主体时 `/tenant list` → 业务命令或 `/schema`。
425
157
 
426
- 失败信封**恒为 JSON 且恒走 stderr**，与 `--format` 无关：失败的首要消费者是 Agent，契约不随渲染格式分叉。
158
+ Agent 使用时读本机 `sino-bc-cli/SKILL.md`，再按意图读一份域技能。仓库开发看源码根目录 `AGENTS.md`（不随 npm 包分发）。
427
159
 
428
- | 退出码 | 含义 |
429
- | :----- | :--- |
430
- | `0` | 成功 |
431
- | `2` | 调用方参数或配置有误（`error.type` 为 `validation` / `config`）——**改命令再试**，重试原命令没用 |
432
- | `10` | 写操作待确认，**不是错误**；向用户确认后在原命令末尾追加 `--yes` 重试 |
433
- | `1` | 上游网关或业务接口失败（`error.type` 为 `api`）——可重试或告知用户 |
160
+ ## 斜杠命令
434
161
 
435
- ### 变量配置文件
436
-
437
- 身份令牌（`authToken`，即网关鉴权用的 JWT）存于平台密钥存储：macOS/Linux 为 `~/.sino-bc-cli/secrets/` 下的 AES-256-GCM 密文，Windows 为当前用户凭据库；均不写入 `config.json` 明文。`X-GATEWAY-TYPE` 固定为 `A2C-CLI`，不开放配置。可写配置为身份令牌与 `gateway-url`；签约主体是调用级参数。写配置时删除磁盘旧键 `env` / `apifoxToken` / `corporationId`。
438
-
439
- | 字段 | 命令行键名 | 默认值 | 说明 |
440
- | :--- | :--------- | :----- | :--- |
441
- | `authToken` | `auth-token` | 无内置默认值 | 网关鉴权用的身份令牌（JWT，业务命令使用）；不同身份（公司人员 / 客户 / 内部应用）持有各自的令牌；存于平台密钥存储 |
442
- | `gatewayUrl` | `gateway-url` | `https://agent.beyondclick.com` | 业务与认证共用的网关根；合法 http/https 绝对 URL，可带 path 前缀 |
443
- | （调用级主体） | `--corporation-id` / `--auth-context-id` | 每次调用显式传入 | 仅 `x-cli-tenant` 接口需要；`/auth status` 取认证上下文，`/tenant list` 查可用主体 |
162
+ | 命令 | 做什么 |
163
+ | --- | --- |
164
+ | `/init` | 把 Agent 技能写到本机目标目录 |
165
+ | `/update` | 升级到 npm latest，再执行一次 `/init` |
166
+ | `/skill` | 列出入口技能；`/skill <name>` 打开说明；`target add\|list\|remove` 管理额外安装目录 |
167
+ | `/schema` | 列出可调接口；`/schema <name>` 看入参 |
168
+ | `/get-config` | 查看配置（令牌默认打码，`--show-secret` 明文） |
169
+ | `/set-config` | 写访问令牌或网关地址 |
170
+ | `/auth` | `login` 浏览器登录；`status` 查看身份；`logout` 退出 |
171
+ | `/tenant` | 仅 `list`：列出当前身份可用的签约主体 |
172
+ | `/uninstall` | 清理技能、本机配置和身份；默认同时卸载全局包 |
444
173
 
445
174
  ```bash
446
- # 查看（密钥打码）
175
+ sino-bc-cli /init
176
+ sino-bc-cli /skill
177
+ sino-bc-cli /skill target add ~/my-agent/skills
178
+ sino-bc-cli /auth login
179
+ sino-bc-cli /auth status
180
+ sino-bc-cli /tenant list
181
+ sino-bc-cli /schema
182
+ sino-bc-cli /schema biz-line-list
447
183
  sino-bc-cli /get-config
448
-
449
- # 不带参数则逐项交互修改；访问令牌处回车保留现有凭证
450
- sino-bc-cli /set-config
451
-
452
- # 手动配置访问令牌；刷新令牌可省略
453
184
  sino-bc-cli /set-config auth-token <AT>
454
- sino-bc-cli /set-config auth-token <AT> <RT>
455
- # 改网关（与当前不同则清除凭证，须重新 /auth login）
456
185
  sino-bc-cli /set-config gateway-url https://agent.beyondclick.com
457
- sino-bc-cli /auth status
458
- sino-bc-cli /auth logout
459
-
460
- # 客户身份下查询可用主体；每次 tenant 调用显式传入主体与认证上下文
461
- sino-bc-cli /auth status
462
- sino-bc-cli /tenant list
186
+ sino-bc-cli /update
187
+ sino-bc-cli /uninstall --yes
463
188
  ```
464
189
 
465
- > `/init` 只注册技能，不询问、不写入身份令牌。登录用 `/auth login`，手动令牌用 `/set-config auth-token <AT> [RT]`。维护者同步接口文档请设置环境变量 `APIFOX_TOKEN`，不要写入用户配置。
466
-
467
- ### 全局选项
468
-
469
- | 选项 | 短选项 | 说明 |
470
- | :---------- | :----- | :---------------------------------------- |
471
- | `--version` | `-v` | 显示版本信息 |
472
- | `--help` | `-h` | 显示帮助信息 |
473
- | `--debug` | `-d` | 启用 Debug 日志模式，输出更详细的运行信息 |
474
-
475
- ### 环境与请求网关
476
-
477
- 业务与认证请求的根地址取生效 `gateway-url`（缺省 [`src/constants/gateway.ts`](./src/constants/gateway.ts) 的 `DEFAULT_GATEWAY_BASE_URL`），统一走 `joinGatewayUrl(path)` 拼接，由 [`src/shared/gateway-client.ts`](./src/shared/gateway-client.ts) 与 OAuth 客户端发出。`path` 等于接口文档 / OpenAPI / catalog 路由（带 `/sino-opti-hive` 则原样保留）。
190
+ 需要签约主体的接口，把 `/tenant list` 的主体 ID 和 `/auth status` 的认证上下文成对传入 `--corporation-id`、`--auth-context-id`。
478
191
 
479
- | 说明 | 网关地址 |
480
- | :--- | :--- |
481
- | 缺省生产网关 | `https://agent.beyondclick.com` |
192
+ ## 调用样例
482
193
 
483
- > 改地址：`sino-bc-cli /set-config gateway-url <URL>`。归一化后与当前不同会清除身份凭证。
484
-
485
- ### 使用示例
486
-
487
- #### ① 查看版本和帮助
488
-
489
- ```bash
490
- # 查看版本号
491
- sino-bc-cli --version
492
- sino-bc-cli -v
493
-
494
- # 查看帮助文档（含所有可用命令列表）
495
- sino-bc-cli --help
496
- sino-bc-cli -h
497
- ```
498
-
499
- #### ② 查看某域何时用哪条命令
194
+ 业务命令：`<域> +<命令>`；长尾：`<域> api <name> --data '<json>'`。先看帮助。
500
195
 
501
196
  ```bash
502
197
  sino-bc-cli biz-line --help
503
- ```
504
-
505
- 接口字段口径见 [`src/api-doc/README.md`](./src/api-doc/README.md)。
506
-
507
- #### ③ 查询业务线数据
508
-
509
- ```bash
510
- # 按名称查业务线
511
198
  sino-bc-cli biz-line +list --name <业务线名称>
199
+ sino-bc-cli project-analysis +summary --month 2026-08
200
+ sino-bc-cli user +sso-info --data '{"userId":123}'
512
201
 
513
- # 按品类筛选（接受名称或 ID）
514
- sino-bc-cli biz-line +list --category <品类>
515
-
516
- # 查某条业务线的周策略与表现
517
- sino-bc-cli biz-line +strategies --name <业务线名称>
518
-
519
- # 没有 Shortcut 的长尾接口
520
- sino-bc-cli biz-line api biz-line-strategy-compare \
521
- --data '{"bizLineId":123,"currentId":2,"prevId":1}'
522
- ```
523
-
524
- 执行效果：向配置文件指定环境的网关发起请求，路径等于接口文档路由，自动注入 `Authorization` 与 `X-GATEWAY-TYPE: A2C-CLI`。接口清单见 [`src/api-doc/README.md`](./src/api-doc/README.md)。
525
-
526
- #### ④ 执行写操作（需确认）
527
-
528
- ```bash
529
- # 先预览请求，不会真正发起
530
- sino-bc-cli biz-line +status --id 123 --status 3 --dry-run
531
-
532
- # 确认无误后追加 --yes
533
- sino-bc-cli biz-line +status --id 123 --status 3 --yes
534
- ```
535
-
536
- > ⚠️ 写操作会变更线上数据。不加 `--yes` 时：交互式终端会展示环境与关键参数并询问；非交互式环境以退出码 `10` 返回 `confirmation_required`，需人工确认后再重试。
537
-
538
- #### ⑤ 启用 Debug 模式运行
539
-
540
- ```bash
541
- sino-bc-cli --debug biz-line --help
542
- # 或使用短选项
543
- sino-bc-cli -d biz-line --help
544
- ```
545
-
546
- Debug 模式会输出详细的日志，包括参数解析、命令注册、接口调用过程等信息，便于排查问题。
547
-
548
- ---
549
-
550
- ## 🌐 跨平台兼容性
551
-
552
- 本工具已针对以下操作系统进行兼容性处理：
553
-
554
- | 操作系统 | 测试状态 | 打开浏览器方式 |
555
- | :--------------------------- | :------- | :----------------------------------------------------------------- |
556
- | **Windows** (10/11) | ✅ 支持 | 使用 `cmd /c start "" "url"`，已处理 URL 中 `&`/`^` 等特殊字符转义 |
557
- | **macOS** | ✅ 支持 | 使用系统 `open` 命令 |
558
- | **Linux** (Ubuntu/CentOS 等) | ✅ 支持 | 使用 `xdg-open` 命令 |
202
+ sino-bc-cli organization +info \
203
+ --corporation-id <主体ID> \
204
+ --auth-context-id <认证上下文ID>
559
205
 
560
- > 所有平台均通过 Node.js 内置 `child_process.exec` 调用，**不依赖任何 native 模块**，确保跨平台一致性。
561
-
562
- ---
563
-
564
- ## 📦 NPM 脚本说明
565
-
566
- 在 `package.json` 中预定义了以下脚本：
567
-
568
- ```bash
569
- # 编译 TypeScript 为 JavaScript（输出到 dist/）
570
- npm run build
571
-
572
- # 类型检查（不产出文件）
573
- npm run typecheck
574
-
575
- # 跑单元测试
576
- npm test
577
-
578
- # 开发模式：直接运行 TypeScript 源码（ts-node）
579
- npm run dev -- [参数]
580
-
581
- # 运行已编译的 CLI（需要先 build）
582
- npm start -- [参数]
583
-
584
- # 清理编译产物（删除 dist/ 目录）
585
- npm run clean
586
-
587
- # 清理后重新编译
588
- npm run rebuild
206
+ sino-bc-cli biz-line +list --name <业务线名称> --dry-run
589
207
  ```
590
208
 
591
- ---
592
-
593
- ## 🔧 扩展新命令（开发者指南）
594
-
595
- 仓库开发统一使用 [bc-develop](.cursor/skills/bc-develop/SKILL.md)。Cursor 输入 `/bc-develop` 只打开该技能；任务不明会先询问。任务入口为 `/bc-develop-api`、`/bc-develop-commands`、`/bc-develop-skills`、`/bc-develop-review`、`/bc-develop-verify`、`/bc-develop-maintain`、`/bc-develop-merge`，均读取同一技能。改了会进仓库的文件后必须走 `/bc-develop-review`，不要实现完就停。
596
-
597
- 一对一接口由 catalog 生成命令；有名称解析、月份筛选等便利能力才增加 `src/shortcuts/<domain>/` 手写实现，并由通用 registry 聚合。根索引标签在 `src/catalog/sync/business-info.json`，详细口径放 `src/catalog/sync/domains/`；同步统一生成接口文档、域入口、帮助与根索引。
598
-
599
- 维护者执行 `npm run sync-api-doc` 从 Apifox 自动发现并同步全部模块。token 只取环境变量 `APIFOX_TOKEN`，不写入仓库或用户配置。详细开发入口见 [如何添加功能](developer-doc/02-handbook-add-feature.md)。
600
-
601
- ---
602
-
603
- ## 📄 License
604
-
605
- MIT License
606
-
607
-
608
- ### 浏览器设备授权
609
-
610
- 执行 `sino-bc-cli /auth login`，在自动打开的浏览器中确认授权。终端每 3 秒等待一次授权结果，没有固定总等待时限；按 Ctrl+C 可取消。成功后进度流提示「授权成功，本机身份已就绪」，不回显令牌。AT、RT、到期时间写入平台密钥存储，普通配置文件不保存凭证。凭证与环境无关。业务请求在 AT 剩余时间不超过 5 分钟时自动刷新；RT 过期或失效时清除对应凭证并要求重新登录。暂时的网络或服务错误不会清除凭证。macOS 无图形会话时可用 `/auth keychain-downgrade` 把主密钥落到文件。
611
-
612
- `/auth status` 默认打码展示 AT，并给出 JWT `userType` 与已缓存的 `sso` / `system` / `passport`（passport 为按主体 ID 分槽的 map，没有当前主体）。资料缓存在配置目录的 `identity-cache.json`（权限 `0o600`），不进 `config.json`、不进密钥存储，也不得用来填充 `--corporation-id`。`/auth logout` 清除整份身份面、删除该缓存，并取消仍在等待的旧登录。`/set-config auth-token <AT> [<RT>]` 写成手动凭证；省略 RT 则刷新令牌为空。带 RT 的手动凭证在 JWT 即将到期时也会走刷新。并发进程通过本地锁协调刷新，过时的网络响应不会覆盖手动配置、退出或新登录。
209
+ 样例中的 ID 只说明参数形状，不要当成真实数据去请求。
613
210
 
614
- 认证与业务共用生效 `gateway-url`（缺省 `https://agent.beyondclick.com`）。认证请求不跟随重定向。确认页打开服务端返回的 `verificationUrl` 原值。
211
+ ## License
615
212
 
616
- 查询参数同样用 `--data` 传入；上传接口的文件字段填写本地文件路径。具体用法见 [查询参数与文件上传](developer-doc/06-request-input.md)。交互配置令牌时直接回车会保留整套 OAuth 凭证。
213
+ MIT