@master.g/pi-wingman 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 master-g
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# pi-wingman
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[pi](https://github.com/earendil-works/pi) 的僚机扩展：主 agent 干活时替你把关、参谋、想下一步。
+
+三个功能（均可独立开关，模型各自可配）：
+
+| 功能 | 参照 | 说明 |
+|---|---|---|
+| **heads-up** | — | 主 agent 工作时后台自动审计，提前发现潜在问题，notify + widget 告警给用户（只读旁路，不阻塞、不注入） |
+| **advisor** | oh-my-pi advisor | 指定一个模型当顾问，读主 agent 的每个 turn，以 steer 消息内联注入便签（aside / concern / blocker）让主 agent 纠偏 |
+| **hint** | Claude Code prompt suggestions | 任务结束后按上下文与目标生成下一步 prompt，输入框 ghost text 呈现：Tab 填入、Enter 直接发送 |
+
+> 状态：骨架（v0.0.1）。命令与配置已可用；三个控制器按 M1 hint → M2 advisor → M3 heads-up 接入。
+
+## 安装
+
+```bash
+pi install npm:@master.g/pi-wingman
+```
+
+开发中本地加载：
+
+```bash
+pi --extension ~/github/pi-wingman/index.ts
+```
+
+## 命令
+
+- `/wingman` — 查看三个功能的状态与模型
+- `/advisor`、`/hint`、`/headsup` — 各接 `<provider/model>`（开启并设模型，模型须存在）、`on` / `off`（开关，保留已设模型）、无参（看状态）；参数支持补全
+- `/ask-advisor <问题>` — 就当前上下文咨询顾问模型，回答注入对话
+
+## 配置
+
+`<agentDir>/wingman.json`（默认 `~/.pi/agent/wingman.json`），由命令自动写入，也可手改：
+
+```json
+{
+	"headsup": { "enabled": false },
+	"advisor": { "enabled": true, "model": "openai-codex/gpt-5.5" },
+	"hint": { "enabled": false }
+}
+```
+
+三个功能默认都关闭：每个功能都会额外调用模型，需要用户自己开启。模型形如 `provider/model-id`；hint 没配模型时用当前模型（`/hint on`），advisor/heads-up 必须配模型才会激活。
+
+## License
+
+MIT

package/advisor.ts

@@ -0,0 +1,161 @@
+/**
+ * advisor.ts — 用户指定模型的顾问(参照 oh-my-pi advisor)。
+ *
+ * 每个 turn_end 把该 turn 摘要交给后台审计(不 await,不拖住主 agent);
+ * 冷却或在途时摘要先累积,下一个 turn 一起审。返回 note/concern/blocker
+ * 时 notify 用户;agent 仍在运行才以 pi.sendUserMessage(note, { deliverAs:
+ * "steer" }) 注入纠偏,已 idle 则只提示(顾问不自行唤醒 agent)。注入消息
+ * 以 ADVISOR_MARKER 打标:响应旁注的 turn 不再审计(防循环),index.ts
+ * 记录用户目标时也跳过带标记的 prompt(防污染)。
+ *
+ * 另提供 /ask-advisor <问题> 手动咨询当前上下文:答案同样以 steer 注入
+ * 主会话。手动咨询失败时向用户报错;自动审计走静默降级。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Auditor, buildDigest, type DigestMessage, type VerdictLevel } from "./audit.js";
+import type { WingmanConfig } from "./config.js";
+import { completeText, messageText, resolveModel, type AnyModel, type ModelRegistry } from "./llm.js";
+
+/** 注入消息的打标前缀;审计 prompt 也告诉审计员忽略带此标记的内容。 */
+export const ADVISOR_MARKER = "[wingman advisor";
+
+export function isAdvisorNote(text: string): boolean {
+	return text.startsWith(ADVISOR_MARKER);
+}
+
+export function formatAdvisorNote(verdict: { level: VerdictLevel; summary: string }): string {
+	return `${ADVISOR_MARKER} · 旁注,非用户消息,仅供参考] ${verdict.level}: ${verdict.summary}`;
+}
+
+/**
+ * 防循环:注入的旁注以 user 消息进入 transcript。message_end 见到带标记的
+ * user 消息就记下,随后那个 turn_end(响应旁注的 turn)跳过审计。按注入
+ * 文本识别,不依赖后台审计与 turn 的时序。
+ */
+export class AdvisorState {
+	private skipNextTurnAudit = false;
+
+	onUserMessage(text: string): void {
+		if (isAdvisorNote(text)) this.skipNextTurnAudit = true;
+	}
+
+	/** turn_end 到达时调用:true = 本次应审计;false = 跳过并消费跳过量。 */
+	shouldAuditTurn(): boolean {
+		if (this.skipNextTurnAudit) {
+			this.skipNextTurnAudit = false;
+			return false;
+		}
+		return true;
+	}
+}
+
+const ASK_SYSTEM_PROMPT = `你是资深编程顾问,在旁观察一个编程 agent 的工作。给你用户的目标和 agent 近期动作摘要,以及用户现在问你的问题。直接回答问题本身,简洁具体,≤300 字,用中文。`;
+
+const NOTIFY_TYPE: Record<Exclude<VerdictLevel, "ok">, "info" | "warning" | "error"> = {
+	note: "info",
+	concern: "warning",
+	blocker: "error",
+};
+
+/** 冷却期内最多累积几个 turn 的摘要,超出丢最旧的。 */
+const MAX_PENDING_TURNS = 3;
+
+export function installAdvisor(pi: ExtensionAPI, getConfig: () => WingmanConfig, getGoal: () => string): void {
+	const auditor = new Auditor({ minIntervalMs: 60_000 });
+	const shutdown = new AbortController();
+	const state = new AdvisorState();
+	let pendingDigests: string[] = [];
+
+	const audit = async (ctx: ExtensionContext, registry: ModelRegistry, model: AnyModel, digest: string) => {
+		const verdict = await auditor.run(
+			registry,
+			model,
+			{ goal: getGoal(), digest },
+			{ timeoutMs: 15_000, signal: shutdown.signal },
+		);
+		if (!verdict || verdict.level === "ok") return;
+		ctx.ui.notify(`advisor [${verdict.level}] ${verdict.summary}`, NOTIFY_TYPE[verdict.level]);
+		if (ctx.isIdle()) return; // 裁决迟到:agent 已停,只提示用户,不注入
+		pi.sendUserMessage(formatAdvisorNote(verdict), { deliverAs: "steer" });
+	};
+
+	pi.on("message_end", (event) => {
+		if (event.message.role === "user") state.onUserMessage(messageText(event.message));
+	});
+
+	pi.on("turn_end", (event, ctx) => {
+		const config = getConfig().advisor;
+		// advisor 必须显式配置模型才激活(开启必经 /advisor <model>);
+		// 未设或拼错模型都不回退当前模型,避免双份成本。
+		if (!config.enabled || !config.model) return;
+		if (!state.shouldAuditTurn()) return;
+		const model = resolveModel(ctx.modelRegistry, config.model, undefined);
+		if (!model) return;
+
+		const digest = buildDigest([event.message, ...event.toolResults] as DigestMessage[]);
+		if (!digest.trim()) return;
+		pendingDigests = [...pendingDigests, digest].slice(-MAX_PENDING_TURNS);
+		if (!auditor.ready) return; // 冷却或在途:摘要留到下一个 turn 一起审
+		const batch = pendingDigests.join("\n");
+		pendingDigests = [];
+		// 后台执行已在 runner 的 try/catch 之外,自己兜底(会话替换后 UI 调用可能抛)
+		audit(ctx, ctx.modelRegistry, model, batch).catch(() => {});
+	});
+
+	pi.registerCommand("ask-advisor", {
+		description: "Ask the advisor model about current context: /ask-advisor <question>",
+		handler: async (args, ctx) => {
+			const config = getConfig().advisor;
+			if (!config.enabled || !config.model) {
+				ctx.ui.notify("advisor 未启用,先 /advisor <provider/model> 配置", "error");
+				return;
+			}
+			const question = args.trim();
+			if (!question) {
+				ctx.ui.notify("用法:/ask-advisor <问题>", "info");
+				return;
+			}
+			const model = resolveModel(ctx.modelRegistry, config.model, undefined);
+			if (!model) {
+				ctx.ui.notify(`advisor 模型无法解析:${config.model}`, "error");
+				return;
+			}
+
+			const recent = ctx.sessionManager
+				.getBranch()
+				.filter((entry) => entry.type === "message")
+				.slice(-10)
+				.map((entry) => (entry as { message: unknown }).message as DigestMessage);
+			const digest = buildDigest(recent);
+			const goal = getGoal() ? `用户目标:${getGoal()}\n\n` : "";
+			const result = await completeText(
+				ctx.modelRegistry,
+				model,
+				{
+					systemPrompt: ASK_SYSTEM_PROMPT,
+					messages: [
+						{
+							role: "user",
+							content: [
+								{ type: "text", text: `${goal}近期动作:\n${digest || "(暂无)"}\n\n顾问问题:${question}` },
+							],
+							timestamp: Date.now(),
+						},
+					],
+				},
+				{ timeoutMs: 30_000, signal: shutdown.signal },
+			);
+			if (!result.ok) {
+				ctx.ui.notify(`advisor 调用失败:${result.reason}`, "error");
+				return;
+			}
+			pi.sendUserMessage(`${ADVISOR_MARKER} · 问答] 问:${question}\n答:${result.text}`, { deliverAs: "steer" });
+			ctx.ui.notify("顾问回答已注入对话", "info");
+		},
+	});
+
+	pi.on("session_shutdown", () => {
+		shutdown.abort();
+	});
+}

package/audit.ts

@@ -0,0 +1,151 @@
+/**
+ * audit.ts — heads-up 与 advisor 共享的审计管线。
+ *
+ * 输入:用户目标(before_agent_start 的 prompt)+ 近期动作 digest;
+ * 输出:Verdict(ok/note/concern/blocker + 一句话)。heads-up 与 advisor
+ * 只差输出通道,审计逻辑复用同一份。
+ *
+ * Auditor 带冷却与互斥:并发只放行一个,冷却期内直接跳过(返回
+ * undefined);失败一律静默(返回 undefined),不抛进 pi 事件循环。
+ */
+
+import { completeText, messageText, type AnyModel, type Message, type ModelRegistry } from "./llm.js";
+
+export type VerdictLevel = "ok" | "note" | "concern" | "blocker";
+
+export interface Verdict {
+	level: VerdictLevel;
+	/** 一句话说明,给用户或主 agent 看 */
+	summary: string;
+	/** 展开要点(heads-up 展开态用;仅 concern/blocker 时审计模型才会给) */
+	details: string[];
+}
+
+export type DigestMessage = Message;
+
+export interface DigestOptions {
+	maxMessages?: number;
+	perMessageChars?: number;
+}
+
+const AUDIT_SYSTEM_PROMPT = `你是编程 agent 的旁路审计员。给你用户的目标和 agent 近期动作摘要,判断 agent 是否走在正确的路上。
+
+只输出如下格式,不要任何其他内容:
+VERDICT: <ok|note|concern|blocker>
+SUMMARY: <一句话,≤120 字符,用中文>
+DETAILS:(仅 concern/blocker 时输出此块,最多 4 条要点,每条一行以 "- " 开头,各 ≤100 字符,说明判断依据与建议;ok/note 时不要输出此块)
+
+级别含义:
+- blocker:正在犯错且会造成实质损失(破坏数据、违背用户目标、在错误的方向上大量返工),必须立即纠偏
+- concern:方向可疑或明显浪费(改错文件、绕过而非修复、重复无效尝试),值得提醒
+- note:方向正确,但有一个可选的改进建议
+- ok:一切正常,无话可说
+
+宁缺毋滥:不确定时选 ok。带 [wingman advisor 标记的消息是顾问自己之前的旁注,不要评论它。`;
+
+/** 把近期消息压成审计用摘要:role 前缀 + 截断正文 + 工具调用/结果行。 */
+export function buildDigest(messages: DigestMessage[], options: DigestOptions = {}): string {
+	const { maxMessages = 12, perMessageChars = 300 } = options;
+	const lines: string[] = [];
+	for (const message of messages.slice(-maxMessages)) {
+		const text = messageText(message).slice(0, perMessageChars);
+		if (message.role === "toolResult") {
+			const error = message.isError ? " ERROR" : "";
+			lines.push(`[toolResult ${message.toolName}]${error} ${text}`.trimEnd());
+			continue;
+		}
+		const calls =
+			message.role === "assistant"
+				? message.content
+						.filter((c) => c.type === "toolCall")
+						.map((c) => `→ ${c.name}(${JSON.stringify(c.arguments ?? {}).slice(0, 120)})`)
+						.join(" ")
+				: "";
+		lines.push(`[${message.role}] ${text}${text && calls ? " " : ""}${calls}`.trimEnd());
+	}
+	return lines.join("\n");
+}
+
+/** 解析审计模型的输出;没有 VERDICT 行视为无效。 */
+export function parseVerdict(text: string): Verdict | undefined {
+	const verdict = text.match(/verdict:\s*(ok|note|concern|blocker)/i);
+	if (!verdict) return undefined;
+	const summary = text.match(/summary:\s*(.+)/i);
+	const detailsMatch = text.match(/details:\s*\n((?:^[ \t]*-[ \t].*\n?)+)/im);
+	const details = detailsMatch
+		? detailsMatch[1]
+				.split("\n")
+				.map((line) => line.replace(/^[ \t]*-[ \t]*/, "").trim())
+				.filter((line) => line.length > 0)
+				.slice(0, 4)
+				.map((line) => line.slice(0, 200))
+		: [];
+	return {
+		level: verdict[1].toLowerCase() as VerdictLevel,
+		summary: (summary?.[1] ?? "").trim().slice(0, 200),
+		details,
+	};
+}
+
+/** 无守卫的单次审计;冷却互斥由 Auditor 负责。 */
+export async function runAudit(
+	registry: ModelRegistry,
+	model: AnyModel,
+	input: { goal: string; digest: string },
+	options: { timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<Verdict | undefined> {
+	const goal = input.goal ? `用户目标:${input.goal}\n\n` : "";
+	const result = await completeText(
+		registry,
+		model,
+		{
+			systemPrompt: AUDIT_SYSTEM_PROMPT,
+			messages: [
+				{
+					role: "user",
+					content: [{ type: "text", text: `${goal}近期动作:\n${input.digest}` }],
+					timestamp: Date.now(),
+				},
+			],
+		},
+		{ timeoutMs: options.timeoutMs ?? 15_000, signal: options.signal },
+	);
+	if (!result.ok) return undefined;
+	return parseVerdict(result.text);
+}
+
+/** 冷却 + 互斥的审计器:advisor(turn_end)与 heads-up(去抖)共用一个实例各管各的。 */
+export class Auditor {
+	private inFlight = false;
+	private lastRunAt = Number.NEGATIVE_INFINITY;
+	private readonly minIntervalMs: number;
+	private readonly now: () => number;
+
+	constructor(options: { minIntervalMs?: number; now?: () => number } = {}) {
+		this.minIntervalMs = options.minIntervalMs ?? 60_000;
+		this.now = options.now ?? Date.now;
+	}
+
+	/** 此刻 run 会放行:不在途且已过冷却。调用方据此决定是否先消费累积的输入。 */
+	get ready(): boolean {
+		return !this.inFlight && this.now() - this.lastRunAt >= this.minIntervalMs;
+	}
+
+	async run(
+		registry: ModelRegistry,
+		model: AnyModel,
+		input: { goal: string; digest: string },
+		options: { timeoutMs?: number; signal?: AbortSignal } = {},
+	): Promise<Verdict | undefined> {
+		if (!this.ready) return undefined;
+		this.inFlight = true;
+		this.lastRunAt = this.now();
+		try {
+			return await runAudit(registry, model, input, options);
+		} catch {
+			return undefined; // 静默降级
+		} finally {
+			this.inFlight = false;
+		}
+	}
+}

package/config.ts

@@ -0,0 +1,86 @@
+/**
+ * config.ts — wingman 配置：读写 <agentDir>/wingman.json（默认 ~/.pi/agent）。
+ *
+ * 三个功能各自独立开关，默认全关（旁路调用都有成本，须用户显式开启）；
+ * 模型形如 "provider/model-id"。未配置模型时各模块自行回退：hint 用当前
+ * 模型，advisor/heads-up 保持关闭。
+ */
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface FeatureConfig {
+	enabled: boolean;
+	model?: string;
+}
+
+export interface WingmanConfig {
+	headsup: FeatureConfig;
+	advisor: FeatureConfig;
+	hint: FeatureConfig;
+}
+
+export const DEFAULT_CONFIG: WingmanConfig = {
+	headsup: { enabled: false },
+	advisor: { enabled: false },
+	hint: { enabled: false },
+};
+
+export function configPath(): string {
+	return join(getAgentDir(), "wingman.json");
+}
+
+function mergeFeature(base: FeatureConfig, override: unknown): FeatureConfig {
+	if (typeof override !== "object" || override === null) return { ...base };
+	const o = override as Partial<FeatureConfig>;
+	return {
+		enabled: typeof o.enabled === "boolean" ? o.enabled : base.enabled,
+		model: typeof o.model === "string" ? o.model : base.model,
+	};
+}
+
+export function loadConfig(path: string = configPath()): WingmanConfig {
+	let raw: Partial<Record<keyof WingmanConfig, unknown>> = {};
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof parsed === "object" && parsed !== null) raw = parsed;
+	} catch {
+		// 文件不存在或损坏时回退默认配置
+	}
+	return {
+		headsup: mergeFeature(DEFAULT_CONFIG.headsup, raw.headsup),
+		advisor: mergeFeature(DEFAULT_CONFIG.advisor, raw.advisor),
+		hint: mergeFeature(DEFAULT_CONFIG.hint, raw.hint),
+	};
+}
+
+export function saveConfig(config: WingmanConfig, path: string = configPath()): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(config, null, "\t") + "\n");
+}
+
+/** 状态行:"hint: on (provider/model)" / "hint: on (current model)" / "hint: off"。 */
+export function featureLine(name: string, feature: FeatureConfig): string {
+	const state = feature.enabled ? `on (${feature.model ?? "current model"})` : "off";
+	return `${name}: ${state}`;
+}
+
+/**
+ * 应用配置命令参数:"off" 关闭、"on" 重新开启(都保留已设模型),
+ * "provider/model" 开启并设模型,空参只读。返回状态行;模型校验、
+ * saveConfig 与后续副作用(如编辑器同步)由调用方负责。
+ */
+export function applyFeatureArg(
+	config: WingmanConfig,
+	feature: keyof WingmanConfig,
+	arg: string,
+): string {
+	const value = arg.trim();
+	if (value === "off" || value === "on") {
+		config[feature] = { ...config[feature], enabled: value === "on" };
+	} else if (value) {
+		config[feature] = { enabled: true, model: value };
+	}
+	return featureLine(feature, config[feature]);
+}

package/editor.ts

@@ -0,0 +1,113 @@
+/**
+ * editor.ts — WingmanEditor 与其安装管理(EditorManager)。
+ *
+ * WingmanEditor 是全扩展唯一的 CustomEditor(setEditorComponent 全局只能装
+ * 一个):hint 用 ghost 行(M1),heads-up 用数字键捕获(M3)。安装条件是
+ * hint.enabled || headsup.enabled;session_start 与配置命令变更后各 sync
+ * 一次,条件不变不动(避免重建丢掉 pendingHint)。
+ */
+
+import { CustomEditor, type ExtensionContext, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { getKeybindings, truncateToWidth, type EditorTheme, type TUI } from "@earendil-works/pi-tui";
+import type { WingmanConfig } from "./config.js";
+
+export class WingmanEditor extends CustomEditor {
+	private pendingHint: string | undefined;
+	/** heads-up 数字键处理器,返回 true 表示消费;仅编辑器为空时被调用。 */
+	onHeadsUpKey?: (key: "0" | "1" | "2") => boolean;
+
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		keybindings: KeybindingsManager,
+		private readonly activeTui: { current: TUI | undefined },
+	) {
+		super(tui, theme, keybindings);
+	}
+
+	setHint(hint: string | undefined): void {
+		this.pendingHint = hint;
+		this.activeTui.current?.requestRender();
+	}
+
+	render(width: number): string[] {
+		const lines = super.render(width);
+		if (!this.pendingHint || this.getText().length > 0 || lines.length < 2) return lines;
+		// shortcut: ghost 渲染为输入行下方新增一行;如需与输入行内联覆盖再升级。
+		const ghost = truncateToWidth(`\x1b[2m  💡 ${this.pendingHint}\x1b[0m`, width);
+		lines.splice(lines.length - 1, 0, ghost);
+		return lines;
+	}
+
+	handleInput(data: string): void {
+		if (
+			this.getText().length === 0 &&
+			(data === "0" || data === "1" || data === "2") &&
+			this.onHeadsUpKey?.(data)
+		) {
+			return; // heads-up 消费了数字键
+		}
+		if (this.pendingHint) {
+			// 与基类编辑器同一套键位判断:兼容 kitty 协议与用户自定义键位
+			const kb = getKeybindings();
+			if (kb.matches(data, "tui.input.tab")) {
+				// Tab:填入可编辑,吞掉 Tab 防触发补全
+				const hint = this.pendingHint;
+				this.pendingHint = undefined;
+				this.setText(hint);
+				return;
+			}
+			if (kb.matches(data, "tui.input.submit")) {
+				// 提交键:填入后把同一按键交给基类走提交路径
+				const hint = this.pendingHint;
+				this.pendingHint = undefined;
+				this.setText(hint);
+				super.handleInput(data);
+				return;
+			}
+			// 其他任意按键:清除 hint,按键照常转发
+			this.pendingHint = undefined;
+		}
+		super.handleInput(data);
+	}
+}
+
+export class EditorManager {
+	private readonly activeTui: { current: TUI | undefined } = { current: undefined };
+	private editor: WingmanEditor | undefined;
+	private registered = false;
+	/** heads-up 数字键处理器槽位;工厂重建编辑器时自动接上。 */
+	headsUpHandler?: (key: "0" | "1" | "2") => boolean;
+
+	/** 当前编辑器实例(未安装或 TUI 未构建时为 undefined)。 */
+	get current(): WingmanEditor | undefined {
+		return this.editor;
+	}
+
+	/** 按配置同步安装状态;shortcut: 运行中切换会重建编辑器丢弃未提交文本,配置命令场景可接受。 */
+	sync(ctx: ExtensionContext, config: WingmanConfig): void {
+		if (ctx.mode !== "tui") return;
+		const need = config.hint.enabled || config.headsup.enabled;
+		if (need === this.registered) return;
+		if (need) {
+			this.registered = true;
+			ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+				this.activeTui.current = tui;
+				this.editor = new WingmanEditor(tui, theme, keybindings, this.activeTui);
+				this.editor.onHeadsUpKey = (key) => this.headsUpHandler?.(key) ?? false;
+				return this.editor;
+			});
+		} else {
+			// teardown 内部才把 registered 置 false,顺序不可颠倒
+			this.teardown(ctx);
+		}
+	}
+
+	teardown(ctx: ExtensionContext): void {
+		if (!this.registered) return;
+		this.registered = false;
+		this.editor = undefined;
+		this.activeTui.current = undefined;
+		ctx.ui.setEditorComponent(undefined);
+	}
+}

package/headsup.ts

@@ -0,0 +1,276 @@
+/**
+ * headsup.ts — 主 agent 工作时后台去抖审计,提前发现潜在问题
+ * (交互对齐 Claude Code heads-up 真实样例)。
+ *
+ * 触发:tool_execution_end 聚合,去抖 ~8s 或攒够 batchSize 次 → 后台调用
+ * audit.ts 的 Auditor(不 await,不拖住工具事件);冷却或在途时事件留在
+ * 队列等下一次。只有 concern/blocker 上屏,ok/note 静默;失败静默降级
+ * (保留 last-good,即不清已显示的 finding)。
+ *
+ * widget 三态(挂载于 belowEditor,出现时挂载、dismiss 即卸载):
+ *   折叠:`✦ Heads up · <一句话>` + `1: 展开  2: 已知悉  0: 忽略`
+ *   展开:标题 + 要点列表 + `1: 知道了  2: 带到主会话  0: 忽略`
+ *   带到主会话:setEditorText 填入引用块,用户自己编辑/发送(不自动注入)
+ * 数字键仅编辑器为空时被 WingmanEditor 捕获,其余按键照常输入。
+ * 忽略/已知悉/知道了都把发现记入本会话抑制集,同一发现不再弹(v1 同义)。
+ */
+
+import type { ExtensionAPI, ExtensionContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { appendFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Auditor, type Verdict, type VerdictLevel } from "./audit.js";
+import type { WingmanConfig } from "./config.js";
+import type { EditorManager } from "./editor.js";
+import { resolveModel } from "./llm.js";
+
+export type HeadsUpAction = { action: "none" | "expanded" | "dismissed" } | { action: "copied"; text: string };
+
+const WIDGET_KEY = "wingman-headsup";
+const LEVEL_COLOR: Partial<Record<VerdictLevel, ThemeColor>> = { concern: "warning", blocker: "error" };
+/** 冷却期内最多积压的工具事件数,超出丢最旧的。 */
+const MAX_PENDING = 30;
+
+/** WINGMAN_DEBUG=1 时把管线决策追加到 <tmpdir>/wingman-debug.log;旁路默认静默,这是唯一的观测口。 */
+function debug(message: string): void {
+	if (!process.env.WINGMAN_DEBUG) return;
+	try {
+		appendFileSync(join(tmpdir(), "wingman-debug.log"), `${new Date().toISOString()} ${message}\n`);
+	} catch {
+		// 调试通道自身永不抛错
+	}
+}
+
+export class HeadsUpView {
+	private finding: Verdict | undefined;
+	private expanded = false;
+	private readonly suppressed = new Set<string>();
+
+	private key(finding: Verdict): string {
+		return `${finding.level}:${finding.summary}`;
+	}
+
+	/** 上屏新发现;同一发现(level+summary)已被抑制时返回 false。 */
+	show(finding: Verdict): boolean {
+		if (this.suppressed.has(this.key(finding))) return false;
+		this.finding = finding;
+		this.expanded = false;
+		return true;
+	}
+
+	hasPending(): boolean {
+		return this.finding !== undefined;
+	}
+
+	/**
+	 * 三态按键:折叠时 1 展开、0/2 忽略/已知悉(v1 同义,都抑制);
+	 * 展开时 1 知道了、0 忽略(都 dismiss)、2 生成引用块后 dismiss。
+	 */
+	handleKey(key: "0" | "1" | "2"): HeadsUpAction {
+		if (!this.finding) return { action: "none" };
+		if (!this.expanded && key === "1") {
+			this.expanded = true;
+			return { action: "expanded" };
+		}
+		if (this.expanded && key === "2") {
+			const text = this.copyText(this.finding);
+			this.dismiss();
+			return { action: "copied", text };
+		}
+		this.dismiss();
+		return { action: "dismissed" };
+	}
+
+	private dismiss(): void {
+		if (this.finding) this.suppressed.add(this.key(this.finding));
+		this.finding = undefined;
+		this.expanded = false;
+	}
+
+	/** 当前状态的渲染行;无 finding 时为空数组。每行已按宽度截断。 */
+	lines(width: number, theme: Pick<Theme, "fg">): string[] {
+		if (!this.finding) return [];
+		const color = LEVEL_COLOR[this.finding.level];
+		const title = `✦ Heads up · ${color ? theme.fg(color, this.finding.summary) : this.finding.summary}`;
+		const options = theme.fg("dim", this.expanded ? "  1: 知道了  2: 带到主会话  0: 忽略" : "  1: 展开  2: 已知悉  0: 忽略");
+		const lines = this.expanded
+			? [title, "", ...this.finding.details.map((d) => `- ${d}`), "", options]
+			: [title, options];
+		return lines.map((line) => truncateToWidth(line, width));
+	}
+
+	/** finding 的引用块格式(「带到主会话」内容)。 */
+	private copyText(finding: Verdict): string {
+		const quoted = [`> Heads up · ${finding.summary}`];
+		if (finding.details.length > 0) {
+			quoted.push(">");
+			for (const detail of finding.details) quoted.push(`> - ${detail}`);
+		}
+		return `Here is a note offered by a side agent:\n\n${quoted.join("\n")}`;
+	}
+}
+
+export interface ToolEventRecord {
+	toolName: string;
+	isError: boolean;
+	snippet: string;
+}
+
+export function formatToolEvents(events: ToolEventRecord[]): string {
+	return events
+		.map((e) => `${e.toolName} → ${e.isError ? "ERROR" : "ok"}${e.snippet ? ` | ${e.snippet}` : ""}`)
+		.join("\n");
+}
+
+function snippetOf(result: unknown): string {
+	const raw = typeof result === "string" ? result : JSON.stringify(result) || "";
+	return raw.replace(/\s+/g, " ").slice(0, 100);
+}
+
+export interface HeadsUpOptions {
+	batchSize?: number;
+	debounceMs?: number;
+	minIntervalMs?: number;
+}
+
+export function installHeadsUp(
+	pi: ExtensionAPI,
+	getConfig: () => WingmanConfig,
+	getGoal: () => string,
+	editors: EditorManager,
+	options: HeadsUpOptions = {},
+): void {
+	const batchSize = options.batchSize ?? 6;
+	const debounceMs = options.debounceMs ?? 8_000;
+	const auditor = new Auditor({ minIntervalMs: options.minIntervalMs ?? 30_000 });
+	const view = new HeadsUpView();
+	const shutdown = new AbortController();
+	let pending: ToolEventRecord[] = [];
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let lastCtx: ExtensionContext | undefined;
+	let activeTui: { requestRender(): void } | undefined;
+	let widgetShown = false;
+
+	const hideWidget = (ctx: ExtensionContext) => {
+		if (!widgetShown) return;
+		widgetShown = false;
+		activeTui = undefined;
+		ctx.ui.setWidget(WIDGET_KEY, undefined);
+	};
+
+	const showWidget = (ctx: ExtensionContext) => {
+		if (widgetShown) return;
+		widgetShown = true;
+		ctx.ui.setWidget(
+			WIDGET_KEY,
+			(tui, theme) => {
+				activeTui = tui;
+				return {
+					render: (width: number) => view.lines(width, theme),
+					invalidate: () => {},
+					dispose: () => {
+						activeTui = undefined;
+					},
+				};
+			},
+			{ placement: "belowEditor" },
+		);
+	};
+
+	const clearTimer = () => {
+		if (timer) clearTimeout(timer);
+		timer = undefined;
+	};
+
+	const arm = (ctx: ExtensionContext) => {
+		clearTimer();
+		timer = setTimeout(() => runFlush(ctx), debounceMs);
+		timer.unref?.();
+	};
+
+	const flush = async (ctx: ExtensionContext): Promise<void> => {
+		clearTimer();
+		if (pending.length === 0) return;
+		const config = getConfig().headsup;
+		// heads-up 必须显式配置模型才激活(开启必经 /headsup <model>);拼错模型也不回退当前模型
+		if (!config.enabled || !config.model) {
+			debug(`flush 跳过:enabled=${config.enabled} model=${config.model}`);
+			pending = [];
+			return;
+		}
+		const model = resolveModel(ctx.modelRegistry, config.model, undefined);
+		if (!model) {
+			debug(`flush 跳过:模型无法解析 ${config.model}`);
+			pending = [];
+			return;
+		}
+		if (!auditor.ready) {
+			debug(`flush 推迟:审计冷却或在途,保留 ${pending.length} 个事件`);
+			arm(ctx);
+			return;
+		}
+		const events = pending;
+		pending = [];
+		debug(`flush: ${events.length} 个事件送审计`);
+		const verdict = await auditor.run(
+			ctx.modelRegistry,
+			model,
+			{ goal: getGoal(), digest: formatToolEvents(events) },
+			{ timeoutMs: 15_000, signal: shutdown.signal },
+		);
+		debug(`verdict: ${verdict ? `${verdict.level} ${verdict.summary}` : "(调用失败/跳过)"}`);
+		if (!verdict || (verdict.level !== "concern" && verdict.level !== "blocker")) return;
+		if (!view.show(verdict)) {
+			debug("已在抑制集,不上屏");
+			return;
+		}
+		showWidget(ctx);
+		debug("上屏");
+	};
+
+	/** 后台执行 flush:已在 runner 的 try/catch 之外,自己兜底(会话替换后 UI 调用可能抛)。 */
+	const runFlush = (ctx: ExtensionContext) => {
+		flush(ctx).catch(() => {});
+	};
+
+	// 数字键捕获:仅编辑器为空时由 WingmanEditor 调用;已知限制——
+	// 有 pending heads-up 时,空编辑器里输入 0/1/2 开头的文本会被当作命令
+	// (对齐 Claude Code 的行为)。
+	editors.headsUpHandler = (key) => {
+		if (!view.hasPending() || !lastCtx) return false;
+		const result = view.handleKey(key);
+		switch (result.action) {
+			case "expanded":
+				activeTui?.requestRender();
+				return true;
+			case "copied":
+				hideWidget(lastCtx);
+				lastCtx.ui.setEditorText(result.text);
+				return true;
+			case "dismissed":
+				hideWidget(lastCtx);
+				return true;
+			case "none":
+				return false;
+		}
+	};
+
+	pi.on("tool_execution_end", (event, ctx) => {
+		lastCtx = ctx;
+		const config = getConfig().headsup;
+		if (!config.enabled || !config.model || ctx.mode !== "tui") return;
+		pending = [...pending, { toolName: event.toolName, isError: event.isError, snippet: snippetOf(event.result) }].slice(
+			-MAX_PENDING,
+		);
+		debug(`tool_end ${event.toolName}${event.isError ? " ERROR" : ""} pending=${pending.length}`);
+		if (pending.length >= batchSize) runFlush(ctx);
+		else arm(ctx);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		shutdown.abort();
+		clearTimer();
+		hideWidget(ctx);
+	});
+}

package/hint.ts

@@ -0,0 +1,76 @@
+/**
+ * hint.ts — 任务结束后的下一步 prompt 建议(参照 Claude Code prompt suggestions)。
+ *
+ * agent_end 后在后台用便宜模型生成 1 条 ≤120 字符的下一步 prompt(不 await,
+ * 不拖住 agent_end 派发),经 EditorManager 拿到共享 WingmanEditor 设置
+ * pending hint(ghost 渲染与 Tab/Enter/清除状态机在 editor.ts)。
+ * before_agent_start 清除 hint 并使在途生成作废。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { buildDigest, type DigestMessage } from "./audit.js";
+import type { WingmanConfig } from "./config.js";
+import type { EditorManager } from "./editor.js";
+import { completeText, resolveModel, type AnyModel, type ModelRegistry } from "./llm.js";
+
+const HINT_SYSTEM_PROMPT = `The user is driving an AI coding agent. Given the user's goal and the latest transcript, suggest the single next prompt the user is most likely to send.
+
+Rules:
+- Output only the prompt text, no quotes, no explanation.
+- At most 120 characters, one line.
+- Continue the work naturally (next step, fix, verify, or commit); do not repeat what was just done.
+- If the work looks finished, suggest a sensible follow-up or say "继续".`;
+
+const MAX_HINT_CHARS = 120;
+
+export function installHint(
+	pi: ExtensionAPI,
+	getConfig: () => WingmanConfig,
+	getGoal: () => string,
+	editors: EditorManager,
+): void {
+	const shutdown = new AbortController();
+	/** 每个新 run 自增;生成回来时代际已变说明 hint 过期,丢弃。 */
+	let generation = 0;
+
+	const generate = async (registry: ModelRegistry, model: AnyModel, transcript: string, gen: number) => {
+		const goal = getGoal() ? `User's goal: ${getGoal()}\n\n` : "";
+		const result = await completeText(
+			registry,
+			model,
+			{
+				systemPrompt: HINT_SYSTEM_PROMPT,
+				messages: [
+					{
+						role: "user",
+						content: [{ type: "text", text: `${goal}Latest transcript:\n${transcript}` }],
+						timestamp: Date.now(),
+					},
+				],
+			},
+			{ timeoutMs: 10_000, signal: shutdown.signal },
+		);
+		if (!result.ok || gen !== generation) return; // 静默降级 / 已过期
+		editors.current?.setHint(result.text.replace(/\s+/g, " ").trim().slice(0, MAX_HINT_CHARS));
+	};
+
+	pi.on("before_agent_start", () => {
+		generation++;
+		editors.current?.setHint(undefined);
+	});
+
+	pi.on("agent_end", (event, ctx) => {
+		const config = getConfig().hint;
+		if (!config.enabled || ctx.mode !== "tui" || !editors.current) return;
+		const model = resolveModel(ctx.modelRegistry, config.model, ctx.model);
+		if (!model) return;
+		const transcript = buildDigest(event.messages as DigestMessage[], { maxMessages: 6, perMessageChars: 500 });
+		if (!transcript) return;
+		// 后台执行已在 runner 的 try/catch 之外,自己兜底(会话替换后 UI 调用可能抛)
+		generate(ctx.modelRegistry, model, transcript, generation).catch(() => {});
+	});
+
+	pi.on("session_shutdown", () => {
+		shutdown.abort();
+	});
+}

package/index.ts

@@ -0,0 +1,95 @@
+/**
+ * index.ts — pi-wingman 入口。
+ *
+ * M1 hint.ts(下一步 prompt 建议)、M2 advisor.ts(turn 审计 + steer 注入)、
+ * M3 headsup.ts(去抖审计 + widget 三态交互)已接入。
+ * editor.ts 的 EditorManager 统一管理共享 WingmanEditor 的安装(hint 或
+ * headsup 任一开启即装);llm.ts 是共享旁路调用层,audit.ts 是 M2/M3
+ * 共享的审计管线。
+ *
+ * 配置入口对称：/advisor、/hint、/headsup 各接 <provider/model> 开启并设
+ * 模型（须能在 modelRegistry 解析）、on/off 开关（保留模型）、无参看状态；
+ * /wingman 总览。用户目标在此统一捕获，跳过 advisor 注入的旁注，供三个
+ * 功能共用。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { installAdvisor, isAdvisorNote } from "./advisor.js";
+import { applyFeatureArg, featureLine, loadConfig, saveConfig, type WingmanConfig } from "./config.js";
+import { EditorManager } from "./editor.js";
+import { installHeadsUp } from "./headsup.js";
+import { installHint } from "./hint.js";
+import { resolveModel, type ModelRegistry } from "./llm.js";
+
+export default function (pi: ExtensionAPI) {
+	let config: WingmanConfig = loadConfig();
+	let goal = "";
+	/** 参数补全拿不到 ctx,在 session_start 记下 registry。 */
+	let registry: ModelRegistry | undefined;
+	const editors = new EditorManager();
+	const getConfig = () => config;
+	const getGoal = () => goal;
+
+	pi.registerCommand("wingman", {
+		description: "Show wingman status (headsup / advisor / hint)",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify(
+				[
+					"wingman",
+					featureLine("headsup", config.headsup),
+					featureLine("advisor", config.advisor),
+					featureLine("hint", config.hint),
+				].join(" · "),
+				"info",
+			);
+		},
+	});
+
+	for (const feature of ["advisor", "hint", "headsup"] as const) {
+		pi.registerCommand(feature, {
+			description: `Configure wingman ${feature}: /${feature} <provider/model> | on | off`,
+			getArgumentCompletions: (prefix) => {
+				const models = registry?.getAvailable().map((m) => `${m.provider}/${m.id}`) ?? [];
+				const items = ["on", "off", ...models]
+					.filter((value) => value.startsWith(prefix))
+					.map((value) => ({ value, label: value }));
+				return items.length > 0 ? items : null;
+			},
+			handler: async (args, ctx) => {
+				const value = args.trim();
+				if (value && value !== "on" && value !== "off" && !resolveModel(ctx.modelRegistry, value, undefined)) {
+					ctx.ui.notify(`wingman · 找不到模型 ${value}(格式 provider/model-id)`, "error");
+					return;
+				}
+				if (value === "on" && feature !== "hint" && !config[feature].model) {
+					ctx.ui.notify(`wingman · ${feature} 需要模型,先 /${feature} <provider/model>`, "error");
+					return;
+				}
+				const line = applyFeatureArg(config, feature, args);
+				if (args.trim()) {
+					saveConfig(config);
+					editors.sync(ctx, config);
+				}
+				ctx.ui.notify(`wingman · ${line}`, "info");
+			},
+		});
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		config = loadConfig();
+		registry = ctx.modelRegistry;
+		editors.sync(ctx, config);
+	});
+
+	pi.on("before_agent_start", (event) => {
+		if (event.messageType === "user" && !isAdvisorNote(event.prompt)) goal = event.prompt;
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		editors.teardown(ctx);
+	});
+
+	installHint(pi, getConfig, getGoal, editors);
+	installAdvisor(pi, getConfig, getGoal);
+	installHeadsUp(pi, getConfig, getGoal, editors);
+}

package/llm.ts

@@ -0,0 +1,82 @@
+/**
+ * llm.ts — 旁路模型调用封装。
+ *
+ * 经 ctx.modelRegistry.complete() 调 provider 模型：
+ * - resolveModel(registry, "provider/model-id") 解析配置串，未配置/找不到时
+ *   回退当前模型；
+ * - completeText() 统一超时与 AbortController（idle 时 ctx.signal 不存在，
+ *   旁路调用用自有 controller，session_shutdown 统一 abort）。
+ *
+ * 三个功能（headsup / advisor / hint）共用这一层，不直接碰 modelRegistry。
+ * 失败一律返回 { ok: false, reason }，不抛异常进 pi 事件循环。
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type ModelRegistry = ExtensionContext["modelRegistry"];
+export type AnyModel = NonNullable<ExtensionContext["model"]>;
+export type LlmContext = Parameters<ModelRegistry["complete"]>[1];
+/** pi-ai 的 Message:按 role 可辨识的联合(system/user/assistant/toolResult)。 */
+export type Message = LlmContext["messages"][number];
+
+export type CompleteResult = { ok: true; text: string } | { ok: false; reason: string };
+
+/** 拼接内容块里的文本块。 */
+function textOf(content: readonly { type: string }[]): string {
+	return content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text)
+		.join("\n");
+}
+
+/** 提取消息正文的文本块;事件里的 AgentMessage 可能混入无 content 的自定义消息,故守卫数组。 */
+export function messageText(message: Message): string {
+	const { content } = message;
+	if (typeof content === "string") return content;
+	return Array.isArray(content) ? textOf(content) : "";
+}
+
+/**
+ * 解析 "provider/model-id"；缺参或找不到时回退 fallback（hint 传当前模型；
+ * advisor/heads-up 传 undefined，拼错模型时不激活而非悄悄用主模型）。
+ */
+export function resolveModel(
+	registry: ModelRegistry,
+	spec: string | undefined,
+	fallback: AnyModel | undefined,
+): AnyModel | undefined {
+	if (!spec) return fallback;
+	const slash = spec.indexOf("/");
+	if (slash <= 0 || slash === spec.length - 1) return fallback;
+	return registry.find(spec.slice(0, slash), spec.slice(slash + 1)) ?? fallback;
+}
+
+/**
+ * 非流式补全，统一超时与中断。外部 signal（如 session_shutdown）触发时
+ * 一并 abort；超时、stopReason 非 stop、空文本都算失败，原因写进 reason。
+ */
+export async function completeText(
+	registry: ModelRegistry,
+	model: AnyModel,
+	context: LlmContext,
+	options: { timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<CompleteResult> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 15_000);
+	const onOuterAbort = () => controller.abort();
+	options.signal?.addEventListener("abort", onOuterAbort, { once: true });
+	try {
+		const response = await registry.complete(model, context, { signal: controller.signal });
+		if (response.stopReason !== "stop") {
+			return { ok: false, reason: `stopReason=${response.stopReason}` };
+		}
+		const text = textOf(response.content).trim();
+		if (!text) return { ok: false, reason: "empty response" };
+		return { ok: true, text };
+	} catch (error) {
+		return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+	} finally {
+		clearTimeout(timeout);
+		options.signal?.removeEventListener("abort", onOuterAbort);
+	}
+}

package/package.json

@@ -1,6 +1,50 @@
 {
-  "name": "@master.g/pi-wingman",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@master.g/pi-wingman",
+	"version": "0.0.1",
+	"description": "Wingman for pi — heads-up audit while the agent works, a designated advisor model, and next-prompt hints (Tab/Enter to accept)",
+	"type": "module",
+	"license": "MIT",
+	"author": "master-g",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-coding-agent",
+		"extension",
+		"heads-up",
+		"advisor",
+		"hint"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/master-g/pi-wingman.git"
+	},
+	"homepage": "https://github.com/master-g/pi-wingman#readme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"*.ts",
+		"!*.test.ts",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "^1.3.0",
+		"@types/node": "^25.9.3",
+		"bun-types": "^1.4.3",
+		"typescript": "^5.9.0"
+	}
+}