AmberFlow

冻结计划的浏览器自动化中间件（TypeScript / Node ≥ 22.6）：LLM 只规划一次，执行由本地规则与决策模型逐步完成，演示一次后既可端侧执行，也可以手动规划。

规则保证可复现，Laya 保证不轻言放弃，信号保证不作弊。

安装运行

npm ci && npx playwright install chromium
npm start          # 在仓库自带页面上跑一份真实计划：离线、零配置
npm run doctor     # 环境体检：Node / chromium / 决策模型 / LLM，缺什么给什么命令

成功的样子（npm start 会逐步打印判定依据，最后一行是结论）：

step 1: click a "Add to cart" (clicked, rule:match, conf=1.00)
结果：2/2   步骤 2   跳过 0   重试 0

npm start 会把计划检查点写进仓库根 .task_plan.json（跑完 git status 会看到它）；不想动工作区就加 --plan /tmp/my-plan.json。

没有模型权重也能跑：计划点名了目标的步骤由规则解决；确实需要模型兜底的步骤会明确说明缺什么，而不是瞎猜或抛异常。

DSH 插件安装

装进 profile 即得三个工具——amberflow_apps（列应用）/ amberflow_run（跑一个，含 dry / no_model / slots）/ amberflow_learn（录制归纳）：

dsh plugin --profile <名称> add github:Johnly1986/AmberFlow          # 仓库直装（见 README 附注：私有库需凭证）
dsh plugin --profile <名称> add /绝对路径/AmberFlow/integrations/dsh-bridge   # 开发态 link

或在插件页面直接添加项目地址。

三条硬约束

• 不重规划——任务开始时冻结成一份计划（有序子目标 + 每步完成信号 + 数据袋），执行器只按计划推进。
• 不发明取值——要填的值只来自计划的数据袋（slots），模型无权产生值。
• 不信模型说"完成"——子目标完成与否由该步自己的 DOM/URL 信号判定，模型判断仅作记录。

分工原则：规则先于模型——计划 target_hint 点名目标即零成本解决，规则拿不准才问本地模型，模型也不过confidence闸门才考虑升级（默认不接外部 LLM）。

为什么本地还养一个模型

模型不是英雄，是保险；保险的价值要可核对。四组数字，每组都有当场可跑的复现命令：

数字	它证明什么	怎么复现
60 个诱饵元素挡在前面：规则落空 + 目标不在池内 = 必 blocked；模型加宽重看（laya:reobserve）把它捞回来	池子外的目标谁也选不到——模型负责"不轻言放弃"	npx vitest run tests/reobserve.test.ts
transfer-slowjet：冷加载的那一问就是模型的活；去掉 retries 实测 0/7（0.16 < 0.25 直接 block）	没有模型这个应用会红——apps:suite 的"模型步"列明写 ≥1	npm run apps:suite -- --only transfer-slowjet
同一份计划二跑：12 forwards → 0，9.2s → 1.3s（Windows+GPU 实测；离线口径由套件页脚 决策缓存 给同一形状的两个数）	确定性模型不该被问第二次：本地、免费、可审计	npm run cache:measure（要 ONNX 产物）；离线看套件页脚
诚实边界：中文页面上模型 0.03–0.09（argmax 常仍正确）；checkpoint 路由按文字系统切、绝不按置信度切（ECE 0.855 的教训写进了故事）	我们比谁都清楚它不行在哪——这是可信度，不是减分	node --experimental-strip-types src/ctrip-task.ts --no-hints

装不装得模型，跑之前就知道：npm run doctor 点名缺哪件（图 / 外置权重 / tokenizer）并给出一条补齐命令 npm run model:fetch -- --from <url 或本地路径>（SHA256 先验后换，坏件绝不覆盖现有产物）。 跑完之后，每次运行的结果里都有两行：model: on|off(missing) 与"决策来源"一行 （rule 19 · laya 1 (conf 0.31) · laya:reobserve 1 · cache 命中 6/12 forwards）—— CLI 报告、apps:suite 表格与 DSH 插件 amberflow_run 的 summary 念的是同一份账。

把你的流程固化成应用

一个应用 = 一个目录 apps/<id>/pack.json（纯数据）：数据腿 + 旅程（浏览器步 / 命令行工具步）+ 结束状态不变量。加一个应用不需要改共享层一行代码。

npm run apps -- --list                                  # 有哪些应用
npm run apps -- --app demo-app --no-model               # 离线整跑一条完整链路
npm run apps -- --app demo-app --dry                    # 只展开计划，不开浏览器
npm run apps:suite                                      # 全部离线应用跑完，一行一个给结论

三类入口，同一个引擎，同一道门槛——规则模式零模型重放通过，才落盘：

你手上有	入口
一个浏览器 + 会点鼠标	npm run learn——连上你正开着的浏览器（--cdp）或给 --url，做一遍，信号与不变量自动归纳，你只回 y/n
一份 spec / Excel / 代码里的计划	npm run apps:gen -- --spec <key>（--check 可进 CI：改 spec 忘重新生成就会红）
只想手写	复制下面的最小 pack.json 起个新目录

最小可跑的 pack.json（选择器用仓库自带页面，复制即跑）：

{
  "spec_version": 1,
  "id": "hello",
  "label": "最小离线应用",
  "goal": "在门户页进入枪机/筒机录入",
  "journey": [{
    "desc": "点击「枪机 / 筒机 录入」",
    "start_url": "testpages/portal.html",
    "target_hint": "[data-test=entry-fixed]",
    "signal": { "url_contains": "camera_a.html" }
  }],
  "invariants": [
    { "id": "on-camera-a", "desc": "结束时停在 camera_a 录入页",
      "signal": { "url_contains": "camera_a.html" } }
  ]
}

npm run apps -- --app hello --no-model --out /tmp/hello   # 期望 exit 0 + "结果：**通过**"

两条省时间的规则：浏览器步必须点名得到目标（target_hint，或规则能在元素池里命中）；--slot k=v 的键必须在包里声明过（打错名字是用法错误，不是静默忽略）。

在代码里用

import { BrowserMiddleware, TaskPlan, runPlan } from "./src/index.ts";

const plan = new TaskPlan("把无线鼠标加入购物车并打开购物车页", [
  { desc: "加入购物车",
    signal: { css_text_equals: ["[data-test=cart-count]", "1"] },   // 完成只认这个信号
    start_url: "https://example.com/product.html",                  // 换成你的页面；pack 层支持仓库相对路径
    target_hint: "[data-test=add-to-cart]" },                       // 点名目标 → 零模型调用
], ".task_plan.json", { /* slots：取值只来自这里 */ });

const rep = await runPlan(new BrowserMiddleware(), plan);
console.log(rep.completed, rep.traces.length);

命令速查

命令	一句话
npm start -- --goal "…" --url <页面>	打开页面演示一次 → 归纳信号 → 执行（--dry-run 只看计划，--headful 显形浏览器）
npm run plan-cli -- --help	手工编排：new / add / edit / check / run（支持 when 条件跳过、retries 整步重试）
npm run verify	一键门禁：typecheck + 全部测试 + 六层跨实现对拍
npm run apps:matrix	每个应用的声明成本 / 来源（生成还是手写）/ 站点知识泄漏门禁
npm run bench -- --cases bench/cases-live.json --mode-tag live	8 个真实站点跑分（要真网络；跳过不等于通过）

环境变量（都有兜底，全部可不配）

变量	作用
LAYA_ONNX_MODEL / LAYA_TOKENIZER_DIR	本地决策模型产物位置（缺了走规则模式）
OPENAI_BASE_URL + OPENAI_API_KEY	启用 LLM 规划与审计（不配则用内置替身，流程照常）
AMBERFLOW_REPO	DSH 桥指向的 checkout（旧名 LAYAWEBUSE_REPO 仍兼容）

延伸阅读

ARCHITECTURE.md（模块结构与实测规则）· CLAUDE.md（工程规约）· apps/INVENTORY.md（应用清单与"完成"的定义）· PORTING.md / BACKUP.md（Python 参考实现的迁移与存档）

License

Apache-2.0