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

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

• 版本：v4
• 更新日期：2026-05-10
• 目标读者：前端 / 架构 / 产品
• 阅读时间：25-45 分钟
• 边界说明：这里只讲元引擎(Meta Engine)在前端的渲染、可见性和交互分层；本文件描述目标前端形态，不代表当前代码都已实现。元结构定义(MetaSchema)概念引用 架构-02，精确表结构引用 后端-04，精确接口引用 后端-05。

1. 为什么需要元引擎

元引擎(Meta Engine)的目的不是“炫技动态表单”，而是把系统配置、普通用户可见内容和后续生成上下文的边界翻译成稳定 UI。

它要同时服务两类界面：

• 管理员配置界面：管理员(Admin)配置 MetaSchema、字段、可见性、是否进入 AI 上下文和校验规则。
• 普通用户规划界面：普通用户(User)填写作品设定、章节大纲、世界设定、角色关系和文风检查等创作内容。

这两类界面可以复用渲染能力，但不能复用同一套用户语言。管理员可以看到系统术语，普通用户默认只看到创作语言。

2. 管理员配置 MetaSchema

管理员控制台(Admin Console)可以显示系统结构和配置项，包括元结构定义(MetaSchema)、领域(domain)、范围(scope)、目标类型(targetType)和字段控制项。

管理员侧输入至少需要表达：

• MetaSchema 的 domain + scope + targetType 三维分类。
• 字段类型、必填、枚举、引用、排序和校验规则。
• 用户可见性(uiVisible)、是否进入 AI 上下文(aiContext)、用户是否可编辑(userEditable)、用户是否可检索(userSearchable)、是否可导出(exportable)等控制语义。
• 配置版本、启停、回滚或变更记录的展示入口。

前端约束：

• 前端只消费后端已经解析好的目标 MetaSchema，不在前端自行推断 domain、scope 或 targetType。
• 管理员配置界面可以出现 MetaSchema、domain + scope + targetType 等系统词。
• 管理员配置界面不替普通用户填写某个作品的正文、设定或知识确认结果。
• 具体字段名、表结构和接口参数不在本文件定义。

3. 普通用户填写作品规划

普通用户侧的动态表单不是“Schema 表单”，而是作品规划台(Planning Desk)的一部分。前端需要把底层元数据翻译成创作语言。

普通用户默认入口建议收敛为：

普通用户入口	承载内容	AI 辅助方式
作品设定	题材、类型、主题、读者承诺、基调、禁区、结局方向	生成故事前提、补全设定、整理梗概、检查偏题、给多版方向
章节大纲	章节顺序、章节摘要、近期目标、主线、支线、伏笔、情节节拍	生成章节摘要、补齐大纲、整理进度、检查章节目标、建议推进动作
世界设定	角色、地点、物品、组织、规则、事件、时间线、因果链	从正文提取、补全属性、整理时间线、检查冲突、生成关系图
角色关系	角色档案、目标、动机、弱点、秘密、角色弧光、关系变化	生成角色弧线、补全关系、检查章节推进、提示关系停滞
文风检查	作者声音、句式、节奏、叙事视角、张力节奏、风格漂移和质量诊断	分析样本、生成风格说明、整理禁用风格、检查风格偏移、给改写建议

所有规划入口都应支持：

• 用户手写。
• AI 生成。
• AI 补全。
• AI 整理。
• AI 检查。
• AI 给多组选项。
• 从正文提取。
• 绑定后续生成上下文。

普通用户界面不应把 Schema / Pipeline / Agent / Prompt 做成默认导航语言。需要解释系统行为时，使用“创作规则、AI 助手、生成规则、处理记录、AI 候选、待确认知识、已确认设定”等用户语言。

4. 可见性与前端过滤

前端必须按元数据可见性决定普通用户能看到哪些实体、字段和关系。

控制项	前端展示含义
uiVisible	是否展示给普通用户
aiContext	是否允许进入 AI 生成上下文；不等于用户可见
userEditable	普通用户是否可以编辑
userSearchable	普通用户是否可以检索
exportable	是否允许随作品导出

前端约束：

• uiVisible=false 的实体、字段或关系不得出现在普通用户默认 UI 中。
• aiContext=true 只能说明可进入上下文，不代表普通用户可以看见。
• userEditable=false 时，普通用户可以只读查看；是否允许展示仍由 uiVisible 和资源权限共同决定。
• 普通用户可见投影落后或重建失败时，前端应隐藏失效数据或提示稍后重试，不能展示已经被配置隐藏的字段。
• 管理员侧可以看到完整配置；普通用户侧只能看到当前用户和当前作品有权访问且允许展示的投影。

5. 渲染链路

5.1 管理员侧链路

1. 拉取或接收目标 MetaSchema。
2. 保留并展示 domain + scope + targetType 三维分类。
3. 渲染字段、校验规则和可见性控制项。
4. 执行前端即时校验。
5. 提交管理员配置变更。
6. 刷新配置版本或变更结果。

这条链路服务系统配置，不写普通用户作品事实。

5.2 普通用户侧链路

1. 拉取当前作品可见的规划结构和初始值。
2. 按作品设定、章节大纲、世界设定、角色关系、文风检查分组渲染。
3. 根据 uiVisible、userEditable、userSearchable、exportable 控制展示、编辑、检索和导出入口。
4. 用户手写或触发 AI 生成、补全、整理、检查。
5. AI 产出的规划方案先作为 AI 候选或待确认内容展示。
6. 用户确认后，规划项才成为后续生成上下文的一部分。

这条链路服务作品规划，不暴露系统后台配置。

6. 组件分层建议

组件命名可以随实现调整，但职责边界应保持清楚：

• MetaSchemaAdminConsole：管理员元数据配置容器。
• AdminSchemaForm：管理员侧结构与字段配置表单。
• PlanningDeskForm：普通用户作品规划表单容器。
• PlanningSection：作品设定、章节大纲、世界设定、角色关系、文风检查等用户入口。
• DynamicField：字段渲染器，按字段类型选择输入组件。
• AIPlanningActions：生成、补全、整理、检查、给多组选项等动作入口。
• VisibilityGate：按权限和 uiVisible 等元数据控制显示、编辑、检索和导出。

组件复用的底线是“能力复用，不复用错误语言”。同一个字段渲染器可以服务管理员和普通用户，但普通用户界面不显示管理员配置术语。

7. 校验与错误呈现

7.1 校验策略

• 前端做即时可理解的校验：必填、范围、类型、格式和基础依赖。
• 后端做最终事实校验：权限、并发、跨字段规则、来源有效性和是否允许进入规范数据(Canonical)。
• AI 生成、补全、整理、检查失败时，前端应保留用户已输入内容，并说明失败原因和可重试动作。

7.2 错误呈现

• 错误要告诉用户哪里错、为什么错、怎么改。
• 管理员错误可以保留必要系统术语，例如 domain、scope、targetType。
• 普通用户错误要回到创作语言，例如“这个角色关系缺少目标角色”，而不是裸露底层字段名。

8. 章节叙事规划边界

作品规划台可以使用“情节节拍 / 场景推进”这类作者语言，但当前前端文档不引入小说场景(Scene)作为独立一级模型，也不采用 Outline / Scene 作为并列一级导航。

前端应把这类近程叙事控制归入章节大纲、章节叙事规划或章节目标相关界面；如果未来需要独立模型，必须先由架构决策记录(ADR)、后端表结构和接口契约确认，再同步调整前端状态和路由。

9. 关联阅读

• 模型层 MetaSchema 边界：架构-02-核心数据结构与双轨模型.md
• 状态机与元数据可见性约束：架构-04-状态机与约束清单.md
• 产品功能边界：产品-02-核心功能与交互边界.md
• 用户视角流程：流程-01-产品操作流程(用户视角).md
• 统一数据库 Schema：后端-04-统一数据库Schema-v1.md
• 统一 API 契约：后端-05-统一API契约-v1.md