Claude Code 上下文插件安装与使用指南:claude-baton & bookmark

📖 概述

本文档提供 claude-baton 和 @tyroneross/bookmark 两个插件在 Claude Code 中的完整、可靠的安装与使用教程。

🎭 一、claude-baton 安装与使用

工作原理

通过 PreCompact 钩子在 Claude 压缩上下文之前自动保存会话状态到本地 SQLite 数据库，新会话通过 /memo-resume 一键恢复。

安装步骤

# 1. 全局安装
npm install -g claude-baton

# 2. 一键配置（自动注册 MCP 服务器、钩子和斜杠命令）
claude-baton setup

setup 会自动完成：

• ✅ 注册 MCP 服务器（user scope，全局生效）

• ✅ 注册 PreCompact 钩子（自动检查点）

• ✅ 注册允许的工具（斜杠命令免确认）

• ✅ 初始化数据库 ~/.claude-baton/store.db

• ✅ 安装斜杠命令到 ~/.claude/commands/

配置确认

bash

# 检查文件是否生成
ls -la ~/.claude-baton/          # 数据库和配置目录
ls -la ~/.claude/commands/memo-* # 三个斜杠命令文件
cat ~/.claude/settings.json      # 用户级 MCP 配置

核心命令

斜杠命令（在 Claude Code 会话内使用）

CLI 命令（在终端使用）

bash

claude-baton status              # 查看统计
claude-baton projects            # 列出所有追踪的项目
claude-baton export              # 导出检查点为 JSON 文件
claude-baton reset --project     # 重置指定项目的数据
claude-baton uninstall           # 完全卸载

日常使用流程

# ===== 第一天：开始工作 =====
cd my-project
claude

# 完成一个重要功能后手动保存
/memo-checkpoint

# 继续工作... 触发上下文压缩时会自动保存

# ===== 第二天：继续工作 =====
cd my-project
claude

# 第一件事：恢复昨天的上下文
/memo-resume

# Claude 会显示：上次做了什么、关键决策、未完成事项、Git diff
# 然后直接继续工作！

关键文件位置

🔖 二、bookmark 安装与使用

工作原理

运行在外部进程，通过四个钩子自动管理会话快照，零 token 消耗。快照通过模式匹配从对话记录中提取，不调用 LLM。

⚠️ 重要：bookmark 的两种安装方式

bookmark 插件必须通过插件市场安装，不能直接用 /plugin install bookmark。以下是两种可靠的安装方法。

方式一：通过插件市场安装（推荐）

这是官方推荐的方式，需要先添加市场，再安装插件。

步骤 1：添加插件市场

在 Claude Code 会话中执行以下命令：

text

/plugin marketplace add tyroneross/bookmark

或者使用完整 URL：

text

/plugin marketplace add https://github.com/tyroneross/bookmark

💡 提示：如果遇到 SSH 认证错误，请使用 HTTPS URL（第二个命令）。

步骤 2：安装插件

市场添加成功后，执行安装命令：

text

/plugin install bookmark

步骤 3：验证安装

text

/plugin list

应该能看到 bookmark 插件，状态为 active 或 enabled。

方式二：项目级 npm 安装（备选）

如果上述市场安装方式遇到问题，可以通过 npm 在项目级安装。这种方式不经过插件市场，但同样能工作。

bash

# 进入你的项目目录
cd your-project

# 直接通过 npm 安装
npm install @tyroneross/bookmark

安装完成后，重启 Claude Code，插件会自动激活。

📌 注意：这种方式可能不会自动注册斜杠命令，如果 /bookmark:status 不可用，请使用方式一。

配置确认

bash

# 检查插件数据目录（项目级）
ls -la .claude/bookmarks/

# 应该能看到：
# LATEST.md       - 热点上下文
# index.json      - 快照索引
# state.json      - 插件状态
# config.json     - 用户配置
# snapshots/      - 完整快照文件
# archive/        - 旧快照

核心命令

斜杠命令（在 Claude Code 会话内）

CLI 命令（在终端）

bash

bookmark status              # 查看统计
bookmark list                # 列出快照
bookmark show --latest       # 显示最新快照内容
bookmark config              # 查看当前配置
bookmark config --interval 15  # 修改快照间隔为 15 分钟

自适应阈值机制

Bookmark 会根据压缩频率自动调整快照触发时机：

时间触发：默认每 20 分钟活动时间自动快照。

智能模式（可选：调用claude code的官方地址，暂时无法更改）

bash

# 启用智能模式（使用 Claude Haiku 提取，质量更高）
bookmark config --smart-default

# 需要设置 API Key
export ANTHROPIC_API_KEY="your-key"

数据存储结构

text

my-project/
└── .claude/
    └── bookmarks/
        ├── LATEST.md       # 热点上下文（SessionStart 时恢复）
        ├── index.json      # 快照索引
        ├── state.json      # 插件状态
        ├── config.json     # 用户配置
        ├── snapshots/      # 完整快照文件
        └── archive/        # 30天前的旧快照

📌 .claude/bookmarks/ 目录自动加入 .gitignore，不会提交到仓库。

🆚 三、两个插件的对比与选择

选择建议

• 选 claude-baton：需要手动控制检查点、团队协作（JSON 导出）、Git 感知功能

• 选 bookmark：想要零配置自动运行、轻量级个人使用

💡 两者可以同时使用，不冲突！

🩺 四、常见问题与故障排除

Q1: claude-baton 安装后命令不生效？

bash

# 检查安装
claude-baton --version

# 重启 Claude Code（完全退出终端重新打开）

# 验证斜杠命令
/memo-status

Q2: bookmark 安装时遇到 "Plugin not found in any marketplace"？

原因：没有先添加插件市场。

解决方案：先执行市场添加命令：

text

/plugin marketplace add tyroneross/bookmark
# 或
/plugin marketplace add https://github.com/tyroneross/bookmark

# 然后再安装
/plugin install bookmark

Q3: 遇到 "SSH authentication failed" 错误？

原因：SSH key 未配置，Claude Code 默认使用 SSH 克隆市场仓库。

解决方案：使用 HTTPS URL 添加市场：

text

/plugin marketplace add https://github.com/tyroneross/bookmark

Q4: bookmark 安装后 /bookmark:status 仍然找不到？

原因：插件可能未正确加载或斜杠命令未注册。

解决方案：

bash

# 1. 检查插件是否已安装
/plugin list

# 2. 如果列表中沒有，重新安装
/plugin install bookmark

# 3. 重启 Claude Code

# 4. 如果仍然不行，尝试项目级 npm 安装
cd your-project
npm install @tyroneross/bookmark

Q5: 遇到 "Failed to reconnect to plugin:bookmark"？

原因：插件连接失败，通常是配置残留或网络问题。

解决方案：完全重新安装

bash

# 1. 关闭所有 Claude Code 会话

# 2. 清理插件
/plugin remove bookmark

# 3. 清理所有残留
npm uninstall -g @tyroneross/bookmark
rm -rf ~/.claude/plugins/marketplaces/
rm -rf ~/.claude/plugins/installed/bookmark
rm -rf .claude/bookmarks/
rm -rf node_modules/@tyroneross/bookmark

# 4. 重新添加市场并安装
# 在 Claude Code 中：
/plugin marketplace add https://github.com/tyroneross/bookmark
/plugin install bookmark

# 5. 重启 Claude Code

Q6: 如何验证两个插件都正常工作？

在 Claude Code 会话中运行：

text

# 验证 claude-baton /memo-status  # 验证 bookmark /bookmark:status  # 整体诊断 /doctor

Q7: 代理环境下无法连接？

bash

# 设置代理环境变量 export HTTPS_PROXY=http://你的代理地址:端口 export HTTP_PROXY=http://你的代理地址:端口  # 或在 Claude Code 会话中设置 /set env HTTPS_PROXY http://你的代理地址:端口

📋 五、快速安装清单（复制即用）

安装 claude-baton

bash

npm install -g claude-baton claude-baton setup

安装 bookmark（市场方式）

在 Claude Code 会话中依次执行：

text

/plugin marketplace add https://github.com/tyroneross/bookmark /plugin install bookmark

安装 bookmark（npm 备选方式）

bash

cd your-project npm install @tyroneross/bookmark # 然后重启 Claude Code

安装后验证

bash

# 验证 CLI 工具 claude-baton --version bookmark --version  # 在 Claude Code 中验证斜杠命令 /memo-status /bookmark:status

📁 六、文件位置速查表

⚠️ 七、重要提示

1. bookmark 必须先添加市场再安装：/plugin marketplace add → /plugin install bookmark

2. 如遇 SSH 错误，使用 HTTPS URL：https://github.com/tyroneross/bookmark

3. 两个插件可以共存，互不干扰

4. 数据目录不会提交到 Git（已自动加入 .gitignore）

5. 遇到问题先重启 Claude Code，能解决 80% 的问题

6. 使用 /doctor 命令诊断大部分插件问题