pi-vs-cc

一个包含 Pi 编码代理 自定义实例的集合。为什么？ 为了展示如何在代理式编码市场中，针对领导者 Claude Code 进行风险对冲。在这里，我们展示了如何自定义 UI、代理编排工具、安全审计以及跨代理集成。

观看视频，了解 Pi 的实际运行效果。

---

先决条件

以下三项均为必需：

工具	用途	安装
Bun ≥ 1.3.2	运行时与包管理器	bun.sh
just	任务运行器	brew install just
pi	Pi 编码代理 CLI	Pi 文档

---

API 密钥

Pi 不会自动加载 .env 文件 — API 密钥必须在启动 Pi 之前存在于您的 shell 环境中。我们提供了一个示例文件：

cp .env.sample .env   # 复制模板文件
# 打开 .env 并填写您的密钥

.env.sample 覆盖了四个最常用的提供商：

提供商	变量	获取您的密钥
OpenAI	OPENAI_API_KEY	platform.openai.com
Anthropic	ANTHROPIC_API_KEY	console.anthropic.com
Google	GEMINI_API_KEY	aistudio.google.com
OpenRouter	OPENROUTER_API_KEY	openrouter.ai
许许多多其他	***	Pi 提供商文档

加载您的密钥

根据您的工作流程选择合适的方式：

选项 A — 每次会话手动加载：

source .env && pi

选项 B — 一行别名（添加到 ~/.zshrc 或 ~/.bashrc）：

alias pi='source $(pwd)/.env && pi'

选项 C — 使用 just 任务运行器（通过 set dotenv-load 自动连接）：

just pi           # 每个 just 任务都会自动加载 .env
just ext-minimal  # 对所有任务有效，而不仅仅是 `pi`

---

安装

bun install

---

扩展

扩展	文件	描述
pure-focus	extensions/pure-focus.ts	完全移除页脚栏和状态栏 — 纯粹的无干扰模式
minimal	extensions/minimal.ts	紧凑型页脚，显示模型名称和 10 格的上下文使用情况指示器 [###-------] 30%
cross-agent	extensions/cross-agent.ts	扫描 .claude/、.gemini/、.codex/ 目录中的命令、技能和代理，并将它们注册到 Pi
purpose-gate	extensions/purpose-gate.ts	启动时提示您声明会话意图；显示一个持久的目的小部件，并阻止后续提示直到您回答
tool-counter	extensions/tool-counter.ts	丰富的两行页脚：第一行显示模型 + 上下文指示器 + 令牌/费用统计；第二行显示当前目录/分支以及每个工具的调用次数统计
tool-counter-widget	extensions/tool-counter-widget.ts	编辑器上方的实时更新小部件，显示每个工具的调用次数，并以不同颜色背景区分
subagent-widget	extensions/subagent-widget.ts	/sub <task> 命令会启动后台 Pi 子代理；每个子代理都有自己的流式进度小部件
tilldone	extensions/tilldone.ts	任务纪律系统 — 在开始工作前定义任务；跟踪各步骤的完成状态；在页脚显示持久的任务列表及实时进度
agent-team	extensions/agent-team.ts	仅调度员式的编排器：主代理通过 dispatch_agent 将所有工作委派给指定的专业代理；显示网格仪表板
system-select	extensions/system-select.ts	/system 命令用于交互式地在代理角色/系统提示之间切换，这些角色/提示来自 .pi/agents/、.claude/agents/、.gemini/agents/ 和 .codex/agents/
damage-control	extensions/damage-control.ts	实时安全审计 — 拦截危险的 bash 脚本模式，并强制执行来自 .pi/damage-control-rules.yaml 的基于路径的访问控制
agent-chain	extensions/agent-chain.ts	顺序流水线编排器 — 将多个代理串联起来，每一步的输出作为下一步的输入；使用 /chain 来选择并运行
pi-pi	extensions/pi-pi.ts	元代理，利用并行研究专家为文档构建 Pi 代理
session-replay	extensions/session-replay.ts	可滚动的时间轴叠加层，展示会话历史记录——突出可定制的对话 UI
theme-cycler	extensions/theme-cycler.ts	使用键盘快捷键（Ctrl+X/Ctrl+Q）和 /theme 命令，在自定义主题之间循环切换

---

使用方法

运行单个扩展

pi -e extensions/<name>.ts

堆叠多个扩展

扩展可以组合使用——通过传递多个 -e 标志：

pi -e extensions/minimal.ts -e extensions/cross-agent.ts

使用 just 任务

just 封装了最常用的任务组合。运行不带参数的 just 即可列出所有可用任务：

just

常见任务：

just pi                     # 纯净版 Pi，无扩展
just ext-pure-focus         # 无干扰模式
just ext-minimal            # 极简上下文计量器页脚
just ext-cross-agent        # 跨代理命令加载 + 极简页脚
just ext-purpose-gate       # 目的门控 + 极简页脚
just ext-tool-counter       # 丰富的两行页脚，包含工具计数
just ext-tool-counter-widget # 编辑器上方的各工具小部件
just ext-subagent-widget    # 子代理启动器，带有实时进度小部件
just ext-tilldone           # 任务纪律系统，支持实时进度跟踪
just ext-agent-team         # 多代理编排网格仪表板
just ext-system-select      # 通过 `/system` 命令切换代理人格
just ext-damage-control     # 安全审计 + 极简页脚
just ext-agent-chain        # 顺序流水线编排器，支持步骤串联
just ext-pi-pi              # 元代理，利用并行专家构建 Pi 代理
just ext-session-replay     # 会话历史滚动时间轴叠加层
just ext-theme-cycler       # 主题循环器 + 极简页脚
just all                    # 在各自终端窗口中打开所有扩展

open 任务允许你启动一个新终端窗口，并加载任意组合的堆叠扩展（省略 .ts 后缀）：

just open purpose-gate minimal tool-counter-widget

---

项目结构

pi-vs-cc/
├── extensions/          # Pi 扩展源文件（.ts）——每个扩展对应一个文件
├── specs/               # 扩展的功能规范
├── .pi/
│   ├── agent-sessions/  # 临时会话文件（被 git 忽略）
│   ├── agents/          # 团队和链式扩展中的代理定义
│   │   ├── pi-pi/       # 用于 pi-pi 元代理的专家代理
│   │   ├── agent-chain.yaml # 链式代理的流水线定义
│   │   ├── teams.yaml   # 团队代理的团队定义
│   │   └── *.md         # 各个代理的人格/系统提示
│   ├── skills/          # 自定义技能
│   ├── themes/          # 自定义主题（.json），由主题循环器使用
│   ├── damage-control-rules.yaml # 安全审计的路径/命令规则
│   └── settings.json    # Pi 工作空间设置
├── justfile             # just 任务定义
├── CLAUDE.md            # 规范与工具参考（供代理使用）
├── THEME.md             # 扩展作者使用的颜色标记规范
└── TOOLS.md             # 扩展中可用的内置工具函数签名

---

多代理工作流编排

Pi 的架构使得协调多个自主代理变得十分容易。这个实验环境包含了几个强大的多代理扩展：

子代理小部件 (/sub)

subagent-widget 扩展允许你在主终端继续工作的同时，将独立的任务卸载到后台的 Pi 代理上执行。输入 /sub <task> 就会启动一个无头子代理，它会通过编辑器上方的一个持久、实时更新的 UI 小部件报告其执行进度。

代理团队 (/team)

agent-team 编排器充当调度员的角色。主代理不会直接回答你的请求，而是先审查你的需求，从预定义的名单中选择一位专家，并通过 dispatch_agent 工具将任务委派出去。

• 团队配置在 .pi/agents/teams.yaml 中，每个顶级键代表一个团队名称，其中包含一组代理名称（例如：frontend: [planner, builder, bowser]）。
• 各个代理的人格描述文件（如 builder.md、reviewer.md）位于 .pi/agents/ 目录下。
• pi-pi 元代理：pi-pi 团队专门将任务委派给位于 .pi/agents/pi-pi/ 的 Pi 框架专家（如 ext-expert.md、theme-expert.md、tui-expert.md），这些专家通过并行研究构建高质量的 Pi 扩展。
  • 网页爬取备用方案：为了动态获取最新的框架文档，这些专家默认使用 firecrawl 作为现代页面爬虫，但如果 Firecrawl 失败或不可用，他们会安全地回退到内置在 bash 工具集中的原生 curl。

代理链 (/chain)

与动态调度器不同，agent-chain 是一个顺序流水线编排器。工作流定义在 .pi/agents/agent-chain.yaml 中，其中前一个代理的输出会成为下一个代理的输入（$INPUT）。

• 工作流以一系列 steps 列表的形式定义，每一步都指定一个 agent 和一个 prompt。
• 变量 $INPUT 会注入上一步的输出（或者对于第一步是用户的初始提示），而 $ORIGINAL 始终包含用户最初的提示。
• 示例：plan-build-review 流水线会将你的提示交给 planner，再将计划传递给 builder，最后把代码发送给 reviewer。

---

安全审计与损害控制

damage-control 扩展提供了实时的安全钩子，用于防止代理在执行 bash 命令或修改文件时发生灾难性错误。它利用 Pi 的 tool_call 事件来拦截并根据 .pi/damage-control-rules.yaml 对每一项操作进行评估。

• 危险命令：使用正则表达式（bashToolPatterns）阻止破坏性命令，如 rm -rf、git reset --hard、aws s3 rm --recursive 或 DROP DATABASE。有些规则会严格禁止执行，而另一些规则（ask: true）则会暂停执行，等待你确认。
• 零访问路径：防止代理读取或写入敏感文件（如 .env、~/.ssh/、*.pem）。
• 只读路径：允许读取，但禁止修改系统文件或锁文件（package-lock.json、/etc/）。
• 禁止删除路径：允许修改，但禁止删除关键项目配置文件（.git/、Dockerfile、README.md）。

---

扩展作者参考

配套文档涵盖了本仓库中所有扩展所遵循的规范：

• COMPARISON.md — Claude Code 与 Pi Agent 在 12 个类别上的逐项比较（设计哲学、工具、钩子、SDK、企业级等）。
• PI_VS_OPEN_CODE.md — Pi Agent 与 OpenCode（Claude Code 的开源替代品）的架构对比，重点在于扩展能力、事件生命周期和 UI 自定义。
• RESERVED_KEYS.md — Pi 的保留键位、可重写键位以及对扩展作者安全的键位。
• THEME.md — 颜色语言：哪些 Pi 主题标记（success、accent、warning、dim、muted）对应哪些 UI 角色，并附有示例。
• TOOLS.md — 扩展内部可用的内置工具函数签名（read、bash、edit、write）。

钩子与事件

Claude Code 与 Pi Agent 中生命周期钩子的并列比较。

类别	Claude Code	Pi Agent	可用平台
会话	SessionStart, SessionEnd	session_start, session_shutdown	两者
输入	UserPromptSubmit	input	两者
工具	PreToolUse, PostToolUse, PostToolUseFailure	tool_call, tool_result, tool_execution_start, tool_execution_update, tool_execution_end	两者
Bash	—	BashSpawnHook, user_bash	Pi
权限	PermissionRequest	—	CC
压缩	PreCompact	session_before_compact, session_compact	两者
分支	—	session_before_fork, session_fork, session_before_switch, session_switch, session_before_tree, session_tree	Pi
代理/回合	—	before_agent_start, agent_start, agent_end, turn_start, turn_end	Pi
消息	—	message_start, message_update, message_end	Pi
模型/上下文	—	model_select, context	Pi
子代理	SubagentStart, SubagentStop, TeammateIdle, TaskCompleted	—	CC
配置	ConfigChange	—	CC
工作树	WorktreeCreate, WorktreeRemove	—	CC
系统	Stop, Notification	—	CC

资源

Pi 文档

文档	描述
Mario 的 Twitter	Pi 编码代理的创建者
README.md	概述及入门指南
sdk.md	TypeScript SDK 参考文档
rpc.md	RPC 协议规范
json.md	JSON 事件流格式
providers.md	API 密钥与提供商设置
models.md	自定义模型（Ollama、vLLM 等）
extensions.md	扩展系统
skills.md	技能（Agent Skills 标准）
settings.md	配置
compaction.md	上下文压缩

主导型智能体编码

为软件工程的未来做好准备

通过 Tactical Agentic Coding 学习战术性智能体编码模式。

关注 IndyDevDan YouTube 频道，提升你的智能体编码优势。

pi-vs-claude-code 快速上手指南

pi-vs-claude-code 是一个基于 Pi Coding Agent 的定制实例集合。它旨在展示如何通过自定义 UI、智能体编排工具、安全审计以及跨智能体集成，来构建可与市场领导者 Claude Code 相媲美的编程助手。

环境准备

在开始之前，请确保您的系统已安装以下三个必要工具：

工具	用途	安装方式
Bun (≥ 1.3.2)	运行时与包管理器	访问 bun.sh 安装
just	任务运行器	macOS: brew install just Linux/其他：参考 just 官网
pi	Pi Coding Agent CLI	参考 Pi 官方文档 安装

注意：国内用户若无法直接访问 Bun 或 GitHub 源，建议配置相应的国内镜像加速。

安装步骤

1. 克隆项目并安装依赖

   在项目根目录下执行以下命令安装 Node.js/Bun 依赖：

   bun install
   

2. 配置 API Keys

   Pi 不会自动加载 .env 文件，必须在启动前将密钥导出到当前 Shell 环境中。

   • 复制示例配置文件：

     cp .env.sample .env
     

   • 编辑 .env 文件，填入您的 API 密钥（支持 OpenAI, Anthropic, Google, OpenRouter 等）：

     # 使用您喜欢的编辑器打开
     code .env 
     # 或
     vim .env
     

3. 加载环境变量

   选择以下任一方式加载密钥：

   • 方式 A（手动加载，推荐新手）：

     source .env && pi
     

   • 方式 B（设置别名，永久生效）： 将以下内容添加到 ~/.zshrc 或 ~/.bashrc：

     alias pi='source $(pwd)/.env && pi'
     

   • 方式 C（使用 just 工具）： just 会自动处理环境变量加载（见下文用法）。

基本使用

本项目提供了多种扩展（Extensions）来增强 Pi 的功能，您可以单独运行或组合使用。

1. 运行单个扩展

使用 -e 标志指定扩展文件：

pi -e extensions/minimal.ts

示例：启动带有简洁上下文用量计数的底部栏模式。

2. 组合多个扩展

可以传递多个 -e 参数来堆叠功能：

pi -e extensions/minimal.ts -e extensions/cross-agent.ts

示例：同时启用简洁底部栏和跨智能体命令加载（自动识别 .claude/, .gemini/ 等目录下的配置）。

3. 使用 Just 快捷命令（推荐）

项目内置了 justfile，封装了常用的扩展组合。输入 just 查看所有可用命令：

just

常用场景示例：

• 纯净模式（无干扰）：

  just ext-pure-focus
  

• 安全审计模式（拦截危险命令）：

  just ext-damage-control
  

• 多智能体协作（团队模式）：

  just ext-agent-team
  

• 任务纪律系统（定义并追踪任务）：

  just ext-tilldone
  

• 一次性打开所有扩展演示（每个扩展一个终端窗口）：

  just all
  

4. 高级功能速览

• 子智能体 (/sub)：在主终端工作时，输入 /sub <任务> 可在后台启动独立的 Pi 子智能体处理任务，并实时显示进度组件。
• 智能体链 (/chain)：通过 /chain 命令运行预定义的顺序工作流（如：规划 -> 编码 -> 审查），上一步的输出会自动作为下一步的输入。
• 切换角色 (/system)：使用 /system 命令交互式地切换不同的智能体人设（System Prompts）。

现在，您可以尝试运行 just ext-minimal 开始您的第一个定制化 Pi 会话了！