elm · 2026-10-12T08:59:02+08:00

Pi 使用指南整合自 6 篇公众号文章（2026-08 ~ 2026-10），覆盖 Pi 入门、内置工具、插件体系、Pi 1.0 新特性与最佳实践。Pi = Pi Coding Agent，官网 pi.dev，GitHub earendil-works 开源项目，核心作者 Mario Zechner。一、Pi 是什么跑在终端里的 AI 编程助手。它出圈的原因很反直觉：不是功能多，而是功能少。设计哲学一句话：把 Agent 适配成你的工作流，而不是让你反过来适应它。主流工具出厂即"全家桶"（子代理、计划模式、自动审查、记忆系统一股脑塞给你），你永远在用它预设的流程干活。Pi 的内核刻意做得极小，默认连子代理和计划模式都不带，把骨架搭好，剩下的让你自己往上装。你装上的每一个插件都是你真正需要的——没有冗余，没有上下文浪费。二、安装与上手npm install -g --ignore-scripts @earendil-works/pi-coding-agent进项目目录敲 pi，登录模型账号或配 API Key 即可开聊。三、五种扩展方式方式说明位置ExtensionsTypeScript 模块：注册自定义工具、命令、拦截事件、自定义 UI~/.pi/agent/extensions/（全局）/ .pi/extensions/（项目）Skills按需加载的技能包（SKILL.md + 脚本 + 参考文档），符合 Agent Skills 标准~/.pi/agent/skills/、.pi/skills/Prompt TemplatesMarkdown 提示词模板，输入 /名字即展开~/.pi/agent/prompts/ThemesTUI 配色主题（JSON）~/.pi/agent/themes/Pi Packages把以上四种打包，经 npm / git 分发，pi install 一条命令装好—四、插件安装与管理命令pi install npm:pi-mcp-adapter # 从 npm 安装 pi install npm:pi-subagents@0.61.0 # 指定版本 pi install git:github.com/user/repo@v1 # 从 git 安装 pi install ./local/path # 本地目录 pi install -l npm:pi-web-access # -l 装到项目级（.pi/ 下，可随项目共享） pi -e npm:pi-subagents # 临时试用一次，不落盘，用完即弃 pi list # 查看已安装 pi update --all # 全部更新 pi config # TUI 里开关各项资源 pi remove npm:pi-mcp-adapter # 卸载装完 /reload 即生效，不用重启。⚠️ 安全：插件以你的完整系统权限运行、可执行任意代码。只装可信来源的包；项目级插件要在信任项目后才会加载。不放心就先用 pi -e 试用。五、内置工具箱：8 个工具，默认只开 4 个默认启用（最小可用集）：read、bash、edit、write——能读、能跑、能改、能写。默认关闭，按需显式开：grep、find、ls、powershell。设置项 defaultTools（.pi/agent/settings.json）：空数组可关掉全部内置工具（不影响扩展与 SDK 工具）；命令行 --tools 参数按次覆盖、优先级最高。工具做什么关键参数约束 / 上限read读文本与图片（jpg/png/gif/webp/bmp，图片作附件发模型）path、offset、limit截断 2000 行 / 50KB（先到者为准）；截断时描述里直接写明"用 offset 续读"write整份写入，不存在则创建，自动建父目录path、content走文件变更队列edit精确文本替换path、edits[].oldText/newTextoldText 必须唯一且不重叠；相邻改动要合并成一次编辑；别塞大段未变内容bash执行 shell 命令，返回 stdout/stderrcommand、timeout（秒）截断取最后 N 行（关键信息在末尾）；完整输出落临时文件；非零退出码抛错（失败显式化）powershell同 bash 的 Windows 侧实现同 bash复用 bash 契约，注入 UTF-8 输出编码前缀grep搜内容，返回匹配行+路径+行号pattern、path、glob、ignoreCase、literal、context、limit默认 100 个匹配；单行截 500 字符find按 glob 找文件，返回相对路径pattern、path、limit默认 1000 个结果ls列目录，字母排序，目录带 /，含点文件path、limit默认 500 项三个检索工具的共同纪律：都尊重 .gitignore、都有硬上限、输出结构化（比让模型自己拼 shell 管道稳）。为什么单独做 powershell：Pi 默认面向 Windows/macOS/Linux 三平台设计，把 Windows shell 做成与 bash 平级的一等工具，比让模型在 bash 里绕道调 powershell 干净得多。两者是同一 shell 契约的两个实现（复用同一套输入/详情类型），只换 shell 名与提示符（PS>）并在命令前注入 UTF-8 输出编码设置。shell 工具的失败契约：非零退出码抛错（成为 isError: true 的失败结果，而非"看起来正常的文本输出"）、超时抛 timeout:N、被中止抛 aborted。成熟度不在能跑命令，而在"截断怎么取、超时怎么报、失败怎么显式"这三点都写死在契约里。容易被忽略的机制：每个工具都带 promptSnippet（一句话摘要）和 promptGuidelines（使用指南），会"投稿"进系统提示词——开哪些工具，等于决定系统提示词里出现哪些段落（例如 powershell 的指南就告诉你：查看 PI_* 环境变量可了解当前模型与会话信息）。核心工具还带 constrainedSampling（偏好强约束 JSON 抽样，参数用 TypeBox 定义、最终转成 provider 需要的 schema）。省上下文的使用心法："读得准"比"读得多"省钱——read 用 offset/limit 精准取段，grep 先用窄 glob 定位，小改动用 edit 而不是 write 整份覆盖。5.1 怎么加自己的工具内置 8 个只是起点，真正的扩展面在扩展系统里。加一个自定义工具需要四件套：名字、面向模型的描述、TypeBox 参数 schema、execute() 函数。返回结果里 content 给模型看、details 给渲染或状态重建（没有结构化数据就写 details: undefined）。几条官方规则很关键，决定它能不能进生产：规则说明抛错才是失败从 execute() 抛错才产生失败的工具结果；返回一个对象不会标记为错误terminate: true 是批内共识只有这一批每个完成的工具都同意终止，才跳过自动跟进共享内存状态要顺序执行不共享的可以并行——并行是默认，安全要声明改文件必须进队列用 withFileMutationQueue() 把"读-改-写"整段包住（同批工具调用可并行跑）大结果要截断 + 指路截断后告诉模型去哪读完整输出（和内置工具同一套路）嵌套模型调用要挂用量工具内部调了模型，就把 usage 放进结果，否则会话总账不准两个进阶玩法：动态激活省 token：工具先全部注册、默认不激活，再用一个"加载器工具"调 pi.setActiveTools() 按需激活。按工具挂钩子：tool_call / tool_result 都是按工具名细分的联合类型，官方提供 isToolCallEventType(toolName, event) 判断助手。六、推荐插件清单6.1 下载量 Top 榜（npm 月下载量，2026-08）插件月下载量一句话定位pi-mcp-adapter~76 万接入 MCP 生态但不烧上下文pi-web-access~40 万上网搜索、抓网页、看视频pi-subagents~36 万补上子代理能力@juicesharp/rpiv-ask-user-question~12 万该问就问，不再瞎猜pi-background-tasks~11 万长任务后台跑，不阻塞对话@juicesharp/rpiv-todo~10 万实时待办浮层pi-lens~6 万写代码实时反馈（LSP/lint/类型检查）@plannotator/pi-extension~5 万计划先批注再执行pi-simplify~4 万代码简化审查pi-memory~3.7 万语义记忆pi-dynamic-workflows~3.4 万动态工作流 + 深度研究6.2 逐个拆解（核心 8 个）1. pi-mcp-adapter —— MCP 接入不烧上下文（下载量之王）痛点：MCP 工具定义冗长，一个 server 能烧 1 万+ token。解法：用约 200 token 的代理工具替代全部工具定义，模型按需发现，server 真正用到时才启动。自动读取已有 .mcp.json / ~/.config/mcp/mcp.json；用过 Cursor / Claude Code / Codex 的，/mcp setup 一键迁移。2. pi-web-access —— 给 Agent 装上网线Pi 默认不能上网。补齐：Web 搜索（内置 Exa 零配置，用 Codex 订阅登录还能复用 OpenAI 的搜索授权；另支持 Brave、Tavily、Firecrawl、Jina、Kagi、自托管 SearXNG 等 20+ 源）、URL 抓取、GitHub 仓库克隆、PDF 提取、YouTube 视频理解（扔链接就能问内容）、本地视频分析。3. pi-subagents —— 补上子代理零配置，大白话调用：用 reviewer 审查这个 diff、让 oracle 对我的计划提第二意见、并行跑三个 reviewer：查正确性 / 查测试 / 查过度设计。内置 scout（侦察）、researcher（调研）、reviewer（审查）、oracle（第二意见）等角色；子代理是独立子会话，前台流式、后台可查。4. rpiv-ask-user-question —— 不给选项就不猜需求有歧义时弹结构化问卷（选择/确认/输入），而不是脑补后埋头做错。省的是"做完才发现方向错了"这种最贵的错误。5. pi-background-tasks —— 长任务后台跑跑测试、起 dev server、迁移 dry-run 转后台，/bg 启动，/jobs /logs /kill 管理，完成通知。支持只读委托子代理（派只读的子 Pi 去调研，结果哈希校验后带回）；进阶玩法 Fusion：三个候选子代理并行 + 盲评 + 合并。6. rpiv-todo —— 实时待办浮层模型维护的任务清单常驻终端，实时看到干到哪、还剩几步。关键：/reload 和上下文压缩后依然存活，进度不丢。7. pi-lens —— 写代码实时"体检仪"每次写入/编辑后自动跑 LSP 诊断、lint、类型检查、格式化，能 autofix；/lens-map 生成 HTML 依赖图，symbol_search 全局符号检索；诊断可标记误报/忽略/延期，跨会话生效。强类型项目（TS/Python/Go）建议人手一个。8. pi-dynamic-workflows —— 重型玩家把任务扇出给 100+ 子代理并行，带模型路由、token/成本核算、断点续跑、git worktree 隔离，内置 /deep-research。大型重构、批量审查、深度调研用。6.3 其他高口碑插件插件安

2409

elm2026-10-12
🌞 社区骨干 📚✅VIP60
本主题需要点赞才可查看
登录后点赞投币查看主楼
相关标签开源项目 AI编程助手 Pi Coding Agent 插件体系终端工具
相关主题

登录后查看回帖本主题已有 9 条回帖，登录后即可全部查看注册账号

Pi 上手指南