@lark-people/cli 0.0.0 → 0.0.1

package/skills/people-hire/references/people-hire-job-requirement.md

@@ -0,0 +1,217 @@
+# job-requirement
+
+招聘需求查询场景，覆盖需求列表、需求编号、需求状态、需求人数、招聘负责人等能力。
+
+> **字段来源：** 本文中的输入输出字段以 `people-cli hire +job-requirement-list --help` 为准；底层 schema 仅在 reference/help 未覆盖字段时用于核对。
+> **Shortcut 约束：** 查询招聘需求列表必须使用 `people-cli hire +job-requirement-list`，默认输出 `--view summary` 紧凑表格；用户要求特定字段时用 `--fields`，只有用户明确要求完整结构时才使用 `--view full`。
+
+## 适用意图
+
+当用户出现以下表达时，优先使用本场景：
+
+- "查招聘需求"
+- "查招需 / 需求池 / 招需草稿"
+- "我负责的招聘需求 / 我负责的招需"
+- "按招需短码或 ID 找需求"
+- "看看哪些需求进行中 / 已完成 / 已超期"
+- "本季度指定部门各招需关联了哪些职位，每条招需还差几个名额"
+
+## 意图和命令索引
+
+| 用途 / 何时使用 | 命令 | 说明 |
+|---|---|---|
+| 查询招聘需求列表、需求草稿、需求编号、状态、人数、负责人 | `people-cli hire +job-requirement-list` | 默认裁剪表格输出 |
+| 查询我负责的招聘需求 | `people-cli hire +job-requirement-list --mine --user-id-type open_id` | Shortcut 内部获取当前登录用户 `data.open_id` 并作为招聘负责人 ID，写入底层 body 的 `recruiter_id_list` |
+| 查询某招聘负责人负责的招聘需求 | `people-cli hire +job-requirement-list --recruiter-id <open_id> --user-id-type open_id` | 指定招聘负责人 open_id，`--recruiter-id` 映射到底层 body 的 `recruiter_id_list` |
+| 查询招需关联职位和剩余名额 | `people-cli hire +job-requirement-list --with-linked-jobs --fields requirement_name,progress,linked_jobs,head_count,filled_count,remaining_count` | Shortcut 使用招需返回的 `job_id_list` 精确补职位名称，不反向扫描职位列表 |
+
+## 固定查询流程
+
+1. **识别是否为需求视角**
+   - 只要用户问的是招需、需求池、需求编号、需求状态、需求人数，就走本接口。
+   - 不要误用职位接口代替招聘需求接口。
+2. **必须使用 Shortcut**
+   - `+job-requirement-list` 会自动区分 query 与 request body。
+   - 用户要查"我负责的招聘需求 / 我负责的招需"时，执行 `people-cli hire +job-requirement-list --mine --user-id-type open_id --page-size 5`。
+   - Shortcut 内部会调用 `GET /open-apis/authen/v1/user_info`，读取 `data.open_id` 并写入底层 `recruiter_id_list`。
+   - 不要手动使用 `people-cli auth status` 或 `people-cli api GET /open-apis/authen/v1/user_info --as user` 获取当前用户信息。
+   - 用户要查"某招聘负责人负责的招需"时，使用用户提供或已解析出的负责人 open_id 传 `--recruiter-id <open_id> --user-id-type open_id`。
+   - 如果当前用户信息不可用，停止继续拼接依赖当前用户的参数；不要猜测 open_id，也不要先拉全量招需再按负责人名称过滤。
+   - 用户给出部门、招需名称/编号/负责人关键词时，优先使用 `--department` / `--department-id` / `--keyword`，不要手动拉页后过滤。
+   - 用户问"各招需关联了哪些职位 / 每条招需还差几个名额"时，加 `--with-linked-jobs` 并使用 `--fields requirement_name,progress,linked_jobs,head_count,filled_count,remaining_count`；不要先拉全量职位再由模型手工拼接。
+   - 禁止直接调用原生 `job-requirement list`；自定义字段需求使用 `--fields`，完整结构需求使用 `--view full`。
+3. **识别需求状态过滤**
+   - 用户说"进行中的招需 / 进行中招聘需求"，按 `display_progress=2` 过滤。
+   - 用户说"未开始 / 已取消 / 已暂停 / 已完成 / 已超期"，分别按 `display_progress=1/3/4/5/6` 过滤。
+   - `display_progress` 是返回字段；只有当前 `people-cli schema hire.job-requirement.list` 明确暴露同名入参时，才可下推到 `--data`。如果 schema 未暴露状态入参，使用 Shortcut 的 `--display-progress` 触发 CLI 受控扫描，不要手动翻页过滤。
+4. **按输出层级回复**
+   - 默认先返回 `5` 条需求摘要列表，使用 Shortcut 默认表格输出。
+   - 默认 CLI 输出列为 `Requirement Name`、`Requirement Code`、`Progress`、`Department`、`Recruiters`、`Head Count`，并保留 `Linked Jobs`、`Filled Count`、`Remaining Count` 等按需分析列；Shortcut 返回中仍保留 `Requirement ID` 供后续下钻使用。
+   - 回复用户时可把 CLI 列名转成中文展示名；写 `--fields` / `--where` 时优先使用下方稳定字段别名，不要使用中文展示名或嵌套 jq 路径。
+   - `+job-requirement-list` 默认已经裁剪为紧凑表格；用户要求自定义字段时使用 `--fields`，禁止调用原生 `job-requirement list`。
+   - 如果当前页之外还有更多数据，CLI/Shortcut 输出的 `page_token` 供 skill/agent 内部继续翻页；最终回复用户时只提示"还有更多数据"，不要展示 `page_token`。
+   - 如果用户明确指定查询后过滤条件（如 `XX天内`、`全部`、`XX状态`、`我的XXX`），使用 `--where` / `--mode` / `--limit` / `--scan-page-limit` 让 Shortcut 受控扫描；不要在最终回复用户时展示 `page_token`。
+   - 对"查看进行中的招需"这类状态过滤，默认通过 `--display-progress 2` 在 CLI 内按受控预算补齐结果；不要把第一页过滤后的 2/3 条直接当最终结果。
+   - 用户明确要求完整字段结构时，再返回完整 `items[]` 字段。
+   - 用户只关心少数字段时，直接使用 `+job-requirement-list` 的默认表格输出。
+5. **再决定是否继续**
+   - 如果接口返回 `has_more=true`，默认停在当前页；只有用户明确要求继续时才使用 `page_token`，查询后过滤一律走 Shortcut 受控扫描参数。
+   - 多条结果时优先让用户继续缩小条件，不要一次性倾倒所有字段。
+
+## 标准输入
+
+### Shortcut Query 参数
+
+以下字段由 `+job-requirement-list` 映射到底层 `job-requirement.list` query：
+
+| 字段 | 位置 | 类型 | 说明 |
+|---|---|---|---|
+| `--user-id-type` | query | enum | `user_id` / `union_id` / `open_id` |
+| `--department-id-type` | query | enum | `open_department_id` / `department_id`；使用 `--department-id` 时未显式指定则默认 `open_department_id` |
+| `--job-level-id-type` | query | enum | `people_admin_job_level_id` / `job_level_id` |
+| `--job-family-id-type` | query | enum | `people_admin_job_category_id` / `job_family_id` |
+| `--employee-type-id-type` | query | enum | `people_admin_employee_type_id` / `employee_type_enum_id` |
+
+### Shortcut Request Body 参数
+
+以下字段由 `+job-requirement-list` 映射到底层 `job-requirement.list` request body：
+
+| 字段 | 位置 | 类型 | 说明 |
+|---|---|---|---|
+| `--page-token` | body | string | 页码标识 |
+| `--page-size` | body | int | skill 默认 `5`，最大 `20` |
+| `--create-time-begin` | body | string | 起始创建时间，支持毫秒时间戳或日期/相对时间字符串 |
+| `--create-time-end` | body | string | 截止创建时间，支持毫秒时间戳或日期/相对时间字符串 |
+| `--id` | body | repeatable string | 招需 ID 列表 |
+| `--short-code` | body | repeatable string | 招需短码列表 |
+| `--keyword` | internal filter | string | 招需关键字过滤，会在需求名称、编号、部门、负责人等摘要字段中匹配 |
+| `--department` | internal filter | string | 部门名称包含过滤 |
+| `--department-id` | internal filter | string | 部门 ID 过滤，必须传显式部门 ID；ID 类型跟随 `--department-id-type`，未指定时默认 `open_department_id` |
+| `--recruiter-id` | body | repeatable string | 招聘负责人 ID 列表，对应 `recruiter_id_list`，用于查询指定负责人负责的招聘需求；支持传 `self` 表示当前用户 |
+| `--mine` | internal | bool | 查询"我负责的招聘需求/招需"时使用；Shortcut 内部获取当前用户 `data.open_id` 并写入 `recruiter_id_list` |
+| `--progress` | internal filter | enum | `--display-progress` 别名；需求状态过滤，支持 `1-6`、英文别名或中文状态 |
+| `--display-progress` | internal filter | enum | 需求状态过滤，支持 `1-6`、英文别名或中文状态 |
+| `--with-linked-jobs` | internal enrichment | bool | 用招需返回的 `job_id_list` 精确查询职位详情补齐 `linked_jobs`；`linked_job_ids` 直接来自招需列表，不反向扫描职位列表 |
+| `--view` | - | enum | `summary` 默认裁剪视图；`full` 原始字段视图 |
+| `--fields` | - | string | 逗号分隔字段名，如 `requirement_id,requirement_name,progress,recruiters` |
+| `--where` | - | string | 查询后过滤表达式，如 `department contains Brand; progress=进行中` |
+| `--limit` | - | int | 最多返回的匹配行数，默认等于 `--page-size` |
+| `--scan-page-limit` | - | int | 查询后过滤最多扫描源页数，默认由 Shortcut 控制 |
+| `--mode` | - | enum | `list` / `exists` / `count` / `aggregate` |
+| `--group-by` | - | string | `--mode aggregate` 时按哪个字段聚合 |
+
+> 触发 `--where` / `--mode count|aggregate` / `--display-progress` 类内部扫描，或显式 `--limit` 大于 `--page-size` 时，Shortcut 会自动调大底层源接口 `page_size` 以提升过滤效率；最终展示仍按 `--limit` / 默认 `--page-size` 裁剪。
+
+## 标准输出
+
+底层 `job-requirement.list` 返回 `items[]`。`+job-requirement-list` 默认会把列表裁剪成表格友好的摘要；自定义字段使用 `--fields`，完整结构使用 `--view full`：
+
+| 字段 | 类型 | 用途 | 说明 |
+|---|---|---|---|
+| `id` | string | 内部关联 | 招需 ID，默认不展示 |
+| `name` | string | 默认展示 | 需求名称 |
+| `short_code` | string | 默认展示 / 内部关联 | 需求编号 |
+| `display_progress` | int | 默认展示 | 需求状态，`1`=未开始，`2`=进行中，`3`=已取消，`4`=已暂停，`5`=已完成，`6`=已超期 |
+| `department` | object | 默认展示 | 需求部门信息 |
+| `recruiter_list` | array | 默认展示 | 需求负责人列表 |
+| `head_count` | int | 默认展示 | 需求人数 |
+| `linked_jobs` / `linked_job_ids` | string | 按需展示 / 过滤 | `linked_job_ids` 直接来自 `job_id_list`；需要职位名称 `linked_jobs` 时使用 `--with-linked-jobs` |
+| `filled_count` | string | 按需展示 | 已占用/已满足名额；接口未返回时为空 |
+| `remaining_count` | string | 按需展示 | 剩余名额；优先读接口返回字段，必要时用 `head_count - filled_count` 计算 |
+
+如需进一步分析，可按需补充以下字段：`requirement_id` / `id`、`requirement_name` / `name`、`department_id`、`recruitment_type`、`employee_type`、`max_level`、`min_level`、`sequence`、`head_count`、`search`。这些字段可用于 `--where` 或显式 `--fields`，但不会出现在默认展示列中。CLI 兼容 `headcount` 等模型常见写法，但生成命令时仍优先写稳定别名 `head_count`。
+
+### 需求状态枚举与过滤
+
+| 用户说法 | `display_progress` | 处理方式 |
+|---|---|---|
+| 未开始 | `1` | 使用 `--display-progress 1` 触发 Shortcut 受控扫描 |
+| 进行中 | `2` | 使用 `--display-progress 2` 触发 Shortcut 受控扫描，默认按 `--limit` / `--scan-page-limit` 控制结果 |
+| 已取消 | `3` | 使用 `--display-progress 3` 触发 Shortcut 受控扫描 |
+| 已暂停 | `4` | 使用 `--display-progress 4` 触发 Shortcut 受控扫描 |
+| 已完成 | `5` | 使用 `--display-progress 5` 触发 Shortcut 受控扫描 |
+| 已超期 | `6` | 使用 `--display-progress 6` 触发 Shortcut 受控扫描 |
+
+> 状态过滤必须交给 Shortcut 的受控扫描完成，不要只过滤第一页。以"查看进行中的招需"为例：使用 `--display-progress 2 --limit 5`，Shortcut 会在 `--scan-page-limit` 预算内继续扫描，直到得到 5 条进行中招需或预算/数据耗尽。
+
+分页状态字段（CLI/Shortcut 需要输出给 skill/agent 内部判断和续查，默认不对用户展示 `page_token`）：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `has_more` | bool | 是否有下一页 |
+| `page_token` | string | 内部翻页页码，CLI 可见，最终回复用户时默认隐藏 |
+
+## 输出
+
+### 默认展示字段
+
+`+job-requirement-list` 默认回复会整理为表格友好的列表，并在返回中保留后续下钻需要的内部 ID：
+
+| CLI 列 | 稳定字段别名 | 用户回复含义 | 来源字段 |
+|------|------|------|------|
+| `Requirement ID` | `requirement_id` / `id` | 招需 ID，默认不向用户展示 | `id` |
+| `Requirement Name` | `requirement_name` / `name` / `requirement` | 需求名称 | `name` |
+| `Requirement Code` | `requirement_code` / `short_code` | 需求编号 | `short_code` |
+| `Progress` | `progress` | 需求状态 | `display_progress` |
+| `Department` | `department` | 需求部门 | `department` |
+| `Department ID` | `department_id` | 需求部门 ID，默认不向用户展示 | `department.id` / `department_id` |
+| `Recruiters` | `recruiters` / `recruiter` | 需求负责人 | `recruiter_list` |
+| `Head Count` | `head_count` | 需求人数 | `head_count` |
+| `Linked Jobs` | `linked_jobs` | 关联职位 | 接口字段，或 `--with-linked-jobs` 基于 `job_id_list` 精确查询职位详情得到 |
+| `Linked Job IDs` | `linked_job_ids` / `job_ids` | 关联职位 ID，默认不向用户展示 | 招需列表 `job_id_list` |
+| `Filled Count` | `filled_count` | 已占用/已满足名额 | 接口字段 |
+| `Remaining Count` | `remaining_count` | 剩余名额 | 接口字段或 `head_count - filled_count` |
+
+> `--fields`、`--where`、`--group-by` 使用稳定字段别名或 CLI 列名。最终回复用户时可使用中文名，但除非用户明确指定，不要直接展示招需 ID。`--where` 多条件优先用分号分隔，CLI 兼容英文 `AND`，但不支持 `OR`。若用户要求完整字段结构，继续按上方 `items[]` 完整输出返回。
+
+## 所需权限
+
+| 方法 | Scope |
+|---|---|
+| `job-requirement.list` | `hire:job_requirement:readonly`；使用 `--with-linked-jobs` 时还需要 `hire:job.composite_info:readonly` |
+
+## 示例
+
+```bash
+# 查询最近创建的招聘需求
+people-cli hire +job-requirement-list --page-size 5
+
+# 按招需短码查询
+people-cli hire +job-requirement-list --short-code xx1 --page-size 5
+
+# 查询我负责的招聘需求
+people-cli hire +job-requirement-list --mine --user-id-type open_id --page-size 5
+
+# 查询某招聘负责人负责的招聘需求
+people-cli hire +job-requirement-list --recruiter-id ou_xxx --user-id-type open_id --page-size 5
+
+# 查看进行中的招需：Shortcut 受控扫描，默认返回最多 5 条
+people-cli hire +job-requirement-list --display-progress 2 --page-size 5 --limit 5
+
+# 确认 Brand 部门是否有进行中的招需
+people-cli hire +job-requirement-list --department Brand --progress 进行中 --mode exists --limit 1
+
+# 按招需名称/编号/部门/负责人关键词查询
+people-cli hire +job-requirement-list --keyword Brand --limit 5
+
+# 查询指定部门招需关联职位和剩余名额
+people-cli hire +job-requirement-list --department-id <department_id> --with-linked-jobs --fields requirement_name,progress,linked_jobs,head_count,filled_count,remaining_count --limit 10 --scan-page-limit 10
+
+# 按需求状态做聚合摘要，避免拉完整明细
+people-cli hire +job-requirement-list --mode aggregate --group-by progress --scan-page-limit 10
+
+# 只取 AI 需要消费的字段，避免手写 jq
+people-cli hire +job-requirement-list --fields requirement_id,requirement_name,progress,recruiters
+
+# 用户明确要求完整结构时
+people-cli hire +job-requirement-list --view full --format json
+```
+
+> `+job-requirement-list --display-progress` 会在 Shortcut 内部按 `--limit` / `--scan-page-limit` 受控扫描。回复用户时不要展示 `page_token`，也不要展示 `id` 字段。
+
+## 选路提醒
+
+- Shortcut 会自动处理 `POST` 接口的 query/body 分发；不要为了手动区分 `--params` 和 `--data` 绕过 Shortcut。
+- 用户问的是"职位"时不要误走到招需接口。
+- 需求列表返回多条时，优先让用户确认具体需求，再继续做后续分析。
+- 用户问"查看进行中的招需"时，不要只过滤第一页结果；使用 `--display-progress 2` 或 `--where 'progress=进行中'` 让 Shortcut 受控扫描。

package/skills/people-hire/references/people-hire-job.md

@@ -0,0 +1,266 @@
+# job
+
+职位查询场景，覆盖职位列表与职位详情两类能力。
+
+> **字段来源：** 本文中的输入输出字段以 `people-cli hire +job-list --help` 和 `people-cli hire +job-detail --help` 为准；底层 schema 仅在 reference/help 未覆盖字段时用于核对。
+> **Shortcut 约束：** 查询职位列表必须使用 `people-cli hire +job-list`，查询职位详情必须使用 `people-cli hire +job-detail`。两者默认输出 `--view summary` 紧凑表格；用户要求特定字段时用 `--fields`，只有用户明确要求完整结构时才使用 `--view full`。
+
+## 适用意图
+
+当用户出现以下表达时，优先使用本场景：
+
+- "查职位列表"
+- "我负责的职位 / 我名下的职位"
+- "我协助的职位 / 我作为招聘协助人的职位"
+- "我作为用人经理的职位"
+- "某招聘负责人 / 用人经理 / 协助人名下有哪些职位"
+- "这个职位详情是什么"
+- "某职位的招聘进度 / 关联招需 / 负责人是谁"
+- "招聘中的职位 / 活跃职位有哪些"
+- "已关闭 / 已暂停 / 非活跃的职位有哪些"
+
+## 意图和命令索引
+
+| 用途 / 何时使用                       | 命令                           | 说明                                       |
+| ------------------------------------- | ------------------------------ | ------------------------------------------ |
+| 查职位列表、筛选职位、先拿 `job_id` | `people-cli hire +job-list` | 按更新时间、负责人、协助人、用人经理等筛选，并默认裁剪表格输出 |
+| 查询我负责的职位                      | `people-cli hire +job-list --mine --user-id-type open_id` | Shortcut 内部获取当前登录用户 `data.open_id` 并作为招聘负责人 ID |
+| 查询我协助的职位                      | `people-cli hire +job-list --assistant-mine --user-id-type open_id` | Shortcut 内部获取当前登录用户 `data.open_id` 并作为招聘协助人 ID |
+| 查询我作为用人经理的职位              | `people-cli hire +job-list --hiring-manager-mine --user-id-type open_id` | Shortcut 内部获取当前登录用户 `data.open_id` 并作为用人经理 ID |
+| 按职位启用状态筛选职位                | `people-cli hire +job-list` | 用户说"招聘中/活跃"按启用状态理解；当前接口未暴露状态入参时不要猜测下推 |
+| 查某个职位详情与招聘进度              | `people-cli hire +job-detail --job-id <job_id>` | 需要先有 `job_id`，默认裁剪详情大字段 |
+
+## 固定查询流程
+
+1. **先判断是否已有 `job_id`**
+   - 用户只说"查职位列表"、"某负责人名下有哪些职位"时，必须走 `+job-list`。
+   - 用户明确给出 `job_id`，或上一步已查到 `job_id`，再走 `+job-detail --job-id <job_id>`。
+2. **识别当前用户归属条件**
+   - 用户说"我负责的职位 / 我名下的职位"时，执行 `people-cli hire +job-list --mine --user-id-type open_id --page-size 5`。
+   - 用户说"我协助的职位 / 我作为招聘协助人的职位"时，执行 `people-cli hire +job-list --assistant-mine --user-id-type open_id --page-size 5`。
+   - 用户说"我作为用人经理的职位"时，执行 `people-cli hire +job-list --hiring-manager-mine --user-id-type open_id --page-size 5`。
+   - Shortcut 内部会调用 `GET /open-apis/authen/v1/user_info`，读取 `data.open_id` 并填入底层招聘负责人、招聘协助人或用人经理字段。
+   - 不要手动使用 `people-cli auth status` 或 `people-cli api GET /open-apis/authen/v1/user_info --as user` 获取当前用户信息。
+   - 如果当前用户信息不可用，停止继续拼接依赖当前用户的参数；不要猜测 open_id，也不要先拉全量职位再按负责人、协助人或用人经理过滤。
+3. **识别职位启用状态别称**
+   - 用户说"招聘中"、"活跃"时，按职位启用状态理解为启用中的职位。
+   - 用户说"已关闭"、"已暂停"、"非活跃"时，按职位启用状态理解为未启用的职位。
+   - 具体筛选字段、枚举值与过滤方式必须以 `+job-list --help` 和本文 Shortcut 参数为准，禁止自行猜测未暴露的参数名或枚举值。
+4. **详情查询也必须走 Shortcut**
+   - 使用 `people-cli hire +job-detail --job-id <job_id>`，不要调用原生 `people-cli hire job detail`。
+5. **执行列表或详情**
+   - 列表场景：职位接口返回内容较多，默认执行 `people-cli hire +job-list --page-size 5 ...`，Shortcut 会只提取默认展示字段。
+   - 详情场景默认执行 `people-cli hire +job-detail --job-id <job_id>`，Shortcut 会只提取关键字段，默认不返回自定义字段及数量。
+   - 用户明确要求职位描述、职位要求、自定义字段等非默认字段时，使用 `--fields description,requirement,custom_fields`；用户明确要求完整结构时才用 `--view full --format json`。
+6. **按输出层级回复**
+   - 默认先返回 `5` 条职位摘要列表，使用 Shortcut 默认表格输出。
+   - 默认 CLI 输出列为 `Job Title`、`Job Code`、`Department`、`Recruitment Type`、`Process Type`、`City`；Shortcut 返回中仍保留 `Job ID` 供后续 `+job-detail` 使用。
+   - 回复用户时可把 CLI 列名转成中文展示名；写 `--fields` / `--where` 时优先使用下方稳定字段别名，不要使用中文展示名或嵌套 jq 路径。
+   - 如果当前页之外还有更多数据，CLI/Shortcut 输出的 `page_token` 供 skill/agent 内部继续翻页；最终回复用户时只提示"还有更多数据"，不要展示 `page_token`。
+   - 如果用户明确指定查询后过滤条件（如 `XX天内`、`全部`、`XX状态`、`我的XXX`），使用 `--where` / `--mode` / `--limit` / `--scan-page-limit` 让 Shortcut 受控扫描；不要手动循环 `page_token`。
+   - 用户明确要求完整详情时，使用 `+job-detail --view full --format json`。
+   - 用户只关心摘要时，直接使用 `+job-list` 或 `+job-detail` 的默认紧凑表格；用户要求自定义字段时使用 `--fields`，用户明确要求完整结构时使用 `--view full`，禁止调用原生 `job list` / `job detail`。
+7. **再决定是否继续**
+   - 如果列表命中了多条职位，先让用户确认要看哪一个 `job_id`。
+   - 如果接口返回 `has_more=true`，默认停在当前页；只有用户明确要求继续时才使用 `page_token`，查询后过滤一律走 Shortcut 受控扫描参数。
+   - 不要原样倾倒整包数据；默认先摘要、后详情。
+
+## 标准输入
+
+### `+job-list`
+
+Shortcut 参数映射到底层 `job.list` query：
+
+| 字段                       | 位置  | 类型   | 说明                     |
+| -------------------------- | ----- | ------ | ------------------------ |
+| `--update-start-time`    | query | string | 最早更新时间，支持毫秒时间戳或日期/相对时间字符串 |
+| `--update-end-time`      | query | string | 最晚更新时间，支持毫秒时间戳或日期/相对时间字符串 |
+| `--page-size`            | query | int    | skill 默认 `5`，最大 `20` |
+| `--page-token`           | query | string | 翻页 token               |
+| `--user-id-type`         | query | enum | `user_id` / `union_id` / `open_id` |
+| `--department-id-type`   | query | enum | `open_department_id` / `department_id`；使用 `--department-id` 时未显式指定则默认 `open_department_id` |
+| `--job-level-id-type`    | query | enum | `people_admin_job_level_id` / `job_level_id` |
+| `--job-family-id-type`   | query | enum | `people_admin_job_category_id` / `job_family_id` |
+| `--recruiter-id`         | query | repeatable string | 招聘负责人 ID 列表；支持传 `self` 表示当前用户 |
+| `--mine`                 | internal | bool | 查询"我负责的职位"时使用；Shortcut 内部获取当前用户 `data.open_id` 并作为招聘负责人 ID |
+| `--hiring-manager-id`    | query | repeatable string | 用人经理 ID 列表 |
+| `--hiring-manager-mine`  | internal | bool | 查询"我作为用人经理的职位"时使用；Shortcut 内部获取当前用户 `data.open_id` 并作为用人经理 ID |
+| `--assistant-id`         | query | repeatable string | 招聘协助人 ID 列表 |
+| `--assistant-mine`       | internal | bool | 查询"我协助的职位"时使用；Shortcut 内部获取当前用户 `data.open_id` 并作为招聘协助人 ID |
+| `--with-stage-counts`    | internal | bool | 按需补查职位详情中的阶段人数统计；用户问"每个职位进展/各阶段候选人数"时使用 |
+| `--keyword`              | internal filter | string | 职位关键字过滤，会在职位名称、编号、部门、地点、序列等摘要字段中匹配 |
+| `--department`           | internal filter | string | 部门名称包含过滤 |
+| `--department-id`        | internal filter | string | 部门 ID 过滤，必须传显式部门 ID；ID 类型跟随 `--department-id-type`，未指定时默认 `open_department_id` |
+| `--process-type`         | internal filter | enum | 流程类型过滤，支持 `social`/`社招`、`campus`/`校招` |
+| `--active-status`        | internal filter | enum | 职位启用状态过滤，支持 `active`/`招聘中`、`inactive`/`已关闭` |
+| `--closed`               | internal filter | bool | 查询已关闭/非活跃职位，等价于 `--active-status inactive` |
+| `--city`                 | internal filter | string | 工作城市包含过滤 |
+| `--job-category`         | internal filter | string | 职位序列/职能方向包含过滤 |
+| `--recruitment-type`     | internal filter | string | 招聘类型/雇佣类型包含过滤，如正式、实习 |
+| `--salary-currency`      | internal filter | string | 薪资币种包含过滤 |
+| `--view`                 | - | enum | `summary` 默认裁剪视图；`full` 原始字段视图 |
+| `--fields`               | - | string | 逗号分隔字段名，如 `job_id,job_title,department`；包含 `stage_counts` 时会自动按需补查职位详情 |
+| `--where`                | - | string | 查询后过滤表达式，如 `department contains Brand; city=成都` |
+| `--limit`                | - | int | 最多返回的匹配行数，默认等于 `--page-size` |
+| `--scan-page-limit`      | - | int | 查询后过滤最多扫描源页数，默认由 Shortcut 控制 |
+| `--mode`                 | - | enum | `list` / `exists` / `count` / `aggregate` |
+| `--group-by`             | - | string | `--mode aggregate` 时按哪个字段聚合；支持逗号分隔多个字段 |
+
+> 触发 `--where` / `--mode count|aggregate` 等受控扫描，或显式 `--limit` 大于 `--page-size` 时，Shortcut 会自动调大底层源接口 `page_size` 以提升过滤效率；最终展示仍按 `--limit` / 默认 `--page-size` 裁剪。
+> 多个职位的候选人阶段人数优先用 `+job-list --with-stage-counts --fields job_title,stage_counts`，不要对每个职位调用 `+application-list` 后再聚合。
+
+### `+job-detail`
+
+Shortcut 参数映射到底层 `job.detail`：
+
+| 字段                   | 位置  | 类型   | 说明          |
+| ---------------------- | ----- | ------ | ------------- |
+| `--job-id`           | path  | string | 职位 ID，必填 |
+| `--user-id-type`     | query | enum | `user_id` / `union_id` / `open_id` / `people_admin_id`，默认 `open_id` |
+| `--department-id-type` | query | enum | `open_department_id` / `department_id`，默认 `open_department_id` |
+| `--job-level-id-type`  | query | enum | `people_admin_job_level_id` / `job_level_id` |
+| `--job-family-id-type` | query | enum | `people_admin_job_category_id` / `job_family_id` |
+| `--view`             | - | enum | `summary` 默认裁剪视图；`full` 原始字段视图 |
+| `--fields`           | - | string | 逗号分隔字段名，如 `job_id,job_title,recruiter,stage_counts` |
+
+## 标准输出
+
+### 底层 `job.list` 字段参考
+
+底层 `job.list` 返回 `items[]`。`+job-list` 默认会把列表裁剪成表格友好的摘要；自定义字段使用 `--fields`，完整结构使用 `--view full`：
+
+| 字段                 | 类型   | 用途 | 说明                                          |
+| -------------------- | ------ | ---- | --------------------------------------------- |
+| `id`               | string | 内部关联 | 职位详情查询用，默认不展示                  |
+| `title`            | string | 默认展示 | 职位名称                                      |
+| `code`             | string | 默认展示 | 职位编号                                      |
+| `department`       | object | 默认展示 | 部门信息，含 `id`、`zh_name`、`en_name` |
+| `recruitment_type` | object | 默认展示 | 雇佣类型，含 `id`、`zh_name`、`en_name` |
+| `process_type`     | int    | 默认展示 | 职位流程类型，`1`=社招流程，`2`=校招流程  |
+| `city_list`        | array  | 默认展示 | 工作地点列表                                  |
+
+如需进一步排查或缩小范围，可使用以下 Shortcut 稳定别名：`job_id`、`job_title` / `title` / `job`、`department_id`、`job_category`、`job_type`、`active_status`、`head_count`、`experience`、`required_degree`、`target_major`、`min_salary`、`max_salary`、`salary_currency`、`update_time`、`search`。这些别名可用于 `--where` 或显式 `--fields`，但不会出现在默认展示列中。底层 `id` / `update_timestamp` 字段在 Shortcut 中分别对应 `job_id` / `update_time`；CLI 兼容 `id`、`name`、`job_name`、`status`、`job_family`、`headcount`、`salary_min`、`salary_max` 等模型常见写法，但生成命令时仍优先写稳定别名。
+
+分页状态字段（CLI/Shortcut 需要输出给 skill/agent 内部判断和续查，默认不对用户展示 `page_token`）：
+
+| 字段           | 类型   | 说明           |
+| -------------- | ------ | -------------- |
+| `has_more`   | bool   | 是否还有下一页 |
+| `page_token` | string | 内部翻页 token，CLI 可见，最终回复用户时默认隐藏 |
+
+### 底层 `job.detail` 字段参考
+
+底层详情接口返回 `job_detail`。`+job-detail --view summary` 默认只取摘要字段；以下字段可作为 `--view full` 或字段理解参考：
+
+| 字段                                       | 类型   | 说明             |
+| ------------------------------------------ | ------ | ---------------- |
+| `job_detail.basic_info.id`               | string | 职位 ID          |
+| `job_detail.basic_info.title`            | string | 职位名称         |
+| `job_detail.basic_info.code`             | string | 职位编号         |
+| `job_detail.basic_info.description`      | string | 职位描述         |
+| `job_detail.basic_info.requirement`      | string | 职位要求         |
+| `job_detail.basic_info.department`       | object | 部门信息         |
+| `job_detail.basic_info.recruitment_type` | object | 雇佣类型         |
+| `job_detail.basic_info.min_job_level`    | object | 最低职级         |
+| `job_detail.basic_info.max_job_level`    | object | 最高职级         |
+| `job_detail.basic_info.job_category`     | object | 职位序列         |
+| `job_detail.basic_info.job_type`         | object | 职位类别         |
+| `job_detail.basic_info.active_status`    | int    | 启用状态         |
+| `job_detail.basic_info.process_type`     | int    | 流程类型         |
+| `job_detail.basic_info.head_count`       | int    | 招聘人数         |
+| `job_detail.basic_info.required_degree`  | int    | 学历要求         |
+| `job_detail.basic_info.city_list`        | array  | 工作地点列表     |
+| `job_detail.recruiter`                   | object | 招聘负责人       |
+| `job_detail.assistant_list`              | array  | 招聘协助人列表   |
+| `job_detail.hiring_manager_list`         | array  | 用人经理列表     |
+| `job_detail.job_requirement_list`        | array  | 关联招聘需求列表 |
+| `job_detail.address_list`                | array  | 职位地址列表     |
+| `job_detail.tag_list`                    | array  | 职位标签列表     |
+| `job_detail.stage_count_list`            | array  | 招聘进展阶段统计 |
+| `job_detail.basic_info.customized_data_list` | array | 自定义字段列表，默认不展开 |
+
+## 输出
+
+### 默认展示字段
+
+`+job-list` 默认回复会整理为表格友好的列表，并在返回中保留后续 `+job-detail` 需要的内部 ID：
+
+| CLI 列 | 稳定字段别名 | 用户回复含义 | 来源字段 |
+| ------ | ------------ | ------------ | -------- |
+| `Job ID` | `job_id` | 职位 ID，默认不向用户展示 | `id` |
+| `Job Title` | `job_title` / `title` / `job` | 职位名称 | `title` |
+| `Job Code` | `job_code` / `code` | 职位编号 | `code` |
+| `Department` | `department` | 部门信息 | `department` |
+| `Department ID` | `department_id` | 部门 ID，默认不向用户展示 | `department.id` / `department_id` |
+| `Recruitment Type` | `recruitment_type` | 雇佣类型 | `recruitment_type` |
+| `Process Type` | `process_type` | 职位流程类型 | `process_type` |
+| `City` | `city` | 工作地点 | `city_list` |
+
+> `--fields`、`--where`、`--group-by` 使用稳定字段别名或 CLI 列名。最终回复用户时可使用中文名，但除非用户明确指定，不要直接展示职位 ID。`--where` 多条件优先用分号分隔，如 `department contains Brand; city=成都`；CLI 兼容英文 `AND`，但不支持 `OR`。
+
+`+job-detail` 默认摘要返回以下字段。自定义字段及自定义字段数量默认都不返回：
+
+| CLI 列 | 来源字段 |
+| ------ | -------- |
+| `Job ID` | `job_detail.basic_info.id` |
+| `Job Title` | `job_detail.basic_info.title` |
+| `Job Code` | `job_detail.basic_info.code` |
+| `Department` | `job_detail.basic_info.department` |
+| `Recruitment Type` | `job_detail.basic_info.recruitment_type` |
+| `Process Type` / `Process ID` / `Process Name` | `job_detail.basic_info.process_*` |
+| `Active Status` / `Head Count` / `City` | `job_detail.basic_info.active_status/head_count/city_list` |
+| `Recruiter` / `Recruiter ID` / `Hiring Managers` | `job_detail.recruiter` / `job_detail.hiring_manager_list` |
+| `Job Requirements` / `Requirement IDs` | `job_detail.job_requirement_list` |
+| `Stage Counts` | `job_detail.stage_count_list` |
+
+> 需要职位描述、职位要求、自定义字段内容或自定义字段数量时，使用 `+job-detail --fields description,requirement,custom_fields,custom_fields_count`。`custom_fields` 会返回压缩摘要；完整自定义字段只允许在用户明确要求完整结构时通过 `--view full` 获取。
+
+## 所需权限
+
+| 方法           | Scope                                |
+| -------------- | ------------------------------------ |
+| `job.list`   | `hire:job:readonly` |
+| `job.detail` | `hire:job.composite_info:readonly` |
+
+## 示例
+
+```bash
+# 先查看职位列表，默认紧凑表格输出
+people-cli hire +job-list --page-size 5
+
+# 查某招聘负责人名下的职位
+people-cli hire +job-list --recruiter-id ou_xxx --user-id-type open_id --page-size 5
+
+# 查询我负责的职位：Shortcut 内部取当前登录用户 open_id 并按招聘负责人筛选
+people-cli hire +job-list --mine --user-id-type open_id --page-size 5
+
+# 查询我作为招聘协助人的校招正式职位
+people-cli hire +job-list --assistant-mine --user-id-type open_id --process-type campus --recruitment-type 正式 --limit 20
+
+# 查询我作为用人经理、目标专业包含软件工程且本科及以上的校招正式职位
+people-cli hire +job-list --hiring-manager-mine --user-id-type open_id --process-type campus --recruitment-type 正式 --where 'target_major contains 软件工程; required_degree contains 本科' --limit 20
+
+# 只取 AI 需要消费的字段，避免手写 jq
+people-cli hire +job-list --fields job_id,job_title,department,process_type
+
+# 确认 Brand 部门在成都是否有设计序列职位
+people-cli hire +job-list --department Brand --city 成都 --job-category 设计 --mode exists --limit 1 --scan-page-limit 5
+
+# 用户明确要求完整结构时
+people-cli hire +job-list --view full --format json
+
+# 用户明确要求更多信息时，再按 job_id 查看裁剪后的详情
+people-cli hire +job-detail --job-id 6897921873523247373 --user-id-type open_id
+
+# 只取职位描述、职位要求、自定义字段摘要
+people-cli hire +job-detail --job-id 6897921873523247373 --fields description,requirement,custom_fields
+
+# 用户明确要求完整职位详情结构时
+people-cli hire +job-detail --job-id 6897921873523247373 --view full --format json
+```
+
+## 选路提醒
+
+- 用户没有 `job_id` 时，不要直接执行 `+job-detail`。
+- 用户只要职位摘要时，必须用 `+job-list`，不要默认返回整包 `job_detail`。
+- `+job-detail` 默认已经裁剪详情大字段；不要回退到原生 `job detail`。

package/skills/people-hire/references/people-hire-minutes.md

@@ -0,0 +1,86 @@
+# minutes
+
+面试速记查询场景，覆盖按 `interview_id` 获取面试速记文本。
+
+> **字段来源：** 本文中的输入输出字段以 `people-cli hire +minutes-detail --help` 为准；底层 schema 仅在 reference/help 未覆盖字段时用于核对。
+> **强制约束：** 面试速记必须使用 `people-cli hire +minutes-detail`，禁止直接调用原生 `people-cli hire minutes detail`。
+## 适用意图
+
+当用户出现以下表达时，优先使用本场景：
+
+- "查面试速记"
+- "看这场面试的逐字稿"
+- "根据面试速记生成面评初稿"
+- "获取 interview_id 对应的速记文本"
+
+## 意图和命令索引
+
+| 用途 / 何时使用 | 命令 | 说明 |
+| --- | --- | --- |
+| 按 `interview_id` 获取面试速记明细 | `people-cli hire +minutes-detail` | 返回速记句子列表，支持分页 |
+
+## 固定查询流程
+
+1. **确认是否已有 `interview_id`**
+   - `minutes.detail` 必须有 `interview_id`。
+   - 如果没有 `interview_id`，先通过 `+interview-list` 或 `+interview-task-list` 定位。
+2. **执行查询**
+   - 使用 `people-cli hire +minutes-detail --interview-id <interview_id>`，不要手写原生 `--params` / `--jq`。
+   - 默认 `--page-size 5`、`--view summary`；需要特定字段时用 `--fields`。
+4. **结构化输出**
+   - 默认只展示前 `5` 条句子或用户要求的数量。
+   - 如果还有更多数据，CLI/Shortcut 输出的 `page_token` 供 skill/agent 内部继续翻页；最终回复用户时只提示"还有更多速记内容"，不要展示 `page_token`。
+   - 用户要求生成面评初稿时，基于接口实际返回的速记文本生成，并明确速记覆盖范围。
+
+## 标准输入
+
+| 参数 | 对应接口字段 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| `--interview-id` | `interview_id` | string | 面试 ID，必填 |
+| `--page-token` | `page_token` | string | 翻页 token |
+| `--page-size` | `page_size` | int | 默认 `5`，最大 `100` |
+| `--view` | - | enum | `summary` 默认裁剪视图；`full` 原始字段视图 |
+| `--fields` | - | string | 逗号分隔字段名，如 `speaker,content,speak_time` |
+
+## 标准输出
+
+`+minutes-detail --view summary` 默认返回以下稳定字段：
+
+| 字段 | 类型 | 用途 | 说明 |
+| --- | --- | --- | --- |
+| `content` | string | 默认展示 | 速记句子文本 |
+| `speak_time` | string | 默认展示 | 句子开始讲话的毫秒时间戳 |
+| `user_type` | int | 默认展示 | 说话人类型：`1` 面试官，`2` 候选人 |
+| `speaker_name` | object | 默认展示 | 说话人名称 |
+
+分页状态字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `has_more` | bool | 是否还有更多速记 |
+| `page_token` | string | 内部翻页 token，CLI 可见，最终回复用户时默认隐藏 |
+
+## 所需权限
+
+| 方法 | Scope |
+| --- | --- |
+| `minutes.detail` | `hire:interview:readonly` |
+
+## 示例
+
+```bash
+# 查询面试速记
+people-cli hire +minutes-detail --interview-id 6989202908470446380 --page-size 5
+
+# 只取说话人与文本
+people-cli hire +minutes-detail --interview-id 6989202908470446380 --fields speaker,content
+
+# 用户明确要求完整结构时
+people-cli hire +minutes-detail --interview-id 6989202908470446380 --view full --format json
+```
+
+## 选路提醒
+
+- `minutes.detail` 需要 `interview_id`，不要传 `application_id` 或 `interview_record_id`。
+- 速记内容可能很长，默认分页裁剪；不要一次性倾倒全量逐字稿。
+- 生成面评初稿时，应说明仅基于已读取速记内容。