CodeTutor: Emacs 的 AI 配对编程导师

CodeTutor 是一个 Emacs 软件包，旨在作为 AI 配对编程导师，而非自动补全引擎。它将本地 AI 助手集成到 Emacs 编辑器中，以提供概念指导、在保存后审查代码变更，并提供架构建议，而绝不会修改用户的源文件。

核心理念：教学重于实现

CodeTutor 的构建原则是引导用户走向解决方案，而不是提供即插即用的代码。该工具旨在扮演高级工程师或资深工程师的角色，专注于底层概念、风险和架构。

实现边界

为了维持其导师角色，CodeTutor 遵循严格的边界：

  • 不修改源码：该工具不会写入项目文件、生成补丁或生成全文件替换。
  • 概念指导：它提供简短的说明性代码示例并解释反馈背后的概念，但避免直接交付特定任务的完整实现。

功能能力

CodeTutor 通过四个主要的交互循环运行：启动评估、保存审查、手动提示和后续问题。

保存审查循环

当启用 codetutor-review-on-save 时，该软件包会挂钩到 Emacs 的保存过程。它在保存前捕获文件的状态，将其与保存后的缓冲区文本进行比较以构建统一的 diff，并将此 diff 以及项目上下文发送到 AI 后端。生成的教学响应随后显示在右侧的导师面板中。

手动提示与后续问题

用户可以通过 codetutor-ask 在 minibuffer 中与导师进行交互。此请求包括当前文件、项目上下文和架构记忆。用户随后可以使用 codetutor-follow-up 就之前的回答提出澄清性问题，从而在对话轮次中保持连续性。

项目评估与后续步骤

  • 启动评估：运行 codetutor-open 会触发项目评估，识别从哪里开始以及在编写代码之前需要哪些工程判断。
  • 下一步是什么：codetutor-what-next 命令会要求导师根据现有的项目上下文推荐单个最佳的下一步。

技术架构与上下文收集

CodeTutor 通过聚合来自多个本地数据源的数据来构建全面的提示词，以确保 AI 拥有足够的上下文来进行建议。

上下文来源

Source Purpose
PROJECT.md / project.md 产品和项目方向
spec/ directory 规范和设计说明
.codetutor/ARCHITECTURE.md 持久化项目记忆
Current file text 当前编辑的上下文
Tree-sitter/Imenu summary 缓冲区的语法级大纲
Project file index 帮助导师识别其他需要检查的文件
Diff since last save 自上次保存以来的特定变更
Open project buffers 当前会话中附近的任务

架构记忆

CodeTutor 实现了一个持久化记忆系统。当导师识别出架构观察结果时，它会将其封装在 codetutor-memory 块中。该软件包会自动提取这些观察结果并将其追加到 .codetutor/ARCHITECTURE.md 中，这是该软件包被允许自动写入的唯一文件。

后端集成与安全性

CodeTutor 支持两个本地后端：codex 和 pi。两者都经过配置，以确保 AI 无法修改用户的文件系统。

后端配置

  • Codex：在只读沙盒中使用 codex exec，并将批准策略设置为 never，同时使用临时会话。
  • pi：使用非交互式打印模式，并使用受限的工具集，仅限于 read、grep、find 和 ls。

安全层

安全性通过两层实现：禁止文件编辑的提示词级指令，以及将 AI 限制在只读模式的后端级命令边界。

安装与要求

CodeTutor 需要 Emacs 28.1 或更高版本，推荐使用 Emacs 29+ 以获得内置的 tree-sitter 支持。

Doom Emacs 配置

对于 Doom Emacs 用户，可以通过 packages.el 使用本地仓库配方进行添加，并在 config.el 中使用以下命令进行配置：

  • codetutor-open
  • codetutor-what-next
  • codetutor-ask
  • codetutor-follow-up
  • codetutor-refresh-architecture-memory

自定义

用户可以调整上下文限制（例如，codetutor-max-project-context-bytes）和系统提示词（codetutor-system-prompt）来定制导师的行为以及发送到 AI 后端的数据量。

Sources