- name
- dingtalk-attendance
- description
- 查询和分析钉钉考勤打卡数据。当用户提到打卡、考勤、迟到、早退、旷工、出勤率、谁没打卡、上班情况、DingTalk attendance 等关键词时触发此 skill。即使用户没有明确说"打卡"，只要涉及员工到岗、缺勤、工时相关的问题，也应该使用这个 skill。
钉钉考勤打卡查询与分析
这个 skill 用于通过钉钉开放平台 API 查询员工的打卡记录，并对结果进行智能分析和汇总。
前置条件
运行脚本前，检查以下三个环境变量是否已设置：
echo $DINGTALK_APPKEY
echo $DINGTALK_APPSECRET
echo $ADMIN_PHONE如果任何一个为空，告知用户需要先配置：
查询钉钉打卡数据需要以下环境变量，请先设置： -DINGTALK_APPKEY— 钉钉企业内部应用的 AppKey -DINGTALK_APPSECRET— 钉钉企业内部应用的 AppSecret -ADMIN_PHONE— 管理员手机号（用于获取操作人 userId） 你可以通过export DINGTALK_APPKEY=xxx设置，或者加到.env/ shell 配置文件中。
确认三个变量都有值后再继续。
时间范围解析
用户会用自然语言描述时间范围。你需要将其转换为脚本要求的格式：YYYY-MM-DD HH:MM:SS。
规则：
- 今天的日期可以通过
date命令获取 - 开始时间的时分秒部分用
00:00:00 - 结束时间的时分秒部分用
23:59:59 - 如果用户只说了一天（如"昨天"、"3月5号"），开始和结束就是同一天
- "上周"指上周一到上周日
- "上个月"指上月1号到上月最后一天
- "这周"指本周一到今天
- "本月"指本月1号到今天
示例：
- "昨天" →
--start-time "2026-03-07 00:00:00" --end-time "2026-03-07 23:59:59" - "3月3号到5号" →
--start-time "2026-03-03 00:00:00" --end-time "2026-03-05 23:59:59" - "上周" →
--start-time "2026-02-23 00:00:00" --end-time "2026-03-01 23:59:59"
执行查询
脚本路径：scripts/attendance_query.py，位于本 skill 所在项目的根目录下。
先确定项目根目录（包含 pyproject.toml 和 scripts/ 目录的那个），然后运行：
cd <项目根目录>
uv run python scripts/attendance_query.py --start-time "YYYY-MM-DD HH:MM:SS" --end-time "YYYY-MM-DD HH:MM:SS"如果不确定项目根目录在哪，可以用 find ~ -name "attendance_query.py" -path "*/scripts/*" 2>/dev/null | head -3 来定位。
脚本会输出打卡异常的员工信息，格式如：
张三 打卡结果 迟到 出现 2 次
李四 打卡结果 旷工 出现 1 次如果没有输出，说明该时间段内所有人打卡正常。
每次 API 查询的结果会自动保存到本地 SQLite 数据库，后续可以直接从本地读取。
使用历史记录（避免重复 API 调用）
脚本支持从本地数据库读取之前查询过的打卡记录，这样做对比分析时不需要重新调用钉钉 API。
查看已有历史数据
uv run python scripts/attendance_query.py --list-history输出示例：
日期 异常次数 最后查询时间
--------------------------------------------------
2026-03-03 40 2026-03-08 15:00:00
2026-03-06 36 2026-03-08 15:05:00从历史记录读取
uv run python scripts/attendance_query.py --history --start-time "YYYY-MM-DD 00:00:00" --end-time "YYYY-MM-DD 23:59:59"如果请求范围内有部分日期没有历史数据，脚本会输出警告（可能是从未查询过，也可能是当日全员正常）。
查询策略
当用户要求查看或对比打卡数据时，按以下优先级选择查询方式：
- 先查历史：用
--list-history看看本地有哪些日期的数据 - 本地有的用本地：如果目标日期在历史记录中，用
--history从本地读取 - 本地没有的调 API：如果目标日期不在历史记录中，不加
--history正常查询（会自动保存） - 跨查询对比：对比两个时间段时，分别获取数据（能从本地读的从本地读，需要 API 的走 API），然后做分析
分析与汇总
拿到脚本输出后，对结果进行有价值的分析。用户真正关心的不是原始数据的罗列，而是"谁有问题、问题有多严重、需要我做什么"。
- 概览：总异常人数。如果查询范围是多天，说明每天上下班各一次打卡，旷工2次意味着全天缺勤
- 分类统计：按异常类型（迟到、早退、旷工等）分别统计人数和次数，用表格呈现
- 严重程度分级：多天查询时，按旷工次数从高到低分组（如"全周旷工"、"多日旷工"、"偶发旷工"），帮助用户快速定位最需要关注的人
- 重点关注：标出需要特别注意的情况——比如连续多天全勤缺失、情况恶化的员工、同时存在多种异常的员工
- 可能的原因提示：大面积旷工时提醒核查是否有请假/出差/系统故障；周五异常偏多时提醒确认是否有特殊安排
- 趋势分析：如果当前对话中有之前的查询结果，将本次结果与之前的做对比，发现趋势（比如"和上周相比，迟到人数增加了 3 人"）
- 如果全部正常：简洁告知"该时间段全员打卡正常"即可，不需要展开分析
输出风格：简洁、结构化，用中文。适当使用表格让数据更直观。
跨查询分析
用户可能要求对比不同时间段的打卡情况（比如"和上周比怎么样"、"最近一个月的趋势"）。这时：
- 先用
--list-history查看本地已有哪些数据 - 已有的数据用
--history读取，没有的先通过 API 查询 - 拿到所有数据后做交叉分析
分析可以包括：
- 同一员工在不同时段的打卡变化（恢复正常/新增异常/持续异常/情况恶化）
- 异常类型的分布变化
- 整体出勤率的趋势