treawork-checkin · treawork签到助手（TRAE 每日签到）

> 技术名 / slug：treawork-checkin　|　显示名：treawork签到助手

TRAE 的每日签到本质是一次带本机登录令牌的 HTTP 请求，不需要模拟点击界面（自动化代理也没有点击桌面 UI 的能力）。

难点在于：TRAE 不把登录态写入文件，令牌只存在于自身进程内存中。因此本技能的做法是——趁 TRAE 运行且已登录时，从其进程内存中提取令牌与设备 ID，再调用官方接口完成领取。

跨平台：同一份代码、同一套参数、同一份 JSON 输出，在 Windows / macOS / Linux 上行为一致；操作系统差异全部收敛在 scripts/traelib/backends/ 的后端实现中，上层逻辑完全共用。全局仅使用 Python 标准库，无任何第三方依赖。

> 面向用户的完整说明（快速开始 / 安全说明 / 常见问题）见 @README.md。
> 三平台能力矩阵、权限模型与逐条排错见 @docs/PLATFORMS.md。
> 本文件只保留元数据与执行所需的关键信息，避免内容重复维护。

关键事实（本机实测验证，TRAE SOLO CN）

• 接口域名：https://api.trae.cn
• 查询状态：POST /trae/api/v2/ug/checkin_credits/status
• 领取积分：POST /trae/api/v2/ug/checkin_credits/claim
• 请求头（极易踩坑）：
• Authorization: Cloud-IDE-JWT <token> —— 不是 Bearer，写错会返回 code:1001（未认证）
• Content-Type: application/json
• X-Device-Id: <device_id> —— 领取接口会校验设备，缺失会返回 code:9004（订单参数不正确）
• 另有可选 x-device-brand / x-device-type / x-os-version / x-app-version，缺失不影响签到
• 请求体：{"req_source": 1}
• 令牌来源：TRAE 进程内存中的 JWT（RS256，长度约 1004）；筛"未过期 + 出现次数最多"者，命中 2 次即早停。
• 设备 ID：内存中 "device_id":"..." 形态（实测为 15~16 位数字串，如 1333088161370286）；若扫不到则回退读取 TRAE 数据目录下的 machineid。

状态查询成功响应示例

{"checked_in": true, "code": 0, "credits": 150,
 "did_checked_in": true, "enable": true, "extra_credits": 50, "message": "success"}

字段含义：code:0 正常；checked_in 今日是否已签；credits 今日发放积分数；enable 活动是否开启；extra_credits 额外奖励。

三平台内存读取（统一接口，三套实现）

三平台都不需要额外权限的替代路径（容器 / CI 场景）：用 --token 或环境变量 TRAE_TOKEN 直接提供令牌，跳过内存扫描。

前置条件（硬性）

1. 平台为 Windows / macOS / Linux 之一（其他平台需显式提供 --token）。
2. TRAE 必须正在运行且已登录 —— 令牌只在进程内存中，进程未启动则无法签到。
3. Python 3.8+，无需任何第三方包。
4. macOS 与部分 Linux 发行版需要 sudo。

脚本用法

python trae_checkin.py                 # 查询状态，未签到则领取
python trae_checkin.py --check-only    # 仅查询状态（只读，不领取）
python trae_checkin.py --diagnose      # 环境自检（不联网领取）
python trae_checkin.py --selftest      # 库级自检（无需 TRAE，可离线）
python trae_checkin.py --no-notify     # 跳过桌面通知
python trae_checkin.py --backend win32 # 强制指定内存后端（调试用）
python trae_checkin.py --version

输出为 UTF-8 JSON；三平台的参数、字段与退出码完全一致：成功或已签到 0，失败 1。

action 取值：claimed 已领取 / skip_already_signed 今日已签 / check_only 只读查询 / no_token 未拿到令牌 / unsupported_platform 平台不支持且未提供令牌 / auth_error 认证失败 / claim_failed 领取失败。

搭建流程（照做即可）

1. 落位代码：脚本自带路径解析，直接在技能目录运行即可，无需复制。
   bash python <技能目录>/scripts/trae_checkin.py --diagnose
   若需要固定入口，把 scripts/ 整体（含 traelib/ 子包）复制到用户目录下并保持目录结构。
2. 自检：跑 --diagnose，确认 backend.ready=true、trae_processes.found > 0、网络可达、device_id 有值。
   macOS / Linux 若提示权限不足，加 sudo 重跑。
3. 只读验证：跑 --check-only，应返回 status: ok 且能看到 checked_in / credits。
4. 完整跑一次：不带参数运行。已签到 → skip_already_signed；未签到 → claimed（提示用户去 TRAE 界面核对积分）。
5. 开启每日自动签到：用 automation_update（mode=create）建 recurring 任务：
   - name：TRAE 签到助手 · 每日自动签到
   - rrule：FREQ=DAILY;BYHOUR=10;BYMINUTE=5
   - status：ACTIVE
   - 提示词：跑脚本并脱敏汇报（输出里的 token 已是脱敏形态）。

安全约束（务必遵守）

• 令牌只在内存中使用：不写入任何文件、不回显完整值（输出仅 eyJhbGci...ocxg(len=1004)）、不写入日志。
• 日志只记录时间、结果与积分，路径 ~/.workbuddy/logs/trae_checkin.log（可用 TRAE_STATE_DIR 覆盖），可放心外传。
• 只访问官方 api.trae.cn，不向任何第三方发送数据。
• 只读进程内存，不修改 TRAE 的登录态或数据目录。
• 不引入任何第三方运行时依赖；不注册系统级计划任务，定时执行交给宿主平台。

验证与打包

python scripts/verify.py                  # 编译 + 单测 + 库级自检 + 环境诊断，三平台同一命令
python -m unittest discover -s tests -v   # 33 个跨平台用例，不依赖 TRAE / 网络
python scripts/package_skill.py           # 打包为可上传的 zip（产出 dist/）

• 内置三平台 × Python 3.8/3.11/3.13 的 CI 矩阵配置（.github/workflows/ci.yml）。
• pyproject.toml 可打包为 wheel 并安装 trae-checkin 命令。
• scripts/package_skill.py 产出 dist/<name>-<version>.zip：SKILL.md 位于压缩包根目录，
  自动剔除缓存 / 版本控制 / 构建产物，并在打包前校验 frontmatter 必填字段、包体上限与路径合法性。

目录结构

scripts/trae_checkin.py        CLI 入口（跨平台编排层，不含任何平台分支）
scripts/verify.py              一键校验
scripts/package_skill.py       打包为可上传的 zip
scripts/traelib/
  paths.py                     三平台路径解析（零硬编码绝对路径）
  scanner.py                   令牌 / 设备 ID 提取（与平台无关）
  client.py                    官方签到接口
  notifier.py                  三平台桌面通知
  selftest.py                  库级自检
  backends/{win32,linux,darwin}.py   内存读取后端，统一接口
tests/test_trae_checkin.py     跨平台单测
docs/PLATFORMS.md              能力矩阵 / 权限模型 / 排错

排错速查