@zhushanwen/subagent-core 0.2.0

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/__tests__/schema-jsonify.test.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 与 resolver 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/__tests__/timer-delay.test.ts

@@ -0,0 +1,61 @@
+// src/shared/__tests__/timer-delay.test.ts
+//
+// assertSafeTimerDelay 纯函数契约——三个 timer 挂载入口（budgetTimeMs /
+// XYZ_SUBAGENT_SPAWN_WATCHDOG_MS / idleTimeoutMs）统一在值流入 setTimeout 前调
+// 用本函数 fail-fast，契约由本文件锁定。
+//
+// [F-3 NaN 穿透修复] 旧实现只挡 `> MAX`：NaN 的 `NaN > MAX` 为 false 静默放行，
+// setTimeout(fn, NaN) 被 Node 塌缩为 1ms 立即触发（watchdog 刚启动就误杀）。
+// 非有限数（NaN/±Infinity）现在同样 fail-fast，且错误消息区分两种情况。
+import { describe, expect, it } from "vitest";
+
+import { MAX_TIMER_DELAY_MS, assertSafeTimerDelay } from "../timer-delay.ts";
+
+describe("assertSafeTimerDelay", () => {
+  it("安全域内的有限值放行（0 与上限值不抛）", () => {
+    expect(() => assertSafeTimerDelay(0, "t")).not.toThrow();
+    expect(() => assertSafeTimerDelay(1000, "t")).not.toThrow();
+    expect(() => assertSafeTimerDelay(MAX_TIMER_DELAY_MS, "t")).not.toThrow();
+  });
+
+  it("[F-3] NaN → fail-fast throw（旧实现 NaN > MAX 为 false 静默放行）", () => {
+    expect(() => assertSafeTimerDelay(Number.NaN, "budgetTimeMs")).toThrowError(/NaN/);
+    expect(() => assertSafeTimerDelay(Number.NaN, "budgetTimeMs")).toThrowError(/not a finite number/);
+  });
+
+  it("[F-3] ±Infinity → fail-fast throw", () => {
+    expect(() => assertSafeTimerDelay(Number.POSITIVE_INFINITY, "t")).toThrowError(/not a finite number/);
+    expect(() => assertSafeTimerDelay(Number.NEGATIVE_INFINITY, "t")).toThrowError(/not a finite number/);
+  });
+
+  it("非有限值错误消息含来源标识与上游修复指引（非 clamp 指引）", () => {
+    expect(() => assertSafeTimerDelay(Number.NaN, "idleTimeoutMs")).toThrowError(/idleTimeoutMs/);
+    expect(() => assertSafeTimerDelay(Number.NaN, "idleTimeoutMs")).toThrowError(/fix the upstream computation/);
+  });
+
+  it("超出上限 → fail-fast throw，消息含上限值与 clamp 恢复指引（原语义不变）", () => {
+    expect(() => assertSafeTimerDelay(MAX_TIMER_DELAY_MS + 1, "budgetTimeMs")).toThrowError(/2147483647/);
+    expect(() => assertSafeTimerDelay(3_000_000_000, "budgetTimeMs")).toThrowError(/Recovery: clamp/);
+  });
+
+  it("两种错误可区分：非有限值消息不含 clamp 指引，溢出消息不含 upstream 指引", () => {
+    const nonFiniteMsg = (() => {
+      try {
+        assertSafeTimerDelay(Number.NaN, "t");
+        return "";
+      } catch (err) {
+        return (err as Error).message;
+      }
+    })();
+    const overflowMsg = (() => {
+      try {
+        assertSafeTimerDelay(MAX_TIMER_DELAY_MS + 1, "t");
+        return "";
+      } catch (err) {
+        return (err as Error).message;
+      }
+    })();
+    expect(nonFiniteMsg).not.toContain("clamp");
+    expect(overflowMsg).not.toContain("fix the upstream computation");
+  });
+});

package/src/shared/agent-event.ts

@@ -0,0 +1,13 @@
+// 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

@@ -0,0 +1,57 @@
+/**
+ * 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

@@ -0,0 +1,261 @@
+/**
+ * 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)}` };
+  }
+}