@zhushanwen/pi-subagent-workflow 5.0.2 → 7.0.0

package/src/shared/__tests__/meta-parser.test.ts

@@ -0,0 +1,304 @@
+/**
+ * meta-parser 测试（v5 §11.1 / TC1-TC10 + 边界 + exec-review 回归）
+ *
+ * [P-yaml] 探针由 TC5/TC10 承载：验证 eemeli/yaml 真实抛错对象有 linePos 字段且结构为
+ * {line,col}（取自 linePos[0]）。不 mock parseYaml——必须用真实库验证此运行时断言。
+ *
+ * exec-review 回归：major-1（星斜杠截断）+ minor-2（kind 串类）+ minor-3（description 必填）
+ * + minor-4（detail 非字符串）+ minor-5（parameters 非对象）+ minor-6（空块 vs 缺块）+ minor-7（CRLF）。
+ *
+ * 框架：vitest（项目规范：禁 node:test，import from "vitest"）。
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  parseResourceMeta,
+  parseResourceMetaDetailed,
+} from "../meta-parser.ts";
+import type { AgentMeta, WorkflowMeta } from "../resource-meta.ts";
+
+// ── 固定 content fixtures ────────────────────────────────────
+
+const VALID_WORKFLOW = `// 顶部可有任意代码注释
+/* @pi-meta
+name: chain
+description: 通用编排三步链
+when: 用户要顺序编排
+phases: [analyze, transform, synthesize]
+parameters:
+  type: object
+  properties:
+    task: { type: string }
+  required: [task]
+usage: |
+  ## 使用说明
+  - task 必填
+*/
+const agent = require("./agent");
+`;
+
+const VALID_AGENT = `---
+name: code-review
+description: 审查代码变更
+when: 用户要求 review
+notFor: 非 xyz-agent 项目
+examples:
+  - match: "帮我 review 一下"
+    action: 调用 code-review
+    positive: true
+  - match: 今天天气
+    action: 不调用
+    positive: false
+tools: [read, bash, grep]
+model: claude-3.5
+---
+# code-review agent 正文
+`;
+
+const MALFORMED_INDENT = `/* @pi-meta
+name: x
+description: bad
+  description: bad indent
+phases: [a]
+*/`;
+
+const REGEX_SINGLE_BACKSLASH = `/* @pi-meta
+name: rfl
+description: 测试正则转义
+phases: [Review, Fix]
+parameters:
+  type: object
+  patternProperties:
+    "^batch\\d+$": { type: string }
+*/`;
+
+const LEGACY_CONST_META = `const meta = {
+  name: chain,
+  description: 旧格式,
+  phases: ["a"]
+};
+const agent = require("./agent");
+`;
+
+const NO_META_BLOCK = `const agent = require("./agent");
+// 纯代码，无 @pi-meta
+`;
+
+const EMPTY_PI_META = `/* @pi-meta
+
+*/
+const x = 1;
+`;
+
+const EMPTY_PHASES = `/* @pi-meta
+name: x
+description: 空 phases
+phases: []
+*/`;
+
+// ── parseResourceMeta（IF1，discovery）──────────────────────
+
+describe("parseResourceMeta (discovery, fail-safe null)", () => {
+  it("TC1: 合法 workflow @pi-meta 返 WorkflowMeta", () => {
+    const meta = parseResourceMeta(VALID_WORKFLOW, "workflow");
+    expect(meta).not.toBeNull();
+    const wf = meta as WorkflowMeta;
+    expect(wf.kind).toBe("workflow");
+    expect(wf.name).toBe("chain");
+    expect(wf.phases).toEqual(["analyze", "transform", "synthesize"]);
+    expect(wf.when).toBe("用户要顺序编排");
+    expect(wf.parameters).toBeDefined();
+    expect(wf.usage).toContain("task 必填");
+  });
+
+  it("TC2: 合法 agent frontmatter 返 AgentMeta", () => {
+    const meta = parseResourceMeta(VALID_AGENT, "agent");
+    expect(meta).not.toBeNull();
+    const a = meta as AgentMeta;
+    expect(a.kind).toBe("agent");
+    expect(a.name).toBe("code-review");
+    expect(a.notFor).toBe("非 xyz-agent 项目");
+    expect(a.examples).toHaveLength(2);
+    expect(a.examples![0]).toEqual({ match: "帮我 review 一下", action: "调用 code-review", positive: true });
+    expect(a.examples![1]!.positive).toBe(false);
+    expect(a.tools).toEqual(["read", "bash", "grep"]);
+    expect(a.model).toBe("claude-3.5");
+  });
+
+  it("TC3: malformed YAML（缩进错）返 null，不抛 [P-yaml]", () => {
+    expect(() => parseResourceMeta(MALFORMED_INDENT, "workflow")).not.toThrow();
+    expect(parseResourceMeta(MALFORMED_INDENT, "workflow")).toBeNull();
+  });
+
+  it("TC4: 缺 meta 块返 null", () => {
+    expect(parseResourceMeta(NO_META_BLOCK, "workflow")).toBeNull();
+  });
+
+  it("TC8（修正）: workflow 字段（phases）当 agent kind 解析，typecheckMeta 串类 reject [minor-2]", () => {
+    // 用 frontmatter 包裹 workflow 字段，确保 FRONTMATTER_RE 匹配、typecheckMeta 真正被触达
+    const content = `---
+name: chainlike
+description: has phases but parsed as agent
+phases: [analyze, transform]
+parameters:
+  type: object
+---
+# agent body`;
+    expect(parseResourceMeta(content, "agent")).toBeNull();
+  });
+
+  it("TC8b: agent 字段（examples）当 workflow kind 解析，串类 reject [minor-2]", () => {
+    const content = `/* @pi-meta
+name: x
+description: has examples but workflow
+phases: [A]
+examples:
+  - match: m
+    action: a
+    positive: true
+*/`;
+    expect(parseResourceMeta(content, "workflow")).toBeNull();
+  });
+
+  it("TC9: legacy const meta（无 @pi-meta 块）返 null（无 adapter）[D1]", () => {
+    expect(parseResourceMeta(LEGACY_CONST_META, "workflow")).toBeNull();
+  });
+
+  it("TC10: patternProperties 单反斜杠正则致 YAML 解析失败返 null [P-yaml]", () => {
+    expect(parseResourceMeta(REGEX_SINGLE_BACKSLASH, "workflow")).toBeNull();
+  });
+
+  it("边界：空 @pi-meta 块（内容为空）返 null", () => {
+    expect(parseResourceMeta(EMPTY_PI_META, "workflow")).toBeNull();
+  });
+
+  it("边界：phases: [] 空数组合法（workflow 可无 phase）", () => {
+    const meta = parseResourceMeta(EMPTY_PHASES, "workflow");
+    expect(meta).not.toBeNull();
+    expect((meta as WorkflowMeta).phases).toEqual([]);
+  });
+
+  // ── exec-review 回归 ──────────────────────────────────────
+
+  it("major-1: usage 块标量含 */ 不再截断，parameters 不丢失", () => {
+    const content = `/* @pi-meta
+name: x
+description: d
+phases: [A]
+when: present
+usage: |
+  see */ for details
+parameters:
+  type: object
+  properties:
+    task: { type: string }
+*/`;
+    const meta = parseResourceMeta(content, "workflow");
+    expect(meta).not.toBeNull();
+    const wf = meta as WorkflowMeta;
+    expect(wf.parameters).toBeDefined(); // major-1：此前被 */ 截断静默丢失
+    expect(wf.when).toBe("present");     // 此前同样丢失
+    expect(wf.usage).toContain("see */ for details");
+  });
+
+  it("major-1b: patternProperties 正则含 * 后接 / 不再误截断", () => {
+    const content = `/* @pi-meta
+name: re
+description: regex
+phases: [A]
+parameters:
+  type: object
+  patternProperties:
+    "^\\\\d*/\\\\w+$": { type: string }
+*/`;
+    const meta = parseResourceMeta(content, "workflow");
+    expect(meta).not.toBeNull();
+    expect((meta as WorkflowMeta).parameters).toBeDefined();
+  });
+
+  it("minor-3: 缺 description 返 null（必填，不再静默空串）", () => {
+    const content = `/* @pi-meta
+name: nodesc
+phases: [A]
+*/`;
+    expect(parseResourceMeta(content, "workflow")).toBeNull();
+  });
+
+  it("minor-4: phase detail 非字符串返 null（不再静默丢弃）", () => {
+    const content = `/* @pi-meta
+name: x
+description: d
+phases:
+  - title: A
+    detail: 123
+*/`;
+    expect(parseResourceMeta(content, "workflow")).toBeNull();
+  });
+
+  it("minor-5: parameters 是数组返 null（不再静默当 undefined）", () => {
+    const content = `/* @pi-meta
+name: x
+description: d
+phases: [A]
+parameters: [a, b]
+*/`;
+    expect(parseResourceMeta(content, "workflow")).toBeNull();
+  });
+
+  it("minor-7: CRLF 行尾 frontmatter 正确提取", () => {
+    const content = "---\r\nname: a\r\ndescription: d\r\n---\r\n# body";
+    const meta = parseResourceMeta(content, "agent");
+    expect(meta).not.toBeNull();
+    expect((meta as AgentMeta).name).toBe("a");
+  });
+});
+
+// ── parseResourceMetaDetailed（IF2，generate 闭环）──────────
+
+describe("parseResourceMetaDetailed (generate, linePos)", () => {
+  it("TC6: 合法返 {ok:true, meta}", () => {
+    const r = parseResourceMetaDetailed(VALID_WORKFLOW, "workflow");
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.meta.name).toBe("chain");
+  });
+
+  it("TC5: malformed YAML 返 {ok:false, error, linePos:{line,col}} [P-yaml]", () => {
+    const r = parseResourceMetaDetailed(MALFORMED_INDENT, "workflow");
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toBeTruthy();
+      expect(r.linePos).toBeDefined();
+      expect(typeof r.linePos!.line).toBe("number");
+      expect(typeof r.linePos!.col).toBe("number");
+      expect(r.linePos!.line).toBeGreaterThan(0);
+    }
+  });
+
+  it("TC7: 缺块返 {ok:false, error} 无 linePos", () => {
+    const r = parseResourceMetaDetailed(NO_META_BLOCK, "workflow");
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.linePos).toBeUndefined();
+  });
+
+  it("TC10: 单反斜杠正则返 {ok:false, error 含 escape, linePos} [P-yaml]", () => {
+    const r = parseResourceMetaDetailed(REGEX_SINGLE_BACKSLASH, "workflow");
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("escape");
+      expect(r.linePos).toBeDefined();
+      expect(r.linePos!.line).toBeGreaterThan(0);
+    }
+  });
+
+  it("minor-6: 空块与缺块错误消息区分（空块不报「未找到」）", () => {
+    const empty = parseResourceMetaDetailed(EMPTY_PI_META, "workflow");
+    const missing = parseResourceMetaDetailed(NO_META_BLOCK, "workflow");
+    expect(empty.ok).toBe(false);
+    expect(missing.ok).toBe(false);
+    if (!empty.ok && !missing.ok) {
+      // 缺块报「未找到 meta 块」；空块报类型校验失败（块在但内容空/非法）
+      expect(missing.error).toContain("未找到");
+      expect(empty.error).not.toContain("未找到");
+    }
+  });
+});

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

@@ -6,13 +6,23 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+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 个失败）。
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return { ...actual, homedir: () => "/nonexistent-home-for-tests" };
+});
 
 import {
   discoverResources,
   discoverResourcesSync,
   findWorkspaceRoot,
   processPackageSync,
+  getCachedFile,
+  getCachedFileContent,
 } from "../resource-discovery.ts";
 
 // ============================================================
@@ -79,8 +89,11 @@ describe("discoverResourcesSync", () => {
   it("discovers agents from project .pi/agents/", () => {
     writeFile(path.join(ws, ".pi", "agents"), "worker.md", "body");
     const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
-    expect(result.map((r) => path.basename(r.path))).toEqual(["worker.md"]);
-    expect(result[0]?.available).toBe(true);
+    // 按 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/", () => {
@@ -93,8 +106,9 @@ describe("discoverResourcesSync", () => {
     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, agentDir });
-    expect(result).toHaveLength(1);
-    expect(result[0]?.source).toBe("project-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", () => {
@@ -121,12 +135,14 @@ describe("discoverResourcesSync", () => {
     writeFile(dir, "_skip.md", "ignored");
     writeFile(dir, "trace.chain.md", "ignored");
     const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
-    expect(result.map((r) => path.basename(r.path))).toEqual(["real.md"]);
+    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, agentDir });
-    expect(result).toEqual([]);
+    // 用户全局目录可能有真实文件——只断言 project 源为空
+    expect(result.filter((r) => r.source === "project-pi" || r.source === "project-agents")).toEqual([]);
   });
 });
 
@@ -224,3 +240,147 @@ describe("discoverResources (async)", () => {
     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 });
+  });
+
+  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, agentDir });
+    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, agentDir });
+    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, agentDir });
+    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, agentDir });
+    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, agentDir });
+    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, agentDir });
+    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, agentDir });
+    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");
+  });
+});
+
+// ── 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 });
+    }
+  });
+});

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

@@ -0,0 +1,51 @@
+/**
+ * resource-meta 类型族测试（v5 §11.1）
+ *
+ * 编译期 + 运行期判别 ResourceMeta 联合。
+ */
+import { describe, expect, it } from "vitest";
+
+import type { AgentMeta, ResourceMeta, WorkflowMeta } from "../resource-meta.ts";
+
+describe("ResourceMeta 类型族", () => {
+  it("WorkflowMeta 判别 kind='workflow'", () => {
+    const wf: WorkflowMeta = {
+      kind: "workflow",
+      name: "chain",
+      description: "test",
+      phases: ["a"],
+    };
+    expect(wf.kind).toBe("workflow");
+  });
+
+  it("AgentMeta 判别 kind='agent'", () => {
+    const ag: AgentMeta = {
+      kind: "agent",
+      name: "reviewer",
+      description: "review",
+    };
+    expect(ag.kind).toBe("agent");
+  });
+
+  it("联合类型 kind 判别 narrowing", () => {
+    function isWorkflow(m: ResourceMeta): m is WorkflowMeta {
+      return m.kind === "workflow";
+    }
+    const wf: ResourceMeta = { kind: "workflow", name: "x", description: "", phases: [] };
+    const ag: ResourceMeta = { kind: "agent", name: "y", description: "" };
+    expect(isWorkflow(wf)).toBe(true);
+    expect(isWorkflow(ag)).toBe(false);
+  });
+
+  it("可选字段缺省为 undefined", () => {
+    const wf: WorkflowMeta = {
+      kind: "workflow",
+      name: "x",
+      description: "",
+      phases: [],
+    };
+    expect(wf.parameters).toBeUndefined();
+    expect(wf.usage).toBeUndefined();
+    expect(wf.when).toBeUndefined();
+  });
+});

package/src/shared/agent-ref.ts

@@ -0,0 +1,36 @@
+/**
+ * agentRef / workflowRef 统一路径解析（S2）。
+ *
+ * 设计（agent-ref-path-redesign D1）：资源引用唯一形态 = 绝对路径。
+ * - agentRef    → .md 文件绝对路径（注入段 <available_subagents> 的 <location>）
+ * - workflowRef → .js 文件绝对路径（注入段 <available_workflows> 的 <location>）
+ * - 支持 `~/` 前缀展开（homedir）；相对路径不认（注入段给绝对路径，模型照抄零歧义）
+ *
+ * 名字不再是引用——只是注入段展示标签。执行侧拿到引用后一律 normalizeRef →
+ * 文件加载（AgentRegistry.loadByPath / WorkflowScriptRegistry.getPath）。
+ */
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+/**
+ * 归一化资源引用：~ 展开 + 绝对路径校验。
+ *
+ * @param ref   原始引用（注入段 location / 工具参数值）
+ * @param ext   期望扩展名（如 ".md" / ".js"），不匹配返回 null
+ * @returns 归一化绝对路径；非法（空/相对路径/扩展名不符）返回 null
+ */
+export function normalizeRef(ref: string, ext?: string): string | null {
+  const trimmed = ref.trim();
+  if (!trimmed) return null;
+
+  const expanded = trimmed.startsWith("~/") ? join(homedir(), trimmed.slice(2)) : trimmed;
+  if (!isAbsolute(expanded)) return null; // 相对路径无基准（注入段给绝对路径）
+
+  if (ext !== undefined && !expanded.endsWith(ext)) return null;
+  return expanded;
+}
+
+/** agentRef 扩展名。 */
+export const AGENT_REF_EXT = ".md";
+/** workflowRef 扩展名。 */
+export const WORKFLOW_REF_EXT = ".js";