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

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

• 版本：v7
• 更新日期：2026-07-17
• 目标读者：前端 / 架构 / 产品 / 后端
• 阅读时间：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 上下文（布尔或用途集，值域权威见 架构-02 §9）	不等于用户可见，也不等于可导出；前端只展示后端返回的上下文摘要
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 管理后台

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

5.2 用户端

进入作品规划台或知识表单
-> /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