@lark-people/cli 0.0.16 → 0.0.18

package/skills/people-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: people-cli
 version: 1.0.0
-description: "当用户需要处理飞书人事或飞书招聘数据时使用；覆盖 CoreHR 员工、组织（部门、成本中心和自定义组织）、入职流程、异动、离职、续约/续签、编制/HC，以及 Hire 职位、招需、投递、候选人、面试、评估、人才查询；也适用于 CLI 安装、升级、登录授权、Permission denied 和 scope 权限问题。"
+description: "当用户需要处理飞书人事、招聘或考勤数据时使用；覆盖 CoreHR 员工、组织（部门、成本中心和自定义组织）、入职流程、异动、离职、续约/续签、编制/HC，Hire 职位、招需、投递、候选人、面试、评估、人才查询，以及考勤打卡结果、日报/月报统计、统计字段与当前视图设置；也适用于 CLI 安装、升级、登录授权、Permission denied 和 scope 权限问题。"
 metadata:
   requires:
     bins: [ "people-cli" ]
@@ -10,14 +10,14 @@ metadata:
 
 # People CLI
 
-飞书 People 全能套件，通过 `people-cli` 命令行工具查询飞书人事、CoreHR 和招聘数据。
+飞书 People 全能套件，通过 `people-cli` 命令行工具查询飞书人事、CoreHR、招聘和考勤数据。
 
 主入口只做标准化前置检查、用户身份合规约束和业务域分发。下方 Step 5 是路由表：判断用户意图属于哪个业务域，然后读取该域对应的嵌入子
-Skill，再按子 Skill 的参数规范构造命令；构造完成后必须过 Step 6 确认单批拉取的数据量才能执行。重点关注：
+Skill，再按子 Skill 的参数规范构造命令；构造完成后必须过 Step 6 决定本次命令是走单批数据量自检，还是落入明确的免分页例外。重点关注：
 
 1. 嵌入子 Skill 要求继续加载 reference 时，必须加载该子 Skill 自己目录下的 reference。
 2. 严禁凭路由表描述或自身记忆猜测参数、字段、分页、元数据校准或输出格式。
-3. 每条取数命令执行前应过 Step 6 的自检，尽量按推荐值显式指定单批拉取的数据量。
+3. 每条取数命令执行前都应过 Step 6：有分页/limit 参数的命令尽量显式指定单批拉取的数据量；天然没有这些参数的命令只确认自己属于免分页列表，不追加不存在的 flag，也不虚构上限。
 
 ## ⚠️ 标准执行流程 - 使用任何业务命令前必须执行
 
@@ -175,9 +175,23 @@ N、编制明细和原始行数据。普通员工人数走员工；涉及计划
 
 → 详见 [people-hire](references/people-hire/SKILL.md)
 
+#### 打卡结果查询 (attendance-user-task)
+
+本人或指定员工的实际打卡、上下班结果、迟到、早退、缺卡及打卡记录中的排班状态。日报统计指标走考勤统计域，员工资料搜索只是辅助解析步骤，不改变最终业务路由。
+
+→ 详见 [people-attendance-user-task](references/people-attendance-user-task/SKILL.md)
+
+#### 考勤日报/月报统计 (attendance-stats-data)
+
+日度或月度统计数据、日报/月报指标、当前视图字段和经授权字段调整。实际打卡明细、休息日是否有打卡等问题走打卡结果域；招聘报表、员工花名册和其他业务报表仍按最终对象路由。
+
+→ 详见 [people-attendance-stats-data](references/people-attendance-stats-data/SKILL.md)
+
 #### 路由判定规则
 
 - 必须先识别用户最终想查询的对象，再把日期、地点、部门、状态等识别为筛选条件；禁止仅按句中出现的单个词路由。
+- 用户最终想查本人或他人的打卡结果、上下班记录、迟到、早退、缺卡、休息日/未排班是否有打卡时，路由到 `attendance-user-task`。
+- 用户最终想查日报/月报、日度/月度统计指标、统计字段、当前统计视图，或想在已授权前提下调整当前统计视图字段时，路由到 `attendance-stats-data`。
 - 用户最终想查入职名单、入职记录、入职流程、入职进度或待入职人员时，路由到 `prehire`。
 - 用户最终想查员工、员工名单、员工花名册、员工档案或在职人员时，路由到 `employee`。
 - 用户最终想查投递、候选人、面试、职位或招聘需求时，路由到 `hire`；想查调动、晋升、转岗或异动记录时，路由到 `job-change`。
@@ -185,6 +199,8 @@ N、编制明细和原始行数据。普通员工人数走员工；涉及计划
   Skill 根据真实元数据确认。
 - 用户最终想查编制方案、HC、预增、预减、缺编数、满编率、方案维度、编制汇总或明细时，路由到 `workforce-plan`；组织只作为编制规划的筛选或分组维度时仍走
   `workforce-plan`。
+- 在考勤语境里，姓名搜索、工号解析和权限回退只是辅助步骤；解析完成后必须回到最终的考勤业务域，不能因为先查了员工信息就改路由到 `employee`。
+- 在考勤语境里，实际打卡明细与排班状态归 `attendance-user-task`，统计口径、日报/月报指标与字段设置归 `attendance-stats-data`；提报、补卡、审批等不在本主入口覆盖范围。
 - 一个词同时可能是业务域提示和实体名称的一部分时，不得拆词触发；必须以用户最终要求返回的对象或指标判定业务域。
 - 续约、离职等其他对象继续按上方各业务域定义路由。描述中的话术是可判别示例，不是需要穷举的关键词白名单。
 - 如果多个业务对象都成立且无法确定主对象，问一个简短澄清问题。
@@ -205,13 +221,21 @@ N、编制明细和原始行数据。普通员工人数走员工；涉及计划
 **（有的是 `--limit`，有的是 `--page-size`，有的要写进 `--params` 里的 `page_size`），务必按下表「参数」列构造，不要一律猜成
 `--page-size`。
 
+**先判定是否属于免分页命令。** 考勤 `+user-task-query`、`+user-task-admin-query`、`+stats-views-query`、`+stats-views-update`、
+`+stats-data-query`、`+stats-data-admin-query` 没有分页或 `limit` 参数。对这些命令只确认日期范围、统计类型和管理员人员列表等必要上下文，不追加
+`--page-size`/`--limit`，不虚构分页上限。注意：考勤打卡和统计管理员查询仍有业务批量限制：打卡结果每次最多 50 个 `user_ids`，考勤统计每次最多 20 个 `user_ids`；打卡结果和统计数据查询日期范围单次不超过 31 天，超出时按对应考勤子 Skill 的自然月拆分规则执行。其他接口仍按下表执行。
+
+**写操作确认授权可复用，但纯查询不等于写授权。** 如果当前会话里，用户已经对同一登录身份、同一当前视图、同一 `stats-type`、同一 `employee-type`
+且同一字段给出过明确开启授权，主入口可以复用该授权，不重复拦截；如果只是想查询字段、解释字段或读取统计数据，不视为已授权写设置。若子 Skill 已根据“明确要求开启/增加字段”判定可直接更新，主入口不得再重复确认一次。
+
 **执行前自检（每条取数命令都过一遍）**：
 
-1. 命令里是否已**显式**指定了单批拉取的数据量？（尽量不靠 CLI 默认值）
-2. 用的参数名是否正确？（见下表「参数」列）
-3. 取值是否等于该业务域的推荐值（取 Max）？
+1. 该命令是否属于上面的免分页列表？如果是，只核对必要上下文，不追加分页参数；若是考勤打卡或统计数据命令，还要检查对应人数上限和 31 天限制。
+2. 如果不属于免分页列表，命令里是否已**显式**指定了单批拉取的数据量？（尽量不靠 CLI 默认值）
+3. 如果不属于免分页列表，用的参数名是否正确？（见下表「参数」列）
+4. 如果不属于免分页列表，取值是否等于该业务域的推荐值（取 Max）？
 
-有任一为否，尽量先补齐再执行。
+非免分页命令有任一为否，尽量先补齐再执行。
 
 **核心原则：用「一批多拉 + 少翻页」，不要用「一批少拉 + 多翻页」。** 限流卡的是请求数 /
 频率，单批拉得越少翻页越多、请求越多，越容易触发限流。所以每次取数都按下表用该接口允许的最大单批数据量，一批多取、少翻页。
@@ -236,10 +260,10 @@ Skill 为准，冲突时服从子 Skill。
 - 默认不向用户暴露内部 ID，例如
   employee_id、department_id、job_id、application_id、talent_id、cursor、next_cursor；优先展示姓名、部门名、职位名、状态、日期、数量和可读链接。
 - 如果 CLI 返回 `log_id`，可以保留用于排障。
-- 写入、更新、删除、提交申请或发起流程前必须向用户确认关键字段；能 dry-run 时先 dry-run。
+- 写入、更新、删除、提交申请或发起流程前，必须确认当前动作及关键字段已经有有效授权；如果当前会话里对同一登录身份、同一对象/视图、同一统计类型和同一字段集合已经给过明确授权，则直接复用，不重复追问。没有现成授权时再向用户确认关键字段；能 dry-run 时可先 dry-run，但 dry-run 不算授权，也不能替代确认。
 - 工具、登录、授权、权限或网络失败时，如实说明失败类型和下一步动作，不编造 People 数据。
 
 ## 不覆盖
 
-- 本阶段不从主入口路由到出勤、加班或其他未列出的 People Skill。
+- 主入口不覆盖考勤提报、补卡、审批、回填等写流程，也不拿打卡结果或统计数据命令替代这些能力。
 - 不处理薪酬、身份证、银行账户、完整档案、跨部门/全公司导出、绕过审批或绕过授权的请求。

package/skills/people-cli/references/people-attendance-common/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: people-attendance-common
+description: "Use from people-cli attendance skills when resolving date ranges or person identifiers for attendance punch results and attendance statistics. 当考勤打卡或统计 skill 需要解析日期、本人/他人、姓名、邮箱、工号、考勤 employee_id 或员工标识类型时使用。"
+metadata:
+  requires:
+    bins: ["people-cli"]
+---
+
+# 考勤通用解析规则
+
+本 skill 是 people-cli 内部引用，不是用户意图入口。打卡结果和考勤统计 skill 在构造命令前使用这里的日期和人员解析规则。
+
+开始前先读取 [people-shared](../people-shared/SKILL.md) 的认证与权限规则。涉及姓名、邮箱或本人混合查询时，读取 [people-corehr-employee](../people-corehr-employee/SKILL.md)，按其真实命令和权限规则解析员工。
+
+## 日期范围
+
+把自然语言时间转换为合法 `YYYYMMDD`：
+
+- 今天、昨天、前天、本周、上周、本月、上月等，基于当前系统日期和会话时区解析。
+- 已有会话明确的时间范围可以复用；用户换了时间条件则重新解析。
+- 起始日期必须 `<=` 结束日期。
+- 完全位于未来的范围不查询；部分在未来时截到今天并说明实际查询范围。
+- 日期非法时先让用户修正，不构造命令。
+
+不要把空结果解释成 0 或没有打卡/没有统计；空结果只表示接口没有返回可用数据。
+
+## 查询对象
+
+| 用户问题及上下文 | 人员处理 |
+| --- | --- |
+| “我/本人/我的”，或没有指定其他对象 | 个人入口；不额外查询自己的 ID |
+| 直接给工号 | 保留字符串和前导零，使用 `--employee-type employee_no` |
+| 直接给考勤 employee_id | 保留原始字符串，使用 `--employee-type employee_id` |
+| 姓名、邮箱、本人混合查询、重名、搜索无结果、分页提示、工号无权限 | 读取并遵循 [people-corehr-employee](../people-corehr-employee/SKILL.md) |
+| “他/那个人”等指代无上下文 | 先澄清对象 |
+
+明确查询他人时不能降级为查询自己；管理员无权限时也不能换个人入口绕过。
+
+## 员工搜索和 ID 回退
+
+姓名或邮箱先读取员工 skill，并按员工 skill 的当前命令说明执行搜索；本 common skill 不复制 `people-cli corehr ...` 的具体调用形式，避免参数规则漂移。
+
+规则：
+
+- 唯一明确匹配且有工号：使用实际返回工号，`--employee-type employee_no`。
+- 多个候选或结果分页可能还有更多：展示必要的姓名、工号或可用标识，让用户确认；不要选第一条。
+- 没有结果：请求用户提供明确工号或考勤 employee_id。
+- 工号字段无权限：按员工 skill 确认可用人事接口是否支持 `employee_id_type=user_id`。该类型下返回的人事 `user_id` 等于考勤 `employee_id`，可作为 `--user-ids` 并设置 `--employee-type employee_id`。
+- 当前 `+employee-search` 和 `+employee-basic-info-query` 没有 `employee-id-type` flag，不能直接追加不存在的参数。必须查看真实 help/schema 后再调用支持该选项的接口。
+- 无法确认支持入口、整体人事查询无权限，或工号与回退 user_id 都无法取得：说明原因并请求明确标识，不编造接口或 ID。
+
+只把上述确认类型的人事 `user_id` 当作考勤 employee_id。通讯录 open_id、未确认类型的 user_id、CoreHR employment_id/person_id 不能直接用于考勤。
+
+## 混合人员
+
+同时查询本人和其他人时，统一使用管理员入口：
+
+- 如果可以统一为工号，全部使用 `employee_no`。
+- 工号无权限时，全部统一为确认过的考勤 `employee_id`。
+- 不能把 `employee_no` 和 `employee_id` 混在同一个 `--user-ids` 列表中。
+- 无法统一标识类型时先澄清或请求补充，不拆成多个不同类型的查询来拼结果，除非用户明确要求分开查。
+
+## 参数约定
+
+| 参数 | 约定 |
+| --- | --- |
+| `--employee-type` | 默认 `employee_id`；使用工号时显式 `employee_no`；使用人事 `employee_id_type=user_id` 回退时为 `employee_id` |
+| `--user-ids` | 仅管理员类命令提供；保留字符串、前导零，保序去重，拒绝空元素 |
+| `--as user` | 考勤相关查询和设置均使用用户身份 |
+
+打卡结果与考勤统计的业务参数、字段解释和输出规则由各自 skill 继续定义。

package/skills/people-cli/references/people-attendance-stats-data/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: people-attendance-stats-data
+description: "Use when users query personal or other employees' attendance statistics, daily reports, monthly reports, requested report fields, or ask to add fields to the current attendance statistics view. 当用户查询本人或他人的考勤统计数据、日报、月报及报表字段时使用。"
+metadata:
+  requires:
+    bins: ["people-cli"]
+  cliHelp: "people-cli attendance +stats-data-query --help"
+---
+
+# 考勤统计数据与字段选择
+
+**CRITICAL — 开始前先读取 [`../people-shared/SKILL.md`](../people-shared/SKILL.md)**，遵循认证、scope 和写操作确认规则。再读取 [people-attendance-common](../people-attendance-common/SKILL.md) 解析日期和人员标识。所有命令都只使用 `--as user`；查询需要 `attendance:task:readonly`，更新统计视图需要 `attendance:task`。
+
+本 skill 组织完整流程：确定统计类型与查询对象，查询当前登录用户的统计视图，按字段规则决定是否允许修改，再查询统计数据。人员和日期解析统一使用 common；不要执行打卡结果命令，也不要把 `shift_id` 等打卡语义用于统计数据。
+
+## 入口选择
+
+| 问题 | 处理 |
+| --- | --- |
+| “我/本人/我的统计数据”，或未指定其他对象 | `+stats-data-query` |
+| 指定其他员工、工号、考勤 employee_id | 解析对象后使用 `+stats-data-admin-query --user-ids ...` |
+| “我和张三”等混合对象 | 统一标识类型后走管理员入口 |
+| 只问字段含义或当前设置 | 只查 `+stats-views-query`，不查数据 |
+| 想新增/开启字段 | 先查 `+stats-views-query`，必要时 `+stats-views-update`，验证成功后再查数据 |
+
+管理员查他人时，**设置查询和设置更新仍然只作用于当前登录用户自己的统计视图**，不修改目标员工的视图。
+
+## 人员、日期与统计类型
+
+人员和日期解析遵循 [people-attendance-common](../people-attendance-common/SKILL.md)：
+
+- 本人默认走个人入口，不额外查询自己的 ID。
+- 用户直接提供工号或考勤 `employee_id` 时直接使用。
+- 其他人员解析，包括姓名、邮箱、本人混合查询、重名确认、工号无权限时的人事 `employee_id_type=user_id` 回退，都按 common 的员工解析流程执行。
+- 只有在人员、日期或统计类型缺失且无法推导时才追问，不重复确认已明确上下文。
+- 工号与考勤 employee_id 不混用；混合查询必须统一成同一种 `employee-type`。
+
+统计类型规则：
+
+- 日报、日度明细使用 `daily`。
+- 月报、月度汇总使用 `month`。
+- 只说“统计数据”且上下文无法推导时，只澄清 `daily` 还是 `month`。
+
+日期规则：
+
+- 将“昨天/本周/上周”等换成 `YYYYMMDD`。
+- `--start-date` 不得晚于 `--end-date`。
+- 完全位于未来的范围不查询；部分在未来时截到今天并说明。
+- 单次统计数据查询的起止日期跨度不能超过 31 天。超过 31 天时，默认按自然月拆分为多个连续查询窗口；只有用户明确要求其他拆分方式时才按其要求处理。
+- 拆分后的每段仍使用相同的 `stats-type`、`locale`、`employee-type`、字段设置状态和人员标识类型。
+
+## 先查询当前统计视图
+
+在判断字段前，先查询当前登录用户、当前统计类型对应的统计视图。
+
+```bash
+people-cli attendance +stats-views-query --as user \
+  --stats-type month --employee-type employee_id --locale zh --format json
+```
+
+约定：
+
+- `+stats-views-query` 必须提供 `--stats-type daily|month`，没有默认值。
+- `--employee-type` 默认 `employee_id`，可选 `employee_no`。
+- `--locale` 默认 `zh`，只有用户明确需要时才改。
+- 设置查询、设置更新和数据查询必须保持**同一 `stats-type`、`locale`、`employee-type` 和登录身份**。
+
+读取完整响应，按 `data.view.items[].child_items[]` 中的真实 `code`、`title`、`value`、`read_only` 做后续判断。已有本轮相同 `stats-type`、`locale`、`employee-type` 和登录身份的有效设置结果可以复用；其中任一条件变化都要重新查询。
+
+## 字段决策
+
+| 用户要求 | 行为 |
+| --- | --- |
+| 未指定字段 | 直接按当前已开启字段查询数据，不询问是否新增字段 |
+| 指定字段且已开启 | 直接查询，并按该字段总结 |
+| 指定字段但当前关闭 | 说明该字段当前不在报表中，询问是否持久修改当前登录用户的该类型统计设置 |
+| 明确要求“增加/开启某字段再查询” | 确认真实字段 code 后直接更新，不重复确认 |
+| 名称歧义、匹配多个字段、未知字段 | 先澄清，不猜 code、不更新 |
+
+匹配字段时以当前统计视图返回的真实 `title` 和 `code` 为准：
+
+- 使用二级字段 `child_items[]`，不要把一级分组当成可开启字段。
+- 只把真实开关字段的 `value="1"` / `value="0"` 当作开启/关闭。
+- 不把其他非开关字段的值误判为布尔状态，例如不能因为值里出现 `1` 就当成“已开启”。
+- 只读字段、非开关字段、未知字段、状态不明确字段，都不能通过 `--enable-fields` 更新。
+
+用户未指定字段时，不要停下来征求“是否新增字段”；直接使用当前视图查询。指定字段关闭时，才询问是否持久修改当前登录用户自己的日报或月报视图。
+
+推荐确认话术必须明确字段名称、字段 code、统计类型和持久影响。例如：
+
+- `字段“出勤时长”(code: 50102) 当前不在你自己的 month 统计视图里。要不要把它持久加入你当前登录账号的 month 报表字段？这会修改你之后查看 month 统计时的默认字段。`
+- `字段“迟到次数”(code: 60103) 当前不在你自己的 daily 统计视图里。要不要把它持久加入你当前登录账号的 daily 报表字段？这会修改你之后查看 daily 统计时的默认字段。`
+
+如果用户一开始就明确要求“开启/增加某字段”，这本身就是对该字段变更的授权；确认真实 code 后直接更新，不重复再问一次。
+
+## 更新统计视图
+
+仅在以下两种情况下允许更新：
+
+1. 用户在“指定字段当前关闭”的情况下明确同意修改当前视图。
+2. 用户一开始就明确要求“增加/开启某字段”。
+
+月报、`employee_id` 示例：
+
+```bash
+people-cli attendance +stats-views-update --as user \
+  --stats-type month --employee-type employee_id --locale zh \
+  --enable-fields 50102
+```
+
+如果后续管理员数据查询要使用 `employee_no`，那么前面的设置查询和授权更新也必须保持相同的 `employee_no`，不要先用 `employee_id` 链路再切到 `employee_no`。例如：
+
+```bash
+people-cli attendance +stats-views-query --as user \
+  --stats-type month --employee-type employee_no --locale zh --format json
+people-cli attendance +stats-views-update --as user \
+  --stats-type month --employee-type employee_no --locale zh \
+  --enable-fields 50102
+people-cli attendance +stats-data-admin-query --as user \
+  --stats-type month --employee-type employee_no --locale zh \
+  --user-ids 001,002 --start-date 20261001 --end-date 20261025 --format json
+```
+
+只有在该字段已经开启，或者用户已明确授权开启并且更新验证成功后，才继续最后一步管理员数据查询。
+
+更新规则：
+
+- 只开启本次需要的二级 `code`，不关闭已有字段。
+- 不手工构造部分视图；依赖命令自身先查当前完整视图、保留未指定字段后再提交。
+- 更新的是当前登录用户自己的该类型视图，不是目标员工的视图。
+- 只读字段、非开关字段、未知字段、重名未澄清字段，一律不更新。
+- 单纯想查某个未开启字段，不等于已经授权写设置；没有明确确认前不能更新。
+
+如果用户拒绝修改：
+
+- 不调用更新命令。
+- 说明该字段当前不能通过现有报表直接获取。
+- 只有用户改为查询已有字段时再继续。
+
+## 更新后必须验证
+
+更新成功后，先确认目标字段真的处于开启状态，再继续查数据。
+
+- 优先检查更新响应里的目标字段状态。
+- 如果响应缺少足够状态，重新执行一次 `+stats-views-query` 验证。
+- 如果更新失败，或验证后仍不能确认字段已开启，**立即停止**，不要假设后续数据查询会带出该字段。
+
+## 查询统计数据
+
+字段已确定且所需更新已经确认成功后，再执行数据查询。
+
+当前用户：
+
+```bash
+people-cli attendance +stats-data-query --as user \
+  --stats-type month --employee-type employee_id --locale zh \
+  --start-date 20261001 --end-date 20261025 --format json
+```
+
+管理员查指定员工：
+
+先保证前面的设置查询/更新与最终管理员查询保持同一个 `employee-type`。例如，下面这个管理员工号查询的完整链路里，设置查询和可选更新也都必须使用 `employee_no`：
+
+```bash
+people-cli attendance +stats-views-query --as user \
+  --stats-type month --employee-type employee_no --locale zh --format json
+people-cli attendance +stats-views-update --as user \
+  --stats-type month --employee-type employee_no --locale zh \
+  --enable-fields 50102
+people-cli attendance +stats-data-admin-query --as user \
+  --stats-type month --employee-type employee_no --locale zh \
+  --user-ids 001,002 --start-date 20261001 --end-date 20261025 --format json
+```
+
+参数约定：
+
+- 两个数据命令都要求 `--stats-type`、`--start-date`、`--end-date`。
+- `--employee-type` 默认 `employee_id`；使用工号时显式设置 `employee_no`。
+- `--need-history` 和 `--current-group-only` 默认都是 `true`；只有用户明确要求时才改。
+- 不传单独 `--user-id`。个人查询不传 `--user-ids`；管理员查询必须提供 `--user-ids`。
+- 数据 API 没有字段过滤参数，**不要虚构字段列表请求**；字段范围由当前统计视图控制。
+
+## 批量与长日期范围
+
+- 管理员统计查询每次最多传 20 个 `user_ids`。超过 20 人时，按已解析顺序分批，每批最多 20 个；不要丢弃、重排或混合不同 `employee-type`。
+- 日期范围超过 31 天时，默认按自然月拆分。例如 20260115 到 20260310 拆成 20260115-20260131、20260201-20260228、20260301-20260310。
+- 人数和日期都超限时，按“日期窗口 × 人员批次”执行多次查询。先固定一个日期窗口，再遍历该窗口下的人员批次；每次查询都保持同一统计类型、字段设置状态和参数默认值。
+- 用户明确要求按周、按自定义日期段或指定人员分组时，遵循用户拆分要求，但每次仍不能超过 20 人和 31 天。
+- 回答时合并展示结果，说明实际拆分的日期窗口和人员批次数；不要把多个批次的部分失败列表吞掉。
+
+## 结果解读
+
+读取完整 envelope，重点看：
+
+- `data.user_datas`
+- 每个用户下的 `datas`
+- `invaild_user_ids`
+- `unauthorized_user_ids`
+- 以及额外返回字段
+
+回答规则：
+
+- 未指定字段时，按当前视图和实际返回字段总结。
+- 指定字段时，聚焦该字段；字段没返回就明确说“未返回”，不要写成 `0`。
+- 部分成功时，只对成功返回的用户下结论；无效或无权限用户单独说明。
+- 空结果不代表零统计，也不代表用户没有考勤数据。
+- 不擅自累加、换算或解释未知口径的值。
+- 需要原始结构、完整 JSON 或命令时再展示；默认直接给业务结论。
+
+## 最终检查
+
+- 使用了正确的统计类型：`daily` 或 `month`。
+- 已按 [people-attendance-common](../people-attendance-common/SKILL.md) 解析人员和日期，未混用 employee_no 与 employee_id。
+- 设置查询、设置更新、数据查询三步使用相同的 `stats-type`、`locale`、`employee-type` 和登录身份。
+- 查询他人时没有修改对方视图，仍然只使用当前登录用户自己的视图。
+- 未指定字段时没有多余询问；指定关闭字段时做了明确的写设置确认；明确要求开启字段时没有重复确认。
+- 只读、非开关、未知或状态不明字段没有被错误更新。
+- 更新成功已验证；更新失败或状态未确认时已停止。
+- 缺字段不当作 `0`，部分失败没有被说成全部成功。

package/skills/people-cli/references/people-attendance-user-task/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: people-attendance-user-task
+version: 1.1.0
+description: "Use when users ask about attendance punch/check-in/check-out results, late arrival, early departure or missing punches for themselves or other employees identified by name, email, employee number or attendance employee_id. 当用户查询本人或他人的打卡结果、迟到、早退、缺卡或打卡记录中的排班状态时使用。"
+metadata:
+  requires:
+    bins: ["people-cli"]
+  cliHelp: "people-cli attendance +user-task-query --help"
+---
+
+# 打卡结果查询
+
+先读取 [people-shared](../people-shared/SKILL.md) 的认证与权限规则，并按 [people-attendance-common](../people-attendance-common/SKILL.md) 解析日期和人员标识。两个查询命令都仅支持 `user_access_token`，使用 `--as user`，需要 `attendance:task:readonly`。查询他人由服务端校验当前用户的管理员权限，不需要切换 bot。
+
+本 skill 仅查询打卡结果。出勤/加班提报汇总未在本 people-cli 包接入，不用打卡结果或统计数据命令代替；补卡、审批等写操作不在本 skill 范围。只讨论字段含义时直接解释，不发起查询。
+
+## 自动选择查询入口
+
+| 用户问题及已确认上下文 | 处理 |
+| --- | --- |
+| “我/本人/我的打卡”，或未指定其他对象 | `+user-task-query`，不传 `--user-ids`，无需查询本人工号 |
+| 指定其他姓名、邮箱、工号或考勤 employee_id | 解析目标后 `+user-task-admin-query --user-ids ...` |
+| “我和张三”等混合人员 | 获取全部人员的统一标识，使用管理员入口 |
+| “他/那个人”且上下文不能确定是谁 | 澄清对象，不能默认查自己 |
+| 没有可推导的日期范围 | 只询问时间范围 |
+
+明确的会话对象、标识和日期可以复用，不重复追问。明确查询他人时，不能因人员解析失败或管理员无权限改成查询自己，也不能通过个人接口绕过权限。人员和日期的详细规则统一见 [people-attendance-common](../people-attendance-common/SKILL.md)：只有用户直接给出工号或考勤 `employee_id` 时直接使用；姓名、邮箱、本人混合查询、工号无权限回退等都走 common 中的员工解析流程。
+
+## 参数
+
+| 参数 | 个人与管理员共同约定 |
+| --- | --- |
+| `--start-date`、`--end-date` | 必填，合法 `YYYYMMDD` |
+| `--employee-type` | 默认 `employee_id`；使用工号时显式 `employee_no` |
+| `--need-overtime-result` | 默认 `true`；用户明确不需要班次内加班班段时设 `false` |
+| `--include-terminated-user` | 默认 `false`；明确要同标识对应的全部在职与离职数据时设 `true` |
+| `--user-ids` | 个人不提供，命令发送空数组默认查自己；管理员必填，保序去重、拒绝空元素 |
+
+`ignore_invalid_users=true` 由命令固定发送，不提供 `--ignore-invalid-users`。不提供 `--user-id` 或发送单独 `user_id`。目标和时间明确后直接执行，默认用 `--format json` 读取完整结果；`--dry-run` 仅供请求检查，不能作为查询结果回答。
+
+## 批量与长日期范围
+
+- 管理员查询每次最多传 50 个 `user_ids`。超过 50 人时，按已解析顺序分批，每批最多 50 个；不要丢弃、重排或混合不同 `employee-type`。
+- 日期范围超过 31 天时，默认按自然月拆分为多个连续查询窗口。例如 20260115 到 20260310 拆成 20260115-20260131、20260201-20260228、20260301-20260310。
+- 人数和日期都超限时，按“日期窗口 × 人员批次”执行多次查询。先固定一个日期窗口，再遍历该窗口下的人员批次；每次查询都保持同一 `employee-type`、`need-overtime-result` 和 `include-terminated-user`。
+- 用户明确要求按周、按自定义日期段或指定人员分组时，遵循用户拆分要求，但每次仍不能超过 50 人和 31 天。
+- 回答时合并展示结果，说明实际拆分的日期窗口和人员批次数；不要吞掉任一批次的 `invaild_user_ids` 或 `unauthorized_user_ids`。
+
+## 个人查询
+
+“查我10月1日至7日的打卡”：
+
+```bash
+people-cli attendance +user-task-query --as user \
+  --start-date 20261001 --end-date 20261007 --format json
+```
+
+无需员工搜索、无需手工填自己的 ID。命令调用 `user_task.query`，其他查询参数和管理员入口一致。
+
+## 管理员查询其他人
+
+先按上述规则解析明确的目标。工号为 `001`、`002` 时：
+
+```bash
+people-cli attendance +user-task-admin-query --as user \
+  --employee-type employee_no --user-ids 001,002 \
+  --start-date 20261001 --end-date 20261007 --format json
+```
+
+通过确认的 `employee_id_type=user_id` 人事查询取得 ID 后，使用以下格式；示例值仅代表已解析的考勤 employee_id：
+
+```bash
+people-cli attendance +user-task-admin-query --as user \
+  --employee-type employee_id --user-ids 123,456 \
+  --start-date 20261001 --end-date 20261007 --format json
+```
+
+命令调用 `user_task.admin_query`。无权限时按真实错误说明；不要换个人接口或 bot 重试。缺应用/user scope 或 token 失效按 people-shared 的认证流程处理，不能把缺管理员数据权限简单当作缺 scope。
+
+## 排班状态与打卡结果
+
+读取完整 envelope 的 `data.user_task_results[]`。`shift_id` 是班次 ID，标准返回字符串；数值特殊值的含义相同，其他 ID 不转浮点数。
+
+| `shift_id` | 排班状态 |
+| --- | --- |
+| `"0"` 或数值 `0` | 休息日 |
+| `"-1"` 或数值 `-1` | 未排班 |
+| 其他有效值 | 有具体班次；使用实际返回名称，名称缺失时显示 ID，不编造名称 |
+| 缺失、null 或空值 | 排班状态未返回，不能推断为休息日或未排班 |
+
+**排班状态与打卡状态分别解释。** 休息日、未排班不直接代表缺卡、迟到或旷工。休息日或未排班有实际打卡记录时仍展示，不能过滤掉。
+
+- 上下班结果依据 `records[].check_in_result`、`check_out_result` 及对应 supplement。Normal 可解释为正常，明确返回的迟到/早退/缺卡结果按其语义总结；未知枚举保留原值，不能自行归为异常。
+- 实际流水依据 `check_in_record`、`check_out_record`；时间仅在真实字段存在且与问题有关时展示，并按字段定义转换时区，不用排班时间冒充实际打卡时间。
+- `records: []` 表示未返回班次打卡明细，字段缺失表示未返回；不能单凭空记录、缺字段或空响应判定未打卡或旷工。
+
+例如 `shift_id="0"` 且上下班结果 Normal，应答“休息日，有正常打卡记录”；`shift_id="-1"` 且 records 为空，应答“未排班，未返回打卡明细”，不能答“旷工”。
+
+## 回答与部分失败
+
+按“实际查询范围 + 人员、日期、排班状态、上下班结果”给出简明总结。多人员结果必须对应姓名及可用工号/标识；结果只基于实际查询返回。用户明确要原始数据或可执行命令时再提供完整内容，平常不展示命令构造和调试过程。
+
+同时读取 `data.invaild_user_ids` 和 `data.unauthorized_user_ids`：前者明确说明不合法的用户 ID，后者说明无权限查询。只对成功返回的用户下结论，不能把部分成功说成全体完成，也不能把无权限用户说成没有打卡。只有失败列表或空结果时明确说明没有获得有效结果，不能推断业务事实。
+
+JSON/pretty 保留完整对象；table/CSV/NDJSON 将完整响应作为一行输出。分析优先用 JSON 的 `data.user_task_results`，不要把旧版裁剪数组当作当前结构。
+
+## 最终检查
+
+- 根据问题及上下文选择本人或管理员入口，目标不明确时只询问缺失信息。
+- 已按 [people-attendance-common](../people-attendance-common/SKILL.md) 解析人员和日期：标识真实、来源清楚、同一请求类型一致，重名已确认，工号无权限时已检查合法人事 user_id 回退。
+- 已检查管理员查询不超过每批 50 人；超过 31 天的范围已按自然月或用户指定方式拆分，且每次请求都不超过限制。
+- 日期有效，实际范围已回显；用户 token 和权限符合当前请求。
+- 保持默认加班 `true`、离职选项 `false`，除非用户明确修改。
+- 排班与打卡状态分别解释，休息日/未排班/空记录不误判旷工。
+- 无效、无权限和无数据如实说明，不夸大查询完成情况。