release: prepare v0.3.1-beta.1

Author: sleepinginsummer

.github/workflows/publish.yml

@@ -80,7 +80,12 @@ jobs:
           set -euo pipefail
           PACKAGE_NAME=$(node -p "require('./package.json').name")
           PACKAGE_VERSION=$(node -p "require('./package.json').version")
-          if npm publish --access public; then
+          if [[ "${GITHUB_REF_NAME}" == *-* ]]; then
+            NPM_TAG="${NPM_TAG:-beta}"
+          else
+            NPM_TAG="${NPM_TAG:-latest}"
+          fi
+          if npm publish --access public --tag "${NPM_TAG}"; then
             exit 0
           fi
           if [ "$(npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" version 2>/dev/null || true)" = "${PACKAGE_VERSION}" ]; then
@@ -126,7 +131,12 @@ jobs:
           set -euo pipefail
           PACKAGE_NAME=$(node -p "require('./package.json').name")
           PACKAGE_VERSION=$(node -p "require('./package.json').version")
-          if npm publish --access public; then
+          if [[ "${GITHUB_REF_NAME}" == *-* ]]; then
+            NPM_TAG="${NPM_TAG:-beta}"
+          else
+            NPM_TAG="${NPM_TAG:-latest}"
+          fi
+          if npm publish --access public --tag "${NPM_TAG}"; then
             exit 0
           fi
           if [ "$(npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" version 2>/dev/null || true)" = "${PACKAGE_VERSION}" ]; then
@@ -210,8 +220,13 @@ jobs:
             else
               printf '%s\n' "${DEFAULT_NOTES}" > release-notes.md
             fi
+            release_flags=()
+            if [[ "${GITHUB_REF_NAME}" == *-* ]]; then
+              release_flags+=(--prerelease)
+            fi
             gh release create "${GITHUB_REF_NAME}" "${release_assets[@]}" \
               --repo "${GITHUB_REPOSITORY}" \
               --title "${GITHUB_REF_NAME}" \
-              --notes-file release-notes.md
+              --notes-file release-notes.md \
+              "${release_flags[@]}"
           fi

AI_INSTALL.md

@@ -10,8 +10,8 @@
 2. 先询问我希望把 Chrome 扩展解压到哪个本地目录。
 3. 从 GitHub 最新 Release 下载 `chrome-extensions.zip`，解压到我指定的目录，并指导我在 Chrome 中加载解压后的 `tmwd_cdp_bridge` 扩展目录。
 4. 如果之前已经加载过扩展，必须在 chrome://extensions 里重新加载该扩展，确保最新 `config.js`、`content.js` 和 `background.js` 生效。
-5. 将 skills/agent-browser-cli/SKILL.md 安装到当前 AI 可识别的 skills 目录。
-6. 执行 agent-browser-cli tabs、open 和 status 验证可用。
+5. skill 从 npm 包内置的 `skills/agent-browser-cli` 复制安装，不需要从 GitHub 下载 SKILL.md；先执行 `agent-browser-cli install-skill --dry-run` 展示安装计划，向我确认后再执行 `agent-browser-cli install-skill`。
+6. 执行 agent-browser-cli status、doctor、tabs、open 验证可用。
 7. 如果 npm 平台包暂不支持当前系统，再回退到源码构建：cargo build --release。
 ```
 
@@ -101,33 +101,54 @@ Chrome 至少需要打开一个正常网页标签页，不要只停留在 `about
 
 ## 3. 安装 skill
 
-将仓库中的 `skills/agent-browser-cli/SKILL.md` 安装到 AI 使用的 skills 目录。
+`agent-browser-cli install-skill` 使用 CLI 包内置的 skill 目录作为来源。npm 全局安装时，来源位于 npm 包内部的 `skills/agent-browser-cli`，不会联网，也不会从 GitHub 拉取 `SKILL.md`。源码构建时，来源为仓库内的同名目录。
 
-通用目录示例：
+默认实体安装目录：
+
+```text
+~/.agents/skills/agent-browser-cli
+```
+
+Codex、Claude、Kimi CLI、Cursor、Gemini 等目录只创建指向主安装目录的软链接，不复制多份实体文件：
+
+```text
+~/.codex/skills/agent-browser-cli -> ~/.agents/skills/agent-browser-cli
+~/.claude/skills/agent-browser-cli -> ~/.agents/skills/agent-browser-cli
+~/.config/agents/skills/agent-browser-cli -> ~/.agents/skills/agent-browser-cli
+~/.cursor/skills/agent-browser-cli -> ~/.agents/skills/agent-browser-cli
+~/.gemini/skills/agent-browser-cli -> ~/.agents/skills/agent-browser-cli
+```
+
+安装前必须先展示真实计划，并让用户确认。dry-run 输出中的“复制内置 skill 目录”就是本次安装的实际来源：
+
+```bash
+agent-browser-cli install-skill --dry-run
+```
+
+确认后再执行：
 
 ```bash
-mkdir -p ~/.agents/skills/agent-browser-cli
-cp skills/agent-browser-cli/SKILL.md ~/.agents/skills/agent-browser-cli/SKILL.md
+agent-browser-cli install-skill
 ```
 
-Codex 默认目录示例：
+`--yes` 只适合脚本化安装，不建议默认使用：
 
 ```bash
-mkdir -p ~/.codex/skills/agent-browser-cli
-cp skills/agent-browser-cli/SKILL.md ~/.codex/skills/agent-browser-cli/SKILL.md
+agent-browser-cli install-skill --yes
 ```
 
-如果 AI 使用其它 skills 目录，将 `SKILL.md` 复制到对应的 `agent-browser-cli/SKILL.md`。
+安装命令不会覆盖 Codex/Claude/Kimi CLI/Cursor/Gemini 目录下已存在的非软链接实体路径；即使使用 `--yes` 也会跳过并提示用户手动处理。
 
 ## 4. 验证
 
 ```bash
+agent-browser-cli status
+agent-browser-cli doctor
 agent-browser-cli tabs
 agent-browser-cli open https://www.baidu.com
-agent-browser-cli status
 ```
 
-成功时，`tabs` 会返回 `ok: true`，并包含当前 Chrome 标签页数量。
+成功时，`status` 应返回 `healthy: true` 和 `summary: "ready"`；`tabs` 会返回 `ok: true`，并包含当前 Chrome 标签页数量。
 `open` 应能原生新开标签页，不应使用 `exec --monitor` 或 `window.open` 代替。
 
 如果常驻服务需要重载最新代码：
@@ -145,7 +166,13 @@ agent-browser-cli scan --tab <tabId> --text-only
 agent-browser-cli exec --tab <tabId> 'return document.title'
 ```
 
-完整命令和浏览器操作 SOP 见：
+完整命令和浏览器操作 SOP 见安装后的：
+
+```text
+~/.agents/skills/agent-browser-cli/SKILL.md
+```
+
+源码仓库中的对应文件为：
 
 ```text
 skills/agent-browser-cli/SKILL.md

CHANGELOG.md

@@ -0,0 +1,140 @@
+# 更新日志
+
+所有重要变更都会记录在这里。日期使用北京时间自然日。
+
+## v0.3.1-beta.1 - 2026-05-16
+
+### 新增
+
+- 新增 `logs`：读取 `~/.agent-browser-cli/logs/daemon.log`，支持 `--tail`。
+- 新增 `doctor`：输出 JSON 诊断信息，不自动启动 daemon。
+- 新增 `install-skill`：支持 `--dry-run` 和 `--yes`，用于安装/更新 Agent skill。
+- 增强 `status`：新增 `healthy`、`summary`、`message`，保留旧字段。
+- 新增 `snapshot`：基于 Chrome Accessibility Tree 生成 `@e` 操作引用，支持 `--offset`、`--limit`、`--details`、`--tab`。
+- 新增高层操作命令：`click`、`fill`、`send-keys`、`mouse-click`。
+- 新增 `screenshot`：支持视口截图、全页截图、元素截图、PNG/JPEG、默认落盘目录。
+- 新增 `save-pdf`：支持纸张、横向、缩放、打印背景、默认文件名清理和 50MB 上限。
+- 新增 `network` 调试命令：`start`、`list`、`detail`、`clear`、`stop`。
+- 新增 `console` 调试命令：`start`、`list`、`clear`、`stop`。
+- `open 新增 `--session` 和 `--group-title`，支持 Chrome 原生 tab group。
+- 新增 `close --tab <tabId>`，通过扩展原生 `chrome.tabs.remove` 关闭标签页。
+- Chrome 扩展新增 bot 图标，显示名改为 `Agent Browser CLI Bridge`。
+- daemon 退出时清理 daemon 缓存，并通知扩展清理 network/console 调试缓存。
+
+### 调整
+
+- daemon stdout/stderr 日志固定写入用户目录，不再落到当前目录或 npm 包目录。
+- npm wrapper 设置 `AGENT_BROWSER_CLI_PACKAGE_DIR`，方便全局安装后定位内置 skill。
+- `network stop` / `console stop` 会停止监听并清理对应缓存。
+- skill 文档重写为 Agent 操作 SOP，明确 `scan`、`snapshot`、`exec/CDP` 的职责边界。
+
+### 验证
+
+- 已覆盖真实 Chrome 场景：百度搜索、页面扫描、DOM 定位、输入/点击、截图、PDF、network/console 监听、缓存清理、tab group、关闭测试 tab。
+- 已执行 `cargo fmt --check`、`cargo check`、`cargo build`、`cargo test`、`node --check`。
+
+## v0.2.10-extension - 2026-05-15
+
+### 调整
+
+- Chrome 扩展默认不抢占系统前台窗口。
+- `Page.bringToFront` 这类可能聚焦浏览器的行为改为显式 `allowFocus=true` 才执行。
+
+## v0.2.9 - 2026-05-15
+
+### 修复
+
+- 同步平台包版本，保证 npm 包与 Rust crate 版本一致。
+
+## v0.2.8 - 2026-05-15
+
+### 新增
+
+- 支持自定义 Chrome 扩展 WebSocket 监听端口。
+- 新增 `set-extension-port <port>`，写入 `~/.agent-browser-cli/config.json`。
+- daemon 运行中修改端口时自动重启，使新端口立即生效。
+
+## v0.2.7 - 2026-05-15
+
+### 调整
+
+- 发布版本 `0.2.7`。
+- 整合 release/publish 流程，为后续多平台包发布做准备。
+
+## v0.2.6 - 2026-05-15
+
+### 新增
+
+- 支持 Linux ARM64 平台包。
+
+### 文档
+
+- 更新 Chrome 扩展安装说明，推荐从 Release 下载 `chrome-extensions.zip`。
+- 补充 Linux 与 WSL 使用前提。
+
+## v0.2.5 - 2026-05-13
+
+### 调整
+
+- 准备 `0.2.5` 发布。
+- 更新支持平台说明。
+- 改进 Chrome 扩展右侧提示角标，并补充文档说明。
+- 增加 GenericAgent 友情链接。
+
+## v0.2.4 - 2026-05-13
+
+### 调整
+
+- 准备 `0.2.4` 发布。
+- 改进 release notes 保留逻辑。
+- 增加 Linux 构建验证。
+
+## v0.2.3 - 2026-05-12
+
+### 修复
+
+- 修复 Release npm artifact 匹配逻辑，让发布产物查找更稳健。
+- 更新 `Cargo.lock` 到 `0.2.3`。
+
+## v0.2.2 - 2026-05-12
+
+### CI
+
+- npm token 不存在时跳过 npm publish，避免发布流程失败。
+- 增加 npm 发布 GitHub Actions 工作流。
+- 调整 macOS Intel runner。
+
+## v0.2.1 - 2026-05-11
+
+### 移除
+
+- 移除旧 Python runtime，CLI 主链路切换到 Rust 实现。
+
+## v0.2.0 - 2026-05-11
+
+### 新增
+
+- 新增 Rust npm CLI release。
+- 通过 npm 包分发 Rust CLI。
+
+### 文档
+
+- 补充性能参考和延迟数据说明。
+
+## v0.1.1 - 2026-05-11
+
+### 修复
+
+- CLI 关闭时主动关闭 bridge，避免连接残留。
+
+### 文档
+
+- 补充安装指引，强调替换项目路径占位符。
+
+## v0.1.0 - 2026-05-09
+
+### 新增
+
+- 新增 `open 命令。
+- 支持通过 Chrome 扩展原生创建标签页。
+- 建立基础浏览器控制 CLI 能力。

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "agent-browser-cli"
-version = "0.2.9"
+version = "0.3.1-beta.1"
 edition = "2021"
 license = "MIT"
 

Cargo.toml

@@ -10,11 +10,11 @@
   <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/sys-win%2Fmac%2Flinux-0078D6?labelColor=0078D6&color=C0C0C0" alt="sys win/mac/linux"></a>
-  <a href="https://github.com/sleepinginsummer/agent-browser-cli/releases"><img src="https://img.shields.io/badge/release-v0.2.9-blue" alt="release v0.2.9"></a>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli/releases"><img src="https://img.shields.io/badge/release-v0.3.1--beta.1-orange" alt="release v0.3.1-beta.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 一句话安装](#ai-一句话安装) · [手动安装](#手动安装) · [Chrome 扩展](#chrome-扩展) · [更新](#更新) · [卸载](#卸载) · [友情链接](#友情链接)
+[AI 一句话安装](#ai-一句话安装) · [手动安装](#手动安装) · [Chrome 扩展](#chrome-扩展) · [更新](#更新) · [更新日志](CHANGELOG.md) · [卸载](#卸载) · [友情链接](#友情链接)
 
 中文 | [English](README_EN.md)
 
@@ -26,7 +26,7 @@
 
 ## 项目信息
 
-- 当前版本：`0.2.9`
+- 当前版本：`0.3.1-beta.1`
 - 支持平台：Windows（包括 WSL）/ Mac / Linux
 - 浏览器：Chrome，需加载拓展 `assets/tmwd_cdp_bridge`
 - Linux 支持前提：本机 Chrome / Chromium 需要支持安装扩展
@@ -189,6 +189,8 @@ agent-browser-cli tabs
 
 ## 更新
 
+完整版本记录见 [CHANGELOG.md](./CHANGELOG.md)。
+
 ai一句话更新
 ```text
 请阅读 https://github.com/sleepinginsummer/agent-browser-cli/blob/main/AI_INSTALL.md，按说明更新 CLI、重新下载插件zip让用户指定位置，用户手动加载 Chrome 扩展，并更新相关 SKILL.md`。

README.md

@@ -10,11 +10,11 @@ Browser perception · Page control · Chrome session reuse · CDP · Conditional
   <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/sys-win%2Fmac%2Flinux-0078D6?labelColor=0078D6&color=C0C0C0" alt="sys win/mac/linux"></a>
-  <a href="https://github.com/sleepinginsummer/agent-browser-cli/releases"><img src="https://img.shields.io/badge/release-v0.2.9-blue" alt="release v0.2.9"></a>
+  <a href="https://github.com/sleepinginsummer/agent-browser-cli/releases"><img src="https://img.shields.io/badge/release-v0.3.1--beta.1-orange" alt="release v0.3.1-beta.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)
+[AI One-Line Install](#ai-one-line-install) · [Manual Installation](#manual-installation) · [Chrome Extension](#chrome-extension) · [Update](#update) · [Changelog](CHANGELOG.md) · [Uninstall](#uninstall) · [Friendly Links](#friendly-links)
 
 [中文](README.md) | English
 
@@ -26,7 +26,7 @@ This project is not Selenium or Playwright. It is better suited for helping agen
 
 ## Project Info
 
-- Current version: `0.2.9`
+- Current version: `0.3.1-beta.1`
 - Supported platforms: Windows (including WSL) / Mac / Linux
 - Browser: Chrome, with the `assets/tmwd_cdp_bridge` extension loaded
 - Linux prerequisite: the local Chrome / Chromium build must support loading extensions
@@ -187,6 +187,8 @@ agent-browser-cli tabs
 
 ## Update
 
+For the full version history, see [CHANGELOG.md](./CHANGELOG.md).
+
 AI one-line update:
 
 ```text