@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

package/src/orchestration/agent-opts-resolver.ts

@@ -1,174 +0,0 @@
-/**
- * Agent options resolver — resolves skill / schema to append-system-prompt
- * content + env vars on every dispatch (BL-1).
- *
- * BL-1：解析 workflow 脚本里 `agent({skill,schema})` 的 inline override，
- * 否则 pi 子进程只收到原始 prompt，没有 --append-system-prompt /
- * --skill / PI_WORKFLOW_SCHEMA。
- *
- * 职责范围（M2 修正）：仅处理 schema SO 指令（内容直传 appendSystemPrompt）+ skill。
- * agent ref 处理（systemPrompt/model/thinkingLevel）已移交 resolveIdentity（execution 层，
- * 经 getAgentConfig + resolveModel 完整覆盖），消除双重注入与 model 层级混乱。
- *
- * 调用方：engine/error-recovery.ts dispatchAgentCall（每次 agent-call 消息）。
- * - skill → resolveSkillPath → skillPath（--skill）
- * - schema → 结构化输出指令内容直传 appendSystemPrompt（--append-system-prompt）+ schemaEnv（PI_WORKFLOW_SCHEMA）
- *
- * M2 bug 修正：旧实现把 schema 指令写成临时文件、push 文件路径（而非内容）给下游，
- * 下游 mapper/session-runner 把路径当文本拼进最终 append 文件，导致 schema 指令从未
- * 进入子进程。改为指令内容直传（不写盘、无临时文件）。
- */
-
-import type { AgentCallOpts } from "./models/types.ts";
-import { resolveSkillPath } from "./skill-discovery.ts";
-import { stringifySchemaCached } from "../shared/schema-jsonify.ts";
-
-export interface ResolveResult {
-  opts: AgentCallOpts;
-  error?: string;
-}
-
-// ── 根类型判定（与 structured-output 同源，本地副本） ──────────────
-
-/** plain object 判定（isPlainObject，与 @zhushanwen/pi-structured-output schema-guards.ts 同语义）。 */
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/**
- * [U3 本地副本·同源锚定] 判定权威 schema 的根数据形态是否为 object。
- *
- * 与 @zhushanwen/pi-structured-output `src/execute.ts` 的 `isObjectRootSchema`
- * 逐语义一致（该函数是 structured-output 工具 parameters {value} 包装/解包的唯一
- * 判定源）。两包是独立 npm 包不能直接 import——optional peer 依赖在独立安装场景
- * （pi 用户单独装本包）不保证存在，顶层值 import 会让整个 extension 加载崩溃；
- * 且 builtin esbuild bundle 会把 import 的包内联成双实例（先例：session-runner.ts
- * 的 PI_WORKFLOW_SCHEMA env 契约注释）。故本地复制，任一端改动判定逻辑必须同步
- * 另一端（两端 docstring 互相锚定）。
- *
- * draft-07 语义：无 type 时类型关键字按值形态适用——properties/required 等
- * object 特有关键字的存在意味着作者在描述 object 输出，算 object 根；组合根
- * （anyOf/oneOf/allOf/$ref/enum）可能接受非 object 值，保真起见一律按非 object
- * （{value} 包装可容纳任意成员类型）。
- */
-function isObjectRootSchema(schema: unknown): schema is Record<string, unknown> {
-  if (!isPlainObject(schema)) return false;
-  if (schema.type === "object") return true;
-  if (Array.isArray(schema.type) && schema.type.includes("object")) return true;
-  const OBJECT_ONLY_KEYS = [
-    "properties",
-    "required",
-    "patternProperties",
-    "additionalProperties",
-    "minProperties",
-    "maxProperties",
-    "dependencies",
-    "dependentRequired",
-    "propertyNames",
-  ];
-  return OBJECT_ONLY_KEYS.some((k) => k in schema);
-}
-
-/**
- * 构造 schema structured-output 指令——resolver 单点注入的唯一文案源。
- *
- * [审查项#2] 消费链：resolveAgentOpts → appendSystemPrompt（ASP 稳定前缀区）。
- * 此前 session-runner 有一份措辞相近的同名函数并把指令拼进 task 末尾，形成
- * ASP + task 双重静态注入；task 后缀已删（task 每 agent 变化不可缓存，工具
- * parameters 是 pi 必然注入的权威展示——注册工具 schema 随每次请求下发进
- * provider 请求体，机制登记 PS-21：pi-ai dist/api/anthropic-messages.js
- * convertTools :1000/:1008 → :1017 input_schema、openai-completions.js :1099
- * parameters——schema 全文不必在 task 重复，文本重复浪费 ~730 tokens/子进程）。
- *
- * [审查项#4] AP 告知：注入侧校验用 additionalProperties:false 收窄后的
- * parameters，模型自带 schema 外字段会被拒——不前置告知，拒绝显得凭空。
- *
- * JSON 序列化用 compact（stringifySchemaCached），与 schemaEnv 复用同串（IF7 #13）。
- */
-export function formatSchemaInstruction(schema: Record<string, unknown>): string {
-  const schemaJson = stringifySchemaCached(schema, "compact");
-  // [U3] 根类型条件化：判定与 structured-output 的工具 parameters {value} 包装/解包
-  // 同源（上方 isObjectRootSchema 本地副本）。object 根 arguments 即 data；非 object
-  // 根参数层实为 {value} 包装——ASP 文案必须与工具 description 同语汇告知包装契约
-  // （{value: <data>} + value. 错误路径前缀），否则模型直传裸值必首调失败。
-  const isObjectRoot = isObjectRootSchema(schema);
-  const argsContractLine = isObjectRoot
-    ? "Your call arguments ARE the result data itself — the tool's parameter schema IS the required shape of your result."
-    : "The tool's single argument must be an object `{value: <data>}` — put the result itself in `value`, and it must conform to the schema below. " +
-      "Validation errors may reference paths starting with `value.` (e.g. `value.0`, `value.name`): " +
-      "that prefix addresses the wrapper, not your data.";
-  const rulesCallLine = isObjectRoot
-    ? "- Call the structured-output tool with your result data as its arguments. The system validates them against the schema above automatically."
-    : "- Call the structured-output tool with `{value: <your result data>}`. The system validates the `value` field against the schema above automatically.";
-  // [AP 告知条件化] 根级 additionalProperties 未声明时 D4 注入 false（见
-  // structured-output tool-definition）——额外字段恒拒绝，强承诺成立；作者显式声明
-  // true / 子 schema 时 injection 侧尊重不动，额外字段按作者声明放行，无条件
-  // 「一律拒绝」文案与参数层行为不符（保守方向误导：模型不敢传合法字段）。
-  const apLine = schema.additionalProperties === undefined
-    ? "- Fields not defined in this schema are rejected — do not add extra fields."
-    : "- Extra fields follow this schema's own additionalProperties declaration.";
-  return [
-    "## MANDATORY: Structured Output Requirement",
-    "",
-    "This task requires structured output.",
-    "Your FINAL action must be calling the `structured-output` tool.",
-    "",
-    argsContractLine,
-    `Your result must conform to this schema:`,
-    "```json",
-    schemaJson,
-    "```",
-    "",
-    "Rules:",
-    rulesCallLine,
-    "- Do NOT output JSON in your text response — use the structured-output tool.",
-    "- Do NOT skip this step. The structured-output call IS your result.",
-    "- Complete all other work FIRST, then call structured-output as the last action.",
-    apLine,
-  ].join("\n");
-}
-
-/**
- * Resolve skill and schema into appendSystemPrompt (content array) + skillPath + schemaEnv.
- *
- * - Skill name -> resolved SKILL.md dir path via --skill
- * - Schema JSON -> structured-output instruction string pushed into appendSystemPrompt
- *   (content, not file path) + PI_WORKFLOW_SCHEMA env
- *
- * Agent ref is intentionally NOT handled here — resolveIdentity (execution layer)
- * covers it via getAgentConfig + resolveModel. Handling agent here would cause
- * double-injection (agentConfig.systemPrompt at session-runner + appendSystemPrompt)
- * and model-tier confusion.
- *
- * Returns the enriched opts.
- */
-export function resolveAgentOpts(opts: AgentCallOpts): ResolveResult {
-  const appendSystemPrompt: string[] = [];
-
- // Resolve skill name to SKILL.md path
-  if (opts.skill) {
-    const skillPath = resolveSkillPath(opts.skill);
-    if (!skillPath) {
-      return { opts, error: `Skill not found: ${opts.skill}. Searched .agents/skills/ and ~/.pi/agent/skills/` };
-    }
-    opts = { ...opts, skillPath };
-  }
-
- // Inject schema as structured-output instruction into appendSystemPrompt (content,
- // not temp file) and set environment variable for conditional tool + hook activation.
- // M2 fix: previously wrote the instruction to a temp file and pushed the FILE PATH,
- // which got concatenated into the final append file as path garbage — the SO instruction
- // never reached the subprocess. Now the instruction content is pushed directly.
-  if (opts.schema) {
-    // IF7(#13)：formatSchemaInstruction 与 schemaEnv 对同一 schema 对象引用共享
-    // WeakMap 缓存条目（compact stringify 整个 dispatch 只发生一次）
-    appendSystemPrompt.push(formatSchemaInstruction(opts.schema));
-
- // Set env var for structured-output extension to activate tool + hook
-    opts = { ...opts, schemaEnv: stringifySchemaCached(opts.schema, "compact") };
-  }
-
-  return {
-    opts: { ...opts, ...(appendSystemPrompt.length > 0 ? { appendSystemPrompt } : {}) },
-  };
-}

package/src/orchestration/args-validator.ts

@@ -1,127 +0,0 @@
-// src/orchestration/args-validator.ts
-//
-// m3：参数校验单一 chokepoint（IF3 validateRunArgs + IF4 ArgsValidationError）。
-// lifecycle.runWorkflow 首行调用——§5.3 fail-fast：参数错误在 worker 启动前返回，
-// 带「read 脚本重看」指引。
-//
-// 设计决策（m3 design-review 探针实证）：
-// - ajv 选项钉死 { coerceTypes:true, strictSchema:false, allErrors:true, useDefaults:false }：
-//   coerceTypes 原地规范化弱 LLM 的字符串参数（'false'→false、'10'→10，m2 MAJOR-1 闭环）；
-//   strictSchema:false 容忍用户 workflow 的自定义关键字/format（默认 strict:true 会误判畸形）；
-//   useDefaults:false 不注入 schema default（脚本 fallback 语义不变）。
-// - 无缓存：ajv.compile 实测 0.006ms/次（[P-compile]），v5 §6.5 的 Map 缓存被探针证据推翻。
-// - null-scan + required 空串复查：coerceTypes 下 {target:null} 会被 coerce 成 "" 放行
-//   required（required 只查属性存在性）——null 视为缺失、必填字符串空串视为失败，
-//   与 review-fix-loop 脚本的 !target 语义对齐，保住「启动前 fail-fast」承诺。
-
-import Ajv from "ajv";
-
-import type { RunSpec } from "./models/run-spec.ts";
-
-/** 参数校验失败（§5.3）。三调用方各自 catch 并映射到返回类型。 */
-export class ArgsValidationError extends Error {
-  readonly workflowName: string;
-  /** ajv 校验错误数组（畸形 schema 时为 undefined）。 */
-  readonly errors?: readonly unknown[];
-
-  constructor(workflowName: string, message: string, errors?: readonly unknown[]) {
-    super(message);
-    this.name = "ArgsValidationError";
-    this.workflowName = workflowName;
-    this.errors = errors;
-  }
-}
-
-const ajv = new Ajv({
-  coerceTypes: true,
-  strictSchema: false,
-  allErrors: true,
-  useDefaults: false,
-});
-
-/** §5.3 错误文案：workflow 名 + errors 摘要 + info 指引。 */
-function formatMessage(name: string, errors: readonly unknown[]): string {
-  const lines = errors.map((e) => {
-    let path = "/";
-    let msg = "invalid";
-    if (e !== null && typeof e === "object") {
-      const err = e as Record<string, unknown>;
-      if (typeof err.instancePath === "string" && err.instancePath) path = err.instancePath;
-      if (typeof err.message === "string") msg = err.message;
-    }
-    return `- ${path}: ${msg}`;
-  });
-  return (
-    `Invalid args for workflow '${name}': ${errors.length} error(s)\n` +
-    `${lines.join("\n")}\n` +
-    `Read the workflow script file (location from <available_workflows>) for the parameter schema and usage.`
-  );
-}
-
-/**
- * 校验 spec.parameters（JSON Schema draft-07）对 spec.args 的约束。
- *
- * - spec.parameters === undefined → 跳过（安全退化：漏拷 parameters 退化是「不校验」非「校验错」）
- * - coerceTypes 原地规范化 spec.args（worker 启动 + 崩溃重建重跑共用同一对象，
- *   run.spec === spec，保证重跑路径参数一致）
- * - 失败 throw ArgsValidationError（非原始 ajv 错误）
- *
- * @throws ArgsValidationError 参数不合法或 schema 无效
- */
-export function validateRunArgs(spec: RunSpec): void {
-  const { parameters, args, scriptName } = spec;
-  if (parameters === undefined) return;
-
-  if (parameters === null || typeof parameters !== "object" || Array.isArray(parameters)) {
-    throw new ArgsValidationError(
-      scriptName,
-      `Workflow '${scriptName}' has an invalid parameter schema (expected object). Read the workflow script file (location from <available_workflows>) to inspect it.`,
-    );
-  }
-
-  // null-scan：null 值视为缺失（coerceTypes 会把 null→"" 放行 required，绕过 fail-fast）。
-  // 只删 schema 未声明 nullable 的键——type 含 "null"（如 ["string","null"]）的合法 null
-  // 输入保留（m3 exec-review M1 探针实证：全键删除会拒掉 nullable required 的合法值）。
-  const schema = parameters as Record<string, unknown>;
-  const properties =
-    schema.properties !== null && typeof schema.properties === "object"
-      ? (schema.properties as Record<string, unknown>)
-      : {};
-  for (const key of Object.keys(args)) {
-    if (args[key] !== null) continue;
-    const prop = properties[key];
-    let isNullable = false;
-    if (prop !== null && typeof prop === "object") {
-      const propType = (prop as Record<string, unknown>).type;
-      isNullable = Array.isArray(propType)
-        ? (propType as unknown[]).includes("null")
-        : propType === "null";
-    }
-    if (!isNullable) delete args[key];
-  }
-
-  let validate: ReturnType<Ajv["compile"]>;
-  try {
-    validate = ajv.compile(parameters);
-  } catch (err) {
-    // 真畸形 schema（如 type:'not-a-type'）→ 结构化 ArgsValidationError，不泄漏原始 throw
-    const detail = err instanceof Error ? err.message : String(err);
-    throw new ArgsValidationError(
-      scriptName,
-      `Workflow '${scriptName}' has an invalid parameter schema: ${detail}. Read the workflow script file (location from <available_workflows>) to inspect it.`,
-    );
-  }
-
-  if (!validate(args)) {
-    throw new ArgsValidationError(
-      scriptName,
-      formatMessage(scriptName, validate.errors ?? []),
-      validate.errors ?? undefined,
-    );
-  }
-  // 注：非空约束由 schema 声明（minLength/pattern），chokepoint 不发明约束——
-  // m3 exec-review M2：硬编码 trim 空串复查与 schema 显式语义（enum 含 ''/minLength:0）
-  // 矛盾。review-fix-loop 的 target 用 { minLength: 1, pattern: '\\S' } 表达。
-  // 校验失败时 spec.args 可能已被 null-scan/coerce 部分 mutate（文档化行为：失败后
-  // 调用方不应复用该 args 对象）。
-}

package/src/orchestration/config-loader.ts

@@ -1,315 +0,0 @@
-/**
- * Workflow Config Loader — 统一资源发现版（ADR-031）
- *
- * 扫描逻辑委托给 shared/resource-discovery（与 agent 发现共享同一套扫描源）。
- * 本文件只保留 workflow 专属的 meta 提取（经 shared/meta-parser.ts IF1 统一 parser）+ 60s TTL 缓存。
- *
- * m2 收敛：删 extractMetaViaRegex + safeEvalObject(new Function)，改调 parseResourceMeta
- * （真实 YAML 解析 @pi-meta 块注释，发现期不执行作者代码，v5 原则 6 no-eval）。
- * toCachedMeta 整对象透传（...meta），不再 {name,description,phases} 解构——消灭第 1 处重映射。
- *
- * Failed imports are marked available=false — the loader never throws.
- */
-
-
-import { resolve } from "node:path";
-
-// WorkflowMeta 规范来源是 shared/resource-meta.ts（m1 DM1）；WorkflowSource 来自 workflow-script
-import type { WorkflowSource } from "./models/workflow-script.ts";
-import { clearLintMemo } from "./models/workflow-script.ts";
-import type { WorkflowMeta } from "../shared/resource-meta.ts";
-import { getCachedFile, getCachedFileContent, clearFileCache } from "../shared/resource-discovery.ts";
-import { parseResourceMeta } from "../shared/meta-parser.ts";
-import { normalizeRef, WORKFLOW_REF_EXT } from "../shared/agent-ref.ts";
-export type { WorkflowMeta, WorkflowSource };
-
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-const logger = getLogger("config-loader");
-
-import {
-  discoverResources,
-  findWorkspaceRoot,
-  type ResourceSource,
-  type ScanConfig,
-} from "../shared/resource-discovery.ts";
-
-// ── Public types ──────────────────────────────────────────────
-
-export interface CachedWorkflowMeta extends WorkflowMeta {
-  /** Absolute path to the script file */
-  path: string;
-  /** false when the script failed to load or has no valid meta export */
-  available: boolean;
-  /** Whether this is a saved (fixed) or temporary (ad-hoc) workflow */
-  source: WorkflowSource;
-}
-
-// ── Internal types ────────────────────────────────────────────
-
-interface CacheEntry {
-  meta: CachedWorkflowMeta;
-  /** 文件 mtime（m5：mtime 键控判失效——删 60s TTL，mtime 未变即命中）。 */
-  mtimeMs: number;
-}
-
-// ── Constants ─────────────────────────────────────────────────
-
-// m5：删 60s TTL——mtime 键控判失效（TTL 只服务 getWorkflow 且造成 60s 陈旧窗口）。
-
-// ── Cache ─────────────────────────────────────────────────────
-
-// Keyed by workspace root so that switching projects does not serve stale entries.
-const cache = new Map<string, Map<string, CacheEntry>>();
-
-function getCacheBucket(workspaceRoot: string): Map<string, CacheEntry> {
-  let bucket = cache.get(workspaceRoot);
-  if (!bucket) {
-    bucket = new Map<string, CacheEntry>();
-    cache.set(workspaceRoot, bucket);
-  }
-  return bucket;
-}
-
-function isCacheValid(entry: CacheEntry): boolean {
-  // m5：mtime 判变——文件 mtime 未变即命中（删 TTL 后文件变更立即反映）
-  const file = getCachedFile(entry.meta.path);
-  return file !== null && file.mtimeMs === entry.mtimeMs;
-}
-
-// ── Helpers ───────────────────────────────────────────────────
-
-/** Extract filename stem (no directory, no extension). */
-function stem(filePath: string): string {
-  const base = filePath.split("/").pop() ?? filePath;
-  const dot = base.lastIndexOf(".");
-  return dot > 0 ? base.slice(0, dot) : base;
-}
-
-// ── ResourceSource → WorkflowSource 映射 ─────────────────────
-
-/** 统一模块的 ResourceSource 映射为 workflow 的 saved/tmp 语义 */
-function toWorkflowSource(source: ResourceSource): WorkflowSource {
-  return source === "project-pi-tmp" ? "tmp" : "saved";
-}
-
-/**
- * 按路径推导 ResourceSource（IF4/外部 #5 残留）。
- *
- * getWorkflowByPath 可加载任意绝对路径（不限扫描源），此前硬编码 "user-pi"
- * 使 workspaceRoot/.pi/workflows/.tmp/ 下的临时脚本按路径加载被错标 saved
- * （discoverWorkflows 对同文件正确标 tmp，两路径不一致）。修正：路径落在
- * tmp 目录前缀内 → "project-pi-tmp"，其余 → "user-pi"（非 tmp 路径输出不变，DS4）。
- */
-function deriveResourceSource(filePath: string, workspaceRoot: string): ResourceSource {
-  const tmpDir = resolve(workspaceRoot, ".pi/workflows/.tmp");
-  const normalized = resolve(filePath);
-  return normalized === tmpDir || normalized.startsWith(`${tmpDir}/`) ? "project-pi-tmp" : "user-pi";
-}
-
-// ── 单文件 → CachedWorkflowMeta（IF1 parseResourceMeta + 整对象透传）──
-
-/**
- * 提取单个文件的 meta（经 IF1 parseResourceMeta），失败时标 available=false（fail-safe 不抛）。
- *
- * m2：整对象透传（...meta），不再 {name,description,phases} 解构——消灭第 1 处重映射，
- * parameters/usage/when/notFor 一路流到 script.meta。仅认 @pi-meta 新格式（D1 无 adapter）。
- */
-async function toCachedMeta(
-  filePath: string,
-  source: ResourceSource,
-): Promise<CachedWorkflowMeta> {
-  const fallbackName = stem(filePath);
-  const wfSource = toWorkflowSource(source);
-  try {
-    const content = getCachedFileContent(filePath); // m5：统一 mtime 缓存层
-    if (content === null) throw new Error("file not readable");
-    const meta = parseResourceMeta(content, "workflow");
-    if (meta && meta.kind === "workflow") {
-      return { ...meta, path: filePath, available: true, source: wfSource };
-    }
-    // m2 exec-review MINOR-4：文件可读但 meta=null → 旧 const meta 格式或格式错误，
-    // 静默 available=false（D1 无 adapter）。warn 帮助用户定位需迁移到 @pi-meta 的存量 workflow。
-    logger.warn(
-      `[config-loader] ${filePath}: 未解析到 @pi-meta 元数据（旧 const meta 格式需迁移）→ available=false`,
-    );
-  } catch (err) {
-    // 读失败 → available=false（fail-safe 不抛，与原行为一致）
-    logger.debug(`[config-loader] skip unreadable workflow file ${filePath}`, {
-      reason: err instanceof Error ? err.message : String(err),
-    });
-  }
-  return {
-    kind: "workflow",
-    name: fallbackName,
-    description: "",
-    phases: [],
-    path: filePath,
-    available: false,
-    source: wfSource,
-  };
-}
-
-// ── Public API ────────────────────────────────────────────────
-
-/**
- * workflow 发现的扫描配置。每个字段显式声明一个扫描源目录。
- *
- * 生产环境用 defaultScanConfig() 构造默认值（全局 ~/.pi/agent/* 目录）。
- * 测试/隔离环境构造完整 config 指向 tmp 目录，完全不碰全局文件系统。
- */
-export interface WorkflowScanConfig {
-  /** 项目级脚本目录（workspaceRoot/.pi/workflows） */
-  projectDir: string;
-  /** user 级脚本目录（~/.pi/agent/workflows） */
-  userDir: string;
-  /** 临时脚本目录（workspaceRoot/.pi/workflows/.tmp） */
-  tmpDir: string;
-  /** npm 包扫描目录（~/.pi/agent/npm/node_modules 等） */
-  npmDirs: string[];
-}
-
-/**
- * 把 WorkflowScanConfig 转为统一模块的 ScanConfig。
- *
- * 测试隔离场景下传入完整 config——此时按声明的 projectDir/tmpDir 反推
- * workspaceRoot（与原行为一致：resolve(config.projectDir, "../..")）。
- * 生产场景（省略或部分 config）走 findWorkspaceRoot(cwd)。
- */
-function toScanConfig(
-  configOrCwd: Partial<WorkflowScanConfig> & { cwd?: string } | undefined,
-): ScanConfig {
-  // 测试隔离：传入了 projectDir，直接反推 workspaceRoot
-  if (configOrCwd?.projectDir) {
-    const workspaceRoot = resolve(configOrCwd.projectDir, "../..");
-    return {
-      kind: "workflows",
-      workspaceRoot,
-      agentDir: "test-no-agent-dir",
-      includeTmp: true,
-    };
-  }
-
-  // 生产默认
-  const cwd = configOrCwd?.cwd;
-  const workspaceRoot = findWorkspaceRoot(cwd);
-  return {
-    kind: "workflows",
-    workspaceRoot,
-    agentDir: getAgentDir(),
-    includeTmp: true,
-  };
-}
-
-/**
- * 从指定 config 扫描所有 workflow 脚本，按 tmp>project>npm>user 优先级
- * 去重，60s TTL 缓存（按 workspaceRoot 分桶）。
- *
- * 扫描逻辑委托给 shared/resource-discovery（与 agent 发现共享同一套扫描源）。
- *
- * Never throws. 解析失败的脚本以 available=false 返回。
- *
- * @param configOrCwd 完整 WorkflowScanConfig（隔离用）、部分字段（覆盖默认）、
- *                   或省略（纯生产默认）。可选 cwd 用于推导 workspaceRoot。
- */
-export async function discoverWorkflows(
-  configOrCwd?: Partial<WorkflowScanConfig> & { cwd?: string },
-): Promise<CachedWorkflowMeta[]> {
-  const scanConfig = toScanConfig(configOrCwd);
-  const workspaceRoot = scanConfig.workspaceRoot;
-
-  // 统一发现：返回已去重的资源列表（按优先级合并）
-  const resources = await discoverResources(scanConfig);
-
-  // 提取 meta（逐文件）
-  const mergedMap = new Map<string, CachedWorkflowMeta>();
-  for (const resource of resources) {
-    const cachedMeta = await toCachedMeta(resource.path, resource.source);
-    // available=false 的不覆盖已有的 available=true（与统一模块逻辑一致）
-    if (!cachedMeta.available && mergedMap.has(cachedMeta.name)) {
-      continue;
-    }
-    mergedMap.set(cachedMeta.name, cachedMeta);
-  }
-
-  // 按 name 码点序输出（KV-cache 契约，与 injector 层一致）：不依赖发现层
-  // 优先级迭代序 / readdir 枚举序，重建结果顺序稳定。
-  const merged = Array.from(mergedMap.values()).sort((a, b) =>
-    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
-  );
-
-  // Update cache (scoped to current workspace root)
-  const bucket = getCacheBucket(workspaceRoot);
-  for (const wf of merged) {
-    const file = getCachedFile(wf.path);
-    bucket.set(wf.name, { meta: wf, mtimeMs: file?.mtimeMs ?? 0 });
-  }
-
-  return merged;
-}
-
-/**
- * Load and cache all available workflow scripts from project-level
- * (.pi/workflows/) and user-level (~/.pi/agent/workflows/) directories.
- *
- * discoverWorkflows() 的生产 preset——用全局默认目录。
- *
- * Never throws. Failed imports are returned with available=false.
- */
-export async function loadWorkflows(): Promise<CachedWorkflowMeta[]> {
-  return discoverWorkflows();
-}
-
-/**
- * Get a specific workflow by name.
- * Returns cached result if still valid, otherwise triggers a fresh load.
- */
-export async function getWorkflow(name: string): Promise<CachedWorkflowMeta | undefined> {
-  const workspaceRoot = findWorkspaceRoot();
-  const bucket = getCacheBucket(workspaceRoot);
-  const cached = bucket.get(name);
-  if (cached && isCacheValid(cached)) {
-    return cached.meta;
-  }
-
-  const workflows = await loadWorkflows();
-  return workflows.find((wf) => wf.name === name);
-}
-
-/**
- * 按绝对路径加载单个 workflow（workflowRef 统一解析入口——S2 路径统一）。
- *
- * - ~/ 前缀展开；相对路径/非 .js 引用返回 undefined（引用唯一形态 = 绝对路径）
- * - 任意路径（不限扫描源）：内置包内脚本、用户任意位置脚本均可执行
- * - meta 提取失败/文件不可读 → available=false（fail-safe，不抛）
- * - [perf] 与 getWorkflow(name) 对称走 bucket 缓存（key=绝对路径，与 stem 名不冲突），
- *   消除 workflow tool 主路径每次 run 的全文 regex + YAML.parse（mtime 判变失效）
- */
-export async function getWorkflowByPath(ref: string): Promise<CachedWorkflowMeta | undefined> {
-  const filePath = normalizeRef(ref, WORKFLOW_REF_EXT);
-  if (filePath === null) return undefined;
-  const workspaceRoot = findWorkspaceRoot();
-  const bucket = getCacheBucket(workspaceRoot);
-  const cached = bucket.get(filePath);
-  if (cached && isCacheValid(cached)) {
-    return cached.meta;
-  }
-  // IF4：source 按路径推导——.tmp 前缀 → project-pi-tmp（→ "tmp"），其余 user-pi 维持现值
-  const meta = await toCachedMeta(filePath, deriveResourceSource(filePath, workspaceRoot));
-  const file = getCachedFile(filePath);
-  if (file) bucket.set(filePath, { meta, mtimeMs: file.mtimeMs });
-  return meta;
-}
-
-/**
- * Invalidate the internal meta cache.
- * The next call to loadWorkflows or getWorkflow will re-scan directories.
- */
-export function invalidateCache(): void {
-  // m5：清统一 mtime 缓存层 + bucket（测试隔离 + mtime 漏判场景手动刷新兜底）
-  // IF9：连带清 workflow-script validate 的 lint memo（同源文件缓存，测试隔离统一走它）
-  clearFileCache();
-  cache.clear();
-  clearLintMemo();
-}