@zhushanwen/pi-subagent-workflow 8.1.0 → 8.2.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/__tests__/workflows-e2e.test.ts

@@ -20,7 +20,7 @@
  *
  * registry 绕过说明（见末尾 notes）：
  *   WorkflowScriptRegistryImpl(config) 的扫描源是固定约定目录（.pi/workflows 等），
- *   无法指向 extensions/subagent-workflow/workflows/。为不改源码，这里直接读 .js 文件
+ *   无法指向 extensions/universal/subagent-workflow/workflows/。为不改源码，这里直接读 .js 文件
  *   内容 + 手动构造 WorkflowScript 对象，包装为一个满足 WorkflowScriptRegistry 接口
  *   的自定义 registry（loadWorkflowsFromDir）。
  */
@@ -48,7 +48,7 @@ import type { WorkflowScriptRegistry } from "../models/workflow-script-registry.
 import { WorkerHostImpl } from "../worker-host.ts";
 
 // ── 路径：定位真实 workflows 目录 ─────────────────────────────────────────
-// 本测试文件在 src/orchestration/__tests__/，workflows 目录在 extensions/subagent-workflow/workflows/
+// 本测试文件在 src/orchestration/__tests__/，workflows 目录在 extensions/universal/subagent-workflow/workflows/
 // 即 __dirname → ..  (orchestration) → ..  (src) → ..  (subagent-workflow) → workflows
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const WORKFLOWS_DIR = join(__dirname, "..", "..", "..", "workflows");

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

package/src/shared/__tests__/resource-discovery.test.ts

@@ -23,6 +23,8 @@ import {
   processPackageSync,
   getCachedFile,
   getCachedFileContent,
+  getCachedParsed,
+  clearFileCache,
 } from "../resource-discovery.ts";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
@@ -463,3 +465,80 @@ describe("m5: 统一 mtime 缓存层", () => {
     }
   });
 });
+
+// ── KV-cache 稳定性改造：解析结果缓存 getCachedParsed ──
+
+describe("getCachedParsed（mtime 级解析缓存）", () => {
+  beforeEach(() => {
+    clearFileCache();
+  });
+
+  it("mtime 未变时 parse 只跑一次（缓存解析结果）", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "parsed-cache-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "---\nname: x\ndescription: y\n---", "utf-8");
+    try {
+      const parse = vi.fn((content: string) => (content.includes("name: x") ? "OK" : "BAD"));
+      const first = getCachedParsed(f, parse);
+      const second = getCachedParsed(f, parse);
+      expect(first).toBe("OK");
+      expect(second).toBe("OK");
+      expect(parse).toHaveBeenCalledTimes(1); // 第二次命中缓存，不重 parse
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("mtime 变后重新 parse；文件删除后返回 null 并驱逐", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "parsed-cache2-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "v1", "utf-8");
+    try {
+      const parse = (content: string) => content;
+      expect(getCachedParsed(f, parse)).toBe("v1");
+      fs.writeFileSync(f, "v2", "utf-8");
+      expect(getCachedParsed(f, parse)).toBe("v2"); // mtime 变 → 重新 parse
+      fs.rmSync(f);
+      expect(getCachedParsed(f, parse)).toBeNull(); // 删除 → null
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("clearFileCache 同时清空解析缓存", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "parsed-cache3-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "content", "utf-8");
+    try {
+      const parse = vi.fn(() => "OK");
+      getCachedParsed(f, parse);
+      clearFileCache();
+      getCachedParsed(f, parse);
+      expect(parse).toHaveBeenCalledTimes(2); // 缓存被清 → 重新 parse
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("同一 path 的不同 parse 各自独立缓存（缓存键含 parse 身份，防跨 parse 污染）", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "parsed-cache4-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "shared-content", "utf-8");
+    try {
+      // 模拟真实双 parse 场景：parseAgentFrontmatter vs parseWorkflowMeta 对同一
+      // path（agent 与 workflow 发现源理论上可命中同一路径）各自解析
+      const parseA = (content: string) => ({ kind: "agent" as const, content });
+      const parseW = (content: string) => ({ kind: "workflow" as const, len: content.length });
+      const a1 = getCachedParsed(f, parseA);
+      // 修复前：缓存键只有 path，这里会命中 parseA 的缓存条目并 as T 断言返回
+      // {kind:"agent"}——w1 被污染成错误类型
+      const w1 = getCachedParsed(f, parseW);
+      const a2 = getCachedParsed(f, parseA);
+      expect(a1).toEqual({ kind: "agent", content: "shared-content" });
+      expect(w1).toEqual({ kind: "workflow", len: 14 });
+      expect(a2).toEqual({ kind: "agent", content: "shared-content" });
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/shared/resource-discovery.ts

@@ -174,11 +174,49 @@ export function getCachedFileContent(filePath: string): string | null {
   return getCachedFile(filePath)?.content ?? null;
 }
 
+// [perf] 解析结果缓存（KV-cache 稳定性改造）：外层 key = parse 函数身份，内层 key =
+// path，value = { mtimeMs, parsed }。key 含 parse 身份是正确性要求——同一 path 可能被
+// 不同 parse（agent frontmatter vs workflow meta）解析，单层 path key 会跨 parse 类型
+// 互相污染缓存（先 parse 的结果被 as T 断言返回）。用普通 Map 而非 WeakMap：
+// clearFileCache 需全量清空（测试隔离），WeakMap 不可遍历；parse 函数均为模块级
+// 常量，强引用无泄漏。复用 getCachedFile 的 mtime 判变——mtime 未变时跳过 parse
+// （frontmatter YAML 解析是重建发现时最大的可省 CPU 项）。parse 的确定性结果（含
+// null，如 frontmatter 非法）均可缓存：同一 content 必然解析出同一结果。失效与
+// mtimeCache 同步（clearFileCache）。
+const parsedCache = new Map<
+  (content: string) => unknown,
+  Map<string, { mtimeMs: number; parsed: unknown }>
+>();
+
+/**
+ * mtime 级解析结果缓存：mtime 未变返回缓存 parsed，变则经 getCachedFile 取 content
+ * 重新 parse 并缓存。文件不存在/不可读 → null（并驱逐条目）。缓存按 parse 函数隔离
+ * ——同一 path 的不同 parse 互不污染。
+ */
+export function getCachedParsed<T>(filePath: string, parse: (content: string) => T): T | null {
+  const file = getCachedFile(filePath);
+  let perParse = parsedCache.get(parse);
+  if (!file) {
+    perParse?.delete(filePath);
+    return null;
+  }
+  if (!perParse) {
+    perParse = new Map();
+    parsedCache.set(parse, perParse);
+  }
+  const entry = perParse.get(filePath);
+  if (entry && entry.mtimeMs === file.mtimeMs) return entry.parsed as T;
+  const parsed = parse(file.content);
+  perParse.set(filePath, { mtimeMs: file.mtimeMs, parsed });
+  return parsed;
+}
+
 /** 清空（invalidateCache 语义——测试隔离 + mtime 漏判场景手动刷新兜底）。 */
 export function clearFileCache(): void {
   mtimeCache.clear();
   workspaceRootCache.clear();
   manifestCache.clear();
+  for (const perParse of parsedCache.values()) perParse.clear();
 }
 
 export function findWorkspaceRoot(cwd?: string): string {

package/src/shared/xml-injection.ts

@@ -0,0 +1,35 @@
+// src/shared/xml-injection.ts
+//
+// XML 注入段渲染共享原语——subagent / workflow / model 三个 injector 的 format
+// 函数曾是三份手写同构（escapeXml 逐字重复 + 同一段落骨架），提取此模块消除重复。
+// 调用方保留各自的排序契约与条目渲染（字段差异大，不强行归一）。
+
+/**
+ * 转义 XML 特殊字符（注入段进每 turn system prompt，内容含 < > & 等会破坏
+ * XML 结构——全部字段过一遍转义防注入段破碎）。
+ */
+export function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+/**
+ * XML 注入段渲染骨架：`"\n\n<tag>"` 前导（衔接宿主 prompt 末尾）+ 引导语 +
+ * 条目行 + 闭合标签，以 "\n" join。空条目返回空串（不注入）。
+ *
+ * 三个 injector 共用此骨架保证段落结构逐字节同构；KV-cache 契约（顺序稳定 =
+ * 注入段字节稳定）由调用方排序保证，本函数不重排。
+ */
+export function renderXmlSection(section: {
+	tag: string;
+	guide: string;
+	items: string[];
+}): string {
+	if (section.items.length === 0) return "";
+	const lines = [`\n\n<${section.tag}>`, section.guide, ...section.items, `</${section.tag}>`];
+	return lines.join("\n");
+}

package/workflows/review-fix-loop-utils.cjs

@@ -1,7 +1,7 @@
 // review-fix-loop-utils.cjs — review-fix-loop.js 的可测纯函数模块
 //
 // workflow 编排逻辑的纯函数抽到独立 .cjs，
-// 供 vitest 单测直接 require（extensions/subagent-workflow/src/__tests__/review-fix-loop-utils.test.ts）
+// 供 vitest 单测直接 require（extensions/universal/subagent-workflow/src/__tests__/review-fix-loop-utils.test.ts）
 // 与 worker 运行时共用（review-fix-loop.js 经 workerData.scriptPath 定位本文件）。
 //
 // 本文件不依赖 workflow 全局（$ARGS/agent/parallel/phase/log），所有需要报错的函数