Pi 是 Mario Zechner 发起的开源 Agent Harness。它不是一个大模型,而是一套把大模型、上下文、工具、会话和终端界面组合起来的运行框架。它既提供可以直接使用的编程 Agent,也提供 SDK、RPC、Skills 和 Extensions,适合继续封装成企业内部的 AI 助手。
本文以 2026 年 8 月 1 日的官方版本为基准,从安装和第一次对话开始,逐步讲到项目规则、模型配置、技能、扩展工具、SDK、Java 系统集成、安全控制和效果评估。业务示例统一使用供应链系统中的订单、库存、采购和补货场景。
Pi 已迁移到 earendil-works/pi,npm 包也已改为 @earendil-works/*。旧的 badlogic/pi-mono 和 @mariozechner/* 资料可能仍能搜索到,但新项目应使用当前名称。
一、先理解Pi解决什么问题 一个可执行的 AI Agent 至少需要五部分:
模型:负责理解目标、推理和决定下一步动作。
上下文:告诉模型项目结构、业务术语和工程约束。
工具:让模型读取文件、执行命令或调用业务接口。
Agent 循环:重复执行“模型判断、调用工具、读取结果、继续判断”。
会话:保存消息、工具结果、模型状态和上下文压缩结果。
Pi 把这些能力拆成多个包:
包
职责
@earendil-works/pi-ai
统一不同模型提供商的调用接口
@earendil-works/pi-agent-core
Agent 循环、工具调用和状态管理
@earendil-works/pi-coding-agent
可直接使用的 CLI、SDK、会话和扩展系统
@earendil-works/pi-tui
终端交互界面
因此,Pi 有四种常见用法:
直接运行 pi,把它当作终端编程助手。
运行 pi -p,完成一次性、非交互任务。
运行 pi --mode rpc,通过 JSONL 接入 Java、Python 或桌面应用。
在 Node.js/TypeScript 服务中使用 AgentSession SDK。
二、安装Pi并完成第一次运行 1. 检查Node.js版本 当前 pi-coding-agent 要求 Node.js >=22.19.0:
1 2 node --version npm --version
如果版本过低,先通过 Node.js 官方安装包、nvm 或 fnm 升级。
2. 全局安装 1 2 npm install -g --ignore-scripts @earendil-works/pi-coding-agent pi --version
--ignore-scripts 会阻止依赖安装阶段执行生命周期脚本,Pi 的正常 npm 安装不依赖这些脚本。
Windows PowerShell、macOS 和 Linux 都可以使用相同的 npm 安装命令。如果安装成功但提示找不到 pi,应检查 npm 全局可执行目录是否已加入 PATH:
3. 登录模型提供商 进入任意项目目录后启动:
1 2 cd /path/to/supply-chain-systempi
在 Pi 里执行:
可以选择官方支持的订阅登录,也可以使用 API Key。以 PowerShell 为例,临时设置 OpenAI API Key:
1 2 $env:OPENAI_API_KEY ="你的API Key" pi
Linux 或 macOS:
1 2 export OPENAI_API_KEY="你的API Key" pi
不要把 API Key 写入 Git 仓库、AGENTS.md、提示词或日志。也可以通过 /login 把凭证交给 Pi 管理,默认凭证文件位于 ~/.pi/agent/auth.json。
4. 第一次供应链任务 先让 Pi 理解项目,不要一上来就让它改代码:
1 2 3 请先读取 README.md、pom.xml 和订单、库存、采购模块的目录结构。 说明创建采购订单后,库存预占、补货计算和供应商下单分别在哪些模块完成。 只分析,不修改文件,也不要执行写数据库的命令。
Pi 默认给模型提供 read、write、edit、bash 四个工具。模型并不是直接操作电脑,而是在 Agent 循环中选择工具,Pi 执行工具后把结果返回给模型。
三、用AGENTS.md建立项目规则 AI 在供应链项目里最容易犯的错误,不是 Java 语法错误,而是误解库存口径、订单状态和事务边界。应在仓库根目录创建 AGENTS.md,把长期有效的规则放进去。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 # Supply Chain Project Instructions ## Modules - order-service: 销售订单和状态流转- inventory-service: 现存量、预占量、冻结量和库存流水- procurement-service: 采购申请、采购订单和供应商协同- replenishment-service: 安全库存与补货建议## Business Rules - 可用库存 = 现存量 - 预占量 - 冻结量。- 库存扣减必须使用带数量条件的原子更新,并记录库存流水。- 同一个 businessRequestId 重试时不得重复预占或释放库存。- 采购订单状态只能按状态机流转,禁止直接覆盖状态。- 跨服务一致性使用本地事务加 Outbox 事件,不创建分布式大事务。## Safety - 默认只允许查询本地开发库,不连接生产数据库。- 未经明确确认,不执行 INSERT、UPDATE、DELETE、DDL 和消息重放。- 不读取或输出 .env、密钥、Token、客户手机号和供应商银行信息。## Verification - Java 代码修改后运行 mvn -pl <module > test。- 库存并发逻辑必须增加重复请求、库存不足和并发扣减测试。- 数据库变更必须提供可回滚迁移脚本和索引影响说明。
Pi 启动时会加载全局 ~/.pi/agent/AGENTS.md,以及当前目录和父目录中的 AGENTS.md 或 CLAUDE.md。修改规则后执行 /reload,或者重新启动 Pi。
项目规则应该描述稳定事实,不要把某次临时需求全部塞进去。临时需求应放在单独的需求文档中,再通过 @文件名 引用。
四、掌握一套可靠的日常开发流程 以“订单创建时预占库存”为例,可以把一次任务拆成五个阶段。
阶段1:建立上下文 1 2 读取 @AGENTS.md、@docs/inventory-model.md,搜索现有的库存扣减、释放、流水和幂等实现。 列出相关文件、当前调用链、事务边界和测试入口。不要修改代码。
这一步要求 Pi 先找到项目里的真实模式,避免凭经验发明不存在的层次和组件。
阶段2:输出实施计划 1 2 3 4 5 6 7 8 9 10 11 需求:订单创建成功后预占库存;订单取消或支付超时后释放;重复消息不能重复处理。 请给出实施计划,必须包含: 1. 正常流程和异常流程。 2. 表字段、唯一键、版本号和条件更新SQL。 3. 本地事务与Outbox事件边界。 4. 幂等键定义和重复消费处理。 5. 需要修改的文件清单。 6. 单元测试、并发测试和集成测试用例。 只输出计划,等待确认后再编码。
阶段3:小步实现 确认计划后再执行:
1 2 按计划先完成库存预占的领域逻辑和仓储层,只修改 inventory-service。 不要修改公共依赖版本。完成后展示差异并运行该模块测试。
一次只改变一个业务闭环。订单、库存、采购三个服务同时大改,会让上下文迅速膨胀,也会增加错误定位成本。
阶段4:验证业务不变量 至少检查以下不变量:
可用库存不能为负数。
相同幂等键只能产生一次库存流水。
释放数量不能超过原预占数量。
数据库回滚时不能留下已发送但无法追踪的业务事件。
消息重复、乱序、延迟时,最终状态仍然正确。
可以让 Pi 主动补测试:
1 根据本次 diff 检查库存不变量。补充库存不足、相同幂等键重复请求、20线程并发预占、事务回滚四组测试,然后运行测试并解释失败原因。
阶段5:审查和提交 1 2 审查当前 git diff,优先寻找数据一致性、并发、幂等、空值、越权和日志泄密问题。 没有阻塞问题后,给出建议的提交信息,但不要自动推送。
这个流程的重点是把“理解、计划、实现、验证、审查”分开。模型能力再强,也不应该跳过业务确认和可重复验证。
五、模型、思考强度与会话管理 切换模型 在交互模式中:
也可以使用 Ctrl+L 打开模型选择器,使用 Shift+Tab 切换思考强度。简单的格式调整不需要高强度推理;跨服务库存一致性、死锁分析和数据迁移则适合更高强度。
项目级 .pi/settings.json 可以保存团队约定,例如:
1 2 3 4 5 6 7 8 9 { "defaultProvider" : "openai" , "defaultModel" : "你的模型ID" , "defaultThinkingLevel" : "medium" , "enabledModels" : [ "openai/*" , "anthropic/*" ] }
模型 ID 会随提供商更新,先用 /model 或 pi --list-models 查看当前可用值,不要照抄过时文章里的模型名。
管理长任务 1 2 3 pi -c pi -r pi --name "库存预占改造"
交互模式还提供 /new、/resume、/tree、/fork 和 /clone。建议一个会话只解决一个明确问题。需求方向发生变化时,通过 /fork 保留原分支,比在同一上下文里反复推翻更清晰。
接入本地模型 Pi 可以通过 ~/.pi/agent/models.json 接入 Ollama、LM Studio、vLLM 等 OpenAI 兼容服务:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 { "providers" : { "ollama" : { "baseUrl" : "http://localhost:11434/v1" , "api" : "openai-completions" , "apiKey" : "ollama" , "compat" : { "supportsDeveloperRole" : false , "supportsReasoningEffort" : false } , "models" : [ { "id" : "你的本地模型ID" , "reasoning" : false } ] } } }
本地模型适合代码检索、摘要和低风险分类,但是否能处理复杂库存一致性问题,必须通过真实测试集评估,不能只看通用排行榜。
六、用Skill沉淀供应链知识 AGENTS.md 是所有任务都要遵守的项目规则,Skill 则是按需加载的专业流程。可以创建:
1 .pi/skills/supply-chain-review/SKILL.md
内容如下:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 --- name: supply-chain-review description: 审查订单、库存、采购和补货代码。当任务涉及库存数量、状态机、幂等、消息或供应链数据一致性时使用。 --- # Supply Chain Review 1. 先识别业务实体、状态和数量口径。2. 画出同步调用、事务提交和异步消息的先后顺序。3. 检查幂等键来源、唯一约束和重复消息处理。4. 检查库存更新是否包含 `available_qty >= request_qty` 条件。5. 检查超时、取消、部分成功和补偿路径。6. 检查日志是否泄露客户、供应商或凭证信息。7. 输出按严重程度排序的问题,并给出文件位置和测试建议。
项目被信任后,Pi 会发现 .pi/skills/ 下的技能。重载后可以显式调用:
1 /skill:supply-chain-review 审查本次库存预占改动
Skill 可以附带 scripts/、references/ 和 assets/。例如把库存字段字典、订单状态机和消息规范放进 references/,只有任务需要时才加载,能减少固定上下文占用。
七、用Extension接入只读库存接口 Skill 只是告诉模型怎么工作,Extension 才能注册真正可调用的工具。下面创建一个项目级只读库存查询工具:
1 .pi/extensions/inventory-query.ts
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent" ;import { Type } from "typebox" ;export default function (pi : ExtensionAPI ) { pi.registerTool ({ name : "query_inventory" , label : "Query Inventory" , description : "按SKU和仓库查询只读库存快照,不执行预占、扣减或释放" , parameters : Type .Object ({ sku : Type .String ({ description : "SKU编码" }), warehouseCode : Type .String ({ description : "仓库编码" }), }), async execute (_toolCallId, params, signal ) { const baseUrl = process.env .SCM_API_BASE_URL ; const token = process.env .SCM_API_TOKEN ; if (!baseUrl) { throw new Error ("SCM_API_BASE_URL is not configured" ); } const url = new URL ("/api/v1/inventory/availability" , baseUrl); url.searchParams .set ("sku" , params.sku ); url.searchParams .set ("warehouseCode" , params.warehouseCode ); const headers : Record <string , string > = { Accept : "application/json" , }; if (token) headers.Authorization = `Bearer ${token} ` ; const response = await fetch (url, { headers, signal }); if (!response.ok ) { throw new Error (`Inventory API failed: HTTP ${response.status} ` ); } const snapshot = await response.json (); return { content : [ { type : "text" , text : JSON .stringify (snapshot, null , 2 ), }, ], details : { sku : params.sku , warehouseCode : params.warehouseCode , status : response.status , }, }; }, }); }
配置环境变量后启动 Pi:
1 2 3 $env:SCM_API_BASE_URL ="https://scm-api.example.internal" $env:SCM_API_TOKEN ="短期只读Token" pi
首次加载项目级 Extension 时,Pi 会要求确认是否信任项目。执行 /reload 后,可以输入:
1 查询 SKU-10001 在 WH-SZ-01 的库存快照,结合近30天日均销量和7天采购提前期判断是否需要补货。只生成建议,不创建采购单。
这个工具应使用专门的只读服务账号,并在 API 网关限制路径、仓库范围、频率和返回字段。不要为了方便给 Agent 一个可以调用任意内部接口的管理员 Token。
八、使用SDK构建补货建议服务 如果要把 Pi 嵌入 Node.js 服务,使用 SDK 比启动子进程更直接:
1 npm install @earendil-works/pi-coding-agent typebox
下面是一个最小的补货建议 Agent。真实项目应把 queryReplenishmentInputs 替换成经过鉴权的内部 API 客户端。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 import { createAgentSession, defineTool, ModelRuntime , SessionManager , } from "@earendil-works/pi-coding-agent" ; import { Type } from "typebox" ;const scmApiBaseUrl = process.env .SCM_API_BASE_URL ;const scmApiToken = process.env .SCM_API_TOKEN ;if (!scmApiBaseUrl || !scmApiToken) { throw new Error ("SCM_API_BASE_URL and SCM_API_TOKEN must be configured" ); } const replenishmentInputs = defineTool ({ name : "get_replenishment_inputs" , label : "Get Replenishment Inputs" , description : "读取SKU补货计算所需的库存、销量、在途和提前期数据" , parameters : Type .Object ({ sku : Type .String (), warehouseCode : Type .String (), }), async execute (_toolCallId, params, signal ) { const query = new URLSearchParams ({ sku : params.sku , warehouseCode : params.warehouseCode , }); const response = await fetch ( `${scmApiBaseUrl} /api/v1/replenishment/inputs?${query} ` , { headers : { Authorization : `Bearer ${scmApiToken} ` , }, signal, }, ); if (!response.ok ) throw new Error (`SCM API returned ${response.status} ` ); const data = await response.json (); return { content : [{ type : "text" , text : JSON .stringify (data) }], details : { sku : params.sku , warehouseCode : params.warehouseCode }, }; }, }); const modelRuntime = await ModelRuntime .create ();const { session } = await createAgentSession ({ modelRuntime, sessionManager : SessionManager .inMemory (process.cwd ()), tools : ["get_replenishment_inputs" ], customTools : [replenishmentInputs], }); session.subscribe ((event ) => { if ( event.type === "message_update" && event.assistantMessageEvent .type === "text_delta" ) { process.stdout .write (event.assistantMessageEvent .delta ); } }); await session.prompt (` 分析 SKU-10001 在 WH-SZ-01 的缺货风险。 先调用工具获取事实,再按以下公式给出建议: 补货点 = 提前期日均需求 + 安全库存。 输出事实、计算过程、风险、建议数量和需要人工确认的假设。 禁止创建采购单。 ` );
这段代码只开放了一个自定义工具,没有给 Agent bash、write 或 edit。服务端 Agent 应按场景建立工具白名单,不要照搬编程助手的默认权限。
九、Java系统通过RPC接入Pi 供应链后台通常是 Java 技术栈。此时可以单独部署一个 Pi Agent Sidecar,由 Java 服务通过 RPC 调用:
1 pi --mode rpc --no-session
RPC 使用标准输入和标准输出传输 JSONL,每行一个 JSON 对象。Java 服务发送:
1 { "id" : "replenishment-10001" , "type" : "prompt" , "message" : "分析SKU-10001在WH-SZ-01的缺货风险,只输出补货建议" }
Pi 会先返回请求是否被接受,再持续输出 message_update、tool_execution_start、tool_execution_end 和 agent_end 等事件。
生产环境建议采用以下结构:
Java 业务服务负责登录态、租户、权限和参数校验。
Node.js Agent 服务或 Pi RPC Sidecar 负责会话和模型编排。
Agent 只能通过受控工具访问订单、库存和采购 API。
工具层统一做超时、重试、熔断、脱敏和审计。
采购单创建等写操作进入待审批队列,由业务服务执行。
不要为每个请求临时启动一个 Pi 进程。可以维护固定数量的 Sidecar,按租户和任务隔离会话;如果主系统本身可以部署 Node.js 服务,优先使用 SDK,类型和生命周期管理会更简单。
十、供应链补货Agent的完整技术方案
一个可上线的补货 Agent 可以分成四层。
1. 入口层
Web、企业微信或 ERP 页面接收用户问题。
Java 网关校验用户、租户、仓库和数据权限。
把自然语言转换为带 requestId 的 Agent 请求。
2. Agent编排层
Pi AgentSession 保存一次分析任务的上下文。
系统提示词限定角色、公式、输出格式和禁止事项。
Skill 提供补货分析步骤和业务术语。
模型决定先查询哪些事实,再形成结论。
3. 工具层 至少拆成这些只读工具:
get_inventory_snapshot:现存、预占、冻结、可用和在途库存。
get_sales_forecast:历史销量、预测量和促销修正。
get_supplier_lead_time:供应商交期、最小起订量和包装倍数。
get_open_purchase_orders:未关闭采购单和预计到货日期。
calculate_replenishment:使用确定性代码计算补货点和建议量。
计算公式应该由确定性工具执行,而不是让模型心算。例如:
1 2 3 4 有效库存位置 = 可用库存 + 在途库存 - 已分配未出库数量 补货点 = 采购提前期内预测需求 + 安全库存 建议补货量 = max(0, 目标库存 - 有效库存位置) 最终采购量 = 按最小起订量和包装倍数向上取整
模型负责解释数据、识别异常和组织建议,确定性程序负责算数、状态校验和写入。
4. 审批与执行层 Agent 的结果先形成 ReplenishmentProposal:
1 2 3 4 5 6 7 8 9 { "requestId" : "RP-20260801-0001" , "sku" : "SKU-10001" , "warehouseCode" : "WH-SZ-01" , "suggestedQty" : 240 , "reasonCodes" : [ "BELOW_REORDER_POINT" , "LEAD_TIME_RISK" ] , "evidenceVersion" : "inventory-88921" , "status" : "PENDING_APPROVAL" }
审批通过后,由采购服务重新读取库存版本、校验建议是否过期,再创建采购申请。不要让模型直接拼接 SQL 写数据库,也不要把“模型已经判断正确”当作越过业务校验的理由。
十一、生产安全与权限控制 Pi 默认没有内置沙箱。bash、Extension 和第三方 Package 都以 Pi 进程的系统权限运行。项目信任机制只能控制是否加载项目资源,不等于运行时安全边界。
生产环境至少落实以下措施:
进程隔离:在容器、虚拟机或受限系统账号中运行 Agent。
工具白名单:业务 Agent 不开放任意 bash、文件写入和通用 HTTP 工具。
最小权限:库存工具只读,且限制租户、仓库、接口和字段。
人工审批:采购下单、库存调整、价格修改必须经过确认。
参数校验:服务端重新校验 SKU、数量、状态和数据版本。
凭证隔离:Token 存在密钥系统或环境变量中,不进入模型上下文。
防提示词注入:把接口返回的数据当作不可信数据,不执行其中夹带的指令。
审计留痕:记录用户、模型、会话、工具、脱敏参数、耗时、结果版本和审批人。
预算控制:限制单次任务轮数、上下文、Token、超时和并发数。
降级策略:模型或工具不可用时回退到传统规则引擎和人工流程。
第三方 Skill、Extension 和 Pi Package 可能包含可执行代码,安装前必须审查源码并固定版本。
十二、评估Agent是否真的可用 不要用“回答看起来不错”作为上线标准。可以从历史供应链数据中构造一套脱敏测试集:
正常补货 SKU。
促销导致需求突增的 SKU。
有大量在途库存的 SKU。
供应商延迟交付的 SKU。
库存数据缺失或时间戳过期的 SKU。
多仓调拨比采购更合适的 SKU。
最小起订量和包装倍数冲突的 SKU。
关键指标包括:
指标
说明
工具选择准确率
是否调用了正确的事实查询和计算工具
参数准确率
SKU、仓库、租户和时间范围是否正确
事实一致率
输出数字是否与工具结果一致
建议接受率
采购人员接受或小幅调整建议的比例
危险动作率
未审批写入、越权访问等事件,目标必须为0
任务成功率
在超时和重试限制内完成的比例
P95耗时与成本
评估交互体验和规模化成本
每次升级模型、提示词、Skill 或 Extension,都应重放同一批测试集并比较结果。只有回归指标稳定,才能扩大业务范围。
十三、常见问题排查 pi命令不存在 检查 Node.js 版本、全局安装结果和 npm prefix:
1 2 3 node --version npm list -g @earendil-works/pi-coding-agent npm config get prefix
登录成功但找不到模型 先执行 pi --list-models,检查提供商凭证和 models.json。自定义无密钥本地服务也需要占位 apiKey,否则模型可能不会出现在可用列表中。
项目Skill或Extension没有加载 确认目录分别是 .pi/skills/ 和 .pi/extensions/,确认已经信任当前项目,然后执行 /reload。非交互模式不会显示信任对话框,需要预先保存信任决策,或者在明确理解风险时使用一次性的 --approve。
Agent修改范围越来越大 重新开会话,把任务缩小到一个模块;在提示词中列出允许修改的目录;先让 Pi 输出文件清单和计划,再允许编辑。
结果包含正确解释但数字算错 把公式和取整规则实现成确定性工具。模型只能传入参数、调用工具和解释结果,不能作为财务、库存或采购数量的唯一计算器。
十四、推荐的进阶路线
第一天:完成安装、登录、文件引用、模型切换和会话恢复。
第二天:为现有 Java 供应链项目编写 AGENTS.md。
第三天:用 Pi 完成一个低风险代码审查和测试补充任务。
第四天:创建供应链审查 Skill,沉淀团队检查清单。
第五天:编写一个只读库存查询 Extension。
第六天:使用 SDK 构建补货建议原型,并建立离线测试集。
第七天以后:接入审批、审计、监控、限流和容器隔离,再考虑试点上线。
总结 Pi 的价值不在于预置了多少复杂流程,而在于它提供了一套小而清晰的 Agent 基础能力:统一模型接口、Agent 循环、会话、工具、TUI、Skills、Extensions、SDK 和 RPC。初学时可以直接使用 CLI,提高 Java 项目的检索、修改和测试效率;进阶后可以通过 Skill 固化供应链知识,通过 Extension 接入内部只读 API;真正上线时,则应使用 SDK 或 RPC,把 Pi 放在权限、审批和审计体系之内。
供应链 Agent 最可靠的职责是“查询事实、执行确定性计算、解释风险、生成建议”,而不是绕过业务服务直接修改库存和采购数据。把模型的推理能力与传统系统的规则、事务和权限结合起来,才是从能演示走向能生产的关键。
参考资料