33aad93bef
基于产品/架构/流程/前端/后端五维度并行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解决复杂度、知识确认默认自动+冲突时人工
1025 lines
58 KiB
Markdown
1025 lines
58 KiB
Markdown
# 前端-05：智能体与知识库工作台交互
|
||
|
||
- 版本：v1
|
||
- 更新日期：2026-05-24
|
||
- 目标读者：前端开发者
|
||
- 归属仓库：muse-studio（用户端）
|
||
- 阅读时间：45-65 分钟
|
||
- 边界说明：本文件定义智能体工作台和知识库工作台在 `muse-studio` 中的页面结构、组件交互、状态管理和 API 调用。产品功能规格见 `产品-02D/02E`，API 契约见 `后端-05`，工程结构见 `前端-01`，动态表单见 `前端-03`。
|
||
|
||
## 1. 总体定位
|
||
|
||
智能体工作台和知识库工作台是 `muse-studio` 的两个顶级产品空间，与用户工作区、市场、个人中心平级。
|
||
|
||
核心原则：
|
||
|
||
1. 普通作者不需要先配置智能体或创建知识库即可完成 no-config 创作主路径。
|
||
2. 两个工作台只调用 `/app-api/**`，不调用管理后台接口。
|
||
3. 前端只展示后端返回的状态和可用动作，不自行推断授权、处理状态或兼容性。
|
||
4. 跨空间跳转必须基于服务端 handoff token/session，不能用 URL 参数直接执行高影响动作。
|
||
5. 所有高影响操作（绑定、替换、发布、停用）必须消费服务端预检快照，过期时禁用确认。
|
||
|
||
## 2. 路由结构
|
||
|
||
```text
|
||
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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 顶部：新建智能体按钮（按权限显示） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 页签：我创建的 | 已安装 | 系统默认 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 搜索筛选栏：关键词、来源、形态、能力目标、状态 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 授权异常提示条（有异常时显示） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 智能体卡片列表（分页） │
|
||
│ - 名称、类型、能力目标、版本、状态 │
|
||
│ - 可编辑性、兼容槽位摘要、最近使用 │
|
||
│ - 授权状态标记 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 形态选择：配置型 | 工作流型（按权限灰度） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 能力目标选择：写作 | 分析 | 检测 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 模板选择（可选） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 创建限制提示（配额不足、工作流未开放） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 创建按钮 / 返回列表 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 顶部：智能体名称 / 保存状态 / 操作按钮 │
|
||
├──────────────────────┬──────────────────────────┤
|
||
│ 左侧编辑区 │ 右侧预览/校验区 │
|
||
│ - 基础信息 │ - 输出合同预览 │
|
||
│ - 能力目标 │ - 兼容槽位摘要 │
|
||
│ - 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 顶部：名称 / 保存状态 / 操作按钮 │
|
||
├──────────────────────┬──────────────────────────┤
|
||
│ 左侧工具面板 │ 中央画布 │
|
||
│ - 可用工具列表 │ - 步骤节点（拖拽） │
|
||
│ - 可用子智能体 │ - 连线（输入输出映射） │
|
||
│ - 步骤模板 │ - 条件分支节点 │
|
||
│ │ - 循环节点 │
|
||
│ │ - 错误处理节点 │
|
||
├──────────────────────┼──────────────────────────┤
|
||
│ 右侧属性面板 │ │
|
||
│ - 步骤配置 │ │
|
||
│ - 输入来源 │ │
|
||
│ - 输出去向 │ │
|
||
│ - 超时/失败策略 │ │
|
||
│ - 外发范围说明 │ │
|
||
├──────────────────────┴──────────────────────────┤
|
||
│ 底部：保存 | 校验 | 试用 | 启用版本 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 左侧：测试上下文选择 │
|
||
│ - 手动输入片段 │
|
||
│ - 作品样例选择（有权作品） │
|
||
│ - 授权知识摘要 │
|
||
│ - 模型档位和 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 筛选：能力目标、槽位状态 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 槽位列表 │
|
||
│ - 槽位名称、能力目标 │
|
||
│ - 允许输入/输出摘要 │
|
||
│ - 兼容状态标记（兼容/部分兼容/阻断） │
|
||
│ - 保护节点说明（只读） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 槽位合同详情抽屉 │
|
||
│ - 允许输入类型 │
|
||
│ - 允许输出类型 │
|
||
│ - 允许工具 │
|
||
│ - 失败策略 │
|
||
│ - 不兼容原因（如有） │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 10.2 API 调用
|
||
|
||
| 时机 | API 路径 | 说明 |
|
||
|---|---|---|
|
||
| 页面加载 | `GET /app-api/muse/agents/{agentId}/slot-compatibility` | 兼容槽位列表 |
|
||
| 合同详情 | 详情响应中的槽位合同字段 | 展示合同摘要 |
|
||
|
||
### 10.3 交互规则
|
||
|
||
- 该页面只读，无写操作。
|
||
- 阻断状态：展示具体不兼容原因，引导跳转编辑器修正。
|
||
- 保护节点：只展示说明文字，不提供修改入口。
|
||
|
||
## 11. 作品槽位候选选择与替换（agent-work-slot-selector）
|
||
|
||
### 11.1 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 顶部：作品名 / 槽位名 / 跳转授权状态 / 过期 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 当前绑定：当前智能体名称和版本 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 候选列表 │
|
||
│ - 智能体名称、版本、兼容性 │
|
||
│ - 授权状态、来源 │
|
||
│ - 试用入口 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 预检结果区 │
|
||
│ - 兼容性结论 │
|
||
│ - 阻断原因 │
|
||
│ - 回退策略 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 操作区：确认替换 | 回退系统默认 | 返回作品 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 流程
|
||
|
||
1. 从作品智能体关联页跳转时，URL 携带 `handoffToken` 参数。
|
||
2. 页面加载时立即调用 handoff 消费接口，将 token 交换为 session。
|
||
3. session 存入 Zustand store，后续预检和确认都基于该 session。
|
||
4. session 过期时：禁用确认按钮，展示"授权已过期，请返回作品重新发起"。
|
||
5. 浏览器后退/重复加载：返回同一 session 状态，不扩大动作范围。
|
||
|
||
### 11.4 错误处理
|
||
|
||
- handoff token 过期：展示过期提示，只提供"返回作品"按钮。
|
||
- 预检失败：展示具体原因（输出不合约、授权失效），禁用确认。
|
||
- 替换失败：保持原绑定，展示"事实未改变"和失败原因。
|
||
|
||
## 12. 已安装智能体与授权（agent-installed-library）
|
||
|
||
### 12.1 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 页签：可安装 | 已安装 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 智能体列表 │
|
||
│ - 名称、发布者、许可摘要 │
|
||
│ - 版本、安装状态、到期时间 │
|
||
│ - 可升级标记、下架标记 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 操作：安装 | 停用 | 升级 | 固定版本 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 异常提示（授权失效、已下架） │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 待提交版本选择 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 商品信息表单 │
|
||
│ - 名称、描述、封面/图标 │
|
||
│ - 能力目标、许可范围 │
|
||
│ - 禁止用途、是否可复制 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 权利声明 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 安全检查结果 │
|
||
│ - 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 筛选：时间范围、来源类型、状态、失败类型 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 运行记录列表 │
|
||
│ - 时间、来源（试用/作品调用） │
|
||
│ - 槽位、版本、状态 │
|
||
│ - 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 顶部摘要：可用总数 / 我创建 / 已安装 / 全局 │
|
||
│ 新建知识库按钮（按权限显示） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 页签：我创建的 | 已安装 | 全局授权 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 搜索筛选栏：关键词、来源、类型、处理状态、授权 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 授权异常提示条 / 处理失败提示条 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 知识库卡片列表（分页） │
|
||
│ - 名称、来源类型、所有权 │
|
||
│ - 版本、处理状态、授权状态 │
|
||
│ - 可编辑性、可绑定作品数、最近命中 │
|
||
│ - 风险摘要 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 类型选择：空白创建 | 文件导入 | 模板创建 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 用途选择（可选） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 模板预览（选择模板时展示） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 导入限制说明（文件类型、大小、数量） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 创建配额提示 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 创建按钮 / 返回列表 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 顶部摘要 │
|
||
│ - 名称、来源、所有权、版本 │
|
||
│ - 处理状态、授权状态、发布状态 │
|
||
│ - 风险摘要 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 上传区（拖拽上传） │
|
||
│ - 支持格式说明 │
|
||
│ - 上传进度条 │
|
||
│ - 文件大小限制提示 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 手写条目编辑入口 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 资料列表 │
|
||
│ - 文件名、类型、大小、来源 │
|
||
│ - 扫描状态、处理状态 │
|
||
│ - 可检索/可生成标记 │
|
||
│ - 失败原因（如有） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 处理操作栏 │
|
||
│ - 运行处理检查 | 发起处理 │
|
||
│ - 处理状态入口 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 风险提示（隔离资料、扫描阻断） │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 上传交互
|
||
|
||
1. 拖拽或点击选择文件。
|
||
2. 前端校验文件类型和大小（MIME 白名单、最大单文件大小）。
|
||
3. 上传中展示进度条。
|
||
4. 上传完成后资料进入"待扫描"状态。
|
||
5. 扫描通过后进入"待处理"状态。
|
||
6. 扫描隔离：展示隔离原因，禁用处理和下载。
|
||
|
||
### 18.4 处理状态轮询
|
||
|
||
- 资料上传后自动开始轮询处理状态（`refetchInterval: 5000`）。
|
||
- 状态流转：待扫描 → 扫描中 → 待处理 → 处理中 → 可检索/可生成。
|
||
- 失败时停止轮询，展示失败原因和重试入口。
|
||
- 所有状态使用用户语言展示，不暴露 worker 或底层日志。
|
||
|
||
## 19. 处理状态与失败恢复（knowledge-processing-status）
|
||
|
||
### 19.1 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 任务时间线 │
|
||
│ - 排队 → 扫描 → 清洗 → 解析 → 索引 → 完成 │
|
||
│ - 当前阶段高亮 │
|
||
│ - 失败阶段标红 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 资料分组 │
|
||
│ - 成功资料数量 │
|
||
│ - 失败资料列表 │
|
||
│ - 失败原因和可行动建议 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 操作区 │
|
||
│ - 重试失败任务 │
|
||
│ - 取消可取消任务 │
|
||
│ - 跳转资料管理 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 页签：可安装 | 已安装 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 知识库列表 │
|
||
│ - 名称、发布者、许可摘要 │
|
||
│ - 版本、安装状态、到期时间 │
|
||
│ - 处理状态、可用于检索/生成 │
|
||
│ - 下架标记、可升级标记 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 操作：安装 | 停用 | 升级 | 固定版本 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 异常提示（授权失效、已下架、处理需重验） │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 顶部：知识库名 / 版本 / 跳转授权状态 / 过期 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 作品选择 │
|
||
│ - 可绑定作品列表（有 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 流程
|
||
|
||
1. 从作品知识来源页或知识库详情跳转时，URL 携带 `handoffToken`。
|
||
2. 页面加载时调用预检接口消费 token，获取 handoff session。
|
||
3. session 存入 Zustand store。
|
||
4. 选择作品和用途后执行绑定预检，获取 `kbBindPrecheckId`。
|
||
5. 确认绑定时原子消费 session 和预检快照。
|
||
6. 成功后返回作品知识来源页并刷新绑定。
|
||
|
||
### 21.4 用途开关交互
|
||
|
||
- 默认只开启"检索"和"只读参考"。
|
||
- 开启"生成"或"导出"需要二次确认，展示外发范围。
|
||
- 许可不允许的用途：开关置灰，展示"许可不允许"。
|
||
- 扩大用途必须有有效预检，过期时禁用确认。
|
||
|
||
## 22. 知识库发布准备（knowledge-publish-prep）
|
||
|
||
### 22.1 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 待提交版本 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 商品信息表单 │
|
||
│ - 名称、描述、封面 │
|
||
│ - 资料摘要 │
|
||
│ - 许可范围、禁止用途 │
|
||
│ - 是否可复制、是否可用于生成 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 权利声明 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 发布检查结果 │
|
||
│ - 处理状态检查 │
|
||
│ - 隐私/密钥/版权检查 │
|
||
│ - 阻断项列表 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 操作：保存草稿 | 运行检查 | 提交审核 | 撤回 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 筛选：时间范围、作品、用途、状态 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 绑定列表 │
|
||
│ - 作品名、绑定版本、用途 │
|
||
│ - 最近命中数量 │
|
||
│ - 授权状态 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 命中摘要 │
|
||
│ - 命中章节、用途、冲突摘要 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 用量摘要 │
|
||
│ - 处理用量、生成引用用量 │
|
||
│ - 待归属、异常 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 失败摘要 │
|
||
│ - 失败分类、可行动建议 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 页面结构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 全局知识库列表 │
|
||
│ - 名称、版本、授权范围 │
|
||
│ - 处理状态、可绑定性 │
|
||
│ - 管理员公告 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 授权摘要 │
|
||
│ - 可检索/可生成/可导出 │
|
||
│ - 到期时间、限制 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 操作：查看详情 | 按授权绑定到作品 │
|
||
│ （管理员维护动作跳回管理员控制台） │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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 实现
|
||
|
||
```typescript
|
||
// 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. 市场安装后的槽位替换流程
|
||
|
||
从市场安装智能体后，用户需要手动关联到作品槽位：
|
||
|
||
1. 市场安装完成 → 跳转 `agent-installed-library`。
|
||
2. 用户在已安装列表看到新智能体。
|
||
3. 用户进入作品工作台 → 智能体关联页 → 选择槽位。
|
||
4. 系统生成 handoff token → 跳转 `agent-work-slot-selector`。
|
||
5. 消费 token → 展示候选（包含新安装的智能体）。
|
||
6. 预检 → 确认替换 → 返回作品。
|
||
|
||
关键约束：安装不等于自动关联作品，必须经过槽位预检和用户确认。
|
||
|
||
---
|
||
|
||
## 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` | 市场购买/安装流程、个人中心跳转 |
|
||
|
||
|
||
|