sino-bc-cli 1.0.0-beta.0

package/dist/skills/sino-bc-cli/domains/sino-bc-tenant/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sino-bc-tenant
+description: "查询或操作 BeyondClick 签约主体（tenant 域），用于本域 Shortcut 或 schema/API 调用。"
+metadata:
+  requires:
+    bins:
+      - sino-bc-cli
+    cliHelp: sino-bc-cli tenant --help
+---
+
+# 签约主体
+
+**开始前 MUST 先用 Read 工具读取 [sino-bc-shared](../../../sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references**；当前上下文已读且仍适用时可复用。
+
+## Shortcuts（推荐优先使用）
+
+有手写 Shortcut 时优先 `sino-bc-cli tenant +<shortcut>`。WHEN 见 `affordance/tenant.md`。⚠️ 表示高风险写；确认流程见 shared，普通 `write` 直接执行。
+
+本域暂无手写 Shortcut，用下面 API Resources。
+
+## API Resources
+
+先用 `/schema <name>` 查看字段，再用 `sino-bc-cli tenant api <name> --data '<json>'`。`<name>` 取自 catalog，不要发明。GET 的 query 参数同样通过 `--data` 传入；multipart 文件字段填写本地文件路径，由 CLI 上传内容，`--dry-run` 只预览。
+
+### 直属接口
+
+| 用户在问 | name | 注意 |
+| --- | --- | --- |
+| 查询用户签约主体列表 | `cli-user-corporation-list` | 角色：sso/passport/system |
+
+```bash
+sino-bc-cli tenant +list
+sino-bc-cli tenant api cli-user-corporation-list --data '<json>'
+```

package/dist/skills/sino-bc-cli/domains/sino-bc-user/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: sino-bc-user
+description: "按 userId 或姓名查询 BeyondClick SSO 用户资料、列表及签约主体用户资料；签约主体用户使用 body corporationId。当前组织登录态查询使用 organization。"
+metadata:
+  requires:
+    bins:
+      - sino-bc-cli
+    cliHelp: sino-bc-cli user --help
+---
+
+# 用户信息
+
+**开始前 MUST 先用 Read 工具读取 [sino-bc-shared](../../../sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references**；当前上下文已读且仍适用时可复用。
+
+## Core Concepts
+
+SSO 用户与签约主体（租户）用户资料查询。文案里的签约主体即租户，签约主体 ID 即租户 ID。
+
+- `+sso-info` / `+sso-info-batch`：按用户 ID 查公司内部用户，`--data` 只传 `userId` 或 `userIdList`。
+- `+sso-list`：按 `userIdList` 或名称模糊 `userName` 查 SSO 用户列表，两者至少传一个；返回列表无分页，字段含 `userDisplayName` / `email`，不要和 `+sso-info` 的单条资料结构混用。当前登录用户走 `organization +info` 或资料补查，不要用 `+sso-list` 回填身份槽。
+- `+tenant-info` / `+tenant-info-batch`：签约主体用户，`--data` 必须带 `corporationId` 与 `userId`/`userIdList`。本接口 `tenant=false`，主体 ID 放在请求体，不要用 `--corporation-id` 头代替。
+- `system` 角色可按接口角色范围显式查询目标用户资料；这两类接口不用于查询或自动补查系统身份本人的资料。
+- 可选主体列表走 `tenant +list` / `/tenant list`；组织树与团队成员走 `organization`；SSO 组别走 `sso-team-group +group-list`。不要和本域资料查询混用。
+- catalog 若声明 `roleScope`，CLI 在发请求前按 JWT `user_type` 拦截；未声明则不因角色拦截。
+- CLI 会把资料缓存在本机 `identity-cache.json`（passport 按主体 ID 分槽，没有「当前主体」）。这不是会话源：不要用缓存填 `--corporation-id`；对话里仍须成对保存 `--corporation-id` 与 `--auth-context-id`。
+
+单条查不到时 `result` 为 `null`；批量会去重且只返回命中项。`corporationId` 在本域请求体是整数；`/tenant list` 返回值可能是字符串，写入 `--data` 前转成数字。
+
+## Shortcuts（推荐优先使用）
+
+有手写 Shortcut 时优先 `sino-bc-cli user +<shortcut>`。WHEN 见 `affordance/user.md`。⚠️ 表示高风险写；确认流程见 shared，普通 `write` 直接执行。
+
+本域暂无手写 Shortcut，用下面 API Resources。
+
+## API Resources
+
+先用 `/schema <name>` 查看字段，再用 `sino-bc-cli user api <name> --data '<json>'`。`<name>` 取自 catalog，不要发明。GET 的 query 参数同样通过 `--data` 传入；multipart 文件字段填写本地文件路径，由 CLI 上传内容，`--dry-run` 只预览。
+
+### 租户用户
+
+| 用户在问 | name | 注意 |
+| --- | --- | --- |
+| 批量查询租户用户信息 | `tenant-user-info-batch` | 角色：sso/passport/system |
+| 查询租户用户信息 | `tenant-user-info` | 角色：sso/passport/system |
+
+### SSO 用户
+
+| 用户在问 | name | 注意 |
+| --- | --- | --- |
+| 查询SSO用户信息(用户ID) | `sso-user-info` | 角色：sso/passport/system |
+| 批量查询SSO用户信息(用户ID) | `sso-user-info-batch` | 角色：sso/passport/system |
+| 查询SSO用户列表（支持名称模糊） | `sso-user-list` | 角色：sso/passport/system |
+
+```bash
+sino-bc-cli user +tenant-info --data '<json>'
+sino-bc-cli user api tenant-user-info --data '<json>'
+```

package/dist/skills/sino-bc-cli/domains/sino-bc-wallet/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: sino-bc-wallet
+description: "查询或操作 BeyondClick 预付钱包、充值与流水查询（wallet 域），用于本域 Shortcut 或 schema/API 调用。"
+metadata:
+  requires:
+    bins:
+      - sino-bc-cli
+    cliHelp: sino-bc-cli wallet --help
+---
+
+# 预付钱包
+
+**开始前 MUST 先用 Read 工具读取 [sino-bc-shared](../../../sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references**；当前上下文已读且仍适用时可复用。
+
+## Core Concepts
+
+预付钱包、充值与流水只读查询。列表接口若响应再包一层 `xxxPage`，不要开启 CLI 翻页；未注册的汇总字段 `collectFlag` 不生效。
+
+全部接口 `tenant=true`，每次调用成对传 `--corporation-id` 与 `--auth-context-id`；角色支持 `passport` / `system`。请求体不要自行添加 `corporationId`，字段与分页能力按 `/schema <name>`。
+
+## Shortcuts（推荐优先使用）
+
+有手写 Shortcut 时优先 `sino-bc-cli wallet +<shortcut>`。WHEN 见 `affordance/wallet.md`。⚠️ 表示高风险写；确认流程见 shared，普通 `write` 直接执行。
+
+本域暂无手写 Shortcut，用下面 API Resources。
+
+## API Resources
+
+先用 `/schema <name>` 查看字段，再用 `sino-bc-cli wallet api <name> --data '<json>'`。`<name>` 取自 catalog，不要发明。GET 的 query 参数同样通过 `--data` 传入；multipart 文件字段填写本地文件路径，由 CLI 上传内容，`--dry-run` 只预览。
+
+### 直属接口
+
+| 用户在问 | name | 注意 |
+| --- | --- | --- |
+| 钱包首页 | `wallet-own` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 最近钱包流水 | `wallet-change-recent` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 最近充值记录 | `wallet-recharge-recent` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 钱包币种列表 | `wallet-currency-list` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 现金账务类型 | `wallet-cash-change-accounts-type` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 现金收支明细 | `wallet-cash-change-list` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 钱包账务类型 | `wallet-change-accounts-type` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 钱包额度类型 | `wallet-change-quota-type` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 钱包消费明细 | `wallet-change-list` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 充值明细 | `wallet-recharge-list` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 币种可用额度 | `wallet-currency-amount` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+| 币种汇率 | `wallet-exchange-rate` | 主体必填：`--corporation-id` 与 `--auth-context-id`；角色：passport/system |
+
+## 主体上下文
+
+仅标记“主体必填”的接口适用以下要求。主体必填：每次传入 `--corporation-id` 与 `--auth-context-id`，两者不放进 `--data`；绑定与恢复按 shared 条件索引读取主体参考。
+
+```bash
+sino-bc-cli wallet +own --corporation-id <主体ID> --auth-context-id <认证上下文ID>
+sino-bc-cli wallet api wallet-own --data '<json>' --corporation-id <主体ID> --auth-context-id <认证上下文ID>
+```

package/dist/skills/sino-bc-cli/references/domain-index/module-8534789.md

@@ -0,0 +1,53 @@
+# 优化工作台
+
+按意图选择下表入口，再读取完整 API Skill 及其要求的 shared/参考；参数与执行规则以 CLI 帮助和 schema 为准。已核实目标域及能力时可直读。
+
+| 意图 | 子技能 |
+| --- | --- |
+| 查询、新建或更新业务线及其状态；管理已有周策略，查看策略消耗、投放品类与策略标签、关联优化项目和广告账号。 | [sino-bc-biz-line](../../domains/sino-bc-biz-line/SKILL.md) |
+| 查询 Facebook（Meta）、Google、TikTok 的广告策略维度配置与成效数据，包括目标、出价、定向及对应效果；业务线与正式周策略管理使用 biz-line。 | [sino-bc-biz-line-metrics](../../domains/sino-bc-biz-line-metrics/SKILL.md) |
+| 分析优化项目月度汇总、项目列表、消耗与工时趋势、单位工时消耗和优化师人效，导出项目/工时/人效 Excel；也可分页查询工时系统项目、任务和工时原始表，两套时间口径不可混用。 | [sino-bc-project-analysis](../../domains/sino-bc-project-analysis/SKILL.md) |
+| 保存已生成的业务线 AI 策略，分页查询已保存策略、使用日志及用户填写的策略快照；不负责生成新策略或导出 Excel，也不等同于正式周策略的新建和更新。 | [sino-bc-biz-line-ai-strategy](../../domains/sino-bc-biz-line-ai-strategy/SKILL.md) |
+| 获取组别 code/name 选项；按组长名称或行业筛选组别管理列表，查询组长、优化师人数和组别成员详情。 | [sino-bc-sso-team-group](../../domains/sino-bc-sso-team-group/SKILL.md) |
+
+## 选用提示
+
+### 业务线策略
+
+关键词：业务线、周策略、品类、策略标签、biz-line
+
+选用提示：业务线和正式周策略使用本域；广告策略成效看 biz-line-metrics，已保存的 AI 策略看 biz-line-ai-strategy；组别选项、组长及成员信息看 sso-team-group。
+
+相关域：[业务线策略广告成效数据](../../domains/sino-bc-biz-line-metrics/SKILL.md)、[业务线AI策略](../../domains/sino-bc-biz-line-ai-strategy/SKILL.md)、[优化组别](../../domains/sino-bc-sso-team-group/SKILL.md)
+
+### 业务线策略广告成效数据
+
+关键词：广告策略、维度、成效、Facebook、Google、TikTok、Meta
+
+选用提示：查询广告策略配置和成效；正式周策略看 biz-line，已保存的 AI 策略看 biz-line-ai-strategy。
+
+相关域：[业务线策略](../../domains/sino-bc-biz-line/SKILL.md)
+
+### 优化项目分析
+
+关键词：项目分析、工时、工时系统、人效、消耗、Excel、project-analysis
+
+选用提示：优化项目月度消耗、工时趋势、人效及 Excel 导出使用本域；营销协同看板看 dashboard，投放阶段指标看 report。
+
+相关域：[看板](../../domains/sino-bc-dashboard/SKILL.md)、[报表相关](../../domains/sino-bc-report/SKILL.md)
+
+### 业务线AI策略
+
+关键词：AI策略、历史记录、使用日志、策略快照
+
+选用提示：已生成的 AI 策略保存与记录查询使用本域；正式周策略管理看 biz-line。
+
+相关域：[业务线策略](../../domains/sino-bc-biz-line/SKILL.md)
+
+### 优化组别
+
+关键词：优化组别、组别选项、组长、优化师、行业、sso-team-group
+
+选用提示：只需 code/name 时使用组别选项列表；查组长、人数或行业用管理列表，查成员用详情；业务线和周策略看 biz-line。
+
+相关域：[业务线策略](../../domains/sino-bc-biz-line/SKILL.md)、[用户信息](../../domains/sino-bc-user/SKILL.md)

package/dist/skills/sino-bc-cli/references/domain-index/module-8551546.md

@@ -0,0 +1,70 @@
+# 营销协同
+
+按意图选择下表入口，再读取完整 API Skill 及其要求的 shared/参考；参数与执行规则以 CLI 帮助和 schema 为准。已核实目标域及能力时可直读。
+
+| 意图 | 子技能 |
+| --- | --- |
+| 查询和维护营销协同对客项目、成员、分组、阶段、操作日志与项目文档关系，查看建项字段、动态表单定义、投放阶段 Tab 和项目飞书群绑定；动态表单提交契约尚未补齐，执行前须核实。 | [sino-bc-project](../../domains/sino-bc-project/SKILL.md) |
+| 查询营销协同任务列表、详情和操作日志；创建、编辑或调整任务，提交交付，完成审核、确认、驳回、暂停或删除，处理任务交付闭环。 | [sino-bc-task](../../domains/sino-bc-task/SKILL.md) |
+| 查询营销协同文档中心的文档列表与详情，上传物理文件，按文件标识或上传记录获取文件信息和链接；项目内文档关联与阶段归属使用 project。 | [sino-bc-document](../../domains/sino-bc-document/SKILL.md) |
+| 查看营销协同项目的整体看板：核心指标、按媒体/区域/项目类型/营销目标的预算分布、预算排行与来源占比、项目分布及关键项目时间轴。 | [sino-bc-dashboard](../../domains/sino-bc-dashboard/SKILL.md) |
+| 查询组织人员架构、团队成员、当前登录用户信息及按来源类型的用户列表；指定用户的单条或批量资料使用 user，可访问签约主体优先使用 /tenant list。 | [sino-bc-organization](../../domains/sino-bc-organization/SKILL.md) |
+| 查询项目或任务日志关联的飞书聊天记录、群成员、消息详情与回复链；发送机器人卡片、员工通知和项目匹配告警，查询自动汇总开关；项目与群的绑定关系使用 project。 | [sino-bc-im](../../domains/sino-bc-im/SKILL.md) |
+| 按项目、任务等用途查询可用字典场景，再按场景编码读取下拉选项或树形条目；用于营销协同选项取值，不替代项目动态表单或业务线策略标签字典。 | [sino-bc-dict](../../domains/sino-bc-dict/SKILL.md) |
+| 查询营销协同投放阶段的核心指标、花费、KPI 进度与走势、维度分布及成效明细；查看或保存 Campaign 归集规则、查询候选广告系列，阶段 Tab 使用 project。 | [sino-bc-report](../../domains/sino-bc-report/SKILL.md) |
+
+## 选用提示
+
+### 营销协同项目
+
+关键词：营销协同、对客项目、项目成员、项目分组、项目阶段、项目文档、project
+
+相关域：[营销协同文档](../../domains/sino-bc-document/SKILL.md)、[报表相关](../../domains/sino-bc-report/SKILL.md)、[飞书IM](../../domains/sino-bc-im/SKILL.md)
+
+### 营销协同任务
+
+关键词：任务、交付、审核、确认、task
+
+### 营销协同文档
+
+关键词：文档中心、文件上传、上传记录、对象存储、document
+
+选用提示：文档中心及营销协同物理文件使用本域；项目文档关系和项目文档上传看 project，跨服务通用上传看 common-file。
+
+相关域：[营销协同项目](../../domains/sino-bc-project/SKILL.md)、[文件管理](../../domains/sino-bc-common-file/SKILL.md)
+
+### 看板
+
+关键词：看板、预算分布、dashboard
+
+选用提示：预算分布、项目分布和关键项目时间轴使用本域；投放阶段指标看 report，工时与优化师人效看 project-analysis。
+
+相关域：[报表相关](../../domains/sino-bc-report/SKILL.md)、[优化项目分析](../../domains/sino-bc-project-analysis/SKILL.md)
+
+### 组织与用户
+
+关键词：组织、团队成员、人员架构、当前用户、organization
+
+选用提示：组织架构、团队成员和当前组织用户使用本域；指定用户资料或姓名列表看 user。
+
+相关域：[用户信息](../../domains/sino-bc-user/SKILL.md)
+
+### 飞书IM
+
+关键词：飞书、群消息、IM、im
+
+### 通用字典
+
+关键词：通用字典、字典场景、下拉选项、sceneCodes、bizScope、dict
+
+选用提示：营销协同项目、任务等用途的场景和选项使用本域；业务线投放品类与策略标签看 biz-line。
+
+相关域：[营销协同项目](../../domains/sino-bc-project/SKILL.md)、[营销协同任务](../../domains/sino-bc-task/SKILL.md)、[业务线策略](../../domains/sino-bc-biz-line/SKILL.md)
+
+### 报表相关
+
+关键词：报表、投放指标、KPI、消耗、阶段数据、Campaign
+
+选用提示：Campaign 归集规则与投放阶段指标使用本域；阶段 Tab 看 project，优化项目月度消耗与工时分析看 project-analysis。
+
+相关域：[营销协同项目](../../domains/sino-bc-project/SKILL.md)、[看板](../../domains/sino-bc-dashboard/SKILL.md)、[优化项目分析](../../domains/sino-bc-project-analysis/SKILL.md)

package/dist/skills/sino-bc-cli/references/domain-index/module-8562638.md

@@ -0,0 +1,13 @@
+# 租户
+
+按意图选择下表入口，再读取完整 API Skill 及其要求的 shared/参考；参数与执行规则以 CLI 帮助和 schema 为准。已核实目标域及能力时可直读。
+
+| 意图 | 子技能 |
+| --- | --- |
+| 查询当前登录身份可以访问的签约主体列表，用于确认本次操作的主体范围；日常主体探查优先使用 /tenant list，不设置全局当前主体。 | [sino-bc-tenant](../../domains/sino-bc-tenant/SKILL.md) |
+
+## 选用提示
+
+### 签约主体
+
+关键词：租户、签约主体、tenant

package/dist/skills/sino-bc-cli/references/domain-index/module-8566367.md

@@ -0,0 +1,13 @@
+# 认证及授权
+
+按意图选择下表入口，再读取完整 API Skill 及其要求的 shared/参考；参数与执行规则以 CLI 帮助和 schema 为准。已核实目标域及能力时可直读。
+
+| 意图 | 子技能 |
+| --- | --- |
+| 获取浏览器授权链接、交换访问凭证或刷新凭证；日常登录、查看登录状态和退出登录优先使用 CLI 的 /auth 身份命令。 | [sino-bc-auth](../../domains/sino-bc-auth/SKILL.md) |
+
+## 选用提示
+
+### 访问凭证管理
+
+关键词：登录、auth、令牌、OAuth

package/dist/skills/sino-bc-cli/references/domain-index/module-8581524.md

@@ -0,0 +1,17 @@
+# 用户
+
+按意图选择下表入口，再读取完整 API Skill 及其要求的 shared/参考；参数与执行规则以 CLI 帮助和 schema 为准。已核实目标域及能力时可直读。
+
+| 意图 | 子技能 |
+| --- | --- |
+| 按用户 ID 单条或批量查询 SSO 用户、签约主体用户资料，按姓名模糊查询 SSO 用户列表；签约主体用户的主体 ID 属于请求体，当前组织用户与团队架构使用 organization。 | [sino-bc-user](../../domains/sino-bc-user/SKILL.md) |
+
+## 选用提示
+
+### 用户信息
+
+关键词：用户信息、SSO用户、租户用户、签约主体用户、模糊查询、user
+
+选用提示：按指定 userId、姓名或签约主体查询用户资料使用本域；当前组织登录态及组织架构看 organization。
+
+相关域：[组织与用户](../../domains/sino-bc-organization/SKILL.md)

package/dist/skills/sino-bc-cli/references/domain-index/module-8601540.md

@@ -0,0 +1,13 @@
+# 广告投放媒体
+
+按意图选择下表入口，再读取完整 API Skill 及其要求的 shared/参考；参数与执行规则以 CLI 帮助和 schema 为准。已核实目标域及能力时可直读。
+
+| 意图 | 子技能 |
+| --- | --- |
+| 查询系统支持的广告投放渠道，按渠道名称、ID 和图标信息识别媒体；不用于查询广告策略配置或投放成效。 | [sino-bc-media](../../domains/sino-bc-media/SKILL.md) |
+
+## 选用提示
+
+### 媒体字典
+
+关键词：投放渠道、媒体、渠道、media、TikTok、Facebook、Google、Meta

package/dist/skills/sino-bc-cli/references/domain-index/module-8614891.md

@@ -0,0 +1,33 @@
+# 财务&钱包
+
+按意图选择下表入口，再读取完整 API Skill 及其要求的 shared/参考；参数与执行规则以 CLI 帮助和 schema 为准。已核实目标域及能力时可直读。
+
+| 意图 | 子技能 |
+| --- | --- |
+| 查询财务对账单列表、基本信息、账单明细、操作历史及对账单/发票枚举，了解可开票账单；月度打包对账文件使用 reconciliation。 | [sino-bc-bill](../../domains/sino-bc-bill/SKILL.md) |
+| 查询对账单关联结算单、发票结算单列表与详情、还款记录，下载发票文件；本域不提供开票或还款执行能力。 | [sino-bc-invoice](../../domains/sino-bc-invoice/SKILL.md) |
+| 按月份查询月度对账单、对账邮件发送记录与邮件预览，获取对账文件下载链接；用于月度文件和邮件核对，不负责发送邮件或查询单笔账单明细。 | [sino-bc-reconciliation](../../domains/sino-bc-reconciliation/SKILL.md) |
+| 查询签约主体的后付信用额度信息，用于了解后付额度；不提供额度调整、授信申请或预付钱包操作。 | [sino-bc-quota](../../domains/sino-bc-quota/SKILL.md) |
+| 查询预付钱包概况、余额与币种可用额度、汇率、最近或历史充值记录、现金收支及消费流水和类型字典；本域不提供充值执行能力。 | [sino-bc-wallet](../../domains/sino-bc-wallet/SKILL.md) |
+
+## 选用提示
+
+### 对账单
+
+关键词：对账单、可开票、账单
+
+### 发票结算单
+
+关键词：发票、结算单、下载
+
+### 月度对账单
+
+关键词：月度对账、对账文件、邮件
+
+### 后付额度
+
+关键词：后付、额度
+
+### 预付钱包
+
+关键词：预付、钱包、充值、流水

package/dist/skills/sino-bc-cli/references/domain-index/module-8621792.md

@@ -0,0 +1,17 @@
+# 通用功能
+
+按意图选择下表入口，再读取完整 API Skill 及其要求的 shared/参考；参数与执行规则以 CLI 帮助和 schema 为准。已核实目标域及能力时可直读。
+
+| 意图 | 子技能 |
+| --- | --- |
+| 跨服务上传通用文件并取得 storageKey，或用已有 storageKey 换取下载链接；适用于策略 Excel 等文件，不负责营销协同项目文档关系。 | [sino-bc-common-file](../../domains/sino-bc-common-file/SKILL.md) |
+
+## 选用提示
+
+### 文件管理
+
+关键词：通用文件、上传、下载链接、storageKey、common-file
+
+选用提示：通用上传或已知 storageKey 获取下载链接时使用；营销协同文件记录看 document，项目文档关系看 project。
+
+相关域：[营销协同文档](../../domains/sino-bc-document/SKILL.md)、[营销协同项目](../../domains/sino-bc-project/SKILL.md)

package/dist/skills/sino-bc-shared/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: sino-bc-shared
+description: >
+  sino-bc-cli 的共用执行规则；API 调用前读取，按条件处理主体绑定、写入确认、
+  鉴权恢复，以及配置、输出和技能安装维护。
+---
+
+# sino-bc-cli 共享规则
+
+## 执行底线
+
+1. 直接使用 CLI，不自行拼网关 HTTP；地址、path 与鉴权头由 CLI 处理。命令看帮助，参数及 `_meta.tenant`、`risk`、`roleScope`、`confirmationRequired` 看 `/schema <name>`，不猜字段、命令或示例 ID。
+2. AT/RT 不回显、不放 argv 或业务 JSON；需要登录或录入凭证时先读下表的配置参考。
+3. `_meta.tenant=true` 的调用须按任务目标确定主体，并成对传 `--corporation-id` / `--auth-context-id`，不放进 `--data`、不写全局主体、不从资料缓存回填。身份变化后整对失效，不能只换认证标记；schema 声明的业务 `corporationId` / `corporationIdList` 仍放 `--data`。
+4. 只有 `high-risk-write` 需要业务确认；普通 `write` 直接执行。`--yes` 必须对应用户已明确授权的动作与关键参数，不能为绕过提示自行添加，也不能绕过身份、主体或输入校验。生命周期命令遵循各自确认规则。
+5. 成功看 `ok == true` 或退出码 0；状态查询成功只表示本地读取成功。失败优先按 `error.params[].reason` 判断最终恢复结果，再结合 `error.code`、`error.hint`。CLI 已负责有限的令牌恢复，Agent 不额外刷新、不从头重跑已成功步骤。超时或未知结果的写入先核实结果，不能当作未执行直接重放。
+
+## 按条件读取
+
+命中以下条件时，**MUST 在下一依赖操作前读取对应参考**；未命中不预读。当前上下文已读且版本、适用条件未变时可复用；上下文丢失或文档版本变化后重新读取。多条件同时命中时，先处理身份有效性，再处理主体、确认和业务执行；这不要求普通调用每次预先运行 `/auth status` 或 `/tenant list`。
+
+| 当前任务或结果 | 必读参考 |
+| --- | --- |
+| 首次处理 tenant 接口、绑定缺失/失效、目标主体变化；`error.params[].reason` 为 `context_required` / `no_available_corporation`，或 `error.code=corporation_required` / `corporation_forbidden` | [主体上下文](references/tenant-context.md) |
+| `risk=high-risk-write`、`confirmationRequired=true`，或业务调用返回 `confirmation_required` / 退出码 10 | [高风险写确认](references/write-approval.md) |
+| `error.code` 为 `token_expired` / `token_invalid` / `authorization_unavailable` / `corporation_forbidden` / `api_forbidden`；`error.params[].reason` 为 `auth_required` / `auth_context_changed` / `auth_refresh_failed` / `credential_unreadable`；普通 HTTP 401、超时、5xx 或写入结果未知需判断如何继续 | [鉴权恢复与失败续接](references/auth-recovery.md) |
+| 查看或解释 `/auth status --json` 的 `data.localStatus`、登录、缺凭证、手动录入令牌、网关设置、角色或本人资料缓存问题 | [环境与配置](references/config-and-env.md) |
+| `/init`、`/update`、`/skill target`、`/uninstall` 或安装/迁移/恢复问题 | [技能生命周期](references/skill-lifecycle.md) |
+| 需要脚本解析信封、选择/解析输出格式、控制分页、判断截断或数据完整性、解释额外错误字段 | [输出契约](references/output-contract.md) |
+
+本技能不用于仓库源码开发、扩展命令或 npm 发布。

package/dist/skills/sino-bc-shared/references/auth-recovery.md

@@ -0,0 +1,36 @@
+# 鉴权恢复与失败续接
+
+正常业务调用在发送前按本地到期规则自动续期，无需 Agent 每次先执行 status 或单独刷新。收到失败响应后，CLI 仅根据网关在业务转发前明确返回的 `token_expired`（17000042）或 `token_invalid`（17000043）进行令牌恢复，不按普通 HTTP 401、附加响应头或未知业务码猜测。业务接口不得复用这两个网关错误码。
+
+有可用 RT 时，CLI 已负责续期并至多重试当前失败请求一次；主体探查、资料补查和业务发送共用这一次预算。同一身份已有新 AT 时可复用，正常刷新保留 `authContextId`。同一身份下恢复时，Agent 不要再单独调用 `auth +refresh` 或从头重跑已成功的业务步骤、分页。当前请求检测到并发换身份时停止该请求；自动分页的整次查询规则见下文，需要主体时按[主体上下文](tenant-context.md)重新确认身份并绑定。
+
+最终失败先读 `error.params[].reason`，再结合 `error.code` 和 `error.hint`；按 reason 分支，不要求各分支的 `name` 相同，也不从中文消息猜测。初始 `token_expired` / `token_invalid` 可能仍保留在信封里，不代表最终必须重新登录。
+
+| `error.params[].reason` | Agent 后续处理 |
+| --- | --- |
+| `auth_required` | 已确认缺 AT、当前凭证不可续期，或本次恢复后仍被网关拒绝。按[环境与配置](config-and-env.md)核对当前环境并重新授权；需要主体时重新绑定 |
+| `auth_context_changed` | 停止原身份的调用，不清新身份。确认当前身份；需要主体时清除整对旧绑定，按[主体上下文](tenant-context.md)重新查询并匹配，不能只换认证标记 |
+| `auth_refresh_failed` | 本次刷新未完成，现有凭证保留；排查或稍后只重试当前失败操作，不自动重登，不从头重跑成功步骤。不承诺 RT 有效，持续失败时按 hint 排查 |
+| `credential_unreadable` | 本地凭证解析、解密或存储读取失败。核对当前用户、home / 沙箱及存储访问；不当成未登录，不自动登录、清文件或降级存储 |
+
+`auth_refresh_failed` 包括刷新网络/服务故障、未知状态、无效令牌响应、锁超时，也包括旧 RT 的刷新失败时凭证已被其它操作更新。后一种情况不证明当前 RT 失效，也不证明当前凭证已换新或有效；保留现有凭证，停止本次操作后独立重试。
+
+例如 `error.code=token_expired`，但 `error.params` 含 `{ "name": "refreshToken", "reason": "auth_refresh_failed" }` 时，应按刷新未完成处理，不根据初始过期码登录。若 reason 为 `credential_unreadable`，则先检查存储；若为 `auth_context_changed`，则先重新确认身份与绑定。
+
+| 其它 error.code / 情况 | Agent 后续处理 |
+| --- | --- |
+| `corporation_forbidden` | 按任务目标核对主体与权限，必要时联系管理员 |
+| `api_forbidden` | 联系管理员核对接口登记及权限，不能只凭此码认定接口存在或令牌失效 |
+| `authorization_unavailable` | 保留凭证，故障排除后只继续当前失败步骤 |
+| `corporation_required` | 按[主体上下文](tenant-context.md)的服务端缺主体流程处理 |
+| 普通 HTTP 401、网络超时、5xx、无权限或未知失败 | 保留凭证，不自动重放；尤其不能把结果未知的写入当作未执行 |
+
+没有可用 RT 或 RT 明确失效时，CLI 只清理仍匹配的旧凭证和资料；并发更新后不会用旧失败清理当前凭证。刷新后再次被拒绝时停止并给出 `auth_required`，但保留新凭证；Agent 不因恢复原因自行追加清理。业务 3xx 不自动跟随。单次调用只输出最终一份失败信封；网关拒绝通常为 `api` / 退出码 1，本地读取、刷新或身份变化可能保留 `config` / `validation` / 退出码 2，不能仅按退出码决定登录。字段与传播边界见[输出契约](output-contract.md)。
+
+重新登录或手动更换 AT 后，需要主体的后续调用须重新绑定，不能只换认证标记。正常同身份刷新无需重新绑定。
+
+一次 `--page-all` / `--page-limit` 自动分页绑定首次取得的有效 `authContextId`；发送前或成功响应返回后发现身份变化，整次查询停止，不输出部分结果，也不自动用新身份重启。用户确认当前身份后可重新发起完整查询，需要主体时先重新绑定；不得把原身份下已取的页拼入新查询。同一上下文内正常 AT 续期仍继续分页，不重放成功页。绑定范围和在途请求限制见[自动翻页](output-contract.md#自动翻页)。
+
+普通 HTTP 401、超时或 5xx 不证明网关在业务转发前已拒绝请求。写入结果未知时先查询或核对业务结果，无法确认就说明现状并停止；不要再次提交来“试试看”。已有成功步骤、已上传文件和已完成分页不因鉴权恢复从头重跑；上文因身份变化终止自动分页后，由用户确认身份再发起的完整查询单独处理。专家技能中更具体的部分成功与补偿约束继续适用。
+
+同一状态目录下正常凭证读取可并行；CLI 内部协调刷新与状态修改。不要通过删除锁文件处理等待或超时，也不要因锁竞争重新登录。`/auth status` 不迁移旧凭证存储、不清理坏资料缓存；空凭证残留认证标记仍按既有规则规范化。

package/dist/skills/sino-bc-shared/references/config-and-env.md

@@ -0,0 +1,60 @@
+# 环境与变量配置
+
+| 项 | 规则 |
+| --- | --- |
+| 网关 | 缺省 `https://agent.beyondclick.com`；`/set-config gateway-url <URL>` 写入 `config.json`（合法 http/https 绝对 URL，可带 path 前缀）。业务与认证共用该根，由 CLI 请求，不直连上游服务地址 |
+| 调用 path | 等于 OpenAPI / catalog 中的 path（带 `/sino-opti-hive` 则原样保留） |
+| 鉴权 | `Authorization: Bearer <authToken>`；由 CLI 注入。macOS/Linux 令牌为 `~/.sino-bc-cli/secrets/` AES 密文，Windows 为凭据库；均不写入 `config.json` |
+| 租户头 | `x-corporation-id: <本次 --corporation-id>`；只在接口标记 `x-cli-tenant` 为真且本次显式传入主体时注入 |
+| 来源头 | `X-GATEWAY-TYPE: A2C-CLI`（固定写入，不开放配置） |
+
+macOS 可用 `/auth keychain-downgrade` 将主密钥改存本机文件，具体影响以命令提示为准。
+
+`/get-config --json` 查看公开配置（含 `config.gatewayUrl`）及 `config.authTokenConfigured`、`config.refreshTokenConfigured` 布尔值。`exists` 只表示 `config.json` 是否存在；false 表示公开配置使用默认值，不表示独立存储的凭证不存在。排查不同用户、home 或沙箱时可对照 `configPath`，不要仅因缺配置文件而重新授权。配置与状态输出均不显示令牌片段、长度或明文。
+
+可写配置：在交互终端执行 `sino-bc-cli /set-config`，隐藏输入 AT 和可选 RT；已有 AT 时执行 `sino-bc-cli /set-config refresh-token --prompt`，仅隐藏输入 RT。非 TTY 自动化用可信凭证提供程序向 `sino-bc-cli /set-config --stdin` 输送 JSON 对象，字段为 `authToken`、可选 `refreshToken`；只传 RT 需已有 AT，空 RT 表示清除。令牌不得经 argv 传入。网关根可用 `sino-bc-cli /set-config gateway-url <URL>` 修改。查看状态用 `/auth status --json`，清除用 `/auth logout`；交互身份可用 `/auth login` 在浏览器完成设备授权（成功后进度流与 json 信封 `data.message` 为「授权成功，本机身份已就绪」，不含 AT/RT）。只写 AT 不写 RT 会清掉旧 RT。只改 RT、不改 AT 时保留 `authContextId`。logout 清除整套凭证。
+
+登录、换票、刷新与业务请求使用同一生效网关根。将 `gateway-url` 写成与当前不同的地址只改网关根，不清凭证，也不丢弃对话中的主体对。归一化后相同（含仅末尾 `/` 不同）同样不清凭证。`env` / `corporation-id` / `apifox-token` 是未知键。需要主体时按[主体上下文](tenant-context.md)绑定。
+
+遇到鉴权失败时按[鉴权恢复](auth-recovery.md)判断下一步；不要因为资料过期就重新登录。
+
+维护者同步接口文档只读进程环境变量 `APIFOX_TOKEN`，不要写入 `config.json`。不要在业务任务里读取或设置它。
+
+CLI 授权接口出入参采用驼峰；`accessExpiresAt`、`refreshExpiresAt` 为毫秒时间戳。凭证由 CLI 直接保存，Agent 无需自行换算或处理 token。
+交互 `/set-config` 的访问令牌处直接回车，会保留完整 OAuth 凭证。显式输入 AT 且未给 RT 时切换为手动凭证并把 RT 置空；同时给出 RT 则一并保存。涉及安装、升级与目标恢复时见[技能生命周期](skill-lifecycle.md)。普通配置写入与技能目标登记由 CLI 协调；出现操作忙或冲突时处理提示后重试原操作。
+
+## 本地认证状态
+
+配套使用最新 CLI 与随包 Skill。需要查看状态或建立主体绑定时执行：
+
+```bash
+sino-bc-cli /auth status --json
+```
+
+TTY 与非 TTY 都从成功信封的 `data` 读取 `localStatus`、`message`、`authContextId` 等字段；`configured` / `refreshTokenConfigured` 只表示本地 AT/RT 是否存在。`localStatus` 按本地到期规则判断，未向服务器验证授权或权限。五种状态成功读取时均为退出码 0，不能把该退出码当作登录有效的证明。
+
+| `data.localStatus` | 含义与下一步 |
+| --- | --- |
+| `missing` | 当前执行环境没有非空 AT。先核对用户、home 或沙箱，再按需授权或安全录入凭证 |
+| `ready` | 按本地规则可继续业务；不保证服务器仍接受当前 AT |
+| `refresh_needed` | 下次真实调用由 CLI 自动尝试刷新；无需先登录，也不表示状态查询已刷新成功或 RT 已验证有效 |
+| `reauth_required` | 已满足本地不可续期条件，需要重新授权；状态查询本身不清凭证或发起登录 |
+| `expiry_unreadable` | 非空手动 AT 的到期信息无法读取，先核对凭证来源；不等于未登录，不据此自动重登 |
+
+OAuth 使用已保存的服务端截止时间：AT 剩余不超过 5 分钟（含已到期）且 RT 截止时间仍在未来时为 `refresh_needed`，RT 也到期则为 `reauth_required`；AT 尚余超过 5 分钟时仍为 `ready`。因此 AT 还剩 4 分钟但 RT 已过期，是进入续期窗口且无法续期，不是 AT 已过期。手动 AT 有 RT 时也使用 5 分钟窗口，但只承诺尝试刷新；没有 RT 时直到 AT 实际到期才需要重新授权。
+
+正常业务调用会按上述规则自动续期，不需要每次先执行 status。比如 `data.configured=true`、`data.localStatus=refresh_needed` 且 `data.sso=null` 时，继续原业务，由 CLI 尝试刷新；资料为空不是重新登录的依据。真实调用失败后按[鉴权恢复](auth-recovery.md)的最终原因处理。
+
+status 不发认证或业务 HTTP，不刷新、不补查资料，也不把旧裸 AT 转为 JSON 载荷或给有效凭证补认证标记。底层仍可能按既有规则搬迁旧 Keychain 存储、规范空凭证残留标记及写锁/审计，因此不承诺零文件副作用。凭证解析、解密或存储读取失败会返回失败信封，不能当成 `missing`；`credential_unreadable` 应检查当前环境与存储访问，不自动登录、清理文件或降级存储。
+
+## 角色与资料查询
+
+`/schema <name>` 的 `_meta.roleScope` 声明允许的 JWT `user_type`；已声明时，当前 JWT 的角色缺少或不匹配则 CLI 拒绝发送业务 HTTP，未声明为 null 时不因角色拦截。SSO 资料用 `user +sso-info`，签约主体用户资料用 `user +tenant-info`，其 `corporationId` 是 `--data` 字段。`system` 可按 roleScope 显式查询目标用户，但不能用这两类接口补查系统身份本人。
+
+## 本人资料缓存
+
+`/auth status --json` 的 `data` 另含 JWT `userType` 与已缓存的 `sso` / `system` / `passport`；Passport 是按主体 ID 分槽的 map，没有当前主体，不能用来填充 `--corporation-id`。资料缓存在配置目录的 `identity-cache.json`（权限 `0o600`），不进 `config.json`、不进密钥存储。
+
+本人资料只由自动补查写入，成功后固定有效 24 小时；主动查询本人或他人的资料都不会更新该缓存。状态输出的 `data.sso` / `data.system` 只显示有效资料，否则为 null；`data.passport` 只含有效主体资料。查看 `data.profileCache` 中对应角色或 Passport 主体的 `status`（`fresh` / `expired` / `missing`）判断资料状态，`fetchedAt` / `expiresAt` 为毫秒时间戳，缺失时为 null；未出现的 Passport 主体键也表示缺失。资料 null、空 map、过期或 `userType` 无法读取均不能证明未登录，也不改变 `localStatus`。下次普通业务调用会按需补查资料，普通失败仍继续业务，不要因此要求重新登录。
+
+新登录成功或手动更换 AT 清旧资料；同身份 AT/RT 刷新、仅更新 RT 或修改网关地址保留原有效期，不续期。Passport 各主体独立计时，没有默认主体。退出登录、清凭证或卸载时清资料。

package/dist/skills/sino-bc-shared/references/output-contract.md

@@ -0,0 +1,86 @@
+# JSON 输出契约
+
+业务 Shortcut 在非 TTY 默认 `--format json`，TTY 默认 `table`。可用 `--format json|table|ndjson|csv` 覆盖（**无 `pretty`**）。
+
+状态查询用 `sino-bc-cli /auth status --json`，读取成功时 TTY 与非 TTY 都返回信封 `{ ok, command, data, meta }`；读取 `data.localStatus`、`data.message` 和 `data.authContextId`，不读取根层同名字段。未传 `--json` 时保持原默认格式。五种本地状态成功读取时均为退出码 0；状态解释见[环境与配置](config-and-env.md#本地认证状态)。
+
+| 格式 | 成功输出 |
+| --- | --- |
+| `json` | stdout JSON 信封 `{ ok, command, data, meta }`，`data` 忠实保留上游形状 |
+| `table` | stdout 人读表格（面向记录） |
+| `ndjson` | 主记录数组逐行 JSON；无记录数组时整体一行；空记录零行（无信封） |
+| `csv` | 主记录数组渲染行式表格；无记录数组时降级 `key,value` 点号扁平（**不会失败**） |
+
+`ndjson` / `csv` / `table` 只认该接口分页 profile 声明的条目字段下钻，所以分页接口的 `{ total, result: [...] }` 能直接出记录行；没有该字段就不下钻（不猜"哪个数组字段是记录集"，避免把详情结果的同级标量字段吞掉）。
+
+单页调用（未开启翻页）若上游报告的 `total` 大于本页条数，非 `json` 格式会向 stderr 提示未取全并建议加 `--page-all`；`json` 的 `data` 本身带 `total`，不额外提示。该提示与截断提示不会同时出现。
+
+失败时**恒为 JSON 错误信封写 stderr**，与 `--format` 无关。自动翻页若已打出进度行，它会在信封前面；从首个 `{` 起解析。
+
+成功写 **stdout**，退出码 `0`（`json` 示例）：
+
+```json
+{ "ok": true, "command": "biz-line +list", "data": [], "meta": { "count": 0 } }
+```
+
+失败写 **stderr**：
+
+```json
+{ "ok": false, "command": "biz-line +save", "error": { "type": "validation", "message": "...", "hint": "..." } }
+```
+
+flag 解析类失败（未知 flag / 缺少取值 / 取值非法）会额外带 `error.params`，每项 `{ "name": "--foo", "reason": "unknown flag" }`，可直接拿 `name` 定位是哪个参数出错，不必从 `hint` 里正则解析。主体上下文失败同样带 `error.params[].reason`，包括 `context_required`、`no_available_corporation`。身份恢复也使用该字段，稳定取值为 `auth_required`、`auth_context_changed`、`auth_refresh_failed`、`credential_unreadable`；按 reason 分支，不依赖 name 统一。完整处理步骤见[鉴权恢复](auth-recovery.md)。其它没有单一出错字段且不涉及身份恢复的失败（普通上游业务错误、未知接口 name）不会有这个字段。
+
+## 退出码
+
+| 码 | 含义 | 该怎么做 |
+| --- | --- | --- |
+| `0` | 成功 | — |
+| `2` | `validation` / `config`：参数、配置或本地身份处理失败 | 按 `error.params[].reason` 与 hint 处理；涉及身份恢复时见[鉴权恢复](auth-recovery.md)，涉及主体时见[主体上下文](tenant-context.md) |
+| `10` | `confirmation_required`：待确认，尚未执行 | 业务调用按[高风险写确认](write-approval.md)处理；生命周期命令见[技能生命周期](skill-lifecycle.md) |
+| `1` | `api`：上游网关或业务接口失败 | 按 `error.params[].reason`、`error.code` / `hint` 处理；鉴权及失败续接见[鉴权恢复](auth-recovery.md) |
+
+## 鉴权错误字段
+
+网关鉴权拒绝使用 `error.type=api`，退出码 1。`error.message` 保留上游消息；`error.businessCode` 为原始业务码，已知码额外带稳定 `error.code`。未知业务码不推断令牌无效。排障使用 `error.ddtraceId` 与 `appTrace`，不使用默认 body 的 `traceId`。
+
+| businessCode | error.code |
+| --- | --- |
+| `17000042` | `token_expired` |
+| `17000043` | `token_invalid` |
+| `17000044` | `corporation_forbidden` |
+| `17000045` | `api_forbidden` |
+| `17000046` | `authorization_unavailable` |
+| `17000048` | `corporation_required` |
+
+`error.params[].reason` 表达最终恢复结果，优先于初始 `token_expired` / `token_invalid` 的重登推断；原 code、businessCode、message 和 appTrace 仍保留。发请求前的本地失败保持原 `validation` / `config` / `api` 分类和退出码；身份变化为 `auth_context_changed`、`validation` / 2。42/43 后刷新失败且身份复核成功时保留原网关 `api` / 1；复核读取本身失败则保留该读取错误原类别及退出码，已知读取异常附 `credential_unreadable`，不补造网关业务码或据此认定已清凭证。
+
+主体相关错误按[主体上下文](tenant-context.md)处理；其余鉴权码按[鉴权恢复](auth-recovery.md)的最终 reason 与 hint 判断，不仅凭 code 决定重新登录。
+
+## 自动翻页
+
+公共 flag：`--page-all`、`--page-limit <n>`（`0` = 不封顶，**默认不封顶**；单独传也开启翻页）、`--page-delay <ms>`（默认 200）。
+
+默认单页，翻页要显式要求。能否翻页由接口声明，字段名已钉进 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` 列表 |
+
+```bash
+sino-bc-cli biz-line api <name> --page-all --data '{"pageSize":100}'
+sino-bc-cli biz-line api <name> --page-limit 2                 # 只抽前两页
+sino-bc-cli /schema <name>                                     # 看 _meta.pagination 判断能否翻页
+```
+
+- 页码从 1 递增，页大小不传则 CLI 注入默认值；一直拉到累计条数追上 `total`，或触及单次拉取硬上限 100 万条（兜底上游忽略页码的异常场景）。`total` 按数字宽松解析，兼容上游把它序列化成字符串。
+- 翻页后 `data` 保持单页形状，条目字段替换为全部条目；`meta` 给出 `count` / `pages` / `total`。
+- 一次 `--page-all` / `--page-limit` 绑定首次真实取得的有效 `authContextId`，包括需要主体和不需要主体的接口；首次请求准备也在绑定范围内。同一上下文内正常 AT 续期仍可继续。发送前或成功响应返回后发现身份变化时，整次查询以 `error.params[].reason=auth_context_changed`、`validation` 退出码 `2` 失败，不输出部分聚合结果、不自动用新身份重启，也不清理新身份凭证及资料。凭证获取自身失败保持既有鉴权错误语义，后续处理见[鉴权恢复](auth-recovery.md)。
+- 身份绑定只覆盖本次自动分页，不保证手工多次命令或专家跨进程任务共享身份。已发出的 HTTP 不会被撤销；CLI 在成功响应返回后检查并丢弃身份已变化的结果，不保证消除最后检查后的跨进程竞态。
+- **`meta.truncated == true` 表示因显式页数上限或单次拉取硬上限提前停止、数据不全**。用户明确限量或抽样时，保留该范围并如实说明。任务要求全量时先判定截断原因：显式页数上限可加大或移除后重新取数；触及硬上限时，按 schema 支持的业务筛选拆分并核对覆盖范围，无法保证全量就报告限制，不能只加大 `--page-limit`。不要拿截断结果当全量汇报；主动重新取全量与失败重放不同，不能用来重跑结果未知的写入。
+- 不能翻页的两类接口传分页 flag 会 `validation` 失败且**不发请求**：写操作，以及 `_meta.pagination` 为 `null` 的接口。
+- 请求体若含 `pagination: false`（服务端一次返回全量），传 `--page-all` / `--page-limit` 时会去掉该字段并按页翻页。
+- `data` 只放上游 `result`。判断成功只看 `ok` 或进程退出码，**不要**用上游 `code == 0`。
+- `meta.count` 恒为主记录数组长度，与是否翻页无关。
+- 提示与进度走 stderr，避免污染信封。自动翻页且第 1 页后仍至少还有 2 个请求时，stderr 打一行「剩余约 X 个请求待处理。全部流程预计还需 A 到 B 分钟。」（含 json）；不要把这行写进信封。后续页失败时这行会留在失败信封前面，解析信封从首个 `{` 起读。