@zhushanwen/pi-subagent-workflow 5.0.2 → 7.0.0

package/src/orchestration/models/types.ts

@@ -32,7 +32,9 @@ export type DoneReason =
   | "failed"
   | "aborted"
   | "budget_limited"
-  | "time_limited";
+  | "time_limited"
+  // m3：runAndWait 合成返回值专用——参数校验失败（run 从未创建，不进入 run.state.reason）
+  | "invalid_args";
 
 /** 合法的状态转换。空数组 = 无出边（done 终态）。 */
 export const VALID_RUN_TRANSITIONS: Record<RunStatus, readonly RunStatus[]> = {
@@ -47,6 +49,7 @@ export const ALL_DONE_REASONS: readonly DoneReason[] = [
   "completed",
   "failed",
   "aborted",
+  "invalid_args",
   "budget_limited",
   "time_limited",
 ] as const;
@@ -87,7 +90,7 @@ export interface AgentCallOpts {
  /**
  * Thinking level override (e.g. "high", "medium", "low").
  * M2: Added to align with subagent path's ExecuteOptions.thinkingLevel.
- * When omitted, agent .md frontmatter thinkingLevel is used (via resolveAgentOpts).
+ * When omitted, agent .md frontmatter thinkingLevel is used (via resolveIdentity/getAgentConfig).
  */
   thinkingLevel?: string;
  /** Scene name for model-switch advisor recommendation. */
@@ -111,16 +114,20 @@ export interface AgentCallOpts {
  /** Human-readable description for logging and debugging. */
   description?: string;
  /**
- * Agent name to resolve from AgentRegistry. When set, the resolved
- * agent's systemPrompt is injected via --append-system-prompt.
+ * Agent ref (absolute .md path). Resolved by resolveIdentity via getAgentConfig,
+ * which injects the agent's systemPrompt/model/tools/thinkingLevel. Not handled by
+ * resolveAgentOpts (single-responsibility: agent ref ownership belongs to resolveIdentity,
+ * M2 fix — previously overlapped causing double-injection + model-tier confusion).
  */
   agent?: string;
  /**
- * Absolute paths to temp files containing system prompt injections.
- * Set by agent-opts-resolver: agent systemPrompt + schema injection files.
- * buildArgs injects each via --append-system-prompt.
+ * System prompt injection CONTENT (not file paths).
+ * Set by agent-opts-resolver: schema structured-output instruction string.
+ * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
+ * mapToExecuteOptions passes this through to ExecuteOptions.appendSystemPrompt
+ * (same name/semantics, transparent passthrough).
  */
-  systemPromptFiles?: string[];
+  appendSystemPrompt?: string[];
  /**
  * Schema JSON for PI_WORKFLOW_SCHEMA env var.
  * Set by agent-opts-resolver when opts.schema is present; passed as env var

package/src/orchestration/models/workflow-script-registry.ts

@@ -27,6 +27,9 @@ export interface WorkflowScriptRegistry {
  /** 按名查单个脚本（含缓存）。返回 undefined 当 name 不存在。 */
   get(name: string): Promise<WorkflowScript | undefined>;
 
+ /** 按绝对路径加载单个脚本（workflowRef 统一解析入口——S2 路径统一）。 */
+  getPath(ref: string): Promise<WorkflowScript | undefined>;
+
  /** 失效缓存——下次 loadAll/get 重新扫描文件系统。 */
   invalidate(): void;
 }

package/src/orchestration/models/workflow-script.ts

@@ -18,19 +18,14 @@
 import { type LintResult,lintScript } from "../script-lint.ts";
 // LintFinding/LintResult 类型规范归属 engine/script-lint.ts（canonical 源）。
 
+// WorkflowMeta 规范来源是 shared/resource-meta.ts（m1 DM1，含 parameters/usage/when/notFor）。
+// m2：删本地封闭 3 字段 interface，re-export m1 的判别联合。
+import type { WorkflowMeta } from "../../shared/resource-meta.ts";
+export type { WorkflowMeta };
+
 /** 脚本来源：saved（.pi/workflows/ 固定）或 tmp（.pi/workflows/.tmp/ 临时）。 */
 export type WorkflowSource = "saved" | "tmp";
 
-/** 脚本元信息（regex 提取，不执行用户代码）。 */
-export interface WorkflowMeta {
-  name: string;
-  description: string;
-  phases: (string | { title: string; detail?: string })[];
-}
-
-/** strip `export const meta` → `const meta`（lifecycle.ts:66 逻辑迁移）。 */
-const EXPORT_META_PATTERN = /\bexport\s+const\s+meta\b/g;
-
 /**
  * WorkflowScript 实体。
  *
@@ -79,12 +74,13 @@ export class WorkflowScript {
   }
 
  /**
- * 返回可执行源（strip `export const meta` → `const meta`）。
+ * 返回可执行源。
  *
- * 脚本格式不变（AC-4）。Worker 线程 wrap（注入 globals）由 infra
- * infra/worker-script-builder.ts buildWorkerScript 完成——本方法只做纯文本变换。
+ * m2：不再 strip `export const meta`——meta 现为 @pi-meta 块注释（合法 JS，
+ * worker 天然忽略），无 const meta 变量。toExecutable 返回原文（含块注释）。
+ * Worker 线程 wrap（注入 globals）由 infra/worker-script-builder.ts buildWorkerScript 完成。
  */
   toExecutable(): string {
-    return this.sourceCode.replace(EXPORT_META_PATTERN, "const meta");
+    return this.sourceCode;
   }
 }

package/src/orchestration/script-lint.ts

@@ -25,6 +25,13 @@
  * 参考：domain-models.md §7（validate 语义）。
  */
 
+/** m4 W2：meta 描述字段长度上限（§5.1 注入段预算约束）。 */
+const DESC_MAX_LENGTH = 200;
+/** m4 W4：agent examples 最少条数（正反各一需 ≥2）。 */
+const EXAMPLES_MIN_COUNT = 2;
+/** m5：examples 上限（注入是每 turn 常驻成本——防数据无界膨胀）。 */
+const EXAMPLES_MAX_COUNT = 4;
+
 /** Lint 检查发现项。 */
 export interface LintFinding {
  /** error = 会导致运行时崩溃; warning = 可能的错误 */
@@ -41,6 +48,9 @@ export interface LintResult {
 }
 
 /** 必须命中其一——workflow 脚本不调用任何编排函数等于空跑。 */
+import type { AgentMeta } from "../shared/resource-meta.ts";
+import { parseResourceMeta } from "../shared/meta-parser.ts";
+
 const ENTRY_POINT_PATTERNS = [/\bagent\s*\(/, /\bparallel\s*\(/, /\bpipeline\s*\(/] as const;
 
 /**
@@ -568,6 +578,148 @@ function checkPhaseConsistency(source: string): LintFinding[] {
  * @param source 脚本源码（原始文件内容）
  * @returns LintResult（valid = 无 error 级 finding）
  */
+/**
+ * W2/W3 共享 helper：meta 描述字段长度上限 + 单句判定（workflow lintScript 与
+ * agent lintAgentMeta 共用同一规则——S-5 对称，避免 agent 长 description 常驻膨胀）。
+ *
+ * W2：>200 字符 → error。
+ * W3：括号内容剥离（（…）/（…）与 (...)）后含换行/。；/'. ' 分句 → error。
+ * 输出格式与 severity 约定与 checkMetaQuality 一致（error / line 1 / meta.<field> 前缀）。
+ */
+function checkMetaFieldQuality(field: string, value: string): LintFinding[] {
+  const findings: LintFinding[] = [];
+  // W2
+  if (value.length > DESC_MAX_LENGTH) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `meta.${field} 长度 ${value.length} 超过 ${DESC_MAX_LENGTH} 字符（§5.1 注入段预算约束）`,
+      suggestion: "精简为单句路由描述，细节移入 usage",
+    });
+  }
+  // W3：括号剥离后分句判定
+  const stripped = value
+    .replace(/（[^）]*）/g, "")
+    .replace(/\([^)]*\)/g, "")
+    .replace(/\b(?:e\.g|i\.e)\.\s/g, ""); // 缩写剔除（exec-review F8：括号外 e.g. 不误报）
+  if (/[\n。；]|\.\s/.test(stripped)) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `meta.${field} 非单句（含换行/分句标点）——§5.1 注入段要求一句话路由描述`,
+      suggestion: "精简为单句，细节移入 when/notFor/usage",
+    });
+  }
+  return findings;
+}
+
+/**
+ * W1-W3：SSOT lint（m4）——保 §5.1 注入段 description 短单句、不含已声明参数名。
+ * 仅对 parseResourceMeta 解析成功的 meta 执行（旧 const meta 格式不检查）。
+ *
+ * W1 参数名匹配（非形态匹配）：'note:'/'Example:'/'a=b' 等 prose 不误报（design-review
+ * 探针实测形态匹配误报面）；参数名集合 = meta.parameters.properties keys + patternProperties
+ * 的 word 前缀（^word\\d+$ 转义形态）。检查面 = description + when + notFor 三字段
+ * （同进 §5.1 注入段）。W2/W3 抽到 checkMetaFieldQuality（lintAgentMeta 共用）。
+ */
+function checkMetaQuality(meta: { description?: string; when?: string; notFor?: string; parameters?: Record<string, unknown> }): LintFinding[] {
+  const findings: LintFinding[] = [];
+  const description = meta.description ?? "";
+
+  // W1 参数名集合
+  const paramNames = new Set<string>();
+  if (meta.parameters && typeof meta.parameters === "object") {
+    const props = (meta.parameters as Record<string, unknown>).properties;
+    if (props !== null && typeof props === "object") {
+      for (const k of Object.keys(props as Record<string, unknown>)) paramNames.add(k);
+    }
+    const pp = (meta.parameters as Record<string, unknown>).patternProperties;
+    if (pp !== null && typeof pp === "object") {
+      for (const p of Object.keys(pp as Record<string, unknown>)) {
+        const m = p.match(/^\^([a-zA-Z]+)\\d\+\$$/);
+        if (m) paramNames.add(m[1] as string);
+      }
+    }
+  }
+
+  const fields: Array<[string, string]> = [
+    ["description", description],
+    ["when", meta.when ?? ""],
+    ["notFor", meta.notFor ?? ""],
+  ];
+  for (const [field, value] of fields) {
+    if (value.length === 0) continue;
+    // W1：已声明参数名的 ':'/'=' 形态（参数名转义防 RegExp 注入崩溃——exec-review F2；
+    // ':' 形态加 \\b 前缀防子串误报（subtask: 不命中 task——exec-review F6））
+    for (const name of paramNames) {
+      const nameEsc = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      if (new RegExp(`\\b${nameEsc}:\\s`).test(value) || new RegExp(`\\b${nameEsc}=\\S`).test(value)) {
+        findings.push({
+          severity: "error",
+          line: 1,
+          message: `meta.${field} 包含已声明参数名 '${name}'（'${name}:' / '${name}=' 形态）——参数契约请 read 脚本文件的 @pi-meta parameters 查询，description/when/notFor 只放路由信息`,
+          suggestion: `从 meta.${field} 移除 '${name}: ...' / '${name}=...'，改在 parameters/usage 中声明`,
+        });
+      }
+    }
+    findings.push(...checkMetaFieldQuality(field, value));
+  }
+  return findings;
+}
+
+/**
+ * W2/W3 + W4（m4/m5 挂 agent 加载路径）：description/when/notFor 长度与单句检查
+ * （与 workflow 同规则，S-5 对称）+ examples 正反各一。
+ * RoutingExample.positive 判别（action 是 string 非 null）；examples 缺失 → 无 finding
+ * （未迁移 agent 不报错——m5 挂载安全根基）。
+ */
+export function lintAgentMeta(meta: AgentMeta): LintFinding[] {
+  // W2/W3（S-5 对称）：agent 的 description/when/notFor 与 workflow 同规则
+  // （长度上限 + 单句判定）——formatAgentList 原样注入 systemPrompt，长描述是每 turn 常驻成本。
+  const findings: LintFinding[] = [];
+  const fields: Array<[string, string]> = [
+    ["description", meta.description],
+    ["when", meta.when ?? ""],
+    ["notFor", meta.notFor ?? ""],
+  ];
+  for (const [field, value] of fields) {
+    if (value.length === 0) continue;
+    findings.push(...checkMetaFieldQuality(field, value));
+  }
+
+  const examples = meta.examples;
+  if (examples === undefined) return findings; // 未迁移 agent（无 examples 字段）不报错
+  if (examples.length === 0) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `agent '${meta.name}' 声明了 examples 但为空——需 ≥2 条且正反各一`,
+      suggestion: "补正向样本（何时调用）+ 反向样本（何时不调用）",
+    });
+    return findings;
+  }
+  const hasPositive = examples.some((e) => e.positive === true);
+  const hasNegative = examples.some((e) => e.positive === false);
+  if (examples.length < EXAMPLES_MIN_COUNT || !hasPositive || !hasNegative) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `agent '${meta.name}' 的 examples 需 ≥2 条且正反各一（positive:true 触发路由 + positive:false 反例）`,
+      suggestion: "补正向样本（何时调用）+ 反向样本（何时不调用）",
+    });
+    return findings;
+  }
+  if (examples.length > EXAMPLES_MAX_COUNT) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `agent '${meta.name}' 的 examples ${examples.length} 条超过上限 ${EXAMPLES_MAX_COUNT}（注入段是每 turn 常驻成本）`,
+      suggestion: "精简到 2-4 条：正反各一 + 最多 2 条冗余",
+    });
+  }
+  return findings;
+}
+
 export function lintScript(source: string): LintResult {
   const lines = source.split("\n");
   const findings: LintFinding[] = [];
@@ -591,6 +743,13 @@ export function lintScript(source: string): LintResult {
  // 最终靠 worker-host → handleReturn → release → abort 的调用栈定位。
   findings.push(...checkBareAsyncIIFE(source));
 
+ // m4 W1-W3：meta 质量（description/when/notFor 短单句 + 不含已声明参数名）。
+ // 仅对 IF1 解析成功的 @pi-meta 执行——旧 const meta 格式（D1 无 adapter）不检查。
+  const meta = parseResourceMeta(source, "workflow");
+  if (meta && meta.kind === "workflow") {
+    findings.push(...checkMetaQuality(meta));
+  }
+
  // 显示性检查（warning）：agent 缺 description / meta.phases 形式 / phase 一致性。
  // 目的：让 TUI /workflows 视图避免 unnamed agent 与 (unnamed) phase 分组。
   findings.push(...checkAgentDescription(source));

package/src/orchestration/worker-host.ts

@@ -67,6 +67,11 @@ export class WorkerHostImpl implements WorkerHost {
           usedTokens: 0,
           usedCost: 0,
         },
+        // Option B symmetric single-path: model/thinkingLevel flow through
+        // workerData → $MODEL/$THINKING_LEVEL worker globals (injected by
+        // worker-script-builder) → agent() fallback. Not merged into args.
+        model: spec.model,
+        thinkingLevel: spec.thinkingLevel,
       },
     });
 

package/src/orchestration/worker-script-builder.ts

@@ -114,6 +114,12 @@ export function buildWorkerScript(userScript: string): string {
     '    remaining() { return Math.max(0, _budgetData.total - _budgetData._spentTokens); },',
     '  };',
     '',
+    '  // ── Run-level model/thinkingLevel override (Option B symmetric single-path) ──',
+    '  // Injected from workerData (set by workerHost from RunSpec.model/thinkingLevel).',
+    '  // agent() reads these as run-level defaults; per-call explicit opts still win.',
+    '  const $MODEL = (workerData.model && typeof workerData.model === "string") ? workerData.model : undefined;',
+    '  const $THINKING_LEVEL = (workerData.thinkingLevel && typeof workerData.thinkingLevel === "string") ? workerData.thinkingLevel : undefined;',
+    '',
     '  // ── WorkflowAbortedError ──',
     '  class WorkflowAbortedError extends Error {',
     '    constructor(reason) {',
@@ -188,10 +194,10 @@ export function buildWorkerScript(userScript: string): string {
     '        prompt: firstArg,',
     '        description: (secondArg && typeof secondArg === "object" && secondArg.label) || undefined,',
     '        schema: (secondArg && typeof secondArg === "object" && secondArg.schema) || undefined,',
-    '        model: (secondArg && typeof secondArg === "object" && secondArg.model) || undefined,',
+    '        model: (secondArg && typeof secondArg === "object" && secondArg.model) || $MODEL,',
     '        scene: (secondArg && typeof secondArg === "object" && secondArg.scene) || undefined,\n' +
       '        phase: (secondArg && typeof secondArg === "object" && secondArg.phase) || undefined,',
-      '        thinkingLevel: (secondArg && typeof secondArg === "object" && secondArg.thinkingLevel) || undefined,',
+      '        thinkingLevel: (secondArg && typeof secondArg === "object" && secondArg.thinkingLevel) || $THINKING_LEVEL,',
     '      };',
     '    } else if (typeof firstArg === "object" && firstArg !== null) {',
     '      if (firstArg.prompt) {',
@@ -204,7 +210,7 @@ export function buildWorkerScript(userScript: string): string {
     '          description: firstArg.label || firstArg.description,',
     '          agent: firstArg.agent,',
     '          schema: firstArg.schema,',
-    '          model: firstArg.model,',
+    '          model: firstArg.model || $MODEL,',
     '          scene: firstArg.scene,',
     '          skill: firstArg.skill,',
     '          timeoutMs: firstArg.timeoutMs,',
@@ -212,7 +218,7 @@ export function buildWorkerScript(userScript: string): string {
     '          fork: firstArg.fork,',
     '          worktree: firstArg.worktree,',
     '          returnMeta: firstArg.returnMeta,',
-    '          thinkingLevel: firstArg.thinkingLevel,',
+    '          thinkingLevel: firstArg.thinkingLevel || $THINKING_LEVEL,',
     '        };',
     '      } else {',
     '        opts = firstArg;',
@@ -221,6 +227,11 @@ export function buildWorkerScript(userScript: string): string {
     '      throw new Error("agent() requires a prompt string or options object as first argument");',
     '    }',
     '',
+    '    // Run-level fallback for object branches (opts = firstArg direct assign).',
+    '    // Priority: agent() explicit > $MODEL global (set from workerData.model).',
+    '    if (!opts.model && $MODEL) opts.model = $MODEL;',
+    '    if (!opts.thinkingLevel && $THINKING_LEVEL) opts.thinkingLevel = $THINKING_LEVEL;',
+    '',
     '    // Validate known agent() fields to catch API misuse early',
     '    const _knownFields = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
     '    const _unknownFields = Object.keys(opts).filter((k) => !_knownFields.has(k));',

package/src/orchestration/workflow-script-registry-impl.ts

@@ -16,17 +16,14 @@
  * - get(name) 精确匹配；fuzzy 匹配由 Interface 层 tool 负责。
  */
 
-import { readFileSync } from "node:fs";
-
-import {
-  type WorkflowMeta,
-  WorkflowScript,
-  type WorkflowSource,
-} from "./models/workflow-script.ts";
+import { WorkflowScript } from "./models/workflow-script.ts";
+import { getCachedFileContent } from "../shared/resource-discovery.ts";
 import type { WorkflowScriptRegistry } from "./models/workflow-script-registry.ts";
 import {
+  type CachedWorkflowMeta,
   discoverWorkflows,
   getWorkflow,
+  getWorkflowByPath,
   invalidateCache,
   loadWorkflows,
   type WorkflowScanConfig,
@@ -73,6 +70,15 @@ export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
     return meta ? this.toScript(meta) : undefined;
   }
 
+ /**
+  * 按绝对路径加载单个脚本（S2 路径统一）。任意路径（不限扫描源）。
+  * 供 workflow tool 的 run/info（name 参数 = workflowRef）。
+  */
+  async getPath(ref: string): Promise<WorkflowScript | undefined> {
+    const meta = await getWorkflowByPath(ref);
+    return meta ? this.toScript(meta) : undefined;
+  }
+
  /** 失效缓存——下次 loadAll/get 重新扫描文件系统。 */
   invalidate(): void {
     invalidateCache();
@@ -81,34 +87,29 @@ export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
  /**
  * 把 CachedWorkflowMeta 转换为 WorkflowScript 实体。
  *
- * 字段映射：
- * - name/path/source 直接传
- * - meta 拆为 WorkflowMeta（name/description/phases）
- * - sourceCode 在此 readFile 填充（FR-2：registry 是唯一读文件处，扫描+缓存+去重；
- * 60s TTL 缓存避免重复读）。caller（launcher.runAndWait / tool-workflow.actionRun）
- * 直接用 script.validate / script.toExecutable，不再各自 readFile。
- * - available：meta 提取失败（config-loader 标 available=false）或文件不可读时为 false
+ * m2：整对象透传——m 已是 WorkflowMeta（CachedWorkflowMeta extends WorkflowMeta），
+ * 直接传 meta: m，不再 {name,description,phases} 重建。消灭第 3 处重映射，
+ * parameters/usage/when/notFor 一路流到 script.meta。
+ *
+ * sourceCode 在此 readFile 填充（FR-2：registry 是唯一读文件处）。
+ * available：meta 提取失败或文件不可读时为 false。
  */
-  private toScript(m: {
-    name: string;
-    description: string;
-    phases: (string | { title: string; detail?: string })[];
-    path: string;
-    available: boolean;
-    source: WorkflowSource;
-  }): WorkflowScript {
-    const meta: WorkflowMeta = {
-      name: m.name,
-      description: m.description,
-      phases: m.phases,
-    };
+  private toScript(m: CachedWorkflowMeta): WorkflowScript {
  // FR-2: registry 是唯一读文件处。readFileSync 填 sourceCode —— 这样 launcher/tool
  // 直接调 toExecutable/validate 即可，无需各自 readFile（避免重复读，60s TTL 缓存生效）。
     let sourceCode = "";
     let available = m.available;
     if (available) {
       try {
-        sourceCode = readFileSync(m.path, "utf-8");
+        const cachedContent = getCachedFileContent(m.path); // m5：统一 mtime 缓存层
+        if (cachedContent === null) {
+          // ENOENT/不可读竞态 → available=false（exec-review major-3：?? '' 会静默
+          // 返回空源码 workflow——恢复旧 readFileSync throw → catch → available=false 语义）
+          sourceCode = "";
+          available = false;
+        } else {
+          sourceCode = cachedContent;
+        }
       } catch {
  // 文件不可读（race condition 删除、权限等）——标 available=false，
  // 与 meta 提取失败的现有语义一致（loader "never throws"）。
@@ -121,7 +122,11 @@ export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
       source: m.source,
       path: m.path,
       sourceCode,
-      meta,
+      // meta: m 整对象透传（m2 决策）：故意不做显式投影——投影会重引入
+      // {name,description,phases} 解构重映射反模式（m2 消灭的丢字段 bug）。
+      // CachedWorkflowMeta 多带的 path/available/source 是良性泄漏（无消费者
+      // 序列化 script.meta）；若未来有消费者，改为组合式 { meta, path, ... } 而非投影。
+      meta: m,
       available,
     });
   }