refactor(docs): update terminology and enhance shared space documentation
- Changed references from "工作空间" to "共享空间" for consistency and clarity. - Expanded the documentation to include details on shared agents and their management within shared spaces. - Updated sections to reflect the new structure and rules regarding knowledge base and agent sharing, including permissions and user roles. - Improved overall readability and organization of the document to facilitate better understanding of shared space functionalities. This update enhances the documentation by ensuring accurate terminology and providing comprehensive guidelines on shared space features.
This commit is contained in:
+84
-38
@@ -1,38 +1,39 @@
|
||||
# 工作空间(共享空间)说明文档
|
||||
# 共享空间说明文档
|
||||
|
||||
本文档说明 WeKnora 中的**工作空间**(产品中又称「共享空间」)功能,包括空间创建与加入、成员角色与权限、知识库共享规则,以及用户对知识库的最终访问权限计算方式。
|
||||
本文档说明 WeKnora 中的**共享空间**功能,包括空间创建与加入、成员角色与权限、知识库与智能体共享规则、智能体停用机制,以及用户对知识库的最终访问权限计算方式。
|
||||
|
||||
---
|
||||
|
||||
## 一、工作空间概述
|
||||
## 一、共享空间概述
|
||||
|
||||
### 1.1 什么是工作空间
|
||||
### 1.1 什么是共享空间
|
||||
|
||||
工作空间(Organization)是跨租户协作的载体。用户可以在同一系统内属于不同租户(账户),通过**加入同一工作空间**,实现:
|
||||
共享空间是跨租户协作的载体。用户可以在同一系统内属于不同租户(账户),通过**加入同一共享空间**,实现:
|
||||
|
||||
- 共享知识库:将本租户的知识库共享到空间,供空间内其他成员使用;
|
||||
- 共享智能体:将本租户的智能体共享到空间,供空间内其他成员在对话等场景中使用;
|
||||
- 访问他人共享的知识库:在「知识库列表」中看到并打开通过空间共享给自己的知识库;
|
||||
- 在对话、智能体等场景中选择并使用这些共享知识库。
|
||||
- 在对话、智能体等场景中选择并使用这些共享知识库与共享智能体。
|
||||
|
||||
数据与权限关系简要如下:
|
||||
|
||||
- **租户**:知识库的归属单位,每个知识库属于一个租户;
|
||||
- **工作空间**:不拥有知识库,只记录「某知识库被共享到某空间」以及「共享时的权限」;
|
||||
- **租户**:知识库、智能体的归属单位,每个知识库/智能体属于一个租户;
|
||||
- **共享空间**:不拥有知识库或智能体,只记录「某知识库/智能体被共享到某空间」以及「共享时的权限」;
|
||||
- **成员**:用户通过邀请码或管理员邀请加入空间,在空间内拥有一个角色(管理员 / 编辑者 / 只读)。
|
||||
|
||||
### 1.2 核心概念对照
|
||||
|
||||
| 概念 | 说明 |
|
||||
|------|------|
|
||||
| 工作空间 / 共享空间 | 同一产品中的「组织」(Organization),用于跨租户共享知识库 |
|
||||
| 共享空间 | 系统中的「组织」(Organization),用于跨租户共享知识库与智能体 |
|
||||
| 空间创建者 | 创建该空间的用户,自动成为该空间的管理员,且不可被移除或降级 |
|
||||
| 空间成员 | 通过邀请码加入或由管理员邀请加入的用户,拥有管理员、编辑者或只读之一角色 |
|
||||
| 知识库归属 | 知识库始终属于一个租户;共享到空间不改变归属,只建立「空间 ↔ 知识库」的共享关系 |
|
||||
| 共享关系 | 一条记录表示:某知识库以某种权限(只读/可写)被共享到某工作空间 |
|
||||
| 知识库/智能体归属 | 知识库、智能体始终属于一个租户;共享到空间不改变归属,只建立「空间 ↔ 知识库/智能体」的共享关系 |
|
||||
| 共享关系 | 一条记录表示:某知识库以某种权限(只读/可写)被共享到某共享空间;或某智能体以只读方式被共享到某共享空间 |
|
||||
|
||||
---
|
||||
|
||||
## 二、工作空间的创建、加入与离开
|
||||
## 二、共享空间的创建、加入与离开
|
||||
|
||||
### 2.1 创建空间
|
||||
|
||||
@@ -83,7 +84,7 @@
|
||||
|
||||
## 三、空间内角色与权限
|
||||
|
||||
工作空间内共有三种角色,权限从高到低为:**管理员 > 编辑者 > 只读**。
|
||||
共享空间内共有三种角色,权限从高到低为:**管理员 > 编辑者 > 只读**。
|
||||
|
||||
### 3.1 角色定义
|
||||
|
||||
@@ -121,8 +122,8 @@
|
||||
|
||||
### 4.1 谁可以发起共享
|
||||
|
||||
- 只有**知识库所属租户下的用户**(即「拥有」该知识库的账户下的用户)才能将该知识库共享到某个工作空间。
|
||||
- 同时,该用户必须是目标工作空间的**成员**,且角色为**管理员**或**编辑者**。
|
||||
- 只有**知识库所属租户下的用户**(即「拥有」该知识库的账户下的用户)才能将该知识库共享到某个共享空间。
|
||||
- 同时,该用户必须是目标共享空间的**成员**,且角色为**管理员**或**编辑者**。
|
||||
即:**只读成员不能把任何知识库(包括自己的)共享到该空间。**
|
||||
|
||||
### 4.2 共享时的权限设置
|
||||
@@ -132,7 +133,7 @@
|
||||
- **只读(viewer)**:空间成员在该知识库上最多只读(实际权限还会受成员在空间内的角色限制,见下)。
|
||||
- **可写(editor)**:空间成员在该知识库上可被赋予编辑能力(同样受成员角色限制)。
|
||||
|
||||
同一知识库可以共享到多个工作空间,且每个空间可以设置不同的共享权限(例如空间 A 只读、空间 B 可写)。
|
||||
同一知识库可以共享到多个共享空间,且每个空间可以设置不同的共享权限(例如空间 A 只读、空间 B 可写)。
|
||||
|
||||
### 4.3 更新与取消共享
|
||||
|
||||
@@ -143,26 +144,68 @@
|
||||
|
||||
### 4.4 同一知识库共享到多个空间
|
||||
|
||||
- 允许将同一知识库共享到多个工作空间。
|
||||
- 允许将同一知识库共享到多个共享空间。
|
||||
- 每个空间一条共享记录,各自独立配置权限(只读/可写)。
|
||||
- 例如:知识库 K 共享到空间 A(只读)、空间 B(可写),互不影响。
|
||||
|
||||
---
|
||||
|
||||
## 五、用户对知识库的最终访问权限
|
||||
## 五、智能体共享规则
|
||||
|
||||
智能体也可通过共享空间在成员间共享,供成员在对话等场景中选择使用。规则与知识库共享类似,但权限仅支持只读。
|
||||
|
||||
### 5.1 谁可以发起智能体共享
|
||||
|
||||
- 只有**智能体所属租户下的用户**才能将该智能体共享到某个共享空间。
|
||||
- 同时,该用户必须是目标共享空间的**成员**,且角色为**管理员**或**编辑者**(与知识库共享一致)。
|
||||
- 智能体须已配置完成(如已选模型、若使用知识库则已选 rerank 模型等)方可共享。
|
||||
|
||||
### 5.2 共享时的权限
|
||||
|
||||
- 智能体共享到空间时**仅支持只读**:空间成员只能以「使用」方式使用该智能体(如在对话中选择),不能编辑该智能体的配置或删除共享关系以外的管理操作。
|
||||
- 同一智能体可以共享到多个共享空间。
|
||||
|
||||
### 5.3 更新与取消共享
|
||||
|
||||
- **取消某条智能体共享**:
|
||||
- **发起该次共享的用户**可随时取消;
|
||||
- 目标空间的**管理员**也可取消该空间下的任意智能体共享(包括他人发起的)。
|
||||
|
||||
---
|
||||
|
||||
## 六、智能体停用机制
|
||||
|
||||
「停用」是当前租户对**通过共享空间获得的智能体**的一种个人偏好设置,仅影响本租户在**对话中选择智能体**时的展示与使用体验,不改变共享关系,也不影响其他成员。
|
||||
|
||||
### 6.1 停用的含义
|
||||
|
||||
- 当某租户将某个「通过共享空间获得的智能体」标记为**已停用**时:
|
||||
- 在该租户的对话界面中,该智能体可在下拉列表中被隐藏或标记为已停用,减少干扰;
|
||||
- 该智能体仍对该共享空间的其他成员可见、可用;
|
||||
- 共享关系不变,发起共享的用户与空间管理员仍可照常管理该条共享。
|
||||
- 停用状态按「租户 + 智能体(含来源租户)」记录,即:同一智能体被多个空间共享时,用户停用后在所有入口对该智能体的展示偏好一致。
|
||||
|
||||
### 6.2 停用与恢复
|
||||
|
||||
- 用户可随时将已停用的共享智能体**恢复**,恢复后该智能体重新在对话下拉等列表中正常显示。
|
||||
- 停用/恢复仅影响当前租户自己的视图与选择列表,不影响他人,也不影响该用户通过直接链接等方式访问该智能体。
|
||||
|
||||
---
|
||||
|
||||
## 七、用户对知识库的最终访问权限
|
||||
|
||||
用户对某个知识库的访问可能来自两种途径,最终权限取「最宽」的一种。
|
||||
|
||||
### 5.1 两种访问来源
|
||||
### 7.1 两种访问来源
|
||||
|
||||
1. **本租户拥有**
|
||||
知识库属于用户当前所在租户 → 用户对该知识库拥有**完整权限**(创建者/管理端意义上的「所有者」权限:可编辑、管理设置、删除知识库等),无需也不依赖工作空间。
|
||||
2. **通过工作空间共享获得**
|
||||
知识库不属于当前租户,但被共享到了用户所在的至少一个工作空间 → 用户通过「成员身份 + 共享设置」得到**受限权限**(见下)。
|
||||
知识库属于用户当前所在租户 → 用户对该知识库拥有**完整权限**(创建者/管理端意义上的「所有者」权限:可编辑、管理设置、删除知识库等),无需也不依赖共享空间。
|
||||
2. **通过共享空间共享获得**
|
||||
知识库不属于当前租户,但被共享到了用户所在的至少一个共享空间 → 用户通过「成员身份 + 共享设置」得到**受限权限**(见下)。
|
||||
|
||||
若同时满足 1 和 2(例如先通过空间访问,后来切换到知识库所属租户),系统按「本租户拥有」处理,即完整权限。
|
||||
|
||||
### 5.2 单条共享下的「有效权限」
|
||||
### 7.2 单条共享下的「有效权限」
|
||||
|
||||
对**某一条**「知识库 ↔ 空间」的共享而言,用户在该空间内对这份知识库的权限为:
|
||||
|
||||
@@ -176,11 +219,11 @@
|
||||
- 共享为「只读」,用户在空间内是「编辑者」→ 有效权限为**只读**;
|
||||
- 共享为「可写」,用户在空间内是「编辑者」→ 有效权限为**可写**。
|
||||
|
||||
### 5.3 同一用户通过多个空间访问同一知识库(取高)
|
||||
### 7.3 同一用户通过多个空间访问同一知识库(取高)
|
||||
|
||||
若用户加入了多个工作空间,且同一知识库被共享到了其中多个空间(可能权限不同),则:
|
||||
若用户加入了多个共享空间,且同一知识库被共享到了其中多个空间(可能权限不同),则:
|
||||
|
||||
- 先按 5.2 对每个空间分别算出一条「有效权限」;
|
||||
- 先按 7.2 对每个空间分别算出一条「有效权限」;
|
||||
- 用户对该知识库的**最终权限** = 这些有效权限中的**最高**一档(不取低、不取交集)。
|
||||
|
||||
示例:
|
||||
@@ -192,7 +235,7 @@
|
||||
|
||||
这样设计可以避免:用户因同时在一个「只读共享」的空间里而被整体降级为只读。
|
||||
|
||||
### 5.4 权限层级与可执行操作
|
||||
### 7.4 权限层级与可执行操作
|
||||
|
||||
| 最终权限 | 可执行操作 |
|
||||
|----------|------------|
|
||||
@@ -204,35 +247,38 @@
|
||||
|
||||
---
|
||||
|
||||
## 六、典型场景小结
|
||||
## 八、典型场景小结
|
||||
|
||||
| 场景 | 结果 |
|
||||
|------|------|
|
||||
| 用户是空间内只读成员 | 不能把任何知识库共享到该空间;只能查看/检索该空间内已共享的知识库,且每条共享的有效权限不会超过「只读」 |
|
||||
| 用户是空间内编辑者 | 可把自己的知识库共享到该空间(可设只读或可写);可编辑空间内已共享的知识库内容(在共享权限允许的前提下);不可管理空间设置与成员 |
|
||||
| 用户是空间内管理员 | 除编辑者能力外,还可管理空间设置、成员、邀请码、审批加入/升级,以及取消空间内任意知识库共享 |
|
||||
| 用户是空间内只读成员 | 不能把任何知识库或智能体共享到该空间;只能查看/检索该空间内已共享的知识库、使用已共享的智能体,且知识库每条共享的有效权限不会超过「只读」 |
|
||||
| 用户是空间内编辑者 | 可把自己的知识库共享到该空间(可设只读或可写)、智能体共享到该空间(仅只读);可编辑空间内已共享的知识库内容(在共享权限允许的前提下);不可管理空间设置与成员 |
|
||||
| 用户是空间内管理员 | 除编辑者能力外,还可管理空间设置、成员、邀请码、审批加入/升级,以及取消空间内任意知识库共享、智能体共享 |
|
||||
| 同一知识库共享到多空间且权限不同,用户同属多空间 | 用户对该知识库的最终权限 = 各空间有效权限中的**最高**一档 |
|
||||
| 用户退出或被移出空间 | 立即失去通过该空间访问任何共享知识库的权限 |
|
||||
| 用户退出或被移出空间 | 立即失去通过该空间访问任何共享知识库与共享智能体的权限 |
|
||||
| 用户停用某共享智能体 | 仅影响本租户在对话下拉等处的展示偏好,不取消共享,不影响其他成员 |
|
||||
|
||||
---
|
||||
|
||||
## 七、与产品术语的对应
|
||||
## 九、与产品术语的对应
|
||||
|
||||
- 产品中的「共享空间」= 本文的「工作空间」= 系统中的 Organization。
|
||||
- 产品与系统中的「共享空间」= Organization。
|
||||
- 产品中的「创建者」= 空间创建者 = 自动拥有管理员角色且不可被降级或移出的成员。
|
||||
- 知识库「共享到空间」= 建立一条 KnowledgeBaseShare 记录,并指定该空间下的共享权限(只读/可写)。
|
||||
- 成员在空间内的「权限说明」中「共享知识库到空间」一项:仅管理员和编辑者具备,只读不具备;与本文第四节、第五节规则一致。
|
||||
- 智能体「共享到空间」= 建立一条 AgentShare 记录,权限固定为只读。
|
||||
- 成员在空间内的「权限说明」中「共享知识库/智能体到空间」:仅管理员和编辑者具备,只读不具备;与本文第四、五节规则一致。
|
||||
- 智能体「停用」= 当前租户在 tenant_disabled_shared_agents 中记录偏好,仅影响本人对话下拉等展示,与第六节一致。
|
||||
|
||||
---
|
||||
|
||||
## 八、附录:权限判定流程(实现参考)
|
||||
## 十、附录:权限判定流程(实现参考)
|
||||
|
||||
以下为后端逻辑的简要归纳,便于与实现对照:
|
||||
|
||||
1. **判断是否本租户知识库**
|
||||
若 `knowledge_base.tenant_id == current_user.tenant_id` → 直接视为完整权限,不再查共享。
|
||||
|
||||
2. **收集所有「该知识库 → 某空间」的共享**
|
||||
2. **收集所有「该知识库 → 某共享空间」的共享**
|
||||
查出所有 `kb_id = 该知识库` 的共享记录。
|
||||
|
||||
3. **对每条共享**
|
||||
@@ -246,4 +292,4 @@
|
||||
- 发起共享:用户须为空间成员且角色为 admin 或 editor;
|
||||
- 取消/修改共享:发起人可操作自己的共享;空间管理员可取消任意指向本空间的共享。
|
||||
|
||||
以上规则与 `internal/application/service/kbshare.go` 及 `organization.go` 中的实现一致。产品界面(如成员列表中的「权限说明」、共享知识库时的空间筛选)已按相同规则做了展示与限制。
|
||||
以上规则与 `internal/application/service/kbshare.go`、`agent_share.go` 及 `organization.go` 中的实现一致。产品界面(如成员列表中的「权限说明」、共享知识库/智能体时的空间筛选、智能体停用偏好)已按相同规则做了展示与限制。
|
||||
|
||||
Reference in New Issue
Block a user