系列《VeapAI 自然语言操作实战》第 5 篇收尾篇 相关源码veap-ui/src/components/AiAgentEngine/执行器调度、状态、审计、安全边界与交互、veap-cloud/veap-modules/veap-ai/语义模板与上下文资源同步、veap-cloud/DB/veap.sql## 一、把前面四篇收成一张图回头看这套东西其实只有两句话。第一句**让数据先会说话。** 三层语义各管一段——数据表字典管字段语义生成器字段快照管字段可用能力知识主题管业务术语。这三层都不是给模型看的文档而是可以被程序读取、被脚本断言的事实清单。第二句**让编排只做编排。** 一条命令拆成五段判断每段后面跟一道校验闸门分支、确认、回显、审计都在画布上配置不写在代码里。mermaidflowchart LRA[用户命令] -- B[意图识别br/ 校验闸门]B -- C[表定位br/ 校验闸门]C -- D{路由}D --|引导| E[接口清单 → 能力说明]D --|无法识别| F[可读提示后中断]D --|主链| G[字段清单 ∥ 接口清单]G -- H[执行计划br/ 校验闸门]H -- I{查询 / 统计 / 分析 / 操作}I -- J[执行]I -- K[确认弹窗]K -- L[写接口]J -- M[结果呈现]L -- MM -- N[结论输出 审计留痕]三层语义保证命令能落到具体表和字段上编排保证每一步都可校验、可确认、可追溯。把三层语义、编排链路和能力底座放在一张图上看结构是这样的![自然语言操作链路全景三层语义 一个编排]这篇不讲新东西只做三件事把安全与不失控的边界讲清楚、把当前做不到的地方如实列出来、说说语音这条演进路。## 二、放开自然语言操作最怕的是什么系统里多了一个「用自然语言就能执行操作」的入口第一反应通常是担心会不会删错数据会不会被绕过权限我们的做法是把风险拆成四类一类一类堵。### 2.1 第一类执行了不该执行的东西链路里的脚本节点和条件节点都会执行代码。这类节点如果放任等于在画布上开了一个任意代码执行的口子。平台的处理收敛在一个安全模块里脚本与条件表达式的执行统一走沙箱求值全局对象是白名单制的window、document、fetch、eval 这类被明确阻断。越界会抛带固定错误码的可读错误沙箱类、脚本类、条件表达式类各有一组前缀而不是静默失败。关键点是「统一」脚本节点、条件节点、循环退出条件三处用的是同一个求值入口。如果有第二处自己实现白名单迟早会不同步。### 2.2 第二类请求打到了不该打的地方接口节点可以配任意地址这是风险点。约束有三条都在同一个安全模块里- 只允许绝对的 http / https 地址不允许相对路径、file: 之类的协议- URL 里不允许内嵌凭证也就是 user:passwordhost 这种写法- 请求一律不带凭证credentials 固定为 omit。第三条容易被忽略前端发请求默认可能带上同站凭证如果允许一个配错的地址就可能把用户的会话带到外部去。固定为不带这个可能性就被消掉了。### 2.3 第三类权限绕过这是最容易做错的一类。我们没为自然语言操作另建一套权限体系而是让它走既有接口的权限。查询调的是在线生成的列表接口写操作调的是生成的增删改接口授权调的是既有的授权端点。权限注解、租户隔离、数据权限这些既有能力全部生效。这个选择的代价是AI 能做的事不会超出当前用户本来就能做的事。好处也一样——不需要维护两套权限规则也就不会出现「页面上点不动、命令里却能改」的漏洞。### 2.4 第四类用户不知道自己触发了什么写操作这一类的处理是强制确认。四条操作子链新增、修改、删除、授权在执行前都会弹一个确认列表。新增显示将要写入的载荷摘要修改和删除先按定位条件查出候选行展示行主键与行标题让用户挑授权展示解析出来的目标用户与授权对象。取消的语义也写死了弹窗取消后节点状态置为「已取消」下游还没执行的节点级联标记为「跳过」实例以正常终态收尾不计入失败。**取消就是什么都没发生**不会留下半执行状态。## 三、错误分两类处理方式完全不同自然语言链路的报错很容易糊成一团。我们把错误分成两类处理方式分开。**用户可修复的错误**字段没配查询方式、定位条件缺失、表不在目录里、授权对象匹配不到、命令无法识别——这些都能靠改配置或改命令解决。处理方式是弹一个可读提示然后继续抛出错误让节点落到失败状态。**技术性错误**契约被破坏、路由分支不可达、框架不变量被违反——这些是开发要处理的。处理方式是打控制台错误日志同样继续抛。两类都不允许「吞掉异常继续往下跑」。关于允许写异常捕获的位置全仓库只有几处命令执行、模型调用、后端状态写回这几个审计边界。捕获的目的是补一条日志或提示然后**原样抛出原错误**不是把错误换成成功。这个约束在自然语言场景里格外重要。如果某一步失败被吞掉模型可能基于空数据继续往下编一个答案出来用户拿到一个看起来正常、实际错误的结果——这比直接报错危险得多。## 四、这套设计怎么扩展当初拆三段模型、把每个判断后面都接一道闸门有一个很实际的考虑将来要加东西时希望只改一小块。现在看扩展路径有三条各自边界清楚。**加一种意图。** 需要动三处意图识别的取值集合与提示词、意图校验脚本的集合断言、路由上的一个新分支加一条子链。不需要碰前面的定位逻辑也不需要碰其他分支的方案。**加一张表或一批字段。** 不需要动流程只要把表和字段登记到数据字典、生成对应接口然后重跑语义资源的两步刷新。链路会自动识别到新表——因为表定位的依据就是目录资源。**加一种节点能力。** 这是三条路径里最重的一条平台侧注册节点类型、实现处理器、按契约接入运行与调试两条模式。这条路我们不鼓励为了单个流程走因为它改的是引擎本身。顺带说一条我们给自己的约束这套链路的实现过程中引擎代码零改动也没有新增节点类型。所有能力都用已注册的 19 类节点拼出来。这条约束的收益在升级时体现——引擎升级不会因为业务流程里有私有节点而卡住。## 五、性能这件事的收尾前面一篇把机制列得很细这里只留三条判断。**能提前算的不要放到运行期。** 表目录、表关系、字典翻译三份数据离线产出运行期只读。为了让刷新可控我们接受了「改了字典要等刷新」这个代价。**能一次写完的不要分多次。** 节点实例的初始化和跳过标记都改成批量请求失败语义写死在接口里不允许出现半成功。**上限写死不给配置。** 200 行、50 行、20 条语句、5000 行结果、10 秒连接超时——这些数字存在的原因是保护系统不是给业务调优的。这三条没有一条是算法优化都是工程约束。但它们的收益很确定请求数下降一个量级运行期输入体积下降异常场景可预期。## 六、现在做不到的事写架构文章最容易犯的毛病是只讲能力不讲缺口。这里把我们的缺口列清楚。**一个命令只执行一次。** 没有多轮追问。用户说「查一下用户」但没说条件系统不会反问「按什么条件」而是按该命令的默认理解执行或给出可读提示。要支持多轮需要引入会话状态与澄清机制这是下一步的事。**复杂查询只开放读能力。** 结构化查询协议本身支持写类型但这套链路只用了查询类型。所有写操作都必须走在线生成的接口。这条限制是刻意的——写入要经过确认弹窗和权限判定不能从一条协议通道绕过去。**跨表关联查询的能力有限。** 计划里引用的字段只能来自目标表跨表关联需要在命令说明里描述清楚由后端按基座能力处理。这一点我们在提示词里写明了不做超出能力的承诺。**复杂结果的呈现方式是文本。** 结果以 Markdown 表格形式输出受确认弹窗的静态列限制还不能把任意结构的查询结果做成可交互表格。这是一个明确的后续项。**语义资源刷新是离线的。** 前面讲过取舍这里不重复但它是使用前必须知道的一条。**没有实测的性能数字。** 我们知道请求数降了、输入体积降了但没有做过正式的压测。所以文章里只写机制和上限不写倍数。## 七、语音这条路差什么标题里说的「未来语音」其实不是一句口号它对应一个具体的结构事实。这条链路的命令入口只有一个开始节点上的一个字符串参数。整条链路从头到尾只消费这一个输入不读取任何界面状态不依赖鼠标点击的位置也不需要用户先在某个页面上。这意味着接入语音只需要在入口前加一层语音转文字 → 把文本塞进这个参数 → 其余不变。真正要解决的不会是技术对接而是另外两件事。一是命令的容错。口述比打字更随意缺主语、省动词、口音转写错误都更常见。二是确认交互的形态现在确认是点一下列表语音场景下确认可能也要用说的。这两件事我们现在没有答案也不打算在文章里给一个看起来漂亮的方案。把三层语义、编排链路和演进路线放在一起大致是这样![三层语义与演进路线从文字命令到语音操作]## 八、怎么上手想自己跑一遍路径是这样的。代码在 Giteehttps://gitee.com/mindock/veap。环境需要 JDK 17、Maven 3.6、MySQL 8.x、Redis向量能力可选 Milvus 2.4.x。后端按单体模式打包mvn -B -pl veap-package/veap-monolith -am -DskipTests package。前端npm install npm run dev。起来之后按顺序做四件事登记数据表与字段、配置字段的查询方式并生成接口、构建三个语义资源并挂到节点、在画布上导入流程定义。源码里可以直接对照着看veap-ui/src/views/ai/agentDesign/ 是画布编排器veap-ui/src/components/AiAgentEngine/ 是执行器调度、状态、审计与安全边界都在这里veap-cloud/veap-modules/veap-gen/ 是在线开发与代码生成veap-cloud/veap-modules/veap-blockgen/ 是接口扫描veap-cloud/veap-modules/veap-ai/ 是语义模板与上下文资源同步。想看数据库层veap-cloud/DB/veap.sql 里 ai_agent_ 开头的十张表就是这套编排在库里的全部结构。## 最后这套方案的价值不在「用了大模型」而在于它把大模型放在了一个受控的位置上模型只负责从清单里挑不负责发明每一步的输出都要过一道确定性的闸门写操作必须经过人的确认每一次状态变化都留痕。它不便宜——需要先把字典、接口、术语三份清单做扎实改字典还要等资源刷新。但如果你的系统正在被「改一个查询要排期」消耗这份投入换来的是一个可以持续扩展的入口加一张表只要登记字典加一种意图只要加一条分支。真正的难点从来不是让机器听懂一句话而是让它在听懂之后只做该做的那一件事。