Gentleman-Programming/gentle-pi · 上手攻略
- 仓库：Gentleman-Programming/gentle-pi
- 链接：https://github.com/Gentleman-Programming/gentle-pi
- 分类：AI Coding Agent · 开发流程治理 · Pi 生态
- 作者：Tom
- 更新：2026-09-09
这是什么
gentle-pi 是一个 Pi Coding Agent 的操作治理层（harness），将 Pi 从一个强大的自由式编码助手，转变为受 Spec-Driven Development（SDD） 规范约束的开发环境。
核心理念：大多数 AI coding agent 失败的原因不是模型能力不足，而是工作流缺乏纪律——需求不清就动手、架构决策消失在聊天记录里、测试跑得太晚或根本不跑、代码变动没有边界控制。gentle-pi 修复的是 agent 周围的工作流，而不是 agent 本身。
Pi 是 Earendil Inc. 维护的终端编码助手（MIT license，GitHub 91,600+ stars as of 2026-08），属于"AI Coding Agent"新品类。gentle-pi 则是给 Pi 添加 senior architect 行为约束的包。
解决什么问题
- Pi 每次会话"太自由"：需求不清就写代码，架构决策不落地，测试全靠自觉
- 想在团队中推广 AI coding agent，但缺少规范化的代码审查和交付流程
- 需要 subagent 编排能力，但没有统一的父 session 负责机制
- 项目 skill 存在，但模型经常忘记加载
快速安装
前提：已安装 Pi（
pi命令在 PATH 中）
# Pi 内一行命令安装
pi install npm:gentle-pi@0.14.0
安装后启动 Pi，gentle-pi 会自动运行 postinstall hook，配置 tuiMode 等运行时行为。
验证安装成功：
/gentle-ai:status
会显示 package 版本、SDD asset 状态、OpenSpec 配置、模型配置。
完全卸载：
pi uninstall npm:gentle-pi
rm -rf ~/.pi/plugins/gentle-pi # 可选，清理残留
核心用法
切换人格
# 在 Pi 对话中
/gentleman:persona # 在 gentleman 和 neutral 之间切换
# gentleman：senior architect 风格，主动引导规范
# neutral：普通模式
SDD 初始化（Spec-Driven Development）
/sdd-init
# 引导配置 openspec/config.yaml
# 解析 SDD 模式、工件存储路径、交付策略、审查预算
工作路由（Work Routing）
gentle-pi 将任务分为三类并强制分流：
| 任务规模 | 处理方式 |
|---|---|
| 小任务（改 bug、快速修复） | 保持 inline 直接在主 session 完成 |
| 中等任务（需要探索） | 委派给专注子 agent（subagent） |
| 大任务/高风险改动 | 强制走 SDD/OpenSpec 完整流程 |
TDD 强制（Strict TDD）
当项目配置声明了 test command，apply/verify 阶段必须记录 RED → GREEN → TRIANGULATE → REFACTOR 四个阶段的证据（git commit diff），而不是 agent 口头声称"我测了"。
# 查看当前项目的测试命令配置
# （需项目根目录有 .atl/ 或 gentle-pi 配置文件）
Subagent 编排
# 启动子 agent 探索（parent session 保持主控）
# 子 agent 专注单一任务，context 独立
# Parent session 最终负责交付决策
Skill 发现与加载
# 维护 .atl/skill-registry.md（项目 skill + 用户 skill）
# 审查/评论/PR workflow 自动发现可用 skill
# 不再依赖模型"想起来"加载
核心功能详解
el Gentleman 人格
让 Pi 表现得像一个 senior architect + 教师，而不是通用 chatbot。西班牙语响应默认使用 Rioplatense voseo（阿根廷/乌拉圭风格），可通过 neutral mode 覆盖并全局保存。
SDD/OpenSpec 工作流（11 个阶段）
gentle-pi 安装了完整 SDD phase agents 和 chains，覆盖：
init → onboard → explore → proposal → spec → design → tasks → apply → verify → sync → archive
每个阶段有独立的 prompt 和交付物模板，强制结构化输出。
Lazy SDD 预检
SDD 模式、工件存储、交付策略、审查预算在每个 session 只解析一次，之后只在真正需要决策时才 prompt 用户，而不是每次操作都问一遍。
运行时安全
- 拦截破坏性 shell 命令（
rm -rf /类） - 敏感操作强制确认
- 阻止直接读写敏感路径（
.env、/etc、~/.ssh等）
OpenSpec 兼容性
gentle-pi 将 OpenSpec 兼容行为作为 harness 的一部分。你不需要单独安装 OpenSpec CLI，SDD/OpenSpec 文件结构由 gentle-pi 自身管理：
- openspec/specs/ 存放规范文档
- openspec/changes/ 存放变更 delta
模型分配（Per-agent）
Pi 原生支持为不同 SDD agent 分配不同模型（强模型 vs 便宜模型），通过 Pi-native modal 交互：
/gentleman:models
# 在 Pi 内打开模型分配界面
Bounded Native Review
- 冻结一个候选方案
- 仅分发 controller 选择的审查维度
- 审查结果仅供参考，交付决策遵循普通仓库 policy
与同类对比
| 工具 | 定位 | 核心约束 | 适用场景 |
|---|---|---|---|
| gentle-pi | Pi 的治理层 | SDD/TDD/OpenSpec | 已有 Pi 团队，想规范化工作流 |
| Cursor Rules | IDE 集成规则 | .cursorrules 文件 | 个人/小团队快速上手 |
| Claude Code (native) | 自由式 agent | 无强制结构 | 个人探索性任务 |
| Gentle-AI (gentle-ai) | 跨 agent 生态 | SDD + Skills + Memory | 想在整个 coding stack 建立规范 |
gentle-pi 的差异化在于 OpenSpec 规范驱动 + TDD 证据链 + 严格工作路由，而不是单纯加几条 system prompt。
坑与注意
⚠️ pi-tool-cards 和 quiet-tools 不可同时启用：Pi 会拒绝重复的 bash、read、edit、write 注册。迁移期间禁用或移除 standalone package。
⚠️ Pi 全屏模式要求：Pointer input 行为（Compose hover/click/wheel）是全屏独占的，在非全屏 TUI 模式下不生效。
⚠️ Windows 构建需验证：verified native runtime 在 Windows x64/arm64 上通过 Go SumDB 验证源码构建，但 Windows 环境下的完整测试覆盖度请参考官方文档。
⚠️ Skill registry 需主动维护：.atl/skill-registry.md 不会自动同步所有 skill，需要项目自觉更新。
⚠️ el Gentleman 西班牙语模式：Rioplatense voseo 对中文用户可能产生意外的西语干扰，非西语项目建议始终使用 neutral persona。
⚠️ v0.14.0 兼容性：postinstall 会持久化 tuiMode 等全局状态。升级后建议 /gentle-ai:status 确认所有组件正常加载。
一句话推荐结论
如果你的团队已经在用 Pi 做 coding agent，但每次会话都在"自由搏击"——装 gentle-pi，把 SDD 流程跑起来，TDD 证据链让代码质量有据可查，subagent 编排让大任务不再失控。不是让 Pi 更聪明，而是让 Pi 的输出更可靠。
来源：GitHub README + gentle-ai ecosystem docs + pi.dev package registry ⚠️ gentle-pi 是 Pi 的治理包，Pi 本身需单独安装（pi.dev/packages/gentle-pi）