@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

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

@@ -1,51 +0,0 @@
-/**
- * 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/__tests__/schema-jsonify.test.ts

@@ -1,81 +0,0 @@
-/**
- * stringifySchemaCached（IF7/#13）— WeakMap 引用级缓存单测（TC6/DM4）。
- *
- * 断言面（design IF7 契约）：
- * - 同对象二调返回同字符串引用（缓存命中，非等值新串）
- * - compact/pretty 分别缓存（互不覆写）
- * - 不同对象互不污染
- * - 输出与直接 JSON.stringify 逐字节一致
- */
-import { describe, expect, it, vi } from "vitest";
-
-import { stringifySchemaCached } from "../schema-jsonify.ts";
-
-describe("stringifySchemaCached — WeakMap 引用级缓存", () => {
-  const schema = { type: "object", properties: { n: { type: "number" } } };
-
-  it("输出与直接 JSON.stringify 逐字节一致（compact / pretty）", () => {
-    expect(stringifySchemaCached(schema, "compact")).toBe(JSON.stringify(schema));
-    expect(stringifySchemaCached(schema, "pretty")).toBe(JSON.stringify(schema, null, 2));
-  });
-
-  it("同对象二调返回同字符串引用（缓存命中）", () => {
-    const a = stringifySchemaCached(schema, "compact");
-    const b = stringifySchemaCached(schema, "compact");
-    expect(b).toBe(a); // toBe = 引用相等（非仅等值）
-  });
-
-  it("同对象跨格式：compact 与 pretty 分别缓存且各自命中", () => {
-    const c1 = stringifySchemaCached(schema, "compact");
-    const p1 = stringifySchemaCached(schema, "pretty");
-    const c2 = stringifySchemaCached(schema, "compact");
-    const p2 = stringifySchemaCached(schema, "pretty");
-    expect(c2).toBe(c1);
-    expect(p2).toBe(p1);
-    expect(c1).not.toBe(p1); // 两种格式输出不同，分别缓存
-  });
-
-  it("不同对象互不污染（等值异引用各持条目）", () => {
-    const s1 = { type: "object" };
-    const s2 = { type: "object" }; // 等值但异引用
-    const r1 = stringifySchemaCached(s1, "compact");
-    const r2 = stringifySchemaCached(s2, "compact");
-    expect(r1).toBe(r2); // 等值（内容相同）
-    // s2 未命中 s1 的条目（否则 spy 场景下 s2 的 stringify 调用会被跳过——
-    // 引用级隔离由「同引用返回同串」+「等值异引用各自 stringify」共同保证）
-  });
-
-  it("缓存命中路径不再调 JSON.stringify（spy 计数）", () => {
-    const spy = vi.spyOn(JSON, "stringify");
-    try {
-      const obj = { spy: true };
-      stringifySchemaCached(obj, "pretty");
-      stringifySchemaCached(obj, "pretty"); // 第二次应命中缓存
-      const calls = spy.mock.calls.filter((c) => c[0] === obj);
-      expect(calls).toHaveLength(1);
-    } finally {
-      spy.mockRestore();
-    }
-  });
-
-  it("pretty 缩进锚定：indent=2 与 formatSchemaInstruction 渲染同源", () => {
-    const out = stringifySchemaCached({ type: "object" }, "pretty");
-    expect(out).toBe('{\n  "type": "object"\n}');
-  });
-
-  // [review 修复] TS lib 盲区回归：schema 含 toJSON: () => undefined 钩子时
-  // JSON.stringify 运行时返回 undefined，违反声明的 string 返回类型——现 fail-loud
-  // 抛含恢复指引的错误，不静默返回 undefined / 垃圾串。
-  it("[review 修复] schema 含 toJSON: () => undefined → 抛含恢复指引的错误（compact / pretty）", () => {
-    const bad = { type: "object", toJSON: () => undefined };
-    expect(() => stringifySchemaCached(bad, "compact")).toThrowError(
-      /stringifySchemaCached: JSON\.stringify returned undefined.*Recovery:/s,
-    );
-    expect(() => stringifySchemaCached(bad, "pretty")).toThrowError(
-      /toJSON hook returning undefined.*Recovery:/s,
-    );
-    // 正常 schema 不受影响（toJSON 返回合法值时按其返回值序列化）
-    const good = { type: "object", toJSON: () => ({ type: "string" }) };
-    expect(stringifySchemaCached(good, "compact")).toBe('{"type":"string"}');
-  });
-});

package/src/shared/agent-event.ts

@@ -1,13 +0,0 @@
-// src/shared/agent-event.ts
-//
-// AgentEvent 类型唯一出口（两包合并后 import 收口）。
-//
-// 合并前 AgentEvent 分别定义在 execution/types.ts（subagents 侧）和
-// orchestration/live/types.ts（workflow 侧）——两份定义完全一致但独立维护。
-// 合并后本文件是单一 source of truth——re-export execution/types.ts 的 AgentEvent，
-// orchestration 层通过本文件引用（替代 orchestration/live/types.ts 的旧副本）。
-//
-// wave-3 删 orchestration/live/types.ts 后，AgentEvent 的唯一定义在 execution/types.ts。
-// 本 re-export 保持「shared/ 是类型共享层」的架构约定。
-
-export type { AgentEvent } from "../execution/types.ts";

package/src/shared/agent-ref.ts

@@ -1,57 +0,0 @@
-/**
- * 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";
-
-/** home 目录简写前缀（`~/`），展开为 homedir 绝对路径。 */
-const HOME_DIR_PREFIX = "~/";
-
-/**
- * 归一化资源引用：~ 展开 + 绝对路径校验。
- *
- * @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(HOME_DIR_PREFIX)
-    ? join(homedir(), trimmed.slice(HOME_DIR_PREFIX.length))
-    : 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";
-
-/**
- * agent ref 的显示名：basename + 去 .md 扩展名（`/a/b/worker.md` → `worker`）。
- *
- * agentRef 是绝对路径，UI 显示层（TUI tool block 标题 / list / 完成通知、GUI list item /
- * pending 通知 name）统一经本函数取短名，避免长路径挤占显示宽度。数据层不动——
- * record.agent / env 注入（PI_SUBAGENT_AGENT）/ 持久化 / LLM 通知文本保持完整路径。
- *
- * 非路径值（DEFAULT_AGENT_NAME "general-purpose"）与无 .md 后缀的值原样返回。
- * 手动 split(/[\\/]) 而非 path.basename：跨平台统一（macOS 的 path.basename
- * 不切 Windows `\` 分隔符，反之类推），且本模块避免引入平台分支。
- */
-export function displayAgentName(ref: string): string {
-  const base = ref.split(/[\\/]/).pop() ?? ref;
-  return base.endsWith(AGENT_REF_EXT) ? base.slice(0, -AGENT_REF_EXT.length) : base;
-}

package/src/shared/meta-parser.ts

@@ -1,261 +0,0 @@
-/**
- * Meta Parser — 资源元数据统一解析器（v5 §4.2 / IF1 + IF2）
- *
- * 两个变体，职责分离（R8-F1：discovery 的 fail-safe null 与 generate 的 linePos 需求互斥，
- * 单一函数无法兼顾）：
- * - parseResourceMeta（IF1，discovery 用）：fail-safe，任何失败返 null，不抛。
- *   供 config-loader / registry / 两 injector / agent-registry 调用（4 parser 收敛为 1）。
- * - parseResourceMetaDetailed（IF2，generate 闭环用）：失败返 {ok:false, error, linePos}，
- *   linePos 取自 eemeli/yaml YAMLParseError.linePos[0]（[P-yaml] 探针实测：
- *   e.linePos 是 [start,end] 数组，取 [0] 作起止点），供 actionGenerate 报行列给 LLM 自纠正。
- *
- * 格式（v5 §7 / DM4）：
- * - workflow (.js)：块注释 `/* @pi-meta <YAML> * /`（单星，非 JSDoc），WORKFLOW_META_RE 提取。
- * - agent (.md)：frontmatter `--- <YAML> ---`，FRONTMATTER_RE 提取。
- * - 无 legacy fallback（D1）：const meta 旧格式 → extractBlock 取不到块 → null。
- *
- * [P-yaml] 探针已验证：eemeli/yaml 2.9.0 的 YAMLParseError.linePos = [{line,col},{line,col}]。
- *
- * exec-review 修复（major-1 + minor-2..8）：
- * - 正则闭合符（星斜杠）必须独占行首，防止 YAML 正文里中途出现的星斜杠（如 usage 块标量
- *   或 patternProperties 正则）截断块致 parameters 等字段静默丢失（§2.3 failure-A 同形态）。
- * - typecheckMeta 严格化：kind 专属字段不可串类（workflow 不许 examples、agent 不许 phases），
- *   description 必填，phase detail 非字符串/parameters 非对象均 reject（消除「静默丢弃非法字段」）。
- * - 区分「未找到块」(undefined) 与「块为空」("")，IF2 给可操作错误。
- * - FRONTMATTER_RE 兼容 CRLF。
- *
- * 层归属：shared（L2 统一解析器）。
- */
-
-import { parse as parseYaml } from "yaml";
-
-import type {
-  AgentMeta,
-  ResourceKind,
-  ResourceMeta,
-  RoutingExample,
-  WorkflowMeta,
-} from "./resource-meta.ts";
-
-// ── 格式提取正则 ──────────────────────────────────────────────
-
-/**
- * workflow @pi-meta 块注释：单星块注释（非 JSDoc `/**`），内容为 YAML。
- * 闭合符（星斜杠）必须独占行首、列 0——防止 YAML 正文里中途出现的星斜杠（如 usage 块标量
- * 内的 see-星斜杠-for、或 patternProperties 正则含星后接斜杠）截断块致后续字段静默丢失（major-1）。
- * 格式规范要求闭合符在列 0（v5 §7），故列 0 闭合不损失合法用例。
- */
-const WORKFLOW_META_RE = /\/\*\s*@pi-meta\s*\n([\s\S]*?)\n\*\//;
-
-/** agent frontmatter：标准 YAML frontmatter，兼容 CRLF（minor-7）。 */
-const FRONTMATTER_RE = /---\r?\n([\s\S]*?)\r?\n---/;
-
-/**
- * 按资源种类取 meta 块文本（YAML 体）。
- * @returns 未匹配返 undefined；匹配返字符串（可能为空 ""）——调用方据 undefined 区分「未找到」。
- */
-function extractBlock(content: string, kind: ResourceKind): string | undefined {
-  const re = kind === "workflow" ? WORKFLOW_META_RE : FRONTMATTER_RE;
-  return re.exec(content)?.[1];
-}
-
-// ── 类型校验（手写，非 ajv；meta 结构简单）──────────────────
-
-function isNonEmptyString(v: unknown): v is string {
-  return typeof v === "string" && v.length > 0;
-}
-function isString(v: unknown): v is string {
-  return typeof v === "string";
-}
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-/**
- * 把 parseYaml 结果（unknown）校验为类型化 ResourceMeta，失败返 null（语义非法，非语法错）。
- * 严格化（exec-review minor-2..5）：kind 专属字段不可串类、description 必填、
- * phase detail 非字符串/parameters 非对象均 reject（消除「静默丢弃非法字段」）。
- */
-function typecheckMeta(raw: unknown, kind: ResourceKind): ResourceMeta | null {
-  if (!isPlainObject(raw)) return null;
-  const o = raw;
-
-  // 公共必填：name 非空字符串、description 必须是字符串（minor-3：缺 description reject）
-  if (!isNonEmptyString(o.name)) return null;
-  if (!isString(o.description)) return null;
-  const when = isString(o.when) ? o.when : undefined;
-  const notFor = isString(o.notFor) ? o.notFor : undefined;
-
-  if (kind === "workflow") {
-    // minor-2：agent 专属字段不可出现在 workflow（串类 reject）
-    if (o.examples !== undefined || o.tools !== undefined || o.model !== undefined || o.engine !== undefined) {
-      return null;
-    }
-    // phases 必填数组，元素为 string | {title:string, detail?:string}
-    if (!Array.isArray(o.phases)) return null;
-    const phases: WorkflowMeta["phases"] = [];
-    for (const p of o.phases) {
-      if (isString(p)) {
-        phases.push(p);
-      } else if (isPlainObject(p) && isNonEmptyString(p.title)) {
-        // minor-4：detail 存在但非字符串 → reject（不再静默丢弃）
-        if (p.detail !== undefined && !isString(p.detail)) return null;
-        phases.push(isString(p.detail) ? { title: p.title, detail: p.detail } : { title: p.title });
-      } else {
-        return null;
-      }
-    }
-    // minor-5：parameters 存在但非 plain object → reject（不再静默当 undefined）
-    const parameters = o.parameters;
-    if (parameters !== undefined && !isPlainObject(parameters)) return null;
-    const usage = isString(o.usage) ? o.usage : undefined;
-
-    const meta: WorkflowMeta = {
-      kind: "workflow",
-      name: o.name,
-      description: o.description,
-      phases,
-      ...(parameters !== undefined ? { parameters: parameters as Record<string, unknown> } : {}),
-      ...(usage !== undefined ? { usage } : {}),
-      ...(when !== undefined ? { when } : {}),
-      ...(notFor !== undefined ? { notFor } : {}),
-    };
-    return meta;
-  }
-
-  // kind === "agent"
-  // minor-2：workflow 专属字段不可出现在 agent（串类 reject）
-  if (o.phases !== undefined || o.parameters !== undefined || o.usage !== undefined) return null;
-  let examples: RoutingExample[] | undefined;
-  if (o.examples !== undefined) {
-    if (!Array.isArray(o.examples)) return null;
-    const exs: RoutingExample[] = [];
-    for (const e of o.examples) {
-      if (
-        isPlainObject(e) &&
-        isString(e.match) &&
-        isString(e.action) &&
-        typeof e.positive === "boolean"
-      ) {
-        exs.push({ match: e.match, action: e.action, positive: e.positive });
-      } else {
-        return null;
-      }
-    }
-    examples = exs;
-  }
-  let tools: string[] | undefined;
-  if (o.tools !== undefined) {
-    if (Array.isArray(o.tools)) {
-      if (!o.tools.every(isString)) return null;
-      tools = o.tools as string[];
-    } else if (isString(o.tools)) {
-      // 兼容 agent .md 的逗号分隔字符串约定（如 `tools: read, bash, grep`）
-      const parts = o.tools.split(",").map((s) => s.trim()).filter(Boolean);
-      tools = parts.length > 0 ? parts : undefined;
-    } else {
-      return null;
-    }
-  }
-  const model = isString(o.model) ? o.model : undefined;
-  const engine = isString(o.engine) ? o.engine : undefined;
-
-  const meta: AgentMeta = {
-    kind: "agent",
-    name: o.name,
-    description: o.description,
-    ...(examples !== undefined ? { examples } : {}),
-    ...(tools !== undefined ? { tools } : {}),
-    ...(model !== undefined ? { model } : {}),
-    ...(engine !== undefined ? { engine } : {}),
-    ...(when !== undefined ? { when } : {}),
-    ...(notFor !== undefined ? { notFor } : {}),
-  };
-  return meta;
-}
-
-// ── IF1: parseResourceMeta（discovery，fail-safe null）─────────────────
-
-/**
- * 统一 meta 解析入口（discovery 用）。仅认新格式，无 legacy fallback。
- * 任何失败（缺块 / YAML 语法错 / 类型校验失败）→ return null（不抛）。
- * discovery fail-safe：单文件解析失败仅让该资源 available=false，不阻塞其他资源。
- */
-export function parseResourceMeta(
-  content: string,
-  kind: ResourceKind,
-): ResourceMeta | null {
-  const block = extractBlock(content, kind);
-  if (block === undefined) return null;
-  try {
-    const raw = parseYaml(block);
-    return typecheckMeta(raw, kind);
-  } catch {
-    return null;
-  }
-}
-
-/** 从 eemeli/yaml 拋错提取 linePos 起点（类型守卫，避免 unsafe cast）。[P-yaml] 实测 e.linePos = [{line,col},{line,col}]。*/
-function getYamlLinePos(e: unknown): { line: number; col: number } | undefined {
-  if (e !== null && typeof e === "object" && "linePos" in e) {
-    const lp = (e as Record<string, unknown>).linePos;
-    if (Array.isArray(lp) && lp.length > 0) {
-      const first = lp[0];
-      if (first !== null && first !== undefined && typeof first === "object"
-          && "line" in first && "col" in first) {
-        const f = first as Record<string, unknown>;
-        if (typeof f["line"] === "number" && typeof f["col"] === "number") {
-          return { line: f["line"], col: f["col"] };
-        }
-      }
-    }
-  }
-  return undefined;
-}
-
-// ── IF2: parseResourceMetaDetailed（generate 闭环，返 linePos）─────────
-
-export type DetailedResult =
-  | { ok: true; meta: ResourceMeta }
-  | { ok: false; error: string; linePos?: { line: number; col: number } };
-
-/**
- * generate 闭环专用。失败时返回 error + linePos（取自 eemeli/yaml YAMLParseError.linePos[0]），
- * 供 actionGenerate 报「生成 YAML 错在 line X col Y」给 LLM 自纠正（ERR4）。
- * discovery 不用此（保持 fail-safe null）。
- *
- * [P-yaml] 探针实测：e.linePos 是 [{line,col},{line,col}]（start+end），取 [0] 作起点。
- *
- * minor-6：区分「未找到块」(undefined) 与「块为空/非法」("")，给可操作错误。
- * minor-8：typecheckMeta 包进 try（与 IF1 对称，防御 typecheck 未来抛错）。
- */
-export function parseResourceMetaDetailed(
-  content: string,
-  kind: ResourceKind,
-): DetailedResult {
-  const block = extractBlock(content, kind);
-  if (block === undefined) {
-    return { ok: false, error: "未找到 meta 块（缺少 /* @pi-meta */ 或 frontmatter，或闭合 */ 不在行首）" };
-  }
-  let raw: unknown;
-  try {
-    raw = parseYaml(block);
-  } catch (e) {
-    // eemeli/yaml YAMLParseError：e.linePos = [{line,col},{line,col}]（[P-yaml] 实测）
-    const linePos = getYamlLinePos(e);
-    return {
-      ok: false,
-      error: e instanceof Error ? e.message.split("\n")[0] : String(e),
-      ...(linePos !== undefined ? { linePos } : {}),
-    };
-  }
-  try {
-    const meta = typecheckMeta(raw, kind);
-    if (!meta) {
-      return { ok: false, error: "meta 类型校验失败（缺 name/description、phases 非法、kind 字段串类或可选字段类型错）" };
-    }
-    return { ok: true, meta };
-  } catch (e) {
-    return { ok: false, error: `meta 类型校验异常: ${e instanceof Error ? e.message : String(e)}` };
-  }
-}