目录
一、背景
二、效果预览
三、分层实现介绍
1.Agent Loop(一切的核心)
2.AI 模型适配层(Agent Loop 调用的是谁)
3.Tool System(Agent Loop的手和脚)
4.Product层(循环之外的事)
5.Event System(插件实现的基础)
6.网络层(客户端实现的基础)
7.Python Client 实现
四、总结
一
背景
从 24 年冬天开始,各类 coding agent 层出不穷——从 Gemini CLI 的起步,到 Claude Code 的尝试,再到如今 Codex、OpenCode、PI、Qoder 等百花齐放。
短短一年多的时间,agent 从大模型的一个附属品,逐渐演变成模型能力的放大器,成为 AI 工程化的关键载体。市面上各类业务 agent——客服、数据分析、工作流编排等——追根溯源,基本都是 coding agent 的泛化变种。
理解了 coding agent 的构建原理,也就掌握了理解其他 agent 的一把钥匙。笔者对每天都在使用的 agent 原理很感兴趣,于是决定自己写一个:violin。
二
效果预览
虽然有点丑,但是基本的功能(多模态、skill、插件)已经完备了。
三
整体架构
Violin 的架构设计深度借鉴了 Pi 的设计理念。Pi 作为一个 TypeScript 实现的 AI coding agent,其最突出的特点是简洁而可扩展的架构——三层分离(模型适配层 / 内核层 / 产品层)、EventBus 事件驱动、工具注册表和插件系统,每个模块各司其职且松耦合。
更难得的是,Pi 的代码完全开源,这不仅让 Violin 有了一个扎实的参考蓝本,也让它本身成为一个极佳的 Agent 工程学习范本:代码结构清晰、注释详尽、每层职责明确。想要学习 Pi 架构的,强烈推荐这个项目:how-pi-agent-works。
可以说,读懂了 Pi 的架构,就理解了现代 AI coding agent 的核心设计模式。Violin 在保持这一架构精髓的同时,用 Zig 替换了 TypeScript,在内存安全和性能上做了进一步的探索。
Violin agent 的架构如下:
Why Zig?
Violin 的架构设计深度借鉴了 Pi 的三层分离和 EventBus 方案,但在实现语言上做了完全不同的选择。既然每一层通过接口(或网络协议)解耦,那么不同层用不同语言实现是完全可行的——不需要也不可能「全部用一种语言写完」。
Violin 的分工是:Agent Loop、模型适配、会话管理等底层引擎用 Zig 实现,追求极致的性能和内存可控性;而 Client 端用 Python 实现,利用 Python 的生态快速搭建终端交互 UI。
两者通过 TCP + JSON line 协议通信,Server 不关心 Client 用什么语言写的。笔者的技术栈恰好是 Zig + Python,不会 JS、不熟悉 Rust,但这个组合正好覆盖了「引擎」和「界面」两端,分工清楚,各取所长。
每层为什么存在
ai:把供应商拍平
不同模型 API 对工具调用、推理内容、缓存、错误、OAuth、流式协议的表达都不同。Violin 把这些差异统一成 Message、Tool、AssistantMessageEvent 和 streamSimple()。
这样上层 Agent Loop 不需要知道「这是 Anthropic 的 tool_use,还是 OpenAI Responses 的 function call」。它只关心统一后的 toolCall 内容块。
agent-core:只管 Agent 运行时
product:把 Agent 变成可用产品
写一个 Agent Loop 不难,难的是把它变成每天能用的开发工具。产品层负责这些「麻烦但关键」的事情:
server:把 Agent 能力包装为一个TCP Server
为了让客户端实现与语言无关,我们需要将 agent 能力包装为一套通信协议 + 一个 TCPServer。TCPServer 流式通信 + 全双工,天生适合这个场景。
四
分层实现介绍
Agent Loop(一切的核心)
Agent Loop 是什么?一个 while 循环,在「问模型」和「执行工具」之间来回切换,直到模型给出最终答案。它不关心模型是 OpenAI 还是 Anthropic,不关心工具是读文件还是跑命令,只关心两件事:模型要不要调工具?如果要,调完继续问;如果不要,结束。
这是 Agent Loop 的核心代码(简化后):
while (turn < max_turns) : (turn += 1) { // 1. 调模型 const assistant = try model.complete(.{ .messages = messages.items, .tools = tool_registry.definitions(), }); // 2. 检查是否有工具调用 const has_tool_calls = assistant.toolCalls().len > 0; // 3. 没有 → 结束;有 → 逐个执行工具 if (!has_tool_calls) break; for (assistant.content) |block| { if (block == .tool_call) { const result = tool_registry.execute(tc.name, tc.args); messages.append(result); // 回写给模型 } }}
这里需要注意:
- 为什么要有 max_turns — 模型可能陷入无限工具循环,上限是安全阀。
- 为什么工具结果要 append 回 messages — 模型需要看到结果才能决定下一步。
- 为什么 tools 定义要传进 complete()— 模型要提前知道有哪些工具可用。
当然不管是 LLM 调用还是工具调用,都有失败的可能,所以我们需要在 AgentLoop 这一层加入重试机制。首先我们需要区分错误种类,是不是一个可以重试的错误,Violin 中做了简单分类:
Agent Loop 只关心「循环」,不关心消息从哪里来、执行结果存到哪里。这些「循环之外」的事——会话历史的加载和保存、上下文压缩后的重试、Arena 内存管理——由上一层产品层(product/agent.zig)封装。
agent.zig 调用 loop.run() 时传入历史消息,loop 返回后它负责把新消息持久化到 Session,并在 ContextOverflow 时截断上下文重试。
AI 模型适配层
(Agent Loop 调用的是谁)
模型适配层的职责只有一句话:把不同 LLM Provider 的 API 差异封装在一个 Model.complete() 接口后面。Agent Loop 只认这个接口,不关心背后是 OpenAI 还是 Anthropic。
简化后的核心逻辑(伪代码):
interface ModelAdapter { complete(input: CompleteInput) -> AssistantMessage name() -> string}// 每个 Provider 实现这个接口:// OpenAIAdapter — 调用 /chat/completions// AnthropicAdapter — 调用 /v1/messagesstruct CompleteInput { system_prompt: string, messages: Message[], tools: ToolDefinition[], max_tokens: int, temperature: float, stream_callback: optional callback, // 流式输出}
实际 Zig 实现使用函数指针表(Zig 没有 trait 和虚函数,用函数指针实现多态),每个适配器提供三个函数指针(complete、name、deinit),通过统一接口调用。适配器内部状态(如 base_url/api_key)通过类型擦除的指针在回调中还原。
Violin 适配了目前最流行的 2 种 LLM 协议:
两个适配器代码量差不多(531 vs 558 行),因为它们各自要处理 JSON 序列化、HTTP 请求、SSE 流式解析、错误映射。差异主要在:请求体格式不同(OpenAI 用 messages[],Anthropic 用 content[])。工具调用的结构不同(OpenAI 是 tool_calls[],Anthropic 是 content[] 中的 tool_use block)。流式协议不同(OpenAI 用 data: 行,Anthropic 用 event: 行)。
LLM 生成一个回答可能需要几秒甚至十几秒。如果等全部生成完再返回,用户只能干等。为了客户端体验的流畅,目前主流 Agent 都采用了流式输出,这个问题的解决方案是流式(SSE)。
// 模型适配器在收到 SSE 的每个 chunk 时,调用 stream_callback// Agent Loop 收到回调后,立即通过 EventBus 发射 message_update 事件// Client 收到事件后,实时追加到终端显示pub const StreamCallback = *const fn (ctx, chunk: StreamChunk) bool;
Violin 没有内置任何模型,全部从 ~/.violin/agent/models.json 中加载模型配置,再由客户端决定使用哪个模型:
{"providers": { "openai": { "base_url": "https://api.openai.com/v1", "api": "openai-completions", "api_key": "$OPENAI_API_KEY", "models": [ { "id": "gpt-4o", "name": "GPT-4o", "contextWindow": 128000 } ] } }}
Tool System
(Agent Loop的手和脚)
模型适配层让 Agent Loop 可以调任何模型,工具系统让 Agent Loop 可以做任何事。
工具的定义:
pub const Tool = struct { name: []const u8, description: []const u8, parameters: []const u8, // JSON Schema execute: ToolExecuteFn,};
Violin 内置了 6 个基本工具,和 Pi 的设计保持一致:
为了方便管理这些 tools,Violin 中实现了一个工具注册表(伪代码):实际 Zig 实现使用 HashMap 存储工具,按名称快速查找。definitions() 将工具列表编码为模型可识别的 JSON Schema 格式。
// 简化后的工具注册表逻辑:classToolRegistry: tools: Map funcregister(name, description, execute_fn): tools[name] = Tool(name, description, execute_fn) func get(name) -> Tool: return tools[name] func definitions() -> ToolDefinition[]: // 返回所有工具定义,发送给模型 return [t.definition() for t in tools.values()] func execute(name, args) -> ToolResult: tool = tools[name] return tool.execute(args)
Product层(循环之外的事)
agent.zig — 胶水层,但最关键
product/agent.zig 只有 123 行,却是把整个项目「粘起来」的那层。它做的事情很简单:
- 从 Session 加载历史消息。
- 传给 loop.run () 执行。
- loop 返回后,把所有新消息保存到 Session。
- 如果 loop 抛了 ContextOverflow,调用 compaction 压缩后重试。
展示核心逻辑(简化):
// 简化后的 agent.run() 逻辑:func run(config, user_input) -> AgentResult: history = load_history(config.session) while True: loop_result = loop.run( model=config.model, initial_messages=history, input=user_input ) if loop_result == ContextOverflow: compact_session() // 压缩历史,保留关键信息 continue // 压缩后重试 // 保存新消息到会话 for msg in loop_result.new_messages: session.appendMessage(msg) return AgentResult(text=loop_result.final_text)
session.zig — 对话的「记忆」
没有 Session,Agent 每次对话都是「失忆」的。存储格式:JSONL,每行一个独立 JSON 对象。第一行是会话头(id, created_at, cwd),后续每行是一条消息。
{"id":"sess_001","created_at":1717234567,"cwd":"/project","model":"gpt-4o"}{"id":1,"parent_id":null,"…