Coding Agent:执行闭环、会话隔离与监控实践
用 Go 构建一个可验收的 Coding Agent:mewcode 的执行闭环、会话隔离与监控实践
从终端编程助手到网页工作台,记录一个 Coding Agent 如何组织工具调用、验证代码、隔离会话,并用可解释的指标评估任务结果。
本文于 2026 年 10 月 12 日整理,源码参考版本为 2d51832。
1. 项目背景:让读者能够亲自验证 Agent 的能力
当一个编程 Agent 收到“修复购物车总价计算的问题,并运行测试”这样的请求时,用户希望看到一条完整的工作链路:找到相关文件,理解错误,修改代码,执行测试,再给出有依据的结论。这个过程同时涉及模型决策、文件操作、命令执行和结果验证,任何一个环节缺失,用户都很难判断任务是否完成。
mewcode 是一个使用 Go 实现的 AI 编程助手。它的核心是工具调用循环,终端版围绕这个循环提供模型适配、权限检查、上下文压缩、会话恢复、Skills、MCP 和多 Agent 协作等能力。在此基础上,项目增加了一个名为 Coding Agent 的网页工作台,让访客通过浏览器体验一次完整的代码修改过程。
网页版的主要使用场景是项目展示。HR 可以直接打开页面,了解项目能做什么;技术面试官可以查看执行轨迹、工作区文件和验证结果,进一步讨论架构设计。访客无需注册账号,进入页面后就能创建自己的对话。每个新对话包含一个独立的购物车示例,也可以根据用户要求创建静态网页或小游戏。
这样的展示方式对工程设计提出了具体要求。不同访客的历史和代码必须分开,同一个访客创建的不同对话也不能相互污染;模型调用需要有成本记录;执行错误需要可见;生成的网页需要有实际打开和操作的入口。围绕这些要求,项目逐步形成了“执行、验证、反馈、监控”的完整链路。
2. 整体架构:共享核心,按入口组织能力
项目有两个主要入口:cmd/mewcode 对应终端助手,cmd/mewcode-demo 对应网页演示服务。二者复用 Agent、LLM、工具、文件历史和监控等基础模块,但面向的使用环境不同。
终端版面向开发者的本地工程,可以根据配置加载项目指令、持久化记忆、MCP 工具和子 Agent。网页版面向匿名访问者,使用服务端创建的独立工作区,只注册演示所需的工具,不加载全局记忆,也不把完整宿主机工程交给模型。
几个核心模块的职责可以概括如下:
| 模块 | 主要职责 |
|---|---|
internal/agent | 驱动模型与工具迭代,处理验证和恢复 |
internal/llm | 适配模型协议,统一流式事件和错误类型 |
internal/tools | 管理工具定义、参数和执行结果 |
internal/permissions | 判断工具操作的权限边界 |
internal/toolresult、internal/compact | 管理工具结果预算和会话压缩 |
internal/filehistory、internal/session | 保存文件快照、消息及工具调用记录 |
internal/demo | 组织网页会话、容器执行、预览、额度和监控 |
这种拆分让网页能力能够建立在已有核心之上。后续替换模型协议、改进压缩策略或修复执行逻辑时,可以在相应模块内处理;网页层主要关注访客归属、任务状态和展示方式。
3. Agent 的工作方式:围绕工具结果持续决策
从当前实现看,mewcode 采用的是工具调用驱动的迭代循环。模型根据用户请求和已有上下文决定下一步动作,系统执行工具,将结果写回会话,然后再次调用模型。工具返回的文件内容、测试输出或错误信息,都会成为下一轮决策的依据。
这种思路与 ReAct 强调的推理和行动交替有相通之处。ReAct 论文讨论了模型如何通过外部行动获取信息,并据此调整后续决策。这里用“类似 ReAct 的工具循环”描述工作方式更合适:项目使用模型协议中的结构化工具调用,没有要求所有模型都输出固定格式的 Thought、Action 和 Observation 文本。
下面的伪代码展示了主流程,实际实现还包含流式事件、取消、压缩和错误恢复:
接收用户任务
初始化当前会话与任务状态
循环:
构建提示词和可用工具描述
管理工具结果预算与上下文长度
调用模型并接收流式事件
如果模型请求工具:
检查参数、权限和路径
执行工具并保存结果
将观察结果写回当前会话
进入下一轮
如果模型准备结束:
根据配置运行验证门
验证失败时注入证据并尝试恢复
保存最终状态和执行记录
结束本轮任务
核心循环没有拆成独立的 Planner 服务和 Executor 服务。模型可以在执行中调整策略,例如读完文件后改变修改方案,或者根据测试失败信息补充一次修复。终端版提供的计划模式则是一种工作流与权限约束:允许先分析和形成计划,再进入实施阶段。它与独立规划器、执行器分工的架构需要分别理解。
在交互层面,流式事件让用户能够观察 Agent 正在做什么。网页可以逐步展示模型文本、工具调用、工具结果、重试和验证证据,用户也可以请求取消当前任务。一个任务的执行过程由明确的事件和状态组成,便于展示,也便于后续统计。
4. 工具边界:把模型决策转换为受控操作
模型生成的工具调用需要经过宿主程序处理。工具名称是否存在、参数能否解析、文件路径是否允许访问、命令是否属于可执行集合,都应由代码决定。
终端版的权限检查包含计划文件例外、安全命令、危险操作检测、路径沙箱、规则引擎、会话级授权和权限模式等分支。在适用的操作系统上,还可以结合系统沙箱。权限检查与具体工具执行分开,使读取、写入和命令操作能够遵循各自的规则。
网页演示版进一步收紧了可用能力。它注册读取、写入、编辑、搜索、受限命令和预览等工具,所有文件操作都绑定到当前会话工作区。路径解析会检查 .. 逃逸、符号链接、内部状态目录等情况,阻止模型通过文件参数访问工作区之外的内容。
命令执行采用固定允许列表,例如:
go test ./...
go test -v ./...
go vet ./...
go build ./...
这些字符串被映射为明确的程序和参数,再交给执行器处理。网页版没有提供任意 shell 命令入口,因此模型不能通过追加管道、命令替换或下载脚本来扩展执行范围。当前演示的依赖和工具链需要预先准备,工作容器不能在任务中临时联网下载软件。
另一个容易被忽略的环节是文件历史。编辑前,文件工具通过 TrackEdit 保存原始内容;任务边界创建快照并持久化。这样,当验证失败需要回退时,恢复逻辑可以找到修改前的文件状态。文件备份与会话记录共同构成了可恢复执行的基础。
5. 会话隔离:浏览器归属、上下文和工作区一起管理
面向匿名访客时,隔离需要贯穿 API、模型上下文和文件操作。给页面添加一个会话编号,只解决了显示问题;服务端还需要检查这个编号属于谁,以及执行时使用了哪些数据。
网页版为浏览器生成随机访客凭证,通过 Cookie 发送,并在服务端使用其哈希关联会话。Cookie 配置了 HttpOnly 和 SameSite;使用 HTTPS 公网地址时设置 Secure。读取会话、查看文件和获取预览时,服务端都会检查访客归属。即使知道其他会话的 ID,也不能仅凭这个 ID 读取对方的数据。
这种机制支持免注册体验。它代表浏览器持有的匿名归属凭证,不能等同于实名身份;同一个浏览器配置中的标签页会共享这组归属,而无痕窗口通常使用另一组 Cookie。清除 Cookie 或更换访问域名后,原来的会话不会自动出现在新浏览器环境中。
在模型层面,每个会话都有自己的 conversation.Manager,保存该对话的消息和工具结果。网页任务不加载终端版的全局记忆,另一个对话的历史不会被直接加入当前模型请求。这个边界对演示特别重要:访客 A 告诉 Agent 的验收要求,不应该成为访客 B 的隐含前提。
在文件层面,每个新会话都有独立目录,并从原始示例初始化。
因此,在 A 中修复 cart.go 后,B 中仍然保留原始错误,能够再次完整演示修复过程。同一个访客新建两个对话,也遵循相同规则。网页中的 /new 和 /clear 都会创建新的独立对话,原对话和文件继续保留在列表中;这里的 /clear 需要按网页端的实际语义理解。
在运行层面,每次任务会启动独立 Docker 工作容器,仅挂载当前会话的工作区。模型密钥由主服务持有,工作容器不接收 API Key,也不挂载 Docker socket。
当前执行器设置了无网络、只读根文件系统、只读工作区挂载、非 root 用户、移除 capabilities、禁止新增权限,以及 CPU、内存和进程数约束。文件编辑由主服务中的受限工具完成,容器用于编译、测试和检查。这样的职责分工让文件操作边界与运行环境边界能够分别审查。
容器与宿主机共享内核,Docker daemon 也有较大的控制权限,因此这套方案适合当前受限演示场景。对更复杂的公开代码执行平台,还需要评估独立执行节点、rootless 容器或更强的隔离方式。Docker 官方安全文档也将内核隔离、资源约束、daemon 权限和容器配置列为需要共同考虑的因素。
6. 验证门:让测试证据进入结束流程
Agent 输出一段完成说明时,系统仍然需要判断验证是否充分。mewcode 在核心循环的结束位置提供 VerificationGate,让验证结果参与任务结束和恢复流程。
网页版为每次任务启用验证门,并根据实际修改分类处理。如果修改了 Go 代码,就在当前工作容器中执行 go test ./...;如果生成的是静态网页,则返回部分验证信息,提示用户在运行预览中继续操作;如果没有修改文件,则说明当前任务没有需要执行的代码验证。
验证结果包含三种主要语义:
| 结果 | 在项目中的含义 |
|---|---|
PASS | 当前验证项通过,附带实际证据 |
FAIL | 验证发现问题,进入恢复或最终未验证流程 |
PARTIAL | 已有部分结果,但验证范围有限,需要结合说明继续验收 |
当前核心循环允许 PARTIAL 结束本轮执行,所以页面显示流程完成时,仍然需要阅读验证证据。例如,静态网页已经生成且可以打开,不代表游戏规则、键盘输入和重新开始功能都已自动测试。这也是项目额外提供用户验收反馈的原因。
验证失败后,系统把失败证据写回会话,要求 Agent 根据问题继续修复。随着验证重试推进,可以通过文件历史回退到任务前的快照,再尝试执行。恢复次数有边界;验证无法完成或重试耗尽时,会保留相应状态和证据。
以购物车示例为例,演示过程包含:读取代码与测试、发现循环漏算最后一项、修改实现、执行测试、展示测试输出。即使模型在解释中判断自己修复了问题,验证门仍会执行实际测试,使最终说明能够对应到可查看的证据。
这套设计把验证变成了控制流程的一部分。测试的价值同时体现在两处:发现错误,以及为用户提供判断任务结果的依据。
7. 上下文管理:控制体积,同时保留任务线索
编程任务的上下文容易增长。多次读取文件、搜索代码和运行测试后,工具输出可能占据较大比例。简单裁掉历史会丢失关键线索,而不断追加全部内容又会增加 Token 消耗,并触及模型上下文窗口。
mewcode 使用两层处理。第一层由 internal/toolresult 管理工具结果预算,对超出预算的结果做落盘和替换,模型上下文中保留可引用的预览。第二层由 internal/compact 在会话接近阈值时生成摘要,并保留近期消息和恢复信息。
工具结果替换有一个具体约束:同一个 tool_use_id 的处理决定一旦确定,后续轮次就复用已经记录的预览。即使之后再次整理上下文,也不会随意改写前面已经发送过的替换文本。
这个约束是为了稳定模型可见的历史前缀,避免预算处理反复改变旧消息。它为适用的提示词缓存提供更稳定的输入,但实际缓存命中和费用收益仍取决于供应商、协议和请求内容,不能仅凭实现了替换状态就断言一定节省多少成本。
第二层压缩则更关注任务语义。项目维护恢复状态,在摘要后补充近期文件读取、激活的技能以及可用工具等信息。压缩边界也会持久化,使恢复会话时能够理解当前已经被摘要的上下文。
这部分设计有一个现实取舍:长任务必须控制输入体积,但摘要无法保证保留全部细节。因此,与其把所有要求都寄托在很长的历史文本中,更适合将任务状态、文件变更和验证证据组织成能够恢复的结构化记录。
8. 网页预览:让生成的作品能够打开和操作
静态网页任务需要另一种验收方式。Agent 创建 index.html 后,用户需要进入页面,点击按钮、移动角色或检查布局,才能判断结果是否符合要求。
项目为此增加了“运行预览”。后端读取当前会话中的 HTML 入口,检查引用的资源,把支持的本地 CSS、JavaScript、图片等资源打包为可以随预览文档加载的内容,然后在前端 iframe 中展示。
预览会检查资源路径,拒绝引用工作区外的文件和外部资源,并设置资源体积限制。生成文档包含 Content Security Policy,禁止网络连接、嵌套 frame、对象和表单提交等行为。前端 iframe 只开放脚本执行,没有开放同源权限,目的是将生成页面与主工作台的浏览器权限分开。
因此,当前演示适合本地资源组成的静态页面和小游戏。它没有为用户启动任意 Node.js、Python 或 Go Web 服务,也不承担 npm 依赖构建和后端数据库运行。模型提示词会引导网页任务使用本地 HTML、CSS 和 JavaScript,并通过 Preview 工具检查入口和资源。
Preview 检查能够发现入口不存在、资源越界和部分加载问题,游戏交互仍需要用户实际操作。把文件生成、预览加载和交互验收区分开,能够让页面上的完成说明更准确。
9. 监控指标:给每个数字明确的统计口径
项目的监控包含模型调用、Token、重试、工具错误、上下文压缩和运行时资源等信息。网页演示又增加了五个任务指标,用来回答更直接的问题:任务完成了吗、用户等了多久、消耗多少资源、工具是否可靠、执行是否高效?
9.1 Task Success Rate:由用户确认目标是否达成
任务成功率使用用户对已结束任务的验收反馈:
任务成功率 = 用户确认成功的任务数 / 已验收任务数
验收覆盖率 = 已验收任务数 / 已结束任务数
用户可以选择“已达成目标”或“未达成目标”。没有反馈的任务显示为待验收,模型的完成文本和测试通过不会直接替代用户反馈。
例如,10 个结束任务中只有 2 个得到反馈,且都被确认成功,那么成功率是 100%,验收覆盖率是 20%。这组数字只能说明已反馈样本的情况,因此必须同时展示覆盖率。重复提交相同反馈或改正反馈时,服务端会调整原任务记录,避免重复增加验收数量。
9.2 End-to-End Latency:记录服务端完整执行时间
端到端延迟从服务端接收任务请求开始,持续到任务结束,包含容器准备、模型调用、工具执行、验证和容器清理。它反映的是服务端的任务链路,不包含浏览器和公网之间所有传输耗时。
监控显示均值和近似分位数。平均值帮助观察总体情况,P95 可以反映较慢任务的体验。当前分位数基于延迟桶估算,阅读时需要结合样本数和桶边界;少量任务时,一个较慢样本就可能对结果产生明显影响。
9.3 Cost per Task:对费用已知的任务进行估算
单任务费用累加主执行循环中已返回 usage 的模型调用消耗,包含输入、输出和缓存 Token;重试请求返回的 usage 也会计入。单价单位为人民币每百万 Token,费用记录保存在任务结束信息中。
这里还需要明确当前采集范围:上下文压缩模块会直接调用模型生成摘要,这些请求没有产生网页任务消费的同一组主循环事件,因此摘要调用及其重试尚未纳入单任务费用。当前数字用于观察主执行循环的模型消耗,完整账单分析还需要补齐压缩调用的计量。
网页版使用自己的模型计费规则,可以通过配置提供输入、输出和缓存输入单价。它与终端通用计量模块中的默认费用记录有不同口径,不能直接混用。
项目也处理了未知费用:模型没有对应单价,或者历史任务缺失必要 usage 信息时,显示待记录,计算平均费用时只使用费用已知的任务。未知样本不能算作零元,也不应按今天的单价重新推测历史支出。这里记录的是模型费用估算,不包含服务器成本、套餐优惠或供应商账单调整。
9.4 Tool Call Success Rate:只统计已经返回的调用
工具成功率的分母是已返回的工具调用次数,分子是其中未返回错误的次数。仍在执行中的工具不会提前进入分母,避免长调用尚未结束时拉低指标。
这个指标用于观察工具执行可靠性,还可以结合工具类型、错误次数和耗时查看具体问题。一次失败测试调用也可能是正常诊断过程的一部分,例如修复前运行测试发现原始 Bug,因此工具成功率需要与任务结果一起理解。
9.5 Average Steps per Task:以模型调用尝试作为一步
当前项目将一次主执行循环中的模型调用尝试计为一步,主循环重试也计入。压缩摘要的模型调用没有发出相同的计步事件,因此尚未进入步数统计。它没有把一句思考文本算作一步,也没有将工具调用次数直接等同于模型步数。
平均步数使用有步数记录的结束任务。对于缺少事件的旧数据,无法可靠恢复的样本不参加均值。分析执行效率时,还应结合成功率、延迟和费用:某个任务步骤较少,但没有完成用户目标,其效率指标就需要重新理解。
监控实现还控制了指标标签。HTTP 使用路由模板,工具按有限名称分类,避免把会话 ID、提示词或任意文件路径变成 Prometheus 标签。这样既能减少时序数量增长,也能降低监控数据携带原始对话内容的风险。
10. 每日额度与管理入口:让公开体验有可调整的成本边界
网页版在左下角提供每日 Token 额度和运行监控入口。管理员需要输入密码,验证成功后获得短期令牌;令牌保存在页面内存中,关闭入口会退出,过期后需要重新验证。服务端也限制连续错误密码尝试。
访客可以免注册使用自己的会话,而修改全站额度和查看管理员汇总需要单独授权。这种做法满足当前项目展示的交互需求,也避免为一次体验引入完整账号系统。
部署模板将任务超时、每日任务数和模型轮数配置为不限制,同时保留并发限制、容器资源约束和每日 Token 额度。这几个参数处理的是不同问题:并发和容器资源保护服务器,Token 额度管理模型消耗,模型本身的上下文与输出限制则仍然存在。
每日额度由管理员调整,并写入 quota.json,重启后继续读取已保存的设置。用量按 UTC 自然日统计,北京时间每天 08:00 切换到新的一天。
当前每日用量通过主执行循环的 usage 事件更新,压缩摘要的模型消耗尚未纳入这个额度统计。额度检查发生在主循环模型调用结束、usage 返回之后,因此某次调用可能消耗超过剩余额度的 Token。并发调用也会带来已经发生的消耗。它能够为已计量的调用提供服务级的每日预算控制,供应商侧的账单硬限制仍需要结合供应商设置。若未来需要更严格的实时控制,应先统一主循环与压缩调用的计量,再增加调用前预算预留和调用后结算。
11. 持久化和并发:支持恢复,同时说明统计范围
网页数据保存在各会话目录中,包含历史、事件、任务反馈和监控汇总;每日用量与额度保存为服务级状态。终端版则使用追加式 JSONL 会话日志,保存消息、工具调用、工具结果和压缩边界,便于恢复执行上下文。
流式事件数量需要有上限。若页面展示只保留最近一部分事件,历史 Token、工具次数和任务指标不能因此一起消失。项目将累计监控汇总与展示事件分开保存,使新记录的统计能够在事件裁剪和重启后继续恢复。
同样需要说明的是数据保留范围。默认根据会话的最后更新时间计算保留时长:超过 24 小时后工作区过期,超过 7 天后清理整个会话,运行中的任务会被跳过。单纯打开页面或查看文件不会自动延长这个时间。当前保留会话的汇总与当天全服务用量有不同统计范围;删除或清理会话后,对应的历史汇总也会移除。如果需要长期时序,可以使用可选 Prometheus 模板持续采集。
并发方面,服务限制同时运行的任务数,同一个会话也不会同时启动两个任务。会话状态由相应锁保护,而 conversation.Manager 本身没有内置互斥锁,调用方应维持明确的写入归属,避免多个 goroutine 同时追加模型历史。
这些设计适合当前单实例展示服务。如果未来运行多个服务副本,就需要重新组织共享状态、分布式任务调度和统计去重。当前文件持久化方案没有提供跨实例的数据协调能力,这也是后续扩展时需要优先处理的边界。
12. Linux 部署:让运行环境和验收步骤能够复现
项目为 Ubuntu amd64 准备了部署文档和配置模板。主服务通过 systemd 管理,监听 127.0.0.1:18893,每次任务由 Docker 创建工作容器;私有监控监听 127.0.0.1:18894。对外访问计划接入已有 Cloudflare Tunnel,主服务不需要直接开放公网入站端口。
模型密钥和管理员密码由服务器环境文件提供。程序、环境配置和运行数据分别位于不同目录,便于控制访问权限、更新程序和备份状态。管理员修改的额度保存在数据目录中,更新版本时需要保留。
考虑到服务器直接访问 GitHub 或 Docker Hub 可能超时,项目提供 Windows 打包脚本,生成 Linux amd64 二进制、部署文档和配置模板组成的离线安装包。工作镜像也可以在可联网设备导出,再上传到服务器导入。
执行镜像预装 Go 工具链,任务中关闭工具链和模块在线下载。当前示例不需要额外依赖,因此可以在无网络容器中测试。这个方案的收益是运行环境容易复现,相应取舍是演示不能自由安装任意外部依赖。
部署文档还记录了一个权限细节:工作容器使用 UID 1000,而主服务用户的 UID 未必相同。工作区文件需要具有合适的读取权限,因此服务使用 UMask=0022;私有会话根目录和状态文件则显式设置更严格的权限。应用层的会话路径检查与操作系统文件权限需要一起工作。
部署验收覆盖主服务健康检查、真实模型任务、浏览器归属隔离、静态网页操作、管理员额度调整和重启后状态恢复。更新前等待活动任务结束,再停止服务、备份、替换二进制并检查健康状态;回滚程序与恢复数据分别处理。
项目此前在 Linux amd64、Go 1.25.0 容器环境通过了全量测试、构建和静态检查。Docker 端到端测试还检查容器约束、原始示例测试失败、修复后测试通过、另一会话文件保持原状,以及执行容器清理。这些结果验证了对应链路,实际 Ubuntu 服务启动和 Tunnel 配置仍按部署文档验收。
13. 现阶段的取舍与后续方向
mewcode 的终端版已经包含较完整的扩展机制,网页展示则主动限定了运行能力。这样的范围让访客能够反复体验同一个案例,也让开发者能够把隔离、验证和监控讲清楚。
后续值得推进的工作包括静态网页的自动浏览器验收:将截图、键盘输入和功能断言作为验证证据,同时继续隔离生成页面的权限。对于任务成功率,可以引入固定任务集和自动判定,补充当前用户反馈的覆盖不足。对于费用控制,需要先将压缩摘要请求统一纳入步数、成本和预算计量,再实现预算预留与结算,减少并发调用下的额度超支。
如果展示服务发展为更通用的编程平台,还需要增加依赖构建能力、执行节点隔离、持久任务队列以及多实例状态管理。MCP、Skills 和多 Agent 协作可以在终端版已有实现上继续扩展,但每一项接入网页时,都需要重新审查它对宿主机和其他会话的访问范围。
这次项目实践中,我最关注的是各层如何共同支持一个能够验收的结果:模型决定下一步动作,工具执行受控操作,验证门把证据带回流程,会话边界保护历史和文件,监控记录结果与消耗。用户可以沿着这条链路观察、操作并判断 Agent 的工作,而开发者也能用同一组记录分析问题和改进实现。
源码阅读与部署文档
想进一步查看实现,可以从以下文件开始:
本文依据项目当前实现撰写。示例比例用于解释统计口径;文中的后续方向不代表已实现功能,模型费用也以配置和供应商实际账单为准。