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中引入了JWTJSON 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 wdidnpx whatdiditdo alias wdid-prnpx whatdiditdo --pr --no-ai | pbcopy echo PR描述已复制到剪贴板 alias wdid-undonpx 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辅助编码越来越深入的时代拥有这样一位清醒的“副驾驶”无疑能让你在开发的高速公路上行驶得更加自信和安稳。