minimal-agent 0.12.0 → 0.14.0

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

@@ -1,130 +1,177 @@
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/taskIdentity.ts —— 任务身份与状态目录布局
+ * ------------------------------------------------------------
+ *  状态根目录优先级：
+ *    1. 环境变量 MINIMAL_AGENT_WORKFLOW_STATE_DIR（全局统一目录）
+ *    2. <cwd>/.minimal-agent-workflow/（默认）
+ *
+ *  目录结构（四级）：
+ *    <stateRoot>/<workflow>/<sessionId>/<taskId>/       ← 活动任务实例
+ *    <stateRoot>/<workflow>/<sessionId>/<taskId>.done/  ← 成功归档
+ *    <stateRoot>/<workflow>/<sessionId>/<taskId>.trash/ ← 产物淘汰回收
+ *
+ *  ------------------------------------------------------------
+ *  ⚠️ **为什么是 session 与 taskId 两层，而不是二选一**（这条改之前务必读完）
+ *
+ *  legacy 的演进history是这样的：
+ *    - Phase 2：加 taskId 实例层，根治「同名工作流跑新任务把旧状态清掉」
+ *    - Phase 3：实例目录名**改成** sessionId，taskId 降级为记录字段，换来多
+ *      session 真正并行
+ *
+ *  Phase 3 用「换掉」而不是「叠加」，于是 Phase 2 解决的问题原样回来了：同一个
+ *  session 里连着研究两个不同主题，第二次启动时前一次的声明产物会被归档进
+ *  `.trash/`，工作目录里只剩最新一份。
+ *
+ *  legacy 对此的补偿是「宿主没给显式 session 就自动生成一个带时间戳的」，但那让
+ *  resume 彻底失效 —— 时间每次都不同，于是**每次运行都是一个新 session**，
+ *  断点续跑、completed 判定、语义仲裁全部够不着。实测复现过：同一个 goal 连跑
+ *  两次，产生两个独立的 `.done` 目录，第二次没有命中 completed 而是从头重跑。
+ *
+ *  两个维度本来就是正交的，不该二选一：
+ *    - sessionId 管**并行隔离**（不同会话互不干扰）
+ *    - taskId    管**任务身份**（同一件事 → 同一个目录 → 能 resume）
+ *  两层都留下，三个需求同时成立：
+ *    同 session 同 goal → 同目录 → resume ✓
+ *    同 session 换主题 → 不同目录 → **不覆盖** ✓
+ *    不同 session      → 不同目录 → 并行 ✓
+ *
+ *  相应地本文件**不提供** `generateDefaultSessionId`：宿主给什么 session 就用
+ *  什么（含 `default`）。它当初存在的理由已由 taskId 层从结构上消除。
+ * ============================================================
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { isAbsolute, join, resolve } from 'node:path';
 import { chat as sdkChat, executeTool as sdkExecuteTool, } from '../../../src/plugin-sdk.js';
-import { truncate } from './agentCommon.js';
 import { extractJsonPayload } from './jsonPayload.js';
-// ============================================================
-//  工作流状态目录布局（E6 修复：按 workflow 名隔离）
-// ------------------------------------------------------------
-//  <cwd>/.minimal-agent-workflow/<name>/      ← 每个工作流独立状态
-//  <cwd>/.minimal-agent-workflow/<name>.done/ ← 成功归档
-//  曾经一个 cwd 单例目录：A（如 /plan）未完成时跑不同名工作流 B，
-//  init 的 new-task 路径会清掉 A 的声明产物 + 整个状态目录，A 永久失去
-//  resume 能力——与「不同任务中间文件互不干扰」需求直接冲突。
-//  按名隔离后跨工作流互不可见，互踩从结构上消失。
-//  /new 的前缀清理（.minimal-agent*）作用于父目录，行为不变。
-// ============================================================
-/** 工作流状态目录的父目录名（/new 按 .minimal-agent 前缀整体清理）。 */
+import { truncate } from './util.js';
+/** 工作流状态目录的父目录名（落在 cwd 下时使用）。 */
 export const WF_STATE_PARENT = '.minimal-agent-workflow';
-/** 把 workflow 名清洗成安全的目录名（保留字母数字._-，其余替换为 -）。 */
+/** 全局统一状态目录的环境变量名。 */
+export const WF_STATE_DIR_ENV = 'MINIMAL_AGENT_WORKFLOW_STATE_DIR';
+/** 宿主未指定 session 时的缺省名。**不再**据此自动生成带时间戳的 session。 */
+export const DEFAULT_SESSION_ID = 'default';
+/**
+ * 解析状态根目录（绝对路径）。
+ * 环境变量允许写相对路径（用户可能写 `.wflow` 这类值），基于 process.cwd() 展开。
+ */
+export function resolveStateRoot(workingDir) {
+    const envDir = process.env[WF_STATE_DIR_ENV];
+    if (envDir?.trim()) {
+        const p = envDir.trim();
+        return isAbsolute(p) ? p : resolve(p);
+    }
+    return join(workingDir, WF_STATE_PARENT);
+}
+/** 清洗成安全目录名（保留字母数字 . _ -，其余换成 -）。 */
 export function sanitizeWorkflowDirName(name) {
     return name.replace(/[^\w.-]/g, '-');
 }
-/** 某 workflow 的状态目录绝对路径。workflowState / taskIdentity 共用唯一权威实现。 */
+/** 某工作流的状态目录（其下按 session 再分）。 */
 export function workflowStateDir(workingDir, workflowName) {
-    return join(workingDir, WF_STATE_PARENT, sanitizeWorkflowDirName(workflowName));
+    return join(resolveStateRoot(workingDir), sanitizeWorkflowDirName(workflowName));
+}
+/** 某工作流在某 session 下的目录（其下按 taskId 再分）。 */
+export function sessionStateDir(workingDir, workflowName, sessionId) {
+    return join(workflowStateDir(workingDir, workflowName), sanitizeWorkflowDirName(sessionId));
+}
+/**
+ * 一个具体任务实例的状态目录。
+ * 成功后改名 `<taskId>.done/`；产物淘汰归档到 `<taskId>.trash/`。
+ */
+export function taskInstanceDir(workingDir, workflowName, sessionId, taskId) {
+    return join(sessionStateDir(workingDir, workflowName, sessionId), sanitizeWorkflowDirName(taskId));
+}
+/**
+ * 归一化 goal：小写 → 去标点（保留中日韩/字母/数字/空格）→ 压缩空格 → 截断 200。
+ *
+ * 截断是刻意的：超长输入里靠后的细微差异不该让「同一件事」算成两个任务。
+ */
+function normalizeGoal(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s]/gu, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 200);
 }
 /**
- * 计算任务身份 hash。
+ * 任务身份 = SHA256(工作流名 + 归一化 goal) 前 16 位。
  *
- * 策略（内容 hash 是【唯一权威信号】）：
- *   - 对「workflow 名 + 归一化 goal」做 SHA256 → 取前 16 位 = taskId。
- *   - 同 hash → 同一任务（无论隔了多久）；hash 不同 → 不同任务。
- *   - recency（上次 startedAt 的时间窗口）【不】参与身份判定：30 分钟内换一个
- *     完全不同的 goal 重跑同名 workflow，必须判「全新任务」清理重开，而不是
- *     错误地 resume 旧任务把旧变量混进新目标（需求 3.2「不相关新任务自动清理重开」）。
- *     旧版「时间窗口覆盖 hash 差异」是 bug，已移除。
+ * **纯函数，不读盘** —— 这是四级布局带来的简化：taskId 就是目录名，「是不是同一个
+ * 任务」等价于「那个目录在不在」，不必再扫描实例目录逐个比对记录字段。
  *
- * 归一化规则：
- *   - 转小写
- *   - 去除所有标点符号（保留中文、英文、数字、空格）
- *   - 去除多余空格（连续空格→单空格，首尾 trim）
- *   - 截断到 200 字符（防止超长输入导致不必要的差异）
+ * ⚠️ 时间**不参与**身份判定。半小时内换一个完全不同的 goal 重跑同名工作流，
+ * 必须判成全新任务，而不是 resume 旧任务把旧变量混进新目标里。legacy 早期
+ * 「时间窗口覆盖 hash 差异」的写法是 bug，已移除，别加回来。
  */
-export function computeTaskId(workflowName, inputs, workingDir) {
-    // 1. 提取 goal 文本（与 buildGoalAnchor 同策略）
-    const rawGoal = extractGoal(inputs);
-    // 2. 归一化 goal
-    const normalizedGoal = normalizeGoal(rawGoal);
-    // 3. 计算 contentHash = SHA256(`${workflowName}::${normalizedGoal}`)[:16]
-    const contentHash = createHash('sha256')
-        .update(`${workflowName}::${normalizedGoal}`)
-        .digest('hex')
-        .slice(0, 16);
-    // 4. 如果没有提供 workingDir，只返回 hash，不做比较
-    if (!workingDir) {
-        return {
-            hash: contentHash,
-            isSameTask: false,
-            reason: 'no_previous',
-        };
-    }
-    // 5. 尝试读取旧状态文件（按 workflow 名隔离的状态目录）
-    const stateFilePath = join(workflowStateDir(workingDir, workflowName), 'current.json');
-    if (!existsSync(stateFilePath)) {
-        return {
-            hash: contentHash,
-            isSameTask: false,
-            reason: 'no_previous',
-        };
-    }
-    try {
-        const stateContent = readFileSync(stateFilePath, 'utf-8');
-        const prevState = JSON.parse(stateContent);
-        // a. 不同 workflow 名 → 不同任务
-        if (prevState.name && prevState.name !== workflowName) {
-            return {
-                hash: contentHash,
-                isSameTask: false,
-                reason: 'different_workflow',
-            };
-        }
-        // b. 内容 hash 一致 → 同一任务（唯一权威信号，与时间无关）
-        if (prevState.taskId === contentHash) {
-            return {
-                hash: contentHash,
-                isSameTask: true,
-                reason: 'hash_match',
-            };
-        }
-        // c. hash 不一致 → 不同任务（goal 变了）。recency 不覆盖此判定（见函数头注）。
-        return {
-            hash: contentHash,
-            isSameTask: false,
-            reason: 'hash_diff',
-        };
-    }
-    catch {
-        // 解析失败时返回默认结果
-        return {
-            hash: contentHash,
-            isSameTask: false,
-            reason: 'no_previous',
-        };
-    }
+export function computeTaskId(workflowName, inputs, defs) {
+    const goal = normalizeGoal(extractGoal(inputs, defs));
+    const resourceFingerprint = typeof inputs.__resource_fingerprint === 'string'
+        ? inputs.__resource_fingerprint.trim()
+        : '';
+    // Typed resource workflows also have processing parameters (format, range,
+    // language, etc.). Equal source bytes with different parameters must not hit
+    // completed before the script can observe the new arguments. Keep the legacy
+    // goal-only identity for workflows without resource bindings.
+    const parameters = resourceFingerprint
+        ? (defs ?? [])
+            .filter((d) => d.type !== 'resource' && !['goal', 'requestText'].includes(d.name))
+            .map((d) => [d.name, inputs[d.name] ?? d.default ?? null])
+            .sort(([a], [b]) => a.localeCompare(b))
+        : [];
+    // 资源是任务身份的一部分，而不是目标锚的一部分。这样模型仍只看到人类可读
+    // 目标，但同一句“帮我整理成 Word”配不同附件不会误命中上一份已完成产物。
+    const identity = resourceFingerprint
+        ? `${workflowName} ${goal}\nresource:${resourceFingerprint}${parameters.length ? '\nparameters:' + JSON.stringify(parameters) : ''}`
+        : `${workflowName} ${goal}`;
+    return createHash('sha256').update(identity).digest('hex').slice(0, 16);
 }
 /**
- * 从 inputs 中提取 goal 文本
+ * 从 inputs 里提取「目标」文本。**任务身份与目标锚共用这一份规则** ——
+ * 两处各写一套会让「拿来算 taskId 的目标」和「注入给模型的目标」指向不同的东西。
+ *
+ * 取值顺序：
+ *   ① 名为 `goal` 的输入
+ *   ② 第一个 **required** 的字符串输入（作者用 required 表达了「这是主要输入」）
+ *   ③ 第一个非空字符串输入
+ *   ④ 整体 JSON（保证恒有确定值）
  *
- * 策略：
- * - 优先 inputs.goal
- * - 其次第一个 length > 2 的 string 值
- * - 最后 JSON.stringify 整个 inputs
+ * ⚠️ 第 ③ 条曾经写的是「长度 **> 2** 的字符串」。那条阈值是照拉丁文本想的
+ * （跳过 `ab`、语言代码之类），**对中文直接失效** —— `世界`、`调研` 这种两个字的
+ * 目标太常见了，会被跳过去落到 ④，于是 current.json 里记的目标变成一坨 JSON、
+ * 仲裁时喂给 LLM 的也是那坨 JSON。端到端实跑复现过（/workflow e2e-smoke 世界）。
  */
-export function extractGoal(inputs) {
-    // 优先级1：直接使用 inputs.goal
-    if (typeof inputs.goal === 'string') {
+export function extractGoal(inputs, defs) {
+    if (typeof inputs.goal === 'string' && inputs.goal.trim()) {
         return inputs.goal;
     }
-    // 优先级2：查找第一个长度 > 2 的字符串值
-    for (const value of Object.values(inputs)) {
-        if (typeof value === 'string' && value.length > 2) {
+    for (const def of defs ?? []) {
+        const v = inputs[def.name];
+        if (def.type !== 'resource' &&
+            def.required &&
+            typeof v === 'string' &&
+            v.trim())
+            return v;
+    }
+    if (typeof inputs.requestText === 'string' && inputs.requestText.trim())
+        return inputs.requestText;
+    const resourceNames = new Set((defs ?? []).filter((d) => d.type === 'resource').map((d) => d.name));
+    for (const [name, value] of Object.entries(inputs)) {
+        if (resourceNames.has(name) || name === '__resource_fingerprint')
+            continue;
+        if (typeof value === 'string' && value.trim())
             return value;
-        }
     }
-    // 优先级3：JSON 序列化整个 inputs
-    return JSON.stringify(inputs);
+    if (typeof inputs.__resource_fingerprint === 'string' &&
+        inputs.__resource_fingerprint.trim()) {
+        return `resource:${inputs.__resource_fingerprint}`;
+    }
+    const sanitized = { ...inputs };
+    for (const name of resourceNames)
+        if (name in sanitized)
+            sanitized[name] = '<resource>';
+    return JSON.stringify(sanitized);
 }
 /** 延续短语白名单（归一化后精确匹配；短输入再放宽到前缀匹配）。 */
 const CONTINUATION_PHRASES = new Set([
@@ -146,49 +193,42 @@ const CONTINUATION_PHRASES = new Set([
     'keep going',
     'carry on',
 ]);
-/** 新输入是否是「延续上次任务」的指令（仲裁快路径，不花 LLM）。 */
+/** 新输入是否是「延续上次任务」的指令（快路径，不花 LLM）。 */
 export function isContinuationPhrase(rawGoal) {
     const norm = normalizeGoal(rawGoal);
     if (!norm)
         return false;
     if (CONTINUATION_PHRASES.has(norm))
         return true;
-    // 短输入且以延续词开头（如「继续干活」「continue please」）也算
-    if (norm.length <= 12 &&
+    // 短输入且以延续词开头（「继续干活」「continue please」）也算
+    return (norm.length <= 12 &&
         (norm.startsWith('继续') ||
             norm.startsWith('接着') ||
             norm.startsWith('continue') ||
-            norm.startsWith('resume'))) {
-        return true;
-    }
-    return false;
+            norm.startsWith('resume')));
 }
 /**
- * 构建复合仲裁器（短语快路径 → LLM 单轮仲裁 → AskUserQuestion → 兜底 new）。
- * runner 在 state.init 前构建并传入；任何一级抛错都降级到下一级，绝不让仲裁本身 halt 工作流。
+ * 构建复合仲裁器。任何一级抛错都降级到下一级 —— **仲裁本身绝不 halt 工作流**。
  */
 export function buildTaskArbitrator(deps) {
     const note = (m) => {
         deps.notes?.push(m);
     };
     return async (actx) => {
-        // a. 延续短语快路径
         if (isContinuationPhrase(actx.newGoal)) {
             note(`任务仲裁：新输入「${truncate(actx.newGoal, 40)}」命中延续短语 → 继续旧任务（目标：${truncate(actx.prevGoal, 60)}）`);
             return 'resume';
         }
-        // b. LLM 单轮仲裁
         try {
             const verdict = await llmArbitrate(deps, actx);
             if (verdict !== 'unsure') {
-                note(`任务仲裁：LLM 判定新输入${verdict === 'resume' ? '是旧任务的延续 → 续跑' : '是全新任务 → 清理旧产物重开'}`);
+                note(`任务仲裁：LLM 判定新输入${verdict === 'resume' ? '是旧任务的延续 → 续跑' : '是全新任务 → 归档旧产物重开'}`);
                 return verdict;
             }
         }
         catch {
             // LLM 不可用 → 降级到提问
         }
-        // c. AskUserQuestion（TUI 弹界面；非交互宿主 askBridge 自动选推荐项=全新开始）
         try {
             const verdict = await askUserArbitrate(deps, actx);
             note(`任务仲裁：经用户确认 → ${verdict === 'resume' ? '继续旧任务' : '全新开始'}`);
@@ -197,21 +237,19 @@ export function buildTaskArbitrator(deps) {
         catch {
             // 提问被取消/不可用 → 兜底
         }
-        // d. 兜底 = 旧红线行为（hash 不等 → new-task），最小惊讶
         note('任务仲裁：无法判定（LLM 与提问均不可用）→ 按全新任务处理');
         return 'new';
     };
 }
-/** LLM 单轮仲裁：旧 goal + 新输入 + 进度摘要 → {verdict, reason}。解析失败按 unsure。 */
+/** LLM 单轮仲裁 → {verdict, reason}。解析失败一律按 unsure，不猜。 */
 async function llmArbitrate(deps, actx) {
     const chatFn = deps.chat ?? sdkChat;
-    const progress = `${actx.completedStepIds.length}/${actx.totalSteps}`;
     const prompt = [
         `你是工作流引擎的任务身份仲裁器。同名工作流「${actx.workflowName}」存在一个未完成的旧任务，`,
-        `用户刚发起了一次新调用，新输入的文本与旧任务目标不同。请判断新输入是「旧任务的延续指令」还是「全新任务」。`,
+        '用户刚发起了一次新调用，新输入的文本与旧任务目标不同。请判断新输入是「旧任务的延续指令」还是「全新任务」。',
         '',
         `旧任务目标：${truncate(actx.prevGoal, 300)}`,
-        `旧任务进度：已完成 ${progress} 步${actx.completedStepIds.length ? `（${actx.completedStepIds.join(', ')}）` : ''}`,
+        `旧任务进度：已完成 ${actx.completedCalls} 次调用`,
         actx.artifacts.length ? `旧任务产物：${actx.artifacts.join(', ')}` : '',
         `新输入：${truncate(actx.newGoal, 300)}`,
         '',
@@ -225,7 +263,12 @@ async function llmArbitrate(deps, actx) {
     for await (const ev of chatFn({
         provider: deps.provider,
         messages: [
-            { role: 'user', content: prompt, timestamp: Date.now(), id: crypto.randomUUID() },
+            {
+                role: 'user',
+                content: prompt,
+                timestamp: Date.now(),
+                id: randomUUID(),
+            },
         ],
         tools: [],
         signal: deps.signal,
@@ -244,20 +287,19 @@ async function llmArbitrate(deps, actx) {
     }
     return 'unsure';
 }
-/** 经 AskUserQuestion 问用户（推荐项=全新开始，与兜底语义一致；非交互自动按推荐项）。 */
+/** 问用户。推荐项 = 全新开始（与兜底语义一致）；非交互宿主自动按推荐项。 */
 async function askUserArbitrate(deps, actx) {
     const exec = deps.executeTool ?? sdkExecuteTool;
-    const progress = `${actx.completedStepIds.length}/${actx.totalSteps}`;
     const args = {
         questions: [
             {
                 question: `检测到工作流「${actx.workflowName}」有一个未完成的任务（目标：${truncate(actx.prevGoal, 80)}，` +
-                    `进度 ${progress} 步）。本次输入「${truncate(actx.newGoal, 80)}」是要继续该任务，还是开始全新任务？`,
+                    `已完成 ${actx.completedCalls} 次调用）。本次输入「${truncate(actx.newGoal, 80)}」是要继续该任务，还是开始全新任务？`,
                 header: '任务仲裁',
                 options: [
                     {
                         label: '全新开始 (推荐)',
-                        description: '清理旧任务的中间产物，按本次输入重新规划执行',
+                        description: '归档旧任务的中间产物，按本次输入重新规划执行',
                     },
                     {
                         label: '继续上次任务',
@@ -272,25 +314,3 @@ async function askUserArbitrate(deps, actx) {
         throw new Error(r.error);
     return r.content.includes('继续上次任务') ? 'resume' : 'new';
 }
-/**
- * 归一化 goal 字符串
- *
- * 规则：
- * - toLowerCase()
- * - 去除所有标点符号（保留中文、英文、数字、空格）
- * - 去除多余空格（连续空格→单空格）
- * - 首尾 trim
- * - 截断到 200 字符
- */
-function normalizeGoal(raw) {
-    return (raw
-        .toLowerCase()
-        // 保留中文、英文、数字、空格，去除其他字符（标点等）
-        .replace(/[^\p{L}\p{N}\s]/gu, '')
-        // 连续空格替换为单空格
-        .replace(/\s+/g, ' ')
-        // 首尾去空格
-        .trim()
-        // 截断到 200 字符
-        .slice(0, 200));
-}