diff --git a/browser-harness-guide.md b/browser-harness-guide.md
new file mode 100644
index 0000000..39e979e
--- /dev/null
+++ b/browser-harness-guide.md
@@ -0,0 +1,511 @@
+# Browser Harness 使用指南：连接 AI 与真实浏览器
+
+> 官方仓库：[browser-use/browser-harness](https://github.com/browser-use/browser-harness)
+>
+> 组织：Browser Use
+>
+> 设计哲学：最薄、最小、最强的 Agent 浏览器控制层
+
+---
+
+## 一、项目背景
+
+Browser Harness 是一个极薄的 CDP（Chrome DevTools Protocol）桥接层，让 AI 编程助手（Claude Code、Codex、Hermes Agent 等）**直接操控你的真实浏览器**。它不做任何高层抽象 — 就是一条 WebSocket 连到 Chrome，中间什么都没有。
+
+核心理念来自 [The Bitter Lesson of Agent Harnesses](https://browser-use.com/posts/bitter-lesson-agent-harnesses)：
+
+> "Agent 需要的不是一个全功能的浏览器自动化框架，而是一根足够细的管道 — 能传递点击和截图就够了。"
+
+### 与传统工具的区别
+
+| 特性 | Browser Harness | Playwright / Puppeteer | Selenium |
+|------|-----------------|------------------------|----------|
+| 代码量 | ~1000 行（4 个文件） | 数十万行 | 数十万行 |
+| 浏览器 | 连接你的真实 Chrome | 启动独立浏览器 | 启动独立浏览器 |
+| 登录态 | 直接用你的 Cookie / Session | 需要手动注入或重新登录 | 需要手动注入或重新登录 |
+| 扩展/书签 | 全部可用 | 无 | 无 |
+| AI Agent 编辑 | Agent 可直接改 helper 代码 | 不能 | 不能 |
+| 跨 iframe / Shadow DOM | 坐标点击天然穿透 | 需要切换 context | 需要切换 context |
+
+### 架构（~1000 行代码）
+
+```
+Chrome / Browser Use Cloud → CDP WebSocket → daemon（长驻进程）→ IPC → browser-harness CLI
+```
+
+四个核心文件：
+
+| 文件 | 作用 |
+|------|------|
+| `run.py` | CLI 入口，负责解析命令、启动 daemon、执行 Python 片段 |
+| `daemon.py` | 长驻中间层进程，管理 CDP 连接生命周期 |
+| `helpers.py` | CDP 封装 + 核心浏览器原语（截图、点击、导航、JS 执行） |
+| `admin.py` | daemon 生命周期管理、诊断、更新、云浏览器管理 |
+
+Agent 只能编辑 `agent-workspace/` 下的内容：
+- `agent_helpers.py` — 任务特定的辅助函数
+- `domain-skills/` — 可复用的站点技能（社区贡献）
+
+---
+
+## 二、安装
+
+### 前置要求
+
+- Python >= 3.11
+- `uv`（推荐，Python 包管理器）或 `pip`
+- Chrome / Chromium 浏览器
+- Git
+
+### 推荐安装方式（uv tool，全局可用）
+
+```bash
+# 1. 克隆到持久目录（推荐 ~/Developer/，不要放 /tmp）
+git clone https://github.com/browser-use/browser-harness
+cd browser-harness
+
+# 2. 用 uv tool 安装为可编辑的全局命令
+uv tool install -e .
+
+# 3. 验证
+command -v browser-harness
+# 输出: /home/user/.local/bin/browser-harness
+```
+
+> **为什么用 `-e`（editable）？** Agent 在运行时会往 `agent-workspace/agent_helpers.py` 中写自定义 helper，editable 安装保证下次调用 `browser-harness` 立即使用新代码，无需重新安装。
+
+### 备选安装方式（pip）
+
+```bash
+git clone https://github.com/browser-use/browser-harness
+cd browser-harness
+pip install -e .
+```
+
+### 平台支持
+
+| 平台 | 状态 | 备注 |
+|------|------|------|
+| Linux | ✅ 完全支持 | Socket: `/tmp/bu-<NAME>.sock` |
+| macOS | ✅ 完全支持 | Socket: `/tmp/bu-<NAME>.sock` |
+| Windows | ✅ 支持 | IPC 使用 TCP loopback + port file |
+
+### 各平台安装注意事项
+
+**macOS**：
+```bash
+# Chrome 路径
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
+# 一键打开 chrome://inspect 页面
+osascript -e 'tell application "Google Chrome" to activate' \
+          -e 'tell application "Google Chrome" to open location "chrome://inspect/#remote-debugging"'
+```
+
+**Windows**：
+```bash
+# Chrome 路径
+"C:\Program Files\Google\Chrome\Application\chrome.exe"
+# 安装后确保 %USERPROFILE%\.local\bin 在 PATH 中
+```
+
+**Linux**：
+```bash
+# Chrome 通常已通过包管理器安装
+google-chrome
+# 非标准安装路径
+/usr/bin/google-chrome
+/opt/google/chrome/chrome
+```
+
+### 注册为 Agent 的全局 Skill（可选）
+
+安装后，让 AI Agent 在任何项目中都能使用 Browser Harness：
+
+**Claude Code** — 在 `~/.claude/CLAUDE.md` 中添加：
+
+```markdown
+@~/Developer/browser-harness/SKILL.md
+```
+
+**Codex** — 创建符号链接：
+
+```bash
+mkdir -p ~/.codex/skills/browser-harness
+ln -sf ~/Developer/browser-harness/SKILL.md ~/.codex/skills/browser-harness/SKILL.md
+```
+
+---
+
+## 三、浏览器连接
+
+Browser Harness 连接浏览器有两种方式：
+
+### Way 1：chrome://inspect 复选框（推荐日常使用）
+
+**连接到你的真实 Chrome，继承所有登录态、扩展、书签。**
+
+1. 在 Chrome 地址栏输入 `chrome://inspect/#remote-debugging`
+2. 勾选 "Allow remote debugging for this browser instance"
+3. 此设置是**每个 Profile 一次性的**，勾选后该 Profile 的每次启动都默认开启
+
+Chrome 144+ 首次连接时会弹出 "Allow remote debugging?" 确认框，点击 Allow 即可。
+
+**优点**：直接用你的真实浏览器，Cookie、Session、扩展全部生效。
+**缺点**：偶尔需要手动点击 Allow 弹窗。
+
+### Way 2：命令行启动（推荐自动化/无头场景）
+
+**启动独立的 Chrome 实例，无弹窗，适合无人值守。**
+
+```bash
+# Linux / macOS
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-bh
+
+# macOS（完整路径）
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-bh
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
+  --remote-debugging-port=9222 ^
+  --user-data-dir=%TEMP%\chrome-bh
+```
+
+> **重要**：`--user-data-dir` 必须指向**非默认 Profile 目录**。指向默认目录（如 `~/.config/google-chrome`）时，Chrome 136+ 会**静默忽略** `--remote-debugging-port` 参数。
+
+告诉 Harness 连接哪个端口：
+
+```bash
+# 环境变量方式
+export BU_CDP_URL=http://127.0.0.1:9222
+browser-harness <<'PY'
+print(page_info())
+PY
+
+# 或者内联
+BU_CDP_URL=http://127.0.0.1:9222 browser-harness <<'PY'
+print(page_info())
+PY
+```
+
+### Headless 模式（E10 等企业系统自动化专用）
+
+启动独立 headless Chrome：
+
+```bash
+google-chrome --headless=new \
+  --remote-debugging-port=9223 \
+  --user-data-dir=/tmp/bh-e10 \
+  --no-first-run --no-default-browser-check \
+  --window-size=1920,1080
+```
+
+然后所有 browser-harness 命令加上端口前缀：
+
+```bash
+export BU_CDP_URL=http://127.0.0.1:9223 && browser-harness <<'PY'
+new_tab("https://example.com/login")
+wait_for_load()
+PY
+```
+
+> ⚠️ **关键**：`export` 和 `browser-harness` 必须在**同一行**。daemon 是独立进程，不会继承后续 shell 的环境变量。
+
+---
+
+## 四、基本使用
+
+### 第一个命令
+
+```bash
+browser-harness <<'PY'
+print(page_info())
+PY
+```
+
+输出当前标签页的 URL 和标题。
+
+### 导航
+
+```bash
+browser-harness <<'PY'
+# 打开新标签页（首选方式，不会覆盖用户当前标签）
+new_tab("https://github.com")
+wait_for_load()
+
+# 获取页面信息
+print(page_info())
+PY
+```
+
+> **new_tab() vs goto_url()**：第一次导航总是用 `new_tab()`。`goto_url()` 会在用户当前活跃标签页中导航，可能覆盖用户正在看的内容。
+
+### 截图（最核心的反馈方式）
+
+```bash
+browser-harness <<'PY'
+capture_screenshot("/tmp/page.png")
+PY
+```
+
+截图是验证操作结果的首选方式 — 比 DOM 检查更快、更直观。
+
+### 坐标点击（穿透 iframe / Shadow DOM）
+
+```bash
+browser-harness <<'PY'
+# 用截图找到目标坐标后直接点击
+click_at_xy(500, 300)
+wait_for_load()
+capture_screenshot("/tmp/after_click.png")
+PY
+```
+
+坐标点击经由 Chrome 浏览器的合成器层（compositor level）派发 `Input.dispatchMouseEvent`，天然穿透 iframe、Shadow DOM 和跨域边界。**不需要切换 context。**
+
+> **工作流**：`capture_screenshot()` → 看图找坐标 → `click_at_xy(x, y)` → `capture_screenshot()` 验证。这是 Browser Harness 推荐的操作模式，而非 Playwright 风格的 "先定位再点击"。
+
+### JS 执行（DOM 读取和复杂逻辑）
+
+```bash
+browser-harness <<'PY'
+# 读取页面内容
+content = js("document.body.innerText")
+print(content[:500])
+
+# 提取结构化数据
+import json
+links = json.loads(js('''
+var all = document.querySelectorAll("a");
+var result = [];
+for (var i = 0; i < all.length; i++) {
+    if (all[i].href) result.push({text: all[i].textContent.trim(), href: all[i].href});
+}
+return JSON.stringify(result);
+'''))
+for l in links:
+    print(l["text"], "->", l["href"])
+PY
+```
+
+### 表单填充（native setter 方式）
+
+React/Vue 等框架的受控组件不接受直接的 `.value = "..."` 赋值。需要使用原生 setter + 事件派发：
+
+```bash
+browser-harness <<'PY'
+# 注入通用 fillInput 函数
+js('''
+var ns = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value").set;
+window.__fi = function(selector, value) {
+    var el = document.querySelector(selector);
+    el.focus();
+    ns.call(el, value);
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+    el.dispatchEvent(new Event("change", { bubbles: true }));
+    el.dispatchEvent(new Event("blur", { bubbles: true }));
+};
+''')
+
+js('window.__fi("#username", "myuser")')
+js('window.__fi("#password", "mypass")')
+PY
+```
+
+### 原始 CDP 调用
+
+需要 helpers.py 没有封装的功能时，直接调 CDP 协议：
+
+```bash
+browser-harness <<'PY'
+# 清空浏览器缓存
+cdp("Network.clearBrowserCache")
+# 设置 Cookie
+cdp("Network.setCookie", {"name": "token", "value": "abc123", "domain": "example.com"})
+PY
+```
+
+---
+
+## 五、核心 Helpers 速查
+
+浏览器启动时自动导入的 helpers：
+
+| Helper | 功能 |
+|--------|------|
+| `new_tab(url)` | 打开新标签页并导航 |
+| `goto_url(url)` | 在当前标签页导航（谨慎使用） |
+| `wait_for_load()` | 等待页面加载完成 |
+| `capture_screenshot(path)` | 截图保存为 PNG（**需要传 path 参数**） |
+| `click_at_xy(x, y)` | 坐标点击（穿透所有层级） |
+| `js(code)` | 在页面中执行 JavaScript 并返回结果 |
+| `page_info()` | 返回当前 URL 和标题 |
+| `switch_tab(target)` | 切换到指定标签页 |
+| `cdp(method, params)` | 直接调用 CDP 协议方法 |
+| `http_get(url)` | 并发 HTTP GET（适合批量请求静态页面） |
+| `ensure_real_tab()` | 确保当前连接的是真实标签页（排除 Chrome 内部页） |
+
+---
+
+## 六、Interaction Skills（交互技能）
+
+`interaction-skills/` 目录下包含可复用的交互模式文档：
+
+| 技能 | 内容 |
+|------|------|
+| `screenshots.md` | 截图策略 |
+| `tabs.md` | 标签页管理 |
+| `dialogs.md` | 弹窗处理（alert/confirm/prompt） |
+| `dropdowns.md` | 下拉框交互 |
+| `iframes.md` | iframe 内操作 |
+| `cross-origin-iframes.md` | 跨域 iframe 处理 |
+| `shadow-dom.md` | Shadow DOM 穿透 |
+| `uploads.md` | 文件上传 |
+| `downloads.md` | 文件下载 |
+| `drag-and-drop.md` | 拖拽操作 |
+| `scrolling.md` | 页面滚动 |
+| `cookies.md` | Cookie 管理 |
+| `network-requests.md` | 网络请求拦截 |
+| `print-as-pdf.md` | 网页转 PDF |
+| `viewport.md` | 视口调整 |
+
+---
+
+## 七、Cloud 浏览器（Browser Use Cloud）
+
+Browser Use 提供免费云浏览器（3 个并发浏览器，无需绑卡）：
+
+```bash
+# 设置 API Key
+export BROWSER_USE_API_KEY="your-key"
+
+# 启动远程 daemon
+browser-harness <<'PY'
+start_remote_daemon("work")
+PY
+
+# 使用
+BU_NAME=work browser-harness <<'PY'
+new_tab("https://example.com")
+print(page_info())
+PY
+```
+
+**云浏览器特性**：
+- Stealth 模式（绕过反爬检测）
+- 代理支持（`proxyCountryCode="de"`）
+- Profile 持久化（`profileName="my-work"` — 登录态保持）
+- 本地 Profile 同步（`sync_local_profile("MyChromeProfile")` 上传 Cookie）
+
+---
+
+## 八、Agent 自进化：写好 Helper，下次直接用
+
+Browser Harness 的设计允许 Agent 在执行过程中**自我改进**。当遇到 `helpers.py` 没有的功能时：
+
+```python
+# 在 agent-workspace/agent_helpers.py 中添加
+def fill_form_selectors(fields: dict):
+    """填表：fields = {'#username': 'john', '#password': '***'}"""
+    ns = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value").set
+    for selector, value in fields.items():
+        el = document.querySelector(selector)
+        el.focus()
+        ns.call(el, value)
+        el.dispatchEvent(new Event("input", {"bubbles": true}))
+```
+
+下次调用 `browser-harness` 时（因为是 `-e` editable 安装），新 helper 自动可用。
+
+---
+
+## 九、日常维护
+
+```bash
+# 诊断当前状态
+browser-harness --doctor
+
+# 更新到最新版（每天检查一次，有更新时自动提示）
+browser-harness --update -y
+
+# 重启 daemon
+browser-harness <<'PY'
+restart_daemon()
+PY
+```
+
+---
+
+## 十、故障排查
+
+### Daemon 不响应
+
+```bash
+# 清理残留的 daemon
+pkill -f browser_harness.daemon
+rm -f /tmp/bu-*.sock /tmp/bu-*.pid
+
+# 重新启动
+browser-harness <<'PY'
+restart_daemon()
+PY
+```
+
+### Chrome 远程调试未开启
+
+```bash
+browser-harness --doctor
+# 看 "chrome running" 和 "daemon alive" 两行
+```
+
+- **chrome FAIL**：Chrome 没运行。Way 1 让用户打开 Chrome；Way 2 自己启动。
+- **chrome ok, daemon FAIL**：Chrome 运行了但远程调试没开。去 `chrome://inspect/#remote-debugging` 勾选复选框。
+
+### macOS：一键打开 chrome://inspect
+
+```bash
+osascript -e 'tell application "Google Chrome" to activate' \
+          -e 'tell application "Google Chrome" to open location "chrome://inspect/#remote-debugging"'
+```
+
+### Windows：环境变量设置
+
+```powershell
+# PowerShell
+$env:BU_CDP_URL = "http://127.0.0.1:9222"
+
+# CMD
+set BU_CDP_URL=http://127.0.0.1:9222
+```
+
+### 环境变量陷阱
+
+`export BU_CDP_URL=...` 然后下一行 `browser-harness` **不会生效**。daemon 是独立进程，不继承后续 shell 环境变量。必须：
+
+```bash
+# ✓ 正确
+export BU_CDP_URL=http://127.0.0.1:9222 && browser-harness <<'PY'
+...
+PY
+
+# ✗ 错误
+export BU_CDP_URL=http://127.0.0.1:9222
+browser-harness <<'PY'   # daemon 拿不到 BU_CDP_URL
+...
+PY
+```
+
+---
+
+## 十一、相关资源
+
+- 官方仓库：[github.com/browser-use/browser-harness](https://github.com/browser-use/browser-harness)
+- 设计哲学：[The Bitter Lesson of Agent Harnesses](https://browser-use.com/posts/bitter-lesson-agent-harnesses)
+- Cloud 浏览器：[cloud.browser-use.com](https://cloud.browser-use.com)
+- 官方文档：[docs.browser-use.com](https://docs.browser-use.com)
+
+---
+
+> 最后更新：2026-06-01
+> 基于 Browser Harness v0.1.0