@lark-people/cli 0.0.0-beta.1

package/skills/people-corehr-workforce-plan/references/people-corehr-workforce-plan-detail-list.md

@@ -0,0 +1,238 @@
+# 编制明细查询（workforce_plan_detail.list）
+
+> 本文档只覆盖原始明细行查询与展示。仅在用户明确需要真实行级数据、原始明细或特殊行（如缺维度、过滤全零）时使用本 reference。聚合、排序、Top N、分布统计不属于明细查询职责，禁止拉明细后让大模型自行聚合；此类需求由主 SKILL 路由到汇总能力。
+
+## 适用场景
+
+使用本 reference：
+
+- 查询编制原始明细行。
+- 查看缺维度行、全零行、过滤全零后的行级结果。
+- 导出原始明细行到业务友好的 Excel。
+
+不要使用本 reference：
+
+- 用户问 HC、在职、缺编、满编率、分布、Top N、排序、占比或对比；这些是聚合诉求，不属于明细查询
+- 用户只是要方案列表、生效期或可用维度；这属于方案查询。
+
+## 执行流程
+
+1. 确认用户确实要行级明细；如果问题目标是统计或排序，不属于本 reference，停止并交由主 SKILL 重新路由。
+2. 未给 `workforce_plan_id` 时，先查 `workforce_plan list` 定位方案并保存 `dimension_lists`。
+3. 用 `dimension_lists` 校验维度 key；用户只给维度值名称时，按「维度筛选与澄清」调用 `+query-id-by-name --business-scene workforce_plan`，把唯一匹配的 `matched_id` 作为维度值 ID；多候选时先让用户确认。
+4. 调用 `people-cli schema corehr.workforce_plan_detail.list` 后，再执行 `workforce_plan_detail list`。
+5. 展示或导出时只做字段映射和展示格式转换，不做聚合、排序、Top N 或衍生指标计算。
+
+## 输出格式核心规则
+
+1. 每个维度独占一列，严禁合并到一列。
+2. 维度列名从编制方案 `dimension_lists` 获取，不得使用 key 原文。
+3. 数值列只展示 API 实际返回的字段：编制HC、在职人数、预增、预减为常规字段；缺编数、满编率、季度/预估字段返回才展示，未返回不要编造或自行计算。
+4. 严禁展示内部字段：`workforce_plan_detail_id`、`dimension_id`、`is_missing_dimension`、`is_all_zero_value`。
+5. 严禁编造数据，所有内容必须来自 API 返回。
+6. 缺维度行显示 `-`，不得跳过或隐藏。
+7. 回答必须包含当前页条数、`has_more`、前 10 行的所有维度列、编制HC、在职人数、预增、预减；缺编数、满编率若 API 返回也展示。
+8. 命令示例或执行计划不是答案；最终必须基于 `workforce_plan_detail list` 的真实输出回答。只有命令实际返回认证或权限错误时，才复述原始错误，并分别提示用户检查当前身份或补齐缺失权限。
+9. 不要根据用户描述中的业务场景把行级数据诉求降级成操作建议；判断依据是用户是否需要真实明细结果。需要真实明细结果时必须实际查询。
+
+## Excel 导出规则
+
+当用户要求“导出 / Excel / 表格文件 / xlsx / 下载明细 / 明细表”且目标是原始明细行时，先确认当前运行环境是否提供表格文件生成能力：支持时交付 `.xlsx` 文件和用户友好文案；不支持时仍执行查询，按「输出格式核心规则」返回前 10 行 Markdown 表格，并附当前页条数、已展示范围和 `has_more`，同时明确提示“当前环境不支持生成 xlsx”。不得伪造文件或下载地址，也不得直接输出 raw JSON。
+
+数据源要求：
+
+- 只能使用 `workforce_plan_detail list` 默认 `json` 输出作为导出数据源。
+- 禁止使用通用 `table` / `csv` 输出作为导出数据源。
+- 禁止把 raw JSON 或 JSON envelope 直接平铺进 Excel。
+- 模型只允许做字段映射和展示格式转换，不得聚合、求和、排序、Top N 或计算衍生指标；这些不属于明细查询职责。
+
+Excel 主表取数路径：
+
+- 从 `data.items` 生成主表行。
+- Excel 只生成一张 sheet：`结果明细`。
+- 不得额外生成 `查询说明` 或类似元信息 sheet。
+
+维度列规则：
+
+- 每个维度独占一列，列名必须使用当前方案 `dimension_lists` 中对应 `dimension_key` 的维度名称。
+- 单元格值来自 `dimension_info_datas[].dimension_info.name[]`。
+- 缺失维度显示 `-`，不得跳过或隐藏。
+- 不得直接把 `dimension_key` 当用户可见列名；只有方案未返回维度名称时才 fallback 到 key，并在最终回复中说明。
+
+数值列固定穷举；只展示 API 实际返回的字段，不允许模型自创：
+
+| JSON 字段 | Excel 列名 | 展示规则 |
+|---|---|---|
+| `workforce_plan` | 编制HC | 原样展示 |
+| `active_individuals` | 在职人数 | 原样展示 |
+| `individuals_to_be_added` | 预增 | 返回才展示 |
+| `individuals_to_be_removed` | 预减 | 返回才展示 |
+| `vacancy` | 缺编数 | 返回才展示（明细行常不返回） |
+| `fulfillment_rate` | 满编率 | 返回才展示（明细行常不返回），转成百分比 |
+| `estimated_active_individuals_details` | 季度预估 | 按日期升序展示为 `YYYY-MM-DD=人数`；未返回则不展示或置空 |
+| `multi_period_values` | 多周期编制HC | 只展示返回的周期和 `workforce_plan`，格式为 `YYYY-MM-DD=HC`；未返回则不展示或置空 |
+
+内部字段禁止写入 Excel：
+
+- `workforce_plan_detail_id`
+- `dimension_id`
+- `is_missing_dimension`
+- `is_all_zero_value`
+
+成功生成文件时，最终回复文案必须友好且简洁，至少说明：
+
+- Excel 文件路径。
+- 查询口径，例如方案、筛选维度、是否包含缺维度行、是否过滤全零行。
+- 导出行数：使用本次 `data.items` 行数。
+- 分页状态：`has_more` 和是否还有下一页；如果只导出当前页，必须说明“仅导出当前页”。
+- 若当前环境无法生成 `.xlsx`，按本节开头的固定降级格式返回 Markdown 表格；不能伪造文件路径，也不能退化为 `.txt` 或 raw JSON 平铺文件。
+
+## 调用方式
+
+编制明细查询必须传入 `workforce_plan_id`。如果用户未提供：
+
+1. 先执行 `people-cli corehr workforce_plan list` 获取方案列表。
+2. 只根据真实返回的方案名称、ID、状态、生效期和 `dimension_lists` 自动匹配；无候选或多候选时列出候选让用户选择，不得固定 plan_id。
+3. 保存方案返回的 `dimension_lists`，后续展示维度列名必须使用它。
+
+```bash
+people-cli schema corehr.workforce_plan_detail.list
+
+people-cli corehr workforce_plan_detail list \
+  --params '{"page_size":10}' \
+  --data '{"workforce_plan_id":"<方案ID>","is_centralized_reporting_project":false}'
+```
+
+常用 query 参数（放 `--params`）：
+
+| 参数 | 类型 | 说明                       |
+|---|---|--------------------------|
+| `page_size` | integer | 分页大小，最大 100；用户未指定数量时默认 10 |
+| `page_token` | string | 下一页 token                |
+
+常用 body 参数（放 `--data`）：
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `workforce_plan_id` | string | 必填。编制方案 ID |
+| `dimension_id_in_datas` | array | 可选。维度筛选，每项含 `dimension_key` 和 `dimension_ids` |
+| `include_missing_dimension_rows` | boolean | 可选。是否包含缺维度行 |
+| `filter_all_zero_value_rows` | boolean | 可选。是否过滤全零行 |
+| `is_centralized_reporting_project` | boolean | 查普通方案填 `false`；查集中填报项目必须为 `true` |
+| `centralized_reporting_project_id` | string | 集中填报项目 ID；集中填报明细必填 |
+
+集中填报口径如果缺 `centralized_reporting_project_id` 或批次/项目，必须先澄清，不得只凭方案名、地点或人员类型继续查询。
+
+## 响应结构概览
+
+```
+data.items[] — 编制明细行数组，每行包含：
+├── workforce_plan_detail_id    — 明细行 ID（不展示）
+├── dimension_info_datas[]      — 维度信息数组
+│   ├── dimension_key           — 维度类型 key
+│   └── dimension_info          — 维度详情对象
+│       ├── dimension_id        — 维度值 ID（不展示）
+│       └── name[]              — 国际化名称数组（展示用）
+├── workforce_plan              — 编制规划值(HC)
+├── active_individuals          — 在职人数
+├── individuals_to_be_added     — 预增员数量（返回才展示）
+├── individuals_to_be_removed   — 预减员数量（返回才展示）
+├── vacancy                     — 缺编数（常不返回，返回才展示）
+├── fulfillment_rate            — 满编率（0.5 = 50%，常不返回，返回才展示）
+├── estimated_active_individuals_details[] — 预估在职人数明细（如需展示）
+├── multi_period_values[]       — 多周期编制值（仅展示 workforce_plan）
+├── is_missing_dimension        — 是否缺维度行（不展示）
+└── is_all_zero_value           — 是否全零行（不展示）
+```
+
+不要展示 API 未返回的字段。`vacancy_including_individuals_to_be_added_and_removed`、`fulfillment_rate_including_individuals_to_be_added_and_removed` 属于含在途口径，仅当用户明确要求且 API 返回时才展示。
+
+明细行字段名固定，**严禁臆想**；维度值是 `name[]` 国际化数组。优先选择当前回复语言对应的名称，缺失时回退到第一个可用名称。明细行 `vacancy`（缺编）、`fulfillment_rate`（满编率）常不返回（多数方案的明细行只给原始 HC、在职、预增、预减），返回才展示，需要可靠缺编/满编率时用汇总接口。Agent 可以直接解析默认 JSON；需要 jq-compatible 表达式时，可参考以下用户语言维度值和明细字段提取样例，`<language>` 使用当前回复语言对应的语言代码：
+
+```jq
+.data.items[]
+| ([.dimension_info_datas[]
+    | ((.dimension_info.name[]? | select(.lang=="<language>") | .value) // .dimension_info.name[0].value // "-")]
+   | join(" / ")) as $dim
+| "\(if $dim=="" then "-" else $dim end)\tHC=\(.workforce_plan)\t在职=\(.active_individuals)\t预增=\(.individuals_to_be_added)\t预减=\(.individuals_to_be_removed)"
+```
+
+不强制使用 people-cli `--jq`、Agent 自带 jq 或用户环境中的 jq，也不要求额外安装。若选择 people-cli `--jq`，传入上面的表达式且保持默认 `json`，不要同时传非 `json` 的 `--format` 或 `--output`。
+
+> 多维度行每行可能有多个维度值，必须用 `[...]| join` 聚成一个字段，不要让 `name[]` 展平成多行重复输出。
+
+## 维度筛选与澄清
+
+先用方案 `dimension_lists` 确认维度 key 是否存在。用户提供的是维度值名称而不是 ID 时，调用现有 `+query-id-by-name`；不要从 `dimension_lists` 中臆测维度值 ID：
+
+```bash
+people-cli corehr +query-id-by-name \
+  --business-scene workforce_plan \
+  --language "<zh-CN 或 en-US>" \
+  --format json \
+  --queries '[{"field_api_name":"<业务字段API名>","target_object_api_name":"<目标对象API名>","query_name":"<维度值名称>"}]'
+```
+
+构造查询字段时，以当前方案的 `dimension_key` 为准：普通维度的业务字段和目标对象都使用该 key；`custom_org_01`～`custom_org_10` 的 `field_api_name` 追加 `__c`；`actual_work_location` 的 `target_object_api_name` 使用 `location`。仅当 `results[].matched_id` 唯一匹配，才将其写入 `dimension_id_in_datas[].dimension_ids`。无匹配时如实反馈；多匹配时按候选名称和路径让用户确认，禁止默认取第一条。禁止把任何环境或租户中的维度 key、维度值或固定数据预置为通用映射。
+
+维度解析前先剔除业务功能词：`我的团队`、`我团队`、`我团`、`人员管理` 单独出现或作为入口前缀时，只表示产品入口 / 业务模块，不是编制维度、部门、维度值或筛选条件。不得把这些词写入 `dimension_id_in_datas`，也不得因为它们不在 `dimension_lists` 中就要求用户澄清。只忽略完整词，不截断 `人员类型` 等真实维度词；若用户明确说“名为 <词> 的部门/维度值”，才按真实维度值处理。
+
+匹配规则：
+
+- 用户说法能唯一命中 `dimension_lists[].name` 或 `dimension_lists[].key` 时，使用该条返回的 key。
+- 用户说法无法唯一判断是维度名还是维度值时，必须停止并澄清。
+- 用户说法没有命中或命中多个维度时，必须列出可用维度名称/key 并请用户选择，不能泛泛问“请确认”。
+- 请求的维度没有出现在目标方案 `dimension_lists` 时，必须列出可用维度并让用户选择或更换方案，不能用相近维度替代。
+- 维度值必须使用已确认的 ID；如果用户只给出名称，先执行 `+query-id-by-name`。无法唯一确认时列出候选让用户选择，不能自动取第一个。
+
+明细筛选使用已确认的维度 ID：
+
+```bash
+people-cli corehr workforce_plan_detail list \
+  --params '{"page_size":10}' \
+  --data '{"workforce_plan_id":"<方案ID>","dimension_id_in_datas":[{"dimension_key":"<dimension_key_from_dimension_lists>","dimension_ids":["<维度值ID>"]}],"filter_all_zero_value_rows":true,"is_centralized_reporting_project":false}'
+```
+
+## 格式化规则
+
+### 维度列
+
+- 表格左侧展示所有维度列。
+- 维度列名从方案 `dimension_lists` 获取。
+- 维度值从 `dimension_info.name[]` 获取。
+- 缺失维度显示 `-`。
+
+示例：
+
+```text
+| <维度A> | <维度B> | 编制HC | 在职人数 | 预增 | 预减 | 缺编数 | 满编率 |
+|---|---|---|---|---|---|---|---|
+| <维度值A> | <维度值B> | <HC> | <在职> | <预增> | <预减> | <缺编> | <满编率> |
+| - | <维度值B> | <HC> | <在职> | <预增> | <预减> | <缺编> | <满编率> |
+```
+
+### 数值列
+
+| JSON 字段 | 中文列名 | English Column | 格式化规则 |
+|---|---|---|---|
+| `workforce_plan` | 编制HC | Workforce Plan(HC) | 原样展示 |
+| `active_individuals` | 在职人数 | Active Individuals | 原样展示 |
+| `individuals_to_be_added` | 预增 | To Be Added | 返回才展示 |
+| `individuals_to_be_removed` | 预减 | To Be Removed | 返回才展示 |
+| `vacancy` | 缺编数 | Vacancy | 返回才展示（明细行常不返回） |
+| `fulfillment_rate` | 满编率 | Fulfillment Rate | 返回才展示，乘以 100 并加 `%` |
+
+多周期数据如需展示，按 `multi_period_values[].period_date` 展示每个周期的 `workforce_plan`；若返回预增 / 预减，也可在用户要求多周期口径时展示。
+
+季度、未来日期或预估口径只展示 API 返回字段：`estimated_active_individuals_details` 展示返回日期和预计在职人数；`multi_period_values` 只展示返回的周期和编制值。缺编、含在途缺编、满编率等字段未返回时不得推导。
+
+## 聚合分析规则
+
+- 本 reference 只做行级明细查询与展示，不做聚合、排序、Top N、分布统计、跨维度对比。
+- 禁止通过 `workforce_plan_detail list` 拉明细后本地分组、求和、排序或 Top N。
+- 只有用户明确要查看原始明细行时才使用本 reference；属于聚合/汇总的诉求停止并交由主 SKILL 重新路由。
+
+## 数据量较大时
+
+- 默认展示前 10 行；若用户要求“多给一些”且明细行超过 20 行，展示前 20 行后注明当前页条数、已展示范围和 `has_more`。
+- 若结果为空，固定回复：`未查询到符合条件的编制明细；当前页返回 0 条，has_more=false。`

package/skills/people-corehr-workforce-plan/references/people-corehr-workforce-plan-detail-summary.md

@@ -0,0 +1,221 @@
+# 编制汇总查询 (+workforce-plan-detail-summary)
+
+查询编制规划 HC 汇总数据：编制 HC、在职人数、预增、预减、缺编数、满编率等。支持维度筛选、分组聚合、排序和 Top N。结果获取、排序、Top N、截断都由 shortcut 完成；agent 只表达筛选、分组、排序意图，禁止拉明细后本地分组/求和/排序。最终答案必须是 people-cli 返回的业务数据，命令示例或执行计划不是答案。
+
+> **认证与权限：** 沿用当前 people-cli 运行环境和身份，不预设登录态，也不主动执行登录、初始化或身份切换。汇总基础权限为 `corehr:workforce_detail:read`；未传 `--plan-id` 自动查询方案时还需要 `corehr:workforce_plan:read`；维度按名称解析时还需要 `corehr:corehr:query_id_by_name`。CLI 返回认证错误时提示用户检查当前身份，返回权限错误时提示补齐实际缺失的公共权限。
+
+## 适用场景
+
+使用本 reference：
+
+- 查询编制 HC、在职人数、预增、预减、缺编数、满编率等汇总指标。
+- 按方案维度筛选、分组、排序、Top N、分布、构成、占比、对比或趋势。
+- 判断“哪些部门 / 地点 / 序列 / 维度值满足某个指标条件”。
+- 导出汇总或分组结果到业务友好的 Excel（见「Excel 导出」）。
+
+不要使用本 reference：
+
+- 用户要原始行级明细、缺维度行或过滤全零行 → detail-list reference。
+- 用户只问方案列表、生效期或方案维度清单 → workforce-plan reference。
+
+## 执行流程（禁止跳步）
+
+1. **拆解诉求**：识别答案行粒度（单对象汇总 / 分组聚合 / 对比 / 占比 / 趋势 / 导出）、筛选条件、判断指标。
+2. **定位方案**：未给 `plan_id` 时先 `workforce_plan list` 定位方案并读取 `dimension_lists`。
+3. **解析维度**：筛选、分组、展示维度都必须来自目标方案 `dimension_lists`，按「维度解析」校验与澄清，禁止猜测。
+4. **构造命令**：按答案行粒度选参数（是否分组、排序、Top N、占比分母），分组维度（尤其树维度）的写法都见「分组与排序口径」。
+5. **核对再答**：按「输出与回答规则」整理事实表，逐行可核对后再下结论。
+
+## 命令参数
+
+```bash
+people-cli corehr +workforce-plan-detail-summary [flags]
+```
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--plan-id` | string | 否 | - | 编制方案 ID。不传则自动按当前日期匹配生效方案 |
+| `--plan-name` | string | 否 | - | 方案名称关键词，多方案时过滤；只匹配当前生效方案，历史方案需用 `--plan-id` |
+| `--dimensions` | string_array | 否 | - | 筛选维度，格式 `type:name` 或 `type:=id`；多个维度必须重复传 `--dimensions`，禁止逗号合并 |
+| `--include-children` | bool | 否 | true | 筛选维度是否包含下级 |
+| `--group-by` | string_array | 否 | - | 分组维度，格式 `key`、`key:level`、`key:true/false`；树维度必须显式 `:true`/`:false`/`:<level>`。多个维度必须重复传 `--group-by`（如 `--group-by department:true --group-by job_family:true`），禁止写成 `department:true,job_family:true` 逗号形式（会报 invalid group-by format） |
+| `--sort-by` | string | 否 | - | 排序字段：`workforce_plan`、`active_individuals`、`vacancy`、`fulfillment_rate`、`dimension_name` |
+| `--sort-order` | string | 否 | desc | `asc` / `desc` |
+| `--top` | int | 否 | 0 | 排序后保留前 N 条，使用时必须配 `--sort-by` |
+| `--format` | string | 否 | json | 用户展示用 `pretty`；程序处理 / 排障 / 导出数据源用默认 `json` |
+| `--dry-run` | - | 否 | - | 仅打印将要调用的 API，不实际执行 |
+
+**`--format` 选择**：用户要直接看汇总/分组/排序/对比/示例时必须显式加 `--format pretty`；需要程序化处理、导出数据源、保留完整 envelope 或用 `--jq` 时保留默认 `json`。通用 `table` 格式只会把 envelope 平铺成 key-value，禁止用于用户展示。
+
+## 维度解析
+
+`--dimensions` 两种写法：按名称 `type:name`（如 `<dimension_key>:<维度值名称>`），或直传 ID `type:=id`。多个维度重复 `--dimensions`，名称解析由 shortcut 并发执行。
+
+解析前先剔除业务功能词：`我的团队`、`我团队`、`我团`、`人员管理` 单独出现或作为入口前缀时只表示产品入口，不是维度/维度值/筛选条件，不得传入 `--dimensions`/`--group-by`/`query_id_by_name`，也不得因其不在 `dimension_lists` 中就要求澄清；只忽略完整词，不截断 `人员类型` 等真实维度词；用户明确说“名为 <词> 的部门/维度值”时才按维度值处理。
+
+匹配规则：
+
+- 唯一命中 `dimension_lists[].name` 或 `.key` → 用该 key。
+- 无法判断是维度名还是维度值、命中多个维度、维度值有多个候选 → **停止并列候选让用户选择**，禁止自动取第一个。
+- 没命中任何维度 → 展示当前方案可用维度并询问，禁止猜测或改用相近维度。
+- 禁止预置固定方案 ID、固定维度映射或固定维度值。
+- 不假设不同维度 key 语义等价或可以相互替代；只使用当前方案 `dimension_lists` 中与用户口径明确匹配的维度，存在歧义时列出实际候选让用户确认。
+
+澄清模板：
+
+```text
+当前启用方案是 <方案名称>（<开始日期> 至 <结束日期>），已配置维度包括：<维度列表>。请求中的维度口径尚不能直接匹配到已配置维度，需要先确认使用哪个可用维度或更换方案。
+```
+
+## 分组与排序口径
+
+按答案行粒度选择参数：
+
+| 答案行粒度 | 参数 |
+|---|---|
+| 单对象汇总 | 相同 `--dimensions`，不带 `--group-by` |
+| 哪些对象满足条件 | `--group-by` = 输出行粒度，判断字段取返回行原始指标 |
+| Top / 最多 / 最少 | `--sort-by` + `--sort-order` + `--top`（未明确 N 默认 `--top 5`） |
+| 占比 / 构成 | 分母用 `.data.summary`（同条件总汇总），见「输出与回答规则」 |
+
+### 树维度判定
+
+非树维度（`job_level`、`employee_type`、`job`、`position`、`pathway` 等）只能写裸 `--group-by <key>`，禁止加 `:level`/`:true`/`:false`。
+
+树维度不接受裸 `--group-by <key>`，必须显式选 `:<level>`/`:true`/`:false`，从自然语言一次性自动判定，**禁止把“是否含下级”当澄清问题反问用户**。下表是当前 CLI 支持的树维度清单，唯一代码来源为 Shortcut 的 `treeDimensionKeys`；本 Skill 只在此处维护一份清单，代码修改 `treeDimensionKeys` 时必须同步本表。CLI 运行时校验是最终依据：若返回 `invalid group-by` 或非树维度错误，复述原始错误并按 CLI 提示处理，不自行猜测其他映射；后续 CLI 若通过 help/schema 暴露该清单，则优先读取运行时清单，静态表只作 fallback。
+
+| 类别 | 树维度 key |
+|---|---|
+| 组织/部门 | `department` |
+| 地点/实际工作地点 | `location`、`actual_work_location` |
+| 序列 | `job_family` |
+| 成本中心 | `cost_center` |
+| 自定义组织 | `custom_org_01` ~ `custom_org_10` |
+
+判定优先级（高 → 低）：
+
+1. 层级语义（一级/二级/顶层/第 N 级/下钻一层）→ `key:N`（N 仅 1-5）
+2. 明确含下级（含下级/管辖范围/全景汇总/汇总口径）→ `key:true`
+3. 明确不含下级（仅/节点自身/不含下级/只看 X 本身）→ `key:false`
+4. 分布/占比语义（分布/构成/占比/比例/share/各占多少）且未指定层级和含下级 → `key:false`（互斥分桶）
+5. 都不命中（各对象/Top N 等常见汇总排序）→ `key:true`（含下级，不反问）
+
+| 写法 | 含义 |
+|---|---|
+| `<tree_key>` | 非法；必须显式 `:true`/`:false`/`:<level>` |
+| `<tree_key>:N` | 第 N 层分组；同层互斥分桶，适合分布/占比 |
+| `<tree_key>:true` | 节点及其下级；父子可能重叠，适合含下级排行/汇总，**不可相加、不可当互斥分母** |
+| `<tree_key>:false` | 仅节点自身，不含下级；适合未指定层级的分布/构成/占比 |
+| `<dimension_key>` | 非树维度裸 key 分组 |
+
+输出首行须标注口径，例如：`本次按 含下级 (department:true) 汇总；父子节点可能重叠，不可相加` / `本次按 一级部门 (department:1) 统计；同层分桶可用于占比` / `本次按 节点自身 (department:false) 统计；可用于分布`。
+
+## 跨年 / 多方案对比
+
+跨年或多方案对比时，先按 [`workforce-plan`](people-corehr-workforce-plan.md) 的「全量 / 历史方案定位」拿到各年度的 `workforce_plan_id`，再对每个方案分别 `--plan-id <id>` 查询、保持相同维度筛选与分组口径，最后按年度并列展示（每年标注方案名、plan_id、生效期、口径）。某年度方案不含对比维度时标注「当前方案不含 <维度名> 维度」，不跨年硬凑。
+
+## 典型用法
+
+```bash
+# 树维度一级节点汇总 / 排序 / 占比
+people-cli corehr +workforce-plan-detail-summary \
+  --group-by "<tree_dimension_key>:1" --sort-by workforce_plan --sort-order desc --top "<N>" --format pretty
+
+# 树维度分布 / 构成 / 占比（未声明层级用节点自身，避免父子重叠）
+people-cli corehr +workforce-plan-detail-summary \
+  --plan-id "<方案ID>" --group-by "<tree_dimension_key>:false" --sort-by workforce_plan --sort-order desc --format pretty
+
+# 树维度含下级排行（父子可能重叠，不可相加）
+people-cli corehr +workforce-plan-detail-summary \
+  --plan-id "<方案ID>" --group-by "<tree_dimension_key>:true" --sort-by vacancy --sort-order desc --top 5 --format pretty
+
+# 非树维度稳定展示示例
+people-cli corehr +workforce-plan-detail-summary \
+  --plan-id "<方案ID>" --group-by "<dimension_key>" --sort-by dimension_name --sort-order asc --top 10 --format pretty
+
+# 按维度值过滤后再按另一维度分组
+people-cli corehr +workforce-plan-detail-summary \
+  --plan-id "<方案ID>" --dimensions "<dimension_key_1>:<维度值名称1>" --group-by "<dimension_key_2>" --sort-by vacancy --sort-order desc --format pretty
+
+# 多条件筛选汇总
+people-cli corehr +workforce-plan-detail-summary \
+  --plan-id "<方案ID>" --dimensions "<dimension_key_1>:<维度值名称1>" --dimensions "<dimension_key_2>:<维度值名称2>" --format pretty
+```
+
+## 响应字段、路径与 jq-compatible 样例
+
+默认 `json` envelope 字段路径固定如下，**严禁臆想字段名**；维度值是 `{lang,value}` 国际化数组：
+
+| 路径 | 含义 |
+|---|---|
+| `.data.summary` | 同条件不带 `group_by` 的总汇总（单汇总查询也走这里）；总量 / 分母 / 整体口径优先取此 |
+| `.data.grouped_summary_result.items[]` | 分组结果行；每行含维度信息和数值字段 |
+| `.items[].dimension_info_datas[].dimension_key` | 该分组维度 key |
+| `.items[].dimension_info_datas[].dimension_info.name[]` | 维度值国际化数组；优先取当前回复语言对应的 `value`，缺失时回退到第一个可用名称 |
+| `.data.grouped_summary_result.total_count` | 排序 / Top 前的全量分组数；回答“共 X 个分组”用它 |
+| `.data.grouped_summary_result.returned_count` | 本次返回条数；回答“示例 / 本次返回 X 个”用它 |
+| `.data.grouped_summary_result.has_more` / `all_pages_drained` / `truncated_by_top` | 分页与截断状态 |
+
+数值字段（`summary` 与每个分组行通用）：
+
+| 字段 | 展示名 | 规则 |
+|---|---|---|
+| `workforce_plan` | 编制HC | 原样 |
+| `active_individuals` | 在职人数 | 原样 |
+| `individuals_to_be_added` | 预增 | 原样 |
+| `individuals_to_be_removed` | 预减 | 原样 |
+| `vacancy` | 缺编数 | 原样（HC - 在职，可为负=超编） |
+| `fulfillment_rate` | 满编率 | 转百分比，`0.5`→`50.0%` |
+| `estimated_active_individuals_details[]` | 季度预估 | 用户问季度/预估/未来/年末/走势时逐条展示 `YYYY-MM-DD=人数` |
+
+Agent 可以直接按上述路径解析默认 JSON，不强制使用某一种 jq 实现。需要 jq-compatible 表达式时，可参考以下分组行提取样例；`<language>` 使用当前回复语言对应的语言代码：
+
+```jq
+.data.grouped_summary_result.items[]
+| ([.dimension_info_datas[]
+    | ((.dimension_info.name[]? | select(.lang=="<language>") | .value) // .dimension_info.name[0].value // "-")]
+   | join(" / ")) as $dim
+| "\(if $dim=="" then "-" else $dim end)\tHC=\(.workforce_plan)\t在职=\(.active_individuals)\t预增=\(.individuals_to_be_added)\t预减=\(.individuals_to_be_removed)\t缺编=\(.vacancy)\t满编率=\(.fulfillment_rate)"
+```
+
+不强制使用 people-cli `--jq`、Agent 自带 jq 或用户环境中的 jq，也不要求额外安装。若选择 people-cli `--jq`，传入上面的表达式且保持默认 `json`，不要同时传非 `json` 的 `--format` 或 `--output`。
+
+> 多维度分组时每行可能有多个维度值，必须用 `[...]| join` 聚成一个字段（如 `业务线 / 序列`），不要让 `name[]` 展平成多行重复输出。
+> 数值字段（`workforce_plan`/`active_individuals`/`individuals_to_be_added`/`individuals_to_be_removed`/`vacancy`/`fulfillment_rate`）返回的是**字符串**（如 `"0"`、`"1"`）。使用 jq-compatible 表达式按数值筛选/比较时必须先 `tonumber`，例如 `select((.workforce_plan|tonumber)==1)`；直接 `==1`（数字）永不命中、得到空结果。提取结果为空时如实回答“无符合条件的行”，禁止编造数据。
+
+含在途缺编、含在途满编率仅在用户明确要求且 API 返回时展示。`--format pretty` 已按上表渲染并把季度预估展示为 `YYYY-MM-DD=<预计在职>`，供用户阅读。
+
+## 输出与回答规则
+
+- 维度名称取自 `dimension_lists`、维度值取自 `dimension_info.name[]`，不得把 `dimension_key` 当显示名；缺失维度显示 `-`。
+- 禁止编造 API 未返回的数据：方案名/ID/状态/日期/维度/维度值/人数/分页/预估/缺编字段无返回时只能答无法确认或需澄清。
+- **占比分母**只能来自同筛选条件下不带 `--group-by` 的总汇总（优先 `.data.summary`）或互斥的 `key:false`/`key:N` 分桶；**禁止用 `key:true` 分组行求和当分母**；用户坚持含下级占比时只能称“覆盖口径占比”并说明合计可能超 100%。
+- **排序 / Top N** 必须显式传参，只展示 shortcut 返回的排序后前 N，不得估算 total、重排或补齐未返回的分组。
+- 分组回答必须含：`returned_count`、`total_count`、`has_more`、前 10 个分组的维度值与六项核心指标（编制HC、在职人数、预增、预减、缺编数、满编率）。指定 Top N 时展示排序后前 N。必须区分“本次返回 X 个分组”（`returned_count`）与“共汇总 X 个分组”（需 `all_pages_drained=true` 或 `total_count`）；`has_more=true` 或 `page_token` 非空且需要完整统计时必须继续分页，否则标注仅当前页。
+- 单汇总回答必须含六项核心指标（编制HC、在职人数、预增、预减、缺编数、满编率）。用户问季度/预估/未来/年末/走势时逐条展示 `estimated_active_individuals_details`。
+- 层级维度按工具返回的显示名和层级信息展示。用户明确要求叶子级时，只在返回结果能够可靠识别叶子节点的情况下过滤；无法判断时说明限制，禁止根据名称猜测层级。
+- 空结果固定回答：“未查询到符合条件的编制汇总；当前页返回 0 条，has_more=false”（has_more 以 API 为准），不编造分组。
+
+**自检**：加了不同 `--dimensions` 返回完全相同 → 怀疑筛选未生效或维度值未命中；出现人员类型、组织、地点等业务术语 → 先判断是筛选条件还是输出维度；返回行同时含父子节点 → 先确认覆盖口径还是互斥分桶，含下级不简单求和；只拿到错误/空返回/缺字段 → 不给正向业务结论。
+
+## Excel 导出
+
+用户要求“导出 / Excel / xlsx / 下载结果”时，先确认当前运行环境是否提供表格文件生成能力：支持时交付 `.xlsx` 文件和简洁文案；不支持时仍执行查询，按「输出与回答规则」返回 Markdown 表格：单汇总展示一行，分组结果展示前 10 行，并附 `returned_count`、`total_count` 和 `has_more`，同时明确提示“当前环境不支持生成 xlsx”。不得伪造文件或下载地址，也不得直接输出 raw JSON。
+
+- **数据源**：只用默认 `json` 输出；禁止用 `pretty`（反解析）、通用 `table`、或把 raw JSON/envelope 直接平铺进 Excel。
+- **取数**：分组导出从 `.data.grouped_summary_result.items` 生成主表行，总计 / 占比分母从 `.data.summary` 读取（不对分组行求和）；单汇总导出从 `.data.summary` 生成一行。模型只做字段映射和格式转换，不重新聚合/排序/Top N/计算。
+- **列**：维度列名取 `dimension_lists` 维度名、值取 `dimension_info_datas[].dimension_info.name[]`，优先当前回复语言、缺失时回退第一个可用名称；缺失显示 `-`。数值列固定取「响应字段与路径」数值表，不自创列。
+- **sheet**：只生成一张 `结果明细`（维度列 + 固定数值列）；不生成 `查询说明` 等元信息 sheet；`plan_id`、`group_by`、`sort_by`、`top`、`total_count`、`returned_count`、`has_more` 等元信息只写进回复文案。
+- **文案**：成功生成文件时，至少说明 Excel 路径、查询口径（方案/分组维度/排序/Top N）、导出行数（`returned_count`，总分组数用 `total_count`）、分页截断状态。若环境无法生成 `.xlsx`，按本节开头的固定降级格式返回 Markdown 表格；不伪造文件路径，也不退化为 `.txt` 或 raw JSON 平铺。
+
+## 异常处理
+
+| 场景 | 行为 |
+|------|------|
+| 无生效方案 | 报错 `no active workforce plan covers current date` |
+| 多个生效方案 | 列出方案并提示用 `--plan-id` 或 `--plan-name` |
+| 维度格式错误 | 报错并提示 `type:name` / `type:=id` |
+| 分组格式错误 | 报错并提示 `key` / `key:level` / `key:true/false` |
+| 非树维度指定 level/include_children | 报错并提示只有树维度支持 |
+| `--top` 未指定 `--sort-by` | 报错并要求明确排序字段 |
+| scope 不足 | 复述 CLI 原始错误，提示用户补齐实际调用缺失的公共权限：基础汇总 `corehr:workforce_detail:read`、自动查方案 `corehr:workforce_plan:read`、名称换 ID `corehr:corehr:query_id_by_name` |

package/skills/people-corehr-workforce-plan/references/people-corehr-workforce-plan.md

@@ -0,0 +1,79 @@
+# 编制方案查询（workforce_plan.list）
+
+查询编制方案本身：方案列表、当前生效方案、方案状态、生效期、支持维度（`dimension_lists`）。本 reference 只覆盖方案查询，不涉及 HC 汇总、分组聚合或明细行。
+
+## 适用场景
+
+使用本 reference：
+
+- 查询当前生效方案、方案状态、生效期、支持维度。
+- 查询全量方案清单（含未启用 / 已过期）、启用与停用数量。
+- 查询历史 / 多年方案，按年度取出 `workforce_plan_id`。
+
+不要使用本 reference：用户要 HC、在职、缺编、满编率、分布、Top N、排序、占比、原始明细行等数据，本 reference 不处理；只在用户需要定位方案、确认生效期或拿 `plan_id` / `dimension_lists` 时使用。
+
+## 命令格式
+
+```bash
+# 调用前先看 schema
+people-cli schema corehr.workforce_plan.list
+
+# 查询当前生效方案（默认场景，必须显式传 active=true 只筛选启用方案）
+people-cli corehr workforce_plan list --params '{"active":"true"}'
+
+# 查询全量方案（含未启用 / 已过期），仅在用户明确要历史 / 全部方案时使用
+people-cli corehr workforce_plan list --params '{"active":"false","get_all_plan":"true"}'
+```
+
+参数语义：`active` —— `true` 只获取已启用方案，`false` 获取所有；`get_all_plan` —— `true` 返回所有方案，`false` 仅当前生效。
+
+## 方案查询规则
+
+- **默认显式筛选启用方案**：默认场景必须显式传 `active=true`，只查 `active=true` 且当前日期落在生效期内的方案，不要依赖接口隐式默认；回答必须包含命中数量、方案名称、启用状态、生效期和支持维度（`dimension_lists`）。
+- **全量 / 历史方案**（用户说"所有方案 / 未启用方案 / 过期方案 / 历年方案 / 启用和停用数量 / 先看方案清单"）：显式传 `active=false`、`get_all_plan=true`，分页直到全量；按返回值统计启用 / 未启用数量，输出前 10 个方案示例、状态、生效期、支持维度。
+- **分页约束**：未完成全量分页时必须标注"当前页返回 X 个方案"并展示当前页前 10 个；只有完成分页后才能说"共查询到 X 个方案"。
+- **方案命名词处理**：用户给出年份、官方、预算、方案名称等描述时，只把这些词作为方案列表的检索 / 筛选条件；无法唯一命中方案时列候选让用户确认，禁止把某个年份、固定 `plan_id` 或名称预置为固定方案。
+- **答案来源**：最终答案必须来自 `workforce_plan list` 真实返回；命令示例、执行计划不是答案。无候选时回答"未查询到匹配方案"，多候选时列出候选方案名 / ID / 状态 / 生效期让用户选择。
+
+## 方案对象字段结构与 jq-compatible 样例
+
+`workforce_plan list` 返回的方案对象（`data.items[]`）字段名固定如下，**严禁臆想 `id` / `name` 等字段**：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `workforce_plan_id` | string | 方案唯一 ID，用于 `--plan-id` |
+| `workforce_plan_name` | array | 方案名称，国际化数组 `[{lang,value}]`，非字符串 |
+| `active` | bool | 是否启用 |
+| `start_date` / `end_date` | string | 生效期，如 `2025-01-01` |
+| `dimension_lists` | array | 支持维度，元素 `{key, name:[{lang,value}]}` |
+
+Agent 可以直接按上述字段解析默认 JSON，不强制使用某一种 jq 实现。需要 jq-compatible 表达式时，可参考以下 ID、用户语言名称和生效期提取样例；`<language>` 使用当前回复语言对应的语言代码：
+
+```jq
+.data.items[]
+| .workforce_plan_id as $id
+| ((.workforce_plan_name[]? | select(.lang=="<language>") | .value) // .workforce_plan_name[0].value) as $name
+| "\($id)\t\($name)\t\(.start_date)~\(.end_date)\t active=\(.active)"
+```
+
+执行方式由当前环境决定：可以由 Agent 直接解析，也可以交给 Agent/系统提供的 jq-compatible 能力；若选择 people-cli `--jq`，传入上面的表达式且保持默认 `json`，不要同时传非 `json` 的 `--format` 或 `--output`。样例只规定字段路径和转换口径，不构成 jq 安装或实现依赖。
+
+## 全量 / 历史方案定位
+
+当需要按年度定位方案（如查历年方案清单、取出某年度方案 ID）时：
+
+1. 调用 `workforce_plan list --params '{"active":"false","get_all_plan":"true"}'`，分页直到全量，拉到所有方案（含未启用、已过期）。
+2. 用上节字段路径或 jq-compatible 样例按 `start_date` / `end_date` 定位目标年度方案，取出其 `workforce_plan_id`；同一年度多个方案时结合方案名确认，未唯一命中时列候选让用户选择。
+3. 某年度无对应方案 → 明确输出 `<YYYY 年> 无对应编制方案`，禁止编造或拿邻近年度方案顶替。
+
+> 历史 / 未启用方案只能通过 `workforce_plan_id` 引用，无法用方案名称关键词匹配（名称匹配只作用于当前生效方案）。
+
+## 异常处理
+
+| 场景 | 行为 |
+|---|---|
+| 无生效方案 | 报错 `no active workforce plan covers current date`，提示用户确认日期或换用全量方案查询 |
+| 多个生效方案 | 列出候选方案名 / ID / 状态 / 生效期，让用户指定具体方案 |
+| 未完成全量分页 | 标注“当前页返回 X 个方案”，禁止把当前页当总数 |
+| 方案名 / 关键词无法唯一命中 | 列候选让用户确认，禁止预置固定 `plan_id` 或年份方案 |
+| 认证或 scope 不足 | 复述 CLI 原始错误；认证失败时提示用户检查当前身份，权限不足时提示补齐 `corehr:workforce_plan:read` 后重试；不主动触发登录或身份切换 |