sino-bc-cli 1.8.9 → 1.8.11

package/README.md

@@ -84,9 +84,20 @@ npm ls -g --depth=0 sino-bc-cli   # 确认全局安装的版本
 sino-bc-cli /init
 ```
 
-`/init` 会把根 `SKILL.md` 与 `skills/oapi/`、`skills/custom/`、`skills/default/` 下的标准子技能（`SKILL.md` + `references/`，同路径以后写的层为准）嵌进 `~/.agents/skills/sino-bc-cli/`，不出现 `oapi/` / `custom/` / `default/` 这一层；同时删除旧的平级 `sino-bc-shared` / `sino-bc-<domain>` 技能目录。豆包本地列表里只应看到 **`sino-bc-cli`**。飞书豆包工作侧还需：技能·连接器 → 管理 → **本地** → 刷新。查看包内技能：`sino-bc-cli /skill`。
+`/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>` 技能目录。
 
-> 每次升级版本后请重新执行一次 `sino-bc-cli /init`，以刷新本地技能文件。
+**默认安装目标（带门控）：**
+
+| 目标 | 门控 |
+| :--- | :--- |
+| `~/.agents/skills` | 始终创建并写入（飞书豆包 / 通用） |
+| `~/.cursor/skills` | 仅当 `~/.cursor` 已存在时写入，否则标记 `skipped`（不创建 Agent 根） |
+| `~/.claude/skills` | 仅当 `~/.claude` 已存在 |
+| `~/.codex/skills` | 仅当 `~/.codex` 已存在 |
+
+结果区分 `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`。
+
+> 已安装用户升级请执行 `sino-bc-cli /update`（拉取 latest 并自动 `/init`）。仅刷新技能仍可单独执行 `/init`。
 
 ### ⑥ 免安装临时执行
 
@@ -107,10 +118,10 @@ npx sino-bc-cli --help
 | **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 打开工具（兼容备用方案）                 |
+| **open**       | `^8.4.2`     | 跨平台打开浏览器 / 本地文件（OAuth 登录、`/skill` 打开 SKILL.md） |
+| **@napi-rs/keyring** | `^2.0.0` | Windows 凭据库与 macOS 主密钥；令牌本体在 macOS/Linux 为 AES 文件 |
+| **fs-native-extensions** | `^1.5.1` | 跨进程文件锁（OAuth 刷新） |
 
 ### 开发依赖
 
@@ -118,9 +129,10 @@ npx sino-bc-cli --help
 | :----------------- | :-------- | :-------------------------------- |
 | `@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` |
+| `esbuild`          | `^0.28.2` | 打单文件 `dist/index.js`          |
+| `javascript-obfuscator` | `^5.6.0` | 构建期轻量混淆 |
 
 ---
 
@@ -141,22 +153,27 @@ sino-bc-cli/
 │   │
 │   ├── commands/                 # 📦 命令实现层（每命令一个文件，可独立扩展）
 │   │   ├── index.ts              # 命令批量注册入口
-│   │   ├── init.command.ts       # /init 命令实现（注册 Agent 技能 + 初始化变量配置）
-│   │   ├── bc-api.command.ts     # /bc-api 已下线，仅打印迁移提示并非 0 退出
+│   │   ├── init.command.ts       # /init 命令实现（只注册 Agent 技能）
+│   │   ├── update.command.ts     # /update 命令实现（装 latest，再用新包入口 /init）
+│   │   ├── auth.command.ts       # /auth 命令实现（登录 / 状态 / 退出）
+│   │   ├── tenant.command.ts     # /tenant 命令实现（仅 list）
+│   │   ├── schema.command.ts     # /schema 命令实现（自省 catalog）
 │   │   ├── 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 解析、输出格式、写确认门）
+│   │   ├── index.ts              # 执行器（flag 解析、输出格式、写确认门）
+│   │   ├── registry.ts           # 各业务域手写命令注册
+│   │   ├── raw-api.ts            # 各域 api <name> 点名调用
+│   │   ├── helpers.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/                    # 🛠 工具类层（高内聚的可复用工具）
@@ -166,12 +183,12 @@ sino-bc-cli/
 │   │   ├── crypto.ts             # 加密工具（MD5、SHA-256、AES、Base64、签名生成）
 │   │   ├── http.ts               # HTTP 工具（axios 封装：请求/响应拦截、自动重试）
 │   │   ├── gateway-client.ts     # 网关调用唯一出口（拼地址、注入鉴权与来源头、解包 result）
-│   │   ├── presenter.ts          # 输出与退出码（table / JSON 信封，stdout / stderr 分流）
+│   │   ├── presenter.ts          # 输出与退出码（json / table / ndjson / csv，stdout / stderr 分流）
 │   │   ├── cli-error.ts          # 带分类的 CLI 错误（validation / config / api / 待确认）
 │   │   ├── common.ts             # 通用工具（日期、深拷贝、防抖节流、ID 生成等）
 │   │   ├── prompt.ts             # 终端交互（复用单一 readline 会话：提问、选择、确认）
 │   │   ├── config-store.ts       # 变量配置读写（字段元信息 + 读 / 写 / 删）
-│   │   ├── config-prompt.ts      # 变量配置交互采集（/init 与 /set-config 共用）
+│   │   ├── config-prompt.ts      # 变量配置交互采集（/set-config）
 │   │   └── skill-install.ts      # Agent 技能目录的写入与清理
 │   │
 │   ├── types/                    # 📝 类型定义层
@@ -304,13 +321,21 @@ 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>`。飞书豆包工作：技能·连接器 → 管理 → **本地** → 刷新。若未出现，手动执行：
+`npm i sino-bc-cli -g` 完成后会自动执行 `/init`：向通过门控的默认目标写入唯一技能 `sino-bc-cli`，并清掉旧的平级 `sino-bc-shared` / `sino-bc-<domain>`。未安装对应 Agent 的目录会 `skipped`。飞书豆包工作：技能·连接器 → 管理 → **本地** → 刷新。若未出现，手动执行：
 
 ```bash
 sino-bc-cli /init
 ```
 
-> 卸载全局链接：`npm unlink` 或 `npm uninstall -g sino-bc-cli`
+自定义安装路径：
+
+```bash
+sino-bc-cli /skill target add ~/my-agent/skills
+sino-bc-cli /skill target list
+sino-bc-cli /skill target remove ~/my-agent/skills
+```
+
+> 卸载：`sino-bc-cli /uninstall --yes`（删技能 + 配置 + 全局 npm 包）；`sino-bc-cli /uninstall --yes --keep-cli` 只保留全局 npm 包，**仍删除**技能与配置。
 
 ---
 
@@ -322,12 +347,15 @@ sino-bc-cli /init
 
 | 命令        | 说明                                                                                          |
 | :---------- | :-------------------------------------------------------------------------------------------- |
-| `/init`       | 注册唯一技能 `sino-bc-cli` 到 Agent 技能目录（并删除旧平级 `sino-bc-shared` / `sino-bc-<domain>`），交互设置环境 / `API_KEY` / `APIFOX_TOKEN` |
-| `/skill`      | 列出包内 Agent 技能；传入 name 打开对应 `SKILL.md` |
+| `/init`       | 注册唯一技能 `sino-bc-cli` 到通过门控的默认 Agent 目录 + `extraSkillTargets`（整目录重建，不残留旧文件；不碰同级其它技能）；结果区分 written / skipped / failed。不询问、不写入身份令牌 |
+| `/update`     | 全局安装 `sino-bc-cli@latest`，再用当前 Node 执行新包 `dist/index.js /init`。`--quiet` 抑制 npm 日志并传给该次 `/init`。npm link / 其它全局链接安装拒绝；探测失败则中止，以免覆盖未知安装 |
+| `/skill`      | 列出包内 Agent 技能；传入 name 打开对应 `SKILL.md`；`target add\|remove\|list` 管理自定义安装目录 |
+| `/schema`     | 自省 catalog：无参数列出 `name/domain/summary/risk/tenant`；`/schema <name>` 返回 `inputSchema` + `_meta`（含 tenant 与调用级主体参数；始终 JSON，默认不暴露 method/path；仅 high-risk-write 注入确认字段 `yes`） |
 | `/get-config` | 查看变量配置；密钥默认打码，`--show-secret` 显示明文，`--json` 输出 JSON |
-| `/set-config` | 修改变量配置（环境 / API_KEY / 维护者的 `APIFOX_TOKEN`）；不带参数时逐项交互修改环境与 API_KEY；`/set-config APIFOX_TOKEN` 省略取值写入内置默认 |
-| `/uninstall`  | 删除技能目录与变量配置文件，并从全局 npm 卸载本 CLI |
-| `/bc-api`     | **已下线**。只打印迁移提示并非 0 退出，改用 `biz-line +<shortcut>` 或 `biz-line api <name>` |
+| `/set-config` | 只写身份令牌；不带参数时逐项交互修改 |
+| `/auth`       | `status` 查看身份令牌、`authContextId` 与凭证类型（打码展示）；`logout` 清除整份身份面；`login` 发起浏览器设备授权；`keychain-downgrade` 把 macOS 主密钥落到文件；OAuth 令牌到期前自动刷新 |
+| `/tenant`     | 只支持 `list`；tenant 接口每次调用传入 `--corporation-id` 与 `--auth-context-id` |
+| `/uninstall`  | 先清身份面，再删除全部默认/自定义目标下的技能目录与 `~/.sino-bc-cli`，并从全局 npm 卸载；`--keep-cli` 仅跳过 npm 卸载（不保留配置与身份面） |
 
 ### 业务命令（`biz-line`）
 
@@ -347,55 +375,94 @@ sino-bc-cli /init
 
 | 参数 | 说明 |
 | :--- | :--- |
-| `--format json\|table` | 输出格式。TTY 默认 `table`，非 TTY 默认 `json` |
+| `--format json\|table\|ndjson\|csv` | 输出格式。TTY 默认 `table`，非 TTY 默认 `json`。**无 `pretty`** |
+| `--page-all` | 自动翻页直至按 `total` 取尽；仅分页接口可用 |
+| `--page-limit <n>` | 翻页页数上限，`0` = 不封顶（**默认不封顶**）；单独出现也会开启翻页 |
+| `--page-delay <ms>` | 翻页间隔毫秒（默认 200） |
 | `--dry-run` | 走与真实请求相同的本地 dry-run，只打印将要发起的 method / URL / 请求体，不发请求 |
-| `--yes` | 跳过写操作确认；本地 dry-run 通过后发起请求 |
+| `--yes` | 跳过写操作确认；本地 dry-run 通过后发起请求。不能绕过 tenant 主体门禁 |
+| `--corporation-id` | 本次调用的签约主体 ID；仅 catalog `tenant: true` 的接口需要，不放进 `--data`，不回退全局配置 |
+| `--auth-context-id` | 本次调用的认证上下文 ID，须与 `/auth status` 的 `authContextId` 成对；认证变化后必须整组重绑 |
+
+**格式与形状**：`json` 忠实保留上游形状（分页接口即 `total` + 条目数组）。`ndjson` / `csv` / `table` 面向记录，只认该接口分页 profile 声明的条目字段并下钻逐条渲染；没有该字段就不下钻（不会去猜"哪个数组字段是记录集"，详情类接口常带若干数组字段，猜错会把同级标量字段一起丢了）。`csv` 不会失败——没有记录数组时降级为 `key,value` 两列并按点号路径拍平，方便「查详情」也进表格工具。
+
+单页调用若上游报告的总数大于本页条数，非 `json` 格式会向 stderr 提示「未取全，加 `--page-all`」；`json` 的 `data` 本身带总数，不额外提示。
+
+**自动翻页**：默认仍是单页，只有显式传 `--page-all` 或 `--page-limit` 才翻页。
+
+能否翻页由接口在 OpenAPI 上的 `x-cli-pagination` 声明，同步期把字段名钉进 catalog，运行时不猜形状。网关上并存两套写法，CLI 都支持：
+
+| 请求字段 | 响应条目字段 | 典型接口 |
+| :--- | :--- | :--- |
+| `pageNum` / `pageSize` | `result` | `biz-line-list`、`biz-line-strategy-list`、`optimize-project-query-by-page` |
+| `page` / `size` | `data` | Facebook / Google / TikTok 的 `dimension`、`metrics` 列表 |
+
+页码从 1 递增，页大小未传时 CLI 注入默认值。停止条件为「本页为空 / 累计条数达到 `total` / 达到显式页数上限 / 触及单次拉取硬上限 100 万条」——最后一条是给「上游忽略页码、每页返回同一批数据」这种异常场景的兜底，不影响正常接口。
+
+```bash
+# 取尽（默认不封顶）
+sino-bc-cli biz-line api optimize-project-query-by-page --page-all --data '{"pageSize":100}'
+# 只抽前两页看看
+sino-bc-cli biz-line api optimize-project-query-by-page --page-limit 2
+```
+
+翻页成功时 `data` 保持单页调用的对象形状（条目字段替换为拼接后的全部条目），`meta` 额外给出 `count` / `pages` / `total`；只有显式传了 `--page-limit` 且被截断时 `meta.truncated` 才为 `true` 并在 stderr 提示——**看到 `truncated` 就说明数据不全**，请加大或去掉 `--page-limit`。
+
+两类接口不能翻页，传分页 flag 会以 `validation` 失败且**不发起请求**：写操作（重复请求不可逆），以及 catalog 未声明分页的接口。用 `sino-bc-cli /schema <name>` 看 `_meta.pagination` 即可判断某接口能否翻页。
+
+手写 Shortcut（`+list` / `+strategies`）默认请求体带 `pagination: false`（服务端一次返回全量）；传 `--page-all` / `--page-limit` 时 CLI 会去掉该字段并注入页码字段按页翻页。
 
 ### 输出契约与退出码
 
 非 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": "..." } }
+{ "ok": true,  "command": "biz-line +list", "data": [], "meta": { "count": 0 } }
+{ "ok": false, "command": "biz-line +delete", "error": { "type": "confirmation_required", "message": "...", "hint": "..." } }
 ```
 
-`data` 只包含上游 `result`。**判断成功请看 `ok` 或进程退出码，不要看上游 `code`。**
+`data` 只包含上游 `result`；`meta.count` 恒为主记录数组的长度，与是否翻页无关。**判断成功请看 `ok` 或进程退出码，不要看上游 `code`。**
+
+失败信封**恒为 JSON 且恒走 stderr**，与 `--format` 无关：失败的首要消费者是 Agent，契约不随渲染格式分叉。
 
 | 退出码 | 含义 |
 | :----- | :--- |
 | `0` | 成功 |
+| `2` | 调用方参数或配置有误（`error.type` 为 `validation` / `config`）——**改命令再试**，重试原命令没用 |
 | `10` | 写操作待确认，**不是错误**；向用户确认后在原命令末尾追加 `--yes` 重试 |
-| 其他非 0 | 失败，详见 `error.type`（`validation` / `config` / `api`） |
+| `1` | 上游网关或业务接口失败（`error.type` 为 `api`）——可重试或告知用户 |
 
 ### 变量配置文件
 
-环境、`API_KEY` 与维护者用的 `apifoxToken` 存放在 `<用户主目录>/.sino-bc-cli/config.json`。`X-GATEWAY-TYPE` 固定为 `A2C-CLI`，不开放配置。
+身份令牌（`authToken`，即网关鉴权用的 JWT）存于平台密钥存储：macOS/Linux 为 `~/.sino-bc-cli/secrets/` 下的 AES-256-GCM 密文，Windows 为当前用户凭据库；均不写入 `config.json` 明文。`X-GATEWAY-TYPE` 固定为 `A2C-CLI`，不开放配置。可写配置为身份令牌与 `gateway-url`；签约主体是调用级参数。写配置时删除磁盘旧键 `env` / `apifoxToken` / `corporationId`。
 
 | 字段 | 命令行键名 | 默认值 | 说明 |
 | :--- | :--------- | :----- | :--- |
-| `env` | `env` | `prod` | 目标环境，可选 `test` / `pre` / `prod` |
-| `apiKey` | `api-key` | 内置默认 Key | 网关鉴权用的 API Key（业务命令使用） |
-| `apifoxToken` | `apifox-token` / `APIFOX_TOKEN` | 未配置为空；`/init` 或 `/set-config` 省略取值时写入内置默认 | 仅维护者同步接口文档用（`npm run sync-api-doc`），与业务调用无关；`/init` 会询问，裸 `/set-config` 不问 |
+| `authToken` | `auth-token` | 无内置默认值 | 网关鉴权用的身份令牌（JWT，业务命令使用）；不同身份（公司人员 / 客户 / 内部应用）持有各自的令牌；存于平台密钥存储 |
+| `gatewayUrl` | `gateway-url` | `https://agent.beyondclick.com` | 业务与认证共用的网关根；合法 http/https 绝对 URL，可带 path 前缀 |
+| （调用级主体） | `--corporation-id` / `--auth-context-id` | 每次调用显式传入 | 仅 `x-cli-tenant` 接口需要；`/auth status` 取认证上下文，`/tenant list` 查可用主体 |
 
 ```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
-sino-bc-cli /set-config apifox-token <你的 token>
+# 手动配置访问令牌；刷新令牌可省略
+sino-bc-cli /set-config auth-token <AT>
+sino-bc-cli /set-config auth-token <AT> <RT>
+# 改网关（与当前不同则清除凭证，须重新 /auth login）
+sino-bc-cli /set-config gateway-url https://agent.beyondclick.com
+sino-bc-cli /auth status
+sino-bc-cli /auth logout
+
+# 客户身份下查询可用主体；每次 tenant 调用显式传入主体与认证上下文
+sino-bc-cli /auth status
+sino-bc-cli /tenant list
 ```
 
-> `/init` 在非交互环境（npm `postinstall`、CI、Agent 调用）下不提问：已有配置保持，但空的 `apifoxToken` 会补上内置默认；不存在则按默认值创建（含 `APIFOX_TOKEN`）。
+> `/init` 只注册技能，不询问、不写入身份令牌。登录用 `/auth login`，手动令牌用 `/set-config auth-token <AT> [RT]`。维护者同步接口文档请设置环境变量 `APIFOX_TOKEN`，不要写入用户配置。
 
 ### 全局选项
 
@@ -407,15 +474,13 @@ sino-bc-cli /set-config apifox-token <你的 token>
 
 ### 环境与请求网关
 
-业务命令的请求地址由 [`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 / catalog 路由（带 `/sino-opti-hive` 则原样保留）。
+业务与认证请求的根地址取生效 `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` 则原样保留）。
 
-| `ENV`  | 说明     | 网关地址                             |
-| :----- | :------- | :----------------------------------- |
-| `test` | 测试环境 | `https://test-agent.beyondclick.com` |
-| `pre`  | 预发环境 | `https://test-agent.beyondclick.com` |
-| `prod` | 生产环境 | `https://test-agent.beyondclick.com` |
+| 说明 | 网关地址 |
+| :--- | :--- |
+| 缺省生产网关 | `https://agent.beyondclick.com` |
 
-> 当前三环境同一地址。换地址只需改 `GATEWAY_CONFIG`，同时同步 [`SKILL.md`](./SKILL.md) 与 [`src/api-doc/`](./src/api-doc/custom/README.md) 中的示例地址。
+> 改地址：`sino-bc-cli /set-config gateway-url <URL>`。归一化后与当前不同会清除身份凭证。
 
 ### 使用示例
 
@@ -437,7 +502,7 @@ sino-bc-cli -h
 sino-bc-cli biz-line --help
 ```
 
-接口字段口径见 [`src/api-doc/custom/README.md`](./src/api-doc/custom/README.md)。
+接口字段口径见 [`src/api-doc/README.md`](./src/api-doc/README.md)。
 
 #### ③ 查询业务线数据
 
@@ -456,7 +521,7 @@ 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)。
+执行效果：向配置文件指定环境的网关发起请求，路径等于接口文档路由，自动注入 `Authorization` 与 `X-GATEWAY-TYPE: A2C-CLI`。接口清单见 [`src/api-doc/README.md`](./src/api-doc/README.md)。
 
 #### ④ 执行写操作（需确认）
 
@@ -527,63 +592,25 @@ 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/oapi/sino-bc-biz-line` 的意图表、`affordance/biz-line.md` 的 WHEN、`src/api-doc/oapi/` 的字段口径；手写补充放 `skills/default/`、`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 应当带来智能默认值、参数编排或更友好的输出，否则不值得新增。
+仓库开发统一使用 [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`，不要实现完就停。
 
-### B. 新增生命周期命令
+一对一接口由 catalog 生成命令；有名称解析、月份筛选等便利能力才增加 `src/shortcuts/<domain>/` 手写实现，并由通用 registry 聚合。根索引标签在 `src/catalog/sync/business-info.json`，详细口径放 `src/catalog/sync/domains/`；同步统一生成接口文档、域入口、帮助与根索引。
 
-1. **新建命令文件**：在 `src/commands/` 下创建 `xxx.command.ts`
-2. **实现 ICommand 接口**：编写 `name`、`description` 和 `execute()` 方法
-3. **注册命令**：在 `src/commands/index.ts` 的 `commands` 数组中添加实例
+维护者执行 `npm run sync-api-doc` 从 Apifox 自动发现并同步全部模块。token 只取环境变量 `APIFOX_TOKEN`，不写入仓库或用户配置。详细开发入口见 [如何添加功能](developer-doc/02-handbook-add-feature.md)。
 
-### 示例
+---
 
-```typescript
-// src/commands/example.command.ts
-import { ICommand } from "../types";
-import { logger, BrowserUtils } from "../utils";
+## 📄 License
 
-export class ExampleCommand implements ICommand {
-  public readonly name = "example";
-  public readonly description = "示例命令 - 打开示例网站";
+MIT License
 
-  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(), // 新增注册
-];
-```
+执行 `sino-bc-cli /auth login`，在自动打开的浏览器中确认授权。终端每 3 秒等待一次授权结果，没有固定总等待时限；按 Ctrl+C 可取消。成功后进度流提示「授权成功，本机身份已就绪」，不回显令牌。AT、RT、到期时间写入平台密钥存储，普通配置文件不保存凭证。凭证与环境无关。业务请求在 AT 剩余时间不超过 5 分钟时自动刷新；RT 过期或失效时清除对应凭证并要求重新登录。暂时的网络或服务错误不会清除凭证。macOS 无图形会话时可用 `/auth keychain-downgrade` 把主密钥落到文件。
 
-完成后执行 `npm run build` 即可使用 `sino-bc-cli /example`。
+`/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 即将到期时也会走刷新。并发进程通过本地锁协调刷新，过时的网络响应不会覆盖手动配置、退出或新登录。
 
----
-
-## 📄 License
+认证与业务共用生效 `gateway-url`（缺省 `https://agent.beyondclick.com`）。认证请求不跟随重定向。确认页打开服务端返回的 `verificationUrl` 原值。
 
-MIT License
+查询参数同样用 `--data` 传入；上传接口的文件字段填写本地文件路径。具体用法见 [查询参数与文件上传](developer-doc/06-request-input.md)。交互配置令牌时直接回车会保留整套 OAuth 凭证。

package/dist/SKILL.md

@@ -5,9 +5,11 @@ description: >
   投放渠道/品类、业务线列表/详情/状态、周策略增删改查与策略生成、策略周期/消耗/红绿灯、优化项目；
   Facebook / Google / TikTok 广告策略维度（目标、出价、定向等配置分布）
   与广告策略成效（消耗、曝光、点击等）；
-  SSO 组别；以及 /init、/get-config、/set-config。
+  SSO 组别；  以及 /init、/update、/get-config、/set-config、/schema。
+  也用于优化项目月度分析、消耗与工时趋势、优化师人效、Excel 报表导出（project-analysis），
+  以及营销协同项目、阶段、任务、文档、文件、投放数据、看板、飞书消息、组织用户、租户和用户资料接口。
   用户提到业务线、周策略、策略生成、广告结构、广告层级、广告成效、广告策略维度、biz-line、
-  Meta、Facebook、Google、TikTok、sso、sino-opti-hive 时也必须用本技能，不要自己拼 HTTP。
+  Meta、Facebook、Google、TikTok、sso、user、sino-opti-hive、sino-bc-nexus、营销协同时也必须用本技能，不要自己拼 HTTP。
   完整规则在子技能 sino-bc-shared 与 sino-bc-<domain>。
 metadata:
   requires:
@@ -18,66 +20,117 @@ metadata:
 
 用全局 CLI `sino-bc-cli` 查询或操作 BeyondClick。本文件是**唯一对外技能**，也是决策页：按用户意图只读一份子技能，再执行命令。不要自己拼网关 HTTP，也不要一次读完全部子技能。
 
-`/init` 之后本机目录是 `~/.agents/skills/sino-bc-cli/`，子技能嵌在其下（没有 `oapi/` / `custom/` / `default/` 这一层）：
+`/init` 之后本机技能落在各 Agent 的 `skills/sino-bc-cli/`（至少会写 `~/.agents/skills`；Cursor / Claude / Codex 仅在对应 Agent 根已存在时写入）。子技能嵌在其下（没有 `oapi/` / `custom/` / `default/` 这一层）：
 
 ```text
 sino-bc-cli/
-├── SKILL.md                 ← 本文件
-├── sino-bc-shared/          横切：配置、信封、确认门
-├── sino-bc-biz-line/        业务线、周策略、投放渠道/品类、关联项目、广告策略维度与成效
-└── sino-bc-sso/             SSO 组别
+├── SKILL.md                   ← 本文件
+├── sino-bc-shared/            横切：配置、信封、确认门
+├── sino-bc-auth/              身份令牌与浏览器授权
+├── sino-bc-biz-line/          业务线、周策略、投放渠道/品类、广告策略维度与成效
+├── sino-bc-sso/               SSO 组别
+├── sino-bc-tenant/            签约主体
+├── sino-bc-project-analysis/  优化项目月度分析、趋势、人效与导出
+├── sino-bc-project/           营销协同项目、成员、分组、建项字段
+├── sino-bc-project-stage/     营销协同项目阶段
+├── sino-bc-task/              营销协同任务交付闭环
+├── sino-bc-document/          营销协同文档中心与项目文档
+├── sino-bc-file/              营销协同文件上传
+├── sino-bc-delivery/          营销协同投放数据与 Campaign 归集
+├── sino-bc-dashboard/         营销协同看板
+├── sino-bc-im/                营销协同飞书群消息
+├── sino-bc-organization/      组织、团队与当前用户
+└── sino-bc-user/              SSO / 签约主体（租户）用户资料
 ```
 
-## 运行环境
-
-`sino-bc-cli` 装在用户电脑、服务器本机，或被内嵌进 Agent 沙箱，不保证出现在当前默认执行面。先按下表选执行面，找到命令再进入「怎么跑」。
+Agent 读取时用本机实际安装路径（常见为 `~/.agents/skills/sino-bc-cli/`、`~/.cursor/skills/sino-bc-cli/` 等）；也可用 `sino-bc-cli /skill target list` 查看。
 
-| 当前环境 | 怎么拿 CLI |
-| --- | --- |
-| 豆包工作伙伴 | **优先查沙箱外**本机 CLI。本 CLI 装在用户电脑，沙箱镜像里通常没有。 |
-| 其他 Agent 已把本 CLI 内嵌进沙箱 | 在**当前沙箱**直接执行。 |
-| Linux 服务器或未识别环境（走兜底） | **先查沙箱**；沙箱没有再查本机环境。 |
+## 运行环境
 
-对得上前两行就按前两行；认不准时走 Linux 兜底。沙箱里找不到不要在沙箱里 `npm i`，也不要改去拼 HTTP。两边都没有：提示在本机安装 `npm i sino-bc-cli@latest -g`。
+【sino-bc-cli 执行规则（最高优先级，适用于所有环境）】
+1. 所有 sino-bc-cli 操作前，先读取本机已安装的 `sino-bc-cli/` 下对应 SKILL.md（常见路径见上；不确定时先 `sino-bc-cli /skill target list`）。
+2. 统一探测流程（不按环境预设）：
+   ① 先在当前执行面运行 `which sino-bc-cli` 探测：
+    - 存在 → 直接在当前执行面执行命令；
+    - 不存在 → 进入第②步。
+      ② 探测本机：用提权方式（require_escalated）运行 `which sino-bc-cli`：
+    - 存在 → 所有命令一律带 require_escalated 在本机执行；
+    - 不存在 → 提示安装 `npm i sino-bc-cli@latest -g`，不得改用其他方式。
+3. 严禁自行拼 HTTP 调网关；写操作须用户确认后再加 --yes。
+4. 命令失败时：若是沙箱资源类错误（如 Too many open files），等待后重试，不得降级或跳过；其他错误按报错修正。
 
 ## 怎么跑
 
 1. 用 Read 打开 [`sino-bc-shared/SKILL.md`](sino-bc-shared/SKILL.md)：禁止拼 HTTP、成功看 `ok` / 退出码、写操作退出码 10、配置。
 2. 按下表再读**一份**域技能。Shortcut、组参、枚举、长尾 `api <name>` 都在那份里。
 3. 有 Shortcut 用 `sino-bc-cli <domain> +<shortcut>`；没有再用 `sino-bc-cli <domain> api <name> --data '<json>'`。
-4. 写操作先停下确认环境和意图，用户同意后再加 `--yes`。**不要自行补 `--yes`。**
 
-CLI 未安装：`npm i sino-bc-cli@latest -g`（Node.js >= 24）。技能未出现或升级 CLI 后：`sino-bc-cli /init`。
+输入字段先查看 `/schema <name>`：query 参数同样放入 `--data`，由 CLI 编码到 URL；multipart 文件字段填写本地文件路径（如 `"file":"/path/report.pdf"`），CLI 发送文件内容。`--dry-run` 只校验并预览，不上传。
+4. 写操作先停下确认意图，用户同意后再加 `--yes`。**不要自行补 `--yes`。**
+
+CLI 未安装：`npm i sino-bc-cli@latest -g`（Node.js >= 24）。技能未出现：`sino-bc-cli /init`。升级已安装的 CLI：`sino-bc-cli /update`（拉取 latest 并自动 `/init`）。
 
 ## 意图 → 子技能
 
 | 用户在问 | 读 | 命令入口 |
 | --- | --- | --- |
-| 环境、API_KEY、成功/失败怎么看、写操作要不要确认 | [`sino-bc-shared/SKILL.md`](sino-bc-shared/SKILL.md) | `/init` `/get-config` `/set-config` |
+| 身份令牌、网关地址、成功/失败怎么看、写操作要不要确认 | [`sino-bc-shared/SKILL.md`](sino-bc-shared/SKILL.md) | `/auth login` `/set-config auth-token <AT> [RT]` `/get-config` |
+| 浏览器授权登录、身份令牌状态、清除凭证、查询可用签约主体 | 同上 | `/auth login\|status\|logout` `/tenant list` |
 | 投放渠道/品类、业务线列表/详情/状态、周策略增删改查与策略生成、策略周期/消耗/红绿灯、关联项目/优化项目 | [`sino-bc-biz-line/SKILL.md`](sino-bc-biz-line/SKILL.md) | `biz-line +<shortcut>` |
 | Facebook / Google / TikTok 广告策略维度（目标、出价、定向等配置分布）或广告策略成效（消耗、曝光、点击等） | 同上 | `biz-line +<shortcut>`（维度 / 成效） |
 | SSO 组别 | [`sino-bc-sso/SKILL.md`](sino-bc-sso/SKILL.md) | `sso +group-list` |
-
-不要用本技能处理：本仓库源码开发、扩展命令、npm 发版（见仓库 `README.md` / `ReleaseSteps.md`）。
+| 优化项目月度汇总、项目明细、消耗/工时趋势、优化师人效、导出 Excel | [`sino-bc-project-analysis/SKILL.md`](sino-bc-project-analysis/SKILL.md) | `project-analysis +summary` / `+projects` 等 |
+| 营销协同对客项目、成员、分组、建项字段 | [`sino-bc-project/SKILL.md`](sino-bc-project/SKILL.md) | `project api <name>` |
+| 营销协同项目阶段 | [`sino-bc-project-stage/SKILL.md`](sino-bc-project-stage/SKILL.md) | `project-stage api <name>` |
+| 营销协同任务交付闭环、审核/确认/暂停 | [`sino-bc-task/SKILL.md`](sino-bc-task/SKILL.md) | `task api <name>` |
+| 营销协同文档中心、项目文档 | [`sino-bc-document/SKILL.md`](sino-bc-document/SKILL.md) | `document api <name>` |
+| 营销协同文件上传与下载链接 | [`sino-bc-file/SKILL.md`](sino-bc-file/SKILL.md) | `file api <name>` |
+| 营销协同投放数据、Campaign 归集、阶段指标 | [`sino-bc-delivery/SKILL.md`](sino-bc-delivery/SKILL.md) | `delivery api <name>` |
+| 营销协同看板预算分布与时间轴 | [`sino-bc-dashboard/SKILL.md`](sino-bc-dashboard/SKILL.md) | `dashboard api <name>` |
+| 营销协同飞书群消息 | [`sino-bc-im/SKILL.md`](sino-bc-im/SKILL.md) | `im api <name>` |
+| 组织架构、团队成员、登录态当前用户（`organization +info`） | [`sino-bc-organization/SKILL.md`](sino-bc-organization/SKILL.md) | `organization api <name>` |
+| 按 userId 查询 SSO 或签约主体（租户）用户姓名 | [`sino-bc-user/SKILL.md`](sino-bc-user/SKILL.md) | `user +sso-info` / `user +tenant-info`（租户用户 `corporationId` 放 `--data`） |
+
+不要用本技能处理：本仓库源码开发、扩展命令、npm 发版。
 
 ## 子技能索引
 
 Agent 先读子技能 `sino-bc-shared`，再按意图读域技能。
 
 1. 配置、信封、确认门、禁止拼 HTTP：[`sino-bc-shared/SKILL.md`](sino-bc-shared/SKILL.md)（仓库 [`skills/default/sino-bc-shared/SKILL.md`](skills/default/sino-bc-shared/SKILL.md)）
-2. 业务线、周策略生成、广告结构、广告成效：[`sino-bc-biz-line/SKILL.md`](sino-bc-biz-line/SKILL.md)（仓库 [`skills/oapi/sino-bc-biz-line/SKILL.md`](skills/oapi/sino-bc-biz-line/SKILL.md)）
-3. SSO 组别：[`sino-bc-sso/SKILL.md`](sino-bc-sso/SKILL.md)（仓库 [`skills/oapi/sino-bc-sso/SKILL.md`](skills/oapi/sino-bc-sso/SKILL.md)）
-
-安装与刷新（会写入上面列出的子技能到本机 `sino-bc-cli/`，并删除旧的平级 `sino-bc-shared` / `sino-bc-<domain>` 技能目录）：
+2. 身份令牌与浏览器授权：[`sino-bc-auth/SKILL.md`](sino-bc-auth/SKILL.md)（仓库 [`skills/oapi/sino-bc-auth/SKILL.md`](skills/oapi/sino-bc-auth/SKILL.md)）
+3. 业务线、周策略、投放渠道/品类、关联项目、广告策略维度与成效：[`sino-bc-biz-line/SKILL.md`](sino-bc-biz-line/SKILL.md)（仓库 [`skills/oapi/sino-bc-biz-line/SKILL.md`](skills/oapi/sino-bc-biz-line/SKILL.md)）
+4. 营销协同看板：预算分布、项目分布与关键项目时间轴：[`sino-bc-dashboard/SKILL.md`](sino-bc-dashboard/SKILL.md)（仓库 [`skills/oapi/sino-bc-dashboard/SKILL.md`](skills/oapi/sino-bc-dashboard/SKILL.md)）
+5. 营销协同投放数据：Campaign 归集与投放阶段指标：[`sino-bc-delivery/SKILL.md`](sino-bc-delivery/SKILL.md)（仓库 [`skills/oapi/sino-bc-delivery/SKILL.md`](skills/oapi/sino-bc-delivery/SKILL.md)）
+6. 营销协同文档：文档中心与项目文档：[`sino-bc-document/SKILL.md`](sino-bc-document/SKILL.md)（仓库 [`skills/oapi/sino-bc-document/SKILL.md`](skills/oapi/sino-bc-document/SKILL.md)）
+7. 营销协同文件上传与对象存储记录：[`sino-bc-file/SKILL.md`](sino-bc-file/SKILL.md)（仓库 [`skills/oapi/sino-bc-file/SKILL.md`](skills/oapi/sino-bc-file/SKILL.md)）
+8. 营销协同飞书群消息：[`sino-bc-im/SKILL.md`](sino-bc-im/SKILL.md)（仓库 [`skills/oapi/sino-bc-im/SKILL.md`](skills/oapi/sino-bc-im/SKILL.md)）
+9. 组织架构、团队成员与当前用户：[`sino-bc-organization/SKILL.md`](sino-bc-organization/SKILL.md)（仓库 [`skills/oapi/sino-bc-organization/SKILL.md`](skills/oapi/sino-bc-organization/SKILL.md)）
+10. 营销协同项目：生命周期、成员、分组与建项字段：[`sino-bc-project/SKILL.md`](sino-bc-project/SKILL.md)（仓库 [`skills/oapi/sino-bc-project/SKILL.md`](skills/oapi/sino-bc-project/SKILL.md)）
+11. 优化项目月度分析、消耗与工时趋势、优化师人效及 Excel 导出：[`sino-bc-project-analysis/SKILL.md`](sino-bc-project-analysis/SKILL.md)（仓库 [`skills/oapi/sino-bc-project-analysis/SKILL.md`](skills/oapi/sino-bc-project-analysis/SKILL.md)）
+12. 营销协同项目阶段：[`sino-bc-project-stage/SKILL.md`](sino-bc-project-stage/SKILL.md)（仓库 [`skills/oapi/sino-bc-project-stage/SKILL.md`](skills/oapi/sino-bc-project-stage/SKILL.md)）
+13. SSO 组别：[`sino-bc-sso/SKILL.md`](sino-bc-sso/SKILL.md)（仓库 [`skills/oapi/sino-bc-sso/SKILL.md`](skills/oapi/sino-bc-sso/SKILL.md)）
+14. 营销协同任务：交付闭环与操作日志：[`sino-bc-task/SKILL.md`](sino-bc-task/SKILL.md)（仓库 [`skills/oapi/sino-bc-task/SKILL.md`](skills/oapi/sino-bc-task/SKILL.md)）
+15. 签约主体：[`sino-bc-tenant/SKILL.md`](sino-bc-tenant/SKILL.md)（仓库 [`skills/oapi/sino-bc-tenant/SKILL.md`](skills/oapi/sino-bc-tenant/SKILL.md)）
+16. SSO 用户与签约主体（租户）用户资料：[`sino-bc-user/SKILL.md`](sino-bc-user/SKILL.md)（仓库 [`skills/oapi/sino-bc-user/SKILL.md`](skills/oapi/sino-bc-user/SKILL.md)）
+
+安装与刷新：
 
 ```bash
+# 升级已安装的 CLI（装 latest 并自动刷新技能）
+sino-bc-cli /update
+
+# 只刷新本机技能，不改全局包
 sino-bc-cli /init
 sino-bc-cli /skill
+sino-bc-cli /skill target list
 ```
 
-列出包内技能：`sino-bc-cli /skill`（只有这一条）。查看某条命令何时用：`sino-bc-cli biz-line --help`。
-升级 CLI 后请再跑一次 `/init`。
+列出包内技能：`sino-bc-cli /skill`（只有入口这一条）。管理安装目录：`/skill target add|remove|list`。查看某条命令何时用：`sino-bc-cli biz-line --help`。
+不要把 `/update` 和 `/init` 连着跑：升级只用 `/update`。
+
+> 仓库里 `skills/default/` 只留 `sino-bc-shared`。域默认技能在 `skills/oapi/`，由 `npm run sync-api-doc` 整层重写。`skills/custom/` 可空；有同名目录则打包和 `/init` 整份用 custom，不再与 oapi 按文件叠加，且必须自带完整 `SKILL.md`。custom 不能覆盖 `sino-bc-shared`。
+> `/init` 把根 `SKILL.md` 与选定子技能嵌进通过门控的默认目标（`~/.agents/skills` 始终写；Cursor/Claude/Codex 需 Agent 根已存在）以及 `extraSkillTargets`。
+> 上面的索引由同步脚本按 catalog 维护；域中文标签在 `src/catalog/sync/business-info.json`，概念与 HOW 在 `src/catalog/sync/domains/`，不要手改索引或往通用生成器添加业务特例。
 
-> 仓库里子技能分三层：`skills/oapi/sino-bc-<domain>/` 由 `npm run sync-api-doc` **整层重写**（域 `SKILL.md` 不再与旧文件合并）；`skills/default/sino-bc-shared/` 与 `skills/custom/sino-bc-<domain>/references/` 手写且不会被同步覆盖。域 custom 不要放 `SKILL.md`，以免 `/init` 盖掉生成稿。每个子技能都是标准目录：`SKILL.md` + `references/`。
-> `/init` 把根 `SKILL.md` 与各层子技能嵌进 `~/.agents/skills/sino-bc-cli/`。
-> 上面的索引由同步脚本维护，改它请改 `src/api-utils/render-skills.ts`。
+CLI 授权接口出入参采用驼峰；`accessExpiresAt`、`refreshExpiresAt` 为毫秒时间戳。凭证由 CLI 直接保存，Agent 无需自行换算或处理 token。

package/dist/affordance/auth.md

@@ -0,0 +1,27 @@
+# auth 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +code
+
+- **WHEN**：获取授权链接地址
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli auth +code --data '{...}'`
+
+## +exchange
+
+- **WHEN**：获取访问凭证accessToken和刷新凭证refreshToken
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli auth +exchange --data '{...}'`
+
+## +refresh
+
+- **WHEN**：通过刷新凭证refreshToken获取访问凭证accessToken
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli auth +refresh --data '{...}'`
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli auth api <name> --data '{...}'`