@zhushanwen/pi-subagent-workflow 8.8.0 → 8.8.1

package/src/injectors/__tests__/engine-awareness.test.ts

@@ -22,8 +22,10 @@ import {
 	type EngineAwarenessDeps,
 	type EngineAwarenessOutcome,
 } from "../engine-awareness";
-import { normalizeEngineId } from "@zhushanwen/subagent-core/execution/engine/registry.ts";
-import type { GlobalConfigReadResult } from "@zhushanwen/subagent-core/execution/config.ts";
+// dev 1b05be6f9 删壳 engine-awareness 的 normalizeEngineId 再导出面后，测试直连
+// core barrel（与生产 engine-awareness.ts 的 import 形态一致）
+import { normalizeEngineId } from "@zhushanwen/subagent-core";
+import type { GlobalConfigReadResult } from "@zhushanwen/subagent-core";
 
 // ── 测试数据 ────────────────────────────────────────────
 

package/src/injectors/__tests__/engine-section-stability.test.ts

@@ -9,15 +9,19 @@
 // 1. 段渲染确定性：pi / zcode / ghost 三形态多次独立调用逐字节相等（toBe 级）；
 // 2. 引擎切换只变尾部：provider models 段前缀不变，变化只发生在 engine 段位置（尾部）；
 // 3. 段序守护：engine 段恒位于 provider models 段之后（恒链尾）。双保险实现：
-//    a) handler 链模拟——真实导入 setupModelListInjector + 复刻 index.ts engine
-//       handler 的渲染拼装（检测编排部分归 engine-awareness.test.ts），模拟 pi 的
+//    a) handler 链模拟——真实导入 setupModelListInjector + 复刻 engine handler
+//       （D7-④ 起为 engine-awareness.ts 的 setupEngineAwarenessInjector）的渲染
+//       拼装（检测编排部分归 engine-awareness.test.ts），模拟 pi 的
 //       before_agent_start 链式叠加语义；
-//    b) index.ts 源码级结构断言——锚定注册序与拼装形态。
+//    b) 源码级结构断言——index.ts 锚定注册序（四个 setup 调用先后），engine-awareness.ts
+//       锚定拼装形态。
 //
-// 源码级断言的脆弱性权衡（刻意为之）：engine handler 是 index.ts 内联闭包（无法
-// 导入），而 before_agent_start 多 handler 的段序由注册序唯一决定，「注册序」这一
-// 事实只存在于 index.ts 源码中——源码结构断言是唯一能锚定它的方式。重构挪动注册
-// 位置导致本断言失败属预期行为（提醒同步更新链模拟与守护锚点），不是误报。
+// 源码级断言的脆弱性权衡（刻意为之）：engine handler 的生产实现装配依赖
+// ModelConfigService 单例与 sessionState 存取器（getModelConfigService() 在测试环境
+// 恒 null，导入后 handler 直接早退），链模拟仍以复刻形态锚定拼装保真；而
+// before_agent_start 多 handler 的段序由注册序唯一决定，「注册序」这一事实只存在于
+// index.ts 源码中——源码结构断言是唯一能锚定它的方式。重构挪动注册位置导致本断言
+// 失败属预期行为（提醒同步更新链模拟与守护锚点），不是误报。
 
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -29,12 +33,12 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 // C5①：formatModelList/ModelEntry 下沉 core barrel（setupModelListInjector 留 injector）
 import { formatModelList, type ModelEntry } from "@zhushanwen/subagent-core";
 import { MODEL_LIST_GUIDE, setupModelListInjector } from "../model-list-injector.ts";
-import type { EnginePort } from "@zhushanwen/subagent-core/execution/engine/port.ts";
+import type { EnginePort } from "@zhushanwen/subagent-core";
 import { clearEngines, registerEngine } from "@zhushanwen/subagent-core/execution/engine/registry.ts";
 import {
 	buildEngineModelsPromptAppend,
 	buildSubagentEngineSection,
-} from "@zhushanwen/subagent-core/execution/engine/model-prompt.ts";
+} from "@zhushanwen/subagent-core";
 
 // ── 测试数据 ────────────────────────────────────────────
 
@@ -68,8 +72,9 @@ const ZCODE_MODELS: Array<{ id: string; name?: string }> = [
 const BASE = "You are a coding agent.\n\n# System\nCore prompt body.";
 
 /**
- * engine handler 的追加段拼装（与 index.ts engine handler 同款：状态段 + 清单段、
- * 空段剔除、\n\n 连接）。复刻保真由下方「段序守护」describe 的源码锚点断言保证。
+ * engine handler 的追加段拼装（与 engine-awareness.ts setupEngineAwarenessInjector
+ * 内 handler 同款：状态段 + 清单段、空段剔除、\n\n 连接）。复刻保真由下方「段序守护」
+ * describe 的源码锚点断言保证。
  */
 function composeEngineAppend(defaultEngine: string | undefined): string {
 	return [buildSubagentEngineSection(defaultEngine), buildEngineModelsPromptAppend(defaultEngine)]
@@ -262,7 +267,8 @@ describe("段序守护：engine 段恒链尾（D7）", () => {
 		const { handlers, api } = capturePi();
 		// 真实导入 model list injector（provider models 段的生产渲染路径）
 		setupModelListInjector(api);
-		// 复刻 index.ts engine handler 的渲染拼装部分（检测编排部分归 engine-awareness.test.ts）
+		// 复刻 engine handler（engine-awareness.ts setupEngineAwarenessInjector）的渲染
+		// 拼装部分（检测编排部分归 engine-awareness.test.ts）
 		const defaultEngine = "zcode";
 		handlers.push((event) => {
 			const append = composeEngineAppend(defaultEngine);
@@ -302,8 +308,9 @@ describe("段序守护：engine 段恒链尾（D7）", () => {
 		expect(statusIdx).toBeLessThan(providerIdx);
 	});
 
-	it("index.ts 源码级守护：engine handler 注册序在 model list injector 之后（段序由注册序唯一决定）", () => {
+	it("源码级守护：engine handler 注册序在 model list injector 之后（段序由注册序唯一决定）", () => {
 		const src = readFileSync(fileURLToPath(new URL("../../index.ts", import.meta.url)), "utf8");
+		const eaSrc = readFileSync(fileURLToPath(new URL("../engine-awareness.ts", import.meta.url)), "utf8");
 		const lineOf = (needle: string): number => {
 			const idx = src.indexOf(needle);
 			if (idx < 0) throw new Error(`index.ts 中未找到守护锚点：${needle}`);
@@ -311,33 +318,39 @@ describe("段序守护：engine 段恒链尾（D7）", () => {
 		};
 
 		// 注册序：subagents → workflows → provider models → engine handler（链尾，D7）。
-		// engine handler 是唯一的直接 pi.on("before_agent_start")（其余三段经 setup* 间接注册），
-		// 恰出现一次的断言让「链尾」语义精确成立；未来若新增直接注册需人工复核段序。
-		expect(src.split('pi.on("before_agent_start"')).toHaveLength(2);
+		// D7-④：index.ts 不再有直接 pi.on("before_agent_start") 注册——四段注入全部经
+		// setup* 函数（engine 段经 setupEngineAwarenessInjector）。「零直接注册」断言让
+		// 「链尾」语义精确成立；未来若新增直接注册需人工复核段序。
+		expect(src.split('pi.on("before_agent_start"')).toHaveLength(1);
 		const lineSubagents = lineOf("setupSubagentListInjector(pi);");
 		const lineWorkflows = lineOf("setupWorkflowListInjector(pi);");
 		const lineModels = lineOf("setupModelListInjector(pi);");
-		const lineEngineHandler = lineOf('pi.on("before_agent_start"');
+		const lineEngineSetup = lineOf("setupEngineAwarenessInjector(pi,");
 		expect(lineSubagents).toBeLessThan(lineWorkflows);
 		expect(lineWorkflows).toBeLessThan(lineModels);
-		expect(lineModels).toBeLessThan(lineEngineHandler);
+		expect(lineModels).toBeLessThan(lineEngineSetup);
+
+		// engine handler 的唯一注册点在 engine-awareness.ts（setupEngineAwarenessInjector
+		// 内恰一处 pi.on("before_agent_start")）。
+		expect(eaSrc.split('pi.on("before_agent_start"')).toHaveLength(2);
 
 		// engine handler 内渲染调用序：状态段在清单段之前（append 内段序：状态段 → 清单段）。
-		// 两个调用在 index.ts 中位于同一行（数组字面量），行号无法区分先后——用字符偏移断言
-		const offsetStatusCall = src.indexOf("buildSubagentEngineSection(defaultEngine)");
-		const offsetModelsCall = src.indexOf("buildEngineModelsPromptAppend(defaultEngine)");
+		// 两个调用在 engine-awareness.ts 中位于同一行（数组字面量），行号无法区分先后——
+		// 用字符偏移断言
+		const offsetStatusCall = eaSrc.indexOf("buildSubagentEngineSection(defaultEngine)");
+		const offsetModelsCall = eaSrc.indexOf("buildEngineModelsPromptAppend(defaultEngine)");
 		if (offsetStatusCall < 0 || offsetModelsCall < 0) {
-			throw new Error("index.ts 中未找到 engine 段渲染调用锚点");
+			throw new Error("engine-awareness.ts 中未找到 engine 段渲染调用锚点");
 		}
-		expect(offsetStatusCall).toBeGreaterThan(src.indexOf('pi.on("before_agent_start"'));
+		expect(offsetStatusCall).toBeGreaterThan(eaSrc.indexOf('pi.on("before_agent_start"'));
 		expect(offsetStatusCall).toBeLessThan(offsetModelsCall);
 
 		// 链模拟复刻保真锚点：append 拼装形态（空段剔除 + \n\n 连接 + 尾部追加模板）。
-		// 这些锚点保证 composeEngineAppend 与 index.ts 生产拼装的一致性——生产形态
-		// 变化会先在这里红，提醒同步更新本文件全部复刻点。
-		expect(src).toContain('[buildSubagentEngineSection(defaultEngine), buildEngineModelsPromptAppend(defaultEngine)]');
-		expect(src).toContain('.filter((part) => part !== "")');
-		expect(src).toContain('.join("\\n\\n")');
-		expect(src).toContain("${event.systemPrompt}\\n\\n${append}");
+		// 这些锚点保证 composeEngineAppend 与生产拼装（engine-awareness.ts）的一致性——
+		// 生产形态变化会先在这里红，提醒同步更新本文件全部复刻点。
+		expect(eaSrc).toContain('[buildSubagentEngineSection(defaultEngine), buildEngineModelsPromptAppend(defaultEngine)]');
+		expect(eaSrc).toContain('.filter((part) => part !== "")');
+		expect(eaSrc).toContain('.join("\\n\\n")');
+		expect(eaSrc).toContain("${event.systemPrompt}\\n\\n${append}");
 	});
 });

package/src/injectors/engine-awareness.ts

@@ -10,13 +10,24 @@
 // 只改注入不改路由会出现「prompt 说引擎 B、实际派发跑引擎 A」，权威信息源说谎）
 // → sendMessage 对话流通知（D3/D4，短文案不含任何模型清单）→ 更新 lastEngine。
 //
-// 本模块是无状态纯编排（依赖注入式，可测）；状态（lastEngine）与宿主能力
-// （readConfig / applyRead / sendMessage）由 index.ts engine handler 装配注入。
+// 本模块的编排核心（runEngineAwarenessTurn）是无状态纯编排（依赖注入式，可测）；
+// 生产装配在下方 setupEngineAwarenessInjector（D7-④：接线从 index.ts 内联第 4 处
+// 收编至此，与另三个 injector 的 setup* 同形）——lastEngine 的 per-session 存取经
+// 参数注入（index.ts sessionState 装配），其余宿主能力（readConfig / applyRead /
+// sendMessage）在装配函数内组装。
 
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type {
+  BeforeAgentStartEvent,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-import type { GlobalConfigReadResult } from "@zhushanwen/subagent-core/execution/config.ts";
-import { DEFAULT_ENGINE_ID, normalizeEngineId } from "@zhushanwen/subagent-core/execution/engine/registry.ts";
+import { readGlobalConfig, type GlobalConfigReadResult } from "@zhushanwen/subagent-core";
+import { DEFAULT_ENGINE_ID, normalizeEngineId } from "@zhushanwen/subagent-core";
+import { buildEngineModelsPromptAppend, buildSubagentEngineSection } from "@zhushanwen/subagent-core";
+import { getModelConfigService } from "@zhushanwen/subagent-core";
 
 const logger = getLogger("subagents");
 
@@ -117,3 +128,68 @@ export function runEngineAwarenessTurn(deps: EngineAwarenessDeps): EngineAwarene
   );
   return { outcome: "changed", from: last, to: target };
 }
+
+// ── 生产装配（D7-④：接线从 index.ts 内联收编为统一 setup 函数）─────────────
+//
+// 注册链尾 before_agent_start handler：per-turn 检测编排 + 恒在状态段/引擎清单段
+// 渲染。原 index.ts 内联第 4 处接线（[engine-awareness U3] 标记区域）收编于此——
+// index.ts 的注入链序由四个 setup 调用（subagents → workflows → provider models →
+// engine）的先后表达，不再靠内联闭包 + 注释维护。
+//
+// 编排依据（自 index.ts 随迁的设计注释）：
+// - sendMessage 不设 triggerTurn（D3）——切换是用户主动行为，无需唤醒 AI 立即行动；
+//   P1 探针已证此形态消息进入本 turn LLM 上下文（证据：真机 pi rpc payload dump +
+//   0.84.4 dist sendMessage→_appendCustomMessage→agent.state.messages.push→
+//   createContextSnapshot 调用链）。
+// - 段序：状态段在前（文案声明 "listed ... below"），清单段在后；provider models 段
+//   由更早注册的 handler 注入、位于上方——本 handler 恒链尾注册（D7：段内容变化只断
+//   system prompt 尾部 cache 前缀）。apply 后 getGlobalConfig() 即新值——通知、状态段、
+//   路由三处同 turn 对齐（G2）。
+// - fail-safe：任何异常不注入不阻塞 agent loop；service 未装配（null）或
+//   systemPrompt 非 string 同样静默跳过。
+
+/** per-session lastEngine 存取（生产装配由 index.ts sessionState 提供）。 */
+export interface EngineAwarenessSessionAccessors {
+  /** per-session lastEngine 读取（undefined = 未基线化，D1b）。 */
+  getLastEngine(sessionId: string): string | undefined;
+  /** per-session lastEngine 写入（仅合法引擎 id，不写 undefined）。 */
+  setLastEngine(sessionId: string, engine: string): void;
+}
+
+/**
+ * 注册引擎感知 before_agent_start handler（链尾）。
+ *
+ * 每 turn：① runEngineAwarenessTurn 检测编排（§2.3 数据流 ①② 步）；② 恒在状态段
+ * <current_subagent_engine>（D6）+ 引擎清单段 <available_<engine>_models> 渲染追加
+ * （③ 渲染归本函数）。渲染拼装 = 状态段 + 清单段、空段剔除、\n\n 连接、尾部追加
+ * （engine-section-stability.test.ts 的链模拟复刻此形态，源码锚点断言保真）。
+ */
+export function setupEngineAwarenessInjector(
+  pi: ExtensionAPI,
+  session: EngineAwarenessSessionAccessors,
+): void {
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent, ctx: ExtensionContext) => {
+    try {
+      const service = getModelConfigService();
+      if (service === null || typeof event.systemPrompt !== "string") return undefined;
+      const sid = ctx.sessionManager.getSessionId();
+      runEngineAwarenessTurn({
+        readConfig: () => readGlobalConfig(getAgentDir()),
+        applyRead: (read) => service.applyGlobalConfig(read),
+        sendMessage: (message) => {
+          // D3：不设 triggerTurn——切换是用户主动行为，无需唤醒 AI 立即行动
+          pi.sendMessage(message, {});
+        },
+        getLastEngine: () => session.getLastEngine(sid),
+        setLastEngine: (engine) => session.setLastEngine(sid, engine),
+      });
+      const defaultEngine = service.getGlobalConfig().defaultEngine;
+      const append = [buildSubagentEngineSection(defaultEngine), buildEngineModelsPromptAppend(defaultEngine)]
+        .filter((part) => part !== "")
+        .join("\n\n");
+      return { systemPrompt: `${event.systemPrompt}\n\n${append}` };
+    } catch {
+      return undefined;
+    }
+  });
+}

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 };
+}