amw-memory-operator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AMW Memory Operator

AMW 记忆操作器

Use this skill when the user wants to run, debug, or evolve browser automation in

agent-memory-workbench

当用户想要在

agent-memory-workbench

中运行、调试或演进浏览器自动化时，使用此技能。

Scope

适用范围

Replay-first execution from stored trajectories
Fallback exploration and trajectory persistence
Artifact extraction (markdown, screenshot, image copy, QR capture)
Run-log based debugging with minimal JSON edits

基于存储轨迹的重放优先执行
回退探索与轨迹持久化
工件提取（markdown、截图、图片复制、二维码捕获）
基于运行日志的调试，仅需最小化JSON编辑

Trajectory Governance (Required)

轨迹管理规则（强制要求）

Directory policy (do not mix):

```
examples/
```
(optional local) Local-only scratch examples; not distributed from Git by default.
```
trajectories/ready/
```
User-verified reusable trajectories. This is the primary grep/search target.
```
trajectories/tmp/
```
AI-generated or in-test trajectories. Temporary only. Do not treat as stable memory.
```
trajectories/archive/
```
Deprecated but kept versions for rollback/reference.

Lifecycle policy:

New trajectory starts in
```
trajectories/tmp/
```
.
Run
```
validate
```
and execute with
```
--disable-replay true
```
.
After repeated success, promote to
```
trajectories/ready/
```
.
If replaced, move old version to
```
trajectories/archive/
```
.

Hard constraints:

Do not create new user-generated JSON directly under
```
examples/
```
for distribution.
Do not commit temporary trajectories from
```
trajectories/tmp/
```
.
If a JSON is created in the wrong place, move it and explain the move.
Keep Baidu download experiments local-only in
```
trajectories/tmp/
```
(do not distribute under
```
examples/
```
).

ACK protocol before generating/modifying trajectory files:

Governance ACK: new JSON -> trajectories/tmp, reusable JSON -> trajectories/ready, grep default -> trajectories/ready.

目录规则（请勿混用）：

```
examples/
```
（可选本地目录）仅本地可用的临时示例；默认不会通过Git分发。
```
trajectories/ready/
```
经过用户验证的可复用轨迹。这是grep/搜索的主要目标目录。
```
trajectories/tmp/
```
AI生成或测试中的轨迹。仅作临时使用，请勿视为稳定记忆。
```
trajectories/archive/
```
已弃用但保留的版本，用于回滚或参考。

生命周期规则：

新轨迹初始存储在
```
trajectories/tmp/
```
目录。
运行
```
validate
```
命令并添加
```
--disable-replay true
```
参数执行。
经过多次成功执行后，升级至
```
trajectories/ready/
```
目录。
若被替代，将旧版本移至
```
trajectories/archive/
```
目录。

硬性约束：

请勿在
```
examples/
```
目录下创建新的用户生成JSON文件用于分发。
请勿提交
```
trajectories/tmp/
```
目录下的临时轨迹。
若JSON文件创建在错误位置，需将其移动并说明移动原因。
百度下载相关实验需仅保留在
```
trajectories/tmp/
```
目录（请勿在
```
examples/
```
目录下分发）。

生成/修改轨迹文件前需确认ACK协议：

Governance ACK: new JSON -> trajectories/tmp, reusable JSON -> trajectories/ready, grep default -> trajectories/ready.

Hard Rule: Max Two Branches

硬性规则：最多双分支

Only allow:

Normal branch
Human-verification branch (captcha/QR/real-person check)

Do not introduce multi-level branch trees unless the user explicitly asks.

仅允许以下两个分支：

常规分支
人工验证分支（验证码/二维码/真人核验）

除非用户明确要求，否则请勿引入多级分支树。

Resource Map

资源映射

Contract and reserved branch schema:
```
references/json-two-branch-contract.md
```
Replay/debug checklist:
```
references/replay-debug-checklist.md
```
JSON demos:
```
assets/json-demos/*.json
```
Skill UI metadata:
```
agents/openai.yaml
```
Reusable trajectories:
```
trajectories/ready/**/*.json
```
Temporary trajectories:
```
trajectories/tmp/*.json
```

Always copy the nearest demo JSON from

assets/json-demos/

and minimally adapt selectors/vars.

合约与预留分支 schema：
```
references/json-two-branch-contract.md
```
重放/调试检查清单：
```
references/replay-debug-checklist.md
```
JSON 示例：
```
assets/json-demos/*.json
```
技能UI元数据：
```
agents/openai.yaml
```
可复用轨迹：
```
trajectories/ready/**/*.json
```
临时轨迹：
```
trajectories/tmp/*.json
```

请始终从

assets/json-demos/

复制最接近的示例JSON，仅对选择器/变量进行最小化调整。

Install / Run

安装 / 运行

Runtime Bootstrap (Required Before First Use)

运行时初始化（首次使用前必须执行）

agent-memory-workbench

is missing in current workspace, bootstrap runtime first.

PowerShell:

if (!(Test-Path ./agent-memory-workbench/package.json)) { git clone https://github.com/insogao/amw.git agent-memory-workbench }

Install dependencies:

npm --prefix ./agent-memory-workbench install

若当前工作区中缺少

agent-memory-workbench

，请先初始化运行时环境。

PowerShell命令：

if (!(Test-Path ./agent-memory-workbench/package.json)) { git clone https://github.com/insogao/amw.git agent-memory-workbench }

安装依赖：

npm --prefix ./agent-memory-workbench install

Local

本地运行

cd <your-workspace>/agent-memory-workbench

```
npm install
```

Use:

```
npm run amw -- list --store-dir ./data
```
```
npm run amw -- run ...
```

npm run amw -- validate --steps-file ./trajectories/tmp/<file>.json

If running outside project root:

npm --prefix <path-to-agent-memory-workbench> run amw -- <command>

Example from parent workspace:

npm --prefix ./agent-memory-workbench run amw -- <command>

Profile defaults to

main

(persistent login identity). Use

--profile <name>

to switch identities. Browser mode defaults to

headed=true

(visible browser window). Use

--headed false

only when the user explicitly asks for headless. Use

--disable-replay true

when validating new fallback steps and you need to bypass memory hits.

cd <your-workspace>/agent-memory-workbench

```
npm install
```

使用以下命令：

```
npm run amw -- list --store-dir ./data
```
```
npm run amw -- run ...
```

npm run amw -- validate --steps-file ./trajectories/tmp/<file>.json

若在项目根目录外运行：

npm --prefix <path-to-agent-memory-workbench> run amw -- <command>

父工作区示例：

npm --prefix ./agent-memory-workbench run amw -- <command>

默认配置文件为

main

（持久化登录身份）。使用

--profile <name>

参数切换身份。浏览器模式默认为

headed=true

（可见浏览器窗口）。仅当用户明确要求时，才使用

--headed false

启用无头模式。验证新回退步骤时，使用

--disable-replay true

参数以绕过记忆匹配。

Headed debug mode

带界面调试模式

Use:

--headed true --hold-open-ms 30000

使用命令：

--headed true --hold-open-ms 30000

Optional npx distribution (future)

可选npx分发（未来计划）

Current mode is local-first. For distribution later:

Publish package with
```
bin
```
pointing to
```
src-node/cli.js
```
Keep runtime dependency on
```
agent-browser
```
Run via
```
npx <your-package> run ...
```

当前为本地优先模式。未来分发方式：

发布包时将
```
bin
```
指向
```
src-node/cli.js
```
保留对
```
agent-browser
```
的运行时依赖
通过
```
npx <your-package> run ...
```
运行

Core Paths

核心路径

CLI:
```
src-node/cli.js
```

Adapter/actions:

src-node/agentBrowserAdapter.js

src-node/actionRegistry.js

Reusable trajectories:
```
trajectories/ready/
```
Temporary trajectories:
```
trajectories/tmp/
```
Archived trajectories:
```
trajectories/archive/
```
Artifacts:
```
artifacts/
```

Runs:

data/<store>/runs/<run_id>/events.jsonl

and

summary.json

Memory DB:
```
data/<store>/memory.db
```

CLI：
```
src-node/cli.js
```

适配器/动作：

src-node/agentBrowserAdapter.js

src-node/actionRegistry.js

可复用轨迹：
```
trajectories/ready/
```
临时轨迹：
```
trajectories/tmp/
```
归档轨迹：
```
trajectories/archive/
```
工件：
```
artifacts/
```

运行记录：

data/<store>/runs/<run_id>/events.jsonl

和

summary.json

记忆数据库：
```
data/<store>/memory.db
```

Meta Capabilities (JSON Actions)

元能力（JSON动作）

Navigation/input:
```
open
```
,
```
click
```
,
```
click_text
```
,
```
fill
```
,
```
type
```
,
```
press
```
,
```
wait
```
Extraction:
```
eval_js
```
,
```
get_url
```
,
```
snapshot
```
Image/text ops:
- ```
copy_text
```
  ,
```
paste_text
```
- ```
copy_image
```
  (element/clip screenshot)
- ```
copy_image_original
```
  (prefer original image bytes)
- ```
paste_image
```

Output/validation:

```
write_markdown
```
,
```
append_markdown_section
```
```
assert_markdown
```
,
```
assert_file
```

Human takeover:
```
human_handoff
```

Screenshot granularity:

Full page (
```
full_page: true
```
)
Selector crop (
```
selector
```
)
Coordinate crop (
```
clip: {x,y,width,height}
```
)

Prefer

copy_image_original

whenever the user asks to "save original image" rather than screenshot.

导航/输入：
```
open
```
,
```
click
```
,
```
click_text
```
,
```
fill
```
,
```
type
```
,
```
press
```
,
```
wait
```
提取：
```
eval_js
```
,
```
get_url
```
,
```
snapshot
```
图片/文本操作：
- ```
copy_text
```
  ,
```
paste_text
```
- ```
copy_image
```
  （元素/剪贴板截图）
- ```
copy_image_original
```
  （优先获取原始图片字节）
- ```
paste_image
```

输出/验证：

```
write_markdown
```
,
```
append_markdown_section
```
```
assert_markdown
```
,
```
assert_file
```

人工接管：
```
human_handoff
```

截图粒度：

全页截图（
```
full_page: true
```
）
选择器裁剪（
```
selector
```
）
坐标裁剪（
```
clip: {x,y,width,height}
```
）

当用户要求“保存原始图片”时，优先使用

copy_image_original

而非截图。

Retrieval and Replay Workflow

检索与重放工作流

Normalize intent into
```
{site, task_type, intent, vars}
```
Run replay-first
If replay misses/fails, run fallback steps
On success, persist trajectory
Compare
```
summary.json
```
```
mode
```
and latency (
```
replay
```
vs
```
explore
```
)
For grep-first manual selection, search
```
trajectories/ready/
```
first.

将意图标准化为
```
{site, task_type, intent, vars}
```
执行重放优先流程
若重放失败/未命中，执行回退步骤
成功后持久化轨迹
对比
```
summary.json
```
中的
```
mode
```
和延迟（
```
replay
```
vs
```
explore
```
）
对于grep优先的手动选择，优先搜索
```
trajectories/ready/
```
目录。

JSON Editing Policy

JSON编辑规则

Edit the smallest possible segment
Keep selectors stable and robust
Keep variable input externalized (
```
{{vars.xxx}}
```
)
Keep branch count <= 2
Keep
```
assert_*
```
checks at the tail

仅编辑最小必要片段
保持选择器稳定且健壮
将变量输入外部化（
```
{{vars.xxx}}
```
）
分支数量不超过2个
将
```
assert_*
```
检查放在末尾

Single-Line Match Field (Required)

单行匹配字段（强制要求）

For grep-first low-token retrieval, each JSON should include one reserved single-line field:

json

"amw_match_line": "amw site:example.com task:example_task flow:example_v1 key:foo key:bar key:<zh_keyword>"

Strict rules:

```
amw_match_line
```
must stay on one physical line (no
```
\n
```
or wrapped multi-line values).
Use ASCII tags only:
```
site:
```
,
```
task:
```
,
```
flow:
```
,
```
key:
```
.
Chinese is allowed in
```
key:
```
values when files are UTF-8 encoded.
Do not remove
```
amw
```
anchor token.
Prefer adding new
```
key:
```
tokens instead of changing
```
flow:
```
unless behavior truly changes.

For human verification:

Detect blocker (
```
eval_js
```
or error symptoms)
Save required artifact (
```
copy_image_original
```
preferred)
Pause with
```
human_handoff
```
Resume normal flow

For reserved branch fields, follow

references/json-two-branch-contract.md

为了支持grep优先的低token检索，每个JSON需包含一个预留的单行字段：

json

"amw_match_line": "amw site:example.com task:example_task flow:example_v1 key:foo key:bar key:<zh_keyword>"

严格规则：

```
amw_match_line
```
必须保持在同一物理行（不能有
```
\n
```
或换行）。
仅使用ASCII标签：
```
site:
```
,
```
task:
```
,
```
flow:
```
,
```
key:
```
。
若文件为UTF-8编码，
```
key:
```
值中可包含中文。
请勿移除
```
amw
```
锚点标记。
除非行为确实发生变化，否则优先添加新的
```
key:
```
标记而非修改
```
flow:
```
。

人工验证流程：

检测阻塞项（
```
eval_js
```
或错误症状）
保存所需工件（优先使用
```
copy_image_original
```
）
通过
```
human_handoff
```
暂停
恢复常规流程

预留分支字段请遵循

references/json-two-branch-contract.md

。

Debug Protocol

调试协议

On failure, inspect in order:

```
summary.json
```
(
```
failed_step_id
```
,
```
reason
```
,
```
mode
```
)
```
events.jsonl
```
(
```
step_error
```
, timeout, guard failure)
Artifact correctness in
```
artifacts/
```

Patch only the failed segment, then re-run once in headed mode. For fallback verification, add

--disable-replay true

so replay memory does not mask issues.

失败时，按以下顺序检查：

```
summary.json
```
（
```
failed_step_id
```
,
```
reason
```
,
```
mode
```
）
```
events.jsonl
```
（
```
step_error
```
, 超时，守卫失败）
```
artifacts/
```
目录中工件的正确性

仅修复失败片段，然后在带界面模式下重新运行一次。验证回退流程时，添加

--disable-replay true

参数，避免重放记忆掩盖问题。

Command Templates

命令模板

Run:

npm run amw -- run --site <site> --task-type <task_type> --intent "<intent>" --fallback-steps-file ./trajectories/ready/<file>.json --store-dir ./data/<store> --session <session> --headed true --hold-open-ms 30000

Run (force fallback):

npm run amw -- run --site <site> --task-type <task_type> --intent "<intent>" --fallback-steps-file ./trajectories/tmp/<file>.json --store-dir ./data/<store> --disable-replay true

Validate JSON:

npm run amw -- validate --steps-file ./trajectories/tmp/<file>.json

Inspect:

npm run amw -- list --store-dir ./data/<store>

npm run amw -- search --site <site> --task-type <task_type> --intent "<intent>" --store-dir ./data/<store>

Grep-first retrieval (AND by chain):

rg -n --glob "*.json" "\"amw_match_line\"\\s*:\\s*\".*\"" trajectories/ready | rg -i "amw" | rg -i "site:<domain>" | rg -i "task:<task_type>" | rg -i "<keyword_or_zh_keyword>"

运行：

npm run amw -- run --site <site> --task-type <task_type> --intent "<intent>" --fallback-steps-file ./trajectories/ready/<file>.json --store-dir ./data/<store> --session <session> --headed true --hold-open-ms 30000

强制回退运行：

npm run amw -- run --site <site> --task-type <task_type> --intent "<intent>" --fallback-steps-file ./trajectories/tmp/<file>.json --store-dir ./data/<store> --disable-replay true

验证JSON：

npm run amw -- validate --steps-file ./trajectories/tmp/<file>.json

检查：

npm run amw -- list --store-dir ./data/<store>

npm run amw -- search --site <site> --task-type <task_type> --intent "<intent>" --store-dir ./data/<store>

Grep优先检索（链式AND匹配）：

rg -n --glob "*.json" "\"amw_match_line\"\\s*:\\s*\".*\"" trajectories/ready | rg -i "amw" | rg -i "site:<domain>" | rg -i "task:<task_type>" | rg -i "<keyword_or_zh_keyword>"