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

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）加：

{
  "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

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}

验证录制

# 录制一个会话后
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 启动失败

查日志：

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

端口冲突

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

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

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

<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），数据库文件注意保护