设计哲学
Pi 的核心哲学是最小 core，扩展一切：
- 不内置 MCP 支持（可通过 Extension 自行实现）
- 不内置 sub-agents（用 tmux 或 Extension 实现）
- 不内置权限弹窗（容器化或 Extension 自定义）
- 不内置 plan mode（写文件或 Extension）
- 不内置 to-do 系统（用 TODO.md 文件或 Extension）
- 不内置 background bash（用 tmux）
“Pi is aggressively extensible so it doesn’t have to dictate your workflow.”
Monorepo 包结构
pi-mono/
├── packages/
│ ├── ai/ → @earendil-works/pi-ai 基础 LLM API 层
│ ├── agent/ → @earendil-works/pi-agent-core Agent 运行时
│ ├── coding-agent/ → @earendil-works/pi-coding-agent 编程 Agent CLI
│ ├── tui/ → @earendil-works/pi-tui 终端 UI 框架
│ └── orchestrator/ → @earendil-works/pi-orchestrator 编排层（实验性）
依赖层次
pi-coding-agent
├── pi-agent-core
│ └── pi-ai
└── pi-tui
pi-ai：最底层，纯 LLM Provider 抽象，零 Agent 概念pi-agent-core：构建在pi-ai上，添加状态、工具执行、事件流pi-tui：独立的 TUI 渲染框架，与 Agent 层解耦pi-coding-agent：最终用户产品，整合所有层 + CLI + 扩展系统
四种运行模式
| 模式 | 说明 |
|---|---|
| Interactive | 默认交互 TUI，全功能操作界面 |
Print (-p) | 非交互，输出后退出，可管道输入 |
JSON (--mode json) | 输出所有事件的 JSON lines |
RPC (--mode rpc) | stdin/stdout JSONL 协议，供外部进程集成 |
扩展体系
四种可插拔能力，均可打包为 pi-packages：
| 类型 | 描述 | 存放位置 |
|---|---|---|
| extensions | TypeScript 模块，注册工具/命令/UI | ~/.pi/agent/extensions/ |
| skills | Markdown 按需能力包 | ~/.pi/agent/skills/ |
| Prompt Templates | 可复用 Prompt，/name 展开 | ~/.pi/agent/prompts/ |
| Themes | 终端配色主题 | ~/.pi/agent/themes/ |
供应链安全
- 直接外部依赖锁定到精确版本（
save-exact=true） min-release-age=2避免同日依赖发布package-lock.json是依赖事实来源- 发布 CLI 包含
npm-shrinkwrap.json锁定传递依赖 - CI 使用
npm ci --ignore-scripts