magicpay

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MagicPay is your gateway to the agentic economy. It gives an AI agent one unified balance that users top up and spend through supported agent-native and traditional payment rails: x402, crypto transfers, MagicCard/card payments, and online checkout. MagicPay handles supported provider inventory, conversion, and settlement behind the scenes instead of making users manage a separate wallet or network balance per payment. Protected payment and identity details stay outside chat and the model prompt. The agent asks the user to approve the exact consequential action; approval is permission, and success requires confirmed terminal settlement. Memory

plan-fill

and

apply-fill

bring approved saved values to forms without exposing raw values.

Terms are fixed: request means a user-owned wait state; approval means permission for one consequential action; field means a page input; session means a product-level run; workflow means an ordered procedure. Exact names stay unchanged.

For open-ended purchase or booking discovery, default to MagicSearch. Use a safe alternative only when unavailable, blocked, or empty. For ordinary navigation, use the owner of the bound browser; switch only when it cannot continue.

For failures, use the statuses reference and its troubleshooting table. Unfamiliar terms (

itemRef

fieldRef

targetRef

session_stop

, etc.) are defined in their references.

MagicPay 是您通往Agent经济生态的入口。它为AI Agent提供统一余额，用户可通过支持Agent原生及传统的支付渠道进行充值与消费：x402、加密货币转账、MagicCard/银行卡支付以及在线结账。MagicPay 在后台处理支持的供应商库存、兑换与结算，无需用户为每种支付方式单独管理钱包或网络余额。受保护的支付与身份信息不会出现在聊天内容或模型提示词中。Agent会请求用户批准具体的关键操作；批准即代表授权，操作成功需以最终确认结算为准。Memory 的

plan-fill

和

apply-fill

可将已批准的保存值填入表单，且不会暴露原始数据。

术语定义固定：request指用户侧的等待状态；approval指对单个关键操作的授权；field指页面输入框；session指产品级运行实例；workflow指有序流程。术语名称保持不变。

对于开放式采购或预订的发现环节，默认使用MagicSearch。仅当MagicSearch不可用、被拦截或返回空结果时，才使用安全替代方案。对于常规导航，使用绑定浏览器的原生控制能力；仅当原生控制无法继续时才切换方案。

若出现失败情况，参考状态码及故障排除表格。不熟悉的术语（如

itemRef

、

fieldRef

、

targetRef

、

session_stop

等）可查阅相关参考文档。

References

参考文档

Open an extra reference only when it helps:

references/commands.md
references/guardrails.md
references/payment-operations.md
references/setup.md
references/statuses.md
references/workflow.md

仅在需要时打开额外参考文档：

references/commands.md
references/guardrails.md
references/payment-operations.md
references/setup.md
references/statuses.md
references/workflow.md

Native Payment Operations

原生支付操作

For exact balances, funding, crypto sends, x402 resources, status, results, or reconciliation, follow references/payment-operations.md. Keep one session, idempotency key, and operation; approval is permission, reservation is in flight, and only

completed

is settlement.

如需查询精准余额、资金充值、加密货币转账、x402资源、状态、结果或对账，请遵循references/payment-operations.md的指引。保持单一会话、幂等键及操作；批准即代表授权，预订代表处理中，仅

completed

状态表示结算完成。

Core Flow

核心流程

After

magicpay plan-fill

, execute its exact returned

applyCommand

A known x402 resource URL uses Native Payment Operations: skip MagicSearch and never launch, attach, or commit a browser; bind

x402-purchase

to one payment intent session instead. Contract with a usable destination that is ordinary non-x402:

status → start-session → (launch [url] | attach <cdp-url>) → plan-fill → returned applyCommand → [typed approval] → end-session

. For a purchase or booking intent with no usable destination, run

magicsearch query

; keep currency inside the refined prompt and never add

--currency

. Resolve any actual purchase choice before

magicpay start-session

; use the selected URL in the product workflow. Retain the workflow's active-session exception for

magicsearch discover

provider execution. For other MagicPay work, do not invoke MagicSearch; run

magicpay start-session

before browser preparation. Page work between MagicPay steps stays with the page-control owner.

执行

magicpay plan-fill

后，严格执行其返回的

applyCommand

。

已知的x402资源URL需使用原生支付操作：跳过MagicSearch，绝不启动、绑定或提交浏览器；将

x402-purchase

绑定到单个支付意向会话即可。对于普通非x402的可用目标，遵循流程：

status → start-session → (launch [url] | attach <cdp-url>) → plan-fill → 返回的applyCommand → [类型化审批] → end-session

。对于无可用目标的采购或预订意向，执行

magicsearch query

；将货币信息包含在优化后的提示词中，切勿添加

--currency

参数。在执行

magicpay start-session

前确定最终采购选择；在产品工作流中使用选定的URL。保留

magicsearch discover

供应商执行的活动会话例外规则。对于其他MagicPay操作，请勿调用MagicSearch；在浏览器准备前执行

magicpay start-session

。 MagicPay步骤之间的页面操作由页面控制所有者负责。

1. Preflight

1. 预检

Preflight with

magicpay status

. If it reports a missing key, a

cliUpdate

, or still fails after

init

(in which case run

magicpay doctor

), follow the recovery rules in the workflow reference.

magicpay status

reports the CLI is not configured, read the setup reference and complete setup first.

For an explicitly selected branch or preview project, also run

magicpay doctor

before starting a session. Compare the

status

doctor

API URL and doctor executable/build provenance with the requested project and local build; a matching package version alone is insufficient. If either does not match, do not start the protected workflow—repair the profile or installation first.

执行

magicpay status

进行预检。若报告密钥缺失、需要

cliUpdate

，或执行

init

后仍失败（此时需执行

magicpay doctor

），请遵循工作流参考文档中的恢复规则。

若

magicpay status

报告CLI未配置，请阅读设置参考文档并先完成配置。

对于明确选定的分支或预览项目，在启动会话前也需执行

magicpay doctor

。将

status

doctor

的API URL及doctor可执行文件/构建来源与请求的项目及本地构建进行对比；仅包版本匹配并不足够。若任意一项不匹配，请勿启动受保护的工作流——先修复配置文件或安装环境。

2. Start the product workflow

2. 启动产品工作流

With a known x402 resource URL, follow Native Payment Operations without MagicSearch or a browser. With a usable checkout or booking URL that is ordinary non-x402, skip MagicSearch and run

magicpay start-session [name]

directly. For a purchase or booking intent with no usable destination, follow Purchase Discovery With MagicSearch first; keep currency inside the refined prompt and never add

--currency

. Its provider-execution exception explains when

magicsearch discover

needs an active session. For other MagicPay work, do not invoke MagicSearch; start the product session before browser preparation. Starting the product workflow creates its session and telemetry root before any browser child is required.

对于已知的x402资源URL，遵循原生支付操作，无需使用MagicSearch或浏览器。对于普通非x402的可用结账或预订URL，跳过MagicSearch，直接执行

magicpay start-session [name]

。对于无可用目标的采购或预订意向，先通过MagicSearch进行采购发现；将货币信息包含在优化后的提示词中，切勿添加

--currency

参数。其供应商执行例外规则说明了

magicsearch discover

何时需要活动会话。对于其他MagicPay操作，请勿调用MagicSearch；在浏览器准备前启动产品会话。启动产品工作流会先创建会话及遥测根节点，之后才会需要浏览器子进程。

3. Bind a browser (optional)

3. 绑定浏览器（可选）

Bind a browser inside the active product workflow:

run
```
magicpay launch [url]
```
when the flow has not started in a browser yet; the new child is the browser for the whole flow, and the
```
launch
```
result includes the child's
```
cdpUrl
```
so a page-control tool can drive the same browser (for example
```
magicbrowse attach <cdpUrl>
```
);
run
```
magicpay attach <cdp-url>
```
when the page was already prepared in a CDP-reachable browser: your own page-control session, or a private browser the user approved for this task.
```
launch
```
cannot adopt a page prepared elsewhere; if that already-open page is not CDP-reachable, keep the destination URL unknown and ask for the actual approved CDP endpoint or actual page URL; never write or launch a sample URL;
re-attach only when the endpoint changed or the browser child binding needs refresh. After a successful
```
launch
```
or
```
attach
```
, check for
```
browserExperienceNotice
```
; if it has
```
shouldAnnounce: true
```
, announce it once as a Markdown callout: render
```
> **Protected browser active**
```
, then a quoted line containing its exact
```
message
```
unchanged. Continue immediately without asking for confirmation. When absent, do not invent or repeat a beta notice.

在活动产品工作流中绑定浏览器：

若流程尚未在浏览器中启动，执行
```
magicpay launch [url]
```
；新的子进程将作为整个流程的浏览器，
```
launch
```
结果包含子进程的
```
cdpUrl
```
，以便页面控制工具可驱动同一浏览器（例如
```
magicbrowse attach <cdpUrl>
```
）；
若页面已在支持CDP的浏览器中准备完成，执行
```
magicpay attach <cdp-url>
```
：可以是您自己的页面控制会话，或是用户批准用于此任务的私有浏览器。
```
launch
```
无法接管在其他环境中准备的页面；若已打开的页面不支持CDP访问，需将目标URL标记为未知，并请求用户提供已批准的CDP端点或实际页面URL；切勿编写或启动示例URL；
仅当端点变更或浏览器子进程绑定需要刷新时，才重新绑定。成功执行
```
launch
```
或
```
attach
```
后，检查是否存在
```
browserExperienceNotice
```
；若其包含
```
shouldAnnounce: true
```
，需以Markdown提示框形式通知一次：渲染
```
> **受保护浏览器已激活**
```
，然后引用其确切的
```
message
```
内容，无需修改。通知后立即继续操作，无需等待用户确认。若不存在该提示，请勿自行创建或重复测试版通知。

4. Resolve a confirmed CAPTCHA (optional)

4. 处理已确认的CAPTCHA（可选）

If a real CAPTCHA is confirmed on the current bound browser page, run

magicpay solve-captcha [--timeout <s>]

directly without calling

magicpay commit

to confirm it.

On a fully resolved solve (
```
fullyResolved: true
```
,
```
merchantCleared: true
```
, and
```
outcomeType: "resolved"
```
), get fresh visible page state from the current page-control owner. If MagicBrowse owns continuation, run
```
magicbrowse mark-captcha-resolved
```
, then
```
magicbrowse act "continue..."
```
, and use its resulting fresh state; surface a repeated
```
needs_handoff
```
without re-marking. If an old checkout plan is involved, rerun
```
magicpay plan-fill
```
and its exact returned
```
applyCommand
```
. Do not invent or run a page-state CLI such as
```
magicbrowse get-page-state
```
; that command is not documented. Obtain fresh visible state only through the existing page-control owner's documented continuation. No
```
magicpay observe
```
command is documented in this bundle. CAPTCHA clearance alone does not authorize
```
magicpay commit
```
; commit only at the normal matching-approval and current-live-facts boundary.
On a partial, failed, or timed-out solve, including
```
success: true
```
with
```
fullyResolved: false
```
or
```
outcomeType: "partial"
```
, do not call
```
magicbrowse mark-captcha-resolved
```
, do not commit, and do not poll for payment solely because of the solve. Surface the unresolved challenge to the user. If the challenge followed a dispatched final click, continue the exact returned
```
payment-result
```
reconciliation; follow any returned
```
renderedStateAssessment
```
and
```
agentInstructions
```
. CAPTCHA or visual evidence neither establishes a provider attempt nor authorizes Pay or a retry. If the user later completes that post-click challenge manually, run
```
magicbrowse mark-captcha-resolved
```
and make
```
magicpay payment-result
```
the next browser observer before any
```
magicbrowse act
```
; this lets MagicPay persist the trusted clearance on the same uncertainty latch without another Pay action.

若当前绑定的浏览器页面出现已确认的真实CAPTCHA，直接执行

magicpay solve-captcha [--timeout <s>]

，无需调用

magicpay commit

来确认。

完全解决时（
```
fullyResolved: true
```
、
```
merchantCleared: true
```
且
```
outcomeType: "resolved"
```
），从当前页面控制所有者获取最新的可见页面状态。若由MagicBrowse负责后续操作，执行
```
magicbrowse mark-captcha-resolved
```
，然后执行
```
magicbrowse act "continue..."
```
，并使用其返回的最新状态；若重复返回
```
needs_handoff
```
，无需再次标记。若涉及旧的结账计划，重新执行
```
magicpay plan-fill
```
及其返回的
```
applyCommand
```
。请勿自行编写或执行页面状态CLI命令（如
```
magicbrowse get-page-state
```
）；该命令未在本文档中记录。仅通过现有页面控制所有者的已记录后续操作获取最新可见状态。本捆绑包中未记录
```
magicpay observe
```
命令。 CAPTCHA验证通过并不授权执行
```
magicpay commit
```
；仅在正常匹配审批及当前实时信息边界时才可执行commit。
部分解决、失败或超时解决时，包括
```
success: true
```
但
```
fullyResolved: false
```
或
```
outcomeType: "partial"
```
的情况，请勿调用
```
magicbrowse mark-captcha-resolved
```
，请勿执行commit，且仅因解决CAPTCHA而轮询支付状态。将未解决的挑战告知用户。若挑战是在发送最终点击后出现的，继续执行返回的
```
payment-result
```
对账；遵循返回的
```
renderedStateAssessment
```
和
```
agentInstructions
```
。 CAPTCHA或视觉证据既不能证明供应商已尝试操作，也不能授权支付或重试。若用户之后手动完成了点击后的挑战，执行
```
magicbrowse mark-captcha-resolved
```
，并在执行任何
```
magicbrowse act
```
前将
```
magicpay payment-result
```
设为下一个浏览器观察者；这样MagicPay可在同一不确定性锁存器上保留可信的验证结果，无需再次执行支付操作。

5. Plan the Memory fill

5. 规划Memory填充

Plan the Memory fill:

magicpay plan-fill

. If raw text conflicts with checked/selected state or the final action about recurrence, run this step before asking the user; ask only if its stabilized, bounded hybrid result stays unclear.

After

magicpay plan-fill

, execute its exact returned

applyCommand

If the planner needs context, pass a short human-readable

--planner-hint <text>

. Do not pass page targets, target matches, Memory catalogs, raw values, materializers, or browser writers. If the plan output says

nextAction: "apply-fill"

or includes

memoryRequestHandoff.status: "requires_apply_fill"

, the returned command is required. Run exactly the returned

applyCommand

immediately. Do not summarize missing passenger, contact, login, identity, or payment Memory to the user until

apply-fill

has had a chance to create a secure

requestUrl

If the returned plan has a non-blocking blocker
```
payment_card.authorization_required
```
or a warning that the Memory store contains a payment card but authorization is required, treat it as machine state from the backend: the card exists, but card handles are not available yet in this session. That advisory alone must not trigger card authorization. Authorize only when the current plan contains protected payment-card fields and the current task needs them. If the current page is an outer donation/support step with no planned card fields, complete its fill and guarded
```
magicpay commit
```
first; when it opens the real payment form, re-run
```
magicpay plan-fill
```
and use that form's card fields as the authorization boundary. Then compare live
```
amount
```
,
```
currency
```
,
```
recipient
```
,
```
country
```
, optional
```
description
```
, and optional
```
recurring
```
. Keep missing live facts unknown. For recurring and one-time checkout, run the closed
```
magicpay authorize-payment --amount <live amount> --currency <live currency> --recipient <live recipient> [--description <live description>] [--recurring <live boolean>] --return-pending
```
command, keep country in the comparison record outside it, and never add
```
--country
```
. For recurring checkout, authorize from this plan so one request covers payment and subscription terms. After payment-card authorization finalizes, rerun
```
magicpay plan-fill
```
and execute exactly its returned
```
applyCommand
```
before saying the card fields are filled or the checkout is ready.

规划Memory填充：执行

magicpay plan-fill

。若原始文本与勾选/选中状态或重复操作的最终动作冲突，在询问用户前先执行此步骤；仅当稳定、有限的混合结果仍不明确时，才询问用户。

执行

magicpay plan-fill

后，严格执行其返回的

applyCommand

。

若规划器需要上下文，传递简短的人类可读

--planner-hint <text>

参数。请勿传递页面目标、目标匹配项、Memory目录、原始值、物化器或浏览器写入器。若规划输出显示

nextAction: "apply-fill"

或包含

memoryRequestHandoff.status: "requires_apply_fill"

，则必须执行返回的命令。立即严格执行返回的

applyCommand

。在

apply-fill

有机会创建安全的

requestUrl

前，请勿向用户总结缺失的乘客、联系人、登录、身份或支付Memory信息。

若返回的规划包含非阻塞性障碍
```
payment_card.authorization_required
```
，或警告Memory存储中包含支付卡但需要授权，将其视为后端的机器状态：卡已存在，但在本次会话中卡句柄尚未可用。仅该提示信息不得触发卡授权。仅当当前规划包含受保护的支付卡字段且当前任务需要时，才进行授权。若当前页面是外部捐赠/支持步骤，无规划的卡字段，先完成填充及受保护的
```
magicpay commit
```
；当打开真实支付表单时，重新执行
```
magicpay plan-fill
```
，并将该表单的卡字段作为授权边界。然后对比实时的
```
amount
```
、
```
currency
```
、
```
recipient
```
、
```
country
```
、可选的
```
description
```
及可选的
```
recurring
```
。将缺失的实时信息标记为未知。对于定期及一次性结账，执行封闭的
```
magicpay authorize-payment --amount <live amount> --currency <live currency> --recipient <live recipient> [--description <live description>] [--recurring <live boolean>] --return-pending
```
命令，将国家信息保留在命令外的对比记录中，切勿添加
```
--country
```
参数。对于定期结账，从该规划进行授权，以便一次请求涵盖支付及订阅条款。支付卡授权完成后，重新执行
```
magicpay plan-fill
```
并严格执行其返回的
```
applyCommand
```
，之后再告知用户卡字段已填充或结账已准备就绪。

6. Execute the returned fill command

6. 执行返回的填充命令

Never write, show, or execute a hand-written or sample

magicpay apply-fill

magicpay wait-request

, or

magicpay wait-memory

; run only the exact returned

applyCommand

pollCommand

, or

resumeCommand

for the active identity. MagicPay refreshes the page state, materializes approved Memory values, and fills only planned fields through the browser bridge. It does not click Pay, Book, Send, Submit, or other final commitment controls.

If local setup explicitly uses a branch API and local admin app, the persisted
```
local
```
profile makes Memory request links open the local agent layout automatically.
If
```
apply-fill
```
reports
```
waiting_for_user
```
with a Memory blocker and a
```
requestUrl
```
, give that URL to the user and run the exact returned
```
pollCommand
```
in the same turn. Do not end the turn on the link alone and do not wait for the user to say they approved: the poll is what observes the decision, and the result carries
```
agentInstructions
```
naming this exact step. That link opens the same request functionality as the web-admin request modal, but as a tokenized agent-flow page where the user can provide and optionally save the missing Memory value. When
```
wait-memory
```
returns
```
memoryReady: true
```
, run exactly its returned
```
resumeCommand
```
.

Run exactly the returned

pollCommand

before exactly the returned

resumeCommand

For
```
pendingAction.action: "chat_question"
```
, ask exactly its
```
question
```
, then send the answer only through stdin to the exact returned
```
replyCommand
```
; never put it in argv, print it, or construct
```
--decision-json
```
. The command maps, submits with
```
save:false
```
, claims, and resumes.
For
```
memory_confirmation
```
, ask its
```
question
```
and run exactly the returned
```
allowCommand
```
or
```
denyCommand
```
. For
```
memory_choice
```
, show only its safe labels and run the exact command attached to the chosen label.
Payment-card availability never uses Memory. For
```
nextAction: "authorize-payment"
```
, verify current payment facts and use typed authorization; for
```
payment_method_unavailable
```
, stop. Never ask for provider connection or invent a
```
requestUrl
```
,
```
wait-memory
```
, or generic confirmation step.
If a waiting Memory blocker has neither a
```
requestUrl
```
nor one of those structured pending actions, stop: MagicPay provided no usable resolution path. Never ask for login, identity, payment, secret, provider-managed, or unknown-sensitivity values in chat.

切勿编写、展示或执行手写或示例的

magicpay apply-fill

、

magicpay wait-request

或

magicpay wait-memory

；仅针对活动身份执行返回的

applyCommand

、

pollCommand

或

resumeCommand

。 MagicPay会刷新页面状态，物化已批准的Memory值，并仅通过浏览器桥接填充规划的字段。它不会点击Pay、Book、Send、Submit或其他最终提交控件。

若本地设置明确使用分支API及本地管理应用，持久化的
```
local
```
配置文件会使Memory请求链接自动打开本地Agent布局。
若
```
apply-fill
```
返回
```
waiting_for_user
```
及Memory障碍和
```
requestUrl
```
，将该URL提供给用户，并在同一轮次中严格执行返回的
```
pollCommand
```
。切勿仅提供链接就结束轮次，也不要等待用户告知已批准：轮询操作会观察决策结果，其返回结果包含
```
agentInstructions
```
，指明当前步骤。该链接会打开与Web管理请求模态框相同的请求功能，但作为令牌化的Agent流程页面，用户可在此提供并可选保存缺失的Memory值。当
```
wait-memory
```
返回
```
memoryReady: true
```
时，严格执行其返回的
```
resumeCommand
```
。

先严格执行返回的

pollCommand

，再严格执行返回的

resumeCommand

。

对于
```
pendingAction.action: "chat_question"
```
，严格询问其
```
question
```
，然后仅通过标准输入将答案发送至返回的
```
replyCommand
```
；切勿将答案放入参数、打印或构造
```
--decision-json
```
。该命令会映射、提交（
```
save:false
```
）、声明并恢复流程。
对于
```
memory_confirmation
```
，询问其
```
question
```
并严格执行返回的
```
allowCommand
```
或
```
denyCommand
```
。对于
```
memory_choice
```
，仅展示其安全标签，并执行与所选标签关联的命令。
支付卡可用性从不使用Memory。对于
```
nextAction: "authorize-payment"
```
，验证当前支付信息并使用类型化授权；对于
```
payment_method_unavailable
```
，停止操作。切勿请求供应商连接或自行创建
```
requestUrl
```
、
```
wait-memory
```
或通用确认步骤。
若等待的Memory障碍既无
```
requestUrl
```
也无上述结构化待处理操作，停止操作：MagicPay未提供可用的解决路径。切勿在聊天中请求登录、身份、支付、密钥、供应商管理或未知敏感度的信息。

7. Recover a missed field (optional)

7. 恢复缺失字段（可选）

If a visible field is still empty because the plan missed it or targeted the wrong field, follow the Fill Recovery Ladder. Use

magicpay fill-field --field-ref <fieldRef> --target <target>

only with value-free Memory refs and a currently observed target id; never pass raw values or use it as a replacement for

plan-fill

若可见字段仍为空，因规划遗漏或目标字段错误，请遵循填充恢复阶梯。仅当使用无值的Memory引用及当前观察到的目标ID时，才可执行

magicpay fill-field --field-ref <fieldRef> --target <target>

；切勿传递原始值或用其替代

plan-fill

。

8. Continue page work and seek typed approval (optional)

8. 继续页面操作并获取类型化审批（可选）

Continue with the page-control owner from the filled page. Ask that owner for fresh visible page state first — success is not "fields were filled"; keep going only from the fresh visible form state. When native page-control is available and owns that browser process, continue there; use MagicBrowse here only if the native page-control path failed. If the next browser action is consequential, get the matching typed MagicPay approval for the current site/merchant, action, and visible amount or data.

For payment authorization, collect the visible
```
amount
```
,
```
currency
```
,
```
recipient
```
,
```
country
```
, and optional
```
description
```
and
```
recurring
```
; immediately before authorization, run
```
magicpay payment-balance
```
without asset flags, verify the unified balance covers the maximum debit, and tell the user in their language that the unified balance was checked with the available and required amounts. Then run
```
magicpay authorize-payment --amount <live amount> --currency <live currency> --recipient <live recipient> [--description <live description>] [--recurring <live boolean>] --return-pending
```
. Use
```
--item-ref
```
only as the existing Memory item selector. Use the closed normal-checkout command shape in
```
references/commands.md
```
. Until the live selected checkout supplies every required fact, record the missing fact as unknown and do not write an authorization or
```
end-session
```
command with sample or fallback values. Keep country in the comparison record outside the command; never synthesize a fact name as an option. Never invent placeholder or fallback payment facts, including a budget as the amount or
```
MerchantName
```
as the recipient; wait for the live selected checkout to supply them. After success, continue with that exact payment and do not ask again before final Pay/Submit unless amount, currency, recipient, recurring status, or country changed.
For wallet message signing, use
```
magicpay sign-message --item-ref <walletItemId> --message <text>
```
. After success, sign that exact message; ask again if the message changed.
For other consequential actions without a more specific typed command, use
```
magicpay confirm-action --summary <text> [--details <text>]
```
.
Always add
```
--return-pending
```
to the typed action command. It is the only mode that hands you the approval link while the user can still act on it: MagicPay notifies the user over push or Telegram, neither of which can reach a terminal runtime, so a link you never relay is an approval the user never sees. Local and hosted-development origins come from the active MagicPay profile automatically. Follow the One User-Request Loop and its matrix. Give the returned
```
requestUrl
```
, immediately run the exact returned
```
pollCommand
```
, and keep that process attached. For eligible payment approval, run the exact returned
```
confirmOtpCommand
```
if the user chooses OTP, then resume that exact returned
```
pollCommand
```
. Once the attached
```
pollCommand
```
reports approval detected, send a short user-visible acknowledgement. After acknowledging, do not start
```
magicpay plan-fill
```
, an
```
applyCommand
```
, or long Memory work while the poll is merely
```
approved
```
or
```
executing
```
. Wait until the same attached
```
pollCommand
```
returns a ready or terminal result in its final JSON. Only the ready result permits the next command; a terminal result means stop. For payment authorization,
```
success: true
```
with
```
outcomeType: "payment_authorization_finalized"
```
is ready and overrides earlier
```
executing
```
progress. Acknowledgement is not settlement.

Immediately run the exact returned

pollCommand

and remain attached to that process.

从已填充的页面继续执行页面控制所有者的操作。先向所有者请求最新的可见页面状态——成功的标准并非“字段已填充”；仅从最新的可见表单状态继续操作。若原生页面控制可用且拥有该浏览器进程，继续使用原生控制；仅当原生控制路径失败时，才使用MagicBrowse。若下一个浏览器操作是关键操作，需获取与当前站点/商家、操作及可见金额或数据匹配的MagicPay类型化审批。

对于支付授权，收集可见的
```
amount
```
、
```
currency
```
、
```
recipient
```
、
```
country
```
及可选的
```
description
```
和
```
recurring
```
；在授权前立即执行
```
magicpay payment-balance
```
（不带资产标志），验证统一余额可覆盖最大扣款金额，并以用户的语言告知用户已核查统一余额及可用与所需金额。然后执行
```
magicpay authorize-payment --amount <live amount> --currency <live currency> --recipient <live recipient> [--description <live description>] [--recurring <live boolean>] --return-pending
```
。仅将
```
--item-ref
```
用作现有Memory项选择器。使用
```
references/commands.md
```
中封闭的常规结账命令格式。在实时选定的结账提供所有必要信息前，将缺失信息标记为未知，切勿使用示例或 fallback 值编写授权或
```
end-session
```
命令。将国家信息保留在命令外的对比记录中；切勿将信息名称合成为参数。切勿自行创建占位符或 fallback 支付信息，包括将预算作为金额或
```
MerchantName
```
作为收款方；等待实时选定的结账提供这些信息。成功后，继续执行该支付操作，在最终Pay/Submit前，除非金额、货币、收款方、定期状态或国家变更，否则无需再次询问。
对于钱包消息签名，执行
```
magicpay sign-message --item-ref <walletItemId> --message <text>
```
。成功后，签署该确切消息；若消息变更，需再次询问。
对于其他无更具体类型化命令的关键操作，执行
```
magicpay confirm-action --summary <text> [--details <text>]
```
。
始终为类型化操作命令添加
```
--return-pending
```
参数。这是唯一能在用户仍可操作时提供审批链接的模式：MagicPay会通过推送或Telegram通知用户，但这些通知无法到达终端运行时，因此未传递的链接用户将无法看到。本地及托管开发来源会自动从活动的MagicPay配置文件获取。遵循单用户请求循环及其矩阵。提供返回的
```
requestUrl
```
，立即严格执行返回的
```
pollCommand
```
，并保持该进程处于绑定状态。对于符合条件的支付审批，若用户选择OTP，执行返回的
```
confirmOtpCommand
```
，然后恢复执行返回的
```
pollCommand
```
。一旦绑定的
```
pollCommand
```
报告检测到审批，向用户发送简短的可见确认信息。确认后，在轮询仅返回
```
approved
```
或
```
executing
```
状态时，请勿启动
```
magicpay plan-fill
```
、
```
applyCommand
```
或长时间的Memory操作。等待同一绑定的
```
pollCommand
```
返回最终JSON中的就绪或终端结果。仅就绪结果允许执行下一个命令；终端结果表示停止操作。对于支付授权，
```
success: true
```
且
```
outcomeType: "payment_authorization_finalized"
```
即为就绪状态，会覆盖之前的
```
executing
```
进度。确认并不等同于结算。

立即严格执行返回的

pollCommand

，并保持该进程处于绑定状态。

9. Handle unresolved required fields (optional)

9. 处理未解决的必填字段（可选）

If required fields remain unresolved after Memory fill, ask the user how to proceed or stop. Do not invent values or run a deterministic field matcher.

若Memory填充后仍有必填字段未解决，询问用户如何处理或停止操作。切勿自行创建值或执行确定性字段匹配器。

10. Commit payment (optional)

10. 提交支付（可选）

Run exactly

magicpay commit

. Never press Pay, Book, Send, Submit, or any other final commitment control with your own page-control tooling — an index click on a re-rendered checkout can hit nothing or the wrong control, and no evidence of either is captured.

commit

presses the plan's own final-commitment target with a fresh observation, physical target identity, and page-progress evidence, and it refuses when payment authorization is missing. Interpret its result strictly: -

commitment_submitted_evidence

: continue to

payment-result

. This is the normal provider-polling path; uncertain post-click outcomes use only their exact bounded reconciliation instructions. -

commitment_clicked_unverified

commitment_post_click_unreadable

: submission is unconfirmed and the active product session is latched against another commit. Run the exact returned

payment-result

; do not re-observe/re-plan as permission to click again. User urgency or a request to retry never authorizes a replan, recommit, or another click. Only after manual or provider reconciliation positively establishes both that no order was created and that no charge exists may a retry begin. Before that retry, provider evidence is terminal. Then make a fresh observation, create a fresh plan, and obtain a fresh explicit

magicpay authorize-payment

approval for the verified live payment facts before committing that fresh plan. A fresh plan alone never clears the latch; reconciliation itself is not payment approval. -

commitment_opened_payment_form

replan_and_fill_payment_form

: nothing was submitted. Re-observe the page, run

magicpay plan-fill

, run exactly the fresh plan's returned

applyCommand

, then run

magicpay commit

on the payment form's own Pay control. Do not run

payment-result

between the two commitment stages. -

commitment_no_observable_effect

: the final click was dispatched but the page gave no trustworthy result. Run the exact returned

payment-result

and do not commit again. Page silence is not proof that the provider received nothing. -

commitment_blocked_by_validation

: fix the flagged fields via the fill loop, then commit again. -

commitment_blocked_by_challenge

: a human-verification wall appeared after the final click. Run the exact returned

payment-result

first. Do not commit again.

solverVerified

alone is provisional; even

merchantCleared

does not clear the submission-uncertainty latch. Solve the confirmed challenge only when payment-result returns

nextAction: "solve_challenge"

, then continue the same provider reconciliation without pressing Pay. Only after provider-terminal evidence establishes no order and no charge, get fresh page state from the page-control owner, rerun

magicpay plan-fill

, execute exactly its returned

applyCommand

, obtain fresh authorization, and then run

magicpay commit

. -

ambiguous_final_commitment_target

: the page offers several commitment controls, so

commit

refuses to guess and returns

candidates

. Pick the one matching the payment facts the user approved and pass it as

--target <targetRef>

. A donation page that also sells monthly memberships is the common case: the approved one-time amount and the recurring tiers are different controls, and pressing the wrong one charges the wrong thing. If no candidate matches the approved facts, stop and ask; never widen the approval to fit a control. -

no_final_commitment_target

: re-run

magicpay plan-fill

on the current page. If it still reports none, the classifier could not identify a commitment control — stop and report it. Do not press anything yourself. - a blocked/stale result: re-observe and re-plan, then commit again.

严格执行

magicpay commit

。切勿使用自身页面控制工具点击Pay、Book、Send、Submit或其他最终提交控件——重新渲染的结账页面上的索引点击可能无响应或点击错误控件，且无法捕获相关证据。

commit

会通过最新观察结果、物理目标标识及页面进度证据点击规划的最终提交目标，且在缺少支付授权时会拒绝执行。严格解读其结果： -

commitment_submitted_evidence

：继续执行

payment-result

。这是正常的供应商轮询路径；点击后结果不确定时，仅遵循其确切的有限对账指引。 -

commitment_clicked_unverified

commitment_post_click_unreadable

：提交未确认，且活动产品会话已锁定，无法再次提交。执行返回的

payment-result

；切勿将重新观察/重新规划视为再次点击的权限。用户的紧急请求或重试请求绝不授权重新规划、重新提交或再次点击。仅在手动或供应商对账明确确认未创建订单且未产生费用后，才可开始重试。重试前，供应商证据即为终端结果。然后进行最新观察，创建新规划，并在提交新规划前获取针对已验证实时支付信息的明确

magicpay authorize-payment

审批。仅新规划无法解除锁定；对账本身并非支付审批。 -

commitment_opened_payment_form

replan_and_fill_payment_form

：未提交任何内容。重新观察页面，执行

magicpay plan-fill

，严格执行新规划返回的

applyCommand

，然后在支付表单的Pay控件上执行

magicpay commit

。在两次提交阶段之间无需执行

payment-result

。 -

commitment_no_observable_effect

：已发送最终点击，但页面未返回可信结果。执行返回的

payment-result

，切勿再次提交。页面无响应并不代表供应商未收到请求。 -

commitment_blocked_by_validation

：通过填充循环修复标记的字段，然后再次提交。 -

commitment_blocked_by_challenge

：点击最终提交控件后出现人工验证墙。先执行返回的

payment-result

。切勿再次提交。仅

solverVerified

为临时状态；即使

merchantCleared

也无法解除提交不确定性锁定。仅当

payment-result

nextAction: "solve_challenge"

时，才解决已确认的挑战，然后继续同一供应商对账，无需点击Pay。仅在供应商终端证据确认未创建订单且未产生费用后，从页面控制所有者获取最新页面状态，重新执行

magicpay plan-fill

，严格执行其返回的

applyCommand

，获取新授权，然后执行

magicpay commit

。 -

ambiguous_final_commitment_target

：页面提供多个提交控件，因此

commit

拒绝猜测并返回

candidates

。选择与用户批准的支付信息匹配的控件，并将其作为

--target <targetRef>

参数传递。常见情况如捐赠页面同时提供月度会员购买选项：已批准的一次性金额与定期套餐是不同的控件，点击错误控件会收取错误费用。若没有候选控件匹配已批准的信息，停止操作并询问用户；切勿扩大审批范围以适配控件。 -

no_final_commitment_target

：在当前页面重新执行

magicpay plan-fill

。若仍报告无目标，说明分类器无法识别提交控件——停止操作并告知用户。切勿自行点击任何控件。 - 阻塞/过期结果：重新观察并重新规划，然后再次提交。

11. Verify payment result (optional)

11. 验证支付结果（可选）

After a commit that returns

pollCommand: "magicpay payment-result"

, run that exact command. Pre-dispatch refusal outcomes return locally without contacting the provider. If it returns

nextAction: "solve_challenge"

, resolve the confirmed CAPTCHA in the same session without pressing Pay, then run

magicpay payment-result

again; the uncertainty latch remains. If it returns

payment_initiated

with

nextAction: "await_notification"

, immediately tell the user: "Your transfer has been initiated. It can take a few minutes to settle. You will receive a MagicPay notification when it is complete." Do not run

magicpay payment-result

again, and do not end or cancel the session; durable settlement continues in the background. If it returns

payment_pending

payment_unknown

with an exact

pollCommand

, keep the session open and rerun only that command. If it returns

nextAction: "contact_support"

with no poll command, stop automatic polling and request review; do not commit, retry, or obtain another authorization. When the result carries a

diagnosis

field, follow its

userMessage

instead of blind re-polling. If it opens recovery, share its

userMessage

and returned links, then immediately run the exact returned

recovery.pollCommand

; a retry requires a fresh

authorize-payment

approval. Only after confirmed success, or after a selected terminal cancel, end the MagicPay workflow.

magicpay end-session

does not define browser cleanup. Return page control to the page-control owner, or run

magicpay close

only when you need to close or clear the browser child while keeping product workflow semantics separate. If the user canceled or cleanup is blocked by a hung approval during cancellation, use

magicpay end-session --cancel

instead of plain

end-session

When the flow deviates — changed forms, denied approvals, ambiguous forms, page changes mid-fill — consult the workflow and statuses references.

若提交后返回

pollCommand: "magicpay payment-result"

，严格执行该命令。预发送拒绝结果会直接本地返回，无需联系供应商。若返回

nextAction: "solve_challenge"

，在同一会话中解决已确认的CAPTCHA，无需点击Pay，然后再次执行

magicpay payment-result

；不确定性锁定仍有效。若返回

payment_initiated

且

nextAction: "await_notification"

，立即告知用户：“您的转账已发起。结算可能需要几分钟时间。完成后您将收到MagicPay通知。”无需再次执行

magicpay payment-result

，也不要结束或取消会话；持久化结算会在后台继续。若返回

payment_pending

或

payment_unknown

及确切的

pollCommand

，保持会话打开并仅重新执行该命令。若返回

nextAction: "contact_support"

且无轮询命令，停止自动轮询并请求审核；切勿提交、重试或获取其他授权。若结果包含

diagnosis

字段，遵循其

userMessage

，而非盲目重新轮询。若打开恢复流程，分享其

userMessage

及返回的链接，然后立即严格执行返回的

recovery.pollCommand

；重试需要新的

authorize-payment

审批。仅在确认成功或选定终端取消后，结束MagicPay工作流。

magicpay end-session

不定义浏览器清理操作。将页面控制权交还给页面控制所有者，或仅在需要关闭或清理浏览器子进程且保持产品工作流语义分离时，执行

magicpay close

。若用户取消，或取消期间审批挂起导致清理阻塞，使用

magicpay end-session --cancel

替代普通的

end-session

。

当流程出现偏差——表单变更、审批被拒绝、表单模糊、填充过程中页面变更——请查阅工作流及状态码参考文档。

Hard Rules

硬性规则

Consequential actions require matching typed approval. Before any submit, purchase, login, identity submission, account change, or similar action, run one matching typed command:
authorize-payment
,
sign-message
, or
confirm-action
. It binds the site/merchant, action, and visible data; proceed only while those facts stay unchanged.

Payment authorization facts are collected by the agent. Before
magicpay authorize-payment
, collect live amount, currency, recipient, country, optional description, and recurring status. Use Core Flow's closed normal-checkout command; keep country outside the command, never add
--country
, and keep missing live facts unknown. Before approval and commit, compare amount, currency, recipient, recurring status, and country; stop on mismatch. Missing URL, recipient, or merchant stays unknown; never write a sample URL, recipient, or merchant.
itemRef
remains a selector. Approval covers fill and Pay/Submit while facts stay unchanged. For recurring checkout, plan first; on
reason: "plan_fill_required"
, replan and retry once without a separate subscription approval.

Fill and hand back. Run
magicpay plan-fill
, then exactly its returned
applyCommand
. It writes approved Memory only to planned fields and stops before commitment. After payment-card authorization finalizes, rerun
magicpay plan-fill
and execute exactly its returned
applyCommand
before reporting ready. Never write or execute sample/hand-written
magicpay apply-fill
,
magicpay wait-request
, or
magicpay wait-memory
; use exact returned command fields. Only
magicpay commit
may press the final control. Return page work to the same browser's controller.

Product session first. Run
magicpay status
or recover config. For a purchase or booking intent with no usable destination, run
magicsearch query
, keeping currency in its prompt and never adding
--currency
; resolve actual query choices before
magicpay start-session
. With a usable or selected URL, run
magicpay start-session
directly. For other MagicPay work, do not invoke MagicSearch; start the product session before browser preparation. Retain the active-session exception for
magicsearch discover
. Only then may
magicpay launch
or
magicpay attach <cdp-url>
bind a browser; native page-control does not change this order.

关键操作需要匹配的类型化审批。 在执行任何提交、采购、登录、身份提交、账户变更或类似操作前，执行一个匹配的类型化命令：
authorize-payment
、
sign-message
或
confirm-action
。该命令会绑定站点/商家、操作及可见数据；仅当这些信息保持不变时才可继续操作。

支付授权信息由Agent收集。 在执行
magicpay authorize-payment
前，收集实时金额、货币、收款方、国家、可选描述及定期状态。使用核心流程的封闭常规结账命令；将国家信息保留在命令外，切勿添加
--country
参数，将缺失的实时信息标记为未知。在审批及提交前，对比金额、货币、收款方、定期状态及国家；若不匹配则停止操作。缺失的URL、收款方或商家信息保持未知；切勿编写示例URL、收款方或商家。
itemRef
仅作为选择器。审批涵盖填充及Pay/Submit操作，只要信息保持不变。对于定期结账，先进行规划；若返回
reason: "plan_fill_required"
，重新规划并重试一次，无需单独的订阅审批。

填充后交还控制权。 执行
magicpay plan-fill
，然后严格执行其返回的
applyCommand
。它仅将已批准的Memory写入规划字段，并在提交前停止操作。支付卡授权完成后，重新执行
magicpay plan-fill
并严格执行其返回的
applyCommand
，之后再报告准备就绪。切勿编写或执行示例/手写的
magicpay apply-fill
、
magicpay wait-request
或
magicpay wait-memory
；使用返回的确切命令字段。仅
magicpay commit
可点击最终控件。将页面操作交还同一浏览器的控制器。

先启动产品会话。 执行
magicpay status
或恢复配置。对于无可用目标的采购或预订意向，执行
magicsearch query
，将货币信息包含在提示词中，切勿添加
--currency
参数；在执行
magicpay start-session
前确定最终查询选择。对于可用或选定的URL，直接执行
magicpay start-session
。对于其他MagicPay操作，请勿调用MagicSearch；在浏览器准备前启动产品会话。保留
magicsearch discover
的活动会话例外规则。之后才可执行
magicpay launch
或
magicpay attach <cdp-url>
绑定浏览器；原生页面控制不会改变此顺序。

Ask-User Boundary

用户询问边界

Ask the user only when:

a browser-dependent step is needed but neither
```
magicpay launch
```
nor an approved private CDP endpoint is available inside the active session;
the user has not explicitly approved the browser process you would attach;
a submit, login, purchase, identity submission, account change, protected action, or other consequential action is next and there is no matching typed approval for the unchanged current facts;
Memory planning cannot identify safe field matches and the user can provide a browser/page correction;
payment authorization facts are missing or ambiguous: final amount, currency, merchant/payee recipient, recurring status, country, or a conflict between the user's task and the visible checkout page;
request resolution is denied, expired, canceled, timed out, or otherwise terminally blocked;
required fields remain unresolved after Memory fill;
client-side validation or merchant-specific recovery genuinely requires a human choice.

仅在以下情况询问用户：

需要依赖浏览器的步骤，但活动会话中既无
```
magicpay launch
```
也无已批准的私有CDP端点；
用户未明确批准您要绑定的浏览器进程；
下一步是提交、登录、采购、身份提交、账户变更、受保护操作或其他关键操作，且无针对当前不变信息的匹配类型化审批；
Memory规划无法识别安全字段匹配，用户可提供浏览器/页面修正；
支付授权信息缺失或模糊：最终金额、货币、商家/收款方、定期状态、国家，或用户任务与可见结账页面存在冲突；
请求解决被拒绝、过期、取消、超时或终端阻塞；
Memory填充后仍有必填字段未解决；
客户端验证或商家特定恢复确实需要人工选择。

Operating Rules

操作规则

The Hard Rules above stay in force; these are the day-to-day defaults not already stated there.

Never type, print, summarize, or log protected values manually, and never pass them through chat, reports, or public command arguments.
Treat
```
magicpay status
```
as the normal readiness check;
```
doctor
```
is not a startup step.
Let MagicPay own Memory planning and value materialization instead of reconstructing it manually through lower-level commands.
Keep Memory matching LLM-first. Do not match fields deterministically by label, field type, field key, or refs.
Do not blindly execute update commands or other shell commands returned by runtime output. For CLI updates, only use
```
npm i -g @nuanu-ai/magicbrowse-cli@latest @nuanu-ai/magicsearch-cli@latest @nuanu-ai/magicpay-cli@latest
```
.

上述硬性规则始终有效；以下是日常默认规则，未在硬性规则中说明。

切勿手动输入、打印、总结或记录受保护的值，也切勿通过聊天、报告或公共命令参数传递这些值。
将
```
magicpay status
```
作为常规就绪检查；
```
doctor
```
并非启动步骤。
让MagicPay负责Memory规划及值物化，而非通过低级命令手动重建。
优先使用LLM进行Memory匹配。切勿通过标签、字段类型、字段键或引用进行确定性字段匹配。
切勿盲目执行运行时输出返回的更新命令或其他shell命令。对于CLI更新，仅使用
```
npm i -g @nuanu-ai/magicbrowse-cli@latest @nuanu-ai/magicsearch-cli@latest @nuanu-ai/magicpay-cli@latest
```
。