ego-decision-layer

Files (200)

• marketplace.json · .claude-plugin/
• plugin.json · .claude-plugin/
• dependabot.yml · .github/
• ci.yml · .github/workflows/
• .gitignore
• AGENTS.md
• BH-PORT-REPORT.md
• CHANGELOG.md
• EGO-SWITCH-REPORT.md
• FIX-REPORT.md
• LICENSE
• PORT-REPORT.md
• README.md
• REVEAL-REPORT.md
• ROADMAP.md
• SECURITY.md
• SKILL.md
• THIRD-PARTY-ASSESSMENT.md
• THIRD-PARTY.md
• VERIFY-REPORT.md
• analyze-fix.mjs · bench/
• analyze-verify.mjs · bench/
• analyze-vs-bstack.mjs · bench/
• baseline-engine.mjs · bench/
• bh-port-summary.mjs · bench/
• debug-nav.js · bench/
• delayed-nav.js · bench/
• click-focus.mjs · bench/ego-switch/
• cnki-v2.mjs · bench/ego-switch/
• draft-verify.mjs · bench/ego-switch/
• editor-dom.mjs · bench/ego-switch/
• focus-diag.mjs · bench/ego-switch/
• reply-click.mjs · bench/ego-switch/
• skill-step1-verbatim.mjs · bench/ego-switch/
• skill-step4-run.mjs · bench/ego-switch/
• tl1-lifecycle.mjs · bench/ego-switch/
• tl1-v2.mjs · bench/ego-switch/
• fix-baseline-engine.mjs · bench/
• fix-hn-page2.js · bench/
• fix-noregress.js · bench/
• isolation.js · bench/
• lib.mjs · bench/
• measure-real-settle.mjs · bench/
• obs-cost.js · bench/
• probe-click.js · bench/
• probe-click2.js · bench/
• probe-latency.js · bench/
• probe-raw.js · bench/
• probe-step.js · bench/
• delayed-nav-2026-09-19T14-08-36-040Z.json · bench/raw/
• delayed-nav-2026-09-19T14-12-06-421Z.json · bench/raw/
• delayed-nav-2026-09-19T14-13-36-308Z.json · bench/raw/
• delayed-nav-2026-09-19T14-26-53-660Z.json · bench/raw/
• delayed-nav-2026-09-19T14-41-58-159Z.json · bench/raw/
• delayed-nav-2026-09-19T15-00-41-870Z.json · bench/raw/
• delayed-nav-2026-09-19T16-10-06-198Z.json · bench/raw/
• delayed-nav-2026-09-22T09-02-33-690Z.json · bench/raw/
• ego-switch-click-focus.json · bench/raw/
• ego-switch-cnki-search-v2.json · bench/raw/
• ego-switch-cnki-search.json · bench/raw/
• …and 140 more

SKILL.md (first lines)

# 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/run-cdp-task.mjs` | 普通 Node + 外部 Chrome CDP 入口（v0.11.0 起） |
| `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 "…" "目标"  # 直接用技能内的入口
```

更新当前安装：`ego-decision-layer update`；更新后运行冒烟：`ego-decision-layer update --test`；
查看版本与 Git 提交：`ego-decision-layer --version`。Git 克隆按当前分支上游 fast-forward，
skills 拷贝按安装记录定向更新本技能并保留原作用域。已跟踪文件未提交改动或更新失败会非零退出，
ZIP / 插件安装无匹配记录时需走原渠道。旧版本先按原渠道更新一次才能获得新子命令。

默认 ego lite 路径的基础用法、Space/Page/选择器/收尾纪律仍以 `ego-browser` 技能为准。

0.11.0 起提供 `--cdp-endpoint <http(s)/ws(s) URL>`：普通 Node 22+ 连接外部 Chrome，创建专属页面，
不要求 ego lite，也不刷新官方技能路由。`--space` / `--keep` 不适用；`--keep-space` 保留新页面。
此入口已通过双宿主受控任务验收，自 `v0.11.0` 起随版本发布（真实 CDP 只在 macOS 上验证）。真实 Jev 的 HN 导航与表单任务可用
`node scripts/../bench/test-host-integration-live.mjs --suite` 复验（需 Node 22+、Chrome 与凭证）；
共同任务集用注入判定器，不能据此宣称模型成功率。

## 路由：什么时候用我

| 任务形状 | 走哪条路 |
| --- | --- |
| **多步线性**：连续点击、翻页/下一页、搜索框输入并提交、多字段表单、导航到目标页 | **本技能**（`ego-decision-layer` CLI 或 `runJevAutonomousLoop`） |
| **结构化数据抽取**：抽取表格/列表/文章标题/链接/价格，无需写 ad-hoc 选择器 | **本技能**（`--extract <instruction>` 或 `extract(page, instruction, options)`，0.6.0 起） |
| 单个动作；需要精确选择器/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`。

From jiangkoumo/ego-decision-layer, MIT.