内容
<h1 align="center">会话记录</h1>
<p align="center">
跨越AI编码会话的搜索和记忆。<br/>
一个索引涵盖 <strong>Claude 代码</strong>、<strong>Codex</strong> 和 <strong>Pi</strong> — 从CLI模糊查找和恢复过去的会话，通过MCP给代理人提供对之前工作的回忆，并查看令牌的使用情况。
</p>
<p align="center">
<a href="https://github.com/nicknisi/sessions/actions/workflows/ci.yml"><img src="https://github.com/nicknisi/sessions/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://github.com/nicknisi/sessions/releases/latest"><img src="https://img.shields.io/github/v/release/nicknisi/sessions" alt="最新版本" /></a>
</p>
## 为什么
每个AI编码会话都会留下记录。Claude 代码将它们隐藏在 `~/.claude/projects/` 中，Codex 和 Pi 有自己的布局 — 而它们的内容（你尝试过的，决定过的，报错的）实际上是只可写的。
`sessions` 为所有这些建立了一个全文搜索索引，并以三种方式利用这个历史记录：
- **搜索和恢复（CLI）** — 模糊查找任意过去的会话，跨越所有三个工具，按相关性排名，并跳转回去。
- **代理人记忆（MCP）** — 代理人搜索你的历史记录，在你返回代码库时拉取一个作用域内的上下文启动器，并通过捆绑的技能回答“上周我做了什么？”
- **使用报告** — 跨越工具、模型和项目的令牌/成本仪表盘。
## 安装
### Homebrew
```sh
brew install nicknisi/formulae/sessions
```
或者，等效地：
```sh
brew tap nicknisi/formulae
brew install sessions
```
### 从源码
```sh
git clone https://github.com/nicknisi/sessions && cd sessions
bun install && bun run build
```
编译后的二进制文件位于 `dist/sessions`。从源码构建需要 [Bun](https://bun.sh)。Homebrew安装是一个独立的二进制文件 — 不需要运行时。
### 依赖
- **fzf** （可选但推荐）— 用于模糊选择。如果fzf未安装，则使用内置的编号列表选择器作为备用。可以使用 `brew install fzf` 安装。
## 快速设置
安装后，运行：
```sh
sessions setup
```
这会自动：
1. 将插件和技能复制到 `~/.local/share/sessions/plugin/`
2. 检测已安装的AI工具（Claude 代码，Cursor，Codex）
3. 将MCP服务器配置添加到每个工具
4. 注册插件，以便技能可被发现
```
❯ sessions setup
sessions setup
✓ 插件已安装到 ~/.local/share/sessions/plugin/
✓ MCP服务器已添加到 Claude 代码
✓ 插件已注册到 Claude 代码
✓ MCP服务器已添加到 Cursor
✓ 插件已注册到 Cursor
可用技能：
/context 当前代码库的上下文启动器
/weekly-summary 总结过去一周的AI会话
/standup 昨天 + 今天的活动，用于日报
/recall 指定项目上做了什么？
/session-metrics 带有工具分解的使用仪表盘
在升级sessions（例如，`brew upgrade sessions`）后，再次运行`sessions setup`以更新技能到最新版本。
要删除所有内容：`sessions uninstall`
## CLI：搜索和恢复
```sh
sessions # 浏览所有会话，带有fzf
sessions <查询> # 跨会话内容的全文搜索
sessions --here # 仅限当前git代码库
sessions --tool claude # 仅限Claude 代码会话
sessions --errored # 仅限报错的会话
sessions context # 打印代码库的上下文启动器
sessions report # 使用报告（HTML仪表盘，在浏览器中打开）
```
### 选项
| 标志/命令 | 描述 |
| --------------- | -------------------------------------------------------------------------------------------- |
| `context` | 打印代码库的markdown上下文启动器（参见 [上下文启动器](#context-primer)） |
| `report` | 生成使用报告（参见 [使用报告](#usage-reports)） |
| `setup` | 安装插件并为检测到的工具配置MCP（ `--hooks` 选项启用自动注入） |
| `uninstall` | 删除插件、MCP配置和会话启动钩子，适用于所有工具 |
| `cleanup` | 完整重置：卸载插件 + 清除搜索索引 |
| `--here` | 仅限当前git代码库（默认：所有项目） |
| `--tool <名称>` | 按工具筛选：`claude`、`codex` 或 `pi` |
| `--errored` | 仅显示报错的会话 |
| `--mcp` | 启动为MCP服务器（stdio传输） |
| `--clear-cache` | 删除搜索索引（在下次使用时重建） |
| `--no-color` | 禁用彩色输出 |
| `-h`, `--help` | 显示帮助 |
### 浏览
没有参数时，`sessions` 会扫描所有会话目录，提取每个对话的第一个用户，并将结果通过fzf进行模糊选择：
```
● 我的项目 claude 今天 重构身份验证中间件以使用JWT
● 我的项目 pi 2天前 帮助我调试易逝的集成测试
● api-server codex 1周前 在/api/v2端点添加速率限制
○ 旧项目 claude 2025-03 设置初始项目结构
```
- **●** （绿色）— 项目目录仍然存在
- **○** （红色）— 项目目录已被删除
### 搜索
传递查询以运行全文搜索，跨越所有会话：
```sh
sessions "速率限制"
```
CLI使用与MCP服务器相同的搜索索引：结果按相关性（BM25）而非时间顺序排名，匹配使用porter词干提取（`refactor` 匹配 `refactoring`），多词查询匹配会话，包含 _任意_ 个术语，优先显示最接近的匹配项。搜索涵盖您的消息和助手的回复；系统注入的内容（`<system-reminder>` 等）已从您的消息中剥离，以便您仅匹配实际输入的内容。匹配的会话显示上下文片段，然后通过fzf进行管道传输。
### 选择后
当您选择一个会话时，`sessions` 会显示恢复命令并将其复制到剪贴板：
```
我的项目（claude）
重构身份验证中间件以使用JWT
cd /Users/you/Developer/my-project && claude --resume abc123
（复制到剪贴板）
```
对于Claude 代码会话，命令包括 `--resume <会话ID>`。对于Pi和Codex会话，它会导航到项目目录（这些工具不支持直接会话恢复）。
## 代理人记忆
`sessions` 包括一个 [MCP](https://modelcontextprotocol.io/) 服务器，为AI代理人提供对其过去对话的可搜索访问权限 — 跨越每个工具，而不仅仅是他们运行的工具。 `sessions setup` 自动配置它；对于手动设置，请添加到您的MCP配置（例如，`~/.claude/.mcp.json`）：
```json
{
"mcpServers": {
"sessions": {
"command": "sessions",
"args": ["--mcp"]
}
}
}
```
### MCP工具
MCP服务器暴露五个工具：
| 工具 | 描述 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `search_sessions` | 按关键词搜索会话；返回片段、涉及的文件/命令、报错标志和准备好的恢复命令 |
| `get_session_messages` | 从特定会话中检索消息，按偏移量和限制分页 |
| `get_activity_digest` | 会话的紧凑摘要，日期范围分组，按天和项目 — 用于周报 |
| `get_session_metrics` | 日期范围的使用指标：工具/项目分解、每日活动、活跃小时 |
| `get_context_primer` | 代码库范围的启动器（详细显示最近的会话 + 旧的标题）用于重新注入之前的工作 |
`get_activity_digest` 工具支持一个 `detail` 参数：`"compact"` （默认）返回主题和文件路径，`"highlights"` 添加第一个和最后一个用户消息，用于实质性会话（最适合摘要），而 `"full"` 包括每个会话的所有用户消息。
### 技能
插件自带五个技能，将MCP工具组合成可重复的工作流程：
| 技能 | 触发 | 它做了什么 |
| ------------------ | ------------------------------------------- | ----------------------------------------------------------------- |
| `/context` | "这里发生了什么", "给我更新" | 代码库范围的启动器：之前的决定，死胡同，开线程 |
| `/recall` | "我在[项目]上做了什么" | 按项目/主题搜索会话，显示时间顺序历史 |
| `/standup` | "日报", "昨天我做了什么" | 昨天 + 今天的紧凑格式，Slack的简洁项目 |
| `/weekly-summary` | "总结我的周", "周报" | 获取过去7天的完整摘要，写入结构化报告 |
| `/session-metrics` | "会话统计", "我最常用哪个工具" | 工具/项目分解，每日活动，活跃小时热图 |
技能与Claude 代码、Cursor、Codex和任何支持 `skills.sh` 格式的代理人一起工作。
### 上下文启动器
当您返回代码库时，启动器会回答“我在那里停下来了？”，显示最近的会话，详细显示旧的标题，包括分支和每个会话的最后交换。它有三种方式：
- **从代理人按需** — `/context` 技能或 `get_context_primer` MCP工具
- **从shell按需** — `sessions context` 以markdown格式打印（ `--full` 加宽细节； `--limit`/`--days`/`--tool` 筛选； `--worktree` 仅限当前工作树； `--out <path>` 写入文件）
- **在会话开始时自动** — 可选，下面
#### 在会话开始时自动注入上下文（可选）
您可以通过 [会话启动钩子](https://docs.claude.com/en/docs/claude-code/hooks) 在每个Claude 代码会话开始时自动注入一个小的启动器：
```bash
sessions setup --hooks # 启用自动注入（Claude 代码）
```
在没有 `--hooks` 的情况下运行 `setup` 会交互式地询问（在TTY上）；它 **默认关闭** ，因为它会消耗少量令牌。钩子运行 `sessions context --hook` — 一个微小的启动器（当前代码库的3个最近会话）。在没有历史记录的新代码库中，或在git代码库之外，它不会注入任何内容，并且永远不会阻止会话开始。
要关闭它，请运行 `sessions uninstall` （这也会删除插件和MCP配置）。钩子位于 `~/.claude/settings.json` 下的 `hooks.SessionStart`；启用和禁用会保留您配置的任何其他钩子。
> Codex 和 Cursor 尚未支持 — 它们的会话启动钩子合约仍在确认中。钩子还需要 `sessions` 在会话开始时位于您的 `PATH` 上。
## 使用报告
`sessions report` 对您本地的Claude 代码、Codex 和 Pi 日志进行一次新鲜的传递，并生成令牌/成本使用报告。默认情况下，它会渲染一个自包含的HTML仪表盘，并在您的浏览器中打开；JSON输出可用于管道。
```sh
sessions report # HTML仪表盘，在浏览器中打开
sessions report --out ./report.html # 保存仪表盘而不是打开它
sessions report --format json --stdout # 将JSON打印到stdout（用于管道）
sessions report --days 30 --tool claude # 最近30天，仅Claude 代码
sessions report --this-month # 当前月份至今
sessions report --month 2026-05 # 特定日历月份
sessions report --here # 仅限当前项目
```
所选期间在两个输出的顶部醒目显示（和JSON的 `period`）。
### 报告选项
| 标志 | 描述 |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--format json\|html\|both` | 输出内容。默认为 `html`。 |
| `--out <path>` | 保存输出而不是打开浏览器。对于 `both`，目录 → `usage-report.json` + `report.html`；对于单个格式，文件路径。 |
| `--here` | 仅限当前项目。 |
| `--from YYYY-MM-DD` / `--to YYYY-MM-DD` | 包括本地日期范围。默认为所有时间。 |
| `--days N` | 最近 `N` 天（而不是 `--from`/`--to`）。 |
| `--today` / `--this-week` / `--this-month` / `--last-month` / `--this-year` | 解析为日期范围的便捷预设。 |
| `--month YYYY-MM` | 特定日历月份。 |
| `--tool claude\|codex\|pi` | 仅限一种工具。默认为全部三种。 |
| `--tz <IANA>` | 时区，用于按小时/天分组。默认为 `$TIMEZONE`，否则为 `America/Chicago`。 |
| `--stdout` | 将JSON打印到stdout并跳过JSON文件（如果请求，仍写入HTML）。 |
| `--offline` | 跳过价格刷新；使用缓存/嵌入的价格数据。 |
| `--refresh-pricing` | 强制价格刷新，即使缓存很新鲜。 |
### 报告内容
两个输出都基于相同的数据：
- **摘要** — 总成本、令牌、会话、消息、活跃天数、当前/最长连胜、峰值小时和最常用模型。
- **分解** — 按工具、提供商、模型和项目进行分解。
- **每日系列** — 每天的令牌/成本/会话/消息，带有每小时直方图。
- **洞察** — 每周趋势 + 小时和工作日活动配置文件。
JSON是一种会话拥有的 `UsageReport` （ `{ "generator": "sessions", "version": 1, ... }` ）。HTML是完全自包含的（内联SVG图表，无外部资产），并适应浅色/深色主题。
成本从 [LiteLLM](https://github.com/BerriAI/litellm) 定价数据估算，该数据最多每天获取一次并在本地缓存，具有嵌入的快照作为离线备用 — 失败的获取永远不会阻止报告。Pi会话使用其日志中记录的成本。未知模型的令牌总数仍会计算，成本显示为 `$0`。令牌总数不包括缓存读取（重放上下文，大部分免费重用）。
## 工作原理
### 会话发现
`sessions` 读取JSONL会话文件，来自这些位置：
| 工具 | 目录 |
| ----------- | ------------------------------- |
| Claude 代码 | `~/.claude/projects/<项目>/` |
| Pi | `~/.pi/agent/sessions/` |
| Codex | `~/.codex/sessions/` |
每个会话文件都被解析以提取：
- **工作目录** — 从会话元数据中读取以确定会话属于哪个项目
- **第一个用户** — 您发送的初始消息，清理了系统注入的标签
- **自定义标题** — 如果会话在Claude 代码中被重命名，则使用该标题
- **消息数** — 会话中的总用户 + 助手消息
- **时间戳** — 会话持续时间和日期范围查询的第一个和最后一个时间戳
- **子代理内容** — 对于Claude 代码，会话日志文件中的用户消息会合并到搜索索引中
### 搜索索引
CLI和MCP服务器共享一个SQLite + FTS5索引，位于 `~/.cache/sessions/index.db`。索引在第一次使用时自动构建（~5秒，数千个会话）并在后续运行中通过检查文件修改时间进行增量更新 — 只有新的或更改的会话会被重新索引。
要清除索引并强制完全重建：
```sh
sessions --clear-cache
```
### 使用 `--here` 进行范围限定
当传递 `--here` 时，`sessions` 解析当前git代码库根目录，仅显示工作目录落在该根目录下的会话。这适用于裸仓库工作树 — 如果 `.git` 文件指向 `.bare` 目录，则使用父目录作为代码库根目录。
## 开发
```sh
bun install # 安装依赖
bun run dev # 直接运行，无需编译
bun run build # 编译到 dist/sessions
bun run typecheck # 使用tsc进行类型检查
bun run lint # 使用oxlint进行lint
bun run format # 使用oxfmt进行格式化
bun run format:check # 检查格式，无需写入
```
### 跨编译
发布工作流为三个平台编译二进制文件：
| 目标 | 工件 |
| ------------------------- | ------------------------ |
| macOS ARM（Apple Silicon） | `sessions-darwin-arm64` |
| macOS x86_64（Intel） | `sessions-darwin-x86_64` |
| Linux x86_64 | `sessions-linux-x86_64` |
二进制文件使用 `bun build --compile --minify` 编译并作为 `.tar.gz` 归档文件附加到GitHub Releases。
### 发布流程
发布是使用 [release-please](https://github.com/googleapis/release-please) 自动化的：
1. 使用 [conventional commit](https://www.conventionalcommits.org/) 消息将提交推送到 `main`
2. release-please 打开一个版本提升PR，并自动生成更改日志
3. 合并PR以触发发布管道
4. 二进制文件被构建，附加到GitHub Release，Homebrew公式自动更新
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器