大道至简的AI编程助手：Pi Agent 安装配置与实战完全指南

Pi的核心优势：极简设计带来极致效率

在众多AI Coding Agent中，Pi以其简洁的设计脱颖而出。整个Agent仅依赖四个基础工具，系统提示词控制在1000 Token以内。这种极简主义带来的效果是显著的：一个简单的问候指令，Pi仅需1100 Token即可完成上传，仅占用上下文窗口的0.4%。相比之下，Codex处理同样的指令就需要消耗18000 Token，尚未执行任何实质任务便占用了7%的上下文窗口。

效率提升的数据来自Composio上月发布的基准测试：Pi Agent完成编程任务的速度比同类Coding Agent快1.5至2倍，综合成本也显著低于主流框架。

在代码质量层面，Databricks在其百万行代码仓库中进行的测试更具说服力。以任务成本为横轴、任务通过率为纵轴的测试结果显示，红色曲线标注的"同等成本下最优Agent+模型组合"中，Pi在多数场景下表现优于Claude Code和Codex。整张测试图的质量最高点出现在Pi+Claude Opus 4.8的组合上。

本文将系统讲解Pi Agent的完整使用方法，涵盖以下内容：

• 安装配置（Windows/Mac）
• 模型接入
• 基础操作

---

一、Pi的安装配置

Windows系统

使用一台全新的Windows电脑进行演示。安装前无需任何准备工作。

1. 在桌面右键，选择"终端打开"，启动Windows PowerShell控制台
2. 访问Pi官网，复制PowerShell一键安装命令：

powershell -c "irm https://pi.dev/install.ps1 | iex"

1. 粘贴至控制台并回车执行

安装过程中可能需要两次确认：

• 输入y回车，安装Node.js运行环境
• 再次输入y回车，安装Pi本体
• 若系统未安装Git，建议输入w让Pi自动完成Windows端的Git配置

安装完成后，关闭当前命令行窗口，重新右键打开终端，输入pi启动。若成功显示对话窗口，说明安装完成。

Mac系统

在Mac上安装更为简洁：

1. 打开终端
2. 访问Pi官网，复制curl安装命令：

curl -fsSL https://pi.dev/install.sh | sh

1. 粘贴执行即可完成安装

---

二、配置模型

启动Pi后，在界面输入命令/login进入模型配置。Pi支持两种接入方式：API Key和模型订阅。

方式一：API Key接入

以DeepSeek为例说明：

1. 在Pi中输入/login，选择API Key方式
2. 输入关键词DeepSeek筛选并回车
3. 访问DeepSeek官网的API开放平台，确保账户有可用额度
4. 点击"API Keys" → "创建API Key"，填写名称后生成
5. 复制生成的API Key，粘贴至Pi并回车确认

配置完成后发送测试消息验证连通性。默认模型为DeepSeek V4 Pro，可输入命令/model切换至其他模型（如DeepSeek V4 Flash）。

快捷操作：

• Shift+Tab：切换模型的思考强度
• Ctrl+L（Mac同）：快速打开模型选择器

方式二：模型订阅接入

以OpenAI订阅为例：

1. 输入/login，选择"Sign in with account"
2. 选择OpenAI Codex，点击"浏览器登录"
3. 浏览器打开登录窗口，完成OpenAI账户认证
4. 返回Pi界面，按Ctrl+L打开模型列表，ChatGPT模型已自动出现

---

三、基础操作

项目初始化

创建项目文件夹后，在文件夹内右键选择"在终端打开"，输入pi启动。Pi窗口将显示当前工作目录，后续所有代码文件都将写入该目录。

编写代码

以"使用React框架制作宠物洗护店网页"为例演示：

多行输入：

• 不要按回车直接发送，应使用Shift+回车换行
• 或按Ctrl+G打开记事本，在记事本中编辑提示词更便捷，保存后内容自动同步至对话窗口

输入三行提示词后回车执行，Pi将完成代码编写。

---

下期预告

Pi窗口底部显示的运行信息，以及Pi的进阶功能，将在后续章节继续讲解。

会话管理：输入输出与上下文

Pi界面顶部的上下箭头直观展示了Token的消耗情况。上箭头代表当前Session的全部输入Token总量。Session指的是一段完整的对话上下文，记录了AI多轮交互的整个工作轨迹。使用/new命令可以开启全新的Session，此时历史对话被清空，上下文窗口恢复初始状态。下箭头则显示本轮对话的输出Token数量，本例中总计输出11000 Token。

界面上还提供几项关键指标：

• R（Cache Read）：Session内命中缓存的Token数量
• CH（Cache Hit Rate）：最近一次请求的缓存命中率，而非整个Session的统计值
• 预估成本：括号内的"sub"表示subscription，即当前费用按订阅方案计算，供参考
• 上下文占用：4.6%表示已使用模型上下文窗口的比例，斜杠后为总量（GPT 5.6为272k）
• auto：自动上下文压缩开关，当使用量达到阈值时自动触发

底部显示模型提供商、当前模型名称及思考强度配置。

命令执行：叹号临时运行

代码编写完成后，可以直接在该窗口内启动开发服务器。输入英文感叹号后跟命令即可：

!npm run dev

回车后，开发服务器随即启动。这种!前缀的用法允许在对话流中临时执行命令，AI能够观察命令的运行过程与输出结果。

如需隐藏命令不让AI看到，可改用双叹号：

!!npm run dev

反馈方式：截图与文件引用

开发过程中若需调整界面，可直接截图反馈。Windows用户按Alt+V、Mac用户按Control+V粘贴图片，然后描述修改需求。Pi能够解析图片内容并完成相应调整。

除了截图，还可通过@符号直接引用代码文件。输入@后选择文件路径，再配合/快速定位具体文件。这种方式尤其适合代码结构调整类的需求——例如要求AI将单文件代码拆分为模块化结构。

指令追加：Steering与Follow-up

当AI选用的技术方案与预期不符时，不必中断其执行流程。直接追加指令即可引导AI调整方向。

Steering（引导）

输入补充说明（如"使用Next.js框架，数据库用SQLite"）后回车，这条指令会显示"Steering"标记。Steering意为掌控方向，在AI执行过程中进行干预，使其立即转向新的技术路线。发送后AI会立刻停止当前工作，开始安装Next.js相关依赖。

Follow-up（排队）

与Steering不同，Follow-up不会中断AI当前任务，而是等待其完成整轮工作后才处理新指令。Windows用户需先调整PowerShell快捷键配置：右键打开设置，在操作中找到Alt+回车（全屏化快捷键）并删除该绑定（与Pi默认快捷键冲突），保存后返回Pi界面。输入指令后，使用Alt+回车（Mac为Option+回车）发送，指令前会显示"Follow-up"标记进入排队状态。排队中的指令可按Alt+上箭头重新编辑修改后再次提交。

当AI完成手头工作后，才会读取并执行排队中的指令。整个流程体现了Pi Agent的双层循环机制：

• 内层循环：调用大模型 → 根据指令调用工具 → 将工具结果反馈给模型 → 模型判断是否完成 → 未完成则进入下一轮
• 巧妙设计：进入下一轮循环时，Pi自动将Steering消息注入上下文，使引导指令生效

会话管理与对话树

消息处理的循环机制

Pi 对消息的处理分为两个层级：内层循环负责即时响应用户指令，外层循环则管理 Follow-up 消息的排队。当用户在 Pi 常规运行时发送新指令，这些指令会进入外层队列，等待当前任务完成后才会被读取和处理。

非交互模式

除了实时交互，Pi 还支持一次性非交互模式，适合将 Agent 作为临时 CLI 工具使用：

pi -p "你的指令"

执行时 Pi 在后台静默运行，完成后直接输出结果。以“查询天气并写入桌面文件”为例：

pi -p "查询今天天气，在桌面创建weather.txt文件"

该模式适合自动化脚本、定时任务等不需要持续对话的场景。

Session：会话管理的核心单元

Pi 的会话管理以 Session 为基本单位。每次对话的历史记录构成一个独立的 Session。

创建新会话：输入 /new 即可开启全新的 Session，两次会话互不干扰。

恢复历史会话：关闭窗口后，可通过以下命令恢复：

命令	用途
pi -c	继续最近一次 Session
pi -r	手动选择要恢复的 Session

对话树：Pi 的特色功能

与传统线性对话不同，Pi 的每个 Session 可以呈现树状结构，支持分支探索和时间线回溯。

进入对话树视图：

/tree

操作流程示例：假设在“蔬菜列表”会话中新增了茄子、芹菜、白菜后，发现方向有误，想改为添加海鲜而非继续添加蔬菜。

1. 在白菜节点选择“新建分支”
2. 在新分支执行：添加海鲜（皮皮虾）
3. 再次输入 /tree 查看结构

此时的对话树呈现两条并行时间线：

 茄子
 /
 芹菜——
 / \
蔬菜列表 白菜（继续蔬菜）
 \
 新分支：皮皮虾（海鲜）

重要限制：使用对话树回退时，仅回退对话历史，已写入的代码不会同步回滚。

配合 Git 实现完整回退

若需同时回退对话记录和代码文件，必须借助 Git。

操作步骤：

1. 使用 /tree 将对话回退到目标节点（如“新增茄子”）
2. 在代码编辑器中找到对应提交的 commit ID
3. 执行 Git 命令强制回退：

git reset --hard 

回退后，代码与对话历史均恢复到此前的状态。

回退时的三种选项：

选项	行为
不总结	直接丢弃后续对话历史
总结	AI 对被丢弃分支的工作进行概述
自定义总结	指定 AI 总结的方式和侧重点

注意事项：总结仅作用于被回退的分支，其他分支（如“皮皮虾”分支）的历史不会被纳入总结范围。

Session 克隆

克隆功能可将当前 Session 完整复制为新 Session，适合需要基于同一上下文进行多方向探索时使用。

操作：在目标 Session 中输入 /clone，即可生成完全相同的副本。

例如在“蔬菜列表”Session 中执行克隆后，通过 pi -r 查看，列表中会显示两份独立的蔬菜 Session，各自拥有完整的历史记录。

工具设计与插件扩展

对话节点与上下文管理

/fork 命令允许基于特定对话节点创建独立的新 Session，而非克隆整棵对话树。以水果分类场景为例，选择"香蕉"节点执行 fork，即可生成一个仅包含此前对话历史的新会话环境。该命令非常适合在需要探索不同解决路径时保留原始会话的同时开启并行分支。

/compact 命令用于手动触发上下文压缩。当对话历史占用的上下文空间超过阈值时，Pi 会自动对历史进行总结精简。压缩操作能有效降低 Token 消耗并提升 AI 后续响应的专注度——从测试数据看，18% 的上下文占用压缩后降至 10% 左右。

不过在 Agent 实践中存在一条通用经验：清空优于压缩。对话历史越长、轮次越多，对 AI 注意力分散的影响就越明显。因此在完成一轮任务后，最佳做法是直接输入 /new 创建全新 Session，让模型从零开始处理下一个任务，从而获得最佳的执行效果。

极简的工具哲学

Pi 默认仅提供四个核心工具：读文件（Read）、写文件（Write）、改文件（Edit）、执行命令（Bash）。这种设计遵循"最小工具集覆盖绝大多数编程场景"的理念。其中 Bash 工具本身具备极高的扩展性——通过它可以调用 find 搜索文件、grep 检索代码、ls 调查目录结构，几乎无所不能。

除四个核心工具外，Pi 的扩展能力通过 Agent Skill 实现。官网首页的那句话清晰地阐释了它的设计哲学：

让工具来适应你的工作流，而不是让你去适应工具。

这意味着 Pi 刻意省略了 MCP、SubAgent、Plan Mode、Todo 等常见功能，让核心保持精简，从而为用户提供最大的自由度去按需组装能力。

插件系统使用指南

Pi 的插件安装在官网 Package 页面管理，以下介绍几个核心插件的用法。

联网搜索插件（pi-web-access）

该插件让 Pi 具备联网搜索与网页信息提取能力，采用零配置模式，接入 Exa MCP 服务，无需 API Key，装上即可使用：

pip install pi-web-access

启动 Pi 后，[Extensions] 区域会显示已加载的联网插件。直接提问"青岛天气如何"，Pi 便会调用搜索能力并返回整理后的结果。卸载插件同样简单，只需将 install 替换为 uninstall：

pip uninstall pi-web-access

并行子代理插件（pi-subagents）

pi-subagents 赋予 Pi 同时运行多个子代理的能力，适合需要并行处理多个独立任务或生成多个设计方案的场景。安装方式支持两种粒度：

安装方式	命令	作用范围
全局安装	pip install pi-subagents	所有项目生效
项目级安装	pip install pi-subagents -l	仅当前目录生效

全局安装的插件会增加所有项目的系统提示词负担，对于不需要该插件的项目而言是额外开销。若只需在特定项目中使用，推荐使用项目级安装。插件会被放置在项目目录的 .pi 文件夹中，仅对当前文件夹生效。

以并行生成多风格个人网页为例，执行 /pi-subagents 并要求设计 5 种不同风格的作品，Pi 会启动 5 个 Worker 并行完成开发和审查，最终交付 5 份成品。实际效果测试显示，这一功能在需要快速产出多样方案时非常实用。

MCP 适配插件（pi-mcp-adapter）

Pi 原生不支持 MCP，通过安装该插件可获得完整 MCP 功能。安装命令：

pip install pi-mcp-adapter

MCP Server 的配置文件为项目根目录下的 .mcp.json。以接入高德地图服务为例，需先在高德开放平台申请 Key，填入配置后即可使用：

{
 // 高德地图 MCP 配置
 "key": "你申请的高德地图API Key"
}

配置完成后启动 Pi，即可调用地图查询功能。例如询问"从太平角公园到崂山仰口的公共交通路线"，Pi 会自动调用高德地图 MCP 获取坐标信息和路线规划，输出完整的出行攻略。

旁路对话：让 AI 工作不受干扰

在传统 Claude Code 中，有一个名为 btw（by the way）的实用功能——它允许用户在 AI 执行任务的同时开启旁路对话，随时提问而不中断主流程。Pi 本身并未内置此功能，但通过插件扩展可以轻松实现。

安装步骤十分简单：在 Packages 页面搜索 "btw"，选择更新时间最新、下载量最大的版本，复制安装命令后在控制台执行即可。

启动 Pi 后，当 AI 忙于处理任务时，可输入 /btw 命令开启旁路对话。例如在 AI 调研项目功能的过程中，直接询问 "Nextjs 是什么"，Pi 会打开子窗口进行解答。旁路对话完全独立于主对话，不会干扰正在执行的工作。如需退出子窗口，按 Ctrl+C 即可返回主对话界面。

Plan Mode：任务规划先行

计划模式是另一个高频使用的功能，同样通过安装插件获得。在插件列表中搜索 "plan" 并安装相关插件后，输入 /plan-mode 命令即可启用，此时界面底部会显示 plan 标记。

该模式的核心逻辑是：AI 先输出任务计划而非直接执行，用户审核并调整计划内容，确认无误后再关闭计划模式，AI 才开始正式开发。

以改造数据库为例，输入 "把数据库改造成 Supabase 的数据库"，Pi 会先将计划写入 PLAN.md 文件。用户可在此阶段修改计划内容，确认后输入 Plan Mode 命令关闭该模式，再发出执行指令，Pi 便会按计划推进开发工作。

Goal 模式：多轮迭代达成目标

Goal 模式借鉴自 Codex 和 Claude Code，支持通过 /goal 命令为 AI 设定长期目标，Pi 会在多个轮次中持续朝该目标努力直至完成。

以开发 HTML 坦克大战游戏为例，设定目标为：编写完成后启动试玩，输出测试结论，重做版本，最终效果尽量接近红白机。Pi 启动 Goal 模式后自动开始迭代开发，整个过程共迭代三次即可完成。开发者可在 iterations 面板查看历史迭代记录，确认最终效果。

Dynamic Workflows：大规模任务并行处理

Dynamic Workflows 是 Claude Code 的特色功能，可根据任务复杂度生成 JavaScript 编排脚本，自动调度数十乃至上百个子代理协同工作，实现单次对话内的大规模长时任务执行。通过安装 pi-dynamic-workflows 插件，Pi 也能具备此能力。

使用关键字触发动态工作流后，Pi 会自动分解任务并启动多个子代理并行处理。例如要求调研 2022 至 2026 年 AI 领域具有重大影响力的论文，Pi 同时启动了 10 个 Agents 进行工作。通过 /workflows 命令可查看各子代理的实时状态，如第一个子代理正在检索 2022 年相关论文。整体体验与 Claude Code 基本一致。

即时通信：手机与桌面 Agent 互联

许多桌面 Agent 已支持与手机即时通信功能，Pi 通过插件同样可以实现。安装即时通信插件后，使用 /wechat login 命令并在手机端扫码配对，随后通过 /wechat start 启动连接。

实际使用中，在手机端向 Bot 发送消息，电脑端会同步接收，Pi 自动开启相应任务并返回结果。例如查询济南天气，手机端发起请求后，Pi 在后台处理并将结果推送至手机端。

Skills：扩展 Agent 能力边界

除了插件体系，Skills 是为 Pi 扩展能力的另一重要途径。Pi 遵循标准的 Skills 协议，只需将 Skills 文件放置在项目目录的 .agents/skills/ 文件夹下即可，支持同时配置多个 Skills。

以 Playwright CLI 为例，这是让 AI 获得浏览器自动化能力的重要 Skill。首先执行命令安装 Playwright CLI 工具本体，随后按照标准路径放置 Skills 文件，Pi 便能调用相关能力完成浏览器自动化任务。

Playwright CLI 技能配置

Playwright CLI 工具安装完成后，接下来为 Pi 配置对应的 Skill 组件。

方式一：从源码包复制

项目源码中已包含 /skills/playwright-cli/SKILL.md 文件，可按以下步骤操作：

1. 在 GitHub 下载 Playwright CLI 源码压缩包
2. 解压后在项目根目录新建 .agents 文件夹
3. 将源码中 skills 目录整体复制到 .agents 路径下
4. 最终目录结构为：项目目录/.agents/skills/playwright-cli/SKILL.md

这样 Pi 就能自动识别并加载该技能。启动 Pi 后，在 Skills 列表中即可看到 Playwright CLI 选项。这是一个浏览器自动化技能，能够操控 Chrome 浏览器执行各类任务。

方式二：全局配置

若希望某个技能在所有项目中通用，需将其放置到用户级别的配置目录：

~/.agents/skills/

以 Windows 系统为例，进入 C:\ 目录下的 .agents 文件夹（若不存在则新建），将包含 Skills 的文件夹拖入即可。配置完成后，任意项目启动 Pi 时都能加载该技能。

SkillHub 技能市场

除 GitHub 外，SkillHub 也是检索技能的良好渠道。以 Markdown Converter 技能为例，它可将各类文档转换为 Markdown 格式。

安装方式：

• 下载 zip 压缩包，解压后放入指定目录
• 或直接将提示词发送给 Pi，让其自动完成安装

安装过程中若提示缺少依赖工具（如 uvx），可让 Pi 协助安装。安装完成后，发送 PDF 文件给 Pi，即可自动完成格式转换。

Web UI 界面

对于不习惯命令行的用户，社区已开发多个 Pi Web UI 项目。其中 star 数最高的项目由国内开发者「第四种黑猩猩」发布，目前已达 4,200+ stars。

快速启动

npx @anthropic/mcp-playground

终端执行后会自启动网页界面。

界面布局

区域	功能
左上角	项目切换，支持自定义路径作为工作目录
左下角	文件浏览器、模型配置、技能与插件管理
中部	模型选择器

模型配置： 点击模型按钮进入设置，添加 provider（如 Kimi）。在 Kimi 后台获取 API key 后填入保存，即可在模型选择器中使用。

技能管理： Skills 列表按作用域分为两类：

• Project 技能：仅在当前项目内生效
• Global 技能：所有项目通用

可灵活开启或关闭特定技能，及时禁用不用的技能有助于节省 Token 消耗。

插件管理： 同样区分 Project 和 Global 两种作用域，可在界面中直接控制开关。

添加技能： 点击添加按钮可搜索并安装新技能。例如添加 TTS 技能时，Edge TTS 插件无需配置 API key，完全零成本。

安装方式上，技能可以跟随项目，也可以全局安装。以项目维度为例，装好后直接测试效果：让 Pi 把一段文字转成音频。整个过程无需手动指定技能，它会根据任务场景自动选择合适的工具。这里 Pi 调用了 edge-tts Skill 完成音频生成，进入播放确认效果即可。

在对话面板中，斜线命令用于触发内置功能，@ 符号用来定位文件，也可以直接截图后 Control+V 粘贴到 Web UI。模型推理时的思考深度同样可以在此调整。任务完成后，下方会显示输入输出 Token 数量以及预估费用。掌握前面介绍的 TUI 操作后，Web UI 也能快速上手，没有额外门槛。如果关闭了浏览器但仍需使用 Web UI，执行重新启动命令即可恢复。

跨 Session 记忆

每次开启新对话，AI 面对的都是一个空白上下文——不记得之前做过什么，对整个项目的了解也是从零开始。对于复杂项目而言，每次都要重新交代背景或者让它自己读代码摸索，效率很低。本节介绍如何为 Pi 添加跨 Session 的记忆能力。

AGENTS.md 文件

通用方案是在项目根目录创建 AGENTS.md 文件。这个方法在 Codex、OpenCode 等其他 AI Agent 中同样适用。以水果蔬菜列表项目为例，在目录中新建该文件。

这个文件是 AI 每次对话时的必读指南。创建后，所有与 Pi 的对话都会自动携带它的内容作为上下文，帮助 AI 更快理解项目。

例如，在文件中补充项目背景：

我叫...
擅长的语言...
对前端一窍不通，如果遇到网页问题需要用大白话给我解释。

保存文件后，在终端中向 Pi 提问"我叫什么、擅长什么技术"，可以看到它自动将 AGENTS.md 的内容纳入上下文。

手动编写这个文件比较繁琐，也可以让 Pi 代劳。进入宠物洗护项目目录，让它通读当前文件夹，然后将学习到的项目知识写入 AGENTS.md 文件。

Pi 会扫描整个项目的源码、配置和文档，将关键信息整理到文件中。后续开启新对话时，Pi 自动获取这些知识，更快进入状态。对于复杂项目来说，这个文件是必写的。

全局记忆

将 AGENTS.md 放到项目目录只对当前项目生效。如果需要为 Pi 添加全局提示词，可以采用另一种方式。在 Pi 的全局配置目录下新建 APPEND_SYSTEM.md 文件。

以 Windows 为例，路径是 C:\.pi，Mac 系统则是 ~/.pi 目录。进入 agent 文件夹后，新建该文件即可。这里的 APPEND 表示追加，SYSTEM 表示系统——文件内容会被直接附加到系统提示词中，因此优先级更高、效果更强。

以一条常见的安全约束为例：禁止 Pi 批量删除文件或目录，只能通过明确路径单个删除；如需批量操作，应停止并请求用户手动处理。开启新项目测试时，Pi 会遵循这条全局提示词。

大多数场景下，使用通用的 AGENTS.md 文件已经足够。

安全机制

Pi 的安全机制相当基础。仅在包含插件或 Skill 的陌生目录下启动时，它会询问用户是否信任并加载这些内容——这点在之前安装 Skills 时见过。

一旦 Pi 开始运行，所有限制即告失效：编辑文件、执行命令等操作都是自动完成，不会停下来等待确认。它也没有任何沙箱隔离。这是有意为之的设计选择。Pi 的理念是打造极简 Agent，保持本体简洁高效，让它有足够能力以最快速度完成任务，而不是内置一个看似安全但实际并不完整的沙箱。

如果确实需要更高安全性，可以借助外部方案。

容器化运行

官方推荐使用容器或虚拟机来隔离 Pi。例如前面提到的 WSL——运行在 Windows 上的 Linux 子系统。即使 AI 把环境搞坏，删除虚拟机重建即可，不会影响宿主机。类似方案还包括 Windows Hyper-V、Docker 容器等。

Pi 的极简轻量特性使其成为容器化运行的理想选择：启动快、内存占用低，非常适合用 Docker 或 K8S 进行批量部署。

权限插件

通过安装插件也能提升安全性。比如 pi-permission-system，装好后 Pi 执行敏感操作前会弹出审批窗口，等待用户确认后才会继续——类似 Claude Code 的权限系统。不过这类插件会拖慢开发效率，按需取用即可。

Pi提供了高度开放的接口体系，用户可以对模型配置、工具系统、会话流程乃至界面呈现进行全方位定制。这种灵活的设计为社区开发者提供了广阔的创作空间——前文演示的那些插件，正是基于这些开放接口实现的。

更有趣的是，Pi不仅支持安装插件，还具备自主开发插件的能力。用户无需编写代码，只需描述需求，Pi就能根据内置的插件开发文档自动生成代码。下面通过几个具体案例，展示如何利用这一特性定制专属功能。

自定义天气展示插件

让Pi编写一个插件，完成以下流程：根据IP地址查询地理坐标，再获取当地天气信息，最终将天气数据展示在对话界面上方。Pi会自动读取相关开发文档并生成代码。生成的插件是一个TypeScript文件，存放在项目目录下的 .pi/extensions 文件夹中。执行 /reload 命令重新加载后，天气信息便会显示在对话框顶部。

上述方式创建的插件仅在当前项目内生效。如需在所有项目中启用，可将插件目录复制到Pi的全局配置目录（C:\.pi 或 macOS 的 ~/.pi）下的 agent 文件夹中。此后在任意项目启动Pi时，对应的插件都会自动生效。

文件保护插件

编写一个插件，防止AI访问受保护的 .env 文件。一旦AI尝试读取该文件，插件会立即拦截并提示该文件已受保护。加载插件后，尝试让Pi查看 .env 内容，系统会直接拒绝操作。

危险操作确认插件

为删除命令添加执行前的确认机制。当Pi准备执行 rm 删除操作时，先弹出对话框询问用户是否允许执行。同样先加载插件，然后在项目目录放置一个测试文件进行验证。点击"No"则取消操作，文件保留；点击"Yes"则执行删除。该插件同样仅用GPT 5.6 SOL调试通过。

上述三个插件的开发过程表明，使用Pi自带的代码生成能力定制功能并不复杂，只需准确描述需求即可快速完成。

源代码架构与 SDK 集成

Pi在GitHub上的仓库中，核心代码集中在 packages 目录，主要包含四个包：

包名	职责
ai	统一封装数十个模型厂商的调用接口，提供一致的调用规范
agent	实现Pi的核心双层循环机制
coding-agent	具体实现编程功能，包括四个基础工具、系统提示词、Skills机制和插件系统
tui	构建命令行界面的全部交互逻辑

对于从事Agent开发的技术人员而言，Pi的源码是极佳的学习范例。其核心包已被封装为可直接引用的SDK。

接入模型能力

npm install @pi-ai/sdk

通过 createModel 方法，可在项目中接入任意支持的模型并与其对话。

集成编程Agent

npm install @pi-coding-agent/sdk

创建Session后即可直接启动任务，获得开箱即用的Agent能力。

关注最新 AI 动态,访问我的主页 http://my.arthaskj.top