定時任務
文件版本：20260905
文件目前版本對應的 APP 版本：
- iOS：>= 3.16
- Android：>= 1.8.0
- macOS / Windows（PC 端）：>= 1.0.21
定時任務可以把一條 請求重放 或一整條 組合重放 規則，依 Cron 或自訂間隔自動執行。適合秒殺壓測、活動開賣瞬間驗證、定時巡檢介面等「人手點來不及」的場景。
典型場景：電商秒殺窗口極短，人工點擊很容易錯過。可以先從抓包歷史取出下單請求（或編成組合重放），再建一條定時任務，在開賣前依秒級間隔自動送出，並用自動終止條件在「搶購成功 / 活動結束」時停掉任務。
組合重放本身的編排、依賴注入、表達式寫法，見 組合重放使用教程。
目錄
一、功能概覽
| 能力 | 說明 |
|---|---|
| 請求重放 | 依快照重放單條 HTTP/HTTPS 請求（Method / URL / Header / Body） |
| 組合重放 | 依快照執行整條組合規則（拓撲分層、表達式、依賴注入都會跑） |
| Cron | 6 欄位表達式（含秒）：秒 分 時 日 月 週 |
| 自訂 | 依間隔秒循環執行；可限制次數、持續時長（iOS / PC 還可指定開始時間） |
| 自動終止 | 僅兩種：回應 Body 正規表示式、JSON 欄位值完全相等。命中後任務被停用，不是暫停 |
| 執行歷史 | 獨立的「執行歷史」面板，含 Avg / P95 / P99、成功率 |
二、快速上手
- 先抓包，取得要定時執行的 HTTP/HTTPS 請求；若要跑流程，先在組合重放裡建好規則並儲存。
- 進入 定時任務 列表，點 + / 新增定時任務。
- 填寫 Job名稱，選擇目標類型：
- 請求重放：從歷史裡選一條請求，可以再改查詢參數、請求頭、請求 Body
- 組合重放：從既有組合規則裡選一條，可以再改每個節點（請求）的參數
- 選擇 Cron 或 自訂，確認設定頁裡的「最近幾次執行時間 / 下次執行時間」預覽合理。
- （可選）打開 自動終止，用正規表示式或 JSON 欄位比對「成功 / 結束」回應。
- 確認任務為 已啟用，然後：
- iOS / Android：開始抓包（VPN）。未開抓包時任務不會跑。執行期間 VPN 開著，請求也會進請求歷史，且已設定的重寫／指令碼會生效。
- 桌面端：保持 ApiCatcher 視窗執行即可，不依賴 VPN。若要讓重寫／指令碼作用到定時任務送出的請求，需要啟動擷取。
- 點進任務查看 執行歷史。
三、入口與任務管理
3.1 怎麼進「定時任務」
- 抓包首頁右上角 + → 定時任務
- 在 請求重放 或 組合重放執行頁 右上角點鬧鐘按鈕，可帶著目前請求或規則直接建立
3.2 建立 / 編輯 / 刪除 / 啟用
| 操作 | 方式 |
|---|---|
| 建立 | 列表右上角 +，或空狀態「新增定時任務」 |
| 看歷史 | 點一下任務列 |
| 編輯 | 左滑 → 編輯 |
| 刪除 | 左滑 → 刪除（會一併刪除該任務的執行歷史） |
| 啟用 / 停用 | 編輯頁 Toggle「啟用」 |
新建時預設啟用。
編輯既有任務時，不能更換目標類型，也不能另選一條請求／規則；仍可改名稱、啟用開關、快照裡的請求參數／節點參數、排程方式和自動終止。
四、任務目標
目標只有兩種：
| Job目標 | 執行內容 |
|---|---|
| 請求重放 | 執行單個 HTTP 請求，支援表達式注入 |
| 組合重放 | 執行多個 HTTP 請求，依組合重放規則編排的順序執行，支援依賴注入、表達式注入 |
若組合重放規則更新後想讓 Job 跟著變，就必須再建一條新的 Job。
五、排程設定
兩種類型：Cron / 自訂。
設定頁會預覽最近／下次若干次執行時間（最多 5 條）。
5.1 Cron
表達式為 6 段，順序：
秒 分 時 日 月 週
第 7 段（年）即使寫了也會被忽略。少於 6 段就無法算出下次時間，不會排程。
這不是 Linux crontab 的 5 欄位寫法。例如 */5 * * * *（每 5 分鐘）在這裡無效。
支援的寫法：
*：該欄位任意取值?：用在日或週，表示不限定- 單個數字：如秒
0、時9 - 秒欄位步長
/：如0/30表示每 30 秒
預設／佔位示例：
0 * * * * ?
含義：每分鐘的第 0 秒。
常用例子：
| 表達式 | 含義 |
|---|---|
0 * * * * ? | 每分鐘第 0 秒 |
0 0 * * * ? | 每小時的 0 分 0 秒 |
0 0 9 * * ? | 每天 09:00:00 |
0/30 * * * * ? | 每 30 秒 |
需要「每 N 分鐘」時，請用 自訂，把間隔設為 N × 60 秒。
表達式框旁可用 AI 依自然語言產生 Cron。產生後請看下方預覽時間是否符合預期。
空表達式或算不出下次時間：該任務這次不排程，不會因此自動停用。
5.2 自訂
沒有單獨的「結束時間」欄位。依固定間隔循環執行，次數 與 持續時長 滿足其一即停（每次執行前檢查）。
| 欄位 | 單位 | 說明 |
|---|---|---|
| 間隔 | 秒 | 每隔多久執行一次，至少為 1 |
| 最大執行次數 | 次 | 達到次數後停止 |
| 持續時長 | 分鐘 | 從首次執行起持續多久後停止 |
次數、時長的計數在引擎記憶體裡。行程重啟後計數歸零；但若任務已被停用，不會自動再啟用。重新打開啟用開關後，次數從 0 再計。
跑滿次數或達到時長後，任務會被寫成 未啟用。
六、自動終止
介面名稱：自動終止。含義是：一旦命中，不管 Cron 還有沒有下次、自訂次數有沒有跑完，都不再繼續。
只有兩種條件，沒有依 HTTP 狀態碼終止：
| 類型 | 比對對象 | 規則 |
|---|---|---|
| 正規表示式 | 回應 Body 文字 | 任意位置命中即可（不是整串必須等於） |
| 欄位選擇 | 回應 JSON | 依路徑取值後，與「符合值」做 字串完全相等 |
補充：
- 多條條件是 或（OR），任一命中即停。
- 組合重放可指定 觀察節點；只看該節點的執行結果。
- JSON 比較是字串完全相等：數字
200要填符合值200；布林為true/false。
命中後的行為是 停用任務，任務還在，歷史還在，不會刪除。
七、何時會真正執行
受限於系統，各端實作不同。
iOS
定時任務需在 VPN 行程執行，開始抓包後才會生效。
| 情境 | 是否繼續跑 |
|---|---|
| 已開始抓包，主 App 進背景 | 會 |
| 已開始抓包，劃掉主 App，VPN 仍開 | 會 |
| 停止抓包 | 全部 timer 取消，停止 |
| 系統因記憶體回收 VPN 行程 | 停止；再次開始抓包才會重新載入已啟用任務 |
| 未開抓包 | 不執行。儲存任務只寫入資料庫，等下次開始抓包再排程 |
請求逾時 15 秒。VPN 開啟時，重放走本機 MITM（127.0.0.1:8888），因此 重寫規則、指令碼 會作用在這些請求上，抓包歷史裡也可能再出現對應紀錄。
Android
定時任務需在 VPN 服務執行，開始抓包後才會生效。
| 情境 | 是否繼續跑 |
|---|---|
| 抓包中，只滑到背景（前景通知還在） | 通常會繼續 |
| 停止抓包 | stop()，協程取消，記憶體裡的次數／首次時間清零 |
| 強制結束 App | VPN 與行程一起沒了，任務停 |
| 系統因省電殺掉行程 | 停止；若前景服務被系統拉起並再次 start()，才會重新排程仍為啟用的任務 |
連線／讀取逾時各 30 秒。同樣走本機 MITM，抓包歷史裡可能出現定時重放的流量。
桌面端
在 APP 行程執行，行程還在就能執行，行程結束就不再執行。
| 情境 | 是否繼續跑 |
|---|---|
| 視窗開著（可最小化） | 會 |
| 未開抓包 | 會 |
| 結束應用程式 | 停止 |
單請求逾時 30 秒；組合重放每個節點逾時 5 秒。請求走系統代理；若此時本機擷取開著，重寫規則、指令碼 會作用在這些請求上，抓包歷史裡也可能再出現對應紀錄。
組合重放執行規則（三端一致）
- 依依賴拓撲分層；同一層並行，下一層等上一層完成。
- 某節點非 2xx（或送出失敗）後，後續層 跳過（不再請求）。
- 快照裡的表達式、依賴注入、全域變數都會執行。
八、執行歷史與統計
點任務進入 執行歷史（不是編輯頁）。
頂部「統計詳情」依 全部執行紀錄 彙總（一次定時觸發算一條，不是依單條 HTTP）：
- Avg / P95 / P99：先算每一次執行的整段耗時（該條紀錄的結束時間 − 開始時間），再對全部紀錄取平均和第 95 / 99 百分位，介面顯示為毫秒
- Success Rate / Success / Failure：某一次執行裡 所有請求都成功 才算這次成功；組合重放有一個節點失敗，整次算失敗。再據此統計全部紀錄的成功率和成功／失敗次數
點某條紀錄可查看這次送出的請求（詳情）。如果是組合重放，會先列出各個節點，再點節點看詳情。
右上角可以清空該任務的全部歷史。刪除任務時，歷史會一起刪掉。
這套資料在獨立表裡，不是主介面「歷史紀錄／請求歷史」那張表。但如上一節所述：開著抓包時，重放往往還會再進主歷史。
主歷史裡的這些紀錄 沒有「定時任務」標記，看起來就像普通抓包。
九、典型場景
場景 1：秒殺開賣前高頻打單
- 抓到下單介面，確認 Body／Header 無誤（需要動態時間戳時，用組合重放節點寫
${method.timestamp()}）。 - 新建定時任務，目標選該請求或組合規則。
- 自訂：開始時間設為開賣前數秒（務必設未來時間），間隔 1 秒。
- 自動終止：JSON 欄位
code符合200，或正規表示式符合"搶購成功"/"活動已結束"。 - iOS / Android 提前開始抓包；桌面端保持視窗開啟。
場景 2：每分鐘巡檢一條健康檢查介面
三端都可用 Cron：
0 * * * * ?
不配自動終止，任務會一直依分鐘跑，直到你手動停用，或停止抓包（行動端）／結束應用程式（桌面端）。
場景 3：登入 + 業務介面的定時迴歸
- 在組合重放裡配好：登入 → 業務介面，並做好 token 依賴注入。
- 用該規則建立定時任務。
十、常見問題
Q：任務儲存了但不跑？
A：iOS / Android 必須先 開始抓包。桌面端必須讓應用程式保持執行。再確認任務是「已啟用」，Cron 至少 6 段且預覽能算出時間。
Q：自訂任務儲存後立刻變成未啟用？
A：把開始時間設成過去時間，引擎會直接停用且一次都不執行。請改成未來時間後重新啟用並儲存。
Q：改了組合重放規則，定時任務沒變化？
A：預期行為。任務綁的是建立時儲存的快照。請刪除後重建。
Q：為什麼主歷史裡也能看到這些請求？
A：行動端開著 VPN 時，定時重放會走本機 MITM，和普通抓包同一套入庫。請到任務的「執行歷史」看專用報表；主歷史裡沒有定時任務標記。
Q：自動終止配了狀態碼 200 怎麼不生效？
A：沒有「依 HTTP 狀態碼終止」。請改用 JSON 欄位（例如 code == 200）或正規表示式比對 Body。
Q：為什麼有的組合節點沒送出去？
A：與手動執行組合重放相同：上一層非 2xx 後，後續層跳過。被跳過的觀察節點沒有 Body，自動終止也不會命中。
Q：解除安裝 App／清除資料後任務還在嗎？
A：任務和歷史都在本機。解除安裝或清除資料會遺失。
Q：需要一直開著重寫規則嗎？
A：行動端定時請求會進 MITM。若有 Mock／丟棄／修改規則符合這些 URL，定時任務打出去的也是被改過的結果。排查「回應不對」時先看重寫和指令碼。