pi 编码代理生态与源码开发环境 (pi Coding Agent Ecosystem and Source Dev Environment)

2026-09-18 暂无评论

2026-09-18 整理。背景：基于 pi 自建编码代理（自选插件、改源码）。本机 Windows + Node 24 + Bun 1.3 + gh CLI 已登录 connectedGraph。

生态地图

项目	仓库	定位
pi（上游）	`earendil-works/pi`	AI agent toolkit：统一 LLM API + agent loop + TUI + coding agent CLI。约 107k star。原名 `badlogic/pi-mono`
pi（自己的 fork）	`connectedGraph/pi`	上游 fork，用于改源码
oh-my-pi / omp	`can1357/oh-my-pi`	Pi 的重型 fork，"IDE wired in"。Rust core 约 80k 行、31 个内置工具、LSP/DAP。npm `@oh-my-pi/pi-coding-agent`，命令 `omp`。约 31.8k star
pi-msp	`connectedGraph/pi-msp`	把 pi 装进进程内 MSP 沙箱内核，见 Model Shell Protocol 与 pi-shell 沙箱内核 (MSP & pi-shell Sandbox Kernel)
PiDeck	`ayuayue/PiDeck`	Electron 桌面工作台：多项目管理 pi 会话、导入 Codex/Claude 会话、Git 集成、内置终端、插件管理。约 885 star
PI-Desktop	`vastsa/PI-Desktop`	Electron + Rust host core + pi Agent Harness + 可用户安装插件
pi-from-scratch	`SaladDay/pi-from-scratch`	600 行 TS 迷你 pi，用来看懂 agent 最小闭环
awesome-pi-agent	`qualisero/awesome-pi-agent`	生态清单（add-ons / hooks / tools / skills）
官方扩展	`earendil-works/pi-review`、`pi-review-loop`、`pi-transcribe`、`pi-chat`、`pi-tutorial`	官方维护的扩展样例

第三方扩展（GitHub topic:pi-extension）：

tintinweb/pi-subagents：Claude Code 式子代理与工作流编排，并行执行 + live widget
kenryu42/cc-safety-net：工具调用执行前拦截破坏性 git / 文件命令、敏感文件访问
MasuRii/pi-tool-display、MasuRii/pi-rtk-optimizer：TUI 工具输出压缩与 diff 可视化
tintinweb/pi-tasks、tintinweb/pi-gitnexus：任务追踪 / 知识图谱
fitchmultz/pi-cursor-sdk、pi-posthorse、pi-codex-goal：Cursor SDK 接入 / 无摘要上下文窗口 / 目标追踪
edgehero/pi-dispatch：把 pi 当服务跑（cron / GitHub issue 触发 + 队列 + 花费上限）

版本对照（2026-09-18 实测）

对象	本机 / fork	上游最新
`@earendil-works/pi-coding-agent`	0.84.2（全局 npm，命令 `pi`）	0.85.1
`@oh-my-pi/pi-coding-agent`	17.1.4（全局 npm，命令 `omp`）	18.2.5
`connectedGraph/pi` fork	落后 707 个提交	`earendil-works/pi` main

同步 fork（同源时是纯 fast-forward，安全）：

gh api repos/connectedGraph/pi/merge-upstream -X POST -f branch=main

判断快照新旧的正规做法：npm view <pkg> version dist-tags、gh api repos/<o>/<r>/compare/<base>...<head>。

源码开发环境

pi 是 npm workspaces 单仓多包：ai / agent / tui / coding-agent / protocol / client / server / chord / durable / session-backends / telemetry / evals。

git clone https://github.com/connectedGraph/pi      # 资产库副本
# 开发副本放到 git-workspace，remote 指回 fork，并加 upstream
npm install --ignore-scripts
npm run hydrate:model-data                          # 必需，见相关 pitfall

源码模式跑内置功能不需要 build：pi-test.sh / pi-test.ps1 用 tsx 直接跑 src/cli.ts。

但加载扩展（-e 或自动发现）必须先 npm run build。扩展路径会把 packages/coding-agent/src/main.ts 拉进模块图，它按包名导入 @earendil-works/pi-ai 等 workspace 包，解析到 node_modules/@earendil-works/pi-ai/dist/index.js；未构建时报：

Error [ERR_MODULE_NOT_FOUND]: Cannot find module
  '.../node_modules/@earendil-works/pi-ai/dist/index.js'
  imported from .../packages/coding-agent/src/main.ts

所以完整顺序是 npm install --ignore-scripts → npm run hydrate:model-data → npm run build。构建只需一次，之后改扩展源码可直接 /reload。

.\pi-test.ps1 --version                                             # → 0.85.1
.\pi-test.ps1 -p --no-session --provider deepseek --model deepseek-flash "Reply OK"

脚本	实际执行
`pi-test.sh`	`tsx packages/coding-agent/src/experimental/cli.ts`
`pi-test.ps1`	`tsx packages/coding-agent/src/cli.ts`，支持 `--no-env` 清空所有 provider 密钥

其他命令：npm run build（正式构建，含 generate-models）、npm run check（biome + 类型 + 依赖声明）、./test.sh（非 LLM 测试，无需 API key）。

扩展系统（插件机制）

扩展是 TypeScript 模块，由 jiti 直接加载，无需编译。

位置	作用域
`~/.pi/agent/extensions/.ts` 或 `/index.ts`	全局（所有项目）
`.pi/extensions/.ts` 或 `/index.ts`	项目级（项目需先 trusted）
`settings.json` 的 `packages` / `extensions`	显式 npm / git / 本地路径
`pi -e ./path.ts`	临时测试，可用 `/reload` 热重载

能力面：registerTool() 自定义工具、on() 事件拦截（可 block / 改写工具调用、注入上下文、自定义 compaction）、registerCommand() 斜杠命令、registerShortcut()、registerFlag()、ctx.ui（confirm / select / input / notify / custom TUI 组件）、appendEntry() 跨重启状态、自定义渲染。

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      if (!(await ctx.ui.confirm("Dangerous!", "Allow rm -rf?")))
        return { block: true, reason: "Blocked by user" };
    }
  });

  pi.registerTool({
    name: "greet",
    label: "Greet",
    description: "Greet someone by name",
    parameters: Type.Object({ name: Type.String() }),
    async execute(toolCallId, params) {
      return { content: [{ type: "text", text: `Hello, ${params.name}!` }], details: {} };
    },
  });
}

包分发：npm:@scope/pkg@1.0.0、git:github.com/user/repo@v1，用 pi install <source> 安装。安全边界：扩展具有完整系统权限，只装可信来源；项目级 .pi/extensions 仅在该项目被信任后加载。

二开与改品牌

packages/coding-agent/package.json：

{ "piConfig": { "configDir": ".pi" }, "bin": { "pi": "dist/bundle/cli.js" } }

改 name、configDir、bin 会影响 CLI banner、配置目录、环境变量名。

隔离注意：源码模式默认仍读写 ~/.pi/agent，与全局安装的 pi 共享认证、models.json、sessions、skills。自建 agent 必须换 configDir（如 .my-pi），否则两个实例互相覆盖配置。