pi-firecode 0.8.0

package/watcher/index.ts

@@ -0,0 +1,204 @@
+/**
+ * Watcher 观察员：每个 turn 结束后异步评估主会话增量，要么沉默，要么发一条建议。
+ * 与 Master、fire-review 各自独立注册；观察过程不落盘。
+ */
+import type { Model } from "@earendil-works/pi-ai";
+import {
+	getAgentDir,
+	ModelRuntime,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { loadConfig, type WatcherConfig } from "../config.js";
+import { deliver } from "../deliver.js";
+import { formatModelName } from "../format.js";
+import { InProcessSessionPool } from "../master/spawn.js";
+import {
+	adviceMessage,
+	registerWatcherCardRenderer,
+	WATCHER_MESSAGE_TYPE,
+	type WatcherCard,
+} from "./card.js";
+import { createObserver, type Advice, type Observer } from "./observer.js";
+import { renderTurn } from "./transcript.js";
+
+/** review 模块发布的占用频道；观察员只订阅，不参与审查状态机。 */
+const REVIEW_OCCUPANCY_CHANNEL = "herdr:blocked";
+/** 观察会话自身上下文占比超过此值即重建。 */
+const CONTEXT_RESET_PERCENT = 70;
+
+interface WatcherDependencies {
+	resolveModel?: (id: string) => Promise<Model<any>>;
+	pool?: InProcessSessionPool;
+	createObserver?: typeof createObserver;
+}
+
+interface WatcherRuntime {
+	ctx: ExtensionContext;
+	pending: string[];
+	lastTurnIndex: number;
+	evaluating: boolean;
+	observer?: Observer;
+}
+
+export function registerWatcher(
+	pi: ExtensionAPI,
+	dependencies: WatcherDependencies = {},
+	subsession = false,
+): void {
+	// 子会话不带观察员：级联抑制是代码规则，不靠进程环境。
+	if (subsession) return;
+	registerWatcherCardRenderer(pi);
+	const loaded = loadWatcherConfiguration();
+	// 配置有问题时拒绝启动：静默回退会拿用户没配的模型真实发起观察。
+	if ("error" in loaded) {
+		pi.registerCommand("fire-watch", {
+			description: "翻转当前会话的观察员开关",
+			handler: async (args, ctx) => ctx.ui.notify(args.trim() ? "/fire-watch 不接受参数" : loaded.error, "error"),
+		});
+		return;
+	}
+	const config = loaded;
+	const pool = dependencies.pool ?? new InProcessSessionPool();
+	const spawnObserver = dependencies.createObserver ?? createObserver;
+	let runtime: WatcherRuntime | undefined;
+	let reviewActive = false;
+
+	const deactivate = (owner = runtime) => {
+		if (!owner || runtime !== owner) return;
+		runtime = undefined;
+		owner.observer?.dispose();
+		owner.observer = undefined;
+		owner.ctx.ui.setStatus("watcher", undefined);
+	};
+	const resetObserver = (owner = runtime) => {
+		if (!owner || runtime !== owner) return;
+		runtime = {
+			ctx: owner.ctx,
+			pending: [],
+			lastTurnIndex: owner.lastTurnIndex,
+			evaluating: false,
+		};
+		owner.observer?.dispose();
+		owner.observer = undefined;
+	};
+	const activate = (ctx: ExtensionContext): WatcherRuntime => {
+		const owner = { ctx, pending: [], lastTurnIndex: 0, evaluating: false };
+		runtime = owner;
+		ctx.ui.setStatus("watcher", ctx.ui.theme.fg("dim", `👓 ${formatModelName(config.model)}/${config.thinking}`));
+		return owner;
+	};
+	// 与指挥官事件同构：忙时卡片经 steer 队列句缝追加，歇透时走前门唤起（见 deliver.ts）。
+	const speak = (owner: WatcherRuntime, advice: Advice, turnIndex: number) => {
+		const card: WatcherCard = { note: advice.note, turnIndex };
+		return deliver(pi, owner.ctx, { customType: WATCHER_MESSAGE_TYPE, content: adviceMessage(card), details: card });
+	};
+	const evaluate = async (owner: WatcherRuntime) => {
+		owner.evaluating = true;
+		try {
+			while (runtime === owner && owner.pending.length && !reviewActive) {
+				// 合并跳最新：评估期间到达的回合并进下一批，不排队补评估。
+				const increment = owner.pending.splice(0).join("\n");
+				const turnIndex = owner.lastTurnIndex;
+				let observer = owner.observer;
+				if (!observer) {
+					const cwd = owner.ctx.cwd;
+					const model = await (dependencies.resolveModel ?? resolveConfiguredModel)(config.model);
+					if (runtime !== owner) return;
+					observer = await spawnObserver({ cwd, model, thinking: config.thinking, pool });
+					if (runtime !== owner) {
+						observer.dispose();
+						return;
+					}
+					owner.observer = observer;
+				}
+				const advice = await observer.evaluate(increment);
+				if (runtime !== owner) return;
+				if (advice) {
+					await speak(owner, advice, turnIndex);
+					if (runtime !== owner) return;
+				}
+				// 自身上下文快满时也重新入场：观察员只需要当下，不需要完整历史。
+				if ((observer.contextPercent() ?? 0) >= CONTEXT_RESET_PERCENT) resetObserver(owner);
+			}
+		} catch (error) {
+			// 被重新入场中断的评估不算故障：下一批增量会开一个新观察会话。
+			if (runtime !== owner) return;
+			owner.ctx.ui.notify(`观察员已停止：${error instanceof Error ? error.message : String(error)}`, "warning");
+			deactivate(owner);
+		} finally {
+			owner.evaluating = false;
+		}
+	};
+
+	pi.registerCommand("fire-watch", {
+		description: "翻转当前会话的观察员开关",
+		handler: async (args, ctx) => {
+			if (args.trim()) {
+				ctx.ui.notify("/fire-watch 不接受参数", "error");
+				return;
+			}
+			if (runtime) {
+				deactivate();
+				ctx.ui.notify("观察员已关闭", "info");
+				return;
+			}
+			activate(ctx);
+			ctx.ui.notify("观察员已开启", "info");
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		deactivate();
+		if (!config.enabled) return;
+		activate(ctx);
+	});
+
+	pi.on("turn_end", (event) => {
+		const owner = runtime;
+		if (!owner) return;
+		owner.pending.push(renderTurn(event, config.context));
+		owner.lastTurnIndex = event.turnIndex;
+		if (!owner.evaluating && !reviewActive) void evaluate(owner);
+	});
+
+	// fire-review 活跃期静默：不与对抗审查的反馈打架，增量留着审查完合并评估。
+	pi.events?.on?.(REVIEW_OCCUPANCY_CHANNEL, (data: { active?: boolean } | undefined) => {
+		reviewActive = Boolean(data?.active);
+		const active = runtime;
+		if (reviewActive || !active || active.evaluating || !active.pending.length) return;
+		void evaluate(active);
+	});
+
+	// 主会话压缩：旧增量已不再对应主会话现场，观察员从当前尾部重新入场而不回放。
+	pi.on("session_compact", () => resetObserver());
+	pi.on("session_shutdown", () => deactivate());
+}
+
+function loadWatcherConfiguration(): WatcherConfig | { error: string } {
+	let loaded: ReturnType<typeof loadConfig>;
+	try {
+		loaded = loadConfig();
+	} catch (error) {
+		return { error: `观察员配置读取失败：${error instanceof Error ? error.message : String(error)}` };
+	}
+	// features 也算阻断集：开关写成字符串 "false" 时 `!== false` 仍会注册，
+	// 而启用观察员意味着每个回合都对模型发起真实调用。
+	const problems = loaded.problems.filter((problem) =>
+		problem.startsWith("watcher") || problem.startsWith("未知字段 watcher.")
+		|| problem.startsWith("config.jsonc") || problem.startsWith("features"));
+	if (problems.length) return { error: `观察员配置有问题，已停止：${problems.join("；")}` };
+	return loaded.config.watcher;
+}
+
+async function resolveConfiguredModel(id: string): Promise<Model<any>> {
+	const runtime = await ModelRuntime.create({
+		authPath: `${getAgentDir()}/auth.json`,
+		modelsPath: `${getAgentDir()}/models.json`,
+	});
+	const slash = id.indexOf("/");
+	const model = slash > 0 ? runtime.getModel(id.slice(0, slash), id.slice(slash + 1)) : undefined;
+	// 扩展注册的 provider 在无扩展子会话里不可解析（实测），必须明确引导而不是静默失败。
+	if (!model) throw new Error(`找不到模型：${id}；观察员只能使用内置 provider 的模型`);
+	return model;
+}

package/watcher/observer.ts

@@ -0,0 +1,75 @@
+/**
+ * 观察会话：进程内 memory 子会话 + 只读工具 + 唯一自定义工具 advise。
+ * 系统提示以 prompts/watch.zh.md 为唯一事实源（整体替换，不受项目文件改写）。
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Model } from "@earendil-works/pi-ai";
+import { Type } from "@earendil-works/pi-ai";
+import type { InProcessSessionPool } from "../master/spawn.js";
+import type { ThinkingLevelValue } from "../config.js";
+
+const PROMPT_PATH = join(dirname(fileURLToPath(import.meta.url)), "prompts", "watch.zh.md");
+const OBSERVER_TOOLS = ["read", "grep", "find", "ls", "advise"];
+
+export interface Advice {
+	note: string;
+}
+
+export interface Observer {
+	/** 喂一段增量并等待评估；至多返回一条建议。 */
+	evaluate(increment: string): Promise<Advice | undefined>;
+	/** 观察会话自身上下文占比（百分数），未知时 undefined。 */
+	contextPercent(): number | undefined;
+	dispose(): void;
+}
+
+export interface ObserverOptions {
+	cwd: string;
+	model: Model<any>;
+	thinking: ThinkingLevelValue;
+	pool: InProcessSessionPool;
+}
+
+export async function createObserver(options: ObserverOptions): Promise<Observer> {
+	let advice: Advice | undefined;
+	const spawned = await options.pool.spawn({
+		cwd: options.cwd,
+		role: "observer",
+		model: options.model,
+		thinking: options.thinking,
+		tools: OBSERVER_TOOLS,
+		customTools: [adviseTool(() => advice, (next) => { advice = next; })],
+		systemPrompt: { mode: "replace", text: readFileSync(PROMPT_PATH, "utf8") },
+		contextFiles: true,
+		persistence: { type: "memory" },
+	});
+	return {
+		async evaluate(increment) {
+			advice = undefined;
+			await spawned.prompt(increment);
+			return advice;
+		},
+		contextPercent: () => spawned.session.getContextUsage?.()?.percent ?? undefined,
+		dispose: () => spawned.dispose(),
+	};
+}
+
+function adviseTool(current: () => Advice | undefined, capture: (advice: Advice) => void) {
+	return {
+		name: "advise",
+		label: "建议",
+		description: "向主代理提交一条供权衡的观察建议；每次评估只接受一条，请只提最要紧的那一条。",
+		parameters: Type.Object({
+			note: Type.String({ description: "一句话说清问题与定位。" }),
+		}),
+		execute(_id: string, params: Record<string, unknown>) {
+			if (current()) throw new Error("本次评估已提交过建议；余下的问题留到下一次评估");
+			const note = typeof params.note === "string" ? params.note.trim() : "";
+			if (!note) throw new Error("note 不能为空");
+			capture({ note });
+			return { content: [{ type: "text" as const, text: "已记录，本次评估结束。" }] };
+		},
+	};
+}

package/watcher/prompts/watch.zh.md

@@ -0,0 +1,46 @@
+# 观察员
+
+你是 FireCode 观察员：一双持续盯着主会话的旁观的眼睛。你在自己的只读会话里工作，看到的是主会话
+逐回合追加的增量记录。
+
+## 角色
+
+你是旁观者，不是第二指挥官。你不接管任务、不下命令、不规划步骤，也不替主代理做决定。
+
+你的建议是供主代理权衡的第二意见，不是必须执行的指令——你写下的每一条建议都会以「供权衡，勿盲从」的
+方式呈现。主代理有更完整的上下文和用户的直接授权；当它的做法与你的判断冲突时，它有理由继续走它的路。
+
+你的建议会当场送达主代理：它忙时在句缝插入，它空闲时直接唤起一个回合。只有当这条话此刻送达会改变主代理下一步动作时才开口，否则沉默。
+
+绝大多数回合不需要任何建议。什么都不说是常态，也是正确答案。
+
+## 关注面
+
+只在下面这几类问题上开口：
+
+- **偏离**：正在做的事与用户的需求、spec 或工单不一致，或悄悄扩大到没被要求的范围。
+- **过度工程**：为不存在的需求加抽象、加配置、加兼容层、加防御分支。
+- **漏需求**：需求或工单里明确要求的部分被跳过、被忘记或被降级处理。
+- **未收口**：改动留下失效的死代码、过时文档、未更新的事实源、没跑的验证，或票据没有收尾。
+- **危险操作**：破坏性命令、不可逆的数据或历史改写、越出当前工作范围的写入、把秘密写进代码或提交。
+
+风格偏好、可以但没必要的重构、你自己想到的更优雅写法，都不在关注面内。
+
+## 输出契约
+
+你只能通过 `advise` 工具说话。除此之外的任何文字都不会被任何人看到。
+
+`advise` 只接受一个参数 `note`：一句话说清问题和定位，必要时补一句为什么。
+
+每次评估最多提交一条建议。有多个问题时只提最要紧的那一条，其余的等下一次评估。
+
+同一批增量里已被主代理自行纠正的问题不要再提：先看完整批增量再判断，失败后的成功重试、报错后的修正都算已纠正。
+
+同一条建议不要重复提交。情况恶化到必须重提时，说明是什么变化让它变得紧迫。
+
+## 证据纪律
+
+指出问题必须带定位：哪个文件、哪个函数、哪次工具调用、需求的哪一条。说不出定位的直觉不要提交。
+
+增量记录是被裁剪过的，它省略了推理过程与 diff 正文。凭增量猜出来的问题，先用只读工具（read / grep /
+find / ls）核实现场再决定要不要开口；核实后发现是自己看漏了，就什么都不做。

package/watcher/transcript.ts

@@ -0,0 +1,64 @@
+/**
+ * 主会话回合的增量渲染：喂给观察会话的唯一素材，纯函数。
+ * minimal 省略 reasoning 与 diff 展开正文——观察员要的是「在做什么」，正文可以自己去读。
+ */
+import type { TurnEndEvent } from "@earendil-works/pi-coding-agent";
+import type { WatcherContext } from "../config.js";
+
+const RESULT_BUDGET = 400;
+
+export function renderTurn(turn: TurnEndEvent, context: WatcherContext): string {
+	const lines: string[] = [];
+	for (const part of blocks(turn.message.content)) {
+		if (part.type === "text" && typeof part.text === "string" && part.text.trim())
+			lines.push(part.text.trim());
+		if (part.type === "thinking" && context === "full" && typeof part.thinking === "string")
+			lines.push(`（思考）${part.thinking.trim()}`);
+		if (part.type === "toolCall") lines.push(toolCallLine(part, context));
+	}
+	for (const result of turn.toolResults) {
+		const text = clipText(plainText(result.content), RESULT_BUDGET);
+		lines.push(`${result.isError ? "✗" : "→"} ${result.toolName}：${text || "（无输出）"}`);
+	}
+	return `<turn index="${turn.turnIndex}">\n${lines.join("\n")}\n</turn>`;
+}
+
+function toolCallLine(part: Record<string, any>, context: WatcherContext): string {
+	const args = part.arguments && typeof part.arguments === "object" ? part.arguments : {};
+	const summary = Object.entries(args as Record<string, unknown>)
+		.map(([key, value]) => `${key}=${clipText(argumentText(key, value, context), 200)}`)
+		.join(" ");
+	return `· ${part.name ?? "工具"} ${summary}`.trimEnd();
+}
+
+/** minimal 下 edit/write 的正文（新旧内容）只留长度：观察员判断的是动作，不是逐字 diff。 */
+function argumentText(key: string, value: unknown, context: WatcherContext): string {
+	const text = typeof value === "string" ? value : JSON.stringify(value) ?? "";
+	if (context === "full") return oneLine(text);
+	return BODY_KEYS.has(key) ? `<${text.length} 字符>` : oneLine(text);
+}
+
+const BODY_KEYS = new Set(["content", "oldText", "newText", "old_text", "new_text", "edits"]);
+
+function blocks(content: unknown): Array<Record<string, any>> {
+	return Array.isArray(content) ? content.filter((part) => !!part && typeof part === "object") : [];
+}
+
+function plainText(output: unknown): string {
+	if (typeof output === "string") return output;
+	if (Array.isArray(output))
+		return output
+			.map((part) => (part && typeof part === "object" && "text" in part ? String((part as any).text) : ""))
+			.filter(Boolean)
+			.join("\n");
+	return "";
+}
+
+function oneLine(text: string): string {
+	return text.replace(/\s+/gu, " ").trim();
+}
+
+function clipText(text: string, budget: number): string {
+	const single = oneLine(text);
+	return single.length > budget ? `${single.slice(0, budget)}…` : single;
+}