@lark-people/cli 0.0.0-beta.2 → 0.0.0-beta.4

package/skills/people-overtime/references/people-attendance-overtime-apply.md

@@ -1,491 +0,0 @@
-# +overtime-apply-render / +overtime-apply-options / +overtime-apply-convert / +overtime-apply-create
-
-加班申请工具。支持渲染加班表单、查询枚举选项、格式转换、发起加班申请。
-
-> **前置条件：** 先阅读 [`../../people-shared/SKILL.md`](../../people-shared/SKILL.md)
-
-**CRITICAL — 仅适用于 CN 中国大陆员工**：本流程的表单结构、calculation 字段、审批流均按 CN 中国大陆加班制度设计，仅支持 CN 员工本人发起加班申请。**SGP / 海外员工**的加班发起意图（含 Asia/Singapore / Working Day Overtime / Saturday OT / Sunday OT / 1.5x Daily Salary / Time off in Lieu / by_duration / by_time 等信号）一律不要调用 `+overtime-apply-render` / `+overtime-apply-options` / `+overtime-apply-create`，直接告知不支持，并引导用户前往加班审批系统提交申请；如用户改为查询历史加班记录，再走 `submission.get` (`time_type=2`) / `query_month_summary`。**如果误调用 `+overtime-apply-*` 且返回报错文案包含 `method only support CHN country`，直接告诉用户：`暂时不支持非CN大陆提交加班，请前往审批系统提交。` 不要再做任何回退尝试。**
-
-## 触发场景
-
-- 用户（**CN 中国大陆员工**）需要申请加班、提交加班单据、查询加班申请表单选项时使用本流程。
-- 用户为 **SGP / 海外员工**时，不使用本流程，直接告知不支持，并指引用 `submission` 查询或前往审批系统操作。
-- 用户只想查询已有加班记录时，不使用本流程，改用 [`people-attendance-overtime.md`](people-attendance-overtime.md)（默认用于 CN 审批单）或 [`people-attendance-submission.md`](people-attendance-submission.md)（默认用于非 CN 提报记录 / 月度汇总；命中特定地域报错时按规则回退）。
-- 用户要求撤回、取消、修改加班申请时，不调用本流程，直接说明当前仅支持发起加班申请。
-- 用户要求给他人、下属、同事，或通过工号/用户 ID/open_id/union_id 等身份信息代提交加班时，不调用本流程，直接说明当前仅支持给当前登录用户本人发起加班申请。
-
-## 用法
-
-```bash
-people-cli attendance +overtime-apply-render [flags]
-people-cli attendance +overtime-apply-options [flags]
-people-cli attendance +overtime-apply-convert [flags]
-people-cli attendance +overtime-apply-create [flags]
-```
-
-`--form-info` 和 `--input` 优先直接传 JSON 字符串，避免读写临时 `form_info.json` / `final_form.json` 的耗时；仅在参数过大或 shell 转义困难时使用 `@filepath`，也可用 `@-` 从 stdin 读取。
-
-## 核心概念
-
-| 概念 | 说明 |
-|------|------|
-| `form_info` | 加班表单参数 JSON 字符串，贯穿 `render`、`options`、`create` |
-| `+overtime-apply-render` | 渲染/校验当前表单状态，并输出 `submit_form_info`、`ready_to_create`、`enum_query_paths` |
-| `+overtime-apply-options` | 查询枚举字段的下拉选项，例如加班原因、补偿方式 |
-| `+overtime-apply-convert` | 将 `render` 返回的字段数组转换为提交格式 |
-| `+overtime-apply-create` | 发起加班申请 |
-| `display_summary` | 标准化中文确认摘要；确认态和成功态优先直接复用，避免 LLM 自行改写字段名 |
-
-## 表单字段规则
-
-| 字段属性 | 规则 |
-|------|------|
-| `key` | 字段名称；AI 构造 `form_info` 时就用这个名称传值 |
-| `validate_results` | 服务端校验结果；没有该字段或为空表示该字段当前校验通过 |
-| `writable` | 是否可写；`writable=true` 的字段可由 AI 在用户明确提供时填充 |
-| `required` | 是否必填；必填且缺值时应通过 render/追问补充，禁止用“无”等占位值默认填充 |
-| `type.type=enum` | 枚举字段；如果必填或 `validate_results` 提示未填写，需要调用 `+overtime-apply-options` 查询可选值 |
-| `type.type=record` | 单行记录；填充为 JSON 对象，递归读取 `sub_fields` 确定子字段、必填和可写状态 |
-| `type.type=list` 且 `item_type=record` | 多行记录（`list<record>`）；填充为对象数组，`template_sub_fields` 是表头定义，没有 `sub_fields` 表示当前还没有任何记录 |
-
-`type` 到 `form_info` 结构映射：
-
-- `type=record`：填充为对象，例如
-
-```json
-{
-  "notes": "beizhu",
-  "reason_for_cancellation": "reason",
-  "work_apply_overtime": {}
-}
-```
-
-- `type=list<record>`：填充为数组，例如
-
-```json
-[
-  {
-    "overtime_date": "2026-05-08",
-    "overtime_duration": 0.5,
-    "paymod": "paymod_pay"
-  },
-  {
-    "overtime_date": "2026-05-10",
-    "overtime_duration": 1,
-    "paymod": "paymod_pay"
-  }
-]
-```
-
-说明：发起加班只支持日期 + 时长模式，日期使用 `2006-01-02`；不要通过 `datetime`、`start_time`、`end_time` 构造开始时间-结束时间的加班时段。
-
-## 可用命令
-
-| 命令 | 说明 | 参数 |
-|------|------|------|
-| `+overtime-apply-render` | 渲染加班表单、校验参数、转换提交参数 | `--form-info`，首次可空 |
-| `+overtime-apply-options` | 查询枚举字段下拉选项 | `--form-info --query-path <path>` |
-| `+overtime-apply-convert` | 将 `render` 返回转换为提交格式 | `--input` |
-| `+overtime-apply-create` | 发起加班申请 | `--form-info --time-zone --yes` |
-
-## 参数
-
-### +overtime-apply-render
-
-| Flag | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--form-info` | string | 否 | 空 | 加班表单参数 JSON 字符串；优先直接传 JSON，支持 `@filepath`、`@-` |
-| `--format` | string | 否 | `json` | 输出格式：`json`、`pretty`、`table`、`ndjson`、`csv` |
-
-### +overtime-apply-options
-
-| Flag | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--form-info` | string | 否 | 空 | 加班表单参数 JSON 字符串；优先直接传 JSON，支持 `@filepath`、`@-` |
-| `--query-path` | string | 是 | - | enum 字段查询路径 |
-| `--format` | string | 否 | `json` | 输出格式：`json`、`pretty`、`table`、`ndjson`、`csv` |
-
-### +overtime-apply-convert
-
-| Flag | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--input` | string | 是 | - | `render` 返回 JSON 或字段数组；优先直接传 JSON，支持 `@filepath`、`@-` |
-| `--format` | string | 否 | `json` | 输出格式：`json`、`pretty`、`table`、`ndjson`、`csv` |
-
-### +overtime-apply-create
-
-| Flag | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--form-info` | string | 是 | - | 最终提交的加班表单参数 JSON 字符串；优先直接传 JSON，支持 `@filepath`、`@-` |
-| `--time-zone` | string | 否 | `Asia/Shanghai` | 申请人所在时区 |
-| `--yes` | bool | 是 | `false` | 二次确认后才允许提交真实加班申请；未传时命令会拒绝执行 |
-| `--format` | string | 否 | `json` | 输出格式：`json`、`pretty`、`table`、`ndjson`、`csv` |
-
-## 标准工作流
-
-加班申请是一个**循环渲染**流程，需要按轮次调用 `+overtime-apply-render`，直到参数满足提交条件。动态表单规则可能随用户输入变化，因此每轮 render 后必须以最新返回结果为准，但下一次 render 必须等本轮缺失项全部收集完成后再执行。
-
-**日期确认是强制前置步骤（Step 0），必须在首次 render 之前完成，不可跳过。** 无论用户给出绝对日期还是相对日期，都必须先完成日期确认。流程：调用 `scripts/resolve_date.py` → 脚本失败时 Agent 语义推理 → 仍无法确定则追问用户 → 向用户展示确认 → 确认后才进入 render。详见 SKILL.md 的”强制前置：日期确认（Step 0）”章节。
-
-**为减少 render 调用次数，必须一次性收集齐缺失字段再 render。为保证 enum 联动正确，必须先非 enum、后 enum：**
-- 每轮 render 返回 `missing_fields`、`validate_results`、`enum_query_paths` 后，先筛出所有缺失的非 enum 字段，一次性向用户追问。
-- 非 enum 字段收集并写入 `form_info` 后，再查询 enum options；若没有任何非 enum 字段可收集或依赖，允许用空 `form_info` 查询 enum。
-- enum 字段之间是平等关系，不要求固定查询顺序；非 enum 字段收集完成后，多个 enum options 可并行查询。
-- 若某个 enum 已经确定（用户已明确选择、或 options 只有一个选项自动填充），查询其他 enum 时应把这个已知 enum 一起拼进 `form_info`。
-- 如果用户只回答了部分字段，继续追问剩余字段，**不要在用户输入未补齐前就调用 render，收集完整之后再发起下一次render**。
-
-1. **执行日期确认（Step 0）**：从用户输入中提取日期表达 → 调用 `python3 <skill_path>/scripts/resolve_date.py --expr “<日期表达>” --anchor “<当前日期YYYY-MM-DD>”` → 根据返回结果获得绝对日期（脚本失败则 Agent 推理或追问）→ 向用户输出确认：”今天是 M月D日 星期X，您要申请的加班日期是 YYYY-MM-DD（星期X），是否正确？” → 用户确认后继续。
-2. 首次调用 `+overtime-apply-render --form-info ''`，读取 `fields`，所有字段都以 render 返回为准，不写死字段清单。
-3. 递归读取 `fields`：`required=true` 必填，`writable=true` 且用户明确提供时可填，`writable=false` 不构造；申请人、工号、用户 ID 等身份字段一律不构造。
-4. 把本轮 render 返回的所有缺失非 enum 字段一次性向用户追问；若用户已经给出非法时长、非法日期范围或代提他人信息，先直接拦截，不要调用 render/options。
-5. 非 enum 字段写入 `form_info` 后，调用 `+overtime-apply-options` 查询 enum 选项；enum 之间平等，可并行查询。若查询时已有其他 enum 的确定值，应把已知 enum 一起带入 `form_info`。
-6. **收集完所有缺失字段（包括所有非 enum 和 enum 字段）后**，才调用 `+overtime-apply-render --form-info '<当前 form_info JSON>'` 复核；不要为了传参落盘 `form_info.json`，**不要在只收集了部分信息时就调用 render**。
-7. `ready_to_create=true` 后，直接使用 `submit_form_info` 作为最终提交参数。
-8. 调用 `+overtime-apply-create` 前必须优先展示最终 `display_summary.text`；如果摘要缺字段，则按最终 `submit_form_info` 补齐展示所有申请数据。
-9. 必须获得用户明确二次确认后才可 create；这次确认必须发生在 create 前一刻，不能复用日期确认（Step 0）、enum 选择确认、每轮 render 确认或 `ready_to_create=true`。
-10. 用户确认后，调用 `+overtime-apply-create --yes` 发起申请。
-
-按照"批量收集 → render"的节奏，循环 `render` 次数通常不应超过 3 次；超过后应提示用户检查输入或稍后重试。
-
-命令执行报错时按以下重试策略处理：
-- **参数不变**：仅对非业务校验类的临时命令/API 错误，使用完全相同的命令和参数原样重试 1 次；第二次仍失败则停止，直接向用户说明失败原因和最后一次错误信息。
-- **自动修改参数后重试**：只有错误信息明确指向可修正参数时，大模型才可基于已有上下文自动调整 `form_info` 后重新 `render/create`；这类自动改参重试累计最多 3 次，超过后必须停止。
-- **用户补充信息不计数**：用户补充或修改了日期、时长、原因、计算方式等信息后再次执行，属于新的输入轮次，不计入上述 3 次自动改参重试。
-- **不重试场景**：所有不支持的操作、`validate_results`、`create_invalid_msg`、2 段上限、代提他人、0/负数时长、工作日/休息日超限、token 过期等确定性业务或鉴权错误都不要重试，应直接告知不支持、解释原因、引导用户修正或重新授权。
-
-## Step 1: 首次渲染
-
-首次可传空字符串，用于了解表单结构。
-
-```bash
-people-cli attendance +overtime-apply-render --form-info ''
-```
-
-返回内容通常包含：
-
-- `key`、`title`、`type`、`required`、`writable`
-- `fields`，字段数组；来自服务端 render 返回
-- `validate_results`，例如“备注为必填
-- `fillable_fields`，本轮可写字段清单
-- `missing_fields`，本轮缺失或校验失败的字段；`list record` 会包含 `record_template`
-- `enum_query_paths`，可直接用于 `+overtime-apply-options --query-path`
-- `next_action`，下一步动作：`fill_missing_fields`、`choose_enum`、`confirm_create` 或 `render_again`
-- `submit_form_info`，已转换成可提交结构
-- `display_summary`，标准化用户确认摘要，含固定标签和 `text`
-- `ready_to_create`，是否可进入用户确认和提交
-
-## Step 0: 日期确认（强制前置，不可跳过）
-
-**此步骤必须在 Step 1（首次渲染）之前完成。未经此步确认的日期不得写入 form_info。**
-
-### 为什么要用脚本
-
-LLM 对”下周六””下个月3号”等相对日期表达极易产生幻觉（推错日期、搞错星期几）。用确定性的 Python 脚本做规则计算可以消除此类错误。即使是绝对日期（如 `6.13`），也通过脚本做规范化并向用户展示确认，防止年份推断错误。
-
-### 三级瀑布流程
-
-```
-Level 1: 调用 resolve_date.py 脚本（确定性计算，优先使用）
-    ├─ success=true → 使用 resolved_date
-    └─ success=false → 进入 Level 2
-
-Level 2: Agent 基于 ISO 8601 规则语义推导（周一=第一天）
-    ├─ 有信心推出日期 → 使用推理结果
-    └─ 无信心 → 进入 Level 3
-
-Level 3: 主动追问用户”请给出具体日期（如 2026-06-13）”
-
-无论哪个 Level 获得日期，都必须向用户输出确认（不可省略）。
-```
-
-### 脚本调用
-
-```bash
-python3 <skill_path>/scripts/resolve_date.py --expr “<用户日期表达>” --anchor “<当前日期YYYY-MM-DD>”
-```
-
-- `--anchor`：从 system prompt 的 `now_time` / `currentDate` 中取 YYYY-MM-DD；取不到时使用 UTC+8 当前日期
-- `--expr`：用户原始日期表达，如 `下周六`、`6月13日`、`明天`、`下个月3号`
-
-返回 JSON 示例（成功）：
-```json
-{“success”: true, “type”: “single”, “resolved_date”: “2026-06-06”, “resolved_weekday”: “星期六”, “anchor_date”: “2026-05-29”, “anchor_weekday”: “星期五”, “expression”: “下周六”, “method”: “rule_based”}
-```
-
-返回 JSON 示例（失败，交由 Level 2/3 处理）：
-```json
-{“success”: false, “reason”: “无法解析表达式 '端午节那天'，不在已知模式中”, “anchor_date”: “2026-05-29”, “anchor_weekday”: “星期五”, “expression”: “端午节那天”}
-```
-
-### 脚本支持的表达模式
-
-| 类别 | 示例 |
-|------|------|
-| 绝对日期 | `2026-06-13`、`6.13`、`6月13日`、`2026年6月13日`、`20260613` |
-| 今/明/昨/后/前 | 今天、明天、昨天、后天、大后天、前天 |
-| 周X / 本/上/下/下下周X | 周六（默认本周六）、周日（默认本周日）、本周六、下周六、上周日、下下周六、上上周一 |
-| 周末（范围） | 本周末、下周末、上周末 |
-| 月+日 | 下个月3号、本月15号、上个月20号 |
-| N天/周后/前 | 三天后、两周后、5天前、一周后 |
-| 月第N个周X | 本月第二个周五、下个月第一个周一 |
-| 年/半年（范围） | 今年、明年、上半年、下半年 |
-
-### 脚本不支持的表达（Level 2/3 处理）
-
-- 节假日名称：”端午节那天””中秋节”
-- 复合偏移：”明天第三个周五””下个月最后一个工作日”
-- 非标口语：”这个礼拜六”（注：”这周六”脚本可以识别）
-
-### 确认话术（必须输出，不可省略）
-
-单段加班：
-```
-今天是 {M}月{D}日 星期{W}，您要申请的加班日期是 {resolved_date}（{resolved_weekday}），是否正确？
-```
-
-多段加班（最多2段，每段分别调用脚本）：
-```
-今天是 {M}月{D}日 星期{W}：
-- 第1段加班日期：{resolved_date_1}（{resolved_weekday_1}）
-- 第2段加班日期：{resolved_date_2}（{resolved_weekday_2}）
-
-以上日期是否正确？
-```
-
-### Agent 语义推导规则（Level 2 使用）
-
-当脚本返回 `success=false` 时，Agent 按以下规则自行推导：
-
-- 锚点：使用 `--anchor` 同一日期
-- 周规则：ISO 8601，周一为每周第一天
-- 本周X = 本周一 + (X-1) 天；下周X = 本周X + 7 天；上周X = 本周X - 7 天
-- 推导结果同样必须向用户展示确认
-
-### 用户确认后
-
-将确认的日期以 `YYYY-MM-DD` 格式用于后续 form_info 构造。用户纠正则用新表达重新从 Level 1 开始。
-
-## Step 2: 带参数渲染
-
-用户提供加班信息后，构造 `form_info` 并渲染。
-
-当前发起加班只支持**日期 + 时长**模式，不支持**开始时间 - 结束时间**的加班时段模式。不要构造 `work_apply_overtime.work_overtimes`、`start_time`、`end_time`；用户只给出“几点到几点”时，先换算为日期和时长并向用户确认，无法明确换算时追问加班时长。
-
-判定规则：如果 render 返回的 `fields`、`missing_fields`、`record_template` 或 `submit_form_info` 中出现 `work_apply_overtime.daily_overtime_details`，并且其子字段包含 `overtime_date` 与 `overtime_duration`，说明当前表单就是**日期 + 时长模式**。此时 agent 只能追问「加班日期」和「加班时长」，不得追问「加班具体时间段」「几点到几点」「开始时间」「结束时间」。
-
-```bash
-people-cli attendance +overtime-apply-render --form-info '<form_info_json>'
-```
-
-`form_info` 使用提交格式：
-
-```json
-{
-  "notes": "用户明确提供的加班备注",
-  "work_apply_overtime": {
-    "daily_overtime_details": [
-      {
-        "overtime_date": "2026-05-08",
-        "overtime_duration": 3,
-        "paymod": "paymod_pay",
-        "overtime_reason": "overtime_reason_xxx"
-      }
-    ]
-  }
-}
-```
-
-不要为了通过校验而预填占位值；例如用户没有提供 `reason_for_cancellation` 时，不要写 `"reason_for_cancellation": "无"`，应交给 `render` 返回 `missing_fields` / `validate_results` 后再提醒用户补充。
-
-`paymod` 是补偿方式枚举，只有用户明确表达或选择时才写入：
-
-| 用户选择 | 写入值 |
-|----------|--------|
-| 加班费 | `paymod_pay` |
-| 调休假 | `paymod_compensatory_leave` |
-
-如果用户没有说明补偿方式，或者上下文没有收集到该信息，不要默认写入 `paymod`；调用 `render` 后根据 `enum_query_paths` / `missing_fields` 再查询 options 并让用户选择。
-
-字段类型转换规则：
-
-| 类型 | 转换规则 |
-|------|----------|
-| `date` | 传年月日字符串，格式固定为 `2006-01-02`，例如 `2026-05-08` |
-| `number` | 传加班时长数字，例如 `3` 表示 3 小时；不要通过 `start_time/end_time` 提交时段 |
-| `enum` | 传选项的 `key` 字符串；如果 render 返回 `{value,label}`，shortcut 会自动提取 `value` |
-
-
-## Step 3: 查询枚举选项
-
-当字段类型为 enum 且需要填值时调用 `+overtime-apply-options`。调用前必须先收集并写入当前记录行所有已知非 enum 字段；目标 enum 字段可以先不填。
-
-```bash
-people-cli attendance +overtime-apply-options --form-info '<form_info_json>' --query-path "work_apply_overtime.daily_overtime_details[0].paymod"
-```
-
-返回示例：
-
-```json
-[
-  {"key": "overtime_reason_xxx_001", "name": "计划内加班"},
-  {"key": "overtime_reason_xxx_002", "name": "计划外加班"}
-]
-```
-
-Agent 必须把 `name` 展示给用户选择，最终写入 `form_info` 的是对应 `key`。
-
-多 enum 联动规则：
-
-- enum 字段之间是平等关系，不要求固定查询顺序；通常可以对 `enum_query_paths` 中的多个 enum 并行调用 options。
-- 查询 enum 时，`--form-info` 必须包含已收集到的所有非 enum 字段；如果没有任何非 enum 字段可收集，则允许传空 `form_info`。
-- 若某个 enum 已经确定（用户已选择，或 options 只有一个选项自动填充），查询其他 enum 时要把这个已知 enum 一起写入 `form_info` 作为参数。
-- 若某个 enum 只返回一个选项，默认自动写入该 `key`，继续查询下一个 enum，不需要让用户选择。
-- `record` 内 enum 也不要求顺序，可并行查询。
-- `list<record>` 行之间没有依赖：先收集每一行的非 enum 字段，然后可并行查询所有行的 enum options；同一行内多个 enum 字段也不要求固定顺序，可并行查询。
-- 不允许在存在非 enum 上下文但尚未收集时，用空 `form_info` 查询依赖日期/时长等上下文的 enum。
-
-## 用户展示文案模板
-
-确认态和成功态必须优先复用 `display_summary.text`；如需自行展示，字段名必须保持一致：
-
-```text
-加班类型：<加班类型>
-加班日期：<YYYY-MM-DD 周X>
-加班时长：<N小时>
-加班原因：<加班原因>
-计算方式：<加班费|调休假>
-请确认以上信息
-```
-
-固定口径：
-
-| 展示字段 | 固定写法 | 禁止写法 |
-|----------|----------|----------|
-| 计算方式 | `计算方式：调休假` | `补偿方式：调休` |
-| 加班原因 | `加班原因：xxx` | `事由：xxx` |
-| 确认提示 | `请确认以上信息` | 自由改写 |
-
-## Step 4: 格式转换
-
-将历史 `render` 返回的字段数组转换为提交格式。正常高效流程下，优先直接使用 `+overtime-apply-render` 输出的 `submit_form_info`，无需单独执行本命令。
-
-```bash
-people-cli attendance +overtime-apply-convert --input @render_response.json
-```
-
-转换原则：
-
-- 外层字段直接抽取 `value`。
-- `list` 类型转换成数组格式。
-- 自定义控件 `type=record` 按 `template_sub_fields` 结构转化。
-- 只转化 `template_sub_fields` 中包含的字段，`value` 从 `sub_fields` 获取。
-
-## Step 5: 发起加班申请
-
-调用 `+overtime-apply-create` 前必须向用户展示最终摘要并获得独立二次确认。摘要必须覆盖最终 `submit_form_info` 中所有申请数据，包括服务端默认字段、多段加班明细、不可修改字段和唯一选项 enum；如果 `display_summary.text` 信息不完整，必须补充展示 `submit_form_info` 中遗漏的字段。没有这次 create 前确认，不得调用 create。
-
-```bash
-people-cli attendance +overtime-apply-create --form-info '<submit_form_info_json>' --time-zone "Asia/Shanghai" --yes
-```
-
-成功返回：
-
-```json
-{
-  "create_result": true,
-  "record_id": 7637050129895132688 
-}
-```
-
-
-
-若返回 `create_result: false`，向用户展示 `create_invalid_msg`。如果 `CreateInvalidMsg.InvalidFields[].Message` 或 `create_invalid_msg.invalid_fields[].message` 是“操作频繁，请稍后重试。”，应向用户展示“操作频繁，请5秒后重试。”。
-返回结果中的 `record_id` 是生成的加班记录的唯一ID，并非审批流程的ID。
-
-## Shortcuts 执行流程
-
-### 快捷发起加班
-
-适用于用户一次性提供完整加班信息，如日期、加班时长、原因、备注。当前不支持开始时间-结束时间的加班时段模式。
-
-1. **执行日期确认（Step 0，不可跳过）**：提取用户日期表达 → 调用 `resolve_date.py` → 向用户展示确认 → 用户确认后继续。
-2. 构造 `form_info`，日期使用 Step 0 确认的 `YYYY-MM-DD`，时长使用用户明确提供或确认后的小时数；不要构造 `work_overtimes/start_time/end_time`。
-3. 调用 `+overtime-apply-render --form-info '<form_info_json>'` 校验，优先内联传参，不写临时文件。
-4. 如 `validate_results` 或 `missing_fields` 中存在非 enum 缺失字段，先一次性向用户补齐这些非 enum 字段；如果缺失字段来自 `daily_overtime_details.overtime_date/overtime_duration`，只问日期和时长，不问时段。
-5. 如 `enum_query_paths` 中存在未填 enum 字段，在非 enum 字段齐全后可并行调用 `+overtime-apply-options`；如果某个 enum 已经确定，查询其他 enum 时把已知 enum 一起带入 `form_info`。
-6. 非 enum 和 enum 都收集完成后，重新调用 `+overtime-apply-render --form-info '<form_info_json>'` 复核。
-7. `ready_to_create=true` 后，直接把 `submit_form_info` 序列化为 JSON 字符串作为最终提交参数，不写 `final_form.json`。
-7. 优先展示最终 `display_summary.text`，并用 `submit_form_info` 补齐所有未展示字段，等待用户做 create 前独立二次确认。
-8. 用户明确确认后调用 `+overtime-apply-create --form-info '<submit_form_info_json>' --time-zone "<time_zone>" --yes`。
-
-### 快捷查询选项
-
-适用于用户询问“加班原因有哪些”“补偿方式有哪些”等。
-
-```bash
-people-cli attendance +overtime-apply-render --form-info ''
-people-cli attendance +overtime-apply-options --form-info '<form_info_json>' --query-path "work_apply_overtime.daily_overtime_details[0].paymod"
-```
-
-如果用户询问的枚举字段不是 `overtime_reason`，先从 `+overtime-apply-render` 返回的 `enum_query_paths` 中确认对应 `query-path`，不要猜测路径。
-
-## 用户交互规范
-
-- **必须确认后才能提交**：调用 `+overtime-apply-create --yes` 之前，必须优先展示最终 `display_summary.text`，并用最终 `submit_form_info` 补齐所有未展示字段后获得用户明确二次确认。摘要中必须包含**绝对日期**（如 `2026-05-16`），便于用户校验日期是否正确；不能只展示部分字段。
-- **二次确认不可复用**：create 前二次确认必须独立发生在 create 前一刻；日期校准确认、enum 选择确认、render 后修改确认、用户前面说过“确认”，以及 `ready_to_create=true` 都不能视为允许提交。
-- **校验错误要解释**：将 `validate_results` 翻译成用户友好的补充信息。
-- **枚举字段要展示选项**：遇到 enum 类型，查询 `+overtime-apply-options` 后让用户选择。
-- **不要默认填充未知字段**：用户未明确提供的字段不要用“无”“默认”“其他”等占位值填充，应让 `render` 返回缺失项后提醒用户。
-- **补偿方式不要猜测**：`paymod_pay` 表示加班费，`paymod_compensatory_leave` 表示调休假，`paymod_readonly` 表示仅记录；没有用户选择时不要填写。
-- **options 可能是宽表选项**：`+overtime-apply-options` 返回的时长/计算方式不代表在当前日期一定合法；日期、时长、计算方式的最终合法性以后续 `+overtime-apply-render` 的 `validate_results` 为准。
-- **业务红线优先阻断**：`validate_results`、`create_invalid_msg` 或规则说明中出现工作日超 3 小时、休息日/法定节假日超 8 小时、当天不可申请、每周至少 1 个完整休息日等信息时，应先提示原因并给出明确调整建议（如“请调整为 3 小时”“建议只选择一天”），不要继续 create。
-- **操作频繁提示**：create 返回 `CreateInvalidMsg.InvalidFields[].Message="操作频繁，请稍后重试。"` 时，统一提示“操作频繁，请5秒后重试。”，让用户和 agent 明确等待 5 秒后再重试。
-- **日期必须经过 Step 0 确认**：所有加班日期（无论绝对/相对）必须先通过 `resolve_date.py` 脚本计算或 Agent 推导，再向用户展示确认后才能写入 form_info。不得跳过此步骤直接构造日期参数。写入 `form_info` 的最终值必须是 `YYYY-MM-DD` / `YYYY-MM-DD HH:MM:SS`，不要传 `这周六` 等中文相对表述。
-- **不支持时段模式**：发起加班只支持日期 + 时长，不支持开始时间 - 结束时间。不要构造 `work_apply_overtime.work_overtimes`、`start_time`、`end_time`；用户说“19 点到 22 点”时，应先复述为“加班日期 YYYY-MM-DD、加班时长 3 小时”并让用户确认，确认后只写入日期和时长字段。
-- **render 字段决定追问口径**：只要 render 结果包含 `daily_overtime_details`，且其中有 `overtime_date` 与 `overtime_duration`，就必须按日期 + 时长模式追问。即使用户没有给时长，也应该问“加班时长是多少小时”，不能问“几点到几点”。
-- **最多 2 段加班**：`work_apply_overtime.daily_overtime_details` 每次申请最多 2 条。用户表达 2 段以内时，必须放在同一次 `form_info` 中一起提交，不要拆成多个独立申请。用户表达超过 2 段时，直接拒绝并提示「当前一次申请最多支持 2 段加班，请减少到 2 段以内后再提交」；不要合并、截断或拆分成多次申请。CLI 会在 `--form-info` 校验阶段直接报错。
-- **仅支持为本人发起**：加班申请只能为当前登录用户本人发起。AI 不得询问申请人、被加班人、下属、同事、工号、用户 ID、open_id、union_id 等身份信息，也不要在 `form_info` 中构造 `applicants`、`employee_id`、`employee_no`、`employment_id`、`user_id`、`open_id`、`union_id` 等字段；如果 `form_info` 中出现这类字段，CLI 会直接报错。用户表达“帮别人申请”“给工号 E12345 申请”“帮下属提交”时，直接拒绝并提示「当前只支持给本人发起加班申请，不支持代提他人加班」。
-- **每轮 render 后必须向用户展示全量字段进行确认**：
-  - 展示当前 `submit_form_info` 中**所有**已收集字段，而不是只展示缺失项；包括服务端默认填充的字段。
-  - 字段分组：基础字段（如 `notes`、`reason_for_cancellation`）一组；`daily_overtime_details` 等日期 + 时长多段记录每段单独展示。
-  - `writable=true` 字段标记为「可修改」，允许用户调整后重新 render。
-  - `writable=false` 字段标记为「不可修改」。
-  - 经 `+overtime-apply-options` 查询后**只有一个可选项**的 enum 字段（如部分场景的 `paymod`）：直接写入该唯一 `key`，标记为「不可修改」，不接受用户调整请求，也不要让用户「选」。
-  - **可写 enum 字段（`writable=true` 且 `type.type=enum`）**：用户可以修改，但取值范围**严格限定于** `+overtime-apply-options` 返回的选项集；
-    - 修改前先调用 options 拿到选项列表，向用户展示 `name`；
-    - 用户给出的值若不在选项集内，拒绝写入并提示「只能从以下选项中选择：…」；不要做模糊匹配或自由文本写入；
-    - 最终写入 `form_info` 的必须是选项的 `key`，不是 `name`。
-  - 用户提出修改 → 更新 `form_info` → 重新 render；用户确认无修改 → 进入 create 二次确认。
-- **不支持取消/撤回/修改**：相关诉求不要调用 `+overtime-apply-create`，直接说明当前能力边界。
-
-## 环境变量
-
-| 变量 | 说明 | 默认值 |
-|------|------|--------|
-| `PEOPLE_CLI_CONFIG` | people-cli 配置文件路径 | 默认配置路径 |
-
-## 错误处理
-
-| 错误 | 解决方案 |
-|------|----------|
-| 未登录或缺少 scope | 提示用户执行 `people-cli auth login --scope "attendance:over_time:read attendance:over_time:write"` |
-| `validate_results` 非空 | 根据错误信息补充必填字段，重新 `+overtime-apply-render` |
-| `create_result: false` | 展示 `create_invalid_msg` 给用户 |
-| token 过期，错误码 `99991663`、`99991664`、`99991665`、`99991668` | 提示用户重新授权或刷新登录态 |
-| 非业务校验类命令/API 报错且参数不变 | 原命令原样重试 1 次；仍失败则停止并告知用户 |
-| 自动修改参数后重试 | 大模型基于已知信息自动改参时累计最多 3 次；仍失败则停止并告知用户最后一次错误 |
-| 用户补充或修改信息 | 属于新的输入轮次，不计入自动改参重试次数 |
-| 不支持的操作或确定性业务拦截 | 不重试，直接告知用户不支持或给出修正建议 |
-
-## 注意事项
-
-- `form_info` 在 `+overtime-apply-render`、`+overtime-apply-options`、`+overtime-apply-create` 之间流转，必须保持一致。
-- `form_info` 在多轮调用间优先保存在对话上下文/内存变量中，并以内联 JSON 传给 CLI；不要把中间态写入 `form_info.json` 或 `final_form.json`。
-- `date` 字段必须使用 `2006-01-02` 格式字符串。
-- 不要在 `form_info` 中传 `applicants`、`employee_id`、`employee_no`、`employment_id`、`user_id`、`open_id`、`union_id` 等身份字段；加班申请只能为当前登录用户本人发起，申请人由服务端基于登录态处理，CLI 会在 `--form-info` 校验阶段拒绝这类入参。
-- 发起加班只支持日期 + 时长；不要在 `form_info` 中传 `work_apply_overtime.work_overtimes`、`start_time`、`end_time`。
-- `work_apply_overtime.daily_overtime_details` 最多 2 段；2 段以内同一次申请一起提交，超过 2 段 CLI 会直接报错。
-- 不要传 `reason_for_cancellation: "无"` 这类占位值；缺失字段由 `render` 识别并返回给用户补充。
-- 加班明细字段以服务端 render 返回为准，常见 enum 路径如 `work_apply_overtime.daily_overtime_details[0].paymod`。
-- 不要跳过 `+overtime-apply-render` 直接 `+overtime-apply-create`。
-- 不要在用户确认前提交加班申请。

package/skills/people-overtime/references/people-attendance-overtime.md

@@ -1,51 +0,0 @@
-# user_approval_over_time
-
-
-
-**CRITICAL — 默认适用于 CN 中国大陆员工**：本接口查询的是 CN 中国大陆加班审批单数据；**非 CN（新加坡 SGP / 马来西亚 MY / 其他海外）员工**默认请改用 `submission.get` (`time_type=2`) 查询加班提报记录或 `submission.query_month_summary` 查询月度汇总。**仅当调用本接口时返回报错文案包含 `method only support CHN country`，才允许自动回退到 `submission` 对应查询**；若只是空结果，则直接按无记录处理，不要切换接口。
-
-**CRITICAL — 只支持查询当前登录用户的加班，不支持查询其他人加班记录**
-
-## 参数填充规则
-
-`user_approval_over_time.list` 必须通过 `--params` 传 JSON；不要编造 `--check-date-from`、`--check-date-to`、`--status` 等独立 flag。日期字段必须传 `YYYYMMDD` 字符串，不要传 JSON 数字。
-
-```bash
-people-cli attendance user_approval_over_time list --params '{"check_date_from":"20260523","check_date_to":"20260523","status":2}'
-```
-
-| 参数              | 描述                                                                 |
-|-----------------|--------------------------------------------------------------------|
-| check_date_from | 开始时间，必填，格式为 `YYYYMMDD` 字符串                                             |
-| check_date_to   | 结束日期，必填，格式为 `YYYYMMDD` 字符串，结束时间-开始时间不能大于30天，超过需分段查询                    |
-| status          | 审批状态，必填，用户不指明查询审批状态的话，强制设置为'2'; 0,审批中; 1,已拒绝; 2,审批通过; 3,已撤回; 4,已撤销 |
-
-## API Resources
-
-```bash
-people-cli schema attendance.<resource>.<method>   # 调用 API 前必须先查看参数结构
-people-cli attendance <resource> <method> --params '<json>' # 调用 GET/list API
-```
-
-> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
-
-### user_approval_over_time
-
-- `list` —
-
-## 权限表
-
-| 方法 | 所需 scope |
-|------|-----------|
-| `user_approval_over_time.list` | `corehr:people_cli` |
-
-## 加班记录完整返回字段说明
-
-| 参数         | 描述                                                          |
-|------------|-------------------------------------------------------------|
-| duration   | 加班时长，必须结合unit字段，case：1天，8小时。加班时长不能使用start_time减end_time的值替换 |
-| unit       | 加班时长单位: 1, 天；2，小时；3，半天；4，半小时                                |
-| start_time | 加班开始时间                                                      |
-| end_time   | 加班结束时间                                                      |
-| status     | 审批状态：0,审批中; 1,已拒绝; 2,审批通过; 3,已撤回; 4,已撤销                     |
-| reason     | 加班原因                                                        |