AI编程助手Sage：在代码生成前进行“计划层审查”的自动化同行评审工具

1. 项目概述当你的AI编程伙伴有了“导师”如果你和我一样日常开发已经离不开像Claude Code、Cursor这类AI编程助手那你肯定也经历过这样的时刻AI助手信心满满地给出了一段代码或一个方案你乍一看觉得“嗯有道理”但实际跑起来或者深入思考后才发现里面藏着架构上的缺陷、逻辑上的漏洞或者干脆就是一条效率低下的“弯路”。现有的代码审查工具比如GitHub上的那些AI Review Bot它们很棒但它们只审查最终的代码差异diff。问题在于我们和AI协作时80%的时间可能花在讨论方案、推敲设计上只有20%的时间在真正写代码。如果最初的思路就错了那么审查再完美的代码也只是在优化一个错误的方向。这就是Sage要解决的问题。你可以把它理解为你主力AI编程助手比如Claude Code的“专属导师”。它不直接参与编码而是像一个经验丰富的高级工程师静静地坐在旁边观察你和Claude Code的每一次对话。每当Claude Code给出一个回复——无论是长篇大论的设计方案还是一小段代码片段——Sage都会立刻动用另一个AI模型目前是OpenAI的Codex对这个回复进行“同行评审”。它会分析方案的合理性、代码的潜在问题并给出结构化的评审意见通过、有疑虑、或存在严重问题。更重要的是它会生成一段可以直接粘贴回对话的“给AI的消息”让你能引导Claude Code走向更优的解决方案。简单说Sage把开发者之间那种“嘿哥们我觉得你这个思路有点问题要不要试试……”的即时同行评审自动化地引入了人机协作的流程中。它瞄准的是“计划层”的缺陷在错误被写成代码之前就将其扼杀。2. 核心设计思路为什么“计划审查”比“代码审查”更重要2.1 现有工具的局限性剖析传统的AI代码审查工具如CodeRabbit或Greptile其工作模式是静态的、基于结果的。它们接收一个代码变更集Pull Request然后分析这些新增或修改的代码行。这种模式在纯人类协作中很有效因为PR代表了一个相对完整、经过思考的决策结果。但在AI辅助编程的动态对话流中它就显得滞后和片面了。想象一下这个场景你想实现一个用户权限系统。你问Claude Code“如何设计一个基于角色的访问控制RBAC系统” Claude Code可能会建议你使用一个包含users、roles、permissions三张表的关系型数据库设计并附上SQL schema。从代码语法上看这个设计可能毫无瑕疵。一个传统的AI审查工具会通过。然而一个有经验的工程师可能会立刻指出对于你的业务规模比如一个小型内部工具这个设计是否过于重量级你是否考虑过使用更简单的位掩码bitmask或在JWT令牌中直接嵌入角色这些架构层面的权衡是代码diff无法体现的。Sage的设计哲学正是基于此大量的缺陷源于错误的设计决策而非错误的代码实现。审查对话就是审查决策过程本身。2.2 “模型议会”理念的自动化实现许多高阶用户已经自发地在实践“模型交叉验证”他们同时打开Claude和ChatGPT的对话窗口把其中一个模型的输出复制给另一个问“你觉得这个方案怎么样”。这本质上是组建了一个微型的“模型议会”利用不同模型的知识盲区和思维差异来相互制衡、补充。研究表明这种多模型协作能显著提升输出的准确性和可靠性。然而手动操作极其繁琐严重打断了编码心流。Sage的核心价值之一就是将这一最佳实践自动化、无缝化。目前Sage使用OpenAI Codex作为评审员来监督Anthropic的Claude Code。它的路线图清晰地显示未来将支持更多模型如Gemini、开源模型组成一个真正的“评审委员会”。这意味着你的Claude Code提出的方案可能会同时受到来自Google、OpenAI和社区顶尖模型的多角度审视这种集思广益的效果是单一模型难以企及的。2.3 非侵入式集成不改变你的工作流一个好的工具应该适应人而不是让人去适应工具。Sage深谙此道。它不需要你改变使用Claude Code的习惯。你不需要将代码复制到一个新的界面也不需要切换标签页。你只需要在另一个终端窗口运行sage命令然后像往常一样使用claude命令进行编程。Sage通过巧妙的“钩子hooks”机制监听Claude Code会话的生命周期事件。当Claude Code产生新的回复时钩子会触发SageSage则自动抓取完整的对话上下文和项目代码交给Codex进行评审。整个过程在后台静默完成评审结果以富文本卡片的形式实时显示在Sage的终端界面里。你想采纳建议就复制粘贴觉得没必要就忽略。控制权始终在你手中。这种设计使得Sage从一个“你必须使用的工具”变成了一个“随时可用的顾问”极大地降低了采用门槛和使用负担。3. 详细安装与配置指南虽然Sage的README给出了基础命令但在实际部署中有几个细节和潜在坑点需要特别注意。以下是我在macOS系统上从零搭建可用的Sage环境的全过程记录。3.1 环境前置检查与依赖安装首先确保你的系统已经准备好。Sage重度依赖Node.js环境并且对Claude Code的版本有严格要求。# 1. 检查并更新Node.js。建议使用nvm管理版本确保Node版本在18以上。 node --version # 如果版本较低使用nvm安装新版本nvm install 20 nvm use 20 # 2. 安装或更新Claude Code。这是核心必须使用2.0.50或更高版本。 # 前往 https://claude.ai/download 下载最新安装包并安装。 # 安装后在终端验证 claude --version # 输出应为2.0.50 或更高。如果找不到命令可能需要将Claude Code添加到系统PATH。 # 通常安装程序会自动配置如果没有手动添加export PATH\/Applications/Claude.app/Contents/Resources:\$PATH\ # 可以将这行添加到你的 ~/.zshrc 或 ~/.bash_profile 中。 # 3. 安装OpenAI Codex CLI。这是Sage的“大脑”负责执行评审。 npm install -g openai/codex运行codex命令它会引导你完成认证。你有两种选择交互式登录直接输入codex它会打开浏览器让你用ChatGPT账号登录。这是最简单的方式。API密钥方式如果你有OpenAI的API密钥可以设置环境变量export CODEX_API_KEY‘sk-...’。这对于无头服务器或自动化环境更友好。关键提示openai/codex这个包与OpenAI的API不同它是OpenAI提供的一个本地运行的AI代理框架。安装时如果遇到权限问题可以尝试使用sudo npm install -g ...但更推荐先修复npm的全局安装目录权限或者使用npm install -g openai/codex --ignore-scripts来避免某些post-install脚本的权限错误。3.2 安装Sage并启动你的第一次评审前置条件满足后安装Sage本身非常简单npm install -g tigtech/sage安装完成后最关键的一步来了你需要在一个具体的项目目录下运行Sage。Sage需要读取项目代码作为评审的上下文所以它必须知道你在哪个项目里工作。# 切换到你的项目目录比如一个React应用 cd ~/projects/my-awesome-app # 在一个新的终端窗口或Tmux/Pane中运行Sage sage第一次运行sage时它会自动尝试为Claude Code配置钩子。你应该在终端看到类似以下的输出 Detecting Claude Code installation... ✓ Found Claude Code at /Applications/Claude.app/Contents/Resources/claude Configuring hooks for Claude Code... ✓ Hooks configured successfully.这个“钩子”实际上是在你的Claude Code用户配置目录~/.claude/下修改了settings.local.json文件添加了Sage的监听器。这样每当Claude Code会话状态变化就会通知Sage。如果自动配置失败可能由于权限或路径问题你可以手动运行Sage包内的配置脚本# 找到Sage的全局安装路径通常类似 /usr/local/lib/node_modules/tigtech/sage # 然后运行其配置脚本 npm explore -g tigtech/sage -- npm run configure-hooks配置成功后Sage的终端UI会启动并列出当前项目目录下所有可用的Claude Code会话。如果列表为空别急先去另一个终端窗口在同一个项目目录下启动一个新的Claude Code会话# 在另一个终端同样先进入项目目录 cd ~/projects/my-awesome-app # 启动Claude Code claude现在回到Sage的窗口按下R键刷新列表你应该能看到刚刚创建的会话了。选择它Sage就会开始实时跟踪这个会话中的所有对话。4. 深度使用与工作流解析4.1 理解Sage的评审输出当你选中一个会话后Sage界面通常会分成几个区域。主区域会实时显示Claude Code的回复以及Sage的评审卡片。一张典型的评审卡片包含以下核心信息裁决 (Verdict)这是最直观的结论。Approved绿色表示Sage基本认同该方案风险较低。Concerns黄色表示方案大体可行但存在一些值得商榷的优化点或潜在风险。Critical Issues红色则是一个明确的警告意味着Sage认为当前方案存在根本性缺陷继续推进可能导致严重问题。替代方案 (Alternatives)这是Sage作为“高级工程师”价值的集中体现。它不会只说“不好”而是会给出“怎样更好”。例如Claude Code建议用一堆if-else实现状态机Sage可能会指出“考虑使用状态模式State Pattern或一个简单的状态查找表state lookup table这将使增加新状态更容易并符合开闭原则。” 这部分内容对于拓宽思路、学习更好的设计模式极具价值。给AI的消息 (Message for agent)这是可直接操作的干货。Sage会生成一段自然语言文本你可以一键复制通常高亮后按回车或特定快捷键然后直接粘贴回Claude Code的输入框。这段消息已经过润色能有效地将评审意见转化为对AI的引导指令例如“你提出的方案A在扩展性上可能有问题。我们是否可以考虑方案B另外请特别注意边界条件X的处理。”4.2 与Claude Code的“计划模式”协同工作Claude Code有一个强大的“计划模式”Plan Mode它允许AI在写代码前先输出一个详细的实现计划。这正是Sage发挥“计划层审查”优势的绝佳场景。标准流程当Claude Code在计划模式下输出一个提案时由于技术限制Sage无法在提案生成的瞬间触发评审没有对应的钩子事件。它会等到你停止Claude Code的思考或Claude自己完成输出后才进行评审。这时你会在Sage界面看到对该计划的评审卡片。高级技巧如果你希望在Claude Code刚输出计划、你尚未决定是否采纳前就得到Sage的反馈可以手动触发。在Sage界面中当看到Claude Code输出了新内容但Sage还未评审时按下M键Manual ReviewSage会立即对最新的对话内容进行一次评审。这让你能在点击“Accept Plan”之前就获得第二意见避免接受一个有缺陷的蓝图。4.3 处理复杂项目与多会话场景在大型项目中你可能同时开启多个Claude Code会话分别处理不同的功能模块例如一个处理前端组件一个处理后端API。Sage的会话选择器可以列出所有活跃会话。你需要根据会话描述通常是基于目录或初始提示生成来选择要监控哪一个。实操心得为了更高效我养成了一个习惯在启动Claude Code会话时用一个非常明确的提示开头例如“// 会话主题用户登录模块的重构”。这样这个主题也会出现在Sage的会话列表中让我一目了然不会跟“支付集成”的会话搞混。如果Sage没有自动检测到新会话除了按R刷新还可以检查后台机制。Sage通过文件系统监听使用Chokidar库来捕获Claude Code产生的信号文件。这些文件位于~/.sage/{你的项目路径哈希}/runtime/needs-review/目录下。如果自动评审没触发可以到这个目录看看是否有以.signal结尾的新文件。手动删除一个旧文件或重启Sage有时能解决监听僵死的问题。5. 架构揭秘与高级配置5.1 Sage的核心组件如何协同工作理解Sage的架构有助于你在遇到问题时进行排查甚至进行一些高级定制。它的设计可以概括为以下几个模块的协作终端界面 (React Ink)提供交互式列表和实时评审显示。Ink是一个用React构建CLI应用的库这让Sage的界面既美观又响应迅速。钩子管理器 (Claude Code Hooks)这是“触发器”。它修改Claude Code的配置使其在特定事件如“会话创建”、“新回复就绪”时执行Sage提供的一个脚本。这个脚本的工作很简单在特定目录下创建一个“信号文件”。文件监视器 (Chokidar)Sage的核心进程持续监视着~/.sage/runtime/needs-review/目录。一旦发现新的信号文件就知道有新的Claude回复需要评审了。评审引擎 (OpenAI Codex SDK)这是“大脑”。当监视器发现信号后评审引擎被唤醒。它会做以下几件事读取信号文件获取对应的Claude Code会话ID和项目路径。找到该会话的完整JSONL格式的对话转录文件Claude Code本地保存的聊天记录。读取当前项目目录的代码文件构建评审上下文。将所有信息对话历史、最新回复、相关代码组织成一个精心设计的提示词Prompt发送给Codex模型。解析Codex的返回生成结构化的评审卡片。状态与缓存Sage会维护状态确保不会对同一回复重复评审并能将多次评审关联到同一个会话线程中。5.2 潜在的性能调优与自定义默认配置下Sage运行良好。但对于超大型项目或网络较慢的环境你可以进行一些调整。环境变量Sage和Codex都支持通过环境变量配置。例如如果你在使用企业代理或需要指定不同的API端点可以设置export HTTPS_PROXYhttp://your-proxy:port export CODEX_BASE_URLhttps://your-custom-endpoint.com评审上下文限制Sage在构建评审提示时会读取项目文件。对于巨型项目如包含node_modules这可能会拖慢速度或触及模型的上下文长度限制。目前Sage的默认策略是智能地选取可能与当前对话相关的文件通过文件路径关键词匹配。如果发现评审内容不准确或遗漏重要文件你可以检查Sage运行时的日志输出通过SAGE_DEBUG1 sage开启调试模式看它到底加载了哪些文件。自定义评审提示高级Sage的评审逻辑固化在代码中。但理论上你可以通过修改其源代码在tigtech/sage的安装目录下调整它发送给Codex的提示词模板以改变评审的侧重点例如更强调性能、安全性或代码风格。6. 常见问题排查与实战技巧即使按照指南操作在实际使用中仍可能遇到各种问题。下面是我在深度使用过程中遇到的典型问题及解决方案这可能是官方文档都未曾提及的“实战秘籍”。6.1 安装与启动类问题问题一运行sage命令后提示“Claude Code not found”或“Claude Code version too old”。排查步骤确认claude命令在终端中可直接执行。直接在终端输入claude --version。如果找不到命令说明Claude Code的二进制文件不在你的PATH环境变量中。Sage是通过which claude来查找的。解决方案找到Claude Code的实际安装路径。通常在/Applications/Claude.app/Contents/Resources/claude。然后通过环境变量显式告诉Sageexport CLAUDE_BIN/Applications/Claude.app/Contents/Resources/claude # 然后重新运行 sage sage为了永久生效将这行export语句添加到你的shell配置文件~/.zshrc或~/.bash_profile中。问题二Sage启动后会话列表始终为空按R刷新也没用。排查步骤确认钩子已配置检查文件~/.claude/settings.local.json看其中是否包含一个指向Sage的hookCommand配置项。内容应该类似{ hookCommand: /usr/local/bin/node /usr/local/lib/node_modules/tigtech/sage/dist/cli.js hook }确认在项目目录下运行Sage的会话发现是基于当前工作目录的。你必须cd到你的项目根目录再运行sage和claude。确认会话创建于Sage之后Sage只能监控在它配置好钩子之后创建的Claude Code会话。对于已有的旧会话需要先用claude --resume session-id恢复一次以触发钩子。检查信号目录查看~/.sage/{project-path-hash}/runtime/sessions/目录下是否有以.json结尾的会话元数据文件。如果没有说明钩子没有正确记录会话。手动运行钩子配置如果上述都无效尝试手动运行npm explore -g tigtech/sage -- npm run configure-hooks然后完全重启Claude Code和Sage。6.2 运行时与评审类问题问题三Claude Code有回复但Sage界面没有更新评审卡片。排查步骤首先在Sage界面按M键手动触发评审。如果手动可以说明自动触发链路有问题。检查错误日志Sage会将钩子执行错误记录在~/.sage/{project-path-hash}/runtime/hook-errors.log。查看这个文件里面可能有权限错误或Node路径错误。一个常见原因如果你的系统有多个Node版本并且Sage是用一个版本如通过nvm安装的Node 18安装的而Claude Code钩子运行时可能使用了系统默认的另一个Node版本如Node 16这会导致模块找不到。解决方案确保~/.claude/settings.local.json中的hookCommand使用了正确的Node绝对路径。你可以用which node查看当前Sage使用的Node路径并手动更新配置文件。问题四评审内容感觉泛泛而谈没有切中项目要害。原因分析Sage的评审质量很大程度上取决于它构建的“上下文”。如果它没有正确加载你项目中的关键文件或者对话历史中缺乏必要的背景信息Codex就无法做出精准判断。优化技巧在对话中提供更多背景在向Claude Code描述问题时尽量详细。例如不只是说“写一个API端点”而是说“在我的Next.js 14项目使用App Router中在/app/api/users/route.ts里写一个处理GET请求的端点它需要连接MongoDB数据库连接字符串在.env.local里并返回用户列表。”确保项目结构清晰Sage会尝试索引项目文件。一个结构混乱、包含大量无关构建产物的目录会影响其判断。确保在项目根目录运行并考虑添加.gitignore来排除build/dist/node_modules/等目录虽然Sage会尝试过滤但清晰的目录更好。手动引导评审焦点如果你对某个特定方面如安全性、数据库查询性能特别关注可以在Sage运行时直接在它的界面中寻找是否有输入框或配置项未来版本可能支持或者在给Claude Code的提示中预先说明“请特别注意性能优化”这样Sage在评审时也会看到这个上下文。问题五在iTerm2终端中使用时界面闪烁严重。原因这是一个已知问题源于底层使用的Ink库与iTerm2在渲染频繁更新的终端UI时存在兼容性问题。解决方案首选方案切换到macOS自带的“终端”Terminal.app或VS Code的内置终端。它们通常没有这个问题。如果必须使用iTerm2尝试在iTerm2的设置中调整。进入Preferences - Profiles - Your Profile - Terminal将“终端报告类型”Report Terminal Type从默认的xterm-256color改为xterm或vt100。这有时能缓解问题但可能影响其他终端应用的色彩显示。6.3 进阶使用与集成思路将Sage集成到团队工作流中虽然Sage目前主要面向个人开发者但其理念可以扩展到团队。想象一下团队中每个开发者的AI编程助手输出在形成代码提交前都经过一个共享的、更强大的“Sage委员会”由多个顶级模型组成的评审并将评审摘要附在PR描述中。这能极大提升团队代码设计的一致性和质量。目前这需要一定的定制开发但Sage的开源架构为此提供了可能。结合本地模型降低成本与延迟Sage的路线图包含对开源模型的支持。一旦实现你可以将评审工作负载部署到本地的Ollama运行Llama 3 Code等模型或通过vLLM部署的私有模型上。这不仅能消除API调用成本还能显著降低评审延迟实现真正的实时反馈并且所有代码和对话数据都留在本地满足严格的隐私和安全要求。用作AI提示词Prompt的调试器Sage的核心是审查“AI的思考过程”。这使它成为一个绝佳的提示词调试工具。当你精心设计了一个复杂的提示词给Claude Code但输出不尽如人意时观察Sage对Claude Code回复的评审能让你从另一个AI的视角理解你的提示词在哪里导致了歧义或低效的解决方案。你可以根据Sage的反馈迭代优化你的提示词从而提升与主力AI协作的整体效率。