--- name: ego-decision-layer description: 多步线性浏览器任务（连续点击、翻页、搜索表单提交、导航跳转）的默认入口：用 `ego-decision-layer` 一条命令让决策层在单个 ego-browser 进程内闭环决策（默认 System One / Jev，可换本地 OpenAI 兼容后端；browser automation / multi-step click chain / form submit / navigation），不再每步退回大模型思考。单步动作、精确 DOM/选择器、批量抓取仍走 ego-browser 原生 API；也可把官方 ego-browser 技能入口接管成路由层。当任务涉及浏览器多步操作、要写 ego-browser nodejs 脚本（await import / fetch / 凭证落盘）时读它。 metadata: version: "0.4.4" date: "2026-09-26" requires: ego-browser --- # ego-decision-layer — 给 ego-browser 装一个可插拔的决策层 这是一个**附加技能（外挂）**：它只存在于 Agent 的技能目录里（如 `~/.agents/skills/ego-decision-layer/`）， **不修改 ego lite 应用包里的任何文件**，因此 ego lite 升级不会把它冲掉。 本技能的组成（都在本 SKILL.md 所在目录内）： | 路径 | 作用 | | --- | --- | | `scripts/decider-loop.mjs` | 引擎（决策闭环、元素表解析、退出判定） | | `scripts/ego-decision-layer` | 命令行入口（会自动在 同目录 / 仓库根 / `~/.agents/lib/` 里找引擎） | | `scripts/wire-agent-skills.sh` | 把 Agent 技能目录里的官方 `ego-browser` 入口接管成**路由层**（见下节） | | `overlay/ego-browser/SKILL.md.in` | 路由层的模板（接管时生成，正文仍指向 App 当前版本） | | `examples/bench/` | 对照基准脚本（A 组 Jev 闭环 vs B 组经典循环） | 命令行两种调用方式，任选其一： ```bash ego-decision-layer --url "…" "目标" # 已链接进 PATH 时 "<本技能目录>/scripts/ego-decision-layer" --url "…" "目标" # 直接用技能内的入口 ``` 基础用法、Space/Page/选择器/收尾纪律仍以 `ego-browser` 技能为准；本技能只负责「让 Jev 加速」这件事。 ## 路由：什么时候用我 | 任务形状 | 走哪条路 | | --- | --- | | **多步线性**：连续点击、翻页/下一页、搜索框输入并提交、多字段表单、导航到目标页 | **本技能**（`ego-decision-layer` CLI 或 `runJevAutonomousLoop`） | | 单个动作；需要精确选择器/DOM、批量抽取、截图、文件、网络请求、CDP | `ego-browser` 原生 API（读官方技能） | | 内容生成、业务判断（回什么话、选哪个商品、写哪段文案） | 大模型决定，把决定喂给上面两条 | **但「默认用哪个」不能只靠这段表格**：ego lite 会把官方 `ego-browser` 技能写进每个 Agent 的技能目录 （`~/.agents/skills/ego-browser`、`~/.claude/skills/ego-browser` …，由 App 在安装/升级时重建）， 而官方正文不知道 ego-decision-layer 存在 —— 于是 Agent 默认照它写逐步脚本。用本技能的接管脚本把这个入口换成 **路由层**，Agent 先看到的就是上面的路由规则。**`install.sh` 默认就接管；`ego-decision-layer` CLI 首次运行时 也会在检测到官方入口时补一次**（`EGO_JEV_NO_WIRE=1` 关闭）： ```bash bash scripts/wire-agent-skills.sh # 接管/刷新（幂等；只写 Agent 技能目录，不碰应用包） bash scripts/wire-agent-skills.sh --check # 只读：已接管 N / 无需接管 M / 漂移 K（漂移则 exit 1） bash scripts/wire-agent-skills.sh --restore # 还原成官方软链（启用标记与 always-on 块一并清掉） ``` 接管后：入口是包外的一层 `SKILL.md`，正文仍软链到 App 当前版本的官方技能（升级自动跟随）， 只有「先路由、再决定写不写脚本」那一段是本技能加的。`update.sh` 与 `ego-decision-layer` CLI 都会自动重接管 （ego lite 升级会把入口还原）。**应用包内任何文件都没动。** `--restore` 是**粘性**的：它记下「不接管」的选择，之后 CLI 首跑不会自动接管回去； 重新启用要显式跑一次接管（`bash scripts/wire-agent-skills.sh`）。 想让它**在读技能之前**就知道路由：`bash scripts/wire-agent-skills.sh --always-on AGENTS.md` （显式开关，默认不写任何用户文件；块带标记、幂等、可 `--restore` 精确移除）。 路由状态可事后审计：`ego-decision-layer --route-status`（只读 JSON，不起浏览器、不要凭证）。 **派浏览器任务给子代理时必须显式点名**：实测子代理 / 一次性无会话上下文的上下文里既没有技能清单、 也没有任何 AGENTS.md 内容，接管与 always-on 都到不了它们。`ego-decision-layer --handoff-prompt` 打印一段可直接粘贴的指派块（路由判据 + 解析后的技能目录 / CLI / SKILL.md 真实路径 + 可照抄的命令模板， 结尾提示用 `--route-status` 核对）；`--handoff-prompt --json` 给机器可读的 `{prompt, skillDir, cliPath, skillMdPath}`。只读选项，不起浏览器、不需要凭证。 ## 加速能力 多步按钮点击、翻页、搜索表单、导航跳转这类「下一步做什么很明确」的线性任务，不要每走一步都 退出来交给大模型慢思考。可以让 Jev（TypeSafe System One）在单个进程内闭环决策执行。 实测（2026-09-26, 服务端 `jev-1.13.0`，维基百科搜索任务）：单步（观测+决策+执行+校验）约 **1.0–1.4s**，其中**决策请求本身约 0.35–0.52s**（10 次采样 352–524ms，中位 434ms）， **执行（派发 + 稳定等待）约 0.56–0.99s 是当前单步的大头**；分阶段数字由 `renderJevSummary` 打印。旧文档的「单步决策约 1.0–1.5s」实为**整步耗时**，不是决策请求本身。 **对照实测**（同任务、同元素表、同验证器， 交替 3 轮取中位数）： | 任务 | Jev 单进程闭环 | 经典循环（每步一进程 + 大模型思考） | 结果 | | --- | ---: | ---: | --- | | HN 两步复合导航 | 中位 **4.9s**（1 进程，12 次浏览器调用） | 中位 **9.7s**（3 进程） | Jev 快 **~2.0×** | | 维基百科搜索（两组都要生成文本） | 中位 **5.4s**（1 步） | 中位 **10.1s**（2 进程） | Jev 快 **~1.9×** | 差异主要来自**决策延迟**：Jev 决策请求约 0.35–0.52s/次（整步合计约 1.0–1.4s），而可用大模型 1.6–4.5s/次（实测 kimi-k3 1.8s、 minimax-m3 1.6s、glm-5.3 3.2s、qwen3.8-max 3.5s、deepseek-v4-pro 4.5s；gpt-5.6-luna 与 grok-4.6 端点 503 不可用）。进程启动实测只占约 250–350ms/次，**不是**主要成本。 样本只有 3 对/任务且**方差很大**（经典组单轮 7.3s–22s，上述是不同批次中更好的那批）， 不构成基准；只能说量级上 Jev 闭环约为经典循环的一半时间。基准脚本在 仓库的 `examples/bench/` （`run-pair.sh` + `arm-a.js` / `arm-b-step.js`）。 测量纪律：请求里写的是浮动别名 `jev-latest`，**服务端实际服务哪个版本只有响应里的 `model` 字段能回答** ——每次测量都要记下它（`renderJevSummary` 会打印），否则事后无法判断数字属于哪版模型。 2026-09-26 曾出现约 5 分钟的 `403 RBAC: access denied`（凭证文件完好，随后自愈）：环境本身会变， 只记「能跑通」不够。 **Jev 快在哪里、不快在哪里**：省的是**决策往返**（Jev 决策请求 0.35–0.52s/次 vs 大模型 1.6–4.5s/次） 和**每步退出浏览器上下文**的开销。引擎自身也已重构（详见仓库 `PORT-REPORT.md`）：观测改成一次 `page.evaluate` 自建 DOM 元素表（约 2–4ms，替代 110–130ms 的 `page.snapshot()`），动作改成**裸 CDP `Input.dispatchMouseEvent`**（13–16ms，替代 788–1005ms 的 `page.click`），等待改成可观察条件。 HN 两步导航端到端因此从 4569ms 降到 1675ms。目标能用选择器写死时，直接写代码仍比两者都快。 **凭证**：`ego-browser nodejs` 内嵌运行时只继承最小化登录环境（HOME/PATH 等），shell 里 export 的变量不会传进去，所以凭证只能来自文件。查找顺序： `--api-key` > `TYPESAFE_API_KEY`（仅普通 node 进程可见）> `TYPESAFE_API_KEY_FILE` > `~/.config/ego-decision-layer/credentials` > `~/.config/typesafe/api_key` > rc 文件（`~/.zshrc`/`~/.bashrc`/ `~/.bash_profile`/`~/.profile`）里的 `export TYPESAFE_API_KEY=…`。所以已经 export 过 key 的机器 不必再落盘一次。`~/.config/typesafe/api_key` 仍是「一行裸 Key」的既有形态（权限 600）； 文件都找不到时 CLI 直接报错 exit 3。后端地址 `TYPESAFE_BASE_URL` 可覆盖，主后端失败时的 降级端点 `TYPESAFE_FALLBACK_BASE_URL`（不设即不降级，`fallback: false` 可关）；**这两个变量由 CLI 在父进程读取后写进配置传给子进程**（ego 运行时自身读不到自定义环境变量），直接写 `ego-browser nodejs` 脚本时用 `options.baseUrl` / `options.fallbackBaseUrl`。 **没凭证也能先自测**：`ego-browser nodejs < bench/test-offline-e2e.mjs` 在 `about:blank` 上注入 DOM， 用 `options.ask` 注入确定性判定器（不联网、不需要 key），但观测、`locate`、裸 CDP 派发、真实 DOM 断言 全走真实路径，并断言整个用例一次 `fetch` 都没发。判定器注入契约：`options.ask(state, questions, options)`， 与引擎自己的 `askJev` 同签名；默认仍走 TypeSafe。 **决策后端可换**：契约形如 `decide({ state, questions, options }) → { answers, meta }`；默认 System One （语义不变），配置 `~/.config/ego-decision-layer/decider.json` 可切到本地 OpenAI 兼容端点 （`kind: "openai-compatible"`），CLI 用 `--decider` / `--base-url` / `--model` 覆盖。本地文本模型 没有校准置信度（`capabilities.confidence: false`），引擎跳过置信度阈值升级但保留全部执行层护栏 （陈旧 / `guardRejected` / 跨 frame fail-closed / 危险动作拦截 / 候选合法性校验）；细节见 README。 **决策结构**（对齐 [browser-use/jev-ultrafast](https://github.com/browser-use/jev-ultrafast) 的 dynamic operation + target）：每次观测产出「索引化元素表」，每个可交互元素一个 `ref`，并携带 当前值；一次请求同时问 **operation** 和各操作的 **target**（推测性问题，彼此不可见）； 每个 target 头只列出与它兼容的元素，executor 只消费命中操作对应的那个头。 ``` ref=2 | textbox | "Query Field" | 当前值="hello world" ref=4 | checkbox | "Subscribe Newsletter" | 未勾选 ref=6 | combobox | "Country Select" | 当前值="Japan" | 选项=[Switzerland|Japan|Germany] ref=10 | anchor | "Next Page" | /next operation: click / type_text / type_text_submit / select / scroll_up / scroll_down / wait / done / blocked └─ 只列出当前页面受支持的操作 click_target ← 只含可点元素（按钮/链接/复选框，不含输入框与原生下拉） type_text_target ← 只含可输入元素（textbox/searchbox/textarea） select_target ← 原生下拉，候选写成 元素#选项序号（如 ref=6#2） ``` `done` / `blocked` 就是 operation 之一，不另设概率阈值；复选框/单选不会被当成可编辑元素。 原生下拉的选项索引与勾选态快照不暴露，由引擎额外做**一次**批量页面调用补齐。 1. **终端一行命令直接驱动**（在任何项目与路径下可用）： ```bash # 简单目标 ego-decision-layer --url "https://example.com" "点击登录按钮并聚焦输入框" # 需要输入文本：候选由调用方给，Jev 只负责选字段和选哪段文本 ego-decision-layer --url "https://en.wikipedia.org/wiki/Main_Page" --text "Jev" \ --until "/wiki/Jev" "在页面顶部的搜索框中输入并提交搜索" # 让模型自己写文本（已配置好，无需 --text） ego-decision-layer --url "https://en.wikipedia.org/wiki/Main_Page" "在维基百科搜索框里搜索哥德尔不完备定理" # 复用已有 space，并在完成后保留 space 供人工检查 ego-decision-layer --space 3 --keep-space --steps 15 "点击未发送帖子并保存" ``` `--until ` 给确定性退出条件（URL 包含该子串即判成功），比依赖 Jev 自评 `done` 可靠得多， 强烈建议带上。退出码 0 表示成功，1 表示未达成目标（此时 space 会被保留供排查）。 #### 文本生成配置（`~/.config/typesafe/text_model.json`，当前指向 opencode-go） ```json { "baseUrl": "https://opencode.ai/zen/go/v1", "apiKeyJson": { "file": "~/.pi/agent/auth.json", "path": "opencode-go.key" }, "model": "deepseek-v4.1-flash", "sessionHeader": "x-opencode-session", "sessionId": "ego-decision-layer", "userAgent": "ego-decision-layer/1.0", "headers": { "x-opencode-client": "ego-decision-layer" } } ``` - `apiKeyJson` **引用已有凭证文件**而非复制密钥；也可直接写 `apiKey`。 - `opencode-go` 必须带 `x-opencode-session`（稳定会话 id，用于路由与提示缓存）， 缺它直接 400 `MissingSessionID`。 - 实测 `deepseek-v4.1-flash` 会输出 `reasoning_content`，**`reasoning:{enabled:false}` 无效**， 生成耗时 1.3–1.9s；答案在 `content` 字段，引擎只读它。带生成的整步约 3.8s。 2. **在任何 `ego-browser nodejs` 脚本中导入复用**： ```js import { runJevAutonomousLoop } from "<本技能目录>/scripts/decider-loop.mjs"; // Jev 在当前页面自主连续操作，直到 check 通过或 Jev 判定 done const result = await runJevAutonomousLoop(page, "依次打开 new 页面，再打开 comments 页面", { maxSteps: 8, text: ["Jev"], // 可填文本候选（可选） check: async (p) => (await p.url()).includes("/newcomments"), // 确定性成功条件（推荐） }); console.log(result); // { success, reason, steps, history } ``` 配套导出：`askJev(state, questions, options)` 做单次判断、`parseActionTargets(snapshot)` 把快照解析成元素表（含 kind/当前值）、`enrichTargets(page, targets)` 一次批量调用补齐下拉选项与 勾选态、`buildQuestions(targets, { texts, hasTextSource })` 组装操作/目标问题、 `buildActionMenu()` / `extractCandidateRefs()` 构建动作菜单与提取候选目标、 `validateChoice(response, questions)` 响应校验（拒收非 argmax 或概率和不一致的响应）、 `generateText(input, options)` / `loadTextModelConfig()` 文本生成、`runJevStep(page, goal, options)` 走一步。 ### 边界（实测） > **滚动密集站点（含 X）：本文件此前写它们“不可用”，那条警告已作废**——它依据的 0/15 是用有缺陷的 > harness 测出来的（锚点在**一次**页面加载里测量、任务却在**另一次**加载里跑；X 时间线每次加载内容都变， > 锚点帖往往已不存在，引擎再强也点不中。见 `bench/reveal-tasks.js:137` 与 `:181`）。 > 有效的配对测量（4 任务 × 2 引擎 × 6 轮，详见 `BH-PORT-REPORT.md`）： > > | 场景 | 改动前 | 改动后 | > | --- | --- | --- | > | X 上必须连滚 >3 次的深帖任务（`x-far`） | **0/6**（6 次全 `stuck`） | **6/6** | > | X 合计（已剔除“锚点找不到”的不可测轮） | 14/20 | 18/18 | > > 机制：**滚动若真的移动了视口、或露出新元素，就算作进展**（移植自 browser-harness 的 `fingerprint()` 思路；本项目**不依赖**它）； > 到页面边界仍会停，`maxSteps` 仍是硬上限。**emoji 截断已修**（按码点截断 + 请求前清理孤立代理， > X 上 34 次运行 0 次 Jev 400）。 > > 仍然成立的两条限制： > - **「有界滚动揭示」在真实站点几乎不触发**（它只在“选了需要目标的动作却解析不出目标”时生效； > 真实长列表里 Jev 会自己滚或点相似链接）——但它已不是必需品，滚动本身现在能推进目标。 > - Jev 若在页面边界反复交替上/下滚，仍可能跑到 `maxSteps`（有界，但不优雅；实测未遇到）。 - **新建标签页视口 0×0 是宿主常态（本机实测，不是异常）**：本机 ego lite 0.5.1.13 上， `taskSpace` 新建的标签页在**未导航 / `goto(domcontentloaded)` 之后 / `load` 之后**读到的 `window.innerWidth/innerHeight` **全是 0×0**，`page.info()` 也拿不到尺寸；覆盖是 **per-space / per-page** 的，**紧接着新开的 space 仍是 0×0**（不会跨运行生效）。元素表按 **视口可见性**构建（既有设计，不是 bug），0×0 时恒为空 → 不处理就是每轮 `no_targets` + 700ms 等待，**白烧步数且一次模型都没问**（决策 0ms），用户还看不出原因。所以**默认行为是自动撑起**： 循环入口读一次视口（`page.evaluate`，不新增 CDP），任一为 0 时自动 `Emulation.setDeviceMetricsOverride { width: 1280, height: 900, deviceScaleFactor: 1, mobile: false }` 并打印一行说明，然后照常跑；**视口本来正常时不做任何覆盖调用**（零额外 CDP）。 `--force-viewport <宽x高>[@缩放]`（库 `options.forceViewport`）指定尺寸（优先于自动值）； `--no-force-viewport`（库 `options.strictViewport: true`）才回到「退化直接失败」； **只有自动撑起也失败**（CDP 报错）或显式 strict 时才以 `viewport_degraded` 失败 （`steps: 0`、不派发、不问模型）。退出时按需用 `Emulation.clearDeviceMetricsOverride` 清理 （保留了 space / 页面时不清理），**清理结果如实报告（不谎报“已清除”）**：本机 0.5.1.13 实测， 同进程调过 `clearDeviceMetricsOverride` 之后 `innerWidth/innerHeight` 仍显示覆盖值。 **来源**：0×0 常态与症状由另一个 Agent harness（Hermes Agent）在本机真实运行中发现； 0.4.2 曾把它当异常硬失败（在本机正常路径上就是回归），0.4.3 改回默认自动撑起。 - Jev 只发一次并行判断、**无跨请求记忆**：复合目标（A 然后 B）依赖引擎回填的「已完成步骤」， 已内置并已验证（两步导航、已填字段改写、下拉改选、勾选均通过）。更长链路未做专项评估。 - 元素表由**一次 `page.evaluate` 在页面内自建**（默认 `maxTargets` 60 项、可见文本 `maxText` 2500 字符），元素每次观测都会**重新编号**。候选分两遍收集：原生交互标签与 `role=…`（a11y 类， **优先占预算**）先收；再把**无 role 的容器型可点元素**（`
`、`tabindex`、 `cursor:pointer` 块级容器）补成 `clickable-region`（映射到 `kind: clickable`，自动进入同一套 点击决策）。去重：节点身份 + 祖先去重（嵌套容器只收最内层）；被占满的容器（内含 a11y 元素 且占了它一半以上面积）、`` 里的容器、`