sino-bc-cli 1.8.10 → 1.8.12

package/dist/affordance/biz-line.md

@@ -4,7 +4,7 @@
 
 ## +list
 
-- **WHEN**：查询业务线分页列表
+- **WHEN**：查询业务线列表；不传条件即查全部
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +list --data '{...}'`
 
@@ -16,19 +16,19 @@
 
 ## +save
 
-- **WHEN**：新建业务线 （写操作需 --yes）
+- **WHEN**：新建业务线
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +save --data '{...}'`
 
 ## +update
 
-- **WHEN**：更新业务线 （写操作需 --yes）
+- **WHEN**：编辑业务线
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +update --data '{...}'`
 
 ## +status
 
-- **WHEN**：更新业务线状态 （写操作需 --yes）
+- **WHEN**：切换业务线状态：1 进行中 / 2 已完成 / 3 已暂停
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +status --data '{...}'`
 
@@ -40,7 +40,7 @@
 
 ## +strategies
 
-- **WHEN**：查询投放策略分页列表
+- **WHEN**：查询业务线的周策略与表现；支持按名称解析业务线
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +strategies --data '{...}'`
 
@@ -52,31 +52,31 @@
 
 ## +strategy-save
 
-- **WHEN**：新建投放策略 （写操作需 --yes）
+- **WHEN**：新建业务线周策略
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +strategy-save --data '{...}'`
 
 ## +strategy-update
 
-- **WHEN**：更新投放策略 （写操作需 --yes）
+- **WHEN**：编辑周策略；version 为乐观锁，冲突时可传 overwrite
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +strategy-update --data '{...}'`
 
 ## +strategy-delete
 
-- **WHEN**：删除投放策略 （写操作需 --yes）
+- **WHEN**：删除周策略 （写操作需 --yes）
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +strategy-delete --data '{...}'`
 
 ## +channels
 
-- **WHEN**：查询投放渠道列表
+- **WHEN**：查询投放渠道列表（code 即业务线里的 mediaChannelId）
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +channels`
 
 ## +categories
 
-- **WHEN**：查询投放品类字典
+- **WHEN**：查询投放行业与品类字典树（一级行业，二级品类）
 - **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
 - **示例**：`sino-bc-cli biz-line +categories`
 
@@ -130,6 +130,6 @@
 
 ## api
 
-- **WHEN**：没有 `+` 的接口按 name 点名调用。
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
 - **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
 - **示例**：`sino-bc-cli biz-line api <name> --data '{...}'`

package/dist/affordance/dashboard.md

@@ -0,0 +1,73 @@
+# dashboard 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +budget-by-marketing-goal
+
+- **WHEN**：营销目标预算分布
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-by-marketing-goal --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +budget-by-media
+
+- **WHEN**：媒体预算占比
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-by-media --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +budget-by-project-type
+
+- **WHEN**：项目类型预算分布
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-by-project-type --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +budget-by-region
+
+- **WHEN**：区域预算占比
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-by-region --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +budget-rank
+
+- **WHEN**：预算排行榜
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-rank --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +budget-source-ratio
+
+- **WHEN**：预算来源占比
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +budget-source-ratio --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +key-project-timeline
+
+- **WHEN**：关键项目时间轴
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +key-project-timeline --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +metrics
+
+- **WHEN**：核心卡片指标
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +metrics --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +project-distribution
+
+- **WHEN**：项目分布
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli dashboard +project-distribution --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli dashboard api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。

package/dist/affordance/delivery.md

@@ -0,0 +1,81 @@
+# delivery 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +campaign-page
+
+- **WHEN**：分页查询项目自动归集广告系列
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +campaign-page --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +campaign-get
+
+- **WHEN**：查询广告系列设置
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +campaign-get --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +campaign-save
+
+- **WHEN**：保存广告系列设置
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +campaign-save --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +core-metrics
+
+- **WHEN**：核心指标卡
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +core-metrics --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +detail-choose-list
+
+- **WHEN**：查询项目维度筛选列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +detail-choose-list --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +detail-list
+
+- **WHEN**：查询项目成效列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +detail-list --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +dimension-module
+
+- **WHEN**：维度分布
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +dimension-module --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +kpi-module
+
+- **WHEN**：KPI 进度与走势
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +kpi-module --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +spend-module
+
+- **WHEN**：消耗分析
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +spend-module --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +stage-tabs
+
+- **WHEN**：投放阶段 Tab 下拉（含起止时间）
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli delivery +stage-tabs --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli delivery api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。

package/dist/affordance/document.md

@@ -0,0 +1,69 @@
+# document 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +project-delete
+
+- **WHEN**：删除项目文档
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli document +project-delete --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +linked-tasks
+
+- **WHEN**：查询项目文档已关联任务列表（同项目同 storage_key 的 TASK 文档行）
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli document +linked-tasks --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +project-list
+
+- **WHEN**：查询项目文档
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli document +project-list --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +update-stage
+
+- **WHEN**：修改项目文档所属阶段
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli document +update-stage --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +project-upload
+
+- **WHEN**：上传项目文档（multipart/form-data：projectId项目ID，file 为文件 part）
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli document +project-upload --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+- **上传**：`--data` 的文件字段填写本地文件路径；可先 `--dry-run` 预览。
+
+## +detail
+
+- **WHEN**：协同文档详情
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli document +detail --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## +list
+
+- **WHEN**：协同文档列表（全量）
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli document +list --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +page
+
+- **WHEN**：协同文档列表（分页）
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli document +page --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli document api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。

package/dist/affordance/file.md

@@ -0,0 +1,43 @@
+# file 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +upload-info-by-record
+
+- **WHEN**：根据上传记录ID获取上传文件信息
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli file +upload-info-by-record --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## +upload-info
+
+- **WHEN**：获取上传文件信息
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli file +upload-info --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## +upload
+
+- **WHEN**：文件上传
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli file +upload --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+- **上传**：`--data` 的文件字段填写本地文件路径；可先 `--dry-run` 预览。
+
+## +url
+
+- **WHEN**：获取上传文件链接
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli file +url --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli file api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。

package/dist/affordance/im.md

@@ -0,0 +1,66 @@
+# im 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +members
+
+- **WHEN**：查询会话成员
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli im +members --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +list
+
+- **WHEN**：查询任务或项目日志关联的飞书聊天记录
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli im +list --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +cursor
+
+- **WHEN**：锚点翻页查询群消息
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli im +cursor --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +detail
+
+- **WHEN**：按 chatId + messageId 查询消息明细
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli im +detail --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +page
+
+- **WHEN**：分页查询群消息
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli im +page --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +replies
+
+- **WHEN**：按引用链根查询根消息及全部回复
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli im +replies --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +scope
+
+- **WHEN**：查询消息归属（主群或话题）
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli im +scope --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +send
+
+- **WHEN**：应用机器人发送消息（卡片）
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli im +send --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli im api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。

package/dist/affordance/organization.md

@@ -0,0 +1,45 @@
+# organization 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +list
+
+- **WHEN**：获取用户可以查看的签约主体列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli organization +list --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +tree
+
+- **WHEN**：人员架构树
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli organization +tree --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +team-members
+
+- **WHEN**：团队成员列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli organization +team-members --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +info
+
+- **WHEN**：获取当前用户信息
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli organization +info --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +listBySourceType
+
+- **WHEN**：根据用户来源类型获取用户列表（包含SSO用户则只返回前10条）
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli organization +listBySourceType --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli organization api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。

package/dist/affordance/project-analysis.md

@@ -0,0 +1,75 @@
+# project-analysis 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +export-member-hre
+
+- **WHEN**：导出优化师人效列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +export-member-hre --data '{...}'`
+
+## +export-member-timesheets
+
+- **WHEN**：导出优化师工时列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +export-member-timesheets --data '{...}'`
+
+## +export-projects
+
+- **WHEN**：导出项目数据列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +export-projects --data '{...}'`
+
+## +member-hre
+
+- **WHEN**：查询优化师人效列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +member-hre --data '{...}'`
+
+## +member-spend
+
+- **WHEN**：查询优化师消耗趋势
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +member-spend --data '{...}'`
+
+## +member-timesheet-trend
+
+- **WHEN**：查询优化师工时趋势
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +member-timesheet-trend --data '{...}'`
+
+## +member-timesheets
+
+- **WHEN**：查询优化师工时列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +member-timesheets --data '{...}'`
+
+## +projects
+
+- **WHEN**：分页查询优化项目月度数据；默认第 1 页、每页 10 条
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +projects --data '{...}'`
+
+## +spend-per-hour
+
+- **WHEN**：查询单位工时消耗趋势
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +spend-per-hour --data '{...}'`
+
+## +spend-timesheet
+
+- **WHEN**：查询消耗与工时趋势
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +spend-timesheet --data '{...}'`
+
+## +summary
+
+- **WHEN**：查询优化项目分析汇总；支持单月、月份范围和多选筛选
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-analysis +summary --data '{...}'`
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli project-analysis api <name> --data '{...}'`

package/dist/affordance/project-stage.md

@@ -0,0 +1,40 @@
+# project-stage 命令何时用
+
+字段口径在 `src/api-doc/`，这里只写 WHEN / 别用 / 示例。
+
+## +list-with-task-count
+
+- **WHEN**：查询项目阶段列表（含可见任务数）
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-stage +list-with-task-count --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## +listByProjectId
+
+- **WHEN**：查询项目阶段列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-stage +listByProjectId --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+- **参数**：`--data` 中的 query 字段按接口定义编码到 URL。
+
+## +save
+
+- **WHEN**：批量保存项目阶段
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-stage +save --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## +stage-name-list
+
+- **WHEN**：项目阶段名称列表
+- **别用**：已有更贴切的 Shortcut 时不要用本命令凑合。
+- **示例**：`sino-bc-cli project-stage +stage-name-list --data '{...}' --corporation-id <主体ID> --auth-context-id <认证上下文ID>`
+- **主体上下文**：该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。
+
+## api
+
+- **WHEN**：需要原始 JSON 字段，或没有合适的便捷 Shortcut 时按 name 调用。
+- **别用**：已有 Shortcut 的高频查询仍应走 `+xxx`。
+- **示例**：`sino-bc-cli project-stage api <name> --data '{...}'`
+- **主体要求**：先查 `/schema <name>` 的 `_meta.tenant`；为 true 时，该接口需要本次调用的主体绑定：先执行 `sino-bc-cli /auth status` 查看认证上下文，再用 `sino-bc-cli /tenant list` 查询当前身份可用主体，按任务明确的主体成对保存 ID 与认证上下文。每次调用传入 `--corporation-id <主体ID> --auth-context-id <认证上下文ID>`，不要放进 `--data`。漏传可补齐已有有效绑定；认证上下文变化时清除旧绑定，重新查询主体并唯一匹配后重新绑定，不能只替换认证标记。