sino-bc-cli 1.0.0-beta.0

package/README.md

@@ -0,0 +1,256 @@
+# sino-bc-cli
+
+BeyondClick 全局命令行工具。用本机命令访问平台能力，**不要自己拼网关 HTTP**。
+
+已发布到 [npm](https://www.npmjs.com/package/sino-bc-cli)。官网右侧 Install 框里的 `npm i sino-bc-cli` 没有 `-g`，那是网站固定文案；本包请按下面的全局安装命令执行。
+
+## 环境要求
+
+- Node.js **>= 24.0.0**
+- 能访问 npm 官方源 `https://registry.npmjs.org/`
+
+```bash
+node -v    # 需要 v24.x 或更高
+```
+
+## 架构设计
+
+运行时只有两条执行面，外加一条**不参与用户调用**的维护者同步面。
+
+| 面 | 入口形态 | 职责 | 不做什么 |
+| --- | --- | --- | --- |
+| 斜杠命令 | `/init` `/auth` … | 安装技能、升级、配置、身份、租户列表 | 不调业务接口、不拼业务 URL |
+| 业务 Shortcut | `<域> +<命令>` 或 `<域> api <name>` | 按接口清单调网关 | 不改技能目录、不定义配置字段 |
+| 维护者同步 | `npm run sync-api-doc` | 从 Apifox 生成清单 / 文档 / 技能 | 不走网关客户端，用户安装后不会再打 Apifox |
+
+设计取舍：
+
+1. **清单驱动**：运行时只认包内接口清单（name、path、域、风险、是否要主体）。命令里不写死 URL。
+2. **请求编排集中**：鉴权头、主体绑定、确认门、分页、输出信封由公共层做。域代码只回答「调哪条接口、请求体是什么」。
+3. **Shortcut 三层**：手写（名称解析、默认值）优先；其余一对一由清单生成薄命令；长尾用 `api <name>` 点名。
+4. **生成物与手写分层**：同步只覆盖生成层；专家口径和横切规则不随同步被冲掉。
+5. **目录归属一致**：Apifox 模块形成业务域导航，一级业务目录对应一个 API Skill 和命令域，子目录在 Skill 内按功能分组。目录改名保留稳定英文命令域；接口跨一级目录迁移后使用新域前缀，旧调用不保留别名。
+
+```mermaid
+flowchart TB
+  subgraph runtime [用户运行时]
+    U[用户 / Agent] --> BIN[sino-bc-cli]
+    BIN --> APP[解析 argv 并分流]
+    APP -->|斜杠命令| CMD[生命周期命令]
+    APP -->|域 +命令 或 域 api| SC[Shortcut 执行器]
+    APP -->|只有域名| HELP[域帮助 不发 HTTP]
+    CMD --> LOCAL[本机：技能 / 配置 / 身份]
+    SC --> CAT[接口清单]
+    SC --> GW[网关客户端]
+    CAT --> GW
+    GW --> HTTP[HTTP]
+    HTTP --> API[BeyondClick 网关]
+  end
+
+  subgraph maintainer [维护者同步 不在运行时触发]
+    AF[Apifox OpenAPI 与目录结构] --> SYNC[生成 catalog / 文档 / 技能]
+    SYNC --> CAT
+  end
+```
+
+身份令牌存在本机平台密钥存储，不进普通配置明文。业务请求统一带 `Authorization` 与 `X-GATEWAY-TYPE: A2C-CLI`，根地址是生效的 `gateway-url`（缺省 `https://agent.beyondclick.com`）。需要签约主体的接口必须在**这一次调用**传入 `--corporation-id` 与 `--auth-context-id`，没有全局当前主体。
+
+## 代码执行流程
+
+进程入口创建应用、跑完 `argv`、按退出码结束。全局选项（`--version` / `--help`）先扫一遍；是否走业务只看**位置参数**。每次运行会尝试记录 JSON 审计日志，成功/失败信封里的 `ddtraceId` 与请求头 `x-datadog-trace-id` 是同一枚。
+
+日志按机器当地日期每天一份追加写入，不按大小拆分、不限制总容量；单条完整 JSON（含换行）最多 64 KiB，过长详情先脱敏再截断。普通追加不争抢排他写锁。每个进程首次写日志和日期变化时检查清理状态，同一状态目录每天最多尝试一次历史清理：先记录“最近清理尝试日期”，再删除文件日期零点早于本次时刻减去 7 天的日志，不启动后台任务。
+
+清理失败会停止本轮后续删除，当天不再尝试，次日可再清理；标识无法安全写入则跳过清理。清理失败记录 WARN，WARN 或普通日志无法写入时静默跳过，不输出终端告警，业务继续且不补写失败记录。未运行、清理失败或标识日期超前时文件可能保留更久，高日志量仍可能耗尽磁盘。
+
+旧分片日志不搬迁、不合并，过期后由新版本一并清理。每日限次以全部写入进程使用新协议且状态完整为前提；旧版本混跑不保证限次，回退后旧版本不会维护新命名日志。正常本地文件系统的完整并发写入须保持独立记录；网络文件系统、短写、磁盘故障及长期挂起跨保留期等异常不保证日志完整，故障可能留下不完整行。
+
+### 1. 路由
+
+```mermaid
+flowchart TD
+  START[process.argv] --> INIT[注册斜杠命令]
+  INIT --> GLOB{"全局 --version / --help?"}
+  GLOB -->|已处理且不是域帮助| EXIT1[退出]
+  GLOB -->|继续| POS{位置参数}
+
+  POS -->|无| BANNER[欢迎 + 全局帮助]
+  POS -->|首参是已知域 且 次参是 +xxx 或 api| SC[Shortcut 执行器]
+  POS -->|首参是已知域 否则| DH[打印域帮助 不发 HTTP]
+  POS -->|其它| SLASH[斜杠命令注册表]
+```
+
+例如：`biz-line +list` 走 Shortcut；`biz-line --help` 走域帮助；`/auth login` 走斜杠命令。未知的 `+命令` 仍进 Shortcut，再以参数错误失败，不会悄悄变成帮助。
+
+### 2. 斜杠命令
+
+去掉可选的 `/`，在注册表里查找并执行。这一面只动本机（技能目录、配置、身份），**不**走业务 Shortcut 执行器。
+
+```mermaid
+flowchart LR
+  A["/init /update /skill ..."] --> R[命令注册表]
+  R --> E[对应命令 execute]
+  E --> L[写技能 / 读配置 / 登录或列主体]
+```
+
+`/tenant list` 是身份面的主体查询，不是业务域里的随意写操作。
+
+### 3. 业务 Shortcut
+
+执行器固定按下面顺序走。各条命令只提供「endpoint + 请求体」；能不能发、怎么确认、怎么输出由执行器决定。
+
+```mermaid
+flowchart TD
+  A[查找 Shortcut 定义] --> B[解析 flag]
+  B --> C[域代码 resolve<br/>得到接口名和请求体]
+  C --> D[清单上的风险 / 分页 / 主体标记]
+  D --> E{已登录?}
+  E -->|否| FAIL1[参数/配置错误 不发请求]
+  E -->|是| F{角色是否允许该接口?}
+  F -->|否| FAIL1
+  F -->|是| G{"--dry-run?"}
+  G -->|是| PREP[本地组装 method / URL / 体] --> OUT1[打印预览 结束]
+  G -->|否| H{缺主体绑定?}
+  H -->|tenant 接口且未成对传入| PROBE[先查可用主体列表]
+  PROBE -->|列表空| FAIL2[阻断 不发业务请求]
+  PROBE -->|可继续| PREP2[本地组装]
+  H -->|已绑定或不需要| PREP2
+  PREP2 --> I{"高风险写 且未 --yes?"}
+  I -->|是 非 TTY| EXIT10[退出码 10 待确认]
+  I -->|是 TTY| ASK[终端询问]
+  I -->|否 普通写或读| SEND[发网关请求]
+  ASK -->|同意| SEND
+  ASK -->|拒绝| FAIL1
+  SEND --> PAGE{是否自动翻页}
+  PAGE --> FMT[按 --format 输出信封]
+```
+
+要点：
+
+- `--dry-run` 与真实请求做**同一套**本地可组装校验，但不发 HTTP，也不探查主体列表。
+- 只有清单标成高风险写的接口才要 `--yes`；普通写操作直接执行。
+- 没有分页声明却传了翻页参数：直接校验失败，不发请求。
+- 一次 `--page-all` / `--page-limit` 固定首次有效身份，同身份令牌续期可继续；发现换身份则整次失败，不返回部分结果。确认当前身份后可重新完整查询，详见 shared 的自动翻页与鉴权恢复说明。
+- 成功看退出码 `0` 或 JSON 的 `ok`，不要看上游业务 `code`。
+- `--yes` 表示已获得高风险操作的确认，不能绕过身份、主体或其他必要校验。
+- 主体绑定与鉴权恢复由 shared 提供完整指引；鉴权失败按 `error.code`、`error.params` 和 `error.hint` 处理，不盲目重放结果未知的写入。
+
+执行 `sino-bc-cli /skill`，按返回的 `path` 读取 `sino-bc-shared` 轻量入口，再按当前任务或错误命中的条件读取对应 references；主体绑定、确认和鉴权恢复分别维护完整流程，无需预读全部参考。该路径来自当前 CLI 包，可在尚未安装 Agent 技能时查看。
+
+## 安装
+
+```bash
+# 最新版（推荐）
+npm i sino-bc-cli@latest -g
+
+# 指定版本
+npm i sino-bc-cli@<version> -g
+
+# 已安装用户升级（装 latest 并自动 /init）
+sino-bc-cli /update
+```
+
+```bash
+sino-bc-cli --version
+sino-bc-cli --help
+```
+
+装完会尝试自动 `/init`。技能没出现时再手动执行：
+
+```bash
+sino-bc-cli /init
+```
+
+`/init` 安装同一包中的导航、shared、API 域与专家技能，API 域位于 `sino-bc-cli/domains/<name>/`，通过与 Apifox 模块对应的业务域导航按需读取；shared 和专家是顶层完整入口。默认写入 `~/.agents/skills`；本机存在 `~/.claude` 时也写入 `~/.claude/skills`。需要其它目录时使用 `/skill target add <目录>` 显式登记。它不写入令牌。飞书豆包：技能·连接器 → 管理 → **本地** → 刷新。
+
+每次安装或刷新都会整目录替换 `sino-bc-cli`、`sino-bc-shared`。专家按旧安装记录中的有效名单与当前包名单的并集清理，再整目录安装当前包的专家；旧名单不存在、损坏、无法读取或无法识别时，改用当前包的专家名单。同名专家和两个固定目录中的本地修改也会被替换，缺失目录会重新安装；其它技能保留，不按名称前缀扫描删除。降级时无法识别当前包已不包含的旧专家，这些目录会保留。
+
+新包先校验并暂存，再备份旧目录并替换，成功后保存新的专家名单；安装失败恢复旧内容，恢复未完成则保留备份与恢复信息。任一目标失败，命令都会明确报告未完成。新通用目标安装成功后，清理未登记的历史位置 `~/.codex/skills`、`~/.cursor/skills`：两个固定目录直接整目录清理，专家按有效旧名单与当前包名单的并集清理，旧名单不可用时降级当前名单；仅剩 shared 或专家也会处理。已登记或实际路径属于生效目标的目录按安装规则刷新，不作为旧位置清理。清理失败或中断时保留恢复信息，重试 `/init` 按原记录继续，不扩大删除范围。不同 Agent 的发现规则可能使同一技能显示多份。
+
+`/skill target list` 可查看各目标的完整性及待恢复状态。安装中断后重试原操作；移除目标或卸载失败时，保留登记和恢复记录供重试。`/update` 会先核对 latest 的具体版本与技能安装格式，再安装已核验的版本；无法确认兼容性时停止升级，避免较新的 Beta 布局被旧正式版覆盖。
+
+首次从格式 2 平铺安装迁移到格式 3 时，旧 `/update` 会拒绝未知格式。退出其他生命周期操作后，串行执行 `npm install -g sino-bc-cli@<已确认的新版本> --registry=https://registry.npmjs.org/`，再运行新包的 `/init` 和 `/skill target list`。外部 npm 换包阶段不受 CLI 协调锁保护；新包 init 受锁保护。npm 安装成功仍需检查 Skill 是否完整；安装失败按提示处理后重试 `/init`，不要自动降级旧包。新安装记录应由新版 CLI 继续维护。
+
+命令找不到：`npm prefix -g` 把全局 bin 加入 `PATH` 后重开终端。临时试跑（不注册技能）：`npx sino-bc-cli --help`。
+
+上手顺序：安装 → `/init` → `/auth login` → 需要主体时 `/tenant list` → 业务命令或 `/schema`。
+
+Agent 在 API 域未知或有歧义时先选业务域，再选择一级目录对应的完整 API Skill；已用当前依赖说明、CLI 帮助或 schema 核实域及能力时直接读取。完成策略生成等任务时直接选择专家 Skill；各入口按需读取 shared 和依赖域。`sino-bc-cli/SKILL.md` 只提供概览、shared 及 API 分类导航；专家不在业务导航中，`/skill` 仍列出全部入口。全部技能随同一个 npm 包安装、升级和卸载。仓库开发看源码根目录 `AGENTS.md`（不随 npm 包分发）。
+
+## 斜杠命令
+
+| 命令 | 做什么 |
+| --- | --- |
+| `/init` | 把 Agent 技能写到本机目标目录 |
+| `/update` | 升级到 npm latest，再执行一次 `/init` |
+| `/skill` | 列出导航、shared、API 域及专家技能；`/skill <name>` 打开说明；`target add\|list\|remove` 管理额外安装目录 |
+| `/schema` | 列出可调接口；`/schema <name>` 看入参 |
+| `/get-config` | 查看公开配置及 AT/RT 是否已配置，不显示令牌内容 |
+| `/set-config` | 交互隐藏输入 AT/RT、从非 TTY JSON 标准输入导入令牌，或写网关地址 |
+| `/auth` | `login` 浏览器登录；`status --json` 查看本地身份状态；`logout` 退出 |
+| `/tenant` | 仅 `list`：列出当前身份可用的签约主体 |
+| `/uninstall` | 清理技能、本机配置和身份；默认同时卸载全局包 |
+
+`sino-bc-cli /auth status --json` 在终端和自动化中都返回 JSON 信封，状态从 `data.localStatus` 读取，解释见 `data.message`。它只判断本地状态，不向服务器验证、不刷新令牌；正常业务调用会自动尝试续期，无需每次先查状态。`refresh_needed` 不表示已经刷新成功，也无需先登录。 同一状态目录下，多个 CLI 可并行读取正常凭证；刷新由专用锁协调并复用其他进程的刷新结果，登录、退出和凭证修改仍互斥。锁竞争可能超时，遇到失败应按错误提示处理，不要手动删除锁文件。
+
+`/get-config` 的 `exists=false` 只表示公开配置使用默认值；本人资料为空或过期也不表示未登录。状态含义、资料缓存和失败后的完整处理规则见通过 `/skill` 定位的 shared；鉴权失败优先读取 `error.params[].reason`，不能只凭 `token_expired` / `token_invalid` 重新登录。
+
+```bash
+sino-bc-cli /init
+sino-bc-cli /skill
+sino-bc-cli /skill target add ~/my-agent/skills
+sino-bc-cli /auth login
+sino-bc-cli /auth status --json
+sino-bc-cli /tenant list
+sino-bc-cli /schema
+sino-bc-cli /schema biz-line-list
+sino-bc-cli /get-config
+sino-bc-cli /set-config  # 交互终端隐藏输入 AT，RT 可空
+sino-bc-cli /set-config refresh-token --prompt  # 仅更新 RT
+sino-bc-cli /set-config gateway-url https://agent.beyondclick.com
+sino-bc-cli /update
+sino-bc-cli /uninstall --yes
+```
+
+自动化导入时，由可信凭证提供程序向 `sino-bc-cli /set-config --stdin` 输送 JSON：`{"authToken":"…","refreshToken":"…"}`。也可只传 `authToken`（清除旧 RT），或在已有 AT 时只传 `refreshToken`（空字符串表示清除 RT）。不要把真实令牌放进命令行参数或终端历史。
+
+需要签约主体的接口，把 `/tenant list` 的主体 ID 和 `/auth status --json` 的 `data.authContextId` 成对传入 `--corporation-id`、`--auth-context-id`。
+
+## 调用样例
+
+业务命令：`<域> +<命令>`；长尾：`<域> api <name> --data '<json>'`。先看帮助。
+
+优化组别统一使用 `sso-team-group` 域：`+group-list` 获取 code/name 选项，`+list` 查询管理信息，`+detail` 查询成员详情。
+
+```bash
+sino-bc-cli sso-team-group --help
+sino-bc-cli sso-team-group +group-list
+sino-bc-cli sso-team-group +list --data '{}'
+sino-bc-cli sso-team-group +detail --data '{"code":"<组别code>"}'
+sino-bc-cli biz-line --help
+sino-bc-cli biz-line +list --data '{"name":"<业务线名称>"}'
+sino-bc-cli project-analysis +summary --data '{"startMonth":"2026-08","endMonth":"2026-08"}'
+sino-bc-cli user +sso-info --data '{"userId":123}'
+
+sino-bc-cli organization +info \
+  --corporation-id <主体ID> \
+  --auth-context-id <认证上下文ID>
+
+sino-bc-cli dict +items --data '{"sceneCodes":["<场景编码>"]}' \
+  --corporation-id <主体ID> \
+  --auth-context-id <认证上下文ID>
+
+sino-bc-cli biz-line +list --data '{"name":"<业务线名称>"}' --dry-run
+```
+
+样例中的 ID 只说明参数形状，不要当成真实数据去请求。
+
+## License
+
+MIT
+
+## 业务线策略生成
+
+Agent 使用 `biz-line-strategy-generate` 专家技能（需 Python 3），最多并发 3 条业务线。默认每条生成桌面 Excel；明确要求“写入数据库”时，生成并上传 Excel 后删除本地临时文件，将文件 key、四大策略和 learning 一并保存为 AI 策略。
+
+两种模式的 Excel 均在预算、广告产品、受众策略前展示匹配标签；素材不加标签。标签字典使用真实业务线的首个所属行业，Agent 按策略正文选取匹配标签。数据库模式先核对全部关联项目的上周消耗，全部为 0 时直接保存无投放数据状态。调用示例与参数见安装后的专家技能说明。

package/dist/affordance/auth.md

@@ -0,0 +1,31 @@
+# auth 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+执行前 MUST 读取 [sino-bc-shared](../skills/sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references；当前上下文已读且仍适用时可复用。可用 `sino-bc-cli /skill` 查询真实路径。
+
+日常登录用 `sino-bc-cli /auth login`，查看身份与本人资料缓存用 `/auth status`；自动令牌恢复由 CLI 处理，不需另调 `+refresh`。本人资料缓存字段与有效期按 shared 的配置参考读取。
+
+## +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 '{...}'`

package/dist/affordance/bill.md

@@ -0,0 +1,48 @@
+# bill 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+执行前 MUST 读取 [sino-bc-shared](../skills/sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references；当前上下文已读且仍适用时可复用。可用 `sino-bc-cli /skill` 查询真实路径。
+
+## +bill-list
+
+- **WHEN**：对账单列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli bill +bill-list --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +bill-detail
+
+- **WHEN**：对账单基本信息
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli bill +bill-detail --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## +bill-original
+
+- **WHEN**：对账单明细
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli bill +bill-original --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +bill-operate
+
+- **WHEN**：对账单操作历史
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli bill +bill-operate --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +bill-enum
+
+- **WHEN**：对账单与发票枚举
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli bill +bill-enum --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli bill api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。

package/dist/affordance/biz-line-ai-strategy.md

@@ -0,0 +1,35 @@
+# biz-line-ai-strategy 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+执行前 MUST 读取 [sino-bc-shared](../skills/sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references；当前上下文已读且仍适用时可复用。可用 `sino-bc-cli /skill` 查询真实路径。
+
+## +ai-strategy-save
+
+- **WHEN**：保存业务线AI策略
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-ai-strategy +ai-strategy-save --data '{...}'`
+
+## +list
+
+- **WHEN**：业务线AI策略分页列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-ai-strategy +list --data '{...}'`
+
+## +use-log-list
+
+- **WHEN**：业务线AI策略使用日志分页列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-ai-strategy +use-log-list --data '{...}'`
+
+## +snapshot-list
+
+- **WHEN**：用户填写原始策略快照分页列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-ai-strategy +snapshot-list --data '{...}'`
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli biz-line-ai-strategy api <name> --data '{...}'`

package/dist/affordance/biz-line-metrics.md

@@ -0,0 +1,47 @@
+# biz-line-metrics 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+执行前 MUST 读取 [sino-bc-shared](../skills/sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references；当前上下文已读且仍适用时可复用。可用 `sino-bc-cli /skill` 查询真实路径。
+
+## +facebook-dimension
+
+- **WHEN**：Facebook广告策略维度数据
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-metrics +facebook-dimension --data '{...}'`
+
+## +google-dimension
+
+- **WHEN**：Google广告策略维度数据
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-metrics +google-dimension --data '{...}'`
+
+## +tiktok-dimension
+
+- **WHEN**：TikTok广告策略维度数据
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-metrics +tiktok-dimension --data '{...}'`
+
+## +facebook-metrics
+
+- **WHEN**：Facebook广告策略成效数据
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-metrics +facebook-metrics --data '{...}'`
+
+## +google-metrics
+
+- **WHEN**：Google广告策略成效数据
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-metrics +google-metrics --data '{...}'`
+
+## +tiktok-metrics
+
+- **WHEN**：TikTok广告策略成效数据
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line-metrics +tiktok-metrics --data '{...}'`
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli biz-line-metrics api <name> --data '{...}'`

package/dist/affordance/biz-line.md

@@ -0,0 +1,84 @@
+# biz-line 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+执行前 MUST 读取 [sino-bc-shared](../skills/sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references；当前上下文已读且仍适用时可复用。可用 `sino-bc-cli /skill` 查询真实路径。
+
+## +list
+
+- **WHEN**：查询业务线分页列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +list --data '{...}'`
+
+## +detail
+
+- **WHEN**：业务线详情
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +detail --data '{...}'`
+
+## +save
+
+- **WHEN**：新建业务线
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +save --data '{...}'`
+
+## +update
+
+- **WHEN**：更新业务线
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +update --data '{...}'`
+
+## +status
+
+- **WHEN**：更新业务线状态
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +status --data '{...}'`
+
+## +strategies
+
+- **WHEN**：查询投放策略分页列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +strategies --data '{...}'`
+
+## +spend
+
+- **WHEN**：查询投放策略消耗信息
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +spend --data '{...}'`
+
+## +strategy-save
+
+- **WHEN**：新建投放策略
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +strategy-save --data '{...}'`
+
+## +strategy-update
+
+- **WHEN**：更新投放策略
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +strategy-update --data '{...}'`
+
+## +categories
+
+- **WHEN**：查询业务线字典和策略标签
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +categories --data '{...}'`
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## +project-list
+
+- **WHEN**：查询业务线关联项目和广告账号
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +project-list --data '{...}'`
+
+## +queryByPage
+
+- **WHEN**：查询项目分页列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli biz-line +queryByPage --data '{...}'`
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli biz-line api <name> --data '{...}'`

package/dist/affordance/common-file.md

@@ -0,0 +1,25 @@
+# common-file 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+执行前 MUST 读取 [sino-bc-shared](../skills/sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references；当前上下文已读且仍适用时可复用。可用 `sino-bc-cli /skill` 查询真实路径。
+
+## +upload
+
+- **WHEN**：上传文件
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli common-file +upload --data '{...}'`
+- **上传**：`--data` 的文件字段填写本地文件路径；可先 `--dry-run` 预览。
+
+## +url
+
+- **WHEN**：获取文件下载链接
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli common-file +url --data '{...}'`
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli common-file api <name> --data '{...}'`

package/dist/affordance/dashboard.md

@@ -0,0 +1,75 @@
+# dashboard 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+执行前 MUST 读取 [sino-bc-shared](../skills/sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references；当前上下文已读且仍适用时可复用。可用 `sino-bc-cli /skill` 查询真实路径。
+
+## +budget-by-marketing-goal
+
+- **WHEN**：营销目标预算分布
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-by-marketing-goal --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +budget-by-media
+
+- **WHEN**：媒体预算占比
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-by-media --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +budget-by-project-type
+
+- **WHEN**：项目类型预算分布
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-by-project-type --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +budget-by-region
+
+- **WHEN**：区域预算占比
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-by-region --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +budget-rank
+
+- **WHEN**：预算排行榜
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-rank --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +budget-source-ratio
+
+- **WHEN**：预算来源占比
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-source-ratio --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +key-project-timeline
+
+- **WHEN**：关键项目时间轴
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +key-project-timeline --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +metrics
+
+- **WHEN**：核心卡片指标
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +metrics --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## +project-distribution
+
+- **WHEN**：项目分布
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +project-distribution --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli dashboard api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。

package/dist/affordance/dict.md

@@ -0,0 +1,28 @@
+# dict 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+执行前 MUST 读取 [sino-bc-shared](../skills/sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references；当前上下文已读且仍适用时可复用。可用 `sino-bc-cli /skill` 查询真实路径。
+
+## +items
+
+- **WHEN**：按场景查询字典条目
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dict +items --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## +scenes
+
+- **WHEN**：按作用域查询字典场景
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dict +scenes --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli dict api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。