minimal-agent 0.13.0 → 0.14.0

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

@@ -0,0 +1,162 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/jsonSchema.ts —— JSON Schema 子集校验
+ * ------------------------------------------------------------
+ *  为什么手写而不是引 ajv：
+ *   ① 工作流的结构化输出契约采用可序列化的 JSON Schema 子集，便于参与 journal
+ *      指纹并跨 provider 使用。
+ *   ② 校验结果要**回喂给模型做修复**，所以错误消息比规范覆盖度重要得多 ——
+ *      「`branches[2].score` 应为 number，实际是 string」比一句
+ *      `must be number` 有用，而通用库的默认文案偏向后者。
+ *   ③ 项目一贯取向：能用基本类型说清就不引第三方（见 CLAUDE.md 设计原则）。
+ *
+ *  支持的关键字：type（含数组联合）/ properties / required / items /
+ *  enum / additionalProperties:false / minItems / maxItems / minimum / maximum /
+ *  nullable。**不支持**的关键字一律**忽略**（宽松），不报错 —— 校验器的职责是
+ *  挡住畸形输出，不是当规范警察；误伤一个合法产出的代价比放过一个边角约束大。
+ * ============================================================
+ */
+
+export interface JsonSchema {
+  type?: string | string[];
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  enum?: unknown[];
+  additionalProperties?: boolean | JsonSchema;
+  minItems?: number;
+  maxItems?: number;
+  minimum?: number;
+  maximum?: number;
+  nullable?: boolean;
+  [k: string]: unknown;
+}
+
+/** 校验失败的具体位置与原因（要拿去喂模型，所以必须是人话 + 路径）。 */
+export interface SchemaViolation {
+  path: string;
+  message: string;
+}
+
+function typeOf(v: unknown): string {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  if (Number.isInteger(v)) return 'integer';
+  return typeof v;
+}
+
+/** `integer` 也满足 `number`；其余按 typeof 对齐。 */
+function typeMatches(want: string, v: unknown): boolean {
+  const actual = typeOf(v);
+  if (want === actual) return true;
+  if (want === 'number') return actual === 'integer' || actual === 'number';
+  if (want === 'integer') return actual === 'integer';
+  return false;
+}
+
+function describe(v: unknown): string {
+  const t = typeOf(v);
+  if (t === 'string') return `string(${JSON.stringify(String(v)).slice(0, 40)})`;
+  if (t === 'array') return `array(长度 ${(v as unknown[]).length})`;
+  if (t === 'object') return `object(键 ${Object.keys(v as object).join('/')})`;
+  return `${t}(${String(v)})`;
+}
+
+function walk(
+  value: unknown,
+  schema: JsonSchema,
+  path: string,
+  out: SchemaViolation[],
+): void {
+  if (!schema || typeof schema !== 'object') return;
+
+  if (value === null && schema.nullable === true) return;
+
+  if (schema.enum && Array.isArray(schema.enum)) {
+    if (!schema.enum.some((e) => e === value)) {
+      out.push({
+        path,
+        message: `应为 [${schema.enum.map((e) => JSON.stringify(e)).join(', ')}] 之一，实际是 ${describe(value)}`,
+      });
+      return;
+    }
+  }
+
+  if (schema.type !== undefined) {
+    const wants = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!wants.some((w) => typeMatches(w, value))) {
+      out.push({
+        path,
+        message: `应为 ${wants.join(' 或 ')}，实际是 ${describe(value)}`,
+      });
+      return; // 类型都不对，再查下去只会刷屏
+    }
+  }
+
+  const t = typeOf(value);
+
+  if (t === 'object') {
+    const obj = value as Record<string, unknown>;
+    for (const key of schema.required ?? []) {
+      if (!(key in obj)) {
+        out.push({ path: path ? `${path}.${key}` : key, message: '缺少必填字段' });
+      }
+    }
+    if (schema.properties) {
+      for (const [key, sub] of Object.entries(schema.properties)) {
+        if (key in obj) walk(obj[key], sub, path ? `${path}.${key}` : key, out);
+      }
+      if (schema.additionalProperties === false) {
+        for (const key of Object.keys(obj)) {
+          if (!(key in schema.properties)) {
+            out.push({
+              path: path ? `${path}.${key}` : key,
+              message: '不允许的额外字段',
+            });
+          }
+        }
+      }
+    }
+  }
+
+  if (t === 'array') {
+    const arr = value as unknown[];
+    if (typeof schema.minItems === 'number' && arr.length < schema.minItems) {
+      out.push({ path, message: `至少要 ${schema.minItems} 项，实际 ${arr.length} 项` });
+    }
+    if (typeof schema.maxItems === 'number' && arr.length > schema.maxItems) {
+      out.push({ path, message: `最多 ${schema.maxItems} 项，实际 ${arr.length} 项` });
+    }
+    if (schema.items) {
+      arr.forEach((el, i) => walk(el, schema.items!, `${path}[${i}]`, out));
+    }
+  }
+
+  if (t === 'number' || t === 'integer') {
+    const n = value as number;
+    if (typeof schema.minimum === 'number' && n < schema.minimum) {
+      out.push({ path, message: `不得小于 ${schema.minimum}，实际 ${n}` });
+    }
+    if (typeof schema.maximum === 'number' && n > schema.maximum) {
+      out.push({ path, message: `不得大于 ${schema.maximum}，实际 ${n}` });
+    }
+  }
+}
+
+/** 校验一个值。返回空数组 = 通过。 */
+export function validateAgainstSchema(
+  value: unknown,
+  schema: JsonSchema,
+): SchemaViolation[] {
+  const out: SchemaViolation[] = [];
+  walk(value, schema, '', out);
+  return out;
+}
+
+/** 把违规列表渲染成给**模型**看的修复指令（不是给人看的报错）。 */
+export function renderViolations(violations: SchemaViolation[]): string {
+  return violations
+    .slice(0, 20)
+    .map((v) => `  · ${v.path || '(根)'}：${v.message}`)
+    .join('\n');
+}

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

@@ -0,0 +1,64 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/moduleResolution.ts —— ESM 依赖图解析的唯一实现
+ * ------------------------------------------------------------
+ *  `workflowFingerprint.ts`（指纹计算）与 `sandbox.ts`（实际执行）此前各自独立
+ *  实现了同一组"扫 import/解析相对模块/取裸包名"逻辑，且已经漂移出行为分歧
+ *  （符号链接策略、`.json` 候选扩展名）。指纹计算总是先于执行
+ *  （见 `workflowDependencies.ts::resolveWorkflowBundle`），所以漂移目前只表现
+ *  成"先炸在指纹这一步"而不是安全漏洞，但仍是两份本该一致的判断各自演化。
+ *  这里统一成一份，两处都改成从这里导入。
+ *
+ *  `scriptGuard.mjs` 不从这里导入——它必须保持零依赖纯 `.mjs`（同时被 TS 侧
+ *  `import` 和 `skills/workflow-creator/scripts/validate.mjs` 裸 `node` spawn），
+ *  多一个必须原样发布的 `.mjs` 文件会重演 CLAUDE.md 里
+ *  "package.json::files 是逐后缀白名单"那类漏发布事故的风险面。它自己那份小小的
+ *  `STATIC_IMPORT`/`packageName` 保留原样，人工与本文件保持同步。
+ * ============================================================
+ */
+import { lstat } from 'node:fs/promises';
+import { dirname, extname, join, resolve } from 'node:path';
+/**
+ * 匹配静态 `import`/`export ... from '...'` 的说明符。三个捕获组
+ * （前缀/说明符/后缀）让 `sandbox.ts` 能就地 `.replace()` 改写裸包名为 file URL；
+ * `moduleImports()` 只取第二组即可。
+ */
+export const STATIC_IMPORT = /((?:^|[;\n])\s*(?:import|export)\s+(?:[^'";]*?\s+from\s+)?['"])([^'"]+)(['"])/gm;
+/** 从源码里抽出全部静态 import/export 说明符。 */
+export function moduleImports(source) {
+    return [...source.matchAll(STATIC_IMPORT)].map((match) => match[2]);
+}
+/** 裸导入说明符 → 包名（`@scope/pkg/sub` → `@scope/pkg`，`pkg/sub` → `pkg`）。 */
+export function packageName(specifier) {
+    return specifier.startsWith('@')
+        ? specifier.split('/').slice(0, 2).join('/')
+        : specifier.split('/')[0];
+}
+/**
+ * 把一个相对 import 说明符解析成真实文件路径。
+ *
+ * **拒绝符号链接**（用 `lstat` 而不是 `stat`）——采纳 `workflowFingerprint.ts`
+ * 对随包资源文件本来就有的安全立场；`sandbox.ts` 此前用 `stat`（跟随符号链接）
+ * 是漂移，不是有意选择，收紧它是严格向下兼容。
+ *
+ * **候选扩展名不含 `.json`**——不带扩展名的相对导入解析到 `.json` 在 Node 原生
+ * ESM 下本来就不合法（没有 import assertion 语法写不出这种导入），全部 15 个
+ * 真实工作流也确认没有依赖这个候选项，去掉是安全的。显式写 `./x.json` 走
+ * `sandbox.ts::copyModule` 里单独的 `extname === '.json'` 分支，与这里正交。
+ */
+export async function resolveRelativeModule(from, specifier) {
+    const base = resolve(dirname(from), specifier);
+    const candidates = extname(base)
+        ? [base]
+        : [base, `${base}.mjs`, `${base}.js`, join(base, 'index.mjs'), join(base, 'index.js')];
+    for (const candidate of candidates) {
+        try {
+            if ((await lstat(candidate)).isFile())
+                return candidate;
+        }
+        catch {
+            // 试下一个候选
+        }
+    }
+    throw new Error(`无法解析工作流相对模块：${specifier}（来自 ${from}）`);
+}

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

@@ -0,0 +1,71 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/moduleResolution.ts —— ESM 依赖图解析的唯一实现
+ * ------------------------------------------------------------
+ *  `workflowFingerprint.ts`（指纹计算）与 `sandbox.ts`（实际执行）此前各自独立
+ *  实现了同一组"扫 import/解析相对模块/取裸包名"逻辑，且已经漂移出行为分歧
+ *  （符号链接策略、`.json` 候选扩展名）。指纹计算总是先于执行
+ *  （见 `workflowDependencies.ts::resolveWorkflowBundle`），所以漂移目前只表现
+ *  成"先炸在指纹这一步"而不是安全漏洞，但仍是两份本该一致的判断各自演化。
+ *  这里统一成一份，两处都改成从这里导入。
+ *
+ *  `scriptGuard.mjs` 不从这里导入——它必须保持零依赖纯 `.mjs`（同时被 TS 侧
+ *  `import` 和 `skills/workflow-creator/scripts/validate.mjs` 裸 `node` spawn），
+ *  多一个必须原样发布的 `.mjs` 文件会重演 CLAUDE.md 里
+ *  "package.json::files 是逐后缀白名单"那类漏发布事故的风险面。它自己那份小小的
+ *  `STATIC_IMPORT`/`packageName` 保留原样，人工与本文件保持同步。
+ * ============================================================
+ */
+
+import { lstat } from 'node:fs/promises';
+import { dirname, extname, join, resolve } from 'node:path';
+
+/**
+ * 匹配静态 `import`/`export ... from '...'` 的说明符。三个捕获组
+ * （前缀/说明符/后缀）让 `sandbox.ts` 能就地 `.replace()` 改写裸包名为 file URL；
+ * `moduleImports()` 只取第二组即可。
+ */
+export const STATIC_IMPORT =
+  /((?:^|[;\n])\s*(?:import|export)\s+(?:[^'";]*?\s+from\s+)?['"])([^'"]+)(['"])/gm;
+
+/** 从源码里抽出全部静态 import/export 说明符。 */
+export function moduleImports(source: string): string[] {
+  return [...source.matchAll(STATIC_IMPORT)].map((match) => match[2]!);
+}
+
+/** 裸导入说明符 → 包名（`@scope/pkg/sub` → `@scope/pkg`，`pkg/sub` → `pkg`）。 */
+export function packageName(specifier: string): string {
+  return specifier.startsWith('@')
+    ? specifier.split('/').slice(0, 2).join('/')
+    : specifier.split('/')[0]!;
+}
+
+/**
+ * 把一个相对 import 说明符解析成真实文件路径。
+ *
+ * **拒绝符号链接**（用 `lstat` 而不是 `stat`）——采纳 `workflowFingerprint.ts`
+ * 对随包资源文件本来就有的安全立场；`sandbox.ts` 此前用 `stat`（跟随符号链接）
+ * 是漂移，不是有意选择，收紧它是严格向下兼容。
+ *
+ * **候选扩展名不含 `.json`**——不带扩展名的相对导入解析到 `.json` 在 Node 原生
+ * ESM 下本来就不合法（没有 import assertion 语法写不出这种导入），全部 15 个
+ * 真实工作流也确认没有依赖这个候选项，去掉是安全的。显式写 `./x.json` 走
+ * `sandbox.ts::copyModule` 里单独的 `extname === '.json'` 分支，与这里正交。
+ */
+export async function resolveRelativeModule(
+  from: string,
+  specifier: string,
+): Promise<string> {
+  const base = resolve(dirname(from), specifier);
+  const candidates = extname(base)
+    ? [base]
+    : [base, `${base}.mjs`, `${base}.js`, join(base, 'index.mjs'), join(base, 'index.js')];
+  for (const candidate of candidates) {
+    try {
+      if ((await lstat(candidate)).isFile()) return candidate;
+    } catch {
+      // 试下一个候选
+    }
+  }
+  throw new Error(`无法解析工作流相对模块：${specifier}（来自 ${from}）`);
+}

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

@@ -0,0 +1,220 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { chmod, copyFile, mkdir, readdir, readlink, stat, } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { agentStateDir } from '../../../src/context/agentHome.js';
+const MIME_BY_EXT = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.webp': 'image/webp',
+    '.heic': 'image/heic',
+    '.heif': 'image/heif',
+    '.gif': 'image/gif',
+    '.bmp': 'image/bmp',
+    '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.ppt': 'application/vnd.ms-powerpoint',
+    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    '.zip': 'application/zip',
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.m4a': 'audio/mp4',
+    '.mp4': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.mkv': 'video/x-matroska',
+};
+function mimeForPath(path) {
+    const match = /\.[^.]+$/.exec(path.toLowerCase());
+    return (match && MIME_BY_EXT[match[0]]) || 'application/octet-stream';
+}
+function mimeMatches(mime, accepted) {
+    const a = accepted.toLowerCase();
+    return a.endsWith('/*')
+        ? mime.toLowerCase().startsWith(a.slice(0, -1))
+        : mime.toLowerCase() === a;
+}
+function compatible(resource, def) {
+    if (resource.kind === 'directory' && def.allowDirectory === false)
+        return false;
+    if (resource.kind === 'file' && def.allowFile === false)
+        return false;
+    if (def.accepts?.length &&
+        resource.kind === 'file' &&
+        !def.accepts.some((a) => {
+            const accepted = a.toLowerCase();
+            const ext = resource.name.toLowerCase().match(/\.[^.]+$/)?.[0];
+            return mimeMatches(resource.mime, accepted) || accepted === ext;
+        }))
+        return false;
+    return true;
+}
+function resourceId(path) {
+    return `path-${createHash('sha256').update(resolve(path)).digest('hex').slice(0, 24)}`;
+}
+async function contentHash(path) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+async function directoryContentHash(root) {
+    const hash = createHash('sha256');
+    const visit = async (dir, prefix) => {
+        const entries = await readdir(dir, { withFileTypes: true });
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                hash.update(`d\0${relative}\0`);
+                await visit(fullPath, relative);
+            }
+            else if (entry.isFile()) {
+                hash.update(`f\0${relative}\0${await contentHash(fullPath)}\0`);
+            }
+            else if (entry.isSymbolicLink()) {
+                hash.update(`l\0${relative}\0${await readlink(fullPath)}\0`);
+            }
+            else {
+                // Keep uncommon filesystem entries deterministic without opening them.
+                const info = await stat(fullPath);
+                hash.update(`o\0${relative}\0${info.mode}\0${info.size}\0`);
+            }
+        }
+    };
+    await visit(root, '');
+    return hash.digest('hex');
+}
+function safeSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120) || 'default';
+}
+function safeFileName(value, fallback) {
+    return ([...basename(value)]
+        .map((ch) => ch.codePointAt(0) < 32 || '<>:"|?*/\\'.includes(ch) ? '_' : ch)
+        .join('')
+        .slice(0, 180) || fallback);
+}
+function stagedFilePath(dir, resource, index) {
+    const safe = safeFileName(resource.name, `input-${index + 1}`);
+    return join(dir, `${String(index + 1).padStart(3, '0')}-${safe}`);
+}
+function resolveInputPath(value, cwd) {
+    if (value === '~')
+        return homedir();
+    if (value.startsWith('~/') || value.startsWith('~\\')) {
+        return resolve(homedir(), value.slice(2));
+    }
+    return resolve(cwd, value);
+}
+async function resourceFromPath(value, cwd) {
+    const localPath = resolveInputPath(value, cwd);
+    const info = await stat(localPath);
+    const kind = info.isDirectory() ? 'directory' : 'file';
+    const sha256 = kind === 'file'
+        ? await contentHash(localPath)
+        : await directoryContentHash(localPath);
+    return {
+        id: resourceId(localPath),
+        origin: 'path',
+        name: basename(localPath),
+        mime: kind === 'directory' ? 'inode/directory' : mimeForPath(localPath),
+        size: kind === 'file' ? info.size : undefined,
+        sha256,
+        localPath,
+        kind,
+    };
+}
+/** Stage attachment files in a deterministic, private directory for legacy path APIs. */
+export async function materializeResources(workflowName, sessionId, inputName, resources) {
+    const fingerprint = createHash('sha256')
+        .update(resources
+        .map((r) => `${r.sha256 ?? r.id}:${r.name}:${r.size ?? ''}`)
+        .join('|'))
+        .digest('hex')
+        .slice(0, 24);
+    const dir = join(agentStateDir(), 'workflow-inputs', safeSegment(workflowName), safeSegment(sessionId), safeSegment(inputName), fingerprint);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    for (let i = 0; i < resources.length; i++) {
+        const source = resources[i];
+        if (source.kind !== 'file')
+            continue;
+        const target = stagedFilePath(dir, source, i);
+        try {
+            await stat(target);
+            continue;
+        }
+        catch {
+            // First materialization for this content fingerprint.
+        }
+        await copyFile(source.localPath, target);
+        await chmod(target, 0o400);
+    }
+    return dir;
+}
+/** Bind explicit paths first, then compatible current-turn attachments. */
+export async function bindResourceInputs(opts) {
+    const inputs = { ...opts.rawInputs };
+    const resourceMap = {};
+    const resourceIdentity = [];
+    const warnings = [];
+    for (const def of opts.defs ?? []) {
+        if (def.type !== 'resource')
+            continue;
+        const explicit = opts.rawInputs[def.name];
+        if (explicit?.trim()) {
+            const resource = await resourceFromPath(explicit, opts.cwd ?? process.cwd());
+            const stageAsDirectory = def.materialize === 'directory' && resource.kind === 'file';
+            const accepted = stageAsDirectory
+                ? compatible(resource, { ...def, allowFile: true })
+                : compatible(resource, def);
+            if (!accepted)
+                throw new Error(`input ${def.name} 的路径类型不受支持：${explicit}`);
+            resourceMap[def.name] = [resource];
+            inputs[def.name] = stageAsDirectory
+                ? await materializeResources(opts.workflowName, opts.sessionId, def.name, [resource])
+                : resource.localPath;
+            resourceIdentity.push(def.identity === 'reference'
+                ? `${def.name}:${resource.id}`
+                : `${def.name}:${resource.sha256 ?? resource.id}`);
+            continue;
+        }
+        if (!def.attachmentFallback)
+            continue;
+        const matches = (opts.attachments ?? []).filter((resource) => def.materialize === 'directory' && resource.kind === 'file'
+            ? compatible(resource, { ...def, allowFile: true })
+            : compatible(resource, def));
+        if (!matches.length)
+            continue;
+        if (def.maxItems !== undefined && matches.length > def.maxItems) {
+            throw new Error(`input ${def.name} 最多允许 ${def.maxItems} 个附件，但本轮有 ${matches.length} 个兼容附件；请减少附件或调整 maxItems`);
+        }
+        if (def.multiple !== true && matches.length > 1) {
+            throw new Error(`input ${def.name} 只允许一个附件，但本轮有 ${matches.length} 个兼容附件；请使用 --input ${def.name}=路径 或声明 multiple: true`);
+        }
+        resourceMap[def.name] = matches;
+        for (const resource of matches) {
+            resourceIdentity.push(def.identity === 'reference'
+                ? `${def.name}:${resource.id}`
+                : `${def.name}:${resource.sha256 ?? resource.id}`);
+        }
+        const staged = await materializeResources(opts.workflowName, opts.sessionId, def.name, matches);
+        // Host attachment paths can be temporary (notably team deliveries), so
+        // even a single file must use the stable Runner copy for journal resume.
+        inputs[def.name] =
+            matches.length === 1 && def.materialize !== 'directory'
+                ? stagedFilePath(staged, matches[0], 0)
+                : staged;
+        warnings.push(`已将本轮 ${matches.length} 个附件绑定到 input ${def.name}`);
+    }
+    return { inputs, resourceMap, resourceIdentity, warnings };
+}