Communitygithub.com

wellwelwel/lagune

🌊 Lagune 是您的安全副駕駛,協助您在建置時確保安全;也是您的藍隊夥伴,無論您是開發者與否,都能在審計時提供協助。

lagune 是什麼?

這項技能模擬 Lagune 的一系列安全命令(charter、detect、plan、harden、verify),以確保模擬過程真實可驗證,而非僅是華麗的展示。它解決了一個常見問題:AI 代理可能會憑空想像命令的輸出,導致產生不可靠的結果,從而浪費使用者的時間與信任。此技能強制執行四項嚴格規則:在 `./temp` 目錄中執行所有操作,以保持使用者工作區的可見性;使用 fenced code block 完整呈現提示與回應,避免工具呼叫的截斷預覽;嚴格遵循 Lagune 各階段的規格文件(`spec/commands/lagune.<phase>.md`),包括其中的確認暫停點;以及透過實際執行上遊階段來建置工作鏈,而非手動撰寫預期的下游產出物。支援的模擬平台包括 Claude Code、Cursor 及 Codex 等 AI Agent 環境,確保在任何平台上都能以一致且可靠的方式進行安全稽核。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add wellwelwel/lagune

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

模擬 Lagune 命令

此技能之所以存在,是因為模擬一個命令很容易出錯,導致浪費使用者的時間與信任。過去的困難經驗歸納出四項不容妥協的規則與一個方法。請嚴格遵守。

每當使用者要求「模擬」、「展示」、「實際操作」、「執行」或「親眼所見」任何 /lagune.* 命令(charter、detect、plan、harden、verify),或是想在正式使用前預覽命令的行為時,請使用此技能。

開始之前(必要條件)

在以下兩點都確定之前,請不要開始模擬、建立情境或複製 fixture,並且必須依序處理:

  1. 使用者必須告訴您要模擬哪個 Lagune 命令。 這是必須的,絕不能猜測或自行選擇。如果使用者沒有指定命令(charter、detect、plan、harden 或 verify),請先詢問,再做任何其他事情。如果使用者指定了多個命令,請確認您要執行的順序。
  2. 然後,列出可用的 fixture,並讓使用者選擇。 一旦確定了命令,請將可用的 fixture(來自 .claude/skills/simulate/fixtures/)以編號列表的方式呈現,每個 fixture 附上一行說明其情境,並要求使用者透過編號選擇。不要默默地預設使用某個 fixture。如果只有一個 fixture,仍然要呈現並在使用前獲得使用者的確認。如果沒有任何 fixture 符合該命令的需求,請告知使用者,並提議新增一個 fixture(請參閱 fixture 章節)。

只有當命令被指定且 fixture 被選定後,才能繼續進行下面的規則和方法。

為什麼需要這個技能(請先閱讀)

Lagune 命令不是一個獨立的程式。它是一份指令檔(spec/commands/lagune.<phase>.md,以技能形式提供給代理讀取),告訴 AI 代理如何執行安全工作的某個階段。「執行命令」意味著一個代理遵循那些指令。並沒有一個可以獨立於代理之外、產生確定結果的二進位檔。因此,「模擬」就是讓代理在實際的情境中真正執行命令的步驟,同時展示其工作過程。

需要避免的失敗模式是:敘述您想像命令會輸出的內容,將其格式化得像終端機的輸出,然後呈現為命令實際執行後的結果。那是表演。使用者無法分辨虛構的輸出與真實的輸出,而且他們(理所當然地)會稱其為一場鬧劇。以下所有設計都是為了讓模擬真實且可由使用者驗證,而不是一場表演。

四項硬性規則

規則 1:在 ./temp 下執行情境

在 ./temp(位於儲存庫根目錄)內建置模擬所需的一切(fixture、.lagune/memory/ 中各階段產生的工件、任何輸入),切勿在系統的 /tmp 中進行。

  • /tmp 對使用者是不可見的:他們無法在編輯器中開啟這些檔案,因此您在該處所做的一切都變成了「相信我吧」。./temp 位於使用者的工作區,可以開啟和檢查。
  • ./temp 已被 .gitignore 忽略,因此模擬永遠不會污染提交記錄。
  • 當使用者完成後,清理 ./temp,或者留給他們檢查,但必須先詢問。

Fixtures:每次模擬都從一個 fixture 開始

中立範例專案與此技能一同發布,每個專案位於 .claude/skills/simulate/fixtures/<name>/ 目錄下。選擇一個其情境符合命令需求的 fixture,或者新增一個(請參閱下文)。每個 fixture 都是一個小型、真實的專案,故意包含健全且脆弱的程式碼,並以中立配對的形式存在,這樣命令就必須分析程式碼,而不是讀取標籤。

可用的 fixtures:

  • image-upload-service:一個小型 ESM HTTP 服務,接受圖片上傳、從遠端 URL 匯入圖片,並提供圖片回傳服務。
  • template-toolkit:一個可發布的 ESM npm 套件(一個函式庫加上一個 tmpl CLI),用於渲染範本和解析文字。

始終透過將一個 fixture 原始複製到 ./temp 來開始模擬。 如果 ./temp 已存在且不為空,請先清除它,以便每次執行都從乾淨狀態開始(將 <name> 替換為您選擇的 fixture):

rm -rf ./temp && mkdir -p ./temp
cp -R .claude/skills/simulate/fixtures/<name>/. ./temp/

然後,透過依照規則 4 實際執行上游階段,在 ./temp 之上建置工作鏈,這樣命令讀取的 .lagune/memory/*.md 工件是由其本身的階段產生,而不是手寫的。依照規則 3 嚴格遵循其規格,根據規格對 ./temp 執行命令的步驟,並依照規則 2 顯示每個步驟的輸出。

若要新增 fixture,請建立 .claude/skills/simulate/fixtures/<new-name>/ 作為一個小型、真實的專案,包含自己的 package.json,以中立配對的方式保留健全且脆弱的程式碼,不要添加任何會洩露資訊的註解或名稱,並在上方列出它。當某個命令需要的素材是當前 fixtures 未涵蓋時(例如不同的語言或技術堆疊、秘密處理、認證、資料庫等),就新增一個。

規則 2:在聊天訊息中以 fenced code block 呈現提示與回應

這是一條花了最久時間才學會的規則。當您執行一個工具(Bash、Read)時,使用者的介面會顯示該工具的 IN 和 OUT 的截斷預覽。您無法控制顯示多少內容,而且通常會被截斷。如果支持某個主張的證據只存在於工具呼叫的輸出中,使用者看不到它,而且您描述它的任何句子看起來都像是虛構的。

因此:

  • 執行工具後,將相關的原始輸出複製到一個 fenced code block(三個反引號)中,放在您的一般聊天訊息中。這個 fenced block 會在每個介面中完整且一致地呈現。這就是使用者所指的「黃字」:一個 Markdown code block。
  • 命令的提示和互動(/lagune.<phase> 在執行時顯示的內容:逐步說明、範圍決定、判定結果)也放在一個 fenced code block 中,格式如同轉錄稿。
  • 永遠不要寫「上面的輸出顯示了 X」並指向一個工具呼叫。請指向您貼上的 fenced block,使用者可以完整閱讀它。
  • 當您轉錄稿中的數字或行來自實際執行時,它必須與您貼上的原始輸出相符。如果您撰寫的轉錄稿行沒有原始輸出作為依據,那麼您就是在虛構,請立即停止。

一個可靠的模式:執行命令,將原始輸出重新導向到 ./temp 下的一個檔案(例如 ./temp/run.log),然後 Read 那個檔案(Read 的結果會完整顯示給您看),並將其內容貼到一個 fenced block 中。使用者也可以開啟 ./temp/run.log 來驗證。

邊做邊顯示,而不是在最後一批顯示。 觸發點是每個步驟:一旦某個步驟產生了使用者應該看到的內容(它讀取的輸入、它的轉錄稿、它寫入的工件),就在同一個訊息中將其貼到 fenced block 中,然後再進行下一個步驟。如果您即將開始下一個階段或修正,而上一個步驟的輸出尚未顯示在畫面上,請先停下來並貼上它。如果使用者必須提醒您顯示某個命令的輸出,那麼規則就已經被違反了。

規則 3:您就是命令,因此請嚴格遵循其規格

「執行命令」就是您逐步執行 spec/commands/lagune.<phase>.md,而不是以您自己的方式執行該階段,然後稱之為命令。

  • 首先開啟該規格,並將其視為唯一的真理來源。 依序遵循其步驟。不要憑記憶或此技能的摘要來執行該階段。
  • 實際執行規格所設定的每一個確認暫停。 harden 必須在編輯任何程式碼之前確認,完整的 detect 掃描必須確認,因為它會消耗大量 token。在轉錄稿區塊中呈現規格要求呈現的內容,然後等待。在獲得確認之前,切勿編輯程式碼或執行有門檻的步驟。
  • 按照規格步驟的方式來決定範圍、判定結果、修正、優先事項和發現項目,並以實際情境為依據。如果您無法指出規格中的哪個步驟證明了某行輸出的合理性,那麼您就是在扮演自己,所以請停止並遵循規格。

規則 4:每個階段的輸入必須來自執行上一個階段,而非來自您

工作鏈是 charter → detect → plan → harden → verify,每個階段讀取前一個階段所寫入的內容。手動撰寫一個帶有您預期答案的下游工件(例如一個 harden.md,其中準確記錄了您希望 verify 確認或捕捉的內容)就是一種失敗:下游階段將根據您的預測而非現實進行測試,因此它會錯過您所錯過的一切。

  • 透過執行其階段來產生每一個上游工件,在其自己的規格下,並依照規則 2 顯示。若要展示 verify,請執行 detect(讀取程式碼),然後執行 plan(讀取 detect.md),然後執行 harden(讀取 plan.md,編輯程式碼)。即使使用者從中段開始,也請以這種方式、依序建置缺失的工件。
  • 讓工件呈現實際執行所產生的內容,包括其中的空白:例如一個 Partial、一個 Blocked、一個您未曾預見的發現。一個過於乾淨的工件就是此規則被違反的跡象。
  • 刻意偏離的情境是可以的(例如 harden 套用了所有修正,然後程式碼被還原,這樣 verify 就必須捕捉到這個變動),但請以明顯的方式引入這個偏離(在顯示的工具呼叫中進行還原,保留真實的工件),切勿透過手動撰寫一個從未實際執行過的記錄。

方法,逐步說明

每個階段讀取前一個階段的內容,並寫入表格中所列的內容。請熟悉這個工作鏈,不要打破它:

階段讀取內容寫入內容
charter專案上下文.lagune/memory/charter.md
detect程式碼.lagune/memory/detect.md
plan僅 detect.md,切勿讀取程式碼.lagune/memory/plan.md
harden僅 plan.md 加上 charter,並且編輯使用者的程式碼.lagune/memory/harden.md
verifyharden.md 和程式碼,將記錄與現實進行比對,不修改任何程式碼harden.md 區塊上的 Verdict/Reason

接著,針對您要模擬的命令:

  1. 將 fixture 原始複製到 ./temp(規則 1)。
  2. 透過依序執行每個上游階段來建置工作鏈,針對 ./temp 執行(規則 4)。
  3. 在其 spec/commands/lagune.<phase>.md 下,嚴格遵循規則 3 執行目標階段。
  4. 在進行過程中,將每個輸入、轉錄稿和工件放入 fenced block 中顯示(規則 2)。將每個輸出工件寫入為真實檔案,然後 Read 並顯示它。

呈現任何內容前的誠實檢查

  • 這是否真的執行過,還是我正在輸入我認為會發生的情況?
  • 每一行轉錄稿是否有我貼上的原始輸出作為依據,或者是一個使用者可以開啟的 ./temp 檔案,而不是一個被截斷的工具呼叫?(規則 2)
  • 我是否已經貼上了到目前為止每個步驟的輸出,這樣使用者永遠不必主動詢問?(規則 2)
  • 我是否遵循了每個階段的規格,包括確認暫停,而不是以我自己的想法行動?(規則 3)
  • 每個上游工件是否來自於執行其階段,而不是我為了得到想要的結果而手寫的?(規則 4)
  • 情境是否在 ./temp 下,而不是隱藏在 /tmp 中?(規則 1)

如果任何一個答案為「否」,請在送出前修正。使用者寧願看到真實、樸實的輸出,也不願看到精心修飾的虛構產物。

相關技能