配合 ScriptCat 1.3.x 更新 @crontab 说明

docs/dev/background.md

@@ -15,7 +15,7 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性
 
 > 定时脚本属于后台脚本的一种，适用于**按时间周期重复执行**的任务。
 
-定时脚本通过 `@crontab` 属性声明，支持分钟级与秒级调度，并提供脚本猫扩展语法 `once`，用于避免在同一时间周期内重复执行。
+定时脚本通过 `@crontab` 属性声明，支持分钟级与秒级调度，并提供脚本猫扩展语法 `once` / `once(...)`，用于避免在同一时间周期内重复执行。
 
 ⚠️ 注意事项：
 
@@ -69,9 +69,26 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性
 
 即使在同一周期内，后续时间点仍然符合 cron 规则，也不会再次执行。
 
+### `once` 与 `once(...)` 的区别
+
+| 写法          | 该字段对应的 cron 值 | 说明                              |
+| ----------- | ------------- | ------------------------------- |
+| `once`      | `*`（任意值）      | 周期内第一次命中时执行，不限定具体时间点            |
+| `once(expr)` | `expr`        | 周期内仅在 `expr` 匹配的时间点执行，且只执行一次 |
+
+`once(expr)` 允许在限制"每周期只执行一次"的同时，精确指定候选时间点。括号内支持所有标准 cron 语法（数字、范围、步长、列表）。
+
+示例对比：
+
+```text
+* once * * *          // 每小时任意分钟，第一次命中即执行，本小时内不再执行
+* once(9-17) * * *    // 每天 9 时至 17 时期间，每小时执行一次
+0,30 once * * *       // 每小时在 0 分或 30 分中，最早命中的那次执行，本小时内不再执行
+```
+
 ### `once` 所在位置 = 限制的时间周期
 
-`once` 写在哪一位，就表示“在该时间粒度内只执行一次”。
+`once` / `once(...)` 写在哪一位，就表示"在该时间粒度内只执行一次"。
 
 | `once` 位置 | 行为含义     |
 | --------- | -------- |
@@ -84,13 +101,14 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性
 示例：
 
 ```text
-* once * * *   // 每小时只执行一次
-* * once * *   // 每天只执行一次
+* once * * *       // 每小时只执行一次
+* * once * *       // 每天只执行一次
+* 9-18 once * *    // 每天 9 时至 18 时之间只执行一次
 ```
 
 ### `once` 与范围 / 列表 / 步长的组合行为
 
-`once` 可以与任何 cron 语法组合使用，但规则只有一条：
+`once` / `once(...)` 可以与任何 cron 语法组合使用，但规则只有一条：
 
 > **在同一周期内，只要成功执行过一次，其余命中的时间点都会被忽略**
 
@@ -130,6 +148,28 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性
 * 当天第一次执行后
 * 其余时间点将不再执行
 
+#### 示例四：`once(...)` 指定候选时间点
+
+```text
+* once(9-17) * * *
+```
+
+含义：
+
+* 每天 9 时至 17 时为候选小时
+* 每小时周期重置，当小时内第一次命中后不再重复
+* 效果：每天 9 时至 17 时期间，每小时各执行一次，共 9 次
+
+```text
+* 9-18 once * *
+```
+
+含义：
+
+* 每天 9:00–18:59 为候选时间
+* 日位 `once` 锁定每天周期
+* 当天第一次命中后，18:59 前不再执行
+
 ## `@crontab` 示例
 
 ### 常见
@@ -148,9 +188,12 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性
 ### 进阶
 
 ```js
-//@crontab * 1,3,5 once * *    // 每天1点3点5点中运行一次（假设当1点时运行了一次,3,5点将不会再运行）
-//@crontab * 10-23 once * *    // 每天10点-23:59中运行一次（假设当10:04时运行了一次,10:05-23:59的后续时间将不会再运行）
-//@crontab * once 13 * *    // 每个月的13号的每小时运行一次
+//@crontab * 1,3,5 once * *       // 每天1点3点5点中运行一次（假设当1点时运行了一次,3,5点将不会再运行）
+//@crontab * 10-23 once * *       // 每天10点-23:59中运行一次（假设当10:04时运行了一次,10:05-23:59的后续时间将不会再运行）
+//@crontab * once 13 * *          // 每个月的13号的每小时运行一次
+//@crontab * once(9-17) * * *     // 每天9时至17时期间，每小时执行一次
+//@crontab 0,30 once * * *        // 每小时在0分或30分中，最早命中的那次执行，本小时不再重复
+//@crontab * 9-18 once * *        // 每天9时至18时之间只执行一次
 ```
 
 ## 使用建议
@@ -173,8 +216,12 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性
 
 ## Cron 表达式测试
 
-测试 cron 表达式时，请将 `once` **临时替换为 `*`**。
-注意测试工具有可能不支持 扩展 6 位格式。
+测试 cron 表达式时，请将 `once` / `once(...)` **临时替换为对应的值**：
+
+* `once` → `*`
+* `once(expr)` → `expr`
+
+注意测试工具有可能不支持扩展 6 位格式。
 
 推荐工具：