Hook Deployer

AI 对话历史自动存档工具

Hook Deployer 是一个 Python 命令行工具，可以自动为你的项目配置 Claude Code、Cursor、CodeBuddy、OpenClaw 等开发工具的 Hook，在每次对话结束时自动保存完整的对话历史记录。

✨ 特性

• 🚀 零配置: 一条命令完成所有 IDE 的 Hook 部署
• 🔌 多 IDE 兼容: 支持 Claude Code、Cursor、CodeBuddy、OpenClaw 等主流工具
• 📝 历史可追溯: 每次对话独立存档，便于检索和分析
• 🎯 插件化架构: 微内核设计，易于扩展新功能
• 🔄 自举测试: 支持使用 hook-deployer 保存自身对话历史

📦 安装

从 PyPI 安装（推荐）

pip install hook-deployer

从源码安装

git clone https://github.com/yourusername/hook-deployer.git
cd hook-deployer
pip install -e .

🚀 快速开始

1. 安装 Hook

在项目根目录执行：

hook-deployer install

这将自动检测项目中使用的 IDE 并配置对应的 Hook。

2. 指定输出目录

hook-deployer install --output-dir .ai-history

3. 强制重新安装

hook-deployer install --force

4. 查看详细日志

hook-deployer install --verbose

📋 命令

install

安装 Hook 脚本到当前项目。

hook-deployer install [OPTIONS]

选项:

• --output-dir <路径>: 对话历史存储目录（默认: .ai-conversations）
• --force: 强制覆盖已存在的配置
• --verbose, -v: 显示详细日志

uninstall

移除当前项目的 Hook 配置。

hook-deployer uninstall [OPTIONS]

选项:

• --verbose, -v: 显示详细日志

list

列出当前项目的 IDE 和 Hook 状态。

hook-deployer list [OPTIONS]

选项:

• --verbose, -v: 显示详细日志

config

查看或修改当前项目的 Hook 配置。

hook-deployer config [OPTIONS]

选项:

• --key <配置项>: 配置项名称
• --value <值>: 配置项值
• --verbose, -v: 显示详细日志

示例:

# 查看完整配置
hook-deployer config

# 查看特定配置项
hook-deployer config --key version

# 更新配置项
hook-deployer config --key version --value 2.0.0

📁 对话历史格式

对话历史以 Markdown 格式保存到指定目录，文件名格式为：YYYYMMDD_HHMMSS_sessionId.md

Claude Code / Cursor / CodeBuddy 格式

# 对话历史

**时间**: 2026-03-01T15:30:22+08:00
**工具**: Claude Code
**工作目录**: /path/to/project
**会话 ID**: abc123

---

## 对话内容

[此处为完整对话文本]

OpenClaw 格式

# OpenClaw 对话历史

**时间**: 2026-03-01T15:30:22+08:00
**会话 ID**: ou_a7a583dc5002d3ae942f07a63e465a0d
**渠道**: feishu
**提供方**: feishu
**聊天 ID**: user:ou_a7a583dc5002d3ae942f07a63e465a0d

---

## 用户消息

用户输入的消息内容...

---

## AI 响应

AI 的响应内容...

---

## 完整对话历史

完整的对话历史内容...

---

*由 hook-deployer 自动保存*

🏗️ 架构

Hook Deployer 采用微内核 + 插件化架构：

hook-deployer/
├── core/                # 核心引擎
│   ├── hook_manager.py  # Hook 生命周期管理
│   └── installer.py     # IDE 配置安装器
├── plugins/             # 插件目录
│   ├── session_end/     # SessionEnd 插件
│   └── openclaw/       # OpenClaw 插件
└── cli.py              # CLI 入口

支持的 IDE

IDE / 工具	Hook 事件	状态
Claude Code	SessionEnd	✅
Cursor	sessionEnd	✅
CodeBuddy	onSessionEnd	✅
OpenClaw	OpenClawSessionEnd	✅
Cline	session_end	🚧

🔧 开发

本地开发

# 克隆仓库
git clone https://github.com/yourusername/hook-deployer.git
cd hook-deployer

# 安装依赖
pip install -e .

# 运行测试
pytest

# 运行自举测试
pytest tests/test_bootstrap.py -v

# 运行测试覆盖率
pytest --cov=core --cov=plugins --cov=cli --cov-report=term-missing

OpenClaw 支持

hook-deployer 现在完全支持 OpenClaw 对话历史自动保存。详细信息请查看 OpenClaw 支持文档。

添加新插件

1. 在 plugins/ 目录下创建新插件目录
2. 实现 HookPlugin 接口
3. 在 cli.py 中注册插件

示例：

from core.plugin_base import HookPlugin
from pathlib import Path
from typing import List, Dict

class MyPlugin(HookPlugin):
    @property
    def event_name(self) -> str:
        return "MyEvent"

    @property
    def supported_ides(self) -> List[str]:
        return ["claude", "cursor"]

    def generate_script(self, output_dir: Path) -> Path:
        # 生成脚本逻辑
        pass

    def get_config(self, ide: str, script_path: Path) -> Dict:
        # 返回 IDE 配置
        pass

🧪 测试

# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_openclaw_plugin.py

# 运行自举测试
pytest tests/test_bootstrap.py -v

# 生成测试覆盖率报告
pytest --cov=core --cov=plugins --cov=cli --cov-report=html

测试结果:

• 总测试数: 45
• 通过: 45 ✅
• 失败: 0
• 覆盖率: 81%

📖 使用场景

1. 个人知识库

自动保存所有与 AI 的对话，构建个人知识库，便于后续回顾和学习。

2. 团队协作

团队成员共享对话历史，便于知识共享和团队学习。

3. 模型训练

收集大量真实对话数据，用于模型微调或数据分析。

4. 合规审计

保存所有 AI 对话记录，满足合规和审计要求。

🔧 配置

项目配置文件

Hook Deployer 在项目根目录创建 .hook-deployer/config.json 配置文件：

{
  "version": "1.0.0",
  "output_dir": ".ai-conversations",
  "enabled_ides": ["claude", "cursor"],
  "hook_scripts": {
    "claude": ".ai-conversations/session-end.sh",
    "cursor": ".ai-conversations/session-end.sh"
  },
  "installed_at": "2026-03-01T05:00:00Z"
}

环境变量

• HOOK_DEPLOYER_LOG_LEVEL: 日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
• HOOK_DEPLOYER_OUTPUT_DIR: 默认输出目录

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

开发指南

• 遵循现有代码风格
• 添加测试覆盖新功能
• 更新相关文档
• 确保所有测试通过

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🔗 相关链接

• Claude Code Hooks 文档
• Cursor Hooks 文档
• CodeBuddy 自定义脚本
• OpenClaw 支持文档
• 产品需求文档
• 架构设计文档
• QA 测试用例

📝 变更日志

详见 CHANGELOG.md

🙏 致谢

感谢所有为本项目做出贡献的开发者！

---

Made with ❤️ by Hook Deployer Team