zizi 33aad93bef 提交全维度文档review后的22项架构决策落地

基于产品/架构/流程/前端/后端五维度并行review，澄清并落地22项关键决策：

架构层：Governance按消费者归属拆散、MetaSchema独立模块、
Source传播改为事件驱动自治、去掉Candidate Decision Envelope
和needs_recheck中间状态、Neo4j决策为依赖RAGFlow GraphRAG

后端层：Entitlement统一为可变表+审计日志、API版本策略采用
X-API-Version Header、知识实体唯一键加scope字段

前端层：SSE实时通信（AI stream独立+事件统一）、正文持久化
IndexedDB安全网、Block粒度为场景/小节级

产品层：范围不变UX解决复杂度、知识确认默认自动+冲突时人工

2026-05-24 04:28:52 +08:00

58 KiB

Raw Blame History

前端-05：智能体与知识库工作台交互

版本：v1
更新日期：2026-05-24
目标读者：前端开发者
归属仓库：muse-studio（用户端）
阅读时间：45-65 分钟
边界说明：本文件定义智能体工作台和知识库工作台在 muse-studio 中的页面结构、组件交互、状态管理和 API 调用。产品功能规格见 产品-02D/02E，API 契约见 后端-05，工程结构见 前端-01，动态表单见 前端-03。

1. 总体定位

智能体工作台和知识库工作台是 muse-studio 的两个顶级产品空间，与用户工作区、市场、个人中心平级。

核心原则：

普通作者不需要先配置智能体或创建知识库即可完成 no-config 创作主路径。
两个工作台只调用 /app-api/**，不调用管理后台接口。
前端只展示后端返回的状态和可用动作，不自行推断授权、处理状态或兼容性。
跨空间跳转必须基于服务端 handoff token/session，不能用 URL 参数直接执行高影响动作。
所有高影响操作（绑定、替换、发布、停用）必须消费服务端预检快照，过期时禁用确认。

2. 路由结构

muse-studio/
  app/
    (user)/
      agents/                          # 智能体工作台入口
        page.tsx                        # agent-list 智能体列表
        create/page.tsx                 # agent-create-entry 新建入口
        [agentId]/
          page.tsx                      # agent-detail-version 详情与版本
          edit/page.tsx                 # agent-config-editor 配置型编辑器
          workflow/page.tsx             # agent-workflow-editor 工作流编辑器
          test/page.tsx                 # agent-test-bench 试用与评估
          slots/page.tsx               # agent-slot-compatibility 槽位兼容性
          publish/page.tsx             # agent-publish-prep 发布准备
          records/page.tsx             # agent-records-usage 运行与用量
        installed/page.tsx             # agent-installed-library 已安装与授权
        slot-selector/page.tsx         # agent-work-slot-selector 作品槽位候选选择
      knowledge-bases/                 # 知识库工作台入口
        page.tsx                        # knowledge-list 知识库列表
        create/page.tsx                # knowledge-create-entry 新建入口
        [kbId]/
          page.tsx                      # knowledge-detail-version 详情与版本
          materials/page.tsx           # knowledge-material-manager 资料管理
          processing/page.tsx          # knowledge-processing-status 处理状态
          bind/page.tsx                # knowledge-work-bind-selector 作品绑定选择
          publish/page.tsx             # knowledge-publish-prep 发布准备
          records/page.tsx             # knowledge-records-usage 使用记录
        installed/page.tsx             # knowledge-installed-library 已安装与授权
        global/page.tsx                # global-knowledge-view 全局知识库视图

3. 状态管理策略

3.1 分层原则

状态类型	技术选型	适用场景
服务器事实	TanStack Query	列表、详情、版本、授权、处理状态等后端数据
表单状态	React Hook Form + Zod	创建向导、配置编辑器、发布材料表单
UI 临时态	Zustand / component state	筛选条件、页签、滚动位置、弹窗开关
跨页面上下文	Zustand store	handoff session、预检快照、返回点

3.2 缓存与失效

列表页使用 staleTime: 30s，返回时自动 refetch。
详情页使用 staleTime: 0，每次进入重新拉取。
高影响操作（绑定、替换、停用）成功后，invalidate 相关 query key。
handoff session 和预检快照存入 Zustand，页面卸载或过期时清除。
轮询场景（处理状态、试用运行）使用 TanStack Query 的 refetchInterval，任务终态后停止。

3.3 乐观更新与回滚

列表筛选、排序使用乐观 UI，失败时回滚。
高影响命令（绑定、替换、发布提交）不做乐观更新，等待服务端确认后刷新。
表单保存使用 debounce 自动保存 + 手动保存按钮，冲突时展示本地未保存提示。

4. 通用错误处理

错误码	前端处理
`UNAUTHENTICATED`	跳转登录页
`FORBIDDEN`	展示无权限说明，禁用操作按钮
`RESOURCE_NOT_FOUND`	返回列表页
`STATE_CONFLICT`	刷新对象状态和可用动作
`SOURCE_NEEDS_RECHECK`	展示来源重验入口
`SOURCE_BLOCKED`	禁用确认/绑定/生成，展示原因归因
`PRECHECK_EXPIRED`	清除本地预检快照，引导重新预检
`PRECHECK_REQUIRED`	返回来源空间刷新预检
`REVISION_CONFLICT`	拉取最新数据，展示冲突提示
`FEATURE_DISABLED`	隐藏或禁用对应入口

所有错误展示使用产品语言，不暴露技术术语（如 handoff session、precheckId）。

第一部分：智能体工作台

5. 智能体列表（agent-list）

5.1 页面结构

┌─────────────────────────────────────────────────┐
│ 顶部：新建智能体按钮（按权限显示）              │
├─────────────────────────────────────────────────┤
│ 页签：我创建的 | 已安装 | 系统默认              │
├─────────────────────────────────────────────────┤
│ 搜索筛选栏：关键词、来源、形态、能力目标、状态  │
├─────────────────────────────────────────────────┤
│ 授权异常提示条（有异常时显示）                  │
├─────────────────────────────────────────────────┤
│ 智能体卡片列表（分页）                          │
│   - 名称、类型、能力目标、版本、状态            │
│   - 可编辑性、兼容槽位摘要、最近使用            │
│   - 授权状态标记                                │
└─────────────────────────────────────────────────┘

5.2 API 调用

时机	API 路径	说明
页面加载	`GET /app-api/muse/agents`	智能体列表，带筛选和分页
页签切换	`GET /app-api/muse/agents`	切换 source 参数
授权异常	列表响应中的 `authorizationAlerts` 字段	展示异常数量和处理入口

5.3 交互规则

新建按钮：无创建权限时隐藏；有权限时跳转 agent-create-entry。
卡片点击：跳转 agent-detail-version。
筛选保持：从详情返回时恢复筛选条件和滚动位置（Zustand 持久化）。
空态：无智能体时展示系统默认能力摘要和"去市场安装"入口。
加载失败：保留旧列表数据，展示刷新时间和重试按钮。

5.4 跳转关系

→ agent-create-entry：新建
→ agent-detail-version：卡片点击
→ agent-installed-library：已安装页签
← 作品智能体关联页：完成槽位替换后返回

6. 新建智能体入口（agent-create-entry）

6.1 页面结构

┌─────────────────────────────────────────────────┐
│ 形态选择：配置型 | 工作流型（按权限灰度）       │
├─────────────────────────────────────────────────┤
│ 能力目标选择：写作 | 分析 | 检测                │
├─────────────────────────────────────────────────┤
│ 模板选择（可选）                                │
├─────────────────────────────────────────────────┤
│ 创建限制提示（配额不足、工作流未开放）          │
├─────────────────────────────────────────────────┤
│ 创建按钮 / 返回列表                            │
└─────────────────────────────────────────────────┘

6.2 API 调用

时机	API 路径	说明
页面加载	`GET /app-api/muse/agents/create-options`	查询可创建形态、模板、配额
创建	`POST /app-api/muse/agents`	创建草稿，带幂等键

6.3 交互规则

工作流型未开放时：选项置灰，展示"需要高级权限"说明。
配额不足：禁用创建按钮，展示个人中心权益入口。
创建成功：跳转对应编辑器（配置型 → agent-config-editor，工作流型 → agent-workflow-editor）。
创建失败：不生成草稿，保留用户选择，允许重试。

7. 配置型智能体编辑器（agent-config-editor）

7.1 页面结构

┌─────────────────────────────────────────────────┐
│ 顶部：智能体名称 / 保存状态 / 操作按钮         │
├──────────────────────┬──────────────────────────┤
│ 左侧编辑区          │ 右侧预览/校验区          │
│ - 基础信息           │ - 输出合同预览           │
│ - 能力目标           │ - 兼容槽位摘要           │
│ - Prompt 模板编辑    │ - 校验结果               │
│ - 变量说明           │ - 敏感信息提示           │
│ - 模型档位选择       │                          │
│ - 参数配置           │                          │
│ - 上下文策略         │                          │
├──────────────────────┴──────────────────────────┤
│ 底部：保存草稿 | 校验 | 试用 | 启用版本         │
└─────────────────────────────────────────────────┘

7.2 API 调用

时机	API 路径	说明
页面加载	`GET /app-api/muse/agents/{agentId}`	加载草稿详情
模型选项	详情响应中的模型绑定选项	平台开放模型档位
保存草稿	`POST /app-api/muse/agents/{agentId}/versions/draft`	带幂等键
校验	`POST /app-api/muse/agents/{agentId}/versions/{versionId}/validate`	返回 validationId
启用版本	`POST /app-api/muse/agents/{agentId}/versions/{versionId}/activate`	消费 validationId

7.3 状态管理

表单状态：React Hook Form 管理 Prompt、参数、上下文策略。
自动保存：debounce 3s 后自动调用保存草稿，展示"已保存"/"未保存"状态。
校验快照：校验成功后将 validationId 存入组件 state，过期时清除并要求重新校验。
启用前置：启用按钮仅在 validationId 有效时可点击。

7.4 错误处理

保存失败：保留本地未保存提示，允许重试。
校验失败：定位到具体字段，展示输出不合约、Prompt 注入风险等原因。
启用失败：不改变当前版本，展示影响范围和失败原因。
敏感信息命中：阻断保存或强提示，要求用户移除。

8. 工作流型智能体编辑器（agent-workflow-editor）

8.1 页面结构

┌─────────────────────────────────────────────────┐
│ 顶部：名称 / 保存状态 / 操作按钮               │
├──────────────────────┬──────────────────────────┤
│ 左侧工具面板        │ 中央画布                  │
│ - 可用工具列表       │ - 步骤节点（拖拽）       │
│ - 可用子智能体       │ - 连线（输入输出映射）   │
│ - 步骤模板           │ - 条件分支节点           │
│                      │ - 循环节点               │
│                      │ - 错误处理节点           │
├──────────────────────┼──────────────────────────┤
│ 右侧属性面板        │                          │
│ - 步骤配置           │                          │
│ - 输入来源           │                          │
│ - 输出去向           │                          │
│ - 超时/失败策略      │                          │
│ - 外发范围说明       │                          │
├──────────────────────┴──────────────────────────┤
│ 底部：保存 | 校验 | 试用 | 启用版本             │
└─────────────────────────────────────────────────┘

8.2 API 调用

时机	API 路径	说明
工具目录	`GET /app-api/muse/agents/{agentId}/tools`	授权工具列表
子智能体	详情响应中的可用子智能体选项	可组合子能力
保存	`POST /app-api/muse/agents/{agentId}/versions/workflow-draft`	步骤和工具配置
校验	`POST /app-api/muse/agents/{agentId}/versions/{versionId}/validate`	工作流校验

8.3 交互规则

节点拖拽：从左侧工具面板拖入画布创建步骤节点。
连线：从节点输出端口拖到另一节点输入端口建立数据流。
条件分支：双击条件节点配置分支条件。
循环：支持 for-each 和 while 两种循环模式，必须有终止条件。
工具无权：工具列表中未授权工具置灰，展示"需要授权"说明。
外发提示：使用外发工具时，右侧面板展示外发范围和确认要求。
校验失败：画布中高亮错误节点，右侧展示具体原因（循环无终止、输出不合约等）。

9. 智能体试用与评估（agent-test-bench）

9.1 页面结构

┌─────────────────────────────────────────────────┐
│ 左侧：测试上下文选择                            │
│ - 手动输入片段                                  │
│ - 作品样例选择（有权作品）                      │
│ - 授权知识摘要                                  │
│ - 模型档位和 Token 预估                         │
├─────────────────────────────────────────────────┤
│ 中央：运行控制                                  │
│ - 运行按钮 / 停止按钮                           │
│ - 外发范围提示                                  │
│ - 用量预估                                      │
├─────────────────────────────────────────────────┤
│ 右侧：输出结果                                  │
│ - 任务状态（排队/运行中/成功/失败/超时）        │
│ - 输出文本                                      │
│ - 质量评分和风险标记                            │
│ - 失败原因（权限/授权/合同/超时）               │
│ - 保存为样例按钮                                │
└─────────────────────────────────────────────────┘

9.2 API 调用

时机	API 路径	说明
上下文选项	`GET /app-api/muse/agents/{agentId}/test-context`	可用样例和输入选项
运行试用	`POST /app-api/muse/agents/{agentId}/test`	返回 testRunId
轮询结果	`GET /app-api/muse/jobs/{jobId}`	轮询任务状态
取消	`POST /app-api/muse/jobs/{jobId}/cancel`	取消运行中任务

9.3 状态管理

运行状态：使用 TanStack Query 的 refetchInterval: 2000 轮询，终态后停止。
输出展示：成功时渲染输出文本和质量评分；失败时展示分类原因。
用量提示：运行前展示预估 Token 消耗；运行后展示实际用量。

9.4 关键约束

试用输出没有候选 ID，不能被作品候选接受/合并接口消费。
使用作品样例时必须提示"不会写作品事实，但会产生模型调用和用量"。
市场智能体按许可和信任合同决定是否允许试用。

10. 可替换槽位与兼容性（agent-slot-compatibility）

10.1 页面结构

┌─────────────────────────────────────────────────┐
│ 筛选：能力目标、槽位状态                        │
├─────────────────────────────────────────────────┤
│ 槽位列表                                        │
│ - 槽位名称、能力目标                            │
│ - 允许输入/输出摘要                             │
│ - 兼容状态标记（兼容/部分兼容/阻断）            │
│ - 保护节点说明（只读）                          │
├─────────────────────────────────────────────────┤
│ 槽位合同详情抽屉                                │
│ - 允许输入类型                                  │
│ - 允许输出类型                                  │
│ - 允许工具                                      │
│ - 失败策略                                      │
│ - 不兼容原因（如有）                            │
└─────────────────────────────────────────────────┘

10.2 API 调用

时机	API 路径	说明
页面加载	`GET /app-api/muse/agents/{agentId}/slot-compatibility`	兼容槽位列表
合同详情	详情响应中的槽位合同字段	展示合同摘要

10.3 交互规则

该页面只读，无写操作。
阻断状态：展示具体不兼容原因，引导跳转编辑器修正。
保护节点：只展示说明文字，不提供修改入口。

11. 作品槽位候选选择与替换（agent-work-slot-selector）

11.1 页面结构

┌─────────────────────────────────────────────────┐
│ 顶部：作品名 / 槽位名 / 跳转授权状态 / 过期    │
├─────────────────────────────────────────────────┤
│ 当前绑定：当前智能体名称和版本                  │
├─────────────────────────────────────────────────┤
│ 候选列表                                        │
│ - 智能体名称、版本、兼容性                      │
│ - 授权状态、来源                                │
│ - 试用入口                                      │
├─────────────────────────────────────────────────┤
│ 预检结果区                                      │
│ - 兼容性结论                                    │
│ - 阻断原因                                      │
│ - 回退策略                                      │
├─────────────────────────────────────────────────┤
│ 操作区：确认替换 | 回退系统默认 | 返回作品       │
└─────────────────────────────────────────────────┘

11.2 API 调用

时机	API 路径	说明
落地	`POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/prechecks`	消费 handoff token，获取 session
候选列表	`GET /app-api/muse/works/{workId}/agent-slots`	兼容智能体列表
预检	`POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/prechecks`	返回 precheckId
确认替换	`POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/bind`	消费 session + precheckId
回退默认	`POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/reset`	清除作品级替换

11.3 Handoff 流程

从作品智能体关联页跳转时，URL 携带 handoffToken 参数。
页面加载时立即调用 handoff 消费接口，将 token 交换为 session。
session 存入 Zustand store，后续预检和确认都基于该 session。
session 过期时：禁用确认按钮，展示"授权已过期，请返回作品重新发起"。
浏览器后退/重复加载：返回同一 session 状态，不扩大动作范围。

11.4 错误处理

handoff token 过期：展示过期提示，只提供"返回作品"按钮。
预检失败：展示具体原因（输出不合约、授权失效），禁用确认。
替换失败：保持原绑定，展示"事实未改变"和失败原因。

12. 已安装智能体与授权（agent-installed-library）

12.1 页面结构

┌─────────────────────────────────────────────────┐
│ 页签：可安装 | 已安装                           │
├─────────────────────────────────────────────────┤
│ 智能体列表                                      │
│ - 名称、发布者、许可摘要                        │
│ - 版本、安装状态、到期时间                      │
│ - 可升级标记、下架标记                          │
├─────────────────────────────────────────────────┤
│ 操作：安装 | 停用 | 升级 | 固定版本             │
├─────────────────────────────────────────────────┤
│ 异常提示（授权失效、已下架）                    │
└─────────────────────────────────────────────────┘

12.2 API 调用

时机	API 路径	说明
可安装列表	`GET /app-api/muse/marketplace/assets?assetType=agent`	已授权未安装
已安装列表	`GET /app-api/muse/agents/installed`	已安装智能体
安装	`POST /app-api/muse/marketplace/assets/{assetId}/install`	带许可确认
停用	`POST /app-api/muse/agents/{agentId}/installed/disable`	展示影响作品
升级	`POST /app-api/muse/agents/{agentId}/installed/upgrade`	展示变更和影响

12.3 交互规则

安装前：展示许可、版本、风险等级、可读上下文、工具和外发范围。
停用确认：二次确认弹窗，展示影响哪些作品槽位。
升级确认：展示变更说明和影响作品，已固定绑定不静默变化。
授权失效：保留只读摘要，禁用新增绑定，展示处理路径。

13. 智能体发布准备（agent-publish-prep）

13.1 页面结构

┌─────────────────────────────────────────────────┐
│ 待提交版本选择                                  │
├─────────────────────────────────────────────────┤
│ 商品信息表单                                    │
│ - 名称、描述、封面/图标                         │
│ - 能力目标、许可范围                            │
│ - 禁止用途、是否可复制                          │
├─────────────────────────────────────────────────┤
│ 权利声明                                        │
├─────────────────────────────────────────────────┤
│ 安全检查结果                                    │
│ - Prompt 注入检查                               │
│ - 敏感信息检查                                  │
│ - 兼容槽位摘要                                  │
├─────────────────────────────────────────────────┤
│ 操作：保存草稿 | 运行检查 | 提交审核 | 撤回     │
└─────────────────────────────────────────────────┘

13.2 API 调用

时机	API 路径	说明
加载状态	`GET /app-api/muse/agents/{agentId}/publish-status`	发布准备状态
保存草稿	`POST /app-api/muse/marketplace/publish-drafts`	保存发布材料
运行检查	`POST /app-api/muse/marketplace/publish-drafts/{draftId}/checks`	返回 publishCheckId
提交审核	`POST /app-api/muse/marketplace/publish-requests`	消费 publishCheckId
撤回	`POST /app-api/muse/marketplace/publish-requests/{requestId}/withdraw`	撤回申请

13.3 交互规则

提交按钮：仅在检查通过且 publishCheckId 未过期时可点击。
检查失败：展示阻断项（权利不清、安全阻断），禁用提交。
提交成功：返回详情页，展示"审核中"状态。
重复提交：幂等返回当前申请状态。

14. 智能体运行与用量记录（agent-records-usage）

14.1 页面结构

┌─────────────────────────────────────────────────┐
│ 筛选：时间范围、来源类型、状态、失败类型        │
├─────────────────────────────────────────────────┤
│ 运行记录列表                                    │
│ - 时间、来源（试用/作品调用）                   │
│ - 槽位、版本、状态                              │
│ - Token 摘要、失败原因                          │
├─────────────────────────────────────────────────┤
│ 用量摘要卡片                                    │
│ - 总调用次数、成功率                            │
│ - Token 消耗、待归属                            │
├─────────────────────────────────────────────────┤
│ 详情抽屉（点击记录展开）                        │
│ - 脱敏输入输出摘要                              │
│ - 授权快照摘要                                  │
│ - 失败详情和可行动建议                          │
└─────────────────────────────────────────────────┘

14.2 API 调用

时机	API 路径	说明
记录列表	`GET /app-api/muse/agents/{agentId}/run-records`	带筛选和分页
用量摘要	`GET /app-api/muse/account/usage?dimension=agent`	Token 和调用摘要
失败原因	记录详情中的失败字段	分类和建议

14.3 权限规则

使用者：可看自己的作品调用详情。
发布者：只能看达到最小样本阈值的脱敏聚合，不能看单次运行详情。

第二部分：知识库工作台

15. 知识库列表（knowledge-list）

15.1 页面结构

┌─────────────────────────────────────────────────┐
│ 顶部摘要：可用总数 / 我创建 / 已安装 / 全局     │
│ 新建知识库按钮（按权限显示）                    │
├─────────────────────────────────────────────────┤
│ 页签：我创建的 | 已安装 | 全局授权              │
├─────────────────────────────────────────────────┤
│ 搜索筛选栏：关键词、来源、类型、处理状态、授权  │
├─────────────────────────────────────────────────┤
│ 授权异常提示条 / 处理失败提示条                 │
├─────────────────────────────────────────────────┤
│ 知识库卡片列表（分页）                          │
│ - 名称、来源类型、所有权                        │
│ - 版本、处理状态、授权状态                      │
│ - 可编辑性、可绑定作品数、最近命中              │
│ - 风险摘要                                      │
└─────────────────────────────────────────────────┘

15.2 API 调用

时机	API 路径	说明
页面加载	`GET /app-api/muse/knowledge-bases`	知识库列表，带筛选和分页
已安装	`GET /app-api/muse/installed-knowledge-bases`	已安装知识库
授权异常	列表响应中的 `authorizationAlerts` 字段	异常数量和处理入口

15.3 交互规则

卡片必须让用户一眼区分"我创建 / 已安装 / 全局授权 / 账户可用"。
处理状态使用用户语言展示（"处理中""可检索""可生成"），不暴露 worker 或 Pipeline。
筛选保持：从详情返回时恢复筛选条件和滚动位置。
空态：无知识库时展示全局授权摘要和"创建知识库"/"去市场"入口。
普通作者：新建入口可按权限折叠，不强制展示。

15.4 跳转关系

→ knowledge-create-entry：新建
→ knowledge-detail-version：卡片点击
→ knowledge-installed-library：已安装页签
→ global-knowledge-view：全局页签
← 作品知识来源页：完成绑定后返回

16. 新建知识库入口（knowledge-create-entry）

16.1 页面结构

┌─────────────────────────────────────────────────┐
│ 类型选择：空白创建 | 文件导入 | 模板创建        │
├─────────────────────────────────────────────────┤
│ 用途选择（可选）                                │
├─────────────────────────────────────────────────┤
│ 模板预览（选择模板时展示）                      │
├─────────────────────────────────────────────────┤
│ 导入限制说明（文件类型、大小、数量）            │
├─────────────────────────────────────────────────┤
│ 创建配额提示                                    │
├─────────────────────────────────────────────────┤
│ 创建按钮 / 返回列表                            │
└─────────────────────────────────────────────────┘

16.2 API 调用

时机	API 路径	说明
页面加载	`GET /app-api/muse/knowledge-bases/create-options`	可创建类型、模板、配额
创建	`POST /app-api/muse/knowledge-bases`	创建草稿，带幂等键

16.3 交互规则

页面让用户理解知识库是可复用资料资产，不是作品正式知识，也不是写作前置条件。
全局知识库创建入口只显示"去管理员控制台"（普通用户不可见）。
创建成功：跳转 knowledge-material-manager 进入资料管理。
配额不足：禁用创建，展示个人中心权益入口。

17. 知识库详情与版本（knowledge-detail-version）

17.1 页面结构

┌─────────────────────────────────────────────────┐
│ 顶部摘要                                        │
│ - 名称、来源、所有权、版本                      │
│ - 处理状态、授权状态、发布状态                  │
│ - 风险摘要                                      │
├─────────────────────────────────────────────────┤
│ Tab：资料概览 | 版本历史 | 绑定作品 | 使用摘要  │
├─────────────────────────────────────────────────┤
│ 资料概览 Tab                                    │
│ - 资料数量、处理状态分布                        │
│ - 进入资料管理入口                              │
├─────────────────────────────────────────────────┤
│ 版本历史 Tab                                    │
│ - 版本列表、变更摘要、回退限制                  │
│ - 影响作品数量                                  │
├─────────────────────────────────────────────────┤
│ 操作区                                          │
│ - 编辑资料 | 绑定作品 | 发布准备                │
│ - 复制为个人副本 | 导出                         │
│ - 停用 | 重新启用 | 删除（危险操作）            │
└─────────────────────────────────────────────────┘

17.2 API 调用

时机	API 路径	说明
详情加载	`GET /app-api/muse/knowledge-bases/{kbId}`	基础信息、版本、处理状态
版本历史	详情响应中的版本列表	版本和变更摘要
影响范围	详情响应中的绑定摘要	绑定作品数、安装影响
停用	`POST /app-api/muse/knowledge-bases/{kbId}/disable`	带 commandId
删除	`DELETE /app-api/muse/knowledge-bases/{kbId}`	带 commandId
恢复	`POST /app-api/muse/knowledge-bases/{kbId}/restore`	可取消期内
导出预检	`POST /app-api/muse/knowledge-bases/{kbId}/export-tasks/precheck`	返回导出范围
导出	`POST /app-api/muse/knowledge-bases/{kbId}/export-tasks`	创建导出任务

17.3 交互规则

市场安装知识库：默认只读，不展示不可见资料全文。
停用/删除：二次确认弹窗，展示影响作品、绑定、运行任务和后续生成。
版本回退：展示影响范围，已固定绑定不静默变化。
导出：展示导出范围、脱敏要求和下载有效期。

18. 资料管理与导入（knowledge-material-manager）

18.1 页面结构

┌─────────────────────────────────────────────────┐
│ 上传区（拖拽上传）                              │
│ - 支持格式说明                                  │
│ - 上传进度条                                    │
│ - 文件大小限制提示                              │
├─────────────────────────────────────────────────┤
│ 手写条目编辑入口                                │
├─────────────────────────────────────────────────┤
│ 资料列表                                        │
│ - 文件名、类型、大小、来源                      │
│ - 扫描状态、处理状态                            │
│ - 可检索/可生成标记                             │
│ - 失败原因（如有）                              │
├─────────────────────────────────────────────────┤
│ 处理操作栏                                      │
│ - 运行处理检查 | 发起处理                       │
│ - 处理状态入口                                  │
├─────────────────────────────────────────────────┤
│ 风险提示（隔离资料、扫描阻断）                  │
└─────────────────────────────────────────────────┘

18.2 API 调用

时机	API 路径	说明
资料列表	`GET /app-api/muse/knowledge-bases/{kbId}/documents`	资料和处理状态
上传	`POST /app-api/muse/knowledge-bases/{kbId}/documents`	返回 documentId 和处理任务
删除资料	`DELETE /app-api/muse/knowledge-bases/{kbId}/documents/{documentId}`	带影响确认
处理状态	`GET /app-api/muse/knowledge-bases/{kbId}/processing-tasks/{taskId}`	轮询处理进度
重建索引	`POST /app-api/muse/knowledge-bases/{kbId}/reindex`	返回任务

18.3 上传交互

拖拽或点击选择文件。
前端校验文件类型和大小（MIME 白名单、最大单文件大小）。
上传中展示进度条。
上传完成后资料进入"待扫描"状态。
扫描通过后进入"待处理"状态。
扫描隔离：展示隔离原因，禁用处理和下载。

18.4 处理状态轮询

资料上传后自动开始轮询处理状态（refetchInterval: 5000）。
状态流转：待扫描 → 扫描中 → 待处理 → 处理中 → 可检索/可生成。
失败时停止轮询，展示失败原因和重试入口。
所有状态使用用户语言展示，不暴露 worker 或底层日志。

19. 处理状态与失败恢复（knowledge-processing-status）

19.1 页面结构

┌─────────────────────────────────────────────────┐
│ 任务时间线                                      │
│ - 排队 → 扫描 → 清洗 → 解析 → 索引 → 完成     │
│ - 当前阶段高亮                                  │
│ - 失败阶段标红                                  │
├─────────────────────────────────────────────────┤
│ 资料分组                                        │
│ - 成功资料数量                                  │
│ - 失败资料列表                                  │
│ - 失败原因和可行动建议                          │
├─────────────────────────────────────────────────┤
│ 操作区                                          │
│ - 重试失败任务                                  │
│ - 取消可取消任务                                │
│ - 跳转资料管理                                  │
└─────────────────────────────────────────────────┘

19.2 API 调用

时机	API 路径	说明
任务列表	`GET /app-api/muse/knowledge-bases/{kbId}/processing-tasks/{taskId}`	处理任务状态
重试	`POST /app-api/muse/knowledge-bases/{kbId}/reindex`	重试失败资料
取消	`POST /app-api/muse/jobs/{jobId}/cancel`	取消可取消任务

19.3 交互规则

处理阶段用用户语言表达，不暴露 worker、Pipeline、向量库或底层日志。
失败原因要可行动：例如"删除隔离资料""重新上传""稍后重试"。
取消处理：展示当前知识库是否仍可用于已有绑定。
轮询：处理中状态使用 refetchInterval: 3000，终态后停止。

20. 已安装知识库与授权（knowledge-installed-library）

20.1 页面结构

┌─────────────────────────────────────────────────┐
│ 页签：可安装 | 已安装                           │
├─────────────────────────────────────────────────┤
│ 知识库列表                                      │
│ - 名称、发布者、许可摘要                        │
│ - 版本、安装状态、到期时间                      │
│ - 处理状态、可用于检索/生成                     │
│ - 下架标记、可升级标记                          │
├─────────────────────────────────────────────────┤
│ 操作：安装 | 停用 | 升级 | 固定版本             │
├─────────────────────────────────────────────────┤
│ 异常提示（授权失效、已下架、处理需重验）        │
└─────────────────────────────────────────────────┘

20.2 API 调用

时机	API 路径	说明
可安装	`GET /app-api/muse/marketplace/assets?assetType=knowledge_base`	已授权未安装
已安装	`GET /app-api/muse/installed-knowledge-bases`	已安装知识库
安装	`POST /app-api/muse/marketplace/assets/{assetId}/install`	带许可确认
停用	`POST /app-api/muse/installed-knowledge-bases/{installId}/disable`	展示影响
升级	版本升级接口	展示变更和影响

20.3 交互规则

安装不自动绑定作品；升级不静默改变已固定版本的作品绑定。
安装前展示许可、版本、可读范围、可检索/可生成、外发范围。
停用确认：展示影响哪些作品绑定和是否需要降权或解绑。
授权失效或下架：保留只读摘要，不允许新增绑定。

21. 作品绑定选择与用途（knowledge-work-bind-selector）

21.1 页面结构

┌─────────────────────────────────────────────────┐
│ 顶部：知识库名 / 版本 / 跳转授权状态 / 过期    │
├─────────────────────────────────────────────────┤
│ 作品选择                                        │
│ - 可绑定作品列表（有 source_manage 权限）       │
│ - 现有绑定状态                                  │
├─────────────────────────────────────────────────┤
│ 用途开关                                        │
│ - 检索 | 生成 | 检查 | 导出 | 只读参考          │
│ - 外发范围说明                                  │
│ - 冲突策略                                      │
├─────────────────────────────────────────────────┤
│ 预检结果区                                      │
│ - 许可范围、处理状态                            │
│ - 阻断原因                                      │
│ - 过期时间                                      │
├─────────────────────────────────────────────────┤
│ 操作：确认绑定 | 解绑 | 调整用途 | 返回         │
└─────────────────────────────────────────────────┘

21.2 API 调用

时机	API 路径	说明
落地	`POST /app-api/muse/works/{workId}/knowledge-bindings/prechecks`	消费 handoff token
可绑定作品	预检响应中的可绑定作品	有 source_manage 的作品
预检	`POST /app-api/muse/works/{workId}/knowledge-bindings/prechecks`	返回 kbBindPrecheckId
绑定	`POST /app-api/muse/works/{workId}/knowledge-bindings`	消费 session + precheckId
解绑	`DELETE /app-api/muse/works/{workId}/knowledge-bindings/{bindingId}`	展示影响
调整用途	`PATCH` 绑定用途接口	扩大用途需确认

21.3 Handoff 流程

从作品知识来源页或知识库详情跳转时，URL 携带 handoffToken。
页面加载时调用预检接口消费 token，获取 handoff session。
session 存入 Zustand store。
选择作品和用途后执行绑定预检，获取 kbBindPrecheckId。
确认绑定时原子消费 session 和预检快照。
成功后返回作品知识来源页并刷新绑定。

21.4 用途开关交互

默认只开启"检索"和"只读参考"。
开启"生成"或"导出"需要二次确认，展示外发范围。
许可不允许的用途：开关置灰，展示"许可不允许"。
扩大用途必须有有效预检，过期时禁用确认。

22. 知识库发布准备（knowledge-publish-prep）

22.1 页面结构

┌─────────────────────────────────────────────────┐
│ 待提交版本                                      │
├─────────────────────────────────────────────────┤
│ 商品信息表单                                    │
│ - 名称、描述、封面                              │
│ - 资料摘要                                      │
│ - 许可范围、禁止用途                            │
│ - 是否可复制、是否可用于生成                    │
├─────────────────────────────────────────────────┤
│ 权利声明                                        │
├─────────────────────────────────────────────────┤
│ 发布检查结果                                    │
│ - 处理状态检查                                  │
│ - 隐私/密钥/版权检查                            │
│ - 阻断项列表                                    │
├─────────────────────────────────────────────────┤
│ 操作：保存草稿 | 运行检查 | 提交审核 | 撤回     │
└─────────────────────────────────────────────────┘

22.2 API 调用

时机	API 路径	说明
加载状态	`GET /app-api/muse/knowledge-bases/{kbId}/publish-status`	发布准备状态
保存草稿	`POST /app-api/muse/marketplace/publish-drafts`	保存发布材料
运行检查	`POST /app-api/muse/knowledge-bases/{kbId}/publish-prechecks`	返回 kbPublishCheckId
生成快照	`POST /app-api/muse/knowledge-bases/{kbId}/publish-snapshots`	固化版本和来源
提交审核	`POST /app-api/muse/knowledge-bases/{kbId}/publish-requests`	消费检查和快照
撤回	`POST /app-api/muse/marketplace/publish-requests/{requestId}/withdraw`	撤回申请

22.3 交互规则

非自有、全局、局域、市场安装资产默认不可提交。
检查过期或资料变化时要求重新检查。
提交成功后返回详情，展示"审核中"。
页面只做发布准备和提交，不处理市场审核结论。

23. 知识库使用与命中记录（knowledge-records-usage）

23.1 页面结构

┌─────────────────────────────────────────────────┐
│ 筛选：时间范围、作品、用途、状态                │
├─────────────────────────────────────────────────┤
│ 绑定列表                                        │
│ - 作品名、绑定版本、用途                        │
│ - 最近命中数量                                  │
│ - 授权状态                                      │
├─────────────────────────────────────────────────┤
│ 命中摘要                                        │
│ - 命中章节、用途、冲突摘要                      │
├─────────────────────────────────────────────────┤
│ 用量摘要                                        │
│ - 处理用量、生成引用用量                        │
│ - 待归属、异常                                  │
├─────────────────────────────────────────────────┤
│ 失败摘要                                        │
│ - 失败分类、可行动建议                          │
└─────────────────────────────────────────────────┘

23.2 API 调用

时机	API 路径	说明
使用记录	`GET /app-api/muse/knowledge-bases/{kbId}/usage-records`	绑定和命中
用量摘要	`GET /app-api/muse/account/usage?dimension=knowledge`	处理和生成用量

23.3 权限规则

使用者：可看自己的作品绑定和命中。
发布者：只能看达到最小样本阈值的脱敏聚合（同一时间桶不少于 10 个使用者且不少于 3 个作品来源），未达阈值隐藏或合并维度。
不展示他人作品正文、检索片段或生成输入输出。

24. 全局知识库视图（global-knowledge-view）

24.1 页面结构

┌─────────────────────────────────────────────────┐
│ 全局知识库列表                                  │
│ - 名称、版本、授权范围                          │
│ - 处理状态、可绑定性                            │
│ - 管理员公告                                    │
├─────────────────────────────────────────────────┤
│ 授权摘要                                        │
│ - 可检索/可生成/可导出                          │
│ - 到期时间、限制                                │
├─────────────────────────────────────────────────┤
│ 操作：查看详情 | 按授权绑定到作品               │
│ （管理员维护动作跳回管理员控制台）              │
└─────────────────────────────────────────────────┘

24.2 API 调用

时机	API 路径	说明
列表	`GET /app-api/muse/knowledge-bases?scope=global`	全局知识库可见列表
详情	`GET /app-api/muse/knowledge-bases/{kbId}`	全局知识库详情

24.3 交互规则

普通用户只读；创建、导入、维护、停用和授权策略回到管理员控制台。
按授权绑定：跳转 knowledge-work-bind-selector，走标准绑定流程。
授权不可用时：展示原因，禁用绑定入口。

第三部分：跨空间跳转与市场关系

25. 跨空间跳转设计

25.1 智能体工作台跳转矩阵

来源	目标	触发	handoff 内容	完成后
作品智能体关联页	agent-work-slot-selector	选择槽位替换	作品、槽位、当前智能体、授权	返回作品刷新槽位
写作台候选面板	agent-detail-version	查看智能体详情	只读返回点	返回写作台
agent-work-slot-selector	agent-test-bench	试用候选	候选智能体、槽位合同	返回候选选择
agent-detail-version	agent-publish-prep	发布准备	版本、所有者	返回详情
市场获取完成	agent-installed-library	安装	资产、许可、版本	安装后回市场或作品

25.2 知识库工作台跳转矩阵

来源	目标	触发	handoff 内容	完成后
作品知识来源页	knowledge-work-bind-selector	绑定知识库	作品、当前来源、用途	返回作品刷新绑定
写作台候选面板	knowledge-detail-version	查看来源详情	只读返回点	返回写作台
knowledge-detail-version	knowledge-work-bind-selector	绑定到作品	知识库、版本、授权	返回详情或作品
knowledge-detail-version	knowledge-publish-prep	发布准备	版本、所有者	返回详情
市场获取完成	knowledge-installed-library	安装	资产、许可、版本	安装后回市场或作品

25.3 前端 Handoff 实现

// Zustand store 定义
interface HandoffStore {
  // 当前 handoff session
  session: HandoffSession | null;
  // 预检快照
  precheckId: string | null;
  precheckExpiry: number | null;
  // 返回点
  returnUrl: string | null;

  // 动作
  consumeToken: (token: string) => Promise<void>;
  clearSession: () => void;
  setPrecheckId: (id: string, expiry: number) => void;
  isSessionValid: () => boolean;
  isPrecheckValid: () => boolean;
}

规则：

handoff token 从 URL searchParams 获取，消费后从 URL 移除。
session 过期检查：每次操作前校验 session.expiresAt > Date.now()。
页面卸载时不清除 session（支持浏览器后退恢复）。
并发打开同一 handoff：返回同一 session 状态，不扩大范围。

26. 市场安装后的槽位替换流程

从市场安装智能体后，用户需要手动关联到作品槽位：

市场安装完成 → 跳转 agent-installed-library。
用户在已安装列表看到新智能体。
用户进入作品工作台 → 智能体关联页 → 选择槽位。
系统生成 handoff token → 跳转 agent-work-slot-selector。
消费 token → 展示候选（包含新安装的智能体）。
预检 → 确认替换 → 返回作品。

关键约束：安装不等于自动关联作品，必须经过槽位预检和用户确认。

27. 关联阅读

文档	关联内容
`产品-02D-智能体工作台功能规格.md`	智能体工作台完整产品定义、页面规格、操作规格
`产品-02E-知识库工作台功能规格.md`	知识库工作台完整产品定义、页面规格、操作规格
`后端-05-统一API契约-v1.md`	API 路径、请求响应格式、错误码、幂等规则
`架构-01-系统全貌与边界上下文.md`	BC 边界、权威归属、跨上下文协作
`架构-02-核心数据结构与双轨模型.md`	双轨模型、Shadow/Canonical 边界
`前端-01-工程结构与核心依赖.md`	工程结构、路由约定、状态分层、技术栈
`前端-02-写作台与候选交互.md`	作品工作台交互，候选接受/合并流程
`前端-03-元引擎与动态表单.md`	MetaSchema 投影消费、动态表单渲染
`前端-04-市场与个人中心交互.md`	市场购买/安装流程、个人中心跳转

58 KiB Raw Blame History Unescape Escape

前端-05：智能体与知识库工作台交互

1. 总体定位

2. 路由结构

3. 状态管理策略

3.1 分层原则

3.2 缓存与失效

3.3 乐观更新与回滚

4. 通用错误处理

第一部分：智能体工作台

5. 智能体列表（agent-list）

5.1 页面结构

5.2 API 调用

5.3 交互规则

5.4 跳转关系

6. 新建智能体入口（agent-create-entry）

6.1 页面结构

6.2 API 调用

6.3 交互规则

7. 配置型智能体编辑器（agent-config-editor）

7.1 页面结构

7.2 API 调用

7.3 状态管理

7.4 错误处理

8. 工作流型智能体编辑器（agent-workflow-editor）

8.1 页面结构

8.2 API 调用

8.3 交互规则

9. 智能体试用与评估（agent-test-bench）

9.1 页面结构

9.2 API 调用

9.3 状态管理

9.4 关键约束

10. 可替换槽位与兼容性（agent-slot-compatibility）

10.1 页面结构

10.2 API 调用

10.3 交互规则

11. 作品槽位候选选择与替换（agent-work-slot-selector）

11.1 页面结构

11.2 API 调用

11.3 Handoff 流程

11.4 错误处理

12. 已安装智能体与授权（agent-installed-library）

12.1 页面结构

12.2 API 调用

12.3 交互规则

13. 智能体发布准备（agent-publish-prep）

13.1 页面结构

13.2 API 调用

13.3 交互规则

14. 智能体运行与用量记录（agent-records-usage）

14.1 页面结构

14.2 API 调用

14.3 权限规则

第二部分：知识库工作台

15. 知识库列表（knowledge-list）

15.1 页面结构

15.2 API 调用

15.3 交互规则

15.4 跳转关系

16. 新建知识库入口（knowledge-create-entry）

16.1 页面结构

16.2 API 调用

16.3 交互规则

17. 知识库详情与版本（knowledge-detail-version）

17.1 页面结构

17.2 API 调用

17.3 交互规则

18. 资料管理与导入（knowledge-material-manager）

18.1 页面结构

18.2 API 调用

18.3 上传交互

18.4 处理状态轮询

19. 处理状态与失败恢复（knowledge-processing-status）

19.1 页面结构

19.2 API 调用

19.3 交互规则

20. 已安装知识库与授权（knowledge-installed-library）

20.1 页面结构

20.2 API 调用

58 KiB

Raw Blame History