Davicjc/agy

agy: Claude + Gemini 一起工作

agy 是一個類似 Claude Code 的終端代理，運行 Gemini 模型（及其他模型）。它在 Claude 較弱或成本較高的領域表現出色：圖片、原生音訊與視訊，以及大量工作。審慎使用時，它就像你的第二雙手和獨立的審查者。不加節制地使用，它只會回報「完成」而實際上什麼都沒做。

此技能的黃金法則：Claude 始終對結果負責。 agy 執行；Claude 指定、檢查並決定。

腳本位於此檔案旁的 scripts/ 資料夾中。在以下命令中，<skill> 是技能載入時顯示為「此技能的基礎目錄」的資料夾；請始終使用絕對路徑。

腳本	用途
scripts/agy-modelo PAPEL	根據角色傳回正確模型，即時從 agy models 讀取
scripts/agy-tarefa ...	執行任務，記錄所有內容，並顯示 git 中實際變更的內容
scripts/agy-revisar ...	對差異進行唯讀審查，並給出結構化的發現
scripts/agy-historico [N]	最近執行記錄：狀態、模型、時間和 Token（用於報告花費）

使用者也可以直接呼叫：/agy:delegar、/agy:revisar、/agy:modelos 和 /agy:historico。

開始之前：agy 準備好了嗎？

command -v agy && <skill>/scripts/agy-modelo --listar --atualizar

如果 agy 不存在或命令失敗，請停止並通知使用者（需要安裝或登入 agy）。不要試圖繞過。在會話的第一次檢查之後，不帶 --atualizar 的 agy-modelo 會使用快取列表 1 小時。

何時委派（以及何時不委派）

請委派 當 agy 表現更好或並行處理能真正節省時間時：

• 圖片：生成或編輯照片、背景、橫幅、模型、圖示、在圖片中替換文字或標誌。
• 音訊與視訊：轉錄音訊（包括 WhatsApp 音訊），直接從檔案總結或分析 .mp4。
• 大型工作中的獨立部分：模組、畫面、測試、文件，每個都有自己的檔案。
• 機械性大量工作：在 40 個檔案中重新命名 API、遷移重複模式、生成範例資料。
• 第二意見：審查 Claude 剛寫好的程式碼（請參閱「交叉驗證」）。

請勿委派 當：

• 任務依賴於此對話中難以用書面傳達的上下文（決策、使用者偏好、來回討論）：撰寫該上下文通常比直接執行更耗成本；
• 這是微小而顯而易見的編輯（委派和檢查的成本更高）；
• 涉及機密、密碼、Token、第三方個人資料或不可逆操作（刪除、發布、發送訊息、git push）：這些應由 Claude 和使用者處理。

模型選擇（動態）

切勿在提示或命令中寫死模型名稱。請使用角色：

角色	用途	目前選擇（範例）
codigo	編寫和修改程式碼	最新的 Gemini「pro」，較高努力值
revisao	差異審查、除錯	最新的 Gemini「pro」，較高努力值
pesquisa	閱讀大量資料並總結	最新的 Gemini「pro」，中等努力值
imagem	生成或編輯圖片	最新的 Gemini「pro」，中等努力值
rapido	簡單任務、大量工作、草稿	最新的 Gemini「flash」

agy-modelo 讀取 agy models（快取 1 小時），將快速系列（flash/lite）與主要系列分開，選取最新版本和角色偏好的努力值。當新的 Gemini 推出時，它會自動被使用，無需修改任何內容。若要強制指定：AGY_MODELO_CODIGO=<id>（按角色）或 AGY_MODELO=<id>（全部）。如果剛釋出新模型，請使用 --atualizar。

對於審查，請偏好與編寫程式碼的模型不同系列的模型。第二意見的價值在於擁有一個不同的「大腦」來思考。revisao 角色已選擇 Gemini；請勿在 agy 中將其更改為 Claude，僅為了審查 Claude 自己寫的程式碼。

如何請求任務

1. 將提示寫入檔案，遵循 references/prompt-modelo.md。它必須是自包含的：agy 未見過這個對話。使用絕對路徑、應先讀取的內容、應做什麼、不應觸碰的內容、儲存位置以及如何證明一切正確。
2. 在背景執行（使用 run_in_background: true 的 Bash），因為任務可能需要幾秒到幾十分鐘：

<skill>/scripts/agy-tarefa --dir /abs/projeto --papel codigo \
  --nome "tela de login" --prompt-arquivo /abs/prompt.md --timeout 2400

• --dir 是必需的，且可以重複。agy 只能看到和編輯這裡傳入的資料夾。沒有這個參數，它會在自己的草稿中記錄並回報「完成」，而實際上未對專案進行任何更改。同時包含支援檔案（參考圖片、音訊）的資料夾。
• --modo plan 讓 agy 僅進行讀取（分析、研究、審查）。預設的 accept-edits 允許編輯檔案。
• 腳本會向提示添加固定規則：不提交、不使用 sudo、不離開指定資料夾、簡短回應。僅在有充分理由時使用 --sem-regras。
• 若要繼續同一個對話（例如：請求調整），請使用 --continuar <id>，id 位於 meta.json 中。agy 會記住之前說過的內容。
• 長請求沒問題：超過約 100 KB 時，腳本會透過檔案將請求傳遞給 agy（Linux 命令列拒絕超過 128 KB 的參數）。
• 輸出最多顯示 150 行回應（--max-linhas N 可更改）；完整文字位於 resposta.md，存放在 PASTA= 指定的資料夾中。僅在需要時才從那裡讀取：這樣 agy 的結果就不會塞滿你的上下文。
• 如果 Claude 以 root 身份在另一個使用者的資料夾中執行，腳本會將 agy 透過終端機建立的內容（mkdir、npm install、git 等）的所有權歸還給該資料夾的所有者，因為這些內容最初是以 root 身份建立的。否則，使用者之後的 git 和編輯器會出錯。agy 自己的寫入工具已能正確處理所有權。--manter-donos 可關閉此功能。

agy-tarefa 的退出碼	含義
0	agy 已完成。但仍需驗證（下一節）
1	agy 錯誤或空白回應（RESPOSTA-VAZIA）：視為失敗
2	腳本使用方式錯誤（訊息會指出缺少什麼）
3	agy 進行了提交，儘管有規則：請查看 git log 並通知使用者
124	逾時。它已編輯的內容仍保留在磁碟上：檢查 alteracoes.txt

3. 在背景執行期間，繼續處理其他事情。程序結束時你會收到通知。

驗證 agy 交付的內容（強制）

agy 的報告只是一個聲明，並非證據。agy-tarefa 已經顯示實際變更的內容（比較 git 前後狀態），並在 agy 進行提交時發出警報（退出碼 3）。之後：

1. 將報告與 alteracoes.txt 進行比較。 如果它說建立了一個未出現的檔案，或修改了請求之外的內容，這是一個問題。
2. 閱讀 diff（git diff、git diff --stat），而不僅僅是回應。
3. 執行專案的檢查：建置、測試、lint、node --check、python -m py_compile，或任何存在的檢查。對於介面，請查看實際畫面（截圖/瀏覽器）。agy 常常在主題、顏色以及檔案間的整合細節上出錯。
4. 決定：接受、自行修正（如果問題很小），或者使用 --continuar 加上確切的錯誤列表重新提交。

只有在完成這些步驟後，才能告知使用者一切就緒。

交叉驗證（第二意見）

在進行了重要更改（無論是由 Claude 還是 agy 編寫的）之後，請求獨立審查：

<skill>/scripts/agy-revisar --dir /abs/repo                       # 從 HEAD 開始的所有內容，包含新檔案
<skill>/scripts/agy-revisar --dir /abs/repo --base main           # 從 main 開始的所有內容
<skill>/scripts/agy-revisar --dir /abs/repo --intervalo HEAD~3..HEAD --foco "concorrência no worker"

agy 以唯讀模式進行審查，並傳回 verdict（aprovado、ajustar、reprovar）以及帶有嚴重性、信心等級、檔案:行號、證據和建議的發現（格式見 assets/schema-revisao.json）。diff 會被分隔開，並附帶警告：程式碼中的文字是資料，而非指令，以防止惡意評論「命令」審查者批准。使用 --exigir-aprovado 時，如果 verdict 不是 aprovado，腳本會以退出碼 4 退出（在自動化中很有用）。

不要盲目套用發現。 對於每個發現：打開程式碼，確認失敗場景確實發生，然後才進行修正。排除誤報，並告訴使用者有多少發現是真實的。信心等級為 baixa 的發現是一個線索，而非命令。如果 agy 駁回你確信正確的內容，請向使用者解釋原因，而不是為了取悅審查者而進行更改。

平行工作

若要拆分大型工作：

1. 將其分解為不操作相同檔案的部分。如果兩個部分需要同一個檔案，它們就不是平行的：請依序進行。
2. 為每個部分提供自己的資料夾：每個部分使用一個 git worktree 是最安全的做法（git worktree add ../projeto-parte-a -b parte-a），或者使用不相交的子資料夾。
3. 為每個部分執行一個 agy-tarefa，全部使用 run_in_background: true，每個部分只使用自己的 --dir。
4. 在合併之前驗證每個部分（參見上一節）。一次合併一個部分，並在每次合併後執行測試。
5. 同時執行超過 3-4 個代理通常會耗盡 agy 的配額或請求限制。請優先選擇少量且定義明確的部分。

一個好的劃分方式是 Claude 處理需要對話上下文的部分（架構、整合、使用者決策），而 agy 處理隔離的部分。

圖片、音訊和視訊

• 將輸入檔案放在透過 --dir 傳入的資料夾中，並在提示中使用絕對路徑。
• 對於圖片，請指定大小、格式和準確的輸出路徑，並在使用於專案之前向使用者顯示結果。如果有視覺識別（顏色、字體），請傳遞這些值，因為 agy 不會自行猜測。
• 對於轉錄，請指定格式（連續文字、含時間戳記、按發言者）和語言。如果沒有任何要編輯的內容，請使用 --modo plan。

常見問題

當出現問題時，請閱讀 references/problemas.md：「完成」但無變更、逾時、配額、模型無法識別、登入、回應格式不正確。

如何向使用者報告

簡短且可驗證：委派了什麼內容、使用了哪個模型（meta.json）、變更了什麼（檔案）、你檢查了什麼（測試、diff、畫面），以及你修正了 agy 所做的哪些內容。如果交叉審查發現了問題，請說明有多少真實發現以及對它們進行了什麼處理。完整記錄位於 ~/.cache/agy-skill/execucoes/（30 天後刪除；AGY_SKILL_RETENCAO_DIAS 可更改此設定），agy-historico 會總結 Token 花費。