pi-cc-loop 0.1.0 → 0.2.0

package/README.md

@@ -21,11 +21,15 @@ pi install npm:pi-cc-loop
 | 固定间隔 | 5 字段 cron；`30s`、`5m`、`2h`、`1d`；秒向上取整到分钟 | `/loop 5m <prompt>` |
 | 自选间隔 | 模型每轮用 `schedule_wakeup` 决定下次延迟（60–3600s） | `/loop <prompt>` |
 | 自然语言间隔 | 命令层认不出时交给模型解析（中英文均可） | `/loop 每30秒 ...` |
+| loop.md | 不带 prompt 时运行 `.pi/loop.md`（每次触发重读，改了下一轮生效），没有则跑内置维护 prompt | `/loop`、`/loop 15m` |
 | 立即执行 | 创建后马上跑一次，不等首个 cron | 自动 |
 | 漏跑合并 | agent 忙时到点只记一次 pending，空闲后发一条 | 自动 |
 | 兜底心跳 | 模型忘记调度时 arm 一次 20 分钟心跳，预算 1 次 | 自动 |
+| Esc 取消 | 打断属于某个自定步调 loop 的回合（它的 tick、它的 Monitor 唤醒的回合）时取消该 loop；无关回合、空闲时不受影响；固定间隔不受影响 | Esc |
+| 错峰 | 周期任务按 id 固定延后最多半个周期（≤30 分钟），间隔本身不变；`:00`/`:30` 的一次性任务最多提前 90 秒 | 自动 |
+| 过期 | 周期任务 7 天后最后执行一次再删除；一次性任务不过期 | 自动 |
 | 次数上限 | `--max N`，到顶自动删除 | 标志 |
-| 持久化 | `--durable` 写入 `.pi/scheduled_tasks.json` | 标志 |
+| 持久化 | `--durable` 写入 `.pi/scheduled_tasks.json`；同一项目只由一个 Pi 会话执行 | 标志 |
 | 状态条 | 输入框上方状态行，默认关闭 | `/loop widget on\|off` |
 
 ## 命令
@@ -33,7 +37,7 @@ pi install npm:pi-cc-loop
 ```text
 /loop [间隔] <prompt>     按间隔重复跑
 /loop <prompt>            间隔交给模型判断
-/loop                     使用 .pi/loop.md 或内置维护 prompt
+/loop [间隔]              运行 .pi/loop.md 或内置维护 prompt（不带间隔则自定步调）
 /loop status              列出当前 loop
 /loop stop [id]           停止一个或全部
 /loop widget on|off       状态条
@@ -43,11 +47,13 @@ pi install npm:pi-cc-loop
 
 标志：`--durable` 写入 `.pi/scheduled_tasks.json`；`--max N` 触发 N 次后自动停止。
 
+agent 忙时输入 `/loop`，会等当前回合结束再开始。
+
 间隔写法：
 
 - `30s`、`5m`、`2h`、`1d`
-- `check the deploy every 20m`
-- 不整除的间隔按 CC 规则取整并提示：`7m` → `*/6`，`30s` → 每分钟
+- `check the deploy every 20m`、`every 5 min`、`every 2 hrs`
+- 秒向上取整到分钟；不整除的间隔按 CC 规则取整并提示：`7m` → `*/6`，`30s` → 每分钟
 - 其他语言（如「每30秒」）交给模型解析
 
 ## 工具
@@ -63,9 +69,20 @@ pi install npm:pi-cc-loop
 
 - `delaySeconds`：60–3600，越界自动钳制
 - `reason`：一句原因
-- `prompt`：原样传回 `/loop` 的 prompt
+- `prompt`：原样传回 `/loop` 的 prompt；裸 `/loop` 传 `<<loop.md>>`
 - `stop`：结束当前自选间隔 loop
 
+`schedule_wakeup` 调用后本回合结束（工具批次里只有它时），所以模型会先写进度再调用；
+延迟按你给的值使用（四舍五入到整秒），只有超出 60–3600 秒才会被 clamp 并提示。CC 会把 `*/5` 任务提前 15 秒、把 286–300 秒的延迟压到 285 秒来保温 5 分钟的 prompt 缓存，我们没有跟：现在的缓存能活几十分钟到几小时，这样改只会让间隔变成 4 分 45 秒。
+
+## 持久化与恢复
+
+- `--durable` / `durable: true` 的任务存在 `.pi/scheduled_tasks.json`，并自动加入 `.git/info/exclude`
+- 同一项目只有持有 `.pi/scheduled_tasks.lock` 的 Pi 会话执行它们；该会话退出（或 60 秒没有心跳）后由其他会话接管
+- Pi 没运行时错过的 durable 一次性任务会被移除，下一轮先问你要不要补跑
+- 从别的目录拷来的任务只列出、不执行；`.pi` 或任务文件是符号链接时拒绝写入
+- 恢复会话：会话内任务照常恢复，但过期的周期任务、已过时间的一次性任务除外，错过的运行不补跑；自定步调 loop 不恢复（需重新 `/loop`），`/reload` 时保留
+
 ## 设置
 
 两个 pi-cc 扩展共享 `~/.pi/agent/pi-cc.json`：
@@ -98,7 +115,7 @@ pi install npm:pi-cc-loop
 | --- | --- | --- |
 | `PI_LOOP_MAX_AGE_DAYS` | `7` | 任务最长存活天数，`0` 不过期 |
 | `PI_LOOP_KEEPALIVE_SECONDS` | `1200` | 兜底心跳；`0` 禁用 |
-| `PI_LOOP_JITTER` | `0` | 抖动比例 0–1 |
+| `PI_LOOP_JITTER` | `0.5` | 周期任务最多延后的周期比例；`0` 关闭错峰 |
 | `PI_LOOP_SCAN_MS` | `1000` | 调度扫描间隔 |
 
 ## 兼容性
@@ -117,9 +134,11 @@ npx --yes typescript@5.9.3 tsc --noEmit -p tsconfig.json
 ## 说明
 
 - 行为对齐 Claude Code v2.1.306 的 `/loop`，用 Pi 扩展 API 实现。
-- `/loop stop` 代替 CC 的 Esc；状态条默认关闭，和 CC 主会话一致。
+- Esc 只取消被打断回合所属的自定步调 loop；CC 在任何时候按 Esc（包括空闲、打断无关回合）都会取消所有自定步调 loop。其他情况用 `/loop stop`。
+- 状态条默认关闭，和 CC 主会话一致。
 - `cron_create` 的 `maxFires` 是额外加固；CC 没有次数上限。
-- `/loop stop` 会连带停掉该 chain 绑定的 Monitor。
+- `/loop stop` 会连带静默停掉该 chain 绑定的 Monitor。
+- Monitor 事件不会取消待触发的 wakeup，它始终是兜底心跳（与 CC 一致）。
 
 ## 许可证
 

package/cron.ts

@@ -176,11 +176,12 @@ const UNIT_SECONDS: Record<string, number> = {
 	d: 86400,
 };
 
-const UNIT_NAMES: Record<string, [string, string]> = {
-	s: ["second", "seconds"],
-	m: ["minute", "minutes"],
-	h: ["hour", "hours"],
-	d: ["day", "days"],
+/** The unit words Claude Code's /loop accepts in a trailing "every N <unit>" clause. */
+const UNIT_WORDS: Record<string, string[]> = {
+	s: ["s", "sec", "secs", "second", "seconds"],
+	m: ["m", "min", "mins", "minute", "minutes"],
+	h: ["h", "hr", "hrs", "hour", "hours"],
+	d: ["d", "day", "days"],
 };
 
 /**
@@ -227,8 +228,10 @@ export function intervalToCron(seconds: number): IntervalSpec | null {
 		};
 	}
 
-	if (seconds < 3600) {
-		const requested = Math.round(seconds / 60);
+	// "Seconds are rounded up to the nearest minute since cron has one-minute
+	// granularity."
+	if (seconds < 3600 && Math.ceil(seconds / 60) < 60) {
+		const requested = Math.ceil(seconds / 60);
 		const minutes = nearestDivisor(requested, 60);
 		return {
 			seconds: minutes * 60,
@@ -243,7 +246,7 @@ export function intervalToCron(seconds: number): IntervalSpec | null {
 	}
 
 	if (seconds < 86400) {
-		const requested = Math.round(seconds / 3600);
+		const requested = Math.max(1, Math.round(seconds / 3600));
 		const hours = nearestDivisor(requested, 24);
 		return {
 			seconds: hours * 3600,
@@ -277,24 +280,19 @@ export function parseIntervalToken(token: string): number | null {
 	return amount * UNIT_SECONDS[unit];
 }
 
-/** Parse `every 20m` / `every 5 minutes` / `every 2 hours` style clauses. */
+/**
+ * Parse a trailing `every 20m` / `every 5 min` / `every 2 hours` clause, with
+ * the unit words Claude Code accepts.
+ */
 export function parseEveryClause(input: string): { interval: number; prompt: string } | null {
 	const m = /\bevery\s+(\d+)\s*([a-z]+)\s*$/i.exec(input.trim());
 	if (!m) return null;
 	const amount = Number(m[1]);
+	if (!(amount > 0)) return null;
 	const word = m[2].toLowerCase();
-	let unitSeconds: number | undefined;
-	for (const [key, names] of Object.entries(UNIT_NAMES)) {
-		if (names[0] === word || names[1] === word) {
-			unitSeconds = UNIT_SECONDS[key];
-			break;
-		}
-	}
-	// Single letter units, e.g. "every 20m".
-	if (unitSeconds === undefined && word.length === 1 && word in UNIT_SECONDS) {
-		unitSeconds = UNIT_SECONDS[word];
-	}
-	if (unitSeconds === undefined) return null;
+	const unit = Object.keys(UNIT_WORDS).find((key) => UNIT_WORDS[key].includes(word));
+	if (!unit) return null;
+	const unitSeconds = UNIT_SECONDS[unit];
 	const prompt = input.trim().slice(0, m.index).trim();
 	return { interval: amount * unitSeconds, prompt };
 }
@@ -302,46 +300,59 @@ export function parseEveryClause(input: string): { interval: number; prompt: str
 const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
 
 /**
- * A human readable cadence for a cron expression, the way Claude Code
- * reports it ("Every minute", "Every 5 minutes", "Daily at 9:00 AM").
+ * A human readable cadence for a cron expression, with Claude Code's labels:
+ * "Every minute", "Every 5 minutes", "Every hour at :07", "Every 2 hours",
+ * "Every day at 9:00 AM", "Every Sunday at 9:00 AM", "Weekdays at 9:00 AM".
+ *
+ * Like Claude Code, anything else is shown as written rather than as a
+ * half-filled sentence. The one addition is "Every N days at ...", which
+ * `/loop Nd` produces.
  */
 export function humanSchedule(expression: string): string {
-	const fields = parseCron(expression);
-	if (!fields) return expression;
-	const [minute, hour, dom, month, dow] = expression.trim().split(/\s+/);
-	const everyMinute = minute === "*" && hour === "*" && dom === "*" && month === "*" && dow === "*";
-	if (everyMinute) return "Every minute";
+	const fields = expression.trim().split(/\s+/);
+	if (fields.length !== CRON_FIELD_COUNT || !parseCron(expression)) return expression;
+	const [minute, hour, dom, month, dow] = fields;
+	const isNumber = (value: string) => /^\d+$/.test(value);
+	const step = (value: string) => {
+		const match = /^\*\/(\d+)$/.exec(value);
+		return match ? Number(match[1]) : undefined;
+	};
+	const atMinute = (value: number) => `:${String(value).padStart(2, "0")}`;
+	const everyDay = dom === "*" && month === "*" && dow === "*";
+
+	if (hour === "*" && everyDay) {
+		if (minute === "*") return "Every minute";
+		const n = step(minute);
+		if (n !== undefined) return n === 1 ? "Every minute" : `Every ${n} minutes`;
+		if (isNumber(minute)) return Number(minute) === 0 ? "Every hour" : `Every hour at ${atMinute(Number(minute))}`;
+		return expression;
+	}
 
-	const step = /^\*\/(\d+)$/.exec(minute);
-	if (step && hour === "*" && dom === "*" && month === "*" && dow === "*") {
-		const n = Number(step[1]);
-		return n === 1 ? "Every minute" : `Every ${n} minutes`;
+	const hours = step(hour);
+	if (isNumber(minute) && hours !== undefined && everyDay) {
+		const at = Number(minute) === 0 ? "" : ` at ${atMinute(Number(minute))}`;
+		return hours === 1 ? `Every hour${at}` : `Every ${hours} hours${at}`;
 	}
 
-	const clock = clockText(minute, hour);
-	if (dom === "*" && month === "*" && dow === "*") {
-		if (hour === "*") return `Every hour at :${minute.padStart(2, "0")}`;
-		if (minute === "0") return `Hourly`;
-		return `Daily at ${clock}`;
+	if (!isNumber(minute) || !isNumber(hour)) return expression;
+	const clock = clockText(Number(minute), Number(hour));
+	if (everyDay) return `Every day at ${clock}`;
+	if (dom === "*" && month === "*") {
+		if (/^\d$/.test(dow)) return `Every ${DAY_NAMES[Number(dow) % 7]} at ${clock}`;
+		if (dow === "1-5") return `Weekdays at ${clock}`;
 	}
-	if (month === "*" && dow === "*") return `On day ${dom} at ${clock}`;
-	if (month === "*") {
-		const days = dow
-			.split(",")
-			.map((d) => DAY_NAMES[Number(d) % 7])
-			.join(", ");
-		return `Every ${days} at ${clock}`;
+	const days = step(dom);
+	if (days !== undefined && month === "*" && dow === "*") {
+		return days === 1 ? `Every day at ${clock}` : `Every ${days} days at ${clock}`;
 	}
 	return expression;
 }
 
-/** "9:05 AM" style time for the minute and hour fields. */
-function clockText(minute: string, hour: string): string {
-	if (hour === "*") return `:${minute.padStart(2, "0")}`;
-	const h = Number(hour);
-	const suffix = h < 12 ? "AM" : "PM";
-	const display = h % 12 === 0 ? 12 : h % 12;
-	return `${display}:${minute.padStart(2, "0")} ${suffix}`;
+/** "9:05 AM" style time. */
+function clockText(minute: number, hour: number): string {
+	const suffix = hour < 12 ? "AM" : "PM";
+	const display = hour % 12 === 0 ? 12 : hour % 12;
+	return `${display}:${String(minute).padStart(2, "0")} ${suffix}`;
 }
 
 /** Human readable summary of a cron expression. */