原创编号：DMZ-PI-001｜作者：大拇指
很多人第一次接触 Pi Agent，最想知道的并不是它有多少命令，而是：我把一个真实需求交给它，它能不能自己阅读资料、编写代码、运行检查，最后把结果交给我验收？
这次我用一个“本地家庭记账分析器”做完整演示。整个项目从需求说明开始，使用原生 HTML、CSS 和 JavaScript 实现，再通过实际运行与浏览器检查完成验收。视频保留了关键过程，没有把它剪成只展示成功结果的宣传片。
播放器字幕可以自由打开或关闭。如果浏览器没有自动显示字幕，请在播放器的字幕菜单中选择“中文”。
一、这次要完成什么
项目目标是制作一个完全在本地浏览器运行的家庭收支分析网页。它需要能够读取 CSV 账单，并提供以下功能：
- 统计总收入、总支出、结余和预算使用率；
- 按消费类别汇总支出；
- 显示每日支出趋势和金额较大的消费；
- 支持月度预算、明细搜索和收支筛选；
- 提供清晰的空状态及错误提示；
- 同时适配电脑和手机屏幕；
- 所有账单只在浏览器本地处理，不上传服务器。
演示使用的是专门生成的虚构账单，共 60 条记录。示例数据的收入为 9786.20，支出为 4386.00，结余为 5400.20。这些数字也用于最后的程序验收。
二、Pi Agent是什么
Pi Agent 是一个运行在终端中的编码 Agent。它不只是回答代码问题，还可以在获得许可后读取项目文件、创建和修改代码、执行命令、检查错误，并调用浏览器或其他工具完成验证。
需要说明的是，Pi Agent 是官方项目。本视频中的 Windows 便携环境整合、启动脚本、迁移方案和中文指南由大拇指整理制作。
三、Windows安装与启动
已经安装当前版本 Node.js 的电脑，可以按照 Pi Agent 当前文档使用 npm 安装：
npm install -g @mariozechner/pi-coding-agent
pi
第一次启动后，根据终端提示配置所使用的模型。不同版本的命令和模型配置可能变化，实际操作时应以当前版本帮助和官方文档为准。
如果希望把 Node.js、Git、Skills、插件、配置和项目集中在一个可迁移目录，可以继续阅读：
Windows Pi Agent 真正便携版：安装、迁移、Skills 与插件完整指南
四、先用文件把需求说清楚
这次没有直接输入一句“帮我做个记账网页”，而是先在项目中准备了 README.md、AGENTS.md 和示例 CSV。
README.md
README.md 说明项目本身：它要解决什么问题、有哪些功能、怎么运行，以及最终需要达到什么标准。它既能给 Pi 阅读，也能给以后接手项目的人阅读。
AGENTS.md
AGENTS.md 更像是给编码 Agent 的工作规则，例如：
- 优先读取哪些文件；
- 允许使用哪些技术；
- 修改后必须运行哪些检查；
- 不得读取或展示项目目录之外的个人信息；
- 账单数据必须留在本地。
需求越具体，Agent 越容易给出可检查的结果。更重要的是，明确的验收标准能让我们判断它到底完成了没有。
五、把完整任务交给Pi
演示中使用的核心提示词不是逐步遥控，而是一次交代目标和边界：
请先阅读 README.md、AGENTS.md 和 data/sample-expenses.csv，
然后完成这个本地家庭记账分析器。
先用几句话说明实现思路，随后直接完成开发、检查和隔离浏览器验收，
不需要等待我逐步确认。
请保持过程清晰，避免展示任何项目目录之外的个人信息。
Pi 随后读取项目说明与示例数据，规划文件结构，创建 HTML、CSS 和 JavaScript，并运行语法与数据检查。
六、不要跳过错误和修正过程
实际开发中，第一次检查并不一定成功。演示里就出现了系统找不到 python 的情况。重要的不是“永远不报错”，而是 Agent 能否识别环境差异、换用可用的方法继续检查，并把结果验证清楚。
这也是我保留真实过程的原因：使用 Agent 并不等于不需要判断。我们仍然要看它读取了什么、修改了什么、运行了什么，以及最终结果是否符合原始要求。
七、在隔离浏览器中验收
代码检查通过后，Pi 启动本地静态服务，并在隔离浏览器中打开网页。验收重点包括：
- 示例 CSV 能否正确载入；
- 收入、支出和结余是否与已知数据一致；
- 图表、分类统计和消费明细是否可读；
- 预算修改、搜索和筛选能否正常工作；
- 错误格式是否会导致页面崩溃；
- 窄屏状态下是否仍然可用。
最终页面成功完成汇总卡片、分类占比、每日趋势、最大消费、预算设置和明细筛选。账单解析和统计均在当前浏览器中完成，程序不需要数据库或远程接口。
八、使用Pi Agent时要注意什么
- 先限定目录：只让 Agent 处理当前项目所需文件。
- 敏感信息不要进入演示：API Key、Cookie、SSH 私钥、真实账单和个人路径都不应公开。
- 重要项目先使用 Git：修改前建立提交点，便于查看差异和回退。
- 命令执行仍需判断：特别是删除、部署、付费服务和生产服务器操作。
- 必须实际验收：“代码已生成”不等于“项目已经完成”。
九、总结
这次实战展示的不是某一段神奇提示词，而是一条可以重复使用的工作流：
明确目标 → 准备上下文 → 设定边界 → 让 Pi 实现 → 运行检查 → 浏览器验收
当需求、限制和验收标准足够清楚时，Pi Agent 可以把大量重复的开发和检查工作串联起来。使用者需要做的，是给它正确的上下文、控制权限边界，并对最终结果负责。
原创制作：大拇指部落格
原创编号：DMZ-PI-001
damuzhiblog.com
声明：本文与配套视频为大拇指部落格原创教程。引用或转载时请保留作者、原文链接和原创编号。Pi Agent 项目及其名称归相应项目方所有。
