@sleepinsummer/agent-browser-cli 0.2.0

package/AI_INSTALL.md

@@ -0,0 +1,126 @@
+# AI 安装说明
+
+把下面这段话发给 AI，让 AI 在你的本机环境里完成安装、配置 skill 和验证。
+
+```text
+请帮我安装 agent-browser-cli：https://github.com/sleepinginsummer/agent-browser-cli
+
+要求：
+1. 优先使用 npm 安装：npm install -g @sleepinsummer/agent-browser-cli。
+2. 指导我在 Chrome 中加载 assets/tmwd_cdp_bridge 解压扩展。
+3. 如果之前已经加载过扩展，必须在 chrome://extensions 里重新加载 `assets/tmwd_cdp_bridge`，确保最新 `config.js` 和 `background.js` 生效。
+4. 将 skills/agent-browser-cli/SKILL.md 安装到当前 AI 可识别的 skills 目录。
+5. 执行 agent-browser-cli tabs、open 和 status 验证可用。
+6. 如果 npm 平台包暂不支持当前系统，再回退到源码构建：cargo build --release。
+```
+
+## 1. 安装 CLI
+
+优先使用 npm 全局安装：
+
+```bash
+npm install -g @sleepinsummer/agent-browser-cli
+agent-browser-cli --help
+```
+
+当前 npm 包按平台安装原生二进制：
+
+```text
+@sleepinsummer/agent-browser-cli
+@sleepinsummer/agent-browser-cli-darwin-arm64
+@sleepinsummer/agent-browser-cli-darwin-x64
+@sleepinsummer/agent-browser-cli-win32-x64
+```
+
+如果当前平台包暂未发布或安装失败，使用源码构建：
+
+```bash
+git clone https://github.com/sleepinginsummer/agent-browser-cli.git
+cd agent-browser-cli
+cargo build --release
+./target/release/agent-browser-cli --help
+```
+
+## 2. 加载 Chrome 扩展
+
+如果使用 npm 安装，需要先下载或克隆仓库，用于加载扩展和安装 skill：
+
+```bash
+git clone https://github.com/sleepinginsummer/agent-browser-cli.git
+cd agent-browser-cli
+```
+
+在 Chrome 打开：
+
+```text
+chrome://extensions
+```
+
+开启“开发者模式”，加载已解压扩展目录：
+
+```text
+assets/tmwd_cdp_bridge
+```
+
+如果之前已经安装过旧版 GenericAgent 的 `tmwd_cdp_bridge` 扩展，可以继续使用同协议旧扩展；但建议加载当前仓库的 `assets/tmwd_cdp_bridge` 并点击“重新加载”。
+
+当前扩展配置应包含：
+
+```js
+const TID = '__agent_browser_cli_bridge_26c9f1';
+```
+
+Chrome 至少需要打开一个正常网页标签页，不要只停留在 `about:blank` 或 `chrome://` 页面。
+
+## 3. 安装 skill
+
+将仓库中的 `skills/agent-browser-cli/SKILL.md` 安装到 AI 使用的 skills 目录。
+
+通用目录示例：
+
+```bash
+mkdir -p ~/.agents/skills/agent-browser-cli
+cp skills/agent-browser-cli/SKILL.md ~/.agents/skills/agent-browser-cli/SKILL.md
+```
+
+Codex 默认目录示例：
+
+```bash
+mkdir -p ~/.codex/skills/agent-browser-cli
+cp skills/agent-browser-cli/SKILL.md ~/.codex/skills/agent-browser-cli/SKILL.md
+```
+
+如果 AI 使用其它 skills 目录，将 `SKILL.md` 复制到对应的 `agent-browser-cli/SKILL.md`。
+
+## 4. 验证
+
+```bash
+agent-browser-cli tabs
+agent-browser-cli open https://www.baidu.com
+agent-browser-cli status
+```
+
+成功时，`tabs` 会返回 `ok: true`，并包含当前 Chrome 标签页数量。
+`open` 应能原生新开标签页，不应使用 `exec --monitor` 或 `window.open` 代替。
+
+如果常驻服务需要重载最新代码：
+
+```bash
+agent-browser-cli restart
+```
+
+## 5. 使用入口
+
+拿到标签页 ID 后，可以执行：
+
+```bash
+agent-browser-cli scan --tab <tabId> --text-only
+agent-browser-cli exec --tab <tabId> 'return document.title'
+```
+
+完整命令和浏览器操作 SOP 见：
+
+```text
+skills/agent-browser-cli/SKILL.md
+```
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sleepinginsummer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+<div align="center">
+
+# agent-browser-cli
+
+面向 Agent 的浏览器感知与控制 CLI，把真实 Chrome 会话变成可复用的标签页扫描、页面 JS、Cookie、CDP 和截图能力。
+
+浏览器感知 · 页面控制 · Chrome 登录态复用 · CDP · 条件等待 · Agent Skill 集成
+
+<p>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli"><img src="https://img.shields.io/badge/CLI-agentbrowsercli-2ea44f" alt="CLI agentbrowsercli"></a>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License MIT"></a>
+    <a href="https://github.com/sleepinginsummer/agent-browser-cli"><img src="https://img.shields.io/badge/Windows-MacOS-0078D6?labelColor=0078D6&color=C0C0C0" alt="Windows/MacOS"></a>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli/releases"><img src="https://img.shields.io/badge/release-v0.2.0-blue" alt="release v0.2.0"></a>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"></a>
+</p>
+
+[AI 一句话安装](#ai-一句话安装) · [手动安装](#手动安装) · [Chrome 扩展](#chrome-扩展) · [更新](#更新) · [卸载](#卸载) · [友情链接](#友情链接)
+
+中文 | [English](README_EN.md)
+
+</div>
+
+`agent-browser-cli` 是一个面向 Agent 的浏览器感知与控制工具。它通过 Chrome 扩展连接用户真实浏览器，保留登录态和 Cookie，提供标签页扫描、页面 JS 执行、Cookie 读取、CDP 控制、截图、文件上传、下拉框点击等能力。
+
+本项目不是 Selenium / Playwright。它更适合在已有浏览器会话中辅助 Agent 精确读取页面和执行操作。
+
+## 项目信息
+
+- 当前版本：`0.2.0`
+- 支持平台：Windows、macOS
+- 运行时：Rust 原生二进制；npm 安装时按平台选择二进制包
+- 浏览器：Chrome / Chromium，需加载 `assets/tmwd_cdp_bridge`
+
+## 致谢
+
+本项目的浏览器控制能力提取并改造自 [GenericAgent](https://github.com/lsdefine/GenericAgent) 项目中的 Web 工具链，包括 `TMWebDriver`、`simphtml` 和 `tmwd_cdp_bridge` 扩展相关思路与实现。
+
+感谢 GenericAgent 项目提供的浏览器桥接、页面简化、CDP 控制和实践 SOP。本仓库在此基础上做了面向独立使用和 CLI 调用的整理与增强。
+
+## AI 一句话安装
+
+```text
+请阅读 https://github.com/sleepinginsummer/agent-browser-cli/blob/main/AI_INSTALL.md，按说明安装 CLI、加载 Chrome 扩展，并添加 `skills/agent-browser-cli/SKILL.md`。
+```
+
+## 改进内容
+
+- 从 GenericAgent 中拆出浏览器控制能力，使用cli 提供给codex、claude code、opencode使用。GenericAgent浏览器插件不需要重新安装，可以共用同一个插件
+- 避免每次命令都重新初始化浏览器连接。
+- 新增启动锁，避免多个 CLI 并发启动时重复绑定底层端口。
+- 增加skill：`skills/agent-browser-cli/SKILL.md`，提供ai参考使用。
+- 若干优化，缩短命令执行时间
+
+## 目录结构
+
+```text
+.
+├── agent_browser_cli.py          # 命令行入口
+├── agent_browser_server.py       # 常驻 HTTP 服务
+├── ga.py                         # web_scan / web_execute_js 入口
+├── TMWebDriver.py                # 浏览器扩展 WebSocket / HTTP 桥
+├── simphtml.py                   # 页面简化和 DOM diff
+├── assets/tmwd_cdp_bridge/       # Chrome MV3 扩展
+├── memory/                       # 浏览器工具 SOP
+└── skills/agent-browser-cli/     #  skill
+```
+
+## 手动安装
+
+### npm 安装
+
+```bash
+npm install -g @sleepinsummer/agent-browser-cli
+agent-browser-cli tabs
+```
+
+当前 npm 分发采用主包 + 平台二进制包：
+
+```text
+@sleepinsummer/agent-browser-cli
+@sleepinsummer/agent-browser-cli-darwin-arm64
+@sleepinsummer/agent-browser-cli-darwin-x64
+@sleepinsummer/agent-browser-cli-win32-x64
+```
+
+### 本地源码构建
+
+```bash
+cargo build --release
+./target/release/agent-browser-cli tabs
+```
+
+### Python 旧版运行方式
+
+Python 实现暂时保留为迁移参考和回退入口：
+
+```bash
+cd /path/to/agent-browser-cli
+python3 -m venv .venv
+.venv/bin/python -m pip install -r requirements.txt
+```
+
+## Chrome 扩展
+
+加载扩展目录：
+
+```text
+assets/tmwd_cdp_bridge
+```
+
+Chrome 需要至少打开一个正常网页标签页，不要只停留在 `about:blank` 或 `chrome://` 页面。
+
+## 快速自检
+
+```bash
+agent-browser-cli tabs
+agent-browser-cli open https://www.baidu.com
+```
+
+成功时会返回：
+
+```json
+{
+  "ok": true,
+  "result": {
+    "status": "success",
+    "metadata": {
+      "tabs_count": 1
+    }
+  }
+}
+```
+
+## 常用命令
+
+README 只保留快速入口；完整命令和浏览器操作 SOP 见 [skills/agent-browser-cli/SKILL.md](./skills/agent-browser-cli/SKILL.md)。
+
+```bash
+agent-browser-cli tabs
+```
+
+## 更新
+
+```bash
+git pull
+cargo build --release
+./target/release/agent-browser-cli restart
+```
+
+如果 Chrome 扩展有更新，在 `chrome://extensions` 中重新加载 `assets/tmwd_cdp_bridge` 扩展。
+
+当前扩展配置标识为：
+
+```js
+const TID = '__agent_browser_cli_bridge_26c9f1';
+```
+
+如果你把 skill 安装到了 Codex/Agent 的全局目录，更新后同步复制：
+
+```bash
+mkdir -p ~/.agents/skills/agent-browser-cli
+cp skills/agent-browser-cli/SKILL.md ~/.agents/skills/agent-browser-cli/SKILL.md
+```
+
+## 卸载
+
+先停止常驻服务：
+
+```bash
+agent-browser-cli stop
+```
+
+然后按需清理：
+
+```bash
+rm -f .agent-browser-cli.log .agent-browser-cli.lock
+rm -rf ~/.agents/skills/agent-browser-cli
+```
+
+最后在 Chrome 扩展管理页中移除 `TMWD CDP Bridge` 扩展，或删除已加载的 `assets/tmwd_cdp_bridge` 扩展配置。
+
+## 端口
+
+- `18765`：底层 `TMWebDriver` WebSocket，Chrome 扩展连接使用。
+- `18766`：底层 `TMWebDriver` HTTP `/link`，用于内部 master/remote 协议。
+- `18767`：外层 `agent-browser-cli` HTTP 服务，供 CLI 复用会话。
+
+## 友情链接
+
+- [LINUX DO - 新的理想型社区](https://linux.do/)
+
+## 许可证
+
+MIT License. See [LICENSE](./LICENSE).

package/README_EN.md

@@ -0,0 +1,169 @@
+<div align="center">
+
+# agent-browser-cli
+
+A browser perception and control CLI for agents, turning a real Chrome session into reusable tab scanning, page JavaScript, Cookie, CDP, and screenshot capabilities.
+
+Browser perception · Page control · Chrome session reuse · CDP · Conditional wait · Agent Skill integration
+
+<p>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli"><img src="https://img.shields.io/badge/CLI-agentbrowsercli-2ea44f" alt="CLI agentbrowsercli"></a>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License MIT"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-%3E%3D3.10-3776AB?logo=python&logoColor=white" alt="Python >=3.10"></a>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli"><img src="https://img.shields.io/badge/Windows-MacOS-0078D6?labelColor=0078D6&color=C0C0C0" alt="Windows/MacOS"></a>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli/releases"><img src="https://img.shields.io/badge/release-v0.1.1-blue" alt="release v0.1.1"></a>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"></a>
+</p>
+
+[AI One-Line Install](#ai-one-line-install) · [Manual Installation](#manual-installation) · [Chrome Extension](#chrome-extension) · [Update](#update) · [Uninstall](#uninstall) · [Friendly Links](#friendly-links)
+
+[中文](README.md) | English
+
+</div>
+
+`agent-browser-cli` is a browser perception and control tool for agents. It connects to the user's real Chrome browser through a Chrome extension, preserving login state and cookies while providing tab scanning, page JavaScript execution, cookie reading, CDP control, screenshots, file uploads, dropdown clicks, and related capabilities.
+
+This project is not Selenium or Playwright. It is better suited for helping agents read pages accurately and perform actions inside an existing browser session.
+
+## Project Info
+
+- Current version: `0.1.1`
+- Supported platforms: Windows, macOS
+- Python: `3.10+` recommended
+- Browser: Chrome / Chromium, with `assets/tmwd_cdp_bridge` loaded
+
+## Acknowledgements
+
+The browser control capability in this project was extracted and adapted from the Web toolchain in [GenericAgent](https://github.com/lsdefine/GenericAgent), including ideas and implementation around `TMWebDriver`, `simphtml`, and the `tmwd_cdp_bridge` extension.
+
+Thanks to the GenericAgent project for the browser bridge, page simplification, CDP control, and practical SOPs. This repository reorganizes and enhances that work for standalone usage and CLI invocation.
+
+## AI One-Line Install
+
+```text
+Please read https://github.com/sleepinginsummer/agent-browser-cli/blob/main/AI_INSTALL.md, follow the instructions to install the CLI, load the Chrome extension, and add `skills/agent-browser-cli/SKILL.md`.
+```
+
+## Improvements
+
+- Extracted browser control capability from GenericAgent and exposed it as a CLI for Codex, Claude Code, and OpenCode. The GenericAgent browser extension can be reused and does not need to be reinstalled.
+- Avoids reinitializing the browser connection for every command.
+- Adds a startup lock to avoid repeated low-level port binding when multiple CLI commands start concurrently.
+- Adds the skill `skills/agent-browser-cli/SKILL.md` for AI usage reference.
+- Includes several optimizations to reduce command execution time.
+
+## Layout
+
+```text
+.
+├── agent_browser_cli.py          # CLI entry
+├── agent_browser_server.py       # Long-lived HTTP service
+├── ga.py                         # web_scan / web_execute_js entry
+├── TMWebDriver.py                # Browser extension WebSocket / HTTP bridge
+├── simphtml.py                   # Page simplification and DOM diff
+├── assets/tmwd_cdp_bridge/       # Chrome MV3 extension
+├── memory/                       # Browser tool SOPs
+└── skills/agent-browser-cli/     # skill
+```
+
+## Manual Installation
+
+```bash
+cd /path/to/agent-browser-cli
+python3 -m venv .venv
+.venv/bin/python -m pip install -r requirements.txt
+```
+
+## Chrome Extension
+
+Load this extension directory:
+
+```text
+assets/tmwd_cdp_bridge
+```
+
+Chrome needs at least one normal web page tab open. Do not leave it only on `about:blank` or `chrome://` pages.
+
+## Quick Check
+
+```bash
+.venv/bin/python agent_browser_cli.py tabs
+.venv/bin/python agent_browser_cli.py open https://www.baidu.com
+```
+
+On success, it returns:
+
+```json
+{
+  "ok": true,
+  "result": {
+    "status": "success",
+    "metadata": {
+      "tabs_count": 1
+    }
+  }
+}
+```
+
+## Common Commands
+
+The README only keeps the quick entry point. For the full command list and browser operation SOP, see [skills/agent-browser-cli/SKILL.md](./skills/agent-browser-cli/SKILL.md).
+
+```bash
+.venv/bin/python agent_browser_cli.py tabs
+```
+
+## Update
+
+```bash
+git pull
+.venv/bin/python -m pip install -r requirements.txt
+.venv/bin/python agent_browser_cli.py restart
+```
+
+If the Chrome extension has updates, reload the `assets/tmwd_cdp_bridge` extension in `chrome://extensions`.
+
+Current extension bridge identifier:
+
+```js
+const TID = '__agent_browser_cli_bridge_26c9f1';
+```
+
+If you installed the skill into a global Codex/Agent directory, copy it again after updating:
+
+```bash
+mkdir -p ~/.agents/skills/agent-browser-cli
+cp skills/agent-browser-cli/SKILL.md ~/.agents/skills/agent-browser-cli/SKILL.md
+```
+
+## Uninstall
+
+Stop the long-lived service first:
+
+```bash
+.venv/bin/python agent_browser_cli.py stop
+```
+
+Then clean up as needed:
+
+```bash
+rm -rf .venv
+rm -f .agent-browser-cli.log .agent-browser-cli.lock
+rm -rf ~/.agents/skills/agent-browser-cli
+```
+
+Finally, remove the `TMWD CDP Bridge` extension from Chrome's extension management page, or remove the loaded `assets/tmwd_cdp_bridge` extension configuration.
+
+## Ports
+
+- `18765`: underlying `TMWebDriver` WebSocket, used by the Chrome extension.
+- `18766`: underlying `TMWebDriver` HTTP `/link`, used by the internal master/remote protocol.
+- `18767`: outer `agent-browser-cli` HTTP service, used by the CLI to reuse the session.
+
+## Friendly Links
+
+- [LINUX DO - A New Ideal Community](https://linux.do/)
+
+## License
+
+MIT License. See [LICENSE](./LICENSE).