pi-firecode 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suge8
+
+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

@@ -0,0 +1,40 @@
+# FireCode
+
+FireCode 是一个模块化 Pi Package，提供终端状态与工具渲染、会话预设、`/fire-review` 对抗审查、`/fire-master` 进程内子代理委派和 `/fire-watch` 观察员。指挥官与观察员的新会话状态由配置决定，裸命令只翻转当前会话；各模块由功能开关独立注册，关闭任一模块不会改变其余模块。
+
+## 安装
+
+```bash
+pi install git:github.com/Suge8/firecode@v0.6.1
+```
+
+也可在本地仓库中直接试用：
+
+```bash
+pi -e .
+```
+
+Pi Package 拥有与 Pi 相同的本机权限；安装前应审阅源码。
+
+## 配置
+
+运行配置不随包分发。将公开模板复制到 Pi Agent 目录后按需启用功能，再重启 Pi：
+
+```bash
+agent_dir="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+mkdir -p "$agent_dir/extensions/firecode"
+curl -fsSL https://raw.githubusercontent.com/Suge8/firecode/v0.6.1/config.example.jsonc \
+  -o "$agent_dir/extensions/firecode/config.jsonc"
+```
+
+公开模板提供维护者当前的完整推荐配置：除 Bark 外功能全开，Master 与 Watcher 在新会话自动激活。Watcher 会在每个主会话回合后调用模型，OpenAI priority 会按供应商规则加价；复制前应确认列出的模型均已认证并接受额外费用。审查与观察员的模型必须显式写入运行配置，否则对应功能拒绝启动。缺少运行配置时，FireCode 会关闭可选功能并在会话启动时警告；配置模板本身不会被运行时读取。
+
+## 开发
+
+需要 [Bun](https://bun.sh/) 和一个 pi-mono checkout。开发版 `pi` 在 `PATH` 中时，测试会自动定位它；否则设置 `PI_PACKAGES_DIR` 为 pi-mono 的 `packages/` 目录。
+
+```bash
+bun test
+```
+
+模块边界、状态机约束和领域术语见 `AGENTS.md`、各模块的 `AGENTS.md` 与 `CONTEXT.md`。

package/config.example.jsonc

@@ -0,0 +1,100 @@
+{
+	// 公开推荐配置：除 Bark 外功能全开。复制后重启 Pi。
+	// Watcher 默认在每个主会话回合后调用模型；OpenAI priority 会按供应商规则加价。
+	"features": {
+		"header": true,
+		"statusbar": true,
+		"tools": true,
+		"presets": true,
+		"rename": true,
+		"stats": true,
+		"claudeSub": true,
+		"openaiNative": true,
+		"workingFlame": true,
+		"bark": false,
+		"review": true,
+		"master": true,
+		"watcher": true
+	},
+
+	"keys": {
+		"rename": "ctrl+r",
+		"cyclePreset": "ctrl+shift+u",
+		"fast": "ctrl+f"
+	},
+
+	// nativeCompaction 使用 OpenAI 原生上下文压缩；priority 加钱换更快出字。
+	"openai": {
+		"nativeCompaction": true,
+		"providers": {
+			"openai-codex": { "textVerbosity": "low", "priority": true },
+			"xai": { "priority": true }
+		}
+	},
+
+	// 每个主会话回合后评估新增内容，会产生额外模型调用；需要开口时当场插话。
+	"watcher": {
+		"enabled": true,
+		"model": "openai-codex/gpt-5.6-sol",
+		"thinking": "low",
+		"context": "minimal"
+	},
+
+	// 新会话默认激活指挥官；每个模型原子必须是 provider/model/thinking。
+	"master": {
+		"autoActivate": true,
+		"workerExcludeExtensions": [],
+		"roles": {
+			"调研员": {
+				"model": "openai-codex/gpt-5.6-luna/xhigh",
+				"use": "大规模并行调研，便宜，不承担实现"
+			},
+			"工程师": {
+				"model": "openai-codex/gpt-5.6-sol/medium",
+				"use": "常规实现与调试，速度快",
+				"fallback": ["anthropic/claude-opus-5/medium"]
+			},
+			"全栈": {
+				"model": "anthropic/claude-opus-5/medium",
+				"use": "前后端综合实现与调试",
+				"fallback": ["openai-codex/gpt-5.6-sol/medium"]
+			},
+			"架构师": {
+				"model": "anthropic/claude-fable-5/high",
+				"use": "高级架构顾问；费用高，启用前必须先征求用户确认"
+			},
+			"设计师": {
+				"model": "kimi-coding/k3-256k/high",
+				"use": "纯视觉设计；已有固定组件和设计方案时不适用"
+			},
+			"哨兵": {
+				"model": "openai-codex/gpt-5.6-luna/low",
+				"use": "盯守 CI、部署与长测试等等待过程"
+			}
+		}
+	},
+
+	"presets": {
+		"fable": { "provider": "anthropic", "model": "claude-fable-5", "thinkingLevel": "high", "key": "alt+1" },
+		"opus5": { "provider": "anthropic", "model": "claude-opus-5", "thinkingLevel": "medium", "key": "alt+2" },
+		"sol": { "provider": "openai-codex", "model": "gpt-5.6-sol", "thinkingLevel": "medium", "key": "alt+3" },
+		"gemini": { "provider": "antigravity", "model": "gemini-3.7-flash", "thinkingLevel": "high", "key": "alt+4" },
+		"ds": { "provider": "deepseek", "model": "deepseek-v4-flash", "thinkingLevel": "high", "key": "alt+5" },
+		"k3-256": { "provider": "kimi-coding", "model": "k3-256k", "thinkingLevel": "high", "key": "alt+6" },
+		"xai": { "provider": "xai", "model": "grok-4.6", "thinkingLevel": "high", "key": "alt+7" }
+	},
+
+	// 审查只在用户或指挥官发起时调用模型。
+	"review": {
+		"advisor": { "model": "anthropic/claude-fable-5", "thinking": "high" },
+		"reviewers": [
+			{ "model": "anthropic/claude-sonnet-5", "thinking": "medium" },
+			{ "model": "anthropic/claude-opus-5", "thinking": "medium" }
+		],
+		"maxRounds": 5,
+		"advisorAfterFailures": 2,
+		"timeoutMinutes": 20,
+		"tools": ["read", "grep", "find", "ls", "bash"],
+		"language": "zh"
+	}
+}

package/config.ts

@@ -0,0 +1,474 @@
+/** FireCode 配置：只读 Pi Agent 目录下的 `extensions/firecode/config.jsonc`。 */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { parseJsonc } from "./jsonc.js";
+
+export type Language = "zh" | "en";
+export type ThinkingLevelValue =
+	| "off"
+	| "minimal"
+	| "low"
+	| "medium"
+	| "high"
+	| "xhigh"
+	| "max";
+
+export interface Preset {
+	provider?: string;
+	model?: string;
+	thinkingLevel?: ThinkingLevelValue;
+	tools?: string[];
+	instructions?: string;
+	/** 一键切换，如 alt+1；不填则无快捷键 */
+	key?: string;
+}
+
+export interface ReviewModel {
+	model: string;
+	thinking: ThinkingLevelValue;
+}
+
+/** /fire-review 配置：审查者 / 顾问模型 + 循环限制。见 config.jsonc 的 review 节注释。 */
+export interface ReviewConfig {
+	advisor: ReviewModel;
+	reviewers: ReviewModel[];
+	/** 审查轮数硬上限。 */
+	maxRounds: number;
+	/** 连续几轮失败触发顾问仲裁。 */
+	advisorAfterFailures: number;
+	/** 单个审查者 / 顾问会话超时（分钟）。 */
+	timeoutMinutes: number;
+	/** 审查者只读工具白名单。 */
+	tools: string[];
+	language: Language;
+}
+
+/** Master 角色表条目：原子模型已拆成运行时模型与思考档。 */
+export interface MasterModelAtom {
+	model: string;
+	thinking: ThinkingLevelValue;
+}
+
+export const MASTER_ROLES = ["调研员", "工程师", "全栈", "架构师", "设计师", "哨兵"] as const;
+export type MasterRoleName = (typeof MASTER_ROLES)[number];
+
+export interface MasterRole extends MasterModelAtom {
+	role: MasterRoleName;
+	use: string;
+	fallback: MasterModelAtom[];
+}
+
+export interface MasterConfig {
+	roles: MasterRole[];
+	workerExcludeExtensions: string[];
+	autoActivate: boolean;
+}
+
+/** 观察员喂给观察会话的增量粒度：minimal 省略 reasoning 与 diff 正文。 */
+export type WatcherContext = "minimal" | "full";
+
+/** Watcher 观察员配置：模型与 thinking 必须显式配置，绝不回退默认模型。 */
+export interface WatcherConfig {
+	enabled: boolean;
+	model: string;
+	thinking: ThinkingLevelValue;
+	context: WatcherContext;
+}
+
+export const FEATURES = [
+	"header",
+	"statusbar",
+	"tools",
+	"presets",
+	"rename",
+	"stats",
+	"claudeSub",
+	"openaiNative",
+	"workingFlame",
+	"bark",
+	"review",
+	"master",
+	"watcher",
+] as const;
+
+export type Feature = (typeof FEATURES)[number];
+
+export const DEFAULT_KEYS = {
+	rename: "ctrl+r",
+	cyclePreset: "ctrl+shift+u",
+	fast: "ctrl+f",
+} as const;
+
+export type FireCodeKeys = {
+	rename: string;
+	cyclePreset: string;
+	fast: string;
+};
+
+export interface FireCodeConfig {
+	features: Partial<Record<Feature, boolean>>;
+	keys: FireCodeKeys;
+	presets: Record<string, Preset>;
+	review: ReviewConfig;
+	master: MasterConfig;
+	watcher: WatcherConfig;
+}
+
+export type LoadedConfig = {
+	config: FireCodeConfig;
+	problems: string[];
+};
+
+export const CONFIG_PATH = join(getAgentDir(), "extensions", "firecode", "config.jsonc");
+
+function readFile(problems: string[]): Record<string, unknown> {
+	if (!existsSync(CONFIG_PATH)) {
+		problems.push("config.jsonc 不存在，已关闭可选功能");
+		return { features: Object.fromEntries(FEATURES.map((feature) => [feature, false])) };
+	}
+	try {
+		const parsed: unknown = parseJsonc(readFileSync(CONFIG_PATH, "utf8"));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			problems.push("config.jsonc 顶层必须是对象");
+			return {};
+		}
+		return parsed as Record<string, unknown>;
+	} catch (error) {
+		// 统一前缀：文件级故障必须能被调用方识别并阻断功能，
+		// 不能因为消息文本不带节名就被当成无关问题过滤掉。
+		const message = error instanceof Error ? error.message : String(error);
+		problems.push(`config.jsonc 解析失败：${message}`);
+		return {};
+	}
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
+function checkFeatures(features: Record<string, unknown>, problems: string[]): void {
+	for (const [key, value] of Object.entries(features)) {
+		if (!FEATURES.includes(key as Feature)) {
+			problems.push(`未知开关 features.${key}，可用：${FEATURES.join(" / ")}`);
+			continue;
+		}
+		// 开关只能是布尔：写成字符串 "false" 时因为 `!== false` 仍会启用，
+		// 而启用 review 意味着真实的模型调用，不能静默放行。
+		if (typeof value !== "boolean")
+			problems.push(`features.${key} 必须是 true 或 false`);
+	}
+}
+
+function checkKeys(keys: FireCodeKeys, presets: Record<string, Preset>, problems: string[]): void {
+	const owners = new Map<string, string>([
+		[keys.rename, "keys.rename"],
+		[keys.cyclePreset, "keys.cyclePreset"],
+		[keys.fast, "keys.fast"],
+	]);
+	const declared = Object.entries(keys);
+	for (let index = 0; index < declared.length; index++) {
+		for (let other = index + 1; other < declared.length; other++) {
+			if (declared[index][1] === declared[other][1]) {
+				problems.push(
+					`快捷键 ${declared[index][1]} 被 keys.${declared[index][0]} 和 keys.${declared[other][0]} 重复占用`,
+				);
+			}
+		}
+	}
+	for (const [name, preset] of Object.entries(presets)) {
+		if (!preset?.key) continue;
+		const owner = owners.get(preset.key);
+		if (owner) problems.push(`快捷键 ${preset.key} 被 ${owner} 和预设 ${name} 重复占用`);
+		else owners.set(preset.key, `预设 ${name}`);
+	}
+}
+
+let cached: LoadedConfig | undefined;
+
+export function loadConfig(): LoadedConfig {
+	if (cached) return cached;
+
+	const problems: string[] = [];
+	const raw = readFile(problems);
+	// features 省略表示沿用默认全开；只要显式写了，就必须是对象。
+	// 非对象不能回退成 {}，因为 {} 在入口语义里正是「全部启用」。
+	const invalidFeatures = raw.features !== undefined && !isPlainObject(raw.features);
+	if (invalidFeatures) problems.push("features 必须是对象");
+	const features: Partial<Record<Feature, boolean>> = invalidFeatures
+		? Object.fromEntries(FEATURES.map((feature) => [feature, false]))
+		: asRecord(raw.features);
+	const rawKeys = asRecord(raw.keys);
+	const presets = asRecord(raw.presets) as Record<string, Preset>;
+	const keys: FireCodeKeys = {
+		rename: typeof rawKeys.rename === "string" ? rawKeys.rename : DEFAULT_KEYS.rename,
+		cyclePreset:
+			typeof rawKeys.cyclePreset === "string" ? rawKeys.cyclePreset : DEFAULT_KEYS.cyclePreset,
+		fast: typeof rawKeys.fast === "string" ? rawKeys.fast : DEFAULT_KEYS.fast,
+	};
+	checkFeatures(features, problems);
+	checkKeys(keys, presets, problems);
+	// review 写成字符串/数组/null 或缺字段时不能静默补齐：会拿用户未选择的模型真实发起审查。
+	const reviewProblems: string[] = [];
+	if (raw.review !== undefined && !isPlainObject(raw.review))
+		reviewProblems.push("review 必须是对象");
+	const review = parseReviewConfig(asRecord(raw.review), reviewProblems);
+	if (raw.review !== undefined || features.review !== false) problems.push(...reviewProblems);
+	// master 同理：角色表错误会拿错模型真实发起 Worker，不能静默当空对象。
+	if (raw.master !== undefined && !isPlainObject(raw.master))
+		problems.push("master 必须是对象");
+	const master = parseMasterConfig(asRecord(raw.master), problems);
+	// watcher 同理：缺节或模型有误时功能拒绝启动，静默回退会拿用户没配的模型真实发起观察。
+	const watcherProblems: string[] = [];
+	if (raw.watcher !== undefined && !isPlainObject(raw.watcher))
+		watcherProblems.push("watcher 必须是对象");
+	const watcher = parseWatcherConfig(asRecord(raw.watcher), watcherProblems);
+	if (raw.watcher !== undefined || features.watcher !== false) problems.push(...watcherProblems);
+
+	cached = { config: { features, keys, presets, review, master, watcher }, problems };
+	return cached;
+}
+
+// ---- review 节 ----
+
+const REVIEW_KEYS = new Set([
+	"advisor",
+	"reviewers",
+	"maxRounds",
+	"advisorAfterFailures",
+	"timeoutMinutes",
+	"tools",
+	"language",
+]);
+const DEFAULT_TOOLS = ["read", "grep", "find", "ls", "bash"];
+const EMPTY_REVIEW_MODEL: ReviewModel = { model: "", thinking: "medium" };
+const THINKING_LEVELS = new Set<ThinkingLevelValue>([
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+]);
+const LANGUAGES = new Set<Language>(["zh", "en"]);
+
+/** 导出供测试：严格拒绝未知字段（含嵌套），类型错误一律记录而非静默回退。 */
+export function parseReviewConfig(raw: Record<string, unknown>, problems: string[]): ReviewConfig {
+	for (const key of Object.keys(raw)) {
+		if (REVIEW_KEYS.has(key)) continue;
+		problems.push(key === "background"
+			? "review.background 已随审查子进程层删除，请直接移除该键"
+			: `未知字段 review.${key}`);
+	}
+	for (const key of REVIEW_KEYS)
+		if (!(key in raw)) problems.push(`review.${key} 必须显式配置`);
+	const advisor = reviewModel(raw.advisor, "review.advisor", EMPTY_REVIEW_MODEL, problems);
+	const reviewers = reviewModels(raw.reviewers, problems);
+	return {
+		advisor,
+		reviewers,
+		maxRounds: reviewInt(raw.maxRounds, "review.maxRounds", 5, 1, 10, problems),
+		advisorAfterFailures: reviewInt(raw.advisorAfterFailures, "review.advisorAfterFailures", 2, 1, 5, problems),
+		timeoutMinutes: reviewInt(raw.timeoutMinutes, "review.timeoutMinutes", 20, 1, 60, problems),
+		tools: reviewTools(raw.tools, problems),
+		language: reviewLanguage(raw.language, problems),
+	};
+}
+
+/** 嵌套对象也做键白名单：拼写错误必须报出来，不能静默回退默认值。 */
+function rejectUnknownKeys(
+	record: Record<string, unknown>,
+	allowed: readonly string[],
+	field: string,
+	problems: string[],
+) {
+	for (const key of Object.keys(record))
+		if (!allowed.includes(key)) problems.push(`未知字段 ${field}.${key}`);
+}
+
+function reviewModel(
+	value: unknown,
+	field: string,
+	fallback: ReviewModel,
+	problems: string[],
+): ReviewModel {
+	if (value === undefined) return fallback;
+	const record = asRecord(value);
+	rejectUnknownKeys(record, ["model", "thinking"], field, problems);
+	if (!record.model || typeof record.model !== "string") {
+		problems.push(`${field}.model 必须是非空字符串`);
+		return fallback;
+	}
+	const thinking =
+		typeof record.thinking === "string" && THINKING_LEVELS.has(record.thinking as ThinkingLevelValue)
+			? (record.thinking as ThinkingLevelValue)
+			: fallback.thinking;
+	if (thinking !== record.thinking) problems.push(`${field}.thinking 值无效`);
+	return { model: record.model, thinking };
+}
+
+function reviewModels(value: unknown, problems: string[]): ReviewModel[] {
+	if (!Array.isArray(value) || value.length === 0 || value.length > 5) {
+		if (value !== undefined) problems.push("review.reviewers 必须包含 1–5 个模型");
+		return [];
+	}
+	return value.map((item, index) =>
+		reviewModel(item, `review.reviewers[${index}]`, EMPTY_REVIEW_MODEL, problems),
+	);
+}
+
+function reviewInt(
+	value: unknown,
+	field: string,
+	fallback: number,
+	min: number,
+	max: number,
+	problems: string[],
+): number {
+	if (value === undefined) return fallback;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+		problems.push(`${field} 必须是 ${min}–${max} 的整数`);
+		return fallback;
+	}
+	return value;
+}
+
+function reviewTools(value: unknown, problems: string[]): string[] {
+	if (value === undefined) return [...DEFAULT_TOOLS];
+	if (!Array.isArray(value)) {
+		problems.push("review.tools 必须是字符串数组");
+		return [...DEFAULT_TOOLS];
+	}
+	const tools = value.filter((item): item is string => typeof item === "string" && item.length > 0);
+	if (tools.length !== value.length || tools.length === 0)
+		problems.push("review.tools 必须是非空字符串数组");
+	return tools.length > 0 ? tools : [...DEFAULT_TOOLS];
+}
+
+// ---- master 节 ----
+
+/** 导出供测试：与 review 节同样严格拒绝未知字段，类型错误记录而非静默回退。 */
+export function parseMasterConfig(raw: Record<string, unknown>, problems: string[]): MasterConfig {
+	for (const key of Object.keys(raw))
+		if (key !== "roles" && key !== "workerExcludeExtensions" && key !== "autoActivate")
+			problems.push(`未知字段 master.${key}`);
+	const exclusions = stringArray(raw.workerExcludeExtensions, "master.workerExcludeExtensions", problems);
+	const autoActivate = booleanValue(raw.autoActivate, "master.autoActivate", true, problems);
+	if (raw.roles === undefined)
+		return { roles: [], workerExcludeExtensions: exclusions, autoActivate };
+	if (!isPlainObject(raw.roles) || Object.keys(raw.roles).length === 0) {
+		problems.push("master.roles 必须是至少包含一个固定角色的对象");
+		return { roles: [], workerExcludeExtensions: exclusions, autoActivate };
+	}
+	const configured = raw.roles;
+	for (const role of Object.keys(configured))
+		if (!MASTER_ROLES.includes(role as MasterRoleName))
+			problems.push(`未知角色 master.roles.${role}，可用：${MASTER_ROLES.join(" / ")}`);
+	const roles = MASTER_ROLES.flatMap((role) =>
+		Object.hasOwn(configured, role)
+			? [masterRole(configured[role], `master.roles.${role}`, role, problems)]
+			: []);
+	return { roles, workerExcludeExtensions: exclusions, autoActivate };
+}
+
+function booleanValue(value: unknown, field: string, fallback: boolean, problems: string[]): boolean {
+	if (value === undefined) return fallback;
+	if (typeof value === "boolean") return value;
+	problems.push(`${field} 必须是 true 或 false`);
+	return fallback;
+}
+
+function stringArray(value: unknown, field: string, problems: string[]): string[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item)) {
+		problems.push(`${field} 必须是非空字符串数组`);
+		return [];
+	}
+	return [...new Set(value)];
+}
+
+function masterRole(
+	value: unknown,
+	field: string,
+	role: MasterRoleName,
+	problems: string[],
+): MasterRole {
+	const record = asRecord(value);
+	rejectUnknownKeys(record, ["model", "use", "fallback"], field, problems);
+	const atom = masterModelAtom(record.model, `${field}.model`, problems);
+	const use = typeof record.use === "string" && record.use ? record.use : "";
+	if (!use) problems.push(`${field}.use 必须是非空字符串`);
+	const fallback = masterFallback(record.fallback, `${field}.fallback`, problems);
+	return { role, ...atom, use, fallback };
+}
+
+function masterFallback(value: unknown, field: string, problems: string[]): MasterModelAtom[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.length > 2) {
+		problems.push(`${field} 必须是至多 2 项的数组`);
+		return [];
+	}
+	return value.map((item, index) => masterModelAtom(item, `${field}[${index}]`, problems));
+}
+
+function masterModelAtom(value: unknown, field: string, problems: string[]): MasterModelAtom {
+	if (typeof value !== "string" || !value) {
+		problems.push(`${field} 必须是“供应商/模型/思考档”字符串`);
+		return { model: "", thinking: "medium" };
+	}
+	const slash = value.lastIndexOf("/");
+	const model = slash > 0 ? value.slice(0, slash) : "";
+	const thinking = slash > 0 ? value.slice(slash + 1) : value;
+	if (!THINKING_LEVELS.has(thinking as ThinkingLevelValue))
+		problems.push(`${field} 思考档无效：${thinking}`);
+	const providerSlash = model.indexOf("/");
+	if (providerSlash <= 0 || providerSlash === model.length - 1)
+		problems.push(`${field} 模型无效：必须是 provider/model`);
+	return {
+		model,
+		thinking: THINKING_LEVELS.has(thinking as ThinkingLevelValue)
+			? thinking as ThinkingLevelValue
+			: "medium",
+	};
+}
+
+// ---- watcher 节 ----
+
+const WATCHER_KEYS = ["enabled", "model", "thinking", "context"] as const;
+const WATCHER_CONTEXTS = new Set<WatcherContext>(["minimal", "full"]);
+
+/** 导出供测试：model/thinking 必填，enabled 默认 true、context 默认 minimal。 */
+export function parseWatcherConfig(raw: Record<string, unknown>, problems: string[]): WatcherConfig {
+	rejectUnknownKeys(raw, WATCHER_KEYS, "watcher", problems);
+	const enabled = booleanValue(raw.enabled, "watcher.enabled", true, problems);
+	const model = typeof raw.model === "string" && raw.model ? raw.model : "";
+	if (!model) problems.push("watcher.model 必须显式配置为非空字符串");
+	let thinking: ThinkingLevelValue | undefined;
+	if (raw.thinking === undefined) problems.push("watcher.thinking 必须显式配置");
+	else if (typeof raw.thinking === "string" && THINKING_LEVELS.has(raw.thinking as ThinkingLevelValue))
+		thinking = raw.thinking as ThinkingLevelValue;
+	else problems.push("watcher.thinking 值无效");
+	let context: WatcherContext = "minimal";
+	if (raw.context !== undefined) {
+		if (typeof raw.context === "string" && WATCHER_CONTEXTS.has(raw.context as WatcherContext))
+			context = raw.context as WatcherContext;
+		else problems.push("watcher.context 必须是 minimal 或 full");
+	}
+	return { enabled, model, thinking: thinking ?? "low", context };
+}
+
+function reviewLanguage(value: unknown, problems: string[]): Language {
+	if (value === undefined) return "zh";
+	if (typeof value !== "string" || !LANGUAGES.has(value as Language)) {
+		problems.push("review.language 必须是 zh 或 en");
+		return "zh";
+	}
+	return value as Language;
+}

package/deliver.ts

@@ -0,0 +1,32 @@
+/**
+ * 统一投递入口（Master 事件与观察员发言共用）：宿主流式中投自定义卡片、经
+ * steer 队列在句缝送达；会话歇透时改走 sendUserMessage 前门唤起——宿主的
+ * triggerTurn 唤醒会跳过 before_agent_start（上游缺陷，#33），前门唤醒自带
+ * 完整开跑仪式，系统提示注入不随回合抖动。
+ *
+ * 忙闲判断与发送必须在同一事件循环节拍内完成，两者之间禁止 await：会话落定
+ * 是下一节拍的事件，同节拍读到的忙闲不会骑墙；宿主在回合结束前清空 steer
+ * 队列，忙时入队的消息以同回合续跑送达，不会沦为唤醒者。
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export interface Envelope<T> {
+	customType: string;
+	content: string;
+	details?: T;
+}
+
+export async function deliver<T>(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	envelope: Envelope<T>,
+): Promise<void> {
+	if (ctx.isIdle?.() === true) {
+		await pi.sendUserMessage(envelope.content);
+		return;
+	}
+	pi.sendMessage<T>(
+		{ customType: envelope.customType, content: envelope.content, display: true, details: envelope.details },
+		{ deliverAs: "steer" },
+	);
+}