🔥 痛点预警：你是否曾为找一段 AI 给的完美代码，在 Cursor 聊天记录里上翻下翻，最后眼睁睁看着会话超时清空？又或者想复盘某个 Bug 的解决过程，却只能凭记忆东拼西凑？今天推荐的这个开源小工具 sync-transcript，就是来终结这场噩梦的。它能自动将你与 AI Agent 的每一次对话，按日期和会话 ID 保存到项目的 chat/ 目录中，从此聊天记录即代码，版本管理、团队复盘、知识沉淀全搞定。

---

📌 一、这是什么？

一句话概括：sync-transcript 是一款基于 Cursor/Claude Code Hooks 机制的会话自动存档工具，由开发者 HLX 开源并维护。

它的核心思路非常简单——在 AI 助手每次回复完毕后（或会话停止时），自动将当前对话内容同步到项目内的 chat/YYYYMMDD--<conversation_id>.md（或 .txt）文件中，方便后续进行 Git 版本管理、全文检索与团队知识共享。

为什么需要它？

痛点	sync-transcript 解决方案
找历史对话像大海捞针	chat/ 目录下按日期+会话 ID 命名，一目了然
换设备/重装环境后聊天记录丢失	文件随项目走，永不丢失
团队协作时无法共享 AI 交互过程	将 chat/ 纳入 Git，全团队可见
想复盘 AI 的解题思路但无处可查	Markdown 格式导出，支持全文搜索

---

📌 二、支持哪些工具？

目前 sync-transcript 已适配两大主流 AI 编程工具，覆盖绝大多数开发者的使用场景：

工具	Hook 时机	配置文件	输出格式
Cursor	每轮助手回复后 (afterAgentResponse)	.cursor/hooks.json	Markdown（.md）
Claude Code	会话停止时 (Stop)	.claude/settings.json	终端风格纯文本（.txt）

💡 特别提醒：Cursor 导出的是类官方 Export Transcript 风格的 Markdown，排版美观、层次分明；Claude Code 则导出与终端 /export 一致的纯文本格式，原生风格、简洁干练。

---

📌 三、极速安装（两种方式任选）

🚀 方式一：自动安装（推荐）

直接将以下指令完整复制给 Cursor Agent（或 Claude Code Agent），它就会自动完成全部部署：

Cursor 用户请复制这段：

请在本项目（当前工作区根目录）安装 Cursor 会话同步 Hook：
打开 GitHub 仓库 https://github.com/hlx-statistics/sync-transcript.git ，
严格按该仓库 README 里「Cursor › 给 Cursor Agent 的安装任务说明」执行；
从当前分支拉取 .cursor/hooks/sync-transcript.mjs 并合并 .cursor/hooks.json，
不要覆盖我已有的其它 Hook。

Claude Code 用户请复制这段：

请在本项目（当前工作区根目录）安装 Claude Code 会话同步 Hook：
打开 GitHub 仓库 https://github.com/hlx-statistics/sync-transcript.git ，
严格按该仓库 README 里「Claude Code › 给 Claude Code Agent 的安装任务说明」执行；
从当前分支拉取 .claude/hooks/sync-export.mjs 并合并 .claude/settings.json 的 hooks.Stop，
不要覆盖我已有的其它 Hook。

✅ Agent 会自动完成：创建目录 → 拉取脚本 → 合并配置文件（幂等操作，已有 Hook 不会被覆盖）。

---

🛠️ 方式二：手动安装（适合喜欢掌控感的同学）

Cursor 手动安装

Step 1：将仓库中的 sync-transcript.mjs 保存为 .cursor/hooks/sync-transcript.mjs。

Step 2：编辑 .cursor/hooks.json，内容如下（若文件已存在，只追加 afterAgentResponse 数组项，勿覆盖原有内容）：

{
  "version": 1,
  "hooks": {
    "afterAgentResponse": [
      {
        "command": "node .cursor/hooks/sync-transcript.mjs"
      }
    ]
  }
}

Claude Code 手动安装

Step 1：将仓库中的 sync-export.mjs 保存为 .claude/hooks/sync-export.mjs。

Step 2：编辑 .claude/settings.json，内容如下：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/sync-export.mjs"
          }
        ]
      }
    ]
  }
}

---

📌 四、效果自检与排错指南

安装完成后，随便跟 AI 对话一轮，然后检查项目根目录：

• Cursor 用户：应出现 chat/YYYYMMDD--<conversation_id>.md 文件
• Claude Code 用户：应出现 chat/YYYYMMDD--<conversation_id>.txt 文件

⚠️ 常见问题排查

问题	解决方案
对话结束但 chat/ 目录无文件生成	① 检查 node 是否在 PATH 中（终端运行 node -v 验证） ② 重启 Cursor / Claude Code 后再试
报错 “cannot find module”	确认 .cursor/hooks/sync-transcript.mjs 文件路径正确（相对于项目根目录）
想排除某些文件不提交 Git	在 .gitignore 中添加 chat/ 即可

---

📌 五、进阶玩法：环境变量自定义（Claude Code 专属）

Claude Code 用户可以通过环境变量灵活控制导出行为：

环境变量	作用	默认值
CLAUDE_EXPORT_DIR	自定义导出目录	/chat
CLAUDE_EXPORT_FILE	固定输出文件名（设置后忽略日期/会话命名）	无（按日期+会话 ID 自动命名）
CLAUDE_EXPORT_INCLUDE_EXPORT	设为 1 时保留 /export 类 slash 命令	0（跳过）

💡 实用技巧：如果你想将某次重要对话固定保存为 important-debug.md，只需设置 CLAUDE_EXPORT_FILE=important-debug.md 即可。

---

📌 六、项目结构一览

了解项目文件结构有助于二次开发或手动排错：

路径	说明
.cursor/hooks.json	Cursor Hook 注册配置（afterAgentResponse）
.cursor/hooks/sync-transcript.mjs	Cursor 导出脚本（输出 .md）
.claude/settings.json	Claude Code Hook 注册配置（Stop）
.claude/hooks/sync-export.mjs	Claude Code 导出脚本（输出 .txt）
chat/	导出目录（.md 与 .txt 可共存）
LICENSE	MIT 许可证

📄 本项目采用 MIT License 开源，Copyright © 2026 HLX，可放心用于个人和商业项目。

---

📌 七、总结：你的 AI 编程“黑匣子”

sync-transcript 彻底解决了 AI 编程时代开发者共有的一个隐痛：聊天记录无法持久化、无法版本管理。它通过极简的 Hook 机制，将每一次人机协作的思维过程完整保存，让你的项目不仅拥有代码资产，更拥有宝贵的交互上下文。

🎯 适用场景

• 个人开发者：随时回溯 AI 的解题思路，积累调试经验
• 团队协作：共享 AI 对话记录，提升集体知识密度
• 代码审计：追溯某段代码的生成过程与上下文
• 学习复盘：复习与 AI 的交互过程，提升 Prompt 工程能力

🔗 仓库地址

👉 GitHub：https://github.com/hlx-statistics/sync-transcript.git

👍 如果觉得有用，点赞 + 收藏 + 关注 三连走起！有问题欢迎评论区交流讨论，一起让 AI 编程更高效 🚀