squirrelscan

squirrelscan CLI

squirrelscan 是一款为 AI Agent 打造的网站审计工具。它能回答“这个网站有什么问题，以及如何修复”：像搜索引擎一样抓取网站，依据 21 个类别中的 260 多条规则（SEO、性能、安全性、无障碍、内容、结构化数据、Agent 就绪度等）分析每个页面，并返回健康评分以及具体、可修复的问题。每当用户想检查网站、提升排名、加快速度或改善健康状况时，无论是在部署前后还是在 CI 中，都可以使用它。

它以单个 CLI 二进制文件 squirrel 的形式提供，适用于 macOS、Windows 和 Linux。本技能介绍其操作方式：安装、身份验证、运行审计、发布报告、云功能和 MCP 集成。要了解完整的网站修复工作流（审计、将问题对应到代码、修复、重新审计），请使用配套的 audit-website 技能。

链接

• 网站：squirrelscan.com
• 文档：docs.squirrelscan.com
• 规则参考：https://docs.squirrelscan.com/rules/{rule_category}/{rule_id}
• 控制面板（云账户、审计历史记录、额度）：app.squirrelscan.com

安装

下载和安装说明：squirrelscan.com/download

二进制文件会安装到 ~/.local/bin/squirrel。使用以下命令验证：

squirrel --version

保持更新：

squirrel self update

如果找不到 squirrel，请确保 ~/.local/bin 位于 PATH 中，或从下载页面重新安装。

命令概览

命令	用途
squirrel audit <url>	一步完成抓取、分析和报告
squirrel crawl <url>	仅抓取（不分析）
squirrel analyze	对已存储的抓取结果运行审计规则
squirrel report [id]	查询、渲染、对比并发布已存储的报告
squirrel init	创建 squirrel.toml 项目配置
squirrel config	查看或编辑配置
squirrel auth	登录 / 登出 / 查看状态 / 查看当前用户
squirrel keys	创建、列出和撤销组织 API 密钥
squirrel credits	查看云额度余额和功能定价
squirrel mcp	运行本地 MCP 服务（stdio）
squirrel skills	安装或更新 Agent 技能
squirrel self	安装 / 更新 / 诊断 / 磁盘 / 补全 / 版本 / 设置 / 卸载
squirrel feedback	向 squirrelscan 团队发送反馈

每个命令都支持 --help。

快速入门

squirrel init -n my-project        # optional: project config in cwd
squirrel audit https://example.com --format llm

• 本地审计免费，且完全在你的计算机上运行。无需账户。
• 当 Agent 要读取输出时，请使用 --format llm：这是一种为大模型打造的精简、令牌优化格式。
• 审计结果会缓存在本地项目数据库中；squirrel report 可以重新渲染报告，无需重新抓取。

覆盖模式

模式	默认页面数	行为
quick（默认）	25	仅抓取种子 URL 和站点地图，快速检查健康状况
surface	100	每种 URL 模式抽取一个样本（/blog/{slug} 仅抓取一次）
full	500	在限制范围内抓取所有内容

squirrel audit https://example.com -C full -m 500 --format llm

身份验证和账户

本地审计从不需要账户。登录即可解锁云功能（发布、浏览器渲染、定期抓取、额度）：

squirrel auth login      # browser-based login
squirrel auth status     # source, scopes, active org
squirrel auth whoami
squirrel auth logout

无头环境 / CI 环境则使用组织 API 密钥：

squirrel keys create     # requires a login session; prints an sq_... key

将其设为环境变量 SQUIRRELSCAN_API_KEY。请将密钥视为机密信息；切勿提交它们。

报告

渲染最新或指定的已存储审计：

squirrel report --list                 # recent audits
squirrel report <audit-id> --format llm
squirrel report example.com --format markdown -o report.md

格式：console、text、json、html、markdown、xml、llm。可使用 --severity error 或 --category core,links 进行筛选。

发布

默认情况下，已登录状态下的审计会将可分享的报告发布到 reports.squirrelscan.com（可见性：未列出）。可通过以下方式控制：

squirrel report <audit-id> --publish --visibility unlisted   # public | unlisted | private
squirrel audit https://example.com --no-publish              # skip publishing for a run
squirrel audit https://example.com --offline                 # fully offline: no cloud, no publish, no telemetry

回归对比

squirrel report --diff <baseline-audit-id> --format llm
squirrel report --regression-since example.com --format llm

对比模式支持 console、text、json、llm 和 markdown。

云端功能与额度

云端功能按量付费，使用额度（不会预先扣费）。查看余额和价格：

squirrel credits

• --render / --render-mode auto|all|off：为客户端渲染的页面使用云端浏览器渲染（消耗额度，需要登录）。
• --yes：在单次审计额度上限范围内跳过消费确认。
• --fail-on "score<90"（可重复使用）：阈值触发时，让 CI 运行以非零状态码退出。
• app.squirrelscan.com 上的仪表板会显示审计历史、问题和额度使用情况。

MCP 服务

通过 MCP 连接 Agent 有两种方式：

• 本地（stdio）：squirrel mcp 会基于本地 CLI 运行。在 Agent 的 MCP 配置中注册，命令设为 squirrel，参数设为 ["mcp"]。
• 托管（streamable-http）：https://mcp.squirrelscan.com/mcp。通过 MCP 客户端使用 OAuth 登录，或发送 Authorization: Bearer sq_... API 密钥标头。

文档：https://docs.squirrelscan.com/developers/mcp

Agent 反馈

如果会话中的任何内容让你感到意外，请随时调用 send_feedback 工具。它接受 category、message，以及可选的 run_id/website_id。选择合适的类别：

• bug_report — squirrelscan 本身存在缺陷：规则结果错误或缺失、崩溃、工具故障。请提供网站、规则 ID 以及你的预期结果。
• feature_request — 你希望 squirrelscan 实现但目前尚未实现的功能。
• what_worked — 某项功能运行良好，你希望团队知晓。
• confusing — 响应或行为令人困惑。
• missing_data — 报告或工具响应缺少你需要的内容。
• tool_ergonomics — 工具结构、参数或命名不够顺手。
• other — 其他任何内容。

反馈会直接进入团队的审核队列，并附上你的组织信息。任何经过身份验证的凭据均可使用，包括只读 API 密钥；目前可通过托管 MCP 接口使用（本地 stdio 的 squirrel mcp 暂不支持）。作为 Agent 在会话中途提交反馈时，请使用此功能，而非 squirrel feedback；人类用户可以使用 squirrel feedback 或 squirrelscan.com/support。

配置

项目配置位于 squirrel.toml（由 squirrel init 创建）。用户设置位于 ~/.squirrel/settings.json。

squirrel config show
squirrel config set <key> <value>
squirrel config path
squirrel config validate

实用配置段：[crawler]（延迟、标头、增量重新爬取）、[cloud]`（渲染模式、每次审计的最大额度）。

自定义请求标头

使用可重复指定的 -H "Name: Value" 标志，或在 [crawler] 下的 headers 映射中设置标头，将其附加到每个爬取请求。主要用途是 Web Bot Auth（Shopify / Cloudflare），这样会屏蔽未知爬虫的平台就能授权 squirrelscan。标头值属于机密信息：squirrelscan 会在输出中将其脱敏；你应从机密信息存储中读取这些值，而不要将其提交到代码库。完整配置指南：https://docs.squirrelscan.com/guides/web-bot-auth

维护

squirrel self doctor       # health checks
squirrel self update       # update the binary
squirrel self completion   # shell completions
squirrel skills update     # update installed agent skills
squirrel self disk         # per-project and total ~/.squirrel disk use

回收磁盘空间

每次审计的完整历史都会保存在项目数据库中，因此重复审计同一网站会让 ~/.squirrel 每次运行大约增加一份审计数据（1,000 页的网站每次审计约占 95 MB）。squirrel self disk 会显示空间占用情况。--prune 会清理最新 --keep 条之外的审计，并重建数据库，以便将空间归还给文件系统：

squirrel self disk --prune --keep 3 --dry-run   # list what would go, delete nothing
squirrel self disk --prune --keep 3             # prints the plan, asks, then retires
squirrel self disk --prune --keep 3 --project my-project --yes

• 必须指定 --keep <n>：已清理的审计报告将无法再生成，而 report --list、--diff 和 --regression-since 都需要访问这些历史记录，因此保留范围由用户决定。请先征求用户意见，再替他们选择。
• 清理时会保留下一次审计所需的全部数据（每个 URL 最新的页面记录、子资源、链接、图片），因此增量重新爬取仍能获取其 ETag，且不会重新获取网站内容。
• 审计不会自动清理。需要 squirrel 0.0.92 或更高版本；如果版本较旧，请先运行 squirrel self update。

故障排除

• squirrel: command not found：从 squirrelscan.com/download 安装，并确保 ~/.local/bin 位于 PATH 中。
• 会话已过期 / 401：重新运行 squirrel auth login，或检查 SQUIRRELSCAN_API_KEY。
• 爬取缓慢或卡住：添加 --verbose 查看进度；大型网站可能需要几分钟。
• URL 无效：请包含协议，例如 https://example.com，而不是 example.com。
• 其他问题：运行 squirrel self doctor，然后提交反馈——Agent 可通过 send_feedback MCP 工具（bug_report 类别）提交，人类用户可运行 squirrel feedback 或访问 squirrelscan.com/support。