Dingtalk Attendance

查询和分析钉钉考勤打卡数据。当用户提到打卡、考勤、迟到、早退、旷工、出勤率、谁没打卡、上班情况、DingTalk attendance 等关键词时触发此 skill。即使用户没有明确说"打卡"，只要涉及员工到岗、缺勤、工时相关的问题，也应该使用这个 skill。

Security Scan

The skill's code and instructions appear to implement DingTalk attendance queries and analysis, but the skill metadata does not declare the environment variables/credentials the runtime actually requires and some runtime commands are a bit odd — this mismatch should be resolved before trusting the skill with production credentials.

Purpose & Capability

The SKILL.md and scripts/attendance_query.py clearly implement DingTalk attendance queries (calls to oapi.dingtalk.com, local SQLite cache, analysis). That purpose matches the name/description. However, the skill registry metadata declares no required environment variables or primary credential, while SKILL.md explicitly requires DINGTALK_APPKEY, DINGTALK_APPSECRET and ADMIN_PHONE. The metadata omission is an incoherence: a consumer could install this skill without being warned it needs secrets.

Instruction Scope

SKILL.md stays within the stated purpose: it instructs checking three env vars, converting natural-language time ranges to timestamps, running scripts/attendance_query.py, and using local history to avoid unnecessary API calls. It instructs using `find ~ -name "attendance_query.py" -path "*/scripts/*"` to locate the script (scans home for matching files) — this is functional but could scan a lot of the user's home. The run command shown uses `uv run python ...`, which is unusual/unexplained (likely a wrapper/alias or typo); the instructions do not declare Python package dependencies (requests) or how to set up the execution environment.

Install Mechanism

There is no install spec (instruction-only with an included script). No remote downloads or installers are present. That is lower-risk from an install perspective, but the script imports third-party modules (requests) without documenting dependency installation — the runtime may fail or require the host to install packages manually.

Credentials

The three environment variables referenced in SKILL.md (DINGTALK_APPKEY, DINGTALK_APPSECRET, ADMIN_PHONE) are appropriate and proportional to the claimed DingTalk attendance functionality — the AppKey/AppSecret are needed to obtain an access_token and ADMIN_PHONE is used to determine an operator userId. The problem is that the skill metadata does not declare these required environment variables or a primary credential, which is a mismatch that can lead to unexpected credential exposure or omission by users. Also note ADMIN_PHONE is personally identifiable (phone number) and should be treated carefully.

Persistence & Privilege

The skill is not always-included and does not request elevated platform permissions. It writes a local SQLite cache (cache.db next to the script) to store API responses and history — this is expected behavior for caching/historical reads and is scoped to the skill's directory. There is no evidence the skill modifies other skills or global agent config.

What to consider before installing

This skill appears to do what it says (query DingTalk attendance and save results locally) but the package metadata did not declare required secrets. Before installing or running: 1) Do not provide production AppKey/AppSecret until you verify the source — use a test account with least privilege. 2) Expect to set DINGTALK_APPKEY, DINGTALK_APPSECRET, and ADMIN_PHONE in your environment; ask the publisher to update the registry metadata to declare these. 3) Inspect scripts/attendance_query.py yourself (it calls official oapi.dingtalk.com endpoints and saves results to a local SQLite DB in the scripts/ directory). 4) Run the script in an isolated environment (virtualenv/container) after installing dependencies (requests), and confirm the `uv run python` command is valid in your environment (it may be a typo or require a specific runner). 5) Consider rotating credentials after testing and grant the app minimal API scope. If the publisher cannot explain the missing metadata or origin, treat the skill as untrusted.

钉钉考勤打卡查询与分析

这个 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"

如果请求范围内有部分日期没有历史数据，脚本会输出警告（可能是从未查询过，也可能是当日全员正常）。

查询策略

当用户要求查看或对比打卡数据时，按以下优先级选择查询方式：

1. 先查历史：用 --list-history 看看本地有哪些日期的数据
2. 本地有的用本地：如果目标日期在历史记录中，用 --history 从本地读取
3. 本地没有的调 API：如果目标日期不在历史记录中，不加 --history 正常查询（会自动保存）
4. 跨查询对比：对比两个时间段时，分别获取数据（能从本地读的从本地读，需要 API 的走 API），然后做分析

分析与汇总

拿到脚本输出后，对结果进行有价值的分析。用户真正关心的不是原始数据的罗列，而是"谁有问题、问题有多严重、需要我做什么"。

1. 概览：总异常人数。如果查询范围是多天，说明每天上下班各一次打卡，旷工2次意味着全天缺勤
2. 分类统计：按异常类型（迟到、早退、旷工等）分别统计人数和次数，用表格呈现
3. 严重程度分级：多天查询时，按旷工次数从高到低分组（如"全周旷工"、"多日旷工"、"偶发旷工"），帮助用户快速定位最需要关注的人
4. 重点关注：标出需要特别注意的情况——比如连续多天全勤缺失、情况恶化的员工、同时存在多种异常的员工
5. 可能的原因提示：大面积旷工时提醒核查是否有请假/出差/系统故障；周五异常偏多时提醒确认是否有特殊安排
6. 趋势分析：如果当前对话中有之前的查询结果，将本次结果与之前的做对比，发现趋势（比如"和上周相比，迟到人数增加了 3 人"）
7. 如果全部正常：简洁告知"该时间段全员打卡正常"即可，不需要展开分析

输出风格：简洁、结构化，用中文。适当使用表格让数据更直观。

跨查询分析

用户可能要求对比不同时间段的打卡情况（比如"和上周比怎么样"、"最近一个月的趋势"）。这时：

1. 先用 --list-history 查看本地已有哪些数据
2. 已有的数据用 --history 读取，没有的先通过 API 查询
3. 拿到所有数据后做交叉分析

分析可以包括：

• 同一员工在不同时段的打卡变化（恢复正常/新增异常/持续异常/情况恶化）
• 异常类型的分布变化
• 整体出勤率的趋势