AI History Auto Record（AI历史自动记录）

🤖 Automatically track and snapshot AI code changes with Shadow Git. Supports manual & auto mode, Claude Code hooks integration. | 自动跟踪和快照AI代码的变化与影子Git。支持手动和自动模式，Claude Code hooks集成。
项目地址：[ai-history-auto-record](https://github.com/guoqw7/ai-history-auto-record/blob/HEAD/https:/github.com/guoqw7/ai-history-auto-record)

中文文档

功能特性

特性	说明
🎬 自动录制	自动追踪文件变更，无需手动干预
🖐️ 手动快照	保留手动模式，精确控制快照时机
🪝 Claude 钩子	支持 `SessionStart` / `SessionEnd` 钩子，无缝集成 Claude Code
📝 Markdown 摘要	每次会话生成易读的 `AI_Summary.md`，含 Before/After 对比
🔧 Git Patch	生成标准 `changes.patch`，可直接 `git apply`
📊 结构化元数据	`metadata.json` 记录会话信息，为未来图形化面板提供数据
⏪ 一键回滚	在 AI_Summary.md 中点击按钮即可回滚到改前状态
🌐 双语 UI	中文 + 英文界面，自动跟随 VS Code 语言
📁 干净存储	所有快照存在 `.vscode/.ai-history-auto-record/`，不污染项目根目录

安装方式

方式一：本地安装（推荐）

# 1. 编译插件
cd ai-history-auto-record
pnpm install
pnpm run compile

# 2. 复制到 VS Code 扩展目录
# Windows PowerShell:
Copy-Item -Recurse . "$env:USERPROFILE\.vscode\extensions\local-dev.ai-history-auto-record-0.0.1"

# macOS / Linux:
cp -r . ~/.vscode/extensions/local-dev.ai-history-auto-record-0.0.1/

# 3. 重启 VS Code

方式二：开发模式运行

cd ai-history-auto-record
pnpm install
pnpm run watch

# 然后按 F5 启动扩展开发窗口

前置要求

Git CLI 必须安装且可在终端中直接调用（git --version 能正常输出）
VS Code ^1.85.0

快速上手

自动模式（默认开启）

打开 VS Code 项目 → 插件自动激活，状态栏显示「AI 录制中」
使用 Claude Code 或其他 AI 工具修改代码 → 插件自动监听文件保存
按 Ctrl+Alt+Shift+S 或点击编辑器右上角 🔴 按钮 → 结束会话，生成报告
插件自动打开 AI_Summary.md，展示 Before/After 对比

手动模式

① Ctrl+Alt+A（拍快照）
   ↓  拍下 AI 修改前的代码状态
② 让 AI 改代码
   ↓  Claude Code / Copilot / 手动编辑
③ Ctrl+Alt+S（保存变更）
   ↓  弹出 Prompt 输入框 → 填写你给 AI 的指令
④ 自动生成 AI_Summary.md → 查看差异

⚠️ 操作顺序很重要！ 必须先拍快照，再让 AI 修改。如果先改了再拍快照，diff 为空。

自动模式

自动模式是本插件的核心创新。启用后，插件在激活时自动开始一个「会话」，持续监听文件变更。

工作流程

VS Code 启动 → 自动开始会话 → 拍摄初始快照
                ↓
         AI 修改文件（自动追踪）
                ↓
         结束会话（手动 / Claude 钩子自动触发）
                ↓
         生成报告（AI_Summary.md + changes.patch + metadata.json）

切换模式

命令面板：AI Record: Toggle Auto/Manual Mode
或直接修改 VS Code 设置："aiHistoryAutoRecord.autoMode": true/false

Claude Code 钩子配置

让 Claude Code 在每次会话开始/结束时自动触发快照。

配置步骤

在项目根目录的 .claude/settings.local.json 中添加：

{
  "hooks": {
    "SessionStart": [
      {
        "command": "code --command ai-history-auto-record.startSession"
      }
    ],
    "SessionEnd": [
      {
        "command": "code --command ai-history-auto-record.endSession"
      }
    ]
  }
}

效果

时机	自动执行
Claude Code 会话开始	自动拍摄项目快照
Claude Code 会话结束	自动生成差异报告

输出文件说明

每次会话在 .vscode/.ai-history-auto-record/<时间戳>/ 下生成三个文件：

.vscode/.ai-history-auto-record/2026-06-02_16-28-33/
├── AI_Summary.md      # Markdown 摘要（人类阅读）
├── changes.patch      # Git 兼容补丁（机器处理）
└── metadata.json      # 结构化元数据（GUI 消费）

AI_Summary.md

> 💬 **Prompt:** *帮我添加三日天气预报*

---
## 📄 File: `weather-log/2026-06-02-weather.md`
> 📍 变更位置：约第 17 行

**❌ 修改前（Before AI）：**
```markdown
## 备注
（自由记录）

✅ 修改后（After AI）：

## 未来三日预报
| 日期 | 天气 | 温度 |
|------|------|------|
| ... |


### changes.patch

标准 unified diff 格式，可被任何 Git 工具消费：

```bash
# 查看补丁内容
git apply --stat changes.patch

# 应用补丁
git apply changes.patch

metadata.json

{
  "version": "0.0.1",
  "mode": "auto",
  "timestamp": "2026-06-02T08:28:33.000Z",
  "sessionId": "2026-06-02_16-28-33",
  "prompt": "帮我添加三日天气预报",
  "files": ["weather-log/2026-06-02-weather.md"]
}

回滚操作

如果 AI 的修改不理想，可以一键回滚：

在 VS Code 中打开 .vscode/.ai-history-auto-record/<时间戳>/AI_Summary.md
点击编辑器右上角的 🔄 回滚按钮
文件恢复到 AI 修改前的状态
摘要文件中自动添加 🛑 REVERTED 标记

⚠️ 回滚后如果手动修改了文件，再次回滚可能因冲突失败。建议在回滚前确认文件未被二次修改。

扩展配置

配置项	类型	默认值	说明
`aiHistoryAutoRecord.autoMode`	boolean	`true`	是否启用自动录制模式
`aiHistoryAutoRecord.storagePath`	string	`.vscode/.ai-history-auto-record`	快照存档路径（相对于项目根目录）
`aiHistoryAutoRecord.watchDebounceMs`	number	`1000`	文件保存防抖延迟（毫秒）

快捷键

快捷键	命令	说明
`Ctrl+Alt+Shift+A`	开始会话	自动模式：启动录制会话
`Ctrl+Alt+Shift+S`	结束会话	自动模式：结束会话并生成报告
`Ctrl+Alt+A`	手动快照	手动模式：拍摄 AI 修改前的代码状态
`Ctrl+Alt+S`	保存变更	手动模式：对比差异并生成报告
（在 AI_Summary.md 中）	回滚按钮	点击编辑器右上角 🔄 按钮

常见问题

Q: 为什么 `.vscode/.ai-shadow/` 是空的或不存在？

A: .ai-shadow/ 是临时目录，只在会话期间存在。会话结束后自动删除。这是正常行为。

Q: 为什么我看不到任何 AI_Summary.md？

A: 检查操作顺序是否正确：先拍快照 → 再改代码 → 最后保存。如果顺序反了，diff 为空，不会生成报告。

Q: 如何在 Windows 资源管理器中查看快照？

A: 快照存储在 .vscode/.ai-history-auto-record/，在 VS Code 文件浏览器中可直接浏览和打开。

Q: 支持哪些编程语言的语法高亮？

A: 支持 20+ 种语言：TypeScript、JavaScript、Python、Rust、Go、Java、HTML、CSS、Vue、Svelte 等。语言根据文件扩展名自动检测。

Q: 如何排除不需要追踪的目录？

A: 在项目根目录创建 .aiignore 文件（格式同 .gitignore），或在 .gitignore 中添加规则。内置默认排除 .git、.vscode/.ai-shadow、.vscode/.ai-history-auto-record。

重点难点

1. 钩子与扩展的通信方式

问题： Claude Code 钩子运行 shell 命令，需要将事件通知给同一台机器上的 VS Code 扩展。

方案对比：

方案	问题
`code --command`	会打开新的 VS Code 窗口，无法发给当前窗口
信号文件轮询	需要文件系统轮询，延迟高、可靠性差
HTTP Server	过度设计，TCP 已足够
✅ TCP 127.0.0.1	轻量、可靠、零依赖，`node -e "net.connect()"` 一行搞定

实现： 扩展启动时在 127.0.0.1 随机端口创建 TCP Server。端口号写入 .vscode/.ai-record-port。钩子脚本读取端口后 net.connect(port).end('start') 发消息。

2. git add 反复失败的排查过程

症状： git add . 在终端执行成功（exit 0），但在 Node.js cp.exec 中始终 exit ≠ 0。

排查链路：

Shell Profile 污染 → stderr 超 maxBuffer → 改用 execFile 绕过 shell
execFile 丢环境变量 → PATH/TEMP 缺失导致 git 写对象失败 → 回退 exec（50MB buffer）
safecrlf=true（用户全局配置）→ CRLF 警告变硬错误 exit 1 → 加 -c core.safecrlf=false
advice.addIgnoredFile → pathspec 和 .gitignore 重叠时 git 输出 hint 并 exit 1 → 加 -c advice.addIgnoredFile=false
node_modules 未排除 → git add 尝试写入数千个文件 → .gitignore 加 node_modules/
pathspec 与 .gitignore 冲突 → 两者同时排除同一路径导致 exit 1 → pathspec 精简为仅 .git + .claude

最终稳定的 git 命令前缀： git -c core.safecrlf=false -c advice.addIgnoredFile=false

3. Windows 路径长度限制

影子 Git 最初放在 .vscode/.ai-shadow/，导致 Windows 上路径超过 260 字符限制，git add 写入对象时报 unable to create temporary file。最终移到项目根目录 .ai-shadow/，大幅缩短路径。

4. 为什么 prompt 抓取用 UserPromptSubmit 而非 SessionStart

SessionStart 的 stdin JSON 不含 prompt 字段——仅包含 session_id、cwd 等会话元数据
UserPromptSubmit 的 stdin JSON 直接包含 "prompt": "用户原始消息"——完美匹配需求
UserPromptSubmit 只在用户真正发送消息时触发，不会像 SessionStart(resume) 在 VS Code 启动时误触发

English Documentation

Features

Feature	Description
🎬 Auto Recording	Automatically tracks file changes with zero manual intervention
🖐️ Manual Snapshots	Manual mode retained for precise snapshot timing
🪝 Claude Hooks	First-class `SessionStart` / `SessionEnd` hook support for Claude Code
📝 Markdown Summaries	Human-readable `AI_Summary.md` with Before/After code blocks
🔧 Git Patch Files	Standard `changes.patch` — directly consumable by `git apply`
📊 Structured Metadata	`metadata.json` records session info for future GUI integration
⏪ One-Click Rollback	Click the revert button in AI_Summary.md to undo AI changes
🌐 Bilingual UI	Chinese + English interface, auto-follows VS Code language
📁 Clean Storage	All snapshots live in `.vscode/.ai-history-auto-record/` — no root pollution

Installation

Option 1: Local Install (Recommended)

# 1. Compile the extension
cd ai-history-auto-record
pnpm install
pnpm run compile

# 2. Copy to VS Code extensions directory
# Windows PowerShell:
Copy-Item -Recurse . "$env:USERPROFILE\.vscode\extensions\local-dev.ai-history-auto-record-0.0.1"

# macOS / Linux:
cp -r . ~/.vscode/extensions/local-dev.ai-history-auto-record-0.0.1/

# 3. Restart VS Code

Option 2: Development Mode

cd ai-history-auto-record
pnpm install
pnpm run watch

# Press F5 to launch Extension Development Host

Prerequisites

Git CLI must be installed and accessible in PATH (git --version should work)
VS Code ^1.85.0

Quick Start

Auto Mode (Enabled by Default)

Open a VS Code project → extension auto-activates, status bar shows "AI Recording..."
Use Claude Code or any AI tool to modify files → extension watches saves automatically
Press Ctrl+Alt+Shift+S or click the editor toolbar button → End Session, generate report
AI_Summary.md opens automatically, showing Before/After comparisons

Manual Mode

① Ctrl+Alt+A (Snapshot)
   ↓  Captures code state BEFORE AI modifications
② Let AI modify the code
   ↓  Claude Code / Copilot / manual edits
③ Ctrl+Alt+S (Save Changes)
   ↓  Enter the prompt you gave to the AI
④ AI_Summary.md auto-generated → review the diff

⚠️ Order matters! Snapshot first, then AI changes. Reversing the order results in an empty diff.

Auto Mode

Auto mode is the core innovation of this extension. When enabled, the extension automatically starts a "session" on activation and continuously monitors file changes.

Workflow

VS Code Launch → Auto-start session → Take initial snapshot
                        ↓
                AI modifies files (auto-tracked)
                        ↓
           End session (manual or via Claude hooks)
                        ↓
        Generate report (AI_Summary.md + changes.patch + metadata.json)

Toggle Mode

Command Palette: AI Record: Toggle Auto/Manual Mode
Or edit VS Code settings: "aiHistoryAutoRecord.autoMode": true/false

Claude Code Hooks Setup

Automatically trigger snapshots when Claude Code sessions start and end.

Configuration

Add the following to .claude/settings.local.json in your project root:

{
  "hooks": {
    "SessionStart": [
      {
        "command": "code --command ai-history-auto-record.startSession"
      }
    ],
    "SessionEnd": [
      {
        "command": "code --command ai-history-auto-record.endSession"
      }
    ]
  }
}

What Happens

Event	Automatic Action
Claude Code session starts	Full project snapshot taken
Claude Code session ends	Diff report generated automatically

Output Files

Each session produces three files under .vscode/.ai-history-auto-record/<timestamp>/:

.vscode/.ai-history-auto-record/2026-06-02_16-28-33/
├── AI_Summary.md      # Markdown summary (human-readable)
├── changes.patch      # Git-compatible patch (machine-consumable)
└── metadata.json      # Structured metadata (GUI-ready)

AI_Summary.md

Human-readable Markdown with syntax-highlighted Before/After code blocks. See Chinese section above for a detailed example.

changes.patch

Standard unified diff format, consumable by any Git tool:

# Inspect the patch
git apply --stat changes.patch

# Apply the patch
git apply changes.patch

metadata.json

Structured JSON providing session metadata for future GUI integration. See Chinese section above for the schema.

Rollback

If the AI's changes aren't satisfactory, rollback with one click:

Open .vscode/.ai-history-auto-record/<timestamp>/AI_Summary.md in VS Code
Click the 🔄 Revert button in the editor toolbar
Files are restored to their pre-AI state
A 🛑 REVERTED badge is automatically injected into the summary

⚠️ If files are manually edited after the rollback point, the reverse patch may fail due to merge conflicts. Rollback immediately if you don't like the AI's output.

Extension Settings

Setting	Type	Default	Description
`aiHistoryAutoRecord.autoMode`	boolean	`true`	Enable automatic recording mode
`aiHistoryAutoRecord.storagePath`	string	`.vscode/.ai-history-auto-record`	Storage path for snapshots (relative to project root)
`aiHistoryAutoRecord.watchDebounceMs`	number	`1000`	Debounce delay for file save events (ms)

Keyboard Shortcuts

Shortcut	Command	Description
`Ctrl+Alt+Shift+A`	Start Session	Auto mode: begin recording session
`Ctrl+Alt+Shift+S`	End Session	Auto mode: end session & generate report
`Ctrl+Alt+A`	Manual Snapshot	Manual mode: snapshot code before AI changes
`Ctrl+Alt+S`	Save Changes	Manual mode: diff changes & generate report
(in AI_Summary.md)	Rollback Button	Click the 🔄 button in the editor toolbar

FAQ

Q: Why is `.vscode/.ai-shadow/` empty or missing?

A: .ai-shadow/ is a temporary directory that only exists during an active session. It's automatically cleaned up when the session ends. This is expected behavior.

Q: I don't see any AI_Summary.md files. Why?

A: Check your operation order: snapshot first → then modify code → then save. If reversed, the diff will be empty and no report is generated.

Q: How do I view snapshots in Windows Explorer?

A: Snapshots are stored at .vscode/.ai-history-auto-record/. You can browse and open them directly in VS Code's file explorer.

Q: What languages are supported for syntax highlighting?

A: 20+ languages including TypeScript, JavaScript, Python, Rust, Go, Java, HTML, CSS, Vue, Svelte, and more. Language is auto-detected from the file extension.

Q: How do I exclude directories from tracking?

A: Create an .aiignore file in your project root (same format as .gitignore), or add rules to .gitignore. The following are always excluded: .git, .vscode/.ai-shadow, .vscode/.ai-history-auto-record.

Key Challenges

1. Hook-to-Extension Communication

Problem: Claude Code hooks run shell commands. How to notify the VS Code extension?

Comparison:

Approach	Issue
`code --command`	Opens a NEW VS Code window, not the existing one
Signal file polling	Filesystem polling — high latency, unreliable
HTTP Server	Overengineered for the task
✅ TCP 127.0.0.1	Lightweight, reliable, zero dependencies

Implementation: Extension starts a TCP server on 127.0.0.1 with a random port. The port is written to .vscode/.ai-record-port. Hook scripts read the port and connect via net.connect(port).end('start').

2. git add Debugging Journey

Symptom: git add . works in terminal (exit 0) but fails inside Node.js cp.exec (exit ≠ 0).

Debugging chain:

Shell profile noise → stderr overflow → tried execFile to bypass shell
execFile missing env → PATH/TEMP lost on Windows → git object write failure → back to exec (50MB buffer)
safecrlf=true (user global config) → CRLF warnings treated as errors → added -c core.safecrlf=false
advice.addIgnoredFile → pathspec & .gitignore overlap triggers hint + exit 1 → added -c advice.addIgnoredFile=false
node_modules not excluded → git add tries to hash thousands of files → added node_modules/ to .gitignore
pathspec conflict with .gitignore → both excluding the same path → exit 1 → pathspec reduced to .git + .claude

Final stable git prefix: git -c core.safecrlf=false -c advice.addIgnoredFile=false

3. Windows Path Length Limit

Shadow git was initially placed at .vscode/.ai-shadow/. On Windows, this path exceeded the 260-character limit, causing git add to fail with unable to create temporary file. Moved to project root .ai-shadow/, significantly shortening the path.

4. Why UserPromptSubmit for Prompt Capture

SessionStart stdin JSON does NOT contain the prompt field — only session metadata (session_id, cwd)
UserPromptSubmit stdin JSON directly contains "prompt": "user's raw message" — exactly what's needed
UserPromptSubmit only fires when the user actually sends a message, unlike SessionStart(resume) which also fires on VS Code startup

📄 License

GPL-3.0

Made with ❤️ for the AI-assisted development workflow.

AI History Auto Record（AI历史自动记录）

guoking

AI History Auto Record（AI历史自动记录）

📖 目录 / Table of Contents

中文文档

功能特性

安装方式

方式一：本地安装（推荐）

方式二：开发模式运行

前置要求

快速上手

自动模式（默认开启）

手动模式

自动模式

工作流程

切换模式

Claude Code 钩子配置

配置步骤

效果

输出文件说明

AI_Summary.md

metadata.json

回滚操作

扩展配置

快捷键

常见问题

Q: 为什么 .vscode/.ai-shadow/ 是空的或不存在？

Q: 为什么我看不到任何 AI_Summary.md？

Q: 如何在 Windows 资源管理器中查看快照？

Q: 支持哪些编程语言的语法高亮？

Q: 如何排除不需要追踪的目录？

重点难点

1. 钩子与扩展的通信方式

2. git add 反复失败的排查过程

3. Windows 路径长度限制

4. 为什么 prompt 抓取用 UserPromptSubmit 而非 SessionStart

English Documentation

Features

Installation

Option 1: Local Install (Recommended)

Option 2: Development Mode

Prerequisites

Quick Start

Auto Mode (Enabled by Default)

Manual Mode

Auto Mode

Workflow

Toggle Mode

Claude Code Hooks Setup

Configuration

What Happens

Output Files

AI_Summary.md

changes.patch

metadata.json

Rollback

Extension Settings

Keyboard Shortcuts

FAQ

Q: Why is .vscode/.ai-shadow/ empty or missing?

Q: I don't see any AI_Summary.md files. Why?

Q: How do I view snapshots in Windows Explorer?

Q: What languages are supported for syntax highlighting?

Q: How do I exclude directories from tracking?

Key Challenges

1. Hook-to-Extension Communication

2. git add Debugging Journey

3. Windows Path Length Limit

4. Why UserPromptSubmit for Prompt Capture

📄 License

Q: 为什么 `.vscode/.ai-shadow/` 是空的或不存在？

Q: Why is `.vscode/.ai-shadow/` empty or missing?