Agent
快来分享你的内容吧～
又一个国产版 Codex 神器，也来卷办公了！
大家好，我是程序员鱼皮。 经常看我文章的朋友应该知道，之前测评 GLM 系列模型的时候，我用的都是智谱的 ZCode。 ZCode 是智谱官方推出的 AI 工作台，使用体验跟 Codex 之类的 AI 工具几乎一致，而且跟自家的 GLM 模型做了深度联调。  得益于 GLM 模型的能力，它已经成了我用得最多的国产 AI 工具。 而且开源之后，ZCode 正式发力，已经从写代码的工具变成了兼顾办公体验的万能工具。普通的办公任务可以交给 Work 模式，几百份文件的大活可以交给 Workflow 工作流，更专业的需求还能去插件市场装插件。  下面，实战教程开始~ ## 1、Work 模式 - 一句话整理报销单 先从最常见的办公任务开始。 作为一名创业者，每到月底报销，我都头大。 因为发票有的是 PDF，有的是截图，甚至偶尔还有随手拍的照片，整理起来又费时间、又容易出错。 为了测试 ZCode 的办公模式到底靠不靠谱，我准备了 12 份票据（全部是虚构的演示数据），还偷偷埋了 5 个坑。 比如同一张发票，我既放了 PDF 原件，又放了一张手机拍照版，这属于重复报销；打车行程单只是发票的附件，不能重复算钱；有张发票的购买方税号错了一位；有张发票的大写金额和小写金额对不上；还有一张是餐厅的结账小票，根本就不是发票。 操作很简单，打开 ZCode 新建任务，把装票据的文件夹拖进对话框，然后用大白话说出需求就行。 ```plain 文件夹里是我这个月的报销票据（演示用的虚构数据），帮我整理成一份 Excel 报销单，按费用类别汇总。 公司抬头：摸鱼科技（深圳）有限公司，税号 91440300MA5H7Q2K3R ```  ZCode 先把 12 个文件挨个儿读了一遍，PDF、截图、照片都能识别，1 分钟左右就读取完了。 而且在识别阶段，它就已经发现了好几个问题，比如烧烤那张发票的税号尾号是 8R，跟公司的税号对不上。 接下来，它加载了表格技能开始制作 Excel。第一次使用会有点慢，因为要先安装 LibreOffice 等处理库，用来重新计算表格里的公式，检查有没有算错。  表格做完之后，它还会把每个工作表渲染成图片，派一个专门的视觉验收子代理检查排版，发现问题再自主修复。 最后交付的 Excel 有 3 个工作表，分别是报销明细、分类汇总和行程单明细，公式和金额都经过了重新计算核对。  再来看看我埋的 5 个坑，AI 发现了没有？ 重复的发票它只算了一次，行程单也老老实实当成了打车发票的附件，没有重复算钱。税号错误和小票都被标了出来，提醒我退回重开或者补开发票。  **5 个坑找到了 4 个！** 唯一漏掉的是那张大小写金额不一致的图书发票。 这个坑确实比较阴，所以我的建议是，AI 整理完之后，关键金额还是要自己再扫一眼。 整体来说，我对这份报销单还是很满意的，比我自己对着发票一张张填快多了。 不过分析处理十几张票据还只是牛刀小试，如果让 AI 处理几百份文件的大任务，它能胜任么？ ## 2、Workflow - 让 AI 检查数百篇教程 我有一套免费开源的 [《AI 编程零基础教程》](https://github.com/liyupi/ai-guide)，光中文内容就有 380 篇文章、6000 多个链接。 AI 圈的变化实在太快了，模型几周就换一代，价格说改就改，链接说失效就失效。教程写得越多，过时的地方也就越多，靠人工检查一遍至少得好几周。  这个任务的复杂度很高。每个链接都要真实访问一遍，每条模型和价格信息都要联网核实，还要跨文章找出前后矛盾的说法。感觉做一遍 Tokens 消耗要爆炸了！ 这种任务就很适合交给 ZCode 新出的 Workflow 动态工作流。 普通的多 Agent 协作，大多是 AI 边干活边商量怎么分工。 而 Workflow 的思路不一样，AI 会先把「怎么干」写成一份代码脚本，相当于项目经理先写好 SOP 和排期表，然后再调度一支 AI 小队照着脚本分工干活，关键节点还有专人负责质检。  使用方法很简单，在需求前面加上 `/workflow` 就行，下面是我发给 AI 的提示词：  AI 先加载了 dynamic-workflows 动态工作流技能，然后检查仓库结构，统计出 3 个目录一共有 380 篇文章，去重后有 6287 个链接。 在写工作流之前，它先写了一个链接检测脚本试跑，并且用 EvalWorkflowSnippet 工具提前验证了文章分组，确认二十多个分组刚好覆盖全部 380 篇文章，一篇都没有遗漏。  准备工作做完，它才开始设计子代理的分工，并编写工作流脚本。 写好之后，ZCode 会把整个工作流画成一张流程图，等你确认之后再开跑。  可以看到这个工作流分成 6 个阶段，有跑脚本批量检测链接的，有「链接分诊员」复核疑似死链，有一群「扫描员」分组通读全部文章，还有「核实员」联网核实过时信息、「复核员」做二次确认，以及「矛盾交叉比对员」专门找文章之间互相矛盾的说法。 感觉真像是一个大公司的团队了，有模有样的~ 接下来运行工作流。我觉得 Workflow 的 UI 做得还是很不错的，哪些 AI 员工正在干活、哪些已经完成，一目了然。  由于任务量较大，跑了很久才完成，一共调度了 105 个子代理，消耗了 4000 多万 Token。  最终 AI 体检出 219 个问题，其中高严重度的有 35 个。按类型分，有 106 个失效链接、91 条过时信息和 26 处前后矛盾的说法，全部按严重程度排好序写进了 Excel。  接下来，我就可以照着这份 Excel 清单挨个修复了。这个工作流还能保存下来，下次教程更新完，直接复跑一遍就行~ ## 3、专业插件 - 录个屏就能复刻网站 前面两个任务用的都是 ZCode 自带的能力，如果想让它干更专业的活，就要用到插件了。 点击左上角的「插件市场」，可以看到 ZCode 提供的插件种类很丰富。 像 PDF、演示文档、电子表格、Word 文档这些办公插件已经内置好了。除了这些，还有 Zotero、Blender 这类专业软件的插件，以及 GitHub、飞书、钉钉、企业微信等常用工具的插件。  在「生产力」分类里，我发现了一个很有意思的插件 `Video2code`，点击安装。  顾名思义，Video2code 能根据网页的录屏视频还原出代码，把视频里的网站复刻出来。 我决定拿自己的 [《鱼皮 AI 导航》](https://ai.codefather.cn/) 网站试试。先用电脑自带的录屏功能，把网站的首页、AI 工具、绘图提示词、学习教程和资讯这几个页面都点了一遍，录了一段 30 秒左右的演示视频，放到项目目录里。  然后在对话框里选择 Video2code 插件，不加任何参数，直接输入提示词。  AI 先读取了视频的时长和分辨率，然后把视频按时间抽帧，拼成一张张带时间戳的图片，逐段观察每个页面长什么样、有哪些交互。  看完视频后，它还顺着视频里出现的页面，去官网抓取了真实的文案和图片，一共下载了 491 张图片素材。 然后 AI 先写好复刻计划，列出 17 个要还原的布局和动效，才开始搭建 React 项目。 项目跑起来之后，就进入了最磨人的验证环节。AI 会用 ZCode 内置的浏览器打开自己做的网站，截图、录动效视频，再跟原始录屏逐项对比，发现不像的地方就自己修改。  比如下面这张图，左边是原始录屏里的下拉菜单，右边是它复刻出来的版本，每个动效都要像这样拿出证据对比。  注意，这个任务比较复杂，需要反复调用视觉分析，执行过程中免费套餐可能会被限流，我这次就被限流卡了一阵子。 等我吃完饭回来，AI 终于完成了任务。  打开本地预览地址，跟原版对比一下。 先看首页首屏，导航栏、搜索框、精选推荐卡片的布局和配色几乎一模一样。录屏的时候我是登录状态，所以复刻版的右上角显示的是我的头像，连消息红点都复刻出来了。  再看绘图提示词页面，封面、标题和标签都对上了。不过布局有些出入，原版的瀑布流被做成了整齐的网格。  录屏里没有点开的社区、MCP 等页面，它统一做成了「内容整理中」的占位页，没有自己瞎编。 虽然没有 100% 还原，但只靠一段 30 秒的录屏，就能复刻出可用的、神似的网站，已经超出我的预期了。  如果你懒得录屏，也可以直接把网址发给它，插件会先用内置浏览器自己把网站录一遍，再走同样的复刻流程。 我感觉这个插件尤其适合产品经理，能快速做出可交互的原型，或者程序员重构老页面时拿来参考。 **不过复刻别人的网站要注意版权，学习研究可以，别直接拿去商用。** ## 最后哔哔 测完这 3 个任务，你也已经掌握了 ZCode 最核心的用法了：基础的 Work 模式、Workflow 和专项插件。 **根据任务选择最合适的方式，才能让 AI 把活干得又快又省。** 最后说个小福利 🎁。目前新用户注册 ZCode 能领 4000 万免费 Token，GLM 编程套餐用户在 ZCode 里还有 150% 的使用额度。通过我的 Link 进来，还能额外拿到一张夜间蹬蹬卡（1 亿 GLM-5.3-Flash Token），正好拿来跑 Workflow 这种大活。 👉🏻 指路：[https://zcode.z.ai/invite/QMRC52HR](https://zcode.z.ai/invite/QMRC52HR)  我是鱼皮，持续分享 AI 编程和 AI 工具干货。觉得有用的话记得点赞收藏和关注~
做 Coding Agent 搜代码：到底该选 RAG 还是 Grep？扒完 Claude Code 源码我顿悟了
大家好，我是不会喷火的小火龙。 很多团队自研 Coding Agent，第一步就是去搭向量数据库——Chroma、Qdrant、Weaviate 随便选一个，跑 Embedding，切片，建索引。看起来很"AI"，很高大上。 但你有没有想过：Claude Code，目前公认最强的 AI 编程工具之一，它的代码检索底层，其实就是一个 50 年前的命令行工具——`grep`？ 如图 1 所示，这就是很多团队盲目上 RAG 之后经历的真实工程困局，和 Anthropic 自己走过的弯路。  这篇文章想帮你搞清楚三件事：代码检索场景下 RAG 为什么频繁翻车、Claude Code 的极简方案如何跑通、以及你自己的项目到底该怎么选。 --- ## 一、为什么代码检索场景下，传统 RAG 频频翻车？ 代码是符号系统，不是自然语言。这句话听起来像废话，但绝大多数 RAG 翻车的根源就在这里。 向量语义检索的逻辑是意思相近的文本在向量空间里彼此靠近，这在自然语言里成立，但在代码里会系统性失效。举个例子：`createD1HttpClient` 和 `buildD1HttpClient` 语义高度相近，向量距离极小，但它们在代码里是两个完全不同的函数；而同一条调用链里相互依赖的函数，语义可能毫无关联，向量检索根本找不到它们之间的联系。 如下表所示，代码符号场景下，语义向量召回和精确匹配之间的准确率差距相当触目： **代码精确符号 vs 语义向量召回偏差对比** | 查询类型 | 示例查询 | 向量检索结果 | 精确匹配结果 | |:---|:---|:---|:---| | 函数名精确查找 | `createD1HttpClient` | 召回 `buildD1HttpClient`（相似但错误）| 精准命中，第 1 条结果 | | 错误码定位 | `ERR_DB_CONNECTION_TIMEOUT` | 召回语义模糊的错误描述文本 | 直接定位到常量定义行 | | 调用链追踪 | `handlePaymentCallback` 的全部调用方 | 召回支付相关的无关业务代码 | 逐个匹配调用点，一个不漏 | | 变量赋值查找 | `MAX_RETRY_COUNT = 3` 在哪里定义 | 无法区分定义和引用 | 精确定位定义行 | RAG 在代码场景还有三个硬伤。 第一，Chunk 切片会破坏 AST。按字符数盲目切片，会把一个类或一个函数切成两半，上下文彻底断裂。第二，索引永远赶不上代码变化。代码是秒级变动的，向量索引构建慢、增量同步复杂，极易产生脏数据，让 LLM 基于过期上下文产生幻觉。第三，全量代码送第三方向量化，隐私泄露风险不可忽视；本地跑大型 Embedding 模型，GPU 成本直接劝退。 --- ## 二、扒开 Claude Code 源码：极简的 Agentic Search 是怎么跑通的？ Anthropic 没有预先构建任何静态索引。Claude Code 的做法是把搜索变成 LLM 的"多轮自主探索循环"。 三大并发安全工具构成整个检索引擎： - `GlobTool`：按文件名模式快速扫描项目骨架，类似人类第一步看目录结构，确定大致位置。 - `GrepTool`（底层是 ripgrep）：毫秒级全文精确正则搜索，类似人类在 IDE 里按 `Cmd+Shift+F` 搜关键词。 - `ReadTool`：按需读取具体行号范围，类似人类定位到文件后翻开那几十行上下文。 为什么选 ripgrep 而不是普通 grep？ripgrep 用 Rust 开发，内置 SIMD 硬件加速，万级文件的全文扫描仅需约 200ms，自动跳过 `.gitignore` 指定的目录，天然适配代码仓库。内置的 `head_limit=250` 截断保护，防止搜索结果把上下文窗口撑爆。 如图 2 所示，两者的底层架构存在根本性的范式转移： **图 2：静态 RAG 检索管线 vs Agentic Search 多轮自主探索流程**  这个设计里最巧妙的地方：LLM 本身就是最顶级的动态 Reranker。每轮检索结束后，LLM 自己判断这个线索够不够、要不要继续顺藤摸瓜，完全替代了传统架构里那个静态的 Rerank 模型。 --- ## 三、权威佐证：Anthropic 踩坑实录与亚马逊论文实锤 放弃 RAG 不是 Anthropic 拍脑袋的激进决定，是被真实实验数据逼出来的。 Boris Cherny（Claude Code 技术负责人）在 2025 年 5 月的 Latent Space 播客里说过：Claude Code 早期确实搭建过基于 Voyage Embedding 的向量 RAG 检索系统，效果"还行"。但在实测用 Glob + Grep + Read 构成的 Agentic Search 之后，他的原话是： > "outperformed everything, by a lot. You avoid all the problems with security, staleness, and indexing." 安全问题没了，索引过期没了，增量同步也不用维护了。 学界的数据同样说明问题。亚马逊科学团队在 AAAI 2026 发表的论文《Keyword search is all you need》（[arXiv:2602.23368](https://arxiv.org/abs/2602.23368)）严格对比了标准向量 RAG 和纯关键词检索的 Agent 系统，结论是：关键词搜索在综合性能上达到 RAG 的 90% 以上，在代码等高度结构化的符号系统中，精确匹配的表现还显著优于向量语义检索。 从工程实践到学术实验，两份证据指向同一个结论：代码这个特殊领域里，精确性比语义相似性更重要。 如图 3 所示，代码搜索工具链使用图：  --- ## 四、反方视角：Cursor 为什么坚持重仓向量？ 读到这里，你可能会问：Cursor 呢？它也是 AI 编程工具里的顶流，技术路线和 Claude Code 截然不同，难道走错了？ 没有。两者的架构选择，背后是产品形态的差异。 Claude Code 是轻量 CLI 工具，面对频繁切换的项目，零冷启动是第一要务。每次打开一个新项目，没有时间也没有必要预建索引，Glob + Grep 随开随用，几毫秒就能工作。 Cursor 是 IDE 插件，常驻用户系统，面对的往往是几十万文件的超大 Monorepo。在这个规模下，每次查询都做全量 ripgrep 扫盘，性能会出现瓶颈。 如图 4 所示，Cursor 并没有抛弃 grep，而是构建了一套双轨混合系统： **图 4：Cursor 混合检索双轨架构**  Cursor 工程团队在官方博客（[Instant Grep & Codebase Indexing](https://www.cursor.com/blog/instant-grep)）里直说：纯语义搜索在精确标识符、错误码、函数名上表现太差，所以他们自研了基于三元组（trigram）倒排索引的"Instant Grep"来弥补。两套系统并联，精确归精确，语义归语义，用 Merkle Tree 实现分钟级增量同步保持索引新鲜。 Cursor 的一个典型场景是：用户说"微信支付退款重试逻辑在哪里"，记不住具体函数名，这时候语义向量检索才真的有用。 --- ## 五、实战选型指南：自研 Coding Agent 到底怎么选？ 扔掉非黑即白的架构争论。正确的问题是：你的产品形态和业务场景是什么？ 我把这套选型逻辑整理成了一张清晰的决策树，如图 5 所示： **图 5：Coding Agent 代码检索技术选型决策树**  三个场景的核心判断： 模式 1，极简优先，适合 90% 的个人开发者和轻量 CLI 工具。零依赖、零维护，直接用 ripgrep + Glob + Read 先把产品跑起来，有实际用户反馈再说向量的事。 模式 2，混合检索，适合 IDE 插件和常驻大型 Monorepo 的服务。精确符号归 trigram 倒排，模糊语义归轻量向量，两者并联。不要上重型托管向量数据库，自研 trigram 索引成本比你想象的低得多。 模式 3，LSP 语法感知，有明确跨文件引用追踪需求时接入 Language Server Protocol，获取符号定义和引用关系图。这才是"语义理解"真正应该发生的地方。 --- ## 结语 Anthropic 用 50 年前的 grep 打败了自己搭的向量 RAG，这不是反智，这是工程上的诚实：代码是精确的符号系统，grep 是精确的符号匹配工具，用对了工具比堆技术栈更管用。 希望这篇文章能帮你在自研 Coding Agent 的路上少走一段弯路。 如果你对这类技术拆解感兴趣，欢迎关注公众号「[小火龙AI 手记](https://mp.weixin.qq.com/s/1NIIz2-4XnP8cSDmr9Fa-g) 」。 这里持续挖掘 GitHub 等开源社区里真正好用、能打的高价值项目，拆解它们背后的工程逻辑；同时也记录我自己用 AI 搓工具、做产品、踩坑填坑的全过程实录。都是有一点技术基础就能看懂的干货，跟你一起把 AI 驯化成真正趁手的生产力工具。 --- *参考资料：* - *Boris Cherny & Cat Wu on Claude Code，Latent Space Podcast，May 2025：https://www.latent.space/p/claude-code* - *Claude Code 官方文档：https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview* - *Shreyas Subramanian et al.，"Keyword search is all you need"，AAAI 2026：https://arxiv.org/abs/2602.23368* - *Cursor Engineering，"Instant Grep & Codebase Indexing"：https://www.cursor.com/blog/instant-grep*
一文吃透 Pi：10w stars 的极简 Agent harness
Hi，我是松柏。 今年 AI 编程 Agent 领域卷得不行，Claude Code、Cursor、OpenCode、Codex CLI 都在疯狂堆功能，宠物、sub-agents、plan mode、MCP、扩展市场，恨不得把能想到的东西全塞进去。 不过有个项目却反其道而行之，它就是 Pi，一个主打极简的 Agent Harness：  它默认只给模型提供了 4 个工具：`read`、`write`、`edit`、`bash`，系统提示词加工具定义一共不到 1000 tokens。 就这么个极简到离谱的东西，GitHub 10 万+ stars，npm 周下载量 120 万+，3 个月从 54k 涨到 98k。不少人已经拿它当日常主力了：  这篇文章我会先带大家快速上手 Pi，然后深入拆解它的核心设计理念和分层架构。看完之后你会对 Agent 框架的设计思路有一个新的认识。 废话不多说，**点赞关注**，我们直接开始！ ## 快速上手 ### 安装 一行命令搞定： ```bash # 推荐方式 curl -fsSL https://pi.dev/install.sh | sh # 或者用 npm npm install -g --ignore-scripts @earendil-works/pi-coding-agent ```  装完之后终端里直接敲 `pi` 就能进入交互界面。 ### 配置模型 Pi 支持 15+ 模型提供商，Anthropic、OpenAI、Google、DeepSeek、xAI、Groq、Ollama 这些基本都有。配置方式也简单： - 有订阅的话（Claude Pro/Max、ChatGPT Plus 等），直接 `/login` 走 OAuth - 用 API Key 的话，设好环境变量就行，比如 `ANTHROPIC_API_KEY` 进去之后 `/model` 切模型，`Ctrl+P` 快速循环你的常用模型列表。而且它支持会话中途换模型，上下文会自动做跨提供商的转换，这个后面架构部分会细说。  ### 基本使用 跟其他产品类似，打开终端，输入你的需求，Pi 就会帮你完成： ```bash # 交互模式 pi # 一行式调用，适合脚本或 CI pi -p "给这个函数加单元测试" ```  Pi 默认只给模型 4 个工具： - `read`：读文件（支持图片） - `write`：写文件，自动建目录 - `edit`：精确文本替换 - `bash`：执行任意命令 你可能会觉得 4 个也太少了。不过仔细想想，有了 `bash`，需要搜文件就跑 `rg`，需要看 git 日志就跑 `git log`，需要装依赖就 `npm install`。 所以大部分需求其实不用专门做 tool，一个 `bash` 就能实现了，这也是 Pi 的核心设计思路之一。 ### 会话管理 Pi 的会话不是普通的线性记录，而是一棵树。每次对话都会存成树形结构，你可以在任意节点分支出去： ```bash pi -c # 继续上次的会话 pi -r # 浏览历史会话列表 pi --fork <id> # 从某个历史节点分出新分支 ``` 会话里用 `/tree` 可以看到完整的对话树，想跳回哪个节点就跳回哪个节点。 ### 四种运行模式 除了终端里直接交互，Pi 还有三种无头模式，方便把它集成到其他地方： | 模式 | 命令 | 适合场景 | |------|------|------| | Interactive | `pi` | 日常开发，完整终端体验 | | Print/JSON | `pi -p "query"` | 脚本调用、CI 流水线 | | RPC | `--mode rpc` | stdin/stdout JSON 协议，给非 Node 项目用 | | SDK | TypeScript API | 嵌入你自己的应用 | 这四种模式共享同一套 session 格式和事件流，所以不管从终端、Web 还是 CI 调用，看到的都是同一个 Agent。比如 OpenClaw 就是拿 Pi 的 SDK 模式做的一个完整产品。 OK，到这里基本上手流程就走完了。 接下来聊聊更有意思的部分，Pi 为什么要这么设计。 ## 极简的设计哲学 Pi 的作者 Mario Zechner 说过一句话：**"if I don't need it, it won't be built"**，翻译成大白话就是：没用的东西我不做。 整个 Pi 的设计都是围绕这条原则展开的。 ### 极简系统 Prompt 先看 Pi 的完整系统提示词： ```markdown You are an expert coding assistant. You help users with coding tasks by reading files, executing commands, editing code, and writing new files. Available tools: - read: Read file contents - bash: Execute bash commands - edit: Make surgical edits to files - write: Create or overwrite files Guidelines: - Use bash for file operations like ls, grep, find - Use read to examine files before editing - Use edit for precise changes (old text must match exactly) - Use write only for new files or complete rewrites - Be concise in your responses - Show file paths clearly when working with files ``` 就这？就这！加上工具定义一共不到 1000 tokens。 为什么系统提示词要这么短呢？ 因为现在的前沿模型经过大量 RL 训练，其实已经天生就知道怎么当一个 coding agent。我们不需要在 system prompt 里手把手教它该怎么做，它自己就会选工具、读文件、跑命令。Pi 在 Terminal-Bench 2.0 上的跑分也验证了这一点，极简 prompt 的效果并不比上万 token 的 prompt 差：  而且 prompt 越短越稳定，提供商那边的 cache 就越容易命中，每次请求的成本也更低。 ### 4 个工具 前面提到 Pi 只有 `read`、`write`、`edit`、`bash` 四个工具，这确实和其他 Agent 动辄十几个 tool 的做法很不一样。 Pi 的思路是与其给每个功能都做一个专门的 tool（搜索 tool、git tool、测试 tool……），不如只留一个 `bash`，让模型自己写命令。 另外工具少还有一个好处，就是模型做决策更快。工具越多，模型越容易纠结用哪个，甚至选错，4 个工具就那么几种排列组合，选择成本几乎为零。 ### 全权限运行 Pi 默认不弹任何权限确认，没有“是否允许写入文件”，没有“是否允许执行命令”，模型拿到工具就直接用。 这听起来挺激进的，不过也不是没道理，因为只要 Agent 能写代码、能执行代码、能联网，那所谓的权限弹窗本质上只是在给你一种安全感，实际拦不住什么。 毕竟就算让我们自己审批，不也是一路确认允许嘛。 当然，如果你的场景确实需要隔离，Pi 也提供了三种容器化方案，Gondolin（本地微虚拟机）、Docker、OpenShell（策略沙箱），按需选用就行。 ### 那些故意不做的功能 这部分我觉得是 Pi 最有意思的地方。很多 Agent 产品当成卖点的功能，Pi 一个都不做，但每个都给了更简单的替代思路： #### 1）Plan Mode → 写文件 不需要内置计划模式，直接写个 `PLAN.md`： ```markdown ## Goal 重构认证系统支持 OAuth ## Approach 1. 调研 OAuth 2.0 流程 2. 设计 token 存储 schema 3. 实现认证端点 4. 更新前端登录流 ## Current Step 正在做第 3 步 ``` Agent 能读能改，你也能手动编辑，还能用 git 管版本。比藏在 Agent 内部的 Plan Mode 透明多了。 #### 2）Sub-agents → bash 自调用 Pi 可以通过 bash 启动另一个自己： ```bash pi -p "review this PR" --provider anthropic --model claude-sonnet-4-5 ``` 还能丢进 tmux 跑，全程都能看到子 Agent 在干什么。相比之下，Claude Code 的 sub-agent 就是个黑盒，你只能看到最后的结果，中间过程完全不透明。 #### 3）MCP → CLI 工具 + README MCP 的问题在于上下文开销。像 Playwright MCP 一注册就是 21 个 tool、13.7k tokens，不管你这次用不用都占着窗口。Pi 的做法是做成普通的 CLI 工具，配一个 README，Agent 需要的时候用 `bash` 调，顺便读下 README 看用法，只在真正用到时才付 token 成本。 #### 4）后台进程 → tmux 需要在后台跑 dev server？用 tmux 起一个： ```bash tmux new-session -d -s dev "npm run dev" ``` Agent 随时可以 `tmux capture-pane` 看日志输出，比内置的后台 bash 功能更灵活，可观测性也更好。 ## 分层架构拆解 聊完设计理念，我们来看看 Pi 的代码是怎么组织的。  Pi 是一个 TypeScript monorepo，核心分成四层，从底到顶依次是： ### pi-ai：统一多模型 API 最底层的包，把各家 LLM 提供商的 API 抽象成一套统一接口。底层其实只需要对接四种协议，OpenAI Completions、OpenAI Responses、Anthropic Messages、Google Generative AI，各家提供商基本都是这四种 API 的某个变体。 这一层有几个值得学习的设计点： 首先是跨提供商上下文接力。你可以在会话中途从 Claude 切到 GPT，pi-ai 会把 Claude 的思维链转成 `<thinking>` 标签塞进消息里，尽量让新模型能理解之前的上下文。代码上大概是这样： ```typescript // 用 Claude 开始对话 const claude = getModel('anthropic', 'claude-sonnet-4-5'); context.messages.push({ role: 'user', content: '25 * 18 = ?' }); const claudeResponse = await complete(claude, context); // 中途切到 GPT，上下文自动转换 const gpt = getModel('openai', 'gpt-5.1-codex'); context.messages.push({ role: 'user', content: '对吗？' }); const gptResponse = await complete(gpt, context); ``` 然后是全链路的 Abort 支持。很多 LLM 封装库根本没处理请求中断的情况。pi-ai 从一开始就支持 `AbortController`，而且中断之后还能拿到已经生成的部分结果，不会因为中断就全丢了。 还有工具结果分离。一个工具执行完，可以分别返回“给 LLM 看的文本”和“给 UI 展示的结构化数据”，不用再从一堆文本输出里费劲去解析了。  ### pi-agent-core：Agent 循环 中间层，实现 Agent 的核心运行循环：收到用户消息 → 调 LLM → LLM 要用工具 → 执行 → 结果喂回去 → 再调 LLM → 直到不再需要工具为止。 这层的关键类是 `Agent`，它除了管状态（消息历史、工具列表、当前模型），还提供了两种消息队列： - Steering：Agent 干活的时候你插一句话进去，当前工具跑完就会处理 - Follow-up：排队等着，Agent 这轮忙完了再处理 整个循环是事件驱动的，所有生命周期节点都通过 `AgentEvent` 暴露出来，上层拿到事件就能构建各种 UI。  ### pi-coding-agent：编码 Agent CLI 应用层，也就是你实际敲的那个 `pi` 命令，核心是 `AgentSession`，在 Agent 循环之上加了这些东西： - 会话持久化：JSONL 格式的树形存储，每条消息带 `id` 和 `parentId`，分支操作不需要新建文件 - 自动压缩：上下文快满的时候自动 compaction 旧消息，压缩策略可以通过扩展自定义 - 工具注册：内置 read/write/edit/bash，另外还有 grep/find/ls 三个只读工具可选 - 扩展加载：用 jiti 动态加载 TypeScript，写完不用编译直接跑 前面提到的四种运行模式就是在这一层实现的，它们共享同一套 session 和事件流。 ### pi-tui：差分渲染的终端 UI Pi 的终端 UI 没有像 Amp、OpenCode 那样接管整个终端画面，采用的是像普通 CLI 一样往下写内容，保留终端自带的滚动和搜索。 渲染方式是保留模式（Retained Mode）：每个组件有一个 `render(width)` 方法，返回带 ANSI 样式的文本行。已经流式输出完的消息会缓存渲染结果，下次直接复用。 更新的时候用差分渲染，新旧两帧逐行对比，只重绘变化的部分，再配合终端的同步输出转义序列（`CSI ?2026h / CSI ?2026l`），把一帧的所有输出攒起来原子性地刷到屏幕上，在 Ghostty 和 iTerm2 上基本做到了零闪烁。 ## 扩展系统 Pi 整套扩展机制分三层： ### Extensions（代码级） 就是 TypeScript 模块，可以注册工具、添加命令、绑快捷键、拦截工具调用、自定义 UI 组件。示例代码： ```typescript // ~/.pi/agent/extensions/my-tool.ts import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'; import { Type } from 'typebox'; export default function(pi: ExtensionAPI) { pi.registerTool({ name: 'search_docs', description: '搜索项目文档', parameters: Type.Object({ query: Type.String() }), async execute(id, params, ctx) { const result = await searchIndex(params.query); return { content: [{ type: 'text', text: result }] }; } }); } ``` 保存后 `/reload` 热加载，不用重启。官方仓库有 50+ 示例，从权限确认、Git 检查点到 Snake 小游戏都有。 ### Skills（提示词级） Skills 是 Markdown 文件，定义特定任务的指令和工作流。和 Extensions 的关键区别在于它是按需加载的，平时只在上下文里保留一行描述（几十个 token），等真正被触发时才加载完整内容。 这样即使你装了几十个 Skill，也不会撑爆上下文窗口，也就是我们常说的“渐进式上下文披露”。 ### Packages（生态打包） Extensions、Skills、Prompt Templates、Themes 都可以打包成一个 Package，通过 npm 或 git 安装： ```bash pi install npm:pi-autoresearch pi install git:github.com/badlogic/pi-doom ``` ### Shopify 的 pi-autoresearch 说到 Package，就不得不提目前最出圈的一个，Shopify 工程师 David Cortés 做的 pi-autoresearch。  它是一个自动化性能优化循环：你设定一个要优化的指标（比如构建时间），Agent 就会自动尝试改代码、跑 benchmark、比基线快就保留、慢了就回滚，然后继续下一轮，直到你打断。 最有意思的是，这个扩展本身就是让 Pi 写出来的。 后来 Shopify CEO Tobi Lütke 看到这个东西，直接上手贡献了 32 个 commit。目前 pi-autoresearch 在 GitHub 上有 7900+ star，Shopify 内部用它把单测速度提升了 300 倍，React 组件挂载快了 20%。 ## 结语 我觉得 Pi 这个框架里最值得学习的一点就是不是功能越多越好，把核心的东西做到位就行，你们觉得呢？ 这篇文章就到这里了，如果有帮助的话麻烦点个关注吧~ 下期再见，拜拜👋🏻