@zhushanwen/pi-subagent-workflow 8.7.0 → 8.8.1

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

@@ -1,7 +1,7 @@
 // engine-awareness 单测（[engine-awareness U3]）
 //
 // 覆盖（设计 docs/design/subagent-engine-awareness-injection.md 验收挂钩 D1/D1b/D2/D3/D5）：
-// 1. normalizeEngineId：缺省/空白归一到 'pi'（单一权威源 registry.ts，经本模块再导出）
+// 1. normalizeEngineId：缺省/空白归一到 'pi'（单一权威源 registry.ts，直连导入）
 // 2. buildEngineChangeNotice：§3.1 文案骨架、pi/非 pi 指路段分界、不含任何模型清单（D4）
 // 3. runEngineAwarenessTurn 编排：
 //    - 变更触发 apply + 通知（D2 顺序硬约束：提交缓存先于通知先于记账）
@@ -18,12 +18,14 @@ import { describe, expect, it } from "vitest";
 import {
 	buildEngineChangeNotice,
 	ENGINE_CHANGE_CUSTOM_TYPE,
-	normalizeEngineId,
 	runEngineAwarenessTurn,
 	type EngineAwarenessDeps,
 	type EngineAwarenessOutcome,
 } from "../engine-awareness";
-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";
@@ -26,13 +30,15 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { formatModelList, setupModelListInjector, type ModelEntry } from "../model-list-injector.ts";
-import type { EnginePort } from "@zhushanwen/subagent-core/execution/engine/port.ts";
+// 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";
 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";
 
 // ── 测试数据 ────────────────────────────────────────────
 
@@ -66,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)]
@@ -80,7 +87,7 @@ const APPEND_SEPARATOR = "\n\n";
 
 /** 合成一个 turn 的 system prompt 尾部：BASE + provider models 段 + engine 追加段。 */
 function composeTurn(defaultEngine: string | undefined): string {
-	const providerSection = formatModelList(PROVIDER_ENTRIES);
+	const providerSection = formatModelList(PROVIDER_ENTRIES, { guide: MODEL_LIST_GUIDE });
 	const afterProvider = providerSection === "" ? BASE : BASE + providerSection;
 	const append = composeEngineAppend(defaultEngine);
 	return append === "" ? afterProvider : `${afterProvider}${APPEND_SEPARATOR}${append}`;
@@ -190,7 +197,7 @@ describe("段渲染确定性（D7：同输入恒同输出）", () => {
  *   - 切换后的引擎追加段恰居 prompt 尾部。
  */
 function expectOnlyTailDiffers(from: string | undefined, to: string | undefined): void {
-	const stableHead = BASE + formatModelList(PROVIDER_ENTRIES);
+	const stableHead = BASE + formatModelList(PROVIDER_ENTRIES, { guide: MODEL_LIST_GUIDE });
 	const before = composeTurn(from);
 	const after = composeTurn(to);
 	const beforeAppend = composeEngineAppend(from);
@@ -260,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);
@@ -279,7 +287,7 @@ describe("段序守护：engine 段恒链尾（D7）", () => {
 		// 恒链尾：engine 追加段是 prompt 的最后内容
 		expect(prompt.endsWith(`${APPEND_SEPARATOR}${composeEngineAppend(defaultEngine)}`)).toBe(true);
 		// model list handler 注入形态锚定（BASE + injection 无分隔，生产 handler 同款）
-		expect(prompt.startsWith(BASE + formatModelList(PROVIDER_ENTRIES))).toBe(true);
+		expect(prompt.startsWith(BASE + formatModelList(PROVIDER_ENTRIES, { guide: MODEL_LIST_GUIDE }))).toBe(true);
 	});
 
 	it("对照：注册序颠倒（engine 先、model list 后）时段序断言必失败——守护有判别力", async () => {
@@ -300,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}`);
@@ -309,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/__tests__/model-list-injector.test.ts

@@ -11,7 +11,10 @@ import { describe, expect, it, vi } from "vitest";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import type { ModelEntry } from "../model-list-injector";
+// C5①：formatModelList + ModelEntry 口径下沉 core barrel——测试改从 barrel 取实现，
+// guide 用 pi 宿主注入文案
+import { formatModelList, type ModelEntry } from "@zhushanwen/subagent-core";
+import { MODEL_LIST_GUIDE } from "../model-list-injector";
 
 // ── 测试数据工厂 ────────────────────────────────────────
 
@@ -30,65 +33,59 @@ function entry(overrides: Partial<ModelEntry> = {}): ModelEntry {
 // ── 纯函数：formatModelList ─────────────────────────────
 
 describe("formatModelList", () => {
-	it("空列表返回空串（不注入）", async () => {
-		const { formatModelList } = await import("../model-list-injector");
-		expect(formatModelList([])).toBe("");
+	it("空列表返回空串（不注入）", () => {
+		expect(formatModelList([], { guide: MODEL_LIST_GUIDE })).toBe("");
 	});
 
-	it("渲染 provider/modelId + name + caps + contextWindow", async () => {
-		const { formatModelList } = await import("../model-list-injector");
+	it("渲染 provider/modelId + name + caps + contextWindow", () => {
 		const out = formatModelList([
 			entry({ provider: "p1", id: "m1", name: "Model One" }),
-		]);
+		], { guide: MODEL_LIST_GUIDE });
 		expect(out).toContain("<available_provider_models>");
 		expect(out).toContain("<model><id>p1/m1</id><name>Model One</name><caps>reasoning</caps><contextWindow>200000</contextWindow></model>");
 		expect(out).toContain("</available_provider_models>");
 	});
 
-	it("input 含 image 时 caps 加 vision；无能力时省略 caps 段", async () => {
-		const { formatModelList } = await import("../model-list-injector");
+	it("input 含 image 时 caps 加 vision；无能力时省略 caps 段", () => {
 		const out = formatModelList([
 			entry({ id: "vision-m", input: ["text", "image"] }),
 			entry({ id: "plain-m", reasoning: false }),
-		]);
+		], { guide: MODEL_LIST_GUIDE });
 		expect(out).toContain("<id>zai-coding-cn/vision-m</id>");
 		expect(out).toContain("<caps>reasoning,vision</caps>");
 		// plain-m：reasoning=false 且无 image → 无 caps 段
 		expect(out).toMatch(/<id>zai-coding-cn\/plain-m<\/id><name>[^<]*<\/name><contextWindow>/);
 	});
 
-	it("按 (provider, id) 排序——输入乱序输出仍字节稳定（KV cache 前提）", async () => {
-		const { formatModelList } = await import("../model-list-injector");
+	it("按 (provider, id) 排序——输入乱序输出仍字节稳定（KV cache 前提）", () => {
 		const models = [
 			entry({ provider: "b-prov", id: "z-model" }),
 			entry({ provider: "a-prov", id: "y-model" }),
 			entry({ provider: "a-prov", id: "x-model" }),
 		];
-		const out1 = formatModelList([...models]);
-		const out2 = formatModelList([...models].reverse());
+		const out1 = formatModelList([...models], { guide: MODEL_LIST_GUIDE });
+		const out2 = formatModelList([...models].reverse(), { guide: MODEL_LIST_GUIDE });
 		expect(out1).toBe(out2);
 		// 排序断言：a-prov/x-model 在最前，b-prov 在最后
 		const ids = [...out1.matchAll(/<id>([^<]+)<\/id>/g)].map((m) => m[1]);
 		expect(ids).toEqual(["a-prov/x-model", "a-prov/y-model", "b-prov/z-model"]);
 	});
 
-	it("排序为码点序而非 locale 序（跨环境字节一致契约，禁 localeCompare）", async () => {
-		const { formatModelList } = await import("../model-list-injector");
+	it("排序为码点序而非 locale 序（跨环境字节一致契约，禁 localeCompare）", () => {
 		// 判别样本：码点序 "B"(0x42) < "a"(0x61)，而多数 locale 的 localeCompare
 		// 会把 "a-model" 排在 "B-model" 前——本断言在 localeCompare 实现下必挂
 		const out = formatModelList([
 			entry({ provider: "p", id: "a-model" }),
 			entry({ provider: "p", id: "B-model" }),
-		]);
+		], { guide: MODEL_LIST_GUIDE });
 		const ids = [...out.matchAll(/<id>([^<]+)<\/id>/g)].map((m) => m[1]);
 		expect(ids).toEqual(["p/B-model", "p/a-model"]);
 	});
 
-	it("name 含 XML 特殊字符时转义（防注入段结构破坏）", async () => {
-		const { formatModelList } = await import("../model-list-injector");
+	it("name 含 XML 特殊字符时转义（防注入段结构破坏）", () => {
 		const out = formatModelList([
 			entry({ provider: "p", id: "m", name: `A<&>"'B` }),
-		]);
+		], { guide: MODEL_LIST_GUIDE });
 		expect(out).toContain("<name>A&lt;&amp;&gt;&quot;&apos;B</name>");
 	});
 });
@@ -99,7 +96,7 @@ describe("setupModelListInjector", () => {
 	type Handler = (event: unknown, ctx: unknown) => Promise<unknown>;
 
 	async function setupWithRegistry(models: ModelEntry[], fail = false): Promise<Handler> {
-		const mod = await import("../model-list-injector");
+		const mod = await import("../model-list-injector"); // handler 注册面（含 MODEL_LIST_GUIDE 注入）
 		const handlers: Record<string, Handler> = {};
 		const pi = {
 			on: (name: string, fn: Handler) => {

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

@@ -12,7 +12,11 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { DiscoveredResource } from "@zhushanwen/subagent-core/shared/resource-discovery.ts";
 // 共享 mock 基建（vi.mock 工厂 / mock pi / mock ctx）：helpers/injector-test-mocks.ts
+// ——必须先于 barrel import 初始化：barrel 的 re-export 链会触发深路径 mock 工厂，
+// 工厂闭包引用本 helpers 的绑定（helpers 文件头「惰性求值」约束）
 import { createDiscoveryModuleMock, createLoggerModuleMock, createMockCtx, createMockPi, type CapturedHandlers } from "./helpers/injector-test-mocks.ts";
+// C5①：formatAgentList 下沉 core barrel——测试改从 barrel 取实现，guide 用 pi 宿主注入文案
+import { formatAgentList } from "@zhushanwen/subagent-core";
 
 // ── 稳定 spy：vi.hoisted 保证 resetModules 后引用不变（vi.mock 工厂闭包捕获同一 fn，
 //    故 fresh import 的注入器拿到的 discoverResources === spies.discoverResources，跨
@@ -26,7 +30,7 @@ vi.mock("@zhushanwen/subagent-core/shared/resource-discovery.ts", () => createDi
 vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
 
 // ── 纯函数测试：静态 import（模块级缓存状态不影响纯函数；与下方缓存 describe 隔离） ──
-import { formatAgentList, parseAgentFrontmatter } from "../subagent-list-injector";
+import { parseAgentFrontmatter, SUBAGENT_LIST_GUIDE } from "../subagent-list-injector";
 
 describe("parseAgentFrontmatter", () => {
 	it("解析双引号包裹的 name + description", () => {
@@ -70,7 +74,7 @@ description: '代码审查'
 
 describe("formatAgentList", () => {
 	it("空列表返回空串（不注入）", () => {
-		expect(formatAgentList([])).toBe("");
+		expect(formatAgentList([], { guide: SUBAGENT_LIST_GUIDE })).toBe("");
 	});
 
 	it("TC1: when + examples 注入（原样渲染 + escapeXml + 缺省兼容）", () => {
@@ -86,7 +90,7 @@ describe("formatAgentList", () => {
 				],
 			},
 			{ name: "legacy", description: "未迁移 agent", path: "/agents/legacy.md" },
-		]);
+		], { guide: SUBAGENT_LIST_GUIDE });
 		expect(out).toContain("<when>用户要求 review 代码</when>");
 		// 正反原样渲染——negative action 含原因文本（评审 M5：渲染器不硬编码）
 		expect(out).toContain('"帮我 review 这段代码" → 调用 reviewer 对抗式审查');
@@ -99,29 +103,34 @@ describe("formatAgentList", () => {
 				path: "/agents/x.md",
 				examples: [{ match: "处理 <task> 的 diff", action: "调用 x", positive: true }],
 			},
-		]);
+		], { guide: SUBAGENT_LIST_GUIDE });
 		expect(xmlOut).toContain("&lt;task&gt;");
 		// 缺省兼容：无 when/examples 的 agent 不渲染该段
-		const legacyOut = formatAgentList([{ name: "legacy", description: "未迁移 agent", path: "/agents/legacy.md" }]);
+		const legacyOut = formatAgentList([{ name: "legacy", description: "未迁移 agent", path: "/agents/legacy.md" }], { guide: SUBAGENT_LIST_GUIDE });
 		expect(legacyOut).not.toContain("<when>");
 		expect(legacyOut).not.toContain("<examples>");
 	});
 
 	it("包含 P3 正向触发引导语（何时该 delegate）", () => {
-		const out = formatAgentList([{ name: "worker", description: "d", path: "/agents/worker.md" }]);
+		const out = formatAgentList([{ name: "worker", description: "d", path: "/agents/worker.md" }], { guide: SUBAGENT_LIST_GUIDE });
 		expect(out).toContain("PRIORITY");
 		expect(out).toContain("3+ files");
 		expect(out).toContain("delegate");
 		expect(out).toContain("FIRST");
 	});
 
-	it("保留原 'ONLY use agent names from this list' 名字约束", () => {
-		const out = formatAgentList([{ name: "worker", description: "d", path: "/agents/worker.md" }]);
-		expect(out).toContain("ONLY use agent names from this list");
+	it("C5① guide 更新：agent 引用改为 <location> 路径形态，动态 agent 指引改为缺省 general-purpose（systemPrompt 参数已不在 schema）", () => {
+		const out = formatAgentList([{ name: "worker", description: "d", path: "/agents/worker.md" }], { guide: SUBAGENT_LIST_GUIDE });
+		expect(out).toContain("ONLY use agents from this list");
+		expect(out).toContain("pass the <location> path (absolute .md path) as the agent param");
+		expect(out).toContain("omit agent (a general-purpose agent is used)");
+		// 旧句已过期（subagent tool schema 无 systemPrompt 参数，见 subagent-tool-schema.ts）
+		expect(out).not.toContain("systemPrompt");
+		expect(out).not.toContain("ONLY use agent names from this list");
 	});
 
 	it("包含 'Do NOT call list to discover' 引导语", () => {
-		const out = formatAgentList([{ name: "worker", description: "d", path: "/agents/worker.md" }]);
+		const out = formatAgentList([{ name: "worker", description: "d", path: "/agents/worker.md" }], { guide: SUBAGENT_LIST_GUIDE });
 		expect(out).toContain("Do NOT call list to discover");
 		expect(out).toContain("use list only for running state");
 	});
@@ -130,7 +139,7 @@ describe("formatAgentList", () => {
 		const out = formatAgentList([
 			{ name: "worker", description: "does work", path: "/agents/worker.md" },
 			{ name: "reviewer", description: "reviews code", path: "/agents/reviewer.md" },
-		]);
+		], { guide: SUBAGENT_LIST_GUIDE });
 		expect(out).toContain("<available_subagents>");
 		expect(out).toContain("</available_subagents>");
 		expect(out).toContain("<name>worker</name>");
@@ -143,10 +152,39 @@ describe("formatAgentList", () => {
 	});
 
 	it("转义 XML 特殊字符", () => {
-		const out = formatAgentList([{ name: "a&b<c>", description: "\"q\"", path: "/agents/a&b<c>.md" }]);
+		const out = formatAgentList([{ name: "a&b<c>", description: "\"q\"", path: "/agents/a&b<c>.md" }], { guide: SUBAGENT_LIST_GUIDE });
 		expect(out).toContain("<name>a&amp;b&lt;c&gt;</name>");
 		expect(out).toContain("&quot;q&quot;");
 	});
+
+	it("CA2 快照等价锚定：骨架 + 条目段逐字节等于 pi 旧本地实现模板（除 location 前缀外零变化）", () => {
+		// 条目模板逐字复制自 C5① 前的本地 formatAgentList 实现（escapeXml 同函数），
+		// 锚定 core 下沉未改变渲染字节（红线 8：等价豁免仅 location 前缀 + guide 段）
+		const agents = [
+			{
+				name: "reviewer",
+				description: "代码审查",
+				path: "/OLD-PREFIX/agents/reviewer.md",
+				when: "用户要求 review",
+			},
+			{ name: "worker", description: "does work", path: "/OLD-PREFIX/agents/worker.md" },
+		];
+		const expectedItems = [
+			'  <agent><name>reviewer</name><description>代码审查</description><when>用户要求 review</when><location>/OLD-PREFIX/agents/reviewer.md</location></agent>',
+			'  <agent><name>worker</name><description>does work</description><location>/OLD-PREFIX/agents/worker.md</location></agent>',
+		];
+		const out = formatAgentList(agents, { guide: SUBAGENT_LIST_GUIDE });
+		expect(out).toBe(
+			`\n\n<available_subagents>\n${SUBAGENT_LIST_GUIDE}\n${expectedItems.join("\n")}\n</available_subagents>`,
+		);
+
+		// location 前缀替换（资产来源迁移：pi-sw 安装目录 → core 包）后其余字节零变化
+		const migrated = formatAgentList(
+			agents.map((a) => ({ ...a, path: a.path.replace("/OLD-PREFIX/", "/NEW-CORE-PKG/") })),
+			{ guide: SUBAGENT_LIST_GUIDE },
+		);
+		expect(migrated).toBe(out.replaceAll("/OLD-PREFIX/", "/NEW-CORE-PKG/"));
+	});
 });
 
 // ──────────────────────────────────────────────────────────────
@@ -327,10 +365,12 @@ describe("discoverAllAgents 顺序契约（KV-cache）", () => {
 			]);
 		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
 
-		const { discoverAllAgents, formatAgentList } = await import("../subagent-list-injector");
+		const { discoverAllAgents } = await import("../subagent-list-injector");
 		const first = await discoverAllAgents("/ws");
 		const second = await discoverAllAgents("/ws");
 		expect(second).toEqual(first);
-		expect(formatAgentList(second)).toBe(formatAgentList(first));
+		expect(formatAgentList(second, { guide: SUBAGENT_LIST_GUIDE })).toBe(
+			formatAgentList(first, { guide: SUBAGENT_LIST_GUIDE }),
+		);
 	});
 });

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

@@ -12,7 +12,11 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { DiscoveredResource } from "@zhushanwen/subagent-core/shared/resource-discovery.ts";
 // 共享 mock 基建（vi.mock 工厂 / mock pi / mock ctx）：helpers/injector-test-mocks.ts
+// ——必须先于 barrel import 初始化：barrel 的 re-export 链会触发深路径 mock 工厂，
+// 工厂闭包引用本 helpers 的绑定（helpers 文件头「惰性求值」约束）
 import { createDiscoveryModuleMock, createLoggerModuleMock, createMockCtx, createMockPi, type CapturedHandlers } from "./helpers/injector-test-mocks.ts";
+// C5①：formatWorkflowList/summarizeDescription 下沉 core barrel——测试改从 barrel 取实现
+import { formatWorkflowList, summarizeDescription } from "@zhushanwen/subagent-core";
 
 // ── 稳定 spy（vi.hoisted 保证 resetModules 后引用不变，见 subagent 测试同款注释） ──
 const spies = vi.hoisted(() => ({ discoverResources: vi.fn(), getCachedFileContent: vi.fn() }));
@@ -23,11 +27,7 @@ vi.mock("@zhushanwen/subagent-core/shared/resource-discovery.ts", () => createDi
 vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
 
 // ── 纯函数测试：静态 import（模块级缓存状态不影响纯函数） ──
-import {
-	formatWorkflowList,
-	parseWorkflowMeta,
-	summarizeDescription,
-} from "../workflow-list-injector";
+import { parseWorkflowMeta, WORKFLOW_LIST_GUIDE } from "../workflow-list-injector";
 
 describe("summarizeDescription", () => {
 	it("短描述原样返回", () => {
@@ -113,14 +113,14 @@ phases: [Review, Fix]
 
 describe("formatWorkflowList", () => {
 	it("空列表返回空串（不注入）", () => {
-		expect(formatWorkflowList([])).toBe("");
+		expect(formatWorkflowList([], { guide: WORKFLOW_LIST_GUIDE })).toBe("");
 	});
 
 	it("用 <available_workflows> 标签包裹并列出每个 workflow", () => {
 		const out = formatWorkflowList([
 			{ name: "chain", description: "三步链", path: "/workflows/chain.js" },
 			{ name: "parallel", description: "并行分析", path: "/workflows/parallel.js" },
-		]);
+		], { guide: WORKFLOW_LIST_GUIDE });
 		expect(out).toContain("<available_workflows>");
 		expect(out).toContain("</available_workflows>");
 		expect(out).toContain("<name>chain</name>");
@@ -131,14 +131,26 @@ describe("formatWorkflowList", () => {
 		expect(out).toContain("<location>/workflows/parallel.js</location>");
 	});
 
+	it("CA2 快照等价锚定：骨架 + 条目段逐字节等于 pi 旧本地实现模板（workflow 段 guide 未变）", () => {
+		// 条目模板逐字复制自 C5① 前的本地 formatWorkflowList 实现——锚定 core 下沉
+		// 未改变渲染字节（workflow 段无 location 变化面，全段逐字节等价）
+		const out = formatWorkflowList(
+			[{ name: "chain", description: "三步链", path: "/workflows/chain.js" }],
+			{ guide: WORKFLOW_LIST_GUIDE },
+		);
+		expect(out).toBe(
+			`\n\n<available_workflows>\n${WORKFLOW_LIST_GUIDE}\n  <workflow><name>chain</name><description>三步链</description><location>/workflows/chain.js</location></workflow>\n</available_workflows>`,
+		);
+	});
+
 	it("包含 'Do NOT call list to discover available workflows' 引导语", () => {
-		const out = formatWorkflowList([{ name: "chain", description: "d", path: "/workflows/chain.js" }]);
+		const out = formatWorkflowList([{ name: "chain", description: "d", path: "/workflows/chain.js" }], { guide: WORKFLOW_LIST_GUIDE });
 		expect(out).toContain("Do NOT call list to discover available workflows");
 		expect(out).toContain("use list only for running state");
 	});
 
 	it("引导语通用化：不写死内置 workflow 名，含 info 回收指引", () => {
-		const out = formatWorkflowList([{ name: "chain", description: "d", path: "/workflows/chain.js" }]);
+		const out = formatWorkflowList([{ name: "chain", description: "d", path: "/workflows/chain.js" }], { guide: WORKFLOW_LIST_GUIDE });
 		expect(out).toContain("All listed workflows run directly via action:run");
 		expect(out).toContain("read the <location> script file");
 		// 通用化约束：引导语不点名具体 workflow（名字由 @pi-meta 动态注入，
@@ -147,7 +159,7 @@ describe("formatWorkflowList", () => {
 	});
 
 	it("转义 XML 特殊字符", () => {
-		const out = formatWorkflowList([{ name: "a&b", description: "<x>", path: "/workflows/a&b.js" }]);
+		const out = formatWorkflowList([{ name: "a&b", description: "<x>", path: "/workflows/a&b.js" }], { guide: WORKFLOW_LIST_GUIDE });
 		expect(out).toContain("<name>a&amp;b</name>");
 		expect(out).toContain("&lt;x&gt;");
 	});
@@ -313,10 +325,12 @@ describe("discoverAllWorkflows 顺序契约（KV-cache）", () => {
 			]);
 		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
 
-		const { discoverAllWorkflows, formatWorkflowList } = await import("../workflow-list-injector");
+		const { discoverAllWorkflows } = await import("../workflow-list-injector");
 		const first = await discoverAllWorkflows("/ws");
 		const second = await discoverAllWorkflows("/ws");
 		expect(second).toEqual(first);
-		expect(formatWorkflowList(second)).toBe(formatWorkflowList(first));
+		expect(formatWorkflowList(second, { guide: WORKFLOW_LIST_GUIDE })).toBe(
+			formatWorkflowList(first, { guide: WORKFLOW_LIST_GUIDE }),
+		);
 	});
 });

package/src/injectors/engine-awareness.ts

@@ -10,23 +10,30 @@
 // 只改注入不改路由会出现「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");
 
 /** 引擎变更通知 customType（D3；renderer/测试按此识别引擎变更消息）。 */
 export const ENGINE_CHANGE_CUSTOM_TYPE = "subagent-engine-changed";
 
-// normalizeEngineId 单一权威源在 registry.ts，此处再导出保持既有导入面（index.ts
-// 与测试经本模块导入）不断裂。
-export { normalizeEngineId };
-
 /**
  * 引擎变更通知文案（设计 §3.1 英文基准，三行结构逐字骨架；D4：不含任何模型清单，
  * 清单只活在 system prompt 现值一份）。指路段按目标引擎参数化，与
@@ -121,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;
+    }
+  });
+}