@muzi3/herdr 0.1.0 → 0.1.2

package/README.md

@@ -6,6 +6,7 @@
 |------|------|------|
 | `herdr-guide` | user-invoked 向导 | 引导用户理解、安装、配置与排查 Herdr（`herdr.dev/agent-guide.md`） |
 | `herdr-agent-state` | 扩展 | 通过 Herdr 的 pane socket 上报 agent 状态（working / blocked / idle）及会话引用，供 Herdr 面板展示 |
+| `pi-hot-restart` | 扩展 | 提供 `/pi-hot-restart` 命令：批量重启当前 herdr 里的所有 pi 窗口（跳过 working），并恢复到原 session |
 
 ## 来源与许可
 
@@ -18,6 +19,8 @@ Herdr 以 [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) 许可发布
 
 > 扩展源文件由 Herdr 集成管理，重装或更新集成时会覆盖；请在旁边添加自定义 hooks 而非编辑它。
 
+`pi-hot-restart.ts` 是本包自带的补充扩展，与官方 `herdr-agent-state` 互不干扰，在 `package.json` 的 `pi.extensions` 中显式声明（因 `extensions/index.ts` 存在时 pi 不会扫描同目录兄弟文件）。
+
 ## 安装
 
 ```bash
@@ -29,6 +32,15 @@ pi install npm:@muzi3/herdr
 - 用户询问 Herdr 是什么、怎么安装/配置/使用，或排查 agent 未识别、快捷键失效等问题时，触发 `herdr-guide` 引导（`/herdr-guide`）
 - 触发词：`herdr` / `herdr 安装` / `herdr 配置` / `终端工作区` / `agent 状态检测` 等
 
+### 批量重启 pi 窗口
+
+在任意 pi 窗口执行 `/pi-hot-restart`，会：
+
+1. 列出当前 herdr 里所有 `pi` 窗口；
+2. 跳过 `agent_status === "working"` 的窗口（含当前发起命令的窗口本身）；
+3. 弹出确认框，展示将重启的窗口清单与数量；
+4. 对每个目标窗口：向 pi 前台进程组发 SIGTERM 优雅退出（session 落盘），等待退出后用 `pi --session <path|id>` 在原 pane 恢复。
+
 ### 扩展环境变量
 
 扩展需在 Herdr 集成环境中运行，依赖以下环境变量：
@@ -39,7 +51,7 @@ pi install npm:@muzi3/herdr
 | `HERDR_SOCKET_PATH` | Herdr pane socket 路径 |
 | `HERDR_PANE_ID` | 当前 pane id |
 
-未设置这些变量时扩展静默跳过。扩展行为：`agent_start` / `agent_settled` 时上报 `working` / `idle`，`herdr:blocked` 事件上报 `blocked`，`session_start` 时上报会话引用。
+未设置这些变量时 `herdr-agent-state` 扩展静默跳过。`pi-hot-restart` 通过 PATH 调用 `herdr` CLI（`agent list` / `pane process-info` / `pane run`），不依赖上述变量。
 
 ## 参考
 

package/extensions/pi-hot-restart.ts

@@ -0,0 +1,206 @@
+/**
+ * pi-hot-restart
+ *
+ * 提供 `/pi-hot-restart` 命令：批量重启当前 herdr 里的所有 pi 窗口，
+ * 每个窗口重启后恢复到原来的 session。
+ *
+ * 行为约定：
+ * - 跳过 agent_status 为 "working" 的窗口，以及当前发起命令的窗口自身
+ *   （按 `HERDR_PANE_ID` 排除；敲命令时该窗口是 idle，不能只靠状态排除，
+ *   否则会把自己的 pi 进程也 SIGTERM 掉，循环当场中断）。
+ * - 重启前弹确认框，列出将重启的窗口与数量。
+ * - 通过向 pi 前台进程组发 SIGTERM 触发优雅退出（session 落盘），
+ *   退出后用 `herdr pane run` 以 `pi --session <path|id>` 重新拉起。
+ *
+ * 依赖：
+ * - 运行在 herdr 集成环境中（HERDR_ENV=1 等），通过 PATH 调用 `herdr` CLI。
+ * - `herdr agent list` / `herdr pane process-info` / `herdr pane run` 子命令。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { execFile } from "node:child_process";
+
+const HERDR = "herdr";
+
+interface AgentSession {
+	kind: string;
+	value: string;
+}
+
+interface PiAgent {
+	agent: string;
+	agent_status: string;
+	cwd: string;
+	pane_id: string;
+	terminal_title?: string;
+	agent_session?: AgentSession;
+}
+
+interface ForegroundProcess {
+	argv0?: string;
+}
+
+interface ProcInfo {
+	foreground_process_group_id?: number;
+	foreground_processes?: ForegroundProcess[];
+}
+
+interface HerdrListResult {
+	result?: { agents?: PiAgent[] };
+}
+
+interface HerdrProcInfoResult {
+	result?: { process_info?: ProcInfo };
+}
+
+/** 执行 herdr CLI，无论退出码如何都返回 stdout/stderr/code，方便解析错误 JSON。 */
+function runHerdr(args: string[]): Promise<{ stdout: string; stderr: string; code: number }> {
+	return new Promise((resolve) => {
+		execFile(
+			HERDR,
+			args,
+			{ env: process.env, maxBuffer: 64 * 1024 * 1024 },
+			(error, stdout, stderr) => {
+				resolve({
+					stdout: stdout ?? "",
+					stderr: stderr ?? "",
+					code: error ? Number((error as NodeJS.ErrnoException).code ?? 1) : 0,
+				});
+			},
+		);
+	});
+}
+
+async function herdrJson<T>(args: string[]): Promise<T> {
+	const { stdout, stderr, code } = await runHerdr(args);
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch {
+		throw new Error(`herdr ${args.join(" ")} 输出不是 JSON (code=${code}): ${stderr || stdout}`);
+	}
+	if (code !== 0 && typeof parsed === "object" && parsed !== null && "error" in parsed) {
+		throw new Error(`herdr ${args.join(" ")} 失败: ${String((parsed as { error: unknown }).error)}`);
+	}
+	return parsed as T;
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((r) => setTimeout(r, ms));
+}
+
+function shellQuote(s: string): string {
+	return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** 取当前 herdr 中所有已识别的 pi 窗口。 */
+async function listPiAgents(): Promise<PiAgent[]> {
+	const data = await herdrJson<HerdrListResult>(["agent", "list"]);
+	return (data?.result?.agents ?? []).filter((a) => a.agent === "pi");
+}
+
+/** 该 pane 的前台进程组中是否还存在 pi 进程。 */
+async function hasPiForeground(paneId: string): Promise<boolean> {
+	try {
+		const data = await herdrJson<HerdrProcInfoResult>(["pane", "process-info", "--pane", paneId]);
+		const procs = data?.result?.process_info?.foreground_processes ?? [];
+		return procs.some((p) => p.argv0 === "pi");
+	} catch {
+		// 拿不到进程信息时按「已退出」处理，避免卡死等待。
+		return false;
+	}
+}
+
+/** 向前台进程组发 SIGTERM，只杀 pi + 同组子进程，保留 shell。 */
+async function terminatePane(paneId: string): Promise<boolean> {
+	try {
+		const data = await herdrJson<HerdrProcInfoResult>(["pane", "process-info", "--pane", paneId]);
+		const pgid = data?.result?.process_info?.foreground_process_group_id;
+		if (!pgid) return false;
+		process.kill(-pgid, "SIGTERM");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** 轮询等待 pi 真正退出；超时则抛错（避免在旧 pi 仍活着时重启）。 */
+async function waitExit(paneId: string, timeoutMs = 15000): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (!(await hasPiForeground(paneId))) return;
+		await sleep(300);
+	}
+	throw new Error("等待 pi 退出超时");
+}
+
+/** 在 pane 里以原 session 重新拉起 pi。 */
+async function relaunch(agent: PiAgent): Promise<void> {
+	const session = agent.agent_session?.value;
+	if (!session) throw new Error(`pane ${agent.pane_id} 无 session 信息，无法恢复`);
+	const cmd = `cd ${shellQuote(agent.cwd)} && pi --session ${shellQuote(session)}`;
+	const { code, stderr } = await runHerdr(["pane", "run", agent.pane_id, cmd]);
+	if (code !== 0) throw new Error(stderr || `herdr pane run 退出码 ${code}`);
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("pi-hot-restart", {
+		description: "批量重启当前 herdr 里的所有 pi 窗口（跳过 working 与当前窗口），并恢复到原 session",
+		handler: async (_args, ctx) => {
+			let agents: PiAgent[];
+			try {
+				agents = await listPiAgents();
+			} catch (e) {
+				ctx.ui.notify(`获取 pi 窗口失败: ${(e as Error).message}`, "error");
+				return;
+			}
+
+			if (agents.length === 0) {
+				ctx.ui.notify("没有发现 pi 窗口", "info");
+				return;
+			}
+
+			const self = process.env.HERDR_PANE_ID;
+			const targets = agents.filter((a) => a.agent_status !== "working" && a.pane_id !== self);
+			const skipped = agents.filter((a) => a.agent_status === "working" || a.pane_id === self);
+
+			if (targets.length === 0) {
+				ctx.ui.notify(`没有可重启的 pi 窗口（共 ${agents.length} 个，其余为 working 或当前窗口）`, "info");
+				return;
+			}
+
+			const list = targets
+				.map((a) => `  - ${a.terminal_title ?? a.pane_id} (${a.cwd})`)
+				.join("\n");
+			const skipNote = skipped.length ? `\n\n将跳过 ${skipped.length} 个窗口（working 或当前窗口）` : "";
+			const ok = await ctx.ui.confirm(
+				"pi-hot-restart",
+				`将重启 ${targets.length} 个 pi 窗口：\n${list}${skipNote}`,
+			);
+			if (!ok) return;
+
+			let done = 0;
+			const failures: string[] = [];
+			for (const agent of targets) {
+				try {
+					const killed = await terminatePane(agent.pane_id);
+					if (killed) {
+						await waitExit(agent.pane_id);
+					}
+					await sleep(300); // 给 shell 一点时间回到 prompt
+					await relaunch(agent);
+					done++;
+				} catch (e) {
+					failures.push(`${agent.terminal_title ?? agent.pane_id}: ${(e as Error).message}`);
+				}
+			}
+
+			if (failures.length) {
+				ctx.ui.notify(`重启完成 ${done}/${targets.length} 个，失败 ${failures.length} 个`, "warning");
+				ctx.ui.notify(failures.join("\n"), "error");
+			} else {
+				ctx.ui.notify(`已重启 ${done} 个 pi 窗口`, "info");
+			}
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muzi3/herdr",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Herdr for pi: the herdr operate skill (control Herdr from inside a pane), the herdr-guide skill (teach a human to set up and troubleshoot Herdr), and the herdr-agent-state extension (report agent state to Herdr).",
   "keywords": [
     "pi-package",
@@ -20,7 +20,8 @@
   "license": "Apache-2.0",
   "pi": {
     "extensions": [
-      "./extensions"
+      "./extensions/index.ts",
+      "./extensions/pi-hot-restart.ts"
     ],
     "skills": [
       "./skills"

package/skills/herdr-guide/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Herdr Guide"
-  short_description: "Help a human set up, use, and troubleshoot Herdr"