随笔 on 永恒的四月博客

Pi Agent：极简核心与可扩展的编程代理

Sat, 13 Jun 2026 22:05:58 +0800

Pi Agent 是一个运行在终端中的编程代理 harness。官方文档中对它的定义是 minimal terminal coding harness，这个定义基本概括了项目的核心取向：保持最小可用核心，将具体工作流交给扩展层。

它没有预设完整开发流程，也没有把所有常见能力直接打包进核心。Pi 更接近一个本地 agent runtime：负责模型接入、终端交互、工具调用、会话管理和资源加载。计划模式、子代理、权限确认、MCP、任务列表等工作流能力，则通过 extensions、skills、prompt templates、themes 和 pi packages 组合出来。

这种设计的重点在于限制核心职责，避免由核心替用户决定工作方式。

最小核心

默认情况下，Pi 给模型提供的主要工具非常有限：

read
write
edit
bash

这四个工具覆盖了本地代码代理最基础的能力：读取文件、创建或覆盖文件、精确编辑文件、执行 shell 命令。除此之外，Pi 还可以通过工具选项启用额外的只读工具，例如 grep、find、ls。

与很多编程 Agent 不同，Pi 官方 Philosophy 明确列出了一组默认不内置的能力：

No MCP.
No sub-agents.
No permission popups.
No plan mode.
No built-in to-dos.
No background bash.

这些缺省项体现了架构选择。MCP、子代理、计划模式、权限弹窗和任务系统都存在多种实现方式，也对应不同的使用习惯和安全模型。将它们固定在核心里，意味着所有用户都要接受同一套默认行为。

Pi 的选择相反：核心只保留必要运行时，复杂能力由扩展系统提供。

因此，Pi 的默认体验会比许多“大而全”的 Agent 更薄。第一次使用时，它更像一个可以读写项目并执行命令的终端代理。完整的项目管理流程需要在扩展层继续配置。

这也是它的边界。轻量任务可以直接使用默认工具完成；复杂任务需要通过扩展、技能或外部约束补齐流程。

扩展机制

Pi 的扩展体系主要由五类资源构成：

Extensions       TypeScript 模块，用于扩展工具、命令、事件和 UI
Skills           按需加载的能力包，遵循 Agent Skills 标准
Prompt Templates 可复用的提示词模板
Themes           终端界面主题
Pi Packages      通过 npm 或 git 分发的一组扩展资源

Extensions 是能力最强的一层。它们可以注册自定义工具、替换内置工具、添加 slash commands、监听事件、改写 UI、实现权限门禁、接入 MCP、实现 plan mode，甚至将 Pi 改造成另一种交互形态。

Skills 更适合封装任务知识。一个 skill 可以包含某类任务的工作流程、注意事项、辅助脚本和参考资料。与长期膨胀的系统提示词相比，skills 的优势在于按需加载。写 commit message、做 code review、处理 release、生成文档，各自可以有独立规则，不必永久占用主上下文。

Prompt templates 用于复用常见提示词。Themes 负责界面呈现。Pi packages 则是分发机制，可以把 extensions、skills、prompts 和 themes 打包，通过 npm 或 git 安装到全局或项目本地。

这一套机制让 Pi 更接近可组合平台。用户可以只使用默认工具，也可以按自己的工作流逐步增加能力。项目级配置可以放在 .pi/settings.json，用户级配置则位于 ~/.pi/agent/settings.json。

工作流编排

Pi 核心没有内置 plan mode 或 sub-agents，但并不阻止这些能力存在。相反，它鼓励通过扩展或 package 实现不同版本的工作流。

例如子代理可以作为额外 package 提供，由父会话负责协调，再把探索、实现、审查等阶段拆给不同角色：

scout / context-builder   收集项目上下文
worker                    执行明确修改
reviewer                  使用新上下文审查 diff 或方案
researcher                检索外部资料和官方文档
parent session            负责决策、取舍和最终汇总

这种模型解决的是上下文污染和职责混杂的问题。单个 agent 从需求分析、代码阅读、实现到审查一路执行，容易把早期假设带到后续判断中。将探索、执行和审查拆分，可以降低主上下文压力，也能让审查阶段获得更独立的视角。

计划模式也类似。Pi 不预设唯一的 plan mode。计划可以写入普通文件，也可以由 extension 提供交互式计划流程，还可以通过 OpenSpec / SDD 这类阶段化方法沉淀为 proposal、spec、design、tasks、apply、verify 等工件。

工作流因此脱离核心固定功能，成为用户根据项目复杂度选择的编排层。

与常见编程 Agent 的差异

许多编程 Agent 追求开箱即用，倾向于把完整体验集成在产品内部：权限确认、计划模式、MCP、子代理、任务列表、后台命令执行等能力都作为默认流程的一部分。

这种方式降低了初始配置成本，也让用户更容易直接进入自动化开发。但代价是默认行为较重，工作流边界也更难修改。用户通常会进入工具预设的流程，底层组合空间相对更少。

Pi 的差异在于默认取舍：

核心负责运行时，不负责规定流程。
扩展负责能力增长，不污染最小核心。
安全边界交给系统级隔离，避免用内置弹窗伪装成完整沙箱。
项目工作流可以被声明、安装、替换或移除。

这使 Pi 更适合需要自定义 agent 行为的人。比如希望使用特定 review 流程、特定计划格式、特定权限策略、特定子代理编排方式，或者希望把已有团队规范封装成 skills 和 extensions。

相对地，如果只需要一个开箱即用、默认流程完整的 AI 编程工具，Pi 的初始体验可能显得过于朴素。它要求用户理解工具边界，并愿意把工作流作为工程对象来维护。

安全边界

Pi 是本地编程代理，以启动它的用户权限运行。内置工具可以读写文件和执行 shell 命令，extensions 也是具有同等权限的 TypeScript 模块。

官方安全文档明确指出：project trust 不具备 sandbox 语义。它只控制项目本地配置、资源、packages 和 extensions 是否加载，不限制模型在已启动会话中请求工具执行什么操作。

因此，不可信仓库、不希望密切监督的生成代码、无人值守自动化任务，都不应该只依赖 Pi 自身的 trust 机制。更强的边界需要来自操作系统或虚拟化层，例如容器、VM、micro-VM、远程 sandbox 或带策略控制的执行环境。

这一点和 Pi 的整体设计一致。它不在进程内部提供容易被误解的半沙箱，真实隔离交给外部环境。

我的工具配置列表

在默认 Pi 之上，我目前主要增加了几个 package。它们位于 Pi 核心之外，建立在 Pi 扩展机制之上，组成个人工作流层。

gentle-pi        SDD / OpenSpec / review guardrails
gentle-engram    persistent memory
pi-subagents     subagent orchestration
pi-web-access    web search / fetch / GitHub clone / media extraction
pi-mcp-adapter   MCP adapter
pi-zentui        terminal UI / statusline

gentle-pi 是我配置里的主干。它把 Pi 调整成偏工程纪律的开发 harness，提供 el Gentleman persona、SDD/OpenSpec 流程、严格 TDD 证据约束、review workload guard、skill registry 以及 PR / issue / release 等协作技能。

我使用它的目的在于给复杂开发任务增加阶段边界。这里的重点不在“人格”本身，而在 proposal / spec / design、tasks、verify 这些阶段化约束。需求不清楚时先沉淀规格，进入实现前拆任务，实现后再验证。这样可以避免所有需求、假设和决策都留在聊天上下文里。

gentle-engram 提供持久记忆能力。Pi 本身有 session，但 session 更偏向会话记录。项目长期知识库需要保存跨会话仍然有价值的信息，例如项目约定、用户偏好、非显然发现、修复过的问题和配置决策。Engram 用来承担这部分职责。

我使用它的目的在于降低重复解释成本。每次进入项目时，不必重新告诉 agent 文章目录、脚本位置、测试能力或偏好的工作方式。但 memory 需要保持可验证和可维护，过期信息不能当成事实直接使用。

pi-subagents 为 Pi 增加子代理、chain、parallel、async、forked context 等编排能力。Pi 官方默认不内置 sub-agents，这个 package 相当于在扩展层实现了一套可组合的代理工作流。

我使用它的目的主要是分离职责。探索阶段交给 scout 或 context-builder，执行阶段交给 worker，审查阶段交给 fresh-context reviewer，外部资料检索交给 researcher。主会话只保留决策、取舍和最终汇总，避免一个上下文承担所有角色。

pi-web-access 提供外部资料访问能力，包括 web search、URL 内容抽取、GitHub 仓库克隆、PDF 提取、YouTube 视频理解和本地视频分析。对需要核查官方文档、库源码或网页资料的任务，它补齐了 Pi 默认工具无法直接覆盖的外部信息来源。

我使用它的目的在于减少凭印象写作和实现。涉及第三方项目、公开仓库、API 行为或文档解释时，需要优先读取 primary source，降低对模型已有知识的依赖。

pi-mcp-adapter 用于接入 MCP。Pi 官方核心不内置 MCP，原因仍然是保持核心小，并避免把某一种工具接入协议强制变成默认路径。需要 MCP 时，通过 adapter 扩展即可。

我使用它的目的在于保留 MCP server 的兼容性。MCP 在这套配置里只是可选接入层，不进入 Pi 核心依赖，也不承担所有工具能力的入口。

pi-zentui 负责终端界面和状态展示，提供类似 Starship 的 statusline 和另一套 TUI 风格。它不改变 agent 的能力边界，但会影响长会话中的可观察性。

我使用它的目的主要是改善交互体验。模型、上下文、工作目录、状态提示、token 使用等信息更容易在终端里被看到，长时间使用时成本更低。

这些工具组合后的实际形态更接近一个个人开发 harness：Pi 提供极简运行时，package 提供工作流能力，项目配置保存本地约束，memory 保存跨会话事实，subagents 负责拆分复杂任务，web access 负责事实核查。

我的使用场景

我的使用场景主要集中在本地项目开发和技术资料整理。默认 Pi 可以完成轻量读写和命令执行；在此基础上，额外配置用于补齐长期使用中更容易出问题的部分：需求沉淀、上下文管理、事实核查、审查和交互可观察性。

目前更适合用 Pi 处理的任务包括：

在终端中直接阅读和修改本地项目；
根据项目约定生成或调整文档、脚本、配置文件；
通过 web access 核查官方文档、公开仓库和 API 行为；
通过 SDD / OpenSpec 管理边界不清楚的复杂需求；
通过 subagents 拆分探索、实现和审查；
通过 memory 保存跨会话仍然有效的项目事实。

这套配置不追求“一键自动开发”。更准确的定位是把 AI 编程变成一个可编排、可审查、可回溯的本地工作流。

轻量任务仍然可以直接交给默认工具。复杂任务则需要先确定范围，再决定是否使用 SDD、是否委托子代理、是否需要外部资料核查、是否需要 fresh review。

工具本身不替人决定这些问题。真正需要维护的是流程、上下文、权限、审查和项目规范。Pi 提供底座，我的配置负责把这些边界补上。

日月反背睡不着的晚上

Tue, 12 May 2026 03:48:21 +0800

这种状态已经持续很久了，每天凌晨的3-5点会醒来，白天10点后开始犯困。我的床太软了，如果我白天躺下，那么我一定不顾闹钟的作用睡到可以起床的时间，大概在下午16-18时。我想这是由于焦虑的原因，对未来的对明天的焦虑。这样日夜颠倒的生活造成的影响反过来加重了我的焦虑和内耗。

从我夜里醒来那一刻开始，耳鸣像机器运行时的轰鸣声，提醒我的大脑开始运作思考。我的头会非常酸胀和疼痛，其中的大脑想必在身体睡着的时候一直在工作。当我醒来时就开始总结、内耗、回想，尝试给昨天总结出一个Todo，而记忆系统会说这根本不可能，因此只能空想着凭空产出某些事项去推动今天应该“焦虑待办”的事情。

在此之后第一个思考的问题就是今天的早餐。假如我4点醒来，那么直到早餐店开门还有三小时。接着我开始思考有没有可能用别的方式回应肚子的抗议，开始考虑冰箱有没有食物，即食的还是需要处理？即食是否因为冻了一夜需要加热？吃完会不会伤胃变成需要加热处理？需要处理的话这个时间（凌晨四点）会不会发出声音影响其他人？想喝热水烧水时的声音会不会太吵？一系列脑子里的小人开会。

当我靠在床上没做任何事情而脑子里左右互搏，否定所有让自己行动的方案，最终决定饿着肚子撑到天亮的时候便开始把思考方向转向有什么方式能够消磨时间。在不触犯前一步思考过的规则里把注意力从饿着的肚子上转移，那么实际上我只有一个手机可刷，不过是在考虑从这些刷过千百万次的信息流里找到某些东西把注意力吸引走而已，过程还附带潜意识里对自己没有在现实做些什么有价值的事情而浪费时间的批判。

上面写的那么多而客观上我的身体做了什么呢？——什么没做，只不过是醒来，然后倚靠在床头把脸对着手机而已。

一个微小的动作如此，更不用说处理日常事务：

什么时候刷牙，吃饭前还是吃饭后
刷牙洗漱的顺序，洗脸用哪个毛巾，加不加洗面奶
吃饭、穿鞋、剪指甲、取快递
… …

任何微小的事情在我脑子里都是一个巨大的工程。

在个人作息和社会生活相背的问题上。假如一天我不需要与任何人打交道那很好，长久的这样生活已经让我摸清了如何处理我的日常需求问题的范式，它们基本上只包括什么时候周边哪家商店、外卖还在提供配送等基本生命维持的需求。

假如在某天我需要和社会接触去办某些事那么我需要考虑的就更多了，首先要在白天工作时间在一个我仍能清醒并且自主思维活跃的时候，有时候常以为自己能在某个约定的时间到达，实际上因为太困忽略闹钟起不来而错过。

网络和AI建议我把想法写到某个地方给脑子卸货，于是我想到了挺久没更新的博客。

在我写这篇文章的当下，在这个凌晨四点，我尝试写一些什么用来理清自己的思绪，总结某些事项，做做未来计划什么的。但是我发现我并不能做到这些，其次是我的生活非常单一而我清楚应该从哪些角度整理，我能总结到的只是我自身感觉到的，我可能需要一面镜子和其他人聊聊或者把这篇文章丢给AI什么的。

对于未来我已经不能看得很清晰，我想这就是我焦虑的来源。

即使我像前文一样脑子里有很多的思考，把我的想法以某种形式带到现实世界是非常困难的事情。我写这篇文章的时候一直在逐句逐字斟酌，我在想刚写下的那句话是不是和我的实际完全符合，这段和下一段衔接怎么样，写这个内容会不会太暴露自己，语言风格是不是和我个人一样，用词是否正确，写完会不会招致刻薄的评论等等。

而且我在写某一句话的时候除了停下来思考这些，还会在最后直接跳过这句话开始考虑下一句，下一个内容的写法。从客观视角看我只是写某句话停到一半开始注意力稀疏停下。

这些思考并不能体现我写文章的水平上，我的文笔还是这么烂哈哈哈。

即使心里明白现实世界和我脑子的想法是不同的，情况完全没有脑子想象的那么糟糕，只是稍微不注意就会被脑子控制。。。

如此回想起来真的感觉我一直在水中捞月。

嗯、甚至没人来看我的博客。。。

啊、两分钟后的自己，你想好这篇文章的tag和categories了吗

谷歌 Vertex AI API 调用与 429 问题

Wed, 25 Mar 2026 13:51:45 +0800

如果想调用市面上比较前沿的多模态模型制作一些东西，使用 GCP 中的 Vertex AI 是一个不错的选择。它提供谷歌最新的 Gemini 模型调用权限，一站式支持文本、图片、视频、语音模型。

如果是新注册的 GCP 账号，一般还可以配合 Free Trial 的 300 美元赠金来用。

大体步骤是：创建一个 Google 云服务账号 -> 在控制台启用 Vertex AI 的 API 功能 -> 开通一个服务账号并授予 Vertex AI User 角色。然后可以通过 ADC 调用；如果你是服务账号方式，也可以下载对应的 JSON 文件来配：

https://googleapis.github.io/python-genai

在使用过程中会发现有时候经常返回 429 报错：

{ "error": 
    { "code": 429,
      "message": "Resource exhausted. Please try again later. Please refer to https://cloud.google.com/vertex-ai/generative-ai/docs/error-code-429 for more details.",
      "status": "RESOURCE_EXHAUSTED"
      }
}

一些比较新的模型，我自己用下来会更容易碰到这种情况。不过这更多是个人观察，不算官方结论。

官方文档里提到，部分 Gemini 模型会使用 DSQ（Dynamic Shared Quota，动态共享配额）。DSQ 没有固定的预定义 quota，请求会在共享容量池里动态分配。所以 429 不一定表示你打到了一个固定 quota，也可能只是某个时段共享资源比较紧张。

https://docs.cloud.google.com/vertex-ai/generative-ai/docs/quotas

官方建议是：

用 global endpoint；

做 truncated exponential backoff；

平滑流量，避免秒级尖峰；

需要更稳定容量时，改用 Provisioned Throughput（加钱买预订配额，这非常贵）

这非常难受。不过根据我的观察，在北京时间早上 9-12 点时会好很多

如果真的频繁 429，那么除了做重试和错峰，把对模型要求不高的业务先指向比较老、比较便宜或者更稳定的模型，也会缓解一些。

我的第一篇博文

Tue, 17 Mar 2026 12:01:08 +0800

我为什么还在写博客？

似乎是一种情怀？在我学习计算机技术的时期，那时候还没有人工智能，我查找资料的能力仅限于使用百度搜索。结果自然是被导航到许多沾满牛皮癣悬浮窗的文章页面。我在这些牛皮癣里找到一些高质量的干货，想看看作者的其他文章，就会从转载来源链接到作者的个人博客。

我会惊叹于这些网站干净、整洁、易读的界面。包括站点中作者的生活、心情分享，都让我感觉到这背后是一个个鲜活的同路人，枯燥的学习也有了一种并不孤单的感觉。即使我当时还没有“博客”“Markdown”这些概念，开源精神的种子已经在我心里种下。

即使学的是计算机技术，这些年我每天也都在网上冲浪。但十几年来，我在互联网各个平台的评论区里其实很少发言，更多时候只是在看，旁观人们围绕某个观点讨论、争执、拉扯、对骂。

我不太知道该怎么描述这种感觉，我只是觉得很混乱。再加上这几年社会戾气的上升、平台言论监管越来越严格，以及网络水军行业的兴起，我会觉得这些评论区已经越来越没有什么真正有价值的内容了。或许也是因为我没有找到真正高质量的社区。

我喜欢 GitHub Issues 里的讨论氛围。人们会就事论事，正式而有条理地围绕一个项目讨论，并且真的推动它往前走。我想，这才是我想要的。

还需要靠博客分享和获取知识吗？

我认为，当前如果从学习者的角度看，从个人博客页面获取知识的效率，远不如与人工智能直接讨论来得高。除非是某个行业前沿里一些大佬的分享，就像 AI 对 Stack Overflow 访问量的冲击和改变一样。

个人博客更多承载的，可能是人们对某些事情的观点，而不只是技术知识；也包括对特定场景的经验分享，例如对新工具、新软件的看法。

我是如何搭建这个博客的？

整个过程都是借助 AI 完成的。当我想起我那个闲置的域名，并且想搭建一个博客的时候，我只是把我的想法打进输入框。我有一个 Codex，我问它我想要搭建一个静态博客可以用什么工具，于是它向我推荐了 Hugo，并帮我完成部署。

在选择和配置主题的过程中，所有的配置文件也都是使用 Codex 帮我改写的。我只是说出了我想要的效果而已。我觉得 Codex 是非常好用的工具，在 Linux 环境下办公，可以在任何地方启动 Codex，执行命令也方便，几乎等同于我的系统助手。

我会分享什么？

我个人的技术知识肯定没有 AI 丰富，所以在技术分享层面，我可能不会有太多见解。我更多会分享一些踩过的坑、工具使用技巧等等，还有一些日常、散文。

我的文笔不是很好，个人观点也不是很成熟。

这些文章可能会使用 AI 调整排版，纠正语病和错别字，确保在符合我观点的情况下，只做最小的修改。

夜渡小记

Sat, 14 Mar 2026 17:35:00 +0800

江边的渡口很小，木牌上的字被风雨磨得发白，只剩一个模糊的“渡”字还算清楚。天刚黑，河面像一张慢慢铺开的铁灰色绸布，偶尔被船桨划开，裂出几道短暂的银光。

船夫没有多话，只在我上船时点了点头，替我扶了一把晃动的船舷。船上除我之外，还有一个背竹篓的老人，一个抱着油纸包的孩子。大家都沉默着，像是怕惊动了河心刚升起的那轮月亮。

船离岸后，四周的声音忽然变得很远。岸上的犬吠、茶摊的招呼、晚归人的脚步，都隔着水雾，轻得像别处传来的旧梦。只有船底触水的声音一下一下，稳稳地托着夜色往前走。

老人先开了口，说今年的春天来得慢，田里的水还冷。孩子却只顾看月亮，忽然问船夫，月亮是不是也要过河。船夫笑了笑，说它不过河，它只是一直跟着有心事的人。

这话一出，大家都安静了片刻。风从河面吹过来，带着湿润的草木气息。我低头看水，月影正碎在船边，又在下一瞬重新拼好，像许多说不清的念头，散了又聚，聚了又散。

靠岸时，远处村口亮着两盏灯，暖黄得很。老人背起竹篓，孩子抱紧油纸包，各自走向不同的小路。船夫把缆绳往木桩上一绕，仍旧什么都没问，只说了一句：夜里风大，路上慢些。

我回头看那条河，月光还落在水中央，平静得像从未有人经过。可我知道，刚才那一趟短短的夜渡，已经把许多白天说不出口的话，都悄悄带到了对岸。