@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,749 @@
+// src/shared/__tests__/resource-discovery.test.ts
+//
+// 统一资源发现模块测试（ADR-031）。
+// 验证：扫描源覆盖、优先级合并、manifest 校验、约定目录 fallback。
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+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: () => mockHomeDir };
+});
+
+import {
+  discoverResources,
+  discoverResourcesSync,
+  findWorkspaceRoot,
+  processPackageSync,
+  getCachedFile,
+  getCachedFileContent,
+  __testResetShadowDedup,
+  __testInjectShadowDedupKey,
+  isMachineSource,
+  getCachedParsed,
+  clearFileCache,
+} from "../resource-discovery.ts";
+// logger 断言目标随源切换（u0-data-discovery）：resource-discovery 的 logger 是
+// core facade（同 component 单例引用），spyOn facade 实例即拦截模块内 logger 调用
+import { getLogger } from "../../core/logger.ts";
+
+// ============================================================
+// helpers
+// ============================================================
+
+function tmpWorkspace(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "res-disc-test-"));
+}
+
+/** 与 pi 壳 agentDirKindRoots 同构的注入根：由旧 ScanConfig.agentDir 入参等价推导
+ *  （user-pi 根 = <agentDir>/<kind>，npm 根 = <agentDir>/npm/node_modules，npm-dev
+ *  根 = <agentDir>/extensions）——扫描目录与形状改造前逐字一致，expected 断言不动。 */
+function hostRootsFor(agentDir: string, kind: "agents" | "workflows") {
+  return [
+    { dir: path.join(agentDir, kind), source: "user-pi" },
+    { dir: path.join(agentDir, "npm", "node_modules"), source: "npm" },
+    { dir: path.join(agentDir, "extensions"), source: "npm-dev" },
+  ];
+}
+
+function writeFile(dir: string, name: string, content: string): string {
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, name);
+  fs.writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
+function writePackageJson(pkgDir: string, pi: Record<string, unknown>): void {
+  fs.mkdirSync(pkgDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(pkgDir, "package.json"),
+    JSON.stringify({ name: "test-pkg", pi }),
+    "utf-8",
+  );
+}
+
+// ============================================================
+// findWorkspaceRoot
+// ============================================================
+
+describe("findWorkspaceRoot", () => {
+  it("returns cwd when no marker found", () => {
+    const ws = tmpWorkspace();
+    expect(findWorkspaceRoot(ws)).toBe(ws);
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("finds .git root", () => {
+    const ws = tmpWorkspace();
+    fs.mkdirSync(path.join(ws, ".git"));
+    const sub = path.join(ws, "sub", "deep");
+    fs.mkdirSync(sub, { recursive: true });
+    expect(findWorkspaceRoot(sub)).toBe(ws);
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+});
+
+// ============================================================
+// discoverResourcesSync — 扫描源覆盖 + 优先级
+// ============================================================
+
+describe("discoverResourcesSync", () => {
+  let ws: string;
+  let agentDir: string;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+    agentDir = path.join(ws, ".fake-agent");
+  });
+  afterEach(() => {
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("discovers agents from project .pi/agents/", () => {
+    writeFile(path.join(ws, ".pi", "agents"), "worker.md", "body");
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    // 按 source 过滤断言——用户全局目录（~/.agents/agents/）可能有真实 agent 文件，
+    // 测试不假设环境为空（2026-08：环境新增 tech-design-review.md 暴露此脆弱性）
+    const project = result.filter((r) => r.source === "project-pi");
+    expect(project.map((r) => path.basename(r.path))).toEqual(["worker.md"]);
+    expect(project[0]?.available).toBe(true);
+  });
+
+  it("discovers workflows from project .pi/workflows/", () => {
+    writeFile(path.join(ws, ".pi", "workflows"), "build.js", "const meta={name:'build'};");
+    const result = discoverResourcesSync({ kind: "workflows", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "workflows") });
+    expect(result.map((r) => path.basename(r.path))).toEqual(["build.js"]);
+  });
+
+  it("project .agents overrides project .pi on name clash (priority)", () => {
+    writeFile(path.join(ws, ".pi", "agents"), "worker.md", "pi-body");
+    writeFile(path.join(ws, ".agents", "agents"), "worker.md", "agents-body");
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const project = result.filter((r) => r.source === "project-agents");
+    expect(project).toHaveLength(1);
+    expect(project[0]?.source).toBe("project-agents");
+  });
+
+  it("includes tmp source for workflows when includeTmp=true", () => {
+    writeFile(path.join(ws, ".pi", "workflows", ".tmp"), "temp.js", "const meta={name:'temp'};");
+    const result = discoverResourcesSync({
+      kind: "workflows",
+      workspaceRoot: ws,
+      hostRoots: hostRootsFor(agentDir, "workflows"),
+      includeTmp: true,
+    });
+    expect(result.map((r) => path.basename(r.path))).toEqual(["temp.js"]);
+    expect(result[0]?.source).toBe("project-pi-tmp");
+  });
+
+  it("excludes tmp source when includeTmp omitted", () => {
+    writeFile(path.join(ws, ".pi", "workflows", ".tmp"), "temp.js", "x");
+    const result = discoverResourcesSync({ kind: "workflows", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "workflows") });
+    expect(result).toEqual([]);
+  });
+
+  it("ignores _ prefix and .chain.md files", () => {
+    const dir = path.join(ws, ".pi", "agents");
+    writeFile(dir, "real.md", "body");
+    writeFile(dir, "_skip.md", "ignored");
+    writeFile(dir, "trace.chain.md", "ignored");
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const project = result.filter((r) => r.source === "project-pi");
+    expect(project.map((r) => path.basename(r.path))).toEqual(["real.md"]);
+  });
+
+  it("nonexistent directories are silently skipped", () => {
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    // 用户全局目录可能有真实文件——只断言 project 源为空
+    expect(result.filter((r) => r.source === "project-pi" || r.source === "project-agents")).toEqual([]);
+  });
+});
+
+// ============================================================
+// processPackageSync — manifest 校验
+// ============================================================
+
+describe("processPackageSync", () => {
+  let pkgDir: string;
+
+  beforeEach(() => {
+    pkgDir = tmpWorkspace();
+  });
+  afterEach(() => {
+    fs.rmSync(pkgDir, { recursive: true, force: true });
+  });
+
+  it("loads from manifest directory declaration", () => {
+    writeFile(path.join(pkgDir, "agents"), "worker.md", "body");
+    writePackageJson(pkgDir, { agents: ["./agents"] });
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(true);
+  });
+
+  it("loads from manifest file declaration", () => {
+    writeFile(pkgDir, "worker.md", "body");
+    writePackageJson(pkgDir, { agents: ["./worker.md"] });
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(true);
+  });
+
+  it("manifest path not exists → available=false, no fallback", () => {
+    writePackageJson(pkgDir, { agents: ["./nonexistent"] });
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(false);
+    // 不 fallback 到约定目录
+    writeFile(path.join(pkgDir, "agents"), "hidden.md", "body");
+    const result2 = processPackageSync(pkgDir, "agents");
+    expect(result2).toHaveLength(1);
+    expect(result2[0]?.available).toBe(false);
+  });
+
+  it("no manifest → fallback to convention dir", () => {
+    writeFile(path.join(pkgDir, "agents"), "worker.md", "body");
+    // 无 package.json 或无 pi.agents
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(true);
+  });
+
+  it("no manifest and no convention dir → empty", () => {
+    writePackageJson(pkgDir, { extensions: ["./index.ts"] });
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toEqual([]);
+  });
+});
+
+// ============================================================
+// discoverResources (async) — 基本冒烟
+// ============================================================
+
+describe("discoverResources (async)", () => {
+  let ws: string;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+  });
+  afterEach(() => {
+    fs.rmSync(ws, { recursive: true, force: true });
+    __testResetShadowDedup();
+  });
+
+  it("discovers agents from project .pi/agents/ (async)", async () => {
+    writeFile(path.join(ws, ".pi", "agents"), "worker.md", "body");
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: hostRootsFor(path.join(ws, ".fake-agent"), "agents"),
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(true);
+  });
+
+  it("discovers workflows with tmp source (async)", async () => {
+    writeFile(path.join(ws, ".pi", "workflows"), "build.js", "x");
+    writeFile(path.join(ws, ".pi", "workflows", ".tmp"), "temp.js", "x");
+    const result = await discoverResources({
+      kind: "workflows",
+      workspaceRoot: ws,
+      hostRoots: hostRootsFor(path.join(ws, ".fake-agent"), "workflows"),
+      includeTmp: true,
+    });
+    expect(result).toHaveLength(2);
+  });
+});
+
+// ============================================================
+// user-extension-paths (XYZ_EXTENSION_PATHS) — dev-link 扩展发现
+// ============================================================
+
+describe("user-extension-paths (XYZ_EXTENSION_PATHS)", () => {
+  let ws: string;
+  let agentDir: string;
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+    agentDir = path.join(ws, ".fake-agent");
+    savedEnv = process.env.XYZ_EXTENSION_PATHS;
+  });
+  afterEach(() => {
+    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", () => {
+    const pkgDir = path.join(ws, "my-ext");
+    writePackageJson(pkgDir, { agents: ["./agents"] });
+    writeFile(path.join(pkgDir, "agents"), "custom.md", "body");
+    process.env.XYZ_EXTENSION_PATHS = pkgDir;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const ext = result.filter((r) => r.source === "user-extension-paths");
+    expect(ext.map((r) => path.basename(r.path))).toEqual(["custom.md"]);
+    expect(ext[0]?.source).toBe("user-extension-paths");
+  });
+
+  it("discovers agents via convention dir (no manifest)", () => {
+    const pkgDir = path.join(ws, "my-ext");
+    writeFile(path.join(pkgDir, "agents"), "conv.md", "body");
+    process.env.XYZ_EXTENSION_PATHS = pkgDir;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const ext = result.filter((r) => r.source === "user-extension-paths");
+    expect(ext.map((r) => path.basename(r.path))).toEqual(["conv.md"]);
+    expect(ext[0]?.source).toBe("user-extension-paths");
+  });
+
+  it("multiple paths separated by delimiter", () => {
+    const pkg1 = path.join(ws, "ext1");
+    const pkg2 = path.join(ws, "ext2");
+    writeFile(path.join(pkg1, "agents"), "a1.md", "body");
+    writeFile(path.join(pkg2, "agents"), "a2.md", "body");
+    process.env.XYZ_EXTENSION_PATHS = `${pkg1}${path.delimiter}${pkg2}`;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const ext = result.filter((r) => r.source === "user-extension-paths");
+    expect(ext.map((r) => path.basename(r.path)).sort()).toEqual(["a1.md", "a2.md"]);
+  });
+
+  it("overrides npm on name clash (priority: user-extension-paths > npm)", () => {
+    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 result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const shared = result.find((r) => path.basename(r.path) === "shared.md");
+    expect(shared?.source).toBe("user-extension-paths");
+  });
+
+  it("project-agents overrides user-extension-paths (project wins)", () => {
+    const devPkg = path.join(ws, "dev-ext");
+    writePackageJson(devPkg, { agents: ["./agents"] });
+    writeFile(path.join(devPkg, "agents"), "x.md", "dev-body");
+    writeFile(path.join(ws, ".agents", "agents"), "x.md", "project-body");
+    process.env.XYZ_EXTENSION_PATHS = devPkg;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const x = result.find((r) => path.basename(r.path) === "x.md");
+    expect(x?.source).toBe("project-agents");
+  });
+
+  it("empty/unset env → no user-extension-paths source", () => {
+    delete process.env.XYZ_EXTENSION_PATHS;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    expect(result.filter((r) => r.source === "user-extension-paths")).toEqual([]);
+  });
+
+  it("async discoverResources also scans user-extension-paths", async () => {
+    const pkgDir = path.join(ws, "my-ext");
+    writePackageJson(pkgDir, { agents: ["./agents"] });
+    writeFile(path.join(pkgDir, "agents"), "async.md", "body");
+    process.env.XYZ_EXTENSION_PATHS = pkgDir;
+    const result = await discoverResources({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const ext = result.filter((r) => r.source === "user-extension-paths");
+    expect(ext.map((r) => path.basename(r.path))).toEqual(["async.md"]);
+    expect(ext[0]?.source).toBe("user-extension-paths");
+  });
+
+  it("async: overrides npm on name clash (priority: user-extension-paths > npm)", async () => {
+    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 result = await discoverResources({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const shared = result.find((r) => path.basename(r.path) === "shared.md");
+    expect(shared?.source).toBe("user-extension-paths");
+  });
+
+  it("async: project-agents overrides user-extension-paths (project wins)", async () => {
+    const devPkg = path.join(ws, "dev-ext");
+    writePackageJson(devPkg, { agents: ["./agents"] });
+    writeFile(path.join(devPkg, "agents"), "x.md", "dev-body");
+    writeFile(path.join(ws, ".agents", "agents"), "x.md", "project-body");
+    process.env.XYZ_EXTENSION_PATHS = devPkg;
+    const result = await discoverResources({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+    const x = result.find((r) => path.basename(r.path) === "x.md");
+    expect(x?.source).toBe("project-agents");
+  });
+
+  it("async: 4 源混合 fixture——输出序 + 优先级 + 与串行版快照等价", async () => {
+    // 源优先级低→高：npm < user-extension-paths < project-pi < project-agents
+    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"), "dev.md", "dev-body");
+    writeFile(path.join(ws, ".pi", "agents"), "pi.md", "pi-body");
+    writeFile(path.join(ws, ".agents", "agents"), "shared.md", "project-body");
+    writeFile(path.join(ws, ".agents", "agents"), "proj.md", "proj-body");
+    process.env.XYZ_EXTENSION_PATHS = devPkg;
+    const config = { kind: "agents" as const, workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") };
+
+    const asyncResult = await discoverResources(config);
+
+    // 输出序：stem 首次插入位置固定（低优先级源先入 Map），同名后续覆盖值不移位
+    expect(asyncResult.map((r) => path.basename(r.path))).toEqual([
+      "shared.md", // 首现于 npm（最低源），位置固定
+      "dev.md", // user-extension-paths
+      "pi.md", // project-pi
+      "proj.md", // project-agents
+    ]);
+    // 优先级：shared.md 两源同名，project-agents（高）last-writer-wins
+    expect(asyncResult.find((r) => path.basename(r.path) === "shared.md")?.source).toBe(
+      "project-agents",
+    );
+    // 快照等价：源级并行 async 版与串行 sync 版输出逐项一致（含序与 source 标签）
+    expect(asyncResult).toEqual(discoverResourcesSync(config));
+  });
+
+  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, hostRoots: hostRootsFor(agentDir, "agents") });
+
+      // 遮蔽仍生效（last-writer-wins 语义不变）
+      expect(result.find((r) => path.basename(r.path) === "dup.md")?.source).toBe("project-agents");
+      // 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, hostRoots: hostRootsFor(agentDir, "agents") });
+
+      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, hostRoots: hostRootsFor(agentDir, "agents") });
+
+      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, hostRoots: hostRootsFor(agentDir, "agents") });
+        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, hostRoots: hostRootsFor(agentDir, "agents") });
+        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, hostRoots: hostRootsFor(agentDir, "agents") });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+
+        // 第二次调用——同 key 去重，不报
+        warnSpy.mockClear();
+        await discoverResources({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+        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, hostRoots: hostRootsFor(agentDir, "agents") });
+        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, hostRoots: hostRootsFor(agentDir, "agents") });
+        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, hostRoots: hostRootsFor(agentDir, "agents") });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        warnSpy.mockClear();
+
+        // 步骤 4：第三次调用——dedup key 在 set 中 → 去重跳过 warn
+        await discoverResources({ kind: "agents", workspaceRoot: ws, hostRoots: hostRootsFor(agentDir, "agents") });
+        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, hostRoots: hostRootsFor(agentDir, "agents") });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+      } finally {
+        warnSpy.mockRestore();
+        __testResetShadowDedup();
+      }
+    } finally {
+      fs.rmSync(userAgentsDir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── m5 TC4/TC5: 统一 mtime 缓存层（P-cache / P-cache-invalidation） ──
+
+describe("m5: 统一 mtime 缓存层", () => {
+  it("TC4a: P-cache——文件未变时二次读取命中同一缓存条目（对象引用）", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "m5-cache-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "---\nname: x\ndescription: y\n---\nbody", "utf-8");
+    try {
+      // ESM 下 node:fs 不可 spy（vitest 限制）——命中断言用对象引用：
+      // getCachedFile 命中时返回缓存条目对象本身（非新建）
+      const first = getCachedFile(f);
+      const second = getCachedFile(f);
+      expect(first?.content).toBe("---\nname: x\ndescription: y\n---\nbody");
+      expect(second).toBe(first); // 同引用 = 命中缓存（未重 read）
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("TC4b: P-cache——两处消费方（getCachedFile/getCachedFileContent）共享同一缓存条目", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "m5-cache2-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "---\nname: x\ndescription: y\n---\nbody", "utf-8");
+    try {
+      const a = getCachedFile(f);
+      const b = getCachedFileContent(f);
+      // 内容一致性（命中语义由 TC4a 的对象引用断言覆盖——此处验证两 API 一致）
+      expect(a?.content).toBe(b);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("TC5: P-cache-invalidation——改内容（mtime 变）后重读新内容；删文件后驱逐", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "m5-cache3-"));
+    const f = path.join(dir, "a.md");
+    fs.writeFileSync(f, "v1", "utf-8");
+    try {
+      expect(getCachedFileContent(f)).toBe("v1");
+      fs.writeFileSync(f, "v2", "utf-8");
+      expect(getCachedFileContent(f)).toBe("v2"); // mtime 变 → 重读
+      // 删除 → 驱逐（不再返回旧内容）
+      fs.rmSync(f);
+      expect(getCachedFileContent(f)).toBeNull();
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── 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 });
+    }
+  });
+});