WeKnora/website-docs/04-api/02-api-org.md

453 lines
16 KiB
Markdown
Raw Normal View History

# API 参考:组织与共享
管理组织成员以及知识库和智能体的共享关系。组织以工作空间为成员单位。
组织(Organization)以“空间(tenant)”为成员单位。组织组路由的 API key 策略为 `manage_spaces` 或 full-access;KB/Agent 分享管理仅 full-access key 可用。
## 组织管理(/api/v1/organizations)
### POST /api/v1/organizations
用途:创建组织。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 组织名称 |
| `description` | string | 否 | 描述 |
| `avatar` | string | 否 | 头像 URL |
| `searchable` | bool | 否 | 是否可被搜索发现 |
| `require_approval` | bool | 否 | 加入是否需审批 |
| `member_limit` | int | 否 | 成员空间数上限 |
| `invite_code_validity_days` | int | 否 | 邀请码有效期(天) |
响应:201 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl -X POST $BASE/api/v1/organizations -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"研发组织"}'
```
### GET /api/v1/organizations
用途:列出我所在的组织。权限:Viewer+。
响应:200 `{"success":true,"data":{"organizations":[...],"total":N,"resource_counts":{"knowledge_bases":{"by_organization":{}},"agents":{"by_organization":{}}}}}`
```bash
curl $BASE/api/v1/organizations -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/preview/:code
用途:按邀请码预览组织(不加入)。权限:Viewer+。路径参数:`code` 邀请码。
响应:200 `{"success":true,"data":{id,name,description,avatar,member_count,share_count,agent_share_count,is_already_member,require_approval,created_at}}`
```bash
curl $BASE/api/v1/organizations/preview/ABC123 -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/join
用途:凭邀请码加入组织。权限:Admin+。请求体:`{"invite_code":"..."}`(必填)。
响应:200 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl -X POST $BASE/api/v1/organizations/join -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"invite_code":"ABC123"}'
```
### POST /api/v1/organizations/join-request
用途:提交加入申请(需审批的组织)。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `invite_code` | string | 是 | 邀请码 |
| `message` | string | 否 | 申请附言 |
| `role` | string | 否 | 期望角色 |
响应:200 `{"success":true,"data":{JoinRequest}}`
```bash
curl -X POST $BASE/api/v1/organizations/join-request -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"invite_code":"ABC123","message":"申请加入"}'
```
### GET /api/v1/organizations/search
用途:搜索可发现(searchable)的组织。权限:Viewer+。
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `q` | string | 否 | 关键字 |
| `limit` | int | 否 | 默认 20,上限 100 |
响应:200 `{"success":true,"data":[SearchableOrganization],"total":N}`
```bash
curl "$BASE/api/v1/organizations/search?q=研发" -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/join-by-id
用途:按组织 ID 加入可发现组织(无需邀请码)。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `organization_id` | string | 是 | 目标组织 ID |
| `message` | string | 否 | 附言 |
| `role` | string | 否 | 期望角色 |
响应:200 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl -X POST $BASE/api/v1/organizations/join-by-id -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"organization_id":"org-1"}'
```
### GET /api/v1/organizations/:id
用途:组织详情。权限:Viewer+。
响应:200 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/organizations/:id
fix(security): close the low-severity shared-space findings (#3416) * fix(security): close the low-severity shared-space findings Verified and fixed from the shared-space permission review: - Embed channels kept knowledge_ids, tag_ids, mentioned_items, skill_names and summary_model_id from anonymous visitors. Mentions are only scoped for shared agents, so a visitor could query any KB (and pick any model) of the channel workspace by ID. The payload now drops them; the widget never sends them. - PUT /knowledgebase/:kb_id/wiki/issues/:issue_id/status updated any issue by ID. The update is now scoped to the path's KB (404 otherwise). - A direct org invite let the inviter attach any user of the target workspace (or any user by ID) as its representative, whose username and email the roster then showed to all members. Direct adds attach no representative, and the roster returns emails only for the caller's own workspace. - COS and KS3 dropped the bucket (and COS the region) segment when turning a path into an object key, while the tenant check scans every segment: cos://42/<region>/prefix/7/... passed as tenant 42 and read tenant 7's object from a shared bucket. Both must now match the service's config. - Shared agent listings returned the full agent to receivers. Prompts and the creator's user ID are withheld; capabilities and scope stay visible. - Temporary document uploads let the caller pick the parser engine (and its credentials) of a shared agent's workspace; only the agent's rules choose one there now. - Suggested questions used request / message-snapshot knowledge_ids without a permission check. Each document is now resolved to its KB and checked like KB IDs, including a shared agent's scope. - IM channels accepted any knowledge_base_id (and any agent ID on create). Both must belong to the channel's workspace, the KB also to a restricted API key's allow-list. - KB-restricted API keys could list org-shared KBs outside their allow-list in the organization views; those listings are now filtered. - With enable_rbac=false, RequireKBAccess let cross-workspace denials through. That switch is for roles inside a workspace; the guard now always denies another workspace's KB, since handlers behind it load by ID without a tenant filter. - The org member limit was counted before and enforced apart from the insert; it is now checked in the insert's transaction with the organization row locked (SQLite serializes writers instead). - The UpdateOrganization route comment and API doc said owner-only; the service and UI allow org admins. Comment and doc corrected. Documented, not changed: issued /r/ and presigned links stay valid until they expire after a share is revoked. * fix(security): address review of the low-severity shared-space fixes - Embed payloads also drop question_origin. It selects a KB like an @mention for agents that retrieve only when mentioned, and the widget never sends it; the selection stays inside the agent's scope, but an anonymous visitor should not pick among its KBs. suggestion_attribution is kept (the widget sends it and it is validated). - The receiver view of a shared agent also withholds the follow-up suggestion instruction, a prompt like the others. Starter questions are shown to receivers anyway, and the sharer's name is displayed by design. - Follow-up suggestion generation moves into the agent's workspace with types.WithExecutionTenant instead of a bare tenant rewrite, so the caller is pinned before the document permission check runs. The auth middleware and the shared run already pinned it; this removes the dependency on that. - KS3 CopyFile copies only from the service's own bucket (as COS and S3 do); another bucket's path is a cross-backend copy. Tests cover the dropped question_origin, the follow-up instruction and the /shared-agents listing, a follow-up context with the tenant switched, a repeated wiki issue status update, and the KS3 copy source.
2026-09-18 14:58:46 +00:00
用途:更新组织(服务层校验调用者空间是组织 admin,不限于 owner)。权限:Admin+。请求体字段同创建(均可选)。
响应:200 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl -X PUT $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"description":"更新描述"}'
```
### DELETE /api/v1/organizations/:id
用途:删除组织。权限:Admin+(服务层要求组织 owner)。
响应:200 `{"success":true,"message":"Organization deleted successfully"}`
```bash
curl -X DELETE $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/:id/leave
fix(security): close cross-workspace access paths in shared spaces (#3408) * fix(security): close cross-workspace access paths in shared spaces A review of how shared-space (organization) members reach each other's resources found six paths that bypass the org-share permission model: - presigned-preview signed any resource handle or storage path, turning a known resource:// handle into an anonymous /r/ URL that outlives share revocation. It now requires the path to belong to the caller's tenant, like /files. - POST /initialization/initialize let a shared-KB editor rewrite the owner workspace's models (base URL, API key) in place. Only the KB's own workspace may call it, and rewriting a stored model needs the same authority as PUT /models/:id. - KB JSON carried the legacy inline credentials (storage_config secret_id/secret_key, which initialization fills with the MinIO env keys, and vlm_config api_key) to every share receiver. They are withheld from JSON; their DB columns are unchanged. - A chat without agent_source_tenant_id resolved shares before the caller's own agent, so a member sharing a same-ID built-in agent took over other workspaces' default agent. Own agents now win, built-in agents can no longer be shared (existing such shares no longer resolve), and embed channels drop a visitor-supplied source workspace. - Any org-admin tenant (even a tenant Viewer inside it) could raise another workspace's KB share to editor/admin, and the route guard was bypassable via an unrelated :id. Share management is now: the sharer from the source tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's Admin+ that may only remove or lower. share_id must belong to :id. - Wiki write tools were registered for every wiki KB in the search targets, which only need read access, so a viewer share (e.g. via the built-in wiki fixer) could edit or delete another workspace's wiki pages. They now act only on KBs the caller may edit. * fix(security): close the KB settings path and owner details for share receivers Follow-up to the shared-space review: - PUT /initialization/config shares the route guard that admits share editors, so an editor could still rebind the owner's KB models, chunking and storage, and storage backends resolved against the caller's workspace let it bind the owner's KB to its own backend. Another workspace now needs an admin share (the only share level the frontend offers settings to) and may not change the storage binding at all. - GET /initialization/config showed model base URLs and bucket locations to any admin of the caller's own workspace, including share receivers. They now only see whether credentials are configured. - Wiki write tools on the caller's own KBs had no role floor, so a tenant Viewer (and the IM, embed and MCP endpoint principals that run as Viewer) could write through an agent what the HTTP routes deny. Writes now need Contributor+, or the ingest capability for a scoped API key, following the RBAC rollout switch. - resolveAgent logs the share lookup error instead of a nil own-agent error when a shared selector fails. * fix(security): close the medium shared-space access findings Follow-up to the high-risk fixes, from the same review: - Wiki fixer moved into a shared KB's workspace ran with the caller's own config there: an unset MCP mode registered all of the owner's MCP services, and an "all" KB scope reached the owner's other KBs. The scoped run now uses the built-in config pinned to that one KB, without MCP, skills, sandbox or web search, and falls back to the KB's own model. - An unset MCP mode means "all" at runtime but is shown as none in the share scope; shared runs now treat it as none. - Quick-answer mode used the request's web_search_enabled alone, so a receiver could turn on search the agent disables and spend the owner's provider quota. It now requires the agent setting too, as agent mode does. - summary_model_id picked any model of the workspace a run executes in. It is ignored for shared agents and the relocated wiki fixer. - A workspace that left or was removed from an organization kept sharing its KBs and agents. Its shares are revoked on departure, and share queries and permission checks require the source workspace's membership and a live organization, which also covers rows left behind earlier. - Sharing an agent exposes its KB scope to all members, so a Contributor could share colleagues' KBs (or "all") through an agent. The sharer must now be able to share each KB directly (creator or Admin+; "all" needs Admin+), also when a shared agent's scope is widened later. - A scoped API key with manage_channels could mint an MCP endpoint token wider than itself. Endpoints it creates, updates or rotates must stay within its KB allow-list and capabilities. - A shared agent's run indexed the receiver's Q&A into the owner's chat history KB; indexing now uses the session owner's configuration. - Sharing an agent with skills keeps injecting the owner's skill environment values (product decision); the share panel now warns that members can read them. Preview of originals through read-only shares is kept as designed and documented.
2026-09-18 14:00:02 +00:00
用途:本空间退出组织。权限:Admin+。无请求体。本空间分享进该组织的知识库和 Agent 会被一并撤销。
响应:200 `{"success":true,"message":"Left organization successfully"}`
```bash
curl -X POST $BASE/api/v1/organizations/org-1/leave -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/:id/request-upgrade
用途:申请提升本空间在组织内的角色。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `requested_role` | string | 是 | 期望的组织角色(`viewer/editor/admin`) |
| `message` | string | 否 | 附言 |
响应:200 `{"success":true,"data":{JoinRequest}}`
```bash
curl -X POST $BASE/api/v1/organizations/org-1/request-upgrade -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"requested_role":"editor"}'
```
### POST /api/v1/organizations/:id/invite-code
用途:生成组织邀请码。权限:Admin+(服务层要求组织 admin)。无请求体。
响应:200 `{"success":true,"data":{"invite_code":"..."}}`
```bash
curl -X POST $BASE/api/v1/organizations/org-1/invite-code -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/search-tenants
用途:搜索可邀请的空间(返回按空间分组的候选)。权限:Admin+。
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `q` | string | 是 | 空间名关键字 |
| `limit` | int | 否 | 默认 10,上限 50 |
响应:200 `{"success":true,"data":[{"tenant_id","tenant_name"}]}`
```bash
curl "$BASE/api/v1/organizations/org-1/search-tenants?q=demo" -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/search-users
用途:已废弃别名,行为同 `search-tenants`(返回空间分组结果)。权限:Admin+。参数同上。
```bash
curl "$BASE/api/v1/organizations/org-1/search-users?q=demo" -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/:id/invite
用途:直接邀请空间加入组织。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `tenant_id` | uint64 | 二选一 | 目标空间 ID(推荐) |
| `user_id` | string | 二选一 | 兼容路径:用户 ID(解析为其空间) |
fix(security): close the low-severity shared-space findings (#3416) * fix(security): close the low-severity shared-space findings Verified and fixed from the shared-space permission review: - Embed channels kept knowledge_ids, tag_ids, mentioned_items, skill_names and summary_model_id from anonymous visitors. Mentions are only scoped for shared agents, so a visitor could query any KB (and pick any model) of the channel workspace by ID. The payload now drops them; the widget never sends them. - PUT /knowledgebase/:kb_id/wiki/issues/:issue_id/status updated any issue by ID. The update is now scoped to the path's KB (404 otherwise). - A direct org invite let the inviter attach any user of the target workspace (or any user by ID) as its representative, whose username and email the roster then showed to all members. Direct adds attach no representative, and the roster returns emails only for the caller's own workspace. - COS and KS3 dropped the bucket (and COS the region) segment when turning a path into an object key, while the tenant check scans every segment: cos://42/<region>/prefix/7/... passed as tenant 42 and read tenant 7's object from a shared bucket. Both must now match the service's config. - Shared agent listings returned the full agent to receivers. Prompts and the creator's user ID are withheld; capabilities and scope stay visible. - Temporary document uploads let the caller pick the parser engine (and its credentials) of a shared agent's workspace; only the agent's rules choose one there now. - Suggested questions used request / message-snapshot knowledge_ids without a permission check. Each document is now resolved to its KB and checked like KB IDs, including a shared agent's scope. - IM channels accepted any knowledge_base_id (and any agent ID on create). Both must belong to the channel's workspace, the KB also to a restricted API key's allow-list. - KB-restricted API keys could list org-shared KBs outside their allow-list in the organization views; those listings are now filtered. - With enable_rbac=false, RequireKBAccess let cross-workspace denials through. That switch is for roles inside a workspace; the guard now always denies another workspace's KB, since handlers behind it load by ID without a tenant filter. - The org member limit was counted before and enforced apart from the insert; it is now checked in the insert's transaction with the organization row locked (SQLite serializes writers instead). - The UpdateOrganization route comment and API doc said owner-only; the service and UI allow org admins. Comment and doc corrected. Documented, not changed: issued /r/ and presigned links stay valid until they expire after a share is revoked. * fix(security): address review of the low-severity shared-space fixes - Embed payloads also drop question_origin. It selects a KB like an @mention for agents that retrieve only when mentioned, and the widget never sends it; the selection stays inside the agent's scope, but an anonymous visitor should not pick among its KBs. suggestion_attribution is kept (the widget sends it and it is validated). - The receiver view of a shared agent also withholds the follow-up suggestion instruction, a prompt like the others. Starter questions are shown to receivers anyway, and the sharer's name is displayed by design. - Follow-up suggestion generation moves into the agent's workspace with types.WithExecutionTenant instead of a bare tenant rewrite, so the caller is pinned before the document permission check runs. The auth middleware and the shared run already pinned it; this removes the dependency on that. - KS3 CopyFile copies only from the service's own bucket (as COS and S3 do); another bucket's path is a cross-backend copy. Tests cover the dropped question_origin, the follow-up instruction and the /shared-agents listing, a follow-up context with the tenant switched, a repeated wiki issue status update, and the KS3 copy source.
2026-09-18 14:58:46 +00:00
| `representative_user_id` | string | 否 | 已忽略,仅为兼容保留:直接添加的空间不挂代表用户,避免邀请方指定对方空间里哪位用户的信息出现在成员列表中 |
| `role` | string | 是 | 组织内角色 |
响应:200 `{"success":true,"message":"Member added successfully"}`
```bash
curl -X POST $BASE/api/v1/organizations/org-1/invite -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"tenant_id":2,"role":"viewer"}'
```
### GET /api/v1/organizations/:id/members
fix(security): close the low-severity shared-space findings (#3416) * fix(security): close the low-severity shared-space findings Verified and fixed from the shared-space permission review: - Embed channels kept knowledge_ids, tag_ids, mentioned_items, skill_names and summary_model_id from anonymous visitors. Mentions are only scoped for shared agents, so a visitor could query any KB (and pick any model) of the channel workspace by ID. The payload now drops them; the widget never sends them. - PUT /knowledgebase/:kb_id/wiki/issues/:issue_id/status updated any issue by ID. The update is now scoped to the path's KB (404 otherwise). - A direct org invite let the inviter attach any user of the target workspace (or any user by ID) as its representative, whose username and email the roster then showed to all members. Direct adds attach no representative, and the roster returns emails only for the caller's own workspace. - COS and KS3 dropped the bucket (and COS the region) segment when turning a path into an object key, while the tenant check scans every segment: cos://42/<region>/prefix/7/... passed as tenant 42 and read tenant 7's object from a shared bucket. Both must now match the service's config. - Shared agent listings returned the full agent to receivers. Prompts and the creator's user ID are withheld; capabilities and scope stay visible. - Temporary document uploads let the caller pick the parser engine (and its credentials) of a shared agent's workspace; only the agent's rules choose one there now. - Suggested questions used request / message-snapshot knowledge_ids without a permission check. Each document is now resolved to its KB and checked like KB IDs, including a shared agent's scope. - IM channels accepted any knowledge_base_id (and any agent ID on create). Both must belong to the channel's workspace, the KB also to a restricted API key's allow-list. - KB-restricted API keys could list org-shared KBs outside their allow-list in the organization views; those listings are now filtered. - With enable_rbac=false, RequireKBAccess let cross-workspace denials through. That switch is for roles inside a workspace; the guard now always denies another workspace's KB, since handlers behind it load by ID without a tenant filter. - The org member limit was counted before and enforced apart from the insert; it is now checked in the insert's transaction with the organization row locked (SQLite serializes writers instead). - The UpdateOrganization route comment and API doc said owner-only; the service and UI allow org admins. Comment and doc corrected. Documented, not changed: issued /r/ and presigned links stay valid until they expire after a share is revoked. * fix(security): address review of the low-severity shared-space fixes - Embed payloads also drop question_origin. It selects a KB like an @mention for agents that retrieve only when mentioned, and the widget never sends it; the selection stays inside the agent's scope, but an anonymous visitor should not pick among its KBs. suggestion_attribution is kept (the widget sends it and it is validated). - The receiver view of a shared agent also withholds the follow-up suggestion instruction, a prompt like the others. Starter questions are shown to receivers anyway, and the sharer's name is displayed by design. - Follow-up suggestion generation moves into the agent's workspace with types.WithExecutionTenant instead of a bare tenant rewrite, so the caller is pinned before the document permission check runs. The auth middleware and the shared run already pinned it; this removes the dependency on that. - KS3 CopyFile copies only from the service's own bucket (as COS and S3 do); another bucket's path is a cross-backend copy. Tests cover the dropped question_origin, the follow-up instruction and the /shared-agents listing, a follow-up context with the tenant switched, a repeated wiki issue status update, and the KS3 copy source.
2026-09-18 14:58:46 +00:00
用途:组织成员(空间)列表。权限:Viewer+。`email` 只对调用方自己空间那一行返回,其他空间只返回用户名和头像。
响应:200 `{"success":true,"data":{"members":[{id,user_id,representative_user_id,role,tenant_id,tenant_name,username,email,avatar,joined_at}],"total":N}}`
```bash
curl $BASE/api/v1/organizations/org-1/members -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/organizations/:id/members/:tenant_id
用途:修改成员空间的组织角色。权限:Admin+。路径参数 `tenant_id` 为成员空间 ID。请求体:`{"role":"editor"}`(必填,`viewer/editor/admin`)。
响应:200 `{"success":true,"message":"Member role updated successfully"}`
```bash
curl -X PUT $BASE/api/v1/organizations/org-1/members/2 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"role":"editor"}'
```
### DELETE /api/v1/organizations/:id/members/:tenant_id
fix(security): close cross-workspace access paths in shared spaces (#3408) * fix(security): close cross-workspace access paths in shared spaces A review of how shared-space (organization) members reach each other's resources found six paths that bypass the org-share permission model: - presigned-preview signed any resource handle or storage path, turning a known resource:// handle into an anonymous /r/ URL that outlives share revocation. It now requires the path to belong to the caller's tenant, like /files. - POST /initialization/initialize let a shared-KB editor rewrite the owner workspace's models (base URL, API key) in place. Only the KB's own workspace may call it, and rewriting a stored model needs the same authority as PUT /models/:id. - KB JSON carried the legacy inline credentials (storage_config secret_id/secret_key, which initialization fills with the MinIO env keys, and vlm_config api_key) to every share receiver. They are withheld from JSON; their DB columns are unchanged. - A chat without agent_source_tenant_id resolved shares before the caller's own agent, so a member sharing a same-ID built-in agent took over other workspaces' default agent. Own agents now win, built-in agents can no longer be shared (existing such shares no longer resolve), and embed channels drop a visitor-supplied source workspace. - Any org-admin tenant (even a tenant Viewer inside it) could raise another workspace's KB share to editor/admin, and the route guard was bypassable via an unrelated :id. Share management is now: the sharer from the source tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's Admin+ that may only remove or lower. share_id must belong to :id. - Wiki write tools were registered for every wiki KB in the search targets, which only need read access, so a viewer share (e.g. via the built-in wiki fixer) could edit or delete another workspace's wiki pages. They now act only on KBs the caller may edit. * fix(security): close the KB settings path and owner details for share receivers Follow-up to the shared-space review: - PUT /initialization/config shares the route guard that admits share editors, so an editor could still rebind the owner's KB models, chunking and storage, and storage backends resolved against the caller's workspace let it bind the owner's KB to its own backend. Another workspace now needs an admin share (the only share level the frontend offers settings to) and may not change the storage binding at all. - GET /initialization/config showed model base URLs and bucket locations to any admin of the caller's own workspace, including share receivers. They now only see whether credentials are configured. - Wiki write tools on the caller's own KBs had no role floor, so a tenant Viewer (and the IM, embed and MCP endpoint principals that run as Viewer) could write through an agent what the HTTP routes deny. Writes now need Contributor+, or the ingest capability for a scoped API key, following the RBAC rollout switch. - resolveAgent logs the share lookup error instead of a nil own-agent error when a shared selector fails. * fix(security): close the medium shared-space access findings Follow-up to the high-risk fixes, from the same review: - Wiki fixer moved into a shared KB's workspace ran with the caller's own config there: an unset MCP mode registered all of the owner's MCP services, and an "all" KB scope reached the owner's other KBs. The scoped run now uses the built-in config pinned to that one KB, without MCP, skills, sandbox or web search, and falls back to the KB's own model. - An unset MCP mode means "all" at runtime but is shown as none in the share scope; shared runs now treat it as none. - Quick-answer mode used the request's web_search_enabled alone, so a receiver could turn on search the agent disables and spend the owner's provider quota. It now requires the agent setting too, as agent mode does. - summary_model_id picked any model of the workspace a run executes in. It is ignored for shared agents and the relocated wiki fixer. - A workspace that left or was removed from an organization kept sharing its KBs and agents. Its shares are revoked on departure, and share queries and permission checks require the source workspace's membership and a live organization, which also covers rows left behind earlier. - Sharing an agent exposes its KB scope to all members, so a Contributor could share colleagues' KBs (or "all") through an agent. The sharer must now be able to share each KB directly (creator or Admin+; "all" needs Admin+), also when a shared agent's scope is widened later. - A scoped API key with manage_channels could mint an MCP endpoint token wider than itself. Endpoints it creates, updates or rotates must stay within its KB allow-list and capabilities. - A shared agent's run indexed the receiver's Q&A into the owner's chat history KB; indexing now uses the session owner's configuration. - Sharing an agent with skills keeps injecting the owner's skill environment values (product decision); the share panel now warns that members can read them. Preview of originals through read-only shares is kept as designed and documented.
2026-09-18 14:00:02 +00:00
用途:移除成员空间(含自移除)。权限:Admin+。被移除空间分享进该组织的知识库和 Agent 会被一并撤销。
响应:200 `{"success":true,"message":"Member removed successfully"}`
```bash
curl -X DELETE $BASE/api/v1/organizations/org-1/members/2 -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/join-requests
用途:加入申请队列。权限:Admin+。
响应:200 `{"success":true,"data":{"requests":[{id,user_id,username,email,message,request_type,prev_role,requested_role,status,created_at,reviewed_at}],"total":N}}`
```bash
curl $BASE/api/v1/organizations/org-1/join-requests -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/organizations/:id/join-requests/:request_id/review
用途:审批加入/升级申请。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `approved` | bool | 是 | 通过/拒绝 |
| `message` | string | 否 | 审批意见 |
| `role` | string | 否 | 通过时授予的角色 |
响应:200 `{"success":true,"message":"Review completed"}`
```bash
curl -X PUT $BASE/api/v1/organizations/org-1/join-requests/req-1/review \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"approved":true}'
```
### GET /api/v1/organizations/:id/shares
用途:查看共享到该组织的 KB 列表。权限:Viewer+。
响应:200 `{"success":true,"data":{"shares":[KnowledgeBaseShareResponse],"total":N}}`
```bash
curl $BASE/api/v1/organizations/org-1/shares -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/agent-shares
用途:查看共享到该组织的 Agent 列表。权限:Viewer+。
响应:200 `{"success":true,"data":{"shares":[AgentShareResponse],"total":N}}`
```bash
curl $BASE/api/v1/organizations/org-1/agent-shares -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/shared-knowledge-bases
用途:组织空间视图:组织内全部共享 KB(含我自己的)。权限:Viewer+。
响应:200 `{"success":true,"data":[...含 is_mine、source_from_agent 标记...],"total":N}`
```bash
curl $BASE/api/v1/organizations/org-1/shared-knowledge-bases -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/shared-agents
用途:组织空间视图:组织内全部共享 Agent。权限:Viewer+。
响应:200 `{"success":true,"data":[SharedAgentInfo],"total":N}`
```bash
curl $BASE/api/v1/organizations/org-1/shared-agents -H "Authorization: Bearer $TOKEN"
```
## KB 分享(/api/v1/knowledge-bases/:id/shares)
API key:仅 full-access。Handler: `internal/handler/organization.go`
### POST /api/v1/knowledge-bases/:id/shares
用途:把 KB 分享到组织。权限:KB 创建者 OR Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `organization_id` | string | 是 | 目标组织 |
| `permission` | string | 是 | 共享权限(组织角色语义,如 `viewer/editor`) |
响应:201 `{"success":true,"data":{KBShare}}`
```bash
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/shares -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"organization_id":"org-1","permission":"viewer"}'
```
### GET /api/v1/knowledge-bases/:id/shares
用途:查看该 KB 的分享列表。权限:Viewer+。
响应:200 `{"success":true,"data":{"shares":[KnowledgeBaseShareResponse],"total":N}}`
```bash
curl $BASE/api/v1/knowledge-bases/kb-1/shares -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/knowledge-bases/:id/shares/:share_id
用途:修改分享权限。权限:KB 创建者 OR Admin+。请求体:`{"permission":"editor"}`(必填)。
fix(security): close cross-workspace access paths in shared spaces (#3408) * fix(security): close cross-workspace access paths in shared spaces A review of how shared-space (organization) members reach each other's resources found six paths that bypass the org-share permission model: - presigned-preview signed any resource handle or storage path, turning a known resource:// handle into an anonymous /r/ URL that outlives share revocation. It now requires the path to belong to the caller's tenant, like /files. - POST /initialization/initialize let a shared-KB editor rewrite the owner workspace's models (base URL, API key) in place. Only the KB's own workspace may call it, and rewriting a stored model needs the same authority as PUT /models/:id. - KB JSON carried the legacy inline credentials (storage_config secret_id/secret_key, which initialization fills with the MinIO env keys, and vlm_config api_key) to every share receiver. They are withheld from JSON; their DB columns are unchanged. - A chat without agent_source_tenant_id resolved shares before the caller's own agent, so a member sharing a same-ID built-in agent took over other workspaces' default agent. Own agents now win, built-in agents can no longer be shared (existing such shares no longer resolve), and embed channels drop a visitor-supplied source workspace. - Any org-admin tenant (even a tenant Viewer inside it) could raise another workspace's KB share to editor/admin, and the route guard was bypassable via an unrelated :id. Share management is now: the sharer from the source tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's Admin+ that may only remove or lower. share_id must belong to :id. - Wiki write tools were registered for every wiki KB in the search targets, which only need read access, so a viewer share (e.g. via the built-in wiki fixer) could edit or delete another workspace's wiki pages. They now act only on KBs the caller may edit. * fix(security): close the KB settings path and owner details for share receivers Follow-up to the shared-space review: - PUT /initialization/config shares the route guard that admits share editors, so an editor could still rebind the owner's KB models, chunking and storage, and storage backends resolved against the caller's workspace let it bind the owner's KB to its own backend. Another workspace now needs an admin share (the only share level the frontend offers settings to) and may not change the storage binding at all. - GET /initialization/config showed model base URLs and bucket locations to any admin of the caller's own workspace, including share receivers. They now only see whether credentials are configured. - Wiki write tools on the caller's own KBs had no role floor, so a tenant Viewer (and the IM, embed and MCP endpoint principals that run as Viewer) could write through an agent what the HTTP routes deny. Writes now need Contributor+, or the ingest capability for a scoped API key, following the RBAC rollout switch. - resolveAgent logs the share lookup error instead of a nil own-agent error when a shared selector fails. * fix(security): close the medium shared-space access findings Follow-up to the high-risk fixes, from the same review: - Wiki fixer moved into a shared KB's workspace ran with the caller's own config there: an unset MCP mode registered all of the owner's MCP services, and an "all" KB scope reached the owner's other KBs. The scoped run now uses the built-in config pinned to that one KB, without MCP, skills, sandbox or web search, and falls back to the KB's own model. - An unset MCP mode means "all" at runtime but is shown as none in the share scope; shared runs now treat it as none. - Quick-answer mode used the request's web_search_enabled alone, so a receiver could turn on search the agent disables and spend the owner's provider quota. It now requires the agent setting too, as agent mode does. - summary_model_id picked any model of the workspace a run executes in. It is ignored for shared agents and the relocated wiki fixer. - A workspace that left or was removed from an organization kept sharing its KBs and agents. Its shares are revoked on departure, and share queries and permission checks require the source workspace's membership and a live organization, which also covers rows left behind earlier. - Sharing an agent exposes its KB scope to all members, so a Contributor could share colleagues' KBs (or "all") through an agent. The sharer must now be able to share each KB directly (creator or Admin+; "all" needs Admin+), also when a shared agent's scope is widened later. - A scoped API key with manage_channels could mint an MCP endpoint token wider than itself. Endpoints it creates, updates or rotates must stay within its KB allow-list and capabilities. - A shared agent's run indexed the receiver's Q&A into the owner's chat history KB; indexing now uses the session owner's configuration. - Sharing an agent with skills keeps injecting the owner's skill environment values (product decision); the share panel now warns that members can read them. Preview of originals through read-only shares is kept as designed and documented.
2026-09-18 14:00:02 +00:00
服务层规则(与取消分享共用):
- 原分享人需在 KB 所属空间内操作,且空间角色为 Contributor+;
- KB 所属空间的 Admin+ 可以管理本空间的全部分享;
- 目标组织中角色为 admin 的空间,其 Admin+ 用户只能**降低**权限或取消分享,不能把权限提升到超过当前值。
`share_id` 必须属于路径中的 KB,否则 404。
响应:200 `{"success":true,"message":"Share permission updated successfully"}`
```bash
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/shares/s-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"permission":"editor"}'
```
### DELETE /api/v1/knowledge-bases/:id/shares/:share_id
fix(security): close cross-workspace access paths in shared spaces (#3408) * fix(security): close cross-workspace access paths in shared spaces A review of how shared-space (organization) members reach each other's resources found six paths that bypass the org-share permission model: - presigned-preview signed any resource handle or storage path, turning a known resource:// handle into an anonymous /r/ URL that outlives share revocation. It now requires the path to belong to the caller's tenant, like /files. - POST /initialization/initialize let a shared-KB editor rewrite the owner workspace's models (base URL, API key) in place. Only the KB's own workspace may call it, and rewriting a stored model needs the same authority as PUT /models/:id. - KB JSON carried the legacy inline credentials (storage_config secret_id/secret_key, which initialization fills with the MinIO env keys, and vlm_config api_key) to every share receiver. They are withheld from JSON; their DB columns are unchanged. - A chat without agent_source_tenant_id resolved shares before the caller's own agent, so a member sharing a same-ID built-in agent took over other workspaces' default agent. Own agents now win, built-in agents can no longer be shared (existing such shares no longer resolve), and embed channels drop a visitor-supplied source workspace. - Any org-admin tenant (even a tenant Viewer inside it) could raise another workspace's KB share to editor/admin, and the route guard was bypassable via an unrelated :id. Share management is now: the sharer from the source tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's Admin+ that may only remove or lower. share_id must belong to :id. - Wiki write tools were registered for every wiki KB in the search targets, which only need read access, so a viewer share (e.g. via the built-in wiki fixer) could edit or delete another workspace's wiki pages. They now act only on KBs the caller may edit. * fix(security): close the KB settings path and owner details for share receivers Follow-up to the shared-space review: - PUT /initialization/config shares the route guard that admits share editors, so an editor could still rebind the owner's KB models, chunking and storage, and storage backends resolved against the caller's workspace let it bind the owner's KB to its own backend. Another workspace now needs an admin share (the only share level the frontend offers settings to) and may not change the storage binding at all. - GET /initialization/config showed model base URLs and bucket locations to any admin of the caller's own workspace, including share receivers. They now only see whether credentials are configured. - Wiki write tools on the caller's own KBs had no role floor, so a tenant Viewer (and the IM, embed and MCP endpoint principals that run as Viewer) could write through an agent what the HTTP routes deny. Writes now need Contributor+, or the ingest capability for a scoped API key, following the RBAC rollout switch. - resolveAgent logs the share lookup error instead of a nil own-agent error when a shared selector fails. * fix(security): close the medium shared-space access findings Follow-up to the high-risk fixes, from the same review: - Wiki fixer moved into a shared KB's workspace ran with the caller's own config there: an unset MCP mode registered all of the owner's MCP services, and an "all" KB scope reached the owner's other KBs. The scoped run now uses the built-in config pinned to that one KB, without MCP, skills, sandbox or web search, and falls back to the KB's own model. - An unset MCP mode means "all" at runtime but is shown as none in the share scope; shared runs now treat it as none. - Quick-answer mode used the request's web_search_enabled alone, so a receiver could turn on search the agent disables and spend the owner's provider quota. It now requires the agent setting too, as agent mode does. - summary_model_id picked any model of the workspace a run executes in. It is ignored for shared agents and the relocated wiki fixer. - A workspace that left or was removed from an organization kept sharing its KBs and agents. Its shares are revoked on departure, and share queries and permission checks require the source workspace's membership and a live organization, which also covers rows left behind earlier. - Sharing an agent exposes its KB scope to all members, so a Contributor could share colleagues' KBs (or "all") through an agent. The sharer must now be able to share each KB directly (creator or Admin+; "all" needs Admin+), also when a shared agent's scope is widened later. - A scoped API key with manage_channels could mint an MCP endpoint token wider than itself. Endpoints it creates, updates or rotates must stay within its KB allow-list and capabilities. - A shared agent's run indexed the receiver's Q&A into the owner's chat history KB; indexing now uses the session owner's configuration. - Sharing an agent with skills keeps injecting the owner's skill environment values (product decision); the share panel now warns that members can read them. Preview of originals through read-only shares is kept as designed and documented.
2026-09-18 14:00:02 +00:00
用途:取消分享。权限:KB 创建者 OR Admin+,服务层规则同上。`share_id` 必须属于路径中的 KB,否则 404。
响应:200 `{"success":true,"message":"Share removed successfully"}`
```bash
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/shares/s-1 -H "Authorization: Bearer $TOKEN"
```
## Agent 分享(/api/v1/agents/:id/shares)
API key:仅 full-access。Handler: `internal/handler/organization.go`
### POST /api/v1/agents/:id/shares
fix(security): close cross-workspace access paths in shared spaces (#3408) * fix(security): close cross-workspace access paths in shared spaces A review of how shared-space (organization) members reach each other's resources found six paths that bypass the org-share permission model: - presigned-preview signed any resource handle or storage path, turning a known resource:// handle into an anonymous /r/ URL that outlives share revocation. It now requires the path to belong to the caller's tenant, like /files. - POST /initialization/initialize let a shared-KB editor rewrite the owner workspace's models (base URL, API key) in place. Only the KB's own workspace may call it, and rewriting a stored model needs the same authority as PUT /models/:id. - KB JSON carried the legacy inline credentials (storage_config secret_id/secret_key, which initialization fills with the MinIO env keys, and vlm_config api_key) to every share receiver. They are withheld from JSON; their DB columns are unchanged. - A chat without agent_source_tenant_id resolved shares before the caller's own agent, so a member sharing a same-ID built-in agent took over other workspaces' default agent. Own agents now win, built-in agents can no longer be shared (existing such shares no longer resolve), and embed channels drop a visitor-supplied source workspace. - Any org-admin tenant (even a tenant Viewer inside it) could raise another workspace's KB share to editor/admin, and the route guard was bypassable via an unrelated :id. Share management is now: the sharer from the source tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's Admin+ that may only remove or lower. share_id must belong to :id. - Wiki write tools were registered for every wiki KB in the search targets, which only need read access, so a viewer share (e.g. via the built-in wiki fixer) could edit or delete another workspace's wiki pages. They now act only on KBs the caller may edit. * fix(security): close the KB settings path and owner details for share receivers Follow-up to the shared-space review: - PUT /initialization/config shares the route guard that admits share editors, so an editor could still rebind the owner's KB models, chunking and storage, and storage backends resolved against the caller's workspace let it bind the owner's KB to its own backend. Another workspace now needs an admin share (the only share level the frontend offers settings to) and may not change the storage binding at all. - GET /initialization/config showed model base URLs and bucket locations to any admin of the caller's own workspace, including share receivers. They now only see whether credentials are configured. - Wiki write tools on the caller's own KBs had no role floor, so a tenant Viewer (and the IM, embed and MCP endpoint principals that run as Viewer) could write through an agent what the HTTP routes deny. Writes now need Contributor+, or the ingest capability for a scoped API key, following the RBAC rollout switch. - resolveAgent logs the share lookup error instead of a nil own-agent error when a shared selector fails. * fix(security): close the medium shared-space access findings Follow-up to the high-risk fixes, from the same review: - Wiki fixer moved into a shared KB's workspace ran with the caller's own config there: an unset MCP mode registered all of the owner's MCP services, and an "all" KB scope reached the owner's other KBs. The scoped run now uses the built-in config pinned to that one KB, without MCP, skills, sandbox or web search, and falls back to the KB's own model. - An unset MCP mode means "all" at runtime but is shown as none in the share scope; shared runs now treat it as none. - Quick-answer mode used the request's web_search_enabled alone, so a receiver could turn on search the agent disables and spend the owner's provider quota. It now requires the agent setting too, as agent mode does. - summary_model_id picked any model of the workspace a run executes in. It is ignored for shared agents and the relocated wiki fixer. - A workspace that left or was removed from an organization kept sharing its KBs and agents. Its shares are revoked on departure, and share queries and permission checks require the source workspace's membership and a live organization, which also covers rows left behind earlier. - Sharing an agent exposes its KB scope to all members, so a Contributor could share colleagues' KBs (or "all") through an agent. The sharer must now be able to share each KB directly (creator or Admin+; "all" needs Admin+), also when a shared agent's scope is widened later. - A scoped API key with manage_channels could mint an MCP endpoint token wider than itself. Endpoints it creates, updates or rotates must stay within its KB allow-list and capabilities. - A shared agent's run indexed the receiver's Q&A into the owner's chat history KB; indexing now uses the session owner's configuration. - Sharing an agent with skills keeps injecting the owner's skill environment values (product decision); the share panel now warns that members can read them. Preview of originals through read-only shares is kept as designed and documented.
2026-09-18 14:00:02 +00:00
用途:把 Agent 分享到组织。权限:Agent 创建者 OR Admin+。请求体同 KB 分享(`organization_id` + `permission`,必填)。内置智能体不能分享(400):每个空间都有同 ID 的内置智能体,分享后接收方无法区分。Agent 的知识库范围会开放给组织成员,因此调用者必须有权直接分享其中每个知识库(知识库创建者或 Admin+),`kb_selection_mode: all` 只有 Admin+ 可以分享,否则 403。
响应:201 `{"success":true,"data":{AgentShare}}`
```bash
curl -X POST $BASE/api/v1/agents/agent-1/shares -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"organization_id":"org-1","permission":"viewer"}'
```
### GET /api/v1/agents/:id/shares
用途:查看该 Agent 的分享列表。权限:Agent 创建者 OR Admin+。
响应:200 `{"success":true,"data":{"shares":[AgentShareResponse],"total":N}}`
```bash
curl $BASE/api/v1/agents/agent-1/shares -H "Authorization: Bearer $TOKEN"
```
### DELETE /api/v1/agents/:id/shares/:share_id
fix(security): close cross-workspace access paths in shared spaces (#3408) * fix(security): close cross-workspace access paths in shared spaces A review of how shared-space (organization) members reach each other's resources found six paths that bypass the org-share permission model: - presigned-preview signed any resource handle or storage path, turning a known resource:// handle into an anonymous /r/ URL that outlives share revocation. It now requires the path to belong to the caller's tenant, like /files. - POST /initialization/initialize let a shared-KB editor rewrite the owner workspace's models (base URL, API key) in place. Only the KB's own workspace may call it, and rewriting a stored model needs the same authority as PUT /models/:id. - KB JSON carried the legacy inline credentials (storage_config secret_id/secret_key, which initialization fills with the MinIO env keys, and vlm_config api_key) to every share receiver. They are withheld from JSON; their DB columns are unchanged. - A chat without agent_source_tenant_id resolved shares before the caller's own agent, so a member sharing a same-ID built-in agent took over other workspaces' default agent. Own agents now win, built-in agents can no longer be shared (existing such shares no longer resolve), and embed channels drop a visitor-supplied source workspace. - Any org-admin tenant (even a tenant Viewer inside it) could raise another workspace's KB share to editor/admin, and the route guard was bypassable via an unrelated :id. Share management is now: the sharer from the source tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's Admin+ that may only remove or lower. share_id must belong to :id. - Wiki write tools were registered for every wiki KB in the search targets, which only need read access, so a viewer share (e.g. via the built-in wiki fixer) could edit or delete another workspace's wiki pages. They now act only on KBs the caller may edit. * fix(security): close the KB settings path and owner details for share receivers Follow-up to the shared-space review: - PUT /initialization/config shares the route guard that admits share editors, so an editor could still rebind the owner's KB models, chunking and storage, and storage backends resolved against the caller's workspace let it bind the owner's KB to its own backend. Another workspace now needs an admin share (the only share level the frontend offers settings to) and may not change the storage binding at all. - GET /initialization/config showed model base URLs and bucket locations to any admin of the caller's own workspace, including share receivers. They now only see whether credentials are configured. - Wiki write tools on the caller's own KBs had no role floor, so a tenant Viewer (and the IM, embed and MCP endpoint principals that run as Viewer) could write through an agent what the HTTP routes deny. Writes now need Contributor+, or the ingest capability for a scoped API key, following the RBAC rollout switch. - resolveAgent logs the share lookup error instead of a nil own-agent error when a shared selector fails. * fix(security): close the medium shared-space access findings Follow-up to the high-risk fixes, from the same review: - Wiki fixer moved into a shared KB's workspace ran with the caller's own config there: an unset MCP mode registered all of the owner's MCP services, and an "all" KB scope reached the owner's other KBs. The scoped run now uses the built-in config pinned to that one KB, without MCP, skills, sandbox or web search, and falls back to the KB's own model. - An unset MCP mode means "all" at runtime but is shown as none in the share scope; shared runs now treat it as none. - Quick-answer mode used the request's web_search_enabled alone, so a receiver could turn on search the agent disables and spend the owner's provider quota. It now requires the agent setting too, as agent mode does. - summary_model_id picked any model of the workspace a run executes in. It is ignored for shared agents and the relocated wiki fixer. - A workspace that left or was removed from an organization kept sharing its KBs and agents. Its shares are revoked on departure, and share queries and permission checks require the source workspace's membership and a live organization, which also covers rows left behind earlier. - Sharing an agent exposes its KB scope to all members, so a Contributor could share colleagues' KBs (or "all") through an agent. The sharer must now be able to share each KB directly (creator or Admin+; "all" needs Admin+), also when a shared agent's scope is widened later. - A scoped API key with manage_channels could mint an MCP endpoint token wider than itself. Endpoints it creates, updates or rotates must stay within its KB allow-list and capabilities. - A shared agent's run indexed the receiver's Q&A into the owner's chat history KB; indexing now uses the session owner's configuration. - Sharing an agent with skills keeps injecting the owner's skill environment values (product decision); the share panel now warns that members can read them. Preview of originals through read-only shares is kept as designed and documented.
2026-09-18 14:00:02 +00:00
用途:取消 Agent 分享。权限:Agent 创建者 OR Admin+,服务层规则同 KB 取消分享。`share_id` 必须属于路径中的 Agent,否则 404。
响应:200 `{"success":true,"message":"Share removed successfully"}`
```bash
curl -X DELETE $BASE/api/v1/agents/agent-1/shares/s-1 -H "Authorization: Bearer $TOKEN"
```
## 共享资源聚合视图
### GET /api/v1/shared-knowledge-bases
用途:列出通过组织共享给我的 KB(去除属主侧向量库元数据)。权限:Viewer+;API key 需 `manage_spaces` 或 full-access。
响应:200 `{"success":true,"data":[...],"total":N}`
```bash
curl $BASE/api/v1/shared-knowledge-bases -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/shared-agents
用途:列出通过组织共享给我的 Agent。权限:Viewer+;API key 同上。
响应:200 `{"success":true,"data":[SharedAgentInfo],"total":N}`。`SharedAgentInfo` 含 `source_tenant_id`(来源空间)、`org_name`、`shared_by_username`、`permission`,以及 `web_search_ready`——只返回「来源空间的联网搜索是否可用」这一个布尔位,不下发来源空间的 provider 配置(会泄露配置),也不拿接收方空间的 provider ID 去比对(会误报不可用)。
使用共享 Agent 调用其它接口时,若同名 Agent 被多个空间共享,可带 `agent_source_tenant_id` 指明来源空间;该值会与共享关系逐一校验,非法或无权限时直接报错,不会静默回退到别的来源。
```bash
curl $BASE/api/v1/shared-agents -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/shared-agents/disabled
用途:设置“本空间禁用某共享 Agent”(影响整个空间的会话下拉)。权限:Admin+;API key 同上。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `agent_id` | string | 是(`binding:"required"`) | 共享 Agent ID |
| `disabled` | bool | 否 | 是否禁用(默认 false) |
响应:200 `{"success":true}`
```bash
curl -X POST $BASE/api/v1/shared-agents/disabled -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"agent_id":"agent-1","disabled":true}'
```
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterOrganizationRoutes`。Handler:`internal/handler/organization.go`。