第6章 在終端裡使用——agy -p 和悄悄拒絕
選讀 需要的時候再讀。跳過也能跟上後面的章節。一句話總結:
agy是 Antigravity 的終端程式,agy -p "要做的事"執行一次就結束。 在-p下,需要許可的事會被悄悄拒絕。可是退出碼(程式結束時留下的編號)仍是 0(成功),所以很容易把空結果誤當成成功。
終端是用文字輸入命令來操作電腦的視窗。如果你是第一次接觸終端,這一章可以跳過。 想多瞭解終端,請看 Claude Code 第10章(選讀)。
本章的結果,是這本指南在 macOS 上實際執行 agy 得到的。照著做時,請直接在終端裡執行 agy。[1]
安裝並開始
macOS·Linux 的安裝命令是這樣的。[2]
curl -fsSL https://antigravity.google/cli/install.sh | bash這條命令會直接執行從網際網路上下載的安裝程式。所以,請確認和官方文件(antigravity.google/docs)上寫的一模一樣,再執行。 Windows 用的命令也在官方文件裡。
進入整理工具資料夾,輸入 agy,就會開啟對話介面。[3] 下面第一行的 cd 是進入那個資料夾的命令。如果已經在應用裡登入過,就不用瀏覽器,直接登入。[4]
第一次執行時,會問你是否信任這個資料夾(Workspace trust,把資料夾登記為可信的步驟)。[5] 整理工具資料夾是你自己建的,回答信任就行。這樣回答好,應該就能避開後面要講的一個拒絕陷阱(這本指南的推測)。
cd ~/hello-ai-practice/organizer
agy理解檢查
第一次執行 agy 時確認的“Workspace trust”是什麼?
執行模式
在互動式 agy 裡,用 Shift+Tab 切換執行模式。[6]
| 模式 | 修改檔案 | 執行命令 |
|---|---|---|
default | 展示改動內容並確認 | 詢問 |
accept-edits | 工作資料夾內自動 | 詢問 |
出處:Antigravity 官方文件(只摘錄了一部分)[7]
終端的預設許可權比應用更謹慎。寫檔案·命令·網路工具之前都會詢問,把命令關在圍欄裡的沙盒預設是關閉的(第4章)。
理解檢查
關於 agy 的 accept-edits 模式,哪種說法是對的?
agy -p——問一次就結束
-p 是發出一個請求、拿到回答後就結束的方式。因為沒有詢問的視窗,需要許可的事會按事先定好的規則處理。[8] 程式輸出的文字分成兩條路。[9]
- 正式輸出(stdout,標準輸出):回答本身。比如我要的檔案列表表格。
- 旁路(stderr,標準錯誤):進度和錯誤。比如告知 shell 命令被拒絕的提示。
在終端介面上,兩者通常會一起顯示。回答和提示混在一起也不用慌。
官方文件說明,工作資料夾內檔案的讀寫自動允許,shell 命令預設是「詢問」,所以會被悄悄拒絕(soft-deny)。[10] 悄悄拒絕不會中斷執行,而是以退出碼 0 結束,只在 stderr 裡告知什麼被攔住了。[11]
理解檢查
在 agy -p 裡遇到需要許可的操作,會怎樣?
這本指南遇到的四個陷阱
這些是在整理工具資料夾裡多次執行 agy -p 時真實遇到的事。
- 結果是空的,卻顯示成功。 代理想用 shell 命令(
ls,在終端裡輸入的命令)檢視資料夾列表,被拒絕了。於是它什麼也沒做出來就結束了。 退出碼是 0。這種事發生了三次。- 要做的事:請一定要確認結果檔案是不是真的生成了。
- 在沒有信任的資料夾裡,連讀寫也被拒絕。 在練習資料夾裡,曾經連寫入和讀取檔案都被拒絕。原因看起來是這個資料夾還沒有被登記為「信任的資料夾」(這本指南的推測)。[12]
- 要做的事:開啟一次互動式
agy,回答信任這個資料夾。[12:1]
- 要做的事:開啟一次互動式
- 解決:一個模式 + 一句話。 在命令末尾加上
--mode accept-edits,並在請求末尾加上「不要用 shell 命令,只讀寫檔案」,就全部成功了。- 不要使用允許一切的
--dangerously-skip-permissions選項。 - 這種以
--開頭的文字叫作選項。加在命令後面,用來改變執行方式。--mode accept-edits的意思是用上面表格裡的accept-edits模式執行。在下面命令的最末尾能看到它。
- 不要使用允許一切的
- 回答漏掉的檔案。 我請它以只讀方式,把 notes 資料夾的檔案列表做成表格給我。整理好的檔案有 3 個(週會會議記錄·臨時會議會議記錄·週迴顧)。可是表格裡漏掉了臨時會議會議記錄,反而放進了空檔案
.gitkeep。- 要做的事:請自己數一數確認的範圍。
詳細說明(點選展開)
實際用的命令是這樣的。
cd ~/hello-ai-practice/organizer
agy -p "列出 notes 資料夾的檔案,並用一行告訴我每個檔案是用哪個模板(templates 裡的哪一個)寫的。不要修改檔案。回答要簡短,只用表格。不要用 shell 命令,只讀取檔案。" --mode accept-edits結果:agy -p 輸出(我電腦裡的路徑換成了 ~)
| Claude Code | Codex | Antigravity | |
|---|---|---|---|
| 執行一次 | claude -p | codex exec | agy -p |
| 預設寫檔案 | 需要許可 | 只讀 | 工作資料夾內自動(文件) |
| 被攔住時 | 拒絕 | 暫停 | 悄悄拒絕,退出碼 0 |
出處:這本指南的整理(各個工具的終端章節和實踐)
理解檢查
agy -p 以成功(退出碼 0)結束,卻沒有結果檔案。按這份指南的經驗,先做什麼?
繼續對話和用量
終端裡的對話記錄是按執行時所在的資料夾分開的。[14] 用 agy -c 可以直接接上那個資料夾的最後一次對話,也可以用 /resume 選擇後接著做。[15] /rewind(或 /undo)會把對話退回到前面的訊息(第4章)。檔案會不會也跟著退回,官方文件裡沒有寫,所以檔案請相信 Git 的記錄。
用量用 /usage 檢視。[16]
理解檢查
在 agy 裡,直接接著這個資料夾裡的最後一次對話,怎麼做?
親自試一試
- 確認官方文件的安裝命令和上面的命令一樣之後再安裝(已經有的話,執行
agy --version)。 - 在整理工具資料夾裡開啟一次互動式
agy,被問到是否信任資料夾時回答。 - 執行上面的只讀
agy -p,把表裡的檔案數和 notes 資料夾對著數一數。 - 如果結果是空的,讀 stderr 裡的拒絕提示,確認是什麼被攔住了。
連續任務:第7章會整理費用·資料·安全,並決定怎麼搭配使用三個工具。
整理
agy是互動式,agy -p是執行一次就結束。對話記錄按資料夾分開。- 在
-p下,需要許可的事會被悄悄拒絕,退出碼是 0。要親自確認結果檔案。 - 在沒有信任的資料夾裡,檔案操作也可能被攔住。把資料夾登記為信任,或者用
--mode accept-edits。 - 「不要用 shell 命令」這一句話,減少了因拒絕而停下來的情況。回答的範圍要自己數。
術語整理
| 術語 | 中文名稱 | 一句話解釋 |
|---|---|---|
| Headless | 無介面模式 | 不開啟對話介面,執行一次的方式 |
| Soft-deny | 軟拒絕 | 不中斷執行,只悄悄拒絕那個動作 |
| Workspace trust | 工作區信任 | 把這個資料夾登記為信任的步驟 |
| Exit code | 退出碼 | 程式結束時留下的成功·失敗編號 |
這一章讀完了嗎?
學習記錄只儲存在這個瀏覽器中。整體進度可以在 全部目錄中檢視。
參考資料(16 則)
這一章是根據 2026 年 11 月 1 日確認的 Antigravity 官方文件,以及在 macOS 上執行
agy1.4.12 的結果寫的。這本指南是在另一個實踐用的 AI 工具裡呼叫並運行了agy。官方 FAQ 說個人方案不支援這種用法(第7章)。 ↩︎Antigravity 官方文件,《Get started》。"curl -fsSL antigravity.google | bash" antigravity.google (確認日期 2026-11-01) ↩︎
Antigravity 官方文件,《Get started》。"|
agy| Launches the interactive TUI in the current directory. |" antigravity.google (確認日期 2026-11-01) ↩︎Antigravity 官方文件,《Authenticate》。"If a valid token profile is found, the CLI authenticates your session silently without opening a browser." antigravity.google (確認日期 2026-11-01) ↩︎
Antigravity 官方文件,《Get started》。"Workspace trust: Confirm that you trust the repository directory before the agent begins file indexing." antigravity.google (確認日期 2026-11-01) ↩︎
Antigravity 官方文件,《Choose an execution mode》。"Press Shift + Tab inside the prompt box to cycle through the active sequence:
default>accept-edits>auto>plan>default." antigravity.google (確認日期 2026-11-01) ↩︎Antigravity 官方文件,《Choose an execution mode》。"|
default| Pauses for interactive diff review before modifying or creating files, and asks before running terminal commands. | Standard development, reviewing sensitive code changes, and careful refactoring. |" / "|accept-edits| Automatically approves file creations and edits inside your workspace, but still asks before running terminal commands. | Rapid prototyping, iterating on trusted code, and reducing file-edit interruptions. |" antigravity.google (確認日期 2026-11-01) ↩︎Antigravity 官方文件,《Headless mode》。"Headless mode (also called print mode) sends a single prompt to the agent, streams or returns the response, and exits." / "There is no interactive prompt in headless mode, so tools that would normally ask for confirmation are handled by policy." antigravity.google (確認日期 2026-11-01) ↩︎
Antigravity 官方文件,《Headless mode》。"Diagnostics—errors, authentication prompts, progress, and permission notices—go to
stderr." antigravity.google (確認日期 2026-11-01) ↩︎Antigravity 官方文件,《Headless mode》。"Reading and writing files inside your active workspace is auto-allowed; actions such as shell commands default to Ask and are soft-denied in headless mode unless you grant them." antigravity.google (確認日期 2026-11-01) ↩︎
Antigravity 官方文件,《Headless mode》。"A tool that requires approval it can’t obtain is soft-denied: the run continues, exits
0, and prints a notice tostderrnaming the tool and how to allow it." antigravity.google (確認日期 2026-11-01) ↩︎Antigravity 官方文件,《CLI commands》。"|
trustedWorkspaces| string[] |[]| Folders you chose to trust when the CLI asked. The CLI adds entries for you. |" antigravity.google (確認日期 2026-11-01) ↩︎Antigravity 官方文件,《Headless mode》。"Warning:
--dangerously-skip-permissionsapproves all tool calls, including file writes and command execution. Prefer scopedpermissions.allowrules unless you fully trust the prompt and environment." antigravity.google (確認日期 2026-11-01) ↩︎Antigravity 官方文件,《Managing conversations》。"When you launch
agyfrom a specific directory, the agent only displays and resumes sessions associated with that specific local repository or subdirectory." antigravity.google (確認日期 2026-11-01) ↩︎Antigravity 官方文件,《Managing conversations》。"Antigravity CLI supports both an interactive Session Picker TUI overlay and direct command-line flags (
agy -c/agy --continue) to resume threads instantly based on your active workspace." antigravity.google (確認日期 2026-11-01) ↩︎Antigravity 官方文件,《Model quotas (/usage)》。"Antigravity CLI provides the
/usagecommand (alias/quota) to help you monitor your resource consumption." antigravity.google (確認日期 2026-11-01) ↩︎