@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

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

@@ -10,23 +10,27 @@
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import type { DiscoveredResource } from "../../shared/resource-discovery.ts";
+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，跨
 //    resetModules 调用计数连续，mockClear 控制每用例重置） ──
 const spies = vi.hoisted(() => ({ discoverResources: vi.fn(), getCachedFileContent: vi.fn() }));
 
-vi.mock("../../shared/resource-discovery.ts", () => createDiscoveryModuleMock(spies));
+vi.mock("@zhushanwen/subagent-core/shared/resource-discovery.ts", () => createDiscoveryModuleMock(spies));
 
 // 工厂必须写成箭头惰性形式：vi.mock 被提升到 import 之前执行，直接传
 // createLoggerModuleMock 引用会在提升位置立即求值 import 绑定 → TDZ ReferenceError
 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/"));
+	});
 });
 
 // ──────────────────────────────────────────────────────────────
@@ -306,7 +344,7 @@ describe("discoverAllAgents 顺序契约（KV-cache）", () => {
 		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
 
 		const { discoverAllAgents } = await import("../subagent-list-injector");
-		const agents = await discoverAllAgents("/ws", "/agent");
+		const agents = await discoverAllAgents("/ws");
 		expect(agents.map((a) => a.name)).toEqual(["alpha", "worker", "zeta"]);
 	});
 
@@ -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 first = await discoverAllAgents("/ws", "/agent");
-		const second = await discoverAllAgents("/ws", "/agent");
+		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

@@ -10,24 +10,24 @@
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import type { DiscoveredResource } from "../../shared/resource-discovery.ts";
+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() }));
 
-vi.mock("../../shared/resource-discovery.ts", () => createDiscoveryModuleMock(spies));
+vi.mock("@zhushanwen/subagent-core/shared/resource-discovery.ts", () => createDiscoveryModuleMock(spies));
 
 // 工厂必须写成箭头惰性形式（vi.mock 提升后直接传引用会 TDZ，见 helper 文件头注释）
 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;");
 	});
@@ -293,7 +305,7 @@ describe("discoverAllWorkflows 顺序契约（KV-cache）", () => {
 		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
 
 		const { discoverAllWorkflows } = await import("../workflow-list-injector");
-		const workflows = await discoverAllWorkflows("/ws", "/agent");
+		const workflows = await discoverAllWorkflows("/ws");
 		expect(workflows.map((w) => w.name)).toEqual(["alpha", "chain", "zeta"]);
 	});
 
@@ -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 first = await discoverAllWorkflows("/ws", "/agent");
-		const second = await discoverAllWorkflows("/ws", "/agent");
+		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

@@ -0,0 +1,119 @@
+// src/injectors/engine-awareness.ts
+//
+// [engine-awareness U3] 引擎感知检测编排。设计权威源：
+// docs/design/subagent-engine-awareness-injection.md §2.3 物理数据流 /
+// §3.3 D1（per-turn poll）、D1b（lastEngine 初始化与静默基线化）、D2（reload 先行）、
+// D3（通知通道）、D5（三态读取语义）。
+//
+// 职责：per-turn（before_agent_start）三态 poll 全局 config → 与 per-session
+// lastEngine diff → 变更时按硬约束顺序编排：提交读取结果到路由缓存（D2，先于一切——
+// 只改注入不改路由会出现「prompt 说引擎 B、实际派发跑引擎 A」，权威信息源说谎）
+// → sendMessage 对话流通知（D3/D4，短文案不含任何模型清单）→ 更新 lastEngine。
+//
+// 本模块是无状态纯编排（依赖注入式，可测）；状态（lastEngine）与宿主能力
+// （readConfig / applyRead / sendMessage）由 index.ts engine handler 装配注入。
+
+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";
+
+const logger = getLogger("subagents");
+
+/** 引擎变更通知 customType（D3；renderer/测试按此识别引擎变更消息）。 */
+export const ENGINE_CHANGE_CUSTOM_TYPE = "subagent-engine-changed";
+
+/**
+ * 引擎变更通知文案（设计 §3.1 英文基准，三行结构逐字骨架；D4：不含任何模型清单，
+ * 清单只活在 system prompt 现值一份）。指路段按目标引擎参数化，与
+ * <current_subagent_engine> 恒在段的分界语义一致：目标 pi → 指向核心段
+ * <available_provider_models>；非 pi → 指向该引擎清单段 <available_<engine>_models>。
+ */
+export function buildEngineChangeNotice(from: string, to: string): string {
+  const modelsLine =
+    to === DEFAULT_ENGINE_ID
+      ? "Use pi-registry ids from <available_provider_models> for explicit models;"
+      : `Use ids from <available_${to}_models> for explicit models;`;
+  return [
+    `Subagent default engine changed: ${from} → ${to} (effective this turn).`,
+    modelsLine,
+    "omit `model` to inherit. The <current_subagent_engine> section reflects the current state.",
+  ].join("\n");
+}
+
+/** 检测编排依赖（注入式）。生产装配在 index.ts engine handler；测试用 stub。 */
+export interface EngineAwarenessDeps {
+  /** 三态读取全局 config（D5；生产 = () => readGlobalConfig(getAgentDir())）。 */
+  readConfig(): GlobalConfigReadResult;
+  /**
+   * D2：将本 turn 三态读取结果提交路由缓存（生产 = ModelConfigService.applyGlobalConfig，
+   * 纯赋值幂等；failed 已由编排层早退，到达此调用的必为 ok/absent）。
+   */
+  applyRead(read: GlobalConfigReadResult): void;
+  /** 对话流通知投递（D3；生产 = pi.sendMessage(message, {})，不设 triggerTurn）。 */
+  sendMessage(message: {
+    customType: string;
+    content: string;
+    display: boolean;
+    details?: unknown;
+  }): void;
+  /** per-session lastEngine 读取（undefined = 未基线化，D1b）。 */
+  getLastEngine(): string | undefined;
+  /** per-session lastEngine 写入（仅合法引擎 id，不写 undefined）。 */
+  setLastEngine(engine: string): void;
+}
+
+/** 单次 per-turn 检测的编排结果（测试断言面 + 诊断留痕消费）。 */
+export type EngineAwarenessOutcome =
+  | { outcome: "changed"; from: string; to: string }
+  | { outcome: "unchanged"; engine: string }
+  | { outcome: "baseline"; engine: string }
+  | { outcome: "read-failed"; reason: string };
+
+/**
+ * 单个 session 的 per-turn 引擎检测编排（§2.3 数据流 ①② 步；③ 渲染归 index.ts）。
+ *
+ * 分派（D5 三态 × D1b 基线）：
+ *   - read failed → 保持 lastEngine 不动、不提交缓存、不通知（防 torn write 瞬间伪通知）；
+ *     read-failure warn 日志由 readGlobalConfig 内部落，此处只返回结果。
+ *   - lastEngine === undefined（session_start 初始化读失败的兜底形态）→ 静默基线化为
+ *     当前目标值：不算变更、不发通知（防「changed: undefined → zcode」首 turn 伪通知）。
+ *   - last === target（absent 归一后同值也在内）→ 无事。
+ *   - last ≠ target（含 ENOENT=合法缺省）→ 提交缓存先行 → 通知 → 记账，三步同 turn。
+ *
+ * 抛错面：不主动 try-catch——readGlobalConfig 三态返回不抛，applyRead/sendMessage 的
+ * 生产实现各自吞错；handler 顶层 catch 兜底（fail-safe 不阻塞 agent loop）。
+ */
+export function runEngineAwarenessTurn(deps: EngineAwarenessDeps): EngineAwarenessOutcome {
+  const read = deps.readConfig();
+  if (read.status === "failed") {
+    return { outcome: "read-failed", reason: read.reason };
+  }
+  const target = normalizeEngineId(read.config.defaultEngine);
+  const last = deps.getLastEngine();
+  if (last === undefined) {
+    // D1b（修订）：基线化前把本 turn 读取结果提交到单例缓存。baseline 形态可能来自
+    // session_start 读取失败（lastEngine 未设置 + Service 缓存回落缺省）而文件此后被
+    // 修好——若只记账不提交，缓存/路由/状态段永停旧值且永不通知（「改 config 不生效」
+    // 以更隐蔽形态复活）。apply 纯赋值——检测值与缓存值构造性同源，重复提交无害。
+    deps.applyRead(read);
+    deps.setLastEngine(target);
+    return { outcome: "baseline", engine: target };
+  }
+  if (last === target) {
+    return { outcome: "unchanged", engine: target };
+  }
+  // D2 顺序硬约束：先提交读取结果到路由缓存（本 turn 路由 + 渲染同源生效）→ 再通知 → 再记账。
+  deps.applyRead(read);
+  deps.sendMessage({
+    customType: ENGINE_CHANGE_CUSTOM_TYPE,
+    content: buildEngineChangeNotice(last, target),
+    display: true,
+    details: { from: last, to: target },
+  });
+  deps.setLastEngine(target);
+  logger.debug(
+    `[engine-awareness] default engine changed: ${last} -> ${target} (route reloaded, notice sent)`,
+  );
+  return { outcome: "changed", from: last, to: target };
+}

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 "../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 };