你的代理從沒看到的那條警告：指令預算、隱形的 hook，以及一個吃掉自己產出的同步

在真實專案上跑 Coograph 的一天：還沒寫一行程式碼就先載入 120,000 個 token 的指令、模型從未收到的護欄警告，以及一次同步把它自己的 retro 提議的修正給覆蓋掉了。我們找到了什麼、怎麼證明的，以及 1.8.5 帶來了什麼。

我們發布的東西，大多來自把 Coograph 跑在自己的專案上，然後看著它出錯。這次的發布特別集中：一個針對某個 monorepo 提出的 issue，在一天之內變成了四個發現，其中兩個屬於那種只有直接問模型「你看到了什麼」才會發現的問題。

第一行程式碼之前的 120,000 個 token

這個 issue 附了數字。一個大約十天前裝上 Coograph 的 monorepo（一個 web 應用、一個原生應用、一個共用核心和一組雲端函式），在一般的 web 任務上，代理還沒讀任何程式碼，就先載入了約 120,000 個 token 的指令檔案。其中一份工作區地圖，也就是告訴代理 web 應用如何組織的那個檔案，光它自己就有 91,645 個 token。

沒有人故意寫出一個 90,000 token 的檔案。它是長出來的。每次改動都追加一個帶日期的段落（「登入，見 openspec 2026-09-01」），於是一個畫面的目前行為散落在許多段落裡，代理得全部讀完。在一條 web 與原生對等的規則下，一個功能會在各份地圖裡產生三到五個段落。硬性規則被複製進三個根檔案，付了三次錢。還有一個 6,400 字元的表格儲存格，讓格式化工具把一張寬表的每一列都補齊：那個 363 KB 的檔案裡，有 228 KB 是空白。

Retro 是 Coograph 用來衡量護欄成效的迴圈，本該抓到這個問題。它沒有，因為它量錯了檔案。它的 token 預算只計算根檔案和 .github/instructions/，其他一概不算：不算工作區地圖，也不算任何透過 @ import 引入的內容。那份 91,000 token 的地圖，對唯一一個職責就是發現它的工具來說，是隱形的。

所以 1.8.0 給了指令檔案一個形狀和一把尺。分成三層：永遠載入的根檔案（合計 9,000 個 token，會跟進 import）、每個工作區一個簡短的路由檔（2,000），以及每個產品領域一份功能文件（8,000），只在代理需要時才讀。Gotcha 有自己的檔案，從不預先載入；當代理編輯某個 gotcha 路徑下的檔案，或執行它所針對的指令時，一個 hook 會在那一刻顯示對應條目。layout.py --budget 會量測所有這些，而 CI 檢查會讓一個改動了功能文件所涵蓋程式碼、卻沒碰該文件的 pull request 失敗。

對於已經失控的檔案，/coograph-docs-restructure 會寫出一份 OpenSpec，按來源列出舊地圖裡的每一條事實，然後每個代理遷移一個領域，並逐條對照程式碼檢查。在那個 monorepo 上，它把永遠載入的集合從 30,745 降到 7,914 個 token，把那份 91,645 token 的 web 地圖降到 591；現在沒有任何工作區地圖超過 700。Coograph 自己附帶的範本，現在在 9,000 token 的預算中量到 5,510；以前，它自己的三個根檔案各自完整重複了同一套硬性規則。

沒人讀到的警告

做 gotcha hook 時，得先確認 hook 是怎麼把文字送到模型面前的，而這個確認挖出了一個令人不安的發現。

Coograph 有四個警告 hook。一個在編輯超出已核准改動範圍時警告，一個在沒有提案就編輯第二個原始檔時警告，一個在新增依賴時警告，一個在沒經過審查就提交時警告。四個做的事都一樣：把訊息印到 stderr，然後以代碼 1 結束。訊息出現在對話紀錄裡，所以我們以為它有效。

我們用唯一能下定論的方式測試。我們在一個用完即丟的專案裡啟動一個巢狀工作階段，讓它做一次 scope hook 一定會警告的編輯，然後要求模型在沒有任何其他工具可用的情況下，引用它在那次編輯之後收到的、所有含有「scope」或「OpenSpec」字樣的文字。它的回答是：沒有。hook 觸發了；對話紀錄裡有那段文字，標示為一個非阻擋性的 hook 錯誤。模型從來沒收到它。

同一個下午寫的 gotcha hook 走的是另一個管道，additionalContext，而在同一次探測裡，模型一字不差地引用了它的條目，包括一個它不可能猜到的 token。所以修法很明確。四個警告 hook 現在全都透過 additionalContext（給模型）和 systemMessage（給終端機）發聲，並以 0 結束。我們對修好的 hook 重跑探測：模型逐字引用了 scope 警告。

那次重跑還抓到一件事。第一次嘗試又失敗了，而對話紀錄說明了原因：已安裝外掛自己的那份 hook，還是舊版，搶在專案那份之前接下了事件。Coograph 讓每個事件只有一份 hook 副本會動作，這是對的，但這代表一個修正要等兩份副本都更新後才算生效。外掛現在從 GitHub marketplace 安裝，所以 claude plugin update 能更新到它。

一個憑空升級的護欄

隱形的警告還有一個二階代價，而這是最讓我們擔心的一個。

當證據顯示警告被忽略時，Retro 會把一條規則從警告升級為阻擋：規則觸發，沒人修，它又觸發。在那個 monorepo 上，一次 retro 正是這麼做的。它讀到「不新增依賴」規則的「5 個結果中忽略率 0.8」，就把它改成對安裝的硬性阻擋。表面上看很合理。但這五個結果，每一個都發生在一條代理從未看到的警告之後。阻擋有效；它的理由卻不存在。

所以 Retro 現在只從規則的 outcomes_since 日期開始計算結果，也就是 hook 行為最後一次改變的時間。管道修正之前的結果，描述的是沒人讀到的警告，它們再也不能把一條規則推向阻擋。在那個 monorepo 上，這條規則回到了警告，而代理現在真的看得到它，下一次 retro 會根據誠實的證據重新決定。last_changed 在單純改寫措辭時也會被設定，現在它完全不會影響證據；這個修正的初稿用的就是它，而我們的審查發現，一次只改了一句話的 retro 就會抹掉一條規則的歷史。

刪掉自己產出的同步

最後一個發現，責任在我們。合併這些改動時會跑 Coograph 的同步，把範本檔案複製到每個已註冊的專案。那天晚上，那個 monorepo 自己的提交在工作目錄裡被還原了：一次 retro 的 hook 升級、scope hook 的精準度修正、layout 檢查工具裡的一個防護選項。同步把每個範本檔案都蓋過了專案的版本，而 Retro 提議修改的正是這些檔案。這個工具在刪除它自己回饋迴圈的產出。

同步現在絕不會悄悄覆蓋本地編輯。每個它要取代的檔案，都會和它上次寫入的內容、以及 Coograph 曾經發布過的每個版本比對。兩者都不符的檔案會被保留，新的上游版本放進 .coograph/upstream/，日誌會寫 KEPT <path> (local edit)。在那個 monorepo 上，它保留了剛好那十五個真的有本地改動的檔案，其餘都更新了。這些本地改動中屬於通用性的修正，在同一個版本裡被拉回上游，所以現在每個專案都拿得到。

這個版本還有

• OpenCode 成為一等公民工具。 同步會產生一個 opencode.json，含程式碼圖伺服器和 skills 路徑。已端到端驗證：OpenCode 連上了伺服器，代理對 graph_stats 的呼叫讀到了真實的圖。我們也試過用相對於專案的路徑讓這個檔案可攜：OpenCode 在專案根目錄啟動時能連上，在子資料夾中啟動時就失敗了，所以這個檔案保留本機的絕對路徑，不應提交到儲存庫。
• 一個在嚴格鎖定的 Windows 上也活得下來的啟動器。 在開啟 Smart App Control 的機器上，uv 自己下載的 Python 可能被禁止載入，程式碼圖伺服器在啟動時就掛了。啟動指令現在把 uv 固定到系統上 3.10 或更新版本的 Python。
• OpenSpec 閘門警告現在指名規則，而不是檔案，因為在新的版面配置裡，那條規則住在 AGENTS.md，不是 CLAUDE.md。

這些沒解決的事

預算只能告訴你檔案太大；它不會告訴你哪些事實仍然正確。重構 skill 會逐條對照程式碼檢查事實，但程式碼無法確認的事實，例如某個部署步驟或某個主控台設定，會被保留並標記，而不是驗證。文件檢查是刻意做得粗略的：一份功能文件涵蓋一些路徑，這些路徑下的改動必須碰到該文件，但這完全不代表編輯是對的。還有，警告 hook 現在看得到了，也因此變得更吵；這些噪音值不值得，正是接下來幾次 retro 要量測的東西。

共通的模式

這四個發現裡有三個原因相同：某個東西運作了，留下了紀錄，卻從未被那個唯一重要的讀者看見。一個漏掉最大檔案的預算。一條寫進模型不讀的管道的警告。一次建立在那條沒人讀的警告之結果上的升級。每一次，對話紀錄看起來都沒問題。

每一次的修法，都是不再相信紀錄，而去問讀者。量測代理實際載入的檔案。問模型它收到了什麼。只計算代理有可能據以行動的證據。

這一切都在 Coograph 1.8.5 中發布。關於指令預算和 gotcha 的文件在 /zh-TW/docs/layout/，關於證據如何運作的在 /zh-TW/docs/retro/。