anian0/specstory-sync

Specstory Sync — Claude Code 对话历史自动记录

为任意项目一键配置对话历史自动记录。每次 Claude Code 完成回复时，自动将当前会话导出为格式化的 Markdown 文件，存放在项目的 .specstory/history/ 目录下。

工作原理

1. 脚本 sync_to_spec.py 读取 ~/.claude/projects/ 下的 JSONL 会话数据
2. 转换为 Specstory 兼容的 Markdown（含时间戳、角色标签、工具调用摘要）
3. 去重：通过 fingerprint 机制避免重复写入
4. Hook：利用 Claude Code 的 Stop 事件钩子自动触发

执行步骤

当用户要求配置对话历史记录时，按以下步骤操作：

Step 1: 部署脚本

将 scripts/sync_to_spec.py 复制到目标项目的 .specstory/ 目录：

# 确保目标目录存在
mkdir -p <project-root>/.specstory/history

# 复制脚本
cp <skill-dir>/scripts/sync_to_spec.py <project-root>/.specstory/sync_to_spec.py

其中 <skill-dir> 是本 skill 所在目录，<project-root> 是用户当前项目的根目录。

Step 2: 配置 Stop Hook

读取项目已有的 .claude/settings.json（如果不存在则创建），在其中添加 Stop 事件钩子。

重要：必须保留已有的 hooks 和其他配置，只合并新增内容。

需要添加的 Hook 配置：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".venv/Scripts/python.exe .specstory/sync_to_spec.py",
            "timeout": 15,
            "statusMessage": "Syncing conversation history..."
          }
        ]
      }
    ]
  }
}

Python 解释器适配：根据项目环境选择正确的 Python 路径：

• 如果项目有 .venv/Scripts/python.exe（Windows 虚拟环境），使用 .venv/Scripts/python.exe
• 如果项目有 .venv/bin/python（Linux/Mac 虚拟环境），使用 .venv/bin/python
• 如果项目有 pyproject.toml 且使用 uv，使用 uv run python
• 否则使用系统 python3（Mac/Linux）或 python（Windows）

Step 3: 验证安装

运行脚本测试一次，确认能正确读取和转换对话数据：

cd <project-root>
<python-path> .specstory/sync_to_spec.py

成功输出类似：

[specstory-sync] Synced 47 messages -> 2026-04-22_03-34-25Z-some-title.md

如果出现错误，检查：

• Python 版本 >= 3.10（使用了 Path | None 类型语法）
• ~/.claude/projects/ 下是否有对应项目的目录
• Windows 路径编码是否正确（D:\foo → D--foo）

Step 4: 确认 .gitignore

建议在项目的 .gitignore 中添加以下条目（如果用户希望将对话历史纳入版本控制则跳过）：

.specstory/history/

输出格式

生成的 Markdown 文件存放在 .specstory/history/ 下，命名规则：

YYYY-MM-DD_HH-MM-SSZ-<title-slug>.md

文件内容示例：

<!-- Generated by Claude Code Specstory Sync -->

# 2026-04-22 03:34

<!-- Claude Code Session abc123-def456 (2026-04-22T03:34:25.907Z) -->

_**User (2026-04-22 03:34:25)**_

帮我实现一个功能...

---

_**Assistant (2026-04-22 03:34:30)**_

好的，我来帮你实现...

*Read*: `src/main.py`

```bash
pip install requests

---

## 已有 Specstory 目录的处理

如果项目已经存在 `.specstory/` 目录（来自 Cursor/VSCode 的 Specstory 扩展），本脚本会复用该目录，生成的文件与原有格式兼容。两种来源的记录可以共存。

## 卸载

如果用户想要移除此功能：

1. 从 `.claude/settings.json` 中删除 `Stop` hook 条目
2. 删除 `.specstory/sync_to_spec.py`
3. （可选）删除 `.specstory/history/` 下的 `.*.fp` fingerprint 文件
4. （可选）删除生成的 Markdown 文件