# Cube 企业应用与 AI 平台技术白皮书

版本 2.0（详细图解版） · 2026 年 11 月 22 日 · 面向架构师、技术负责人、业务负责人及实施团队

Cube 将企业门户、组织身份、应用构建、业务流程、知识、业务语义和智能体放在同一套平台能力体系中。企业既可以建设新的业务应用，也可以接入现有系统，让员工通过统一入口办理业务，让 AI 在明确的业务口径与授权范围内参与工作。

本文依据本次核对的 Cube 开发包代码、平台说明和门户界面编写。**代码中存在的能力、现场可见的入口与客户环境的集成验收是三个不同层次。** 文中应用案例是实施示例，正式交付应以部署版本、License、资源授权和目标环境验收为准。

## 阅读导航与图解课程

本文按“平台与架构 → 17 项模块 → 业务贯穿场景 → 部署与验收 → 治理与选型”组织。每个模块配有真实产品截图、可展开播放的中文操作课程及开发手册入口。截图呈现演示环境中的实际 UI，不把演示数据视为经营实绩；课程采用真实操作关键帧与动态标注，非连续录屏。

| 阅读目的             | 建议路径                                                     |
| -------------------- | ------------------------------------------------------------ |
| 判断是否适合企业建设 | 平台定位、能力全景、贯穿场景、选型与实施路线                 |
| 理解技术责任边界     | 总体架构、身份与数据、执行分工、事务与运行治理               |
| 查看真实产品操作     | 各模块“真实界面与操作视频”，或进入[学习中心](/academy)       |
| 进行开发与配置       | [开发手册](/docs/cube/development)，先完成开发环境与场景基线 |

## 01 平台定位与设计原则

企业建设 AI 应用时，难点往往集中在模型之外：业务口径分散、数据访问权限不一致、工具和流程各自运行、操作结果难以核验。Cube 通过共享平台能力，把“员工入口—业务应用—知识与数据—智能执行—运行治理”连接起来。

- **统一入口**：门户展示员工可访问的应用、待办、消息、知识与智能体，保持原系统的业务归属。
- **能力复用**：应用、流程、提示词、技能、工具和语义模型可按权限组合，减少重复配置。
- **语义先行**：在需要跨系统理解业务时，先定义对象、口径、规则与数据映射，再让智能体使用。
- **执行有据**：区分分析建议、待审批计划、业务执行及真实回执，保留可追踪标识。
- **逐步建设**：先跑通一个可验证的业务场景，再扩展应用和 AI 能力。

典型建设对象包括统一办公平台、CRM、采购与库存协同、设备维修、知识问答、经营分析与业务自动化。接入 SAP、ERP、MES 等外部系统需要对应接口、连接器及项目映射，并非录入系统名称即可完成集成。

## 02 总体架构与职责分层

![Cube 平台架构职责图](/docs/cube/diagrams/platform-architecture.svg)

图为架构职责示意；Portal、Design、Admin 分别面向使用、设计与治理，实际部署不要求每个逻辑模块独立进程。

```text
员工与业务人员         实施与应用开发者         平台管理员
      │                     │                     │
      ▼                     ▼                     ▼
Portal 门户            Design 设计端          Admin 管理端
应用 / 待办 / 消息      表单 / 流程 / 页面      身份 / 组织 / 模型 / 审计
知识 / 智能体 / 办公    报表 / 语义 / AI构建    集成配置与平台治理
      └─────────────────────┬─────────────────────┘
                            ▼
企业应用与公共能力：应用元数据、BPM、消息、知识、语义、资产目录
                            ▼
执行体系：业务编排 / 智能体 / Harness 任务 / 模型网关
                            ▼
业务数据与基础设施：平台数据库、缓存、文件、连接器、外部业务系统
```

代码组织包含 `apps/portal`、`apps/admin`、`apps/design`、`apps/backend` 和 `apps/service`。前端工作区区分员工使用、应用设计与平台治理；后端按门户、组织、认证、流程、知识、语义、大屏和 AI 等领域组织。模块划分不意味着每个模块在所有部署方式下都独立运行，实际进程与依赖应按交付架构核对。

模型网关负责模型接入与调用治理；业务编排负责可定义的业务步骤；BPM 负责审批责任与流程状态；Harness 负责目标、计划、任务与结果。几者通过接口和上下文协作，各自保留运行与权限检查。

## 03 统一能力全景

| 能力域     | 模块                                                          | 主要产物                               |
| ---------- | ------------------------------------------------------------- | -------------------------------------- |
| 员工协同   | 门户、统一待办、统一消息、统一新闻公告                        | 工作入口、任务列表、通知、企业内容     |
| 身份与组织 | 统一安全认证、统一组织                                        | 登录会话、组织与角色、资源授权         |
| 应用生产   | 统一应用构建、统一流程定义、统一大屏或报表、AI 应用构建       | 表单、列表、页面、流程、报表、应用版本 |
| 知识与智能 | 统一知识库、智能体及提示词/技能/工具/MCP、业务语义            | 可引用知识、可调用能力、业务上下文     |
| 执行与治理 | 统一 Harness 调度、统一安全审计、统一大模型网关、统一业务编排 | 任务、执行计划、日志、模型路由与回执   |

以下 17 个模块分别说明业务价值、技术组成与集成边界。开发步骤见[开发手册](/docs/cube/development)。

## 04 门户 {#module-portal}

门户是员工进入平台的工作入口。工作台汇集待办、常用应用、快捷入口、知识与智能体，员工按当前身份访问资源。门户内容既包含平台数据，也可以包含经配置的业务页面或示例工作台。

**技术组成**：Portal 工作台路由、门户定义与用户配置、栏目组件、快捷入口和应用收藏。首页展示与业务数据通过相应服务接口连接，门户权限与应用内部权限需要分别生效。

**应用示例**：销售进入工作台查看待跟进事项、进入 CRM、查阅产品资料，再调用商机分析助手。

**集成边界**：演示卡片中的商机或回款数字不等于已接入的实时指标。新增外部卡片时，应明确数据源、刷新周期、空态和失败提示，并核验跳转后权限。

### 工作入口、业务归属与工作台组合

门户以当前身份为起点，组织工作台、应用中心、审批入口、消息、知识和智能体。工作台中的卡片是业务入口与数据摘要；完整单据、审批责任和数据写入规则仍由来源模块维护。比如“待办数为 8”只表示聚合查询结果，不代表 8 笔业务已进入可办理状态，进入详情时仍应重新检查任务有效性。

| 工作区     | 读者关心的信息               | 集成设计重点                                       |
| ---------- | ---------------------------- | -------------------------------------------------- |
| 我的工作   | 待办、申请、已办、待阅、协同 | 明确来源任务标识、分页、统计口径及跳转参数         |
| 常用应用   | 当前有权访问的应用与收藏     | 收藏只改变入口，不提升权限；应用下线后应有清晰提示 |
| 内容与知识 | 新闻、制度、文档和知识库     | 公告可见范围与知识共享范围分别维护                 |
| 智能助手   | 可使用的智能体及业务能力     | 区分对话、分析与实际业务执行，保留原任务或运行标识 |

典型使用链为“识别今日工作 → 打开已授权应用 → 查询或办理 → 返回工作台核对状态”。门户聚合应考虑局部失败：某一业务服务超时，不应把整个门户变成空白页；区块应显示加载、无数据、无权限或失败状态，避免把失败显示为数量零。

跨系统接入时，需要梳理登录方式、应用编码、深链接、PC/移动地址和目标系统可用性。外部系统的按钮打开成功，只证明导航有效，还应核对目标用户映射和业务资源授权。

### 门户：真实界面与操作视频

![门户真实产品界面：应用搜索 · AI-CRM实际筛选结果](/academy/screens/portal-app-search.webp)

图中为已采集的真实产品界面。阅读时重点核对“进入常用应用”涉及的入口与资源；示例或空态以演示环境为准。

[观看《门户》完整动态操作课程](/academy/portal) · [下载本模块操作讲义](/academy/portal/guide.md) · [查看真实界面原图](/academy/screens/portal-app-search.webp)

```academy-video
portal
```

[开发与配置细则：门户](/docs/cube/development#module-portal)

## 05 统一待办 {#module-todo}

统一待办集中呈现员工需要办理、已经办理、本人发起或抄送的事项。平台同时存在聚合任务接口与 BPM 任务接口，页面需按事项类型进入原业务办理链路。

**技术组成**：任务聚合查询、任务数量统计、BPM 待办与流程实例、办理详情和状态回读。建议用“来源系统 + 业务标识 + 任务标识”关联跨系统事项。

**应用示例**：报价审批在门户进入待办，审批人核对报价与附件后完成办理；原流程记录审批结果，门户刷新待办数量。

**集成边界**：展示待办不会自动接管外部系统的流程引擎。外部事项的同步、撤回、已办回写和重复任务处理需要独立适配，数量汇总也要说明统计口径。

### 任务身份、办理链路与状态一致性

统一待办围绕“谁需要处理哪一个业务事项”组织工作。流程定义标识一种审批规则，流程实例标识某一次业务流转，任务标识当前节点的具体办理责任。三者应分别记录，不能仅以单据标题作为任务唯一键。

| 对象       | 用途                       | 容易混淆的边界                         |
| ---------- | -------------------------- | -------------------------------------- |
| 业务单据   | 保存采购、合同等业务事实   | 单据存在不表示审批已发起               |
| 流程实例   | 保存流转路径与实例状态     | 实例存在不表示当前用户可办理           |
| 当前任务   | 保存节点、参与人和办理动作 | 任务可能因撤回、转办或其他人办理而失效 |
| 已办与历史 | 追踪曾经办理的行为         | 已办记录不等于整个业务已完成           |

典型办理链为“查待办 → 查看来源单据与附件 → 确认当前节点 → 执行允许动作 → 核对接口回执 → 刷新任务与历史”。聚合端应保留来源类型、任务 ID、实例 ID、单据 ID 与更新时间。跨系统任务接入还需制定防重键、回调认证和状态对账机制。

并发情况下，两个窗口可能看到同一任务，办理端必须检查任务当时是否仍有效。统一待办不能通过前端删除列表项来模拟完成；失败或结果未知时，先查询原流程与单据，再判断是否允许重试。

### 统一待办：真实界面与操作视频

![统一待办真实产品界面：我的待办 · 实际任务与条件筛选](/academy/screens/todo-list-live.webp)

图中为已采集的真实产品界面。阅读时重点核对“核对我的待办”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一待办》完整动态操作课程](/academy/todo) · [下载本模块操作讲义](/academy/todo/guide.md) · [查看真实界面原图](/academy/screens/todo-list-live.webp)

```academy-video
todo
```

[开发与配置细则：统一待办](/docs/cube/development#module-todo)

## 06 统一消息 {#module-messages}

消息中心按业务场景组织消息模板、接收人规则、通道配置和投递任务，并提供投递记录、站内收件箱、回调与重试接口。原有门户站内信接口仍然存在，接入时应选定主链路，避免重复通知。

**技术组成**：消息场景绑定、模板变量、通道策略、任务与分发记录、已读状态、失败补偿。短信、邮件或企业通信通道能否使用，取决于供应商、凭据和回调配置。

**应用示例**：采购申请到达审批节点后生成站内通知；根据接收人和通道策略发送通知，并保留投递结果。

**集成边界**：业务成功、消息提交成功、通道送达、员工已读是不同状态。重试必须沿用幂等关联，回调需验证来源；不能用已读回执替代审批结果。

### 从业务事件到员工收件箱

统一消息将业务事件、内容模板、接收人、通道、投递记录分开管理。采购审批到达某个节点，是消息触发事件；给哪一组人员发什么内容，是消息场景配置；站内、邮件或其他供应商通道是投递方式。这样可以在保持业务含义稳定的同时调整通知渠道。

```text
业务事件 → 场景与模板 → 接收人解析 → 消息任务 → 通道分发
                                                   ↓
业务办理状态 ← 业务系统                       投递回执 / 员工阅读
```

投递提交、供应商接受、最终送达与员工已读应分别展示。消息中心不能用“任务创建成功”代替“员工已收到”。对于需要重试的通道，实施方案应明确幂等键、最大次数、退避间隔、超时结果与人工补偿入口。

模板变量应有定义、样例和缺失处理，链接应指向当前用户有权访问的单据。通知正文只携带办理所需信息，敏感详情通过登录后的业务页面查看。发送规则、通道凭据和回调验签属于服务端配置，不能放到门户脚本里。

### 统一消息：真实界面与操作视频

![统一消息真实产品界面：统一消息中心 / 模板管理](/academy/screens/messages-templates.webp)

图中为已采集的真实产品界面。阅读时重点核对“编写并预览模板”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一消息》完整动态操作课程](/academy/messages) · [下载本模块操作讲义](/academy/messages/guide.md) · [查看真实界面原图](/academy/screens/messages-templates.webp)

```academy-video
messages
```

[开发与配置细则：统一消息](/docs/cube/development#module-messages)

## 07 统一新闻公告 {#module-news}

新闻公告为企业制度、业务动态与通知提供集中发布入口。栏目、内容和门户展示解耦，支持按栏目查询、阅读及发布状态管理。

**技术组成**：新闻内容、栏目分类、发布与下架、阅读入口和门户展示。后台保存草稿后，需走发布操作才能作为正式内容展示。

**应用示例**：总部发布销售政策，在门户公告区展示，并由知识维护人员决定是否同步进入知识库。

**集成边界**：新闻发布、消息通知和知识索引属于不同链路。下架公告后，关联知识、外部缓存或已发送通知的处理需要有明确规则。

### 企业内容生命周期

新闻公告解决企业内容的集中编排与展示，消息中心解决“把变化通知给谁”，知识库解决“让内容可检索与可引用”。三者可以配合，但生命周期互不替代。发布一条制度公告后，是否发送消息、是否同步到知识库，需要分别确认和记录。

建议项目按“内容草稿 → 审阅 → 正式发布 → 到期复核 → 下架/归档”管理内容；这是一套实施流程，是否每一步都有独立系统状态，应以当前部署的编辑和发布入口核对。制度类内容还应标注业务所有人、适用组织、生效时间、版本及替代关系。

发布后不仅要验证文章详情，还要验证栏目列表、门户轮播、搜索入口和无权用户访问。标题可见而正文受限、附件无权限、过期轮播残留等问题应纳入验收。新闻下架不会自动撤回已发消息，也不能假定已被知识库解析的旧版本自动失效，应建立跨模块内容变更清单。

### 统一新闻公告：真实界面与操作视频

![统一新闻公告真实产品界面：新增新闻公告表单](/academy/screens/news-editor.webp)

图中为已采集的真实产品界面。阅读时重点核对“创建内容草稿”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一新闻公告》完整动态操作课程](/academy/news) · [下载本模块操作讲义](/academy/news/guide.md) · [查看真实界面原图](/academy/screens/news-editor.webp)

```academy-video
news
```

[开发与配置细则：统一新闻公告](/docs/cube/development#module-news)

## 08 统一安全认证 {#module-auth}

认证中心为平台不同端提供登录与会话基础。代码包含 OAuth2 相关客户端配置、会话管理及 SSO 会话恢复链路；前端也提供 PKCE 登录相关处理。

**技术组成**：认证服务、注册客户端、访问令牌与会话、密码策略、登录退出及客户端回调配置。

**应用示例**：员工登录后访问门户、应用设计或管理端；各资源按登录身份及授权校验访问范围。

**集成边界**：单点登录解决身份连续性，应用仍需校验菜单、功能与数据权限。已有系统接入应核对协议、回调白名单、会话退出、令牌有效期与人员标识映射；不应把浏览器可见配置当作服务器机密的存储位置。

### 身份连续性与资源授权

认证链回答“当前是谁”，授权链回答“该身份现在能做什么”。平台前端包含密码登录、OAuth 授权码交换、PKCE、刷新与退出相关接口；服务端提供认证和 SSO 相关控制器。实际采用的登录方式取决于部署配置和客户端注册，不应把所有代码入口视为全部已启用。

```text
访问业务页面 → 判断会话 → 认证端验证身份 → 回调与状态校验
     → 建立本端身份 → 获取角色与资源 → 每次请求再校验数据和动作
```

多端场景中，Portal、Admin 与 Design 的跳转需要统一公开来源地址与回调规则。浏览器的协议、域名、端口和路径参与回调校验；开发环境混用 localhost 与 127.0.0.1 可能造成会话不连续。

密码策略、令牌有效期、刷新、主动退出、强制退出和用户停用需形成完整会话策略。单点退出能影响哪些客户端，应通过实际会话验证；隐藏菜单不能替代接口授权。外部身份接入还需要稳定人员标识、账号冲突处理和停用传播机制。

### 统一安全认证：真实界面与操作视频

![统一安全认证真实产品界面：统一认证 · 实际登录页配置](/academy/screens/auth-settings-live.webp)

图中为已采集的真实产品界面。阅读时重点核对“核对客户端配置”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一安全认证》完整动态操作课程](/academy/auth) · [下载本模块操作讲义](/academy/auth/guide.md) · [查看真实界面原图](/academy/screens/auth-settings-live.webp)

```academy-video
auth
```

[开发与配置细则：统一安全认证](/docs/cube/development#module-auth)

## 09 统一组织 {#module-organization}

组织模块维护人员、组织分组、组织维度与角色等基础信息，为应用可见范围、流程选人、知识权限和管理权限提供依据。

**技术组成**：人员、机构/分组、角色与授权、关系及同步接口。不同业务可能按部门、岗位或项目角色选择参与人，应明确主数据归属。

**应用示例**：销售申请由所在部门负责人审批；区域销售只访问本区域业务；离职人员同步停用并清理有效会话。

**集成边界**：组织同步需要稳定的外部 ID、增量与离职策略。组织记录更新不等于所有业务授权已刷新，应验证缓存、历史任务与交接规则。

### 组织主数据与多维授权

统一组织为应用、流程、知识和智能执行提供人员与组织关系。企业中行政部门、项目组、岗位、业务区域和应用角色可能同时存在；实施时应明确哪一种关系负责审批选人，哪一种关系负责资源授权，哪一种关系用于报表维度。

| 主数据   | 建议管理约定                      | 影响范围                               |
| -------- | --------------------------------- | -------------------------------------- |
| 人员     | 稳定外部 ID、唯一账号、启停与归属 | 登录、待办归属、应用与知识权限         |
| 组织分组 | 编码、父子关系、维度、有效期      | 组织树、数据范围、流程选人             |
| 角色     | 业务职责、授权范围、责任人        | 菜单、动作、管理能力                   |
| 人员关系 | 主属/兼职、岗位与项目归属         | 审批、代理、区域数据；支持范围逐项核对 |

组织同步应优先采用外部 ID 映射，避免按姓名匹配。新增、移动、兼岗和离职要分别制定规则。离职不仅是停用用户，还涉及有效会话、未办任务、数据负责人、文档共享和应用维护责任的交接。

授权变化的生效时机应对缓存、现有会话与后台任务分别验证。历史流程记录应保留当时的办理事实，不应因组织树调整而改写历史责任。

### 统一组织：真实界面与操作视频

![统一组织真实产品界面：组织与成员](/academy/screens/organization.webp)

图中为已采集的真实产品界面。阅读时重点核对“建立组织与人员”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一组织》完整动态操作课程](/academy/organization) · [下载本模块操作讲义](/academy/organization/guide.md) · [查看真实界面原图](/academy/screens/organization.webp)

```academy-video
organization
```

[开发与配置细则：统一组织](/docs/cube/development#module-organization)

## 10 统一应用构建 {#module-application}

统一应用构建以应用为边界组织数据模型、表单、列表、页面、菜单与资源权限。开发者可从业务需求建立应用结构，再配置页面和业务操作。

**技术组成**：应用目录、主子表模型、表单设计、列表视图、页面、大屏资源、菜单授权与版本。AI 构建和人工设计应复用已发布的原生资源，避免形成两套互不相认的定义。

**应用示例**：采购应用包含供应商、采购申请主子表、审批流程和执行看板；CRM 包含客户、报价、合同及回款关联。

**集成边界**：页面预览通过不足以证明应用可交付。应分别验证字段约束、主子表读写、按钮行为、数据权限、版本导出与目标环境安装。涉及高码项目时，还需满足运行环境、构建与交付配置。

### 应用元数据与原生资源模型

应用构建将业务对象、字段、表单、列表、按钮、菜单和资源权限组织为可管理的应用。原生资源是平台设计器与运行时共同识别的定义。AI 生成和人工配置需要回到同一套资源，才能继续编辑、授权、导出和升级。

| 资源层 | 典型内容                   | 设计关注点                                 |
| ------ | -------------------------- | ------------------------------------------ |
| 数据层 | 主表、明细、字段、关系     | 主键、金额精度、字典、约束、审计与数据归属 |
| 交互层 | 表单、列表、页面、按钮     | 校验、查询、分页、附件、错误回显           |
| 流转层 | 流程绑定、编排与业务动作   | 状态机、并发、防重与失败恢复               |
| 访问层 | 菜单、角色、功能与数据范围 | 查看、编辑、导出和动作权限分别检查         |
| 交付层 | 版本、资源包与安装配置     | 依赖、原生资源回读与目标环境回归           |

例如采购申请主表保存申请部门、币种和总额，明细保存物料、数量和单价。总额的服务端计算和流程状态约束不能仅依赖前端只读属性。保存主子表后还应检查完整单据回读，而非只检查新增行返回值。

平台应用开发、高码工程与独立交付具有不同构建依赖。是否支持特定扩展、数据库或部署形态，应结合支持矩阵和交付方式核对，不能从设计界面推导为任意工程均可一键部署。

### 统一应用构建：真实界面与操作视频

![统一应用构建真实产品界面：小型进销存 / 业务模型](/academy/screens/application-model.webp)

图中为已采集的真实产品界面。阅读时重点核对“设计主子表模型”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一应用构建》完整动态操作课程](/academy/application) · [下载本模块操作讲义](/academy/application/guide.md) · [查看真实界面原图](/academy/screens/application-model.webp)

```academy-video
application
```

[开发与配置细则：统一应用构建](/docs/cube/development#module-application)

## 11 统一流程定义 {#module-workflow}

流程定义为审批与协作配置参与人、节点、条件和表单关联；BPM 实例承载每一次具体办理的进度与结果。

**技术组成**：流程定义与模型、节点配置、表单绑定、流程实例、待办、意见和运行管理。业务动作可以在明确的节点和权限条件下接入编排或智能体。

**应用示例**：采购申请按金额分支审批，审批完成后触发业务单据转换；AI 可辅助提取附件与解释风险，由指定人员作审批决定。

**集成边界**：流程定义发布与流程实例完结分别验收。流程退回、撤回、转办、会签和无有效审批人等异常分支应测试；流程变更对在途实例的处理按引擎配置确认。

### 审批责任、流程状态与业务动作

BPM 的核心是确定办理责任和流转路径。应用状态机描述业务是否可编辑、可转换或可归档；流程状态描述实例当前走到哪里。二者需要建立明确关联，但不应直接混为一个字段。

流程设计需要明确开始条件、节点表单、办理人来源、条件分支、意见和结束动作。以采购审批为例，金额应先按指定币种和精度确定，再用于分支；“大于”和“大于等于”的差异会影响临界金额的审批人。组织为空或负责人失效时，需要明确提示或转人工处理，不能静默通过。

| 变更           | 需要核对的对象       | 实施决策                           |
| -------------- | -------------------- | ---------------------------------- |
| 节点人员变化   | 当前任务与后续节点   | 是重新解析、人工转办还是保留原责任 |
| 定义发布新版本 | 新实例与在途实例     | 不默认假设在途实例自动迁移         |
| 业务撤回/驳回  | 单据状态、任务、历史 | 可再次提交的字段和流程版本         |
| 审批后调用接口 | 业务结果、流程回执   | 明确提交成功与业务完成的差异       |

AI 可协助整理附件、风险摘要和依据，审批决定仍由授权主体按业务制度作出。流程结束后调用外部系统时，需要对接口失败和结果未知建立补偿方案；流程实例结束不等于所有外部副作用已完成。

### 统一流程定义：真实界面与操作视频

![统一流程定义真实产品界面：商机阶段审批 / 真实流程设计器](/academy/screens/workflow.webp)

图中为已采集的真实产品界面。阅读时重点核对“绘制节点与分支”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一流程定义》完整动态操作课程](/academy/workflow) · [下载本模块操作讲义](/academy/workflow/guide.md) · [查看真实界面原图](/academy/screens/workflow.webp)

```academy-video
workflow
```

[开发与配置细则：统一流程定义](/docs/cube/development#module-workflow)

## 12 统一大屏或报表 {#module-reports}

平台包含大屏与报表相关服务、设计接口及运行入口，用于把应用数据呈现为经营看板、统计报表或业务明细。

**技术组成**：大屏视图、数据模型、图表、权限、历史与分享管理，以及报表相关资源。多视图列表、定制页面与专业大屏在应用构建中具有各自的资源定义。

**应用示例**：采购看板呈现待审批金额、交期风险和供应商分布；CRM 报表按统一口径计算净销售额与逾期应收。

**集成边界**：图表外观、数据接通、指标正确和访问授权须分别核对。分享链接与导出文件也应测试数据范围；未接入实时数据时应标注为示例或快照。

### 指标口径、数据范围与展示资源

报表首先是可解释的指标，再是可视化。一个“销售额”指标至少要定义订单/合同来源、含税与否、币种、状态过滤、时间字段和撤销处理。看板、问数、智能体和经营周报应尽量复用同一指标定义。

大屏设计、报表资源和多视图列表服务不同需求：大屏强调组合展示与布局，报表强调统计和明细对账，列表强调业务数据浏览与操作。某个界面能呈现图表，不代表其发布、分享和导出权限完全相同。

建议保留指标说明卡：指标编码、负责人、单位、计算方式、来源、统计周期、刷新时间和权限范围。图表旁应呈现数据时间，区分实时查询、缓存与周期汇总。空值、无权限、无数据与接口失败应有不同表现。

分享和导出属于独立数据出口，应单独验收。页面只显示某部门数据时，导出不能退回全量查询；分享地址也不能绕过登录、角色与资源范围。地图、外部数据集、实时消息流等能力以实际连接器和部署资源为前提。

### 统一大屏或报表：真实界面与操作视频

![统一大屏或报表真实产品界面：报表设计器 / 排版与字段绑定](/academy/screens/reports.webp)

图中为已采集的真实产品界面。阅读时重点核对“连接授权数据”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一大屏或报表》完整动态操作课程](/academy/reports) · [下载本模块操作讲义](/academy/reports/guide.md) · [查看真实界面原图](/academy/screens/reports.webp)

```academy-video
reports
```

[开发与配置细则：统一大屏或报表](/docs/cube/development#module-reports)

## 13 统一知识库 {#module-knowledge}

知识库为企业资料提供组织、检索和问答能力，包含知识库、文档、分片、共享权限和门户入口。RAG 问答将可用知识片段提供给模型，回答依据与普通检索候选分别呈现。

**技术组成**：文件与文档管理、解析和检索、知识权限、问答及引用。向量、重排与问答模型需要各自可用的模型能力配置。

**应用示例**：销售咨询产品交付条款，助手返回有来源的说明；维修人员查询设备手册，再结合授权业务数据核对设备状态。

**集成边界**：上传成功不等于解析或索引成功；检索命中不等于回答被证据支持。没有依据、权限不足与模型调用失败应分别提示。完整冻结评测、发布门禁等治理目标需按版本核实，不能把规划内容写成现成能力。

### 从资料到可引用答案

知识链路包含资料登记、解析、片段、索引、检索、上下文组装和回答。每个阶段都应可诊断：上传成功不代表解析完成，全文就绪不代表向量就绪，搜索找到候选也不代表生成答案已经有足够依据。

```text
授权资料 → 解析与片段 → 全文 / 向量 / 可选重排 → 授权候选
                                                       ↓
                  答案与引用 ← 组织上下文 ← 当前问题与历史
```

当前部署指南将 PostgreSQL 作为默认全文检索策略，基于已解析并启用的片段召回；不要求先配置 embedding。向量检索可以采用 pgvector，也存在其他可选组件，须核对实际配置与兼容性。向量链路需要可用 embedding 模型及能力绑定，重排则需要独立重排能力，不能用普通聊天模型替代。

知识治理需要管理资料所有人、版本、有效期、共享范围与冲突规则。权限应贯穿检索候选、文档打开、引用与下载；不能只在知识库入口隐藏文件。模型回答应说明引用与适用范围，资料不足或相互冲突时保留不确定性。

验收样本应覆盖正确问题、同义表达、无答案、过期资料、跨部门越权及带有恶意指令的文档。文档内容只能作为资料，不能获得替用户授权调用工具或更改规则的权力。

### 统一知识库：真实界面与操作视频

![统一知识库真实产品界面：知识资产 · 目录和文档操作](/academy/screens/knowledge-docs-live.webp)

图中为已采集的真实产品界面。阅读时重点核对“上传并检查加工”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一知识库》完整动态操作课程](/academy/knowledge) · [下载本模块操作讲义](/academy/knowledge/guide.md) · [查看真实界面原图](/academy/screens/knowledge-docs-live.webp)

```academy-video
knowledge
```

[开发与配置细则：统一知识库](/docs/cube/development#module-knowledge)

## 14 智能体与能力资产 {#module-agents}

智能体把模型、指令和可访问资源组合成面向任务的工作助手。提示词模板、技能、工具与 MCP 各自维护，可以在智能体配置中按需绑定。

| 资产       | 主要职责                         | 接入与验证要点                                 |
| ---------- | -------------------------------- | ---------------------------------------------- |
| 提示词模板 | 角色、任务、输入变量与输出约定   | 用真实变量测试，避免把示例文本当作业务事实     |
| 技能       | 可复用的方法、步骤与工具使用约定 | 核对技能内容、依赖、发布状态及实际可执行范围   |
| 工具       | 明确输入输出的业务操作           | 校验 Schema、权限、副作用、超时与错误语义      |
| MCP        | 通过协议发现和调用服务工具       | 连接测试、工具发现、认证、输入校验与服务可用性 |
| 知识库     | 文档与知识依据                   | 使用可访问库，核验检索与引用                   |
| 业务语义   | 统一口径、对象关系及受控上下文   | 使用已发布版本、有效映射与场景绑定             |

**应用示例**：合同助手先读取合同信息与制度，再给出风险提示。生成合同或通知外部人员时，应调用经过授权的业务动作并核验结果。

**集成边界**：配置可以独立创建或关联应用，引用须使用真实资源 ID。工具、知识库、技能和 MCP 并非全部必填。保存为草稿与正式发布分开；“有某个工具”不等于当前身份有权执行。技能的文本步骤也不自动赋予底层权限。

### 智能资产的分工与执行契约

| 资产       | 负责什么                         | 推荐管理信息                                       |
| ---------- | -------------------------------- | -------------------------------------------------- |
| 提示词模板 | 角色、目标、输入结构、回答约束   | 版本、变量、样例、输出格式与无依据行为             |
| 技能       | 可复用的任务方法和执行约定       | 适用场景、前置条件、依赖工具、成果与限制           |
| 工具       | 读取数据或执行具体操作           | 输入输出 Schema、权限、副作用、超时、幂等与回执    |
| MCP 服务   | 按协议暴露外部能力               | 服务来源、连接方式、认证引用、工具白名单与健康检查 |
| 智能体     | 组合模型、知识、资产与业务上下文 | 所属应用、绑定资产、可见范围、版本与发布状态       |

资产绑定是引用关系，不会自动授予来源资源权限。MCP 连接成功说明协议握手或服务可达，还应分别验证工具发现、单次只读调用、身份传递和写入策略。工具描述中声称“只读”，也应与实际执行器核对。

运行时应把模型判断、工具请求、工具响应和最终总结分开留存。模型声称“已经提交”不能替代执行器回执。写入型工具需要明确审批、幂等、防重和结果核验；返回未知时，应阻止无条件自动重放。

智能体测试至少包括：有依据回答、知识不足、无权资源、参数不合法、工具失败、超时、恶意指令和重复动作。评测应记录绑定版本与实际模型，避免模型或知识更新后继续引用旧结论。

### 智能体与能力资产：真实界面与操作视频

![智能体与能力资产真实产品界面：提示词模板新建配置表单](/academy/screens/agent-prompt-editor.webp)

图中为已采集的真实产品界面。阅读时重点核对“准备技能与工具”涉及的入口与资源；示例或空态以演示环境为准。

[观看《智能体与能力资产》完整动态操作课程](/academy/agents) · [下载本模块操作讲义](/academy/agents/guide.md) · [查看真实界面原图](/academy/screens/agent-prompt-editor.webp)

```academy-video
agents
```

[开发与配置细则：智能体与能力资产](/docs/cube/development#module-agents)

## 15 统一 Harness 调度 {#module-harness}

Harness 在平台中组织“业务目标—计划—执行任务—结果”。它把已发布、可访问的能力与输入约束用于规划，向员工呈现需要补充的条件、待确认动作、运行状态与产物。

**技术组成**：业务范围、能力目录、需求、计划、任务运行、结果及发布申请。任务记录与真实工具回执共同用于判断完成情况。

**应用示例**：员工提出“分析本月逾期回款并准备跟进报告”。系统发现只读分析能力，必要时追问时间和对象；涉及写入或通知的步骤先显示具体对象与参数，再按审批要求执行。

**与定时任务的关系**：Harness 的任务计划管理与 XXL-JOB 等定时任务管理属于不同职责。定时触发、分布式执行和进程重启恢复，应按具体执行链路与部署配置验收。

**集成边界**：已核对的设计任务链路包含模型生成方案与异步执行，但不应据此承诺每个步骤都能持续自主重规划，或所有任务都能持久化重启恢复。业务结果未知时，先对账再决定是否重试。

### 目标、计划、确认、运行与证据

Harness 将复杂目标整理为计划和可执行任务，把能力选择、参数、作用域和结果串联起来。它适合经营周报、合同审查、应收分析等需要多种能力协作的场景。确定性单据转换仍应优先交给业务编排，审批责任交给 BPM。

```text
目标与作用域 → 计划草案 → 依赖检查 → 人工确认 → 领取运行
                                                     ↓
          业务终态核验 ← 工具回执与成果 ← 分步执行与状态
```

确认应绑定计划摘要、需求版本、作用域、操作参数和能力契约。用户修改计划或参数后，应重新确认。执行前仍需复核授权、发布版本、调用地址和风险策略，避免计划形成后权限或数据已变化。

结果要区分内容生成、操作提交、已核验完成与结果未知。报告正文是内容成果，受理号是提交证据，只有领域系统可回查的终态才能证明业务完成。平台计划与办公受控业务计划可能使用不同 ID，日志关联时应保留其对应关系。

后台执行是额外运行契约。定时或事件触发还需验证调度归属、执行身份、持久化队列、重启恢复、租约、防重、取消和外部结果核验。普通异步线程不能直接表述为可恢复的企业任务调度；自动重规划和无人值守运行需以现场验证结果为准。

### 统一 Harness 调度：真实界面与操作视频

![统一 Harness 调度真实产品界面：Harness / 我的任务](/academy/screens/harness-tasks.webp)

图中为已采集的真实产品界面。阅读时重点核对“描述目标并补条件”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一 Harness 调度》完整动态操作课程](/academy/harness) · [下载本模块操作讲义](/academy/harness/guide.md) · [查看真实界面原图](/academy/screens/harness-tasks.webp)

```academy-video
harness
```

[开发与配置细则：统一 Harness 调度](/docs/cube/development#module-harness)

## 16 统一安全审计 {#module-audit}

安全审计覆盖身份会话、平台操作、AI 运行、模型调用与业务动作等多个领域。相关日志与管理入口分布在认证、系统、AI 治理、语义和业务编排模块中。

**技术组成**：有效会话管理、系统日志、模型调用审计、运行轨迹、语义执行计划与动作回执、编排节点日志。

**应用示例**：管理员从异常任务找到运行标识，核对用户、应用、模型路由、审批记录及业务回执，确认失败发生在模型调用还是业务写入。

**集成边界**：多领域日志不等于所有记录天然统一到一张表。项目应建立 taskId、runId、traceId、业务主键等关联规范，分别配置保留期、访问权限和脱敏。日志存在并不自动构成防篡改存证或特定合规认证。

### 分层审计与跨模块关联

平台审计、业务审计与模型调用审计关注点不同。平台审计记录账号与配置变更；业务审计记录谁对哪张单据做了什么；智能执行审计记录计划、工具、模型与结果。建立关联规范后，才能把一次员工请求追踪到实际单据与模型成本。

| 层面       | 应关注的记录                       | 不能据此推断                   |
| ---------- | ---------------------------------- | ------------------------------ |
| 登录与管理 | 登录结果、配置操作、操作者与时间   | 已登录不等于已获业务权限       |
| 应用与流程 | 单据、实例、节点、意见和回执       | 操作日志不自动表示业务提交成功 |
| 智能运行   | 计划、任务、工具响应与业务核验     | 模型总结不等于执行结果         |
| 模型网关   | 能力绑定、调用状态、用量与费用口径 | 单次调用成功不等于全场景成功   |

项目可以约定统一关联 ID，并保留服务各自原生的 requestId、planId、jobId、runId、instanceId 与业务 ID。字段名称和支持情况应以具体接口为准，不能假定每个日志都天然包含同一字段。

审计本身也需要授权、脱敏、保留与检索策略。配置密钥、完整令牌、个人信息和敏感提示词不应进入普通日志。平台页面存在日志查询入口，不代表已经具备法律意义上的不可篡改归档；若有此要求，需要独立存储、权限隔离与恢复验证。

### 统一安全审计：真实界面与操作视频

![统一安全审计真实产品界面：安全审计 / 安全策略](/academy/screens/audit.webp)

图中为已采集的真实产品界面。阅读时重点核对“配置访问和保留”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一安全审计》完整动态操作课程](/academy/audit) · [下载本模块操作讲义](/academy/audit/guide.md) · [查看真实界面原图](/academy/screens/audit.webp)

```academy-video
audit
```

[开发与配置细则：统一安全审计](/docs/cube/development#module-audit)

## 17 统一大模型网关 {#module-model-gateway}

模型网关统一管理模型端点、凭据、能力绑定和调用治理。业务组件按能力使用模型，减少把供应商地址或密钥写入应用的情况。

**技术组成**：模型提供方、加密凭据、主备能力绑定、健康探测、调用审计、用量与价格、预算和内容策略。

| 能力标识示例         | 主要用途               |
| -------------------- | ---------------------- |
| `task.chat`          | 门户任务对话           |
| `design.generate`    | 页面与应用设计生成     |
| `desktop.assistant`  | DSH 助手               |
| `agent.runtime`      | 智能体与规划调用       |
| `knowledge.answer`   | 知识回答               |
| `embedding.retrieve` | 文本向量检索           |
| `knowledge.rerank`   | 知识重排               |
| `vision.chat`        | 支持视觉输入的实际模型 |

**应用示例**：办公对话使用一个模型，知识检索采用独立的向量和重排模型；管理员统一查看调用量与成本策略。

**集成边界**：端点保存成功和目录非空不代表真实调用通过；需执行健康探测并用实际业务请求验证。文本、向量、视觉和重排能力不能仅靠名称互换。成本估算依赖实际用量与有效价格，缺少计费信息时不能显示为零成本。

### 能力绑定与模型治理链路

网关把“业务需要的能力”与“具体供应商模型”解耦。业务调用 `knowledge.answer`，管理员决定该能力使用哪个主模型与备用模型。调整绑定不应要求业务页面直接持有供应商密钥。

| 能力标识                                | 主要用途           | 前置核验                           |
| --------------------------------------- | ------------------ | ---------------------------------- |
| `task.chat` / `agent.runtime`           | 任务对话、智能体   | 文本、流式与所需工具能力           |
| `design.generate` / `desktop.assistant` | 应用设计、DSH 助手 | 结构化生成、工具或实际上下文需求   |
| `knowledge.answer`                      | 知识回答           | 文本生成；引用由知识链路提供       |
| `embedding.retrieve`                    | 文本向量           | embedding 协议、维度与索引空间     |
| `embedding.image` / `vision.chat`       | 图像向量、视觉问答 | 两种不同任务，模型不能互相假定兼容 |
| `knowledge.rerank`                      | 检索重排           | 实际受支持的重排协议               |

端点、凭据、绑定、健康、价格、预算和内容策略构成治理链。保存配置不会自动请求供应商；保存 provider、credential 或 binding 会使相关健康状态失效，需要重新探测。能力目录非空仅表示配置存在，不说明网络、额度、License 和预算均可用。

降级不是任意换模型：要同时满足协议、上下文、输出格式、工具和向量维度要求。流式响应已经输出部分内容后，不应静默重试而拼接出重复答案。embedding 模型更换时，还需处理旧索引与新向量空间，不能只改模型名称。

费用统计需同时记录价格版本、币种、生效区间和供应商 usage 是否可得。缺少 token 统计时不应把成本记为真实零费用；预算、内容策略与审计是否启用，要在目标租户逐项确认。

### 统一大模型网关：真实界面与操作视频

![统一大模型网关真实产品界面：统一大模型网关 / 模型端点](/academy/screens/model-gateway.webp)

图中为已采集的真实产品界面。阅读时重点核对“安全保存凭据”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一大模型网关》完整动态操作课程](/academy/model-gateway) · [下载本模块操作讲义](/academy/model-gateway/guide.md) · [查看真实界面原图](/academy/screens/model-gateway.webp)

```academy-video
model-gateway
```

[开发与配置细则：统一大模型网关](/docs/cube/development#module-model-gateway)

## 18 统一业务编排 {#module-orchestration}

业务编排将查询、条件、转换、模型调用和业务写入组织为明确的执行图，适合重复、结构化、可回归的业务操作。

**技术组成**：输入输出契约、节点与变量映射、条件和数据转换、应用模型操作、调试与测试用例、发布快照、日志和回滚。

**应用示例**：报价转合同：读取已保存报价及明细 → 校验状态 → 转换字段和金额 → 防重创建合同草稿 → 回填来源 → 返回单据标识。

**事务边界**：当前实现对启用原子转换的本地模型链路提供事务、来源锁与防重处理；跨独立数据源及外部 HTTP 调用不应宣称处于同一数据库事务，应设计幂等与补偿。

**集成边界**：编排处理业务步骤，BPM 处理责任审批，Harness 处理目标和任务。模型输出要通过结构校验；调试 Mock 不能进入生产执行；业务日志中的成功还应与实际单据核对。

### 确定性步骤、发布快照与事务边界

业务编排通过输入输出契约、条件、查询、转换、写入与调用节点组织确定的业务操作。它适合报价转合同、审批后回填、主子表转换与接口联动。模型节点可以参与，但结构化结果需要按 Schema 验证后才能流入后续步骤。

当前实现资料描述了主子表读取、条件与字段白名单、转换预览、运行日志、用例、Mock、发布快照和版本回滚等能力。金额、日期、时区、布尔值、零值与显式 null 的处理应按契约验收，不能仅凭节点连线判断正确。

以 AI-CRM 报价转合同为例：读取并锁定已保存报价及明细 → 检查允许状态与防重 → 转换字段和金额 → 新建草稿合同 → 回填来源关联 → 返回目标标识。来源 ID、真实完整明细和审批状态应由服务端读取，不能信任浏览器携带的金额。

本地同事务转换可覆盖目标新增和来源回填；独立数据源和远程 HTTP 不应继承这一原子承诺。跨系统操作需要业务幂等、状态查询、补偿与人工处理。发布快照、调试草稿和生产运行应分开，Mock 仅用于允许的调试测试环境。

验收应同时检查“第一次成功”“重复请求不重复建单”“并发请求”“来源变化”“中途失败回滚”和“远程结果未知”。画布看起来完整不是交付证据，目标单据、来源回填、运行 ID 与错误记录应彼此对应。

### 统一业务编排：真实界面与操作视频

![统一业务编排真实产品界面：统一业务编排真实设计器](/academy/screens/orchestration.webp)

图中为已采集的真实产品界面。阅读时重点核对“编排读取与校验”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一业务编排》完整动态操作课程](/academy/orchestration) · [下载本模块操作讲义](/academy/orchestration/guide.md) · [查看真实界面原图](/academy/screens/orchestration.webp)

```academy-video
orchestration
```

[开发与配置细则：统一业务编排](/docs/cube/development#module-orchestration)

## 19 AI 应用构建 {#module-ai-builder}

AI 应用构建从自然语言需求出发，辅助完成需求拆解、资源规划、表单页面、流程和应用交付。AI 的生成结果应进入原生应用资源和版本体系，再经过开发者审阅及验证。

**技术组成**：需求分析、App Spec 任务图、原生资源创建和回读、设计预览、运行验证、应用版本与交付安装。标准与高级模式分别面向不同开发和运行需求。

**当前工具链**：开发包说明将面向模型的应用交付入口收敛为 `delivery_app_plan` → `delivery_app_get` → `delivery_app_run` → `delivery_app_status`。旧的蓝图工具保留内部修复或历史对账用途，不作为新项目默认教程。

**应用示例**：提出“建立设备维修应用，含报修、派工、维修和验收”。AI 生成资源计划，开发者检查对象与流程，再验证主子表、列表、权限、真实流程实例和目标端安装。

**集成边界**：生成页面、单元测试、应用发布和客户环境上线是不同验收点。高码签名导出、交付与安装还依赖 License、构建环境、签名与安装目标配置，不能承诺任意环境一键完成。

### 从需求到平台可维护资源

AI 应用构建将自然语言需求转换为设计与资源草案，再由设计器、验证与发布流程形成交付物。高质量输入应包含使用角色、业务对象、字段与关系、操作、状态、审批、报表和验收标准，而不是只有一句“做一个 CRM”。

```text
需求说明 → 应用规格与资源计划 → 人工审阅 → 原生资源生成
       → 资源回读与设计器复核 → 真实运行 → 版本与交付验收
```

原生资源回读是关键检查点：表单是否被表单设计器识别，列表与按钮是否引用正确模型，大屏是否采用对应资源定义，菜单是否能在授权角色下打开。单张生成页面不能代表整个应用已经具备数据、权限、流程和打包能力。

标准与高级模式面向不同配置与扩展需求。应用关联、工具、知识、技能及 MCP 绑定影响智能体的可用能力；未配置依赖时应显示明确提示，而不是假设已有默认业务上下文。应用规格、生成资源和运行时之间的差异，应记录并通过回读或对账修复。

发布前还要检查模型、文件、外部服务和数据库等环境依赖。高码构建、独立应用包、插件和平台内原生资源有各自构建契约，应分别验证。AI 提高设计效率的效果应由真实场景测量，不能把演示生成速度当作所有项目的交付周期。

### AI 应用构建：真实界面与操作视频

![AI 应用构建真实产品界面：AI 应用构建工作台](/academy/screens/ai-builder.webp)

图中为已采集的真实产品界面。阅读时重点核对“审阅应用计划”涉及的入口与资源；示例或空态以演示环境为准。

[观看《AI 应用构建》完整动态操作课程](/academy/ai-builder) · [下载本模块操作讲义](/academy/ai-builder/guide.md) · [查看真实界面原图](/academy/screens/ai-builder.webp)

```academy-video
ai-builder
```

[开发与配置细则：AI 应用构建](/docs/cube/development#module-ai-builder)

## 20 业务语义模块 {#module-semantic}

业务语义（本体）为数据、规则和智能体提供共同的业务解释。它描述“对象是什么、字段代表什么、对象如何关联、数据从哪里来、允许做什么”，让不同应用与智能体复用同一业务口径。

```text
业务域 → 实体 / 属性 / 关系 → 资料与数据连接 → 资源映射
                                                   │
业务规则 + 策略与受控动作 ───────────────────────────┤
                                                   ▼
场景配置 → 就绪检查 → 发布版本 → 上下文绑定 → 运行 / 审批 / 回执
```

**核心构成**：业务域、概念实体、属性、关系、外部资源和映射、规则、动作、策略、场景、上下文、版本、运行任务与审计。设计端有操作指引、语义模型、资源映射、场景配置、就绪检查和运行管理等入口。

**应用示例：回款风险分析**。先定义客户、合同、应收和回款对象，再明确净销售额、截止日、币种和逾期规则。把真实数据字段映射到语义属性，限制敏感信息；只读分析输出依据，生成正式报告或触发办理则走受控计划与审批。

**与相邻能力的关系**：知识库回答文档依据，语义模块说明业务含义并关联结构化事实；业务编排执行确定的步骤；智能体在授权上下文中理解任务；流程确定审批责任。语义模型不会自动替代其中任意一项。

**集成边界**：创建实体不等于接通真实数据；草稿、预览、就绪检查与正式发布分别管理；发布后还需绑定到场景或智能体。界面上的启发式建议或模拟校验，不应替代服务端验证和真实数据验收。具体实施见开发手册的[业务语义章节](/docs/cube/development#module-semantic)。

![业务语义从概念到运行的生命周期图](/docs/cube/diagrams/semantic-lifecycle.svg)

### 语义资产、事实与受控动作

| 层次 | 主要对象                     | 解决的问题                           |
| ---- | ---------------------------- | ------------------------------------ |
| 概念 | 业务域、实体、属性与关系     | 客户、合同、回款分别指什么，如何关联 |
| 事实 | 外部资源、字段结构与映射     | 真实数据来自哪里，字段如何转换       |
| 规则 | 条件、缺失事实处理、回归样例 | 什么情况成立、未成立或无法判断       |
| 行为 | 动作、执行器、策略与审批     | 允许谁在什么前提下执行什么操作       |
| 场景 | 上下文、就绪、版本与绑定     | 哪些资产组合形成一个可运行场景       |
| 运行 | 计划、执行、核验与审计       | 实际做了什么，证据在哪，如何追踪     |

业务语义不是把数据库表名换成中文。它需要定义实体粒度、稳定标识、时间口径、单位、关系方向和事实来源。对于“客户风险高吗”，必须明确统计时点、币种、应收状态、逾期天数、退款抵扣与资料权限。

规则缺失事实时应保留 UNKNOWN，而不是按零值或假条件处理。动作定义要有输入 Schema、执行器、风险级别和审批策略；定义被修改后，需要重新检查其审核与发布状态。发布版本和运行绑定分开管理，回滚版本后还要重新检查权限与策略。

当前资料明确：映射推荐属于启发式辅助，部分就绪评分来自前端权重；批量映射发布不是整体事务；关系配置建议不等于真实数据校验。平台不据此承诺完整 OWL/RDFS 推理、跨库自动 JOIN、实体自动消歧或全外部系统依赖识别。这些限制决定了实施人员必须人工确认映射，并在目标系统核验实际运行结果。

### 统一业务语义：真实界面与操作视频

![统一业务语义真实产品界面：业务语义 / 数据映射](/academy/screens/semantic-mapping.webp)

图中为已采集的真实产品界面。阅读时重点核对“接入资源并映射”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一业务语义》完整动态操作课程](/academy/semantic) · [下载本模块操作讲义](/academy/semantic/guide.md) · [查看真实界面原图](/academy/screens/semantic-mapping.webp)

```academy-video
semantic
```

[开发与配置细则：统一业务语义](/docs/cube/development#module-semantic)

## 21 应用贯穿示例

### CRM：报价、合同与回款协同

1. 组织与认证确定销售和审批人的身份，门户按角色提供应用入口。
2. 应用构建维护客户、报价、合同与回款对象，BPM 处理报价审批，统一待办承接办理。
3. 业务编排将满足条件的报价转为合同草稿，核验防重与来源回填。
4. 业务语义统一净销售额、逾期应收与客户风险口径，知识库提供政策依据。
5. 智能体调用授权的只读分析工具，Harness 组织任务；需要通知或写入时按要求确认及审批。
6. 报表展示可核验结果，消息中心发送通知，各领域日志保留运行关联。

验收应包括：正确口径、引用依据、无权访问、重复转换、失败回滚、消息送达、审批前禁止写入、业务回执与单据一致。

### 设备维修：从异常到验收

设备异常记录进入维修应用，按设备、工单、人员和备件建立语义关系。知识助手引用维修手册；流程分派与验收由指定人员办理；编排同步工单状态或调用经授权的外部接口；看板呈现工单进度。IoT 或 MES 报警来源需单独接入、去重及核验，不应以演示数据代替实时采集。

## 22 部署、扩展与验收

平台开发包包含部署与运维工具、数据库、缓存、文件及可选服务。部署应按目标架构核对必需服务、网络、存储、模型能力、License 和组织授权。官网文档只介绍平台集成路径；具体安装参数以随交付版本提供的安装指南为准。

| 验收层面   | 应保留的证据                                   |
| ---------- | ---------------------------------------------- |
| 身份与数据 | 不同角色、租户与数据范围的正反例               |
| 应用资源   | 表单、页面、列表、菜单及已发布版本             |
| 业务流程   | 真实实例、审批意见、最终状态                   |
| 智能能力   | 可用绑定、工具回执、知识引用、无答案与失败场景 |
| 业务语义   | 有效映射、就绪报告、发布版本、上下文与规则样例 |
| 执行与治理 | 计划、审批、运行标识、实际业务数据与审计关联   |
| 交付运维   | 构建产物、安装记录、数据备份、升级与恢复演练   |

性能、并发量、准确率与可用性应通过目标环境测试给出；本文不引用未经本次验证的历史测试数量作为交付结论。

## 23 文档依据与阅读路径

本白皮书核对了门户工作台与路由、Admin/Design 的接口客户端、认证及各领域控制器，并参考开发包内的模型网关指南、智能体配置、业务编排实现、Harness 场景说明、原生资源契约和业务语义功能清单。**本次未执行平台业务写入、客户系统联调或生产环境验收。**

- 新读者：先阅读本白皮书的平台架构与能力全景，再按应用示例选择首个场景。
- 产品使用者：进入[产品学习中心](/academy)，按模块观看中文配音操作图解，并下载讲义练习。
- 实施与开发人员：进入[开发手册](/docs/cube/development)，按组织、应用、流程、知识、语义和智能执行的顺序实施。
- 文档维护人员：代码依据与章节映射保存在官网仓库 `docs/cube-platform-source-map.md`，更新时重新核对接口与能力边界。

## 24 架构决策：五条相互关联的链路

### 身份链与数据链

身份链依次确认用户、租户、角色、应用归属与授权资源；数据链确认来源系统、业务主键、字段含义、版本与新鲜度。两条链在每次业务读取和写入时交汇。模型、智能体、连接器或工作流被授权调用某个工具，不表示其背后的业务数据自动可见。

应用接入应回答四个问题：平台保存的是什么、来源系统负责什么、修改通过哪个边界进行、失败由谁对账。对于现有 ERP/MES，通常先保留原系统的业务权威，通过授权查询或确定接口接入；涉及双向写入时再明确主数据归属与冲突解决方式。

### 控制链与执行链

控制链包含设计、测试、审核、发布、绑定与撤销；执行链包含用户请求、上下文、计划、任务、工具调用和回执。发布是控制链上的一个结果，不能代替运行时再次判权。撤权、来源停用或模型不可用发生后，即使计划已生成，执行仍应按当前状态检查。

| 决策问题               | 优先使用的模块 | 与其他模块的协同                       |
| ---------------------- | -------------- | -------------------------------------- |
| 谁负责审批、能否撤回   | BPM            | 待办承接办理，消息通知，审计保留意见   |
| 固定几步如何转换单据   | 业务编排       | 应用模型、字段映射、流程节点或受控动作 |
| 复杂目标如何拆解和执行 | Harness        | 智能体、能力目录、人工确认、工具回执   |
| 问题需要哪些业务概念   | 业务语义       | 对象与事实映射、规则、场景、绑定       |
| 根据制度如何解释问题   | 知识与智能体   | 授权检索、引用、模型网关               |
| 业务想使用哪种模型能力 | 模型网关       | 供应商、协议、主备、健康、预算与审计   |

### 证据链与责任链

一次“生成合同跟进计划”的请求可能得到文字建议，也可能触发真实任务，两者证据不同。交付应定义内容成果、操作受理、业务终态与审计记录分别由谁核验。建议在验收表中分别记录原请求、计划、运行、工具回执、目标业务 ID 与核验时间。

外部服务超时后可能已经完成业务动作，不能直接推断失败。具备查询接口时先按幂等关联查结果；没有可用查询能力时，保留未知状态并转人工核验。对外部通知、订单或付款类动作，重复执行的业务影响应在上线前明确。

## 25 非功能设计与运行治理

### 可用性与容量规划

容量评估要按工作负载拆分：门户主要是聚合查询，表单是事务读写，知识解析是文件与计算任务，模型调用是外部依赖和长连接，编排与 Harness 涉及任务状态和执行器。不能用一个“在线人数”替代全部容量指标。

| 工作负载       | 建议观测指标                         | 压测与异常样本                         |
| -------------- | ------------------------------------ | -------------------------------------- |
| 门户与列表     | 响应分位数、错误率、慢查询、缓存命中 | 多角色、分页、来源服务超时             |
| 主子表与流程   | 提交延迟、冲突、防重与事务失败       | 重复提交、并发办理、在途变更           |
| 文档解析与检索 | 队列等待、解析失败、召回、索引新鲜度 | 大文件、格式异常、重建与模型变更       |
| 智能对话       | 首段延迟、总耗时、取消、token 与费用 | 限流、流式断开、上下文超长             |
| 编排与任务     | 等待、运行耗时、失败节点、未知结果   | 超时、进程重启、外部已执行而本地无回执 |

具体并发、容量、恢复目标和服务等级应由目标环境测试确定。设计端大型前端构建与 AI 应用构建也需要单独测量内存和构建依赖，不能用运行时资源需求代替构建机资源。

### 安全、隐私与内容治理

安全设计应覆盖身份、租户、资源、动作、文件、外部连接和日志。凭据保存在受控服务端配置，以引用方式提供给连接器或执行器；文档、前端配置、浏览器日志和截图不应承载真实密钥。对外部地址执行应有访问范围与身份约束，不能把任意用户输入 URL 当成可信执行器。

知识资料、提示词和工具返回值可能包含不可信指令。知识检索和模型推理应服从用户目标、权限与系统规则，不把资料内容升级为执行授权。公开链接、导出、附件预览及模型提供方的数据传输也应纳入治理。

### 数据备份、升级与恢复

备份范围不只是数据库，还包含上传附件、License、任务或沙箱中的业务成果、DSH 配置、模型与连接器配置及发布资源。部署说明要求稳定数据目录，升级不应重建或覆盖存量业务库。备份完成必须做可恢复性验证，恢复后重新核对文档与单据关联。

资源版本回滚、数据库恢复、外部系统补偿和权限恢复是不同操作。编排回滚改变活动定义，语义版本回滚不自动恢复历史权限，供应商凭据变更也不会随应用包恢复。运维方案应说明每一类配置的责任人与恢复方法。

## 26 典型业务方案的详细设计

### 采购申请到履约跟踪

以“采购申请审批后形成待执行记录”为首期范围。应用定义申请主子表与采购执行对象；组织确定申请人、部门负责人和采购负责人；流程按金额、类别和部门路由；消息发办理通知；门户承接待办。审批结束后，业务编排读取服务端完整申请，检查状态、防重和明细，再生成待执行记录并回填来源关联。

知识库提供采购制度、附件清单和供应商要求，智能体只解释规则和整理材料；若需生成正式记录或发起办理，转受控动作。业务语义定义采购金额、交期、未履约与供应商风险，看板与智能分析引用相同口径。对接 ERP 采购单是独立集成阶段，必须确认编码、税额、单位、状态、幂等与对账。

阶段验收依次检查：表单与权限 → 审批与任务 → 转换与回填 → 消息 → 看板与知识 → AI 与外部集成。这样可以定位问题属于业务规则、应用配置还是外部依赖。

### 合同审查与应收风险

合同审查先确认待审附件、适用制度、合同版本与用户权限。知识检索给出条款依据，智能体标记风险和不确定性，审查人员作业务决定。只有绑定实际业务动作后，才进入审查意见提交或跟进计划执行。

应收风险则需要结构化事实：合同、应收、回款、截止日、币种、退款与争议状态。业务语义定义逾期与风险规则；Harness 组织分析与报告；需要通知责任人或创建跟进事项时，使用独立动作入口并核验单据编号。分析报告、催收消息和跟进完成不得合并成一个“成功”状态。

### 设备异常到维修闭环

设备、测点、报警、工单、人员和备件分别定义稳定标识。IoT/MES 报警先验证来源与去重，再形成维修申请；流程处理分派和验收，知识库提供维修指导，编排同步业务状态，看板统计响应与关闭情况。智能体不能把相似维修案例直接写成已完成维修。

关闭工单应以现场验收、设备状态和必要附件为依据。报警消失、模型建议生成、消息送达与工单完成是四种不同事实。涉及边缘设备或控制指令时，需额外的执行隔离与人工授权设计。

## 27 建设路线与项目交付

| 阶段       | 建设重点                           | 阶段产物                         | 进入下一阶段的条件                     |
| ---------- | ---------------------------------- | -------------------------------- | -------------------------------------- |
| 业务基线   | 角色、对象、状态、口径与系统边界   | 场景卡、数据字典、责任矩阵       | 业务负责人认可样例与验收结果           |
| 平台底座   | 身份、组织、门户与资源授权         | 可登录、可访问、可追踪的测试环境 | 至少两个业务角色的正反权限通过         |
| 单场景闭环 | 应用、审批、待办、消息与看板       | 可回放的真实测试单据与运行记录   | 正常、拒绝、重复与失败路径通过         |
| 知识与智能 | 知识、语义、智能体、网关与 Harness | 评测集、资产版本、动作与回执     | 有依据回答、越权拒绝、未知结果处理通过 |
| 生产交付   | 配置、构建包、备份、告警与恢复     | 发布清单、操作手册、移交记录     | 目标环境验收和恢复演练通过             |

选型时建议现场演示同一条业务链：从登录、建单、审批到查询结果，再加入知识问答或受控智能任务。仅分别展示多个模块页面，无法验证身份、数据与运行证据是否相互连通。

## 28 术语与常见问题

| 术语       | 本文含义                                                |
| ---------- | ------------------------------------------------------- |
| 原生资源   | 设计器、接口和运行时都能识别并继续维护的平台资源定义    |
| 业务事实   | 由授权业务来源提供、带业务标识与时点的数据              |
| 语义上下文 | 按业务域、场景、版本与权限选择的对象、规则和事实上下文  |
| 就绪检查   | 对依赖与配置的检查结果，不代表业务已执行                |
| 发布快照   | 某次发布时被冻结的定义，运行绑定需明确使用哪一版        |
| 幂等       | 同一业务请求重复到达时，不重复产生业务副作用            |
| 结果未知   | 请求可能已执行，但目前没有足够证据判断最终结果          |
| 回执       | 执行器或业务系统返回的受理/结果标识，仍需按契约判断终态 |

**是否必须先建设全部模块？** 不需要。可以先完成身份、应用和审批闭环，再按实际问题接入知识、语义与智能运行。跨模块的数据与权限约定应先统一，避免后续返工。

**知识库能替代业务语义吗？** 知识库适合资料检索与引用；结构化指标、对象关系、数据映射与可执行业务规则需要额外定义。两者可互相提供依据。

**智能体能直接替代审批流吗？** 智能体可以提出建议或请求执行，但审批责任、有效身份、流程状态与写入授权仍应由业务机制控制。

**模型切换后能否继续沿用原测试结果？** 应根据变更影响重新测试工具调用、结构化输出、知识回答、上下文长度、预算与索引兼容性。模型名称相似不表示能力等价。

**课程视频是否证明功能已在客户现场交付？** 视频展示真实产品 UI 与教学路径；写入、审批、外部发送、后台恢复和集成结果仍需要目标环境业务回执与验收记录。

[继续阅读详细开发手册](/docs/cube/development) · [进入产品学习中心](/academy) · [返回文档中心](/document-center)
