diff --git a/docs/工作空间说明.md b/docs/工作空间说明.md index bb1a9f27..033188a0 100644 --- a/docs/工作空间说明.md +++ b/docs/工作空间说明.md @@ -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` 中的实现一致。产品界面(如成员列表中的「权限说明」、共享知识库/智能体时的空间筛选、智能体停用偏好)已按相同规则做了展示与限制。