Pi 大道至简，超越Codex和Claude Code的极简Agent，保姆级全攻略， 一期视频精通

🚀 核心定位与性能优势

• 极简架构：Pi 仅包含 4 个基础工具（读、写、改文件及运行命令），系统提示词仅约 1000 token。
• 资源效率：在 Pi 中发送“你好”仅消耗 1100 输入 token 和 4000 分上下文；相比之下，Codex 仅打招呼即占用 18000 token，白白消耗 7% 上下文窗口。
• 基准测试表现：
• 速度：Composial 测试显示，Pi 完成编程任务速度比其他 Coding Agent 快 1.5 到 2 倍。
• 成本与质量：Databricks 在百万行代码仓库测试中，Pi 在同等成本下任务成功率高于 Claude Code 和 Codex。
• 最佳组合：代码质量最高点为 Pi 搭配 Claude Opus 4.8 模型。

💻 安装配置与模型接入

• 安装流程：
• Windows：通过 PowerShell 执行官网一键命令，自动检测并安装 Node.js 和 Git Bash。
• MacOS：在终端执行 CURL 命令即可安装。
• 模型配置：
• API Key 模式：支持 40 多家供应商，如 DeepSeek。需创建 API Key 并填入 Pi。
• 订阅模式：支持 OpenAI Codex 等订阅服务，通过浏览器登录授权，无需额外 API Key。
• 模型切换：使用 `/model` 命令切换模型（如 DeepSeek V4 Pro/Flash），`Shift+Tab` 调整思考强度，`Ctrl+L` 快速打开模型选择器。

⚡ 核心交互与指令控制

• 多行输入：`Shift+Enter` 换行，或 `Ctrl+G` 打开记事本编辑长提示词。
• 指令追加机制：
• Steering（引导）：默认模式。在执行中途插入指令，AI 立即改变执行方向（如中途要求改用 Next.js）。
• Follow Up（排队）：Windows 需删除 PowerShell 全屏快捷键 `Alt+Enter` 冲突，使用 `Alt+Enter` 发送；Mac 使用 `Option+Enter`。指令排队等待当前任务完成后执行。
• 非交互模式：使用 `-p` 参数后接指令，后台静默执行一次性任务（如查天气写文件）。
• 命令执行：单 `#` 运行命令且 AI 可见结果；双 `##` 运行命令且 AI 不可见。

🌳 会话管理与对话树

• Session 管理：
• `/new`：开启新会话，清空上下文。
• `pi -c`：从最近一次 Session 继续。
• `pi -r`：挑选特定 Session 恢复。
• `/clone`：完整复制当前 Session。
• `/fork`：基于某个节点创建新 Session，仅携带之前的历史。
• 对话树（Tree）：
• `/tree`：进入树状结构，可回退到历史节点并创建分支。
• 回退限制：树仅回退对话历史，不回退代码。代码回退需配合 Git（如 `git reset --hard`）。
• 总结选项：回退时可选择“不总结”、“自动总结”或“自定义总结”，总结仅针对当前分支，不影响其他分支。
• 上下文压缩：`/compact` 手动触发压缩，降低 Token 消耗；建议任务结束后直接 `/new` 以清空上下文，优于压缩。

🧩 插件系统与能力扩展

• 插件安装：
• 全局安装：默认安装到全局目录，对所有项目生效。
• 项目级安装：命令后加 `-l` (local)，仅对当前项目生效，减少无关项目的提示词负担。
• 核心插件功能：
• Pi Web Assist：零配置联网搜索，接入 XR MCP 服务，无需 API Key。
• Pi Subagents：并行运行多个子代理（如同时开发 5 个不同风格网页）。
• Pi MCP Adapter：通过 `.mcp.json` 配置 MCP Server（如高德地图）。
• BTW (By The Way)：旁路对话，在不打断主任务的情况下提问。
• Plan Mode：先生成计划文件供修改，确认后再执行。
• Go Mode：设定长期目标，多轮次迭代直至完成（如开发坦克大战游戏）。
• Dynamic Workflows：动态调度数十个子代理协同工作，类似 Claude Code 特性。
• WeChat Assistant：连接微信，实现手机端指令交互。

🛠️ Skills 技能与外部 UI

• Skills 协议：
• 项目级：放置于项目目录 `.agents/skills` 文件夹。
• 全局级：放置于用户 Home 目录 `.agents/skills` 文件夹。
• 示例：Playwright CLI（浏览器自动化）、Markdown Converter（文档转换）。
• 外部 Web UI：
• 社区项目提供网页版界面，支持切换项目、配置模型（如 Kimi）、管理 Skills 和插件。
• 支持在 UI 中直接截图粘贴、调整思考强度、查看 Token 消耗。
• 关闭浏览器后可通过命令重新启动 Web UI。

🧠 记忆机制与安全策略

• 跨 Session 记忆：
• 项目级：在项目根目录创建 `agents.md`，AI 每次对话自动读取，用于补充项目背景或用户偏好。
• 全局级：在 Pi 全局配置目录 `agents` 文件夹下创建 `agents.md`，对所有项目生效。
• 系统提示词追加：全局配置目录下 `AppendSystem.md`，优先级更高，用于强制安全规则（如禁止批量删除文件）。
• 安全机制：
• 信任机制：在包含插件/Skills 的陌生目录启动时询问是否信任。
• 无沙箱设计：Pi 默认拥有最高权限，无内置沙箱，旨在保持极简高效。
• 外部隔离方案：推荐在 WSL、Hyper-V、Docker 容器或 K8s 中运行，以隔离风险。
• 权限插件：可安装 Pi Permission System 插件，对敏感操作（如删除文件）进行弹窗审批。

📚 架构解析与 SDK 应用

• 源码架构：
• AI 包：统一模型调用接口。
• Agent 包：实现核心双层循环机制（内层处理工具调用，外层处理 Follow Up）。
• Coding Agent 包：定义 4 个基础工具、系统提示词及插件机制。
• TUI 包：实现命令行界面。
• SDK 集成：
• Pi AI SDK：`npm install` 后引用 `create model` 方法，可在任意项目中接入多种大模型。
• Pi Coding Agent SDK：提供开箱即用的 Coding Agent 能力，支持创建 Session 并下发任务。
• DIY 插件：Pi 内置插件开发知识，用户可通过自然语言指令让 AI 自行编写插件（如天气展示、文件保护、删除确认弹窗），并支持项目级或全局级部署。