@zhushanwen/pi-subagent-workflow 5.0.2 → 7.0.0

package/src/shared/meta-parser.ts

@@ -0,0 +1,257 @@
+/**
+ * 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) 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 meta: AgentMeta = {
+    kind: "agent",
+    name: o.name,
+    description: o.description,
+    ...(examples !== undefined ? { examples } : {}),
+    ...(tools !== undefined ? { tools } : {}),
+    ...(model !== undefined ? { model } : {}),
+    ...(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)}` };
+  }
+}

package/src/shared/resource-discovery.ts

@@ -14,7 +14,7 @@
 import * as fsSync from "node:fs";
 import { access, readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join,resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 
 // ── 类型 ─────────────────────────────────────────────────────
 
@@ -32,7 +32,7 @@ export interface DiscoveredResource {
 }
 
 /** 资源来源层级 */
-export type ResourceSource = "user-pi" | "user-agents" | "npm" | "npm-dev" | "project-pi" | "project-pi-tmp" | "project-agents";
+export type ResourceSource = "user-pi" | "user-agents" | "npm" | "npm-dev" | "user-extension-paths" | "project-pi" | "project-pi-tmp" | "project-agents";
 
 /** 扫描配置 */
 export interface ScanConfig {
@@ -67,6 +67,61 @@ function isDirectChildOfWorkspaceRoot(dir: string, workspaceRoot: string): boole
  * bare+worktree 优先找 .bare；普通 repo 找最顶层 .git；fallback 找 .pi。
  * 与 config-loader 原有逻辑一致（合并后提取为共享函数）。
  */
+// ── 统一 mtime 缓存层（m5 IF10）────────────────────────────────────
+//
+// 模块级 Map<path, { mtimeMs, content }>：mtime 判变缓存文件内容。
+// - sync 实现（statSync/readFileSync）：agent-registry discoverAll 是同步路径，
+//   async 缓存无法被 await（m5 design-review A1 探针实证约束）
+// - stat 失败/ENOENT → 驱逐条目（mtime 缓存下文件删除不自愈——A3 修复）
+// - 已知局限（C3 记录）：内容变 mtime 未变（cp -p/rsync -t 保留源 mtime、
+//   2s 粒度文件系统）→ 漏判，invalidateCache/clearFileCache 兜底；
+//   APFS mtimeMs 微秒级浮点 === 判变可靠（探针 P-mtime-精度）
+
+interface MtimeCacheEntry {
+  mtimeMs: number;
+  content: string;
+}
+
+const mtimeCache = new Map<string, MtimeCacheEntry>();
+
+/**
+ * stat + content 统一缓存。文件不存在/不可读 → null（并驱逐条目）。
+ * mtime 未变 → 返回缓存 content（不重 read）；变 → readFileSync + 缓存。
+ */
+export function getCachedFile(filePath: string): { mtimeMs: number; content: string } | null {
+  let mtimeMs: number;
+  try {
+    mtimeMs = fsSync.statSync(filePath).mtimeMs;
+  } catch {
+    mtimeCache.delete(filePath);
+    return null;
+  }
+  const entry = mtimeCache.get(filePath);
+  if (entry && entry.mtimeMs === mtimeMs) return entry;
+  let content: string;
+  try {
+    content = fsSync.readFileSync(filePath, "utf-8");
+  } catch {
+    // stat 与 read 之间的删除/EACCES 竞态 → 驱逐并返回 null（exec-review major-2：
+    // docstring 承诺「不可读 → null」——readFileSync 也必须入守卫）
+    mtimeCache.delete(filePath);
+    return null;
+  }
+  const cached = { mtimeMs, content };
+  mtimeCache.set(filePath, cached);
+  return cached;
+}
+
+/** 便捷封装：只取 content（不存在 → null）。 */
+export function getCachedFileContent(filePath: string): string | null {
+  return getCachedFile(filePath)?.content ?? null;
+}
+
+/** 清空（invalidateCache 语义——测试隔离 + mtime 漏判场景手动刷新兜底）。 */
+export function clearFileCache(): void {
+  mtimeCache.clear();
+}
+
 export function findWorkspaceRoot(cwd?: string): string {
   const dir = cwd ?? process.cwd();
   const root = resolve("/");
@@ -288,6 +343,24 @@ interface ScanTarget {
   enabled: boolean;
 }
 
+/**
+ * 读取 XYZ_EXTENSION_PATHS 环境变量（dev-link 写入的扩展源码路径）。
+ *
+ * delimiter 分隔（POSIX ':' / Windows ';'），trim + 过滤空 + ~ 展开。
+ * 每个路径是一个 extension 包目录（dev-link 指向源码），走 processPackage 发现其
+ * agents/workflows。解析逻辑与 extension-service.getUserExtensionPaths() 一致。
+ */
+function readExtensionPaths(): string[] {
+  const raw = process.env.XYZ_EXTENSION_PATHS;
+  if (!raw) return [];
+  const paths = raw
+    .split(delimiter)
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0)
+    .map((p) => (p.startsWith("~") ? join(homedir(), p.slice(1)) : p));
+  return [...new Set(paths)];
+}
+
 /**
  * 构建所有扫描源（按优先级低→高排列）。
  *
@@ -306,6 +379,10 @@ function buildScanTargets(config: ScanConfig): ScanTarget[] {
     { dir: join(agentDir, "npm", "node_modules"), source: "npm", enabled: true },
     // 4. npm dev symlink: agentDir/extensions/*/<pkg>/
     { dir: join(agentDir, "extensions"), source: "npm-dev", enabled: true },
+    // user extension paths (XYZ_EXTENSION_PATHS, dev-link): each path is a package dir,
+    // 走 processPackage 读 pi.{kind} manifest 或扫 {kind}/ 目录。优先级高于 npm/npm-dev
+    // （dev-link 是开发版 override），低于 project（项目正式资源优先）。
+    ...readExtensionPaths().map((dir) => ({ dir, source: "user-extension-paths" as const, enabled: true })),
     // 5. project .pi/{kind}/
     { dir: join(workspaceRoot, ".pi", kind), source: "project-pi", enabled: true },
   ];
@@ -354,6 +431,11 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
       // 覆盖 source 标签（scanNpmDir 内部统一标 "npm"，这里修正为实际源）
       const tagged = resources.map((r) => ({ ...r, source: target.source }));
       allBySource.push({ source: target.source, resources: tagged });
+    } else if (target.source === "user-extension-paths") {
+      // XYZ_EXTENSION_PATHS（dev-link）：每个 dir 是单个包目录，走 processPackage
+      const resources = await processPackage(target.dir, config.kind);
+      const tagged = resources.map((r) => ({ ...r, source: target.source }));
+      allBySource.push({ source: target.source, resources: tagged });
     } else {
       // 普通目录：直接扫
       const files = await scanDirectory(target.dir, config.kind);
@@ -517,6 +599,10 @@ export function discoverResourcesSync(config: ScanConfig): DiscoveredResource[]
     if (target.source === "npm" || target.source === "npm-dev") {
       const resources = scanNpmDirSync(target.dir, config.kind);
       all.push(...resources.map((r) => ({ ...r, source: target.source })));
+    } else if (target.source === "user-extension-paths") {
+      // XYZ_EXTENSION_PATHS（dev-link）：每个 dir 是单个包目录
+      const resources = processPackageSync(target.dir, config.kind);
+      all.push(...resources.map((r) => ({ ...r, source: target.source })));
     } else {
       const files = scanDirectorySync(target.dir, config.kind);
       all.push(...files.map((f) => ({ path: f, source: target.source, available: true })));

package/src/shared/resource-meta.ts

@@ -0,0 +1,60 @@
+/**
+ * ResourceMeta — 资源元数据统一类型族（v5 §4.1 / DM1）
+ *
+ * workflow 与 agent 两类资源共用同一数据格式（YAML），仅 kind 判别 + 专属字段不同。
+ * skills 显式 out-of-scope（归 pi core）。
+ *
+ * 设计：
+ * - 整对象透传——config-loader.toCachedMeta / registry-impl.toScript 改为 meta: parsedMeta
+ *   不再 {name,description,phases} 解构重建（消灭 3 重映射丢字段 bug）。
+ * - workflow 的 parameters（JSON Schema）由 args-validator（m3）按 schema 校验 args；
+ *   usage（markdown）覆盖 schema 表达不了的语义约束 + 真实合法示例命令。
+ * - agent 的 tools/model 供 AgentRegistry 执行侧 spawn 子进程用，不进 system prompt 注入段。
+ *
+ * 层归属：shared（L1 统一资源模型）。
+ */
+
+/** 资源种类。skills 归 pi core，本 extension 仅 workflow + agent。 */
+export type ResourceKind = "workflow" | "agent";
+
+/** 两类资源共有的路由字段。 */
+export interface ResourceMetaBase {
+  kind: ResourceKind;
+  /** 路由用一句话（受 SSOT lint W1/W2 约束：≤200 字符、不含参数引用语法）。 */
+  name: string;
+  description: string;
+  /** "Use when ..." 正向路由提示（PromptBudget 最后保）。 */
+  when?: string;
+  /** "Not for ..." 负向路由提示。 */
+  notFor?: string;
+}
+
+/** workflow 专属：phases + 参数契约 + 语义说明。 */
+export interface WorkflowMeta extends ResourceMetaBase {
+  kind: "workflow";
+  phases: (string | { title: string; detail?: string })[];
+  /** 参数契约（JSON Schema draft-07）。未声明则 $ARGS 透传不校验（向后兼容）。 */
+  parameters?: Record<string, unknown>;
+  /** markdown，覆盖 schema 表达不了的语义约束 + 真实合法示例命令。 */
+  usage?: string;
+}
+
+/** agent 路由样本（结构化，非嵌入 description 字符串）。 */
+export interface RoutingExample {
+  match: string;
+  action: string;
+  /** true=应触发，false=不应触发（正反各一）。 */
+  positive: boolean;
+}
+
+/** agent 专属：路由样本 + 执行配置。 */
+export interface AgentMeta extends ResourceMetaBase {
+  kind: "agent";
+  examples?: RoutingExample[];
+  /** 供 AgentRegistry 执行侧 spawn 时注入，不进 system prompt 注入段。 */
+  tools?: string[];
+  model?: string;
+}
+
+/** 判别联合（kind 判别）。 */
+export type ResourceMeta = WorkflowMeta | AgentMeta;

package/workflows/README.md

@@ -56,7 +56,7 @@ workflow run map-reduce --args itemsJson=/path/to/items.json --args operation=".
 
 ```
 workflow run review-fix-loop --args targetType=git-diff target=main \
-  --args batch1=fallow-scan --args batch2=reviewer --args autoCommit=true
+  --args batch1=fallow-scan --args batch2=code-reviewer --args autoCommit=true
 workflow run review-fix-loop --args targetType=file target=/path/to/doc.md \
   --args batch1=doc-reviewer
 ```
@@ -64,7 +64,7 @@ workflow run review-fix-loop --args targetType=file target=/path/to/doc.md \
 - `targetType` 枚举：`git-diff`（target=base ref）/ `file`（target=路径）/ `dir`（target=目录）/ `text`（target=自由描述）
 - `batch1..batchN`：批串行，批内并行 review → aggregate → fix → 重审直到 clean；批次用于前置依赖（如 `fallow-scan` 静态分析先行，后续审查才有意义）
 - 批内某 agent 无 must-fix 后后续轮跳过（`skipCleanAgents` 默认 true + `recheckAfterFix` 默认 false）：clean agent 下轮跳过不重派；显式传 `recheckAfterFix=true` 启用强回归模式——fix 后重派全批，clean agent 走限定 prompt（只审 modifiedFiles ∪ 自检关联点，不诱导全量重扫）
-- agent 项支持：AgentRegistry 名（如 `reviewer`）/ 自定义 .md 文件路径（如 `batch1=/path/to/reviewer.md`）/ 内置 `fallow-scan` / **内置 `doc-reviewer`**（文档场景推荐：`targetType=file/dir` + `batch1=doc-reviewer`，四遍审查方法论：事实锚点核实/逻辑断言验证/落地清单完备性/边界与迁移；无 write 工具，报告经 schema 返回由 workflow 落盘）
+- agent 项支持：AgentRegistry 名（如 `code-reviewer`）/ 自定义 .md 文件路径（如 `batch1=/path/to/code-reviewer.md`）/ 内置 `fallow-scan` / **内置 `doc-reviewer`**（文档场景推荐：`targetType=file/dir` + `batch1=doc-reviewer`，四遍审查方法论：事实锚点核实/逻辑断言验证/落地清单完备性/边界与迁移；无 write 工具，报告经 schema 返回由 workflow 落盘）
 - `fixAgent`（可选）：fix 阶段加载指定 agent（内置名或 .md 路径）；代码场景可在该 agent.md 内写 verify 命令（typecheck/test 实测）当轮拦截编译类回归。⚠️ agent.md 内写的 verify 命令**必须确认能在目标项目可运行**（target 的包管理器/目录结构未知），否则命令失败会误报 fix 状态
 - `maxFixAttempts`（可选，默认 2）：needs-redesign 阈值。问题经 maxFixAttempts 次修复仍未收敛（regressed）→ 终止该批，terminated="needs-redesign"（结构性问题需人工介入，非继续补丁能解决）
 - `convergeNewIssues`（可选，默认 1）+ `convergeRounds`（可选，默认 2）：新发现率收敛阈值。连续 convergeRounds 轮新发现问题 ≤ convergeNewIssues **且**无 open/regressed 活跃条目 → terminated="converged"（推进下一批）。收敛不等于问题全清——需同时满足无活跃条目才终止

package/workflows/_shared/agent-refs.cjs

@@ -0,0 +1,40 @@
+// workflows/_shared/agent-refs.cjs
+//
+// 编排 workflow 共用的 agentRef 参数解析（S4 路径统一）。
+//
+// agentRef = .md 绝对路径（注入段 <available_subagents> 的 <location>）。
+// agents 参数 = 逗号分隔的 agentRef 列表，按阶段顺序一一映射。
+// 缺省（未传/空）= 不指定 agent（默认执行者）——编排骨架不强制指定执行者。
+//
+// 注意：本模块只做「字符串 → 路径数组」的纯解析，不读文件。agent 内容的加载
+// 由主线程 resolveAgentOpts（agent-call 时按路径读 + systemPrompt 注入）统一完成。
+"use strict";
+
+/**
+ * 解析 agents 参数为 agentRef 路径数组。
+ *
+ * @param raw 逗号分隔字符串（如 "/a/x.md,/b/y.md"）；undefined/null/空 → []
+ * @returns 路径数组（trim + 去空项）
+ */
+function parseAgentRefs(raw) {
+  if (raw === undefined || raw === null) return [];
+  if (typeof raw !== "string") return [];
+  const refs = raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return refs;
+}
+
+/**
+ * 按阶段索引取 agentRef（缺省 undefined = 不指定 agent）。
+ *
+ * @param refs   parseAgentRefs 结果
+ * @param index  阶段索引（0-based）
+ * @returns agentRef 或 undefined
+ */
+function agentRefAt(refs, index) {
+  return refs.length > index ? refs[index] : undefined;
+}
+
+module.exports = { parseAgentRefs, agentRefAt };

package/workflows/chain.js

@@ -11,11 +11,22 @@
 //   - 禁止 bare IIFE（用 top-level await）
 //   - 禁止用 result 作变量名
 
-const meta = {
-  name: "chain",
-  description: "通用编排：analyze → transform → synthesize 顺序三步链",
-  phases: ["analyze", "transform", "synthesize"],
-};
+/* @pi-meta
+name: chain
+description: 通用编排：analyze → transform → synthesize 顺序三步链
+phases: [analyze, transform, synthesize]
+parameters:
+  type: object
+  properties:
+    task: { type: string, minLength: 1 }
+    agents: { type: string }
+  required: [task]
+usage: |
+  ## 使用说明
+  - 顺序三步链：analyze（提取要点）→ transform（产出方案）→ synthesize（合成结论）
+  - agents：逗号分隔的 agent .md 绝对路径，按顺序对应三步（少于 3 个尾部用默认执行者）
+  - 示例：workflow run chain --args task="<任务描述>" agents="/path/analyzer.md,/path/planner.md"
+*/
 
 // ── 入参（$ARGS）──────────────────────────────────────────────────
 const task = $ARGS.task;
@@ -23,7 +34,17 @@ if (typeof task !== "string" || task.trim() === "") {
   throw new Error("chain 缺少必需参数 task（非空字符串）。用法：workflow run chain --args task=\"<描述>\"");
 }
 
-log("chain 开始，task=" + task);
+// S4：agents 参数 = 逗号分隔的 agentRef 路径数组，按阶段顺序对应三步
+// worker 沙箱为 eval 模式：require 相对路径以 cwd 为基准（非脚本目录），
+// 必须用 workerData.scriptPath 锚定脚本目录（review-fix-loop 同模式）。
+const SCRIPT_DIR = workerData && workerData.scriptPath
+  ? require("path").dirname(workerData.scriptPath)
+  : process.cwd();
+const { parseAgentRefs, agentRefAt } = require(SCRIPT_DIR + "/_shared/agent-refs.cjs");
+const agentRefs = parseAgentRefs($ARGS.agents);
+const stepAgent = (i) => { const ref = agentRefAt(agentRefs, i); return ref ? { agent: ref } : {}; };
+
+log("chain 开始，task=" + task + (agentRefs.length ? "，agents=" + agentRefs.join(",") : ""));
 
 let currentPhase = "init";
 let outcome;
@@ -47,6 +68,7 @@ try {
       required: ["insights", "keyPoints"],
     },
     description: "chain-analyze",
+    ...stepAgent(0),
   });
 
   // ── 段 2：transform（基于分析产出方案）───────────────────────────
@@ -69,6 +91,7 @@ try {
       required: ["plan", "actions"],
     },
     description: "chain-transform",
+    ...stepAgent(1),
   });
 
   // ── 段 3：synthesize（综合方案输出最终结论）─────────────────────
@@ -87,6 +110,7 @@ try {
       required: ["summary", "recommendation"],
     },
     description: "chain-synthesize",
+    ...stepAgent(2),
   });
 
   outcome = {

package/workflows/map-reduce.js

@@ -13,11 +13,27 @@
 //
 // ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口（兼 agent 嵌套），禁止 bare IIFE
 
-const meta = {
-  name: "map-reduce",
-  description: "通用编排：parallel map → reduce 两段，处理已知 items 数组",
-  phases: ["map", "reduce"],
-};
+/* @pi-meta
+name: map-reduce
+description: 通用编排：parallel map → reduce 两段，处理已知 items 数组
+phases: [map, reduce]
+parameters:
+  type: object
+  properties:
+    items: { type: array, items: { type: string } }
+    itemsJson: { type: string }
+    operation: { type: string }
+    agents: { type: string }
+  required: [operation]
+  oneOf:
+    - required: [items]
+    - required: [itemsJson]
+usage: |
+  ## 使用说明
+  - items 与 itemsJson 至少一个：items 直接传字符串数组，itemsJson 传文件路径（内容为 JSON 数组）
+  - agents：逗号分隔的 agent .md 绝对路径，按顺序对应 map/reduce 两段
+  - 示例：workflow run map-reduce --args operation="<对每个 item 做什么>" itemsJson="/path/items.json" agents="/path/mapper.md,/path/reducer.md"
+*/
 
 const fs = require("fs");
 
@@ -50,6 +66,16 @@ if (!Array.isArray(items) || items.length === 0) {
 
 log("map-reduce 开始，items=" + items.length + " 个，operation=" + operation);
 
+// S4：agents 参数 = 逗号分隔的 agentRef 路径数组，按顺序对应 map/reduce 两段
+// worker 沙箱为 eval 模式：require 相对路径以 cwd 为基准（非脚本目录），
+// 必须用 workerData.scriptPath 锚定脚本目录（review-fix-loop 同模式）。
+const SCRIPT_DIR = workerData && workerData.scriptPath
+  ? require("path").dirname(workerData.scriptPath)
+  : process.cwd();
+const { parseAgentRefs, agentRefAt } = require(SCRIPT_DIR + "/_shared/agent-refs.cjs");
+const agentRefs = parseAgentRefs($ARGS.agents);
+const stepAgent = (i) => { const ref = agentRefAt(agentRefs, i); return ref ? { agent: ref } : {}; };
+
 let currentPhase = "init";
 let outcome;
 
@@ -74,6 +100,7 @@ try {
           required: ["itemIndex", "mapped"],
         },
         description: "map-reduce-map-" + idx,
+        ...stepAgent(0),
       })
     ),
   );
@@ -121,6 +148,7 @@ try {
       required: ["reduced", "stats"],
     },
     description: "map-reduce-reduce",
+    ...stepAgent(1),
   });
 
   outcome = {