minimal-agent 0.13.0 → 0.14.0

package/plugins/workflow-runner/src/discovery.js

@@ -0,0 +1,160 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/discovery.ts —— 工作流目录发现
+ * ------------------------------------------------------------
+ *  一个工作流 = 一个目录：`workflows/<name>/workflow.mjs`。目录名即工作流名。
+ *
+ *  三源搜索沿用框架既有契约 `getResourceSearchPaths('workflows', ...)`：
+ *    cwd/workflows/ → exe 同级 workflows/（绿色版）→ packageRoot/workflows/
+ *  先扫到的同名条目胜出，用户可以在自己项目里覆盖包内自带的工作流。
+ *
+ *  ------------------------------------------------------------
+ *  与 legacy loader 的一处**有意不同**：坏脚本不再只 `console.warn` 后消失。
+ *
+ *  legacy 的行为是「一个坏 yaml 不拖累其它工作流」——这条对，但它把坏文件
+ *  静默丢出列表，用户看到的是「我的工作流不见了」，而不是「我的工作流写错了」。
+ *  这里改成继续扫描 + **把失败原因带出去**（`DiscoveryResult.failures`），由
+ *  /workflows 如实报出。静默降级是本项目反复吃过亏的失败模式（漏注册插件退化成
+ *  markdown、漏拷资产目录报「未找到说明书」），不在新引擎里重演。
+ * ============================================================
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { getResourceSearchPaths } from '../../../src/plugin-sdk.js';
+import { validateScript } from './scriptGuard.mjs';
+/** 编排脚本的固定文件名。目录里没有它就不是工作流目录。 */
+export const SCRIPT_FILENAME = 'workflow.mjs';
+/**
+ * 把 scriptGuard 求值出的 meta（形状是 unknown 的宽松对象）收紧成 WorkflowMeta。
+ * 调用前 validateScript 已保证 description 是非空字符串、inputs/artifacts 是数组。
+ */
+function narrowMeta(raw) {
+    const meta = {
+        apiVersion: 2,
+        description: String(raw.description),
+    };
+    if (Array.isArray(raw.dependencies))
+        meta.dependencies = raw.dependencies;
+    if (Array.isArray(raw.packages))
+        meta.packages = raw.packages;
+    if (Array.isArray(raw.inputs))
+        meta.inputs = raw.inputs;
+    if (Array.isArray(raw.artifacts)) {
+        meta.artifacts = raw.artifacts.map((a) => String(a));
+    }
+    if (typeof raw.resumeBackoff === 'number') {
+        meta.resumeBackoff = raw.resumeBackoff;
+    }
+    if (typeof raw.managedRuntime === 'string' && raw.managedRuntime.trim()) {
+        meta.managedRuntime = raw.managedRuntime.trim();
+    }
+    return meta;
+}
+/**
+ * 读并校验单个工作流目录。
+ *
+ * @returns 成功返回 WorkflowScript；失败返回 errors（调用方决定怎么报）
+ */
+export async function loadWorkflowDir(dir) {
+    const scriptPath = join(dir, SCRIPT_FILENAME);
+    let source;
+    try {
+        source = await readFile(scriptPath, 'utf8');
+    }
+    catch (e) {
+        return {
+            ok: false,
+            // ⚠️ 这里必须给**类型化**的原因，调用方据此区分「这不是工作流目录」与
+            // 「这是个写错的工作流」。曾经是让调用方去 `errors[0].includes('读取')`
+            // 匹配中文文案 —— 那意味着有人给错误信息换个措辞，`assets/`、模板目录
+            // 这些普通目录就会全部变成「坏工作流」刷进 /workflows 列表。
+            reason: 'no-script',
+            errors: [
+                `读取 ${scriptPath} 失败：${e instanceof Error ? e.message : String(e)}`,
+            ],
+        };
+    }
+    const name = basename(dir);
+    const verdict = validateScript(source, {
+        filename: join('workflows', name, SCRIPT_FILENAME),
+    });
+    if (!verdict.ok || !verdict.meta || verdict.bodyOffset === undefined) {
+        return { ok: false, reason: 'invalid-script', errors: verdict.errors };
+    }
+    return {
+        ok: true,
+        workflow: {
+            name,
+            dir,
+            scriptPath,
+            source,
+            meta: narrowMeta(verdict.meta),
+            bodyOffset: verdict.bodyOffset,
+        },
+    };
+}
+/**
+ * 按给定的搜索根扫描（前面的根优先）。
+ *
+ * 独立导出是为了让「cwd 覆盖 packageRoot」这类多根语义可被单测直接驱动 ——
+ * 项目惯例是用依赖注入而不是 `mock.module`（后者会全局泄漏、污染同批其它测试）。
+ *
+ * 永不抛：目录不存在 / 读不动 / 脚本写错，都降级成「少一个工作流 + 一条 failure」。
+ */
+export async function discoverWorkflowsIn(roots) {
+    const workflows = [];
+    const failures = [];
+    const seen = new Set();
+    for (const root of roots) {
+        // ⚠️ 显式写 `Dirent[]`，别用 `Awaited<ReturnType<typeof readdir>>` ——
+        // readdir 是重载函数，ReturnType 只会挑中其中一个（Buffer 那条），于是这里
+        // 拿到 `Dirent<NonSharedBuffer>[]`，下面每个 `entry.name` 都变成 Buffer，
+        // 连报 6 个类型错。运行时完全正常，所以只有 `tsc --build` 才看得见。
+        let entries;
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch {
+            continue; // 目录不存在 → 静默跳过（与既有资源目录契约一致）
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue; // 工作流恒为目录，散落的文件一律不认
+            const name = entry.name;
+            if (seen.has(name))
+                continue; // 先扫到的胜出（cwd 覆盖 packageRoot）
+            const dir = join(root, name);
+            const loaded = await loadWorkflowDir(dir);
+            if (loaded.ok) {
+                seen.add(name);
+                workflows.push(loaded.workflow);
+            }
+            else if (loaded.reason === 'invalid-script') {
+                // 占位：别让 packageRoot 的同名工作流顶替一个写错的 cwd 版本 ——
+                // 否则现象是「我改坏了自己项目里的工作流，跑起来却是包内那个旧版本」。
+                seen.add(name);
+                failures.push({
+                    name,
+                    scriptPath: join(dir, SCRIPT_FILENAME),
+                    errors: loaded.errors,
+                });
+            }
+            // reason === 'no-script'：普通目录，静默跳过（不占名、不报错）
+        }
+    }
+    workflows.sort((a, b) => a.name.localeCompare(b.name));
+    failures.sort((a, b) => a.name.localeCompare(b.name));
+    return { workflows, failures };
+}
+/**
+ * 扫描三源目录（cwd → 绿色版 exe 同级 → packageRoot），返回全部代码形态工作流
+ * 与全部加载失败。
+ */
+export async function discoverWorkflows(workingDir) {
+    return discoverWorkflowsIn(getResourceSearchPaths('workflows', import.meta.url, workingDir));
+}
+/** 按名字找一个代码形态工作流；不存在返回 null（可能是 legacy yaml，由调用方决定）。 */
+export async function findWorkflowByName(name, workingDir) {
+    const { workflows } = await discoverWorkflows(workingDir);
+    return workflows.find((w) => w.name === name) ?? null;
+}

package/plugins/workflow-runner/src/discovery.ts

@@ -0,0 +1,194 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/discovery.ts —— 工作流目录发现
+ * ------------------------------------------------------------
+ *  一个工作流 = 一个目录：`workflows/<name>/workflow.mjs`。目录名即工作流名。
+ *
+ *  三源搜索沿用框架既有契约 `getResourceSearchPaths('workflows', ...)`：
+ *    cwd/workflows/ → exe 同级 workflows/（绿色版）→ packageRoot/workflows/
+ *  先扫到的同名条目胜出，用户可以在自己项目里覆盖包内自带的工作流。
+ *
+ *  ------------------------------------------------------------
+ *  与 legacy loader 的一处**有意不同**：坏脚本不再只 `console.warn` 后消失。
+ *
+ *  legacy 的行为是「一个坏 yaml 不拖累其它工作流」——这条对，但它把坏文件
+ *  静默丢出列表，用户看到的是「我的工作流不见了」，而不是「我的工作流写错了」。
+ *  这里改成继续扫描 + **把失败原因带出去**（`DiscoveryResult.failures`），由
+ *  /workflows 如实报出。静默降级是本项目反复吃过亏的失败模式（漏注册插件退化成
+ *  markdown、漏拷资产目录报「未找到说明书」），不在新引擎里重演。
+ * ============================================================
+ */
+
+import type { Dirent } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import { getResourceSearchPaths } from '../../../src/plugin-sdk.js';
+import { validateScript } from './scriptGuard.mjs';
+import type {
+  DiscoveryResult,
+  InputDef,
+  WorkflowMeta,
+  WorkflowScript,
+} from './types.js';
+
+/** 编排脚本的固定文件名。目录里没有它就不是工作流目录。 */
+export const SCRIPT_FILENAME = 'workflow.mjs';
+
+/**
+ * 加载失败的**类型化**原因。两者的处理方式完全不同：
+ *  - `no-script`      这压根不是工作流目录（assets/、模板目录…）→ 静默跳过
+ *  - `invalid-script` 这是个写错了的工作流 → 必须报给用户
+ */
+export type LoadFailureReason = 'no-script' | 'invalid-script';
+
+export type LoadWorkflowResult =
+  | { ok: true; workflow: WorkflowScript }
+  | { ok: false; reason: LoadFailureReason; errors: string[] };
+
+/**
+ * 把 scriptGuard 求值出的 meta（形状是 unknown 的宽松对象）收紧成 WorkflowMeta。
+ * 调用前 validateScript 已保证 description 是非空字符串、inputs/artifacts 是数组。
+ */
+function narrowMeta(raw: Record<string, unknown>): WorkflowMeta {
+  const meta: WorkflowMeta = {
+    apiVersion: 2,
+    description: String(raw.description),
+  };
+  if (Array.isArray(raw.dependencies))
+    meta.dependencies = raw.dependencies as string[];
+  if (Array.isArray(raw.packages)) meta.packages = raw.packages as string[];
+  if (Array.isArray(raw.inputs)) meta.inputs = raw.inputs as InputDef[];
+  if (Array.isArray(raw.artifacts)) {
+    meta.artifacts = raw.artifacts.map((a) => String(a));
+  }
+  if (typeof raw.resumeBackoff === 'number') {
+    meta.resumeBackoff = raw.resumeBackoff;
+  }
+  if (typeof raw.managedRuntime === 'string' && raw.managedRuntime.trim()) {
+    meta.managedRuntime = raw.managedRuntime.trim();
+  }
+  return meta;
+}
+
+/**
+ * 读并校验单个工作流目录。
+ *
+ * @returns 成功返回 WorkflowScript；失败返回 errors（调用方决定怎么报）
+ */
+export async function loadWorkflowDir(
+  dir: string,
+): Promise<LoadWorkflowResult> {
+  const scriptPath = join(dir, SCRIPT_FILENAME);
+  let source: string;
+  try {
+    source = await readFile(scriptPath, 'utf8');
+  } catch (e) {
+    return {
+      ok: false,
+      // ⚠️ 这里必须给**类型化**的原因，调用方据此区分「这不是工作流目录」与
+      // 「这是个写错的工作流」。曾经是让调用方去 `errors[0].includes('读取')`
+      // 匹配中文文案 —— 那意味着有人给错误信息换个措辞，`assets/`、模板目录
+      // 这些普通目录就会全部变成「坏工作流」刷进 /workflows 列表。
+      reason: 'no-script',
+      errors: [
+        `读取 ${scriptPath} 失败：${e instanceof Error ? e.message : String(e)}`,
+      ],
+    };
+  }
+
+  const name = basename(dir);
+  const verdict = validateScript(source, {
+    filename: join('workflows', name, SCRIPT_FILENAME),
+  });
+  if (!verdict.ok || !verdict.meta || verdict.bodyOffset === undefined) {
+    return { ok: false, reason: 'invalid-script', errors: verdict.errors };
+  }
+
+  return {
+    ok: true,
+    workflow: {
+      name,
+      dir,
+      scriptPath,
+      source,
+      meta: narrowMeta(verdict.meta as Record<string, unknown>),
+      bodyOffset: verdict.bodyOffset,
+    },
+  };
+}
+
+/**
+ * 按给定的搜索根扫描（前面的根优先）。
+ *
+ * 独立导出是为了让「cwd 覆盖 packageRoot」这类多根语义可被单测直接驱动 ——
+ * 项目惯例是用依赖注入而不是 `mock.module`（后者会全局泄漏、污染同批其它测试）。
+ *
+ * 永不抛：目录不存在 / 读不动 / 脚本写错，都降级成「少一个工作流 + 一条 failure」。
+ */
+export async function discoverWorkflowsIn(
+  roots: string[],
+): Promise<DiscoveryResult> {
+  const workflows: WorkflowScript[] = [];
+  const failures: DiscoveryResult['failures'] = [];
+  const seen = new Set<string>();
+
+  for (const root of roots) {
+    // ⚠️ 显式写 `Dirent[]`，别用 `Awaited<ReturnType<typeof readdir>>` ——
+    // readdir 是重载函数，ReturnType 只会挑中其中一个（Buffer 那条），于是这里
+    // 拿到 `Dirent<NonSharedBuffer>[]`，下面每个 `entry.name` 都变成 Buffer，
+    // 连报 6 个类型错。运行时完全正常，所以只有 `tsc --build` 才看得见。
+    let entries: Dirent[];
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      continue; // 目录不存在 → 静默跳过（与既有资源目录契约一致）
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue; // 工作流恒为目录，散落的文件一律不认
+      const name = entry.name;
+      if (seen.has(name)) continue; // 先扫到的胜出（cwd 覆盖 packageRoot）
+      const dir = join(root, name);
+      const loaded = await loadWorkflowDir(dir);
+      if (loaded.ok) {
+        seen.add(name);
+        workflows.push(loaded.workflow);
+      } else if (loaded.reason === 'invalid-script') {
+        // 占位：别让 packageRoot 的同名工作流顶替一个写错的 cwd 版本 ——
+        // 否则现象是「我改坏了自己项目里的工作流，跑起来却是包内那个旧版本」。
+        seen.add(name);
+        failures.push({
+          name,
+          scriptPath: join(dir, SCRIPT_FILENAME),
+          errors: loaded.errors,
+        });
+      }
+      // reason === 'no-script'：普通目录，静默跳过（不占名、不报错）
+    }
+  }
+
+  workflows.sort((a, b) => a.name.localeCompare(b.name));
+  failures.sort((a, b) => a.name.localeCompare(b.name));
+  return { workflows, failures };
+}
+
+/**
+ * 扫描三源目录（cwd → 绿色版 exe 同级 → packageRoot），返回全部代码形态工作流
+ * 与全部加载失败。
+ */
+export async function discoverWorkflows(
+  workingDir?: string,
+): Promise<DiscoveryResult> {
+  return discoverWorkflowsIn(
+    getResourceSearchPaths('workflows', import.meta.url, workingDir),
+  );
+}
+
+/** 按名字找一个代码形态工作流；不存在返回 null（可能是 legacy yaml，由调用方决定）。 */
+export async function findWorkflowByName(
+  name: string,
+  workingDir?: string,
+): Promise<WorkflowScript | null> {
+  const { workflows } = await discoverWorkflows(workingDir);
+  return workflows.find((w) => w.name === name) ?? null;
+}

package/plugins/workflow-runner/src/goalAnchor.js

@@ -0,0 +1,53 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/goalAnchor.ts —— 目标锚定与补充要求
+ * ------------------------------------------------------------
+ *  自 legacy `agentCommon.ts` 移植这一小块（其余部分与「怎么消费 runQuery」
+ *  绑得紧，随 API 面一起走）。
+ *
+ *  解决的是一个真实失效模式：多步长跑（尤其自动压缩发生过之后），模型会逐渐
+ *  「忘记」用户的原始目标而偏航。锚由引擎在每次 agent/llm/skill 调用前自动
+ *  前置注入，**对脚本作者透明** —— 作者不需要在每个 prompt 里手写目标。
+ *
+ *  补充要求（`ask()` 里用户的自由输入、`addGoalSupplement()` 的产出、仲裁
+ *  延续时的新指令）与原始目标**同等贯穿**，不只活在被修订的那个文件里。
+ * ============================================================
+ */
+import { extractGoal } from './taskIdentity.js';
+/**
+ * 从 inputs 里构造锚定串。
+ *
+ * 取值顺序：名为 `goal` 的输入 → 第一个 required 的字符串输入 → 第一个长度 >2
+ * 的字符串输入。都没有则返回空串（= 无锚，调用方跳过注入，不硬凑）。
+ */
+export function buildGoalAnchor(inputs, defs) {
+    // 委托 extractGoal —— 任务身份（computeTaskId）用的是同一个函数。
+    // 两处各写一套取值规则，就会出现「按 A 算的 taskId」配「按 B 注入的目标」。
+    const goal = extractGoal(inputs, defs).trim();
+    // 取不到真实文本时 extractGoal 会回退成整体 JSON —— 那种东西不该当目标注入给
+    // 模型（它会朝着一坨 JSON 努力），此时视为无锚。
+    if (!goal || goal.startsWith('{'))
+        return '';
+    return `> 🎯 本次任务的原始目标：${goal}`;
+}
+/**
+ * 锚 + 补充要求的最终渲染。返回空串 = 无锚，调用方跳过注入。
+ *
+ * ⚠️ 补充要求即使在**没有**原始锚的情况下也要注入 —— 那种场景下它们就是仅有的
+ * 约束，漏掉等于用户白说。所以没有 base 时额外补一句说明它们的效力等级。
+ */
+export function effectiveGoalAnchor(ctx) {
+    const base = ctx.goalAnchor ?? '';
+    const supps = (ctx.goalSupplements ?? []).filter((s) => s.trim());
+    if (supps.length === 0)
+        return base;
+    const lines = supps.map((s) => `> 📌 用户补充要求：${s}`).join('\n');
+    return base
+        ? `${base}\n${lines}`
+        : `${lines}\n> ⚠️ 以上补充要求与原始目标同等约束所有操作。`;
+}
+/** 把锚前置到一段 prompt 前面。无锚时原样返回（不留多余空行）。 */
+export function withGoalAnchor(ctx, prompt) {
+    const anchor = effectiveGoalAnchor(ctx);
+    return anchor ? `${anchor}\n\n${prompt}` : prompt;
+}

package/plugins/workflow-runner/src/goalAnchor.ts

@@ -0,0 +1,59 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/goalAnchor.ts —— 目标锚定与补充要求
+ * ------------------------------------------------------------
+ *  自 legacy `agentCommon.ts` 移植这一小块（其余部分与「怎么消费 runQuery」
+ *  绑得紧，随 API 面一起走）。
+ *
+ *  解决的是一个真实失效模式：多步长跑（尤其自动压缩发生过之后），模型会逐渐
+ *  「忘记」用户的原始目标而偏航。锚由引擎在每次 agent/llm/skill 调用前自动
+ *  前置注入，**对脚本作者透明** —— 作者不需要在每个 prompt 里手写目标。
+ *
+ *  补充要求（`ask()` 里用户的自由输入、`addGoalSupplement()` 的产出、仲裁
+ *  延续时的新指令）与原始目标**同等贯穿**，不只活在被修订的那个文件里。
+ * ============================================================
+ */
+
+import { extractGoal } from './taskIdentity.js';
+import type { InputDef, RunContext } from './types.js';
+
+/**
+ * 从 inputs 里构造锚定串。
+ *
+ * 取值顺序：名为 `goal` 的输入 → 第一个 required 的字符串输入 → 第一个长度 >2
+ * 的字符串输入。都没有则返回空串（= 无锚，调用方跳过注入，不硬凑）。
+ */
+export function buildGoalAnchor(
+  inputs: Record<string, unknown>,
+  defs?: InputDef[],
+): string {
+  // 委托 extractGoal —— 任务身份（computeTaskId）用的是同一个函数。
+  // 两处各写一套取值规则，就会出现「按 A 算的 taskId」配「按 B 注入的目标」。
+  const goal = extractGoal(inputs, defs).trim();
+  // 取不到真实文本时 extractGoal 会回退成整体 JSON —— 那种东西不该当目标注入给
+  // 模型（它会朝着一坨 JSON 努力），此时视为无锚。
+  if (!goal || goal.startsWith('{')) return '';
+  return `> 🎯 本次任务的原始目标：${goal}`;
+}
+
+/**
+ * 锚 + 补充要求的最终渲染。返回空串 = 无锚，调用方跳过注入。
+ *
+ * ⚠️ 补充要求即使在**没有**原始锚的情况下也要注入 —— 那种场景下它们就是仅有的
+ * 约束，漏掉等于用户白说。所以没有 base 时额外补一句说明它们的效力等级。
+ */
+export function effectiveGoalAnchor(ctx: RunContext): string {
+  const base = ctx.goalAnchor ?? '';
+  const supps = (ctx.goalSupplements ?? []).filter((s) => s.trim());
+  if (supps.length === 0) return base;
+  const lines = supps.map((s) => `> 📌 用户补充要求：${s}`).join('\n');
+  return base
+    ? `${base}\n${lines}`
+    : `${lines}\n> ⚠️ 以上补充要求与原始目标同等约束所有操作。`;
+}
+
+/** 把锚前置到一段 prompt 前面。无锚时原样返回（不留多余空行）。 */
+export function withGoalAnchor(ctx: RunContext, prompt: string): string {
+  const anchor = effectiveGoalAnchor(ctx);
+  return anchor ? `${anchor}\n\n${prompt}` : prompt;
+}