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 install 只需要 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 句话涵盖：会话内容、关键成果以及值得记住的文件/决策。以建议的重要性等级（琐碎/轻量/中等/重要/重量级）结束。

3. 将记忆笔记保存到用户指定的位置。

提示

• --prompt handoff 和 --prompt memory 模板是第一版草稿。请随意根据用户需求调整输出格式——有价值的是摘要数据，而不是模板文本。
• 当你需要完整会话记录作为上下文时（例如复杂多步骤工作），使用 --full。不使用 --full 时，摘要是紧凑的，可能会省略细节。
• Claude recap、Codex compaction 以及 BotBandit memory/compaction 事件会作为 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 来缩小检查范围。