dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-misc/references/attendance-report.md

@@ -0,0 +1,109 @@
+# 考勤 Excel / 报表导出
+
+仅当用户明确要求“导出、Excel、表格、生成报表”时加载本 Reference。单次 JSON 查询、个人摘要、排班表和假期余额表分别走 [attendance.md](attendance.md)、[attendance-schedule.md](attendance-schedule.md)、[attendance-vacation.md](attendance-vacation.md)。
+
+已知脚本入口时直接执行，不先查 Help、产品 Schema 或原子命令。脚本内部负责数据查询、分批、分页、聚合、姓名补齐和 Excel 生成；Agent 不重复这些远程读取，也不目测聚合。
+
+性能优化只能消除重复发现、重复查询和 Agent 目测聚合，不能删减用户要求的人员、日期、字段、分页、失败项或 warning。脚本输出 partial/incomplete 时必须原样保留，不能用已有部分数据宣称完整。
+
+## 报表类型 Golden Route
+
+| 用户意图 | 脚本 | 说明 |
+|---|---|---|
+| 未指定粒度的“考勤报表”/明确月度汇总 | `attendance_report_monthly.py` | 默认；按人汇总并生成日历 Sheet |
+| 每日统计/按天汇总 | `attendance_report_daily.py` | 按人按日 |
+| 打卡明细/原始上下班明细 | `attendance_report_detail.py` | 数据源是打卡结果 + 打卡流水 |
+| 请假/补卡/出差/外出审批记录表 | `attendance_report_record.py` | 审批单粒度；必须选择一种记录类型 |
+| 签到/外勤签到报表 | `attendance_report_checkin.py` | 签到不是上下班打卡 |
+
+“请假记录”走 record；“请假时长统计/请假报表”在未要求审批单明细时走 monthly/daily，并通过列关键词选取假期字段。“导出排班表”不属于本文件。
+
+## 1. 解析范围
+
+- 人员范围必填。姓名用 `dws aisearch person --query "<姓名>" --dimension name --format json`；部门先唯一解析 deptId，再获取完整成员；用户已给 userId 时直接使用。
+- 零命中、多候选或部门分页未完成时停止，禁止默认第一项或只导出第一页成员。
+- 时间范围必填，脚本参数使用 `YYYY-MM-DD`。本周=周一到周日，本月=1 日到真实月末；自定义范围按用户原值。
+- 用户未指定报表粒度时默认 monthly，不追问；执行结果中说明“已按月度汇总生成”。人员或时间缺失时一次性询问。
+- 所有解析和脚本执行保持同一 profile；不得复用历史 userId/deptId。
+
+## 2. 选择列
+
+monthly/daily 支持 `--column-keywords`；detail/record/checkin 列固定，不传该参数。
+
+| 关注维度 | `--column-keywords` |
+|---|---|
+| 未指定 | 省略，使用脚本默认列 |
+| 加班 | `加班-审批单统计,加班总时长,考勤结果` |
+| 请假/出差/外出 | `请假,出差时长,外出时长,考勤结果` |
+| 异常/迟到早退/缺卡 | `迟到次数,迟到时长,严重迟到次数,严重迟到时长,旷工迟到次数,早退次数,早退时长,上班缺卡次数,下班缺卡次数,旷工天数,考勤结果` |
+| 其他明确字段 | 使用用户原词组成逗号列表 |
+
+字段 ID 由脚本实时调用 `attendance report columns` 建立映射，禁止硬编码。无权限字段、未匹配字段和无数据字段必须分别保留在 warning 中，不能都说成 0。
+
+## 3. 执行脚本
+
+### 月度汇总
+
+```bash
+python3 scripts/attendance_report_monthly.py \
+  --users <USER_IDS> --start <YYYY-MM-DD> --end <YYYY-MM-DD> \
+  [--column-keywords "<关键词>"] [--out <相对路径.xlsx>]
+```
+
+### 每日统计
+
+```bash
+python3 scripts/attendance_report_daily.py \
+  --users <USER_IDS> --start <YYYY-MM-DD> --end <YYYY-MM-DD> \
+  [--column-keywords "<关键词>"] [--out <相对路径.xlsx>]
+```
+
+### 打卡明细
+
+```bash
+python3 scripts/attendance_report_detail.py \
+  --users <USER_IDS> --start <YYYY-MM-DD> --end <YYYY-MM-DD> \
+  [--out <相对路径.xlsx>]
+```
+
+### 审批记录
+
+```bash
+python3 scripts/attendance_report_record.py \
+  --type <leave|trip|out|patch> \
+  --users <USER_IDS> --start <YYYY-MM-DD> --end <YYYY-MM-DD> \
+  [--out <相对路径.xlsx>]
+```
+
+映射：请假/年假/调休/病假=`leave`，出差=`trip`，外出=`out`，补卡=`patch`。用户同时要求多种记录时按类型分别生成或明确给出多个文件，禁止把一种类型冒充完整集合。
+
+### 签到报表
+
+```bash
+python3 scripts/attendance_report_checkin.py \
+  --users <USER_IDS> --start <YYYY-MM-DD> --end <YYYY-MM-DD> \
+  [--out <相对路径.xlsx>]
+```
+
+仅使用工作目录内安全相对输出路径；默认不覆盖已有文件。`--inspect` 仅在真实返回结构漂移、脚本明确提示时使用一次，不作为正常流程。
+
+## 脚本负责的边界
+
+- [attendance_report_common.py](../scripts/attendance_report_common.py) 是上述导出脚本共享的内部模块，不可单独执行。
+- monthly/daily：实时列权限、最多 20 人/请求、最多 32 天/请求，按月切片并聚合。
+- detail：打卡结果自动翻页、打卡流水按用户/月份分批，区分无流水与 NotSigned/Absenteeism。
+- record：查询考勤审批摘要、按真实实例取详情并拆行；不代替用户提交审批。
+- checkin：最多 7 天一段并分批查询，按签到时间/地点整理；不混用 check record。
+- 所有脚本：userId→姓名、原始单位保留、失败/warning 统计、xlsx 输出。
+
+Agent 不应先手动执行 `report columns/query-data`、`check result/record` 或 `approve list` 再让脚本重复查询。只有脚本报出一个明确、可复现的结构问题时，才做一次精确 leaf Schema/Help 审计。
+
+## 结果与失败
+
+- 返回脚本 stdout 中的输出路径、人员数、日期范围、记录数、使用列和 warning；不要把整个 Excel 粘贴到对话。
+- 只有文件成功写入且脚本完成数据核对后报告成功。部分用户/字段/日期失败时报告 partial，不把其余数据当成完整报表。
+- 403/权限错误：说明需要考勤管理员或相应管理范围，不重试、不切身份。
+- 无人员、无可见字段、日期非法：本地停止，零业务查询；让用户修正输入。
+- 无业务数据：可以生成空表但必须明确“查询成功、无记录”；不能转换成“所有人正常”。
+- 脚本依赖缺失：报告缺失依赖，不自动联网安装。
+- 远端超时且请求可能已完成时，先检查目标文件和脚本摘要；不要重新发起整批导出造成重复查询。

package/skills/dws/dingtalk-misc/references/attendance-schedule.md

@@ -0,0 +1,115 @@
+# 考勤排班导入与排班表导出
+
+只在以下两类任务加载本 Reference：
+
+- 写：导入排班、给员工排班、调班、换班、排休、临时安排后恢复。
+- 读：明确要求把排班导出为 Excel/排班表。
+
+只需查看排班数据或对照班次时直接使用 `attendance schedule get` / `attendance shift list`，按 [attendance.md](attendance.md) 执行，不加载本文件。
+
+## 入口选择
+
+| 意图 | 唯一推荐入口 | 说明 |
+|---|---|---|
+| 导入/修改/恢复排班 | `python3 scripts/attendance_schedule_import.py` | 脚本负责组类型、班次归属、记录格式和确认门禁；不要手拼底层 import payload |
+| 导出排班 Excel | `python3 scripts/attendance_schedule_export.py` | 脚本分批查询、补齐姓名/班次名并生成日历表 |
+| 仅查看 JSON | `dws attendance schedule get --users ... --start ... --end ... --format json` | 无需脚本和 Excel |
+| 仅看 7 天计划上下班/休息日 | `dws attendance shift list --users ... --start ... --end ... --format json` | 最多 50 人、7 天 |
+
+已知上述入口时不要先查 Help、产品 Schema 或 Shortcut 列表。只有脚本真实报 `unknown command/flag` 时查一次对应 leaf Help；参数/确认不明时只查一次精确 leaf compact Schema。
+
+`schedule get` 的 CLI 日期入参仍使用 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:mm:ss`；CLI 会把日期规范化为上游要求的 datetime 字符串。不要自行换算或传 Unix 毫秒时间戳。
+
+性能优化只能消除重复发现和重复查询，不能省略排班记录、日期、班次身份、休息状态、失败项或写后回读。需要完整范围时必须覆盖所有目标用户和日期；空记录、休息日和查询不完整必须分别表达。
+
+## 排班写入 Golden Route
+
+### 1. 解析真实目标
+
+- 人名：`dws aisearch person --query "<姓名>" --dimension name --format json`。零命中或多候选时停止。
+- 明确给出考勤组名称：`dws attendance group search --query "<名称>" --type TURN --page 1 --limit 20 --format json`，必须唯一命中。
+- 只给“我的考勤组”：可用 `dws attendance rules --date <YYYY-MM-DD> --format json` 取得当前用户 groupId；该命令不能据此推断其他员工的考勤组。
+- 部门成员：先唯一解析部门，再 `dws contact dept list-members --ids <deptId> --format json`；不要把 deptId 当 userId。
+
+所有 ID 都必须来自本轮同一 profile 的真实返回，禁止复用历史 ID。
+
+### 2. 校验考勤组与班次
+
+执行：
+
+```bash
+dws attendance group get --group-id <GROUP_ID> --format json
+```
+
+必须满足：
+
+- `groupVO.type == TURN`。FIXED/NONE 不能导入排班。
+- 目标用户属于该组；需要时用 `group filtered-get --group-id <GROUP_ID> --member` 验证。
+- 班次只能来自该组的 `shiftVOList` / `classIds`。先在组返回的班次中按名称匹配；零命中或多候选停止。
+- 只有组结果缺班次名称时，才按组内已有 classId 调 `class get` 补齐；禁止用企业全局 `class search` 随意选一个同名班次。
+
+### 3. 写前保存与预览
+
+临时修改/恢复或覆盖已有日期时，先保存原排班：
+
+```bash
+dws attendance schedule get --users <USER_IDS> --start <START> --end <END> --format json
+```
+
+构建非空 JSON 数组，每项至少包含：
+
+```json
+{"userId":"user001","workDate":"2026-08-31","classId":123456,"isRest":"N"}
+```
+
+排休使用真实约定 `isRest="Y"`，并保留脚本/当前接口要求的 classId。向用户展示完整预览：考勤组、员工姓名、日期、星期、班次名称/排休、覆盖范围。不能只显示 userId/classId。
+
+`schedule import` 是 `confirmation=user_required`。只有用户确认了这份完整预览后，才能进入执行；确认前可用脚本 `--dry-run` 做零写入校验。
+
+### 4. 执行
+
+```bash
+python3 scripts/attendance_schedule_import.py \
+  --group-id <GROUP_ID> \
+  --schedules '<JSON数组>' \
+  --confirm
+```
+
+脚本会二次校验 TURN、组内班次和记录格式，再调用当前真实 leaf（底层参数为 `--groupId/--scheduleVOS`）。Agent 不要绕过脚本改用旧的 `--group-id/--schedules` 原子命令写法。
+
+### 5. 回读、恢复与结果
+
+- 写后用相同 users/date 调 `schedule get`，逐项核对 userId、workDate、classId/isRest；只凭脚本退出码不能宣称成功。
+- 用户要求“临时修改后恢复”时，用步骤 3 保存的原排班恢复，再次回读。原来无排班与休息日必须按真实结构区分，禁止编造默认班次。
+- 修改已提交但回读失败时，不要盲目重放；先保留目标范围并再次只读对账。无法确定时报告 commit-unknown。
+- 批量中部分员工失败时逐项列出成功/失败/未知；不得把部分成功表述为全部成功。
+
+## 排班表 Excel 导出
+
+### 1. 收集范围
+
+- 员工范围必填：指定员工、部门、考勤组成员或明确 userId 列表。
+- 日期范围必填，格式 `YYYY-MM-DD`。本周=周一到周日，本月=1 日到真实月末；使用当前会话时区。
+- 人员/日期缺失时一次性询问；不追问输出文件名，缺省交给脚本生成。
+
+### 2. 执行
+
+```bash
+python3 scripts/attendance_schedule_export.py \
+  --users <USER_ID_1,USER_ID_2> \
+  --start <YYYY-MM-DD> \
+  --end <YYYY-MM-DD> \
+  [--output <相对路径.xlsx>]
+```
+
+脚本自动完成：按 20 人分批调用 `schedule get`、userId→姓名、classId→班次名称、按人×日期生成 Excel。不要在 Agent 中重复查同一批排班或手工拼表。
+
+只允许工作目录内安全相对输出路径，默认不覆盖已有文件。向用户返回脚本 stdout 的路径、人数、日期范围、记录数和 warning，不粘贴完整 Excel 内容。
+
+## 错误最短路径
+
+1. 考勤组非 TURN、目标不在组内、班次不属于组：写入前停止，展示真实冲突，不换同名目标。
+2. 权限错误：提示需要考勤管理员/对应管理范围，不切 profile、不改用底层 API。
+3. `unknown flag`：只查真实失败的 leaf Help 一次；不要尝试旧 flag 组合。
+4. 脚本依赖缺失：报告缺失依赖，不自动联网安装。
+5. 空/异常返回：保留员工和日期范围，按失败或不完整处理；禁止把空结构当作“全部休息”。

package/skills/dws/dingtalk-misc/references/attendance-vacation.md

@@ -0,0 +1,129 @@
+# 考勤假期、余额与变更流水
+
+本 Reference 处理假期类型、余额、余额变更记录、假期规则修改、余额设置和假期余额 Excel。请假/加班/补卡审批表单与记录走 [attendance.md](attendance.md)；考勤统计 Excel 走 [attendance-report.md](attendance-report.md)。
+
+已知下列路由时直接执行，不先查 vacation Help、产品 Schema 或 Shortcut 列表。只有参数/确认不确定时查一次精确 leaf compact Schema；只有真实 `unknown flag` 时查一次 leaf Help。
+
+## Golden Route
+
+| 用户意图 | 唯一推荐入口 | 关键边界 |
+|---|---|---|
+| 列出可用假期规则/类型 | `dws attendance vacation types --format json` | 无业务参数；从真实返回读取 leaveCode、名称、单位、来源和适用范围 |
+| 查询某人某类当前余额 | `dws attendance vacation balance` | `--users <ids> --leave-code <code>`；当前 main 的 leave-code 必填 |
+| 查询某人某类余额变更流水 | `dws attendance vacation records` | `--user <id> --leave-code <code> --start YYYY-MM-DD --end YYYY-MM-DD`；四项均必填 |
+| 查询某时间段假期使用数据（管理员） | `dws attendance report query-leave` | `--users --leave-names --start/--end "YYYY-MM-DD HH:mm:ss"`；最多 20 人、32 天 |
+| 修改假期规则 | `dws attendance vacation update-type` | 仅目标规则当前 `leaveStatisticType=freedom`；`--leave-code` 加至少一个修改字段；user_required |
+| 设置员工假期余额 | `dws attendance vacation save-balance` | SET 替换，不是 ADD；user_required |
+| 导出多员工/多假期余额 Excel | `python3 scripts/attendance_vacation_balance.py` | 脚本逐个真实 leaveCode 查询并横向汇总 |
+
+## 只读查询
+
+### 1. 解析人和假期规则
+
+- 姓名先用 `dws aisearch person --query "<姓名>" --dimension name --format json`；零命中、多候选停止。
+- 先调用 `vacation types`，按假期名称唯一匹配 leaveCode。不要猜 UUID，不跨 profile 复用历史 code。
+- 用户要求年假和调休等多个类型时，对每个匹配 leaveCode 分别查询；不能省略 leave-code 后声称查询了全部。
+- `corpId` / `opUserId` 由当前登录上下文注入，不向用户索要。
+
+### 2. 当前余额
+
+```bash
+dws attendance vacation balance \
+  --users <USER_ID_1,USER_ID_2> \
+  --leave-code <LEAVE_CODE> \
+  --format json
+```
+
+返回时同时展示假期名称、leaveCode 对应单位和真实余额。`visible=false` 表示该员工不适用该规则，不等于余额 0；“假期类型没有余额”按“不限制余额”处理；权限错误不做同义重试。
+
+### 3. 变更流水
+
+```bash
+dws attendance vacation records \
+  --user <USER_ID> --leave-code <LEAVE_CODE> \
+  --start <YYYY-MM-DD> --end <YYYY-MM-DD> \
+  --format json
+```
+
+按服务端真实时间、变更数量、原因和有效期展示；不要把空数组描述成“没有发放过”，只能说“该查询范围返回 0 条记录”。用户要求“今年”时使用当年 1 月 1 日到当前日期；不得查询未来日期补齐全年。
+
+## 修改假期规则
+
+`vacation update-type` 为 `confirmation=user_required`。流程：
+
+1. `vacation types` 唯一定位规则并保存完整当前值。
+2. 检查目标规则的精确 `leaveStatisticType`。只有值严格等于 `freedom` 时才能继续；其他值立即报告后端不支持，不调用写接口、不改写枚举、不查 Help、不重试。能力缺陷允许正确阻塞，不为追求 case 成功而绕过。
+3. 仅组装用户要求的变更字段；展示名称/code、`当前值 → 新值`、适用范围影响。
+4. 用户确认后执行；写后再次 `vacation types`，按同一 leaveCode 核对。
+
+可用修改字段：`--name`、`--unit day|halfDay|hour`、`--paid`、`--per-hours`、`--when-can-leave entry|formal`、`--visibility-rules '<JSON数组>'`。至少传一项。
+
+可见范围约定：
+
+- 不传 `--visibility-rules`：不修改。
+- 指定范围：`[{"type":"staff|dept|label|employee_type","visible":["id1"]}]`。
+- 全公司：必须显式使用哨兵 `[{"type":"dept","visible":["-1"]}]`。
+- `[]`、`[{}]` 或空 visible 无效，禁止用来表达全公司或清空。
+
+临时修改单位/一天折算时长后恢复时，确认计划必须同时覆盖修改和恢复；修改后回读，再用步骤 1 保存值恢复并回读。恢复失败报告 partial，不得宣称完成。
+
+## 设置假期余额
+
+`vacation save-balance` 是 SET：传入新总余额会替换当前余额。即使用户说“增加 3 天”，也必须先读取当前值再计算新总值。
+
+1. 用 `vacation balance --users <单个目标> --leave-code <code>` 查询当前值和单位。
+2. 计算并展示：目标员工、假期、当前余额、新总余额、差额、原因、可选有效期。
+3. 获得明确确认后执行：
+
+```bash
+dws attendance vacation save-balance \
+  --target <USER_ID> --leave-code <LEAVE_CODE> \
+  --num <NEW_TOTAL> --reason "<REASON>" \
+  [--start <YYYY-MM-DD> --end <YYYY-MM-DD>] \
+  --format json
+```
+
+4. 再次调用 `vacation balance` 验证新总值。CLI 会把实际单位数量乘以 100 发送（例如 8→800），Agent 传用户可读的 8，不自行乘 100。
+
+可能提交后超时不得盲目重试，先读余额对账。批量调整需逐员工保留成功/失败/未知账本；不要把一人成功扩展成全部成功。
+
+## 假期余额 Excel
+
+### 1. 解析范围
+
+- 人员范围必填：指定员工、部门/多部门或明确 userId 列表。完整解析并去重，禁止只取部门第一页。
+- 用户未指定假期类型时导出全部可见规则，不传 `--leave-keywords`；指定类型时传名称关键词，脚本实时映射 leaveCode。
+
+### 2. 执行
+
+```bash
+python3 scripts/attendance_vacation_balance.py \
+  --users <USER_ID_1,USER_ID_2> \
+  [--leave-keywords "年假,病假,调休"] \
+  [--out <相对路径.xlsx>]
+```
+
+`--leave-keywords` 是脚本参数，不是 `dws attendance vacation balance` 参数。脚本自动执行：
+
+- `vacation types` 建立名称、leaveCode、单位、source 和列顺序。
+- 对每个匹配规则逐个调用 `vacation balance --leave-code`。
+- userId→姓名/部门/入职信息。
+- 每名员工一行，假期规则横向展开并在表头保留单位。
+
+特殊值必须保真：
+
+- 服务端表示无余额上限 → `不限制余额`。
+- `visible=false` 或员工缺少规则依赖的入职/首次工作时间 → `不适用`。
+- `source=external` 且非权限类余额错误 → `外部规则暂无余额，需通过接口初始化更新余额`。
+- 真实无返回且无上述证据 → `未设置`，不得填 0。
+
+返回脚本 stdout 中的路径、员工数、规则列数、筛选关键词和 warning，不粘贴完整 Excel。只允许工作目录内安全相对路径，默认不覆盖。
+
+## 错误最短路径
+
+1. 假期名称零命中/多候选：停止，展示候选；禁止按列表首项继续。
+2. 权限不足：说明目标员工不在管理范围或需要管理员权限，不切换组织/身份。
+3. leaveCode 为空或过期：重新调用一次 `vacation types`；仍不存在则停止，不猜 code。
+4. 写请求可能已提交：先按同一 user/code 回读对账；禁止自动重放。
+5. Excel 脚本依赖缺失：报告缺失依赖，不自动联网安装。
+6. 返回结构漂移：脚本明确提示后才用一次 `--inspect`；不要先加载产品 Schema。

package/skills/dws/dingtalk-misc/references/attendance.md

@@ -0,0 +1,149 @@
+# 考勤查询、规则与设置
+
+本 Reference 处理打卡流水/结果、个人详情、签到、审批记录与入口、班次定义、考勤组、考勤规则、个人/全局设置和管理员修正。
+
+以下场景不要先读本文件：
+
+- 排班导入、调班、排休、排班表 Excel → [attendance-schedule.md](attendance-schedule.md)
+- 考勤/月度/每日/明细/审批记录/签到 Excel → [attendance-report.md](attendance-report.md)
+- 假期类型、余额、变更流水、假期规则或余额导出 → [attendance-vacation.md](attendance-vacation.md)
+
+## 最小执行契约
+
+- 已知路由和参数足够时直接执行，结构化结果统一加 `--format json`。不要先查产品级 Schema、Shortcut 列表或 Help。
+- 只有参数/约束/确认语义不确定时查一次精确 leaf Schema；只有真实出现 `unknown command` / `unknown flag` 时查一次精确 leaf Help。禁止连续试探同义命令。
+- 姓名先用 `dws aisearch person --query "<姓名>" --dimension name --format json` 解析；零命中、多候选或跨 profile 时停止，禁止选择第一项。后续只复用本轮真实返回的 userId/groupId/classId/ruleId/leaveCode。
+- profile、组织和操作者身份从目标解析到最终读取/写入必须保持一致。宿主或 CLI 自动注入的 `corpId` / `opUserId` 不向用户索要；精确 leaf 明确要求的操作者字段除外。
+- 写操作是否确认以 Runtime/精确 Schema 的 `confirmation` 为准。`user_required` 时先读当前值、展示目标和差异、获得确认，再执行并回读；存储示例不预填 `--yes`。
+- 退出码 0 或传输成功不等于业务成功；检查真实业务结果、稳定 ID、分页完整性和失败项。可能已提交的写请求不得盲目重试。
+- 性能优化只减少重复发现和重复请求，不删减用户要求的记录、字段、分页、失败项或验证。窄投影必须保留稳定 ID、请求所需业务字段、业务状态和完整性元数据；最终回答必须自包含，不用“以上/如上”代替结果。
+
+## Golden Route
+
+### 记录、结果与统计
+
+| 用户意图 | 推荐入口 | 关键参数/边界 |
+|---|---|---|
+| 某人某天个人考勤详情 | `dws attendance record get` | `--user <userId> --date YYYY-MM-DD`；返回详情，不替代跨日统计 |
+| 原始打卡流水：实际时间、地点、定位方式 | `dws attendance +check-record` | `--users <ids> --start YYYY-MM-DD --end YYYY-MM-DD`；区间不超过 1 个月 |
+| 打卡判定：Normal/Late/Early/NotSigned/Absenteeism | `dws attendance +check-result` | 同上；最多 100 人；`--limit 1..1000 --offset >=0` |
+| 周/月摘要 | `dws attendance summary` | `--user <id> --date <日期> --stats-type week\|month` |
+| 当天适用考勤组、范围与规则 | `dws attendance rules` | `--date YYYY-MM-DD` 或 `YYYY-MM-DD HH:mm:ss` |
+| 未来 7 天内计划班次 | `dws attendance shift list` | `--users <ids> --start YYYY-MM-DD --end YYYY-MM-DD`；最多 50 人、最多 7 天 |
+| 已导入的排班记录 | `dws attendance schedule get` | `--users <ids> --start <日期> --end <日期>`；只查看/对照时直接用，不强制导出 Excel |
+| 签到/外勤签到记录 | `dws attendance checkin records` | `--operator-corp-id`、`--operator-staff-id`、`--staff-ids`、`--start/--end "YYYY-MM-DD HH:mm:ss"`；最多 100 人、最多 7 天 |
+
+`签到` 是外勤签到，走 `checkin records`；`打卡流水` 走 `+check-record`；`打卡结果/迟到/缺卡/旷工` 走 `+check-result`。三者不能互换。
+
+分页规则：
+
+- 用户明确要“前 50 条再下一页”时，先 `+check-result --limit 50 --offset 0`，再使用返回 continuation/下一 offset；不要重复第一页。
+- “全部/完整”需要继续到 `meta.pagination.endpoint_exhausted=true`；达到边界但未耗尽时返回 next token，不得宣称完整。
+- 无流水只是“无打卡数据”，不等于正常，也不等于缺卡。缺卡/旷工以 `+check-result` 的判定为准；完全无记录单独列出。
+
+### 考勤审批
+
+| 用户意图 | 推荐入口 | 关键参数/边界 |
+|---|---|---|
+| 查已提交的请假/加班/出差外出/补卡记录 | `dws attendance +list-approve` | `--users <ids> --types overtime,trip,leave,patch --start YYYY-MM-DD --end YYYY-MM-DD` |
+| 获取可提交表单入口 | `dws attendance +get-approve-template` | `--type leave\|overtime\|repair-check\|travel\|out`；只返回入口，不代填提交 |
+
+查询接口把出差和外出合并为 `trip`；表单入口必须区分外出 `travel` 与出差 `out`。多个模板全部返回，将名称最匹配者置前，并用 `[表单名称](submitUrl)` 展示，禁止裸露 URL 或只返回一个模板。
+
+### 补卡规则、加班规则与班次定义
+
+| 用户意图 | 推荐入口 | 关键参数/边界 |
+|---|---|---|
+| 补卡规则候选 ID/名称 | `dws attendance +search-adjustment-rule` | `--query <名称> --page <n> --limit <=200`；投影只保证 ID/名称 |
+| 补卡规则完整列表字段 | `dws attendance adjustment search` | 同样使用 `--query/--page/--limit`；需要有效期、次数、适用范围时用此原子入口 |
+| 已知补卡规则 ID 取详情 | `dws attendance adjustment get --adjustment-id <id>` | 当前下游可能返回空详情；空 result 必须报告 unavailable，不把搜索摘要冒充详情 |
+| 加班规则候选 ID/名称 | `dws attendance +search-overtime-rule` | `--query <名称> --page <n> --limit <=200` |
+| 加班规则完整列表字段 | `dws attendance overtime search` | 比较工作日/休息日/节假日计算方式时使用 |
+| 已知加班规则 ID 取完整详情 | `dws attendance +get-overtime-rule --overtime-id <id>` | 响应 ID 必须匹配请求 ID |
+| 班次候选 ID/名称 | `dws attendance +search-class` | `--query <名称> --filter-type ALL\|MINE_OWN --page <n> --limit <=200`；窄投影 |
+| 班次完整配置列表 | `dws attendance class search` | 需要上下班、休息段或完整配置时使用；分页参数仍是 `--page/--limit` |
+| 已知班次 ID 精确详情 | `dws attendance class get --class-id <id>` | 仅对当轮真实 ID 使用 |
+
+按名称搜索时，严格使用 `--query`，不要猜 `--name` 或 `--page-size`。用户指定“前两页”时只读 page 1 和 page 2；若需唯一目标，零命中停止，多候选先消歧。
+
+### 考勤组与设置
+
+| 用户意图 | 推荐入口 | 关键参数/边界 |
+|---|---|---|
+| 搜索考勤组 | `dws attendance group search` | `--query`、`--type FIXED\|TURN\|NONE`、`--page/--limit`；按需 `--query-position/--query-ble` |
+| 考勤组完整配置 | `dws attendance group get --group-id <id>` | 完整配置、负责人、班次与范围 |
+| 只取成员/地址/Wifi/蓝牙 | `dws attendance group filtered-get` | `--group-id` 加 `--member/--position/--wifi/--bles`；避免全量读取 |
+| 当前登录用户本人的个人提醒/极速打卡/通知设置 | `dws attendance selfsetting get` | `--user <本人 userId> --setting-scene <scene>`；不支持查询其他员工，管理员也不能代查 |
+| 企业全局设置（管理员） | `dws attendance globalsetting get` | `--scope 企业\|全公司\|所有人 --setting-scene <scene>` |
+| 简单报表字段查询（非 Excel） | `dws attendance report columns` → `report query-data` | 先取有权字段 ID；`query-data` 最多 20 人、32 天 |
+| 简单假期报表查询（非 Excel） | `dws attendance report query-leave` | `--users --leave-names --start/--end "YYYY-MM-DD HH:mm:ss"` |
+
+`setting-scene` 只取：`checkRemind`、`fastCheck`、`checkResultNotify`、`lackRemind`、`personalAttendStatNotify`、`bossAttendStatNotify`。只查询用户指定的 scene，不默认把六类全部读取。
+
+`selfsetting get/save` 仅支持当前登录用户本人，`--user` 必须是本人 userId。目标为其他员工时立即报告能力不支持；禁止调用 selfsetting，禁止改查当前用户，禁止用 globalsetting 冒充替代，也不要 Help 或重复尝试。能力缺陷允许正确阻塞，不为追求成功率绕过服务端边界。
+
+## 写操作最短路径
+
+下列命令均为 `confirmation=user_required`：
+
+| 操作 | 命令 | 写前/写后要求 |
+|---|---|---|
+| 创建班次 | `attendance class create --name --class-vo` | `class-vo.sections[].times` 明确上下班；先按同名 search 防重复，写后按返回 ID/唯一名称回读 |
+| 更新班次 | `attendance class update --class-id [--name/--owner/--class-vo]` | 先 `class get` 保存完整原值；只改目标字段；写后回读 |
+| 创建考勤组 | `attendance group create --name --type [--owner/--group-vo]` | 同名 search 防重复；FIXED 的 `group-vo` 必须含 `defaultClassId` 和 7 天 `workDayClassList` |
+| 更新考勤组 | `attendance group update --group-id [--name/--type/--owner/--enable-outside-check/--classIds/--group-vo]` | 先 `group get` 保存原值；复杂对象以当前配置为基线，禁止凭空全量覆盖 |
+| 更新成员 | `attendance group update-members --group-id` 加至少一个增删 flag | 每类最多 20 个 ID；写前 `filtered-get --member`，写后回查目标差异 |
+| 更新本人个人设置 | `attendance selfsetting save --user <本人 userId> --setting-scene <scene> <scene字段>` | 仅当前登录用户本人；先同 scene `get`；禁止把不同 scene 字段混用 |
+| 更新全局设置 | `attendance globalsetting save --scope --setting-scene <scene> <scene字段>` | 仅管理员；先同 scope/scene `get`，写后回读 |
+| 管理员修正打卡 | `attendance boss-check --plan-id <id>` 或 `--result-id <id>` | 两种 ID 至少一个；先定位唯一记录并展示 `当前值 → 新值`，写后重新查询结果 |
+
+临时修改并恢复时：写前保存完整原配置和稳定 ID；一次性展示“修改 + 验证 + 恢复”计划并获得明确确认；修改后回读，再用保存值恢复并再次回读。中途验证失败也要尝试恢复；恢复失败必须报告 partial/commit-unknown，不能宣称任务完成。
+
+复杂 payload、枚举和罕见字段只在精确 leaf Schema 中读取，禁止为已知简单 flag 加载产品级 Schema。班次/考勤组复杂 JSON 必须基于写前真实对象做最小变更。
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcuts（无专用脚本/recipe 时优先）
+
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "attendance +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws attendance <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service attendance --format json` 批量发现。
+
+| Shortcut | 风险 | 适用场景 |
+|---|---|---|
+| `dws attendance +check-record` | read | 查询用户打卡流水（打卡时间/地点/定位方式） |
+| `dws attendance +check-result` | read | 查询用户打卡结果（迟到/早退/缺卡等） |
+| `dws attendance +get-approve-template` | read | 查询补卡/请假/加班/外出/出差审批提交链接 |
+| `dws attendance +get-overtime-rule` | read | 根据加班规则主键 ID 查询加班规则详情 |
+| `dws attendance +list-approve` | read | 查询用户考勤审批单（补卡/加班/请假/出差外出） |
+| `dws attendance +search-adjustment-rule` | read | 查询当前用户可管理的补卡规则列表 |
+| `dws attendance +search-class` | read | 查询当前用户可管理的班次详情列表 |
+| `dws attendance +search-overtime-rule` | read | 查询当前用户可管理的加班规则列表 |
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## 复用脚本
+
+- [attendance_my_record.py](../scripts/attendance_my_record.py)：自动解析当前用户，查询今天或指定日期的本人考勤记录；适合“查我今天考勤”这类单人快捷查询。
+- [attendance_team_shift.py](../scripts/attendance_team_shift.py)：按明确的 userId 列表查询团队日期范围内的排班；默认本周一至周五，最多 50 人。
+
+脚本已覆盖身份解析、日期默认值或批量边界时直接运行；不要先手写同一批查询再让脚本重复调用。
+
+## 日期、结果与聚合
+
+- 本周=周一到周日；本月=1 日到真实月末；用户给定范围时原样使用。按当前会话时区计算，禁止硬编码。
+- `check/approve/shift/schedule/vacation records` 使用 `YYYY-MM-DD`；`checkin/report` 使用 `YYYY-MM-DD HH:mm:ss`。不要混用。
+- 超过 3 条记录的求和、分组、计数、排序或跨字段核对使用本地脚本处理，保留原始单位；不要靠目测。仅当用户要求 Excel 时切换专项报表脚本。
+- 返回中没有某人/某日时标记“无记录”；`NotSigned`、`Absenteeism` 分别按真实结果展示；不把缺失数据补成 0 或 Normal。
+- 对“最近一个有记录的日期”，从实际返回的日期字段取最大值，再把这个日期传给后续 `rules`/`record get`/`shift list`；禁止用今天或区间结束日代替。
+
+## 错误最短路径
+
+1. 零命中、多候选、目标类型不明：停止后续写入，展示候选或要求用户明确；禁止默认第一项。
+2. `unknown flag`：只查该 leaf Help 并修正一次；`unknown command`：只查一次精确父级/Shortcut 清单，禁止猜后缀。
+3. 参数或确认不清楚：只查一次精确 leaf compact Schema，字段投影限制为 `parameters,constraints,confirmation`；禁止产品级或 `--all`。
+4. 权限错误：说明需要的管理员/管理范围，不切 profile、不改目标、不用底层接口绕过。
+5. 只读后端依赖错误可保持原参数重试一次；写操作在无法证明未开始时先回读对账，禁止自动重放。
+6. 返回 `null`、缺稳定 ID、响应 ID 不匹配或分页停滞：按真实失败/不完整处理，不包装成空成功。
+
+## 跨产品边界
+
+- 考勤类请假/加班/补卡/出差外出记录和提交入口属于 attendance；通用 OA 审批实例状态、同意/拒绝/转交属于 `dingtalk-misc` 的 OA Reference。
+- 人名解析优先 `dingtalk-aisearch`；已知 userId 的批量姓名/部门补齐用 `dingtalk-contact`。
+- 普通活动签到、日历会议、持续事件监听不属于 attendance；分别路由日历/事件产品。

package/skills/dws/dingtalk-misc/references/dev/app.md

@@ -0,0 +1,42 @@
+# 应用基础操作
+
+> 操作的是「应用」容器本体（见 [devapp.md](../devapp.md) 概念地图）；启停/删除改的是应用 appStatus，不是版本 versionStatus。
+
+应用列表查询、详情、创建、修改、生命周期启停和删除。参数用对应命令的 `--help` 查询。
+
+## 应用定位
+
+写操作与多数单应用命令统一用 `--unified-app-id`（全树主键）定位。`dev app get` 额外支持只读按 `--app-key`（=clientId）查详情；`--name` 仍只在 `dev app list` 作列表过滤。拿到 appKey 时可先 `app get --app-key` 核验并拿回 `unifiedAppId`；写操作必须由用户或上游结果提供明确 `unifiedAppId`。
+
+## 应用状态 appStatus
+
+`app get` 的 `appStatus` 是字符串，取值如 `normal`、`published`。`app list` 不回这个字段（恒 `null`），看应用状态以 `app get` 为准。应用状态 `appStatus` 和版本状态 `versionStatus` 是两套，别混。遇到没见过的 `appStatus` 值原样展示。
+
+`app create`、`app update` 不返回状态字段；版本状态由 `version create` 返回的 `status`（值如 INIT）表达，见 version.md。
+
+## 要点
+
+- `get` 主要用于定位核验；若返回里带 `appSecret`，脱敏处理，不复制到回答；主动读凭证走 `credentials get`。
+- `disable/enable` 成功返回 `{disabled:true}` / `{enabled:true}` + `message`，不回 `appStatus`；以这个布尔判操作成败。要确认最终生效态再 `get` 看 `appStatus` 字符串值。
+- `delete` 前必须展示应用摘要；删除是异步，成功后延迟从列表消失。
+
+## 错误处理
+
+| 情况 | 处理 |
+|------|------|
+| 多应用命中 | 展示候选，停止写操作 |
+| `ServiceResult.success=false` | 透传 `errorCode/errorMsg` |
+
+## 发现命令
+
+调用任何方法前先查清楚再敲：
+
+```
+# 浏览命令组下的子命令与 flag
+dws dev app --help
+
+# 查某方法的必填参数、类型、默认值
+dws dev <command-path> --help
+```
+
+按 `--help` 输出构造 flag；不要凭旧 schema 名称猜参数。