内容
# 法罗
[](LICENSE)
[](Cargo.toml)
[](agents/faro/)
法罗是一款终端优先的浏览器调试工作台，适用于前端和全栈开发。
它通过Chrome DevTools协议启动或附加到Chromium家族浏览器，捕获浏览器观察到SQLite，并允许人类和代理通过TUI、CLI、SQL或MCP检查结果。
```text
浏览器 -> Chrome DevTools协议 -> 法罗捕获 -> SQLite -> TUI / CLI / MCP
```
法罗不嵌入Chromium，也不渲染网页到终端。它控制一个真正的浏览器，并保持一个持久的本地调试数据库。
链接： [贡献](CONTRIBUTING.md) · [安全](SECURITY.md) · [行为准则](CODE_OF_CONDUCT.md) · [MIT许可证](LICENSE)
## 功能
- 网络请求树，带有路由钻取、过滤器、预设、响应详细信息和重放历史。
- WebSocket帧流视图，带有发送/接收流量、有效载荷检查和过滤。
- 捕获的请求/响应头、查询参数、请求体、有界文本响应体、SSE解析和支持内联图像的终端小图像预览。
- 控制台日志、页面错误和通过 `$EDITOR` 的JavaScript临时评估。
- 存储和cookie视图，带有捕获的快照和实时的变更事件。
- 复制任何捕获的请求为一个完整的 `curl` 命令。
- 重放捕获的请求，使用 `curl`，持久化重放状态/正文元数据，并在请求详细信息面板中查看重放历史。
- 复制选定的请求的红白Markdown共享包，以便在需要将上下文发送给另一个人或代理时使用。
- TUI中的只读SQL编辑器，以及用于代理的CLI/MCP只读SQL。
- 面向代理的CLI和MCP服务器，用于捕获、检查、重放和SQL。
## 快速入门
### 从源代码安装
先决条件：
- Rust稳定版，支持2024版。
- Chromium家族浏览器：Chromium、Chrome、 Brave等。
- `curl`用于请求重放。
- 可选：`nvim`或其他 `$EDITOR`用于主体编辑、SQL和控制台评估。
```sh
git clone https://github.com/nullslate/faro.git
cd faro
cargo install --path crates/app
```
在本地应用程序上运行TUI：
```sh
faro http://localhost:5173
```
按 `o` 启动浏览器并开始捕获。使用急切启动，当您希望捕获立即开始时：
```sh
faro --launch-on-start http://localhost:5173
```
在不启动浏览器的情况下打开先前捕获的数据库：
```sh
faro tui ~/.config/faro/faro.db
```
### 无需安装即可运行
```sh
cargo run -- http://localhost:5173
cargo run -- --launch-on-start http://localhost:5173
```
### 附加到现有浏览器
```sh
chromium --remote-debugging-port=9222 --user-data-dir=/tmp/faro-profile
faro --attach-port 9222 http://localhost:5173
```
使用 `FARO_BROWSER=/path/to/chrome-or-chromium` 覆盖浏览器发现。
### 编辑器交接
法罗为SQL、控制台评估、正文查看/编辑、存储编辑、cookie编辑和重放编辑打开 `$EDITOR`。终端编辑器通常可以直接使用：
```sh
export EDITOR=nvim
```
GUI编辑器应配置为等待文件关闭：
```sh
export EDITOR="code --wait"
export EDITOR="zed --wait"
```
如果没有等待标志，GUI编辑器可能会立即返回，法罗将在文件保存之前继续。
## TUI基础知识
常用键：
```text
q/esc 退出
tab 切换焦点
1-6 切换视图：网络、控制台、WebSocket、脚本、存储、cookie
j/k 移动聚焦的选择
enter 钻取路由/展开选定的树项目
backspace 返回上一级路由
h/l 切换请求详细信息选项卡
p 打开命令调色板
o 打开浏览器并开始捕获
y 将选定的请求复制为curl
w 将选定的请求/响应交换保存到/tmp
r 使用curl重放选定的请求
R 在$EDITOR中编辑选定的请求，然后重放
D 将原始响应体与最新的重放响应体进行差异比较
s 循环请求排序
S 打开会话管理器
f 循环快速网络过滤器预设
e 在$EDITOR中打开选定的项目
u/d 滚动聚焦的详细信息/正文面板
g/G 跳转到聚焦面板的顶部/底部
/ 过滤请求
? 浮动键/过滤器帮助
c 清除请求过滤器
```
会话管理器允许您在捕获的会话之间切换并从数据库中删除旧会话。按 `S`，使用 `j/k` 移动，按 `enter` 打开会话，或按 `x` 删除选定的会话。
有用的调色板命令：
- `复制共享包`：复制带有标头、主体预览和重放历史的红白Markdown请求摘要。
- `会话：浏览`：在捕获的会话之间切换或删除，并带有请求/错误/重放/存储计数。
- `调试：切换性能`：在调整性能时显示帧、轮询、捕获、重放和详细加载计时。
请求过滤器支持纯文本、结构化字段和不区分大小写的正则表达式模式：
```text
method:post
status:2xx
status:404
type:fetch
domain:localhost
url:/api/users
path:/api
mime:json
header:x-request-id
body:error
reqbody:email
resbody:database
has:body
has:error
has:replay
duration:>500
size:>100kb
api/(users|teams)
path:/api/v[0-9]+
method:^(post|put)$
```
快速预设包括全部、错误、JSON、获取、XHR、SSE、图像、脚本、样式、文档、带有正文、慢速、大型和重放的预设。
## CLI
CLI设计用于希望在不打开TUI的情况下检查法罗的人和代理。
在没有TUI的情况下捕获页面：
```sh
faro capture https://example.com --for 15s --json
```
检查捕获的请求：
```sh
faro requests --route /api --filter "status >= 400" --json
faro request get <request-id> --body --json
faro request curl <request-id>
```
检查浏览器状态：
```sh
faro console errors --json
faro storage get localStorage auth --json
faro cookies list --json
faro sessions list --json
faro sessions prune <session-id> --max-requests 5000 --max-repeated 25 --max-console 2000 --max-ws 5000
faro db stats
faro db compact --vacuum
```
重放和查询：
```sh
faro replay <request-id> --json
faro sql "select * from requests where status_code >= 500" --json
```
清除捕获的会话及其级联的请求/控制台/存储/cookie/重放行：
```sh
faro sessions nuke --yes
```
修剪一个嘈杂的会话，同时保留最近的数据：
```sh
faro sessions prune <session-id> --max-requests 5000 --max-repeated 25 --max-console 2000 --max-ws 5000
```
在删除旧会话或修剪大量捕获数据后，压缩数据库：
```sh
faro db stats
faro db compact --vacuum
```
`faro sessions compact --vacuum` 作为兼容别名保留。压缩删除孤立的主体行，并且使用 `--vacuum` 时，检查WAL并要求SQLite回收文件空间。
`faro db stats` 报告数据库/WAL大小、正文字节总数、顶部会话的捕获权重、顶部重复请求组和表行计数，以便您了解有效载荷或元数据是否驱动增长。
路由过滤器接受：
- `/api/users`：确切的路由和后代。
- `/api/users/:id`：一个动态路径段。
- `/api/*`：路径的其余部分的通配符。
在任何命令中使用 `--db <path>` 以定位特定的SQLite数据库。
## MCP和代理集成
法罗包括一个stdio MCP服务器，以便编码代理可以检查与TUI和CLI相同的浏览器捕获数据库。服务器是DB-first：工具从SQLite读取，不会刮取终端UI。变异或浏览器驱动工具默认情况下被禁用。
```sh
faro mcp
```
仅当您希望代理启动/附加捕获、删除会话、重放请求、重新加载页面或评估JavaScript时，才启用变异工具：
```sh
faro --mcp-allow-mutation mcp
```
`copy_request_as_curl` 默认情况下会编辑敏感的头部并省略请求正文。要允许代理请求完整的凭证和正文，请使用 `include_sensitive: true` 启动MCP：
```sh
faro --mcp-allow-sensitive mcp
```
MCP正文返回工具使用 `redaction.mcp_body_limit_bytes` 从 `config.toml` 中限制返回正文文本，并在正文被剪裁时包含截断元数据。
MCP配置示例：
```json
{
"mcpServers": {
"faro": {
"command": "faro",
"args": ["mcp"]
}
}
}
```
大多数用户应该指向默认配置数据库。使用显式数据库时，您希望使用项目特定的捕获或一次性调试会话：
```json
{
"mcpServers": {
"faro": {
"command": "faro",
"args": ["--db", "/path/to/faro.db", "mcp"]
}
}
}
```
### 典型代理工作流程
1. 通常启动法罗以重现问题。如果您有意启用 `--mcp-allow-mutation`，则代理也可以运行 `capture_url`。
2. 让代理调用 `list_sessions` 并在存在多个捕获时选择正确的 `session_id`。
3. 要求代理列出失败或缓慢的请求，并使用 `list_requests`。
4. 让它检查请求，并使用 `get_request` 和 `get_response_body` 检查响应正文。
5. 让它检查控制台失败，并使用 `list_console_errors`。
6. 使用 `copy_request_as_curl` 获取编辑的再现命令。只有在需要原始正文/凭证时，才启用敏感的MCP模式。
7. 仅在启动MCP并使用 `--mcp-allow-mutation` 时，才使用 `replay_request`。
8. 对于跨捕获数据库的更深入分析，使用 `run_readonly_sql`。
有用提示：
```text
使用法罗查找最新捕获中的失败网络请求。检查响应正文并总结可能的后端或前端问题。
```
```text
使用法罗检查捕获期间/api下的请求。查找慢速调用，如果安全，请重放最可疑的请求，并向我显示curl命令。
```
```text
使用法罗只读SQL，按域和状态码对捕获的请求进行分组。突出显示第三方故障和任何异常大的响应。
```
### MCP工具
| 工具 | 目的 |
| --- | --- |
| `capture_url` | 启动或附加到Chromium并捕获URL一段时间。需要 `--mcp-allow-mutation`。 |
| `list_sessions` | 列出捕获会话，带有请求/错误/重放/存储计数。 |
| `get_session` | 获取一个捕获会话和摘要计数。 |
| `get_db_stats` | 返回DB维护统计信息，包括正文总数、重会话、重复请求组和表计数。 |
| `list_heavy_sessions` | 按捕获的正文字节和请求量列出会话。 |
| `list_repeated_requests` | 列出重复的方法/类型/ URL组，这些组可能使会话嘈杂或变大。 |
| `prune_session` | 修剪一个会话并保留限制；需要 `confirm: true` 和 `--mcp-allow-mutation`。 |
| `delete_all_sessions` | 删除所有会话和级联捕获的数据；需要 `confirm: true` 和 `--mcp-allow-mutation`。 |
| `list_requests` | 列出捕获的请求，支持路由/过滤器以缩小结果。接受可选的 `session_id`。 |
| `get_request` | 获取请求元数据、头部、响应元数据和正文引用。 |
| `get_response_body` | 按请求id加载捕获的响应正文。 |
| `list_replays` | 按会话或请求列出重放记录。 |
| `get_replay` | 获取一个重放记录和可选的存储正文。 |
| `list_websocket_frames` | 列出捕获的WebSocket帧，带有方向/操作码过滤器。 |
| `list_console_errors` | 返回捕获的浏览器控制台错误。接受可选的 `session_id`。 |
| `list_storage_items` | 列出当前的localStorage/sessionStorage项目。接受可选的 `session_id` 和过滤器。 |
| `get_storage_item` | 读取当前的localStorage或sessionStorage项目。 |
| `list_cookies` | 列出当前的捕获cookie。接受可选的 `session_id`。 |
| `copy_request_as_curl` | 默认情况下返回编辑的 `curl` 命令。 `include_sensitive: true` 需要 `--mcp-allow-sensitive`。 |
| `replay_request` | 重放捕获的请求并持久化重放元数据。需要 `--mcp-allow-mutation`。 |
| `evaluate_js` | 通过 `capture_url` 返回的CDP websocket URL评估JavaScript。需要 `--mcp-allow-mutation`。 |
| `reload_page` | 通过 `capture_url` 返回的CDP websocket URL重载附加页面。需要 `--mcp-allow-mutation`。 |
| `run_readonly_sql` | 对法罗SQLite数据库运行有保护的只读SQL。 |
### 安全默认值
法罗设计用于捕获敏感的浏览器调试数据，因此共享和代理访问受到保护：
- 编辑的共享包隐藏敏感的头部并编辑匹配的JSON正文字段。
- MCP默认情况下运行只读以获取风险工具。浏览器驱动和变异工具需要 `--mcp-allow-mutation`。
- MCP curl输出默认情况下被编辑。原始凭证和正文需要 `include_sensitive: true` 和 `--mcp-allow-sensitive`。
- MCP正文响应大小上限为 `redaction.mcp_body_limit_bytes`。
- 与安全相关的操作会追加到法罗配置目录中的 `audit.jsonl`。
编辑规则可在 `config.toml` 中配置：
```toml
[redaction]
header_names = ["authorization", "cookie", "set-cookie", "x-api-key"]
json_key_patterns = ["auth", "email", "password", "secret", "token"]
text_patterns = ["bearer ", "token=", "password=", "secret="]
mcp_body_limit_bytes = 262144
```
与CLI相同的workflow可在代理无法使用MCP时使用：
```sh
faro capture https://example.com --for 15s --json
faro requests --filter "status >= 400" --json
faro request get <request-id> --body --json
faro request curl <request-id>
faro console errors --json
faro sql "select status_code, count(*) from requests group by status_code" --json
```
可导入的代理包位于：
```text
agents/faro/
```
它包含：
- `SKILL.md`：代理工具的工作流说明。
- `mcp.json`：可以直接复制的MCP服务器配置。
## 配置
在第一次运行法罗时，它会在平台配置目录中创建 `config.toml`：
```text
Linux: $XDG_CONFIG_HOME/faro/config.toml or ~/.config/faro/config.toml
macOS: ~/Library/Application Support/faro/config.toml
Windows: %APPDATA%\faro\config.toml
```
默认数据库路径是相对于配置目录的 `faro.db`。法罗还存储布局首选项、最后一个SQL查询和持久的Chromium配置文件。
```text
Linux: ~/.config/faro/faro.db
macOS: ~/Library/Application Support/faro/faro.db
Windows: %APPDATA%\faro\faro.db
```
重要配置字段：
```toml
[app]
db_path = "faro.db"
launch_on_start = false
[ui]
bottom_fade_rows = 3
max_body_tree_items = 2000
[theme]
text = "#d4be98"
muted = "#928374"
accent = "#89b482"
panel_title = "#d8a657"
panel_border = "#3c3836"
active_border = "#89b482"
```
默认主题是Gruvbox-inspired，可以使用十六进制颜色或支持的终端颜色名称进行自定义。
## 架构
工作区crates：
- `faro-core`：领域模型和事件类型。
- `faro-store`：SQLite事件存储、投影和只读SQL护栏。
- `faro-capture`：源中立的摄入管道。
- `faro-cdp`：Chrome DevTools协议捕获/控制平面。
- `faro`：CLI、TUI和MCP入口点。
捕获的数据存储在SQLite中，因此TUI、CLI、SQL和MCP都检查相同的事实来源。
## 开发
运行标准检查：
```sh
cargo fmt --check
cargo test
cargo clippy --all-targets --all-features -- -D warnings
rg -n "\.ok\(\)|\.unwrap\(|\.expect\(" crates
```
本地运行：
```sh
cargo run -- http://localhost:5173
cargo run -- capture http://localhost:5173 --for 10s --json
cargo run -- --db /tmp/faro.db mcp
```
运行可选的性能基准测试：
```sh
scripts/perf-smoke.sh
cargo test large_session -- --ignored --nocapture
cargo test render_perf -- --ignored --nocapture
```
使用粗略的目标：
```text
在开发机器上，请求过滤在25k行以下的性能，数据库增量在毫秒级别，渲染路径在16ms预算下。
```
## 下一步
Replay Polish 正在进行中：可选择的重放历史记录，比较任意重放差异，重放响应元数据，以及复制/导出重放结果的操作。
## 当前限制
- 法罗目前通过CDP针对Chromium家族浏览器。
- 响应体捕获有限，以避免无限的数据库增长。
- 存储突变跟踪基于CDP DOMStorage；快照用于基线和调和。
- Cookie突变跟踪使用HTTP `Set-Cookie` 观察加上页面端的 `document.cookie` 观察者。
- MCP浏览器操作需要来自 `capture_url` 的附加CDP websocket URL；数据库检查离线工作。
## 许可
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器