1. 为什么我在终端里折腾了一圈最后留下了 Pi Agent事情得从几个月前说起。我在本地跑一个中小型项目代码量不算大但涉及好几个服务模块来回切换编辑器、手动跑测试、重复敲启动命令一天下来真正写代码的时间没多少全耗在这些机械操作上了。当时想找个能直接在终端里帮我处理这些杂活的工具就顺着社区里的讨论试了一圈从 codex 到 opencode 再到 pi coding agent都装过、也都实际跑过一阵子。先说结论codex 很强但对我来说太重了它更像一个完整的会话式编程平台opencode 灵活可配置项多得让人头大适合愿意花时间打磨工作流的人。而 Pi Agent也叫 pi coding agent走的是另一个路子——极简。它不是一个庞大的 IDE 插件体系也不是又一个聊天机器人外壳它更像一个嵌在终端里的编程代理你给它一个任务描述它在你的项目上下文里自己规划、改代码、跑命令、看结果然后继续迭代直到完成任务或者遇到它搞不定的问题再回来问你。这种定位解决了我最实际的痛点我不想为了一个辅助工具去学习一整套新平台的操作逻辑也不想在编辑器、网页、终端之间来回粘贴代码。我就想在一个终端窗口里用自然语言交代任务然后看着它自己干活。Pi Agent 这个名字在相关热搜里经常和 codex、opencode 放在一起比较其实不太公平——它们不是同一个量级的东西。Pi Agent 的定位就是轻量、本地优先、可随时介入。它不追求取代你的开发环境而是嵌进你现有的终端工作流里做那个帮你跑腿的人。简单说它就是给懒得开 IDE 又不想手动敲一堆命令的人准备的。这篇就按我自己的安装和配置过程来写从环境准备到跑通第一个任务再到我踩过的一些坑尽量把每一步为什么这么做也讲清楚。如果你也是一个日常重度依赖终端的开发者这篇应该能帮你省掉不少试错时间。2. 安装前的三个决定环境、包管理器、模型来源2.1 先确认你的终端环境是不是够用Pi Agent 本质上是个命令行工具所以它对终端环境的要求比一般 GUI 软件要敏感得多。我一开始就是在 Windows 上直接开了个 PowerShell 就想跑结果各种路径问题、脚本执行策略问题接踵而至。后来换了 Windows Terminal Git Bash 的组合才顺畅起来。这里先说清楚我的环境基线方便你对照项目我的配置说明操作系统Windows 11Linux 子系统备用macOS / Linux 同样适用终端Windows Terminal Git Bash原生 cmd / PowerShell 也可以但有兼容性风险Python3.11部分组件依赖较新的 Python 特性Node.js20 LTS仅部分辅助脚本需要非必须Git2.40很多安装源、组件拉取都走 Git如果你还没装 Python 或 Git网上相关的安装教程很多这里不展开了。只提醒一句安装时务必勾选Add Python to PATH这个选项没勾的话后面跑pi --version大概率会提示命令找不到。这是我见过最多的新手翻车点而且问题症状很迷惑——Python 本身能跑但命令行就是找不到 pi。Git 方面Windows 用户建议直接用 Git for Windows因为它自带了一个完整的 Bash 环境对后续执行安装脚本、配置代理源都友好得多。我甚至可以说在 Windows 上折腾 Pi Agent一个好用的 Bash 比什么都重要。2.2 Node.js 和 Python 的版本这道门槛Pi Agent 的核心逻辑是 Python 写的但在安装过程中会用到 Node.js 来处理部分前端资源或工具链脚本。这听起来有点分裂但实际用下来是有道理的Python 负责 Agent 的核心决策和代码分析Node.js 生态里那些现成的格式化工具、语言服务协议实现直接复用比自己重写高效得多。版本上有几个硬性要求需要特别注意Python 必须在 3.10 以上。我最初用的 Python 3.8安装时直接报了一个依赖解析错误提示某个包需要typing_extensions的新版本而那个新版本又要求 Python 3.10。如果你机器上同时有多个 Python 版本建议在安装 Pi Agent 前用python3 --version确认默认版本必要时可以用虚拟环境隔离。Node.js 建议 18 以上。这个不是安装硬门槛但某些 Agent Skill后面会讲到在低版本 Node 下表现不稳定尤其是涉及自动补全和格式化的时候。如果你还没装 Node.js直接用 nvm 管理比较好方便以后切换版本。千万别直接去官网下个安装包一路 next一旦你以后需要切 Node 版本就得重新装一遍环境变量非常痛苦。2.3 你打算让它用哪个模型干活这是 Pi Agent 配置里最关键、也最影响体验的一步。Pi Agent 本身是一个代理框架它需要一个大语言模型作为大脑来理解任务、生成代码和决策。模型来源有两种主流方案方案一使用云端模型 API这是最省事的方式。Pi Agent 支持 OpenAI 兼容的 API 接口你可以填入自己的 API Key指定model参数即可。我用的是 OpenAI 的 GPT 系列整体表现最稳定。也有朋友用其他兼容接口但实测在工具调用Function Calling的稳定性上会差一些。方案二接入本地模型如果你有本地部署的模型比如通过 Ollama、LM Studio 等工具跑的量化模型也可以让 Pi Agent 直接连本地接口。好处是数据不出本机、没有按 token 计费的压力但缺点也很明显本地模型的工具调用能力直接决定了 Pi Agent 的上限。我在本地跑过一个 7B 参数的量化模型简单任务比如给某个函数文件加上异常处理还能凑合稍微复杂一点的多步任务就开始逻辑混乱经常改错文件或者反复做无用修改。我的建议很直接第一优先用云端模型 API先把流程跑通建立对工具的体感之后再根据需求尝试本地模型。别一上来就搞本地模型不然你会把工具调用不稳定造成的错误误以为是 Pi Agent 本身的问题然后直接弃坑。3. 安装全过程从安装包管理器到跑通pi --version3.1 安装包管理器的选择逻辑Pi Agent 官方强烈推荐使用 pipx 来安装而不是直接用pip install全局安装。原因很简单pipx 会自动为每个工具创建独立的虚拟环境避免工具依赖和系统 Python 包产生冲突。这对 Python 生态的工具来说是标准做法了就像你用 npm 全局装 CLI 工具时也会担心依赖冲突一样。安装 pipx 非常简单# macOS brew install pipx # WindowsGit Bash 环境 python -m pip install --user pipx python -m pipx ensurepath # Linux sudo apt install pipx装完记得重新打开终端让 PATH 生效。验证方式pipx --version这一步虽然琐碎但确实能避免后面很多奇怪的依赖问题。我见过有人在系统 Python 环境里强装 Pi Agent结果几个月后因为某个系统级包升级Pi Agent 突然就废了。用 pipx 隔离之后这个问题就不存在了。3.2 核心安装命令和安装过程中可能出现的报错接下来就是正式安装 Pi Agent 了。安装命令非常简单pipx install pi-agent这里安装的是核心命令行工具。装完验证pi --version正常情况下会打印出版本号。如果提示command not found大概率是 pipx 的 PATH 没配置好执行pipx ensurepath然后重启终端就行。我第一次安装时在这里卡了一段时间装完输入pi提示找不到。后来发现是我在 Git Bash 里 pipx 的安装路径和一些环境变量没对上在 Windows 的设置里手动把%USERPROFILE%\.local\bin加到了 PATH 才解决。如果你也遇到类似情况检查一下你用户目录下的.local/bin是否存在并且是否在系统 PATH 里。安装过程中还可能碰到一个报错因为编译某个原生依赖缺少构建工具。Windows 上解决办法是安装 Visual Studio Build ToolsmacOS 上则是确保xcode-select --install已经执行。这类报错信息一般会直接提示缺什么照着装就行不用慌。3.3 安装后的目录结构知道自己的文件都在哪装完后我建议你先花两分钟了解 Pi Agent 在本地生成了哪些关键目录。这不是好奇心驱动的探索而是后续配置 Skill、调试异常时必须知道的事。Pi Agent 默认会在你的用户主目录下创建一个.pi文件夹macOS / Linux或%USERPROFILE%\.piWindows。里面的关键文件包括路径用途~/.pi/config.toml核心配置文件模型、API Key、行为参数都在这里~/.pi/skills/Skill 目录存放各种扩展技能后面细说~/.pi/logs/运行日志出问题时排查的第一站一开始我根本不知道有日志这回事遇到问题就只能靠猜。直到有一次它执行完一个任务后生成了一个错误的文件我打开日志才发现它在一个中间步骤里把路径拼接错了。从那以后遇到任何异常我先翻日志效率高很多。3.4 验证安装写个最简配置跑通一次安装完成后别急着配置模型先用最简配置验证整个链路是通的。在终端里执行pi这会进入交互模式。你随便输入一句指令比如告诉我当前工作目录下有哪些文件并简要说明每个文件的作用。这时候它可能会提示你还没有配置 API Key或者模型配置不完整。没关系这个提示本身就是验证——说明 Pi Agent 已经成功运行只是在等配置。接下来就是重头戏配置文件。4. 配置文件详解模型、API Key、代理源与常见参数4.1 配置文件长什么样Pi Agent 的配置文件会在首次运行时自动生成位置是~/.pi/config.toml。你可以直接用任何文本编辑器打开也可以用命令打开pi config edit这个命令会调用系统默认编辑器打开配置文件省得你自己找路径。一份最基础的配置文件长这样[model] provider openai name gpt-4o api_key sk-xxxxxxxxxxxxxxxx [agent] max_iterations 25 auto_run false [exec] timeout 120 allow_bash true [log] level info看到这你可能觉得太简单了实际上核心就这几项。但每一项后面的决策逻辑很有讲究我分别说一下。4.2 模型配置provider、name、api_key 的选择逻辑provider字段支持openai、anthropic、local等。我主力用的是openai因为 Pi Agent 的默认工具调用协议跟 OpenAI 兼容性最好。如果你用的是 Azure OpenAI 或者国内云厂商的 OpenAI 兼容接口通常也填openai然后在api_key和接口地址上做调整。name字段填模型名称。注意这个模型必须支持 Function Calling 或者 Tool Calling 能力。如果选了不支持工具调用的模型Agent 在执行多步任务时会出现严重行为异常——不是不能回答而是不会用工具它会硬猜命令的执行结果而不是真正去执行命令。这个我在本地模型上踩过一次所以特别强调。api_key直接用你的 API Key。这里有个安全提醒如果你是 mac 或 Linux 用户建议装完后执行chmod 600 ~/.pi/config.toml把这个文件的权限收紧避免其他用户读到你的密钥。Windows 用户则尽量不要把这个目录分享到网盘或云端同步。4.3 max_iterations一个防止跑飞的关键参数max_iterations控制 Agent 在执行一个任务时最多迭代多少轮。每一轮它可能会读一个文件、改一段代码、跑一条命令、查看输出然后决定下一步。默认值是 25我建议新手保持这个值。因为如果你的任务描述不够清晰Agent 可能会陷入一种原地转圈的状态——反复修改同一个文件、跑同一条命令看起来在忙实际没有任何进展。这时max_iterations就是硬止损。实测下来绝大多数中等复杂度的任务比如给现有模块增加一个导出 CSV 的功能10 到 15 轮以内就能完成。如果超过 20 轮还没结束大概率是任务没描述清楚或者模型对项目上下文理解偏了。这时候别硬等直接 CtrlC 打断重新描述任务。4.4 auto_run 与 allow_bash安全边界怎么划auto_run控制 Agent 是否自动执行命令。设成false时Agent 每执行一条命令前都会先征求你的同意并且把命令内容展示给你设成true则会自动执行所有命令。我的建议很明确刚开始用的时候设成false。因为你还没建立对工具的信任感让它在你的项目目录里自动跑命令一旦有一条命令写错了比如误删文件、覆盖配置后悔药都没得吃。等你对它的行为模式熟悉了再改成true提升效率。allow_bash决定是否允许 Agent 通过 Bash 执行命令。如果你想让它自动运行测试、执行构建脚本这个必须为true。如果设成falseAgent 就真的只能改代码文件所有需要执行命令的动作都会被跳过能力大打折扣。这里我强烈建议把timeout设成一个合理值。默认 120 秒应该够了因为 Pi Agent 跑的任务一般不是长时任务。如果你让它跑测试而测试本身需要几分钟那timeout就要相应调大否则测试还没跑完就被中断了。4.5 日志级别与问题排查的配合方式log.level建议在遇到问题时临时改成debug。info级别只会记录 Agent 做了哪些主要动作debug级别则会记录每一步的详细输入输出包括模型返回的原始 JSON、命令执行的完整输出等。排查问题的思路一般是这样先看终端里 Agent 的最后一步输出判断是卡在哪类操作上。打开~/.pi/logs/下最新的日志文件搜索ERROR或WARNING关键词。如果错误信息不够明确把log.level改成debug复现一次问题再看完整日志。这套排查链路我用了很多次基本能覆盖 90% 的异常情况。剩下 10% 要么是模型 API 服务本身的问题要么是系统环境问题那就需要去社区搜一下了。4.6 代理源配置的注意事项这里说的代理源不是网络代理而是包下载源。如果你所在网络环境访问默认源速度很慢或者超时需要把相关工具pip、npm、git的源切换到更快的镜像。但要注意Pi Agent 本身的模型 API 调用地址是独立的跟包管理器源没有关系。如果你的模型 API 请求很慢那是另外一回事需要检查你的 API 服务商和网络链路不能在配置文件里靠换个源来解决。我当时的做法是pip 和 npm 全部切换到国内镜像源Git 拉取 Pi Agent 的 Skill 仓库时通过环境变量设置代理如有需要。这样安装流程基本顺畅但模型 API 调用走的是官方地址稳定性和速度都比较可靠。5. 核心玩法Agent Skill 的安装与自定义扩展5.1 什么是 Agent Skill为什么要用Pi Agent 最吸引我的地方是它的Skill 机制。简单说Skill 就是给 Agent 预装的一套专业技能包让它不用每次重新摸索就知道怎么处理某一类问题。举个例子你用 Pi Agent 做前端开发如果没有对应 Skill它可能不知道应该用 ESLint 的哪些规则来检查代码也不知道package.json里的 scripts 应该优先跑哪个。但装了一个标准前端工作流的 Skill 之后它面对前端项目时就会自动遵循一套最佳实践行为明显专业很多。这就像你雇了一个全能实习生刚开始他什么都要问但你给他一本工作手册之后他就会按手册里的流程干活了。Skill 就是那本工作手册。5.2 安装官方技能包一行命令搞定安装 Skill 的方式很直接。在项目目录下执行pi skill install python-backend把python-backend换成你想要的其他技能名称就行。我常用的几个Skill 名称适用场景python-backendPython 后端项目包含测试、依赖管理、代码规范frontend-standard前端项目包含构建、格式化和常见框架约定git-workflowGit 操作规范比如提交信息格式、分支命名general-refactor通用代码重构适合帮我优化这段代码类任务安装后Skill 会放在~/.pi/skills/目录下。你可以在项目根目录创建一个.pi或.piactor目录具体名称以你安装的版本提示为准在里面用 YAML 文件声明启用哪些 Skill。这个声明文件的格式非常简单skills: - python-backend - git-workflow之后 Pi Agent 在这个项目下运行时会自动加载这些 Skill 的规则。5.3 手写一个自定义 Skill从需求到落地的过程官方 Skill 覆盖的是通用场景但你真正用起来后一定会想加一些属于你自己工作流的内容。比如我经常处理数据清洗就写了一个专门的数据处理 Skill让 Pi Agent 遵循我的固定流程先探查数据、再写清洗脚本、最后输出质量报告。自定义 Skill 的结构很简单本质上就是一组指令文件~/.pi/skills/my-data-pipeline/ SKILL.md rules/ code-style.mdSKILL.md是核心文件写清楚这个 Skill 的用途和整体流程。格式类似# My Data Pipeline Skill ## 适用场景 处理 CSV / Excel 数据清洗和转换任务。 ## 工作流程 1. 先用 Python 读取数据检查缺失值和类型。 2. 向用户报告数据质量确认清洗策略。 3. 编写清洗脚本输出清洗后的文件和质量报告。 ## 规则 - 清洗脚本必须保存到项目下的 scripts/ 目录。 - 处理前备份原始文件。写完后你不需要重启任何服务新 Skill 会在下一轮任务中自动生效。我给 Pi Agent 加了好几个这类自定义 Skill 后它的表现确实有质的提升——不再是什么都会一点但什么都不精而是非常贴合我自己的项目习惯。5.4 为什么 Skill 能显著提升 Agent 表现技术原理其实不复杂。Skill 本质上是在你给 Agent 的任务描述之外额外附加了一层系统级上下文。每次 Agent 接收到任务时它会先加载当前项目启用的 Skill 文件内容把里面的工作流程、规则约束当作默认行为准则。这意味着它不会每次从零开始摸索怎么干活而是直接按照你沉淀下来的方法执行。对编程代理来说上下文就是一切。多给一份高质量的指南效果提升比换更强的模型还明显。我甚至见过一个现象同一个模型装上合适 Skill 之后干活的成功率明显提升而且行为更可预测。5.5 社区扩展资源找到别人沉淀好的技能包除了自己写你也可以从社区找现成的 Skill。有些项目会在自己的仓库里附带.piSkill 定义直接拉下来引用就行。你可以在 GitHub 上搜索pi agent skills或者去对应项目的文档站看有没有插件市场。我个人的习惯是先装官方的再用社区的最后把高频重复的需求自己固化成一个新 Skill。这三个层次配合下来Pi Agent 会越来越懂你。6. 实战演练用 Pi Agent 在一个旧项目里完成重构6.1 任务描述的策略别让它猜给它边界工具再好任务描述不清照样白搭。我拿一个真实的例子来说明。我的一个旧 Python 项目里有个模块负责读取配置文件但这个模块的异常处理非常乱很多地方直接pass吞掉了错误。我想让 Pi Agent 帮我重构这块。我的原始描述是帮我看看 config_loader.py 这个文件重构一下异常处理。这个描述太模糊了。它不知道该不该保留现有的返回结构也不知道重构到什么程度算够好。实际结果就是它改了一版改了等于没改——只是把pass换成了print。后来我重新组织了描述效果完全不一样重构 config_loader.py 的异常处理逻辑目标所有外部依赖调用文件读取、环境变量、JSON 解析都能捕获具体异常并向上抛出带上下文信息的自定义异常保留现有函数签名和返回结构不改变外部调用方代码补充错误信息中包含配置项名称处理完后运行 tests/test_config_loader.py 验证。看看这中间的差别清晰的边界、具体的验收标准、验证方式。模型不是不想干活而是如果你不给它定义干得好的标准它就只能按自己的理解胡乱发挥。6.2 执行过程的观察怎么判断它是在干活还是在瞎转任务执行时Pi Agent 会在终端里打印出当前的步骤和动作。你要学会判断它是正常推进还是原地打转。正常的推进迹象读文件后会明确指出哪个函数存在什么问题然后提出修改计划。每轮迭代之间有关联比如先确认入口函数再逐层往下查调用链。命令执行失败后会先读错误输出再决定修改哪一行代码。危险的瞎转迹象反复打开同一个文件但每次只做很小的改动甚至改完又改回去。执行了和任务无关的命令比如突然跑了个 Git 操作。不读错误输出直接凭猜测改代码改完再跑错了再乱改。遇到瞎转苗头我的处理方法是先让它停下来然后用pi交互模式下追问它你当前的理解是什么下一步计划是什么。有时候它只是对任务理解有偏差通过对话校准一下就能继续。如果连续两轮都在绕圈就直接 CtrlC 终止重新描述任务或者简化任务范围。6.3 重构完成后的验证三板斧任务跑完千万别直接信任输出结果。Agent 说完成不等于真的完成你还是要按自己的标准验收。我自己的验收流程是固定的人工看代码打开被修改的文件看代码风格是否符合项目惯例逻辑是否符合预期。Pi Agent 的代码生成能力虽然强但它不会自动遵循你项目里那些不成文的约定比如某些地方必须用单引号、某些函数要加注释。跑测试让 Pi Agent 执行pytest或项目自己的测试命令看是否全绿。跑一次边缘场景如果你是让它改配置解析逻辑就构造一个真实但不常见的配置输入看看它能不能正确处理。上文中那个 config_loader 重构的例子最后一次我验收时发现一个问题它在自定义异常的信息里把配置项名称拼错了导致错误信息指向了不存在的配置键。这种细节不是逻辑测试能查出来的必须人工看一遍代码。所以我的态度是Pi Agent 是提效工具不是甩手掌柜。它可以帮你分担大量重复劳动但最终质量责任还是你自己的。6.4 多轮对话与中途介入让它按你的节奏走Pi Agent 的交互模式支持在任务执行过程中随时打断和重新引导。这一点非常实用。我之前有个任务它突然决定要重构一个我没让它碰的辅助模块。我直接在终端里输入等一下不要动 utils.py 里的内容只需要处理 config_loader.py。它在下一次迭代中就纠正了方向继续往正确方向推进。这种介入-校准-继续的循环大概来两三次任务的质量就能拉到一个很可控的水平。这也是我为什么推荐新手先把auto_run设成false的原因——强制每步确认的情况下你天然就有介入的机会不容易失控。等你习惯了它的行为模式再尝试true也不迟。7. 常见问题排查我踩过的五个坑与对应解法7.1 安装后命令找不到这是最基础也是遇到最多的坑。核心原因就两个字PATH。排查步骤pipx list # 查看是否安装成功如果列表里能看到pi-agent说明安装成功只是 PATH 没生效。Windows 用户检查%USERPROFILE%\.local\bin是否在系统 PATH 中macOS / Linux 用户检查~/.local/bin是否在 PATH 中。确认后重启终端再试。7.2 模型响应慢或超时如果你已经正确配置了 API Key 和模型名称但每次响应都慢得离谱大概率是 API 网络链路的问题。排查思路直接用 curl 测试 API 接口的响应延迟排除 Pi Agent 本身的问题。在配置文件中临时把log.level改成debug观察是模型 API 调用慢还是命令执行慢。如果是命令执行慢检查timeout参数是否太小酌情调大。注意这不是配置文件里的代理源能解决的问题。模型 API 走的是独立的网络链路你需要从自己的网络环境和 API 服务商角度优化。7.3 Agent 频繁改错文件频次触发这个问题的场景是项目结构比较大多个模块之间的依赖关系复杂。Agent 读了一部分文件后对整体结构的理解产生了偏差于是去改不相关的文件。解法其实不在参数配置而在任务描述的精细化。把任务范围圈定得越小Agent 跑偏的概率就越低。比如不要说优化这个项目的性能要说优化src/data_processor.py中process_batch函数的时间复杂度。不要说帮我检查代码质量要说检查models/目录下所有文件是否遵循 PEP 8 规范并修正违规项。如果项目本身确实很大还有一个技巧先让它输出项目结构树确认它理解对了再让它动手。7.4 日志文件中出现权限或网络错误这类错误通常跟环境相关不是 Pi Agent 代码问题。常见的有尝试从 Git 拉取资源时网络超时或证书错误需要处理你的 Git 网络环境。尝试在某些目录写入文件时权限不足检查目录权限。日志里一般会写明具体操作和错误原因。按提示解决就行不要盲目重装。7.5 多个版本 Python 并存时的依赖错乱机器上装了 Anaconda、系统 Python、Python 3.12 等多个版本时pipx 可能会选错解释器。解决办法用虚拟环境隔离或者显式指定 Python 版本安装。pipx install --python python3.11 pi-agent安装时指定 Python 版本避免依赖错乱。这个坑很隐蔽因为报错信息可能五花八门一会儿是某个包编译失败一会儿是缺某个模块。如果你有多个 Python 环境且安装报错优先怀疑这个原因。8. 和 codex、opencode 的横向对比什么场景选什么既然 Pi Agent 经常和 codex、opencode 出现在同一个讨论里我也分享一些自己的使用体感。先说结论这三者不是简单的优劣关系而是定位不同。工具定位最适场景上手成本Pi Agent极简终端编程代理个人项目、快速原型、脚本编写低codex综合编程平台大型项目、团队协作、复杂工作流高opencode高度可配置的开放框架喜欢自定义所有细节的技术玩家高我个人的使用建议如果你每次的任务都比较具体、范围可控改个函数、写个脚本、查个 bugPi Agent 最顺手。它启动快、配置简单、介入方便。如果你需要和团队共享上下文或者要处理跨多个仓库的复杂任务codex 这类完整平台更合适。如果你就是喜欢折腾配置、想要完全掌控 Agent 行为的每个细节opencode 会让你玩得很开心。对我来说Pi Agent 像一个贴身助理codex 像一个项目经理opencode 像一套没有说明书的乐高。大部分时候我需要的是贴身助理所以我的主力是 Pi Agent偶尔需要处理大型重构时我才会切到 codex。9. 最后再分享两个实用小技巧根据我个人这段时间的使用经验有两个细节对体验提升很大但大多数教程不会提。第一个是在项目根目录放一个项目说明文件。我用的是AGENTS.md内容是项目的整体架构、关键模块的作用、常用命令的说明。Pi Agent 在运行时能自动识别这类文件并作为上下文参考。有了这个文件它的行为明显更贴合项目实际情况尤其是在处理你不常打交道的旧项目时这个文件的价值会被无限放大。第二个是日志习惯。Pi Agent 的日志目录默认保留最近几次运行记录。如果你发现某次任务表现特别好可以把那次日志单独存一份对比一下和表现差的任务之间差异在哪里。我经常能从这种对比中发现自己任务描述里的问题很值得坚持。Pi Agent 是一个值得花时间打磨的工具。初期你不要指望它一次就能完美完成复杂任务就像你不能指望一个新人第一天上班就独当一面。但只要你花半小时把配置弄好、给它准备几份好用的 Skill、学会精准描述任务它很快就能成为你终端工作流里最顺手的那块拼图。