minimal-agent 0.13.0 → 0.14.0

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

@@ -1,5 +1,47 @@
-import { createHash, randomBytes, randomUUID } from 'node:crypto';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+/**
+ * ============================================================
+ *  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 {
@@ -7,378 +49,218 @@ import {
   executeTool as sdkExecuteTool,
 } from '../../../src/plugin-sdk.js';
 import type { Provider } from '../../../src/plugin-sdk.js';
-import { truncate } from './agentCommon.js';
 import { extractJsonPayload } from './jsonPayload.js';
-import type { RunContext } from './types.js';
-
-// ============================================================
-//  工作流状态目录布局（Phase 1 + 2 + 3 升级）
-// ------------------------------------------------------------
-//  状态根目录优先级：
-//    1. 环境变量 MINIMAL_AGENT_WORKFLOW_STATE_DIR（全局统一目录）
-//    2. <cwd>/.minimal-agent-workflow/（默认，与历史行为一致）
-//
-//  目录结构（三级：工作流名 / session 实例 / taskId 记录）：
-//    <stateRoot>/<workflowName>/<sessionId>/       ← 活动任务实例（session 即任务实例）
-//    <stateRoot>/<workflowName>/<sessionId>.done/  ← 成功完成的实例归档
-//    <stateRoot>/<workflowName>/<sessionId>.trash/ ← 清理回收（A4 归档）
-//
-//  Phase 3（session 化）：实例目录名 = sessionId（一个 session 同时只跑一个
-//  同名工作流，session 即天然的任务实例划分单元）。taskId（goal 内容 hash）
-//  降级为 current.json 里的【记录字段】——用于同 session 内识别「换主题 →
-//  new-task 归档重建 / 同主题 → resume/completed」。不同 session 完全隔离，
-//  同主题也可并行互不干扰。
-//
-//  演进历史：
-//    - 最初：<cwd>/.minimal-agent-workflow/ 单例（所有工作流共用）
-//    - E6：按 workflow 名隔离，<cwd>/.minimal-agent-workflow/<name>/
-//    - Phase 1：状态根目录可配置（环境变量指定全局位置，解决 cwd 切换找不到）
-//    - Phase 2：新增 taskId 实例层，同名 workflow 多任务并存（根治新任务清掉旧状态）
-//    - Phase 3：实例目录名改为 sessionId，taskId 降级为记录字段（多 session 真正并行）
-// ============================================================
+import type { InputDef, RunContext } from './types.js';
+import { truncate } from './util.js';
 
-/** 工作流状态目录的父目录名（默认落在 cwd 下时使用）。 */
+/** 工作流状态目录的父目录名（落在 cwd 下时使用）。 */
 export const WF_STATE_PARENT = '.minimal-agent-workflow';
 
 /** 全局统一状态目录的环境变量名。 */
 export const WF_STATE_DIR_ENV = 'MINIMAL_AGENT_WORKFLOW_STATE_DIR';
 
-/** 缺省 sessionId（宿主未显式传 session 时的兜底判定值；真正落盘的 session 由 generateDefaultSessionId 自动命名）。 */
+/** 宿主未指定 session 时的缺省名。**不再**据此自动生成带时间戳的 session。 */
 export const DEFAULT_SESSION_ID = 'default';
 
-/**
- * 工作流引擎的默认 session 自动命名：宿主未显式提供有意义 session（缺失或为
- * DEFAULT_SESSION_ID）时，由引擎自行生成唯一可读的 session 名
- * `YYYYMMDD-HHmmss-xxxxxx`（日期时间 + 6 位随机 hex）。
- *
- * 语义：每次工作流运行（CLI -p 默认 / TUI default 会话）都自动落到独立的
- * `<out>/<workflow>/<session>/` 产物目录与 `<stateRoot>/<workflow>/<session>/`
- * 状态目录——多 session 并行互不覆盖；时间前缀便于人识别与排序，随机后缀
- * 防同一秒并行冲突。宿主显式传 `-s <id>`（非 default）时仍优先使用宿主 id。
- */
-export function generateDefaultSessionId(now = new Date()): string {
-  const pad = (n: number, w = 2): string => String(n).padStart(w, '0');
-  const date = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
-  const time = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
-  const rand = randomBytes(3).toString('hex');
-  return `${date}-${time}-${rand}`;
-}
-
 /**
  * 解析状态根目录（绝对路径）。
- * 优先级：环境变量 MINIMAL_AGENT_WORKFLOW_STATE_DIR > cwd 下默认目录。
- * 环境变量允许相对路径——基于 process.cwd() 展开（用户可能写 `.wflow` 这类相对值）。
- * 传入 workingDir 是为了 cwd 默认模式的相对路径基准。
+ * 环境变量允许写相对路径（用户可能写 `.wflow` 这类值），基于 process.cwd() 展开。
  */
 export function resolveStateRoot(workingDir: string): string {
   const envDir = process.env[WF_STATE_DIR_ENV];
-  if (envDir && envDir.trim()) {
+  if (envDir?.trim()) {
     const p = envDir.trim();
     return isAbsolute(p) ? p : resolve(p);
   }
   return join(workingDir, WF_STATE_PARENT);
 }
 
-/** 把 workflow 名 / sessionId 清洗成安全的目录名（保留字母数字._-，其余替换为 -）。 */
+/** 清洗成安全目录名（保留字母数字 . _ -，其余换成 -）。 */
 export function sanitizeWorkflowDirName(name: string): string {
   return name.replace(/[^\w.-]/g, '-');
 }
 
-/**
- * 某 workflow 的状态目录绝对路径（workflow 级目录，下含多个 session 实例）。
- * workflowState / taskIdentity 共用唯一权威实现。
- */
-export function workflowStateDir(workingDir: string, workflowName: string): string {
-  return join(resolveStateRoot(workingDir), sanitizeWorkflowDirName(workflowName));
+/** 某工作流的状态目录（其下按 session 再分）。 */
+export function workflowStateDir(
+  workingDir: string,
+  workflowName: string,
+): string {
+  return join(
+    resolveStateRoot(workingDir),
+    sanitizeWorkflowDirName(workflowName),
+  );
+}
+
+/** 某工作流在某 session 下的目录（其下按 taskId 再分）。 */
+export function sessionStateDir(
+  workingDir: string,
+  workflowName: string,
+  sessionId: string,
+): string {
+  return join(
+    workflowStateDir(workingDir, workflowName),
+    sanitizeWorkflowDirName(sessionId),
+  );
 }
 
 /**
- * 具体任务实例（= session）的状态目录。
- * 成功后改名为 <sessionId>.done/；清理归档目录为 <sessionId>.trash/。
+ * 一个具体任务实例的状态目录。
+ * 成功后改名 `<taskId>.done/`；产物淘汰归档到 `<taskId>.trash/`。
  */
 export function taskInstanceDir(
   workingDir: string,
   workflowName: string,
   sessionId: string,
+  taskId: string,
 ): string {
-  return join(workflowStateDir(workingDir, workflowName), sanitizeWorkflowDirName(sessionId));
+  return join(
+    sessionStateDir(workingDir, workflowName, sessionId),
+    sanitizeWorkflowDirName(taskId),
+  );
 }
 
 /**
- * 任务身份判定结果
+ * 归一化 goal：小写 → 去标点（保留中日韩/字母/数字/空格）→ 压缩空格 → 截断 200。
+ *
+ * 截断是刻意的：超长输入里靠后的细微差异不该让「同一件事」算成两个任务。
  */
-export interface TaskIdentityResult {
-  /** 归一化后的 hash（16 位 hex） */
-  hash: string;
-  /** 是否与磁盘上记录的 taskId 匹配 */
-  isSameTask: boolean;
-  /** 判定依据：'hash_match' | 'hash_diff' | 'different_workflow' | 'no_previous' */
-  reason: string;
+function normalizeGoal(raw: string): string {
+  return raw
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]/gu, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 200);
 }
 
 /**
- * 计算任务身份 hash。
- *
- * 策略（内容 hash 是【唯一权威信号】）：
- *   - 对「workflow 名 + 归一化 goal」做 SHA256 → 取前 16 位 = taskId。
- *   - 同 hash → 同一任务（无论隔了多久）；hash 不同 → 不同任务。
- *   - recency（上次 startedAt 的时间窗口）【不】参与身份判定：30 分钟内换一个
- *     完全不同的 goal 重跑同名 workflow，必须判「全新任务」清理重开，而不是
- *     错误地 resume 旧任务把旧变量混进新目标（需求 3.2「不相关新任务自动清理重开」）。
- *     旧版「时间窗口覆盖 hash 差异」是 bug，已移除。
+ * 任务身份 = SHA256(工作流名 + 归一化 goal) 前 16 位。
  *
- * 归一化规则：
- *   - 转小写
- *   - 去除所有标点符号（保留中文、英文、数字、空格）
- *   - 去除多余空格（连续空格→单空格，首尾 trim）
- *   - 截断到 200 字符（防止超长输入导致不必要的差异）
+ * **纯函数，不读盘** —— 这是四级布局带来的简化：taskId 就是目录名，「是不是同一个
+ * 任务」等价于「那个目录在不在」，不必再扫描实例目录逐个比对记录字段。
  *
- * 参数：
- *   - workingDir：不传只返回 hash（纯计算，不读盘）。
- *   - sessionId：Phase 3 后传入——实例查找限定到「当前 session」的实例目录
- *     （<wfDir>/<sessionId>/ 与 <sessionId>.done/），读其 current.json 的 taskId
- *     记录与本次 hash 比较。缺省时退化为旧行为（扫 wfDir 下所有 taskId 实例），
- *     兼容历史调用与测试。
+ * ⚠️ 时间**不参与**身份判定。半小时内换一个完全不同的 goal 重跑同名工作流，
+ * 必须判成全新任务，而不是 resume 旧任务把旧变量混进新目标里。legacy 早期
+ * 「时间窗口覆盖 hash 差异」的写法是 bug，已移除，别加回来。
  */
 export function computeTaskId(
   workflowName: string,
   inputs: Record<string, unknown>,
-  workingDir?: string,
-  sessionId?: string,
-): TaskIdentityResult {
-  // 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. 找当前任务对应的实例目录，读其 current.json 记录与本次 hash 比较
-  //    （Phase 3：session 语义——只查当前 session 的实例；taskId 是记录字段）
-  const wfDir = workflowStateDir(workingDir, workflowName);
-  const candidateDirs = findTaskInstanceDirs(wfDir, contentHash, sessionId);
-
-  if (candidateDirs.length === 0) {
-    // 无精确匹配。但若 wfDir 下存在其他任务实例（不同 goal / 已归档），
-    // 语义仍是「新任务 + 旧任务在场」——返回 hash_diff 而非 no_previous，
-    // 让 workflowState.init 能触发仲裁/清理旧产物（旧布局靠读 wfDir/current.json
-    // 天然得到这个信号，新布局必须显式扫描）。
-    return {
-      hash: contentHash,
-      isSameTask: false,
-      reason: hasAnyTaskInstanceInDir(wfDir, sessionId) ? 'hash_diff' : 'no_previous',
-    };
-  }
-
-  // 取第一个匹配的（hash 一样就是同一任务，不应有多个；有多个也只取第一个）
-  const stateFilePath = join(candidateDirs[0], 'current.json');
-  if (!existsSync(stateFilePath)) {
-    return {
-      hash: contentHash,
-      isSameTask: false,
-      reason: 'no_previous',
-    };
-  }
-
-  try {
-    const stateContent = readFileSync(stateFilePath, 'utf8');
-    const prevState = JSON.parse(stateContent) as {
-      taskId?: string;
-      name?: string;
-      startedAt?: string;
-    };
-
-    // 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',
-    };
-  }
-}
-
-/**
- * 在 workflow 级目录下，找到当前任务对应的实例目录。
- * 支持两种布局：
- *   - 新布局（Phase 3，传 sessionId）：<wfDir>/<sessionId>/current.json（活动）
- *     与 <wfDir>/<sessionId>.done/current.json（已完成）
- *   - 旧布局（Phase 2，不传 sessionId）：<wfDir>/<taskId>/current.json
- *     与 <wfDir>/<taskId>.done/current.json
- *   - 旧布局兼容（无 session 层）：<wfDir>/current.json —— 把整个 wfDir 当成一个实例
- * 返回绝对路径数组。
- */
-function findTaskInstanceDirs(
-  wfDir: string,
-  taskId: string,
-  sessionId?: string,
-): string[] {
-  const results: string[] = [];
-
-  if (sessionId) {
-    // Phase 3：session 语义 —— 只找当前 session 的实例（taskId 是记录字段，目录名是 sessionId）
-    const activeDir = join(wfDir, sanitizeWorkflowDirName(sessionId));
-    const doneDir = join(wfDir, `${sanitizeWorkflowDirName(sessionId)}.done`);
-    if (existsSync(activeDir)) results.push(activeDir);
-    if (existsSync(doneDir)) results.push(doneDir);
-  } else {
-    // Phase 2 旧行为：<wfDir>/<taskId>/ 和 <wfDir>/<taskId>.done/
-    const activeDir = join(wfDir, taskId);
-    const doneDir = join(wfDir, `${taskId}.done`);
-    if (existsSync(activeDir)) results.push(activeDir);
-    if (existsSync(doneDir)) results.push(doneDir);
-  }
-
-  if (results.length > 0) return results;
-
-  // 旧布局兼容：wfDir 本身就是实例目录（current.json 直接在 wfDir 下）
-  // 检测方法：wfDir/current.json 存在且 wfDir 下没有子目录是 taskId 格式
-  if (existsSync(join(wfDir, 'current.json'))) {
-    // 确认这是旧布局（不是某个子实例目录）
-    try {
-      const entries = readdirSync(wfDir, { withFileTypes: true });
-      const hasInstanceSubdir = entries.some(
-        (e) => e.isDirectory() && /^[0-9a-f]{16}$/.test(e.name),
-      );
-      if (!hasInstanceSubdir) {
-        results.push(wfDir);
-      }
-    } catch {
-      // 读不到就当旧布局
-      results.push(wfDir);
-    }
-  }
-
-  return results;
-}
-
-/**
- * 检查 wfDir 下是否存在任何任务实例（活动态 / .done 归档态 / 旧布局 current.json）。
- * 不含 .trash 回收目录。用于 computeTaskId 在无精确匹配时区分
- * hash_diff（有其他旧任务）与 no_previous（从未跑过）。
- * 传 sessionId 时只统计当前 session 的实例（Phase 3）。
- */
-function hasAnyTaskInstanceInDir(wfDir: string, sessionId?: string): boolean {
-  if (!existsSync(wfDir)) return false;
-  try {
-    if (sessionId) {
-      // Phase 3：只看当前 session 的实例
-      const active = join(wfDir, sanitizeWorkflowDirName(sessionId));
-      const done = join(wfDir, `${sanitizeWorkflowDirName(sessionId)}.done`);
-      if (existsSync(active)) return true;
-      if (existsSync(done)) return true;
-      // 旧布局：wfDir 本身就是实例目录
-      if (existsSync(join(wfDir, 'current.json'))) return true;
-      if (existsSync(join(wfDir + '.done', 'current.json'))) return true;
-      return false;
-    }
-    const entries = readdirSync(wfDir, { withFileTypes: true });
-    for (const e of entries) {
-      if (!e.isDirectory()) continue;
-      if (/^[0-9a-f]{16}$/.test(e.name)) return true; // 活动实例
-      if (/^[0-9a-f]{16}\.done$/.test(e.name)) return true; // 归档实例
-    }
-    // 旧布局：wfDir 本身就是实例目录
-    if (existsSync(join(wfDir, 'current.json'))) return true;
-    if (existsSync(join(wfDir + '.done', 'current.json'))) return true;
-    return false;
-  } catch {
-    return false;
-  }
+  defs?: InputDef[],
+): string {
+  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] as const)
+        .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 的目标」和「注入给模型的目标」指向不同的东西。
  *
- * 策略：
- * - 优先 inputs.goal
- * - 其次第一个 length > 2 的 string 值
- * - 最后 JSON.stringify 整个 inputs
+ * 取值顺序：
+ *   ① 名为 `goal` 的输入
+ *   ② 第一个 **required** 的字符串输入（作者用 required 表达了「这是主要输入」）
+ *   ③ 第一个非空字符串输入
+ *   ④ 整体 JSON（保证恒有确定值）
+ *
+ * ⚠️ 第 ③ 条曾经写的是「长度 **> 2** 的字符串」。那条阈值是照拉丁文本想的
+ * （跳过 `ab`、语言代码之类），**对中文直接失效** —— `世界`、`调研` 这种两个字的
+ * 目标太常见了，会被跳过去落到 ④，于是 current.json 里记的目标变成一坨 JSON、
+ * 仲裁时喂给 LLM 的也是那坨 JSON。端到端实跑复现过（/workflow e2e-smoke 世界）。
  */
-export function extractGoal(inputs: Record<string, unknown>): string {
-  // 优先级1：直接使用 inputs.goal
-  if (typeof inputs.goal === 'string') {
+export function extractGoal(
+  inputs: Record<string, unknown>,
+  defs?: InputDef[],
+): string {
+  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) {
-      return value;
-    }
+  for (const def of defs ?? []) {
+    const v = inputs[def.name];
+    if (
+      def.type !== 'resource' &&
+      def.required &&
+      typeof v === 'string' &&
+      v.trim()
+    )
+      return v;
   }
-
-  // 优先级3：JSON 序列化整个 inputs
-  return JSON.stringify(inputs);
+  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;
+  }
+  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);
 }
 
 // ============================================================
-//  任务身份语义仲裁层（hash 不等 + 旧任务未完成时的二审）
+//  任务身份语义仲裁（hash 不等 + 旧任务未完成时的二审）
 // ------------------------------------------------------------
-//  hash 仍是「同任务」的权威信号（相等 → resume/completed，与时间无关）。
-//  但 hash 不等不再一票否决：用户输入「继续」这类延续指令，goal 文本必然
-//  与旧任务不同，按旧规则会被误判 new-task 把没做完的产物清掉重开。
-//  仲裁链（逐级降级，零 yaml 耦合，所有工作流自动获益）：
-//    a. 延续短语快路径（继续/接着/continue/resume…）→ resume，不花 LLM
+//  hash 相等仍是「同任务」的权威信号。但 hash 不等**不再一票否决**：用户输入
+//  「继续」这类延续指令时，goal 文本必然与旧任务不同，按裸 hash 规则会被误判成
+//  全新任务、把没做完的产物清掉重开。
+//
+//  仲裁链逐级降级（零脚本耦合，所有工作流自动获益）：
+//    a. 延续短语快路径（继续/接着/continue…）→ resume，不花 LLM
 //    b. LLM 单轮仲裁（旧 goal + 新输入 + 进度摘要 → JSON verdict）
-//    c. verdict=unsure / LLM 不可用 → AskUserQuestion 问用户
+//    c. unsure / LLM 不可用 → AskUserQuestion 问用户
 //       （TUI 弹界面；-p/gateway 由 askBridge 自动选推荐项，不挂起）
-//    d. 提问也失败 → 兜底 new-task（= 旧红线行为，最小惊讶）
+//    d. 提问也失败 → 兜底 new-task（最小惊讶）
 // ============================================================
 
-/** 仲裁输入：引擎已有信息，不依赖任何具体 yaml。 */
+/** 仲裁输入：全部来自引擎已有信息，不依赖任何具体工作流。 */
 export interface TaskArbitrationContext {
   workflowName: string;
-  /** 旧任务的原始 goal（来自状态目录 inputs.json） */
+  /** 旧任务的原始 goal。 */
   prevGoal: string;
-  /** 本次调用的新 goal 文本 */
+  /** 本次调用的新 goal 文本。 */
   newGoal: string;
-  /** 旧任务已完成的步骤 id（按顺序） */
-  completedStepIds: string[];
-  totalSteps: number;
-  /** 旧任务声明的产物路径 */
+  /**
+   * 旧任务已完成的**引擎中介调用数**。
+   *
+   * legacy 这里是 `completedStepIds[] / totalSteps` —— 代码形态没有「步骤」，
+   * 也无法预知总数（控制流由 JS 决定），所以只报已完成数量。
+   */
+  completedCalls: number;
+  /** 旧任务已产出的声明产物路径。 */
   artifacts: string[];
 }
 
-/** 仲裁器：'resume' = 新输入是旧任务的延续；'new' = 全新任务（清理重开）。 */
+/** 'resume' = 新输入是旧任务的延续；'new' = 全新任务（归档旧产物重开）。 */
 export type TaskArbitrator = (
   actx: TaskArbitrationContext,
 ) => Promise<'resume' | 'new'>;
@@ -404,37 +286,33 @@ const CONTINUATION_PHRASES = new Set([
   'carry on',
 ]);
 
-/** 新输入是否是「延续上次任务」的指令（仲裁快路径，不花 LLM）。 */
+/** 新输入是否是「延续上次任务」的指令（快路径，不花 LLM）。 */
 export function isContinuationPhrase(rawGoal: string): boolean {
   const norm = normalizeGoal(rawGoal);
   if (!norm) return false;
   if (CONTINUATION_PHRASES.has(norm)) return true;
-  // 短输入且以延续词开头（如「继续干活」「continue please」）也算
-  if (
+  // 短输入且以延续词开头（「继续干活」「continue please」）也算
+  return (
     norm.length <= 12 &&
     (norm.startsWith('继续') ||
       norm.startsWith('接着') ||
       norm.startsWith('continue') ||
       norm.startsWith('resume'))
-  ) {
-    return true;
-  }
-  return false;
+  );
 }
 
-/** 仲裁器依赖（chat/executeTool 走 DI 优先、plugin-sdk 真实现兜底，同 RunContext 约定）。 */
+/** 仲裁器依赖：chat/executeTool 走 DI 优先、plugin-sdk 真实现兜底。 */
 export interface TaskArbitratorDeps {
   provider: Provider;
   chat?: RunContext['chat'];
   executeTool?: RunContext['executeTool'];
   signal?: AbortSignal;
-  /** 仲裁过程的人话记录（runner 在 init 返回后统一 yield warning，因 init 非 generator） */
+  /** 仲裁过程的人话记录，由调用方统一报给用户（仲裁本身不是 generator）。 */
   notes?: string[];
 }
 
 /**
- * 构建复合仲裁器（短语快路径 → LLM 单轮仲裁 → AskUserQuestion → 兜底 new）。
- * runner 在 state.init 前构建并传入；任何一级抛错都降级到下一级，绝不让仲裁本身 halt 工作流。
+ * 构建复合仲裁器。任何一级抛错都降级到下一级 —— **仲裁本身绝不 halt 工作流**。
  */
 export function buildTaskArbitrator(deps: TaskArbitratorDeps): TaskArbitrator {
   const note = (m: string): void => {
@@ -442,7 +320,6 @@ export function buildTaskArbitrator(deps: TaskArbitratorDeps): TaskArbitrator {
   };
 
   return async (actx) => {
-    // a. 延续短语快路径
     if (isContinuationPhrase(actx.newGoal)) {
       note(
         `任务仲裁：新输入「${truncate(actx.newGoal, 40)}」命中延续短语 → 继续旧任务（目标：${truncate(actx.prevGoal, 60)}）`,
@@ -450,12 +327,11 @@ export function buildTaskArbitrator(deps: TaskArbitratorDeps): TaskArbitrator {
       return 'resume';
     }
 
-    // b. LLM 单轮仲裁
     try {
       const verdict = await llmArbitrate(deps, actx);
       if (verdict !== 'unsure') {
         note(
-          `任务仲裁：LLM 判定新输入${verdict === 'resume' ? '是旧任务的延续 → 续跑' : '是全新任务 → 清理旧产物重开'}`,
+          `任务仲裁：LLM 判定新输入${verdict === 'resume' ? '是旧任务的延续 → 续跑' : '是全新任务 → 归档旧产物重开'}`,
         );
         return verdict;
       }
@@ -463,7 +339,6 @@ export function buildTaskArbitrator(deps: TaskArbitratorDeps): TaskArbitrator {
       // LLM 不可用 → 降级到提问
     }
 
-    // c. AskUserQuestion（TUI 弹界面；非交互宿主 askBridge 自动选推荐项=全新开始）
     try {
       const verdict = await askUserArbitrate(deps, actx);
       note(
@@ -474,25 +349,23 @@ export function buildTaskArbitrator(deps: TaskArbitratorDeps): TaskArbitrator {
       // 提问被取消/不可用 → 兜底
     }
 
-    // d. 兜底 = 旧红线行为（hash 不等 → new-task），最小惊讶
     note('任务仲裁：无法判定（LLM 与提问均不可用）→ 按全新任务处理');
     return 'new';
   };
 }
 
-/** LLM 单轮仲裁：旧 goal + 新输入 + 进度摘要 → {verdict, reason}。解析失败按 unsure。 */
+/** LLM 单轮仲裁 → {verdict, reason}。解析失败一律按 unsure，不猜。 */
 async function llmArbitrate(
   deps: TaskArbitratorDeps,
   actx: TaskArbitrationContext,
 ): Promise<'resume' | 'new' | 'unsure'> {
   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)}`,
     '',
@@ -507,7 +380,12 @@ async function llmArbitrate(
   for await (const ev of chatFn({
     provider: deps.provider,
     messages: [
-      { role: 'user', content: prompt, timestamp: Date.now(), id: randomUUID() },
+      {
+        role: 'user',
+        content: prompt,
+        timestamp: Date.now(),
+        id: randomUUID(),
+      },
     ],
     tools: [],
     signal: deps.signal,
@@ -528,24 +406,23 @@ async function llmArbitrate(
   return 'unsure';
 }
 
-/** 经 AskUserQuestion 问用户（推荐项=全新开始，与兜底语义一致；非交互自动按推荐项）。 */
+/** 问用户。推荐项 = 全新开始（与兜底语义一致）；非交互宿主自动按推荐项。 */
 async function askUserArbitrate(
   deps: TaskArbitratorDeps,
   actx: TaskArbitrationContext,
 ): Promise<'resume' | 'new'> {
   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: '继续上次任务',
@@ -559,28 +436,3 @@ async function askUserArbitrate(
   if (!r.ok) throw new Error(r.error);
   return r.content.includes('继续上次任务') ? 'resume' : 'new';
 }
-
-/**
- * 归一化 goal 字符串
- *
- * 规则：
- * - toLowerCase()
- * - 去除所有标点符号（保留中文、英文、数字、空格）
- * - 去除多余空格（连续空格→单空格）
- * - 首尾 trim
- * - 截断到 200 字符
- */
-function normalizeGoal(raw: string): string {
-  return (
-    raw
-      .toLowerCase()
-      // 保留中文、英文、数字、空格，去除其他字符（标点等）
-      .replace(/[^\p{L}\p{N}\s]/gu, '')
-      // 连续空格替换为单空格
-      .replace(/\s+/g, ' ')
-      // 首尾去空格
-      .trim()
-      // 截断到 200 字符
-      .slice(0, 200)
-  );
-}