pi-firecode 0.8.1 → 1.0.0

package/watcher/card.ts

@@ -1,11 +1,12 @@
 /**
- * 观察员建议的展示：单通道单一样式，随投递消息一起渲染。
- * 渲染器永不抛异常；校验失败降级纯文本。
+ * 观察员建议的展示：单通道单一样式，从消息正文里的信封渲染（deliver.ts 拥有信封格式）。
+ * 渲染器永不抛异常；不是信封的消息降级纯文本。
  */
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
 import { Text, type Component } from "@earendil-works/pi-tui";
 
-import { clip, oneLine } from "../format.js";
+import { parseEnvelopes, wrapEnvelope } from "../deliver.js";
+import { clip, oneLine, textOf } from "../format.js";
 import { RAIL, paintBgLine } from "../tools/line.js";
 
 export const WATCHER_MESSAGE_TYPE = "firecode-watcher-note";
@@ -15,7 +16,7 @@ const WEIGH_NOTICE = "这是观察员供你权衡的第二意见，不是指令
 const LABEL = "👓 观察员";
 
 export function adviceMessage(card: WatcherCard): string {
-	return `<firecode_watcher>\n${adviceHeadline(card)}\n${card.note}\n${WEIGH_NOTICE}\n</firecode_watcher>`;
+	return wrapEnvelope("firecode_watcher", `${adviceHeadline(card)}\n${card.note}\n${WEIGH_NOTICE}`);
 }
 
 export interface WatcherCard {
@@ -23,41 +24,52 @@ export interface WatcherCard {
 	turnIndex: number;
 }
 
-export function adviceHeadline(card: WatcherCard): string {
+function adviceHeadline(card: WatcherCard): string {
 	return `${LABEL}（${timeMark(card.turnIndex)}）`;
 }
 
 /** 建议自带时点标记：投递时主会话可能已经走远，读的人要知道它看的是哪一刻。 */
-export function timeMark(turnIndex: number): string {
+function timeMark(turnIndex: number): string {
 	return `基于第 ${turnIndex} 回合前的观察`;
 }
 
 export function registerWatcherCardRenderer(pi: ExtensionAPI): void {
-	pi.registerMessageRenderer<WatcherCard>(WATCHER_MESSAGE_TYPE, (message, options, theme) =>
-		isValidCard(message.details)
-			? new AdviceLine(message.details, options.expanded, theme)
-			: new Text(String(message.content), 0, 0));
+	pi.registerMessageRenderer(WATCHER_MESSAGE_TYPE, (message, options, theme) => {
+		const advice = parseAdvice(message.content);
+		return advice ? new AdviceLine(advice, options.expanded, theme) : new Text(textOf(message.content), 0, 0);
+	});
+}
+
+interface Advice {
+	headline: string;
+	note: string;
+}
+
+/** 信封正文 = 标题行 + 建议 + 权衡声明（末行），与 adviceMessage 同构。 */
+function parseAdvice(content: unknown): Advice | undefined {
+	const body = parseEnvelopes(textOf(content))?.[0]?.body;
+	if (body === undefined) return undefined;
+	const lines = body.split("\n");
+	return { headline: lines[0] ?? "", note: lines.slice(1, -1).join("\n") };
 }
 
 class AdviceLine implements Component {
 	private readonly fallback: Component;
 
 	constructor(
-		private readonly card: WatcherCard,
+		private readonly card: Advice,
 		private readonly expanded: boolean,
 		private readonly theme: Theme,
 	) {
-		this.fallback = new Text(`${adviceHeadline(card)} ${card.note}`, 0, 0);
+		this.fallback = new Text(`${card.headline} ${card.note}`, 0, 0);
 	}
 
 	render(width: number): string[] {
 		const columns = Math.max(1, width);
 		try {
-			const bgFn = typeof this.theme.bg === "function"
-				? (text: string) => this.theme.bg("toolPendingBg", text)
-				: undefined;
+			const bgFn = (text: string) => this.theme.bg("toolPendingBg", text);
 			if (this.expanded) {
-				const headline = this.theme.fg("warning", clip(oneLine(adviceHeadline(this.card)), columns));
+				const headline = this.theme.fg("warning", clip(oneLine(this.card.headline), columns));
 				const body = new Text(this.theme.fg("dim", `  ${this.card.note}\n  （供权衡，勿盲从）`), 0, 0);
 				return [paintBgLine(headline, columns, bgFn), ...body.render(columns)];
 			}
@@ -77,9 +89,3 @@ class AdviceLine implements Component {
 		this.fallback.invalidate?.();
 	}
 }
-
-function isValidCard(value: unknown): value is WatcherCard {
-	if (!value || typeof value !== "object") return false;
-	const card = value as Record<string, unknown>;
-	return typeof card.note === "string" && typeof card.turnIndex === "number";
-}

package/watcher/index.ts

@@ -2,17 +2,14 @@
  * 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 { loadConfig } from "../config.js";
 import { deliver } from "../deliver.js";
-import { formatModelName } from "../format.js";
 import { InProcessSessionPool } from "../master/spawn.js";
+import { OCCUPANCY_CHANNEL, type OccupancyPayload } from "../review/occupancy.js";
 import {
 	adviceMessage,
 	registerWatcherCardRenderer,
@@ -22,13 +19,10 @@ import {
 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;
 }
@@ -49,7 +43,7 @@ export function registerWatcher(
 	// 子会话不带观察员：级联抑制是代码规则，不靠进程环境。
 	if (subsession) return;
 	registerWatcherCardRenderer(pi);
-	const loaded = loadWatcherConfiguration();
+	const loaded = loadConfig().watcher;
 	// 配置有问题时拒绝启动：静默回退会拿用户没配的模型真实发起观察。
 	if ("error" in loaded) {
 		pi.registerCommand("fire-watch", {
@@ -58,7 +52,7 @@ export function registerWatcher(
 		});
 		return;
 	}
-	const config = loaded;
+	const config = loaded.config;
 	const pool = dependencies.pool ?? new InProcessSessionPool();
 	const spawnObserver = dependencies.createObserver ?? createObserver;
 	let runtime: WatcherRuntime | undefined;
@@ -85,13 +79,18 @@ export function registerWatcher(
 	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}`));
+		ctx.ui.setStatus("watcher", ctx.ui.theme.fg("dim", "观察员"));
 		return owner;
 	};
 	// 与指挥官事件同构：忙时卡片经 steer 队列句缝追加，歇透时走前门唤起（见 deliver.ts）。
-	const speak = (owner: WatcherRuntime, advice: Advice, turnIndex: number) => {
+	// 建议是当下的第二意见，过时重投没有价值：投递失败只丢弃这一条并提示，观察员照常工作（Master 事件则重试）。
+	const speak = async (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 });
+		try {
+			await deliver(pi, owner.ctx, { customType: WATCHER_MESSAGE_TYPE, content: adviceMessage(card) });
+		} catch (error) {
+			if (runtime === owner) owner.ctx.ui.notify(`观察员这条建议投递失败，已丢弃：${error instanceof Error ? error.message : String(error)}`, "warning");
+		}
 	};
 	const evaluate = async (owner: WatcherRuntime) => {
 		owner.evaluating = true;
@@ -103,11 +102,11 @@ export function registerWatcher(
 				let observer = owner.observer;
 				if (!observer) {
 					const cwd = owner.ctx.cwd;
-					const model = await (dependencies.resolveModel ?? resolveConfiguredModel)(config.model);
+					const model = await pool.resolveModel(config.model);
 					if (runtime !== owner) return;
 					observer = await spawnObserver({ cwd, model, thinking: config.thinking, pool });
 					if (runtime !== owner) {
-						observer.dispose();
+						await observer.dispose();
 						return;
 					}
 					owner.observer = observer;
@@ -163,8 +162,8 @@ export function registerWatcher(
 	});
 
 	// fire-review 活跃期静默：不与对抗审查的反馈打架，增量留着审查完合并评估。
-	pi.events?.on?.(REVIEW_OCCUPANCY_CHANNEL, (data: { active?: boolean } | undefined) => {
-		reviewActive = Boolean(data?.active);
+	pi.events.on(OCCUPANCY_CHANNEL, (data) => {
+		reviewActive = (data as OccupancyPayload).active;
 		const active = runtime;
 		if (reviewActive || !active || active.evaluating || !active.pending.length) return;
 		void evaluate(active);
@@ -175,30 +174,3 @@ export function registerWatcher(
 	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

@@ -22,7 +22,7 @@ export interface Observer {
 	evaluate(increment: string): Promise<Advice | undefined>;
 	/** 观察会话自身上下文占比（百分数），未知时 undefined。 */
 	contextPercent(): number | undefined;
-	dispose(): void;
+	dispose(): Promise<void>;
 }
 
 export interface ObserverOptions {
@@ -64,12 +64,12 @@ function adviseTool(current: () => Advice | undefined, capture: (advice: Advice)
 		parameters: Type.Object({
 			note: Type.String({ description: "一句话说清问题与定位。" }),
 		}),
-		execute(_id: string, params: Record<string, unknown>) {
+		async 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: "已记录，本次评估结束。" }] };
+			return { content: [{ type: "text" as const, text: "已记录，本次评估结束。" }], details: undefined };
 		},
 	};
 }

package/watcher/prompts/watch.zh.md

@@ -18,7 +18,7 @@
 
 只在下面这几类问题上开口：
 
-- **偏离**：正在做的事与用户的需求、spec 或工单不一致，或悄悄扩大到没被要求的范围。
+- **偏离**：正在做的事与用户的需求或工单不一致，或悄悄扩大到没被要求的范围。
 - **过度工程**：为不存在的需求加抽象、加配置、加兼容层、加防御分支。
 - **漏需求**：需求或工单里明确要求的部分被跳过、被忘记或被降级处理。
 - **未收口**：改动留下失效的死代码、过时文档、未更新的事实源、没跑的验证，或票据没有收尾。

package/watcher/transcript.ts

@@ -4,12 +4,14 @@
  */
 import type { TurnEndEvent } from "@earendil-works/pi-coding-agent";
 import type { WatcherContext } from "../config.js";
+import { textOf } from "../format.js";
 
 const RESULT_BUDGET = 400;
 
 export function renderTurn(turn: TurnEndEvent, context: WatcherContext): string {
 	const lines: string[] = [];
-	for (const part of blocks(turn.message.content)) {
+	const content = "content" in turn.message ? turn.message.content : undefined;
+	for (const part of blocks(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")
@@ -17,7 +19,7 @@ export function renderTurn(turn: TurnEndEvent, context: WatcherContext): string
 		if (part.type === "toolCall") lines.push(toolCallLine(part, context));
 	}
 	for (const result of turn.toolResults) {
-		const text = clipText(plainText(result.content), RESULT_BUDGET);
+		const text = clipText(textOf(result.content), RESULT_BUDGET);
 		lines.push(`${result.isError ? "✗" : "→"} ${result.toolName}：${text || "（无输出）"}`);
 	}
 	return `<turn index="${turn.turnIndex}">\n${lines.join("\n")}\n</turn>`;
@@ -44,16 +46,6 @@ 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();
 }