mirror of
https://github.com/Tencent/WeKnora.git
synced 2026-08-31 00:50:02 +08:00
wizardchen
f780f81fc0
Import and update WeKnora documentation with VitePress: getting started, architecture, features, API reference, clients, and development guides. Includes landing page with inline SVG illustrations, theme components, doc check scripts, and product screenshots.
441 lines
15 KiB
Markdown
441 lines
15 KiB
Markdown
# API 参考：组织与共享
|
||
|
||
路由注册：`internal/router/router.go` 的 `RegisterOrganizationRoutes`。Handler：`internal/handler/organization.go`。
|
||
|
||
组织（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
|
||
|
||
用途：更新组织（服务层校验调用者空间为组织 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
|
||
|
||
用途：本空间退出组织。权限：Admin+。无请求体。
|
||
|
||
响应：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（解析为其空间） |
|
||
| `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
|
||
|
||
用途：组织成员（空间）列表。权限：Viewer+。
|
||
|
||
响应：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
|
||
|
||
用途：移除成员空间（含自移除）。权限：Admin+。
|
||
|
||
响应：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"}`（必填）。
|
||
|
||
响应：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
|
||
|
||
用途：取消分享。权限：KB 创建者 OR Admin+。
|
||
|
||
响应：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
|
||
|
||
用途：把 Agent 分享到组织。权限：Agent 创建者 OR Admin+。请求体同 KB 分享（`organization_id` + `permission`，必填）。
|
||
|
||
响应：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
|
||
|
||
用途：取消 Agent 分享。权限：Agent 创建者 OR Admin+。
|
||
|
||
响应：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}'
|
||
```
|