# Changelog 所有对用户可见的变更集中在各版本号下。格式遵循 [Keep a Changelog](https://keepachangelog.com/),版本语义遵循 [SemVer](http://semver.org/)。 ## [0.15.1] - 2026-11-21 — 安全修复:设置网关鉴权 ### 修复 - **`/ego/api/*` 纳入 DSH 鉴权**:设置网关现在要求与 `/api/ego/*` 相同的 `dsh-auth-*` cookie;无凭据请求返回 401。 - **执行相关设置仅限本地配置**:`chromePath`、`ffmpegPath`、`chromeArgs`、`egoCliArgs` 不再允许通过 HTTP 设置网关写入(返回 `local-config-only` / 403);仍可通过 profile 配置文件设置。 - 新增 `SECURITY.md` 并启用 GitHub Private Vulnerability Reporting。 ### 测试 - 新增未鉴权 get/set 拒绝、执行配置 HTTP 写入拒绝的回归测试;全量 **484 passed / 8 skipped**;typecheck/build 通过。 ## [0.15.0] - 2026-11-21 — 工具精简模式 ### 新增 - **`toolProfile: full | lite`**:默认 `full`,保持全部 35 个工具;`lite` 只注册核心工具集,降低工具 schema 的上下文占用。 - lite 核心集:`ego_status`、`ego_help`、`ego_doctor`、`ego_navigate`、`ego_page_info`、`ego_snapshot`、`ego_read_element`、`ego_click`、`ego_fill`、`ego_key`、`ego_scroll`、`ego_verify`、`ego_wait`、`ego_wait_for_human`、`ego_tabs`、`ego_space_open`、`ego_space_close`、`ego_script`、`ego_replay`、`ego_screenshot`。 - 未注册的工具仍可通过 `ego_script` 访问底层运行时;切换 profile 需要重新挂载插件。 - 设置页和 TUI settings section 均加入 Tool profile 选择。 - **capture 失败态**(#112/#114):窗口最小化/关闭导致 capture failed 时,面板显示错误状态卡和「恢复窗口 / 重新连接」按钮,不再整块空白。 ### 说明 这是静态注册时裁剪,不是运行时动态加载;真正的“按需加载工具”仍需要 DSH 工具注册层支持,后续单独设计。 ### 测试 - 新增 lite profile 注册测试与 config 默认值测试;全量 **482 passed / 8 skipped**;typecheck/build 通过。 ## [0.14.2] - 2026-11-20 — spaces 快返回 + ego_scroll 正确性 ### 修复 - **无浏览器时 `/api/ego/spaces` 不再拉起 worker**(#107/#108):没有 live worker/browser 时直接返回空列表,避免用户未开 agent 浏览器时反复 spawn worker。 - **`ensureWorker()` 不再死等**(#108):worker 启动后立即退出时,等待循环在进程结束的 100ms 内中止,而不是等满 8 秒。 - **`ego_scroll` 返回稳定后的偏移**(#109/#110):滚动前读取一次,滚动后轮询到坐标稳定(上限 400ms),返回 `before` / `after` / `moved` / `settled` / `atEnd` / `deltaX` / `deltaY`;`scrollX` / `scrollY` 保持最终位置语义。 - 合并后重新生成 `lib/index.js`,确保 npm 包包含 scroll 修复。 ### 测试 - 全量 **480 passed / 8 skipped**;typecheck/build 通过。 ## [0.14.1] - 2026-11-16 — 观察窗 watch fallback ### 修复 - **地址栏导航后侧栏停在 `idle / 未接管`**:Remote `egoBrowser/watch` 未返回时增加 2 秒超时,并回退到 `/api/ego/watch-fallback` 的 host 代理;该路径只做一次租约切换,不是轮询。 - **Remote 调用不再无限等待**:`egoRpc` 统一加超时,避免状态或 watch 调用悬挂时侧栏不打开 SSE/不建立 capture。 ### 测试 - 全量 **471 passed / 8 skipped**;typecheck/build 通过。 ## [0.14.0] - 2026-11-16 — 侧栏基础浏览器 ### 新增 - **标签栏 `+` 新建独立窗口**:放在标签栏最右侧,点击直接创建 `about:blank` 的独立 Chrome 窗口并激活;不做菜单,不额外询问 URL。 - **常驻地址栏**:显示当前页面 URL,可直接编辑、Enter/Go 访问;没有页面时输入 URL 会先创建窗口再访问。 - **前进/后退/刷新**:新增 `/api/ego/history`,worker 通过 `Page.getNavigationHistory` / `Page.navigateToHistoryEntry` 执行。 - **用户操作激活真实 Chrome**:新建窗口/切换标签/面板导航走显式激活;模型 `ego_*` 仍保持 #99 不抢前台。 - **watch lease 不再由 client 轮询续租**:worker 在 SSE 连接打开期间本地 `touchAll()` 续期,面板稳定打开时不再每 5 秒发一次租约请求。 - 继承 0.13.2 的 lazy Remote、relay 恢复和配对过期修复。 ### 测试 - 新增 `tests/panel-browser-controls.test.ts`、`tests/polling-efficiency.test.ts`;全量 **471 passed / 8 skipped**;typecheck/build 通过。 ## [0.13.2] - 2026-11-16 — Remote review follow-up ### 修复 - **headless 安装不再被 optional peer 拖垮**:`lib/index.js` 不再静态 import `@deepseek-ai/dsh-typert-protocol`;Remote 适配器拆成 `lib/remote.js`,只在 webServer 激活后动态加载,缺 peer 时捕获并降级。 - **relay 重新启用**:`egoBrowser/status` 的 `relay:true` 通过 `frameRelaySet(false)` 清除旧的 disabled 状态,面板不再永久卡在 disabled。 - **配对过期**:`lastSeenAt` 到期时安排一次 deadline render,并在点击登录时重新检查 freshness,避免 20s 后仍按“已配对”导入 cookie。 ### 说明 tsdown/rolldown 不能可靠输出标准装饰器语法,因此继续使用 `markRemote` 手工调用上游装饰器工厂;产物中不保留 `@Remote(...)` 语法。 ### 测试 - 全量 **463 passed / 8 skipped**;typecheck/build 通过。 ## [0.13.1] - 2026-11-16 — 观察窗稳定性 + DSH Remote 宿主通道 ### 修复 / 变更 - **新窗口/后台 target 冻结**:capture session 启用 `Emulation.setFocusEmulationEnabled`,隐藏 target 也能产生 screencast 帧;实测后台动画页 3 秒 99 帧。 - **侧栏切换不跟随真实 Chrome**:用户点击侧栏 tab 时传 `activate:true`,worker 直连 CDP 执行 `Target.activateTarget` + `Page.bringToFront`;模型 `ego_*` 仍保持 #99 不抢前台。 - **capture 会话失效不恢复**:`Session with given id not found` 时清除 session、重新 attach、重试一次;client 收到 failed 时重建 watch lease。 - **保存密码气泡卡住 screencast**:agent profile 冷启动默认关闭 Chrome 密码管理器(`credentials_enable_service=false`、`profile.password_manager_enabled=false`);`EGO_LINUX_DISABLE_PASSWORD_MANAGER=0` 可恢复。 - **观察窗宿主状态改走 DSH Remote**:`GET /api/ego/executor`、`GET /api/ego/login-extension/health`、`GET/POST /api/ego/watch/*` 下线,改由 `egoBrowser/status` + `egoBrowser/watch` 两个 Remote 端点承载;前端通过 `connection.rpc.call('/api', ...)` 复用宿主鉴权/信封/错误码。 - **状态刷新改为推送驱动**:面板挂载、`connection/reset`、窗口 focus、SSE `spaces` 帧(4s 节流)和用户动作触发;只有配对浮层打开期间保留 2s 自终止刷新。 ### 测试 - 新增 `tests/capture-recovery.test.ts`、`tests/remote-endpoints.test.ts`;typecheck/build 通过。 ## [0.13.0] - 2026-11-15 — 回放与观察窗幽灵光标 ### 新增 - **`ego_replay`**:读取 `trajectory` JSONL,按顺序通过同一套 ego_* 脚本构建器重新执行;返回逐步骤 ok/error,失败即停(可配置 `stopOnError:false`)。脱敏的 `ego_fill` / `ego_key` 文本跳过,不把 `` 当真实输入;回放时忽略旧的 `snapshotId`,由回放过程重新观察。 - **观察窗幽灵光标(P2-6)**:host 在 `ego_click` / `ego_hover` 后广播 SSE `cursor` 事件,前端在实时画面上叠加带渐隐动画的光标/点击波纹;不改变页面 DOM,也不影响截图。 ### 测试 - 全量:**453 passed / 8 skipped**;typecheck/build 通过。 - `ego_replay` 与幽灵光标需重启 DSH 后真实浏览器验证。 ## [0.12.0] - 2026-11-15 — 轨迹记录 + 原生能力兜底 ### 新增 - **`trajectory` / `recordText` 设置**:开启后每个会话写一份 JSONL 轨迹到 `~/.dsh/plugin-data/ego-browser/trajectories/.jsonl`,记录 tool / args / ok / code / actionSent / durationMs / url / space / snapshotId;默认关闭。 - **默认脱敏**:`ego_fill` / `ego_key` 的 `text` / `value` 默认写 ``,只有 `recordText:true` 才记录原文。 - **`scripts/replay.mjs`**:读取轨迹 JSONL,校验完整性并输出有序回放计划(`--json` 可交给能执行工具调用的宿主);失败步骤、非法行会返回非零。真实自动重发仍需宿主工具执行入口。 - **原生对话框兜底**:检测到 `cua_driver_native__*` 时,`ego_help` 增加 `native` 主题,系统规则提示文件选择/打印/证书/权限弹窗改用桌面工具;不封装、不耦合 CUA 工具。 ### 测试 - 新增 `tests/trajectory.test.ts`:JSONL 字段、脱敏、关闭时不落盘。 - 新增 `tests/help-topics.test.ts` native 可见性用例。 - 全量:**453 passed / 8 skipped**;typecheck/build 通过。 ## [0.11.0] - 2026-11-15 — 观察成本分级:子树 / 截断 / 续读 ### 新增 - **`ego_snapshot` 作用域裁剪(P1-3)**:`subtreeRef` 只返回指定 ref 的子树;`maxChars` 默认 24000,超出时返回 `truncated:true` + `continuation`;`continuation` 绑定 `snapshotId`,旧代次重新快照会返回 `STALE_REF`。所有裁剪在插件侧完成,不依赖 runtime 扩展。 ### 测试 - 新增 `tests/snapshot-slice.test.ts`:子树缩进裁剪、maxChars 截断、续读游标、非法 ref/越界/格式校验。 - 全量:**449 passed / 8 skipped**;typecheck/build 通过。 ## [0.10.0] - 2026-11-15 — CUA 启发 P0:动作后置断言 + 快照代次 ### 新增 - **`ego_verify`**:1–8 个 `selector` / `text` / `value` / `url` / `count` 谓词 AND 组合,支持 `timeoutMs`、`stableSamples`、`pollMs`。返回 `verdict: satisfied | unsatisfied | unknown`;`unknown`(例如页面被对话框阻塞)永不等于成功。一次 `page.evaluate` 评估全部谓词,页面内轮询,不反复 spawn。 - **`snapshotId` + `STALE_REF`**:`ego_snapshot` 返回快照代次;`ego_click` / `ego_fill` / `ego_check` / `ego_select` / `ego_hover` / `ego_drag` 可传 `snapshotId`。旧代次在动作发送前 fail-closed:`code:STALE_REF`、`actionSent:false`、`retry:reobserve`。不传 `snapshotId` 时行为不变。 - `ego_help` 的 tools/errors/observe/discipline 与系统规则同步更新。 ### 测试 - 新增 `tests/verify-snapshot.test.ts`:谓词匹配、URL glob、非法谓词、快照代次推进/diff 保持、STALE_REF 分类。 - 全量:**445 passed / 8 skipped**;typecheck/build 通过。 ## [0.9.15] - 2026-11-14 — Windows 焦点 / 观察窗 / 弹窗与标签修复(#99–#104) ### 修复 - **#99 Windows 有头模式不再隐式置顶**:transport 拦截模型侧 `Target.activateTarget` / `Page.bringToFront`,保留 active 记账;`Target.createTarget` 使用 `background:true`,并按 session 补 `Emulation.setFocusEmulationEnabled` 保证后台页仍能渲染/截图。`ego-browser --open` 仍保留用户主动抬窗。 - **#100 反向代理子路径**:观察窗的 `/api/ego/*`、`/ego/api/*` 与 SSE 全部按 `` 计算部署前缀,不再请求代理根路径。 - **#101 移动端实时画面比例**:去掉 `max-height:50vh`,body/liveview/stage 改为 flex 填满,图片 `object-fit:contain` 等比铺满可用区域。 - **#102 截图交付卡**:`ego_screenshot` 的 `deliver` 改为显式 opt-in(默认 `false`),避免手机/无桌面宿主生成空白交付卡。 - **#103 观察窗 about:blank**:新建 space 不再激活空白 anchor;持久 Profile 下若已有真实页面,新 space 的 tab 以该 URL 起步(仍独立),worker 的 `activeTargetId()` 也优先真实页而不是 `/json/list[0]`。 - **#104 原生弹窗与 target=_blank**:`Page.javascriptDialogOpening` 立即默认 dismiss,避免 renderer 卡死;`listTabs()` 的 fallback 接受 opener 所属页面。 ### 测试 - 新增 `tests/issue-99-104-regressions.test.ts`,覆盖这 6 个修复的关键路径。 - 全量:**439 passed / 8 skipped**;typecheck/build 通过。 ## [0.9.14] - 2026-11-10 — 视觉观测与触摸操作增强(DEV1 开发中,未发布) ### 新增 - **`ego_screenshot` 默认内联图片**:截图同时返回 `{ path, attachment }`,渲染为 image block,模型当轮即可看到画面,不再需要额外 `read_image`。依赖宿主 `ctx.attachments.saveImage()`;没有附件服务(TUI/无头/旧宿主)或保存失败时自动退回“仅路径”,不影响截图本身。新增 `inline:false` 可只保留路径。 - **`ego_click` 新增 `touch` / `holdMs`**:`touch:true` 发 touchStart/touchEnd(4399 等 touch-first H5 游戏);`holdMs` 在同一坐标按下→等待→抬起。两种模式都不发送 move,因此不会拖动页面或滚动;默认鼠标路径完全不变,拖拽仍只属于 `ego_drag`。 - **Canvas / iframe 观测边界写入文档**:`ego_snapshot` 描述与 `ego_help discipline/screenshots` 明确——Canvas/WebGL/自定义绘制内容不在语义树中,必须用 `ego_screenshot`;跨域 iframe 内元素用 snapshot 的 `ref` 点击/填写,CSS selector 只搜索主文档。 ### 验证 - 实机确认:4399 跨域 age iframe 内的 `#btn_login` 通过 `ref` 点击成功(弹出登录框),说明 iframe 交互无需新增 frame 工具。 - 单元测试新增:截图在附件服务可用时返回 image block、`inline:false` 与无附件服务时自动降级。 ### 修复 - 首次实机测试发现直接访问 `ctx.attachments` 会被 Cordis 的 inject 保护拒绝(`cannot get property "attachments" without inject`)。改为 `ctx.inject(['attachments'], ...)` 捕获服务 + `ctx.get` 兜底;TUI/无头宿主仍自动退回“仅路径”。 - **安全:snapshot 不再回显密码框明文**。`input[type=password]` 的 `value` 统一输出 `••••••`,避免浏览器自动填充把真实密码写进语义树、模型上下文和会话日志;文本/普通输入仍正常显示。已用本地页面实机验证(`pwMasked=true`,无明文)。 - **人机协作规则**:规则段与 `ego_help discipline` 新增“登录/人机验证/支付/年龄确认 → 先告诉用户,用 `ego_wait_for_human` 等待;不要猜密码、不要绕过访问控制”。 - **#98 Android proot 环境适配**:插件启动时自愈 `bin/ego-chrome-wrapper.sh` 的执行位(npm/tar 解压可能掉成 600);wrapper 优先使用插件解析出的 `EGO_LINUX_CHROME_BIN`,并增加 PATH `command -v` 兜底,修复“`ego_doctor` 找到 `/usr/local/bin/chromium` 但 wrapper 找不到”的不一致;`ego_doctor` 输出 wrapper 路径、执行位与最终浏览器。 ### 测试 - 全量:**433 passed / 8 skipped**;typecheck 通过。 - 新增 `tests/click-script.test.ts`(9):默认鼠标路径不变、`touch` 只发 touchStart/touchEnd、`holdMs` 同点按下/抬起、非法 `holdMs` 拒绝、全程无 move。 - 新增 `tests/wrapper.test.ts`(3,Windows 跳过执行位用例):wrapper 脚本契约、执行位自愈、缺失文件降级。 - `scripts/smoke-0.9.13.mjs`:真实 vendored runtime + 本地页面,**31/31 通过**(截图内联在无附件服务的 fake ctx 下按预期退回路径)。 ## [0.9.13] - 2026-11-09 — 浏览器操作能力增强 & 观察窗 UI 重做 ### 新增 - **原生操作规则提示(不引入 skill)**:注册 `plugin:ego-browser:rules` 系统提示段,文本按每个 step 重新求值——本进程第一次出现 `ego_*` 调用前为空(零 token),之后注入 8 条防错规则;装配上下文带 session id 时按会话门控,没有 `systemPrompt` 服务的主机静默跳过。 - **结构化失败契约**:动作类工具失败不再抛异常,而是返回 `{ ok:false, code, actionSent, retry, hint }` 并渲染成一条可执行的恢复提示。覆盖 `TIMEOUT / LOCATOR_NOT_FOUND / NAVIGATION_FAILED / DIALOG_BLOCKING / CAPTCHA / USER_CONTROLLING / SPACE_STALE / BROWSER_DOWN / NO_PAYLOAD / INVALID_ARGS / UNKNOWN`;`actionSent=true` 表示动作可能已送达页面,应先观察而不是盲目重试。 - **`ego_navigate` 新增 `reuse`**:`origin`(默认,同源已开标签页就地导航)/ `exact`(仅完全相同的 URL 切换、不重载)/ `none`(始终导航当前标签页,保持旧行为)。默认策略避免同站导航顶掉正在看的无关页面。 - **`ego_help` 文档注册表**:主题升级为 `mode: inline/lookup` + 平台门控;新增 `gui-test`(黑盒 GUI 测试清单)、`login-import`(仅 macOS/Windows);`topic=list` 按 inline/lookup/本平台不可用分组。 - **`ego_status` 返回三行 `rulesSummary` 与 `help` 指针**;交互工具成功返回附带 `hint`(先做最便宜观察、不要重复同一动作);新增 `rulesPrompt` 诊断(enabled/registered)。 - **`rulesPrompt` 设置(默认 true)**:可关闭规则段;section 仍在注册,只是渲染为空,且按每次装配实时读取。 - **`ego_snapshot({ diff: true })`**:按 session/space/scope 缓存上一份语义树,只返回新增/移除/变化的行(变化行成对给出 before/after),首次 diff 返回完整树作为基线;diff 结果不含可操作 ref,提示操作前重新取完整快照。 - **`ego_tabs` 返回任务空间归属**:list/switch/open/close 的结果附带 `spaces: [{ id, name, ownership, recentTabTitles }]`;user-owned 空间不应被关闭或接管(facade 缺失时 best-effort,不影响动作)。 - **`ego_screenshot` 新增 `fullPage` 与 `clip:{x,y,width,height}`**;与 `selector` 互斥,非法组合明确报错。 - **观察窗 UI 重做**:实时观察面板改用 DSH 宿主主题 token(颜色/圆角/间距随主题切换),不再硬编码皮肤。 - **插件图标与包元数据**:新增 `assets/icon*.png`,`package.json#icon` 与 `files` 收录;包描述更新为中文能力概览。 ### 修复 - **`ego_cli` / `ego_script` 失败统一为结构化值**(`code/actionSent/retry/hint`),不再是这两个逃生舱独有的裸字符串错误;两者 schema 同步扩展。 ### 测试 - 新增 `tests/errors.test.ts`(10)、`tests/rules.test.ts`(7)、`tests/navigate-reuse.test.ts`(9)、`tests/snapshot-diff.test.ts`(12)、`tests/help-topics.test.ts`(5);`tests/tui-tools.test.ts` 增加 diff 接线、交互成功 hint、截图参数、`ego_cli` 失败契约用例。 - `tests/tui-tools.test.ts` 的冷启动用例改为断言结构化失败值(`ok:false, code:BROWSER_DOWN`)。 - 新增 `scripts/smoke-0.9.13.mjs`:真实 vendored runtime + 本地页面的端到端 smoke(31/31 通过),覆盖规则段、导航复用、diff、截图参数、tabs 归属、失败契约与 8 轮稳定性。 - 全量:**420 passed / 7 skipped**;typecheck 通过。 ## [0.9.12] - 2026-11-09 — macOS Cookie 落盘修复开关(#93 收尾) ### 新增 - **「macOS Cookie 落盘修复」设置(`useMockKeychain`,默认关闭)**:把 0.9.11 的诊断开关升级为正式 opt-in 选项。开启后插件在 macOS 上向运行时注入 `EGO_LINUX_USE_MOCK_KEYCHAIN=1`,Chrome 以 `--use-mock-keychain` 启动,恢复 cookie 落盘(#93 社区实测:重启后探针 cookie 仍存在)。仅 macOS 生效,Windows/Linux 不注入;用户显式设置的同名环境变量仍然优先。 - 设置页(Web 设置卡片 + TUI settings section,manifest 同步)新增该布尔项与中英文文案;`ego_doctor` 输出 `useMockKeychain` 状态,并在 macOS 未开启时给出提示。 ### 文档 - README 的 macOS Cookie 章节改写为**已确认成因 + 修复开关 + 验证步骤**:明确 `--use-mock-keychain` 已被真机验证有效;**落盘是延迟的(约 60 秒后出现在 `Default/Cookies`)**,flush 后立刻查询会误判为 0 行;说明 mock Keychain 降低静态加密强度、需浏览器冷启动,以及 `chromeArgs` / `EGO_LINUX_USE_MOCK_KEYCHAIN` 的等价做法与官方 ego lite 线的差异。 ### 测试 - `tests/config.test.ts`:`useMockKeychain` 默认 false 与字符串/数字真值解析。 - `tests/env.test.ts`:macOS 注入 `EGO_LINUX_USE_MOCK_KEYCHAIN=1`、关闭时不注入、Windows/Linux 不注入、用户环境变量优先。 - `tests/tui-integration.test.ts`:同步 manifest 字段列表(含新字段)。 ## [0.9.11] - 2026-11-06 — cast worker 状态路径修复 / macOS Cookie 诊断 ### 诊断 - **macOS 27 + Chrome 156 cookie 不落盘(#93 后续)**:新增 `EGO_LINUX_USE_MOCK_KEYCHAIN=1`(或 `chromeArgs: "--use-mock-keychain"`)对照开关:macOS 上让 Chrome 使用 mock/test Keychain,用于判断实时 cookie jar 非空但 `Default/Cookies` 不变是否由登录 Keychain 引起。**默认关闭**,开启会降低静态加密强度,只建议诊断使用。 - README 增加 macOS Cookie 落盘排查步骤,并明确 macOS 仍使用 `Default/Cookies`(不是 Windows 的 `Default/Network/Cookies`)。 ### 修复 - **自定义 `EGO_LINUX_STATE_DIR` 下 cast worker 无限重启(#97)**:worker 把 `ego-cast.json` 直接写在 `$EGO_LINUX_STATE_DIR`,而插件 `castStatePath()` 又拼了一层 `ego-lite-linux`,导致永远找不到 worker → 每 8 秒重新 spawn,旧 worker 不退出、内存持续增长。现在两边统一为 `/ego-cast.json`;`ensureWorker()` 增加单次 in-flight 保护与 8s→16s→…→60s 指数退避,避免重复 spawn。 ### 测试 - 新增 `tests/worker-state.test.ts`:自定义 state dir 路径、读取 ego-cast.json。 - 全量:**364 passed / 7 skipped**;typecheck/build 通过。 ## [0.9.10] - 2026-11-06 — 标签页选择 / 脚本 space / 面板刷新与最大化 ### 修复 - **`ensureRealTab` 选中 `chrome://newtab`(#92)**:没有 active 标签时,旧兜底把 `__tabs[0]`(常驻 newtab)当成真实页,`ego_script` 的 `page` 句柄指向空白页。现在统一识别 `about:/chrome:/chrome-extension:/edge:/devtools:/data:`,优先「active 且非空白」→ 非空白 → active → 第一个标签;显式 pin 仍优先。 - **`ego_script` / `ego_cli` 没有 space(#92)**:两个脚本工具现在接受 `space` 参数,脚本前置 `taskSpaces.useOrCreate(space)`,并使用同一个 space 记录 targetId pin,和结构化工具的 target 保持一致。 - **Windows 最小化后每次调用弹窗(#96)**:`ensureRealTab` 不再对已经 active 的标签调用 `browser.switchTab`(`Target.activateTarget` 会恢复最小化窗口);只有 pinned/后台目标才切换。 - **截图包含 agent 光标(#96)**:新增 `ego_screenshot({ hideCursor })`,默认 `true`:截图前临时 `ego.hideCursor()`,完成后 `ego.showCursor()`;浏览器窗口仍显示光标,PNG 不再截到它。 - **macOS 运行时仍只认 Linux PATH(#95)**:`runtime/ego-linux/src/chrome.mjs` 的 `resolveBinary()` 在 `which` 失败后增加平台安装路径兜底——macOS `/Applications` 与 `~/Applications` 下的 Chrome/Chromium/Edge/Brave/Tungsten Edge `.app`,Windows Program Files/LocalAppData;PATH 仍优先。README 增加 macOS 官方 ego lite 桥接说明。 - **`ego_auth_flush` 报告真实 cookie 数量(#93 诊断)**:worker `/api/flush` 现在先 `Storage.getCookies` 统计 jar,再 `Storage.flushCookies`,返回 `{total, flushed}`;不再固定 `total:0`。macOS 持久化是否落盘仍需报告者按 issue 步骤复测。另新增 macOS 的 `EGO_LINUX_USE_MOCK_KEYCHAIN=1` / `chromeArgs: "--use-mock-keychain"` 对照开关(默认关闭,会降低静态加密强度),用于判断是否 Keychain 导致 cookie 不落盘。 ### 新增 - **面板刷新 / 手动网址 / 最大化(#94)**:工具栏新增「刷新」「网址」按钮,以及尺寸预设右侧的「最大化」按钮;新增 `/api/ego/navigate` 主机路由和 worker 的 `Page.reload`/`Page.navigate`;`/api/ego/window-size` 支持 `maximize`(`Browser.setWindowBounds({windowState:'maximized'})`)。 ### 测试 - 扩充 `tests/tab-and-viewport.test.ts`:模拟 tab 列表验证空白 active、已 active 不切换、显式 pin;验证脚本 space 前置。 - 新增 `tests/panel-actions.test.ts`:刷新/网址/最大化路由与 UI 接线、焦点回归、截图隐藏光标。 - 全量:**362 passed / 7 skipped**;typecheck/build 通过。 ## [0.9.9] - 2026-11-03 — 登录参数归一化 / X display 存活判断 ### 修复 - **`ego_login_import(source="extension")` 恒 0 条(#90)**:DSH 宿主会把 `type: "json"` 参数以 JSON 字符串交给 `execute`,旧代码的 `Array.isArray(args.domains)` 因此恒为 false,`domains` 变成空数组,扩展静默读到 0 条。新增 `parseJsonArg()` / `asStringArray()` / `asArrayArg()` 统一归一化 JSON 字符串、数组和逗号分隔值;`domains`、`ego_select.value`、`ego_drag.points`、`ego_cdp.params`、`ego_http.headers` 都走归一化。 - **扩展 domains 语义**:省略/空 domains 现在按文档读取**全部 cookie**(`chrome.cookies.getAll({})`),不再静默导出 0 条;结果带 `warning`,面板卡片也会展示。 - **僵尸 X display(#91)**:`displayUsable()` 现在同时检查 `/tmp/.X11-unix/X` 与 `.X-lock` 中的 pid 是否存活;`pickFreeDisplayNumber()` 只把 live display 算作占用。死 Xvfb 不再触发一次 20s 冷启动失败,也不会让 display 号每次重启漂移。 ### 测试 - 新增 `tests/json-args.test.ts`:JSON/数组/逗号分隔归一化、domains/select/points/CDP 接线、空 domains 全量读取、0 条 warning。 - 新增 `tests/display-usable.test.ts`:死/活 lock pid、无 socket、无 lock、僵尸 display 复用、live display 跳过。 - `tests/login-extension.test.ts` 增加“扩展返回 0 条时 warning”用例。 - 全量:**350 passed / 7 skipped**;typecheck/build 通过。 ## [0.9.8] - 2026-11-01 — ego_tabs 脚本生成的重复 space 声明 ### 修复 - **`ego_tabs` 四个动作全部报 `SyntaxError: Identifier 'task' has already been declared`(#88,0.9.7 回归)**:0.9.7 给 `ego_tabs` 加能力降级守卫(#87)时,`guard()` 把 `useSpace(...)`(声明 `const task`)拼进了 `if` 分支、`else` 分支和结尾各一次,加上 action body 自带的那次,单次脚本里同一段 `const task` 出现 4 次。运行时用 `new AsyncFunction(code)` 编译 heredoc,重复的块级 `const` 在编译期就被拒绝,因此 `list/switch/open/close` 在碰到浏览器之前就失败,而其它工具不受影响(它们不经过这个 guard)。 `guard()` 现在只保留一处空格锚定:space 在守卫之前声明一次,两个分支不再重复声明。`ego_tabs` 的脚本生成同时被抽成 `tabsScript()`(`src/index.ts`),以便对生成结果做编译级单测;`runtime capability missing: …` 的 #87 文案与 `switch/open/close` 的行为保持不变。 ### 测试 - 新增 `tests/tabs-script.test.ts`(13 项):用运行时同款 `new AsyncFunction(...)` 编译四个 action 的生成脚本,断言 `const task` 恰好声明一次、守卫在声明之后、#87 能力文案齐全、缺 `targetId`/未知 action 的早退分支仍可编译。 ## [0.9.7] - 2026-10-29 — egoBin 运行时选型 / 官方 ego lite 文档 / ego_tabs 能力降级 ### 修复 - **`egoBin` 填官方 `.exe` 时给出可执行错误(#87)**:插件以 `node ` 启动运行时,官方 `ego-browser.exe` 不能直接使用。`validateEgoBinPath()` 现在拒绝 `.exe/.cmd/.bat`,在工具执行前返回“需要 Node 脚本或 .mjs 桥”的明确提示;`.mjs/.js/.cjs`/无扩展名脚本不受影响。 - **`ego_tabs` 对运行时能力做降级(#87)**:`list/switch` 检查 `browser.listTabs/switchTab`,`open` 检查 `ego.createTab`,`close` 检查 `browser.closeTab`;官方 ego lite 或精简桥缺少 API 时返回 `runtime capability missing: …`,不再抛 ReferenceError/TypeError。 ### 新增 - **设置页 `egoBin` 字段**:可直接填 Node 运行时脚本路径;留空使用内置运行时。`ego_doctor` 增加 `egoBin kind` 与无效时的 warning。 ### 文档 - README 新增「运行时选型:内置运行时 vs 官方 ego lite」:两条线的定位、`--serve`/`waitForResponse` 缓冲/元素级截图/`ego_tabs` 能力差异、桥接示例与“只能补 `ego` 方法、不能整体替换”的注意事项。 - Windows 内置运行时 `Chrome came up ... no WebSocket URL` 排查清单;`cpu-features`/`ssh2` 安装噪音说明。 ## [0.9.6] - 2026-10-28 — 等待响应回放 / 会话级 space / 截图卡片与人工等待 ### 修复 - **`ego_wait_for_response` 看不到"已经完成"的响应**:运行时只在等待期间启用 Network 域,且只监听**未来**事件——典型场景(`page.goto()` 之后再等那次文档响应)永远匹配不到,只能干等到超时。现在: - 会话 attach 时即启用 `Network.enable`(导航期间的请求因此也会被记录),并且等待结束后**不再关闭**该域,全局事件缓冲得以保留整段导航; - `waitForResponse` 在等待前先**回放缓冲**:窗口从当前文档的 `Network.requestWillBeSent` 开始——该事件早于 `Page.frameNavigated`,所以不能简单地"从 frameNavigated 之后切片"(第一版就是这么错的,真机上文档响应始终匹配不到,已修正); - 新增 `includeBuffered` 选项(**默认 true**)回放当前文档已完成的请求;传 `false` 可回到 Playwright 的严格"只看未来"语义; - 超时时若命中的请求由缓存提供(`Network.requestServedFromCache`,不产生网络往返),错误信息会列出具体 URL 并提示加 cache-busting 查询,而不是一句莫名的 timeout。 - **`ego_wait_for_response` 工具**:新增 `includeBuffered` 参数(默认 true),超时 hint 补充缓存说明与"请求与等待需在同一 `ego_script`"的边界。 ### 新增 - **会话级 task space(PR #85)**:新增 `sessionScopedSpaces` 设置(默认 **开**)。省略 `space` 时按 `dsh-agent-` 解析,每个 DSH session 拥有独立的 browser context / window / tab 集合 / tab cursor,并发 session 或子 agent 不再互相抢标签、覆盖目标;显式传 `space` 仍共享。tab cursor key 也加入 session,因此关闭该设置后两个 session 仍保持各自 target。升级后首次调用会为新 space 打开一个新窗口,旧 `dsh-agent` 的标签不迁移;可设 `sessionScopedSpaces: false` 或显式 `space: "dsh-agent"` 保持旧行为。 - **截图/下载卡片 + `ego_wait_for_human`(PR #86)**:`ego_screenshot` / `ego_download` 通过 `deliverables/presented` 事件让 Web GUI 显示可点击卡片(`deliver:false` 可关闭,best-effort);新增 `ego_wait_for_human` 阻塞等待 CAPTCHA / 登录 / 2FA 完成(可选 `selector` 作为"已登录"信号),超时返回 `resolved:false` + 可执行提示,而不是抛错;它不是审批流程。 ### 测试 - 新增 `tests/wait-for-response-buffer.test.ts`(6 项):Network 域的启用时机、等待结束后不关闭、回放窗口包含文档请求、缓存提示文案、插件侧默认传参。 - 真机验证(repo 运行时 + 真实 Chrome):`page.goto()` 之后等待文档响应 → `{firstLoadMatched:true, firstStatus:200}`;`includeBuffered:false` 仍按 Playwright 语义超时。 ## [0.9.5] - 2026-10-27 — 滚轮修复 / 双缓冲硬化 / PR #83 ### 修复 - **侧栏滚轮/触控板滚动失效(#81 回归)**:0.9.4 的 wheel 监听绑在条件渲染的语义 `` 上,首帧到达前 `` 不存在,one-shot effect 之后不再重绑。现在监听器挂在**始终存在的 `.dsh-ego-side-stage`** 上(`passive:false`),点击/双击/`Ctrl+滚轮` 行为不变。 - **双缓冲 review 硬化(#82)**:冷启动/切目标时用 `liveFrameUrl` / frameCache / 当前缩略图做种子,不再清空两层导致空白;`onerror` 不再交换失败层(保留上一帧);目标切换清理 `liveBufferPending` 并加 generation guard,防止旧页面的帧落到新页面;黑色背景移到 `.dsh-ego-side-livebox`。`maxWidthHint` 变化后重启 watch 的逻辑已在 0.9.4 提供。 ### 新增 - **PR #83(社区 @mecamangeg)**:修复多标签时结构化工具总是切到第一个 tab / `ego_script` 没有 tab 选择的问题——新增 per-space tab cursor + `@@EGO_TARGET@@` side channel;`ego_navigate`/`ego_script`/`ego_cli` 支持显式 `tab`;新增 `viewportWidth` / `viewportHeight` / `deviceScaleFactor`(HiDPI 下避免移动版布局);`ego_select` 回退 value → label → index。源码已 rebase 到 0.9.4 并用当前工具链重建,新增 25 个测试。 ## [0.9.4] - 2026-10-27 — Chrome 风格 UI / 一键登录态 / ego_tabs ### 新增 - **Agent 浏览器面板 UI 重做(Chrome 配色)**:移除「需要账号登录时…」引导条;改用 Chrome 调色板(`#f1f3f4` 工具栏、`#202124/#5f6368` 文字、`#1a73e8` 强调,深色模式跟随 `prefers-color-scheme`);标题栏为浅灰工具区 + 蓝色实心「连接/复用 Chrome 登录态」主按钮;标签栏改为 Chrome 式活动白标签;页面标题/URL 放在标签栏下方;状态改为轻量 dot + 文本 + 执行器 chip;操作按钮改为扁平 ghost 样式(26px 高、4px 圆角、hover/focus 状态);配对面板为 Chrome 风白色浮层(锚定在页面信息下方)。同时修掉整行 `opacity:.6` 导致按钮发灰的问题。 - **`ego_tabs` 工具(0.9.4)**:一个工具管理标签页——`list`(返回 targetId/title/url/active/index)、`switch`(按 targetId 切换)、`open`(按 url 新建,默认 about:blank)、`close`(按 targetId 关闭),每次操作后返回最新标签列表。底层复用 runtime 的 `browser.listTabs/switchTab/closeTab` 与 `ego.createTab`,targetId 与 `ego_space_open`/`ego_navigate` 返回一致。真机脚本已验证 list → open → switch → close 全链路。 - **`ego_login_import` 双安全路径(#69 E + A)**: - **E 安全复制**:删除 junction/symlink 启动真实 profile + 强杀的旧路径;现在只复制 `Local State` + Cookies 到临时 profile 读取,真实 profile **从不被浏览器打开/写入**。Chrome/Edge 127+ 因 ABE 复制读到 0 条 cookie,工具明确报错而不是回退到破坏性路径。真机验证:源 Cookies SHA-256 前后一致。 - **A Chrome 扩展桥接**:新增 `extension/`(MV3,`cookies`/`alarms` 权限)与常驻回环桥接 `login-extension.ts`;Agent 浏览器面板右侧新增 **「连接 / 复用 Chrome 登录态」** 按钮:首次配对码(6 位)配对一次,之后每次点击即启动导入任务,扩展通过后台轮询(30s alarm,配对后立即触发)自动读取当前网站 cookie 并写入 ego 浏览器——不再需要每次打开 Chrome UI 或手动点 Export。`ego_login_import({source:"extension",domains:[...]})` 仍可用(等待扩展轮询)。用 Chrome for Testing 156 完成真实端到端验证(扩展读取测试 cookie → 回环 POST → ego 浏览器写入 1 条)。 ## [0.9.3] - 2026-10-26 — 侧栏双缓冲 / TUI 纯文字 / 图标统一 / 移除悬浮球 ### 新增 - **常驻执行器可视化与失败监督(#73 phase 2)**:新增 host 路由 `/api/ego/executor`,观察窗状态行显示当前执行模式(`常驻` + 运行时长 / `一次性` / `常驻已停用`),悬停可看到 pid、最后一次重建原因或停用原因。监督逻辑:连续 3 次冷启动失败后常驻进程保持停用(`parked`),一次性 spawn 继续工作,直到用户切换设置或插件重启,避免 park → one-shot → respawn 循环。默认保持 opt-in(`residentExecutor` 默认关):尚无"一整天浸泡无回归"的数据,先不做默认开启决策。设置持久化(gateway 写入后重启回退)仍需真机复现,留待验证。 ### 修复 - **统一 Agent 浏览器图标**:面板头部原先用 globe 图标,与侧边栏入口的「浏览器窗口 + 光标」不一致;现在两处都使用同一个 `ICON_AGENT_BROWSER` 几何(16×16 圆角窗口、标题栏双点、agent 光标),侧边栏 `EgoWatchIcon` 与字符串图标保持同步。 - **移除悬浮球回退**:DSH 官方右侧边栏已覆盖观察窗,删除浮动 FAB / 浮窗、拖拽吸附、其专用 CSS/图标/常量与键盘代理代码(client bundle 明显减小),只保留原生侧边栏 Tab + 可选 `dsh-better-sidebar` 回退;两者都不可用时不再显示侧栏面板。 - **侧栏实时画面黑闪(#81 / #82)**:`` 逐帧替换会在新 JPEG 解码完成前丢掉已绘制的位图,面板整块露出黑色背景(macOS 无头 CDP 链路尤其明显,Windows 也可复现)。原生侧栏改为**双缓冲**:语义 `` 只负责布局与指针/缩放(`opacity:0`),上方两层层叠 `` 承载可见像素,新帧在隐藏层 `load`/`decode` 完成后才交换可见层,旧帧始终保留;挂载/切标签时用缓存的上一帧做种子,避免首帧空窗。旧浮动面板同样改为**先预加载/解码、再换可见帧**。另修 `maxWidthHint`:在 `root.clientWidth` 为 0 时不再锁成 480;宽度测量提前到首次 watch 之前,`ResizeObserver` 更新后若与当前采集宽度差 >20% 则防抖重启一次 watch,避免 Retina 上一直用 800 采集导致发虚。验证:staging 中两层交替、可见层始终有帧、指针映射不受影响、采集宽度 653px。macOS 实机复测待 #81 报告者确认。 - **TUI 面板改为纯文字(无画面)**:TUI 没有浏览器视窗渲染能力,面板不再使用 `ui.Image`/`/api/snapshot`/SSE 帧,只显示标签、状态、人机验证、当前工具/错误、最近动作与快捷键;同时把标签元数据与 `disableFrameRelay` 解耦(禁用 Web 画面回传时 TUI 仍能看到标签列表)。选中项改为按 **`targetId`** 保持,标签增删/重排后 `x`/`o` 不会作用到错误的页面。 - **登录导入安全范围扩大(#69)**:Windows 上从仅拒绝 Chrome ≥155 扩展为拒绝 **Chrome/Edge ≥127**(App-Bound Encryption 范围)。127–154 同样存在"junction 启动真实 profile + 强杀"的破坏性路径,本次先 fail-closed;`EGO_LINUX_LOGIN_IMPORT_FORCE=1` 仍可覆盖。Linux/macOS 与 Windows 上 Chrome <127 不受影响。 - **headless UA 版本与实际 Chromium 不一致(#79)**:headless 启动时注入的 UA 一直是硬编码 `Chrome/152.0.0.0`,而 `navigator.userAgentData` 来自真实二进制(社区实测 Termux 上外部 Chromium 为 155)。这种自相矛盾的指纹会被风控标记。现在运行时首次 headless 启动会用 ` --version` 探测真实主版本(缓存,2s 超时,失败才回落 152);Windows 上为避免 `chrome.exe --version` 弹窗不做探测,继续使用兜底值。新增 `parseChromeVersionMajor()` 单测。 ### 文档 - **macOS 27 / Chrome 156 复测通过(#68)**:社区在 0.9.2 上复测(macOS 27.0.1 arm64 + Chrome 156.0.8078.47,去掉 `chromePath`/`--headless` 两个旧 workaround)——`.app` 自动探测、headed 冷启动、navigate/截图/`ego_doctor` 全通;README 的 macOS 实测记录已补充该环境(此前为 macOS arm64 + Chrome 154)。 - **Termux / Android 开箱说明(#78)**:README 新增 Termux 小节——`pkg install chromium`(x11 repo)、`chromium-browser` 已在候选列表中、无 `$DISPLAY`/Xvfb 自动 headless、无需 `--no-sandbox`、DBus 报错无害、手机终端建议 `disableFrameRelay: true`;`ego_doctor` 的“未找到浏览器”提示补充 `pkg install chromium`。 - **`ego_script` 的 page 门面不是 Playwright API(#80)**:`ego_help script`、`ego_script` 工具描述与 README 都列出完整 page 方法清单,并明确没有 `fill/click/type/press`(用 `ego_fill`/`ego_click` 或 `page.locator(...)`),`page.goto()` 不返回 Playwright Response。 ## [0.9.2] - 2026-10-23 — macOS 开箱支持(#65/#68,社区 PR #72 移植) 本版把 macOS 从"需手动填 chromePath、headed 路径找 Xvfb"变成**开箱即用**:自动探测 `.app` 内的 Chrome/Chromium/Edge/Brave 并注入运行时,headed 启动不再依赖 X11/Xvfb,同时保留 #16 要求的真实窗口能力。社区贡献者 @syjnzh918 提供实现与 macOS arm64 真机验证。 ### 修复 - **macOS 开箱可用(#65、#68)**:两处平台缺口叠在一起,使 macOS 首装第一次调用任意 `ego_*` 工具必然失败。其一,`COMMON_CHROME_BINS` 只列 Linux 路径、`resolveEgoEnv()` 的注入条件也不含 darwin,而 macOS 上 Chrome 不在 `PATH` 里(只在 `.app` bundle 内),于是报 `no Chrome/Chromium binary found`;现在由 `darwinChromeCandidates()` 探测 Chrome / Chromium / Edge / Brave(含 `~/Applications`),并像 win32 一样把结果注入 `EGO_LINUX_CHROME`。其二,填好路径后仍会撞运行时 `ensureXDisplay()`:它只给 win32 留了"有桌面会话、无 X server"的豁免,而 macOS 在这一点上完全同形(GUI 是 Aqua/Quartz,永不导出 `$DISPLAY`,Xvfb 也不存在于该生态),现在同样豁免。`isHeadlessDetected` 保持排除 darwin——把缺 `$DISPLAY` 当成无头正是 #16 的回归。真机验证:macOS arm64 + Chrome 154,冷启动 → navigate → 截图 → `ego_doctor` 全通。 ### 社区 - macOS 适配(#65/#68)来自社区 PR [#72](https://github.com/omdsh-dev/dsh-ego-browser/pull/72)(@syjnzh918),由其基于当时主干提交并附 macOS arm64 真机冷启动验证;本次将其移植到 0.9.1 后的主线上(解冲突、保留后续 win32/no-Xvfb、常驻执行器与观察窗改动,并补回归测试)。 ## [0.9.1] - 2026-10-23 — 观察窗尺寸同步 / 帧链路性能 / 输入映射修复 本版把观察窗从"只能看"扩展成"能直接改真实窗口大小":尺寸同步开关 + 比例预设 + 边缘拖拽,同时把串流 CPU 砍到约一半,并修复窗口缩放后的点击偏移与拖动卡顿。 ### 新增 - **观察窗尺寸同步(真实窗口)**:侧边栏观察窗的「打开真实页 / 弹出窗口」按钮行新增 **🔒/🔓 尺寸同步** 开关与 **尺寸预设** 菜单。 - **解锁本身不改变窗口**;之后拖动右侧边栏宽度、或直接拖观察窗的**右侧 / 底部 / 右下角手柄**,窗口按拖动**增量** 1:1 缩放(`POST /api/ego/window-size` + CDP `Browser.setWindowBounds`),横向拖动保持页面比例,纵向拖动改变高度。 - **尺寸预设** 提供 16:9 / 4:3 / 21:9 / 1:1 / 9:16:保持当前窗口宽度,把高度设成对应比例。 - 页面标题与 URL 现在显示在实时状态栏那一行(画面下方不再占两行)。 - 布局/窗口其它变化会被吸收为新的基准,不会形成"越缩越小"的反馈环;无头浏览器返回 `headless` 并提示先「弹出窗口」;本次只做 CDP 后端,FFmpeg 路径未改。 ### 修复 - **重启后观察窗卡在「⚠ 未接管 / 暂无截图」**:如果面板在浏览器/worker 还没起来时打开,host 的 `/api/ego/stream` 当时只能建一条静默 SSE,并且之后永远不会再接上 worker——即使浏览器后来启动了、worker 也在推帧,面板也收不到任何 `frame` / `spaces` 事件。现在这条流会每 1.5 秒重试 `ensureWorker()`,worker 一出现就自动接上(新增单测覆盖"worker 晚于 SSE 出现"的情况)。 - **画面边缘的红/橙色条**:边缘拖拽热区原来常显高亮条,看起来像画面多了一圈红边。现在热区默认完全透明,只在鼠标悬停时低调显示;解锁尺寸同步时仅保留极淡的提示色。 - **调整窗口后点击位置偏移**:screencast 帧携带的 `vw/vh` 视口元数据不会在每次窗口变化后更新(实测窗口已缩到 900×573 时帧仍标注 1264×805),面板按旧视口换算点击坐标导致落点偏移。现在:capture 每秒用 `Page.getLayoutMetrics` 同步真实视口;`/api/ego/window-size` 应用新尺寸后 160ms 内刷新会话视口;客户端收到 resize 响应立即用返回的 `viewport` 更新坐标映射。验证:窗口缩放到 900×573 后点击面板 60%/40% 位置,页面收到的坐标与预期一致(540,229)。 - **拖动边缘缩放卡顿**:`/api/ego/window-size` 原来每一步都重新 getWindowForTarget + getWindowBounds + 测量 chrome 边框 + 测量视口 + setWindowBounds(约 5 次 CDP 往返)。现在缓存 windowId / chrome 边框 / 窗口位置与视口(10s / 2s 过期),每步只需 1 次 setWindowBounds;实测单步延迟 avg 22ms(10–47ms)。 ### 性能 - **观察窗串流 CPU 大幅下降**:两处结构性优化,帧率与功能不变。 - **按源取帧**:`Page.startScreencast` 的 `everyNthFrame` 现在按 `cdpFps` 计算(20fps → 每 3 帧取 1 帧),Chrome 不再编码 ~100 帧/秒再丢掉 80%;实测源帧 ~100/s → ~33/s。 - **采集宽度跟随面板**:客户端把面板实际显示宽度(× devicePixelRatio,含余量)通过 `watch/start` 的 `maxWidth` 上报,worker 取配置上限与面板宽度的较小值。面板约 550px 时采集从 1280 宽降到 ~654 宽,编码/传输/解码像素约降 4 倍;全屏面板时仍会按需放大。 - 实测(Windows,面板开启、视频页面):总 CPU 约占 **196% 单核 → 72% 单核**(Chrome ~170% → ~63%,worker ~20% → ~4%);实际下发帧率 ~19/s → ~17/s。 - **窗口隐藏/最小化时停止串流**:面板监听到 `visibilitychange` 后会停掉 watch、关闭 SSE 与画面(恢复窗口时自动重新 watch/串流)。实测:最小化后 watchers 2 → 1,采集侧 CPU 降到约 6%;恢复后自动回到 2 并继续出帧。纯静态页面本来就只在内容变化时出帧。 - **TUI/无头环境可不传画面**:TUI 设置新增「关闭实时画面传输」(`disableFrameRelay`)开关;开启后不启动 cast worker、不做 screencast、不发帧,TUI 面板仅保留文字状态,`ego_*` 工具不受影响。TUI 面板本身只是事件驱动地按需取一张快照(maxWidth 320),没有连续串流。 - 画面 `` 使用 `decoding="async"`,减少主线程解码阻塞。 ## [0.9.0] - 2026-10-22 — dsh-TUI 支持(设置页 / 状态栏 / 侧栏面板 / 页面缩略图) TUI 集成全部通过**可选服务独立注入**:宿主没有对应服务时静默跳过,不新增文件读取、轮询或 worker 启动。合并社区 PR #74、#75、#76(ccch1mneyyy)。 ### 新增 - TUI 通过独立可选注入注册真实的 Agent Browser 设置页、工具活动状态栏和有限通知;缺席服务时不新增 TUI I/O 或后台轮询。 - 不可变浏览器状态快照记录当前工具与最近十次完成结果,包含执行耗时和截短错误;锁内工具从实际取得锁后开始计时。 - Web/TUI 共用安全的工具卡标题:只显示允许的定位摘要,按终端单元截断,隐藏输入值、HTTP 头/正文以及可执行源码。 - 侧栏面板(PR #75):可选 28 列 Agent Browser 面板,展示浏览器运行/无头状态、活动页标题与 URL、按任务空间分组的标签列表、人机验证提示、最近 3–5 次动作;面板聚焦时支持 `↑/↓` 选标签、`o` 弹出真实窗口、`x` 关闭标签(有对话框服务时确认,否则双按)、`f` 落盘登录态、`r` 刷新;可见时约 2 秒刷新、隐藏即停、并发合并。新增 `tuiAutoOpenPanel`(默认关)。 - 页面缩略图(PR #76):worker 新增本机回环 `GET /api/snapshot?targetId=…&maxWidth=…`(不占插件全局锁、不启动直播订阅),终端用宿主 `ui.Image` 显示;选中标签/工具结束/`r` 时各截一帧,隐藏时不请求,无拖影;PNG 用 Node `zlib` 自解(含大小/尺寸/解压上限,无新依赖),终端不支持图形协议时回退为一行文字;`disableFrameRelay` 时不截图。另显示既有的捕获后端/状态行。 ### 修复 - 删除未实现的 TUI Scene 清单声明,Notification fallback 改为无 toast 服务时省略通知、保留工具结果。 - TUI 设置直接读取清单字段作为单一来源,并将清单画质选项纠正为运行时实际接受的 `low / balanced / high`;不改现有 Web 设置实现。 ### 验证范围 - 增加可选服务、真实注册、设置一致性、隐私、Unicode 宽度、不可变快照、锁内执行、重试通知、空闲回收成功与生命周期清理测试。 - 合并后在本地通过 `typecheck` / `vitest`(234 passed, 5 skipped)/ `build`;尚未在真实 DSH TUI 或 Chrome 环境验证视觉布局与人工接管。 ## [0.8.8] - 2026-10-22 — 原生右侧边栏 + 常驻执行器 + 孤儿标签清扫 + 登录导入定向放行 ### 新增 - **原生右侧边栏支持(#64)**:DSH ≥ 0.2.1 自带右侧边栏(`@deepseek-ai/dsh-client-ui-sidebar-right`)时,观察窗注册为原生 Tab——`dsh-ego-browser:watch` 类型 + `sidebar.right.pane.tab` 面板 + guide 入口(自绘「浏览器窗口 + agent 光标」图标)。检测用 `ctx.inject(['sidebarRight','sidebarRightTabs'])` 等待服务(服务晚于插件就绪时不再漏检),优先级 **原生 > dsh-better-sidebar > 浮动球**;升级挂载时会释放上一个宿主,不会出现两份面板。自动打开仍按调用会话作用域。 - **常驻执行器(#56 第一期,可选)**:新增 `residentExecutor`(默认关)与 `residentIdleMin`(默认 30 分钟,0 = 保留到卸载)。开启后 `ego_*` 调用复用同一个 `ego-browser --serve` 进程:首次调用支付启动开销,之后每次 **~1–2 ms**(一次性 spawn 基准 ~340 ms)。浏览器被空闲回收/崩溃后,下一次调用自动回退到一次性 spawn 并重新拉起浏览器(带启动重试),随后恢复常驻;**已经写出的请求不会重试**,避免重复点击/填表。设置卡片(插件 → dsh-ego-browser → 配置)与 TUI settings 字段均已接线。 - **TUI 设置字段**:`dsh-plugin.json` 的 SettingsSection 补充常驻两项。 ### 修复 - **浏览器在常驻进程下被停/崩溃后请求永久失败(#56)**:`--serve` 的 CDP socket 在浏览器停止后不会恢复,旧实现之后每次请求都报 `CDP channel is not open`。现在 `--serve` 每请求检查 `cdp.isOpen()`,失效立即返回可重试的 `browser is not reachable`;插件把它归为冷启动错误,回收常驻进程并走一次性 spawn 恢复(10s cooldown 后才重新常驻)。Windows 上启动失败不再空等 Xvfb(本来不存在,只会多等 10s+)。 - **孤儿标签(#67)**:`reconcile()` 增加两阶段 + 120s 宽限的孤儿 page target 清扫——关闭不属于任何 space 的标签(崩溃恢复/手动打开),跳过 `about:blank`/`chrome://`,并在 `closedSpaces` 留下 `(orphan tab)` 轨迹。此前 `pruneIdle`/`pruneAbandoned`/`--prune-spaces` 只遍历 `state.spaces`,扫不到这些孤儿。 - **登录导入定向放行(#69)**:`ego_login_import` 从"全禁"改为仅 **Windows + Chrome ≥155** 拒绝(该组合的 junction 别名 + 无头启动 + 强杀路径会读到 0 条 cookie 并破坏源 profile);Linux / macOS / 旧 Chrome 正常可用,`EGO_LINUX_LOGIN_IMPORT_FORCE=1` 可在任何环境强制放行。工具会在错误信息里带上检测到的版本。 ### 变更 - README 同步 v0.8.8:版本号、DSH 兼容矩阵(0.2.1 原生侧边栏)、侧边栏三种形态、常驻执行器、登录导入定向放行、Windows 已知限制。 - `dsh-plugin.json` 版本 0.8.8。 - 测试:181 passed / 5 skipped(新增常驻传输、恢复契约、配置与孤儿选择器用例)。 ### 验证 - 真实桌面端(DSH 0.2.1-rc.2):常驻首调 1485ms(含浏览器冷启动)→ 之后 1ms;`--stop` 后下一次调用自动恢复并重新拉起浏览器;冷却期走一次性;冷却后回到新常驻;全程仅 1 个常驻进程、无残留。 - 原生侧边栏(临时 web profile):guide 出现「Agent 浏览器」及图标,面板正常推流/输入。 - #69:Windows + Chrome 155 正确拒绝并给出原因。 ## [0.8.7] - 2026-10-22 — 工具语义修复 + Windows 孤儿锁 + 登录导入止损 + 回收器会话清理 ### 修复 - **虚拟光标箭头与小手重叠**:覆盖层 `#arrow` 的 ID 规则带 `display:block`,优先级压过 `svg.shape{display:none}`——`showShape()` 切到手形/文字光标后箭头仍在绘制,两者在同一点重叠。现在可见性统一由 `svg.shape` / `.on` 控制:悬停链接只显示手形,悬停文本显示输入光标。 - **`ego_wait_for_url` 在导航已完成后仍报 `reached:false`(#71)**:改为两段式——先比对当前 URL(对无 glob 的模式做保守子串匹配),再等待未来导航;失败 payload 带当前 URL 与 `matchedCurrent`,并提示等待只在同一次调用内有效、匹配语义是全 URL 或 `**` glob。 - **`ego_wait_for_response` 超时直接抛错(#71)**:现在捕获超时并返回结构化 `{ok:false, reached:false, url, error, hint}`,不再让整次调用以退出码 1 结束。 - **`ego_dialog` 的误导性 "No dialog is showing"(#71)**:描述明确"只对当前正阻塞的 dialog 有效,跨调用的 dialog 已被自动 dismiss";失败时附当前 URL 与可执行建议(在同一次 `ego_script` 里 `page.once('dialog', d => d.accept())` 后再触发点击)。 - **`ego_script`/`ego_cli` 忘记哨兵即硬失败(#71)**:描述写出 `@@DSH_RESULT@@` 字面量;新增兜底解析——没有哨兵时取最后一行可解析 JSON,并标记 `result.fallback: true`。 - **Windows 上孤儿 Chrome 永久占住 agent profile(#70)**:Chrome 在 Windows 只留空 `lockfile`、没有 `SingletonLock` 符号链接,旧 `clearProfileLock()` 永远 no-op;浏览器一旦非优雅退出,之后每次启动都被转交给孤儿进程并耗尽 20s 超时。现在 win32 下按命令行枚举持有本 profile 的 `chrome.exe`,先收集后终止(500ms 释放等待、10s 硬上限),再清 `lockfile`;只按本 profile 路径匹配,不动用户自己的 Chrome。 - **`ego_login_import` 默认关闭(#69 止损)**:Chrome 155 上 junction 别名 + 无头启动 + 强杀路径读到 0 条 cookie,且被观测到会清空真实 profile 的扩展注册表、重置默认搜索引擎。现在默认 fail-closed,`EGO_LINUX_LOGIN_IMPORT_FORCE=1` 才放行;彻底修复待独立设计。 - **空闲回收后 Chrome 崩溃恢复复活全部旧标签(#67 止损)**:`--stop` 被 Chrome 记为 crash,`Default/Sessions/` 残留会让下次冷启动静默恢复上一轮标签,而这些页面不在 `state.spaces` 中、`pruneIdle`/`pruneAbandoned`/`--prune-spaces` 都扫不到。现在 `stopBrowser()` 在确认浏览器已停止(或本就没在跑)后清理 `Default/Sessions/`;登录态在 `Network/Cookies`,不受影响。 - **纯文本/JSON 标签页不再被光标覆盖层糊成"乱码"**:`renderOverlay()` 在 `document.contentType` 非 `text/html` / `application/xhtml+xml` 时不注入覆盖层,并清掉上一个文档残留的 host(本地 runtime 补丁,见 `runtime/PATCHES.md`)。 ### 变更 - **CDP 预览帧默认宽度 960 → 1280**:960 会把 1264 宽的常见笔记本视口先缩小再由面板放大,是"面板里文字发虚/发糊"的直接来源;1280 让常见视口落在原生宽度,更大屏幕可在设置页调到 1600/1920。 ### 新增 - **`--serve` 常驻传输层(PR #63,BeiWay1145,refs #56)**:CLI 新增 NDJSON 常驻模式,一次启动摊掉进程启动与 harness 加载开销(报告者实测 ~350ms → 后续请求 0–1ms 级)。本次只合并传输半边,默认仍走 spawn 路径;插件侧生命周期(spawn 策略/监督/设置开关/客户端重建)留待后续版本接线。 ### 社区 - 合并 PR #63(`--serve` 常驻传输,BeiWay1145)。 - macOS 适配(#65/#68)暂缓:维护者暂无 Mac 设备验证。 ## [0.8.6] - 2026-09-28 — 登录态导入安全加固 + DSH 0.1.7 设置适配 + 人机验证误报修复 ### 安全 - **`ego_login_import` 不再可能损坏源浏览器 cookie 库(#61,数据丢失)**:旧流程用 `Browser.close` 优雅关闭无头源实例,其异步 flush(热 Profile 上 10s+)会**晚于**还原逻辑落盘——在 Edge 153 上把还原好的 cookie 库覆盖成空库,且第二次调用抓到的"备份"已是空库,兜底全部失效(报告者靠手工快照救回)。现在:① 拆除时丢弃 CDP 连接并**强杀**实例(被杀进程不会 flush,磁盘保持启动前状态);② **无条件还原并校验**(重读加密标记计数,失败重试一次),备份文件保留供手工恢复;③ 若源浏览器期间重新出现(用户在用)则跳过还原,不与活写入者竞争。代价是用户下次真开浏览器会看到一次"未正确关闭"气泡——比静默丢数据划算。 ### 修复 - **导入/落盘的返回值不再"假成功"(#60)**:`closedSource`/`restoredFromBackup` 补进输出 schema(严格宿主此前把每次成功导入判为 invalid output,而副作用其实已执行);读 cookie 的循环改为**计数稳定后退出**(旧逻辑"首次非空即停"在冷启动渐进加载时只读到 0-1 条却报成功);`ego_auth_flush` 无错误时不再返回 `error: undefined`(undefined 不是合法 JSON,整条结果被拒)。 - **写入落地改为服务端确认**:`written` 旧值只是批处理算术,`browser.json` 指向陈旧/被替换的实例时会"报成功但什么都没写"。现在每个 jar 写入后**读回逐条比对**;一条都没落地 = 硬失败并给出重启 agent 浏览器的指引。 - **隔离空间收不到导入的 cookie**:`EGO_ISOLATE_SPACES=1` 时空间上下文是**创建时**从默认 jar 播种的快照(点时间拷贝,非实时共享),导入后已打开的 space 页面仍显示未登录。导入现在写入默认 jar **加** `task-spaces.json` 中所有活跃 space 上下文;某个上下文已消失时降级为警告而非使整体失败。 - **人机验证误报(#62)**:文本兜底匹配裸 `captcha` 名词,任何**讨论**验证码的页面都会误报——包括渲染了本插件源码注释的本地 dashboard。现在:① **本机地址(loopback)不做文本探测**;② 改为匹配**挑战短语**而非裸名词。选择器命中逻辑不变(真实 reCAPTCHA/hCaptcha/Turnstile/Cloudflare 容器仍立即上报)。worker 内的并行探针同步修改。 - **DSH 0.1.7 设置保存后不再静默(0.1.7 forms 路径)**:适配后读路径切到了 loader 活配置,但**没有任何变更订阅**,`onChange()` 保存后零次触发——投屏 worker 的热推送只在下次 spawn 才看到新值(worker 常驻时永远看不到)。现订阅宿主 `settings/document-updated`(forms 服务 `describe()` 后发出),**一条订阅覆盖插件页表单与 `/ego/api/set` 网关两条写入路径**,随插件 fiber 卸载。 - **`--open` 在 Windows 上退出码为 1(#62)**:`process.exit(0)` 在 CDP socket 仍在关闭时执行,触发 libuv `!(handle->flags & UV_HANDLE_CLOSING)` 断言——窗口正常抬起但退出码非 0,按 `$LASTEXITCODE` 判断的调用方视为失败。现改为设置 `process.exitCode` 让事件循环自然退出,加 unref 的 3 秒兜底防句柄泄漏挂起。 - **登录/验证提示的窗口名对不上(#62)**:Chrome 显示的是网页标题,按「ego lite — agent」在任务栏/Alt+Tab 都找不到。文案改为指引面板里已有的**「弹出窗口」按钮**(会置前,无头实例替换为同 Profile 有头窗口)。 ### 新增 - **DSH 0.1.7 设置页适配(插件页行配置)**:0.1.7 退役了可注册的 settings 命名空间与 `settings.plugin.item` 槽。现于 `plugins.row.config` 注册配置视图(同时按 `@dsh-external/ego-browser` 与包名 `dsh-ego-browser` 两个 bundle 名注册,键为 `#`),由宿主下发的 `ConfigPageForm` 渲染(保存走 `form.mutate(ops, revision)`),偏好字段标记 `.volatile()` 并用宿主自己的 schemastery fork 构建 schema;≤ 0.1.6 保留旧设置卡片。0.1.7 上实机验证:行页渲染全部 18 个字段,保存即时生效,重启后保留。 - **「禁用画面回传」开关 `disableFrameRelay`(PR #55,HuanLinOTO)**:可选关闭实时帧回传(含 `/api/ego/stream` 的相应行为)。 ### 社区 - 合并 PR #55(disableFrameRelay 开关,HuanLinOTO)。 - 审查并关闭 PR #59(0.1.7 设置读写):其诊断正确,但 master 上的端到端适配已覆盖同一问题且更完整(含插件页写入路径与上面的变更订阅),并在关闭说明中写明其方案未覆盖的两点。 ## [0.8.5] - 2026-09-18 — 登录态导入 + 空闲回收 + 观察窗修复群 ### 新增 - **从系统浏览器导入登录态(#46)**:新工具 `ego_login_import` + 设置卡「从系统浏览器导入登录态」区块 + `POST /api/ego/login-import` 路由。把日常 Chrome/Edge/Brave 的登录 cookie 按域名复制进 agent 浏览器:真实二进制无头启动真实 Profile(junction 别名绕过 Chromium ≥136 默认目录 CDP 限制,同时满足 App-Bound Encryption 的路径绑定),CDP `Storage.getCookies` 读取、过滤、`Storage.setCookies` 写入持久 Profile。支持 `source/domains/profile/closeSource/dryRun`;源浏览器运行中可优雅关闭后导入(窗口下次启动恢复);**导入前自动备份源 cookie 库,检测到清空自动还原**;cookie 值不进日志与输出。 - **空闲自动回收(#47,opt-in)**:新设置 `idleTimeoutMin`(默认 0 关)。N 分钟无 ego_* 调用后优雅 `--stop` 后台浏览器(实测空闲 ~425MB),下次调用 2-4s 冷启动。观看观察窗不算活动(设置文案已注明)。 - **观察窗「弹出窗口」按钮(#51)**:浮动面板与侧边栏 Tab 新增按钮,调用运行时 `ego-browser --open`——无头实例原地替换为同 Profile 有头窗口(标签页保留),有头则置前。无头模式的 CDP 预览本就可用的结论也已实测确认。 ### 修复 - **滚动后 viewport 截图全白**(PR #50):`Page.captureScreenshot` 的 clip 原点是文档坐标,viewport 截图原先固定 `{x:0,y:0}`,滚动后 clip 落在未绘制区域(`captureBeyondViewport: false`)得到空白图。现用 `pageInfo().sx/sy`(`scrollX/scrollY`)作为 clip 原点;locator 的 viewport boundingBox 同样加上滚动偏移,与 `spaces-server` followClip 一致。 - **聊天外链被观察窗抢走且无法渲染(#48)**:侧边栏 Tab 的 `urlTarget` 声明过宽(认领所有 http(s)),但该 Tab 只是推流画面。已移除声明,外链回归内置 browser 标签。 - **浏览器重启后 ego_* 全部报 task space not found**:插件侧记住的数字空间 id 在重启后悬空。新增 `runWithStaleSpaceRetry`:识别该错误后自动用空间名重建并重试一次(动作工具 + ego_cli/ego_captcha/ego_script 全覆盖)。 - **多会话时观察窗弹到错误会话(#53,PR #54)**:`markEgoToolCall` 携带调用会话 id,自动打开按会话作用域定位侧边栏;一次性守卫改为按会话,探测流常驻。 ### 社区 - 合并 PR #50(截图修复,hpqc032)、#52(观察窗英文 i18n,M4cd1r;我们补了 `wt()` 默认值修复恢复 typecheck)、#54(会话作用域,xiaochaZ)。 ## [0.8.4] - 2026-09-15 — 观察窗 worker 启动链修复 + 社区 PR 合并 ### 修复 - **观察窗在 DSH ≥ 0.1.5 永不启动(#34 / #38 / #43)**:worker spawn 缺少 0.1.5 subprocess provider 必填的 `cwd`,异常被裸 `catch` 吞掉导致 `ensureWorker()` 永远返回 null。已补 `cwd`。 - **worker 启动即自杀(#34 缺陷2 / #40)**:`stopSiblingWorkers()` 的松散子串匹配把 DSH subprocess runner 误判为同侪 worker,`taskkill /T` 连带杀掉自己的进程树,worker 在写 `ego-cast.json` 前死亡。匹配收紧为「node 的直接脚本参数是 ego-cast-worker.mjs」并排除自身祖先进程链。 - **Electron 宿主(DSH Desktop)全部 ego_* 报 no @@DSH_RESULT@@(#42)**:spawn 传显式 env 时缺 `ELECTRON_RUN_AS_NODE`,子进程被当成第二个 Electron 应用启动。`resolveEgoEnv` 与 worker spawn 在 `process.versions.electron` 存在时自动补 `ELECTRON_RUN_AS_NODE=1`。 - **worker 宕机时 /api/ego/stream 空响应(#39,PR #44)**:`proxyWorkerStream(-1)` 短路为 quiet SSE(写 `text/event-stream` 头后保持安静长连接),不再触发 `ERR_SOCKET_BAD_PORT` 把连接撕掉;含 42 行新测试。 - **Windows 下 EGO_LINUX_HEADLESS 被静默忽略(#35)**:显式 `EGO_LINUX_HEADLESS=1` 现在优先于 win32 的 `hasDisplay=true` 默认推断,与 CLI help / README 文档一致。 - **无 dsh-better-sidebar 宿主 web boot 整体阻断**:client 静态 inject 列表移除 `betterSidebar`(loader 会永远等待缺失服务),改为 `ctx.get` 探测 + 浮动观察球立即挂载 + 服务后出现时经 `ctx.inject` 升级为侧边栏 Tab(致谢 PR #45 的方案)。 ### 新增 - **`isolateSpaces` 任务空间沙盒隔离开关(PR #31)**:默认关闭,任务空间复用磁盘持久化 Profile,登录态跨重启永久保留(覆盖 #1 诉求);开启后恢复内存沙盒隔离。`ego_space_open`/`ego_space_close` 工具描述随模式动态注入;修复 gateway 布尔设置无法持久化的问题。 ### 其他 - 修复 `pnpm-workspace.yaml` 未填的 `allowBuilds` 模板占位符导致 pnpm 11 无法 install;补 `isolateSpaces` 的 config 测试夹具。 - 合并 PR #36(README 版本兼容矩阵)、#31、#44;关闭被覆盖的 #45。 ## [0.8.3] - 2026-09-07 — DSH 0.1.2-rc.1 兼容 + 安全/稳定性修复 ### 安全 - **修复无认证 `/api/ego/*` 路由**:exact 路由先于宿主 `/api` prefix 信任栅栏命中,导致 `GET /api/ego/stream` 无凭据流出实时画面帧、`POST /api/ego/input` 无凭据即可提交输入(跨站驱动)。统一包装 webServer.register,所有 ego 路由要求 SameSite=Strict 的 `dsh-auth-*` cookie,恶意网页天然不携带;守卫仅作用于本插件自身路由,不污染宿主单例上其他插件的注册。 ### 修复 - **无 dsh-better-sidebar 宿主 client 启动失败(#29)**:hard-declared `inject` 与裸 `ctx.betterSidebar` 属性访问在 strict resolver 下抛 "without inject"。保留声明(它是解析条件)+ 将访问包进 try/catch 并显式传参,无 sidebar 宿主落到浮动观察球而非整包挂死。 - **Windows 冷启动回归**:#22 的 Xvfb 支持将无 `DISPLAY` 时默认由 headless 改为起 Xvfb,而 Windows 有桌面会话、无 Xvfb → "no X display / no Xvfb binary" 冷启动失败。`ensureXDisplay` 与入口 `hasDisplay` 增加 win32 分支(桌面会话视为 display,headed 直开窗口,恢复 v0.4.0 适配行为)。 - **gateway 设置白名单缺 `egoCliArgs`/`chromeArgs`**:`/ego/api/set` 把这俩配置字段静默丢弃,设置无法持久化——已补入 `ALLOWED_KEYS`。 ### 合并(社区 PR + 本地) - 合并 6 个社区 PR:`#20` root 运行支持、`#22` xvfb、`#16` macOS headless 检测、`#24` schemastery `link:` 修复、`#28` DSH 0.1.2-rc.1/v0.1.3-alpha.1 兼容(peer/engines 收紧)、`#13` Windows 稳定性。 - 修复 dsh-plugin.json 缺逗号导致的 manifest JSON 语法错误(目录收录阻断源)。 - 新增 MIT LICENSE;补充供应链/权限说明;源码不追踪 `*.map`。 - 通过 build-dsh-plugin 官方审计:`status: READY_FOR_PINNED_SOURCE_VERIFICATION`,`route: direct`,`blockers: 0`。 ### 兼容 - `engines.dsh: >=0.1.2-rc.1`;peer 依赖全部锁定 `>=0.1.2-rc.1`。 - 已在 DSH 0.1.2-rc.1(Windows/web profile) 完成安装、启动、`ego_navigate` 真实调用、实时观察面板验收;`0.1.2-alpha.x` 声明可装但未实测;`<0.1.2-rc.1` 请用 v0.8.0 及更早。 ## [0.8.1] - 2026-08-28 — DSH 0.1.2-alpha.1 兼容 ### 变更 - **client 半体迁移到 `@deepseek-ai/dsh-client-store`**:0.1.2-alpha.1 把 `@deepseek-ai/dsh-client-runtime`(含 `/client` 子路径)重命名为 `@deepseek-ai/dsh-client-store`(客户端模块图以裸包名作为静态模块 id)。`createSnapshotStore` 签名不变。 - **client 模块注册 id = 声明包名 `dsh-ego-browser`**:0.1.2 的 boot manifest 行 id 按 package.json `name` 生成、且要求 loader 行规格名与之一致(`nearestPackage` 名相等校验);以别名(`@dsh-external/ego-browser` junction 装载键)挂载会被扫描器判为 "not a client row" → 观察面板静默消失。tsdown 的 banner ID 与 `cordis.patch.yml` 行名统一为声明包名;`dsh-plugin.json` 中的 `dsh-ego-browser` 保持不变。 - **`dsh.client.inject` 只声明真实图行包**:0.1.2 下 `@deepseek-ai/dsh-client-store` / `@deepseek-ai/dsh-client-ui-slots` 是静态模块(不在模块图),声明为注入边会导致条目组合静默 pending(模块不物化、面板不挂载、无任何报错)。仅保留 locale / ui-settings-plugins 两个真实图行。 - **webServer 可选服务改用嵌套注入交付**:0.1.2 严格服务解析器对未声明注入的 `ctx.get('webServer')` 返回 undefined → 宿主 `/api/ego/*` 观察路由静默未注册 → 面板数据层 401/空态。改为 `ctx.inject(['webServer'], cb)`(服务到位才注册路由;无 web 服务器的 TUI/headless 宿主保持 tools-only 不阻塞)。 - **peer 依赖对齐 0.1.x 家族**(client-locale / client-ui-slots / client-ui-settings-plugins / dsh-settings / dsh-tools 声明 `>=0.1.1-rc.2`),`engines.dsh: >=0.1.2-alpha.1`。 - 修复后实测:client 模块正常物化、侧边栏「Agent 浏览器」Tab 与接管观看流程可用、`/api/ego/*` 路由 200、实时推流 `streaming`、画面点击/输入链路可达(pointerdown → `/api/ego/input` → CDP 派发)。 ## [v0.8.0] - 2026-08 sidebar Tab 集成:当 `dsh-better-sidebar` 可用时,实时查看窗注册为 sidebar 原生 Tab 而非浮动浮窗。 ### 新增 - **dsh-better-sidebar Tab 集成**:`apply()` 用 `ctx.get('betterSidebar')` 机会性探测 sidebar 服务(不用 `ctx.betterSidebar`——那要求 `inject` 声明,会把 sidebar 变成硬依赖,没装时整个插件含设置卡都不加载),可用时通过 `registerTab()` 注册一个 `ego-browser:watch` Tab(`single: true`,常驻),不可用时退回原有浮动浮窗。这是 DSH 文档化的可选服务消费模式(见 approval-seam 笔记、postmortem 0001)。 - **首次 ego_* 工具调用自动打开 Tab**:`defineEgoTool` / `ego_cli` / `ego_captcha` / `ego_script` 的 execute 路径调 `markEgoToolCall()` 递增 host 端计数器,该计数器随 `/api/ego/spaces` 响应下发。`LivePreviewController` 检测计数器 0 → >0 跳变时调 `ctx.get('betterSidebar').openTab({ type: 'ego-browser:watch' })`,Tab 自动展开。`autoOpened` 标志保证每会话只开一次。 - **React Tab 组件 `EgoBrowserTab`**:用 `React.createElement` + `bindSnapshotSelector` 渲染 sidebar Tab 内容(头部 / 标签栏 / 实时主视图 / 历史覆盖层 / 登录与验证码提示条)。历史浏览轨迹从原侧抽改为覆盖式(点历史按钮接管整个 Tab 内容区,点条目进入预览或返回实时),适配 sidebar 窄宽度。 - **`LivePreviewController` vanilla 类**:从浮动浮窗的命令式 DOM 代码中提取出轮询 / SSE / 帧缓存 / 缩放 / 输入坐标逆映射 / 自动跟随逻辑,供 React 组件通过 `subscribe`+`getSnapshot` 订阅、通过方法调用转发 pointer/wheel 事件。控制器直接持有 `` ref 以 rAF 合帧频率原地替换 `src`,不触发 React 逐帧重渲染。 - **`dsh-better-sidebar` 不列为 peer 依赖**:用 `ctx.get()` 机会性消费,不需要声明 `inject`,因此也不需要把它列为 peer。装了 sidebar 就用 Tab,没装就退回浮动浮窗,两种部署都干净。 ### 设计取舍(诚实说明) - **混合而非完全重写**:React 负责 UI 结构(头部 / 标签 / 提示条 / 历史覆盖层),vanilla 控制器负责实时帧管道(SSE / rAF 合帧 / 坐标逆映射 / 输入转发)。~1000 行脆弱的实时流逻辑未用 React hooks 重写,降低回归风险。 - **历史轨迹覆盖式**:原浮动浮窗的侧抽设计在 sidebar 窄宽度(~300-400px)下两列都很窄,改为覆盖式后空间利用最好。 - **竞态条件(已知,可接受)**:若 `dsh-better-sidebar` 在 ego-browser 之后加载,`apply()` 运行时 `ctx.betterSidebar` 可能仍为 `undefined`,此时退回浮动浮窗。DSH 模块加载器通常按依赖顺序加载,sidebar 作为基础 UI 插件一般先加载;若不然,刷新页面即可。 - **浮动浮窗代码原样保留**:`mountFloatingWatch()` 是原 effect body 的机械移动,未做逻辑改动,确保无 sidebar 时的体验与 0.7.x 完全一致。 观察窗落地双画面管线:修复 CDP 协议根因,并加入可选 FFmpeg H.264/fMP4 后端。 ### 修复 - **`dsh-plugin.json` 的 `version` 与 `package.json` 重新对齐**:0.8.5→0.8.6 的发版只改了 `package.json`,已发布的 0.8.6 tarball 里这个字段仍是 `0.8.5`(0.8.4 时犯过同一个错并单独修过)。DSH 0.1.7 的插件管理器读 `package.json` 的 `dsh` 字段、从不读这个文件,所以对运行没有任何影响,纯清单卫生问题。已加 `tests/manifest-consistency.test.ts` 把两者钉死(连同「CHANGELOG 里必须有当前版本号」和「`id` 与包名一致」)。 ### 新增 / 优化 - **用户自定义启动参数**:设置卡新增 `ego-browser CLI 附加参数` 与 `Chrome 启动附加参数` 两个字段。前者追加到 `ego-browser nodejs` argv,下一次 `ego_*` 工具调用即生效;后者经 `EGO_LINUX_EXTRA_ARGS` 桥接到 vendored runtime 的 `launch()`,仅浏览器下次冷启动生效(浏览器是单例常驻——需 `ego-browser --stop` 或重启 DSH 才会重新启动)。两边都拉黑会破坏插件自管控制面的标志(`--status`/`--stop`/`--help`/`--user-data-dir`/`--remote-debugging-port`/`--headless`/`--proxy-server` 等);`--proxy-server` 请走 `EGO_LINUX_PROXY`。`ego_doctor` 报告当前生效参数。 - FFmpeg 改为显式按需安装:CDP 不再依赖或安装 `ffmpeg-static`。设置页优先检测自定义路径、系统 PATH 和托管缓存,兼容性检查完成前禁用 FFmpeg 选项,并提供固定版本、SHA-256 校验的一键下载。 - 新增 `githubMirror`,用用户填写的 HTTPS 基址替换 `https://github.com`;Windows/Linux 固定 BtbN release tag,macOS 固定平台资产。下载进入 `~/.dsh/cache/ego-browser/ffmpeg/` 临时目录,校验、解压和能力探测全部成功后才原子发布。 - 观察画面新增局部键盘输入代理:普通文本和粘贴走 `Input.insertText`,中文 IME 在 composition 完成后一次发送,控制键和快捷键走 `Input.dispatchKeyEvent`。只在点击观察画面后聚焦,不抢 DSH 自身输入。 - 新增 `ffmpegBitrateKbps` 设置(500-20000 kbps);低/平衡/高档默认 2000/4000/8000 kbps。编码器使用目标码率、峰值码率与 VBV buffer,替代 `h264_mf` 的约 200 kbps 默认值和 `libx264 crf=28`。 - DSH 窗口进入后台时保持 watch/SSE/video 连续;lease TTL 提高到 120 秒,并对 start/switch/renew 请求做单飞去重,避免后台定时器节流造成 capture 过期和反复 `starting`。 - `CaptureManager` + watcher lease:同时只有一个活动后端和一个观看 target;面板隐藏后停止 capture。 - CDP 后端正确区分 frame ACK ID 与 flattened target session,协议错误可见;默认 20 FPS、latest-frame 限流、单 target backstop,删除透明动画强制重绘。 - FFmpeg 后端:Windows 使用 `gfxcapture(hwnd)` 直接采集 Chrome 的 D3D11 窗口 surface,其他平台保留显示来源 crop;编码为 H.264 fragmented MP4,经二进制 HTTP 与 MediaSource 播放,generation 隔离旧进程数据。 - 新设置:`captureBackend`、画质档位、CDP/FFmpeg FPS、最大宽度和编码器;旧字段集中迁移。 - 新增 MP4 parser、CDP ACK、CaptureManager、配置迁移和平台 argv 单元测试。 ### 平台限制 - Windows 要求 FFmpeg 包含 `gfxcapture`;按 browser PID、target title 和 CDP window bounds 匹配 HWND,窗口被遮挡或移动时仍采集目标页面,且禁止回退到 `gdigrab desktop`。最小化行为仍由 Windows Graphics Capture 决定。 - Linux X11 使用 `x11grab`、macOS 使用 `avfoundation` display crop;遮挡和系统权限仍会影响这两个平台。 - Wayland 随包 FFmpeg 无可用 Portal/PipeWire 输入时明确报 `unsupported-ffmpeg-pipewire`,不使用 root `kmsgrab`,不静默切换整个桌面或伪装成功。 ### 修复 - **偶发鼠标完全无请求 / 键盘始终不可用**:控制面不再依赖 `streamState` 或 spaces 同步,只按当前画面 target 发送;worker 继续做最终 stale-target 校验。此前前端没有任何键盘监听或协议支持,本次补齐 text/keyDown/keyUp 全链路。 - **FFmpeg 实际运行但 Tab 显示 CDP**:capture 状态统一从 SSE、watch 响应、spaces capture 和 watch/status 收敛;缺少 backend 时保留当前值,禁止默认覆盖为 CDP。 - **`space_open` 后遗留 about:blank 窗口**:成功打开的 task space 成为最近活动空间;后续省略 `space` 的 navigate/click/fill 等工具复用该空间,不再回退到固定 `dsh-agent` 创建第二个窗口。关闭活动空间后恢复配置默认值。 - **watch/start 502 与 input 500**:FFmpeg 二进制和 `gfxcapture` 能力探针改为异步子进程,启动期间 worker health 不再被阻塞;watch start/switch 的 worker 代理超时提高到 30 秒,覆盖窗口、编码器和 MP4 init 的完整上限。host 原样透传 worker HTTP 状态和 JSON 错误,仅在 worker 真不可达时返回 502。输入在客户端和 worker 双侧校验 target,失效 target 返回 409 `capture-target-stale`,不再包装成 500。 - **设置已选 FFmpeg 但 Tab 仍显示 CDP**:多 fiber 同时加载插件时,后注册的 settings bridge 遇到 namespace 重复后错误地退回空 composition config,cast worker 因而收到 `captureBackend:auto`。现在同一 settings 服务共享唯一 scope;设置卡、gateway 和 cast-server 始终读取同一持久化配置。空闲 worker 收到配置更新时也会立即发布新的 backend 状态,不再保留旧 CDP 标签。 - **Windows FFmpeg 不再录到用户前台窗口**:此前参数固定为 `gdigrab ... -i desktop`,只在启动时按页面坐标裁剪,Chrome 进入后台后会把覆盖区域中的 DSH 或其他应用串流出去。现在 target 先经 `Browser.getWindowForTarget` 和 Win32 顶层窗口枚举解析到 HWND,再用 `gfxcapture` 捕获独立窗口 surface;多任务空间的不同 Chrome 窗口分别绑定不同 HWND。同一窗口中的后台 tab 会报 `ffmpeg-target-not-visible`,不会展示错误 tab 或主动抢焦点。 - Windows 编码优先 `h264_mf` D3D11 硬件路径;编码器探针使用真实 HWND 管线,避免软件测试帧误判硬件编码不可用。显式 `fps/setpts` 固定 30 FPS,fMP4 分片降为 100ms,并用 `skip_trailer` 避免优雅停止时的 `mfra` parser 错误。 - **登录态跨 DSH 重启保持(复刻原版 ego-lite 哲学)**:此前手动重启 / 强杀 DSH 后需重新登录——worker 收到 SIGTERM/SIGINT 时只 detach 不落盘,且插件卸载的 `--stop` 宽限 4s 不够、常落到 SIGTERM crash 兜底。现在 worker 退场前先对浏览器发 CDP `Browser.close`(优雅关闭,Cookie journal 合并进磁盘 profile),插件 teardown 宽限提到 8s 足够优雅关完。**实测**:优雅重启登录完全保留;强杀(SIGKILL)长期登录态也已落盘、重启能读回。 ### 工程重构 - **纯 JS → TypeScript 迁移**(PR #14):源码从 `lib/` 移至 `src/`(`src/index.ts` 工具层、`src/client/index.ts` 前端、`src/worker/ego-cast-worker.ts` worker),`lib/` 与 `bin/ego-cast-worker.mjs` 改为构建产物(预构建入库)。构建链路改 `pnpm typecheck`(tsc 类型门禁,tsconfig.json + tsconfig.client.json)+ `pnpm test`(vitest)+ `pnpm run build`(tsdown 三 bundle)。测试同步迁移 `tests/*.test.mjs` → `.test.ts` 并补 `vitest.config.ts`。`lib/` 不再手改。 ## [v0.7.1] - 2026-08 修复版本:单次 `ego_space_open` 不再开两个浏览器窗口。 ### 修复 - **`ego_space_open` 不再开两个浏览器窗口**:此前 launch 时把 `"about:blank"` 作为位置参数传入,会在默认 browser context 开一个残留 tab;而 `ego_space_open` 走 `useSpace+ensureRealTab`,在自己的 browser context 里再开一个 tab——Chrome 把不同 context 隔离到独立窗口,用户就看到了两窗。现在 `LAUNCH_FLAGS` 加 `--no-startup-window`、`launch()` 不再传位置 URL,启动即零 tab;第一个 tab 由 `ego_space_open`(或任何走 `useSpace+ensureRealTab` 的结构化 `ego_*` 工具)在自己的 context 中创建,这是用户唯一看到的窗口。旧注释称 `--no-startup-window` 会破坏所有 `page.*` 操作——那是引入 `useSpace+ensureRealTab` 路由之前的结论,对结构化工具不再成立。**已知回归(可接受)**:`ego_cli` / `ego_script` 中如果 heredoc 直接调 `page.*` 而不先 `taskSpaces.useOrCreate`,现在会抛 `"no active tab to attach session"`,错误信息明确,且推荐用法不受影响。 ## [v0.7.0] - 2026-08 小版本更新:观察窗状态灯呼吸效果 + 前端内存治理 + 工具超时/跨平台修正。 ### 新增 - **观察窗状态灯呼吸效果**:FAB 角标绿点在 agent 实际驱动浏览器(`busy`)时常绿,空闲(浏览器开着、无操作)时呼吸(2.4s 周期性绿光晕);面板「正在实时浏览」状态点同步 busy/呼吸逻辑。原「busy=黄、idle=绿」语义翻转为「干活常绿、不干活呼吸」。 ### 修复 - **`ego_script` 的 `timeoutMs` 参数此前被忽略**:schema 声明的每次运行超时覆盖从未生效,所有运行一律采用插件默认 15s 宽限。现已贯穿 `runEgoScript`,传 `timeoutMs` 真正起作用,缺省/非法时回落默认。 - **前端内存治理**:观察窗 `frameCache`(各标签最新一帧 JPEG dataURL)与 `pageMeta` 按 `targetId` 无限累积,长会话/多标签会缓慢泄漏。现在按当前存活标签表剪除已关闭标签的缓存,并给 `frameCache` 加 `MAX_CACHED_FRAMES=12` 最旧优先上限兜底。 - **硬编码 `/root` 家目录回退改为 `os.homedir()`**:状态路径探测中 POSIX 默认家目录由环境相关的 `/root` 改为跨平台正确的 `os.homedir()`,消除非 root 用户/容器环境的隐患。 ### 工程 - 新增 `.gitattributes`:统一 LF 换行(`* text=auto eol=lf`),消除 Windows 侧 `core.autocrlf` 造成的工作树 CRLF 抖动与 diff/cp 误判。 ## [v0.6.1] - 2026-04 修复版本:自愈链路 + 观察窗 worker 稳定性、面板引导条可用性。 ### 修复 - **插件卸载不再阻塞宿主退出 / 破坏自愈**:`ctx.effect` teardown 由 `await ego-browser --stop`(15s 宽限,拖住宿主退出)改为 fire-and-forget,宿主可被 `dsh-web-guard` 在 10s 内干净拉起、被中断 turn 自动续接。 - **观察窗 worker 单实例守卫 + stale 状态清理**:同一份 `ego-cast-worker.mjs` 可能同时从安装目录与 dev 克隆被拉起、且 `ensureWorker` 在已知 pid 失效时会再拉起一个,导致 `ego-cast.json` 恒指向已死/滞后的 worker、面板失去推流。现在 worker 启动即枚举并停止其他同名进程(Windows 经 `powershell -EncodedCommand`,POSIX 走 `ps`),并删除 stale 的 `ego-cast.json`,让本进程 `{port,pid}` 成为唯一权威。 - **登录 / 人机验证引导条支持手动关闭**:新增 × 按钮;两条引导条互斥显示(人机验证优先),不再"关不掉"或"双条叠加压缩画面"。 - **观察窗主动跟随 agent 正在操作的页面**:此前面板用"最后一次重绘"(lastActive) 当作当前页,后台动画/视频页重绘会抢占视图,agent 切页时主画面不跳转。现 worker 经 DevTools `/json/list` 取浏览器 MRU 激活 tab(与 ego runtime `tabs.mjs` 同源判定),在 `/api/spaces` 与 SSE 中都标记 `active: true` 并排第一;前端 auto-follow 仅跟随激活页、忽略后台重绘帧。 ## [v0.6.0] - 2026-04 代码健康治理(工程收敛)。 - 消除构建覆盖炸弹:删除过时的 `src/`(561 行旧版)与 `tsconfig.json`,确立 **`lib/` 为唯一权威源**。`npm run build` 由「tsc 编译 src→lib(会导致旧版覆盖、工具全丢)」改为「对 `lib/` 做语法校验(`node --check`)」。 - 统一工具注册:`ego_captcha` / `ego_help` / `ego_doctor` / `ego_script` 改为与其他工具一致的 `withEgoLock` + 冷启动重试路径(并发安全)。 - 不再分叉:新增能力(下载捕获、人机验证检测、30+ 工具)以 `lib/` 为准。 ## [v0.5.0] - 2026-04 实时推流 + 监控窗直接操作浏览器。 - 修复实时推流关键 bug:`screencastFrame` 匹配错误字段,实时帧从未真正经 SSE 推送。已修正,动态页面接近 10~30fps 推帧。 - cast-server 流式转发改用 `node:http`(fetch 对 chunked 响应缓冲导致首帧延迟)。 - 监控窗鼠标直接操作 agent 浏览器:滚轮滚动、点按/拖动点击真实浏览器(`/api/ego/input` → CDP `Input.dispatchMouseEvent`),Ctrl+滚轮缩放、Ctrl+拖动平移、双击复位,坐标按真实视口逆映射含 letterbox 校正。 - 新增 `/api/ego/stream`(SSE)实时帧 + 页面列表。 - 登录引导条 +「已登录,保存」(触发 `/api/ego/flush` 落盘);修复 `ego_auth_flush` Windows 状态目录路径。 ## [v0.4.0] - 2026-04 跨平台(Windows 适配落地)。 - Windows 原生支持:`IS_WIN` + `windowsChromeCandidates()` 自动探测 Chrome/Edge/Brave 安装目录与 `PATH`/`%PATHEXT%`。 - 注入服务改为 `webServer`/`httpServer` 二选一,Windows 也能挂载观察窗。 - 状态路径跨平台:Windows 用 `%LOCALAPPDATA%\ego-lite-linux`,POSIX 用 `$XDG_STATE_HOME/ego-lite-linux`。 ## [v0.3.0] - 2026-04 修复与增强。 - 冷启动自动重试:每个 `ego_*` 动作新起 `ego-browser` 子进程,会话预热期偶发 `CDP channel is not open` / DevTools 超时。内置最多 3 次逐步退避重试,仅对瞬时冷启动错误重试,真错误立即透传。 ## [v0.2.0] - 2026-04 亮点:实时观察前端口。 - `lib/client.js`:深色毛玻璃 UI,右下角 🌐 小球常驻,点开见 agent 实时画面。 - 标签管理:横排标签条 + 每标签 `×` 关闭(真正关浏览器标签)。 - 缩放/拖拽/复位、动态轮询(活跃 2s / 静止 8s)、导航复用 tab。 - `bin/ego-cast-worker.mjs`:attach 到 agent 正在用的浏览器,CDP 实时推帧,崩溃自动重启。 - 开箱即用:`bin/ego-chrome-wrapper.sh` 随包自带,root/无头自动 `--no-sandbox`。