AI编程助手代码审计工具whatdiditdo：从黑盒到白盒的智能复盘

1. 项目概述当AI替你写代码后如何快速复盘如果你和我一样已经深度依赖AI编程助手比如Cursor、GitHub Copilot、Claude Code来加速日常开发那你一定遇到过这个场景你给AI下了一个指令比如“重构这个组件”或者“添加用户认证”然后AI开始“烹饪”光标闪烁文件飞速变动。几分钟后AI告诉你“完成了”。你看着满屏的绿色和红色的Git差异心里却有点发毛它到底改了啥有没有引入安全漏洞新增了哪些依赖这次改动到底值不值得提交一个Pull Request这就是whatdiditdo要解决的痛点。它是一个极简的Node.js命令行工具专门用来在AI编码会话之后帮你快速、清晰地复盘所有变更。你不需要手动去逐行比对git diff也不需要猜测AI的意图。一条命令它就能给你一份包含文件变更统计、AI总结、安全扫描甚至PR描述草案的完整报告。简单来说它是连接“AI编码”和“人类审查”之间的那座桥梁让你在享受AI生产力的同时牢牢掌握代码的控制权。2. 核心设计思路为什么我们需要一个“AI编码审计员”2.1 从“黑盒”到“白盒”的转变传统的AI编码助手工作模式像一个“黑盒”。你输入需求它输出代码。虽然最终的代码差异可以通过git diff查看但这只是最原始的数据。你需要自己从成百上千行的增减中归纳出“这次改动的核心是什么”、“新增了哪些风险”、“对项目结构有何影响”。这个过程耗时耗力尤其是在复杂的重构或功能添加之后。whatdiditdo的设计哲学就是把这个“黑盒”过程“白盒化”。它不仅仅是一个美化版的git diff而是一个分析引擎。它的核心任务是对AI产生的Git提交进行多维度的解构和分析将原始的行级变更提升为人类开发者能快速理解的语义化信息。这包括结构化统计不只是文件列表而是按增、删、改、新增依赖进行分类和计数。语义化总结利用AI调用外部模型来解释AI的改动用自然语言告诉你“这次改动主要实现了用户登录功能并重构了API调用层”。风险扫描自动检查变更中是否包含硬编码的密钥、被修改的.env文件等安全隐患。工作流集成生成可直接用于协作工具如PR描述、Slack通知的格式化内容。2.2 工具定位轻量、无侵入、即用即走whatdiditdo的另一个关键设计是“轻量级”和“无侵入性”。它本身不修改你的项目代码也不要求复杂的配置。通过npx直接运行意味着你可以在任何Git仓库中随时使用用完即走。这种设计降低了使用门槛使其能无缝融入现有的开发流程无论是个人项目还是团队协作。它将自己定位为一个“审计员”或“复盘助手”而非一个“管理平台”。它的目标是提供洞察而不是施加约束。因此它的所有功能都围绕“分析”和“报告”展开最后的决策权——是否提交、是否回滚——仍然完全掌握在开发者手中。3. 快速上手与核心功能详解3.1 零配置入门一条命令看清全局使用whatdiditdo简单到不可思议。假设你刚刚用Cursor的Chat功能完成了一次代码生成并且已经用git add .暂存了更改或者甚至已经完成了一次提交。打开终端进入你的项目根目录确保这是一个Git仓库然后运行npx whatdiditdo这条命令会做以下几件事自动检测Git状态工具会检查自上次提交以来工作区和暂存区的所有变更。如果你刚刚git add但还未提交它会分析这些暂存的变更。如果你已经提交它会分析最新的一次提交。执行多维度分析扫描变更的文件计算行数检查package.json或类似文件以识别新增的依赖。生成并输出报告在终端里你会看到一个清晰格式化的报告。一个典型的输出可能如下所示 whatdiditdo — AI Coding Session Audit ───────────────────────────────────────── Session: Last commit (abc123f) ⏱️ Timeframe: Changes since main (10 minutes ago) CHANGE SUMMARY ├── Files Changed: 8 ├── Lines Added: 342 ├── Lines Removed: 87 ├── New Dependencies: 2 (axios, zod) SECURITY CHECK ✅ No hardcoded API keys found. ⚠️ .env.example was modified. Review for sensitive defaults. ✅ No private key files detected. AI-GENERATED SUMMARY (via Claude) This session primarily implemented user authentication endpoints and UI components. Key changes include: - Added /api/auth/login and /api/auth/register API routes with JWT token handling. - Created a React LoginForm component with form validation using Zod. - Updated the .env.example file with new environment variable placeholders (JWT_SECRET, DATABASE_URL). - Refactored the global API client (lib/api.ts) to automatically attach auth tokens to requests. FILES CHANGED src/ ├── [] api/auth/login.ts (45) ├── [] api/auth/register.ts (52) ├── [] components/LoginForm.tsx (120) ├── [M] lib/api.ts (25, -10) ├── [M] .env.example (3) └── [M] package.json (2) # Added axios, zod QUICK SHARE 8 files · 342 -87 · 2 new deps · Auth implemented这份报告在几秒钟内就把一次可能涉及多个文件的复杂AI编码会话提炼成了开发者一眼就能看懂的信息全景图。注意首次运行npx whatdiditdo时如果启用了AI总结功能默认开启它会提示你需要配置AI API密钥如OpenAI或Anthropic。你可以选择跳过使用--no-ai标志也可以按照提示进行配置。这是唯一可能需要“配置”的地方而且完全是可选的。3.2 核心功能模块深度解析让我们拆解上面报告中的每个部分看看它们是如何工作的以及为什么它们对开发者如此有用。3.2.1 变更统计与文件列表这是最基础也是最实用的功能。whatdiditdo调用Git命令获取差异然后进行智能解析。如何工作它本质上运行了类似git diff --stat和git diff --name-status的命令组合但进行了更精细的处理。它会区分“新增文件”、“修改文件”和“删除文件”并精确计算每个文件增加和删除的行数。对于package.json、pyproject.toml、go.mod等依赖管理文件它会进行解析对比变更前后精确列出新增和移除的依赖包名称。开发者价值量化评估“342 -87”这样的数据让你立刻对改动规模有个直观感受。是一次小修小补还是一次大规模重构依赖管理明确看到新增了axios和zod你就能立刻评估这两个库是否必要是否会增加包体积许可证是否合规这避免了AI随意添加“它认为有用”的依赖而导致的技术债。快速导航清晰的文件列表和路径让你能快速在编辑器中定位到关键变更文件进行详细审查。3.2.2 AI驱动的语义化总结这是whatdiditdo的“灵魂”功能。它用AI来解释AI的代码形成了一个有趣的“元认知”循环。如何工作当你未使用--no-ai标志时工具会将本次变更的文件列表、关键文件的差异片段特别是新增的重头文件以及提交信息如果有组合成一个提示词Prompt发送给你配置的AI模型API如Claude 3.5 Sonnet 或 GPT-4。模型会分析这些上下文并生成一段简洁、准确的自然语言总结。技术细节为了控制成本和提高速度它不会发送整个仓库的所有代码差异而是有选择地提取新创建的文件的全部内容。被大幅修改的文件的关键差异区块Hunk。提交信息。 然后构造如下的提示词“以下是最近一次Git提交中变更的文件列表和主要差异。请用一段话总结这次提交主要做了什么面向开发者突出重点。”开发者价值快速理解意图对于复杂的重构AI总结能帮你迅速抓住核心比如“将类组件重构为函数组件并使用了React Hooks”比你自己看差异要快得多。验证AI理解通过阅读总结你可以判断AI助手是否准确理解了你的初始指令。如果总结偏离了你的本意那代码很可能也有问题。生成文档草稿这段总结本身就是一次优秀代码变更描述可以直接用于提交信息或PR描述的第一段。3.2.3 安全扫描在AI编码时代安全是一个容易被忽视的盲点。AI可能会“好心”地帮你创建一个包含示例API密钥的配置文件或者将硬编码的密码写入源代码。如何工作whatdiditdo内置了一套简单的正则表达式和模式匹配规则在变更的文件内容中扫描常见的“危险信号”硬编码密钥匹配类似AKIA[0-9A-Z]{16}(AWS密钥)、sk_[a-z0-9]{48}(OpenAI密钥) 等模式。敏感文件修改特别标记对.env、.env.local、config/secrets.yml等常见配置文件的所有修改。即使只是修改.env.example它也会提示你检查因为示例文件可能包含敏感默认值。私钥文件检查是否有.pem、.key、id_rsa等疑似私钥的文件被添加或修改。URL中的凭证扫描包含://username:password模式的URL。开发者价值主动防御在代码进入仓库甚至被推送到远程之前就捕获潜在的安全漏洞。提高意识每次AI编码后都进行一次安全检查能培养开发者尤其是新手对代码安全性的重视。审计追踪如果安装了Git钩子它能为每一次提交提供一份安全记录。3.2.4 快速分享与Emoji摘要这个功能看似小巧却极大地优化了团队协作场景。如何工作每次运行无论是否使用其他标志whatdiditdo都会在报告末尾生成一行“Emoji摘要”例如 8 files · 342 -87 · 2 new deps · Auth implemented。开发者价值极简同步在Slack、Discord或团队群聊中你可以直接粘贴这一行队友在1秒内就能对这次变更的规模、影响和主题有基本了解。标准化格式它提供了一种统一、有趣的变更描述格式避免了每个人描述方式不同带来的理解成本。4. 高级用法与集成工作流4.1 自动生成PR描述告别写作瓶颈为一次AI生成的大规模变更编写清晰、全面的PR描述是一件繁琐的事。whatdiditdo --pr将这个流程自动化了。实操步骤让AI完成编码并提交更改。git add . git commit -m “WIP: AI-generated auth feature”运行命令生成PR描述。npx whatdiditdo --pr工具会输出一个结构完整的Markdown文本通常包含一个建议的PR标题基于AI总结提炼。详细的PR正文概述AI生成的语义总结。变更文件表以表格形式列出文件及行数变化更易读。新增依赖单独列出方便评审者关注。安全警告醒目提示需要人工复核的点。测试计划检查表一个简单的- [ ]列表引导提交者思考是否需要更新测试、文档等。高级技巧结合系统剪贴板在MacOS上你可以使用管道操作符直接复制到剪贴板npx whatdiditdo --pr --no-ai | pbcopy--no-ai在这里是可选的如果你不需要AI总结可以加快速度。运行后PR描述已经复制好直接去GitHub或GitLab页面粘贴即可。这节省了大量机械性写作时间。4.2 审查历史提交追溯AI的足迹AI编码并非总是一次性会话。你可能在多个提交中逐步完善一个功能。--last N标志让你可以回顾过去一段时间内AI的“工作记录”。# 查看最近3次提交的合并分析报告 npx whatdiditdo --last 3这个命令会获取最近3次提交的累积变更并生成一份统一的报告。这对于回答“过去一小时AI都对代码库做了什么”这类问题非常有用有助于进行小阶段的复盘或向团队同步进度。4.3 集成到Git工作流安装提交钩子为了完全自动化审计流程你可以将whatdiditdo安装为Git的post-commit钩子。安装后每次你执行git commit成功它都会自动运行并输出一份简洁的报告主要是Emoji摘要和关键警告。# 安装钩子 npx whatdiditdo --hook # 之后每次提交后你都会看到类似提示 # [whatdiditdo] 2 files · 45 -12 · 0 new deps注意事项与心得钩子位置它安装的是本地仓库的.git/hooks/post-commit钩子不会影响团队其他成员。这很安全。性能影响钩子运行很快通常不影响提交速度。但如果启用了AI总结且网络慢可能会稍有延迟。建议在钩子中使用--no-ai模式以获得最快反馈。# 你可以手动编辑 .git/hooks/post-commit 文件将命令改为 # npx whatdiditdo --no-ai 2/dev/null || true何时使用非常适合个人项目或特性分支作为一道自动化的“代码变更快照”工序。对于团队主分支可能更需要人工控制的PR流程。4.4 回滚与补救当AI“跑偏”时AI并不总是正确的。有时它的“解决方案”可能完全偏离方向或者引入了难以调试的Bug。--undo系列命令提供了精细化的回滚能力。分步回滚流程查看变更列表首先运行npx whatdiditdo --undo。这会列出在上次提交中所有被更改的文件并为每个文件编号同时显示一个简短的差异预览。1. src/components/LoginForm.tsx (120 lines) ...预览片段... 2. src/lib/api.ts (25, -10 lines) ...预览片段... 3. .env.example (3 lines) ...预览片段...选择性回滚如果你只想撤销对api.ts的修改因为它引入了错误的逻辑你可以运行npx whatdiditdo --undo 2这会将第二个文件src/lib/api.ts恢复到提交前的状态同时保留其他文件的更改。全部回滚如果整个AI会话的结果都不可用直接全部撤销npx whatdiditdo --undo all这相当于执行git revert HEAD或git reset --hard HEAD~1取决于是否已推送但通过whatdiditdo操作你是在充分知晓具体变更内容后做出的决定。实操心得--undo功能特别适合与“探索性编程”结合。你可以放心地让AI尝试多种方案每次尝试后都用whatdiditdo评估如果不行就精准回滚而不用担心把仓库状态搞乱。4.5 可视化报告与团队通知对于喜欢图形界面或需要存档的场景whatdiditdo提供了--web和--notify选项。HTML网页报告 (--web)运行npx whatdiditdo --web会在本地启动一个临时服务器并在你的默认浏览器中打开一个美观的、暗色主题的HTML报告页面。这个页面包含了比终端更丰富的视觉元素如语法高亮的代码差异对比图更适合进行深入的代码审查或向不熟悉命令行的同事展示。Webhook通知 (--notify)这是自动化团队协作的利器。你可以将AI编码会话的总结自动推送到团队的Slack或Discord频道。npx whatdiditdo --notify https://hooks.slack.com/services/YOUR/WEBHOOK/URL工具会自动识别Webhook URL的平台并格式化相应的消息卡片。对于未知的URL它会发送一个结构化的JSON摘要。你可以将此命令与CI/CD管道结合当AI辅助的特性分支合并时自动在频道中发布变更摘要。5. 实战场景与避坑指南5.1 场景一大规模重构后的代码审查场景你让Cursor的Composer模式重构一个庞大的遗留模块涉及20多个文件。痛点手动git diff眼花缭乱难以把握重构的整体质量和一致性。whatdiditdo工作流提交所有重构更改。运行npx whatdiditdo --last 5假设重构分了5次提交。查看累积影响。重点关注报告中的AI总结看AI是否理解这是一次“从MVC到MVVM的重构”还是只是“代码格式化”。新增依赖检查是否引入了不必要的新库。安全扫描确保重构没有意外暴露配置。文件列表快速浏览所有被触及的文件确认没有误伤无关模块。使用npx whatdiditdo --web打开网页报告利用其更好的代码对比视图进行关键文件的逐行审查。避坑技巧对于大规模重构AI总结可能因上下文长度限制而不够精确。此时应更依赖文件列表和行数统计来评估改动范围并手动抽查几个核心文件的差异。5.2 场景二团队协作中的AI编码规范场景团队规定所有由AI辅助生成的提交必须在PR描述中附上变更摘要。痛点手动编写摘要耗时且格式不统一。whatdiditdo解决方案在团队的Wiki或README中推荐使用whatdiditdo --pr作为生成PR描述的标准工具。可以创建一个别名或脚本比如git ai-pr将其绑定到npx whatdiditdo --pr --no-ai | pbcopy。鼓励成员在提交AI生成的代码后运行此命令并将生成的描述粘贴到PR中。这确保了所有AI相关的PR都有一致、清晰的结构化描述便于代码评审。避坑技巧--no-ai标志在这里很有用。因为团队内部评审可能不需要额外的AI解释而且可以避免因网络或API配置问题导致命令失败。纯统计信息和安全警告对于评审者来说通常已经足够。5.3 场景三排查由AI引入的诡异Bug场景功能昨天还正常今天AI“优化”了部分代码后出现了一个难以理解的运行时错误。痛点不确定是AI的哪一次修改引入了问题。whatdiditdo排查法使用git log --oneline找到从昨天到今天之间所有包含AI工作的提交通常提交信息有特征。对每个可疑的提交使用git checkout commit-hash切换到该次提交的状态。在该提交状态下运行npx whatdiditdo分析该次提交本身或者与上一个正常提交对比需要手动git diff。仔细阅读AI总结和文件变更列表寻找与错误可能相关的改动例如“优化了数据获取逻辑”、“修改了错误处理函数”。结合--undo功能可以逐一回滚这些提交中的特定文件进行测试快速定位问题代码。避坑技巧养成在每次重要的AI编码会话后立即运行whatdiditdo并简单记录的习惯。甚至可以将其输出通过npx whatdiditdo --md ai-session-$(date %Y%m%d-%H%M).md保存为Markdown文件建立一份“AI编码日志”这对后期追溯问题非常有帮助。5.4 常见问题与故障排除Q1: 运行npx whatdiditdo报错 “Not a git repository”。A1:确保你的当前目录是一个Git仓库的根目录。whatdiditdo的所有功能都基于Git。使用git init初始化一个新仓库或cd到正确的项目目录。Q2: AI总结功能没有触发或者提示需要API密钥。A2:AI总结功能需要外部模型API。你有三个选择跳过AI总结始终使用npx whatdiditdo --no-ai命令。配置一次按照首次运行时的提示设置环境变量如OPENAI_API_KEY或在本地配置文件。具体方法请参考工具的官方文档。检查网络确保你的网络可以访问对应的API服务。Q3: 安全扫描误报了我的.env.example里只是示例值。A3:这是预期行为。安全扫描的原则是“宁可误报不可漏报”。任何对.env、.env.*等敏感配置模式文件的修改都会被标记提醒你进行人工复核。你应该检查这些修改确认没有泄露真实密钥。你可以将其视为一个有益的强制检查点。Q4:--undo命令会丢失我的工作吗A4:--undo命令基于Git操作。--undo all相当于回滚最新的一次提交。如果你有未推送的提交回滚是安全的。如果你已经推送到远程并且与其他人协作则需要考虑使用git revert来生成一个反向提交而不是直接reset。whatdiditdo --undo在内部会尝试使用最安全的方式但在关键操作前理解基本的Git原理总是好的。Q5: 工具运行速度慢。A5:性能瓶颈通常来自两方面AI总结这是最耗时的部分因为涉及网络请求。使用--no-ai标志可以极大提升速度。分析大量文件如果单次提交涉及成百上千个文件如重命名目录分析会变慢。对于这种情况工具本身可能不是最佳选择你应该先考虑用Git命令进行宏观管理。whatdiditdo本质上是一个增强版的Git变更分析器。它不会改变你使用Git和AI编程助手的核心方式而是在这个工作流的“间隙”中插入了一个高效的、自动化的洞察环节。它把开发者从繁琐的变更梳理工作中解放出来让我们能更专注于更高层次的逻辑判断和创造性工作。在AI编码日益普及的今天拥有这样一个“元工具”或许正是保持代码质量和开发者心智清晰的关键一步。