ctxrs/ctx

ctx 代理歷史搜尋

當您需要參考先前的編碼代理會話時，請使用 ctx。那些 對話記錄可能包含使用者意圖、決策、先前的工作時程表、過去的嘗試， 以及哪些方法有效或失敗。

此技能有兩種使用模式：

• 工作前的檢索，當先前的會話可能包含影響當前任務的決策、 命令、失敗或引用時；
• 歷史研究報告，當使用者要求代理或唯讀子代理 研究跨越多個先前的本機代理會話的歷史主題時。

先決條件

• 需要已安裝並設定好 ctx CLI。如果缺少它，且 當前任務適合安裝工具，請使用以下指令安裝：

  curl -fsSL https://ctx.rs/install | sh
  

• 首次設定可能需要時間，因為 ctx 正在索引過去的會話。如果需要，可以讓它在 背景或 tmux 中執行，或等待它完成。

• 如果 ctx 仍然無法使用，請告知使用者本機歷史搜尋無法使用，並且不要 編造結果。

工作流程

1. 從冷啟動脈絡開始時，先確認 ctx 已就緒：

   ctx status
   ctx sources
   

   僅在腳本需要確切欄位時，才使用 ctx status --format json 或 ctx sources --format json。

2. 首先使用一般語言進行搜尋。在需要時加入術語或篩選器：

   ctx search "<query>"
   ctx search "<query>" --refresh off
   ctx search "<query>" --provider codex
   ctx search "<query>" --workspace <workspace>
   ctx search "<query>" --file <path>
   ctx search "<query>" --since 30d
   ctx search "<query>" --term "<related term>" --term "<error text>"
   ctx search "<query>" --session <ctx-session-id>
   ctx search "<query>" --verbose
   

   代理閱讀時，請使用預設的文字輸出。除非要將輸出傳遞給 jq 或一個腳本， 或需要確切的機器可讀取欄位，否則不要為搜尋或顯示加入 --format json。 JSON 輸出體積大得多，且可能迅速消耗脈絡視窗。

   當提示要求跨越多個會話的主題歷史或報告時，請執行數次 ctx search 查詢，使用不同的措辭和篩選器來尋找有希望的會話。當某個會話看起來 相關且需要來自該會話的密集事件層級匹配時，請使用限定的 ctx search "<query>" --session <ctx-session-id>。

   預設搜尋會回傳主要代理會話，以便人類意圖和決策 保持顯著。當實作細節、程式碼審查註記、測試輸出或來自子代理會話的 失敗追蹤可能很重要時，請使用 --include-subagents。

   當需要完整的 ctx ID、提供者 ID、引用和 可複製的後續命令，但不需要切換到 JSON 時，請使用 --verbose。

   您可以將會話對話記錄寫入一個暫存檔，檢查檔案大小， 然後讀取相關部分：

   ctx show session <ctx-session-id> --format markdown --out /tmp/ctx-session.md
   wc -c /tmp/ctx-session.md
   

   在 Codex 中，當 CODEX_THREAD_ID 可用時，ctx 預設會排除當前的活動會話樹， 因此當前的提示和子代理不會主導歷史檢索。僅在 活動會話樹是目標時，才使用 --include-current-session。

3. 在依賴相關結果之前，先檢查它們：

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

4. 當來源身份或恢復提示很重要時，請定位原始提供者材料。provider_session_id 是 Codex 的恢復 UUID：

   ctx locate event <ctx-event-id>
   ctx locate session <ctx-session-id>
   

5. 當您、人類或其他代理需要一個檔案時，請撰寫相關會話的對話記錄：

   ctx show session <ctx-session-id> --format markdown --out <output-path>
   

當搜尋需要縮小範圍時

在得出結論之前，請改變查詢並使用搜尋篩選器。有用的 後續步驟包括密集事件搜尋、限定會話範圍的搜尋，以及來源位置檢查：

ctx search "<query variant>" --events --refresh off
ctx search "<query>" --session <ctx-session-id> --refresh off
ctx search "<query>" --include-subagents --refresh off
ctx show event <ctx-event-id> --window 5
ctx show session <ctx-session-id>
ctx locate event <ctx-event-id>
ctx locate session <ctx-session-id>

搜尋結果視窗是有上限的。請不要根據回傳的命中數量來聲稱確切的語料庫範圍計數或 完整的稽核。如果無法透過搜尋、顯示和定位證據來支持所要求的結論， 請說明此限制，並改為報告所檢索到的最有力證據。

對於進階查詢或完整的確定性事件列舉，請使用 ctx list events。在使用之前，請閱讀完整的篩選器、範圍、游標和輸出文件：

ctx docs show event-queries

歷史研究報告

當被要求研究一個歷史主題時，請保持唯讀，除非使用者同時要求 編輯。代理負責撰寫報告；ctx 僅檢索本機來源 材料。

1. 如果提示不明確，請重新說明主題、範圍和期望的長度。 預設偏好簡潔的報告；當使用者要求時間順序、 替代方案或詳細證據時，使用較長的報告。

2. 執行數次有針對性的搜尋。在使用者措辭、檔案或 模組名稱、錯誤文字、命令、分支名稱和決策術語之間變化查詢術語。從 ctx search "<topic>" 開始，然後使用 --term 擴展或使用 --workspace、--provider、--file、--since 或 --session <ctx-session-id> 縮小範圍。 當審查、實作嘗試、測試輸出或失敗追蹤很可能存在於委託的會話中時，請使用 --include-subagents。當報告必須不更新本機 ctx 索引時，請加入 --refresh off。

3. 在得出結論之前，檢查重點來源。偏好使用 ctx show event 來查看命中結果及其附近的輪次，而當整個會話的 脈絡很重要時，使用 ctx show session：

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

   僅當預設輸出遺漏了必要的證據時，才使用完整或日誌模式。

4. 比較跨會話的證據。記錄一致性、衝突、過時的結果， 以及搜尋未找到證據的缺口。

5. 將報告產出為代理的綜合摘要，並附上引用。

簡潔報告的結構：

• 答案或發現；
• 最有力的支援 ctx ID；
• 重要的注意事項或缺口；
• 選擇性的下一步搜尋或驗證步驟。

長篇報告的結構：

• 問題與範圍；
• 搜尋方法，包括關鍵查詢和篩選器；
• 發現或時間順序；
• 證據表格，包含提供者、ctx 會話 ID、ctx 事件 ID（如果可用），以及 每個來源的重要性的原因；
• 衝突、缺口和建議的後續行動。

引用規則

• 當 ctx 材料影響您的回答或實作時，請引用它。
• 包含提供者、ctx 會話 ID、ctx 事件 ID（如果可用）、提供者會話 ID（如果可用）。
• 如果您綜合了多個片段，請將結論標記為您的綜合，並引用支援的片段。
• 如果引用的某個事件或會話不存在於當前的 Core 世代中，請說明 這種情況，並考慮是否應進行明確的 ctx import。

安全規則

• 代理閱讀時，偏好文字輸出。僅在腳本、jq 或 確切欄位提取時使用 JSON，並保持 JSON 輸出小巧。
• 除非引用的文字明確陳述了某項決策，否則不要說 ctx 推斷出了該決策。
• 不要陳述 ctx 撰寫了模型分析。
• 不要將原始對話記錄、大型 JSON 負載、機密、令牌或私有路徑 貼到面向使用者的報告中。總結已審查的證據，並僅引用支援某項主張所需的 簡短摘錄。
• 除非使用者明確要求分享已審查的摘錄，否則將 ~/.ctx、提供者對話記錄路徑和 JSON 輸出視為 私有本機歷史。