harness-browser 0.1.1__tar.gz

harness_browser-0.1.1/.codebuddy/skills/pypi-publish/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: publish
+description: 当需要发布 Python 包到 PyPI 时使用 — 创建 release 分支、升版本号、更新 CHANGELOG、发布到 PyPI、打 tag、并创建合并请求到 main
+---
+
+# Publish
+
+自动化 Python 包的完整发布流程。
+
+**开始时宣告：** "正在使用 publish 技能发布版本 {VERSION}。"
+
+## 配置项
+
+以下配置有默认值，可在项目的 `.codebuddy/skills/publish/SKILL.md` 中覆盖。
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `PUBLISH_CMD` | 自动检测（见步骤 5） | 发布到 PyPI 的命令 |
+| `CHANGELOG_FILE` | `CHANGELOG.md` | 相对于仓库根目录的路径，文件不存在则跳过 |
+| `VERSION_FILE` | `pyproject.toml` | 包含版本号的文件 |
+| `VERSION_PATTERN` | `^\s*version\s*=\s*"[^"]+"` | 匹配版本行的正则表达式 |
+| `TAG_PREFIX` | ``（空） | Git tag 前缀，设为 `v` 则生成 `v0.1.14` 风格标签 |
+| `REMOTE` | `origin` | Git 远程仓库名 |
+| `TARGET_BRANCH` | `main` | 合并请求的目标分支 |
+| `RELEASE_BRANCH_PREFIX` | `release/` | release 分支名前缀 |
+
+## 调用方式
+
+```
+/publish 0.1.14
+```
+
+目标版本号是唯一必填参数，其余均从配置或自动检测获取。
+
+## 发布流程
+
+### 步骤 1 — 读取配置并确认版本
+
+1. 获取仓库根目录：`git rev-parse --show-toplevel`
+2. 从 `VERSION_FILE` 读取当前版本：
+   ```bash
+   grep -E '^\s*version\s*=\s*"[^"]+"' pyproject.toml
+   ```
+3. 检查未提交的更改：
+   ```bash
+   git status --short
+   ```
+   如果存在未提交的更改，它们将被包含在步骤 4 的发布提交中。这是有意为之 — 所有待处理的工作随版本一起发布。
+4. 查找最近的 git tag：
+   ```bash
+   git tag --sort=-creatordate | head -1
+   ```
+   如果没有 tag，视为首次发布（在步骤 3 中使用从仓库初始到 HEAD 的所有提交）。
+5. 展示确认信息：
+
+```
+当前版本 (pyproject.toml): X.Y.Z
+目标版本:                   A.B.C
+上次发布 tag:               X.Y.Z (YYYY-MM-DD)
+Release 分支:               release/A.B.C
+目标分支 (MR):              main
+
+确认发布 X.Y.Z → A.B.C？[y/N]
+```
+
+如果用户未输入 `y` 确认，立即中止。
+
+### 步骤 2 — 创建 release 分支
+
+从当前 HEAD 创建并切换到新的 release 分支：
+
+```bash
+git checkout -b {RELEASE_BRANCH_PREFIX}{version}
+```
+
+如果分支已存在，中止：
+```
+✗ 分支 {RELEASE_BRANCH_PREFIX}{version} 已存在。
+请手动删除：git branch -D {RELEASE_BRANCH_PREFIX}{version}
+然后重新运行 /publish。
+```
+
+### 步骤 3 — 分析变更并生成 CHANGELOG 草稿
+
+1. 获取上次 tag 以来的提交：
+   ```bash
+   git log {last_tag}..HEAD --oneline
+   # 首次发布时：
+   git log --oneline
+   ```
+
+2. 如果没有找到提交：
+   ```
+   ⚠ 自上次发布 tag ({last_tag}) 以来没有新提交。
+   是否继续？[y/N]
+   ```
+   用户未确认则中止。
+
+3. 按提交前缀分类，生成 Keep a Changelog 格式的条目。
+
+   **CHANGELOG 内容必须用中文书写。** 将每个提交总结为简洁的中文要点 — 不要逐字翻译提交信息。适当合并相关提交。
+
+   分类规则：
+   - 以 `feat:` 或 `feat(` 开头 → **新增**
+   - 以 `fix:` 或 `fix(` 开头 → **修复**
+   - 以 `refactor:` 或 `perf:` 开头 → **变更**
+   - 包含 `!:` 或提交正文含 `BREAKING CHANGE:` → **变更**，加 `**Breaking:**` 前缀
+   - 以 `docs:` 开头 → **变更**
+   - 以 `chore:`、`test:`、`ci:` 开头 → 忽略（基础设施噪音）
+   - 其他所有提交 → **变更**
+   - 移除的功能 → **移除**
+   - 安全修复 → **安全**
+
+   输出格式：
+   ```markdown
+   ## [A.B.C] - YYYY-MM-DD
+
+   ### 新增
+   - 中文描述新增功能
+
+   ### 修复
+   - 中文描述修复内容
+
+   ### 变更
+   - 中文描述行为变更
+
+   ### 移除
+   - 中文描述移除内容
+
+   ### 安全
+   - 中文描述安全修复
+   ```
+   省略空的分类。日期使用 ISO 8601 格式（当天日期）。日期行与第一个分类之间、各分类之间保留空行。
+
+4. 向用户展示草稿并请求确认：
+   ```
+   CHANGELOG 草稿：
+
+   {draft}
+
+   添加到 CHANGELOG.md？[y/N/edit]
+   ```
+   - `y` → 继续
+   - `n` → 中止
+   - `edit` 或其他反馈 → 询问用户："需要什么修改？" — 等待回复后重新生成，再次展示确认。循环直到 `y` 或 `n`。
+
+5. 如果 `CHANGELOG_FILE` 不存在，跳过此步骤（无需警告）。
+
+### 步骤 4 — 更新文件、提交并推送 release 分支
+
+按顺序执行：
+
+**4a. 更新 CHANGELOG：**
+
+在 `CHANGELOG_FILE` 中找到 `## [Unreleased]` 标题，在其后插入新版本条目（保持 `[Unreleased]` 为空）：
+
+```markdown
+## [Unreleased]
+
+## [A.B.C] - YYYY-MM-DD
+### 新增
+- ...
+```
+
+如果 `## [Unreleased]` 标题不存在，在 `# Changelog` 标题行之后插入新条目（若无标题则插入到文件顶部）。
+
+**4b. 升级 VERSION_FILE 中的版本号：**
+
+替换 `VERSION_PATTERN` 匹配到的版本行。对于 `pyproject.toml`：
+```bash
+# 查找当前行：
+grep -n '^\s*version\s*=\s*"[^"]+"' pyproject.toml
+# 用 Edit 工具将该行的 "X.Y.Z" 替换为 "A.B.C"
+```
+
+**4c. 提交：**
+
+检查工作树状态：
+```bash
+git status --short
+```
+
+- 如果有更改（已暂存或未暂存）：暂存所有文件并提交：
+  ```bash
+  git add -A
+  git commit -m "chore: release {version}"
+  ```
+- 如果工作树已干净：无需提交，跳过。
+
+**4d. 推送 release 分支：**
+```bash
+git push -u {REMOTE} {RELEASE_BRANCH_PREFIX}{version}
+```
+
+推送失败则中止。
+
+### 步骤 5 — 发布到 PyPI
+
+**自动检测 PUBLISH_CMD**（仅在配置未覆盖时）：
+
+```bash
+# 检查 Makefile 是否有 publish 目标
+grep -q '^\s*publish\s*:' Makefile 2>/dev/null && echo "make publish" || echo "python -m build && python -m twine upload dist/*"
+```
+
+- 如果 `make publish` 目标存在 → `PUBLISH_CMD=make publish`
+- 否则 → `PUBLISH_CMD=python -m build && python -m twine upload dist/*`
+- 如果 `python -m build` 或 `python -m twine` 未安装，中止："缺少构建工具。请安装：`pip install build twine`"
+
+执行：
+```bash
+{PUBLISH_CMD}
+```
+
+实时输出。如果退出码非零：
+
+```
+✗ 发布失败（退出码 N）。已停止 — 不会创建 tag。
+请检查上方输出，解决问题后重新运行 /publish。
+```
+
+**不继续执行步骤 6。**
+
+### 步骤 6 — 打 tag 并推送
+
+```bash
+git tag {TAG_PREFIX}{version}
+git push {REMOTE} {TAG_PREFIX}{version}
+```
+
+如果 `git tag` 因 tag 已存在而失败：
+```
+✗ Tag {TAG_PREFIX}{version} 已存在。
+请手动删除：git tag -d {TAG_PREFIX}{version}
+然后重新运行 /publish 从此步骤重试。
+```
+中止。
+
+### 步骤 7 — 创建合并请求
+
+使用工丰 MCP 工具从 release 分支创建到 `TARGET_BRANCH` 的合并请求：
+
+1. 从 git remote 检测项目路径：
+   ```bash
+   git remote get-url {REMOTE} | sed -E 's|.*[:/](.+/.+)\.git$|\1|'
+   ```
+
+2. 使用 `mcp__gongfeng__create_merge_request` 创建 MR：
+   - `project_id`：项目完整路径（如 `orcakit/finnie`）
+   - `title`：`chore: release {version}`
+   - `source_branch`：`{RELEASE_BRANCH_PREFIX}{version}`
+   - `target_branch`：`{TARGET_BRANCH}`
+   - `description`：步骤 3 生成的 CHANGELOG 条目
+
+3. 成功时展示：
+   ```
+   ✓ 已发布 {package_name} {version} 到 PyPI
+   ✓ 已创建并推送 tag {TAG_PREFIX}{version} 到 {REMOTE}
+   ✓ 已创建合并请求：{RELEASE_BRANCH_PREFIX}{version} → {TARGET_BRANCH}
+     链接：{mr_url}
+   ```
+
+4. MR 创建失败时展示警告（非致命 — 发布已成功）：
+   ```
+   ⚠ 发布成功，但合并请求创建失败。
+   请手动创建：{RELEASE_BRANCH_PREFIX}{version} → {TARGET_BRANCH}
+   ```
+
+### 步骤 8 — 切回原分支
+
+返回创建 release 分支之前所在的分支：
+
+```bash
+git checkout {original_branch}
+```
+
+确保流程结束后用户不会停留在 release 分支上。
+
+## 错误处理参考
+
+| 场景 | 行为 |
+|------|------|
+| `VERSION_FILE` 未找到 | 中止："找不到 VERSION_FILE：{path}" |
+| 文件中未匹配到版本号 | 中止："在 {VERSION_FILE} 中找不到匹配 {VERSION_PATTERN} 的版本行" |
+| 没有 git tag（首次发布） | 使用从仓库初始到 HEAD 的所有提交；提示"首次发布 — 使用完整 git 历史" |
+| 上次 tag 以来无提交 | 警告并询问是否继续 |
+| Release 分支已存在 | 中止并给出删除指令 |
+| 步骤 4 推送失败 | 中止：文件已在本地更新但未推送 |
+| 步骤 5 发布失败 | 中止：不创建 tag、不创建 MR |
+| 步骤 6 tag 已存在 | 中止并给出删除指令 |
+| 步骤 7 MR 创建失败 | 仅警告（发布已成功） |
+
+## 红线规则
+
+**绝不：**
+- 在发布成功前创建 tag
+- 在发布成功前创建合并请求
+- 跳过步骤 1 的用户确认
+- 跳过步骤 3 的 CHANGELOG 确认
+- 在任何步骤失败后继续执行（步骤 7 MR 失败除外）
+- 流程结束后让用户留在 release 分支
+
+**始终：**
+- 任何失败立即中止（步骤 7 除外）
+- 中止前展示完整错误输出
+- 插入新版本条目后保持 `[Unreleased]` 为空
+- 流程结束时切回原分支

harness_browser-0.1.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug Report
+about: Report a bug
+labels: bug
+---
+
+## Description
+
+## Steps to Reproduce
+
+1.
+2.
+
+## Expected Behavior
+
+## Actual Behavior
+
+## Environment
+
+- OS:
+- Python version:
+- harness-browser version:
+- Chrome version:

harness_browser-0.1.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature Request
+about: Suggest a feature
+labels: enhancement
+---
+
+## Problem
+
+## Proposed Solution
+
+## Alternatives Considered

harness_browser-0.1.1/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5

harness_browser-0.1.1/.github/pull_request_template.md

@@ -0,0 +1,9 @@
+## Summary
+
+## Checklist
+
+- [ ] Tests added or updated
+- [ ] CHANGELOG.md updated under [Unreleased]
+- [ ] No breaking changes (or documented)
+- [ ] `make lint` passes
+- [ ] `make test` passes

harness_browser-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run mypy src/
+      - name: Install Chrome
+        run: sudo apt-get install -y chromium-browser
+      - run: uv run pytest tests/ -v --cov=harness_browser --cov-report=xml
+      - uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml

harness_browser-0.1.1/.github/workflows/codeql.yml

@@ -0,0 +1,20 @@
+name: CodeQL
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 3 * * 1"
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: python
+      - uses: github/codeql-action/autobuild@v3
+      - uses: github/codeql-action/analyze@v3

harness_browser-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: Release
+on:
+  push:
+    tags:
+      - "v*.*.*"
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

harness_browser-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

harness_browser-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.9.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic, websockets, aiohttp]

harness_browser-0.1.1/.python-version

@@ -0,0 +1 @@
+3.11

harness_browser-0.1.1/AGENTS.md

@@ -0,0 +1,122 @@
+# CODEBUDDY.md
+
+This file provides guidance to CodeBuddy Code when working with code in this repository.
+
+## Commands
+
+All targets run through `uv` and the Makefile:
+
+```bash
+make test      # full suite with coverage (uv run pytest tests/ -v --cov=harness_browser)
+make lint      # ruff check + mypy strict on src/
+make format    # ruff format src/ tests/
+make build     # uv build → wheel + sdist
+make mcp       # launch the MCP stdio server (python -m harness_browser.mcp_server)
+make publish   # uv publish (PyPI release)
+make clean     # remove dist/, .coverage, .mypy_cache/, .ruff_cache/
+```
+
+Useful narrower invocations:
+
+```bash
+# Unit tests only — no Chrome required
+uv run pytest tests/unit/ -q
+
+# A single test file or test
+uv run pytest tests/unit/test_mode.py -q
+uv run pytest tests/unit/test_settings.py::test_env_override_browser_mode -q
+
+# Integration tests — auto-skipped when Chrome/Chromium is not on the host
+uv run pytest tests/integration/ -v
+
+# Type-check or lint just one path
+uv run mypy src/harness_browser/session.py
+uv run ruff check src/harness_browser/cdp/
+
+# Install dev extras
+uv sync --extra dev
+pre-commit install
+```
+
+`pytest-asyncio` runs in `asyncio_mode = "auto"` (set in `pyproject.toml`) — async test functions need no decorator. `tests/integration/conftest.py` skips the whole integration suite when `find_chrome()` returns None, so unit work on machines without Chrome stays green.
+
+## Architecture
+
+This package wraps Chrome over **pure CDP** (WebSocket, no Playwright) and exposes it three ways: an async Python API, a stateless `browser_tool()` for AI frameworks, and an MCP server. Understanding the call chain matters when changing anything in the launch / connect / DOM path.
+
+### Layered call chain
+
+```
+browser_tool()  ──► BrowserSession ──► _InternalCDPSession ──► CDPClient (websockets) ──► Chrome
+mcp_server.py   ──┘                          │
+                                             └─► launcher.launch_or_attach + get_page_ws_url
+```
+
+- `tool_interface.browser_tool(action, profile=..., mode=...)` — stateless dispatch keyed by `profile`. Maintains a `_registry: dict[str, BrowserSession]`; first call per profile creates a session, subsequent calls reuse it. Action names map directly to `BrowserSession` methods via `getattr`.
+- `session.BrowserSession` — public async API. Mixes in `HooksMixin` (events: `before_action`, `after_action`, `action_error`, `page_navigated`) and accumulates running totals in `metrics_summary()`.
+- `session._InternalCDPSession` — owns one `CDPClient` + one `RefCache` per page. Honors `cfg.cdp_ws_url`: if set, **bypasses the launcher entirely** and connects directly to the given WebSocket (used for remote/Docker Chrome).
+- `cdp.client.CDPClient` — minimal CDP framing over `websockets.asyncio.client`. `send(method, params)` returns the result; `enable_domain()` enables `Page` / `DOM` / `Runtime` / `Input` after connect.
+- `cdp.launcher` — `find_chrome()`, `launch_or_attach()` (re-attach if port is already serving CDP), `_get_ws_url()` polls `http://{cdp_host}:{port}/json/version`, `get_page_ws_url()` picks the first `type==page` target. All HTTP probes go through `aiohttp` and **always read `cdp_host` from settings** — never hardcode `localhost`.
+
+### Configuration: HarnessSettings (single source of truth)
+
+`settings.HarnessSettings` is a `dataclass` whose every field uses `field(default_factory=lambda: _env_*(...))`. This means **each instantiation re-reads env vars**, which is what `monkeypatch.setenv` in tests relies on. The module-level `settings` singleton (read at import time) is the default everywhere; tests should construct a fresh `HarnessSettings()` rather than mutating it.
+
+Env vars (all optional):
+
+| Variable | Default | Used in |
+|---|---|---|
+| `BROWSER_USE_PROFILES_DIR` | `~/.harness-browser/profiles` | `ProfileManager.__init__` |
+| `BROWSER_USE_CDP_HOST` | `localhost` | `launcher._get_ws_url`, `_port_in_use`, `get_page_ws_url`, `session.list_tabs`; also drives `--remote-debugging-address` when non-loopback |
+| `BROWSER_USE_CDP_PORT_START` | `9222` | `ProfileManager` port assignment |
+| `BROWSER_USE_MODE` | `auto` | resolved via `mode.resolve_headless()` |
+| `BROWSER_USE_CHROME_BIN` | auto-detect | `launcher.find_chrome` (checked before path search) |
+| `BROWSER_USE_CDP_TIMEOUT` | `30.0` | `CDPClient` send timeout |
+| `BROWSER_USE_LAUNCH_RETRIES` / `BROWSER_USE_LAUNCH_DELAY` | `20` / `0.25` | launcher polling |
+| `BROWSER_USE_CDP_WS_URL` | — | `_InternalCDPSession.connect` direct-connect path |
+
+The MCP server has no per-tool `inputSchema` field for these — they are passed via the standard `mcpServers.<name>.env` block in client config. Do not add them to the tool schema.
+
+### Browser mode resolution (harness_browser/mode.py)
+
+Three modes — `auto` / `headed` / `headless`. Resolution priority in `BrowserSession.create()`:
+
+1. Explicit `headless=True/False` argument (legacy escape hatch, wins outright)
+2. Explicit `mode=` argument
+3. `cfg.browser_mode` (from `HarnessSettings`, which reads `BROWSER_USE_MODE`)
+
+`auto` calls `has_desktop_environment()`: True on macOS/Windows always; on Linux requires `$DISPLAY` or `$WAYLAND_DISPLAY`. The result is fed to `resolve_headless()`. `_build_flags` only appends `--headless=new` when the resolved bool is True.
+
+### DOM output: 4 levels and the ref system
+
+- `dom.builder.DOMBuilder` produces `minimal` (~50 tok) / `interactive` (~200–500 tok) / `full` (~1000–3000 tok) / `structured` (JSON) views from a CDP `DOM.getDocument` snapshot.
+- `dom.refs.RefCache` issues stable refs like `btn_2`, `inp_search` mapping `ref → CDP nodeId`. **Refs are invalidated on navigation** — `nav_actions.navigate` / `go_back` / `go_forward` / `reload` clear the cache. Any new navigation-class action MUST do the same or you'll hand the agent stale node IDs.
+- Token estimate is `len(content) // 4` — keep this when adding new actions that build text content.
+
+### Profiles and login persistence
+
+`profile.ProfileManager` allocates one `Chrome --user-data-dir` per profile name under `cfg.profiles_dir`, with `cdp_port = cfg.cdp_port_start + index`. This is the entire login-persistence story: same profile name → same data dir → cookies and storage reused. Don't add ad-hoc paths for cookies/auth — go through `Profile`.
+
+### Hooks and metrics
+
+`HooksMixin` is what `BrowserSession` mixes in. Every action goes:
+
+```
+_fire("before_action", {...}) → action body → _record(result)
+                                                  └─► _fire("after_action", metrics)  (or "action_error")
+```
+
+`ActionMetrics` (`models.py`) carries `duration_ms`, `dom_nodes_scanned`, `estimated_tokens`, `screenshot_size_kb`. `BrowserSession.metrics_summary()` aggregates totals across the session.
+
+### Skill files (Claude Code / agent-facing)
+
+Live at `.codebuddy/skills/harness-browser/SKILL.md` (English) and `.codebuddy/skills/harness-browser-zh/SKILL.md` (Chinese). They use the standard YAML-frontmatter format (`name`, `description`, `allowed-tools`) and are designed to be `cp -r`'d into other agent projects. Keep these in sync when the public surface (env vars, modes, action list) changes.
+
+## Project conventions
+
+- **Docs language**: README is bilingual (`README.md` canonical English + `README.zh.md`); `CHANGELOG.md` and `CONTRIBUTING.md` are Chinese-only by deliberate choice.
+- **ruff**: `line-length = 88`, lint selects `E F I N W`. Do not raise the line length to dodge wraps.
+- **mypy**: `strict = true`, `python_version = "3.11"`. New code must type-check under strict mode; reach for `from __future__ import annotations` (already used everywhere) before adding `# type: ignore`.
+- **No Playwright, no Selenium**: the dependency story is just `websockets`, `aiohttp`, `pydantic`, `mcp`. Don't add browser drivers.
+- **`localhost` is never hardcoded** — always go through `cfg.cdp_host`. A dedicated regression hazard if you forget.
+- **Repository URL** in docs is `https://git.woa.com/orcakit/browser-use.git`. PyPI badges still point at `github.com/harness/...` (publishing target).