pi-cc-loop 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-cc-loop
 
-> 在 Pi 里复刻 Claude Code 的 `/loop`：固定间隔 cron、自选间隔、兜底心跳和可选状态条。
+> 在 Pi 里复刻 Claude Code 的 `/loop`：固定间隔 cron、自选间隔、兜底心跳和底部状态摘要。
 
 ## 快速开始
 
@@ -14,100 +14,64 @@ pi install npm:pi-cc-loop
 
 安装后执行 `/reload`。
 
-## 功能
+## 工作方式
+
+`/loop` 和 CC 一样是一个**技能**，不是用代码直接排任务：你输入的内容会作为一条普通 user 消息进入对话，
+模型自己解析间隔并调用工具完成。所以对话里始终能看到你要求了什么、模型做了什么。
 
 | 功能 | 说明 | 入口 |
 | --- | --- | --- |
-| 固定间隔 | 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 | 自动 |
+| 固定间隔 | 模型用 `cron_create` 建一个 cron（`5m` → `*/5 * * * *`），然后立即执行一次；触发时按"定时任务"呈现 | `/loop 5m <prompt>`、`/loop 每分钟 ...` |
+| 自选间隔 | 运行一次后用 `schedule_wakeup` 决定下次延迟（60–3600s） | `/loop <prompt>` |
+| loop.md | 请求本身没有任务时（裸 `/loop` 或只给间隔）由 `.pi/loop.md` 提供，每次触发重读；首轮由模型自己读文件 | `/loop`、`/loop 15m` |
+| 停止 / 查看 | 也走对话：模型用 `cron_list` / `cron_delete`（自选间隔用 `schedule_wakeup` + `stop: true`） | `/loop stop`、`/loop status` |
 | 漏跑合并 | agent 忙时到点只记一次 pending，空闲后发一条 | 自动 |
 | 兜底心跳 | 模型忘记调度时 arm 一次 20 分钟心跳，预算 1 次 | 自动 |
 | Esc 取消 | 打断属于某个自定步调 loop 的回合（它的 tick、它的 Monitor 唤醒的回合）时取消该 loop；无关回合、空闲时不受影响；固定间隔不受影响 | Esc |
 | 错峰 | 周期任务按 id 固定延后最多半个周期（≤30 分钟），间隔本身不变；`:00`/`:30` 的一次性任务最多提前 90 秒 | 自动 |
 | 过期 | 周期任务 7 天后最后执行一次再删除；一次性任务不过期 | 自动 |
-| 次数上限 | `--max N`，到顶自动删除 | 标志 |
-| 持久化 | `--durable` 写入 `.pi/scheduled_tasks.json`；同一项目只由一个 Pi 会话执行 | 标志 |
-| 状态条 | 输入框上方状态行，默认关闭 | `/loop widget on\|off` |
+| 次数上限 | `maxFires`，到顶自动删除 | 模型传参 |
+| 持久化 | `durable: true` 写入 `.pi/scheduled_tasks.json`；同一项目只由一个 Pi 会话执行 | 模型传参 |
+| 底部摘要 | Pi 底部状态栏一行：`loop 2 · next 3m`，无任务时不占位 | `/loop footer on\|off` |
+| 界面设置 | 仍是本地命令，不进对话 | `/loop settings ...` |
 
 ## 命令
 
 ```text
-/loop [间隔] <prompt>     按间隔重复跑
-/loop <prompt>            间隔交给模型判断
-/loop [间隔]              运行 .pi/loop.md 或内置维护 prompt（不带间隔则自定步调）
-/loop status              列出当前 loop
-/loop stop [id]           停止一个或全部
-/loop widget on|off       状态条
-/loop settings ...        界面设置
-/loop help                帮助
+/loop [间隔] <prompt>     交给模型：按间隔重复，或自选节奏
+/loop <prompt>            交给模型：自选间隔
+/loop [间隔]              交给模型：跑 .pi/loop.md 或内置维护 prompt
+/loop status              交给模型：列出当前 loop
+/loop stop [id]           交给模型：停止一个或全部
+/loop footer on|off       本地：底部摘要
+/loop settings ...        本地：界面设置
+/loop help                本地：帮助
 ```
 
-标志：`--durable` 写入 `.pi/scheduled_tasks.json`；`--max N` 触发 N 次后自动停止。
-
-agent 忙时输入 `/loop`，会等当前回合结束再开始。
+前五个会作为普通 user 消息进入对话（内容就是你输入的那行），模型再按技能说明调用
+`cron_create`、`cron_list`、`cron_delete`、`schedule_wakeup`。后三个只改界面，不进对话。
 
-间隔写法：
+间隔写法没有约束，模型自己解析：`30s`、`5m`、`2h`、`1d`、`check the deploy every 20m`、
+`每2分钟输出一次`、`每分钟打印一次hi` 都可以。小于一分钟会向上取整到每分钟。
 
-- `30s`、`5m`、`2h`、`1d`
-- `check the deploy every 20m`、`every 5 min`、`every 2 hrs`
-- 秒向上取整到分钟；不整除的间隔按 CC 规则取整并提示：`7m` → `*/6`，`30s` → 每分钟
-- 其他语言（如「每30秒」）交给模型解析
+## 底部摘要
 
-## 工具
+`ctx.ui.setStatus("loop", …)` 是 Pi 核心 API，不依赖任何其他扩展：
 
-| 工具 | 说明 |
+| 场景 | 显示 |
 | --- | --- |
-| `cron_create` | 创建固定间隔任务；支持 `recurring`、`durable`、`maxFires` |
-| `cron_delete` | 按 id 取消 |
-| `cron_list` | 列出任务 |
-| `schedule_wakeup` | 自选间隔：安排下次唤醒，或 `stop: true` 结束 |
-
-`schedule_wakeup` 参数：
-
-- `delaySeconds`：60–3600，越界自动钳制
-- `reason`：一句原因
-- `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`：
-
-```jsonc
-{
-  "compactMessages": true,          // 两行 marker / 旧的带底色卡片
-  "compactToolRows": true,          // 一行工具结果 / Pi 默认工具行
-  "managePiCcExtensions": true      // 自动维护 pi-cc-extensions 的 excludeRenderers
-}
-```
-
-用命令切换：
-
-```text
-/loop settings
-/loop settings messages on|off
-/loop settings tools on|off
-```
+| 没有任务 | 不设置状态，footer 不会被多占一行 |
+| 有任务 | `loop 3 · next 4m`（数量 + 最近一次触发） |
+| 一分钟内 | `loop 1 · next <1m` |
+| 超过一小时 | `loop 1 · next 2h 15m` |
 
-- 已画出的旧行需要 `/reload` 才会换样式
-- 环境变量覆盖：`PI_CC_COMPACT_MESSAGES=0`、`PI_CC_COMPACT_TOOL_ROWS=0`、`PI_CC_MANAGE_CCSTYLE=0`
+- 倒计时取整到分钟，配合"文本相同就不调用"的去重，最多每分钟重绘一次（Pi 每次 `setStatus` 都会触发重绘）
+- 装了 `pi-cc-extensions`：这一行会作为它的一个 chip 出现在第 2 行，可在它的配置面板里移动或隐藏；它会把 ANSI 去掉，所以这里只用纯文本
+- 没装 `pi-cc-extensions`：Pi 内置 footer 会把它和其他扩展的状态拼成一行，加在用量行下面，只在有任务时出现
 
-> 如果装了 `pi-cc-extensions`，`tools on` 会把本扩展的工具名加入它的 `excludeRenderers`；
-> `tools off` 只移除自己加过的名字。它只在启动时读配置，切换后需要 `/reload`。
+> 本扩展不写其他插件的配置文件。如果你之前在 `pi-cc-extensions.json` 里因为旧版本加过
+> `cron_create`、`cron_delete`、`cron_list`、`schedule_wakeup` 这几条 `excludeRenderers`，
+> 现在可以删掉：工具行由 Pi 或 pi-cc-extensions 自己渲染。
 
 ## 环境变量
 
@@ -117,6 +81,7 @@ agent 忙时输入 `/loop`，会等当前回合结束再开始。
 | `PI_LOOP_KEEPALIVE_SECONDS` | `1200` | 兜底心跳；`0` 禁用 |
 | `PI_LOOP_JITTER` | `0.5` | 周期任务最多延后的周期比例；`0` 关闭错峰 |
 | `PI_LOOP_SCAN_MS` | `1000` | 调度扫描间隔 |
+| `PI_CC_FOOTER` | `1` | 底部摘要；`0` 关闭（两个 pi-cc 包共用） |
 
 ## 兼容性
 
@@ -135,7 +100,7 @@ npx --yes typescript@5.9.3 tsc --noEmit -p tsconfig.json
 
 - 行为对齐 Claude Code v2.1.306 的 `/loop`，用 Pi 扩展 API 实现。
 - Esc 只取消被打断回合所属的自定步调 loop；CC 在任何时候按 Esc（包括空闲、打断无关回合）都会取消所有自定步调 loop。其他情况用 `/loop stop`。
-- 状态条默认关闭，和 CC 主会话一致。
+- 底部摘要默认开启，是 CC 没有的（CC 主会话不显示 loop 状态）；详细面板默认关闭。
 - `cron_create` 的 `maxFires` 是额外加固；CC 没有次数上限。
 - `/loop stop` 会连带静默停掉该 chain 绑定的 Monitor。
 - Monitor 事件不会取消待触发的 wakeup，它始终是兜底心跳（与 CC 一致）。

package/config.ts

@@ -8,13 +8,13 @@
  *   ~/.pi/agent/pi-cc.json
  *   {
  *     "compactMessages": true,
- *     "compactToolRows": true
+ *     "footer": true
  *   }
  *
  * Environment overrides (useful for tests and quick experiments):
  *   PI_CC_CONFIG_FILE=/path/to/pi-cc.json
  *   PI_CC_COMPACT_MESSAGES=0|1
- *   PI_CC_COMPACT_TOOL_ROWS=0|1
+ *   PI_CC_FOOTER=0|1
  */
 
 import fs from "node:fs";
@@ -24,22 +24,16 @@ import path from "node:path";
 export interface PiCcConfig {
 	/** Two-line marker blocks instead of the padded card. */
 	compactMessages: boolean;
-	/** One-line tool results instead of Pi's "N lines returned" preview. */
-	compactToolRows: boolean;
 	/**
-	 * Keep pi-cc tools out of pi-cc-extensions' global tool styling so the
-	 * compact rows above are visible. Only names this extension added are
-	 * removed again when the setting is turned off.
+	 * Show a one-line summary in Pi's footer (loops armed, monitors running).
+	 * Shared so one switch silences both packages.
 	 */
-	managePiCcExtensions: boolean;
-	/** Internal: names this extension added to pi-cc-extensions.json. */
-	managedExcludes?: string[];
+	footer: boolean;
 }
 
 export const DEFAULT_CONFIG: PiCcConfig = {
 	compactMessages: true,
-	compactToolRows: true,
-	managePiCcExtensions: true,
+	footer: true,
 };
 
 function envBool(name: string): boolean | undefined {
@@ -69,17 +63,8 @@ function readConfig(): PiCcConfig {
 		compactMessages:
 			envBool("PI_CC_COMPACT_MESSAGES") ??
 			(typeof file.compactMessages === "boolean" ? file.compactMessages : DEFAULT_CONFIG.compactMessages),
-		compactToolRows:
-			envBool("PI_CC_COMPACT_TOOL_ROWS") ??
-			(typeof file.compactToolRows === "boolean" ? file.compactToolRows : DEFAULT_CONFIG.compactToolRows),
-		managePiCcExtensions:
-			envBool("PI_CC_MANAGE_CCSTYLE") ??
-			(typeof file.managePiCcExtensions === "boolean"
-				? file.managePiCcExtensions
-				: DEFAULT_CONFIG.managePiCcExtensions),
-		managedExcludes: Array.isArray(file.managedExcludes)
-			? file.managedExcludes.filter((name): name is string => typeof name === "string")
-			: [],
+		footer:
+			envBool("PI_CC_FOOTER") ?? (typeof file.footer === "boolean" ? file.footer : DEFAULT_CONFIG.footer),
 	};
 }
 
@@ -101,73 +86,17 @@ export function saveConfig(patch: Partial<PiCcConfig>): PiCcConfig {
 	const next = { ...loadConfig(), ...patch };
 	const file = configPath();
 	fs.mkdirSync(path.dirname(file), { recursive: true });
-	const temp = `${file}.tmp`;
-	fs.writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, "utf8");
-	fs.renameSync(temp, file);
-	cached = next;
-	return next;
-}
-
-/**
- * pi-cc-extensions' config file. That extension loads its config once at load
- * time, so changes made here apply after `/reload`.
- */
-export function piCcExtensionsConfigPath(): string {
-	const agentDir =
-		process.env.PI_CODING_AGENT_DIR ?? process.env.PI_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
-	return process.env.PI_CC_EXTENSIONS_CONFIG_FILE ?? path.join(agentDir, "pi-cc-extensions.json");
-}
-
-/**
- * Add or remove our tool names in pi-cc-extensions' `excludeRenderers`.
- *
- * Returns true when the file changed (the caller can tell the user to reload).
- * Only names this extension added are removed again; a name the user put there
- * themselves is left alone.
- */
-export function syncPiCcExtensionsExcludes(toolNames: readonly string[], enabled: boolean): boolean {
-	// Another package may have written managedExcludes since our last read.
-	invalidateConfig();
-	const config = loadConfig();
-	if (!config.managePiCcExtensions) return false;
-	const file = piCcExtensionsConfigPath();
-	if (!fs.existsSync(file)) return false;
-
-	let raw: Record<string, unknown>;
+	// Keep keys this version does not know about: the file is the user's.
+	let raw: Record<string, unknown> = {};
 	try {
 		const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
-		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return false;
-		raw = parsed as Record<string, unknown>;
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) raw = parsed as Record<string, unknown>;
 	} catch {
-		return false;
-	}
-
-	const current = Array.isArray(raw.excludeRenderers)
-		? raw.excludeRenderers.filter((name): name is string => typeof name === "string")
-		: [];
-	const managed = new Set(config.managedExcludes ?? []);
-	const next = new Set(current);
-	let changed = false;
-
-	for (const name of toolNames) {
-		if (enabled) {
-			if (!next.has(name)) {
-				next.add(name);
-				managed.add(name);
-				changed = true;
-			}
-		} else if (managed.has(name)) {
-			if (next.delete(name)) changed = true;
-			managed.delete(name);
-		}
+		// A missing or malformed file is rewritten from scratch.
 	}
-
-	if (!changed && managed.size === (config.managedExcludes ?? []).length) return false;
-
-	raw.excludeRenderers = [...next].sort((a, b) => a.localeCompare(b));
 	const temp = `${file}.tmp`;
-	fs.writeFileSync(temp, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
+	fs.writeFileSync(temp, `${JSON.stringify({ ...raw, ...next }, null, 2)}\n`, "utf8");
 	fs.renameSync(temp, file);
-	saveConfig({ managedExcludes: [...managed].sort((a, b) => a.localeCompare(b)) });
-	return changed;
+	cached = next;
+	return next;
 }

package/cron.ts

@@ -154,36 +154,7 @@ export function isUnreachable(expression: string): boolean {
 	return nextFireAfter(fields, new Date(), 366) === null;
 }
 
-export interface IntervalSpec {
-	/** Number of seconds the schedule actually uses. */
-	seconds: number;
-	/** Cron expression that implements the interval. */
-	cron: string;
-	/** Human readable cadence, e.g. "every 5 minutes". */
-	human: string;
-	/** True when the requested interval had to be adjusted. */
-	adjusted: boolean;
-	/** What the user asked for, in seconds. */
-	requestedSeconds: number;
-	/** Human readable explanation of the adjustment, for the user. */
-	note?: string;
-}
-
-const UNIT_SECONDS: Record<string, number> = {
-	s: 1,
-	m: 60,
-	h: 3600,
-	d: 86400,
-};
-
 /** 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"],
-};
-
 /**
  * The divisor of `total` closest to `n`.
  *
@@ -206,99 +177,17 @@ function nearestDivisor(n: number, total: number): number {
 }
 
 /**
- * Convert a duration into a cron expression, following Claude Code's rule:
- *
- *   "Supported suffixes: `s` -> ceil to nearest minute, `m` (minutes),
- *    `h` (hours), `d` (days). Examples: `5m` -> a 5 minute step, `1h` -> `0 * * * *`,
- *    `1d` -> `0 0 * * *`. If the interval doesn't cleanly divide its unit, round to the
- *    nearest clean interval and tell the user what you rounded to."
+ * Parse `每2分钟输出一次` / `输出一次 每隔 2 小时`: an explicit interval written
+ * in Chinese. The digit is required on purpose: `每天都有一个测试失败` is a
+ * prompt, not a schedule, and Claude Code's own splitting is just as literal.
  */
-export function intervalToCron(seconds: number): IntervalSpec | null {
-	if (!Number.isFinite(seconds) || seconds <= 0) return null;
-
-	// Sub-minute: the scheduler's granularity is one minute, so round up.
-	if (seconds < 60) {
-		return {
-			seconds: 60,
-			cron: "* * * * *",
-			human: "every minute",
-			adjusted: true,
-			requestedSeconds: seconds,
-			note: `${seconds}s rounded up to 1 minute (the scheduler's minimum granularity is 1 minute)`,
-		};
-	}
-
-	// "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,
-			cron: `*/${minutes} * * * *`,
-			human: `every ${minutes} minute${minutes === 1 ? "" : "s"}`,
-			adjusted: minutes !== requested,
-			requestedSeconds: seconds,
-			...(minutes !== requested
-				? { note: `${requested}m rounded to ${minutes}m, the nearest clean interval` }
-				: {}),
-		};
-	}
-
-	if (seconds < 86400) {
-		const requested = Math.max(1, Math.round(seconds / 3600));
-		const hours = nearestDivisor(requested, 24);
-		return {
-			seconds: hours * 3600,
-			cron: hours === 1 ? "0 * * * *" : `0 */${hours} * * *`,
-			human: `every ${hours} hour${hours === 1 ? "" : "s"}`,
-			adjusted: hours !== requested,
-			requestedSeconds: seconds,
-			...(hours !== requested
-				? { note: `${requested}h rounded to ${hours}h, the nearest clean interval` }
-				: {}),
-		};
-	}
-
-	const days = Math.max(1, Math.round(seconds / 86400));
-	return {
-		seconds: days * 86400,
-		cron: days === 1 ? "0 0 * * *" : `0 0 */${days} * *`,
-		human: days === 1 ? "every day" : `every ${days} days`,
-		adjusted: days * 86400 !== seconds,
-		requestedSeconds: seconds,
-	};
-}
-
-/** Parse a duration token such as `5m`, `30s`, `2h`, `1d`. */
-export function parseIntervalToken(token: string): number | null {
-	const m = /^(\d+)\s*([smhd])$/i.exec(token.trim());
-	if (!m) return null;
-	const unit = m[2].toLowerCase();
-	const amount = Number(m[1]);
-	if (!Number.isFinite(amount) || amount <= 0) return null;
-	return amount * UNIT_SECONDS[unit];
-}
-
 /**
  * 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();
-	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 };
-}
-
 const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
 
+
 /**
  * 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",