Agent-C：4KB纯C语言AI智能体，零依赖实现本地Shell命令执行

1. 项目概述：一个极简主义的AI执行者

最近在折腾AI应用本地化部署时，我一直在寻找一个能真正“轻装上阵”的解决方案。市面上的AI Agent框架动辄几百MB，依赖库一大堆，部署起来让人头疼。直到我遇到了Agent-C，一个用纯C语言编写、编译后仅有约4KB大小的AI智能体，它彻底改变了我对“轻量级”的认知。这个项目本质上是一个与OpenRouter API通信，并能根据AI的指令执行本地Shell命令的微型代理。它没有依赖curl，也没有链接libssl，在macOS上直接使用系统原生的SecureTransport实现TLS，在Linux上则采用了Mbed TLS，真正做到了从网络通信到命令执行的“全栈自包含”。

对于开发者、运维工程师或是任何希望将大语言模型能力无缝集成到命令行工作流中的人来说，Agent-C提供了一个绝佳的样板。它证明了实现一个功能完整的AI Agent并不需要庞大的框架，核心逻辑可以如此简洁明了。接下来，我将带你彻底拆解这个项目，从设计思路、代码结构到编译实践和扩展可能，让你不仅能用起来，更能理解其每一行代码背后的精妙之处。

2. 核心设计哲学与架构拆解

2.1 为什么选择“零依赖”的C语言路径？

Agent-C最引人注目的特点就是其“零依赖”和极致的体积控制。在当今Node.js、Python生态繁盛的背景下，选择用C语言从头实现一个AI Agent，背后是一套非常务实的设计哲学。

首要考虑是部署的纯粹性与可控性。一个静态链接的、只有几KB的二进制文件，可以扔进任何系统环境（甚至是资源受限的嵌入式环境或初始化系统）中直接运行，无需担心Python版本冲突、Node模块缺失或是动态链接库的路径问题。这对于制作可移植的运维工具、集成到系统镜像或作为其他应用的内嵌组件来说，价值巨大。

其次是性能与资源开销。虽然与OpenRouter API的网络通信是主要延迟来源，但本地的JSON解析、HTTP请求构建、Shell命令派发等环节，用C实现可以做到几乎没有额外开销。整个程序运行时的内存 footprint 可能只有几十MB（大部分还是用于存储对话历史），这对于长期运行在后台的守护进程式Agent尤为重要。

最后是安全边界的清晰化。由于自行实现了HTTP客户端和TLS，开发者对网络层的控制达到了极致，可以精细地管理超时、重试、连接池等行为。同时，将整个逻辑收敛在一个进程内，也减少了因依赖库漏洞或被恶意替换而引入的安全风险。

注意：选择C语言也意味着需要手动处理许多底层细节，如内存管理、字符串操作、网络字节序等，这对开发者的功底要求更高。但Agent-C的代码保持了惊人的简洁，堪称一个优秀的教学范例。

2.2 核心工作流与组件交互

Agent-C的核心工作流是一个标准的“对话-执行-反馈”循环，但其实现方式非常精巧。我们可以通过以下序列来理解其内部组件如何协同工作：

1. 初始化与连接建立：程序启动后，首先读取环境变量OR_KEY获取OpenRouter API密钥。然后，它根据编译目标平台（macOS或Linux）初始化对应的TLS上下文（SecureTransport或Mbed TLS），并创建一个到api.openrouter.ai443端口的TCP连接。

2. 对话管理：程序内部维护一个最多20条消息的滑动窗口（conversation数组）。每次交互，都会将最新的用户查询和此前的对话历史（包括AI的回复和工具执行结果）一起格式化，作为请求的messages字段发送。

3. 请求构造与流式发送：程序将对话消息、指定的模型（如openai/gpt-3.5-turbo）以及定义好的“工具”（一个允许调用sh执行Shell命令的工具描述）组装成一个符合OpenAI API规范的JSON请求体。这个请求通过已建立的TLS连接，以HTTP/1.1的协议格式发送出去。特别的是，它设置了Accept: text/event-stream头部，要求服务器以Server-Sent Events (SSE) 形式流式返回响应。

4. 流式响应处理：程序进入一个循环，持续从网络连接中读取数据块。它解析SSE格式的数据行，寻找以data:开头的行。这些行中包含的是JSON片段，程序会提取其中的choices[0].delta.content字段来获取AI实时生成的文本，并立即打印到终端，实现“打字机”效果。

5. 工具调用检测与执行：这是Agent的“智能”所在。当解析到的JSON片段中包含choices[0].delta.tool_calls字段时，程序就知道AI试图调用工具了。它会收集并组装完整的工具调用参数（其中包含了要执行的Shell命令）。一旦一个完整的工具调用对象被接收，程序就会：

   • 在一个子进程中fork()并exec()指定的Shell（如/bin/sh）来运行该命令。
   • 捕获命令的标准输出和标准错误。
   • 将执行结果（成功或失败，以及输出内容）格式化为一个新的“工具”消息，追加到对话历史中。

6. 自动跟进请求：在成功执行一个工具调用并生成结果消息后，Agent-C不会等待用户输入，而是自动地立即将包含了该结果的新对话历史再次发送给OpenRouter API，以获取AI对执行结果的“看法”或下一步指令。这个过程在一个循环内最多持续5次，以防止因AI逻辑错误导致无限循环执行命令。

7. 循环与退出：完成一轮或数轮（如果有工具调用）的交互后，程序会等待用户输入下一条指令。输入空行或发送EOF（Ctrl+D）即可退出程序。

整个架构的精华在于其“自包含”和“流式响应”与“阻塞式工具执行”的无缝结合。下面这个表格概括了核心组件及其职责：

3. 代码深度解析与关键实现

3.1 网络通信：手动实现HTTP与TLS

对于大多数现代开发者来说，手动用C语言实现HTTPS客户端听起来像是一项“复古”的挑战。但Agent-C做到了，而且代码相当清晰。我们重点看两个平台的不同实现。

在macOS上（使用SecureTransport）： SecureTransport是Apple的原生TLS/SSL API。Agent-C的使用步骤如下：

1. 创建上下文：SSLCreateContext创建一个客户端上下文。
2. 配置连接：SSLSetIOFuncs设置自定义的读写函数，这些函数底层调用的是标准的read和write系统调用，操作的是普通的TCP Socket文件描述符。SSLSetConnection将上下文与Socket关联。
3. 握手：SSLHandshake执行TLS握手。一旦成功，后续通过SSLRead和SSLWrite进行的数据收发都会自动被加密/解密。

这种方式的优势是深度集成系统，无需额外库，且可能受益于系统的证书管理（如Keychain）。

在Linux上（使用Mbed TLS）： Mbed TLS是一个轻量级的、可嵌入的TLS库。Agent-C将其源码直接包含在项目中（或通过子模块引用），实现了静态链接。

1. 初始化结构体：初始化mbedtls_ssl_context,mbedtls_ssl_config,mbedtls_ctr_drbg_context等一系列结构体。
2. 熵源与随机数：配置随机数生成器，这是TLS安全的基础。
3. 设置套接字：mbedtls_ssl_set_bio将SSL上下文与自定义的net_send和net_recv回调绑定，这些回调同样操作TCP Socket。
4. 握手与通信：mbedtls_ssl_handshake和mbedtls_ssl_read/mbedtls_ssl_write完成安全通信。

无论是哪种实现，其上层都抽象出了一套统一的函数接口（如tls_send,tls_recv），使得主逻辑中的HTTP层可以无视底层TLS的实现差异。

手动实现HTTP/1.1客户端： Agent-C没有使用任何HTTP解析库。它通过snprintf手动拼接出HTTP请求字符串：

char request[4096]; snprintf(request, sizeof(request), "POST /api/v1/chat/completions HTTP/1.1\r\n" "Host: api.openrouter.ai\r\n" "Authorization: Bearer %s\r\n" "Content-Type: application/json\r\n" "Accept: text/event-stream\r\n" "Content-Length: %zu\r\n" "\r\n" "%s", api_key, body_len, request_body);

然后通过tls_send发送。接收响应时，它逐字节读取，寻找\r\n\r\n来分割头部和体，并特别处理SSE流中data:的行。

实操心得：手动处理HTTP协议虽然繁琐，但避免了链接libcurl带来的体积膨胀和依赖。这里的关键是缓冲区管理要小心，防止溢出。Agent-C使用了固定大小的缓冲区，在实际使用中，如果对话历史非常长，可能会导致请求体超限，这是项目目前的一个局限，也是未来可以优化的点（例如动态分配内存）。

3.2 简易JSON解析器：状态机的艺术

为了不引入cJSON这类库，Agent-C实现了一个精简的、针对特定路径的JSON解析器。它并不解析整个JSON树，而是像一个状态机一样扫描字符流，只提取它关心的字段：content,tool_calls以及其中的function.arguments。

核心函数parse_json接收一个JSON字符串指针和一个“路径”数组（如{"choices",0,"delta","content"}），然后遍历字符串，根据当前字符（如{,",:）和路径索引来定位目标值。当路径匹配完成且遇到值的起始字符（字符串或对象）时，开始记录直到值结束。

例如，提取流式响应中的文本片段：

// 伪代码逻辑 if (in_string && path_matched) { // 当前字符是目标字符串值的一部分 append_to_output_buffer(current_char); }

对于tool_calls，逻辑更复杂一些，因为它需要解析一个数组，数组中的每个元素是一个对象，对象里包含function对象，其arguments是另一个JSON字符串需要进一步解析。

注意事项：这种解析方式非常高效，因为它避免了构建完整的DOM树。但它也非常脆弱，严重依赖于OpenRouter API返回的JSON格式严格符合预期。如果API响应格式稍有变动（比如字段顺序改变、多了无关空格），这个简易解析器就可能出错。在正式产品中，使用一个健壮的JSON库是更稳妥的选择，但在这个追求极简的Demo中，这种实现方式堪称“黑客艺术”。

3.3 工具调用与Shell命令执行

这是Agent-C最具“智能”也最需谨慎处理的部分。代码在execute_tool_call函数中。

1. 参数提取：从tool_calls中解析出function.arguments，它是一个JSON字符串，通常形如{"command": "ls -la"}。程序需要再次解析这个字符串以获取具体的命令。

2. 创建子进程：使用fork()创建一个子进程。在子进程中：

   • 使用pipe()创建管道，用于重定向子进程的标准输出和标准错误。
   • 使用dup2()将管道的写端重定向到子进程的标准输出和错误文件描述符（STDOUT_FILENO, STDERR_FILENO）。
   • 关闭所有不需要的文件描述符（包括管道的读端）。
   • 调用execl(“/bin/sh”, “sh”, “-c”, command_from_ai, (char *)NULL)来执行命令。这里的-c选项允许直接传递命令字符串。

3. 父进程读取结果：父进程关闭管道的写端，然后从管道的读端读取数据，直到EOF。这将捕获命令执行的所有输出。

4. 结果格式化与反馈：将捕获的输出（或错误信息）格式化为一个新的消息对象，其role为“tool”，并包含一个唯一的tool_call_id，然后将此消息追加到对话历史中。正是这个消息触发了下一轮的自动跟进请求。

安全警告：这是整个项目最大的安全风险点。AI生成的命令被直接传递给system()或exec执行，这意味着AI拥有与运行Agent-C进程相同的用户权限。一个恶意的或出错的AI指令（如rm -rf /， 虽然需要root权限，但删除用户家目录是可能的）可能造成灾难性后果。绝对不要在具有重要数据或高权限的账户下运行未经严格审查和沙箱化的Agent-C。在生产环境中，必须加入命令白名单、用户权限降级、容器隔离或运行时监控等安全机制。

4. 从编译到运行：完整实操指南

4.1 环境准备与编译

Agent-C的编译过程因其极简主义而显得与众不同。它不依赖复杂的构建系统，只有一个Makefile。

第一步：获取代码与API密钥

git clone https://github.com/bravenewxyz/agent-c.git cd agent-c export OR_KEY=sk-or-v1-xxxxxxxxxxxx # 替换为你的OpenRouter API密钥

确保你的OpenRouter账户有余额，并且API密钥有效。

第二步：理解Makefile与编译选项Makefile是编译的核心。它主要做以下几件事：

• 检测平台：默认的make会尝试自动检测是macOS还是Linux。
• 平台特定编译：
  • make macos: 针对macOS编译。它使用clang，并通过-framework Security -framework CoreFoundation链接SecureTransport。最精彩的一步是使用lzma命令将编译出的二进制文件压缩成一个自解压的Shell脚本，使得最终发布的agent-c文件虽然看起来是脚本，但实际是压缩的二进制，运行时自解压，以此实现极致的分发体积。
  • make linux: 针对Linux编译。它使用gcc并链接mbedtls、mbedx509、mbedcrypto库（需要提前安装或从子模块构建）。然后使用upx工具对二进制进行压缩，同样是为了缩小体积。
• 清理：make clean删除编译中间文件。

编译执行：

make # 自动检测平台编译 # 或明确指定 make macos # 编译成功后，当前目录会生成可执行文件 `agent-c` ls -lh agent-c # 你可能会惊讶地看到，在macOS上它可能只有几KB，甚至看起来像一个文本文件（自解压格式）。

踩坑记录：在Linux上编译时，最常见的错误是找不到mbedtls库。你需要确保开发库已安装。在Ubuntu/Debian上可以尝试sudo apt-get install libmbedtls-dev。如果还是不行，项目可能需要从子模块初始化并编译Mbed TLS，仔细阅读项目README或Makefile中的注释。在macOS上，如果遇到SecureTransport相关链接错误，请检查Xcode命令行工具是否完整安装 (xcode-select --install)。

4.2 运行与交互示例

编译成功后，运行非常简单：

./agent-c

程序启动后，会显示一个简单的提示符>>>，等待你输入。

基础对话：

>>> 你好，请介绍一下你自己。 (程序开始流式打印AI的回复) 你好！我是一个轻量级的AI助手，运行在Agent-C程序中。我可以与你对话，并且根据你的需求，在得到你明确授权后，我可以执行一些简单的Shell命令来帮助你完成本地任务，比如查看文件、查询系统信息等。请注意，我执行命令需要你的确认（在这个程序中是自动进行的），并且请确保你了解命令的含义。有什么我可以帮你的吗？

工具调用演示（执行命令）：

>>> 请查看当前目录下有哪些文件，并按大小排序。 (程序开始流式回复，并在中途检测到工具调用) ... 看起来你想查看文件列表。我来帮你执行这个命令。 (此时，程序内部解析到AI返回的tool_calls，其中arguments为 `{"command": "ls -la | sort -k 5 -n"}`) (程序执行该命令，捕获输出，然后自动发送结果给AI获取解读) 已执行命令。输出如下： 总用量 48 -rw-r--r-- 1 user staff 123 4月 10 10:00 README.md -rwxr-xr-x 1 user staff 4096 4月 10 10:05 agent-c -rw-r--r-- 1 user staff 2048 4月 10 10:00 agent.c -rw-r--r-- 1 user staff 567 4月 10 10:00 Makefile ... 根据输出，当前目录下主要有四个文件：README.md文档、可执行的agent-c程序、源代码agent.c和构建文件Makefile。它们已按文件大小（第五列）从小到大排序。最大的文件是agent-c可执行程序（4096字节），其次是agent.c源代码（2048字节）。需要我分析某个特定文件吗？

你可以看到，整个过程是完全自动的：用户提问 -> AI思考并决定调用工具 -> Agent-C执行工具 -> 将结果返回给AI -> AI生成最终回答。用户无需介入中间的命令执行步骤。

多轮工具调用： AI可以规划一连串操作。例如，用户问：“帮我找出当前目录中最近修改的C源文件，并统计它的行数。” AI可能会先调用find . -name “*.c” -type f -printf ‘%T+ %p\n’ | sort -r | head -1 | cut -d‘ ’ -f2-来找到文件，然后在得到文件名结果后，再自动发起第二轮请求，调用wc -l <filename>来统计行数。这一切都在一次用户输入内由Agent-C自动完成最多5个循环。

4.3 配置与自定义

虽然Agent-C小巧，但仍有几个可以调整的地方：

1. 修改对话历史长度：在agent.c源码中，找到#define MAX_MESSAGES 20这行。你可以增大或减小这个值。注意，更大的历史窗口会消耗更多内存，并且可能使每次请求的上下文更长（API调用成本更高）。

2. 更换模型：在send_request函数内部，寻找JSON请求体中“model”字段的设置。默认可能是“openai/gpt-3.5-turbo”或“openai/gpt-4”。你可以将其改为OpenRouter支持的任何其他模型，例如“anthropic/claude-3-haiku”或“google/gemini-flash-1.5”。不同模型的工具调用能力、价格和速度各不相同。

3. 调整工具定义：目前工具定义是硬编码在请求体中的。你可以修改tools数组，来改变工具的名称、描述或参数模式。例如，你可以增加一个工具，或者修改sh工具的描述来更精确地引导AI如何使用它。参数模式“command”是固定的，需要与JSON解析逻辑匹配。

4. 超时与重试：当前代码没有设置网络超时。在生产环境中，你需要在connect,read,write等系统调用处加入超时逻辑，并为失败的API请求添加重试机制（尤其是考虑到OpenRouter可能聚合了多个后端供应商）。

5. 扩展思路与高级玩法

Agent-C作为一个极简原型，为扩展提供了巨大的想象空间。

5.1 功能扩展方向

1. 多工具支持：目前只有sh工具。你可以很容易地添加新工具。例如：

   • python工具：执行一段Python代码并返回结果。
   • http_get工具：执行HTTP GET请求获取网页内容，让AI能够联网搜索（需谨慎处理安全）。
   • calc工具：一个安全的数学表达式计算器，避免直接调用sh执行expr或bc。 实现方式是在tools数组中增加新的工具描述，并在execute_tool_call函数中根据tool_call.function.name来分支处理。

2. 持久化对话历史：将conversation数组在退出时保存到文件（如简单的JSONL格式），并在启动时加载。这样就能实现跨会话的记忆。

3. 交互模式增强：

   • 安全确认：在执行任何Shell命令前，先打印出命令并等待用户输入y确认。这能极大提升安全性。
   • 聊天模式：实现一个更友好的交互界面，支持多行输入、历史命令回顾、语法高亮等。
   • 后台服务模式：让Agent-C作为一个守护进程运行，通过Unix Socket或HTTP端口提供API服务，供其他程序调用。

4. 集成系统监控：将Agent-C与top,df,netstat等命令结合，打造一个可以通过自然语言查询系统状态的运维助手。

5.2 安全加固方案

如前所述，直接执行Shell命令是危险的。以下是一些加固思路：

1. 命令白名单/黑名单：维护一个允许或禁止的命令模式列表。例如，可以禁止包含rm、dd、mkfs、>（重定向到敏感文件）、sudo等危险模式的命令。

2. 沙箱化执行：

   • 使用容器：在fork()后，子进程在exec()前调用clone()或unshare()进入一个新的命名空间，限制其文件系统视图、网络访问等。
   • 使用沙箱工具：调用seccomp-bpf来限制可用的系统调用，或使用bubblewrap等工具。
   • 权限降级：在子进程中调用setuid()/setgid()切换到一个低权限用户（如nobody）。

3. 输入净化与审计：对AI生成的命令进行严格的转义和验证，防止命令注入（如; rm -rf /）。同时，将所有执行的命令和结果记录到审计日志中。

5.3 性能优化与调试

1. 连接复用：目前每个请求都新建连接。可以修改为保持HTTP长连接（HTTP Keep-Alive），在一个连接上发送多个请求，减少TCP和TLS握手开销。

2. 更高效的JSON解析：当消息历史变长，JSON解析可能成为瓶颈。可以考虑集成一个更高效但依然轻量的JSON库，如 parson 。

3. 调试输出：在编译时增加一个-DDEBUG宏定义，在代码中添加条件编译的调试打印，可以输出详细的HTTP请求/响应、解析过程等信息，便于排查问题。

6. 常见问题与故障排除

在实际编译、运行和扩展Agent-C的过程中，你可能会遇到以下问题：

调试技巧：

• 在编译时增加-g标志，使用gdb或lldb进行调试。
• 在代码关键位置（如网络收发、JSON解析开始/结束、工具调用前后）添加fprintf(stderr, “DEBUG: …\n”)打印日志，重定向到文件进行分析。
• 使用strace(Linux) 或dtruss(macOS) 跟踪程序的系统调用，查看网络连接、进程创建等行为。

Agent-C作为一个概念验证项目，其价值在于它清晰地展示了一个AI Agent最核心的骨架。它可能不适合直接用于生产环境，但绝对是学习AI Agent原理、理解LLM工具调用、以及探索轻量级系统编程的宝贵资源。通过拆解和改造它，你能获得远比使用一个现成框架更深入的理解。