Disable runtime YAML result interpolation; apply env-var interpolation before execution and update docs/tests (#2577)

* fix(core): remove yaml runtime result interpolation

* docs(site): simplify yaml result name docs

Author: yuyutaotao

apps/site/docs/en/automate-with-scripts-in-yaml.mdx

@@ -544,26 +544,21 @@ tasks:
       # ...
 ```
 
-#### Reuse Step Results
+#### Step Result Names
 
-Steps that write a result with `name` can be referenced by later steps in the same YAML run. Use `$name` when the whole field should be replaced by the stored value.
+Steps that write a result with `name` save that value into the YAML run result and the JSON output. Use `name` to label values that should appear in the run output.
 
 ```yaml
 tasks:
-  - name: Search by extracted data
+  - name: Save extracted data
     flow:
       - aiString: Get the product id shown on the page
         name: product_id
 
-      - aiInput: Search box
-        value: $product_id
-
       - aiQuery: Get the search result after submitting the product id
         name: search_result
 ```
 
-`$name` keeps the original result type when the referenced value is used as the whole field. Runtime interpolation with `${name}` is also supported inside longer strings; non-string values are serialized as JSON before interpolation. Referencing an undefined variable throws an error.
-
 #### Upload Files With `aiTap`
 
 When clicking a button opens a file chooser, you can set `fileChooserAccept` directly on the `aiTap` step. It accepts either a single path or an array of paths.

apps/site/docs/en/changelog.mdx

@@ -1,12 +1,11 @@
 # Changelog
 
-## v1.8 - YAML Variables, Device Integrations & Model Behavior Updates
+## v1.8 - YAML Workflow, Device Integrations & Model Behavior Updates
 
-v1.8 adds YAML result reuse, refines model reasoning defaults, and brings new device/platform integration options.
+v1.8 refines model reasoning defaults and brings new device/platform integration options.
 
 ### YAML Workflow Enhancements
 
-- YAML steps with `name` can be reused in later steps through `$name` and `${name}`. See: [Automate with Scripts in YAML](./automate-with-scripts-in-yaml#reuse-step-results)
 - Android `runAdbShell` now accepts a `timeout` option in both the JavaScript API and YAML scripts. See: [Android API](./android-api-reference), [Automate with Scripts in YAML](./automate-with-scripts-in-yaml)
 
 ### Device and Platform Integrations

apps/site/docs/en/yaml-script-runner.mdx

@@ -124,7 +124,7 @@ The CLI prints execution progress and generates a visual report when it finishes
 
 ### Use environment variables in `.yaml`
 
-Reference environment variables in your scripts with `${variable-name}`.
+Reference environment variables in your scripts with `${variable-name}`. Environment-variable interpolation is applied before YAML task execution, including task strings.
 
 ```ini filename=.env
 topic=weather today

apps/site/docs/zh/automate-with-scripts-in-yaml.mdx

@@ -551,26 +551,21 @@ tasks:
       # ...
 ```
 
-#### 复用步骤结果
+#### 步骤结果名称
 
-带有 `name` 的步骤会把结果写入当前 YAML 运行的结果中，后续步骤可以引用这些结果。整个字段都需要替换成结果值时，使用 `$name`。
+带有 `name` 的步骤会把结果写入当前 YAML 运行结果和 JSON 输出中。使用 `name` 标记需要出现在运行结果里的值。
 
 ```yaml
 tasks:
-  - name: 使用提取结果搜索
+  - name: 保存提取结果
     flow:
       - aiString: 读取页面中的商品 id
         name: product_id
 
-      - aiInput: 搜索框
-        value: $product_id
-
       - aiQuery: 提交商品 id 后，获取搜索结果
         name: search_result
 ```
 
-当 `$name` 作为整个字段使用时，会保留原始结果类型。运行时也支持在更长的字符串中使用 `${name}` 插值；如果结果不是字符串，会先序列化为 JSON 再插入。引用未定义的变量会抛出错误。
-
 #### 使用 `aiTap` 上传文件
 
 当点击某个按钮会弹出文件选择器时，可以在 `aiTap` 步骤上直接设置 `fileChooserAccept`。它支持单个路径，也支持路径数组。

apps/site/docs/zh/changelog.mdx

@@ -1,12 +1,11 @@
 # 更新日志
 
-## v1.8 - YAML 变量复用、设备集成与模型行为更新
+## v1.8 - YAML 工作流、设备集成与模型行为更新
 
-v1.8 版本新增 YAML 步骤结果复用能力，调整模型思考模式默认行为，并补充了多项设备与平台集成能力。
+v1.8 版本调整模型思考模式默认行为，并补充了多项设备与平台集成能力。
 
 ### YAML 工作流增强
 
-- 带有 `name` 的 YAML 步骤可以在后续步骤中通过 `$name` 和 `${name}` 复用结果。详见：[YAML 脚本自动化](./automate-with-scripts-in-yaml#复用步骤结果)
 - Android `runAdbShell` 在 JavaScript API 和 YAML 脚本中都支持 `timeout` 选项。详见：[Android API](./android-api-reference)、[YAML 脚本自动化](./automate-with-scripts-in-yaml)
 
 ### 设备与平台集成

apps/site/docs/zh/yaml-script-runner.mdx

@@ -127,7 +127,7 @@ npx midscene ./bing-search.yaml
 
 ### 在 `.yaml` 中使用环境变量来填入动态值
 
-脚本中可以通过 `${variable-name}` 引用环境变量。
+脚本中可以通过 `${variable-name}` 引用环境变量。环境变量会在 YAML 任务执行前完成替换，包括任务正文中的字符串。
 
 ```ini filename=.env
 topic=weather today

packages/core/src/yaml/player.ts

@@ -61,28 +61,6 @@ import {
 
 const debug = getDebug('yaml-player');
 
-const VARIABLE_FULL_MATCH_RE = /^\$([a-zA-Z_][a-zA-Z0-9_]*)$/;
-const VARIABLE_EMBEDDED_RE = /\$\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
-
-function deepTransform(
-  value: unknown,
-  transform: (val: unknown) => unknown,
-): unknown {
-  if (Array.isArray(value)) {
-    return value.map((item) => deepTransform(item, transform));
-  }
-
-  if (value !== null && typeof value === 'object') {
-    const result: Record<string, unknown> = {};
-    for (const [key, val] of Object.entries(value)) {
-      result[key] = deepTransform(val, transform);
-    }
-    return result;
-  }
-
-  return transform(value);
-}
-
 const aiTaskHandlerMap = {
   aiQuery: 'aiQuery',
   aiNumber: 'aiNumber',
@@ -307,43 +285,14 @@ export class ScriptPlayer<T extends MidsceneYamlScriptEnv> {
     }
   }
 
-  private resolveVariables(value: unknown): unknown {
-    return deepTransform(value, (val) => {
-      if (typeof val !== 'string') {
-        return val;
-      }
-
-      const fullMatch = val.match(VARIABLE_FULL_MATCH_RE);
-      if (fullMatch) {
-        const varName = fullMatch[1];
-        if (!(varName in this.result)) {
-          throw new Error(`Variable "${varName}" is not defined`);
-        }
-        return this.result[varName];
-      }
-
-      return val.replace(VARIABLE_EMBEDDED_RE, (_, varName) => {
-        if (!(varName in this.result)) {
-          throw new Error(`Variable "${varName}" is not defined`);
-        }
-        const replacement = this.result[varName];
-        return typeof replacement === 'string'
-          ? replacement
-          : JSON.stringify(replacement);
-      });
-    });
-  }
-
   async playTask(taskStatus: ScriptPlayerTaskStatus, agent: Agent) {
     const { flow } = taskStatus;
     assert(flow, 'missing flow in task');
 
     for (const flowItemIndex in flow) {
       const currentStep = Number.parseInt(flowItemIndex, 10);
       taskStatus.currentStep = currentStep;
-      const flowItem = this.resolveVariables(
-        flow[flowItemIndex],
-      ) as RuntimeYamlFlowItem;
+      const flowItem = flow[flowItemIndex] as RuntimeYamlFlowItem;
       const flowItemRecord = flowItem as Record<string, unknown>;
 
       // Skip Finalize action from cache - it's a planning-only marker

packages/core/tests/unit-test/player-action-dispatch.test.ts

@@ -351,8 +351,8 @@ describe('player action dispatch ordering', () => {
     });
   });
 
-  describe('player variable interpolation', () => {
-    it('should replace $var with stored result value', async () => {
+  describe('player task dispatch without runtime result interpolation', () => {
+    it('should pass $var text through as a literal value', async () => {
       const player = createPlayerWithActionSpace([]);
       const agent = createMockAgent();
       player.result.product_id = '110';
@@ -369,32 +369,11 @@ describe('player action dispatch ordering', () => {
 
       expect(agent.callActionInActionSpace).toHaveBeenCalledWith(
         'Input',
-        expect.objectContaining({ value: '110' }),
+        expect.objectContaining({ value: '$product_id' }),
       );
     });
 
-    it('should preserve non-string types for $var replacement', async () => {
-      const player = createPlayerWithActionSpace([]);
-      const agent = createMockAgent();
-      player.result.count = 42;
-
-      const taskStatus = {
-        name: 'test',
-        flow: [{ aiInput: 'qty field', value: '$count' }],
-        index: 0,
-        status: 'running' as const,
-        totalSteps: 1,
-      };
-
-      await player.playTask(taskStatus, agent);
-
-      expect(agent.callActionInActionSpace).toHaveBeenCalledWith(
-        'Input',
-        expect.objectContaining({ value: '42' }),
-      );
-    });
-
-    it('should interpolate ${var} inside strings', async () => {
+    it('should pass ${var} text through as a literal value', async () => {
       const player = createPlayerWithActionSpace([]);
       const agent = createMockAgent({
         aiQuery: vi.fn().mockResolvedValue('query-result'),
@@ -412,12 +391,12 @@ describe('player action dispatch ordering', () => {
       await player.playTask(taskStatus, agent);
 
       expect(agent.aiQuery).toHaveBeenCalledWith(
-        'search for product-110',
+        'search for product-${product_id}',
         expect.anything(),
       );
     });
 
-    it('should throw when referencing undefined variable', async () => {
+    it('should not throw when a literal variable-like value is undefined', async () => {
       const player = createPlayerWithActionSpace([]);
       const agent = createMockAgent();
 
@@ -429,12 +408,15 @@ describe('player action dispatch ordering', () => {
         totalSteps: 1,
       };
 
-      await expect(player.playTask(taskStatus, agent)).rejects.toThrow(
-        'Variable "undefined_var" is not defined',
+      await player.playTask(taskStatus, agent);
+
+      expect(agent.callActionInActionSpace).toHaveBeenCalledWith(
+        'Input',
+        expect.objectContaining({ value: '$undefined_var' }),
       );
     });
 
-    it('should replace variables in nested objects', async () => {
+    it('should pass variable-like values through in nested objects', async () => {
       const player = createPlayerWithActionSpace([]);
       const agent = createMockAgent({
         aiTap: vi.fn().mockResolvedValue('tap-result'),
@@ -455,7 +437,10 @@ describe('player action dispatch ordering', () => {
 
       await player.playTask(taskStatus, agent);
 
-      expect(agent.aiTap).toHaveBeenCalledWith('search box', expect.anything());
+      expect(agent.aiTap).toHaveBeenCalledWith(
+        '$prompt_text',
+        expect.anything(),
+      );
     });
   });
 

packages/core/tests/unit-test/yaml-doc-usage.test.ts

@@ -51,6 +51,7 @@ describe('YAML docs usage coverage', () => {
     Reflect.deleteProperty(process.env, 'DOC_HOST');
     Reflect.deleteProperty(process.env, 'DOC_TOPIC');
     Reflect.deleteProperty(process.env, 'DOC_WIDTH');
+    Reflect.deleteProperty(process.env, 'product_id');
   });
 
   it('parses the documented environment and agent sections', () => {
@@ -328,7 +329,7 @@ tasks:
     );
   });
 
-  it('supports documented result reuse with full-field and embedded interpolation', async () => {
+  it('keeps named step results in output', async () => {
     const script = parseYamlScript(`
 web:
   url: about:blank
@@ -352,7 +353,7 @@ tasks:
 
     expect(player.status).toBe('done');
     expect(agent.callActionInActionSpace).toHaveBeenCalledWith('Input', {
-      value: 'SKU-123',
+      value: '$product_id',
       locate: {
         prompt: 'Search box',
         deepLocate: false,
@@ -361,9 +362,14 @@ tasks:
       },
     });
     expect(agent.aiQuery).toHaveBeenCalledWith(
-      'Get search results after submitting product id SKU-123',
+      'Get search results after submitting product id ${product_id}',
       {},
     );
+    expect(player.result.product_id).toBe('SKU-123');
+    expect(player.result.search_result).toEqual({
+      id: 'SKU-123',
+      title: 'doc item',
+    });
   });
 
   it('continues to the next task when documented task continueOnError is enabled', async () => {
@@ -469,7 +475,7 @@ tasks:
     );
   });
 
-  it('keeps runtime result interpolation in tasks without hiding missing env vars in config', () => {
+  it('keeps unresolved task environment-variable references literal without hiding missing env vars in config', () => {
     expect(() =>
       parseYamlScript(`
 web:
@@ -485,7 +491,7 @@ tasks:
 web:
   url: about:blank
 tasks:
-  - name: Runtime interpolation
+  - name: Literal task reference
     flow:
       - aiString: Read the product id
         name: product_id
@@ -511,7 +517,7 @@ web:
 agent:
   generateReport: \${DOC_ENABLED}
 tasks:
-  - name: Runtime interpolation
+  - name: Environment interpolation
     flow:
       - ai: Search for \${DOC_TOPIC}
       - aiQuery: Search for \${product_id}
@@ -529,6 +535,47 @@ tasks:
     });
   });
 
+  it('interpolates environment variables in task strings before execution', async () => {
+    process.env.product_id = 'ENV-123';
+
+    const script = parseYamlScript(`
+web:
+  url: about:blank
+tasks:
+  - name: Environment interpolation conflict
+    flow:
+      - aiString: Read the product id
+        name: product_id
+      - aiQuery: Search for \${product_id}
+        name: result
+`);
+
+    expect(script.tasks[0].flow[1]).toMatchObject({
+      aiQuery: 'Search for ENV-123',
+    });
+
+    const agent = createDocAgent({
+      aiString: vi.fn(async () => 'RUNTIME-123'),
+      aiQuery: vi.fn(async () => 'search-result'),
+    });
+    const player = new ScriptPlayer(
+      script,
+      async () => ({ agent, freeFn: [] }),
+      undefined,
+    );
+
+    await player.playTask(
+      {
+        ...script.tasks[0],
+        status: 'running',
+        totalSteps: script.tasks[0].flow.length,
+      },
+      agent,
+    );
+
+    expect(agent.aiQuery).toHaveBeenCalledWith('Search for ENV-123', {});
+  });
+
   it('preserves YAML scalar semantics when interpolating config environment variables', () => {
     process.env.DOC_ENABLED = 'true';
     process.env.DOC_WIDTH = '1280';
@@ -542,7 +589,7 @@ web:
 agent:
   generateReport: ${docEnabledRef}
 tasks:
-  - name: Runtime interpolation
+  - name: Environment interpolation
     flow:
       - aiQuery: Search for ${docEnabledRef}
 `);