@zhushanwen/subagent-core 0.2.0 → 0.4.0

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

@@ -0,0 +1,474 @@
+// src/shared/__tests__/resource-discovery-host-roots.test.ts
+//
+// C2-core-discovery（convergence W2）单元测试：发现链扩面四工作项的行为锁定。
+// 覆盖：async 链 realpath 去重（W2①）、project-host 槽位（W2②）、hostRoots 同标签
+// 多根语义（W2④，Map→列表 + 硬编码槽合并原根后置）、单层扫描维持（红线 3）、
+// pi 单条目形态回归快照（回归红线：Map→列表是行为敏感改动）。
+// 设计权威源：docs/design/subagent-core-convergence.md §3.2 D-2 / §3.3 红线 1-4。
+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";
+
+// 隔离真实用户全局目录（~/.agents/agents/）——与 resource-discovery.test.ts 同款
+// 手法：mock homedir 到真实 tmpdir 子目录（macOS SIP 禁止 mkdir /nonexistent-*）。
+const mockHomeDir = vi.hoisted(() => {
+  const fs = require("node:fs");
+  const os = require("node:os");
+  const path = require("node:path");
+  return fs.mkdtempSync(path.join(os.tmpdir(), "res-disc-hr-home-"));
+});
+
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return { ...actual, homedir: () => mockHomeDir };
+});
+
+import { discoverResources } from "../resource-discovery.ts";
+// logger spy 断言（facade 同 component 单例引用，spyOn 即拦截模块内 logger 调用）
+import { getLogger } from "../../core/logger.ts";
+import type { DiscoveryRoot } from "../../core/host-services.ts";
+
+// ============================================================
+// helpers（与 resource-discovery.test.ts 同构）
+// ============================================================
+
+function tmpWorkspace(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "res-disc-hr-"));
+}
+
+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 ? { pi } : {}) }),
+    "utf-8",
+  );
+}
+
+/** pi 壳单条目形态三根（agentDirKindRoots 同构）：user-pi / npm / npm-dev。 */
+function piHostRoots(agentDir: string, kind: "agents" | "workflows"): DiscoveryRoot[] {
+  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" },
+  ];
+}
+
+// ============================================================
+// W2①: async 链 realpath 去重（多链同文件）
+// ============================================================
+
+describe("C2 W2①: async 链 realpath 去重", () => {
+  let ws: string;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+  });
+  afterEach(() => {
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("多链同文件（a.md 本体 + b.md symlink → a.md）清单只留 1 条", async () => {
+    const agentDir = path.join(ws, ".fake-agent");
+    const dir = path.join(agentDir, "agents");
+    const realFile = writeFile(dir, "a.md", "shared-body");
+    fs.symlinkSync(realFile, path.join(dir, "b.md"));
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: piHostRoots(agentDir, "agents"),
+    });
+
+    // stem 去重（a/b 不同 stem）防不住多链同文件——realpath 归一后只留首遇者 a.md
+    expect(result).toHaveLength(1);
+    expect(result[0]?.path).toBe(realFile);
+    expect(result[0]?.source).toBe("user-pi");
+  });
+
+  it("多链同文件不是遮蔽——不产生 duplicate 遮蔽报告（warn/debug 均无）", async () => {
+    const agentDir = path.join(ws, ".fake-agent");
+    const dir = path.join(agentDir, "agents");
+    const realFile = writeFile(dir, "a.md", "shared-body");
+    fs.symlinkSync(realFile, path.join(dir, "b.md"));
+
+    const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+    const debugSpy = vi.spyOn(getLogger("subagents"), "debug");
+    try {
+      await discoverResources({
+        kind: "agents",
+        workspaceRoot: ws,
+        hostRoots: piHostRoots(agentDir, "agents"),
+      });
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(debugSpy).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("跨源多链同文件同样归一（user-pi 链 + user-agents 硬编码根链 → 1 条）", async () => {
+    const agentDir = path.join(ws, ".fake-agent");
+    // 物理文件在 ws 库目录；user-pi 根与 user-agents 硬编码根各挂一个不同名 symlink
+    const libFile = writeFile(path.join(ws, "lib"), "origin.md", "lib-body");
+    const userPiLink = path.join(agentDir, "agents", "alpha.md");
+    fs.mkdirSync(path.dirname(userPiLink), { recursive: true });
+    fs.symlinkSync(libFile, userPiLink);
+    const userAgentsLink = path.join(mockHomeDir, ".agents", "agents", "beta.md");
+    fs.mkdirSync(path.dirname(userAgentsLink), { recursive: true });
+    fs.symlinkSync(libFile, userAgentsLink);
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: piHostRoots(agentDir, "agents"),
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.path).toBe(userPiLink); // 首遇者（user-pi 序位在前）
+    expect(result[0]?.source).toBe("user-pi");
+    // 清理 mockHome 内 fixture
+    fs.rmSync(userAgentsLink, { force: true });
+  });
+
+  it("同 stem 不同物理文件仍按 last-writer-wins 覆盖（realpath 去重不伤遮蔽语义）", async () => {
+    const agentDir = path.join(ws, ".fake-agent");
+    writeFile(path.join(agentDir, "agents"), "clash.md", "user-pi-body");
+    writeFile(path.join(ws, ".agents", "agents"), "clash.md", "project-body");
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: piHostRoots(agentDir, "agents"),
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.source).toBe("project-agents"); // 高优先级覆盖，语义不变
+    expect(result[0]?.path).toBe(path.join(ws, ".agents", "agents", "clash.md"));
+  });
+});
+
+// ============================================================
+// W2④: hostRoots 同标签多根语义（Map→列表）
+// ============================================================
+
+describe("C2 W2④: hostRoots 同标签多根语义", () => {
+  let ws: string;
+  let agentDir: string;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+    agentDir = path.join(ws, ".fake-agent");
+  });
+  afterEach(() => {
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("同标签两条 user-pi 根都被扫描（非靠后者整体覆盖）", async () => {
+    const root1 = path.join(ws, "multi-root-a");
+    const root2 = path.join(ws, "multi-root-b");
+    writeFile(root1, "one.md", "one");
+    writeFile(root2, "two.md", "two");
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: [
+        { dir: root1, source: "user-pi" },
+        { dir: root2, source: "user-pi" },
+        { dir: path.join(agentDir, "npm", "node_modules"), source: "npm" },
+        { dir: path.join(agentDir, "extensions"), source: "npm-dev" },
+      ],
+    });
+
+    // 旧 Map 语义：root2 覆盖 root1 → one.md 消失；列表语义：两根同序位依次扫描
+    const userPi = result.filter((r) => r.source === "user-pi");
+    expect(userPi.map((r) => path.basename(r.path)).sort()).toEqual(["one.md", "two.md"]);
+  });
+
+  it("同标签多根 + 同 stem 撞名：后注入的本体根胜（红线 2 本体在后）", async () => {
+    // 宿主（zsw）注入形态：目录 symlink 展开目标在前、本体根在后
+    const expanded = path.join(ws, "expanded-from-lib");
+    const own = path.join(ws, "own-agents");
+    writeFile(expanded, "shared.md", "lib-body");
+    writeFile(own, "shared.md", "own-body");
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: [
+        { dir: expanded, source: "user-pi" },
+        { dir: own, source: "user-pi" },
+        { dir: path.join(agentDir, "npm", "node_modules"), source: "npm" },
+        { dir: path.join(agentDir, "extensions"), source: "npm-dev" },
+      ],
+    });
+
+    expect(result).toHaveLength(1);
+    // core 合并 last-writer-wins（靠后者胜）→ 本体根注入在后 = 本体胜
+    expect(result[0]?.path).toBe(path.join(own, "shared.md"));
+    expect(result[0]?.source).toBe("user-pi");
+  });
+
+  it("user-agents 标签注入与硬编码根合并（硬编码本体根在后 = 硬编码胜）", async () => {
+    const injected = path.join(ws, "inj-agents");
+    writeFile(injected, "h.md", "injected-body");
+    const hardFile = writeFile(path.join(mockHomeDir, ".agents", "agents"), "h.md", "hard-body");
+
+    try {
+      const result = await discoverResources({
+        kind: "agents",
+        workspaceRoot: ws,
+        hostRoots: [
+          { dir: injected, source: "user-agents" },
+          { dir: path.join(agentDir, "npm", "node_modules"), source: "npm" },
+          { dir: path.join(agentDir, "extensions"), source: "npm-dev" },
+        ],
+      });
+
+      expect(result).toHaveLength(1);
+      // 注入条目在前、硬编码根（本体）在后——last-writer-wins 落硬编码
+      expect(result[0]?.path).toBe(hardFile);
+      expect(result[0]?.source).toBe("user-agents");
+    } finally {
+      fs.rmSync(path.join(mockHomeDir, ".agents", "agents", "h.md"), { force: true });
+    }
+  });
+
+  it("project-agents 标签注入与硬编码根合并（硬编码本体根在后 = 硬编码胜）", async () => {
+    const injected = path.join(ws, "inj-proj-agents");
+    writeFile(injected, "p.md", "injected-body");
+    const hardFile = writeFile(path.join(ws, ".agents", "agents"), "p.md", "hard-body");
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: [
+        { dir: injected, source: "project-agents" },
+        { dir: path.join(agentDir, "npm", "node_modules"), source: "npm" },
+        { dir: path.join(agentDir, "extensions"), source: "npm-dev" },
+      ],
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.path).toBe(hardFile);
+    expect(result[0]?.source).toBe("project-agents");
+  });
+
+  it("project-host 标签同标签多根依注入序生效（project-host 支持列表语义）", async () => {
+    const r1 = path.join(ws, "ph-root-a");
+    const r2 = path.join(ws, "ph-root-b");
+    writeFile(r1, "ph1.md", "one");
+    writeFile(r2, "ph2.md", "two");
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: [
+        { dir: r1, source: "project-host" },
+        { dir: r2, source: "project-host" },
+      ],
+    });
+
+    const ph = result.filter((r) => r.source === "project-host");
+    expect(ph.map((r) => path.basename(r.path)).sort()).toEqual(["ph1.md", "ph2.md"]);
+  });
+});
+
+// ============================================================
+// W2②: project-host 槽位序位
+// ============================================================
+
+describe("C2 W2②: project-host 槽位序位", () => {
+  let ws: string;
+  let agentDir: string;
+  let hostRoot: string;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+    agentDir = path.join(ws, ".fake-agent");
+    hostRoot = path.join(ws, ".zcode", "agents");
+  });
+  afterEach(() => {
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("project-host 同名被 project-agents 遮蔽（project-agents 是项目级最高逃生门）", async () => {
+    writeFile(hostRoot, "clash.md", "host-body");
+    writeFile(path.join(ws, ".agents", "agents"), "clash.md", "proj-body");
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: [
+        ...piHostRoots(agentDir, "agents"),
+        { dir: hostRoot, source: "project-host" },
+      ],
+    });
+
+    const clash = result.find((r) => path.basename(r.path) === "clash.md");
+    expect(clash?.source).toBe("project-agents");
+    expect(clash?.path).toBe(path.join(ws, ".agents", "agents", "clash.md"));
+  });
+
+  it("project-host 压过 project-pi（序位：project-pi < project-pi-tmp < project-host）", async () => {
+    writeFile(path.join(ws, ".pi", "agents"), "ph.md", "pi-body");
+    writeFile(hostRoot, "ph.md", "host-body");
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: [
+        ...piHostRoots(agentDir, "agents"),
+        { dir: hostRoot, source: "project-host" },
+      ],
+    });
+
+    const ph = result.find((r) => path.basename(r.path) === "ph.md");
+    expect(ph?.source).toBe("project-host");
+    expect(ph?.path).toBe(path.join(hostRoot, "ph.md"));
+  });
+
+  it("宿主未注入 project-host 标签时槽位缺席（输出无 project-host 条目）", async () => {
+    writeFile(path.join(ws, ".pi", "agents"), "only.md", "body");
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: piHostRoots(agentDir, "agents"),
+    });
+    expect(result.filter((r) => r.source === "project-host")).toEqual([]);
+    expect(result.map((r) => path.basename(r.path))).toEqual(["only.md"]);
+  });
+});
+
+// ============================================================
+// 红线 3: 单层扫描维持（不递归 / node_modules 不灌清单）
+// ============================================================
+
+describe("C2 红线 3: 单层扫描维持", () => {
+  let ws: string;
+  let agentDir: string;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+    agentDir = path.join(ws, ".fake-agent");
+  });
+  afterEach(() => {
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("子目录不递归（nested/deep.md 不入清单）", async () => {
+    writeFile(path.join(ws, ".pi", "agents", "nested"), "deep.md", "body");
+    writeFile(path.join(ws, ".pi", "agents"), "top.md", "body");
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: piHostRoots(agentDir, "agents"),
+    });
+
+    const project = result.filter((r) => r.source === "project-pi");
+    expect(project.map((r) => path.basename(r.path))).toEqual(["top.md"]);
+  });
+
+  it("源目录内 node_modules 目录在单层语义下不灌清单", async () => {
+    // user-pi 根内的 node_modules/ 是目录（非 .md 文件）——单层扫描不展开
+    writeFile(path.join(agentDir, "agents", "node_modules", "some-pkg"), "pkg-agent.md", "body");
+    writeFile(path.join(agentDir, "agents"), "real.md", "body");
+
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      hostRoots: piHostRoots(agentDir, "agents"),
+    });
+
+    const userPi = result.filter((r) => r.source === "user-pi");
+    expect(userPi.map((r) => path.basename(r.path))).toEqual(["real.md"]);
+  });
+});
+
+// ============================================================
+// 回归红线: pi 单条目形态快照（Map→列表行为敏感改动的锁定）
+// ============================================================
+
+describe("C2 回归红线: pi 单条目形态快照", () => {
+  let ws: string;
+  let agentDir: string;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+    agentDir = path.join(ws, ".fake-agent");
+  });
+  afterEach(() => {
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("与 pi 真实 agentDir 同构 fixture——source 标签与胜出路径逐项稳定", async () => {
+    // fixture 同构本机真实 agentDir（probe-c2 探针 2026-08-30 输出形态）：
+    // user-pi 三文件 / npm 包 10 内置角色（pi.agents manifest）/ user-agents 撞名
+    // tech-design-review / npm-dev 一包 / project 两源为空
+    writeFile(path.join(agentDir, "agents"), "general-purpose.md", "user-pi-gp");
+    writeFile(path.join(agentDir, "agents"), "tech-design-review.md", "user-pi-tdr");
+    writeFile(path.join(agentDir, "agents"), "vision-analyze.md", "user-pi-va");
+    writeFile(path.join(mockHomeDir, ".agents", "agents"), "tech-design-review.md", "user-agents-tdr");
+
+    const npmPkg = path.join(agentDir, "npm", "node_modules", "@zhushanwen", "pi-subagent-workflow");
+    writePackageJson(npmPkg, { agents: ["./agents"] });
+    for (const role of [
+      "general-purpose", "analyst", "coder", "debugger", "doc-reviewer",
+      "explorer", "orchestrator", "planner", "researcher", "reviewer",
+    ]) {
+      writeFile(path.join(npmPkg, "agents"), `${role}.md`, `npm-${role}`);
+    }
+
+    const devPkg = path.join(agentDir, "extensions", "local-dev-pkg");
+    writePackageJson(devPkg); // 无 pi manifest → 约定目录
+    writeFile(path.join(devPkg, "agents"), "dev-extra.md", "npm-dev-body");
+
+    try {
+      const result = await discoverResources({
+        kind: "agents",
+        workspaceRoot: ws,
+        hostRoots: piHostRoots(agentDir, "agents"),
+      });
+
+      // 逐项断言（序 = stem 首插序，值 = last-writer-wins 胜出者）：
+      // 前 3 个 stem 首插于 user-pi（真实探针同构），general-purpose 被 npm 覆盖、
+      // tech-design-review 被 user-agents 覆盖（胜出 source/路径随之变化、位置不动）
+      expect(
+        result.map((r) => ({ source: r.source, base: path.basename(r.path) })),
+      ).toEqual([
+        { source: "npm", base: "general-purpose.md" },
+        { source: "user-agents", base: "tech-design-review.md" },
+        { source: "user-pi", base: "vision-analyze.md" },
+        { source: "npm", base: "analyst.md" },
+        { source: "npm", base: "coder.md" },
+        { source: "npm", base: "debugger.md" },
+        { source: "npm", base: "doc-reviewer.md" },
+        { source: "npm", base: "explorer.md" },
+        { source: "npm", base: "orchestrator.md" },
+        { source: "npm", base: "planner.md" },
+        { source: "npm", base: "researcher.md" },
+        { source: "npm", base: "reviewer.md" },
+        { source: "npm-dev", base: "dev-extra.md" },
+      ]);
+      // 胜出路径逐项锚定（绝对路径，非仅 basename）
+      expect(result[0]?.path).toBe(path.join(npmPkg, "agents", "general-purpose.md"));
+      expect(result[1]?.path).toBe(path.join(mockHomeDir, ".agents", "agents", "tech-design-review.md"));
+      expect(result[2]?.path).toBe(path.join(agentDir, "agents", "vision-analyze.md"));
+      expect(result[12]?.path).toBe(path.join(devPkg, "agents", "dev-extra.md"));
+    } finally {
+      fs.rmSync(path.join(mockHomeDir, ".agents", "agents", "tech-design-review.md"), { force: true });
+    }
+  });
+});

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

@@ -561,9 +561,10 @@ describe("user-extension-paths (XYZ_EXTENSION_PATHS)", () => {
     }
   });
 
-  it("分级穷举：全部 8 个 ResourceSource 的机器/用户归属与 D3 一致", () => {
+  it("分级穷举：全部 9 个 ResourceSource 的机器/用户归属与 D3 一致", () => {
     // 封闭枚举逐值断言，防止未来新增/修改枚举值时分级边界漂移
-    const machine: ResourceSource[] = ["npm", "npm-dev", "user-extension-paths", "project-pi", "project-pi-tmp", "project-agents"];
+    // （W2② 新增 project-host——项目级宿主注入根，机器源）
+    const machine: ResourceSource[] = ["npm", "npm-dev", "user-extension-paths", "project-pi", "project-pi-tmp", "project-host", "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);

package/src/shared/agent-ref.ts

@@ -8,6 +8,13 @@
  *
  * 名字不再是引用——只是注入段展示标签。执行侧拿到引用后一律 normalizeRef →
  * 文件加载（AgentRegistry.loadByPath / WorkflowScriptRegistry.getPath）。
+ *
+ * `..` 路径段拒绝（sink 设计 ⛔2 声明的安全收紧，agent .md 与 workflow .js 引用
+ * 同受此面——两宿主现状均放行，非等值变更）：`/x/../y.md` 形态允许引用逃逸出
+ * 注入段声明的目录集（G1 例 2），引用串含 `..` 段一律拒绝。检测在 `~/` 展开前的
+ * 原始引用上——join 展开会 normalize 消解 `..` 段（`~/../x` → `<home>/../x` 被解析
+ * 成已消解路径），原始串检测使 `~/../x.md` 与 `/x/../y.md` 同判（`..` 逃逸向量与
+ * 前缀形态无关）。保留 `.` 段与 `~/` 展开——最小收紧，不伤合法引用。
  */
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
@@ -16,15 +23,25 @@ import { isAbsolute, join } from "node:path";
 const HOME_DIR_PREFIX = "~/";
 
 /**
- * 归一化资源引用：~ 展开 + 绝对路径校验。
+ * 引用串是否含 `..` 段（`/x/../y`、`x\..\y`、`~/../x` 同判——展开前检测）。
+ * 手动 split(/[\\/]) 与 displayAgentName 同款跨平台切分（本模块避免平台分支）。
+ */
+function hasParentSegment(ref: string): boolean {
+  return ref.split(/[\\/]/).includes("..");
+}
+
+/**
+ * 归一化资源引用：~ 展开 + 绝对路径校验 + `..` 段拒绝（⛔2 安全收紧）。
  *
  * @param ref   原始引用（注入段 location / 工具参数值）
  * @param ext   期望扩展名（如 ".md" / ".js"），不匹配返回 null
- * @returns 归一化绝对路径；非法（空/相对路径/扩展名不符）返回 null
+ * @returns 归一化绝对路径；非法（空/相对路径/含 `..` 段/扩展名不符）返回 null
  */
 export function normalizeRef(ref: string, ext?: string): string | null {
   const trimmed = ref.trim();
   if (!trimmed) return null;
+  // ⛔2：`..` 段 = 目录逃逸向量，展开前检测（join 会 normalize 消解 `..`，展开后判会漏）
+  if (hasParentSegment(trimmed)) return null;
 
   const expanded = trimmed.startsWith(HOME_DIR_PREFIX)
     ? join(homedir(), trimmed.slice(HOME_DIR_PREFIX.length))
@@ -35,6 +52,130 @@ export function normalizeRef(ref: string, ext?: string): string | null {
   return expanded;
 }
 
+// ── 报错文案工厂（sink 设计 U1）──────────────────────────────
+
+/** invalidAgentRefMessage 的可选注入：宿主的清单段名（缺省 pi 的注入段）。 */
+export interface InvalidAgentRefMessageOptions {
+  /**
+   * 清单指引：宿主注入段名。缺省 `<available_subagents>`（pi 注入段）；第三宿主
+   * 注入段名不同（zsw `<available_agents>` 等）时注入替代，文案口径不变。
+   */
+  howToList?: string;
+}
+
+/**
+ * agent ref 非法的统一报错文案（消费方唯一文案口径——不各自拼 message）。
+ *
+ * 基准 = AgentRegistry.loadByPath(require) 的既有 throw 文案
+ * （"Invalid agent ref: ... absolute paths to .md files ..."），工厂收敛后该消费点
+ * 与后续宿主接线点共用此处。`..` 形态附纠正指引（⛔2 新失败路径——错误必须指向
+ * 恢复动作：去掉 `..` 段、改用注入段 location）。
+ */
+export function invalidAgentRefMessage(
+  ref: string,
+  opts?: InvalidAgentRefMessageOptions,
+): string {
+  const howToList = opts?.howToList ?? "<available_subagents>";
+  if (hasParentSegment(ref)) {
+    return (
+      `Invalid agent ref: ${ref}. Agent refs must be absolute paths to .md files ` +
+      `without ".." path segments (use <location> from ${howToList}).`
+    );
+  }
+  return (
+    `Invalid agent ref: ${ref}. Agent refs must be absolute paths to .md files ` +
+    `(use <location> from ${howToList}).`
+  );
+}
+
+// ── workflow ref 原语（sink 设计 U1 / §2.2 D3 行）────────────
+
+/** normalizeWorkflowRef 的可选注入：宿主已知的 workflow 名清单。 */
+export interface NormalizeWorkflowRefOptions {
+  /**
+   * 宿主注入的已知 workflow 名清单（内置 + 用户级，宿主按自身优先级合并去重——
+   * pi 为 config-loader 的 tmp>project>npm>user 去重产物，内置名优先已由该清单
+   * 体现）。省略 = 无已知名，全部裸名按 unknown_name 拒绝。
+   */
+  knownNames?: Iterable<string>;
+}
+
+/** workflow ref 名分支的保留字：`.` / `..` 是文件系统相对路径段保留语义，任何域不可作名引用。 */
+export const WORKFLOW_REF_RESERVED_NAMES: readonly string[] = [".", ".."];
+
+/** normalizeWorkflowRef 拒绝原因（结构化裁决——文案留宿主，与 knownNames 宿主注入哲学一致）。 */
+export type WorkflowRefInvalidReason =
+  | "empty" // 空引用
+  | "reserved" // 名分支命中保留字（保留字裁决优先于 knownNames）
+  | "unknown_name" // 裸名未命中 knownNames
+  | "not_absolute" // 路径分支：相对路径无基准
+  | "parent_segment" // 路径分支：含 `..` 段（⛔2 同面）
+  | "bad_ext"; // 路径分支：非 .js
+
+/**
+ * normalizeWorkflowRef 的三分裁决结果：
+ * - name    → 裸名命中 knownNames，按名引用（内置名优先已由宿主清单体现）
+ * - path    → 路径形态经 normalizeRef 全套校验（~/ 展开、绝对路径、.js、`..` 拒绝）
+ * - invalid → 拒绝（reason 给精确裁决原因，消费方出恢复指引）
+ */
+export type NormalizedWorkflowRef =
+  | { kind: "name"; name: string }
+  | { kind: "path"; path: string }
+  | { kind: "invalid"; ref: string; reason: WorkflowRefInvalidReason };
+
+/**
+ * workflow 引用统一原语（名/路径二分 + 保留字裁决 + 内置名优先，三层口径单源化——
+ * pi「收裸名+路径」、zsw「入口拒裸名/内层宽松」的统一替代）。
+ *
+ * 二分判据：含 `/`、`\` 分隔符或 `~` 前缀 → 路径分支；否则 → 裸名分支。对齐 pi
+ * 现行为「名字是简单标识符，路径串不会撞 workflow 名」（tool-workflow actionRun：
+ * get(name) 先于 getPath——名命中即用，不猜路径，内置名优先由此成立）。
+ *
+ * 裁决顺序（裸名分支）：保留字 > knownNames > unknown——保留字命中即拒，即便宿主
+ * 清单异常含保留字也不放行（`..` 若被当名接受会绕过路径域的 ⛔2 收紧）。
+ *
+ * 路径分支复用 normalizeRef(WORKFLOW_REF_EXT)：`..` 段拒绝、~/ 展开、扩展名校验
+ * 与 agent 域同面（G1：同一校验语义）。
+ */
+export function normalizeWorkflowRef(
+  ref: string,
+  opts?: NormalizeWorkflowRefOptions,
+): NormalizedWorkflowRef {
+  const trimmed = ref.trim();
+  if (!trimmed) return { kind: "invalid", ref, reason: "empty" };
+
+  const looksLikePath = trimmed.includes("/") || trimmed.includes("\\") || trimmed.startsWith("~");
+  if (looksLikePath) {
+    const path = normalizeRef(trimmed, WORKFLOW_REF_EXT);
+    if (path !== null) return { kind: "path", path };
+    // 失败原因细分（normalizeRef 返回 null 不带原因——此处按同一判据重放；重放
+    // 顺序与 normalizeRef 判序逐位对齐：parent_segment 先于 not_absolute，否则
+    // `a/../b.js` 类「相对路径 + 含 .. 段」被误归因 not_absolute，指引改绝对路径
+    // 后仍被 .. 段拒绝——两步误导。`..` 段对原始串检测，与展开前判位一致）
+    const expanded = trimmed.startsWith(HOME_DIR_PREFIX)
+      ? join(homedir(), trimmed.slice(HOME_DIR_PREFIX.length))
+      : trimmed;
+    const reason: WorkflowRefInvalidReason = hasParentSegment(trimmed)
+      ? "parent_segment"
+      : !isAbsolute(expanded)
+        ? "not_absolute"
+        : "bad_ext";
+    return { kind: "invalid", ref, reason };
+  }
+
+  // 裸名分支：保留字 > knownNames > unknown
+  if (WORKFLOW_REF_RESERVED_NAMES.includes(trimmed)) {
+    return { kind: "invalid", ref, reason: "reserved" };
+  }
+  const known = opts?.knownNames;
+  if (known !== undefined) {
+    for (const name of known) {
+      if (name === trimmed) return { kind: "name", name: trimmed };
+    }
+  }
+  return { kind: "invalid", ref, reason: "unknown_name" };
+}
+
 /** agentRef 扩展名。 */
 export const AGENT_REF_EXT = ".md";
 /** workflowRef 扩展名。 */