Ferret
繁體中文
Discord （在新分頁中開啟） X （在新分頁中開啟） GitHub （在新分頁中開啟） 下載

使用 Ferret

傳送給 Agent

在內建終端機中執行你的程式設計 Agent，按一下就把審查交給它。常見的例子是 Claude Code 和 Codex，但下方清單中的任何 Agent 都能使用，你自己新增的 CLI 也可以。你也可以把指示複製給在其他地方執行的 Agent，或把審查發佈到 GitHub。

#檢查意見

意見 分頁中的每張卡片都可以：

  • 直接編輯標題與要求
  • 切換 傳送 / 不傳送
  • 觀看錄影（跳到該時間點）與 替換圖片（改選其他影格）
  • 確認 / 標記為需要確認、與下一則合併、刪除

依進度篩選 可依狀態顯示或隱藏意見（例如 僅顯示 等待你確認的意見）；全部顯示 會清除篩選。

標頭有 還原、開啟資料夾、拷貝給 Agent、傳送到 GitHub / GitLab、整理 與 傳送給 Agent。沒有成為意見的語音會列在 已排除的語音 中，按 還原為意見 即可取回。

意見分頁

#在內建終端機中執行 Agent

開啟專案時，Ferret 會依 設定 → Agent → 開啟專案時啟動 中選擇的 Agent，在專案資料夾中為每個 Agent 開一個終端機分頁，並以 Agent 的一般模式啟動。預設是 Claude Code 和 Codex：

claude
codex

你也可以改從支援清單中挑選任何 Agent（依選取順序啟動），或都不選。

權限確認維持開啟

登錄或複製專案並不會讓 Ferret 信任它。Claude Code 和 Codex 等 Agent 第一次會詢問你是否信任該資料夾，之後在修改檔案或執行指令前也會持續詢問。若要讓 Agent 在你信任的某個專案中略過權限確認、核准與沙箱，請在 設定 → Agent → 略過權限確認 中為該專案開啟並確認。Ferret 會為已知略過參數的 Agent 加上各自的參數；沒有已知參數的 Agent 會保留確認。此設定只套用到你自己在該專案資料夾中開啟的 Agent；開啟專案時自動啟動的 Agent 一律保留確認。在參數中輸入的略過權限參數會被忽略。

若沒有選擇任何 Agent，會開啟一般的 shell。+ 選單可以開啟 新增終端機、在新分頁中啟動你的任一 Agent，或跳到 Agent 設定…。它的搜尋框也能找到分頁、已儲存的 URL 和檔案。

分頁會顯示 Agent 的狀態：執行中、等待輸入、完成（未讀）、閒置。側邊欄會標示有 Agent 正在執行的專案，不必切換專案就能看到。

拖曳終端機分頁與窗格來分割、移動，再把它們變回分頁。

拖曳來分割。拖曳分頁，或拖曳窗格的把手（分頁分割後才會出現），然後放到：

  • 窗格邊緣外側四分之一處：向左分割 / 向右分割 / 向上分割 / 向下分割
  • 窗格中央：以分頁開啟（窗格會離開分割，成為獨立的分頁）
  • 整個終端機區域周圍的細長區域：將整個區域向左分割 等（有 2 個以上窗格時）
  • 分頁列：以分頁放在這裡

移動時程序會繼續執行，變成空的分頁會自動關閉。鍵盤分割：

動作macOSWindows / Linux
新增終端機⌘TCtrlT
向右分割⌘DCtrlShiftD
向下分割⌘⇧DAltShiftD
關閉窗格 / 分頁⌘WCtrlW

#支援的 Agent

Ferret 不綁定特定 Agent。它能辨識下列程式設計 Agent：可以啟動它們、在終端機中偵測它們以使用 傳送給 Agent，並顯示是否已安裝。設定 → Agent 會列出它們並標示 已安裝 / 找不到；若供應商有提供一行安裝指令，會顯示 安裝 按鈕，並列出每個 Agent 的指令與參數。

清單裡沒有？設定 → Agent → 新增自訂 Agent 可以登錄任何 CLI 或包裝腳本（名稱、指令，以及選填的用來辨識它的程序名稱），或在 settings.json 的 agents.customAgents 中加入。在 Ferret 外執行的 Agent 可以使用 拷貝給 Agent。

有幾項功能取決於 Agent，目前僅限 Claude Code 和 Codex：

  • 帳號與用量：在多個登入之間切換，以及頁尾的速率限制計量表。
  • 整理：使用你的 Claude Code 或 Codex 登入執行，或使用你設定的 LLM API。

#傳送給 Agent / 拷貝給 Agent

在意見分頁按「傳送給 Agent」，交給內建終端機中的 Agent。
  1. 按 傳送給 Agent。預設（自動（目前分頁或執行中的 Agent））會送到目前終端機分頁中的 Agent，或正在執行的 Agent。用按鈕旁的箭頭（選擇要傳送的 Agent）可以指定特定的 Agent 或分頁。
  2. Ferret 會把指示寫入 Agent 的輸入欄並送出。請在終端機中查看進度。

若沒有 Agent 在執行，Ferret 會先啟動一個，並在它就緒後立即傳送。Agent 正在等待權限回覆時不會傳送任何內容，請先在終端機中回覆。

拷貝給 Agent 會把同樣的指示放到剪貼簿，給在其他地方（其他終端機、IDE 或 App）執行的 Agent 使用。只有切換為 傳送 的意見會被處理。影片絕不會包含在內。

#用判定模型做驗收檢查

Agent 修正意見，並用判定模型逐一檢查，直到全部通過。

開啟後，你的程式設計 Agent 會在回報「完成」之前，依每則意見檢查自己的成果。Ferret 本身不做任何判定：它把判定模型（任何相容 System One 的 API）提供給 Agent，並在 feedback.md 中要求它反覆執行，直到每則意見都通過。

  1. Agent 實作意見。
  2. 對每則意見，Agent 擷取 AFTER 螢幕截圖（與 BEFORE 靜態畫面相同的視窗範圍與頁面狀態），並把意見內容、其「完成條件」行以及 BEFORE/AFTER 圖片，以一個請求傳給判定模型。
  3. 當 P(done) 達到門檻（預設 0.7）且選擇為 done 時，該意見即通過。Agent 會修正其餘意見，並在每一輪重新判定所有意見；只有在同一輪中所有意見都通過時才停止，或因為必須說明的正當理由而停止：API 無法連線、某則意見超出範圍，或某則意見卡住且分數沒有變化。
  4. 最後的「完成 / 未完成」清單會包含每則意見的分數與輪數。

請在 設定 → 判定模型 中設定，並開啟 在 Agent 指示中加入判定模型檢查。預設組合只會幫你填入欄位；每個欄位都能再編輯，自訂 可搭配任何相容的 API。

預設組合請求 URL模型金鑰
Ollama（預設）http://localhost:11434/v1/systemoneclef-flash、clef（可讀圖片）；nimble、tev1（僅文字）不需要，免費
Cloudflare Workers AIhttps://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}clef-flash、clef（可讀圖片）CLOUDFLARE_API_TOKEN（Workers AI 權限）；帳戶 ID 來自欄位或 CLOUDFLARE_ACCOUNT_ID
Vercel AI Gatewayhttps://ai-gateway.vercel.sh/typesafe/v1/systemonetypesafe-ai/jev、convaiinnovations/laya（僅文字）AI_GATEWAY_API_KEY
TypeSafehttps://api.typesafe.ai/v1/systemonejev-latest、jev-preview（僅文字）TYPESAFE_API_KEY
自訂任何完整 URL任何Bearer、自訂標頭或不使用；可加入額外標頭

使用 Ollama 時，請先安裝（Clef / Clef Flash 需要 0.35.1 以上），並在終端機中下載模型。Ferret 不會執行安裝程式：

ollama pull clef-flash

金鑰來自金鑰欄位（與你的其他 API 金鑰一起儲存）、你指定的環境變數（App 的環境、專案的 .env 或 ~/.ferret/.env），或 settings.json 中的 apiKey。額外標頭可以用 ${VAR} 讀取環境變數的值。

金鑰如何不出現在提示詞中

Agent 永遠看不到你的金鑰。Ferret 會在 127.0.0.1 上執行本機中繼，並提供每個終端機 FERRET_DECISION_URL（中繼的位址，附每個終端機專用的權杖）、FERRET_DECISION_MODEL 與 FERRET_DECISION_IMAGES（在一個版本內，也會同時設定舊的 MOVIE_ADE_DECISION_* 名稱）。中繼會加上金鑰與標頭，並原封不動地轉送請求，因此提示詞、feedback.md 和 Agent 的對話紀錄中都不含機密。變更設定後開啟的終端機會套用新設定。

Cloudflare 與 System One 文件有兩點不同（已用實際 API 確認）：圖片必須是 data URI（data:image/jpeg;base64,…，否則會回傳 422 "image must be an embedded base64 data URI"），且回應會包裝成 { "result": { … }, "success": true }（錯誤則回傳 { "success": false, "errors": [ … ] }）。Cloudflare 預設組合會把 圖片編碼 設為 data URI，Agent 會以 FERRET_DECISION_IMAGE_FORMAT 取得此設定，指示中也會要求它在有 .result 時讀取該欄位。中繼對雙向內容都原封不動地傳遞。若要改用 Global API Key 而非 API 權杖，請把 驗證 設為 無金鑰，並加入標頭 X-Auth-Email: ${CLOUDFLARE_EMAIL} 與 X-Auth-Key: ${CLOUDFLARE_API_KEY}。

只有 Clef 和 Clef Flash 能讀取圖片。使用僅限文字的模型時，請關閉 傳送 BEFORE/AFTER 圖片；此時 Agent 只依文字判定，可靠度較低。

Ollama 與大型圖片

Ollama 0.35.0 將 /v1/systemone 請求限制在 64 KiB，因此附上螢幕截圖的請求會以 HTTP 413 失敗。指示會要求 Agent 把兩張圖片都縮小到寬度最多 1024px 的 JPEG（品質約 70）。如果仍然收到 413，請把 Ollama 更新到 0.35.1 以上，或改用 Cloudflare Workers AI。

#頁尾的 API 用量

判定呼叫會經過中繼，因此 Ferret 可以計算它們。頁尾中 Agent 用量計量表旁的項目會顯示判定模型，以及今天的呼叫次數、權杖數與費用（例如 clef-flash · 42 calls · 18.3k tok）。按一下即可查看今天、本月、各專案、各模型與各類型（判定 / 轉錄 / 整理）的用量，以及最近 50 次呼叫。

只有在 API 回報費用（Vercel AI Gateway 會回報），或你在 設定 → 判定模型 中設定每 1M 權杖的價格時，才會顯示費用；否則會顯示「—」。只會記錄中繼資料（時間、專案、模型、狀態、延遲、大小、圖片數、權杖數、費用），絕不記錄圖片、文字或金鑰；記錄存放在 ~/.ferret/usage/decision-YYYY-MM.jsonl，每月一個檔案。

#自訂指示

編輯 設定 → Agent → 給 Agent 的指示。會展開兩個變數：

變數展開為
{{path}}feedback.md 的絕對路徑
{{relpath}}相對於專案的路徑：.ferret/reviews/<id>/feedback.md

留空即使用預設值。長度上限為 2000 個字元，重設指示 會恢復預設值。範例：

Read {{relpath}} and the PNGs next to it. Fix only findings marked to send, one commit per finding, then run the tests.

此設定以 agentPrompt 儲存在 settings.json 中。

#傳送到 GitHub 或 GitLab（Issue / PR 或 MR 留言）

傳送到 GitHub 會把審查發佈為新的 Issue，或作為留言發佈到你某個開啟中的 Pull Request。驗證交由 GitHub CLI （在新分頁中開啟） 處理。Ferret 絕不讀取或儲存權杖。

  1. 安裝 gh：brew install gh（macOS）、winget install --id GitHub.cli（Windows），或參閱 cli/cli （在新分頁中開啟）。
  2. 設定 → GitHub / GitLab → 在終端機中登入 會在內建終端機中執行 gh auth login --web -h github.com。
  3. 按 傳送到 GitHub，選擇 建立新的 Issue 或某個 PR，並檢查 標題 與 內文（可編輯）。
  4. 勾選確認核取方塊，然後按 建立 Issue 或 發佈留言。

詳細說明：

  • 儲存庫取自 git remote get-url origin。
  • Ferret 會執行 gh issue create --repo … --title … --body-file - 或 gh pr comment <n> --repo … --body-file -。
  • 內文是去掉圖片行的 feedback.md（不會上傳圖片），最多 60,000 個字元。
  • 可選的 PR 是你自己開啟中的 PR（最多 30 個）。

如果設定了 GH_TOKEN 或 GITHUB_TOKEN，gh 會優先使用它，設定面板也會發出警告。

GitLab。當 origin 是 GitLab 專案（gitlab.com 或自行管理的 GitLab）時，同一個按鈕會透過 GitLab CLI （在新分頁中開啟）（glab）傳送到 GitLab：建立新的 Issue，或在你某個開啟中的 Merge Request 上留言。請用 設定 → GitHub / GitLab 登入，它會在內建終端機中執行 glab auth login（自行管理的 GitLab 會加上 --hostname）。Ferret 絕不讀取或儲存權杖，並會在設定了 GITLAB_TOKEN 時發出警告。

加星提示。在你第一次使用 傳送給 Agent 後，以及完成的審查達到 3、10、30 份時，Ferret 可能會請你在 GitHub 上為它加星。最多詢問 3 次，每次至少間隔 3 天，且錄製中絕不詢問。在 GitHub 上加星 會透過你自己的 gh 登入加星（若無法使用 gh 則開啟 GitHub），不再詢問 會停止提示。你也可以從 說明 → 在 GitHub 上為 Ferret 加星 加星。

#安裝並登入 CLI 工具

設定 → CLI 工具 會列出 Agent 經常需要的命令列工具，顯示哪些已安裝及其版本，並在新的終端機分頁中執行適用於你作業系統的官方安裝或登入指令：

  • Git 代管：gh、glab
  • AI 與模型：Ollama、Cloudflare wrangler
  • 部署：Vercel、Netlify、Fly.io、Railway、Heroku
  • 雲端與服務：Supabase、Firebase、Stripe、Google Cloud（gcloud）、AWS、Azure、Docker

若某個工具沒有適用於你作業系統的官方一行安裝指令，文件 會改為開啟它的安裝頁面。安裝完成後，清單會自動重新檢查。

在 GitHub 上協助翻譯此頁 （在新分頁中開啟）