知識擷取
自動使用
在任何倉庫任務的最終回應之前,如果檔案已變更、測試已執行,或做出了決定/發現/後續事項,請為當前工作階段/工作流程建立或更新恰好一個活動中的 session 記錄。請在驗證之後、請求清理待辦事項或批准之前執行此操作。
不要僅因為技能被再次呼叫就建立一個全新的記錄。如果已知此工作流程的活動記錄路徑,請更新該檔案。否則,讀取 .ai/raw/active-session.json 作為候選的活動指標。如果不存在可靠的活動記錄,或工作流程明顯已變更,請建立一個新的原始記錄並取代該指標。
為後續使用記錄足夠的當前任務細節。僅讀取/更新當前工作流程的活動記錄;在 v0.2 版本中,請勿讀取、更新、去重、合併、同步、提交、發布或推廣不相關的記錄。
僅僅因為輔助程式寫入了檔案,並不代表記錄已完成。不要將已知事實的章節留空填寫 Not captured.,特別是「使用者請求」、「變更與證據」、「決定與發現」以及「開放性問題與後續步驟」。
在更新活動記錄時,請寫入整個記錄,使其呈現為當前工作流程步驟完成後應有的狀態。請勿僅附加增量備註。使用當前的任務上下文、可見檔案、差異、測試、命令結果和交接文字作為證據;如果連續性不明確,請建立一個新記錄,而不是憑空發明遺失的上下文。
使記錄與當前實際情況保持一致,而不是與每一個中間想法保持一致。如果先前的決定已更改,且相關工作也隨之更改,請記錄最終/當前的決定和證據。僅在它能夠解釋已實作的程式碼、回滾、未解決的風險或開放性問題時,才保留被取代的決定;請省略純粹理論上已被放棄的選項。
將記錄儲存為 .ai/raw/<類型資料夾>/YYYY-MM-DDTHH-mm-ssZ--<類型>--<主題短語>.md。如果確切的檔案名稱已存在,請在 .md 之前附加 --2、--3,以此類推。
類型:session -> sessions,discussion -> discussions,investigation -> investigations,decision -> decisions,handoff -> handoffs。
對於 session 記錄,維護 .ai/raw/active-session.json 作為指向活動工作流程記錄的本地指標。請勿在每次最終回應後清除它;它支援恢復、壓縮和交接。當新的工作流程記錄開始時,替換它。
記錄
將 /capture 視為建立/更新當前工作階段的記錄。當 <type> 為 session、discussion、investigation、decision 或 handoff 時,將 /capture <type> 視為該類型的記錄。
在上下文壓縮、壓縮或交接之前,如果重要的成果或決定尚未被記錄,請先進行記錄。
如果 Node 可用,這個無依賴的輔助程式可以建立第一個記錄、使用 --update <path> 取代已知的活動記錄,或使用 --update-active 取代指向的記錄。透過 --stdin 傳遞豐富的結構化章節細節,或直接撰寫 Markdown。預設情況下,輔助程式會阻止僅包含標題/摘要的記錄,因為這會遺失有用的工作階段知識。
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --summary "Fixed expired refresh token behavior" --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update .ai/raw/sessions/2026-07-04T18-22-10Z--session--auth-refresh-token-fix.md --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update-active --stdin
在 stdin 上提供來自 references/raw-capture-schema.md 的 Markdown 標題。如果 Node 或 shell 執行不可用,請直接建立或更新 Markdown。
對於活動工作階段記錄,請使用此順序:
- 如果當前上下文中已知活動路徑,則更新該路徑。
- 否則,讀取
.ai/raw/active-session.json作為候選指標。 - 如果指標和執行環境都暴露了一個
agent_session_id且它們匹配,則更新它。 - 如果工作階段 ID 不同、缺失或不可用,但使用者請求或交接明確地持續同一工作流程,則更新它並重新整理指標。
- 否則,建立一個新記錄並取代指標。切勿透過猜測最新檔案名稱來選擇。
護欄
- 記錄有用的原始細節,但避免記錄完整對話、大型日誌和整個檔案。
- 將已變更的檔案、測試、命令和證據置於「變更與證據」下;當多個檔案變更時,按目的對檔案進行分組。
- 僅包含罕見、不明顯或與決策相關的命令/結果;省略那些日後無關緊要的常規命令。
- 僅為了使活動記錄準確有用而對其進行重組;不要捏造事實,或默默地將過時的理論當作仍然真實的內容保留。
- 將
agent_session_id視為一個有用的護欄,而不是工作流程的定義。一個新的代理工作階段可以繼續同一個工作流程。 - 僅在執行環境明確暴露了一個穩定的當前工作階段、對話、執行緒或執行 ID 時,才使用
--agent-session-id。如果不可用,則省略它。切勿偽造一個。 - 排除機密資訊、憑證、API 金鑰、私鑰、客戶私人資料和不相關的個人記憶。
- 如果存在敏感內容,請勿建立記錄;先進行抽象總結。
- 原始/本地狀態來自
.ai/raw/路徑和技能策略,而非來自每個記錄的工作流程欄位。 - 將 Node 輔助程式視為可選項。直接建立檔案同樣有效。
儲存後,報告路徑、類型以及是建立還是更新。如果輔助程式阻止了記錄,請報告警告並且不要儲存原始內容。
參考資料
- 僅在手動撰寫或更改結構時閱讀
references/raw-capture-schema.md。 - 在不確定更新後的工作流程記錄應如何呈現時,閱讀
references/active-session-example.md。 - 僅在將此技能改編給其他代理使用時,閱讀
references/agent-portability.md。