# WebRecorder

录制 Chrome 浏览器请求/响应作为大模型知识库，通过 MCP Server 暴露查询与浏览器控制能力。

- 录制：popup 手动开关，录当前 tab 或所有 tab 的所有请求/响应
- 存储：SQLite 单文件，按 session 组织
- 静态资源：录制时只存元数据，大模型按需 replay 重新请求拿响应体
- 动态资源：存请求体 + 响应体
- 查询：MCP 暴露 list_sessions / list_requests / get_request / get_response_body / search_requests / replay_static
- 控制：MCP 暴露 navigate / evaluate，大模型可主动操作浏览器

详细设计见 `../docs/superpowers/specs/2026-07-10-chrome-web-recorder-design.md`。

## 安装

### 1. 编译并安装 service-go

```bash
cd service-go
bash build.sh                    # 交叉编译 4 平台二进制到 bin/
bash install.sh                  # macOS：安装 launchd 常驻服务
# 或 Linux：bash install-linux.sh
```

安装后：
- 二进制在 `~/.webrecorder/bin/web-recorder-service`
- 监听 `127.0.0.1:9130`（HTTP）和 `9131`（WS），开机自启 + 崩溃重启
- 数据库 `~/.webrecorder/sessions.db`
- 日志 `~/Library/Logs/webrecorder-service.log`（macOS）或 `~/.webrecorder/webrecorder.log`（Linux）

### 2. 加载 Chrome 扩展

1. 打开 `chrome://extensions/`
2. 右上角开启「开发者模式」
3. 点「加载已解压的扩展程序」
4. 选择 `chrome-web-recorder/` 根目录（即本仓库根目录，含 `manifest.json`）

### 3. 配置 Claude Code MCP

在 `~/.claude.json`（或项目 `.mcp.json`）加：

```json
{
  "mcpServers": {
    "web-recorder": {
      "command": "/Users/<你的用户名>/.webrecorder/bin/web-recorder-service",
      "args": []
    }
  }
}
```

args 为空（默认 MCP stdio 模式）。重启 Claude Code 后 MCP 工具可用。

## 使用

### 录制

1. 点扩展图标打开 popup
2. 输入会话名（留空用时间戳）
3. 选范围（当前 tab / 所有）
4. 可选：勾选过滤统计/广告域名，加额外屏蔽子串
5. 点「开始录制」
6. 在目标页面操作（导航、点击、提交等）
7. 点「停止录制」

录制中页面右上角有红色浮标显示实时计数。

### 大模型查询

Claude Code 里直接调 MCP 工具：

```
list_sessions()                                        # 列出所有会话
list_requests(session_id="sess_xxx")                   # 列出某会话的请求
get_request(request_id="req_xxx")                      # 拿单个请求详情
get_response_body(request_id="req_xxx")                 # 拿动态资源响应体
search_requests(session_id="sess_xxx", query="login")  # 全文搜索
replay_static(request_id="req_xxx")                    # 重新请求静态资源
```

### 大模型控制浏览器

```
navigate(url="https://example.com")    # 跳转
evaluate(script="document.title")      # 执行 JS 拿返回值
```

navigate/evaluate 触发的请求也会录进当前 session（如果正在录制）。

## 验证

### 验证 service-go

```bash
curl -s http://127.0.0.1:9130/ping        # 期望 pong
curl -s http://127.0.0.1:9130/config      # 期望 {"http_port":9130,"ws_port":9131}
```

### 验证录制

```bash
# 录制一个会话后
sqlite3 ~/.webrecorder/sessions.db "SELECT id, name, request_count FROM sessions ORDER BY started_at DESC LIMIT 5"
sqlite3 ~/.webrecorder/sessions.db "SELECT method, url, resource_type FROM requests WHERE session_id='<某session_id>' LIMIT 10"
```

### 验证 MCP

在 Claude Code 里调 `list_sessions`，应返回最近会话列表。

## 故障排查

### service-go 启动失败

查日志：

```bash
tail -f ~/Library/Logs/webrecorder-service.log   # macOS
journalctl --user -u webrecorder -f               # Linux
```

### 端口冲突

默认 9130/9131 被占用时，用环境变量改：

```bash
# 手动跑（改端口测试）
WEBRECORDER_HTTP_PORT=9140 WEBRECORDER_WS_PORT=9141 ~/.webrecorder/bin/web-recorder-service --http
```

若要让 launchd 常驻服务用新端口，编辑 `~/Library/LaunchAgents/com.xwx.webrecorder.plist`，在 `ProgramArguments` 后加 `EnvironmentVariables` 字段：

```xml
<key>EnvironmentVariables</key>
<dict>
  <key>WEBRECORDER_HTTP_PORT</key>
  <string>9140</string>
  <key>WEBRECORDER_WS_PORT</key>
  <string>9141</string>
</dict>
```

改完 `launchctl unload && launchctl load` 重载。扩展会通过 `GET /config` 自动发现端口。

### macOS 11 上崩溃

如果二进制在 macOS 11 上报 `dyld: Symbol not found: _SecTrustCopyCertificateChain`，说明编译时部署目标没设到 11.0。

原因（Go 1.25 已知问题）：Go 1.25 默认用 internal linker，internal linking 下 mach-o 的 `LC_BUILD_VERSION.minos` 被 cmd/link 硬编码为 12.0.0，完全不读 `MACOSX_DEPLOYMENT_TARGET` 环境变量。必须在编译时加 `-ldflags="-linkmode=external"` 强制走 external linking（经 clang），clang 才会读取 `MACOSX_DEPLOYMENT_TARGET=11.0` 并生成 `minos=11.0` 的 `LC_BUILD_VERSION`。

当前 `build.sh` 已处理：同时设 `MACOSX_DEPLOYMENT_TARGET=11.0`、`CGO_ENABLED=1`、`-ldflags="-linkmode=external"`，并用 `otool` 验证 `LC_BUILD_VERSION.minos` 字段（注意不是旧的 `LC_BUILD_MACOSX_VERSION`）。编译输出应看到：

```
✓ arm64: deployment target = 11.0.0
✓ amd64: deployment target = 11.0.0
```

如果你自己改 build.sh，注意这三者缺一不可，否则 macOS 11 会崩溃。

### 扩展浮标不出现

- 确认扩展已加载且启用
- 刷新目标页面（content script 在 `document_start` 注入）
- 检查 service worker console（`chrome://extensions/` → 扩展 → 「检查视图 service worker」）有无报错

### MCP 工具不出现

- 确认 Claude Code 配置里 command 路径正确且二进制可执行
- 确认 service-go 以 MCP 模式启动（无 `--http` 参数；MCP 模式由 Claude Code 拉起，与 launchd 的 `--http` 常驻实例是两个独立进程）
- 重启 Claude Code

### 录制后数据库为空

- 确认 service-go 在跑（`curl http://127.0.0.1:9130/ping`）
- service worker console 检查 `fetch('http://127.0.0.1:9130/record')` 是否报错
- 确认 popup 显示「录制中」状态

## 权限说明

| 权限 | 用途 |
|---|---|
| `webRequest` | 监听请求/响应 |
| `storage` | 存录制状态、过滤配置 |
| `alarms` | WS keep-alive |
| `tabs` | navigate |
| `scripting` | evaluate |
| `<all_urls>` | 拦截任意 URL + WS 连本地 + evaluate 任意页面 |

## 安全提示

- `evaluate` 能执行任意 JS，等于完全控制当前页面（读 cookie、调 API、改 DOM）
- service-go 默认仅监听 `127.0.0.1`，不要暴露到公网
- 录制数据含敏感字段（cookie/authorization），数据库文件注意保护