autotd-buaa 0.1.11

BUAA TD automation command line utility

AutoTD

需在校园网下使用

autoTD 是一个可安装的命令行工具包。安装后提供 autotd 命令，用于初始化本地配置目录、管理用户和图片、运行 TD 打卡流程、查询服务器返回的本学期锻炼次数，以及在后台进行定时检测。

PyPI 安装

要求：python >= 3.10

pip install autotd-buaa==0.1.11

本地开发

本项目采用标准 pyproject.toml 包结构：

python3 -m pip install -e .
autotd --help

构建本地 wheel/sdist：

python3 -m build

内部测试发布可使用 TestPyPI：

python3 -m twine upload --repository testpypi dist/*

初始化

所有运行数据存储在 ~/.autoTD 下。测试或临时运行时可用 AUTOTD_HOME 覆盖：

autotd init
autotd init --from ./autoTD

从 0.1.3 开始，如果已有 ~/.autoTD/config.json 仍是旧默认 127.0.0.1:8888，再次运行 autotd init 会自动迁移为当前默认 TD 服务器地址，不会覆盖用户、图片和机器配置。

目录结构：

~/.autoTD/
├── config.json
├── users.json
├── settings.json
├── state.json
├── telemetry_queue.jsonl
├── images/
└── logs/
    └── YYYY-MM-DD-daytime-log.txt

Telemetry 上报

从 0.1.7 开始，AutoTD 默认开启 telemetry，用于向维护者的 Cloudflare Worker + D1 后台上报安装、运行、停止、用户变化、TD 次数变化和后台运行跨日快照。0.1.11 默认 endpoint 为 https://autotd-telemetry.autotd-buaa.workers.dev。

会上报的数据包括：明文学号、每个学号最近一次 TD 次数、当前用户数量、安装实例 ID、AutoTD 版本、平台、事件类型和事件时间。

不会上报的数据包括：card_id、图片、图片文件名、入口/出口机器编号、TD 服务器地址、日志内容。

用户可以随时关闭：

autotd telemetry disable

重新开启或配置 Cloudflare Worker endpoint：

autotd telemetry enable --endpoint https://autotd-telemetry.autotd-buaa.workers.dev
autotd telemetry status
autotd telemetry sync

如果 endpoint 尚未配置，事件会保存在 ~/.autoTD/telemetry_queue.jsonl，不会影响打卡流程；配置 endpoint 后可用 autotd telemetry sync 发送。

维护者侧 Worker/D1 实现在 telemetry-worker/，Cloudflare Pages 管理前端实现在 telemetry-pages/。当前 Pages 地址为 https://autotd-telemetry-dashboard.pages.dev/，Admin Token 保存在仓库外的 /Users/denerate/ELSE/autotd-telemetry-admin-token.txt。

用户管理

autotd user add 22375080 --entrance 2 --exit 6 --entrance-image image3.jpg --exit-image image2.jpg
autotd user add 22375080 --quick 沙河
autotd user add 22375080 --quick 学院路
autotd user list
autotd user show 22375080
autotd user update 22375080 --card-id CARDID --entrance 3 --exit 7 --entrance-image image1.jpg --exit-image image2.jpg
autotd user delete 22375080
autotd user count 22375080
autotd user count 22375080 --refresh

card_id 为空时会自动使用学号的 16 进制大写形式。

autotd user count <student_id> 默认读取 ~/.autoTD/state.json 中最近一次缓存的锻炼次数，不访问服务器。需要发送真实 checkdata 请求并刷新缓存时，使用 --refresh；该刷新请求需要服务器在当前时间返回包含“本学期锻炼次数”的消息。

如果本地缓存显示某个用户本学期 TD 次数已经达到 32 次，autotd run 和 autotd run --once 会跳过该用户，不再继续入口/出口打卡。跳过时仍会发送 telemetry 快照，用于更新 Cloudflare 中的今日活跃用户和最新 TD 次数；因为没有发生新的出口打卡，不会计入今日新增 TD 打卡数。

使用 --quick 时，只需要指定校区：

• --quick 沙河: 随机选择沙河入口机 8/9/10、沙河出口机 11/12/13，并从 ~/.autoTD/images/ 随机选择入口/出口图片。
• --quick 学院路: 随机选择学院路/本部入口机 2/3/4、学院路/本部出口机 5/6/7，并从 ~/.autoTD/images/ 随机选择入口/出口图片。
• 其他字段使用默认值：rounds=3、wait_time_min=180、wait_time_max=240、card_id 自动生成。

图片管理

autotd image add ./image3.jpg
autotd image add ./photo.jpg --name entrance.jpg
autotd image add ./photo.jpg --name entrance.jpg --overwrite
autotd image list

图片会复制到 ~/.autoTD/images/。用户配置中引用的是图片文件名。

立即运行

立即执行一次所有用户：

autotd run --once

autotd run --once 会在当前终端前台执行并打印汇总。执行时某个用户失败会记录日志并继续后续用户。

定时运行

autotd run 会启动后台定时检测进程，终端会立即返回，不持续展示运行日志。日志写入 ~/.autoTD/logs/。

autotd schedule show
autotd schedule set --poll-seconds 60 --windows "07:30-10:00,11:30-14:00,15:30-20:00"
autotd run
autotd status
autotd --stop

autotd run 会启动后台轮询。查看后台进程和今日用户打卡状态用 autotd status，运行中会显示 PID、每位用户的今日进度、等待倒计时或错误信息；如果 pid 文件已过期，会提示并自动清理。需要停止后台定时检测时运行 autotd --stop。

默认时间段为：

• 07:30 - 10:00
• 11:30 - 14:00
• 15:30 - 20:00

定时模式按北京时间判断窗口。后台进程每次轮询都会重新读取用户配置：新增用户会加入当天队列，删除用户会取消待执行状态。每位用户独立记录今日轮次和下一次打卡时间，入口成功后等待再出口，出口成功后如有下一轮也会等待再入口。若倒计时到期时已不在合法窗口，本轮作废，下个窗口从入口重新开始。请求失败会进入 error 状态，可用 autotd status 查看；重新运行 autotd run 会清除今日错误状态并允许重试。

连接失败排查

如果日志中出现 Connection refused 或 无法连接 TD 服务器，先检查：

cat ~/.autoTD/config.json

server.ip 应为可访问的 TD 服务器地址，例如默认模板中的 10.212.28.38，端口为 8888。如果现有配置仍是 127.0.0.1，请编辑 ~/.autoTD/config.json，或重新导入已有项目配置：

autotd init --from /path/to/autoTD

同时确认当前网络可访问校园网或已连接 VPN。

测试

/opt/homebrew/anaconda3/envs/autotd/bin/python -m unittest discover -s tests -v