@lark-people/cli 0.0.0-beta.1

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

@@ -0,0 +1,160 @@
+---
+name: people-corehr-prehire
+version: 3.1.0
+description: "Use when querying CoreHR pre-hire data via people-cli: first inspect option fields, then inspect filter fields/options, then run pre-hire searches with selected return fields and filter conditions."
+metadata:
+  requires:
+    bins: ["people-cli"]
+  cliHelp: "people-cli corehr +prehire-search --help"
+---
+
+# people-corehr-prehire
+
+> **调用边界**：本 skill 只覆盖待入职（pre-hire）场景，统一使用 `people-cli corehr +prehire-*` Shortcut。
+>
+> **元数据流程（最严格）**：
+> - 搜索前必须先调用 `+prehire-fields-query` 获取 Option Fields，确定可返回字段及 `--fields` 别名。
+> - 然后调用 `+prehire-filter-options-query` 获取 Filter Fields，确定可筛选字段左值、右值类型和可选值。
+> - 最后基于前两步整理出的返回字段和筛选条件调用 `+prehire-search`。
+>
+> **禁止事项（最严格）**：
+> - **禁止**在 `--fields` 中拼接带点号的嵌套路径（如 `person_id.preferred_name`）；必须传 [`references/return-fields.md`](references/return-fields.md) 中的别名。
+> - **禁止**根据经验或猜测拼接 `--common-filters`；必须以 `+prehire-filter-options-query` 返回的字段为准。
+
+## references 索引
+
+| 文件 | 用途 |
+| --- | --- |
+| [`return-fields.md`](references/return-fields.md) | Option Fields 的本地参考；实际执行前仍以 `+prehire-fields-query` 返回为准 |
+| [`filter-fields.md`](references/filter-fields.md) | Filter Fields 的本地参考；实际执行前仍以 `+prehire-filter-options-query` 返回为准 |
+| [`command-resolution.md`](references/command-resolution.md) | 命令端内置解析逻辑、`:name` 后缀决策、`option_src` 分流细则 |
+| [`templates.md`](references/templates.md) | 核心命令、`stage_id` 语义、消歧规则、模板、输出规范、搜索构造细则 |
+| [`troubleshooting.md`](references/troubleshooting.md) | 错误速查表、枚举值匹配失败、不支持筛选字段 A/B 分流、多候选 AI 消歧 |
+
+## AI 的三件事
+
+`+prehire-search` 的所有「别名展开 / api_name 映射 / name→ID 解析 / option_src 分流」都由命令层完成（细节见 [`command-resolution.md`](references/command-resolution.md)）。AI 只需要：
+
+1. **先查返回字段**：调用 `+prehire-fields-query`，根据用户想看的列选择 `--fields` 别名。
+2. **再查筛选字段和值域**：调用 `+prehire-filter-options-query`，根据用户筛选条件选择 `--common-filters` 左值和右值。
+3. **选 `:name` 后缀并搜索**：用户给纯数字 ID → 用裸 `api_name`；用户给名称 → 用 `<api_name>:name`；`date_range` / `keyword` / `stage_id` 始终不加后缀。
+
+## 何时使用
+
+只在以下场景使用：
+
+- 获取待入职可返回字段或可筛选字段。
+- 按条件搜索待入职数据，并指定返回字段。
+
+不要使用：
+
+- 查询正式员工、异动、离职、编制。
+- 用户没有查询意图，只是讨论字段含义或业务规则。
+
+## 标准流程（3 阶段）
+
+### 阶段 1：先获取 Option Fields，确定返回字段
+
+调用：
+
+```bash
+people-cli corehr +prehire-fields-query --accept-language zh-CN --format json
+```
+
+处理规则：
+
+1. 从返回的 Option Fields 中找用户想看的字段。
+2. 只把用户明确要求的字段加入 `--fields`，未明确要求时不传 `--fields`，使用命令默认字段。
+3. `--fields` 只能传别名，禁止传带点号的内部字段路径。
+4. 本地 [`return-fields.md`](references/return-fields.md) 只作为排错和字段口径参考；实际可用性以本次 Option Fields 返回为准。
+5. 字段是否可返回以本次 `+prehire-fields-query` 的 Option Fields 为准；如果 Option Fields 返回了对应别名，就可以作为 `--fields` 传入。
+
+### 阶段 2：再获取 Filter Fields，确定筛选左值和右值
+
+调用：
+
+```bash
+people-cli corehr +prehire-filter-options-query --accept-language zh-CN --format json
+```
+
+处理规则：
+
+1. 从返回的 Filter Fields 中找筛选字段左值，即 `--common-filters[].api_name`。
+2. 根据字段的 `option_src` / `options` 判断右值来源：
+   - `local`：右值必须来自该字段 options；用户给名称时用 `<api_name>:name`，命令端解析为 option ID。
+   - 远程数据源：用户给名称时用 `<api_name>:name`，命令端在 `+prehire-search` 内部通过 `query_id_by_name` 解析 ID。
+   - `date_range`：右值为 `["YYYY-MM-DD","YYYY-MM-DD"]`，不加 `:name`。
+   - `keyword` / `stage_id`：右值透传，不加 `:name`。
+3. 用户给纯数字 ID 或 option ID 时用裸 `api_name`；用户给名称时用 `<api_name>:name`。
+4. 不在本次 Filter Fields 中、但在 Option Fields 中的字段，只能作为返回字段，不能直接筛选；按 [`troubleshooting.md`](references/troubleshooting.md) 的“可看不可筛”流程处理。
+5. 用户未显式指定 `stage_id` 时，依赖命令默认 `["preboarding","day_one"]`；用户显式指定时按用户值覆盖。
+
+### 阶段 3：整理后调用 Search，获取筛选条件下的指定字段
+
+把前两阶段结果整理为：
+
+- `--fields "<返回字段别名 CSV>"`
+- `--common-filters '<筛选条件 JSON 数组>'`
+
+调用：
+
+```bash
+people-cli corehr +prehire-search \
+  --fields "<csv>" \
+  --common-filters '<json>' \
+  --accept-language zh-CN \
+  --format json
+```
+
+执行后必须检查输出末尾的 `Has more` 与 `Next page: --page-token <token>`，**仅转述、不主动续拉**。
+
+模板与 `stage_id` 语义见 [`templates.md`](references/templates.md)。
+
+## 解析用户意图
+
+把用户话术拆为三类：
+
+- **返回字段**：将出现在表格里的列，由 Option Fields 决定。
+- **筛选左值**：用什么字段筛，由 Filter Fields 决定。
+- **筛选右值**：筛什么值，由 Filter Fields 的 `option_src` / `options` 决定。
+
+含糊就澄清；候选不唯一就澄清；不要猜。
+
+## 搜索约束
+
+> **执行前守卫**：用户要按「可看不可筛」字段（如社保城市）筛选时，**必须**走 [`troubleshooting.md` 分支 A](references/troubleshooting.md) 的 `--page-size 1` 探查 + `total_number ≤ 1000` 才拉全量流程；详见 [`templates.md` 「可看不可筛」字段执行守卫](references/templates.md#可看不可筛字段执行守卫)。
+>
+> **单次查询原则（强约束）**：默认**只调用一次** `+prehire-search`（命令默认 `--page-size 20`，即返回 20 条）。**禁止**主动翻页 / 重复调用 / 自行扩大 `--page-size`。仅在用户**显式**说「全部 / 翻页 / 拉完 / 继续 / 第 N 页 / 更多」等意图时才追加 `--page-token` 或调高 `--page-size`。`Has more: true` 时仅原样转述给用户，不主动行动。详见 [`templates.md` 单次查询原则](references/templates.md#单次查询原则强约束)。
+
+## 回复用户的两条铁律
+
+1. **单次查询**：每条用户消息**只发起一次** `+prehire-search`，结果原样汇报；用户显式要「全部 / 翻页 / 继续」时才续拉。
+2. **默认隐藏过程**：默认不向用户暴露中间思考、字段匹配过程、命令构造草稿、debug 日志、内部 `api_name`、`option_src` 分流逻辑；但用户明确要求“原始数据 / 原始输出 / 可执行命令 / 入参 / 调试信息”时，必须按用户要求给出对应原始内容或最小必要技术细节。详见 [`templates.md` 输出与过程信息](references/templates.md#输出与过程信息)。
+
+## 错误处理（必读：[`troubleshooting.md`](references/troubleshooting.md)）
+
+执行 `+prehire-search` 前后必须遵守三条最小约束：
+
+- 命令报错或字段不可用时**先查** [`troubleshooting.md`](references/troubleshooting.md)，按对应流程处理；禁止自行降级、丢字段或 keyword 替代。
+- 不在本次 Filter Fields 的字段：按「不支持筛选字段的分流处理」走 A/B 分支。
+- `matches multiple options`：按「多候选命中」走「AI 消歧 → 高置信度自动 `:id` 重跑（必须告知用户）→ 低置信度让用户用 ID 选」。
+
+## 最终检查清单
+
+- [ ] 已先调用 `+prehire-fields-query` 获取 Option Fields。
+- [ ] 已再调用 `+prehire-filter-options-query` 获取 Filter Fields。
+- [ ] `--fields` 中**只有别名**（`name_zh` / `name_en` / `alias`）。
+- [ ] **`--fields` 仅包含用户显式要求的字段**；未明说的字段一律不追加，命令默认字段不重复传。
+- [ ] 字段是否传入 `--fields` 已以本次 Option Fields 为准；Option Fields 未返回的字段未猜测、未兜底。
+- [ ] 筛选字段：`api_name` 精确匹配；歧义已澄清。
+- [ ] **`:name` 后缀已按用户输入选对**：纯数字 ID 用裸 `api_name`；名称用 `<api_name>:name`。
+- [ ] `--common-filters` 每项都是 `{"api_name": "...", "values": [...]}`。
+- [ ] 用户未指定 `stage_id` 时依赖命令默认值；指定时已确认覆盖默认。
+- [ ] 真实执行后检查了 `has_more` / `page_token`。
+- [ ] **本轮只调用了一次** `+prehire-search`；未自行翻页 / 复跑 / 调大 `--page-size`，除非用户显式要「全部 / 翻页 / 继续」。
+- [ ] 用户**显式**要「导出全部字段 / 所有字段 / `all` / `*`」时，已按 [`return-fields.md` 全字段导出](references/return-fields.md#全字段导出) 把本次 Option Fields 支持且非默认的别名一次性拼到 `--fields`，并配 `--page-size 100`，**未**报告"无法一次导出"。
+- [ ] 默认回复只给最终结论；用户明确要求原始数据、原始输出、可执行命令、入参或调试信息时，已按要求回传对应原始内容或最小必要技术细节。
+- [ ] 响应里出现 `total_number` 时，已在回复正文中**显式告知用户具体数值**（详见 [`templates.md` 输出规范](references/templates.md#必须显式回传给用户的元信息)）。
+- [ ] 默认回复中，个人信息对象（如 `direct_manager` / `offer_hr`）只输出 `display_name`/`name` + `employee_number`；仅用户明确要求原始输出时才保留 `avatar` URL、`id` 等原始字段。
+- [ ] 用户要筛「可看不可筛」字段（如社保城市）时：已用 `--page-size 1` 探查 `total_number`，且 `> 1000` 时**立即停止并提示用户**。
+- [ ] 命令报错或出现「字段不支持」「`matches multiple options`」「枚举值未命中」时，已按 [`troubleshooting.md`](references/troubleshooting.md) 处理（禁止丢字段、裸拉全量、随机选候选）。

package/skills/people-corehr-prehire/references/command-resolution.md

@@ -0,0 +1,48 @@
+# 命令端解析逻辑（AI 只传别名）
+
+> `+prehire-search` 在执行时**自动完成**下列工作，AI 不需要在调用前手工解析 ID。
+
+## 命令端会做的 4 件事
+
+1. **`--fields` 别名展开**：把中文/英文别名（如「部门」「直属上级」）自动展开为对应字段，并合并默认字段（`preferred_name` / `worker_id` / `hire_date`）。
+2. **`--common-filters` 别名→`api_name` 映射**：把中文/英文字段名（如「部门」「入职日期」）规范化为后端 `api_name`（如 `department_id` / `onboard_date_range`）。
+3. **`api_name` 后缀决定右值类型**（详见下文 [后缀决策](#后缀决策)）。
+4. **`option_src` 分流**：仅在 `:name` 模式下触发解析（详见下文 [option_src 分流](#option_src-分流)）。
+
+AI 只需要做两件事：
+
+- ① 从 `references/return-fields.md` / `references/filter-fields.md` 挑到正确的别名。
+- ② 根据用户输入是 ID 还是名称，决定是否追加 `:name` 后缀。
+
+> 命令输出包含 `unsupported --fields alias` 或 `unsupported common-filter api_name` 时，按错误信息中的 supported list 修正字段名，**不要**再猜测内部字段名或 `api_name`。
+
+## 后缀决策
+
+| 用户输入 | `api_name` 写法 | 命令端行为 |
+| --- | --- | --- |
+| 纯数字 / option ID | 不加后缀（等价 `:id`） | `values` 原样透传 |
+| 名称（部门名/姓名/岗位名/枚举中文名） | 加 `:name` | 按 `option_src` 把 name→ID |
+| `date_range` / `keyword` / `stage_id` | 始终不加后缀 | 原样透传 |
+
+判断口径：**纯数字串视为 ID，其他一律视为名称走 `:name`**。命令端不会猜测「这串到底是 ID 还是名称」。
+
+示例：
+
+```json
+// 用户给 ID
+{"api_name":"department_id","values":["7552796827847525896"]}
+
+// 用户给名称
+{"api_name":"department_id:name","values":["corehr"]}
+```
+
+## option_src 分流
+
+仅在 `:name` 模式下触发，由命令端自动选择解析路径：
+
+| `option_src` | 典型字段 | 解析方式 |
+| --- | --- | --- |
+| 远程数据源 | `department_id` / `position_id` / `direct_manager_id` / `dotted_line_manager_id` / `offer_hr_id` | 在 `+prehire-search` 内部调用 `POST /open-apis/corehr/v2/common/query_id_by_name`，name→ID |
+| `local` | `work_location_id` / `onboard_method_id` / `company_id` | 调 `GET /pre_hires/filter_field` 取 `options[]`，按中文名/option ID 匹配 |
+| `date_range` | `onboard_date_range` 等 | 固定传 `["YYYY-MM-DD","YYYY-MM-DD"]`，无后缀 |
+| `passthrough` | `keyword` / `stage_id` | 原样透传，无后缀 |

package/skills/people-corehr-prehire/references/filter-fields.md

@@ -0,0 +1,151 @@
+# Pre-hire 可筛选字段（filter_field）
+
+> 本文件是 `+prehire-filter-options-query` 返回内容的本地参考，用于理解 `+prehire-search --common-filters` 左值（`api_name`）与右值（`values`）解析规则。
+> 实际执行搜索前，应先调用 `+prehire-filter-options-query` 获取实时 Filter Fields；严禁臆造字段。
+
+## 解析规则（强约束）
+
+1. 用户给出的中文/英文字段名，必须先在「字段总览」中找到 `api_name`。
+   - 优先精确匹配 `name_zh` / `name_en`；不允许模糊或近义匹配。
+   - 同名歧义（如「国籍」对应 `nationality_id` 与 `nationality_v2_id`）必须向用户澄清。
+2. **`:name` 后缀决定右值类型（ID vs 名称）——AI 必须按用户输入选**：
+   - 用户给的是 ID（纯数字 / option ID）→ 用裸 `api_name`（等价 `:id`），命令端**原样透传**，不做解析。
+     ```json
+     {"api_name":"department_id","values":["7552796827847525896"]}
+     ```
+   - 用户给的是名称（部门名 / 姓名 / 岗位名 / 本地枚举中文名）→ 必须用 `<api_name>:name`，命令端会按 `option_src` 自动把 name→ID。
+     ```json
+     {"api_name":"department_id:name","values":["corehr"]}
+     ```
+   - 命令端**不会**自动猜测「这串到底是 ID 还是名称」；判断口径：纯数字串视为 ID，其他一律视为名称走 `:name`。
+3. 找到 `api_name`、决定后缀后，按 `option_src` 走以下分流（仅 `:name` 模式触发解析）：
+   - `local`：命令端调 `GET /open-apis/corehr/v2/pre_hires/filter_field` 拉 `options[]`，按 option ID、精确名称、大小写不敏感名称、子串匹配依次解析；多候选会报错要求用精确 ID 消歧。
+   - 远程数据源（`/api/v1/hr/datasources/department` / `position` / `employee`）：命令端在 `+prehire-search` 内部调用 `POST /open-apis/corehr/v2/common/query_id_by_name` 把姓名→ID；AI 不单独调用解析命令。
+   - `date_range`：用户必须给出 `[start, end]`，格式 `YYYY-MM-DD`；不需要后缀。
+   - `passthrough`（`keyword` / `stage_id`）：命令直接透传值给后端，不做二次解析；不需要后缀。
+4. 最终下发到 `--common-filters` 的结构必须为：
+   ```json
+   {"api_name":"<api_name>[:name]","values":["<id 或 名称 或透传值>"]}
+   ```
+
+## 字段总览（按 option_src 分组）
+
+### 0. 内建 passthrough — 关键字 / 阶段（命令直接透传）
+
+| api_name | name_zh | name_en | 解析方式 / values 格式 |
+| --- | --- | --- |---------------------------------------------------------------------------------|
+| `keyword` | 关键字 | Keyword | `["<候选人姓名或工号>"]`，命令直接透传；**不要**把它当作除工号/候选人姓名以外的字段筛选                              |
+| `stage_id` | 入职阶段 | Stage | 见下方「stage_id 的完整语义」，取值只允许：`preboarding` / `day_one` / `completed` / `withdrawn` |
+
+> `stage_id` 属于 Shortcut 内建过滤字段：
+> - 用户**未显式**给 `stage_id` 时，命令默认补 `{"api_name":"stage_id","values":["preboarding","day_one"]}`。
+> - 用户**显式**给 `stage_id` 时，命令**不再**合并默认值，按用户传的值走。
+> - keyword只能筛选候选人姓名和工号，不能筛选其他字段；且只能传一个值。不支持工号和姓名同时查询
+
+### A. 远程数据源 — 部门（`option_src=/api/v1/hr/datasources/department`）
+
+| api_name | name_zh | name_en | 解析方式 |
+| --- | --- | --- | --- |
+| `department_id` | 部门 | Department | 由命令端在 `+prehire-search` 内部调用 `query_id_by_name`，`target_object_api_name=department`，`field_api_name=department` |
+
+### B. 远程数据源 — 岗位（`option_src=/api/v1/hr/datasources/position`）
+
+| api_name | name_zh | name_en | 解析方式 |
+| --- | --- | --- | --- |
+| `position_id` | 岗位 | Position | 由命令端在 `+prehire-search` 内部调用 `query_id_by_name`，`target_object_api_name=position`，`field_api_name=position` |
+
+### C. 远程数据源 — 人员（`option_src=/api/v1/hr/datasources/employee`）
+
+| api_name | name_zh | name_en | 解析方式 |
+| --- | --- | --- | --- |
+| `direct_manager_id` | 直属上级 | Direct leader | 由命令端在 `+prehire-search` 内部调用 `query_id_by_name`，`target_object_api_name=employment`，`field_api_name=direct_manager` |
+| `dotted_line_manager_id` | 虚线上级-工作信息 | Dotted-line leader | 由命令端在 `+prehire-search` 内部调用 `query_id_by_name`，`target_object_api_name=employment`，`field_api_name=dotted_line_manager` |
+| `offer_hr_id` | Offer HR | Offer HR | 由命令端在 `+prehire-search` 内部调用 `query_id_by_name`，`target_object_api_name=employment`，`field_api_name=offer_hr` |
+
+> 远程数据源解析后的 ID 直接放进 `values`，不允许把姓名 / 部门名作为 value。
+
+### D. 日期区间字段（`option_src=date_range`）
+
+| api_name | name_zh | name_en | values 格式 |
+| --- | --- | --- | --- |
+| `onboard_date_range` | 入职日期 | Hire date | `["YYYY-MM-DD","YYYY-MM-DD"]`（[start, end]） |
+| `created_date_range` | 流程发起时间 | Process initiation time | 同上 |
+| `seniority_date_range` | 司龄起算日期 | Seniority date | 同上 |
+
+### E. 本地枚举字段（`option_src=local`）
+
+下表的 `api_name` 在 `--common-filters` 中作为左值；右值是**本地枚举 option**，命令端会在执行前调用 `GET /open-apis/corehr/v2/pre_hires/filter_field` 获取 `options[]`，自动把用户输入的中文名或 option ID 映射为 ID。匹配顺序是：option ID → 精确名称 → 大小写不敏感名称 → 子串匹配；匹配失败或有歧义时命令会直接报错。
+
+| api_name | name_zh | name_en |
+| --- | --- | --- |
+| `job_id` | 职务 | Job |
+| `onboard_location_id` | 入职地点 | Onboarding location |
+| `task_status` | 入职任务进展 | Action item status |
+| `job_family_id` | 序列 | Job family |
+| `workforce_type_id` | 人员类型 | Workforce type |
+| `flow_id` | 入职流程 | Onboarding Process |
+| `job_level_id` | 职级 | Job level |
+| `special_intern_id` | 特殊实习生 | Special intern |
+| `reuse_feishu_account` | 是否复用飞书账号 | Whether to reuse Lark account |
+| `onboard_method_id` | 入职方式 | Onboarding method |
+| `company_id` | 合同主体 | Company（「合同主体」与「公司主体」同义，统一走此 api_name） |
+| `pathway_id` | 通道 | Pathway |
+| `work_location_id` | 工作地点 | Work location（「工作城市」与「工作地点」同义，统一走此别名） |
+| `overdue` | 是否逾期 | Overdue |
+| `whether_returnee` | 是否回流 | Whether returnee |
+| `whether_to_pay_social_security_elsewhere` | 是否异地缴纳社保 | Whether pay social security elsewhere |
+| `eligible_for_work_visa` | 是否需要公司支持办理签证 | Eligible for work visa |
+| `chinese_tax_resident` | 是否为中国税务居民 | Chinese tax resident |
+| `rehire` | 是否离职重聘 | Rehire |
+| `whether_the_information_is_abnormal` | 是否信息异常 | Whether the information is abnormal |
+| `additional_nationalities` | 其他国籍 | Additional Nationalities |
+| `nationality_v2_id` | 国籍 | Nationality |
+| `service_company_id` | 任职公司 | Service company（「任职公司」与「所属公司」同义，统一走此 api_name） |
+| `work_shift_id` | 排班 | Work shift |
+| `compensation_type_id` | 薪资类型 | Pay rate type |
+| `job_grade_id` | 职等 | Job grade |
+| `work_country_id` | 工作国家/地区 | Work Country/Region |
+
+## 本地枚举字段值映射
+> AI **不需要、也不允许**把枚举值手工写死在调用里。
+> 用户传中文名（如「校招」「中国大陆」）时命令端会自动匹配为 option ID；匹配失败命令会直接报错并列出支持的选项，AI 据此修正后再执行，**禁止猜测**。
+
+## stage_id 的完整语义（强约束）
+
+`stage_id` 代表**入职流程阶段**，`option_src=passthrough`（命令直接透传，不做二次解析）。
+
+| 值 | 中文含义 | 英文含义 | 说明 |
+| --- | --- | --- | --- |
+| `preboarding` | 入职进行中 | Pre-boarding / onboarding in progress | 流程已发起、尚未到达 Day One |
+| `day_one` | 入职准备就绪 | Day One / onboarding completed and ready | 但没有入职，也是默认口径 |
+| `completed` | 入职流程已完成 | Onboarding completed / finished | 已经入职 |
+| `withdrawn` | 撤销 / 撤回 | Withdrawn / revoked | 候选人退出 |
+
+语义口径：
+- 查"今年待入职的员工" → 按需扩展到 `["preboarding", "day_one"]`。
+- 没有指定入职阶段，默认 `["preboarding", "day_one"]`。
+- 查"入职流程全部走完" → `stage_id=completed`。
+- 查"已入职的候选人" → `stage_id=completed`。
+- 查"放弃入职 / 撤回" → `stage_id=withdrawn`。
+- 查"入职准备就绪" → `stage_id=day_one`。
+
+## 内置默认（命令自动追加）
+
+- 用户**未显式**指定 `stage_id` 时，`+prehire-search` 会自动追加：
+  ```json
+  {"api_name":"stage_id","values":["preboarding","day_one"]}
+  ```
+- 用户**显式**给出 `stage_id` 时，命令**不会**再合并默认值，按用户传的值走。
+- `stage_id` 属于 Shortcut 内建过滤字段，**不在** `filter_field` 元数据接口返回中。
+
+## 易混淆点（必须澄清）
+
+| 用户口语                 | 候选 api_name | 处置                |
+|----------------------| --- |-------------------|
+| 入职地点 vs 工作地点         | `onboard_location_id` / `work_location_id` | 不可互相兜底，必须按用户原话精确取 |
+| 工作地点 vs 工作城市         | `work_location_id` | **同义**，「工作城市」统一映射到 `work_location_id`，无需澄清 |
+| 社保城市 vs 工作地点         | 「社保城市」**不是**可筛选字段 / `work_location_id` | **两者是完全不同的字段，严禁混淆或互相兜底**。「社保城市」`social_security_city` 仅是可返回字段（见 `return-fields.md`），本文件无对应可筛选 `api_name`；用户要求按社保城市筛选时，必须直接回复"社保城市不支持作为筛选条件"，**禁止**改用 `work_location_id` 代替 |
+| 查看北京(没有指定入职地点还是工作地点) | `work_location_id` | 默认使用工作地点          |
+| 任职公司 vs 合同主体         | `service_company_id` / `company_id` | **两者是完全不同的字段，严禁混淆或互相兜底**。「任职公司」与「所属公司」同义 → `service_company_id`；「合同主体」与「公司主体」同义 → `company_id` |
+| 任职公司 vs 所属公司         | `service_company_id` | **同义**，「所属公司」统一映射到 `service_company_id`，无需澄清 |
+| 合同主体 vs 公司主体         | `company_id` | **同义**，「公司主体」统一映射到 `company_id`，无需澄清 |

package/skills/people-corehr-prehire/references/return-fields.md

@@ -0,0 +1,153 @@
+# Pre-hire 可返回字段别名清单
+
+> `--fields` 接受的**别名**清单。命令端已硬编码「别名 → 后端字段」映射，AI 只负责挑别名传入。
+
+## 用法（强约束）
+
+1. 用户口语 → 在「字段总览」精确匹配 `name_zh` / `name_en` / `alias` 任一列。
+2. 把命中行的 **任何一个别名**（推荐用 `name_zh`）追加到 `--fields`，多别名用 `,` 拼接。
+3. 命令端默认始终携带：`preferred_name` / `worker_id` / `hire_date`，不要重复传。
+4. **用户没有显式提到的字段，不要追加**——只保留命令默认字段即可，禁止"贴心"扩展。
+5. **用户显式要全部字段**（"所有字段 / 全部字段 / 导出全部 / all / *"）时，按 [全字段导出](#全字段导出) 一次性拼齐所有 `name_zh`，禁止以"字段太多"为由拒绝。
+6. 别名不命中：先以本次 `+prehire-fields-query` 返回为准确认是否可用；仍不命中时直接告知不支持，禁止猜测。
+
+## 字段可用性口径
+
+字段是否可通过 `--fields` 返回，以本次 `+prehire-fields-query` 返回的 Option Fields 和代码内置 alias 为准。不要维护额外的静态拒绝清单；例如当前代码支持 `薪资类型` / `Pay rate type` / `compensation_type` 作为返回字段别名。
+
+## 字段总览（按业务域分组）
+
+### A. 身份与基础信息
+
+| name_zh | name_en | alias |
+| --- | --- | --- |
+| 工号 | Employee number | `worker_id` |
+| 法定姓名 | Legal name | `legal_name` |
+| 常用姓名 | Preferred name | `preferred_name` |
+| 性别 | Gender | `gender` |
+| 国籍 | Nationality | `nationality` |
+| 其他国籍 | Additional Nationalities | `additional_nationalities` |
+| 民族 / 种族 | Ethnicity / race | `ethnicity_race` |
+| 出生日期 | Date of birth | `date_of_birth` |
+| 年龄 | Age | `age` |
+| 婚姻状况 | Marital status | `marital_status` |
+| 工龄 | Working years | `working_years` |
+| 上家公司 | Former employer | `former_employer` |
+
+### B. 中国大陆户籍信息
+
+| name_zh | name_en | alias |
+| --- | --- | --- |
+| 政治面貌 | Political affiliation | `political_affiliation` |
+| 籍贯 | Native region | `native_region` |
+| 户口类型 | Hukou type | `hukou_type` |
+| 户口所在地 | Hukou location | `hukou_location` |
+| 身份证号码 | National ID number | `national_id_number` |
+
+### C. 联系方式
+
+| name_zh | name_en | alias |
+| --- | --- | --- |
+| 邮箱地址 | Email | `work_email` |
+| 个人邮箱 | Personal email | `personal_email` |
+| 个人电话 | Personal Phone | `phone` |
+
+### D. 工作信息（组织、岗位、上级）
+
+| name_zh | name_en | alias |
+| --- | --- | --- |
+| 部门 | Department | `department` |
+| 部门全路径 | Full path of department | `department_full_path` |
+| 业务线 | Business Line | `cost_center` |
+| 岗位 | Position | `position` |
+| 职务 | Job | `job` |
+| 序列 | Job family | `job_family` |
+| 职级 | Job level | `job_level` |
+| 人员类型 | Workforce type | `employee_type` |
+| 人员子类型 | Workforce sub type | `employee_subtype` |
+| 直属上级 | Direct leader | `direct_manager` |
+| 虚线上级 | Dotted-line leader | `dotted_line_manager` |
+| 任职公司 | Service company | `service_company`（「任职公司」与「所属公司」同义，统一走此别名） |
+| 排班 | Work shift | `work_shift` |
+| 用工类型 | Worker type | `employment_type` |
+| 招聘类型 | Recruitment type | `recruitment_type` |
+
+### E. 工作地点与办公
+
+| name_zh | name_en | alias |
+| --- | --- | --- |
+| 工作地点 | Work location | `work_location`（「工作城市」与「工作地点」同义，统一走此别名） |
+| 工作国家/地区 | Work Country/Region | `work_country` |
+| 办公地点 | Office location | `office_location` |
+| 办公地址 | Office address | `office_address` |
+| 入职地点 | Onboarding location | `onboarding_location` |
+| 入职地址 | Onboarding address | `onboarding_address` |
+| 社保城市 | Social security city | `social_security_city` |
+
+### F. 入职流程与状态
+
+| name_zh | name_en | alias |
+| --- | --- | --- |
+| 入职日期 | Hire date | `hire_date` |
+| 入职流程 | Onboarding process | `process_id` |
+| 入职状态 | Onboarding status | `onboarding_status` |
+| 入职方式 | Onboarding method | `onboarding_method` |
+| 签到方式 | Check in method | `check_in_method` |
+| 签到时间 | Check in time | `check_in_time` |
+| 入职任务是否逾期 | Overdue | `is_overdue` |
+| Offer HR | Offer HR | `offer_hr` |
+| 是否离职重聘 | Rehire | `rehire` |
+| 是否变更审批中 | Whether in modify process | `in_modify_process` |
+| 流程发起时间 | Process initiation time | `wk_created_at` |
+| 司龄起算日期 | Seniority date | `seniority_date` |
+
+### G. 工时与薪资
+
+| name_zh | name_en | alias |
+| --- | --- | --- |
+| 工时制度 | Working hours | `working_hours_type` |
+| 工作日历 | Working calendar | `working_calendar` |
+| 周工作时长 | Weekly working hours | `weekly_working_hours_v2` |
+| 合同主体 | Company | `company`（「合同主体」与「公司主体」同义，统一走此别名） |
+
+### H. 试用期与合同
+
+| name_zh | name_en | alias |
+| --- | --- | --- |
+| 试用期时长 | Probation period | `probation_period` |
+| 试用期开始日期 | Probation start date | `probation_period_start_date` |
+| 试用期预计结束日期 | Probation expected end date | `probation_period_end_date` |
+| 合同类型 | Contract type | `contract_type` |
+| 签订类型 | Signing type | `signing_type` |
+| 期限类型 | Duration type | `duration_type` |
+| 合同开始日期 | Contract start date | `contract_start_date` |
+| 合同预计结束日期 | Contract end date | `contract_end_date` |
+
+## 同名歧义处理
+
+| 用户口语 | 候选 | 处置 |
+| --- | --- | --- |
+| 邮箱 | A 域「邮箱地址」 vs C 域「个人邮箱」 | 询问用户要工作邮箱还是个人邮箱 |
+| 入职地点 vs 工作地点 | E 域两行 | 不可互相兜底，必须按用户原话精确取 |
+| 社保城市 vs 工作地点 | E 域「社保城市」`social_security_city` vs「工作地点」`work_location` | **两者是完全不同的字段，严禁混淆或互相兜底**；用户说「社保城市/社保所在地」只取 `social_security_city`，说「工作地点/工作城市」只取 `work_location` |
+| 工作城市 vs 工作地点 | 同为 E 域「工作地点」`work_location` | **同义**，统一映射到 `work_location`，无需澄清 |
+| 任职公司 vs 合同主体 | D 域「任职公司」`service_company` vs G 域「合同主体」`company` | **两者是完全不同的字段，严禁混淆或互相兜底**。「任职公司」与「所属公司」同义 → 只取 `service_company`；「合同主体」与「公司主体」同义 → 只取 `company` |
+| 任职公司 vs 所属公司 | 同为 D 域「任职公司」`service_company` | **同义**，统一映射到 `service_company`，无需澄清 |
+| 合同主体 vs 公司主体 | 同为 G 域「合同主体」`company` | **同义**，统一映射到 `company`，无需澄清 |
+
+## 失败兜底
+
+- 字段未出现在本表：直接回复"该字段不在 pre-hire 可返回字段中，请确认是否拼写正确或换一个字段名"
+
+## 全字段导出
+
+用户**显式**要求「全部字段 / 所有字段 / 导出全部 / `all` / `*` / 完整信息」时，按以下步骤一次性拉全：
+
+1. **拼接 `--fields`**：把「字段总览」中**每一行**的 `name_zh`（推荐用中文别名，最稳）以英文逗号拼接成一个字符串。**跳过**：
+   - 默认字段（`preferred_name` / `worker_id` / `hire_date`）—— 命令端会自动携带；
+   - 本次 Option Fields 未返回且代码 alias 不支持的字段。
+2. **同时配** `--page-size 100` 与（如需要）`--accept-language zh-CN`。
+3. 一次调用即可拿到该页全部字段。`Has more: true` 时按 [`templates.md` 单次查询原则](templates.md#单次查询原则强约束) 决定是否续拉。
+
+> 不要因为别名清单"看起来太长"就拒绝执行；命令端会自动 alias→sub_field 展开 + 去重 + 合并默认字段，传整列 `name_zh` 是支持的。
+> 若用户只要"主要字段 / 常用字段"等模糊措辞，请反问澄清后再执行，**禁止**自行裁剪。