在编码代理工具爆发的 2025 年，主流产品都在追求功能丰富：更多工具、更多配置项、更多安全护栏。然而，独立开发者 Mario Zechner 在构建 pi-coding-agent 时选择了一条逆向路径 —— 通过主动排除功能来换取可预测性与低开销。这种 "武断"（opinionated）设计哲学值得深入剖析，因为它揭示了代理工具设计的核心矛盾：灵活性与可控性之间的取舍。
传统代理的灵活性陷阱
Zechner 在过去三年亲历了编码代理的演进：从粘贴代码到 ChatGPT，到 Copilot 自动补全，再到 Cursor，最终到 Claude Code、Codex、Amp 等新一代代理 harness。在使用 Claude Code 的过程中，他发现这款工具逐渐 "变成了一艘宇宙飞船"，80% 的功能他从未使用过。更令他困扰的是，系统提示词和工具定义在每次更新中都会变化，导致工作流被打破、模型行为发生漂移。
问题的根源在于现有 harness 普遍采用的 "越多越好" 设计思维。Claude Code 提供了复杂的权限提示、计划模式、子代理调度、MCP 协议支持等特性，理论上为用户提供了极大的灵活性。然而，这种灵活性带来的代价是上下文膨胀、行为不可预测以及调试困难。当代理在后台偷偷注入上下文而不在 UI 中显示时，用户实际上失去了对模型输入的控制权。
极简代理的工程实现
pi-coding-agent 的核心设计原则是：如果不需要，就不构建。整个项目分为四个独立包：pi-ai（统一 LLM API）、pi-agent-core（代理循环）、pi-tui（终端 UI）和 pi-coding-agent（CLI 接线层）。每个包都遵循最小化设计，以下是具体的工程决策。
在提示词层面，pi 的系统提示词控制在约 1000 tokens 以内，仅包含四个工具（read、write、edit、bash）的定义和基本使用指南。相比之下，Claude Code 的系统提示词可达 10,000 tokens 以上，Codex 和 opencode 的提示词同样冗长。Zechner 的假设是：当前的前沿模型都经过大量强化学习训练，本身已经理解编码代理的任务，因此无需冗长的提示词来 "教会" 模型如何工作。这一假设在后续的 Terminal-Bench 2.0 基准测试中得到了验证。
在工具集层面，pi 刻意只提供四个核心工具，而非 Claude Code 的数十个工具。研究表明，模型对工具的选择并非越多越好 —— 过多的工具反而会导致决策瘫痪，增加调用错误的风险。四个工具（文件读写、命令执行）足以覆盖所有编码任务，而额外的 grep、find、ls 等工具仅作为可选的只读工具提供。
在执行模式层面，pi 默认采用 "YOLO 模式"—— 无权限提示、无命令预检、完整文件系统访问。这一决策基于一个务实的观察：任何能够读写文件并执行命令的代理，本质上都已经突破了安全边界。与其在运行时不断弹出权限对话框，不如将安全责任交给用户 —— 通过容器化或访问控制来实现真正的隔离，而非依赖虚假的 "安全剧场"。
刻意缺失的功能清单
pi-coding-agent 明确承诺不会支持若干常见特性，这些 "不做" 的决策本身就是产品哲学的体现。
第一是无内置 to-do 列表。Zechner 发现 to-do 列表往往会混淆模型而非帮助模型。代理需要额外维护和更新 to-do 状态，这引入了更多出错机会。用户若需任务跟踪，应使用外部 Markdown 文件（如 TODO.md）来记录，这既简单又可版本控制。
第二是无计划模式（plan mode）。传统计划模式试图让模型在不修改文件的情况下 "思考"，但这种隔离往往无法持久。pi 的做法是：直接使用文件作为计划载体，将目标、方法和当前步骤写入 PLAN.md，代理可以随时读取和更新。这种方式的优势在于计划可跨会话持久化、可共享、可版本追踪，而非仅存在于内存中的临时状态。
第三是无 MCP 支持。MCP（Model Context Protocol）服务器虽然提供了标准化的工具扩展方式，但代价是上下文开销 —— 例如 Playwright MCP 消耗约 13.7k tokens（占上下文窗口的 7-9%），Chrome DevTools MCP 更是高达 18k tokens。pi 的替代方案是构建自带 README 的 CLI 工具，代理按需读取文档（渐进式披露），避免了上下文预加载的浪费。
第四是无后台 bash。Claude Code 的后台进程管理功能存在可观测性问题 —— 进程状态在上下文压缩后可能丢失，且缺乏查询运行中进程的标准化方式。pi 建议用户直接使用 tmux 来管理长期运行的进程，这提供了更好的可观测性和控制力。
第五是无子代理。子代理调度虽然在复杂任务中有时有用，但会导致可观测性严重下降 —— 主代理无法看到子代理的完整对话过程。pi 的立场是：如果需要并行上下文收集，应显式创建新的会话而非嵌套调用。这种设计迫使开发者更早地规划工作流程，而非依赖运行时动态拆分任务。
性能验证与实践意义
极简设计是否会牺牲性能？Terminal-Bench 2.0 基准测试提供了实证数据。pi 使用 Claude Opus 4.5 与 Codex、Cursor、Windsurf 等主流工具同台竞技，在五轮测试中取得了竞争性排名。更值得注意的是，Terminus 2—— 一个仅提供 tmux 交互的极简代理 —— 同样在排行榜上表现不俗，这进一步支持了 "少即是多" 的设计理念。
Zechner 本人的生产实践经验同样有说服力：pi-ai 已被应用于七个不同的生产项目，pi-coding-agent 支持数百轮对话而无需上下文压缩（而 Claude Code 在类似负载下必须进行压缩）。这种持久性源于极简设计带来的低开销：更少的工具定义、更短的提示词、更简单的代理循环，共同降低了每轮对话的 token 消耗。
对于开发者而言，pi 的设计哲学提供了三条可操作的指导原则。首先是限制工具数量 —— 从四个基础工具开始，仅在实际遇到瓶颈时考虑扩展，而非预先提供所有可能用到的工具。其次是用文件替代内部状态 —— 将计划、任务列表、上下文摘要外置到 Markdown 文件，既可观测又可复用。第三是拥抱 YOLO 模式 —— 在本地开发环境中放弃虚假的权限提示，将精力投入到容器级别的安全隔离。
武断并非傲慢，而是一种设计承诺。pi-coding-agent 通过主动收缩功能边界，换取了可预测性、可维护性和低开销。这种减法哲学提醒我们：在代理工具的设计中，克制有时比强大更重要。
参考资料：Mario Zechner 的博客文章《What I learned building an opinionated and minimal coding agent》（2025 年 11 月 30 日）。