From 8ddb73223230411a9bc283cb53fb608811050ab8 Mon Sep 17 00:00:00 2001
From: Hermes Agent <Hermes@Hermes.Hermes>
Date: Wed, 20 May 2026 22:47:42 +0800
Subject: [PATCH] docs(qdreader): record cron sign success lessons

---
 docs/autman-plugin-rules.md | 77 +++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/docs/autman-plugin-rules.md b/docs/autman-plugin-rules.md
index e02ae91..678cbf8 100644
--- a/docs/autman-plugin-rules.md
+++ b/docs/autman-plugin-rules.md
@@ -653,3 +653,80 @@ QDReader 签到结果判定补充：
 - 大咖荐书应限制在北京时间 `20:00-22:00` 窗口执行；窗口外要标记为跳过并避免调用消息接口，否则晚间窗口后容易返回“参数错误”并污染整账号结果。
 - “无可领取礼包/今日已签到”属于幂等成功类提示；这类提示不应让整个账号汇总失败。
 - 每次修复这类链路必须补 VM 回归测试：请求路径、签名 payload 里的参数、特殊返回码分类、最终账号成功/失败汇总。
+
+## 14. QDReader 定时签到成功复盘：从“代码看起来对”到“现场确实跑通”
+
+本次 `2.10.x` 修复最终确认启点定时签到已成功运行，关键经验如下，后续遇到“定时任务似乎没跑/跑了但结果异常”时按这个顺序复核：
+
+### 14.1 先确认 Autman 实际能调度到插件入口
+
+- 插件必须保留简单明确的 cron 头注，例如 `//[cron: 1 7 * * *]`，避免未验证的复杂多时间表达式。
+- JS 插件顶层必须真的调用 `main()`；cron 触发时通常没有聊天内容，入口要把“空 content”解释为系统定时运行，而不是当作非法输入退出。
+- cron 分支要只做一件事：执行签到。归档应在签到结束后立即完成，不再依赖另一个午夜 cron 或拆分插件。
+- 手动 `启点签到` 与 cron 应复用同一条执行链，只区分账号范围：手动只跑当前用户账号，cron 跑全部账号。这样手动跑通才有诊断价值。
+
+### 14.2 状态判断不能只看“最近日志”
+
+- 当前实现签到结束后会把 `last_result_json` / `last_run_json` 复制到 `archive_json` 后清空近期日志；所以“最近日志为空”不代表没跑。
+- 查询逻辑必须在近期日志为空时回退读取 `archive_json`，并展示归档批次、来源、时间、成功/失败/总数、单账号结果。
+- 归档 key 和展示时间必须按北京时间生成，避免 UTC 边界导致今天的签到归到昨天。
+
+### 14.3 完全体任务要有矩阵，而不是靠猜
+
+默认安全任务：
+
+| 任务 | 默认 | 时间/条件 | 接口 |
+|---|---:|---|---|
+| 主签到 | 开 | cron / 手动 | `/argus/api/v3/checkin/checkin` |
+| 领取奖励 | 开 | 签到后固定执行 | `/argus/api/v3/checkin/receivegifts` |
+
+可选任务必须按账号保存在 `qdreader_task_pref_json`，默认关闭：
+
+| 任务 | 时间/条件 | 接口链 |
+|---|---|---|
+| 激励任务 | 账号开启后执行 | `video/adv/mainPage` → `video/adv/finishWatch` → 回查 `mainPage` |
+| 每日任务 | 账号开启后执行 | `checkin/packagelist` → `finishWatch` → 回查 |
+| 每日抽奖 | 账号开启后执行 | `checkin/detail` → `checkin/lottery` |
+| 每周兑换 | 账号开启且北京时间周日 | `checkin/checkinexchangepage` → `checkin/exchangegoods` |
+| 章节卡片 | 账号开启后执行 | `readtime/scoremall/chaptercardwithbook` |
+| 大咖荐书 | 账号开启且北京时间 20:00-22:00 | `magev6.if.qidian.com/.../pullmessage` → `getrewarddetail` → `rewardcallback/addbookshelf` |
+
+### 14.4 上游返回和签名网关要按实测分类
+
+- `今日已签到`、`重复签到`、`已领取`、`已完成`、`无可领取礼包` 等幂等提示应视为成功类，不应让账号失败。
+- 激励任务 `finishWatch` 的 `Result/result = 9` 是上游可接受状态，要继续回查完成状态，而不是直接失败。
+- 可选任务如果被签名网关返回 `url 不在允许的接口列表内`，应标记为跳过 `⏭`，不要污染基础签到成功率。
+- 大咖荐书必须用 base62 token，并带 `senderId` 拉取具体会话；单次 `pullmessage` 或十进制 token 容易导致“参数错误”。
+
+### 14.5 Autman JS 兼容性要作为上线前检查
+
+- Autman 内置 JS 运行时不一定等同当前 Node。即使 Node `--check` 通过，也要避免不必要的新语法。
+- QDReader token 计算需要 `BigInt`，但不要写 `0n` / `62n` 这类 BigInt 字面量；使用 `BigInt(0)` / `BigInt(62)`，降低旧解析器失败风险。
+- 需要同时检查并同步两份维护副本：`plugins/qdreader/qdreader_sign_autman.js` 和 `js/qdreader_sign_autman.js`。
+
+### 14.6 每次修复必须落地验证
+
+最小验证集：
+
+```bash
+cd /Users/chick/.Hermes/workspace/autman-plugins
+node --check plugins/qdreader/qdreader_sign_autman.js
+node --check js/qdreader_sign_autman.js
+node tests/qdreader_plugin.test.mjs
+git diff --check
+cmp -s plugins/qdreader/qdreader_sign_autman.js js/qdreader_sign_autman.js
+```
+
+推送后还要验证 Gitea raw：
+
+- raw 正式插件存在并包含新版本号。
+- raw `js/` 副本存在并与正式插件一致。
+- raw README/文档包含任务矩阵、执行时间窗口和关键接口。
+- raw 插件中不再包含 `0n` / `62n` 等 BigInt 字面量。
+
+### 14.7 给 BOSS 的最终回复要包含什么
+
+- 明确下一次 cron 时间，例如“每天 07:01”。
+- 明确默认只跑安全签到 + 领取奖励；可选任务需要在 `启点账号 → 账号任务配置` 按账号开启。
+- 明确查询结果从归档判断，不要把清空近期日志误解释成没运行。
+- 给出测试、commit、push、raw 验证结果，避免只说“应该可以”。