GitHub Deep Dive · earendil-works/pi · packages/coding-agent

pi-coding-agent

Pi 是一个极简的终端编码 Harness——核心刻意留小，特性靠 Extensions / Skills / Prompt Templates / Themes 后置组装。"Adapt pi to your workflows, not the other way around。"四种运行模式（Interactive / Print / RPC / SDK）、4 个内置工具（read · write · edit · bash）、20+ LLM Provider，没有 MCP、没有 Sub-agents、没有权限弹窗、没有 Plan Mode——这些都交给 Extension。

运行模式 · interactive/print/rpc/sdk

内置工具 · read · write · edit · bash

20+

LLM Provider · 订阅/API/自定义

JSONL Tree

原生分支会话 · /tree /fork /clone

earendil-works / pi · packages/coding-agent

作者 Mario Zechner (badlogicgames) · npm: @earendil-works/pi-coding-agent · pi.dev

TypeScript Node ≥18 CLI npm · git package 极简核心 · 可插拔

Minimal

core

aggressive extensibility

■ 五层架构总览

pi 的源码按职责分成 5 层：入口分发 → 模式渲染 → Agent 核心 → 能力插件 → 持久化与设置。核心刻意最小化，复杂功能下推到 Extensions。

入口层 · Entry

解析 CLI 参数，选择模式与运行时（Node / Bun），加载会话或新建。

cli.ts bun/cli.ts cli/args.ts cli/session-picker.ts package-manager-cli.ts

▼

模式层 · Modes

同一个 Agent 内核，不同 UI：交互式 TUI、一次性 Print/JSON、stdio JSONL RPC、嵌入式 SDK。

modes/interactive modes/print-mode.ts modes/rpc core/sdk.ts

▼

Agent 核心 · Session Core

对话循环、上下文与工具调用编排、模型解析、System Prompt 组装、事件总线。pi 的大脑。

core/agent-session.ts agent-session-runtime agent-session-services system-prompt model-resolver event-bus

▼

能力层 · Tools · Extensions · Compaction

4 个内置工具、Extensions / Skills / Prompt Templates / Themes 的注册与运行、上下文压缩、HTML 导出。

core/tools/{bash,edit,read,...} core/extensions/loader.ts core/extensions/runner.ts core/compaction core/skills.ts core/export-html

▼

持久化与平台层 · Persistence

JSONL 树状会话存储、auth 凭证、用户/项目设置、模型注册表、Pi 包管理（npm / git 源安装）。

session-manager auth-storage settings-manager model-registry package-manager ~/.pi/agent

■ 文档导航

🚀

搭建 · 部署 · 使用

npm / curl 安装、Provider 认证、会话与分支、Compaction、Settings、上下文文件、CLI 参数与快捷键。

阅读 →

🏗️

架构 · 模块 · 文件结构

五层架构详解、src 树注解、Extension/Skill/Prompt/Theme 模型、Pi Packages、内置工具的边界。

阅读 →

⚡

运行时 · 状态机 · 流程

Agent 对话循环、四种模式启动差异、工具执行管线、Compaction 触发与算法、RPC JSONL 协议、Extension 生命周期。

阅读 →

■ 核心特性

🪶

极简内核 · 4 个工具

默认只给模型 read/write/edit/bash。其余能力靠 Extension 注册——核心不做大而全的承诺。

🧩

Extensions = 第一公民

TS 模块导出工厂函数即可注册自定义工具、命令、键位、事件钩子、UI 组件、Provider、Compaction 策略，甚至重写内置工具。

🌳

原生分支会话

JSONL 树（每条带 id/parentId）。/tree 任意跳点、/fork 切支、/clone 复制活分支，全部在同一文件内。

🔌

20+ LLM Provider

Anthropic / OpenAI / Gemini / Bedrock / Azure / Cerebras / Groq / xAI / OpenRouter ... 订阅、API Key、OAuth 三类接入；自定义 Provider 写一个 extension 即可。

📦

Pi Packages

把 Extensions / Skills / Prompts / Themes 打成 npm 或 git 包。pi install npm:@foo/pkg 或 git:github.com/u/r@v1，可项目内或全局安装。

🔄

智能 Compaction

长会话自动总结历史，分支感知（保留 active 路径）；/compact <指令> 手动触发。算法可被 Extension 完全替换。

🔁

四种运行模式

同一 Agent 核心：interactive 全屏 TUI、print 一次性输出、rpc JSONL stdio 协议、sdk 嵌入到你自己的 Node 进程。

📜

无 MCP · 无 Sub-agent · 无 Plan Mode

核心不内置这些"业界默认"。需要？写 Extension 或装一个 pi package。这是哲学，不是偷懒。

■ 设计哲学 · 刻意不做的事

"Pi 是激进可扩展的，所以它不强加任何工作流。" 下面这些功能其他工具默认带，pi 全部下放到 Extension 层——理由都在作者博客。

No MCP — 用 CLI 工具 + README（Skills 模式）替代；要 MCP 自己写 extension。

No Sub-agents — 用 tmux 起多 pi 进程，或者写 extension 实现你自己的版本。

No 权限弹窗 — 放进容器跑，或者写 extension 做与你环境匹配的确认流。

No Plan Mode — 把计划写到文件里，或者 extension 化。

No 内置 TODO — 作者认为会让模型分心。用 TODO.md，或者 extension。

No Background Bash — 用 tmux：可观测性更好，能直接交互。

■ 60 秒快速开始

macOS · Linux · Windows (Node ≥18)

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 用 Claude 订阅
pi
/login

# 或用 API Key
export ANTHROPIC_API_KEY=sk-ant-...
pi

安装后输入 pi 进入交互模式。完整 Provider 列表、Settings、Sessions、Compaction、Extensions 与 Pi Packages，请阅搭建与部署文档 →