# hey vs pi — 全面对比
> hey：Rust 单二进制 · 数据驱动扩展（配置工具/MCP/Skills）
> pi：Node/TS · 激进可扩展（TS 扩展/Skills/包生态）
> 本文基于 pi v0.x 官方文档（README + docs/）与 hey `DESIGN.md` v6（实现态，M1-M6 完成）实测比对。
## 1. 一句话定位
| **pi** | "minimal terminal coding harness，aggressively extensible"——内核极简，一切能力靠 TS 扩展与包生态按需生长 |
| **hey** | "可裁剪的个人 agent 内核"——内核极简，扩展走数据驱动（配置/MCP/Skills），Rust 单二进制嵌入式可用 |
两者内核哲学同源（都反对把功能堆进核心），分歧在**扩展的实现语言**与**安全模型**。
## 2. 架构总览
| 语言/运行时 | Rust，单二进制 | Node.js / TypeScript，npm 包 |
| 进程模型 | 单进程 | 单进程（另有 SDK 嵌入、RPC 外部集成） |
| 运行模式 | 交互 CLI + `--output json` + 库化 `hey::run` | 交互 TUI + `--print` + `--mode json` + `--mode rpc` + SDK |
| 代码规模 | ~10 文件（预估 3-5k 行） | 3 个子包（pi-ai / pi-agent-core / pi-tui）+ 大量模块 |
| 默认工具 | 5 个：bash/read_file/write_file/edit/grep | 7 个：read/bash/edit/write/grep/find/ls |
| 配置 | 单文件 TOML + env + CLI | 两层 JSON（全局/项目）+ env + CLI |
| 扩展 | 配置工具 + MCP + Skills（零代码） | TS 扩展 + Skills + Prompt Templates + Themes + Pi Packages |
## 3. 分维度对比
### 3.1 内核与哲学
| **相同** | 都宣称 minimal core；都反对内置 plan mode、sub-agents、to-dos（pi 明写，hey 未做）；都无内置沙箱 |
| **pi** | "Features that other tools bake in can be built with extensions"——核心可扩展性是第一原则，宁可缺功能也不内置 |
| **hey** | 核心只留循环 + 3 trait；扩展数据驱动，不引入语言级插件 |
**差异**：pi 把"缺功能"当卖点（用扩展补齐），hey 把"够用"当目标（MCP/Skills/压缩/会话直接内置）。
### 3.2 扩展机制（最大分歧点）
| 形式 | **TypeScript 模块**（registerTool/registerCommand/on(event)/registerProvider/registerShortcut/自定义 UI…） | 配置 JSON 工具 + MCP stdio + SKILL.md |
| 门槛 | 会写 TS | 会写 JSON/TOML |
| 表达力 | 无上限（可重写内置工具、做 sub-agents、做 SSH/sandbox 执行、做自定义压缩、做游戏…） | 命令模板为上限；复杂逻辑需回写 Rust |
| 分享 | Pi Packages（npm/git，`pi install`） | 拷目录（v1）；包分发未设计 |
| 版本兼容 | 插件与 pi 版本绑定，升级有断裂风险 | 无插件系统 = 无兼容问题 |
| 生态 | 有 npm 生态 + Discord 社区 | 无 |
**结论**：pi 的表达力完胜，hey 的门槛与稳定性完胜。hey 的"配置工具 + MCP"覆盖 80% 常见扩展诉求（加命令、接外部服务），剩下 20%（深度 UI、协议级定制）pi 才能做。
### 3.3 MCP（直接对立）
| **pi** | **明确 "No MCP"**（哲学）：认为 MCP 是不必要的抽象层，用"CLI 工具 + README（即 Skills）"替代；要 MCP 得自己写扩展 |
| **hey** | **MCP 是三大扩展通道之一**（v3 设计） |
**深析**：pi 的理由是 MCP 增加了一层协议/进程/维护成本，而 CLI 工具 + 文档本来就是 agent 生态最通用的接口；hey 的理由是 MCP 已成事实标准（CC/codex/opencode 全支持），一次接入可获得全部现成 MCP server 生态。
**建议**：hey 保留 MCP 但仅 stdio + tools 最小面（v3 已如此），同时保留"配置工具"通道 = 同时覆盖 pi 的 CLI 路线。两者不冲突，MCP 是加法不是替换。
### 3.4 权限与安全（第二分歧点）
| 权限弹窗 | **明确反对**："No permission popups"——本地 agent 本来就有全权限，弹窗是虚假安全感；安全靠容器（Gondolin/Docker/micro-VM） | **同款立场**：无弹窗；allow 列表（默认全权限，未匹配 blocked） |
| 项目信任 | **Project Trust**：加载项目级 settings/扩展/skills 前先问信任，存 `trust.json`；非交互模式用 `defaultProjectTrust` | 未设计 |
| 沙箱 | 无内置，文档化容器方案 | 无（v1 明确不做） |
**深析**：pi 的立场更"诚实"——本地 agent 无法真隔离，弹窗只是习惯性防线；hey 的 confirm 更"保守"——对不确定的命令多一道确认。两者都有理，但 **hey 缺 pi 的 Project Trust 是真实缺口**：加载项目 `.hey/skills` 或项目配置前不问信任，等于自动执行陌生仓库的指令。**建议 v2 吸收**。
### 3.5 Skills
| 标准 | 完整实现 **Agent Skills 标准**（frontmatter 校验、progressive disclosure、`/skill:name` 命令、多目录递归发现、跨 harness 复用 CC/codex skills） | 简化版：SKILL.md 扫描 + frontmatter（name/description 必填校验）+ 渐进披露 + `/skill:<name>` 查看 + 项目/全局两目录 |
| 细节 | 支持 `allowed-tools`、`disable-model-invocation`、license/compatibility 元数据、`/skill:name args` | 无（保持精简面） |
| 来源 | 全局 + 项目 + 包 + 设置 + CLI | 全局 + 项目两目录 |
**结论**：hey 的 Skills 已实现核心面（frontmatter 校验 + 渐进披露 + 自我进化闭环 M3 验证）；差距在元数据面（allowed-tools 等）与多目录发现——按需再补，不预埋。
### 3.6 会话管理
| 存储 | JSONL **树结构**（id+parentId，原地分支） | 线性 JSONL |
| 能力 | `/tree` 分支导航、`/fork`、`/clone`、`--fork`、`/export`、`/import`、`/share`（gist）、`-c`/`-r`/`--session` | `--resume <id>` / `--last` |
| 压缩 | 自动+手动 `/compact [指令]`，参数化（reserveTokens 16k / keepRecentTokens 20k），迭代摘要、保留边界追踪 | 裁剪（整对）+ 手动 `/compact` + resume「摘要+窗口」重建 + compress 工具 + nudge（M6 已消除"静默丢中间对"） |
**结论**：pi 的会话树是显著强项（分支不丢历史，压缩无损可回看）；hey 线性模型简单但压缩**有损摘要化**（旧消息压缩成摘要，文件保留原文可审计）。**建议 v2 吸收**：JSONL 加 parentId 字段即可支持 fork/clone，成本低；压缩参数化吸收 reserveTokens/keepRecentTokens。
### 3.7 TUI 与交互
| 编辑器 | @文件引用、Tab 路径补全、多行、外部编辑器、粘贴图片、`!cmd`/`!!cmd` | 无（纯流式 CLI） |
| 队列 | **steering/follow-up 消息队列**（Enter/Alt+Enter，工作中可插话） | 无 |
| 快捷键 | 全套 keybindings + 自定义 + `/hotkeys` | 无 |
| 主题 | dark/light + 自定义 + 热重载 | 无 |
| 扩展 UI | 组件/对话框/widget/status line/自定义编辑器 | 无（Output trait 预留） |
**结论**：这是 hey 与 pi 差距最大的一块（v1 无 TUI）。消息队列（工作中插话）是 pi 特有亮点，不只 UI 更是 agent 协作模型。
### 3.8 Provider 与模型
| 内置 | 30+（订阅：Anthropic/OpenAI/Codex/Copilot；API key：DeepSeek/Gemini/Groq/OpenRouter/xAI/智谱系…；llama.cpp 本地路由） | 1（OpenAI 兼容协议） |
| 自定义 | models.json 扩展协议（OpenAI/Anthropic/Google）+ 扩展级 custom provider（含 OAuth） | 改 base_url/api_key/model 三项配置 |
| 模型管理 | 模型目录、`--model provider/id:thinking`、thinking level（off~max）、`/model` 切换、scoped models | 无 |
**结论**：hey 的覆盖面靠"OpenAI 兼容端点"（DeepSeek/Kimi/通义/Ollama/vLLM 全覆盖），实际可用面 ≈ pi 的 API key 子集；但 pi 的订阅流（Claude Pro/ChatGPT Plus）、llama.cpp 路由、thinking level、OAuth 是 hey 没有的。**thinking level 建议 v2 作为可选参数透传**（兼容协议也支持部分）。
### 3.9 上下文与环境注入
| Context files | AGENTS.md/CLAUDE.md 多目录拼接 + override + SYSTEM.md/APPEND_SYSTEM.md | 未设计（v3 无） |
| bash 环境 | **注入 PI_SESSION_ID/PI_PROVIDER/PI_MODEL 等**到子进程 | 未设计 |
| 系统提示 | 可替换/追加 | 未设计 |
**结论**：hey 缺 Context files 与 bash 环境注入 —— 这两个成本低、价值高（AGENTS.md 是事实标准）。**建议 v2 吸收**：AGENTS.md 拼接 + `HEY_SESSION_ID` 等注入。
### 3.10 分发、性能、生态
| 分发 | `npm install -g` / curl 脚本；需 Node 环境 | `cargo build --release` 单二进制；零运行时依赖 |
| 启动/内存 | Node 冷启动 ~100ms+，内存 ~100MB+ | Rust 冷启动 ~10ms，内存 ~10MB |
| 生态 | npm pi-package + Discord + 已发布 sessions（HuggingFace） | 无 |
| 许可 | MIT | （未定，建议 MIT） |
## 4. 关键分歧小结（三处）
1. **扩展语言**：TS 代码（pi，表达力）vs 数据驱动（hey，门槛与稳定）——各自成立，hey 不追
2. **MCP**：pi 反对（哲学）vs hey 采用（生态）——hey 保持，MCP 是加法
3. **权限**：已对齐 pi 方式（M12）——默认全权限，allow 列表收紧，未匹配 blocked 回填模型，无交互弹窗——分歧已消除
## 5. 差距清单与吸收建议（按性价比排序）
| **高** | AGENTS.md 拼接 + SYSTEM.md 覆盖 | 低 | 对齐事实标准，项目指令可用 |
| **高** | bash 工具注入 `HEY_SESSION_ID` 等环境变量 | 极低 | 子进程可感知 agent 上下文 |
| **高** | Skills 对齐 Agent Skills 标准（frontmatter 校验） | 低 | 复用 Anthropic/pi skills 仓库 |
| **中** | 压缩参数化（reserve/keepRecent tokens） | 低 | 长会话体验提升 |
| **中** | 会话 JSONL 加 parentId（fork/clone 基础） | 低 | 分支能力，无损回看 |
| **中** | Project Trust（加载项目配置/skills 前询问） | 中 | 安全模型补上关键一环 |
| **低** | thinking level 透传 | ✅ 已实现（`--effort` 7 档枚举 + 各协议原生映射：OpenAI `reasoning_effort` 直通 / Anthropic adaptive `output_config.effort` / Google `thinkingLevel` 或 `thinkingBudget`） |
| **低** | 消息队列（工作中插话） | 中 | 交互模型升级，依赖 TUI |
| **低** | TUI（ratatui 只读展示版） | 高 | 观感追平 |
| 不做 | TS 扩展、包分发生态、会话树导航 UI、主题系统 | — | 违背定位/成本高 |
## 6. 结论
**pi 强在**：表达力（TS 扩展）、会话树、TUI/交互、Provider 广度、生态。
**hey 强在**：Rust 单二进制（启动/内存/分发）、扩展零门槛零版本地狱、代理一等公民、可库化嵌入。
**定位不冲突**：pi 是"终端里的瑞士军刀 + 平台"，hey 是"可嵌入的最小 agent 内核"。若目标是做一个自己的、能看懂全部代码、能塞进任何脚本/CI/编辑器插件的 agent，hey 的路线更对；若目标是终端内的极致体验和生态，pi 完胜。
**设计影响**：建议把上表"高优先 3 项 + 中优先 2 项"吸收进 v3（AGENTS.md、bash 环境注入、Skills 标准对齐、压缩参数化、会话 parentId），其余保持精简，不追平 pi。