@zhushanwen/pi-subagent-workflow 8.7.0 → 8.8.1

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

@@ -1,5 +1,5 @@
 /**
- * Model List Injector
+ * Model List Injector（C5① 渲染改接 core）
  *
  * 通过 before_agent_start 每 turn 注入 `<available_provider_models>` 段，列出
  * 当前 auth 可用的模型（provider/modelId + 能力 + contextWindow），与
@@ -19,6 +19,11 @@
  *   injector 的码点序契约对齐）。数据真实变化（用户中途配置了新 provider）
  *   时下一 turn 自然反映。
  *
+ * C5①（convergence D-3）：formatModelList + ModelEntry 口径下沉 core 并改调
+ * barrel——pi 投影全字段必给（provider/reasoning:boolean/input[]/contextWindow），
+ * core 的 (provider,id) 码点序 + provider/id 拼接在 pi 投影下与本地旧实现逐字节
+ * 一致（CA2 快照验收前提）；guide 文案是 pi 宿主注入（core 不内嵌平台文案）。
+ *
  * 立场：本注入段只服务「派发时选模型」，明确告知模型不要在会话中切换主模型
  * （KV cache 不友好）；用户明确要求换模型时走 pi 原生 /model 命令（人手动触发）。
  */
@@ -35,19 +40,17 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-import { escapeXml, renderXmlSection } from "@zhushanwen/subagent-core/shared/xml-injection.ts";
+// C5①/C5⑦：渲染统一走 core barrel（formatModelList + ModelEntry 类型为 barrel 导出面）
+import { formatModelList, type ModelEntry } from "@zhushanwen/subagent-core";
 
 const logger = getLogger("injector");
 
-/** 注入段的最小模型投影（从 Model<Api> 收窄，测试无需构造完整 Model） */
-export interface ModelEntry {
-	provider: string;
-	id: string;
-	name: string;
-	reasoning: boolean;
-	input: string[];
-	contextWindow: number;
-}
+/**
+ * pi 版注入引导文案（C5① guide 参数化——core 渲染函数不内嵌平台文案，宿主注入；
+ * 文案与改造前本地实现逐字一致——models 段 guide 无过期问题）。
+ */
+export const MODEL_LIST_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.";
 
 /** Model<Api> → ModelEntry 投影（只留注入段消费的字段；模块内唯一消费方 setupModelListInjector） */
 function toModelEntry(model: Model<Api>): ModelEntry {
@@ -61,53 +64,6 @@ function toModelEntry(model: Model<Api>): ModelEntry {
 	};
 }
 
-/** 码点序比较（显式契约，禁 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>` 段。
  *
@@ -125,6 +81,7 @@ export function setupModelListInjector(pi: ExtensionAPI): void {
 			try {
 				const injection = formatModelList(
 					ctx.modelRegistry.getAvailable().map(toModelEntry),
+					{ guide: MODEL_LIST_GUIDE },
 				);
 				if (!injection) return;
 				return { systemPrompt: event.systemPrompt + injection };

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

@@ -0,0 +1,209 @@
+/**
+ * Resource List Injector 工厂（dual-track convergence D7-②）
+ *
+ * subagent / workflow 两个资源清单 injector 的同构骨架单实现（原两文件逐字同构的
+ * 缓存对 / 唯一写点 / 发现函数 / 三 handler 收敛于此，改 fallback 策略只改一处）：
+ * - 缓存对：entries + 渲染快照。per-process = per-session——xyz-agent session-pool
+ *   模型下每 pi 子进程 = 一 session = 独立扩展实例，闭包级缓存天然 per-session 隔离
+ *   （split mode 多 session 各自独立进程）。渲染快照与数据缓存同步更新：before_agent_start
+ *   每个 turn 都要注入，format（escapeXml 多趟正则 × 全部字段）在数据不变时输出完全
+ *   相同——渲染一次随缓存复用，turn 热路径零重复计算。
+ * - 唯一写点 setCache：数据与渲染缓存同步更新（null 清空两者）。
+ * - 三 handler 自管缓存生命周期（不耦合 index.ts session 逻辑）：
+ *   session_start（含 reload）发现+覆盖缓存（刷新节奏对齐 pi skill，fail-safe 异常
+ *   不阻断、缓存保持 null）；before_agent_start 读缓存渲染注入、miss（session_start
+ *   未触发/缓存被清）则 fallback 重新发现+赋值，空列表/空注入不返回 systemPrompt，
+ *   任何异常被吞掉（记日志）不阻断 agent turn；session_shutdown 清缓存。
+ *   pi 支持 async handler，同一 event 多 handler 链式（前者返回的 systemPrompt 作
+ *   后者输入）。
+ *
+ * 两实例的真差异经 config 参数化承载：kind（发现种类 + discoveryRoots 宿主槽位）/
+ * parse（单文件内容 → entry；workflow 侧 description 截断内聚于其 parse）/ format
+ * （entries → XML 注入段；guide 文案差异内聚于各自 format）/ includeTmp（workflow 侧
+ * 覆盖 .pi/workflows/.tmp/ generate 产物）/ onParseNull（agent 侧「有 frontmatter 但
+ * 解析失败」warn 判据）/ logTag（错误日志前缀，保持既有可检索性）；assemble（agent
+ * 侧真差异：装配循环覆写——U11 下沉 core discoverAgents 后工厂不重复装配语义，
+ * parse/onParseNull 不参与）。
+ *
+ * model-list-injector 不参与本工厂：数据源是 ModelRegistry 内存快照（真差异，无文件
+ * 发现与缓存生命周期），见该文件头注释。
+ */
+
+import type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	ExtensionAPI,
+	ExtensionContext,
+	SessionShutdownEvent,
+	SessionStartEvent,
+} from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import { getHostServices } from "@zhushanwen/subagent-core";
+
+import {
+	discoverResources,
+	findWorkspaceRoot,
+	getCachedParsed,
+	sortByCodepoint,
+} from "@zhushanwen/subagent-core";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+
+const logger = getLogger("injector");
+
+/** 清单条目最小契约：name（去重键 + 码点序排序键）+ path（<location> 注入，发现层填充）。 */
+export interface ResourceListEntry {
+	name: string;
+	path: string;
+}
+
+/** 工厂参数（真差异承载面，见文件头）。 */
+export interface ResourceListInjectorConfig<TEntry extends ResourceListEntry> {
+	/** 发现种类（discoverResources kind + discoveryRoots 宿主槽位）。 */
+	kind: "agents" | "workflows";
+	/** 错误/发现失败日志前缀（如 "[subagent-list-injector]"）。 */
+	logTag: string;
+	/**
+	 * 装配循环覆写：提供时工厂 discover 整体委托它（发现→解析→去重→排序 +
+	 * warn/error 口径全归被委托方），工厂不再跑内置装配循环。agent 侧真差异：
+	 * U11（sink 设计）装配算法单源 core discoverAgents（第三宿主免复刻 G3/S5），
+	 * 壳侧收缩为「宿主注入根现取 + 委托」。此时 parse/onParseNull 不参与工厂装配。
+	 */
+	assemble?: (workspaceRoot: string) => Promise<TEntry[]>;
+	/** 单文件内容 → entry；null = 跳过该文件（无有效 frontmatter/meta）。assemble 覆写时不需要。 */
+	parse?(content: string): TEntry | null;
+	/** entry 列表 → 注入段；空列表返回空串（不注入）。 */
+	format(entries: TEntry[]): string;
+	/** workflow 侧真差异：包含 .pi/workflows/.tmp/（workflow-script generate 产物）。 */
+	includeTmp?: boolean;
+	/** parse 返 null 的旁路处理（agent 侧真差异：仅「有 frontmatter 但解析失败」warn）。 */
+	onParseNull?(filePath: string): void;
+}
+
+/** 工厂产物：setup 注册三 handler；discover 为发现函数（薄模块再导出）。 */
+export interface ResourceListInjector<TEntry extends ResourceListEntry> {
+	setup(pi: ExtensionAPI): void;
+	discover(workspaceRoot: string): Promise<TEntry[]>;
+}
+
+/** 码点序排序契约见 core sortByCodepoint（KV-cache 契约：禁 localeCompare——宿主 locale 差异会破坏跨环境字节一致）。 */
+
+/** kind 单数形态（错误日志文案用，保持与合并前逐字一致）。 */
+function singularKind(kind: "agents" | "workflows"): string {
+	return kind === "agents" ? "agent" : "workflow";
+}
+
+export function createResourceListInjector<TEntry extends ResourceListEntry>(
+	config: ResourceListInjectorConfig<TEntry>,
+): ResourceListInjector<TEntry> {
+	let entriesCache: TEntry[] | null = null;
+	let injectionCache: string | null = null;
+
+	/** 缓存唯一写点：数据与渲染缓存同步更新（null 清空两者）。 */
+	function setCache(entries: TEntry[] | null): void {
+		entriesCache = entries;
+		injectionCache = entries !== null ? config.format(entries) : null;
+	}
+
+	/**
+	 * 用统一资源发现（ADR-031）发现所有可用条目。永不抛错——发现本身 fail-safe，
+	 * 单个文件读失败仅记日志。
+	 *
+	 * assemble 覆写时整体委托（agent 侧：core discoverAgents 单源装配，U11）；
+	 * 否则跑内置装配循环——
+	 * discoverResources 返回按文件名 stem 去重、优先级合并后的 DiscoveredResource[]
+	 * （project > user > builtin，返回顺序低→高优先级——Map 后写覆盖依赖此序，不可在
+	 * 发现层重排）。此处逐个 parse 提取条目（经 getCachedParsed mtime 级缓存），再按
+	 * name 去重（高优先级靠后，Map.set 后者覆盖前者，故最终保留最高优先级同名条目）。
+	 *
+	 * 输出按 name 码点序排序（KV-cache 契约）：注入段进每 turn system prompt，顺序必须
+	 * 与文件系统枚举序（readdir 无契约）解耦——目录内容不变时，session_start / fallback /
+	 * resume 任意重建的渲染结果逐字节一致；仅条目增减时文本才变化。
+	 */
+	async function discover(workspaceRoot: string): Promise<TEntry[]> {
+		if (config.assemble) {
+			return config.assemble(workspaceRoot);
+		}
+		if (!config.parse) {
+			throw new Error(
+				`${config.logTag} invalid injector config: parse is required unless assemble is provided`,
+			);
+		}
+		const resources = await discoverResources({
+			kind: config.kind,
+			workspaceRoot,
+			// 宿主注入根现取（pi 壳 discoveryRoots 每次现取，实例隔离）；agentDir 形参
+			// 已删——其唯一用途就是喂 ScanConfig（u0-data-discovery 偏差 #7）
+			hostRoots: getHostServices().discoveryRoots?.()?.[config.kind] ?? [],
+			...(config.includeTmp ? { includeTmp: true } : {}),
+		});
+
+		const map = new Map<string, TEntry>();
+		for (const resource of resources) {
+			if (!resource.available) continue;
+			try {
+				const entry = getCachedParsed(resource.path, config.parse);
+				if (entry) {
+					map.set(entry.name, { ...entry, path: resource.path });
+				} else {
+					config.onParseNull?.(resource.path);
+				}
+			} catch (err) {
+				// 单个文件读失败不阻断整条清单注入
+				logger.error(
+					`${config.logTag} skip unreadable ${singularKind(config.kind)} file ${resource.path}`,
+					{ reason: toErrorMessage(err) },
+				);
+			}
+		}
+		return sortByCodepoint([...map.values()], (entry) => entry.name);
+	}
+
+	function setup(pi: ExtensionAPI): void {
+		pi.on(
+			"session_start",
+			async (_event: SessionStartEvent, ctx: ExtensionContext): Promise<void> => {
+				try {
+					setCache(await discover(findWorkspaceRoot(ctx.cwd)));
+				} catch (err) {
+					// fail-safe：发现异常不阻断 session，缓存保持 null（before_agent_start 会 fallback）
+					logger.error(`${config.logTag} session_start discover failed`, {
+						reason: toErrorMessage(err),
+					});
+				}
+			},
+		);
+
+		pi.on(
+			"before_agent_start",
+			async (
+				event: BeforeAgentStartEvent,
+				ctx: ExtensionContext,
+			): Promise<BeforeAgentStartEventResult | void> => {
+				try {
+					// 读缓存；miss（session_start 未触发/缓存被清）则 fallback 重新发现+赋值
+					if (entriesCache === null) {
+						setCache(await discover(findWorkspaceRoot(ctx.cwd)));
+					}
+					// injectionCache 与 entriesCache 不变量同步（setCache 保证），直接复用
+					const injection = injectionCache;
+					if (!injection) return;
+					return { systemPrompt: event.systemPrompt + injection };
+				} catch (err) {
+					logger.error(`${config.logTag} before_agent_start failed`, {
+						reason: toErrorMessage(err),
+					});
+				}
+			},
+		);
+
+		pi.on(
+			"session_shutdown",
+			(_event: SessionShutdownEvent, _ctx: ExtensionContext): void => {
+				setCache(null);
+			},
+		);
+	}
+
+	return { setup, discover };
+}

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

@@ -1,81 +1,50 @@
 /**
- * Subagent List Injector（迁移自 unified-hooks + P3/P4 改造）
+ * Subagent List Injector（迁移自 unified-hooks + P3/P4 改造；C5① 渲染改接 core）
  *
  * 发现所有可用 subagent（builtin + user + project 各源）并通过 before_agent_start
  * 每 turn 注入 `<available_subagents>` 段（name + description），让模型能选对 agent
  * 名字而非臆造。注入格式对齐 pi 内置 skill 注入（XML 标签）。
  *
  * 改造点：
- * - P4：发现路径由自实现扫 4 目录改为同包 ADR-031 统一发现 discoverResources
- *   （覆盖 7 源：user-pi/user-agents/npm/npm-dev/project-pi/project-agents + manifest
- *   模式 + 优先级合并）。discoverResources 只返回 DiscoveredResource（path/source/
- *   available），不含 name/description——保留 parseAgentFrontmatter 解析每个 .md 的
- *   frontmatter 提取 name+description。
- * - P3：formatAgentList 开头补正向触发引导（何时该 delegate），保留原有「ONLY use
- *   agent names from this list」名字约束。
+ * - D7-②（dual-track convergence）：同构骨架（缓存对/唯一写点/三 handler）收敛到
+ *   同目录 resource-list-injector.ts 工厂，本文件只保留 agent 侧真差异。
+ * - P3：注入段引导语含正向触发引导（何时该 delegate）+ 名字约束（文案见
+ *   SUBAGENT_LIST_GUIDE）。
+ * - C5①（convergence D-3）：formatAgentList/sortByCodepoint 下沉 core，本文件改调
+ *   core barrel（渲染骨架与条目模板逐字节同 pi 旧本地实现——CA2 快照验收前提）；
+ *   guide 文案是 pi 宿主注入（core 不内嵌平台文案）。
+ * - U11（sink 设计）：装配循环（发现→解析→去重→排序 + warn/error 口径）整体改
+ *   消费 core discoverAgents（execution/agents-assembly，U2/A6）——经工厂 assemble
+ *   覆写槽委托，壳侧收缩为「宿主注入根现取 + 委托」，语义等值口径见
+ *   agents-assembly.ts 头注（⛔1 探针对照注入 XML diff 为空验收）。
  *
- * 归位原因：injector 是 subagent-workflow 的内聚功能（让 LLM 知道有哪些 agent 可用），
- * 与同包 resource-discovery 同包后可直接 import，消除跨包依赖。
+ * 归位原因：injector 是 subagent-workflow 的内聚功能壳——事件接线与数据获取留
+ * 在插件层（before_agent_start / modelRegistry），解析/渲染算法消费 core。
  */
 
 
 
-import type {
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
-	ExtensionAPI,
-	ExtensionContext,
-	SessionShutdownEvent,
-	SessionStartEvent,
-} from "@earendil-works/pi-coding-agent";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import { getHostServices } from "@zhushanwen/subagent-core/core/host-services.ts";
-
 import {
-	discoverResources,
-	findWorkspaceRoot,
-	getCachedFileContent,
-	getCachedParsed,
-} from "@zhushanwen/subagent-core/shared/resource-discovery.ts";
-import { parseResourceMeta } from "@zhushanwen/subagent-core/shared/meta-parser.ts";
-import { escapeXml, renderXmlSection } from "@zhushanwen/subagent-core/shared/xml-injection.ts";
+	type AgentEntry,
+	discoverAgents,
+	formatAgentList,
+	getHostServices,
+	parseResourceMeta,
+} from "@zhushanwen/subagent-core";
 
-const logger = getLogger("injector");
+import { createResourceListInjector } from "./resource-list-injector.ts";
 
 /**
- * Session 级 agent 列表缓存（per-process = per-session）。
+ * pi 版注入引导文案（C5① guide 参数化——core 渲染函数不内嵌平台文案，宿主注入）。
  *
- * xyz-agent session-pool 模型下每 pi 子进程 = 一 session = 独立扩展实例，模块级缓存
- * 天然 per-session 隔离（split mode 多 session 各自独立进程）。session_start（含
- * reload）触发发现覆盖缓存（刷新节奏对齐 pi skill）；session_shutdown 清空；
- * before_agent_start 读缓存，miss（session_start 未触发/缓存被清）则 fallback
- * 重新发现——保证鲁棒。
- */
-let agentCache: AgentEntry[] | null = null;
-
-/**
- * 注入块渲染缓存（与 agentCache 同步更新）：before_agent_start 每个 turn 都要注入，
- * formatAgentList（escapeXml 多趟正则 × 全部字段）在数据不变时输出完全相同——渲染
- * 一次随缓存复用，turn 热路径零重复计算。
+ * 2026-08 C5 重写依据（pi 现参数面，src/interface/subagent-tool-schema.ts）：
+ * 旧句「pass systemPrompt alongside the agent name to create a dynamic agent」
+ * 指向的 systemPrompt 参数已不在 subagent tool schema——现 agent 参数 = .md 绝对
+ * 路径（<location>），缺省落 general-purpose（继承主 agent 模型与项目上下文），
+ * 动态指引经 task 文本 / appendSystemPrompt 参数承载。
  */
-let agentInjectionCache: string | null = null;
-
-/** agentCache 唯一写点：数据与渲染缓存同步更新（null 清空两者）。 */
-function setAgentCache(entries: AgentEntry[] | null): void {
-	agentCache = entries;
-	agentInjectionCache = entries !== null ? formatAgentList(entries) : null;
-}
-
-/** 从 .md frontmatter 提取的最小 agent 信息（m5：+ when/examples 路由样本；S1：+ path） */
-export interface AgentEntry {
-	name: string;
-	description: string;
-	when?: string;
-	examples?: Array<{ match: string; action: string; positive: boolean }>;
-	/** agentRef：agent .md 文件的绝对路径（注入段 <location>，模型直接引用） */
-	path: string;
-}
+export const SUBAGENT_LIST_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 agents from this list — pass the <location> path (absolute .md path) as the agent param. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.";
 
 /**
  * 解析 markdown 文件的 YAML frontmatter（name + description）。
@@ -83,6 +52,9 @@ export interface AgentEntry {
  * m2 收敛：删本地单行 key:value parser，改调 shared/meta-parser.ts parseResourceMeta
  * （IF1 统一 parser，支持 block scalar）。无有效 frontmatter 或缺 name/description 返 null。
  * 投影 {name, description} 注入用（examples 注入留 m5）。
+ *
+ * U11 后装配循环（含本函数的装配内消费）单源 core discoverAgents；保留导出作为
+ * 严格注入投影语义锚（parseResourceMeta 消费面）。
  */
 export function parseAgentFrontmatter(content: string): AgentEntry | null {
 	const meta = parseResourceMeta(content, "agent");
@@ -92,172 +64,29 @@ export function parseAgentFrontmatter(content: string): AgentEntry | null {
 		description: meta.description,
 		when: meta.when,
 		examples: meta.examples,
-		path: "", // 由 discoverAllAgents 从 DiscoveredResource.path 填充
+		path: "", // 装配时由 core discoverAgents 从 DiscoveredResource.path 填充
 	};
 }
 
 /**
- * 用统一资源发现（ADR-031）发现所有可用 agent。
- *
- * discoverResources 返回按文件名 stem 去重、优先级合并后的 DiscoveredResource[]
- * （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，单个文件读失败仅记日志。
+ * agent 清单实例：缓存生命周期 / 三 handler 经工厂骨架；装配循环经 assemble 覆写
+ * 委托 core discoverAgents（U11 单源，parse/onParseNull 不参与工厂装配——warn 口径
+ * 内聚 core：仅「有 frontmatter 但严格校验未通过」才 warn，README 等无 frontmatter
+ * 的 .md 静默跳过）。
  */
-export async function discoverAllAgents(
-	workspaceRoot: string,
-): Promise<AgentEntry[]> {
-	const resources = await discoverResources({
-		kind: "agents",
-		workspaceRoot,
-		// 宿主注入根现取（pi 壳 discoveryRoots 每次现取 getAgentDir，实例隔离）；
-		// agentDir 形参已删——其唯一用途就是喂 ScanConfig（u0-data-discovery 偏差 #7）
-		hostRoots: getHostServices().discoveryRoots?.()?.agents ?? [],
-	});
-
-	const agentMap = new Map<string, AgentEntry>();
-	for (const resource of resources) {
-		if (!resource.available) continue;
-		try {
-			const agent = getCachedParsed(resource.path, parseAgentFrontmatter);
-			if (agent) {
-				agentMap.set(agent.name, { ...agent, path: resource.path });
-			} else if (startsWithFrontmatter(resource.path)) {
-				// m5（评审 M3/F2 + minor-5）：仅「有 frontmatter 但解析失败」才 warn
-				// （缺 name/description/examples 单条非法致整体 reject）——README 等
-				// 无 frontmatter 的 .md 不刷 warn（每 turn 扫描）。
-				logger.warn(
-					`[subagent-list-injector] ${resource.path}: agent frontmatter 解析失败（IF1 校验不通过）——agent 未注入`,
-				);
-			}
-		} catch (err) {
-			// 单个文件读失败不阻断整条 agent 列表注入
-			logger.error(
-				`[subagent-list-injector] skip unreadable agent file ${resource.path}`,
-				{ reason: err instanceof Error ? err.message : String(err) },
-			);
-		}
-	}
-	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;
-	});
-}
-
-/** 内容以 frontmatter 分隔符开头（解析失败才值得 warn 的判据）。 */
-function startsWithFrontmatter(filePath: string): boolean {
-	return (getCachedFileContent(filePath) ?? "").trimStart().startsWith("---");
-}
-
-/**
- * 将 agent 列表格式化为 XML 注入段。
- *
- * P3：引导语开头补正向触发条件（何时该 delegate），再保留原「ONLY use agent names
- * from this list」名字约束。空列表返回空串（不注入）。
- */
-export function formatAgentList(agents: AgentEntry[]): string {
-	if (agents.length === 0) return "";
-
-	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 注入段破坏）
-		if (agent.when) {
-			block += `<when>${escapeXml(agent.when)}</when>`;
-		}
-		if (agent.examples && agent.examples.length > 0) {
-			// 两极性原样渲染——negative 的 action 由作者写「不调用（原因）」，
-			// 渲染器不硬编码后缀（exec-review major-1：曾追加「（不调用）」致双后缀）
-			const exampleLines = agent.examples.map(
-				(e) => `      - "${escapeXml(e.match)}" → ${escapeXml(e.action)}`,
-			);
-			block += `\n    <examples>\n${exampleLines.join("\n")}\n    </examples>`;
-		}
-		block += `<location>${escapeXml(agent.path)}</location></agent>`;
-		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,
-	});
-}
-
-/**
- * 注册 session 生命周期 handler，注入 `<available_subagents>` 段。
- *
- * 三 handler 自管缓存生命周期（不耦合 index.ts session 逻辑）：
- * - session_start：发现+缓存赋值（fail-safe，异常不阻断，缓存保持 null）
- * - before_agent_start：读缓存渲染注入；miss 则 fallback 发现+赋值；空列表/空注入不返回
- *   systemPrompt；任何异常被吞掉（记日志），不阻断 agent turn
- * - session_shutdown：清缓存
- *
- * pi 支持 async handler，且同一 event 多 handler 链式（前者返回的 systemPrompt 作
- * 后者输入）。
- */
-export function setupSubagentListInjector(pi: ExtensionAPI): void {
-	pi.on(
-		"session_start",
-		async (_event: SessionStartEvent, ctx: ExtensionContext): Promise<void> => {
-			try {
-				setAgentCache(
-					await discoverAllAgents(
-						findWorkspaceRoot(ctx.cwd),
-					),
-				);
-			} catch (err) {
-				// fail-safe：发现异常不阻断 session，缓存保持 null（before_agent_start 会 fallback）
-				logger.error("[subagent-list-injector] session_start discover failed", {
-					reason: err instanceof Error ? err.message : String(err),
-				});
-			}
-		},
-	);
-
-	pi.on(
-		"before_agent_start",
-		async (
-			event: BeforeAgentStartEvent,
-			ctx: ExtensionContext,
-		): Promise<BeforeAgentStartEventResult | void> => {
-			try {
-				// 读缓存；miss（session_start 未触发/缓存被清）则 fallback 重新发现+赋值
-				if (agentCache === null) {
-					setAgentCache(
-						await discoverAllAgents(
-							findWorkspaceRoot(ctx.cwd),
-						),
-					);
-				}
-				// agentInjectionCache 与 agentCache 不变量同步（setAgentCache 保证），直接复用
-				const injection = agentInjectionCache;
-				if (!injection) return;
-				return { systemPrompt: event.systemPrompt + injection };
-			} catch (err) {
-				logger.error("[subagent-list-injector] before_agent_start failed", {
-					reason: err instanceof Error ? err.message : String(err),
-				});
-			}
-		},
-	);
-
-	pi.on(
-		"session_shutdown",
-		(_event: SessionShutdownEvent, _ctx: ExtensionContext): void => {
-			setAgentCache(null);
-		},
-	);
-}
+const injector = createResourceListInjector<AgentEntry>({
+	kind: "agents",
+	logTag: "[subagent-list-injector]",
+	format: (agents) => formatAgentList(agents, { guide: SUBAGENT_LIST_GUIDE }),
+	assemble: (workspaceRoot) =>
+		discoverAgents(
+			workspaceRoot,
+			getHostServices().discoveryRoots?.()?.agents ?? [],
+		),
+});
+
+/** 发现所有可用 agent（装配骨架见工厂；装配算法单源 core discoverAgents，U11）。 */
+export const discoverAllAgents = injector.discover;
+
+/** 注册 session 生命周期 handler，注入 `<available_subagents>` 段（三 handler 语义见工厂）。 */
+export const setupSubagentListInjector = injector.setup;