Harness 与 Agent 工程 · Agent架构与协作 · 2026-08-05

实战从零开始构建一个Coding Agent:Violin |得物技术

得物技术实战拆解:从零构建Coding Agent Violin,解析Agent Loop、模型适配与工具系统,掌握AI工程化核心能力。 核心内容:

  1. 背景与构建动机(Coding Agent发展趋势及Violin项目源起)
  2. 核心架构分层实现(Agent Loop、模型适配层、Tool System等关键模块)
  3. 效果预览与实战总结(Violin功能展示及项目价值)

目录

一、背景

二、效果预览

三、分层实现介绍

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); // 回写给模型 } }}

这里需要注意:

当然不管是 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 行,却是把整个项目「粘起来」的那层。它做的事情很简单:

展示核心逻辑(简化):

// 简化后的 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,"…
— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/OpenSourceLLM/2026080596341.html