pi-coder 扩展架构

底座是 pi 内核（@earendil-works/pi-coding-agent 0.87.1），30 个扩展全部通过同一套扩展 API 挂载 · 依据 docs/extensions.md 与源码实测
扩展层 · 30 个 工具渲染覆盖 · 5 bash-command-collapse read-path-collapse tool-diff thinking-collapse fenceless-code-block TUI 外观 · 7 statusline cwd-statusline startup-logo below-editor-after-statusline prompt-editor user-message-bar working-indicator 工作流 · 8 simple-task recap rewind init-command theme-command folder-history clear-command exit-command 模型与工具 · 10 plan-mode sandbox-boundary core-rules verify-loop memory background-tasks ask-user-question mcp auto-default-model subagent-log-guard 挂载 · 覆盖（同名工具先注册者整包接管） 扩展 API 接口面（pi loader 加载，全部扩展共用） registerTool ×18 registerCommand ×17 registerMessageRenderer ×2 registerMarkdownTransformer ×1 ctx.on(session_start | tool_call | input | …) ctx.ui.setHeader / setStatus / setWorkingMessage systemPromptOptions.sections appendEntry()（会话日志） 提供 pi 内核 · @earendil-works/pi-coding-agent 0.87.1 Node ≥ 22.19 · TypeScript 扩展 · 53 个 PI_* 环境开关 Agent 循环 turn / settle 边界 agent_before_settle 钩子 原生压缩 + 压缩前钩子 8 个内置工具 bash / powershell / read / edit write / grep / find / ls ExecOptions 无后台原语 会话存储 会话 JSONL 落盘 resume 分支投影 getBranch() pi-tui 组件库 Editor / Box / Container Markdown 渲染 · 差分渲染器 备用屏 包裹（仅 macOS） 操作系统 macOS seatbelt（sandbox-exec） bash 工具被包进 (deny file-write-unlink) 能力边界：删除收窄、写入不限；永不删除层由内核 deny 行兜底 Linux / 其他 无 sandbox-exec，删除边界自动关闭（PI_SANDBOX=off 语义），仅剩 AGENTS.md 纪律文本 工具渲染覆盖 5 TUI 外观 7 工作流 8 模型与工具 10

扩展间依赖 四条 import + 一个 globalThis 单例 + 一处刻意绕过

pi loader 不保证两个扩展共享模块实例，故权限模式单例挂在 globalThis；background-tasks 绕过删除边界的缺口写在工具描述里而非堵上。
plan-mode verify-loop recap simple-task sandbox-mode 单例（globalThis） bash-command-collapse/sandbox.ts + allowlist.ts（持久 allowlist） sandbox-boundary apply_patch 删除行 · tool_call 钩子 background-tasks 写 读 读 import import subagents.ts import gap.ts 绕过删除边界（已声明） import / 读写 绕过删除边界 删除边界（seatbelt 两半） 运行时状态单例 边界外执行

旁挂配套包（npm 独立安装）

pi-subagents 0.72.1 子代理 + watchdog 双模型审查 + 三预算 + workflowScript 编排；recap / verify-loop / subagent-log-guard 与之配合 pi-web-access 0.32.0 web 检索工具

主题（3）

pi-coder-1337 默认，移植自 Codex CLI 内置 1337 pi-coder-catppuccin 含 tool-diff 自定义底色 token pi-coder-ayu vars 只留 slot 仍引用的条目

全局配置（config/）

AGENTS.md 28KB 全局纪律，注入 system prompt 的 project_context 段 AGENTS.core.md 7KB 蒸馏核心，由 core-rules/ 按 hash diff 重注入

行为开关

53 个 PI_* 环境变量 未设置 = 开，off = 关；全表见 docs/extensions.md「Environment switches」