一、项目概述

1.1 项目背景与核心目标

WorkBuddy/CodeBuddy桌面客户端内置「Buddy加油站」限时积分活动，用户每日可手动领取100通用积分，活动以周期形式迭代开展，本期活动截止至2026年7月22日。该活动仅桌面客户端开放领取入口，网页端无对应功能，用户每日手动操作繁琐、效率极低。

本项目核心目标为搭建一套全自动、可复用、可分享、低维护的积分领取工具，替代人工手动操作，实现每日定时自动领取积分。同时规避客户端迭代失效、C盘存储不足、程序后台卡死、消息推送失效等问题，最终产出双方案互补、带完整文档、无隐私风险的学习交流版工具包。

1.2 核心约束条件

• 平台约束：仅Windows桌面客户端支持积分领取，网页端无任何操作入口，彻底排除网页自动化方案；
• 环境约束：设备C盘存储空间已满（112/112GB），所有程序、依赖、项目文件必须部署至G盘；
• 安全约束：系统安全策略禁用Windows原生schtasks定时任务命令，无法通过常规命令行注册定时任务；
• 使用约束：工具需支持跨活动周期续领、电脑睡眠合盖不漏领、关闭客户端不影响领取，同时杜绝隐私泄露；
• 体验约束：实现后台静默运行、无弹窗卡顿，支持异常状态消息推送，降低用户运维成本。

二、项目需求与方案选型

2.1 基础需求与迭代需求

基础核心需求

实现无需人工干预的每日自动签到、读取本机合法登录令牌、精准调用官方领取接口、状态自检、定时任务自动注册与管理。

迭代衍生需求

开发过程中逐步完善功能，新增跨期自动续领、失败消息推送、睡眠唤醒补领、Python环境自动部署、静默无窗口运行、防程序卡死、一键安装分享、完整运维文档等功能，全方位优化工具实用性与易用性。

2.2 多方案筛选与最终决策

项目初期对三种自动化方案进行可行性验证，结合稳定性、维护成本、适配性完成筛选，最终采用「主副双方案互补」架构：

• 方案一（废弃）：Playwright网页自动化。因网页端无积分领取入口，方案直接作废；
• 方案二（兜底备用）：客户端UI自动化模拟点击。通过WorkBuddy内置自动化任务模拟点击领取按钮，优点是上手简单、无需逆向接口，缺点是消耗少量积分、客户端UI改版即失效、必须前台运行，仅作为接口失效兜底方案；
• 方案三（主力核心）：接口抓包重放自动化。逆向客户端真实接口，通过脚本读取本地令牌、直连服务端完成领取，具备无积分消耗、后台静默运行、抗UI改版、长期稳定的核心优势，作为日常主力方案。

三、核心技术调研与关键参数突破

项目落地前需解决两大核心阻塞问题，即登录令牌定位、真实领取接口溯源，两项关键技术突破为工具开发奠定基础。

3.1 登录令牌溯源（全程有效，无偏差）

排查方式

通过Process Monitor监控客户端进程文件访问行为，结合客户端userData配置文件排查，精准定位令牌存储路径。

核心参数

• 存储路径：%LOCALAPPDATA%\CodeBuddyExtension\Data\Public\auth\workbuddy-desktop.info
• 令牌字段：auth.accessToken（明文JWT格式，无需解密）
• 有效期：至2027年，过期后重新登录客户端即可自动刷新，无需手动配置
• 安全性：自动读取本机专属令牌，不同设备互不干扰，可安全分享无账号风险

3.2 接口逆向突破（核心纠错，项目关键转折点）

初期错误调研（重大踩坑）

项目初期通过客户端日志、远程页面猜测接口，误将一次性1500积分礼包接口claim-gift认定为每日签到接口。该接口返回「今日已领取」的假阳性结果，误导开发阶段验证判断，导致初期工具完全无法实现每日签到功能。

最终精准溯源（正确结论）

通过逆向客户端app.asar源码（DailyCheckin.tsx、authApiClient.ts文件中claimDailyCheckin方法），获取官方真实签到双接口，破解接口命名规律陷阱：

接口用途	请求方式与路径	前缀特征	核心作用
签到状态查询	GET /v2/billing/meter/checkin-activity-status	带/v2前缀	查询当日是否已签到、连续签到天数、活动状态
每日积分领取	POST /billing/meter/daily-checkin	不带/v2前缀	执行每日100积分领取核心操作

接口踩坑核心原因

每日签到功能封装于客户端app.asar本地源码中，非远程网页接口，无法通过常规抓包、日志猜测获取；且状态接口与领取接口前缀规则相反，常规命名猜测会全部返回404错误。

3.3 领取结果幂等判定标准

基于服务端返回码与字段，制定精准的状态判定逻辑，避免误判、报错：

• 领取成功：code=0 且响应体包含credit字段，credit值为到账积分；
• 当日已领：code=10001 且无credit字段，脚本自动幂等跳过，不报错；
• 令牌失效：HTTP 401/403，触发异常提醒；
• 活动结束：软状态标记，自动跳过任务，避免持续报错。

四、核心功能开发与技术实现

4.1 主力方案：接口自动化脚本开发

开发单文件核心脚本buddy_checkin.py，仅依赖Python标准库，零第三方依赖、零复杂安装，模块化实现全部核心功能，配套一键部署脚本。

4.1.1 核心功能模块

• 令牌读取模块（get_token）：自动读取本地配置文件，解析有效JWT令牌，适配本机环境；
• 签到执行模块（do_claim）：携带合法令牌请求真实签到接口，解析返回状态，处理各类异常场景；
• 状态查询模块（--status）：只读查询当日签到状态，不执行领取操作，用于用户自检；
• 定时任务模块：规避禁用的schtasks命令，直接字节级读写Windows系统任务XML文件，保留UTF-16 BOM编码，创建每日09:05自动任务；
• 防卡死请求模块（_safe_request）：解决原生urllib缺陷，实现线程级硬超时+90s全局看门狗，规避DNS抖动导致的进程挂死；
• 消息推送模块：适配Server酱SC3新版接口，伪装浏览器UA绕过Cloudflare拦截，兼容PushDeer App稳定推送通道；
• 环境部署模块（install.bat/setup_python.ps1）：自动检测Python环境，无环境则静默安装至G盘，规避C盘空间不足问题，一键注册定时任务。

4.1.2 核心优化特性

• 静默运行：替换python.exe为pythonw.exe，开启任务隐藏属性，全程无黑窗口、无弹窗；
• 睡眠唤醒：开启任务WakeToRun=true参数，电脑睡眠/休眠状态可定时唤醒补领，避免漏签；
• 跨期兼容：接口无活动期数参数，无需修改代码，自动适配后续迭代活动周期；
• 日志留存：自动生成运行日志，完整记录每次执行结果，便于问题排查；
• 隐私隔离：区分私人配置与公共模板，默认剔除隐私密钥文件，支持公开分享。

4.2 兜底方案：客户端UI自动化开发

针对接口可能失效的风险，搭建客户端原生自动化兜底方案，无需逆向接口，依托WorkBuddy内置自动化功能实现：

• 执行逻辑：客户端启动登录→点击左下角用户头像→定位「领取今日礼包」按钮→模拟点击领取→识别领取结果；
• 运行配置：每日09:10自动执行，采用轻量级模型降低积分消耗；
• 容错机制：已领自动终止、失败自动截图留存、不重复重试；
• 劣势说明：需客户端前台可见，每次运行消耗少量积分，客户端UI改版即失效，仅作兜底备用。

4.3 双方案整合优化

将两套方案整合至统一项目目录，实现主次分离、互不干扰：默认启用脚本接口方案、暂停UI自动化方案，避免重复执行消耗积分；用户可根据接口运行状态手动切换兜底方案，兼顾稳定性与容错性。

五、项目核心踩坑问题与完整修复方案

项目开发、测试、落地过程中出现多类典型问题，全部完成根源修复，形成完整容错机制，核心问题复盘如下：

5.1 接口误判假阳性问题（最核心故障）

问题现象：初期调用一次性礼包接口，返回「今日已领取」，工具判定执行成功，实际每日100积分从未到账。

问题根因：混淆一次性礼包接口与每日签到接口，仅通过文字提示判断结果，未校验核心credit积分字段。

修复方案：逆向客户端源码替换为真实签到接口，新增credit字段、today_checked_in状态双重校验，杜绝文字假阳性误判。

5.2 脚本进程卡死问题

问题现象：定时任务启动后黑窗口卡死，无执行结果、不自动退出，漏签积分。

问题根因：原生urllib.request.timeout仅限制数据传输超时，无法处理DNS解析抖动导致的进程挂起，无硬性退出机制。

修复方案：封装线程级_safe_request通用请求方法，设置分级超时（网络超时10s、全局硬超时30s），搭配90s全局看门狗，确保异常场景强制退出；全程替换所有网络请求方法。

5.3 消息推送失效问题

问题一：新旧接口不兼容：Server酱SC3新版密钥适配新域名，旧域名返回成功但实际不推送，修复为新版专属推送域名。

问题二：Cloudflare拦截：Python默认请求UA被安全防护拦截，新增浏览器伪装UA头，绕过拦截机制。

问题三：微信通道不稳定：官方微信模板消息接口即将下线、实测推送失败，替换为PushDeer App专属通道，保障推送稳定性。

5.4 定时任务部署异常问题

问题现象：系统禁用schtasks命令，无法常规创建定时任务。

修复方案：通过Python字节级直接读写Windows系统任务目录XML文件，严格保留UTF-16编码与BOM头，实现定时任务静默注册、修改、卸载，适配系统限制。

5.5 环境部署适配问题

问题现象：C盘满存无法部署Python环境，常规安装会占用系统盘。

修复方案：自定义Python自动安装脚本，默认部署至G盘，支持用户自定义路径，全程规避C盘存储占用。

六、项目交付成果与文档体系

项目最终产出双方案可用工具包+全套开发/使用/复盘文档，共计14个核心文件，打包体积约46KB，实现开箱即用、可学习、可分享、可运维。

6.1 功能交付成果

• 主力工具：Python单文件签到脚本、一键安装批处理、Python环境自动部署脚本、通知配置模板；
• 兜底工具：UI自动化任务指令、图文使用教程；
• 配套工具：离线速查HTML卡，支持打印、PDF导出，无依赖可离线查看。

6.2 文档交付体系

• 开发文档（DEVELOPMENT.md）：项目初期架构规划、技术选型、阻塞项梳理、模块设计；
• 全过程复盘文档（对话过程全记录.txt）：完整记录需求迭代、踩坑、纠错、优化全流程，标注所有错误节点与纠正方案；
• 项目阶段性总结（项目总结.txt）：记录接口纠错前的开发状态与后期二次加固优化内容；
• 使用手册（多版本README.md）：覆盖新手一键安装、命令行操作、自检方法、FAQ高频问题；
• 分享教程（每日自动领取教程.md）：面向普通用户与学习者的轻量化实操指南。

6.3 安全合规优化

• 隐私脱敏：剔除私人通知密钥、本地运行日志、私有路径配置，仅保留通用模板；
• 合规声明：新增学习交流声明，明确工具仅个人自用、禁止大规模刷分，规避平台风险；
• 安全保障：工具仅本地读取令牌、调用官方接口，无任何数据上传、窃取行为。

七、项目运行效果与适配说明

7.1 最终运行效果

工具已完成端到端真实验证，每日09:05静默自动执行，可稳定领取100通用积分，签到天数、积分到账数据真实有效；无弹窗、无卡死、无报错；异常场景可精准推送提醒；电脑睡眠状态可自动唤醒补签，关闭客户端不影响运行。

7.2 场景适配规则

• 可用场景：Windows系统、已登录WorkBuddy客户端、电脑睡眠/休眠、关闭客户端、非关机状态；
• 限制场景：电脑彻底关机无法自动签到，开机后可手动补签；电池供电默认不启动任务，可手动修改配置开启；
• 跨期适配：无需代码修改，自动适配后续所有活动周期，长期可用。

八、项目核心经验与技术沉淀

8.1 业务验证经验

绝对不能以文本提示作为业务成功判定依据，必须校验核心业务数据字段，规避平台接口假阳性返回；所有自动化工具必须完成隔天真实场景验证，单次模拟验证无法覆盖全部场景。

8.2 逆向开发经验

Electron客户端内置功能，接口不会暴露在网页抓包日志中，无法通过命名规律猜测，必须逆向app.asar源码获取真实接口；需警惕接口前缀、请求方法的非常规差异化设计。

8.3 程序稳定性经验

网络请求超时机制需分层设计，不仅要设置应用层超时，还需处理DNS解析、线程阻塞等底层异常，搭配全局看门狗机制，彻底杜绝进程卡死问题。

8.4 系统适配经验

Windows系统受限环境下，常规命令失效时，可直接操作系统配置XML文件实现功能适配；硬件存储不足时，可通过脚本自定义软件安装路径，规避系统盘限制。

8.5 项目迭代经验

项目开发需预留兜底方案，单一技术方案存在失效风险；交付产物必须配套完整文档、自检机制、异常提醒，同时做好隐私脱敏，满足复用与分享需求。

九、项目不足与后续维护方案

9.1 现有局限性

• 平台依赖性：依赖官方接口与客户端令牌机制，服务端接口大规模改版后工具会临时失效；
• 系统局限性：仅适配Windows系统，不支持Mac、Linux等系统；
• 运行前提：需要用户保持电脑登录状态，关机状态无法自动补签。

9.2 后续维护方案

• 接口更新：若接口失效，重新逆向客户端源码更新接口路径即可，核心逻辑无需改动；
• 令牌刷新：2027年令牌过期后，用户重新登录客户端即可自动刷新，无需修改工具；
• 方案切换：接口异常时，可快速启用UI自动化兜底方案，保障签到连续性；
• 持续兼容：后续活动迭代无需人工干预，工具自动跨期续领。

十、项目总结

本项目从零完成需求调研、方案筛选、逆向开发、问题修复、双方案整合、打包交付，全程解决接口误判、程序卡死、推送失效、系统限制、存储不足等多项核心问题，最终落地一套稳定、高效、零手动、可复用的积分自动领取工具。

项目最大的价值不仅是实现了自动化签到的业务需求，更沉淀了Electron客户端逆向、
Windows受限环境适配、网络请求容错、双方案冗余设计的实战经验，同时形成了完整的项目复盘体系，为同类桌面端自动化项目提供了可参考的踩坑案例与实现思路。最终交付产物兼顾实用性、稳定性、安全性与学习性，完全满足个人自用与技术学习的双重需求。

链接： https://pan.baidu.com/s/1Q-BNfgNDRTovr9hz7pV0KQ?pwd=6afw 提取码: 6afw