oh-my-muse/design-docs/前端-01-工程结构与核心依赖.md

前端-01：工程结构与核心依赖

• 版本：v7
• 更新日期：2026-06-14
• 目标读者：前端 / 架构 / 产品 / 后端
• 阅读时间：25-40 分钟
• 边界说明：本文件只定义阶段 7 的前端工程基线、管理后台与用户端拆分、路由组织、状态分层和接口边界。写作台交互看 前端-02，元引擎看 前端-03，精确 API 看 后端-05。

1. 前端工程基线

Muse 前端拆为两个项目，不能再用一套 Next.js 应用同时承载管理后台和用户端。

目标仓库	来源 / 形态	定位	技术栈	接口前缀
muse-admin/	fork yudao-ui-admin-vben，主应用路径 apps/web-antd	管理后台(Admin Console)	Vue 3 + Vite + Ant Design Vue + TypeScript	/admin-api/**
muse-studio/	自研用户端	用户端创作产品(User Workspace / Agent Workspace / Knowledge Workspace / Marketplace / Personal Center)	React + Vite + TypeScript	/app-api/**

核心原则：

1. 管理后台只服务管理员治理、配置、审核、观察和运营。
2. 用户端只服务普通用户创作、购买、安装、绑定、发布和个人中心。
3. 两个前端可以共享设计 token、类型生成和接口文档，但不能共享路由、权限模型或后台 layout。
4. 前端只做可见性、交互、状态恢复和用户反馈；权限、事实写入、幂等、审计和状态机必须由后端保证。

阶段 1~6 的硬约束在前端落点：

• 六个产品空间必须保持清楚：管理员控制台、用户工作区、智能体工作台、知识库工作台、市场、个人中心。
• 用户知识库是用户端一级空间，不能被写成作品工作台里的附属抽屉。
• 市场资产包括作品、智能体、知识库；购买、安装或绑定只改变授权和可用性，不自动写入作品事实。
• 作品资产当前 feature gate 默认关闭：用户端只展示阅读、收藏、授权记录或后续能力禁用态，不提供模板化新建、参考来源写入或进入 AI 上下文。
• 输入输出合规、拆分切块、RAG 入库、语义安全围栏、静态检查、权限、审计、Shadow -> Canonical 等保护节点不可被用户替换。
• 前端必须展示或传递来源 lineage、授权快照和来源状态，但不能在本地伪造这些可信结果。
• 前端隐藏菜单、按钮或字段不是安全边界。

2. 管理后台：Vben Admin

管理后台使用：

muse-admin/  # fork yudao-ui-admin-vben
  apps/web-antd/

当前保留模块：

模块	当前定位
system	用户、角色、菜单、权限等平台后台
infra	配置、文件、字典、任务、日志等基础后台
dashboard	后台首页
ai	代码保留，默认隐藏
member	代码保留，默认隐藏
pay	代码保留，默认隐藏
bpm	代码保留，默认隐藏
report	代码保留，默认隐藏
mp	代码保留，默认隐藏

已裁剪后台旧业务域：

• mall
• crm
• erp
• iot
• mes
• 对应页面、API、静态路由、store、工作台快捷入口

注意：mp 保留，不删。

2.1 后续管理后台能力

后台能力	页面方向	后端 owner
内容管理	作品治理列表、章节异常摘要、版本治理摘要、导入导出记录、脱敏元信息、异常内容处理	content
知识管理	全局知识库治理、用户知识库治理摘要、知识来源状态、知识草稿治理摘要、检索配置	knowledge / infra
AI 管理	模型网关绑定引用、可用模型摘要、任务调用归属摘要、Prompt、Agent、生成任务、候选、评测、质量门控、工具授权摘要	ai
市场管理	资产审核、发布申请、授权记录、申诉、治理结果、上下架	market / bpm
账户管理	用户资料、权益、配额、用量、购买/授权/发布记录	account/member/pay
运营配置	字典、配置、文件、任务、日志、菜单权限	system / infra

管理后台不得承载普通用户写作台、候选接受、作品知识取舍或市场购买后的使用流程。

内容管理和知识管理默认只展示治理摘要、异常摘要、脱敏元信息、任务状态、配置和审计记录；不得暗示管理员默认可查看用户私有正文全文、私有版本全文或用户知识库全文。确需查看私有内容时，必须由后续合规访问接口承接，并包含访问理由、时效、分权审批、最小范围和审计记录。

AI 管理只消费 New-API 在 Muse 侧允许展示的网关绑定引用、可用模型摘要和任务调用归属摘要。Provider 配置、路由策略、成本权威口径和原始调用日志仍归 New-API，Muse 管理后台不能把这些写成自身 owner。

2.2 管理后台路由、状态和权限

Vben Admin 的页面入口由后台菜单和权限点驱动。Muse 后续新增管理页面可以挂在 Vben 管理后台的菜单体系下，但只调用 /admin-api/**。

边界	管理后台要求
路由	使用 Vben 路由、菜单、面包屑和权限守卫；不复用 muse-studio 的 React Router 路由
状态	使用 Vben 既有 API 请求、表格、表单、弹窗和菜单状态；不保存用户端作品编辑器状态
权限	使用 system 菜单、按钮、角色、数据范围和高危动作复核；后端仍必须校验业务 owner
API	只访问 /admin-api/**；不从后台页面调用用户端 /app-api/** 完成用户创作决策
数据	默认展示治理摘要、异常摘要、脱敏元信息、配置、任务和审计；不默认读取用户私有正文全文、私有版本全文或用户知识库全文

3. 用户端：muse-studio

muse-studio/ 是普通用户使用的创作产品，不走 Vben。

技术栈：

• React + Vite + TypeScript（SPA，不使用 Next.js；后续文档已全部按纯 React 栈编写）
• Tiptap / ProseMirror：正文编辑、Block 级操作和候选合并
• TanStack Query：服务器状态、轮询、失效刷新
• Zustand 或等价轻量 store：工作台 UI 状态
• React Hook Form + Zod：用户端表单和即时校验

用户端承载：

产品空间	默认入口	主要能力
用户工作区	我的作品	作品列表、单作品工作台、写作、规划、知识、一致性、导入、导出、记录与用量
智能体工作台	智能体列表	用户智能体、已安装智能体、作品槽位替换、试用、发布准备
知识库工作台	我的知识库	资料管理、处理任务状态、知识库版本、发布准备、已安装知识库、作品绑定、安装管理
市场	市场首页	作品、智能体、知识库资产发现、购买、安装、绑定、发布
个人中心	个人资料或用量页	资料、偏好、权益、配额、用量、购买/授权/发布记录

用户端不得暴露系统 Prompt、底层 Pipeline、管理员审计日志、原始密钥、完整模型请求响应或后台配置表。

用户知识库工作台的前端依赖必须闭合到 /app-api/** 的资料、处理任务、版本、发布准备、安装和绑定状态接口。页面至少区分资料上传/引用、解析切块/RAG 入库任务状态、知识库版本与回滚可见状态、发布预检状态、市场安装状态、作品绑定状态和授权快照；前端只展示后端返回的任务与来源状态，不自行推断资料是否已可检索或可发布。

用户端页面文案必须使用产品语言：跳转授权、使用检查、工具权限摘要、运行权限摘要、来源重验、授权记录等。底层会话、检查编号、工具授权和运行权限包等技术名只能出现在管理员审计、调试详情或接口说明中，不能作为普通用户界面的标题、按钮、错误提示或空态说明。

4. 用户端路由建议

muse-studio/
  app/
    (auth)/
      login/
    (user)/
      works/
        page.tsx
        [workId]/
          writing/
          planning/
          knowledge/
          agents/
          import/
          export/
          records/
      agents/
      knowledge-bases/
      marketplace/
      profile/
  components/
    workspace/
    writing-desk/
    planning-desk/
    knowledge/
    agents/
    marketplace/
    personal-center/
    editor/
    common/
  lib/
    api/
    queries/
    mutations/
    store/
    auth/
    permissions/
    types/

约束：

• 登录恢复和应用入口初始化调用 /app-api/muse/me，用于获取当前用户、权益摘要、默认入口和可见产品空间。
• /works 只承载我的作品列表和入口。
• /works/[workId]/* 才承载单作品深层创作流程。
• 智能体、知识库、市场、个人中心是用户端顶级空间，不塞进某个作品工作台内部。
• 作品工作台只展示当前作品关联的智能体、知识库和市场资产使用状态，不承载完整后台配置。
• 作品资产在 feature gate 开启前只出现阅读、收藏、授权记录和不可用原因；模板化、参考来源写入和 AI 上下文绑定入口必须禁用或隐藏，并显示需要后续能力开启。

5. 状态分层

状态类型	管理后台	用户端
服务器事实	Vben API store / table query	TanStack Query
表单状态	Ant Design Vue Form	React Hook Form / local form state
UI 临时态	Vben route/menu/modal state	Zustand / component state
权限可见性	后端菜单和权限点驱动	/app-api/muse/me 权益摘要 + 业务接口结果
待确认内容	管理后台只查看、治理或异常处理	用户端决策：接受、修改后合并、丢弃、确认知识、规划候选确认

正式事实来自后端 Canonical，待确认内容来自 Shadow，历史来自 Archive。前端不能把本地缓存伪造成正式事实。

6. 实时通信策略

用户端使用 SSE（Server-Sent Events）作为实时通信方案，分为两类连接：

6.1 AI 生成 streaming 端点

• 端点：分两步——先 POST /app-api/muse/ai/tasks 创建任务拿到 taskId，再 GET /app-api/muse/ai/tasks/{taskId}/stream 建立 SSE 流（生成提示词等参数走创建任务的请求体，不进 URL）。
• 生命周期：per-request，建流后流式推送，生成完成或失败后连接关闭。
• 用途：AI 正文生成、候选生成等需要流式输出的场景。
• 事件分发：按 SSE event: 行分发，data: 行为该事件 payload JSON。事件类型：chunk（增量文本）、quality_check（质检）、done（结束，payload 含 taskId 与候选 suggestionId）、error（已脱敏错误）。
• 结束信号：服务端发送 event: done，payload 含候选 ID。前端收到后用候选 ID 调用 REST 接口（GET /app-api/muse/suggestions/{suggestionId}）获取完整结构化结果（质量评分、来源标注等元数据）。
• 错误处理：服务端发送 event: error 时，前端展示错误原因并关闭连接。

6.2 统一事件 stream

• 路径：GET /app-api/muse/events
• 生命周期：长连接，用户登录后建立，页面关闭时断开。
• 用途：接收服务端推送的异步事件通知，前端按 event type 分发到对应处理器。

事件类型枚举：

event type	含义	前端处理
candidate.arrived	新候选到达	刷新候选列表，展示新候选提示
task.completed	异步任务成功完成	停止轮询，刷新任务结果
task.failed	异步任务失败	停止轮询，展示失败原因
source.changed	来源状态变化	刷新来源状态，按需禁用操作
knowledge.auto_confirmed	知识自动确认	刷新知识草稿列表

6.3 断线重连策略

• 重连机制：使用 lastEventId 续传。每次收到事件时记录 lastEventId，断线重连时通过 Last-Event-ID header 告知服务端续传位置。
• 服务端保留策略：服务端保留最近 N 分钟事件。重连时如果 lastEventId 仍在保留窗口内，从该位置补发后续事件。
• resync 降级：如果 lastEventId 已过期（超出保留窗口），服务端返回 event: resync。前端收到 resync 后，放弃增量补发，改为 refetch 当前页面所有相关状态（通过 TanStack Query 的 invalidateQueries 批量刷新）。
• 退避策略：重连间隔使用指数退避（1s → 2s → 4s → 8s → 最大 30s），连接成功后重置。

7. 接口边界

• 管理后台只调用 /admin-api/**。
• 用户端只调用 /app-api/**。
• 用户端当前用户入口是 GET /app-api/muse/me，不使用 /app-api/auth/me。
• system/infra 的平台接口按 Yudao 约定保留。
• Muse 新业务接口由后端模块分别提供 admin/app controller。
• 前端类型可以由 OpenAPI 或等价接口契约生成，但接口 owner 是 后端-05。
• 前端禁止绕过接口直接访问数据库、对象存储私有地址、RAGFlow、New-API 或内部模型服务。
• 导出和下载前端必须承接服务端返回的导出清单(included/excluded manifest)：展示已包含内容、已排除内容、排除原因、下载凭证有效期和来源/授权重验状态。下载凭证过期、来源被召回或授权被撤销时，用户端必须重新检查或重新生成，不能继续显示单一“成功下载”态。

8. 权限与导航边界

• Vben 管理后台的菜单、按钮和页面权限来自 system 菜单权限体系。
• muse-studio 的导航可见性来自用户权益、授权、作品权限和业务状态。
• 隐藏菜单不是安全边界；后端必须在 /admin-api/** 和 /app-api/** 同时做认证与业务权限校验。
• 管理员后台可以查看治理摘要、异常摘要、脱敏元信息和审计，不默认读取用户私有正文全文、私有版本全文或用户知识库全文。
• 用户端不允许通过 URL 进入管理后台配置。
• 用户端市场购买、安装、绑定成功后，只刷新授权、安装状态、可用动作和来源授权快照；不会把市场资产内容自动写入作品正文、Local KB 或规划正式事实。

9. 跨空间跳转与 Handoff 前端消费

市场购买、安装或绑定资产后，用户需要从市场空间跳转到目标空间（知识库工作台、智能体工作台或作品工作台）完成绑定或使用。Handoff token 是跨空间跳转的前端传递机制。

9.1 Handoff token 前端生命周期

创建：

• 市场购买/安装成功后，前端调用 POST /app-api/muse/marketplace/handoffs 创建 handoff token。
• 服务端返回 handoffToken、过期时间和目标 owner 消费入口。

传递方式：

• Handoff token 通过 URL query parameter 传递到目标空间页面，例如 /works/[workId]/knowledge?handoffToken=xxx。
• 前端路由守卫在目标页面解析 handoffToken 参数。
• 传递后立即从 URL 中移除 handoffToken（使用 replaceState），避免刷新重复消费。

目标空间消费：

• 知识库绑定：目标页面解析 handoff token 后，调用 POST /app-api/muse/works/{workId}/knowledge-bindings/prechecks 传入 handoff 信息，获取 kbBindPrecheckId，再调用绑定接口完成绑定。
• 智能体槽位替换：目标页面调用 POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/prechecks 传入 handoff 信息，获取 agentSlotPrecheckId，再调用绑定接口完成槽位替换。
• 前端不能自造 precheck，必须由目标 owner 基于 handoff token 生成。

过期/取消处理：

• Handoff token 有短期时效（服务端定义）。
• 过期时前端展示"跳转授权已过期，请返回市场重新操作"，引导用户回到市场空间。
• 用户可主动取消（POST /app-api/muse/marketplace/handoffs/{handoffToken}/cancel）。
• 已消费的 handoff 不可重复使用；重复消费返回 MARKET_HANDOFF_INVALID，前端提示并引导刷新。

9.2 Handoff 状态查询

• 前端可调用 GET /app-api/muse/marketplace/handoffs/{handoffToken} 查询 handoff 当前状态。
• 状态包括：有效、已消费、已过期、已取消。
• 目标页面在消费前应先查询状态，避免对已失效 handoff 发起无效请求。

10. 关联阅读

• 产品定位：产品-01-产品定位与核心价值.md
• 功能总纲：产品-02-核心功能与交互边界.md
• 管理后台规格：产品-02B-管理员控制台功能规格.md
• 用户端规格：产品-02C 至 产品-02G
• 后端工程结构：后端-02-工程结构与模块职责.md
• API 契约：后端-05-统一API契约-v1.md