> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For AgentScope Python, use https://docs.agentscope.io/stable/en/index for new projects. For existing projects, check the installed agentscope version and use matching versioned documentation.
> The /latest/ alias points to the newest documentation and may move ahead of /stable/ when a development version exists. Do not mix AgentScope 1.x and 2.x APIs.
> State the AgentScope version when providing installation commands or code examples. ReMe uses its own continuously updated /reme/latest/ documentation.

# 资源共享

> 以团队，组织为单位共享 API 凭证、智能体与知识库

资源共享是指让一个用户的 **凭证**、**智能体** 和 **知识库** 对其他用户变得可见（可使用）或可编辑。

默认情况下，AgentScope 中智能体服务默认是按照租户严格隔离的，任何用户都看不到别人的记录（见[资源模型](https://docs.agentscope.io/zh/versions/2.0.12dev/deploy/agent-service.md#资源模型)）。
资源共享是在确保数据安全的前提下合法实现资源共享的途径。

适用的典型场景包括：

* **团队共享 API 密钥**: 由一名管理员统一配置好 API key，团队内成员都能使用，却始终看不到密钥本身。
* **发布智能体**: 将一个精心调校好的智能体作为服务分享给其他用户，或整个团队/部门。
* **公共知识库**: 一份已建好索引的知识库（产品手册、政策集）由一个团队共同查询，而不必每个用户各自重复建立。
* **知识库共建**: 一个小组共同维护某个智能体或知识库，每位成员都能编辑它。

## 工作原理

AgentScope 通过 **资源访问策略（resource access policy）** 实现资源的安全共享：它把一个访问者的 `user_id` 映射到其可触达的资源，可以理解为一份资源的路由表单。
而智能体服务中则 **不带有任何用户、群组或成员关系模型**，这份共享关系可以来自任何身份系统（配置、IAM、LDAP、数据库）。

在资源相关的请求中，服务会首先解析出 `view_id`（即*访问者的 `user_id`*），并通过资源访问策略的如下两个接口控制访问权限：

* `list_accessible` 决定**访问者能看到并使用什么**，
* `can_edit` 决定**访问者是否可以进行修改**。

下图描绘这两条路径。

```mermaid theme={null}
flowchart TD
    V([服务中解析的 viewer_id])
    Dir[(身份系统<br/>IAM, LDAP, 配置, 数据库)]

    V --> P[资源访问策略实例<br/>ResourceAccessPolicyBase]
    Dir -.被消费.-> P

    P -->|"list_accessible(viewer_id, kind)"| A["可访问资源<br/>资源类型 · 拥有者ID · 资源ID · 权限"]
    P -->|"can_edit(viewer_id, kind,<br/>owner_id, resource_id)"| B{是否允许修改?}

    A --> Vis[[可见性<br/>被分享的资源 + 用户自己的资源]]
    B --> Mut[[修改权限<br/>可修改 vs. 只读]]
```

在这个流程中，服务会在 `list_accessible` 和 `can_edit` 中注入访问者 ID 和服务的存储实例，服务的部署者需要根据输入在这两个方法中实现“访问者能触达哪些资源”的逻辑。

| 方法 | 是否必需 | 说明 |
| - | - | - |
| `list_accessible(viewer_id, kind, storage)` | 是 | 返回 `viewer_id` 可访问的、类型为 `kind` 的 `ResourceRef`，**不包含**访问者自己的资源。这一个方法就驱动了所有共享资源的 list、get 以及运行时解析。 |
| `can_edit(viewer_id, kind, owner_id, resource_id, storage)` | 否 | `viewer_id` 是否可以修改某个资源。默认实现由 `list_accessible` 推导答案（当存在一个携带 `EDIT` 的匹配项时放行）；可重写该接口进行特定鉴权逻辑。 |

相关字段如下：

| 类型 | 作用 |
| - | - |
| `ResourceAccessPolicyBase` | 部署者要继承并传给 `create_app` 的抽象策略类。 |
| `ResourceKind` | 被共享的资源类型：`CREDENTIAL`、`AGENT` 或 `KNOWLEDGE_BASE`。 |
| `ResourcePermission` | 授予的访问级别：`READ`（可见并可用）或 `EDIT`（可用并可改） |
| `ResourceRef` | 共享资源的索引 `(kind, owner_id, resource_id, permission)`。 |

开发者/部署者通过继承并实现 `ResourceAccessPolicyBase` 类实现业务相关的资源共享逻辑。

被共享的智能体不止能直接对话：只要该智能体开启了 `Invitable`，访问者的队长智能体也可以用 `AgentInvite` 把它邀请进团队，详见[设置邀请范围](https://docs.agentscope.io/zh/versions/2.0.12dev/deploy/agent-team.md#设置邀请范围)。

> [!NOTE]
>
> 智能体服务中默认策略实现是 `DenyAllResourceAccessPolicy`，即跨用户不共享任何资源。

## 实现方式

在智能体服务中，开发者/部署者需要在 `create_app` 的入口处提供对应的资源共享策略，告诉服务*谁能看到什么*。共享凭证、智能体还是知识库，差别仅在于返回的 `ResourceRef` 的 `kind` 值。

**1. 实现一个策略**

继承 `ResourceAccessPolicyBase`，实现所需的共享逻辑。`list_accessible` 是必须实现的抽象接口，`can_edit` 是可选的。两者都是异步方法，在被调用时会提供 `storage` 参数，从而可以访问后端存储，在接口实现时开发者可以自由接入外部源 —— 公司的用户目录、组织架构、项目成员表、IAM 服务 —— 并把这些关系转换为资源授权。

下面的类展示了要填写的接口：

```python policy.py theme={null}
from agentscope.app.access import (
    ResourceAccessPolicyBase,
    ResourceKind,
    ResourceRef,
)
from agentscope.app.storage import StorageBase


class MyResourceAccessPolicy(ResourceAccessPolicyBase):
    """将用户ID映射为其可见的资源。"""

    async def list_accessible(
        self,
        viewer_id: str,
        kind: ResourceKind,
        storage: StorageBase,
    ) -> list[ResourceRef]:
        # 在你的系统中查询 `view_id` 能够访问的对应 `kind` 指向的资源类型；
        # 注意：不需要包含该用户自己拥有的资源；
        ...

    async def can_edit(
        self,
        viewer_id: str,
        kind: ResourceKind,
        owner_id: str,
        resource_id: str,
        storage: StorageBase,
    ) -> bool:
        # 可选实现。决定 `view_id` 指向的用户是否可以编辑该资源，
        # 默认根据 `list_accessible` 返回的资源做匹配，并根据权
        # 限类型返回是否可以编辑        
        ...
```

**2. 描述共享了什么**

每个被共享的资源都使用一个 `ResourceRef` 实例表示。`kind` 代表资源类型，`permission` 决定只读还是可编辑，下面了不同类型的共享资源实例：

```python API 凭证 theme={null}
from agentscope.app.access import (
    ResourceKind,
    ResourcePermission,
    ResourceRef,
)

# 将 Alice 的 API 凭证以“只读”权限分享给用户 Bob。
# Bob 可以使用该 API 凭证创建智能体并运行会话，但是不会看到 API 凭证的真实值。
ref = ResourceRef(
    kind=ResourceKind.CREDENTIAL,
    owner_id="alice",
    resource_id="cred-openai-prod",
    permission=ResourcePermission.READ,
)
```

```python 智能体 theme={null}
from agentscope.app.access import (
    ResourceKind,
    ResourcePermission,
    ResourceRef,
)

# 将 Alice 创建的智能体分享给 Bob，并且 Bob 也可以编辑该智能体
ref = ResourceRef(
    kind=ResourceKind.AGENT,
    owner_id="alice",
    resource_id="agent-support-bot",
    permission=ResourcePermission.EDIT,
)
```

```python 知识库 theme={null}
from agentscope.app.access import (
    ResourceKind,
    ResourcePermission,
    ResourceRef,
)

# 将 Alice 的知识库分享给 Bob，默认为只读权限，即仅可以进行查询
ref = ResourceRef(
    kind=ResourceKind.KNOWLEDGE_BASE,
    owner_id="alice",
    resource_id="kb-handbook",
)
```

**3. 安装策略**

通过 `resource_access_policy` 参数把策略实例传给 `create_app`。此后，凭证、智能体和知识库的 list 与 get 端点会把每个访问者自己的资源与共享给他的资源合并返回。

```python app.py theme={null}
from agentscope.app import create_app
from policy import MyResourceAccessPolicy

app = create_app(
    # ...existing code...
    resource_access_policy=MyResourceAccessPolicy(),
)
```

> [!WARNING]
>
> 共享的 API 凭证在所有 list 与 get 响应中都会被**脱敏** —— 访问者只能看到凭证的 `type` 和 `name`，永远看不到密钥载荷。原始密钥仅在访问者真正运行智能体时、于受信任的运行时路径（chat / embedding / TTS 模型构造）中被解析。切勿新增会把已解析凭证回传给客户端的端点。

> [!TIP]
>
> 返回给访问者的视图带有一个由引用权限计算出的 `editable` 标志，因此前端无需再发一次鉴权请求即可区分渲染只读与可编辑资源。仅有 `READ` 的访问者若尝试 `PATCH`/`DELETE` 会得到 `403`；对完全不可见的资源则返回 `404`。

> [!NOTE]
>
> 共享一个智能体，共享的是它的**配置** —— 显示名、系统提示词，以及 context / ReAct 设置 —— 而**不包括它的 workspace 内容**。MCP 客户端配置、skills 以及累积的记忆（`MEMORY.md`）都存放在按用户隔离的 [workspace](https://docs.agentscope.io/zh/versions/2.0.12dev/deploy/workspace-manager.md) 中，它会为每个访问者重新初始化，因此共享的智能体对每个用户都是从一个干净的 workspace 起步，而非继承属主的工具与记忆。
>
> 共享这部分驻留在 workspace 中的状态是一个已知的缺口，我们正在积极解决；进展请关注 GitHub 上的跟踪 issue。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.