1. 从会聊到会干活我为什么重新设计一个代码问答工具1.1 纯问答模式的三个死穴在决定动手做羲和XiheAgent之前我其实已经用了大半年的代码问答工具。日常查接口、问实现思路、让模型帮忙解释一段复杂逻辑体验都不错。但越用越难受尤其当我们团队开始面对真实工程任务时纯粹问答模式暴露出来的问题越来越明显。第一个死穴是答非所用。模型给的代码示例通常基于它训练时的记忆跟仓库当前真实状态往往有出入。你问它这个服务怎么做限流它能给你写一个漂亮的滑动窗口实现但落到我们自己的项目里依赖版本早就换代了现有的工具类它不知道项目里已经踩过的坑它也不知情。换句话说问答模式提供的标准答案和真实代码库之间存在一条需要人来补的鸿沟。第二个死穴是没有反馈闭环。传统问答工具本质上是单向的信息传递用户拿到答案后自己复制、修改、验证模型并不知道这段代码后来跑起来没有、有没有报错、性能是否达标。这个信息缺口导致模型无法从真实运行结果中学习每一次回答都是独立事件永远是冷启动状态。第三个死穴也是我做羲和最重要的动机问答没有状态无法执行多步任务。一个真实的工程任务比如把单测跑完、修复失败用例、然后打包部署到测试环境中间涉及读代码、改文件、执行命令、观察日志、再迭代。每一步的结果都会影响下一步的决策。纯问答工具没有任务上下文和执行状态的概念自然撑不起这种多阶段、带反馈的流程。这三个问题让我意识到团队真正需要的不是一个更聪明的问答机器人而是一个能把事情做起来的编码助手。这就是羲和的起点把代码问答当作入口把任务执行当作核心能力。1.2 羲和的定位问答只是入口执行才是价值羲和这个名字取意于上古太阳女神、日御者——能驾车带太阳走完每天的行程。我希望这个助手不只是告诉你太阳怎么转而是真的能驾驶日车去完成一段行程。翻译成工程语言就是系统既要有理解与规划的能力大模型也要有稳定执行的基础设施工具链、任务队列、状态存储。在设计之初我给羲和定了几条核心原则执行优先所有问答最终都要落到可执行的工具调用上凡是能通过工具验证的回答不允许只给一段代码让用户自己去试。状态可见任务从创建、排期、运行到完成、失败必须有全程可追溯的记录每个节点能回答现在走到哪一步了、为什么走到这一步。异常可告警执行失败不能悄无声息要通过企微等渠道第一时间触达负责人失败信息必须结构化方便定位根因。人机协同高风险的写操作、部署操作必须经过人工确认降低模型幻觉带来的破坏力。带着这几条原则我搭建了羲和的第一版架构。下面逐个部分拆开讲每一处选型背后都有对应的踩坑记录希望能帮你少走弯路。2. 动静分离的整体架构模型负责规划工程负责执行2.1 三层结构会话层、编排层、执行层羲和的整体架构没有走很花哨的路线核心就是动静分离。动态部分是模型——负责理解意图、拆解任务、生成工具调用参数静态部分是工程——负责真正执行命令、管理状态、保证可靠性。会话接入层承接用户输入和交互包括终端对话、Web界面、IM机器人入口。这一层做的事情很纯粹接收请求、校验格式、把用户消息送入编排层。我额外加了一层会话快照机制用户在对话过程中可以随时回到任意一个历史修订点这在后面调试任务拆解逻辑时帮了大忙。Agent编排层这是羲和的核心负责驱动模型完成任务拆解、工具选择、参数生成。它维护当前任务上下文记录已经完成的步骤、当前所处的阶段、以及下一步可以调用的工具列表。服务执行层实际执行具体命令的模块包括Shell命令执行、代码文件读写、构建/测试工具链调用、服务部署操作等。所有与外部环境的交互都经过这一层相当于给系统的手脚。这条链路里最重要的一条经验是**不要把模型直接接到任意工具上。**我在早期版本中一度让模型直接生成Shell命令并在容器里执行结果很快发现模型的输出存在随机性和幻觉一个本意是列出当前目录文件的请求它生成的命令里偶尔会混进不该有的参数。后来加了一层执行网关所有命令先经过白名单校验和参数模板匹配再落到执行器误操作的概率才压下来。2.2 为什么选异步任务队列而不是同步执行这个问题是我在设计第一版时反复纠结过的。最初的实现很天真用户在对话框里问把单测跑完并修复失败用例系统就同步地跑命令前端一直转圈等结果。同步方式有三个致命问题。首先长任务会挂死会话连接跑一个耗时的集成测试动不动就几分钟HTTP连接和WebSocket都会超时其次同步执行的容错很差进程一断整个任务就没了也没有地方记录执行到一半的内部状态第三无法并发——多个用户同时发起任务时只能排队或粗暴地开进程资源管理形同虚设。最终我设计了一个基于 Redis Stream 的异步任务队列。流程是这样的编排层把拆解好的任务节点序列化成 JobSpec投递到队列执行网关Worker从队列里拉取任务一步步执行并随时把状态回写到持久化存储中。用户侧通过轮询或 SSEServer-Sent Events拿任务动态不需要长连接挂着。之所以选 Redis Stream 而不是直接用 RabbitMQ 或 Kafka主要考虑两点一是我们内部 Redis 基建已经很稳定运维成本低二是 Stream 天然支持消费组和消息重放对任务状态的可回溯性有很好的支撑。Kafka 适合大数据量的消息总线对单个任务编排来说有点重RabbitMQ 的灵活度和可靠性都很好但需要额外运维一套集群。选型不是越强越好而是看当前场景的痛点和团队运维能力的交集这是我在很多项目里反复验证过的一条原则。2.3 状态存储一张任务表就够了吗任务的持久化我开始用一张 PostgreSQL 表存放字段设计得很随意task_id、status、steps、result。结果任务一多、环节一复杂马上发现一步走完改一次整条记录的模式根本无法满足需求。重新设计后我用了三张表来存状态Task一个任务的总体信息包括目标描述、模型配置、创建时间、当前总体状态PENDING / RUNNING / SUCCEEDED / FAILED / CANCELLED。TaskStep任务拆解后的每一个子步骤记录步骤类型、关联的工具、输入参数、执行结果、起止时间、状态。每个 Task 对应多个 TaskStep。TaskLog运行日志流每一步的命令输出、模型推理片段、告警触发记录都追加在这里。把状态拆细之后很多事就顺了。比如用户问现在跑到哪一步了直接查 TaskStep 表筛出 RUNNING 状态的步骤即可做失败分析时看 TaskLog 里对应的告警时间和执行输出片段能快速定位是模型规划问题、工具执行问题还是环境差异问题。后来加企微告警我直接在这三张表的基础上做了一层事件订阅任何状态变更都会发布一个事件通知服务按规则决定要不要触发告警。这批表结构设计过程中最大的体会是**任务执行系统的底层不是消息而是状态。**消息队列负责传输但状态表才是最终裁判。幂等性、重试、并发控制都得围绕状态来设计。3. 工具注册与任务拆解让大模型按契约调用真实服务3.1 工具契约JSON Schema 是第一道防线大模型本身不知道你的服务器上有哪些命令、你的发布系统怎么调用、你的企微机器人端点是什么。它只知道可调用的工具列表并且只能按你定义的格式来调用。所以工具注册表的设计就非常关键——它决定了模型能做什么也决定了系统能拦住什么。我在羲和里定义了一套工具契约格式核心是 JSON Schema{ name: run_shell_command, description: 在目标机器上执行一条Shell命令并返回标准输出。适用于运行测试、构建、查看日志等操作。, parameters: { type: object, properties: { host: { type: string, description: 目标机器地址或主机名 }, command: { type: string, description: 要执行的Shell命令 }, timeout: { type: integer, description: 超时时间秒, default: 120 } }, required: [host, command] } }这套格式的好处在于主流大模型对 JSON Schema 的解析能力都很好函数调用Function Calling模式下可以直接把参数抽取出来。但光有工具定义还不够真正的防线在参数校验和命令白名单。例如 run_shell_command 这个工具我会先做一次正则和模板匹配禁止 rm -rf 这类危险操作禁止超过白名单列表之外的路径写操作。这一步不是限制模型而是给模型可能出现的幻觉兜底。我见过不少团队直接把几十个工具全部塞给模型期望它自己判断什么时候用什么。实际情况是模型在工具选择上经常出错尤其是在工具数量超过20个之后调用错误率会明显上升。解决办法是给工具分组按用户意图做路由。比如用户问为什么测试失败先路由到 test_debug 工具组这个组里只暴露日志读取、测试执行、断言分析这几个工具模型的选择空间变小准确率自然就上来了。3.2 从用户意图到 DAG任务拆解的状态机设计任务拆解是羲和从问答跨越到执行的关键一跳。以跑通单测并修复失败用例为例模型需要把用户的自然语言目标变成一个可执行的任务图步骤1列出项目中的测试模块和入口步骤2执行单测命令收集失败用例列表步骤3逐个分析失败用例的堆栈日志步骤4生成修复建议并应用补丁步骤5重新执行单测验证修复效果这些步骤之间存在依赖关系步骤3依赖步骤2的输出步骤4依赖步骤3的分析结论。所以我采用了状态机 步骤依赖的方式管理而不是简单地把多个步骤线性塞进队列。每一步有一个状态标签NOT_STARTED、WAITING、READY、RUNNING、SUCCEEDED、BLOCKED、FAILED。步骤之间用依赖表连接只有所有前置依赖都变成 SUCCEEDED 之后当前步骤才会进入 READY 状态才会被 Worker 拉取。这个设计让我在任务执行到一半失败时能清楚地知道哪些步骤可以重试、哪些步骤必须回退。有个小技巧值得分享**每生成一步先不要急着去执行先做一次步骤自洽检查。**让模型检查自己生成的步骤清单里是否有遗漏、是否有重复、依赖关系是否闭环。这一步虽然多消耗一次模型调用但能显著降低后续执行阶段的无谓失败。上过两次当之后你会发现这个代价非常值得——有一次它把部署忘了写进步骤如果不做检查整个任务会在测试通过后直接宣告完成部署这关键一步悄无声息被跳过。3.3 上下文管理长对话里的取舍任务执行往往伴随着多轮对话。用户在任务中途可能会说刚才那个文件不要改换另一个或者这个命令的 timeout 加长一点。这就要求系统不能像传统问答那样每轮独立处理而是要维护一份结构化的上下文。羲和的上下文分为两层这里想特别澄清一个常见误区模型上下文Context Window和系统状态上下文State Context是两个东西混为一谈必然出问题。模型上下文是喂给大模型的 token 序列。我严格控制它的长度规则是只保留当前的步骤清单、最近一次工具返回的关键输出片段做摘要而不是全量粘贴、用户最近的几条指令。**不要把历史执行日志整个灌进模型。**一个常见场景是任务跑了20个步骤每个步骤的输出都有几KB如果全塞进上下文token 早就爆了。我的做法是每步执行完之后把输出前200个字符 结尾200个字符搭成一个摘要关键的报错堆栈单独截取再放进上下文。系统状态上下文则是一份结构化的记录放在 Redis 里包含 TaskStep 表的最新状态、工具调用的参数快照、用户未读的通知事件。这份记录不喂给模型而是用于系统自身的逻辑判断比如这个步骤重试了两次还是失败触发告警。顺带说一下长对话裁剪中的一个坑**别把用户说过的话全部精简掉。**特别是用户中途给出的约束条件比如不要动配置文件如果被摘要逻辑吞掉了模型之后就可能违背这个约定。我给这类用户约束打了一个高优先级的标签无论上下文怎么裁剪它都会被保留。4. 失败检测与企微告警任务执行侧最不该省的两件事4.1 执行失败的三类典型原因任务执行跑得多了之后失败是家常便饭。但失败和失败不一样粗略归纳下来有三种类型处理方式完全不同。第一类是命令级失败。比如脚本语法错误、目标路径不存在、测试用例崩溃、编译报错。这类失败通常由工具本身的退出码和非零 stderr 暴露出来处理方式是重新生成参数或修正代码后重试。我在这里踩过一个经典的坑Shell 命令的 exit code 不一定可靠有些命令即使部分失败也会返回 0最典型的例子是grep -r在某些模式下找不到匹配却返回非零而需要检查是否真的执行成功就得解析 output 内容。所以我在执行层里加入了一个结果校验器对于关键命令不光看退出码还会对输出做语义级检查。第二类是环境依赖差异。本地跑得好好的命令换到 CI 容器或者新采购的服务器上就报错多半是依赖版本不一致、系统库缺失、环境变量没同步。这类失败往往在第一次执行时发现不了要跑到后续步骤才暴露所以我在步骤依赖设计上留了一个回退机制失败步骤可以带着上下文回到生成策略调整而不是整个任务从头再来。第三类是权限边界问题。模型没有权限意识它可能尝试写一个受保护的系统文件或者执行一个只有特定用户才能运行的管理命令。执行网关需要做用户态隔离我把工具执行放在受限的沙箱用户下并且每一步执行前都做权限预检。早期没有这个设计时模型有一次尝试执行chmod -R 777把整个目录权限改乱了差点影响到线上服务。从那之后沙箱和权限预检直接列入强制要求。4.2 企微告警的接入与分类策略任务执行失败如果没人知道那这个失败约等于没有发生。企微告警是我们在生产环境里很看重的一环它的接入方式不复杂核心是把通知规则设计好。企微机器人的接入走的是自定义 Webhookimport requests def send_wecom_markdown(webhook_url: str, title: str, content: str) - None: payload { msgtype: markdown, markdown: { content: f### {title}\n{content} } } try: requests.post(webhook_url, jsonpayload, timeout5) except Exception: # 告警通道本身失败不能影响主流程 pass这个函数是所有告警的基础但真正让告警体系有价值的是分级与分组策略。我定义了三档告警级别不同级别由不同事件触发告警级别触发条件通知对象典型场景Info任务完成但结果存疑发起人测试通过但有警告日志、部署完成但服务健康检查延迟Warning单步骤失败重试后恢复发起人 任务群命令超时但重试成功、依赖环境缺失但自动补齐Critical任务连续失败或关键步骤失败发起人 值班群 项目负责人执行失败重试仍失败、部署步骤失败、任务长时间卡死我曾看到过不少团队把所有告警都往一个群里推结果群消息泛滥到大家直接静音真正的紧急失败反而没人看。**告警的关键不是发出去而是发对人、发对级别。**后来我还加了告警指纹机制用失败类型和错误摘要的哈希值做聚合同样的问题在10分钟之内只报一次避免重复消息刷屏。这个功能在一次大规模并发执行时立了大功不然同一个环境变量缺失问题可能在一分钟内推几十条告警出来。再提一个和 DolphinScheduler 有关的场景。我们把羲和被集成到了自研调度平台里调度平台会周期性触发任务执行——比如每天凌晨同步数据、每两小时跑一次回归测试。调度层发现任务执行失败后自然而然也会调企微告警通知接口。羲和在这里的角色更偏向任务执行方它负责把失败原因归类、附上可回溯的执行日志链接再交给调度平台的告警渠道统一发出去。这种调度平台 执行 Agent 企微通知的组合基本覆盖了我们日常运维里所有定时任务相关的告警需求。4.3 重试策略与幂等设计同一个任务不能跑两遍告警只是通知真正要解决问题还得靠重试。重试策略的难点在于不是所有失败都适合无脑重试也不是所有重试都应该用相同的方式。我在羲和里配置了一套阶梯式重试策略第一次失败等待30秒后自动重试适用于网络抖动、资源竞争这类瞬时故障。第二次失败等待2分钟后重试同时通知发起人正在重试。第三次失败停止自动重试触发 Critical 告警将任务状态置为 FAILED保留所有断点现场。这里有一个非常重要的前置条件——幂等。重试的前提是同一个操作可以被安全地执行多次。比如发送企微告警这条操作天然幂等重复发一条顶多是烦人但批量插入数据如果没做幂等控制重试一次就多一批脏数据。所以我给所有写操作工具都要求实现幂等令牌每次任务生成一个全局唯一的 execution_id写操作执行前检查这个 ID 是否已经产生过副作用有就直接返回上一次的结果。还有一类场景比较隐晦就是部分成功。任务里有三个步骤第一个成功、第二个成功一半、第三个失败如果整体重试第二步可能重复执行。我的处理方式是细化步骤级别的事务边界第二步内部再拆成若干子操作记录每一个子操作的完成状态。这样重试时只要从断点处接着跑而不必推倒重来。这种断点续跑能力不是一开始就有的最初的重试逻辑就是整个任务重跑一遍。后来在真实使用中发现一个跑批任务中间失败一次就要从头再来半小时的活可能要折腾两个小时效率低到没法接受才下定决心把状态切细。现在的实现虽然复杂了一些但收益是实打实的。5. 一次真实执行的回放从任务提交到企微通知的完整链路5.1 场景回放定时跑批任务失败后告警为什么会准时到达用一个真实场景把整个流程串起来。有一天DolphinScheduler 在凌晨3点准时拉起了一个报表数据同步任务这个任务被调度到羲和来执行。任务的内容是拉取上游数据源、做字段清洗、写入目标表。调度平台调用了羲和的任务提交接口传入的是一条 JSON 指令包含了数据源信息、目标表结构、以及这次执行的分组和超时配置。羲和的任务入口立刻创建了一个新的 Task 记录状态置为 PENDING并把整个指令原样存档。随后按数据源类型路由到了数据处理工具组。执行过程按 DAG 依次推进。拉取数据步骤执行成功数据量是正常的字段清洗步骤执行到一半时突然报出一个空指针异常——上游数据里出现了一个模板中没有定义的字段。这一步立刻被标记为 FAILED触发重试策略。第一次重试在30秒后自动发起仍然失败第二次重试后还是同一个异常。此时告警条件满足系统生成了 Critical 级别的告警事件通过企微机器人推送到数据任务值班群。告警消息里带了任务ID、失败步骤名称、异常堆栈摘要、以及指向任务执行详情页的链接。值班同学早上看到消息点进链接直接看到失败步骤的完整日志30分钟定位原因——上游某业务方凌晨上线了一个新字段没走数据变更流程——及时修复后手动恢复执行。整个过程不需要人去看守任务失败在几个小时内完成了发现、定位和处理。5.2 我在调试过程中踩过的三个实际坑第一个坑是模型误判执行结果。最早版本的流程是工具执行完就把 stdout 返回给模型让它判断是否成功。模型很容易被误导比如命令输出里出现一个 Error 字眼但没有真失败模型就会自己脑补出一个失败来反过来真正失败时如果输出里有 completed 这个词模型又会误判为成功。后来我彻底改变了策略**成功与否由脚本退出码和结果校验器决定模型只在失败发生时负责分析根因。**这就好比自己身体不舒服体温计告诉你发烧了没有不需要你自我感觉判断。把状态判定这种确定性的活从模型那里拿掉准确率一下就上来了这个改动是后期最重要的性能优化之一。第二个坑是超时设置不当导致任务白跑。Shell 命令的 timeout 参数我开始设得很宽松想着长任务多给点时间更安全。结果测试过程中发现一个卡死的连接白白占住了 Worker 半小时真正的任务反而排队。后来我按命令类型设置了差异化超时普通文件操作 30 秒构建命令 5 分钟集成测试 20 分钟。并且加了一条卡死检测连续两分钟没有新输出且状态不是运行关键步骤强制中断标记为疑似卡死并触发告警。第三个坑是并发执行时的共享状态污染。早期工具执行服务里用一个内存字典存放当前任务进度并发一高就乱了。两个任务同时执行时A 任务的进度会偶尔被 B 任务的日志覆盖。排查了很久才定位到这个低级错误。后来所有状态全部移到 PostgreSQL 和 Redis内存里不带任何与状态相关的东西进程可以随时无状态重启。5.3 后续演进我不打算做的东西和准备做的事随着羲和在公司内部逐渐被用起来有两个方向我是刻意没有做的。一个是不加 IDE 插件。当前版本的交互入口是聊天式和任务式虽然够用但很多工程师已经习惯了在编辑器里就地提问、就地执行。我犹豫了一下还是延后了这个方向原因很简单如果交互入口过于分散状态管理和权限控制就会变成灾难一个工具系统最怕的是入口很多、各自为政。等 API 层再稳定一些我们再考虑做 IDE 侧接入但底层的执行和审计逻辑一定是共用同一套。另一个是不做完全自主的写代码 Agent。完全让模型自动修改所有代码权限界定太模糊一旦出错影响面不可控。羲和的策略是模型负责生成补丁和修改建议落到实际文件之前必须经过用户确认或者自动化测试的验证。这个最后一道人工闸门会降低一些执行效率但换来的是安全性。接下来准备做的最重要的一件事是给羲和加上长期记忆层。现在它虽然能在一个任务内部记住上下文但任务结束后就忘光了。我们希望它能积累长时间的经验比如哪类数据源经常字段不完整、哪类代码风格容易触发静态检查不过这些历史经验如果能沉淀下来下一次执行同类任务时就能主动避坑甚至主动调整步骤设计。这一步做完羲和才真正是那个从问答进化到执行再到经验积累的三级跳。回到文章开头的问题一个 AI 编码助手从代码问答到任务执行越过的不只是技术复杂度还有一整套对工程可靠性的重新思考。代码问答是知识活任务执行是脏活累活加责任心。**能回答问题的助手满大街都是能扛事儿的执行者才是真正的稀缺品。**如果你也在做类似的 Agent 系统我的建议是先从最不起眼的可靠性和可观测性下手再谈花哨的智能。毕竟一次正确执行完五个步骤远比十次回答得精彩但执行时翻车更能让团队信任它。