WorkBuddy Auto Checkin

Overview

Create and maintain a macOS-only WorkBuddy desktop auto-checkin workflow. Prefer the internal IPC chain codebuddy:getCheckinStatus → codebuddy:claimDailyCheckin → codebuddy:getAccountUsage over DOM clicks so the workflow stays stable when the profile panel or button layout changes.

Workflow Decision Tree

• 遇到“从零搭建自动签到”时：先完成环境校验，再用 scripts/setup_checkin.py 生成工作区文件。
• 遇到“已有脚本但不稳定”时：优先将旧逻辑迁移为内部 IPC 调用，不再依赖用户菜单、头像面板或签到按钮 DOM。
• 遇到“需要定时执行”时：默认生成 launchd agent，调度时间设为每天 12:00，并让运行包装脚本默认带 --catchup。
• 遇到“需要发布/分享这套能力”时：先验证技能目录完整，再打包 zip，最后再去 SkillHub 上传。

Step 1: Validate Environment

按下面顺序确认前提条件：

1. 确认运行环境是 macOS。
2. 确认 WorkBuddy 桌面端仍安装在 /Applications/WorkBuddy.app。
3. 确认 Node 运行时可用，并且 playwright 已安装在 WorkBuddy 的托管 Node 工作区；如果未安装，先安装依赖后再继续。
4. 确认目标工作区允许生成以下目录：
   • tools/workbuddy-checkin/
   • .workbuddy/workbuddy-checkin/
5. 确认用户接受“一次性补登录专用 profile”这个前提；没有登录态时，签到逻辑本身无法成功。

Step 2: Generate Workspace Files

执行 scripts/setup_checkin.py，为当前工作区生成一套可运行文件。生成结果应至少包括：

• tools/workbuddy-checkin/checkin.cjs
• tools/workbuddy-checkin/run.sh
• tools/workbuddy-checkin/install-launchd.sh
• tools/workbuddy-checkin/README.md
• .workbuddy/workbuddy-checkin/com.<user>.workbuddy-checkin.plist
• .workbuddy/workbuddy-checkin/logs/
• .workbuddy/workbuddy-checkin/profile/

默认约定：

• run.sh 使用托管 Node 运行 checkin.cjs
• run.sh 默认附带 --catchup
• 日志输出保存到 .workbuddy/workbuddy-checkin/logs/
• 专用登录态保存到 .workbuddy/workbuddy-checkin/profile/

Step 3: Keep the Runtime Logic Stable

将签到核心逻辑固定为下面这套流程：

1. 启动可调试的 WorkBuddy 实例。
2. 连接桌面客户端调试端口。
3. 打开 Agents 页面并等待桥接对象可用。
4. 调用 codebuddy:getCheckinStatus 读取当日状态。
5. 仅在未签到时调用 codebuddy:claimDailyCheckin。
6. 再次调用 codebuddy:getCheckinStatus 与 codebuddy:getAccountUsage 验证结果。
7. 输出 JSON 结果，并保存前后截图与运行日志。

禁止回退到以下脆弱路径，除非用户明确要求做兼容性兜底：

• 点击左下角头像或用户菜单
• 依赖个人面板是否展开
• 依赖“签到”按钮文字或位置
• 依赖视觉识别签到卡片

Step 4: Bootstrap Login State

首次部署时，单独处理登录态，而不是把“登录流程”塞进主签到链路：

1. 先生成工作区文件。
2. 运行一次 tools/workbuddy-checkin/run.sh --keep-open --debug。
3. 如果脚本提示未登录，则在自动签到专用 profile 对应的 WorkBuddy 实例里手动登录一次。
4. 登录完成后重新执行一次手动签到，确认返回 claimed-now 或 already-claimed。

将“登录态失效”与“签到接口变更”分开排查，不要混在一起判断。

Step 5: Install Scheduling

需要定时执行时，优先使用 launchd，而不是 cron。操作顺序：

1. 确认 plist 已生成到 .workbuddy/workbuddy-checkin/。
2. 执行 tools/workbuddy-checkin/install-launchd.sh。
3. 确认 ~/Library/LaunchAgents/com.<user>.workbuddy-checkin.plist 已安装。
4. 用 launchctl list | grep workbuddy-checkin 检查任务是否存在。
5. 用 launchctl kickstart -k gui/$(id -u)/com.<user>.workbuddy-checkin 做一次手动触发验证。

默认调度规则：每天 12:00 执行；脚本以 --catchup 模式运行，尽量覆盖休眠或错过时间窗口后的补执行场景。

Step 6: Troubleshoot in the Right Order

优先按这个顺序排查：

1. WorkBuddy 应用路径是否变化。
2. 专用 profile 是否仍保留有效登录态。
3. IPC 通道名是否变化。
4. 最新运行 JSON、截图、launchd.log、launchd.err 是否暴露错误。

读取 references/publish_and_usage.md 获取更完整的部署、验证和发布检查项。

Step 7: Package and Publish

对外发布前，执行下面流程：

1. 校验 SKILL.md 的元数据与描述是否完整。
2. 确认 scripts/setup_checkin.py 与 scripts/checkin.cjs 已能支撑复用安装。
3. 删除示例占位文件，避免把无关资源打进包里。
4. 运行官方打包脚本生成 zip。
5. 准备 SkillHub 发布页需要的标题、描述、使用场景和封面说明。
6. 上传 zip 后，再逐项核对技能说明是否与实际行为一致。

Bundled Resources

scripts/setup_checkin.py

根据当前工作区生成签到工具目录、运行脚本、launchd 安装脚本、plist 与 README。优先复用这个脚本，不要手写散落的路径和模板。

scripts/checkin.cjs

实际执行签到的 Node 脚本。复制到工作区后再运行，不要直接在技能目录里拿它当用户产物。

references/publish_and_usage.md

包含部署注意事项、手动验证命令、launchd 管理命令与发布前检查清单。需要完整上下文时再读取。