如何构建一个极简的编程代理工具

摘要

作者因不满现有编程代理工具日益复杂且不透明的特性，决定自建名为pi的极简编程代理。他详细记录了统一多个LLM提供商API时遇到的挑战，包括不同提供商对相同API的不同实现方式、令牌计费追踪的困难、跨提供商上下文切换的复杂性等。文章强调精确控制模型上下文的重要性，并展示了pi-ai如何实现跨提供商的无缝会话切换和序列化功能。作者的设计哲学是只构建必要功能，拒绝过度设计，最终形成了包含pi-ai统一API、pi-agent-core代理循环、pi-tui终端UI框架和pi-coding-agent命令行工具的完整解决方案。

内容框架与概述

作者首先回顾了自己使用LLM辅助编程的演进历程，从最初的手动复制代码到ChatGPT，再到各类AI编码工具，最终选择Claude Code作为主力工具。然而随着Claude Code功能日益膨胀且频繁变动，作者开始感到不满，主要痛点包括不可见的上下文注入、不透明的交互过程、缺乏会话格式的文档化支持，以及难以自托管模型等问题。

为了解决这些问题，作者决定从零开始构建自己的编程代理工具。他拆分出四个核心模块：pi-ai负责统一LLM API并支持多个提供商，pi-agent-core处理工具执行和验证循环，pi-tui提供极简的终端UI框架，pi-coding-agent则是最终的CLI工具。设计哲学强调极简主义，只构建真正需要的功能。

文章详细阐述了构建统一LLM API时遇到的技术挑战。作者指出业界存在四种主流API规范，虽然功能相似但各提供商的实现细节差异巨大。这些差异包括对不同字段的支持程度、令牌参数的命名方式、系统提示词的处理方式、推理追踪的返回格式等。为了确保兼容性，pi-ai建立了覆盖所有提供商和流行模型的测试套件。

另一个重大挑战是令牌和缓存计费的追踪。不同提供商的计费报告方式五花八门，有的在SSE流开始时报告，有的在结束时报告，这使得准确成本追踪变得困难。作者还提到Google不支持工具调用流式传输的问题。文章最后展示了跨提供商上下文切换的代码示例，证明了pi-ai能够在Anthropic、OpenAI和Google之间无缝切换会话，并支持上下文的序列化和反序列化。

核心概念及解读

上下文工程：精确控制输入模型的内容和格式，这对提升代码生成质量至关重要。现有工具往往在用户不知情的情况下注入额外内容，破坏了这种精确控制。

跨提供商上下文切换：在同一会话中切换不同LLM提供商的能力，需要处理各提供商特有的工具调用追踪、思考痕迹和签名blob等差异，pi-ai通过最佳努力的方式实现了这一功能。

统一LLM API：抽象层设计，支持Anthropic、OpenAI、Google、xAI、Groq、Cerebras、OpenRouter等多个提供商，提供流式传输、工具调用、思考推理支持和令牌成本追踪等统一接口。

推理追踪：LLM在生成最终输出之前的思考过程记录，不同提供商以不同字段返回此内容，需要在跨提供商切换时进行格式转换和兼容处理。

最佳努力兼容：由于各提供商API差异巨大，无法保证完美的跨提供商兼容性，只能通过广泛的测试覆盖和合理的格式转换来尽可能实现无缝切换。

原文信息

此摘要卡片由 AI 自动生成