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}}
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":{}}}}}
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}}
curl $BASE/api/v1/organizations/preview/ABC123 -H "Authorization: Bearer $TOKEN"POST /api/v1/organizations/join
用途：凭邀请码加入组织。权限：Admin+。请求体：{"invite_code":"..."}（必填）。
响应：200 {"success":true,"data":{OrganizationResponse}}
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}}
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}
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}}
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}}
curl $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/organizations/:id
用途：更新组织（服务层校验调用者空间是组织 admin，不限于 owner）。权限：Admin+。请求体字段同创建（均可选）。
响应：200 {"success":true,"data":{OrganizationResponse}}
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"}
curl -X DELETE $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/organizations/:id/leave
用途：本空间退出组织。权限：Admin+。无请求体。本空间分享进该组织的知识库和 Agent 会被一并撤销。
响应：200 {"success":true,"message":"Left organization successfully"}
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}}
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":"..."}}
curl -X POST $BASE/api/v1/organizations/org-1/invite-code -H "Authorization: Bearer $TOKEN"GET /api/v1/organizations/:id/search-tenants
用途：按空间 ID 解析可邀请的空间。权限：Admin+，且调用者空间须为组织 admin。自 v0.8.2 起只接受完整的空间 ID，不再按空间名称跨空间搜索，limit 参数已移除。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
q | string | 是 | 完整的空间 ID |
响应：200 {"success":true,"data":[{"tenant_id","tenant_name"}]}。q 不是有效 ID、空间不存在或已是组织成员时返回空数组，否则返回唯一候选。
curl "$BASE/api/v1/organizations/org-1/search-tenants?q=10002" -H "Authorization: Bearer $TOKEN"GET /api/v1/organizations/:id/search-users
用途：已废弃别名，行为同 search-tenants。权限：Admin+。参数同上。
curl "$BASE/api/v1/organizations/org-1/search-users?q=10002" -H "Authorization: Bearer $TOKEN"POST /api/v1/organizations/:id/invite
用途：直接邀请空间加入组织。权限：Admin+。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
tenant_id | uint64 | 二选一 | 目标空间 ID（推荐） |
user_id | string | 二选一 | 兼容路径：用户 ID（解析为其空间） |
representative_user_id | string | 否 | 已忽略，仅为兼容保留：直接添加的空间不挂代表用户，避免邀请方指定对方空间里哪位用户的信息出现在成员列表中 |
role | string | 是 | 组织内角色 |
响应：200 {"success":true,"message":"Member added successfully"}
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
用途：组织成员（空间）列表。权限：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}}
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"}
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
用途：移除成员空间（含自移除）。权限：Admin+。被移除空间分享进该组织的知识库和 Agent 会被一并撤销。
响应：200 {"success":true,"message":"Member removed successfully"}
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}}
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"}
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}}
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}}
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}
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}
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}}
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}}
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"}（必填）。
服务层规则（与取消分享共用）：
- 原分享人需在 KB 所属空间内操作，且空间角色为 Contributor+；
- KB 所属空间的 Admin+ 可以管理本空间的全部分享；
- 目标组织中角色为 admin 的空间，其 Admin+ 用户只能降低权限或取消分享，不能把权限提升到超过当前值。
share_id 必须属于路径中的 KB，否则 404。
响应：200 {"success":true,"message":"Share permission updated successfully"}
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
用途：取消分享。权限：KB 创建者 OR Admin+，服务层规则同上。share_id 必须属于路径中的 KB，否则 404。
响应：200 {"success":true,"message":"Share removed successfully"}
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
用途：把 Agent 分享到组织。权限：Agent 创建者 OR Admin+。请求体同 KB 分享（organization_id + permission，必填）。内置智能体不能分享（400）：每个空间都有同 ID 的内置智能体，分享后接收方无法区分。Agent 的知识库范围会开放给组织成员，因此调用者必须有权直接分享其中每个知识库（知识库创建者或 Admin+），kb_selection_mode: all 只有 Admin+ 可以分享，否则 403。
响应：201 {"success":true,"data":{AgentShare}}
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}}
curl $BASE/api/v1/agents/agent-1/shares -H "Authorization: Bearer $TOKEN"DELETE /api/v1/agents/:id/shares/:share_id
用途：取消 Agent 分享。权限：Agent 创建者 OR Admin+，服务层规则同 KB 取消分享。share_id 必须属于路径中的 Agent，否则 404。
响应：200 {"success":true,"message":"Share removed successfully"}
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}
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 指明来源空间；该值会与共享关系逐一校验，非法或无权限时直接报错，不会静默回退到别的来源。
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}
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/routes_agent.go 的 RegisterOrganizationRoutes。Handler：internal/handler/organization.go。