> 系列：VeapAI 自然语言操作实战（全体系架构专题）
> 本文要点：service_inst_conf 唯一装配 · 8 个注册表 · stage 输出强校验 · 错误语义与布局契约
同一套页面，为什么能装三种业务
问答、文档加工、语义模板生成，是三种完全不同的业务。但它们的前端底座是同一套：AiConsole。
打开任一服务的页面代码，你会发现里面几乎没有"业务分支"。页面不写"如果是问答就怎么显示、如果是加工就怎么显示"，只负责把服务配置交给运行时，由运行时把对应的业务模块装进来。
这就是框架层与业务层分离的意义：框架不做业务判断，业务不碰框架结构。中间靠一份装配配置和一组注册中心连接。
!问答服务：由 aiconsole.aiQuestion 装配出的单步问答界面
装配：service_inst_conf 说了算
!AiConsole 框架：装配、运行时骨架、八个注册表与业务 mod、稳定契约
每个 AI 服务的界面装配，唯一事实来源是 `ai_app_service.service_inst_conf`。这份配置里主要有四块：
-
`modIds`：显式声明启用的业务 mod；
-
`layoutId`：布局装配（例如单步问答布局）；
-
`stages`：工作流章节与默认提示词，后续所有校验都以 `stageId` 为主语；
-
`qaConfig` 与 `contextParamBindings`：问答装配参数与上下文绑定。
配置进来之后先过一道校验：`modIds` 必须是非空数组；如果列表里包含问答 mod，`qaConfig` 必须存在；未知的 modId 直接报错，重复的 modId 也直接报错。
规则只有一条核心：显式装配，禁止推断。不按前缀猜、不按命名约定猜、不"找不到就跳过"。看起来严苛，但它把配置错误从"页面运行时怪现象"变成了"加载那一刻的一句明确报错"。
八个注册表：框架的八个抽屉
业务 mod 拿到运行时的入口是 `RegistryHub`，它挂着八个注册表。可以理解为框架提供的八个抽屉，mod 往里放东西，运行时从里取东西：
| 注册表 | 放什么 |
| --- | --- |
| capabilities | 模型提供方等能力 |
| components | 可挂载组件 |
| commands | 可执行命令 |
| menus | 菜单装配 |
| stageOutputs | 每个 stage 的输出校验与归一 |
| workflows | 工作流目录 |
| contextParamExtensions | 上下文参数扩展 |
| contextParamHydratePatchers | 会话恢复时的上下文补丁 |
mod 的目录是自动登记的：`mods/entries` 下的每个模块在构建期被扫描进目录，`modId` 重复会在登记时报错。框架内置 mod 只有两个（core 与导航），并且明确规定：内置 mod 不注册任何业务 stage------业务能力必须由业务 mod 放进来。
!文档加工服务：由 aiconsole.kbBuild 装配出的两步加工界面
运行：从 stage 执行到强校验
!装配与强校验：启动装配链与一次 stage 输出的运行链
一次典型的 stage 执行，走五步：
-
会话恢复（hydrate）：上下文缺什么按补丁注册表补什么，只补一次，运行期不再推断；
-
stage 执行：按工作流位置取当前 stage，调用对应业务编辑器；
-
模型输出解析：先把结构化结果解析出来，解析失败给可读错误；
-
强校验：按当前 `stageId` 从 stageOutputs 注册表取校验器，对输出逐键断言；
-
写入状态：校验通过后写进 stageOutputs 与 contextParams，供后续步骤读取。
校验器的注册本身也有契约：`stageId` 必须非空且唯一；`assertOutput` 必须提供，缺了直接报错；可选的 `mergeOutput`、`normalizeOutput` 如果提供了，必须是函数。也就是说，"这个 stage 没有校验器"这种状态在系统里不允许存在。
后续步骤读取数据只经两个出口：stageOutputs 与 contextParams。跨步骤直接摸别的 mod 内部状态，是被禁止的。
!stage 导航与输出面板：每个步骤的输出经校验后才出现在这里
错误语义与布局契约
错误处理规则很直白：所有错误直接抛出，禁止空吞；业务 mod 用统一的可读错误构造器生成错误（机器可读的 message + 面向用户的 userMessage），提示通道由宿主统一承接；只有"需要写审计事件"的边界允许 try/catch------记录之后仍然要 rethrow。
布局上有一组不显眼但很硬的约定，都是被真实缺陷打磨出来的：
-
框架容器必须"可收缩"：flex / grid 子项显式 `min-width: 0`，grid 列用 `minmax(0, ...)`，否则内容会把布局越撑越宽；
-
滚动所有权唯一：纵向滚动归业务编辑器根节点（或表格内部），横向滚动归宽表局部容器，框架容器只做裁切；
-
禁止测量回写：不许通过监听容器宽度再回写表格像素宽度来"适配"，这类反馈环会让页面在渲染后缓慢变宽。
这些条款写在框架文档里，属于"改之前先读、读完再动手"的那一类。
源码走读
-
注册中枢：`veap-ui/src/components/AiConsole/registry/RegistryHub.js` 与 `registry/registries/*`（八个注册表）；
-
装配校验：`utils/serviceInstConf.js`（modIds 校验与 qaConfig 条件必填）；`mods/catalog.js`（精确解析 modId）与 `mods/autoRegister.js`（目录登记去重）；
-
业务 mod 示例：`mods/aiQuestion`、`mods/kbBuild`、`mods/semanticTemplateGen`；
-
页面宿主：`veap-ui/src/views/ai/AiConsole` 下的各服务页面。
较真：一个"找不到的变量"
框架侧最典型的一次排查，来自一个帮助面板。
组件上线后，帮助内容整块空白，控制台没有任何报错。逐行检查发现：帮助文案从模块里导出，被直接写进了模板引用。代码能编译、能运行，就是渲染不出东西。
根因是 Vue2 的一个特性：模板只能访问组件实例上的数据，脚本顶层 import 的常量在模板里不可见。修法很小------把常量在 `data()` 里暴露一次。排查过程却不小，因为它没有任何报错，只是在页面上"安静地空着"。
后来这条写进了组件开发约定：模块级常量进模板之前，先过 `data()`；同时也出现了一条相邻的规矩------业务组件里不允许做动态加载，一律静态引入，让装配时序保持可预测。
两件事的共同点：前端的坑往往不是"错了"，而是"没发生"。所以对装配类框架来说，显式报错比默默继续更贵------贵得值。
复现与验证
-
看装配：`SELECT service_code, service_inst_conf FROM ai_app_service WHERE service_code = '<服务编码>';`，核对 modIds / layoutId / stages；
-
看目录：打开 `veap-ui/src/components/AiConsole/mods/entries`，目录里的每个文件就是一个可装配的 mod；
-
验证"禁止推断"：把某个服务的 `modIds` 改成一个不存在的值，页面加载会直接报"modId 不存在或未注册"，不会静默降级。
这一层的边界：AiConsole 只是"前端运行时容器"，它不生产知识、不执行模型，也不承担业务规则。它做的是一件事------把可插拔的业务能力，按一份显式配置装进同一套交互骨架里，并且保证各方的约定在加载期就被检查。
架子搭好了，接下来看跑在架子上的两件事：编排引擎与全局语义命令。