内容
<h1 align="center">克劳德工具箱</h1>
<p align="center"><em>为克劳德代码提供会话生命周期管理 - 导向、检查点、关闭并保持会话连续性。</em></p>
<p align="center">
<a href="https://github.com/gf-labs/claude-toolbox"><img src="https://img.shields.io/badge/%E7%89%88%E6%9C%AC-0.5.1-3b82f6?style=flat-square" alt="版本"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/%E6%89%88%E6%9C%AC-MIT-22c55e?style=flat-square" alt="许可证"></a>
<img src="https://img.shields.io/badge/%E5%87%90%E5%BE%B7%E4%BB%A3%E7%A0%81%E6%89%88%E5%8A%BF-d97757?style=flat-square&logo=anthropic&logoColor=white" alt="克劳德代码插件">
<img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
<img src="https://img.shields.io/badge/MCP-%E6%9C%8D%E5%8A%BF-6366f1?style=flat-square" alt="MCP 服务器">
</p>
<p align="center">由 <a href="https://github.com/berniegreen">伯尼·格林</a> · <a href="https://github.com/gf-labs">绿地实验室</a> 构建</p>
> **存储库、插件和命名空间。** 存储库名为 `claude-toolbox`。它作为 **`tools`** 插件通过 [GFL 市场](https://github.com/gf-labs/gfl-marketplace) 提供，其命令命名为 **`/tools:*`**。一个制品，三个名称 - 对于克劳德代码插件来说，这是正常的，阅读以下内容之前值得了解。
---
## 为什么存在
克劳德代码的最大优势也是其最锋利的边缘：**会话**。所有操作都发生在一个滚动的上下文窗口中 - 消息、文件读取、工具输出 - 当窗口填满时，您到达那里的推理被压缩并删除。决策在会话之间蒸发。几天后，您重新打开一个存储库，不确定您离开时的位置。
`claude-toolbox` 是我构建的用于保持线程的系统。它管理整个会话生命周期 - **导向** 在开始，**检查点** 在中间，**关闭** 清洁地在结束，**存档** 重要的内容 - 因此理解在会话之间累积，而不是在每个会话中重置。
概念主干位于 [`docs/context-hygiene.md`](docs/context-hygiene.md) 中：上下文窗口的工作原理，内容存储的位置以及每个命令自动化的内容。
## 您获得的内容
- **永不丢失线索。** 导向命令在几秒钟内重建您的心理模型 - 根据您离开的时间，从 30 秒的脉冲到完整的冷启动简介。
- **无需仪式即可检查点。** `/tools:pin` 捕获状态，写入会话日志条目，并在一步骤中更新持久内存 - 在您运行 `/compact` 之前运行它。
- **清洁关闭。** `/tools:wrap` 运行结束会话的仪式：会话日志，git 检查，计划清理，待办事项审查，内存健康。
- **保持上下文精简。** `PreCompact` 钩子拒绝在您检查点之前压缩；`/tools:cleanup` 在删除旧会话之前从中提取上下文。
- **查询您自己的历史记录。** 通过命令或本地 MCP 服务器，对每个会话进行全文搜索 - 来自任何项目。
---
## 会话生命周期
命令映射到工作会话的自然弧线。您通常不需要一次使用所有命令；使用与您当前状态相符的命令。
```
[ 会话开始 ]
/tools:brief 导向 - 分支、正在进行、最新快照、计划、最近活动
/tools:overview 计划 - 当前状态 + 待办事项优先级 + 排序建议
[ 会话期间 ]
工作...
/tools:status 快速脉冲 - git 详细信息、最新会话笔记、正在进行的待办事项
/tools:pin 断点检查点 - 状态 + 会话日志 + 可选的 MEMORY.md （在 /compact 之前运行）
/tools:aside 以固定格式回答一个边边问题，然后继续
/tools:backlog 将任务捕获到 TaskWarrior 而不中断流程
[ 会话结束 ]
/ramp:wrap 收获知识图（如果安装了 ramp 插件）
/tools:wrap 关闭仪式：
会话日志 → git 检查 → 计划清理 → 待办事项审查
→ 内存健康 → 可选的“标记会话完成”
[ 定期维护 ]
/tools:cleanup 从旧会话中提取上下文，然后删除它们
/tools:search-sessions 按关键词和时间范围对会话历史记录进行全文搜索
/tools:sit-rep 叙事情况报告 - 速度、关键点、学习成果、风险
/tools:doctor 环境 + 项目健康检查
```
---
## 命令
十二个命令加一个技能，按您需要它们的顺序分组。廉价、高频率的命令在 Haiku 上运行；需要推理的命令在 Sonnet 上运行。
### 导向 - “我在哪里？”
四个命令回答不同的进入问题。根据您离开的时间和您需要的内容进行选择。
| 命令 | 何时 | 问题答案 |
|---------|------|---------------------|
| `/tools:brief` | 冷启动/长时间离开（几天或几周） | “让我恢复正常” |
| `/tools:status` | 中途，仍然温暖 | “我现在在哪里？” |
| `/tools:recap` | 短暂离开后（几个小时或一天） | “我最近做了什么？” |
| `/tools:overview` | 计划/决定接下来做什么 | “我接下来应该做什么？” |
> 参见 [`docs/design-log.md`](docs/design-log.md) § *导向命令分类* 获取完整的分类表 - 将一个“状态”命令分成四个的推理。
### 会话中 - 捕获和检查点
| 命令 | 描述 |
|---------|-------------|
| `/tools:pin` | 断点检查点 - 状态显示，会话日志条目，可选的 MEMORY.md 更新 |
| `/tools:aside` | 以固定格式回答任务中的一个小问题，然后返回任务 |
| `/tools:backlog` | 为该项目添加任务到 TaskWarrior（`[item] [+tag] [size:S]`） |
| `/tools:consolidate-tasks` | 将工作项 - 标记跟踪器，代码 `TODO`/`FIXME`，GitHub 问题 - 扫入 TaskWarrior，去除重复和墓碑 |
| `/tools:sit-rep` | 跨越数周工作的叙事情况报告 - 速度，里程碑，关键点，学习成果，风险 *(作为技能提供)* |
### 关闭和维护
| 命令 | 描述 |
|---------|-------------|
| `/tools:wrap` | 会话结束的清理 - 会话日志，git 检查，计划清理，待办事项审查，已完成标记 |
| `/tools:cleanup` | 清理旧会话工件 - 预览，提取上下文，然后删除 |
| `/tools:doctor` | 克劳德代码环境 + 项目健康检查（范围感知） |
| `/tools:search-sessions` | 按关键词和时间范围对会话历史记录进行全文搜索 |
---
## 状态存储位置
`claude-toolbox` 从克劳德代码已使用的存储中读取和写入。没有任何内容隐藏在数据库中 - 每个存储都是一个可以打开、编辑和版本化的普通文件。
| 存储 | 位置 | 自动加载？ | 由谁写入 |
|-------|----------|--------------|------------|
| `MEMORY.md` | `~/.claude/projects/[key]/memory/MEMORY.md` | 是 - 自动内存，200 行预算 | `/tools:pin` |
| `session-log.md` | `~/.claude/projects/[key]/memory/session-log.md` | 否 | `/tools:pin`，`/tools:wrap`，`/tools:cleanup` |
| `CLAUDE.md` | `[repo]/CLAUDE.md` 或 `~/.claude/CLAUDE.md` | 是 - 每个会话 | 手动 |
| 计划 | `~/.claude/plans/[name].md` | 否 - 按需读取 | 手动/代理 |
| 会话文件 | `~/.claude/projects/[key]/[id].jsonl` | 否 - 仅存档 | 克劳德代码 |
---
## 代理
代理是克劳德在任务期间可以启动的子进程。它们在单独的上下文中运行并返回单个结果 - 适用于原本会淹没主窗口的只读子任务。
| 代理 | 模型 | 描述 |
|-------|-------|-------------|
| `explore` | Haiku | 快速代码库资源管理器 - 查找文件，搜索代码，回答结构问题 |
| `plan` | Sonnet | 实现规划器 - 读取代码库，返回阶段性计划 |
| `review` | Haiku | 结构化代码审查 - 差异分析，可读性，正确性，安全性 |
| `summarize` | Haiku | 会话总结器 - 给定一个 JSONL 路径，返回发生情况的简洁说明 |
> 所有四个都是 **只读** - 没有一个具有 `Write` 或 `Edit`，因此它们不能触摸您的工作树。大多数使用 `Glob, Grep, Read, Bash`；`summarize` 更窄（`Read, Bash`）。它们探索和报告，仅此而已。
---
## 钩子
钩子是克劳德代码在生命周期事件上自动触发的命令。插件通过 [`hooks/hooks.json`](hooks/hooks.json) 注册它们；它们适用于加载插件的每个会话。
| 事件 | 匹配器 | 脚本 | 它做了什么 |
|-------|---------|--------|--------------|
| `SessionStart` | — | `validate-env.py` | 检查 `CLAUDE_TOOLBOX_ROOT` 是否设置并有效 |
| `SessionStart` | — | `setup-mcp.py` | 在用户范围内自动注册 MCP 服务器（幂等） |
| `PostToolUse` | `Write` | `collect-plan-map.py` | 在文件创建后刷新计划到项目映射 |
| `PostToolUse` | `Edit \| Write` | `lint-py.py` | 检查刚刚编辑的任何 Python 文件的语法 |
| `PreCompact` | — | `check-pin-ran.py` | **阻止** 紧凑化，除非在此会话中运行了 `/tools:pin`（因此在未检查点的情况下永远不会总结上下文） |
---
## MCP 服务器
`claude-toolbox` 暴露一个本地 [MCP](https://modelcontextprotocol.io) 服务器，以便任何克劳德上下文 - 而不仅仅是当前项目 - 都可以查询您的会话数据。
| 工具 | 描述 |
|------|-------------|
| `search_sessions` | 按关键词和时间范围对会话历史记录进行全文搜索 |
| `list_plans` | 列出具有项目属性的所有活动计划 |
| `get_session_log` | 读取项目的会话日志条目 |
`setup-mcp.py` SessionStart 钩子为您注册它。要手动注册，首先创建服务器的虚拟环境 - 它依赖于 `mcp` 包，而系统 `python3` 无法解析它：
```bash
python3 -m venv mcp_server/.venv
mcp_server/.venv/bin/pip install mcp
```
然后将配置条目指向虚拟环境的 python（或使用 `mcp_server/start.sh`，它为您解析）：
```json
{
"mcpServers": {
"claude-toolbox": {
"command": "/path/to/claude-toolbox/mcp_server/.venv/bin/python3",
"args": ["/path/to/claude-toolbox/mcp_server/server.py"]
}
}
}
```
---
## 入门指南
### 要求
- **克劳德代码**（最新）
- **Python 3.11+** - 命令和钩子仅限标准库；无第三方依赖
- **[TaskWarrior](https://taskwarrior.org)** *(可选)* - 仅 `/tools:backlog` 和 `/tools:consolidate-tasks` 使用它
### 安装
命令通过 `CLAUDE_TOOLBOX_ROOT` 环境变量调用辅助脚本，因此无论您选择哪种安装路径，都要将该环境变量设置为存储库的位置。
**选项 A - GFL 市场（推荐）：**
```bash
/plugin marketplace add gf-labs/gfl-marketplace
/plugin install tools@gfl-marketplace
```
然后克隆存储库并在 `~/.claude/settings.json` 中将 `CLAUDE_TOOLBOX_ROOT` 指向它，以便命令脚本解析：
```json
{ "env": { "CLAUDE_TOOLBOX_ROOT": "/abs/path/to/claude-toolbox" } }
```
**选项 B - 本地开发（直接从克隆中运行）：**
```bash
git clone https://github.com/gf-labs/claude-toolbox ~/path/to/claude-toolbox
```
在 `~/.claude/settings.json` 中设置相同的环境变量，然后使用指向 **存储库根目录** 的 `--plugin-dir` 启动克劳德代码（不是 `.claude-plugin/` 本身）：
```bash
claude --plugin-dir /abs/path/to/claude-toolbox
```
重新启动会话。SessionStart 钩子验证您的设置；现在可以作为 `/tools:*` 使用命令。
### 首次运行
```bash
/tools:doctor # 确认环境健康
/tools:brief # 导向 - 即使在新存储库中，这也会显示您看到的内容
```
---
## 存储库结构
```
claude-toolbox/
├── commands/ # 斜杠命令，作为 /tools:* 提供
├── agents/ # 只读子代理（explore, plan, review, summarize）
├── skills/ # 多步骤技能（sit-rep）
├── scripts/ # 命令和钩子调用的 Python 收集器（仅限标准库）
├── hooks/ # hooks.json - 插件注册的生命周期钩子
├── mcp_server/ # 本地 MCP 服务器（search_sessions, list_plans, get_session_log）
├── docs/ # context-hygiene 参考资料，设计日志，目录参考
└── tests/ # 收集器的 pytest 覆盖率
```
---
## 使用克劳德代码构建
`claude-toolbox` 本身就是克劳德代码扩展模型的一次探索 - 没有应用程序运行时，只有配置和标准库 Python。如果您正在学习插件可以执行什么，此存储库是一个完整的示例，涵盖了所有主要接口：
- **斜杠命令** - 12 个命令使用 `$ARGUMENTS`、``!`bash`` 输出注入和每个命令的 `model` 选择（Haiku 便宜/快速，Sonnet 需要推理）
- **子代理** - `agents/` 中 4 个自定义只读代理，用于上下文隔离工作
- **技能** - `sit-rep`，一个具有捆绑脚本和引用的多步骤合成技能
- **钩子** - 5 个钩子，跨越 `SessionStart`、`PostToolUse` 和 `PreCompact`，包括一个 `PreCompact` 门控，当您使用 `/tools:pin` 检查点后阻止压缩（退出 2）
- **MCP 服务器** - 一个本地标准输入/输出服务器，暴露三个会话查询工具
- **插件打包** - 一个版本化的 `plugin.json` 清单，通过市场目录分发
- **设置层次结构** - 全局/项目/本地 `settings.json`，环境变量和权限范围
---
## 扩展
| 添加... | 步骤 |
|--------|-------|
| **命令** | 在 `commands/` 中用 frontmatter（`description`、`allowed-tools`、`model`、`argument-hint`）创建 `[name].md`。增加版本号，重启。 |
| **脚本** | 添加 `scripts/[name].py`（仅限标准库）。使用 `!python3 ${CLAUDE_TOOLBOX_ROOT}/scripts/[name].py` 从命令调用。 |
| **代理** | 在 `agents/` 中用 frontmatter（`name`、`description`、`tools`、`model`、`color`）创建 `[name].md`。增加版本号，重启。 |
| **钩子** | 在 `hooks/hooks.json` 中为事件键（`SessionStart`、`PostToolUse`、`PreCompact`、`Stop` 等）添加条目。增加版本号，重启。 |
在每次发布时增加 [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) 中的版本号。有关存储库约定和注意事项，请参见 [`CLAUDE.md`](CLAUDE.md)。
---
## 路线图
- **统一搜索**，跨会话、计划、内存和待办事项从一个命令进行搜索
- **更紧密的 ramp 集成** - 一个知识和会话收获的单一操作
- **提交到官方 Anthropic 插件市场**，一旦稳定
---
## 许可证
[MIT](./LICENSE) © 2026 绿地实验室
