@zhushanwen/pi-subagent-workflow 8.7.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

@@ -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

@@ -23,10 +23,6 @@ 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 现值一份）。指路段按目标引擎参数化，与

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