@lark-people/cli 0.0.0-beta.1

package/skills/people-corehr-renewal/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: people-corehr-renewal
+version: 1.16.3
+description: "飞书人事续约/续签：查询续约（合同续签）记录与字段，覆盖合同到期名单、续约状态与流程进展、签署状态、续延、原合同与续签后合同对比、异常冲突排查、数量与分布统计。用户提到续约、续签、不续签、续延、合同到期、合同快到期、到期名单、签署状态、续签评估、renewal 等关键词时必须使用本 skill；仅查员工任职、入离职、异动信息时用 people-corehr。"
+metadata:
+  requires:
+    bins: ["people-cli"]
+  cliHelp: "people-cli corehr --help"
+---
+# 续约信息 (people-corehr-renewal)
+
+独立处理续约相关问题：字段目录、续约记录查询、流程进展、到期名单、主体对比和风险排查。
+
+## 触发条件
+
+- 查续约记录、续签流程、当前状态、反馈截止时间
+- 数量、分布、对比、存在性等统计类问题（多少条/各多少/有没有/哪些）
+- 查哪些续约字段可查、可筛、可排序
+- 导出今天或某时间范围内到期且未完成续约的名单
+- 比较原合同与续签后主体、期限、公司是否一致
+- 排查续延、冲突（含异动在途/离职在途冲突，属本 skill）、撤回、试用期等风险字段
+
+## 硬规则（本节是唯一正本，reference 不重复展开；违反任意一条，答案即视为无效，查询真实性与执行轨迹会被自动校验）
+
+1. **唯一数据通道**：续约数据只能来自 `people-cli` 命令的真实回显。**禁止用 python/脚本/直接 HTTP 请求/历史记忆获取或推算续约数据**；`people-cli` 不可用时不存在任何替代查询方式，只能按"命令不可用"异常模板答复。答案里的每一个事实性断言——数据、字段有无、权限、访问限制——都必须能追溯到本次 CLI 回显或用户原话，追溯不到的整句删掉；典型违规是替 CLI 补一句它从未输出的访问控制/密级/导出限制说明。
+2. **事实题必须真实查询**：数量、名单、存在性、对比、最早/最晚题，必须至少成功执行一次 `+renewal-search` 再作答；字段目录命中、命令草稿、第一页样例、计划性描述都不能替代主查询。条件足够时直接查，不要停在"我可以帮你查"。
+3. **真实查询、可追溯，但不向用户暴露凭据行**：数量/名单/存在性等事实题的每个结论都要能追溯到本次 `+renewal-search` 的真实回显；`query_id` 只能来自 CLI 输出的 Query ID（不可臆造），它与执行轨迹一起被自动校验"是否真的查过"。**不要在给用户的答复里输出「查询凭据」行或 query_id/count/complete 这类技术字段——用户不感知这一层**；查询真实性由执行轨迹核验，不靠答复里自述凭据。
+4. **单员工精确筛选支持工号、empID、姓名转 empID**：续约按员工精确筛选时，若用户直接给工号，用 `employment.employee_number`；若用户直接给 empID，用 `employment`。**如果用户只给姓名、常用名、英文名、拼音或模糊关键词，可先用 `people-cli corehr +query-id-by-name --business-scene renewal --queries '[{"field_api_name":"employment","target_object_api_name":"employment","query_name":"<姓名>"}]'` 解析 empID，再用 `{"employment":"<empID>"}` 查询续约。** 同名多候选必须先让用户确认，禁止默认取第一条；不要再走已下线的员工搜索 shortcut。
+5. **失败 ≠ 0 条**：只有命令真实成功返回（envelope `ok=true`）且命中 0 条时，才能下"0 条/没有记录"的结论。报错、超时、认证失败、命令未调起，一律按异常模板答复，不得降级成 0 条。
+6. **0 条处理流程（按顺序执行）**：拿到 0 条 → 先读输出里的 `hint`，核实筛选值真实存在（工号需用户确认无误；若是姓名链路，则先用 `+query-id-by-name --business-scene renewal` 重新核实 empID；枚举值对照 CLI 报错或 `+renewal-fields-query` 回显的 `enum_options`）→ 核实无误后按空结果模板直接收口。核实后的 0 条是有效结论，不要追加澄清、不要改写口径、不要臆造；**也不要扩大时间范围、放宽筛选条件重查后以新口径作答**——用户点名的时间窗尚未开始、结果必然为 0 时同样按原口径答 0 条（可补一句"该时间段尚未开始"），不得擅自换成更大窗口"顺便"统计。
+7. **纯总数看 `count`，全局名单/分布/穷尽题看是否已覆盖全集**：纯总数题优先信任后端返回的 `total`，CLI 已将其体现在 `count` 中；不要自己翻页数数，也**不要默认先上 `--all-pages` / `--max-records`**。`--count-only` 现在主要表示"只返回统计结果，不返回明细"，不是拿到总数的前提条件。只有 `--group-by`、使用本地后处理过滤（`--renewal-status-exclude` / `--process-status` / `--origin-contract-end-date`）统计，或后端未返回 `total` 时，才按 `complete=false`（等价于 `truncated=true`）判断是否截断。**`--all-pages` / `--max-records` 仅作高级参数，但以下题型一旦出现就必须升级为全量扫描语义，不能停在默认前 10 条：** `哪些/谁/哪几条/全部/所有/全量/导出`、`都是什么/都有哪些/分别是什么/一共有哪几类`、`不为空/为空/双空/组合条件`、`异常原因/异常类型是什么`、`分布情况/各类多少/汇总`、以及任何需要先拉明细再做本地精确过滤的题。**这些题即使用户没说"全量"，也默认要求完整命中集合。** 若普通列表返回条数小于总量，必须继续翻页（必要时 `--all-pages` + `--max-records`）或明确声明当前只是样例，**禁止把第一页、前 10 条或 capped 结果包装成"共有/全部/分布如下"这类全局结论。** **形成答案前必须先做全局语气自检**：只要准备写`仅发现/当前只有/其余都没有/异常类型都是什么/异常原因都是什么/共 N 条里只有`这类全局结论句式，先确认查询已覆盖全集；否则只能改成"当前已取范围内/样例中/至少"口径。**截断处置 SOP（按顺序执行，不可省）**：① 先用 `--max-records 2000` 重试一次；② 仍 `complete=false` 则缩小窗口（拆时间范围、加 `--filter-str` 子条件、按 `--group-by` 拆桶分别查）；③ 仍无法收敛则在答案里**显式声明"该数为下限"**，不得把下限当作精确值汇报，也不得以"截断了所以查不到"代替结论。
+8. **空值/非空类统计与穷尽题**：单字段空值分布直接 `--group-by <字段>` 读 `<empty>` 桶；多字段组合空值（如双空）、"哪些字段不为空/哪些记录异常不为空/哪些人满足组合条件"这类题，必须用 `--select-fields` 拉必要字段后**全量扫描**再本地精确过滤。**这类题里的"哪些/谁/哪几条/都是什么/都有哪些/分别是什么/异常原因是什么/分布情况"天然等价于要完整命中集合，不需要用户额外补一句"全量"。** 若普通列表只返回前 10 条而总量更大，必须继续翻页，不能直接收口。答案写明空值/非空口径；如果最终仍未覆盖全集，只能按"样例/下限/当前已取范围"表述，不能写成全量结论。
+9. **输出净化**：事实题最终答案 = 干净的自然语言结论，按收尾模板交代口径；**不附查询凭据行、不输出 query_id/count/complete 等技术字段**。拒绝、澄清、异常答复按对应模板收口。任何答案都不回显原始 JSON、工具调用片段、shell 文本或"继续查询中"等中间态。枚举 code 的释义（任何语言）同样只认 CLI 回显：中文读行内 `<字段>_label`、分桶 `group_labels`、目录 `enum_options`，英文读 `<字段>_label_en` / `group_labels_en`（有才有）；回显里没给对应语言释义的 code **一律原样展示，禁止自行直译、意译或补翻译括注**（如把 `job_change_conflict` 译成"任职状态变动（Job status change）"，正确中文是回显里的"异动在途"，回显没给英文就保留 code）。
+10. **筛选口径忠于原文**：`filter_str` 的状态/枚举/时间范围严格按用户原话取值——单个值就是单个值。**禁止把单状态扩成多个"等价"值**（如把"已拒绝"查成"已拒绝+已续延+已撤回"），禁止替换成相近枚举，禁止擅自放宽或收紧范围。用户的词同时命中多个枚举候选时先澄清；确需多状态由用户明确列出，不要替他合并终态。
+11. **语义不清先澄清，不臆测硬查**：当用户问题的查询意图**无法明确映射到具体的筛选条件/字段/时间范围/排序口径**时（口径多义、缺必要限定、自造维度、"复杂/紧急/差不多/接近结束/存在问题"等无标准的相对词、泛指词），**先用一句话问清用户到底要查什么，再发起查询**——不要自行假设一个口径就直接查、也不要凭猜测拼命令。**字段目录里能找到一个"看起来相关"的字段，不等于口径已明确**：用户没点名具体字段或阈值时（如把"存在问题"自行定为 `conflict_*`、把"接近结束/快要续完"自行定为某个状态或时间窗），替用户选定口径就是臆测，仍要先澄清。边界：条件已足够、只是带"我组/帮我看看/推进到哪一步"等包装词的，按既有规则**直接查**，不要反向过度澄清；本规则只针对真正落不到查询的语义缺口。
+
+## CLI 已强制的行为（违规会直接报错；不需要背，按报错提示修正即可）
+
+- **字段校验**：`filter_str` / `select_fields` / `sort_field` 用了字段目录外的字段会报"不存在或无字段权限"；目录明确标记不可排序的字段用于 `--sort-field` 也会被拒绝。转述该报错时必须**同时保留两种可能**，不得简化成单边；`filterable=false` 是"可见但不可筛"，另行表述。报错附带的 `closest visible fields` 候选**只用于纠正同一业务字段的写法错误**（拼写、前缀、api_name 误记）；候选与用户点名的业务语义不是同一个字段时，**禁止改用候选替代查询后照常作答**，必须按"字段不存在或无字段权限"模板收口，把改口径的选择权留给用户。
+- **枚举校验**：字段枚举只依赖 `+renewal-fields-query` 对应的 fields 接口回显。`filterable=true` 的字段才可筛；带 `enum_options` 的字段，枚举值只认该命令回显的 `enum_options`，以及 `+renewal-search` 报错里列出的合法值。写 `filter_str` 时可直接传当前显示值或合法 code；未命中且可能多义时先澄清，不要猜。
+- **引用型“类型字段”不是枚举转 code**：`employment.workforce_type`、`employment.employee_type`、`employment.employee_subtype` 这类字段虽然业务名称里带“类型”，但在续约筛选里按**引用型字段**处理，不按普通枚举处理。用户可直接在 `--filter-str` 里写名称，CLI 会先走 `query_id_by_name` 做 **name -> ID**，再把解析后的 ID 回填到筛选条件继续查询。**不要把这类字段解释成“中文显示值自动转枚举 code”，也不要手工猜 code。**
+- **`renewal_progress` 禁筛**：写进 `filter_str` 会被 CLI 直接拒绝；按报错提示改用 `status`、`signature_file.state`、日期、员工等可筛字段，把 `renewal_progress` 放 `--select-fields` 展示。
+- **`--filter-str` 必须是 JSON 对象**：`key:value` 片段、非 JSON 写法会被直接拒绝；日期范围优先用 `--date-field`，手写时用 `<api_name>_start` / `<api_name>_end`。
+- **员工字段默认值与容错**：默认行模式已自动返回 `employee_name` / `employee_number` / `employee_avatar`，并同时带上 `name` / `avatar_url` 这组别名；**用户没明确要求额外员工属性时，不要主动添加 `--employee-fields`。** `employee_name` / `employee_number` / `employee_avatar` 误写进 `--select-fields` 时 CLI 会自动识别为员工补充字段并继续执行。**这些都是输出字段/展示别名，不是筛选 key；`name` / `avatar_url` 也不是 `--employee-fields` 的合法输入。** 按员工筛选时可写 `employment.employee_number`（工号）或 `employment`（empID），不要写裸 `employee_number` / `employment_id`。规范写法是：只有在用户明确要求部门/地点/职级/序列等额外员工属性时，才使用 `--employee-fields`；其中默认别名 `name` / `avatar_url` 只读，不要回填到命令参数里。
+
+## 命令速查表（先查表，再考虑手工组装）
+
+
+| 题型                                               | 命令模板                                                                                                                                             |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 多少条 / 有没有                                    | `people-cli corehr +renewal-search --filter-str '<JSON>' [--count-only]`（`--count-only` 仅用于只返回统计结果）                                       |
+| 分桶统计（各状态多少、通过/待定/拒绝、创建人分布） | `people-cli corehr +renewal-search --group-by <字段api_name> [--filter-str '<JSON>']`（空值自动归 `<empty>` 桶）                                     |
+| 时间范围题（创建/到期/截止）                       | `people-cli corehr +renewal-search --date-field <见时间口径表> --date-start YYYY-MM-DD --date-end YYYY-MM-DD [--count-only]`                         |
+| 近 N 天（最近创建等）                              | `people-cli corehr +renewal-search --date-field created --date-last-days 30 [--count-only]`（日期由 CLI 计算；`--count-only` 只在不需要明细时再加） |
+| 名单 / 明细                                         | `people-cli corehr +renewal-search --filter-str '<JSON>' --select-fields "<api_name,...>"`（默认先看普通列表；**但凡题目要求穷尽命中集合后回答"哪些/谁/哪几条/都是什么/都有哪些/分别是什么/异常原因是什么/分布情况/汇总"**，或要做本地精确过滤/非空判断时，必须继续翻页，必要时追加 `--all-pages` / `--max-records`） |
+| 空值/未填写/非空统计                               | 单字段：`people-cli corehr +renewal-search --group-by <字段>` 读 `<empty>` 桶；多字段组合空值、非空名单、异常不为空、异常原因排查：先 `--select-fields "<字段,...>"` 拉必要字段，再按全量扫描精确过滤（默认前 10 条不够时必须追加 `--all-pages`） |
+| 单员工的续约                                       | 用户直接给工号时，用 `--filter-str '{"employment.employee_number":"<number>"}'`；用户直接给 empID 时，用 `--filter-str '{"employment":"<empID>"}'`；如果只给姓名，先 `+query-id-by-name --business-scene renewal` 解析 empID，再查询 |
+| 今天到期且未完成                                   | `people-cli corehr +renewal-search --origin-contract-end-date today --renewal-status-exclude renewed,extended`（若用户明确要全量名单，再追加 `--all-pages`）                           |
+| 最早 / 最晚 / 排序                                 | 追加`--sort-field <api_name> --sort-order asc|desc`（必须显式传）                                                                                    |
+| 字段目录确认                                       | `people-cli corehr +renewal-fields-query`                                                                                                            |
+| 普通列表（默认）                                   | 不加聚合参数即默认：按 `wk_updated_at desc`（不可排回退 `wk_created_at desc`）返回**前 10 条 + 总数**；只适合预览、样例、前几条名单。**凡是要回答全局名单、异常排查、分布、汇总、哪些/谁/哪几条/都是什么/都有哪些/分别是什么，就不能直接停在默认 10 条。** 只有用户明确要全量名单/导出，或题目天然属于穷尽扫描题时再升级 `--all-pages`；只想隐藏明细时再用 `--count-only`，自定排序用 `--sort-field` |
+
+- 纯总数题直接读返回 JSON 的 `count`；只有分桶或其他非精确聚合统计时，才重点检查 `complete` 是否为 `false`。不要自己翻页数数。
+- 枚举值的释义读 CLI 回显：中文看行内 `<字段>_label`、分桶 `group_labels`，英文看 `_label_en` / `group_labels_en`；没给对应语言释义的 code 原样展示，不要自己翻译。
+- 引用型字段（`employment.department`、`employment.work_location`、`signature_file.template_id.name` 等）可直接写名称，CLI 自动转 ID；转换失败会直接报错，不会静默兜底。
+
+## 标准命令范例（照抄此结构，只换值；行内标注是高频踩坑红线）
+
+不确定怎么拼命令时，先对照下面两条范例的结构，再填自己的值——绝大多数格式报错都是违反了这里的红线。
+
+```bash
+# 范例 A — 单员工的续约名单：用户直接给工号或 empID 时，按精确筛选；只给姓名时先换 empID
+# 红线：姓名链路统一用 `+query-id-by-name --business-scene renewal` 拿 empID，再把 empID 放进 `{"employment":"<empID>"}`；同名多候选必须先澄清。
+#       --filter-str 必须是 JSON 对象，键和值都带双引号；按员工筛选时 key 只能写 `employment.employee_number`（工号）或 `employment`（empID）；不能写裸 `employee_number`，也不能写 `employment_id:xxx`；
+#       默认姓名/工号/头像已自动返回；只有用户明确要求部门/地点/职级等额外员工属性时，才把这些字段放进 --employee-fields，且必须带 employment. 前缀（不能写裸 department，也不能塞进 --select-fields）。
+#       单员工或普通名单题默认先不用 --all-pages；只有用户明确要全量名单/导出时再追加。
+people-cli corehr +renewal-search \
+  --filter-str '{"employment.employee_number":"7766279"}'
+# 或者：
+people-cli corehr +query-id-by-name --business-scene renewal \
+  --queries '[{"field_api_name":"employment","target_object_api_name":"employment","query_name":"张三"}]'
+# 拿到 empID 后：
+people-cli corehr +renewal-search \
+  --filter-str '{"employment":"7536155197170435602"}'
+# 范例 B — 按状态统计条数：只要统计结果时再加 count-only，枚举直接写中文
+people-cli corehr +renewal-search \
+  --filter-str '{"status":"审批中"}' \
+  --count-only
+# 红线：枚举值直接写中文，CLI 自动转 code（不必记 in_progress，更不要猜 completed 这类不存在的 code）；
+#       纯总数题直接读 count；--count-only 只是让输出不带明细。不要默认先加 --max-records；只有 CLI 明确给出 complete=false 时，count 才只是下限，再按规则 7 提级。
+```
+
+## 时间口径（用 --date-field 做选择题）
+
+
+| 用户说法                                 | `--date-field`                               |
+| ---------------------------------------- | -------------------------------------------- |
+| 创建 / 新建 / 只给了时间窗没点名业务日期 | `created`（wk_created_at）                   |
+| 到期 / 原合同结束 / 到期名单、边界、跨度 | `contract-end`（original_contract_end_date） |
+| 续签后合同结束                           | `renewed-contract-end`                       |
+| 反馈截止 / 审批截止                      | `feedback-due`                               |
+| 续延后结束日期                           | `extension-end`                              |
+
+- **时间口径默认值**：用户只说"`某时间段的续约记录`""`2026 年 1 月到 8 月的续约`""`年初到 8 月续约记录`"这类话，而**没有点名到期/原合同结束/续签后合同结束/反馈截止**时，默认就是按 `created` 查；**禁止因为业务上"看起来更像到期"就擅自改成 `contract-end`**。
+- "最近创建/最近新建"未指定窗口时，默认 `created` 近 30 天，并在答案里写明"最近=近 30 天"。
+- "今天更新 / 最近更新 / 谁更新最多"：先 `+renewal-fields-query` 确认字段目录里是否有更新时间/更新人字段；目录里有就按该字段查询，没有就明确说明做不到，**不得偷换成创建时间**。
+- 排序题 `--sort-field` 同样按用户点名的业务日期选（到期=`original_contract_end_date`、创建=`wk_created_at`、反馈截止=`feedback_due_date`），**不要默认按创建时间排**；若 CLI 明确给出 `complete=false`，则"取最早/最晚 N 条"仅在已按该字段正确排序时成立，否则先按规则 7 提级再取。
+- 司龄/工龄满 N 年缺基准日、"快到期/明显拉长/最紧急"缺阈值时先澄清，不要自定规则。
+- `evaluation_result`（评估结果）不是 `status`，空的 `renewal_progress` 不等于"待发起"；查询前先锁定真实字段语义。
+- **原因类字段先过 fields 闸口**：用户问"拒绝原因 / 驳回原因 / 不通过原因 / 撤回原因 / 原因有没有值"这类问题时，**必须先执行 `+renewal-fields-query` 确认当前 fields 集合里是否真的存在对应字段**（如 `reason_for_withdrawal`、`conflict_reason` 等），且语义与用户要的"原因"一致；**字段不存在就立即停止，不得继续发起 `+renewal-search` 主查询，更不得改用 `status` / `evaluation_result` / 其他相近字段代查后照常作答。**
+
+## 拒绝与澄清（优先级固定：拒绝 > 必要澄清 > 直接查）
+
+**拒答归因必须分清两类，不要混着说**：
+
+- **外发政策限制**：用户意图是把数据**送出当前可信边界**（外部合作方/外部邮箱/外发群/对外打包/跨集团对外披露），无论字段本身是否敏感都先按"外发政策不支持"拒绝；理由说"当前不支持对外批量外发这类续约明细"，**不要**说成"字段敏感"或"无权限"。**只有明确出现外部接收方/对外发送对象时，才按本类拒绝。** 用户只说"导出""下载""内部线下流转""线下审批/流转"而**未出现外部接收方**时，默认视为内部使用，不要直接判成外发；若"线下流转"是结论必要条件且内外边界不清，再先澄清是内部还是对外。**`发到我的飞书` / `发我私聊` / `发给我自己` 明确视为内部单接收方发送，可继续执行，不属于"按人批量分发"。** **按人批量分发**（"按人发给各主管""挨个发给负责人"等，即使收件人都在公司内部）同样按本类处理，拒答点明"不支持批量分发，避免信息泄露风险"。
+- **敏感字段限制**：用户意图是**内部使用**但要求拿主观评价/绩效/原件包/全公司排名等敏感口径，按"字段授权/敏感信息不支持"拒绝；理由不要说成"外发不允许"。**识别即拒，不要先查**：请求对象是审批材料/签署文件原件/材料打包（"发我一份""打包给我"），且范围跨团队/跨业务线时，直接按本类拒绝，**不要先去查询记录或确认部门、业务线等筛选字段**，更不要以"筛选字段拿不到"代替敏感材料拒答归因。
+- 同时命中两类时，按"外发政策"为主因收口，并补一句替代方案（聚合统计/脱敏/缩小到内部范围）。
+- 客观风险字段（`conflict_*`、续延、撤回、试用期等）属正常查询范围，不在敏感拒答清单里。**但这条只回答"能不能查"，不回答"查什么"**：用户点名了具体口径（如"有异动在途冲突的""被撤回的"）才直接查；只说"存在问题""有风险""异常"而未点名的，仍按规则 11 先澄清指哪类问题，不要自行替用户选定 `conflict_*` 等字段。
+
+
+| 场景                                                                 | 动作                                                                                                                                                                                                                                                                         |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 给外部合作方/外部邮箱/外部群外发、带外发意图的批量导出               | 拒绝，理由写"当前不支持对外批量外发这类续约明细"（不要先定性成字段敏感），并给聚合统计/脱敏/内部范围替代方案                                                                                                                                                                 |
+| 仅说"导出/下载/线下流转"，但未出现外部接收方或对外发送对象           | 默认按内部使用处理，可继续查询；只有"线下流转"本身影响结论且内外边界不清时，先澄清是内部还是对外                                                                                                                                                                            |
+| 发到我的飞书 / 发我私聊 / 发给我自己                                 | 视为内部单接收方发送，可继续执行；不要套用"按人批量分发"拒绝                                                                                                                                                                                                                |
+| 原件打包、跨团队敏感明细、全公司排名、主观绩效评价/主观风险评分      | 直接拒绝（不要先查询或确认筛选字段），点明"属人事敏感信息，不支持跨团队/业务线批量获取与发送，避免信息泄露"，并给聚合或缩小范围建议（客观的风险字段排查如`conflict_*`、续延属正常查询，不在此列）                                                                            |
+| 跨域明细（离职/试用期等非续约数据）+ 按人批量分发                    | 先按"敏感明细不支持跨团队批量查询与按人分发（避免信息泄露）"拒绝分发诉求，再补一句数据域指引（如基础人事能力）；不要只答"不归本域管"                                                                                                                                          |
+| 主观排序 + 敏感文本判断（"谁写得最差""最复杂说明"）                  | 拒绝，理由写"主观排序/文本判断不支持"，不要改成澄清标准                                                                                                                                                                                                                      |
+| 主观词/相对词无阈值（明显拉长、风险最高、最紧急、快到期、快要续完、接近结束）；"存在问题/有风险"未点名具体字段 | 先澄清阈值、排序字段、时间窗或问题口径，不要自行选定字段替用户决定                                                                                                                                                                                                           |
+| 同名员工多候选；排序标准不明确；"北京的续约""异常续约"等字段口径多义 | 先澄清                                                                                                                                                                                                                                                                       |
+| 按某负责人 / 某 HRBP 负责范围 / 其他维度筛选，但该维度无对应可筛字段 | 先`+renewal-fields-query` 确认该筛选维度有可筛字段；没有就按"字段不存在"异常模板收口并点明此限制，**禁止用时间范围等近似维度替代后照常作答**                                                                                                                                 |
+| 问"拒绝原因 / 驳回原因 / 撤回原因 / 原因有没有值"，但对应原因字段不在当前 fields 集合 | 先`+renewal-fields-query` 确认字段是否存在；**不存在就直接按"字段不存在或无字段权限"异常模板收口**，不得继续发起 `+renewal-search` 主查询，也不得改用 `status` / `evaluation_result` / 其他相近字段替代                                                                                                                                 |
+| 条件已足够，句子带"我组""帮我看看""推进到哪一步"等包装词             | 照常直接查，不要被包装词带回澄清                                                                                                                                                                                                                                             |
+| 未指明团队范围但条件足够                                             | 按当前身份默认可见范围直接查，不追问"你是哪个组"                                                                                                                                                                                                                             |
+| 我组 / 我团队 / 我负责 BU / 我部门 / 我支持范围                      | **点名具体部门**时用 `employment.department` 显式过滤（CLI 自动转 ID），不要用更宽的可见范围代替；没点名具体部门或无稳定负责人字段可筛时，按当前身份默认可见范围先查，并在答案里把范围标成"当前可见范围快照"（该数不等于精确的"我负责"口径）。**禁止把"我们团队/我组"自行改写成"某人所在部门"再去查**；只有团队边界本身是结论必要条件时才澄清 |
+| 空值/非空/双空/待定类统计                                            | 先按已知 code 完成主查询，空值桶用`--group-by` 的 `<empty>` 桶或本地过滤补齐，并在答案里写明口径；不要先停在澄清                                                                                                                                                             |
+
+## 收尾模板（事实题用干净的自然语言收口，不输出查询凭据行 / query_id / count / complete）
+
+- 统计/存在性题：`按[时间字段/范围][主体范围][状态条件]查询，共 N 条[，去重后 M 人]。`（被截断时改述为"至少 N 条（仅为下限）"）
+- 列表题：`按[筛选口径]查到 N 条，按[排序口径]展示前 M 条[；如需全量可继续]。`
+- 空结果：`按[筛选口径]已完成查询，结果为 0 条。`（带筛选条件时补一句"筛选值已核实"）
+- 总数与展示条数用自然语言交代（如"共 100 条，按更新时间倒序展示前 10 条"）；是否截断仅在确为下限时点明，不要把 `complete`/`count`/`query_id` 等字段名抛给用户。
+- 计数口径：续约记录/单据默认按记录数；用户明确问人数或哪些员工时才按员工去重。
+
+## 异常答复模板
+
+异常收口统一为**一段自然语言**，依次交代三件事：为什么这次没法继续查（用用户的业务说法指代条件；多个失败点合并转述，不加小标题、不分点罗列、不回显内部尝试过的命令草稿或猜测的 api_name）→ 本次查询未完成 → 用户下一步可以补什么或改查什么。该结构适用于所有异常类型及其任意组合；下列模板是对应类型的标准说法，可按此结构合并使用。答复只包含用户需要的信息：不解释字段接口等内部机制，也不自证自己没做什么（"我没有改用其他字段"这类话不进答复——行为约束由硬规则和执行轨迹校验，不靠答复自述）。
+
+- 认证/权限失败：`这次续约查询未成功执行，当前被[认证失效/权限限制]阻塞，暂时拿不到可靠结果。你可以先刷新凭证或补充有权限的范围，我再继续查。`
+- 命令不可用/未调起：`这次续约查询没有成功执行，暂时拿不到真实数据，所以不能给出条数或名单（这不代表是 0 条）。请确认 people-cli 可用后让我重试。`
+- 字段不存在或无字段权限（不在 fields 集合）：`当前可见的续约字段里没有[业务说法]相关字段（可能不存在，也可能你没有权限），这次查询未完成。你可以改查[可用字段/更明确口径]，我再继续执行。`
+- 字段存在但不可筛（`filterable=false`）：`[业务说法]字段可以展示但不能用于筛选，这次没有按该条件查询。你可以改用其他条件定位记录，我再继续执行。`
+- 对外批量外发/导出：`这类续约明细当前不支持批量导出给外部合作方或对外发送。若你只需内部使用，我可以在当前可见范围内继续查询；若对外只需共享结果，建议改成聚合统计或脱敏字段。`
+- 内部导出/内部线下流转：`如果你是内部使用或内部线下流转，我可以在当前可见范围内继续查询并整理所需字段；若要对外发送，请先明确接收方和用途，我再按规则判断是否支持。`
+- 发到我的飞书/发我私聊：`可以，我会按你当前可见范围导出并发到你的飞书私聊；这属于内部单接收方发送，不按按人批量分发处理。`
+- 敏感材料批量获取/按人分发：`续约审批材料、签署文件这类原件属于人事敏感信息，当前不支持跨团队/业务线批量获取，也不支持按人批量发送，避免信息泄露风险。如需了解整体情况，我可以提供聚合统计，或在你的可见范围内查询单条记录的状态。`
+- 枚举值多义：`这个说法同时对应多个相近的枚举候选（[候选A/候选B]），我还不能确定你要哪一个。请确认一个，我再继续查。`
+- 主体歧义：`当前主体还不唯一，直接查询可能会拿错人。请补充工号、邮箱或部门，我再继续查。`
+- 查询超时/解析失败：`这次续约查询没有在预期时间内返回可靠结果，我暂时不能安全给你结论。可以改成更小范围、明确字段或分批重查。`
+- 失败后只允许**语义不变的写法修正**：按 CLI 报错改正枚举 code、字段 `api_name` 写法、JSON 格式、员工字段挪到 `--employee-fields` 等，修正后的查询口径必须与用户原问完全一致。**禁止任何改变口径的降级**——不得删掉用户要的筛选条件或展示字段后照常作答、不得换相近字段替代、不得自行缩小范围。修不了写法就按节首结构如实收口，把怎么调整的选择权交给用户，宁可答"没查成"也不答走样的结果。**连续失败止损**：同一写法或同类命令连续失败 2–3 次仍不通过，停止重试——按节首结构如实收口或先澄清，不要靠无限重试堆工具调用。
+
+## 高价值示例
+
+- `2026 年 5 到 6 月的续约有多少条`：`--date-field created --date-start 2026-05-01 --date-end 2026-06-30 [--count-only]`，优先读 `count` 作答；只要统计结果、不需要明细时再加 `--count-only`。只有 CLI 明确给出 `complete=false` 时才按下限口径收口。
+- `2026 年 5 到 6 月各状态分别多少条`：同上时间参数 + `--group-by status`。
+- `2026 年 6 月到期且未续签的续约有哪些`：`--date-field contract-end --date-start 2026-06-01 --date-end 2026-06-30 --filter-str '{"status":"in_progress"}' --select-fields "status,original_contract_end_date,renewal_progress"`（到期≠创建，不要用 created；若用户明确要全量名单再追加 `--all-pages`）。
+- `2026 年年初到 8 月续约记录，只看审批中和已续延两类，异常原因是什么`：这是"`某时间段的续约记录`"口径，**默认按 `created`，不是 `contract-end`**。由于 `status` 不能传数组，应拆成两次查询（审批中 / 已续延），并保持同一时间口径；这是"异常原因是什么"题，必须按全量扫描处理，不能只看默认前 10 条。
+- `待签字的续约文件有哪些`：`--filter-str '{"signature_file.state":"pending_sign"}' --select-fields "status,signature_file.state,original_contract_end_date"`，不要先澄清；只有用户明确要全量名单/导出时再追加 `--all-pages`。
+- `看进行中的续约推进到哪一步`：`--filter-str '{"status":"in_progress"}' --select-fields "status,renewal_progress,feedback_due_date"`；不要用 `renewal_progress` 过滤。
+- `统计评估结果通过、待定、拒绝各多少`：`--group-by evaluation_result`；"待定"读 `<empty>` 桶，并在答案里注明"按未填写/空值口径统计"。
+- `最近谁创建的续约最多`：`--date-field created --date-last-days 30 --group-by wk_created_by`，答案写明"最近=近 30 天"（若报 `wk_created_by` 不存在或无权限，按报错提示先查字段目录确认创建人字段）。
+- `把员工续签评估结果导给外部合作方`：直接拒绝（外发边界），可改提供内部聚合结果。
+- `续延原因不为空的记录`：先 `--select-fields "extension_reason,status"` 拉必要字段，再本地过滤非空；这是穷尽题，若普通列表未覆盖全集，必须继续翻页（必要时 `--all-pages`），不能把前 10 条当完整结果。
+- `2026 年 1 月到 9 月审批中的续约记录哪些异常类型不为空`：`--date-field created --date-start 2026-01-01 --date-end 2026-09-30 --filter-str '{"status":"审批中"}' --select-fields "status,conflict_type,conflict_reason,original_contract_end_date"`；这是"哪些...不为空"题，必须全量扫描后再本地过滤，不能只看默认前 10 条。
+- `帮我看下 2026 年年初到 10 月审批中的续约记录里异常类型都是什么`：这是"`某时间段的续约记录`"口径，默认按 `created`；这是"异常类型都是什么"穷尽题，必须 `--select-fields "status,conflict_type,conflict_reason,original_contract_end_date"` 后全量扫描。**如果没覆盖全集，禁止写"仅发现 1 例/其余都没有/异常类型只有..."这类全局结论。**
+- `全部续签记录里面续约异常类型分布情况`：先判断这是不是全局分布题；答案如果要说"分布情况/各类多少"，就不能基于默认 10 条或 capped 明细手工汇总。要么用已覆盖全集的查询结果，要么明确说明当前只是下限/局部范围。
+- `筛选我下属团队的高潜员工的续约记录`（多失败点合并收口示范）：字段目录确认无"高潜"相关字段且它是结论必要条件，按异常收口结构一段话作答——用业务说法说明缺口、查询未完成、给替代条件（如在当前可见范围内按合同到期时间/续约状态查）；答案里只出现 CLI 真实回显过的限制。
+
+## 参考文档
+
+- [`people-corehr-renewal.md`](references/people-corehr-renewal.md)：命令总览与权限
+- [`people-corehr-renewal-routing.md`](references/people-corehr-renewal-routing.md)：自然语言到参数的映射
+- [`people-corehr-renewal-fields-query.md`](references/people-corehr-renewal-fields-query.md)：字段目录查询
+- [`people-corehr-renewal-search.md`](references/people-corehr-renewal-search.md)：搜索命令参数与示例

package/skills/people-corehr-renewal/references/people-corehr-renewal-fields-query.md

@@ -0,0 +1,62 @@
+# 续约字段查询（`+renewal-fields-query`）
+
+获取当前身份可见、可筛、可排序的续约字段目录，再决定如何构造 `+renewal-search`。硬规则（统一权限口径、实时枚举、`renewal_progress` 禁筛等）以 [`../SKILL.md`](../SKILL.md) 为唯一正本。
+
+## 何时使用
+- 用户要看续约支持哪些字段
+- 字段 API Name、字段类型、是否可筛、是否可排序不确定
+- 用户的问题存在字段歧义，如"当前状态""合同类型""异常"
+
+## 命令
+```bash
+people-cli corehr +renewal-fields-query --as user
+```
+
+## 返回字段
+
+| 字段 | 说明 |
+|---|---|
+| `api_name` | 字段 API Name（查询时唯一可用的字段标识） |
+| `name` | 双语字段名，含 `zh_cn` / `en_us` |
+| `type` | 字段值类型 |
+| `filterable` | 是否支持服务端筛选 |
+| `sortable` | 是否支持排序 |
+| `enum_options` | fields 接口返回给该字段的实时枚举值（`显示值=code`；仅带 `enums` 的字段会有） |
+
+- 字段枚举只读本命令回显的 `enum_options`；它对应的是 fields 接口返回的实时枚举。
+- 字段接口不返回 `operators`。
+- 真正用于查询的是 `field_api_name`，不是 `enum_api_name`。
+
+## 查完字段后的决策
+
+| 情况 | 动作 |
+|---|---|
+| 字段唯一且 `filterable=true`，且不是 `renewal_progress` | 直接进入 `+renewal-search` |
+| 字段唯一但 `filterable=false` | 说明"可见但不可筛"（≠ 不存在或无权限），改用其他可筛字段 |
+| 字段是 `renewal_progress` | 只作返回展示字段；写进 `filter_str` 会被 CLI 直接拒绝（见 SKILL.md "CLI 已强制的行为"） |
+| 两个以上字段都像 | 必须澄清 |
+| 日期/时间范围 | 优先用 `+renewal-search` 的 `--date-field` 选择题，而不是手工拼 `_start` / `_end` |
+| 最早/最晚/排序 | 确认 `sortable=true` 再传 `--sort-field`（CLI 也会校验：排序字段不存在或目录标记不可排序会直接报错） |
+| 枚举型字段 | 只看 `enum_options`；可直接写当前显示值，未命中且多候选时先澄清 |
+
+## 与 `+renewal-search` 的配合
+- `+renewal-search` 会再次校验 `select_fields` 和 `filter_str`（含 `<api_name>_start` / `_end` 范围别名按基础字段校验）。
+- 同一题里字段目录确认最多做一次；拿到真实 `api_name` 后立即进入主查询，不要在字段目录、样例值、命令草稿之间循环。
+- 不要通过 `+renewal-search` 输出猜字段是否可筛；以字段目录里的 `filterable` / `enum_options` 为准。
+
+## 续约表禁用 / 易错字段（写进 `--select-fields` / `--filter-str` 之前对照）
+
+| 字段 / 前缀 | 归属 | 用法 |
+|---|---|---|
+| `employee_name`、`employee_number`、`employee_avatar`、`name`、`avatar_url` | 员工补充列 / 默认别名 | 默认随结果回显。`employee_name` / `employee_number` / `employee_avatar` 误写进 `--select-fields` 时，CLI 会自动剔除并继续执行（不会失败）。**其中 `name` / `avatar_url` 只是结果别名，不可作为 `--employee-fields` 输入，也不可作为 `--filter-str` 的 key；按员工筛选工号用 `employment.employee_number`，empID 用 `employment`** |
+| `employment.*`（如 `employment.department`、`employment.work_location`、`employment.employee_number`） | 员工/任职 | 引用型字段可写在 `--filter-str` 里直接用名称（CLI 转 ID）；要回显时**仅在用户明确要求该额外员工属性、且该字段语义明确时**才用 `--employee-fields employment.xxx`。不要从这条规则推断"凡是 `employment.*` 都适合主动回显"；写进 `--select-fields` 会被 CLI 自动归位到员工查询 |
+| `person.*`（如 `person.preferred_name`） | 人/Person | 同上：只在用户明确要求该人/person 属性时，通过 `--employee-fields` 拉取，不要塞 `--select-fields` |
+| `emp_cus_*`（如 `emp_cus_display.avatar`） | 员工自定义画像 | 仅在用户明确要求对应画像字段时，通过 `--employee-fields` 拉取；默认头像别名已自动返回，无需主动添加 |
+| `renewal_progress` | 续约表 | **禁筛**：只能进 `--select-fields` 展示，写进 `--filter-str` 会被直接拒绝；流程进展过滤改用 `--process-status`（本地过滤）或换用 `status` |
+| `<字段>_label` / `<字段>_label_en` / `group_labels` / `group_labels_en` | CLI 派生展示 | **不是真实字段**，不要写进 `--select-fields` 或 `--filter-str`；它们是 CLI 在 row/group 输出里自动伴生的中文/英文释义列 |
+| 任何不在 `+renewal-fields-query` 回显里的 `api_name` | 不存在或无权限 | CLI 会按硬规则报"不存在或无字段权限"，**不要**改成相近字段或自定别名继续查 |
+
+## 相关文档
+- [`people-corehr-renewal-search.md`](people-corehr-renewal-search.md)
+- [`people-corehr-renewal-routing.md`](people-corehr-renewal-routing.md)
+- [`people-corehr-renewal.md`](people-corehr-renewal.md)

package/skills/people-corehr-renewal/references/people-corehr-renewal-routing.md

@@ -0,0 +1,54 @@
+# 续约执行参考（自然语言 → 查询参数）
+
+本页只负责把用户说法映射成命令参数。硬规则、命令速查表、时间口径、收尾与异常模板的唯一正本是 [`../SKILL.md`](../SKILL.md)，本页不重复展开。
+
+## 统一流程
+1. 先按 [`../SKILL.md`](../SKILL.md) 的"拒绝与澄清"判断分流；可直接查的不要停在澄清。
+2. 用户给姓名、常用名、英文名、拼音或模糊关键词 → 先用 `+query-id-by-name --business-scene renewal --queries '[{"field_api_name":"employment","target_object_api_name":"employment","query_name":"<姓名>"}]'` 解析 empID，再继续续约查询；同名多候选必须先让用户确认。
+3. 字段不明确 → 先 `+renewal-fields-query` 确认真实 `api_name`、`filterable`、`sortable`；同一题最多做一次字段探测。
+4. 按 SKILL.md 命令速查表选模板：统计用 `--count-only` / `--group-by`，时间范围用 `--date-field`；若题目是 `哪些/谁/哪几条`、`都是什么/都有哪些/分别是什么/一共有哪几类`、非空/双空、异常原因、分布/汇总这类穷尽题，明细阶段必须升级成全量扫描语义，不得停在默认列表。
+5. 查询后核对：时间口径、主体、状态是否与题设一致；纯总数题直接读 `count`，只有分桶或其他非精确聚合统计时再检查 `complete`。**若答案要说"全部/共有/分布如下/异常原因如下"，或准备写"仅发现/当前只有/其余都没有/异常类型都是什么"这类全局句式，先确认查询已覆盖全集；否则只能按样例/下限/当前已取范围表述。**
+
+## 常见说法映射
+
+| 用户说法 | 默认处理 |
+|---|---|
+| 当前状态 / 是否进行中 | `status` |
+| 评估通过 / 不通过 / 待定 | `evaluation_result`，不要偷换成 `status`；"待定"用 `--group-by` 的 `<empty>` 桶并注明口径 |
+| 流程进展 / 推进到哪一步 | `renewal_progress` 仅放 `--select-fields` 展示（写进 `filter_str` 会被 CLI 拒绝）；先用 `status`、`signature_file.state`、日期等可筛条件定位记录 |
+| 创建 / 新建 / 某月的续约 | `--date-field created` |
+| 某时间段的续约记录 / 年初到 8 月的续约 | 默认 `--date-field created`；只有明确说"到期/原合同结束"才切到 `contract-end` |
+| 到期 / 原合同结束 | `--date-field contract-end` |
+| 反馈截止 / 审批截止 | `--date-field feedback-due` |
+| 最近创建 / 最近新建（未给窗口） | `--date-field created` 近 30 天，答案注明口径 |
+| 今天更新 / 最近更新 / 谁更新最多 | 先查字段目录确认是否有更新时间/更新人字段；有则按该字段查，没有就明确说明做不到，不得偷换成创建时间 |
+| 待签字 / 已签完 / 签署状态 | `signature_file.state` |
+| 是否续延 / 续延原因 | `extension` / `extension_reason`（非空判断走本地过滤） |
+| 异常续约 | 先确认是 `conflict_type`、`conflict_reason` 还是其他口径，多义先澄清 |
+| 北京的续约 | 先确认是 `employment.work_location` 还是所属公司等字段，多义先澄清 |
+| 司龄 / 工龄满 N 年 | 先澄清计算基准日 |
+| 某人的续约 | 用户直接给工号时，按 `employment.employee_number` 精确筛选；用户直接给 empID 时，按 `employment` 精确筛选；如果只给姓名，先 `+query-id-by-name --business-scene renewal` 解析 empID |
+
+## 员工链路
+- 姓名/关键词 → 先用 `+query-id-by-name --business-scene renewal` 解析 empID，再用 `{"employment":"<empID>"}` 续约筛选。
+- `employee_number` 在续约结果里是展示别名，不是筛选 key；筛选时不要写裸 `employee_number`，只能写 `employment.employee_number`。
+- 如果用户已经拿到了 empID，`--filter-str` 里按 `{"employment":"<empID>"}` 传；不要把 empID 写成裸 `employment_id`。
+- 直接给工号或 empID 可跳过；如果用户已有前端现成的 SearchV2 筛选对象，优先直接复用，不要再把对象拆回姓名解析链路。
+- 单员工且字段明确时直接查续约，不要额外插入字段探测。
+
+## 统计与对比的参数选择
+- 数量/存在性 → 直接查并读 `count`；只要统计结果、不需要明细时再加 `--count-only`。分桶 → `--group-by <字段>`；明细名单默认先普通列表，**但凡题目要穷尽命中集合或做本地精确过滤/汇总时，必须升级 `--all-pages`。**
+- 双状态对比：两次查询必须复用同一 `--date-field`、同一时间范围；纯总数对比直接读 `count`，只有非精确聚合统计时才额外检查 `complete`。
+- 用户只给时间窗、没点名业务日期字段时，两次查询都默认复用 `created`；**禁止一边按 `created`，另一边凭猜测切到 `contract-end`，也禁止把"续约记录"默认理解成"到期记录"。**
+- 首尾/最早/最晚：显式传 `--sort-field` + `--sort-order`，并确认字段 `sortable=true`。
+- 空值/非空/双空：先 `--all-pages --select-fields` 拉必要字段，再本地精确过滤；不要试探 `*`、空串或通配写法。**这类题天然属于全量扫描题，即使用户没说"全量"，也不能停在默认前 10 条。**
+- 异常原因 / 异常类型分布 / 年度汇总 / 异常类型都是什么：只要回答目标是完整结论而不是举例，就按全量或可证明覆盖全集的统计来处理；禁止基于默认页或 capped 结果手工汇总后直接写成全局结论。
+- 记录数 vs 人数：默认记录数；用户明确问"哪些人/多少人"才按员工去重。
+
+## 自检清单（作答前过一遍）
+- 条件足够时是否真的执行了 `+renewal-search`，而不是停在说明或命令草稿。
+- 时间口径是否与题设一致（"到期"是否误用了 created，"某月续约"是否误切到 contract-end）。
+- 统计结论是否先按题型读取了正确字段：纯总数题读 `count`，非精确聚合统计再看 `complete`；`complete=false` 时是否说明了"下限"。
+- 凡是答案用了"全部/共有/分布如下/哪些记录/异常原因如下/异常类型都是什么/其余都没有"等全局表述时，是否先确认已覆盖全集，而不是只看了默认 10 条或 capped 结果。
+- 失败是否按异常模板答复，而不是降级成 0 条。
+- 收尾是否交代筛选口径、计数口径、是否全量。

package/skills/people-corehr-renewal/references/people-corehr-renewal-search.md

@@ -0,0 +1,137 @@
+# 续约搜索（`+renewal-search`）
+
+查询续约记录，并按需补充员工信息。本页只保留命令级用法；硬规则、命令速查表、时间口径、收尾与异常模板见 [`../SKILL.md`](../SKILL.md)。
+
+## 何时使用
+- 查续约记录、状态、流程进展、原合同和续签后合同信息
+- 统计、分桶、到期名单、主体对比、风险排查
+- 事实题、存在性题、对比题的最终落查
+
+## 参数
+
+| 参数 | 说明 |
+|---|---|
+| `--filter-str` | 服务端筛选主入口，**必须是 JSON 对象字符串**（`key:value` 片段会被 CLI 直接拒绝）；`renewal_progress` 写入会被拒绝 |
+| `--date-field` | 时间口径选择题：`created` / `contract-end` / `renewed-contract-end` / `feedback-due` / `extension-end`（也接受真实 api_name）；与 `--date-start` / `--date-end` 配合，由 CLI 合并进 `filter_str` 并自动加入返回字段 |
+| `--date-start` / `--date-end` | 范围边界，`YYYY-MM-DD` 或 `today`；必须与 `--date-field` 同时使用，缺 `--date-field` 会直接报错（防止口径偷换） |
+| `--date-last-days` | "近 N 天"快捷写法（CLI 本地计算日期，不要自己算）；需配 `--date-field`，与 `--date-start/--date-end` 互斥 |
+| `--max-records` | 高级参数：仅在 `--all-pages` / `--count-only` / `--group-by` 已明确提示截断（`complete=false` / `truncated=true`）时，再考虑调高；默认 200，最大 2000 |
+| `--count-only` | **只返回统计结果**：隐藏明细行，只保留 `count` / `complete` 等统计输出。纯总数本身优先由后端 `total` 解决；只有后端无 `total` 或需本地后处理统计时才回退聚合逻辑 |
+| `--group-by` | 按字段分桶计数（如 `--group-by status`），空值归入 `<empty>` 桶；隐含 `--count-only` |
+| `--all-pages` | 高级参数：自动翻页聚合后返回合并明细。默认先用普通列表；只有用户明确要全量名单/导出，或题目本身属于穷尽扫描题（如 `哪些/谁/哪几条`、`都是什么/都有哪些/分别是什么`、非空/双空、异常原因、分布/汇总）时，才必须追加 |
+| `--select-fields` | 返回的续约字段（真实 `api_name`）；显式指定后输出只含这些字段，未返回的字段为 `null`（区分"值为空"和"没请求"） |
+| `--employee-fields` | 员工补充字段，如 `employment.work_location`；`employee_name` / `employee_number` / `employee_avatar` 以及别名 `name` / `avatar_url` 默认随结果返回，无需指定。**用户没明确要求部门/地点/职级/序列等额外员工属性时，不要主动添加 `--employee-fields`。这些是输出字段，不是 `filter_str` 的 key；按员工筛选工号用 `employment.employee_number`，empID 用 `employment`** |
+| `--sort-field` / `--sort-order` | 排序字段与方向（`asc` / `desc`）；首尾/最早/最晚题必须显式传 |
+| `--skip-employee` | 跳过员工信息补充 |
+| `--origin-contract-end-date` | 本地快捷过滤，支持 `today` 或 `YYYY-MM-DD` |
+| `--renewal-status-exclude` | 本地排除续约状态（逗号分隔） |
+| `--process-status` | 本地流程进展过滤，仅匹配 `renewal_progress`（不会匹配 `status`），CLI 自动把 `renewal_progress` 加入返回字段 |
+| `--page-size` / `--page-token` | 普通单页查询的分页控制 |
+
+注意：
+- 本地过滤参数（`--origin-contract-end-date`、`--renewal-status-exclude`、`--process-status`）在聚合模式的内部翻页里同样生效。
+- 纯总数题优先读 `count`：CLI 已优先消费后端返回的 `total`，不要自己翻页数数。
+- 只有分桶统计、使用本地后处理过滤统计，或后端未返回 `total` 时，才需要重点关注 `complete=false`（等价于 `truncated=true`）；此时 `count` 是下限。**不要默认先加 `--all-pages` / `--max-records`**；只有 CLI 已明确提示截断时，才考虑调高 `--max-records`（至多 2000）或缩小范围。**但凡题目要求穷尽命中集合后回答"哪些/谁/哪几条/都是什么/都有哪些/分别是什么/异常原因是什么/分布情况/汇总"，或要先拉字段再本地做空值/非空/组合条件过滤时，即使用户没说"全量"，也必须继续翻页直到覆盖全集；默认前 10 条只可作样例，不能直接收口。** 准备写`仅发现/当前只有/其余都没有/异常类型只有`这类全局句式前，也必须先确认本次查询已覆盖全集。
+- 聚合命中 0 条且带筛选条件时，输出会附带 `hint` 字段，提醒先核实筛选值（工号、枚举 code）真实存在再下"没有记录"的结论。
+- 每次查询输出都带一个随机 `query_id`：行模式在尾部 `Query ID:` 行 + JSON envelope 的 `meta.query_id`，统计模式在 `data.query_id` 字段；它只用于内部执行轨迹校验，不进入面向用户的最终答复。
+- `employee_name` / `employee_number` / `employee_avatar` 误写进 `--select-fields` 时，CLI 自动识别为员工补充字段并继续执行（规范写法是 `--employee-fields`）；同理 `employment.*` / `person.*` / `emp_cus_*` 这些命名空间下的字段误塞 `--select-fields` 也会被自动归位到员工查询。**这层容错只作用于返回字段；不要因此推断"凡是 `employment.*` 都适合主动加进 `--employee-fields`"。只有用户明确要求这些额外员工属性时才添加。** `filter_str` 里按员工筛选，工号用 `employment.employee_number`；如果已知 empID，可用 `employment`。其他不在字段目录里的字段会报 `renewal select field "<字段>" does not exist or you have no field permission for it; stop before SearchRenewal` 并中断。
+- 已废弃的 `--employment-id` 系列参数会直接报错：续约搜索不支持把 employment_id 当成独立 flag；若要按单员工精确筛选，请直接提供工号并使用 `employment.employee_number`，或提供 empID 并在 `filter_str` 里写 `employment`。
+
+## 截断 / 总量 SOP（仅非精确聚合统计适用）
+
+`--group-by`、使用本地后处理过滤统计，或后端未返回 `total` 时，CLI 可能在 `--max-records` 上限处给出 `complete=false` + `truncated=true`。看到这些信号再按下面顺序处理；纯总数题若未出现这些信号，直接按 `count` 作答即可。
+
+| 步骤 | 动作 |
+|---|---|
+| ① 提总量 | 重跑 `--max-records 2000`（封顶值）。不要自己拼翻页 token 累加。 |
+| ② 仍 `complete=false` | 缩小窗口：拆时间（半月/单周）、加 `--filter-str` 子条件、按 `--group-by <字段>` 拆桶后分别重跑统计。 |
+| ③ 仍无法收敛 | 在答案里**显式声明"该数为下限"**，并写明当前窗口/筛选条件。 |
+| ④ 取明细名单 / 穷尽题 | `--all-pages` 同样有 `--max-records` 上限；超过时优先按 ② 拆窗口分批取，避免长名单只拿到前 200 条。凡是"哪些...不为空/为空/双空/组合条件"、"异常原因是什么"、"异常类型都是什么/都有哪些/分别是什么"、"分布情况/汇总"这类需全量扫描后本地过滤或汇总的题，都按本步处理。 |
+
+不要做的事：
+- 把 `complete=false` 下的 `count` 写成"共 N 条"。
+- 看到 `truncated=true` 后改口径继续答（例如把"全公司"改成"前 200 条"而不告知）。
+- 把翻页 token 直接拼回 prompt 里循环，让 LLM 自己累加翻页。
+
+## 推荐字段模板
+
+| 场景 | 推荐 `--select-fields` |
+|---|---|
+| 最小结果 | `status,original_contract_end_date,renewed_contract_end_date` |
+| 到期导出 | `status,renewal_progress,original_contract_number,original_contract_end_date,renewed_contract_number,renewed_contract_end_date,feedback_due_date` |
+| 流程跟踪 | `status,renewal_progress,renewal_intention,evaluation_result,feedback_due_date`；只有 `+renewal-fields-query` 明确返回对应原因字段时，才额外追加 `reason_for_withdrawal` / `conflict_reason` / `conflict_process` |
+| 主体对比 | `status,original_first_party,original_contract_type,original_contract_start_date,original_contract_end_date,renewed_first_party,renewed_contract_type,renewed_contract_start_date,renewed_contract_end_date` |
+| 风险排查 | `status,renewal_progress,extension,extension_reason,contract_end_date_after_extension,conflict_type,conflict_reason,conflict_process,probation_info,offboarding_info,feedback_due_date` |
+
+## 高频示例
+```bash
+# 多少条（纯总数题：优先读后端 total 映射出的 count）
+people-cli corehr +renewal-search --date-field created --date-start 2026-05-01 --date-end 2026-06-30 --count-only
+```
+
+```bash
+# 各状态分别多少条（分桶统计，空值自动归 <empty> 桶）
+people-cli corehr +renewal-search --date-field created --date-start 2026-05-01 --date-end 2026-06-30 --group-by status
+```
+
+```bash
+# 某时间段到期且未续签的名单（"到期"用 contract-end，不要用 created）
+people-cli corehr +renewal-search --date-field contract-end --date-start 2026-06-01 --date-end 2026-06-30 \
+  --filter-str '{"status":"in_progress"}' --select-fields "status,original_contract_end_date,renewal_progress"
+```
+
+```bash
+# 某时间段的续约记录（用户没点名业务日期时，默认按 created，不要擅自改成 contract-end）
+people-cli corehr +renewal-search --date-field created --date-start 2026-01-01 --date-end 2026-08-31 \
+  --filter-str '{"status":"审批中"}' --select-fields "status,conflict_type,conflict_reason,original_contract_end_date"
+```
+
+```bash
+# 今天到期且未续签/未续延
+people-cli corehr +renewal-search --origin-contract-end-date today --renewal-status-exclude renewed,extended --format csv
+```
+
+```bash
+# “我组 / 我团队 / 我负责范围”的名单：未点名具体部门时，按当前身份默认可见范围直接查；不要擅自改成某人的部门
+people-cli corehr +renewal-search \
+  --select-fields "status,renewal_progress,original_contract_end_date,renewed_contract_end_date,feedback_due_date,wk_created_at"
+```
+
+```bash
+# 待签字的续约文件
+people-cli corehr +renewal-search --filter-str '{"signature_file.state":"pending_sign"}' \
+  --select-fields "status,signature_file.state,original_contract_end_date"
+```
+
+注意：
+- 高级参数 `--all-pages` / `--max-records` 默认不前置暴露给用户问题；只有用户明确要全量名单/导出，或 CLI 已明确提示截断时，才升级使用。**例外**：凡是"哪些/谁/哪几条/都是什么/都有哪些/分别是什么" + 本地精确过滤（如异常类型不为空、双空、组合条件）、"异常原因是什么"、"分布情况/汇总"这类问题，即使用户没说"全量"，也必须升级成全量扫描。
+
+```bash
+# 看进行中的续约推进到哪一步（renewal_progress 只展示不过滤）
+people-cli corehr +renewal-search --filter-str '{"status":"in_progress"}' \
+  --select-fields "status,renewal_progress,feedback_due_date"
+```
+
+## 自动名称转 ID
+以下引用型字段可直接把名称写进 `--filter-str`，由 CLI 自动换成 ID（无结果或多结果会直接报错，不静默兜底）：
+`employment.department`、`employment.job_level`、`employment.job_family`、`employment.work_location`、`employment.cost_center`、`employment.workforce_type`、`employment.employee_type`、`employment.employee_subtype`、`signature_file.template_id.name`
+
+其中 `employment.workforce_type`、`employment.employee_type`、`employment.employee_subtype` 虽然业务上叫“类型”，但在续约筛选里仍按**引用型字段**处理，而不是普通枚举字段。用户可以直接写名称，例如：
+`--filter-str '{"employment.employee_subtype":"正式子类型"}'`
+CLI 会先做 **name -> ID**，再把解析后的 ID 回填到筛选条件继续查询；不要把这类字段理解成“中文显示值直接转枚举 code”。
+
+## 枚举字段
+- 字段枚举只依赖 `+renewal-fields-query` 对应的 fields 接口回显：需要确认 code 时读该命令返回的 `enum_options`；可直接写当前显示值，由 CLI 转 code。
+- 未命中时只信 CLI 报错列出的合法值；如果可能有多个候选，先澄清。引用型字段（如 `employment.employee_subtype`）仍走名称转 ID，不按枚举处理；这类字段若解析失败，应提示补更精确名称或直接提供 ID，不要改成猜 code 或按枚举重试。
+- 输出方向同样只认 CLI 回显：结果行内若有 `<字段>_label` / `<字段>_label_en`，以及 `--group-by` 的 `group_labels` / `group_labels_en`，才可用作释义；没给对应语言释义的 code 原样展示，不得自行翻译或补翻译括注。
+
+## 失败处理（命令级）
+- 字段不存在/不可筛/无权限：按 SKILL.md 统一口径答复；不得删掉该字段或换相近字段重试（改变口径的降级被禁止），直接按异常收口结构答复，让用户决定怎么调整。
+- 名称转 ID 失败：提示补更精确名称或直接提供 ID。
+- 员工补充失败/降级：主续约数据照常返回（输出里有 `employee_enrichment_available` 标记）；个别请求字段非法时 CLI 会自动降级保住姓名/工号等基础字段，并在 warning 的 `Hint: relay to the user verbatim` 后给出面向用户的标准说明句——**答复里照抄该句说明缺失，禁止自行归因**（把字段校验失败说成"权限限制"是典型违规，归因只认 CLI 回显原文）。
+- 其余异常答复模板见 [`../SKILL.md`](../SKILL.md)，本页不重复。
+
+## 相关文档
+- [`people-corehr-renewal-fields-query.md`](people-corehr-renewal-fields-query.md)
+- [`people-corehr-renewal-routing.md`](people-corehr-renewal-routing.md)
+- [`people-corehr-renewal.md`](people-corehr-renewal.md)

package/skills/people-corehr-renewal/references/people-corehr-renewal.md

@@ -0,0 +1,39 @@
+# 续约总览
+
+查询续约信息、原合同信息、续签后合同信息，以及按需补充员工信息。
+
+## 命令入口
+```bash
+people-cli corehr +renewal-fields-query [flags]
+people-cli corehr +renewal-search [flags]
+```
+
+## 文档分工
+
+| 目标 | 推荐文档 |
+|---|---|
+| 硬规则、命令速查表、时间口径、收尾与异常模板 | [`../SKILL.md`](../SKILL.md)（唯一正本） |
+| 自然语言到参数的映射 | [`people-corehr-renewal-routing.md`](people-corehr-renewal-routing.md) |
+| 字段目录查询 | [`people-corehr-renewal-fields-query.md`](people-corehr-renewal-fields-query.md) |
+| 搜索命令参数与示例 | [`people-corehr-renewal-search.md`](people-corehr-renewal-search.md) |
+| 枚举 code | `+renewal-fields-query` 回显的 `enum_options`（实时真值来源，无需读取其他离线枚举表） |
+
+## 命令选择
+
+| 用户诉求 | 推荐方式 |
+|---|---|
+| 看字段目录、确认可见/可筛/可排序 | `+renewal-fields-query` |
+| 多少条 / 有没有 | `+renewal-search [--count-only]`（只要统计结果、不需要明细时再加；不要默认先上聚合高级参数） |
+| 分桶统计（各状态、通过/待定/拒绝、创建人分布） | `+renewal-search --group-by <字段>` |
+| 时间范围（创建/到期/截止） | `+renewal-search --date-field ... --date-start ... --date-end ...` |
+| 名单、明细、导出、排风险 | `+renewal-search --select-fields ...`（默认先看普通列表；只有用户明确要全量名单/导出，或题目天然属于穷尽扫描题时，再追加 `--all-pages` / `--max-records`。穷尽扫描题包括：`哪些/谁/哪几条`、非空/双空、异常原因、分布情况、汇总。仅说"内部线下流转/内部使用"按内部导出处理，不直接判外发；`发到我的飞书/发我私聊` 视为内部单接收方发送，可继续执行；只有明确外部接收方时才按对外导出限制收口） |
+
+数量、名单、存在性、分布、对比题最终都必须落到 `+renewal-search`；纯总数题直接读返回的 `count`，只有分桶或其他非精确聚合统计时才重点检查 `complete`。**如果答案要写成"全部/共有/分布如下/异常原因如下"这类全局结论，先确认查询已覆盖全集；默认前 10 条只可作样例，不能直接当全集。**
+
+## 默认补充字段
+`employee_name`、`employee_number`、`employee_avatar` 由 CLI 自动随结果返回；默认行模式还会保留 `name`、`avatar_url` 这组别名，方便下游直接消费头像协议。**`name` / `avatar_url` 只是结果别名，不可作为 `--employee-fields` 输入。** 显式指定员工字段时才使用 `--employee-fields`（`employee_avatar` 映射到 `emp_cus_display.avatar`），且仅在用户明确要求部门/地点/职级/序列等额外员工属性时再添加；不要混入 `--select-fields`。
+
+## 权限
+
+- 只有真实认证失败、scope 失败或明确权限报错时，才能对用户说"权限不足"。
+- 字段不在 fields 集合里时，按 [`../SKILL.md`](../SKILL.md) "CLI 已强制的行为"一节的统一口径答复"不存在或无字段权限"。

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

@@ -0,0 +1,52 @@
+---
+name: people-corehr-workforce-plan
+version: 1.1.0
+description: "当需要用 people-cli 操作 CoreHR 编制规划时调用：适用于查询编制方案、当前生效方案、编制 HC、在职人数、预增、预减、缺编数、满编率、编制汇总、维度分组、Top N、编制明细和原始行数据。用户提到编制、HC、headcount、预增、预减、缺编、满编率、workforce plan、预算方案、方案维度、编制明细时必须使用本 skill。"
+metadata:
+  requires:
+    bins: ["people-cli"]
+  cliHelp: "people-cli corehr --help; people-cli corehr +workforce-plan-detail-summary --help; people-cli corehr +query-id-by-name --help; people-cli corehr workforce_plan list --help; people-cli corehr workforce_plan_detail list --help"
+---
+
+# CoreHR Workforce Plan
+
+本 skill 负责编制规划查询。主文件只做**流程编排与路由**；命令参数、字段、维度、错误码等细节全部在 reference 中，执行前必须先读对应 reference。
+
+> **认证与权限：** 沿用当前 people-cli 运行环境和身份，不预设登录态，也不主动执行登录、初始化或身份切换。只有 CLI 实际返回认证或权限错误时，才复述原始错误并按实际调用补齐公共权限：方案查询使用 `corehr:workforce_plan:read`，明细/汇总使用 `corehr:workforce_detail:read`，名称换 ID 使用 `corehr:corehr:query_id_by_name`。
+
+## 何时使用本 Skill
+
+使用：查询编制方案 / 当前生效方案 / 方案维度；查询编制 HC、在职人数、预增、预减、缺编数、满编率；按方案维度筛选、分组、Top N、分布、占比、对比、趋势；查询编制明细、原始行、缺维度行、过滤全零行；导出编制汇总或明细到 Excel。
+
+不要使用（应转其他 skill）：搜索员工、员工基本信息、任职记录、待入职、异动、离职、员工字段筛选 → `people-corehr`；纯认证 / 初始化 / 切换 `--as` / 处理 scope；用户只是泛化讨论组织设计或预算管理，并未要求查询编制数据。
+
+## 路由表
+
+判断用户要什么结果，路由到唯一对应 reference 并按其步骤执行；不要为简单问题加载无关明细。具体命令、参数、字段、维度解析、错误码都在 reference 内，执行前必须先读对应 reference。
+
+| 用户诉求 | 使用命令 | 必读 reference |
+|---|---|---|
+| 方案列表、当前启用方案、生效期、方案维度 | `workforce_plan list` | [workforce-plan](references/people-corehr-workforce-plan.md) |
+| HC、在职人数、预增、预减、缺编数、满编率、单对象汇总 | `+workforce-plan-detail-summary --format pretty` | [detail-summary](references/people-corehr-workforce-plan-detail-summary.md) |
+| 分组、分布、构成、占比、Top N、排序、对比、趋势 | `+workforce-plan-detail-summary --group-by ...` | [detail-summary](references/people-corehr-workforce-plan-detail-summary.md) |
+| 原始明细行、缺维度行、过滤全零、明细导出 | `workforce_plan_detail list` | [detail-list](references/people-corehr-workforce-plan-detail-list.md) |
+| 导出 Excel / xlsx / 下载结果 | 先判断导出对象是汇总还是明细，再选 summary 或 detail-list | 对应 reference 的「Excel 导出规则」 |
+
+> 命名约定：业务 Shortcut 用 `people-cli corehr +...`；原生 API 用 `people-cli corehr <resource> <method>`，调用前先用 `people-cli schema corehr.<resource>.<method>` 看参数结构。
+
+## 全局红线（跨 reference 通用原则；执行细则见对应 reference）
+
+- **聚合必走 summary**：汇总、分组、排序、Top N、分布、占比、对比一律用 `+workforce-plan-detail-summary`，禁止拉明细后让模型本地分组/求和/排序/截断。
+- **一切动态解析**：方案 ID 和维度 key 从 `workforce_plan list` 的真实返回解析；汇总查询的维度名称转 ID 由 `+workforce-plan-detail-summary` 完成，明细查询按 detail-list reference 调用 `+query-id-by-name --business-scene workforce_plan`，再把唯一匹配的 `matched_id` 写入 `dimension_id_in_datas`。禁止预置固定 plan_id、固定维度映射或固定维度值，也禁止用 `department.search` / `department.list` 替代编制维度解析。
+- **JSON 提取工具中立**：不强制使用 people-cli `--jq`、Agent 自带 jq 或用户环境中的 jq，也不要求额外安装 jq。Agent 可以直接解析默认 JSON；需要 jq-compatible 能力时，只把 reference 中的表达式当作字段路径和转换规则样例，并按当前环境选择执行方式。
+- **业务功能词剔除**：`我的团队`、`我团队`、`我团`、`人员管理` 单独出现或作为入口前缀时，只表示产品入口，不是维度/维度值/筛选条件；只忽略完整词，不截断 `人员类型` 等真实维度词；用户明确说“名为 <词> 的部门/维度值”时才按维度值处理。
+- **多对象独立查询**：多对象并列、比较、求比值时，每个对象必须独立查询、口径一致（相同维度、相同含下级/层级、相同筛选），不能把一次分组结果拆成多个对象的独立事实。同期对比用同一方案；跨年/跨周期对比各自使用对应年度的方案 `plan_id`，只需保持维度与口径一致。
+- **不编造**：未返回的方案名/ID/状态/日期/维度/维度值/人数/分页字段一律回答无法确认或未查询到；空结果按 API 返回如实说明，禁止编造分组或数值。
+
+异常处理（无生效方案、多方案、维度/分组格式错误、scope 不足、空结果等）详见各 reference 的「异常处理」段。
+
+## 参考文档
+
+- [people-corehr-workforce-plan.md](references/people-corehr-workforce-plan.md) — 编制方案查询、生效期、全量/历史方案定位
+- [people-corehr-workforce-plan-detail-summary.md](references/people-corehr-workforce-plan-detail-summary.md) — 编制汇总、分组、排序、Top N、导出
+- [people-corehr-workforce-plan-detail-list.md](references/people-corehr-workforce-plan-detail-list.md) — 编制明细行查询与导出