argent-create-flow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

1. Overview

1. 概述

A flow is a recorded sequence of MCP tool calls saved to a

.yaml

file in the

.argent/flows/

directory. Each step is executed live as you add it, so you verify it works before it becomes part of the flow. Replay a finished flow with

flow-execute

流程是录制好的MCP工具调用序列，保存到

.argent/flows/

目录下的

.yaml

文件中。添加每个步骤时都会实时执行，因此在将其纳入流程前可验证是否可用。使用

flow-execute

回放已完成的流程。

2. Tools

2. 工具

Tool	Purpose
`flow-start-recording`	Start recording — takes a name and executionPrerequisite, creates the file
`flow-add-step`	Execute a tool call live and record it if it succeeds
`flow-add-echo`	Add a label/comment that prints during replay
`flow-finish-recording`	Stop recording and get a summary
`flow-read-prerequisite`	Read a flow's execution prerequisite without running it
`flow-execute`	Replay a saved flow by name

工具	用途
`flow-start-recording`	开始录制——需传入名称和executionPrerequisite，创建对应文件
`flow-add-step`	实时执行工具调用，成功后将其录制到流程中
`flow-add-echo`	添加标签/注释，回放时会打印该内容
`flow-finish-recording`	停止录制并返回流程摘要
`flow-read-prerequisite`	无需运行流程，即可读取其执行前置条件
`flow-execute`	通过名称回放已保存的流程

3. Workflow

3. 工作流程

Recording

录制流程

Start: Call
```
flow-start-recording
```
with a descriptive name, the absolute
```
project_root
```
, and an
```
executionPrerequisite
```
describing the required app state before running the flow (e.g. "App on home screen after a fresh reload").
```
project_root
```
is stored for the session — you do not need to pass it again to subsequent tools.
Build step-by-step: For each action, call
```
flow-add-step
```
with the tool name and args. The tool runs immediately — check the result before moving on.
Add labels: Use
```
flow-add-echo
```
between steps to describe what each section does.
Finish: Call
```
flow-finish-recording
```
to stop recording. It returns the file path where the flow was saved and a summary of all steps. You can edit the
```
.yaml
```
file directly afterwards to remove, reorder, or tweak steps.

Every tool during recording returns the current flow file contents so you can track what has been recorded.

启动录制：调用
```
flow-start-recording
```
，传入描述性名称、绝对路径
```
project_root
```
，以及描述运行流程前所需应用状态的
```
executionPrerequisite
```
（例如："应用重新加载后处于主屏幕"）。
```
project_root
```
会在会话中存储——后续工具无需再次传入该参数。
逐步构建：针对每个操作，调用
```
flow-add-step
```
并传入工具名称和参数。工具会立即运行——继续下一步前请检查执行结果。
添加标签：在步骤之间使用
```
flow-add-echo
```
描述每个环节的作用。
结束录制：调用
```
flow-finish-recording
```
停止录制。它会返回流程文件的保存路径以及所有步骤的摘要。之后你可直接编辑
```
.yaml
```
文件，删除、重新排序或调整步骤。

录制过程中每个工具都会返回当前流程文件的内容，方便你跟踪已录制的内容。

Replaying

回放流程

Call

flow-execute

with the flow name. If the flow has an execution prerequisite:

The tool returns a notice with the prerequisite text instead of running. It asks you to verify the prerequisite is met and call
```
flow-execute
```
again with
```
prerequisiteAcknowledged: true
```
.
You can also call
```
flow-read-prerequisite
```
beforehand to inspect the prerequisite without triggering a run.
Once you pass
```
prerequisiteAcknowledged: true
```
, the flow runs all steps in order and returns every tool call result (including screenshots) merged into a single response.

If the flow has no prerequisite, it runs immediately without needing acknowledgment.

调用

flow-execute

并传入流程名称。如果流程有执行前置条件：

工具会返回包含前置条件文本的提示，而非直接运行流程。它会要求你验证前置条件已满足，并再次调用
```
flow-execute
```
时传入
```
prerequisiteAcknowledged: true
```
。
你也可提前调用
```
flow-read-prerequisite
```
查看前置条件，而不会触发流程运行。
传入
```
prerequisiteAcknowledged: true
```
后，流程会按顺序运行所有步骤，并将所有工具调用结果（包括截图）合并为单个响应返回。

如果流程没有前置条件，则会立即运行，无需确认。

4. flow-add-step Usage

4. flow-add-step 使用方法

The

command

parameter is the MCP tool name. The

args

parameter is a JSON string (not an object):

command: "launch-app"
args: "{\"udid\": \"<UDID>\", \"bundleId\": \"com.apple.Preferences\"}"

command: "gesture-tap"
args: "{\"udid\": \"<UDID>\", \"x\": 0.5, \"y\": 0.35}"

command: "screenshot"
args: "{\"udid\": \"<UDID>\"}"

For tools with no arguments, omit

args

entirely.

command

参数为MCP工具名称。

args

参数是JSON字符串（而非对象）：

command: "launch-app"
args: "{\"udid\": \"<UDID>\", \"bundleId\": \"com.apple.Preferences\"}"

command: "gesture-tap"
args: "{\"udid\": \"<UDID>\", \"x\": 0.5, \"y\": 0.35}"

command: "screenshot"
args: "{\"udid\": \"<UDID>\"}"

对于无参数的工具，可完全省略

args

。

5. Important Rules

5. 重要规则

Every step runs live. You will see the real tool result (including screenshots). Use this to verify the step worked before continuing.
Only successful steps are recorded. If a tool call fails, nothing is written to the flow file — fix the issue and try again.
Pass
project_root
only to
flow-start-recording
. It is stored for the session and automatically used by all subsequent flow tools. An error is returned if the path is not absolute.
You do NOT need to pass a flow name to
```
flow-add-step
```
,
```
flow-add-echo
```
, or
```
flow-finish-recording
```
. The active flow is tracked automatically after
```
flow-start-recording
```
.
Start before adding. Calling
```
flow-add-step
```
,
```
flow-add-echo
```
, or
```
flow-finish-recording
```
without an active recording returns an error: "No active flow. Call flow-start-recording first."
One flow at a time. If you call
```
flow-start-recording
```
while already recording, the active flow switches to the new one. The response tells you which flow was abandoned and which is now active. The old flow's file remains on disk.
Mistakes can be edited out. If a step was recorded by mistake, edit the
```
.yaml
```
file directly to remove or reorder entries.

每个步骤都会实时运行。你会看到真实的工具执行结果（包括截图）。继续下一步前，请利用这一点验证步骤是否正常工作。
仅录制成功的步骤。如果工具调用失败，不会向流程文件写入任何内容——修复问题后重试即可。
仅向flow-start-recording传入project_root。该参数会在会话中存储，后续所有流程工具都会自动使用。如果路径不是绝对路径，会返回错误。
无需向flow-add-step、flow-add-echo或flow-finish-recording传入流程名称。启动录制后，系统会自动跟踪当前活跃的流程。
先启动录制再添加步骤。如果没有活跃的录制会话就调用
```
flow-add-step
```
、
```
flow-add-echo
```
或
```
flow-finish-recording
```
，会返回错误："无活跃流程。请先调用flow-start-recording。"
一次只能录制一个流程。如果在已录制的情况下调用
```
flow-start-recording
```
，活跃流程会切换为新流程。响应会告知你哪个流程被放弃，哪个成为当前活跃流程。旧流程的文件仍会保留在磁盘上。
错误可通过编辑修正。如果误录了某个步骤，可直接编辑
```
.yaml
```
文件删除或重新排序条目。

6. Example Session

6. 示例会话

flow-start-recording  { name: "open-settings", project_root: "/Users/dev/MyApp", executionPrerequisite: "Simulator booted with app installed" }
flow-add-echo  { message: "Launch Settings app" }
flow-add-step  { command: "launch-app", args: "{\"udid\": \"ABC\", \"bundleId\": \"com.apple.Preferences\"}" }
flow-add-echo  { message: "Tap General" }
flow-add-step  { command: "gesture-tap", args: "{\"udid\": \"ABC\", \"x\": 0.5, \"y\": 0.35}" }
flow-add-echo  { message: "Tap About" }
flow-add-step  { command: "gesture-tap", args: "{\"udid\": \"ABC\", \"x\": 0.5, \"y\": 0.17}" }
flow-finish-recording  {}

flow-start-recording  { name: "open-settings", project_root: "/Users/dev/MyApp", executionPrerequisite: "Simulator booted with app installed" }
flow-add-echo  { message: "Launch Settings app" }
flow-add-step  { command: "launch-app", args: "{\"udid\": \"ABC\", \"bundleId\": \"com.apple.Preferences\"}" }
flow-add-echo  { message: "Tap General" }
flow-add-step  { command: "gesture-tap", args: "{\"udid\": \"ABC\", \"x\": 0.5, \"y\": 0.35}" }
flow-add-echo  { message: "Tap About" }
flow-add-step  { command: "gesture-tap", args: "{\"udid\": \"ABC\", \"x\": 0.5, \"y\": 0.17}" }
flow-finish-recording  {}

7. Replay Example

7. 回放示例

flow-execute   { name: "open-settings", project_root: "/Users/dev/MyApp" }
→ Returns: notice with executionPrerequisite: "Simulator booted with app installed"
  "Verify the prerequisite is met and call flow-execute again with prerequisiteAcknowledged set to true."

flow-execute   { name: "open-settings", project_root: "/Users/dev/MyApp", prerequisiteAcknowledged: true }
→ Runs all steps, returns merged results with status and output for every step

flow-execute   { name: "open-settings", project_root: "/Users/dev/MyApp" }
→ 返回：包含executionPrerequisite的提示："Simulator booted with app installed"
  "Verify the prerequisite is met and call flow-execute again with prerequisiteAcknowledged set to true."

flow-execute   { name: "open-settings", project_root: "/Users/dev/MyApp", prerequisiteAcknowledged: true }
→ 运行所有步骤，返回合并后的结果，包含每个步骤的状态和输出

8. Flow File Format

8. 流程文件格式

Flow files use YAML. The top-level is an object with

executionPrerequisite

(describes required state) and

steps

(array of actions):

```
- echo: <message>
```
— a label
```
- tool: <name>
```
with optional
```
args:
```
— a tool call. Add
```
delayMs: <ms>
```
to sleep that long before the step runs (use sparingly — only when the app needs a fixed wait between actions).

Example

.yaml

file:

yaml

executionPrerequisite: Simulator booted with app installed
steps:
  - echo: Launch Settings app
  - tool: launch-app
    args:
      udid: ABC
      bundleId: com.apple.Preferences
  - echo: Tap General
  - tool: gesture-tap
    args:
      udid: ABC
      x: 0.5
      y: 0.35
  - echo: Tap About
  - tool: gesture-tap
    args:
      udid: ABC
      x: 0.5
      y: 0.17

流程文件采用YAML格式。顶层是包含

executionPrerequisite

（描述所需状态）和

steps

（操作数组）的对象：

```
- echo: <message>
```
—— 标签
```
- tool: <name>
```
可搭配可选的
```
args:
```
—— 工具调用。可添加
```
delayMs: <ms>
```
，表示在执行该步骤前等待指定时长（谨慎使用——仅当应用需要在操作间固定等待时使用）。

示例

.yaml

文件：

yaml

executionPrerequisite: Simulator booted with app installed
steps:
  - echo: Launch Settings app
  - tool: launch-app
    args:
      udid: ABC
      bundleId: com.apple.Preferences
  - echo: Tap General
  - tool: gesture-tap
    args:
      udid: ABC
      x: 0.5
      y: 0.35
  - echo: Tap About
  - tool: gesture-tap
    args:
      udid: ABC
      x: 0.5
      y: 0.17

9. When to Proactively Record a Flow

9. 主动录制流程的场景

You do not need the user to ask for a flow. Record one proactively when you recognize any of these patterns:

About to re-profile: You completed a profiling session and are about to apply a fix and re-profile. Record the interaction steps now so the re-profile replays them identically (see
```
argent-react-native-profiler
```
and
```
argent-native-profiler
```
skills).
Repeating steps: You have already performed a multi-step interaction sequence once and the task requires doing it again (comparison, retry, re-test).
Complex path discovered: You worked through a non-trivial sequence of taps/swipes/navigation to reach a desired app state. Capture it before it is lost.
User says "again" / "one more time": Any request to redo what you just did is a signal to record first, then replay.

无需用户明确要求录制流程。当识别到以下模式时，可主动录制：

即将重新分析性能：你已完成一次性能分析会话，即将应用修复并重新分析。立即录制交互步骤，以便重新分析时能完全一致地回放（参考
```
argent-react-native-profiler
```
和
```
argent-native-profiler
```
技能）。
重复执行步骤：你已执行过一次多步交互序列，而任务要求再次执行（对比、重试、重新测试）。
发现复杂路径：你通过一系列非 trivial 的点击/滑动/导航操作才到达所需的应用状态。在遗忘前将其记录下来。
用户要求“再做一次”：任何要求重复刚完成操作的请求，都是先录制再回放的信号。

10. Flow Self-Improvement

10. 流程自我优化

Flows break. UI layouts change, coordinates drift, screens get added or removed. When

flow-execute

returns a failure, follow this procedure to diagnose and fix the flow instead of silently re-recording or giving up.

流程可能会失效。UI布局变化、坐标偏移、新增或移除屏幕等情况都可能导致流程失败。当

flow-execute

返回失败时，请遵循以下步骤诊断并修复流程，而非静默重新录制或直接放弃。

10.1 Classify the Result

10.1 结果分类

After every

flow-execute

, classify the outcome before proceeding:

Outcome	Signal	Action
Success	All steps completed, final screenshot shows expected state	Continue with task
Hard error	A step has `ERROR` in the result — engine stopped there	Enter §10.2
Silent misfire	All steps completed but final screenshot shows wrong screen	Enter §10.2
Partial divergence	Intermediate screenshot shows wrong state even though later steps ran	Enter §10.2

For silent misfires and partial divergence, echo annotations (§10.5) are your reference for what each screen should look like.

每次执行

flow-execute

后，先对结果分类再继续：

结果类型	信号	操作
成功	所有步骤完成，最终截图显示预期状态	继续执行任务
硬错误	某个步骤结果中包含 `ERROR` ——引擎在此处停止运行	进入§10.2
静默失效	所有步骤完成，但最终截图显示错误的屏幕	进入§10.2
部分偏离	中间截图显示错误状态，但后续步骤仍继续运行	进入§10.2

对于静默失效和部分偏离情况，echo注释（§10.5）可作为参考，告诉你每个屏幕应该是什么样子。

10.2 Diagnose

10.2 诊断

Note the failure step index and error message (if hard error).
Call
```
screenshot
```
to see where the app actually is now.
Call
```
describe
```
or
```
debugger-component-tree
```
to get the current element tree.
Compare current state to what the failed step expected. Classify the root cause:

Root cause	Symptoms
Coordinate drift	Tap succeeded but hit wrong element; elements shifted positions
Missing element	Target element not present in element tree
Wrong screen	Screenshot shows entirely different page than expected
Timing	Element exists in tree but tap missed; loading spinner visible
State mismatch	First step fails — executionPrerequisite was not actually met

State the diagnosis in one sentence before attempting any correction.

记录失败步骤的索引和错误信息（如果是硬错误）。
调用
```
screenshot
```
查看应用当前的实际状态。
调用
```
describe
```
或
```
debugger-component-tree
```
获取当前元素树。
将当前状态与失败步骤的预期状态对比，分类根本原因：

根本原因	症状
坐标偏移	点击成功但命中错误元素；元素位置发生偏移
元素缺失	目标元素不在元素树中
屏幕错误	截图显示的页面与预期完全不同
时序问题	元素存在于树中但点击未命中；加载 spinner 可见
状态不匹配	第一步失败——实际未满足executionPrerequisite

在尝试任何修复前，用一句话说明诊断结果。

10.3 Correct

10.3 修复

Choose the lightest strategy that fits:

Strategy 1 — Edit the YAML (coordinate drift, parameter changes). Read

.argent/flows/<flow-name>.yaml

, update the broken step's

bundleId

text

, or other args. Re-run

flow-execute

to verify.

Strategy 2 — Manual recovery + continue (timing/transient issues, one-off replay). Manually execute the failed step with corrected coordinates from §10.2 discovery, then manually execute remaining steps. Does not fix the YAML — use only when re-recording is not worth it.

Strategy 3 — Re-record from failure point (structural changes, new intermediate screens). Navigate the app to the state just before the failure point. Call

flow-start-recording

with the same flow name (overwrites). Re-add the working prefix steps via

flow-add-step

, then continue recording new steps from the divergence point. Call

flow-finish-recording

Strategy 4 — Full re-record (major changes, unclear diagnosis, or 3+ broken steps). Reset the app to prerequisite state (

restart-app

launch-app

). Record from scratch with the same flow name.

Decision heuristic:

1 step broken, parameter-only change → Strategy 1
1 step broken, transient issue, not worth persisting → Strategy 2
2–3 steps broken or flow structure partially changed → Strategy 3
3+ steps broken, or unclear root cause → Strategy 4
Flow used for profiling comparison (must be identical) → Strategy 4

选择最适合的最轻量策略：

策略1——编辑YAML（坐标偏移、参数变更）。读取

.argent/flows/<flow-name>.yaml

，更新失败步骤的

、

bundleId

、

text

或其他参数。重新运行

flow-execute

验证。

策略2——手动恢复并继续（时序/临时问题、一次性回放）。根据§10.2的发现，手动执行修正后的失败步骤，然后手动执行剩余步骤。此策略不会修复YAML——仅在不值得重新录制时使用。

策略3——从失败点重新录制（结构变更、新增中间屏幕）。将导航到失败点之前的应用状态。调用

flow-start-recording

并传入相同的流程名称（会覆盖原文件）。通过

flow-add-step

重新添加正常的前置步骤，然后从偏离点继续录制新步骤。调用

flow-finish-recording

。

策略4——完全重新录制（重大变更、诊断不明确、或3个以上步骤失效）。将应用重置到前置条件状态（

restart-app

launch-app

）。使用相同的流程名称从头开始录制。

决策准则：

仅1个步骤失效，仅需变更参数 → 策略1
仅1个步骤失效，临时问题，不值得持久化修复 → 策略2
2-3个步骤失效或流程结构部分变更 → 策略3
3个以上步骤失效，或根本原因不明确 → 策略4
用于性能分析对比的流程（必须完全一致） → 策略4

10.4 Verify and Bound Retries

10.4 验证并限制重试次数

After applying a correction, re-run

flow-execute

to verify.

If it succeeds → done. Report what changed (e.g. "Fixed step 4: updated tap coordinates from 0.5,0.35 to 0.5,0.42").
If it fails at a different step → return to §10.2 for a second attempt.
If this is already the second correction attempt → stop. Report the diagnosis to the user and recommend a full re-record or manual investigation.

Hard cap: 2 correction cycles. Do not enter an unbounded fix loop.

应用修复后，重新运行

flow-execute

验证。

如果成功 → 完成。报告变更内容（例如："修复步骤4：将点击坐标从0.5,0.35更新为0.5,0.42"）。
如果在不同步骤失败 → 返回§10.2进行第二次尝试。
如果已经是第二次修复尝试 → 停止。向用户报告诊断结果，并建议完全重新录制或手动排查。

硬限制：最多2次修复循环。不要进入无限修复循环。

10.5 Making Flows Resilient

10.5 提升流程韧性

Apply these when recording new flows to reduce future breakage:

Echo expected state, not just actions. Write
```
"On Settings > General screen, about to tap About"
```
not
```
"Tap About"
```
. During diagnosis these tell you what the screen should look like.
Add screenshot steps after critical navigation. Insert
```
screenshot
```
steps after screen transitions. These produce images in the flow result you can inspect during diagnosis.

Write specific executionPrerequisites.

"App on home tab, user logged in, simulator UDID is <X>"

— not

"App running"

. Verify with

screenshot

describe

before acknowledging.

Prefer launch-app / open-url over navigation chains. Deep links are more resilient to layout changes than tap sequences.
Echo accessibility labels for coordinate taps. When recording a tap, add an echo with the target's label or testID:
```
"Tapping 'Submit' button (testID: submit-btn) at 0.5, 0.82"
```
. During repair, use
```
describe
```
to find the element by label and update coordinates. Only use
```
screenshot
```
for permission or system overlays when
```
describe
```
cannot expose the target reliably.

录制新流程时应用以下方法，减少未来失效的可能性：

Echo预期状态，而非仅操作。编写"在设置>通用屏幕，即将点击关于"而非"点击关于"。诊断时这些注释会告诉你屏幕应该是什么样子。
关键导航后添加截图步骤。在屏幕切换后插入
```
screenshot
```
步骤。这些步骤会在流程结果中生成图片，方便你在诊断时查看。
编写具体的executionPrerequisites。例如"应用处于首页标签，用户已登录，模拟器UDID为<X>"——而非"应用正在运行"。确认前用
```
screenshot
```
+
```
describe
```
验证。
优先使用launch-app / open-url而非导航链。深度链接比点击序列更能抵御布局变更。
为坐标点击添加Echo可访问性标签。录制点击操作时，添加包含目标标签或testID的echo："点击'提交'按钮（testID: submit-btn），坐标0.5, 0.82"。修复时，使用
```
describe
```
通过标签查找元素并更新坐标。仅当
```
describe
```
无法可靠识别目标时（如权限或系统弹窗），才使用
```
screenshot
```
。