最近在看本地代码智能体方向时关注到 Ante 这个项目。它的定位非常直接一个打包成单个二进制文件、可以在离线环境下运行的 coding agent。也就是说你下载一个可执行文件在自己电脑或者内网服务器上运行就能让 AI 帮你读代码、改代码、跑测试而整个过程中源代码不需要上传到外部服务。这正好踩在很多团队的痛点上既想要 AI 辅助编码的效率又受限于代码保密、内网隔离和网络带宽问题。本文不打算只做产品介绍而是从 Ante 的设计思路上拆解一个可落地的 offline coding agent 需要哪些核心能力并用 Python 配合本地大模型写一个最小可运行的示例帮助你理解背后的工具调用与任务规划机制。如果你是后端开发、DevOps或者对 AI 编程助手感兴趣的技术爱好者这篇文章会提供一条比较完整的入门路径。1. 背景与核心概念1.1 什么是 coding agent先说结论coding agent编码智能体是一类能够“把任务当项目做”的 AI 编程工具。普通的代码补全工具比如 IDE 里的自动补全、仓库级代码解释本质上都是把当前光标附近的上下文交给模型让模型接着生成后面的内容。但 coding agent 不一样它可以自主地拆解一个较大任务例如“把订单模块的列表查询改成分页查询”然后自己去读控制器、服务层、Mapper、数据库脚本找到需要修改的地方生成改动方案执行代码修改最后可能还会运行测试来验证结果。从工程层面看coding agent 通常是一个可以反复执行“推理 工具调用”循环的程序。它每走一步都会判断现在还需要哪些信息该去读哪个文件是否需要执行命令这个循环有点像一个经验丰富的开发者在排查问题时的思考过程。传统 RPA 或脚本只能按写死的流程执行coding agent 则可以根据模型的语言理解和推理能力动态决定下一步动作。这里的关键不是模型能写出多惊艳的代码而是它能不能像人一样在代码库里定位问题、找到上下文并做出正确的修改决策。1.2 single binary 意味着什么Single binary 在 Go、Rust 等语言的工具链里很常见。它是指把程序的所有依赖、动态库、资源文件全部打包进一个可执行文件用户拿到后直接运行不需要安装 Node.js、Python、Java Runtime也不用去处理各种依赖冲突。对于 coding agent 这种工具来说single binary 带来的第一个好处是分发成本极低。团队里不同成员的电脑环境差异很大有人机器上装了各种版本的 Python有人根本没有运行时环境如果给每人发一个二进制文件所有环境差异都被抹平了。第二个好处是版本一致性。一旦把所有依赖打进二进制那么只要你用的二进制文件版本相同行为就是确定的。这比“让你先装一个 Python 3.11再 pip install 一堆包”要稳健得多。尤其在 CI/CD 流水线里工具链不希望在每次构建时都联网下载依赖。第三个好处是方便容器化部署二进制文件可以直接复制进镜像不需要额外构建运行时层。对于内网部署场景拷贝一个文件远比准备一整套运行环境简单。1.3 offline 模式解决什么问题Offline 在这里有两层含义第一层是运行时不需要访问外部 API推理在本地完成第二层是模型权重和相关依赖都预先缓存好完全断网也能运行。对很多公司来说开发者日常处理的核心代码是敏感资产不允许通过公网传输给外部大模型服务。即便是允许上传代码到云端的企业也会担心代码泄露、隐私合规以及按次计费成本。offline coding agent 直接把代码留在本机或者留在内网服务器上从根本上消除了出网隐患也让响应时间变得更快、更稳定。离线模式也会带来一些代价。本地模型能力通常弱于顶级云模型尤其是在复杂语义理解、长上下文推理和大规模代码重构上。为了弥补这个差距工程上需要做更多事情比如建立更精确的代码索引、使用多轮工具调用来逐步获取上下文、把任务拆分给多个子 agent 分工协作甚至针对特定编程语言和代码风格做微调。从产品角度看离线不是目的而是手段。它用工程复杂度换取数据安全和可用性适合对保密性要求高的场景。1.4 Ante 这类工具的适用场景结合 single binary 和 offline 这两个特点Ante 这类工具最适合的场景基本可以概括成三类。第一类是高保密内网研发环境源代码不能出内网但团队又想用 AI 辅助编码于是本地部署 agent 就成了最现实的方案。第二类是离线开发环境比如飞机、船舶、野外作业等场景网络不稳定甚至完全没有网络开发者依然需要 AI 帮忙生成单元测试、修复语法错误。第三类是追求低摩擦的独立开发者或小团队他们不想折腾模型部署和依赖安装拿到一个二进制文件就能立刻开始使用。当然这类工具也有明显的边界。它不适合那些需要最新领域知识的任务因为本地模型的知识截止日期通常较早也不适合需要超长上下文的项目级重构因为本地模型上下文窗口有限。在实践中比较常见的使用方式是让 agent 完成局部的、明确的目标比如“给这个函数补充参数校验”“把这几处重复代码块抽取成公共方法”“为这个模块补上单元测试”而不是让它在完全没有人工干预的情况下重写整个系统。2. 环境准备与整体架构2.1 示例环境说明为了把概念落到代码上这里准备一个最小可运行的示例。我选择 Python 3.10 配合 Ollama因为本地只需要跑一个小模型就能体验类似 Ante 的 offline coding agent 工作链路。Ollama 是一个本地模型运行时它提供简单的 REST API支持在 macOS、Windows、Linux 上运行并且能离线加载已经下载好的模型。版本这一块不要照搬需要根据你的实际情况调整。本文示例使用的模型是 qwen2.5-coder:3b它是阿里推出的代码模型系列之一3B 参数量在个人电脑上可以运行。下载完成后即使断网也可以调用。如果你的显卡显存较大可以换成 7B 或者 14B 的模型效果会更好但显存占用会相应增加。为了保证示例可复现建议先创建一个干净的目录避免和其他项目混在一起。2.2 整体架构一个 offline coding agent 从架构上可以拆成五个层次。最上层是交互层负责接收用户输入和处理输出通常表现为命令行或者 IDE 插件第二层是任务管理层把一个较大任务拆成若干可执行的步骤并且维护一个状态机第三层是上下文构建层从代码库里提取与当前任务相关的文件片段、符号定义、调用关系第四层是推理层调用本地模型生成决策和代码最下面是工具执行层提供读文件、写文件、执行命令、运行测试等能力。层与层之间通过结构化消息通信。这个架构和 Ante 这类单二进制产品并不矛盾。二进制只是最终分发形态内部的模块化设计仍然非常重要。把上下文构建、推理调度、工具执行分离才能让 agent 的行为可控。如果全部混在一起一旦任务失败你很难判断是模型能力不足导致还是工具调用链路出错。分层之后每一层都能独立测试和优化。2.3 agent 主循环Coding agent 最常见的运行方式是一个循环每一步都包含观察、决策、行动、验证四个环节。观察是从工具执行层获取当前代码库的真实状态比如“读取了某个文件的第 30 到 60 行发现异常处理缺失”。决策是模型基于当前状态选择一个动作可能是继续读别的文件也可能是修改代码还可能是运行测试。行动是工具执行层真正修改文件或者执行命令。验证是再次读取结果判断任务是否已经完成。这个循环会一直持续到模型认为任务完成或者达到我们设置的最大步数上限。为了不让 agent 无限循环下去实际产品里通常还有预算控制和时间限制。在接下来的核心原理拆解里我会重点分析这个循环中的几个关键设计点包括上下文怎么选、工具怎么命中、任务怎么规划。3. 核心原理拆解3.1 上下文构建策略大模型本身并不知道你的代码长什么样所以要在 prompt 里提供给模型相关信息。关键问题是怎么选取信息。最粗糙的做法是把整个代码库塞进 prompt但绝大多数项目远超模型上下文窗口。更合理的做法是先把代码库构建成一个可检索的索引。例如可以用 tree-sitter 提取出所有函数名、类名、变量名形成符号表再维护文件路径到代码行的映射。当任务到来时agent 先判断任务涉及的关键词比如“订单列表”会触发搜索 Order、order、list 等关键词找到相关文件再读取这些文件的内容片段。如果上下文还是不够agent 会进一步读取被引用的函数定义或者在修改点附近扩大读取范围。回到实战我们可以用文件列表和 grep 搜索代替完整的语义索引作为第一版实现。这种做法在小型项目里已经够用而且实现成本低。真实产品往往需要更复杂的索引机制尤其是大型仓库因为搜索会变慢、上下文会爆炸。但无论简单还是复杂目标只有一个在有限上下文内尽量覆盖任务真正涉及的代码。3.2 工具调用的设计工具调用是 coding agent 和普通聊天机器人的本质区别。聊天机器人只负责生成文本coding agent 必须能真正读取文件和修改文件。为了让模型可靠地调用工具一般会给模型提供一个工具清单每个工具都有名字、描述、入参格式。模型的任务是在某些时刻返回一个结构化的调用请求比如 read_file(service/UserService.java, 10, 80)。工具执行层收到请求后执行对应的函数再把执行结果返回给模型。在演示代码里我会选择一种更简单直接的方式让模型输出 JSONJSON 里带上 action 字段和参数。工具层解析这个 JSON执行相应动作把结果追加到对话历史。这种方案对开源模型友好主要原因是它不需要依赖模型特殊的 function calling 支持只要模型能生成符合格式的 JSON 就可以。真实产品则通常使用厂商提供的 function calling 能力效果更稳定但原理上是相近的。3.3 任务规划与 Plan/Coding 分离在 Ante 这类工具里plan 和 coding 往往是两个阶段。Plan 阶段agent 只做分析不修改任何文件。它会阅读相关代码整理出将要修改的清单可能还会生成一份 diff 预览。用户确认无误后agent 才进入 coding 阶段真正应用修改。这样做有两个好处一是防止模型理解错误后对代码库造成破坏二是让用户对修改范围有知情权减少“AI 偷偷改了很多我不想要的代码”的情况。在实现时plan 和 coding 可以共用一个工具集只是阶段不同。Plan 阶段把写文件、执行命令的权限关掉只开放读文件、搜索和 diffcoding 阶段才打开写权限。这种权限模型也能扩展到更细的粒度例如允许写测试文件但不允许写生产文件。在团队协作中这种权限控制主要是给人类留一个确认的窗口确保每一次改动都经过人工审阅。3.4 多 agent 协同与任务拆分当任务很大时单个 agent 很容易迷失方向。于是一些系统引入多 agent 协同一个 manager agent 负责拆解任务多个 worker agent 分别处理不同模块。worker 读取代码、执行修改把结果汇报给 managermanager 汇总后进一步分配任务。它们之间的消息可以看成一种轻量级协议包括“已完成部分”“遇到阻塞”“需要更多上下文”等状态。多 agent 协同的难点在于状态一致性和冲突解决。两个 worker 如果同时修改同一个文件可能会互相覆盖。比较好的做法是让不同 worker 负责不同模块尽量避免修改同一文件或者在写入前用 git diff 检查变化如果冲突则交给 manager 裁决。对个人开发者来说单 agent 已经足够多 agent 更适合大型项目和企业级流水线。至少从成本角度看单 agent 更容易调试和维护。4. 完整实战案例用 Python 实现一个迷你 offline coding agent4.1 案例目标与项目结构这一节我们用 Python 写一个非常小的 coding agent它能够读取工作区文件、修改文件并运行命令。它直接通过 REST API 调用本地 Ollama不依赖外网。先看一下项目结构mini-agent/ ├── agent.py ├── tools.py ├── config.json └── workspace/ └── demo.pytools.py 实现文件读写、命令执行等基础工具agent.py 实现主循环与本地模型交互解析模型输出执行工具workspace/demo.py 是待修改的示例文件作为 agent 的工作对象。config.json 可以存放模型名称、最大步数、工作区路径等配置这里为了简化直接在代码里写常量。接下来先写工具层。4.2 编写工具函数先看 tools.py。它的职责是让 agent 具备与文件系统和命令行的交互能力。代码里保留了明确的函数接口这样后续扩展工具也会比较方便。# 文件路径mini-agent/tools.py from pathlib import Path import subprocess def list_files(rootworkspace): 列出工作区内的所有普通文件。 return [str(p) for p in Path(root).rglob(*) if p.is_file() and .git not in p.parts] def read_file(file_path, start_line0, end_lineNone): 读取指定文件的行区间默认读取整个文件。 lines Path(file_path).read_text(encodingutf-8).splitlines() if end_line is None: end_line len(lines) return \n.join(lines[start_line:end_line]) def write_file(file_path, content): 写入文件注意这里有意保留覆盖语义。 Path(file_path).write_text(content, encodingutf-8) return fwritten {file_path}, {len(content)} chars def run_command(cmd): 执行一个 shell 命令并返回标准输出和错误输出。 result subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue) return result.stdout result.stderr这个工具集虽然只有四个函数但已经足够演示上下文读取、修改代码和验证结果三个典型动作。在真实项目里你会希望把 run_command 的权限收紧比如限制只能运行测试命令不能执行删除文件等高危操作。4.3 编写主循环代码接下来是 agent.py。我使用 Ollama 的 /api/chat 接口并开启 JSON 格式输出让模型返回结构化动作。主循环的思路是每次把当前任务和工具结果放进 messages让模型给出下一步动作工具层执行后把结果加回 messages直到模型输出 done 或者达到最大步数。# 文件路径mini-agent/agent.py import json import urllib.request from tools import list_files, read_file, write_file, run_command OLLAMA_URL http://localhost:11434/api/chat MODEL_NAME qwen2.5-coder:3b MAX_STEPS 10 def chat_with_model(messages): payload { model: MODEL_NAME, messages: messages, stream: False, format: json } req urllib.request.Request( OLLAMA_URL, datajson.dumps(payload).encode(utf-8), headers{Content-Type: application/json} ) with urllib.request.urlopen(req, timeout120) as resp: data json.loads(resp.read().decode(utf-8)) return json.loads(data[message][content]) TOOL_MAP { list_files: lambda args: list_files(), read_file: lambda args: read_file( args[file_path], int(args.get(start_line, 0)), int(args.get(end_line, 100)) ), write_file: lambda args: write_file( args[file_path], args[content] ), run_command: lambda args: run_command(args[cmd]), } def agent_loop(task): workspace_files list_files() system_msg { role: system, content: ( 你是一个运行在用户本机的离线代码智能体。你有四个工具 list_files、read_file、write_file、run_command。 你需要以 JSON 格式返回下一步动作。 格式{\action\: \read_file\, \file_path\: \...\, \start_line\: 0, \end_line\: 20} 或者 {\action\: \done\, \summary\: \任务完成\}。 不要尝试修改工作区以外的文件。 ) } user_msg { role: user, content: ( f任务{task}\n f当前工作区文件列表{workspace_files}\n 请根据任务逐步读取必要文件并完成修改最终输出 done。 ) } messages [system_msg, user_msg] for step in range(MAX_STEPS): print(f STEP {step 1} ) reply chat_with_model(messages) print(模型动作, json.dumps(reply, ensure_asciiFalse)) action reply.get(action) if action done: print(完成信息, reply.get(summary, )) return if action in TOOL_MAP: try: result TOOL_MAP[action](reply) except Exception as e: result f工具执行失败{e} else: result 未知 action请重新给出动作。 messages.append({role: assistant, content: json.dumps(reply, ensure_asciiFalse)}) messages.append({role: user, content: f工具执行结果\n{result}}) print(达到最大步数自动停止。) if __name__ __main__: task input(请输入任务描述) agent_loop(task)这里有一个关键设计工具执行结果会拼成一段文本继续发给模型。模型看到结果后再决定是继续读取其他文件还是开始写文件或者运行命令验证。它的记忆完全依赖 messages 里的历史消息因此 messages 会越来越长。为了控制长度真实产品里通常会对历史做截断或摘要。4.4 准备示例文件创建工作区示例文件 workspace/demo.py 离线编码智能体：单文件二进制与本地大模型实战
最近在看本地代码智能体方向时关注到 Ante 这个项目。它的定位非常直接一个打包成单个二进制文件、可以在离线环境下运行的 coding agent。也就是说你下载一个可执行文件在自己电脑或者内网服务器上运行就能让 AI 帮你读代码、改代码、跑测试而整个过程中源代码不需要上传到外部服务。这正好踩在很多团队的痛点上既想要 AI 辅助编码的效率又受限于代码保密、内网隔离和网络带宽问题。本文不打算只做产品介绍而是从 Ante 的设计思路上拆解一个可落地的 offline coding agent 需要哪些核心能力并用 Python 配合本地大模型写一个最小可运行的示例帮助你理解背后的工具调用与任务规划机制。如果你是后端开发、DevOps或者对 AI 编程助手感兴趣的技术爱好者这篇文章会提供一条比较完整的入门路径。1. 背景与核心概念1.1 什么是 coding agent先说结论coding agent编码智能体是一类能够“把任务当项目做”的 AI 编程工具。普通的代码补全工具比如 IDE 里的自动补全、仓库级代码解释本质上都是把当前光标附近的上下文交给模型让模型接着生成后面的内容。但 coding agent 不一样它可以自主地拆解一个较大任务例如“把订单模块的列表查询改成分页查询”然后自己去读控制器、服务层、Mapper、数据库脚本找到需要修改的地方生成改动方案执行代码修改最后可能还会运行测试来验证结果。从工程层面看coding agent 通常是一个可以反复执行“推理 工具调用”循环的程序。它每走一步都会判断现在还需要哪些信息该去读哪个文件是否需要执行命令这个循环有点像一个经验丰富的开发者在排查问题时的思考过程。传统 RPA 或脚本只能按写死的流程执行coding agent 则可以根据模型的语言理解和推理能力动态决定下一步动作。这里的关键不是模型能写出多惊艳的代码而是它能不能像人一样在代码库里定位问题、找到上下文并做出正确的修改决策。1.2 single binary 意味着什么Single binary 在 Go、Rust 等语言的工具链里很常见。它是指把程序的所有依赖、动态库、资源文件全部打包进一个可执行文件用户拿到后直接运行不需要安装 Node.js、Python、Java Runtime也不用去处理各种依赖冲突。对于 coding agent 这种工具来说single binary 带来的第一个好处是分发成本极低。团队里不同成员的电脑环境差异很大有人机器上装了各种版本的 Python有人根本没有运行时环境如果给每人发一个二进制文件所有环境差异都被抹平了。第二个好处是版本一致性。一旦把所有依赖打进二进制那么只要你用的二进制文件版本相同行为就是确定的。这比“让你先装一个 Python 3.11再 pip install 一堆包”要稳健得多。尤其在 CI/CD 流水线里工具链不希望在每次构建时都联网下载依赖。第三个好处是方便容器化部署二进制文件可以直接复制进镜像不需要额外构建运行时层。对于内网部署场景拷贝一个文件远比准备一整套运行环境简单。1.3 offline 模式解决什么问题Offline 在这里有两层含义第一层是运行时不需要访问外部 API推理在本地完成第二层是模型权重和相关依赖都预先缓存好完全断网也能运行。对很多公司来说开发者日常处理的核心代码是敏感资产不允许通过公网传输给外部大模型服务。即便是允许上传代码到云端的企业也会担心代码泄露、隐私合规以及按次计费成本。offline coding agent 直接把代码留在本机或者留在内网服务器上从根本上消除了出网隐患也让响应时间变得更快、更稳定。离线模式也会带来一些代价。本地模型能力通常弱于顶级云模型尤其是在复杂语义理解、长上下文推理和大规模代码重构上。为了弥补这个差距工程上需要做更多事情比如建立更精确的代码索引、使用多轮工具调用来逐步获取上下文、把任务拆分给多个子 agent 分工协作甚至针对特定编程语言和代码风格做微调。从产品角度看离线不是目的而是手段。它用工程复杂度换取数据安全和可用性适合对保密性要求高的场景。1.4 Ante 这类工具的适用场景结合 single binary 和 offline 这两个特点Ante 这类工具最适合的场景基本可以概括成三类。第一类是高保密内网研发环境源代码不能出内网但团队又想用 AI 辅助编码于是本地部署 agent 就成了最现实的方案。第二类是离线开发环境比如飞机、船舶、野外作业等场景网络不稳定甚至完全没有网络开发者依然需要 AI 帮忙生成单元测试、修复语法错误。第三类是追求低摩擦的独立开发者或小团队他们不想折腾模型部署和依赖安装拿到一个二进制文件就能立刻开始使用。当然这类工具也有明显的边界。它不适合那些需要最新领域知识的任务因为本地模型的知识截止日期通常较早也不适合需要超长上下文的项目级重构因为本地模型上下文窗口有限。在实践中比较常见的使用方式是让 agent 完成局部的、明确的目标比如“给这个函数补充参数校验”“把这几处重复代码块抽取成公共方法”“为这个模块补上单元测试”而不是让它在完全没有人工干预的情况下重写整个系统。2. 环境准备与整体架构2.1 示例环境说明为了把概念落到代码上这里准备一个最小可运行的示例。我选择 Python 3.10 配合 Ollama因为本地只需要跑一个小模型就能体验类似 Ante 的 offline coding agent 工作链路。Ollama 是一个本地模型运行时它提供简单的 REST API支持在 macOS、Windows、Linux 上运行并且能离线加载已经下载好的模型。版本这一块不要照搬需要根据你的实际情况调整。本文示例使用的模型是 qwen2.5-coder:3b它是阿里推出的代码模型系列之一3B 参数量在个人电脑上可以运行。下载完成后即使断网也可以调用。如果你的显卡显存较大可以换成 7B 或者 14B 的模型效果会更好但显存占用会相应增加。为了保证示例可复现建议先创建一个干净的目录避免和其他项目混在一起。2.2 整体架构一个 offline coding agent 从架构上可以拆成五个层次。最上层是交互层负责接收用户输入和处理输出通常表现为命令行或者 IDE 插件第二层是任务管理层把一个较大任务拆成若干可执行的步骤并且维护一个状态机第三层是上下文构建层从代码库里提取与当前任务相关的文件片段、符号定义、调用关系第四层是推理层调用本地模型生成决策和代码最下面是工具执行层提供读文件、写文件、执行命令、运行测试等能力。层与层之间通过结构化消息通信。这个架构和 Ante 这类单二进制产品并不矛盾。二进制只是最终分发形态内部的模块化设计仍然非常重要。把上下文构建、推理调度、工具执行分离才能让 agent 的行为可控。如果全部混在一起一旦任务失败你很难判断是模型能力不足导致还是工具调用链路出错。分层之后每一层都能独立测试和优化。2.3 agent 主循环Coding agent 最常见的运行方式是一个循环每一步都包含观察、决策、行动、验证四个环节。观察是从工具执行层获取当前代码库的真实状态比如“读取了某个文件的第 30 到 60 行发现异常处理缺失”。决策是模型基于当前状态选择一个动作可能是继续读别的文件也可能是修改代码还可能是运行测试。行动是工具执行层真正修改文件或者执行命令。验证是再次读取结果判断任务是否已经完成。这个循环会一直持续到模型认为任务完成或者达到我们设置的最大步数上限。为了不让 agent 无限循环下去实际产品里通常还有预算控制和时间限制。在接下来的核心原理拆解里我会重点分析这个循环中的几个关键设计点包括上下文怎么选、工具怎么命中、任务怎么规划。3. 核心原理拆解3.1 上下文构建策略大模型本身并不知道你的代码长什么样所以要在 prompt 里提供给模型相关信息。关键问题是怎么选取信息。最粗糙的做法是把整个代码库塞进 prompt但绝大多数项目远超模型上下文窗口。更合理的做法是先把代码库构建成一个可检索的索引。例如可以用 tree-sitter 提取出所有函数名、类名、变量名形成符号表再维护文件路径到代码行的映射。当任务到来时agent 先判断任务涉及的关键词比如“订单列表”会触发搜索 Order、order、list 等关键词找到相关文件再读取这些文件的内容片段。如果上下文还是不够agent 会进一步读取被引用的函数定义或者在修改点附近扩大读取范围。回到实战我们可以用文件列表和 grep 搜索代替完整的语义索引作为第一版实现。这种做法在小型项目里已经够用而且实现成本低。真实产品往往需要更复杂的索引机制尤其是大型仓库因为搜索会变慢、上下文会爆炸。但无论简单还是复杂目标只有一个在有限上下文内尽量覆盖任务真正涉及的代码。3.2 工具调用的设计工具调用是 coding agent 和普通聊天机器人的本质区别。聊天机器人只负责生成文本coding agent 必须能真正读取文件和修改文件。为了让模型可靠地调用工具一般会给模型提供一个工具清单每个工具都有名字、描述、入参格式。模型的任务是在某些时刻返回一个结构化的调用请求比如 read_file(service/UserService.java, 10, 80)。工具执行层收到请求后执行对应的函数再把执行结果返回给模型。在演示代码里我会选择一种更简单直接的方式让模型输出 JSONJSON 里带上 action 字段和参数。工具层解析这个 JSON执行相应动作把结果追加到对话历史。这种方案对开源模型友好主要原因是它不需要依赖模型特殊的 function calling 支持只要模型能生成符合格式的 JSON 就可以。真实产品则通常使用厂商提供的 function calling 能力效果更稳定但原理上是相近的。3.3 任务规划与 Plan/Coding 分离在 Ante 这类工具里plan 和 coding 往往是两个阶段。Plan 阶段agent 只做分析不修改任何文件。它会阅读相关代码整理出将要修改的清单可能还会生成一份 diff 预览。用户确认无误后agent 才进入 coding 阶段真正应用修改。这样做有两个好处一是防止模型理解错误后对代码库造成破坏二是让用户对修改范围有知情权减少“AI 偷偷改了很多我不想要的代码”的情况。在实现时plan 和 coding 可以共用一个工具集只是阶段不同。Plan 阶段把写文件、执行命令的权限关掉只开放读文件、搜索和 diffcoding 阶段才打开写权限。这种权限模型也能扩展到更细的粒度例如允许写测试文件但不允许写生产文件。在团队协作中这种权限控制主要是给人类留一个确认的窗口确保每一次改动都经过人工审阅。3.4 多 agent 协同与任务拆分当任务很大时单个 agent 很容易迷失方向。于是一些系统引入多 agent 协同一个 manager agent 负责拆解任务多个 worker agent 分别处理不同模块。worker 读取代码、执行修改把结果汇报给 managermanager 汇总后进一步分配任务。它们之间的消息可以看成一种轻量级协议包括“已完成部分”“遇到阻塞”“需要更多上下文”等状态。多 agent 协同的难点在于状态一致性和冲突解决。两个 worker 如果同时修改同一个文件可能会互相覆盖。比较好的做法是让不同 worker 负责不同模块尽量避免修改同一文件或者在写入前用 git diff 检查变化如果冲突则交给 manager 裁决。对个人开发者来说单 agent 已经足够多 agent 更适合大型项目和企业级流水线。至少从成本角度看单 agent 更容易调试和维护。4. 完整实战案例用 Python 实现一个迷你 offline coding agent4.1 案例目标与项目结构这一节我们用 Python 写一个非常小的 coding agent它能够读取工作区文件、修改文件并运行命令。它直接通过 REST API 调用本地 Ollama不依赖外网。先看一下项目结构mini-agent/ ├── agent.py ├── tools.py ├── config.json └── workspace/ └── demo.pytools.py 实现文件读写、命令执行等基础工具agent.py 实现主循环与本地模型交互解析模型输出执行工具workspace/demo.py 是待修改的示例文件作为 agent 的工作对象。config.json 可以存放模型名称、最大步数、工作区路径等配置这里为了简化直接在代码里写常量。接下来先写工具层。4.2 编写工具函数先看 tools.py。它的职责是让 agent 具备与文件系统和命令行的交互能力。代码里保留了明确的函数接口这样后续扩展工具也会比较方便。# 文件路径mini-agent/tools.py from pathlib import Path import subprocess def list_files(rootworkspace): 列出工作区内的所有普通文件。 return [str(p) for p in Path(root).rglob(*) if p.is_file() and .git not in p.parts] def read_file(file_path, start_line0, end_lineNone): 读取指定文件的行区间默认读取整个文件。 lines Path(file_path).read_text(encodingutf-8).splitlines() if end_line is None: end_line len(lines) return \n.join(lines[start_line:end_line]) def write_file(file_path, content): 写入文件注意这里有意保留覆盖语义。 Path(file_path).write_text(content, encodingutf-8) return fwritten {file_path}, {len(content)} chars def run_command(cmd): 执行一个 shell 命令并返回标准输出和错误输出。 result subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue) return result.stdout result.stderr这个工具集虽然只有四个函数但已经足够演示上下文读取、修改代码和验证结果三个典型动作。在真实项目里你会希望把 run_command 的权限收紧比如限制只能运行测试命令不能执行删除文件等高危操作。4.3 编写主循环代码接下来是 agent.py。我使用 Ollama 的 /api/chat 接口并开启 JSON 格式输出让模型返回结构化动作。主循环的思路是每次把当前任务和工具结果放进 messages让模型给出下一步动作工具层执行后把结果加回 messages直到模型输出 done 或者达到最大步数。# 文件路径mini-agent/agent.py import json import urllib.request from tools import list_files, read_file, write_file, run_command OLLAMA_URL http://localhost:11434/api/chat MODEL_NAME qwen2.5-coder:3b MAX_STEPS 10 def chat_with_model(messages): payload { model: MODEL_NAME, messages: messages, stream: False, format: json } req urllib.request.Request( OLLAMA_URL, datajson.dumps(payload).encode(utf-8), headers{Content-Type: application/json} ) with urllib.request.urlopen(req, timeout120) as resp: data json.loads(resp.read().decode(utf-8)) return json.loads(data[message][content]) TOOL_MAP { list_files: lambda args: list_files(), read_file: lambda args: read_file( args[file_path], int(args.get(start_line, 0)), int(args.get(end_line, 100)) ), write_file: lambda args: write_file( args[file_path], args[content] ), run_command: lambda args: run_command(args[cmd]), } def agent_loop(task): workspace_files list_files() system_msg { role: system, content: ( 你是一个运行在用户本机的离线代码智能体。你有四个工具 list_files、read_file、write_file、run_command。 你需要以 JSON 格式返回下一步动作。 格式{\action\: \read_file\, \file_path\: \...\, \start_line\: 0, \end_line\: 20} 或者 {\action\: \done\, \summary\: \任务完成\}。 不要尝试修改工作区以外的文件。 ) } user_msg { role: user, content: ( f任务{task}\n f当前工作区文件列表{workspace_files}\n 请根据任务逐步读取必要文件并完成修改最终输出 done。 ) } messages [system_msg, user_msg] for step in range(MAX_STEPS): print(f STEP {step 1} ) reply chat_with_model(messages) print(模型动作, json.dumps(reply, ensure_asciiFalse)) action reply.get(action) if action done: print(完成信息, reply.get(summary, )) return if action in TOOL_MAP: try: result TOOL_MAP[action](reply) except Exception as e: result f工具执行失败{e} else: result 未知 action请重新给出动作。 messages.append({role: assistant, content: json.dumps(reply, ensure_asciiFalse)}) messages.append({role: user, content: f工具执行结果\n{result}}) print(达到最大步数自动停止。) if __name__ __main__: task input(请输入任务描述) agent_loop(task)这里有一个关键设计工具执行结果会拼成一段文本继续发给模型。模型看到结果后再决定是继续读取其他文件还是开始写文件或者运行命令验证。它的记忆完全依赖 messages 里的历史消息因此 messages 会越来越长。为了控制长度真实产品里通常会对历史做截断或摘要。4.4 准备示例文件创建工作区示例文件 workspace/demo.py