复刻Microduck：开源AI编码Agent实战全记录

说实话我这个月已经不止一次被同一个名字刷屏Microduck。第一次是在一个技术群里看到有人问“这玩意到底和 Cursor 差多少”第二次是看别人在终端里用几句自然语言把一个拖了三天的空指针问题直接定位到了具体调用链。问了一圈才知道它是个开源项目主打的是把大模型和命令行、编辑器工作流串起来做成一个可以私有部署的 AI 编码 Agent。我花了两周时间把它完整复刻了一遍中间踩了不少坑也把社区里流传的“microduck 怎么训练”“完整训练教程”这类问题都验证了一遍。这篇文章就按我实际操作的时间线来写想折腾的人可以少走点弯路。1. 复刻之前先想清楚 Microduck 到底在解决什么问题1.1 Agent 不是聊天机器人它要的是闭环很多第一次接触 Microduck 的人会下意识把它当成“能聊代码的 ChatGPT”。这个理解偏差会导致后面所有配置和微调动作都走歪。聊天机器人完成一次回答就算结束它不关心你把这端代码粘回去之后能不能编译。编码 Agent 不一样它得对动作后果负责。Microduck 这个项目名有点自嘲的意思会让你联想到“小黄鸭调试法”——对着橡皮鸭一行行解释代码解释着解释着问题就暴露了。它想做的是把这套“解释、验证、修正”的过程自动化先理解仓库里和你需求相关的文件然后形成修改计划接着以补丁形式编辑代码再执行测试命令最后根据测试输出决定是否继续迭代。这个闭环里有几个容易被忽略的关键点。第一Agent 必须意识到“当前在哪个仓库”。同一段指令在 A 项目和 B 项目里可能指向完全不同的代码所以第一步要做仓库定位和符号索引。第二Agent 不能一上来就把整个代码库塞进上下文它需要靠检索先筛出候选文件再按需读取。第三每执行完一个工具动作都要把真实的 stdout、退出码、diff 结果拿回来重新交给模型判断而不是让模型自己脑补“文件已经被改好了”。我在复刻初期就犯过这个错误当时只跑通了一个“模型输出代码修改结果”的简单 Demo表面看起来好像能改代码但一放到多文件项目里就崩了。原因很简单模型生成了一个大 diff却没有真正执行任何命令去验证它只是在一本正经地“编造修改完成”。Microduck 这类开源方案真正值钱的地方就是它把这个闭环的骨架搭出来了你复刻一次就等于把这个认知补上了。1.2 为什么选择复刻而不是直接订阅商业产品也有朋友听说我在搞 Microduck第一反应是现在 Cursor、Codex 这些商业工具不是已经很好用了吗为什么还要折腾一个开源复刻这事得分场景。商业产品确实体验顺滑尤其是一键安装、内置模型、开箱即用这部分做得很成熟。但我在实际使用中遇到的瓶颈有三个一是代码仓库可能涉及公司内部敏感业务把整库上下文交给外部服务合规上总要打几个问号二是底模不可替换如果团队内部已经私有化部署了一个针对特定语言微调过的模型商业产品没法直接接进去三是调试空间有限你没法看到“它到底为什么选了这个文件”“工具调用的参数是什么”只能接受黑盒结果。复刻 Microduck 的方案就灵活很多。它把模型层抽象成了可配置接口后端可以接 OpenAI 兼容协议的服务也可以接本地部署的模型工具层是准入门制的允许执行哪些命令、不允许执行哪些都可以自己定义甚至连会话持久化、多轮上下文摘要这些细节也能按自己的需求改。当然复刻不意味着零成本。它要求你补不少工程功课比如检索索引怎么建、沙箱命令白名单怎么设计、模型返回的 JSON 不合法时怎么容错。不过这些功课本身就是价值你追着源码读一遍比看十篇概念科普都管用。2. 代码还没跑起来先把三个核心模块认清楚2.1 项目骨架和目录结构第一件事不是跑是读拿到任何开源项目我都会建议先别急着uv run或者pip install而是把目录结构从头到尾看一遍。Microduck 的整体骨架不算复杂但它把“Agent”这个词拆得很细。我复刻时梳理出的核心目录大致是下面这个样子microduck/ ├─ core/ │ ├─ runtime.py # 会话运行循环 │ ├─ session.py # 上下文会话状态 │ └─ context_engine.py # 仓库检索与上下文组装 ├─ agents/ │ ├─ plan_agent.py # 负责拆解需求、生成操作计划 │ ├─ edit_agent.py # 负责具体文件修改 │ └─ review_agent.py # 负责检查 diff 和测试结果 ├─ tools/ │ ├─ grep_tool.py # 语义化封装 grep/rg │ ├─ edit_tool.py # 基于锚点字符串的精准编辑 │ ├─ run_tool.py # 执行沙箱命令 │ └─ read_tool.py # 按范围读取文件 ├─ llm/ │ ├─ provider.py # 模型接入抽象 │ └─ schemas.py # 工具定义与输出解析 ├─ configs/ │ └─ default.yaml # 默认配置入口 └─ eval/ └─ run_bench.py # 评测集运行脚本core是整台机器的控制台不绑定具体模型它只负责维护会话状态、决定什么时候该结束循环、怎么把上一轮工具执行结果塞回消息列表。agents是不同角色的策略层你可以理解为“一个 Agent 内部其实有好几个不同分工的小模型在接力”。tools是 Agent 的手脚每个工具都必须暴露统一的入参和返回值结构。我最开始犯的错是把注意力全放在agents/里以为复刻 Agent 就是复刻这里的提示词。后来发现真正让系统稳定运行的是core/runtime.py和tools/这两个底层模块。工具定义得越清晰、执行结果越结构化上层模型就越不容易乱来。2.2 Agent 主循环控制流比模型能力更见功夫Microduck 的主循环逻辑不复杂一句话版本就是把用户指令喂给模型让模型决定调用哪个工具工具执行完把结果喂回去再让模型决定下一步直到模型觉得任务完成或超出最大步数。我当时把这套逻辑简化成了下面这段伪代码方便理解def run_agent(instruction, repo): ctx build_initial_context(repo, instruction) messages [ system_prompt(), user(instruction), context_block(ctx), ] for step in range(MAX_STEPS): action llm.tool_choice(messages, tools) if action.type finish: return action.summary observation tool_executor.execute(action) messages.append(observation) return max steps exceeded真正写起来需要处理的细节比这多得多。比如模型返回的工具调用参数缺了必填字段怎么办工具执行超时怎么掐断测试命令返回非零退出码时Agent 是应该继续修还是停下来如果 Agent 陷入“改代码、跑测试、再改代码”的死循环什么时候该强制退出。这些都属于控制流设计不是模型能力问题。一个顶尖模型配上糟糕的控制流也会反复执行同一个错误命令一个中等模型配上明确的控制流反而能稳定完成任务。复刻时一定要记住Agent 质量是“模型能力、工具协议、控制流”三者的乘积不是单看模型。2.3 上下文引擎让模型只看到它该看的代码另一个让我印象深刻的点是 Microduck 的上下文引擎。多数本地仓库动辄几十万行代码不可能全塞进模型上下文。它采用的办法是先做一次轻量级索引索引里记录符号名、文件路径、函数定义、类定义之间的引用关系然后根据用户指令里的关键字去匹配相关符号。举个例子如果指令是“给 auth/login.py 里的登录接口加上限流”普通的关键词检索可能只匹配到login.py和rate_limit这几个词返回一堆噪音。但符号级索引能理解“登录接口”可能对应def login():也能顺着路由装饰器找到它注册在哪个 URL 路径下。之后上下文组装阶段会把目标文件的代码块、相关依赖函数、最近的改动记录都放进去让模型拿到的是一个“精挑细选后的现场”而不是一仓库的原始材料。我后来自己接了一个向量检索库想替代这个逻辑结果发现纯向量检索的效果并没有想象中好。代码检索里很多需求是符号级别的精确匹配比如“找一下load_config的定义”这种场景用rg加文本正则反而更快更准。向量检索适合语义模糊的需求符号检索适合定位明确的改动Microduck 把两者结合成了一个级联检索策略这个设计思路很值得复刻。3. 真正决定效果下限的是模型路由和工具协议3.1 大模型分工一个 Agent 里同时跑多个模型一开始我以为 Microduck 只会调用一个模型。翻配置文件才发现它把模型层拆成了多个角色每个角色负责不同阶段。在它的默认配置里规划阶段使用一个偏推理的模型负责理解长指令、拆解操作步骤编辑阶段使用一个响应速度快的中小模型负责生成具体的代码补丁review 阶段再用另一个模型检查 diff 和测试结果。这种分工背后的逻辑很务实规划任务需要长上下文和强推理就找大参数模型扛编辑任务往往是局部修改用太快太贵的大模型反而浪费审查任务需要客观性换一个不同模型可以减少“自卖自夸”的问题。我在复刻时没有完全照抄这个默认配置而是先在本地把三个角色都指向同一个开源模型跑通全流程之后再按需拆分。这样做的原因是如果一开始就路由到不同模型出了问题你很难判断是哪个环节的模型选型不对。统一模型能先把控制流和工具协议调稳后面再逐个替换角色模型效果更可控。3.2 工具协议写不严谨再强的模型都会开始胡编在 Agent 系统里工具协议就是模型和真实环境之间的“语法契约”。Microduck 里的工具定义几乎都是严格的 JSON Schema 格式。我复刻时最常踩的坑不是模型不够聪明而是工具 Schema 写得太宽松导致模型返回了一堆没法解析的参数。这是我在本地配置里用到的编辑工具定义你可以直接抄走参考edit_file_schema { type: function, function: { name: edit_file, description: 在指定文件中执行唯一的字符串替换。old_string 必须与当前文件完全一致。, parameters: { type: object, properties: { file_path: { type: string, description: 相对仓库根目录的目标文件路径 }, old_string: { type: string, description: 原文中唯一定位的旧内容 }, new_string: { type: string, description: 替换后的新内容 } }, required: [file_path, old_string, new_string] } } }注意这里为什么要用old_string做锚点而不是告诉模型“去第 80 行改”因为模型对“当前文件的行号”没有可靠感知经过几轮编辑之后行号会漂移但字符串锚点只要存在就大概率能匹配上。实际执行逻辑会先调用工具在文件全文里查找old_string找不到就返回失败而不是直接按模型给的行号乱插。我给工具协议定了几条铁律第一参数一律用严格类型不要用“any”第二description 里要写清楚执行条件比如“old_string 必须与当前文件完全一致”第三每个工具默认只专注做一件事能拆就别合。比如“编辑文件并自动格式化”这种复合工具在 Microduck 里通常被拆成edit_file和run_command两步先改完再单独执行格式化命令这样每一步的结果都能被单独验证。3.3 系统提示词的长度不是加分项聊完工具协议再说提示词。Microduck 的系统提示词写得非常收敛没有那种上千字的长篇大论。我摘一段我在复刻里整理的版本重点不在措辞而在结构你是一个运行在 Git 仓库中的编码 Agent名字叫 Microduck。 你的工作方式是 1. 先理解并阅读相关代码再制定计划。 2. 使用工具执行操作不要假装操作成功。 3. 每次工具调用后必须等待真实结果再决策。 4. 如果测试失败根据报错信息修改代码最多尝试 5 次。 5. 输出最终结果时用简短条目列出修改过的文件和验证命令。 约束 - 只允许修改当前仓库内的文件。 - 禁止读取明显不相关的目录。 - 不要在一次 edit_file 里混入多个不相关修改。从这段能看到三个设计意图一是把“先读后改”写进了模型的行为模式二是强调“先观察真实结果再决策”切断了模型自己脑补成功路径的倾向三是用“最多尝试 5 次”限制无休止的自我修复循环。我自己的经验是系统提示词越长模型越容易注意力分散。真正需要增强约束的地方应该靠工具层的硬校验来解决而不是靠提示词苦口婆心。比如限制 Agent 只允许操作仓库内文件最好的办法是在工具执行层做路径校验而不是在提示词里写一百遍“你只能修改当前仓库”。4. 微调不是默认动作真要训得按数据闭环来4.1 先判断要不要微调社区里搜“microduck 怎么训练”绝大多数回答会直接甩给你一段 LoRA 脚本好像训练完就万事大吉了。我复刻之后反而觉得微调应该是最后一步不是第一步。我在自己跑完一整套流程后总结了三个信号。第一个信号是“格式稳定性差”模型经常在工具调用里给你返回非 JSON 内容或者参数名凭空改掉第二个信号是“定位能力弱”明明指定了文件路径它还是去检索了一堆无关文件第三个信号是“领域知识缺失”比如你的代码库里有一堆内部框架的约定俗成模型生成的代码不遵守这些约定。前两个问题通常换模型、调提示词、加输出解析容错就能解决一大半不建议一上来就微调。第三个问题才真正适合用微调来补充。如果你只是想让模型本地跑通训练动作可以先放一放把精力放在工具协议和控制流上收益会高得多。4.2 训练数据要从真实轨迹里清洗如果你确定要微调那数据的组织方式决定了效果上限。我参考了 Microduck 这类 Agent 项目常用的数据格式和普通文本生成数据的最大区别在于训练样本不仅要模型输出文字还要保留工具调用和工具响应。一份最小可用的训练样本长这样{ session_id: task_001, messages: [ { role: user, content: 给 auth/login.py 的登录接口增加基于内存的限流同一 IP 一分钟最多请求 10 次。 }, { role: assistant, content: null, tool_calls: [ { id: call_1, type: function, function: { name: grep_files, arguments: {\pattern\: \def login\, \path_prefix\: \auth/login.py\} } } ] }, { role: tool, tool_call_id: call_1, content: auth/login.py:42: def login(): } ] }这类数据的关键在于“交互轨迹”不是孤立的一问一答。训练数据要让模型学会“看完工具返回结果之后再做下一步决策”。如果数据里全是“问题-修改代码”的二段式样本模型学会的是跳步而不是通过工具验证来闭环。至于轨迹怎么挖最省力的方法是用一个性能不错的商业模型在若干干净仓库上跑任务把成功轨迹存下来。然后做清洗重点过滤两类脏数据一类是“执行失败但模型声称成功”的假成功样本另一类是工具调用了三次以上还在原地打转的冗余循环。清洗完可以估算一下数据保留率我自己的经验是原始轨迹留到手里能用的往往只有 30% 到 40%这很正常别心疼删除量。4.3 一个低成本 LoRA 微调参数参考如果只是针对自家代码风格或特定工具协议做适配不需要上全量微调。我建议从 LoRA 开始显存要求低实验成本也低。下面这组参数是从我的复刻实验里整理出来的不是标准答案但可以当作起点base_model: Qwen2.5-Coder-7B-Instruct lora_r: 32 lora_alpha: 64 lora_dropout: 0.05 target_modules: - q_proj - k_proj - v_proj - o_proj - gate_proj - up_proj - down_proj learning_rate: 2e-4 batch_size: 8 max_seq_len: 6144 epochs: 2值得多说一句的是max_seq_len。Agent 轨迹数据通常包含一大段代码片段和工具返回结果长度比普通问答长得多。如果按 2048 截断模型很难看到完整的“工具调用-返回-决策”链条。我实际跑下来 6144 起步比较舒服如果显存不够优先减 batch_size 而不是 max_seq_len。训练完成后也别急着说“训完了”。必须用同一批评估任务在微调前和微调后各跑一遍看工具调用格式错误率有没有下降、任务完成率有没有提升。我见过太多人微调完只拿几个对话测试就发帖说效果好一放到真实仓库环境里反而退化。为了模型调度避免使用vllm serve --disable-log-stats之类无所谓关键是“新问题上评估”。4.4 Eval 要防自欺尤其别在脏工作区里测评测机制是复刻时最容易被敷衍掉的部分。我当时一开始简单统计“10 条任务里成功 8 条”后来发现这个数字会骗人。骗子来自几个环节一是 Agent 工作过的工作区残留了上一轮生成的临时文件下一轮任务可能直接读取了这些脏状态导致结果“异常容易成功”二是评估任务太单一只测“修改单文件”没有覆盖“跨文件重构”“根据测试报错修 bug”这类真实场景三是忽略工具调用步骤的格式错误只要最终代码能跑就觉得成功实际上模型经常在过程中产生大量坏调用只是碰巧被后续修正了。我的改进方法是把评估指标拆成三层来记录工具调用格式合规率、补丁应用成功率、最终任务完成率。每层指标分别计算这样能清楚看出瓶颈究竟是模型不会调工具、还是工具编辑失败率高、还是规划阶段就跑偏了。评测还必须在每个任务开始前git checkout到一个干净的 baseline 分支确保工作区里没有上一条任务的残留。5. 复刻实操全记录从第一行命令到第一次自动修复5.1 环境初始化真正麻烦的是依赖版本复刻过程中最耗时间的不是模型配置而是环境初始化。Microduck 这种项目依赖几十个 Python 包里面有不少包之间的版本确实容易打架。我自己第一次直接pip install -r requirements.txt装到一半就崩了好在项目用了锁文件方案重新用uv sync拉取固定版本后顺利多了。如果你也想在自己的环境里复刻我建议 Python 用 3.11不要用 3.12 以下太老的版本也别直接跳到 3.13有些核心依赖还不一定支持。装完依赖之后先跑一遍项目自带的测试用例确认基础环境没问题再接入模型配置。这个顺序能帮你把“环境报错”和“模型配置报错”隔离开来。我在第一次运行测试时看到一个特别典型的报错ModuleNotFoundError: No module named watchdog但它明明在 requirements 里。最后排查发现是虚拟环境混用导致的当时有的包被装进了全局 Python 环境有的被装进了 venv。解决方法是把虚拟环境删掉重建用锁文件重新装一遍。环境干净以后后面排查问题就顺利很多。5.2 最小配置模型 API 和命令白名单跑通闭环需要的最小配置其实只有两块模型接入和命令白名单。Microduck 默认支持 OpenAI 兼容的模型接口所以我本地直接把服务地址指向一个私有化部署的兼容服务不需要改代码。配置文件大概是这样的model: provider: openai-compatible base_url: http://127.0.0.1:8000/v1 api_key: local-test-key planner_model: qwen2.5-coder-32b-instruct editor_model: qwen2.5-coder-7b-instruct sandbox: workspace: /home/user/projects/demo allowed_commands: - pytest - ruff - git diff - git status - python retriever: strategy: hybrid top_k_files: 5 top_k_symbols: 8 runtime: max_steps: 15 tool_timeout_seconds: 60allowed_commands是安全设计的核心。我不会在列表里塞rm -rf、git push这类危险命令也不会允许任意 shell 拼接。如果你确实需要 Agent 执行 npm install也建议放到一个隔离容器里而不是让它直接在你的常用目录里乱装东西。配置好之后先别急着跑复杂任务拿一个最小修改试试水。我当时先让它“把 README 里的项目名改成 Microduck-复刻版”这一步能验证模型接入、工具调用、文件写入、结果返回全链路是否正常。5.3 第一条真实指令从限流功能请求开始最小测试跑通之后我给 Microduck 下了一条略微复杂的指令给auth/login.py里的登录接口加上基于内存的限流同一 IP 一分钟最多 10 次并补充对应的测试用例。整个过程我看得很仔细。规划阶段它先列出几个搜索计划用grep_files找到了登录接口的函数定义并用read_file读取了文件上下文。几轮工具调用后它判断当前文件还没有现成的限流组件于是新建了一个rate_limiter.py在login()入口处加了检查逻辑最后在tests/目录下写了一个测试用例。第一轮测试跑挂在了 import 路径错误上。测试文件在tests/test_login_rate_limit.py里直接from app.auth.login import login失败了因为测试环境的根目录对不上。这个报错如果换个不熟悉 Python 工程结构的模型很可能就开始乱猜路径。Microduck 的表现是先调用run_command查看项目目录结构确认根目录下有一个pyproject.toml然后把测试文件改成基于pyproject.toml所在目录的导入方式再重新跑测试。第二轮测试通过还在终端里打印了简洁的总结列出了修改过的文件和验证命令。那一刻的观感确实不错很像一位同事在给你发“我改完了测试过了”的工作汇报。5.4 第一次跑崩看到“edit failed”怎么办没有 bug 的复刻经历是不完整的。我的第一次崩溃发生在它尝试修改一个多行函数的时候。当时工具层报了一个很具体的错误edit_file failed: old_string not found in auth/login.py我一开始以为是模型瞎编路径后来把模型传入的 old_string 和文件实际内容拉出来对比发现问题是这个函数里有一段缩进用的是空格模型从检索结果里拿到的内容却因为渲染原因把行首空格弄丢了。它拿一个丢失了前导空格的 old_string 去文件里搜索当然找不到。这个问题不是换个更聪明的大模型就能彻底解决的因为它属于“上下文中展示的内容和执行环境里的实际内容存在细微偏差”。我的处理方向是在工具层加一道防御先让模型通过read_file拿到最新的行区间内容然后在edit_file执行前再做一次旧字符串的模糊归一化匹配比如把连续多个空格当成同一语义来匹配。这个兜底写完之后类似报错明显减少。5.5 当 Agent 把自己改崩了怎么办还有一次更刺激Microduck 在修改一个核心配置模块时把原本能跑的初始化流程改崩了测试阶段直接抛异常。我观察到它接下来的动作是先自行分析报错尝试反向修复修了两轮没成功第三轮它开始调用git diff查看自己的改动状态最后通过git checkout -- auth/login.py把文件回滚到了修改前。这个自我回滚的能力让我比较意外。但后来我想想这正是命令白名单里允许了git diff和git status的价值当模型发现自己的修改把系统弄崩并且修复成本太高时它至少能看到自己改了什么也能判断是否需要回滚。需要提醒一句让 Agent 自动执行git checkout是一把双刃剑。如果没有在沙箱里限制回滚范围它可能会把你自己还没提交的其他改动也一起抹掉。所以我的建议是工具层要单独做一个“只在当前任务涉及文件列表内回滚”的防护不要简单粗暴地允许整仓git checkout。6. 从复刻到反哺聊聊个人实际体会复刻完 Microduck 之后我心里最大的变化是对“开源复刻”这几个字有了新的感受。以前看到热门开源项目习惯性做法是点个 star、拉个 README、收藏几个 issue然后就没有然后了。真正动手复刻一遍才会发现代码仓库里最值钱的东西不是那堆能跑的源码而是它的设计取舍为什么要把 Agent 拆成规划、编辑、审查多个角色为什么工具协议要采用精确锚点而不是行号为什么系统提示词要写得那么克制。这些问题不做一遍很难有体感但做过一次之后你在看任何同类项目时都会带着更深的判断力。我给想复刻 Microduck 的朋友一个建议不要急着把它接到生产环境也不要一上来就搞微调。第一次复刻的目标应该是“用真实任务跑通闭环、看懂每个模块为什么这么设计”。等整套流程都跑顺了再考虑让它去处理你仓库里那些真正让团队头疼的重复性修改任务。微调放到第三步第四步都不迟因为到那时候你才真正知道自己手里的脏数据应该清洗成什么样评测指标到底该盯哪个。我现在把这个复刻版 Microduck 用在个人项目里处理一些格式化迁移、加注释、按模板生成单元测试之类的事情。它偶尔还会出现小失误但重要文件我都会 code review不会让它直接推到主分支。工具就是这样你越知道它的边界在哪里使用起来就越安心。