Gentleman-Programming/gentle-ai · 上手攻略

  • 仓库：Gentleman-Programming/gentle-ai
  • 链接：https://github.com/Gentleman-Programming/gentle-ai
  • 分类：AI 编程工具 · Agent 配置框架
  • 作者：Tom
  • 更新：2026-10-06

是什么

Gentle-AI 是一个配置层而非又一个 AI 编程 agent：它接管你已经安装的 Claude Code、Cursor、OpenCode、Codex、Pi 等主流 AI coding agent 的配置，提供持久化记忆（Engram）、有机驱动开发（ODD）、收据驱动开发（RDD）审阅、以及精选 Skills 和 MCP 服务器聚合。它本身不运行 AI 模型，也不替代任何现有 agent——只是让这些 agent 在多人/多会话场景下更安全、更一致、减少重复解释。

⚠️ GitHub 显示截至 2026-10-06 约 7,564 Stars，支持 17+ 种 AI agent（最新数据以 GitHub 页为准）。

解决什么问题

  1. 每次新建 Session 都要重新解释上下文：同样的项目结构、coding style、业务规则，每次开新对话都要重来。Gentle-AI 的 Engram 模块让 agent 在工作过程中主动记录学到的东西，下次自动召回，不需要你反复说。
  2. Agent 的变更无法追踪、回滚：没有结构化变更管理，agent 改了什么、为什么改，散落在对话历史里。ODD（Organic-Driven Development）让 agent 在改代码前先探索、记录计划、改完后保持进度可恢复。
  3. 代码审阅依赖模型当时的判断：模型每次审阅可能给出不同结论，evidence 无法与代码快照绑定。RDD（Receipt-Driven Development）在审阅前冻结候选代码，证据锚定的是那个特定版本，而非模型事后回想出来的结论。
  4. 多人协作时 agent 行为不一致：各人配置的 agent 个性、技能、记忆不同，团队协作时产生混乱。Gentle-AI 提供共享配置、Personas 和 Skills，确保团队成员使用同一套行为约定。

快速安装

macOS（Homebrew）

brew install gentleman-programming/tap/gentle-ai

macOS / Linux（curl 一行脚本）

curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash

Windows（Go 安装，需 Go 1.25.10+）

⚠️ 官方 Windows 原生安装包和 Scoop Bucket 暂时不可用（正在等 Authenticode 签名配置），Go install 是当前 Windows 最可靠方式：

go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.0.0

从源码编译

git clone https://github.com/Gentleman-Programming/gentle-ai.git
cd gentle-ai
go build -o gentle-ai ./cmd/gentle-ai

升级（Stable 通道）

gentle-ai upgrade

Beta 通道（跟踪 main 分支）

# macOS / Linux
GENTLE_AI_CHANNEL=beta gentle-ai upgrade

# Windows (PowerShell)
$env:GENTLE_AI_CHANNEL="beta"; gentle-ai upgrade

⚠️ 安装前必须满足的前提条件（gentle-ai doctor 可检查）： - Git - Go 1.25.10+（Windows 必填；其他平台如用 agent 也需） - Node.js 18+ 和 npm（若选用 CodeGraph 社区工具） - Pi 已安装在 PATH（若选用 Pi agent） - OpenCode 已安装（opencode --version 成功即可）

Gentle-AI 不自动安装这些依赖，gentle-ai install 会检测并打印提示，但不会替你装。

核心用法

首次启动（交互式引导）

gentle-ai
# → 引导你选择：使用哪些 agent、加载哪些组件、选择哪个 Persona

Gentle-AI 生成配置文件在 ~/.config/gentle-ai/（或各平台对应路径），之后每次 agent 启动时 Gentle-AI 自动介入。

健康检查

gentle-ai doctor

读-only 报告，检查所有依赖是否就绪、配置文件是否有效、Skills 是否可加载。不修改任何文件。

Engram（持久化记忆）

agent 在工作过程中把学到的关键信息写进 Engram，下个 Session 自动检索：

# Engram 记忆条目示例（gentle-ai 自动生成，agent 主动写入）
## 项目：payment-service
- 使用 Stripe SDK v12，对象命名用 camelCase
- 订单状态机：pending → processing → fulfilled / failed
- 测试覆盖目标：core/ 目录 90%+

无需人工维护，agent 在合适的时机自动写入和读取。

Organic-Driven Development（ODD，有机驱动开发）

核心工作流： 1. 探索（Explore）：agent 读代码库，理解结构 2. 记录（Document）：对要改的内容写 Feature Document（授权的小改动可极简） 3. 变更（Change）：执行修改，保持进度文件更新 4. 验证（Verify）：跑测试，确认结果

ODD 默认在有可运行测试时采用测试先行（RED → GREEN → Refactor），无测试时 agent 说明异常原因并运行适用的功能检查。

Receipt-Driven Development（RDD，收据驱动审阅）

默认开启（gentle-ai review mode disable 可关闭），审阅证据锚定冻结的候选版本而非模型当下的判断： - 代码快照在审阅前冻结 - 审阅输出附上快照 hash - 开发者决定是否 commit/push/release

可选组件（Gentle-AI 的 Skill 体系）

组件 作用
Skills library 任务匹配时自动加载对应 Skill
Context7 MCP 可选，提供最新框架/库的文档
CodeGraph 只读代码符号图谱
Security deny-list 阻止访问 ~/.ssh、.env、凭证文件
Config backups 每次写配置前自动快照
Personas 可选角色；Gentleman 是「关怀但严格的导师」角色

Persona 示例

Gentleman Persona 风格：严谨、鼓励独立思考、不直接给答案而给方向。其他 Persona 可通过 gentle-ai persona set <name> 切换。

模型分配

可分别为 agent 角色和 review 角色配置不同模型（例如用较便宜的模型跑主要任务，用强模型跑 RDD 审阅）。配置方式在文档：https://github.com/Gentleman-Programming/gentle-ai/blob/main/docs/components.md

典型适用场景

  1. 长期项目维护：Engram 让 agent 记住项目规范，多 session 间不丢失上下文，不用每次重新解释 coding style 和业务规则。
  2. 团队代码规范一致性：统一 Gentle-AI 配置后，所有成员在同一套 RDD 审阅规则、Skills 和 Persona 下工作，减少行为方差。
  3. 对代码变更有审计要求：RDD 的快照锚定特性让每次审阅的证据可追溯，适合有合规要求的团队。
  4. 多 agent 混用：同时使用 Claude Code 写业务代码、用 Pi 做代码审查、用 OpenCode 做探索性实验，Gentle-AI 统一配置管理。
  5. 测试先行的 TDD 工作流：ODD 默认触发测试先行（RED-GREEN-Refactor），适合想建立工程纪律的个人或小团队。

坑与注意

  1. Windows 暂时无原生安装包：⚠️ 截至 2026-10-06，官方 Windows 原生二进制和 Scoop 安装均暂停（Authenticode 签名配置中），Windows 用户必须通过 go install，且需自行确保 Go ≥1.25.10 在 PATH。
  2. Gentle Shell（Pi 集成包）需单独安装：Gentle-AI 配置 Pi agent，但 Pi 的运行行为由 Gentle Shell 包单独管理，安装 Gentle-AI 本身不会同步 Gentle Shell 的行为更新。
  3. Pi 和 OpenCode 安装时 gentle-ai install 会阻断：检测到这两个 agent 未安装时，install 命令会停止直到你在 PATH 中提供对应二进制。
  4. Node.js 是硬依赖：即使你只用不支持 Node.js 的 agent（如纯 Claude Code），Gentle-AI 仍会检查 Node.js 是否存在（CodeGraph 工具需要）。⚠️ 这是当前设计的已知限制。
  5. RDD 审阅默认开启：如果你的工作流不需要审阅介入，每次都需要手动 gentle-ai review mode disable，否则 RDD 会出现在每次变更后。
  6. Beta 通道不稳定：GENTLE_AI_CHANNEL=beta 跟踪 main 分支，可能包含未发布的功能，不建议在生产环境使用。
  7. Skill 匹配依赖任务描述：如果任务描述模糊，Skills 库可能匹配错误或不匹配；建议在 ODD 探索阶段尽量明确变更目标。

与同类对比

| 维度 | Gentle-AI（本工具） | 手动配置各 Agent | Cursor Rules / .cursorrules | Claude Code 原生 Memory | |---|---|---|---| | 多 agent 统一配置 | ✅ 17+ agent | ❌ 各配各的 | ❌ 仅 Cursor | ❌ 仅 Claude Code | | Engram 记忆自动积累 | ✅ agent 主动写入 | ❌ 靠人工 | ❌ 靠人工 | ⚠️ 需 @project 指令 | | ODD TDD 工作流 | ✅ 内置，默认测试先行 | ❌ 无 | ❌ 无 | ❌ 无 | | RDD 代码审阅 | ✅ 快照锚定 evidence | ❌ 随意 | ❌ 无 | ❌ 无 | | Config 快照备份 | ✅ 每次写前快照 | ❌ 无 | ❌ 无 | ❌ 无 | | 安装配置复杂度 | 中（首次引导交互） | 低 | 低 | 低 | | 供应商锁定 | 无（配置现有 agent） | 无 | 仅 Cursor | 仅 Claude Code |

⚠️ Gentle-AI 与 Cursor Rules 是互补而非替代关系：Gentle-AI 统一管理多 agent 配置和 ODD/RDD 工作流，Cursor Rules 专注 Cursor 内的具体提示词规则，两者可以同时生效。

一句话推荐结论

Gentle-AI 适合已经重度使用 Claude Code/Pi/OpenCode 等 agent、但受困于「每次重新解释上下文」和「变更无审计」的团队或个人——它是一个不换 agent 但强化工作流安全性和一致性的配置层；只需轻度使用一个 agent 且不需要团队协作，直接用各 agent 原生配置即可。