Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "ego-decision-layer",
"version": "0.9.1",
"version": "0.10.0",
"owner": {
"name": "liuyuchen",
"url": "https://github.com/jiangkoumo"
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "ego-decision-layer",
"version": "0.9.1",
"version": "0.10.0",
"description": "给 ego lite 的可插拔决策层:默认 System One(Jev),可换本地 / 其他 OpenAI 兼容后端;执行层带 fail-closed 护栏。",
"author": {
"name": "liuyuchen",
Expand Down
13 changes: 12 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,25 @@
每个版本按 **新增 / 修复 / 更正 / 未验证** 分组。「更正」记的是被实测推翻的旧结论,
不是新功能;「未验证」如实列出还没测过的边界。

## 未发布
## 0.10.0 — 2026-10-25

### 新增

- `ego-decision-layer update [--test]`(兼容 `--update`):从任意目录更新当前安装,刷新命令入口和已启用的路由。Git 克隆与 worktree 只 fast-forward,skills 拷贝按安装记录与原作用域定向更新。
- `ego-decision-layer --version`:显示技能版本,Git 安装同时显示提交,维护命令无需浏览器、模型或凭证。
- 更新失败、已跟踪文件的未提交改动、固定标签/提交与缺少安装记录时明确非零退出,避免误报更新成功;普通未跟踪文件保留,冲突由 Git 拒绝覆盖;根目录 `update.sh` 保留兼容转发。
- `bench/test-update.mjs`:离线集成验证真实 Git 更新、复制安装作用域、脚本自替换与失败传播,纳入 CI。
- 独立英文入口 `README.en.md`,覆盖安装、更新、快速验证、能力边界与测量复跑入口。
- `ROADMAP.md` 记录后续优先级:Host Adapter、双宿主共同基准、MCP、视觉与决策后端实验,以及有界失败升级。

### 维护

- CI 工作流权限与依赖固定提交加固,并新增安全问题报告说明。

### 未验证

- 本版未新增外部 Chrome 适配、MCP 或内置图像定位模型;相关内容仍为后续规划。
- 跨平台更新集成使用隔离测试验证;完整 Windows 安装与更新端到端未在本次发布中复测。

## 0.9.1 — 2026-10-20

Expand Down
142 changes: 142 additions & 0 deletions README.en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
![ego-decision-layer](docs/banner.svg)

English · [简体中文](README.md)

# ego-decision-layer

A pluggable decision layer for ego lite browser automation. By default, TypeSafe's System One model **Jev** reads an indexed element table and selects an operation and its target in one request. Code handles observation, execution, guards and completion checks. OpenAI-compatible decision backends are also supported.

**Latest release: v0.10.0.** This release adds installation-aware `update` and `--version` commands, this English guide and a prioritized [roadmap](ROADMAP.md). It retains the existing execution engine and Windows path fixes. Download source from the [release page](https://github.com/jiangkoumo/ego-decision-layer/releases/latest).

## Requirements and installation

You need ego lite with a working `ego-browser` CLI. The default Jev backend also needs a TypeSafe API key. This project installs outside the ego lite application bundle.

Install the skill:

```bash
npx skills add jiangkoumo/ego-decision-layer
```

The skill includes its engine and CLI. For a user-level installation at `~/.agents/skills/ego-decision-layer`, invoke the CLI at the path shown below. Adjust it if your agent uses another skill directory.

Alternatively, clone and install:

```bash
git clone https://github.com/jiangkoumo/ego-decision-layer.git
cd ego-decision-layer
./install.sh --test
```

The installer links the CLI into `~/.local/bin` and normally installs a routing overlay at agents' external `ego-browser` skill entries. Use `./install.sh --no-wire` to skip the overlay. It never modifies the ego lite application bundle. The overlay may need refreshing after ego lite synchronizes its official skills.

Claude Code plugin installation is also available:

```text
/plugin marketplace add jiangkoumo/ego-decision-layer
/plugin install ego-decision-layer@ego-decision-layer
```

Keep the Jev key in `~/.config/typesafe/api_key` as one line, with file permissions `600`. The embedded browser runtime does not inherit custom shell environment variables. The CLI resolves credentials in its parent process; scripts running directly inside `ego-browser nodejs` should use credential files. See [SKILL.md](SKILL.md) for the full lookup chain. Never put credentials in this repository.

## Run and verify a task

```bash
"$HOME/.agents/skills/ego-decision-layer/scripts/ego-decision-layer" \
--url "https://en.wikipedia.org/wiki/Main_Page" \
--text "Jev" --until "/wiki/Jev" --steps 5 \
"type Jev into the search box and submit"
```

From a clone, use `./scripts/ego-decision-layer`. If installed on PATH, use `ego-decision-layer`.

Verify all three: exit code `0`, `success: true`, and a final URL containing `/wiki/Jev`. A deterministic completion check returns `check_passed` or `check_passed_after_step`. The model's `jev_done` alone still needs final-state verification.

| Argument | Meaning |
| --- | --- |
| `--url` | Starting URL |
| `--text` | Text to enter; repeat for multiple candidates |
| `--until` | Required substring of the final URL |
| `--steps` | Maximum steps; default 10 |
| `--space` | Reuse an existing TaskSpace by ID |

Exit codes: `0` success, `1` goal not reached, `2` invalid arguments, `3` missing Jev credentials. Successful tasks close their TaskSpace by default. Failed tasks retain it for inspection and report its ID. Prefer URL paths or DOM state over UI-string checks, because automatic translation can change labels.

## Update an installation

Version 0.10.0 introduces:

```bash
ego-decision-layer --version
ego-decision-layer update
ego-decision-layer update --test
```

Git installations fast-forward from the current branch's upstream. Skill copies update only this skill using their recorded source and original installation scope. Dirty tracked files, pinned revisions, update failures and missing installation records produce nonzero exits. Ordinary untracked files are retained; Git rejects collisions. ZIP and plugin installations without matching records must update through their original channel. Older versions need one update through their original channel before these commands become available.

`update --test` runs a real browser smoke test after updating. Maintenance commands do not need a browser, model or key unless a smoke test is requested.

## Capabilities and limits

| Capability | Current behavior |
| --- | --- |
| Linear browser tasks | Observe, decide, execute and verify inside one browser process; use explicit completion checks |
| Execution guards | Reject stale, covered, unavailable and unresolved frame targets before dispatch; a Chinese/English keyword guard blocks matching dangerous actions |
| Structured extraction | `--extract` / `--schema` and `extract()` produce JSON validated against a supported schema subset; schema validity does not prove business correctness |
| Action cache | Validated replay can skip model requests; full URL, control state, text candidates and task context participate in cache identity |
| Action batches | Execute backend-provided action sequences with preflight guards and one final settle; default Jev does not automatically generate batches |
| Canvas/SVG fallback | Scan geometric regions and accept an injected `visualGrounder`; the default single-region strategy clicks its center and does not interpret image pixels |
| Decision backends | Default System One; configurable OpenAI-compatible backends retain execution guards but do not provide calibrated confidence |
| Host support | ego lite today; external Chrome CDP and MCP are planned |

A cache hit with `decideMs = 0` only means the model request was skipped. Observation, validation and execution still take time. Actions with uncertain outcomes stop rather than being blindly replayed. Keyword guards are heuristic, cross-origin iframes are unsupported, and real CAPTCHA handling has not been validated.

For extraction:

```bash
ego-decision-layer --url "https://news.ycombinator.com" \
--extract "Extract the first 5 news titles, links and scores" \
--schema '[{"title":"string","url":"string","score":"string"}]'
```

Extraction needs a separate text-model configuration; see the [full configuration guide](README.md). For library use, import the stable exports from `scripts/decider-loop.mjs`, including `runJevAutonomousLoop`, `runJevStep` and `extract`. The [skill reference](SKILL.md) documents their options and runtime constraints.

## Measurements and reproduction

Published measurements are historical runs under specific host, model and task conditions. They do not establish a current general success rate. Reports preserve corrections and limitations:

- [VERIFY-REPORT.md](VERIFY-REPORT.md): pre-registered paired comparisons and their decision rules.
- [PORT-REPORT.md](PORT-REPORT.md): engine rebuild measurements and phase breakdowns.
- [BH-PORT-REPORT.md](BH-PORT-REPORT.md): scrolling fixes and paired task results.
- [bench/raw/](bench/raw): original measurement data.
- [CHANGELOG.md](CHANGELOG.md): fixes, corrected claims and unverified boundaries.

Reproduce the current single-process arm or compare with the per-step LLM driver:

```bash
cd examples/bench
./run-pair.sh A
./run-pair.sh B kimi-k3
```

Review `task.json`, model configuration and credential paths first. See [examples/bench/README.md](examples/bench/README.md). The historical comparison against another browser stack uses archived raw data and analysis scripts; its old driver is no longer shipped.

Checks that need no browser or credentials:

```bash
node bench/test-update.mjs
node bench/test-release-consistency.mjs
node bench/test-guardrails.mjs
```

The [Chinese guide](README.md) lists browser integration tests and additional reproduction commands. Demo footage is generated from real runs; see [docs/README.md](docs/README.md).

## Next steps

The [roadmap](ROADMAP.md) prioritizes a minimal Host Adapter and an external Chrome CDP connection, a shared deterministic task suite, then MCP. Image grounding, additional decision backends and bounded escalation to a larger model require separate validation. ego lite remains a first-class host.

## Attribution and license

Built on [ego lite](https://github.com/citrolabs/ego-lite), with parts of the observation, response validation and execution architecture adapted from [browser-use/jev-ultrafast](https://github.com/browser-use/jev-ultrafast). See [THIRD-PARTY.md](THIRD-PARTY.md) and [THIRD-PARTY-ASSESSMENT.md](THIRD-PARTY-ASSESSMENT.md) for attribution and scope.

MIT. See [LICENSE](LICENSE).
21 changes: 17 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,14 @@

[![skills.sh](https://skills.sh/b/jiangkoumo/ego-decision-layer)](https://skills.sh/jiangkoumo/ego-decision-layer)

[English](README.en.md) · 简体中文

**给 ego lite 的可插拔决策层:默认 System One(Jev),可换本地 / 其他 OpenAI 兼容后端;执行层带 fail-closed 护栏。**

> **当前能力**:线性操作闭环、结构化抽取、动作缓存、批处理和 Canvas/SVG 图形区域兜底。
> 各能力都有对应测试,见[功能验证](#功能验证);历史性能数据的条件与复跑脚本见[测量与复跑基准](#测量与复跑基准)。
> [`CHANGELOG.md`](CHANGELOG.md) 保留修复记录和被实测推翻的旧结论,代码级溯源见 [`THIRD-PARTY.md`](THIRD-PARTY.md)。
> **最新版 `v0.9.1`**:包含五个阶段的能力与 Windows 路径修复;[发布页](https://github.com/jiangkoumo/ego-decision-layer/releases/latest)提供对应源码下载。不同安装方式的更新规则见[下载与更新渠道](#下载与更新渠道)。
> **最新版 `v0.10.0`**:新增安装感知的 `update` / `--version` 命令、独立英文 README,并记录下一阶段规划;[发布页](https://github.com/jiangkoumo/ego-decision-layer/releases/latest)提供对应源码下载。不同安装方式的更新规则见[下载与更新渠道](#下载与更新渠道)。

> English summary: `ego-decision-layer` replaces the per-step LLM round trip in browser automation with
> [TypeSafe](https://docs.typesafe.ai)'s System One model **Jev**. Jev reads one *indexed element
Expand Down Expand Up @@ -165,15 +167,26 @@ cd ego-decision-layer

### 下载与更新渠道

`metadata.version` 当前为 `0.9.1`。Windows 路径修复来自 PR #2(合并提交 `76ee335`),已包含在 `v0.9.1`。
`metadata.version` 当前为 `0.10.0`。本版新增 `ego-decision-layer update [--test]` 与 `--version`。
Git 安装按当前分支上游 fast-forward,skills 拷贝按安装记录定向更新并保留原作用域;
ZIP / 插件安装没有匹配记录时需走原渠道。旧版本先按原渠道更新一次,才能获得新子命令。
已跟踪文件有未提交改动时更新停止并非零退出,普通未跟踪文件保留,冲突由 Git 拒绝覆盖。

Windows 路径修复来自 PR #2(合并提交 `76ee335`),已包含在 `v0.9.1` 和 `v0.10.0`。
标签对应固定提交;`main` 会继续演进,后续修复合并后可能先于下一个标签提供。

```bash
ego-decision-layer --version
ego-decision-layer update # 更新当前安装
ego-decision-layer update --test # 更新后运行真实浏览器冒烟
```

| 获取方式 | 是否包含 PR #2 的 Windows 修复 |
| --- | --- |
| 新 `git clone`,默认分支 `main` | 是 |
| 跟踪 `main` 的克隆执行 `git pull --ff-only` / `ego-decision-layer update` | 更新成功后包含;工作区有改动时更新会停止并非零退出 |
| 跟踪 `main` 的克隆执行 `git pull --ff-only` / `ego-decision-layer update` | 更新成功后包含;已跟踪文件有未提交改动时更新会停止并非零退出 |
| GitHub 下载 `main` 的 ZIP | 是,内容以下载时的 `main` 为准 |
| 下载 `v0.9.1` 发布页或标签的 ZIP/tar.gz | 是 |
| 下载 `v0.10.0` 或 `v0.9.1` 发布页或标签的 ZIP/tar.gz | 是 |
| 下载 `v0.9.0` 标签的 ZIP/tar.gz,或固定该标签/更早提交 | 否,需要更新到 `v0.9.1` 或含修复的提交 |
| `npx skills add jiangkoumo/ego-decision-layer` | 未固定 ref 时获取仓库默认分支;已有拷贝需要重新安装更新,不会随合并自动变化 |
| Claude Code 插件市场安装 | 已安装的插件可能仍使用缓存;需更新 marketplace 和已安装插件,再核对其实际代码 |
Expand Down
32 changes: 31 additions & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,35 @@
# ego-decision-layer 演进规划(Roadmap)

## 下一阶段优先级(2026-10-25)

方向:**去宿主化,同时保持 ego lite 一等公民**。继续以原始数据、确定性验收与 fail-closed 执行护栏作为交付依据。
以下均为待实施规划,不代表当前版本已经支持;不承诺未经验证的模型能力或完成日期。

| 优先级 | 工作 | 验收标准与依赖 |
| --- | --- | --- |
| P0:当前发布 | v0.10.0 交付已合入的 `update` / `--version`,补独立英文 README | 更新集成、版本一致性与真实浏览器冒烟通过;版本元数据、标签和 Release 对齐 |
| P1:去宿主化 | 明确最小 Host Adapter 契约,新增普通 Node + 外部 Chrome CDP endpoint 入口,保留 ego lite 体验 | 同一组搜索、点击、输入任务在两个宿主通过;遮挡、陈旧目标、危险动作与控制停止仍按原语义处理;连接与页面归属、清理可验证 |
| P2:共同基准 | 先建立 10–15 个可复跑任务,作为双宿主适配与重构的验收集,再扩到 30–50 个真实任务 | 相同目标、输入、验证器与预算;报告成功率、错误成功率、延迟、请求数、花费、护栏拒绝率、人工接管率及失败消耗;登录、验证码、地域与站点变化单独记录 |
| P3:MCP 入口 | 在独立运行入口稳定后提供 `browser_task(url, goal, until, text)` 工具 | 返回任务标识、确定性验证结果、停止原因与已执行动作;明确取消、重试、连接释放和页面所有权;调用方重试不盲目重复已有副作用 |
| P4:视觉实验 | 通过现有 `visualGrounder` 注入 Jev 图像 + box 定位,默认关闭、显式开启 | 先核实 Jev 1.14 / `jev-preview` 的官方契约与实际可用性;验证截图缩放、CSS 坐标映射、页面漂移、遮挡及无法确认的危险区域处理;测定位准确率、请求延迟与实际点击成功率 |
| P4:后端横评 | 使用共同任务集比较 Jev、候选 Clef / Clef-flash 与一个本地小模型 | 先确认服务、模型版本、能力与价格;固定任务和执行护栏,记录响应中的实际模型版本、配置与原始数据;不把缺少可比能力的模型硬凑成版本 A/B |
| P5:失败升级 | 连续无进展或 blocked 时,打包状态交给大模型规划,再有界恢复 | 设置升级次数、总步数、时间与费用预算;区分未派发、已派发与结果未知,结果未知先复核;人工接管和执行护栏不被规划结果绕过 |

### 实施边界

- **下一项开发从 P1 开始**:先盘点引擎实际消费的 `page` API,保持 `scripts/decider-loop.mjs` 的稳定导出,做最小可运行的第二宿主;外部 Chrome 可由 Playwright 启动,核心不强制依赖 Playwright。
- 不把宿主适配与 4108 行引擎的全面拆分绑成一次改动。第二宿主跑通后,再沿真实依赖逐步拆成 observe / decide / act / guard / cache 等模块,每次只验证受影响部分。
- Jev box 首先比较「当前几何中心策略 vs 图像定位」。只有确认旧版与新版支持相同输入和输出契约,才做同能力的版本对照;合成受控页面的结果与真实站点结果分开报告。
- 中文站点任务可包含知网、B 站、淘宝搜索等候选;是否纳入取决于可重复性、访问条件与确定性验收,不先承诺覆盖。
- 暂缓迁移 `bench/raw/` 与演示视频:原始证据继续随仓库保留。体量影响安装时再评估 Release 附件或数据分支,并保留校验和、对应脚本 revision、稳定下载入口与复算命令;移走当前文件不会缩小已有 Git 历史。
- 上游合作作为长期选项:向 ego lite 提议正式的第三方决策层挂载点,降低覆盖官方技能入口的维护成本。这里只记录方向,尚未联系上游。

---

## 已有阶段与历史验证记录

下面保留早期五阶段规划、实现与当时验证证据;历史耗时不代表当前版本的性能保证。

本项目(`ego-decision-layer`)的核心定位是 **「基于 System One 极低延迟决策的轻量浏览器自动化闭环」**。
在实测中,单步决策仅 0.35~0.5s、端到端整步约 1.0~1.4s,纯裸 CDP 派发,无重型框架包装。

Expand Down Expand Up @@ -27,7 +57,7 @@

```
┌────────────────────────────────────────────────────────────────────────┐
│ Phase 1 (P0): 自适应 Mutation 页面稳定等待机制 (Adaptive Settle) │ ← 当前正在实现
│ Phase 1 (P0): 自适应 Mutation 页面稳定等待机制 (Adaptive Settle) │ ← ✅ 已完成 (v0.5.0)
│ - 静态交互 40ms 极速返回(节省 60~80ms 及 75% IPC 调用) │
│ - 动态异步 DOM 自适应静默判定,消除无效固定延迟 │
└────────────────────────────────────┬───────────────────────────────────┘
Expand Down
Loading
Loading