4.Agent开发框架

企业级Agent产品

1.产品形态

市面上的 Agent 产品形态包括：

1. 功能型：在传统应用中添加ai助手、widget等功能，内部本质就是一性次的ai大模型调用。
2. 工作流：通过工作流编排，实现原本不好实现的业务功能。agent充当复杂逻辑的处理者。高级一些的工作流，是通过skills等方式将流程给到agent，agent根据流程自行编排任务。
3. 纯粹agent：通过chat界面，内部集成大量工具、mcp、skills等，帮助用户实现复杂的业务逻辑。

2.实现方案

1. 最底层的是：基于LangChain或者LangGraph的实现。简单功能实现简单，复杂功能实现复杂。
2. 中层的是：基于DeepAgent或者AgentScope的实现。类似于脚手架，任需开发大量业务逻辑和基础功能。
3. 最高层的是：基于Pi、Claude Code、OpenCode的实现。开箱即用，只需控制好权限、上下文、工具调用等即可。

3.为什么会选择cc等工具

为什么公司自研 Agent 都在用 Claude Code、pi、OpenCode 做底座？

本质是一套分工逻辑：模型层不赚钱也难差异化，真正决定 Agent 上限的是"模型外的工程层"，而这些工具恰好把这层最难啃的部分（工具调用、上下文管理、执行循环、权限沙箱）做完了。

企业基于它们做二次开发，只需要叠加业务工具链和权限体系，就能把原型到生产的周期从数月压缩到数周。

先厘清一个关键概念：Agent Harness

2025–2026 年行业的一个共识正在收敛：竞争焦点从"谁的模型强"转向了"谁的 harness 好"。 Coinbase（Forge）、Shopify（River）、Ramp（Inspect）都自研了内部编码 Agent，但没有一家试图重写底层模型，而是自研 harness——即负责上下文注入、权限审批、工具调度、结果验证的那一层。 LangChain 后来开源的 Open SWE 就是对这套在 Stripe、Ramp、Coinbase 内部已经跑通的模式的公开复刻。

Anthropic 自己也把这条边界挑明了：Claude Code 的 harness（Claude Agent SDK）可以驱动任何类型的 Agent， Anthropic 内部用它跑深度研究、视频生成、笔记等所有非编码场景。

为什么是这三款工具，而不是 LangChain 那类框架？

一个容易被忽视的原因：这三款工具都是"先在真实终端工作流里被验证过的产品"，而不是"为做 Agent 而设计的框架"。 Claude Code 是 Anthropic 内部先用起来的，pi 的作者 Mario Zechner 是 libGDX 的创造者，OpenCode 背后是 SST 这样有多年工程化交付经验的团队。 它们的工具调用 schema、bash 执行语义、错误恢复逻辑，都是被真实开发者日常敲打过的，而不是设计文档里推演出来的。

另一层是成本与锁定规避。有分析直接指出：模型层正在收敛、可替换性最强，真正的粘性在工具集成和遥测上——把 prompt、eval、遥测建立在一个可插拔的 harness 上， 等市场定价变化时可以随时切到更便宜的选项。 Claude Code 给企业的是"调优到极致的 Claude 循环"，pi 和 OpenCode 给的是"模型无关的白盒底座"，三者正好覆盖了"要极致效果"和"要完全自主"两端的需求谱系。

4.Claude Code、pi、OpenCode 三款 Agent 工具全维度对比

1. Claude Code 是 Anthropic 官方的"结构化工作流引擎"——闭源但调优到极致，深度绑定 Claude 模型；
2. OpenCode 是 SST 的"全栈开放标准产品"——多端覆盖、75+ 提供商、工程完整度最高，适合产品化交付；
3. pi 是 badlogic 的"极简可插拔内核"——原语最少、可改写性最强，适合深度自研；

4.1 模块卡片：各工具的核心差异点

Claude Code — 为"即刻能用"而生：优势在于开箱即用和模型协同优化：43 个工具的 schema、bash 执行语义、错误恢复全部经过 Anthropic 内部打磨， sub-agent 并行（可同时编排 15 个）、自动 Compaction、Hooks/Skills/MCP 形成完整闭环。劣势是闭源 + 绑死 Claude 生态， 模型不可替换、不能改内核，扩展点虽然多但嵌在官方循环里"只能接上去、很难改里面"。适合个人开发者和不想折腾工程的团队。

pi — 为"彻底掌控"而生：核心理念是"原语而非特性"：子代理、Plan Mode、权限门禁、路径保护、SSH、沙箱、MCP 这些其他 Agent 硬编码的东西， 在 pi 里全部通过扩展实现，官方提供 50+ 示例包。 独有的树形会话结构（/tree 切换任意分支、/share 导出可分享 URL）和四种运行模式（含 stdin/stdout JSON RPC）让它特别适合被嵌入其他系统。 缺点是上手曲线陡——工作流全部自己搭，TypeScript 工程能力是硬门槛。

OpenCode — 为"工程交付"而生：Client/Server 分离是它的招牌：核心引擎作为服务端运行，TUI/Web/Desktop 全是客户端，opencode serve 暴露 REST 接口供外部调用。 MCP（外部工具）+ ACP（自身可被调用）+ LSP 三协议原生支持，对需要把 Agent 接入 CI/CD、Slack、内部平台的企业是直接可用的标准件。 75+ Provider（含本地模型）让它成为三款中模型自由度最高的选择。缺点是底层循环不如 Claude Code 那样经过极限调优。

4.2 分场景选型建议

• 个人开发者 / 想立刻提升编码效率：Claude Code。订阅即用，调优好的工作流，工程摩擦最小。
• 创业团队 / 快速搭建业务 Agent 原型：OpenCode。多端覆盖 + 多模型路由 + Server 模式让它像可交付的产品，平台团队只需补权限和审计的胶水层。
• 大企业 / 平台工程团队做长期 Agent 自研：pi。如果 Agent 被定位为未来 3-5 年的平台能力，需要在消息送达模型前后、工具调用前后、权限弹窗这些环节全部植入自家逻辑，pi 的 Extension API 是比另外两者更彻底的抓手。
• 编码场景优先 / 追求单任务效果和 token 效率：pi。Composio 100 小时实测里 pi 的"raw results"反而最优，代价是要接受工程自建的负担。
• 需要 Agent 被外部系统调用 / 跨系统集成：OpenCode。ACP 协议让它天然可作为服务端被其他系统调用，这在三者中是独有的。

5.构建 Agent 应用注意事项速查表

一句话总结：这三款工具都把 harness 搭好了，但沙箱、权限、eval、可观测性这四道生产闸门没有一款会替你装——建议先在非关键业务上跑真实 PoC， 让成本账单和故障日志决定优先填哪些坑。

所以上生产要自己写 harness，就控三件事：

1. 可观测：每一步输入输出全摊开，能插桩拦截。
2. 成本：分层压缩上下文，保住缓存命中率。
3. 调度：管好并发、串行和超时中断。

LangChain

• 官网：https://www.langchain.com/
• 国内文档：https://docs.langchain.org.cn/
  • 包括 LangChain、LangGraph、LangSmith、Deep Agents 等。

LangChain 1.0 是全新大版本，API 完全重构。

LangChain 是代理工程平台。Replit、Clay、Rippling、Cloudflare、Workday 等 AI 团队用 LangChain 工程化可靠的代理。

1. LangChain：代理基于 LangGraph 构建，提供持久执行、流式处理、人工干预、持久性等功能，LangChain 提供更灵活自主的程序。
2. LangGraph：通过低级编排、内存和人机协作支持控制自定义代理的每一步。
3. LangSmith：帮助 AI 团队利用实时生产数据持续测试和改进的平台。
   • 可观测性：详细追踪和聚合趋势指标，了解代理如何思考和行动。
   • 评估：对生产数据和离线数据集上的代理行为测试和评分。
   • 部署：为长时间运行任务构建的可扩展基础设施，一键发布代理。

安装

# langchain 核心
pip install -U langchain

# LangChain 提供与数百个 LLM 和数千个集成的独立提供商包
pip install -U langchain-deepseek
pip install -U langchain-openai
pip install -U langchain-anthropic

核心组件

模型

LLM 能像人一样解释和生成文本，可撰写内容、翻译语言、总结和回答问题，无需针对每个任务专门训练。

除文本生成外，许多模型还支持：

1. 工具调用 - 调用外部工具（如数据库查询或 API 调用）并在响应中使用结果。
2. 结构化输出 - 模型响应被限制为遵循定义的格式。
3. 多模态 - 处理和返回除文本之外的数据，如图像、音频和视频。
4. 推理 - 模型执行多步推理以得出结论。

LangChain 提供：动态模型、工具调用、输出格式化、多模态、提示缓存、限流、URL 代理、日志概率、token 用量、调用配置（用 LangSmith 监控调试、日志监控、资源使用等）。

消息

消息是包含以下内容的对象：

1. 角色 - 识别消息类型（如 system、user）
2. 内容 - 表示消息的实际内容（如文本、图像、音频、文档等）
3. 元数据 - 可选字段，如响应信息、消息 ID 和令牌使用情况

工具

工具是 LangChain 调用并执行操作的组件。工作流程：

1. 通过模型明确的输入和输出。
2. LangChain 工具封装一个可调用函数及其输入模式，传递给兼容的聊天模型，模型决定是否调用工具及使用哪些参数。
3. 工具调用使模型能生成符合指定输入模式的请求。

访问上下文：工具通过 ToolRuntime 参数访问运行时信息。

1. 上下文：通过 runtime.context 访问不可变配置和上下文数据，如用户 ID、会话详细信息或应用配置。
2. 内存（存储）：用存储跨对话访问持久数据。通过 runtime.store 访问，保存和检索用户特定或应用特定数据。
3. 流写入器：用 runtime.stream_writer 在工具执行时流式传输自定义更新。向用户提供工具正在做什么的实时反馈。

记忆

记忆上下文，包括内存、Redis、数据库等。

流式

LangChain 流式传输功能：

1. 流式传输 agent 进度 - 在每个 agent 步骤之后获取状态更新。
2. 流式传输 LLM Tokens - 在语言模型生成 token 时流式传输。
3. 流式传输自定义更新 - 发送用户定义的信号（如"已获取 10/100 条记录"）。
4. 流式传输多种模式 - 从 updates（agent 进度）、messages（LLM token + 元数据）或 custom（任意用户数据）中选择。

中间件

中间件用途：

1. 监控：用日志、分析和调试跟踪代理行为。
2. 修改：转换提示、工具选择和输出格式。
3. 控制：添加重试、回退和提前终止逻辑。
4. 强制执行：应用速率限制、防护栏和 PII 检测。

LangChain 内置中间件：

1. 总结：接近令牌限制时自动总结对话历史。SummarizationMiddleware。
2. 人工干预：在工具调用执行前暂停代理，进行人工批准、编辑或拒绝。
3. Anthropic 提示缓存：通过 Anthropic 模型缓存重复提示前缀降低成本。
4. 模型调用限制：限制模型调用次数，防止无限循环或过高成本。
5. 工具调用限制：限制特定工具或所有工具的调用次数。
6. 模型回退：主模型失败时自动回退到备用模型。
7. PII 检测：检测和处理对话中的个人身份信息。
8. 规划：为复杂多步骤任务添加待办事项列表管理。
9. LLM 工具选择器：调用主模型前用 LLM 智能选择相关工具。
10. 工具重试：自动重试失败的工具调用，可配置指数退避。
11. LLM 工具模拟器：用 LLM 模拟工具执行进行测试，用 AI 生成响应替换实际工具调用。
12. 上下文编辑：通过修剪、总结或清除工具使用管理对话上下文。

自定义中间件：通过实现代理执行流程中特定点的钩子构建。方式：

1. 基于装饰器 - 适合单钩子中间件，快速简单。
2. 基于类 - 适合多钩子复杂中间件，功能更强。

结构化输出

响应格式控制代理如何返回结构化数据：

1. ToolStrategy[StructuredResponseT]：用工具调用做结构化输出。
2. ProviderStrategy[StructuredResponseT]：用提供商原生结构化输出。
3. type[StructuredResponseT]：架构类型，根据模型能力自动选最佳策略。
4. None：无结构化输出。

最佳实践

安全防护

在代理执行关键点验证和过滤内容，构建安全合规应用。常见用例：

1. 防止 PII 泄漏。对电子邮件、信用卡、IP、Mac、url 等脱敏，策略包括编辑、掩码、哈希、阻止等。
2. 检测并阻止提示注入攻击。
3. 阻止不适当或有害内容。
4. 强制执行业务规则和合规要求。
5. 验证输出质量和准确性。

实现：通过中间件在关键节点（agent 执行前后、工具调用前后）拦截处理。

MCP

模型上下文协议（MCP）是开放协议，标准化应用程序向 LLM 提供工具和上下文的方式。通过 @mcp.tool 自定义 MCP 服务。

pip install langchain-mcp-adapters

multi-agent

agent 间协同完成复杂任务，通过工具调用或控制权交接实现任务执行。实现原理是主 agent 控制各子 agent 执行。

核心是上下文工程，需控制：

1. 对话或状态的哪些部分传递给每个智能体。
2. 为子智能体量身定制的专用提示。
3. 包含/排除中间推理。
4. 为每个智能体定制输入/输出格式。

检索-RAG

Studio

Studio 是 LangChain 提供的免费代理 IDE，与 LangSmith 集成，实现跟踪、评估和提示工程。精确查看代理如何思考，跟踪每个决策，发布更智能可靠的代理。

集成测试

LangChain 的 AgentEvals 通过执行轨迹匹配或 LLM 判断器评估智能体轨迹（确切消息序列，含工具调用）。

pip install agentevals

1. 轨迹匹配评估器：create_trajectory_match_evaluator 将智能体轨迹与参考轨迹匹配。
2. LLM-as-Judge 评估器：用 LLM 和 create_trajectory_llm_as_judge 评估执行路径。不需要参考轨迹，但可用时可以提供。
3. 异步支持：所有 agentevals 评估器支持 Python asyncio。工厂函数评估器在函数名 create_ 后加 async 获得异步版本。

LangSmith 集成

将评估器结果记录到 LangSmith，跟踪随时间变化的实验。LangSmith 提供两种评估方法：pytest 集成和 evaluate 函数。

LangGraph

LangGraph 是构建、管理和部署长时间运行、有状态智能体的低级编排框架和运行时。Klarna、Replit、Elastic 等公司在用。

LangGraph 非常低级，专注智能体编排，普遍用 LangChain 组件集成模型和工具。专注对智能体编排至关重要的底层功能：持久执行、流式传输、人机协作等。

AgentScope

AgentScope 是阿里达摩院推出的开源 AI Agent 框架，有 Python 和 Java 两版。 Python 版主打生产级多 Agent 应用的可观测性（"可见、可懂、可信"）；Java 版专为 Java 17+ 生态打造，解决类型安全、生产可控性、生态集成需求。

• 官网：https://agentscope.io/

核心特性

• 推理范式：采用 ReAct（Reasoning and Acting）范式。Agent 在"观察-推理-行动"循环中动态规划任务路径，能处理意外情况。
• 生产级控制：
  • 运行时干预：支持安全中断、优雅取消，Agent 状态可保留与恢复。
  • Hook 系统（Human-in-the-Loop）：支持在任意推理步骤插入人工审核或干预，适用于敏感操作场景。
• 内置工具链：
  • PlanNotebook：结构化任务管理，支持 Agent 自主创建、追踪和修改计划。
  • 结构化输出：自动将模型输出映射为 Java POJO，具备格式自纠错能力。
  • 长期记忆：支持持久化、基于语义搜索的记忆存储，具备多租户隔离能力。
  • RAG 集成：内置检索增强生成支持，可对接企业知识库或云服务（如阿里云百炼）。
• 协议与生态：
  • MCP 协议：原生支持 Anthropic 的 Model Context Protocol，可接入实现 MCP 服务端的工具（如数据库、浏览器）。
  • A2A 协议：支持 Agent-to-Agent 通信，可通过服务注册中心（如 Nacos）实现多 Agent、跨语言（如 Java 与 Python）的微服务式协作。

生产就绪能力

• 高性能架构：基于 Project Reactor 的响应式编程，支持高并发与非阻塞执行；支持 GraalVM 原生镜像编译，冷启动降至 200ms 级别，适合 Serverless 与 K8s 环境。
• 安全与可观测性：
  • 安全沙箱：为工具代码提供隔离执行环境，防止 Agent 越权操作。
  • 可观测性：集成 OpenTelemetry，支持全链路分布式追踪；提供 AgentScope Studio 可视化调试界面。

与 Spring AI 的关系

• 定位差异：Spring AI 将 LLM 作为工作流中的可控节点，适合在既定业务流程中嵌入 AI 能力；AgentScope Java 将 LLM 视为自主决策的"大脑"，适合路径不固定、需 Agent 动态规划的场景。
• 互补可能：两者可协同使用，如用 Spring AI 管理主流程，在需自主决策的环节调用 AgentScope Java 构建的 Agent。

Pi Agent

• 官网：https://pi.dev/
• 架构文档：https://deepwiki.com/badlogic/pi-mono

Pi Agent（简称 Pi）是极简、可高度定制的开源 AI 编码智能体/Agent 框架，由 Mario Zechner（libGDX 作者）于 2024 年推出，是 OpenClaw 的核心引擎。

主打：内核极小、工具极少、扩展极强、模型无关。

Pi Agent = 极简内核 + 4 个原子工具 + 全模型兼容 + 无限扩展。适合做轻量、可控、可定制的自动化任务与编程助手。

1.介绍

1.1.核心设计哲学

内核只做 4 件事，只有 4 个内置工具：

• read：读文件/代码上下文
• write：新建文件/写代码
• edit：精准修改文件
• bash：执行终端命令（编译、运行、部署）

没有计划模式、子 Agent、审批流程。复杂度交给扩展，核心只留最薄执行层。

系统提示词极短（约 1000 token），对比 Claude Code / Cursor 动辄 8000–15000 token。好处是上下文利用率高、速度快、成本低、不易跑偏。

模型无关，统一接口：支持 OpenAI、Anthropic、Google、xAI、Groq、Ollama、vLLM 等 15+ 大模型。换模型只需改配置，不用重写适配层。

1.2.适用场景

1. 终端 AI 编程助手：直接在命令行写代码、改 Bug、跑测试、部署。
2. 自动化运维：服务器操作、日志分析、脚本执行。
3. 构建自定义 Agent：通过 TypeScript 扩展/技能包，添加新工具、新流程。
4. 嵌入到其他系统：作为 OpenClaw、IDE 插件、内部平台的底层引擎。

1.3.与 Claude Code / Cursor 的区别

• Pi Agent：极简内核、4 工具、短提示词、高度可扩展、终端优先、开源
• Claude Code：功能大而全、内置规划/子 Agent、提示词极长、闭源
• Cursor：IDE 深度集成、图形界面、闭源、定制化弱

1.4.简单使用

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

# 运行（默认用 OpenAI GPT-5-mini）
pi-agent "写一个 Python 快速排序"

# 切换模型
pi-agent --model ollama:codellama "解释这段代码"

Package Catalog：https://pi.dev/packages

2.架构（pi-mono 5 个包）

2.1.架构图

pi 的架构是一个典型的"分层单体"：五层从底到顶依次是 pi-ai（LLM 抽象层）→ pi-agent-core（Agent 运行时）→ pi-coding-agent（CLI 编排层）→ pi-tui（终端 UI）→ 扩展系统，外加一个独立的 pi-server 做多实例编排。 它把"Agent 必需的最小内核"压到极薄，然后靠 TypeScript Extension API 让上层的一切（subagent、Plan Mode、权限门禁、MCP）都能被你重新实现。

┌─────────────────────────────────────────────────────────────┐
│  Extensions / Skills / Themes / Prompt Templates            │  ← 扩展层
│  (TS 模块，通过 ExtensionAPI 拦截 20+ 生命周期事件)          │
├─────────────────────────────────────────────────────────────┤
│  pi-coding-agent:  AgentSession 编排层                       │
│  ┌─────────┬──────────┬─────────┬──────────┐                │
│  │Interactive│ Print   │  RPC    │   SDK    │ ← 四种运行模式 │
│  └─────────┴──────────┴─────────┴──────────┘                │
│  SessionManager (JSONL 树形持久化)  ·  SettingsManager      │
│  DefaultResourceLoader (资源发现)   ·  Compaction           │
├─────────────────────────────────────────────────────────────┤
│  pi-agent-core:  Agent 运行时                                │
│  ┌────────────────────────────────────────────┐             │
│  │ AgentHarness (高层编排)                     │             │
│  │   ├─ Agent (状态机: _state, 队列)           │             │
│  │   ├─ agentLoop() (LLM↔工具循环)             │             │
│  │   └─ Session (树形转录)                     │             │
│  └────────────────────────────────────────────┘             │
│  PendingMessageQueue (steering / follow-up)                 │
├─────────────────────────────────────────────────────────────┤
│  pi-ai:  LLM 统一抽象层                                      │
│  stream / streamSimple → api-registry → provider 实现        │
│  (OpenAI / Anthropic / Google / Bedrock / Mistral / NIM...)  │
│  MODELS 目录  ·  AuthStorage (OAuth)  ·  calculateCost       │
├─────────────────────────────────────────────────────────────┤
│  pi-tui:  终端 UI 库 (独立包，无 AI 依赖)                     │
│  TUI 差异渲染  ·  Component/Container  ·  Overlay  ·  Editor │
└─────────────────────────────────────────────────────────────┘
        ↕ 旁路
   pi-server (多 Agent 实例编排 · SQLite 会话 · Radius 远程)

2.2.第 1 层：pi-ai 统一抽象

这一层把 15+ 家 Provider 的差异全部抹平，是整个架构的基石。

• 核心入口：stream/complete（Provider 原生参数）和 streamSimple/completeSimple（Provider 无关，统一 reasoning?: ThinkingLevel，取值 minimal/low/medium/high/xhigh）
• API 注册表：api-registry.ts 把 6 种 wire protocol（anthropic-messages、openai-completions、openai-responses、bedrock-converse-stream、google-generative-ai、openai-codex-responses）映射到对应实现
• 核心类型：Model<TApi>、Context（可序列化，支持跨模型切换）、Message（UserMessage/AssistantMessage/ToolResultMessage 判别联合）、Tool（TypeBox schema）
• 模型白名单：目录里只收录支持 function calling 的模型，这是 Agent 工作流的硬前提
• 认证与成本：AuthStorage 处理 OAuth（GitHub Copilot、Gemini CLI、OpenAI Codex），calculateCost 基于模型元数据算费用

2.3.第 2 层：pi-agent-core 运行时

这一层被刻意分成低层 Agent 和高层 AgentHarness 两个概念。

低层 Agent Loop（状态机）

• Agent 类维护 _state、steeringQueue（用户插话队列）、followUpQueue（后续消息队列）
• agentLoop() 是函数式入口，管理多轮对话循环（LLM 调用 ↔ 工具执行）
• PendingMessageQueue 配合 QueueMode（all 或 one-at-a-time）实现 Steering——用户可以在 Agent 执行中插话改变走向
• Transport 抽象通过 AgentMessage 实现，支持通过 declaration merging 扩展自定义消息类型，让 TUI/Web/RPC 都能跑在同一套内核上

工具管道（严格的五段生命周期）：支持 parallel / sequential 两种模式；parallel 模式下 tool_execution_end 按完成顺序触发，但结果消息保持 assistant 源顺序。

tool_execution_start → beforeToolCall hook → 执行 → afterToolCall hook → tool_execution_end

高层 AgentHarness（编排）

• 管理"Turn Snapshot"——单次 LLM 请求所需的 tools/model/resources 的时点快照
• 动态加载 Skill（从 SKILL.md）和 PromptTemplate
• 提供 compact()（自动压缩上下文）和 generateBranchSummary()（跨分支摘要）两个上下文管理原语

2.4.第 3 层：pi-coding-agent 编排层

这是 pi 命令行工具的主战场，核心类是 AgentSession。 四种运行模式共享同一套内核

• 资源发现管道：DefaultResourceLoader 从全局目录（~/.pi/agent/）、项目本地目录（.pi/）和已安装的 pi 包中发现扩展、Skills、Prompt Templates、Themes，项目本地优先于全局。
• 会话持久化：JSONL 文件（log.jsonl），每条记录带 id + parentId 构成树形结构，SessionManager 提供 appendEntry()、branch()、buildSessionContext() 方法——这是 pi 独有的树形会话/分支探索能力的底层实现。
• 配置合并层级：CLI 参数 > 项目 .pi/settings.json > 全局 ~/.pi/agent/settings.json > 内置默认。

2.5.第 4 层：pi-tui — 终端 UI 库

独立发布为 @mariozechner/pi-tui，没有任何 AI/Agent 依赖，可以单独用在任何 Node.js CLI 项目里。

• 差异化渲染：只重绘变化的行，用 CSI 2026 做原子屏幕更新，消除闪烁
• 组件架构：所有可见元素实现 Component 接口（render(width) / handleInput(data) / invalidate()），通过 Container 组合
• Overlay 系统：模态对话框/面板浮层
• 输入抽象：支持 legacy 终端序列和 Kitty keyboard protocol，Editor 支持 IME 硬件光标定位（CJK 输入友好）
• 内置组件：Editor（多行/自动补全/kill-ring）、Input、SelectList、Markdown、Image（Kitty/iTerm2 内联图片）

2.6.第 5 层：Extension 系统

Extension 是 TypeScript 模块，通过 ExtensionAPI 注入——你可以注册新工具、新 slash 命令、新快捷键，并监听生命周期事件（如 before_agent_start）。 扩展、Skills、Themes、Prompt Templates 可以打包成 pi packages（npm 风格的包）分发，未固定的包在新版本出现时会自动安装或更新。

2.7.旁路：pi-server 编排

独立的服务端进程，负责多 Agent 实例管理、IPC、SQLite 会话存储、Radius 远程连接集成，用于把 pi 变成一个可被外部系统编排的多实例平台。

3.设计哲学：为什么是这样的架构

理解 pi 架构的关键是"原语而非特性"这条贯穿始终的原则。

• pi-ai 只有 LLM 调用 + 工具 schema 两个原语——没有 RAG、没有 Agent 编排、没有 Chain 之类的概念，只做"把任何模型的任何调用统一成一套可序列化的类型"
• pi-agent-core 只有循环 + 消息队列 + 工具执行三个原语——subagent、Plan Mode、权限门禁、MCP、TODO 这些在其他 Agent 里被硬编码的特性，这里全部留给扩展实现
• pi-coding-agent 只内置 4-7 个原语工具（read/write/edit/bash/grep/find/ls）——没有内置 subagent、没有内置 plan、没有内置 approval workflow，全部通过 Extension API 让你自己拼
• pi-tui 只有 Component/Overlay 两个原语——但靠组合能搭出任何终端界面

这种"极简内核 + 强扩展点"的架构和 Claude Code 形成镜像对照：

• Claude Code 是把调优好的工作流焊死在内核里，扩展只能"接上去"；
• pi 是把工作流全部交出去，内核只保证事件链可以被拦截和改写。
• 一个 system prompt 约 200 token，另一个约 10k token，就是这个哲学差异最直观的体现。

如果你想深入某个具体子系统（比如 Extension 事件的完整列表、Compaction 的实现细节、RPC 协议的具体格式）， pi-mono 的 DeepWiki 索引页有 20 多个子页面对应到每个模块的源码文件，可以直接按图索骥。

插件

pi官方自带插件平台：https://pi.dev/packages

• Pi 插件减法清单：每个都解决一个具体的烦