AI编码审计工具whatdiditdo：高效复盘与安全审查指南-平芜编程栈

1. 项目概述：当AI替你写代码后，如何快速复盘？

作为一名每天和代码打交道的开发者，我最近遇到了一个甜蜜的烦恼：AI编码助手（比如Cursor、GitHub Copilot、Claude Code）用得太顺手了，它们噼里啪啦一顿输出，改了一堆文件。等回过神来，我常常会陷入一种“代码失忆症”——我到底让它改了啥？新增了哪些依赖？有没有不小心把API密钥给提交了？手动去git diff一个个文件看，既费时又容易遗漏关键改动。

直到我发现了whatdiditdo这个命令行工具，它完美地解决了这个痛点。简单来说，它就是一个专为“AI编码会话”设计的Git变更审计工具。你只需要在AI助手完成工作、提交代码后，在项目根目录运行一条命令，它就能给你一份清晰、全面的变更报告。这不仅仅是git log的简单美化，它集成了AI总结、安全扫描、一键生成PR描述等实用功能，让你能快速理解、审查并分享AI的“劳动成果”。无论你是独立开发者，还是团队协作中需要Review AI生成的代码，这个工具都能显著提升你的工作流效率和代码安全感。

2. 核心功能与设计思路拆解

whatdiditdo的设计哲学非常明确：为AI编码后的混乱带来秩序。它没有试图成为一个全能的Git客户端，而是精准地聚焦于“事后审计”这个场景。下面我们来拆解它的核心设计思路。

2.1 定位：专为AI编码场景优化的Git审计

传统的Git工具（如git diff,git log --stat）是通用的，它们展示所有类型的提交。而whatdiditdo假设了一个特定场景：刚刚发生了一次由AI主导的、可能涉及多个文件的密集编码活动。在这个场景下，用户的核心需求是什么？

快速概览：我不需要看完整的diff，但我需要知道哪些文件被动了，增删了多少行。
理解意图：AI的提交信息可能很模糊（比如“fix bug”或“update”），我需要一个“人话”总结，告诉我这组改动的实际目的。
安全兜底：AI可能会“好心”地引入硬编码的密钥，或者修改了.env配置文件，这是高风险行为，必须被高亮。
无缝集成：审计动作应该能无缝嵌入现有工作流，比如一键生成PR描述、自动安装Git钩子。

whatdiditdo的所有功能都围绕着这几点展开。它通过分析最近一次提交（或指定数量的提交）的差异，来构建这份审计报告。这种“面向最近事件”的设计，使其响应速度极快，几乎能瞬间给出结果。

2.2 核心功能模块解析

基于上述需求，whatdiditdo将功能模块化，你可以通过不同的命令行标志来组合使用。

基础审计 (npx whatdiditdo): 这是默认模式。它会分析上次提交，输出一个包含文件列表、行数统计、新增依赖和安全警告的概览。最亮眼的是，它会调用一个AI接口（需要额外配置），用自然语言生成一段变更总结，例如“添加了用户登录功能，包括JWT令牌验证和密码哈希”。
PR描述生成 (--pr): 这是我认为的“杀手级”功能。在团队协作中，为AI的提交撰写清晰的PR描述是个苦差事。这个标志能直接生成一个包含标题、正文、文件变更表、依赖列表和安全检查清单的Markdown文本，你可以直接粘贴到GitHub、GitLab等平台的PR描述框中。
安全扫描 (内置): 安全不是可选项，而是默认项。每次运行都会扫描变更内容，寻找硬编码的API密钥（如sk-开头的OpenAI密钥）、私钥文件、对.env文件的修改，以及URL中可能包含的凭证。这相当于为每次AI编码会话增加了一道自动化的安全门禁。
交互式回滚 (--undo): AI并不总是对的。这个功能提供了一个安全的回滚界面。运行npx whatdiditdo --undo会列出所有被更改的文件，并显示预览。你可以选择回滚单个文件，或者一次性回滚整个提交，避免了使用git reset时可能发生的误操作。

注意：AI总结功能依赖于外部的AI CLI工具（如OpenAI API）。如果你没有配置或不想使用，可以用--no-ai标志跳过，工具依然会提供完整的结构化数据。

3. 从零开始：安装、配置与核心使用详解

whatdiditdo是一个基于Node.js的命令行工具，它的使用极其简单，但为了发挥最大效用，一些初始配置是必要的。下面我将带你完成从安装到高效使用的全过程。

3.1 环境准备与“安装”

严格来说，whatdiditdo不需要“安装”。它通过npx运行，这是一个随Node.js附带的工具，用于执行npm包中的命令。这意味着你只需要满足两个前提：

Node.js 18+: 确保你的系统安装了Node.js，且版本不低于18。你可以在终端输入node -v来检查。
Git仓库: 你必须在某个Git仓库的根目录下运行这个工具，因为它需要读取Git历史记录。

这就是全部了。无需npm install whatdiditdo，直接使用npx调用即可。这种设计降低了使用门槛，也避免了全局安装带来的版本污染。

3.2 基础使用与输出解读

让我们从一个最简单的场景开始。假设你刚刚用Cursor的Chat功能重构了一个模块，并完成了提交。

打开终端，导航到你的项目根目录。
运行基础命令：
```
npx whatdiditdo
```

你会立刻看到一个结构清晰的输出。以下是一个模拟示例，我们来逐块解读：

🔍 Audit for commit: a1b2c3d (HEAD -> main) 📅 2023-10-27 11:23:45 🤖 AI Agent detected: Cursor 📊 **变更统计** ┌────────────────────┬────────────┐ │ 文件 │ 变更行数 │ ├────────────────────┼────────────┤ │ src/auth.js │ +45 -12 │ │ package.json │ +2 -0 │ │ .env.example │ +5 -0 │ │ README.md │ +8 -3 │ └────────────────────┴────────────┘ ✅ 总计: 4个文件, +60行新增, -15行删除 🔐 **安全扫描** ⚠️ 警告: `.env.example` 被修改。请检查是否包含真实密钥。 ✅ 未检测到硬编码的API密钥或私钥。 📦 **依赖变更** + 新增: `jsonwebtoken@^9.0.0` + 新增: `bcrypt@^5.1.0` 🧠 **AI总结** 本次提交主要实现了用户认证系统的核心功能。在`src/auth.js`中引入了JWT（JSON Web Tokens）用于生成和验证登录令牌，并集成了bcrypt库对用户密码进行安全哈希处理。同时更新了相关环境变量示例文件和项目说明文档。 💬 **快速分享摘要** 📊 4 files · +60 -15 · 2 new deps · 🔐 1 warning

头部信息：告诉你审计的是哪个提交、时间以及工具检测到的AI代理（如果可用）。
变更统计表：一目了然地看到所有变动的文件及具体的增删行数。+45 -12表示新增了45行，删除了12行。
安全扫描：这是关键。它提示.env.example被修改了。虽然这只是示例文件，但这是一个重要的提醒，你需要确认没有敏感信息被意外提交。
依赖变更：清晰地列出package.json中新增的依赖项。这能帮你快速评估本次改动引入了哪些新的第三方库。
AI总结：用一段流畅的文字概括了这次提交的“目的”，即使提交信息写的是“update auth”，你也能立刻明白发生了什么。
快速分享摘要：最后一行是一个浓缩的emoji摘要，方便你复制粘贴到Slack或Discord等聊天工具中，向团队同步进度。

3.3 核心标志（Flags）实战指南

whatdiditdo的强大之处在于其丰富的标志，让你能定制审计输出。下面是一些最常用和实用的组合。

3.3.1 生成即用型PR描述 (--pr)这是团队协作的利器。运行后，它会生成一个完整的Markdown格式的PR描述。

npx whatdiditdo --pr

输出内容可以直接粘贴到GitHub或GitLab的PR描述框里。它通常包括：

PR标题：基于变更内容生成的建议标题。
概述：AI生成的总结。
变更文件表：格式化的Markdown表格。
新依赖列表。
安全检查清单：提醒审查者注意安全项。
测试计划建议：一个勾选框列表，引导提交者补充测试信息。

一个更高效的技巧是结合系统剪贴板命令，实现一键复制：

# 在macOS上 npx whatdiditdo --pr --no-ai | pbcopy # 在Linux上（需要安装xclip） npx whatdiditdo --pr --no-ai | xclip -selection clipboard # 在Windows PowerShell上 npx whatdiditdo --pr --no-ai | Set-Clipboard

使用--no-ai可以跳过可能较慢的AI总结，快速获取结构化内容并复制。

3.3.2 审计历史提交 (--last N)AI可能进行了多次提交。你可以审计最近N次提交的累积效果。

# 查看最近3次提交的总体变更 npx whatdiditdo --last 3

这个命令会聚合这3次提交的所有变更，给你一个整体的视图，非常适合在完成一个功能分支后，进行合并前的最终审查。

3.3.3 安全回滚AI改动 (--undo)当AI的改动引入问题时，回滚需要谨慎。

查看并选择回滚：
```
npx whatdiditdo --undo
```
这会列出所有被更改的文件，并给每个文件编号。你可以选择回滚单个文件（npx whatdiditdo --undo 2回滚列表中的第2个文件），或者使用npx whatdiditdo --undo all回滚整个提交。
实操心得：--undo命令内部使用的是git checkout HEAD~1 -- <file>来恢复单个文件，或git revert HEAD来创建一个反向提交。相比直接使用git reset --hard HEAD~1，这种方式更安全，因为它不会销毁提交历史，而是创建一个新的“撤销”提交，保留了整个变更记录，便于后续追溯。

3.3.4 自动化与集成

安装Git钩子 (--hook): 如果你希望每次提交后都自动运行审计，可以安装一个post-commit钩子。
```
npx whatdiditdo --hook
```
安装后，每次git commit成功，终端都会自动显示一份whatdiditdo报告。用--unhook可以移除它。
注意：对于频繁提交的工作流，这可能会有些干扰。更推荐在完成一个阶段性任务（即一次AI编码会话）后手动运行。
发送通知到协作工具 (--notify <url>): 可以将审计报告发送到Slack、Discord等工具的Webhook。
```
npx whatdiditdo --notify https://hooks.slack.com/services/your/webhook/url
```
这对于远程团队或需要将AI编码活动日志化的场景非常有用。

4. 高级技巧与集成方案

掌握了基础用法后，我们可以探索一些高级技巧，将whatdiditdo深度集成到你的开发工作流中，使其价值最大化。

4.1 构建定制化的AI编码审计流水线

你可以将whatdiditdo与Shell别名、脚本或Makefile结合，创建属于你自己的快捷命令。

创建Shell别名：在你的~/.zshrc或~/.bashrc文件中添加：

alias wdid='npx whatdiditdo' alias wdid-pr='npx whatdiditdo --pr --no-ai | pbcopy && echo "PR描述已复制到剪贴板！"' alias wdid-undo='npx whatdiditdo --undo'

这样，你只需要输入wdid、wdid-pr或wdid-undo即可快速执行对应命令。

集成到项目脚本中：在项目的package.json的scripts字段里添加：
```
{ "scripts": { "postcommit": "npx whatdiditdo --no-ai", "review-ai": "npx whatdiditdo --last 5 --web", "generate-pr": "npx whatdiditdo --pr > pr_description.md" } }
```
- postcommit：利用npm的生命周期钩子，在每次npm run commit（如果你用了commitizen等工具）后自动运行轻量审计（跳过AI总结以加快速度）。
- review-ai：一键在浏览器中打开最近5次提交的HTML报告，进行可视化审查。
- generate-pr：将生成的PR描述直接输出到pr_description.md文件中，方便编辑。

4.2 与其他开发工具的组合拳

whatdiditdo并非孤岛，它可以成为你工具链中承上启下的一环。

与dependabot或renovate配合：当这些自动化依赖更新工具提交PR后，你可以用whatdiditdo --last 1快速查看具体更新了哪些依赖项及其版本，比直接看package.json的diff更直观。
作为Code Review的前置步骤：在团队中，可以约定：所有包含AI生成代码的PR，必须在描述中附上whatdiditdo --pr的输出。这为审查者提供了标准化的、信息丰富的变更上下文，能极大提升Review效率和质量。
与husky结合实现更精细的钩子控制：如果你已经在使用husky管理Git钩子，可以不使用--hook，而是在husky的post-commit钩子脚本中条件性地调用whatdiditdo。例如，只在提交信息包含[AI]标签时才触发审计。

4.3 安全扫描策略的深度理解

whatdiditdo的安全扫描是其核心价值之一。了解其原理能帮助你更好地利用和补充它。

它扫描什么？
- 模式匹配：寻找类似sk-[a-zA-Z0-9]{48}这种格式的字符串（OpenAI API密钥模式）。
- 文件敏感度：标记对.env、.env.*、*_rsa、*_dsa、*_ecdsa等文件名的任何修改。
- 内容关键字：在diff中搜索password、secret、key、token等词汇，并结合上下文判断风险。
它的局限与你的应对：
- 误报：它可能会将一些无害的配置值或示例代码标记为可疑。你需要具备基本的判断力。
- 漏报：它无法识别所有可能的密钥格式或公司内部的机密模式。
- 最佳实践：永远不要完全依赖自动化工具。whatdiditdo是一个出色的“第一道防线”和“提醒器”，但最终的安全责任在于开发者。你应该将其警告视为一次强制性的代码停留点，亲自检查被标记的变更。

5. 常见问题、排查与实战心得

在实际使用中，你可能会遇到一些问题。下面是我总结的一些常见情况及解决方案。

5.1 问题排查速查表

问题现象	可能原因	解决方案
运行`npx whatdiditdo`后无输出或报错“Not a git repository”。	当前目录不是一个Git仓库的根目录。	使用`cd`命令导航到正确的Git项目目录下再运行。
AI总结部分显示“AI summary unavailable”或长时间无响应。	1. 未配置AI CLI（如OpenAI API）。 2. 网络问题。 3. API密钥无效或额度不足。	1. 使用`--no-ai`标志跳过。 2. 检查网络连接。 3. 确认AI服务配置正确。这是一个可选功能，不影响核心审计。
`--undo`命令回滚了不想回滚的文件。	误操作或理解有误。	立即使用`git reflog`查找之前的提交哈希，然后使用`git reset --hard <hash>`恢复到操作前的状态。操作Git历史前，确保你理解命令的含义。
安全扫描给出了大量误报（如测试数据）。	工具的模式匹配触发了测试文件中的示例字符串。	仔细检查每个警告。如果确认是误报，可以忽略。目前工具没有提供自定义忽略规则的功能，这是一个可以反馈给开发者的改进点。
安装Git钩子(`--hook`)后，每次提交都觉得输出太频繁。	post-commit钩子对每次提交都触发。	使用`npx whatdiditdo --unhook`移除自动钩子。改为在重要的、由AI主导的提交后手动运行，这样干扰更小，目的性更强。

5.2 实战中的经验与技巧

将审计作为“保存点”后的标准动作：养成习惯。每次与AI进行一段密集的代码对话并满意地提交后，不要立即开始下一个任务。先运行一次npx whatdiditdo，花30秒快速浏览一下报告。这就像游戏里的“保存点”，确认这个节点的状态是清晰且安全的。
善用--last N进行功能合并前审查：如果你用一个分支开发一个完整功能，期间AI可能提交了多次。在准备合并到主分支前，运行npx whatdiditdo --last 10（假设有10次提交），可以让你对这个功能分支的所有累积变更有一个宏观、准确的认识，避免遗漏某些早期提交引入的依赖或改动。
--pr输出是起点，不是终点：工具生成的PR描述非常棒，但不要直接提交。把它作为一个完美的草稿，在此基础上补充你的动机说明（为什么用AI做这个改动）、测试细节（你手动验证了哪些边界情况）以及后续步骤（还有哪些TODO）。这能让你的PR描述从“好”变得“出色”。
安全警告必须“归零”：对于安全扫描给出的任何警告，我的原则是必须处理到零警告。要么确认是误报并记录（在团队内同步），要么立即修复（如移除误提交的密钥）。绝不能心存侥幸地忽略。
在团队中推广，建立轻量级规范：如果你的团队都在使用AI编码，可以提议将“在AI提交后运行whatdiditdo”作为一个轻量级的团队规范。这不仅能提升代码质量，还能作为一种知识共享的方式，让大家更了解AI对代码库的演进产生了何种影响。

whatdiditdo这个工具的精妙之处在于，它用一个极其简单的接口，解决了一个随着AI普及而日益普遍的开发痛点。它不改变你写代码的方式，而是在你写完代码后，为你点亮一盏灯，让你看清刚才走过的路。在这个AI辅助编码越来越深入的时代，拥有这样一位清醒的“副驾驶”，无疑能让你在开发的高速公路上行驶得更加自信和安稳。