安装
npm i -g gentle-pi适合谁
Gentle Shell 适合这样的开发者：已经在用 Pi 这个编码代理，想要受控开发，希望代理在动手改代码之前先探索、只就真正的决策点提问，并把小任务保持在理解范围内小步推进。官方把这条日常工作流称为有机驱动开发（Organic Driven Development，ODD），并把它描述为：代理先探索再改动，只澄清真正的决策，小而已被理解的工作就保持在小步里。装好之后，一个普通的 Pi 会话会变成工作台：代理编排、实时变更与运行状态、受支持 provider 账户的用量监控、内置 diff 视图集中在同一界面，官方还列出可选的 SDD/OpenSpec、subagents、TDD 证据、review guardrails、skills 与 memory 集成。
不适合或需要前提的情况：如果不使用 Pi，官方没有说明它能在其他 agent 里运行；在官方迁移完成之前，npm 包名和仓库名都仍是 gentle-pi，按 gentle-shell 搜包会找不到。它需要哪些操作系统、Pi 要什么版本，官方说明未提到，需要自行确认后再装。
3 分钟完成第一次尝试
先接受一个安装期副作用，这是官方明说的：gentle-pi 会用它自带的 compact renderer 替换 Pi 内置的 codemode 扩展，之后每次启动 Pi 都会提示内置版没有加载。换句话说，这个副作用发生在安装这一步，而不是某次任务执行中；装与不装的决定，就是接不接受它的决定。依赖内置 codemode 行为的人应先评估再装；其他人可以把这条启动警告当作预期现象。
推荐主路径只有一条：在终端全局安装 npm i -g gentle-pi。安装后启动 gentle-shell，它会打开 Pi，并从自己的主目录 ~/.gentle-shell/agent 加载 Gentle Shell 包；如果想改为从既有的 ~/.pi/agent 加载，启动时加 --link 参数。这只是官方给出的加载位置切换，不是另一条安装方式，两种位置都在官方说明里，选一个即可。
成功信号按官方说明有两处：一是启动后打开的是加载了 Gentle Shell 包的 Pi 会话；二是出现内置 codemode 未加载的启动警告，它恰恰说明替换已生效。这两处都能在启动后的第一屏观察到，不需要先跑任何会改动内容的任务。第一次任务建议选纯分析型的小任务，对象是代码，例如让代理读一遍某个模块并解释它的结构与调用关系，暂时不让它改任何东西。ODD 的路径本来就是先探索再动手，这个阶段不会产生变更；至于它后续执行任务时会不会直接写文件、执行命令或访问网络，官方说明没有写明，不能当作已确认的事实，动手前先在会话里确认。
使用案例
案例一：理解一段陌生代码。在会话里发起这样的任务：先读某个模块，说明它的职责和依赖关系，不要改文件。走的是 ODD 日常路径——代理先探索，只就真正的决策点提问，小任务保持小步。如果代理在探索后提问，按官方对 ODD 的描述，这些应当是真正影响决策的问题。可期待的结果是一份基于探索的解释；具体回复格式官方未定义，以会话实际输出为准。
案例二：边改边核对。让代理做一个小改动，同时用内置 diff 视图逐处检查变更，实时变更与运行状态面板能让你看到代理正在做什么；如果你的账户属于受支持的 provider，用量监控也会出现在同一界面。这个案例的价值在于改动过程可见：视图由官方提供，改动本身由任务产生，两边可以对照着看。改什么由你和代理在会话里商定，官方说明只覆盖这些视图与状态能力，不担保改写质量。
使用边界
副作用与确认点：安装 gentle-pi 即替换 Pi 内置的 codemode（由 compact renderer 接管），启动警告是预期现象而非故障；除此之外，它的命令执行、文件读写与网络访问范围官方没有说明，是否产生这些行为属于未知，不要默认它只读。关于会话中产生的变更如何落盘、是否逐步确认，官方说明没有提到操作细节，只能在会话里观察代理的实际行为后再决定是否继续。
运行环境前提：面向 Pi 会话，经 npm 全局安装；能否在其他 agent 中使用、支持哪些代码或文本语言，官方说明未提到。官方明确的限制：npm 包与仓库名在迁移完成前保持 gentle-pi，产品名与包名不一致的状态会持续到迁移结束；--link 只切换包的加载位置。尚未确认的关键信息还包括：如何配置与卸载、卸载后内置 codemode 是否恢复，以及 SDD/OpenSpec、subagents、TDD 证据、review guardrails、skills、memory 集成各自怎么启用——官方只把它们列为能力，没有给出操作步骤。