Postal：把「Claude Code 这类黑盒」拆开给你看的一个终端 AI 编码 Agent

想象这样一个场景：周五下午六点，你手上有一个三千行的 Python 服务要重构认证模块。IDE 里的 AI 插件能给你补全函数，但没法替你跑测试、没法跨十几个文件做统一改名、也没法在你要求「先给方案再动手」的时候真的先停下来等你点头。

Postal 是今年在开源社区出现的一个「反直觉」项目：它不追求比闭源竞品更强，而是选择把竞品最关键的东西——Agent 主循环、工具调用、上下文管理、审批流——全部用 Python 写出来，摊开在 GitHub 上任你阅读、拆解、二次开发。作者自己说得直白：那些他想学习的 harness 要么闭源，要么不是 Python。

一、从「用 AI 写代码」到「理解 AI 怎么写代码」

Postal 的作者 andrefetch 是个有明确学习目标的开发者。他想搞明白现代 AI 编码 harness 到底是怎么运转的：循环怎么转、工具 schema 怎么发给模型、上下文满了怎么办、危险命令怎么拦。这件事在闭源世界只能靠猜。

于是 Postal 的设计目标从第一天就不是「打败 Claude Code」，而是「把里面拆开给你看，并且顺手给你一个能用的东西」。README 里那句 "It's designed to be hacked on" 是整个项目的灵魂。

从 2026 年 6 月 26 日建仓到 10 月 24 日，379 次提交、151 个 star、32 个 fork，迭代节奏相当密集，版本号走到 v0.0.35——从小数点后两位就能看出：作者还在快速试错，远没到 1.0。

二、一个类比：Postal 像是「手动挡教练车」

如果闭源编码 Agent 像是自动挡汽车——你坐进去，它自己换挡、你自己只管看路；那 Postal 更像一辆拆掉了变速箱外壳的教学教练车：方向盘（交互循环）、油门（工具调用）、刹车（审批策略）全都在你眼前，仪表盘上还贴了张纸写着「这里面的齿轮是这样啮合的」。

你当然可以正常开着它上下路（当成生产工具用），但只要你想停下来拧一颗螺丝，工具箱就在旁边。

三、核心能力拆解

模型层：一切走 OpenRouter。 Postal 不绑定单一厂商。postal login 走浏览器 OAuth 授权 OpenRouter，之后 Claude、GPT、Deepseek、Kimi 乃至免费小模型都在同一个入口下切换，/model <name> 可以在会话中途换模型。底层用 openai SDK 的兼容协议 + httpx 流式请求，配合 tiktoken 做 token 计量。

工具层：一套完整的文件与命令操作原语。 内置 read、write、edit、apply_patch、grep、glob、list_directories 七个文件类工具，其中 apply_patch 特别值得一看——它能把创建、修改、删除、重命名打包进一次全有或全无的原子调用，避免 Agent 半途失败留下烂摊子。另有 bash 工具（自动识别操作系统 shell）、plan 待办工具、DuckDuckGo 网页搜索、URL 抓取和跨会话的键值记忆。

子 Agent 层：五种专职角色。 主 Agent 可以委派给 codebase_investigator、code_reviewer、software_architect、test_writer、debugger 五个专职子 Agent。这一层是「多 Agent 协作」在终端编码场景里少见的完整实现。

MCP 层：接外部工具和数据源。 走 fastmcp 协议，/mcp 随时查看服务器状态。

上下文层：长会话不崩。 上下文管理器会在工具输出堆积时先做 prune_tool_outputs() 剪枝，再判断是否触发压缩；压缩时把历史折叠成一份「续接简报」（continuation brief）继续跑，而不是直接报错退出。循环里还有 loop breaker 机制防死循环。

审批层：安全是一等公民。 六档策略：on_request（默认，每个变更操作都问）、auto_edit（工作目录内改文件不问，跑命令仍问）、auto（除危险命令外全放行）、on_fail（预留未实现）、never（只读模式）、yolo（全放行）。只读工具从不触发提示。

更关键的是两条硬规则，只有 yolo 能覆盖：一是 rm -rf /、dd if=、mkfs、shutdown、curl … | bash 这类危险命令在进入 bash 之前就被 safety/approval.py 的 DANGEROUS_PATTERNS 直接拒绝；二是任何触及工作目录之外的路径一律要求确认。这是很多同类工具做得不到位的地方——而编码 Agent 的能力边界，本质上就是它的破坏力边界。

会话层：关掉终端不等于丢失。 每轮对话自动落盘到 ~/.config/postal/sessions/<id>/（JSONL 转录 + meta.json）。postal --continue 回到上次现场，/rewind 把对话退回任意检查点（注意：只回退对话，不回滚已落盘的文件），/checkpoint <label> 可手动打标。老检查点会按 max_checkpoints 自动裁剪，老会话过 max_sessions 自动淘汰。也可以设 enabled = false 让会话完全不落盘。

UI 层：全屏 TUI + 组件化。 基于 Rich + prompt-toolkit，自建了一套组件化的终端 UI 体系（spinner、gutter、markdown 渲染、工具调用展示、确认框各自独立成组件）。流式输出、实时工具调用、可见的模型推理过程（/thinking on|off|low|medium|high 可调）、token 用量统计一应俱全。斜杠命令支持 Tab 补全和 ↑↓ 选择。

Hook 与 Skill 机制。 hooks/hook_system.py 提供 before_agent / after_agent 等生命周期钩子；skills/SKILL.md 机制会扫描并加载 SKILLS.md，还能「把你在其他 harness 上用过的技能搬过来」。这对想基于 Postal 造自己 Agent 的人价值很高。

四、上手门槛：CLI 还是 WebUI？

Postal 是纯终端工具，没有 Web UI，也没有 IDE 插件。想用图形界面得自己接。

好消息是安装门槛极低：

pip install postalcli
postal login    # 浏览器授权 OpenRouter
postal          # 进 TUI

要求 Python >= 3.11。需要 Git 基础。要注意 postal login 会打开浏览器完成 OAuth，纯 headless 环境得先拿到 OpenRouter 的 API Key 走 API_KEY 环境变量（Docker Compose 文件里正是用这个字段）。

五、争议与局限：得说清楚

第一，它更像教材而非生产力工具。 作者的初衷是学习。这决定了它的一些取舍：功能密度不如 Claude Code / Cursor，生态（插件、IDE 集成、社区提示词资产）几乎为零。

第二，安全模型仍依赖 LLM 的判断力。 危险命令模式匹配是静态的，DANGEROUS_PATTERNS 挡得住 rm -rf /，挡不住精心构造的绕过写法。而 auto 和 yolo 档位下，Agent 拥有完整 shell 权限。README 自己也提醒 yolo 只在沙箱或容器里用——这条建议应当被当作硬性安全要求，而不是可选建议。

第三，成本不可控。 OpenRouter 聚合了多家模型，Agent 循环里的自动重试、压缩摘要、多 Agent 委派都会放大 token 消耗。代码审查者、子 Agent 任务都要额外调模型，长会话下账单可能超出预期。

第四，成熟度有限。 v0.0.35，Alpha 阶段，on_fail 策略尚未实现，Roadmap 里的并行子 Agent 和 Git 集成都还是「正在做」。open_issues_count 目前是 0，说明反馈闭环还没有真正跑起来。

第五，作者集中度风险。 379 次提交里绝大部分来自单一作者，社区贡献有限，未来维护的连续性存在不确定性。

第六，许可证是 GPL-3.0。 这对「学习借鉴、二次开发」其实相当友好，但如果你要把 Postal 的代码闭源嵌入商业产品，需要格外注意 GPL 的传染性要求。

六、行业意义

Postal 代表的，是 2026 年 AI 编码工具市场的一个明确支流：除了「谁更聪明」的竞赛，还有「谁更透明」的竞赛。

当主流编码 Agent 全部闭源时，社区对「AI 到底怎么决策」的需求就只能靠猜。Postal 用一个 180 star 量级、纯 Python、可读性良好的参考实现，把 Agent harness 的内部构造摊到了台面上——这比任何架构博客都更直接。

它还顺带证明了另一件事：Agent 工具的价值不只在「能不能干活」，还在于能不能被信任。Postal 把审批策略、危险命令拦截、只读模式、会话不落盘这些「安全姿态」做成一等公民而非附属功能，这是同类项目里少见的清醒。

从增长曲线看，151 star / 32 fork / 379 commits 对一个 4 个月的新项目不算爆款，但它精准命中了「想自己造一个编码 Agent」的开发者群体——这类人往往不满足于用别人的成品，而是想亲手改一个试试。Postal 明说了「Build a tool, add a sub-agent, swap out a component」——它卖的不是工具，是可改造性。

对于想要理解 AI Agent 内部机制的团队，或者需要在 Postal 基础上定制内部编码助手（接私有模型、加自研工具、嵌进 CI）的工程师，这个项目值得认真读一遍 docs/architecture.md 和 agent/agent.py。