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(), key=lambda 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(key=lambda x: x[0], reverse=True) 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_name=contract.name, status="ok", output="这里是执行结果", duration_ms=int((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_k=3) # 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", headers=headers, json=workflow_payload) return resp.json()# 告警集成：失败时推送企微机器人消息 import requests QYWX_WEBHOOK_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your-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, json=payload)这两个集成的代码量不大，但项目里实用价值很高。把 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 的算法，而在于能不能把“用户说 - 系统想 - 系统做 - 结果反馈”这条闭环里的每一环都打磨得足够可靠。很多失败项目都是因为追求花哨的大模型交互，忽略了执行链路的基础工程问题，结果模型偶尔聪明一下、经常蠢一下，用户无法形成稳定的预期。
“羲和”从代码问答进化到任务执行的过程中，最大的难度不是模型选型，也不是提示词调优，而是把“说”和“做”之间的信任链路打通。每一次工具调用都意味着一次风险决策，这种链路只有在真实的业务场景里反复打磨才能真正稳住。
