@zhushanwen/pi-subagent-workflow 8.1.1 → 8.3.0

package/src/injectors/model-list-injector.ts

@@ -0,0 +1,138 @@
+/**
+ * Model List Injector
+ *
+ * 通过 before_agent_start 每 turn 注入 `<available_provider_models>` 段，列出
+ * 当前 auth 可用的模型（provider/modelId + 能力 + contextWindow），与
+ * `<available_subagents>` / `<available_workflows>` 对称——三者合起来让模型掌握
+ * 派发所需的全部资源清单。
+ *
+ * 背景：模型列表的最大消费者是本包的 subagent/workflow `model` 参数（要求
+ * "provider/modelId" 格式，非法值直接 throw）。注入后模型可直接按 id 派发，
+ * 无需臆造模型名。
+ *
+ * 与另两个 injector 的差异：数据源不是文件发现而是 ModelRegistry.getAvailable()
+ * （pi 权威的 auth 可用模型快照，纯内存同步调用），因此：
+ * - 不需要 session_start 预热 / 渲染缓存 / session_shutdown 清理（无模块级
+ *   状态——结构上规避了缓存生命周期问题）
+ * - 每 turn 直接渲染；排序 (provider, id) 码点序保证输出字节稳定（turn 间
+ *   systemPrompt 前缀稳定 = KV cache 友好；跨环境逐字节可复现，与另两个
+ *   injector 的码点序契约对齐）。数据真实变化（用户中途配置了新 provider）
+ *   时下一 turn 自然反映。
+ *
+ * 立场：本注入段只服务「派发时选模型」，明确告知模型不要在会话中切换主模型
+ * （KV cache 不友好）；用户明确要求换模型时走 pi 原生 /model 命令（人手动触发）。
+ */
+
+import type {
+	Api,
+	Model,
+} from "@earendil-works/pi-ai";
+import type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import { escapeXml, renderXmlSection } from "../shared/xml-injection.ts";
+
+const logger = getLogger("injector");
+
+/** 注入段的最小模型投影（从 Model<Api> 收窄，测试无需构造完整 Model） */
+export interface ModelEntry {
+	provider: string;
+	id: string;
+	name: string;
+	reasoning: boolean;
+	input: string[];
+	contextWindow: number;
+}
+
+/** Model<Api> → ModelEntry 投影（只留注入段消费的字段；模块内唯一消费方 setupModelListInjector） */
+function toModelEntry(model: Model<Api>): ModelEntry {
+	return {
+		provider: model.provider,
+		id: model.id,
+		name: model.name,
+		reasoning: model.reasoning,
+		input: [...model.input],
+		contextWindow: model.contextWindow,
+	};
+}
+
+/** 码点序比较（显式契约，禁 localeCompare——宿主 locale 差异会破坏跨环境字节一致）。 */
+function compareByCodepoint(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** 能力标记：reasoning → "reasoning"，input 含 image → "vision"（空则省略 caps 段） */
+function formatCaps(entry: ModelEntry): string {
+	const caps: string[] = [];
+	if (entry.reasoning) caps.push("reasoning");
+	if (entry.input.includes("image")) caps.push("vision");
+	return caps.join(",");
+}
+
+/**
+ * 将模型列表格式化为 XML 注入段。
+ *
+ * 输入按 (provider, id) 码点序排序——registry 返回顺序不作保证，排序后同一
+ * 数据集输出字节稳定。码点序是显式契约（禁 localeCompare——宿主 locale 差异
+ * 会破坏跨环境字节一致，见 subagent-list-injector.ts sortByCodepoint 注释），
+ * 保证注入段进每 turn system prompt 时跨环境逐字节可复现（cache-probe 前缀
+ * 指纹归因 / 换机器 resume 场景依赖此性质）。空列表返回空串（不注入）。
+ */
+export function formatModelList(models: ModelEntry[]): string {
+	if (models.length === 0) return "";
+
+	const sorted = [...models].sort((a, b) =>
+		a.provider === b.provider
+			? compareByCodepoint(a.id, b.id)
+			: compareByCodepoint(a.provider, b.provider),
+	);
+
+	const items = sorted.map((m) => {
+		const caps = formatCaps(m);
+		return (
+			`  <model><id>${escapeXml(`${m.provider}/${m.id}`)}</id>`
+				+ `<name>${escapeXml(m.name)}</name>`
+				+ (caps ? `<caps>${caps}</caps>` : "")
+				+ `<contextWindow>${m.contextWindow}</contextWindow></model>`
+		);
+	});
+	return renderXmlSection({
+		tag: "available_provider_models",
+		guide: "The following models are available (auth-configured). Use these ids when delegating via the subagent/workflow `model` param (\"provider/modelId\" format) to match the task (e.g. vision models for screenshots, strong reasoners for architecture). Do NOT switch the main conversation model mid-session — per-call model override on delegates only (switching the main model is cache-hostile); use the /model command only when the user explicitly asks to change it.",
+		items,
+	});
+}
+
+/**
+ * 注册 before_agent_start handler，注入 `<available_provider_models>` 段。
+ *
+ * 每 turn 从 ctx.modelRegistry.getAvailable() 同步取快照渲染注入；空列表不
+ * 返回 systemPrompt；任何异常被吞掉（记日志），不阻断 agent turn。与 subagent/
+ * workflow 注入 handler 链式（pi 串联多 handler 的 systemPrompt 返回值）。
+ */
+export function setupModelListInjector(pi: ExtensionAPI): void {
+	pi.on(
+		"before_agent_start",
+		async (
+			event: BeforeAgentStartEvent,
+			ctx: ExtensionContext,
+		): Promise<BeforeAgentStartEventResult | void> => {
+			try {
+				const injection = formatModelList(
+					ctx.modelRegistry.getAvailable().map(toModelEntry),
+				);
+				if (!injection) return;
+				return { systemPrompt: event.systemPrompt + injection };
+			} catch (err) {
+				logger.error("[model-list-injector] before_agent_start failed", {
+					reason: err instanceof Error ? err.message : String(err),
+				});
+			}
+		},
+	);
+}

package/src/injectors/subagent-list-injector.ts

@@ -35,8 +35,10 @@ import {
 	discoverResources,
 	findWorkspaceRoot,
 	getCachedFileContent,
+	getCachedParsed,
 } from "../shared/resource-discovery.ts";
 import { parseResourceMeta } from "../shared/meta-parser.ts";
+import { escapeXml, renderXmlSection } from "../shared/xml-injection.ts";
 
 const logger = getLogger("injector");
 
@@ -97,9 +99,14 @@ export function parseAgentFrontmatter(content: string): AgentEntry | null {
  * 用统一资源发现（ADR-031）发现所有可用 agent。
  *
  * discoverResources 返回按文件名 stem 去重、优先级合并后的 DiscoveredResource[]
- * （project > user > builtin）。此处逐个解析 frontmatter 提取 name+description，
- * 再按 agent name 去重（discoverResources 返回顺序为低→高优先级，高优先级靠后，
- * Map.set 后者覆盖前者，故最终保留最高优先级同名 agent）。
+ * （project > user > builtin，返回顺序低→高优先级——Map 后写覆盖依赖此序，不可在
+ * 发现层重排）。此处逐个解析 frontmatter 提取 name+description（经 getCachedParsed
+ * mtime 级缓存），再按 agent name 去重（高优先级靠后，Map.set 后者覆盖前者，故最终
+ * 保留最高优先级同名 agent）。
+ *
+ * 输出按 name 码点序排序（KV-cache 契约）：注入段进每 turn system prompt，顺序必须
+ * 与文件系统枚举序（readdir 无契约）解耦——目录内容不变时，session_start / fallback /
+ * resume 任意重建的渲染结果逐字节一致；仅条目增减时文本才变化。
  *
  * 永不抛错——发现本身 fail-safe，单个文件读失败仅记日志。
  */
@@ -117,11 +124,10 @@ export async function discoverAllAgents(
 	for (const resource of resources) {
 		if (!resource.available) continue;
 		try {
-			const content = getCachedFileContent(resource.path) ?? "";
-			const agent = parseAgentFrontmatter(content);
+			const agent = getCachedParsed(resource.path, parseAgentFrontmatter);
 			if (agent) {
 				agentMap.set(agent.name, { ...agent, path: resource.path });
-			} else if (content.trimStart().startsWith("---")) {
+			} else if (startsWithFrontmatter(resource.path)) {
 				// m5（评审 M3/F2 + minor-5）：仅「有 frontmatter 但解析失败」才 warn
 				// （缺 name/description/examples 单条非法致整体 reject）——README 等
 				// 无 frontmatter 的 .md 不刷 warn（每 turn 扫描）。
@@ -137,17 +143,21 @@ export async function discoverAllAgents(
 			);
 		}
 	}
-	return [...agentMap.values()];
+	return sortByCodepoint([...agentMap.values()], (a) => a.name);
+}
+
+/** 码点序排序（显式契约，禁 localeCompare——宿主 locale 差异会破坏跨环境字节一致）。 */
+function sortByCodepoint<T>(items: T[], key: (item: T) => string): T[] {
+	return items.sort((a, b) => {
+		const ka = key(a);
+		const kb = key(b);
+		return ka < kb ? -1 : ka > kb ? 1 : 0;
+	});
 }
 
-/** 转义 XML 特殊字符 */
-function escapeXml(str: string): string {
-	return str
-		.replace(/&/g, "&amp;")
-		.replace(/</g, "&lt;")
-		.replace(/>/g, "&gt;")
-		.replace(/"/g, "&quot;")
-		.replace(/'/g, "&apos;");
+/** 内容以 frontmatter 分隔符开头（解析失败才值得 warn 的判据）。 */
+function startsWithFrontmatter(filePath: string): boolean {
+	return (getCachedFileContent(filePath) ?? "").trimStart().startsWith("---");
 }
 
 /**
@@ -159,11 +169,7 @@ function escapeXml(str: string): string {
 export function formatAgentList(agents: AgentEntry[]): string {
 	if (agents.length === 0) return "";
 
-	const lines = [
-		"\n\n<available_subagents>",
-		"The following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, ONLY use agent names from this list. If no agent matches your task, pass systemPrompt alongside the agent name to create a dynamic agent.",
-	];
-	for (const agent of agents) {
+	const items = agents.map((agent) => {
 		let block = `  <agent><name>${escapeXml(agent.name)}</name><description>${escapeXml(agent.description)}</description>`;
 		// m5：路由样本（when + examples 正反原样渲染——negative 的 action 由作者写
 		// 「不调用（原因）」，渲染器不硬编码；全部内容 escapeXml 防 XML 注入段破坏）
@@ -179,10 +185,13 @@ export function formatAgentList(agents: AgentEntry[]): string {
 			block += `\n    <examples>\n${exampleLines.join("\n")}\n    </examples>`;
 		}
 		block += `<location>${escapeXml(agent.path)}</location></agent>`;
-		lines.push(block);
-	}
-	lines.push("</available_subagents>");
-	return lines.join("\n");
+		return block;
+	});
+	return renderXmlSection({
+		tag: "available_subagents",
+		guide: "The following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, ONLY use agent names from this list. If no agent matches your task, pass systemPrompt alongside the agent name to create a dynamic agent.",
+		items,
+	});
 }
 
 /**

package/src/injectors/workflow-list-injector.ts

@@ -31,9 +31,10 @@ import { getLogger } from "@zhushanwen/pi-extension-logger";
 import {
 	discoverResources,
 	findWorkspaceRoot,
-	getCachedFileContent,
+	getCachedParsed,
 } from "../shared/resource-discovery.ts";
 import { parseResourceMeta } from "../shared/meta-parser.ts";
+import { escapeXml, renderXmlSection } from "../shared/xml-injection.ts";
 
 const logger = getLogger("injector");
 
@@ -107,6 +108,8 @@ export function parseWorkflowMeta(content: string): WorkflowEntry | null {
 
 /**
  * 用统一资源发现发现所有可用 workflow（includeTmp 覆盖 generate 产物）。
+ * 解析经 getCachedParsed mtime 级缓存；输出按 name 码点序排序（KV-cache 契约，
+ * 见 subagent-list-injector.ts discoverAllAgents 注释）。
  * 永不抛错——单文件读失败仅记日志。
  */
 export async function discoverAllWorkflows(
@@ -124,8 +127,7 @@ export async function discoverAllWorkflows(
 	for (const resource of resources) {
 		if (!resource.available) continue;
 		try {
-			const content = getCachedFileContent(resource.path) ?? "";
-			const wf = parseWorkflowMeta(content);
+			const wf = getCachedParsed(resource.path, parseWorkflowMeta);
 			if (wf) map.set(wf.name, { ...wf, path: resource.path });
 		} catch (err) {
 			logger.error(
@@ -134,17 +136,9 @@ export async function discoverAllWorkflows(
 			);
 		}
 	}
-	return [...map.values()];
-}
-
-/** 转义 XML 特殊字符 */
-function escapeXml(str: string): string {
-	return str
-		.replace(/&/g, "&")
-		.replace(/</g, "&lt;")
-		.replace(/>/g, "&gt;")
-		.replace(/"/g, "&quot;")
-		.replace(/'/g, "&apos;");
+	return [...map.values()].sort((a, b) =>
+		a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+	);
 }
 
 /**
@@ -157,19 +151,16 @@ function escapeXml(str: string): string {
 export function formatWorkflowList(workflows: WorkflowEntry[]): string {
 	if (workflows.length === 0) return "";
 
-	const lines = [
-		"\n\n<available_workflows>",
+	const items = workflows.map((wf) =>
+		`  <workflow><name>${escapeXml(wf.name)}</name><description>${escapeXml(wf.description)}</description><location>${escapeXml(wf.path)}</location></workflow>`,
+	);
+	return renderXmlSection({
+		tag: "available_workflows",
 		// 引导语与具体 workflow 解耦：不写死内置名（列表本身已含全部 workflow，
 		// 名字/描述每 turn 由 @pi-meta 动态注入），只给通用路由指引 + read location 参数指针。
-		'The following workflows are available. Do NOT call list to discover available workflows — they are listed below; use list only for running state. All listed workflows run directly via action:run — do NOT use workflow-script generate for any listed workflow. For parameter details, read the <location> script file (script header has @pi-meta parameters + usage).',
-	];
-	for (const wf of workflows) {
-		lines.push(
-			`  <workflow><name>${escapeXml(wf.name)}</name><description>${escapeXml(wf.description)}</description><location>${escapeXml(wf.path)}</location></workflow>`,
-		);
-	}
-	lines.push("</available_workflows>");
-	return lines.join("\n");
+		guide: "The following workflows are available. Do NOT call list to discover available workflows — they are listed below; use list only for running state. All listed workflows run directly via action:run — do NOT use workflow-script generate for any listed workflow. For parameter details, read the <location> script file (script header has @pi-meta parameters + usage).",
+		items,
+	});
 }
 
 /**

package/src/orchestration/config-loader.ts

@@ -233,7 +233,11 @@ export async function discoverWorkflows(
     mergedMap.set(cachedMeta.name, cachedMeta);
   }
 
-  const merged = Array.from(mergedMap.values());
+  // 按 name 码点序输出（KV-cache 契约，与 injector 层一致）：不依赖发现层
+  // 优先级迭代序 / readdir 枚举序，重建结果顺序稳定。
+  const merged = Array.from(mergedMap.values()).sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  );
 
   // Update cache (scoped to current workspace root)
   const bucket = getCacheBucket(workspaceRoot);

package/src/orchestration/models/types.ts

@@ -92,7 +92,7 @@ export interface AgentCallOpts {
  * When omitted, agent .md frontmatter thinkingLevel is used (via resolveIdentity/getAgentConfig).
  */
   thinkingLevel?: string;
- /** Scene name for model-switch advisor recommendation. */
+ /** Scene name passed through to the worker for model-selection hints. */
   scene?: string;
  /**
  * Wall-clock timeout in milliseconds. When > 0, aborts the subprocess