squirrelscan

squirrelscan CLI

squirrelscan 是專為 AI 代理程式設計的網站審查工具。它能回答「這個網站有什麼問題，以及如何修正」：它會像搜尋引擎一樣爬取網站，針對 260+ 條規則（涵蓋 21 個類別，包括 SEO、效能、安全性、無障礙性、內容、結構化資料、代理程式就緒度等）分析每個頁面，並回傳健康度分數以及具體可修正的問題。當使用者想要檢查網站、提升排名、加快速度或改善健康度，無論是在部署前後或 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	登入 / 登出 / 狀態 / whoami
squirrel keys	建立、列出、撤銷組織 API 金鑰
squirrel credits	雲端點數餘額 + 功能定價
squirrel mcp	執行本機 MCP 伺服器（stdio）
squirrel skills	安裝或更新代理程式技能
squirrel self	安裝 / 更新 / doctor / completion / version / settings / 解除安裝
squirrel feedback	傳送回饋給 squirrelscan 團隊

每個指令都支援 --help。

快速入門

squirrel init -n my-project        # 可選：在目前目錄建立專案設定
squirrel audit https://example.com --format llm

• 本機審查完全免費，且完全在您的機器上執行。無需帳戶。
• 當代理程式讀取輸出時，請一律使用 --format llm：這是一種專為 LLM 設計的簡潔、最佳化 token 的格式。
• 審查結果會快取在本機專案資料庫中；squirrel report 可重新呈現而不需重新爬取。

涵蓋模式

模式	預設頁數	行為
quick（預設）	25	僅種子頁面與網站地圖，快速健康檢查
surface	100	每種 URL 模式取一個樣本（例如 /blog/{slug} 只爬一次）
full	500	爬取所有頁面直到上限

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

驗證與帳戶

本機審查永遠不需要帳戶。登入以解鎖雲端功能（發布、瀏覽器渲染、排程爬取、點數）：

squirrel auth login      # 透過瀏覽器登入
squirrel auth status     # 來源、範圍、活躍組織
squirrel auth whoami
squirrel auth logout

無頭 / CI 環境請改用組織 API 金鑰：

squirrel keys create     # 需要登入工作階段；會印出 sq_... 金鑰

將金鑰設為環境變數 SQUIRRELSCAN_API_KEY。請將金鑰視為機密，切勿提交到版本控制。

報告

呈現最新（或特定）的已儲存審查結果：

squirrel report --list                 # 最近的審查
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              # 跳過本次執行的發布
squirrel audit https://example.com --offline                 # 完全離線：無雲端、無發布、無遙測

回歸比對

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 連接：

• 本機（stdio）：squirrel mcp 會對應本機 CLI。在代理程式的 MCP 設定中，使用指令 squirrel 與參數 ["mcp"] 註冊。
• 託管（streamable-http）：https://mcp.squirrelscan.com/mcp。從 MCP 用戶端透過 OAuth 登入，或傳送 Authorization: Bearer sq_... API 金鑰標頭。

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

代理程式回饋

當工作階段中發生任何出乎意料的情況時，請隨時呼叫 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 表面上使用（尚未在 squirrel mcp 本機 stdio 中提供）。當您是代理程式並在會話中回報時，請使用此工具而非 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       # 健康檢查
squirrel self update       # 更新二進位檔
squirrel self completion   # shell 自動補全
squirrel skills 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，然後回報 — 代理程式透過 send_feedback MCP 工具（bug_report 類別），人類使用者透過 squirrel feedback 或 squirrelscan.com/support。