Metadata-Version: 2.4
Name: hook-deployer
Version: 1.0.0
Summary: AI 对话历史自动存档工具
Home-page: https://github.com/openclaw/hook-deployer
Author: Hook Deployer Team
Author-email: Hook Deployer Team <contact@hook-deployer.com>
License: MIT
Project-URL: Homepage, https://github.com/openclaw/hook-deployer
Project-URL: Bug Reports, https://github.com/openclaw/hook-deployer/issues
Project-URL: Source, https://github.com/openclaw/hook-deployer
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Hook Deployer

> AI 对话历史自动存档工具

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

## ✨ 特性

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

## 📦 安装

### 从 PyPI 安装（推荐）

```bash
pip install hook-deployer
```

### 从源码安装

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

## 🚀 快速开始

### 1. 安装 Hook

在项目根目录执行：

```bash
hook-deployer install
```

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

### 2. 指定输出目录

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

### 3. 强制重新安装

```bash
hook-deployer install --force
```

### 4. 查看详细日志

```bash
hook-deployer install --verbose
```

## 📋 命令

### install

安装 Hook 脚本到当前项目。

```bash
hook-deployer install [OPTIONS]
```

**选项:**

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

### uninstall

移除当前项目的 Hook 配置。

```bash
hook-deployer uninstall [OPTIONS]
```

**选项:**

* `--verbose, -v`: 显示详细日志

### list

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

```bash
hook-deployer list [OPTIONS]
```

**选项:**

* `--verbose, -v`: 显示详细日志

### config

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

```bash
hook-deployer config [OPTIONS]
```

**选项:**

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

**示例:**

```bash
# 查看完整配置
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 格式

```markdown
# 对话历史

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

---

## 对话内容

[此处为完整对话文本]
```

### OpenClaw 格式

```markdown
# 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 | 🚧 |

## 🔧 开发

### 本地开发

```bash
# 克隆仓库
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 支持文档](./OPENCLAW_SUPPORT.md)。

### 添加新插件

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

示例：

```python
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
```

## 🧪 测试

```bash
# 运行所有测试
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` 配置文件：

```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](LICENSE) 文件

## 🔗 相关链接

* [Claude Code Hooks 文档](https://docs.anthropic.com/claude/code/hooks)
* [Cursor Hooks 文档](https://cursor.sh/docs/hooks)
* [CodeBuddy 自定义脚本](https://codebuddy.dev/docs/hooks)
* [OpenClaw 支持文档](./OPENCLAW_SUPPORT.md)
* [产品需求文档](./PRD.md)
* [架构设计文档](./ARCHITECTURE.md)
* [QA 测试用例](./docs/QA_TEST_CASES.md)

## 📝 变更日志

详见 [CHANGELOG.md](./docs/CHANGELOG.md)

## 🙏 致谢

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

---

**Made with ❤️ by Hook Deployer Team**
