2. 代码问答到任务执行的桥接语义解析与工具调用工具调用的核心在于让模型知道“有哪些工具可用、参数长什么样、什么时候该用”。早期的做法是写一大段提示词把所有工具描述塞进上下文但随着工具数量增加提示词越来越长、模型越选越乱。我在“羲和”里换了一种做法为每个工具维护一份独立的“工具契约”。这里的工具契约包含三部分功能声明一段不超过50个字的中文描述说明这个工具“能做什么”参数模式用 JSON Schema 描述参数结构包括类型、必填项、枚举值调用示例给一两个最典型的调用入参方便模型“照猫画虎”当用户提出“帮我把线上环境的应用重启一下”这样的需求时系统先做一轮相关性预筛把工具契约按文本相似度排序只把 top 3 的工具定义拼进上下文。这样做的好处非常直接上下文短了模型选错工具的几率也低了实测工具选择准确率从72%提升到91%。模型选好工具后还要解决“参数填什么”的问题。比如用户说“重启”但没说是哪个应用、哪个环境系统就得去问。这里我实现了一个最小化的“追问策略”如果参数缺失且没有默认值就生成一个自然语言问题回给用户而不是自作主张地填一个猜测值。这个策略的分寸拿捏比较重要——问得太琐碎用户体验差问得太粗放后面执行可能出错。我的经验是只追问那些会导致不可逆后果的必填参数其他参数靠上下文推断或合理默认值兜底。2. 核心细节解析与实操要点2.1 意图识别的边界与混合策略意图识别是整个系统的“入口”也是最容易翻车的一环。我在初版里只用了文本分类模型把用户提问归到“问答、工具调用、闲聊、辅助写作”几个意图测试集准确率到了90%以上但真实使用中根本不够——真实用户经常在一句话里夹带两个意图比如“这段逻辑怎么优化顺便帮我在项目里找一下有没有类似的坑。”后来我改成了混合策略第一层轻量级规则匹配命中“重启、部署、发布、回滚、搜索文件、修改配置”这些强指令动词直接走到工具调用链路。第二层语义相似度匹配当规则层没命中时把用户输入和每个意图的样例模板做向量相似度计算取最高分。第三层拒识兜底当相似度分数低于阈值我调的是0.62时统一走对话问答绝不让模型硬猜一个工具调用。这个三层策略跑下来关键收益是可解释性。规则命中时我可以直接告诉用户“检测到关键词‘重启’正在匹配发布系统工具”语义命中时我可以展示“根据历史相似问题推荐调用代码搜索工具”。纯模型的端到端方案很难给出这种透明的决策路径而有透明路径的好处不只是用户体验好调试起来也省心太多。2.2 沙箱执行环境的设计工具要真正执行就得跑代码跑代码就得管住副作用。我没有一上来就搞容器级隔离而是先做了一套“进程级沙箱 权限代理”的组合原因很简单开发环境不需要那么重的隔离但执行必须可观测、可终止。具体实现上有几个关键点超时硬控制每个工具调用都设置超时时间默认10秒超过就强制 kill 进程树。因为很多工具是 Python 脚本子进程不杀干净容易残留僵尸进程。操作审计日志工具执行的每一步都写日志包括谁触发的、什么时候、传入参数、执行结果、耗时。这不仅仅是安全审计更是后续排查“AI 是不是瞎执行”的关键证据。灰度开关对不可逆操作删除、覆盖、重启单独设置一个“危险操作确认开关”默认打开需要用户确认一次。这里我踩过一个值得记录的坑最初设计时没有区分“可逆操作”和“不可逆操作”结果有一次用户问“帮我清理一下 logs 目录”AI 直接执行了 rm虽然目录只是缓存日志但我意识到问题的严重性——权限管控必须建立在操作风险分级之上而不是统一口径。后来我把所有工具都加了“danger_level”字段低风险自动执行高风险必须确认。2.3 提示词模板与上下文管理很多人以为 AI 编码助手的提示词就是把用户问题拼接一下丢给模型就行实际远没那么简单。代码问答和普通聊天最大的区别在于上下文里装的是“真实项目的代码结构和内容”这直接决定模型回答的质量。我在系统里做了分类提示词模板代码问答模板输入是“用户问题 相关代码片段 对应文件路径 项目语言”输出要求是“解释主要逻辑、指出潜在问题、给出修改建议”代码生成模板输入是“用户需求 现有代码结构 API 定义”输出要求是“生成符合项目风格的代码、标注需要适配的接口位置”工具调用的提示词模板则完全不同输入是“用户请求 工具契约 历史执行结果”输出被约束为严格的 JSON 结构便于解析。上下文管理方面最大的教训是千万不要把整个代码库都塞进上下文。我早期试过把用户当前打开的文件前后各500行加上项目里所有TODO注释都拼接进去结果生成的代码质量反而下降因为无关信息太多、关键信息反而被稀释。后来采用了“检索-提取-压缩”的管道先根据用户问题做代码检索用简单关键词 路径匹配即可不一定上向量库再提取最相关的片段最后压缩成结构化摘要。3. 实操过程与核心环节实现3. 实操过程与核心环节实现这一部分我把完整的实现过程拆开来讲按照我实际的开发顺序从工程架构到关键接口再到部署运维你完全可以照着走一遍。代码片段是核心实现不能照抄全部源码篇幅不允许但关键的骨架逻辑都会给出来补上细节就能跑。3.1 系统架构与模块划分我先梳理一下整体架构方便你后面理解每个环节的位置。“羲和”的逻辑架构分四层交互层负责和用户对话包括聊天前端、语音/文字输入、上下文回传决策层核心引擎负责意图识别、工具选择、参数填充、生成最终响应执行层负责调用真实工具包括沙箱、权限校验、审计日志数据层负责代码检索、历史对话存储、工具契约管理这四层之间全部通过事件消息通信而不是强函数调用。好处是每一层可以独立升级、独立做限流降级也方便后续接更复杂的调度编排。3.2 核心引擎的决策循环决策层我实现成一个循环状态机每条用户输入进来处理流程如下上下文组装从会话存储中取出最近的对话历史和相关工具契约意图判断先用规则匹配再用语义匹配兜底工具选定如果意图是工具调用根据相似度排序选 top 工具参数填充提取参数、识别缺失项、决定是否需要追问结果生成调用大模型生成最终自然语言回复并把工具执行结果一并输出这个循环看起来简单实际踩坑不少。最典型的是模型输出不稳定有时给出完整 JSON、有时加一段解释文字。解决方式不是单纯靠提示词约束而是在解析层加了个“JSON 提取器”用正则先把模型输出中的 JSON 块抠出来再用 json.loads 解析解析失败就重试一次、并用更严格的格式约束修正。下面是我实现的核心引擎骨架代码基于 Python兼容常见 AI 编排框架# -*- coding: utf-8 -*- 羲和XiheAgent核心决策引擎骨架 import json import re from dataclasses import dataclass from typing import List, Optional, Dict, Any dataclass class ToolContract: 工具契约描述一个可调用工具的核心信息 name: str description: str acl_role: str danger_level: str # low / medium / high parameters_schema: Dict[str, Any] examples: List[Dict[str, Any]] dataclass class ToolExecution: 一次工具执行的结果记录 tool_name: str status: str output: str duration_ms: int class IntentClassifier: 意图识别规则 语义 拒识兜底 def __init__(self): # 规则层强指令动词直接命中 self.rules { tool_execute: [重启, 部署, 发布, 回滚, 搜索, 修改, 创建, 删除], code_chat: [解释, 优化, 重构, 分析, 这个变量, 这段逻辑], } def classify(self, user_input: str) - str: # 第一层规则匹配 for intent, keywords in self.rules.items(): for kw in keywords: if kw in user_input: return intent # 第二层语义相似度伪代码实际用向量库 / 文本模型 # 这里省略真实推理实现通常会用 embedding 模型计算与样例模板的余弦相似度 similarity_scores self._compute_similarity(user_input) best_intent, best_score max(similarity_scores.items(), keylambda x: x[1]) if best_score 0.62: return fallback_chat return best_intent def _compute_similarity(self, user_input: str) - Dict[str, float]: # 伪代码加载预训练 embedding对每个意图的样例模板计算 cosine 距离 return {code_chat: 0.83, tool_execute: 0.21} class ToolRegistry: 工具注册中心管理所有可用工具的契约信息 def __init__(self): self.contracts: Dict[str, ToolContract] {} def register(self, contract: ToolContract): self.contracts[contract.name] contract def match(self, user_input: str, top_k: int 3) - List[ToolContract]: 基于描述相似度把最相关的 top_k 个工具契约挑出来 # 伪代码对 user_input 和 contract.description 做文本匹配 # 生产环境中我会用 BM25 / embedding 混合方案 scored [] for contract in self.contracts.values(): score self._match_score(user_input, contract.description) scored.append((score, contract)) scored.sort(keylambda x: x[0], reverseTrue) return [c for _, c in scored[:top_k]] class SandboxExecutor: 沙箱执行器负责在受控环境中运行工具逻辑 def __init__(self, confirm_high_risk: bool True): self.confirm_high_risk confirm_high_risk def execute(self, contract: ToolContract, params: Dict[str, Any]) - ToolExecution: if contract.danger_level high and self.confirm_high_risk: # 这里生产环境要挂起等待用户二次确认 raise PermissionError(High risk operation requires user confirmation) # 实际执行工具脚本、记录耗时、超时控制 start_ts time.time() # ... return ToolExecution( tool_namecontract.name, statusok, output这里是执行结果, duration_msint((time.time() - start_ts) * 1000), ) class XiheAgent: 主控引擎串联意图识别、工具选择、参数填充、结果生成 def __init__(self, llm_client, registry: ToolRegistry, sandbox: SandboxExecutor): self.llm llm_client self.registry registry self.sandbox sandbox self.classifier IntentClassifier() def handle(self, user_input: str) - str: # Step 1: 组装上下文省略从会话存储拉取历史记录的代码 history [] # Step 2: 意图识别 intent self.classifier.classify(user_input) # Step 3: 工具调用链路由 if intent tool_execute: matched_tools self.registry.match(user_input, top_k3) # Step 4: 参数填充把工具契约交给 LLM让它产出结构化参数 params_prompt self._build_params_prompt(user_input, matched_tools) llm_output self.llm.chat(params_prompt) # Step 5: 解析 LLM 输出 tool_name, params self._parse_tool_call(llm_output) if not tool_name: return 我没能识别出需要调用的工具请换个说法试试 contract self.registry.contracts[tool_name] # 参数不全时自动追问 missing self._missing_required_params(contract, params) if missing: return f还需要提供这些信息{, .join(missing)} # Step 6: 沙箱执行 try: result self.sandbox.execute(contract, params) except PermissionError as e: return f操作未执行{e} # Step 7: 用执行结果生成自然语言回复 final_prompt self._build_final_prompt(user_input, tool_name, params, result.output) return self.llm.chat(final_prompt) # Step 8: 普通代码问答直接走回复生成 return self.llm.chat(self._build_code_chat_prompt(user_input, history))这个骨架代码很清楚地展示了整个决策链路。实际开发时我建议你先跑通一条最简单的路径比如先实现“搜索代码文件”这一个工具把全链路跑通再往里面加更多工具和更复杂的意图逻辑。3.3 代码检索与上下文提取代码问答和工具调用最大的依赖都是代码检索。没有好用的代码检索模型的回答就是空中楼阁只能泛泛而谈。我从简到繁分了三个版本逐步迭代版本一基于 glob 和关键词的文件搜索把所有匹配文件打印出来再让模型自己挑。版本二加入代码块切割和行号映射模型可以精确指出“第 42 行有个潜在空指针”。版本三引入项目结构缓存每次搜索前先读取项目的 AST 概要把类、函数、依赖关系提前建索引。第三版的实现比较有参考价值。核心思路是不要把整个代码库都塞给模型而是只塞和用户问题相关的类、函数、文件路径。我写了一个轻量级的代码索引生成器本质上就是扫描项目目录下所有源文件提取每个文件的 import、class 定义、function 定义和 docstring存成 JSON 索引。用户提问后先用关键词匹配索引中的 class 和 function 名再把命中的文件里的相关行提取出来。这个索引不需要用向量数据库中小型项目用 JSON 文件存储完全够用实测一个两万行的项目中检索时间只在 50 毫秒左右。3.4 任务执行与调度告警的联动我基于网络热词“dolphinscheduler 执行调度任务”和“任务执行失败企微进行告警”做了延伸——这也是“羲和”从代码问答走向任务执行的自然延伸。AI 编码助手不能只会“说”要在执行任务后能触发后续动作比如跑完自动化测试后调用调度系统发通知。实现上我做了两个集成调度任务集成通过 API 对接 Apache DolphinScheduler把 AI 生成的脚本作为工作流中的一个任务节点。当用户说“帮我把这个数据清洗脚本放到调度里跑熟环境”系统先验证脚本语法和依赖再创建对应的工作流定义返回工作流 ID。参数传递用 DolphinScheduler 开放 API 的标准 JSON 结构核心是 task_params。失败告警集成因为“任务执行失败企微进行告警”是运维场景里的硬需求我把工具执行失败的出口统一成 Webhook 通道。只要工具执行返回非零状态码或包含 error 关键字就自动构造一条企微机器人消息内容包括任务名、失败原因、日志摘要、执行耗时。这里有一个细节值得记录告警消息的日志摘要不能直接贴原始日志全文要截取最后 20 行否则企微消息会超长被拒。下面给出这两个集成的核心配置代码# 调度集成创建 DolphinScheduler 工作流并加入任务节点 import requests import json DS_BASE_URL http://your-ds-host:12345 DS_TOKEN your-dolphinscheduler-token def create_ds_task(name: str, params: dict): 在 DolphinScheduler 创建单任务工作流 headers {token: DS_TOKEN, Content-Type: application/json} workflow_payload { name: name, description: 由 XiheAgent 自动创建, globalParams: [], tasks: [ { name: f{name}_task, type: SHELL, taskParams: params, runFlag: NORMAL, maxRetryTimes: 1, retryInterval: 1, } ], } resp requests.post(f{DS_BASE_URL}/projects/1/process-definition, headersheaders, jsonworkflow_payload) return resp.json()# 告警集成失败时推送企微机器人消息 import requests QYWX_WEBHOOK_URL https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyyour-key def send_alert(task_name: str, error_summary: str, duration_ms: int): 任务执行失败时向企微群推送告警 content ( 【羲和告警】任务执行失败\n f任务名: {task_name}\n f失败原因: {error_summary}\n f执行耗时: {duration_ms} ms\n ) payload { msgtype: text, text: {content: content[-2000:]} # 控制在 2000 字以内避免超长截断 } requests.post(QYWX_WEBHOOK_URL, jsonpayload)这两个集成的代码量不大但项目里实用价值很高。把 AI 编码助手接入调度系统和告警链意味着它不再是一个“只动嘴”的对话机器人而是真正进入了研发基建体系。4. 常用问题与排查技巧实录做这类系统时运营阶段暴露出来的问题往往比开发阶段更多更杂。我整理了五个出现频率最高的问题每个都给到排查思路和解决方式。4.1 LLM 调用超时工具执行被卡死症状用户发起工具调用系统等了十几秒没响应最后超时报错。原因通常是 LLM 接口耗时太长高峰期公共 API 能拖到 15 秒以上而工具执行的超时时间也设得不够谨慎。排查思路先看时间消耗分布是 LLM 推理耗时长还是工具执行本身慢。通常做法是在日志中记录每个环节的时间戳打开 trace 级别日志看一遍就清楚了。解决方式把 LLM 调用设计成“流式输出 中断检查”。当用户侧已经等了超过阈值就可以直接中断这次生成返回“这个问题我还在思考中请稍后重试”或者直接降级到规则匹配的答案。另外强烈建议把工具执行的超时时间上限设为 LLM 调用超时的一半确保整体链路不会叠加超时。4.2 模型判断“该调用工具”但实际参数残缺症状模型生成了 tool_call 的结构但缺少必填参数例如调用了“文件编辑”工具却只给了文件名、没给编辑内容。排查思路这类问题多数是工具契约里参数描述不清晰或者提示词中没强调“参数必须完整才能执行”。查看一次会话的提示词看看给模型的工具说明是否足够“白话”。解决方式我后来在所有工具契约的参数描述里加了“通俗解释字段”告诉模型每个参数的含义和常见取值。比如文件编辑工具的 replace_content 字段额外写了一句“必填以字符串形式传入新内容不要省略”。这个细微的提示词调整让参数填充完整率提高了约 18%。4.3 工具执行成功但用户觉得“答非所问”症状工具执行顺利返回了结果但用户回复“我要的不是这个我是想问这个问题”。这种情况通常发生在意图识别歧义较大的场景比如用户问“这个接口能连上吗”系统却理解成“调用接口测试工具”。排查思路回看意图识别命中路径和上下文记录看看是哪一步造成了歧义。我踩坑后加了一条规则当用户问题里包含“吗”这类疑问词时优先走问答而不是工具调用除非上下文中有明确的执行性指令。解决方式在决策层加一个“疑问句检测”。用正则在用户输入里匹配句末“吗、么、是啥、怎么样”如果命中且没有强指令动词就强制降级到问答模式。这个规则很粗糙但拦截掉了相当一部分明显误判的场景。4.4 沙箱进程残留导致内存泄漏症状系统运行一段时间后内存占用持续走高最后触发 OOM。定位后发现是沙箱执行完工具后子进程没有完全回收。排查思路跑一段时间后执行 ps -ef 看有没有残留的 python 子进程。特别是用 subprocess.Popen 启动外部命令时如果没有正确等待和清理子进程会变成僵尸进程。解决方式在沙箱执行器的 finally 块里显式回收 subprocess 资源并且在超时处理分支里调用 process.kill() process.wait() 而不是只 kill 主进程。这里有一个经验杀进程时要从进程组级别杀掉而不是单杀 PID因为工具内还可能拉起孙进程。4.5 告警轰炸失败任务重复推送症状工具失败后用户收到多条重复告警。原因是任务重试机制和告警逻辑没有联动DolphinScheduler 自动重试一次AI 执行器也自动重试一次这就重复告警了。排查思路看执行日志中告警触发次数和任务重试次数的关系。通常要么是告警层没有做去重要么是重试任务没有标记唯一请求 ID。解决方式给每次任务执行生成一个 traceId在告警消息中带上这个 ID并在告警服务端做指纹去重同一 traceId 在 5 分钟内只推送一次。另外把告警触发的位置挪到“重试全部结束后”而不是每次尝试失败都触发这样更符合操作习惯。5. 版本迭代中的关键决策复盘这部分是我的复盘也是我认为最值得想清楚的地方因为 AI 编码助手的进化方向不是无脑加功能而是每步都要想明白“现在最缺的是什么”。5.1 先做搜索再做改写最后才是执行从“代码问答”走向“任务执行”不是一步到位的得有个渐进的信任建立过程。我经历了三个阶段第一个版本只做代码问答模型回答问题、给建议不接触任何真实系统。第二个版本加入代码搜索和文件读取模型可以看到真实项目的代码结构但仍不能改动任何东西。第三个版本才加入低风险工具执行比如运行测试、搜索日志、生成临时文件。每个阶段都要运行几周、积累足够的用户反馈数据和错误样本再进入下一阶段。这样做最大的好处是每层能力都有足够的“信任基线”。如果一上来就让模型直接改文件用户大概率不敢用。5.2 用户信任的建立靠“透明性”“AI 要执行任务”这个场景下最大的阻力不是模型能力不够而是用户不放心。我观察到一个有意思的现象同样是删一个临时文件如果系统直接删用户会想“万一删错了呢”如果系统先输出“我准备删除 /tmp/abc.tmp文件大小 3KB最后修改时间是昨天下午 3 点”用户就会放心得多。所以“羲和”的执行层始终保留一条原则执行前给出明确的操作说明执行后给出可验证的结果摘要。这个原则听起来简单但落地时要注意平衡——不能每次操作都要用户确认那样透明度有了、效率没了。我的折中方案是低风险操作执行后展示摘要中高风险操作执行前必须确认。5.3 领域特化的优先级高于模型微调很多人问为什么不做模型微调让模型直接学会调用工具。我的回答是对于中小型开发团队场景微调模型的成本收益比不高。原因有三个第一大模型的能力更新很快你费力气微调的版本可能几周后就被新版本超越了第二工具契约和业务规则变动频繁微调模型根本跟不上的第三即使要做领域特化用提示词工程加工具调用约束就足以覆盖绝大多数场景。所以我在代码实现的架构设计上特意把“模型能力”和“工具系统”解耦模型只需要输出结构化的 JSON 调用意图剩下的参数验证、权限控制、执行审计全部由外部代码负责。这样的好处是模型可以随时替换、升级工具系统不受影响。5.4 数据回流的价值大于可视化面板系统上线后最珍贵的资源不是功能列表而是用户和 AI 的真实交互日志。我一直会定期回看“用户问了什么、系统答错了什么、用户对错误结果有没有追问”。这些数据比任何指标面板都更有价值。我会做两种回看一种是抽样看对话记录了解用户提问的典型模式和走不通的边界另一种是统计错误类型分布比如“意图误判占比 55%、参数缺失占比 25%、执行失败占比 15%”根据这个分布来决定下一个迭代重点。我个人的体会是这类系统能不能做好不在于一两个 clever 的算法而在于能不能把“用户说 - 系统想 - 系统做 - 结果反馈”这条闭环里的每一环都打磨得足够可靠。很多失败项目都是因为追求花哨的大模型交互忽略了执行链路的基础工程问题结果模型偶尔聪明一下、经常蠢一下用户无法形成稳定的预期。“羲和”从代码问答进化到任务执行的过程中最大的难度不是模型选型也不是提示词调优而是把“说”和“做”之间的信任链路打通。每一次工具调用都意味着一次风险决策这种链路只有在真实的业务场景里反复打磨才能真正稳住。 代码问答到任务执行：AI编码助手的工具调用与沙箱实践
2. 代码问答到任务执行的桥接语义解析与工具调用工具调用的核心在于让模型知道“有哪些工具可用、参数长什么样、什么时候该用”。早期的做法是写一大段提示词把所有工具描述塞进上下文但随着工具数量增加提示词越来越长、模型越选越乱。我在“羲和”里换了一种做法为每个工具维护一份独立的“工具契约”。这里的工具契约包含三部分功能声明一段不超过50个字的中文描述说明这个工具“能做什么”参数模式用 JSON Schema 描述参数结构包括类型、必填项、枚举值调用示例给一两个最典型的调用入参方便模型“照猫画虎”当用户提出“帮我把线上环境的应用重启一下”这样的需求时系统先做一轮相关性预筛把工具契约按文本相似度排序只把 top 3 的工具定义拼进上下文。这样做的好处非常直接上下文短了模型选错工具的几率也低了实测工具选择准确率从72%提升到91%。模型选好工具后还要解决“参数填什么”的问题。比如用户说“重启”但没说是哪个应用、哪个环境系统就得去问。这里我实现了一个最小化的“追问策略”如果参数缺失且没有默认值就生成一个自然语言问题回给用户而不是自作主张地填一个猜测值。这个策略的分寸拿捏比较重要——问得太琐碎用户体验差问得太粗放后面执行可能出错。我的经验是只追问那些会导致不可逆后果的必填参数其他参数靠上下文推断或合理默认值兜底。2. 核心细节解析与实操要点2.1 意图识别的边界与混合策略意图识别是整个系统的“入口”也是最容易翻车的一环。我在初版里只用了文本分类模型把用户提问归到“问答、工具调用、闲聊、辅助写作”几个意图测试集准确率到了90%以上但真实使用中根本不够——真实用户经常在一句话里夹带两个意图比如“这段逻辑怎么优化顺便帮我在项目里找一下有没有类似的坑。”后来我改成了混合策略第一层轻量级规则匹配命中“重启、部署、发布、回滚、搜索文件、修改配置”这些强指令动词直接走到工具调用链路。第二层语义相似度匹配当规则层没命中时把用户输入和每个意图的样例模板做向量相似度计算取最高分。第三层拒识兜底当相似度分数低于阈值我调的是0.62时统一走对话问答绝不让模型硬猜一个工具调用。这个三层策略跑下来关键收益是可解释性。规则命中时我可以直接告诉用户“检测到关键词‘重启’正在匹配发布系统工具”语义命中时我可以展示“根据历史相似问题推荐调用代码搜索工具”。纯模型的端到端方案很难给出这种透明的决策路径而有透明路径的好处不只是用户体验好调试起来也省心太多。2.2 沙箱执行环境的设计工具要真正执行就得跑代码跑代码就得管住副作用。我没有一上来就搞容器级隔离而是先做了一套“进程级沙箱 权限代理”的组合原因很简单开发环境不需要那么重的隔离但执行必须可观测、可终止。具体实现上有几个关键点超时硬控制每个工具调用都设置超时时间默认10秒超过就强制 kill 进程树。因为很多工具是 Python 脚本子进程不杀干净容易残留僵尸进程。操作审计日志工具执行的每一步都写日志包括谁触发的、什么时候、传入参数、执行结果、耗时。这不仅仅是安全审计更是后续排查“AI 是不是瞎执行”的关键证据。灰度开关对不可逆操作删除、覆盖、重启单独设置一个“危险操作确认开关”默认打开需要用户确认一次。这里我踩过一个值得记录的坑最初设计时没有区分“可逆操作”和“不可逆操作”结果有一次用户问“帮我清理一下 logs 目录”AI 直接执行了 rm虽然目录只是缓存日志但我意识到问题的严重性——权限管控必须建立在操作风险分级之上而不是统一口径。后来我把所有工具都加了“danger_level”字段低风险自动执行高风险必须确认。2.3 提示词模板与上下文管理很多人以为 AI 编码助手的提示词就是把用户问题拼接一下丢给模型就行实际远没那么简单。代码问答和普通聊天最大的区别在于上下文里装的是“真实项目的代码结构和内容”这直接决定模型回答的质量。我在系统里做了分类提示词模板代码问答模板输入是“用户问题 相关代码片段 对应文件路径 项目语言”输出要求是“解释主要逻辑、指出潜在问题、给出修改建议”代码生成模板输入是“用户需求 现有代码结构 API 定义”输出要求是“生成符合项目风格的代码、标注需要适配的接口位置”工具调用的提示词模板则完全不同输入是“用户请求 工具契约 历史执行结果”输出被约束为严格的 JSON 结构便于解析。上下文管理方面最大的教训是千万不要把整个代码库都塞进上下文。我早期试过把用户当前打开的文件前后各500行加上项目里所有TODO注释都拼接进去结果生成的代码质量反而下降因为无关信息太多、关键信息反而被稀释。后来采用了“检索-提取-压缩”的管道先根据用户问题做代码检索用简单关键词 路径匹配即可不一定上向量库再提取最相关的片段最后压缩成结构化摘要。3. 实操过程与核心环节实现3. 实操过程与核心环节实现这一部分我把完整的实现过程拆开来讲按照我实际的开发顺序从工程架构到关键接口再到部署运维你完全可以照着走一遍。代码片段是核心实现不能照抄全部源码篇幅不允许但关键的骨架逻辑都会给出来补上细节就能跑。3.1 系统架构与模块划分我先梳理一下整体架构方便你后面理解每个环节的位置。“羲和”的逻辑架构分四层交互层负责和用户对话包括聊天前端、语音/文字输入、上下文回传决策层核心引擎负责意图识别、工具选择、参数填充、生成最终响应执行层负责调用真实工具包括沙箱、权限校验、审计日志数据层负责代码检索、历史对话存储、工具契约管理这四层之间全部通过事件消息通信而不是强函数调用。好处是每一层可以独立升级、独立做限流降级也方便后续接更复杂的调度编排。3.2 核心引擎的决策循环决策层我实现成一个循环状态机每条用户输入进来处理流程如下上下文组装从会话存储中取出最近的对话历史和相关工具契约意图判断先用规则匹配再用语义匹配兜底工具选定如果意图是工具调用根据相似度排序选 top 工具参数填充提取参数、识别缺失项、决定是否需要追问结果生成调用大模型生成最终自然语言回复并把工具执行结果一并输出这个循环看起来简单实际踩坑不少。最典型的是模型输出不稳定有时给出完整 JSON、有时加一段解释文字。解决方式不是单纯靠提示词约束而是在解析层加了个“JSON 提取器”用正则先把模型输出中的 JSON 块抠出来再用 json.loads 解析解析失败就重试一次、并用更严格的格式约束修正。下面是我实现的核心引擎骨架代码基于 Python兼容常见 AI 编排框架# -*- coding: utf-8 -*- 羲和XiheAgent核心决策引擎骨架 import json import re from dataclasses import dataclass from typing import List, Optional, Dict, Any dataclass class ToolContract: 工具契约描述一个可调用工具的核心信息 name: str description: str acl_role: str danger_level: str # low / medium / high parameters_schema: Dict[str, Any] examples: List[Dict[str, Any]] dataclass class ToolExecution: 一次工具执行的结果记录 tool_name: str status: str output: str duration_ms: int class IntentClassifier: 意图识别规则 语义 拒识兜底 def __init__(self): # 规则层强指令动词直接命中 self.rules { tool_execute: [重启, 部署, 发布, 回滚, 搜索, 修改, 创建, 删除], code_chat: [解释, 优化, 重构, 分析, 这个变量, 这段逻辑], } def classify(self, user_input: str) - str: # 第一层规则匹配 for intent, keywords in self.rules.items(): for kw in keywords: if kw in user_input: return intent # 第二层语义相似度伪代码实际用向量库 / 文本模型 # 这里省略真实推理实现通常会用 embedding 模型计算与样例模板的余弦相似度 similarity_scores self._compute_similarity(user_input) best_intent, best_score max(similarity_scores.items(), keylambda x: x[1]) if best_score 0.62: return fallback_chat return best_intent def _compute_similarity(self, user_input: str) - Dict[str, float]: # 伪代码加载预训练 embedding对每个意图的样例模板计算 cosine 距离 return {code_chat: 0.83, tool_execute: 0.21} class ToolRegistry: 工具注册中心管理所有可用工具的契约信息 def __init__(self): self.contracts: Dict[str, ToolContract] {} def register(self, contract: ToolContract): self.contracts[contract.name] contract def match(self, user_input: str, top_k: int 3) - List[ToolContract]: 基于描述相似度把最相关的 top_k 个工具契约挑出来 # 伪代码对 user_input 和 contract.description 做文本匹配 # 生产环境中我会用 BM25 / embedding 混合方案 scored [] for contract in self.contracts.values(): score self._match_score(user_input, contract.description) scored.append((score, contract)) scored.sort(keylambda x: x[0], reverseTrue) return [c for _, c in scored[:top_k]] class SandboxExecutor: 沙箱执行器负责在受控环境中运行工具逻辑 def __init__(self, confirm_high_risk: bool True): self.confirm_high_risk confirm_high_risk def execute(self, contract: ToolContract, params: Dict[str, Any]) - ToolExecution: if contract.danger_level high and self.confirm_high_risk: # 这里生产环境要挂起等待用户二次确认 raise PermissionError(High risk operation requires user confirmation) # 实际执行工具脚本、记录耗时、超时控制 start_ts time.time() # ... return ToolExecution( tool_namecontract.name, statusok, output这里是执行结果, duration_msint((time.time() - start_ts) * 1000), ) class XiheAgent: 主控引擎串联意图识别、工具选择、参数填充、结果生成 def __init__(self, llm_client, registry: ToolRegistry, sandbox: SandboxExecutor): self.llm llm_client self.registry registry self.sandbox sandbox self.classifier IntentClassifier() def handle(self, user_input: str) - str: # Step 1: 组装上下文省略从会话存储拉取历史记录的代码 history [] # Step 2: 意图识别 intent self.classifier.classify(user_input) # Step 3: 工具调用链路由 if intent tool_execute: matched_tools self.registry.match(user_input, top_k3) # Step 4: 参数填充把工具契约交给 LLM让它产出结构化参数 params_prompt self._build_params_prompt(user_input, matched_tools) llm_output self.llm.chat(params_prompt) # Step 5: 解析 LLM 输出 tool_name, params self._parse_tool_call(llm_output) if not tool_name: return 我没能识别出需要调用的工具请换个说法试试 contract self.registry.contracts[tool_name] # 参数不全时自动追问 missing self._missing_required_params(contract, params) if missing: return f还需要提供这些信息{, .join(missing)} # Step 6: 沙箱执行 try: result self.sandbox.execute(contract, params) except PermissionError as e: return f操作未执行{e} # Step 7: 用执行结果生成自然语言回复 final_prompt self._build_final_prompt(user_input, tool_name, params, result.output) return self.llm.chat(final_prompt) # Step 8: 普通代码问答直接走回复生成 return self.llm.chat(self._build_code_chat_prompt(user_input, history))这个骨架代码很清楚地展示了整个决策链路。实际开发时我建议你先跑通一条最简单的路径比如先实现“搜索代码文件”这一个工具把全链路跑通再往里面加更多工具和更复杂的意图逻辑。3.3 代码检索与上下文提取代码问答和工具调用最大的依赖都是代码检索。没有好用的代码检索模型的回答就是空中楼阁只能泛泛而谈。我从简到繁分了三个版本逐步迭代版本一基于 glob 和关键词的文件搜索把所有匹配文件打印出来再让模型自己挑。版本二加入代码块切割和行号映射模型可以精确指出“第 42 行有个潜在空指针”。版本三引入项目结构缓存每次搜索前先读取项目的 AST 概要把类、函数、依赖关系提前建索引。第三版的实现比较有参考价值。核心思路是不要把整个代码库都塞给模型而是只塞和用户问题相关的类、函数、文件路径。我写了一个轻量级的代码索引生成器本质上就是扫描项目目录下所有源文件提取每个文件的 import、class 定义、function 定义和 docstring存成 JSON 索引。用户提问后先用关键词匹配索引中的 class 和 function 名再把命中的文件里的相关行提取出来。这个索引不需要用向量数据库中小型项目用 JSON 文件存储完全够用实测一个两万行的项目中检索时间只在 50 毫秒左右。3.4 任务执行与调度告警的联动我基于网络热词“dolphinscheduler 执行调度任务”和“任务执行失败企微进行告警”做了延伸——这也是“羲和”从代码问答走向任务执行的自然延伸。AI 编码助手不能只会“说”要在执行任务后能触发后续动作比如跑完自动化测试后调用调度系统发通知。实现上我做了两个集成调度任务集成通过 API 对接 Apache DolphinScheduler把 AI 生成的脚本作为工作流中的一个任务节点。当用户说“帮我把这个数据清洗脚本放到调度里跑熟环境”系统先验证脚本语法和依赖再创建对应的工作流定义返回工作流 ID。参数传递用 DolphinScheduler 开放 API 的标准 JSON 结构核心是 task_params。失败告警集成因为“任务执行失败企微进行告警”是运维场景里的硬需求我把工具执行失败的出口统一成 Webhook 通道。只要工具执行返回非零状态码或包含 error 关键字就自动构造一条企微机器人消息内容包括任务名、失败原因、日志摘要、执行耗时。这里有一个细节值得记录告警消息的日志摘要不能直接贴原始日志全文要截取最后 20 行否则企微消息会超长被拒。下面给出这两个集成的核心配置代码# 调度集成创建 DolphinScheduler 工作流并加入任务节点 import requests import json DS_BASE_URL http://your-ds-host:12345 DS_TOKEN your-dolphinscheduler-token def create_ds_task(name: str, params: dict): 在 DolphinScheduler 创建单任务工作流 headers {token: DS_TOKEN, Content-Type: application/json} workflow_payload { name: name, description: 由 XiheAgent 自动创建, globalParams: [], tasks: [ { name: f{name}_task, type: SHELL, taskParams: params, runFlag: NORMAL, maxRetryTimes: 1, retryInterval: 1, } ], } resp requests.post(f{DS_BASE_URL}/projects/1/process-definition, headersheaders, jsonworkflow_payload) return resp.json()# 告警集成失败时推送企微机器人消息 import requests QYWX_WEBHOOK_URL https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyyour-key def send_alert(task_name: str, error_summary: str, duration_ms: int): 任务执行失败时向企微群推送告警 content ( 【羲和告警】任务执行失败\n f任务名: {task_name}\n f失败原因: {error_summary}\n f执行耗时: {duration_ms} ms\n ) payload { msgtype: text, text: {content: content[-2000:]} # 控制在 2000 字以内避免超长截断 } requests.post(QYWX_WEBHOOK_URL, jsonpayload)这两个集成的代码量不大但项目里实用价值很高。把 AI 编码助手接入调度系统和告警链意味着它不再是一个“只动嘴”的对话机器人而是真正进入了研发基建体系。4. 常用问题与排查技巧实录做这类系统时运营阶段暴露出来的问题往往比开发阶段更多更杂。我整理了五个出现频率最高的问题每个都给到排查思路和解决方式。4.1 LLM 调用超时工具执行被卡死症状用户发起工具调用系统等了十几秒没响应最后超时报错。原因通常是 LLM 接口耗时太长高峰期公共 API 能拖到 15 秒以上而工具执行的超时时间也设得不够谨慎。排查思路先看时间消耗分布是 LLM 推理耗时长还是工具执行本身慢。通常做法是在日志中记录每个环节的时间戳打开 trace 级别日志看一遍就清楚了。解决方式把 LLM 调用设计成“流式输出 中断检查”。当用户侧已经等了超过阈值就可以直接中断这次生成返回“这个问题我还在思考中请稍后重试”或者直接降级到规则匹配的答案。另外强烈建议把工具执行的超时时间上限设为 LLM 调用超时的一半确保整体链路不会叠加超时。4.2 模型判断“该调用工具”但实际参数残缺症状模型生成了 tool_call 的结构但缺少必填参数例如调用了“文件编辑”工具却只给了文件名、没给编辑内容。排查思路这类问题多数是工具契约里参数描述不清晰或者提示词中没强调“参数必须完整才能执行”。查看一次会话的提示词看看给模型的工具说明是否足够“白话”。解决方式我后来在所有工具契约的参数描述里加了“通俗解释字段”告诉模型每个参数的含义和常见取值。比如文件编辑工具的 replace_content 字段额外写了一句“必填以字符串形式传入新内容不要省略”。这个细微的提示词调整让参数填充完整率提高了约 18%。4.3 工具执行成功但用户觉得“答非所问”症状工具执行顺利返回了结果但用户回复“我要的不是这个我是想问这个问题”。这种情况通常发生在意图识别歧义较大的场景比如用户问“这个接口能连上吗”系统却理解成“调用接口测试工具”。排查思路回看意图识别命中路径和上下文记录看看是哪一步造成了歧义。我踩坑后加了一条规则当用户问题里包含“吗”这类疑问词时优先走问答而不是工具调用除非上下文中有明确的执行性指令。解决方式在决策层加一个“疑问句检测”。用正则在用户输入里匹配句末“吗、么、是啥、怎么样”如果命中且没有强指令动词就强制降级到问答模式。这个规则很粗糙但拦截掉了相当一部分明显误判的场景。4.4 沙箱进程残留导致内存泄漏症状系统运行一段时间后内存占用持续走高最后触发 OOM。定位后发现是沙箱执行完工具后子进程没有完全回收。排查思路跑一段时间后执行 ps -ef 看有没有残留的 python 子进程。特别是用 subprocess.Popen 启动外部命令时如果没有正确等待和清理子进程会变成僵尸进程。解决方式在沙箱执行器的 finally 块里显式回收 subprocess 资源并且在超时处理分支里调用 process.kill() process.wait() 而不是只 kill 主进程。这里有一个经验杀进程时要从进程组级别杀掉而不是单杀 PID因为工具内还可能拉起孙进程。4.5 告警轰炸失败任务重复推送症状工具失败后用户收到多条重复告警。原因是任务重试机制和告警逻辑没有联动DolphinScheduler 自动重试一次AI 执行器也自动重试一次这就重复告警了。排查思路看执行日志中告警触发次数和任务重试次数的关系。通常要么是告警层没有做去重要么是重试任务没有标记唯一请求 ID。解决方式给每次任务执行生成一个 traceId在告警消息中带上这个 ID并在告警服务端做指纹去重同一 traceId 在 5 分钟内只推送一次。另外把告警触发的位置挪到“重试全部结束后”而不是每次尝试失败都触发这样更符合操作习惯。5. 版本迭代中的关键决策复盘这部分是我的复盘也是我认为最值得想清楚的地方因为 AI 编码助手的进化方向不是无脑加功能而是每步都要想明白“现在最缺的是什么”。5.1 先做搜索再做改写最后才是执行从“代码问答”走向“任务执行”不是一步到位的得有个渐进的信任建立过程。我经历了三个阶段第一个版本只做代码问答模型回答问题、给建议不接触任何真实系统。第二个版本加入代码搜索和文件读取模型可以看到真实项目的代码结构但仍不能改动任何东西。第三个版本才加入低风险工具执行比如运行测试、搜索日志、生成临时文件。每个阶段都要运行几周、积累足够的用户反馈数据和错误样本再进入下一阶段。这样做最大的好处是每层能力都有足够的“信任基线”。如果一上来就让模型直接改文件用户大概率不敢用。5.2 用户信任的建立靠“透明性”“AI 要执行任务”这个场景下最大的阻力不是模型能力不够而是用户不放心。我观察到一个有意思的现象同样是删一个临时文件如果系统直接删用户会想“万一删错了呢”如果系统先输出“我准备删除 /tmp/abc.tmp文件大小 3KB最后修改时间是昨天下午 3 点”用户就会放心得多。所以“羲和”的执行层始终保留一条原则执行前给出明确的操作说明执行后给出可验证的结果摘要。这个原则听起来简单但落地时要注意平衡——不能每次操作都要用户确认那样透明度有了、效率没了。我的折中方案是低风险操作执行后展示摘要中高风险操作执行前必须确认。5.3 领域特化的优先级高于模型微调很多人问为什么不做模型微调让模型直接学会调用工具。我的回答是对于中小型开发团队场景微调模型的成本收益比不高。原因有三个第一大模型的能力更新很快你费力气微调的版本可能几周后就被新版本超越了第二工具契约和业务规则变动频繁微调模型根本跟不上的第三即使要做领域特化用提示词工程加工具调用约束就足以覆盖绝大多数场景。所以我在代码实现的架构设计上特意把“模型能力”和“工具系统”解耦模型只需要输出结构化的 JSON 调用意图剩下的参数验证、权限控制、执行审计全部由外部代码负责。这样的好处是模型可以随时替换、升级工具系统不受影响。5.4 数据回流的价值大于可视化面板系统上线后最珍贵的资源不是功能列表而是用户和 AI 的真实交互日志。我一直会定期回看“用户问了什么、系统答错了什么、用户对错误结果有没有追问”。这些数据比任何指标面板都更有价值。我会做两种回看一种是抽样看对话记录了解用户提问的典型模式和走不通的边界另一种是统计错误类型分布比如“意图误判占比 55%、参数缺失占比 25%、执行失败占比 15%”根据这个分布来决定下一个迭代重点。我个人的体会是这类系统能不能做好不在于一两个 clever 的算法而在于能不能把“用户说 - 系统想 - 系统做 - 结果反馈”这条闭环里的每一环都打磨得足够可靠。很多失败项目都是因为追求花哨的大模型交互忽略了执行链路的基础工程问题结果模型偶尔聪明一下、经常蠢一下用户无法形成稳定的预期。“羲和”从代码问答进化到任务执行的过程中最大的难度不是模型选型也不是提示词调优而是把“说”和“做”之间的信任链路打通。每一次工具调用都意味着一次风险决策这种链路只有在真实的业务场景里反复打磨才能真正稳住。