janole/session-bandit

先決條件

Session Bandit 是一個必須安裝在系統上的 CLI 工具。請檢查是否可用：

command -v session-bandit

如果尚未安裝，請使用以下指令進行全域安裝：

npm install -g session-bandit

如果套件尚未發佈至 npm，請從原始碼安裝：

git clone https://github.com/janole/session-bandit.git
cd session-bandit
pnpm install
pnpm -r build
npm install -g packages/cli

需要 Node.js 22+ 和 pnpm 10+（僅在從原始碼建置時需要；npm 安裝僅需要 Node.js）。

驗證安裝：

session-bandit --version

Session Bandit 的功能

Session Bandit 會將編碼代理（Claude Code、Codex、BotBandit）寫入磁碟的 JSONL 工作階段記錄建立索引。它完全離線運作——沒有 API 呼叫、沒有認證、沒有網路。預設會掃描 ~/.claude/projects/、~/.codex/sessions/ 和 ~/.botbandit/sessions/。

輸出模式

當將 Session Bandit 作為代理工具使用時，請優先使用預設的機器可讀輸出：

• list 和 search 預設輸出 JSON 行。
• extract、redact-check 和 doctor 預設輸出 JSON。
• show 預設輸出人類可讀的記錄。

僅在需要對使用者進行瀏覽或報告的人類可讀終端機檢視時，才使用 --pretty。請勿對您打算解析或用作交接或記憶筆記結構化輸入的指令輸出加上 --pretty。

指令

列出工作階段

# 列出所有工作階段，最新優先（JSON 行）
session-bandit list

# 人類可讀的表格，附帶重要性層級
session-bandit list --pretty

# 依代理或專案篩選
session-bandit list --agent codex --project botbandit

# 依實質內容/重要性排序（內容豐富的工作階段優先）
session-bandit list --sort importance

# 捨棄瑣碎的工作階段
session-bandit list --min-importance moderate

# 限制時間範圍：相對（7d、24h、2w、3m）或絕對日期
session-bandit list --since 7d
session-bandit list --since 2026-06-01 --until 2026-06-15

顯示工作階段記錄

# 完整 ID 或前綴匹配
session-bandit show 342647fa-5bf
session-bandit show 342647fa --agent claude

跨工作階段搜尋

session-bandit search "tool approval"
session-bandit search "apply_patch" --agent codex
session-bandit search "adapter" --since 3d --pretty

提取工作階段摘要（用於交接/記憶的主要功能）

# 結構化摘要（JSON）— 實質分數、檔案、指令、錯誤、關鍵回合
session-bandit extract 342647fa-5bf

# 將摘要包裝成可立即發送的綜合提示
session-bandit extract 342647fa-5bf --prompt handoff
session-bandit extract 342647fa-5bf --prompt memory

# 在摘要中包含完整記錄
session-bandit extract 342647fa-5bf --full --prompt handoff

檢查解析健康狀態

session-bandit doctor
session-bandit doctor --agent codex
session-bandit doctor --agent botbandit

發佈前檢查審查結果

# 預設輸出 JSON 報告
session-bandit redact-check 342647fa-5bf

# 人類可讀的報告，供與使用者一起審查
session-bandit redact-check 342647fa-5bf --pretty

# 更保守的預覽
session-bandit redact-check 342647fa-5bf --redact strict

匯出 Markdown 以供審查/發佈

session-bandit export-md 342647fa-5bf --out ./session.md
session-bandit export-md 342647fa-5bf --out ./session.md --report-out ./redaction-report.json
session-bandit export-md 342647fa-5bf --out ./session.md --title "Apple Watch interface"

export-md 預設使用 --redact cautious。除非使用者明確要求並接受風險，否則請勿對公開成品使用 --redact none；該模式需要 CLI 接受 --yes 參數。

發佈工作階段

當被要求發佈一個編碼工作階段時，請保持 Session Bandit 的確定性與離線特性。使用 CLI 來建立審查後的 Markdown 成品與審查報告；僅使用您的代理判斷來選擇工作階段、選擇標題/代碼、進行可選的文辭潤飾，以及向使用者報告風險。

1. 找到來源工作階段。 如果使用者提供工作階段 ID，請直接使用。否則，搜尋或列出可能的工作階段：

   session-bandit list --sort importance
   session-bandit search "the topic"
   

   當使用者縮小目標範圍時，請使用 --agent 或 --project。

2. 選擇標題、代碼和輸出路徑。 對於 GitHub Pages 風格的儲存庫，建議每個工作階段一個資料夾：

   sessions/<slug>/index.md
   sessions/<slug>/redaction-report.json
   

   保持代碼簡短、小寫且穩定。如果標題不確定，請在匯出前先向使用者提議。

3. 在寫入成品之前預覽審查結果：

   session-bandit redact-check <sessionId> --pretty
   

   報告計數和任何值得注意的風險。如果工作階段似乎包含私人客戶資料、憑證、專有輸出或異常敏感的本地上下文，請使用 --redact strict。

4. 匯出 Markdown 和報告：

   session-bandit export-md <sessionId> \
     --out sessions/<slug>/index.md \
     --report-out sessions/<slug>/redaction-report.json \
     --title "Human readable title"
   

   除非使用者明確要求並接受風險，否則請勿對公開發佈使用 --redact none。

5. 發佈前進行審查。 檢查 Markdown 與審查報告。確保摘要章節、相關工作階段、指令、工具輸出和本地路徑都合理。自動審查僅是盡力而為，並非安全保證。

6. 可選地潤飾 Markdown。 您可以在 CLI 輸出之外，新增或編輯簡短的介紹、章節標題或結語。請勿編造事實；保持記錄、摘要、出處和審查報告的完整性。

7. 在公開前先詢問。 在執行 git add、git commit、git push 或任何部署動作之前，請先總結審查風險並請求使用者明確核准，除非使用者在當前的對話回合中已給予該核准。

GitHub Pages 範本

此技能在 SKILL.md 旁邊附帶了一個預設的發佈範本，位於 templates/github-pages-default/。當使用者要求建立 GitHub Pages 儲存庫、精美的靜態網站或匯出工作階段的預設公開展示方式時，請使用它。

範本行為：

• 這是一個具有自訂佈局和 CSS 的 Jekyll/GitHub Pages 網站。
• 它預期產生的工作階段位於 sessions/<slug>/index.md。
• 它預期審查報告位於工作階段旁邊，作為 sessions/<slug>/redaction-report.json。
• 它使用 _config.yml 的預設值，以便匯出的 Session Bandit Markdown 自動獲得工作階段佈局。
• 它包含一個本地端的 .design/session-page.html 測試用檔案，用於在沒有 Jekyll 或 Pages 部署的情況下檢查佈局。
• 它是靜態且自包含的；除非使用者明確要求，否則請勿添加外部資源、追蹤器、字型或遠端腳本。

在初始化一個空的發佈儲存庫時：

cp -R <skill-directory>/templates/github-pages-default/. <target-repo>/

當儲存庫已存在時，請勿在未經詢問的情況下覆寫 _config.yml、_layouts/、assets/session.css、index.md 或 README.md。僅新增或更新 sessions/<slug>/index.md、sessions/<slug>/redaction-report.json，以及如果使用者想要手動索引，則新增或更新索引條目。

對於視覺範本的變更，建議在發佈前先在本地端檢查 templates/github-pages-default/.design/session-page.html。它特意由純 HTML 建置，因此不需要 Jekyll。

撰寫交接筆記

當被要求從先前的工作階段撰寫交接筆記時：

1. 找到工作階段。 如果使用者提供工作階段 ID，請直接使用。否則，列出最近的工作階段並選取相關的：

   session-bandit list --sort importance
   

   或搜尋一個主題：

   session-bandit search "the topic"
   

   僅在需要手動瀏覽的表格/摘錄時才添加 --pretty。

2. 使用交接提示產生摘要：

   session-bandit extract <sessionId> --prompt handoff
   

   這會輸出一個結構化摘要（實質分數、寫入的檔案、錯誤、摘要/回顧、目標、最終狀態），並包裝在一個綜合提示中，該提示告訴您要寫什麼。

3. 撰寫交接內容。 提示要求您涵蓋：目標、已完成的工作、當前狀態以及剩餘的工作。使用摘要中的結構化資料（寫入的檔案、錯誤、關鍵回合）作為事實依據。保持簡潔——返回的代理需要的是狀態，而不是完整的歷史記錄。

4. 將交接內容儲存 至使用者指定的任何位置（文件儲存庫、Markdown 檔案等）。

撰寫記憶筆記

當被要求從過去的工作階段建立記憶筆記時：

1. 找到並提取工作階段：

   session-bandit extract <sessionId> --prompt memory
   

2. 撰寫記憶筆記。 提示要求 2-4 句話，涵蓋：該工作階段的內容、主要成果，以及值得記住的檔案/決策。最後建議一個重要性層級（trivial / light / moderate / substantive / heavy）。

3. 將記憶筆記儲存 至使用者指定的任何位置。

提示

• --prompt handoff 和 --prompt memory 範本是初稿。請根據使用者的需求自由調整輸出格式——有價值的部分是摘要資料，而不是範本文案。
• 當您需要完整記錄作為上下文時（例如複雜的多步驟工作），請使用 --full。沒有 --full 時，摘要會很精簡，可能會遺漏細節。
• Claude 的回顧、Codex 的壓縮以及 BotBandit 的記憶/壓縮事件會以 summary 訊息的形式呈現，並包含在提取內容中。將它們視為有用的綜合上下文，但仍需將交接和記憶筆記奠基於摘要中的檔案、錯誤、測試和最終回合。
• 在協助公開發佈或匯出工作階段之前，請執行 session-bandit redact-check <sessionId> --pretty 並報告剩餘風險。自動審查僅是盡力而為，並非安全保證。
• 對於 Markdown 匯出，建議使用 session-bandit export-md <sessionId> --out <path> --report-out <reportPath>，然後在建議提交/發佈前檢查報告。
• Markdown 是規範的發佈成品。除非使用者特別要求 HTML，否則請勿建立基本的 HTML 記錄；高品質的 HTML 應從審查後的 Markdown 或審查過的套件產生。
• 對於新的 GitHub Pages 發佈儲存庫，建議使用綁定的 templates/github-pages-default/ 範本。除非使用者要求其他樣式，否則這是預設的公開展示方式。
• 實質分數衡量的是活動量（工具呼叫、檔案寫入、測試執行），而不是重要性。一個簡短的工作階段可能包含一個關鍵決策。請閱讀關鍵回合，而不僅僅是分數。
• 工作階段 ID 可以指定為前綴（例如使用 342647fa 代替完整的 UUID）。
• 如果感覺有問題，請執行 session-bandit doctor——它會檢查解析假設是否符合您的實際工作階段檔案，包括格式漂移、注入標記、未識別的類型和靜默跳過。使用 --agent claude、--agent codex 或 --agent botbandit 來縮小檢查範圍。