HoRain云小助手个人主页 个人专栏: 《Linux 系列教程》《c语言教程》⛺️生活的理想就是为了理想的生活!⛳️ 推荐前些天发现了一个超棒的服务器购买网站性价比超高大内存超划算忍不住分享一下给大家。点击跳转到网站。专栏介绍专栏名称专栏介绍《C语言》本专栏主要撰写C干货内容和编程技巧让大家从底层了解C把更多的知识由抽象到简单通俗易懂。《网络协议》本专栏主要是注重从底层来给大家一步步剖析网络协议的奥秘一起解密网络协议在运行中协议的基本运行机制《docker容器精解篇》全面深入解析 docker 容器从基础到进阶涵盖原理、操作、实践案例助您精通 docker。《linux系列》本专栏主要撰写Linux干货内容从基础到进阶知识由抽象到简单通俗易懂帮你从新手小白到扫地僧。《python 系列》本专栏着重撰写Python相关的干货内容与编程技巧助力大家从底层去认识Python将更多复杂的知识由抽象转化为简单易懂的内容。《试题库》本专栏主要是发布一些考试和练习题库涵盖软考、HCIE、HRCE、CCNA等目录⛳️ 推荐专栏介绍生命周期全景核心事件详解input — 输入拦截实例tool_call — 工具调用拦截实例tool_result — 修改工具结果实例context — 修改 LLM 上下文实例before_agent_start — 注入消息实例事件处理要点事件系统是扩展的核心机制。通过监听生命周期事件你可以在 AI 工作的各个阶段插入自定义逻辑。生命周期全景以下是 Pi Agent 从启动到退出过程中触发的所有事件pi 启动 │ ├─► project_trust在加载项目资源之前仅用户/全局和 CLI 扩展可参与 ├─► session_start { reason: startup } └─► resources_discover { reason: startup } │ ▼ 用户发送提示 ──────────────────────────┐ │ │ ├─► input可拦截、转换或处理 │ ├─► before_agent_start可注入消息 │ ├─► agent_start │ │ │ │ ┌─── 每个轮次 (turn) ──────┐ │ │ │ │ │ │ ├─► turn_start │ │ │ ├─► context可修改消息 │ │ │ ├─► before_provider_headers │ │ │ ├─► before_provider_request │ │ │ ├─► after_provider_response │ │ │ │ │ │ │ │ LLM 响应可能调用工具 │ │ │ │ ├─► tool_execution_start │ │ │ ├─► tool_call可阻止 │ │ │ ├─► tool_execution_update │ │ │ ├─► tool_result可修改 │ │ │ └─► tool_execution_end │ │ │ │ │ │ └─► turn_end │ │ │ │ ├─► agent_end │ └─► agent_settled │ │ 用户发送另一条提示 ◄────────────────────┘ 退出 (CtrlC, CtrlD, SIGHUP, SIGTERM) └─► session_shutdown核心事件详解input — 输入拦截在用户输入被处理之前触发可以转换、拦截或直接处理输入实例pi.on(input, async (event, ctx) {// event.text - 原始输入文本// event.images - 附带的图片// event.source - interactive | rpc | extension// 转换输入在输入前添加指令if (event.text.startsWith(?quick )) {return {action: transform,text: 简短回复${event.text.slice(7)}};}// 直接处理不经过 LLM 直接响应if (event.text ping) {ctx.ui.notify(pong, info);return { action: handled };}// 跳过扩展注入的消息if (event.source extension) {return { action: continue };}return { action: continue }; // 默认正常处理});action 值效果continue不改变输入继续正常处理流程transform修改输入后继续处理多个 handler 的转换会链式叠加handled完全接管跳过 LLM 调用第一个返回此值的 handler 生效input 事件在 Skill 和模板展开之前触发所以你看到的是原始输入。/skill:foo 和 /template 此时尚未展开。tool_call — 工具调用拦截在工具执行之前触发可以修改参数或阻止执行实例import { isToolCallEventType } from earendil-works/pi-coding-agent;pi.on(tool_call, async (event, ctx) {// 拦截危险 bash 命令if (isToolCallEventType(bash, event)) {// event.input 是 { command: string; timeout?: number }// 可以修改 commandevent.input.command source ~/.profile\n${event.input.command};const dangerous [rm -rf /, mkfs., dd if, /dev/sda];if (dangerous.some(cmd event.input.command.includes(cmd))) {return { block: true, reason: 危险命令已被阻止 };}}// 记录所有文件读取操作if (isToolCallEventType(read, event)) {// event.input 是 { path: string; offset?: number; limit?: number }console.log(读取文件: ${event.input.path});}});event.input 是可变的——你修改它会直接影响工具执行。tool_result — 修改工具结果在工具执行完成后触发可以修改返回给 LLM 的结果实例pi.on(tool_result, async (event, ctx) {// event.toolName - 工具名// event.content - 返回给 LLM 的内容// event.details - 详情数据// event.isError - 是否为错误// 例如对 read 结果添加行号if (event.toolName read !event.isError) {const lines event.content.filter(c c.type text).map(c c.text).join(\n).split(\n).map((line, i) ${i 1}: ${line}).join(\n);return {content: [{ type: text, text: lines }],};}});context — 修改 LLM 上下文在每次 LLM 调用之前触发可以过滤或修改消息实例pi.on(context, async (event, ctx) {// event.messages - 当前上下文消息的深拷贝可安全修改// 过滤掉特定类型的消息const filtered event.messages.filter(m {// 移除自定义类型为 debug 的消息if (m.type custom m.customType debug) {return false;}return true;});return { messages: filtered };});before_agent_start — 注入消息在 AI 开始处理用户输入之前触发可以注入额外消息或修改系统提示词实例pi.on(before_agent_start, async (event, ctx) {// event.prompt - 用户的提示文本// event.systemPrompt - 当前配置的系统提示词return {// 注入一条持久化消息存入会话发送给 LLMmessage: {customType: my-context,content: 当前时间是 ${new Date().toISOString()},display: true,},// 追加到系统提示词systemPrompt: event.systemPrompt \n\n请在所有回复中使用中文。,};});事件处理要点多个扩展可以同时监听同一事件按加载顺序依次执行返回 { block: true, reason: ... } 可以阻止操作返回 { cancel: true } 可以取消会话切换等操作使用 ctx.signal 可以在异步操作中响应取消信号使用 ctx.ui 系列方法与用户交互在扩展工厂函数中不要启动后台资源进程、socket、定时器等。将资源启动延迟到 session_start 事件中并在 session_shutdown 中清理。❤️❤️❤️本人水平有限如有纰漏欢迎各位大佬评论批评指正如果觉得这篇文对你有帮助的话也请给个点赞、收藏下吧非常感谢! Stay Hungry Stay Foolish 道阻且长,行则将至,让我们一起加油吧