oh-my-muse/design-docs/前端-03-元引擎与动态表单.md

# 前端-03：元引擎与动态表单

- 版本：v6
- 更新日期：2026-05-24
- 目标读者：前端 / 架构 / 产品 / 后端
- 阅读时间：25-45 分钟
- 边界说明：本文件定义 MetaSchema 在两个前端中的使用方式：Vben 管理后台配置元结构，`muse-studio` 用户端消费可见投影并渲染创作表单。元结构定义看 `架构-02`，Schema 看 `后端-04`，API 看 `后端-05`。

## 1. 核心定位

元引擎不是一个单独产品空间，而是把管理员配置、用户可见内容、AI 上下文和导出边界翻译成稳定 UI 的机制。

它服务两类前端：

| 前端 | 使用者 | 目标 |
|---|---|---|
| `muse-admin/` | 管理员 | 配置 MetaSchema、字段、可见性、AI 上下文、导出、校验和版本 |
| `muse-studio/` | 普通用户 | 填写作品设定、章节大纲、世界设定、角色关系、文风检查和知识表单 |

两端可以共享接口类型和字段渲染约定，但不能共享错误的用户语言。管理员可以看到系统术语，普通用户默认只看到创作语言。

接口边界：

- 管理后台只通过 `/admin-api/**` 配置和发布 MetaSchema。
- 用户端只通过 `/app-api/**` 消费当前用户和当前作品可见投影。
- 用户端当前用户入口是 `/app-api/muse/me`，不使用 `/app-api/auth/me`。
- 用户端动态表单只依赖后端 app 侧投影接口；字段可见性、授权、来源状态和用户语言分组都由后端返回，前端不能从管理端原始 MetaSchema、本地缓存或字段名自行推断。
- 用户端动态表单只能调用业务 owner 提供的投影和动作：Planning、Knowledge、Content 等 owner 决定哪些对象可保存、确认、合并或拒绝。MetaSchema 只是渲染、校验和可见性投影，不能成为绕过 owner 决策接口的通用写入层。

## 2. 管理后台 MetaSchema 配置

管理后台归属 Vben Admin。

管理员可配置：

- `domain / scope / targetType`。
- 字段类型、必填、枚举、引用、排序和校验规则。
- `uiVisible`、`aiContext`、`userEditable`、`userSearchable`、`exportable`。
- 版本、启停、回滚、灰度或变更记录。
- 影响预览：哪些用户端表单、知识投影、生成上下文和导出范围会受影响。

约束：

- 管理后台只提交结构配置，不替用户填写作品内容。
- 激活配置必须进入版本化记录。
- 配置变化影响用户端时，用户端看到的是可理解的能力变化或字段变化，不看到后台字段表。
- 关闭字段可见性不能删除历史事实；只影响展示、检索、AI 上下文或导出。
- 管理后台可以配置用户知识库、市场知识库、作品资产和智能体相关结构的展示规则，但购买、安装或绑定资产不等于写入作品事实。
- 作品资产 feature gate 默认关闭；管理后台可以看到配置和影响预览，但用户端只能展示阅读、收藏、授权记录或禁用态，不允许模板化、参考写入或进入 AI 上下文。

## 3. 用户端创作表单

用户端归属 `muse-studio`。

普通用户默认入口：

| 用户入口 | 承载内容 | AI 辅助 |
|---|---|---|
| 作品设定 | 题材、类型、主题、基调、禁区、结局方向 | 生成故事前提、补全设定、整理梗概、检查偏题 |
| 章节大纲 | 章节顺序、摘要、目标、主线、支线、伏笔、情节节拍 | 生成章节摘要、补齐大纲、检查章节目标 |
| 世界设定 | 角色、地点、物品、组织、规则、事件、时间线 | 从正文提取、补全属性、检查冲突 |
| 角色关系 | 角色档案、目标、动机、弱点、秘密、弧光、关系变化 | 生成弧线、补全关系、提示关系停滞 |
| 文风检查 | 作者声音、句式、节奏、视角、风格漂移 | 分析样本、整理禁用风格、检查偏移 |

用户端可以触发 AI 生成、补全、整理、检查和从正文提取，但结果必须先进入 Shadow 候选或 Knowledge Draft。用户确认后才成为后续生成上下文。

用户端动态表单不得暴露系统保护节点配置。开放槽位可以让用户选择可替换智能体或知识库；输入输出合规、拆分切块、RAG 入库、语义安全围栏、静态检查、质量门控、权限、审计和 Shadow -> Canonical 仍由系统固定链路保证。

## 4. 可见性合同

| 控制项 | 管理后台含义 | 用户端含义 |
|---|---|---|
| `uiVisible` | 是否允许展示给普通用户 | false 时用户端默认不展示；也不生成可见空壳 |
| `aiContext` | 是否允许进入 AI 上下文 | 不等于用户可见，也不等于可导出；前端只展示后端返回的上下文摘要 |
| `userEditable` | 普通用户是否可编辑 | false 时只能只读展示或隐藏；不能在前端强开编辑 |
| `userSearchable` | 是否允许普通用户检索 | false 时不进入用户搜索入口、筛选项或联想结果 |
| `exportable` | 是否允许随作品导出 | false 时导出预检必须排除，并显示不可导出原因 |

前端约束：

- 用户端只消费后端 app 侧投影接口返回的可见投影，不自行推断隐藏字段、授权状态或来源状态。
- 管理后台可以看到完整配置，用户端只能看到有权限且允许展示的字段。
- `aiContext=true` 不允许前端把隐藏字段展示给用户。
- `userEditable=false`、`userSearchable=false`、`exportable=false` 都必须同时在 UI 和提交动作上体现；前端禁用只是体验，后端仍要强制校验。
- 投影落后时，用户端必须显示重试/稍后刷新，而不能展示已被隐藏的数据。
- 导出预检必须返回已包含/已排除清单(included/excluded manifest)、字段或来源被排除的原因、下载凭证有效期和重验要求；用户端按该清单展示，不自行拼装可导出范围。

安全边界：

- 前端隐藏字段、禁用控件或移除入口不是安全边界。
- 后端必须在可见投影、保存、检索、AI 上下文组装和导出预检中重复执行权限、来源状态和授权快照校验。
- 前端不能把 `uiVisible=false` 的字段通过搜索、导出、调试面板、错误详情或 AI 上下文摘要泄露出来。
- 来源 lineage 和授权快照由后端生成并随投影返回；前端只能展示、传递和刷新，不能伪造或覆盖。

## 5. 渲染链路

### 5.1 管理后台

```text
加载 MetaSchema 列表
-> 选择 domain/scope/targetType
-> 编辑字段和可见性
-> 前端即时校验
-> /admin-api 提交
-> 后端版本化
-> 展示影响预览和激活结果
```

### 5.2 用户端

```text
进入作品规划台或知识表单
-> /app-api 拉取当前作品可见结构、数据和版本修订
-> 按创作语言分组渲染
-> 用户手写或触发 AI
-> AI 结果进入候选/草稿
-> 用户确认后调用对应 owner action
```

用户确认必须走对应业务入口：规划候选进入规划正式事实，Knowledge Draft 进入 Local KB，正文候选进入正文 Block。规划候选的接受、修改后保存和丢弃必须走 planning owner 的 `/app-api/**` 决策接口，不得复用 AI Suggestion accept，也不得通过动态表单通用保存写入规划正式事实。

前端禁止封装通用动态字段写入 SDK。动态字段没有跨 owner 的通用写接口（参见 `后端-05-统一API契约-v1.md` §4.3 作品和正文中的投影说明）；正式写入必须回到目标 owner 命令路径：规划写 `PUT /app-api/muse/works/{workId}/planning/{sectionKey}`，正文写 `PUT /app-api/muse/blocks/{blockId}`，知识写 Knowledge Draft confirm/ignore 命令，Agent 写 Agent 配置命令。前端只能调用 `/app-api/muse/works/{workId}/dynamic-fields/validate` 做校验和路由建议，不能据此直接写入任何 Canonical fact。

### 5.3 版本兼容和提交合同

后端 app 侧投影接口返回动态表单时，必须带版本与修订信息：

| 字段 | 含义 | 前端用途 |
|---|---|---|
| `schemaVersion` | 当前激活 MetaSchema 结构版本 | 判断字段结构、校验规则和枚举是否仍匹配 |
| `projectionVersion` | 当前用户、作品、授权和来源状态计算后的可见投影版本 | 判断可见性、可编辑状态和来源快照是否仍匹配 |
| `dataRevision` | 当前表单目标对象的数据修订号 | 判断用户编辑期间是否发生并发修改 |

用户端提交 owner 允许的动态字段草稿或普通字段保存时，必须带 `expectedSchemaVersion`、`expectedProjectionVersion` 和 `expectedDataRevision`。后端只能在三者仍匹配且权限、来源状态、授权快照、字段状态都有效时写入；前端不能只靠本地 Zod 校验或禁用控件放行提交。涉及规划候选、Knowledge Draft、正文候选接受或合并的动作，不走通用动态字段保存，必须调用对应 owner action。

| 错误码 | 触发条件 | 前端处理 |
|---|---|---|
| `SCHEMA_STALE` | 激活 MetaSchema 已升级，字段结构或校验规则不再匹配 | 暂存用户未提交输入，重新拉取投影并重渲染表单，提示用户复核变更字段后再提交 |
| `FIELD_DEPRECATED` | 提交包含已废弃、隐藏或不再可编辑字段 | 标记被移除字段，不再把该字段随下一次提交发送；如有用户输入，展示为需人工处理的本地草稿 |
| `PROJECTION_STALE` | 用户权限、授权快照、来源状态或可见性投影已变化 | 重新拉取投影，刷新可见字段和不可用原因；不能继续展示或提交旧投影里的隐藏数据 |
| `DATA_REVISION_CONFLICT` | 目标对象在用户编辑期间被其他操作修改 | 拉取最新数据，展示冲突提示，由用户选择覆盖、合并或放弃本地草稿；具体策略由对应业务 owner 决定 |

这些错误属于动态表单兼容策略，不改变 owner：规划正式事实仍由 planning owner API 决策，知识正式事实仍由 Knowledge Draft 确认入口决策，正文正式事实仍由编辑器 Block 保存或候选接受入口决策。前端只展示 owner 返回的下一步动作，不自行从错误码推断可以覆盖、合并或继续提交。

## 6. 组件边界

Vben 管理后台组件示例：

- `MetaSchemaList`
- `MetaSchemaEditor`
- `MetaFieldTable`
- `VisibilityPolicyPanel`
- `SchemaImpactPreview`

`muse-studio` 用户端组件示例：

- `PlanningDeskForm`
- `PlanningSection`
- `KnowledgeDraftForm`
- `DynamicField`
- `AIPlanningActions`
- `VisibilityGate`

共享只限：

- 类型定义。
- 字段渲染协议。
- 校验消息码。
- 设计 token 或基础 UI 规范。

不共享：

- 管理后台 layout。
- Vben 菜单和 store。
- 管理员系统术语文案。
- 后台配置编辑组件。

用户可见文案映射：

| 技术名 | 用户端产品语言 |
|---|---|
| `handoff session` | 跳转授权 |
| `precheckId` / `publishCheckId` | 使用检查 |
| `Tool Grant` | 工具权限摘要 |
| `Runtime Permission Envelope` | 运行权限摘要 |

这些技术名只能出现在管理员审计、调试详情或接口说明中；普通用户界面不得直接展示。

## 7. 校验和错误

前端即时校验：

- 必填。
- 类型。
- 范围。
- 枚举。
- 基础引用是否选择。

后端最终校验：

- 权限。
- revision。
- 来源状态。
- 授权快照。
- 跨字段业务规则。
- 是否允许进入 Canonical。

用户端错误必须回到创作语言。例如“这个角色关系缺少目标角色”，不要直接暴露 `target_entity_id required`。

## 8. 章节叙事规划边界

用户端可以使用“情节节拍 / 场景推进”作为创作语言，但阶段 7 不新增 Scene 作为独立一级前端模型。近程叙事控制归入章节大纲、章节目标或 Narrative State 展示。

如果未来引入独立 Scene 模型，必须先由架构、后端 Schema/API 和状态机确认，再调整前端路由与状态。

## 9. 关联阅读

- 前端工程结构：`前端-01-工程结构与核心依赖.md`
- 后端 Schema：`后端-04-统一数据库Schema-v1.md`
- 后端 API：`后端-05-统一API契约-v1.md`
- 架构核心模型：`架构-02-核心数据结构与双轨模型.md`
- 状态机：`架构-04-状态机与约束清单.md`