minimal-agent 0.12.0 → 0.14.0

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

@@ -1,203 +1,266 @@
-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 type { Provider } from '../../../src/plugin-sdk.js';
-import { truncate } from './agentCommon.js';
 import { extractJsonPayload } from './jsonPayload.js';
-import type { RunContext } from './types.js';
+import type { InputDef, RunContext } from './types.js';
+import { truncate } from './util.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 前缀整体清理）。 */
+/** 工作流状态目录的父目录名（落在 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: string): string {
+  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: string): string {
   return name.replace(/[^\w.-]/g, '-');
 }
 
-/** 某 workflow 的状态目录绝对路径。workflowState / taskIdentity 共用唯一权威实现。 */
-export function workflowStateDir(workingDir: string, workflowName: string): string {
-  return join(workingDir, WF_STATE_PARENT, 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),
+  );
+}
+
+/**
+ * 一个具体任务实例的状态目录。
+ * 成功后改名 `<taskId>.done/`；产物淘汰归档到 `<taskId>.trash/`。
+ */
+export function taskInstanceDir(
+  workingDir: string,
+  workflowName: string,
+  sessionId: string,
+  taskId: string,
+): string {
+  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。
+ * 任务身份 = 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: string,
   inputs: Record<string, unknown>,
-  workingDir?: 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. 尝试读取旧状态文件（按 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) 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',
-    };
-  }
+  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'>;
@@ -223,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 => {
@@ -261,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)}）`,
@@ -269,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;
       }
@@ -282,7 +339,6 @@ export function buildTaskArbitrator(deps: TaskArbitratorDeps): TaskArbitrator {
       // LLM 不可用 → 降级到提问
     }
 
-    // c. AskUserQuestion（TUI 弹界面；非交互宿主 askBridge 自动选推荐项=全新开始）
     try {
       const verdict = await askUserArbitrate(deps, actx);
       note(
@@ -293,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)}`,
     '',
@@ -326,7 +380,12 @@ async function llmArbitrate(
   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,
@@ -347,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: '继续上次任务',
@@ -378,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)
-  );
-}

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

@@ -1,12 +1,33 @@
 /**
- * The workflow identity stays anchored to the registered workspace, while file
- * and process tools follow a session worktree as soon as EnterWorktree creates
- * one. Keeping this decision in one helper prevents executors from drifting.
+ * ============================================================
+ *  plugins/workflow-runner/src/toolRuntime.ts —— 工具调用的运行上下文
+ * ------------------------------------------------------------
+ *  宿主能力由每次工具调用的显式 `uses` 数组收敛 ——
+ *  代码形态里没有「step」这个东西，宿主能力由调用点在 `tool()`/`agent()` 的
+ *  选项里显式声明。
+ *
+ *  ⚠️ `effectiveWorkflowCwd` 是**红线级**的单一出处，别在别处再算一次：
+ *  会话可能在运行途中进入 worktree（模型可自主调 EnterWorktree），此后写文件的
+ *  工具跟着 worktree 走。验收侧（verify/exists/readJson）必须用**同一个**函数取 cwd，
+ *  否则就是「产物写进 worktree、验收去原工作区的空目录里找」——条件恒 false，
+ *  引擎反复重试后莫名失败，而产物其实好好躺在 worktree 里。
+ *
+ *  也正因为 worktree 是**运行途中**才进入的，取 cwd 必须在**每次调用时**现算，
+ *  不能在运行开始时快照一次存起来。
+ * ============================================================
  */
+/** 当前有效工作目录 —— 进了 worktree 就跟着走。见文件头注的红线说明。 */
 export function effectiveWorkflowCwd(ctx) {
     return ctx.sessionState?.activeWorktree?.path ?? ctx.cwd;
 }
-export function buildWorkflowToolContext(step, ctx, toolCallId, reportProgress) {
+/**
+ * 组装一次工具调用的 ToolCallContext。
+ *
+ * @param uses 本次调用显式声明需要的宿主能力；缺省表示不需要任何授权切片。
+ * @returns 成功返回上下文；宿主没提供所声明的能力时返回 `{ error }`（不抛，
+ *          让调用方把原因当 tool_result 回填给模型）。
+ */
+export function buildWorkflowToolContext(ctx, toolCallId, reportProgress, uses) {
     const context = {
         ...ctx.toolContext,
         history: ctx.history,
@@ -21,12 +42,12 @@ export function buildWorkflowToolContext(step, ctx, toolCallId, reportProgress)
         toolCallId,
         reportProgress,
     };
-    for (const capability of step.uses ?? []) {
+    for (const capability of uses ?? []) {
         if (capability === 'computer') {
             if (!ctx.host?.computerRun) {
                 return {
-                    error: 'uses:[computer] 声明了需要电脑操控能力，但本次运行的宿主没有提供 —— ' +
-                        '请在支持 Computer Use 的宿主启动，或去掉该步的 uses 声明。',
+                    error: "声明了 uses:['computer']（需要电脑操控能力），但本次运行的宿主没有提供 —— " +
+                        '请在支持 Computer Use 的宿主里启动，或去掉该声明。',
                 };
             }
             context.computerRun = ctx.host.computerRun;
@@ -38,7 +59,7 @@ export function buildWorkflowToolContext(step, ctx, toolCallId, reportProgress)
         if (capability === 'browser') {
             if (!ctx.host?.browserRun) {
                 return {
-                    error: 'uses:[browser] 声明了需要浏览器授权上下文，但本次运行的宿主没有提供。',
+                    error: "声明了 uses:['browser']（需要浏览器授权上下文），但本次运行的宿主没有提供。",
                 };
             }
             context.browserRun = ctx.host.browserRun;