@zhushanwen/pi-subagent-workflow 8.1.1 → 8.3.0

package/src/shared/__tests__/resource-discovery.test.ts

@@ -11,9 +11,18 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 // 隔离真实用户全局目录：resource-discovery 用 homedir() 推导 user-agents 源
 // （~/.agents/agents/），测试环境可能存在真实 agent 文件（如 tech-design-review.md），
 // 不 mock 会导致「期望空列表/精确列表」用例被环境污染（2026-08 实测 4 个失败）。
+// 用真实 tmpdir 下的子目录作 mock homedir（macOS SIP 禁止 mkdir /nonexistent-*）。
+const mockHomeDir = vi.hoisted(() => {
+  const fs = require("node:fs");
+  const os = require("node:os");
+  const path = require("node:path");
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "res-disc-home-"));
+  return dir;
+});
+
 vi.mock("node:os", async (importOriginal) => {
   const actual = await importOriginal<typeof import("node:os")>();
-  return { ...actual, homedir: () => "/nonexistent-home-for-tests" };
+  return { ...actual, homedir: () => mockHomeDir };
 });
 
 import {
@@ -23,6 +32,11 @@ import {
   processPackageSync,
   getCachedFile,
   getCachedFileContent,
+  __testResetShadowDedup,
+  __testInjectShadowDedupKey,
+  isMachineSource,
+  getCachedParsed,
+  clearFileCache,
 } from "../resource-discovery.ts";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
@@ -216,6 +230,7 @@ describe("discoverResources (async)", () => {
   });
   afterEach(() => {
     fs.rmSync(ws, { recursive: true, force: true });
+    __testResetShadowDedup();
   });
 
   it("discovers agents from project .pi/agents/ (async)", async () => {
@@ -260,6 +275,7 @@ describe("user-extension-paths (XYZ_EXTENSION_PATHS)", () => {
     if (savedEnv === undefined) delete process.env.XYZ_EXTENSION_PATHS;
     else process.env.XYZ_EXTENSION_PATHS = savedEnv;
     fs.rmSync(ws, { recursive: true, force: true });
+    __testResetShadowDedup();
   });
 
   it("discovers agents from XYZ_EXTENSION_PATHS via pi.agents manifest", () => {
@@ -390,26 +406,204 @@ describe("user-extension-paths (XYZ_EXTENSION_PATHS)", () => {
     expect(asyncResult).toEqual(discoverResourcesSync(config));
   });
 
-  it("async: 同名遮蔽时输出 warn（D8d 有检测必有报告）", async () => {
+  it("async: 同名遮蔽时机器源×机器源降 debug 不产生 warn（D8d 分级）", async () => {
     const npmPkg = path.join(agentDir, "npm", "node_modules", "test-pkg");
     writePackageJson(npmPkg, { agents: ["./agents"] });
     const npmFile = writeFile(path.join(npmPkg, "agents"), "dup.md", "npm-body");
     const projFile = writeFile(path.join(ws, ".agents", "agents"), "dup.md", "project-body");
     const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+    const debugSpy = vi.spyOn(getLogger("subagents"), "debug");
 
     try {
       const result = await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
 
       // 遮蔽仍生效（last-writer-wins 语义不变）
       expect(result.find((r) => path.basename(r.path) === "dup.md")?.source).toBe("project-agents");
-      // 但不再静默：warn 报告被遮蔽方与保留方路径（D8d「有检测无报告」修复）
-      expect(warnSpy).toHaveBeenCalledTimes(1);
-      const [msg, data] = warnSpy.mock.calls[0];
+      // npm 与 project-agents 均为机器源 → 降级 debug，不产生 warn
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(debugSpy).toHaveBeenCalledTimes(1);
+      const [msg, data] = debugSpy.mock.calls[0];
       expect(String(msg)).toContain('duplicate agents "dup"');
       expect(String(msg)).toContain("project-agents shadows npm");
       expect(data).toMatchObject({ shadowed: npmFile, kept: projFile });
     } finally {
       warnSpy.mockRestore();
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("(a) 机器源×用户源降 debug：npm vs user-pi 不产生 warn", async () => {
+    // npm 源（机器源）与 user-pi 源（用户源）——任一侧为机器源即降 debug
+    const npmPkg = path.join(agentDir, "npm", "node_modules", "test-pkg");
+    writePackageJson(npmPkg, { agents: ["./agents"] });
+    writeFile(path.join(npmPkg, "agents"), "dup.md", "npm-body");
+    // user-pi 源 = agentDir/<kind>/（agentDir 是独立于 homedir mock 的入参，
+    // mockHomeDir 由 vi.hoisted mkdtempSync 创建真实 tmpdir）
+    writeFile(path.join(agentDir, "agents"), "dup.md", "user-pi-body");
+    const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+    const debugSpy = vi.spyOn(getLogger("subagents"), "debug");
+
+    try {
+      await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(debugSpy).toHaveBeenCalled();
+      const [msg] = debugSpy.mock.calls[0];
+      expect(String(msg)).toContain('duplicate agents "dup"');
+    } finally {
+      warnSpy.mockRestore();
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("(a) npm vs user-extension-paths 机器源×机器源降 debug", async () => {
+    // 两个机器源同名（npm 包 vs XYZ_EXTENSION_PATHS 注入的 dev 包，后者 source 标签为 user-extension-paths）
+    const npmPkg = path.join(agentDir, "npm", "node_modules", "test-pkg");
+    writePackageJson(npmPkg, { agents: ["./agents"] });
+    writeFile(path.join(npmPkg, "agents"), "shared.md", "npm-body");
+    const devPkg = path.join(ws, "dev-ext");
+    writePackageJson(devPkg, { agents: ["./agents"] });
+    writeFile(path.join(devPkg, "agents"), "shared.md", "dev-body");
+    process.env.XYZ_EXTENSION_PATHS = devPkg;
+    const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+    const debugSpy = vi.spyOn(getLogger("subagents"), "debug");
+
+    try {
+      await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(debugSpy).toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("(b) 双用户源重复产生 warn 且同进程第二次 discoverResources 不重复（去重生效）", async () => {
+    // user-pi 与 user-agents 都是用户源——需要构造两个源都有同名文件
+    // user-pi = agentDir/agents/（buildScanTargets 第一个 target）
+    // user-agents = mockHomeDir/.agents/agents/（vi.hoisted 创建的真实 tmpdir）
+    const userAgentsDir = path.join(mockHomeDir, ".agents", "agents");
+    fs.mkdirSync(userAgentsDir, { recursive: true });
+    try {
+      // user-pi: agentDir/agents/dup.md
+      writeFile(path.join(agentDir, "agents"), "dup.md", "user-pi-body");
+      // user-agents: mockHomeDir/.agents/agents/dup.md
+      fs.writeFileSync(path.join(userAgentsDir, "dup.md"), "user-agents-body", "utf-8");
+
+      const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+
+      try {
+        // 第一次调用——应产生 warn（双用户源）
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        const [msg] = warnSpy.mock.calls[0];
+        expect(String(msg)).toContain('duplicate agents "dup"');
+
+        // 第二次调用——同进程去重，不再报
+        warnSpy.mockClear();
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).not.toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    } finally {
+      fs.rmSync(userAgentsDir, { recursive: true, force: true });
+    }
+  });
+
+  it("(c) path 变化（新 key）重新报 warn", async () => {
+    const userAgentsDir = path.join(mockHomeDir, ".agents", "agents");
+    fs.mkdirSync(userAgentsDir, { recursive: true });
+    try {
+      writeFile(path.join(agentDir, "agents"), "dup.md", "user-pi-body");
+      fs.writeFileSync(path.join(userAgentsDir, "dup.md"), "user-agents-body", "utf-8");
+
+      const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+
+      try {
+        // 第一次调用——报 warn
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+
+        // 第二次调用——同 key 去重，不报
+        warnSpy.mockClear();
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).not.toHaveBeenCalled();
+
+        // 真实 path 变化产生新 key：双用户目录各加一个不同 stem（dup2.md）
+        // → 新遮蔽对（新 stem 新 path）→ 新 key → 重新报
+        writeFile(path.join(agentDir, "agents"), "dup2.md", "user-pi-body-2");
+        fs.writeFileSync(path.join(userAgentsDir, "dup2.md"), "user-agents-body-2", "utf-8");
+        warnSpy.mockClear();
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        const [newMsg] = warnSpy.mock.calls[0];
+        expect(String(newMsg)).toContain('duplicate agents "dup2"');
+      } finally {
+        warnSpy.mockRestore();
+      }
+    } finally {
+      fs.rmSync(userAgentsDir, { recursive: true, force: true });
+    }
+  });
+
+  it("分级穷举：全部 8 个 ResourceSource 的机器/用户归属与 D3 一致", () => {
+    // 封闭枚举逐值断言，防止未来新增/修改枚举值时分级边界漂移
+    const machine: ResourceSource[] = ["npm", "npm-dev", "user-extension-paths", "project-pi", "project-pi-tmp", "project-agents"];
+    const user: ResourceSource[] = ["user-pi", "user-agents"];
+    for (const s of machine) expect(isMachineSource(s), `${s} 应为机器源`).toBe(true);
+    for (const s of user) expect(isMachineSource(s), `${s} 应为用户源`).toBe(false);
+  });
+
+  it("(d) cap 清空行为：超限后 clear 再 add，之前报过的 key 可重新报", async () => {
+    const userAgentsDir = path.join(mockHomeDir, ".agents", "agents");
+    fs.mkdirSync(userAgentsDir, { recursive: true });
+    try {
+      writeFile(path.join(agentDir, "agents"), "dup.md", "user-pi-body");
+      fs.writeFileSync(path.join(userAgentsDir, "dup.md"), "user-agents-body", "utf-8");
+
+      const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+
+      try {
+        // 步骤 1：首次调用——报 warn，dedup key 加入 set
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        warnSpy.mockClear();
+
+        // 步骤 2：重置 set，注入 1024 个虚拟 key（不含 dedup key）
+        // 使 set.size = MAX，dedup key 不在 set 中
+        __testResetShadowDedup();
+        for (let i = 0; i < 1024; i++) {
+          __testInjectShadowDedupKey(`fake|key${i}|/a|/b`);
+        }
+
+        // 步骤 3：第二次调用——dedup key 不在 set → 进 else 分支 →
+        // size(1024) >= MAX(1024) → clear() → set 空 → add dedup key → warn
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        warnSpy.mockClear();
+
+        // 步骤 4：第三次调用——dedup key 在 set 中 → 去重跳过 warn
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).not.toHaveBeenCalled();
+
+        // 步骤 5：再次填充到 cap——重置 + 注入 1024 个虚拟 key
+        // dedup key（步骤 3 add 的）已被 reset 清除
+        __testResetShadowDedup();
+        for (let i = 0; i < 1024; i++) {
+          __testInjectShadowDedupKey(`fake2|key${i}|/a|/b`);
+        }
+
+        // 步骤 6：第四次调用——cap 再次触发 clear → dedup key 重新报
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+      } finally {
+        warnSpy.mockRestore();
+        __testResetShadowDedup();
+      }
+    } finally {
+      fs.rmSync(userAgentsDir, { recursive: true, force: true });
     }
   });
 });
@@ -463,3 +657,80 @@ describe("m5: 统一 mtime 缓存层", () => {
     }
   });
 });
+
+// ── KV-cache 稳定性改造：解析结果缓存 getCachedParsed ──
+
+describe("getCachedParsed（mtime 级解析缓存）", () => {
+  beforeEach(() => {
+    clearFileCache();
+  });
+
+  it("mtime 未变时 parse 只跑一次（缓存解析结果）", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "parsed-cache-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "---\nname: x\ndescription: y\n---", "utf-8");
+    try {
+      const parse = vi.fn((content: string) => (content.includes("name: x") ? "OK" : "BAD"));
+      const first = getCachedParsed(f, parse);
+      const second = getCachedParsed(f, parse);
+      expect(first).toBe("OK");
+      expect(second).toBe("OK");
+      expect(parse).toHaveBeenCalledTimes(1); // 第二次命中缓存，不重 parse
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("mtime 变后重新 parse；文件删除后返回 null 并驱逐", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "parsed-cache2-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "v1", "utf-8");
+    try {
+      const parse = (content: string) => content;
+      expect(getCachedParsed(f, parse)).toBe("v1");
+      fs.writeFileSync(f, "v2", "utf-8");
+      expect(getCachedParsed(f, parse)).toBe("v2"); // mtime 变 → 重新 parse
+      fs.rmSync(f);
+      expect(getCachedParsed(f, parse)).toBeNull(); // 删除 → null
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("clearFileCache 同时清空解析缓存", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "parsed-cache3-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "content", "utf-8");
+    try {
+      const parse = vi.fn(() => "OK");
+      getCachedParsed(f, parse);
+      clearFileCache();
+      getCachedParsed(f, parse);
+      expect(parse).toHaveBeenCalledTimes(2); // 缓存被清 → 重新 parse
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("同一 path 的不同 parse 各自独立缓存（缓存键含 parse 身份，防跨 parse 污染）", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "parsed-cache4-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "shared-content", "utf-8");
+    try {
+      // 模拟真实双 parse 场景：parseAgentFrontmatter vs parseWorkflowMeta 对同一
+      // path（agent 与 workflow 发现源理论上可命中同一路径）各自解析
+      const parseA = (content: string) => ({ kind: "agent" as const, content });
+      const parseW = (content: string) => ({ kind: "workflow" as const, len: content.length });
+      const a1 = getCachedParsed(f, parseA);
+      // 修复前：缓存键只有 path，这里会命中 parseA 的缓存条目并 as T 断言返回
+      // {kind:"agent"}——w1 被污染成错误类型
+      const w1 = getCachedParsed(f, parseW);
+      const a2 = getCachedParsed(f, parseA);
+      expect(a1).toEqual({ kind: "agent", content: "shared-content" });
+      expect(w1).toEqual({ kind: "workflow", len: 14 });
+      expect(a2).toEqual({ kind: "agent", content: "shared-content" });
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/shared/resource-discovery.ts

@@ -21,6 +21,22 @@ import { getLogger } from "@zhushanwen/pi-extension-logger";
 // 模块级 logger（setPiHandle 注入后自动走 appendEntry，未注入时 console 兜底）
 const logger = getLogger("subagents");
 
+// [D8d] warn 路径进程内去重集合：key=(kind, stem, shadowedPath, keptPath)，
+// cap 1024 超限先清空再 add（对齐 ui-request-observability 的 MAX_WARNED_SESSIONS 范式）。
+// debug 路径不去重（默认 no-op，无成本）。
+const shadowWarnDedup = new Set<string>();
+const MAX_SHADOW_WARN_DEDUP = 1024;
+
+/** @internal 测试辅助：重置 warn 去重集合（cap 测试用，生产代码不调用）。 */
+export function __testResetShadowDedup(): void {
+  shadowWarnDedup.clear();
+}
+
+/** @internal 测试辅助：向 warn 去重集合注入 key（cap 测试用）。 */
+export function __testInjectShadowDedupKey(key: string): void {
+  shadowWarnDedup.add(key);
+}
+
 // ── 类型 ─────────────────────────────────────────────────────
 
 /** 资源种类：agent 或 workflow */
@@ -53,6 +69,23 @@ export interface ScanConfig {
 
 // ── 常量 ─────────────────────────────────────────────────────
 
+/** 机器源集合：包管理/工程配置产物，其同名重复是安装拓扑常态（非用户配置错误）。
+ *  用户个人源（user-pi / user-agents）不在此列——双个人源同名重复保留 warn。 */
+const MACHINE_SOURCES: ReadonlySet<ResourceSource> = new Set<ResourceSource>([
+  "npm",
+  "npm-dev",
+  "user-extension-paths",
+  "project-pi",
+  "project-pi-tmp",
+  "project-agents",
+]);
+
+/** 判断 source 是否属于机器源（安装拓扑常态，同名重复降 debug）。
+ *  导出仅为测试穷举断言用（封闭 8 值枚举 × 分级边界）。 */
+export function isMachineSource(source: ResourceSource): boolean {
+  return MACHINE_SOURCES.has(source);
+}
+
 /** workspace root 向上查找的最大深度 */
 const WORKSPACE_ROOT_MAX_DEPTH = 20;
 
@@ -174,11 +207,49 @@ export function getCachedFileContent(filePath: string): string | null {
   return getCachedFile(filePath)?.content ?? null;
 }
 
+// [perf] 解析结果缓存（KV-cache 稳定性改造）：外层 key = parse 函数身份，内层 key =
+// path，value = { mtimeMs, parsed }。key 含 parse 身份是正确性要求——同一 path 可能被
+// 不同 parse（agent frontmatter vs workflow meta）解析，单层 path key 会跨 parse 类型
+// 互相污染缓存（先 parse 的结果被 as T 断言返回）。用普通 Map 而非 WeakMap：
+// clearFileCache 需全量清空（测试隔离），WeakMap 不可遍历；parse 函数均为模块级
+// 常量，强引用无泄漏。复用 getCachedFile 的 mtime 判变——mtime 未变时跳过 parse
+// （frontmatter YAML 解析是重建发现时最大的可省 CPU 项）。parse 的确定性结果（含
+// null，如 frontmatter 非法）均可缓存：同一 content 必然解析出同一结果。失效与
+// mtimeCache 同步（clearFileCache）。
+const parsedCache = new Map<
+  (content: string) => unknown,
+  Map<string, { mtimeMs: number; parsed: unknown }>
+>();
+
+/**
+ * mtime 级解析结果缓存：mtime 未变返回缓存 parsed，变则经 getCachedFile 取 content
+ * 重新 parse 并缓存。文件不存在/不可读 → null（并驱逐条目）。缓存按 parse 函数隔离
+ * ——同一 path 的不同 parse 互不污染。
+ */
+export function getCachedParsed<T>(filePath: string, parse: (content: string) => T): T | null {
+  const file = getCachedFile(filePath);
+  let perParse = parsedCache.get(parse);
+  if (!file) {
+    perParse?.delete(filePath);
+    return null;
+  }
+  if (!perParse) {
+    perParse = new Map();
+    parsedCache.set(parse, perParse);
+  }
+  const entry = perParse.get(filePath);
+  if (entry && entry.mtimeMs === file.mtimeMs) return entry.parsed as T;
+  const parsed = parse(file.content);
+  perParse.set(filePath, { mtimeMs: file.mtimeMs, parsed });
+  return parsed;
+}
+
 /** 清空（invalidateCache 语义——测试隔离 + mtime 漏判场景手动刷新兜底）。 */
 export function clearFileCache(): void {
   mtimeCache.clear();
   workspaceRootCache.clear();
   manifestCache.clear();
+  for (const perParse of parsedCache.values()) perParse.clear();
 }
 
 export function findWorkspaceRoot(cwd?: string): string {
@@ -541,13 +612,29 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
       if (!r.available && existing) {
         continue;
       }
-      // [D8d] 同名遮蔽可观测：高优先级源覆盖低优先级同名资源时 warn——此前
-      // 「有检测无报告」，用户自定义 agent/workflow 被静默遮蔽后排查无从下手。
+      // [D8d] 同名遮蔽可观测：高优先级源覆盖低优先级同名资源时分级报告——
+      // 机器源重复是安装拓扑常态（npm 包与用户目录结构性同名），降 debug 默认静默
+      // （XYZ_AGENT_DEBUG=1 文件日志可查）；双用户源重复是配置错误，保留 warn 首报。
+      // warn 路径进程内去重（Set cap 1024，对齐 ui-request-observability 范式）：
+      // 每 session 独立进程（process-manager.ts L142-143），进程级去重 ≈ session 级首报。
       if (existing && existing.path !== r.path) {
-        logger.warn(
-          `[resource-discovery] duplicate ${config.kind} "${key}" from ${r.source} shadows ${existing.source}`,
-          { shadowed: existing.path, kept: r.path },
-        );
+        const msg =
+          `[resource-discovery] duplicate ${config.kind} "${key}" from ${r.source} shadows ${existing.source}`;
+        const data = { shadowed: existing.path, kept: r.path };
+        if (isMachineSource(existing.source) || isMachineSource(r.source)) {
+          // 任一侧为机器源 → 降级 debug（安装拓扑常态，排查走 XYZ_AGENT_DEBUG=1）
+          logger.debug(msg, data);
+        } else {
+          // 双侧均为用户源 → 保持 warn，进程内去重（同 key 只报首次）
+          const dedupKey = `${config.kind}|${key}|${existing.path}|${r.path}`;
+          if (!shadowWarnDedup.has(dedupKey)) {
+            if (shadowWarnDedup.size >= MAX_SHADOW_WARN_DEDUP) {
+              shadowWarnDedup.clear();
+            }
+            shadowWarnDedup.add(dedupKey);
+            logger.warn(msg, data);
+          }
+        }
       }
       merged.set(key, r);
     }

package/src/shared/xml-injection.ts

@@ -0,0 +1,35 @@
+// src/shared/xml-injection.ts
+//
+// XML 注入段渲染共享原语——subagent / workflow / model 三个 injector 的 format
+// 函数曾是三份手写同构（escapeXml 逐字重复 + 同一段落骨架），提取此模块消除重复。
+// 调用方保留各自的排序契约与条目渲染（字段差异大，不强行归一）。
+
+/**
+ * 转义 XML 特殊字符（注入段进每 turn system prompt，内容含 < > & 等会破坏
+ * XML 结构——全部字段过一遍转义防注入段破碎）。
+ */
+export function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+/**
+ * XML 注入段渲染骨架：`"\n\n<tag>"` 前导（衔接宿主 prompt 末尾）+ 引导语 +
+ * 条目行 + 闭合标签，以 "\n" join。空条目返回空串（不注入）。
+ *
+ * 三个 injector 共用此骨架保证段落结构逐字节同构；KV-cache 契约（顺序稳定 =
+ * 注入段字节稳定）由调用方排序保证，本函数不重排。
+ */
+export function renderXmlSection(section: {
+	tag: string;
+	guide: string;
+	items: string[];
+}): string {
+	if (section.items.length === 0) return "";
+	const lines = [`\n\n<${section.tag}>`, section.guide, ...section.items, `</${section.tag}>`];
+	return lines.join("\n");
+}