Weknora/Enterprise-Knowledge-Base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ea4a2a39f2a967ab705f3ea8a2aa66aa1475b9de
Enterprise-Knowledge-Base/docs/api/organization.md
T
wizardchen daa9ef500c feat: add agent management functionality 
- Introduced a new package for managing custom agents, including CRUD operations for agent creation, retrieval, updating, and deletion.
- Implemented API endpoints for listing agents and retrieving agent placeholders.
- Added data structures for agent configuration and requests, enhancing the overall agent management capabilities.
- Enhanced the client with methods to interact with the new agent management features, improving user experience in managing agents.

These changes significantly expand the application's functionality for handling custom agents, providing users with a comprehensive toolset for agent management.
2026-03-09 17:34:13 +08:00

984 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 组织管理 API
[返回目录](./README.md)
## 组织 CRUD
| 方法 | 路径 | 描述 |
| ------ | ------------------------- | ---------------- |
| POST | `/organizations` | 创建组织 |
| GET | `/organizations` | 获取我的组织列表 |
| GET | `/organizations/:id` | 获取组织详情 |
| PUT | `/organizations/:id` | 更新组织 |
| DELETE | `/organizations/:id` | 删除组织 |
## 成员管理
| 方法 | 路径 | 描述 |
| ------ | --------------------------------------------- | ------------------ |
| POST | `/organizations/join` | 通过邀请码加入组织 |
| POST | `/organizations/join-request` | 提交加入申请 |
| GET | `/organizations/search` | 搜索组织 |
| POST | `/organizations/join-by-id` | 通过组织ID加入 |
| GET | `/organizations/preview/:invite_code` | 预览组织信息 |
| POST | `/organizations/:id/leave` | 离开组织 |
| POST | `/organizations/:id/request-upgrade` | 请求角色升级 |
| POST | `/organizations/:id/invite-code` | 生成邀请码 |
| GET | `/organizations/:id/search-users` | 搜索可邀请用户 |
| POST | `/organizations/:id/invite` | 邀请成员 |
| GET | `/organizations/:id/members` | 获取成员列表 |
| PUT | `/organizations/:id/members/:user_id` | 更新成员角色 |
| DELETE | `/organizations/:id/members/:user_id` | 移除成员 |
## 加入请求
| 方法 | 路径 | 描述 |
| ---- | ------------------------------------------------------- | ---------------- |
| GET | `/organizations/:id/join-requests` | 获取加入请求列表 |
| PUT | `/organizations/:id/join-requests/:request_id/review` | 审核加入请求 |
## 知识库共享
| 方法 | 路径 | 描述 |
| ------ | --------------------------------------------- | ---------------- |
| POST | `/knowledge-bases/:id/shares` | 共享知识库 |
| GET | `/knowledge-bases/:id/shares` | 获取知识库共享列表 |
| PUT | `/knowledge-bases/:id/shares/:share_id` | 更新共享权限 |
| DELETE | `/knowledge-bases/:id/shares/:share_id` | 取消知识库共享 |
## 智能体共享
| 方法 | 路径 | 描述 |
| ------ | --------------------------------------- | ---------------- |
| POST | `/agents/:id/shares` | 共享智能体 |
| GET | `/agents/:id/shares` | 获取智能体共享列表 |
| DELETE | `/agents/:id/shares/:share_id` | 取消智能体共享 |
## 共享资源
| 方法 | 路径 | 描述 |
| ---- | --------------------------- | ------------------ |
| GET | `/shared-knowledge-bases` | 获取共享知识库列表 |
| GET | `/shared-agents` | 获取共享智能体列表 |
---
## POST `/organizations` - 创建组织
**请求参数**:
- `name`: 组织名称（必填）
- `description`: 组织描述（可选）
- `avatar`: 组织头像 URL（可选）
- `invite_code_validity_days`: 邀请码有效天数（可选）
- `member_limit`: 成员上限（可选）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "AI 技术团队",
"description": "专注于 AI 技术研究与知识管理",
"invite_code_validity_days": 7,
"member_limit": 50
}'
```
**响应**:
```json
{
"data": {
"id": "org-00000001",
"name": "AI 技术团队",
"description": "专注于 AI 技术研究与知识管理",
"avatar": "",
"owner_id": "user-00000001",
"invite_code": "",
"invite_code_validity_days": 7,
"require_approval": false,
"searchable": false,
"member_limit": 50,
"member_count": 1,
"share_count": 0,
"agent_share_count": 0,
"pending_join_request_count": 0,
"is_owner": true,
"my_role": "owner",
"has_pending_upgrade": false,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
},
"success": true
}
```
## GET `/organizations` - 获取我的组织列表
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"organizations": [
{
"id": "org-00000001",
"name": "AI 技术团队",
"description": "专注于 AI 技术研究与知识管理",
"avatar": "",
"owner_id": "user-00000001",
"invite_code_validity_days": 7,
"require_approval": false,
"searchable": false,
"member_limit": 50,
"member_count": 3,
"share_count": 2,
"agent_share_count": 1,
"pending_join_request_count": 0,
"is_owner": true,
"my_role": "owner",
"has_pending_upgrade": false,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
}
]
},
"success": true
}
```
## GET `/organizations/:id` - 获取组织详情
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/org-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"id": "org-00000001",
"name": "AI 技术团队",
"description": "专注于 AI 技术研究与知识管理",
"avatar": "",
"owner_id": "user-00000001",
"invite_code": "ABC123XY",
"invite_code_expires_at": "2025-08-19T10:00:00+08:00",
"invite_code_validity_days": 7,
"require_approval": false,
"searchable": true,
"member_limit": 50,
"member_count": 3,
"share_count": 2,
"agent_share_count": 1,
"pending_join_request_count": 1,
"is_owner": true,
"my_role": "owner",
"has_pending_upgrade": false,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
},
"success": true
}
```
## PUT `/organizations/:id` - 更新组织
**请求参数**（均为可选）:
- `name`: 组织名称
- `description`: 组织描述
- `avatar`: 组织头像 URL
- `require_approval`: 是否需要审核加入
- `searchable`: 是否可被搜索
- `invite_code_validity_days`: 邀请码有效天数
- `member_limit`: 成员上限
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/organizations/org-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"description": "专注于 AI 技术研究与知识管理（更新）",
"require_approval": true,
"searchable": true
}'
```
**响应**:
```json
{
"data": {
"id": "org-00000001",
"name": "AI 技术团队",
"description": "专注于 AI 技术研究与知识管理（更新）",
"avatar": "",
"owner_id": "user-00000001",
"invite_code_validity_days": 7,
"require_approval": true,
"searchable": true,
"member_limit": 50,
"member_count": 3,
"share_count": 2,
"agent_share_count": 1,
"pending_join_request_count": 0,
"is_owner": true,
"my_role": "owner",
"has_pending_upgrade": false,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T12:00:00+08:00"
},
"success": true
}
```
## DELETE `/organizations/:id` - 删除组织
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/organizations/org-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"success": true
}
```
---
## POST `/organizations/join` - 通过邀请码加入组织
**请求参数**:
- `invite_code`: 邀请码（必填）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/join' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"invite_code": "ABC123XY"
}'
```
**响应**:
```json
{
"success": true
}
```
## POST `/organizations/join-request` - 提交加入申请
当组织开启了审核加入（`require_approval: true`）时使用。
**请求参数**:
- `invite_code`: 邀请码（必填）
- `message`: 申请留言（可选）
- `role`: 申请角色（可选）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/join-request' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"invite_code": "ABC123XY",
"message": "希望加入团队参与知识库建设",
"role": "editor"
}'
```
**响应**:
```json
{
"success": true
}
```
## GET `/organizations/search` - 搜索组织
**查询参数**:
- `keyword`: 搜索关键字（可选）
- `page`: 页码（默认 1）
- `page_size`: 每页条数（默认 20）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/search?keyword=AI&page=1&page_size=10' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"organizations": [
{
"id": "org-00000001",
"name": "AI 技术团队",
"description": "专注于 AI 技术研究与知识管理",
"avatar": "",
"owner_id": "user-00000001",
"invite_code_validity_days": 7,
"require_approval": true,
"searchable": true,
"member_limit": 50,
"member_count": 3,
"share_count": 2,
"agent_share_count": 1,
"pending_join_request_count": 0,
"is_owner": false,
"my_role": "",
"has_pending_upgrade": false,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
}
]
},
"success": true
}
```
## POST `/organizations/join-by-id` - 通过组织ID加入
**请求参数**:
- `organization_id`: 组织 ID（必填）
- `message`: 申请留言（可选）
- `role`: 申请角色（可选）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/join-by-id' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"organization_id": "org-00000001",
"message": "希望加入贵团队",
"role": "viewer"
}'
```
**响应**:
```json
{
"success": true
}
```
## GET `/organizations/preview/:invite_code` - 预览组织信息
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/preview/ABC123XY' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"id": "org-00000001",
"name": "AI 技术团队",
"description": "专注于 AI 技术研究与知识管理",
"avatar": "",
"owner_id": "user-00000001",
"invite_code_validity_days": 7,
"require_approval": true,
"searchable": true,
"member_limit": 50,
"member_count": 3,
"share_count": 0,
"agent_share_count": 0,
"pending_join_request_count": 0,
"is_owner": false,
"my_role": "",
"has_pending_upgrade": false,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
},
"success": true
}
```
## POST `/organizations/:id/leave` - 离开组织
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/organizations/org-00000001/leave' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"success": true
}
```
## POST `/organizations/:id/request-upgrade` - 请求角色升级
**请求参数**:
- `requested_role`: 期望角色（必填）
- `message`: 申请理由（可选）
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/organizations/org-00000001/request-upgrade' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"requested_role": "admin",
"message": "需要管理员权限来管理知识库共享"
}'
```
**响应**:
```json
{
"success": true
}
```
## POST `/organizations/:id/invite-code` - 生成邀请码
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/organizations/org-00000001/invite-code' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"invite_code": "NEW1CODE"
},
"success": true
}
```
## GET `/organizations/:id/search-users` - 搜索可邀请用户
**查询参数**:
- `keyword`: 用户名或邮箱关键字（可选）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/search-users?keyword=zhang' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"id": "user-00000002",
"username": "zhangsan",
"email": "zhangsan@example.com"
},
{
"id": "user-00000003",
"username": "zhangwei",
"email": "zhangwei@example.com"
}
],
"success": true
}
```
## POST `/organizations/:id/invite` - 邀请成员
**请求参数**:
- `user_id`: 用户 ID（必填）
- `role`: 角色（必填）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/invite' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"user_id": "user-00000002",
"role": "editor"
}'
```
**响应**:
```json
{
"success": true
}
```
## GET `/organizations/:id/members` - 获取成员列表
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/members' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"members": [
{
"id": "mem-00000001",
"user_id": "user-00000001",
"username": "admin",
"email": "admin@example.com",
"avatar": "",
"role": "owner",
"tenant_id": 1,
"joined_at": "2025-08-12T10:00:00+08:00"
},
{
"id": "mem-00000002",
"user_id": "user-00000002",
"username": "zhangsan",
"email": "zhangsan@example.com",
"avatar": "",
"role": "editor",
"tenant_id": 2,
"joined_at": "2025-08-13T09:00:00+08:00"
}
]
},
"success": true
}
```
## PUT `/organizations/:id/members/:user_id` - 更新成员角色
**请求参数**:
- `role`: 新角色（必填）
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/organizations/org-00000001/members/user-00000002' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"role": "admin"
}'
```
**响应**:
```json
{
"success": true
}
```
## DELETE `/organizations/:id/members/:user_id` - 移除成员
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/organizations/org-00000001/members/user-00000002' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"success": true
}
```
---
## GET `/organizations/:id/join-requests` - 获取加入请求列表
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/join-requests' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"requests": [
{
"id": "jr-00000001",
"user_id": "user-00000003",
"username": "zhangwei",
"email": "zhangwei@example.com",
"message": "希望加入团队参与知识库建设",
"request_type": "join",
"prev_role": "",
"requested_role": "editor",
"status": "pending",
"created_at": "2025-08-14T10:00:00+08:00"
}
]
},
"success": true
}
```
## PUT `/organizations/:id/join-requests/:request_id/review` - 审核加入请求
**请求参数**:
- `approved`: 是否批准（必填，布尔值）
- `message`: 审核留言（可选）
- `role`: 分配角色（可选，批准时生效）
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/organizations/org-00000001/join-requests/jr-00000001/review' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"approved": true,
"message": "欢迎加入",
"role": "editor"
}'
```
**响应**:
```json
{
"success": true
}
```
---
## POST `/knowledge-bases/:id/shares` - 共享知识库
**请求参数**:
- `organization_id`: 目标组织 ID（必填）
- `permission`: 权限级别（必填）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/shares' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"organization_id": "org-00000001",
"permission": "read"
}'
```
**响应**:
```json
{
"data": {
"id": "kbs-00000001",
"knowledge_base_id": "kb-00000001",
"knowledge_base_name": "技术文档库",
"organization_id": "org-00000001",
"organization_name": "AI 技术团队",
"shared_by_user_id": "user-00000001",
"shared_by_username": "admin",
"source_tenant_id": 1,
"permission": "read",
"my_role_in_org": "owner",
"my_permission": "read",
"created_at": "2025-08-15T10:00:00+08:00"
},
"success": true
}
```
## GET `/knowledge-bases/:id/shares` - 获取知识库共享列表
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/shares' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"shares": [
{
"id": "kbs-00000001",
"knowledge_base_id": "kb-00000001",
"knowledge_base_name": "技术文档库",
"organization_id": "org-00000001",
"organization_name": "AI 技术团队",
"shared_by_user_id": "user-00000001",
"shared_by_username": "admin",
"source_tenant_id": 1,
"permission": "read",
"my_role_in_org": "owner",
"my_permission": "read",
"created_at": "2025-08-15T10:00:00+08:00"
}
]
},
"success": true
}
```
## PUT `/knowledge-bases/:id/shares/:share_id` - 更新共享权限
**请求参数**:
- `permission`: 新权限级别（必填）
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/shares/kbs-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"permission": "write"
}'
```
**响应**:
```json
{
"success": true
}
```
## DELETE `/knowledge-bases/:id/shares/:share_id` - 取消知识库共享
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/shares/kbs-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"success": true
}
```
---
## POST `/agents/:id/shares` - 共享智能体
**请求参数**:
- `organization_id`: 目标组织 ID（必填）
- `permission`: 权限级别（必填）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/agents/agent-00000001/shares' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"organization_id": "org-00000001",
"permission": "read"
}'
```
**响应**:
```json
{
"data": {
"id": "as-00000001",
"agent_id": "agent-00000001",
"agent_name": "智能客服助手",
"organization_id": "org-00000001",
"organization_name": "AI 技术团队",
"shared_by_user_id": "user-00000001",
"shared_by_username": "admin",
"source_tenant_id": 1,
"permission": "read",
"created_at": "2025-08-15T11:00:00+08:00"
},
"success": true
}
```
## GET `/agents/:id/shares` - 获取智能体共享列表
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/agents/agent-00000001/shares' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"shares": [
{
"id": "as-00000001",
"agent_id": "agent-00000001",
"agent_name": "智能客服助手",
"organization_id": "org-00000001",
"organization_name": "AI 技术团队",
"shared_by_user_id": "user-00000001",
"shared_by_username": "admin",
"source_tenant_id": 1,
"permission": "read",
"created_at": "2025-08-15T11:00:00+08:00"
}
]
},
"success": true
}
```
## DELETE `/agents/:id/shares/:share_id` - 取消智能体共享
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/agents/agent-00000001/shares/as-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"success": true
}
```
---
## GET `/shared-knowledge-bases` - 获取共享知识库列表
获取当前用户通过组织共享获得的所有知识库。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/shared-knowledge-bases' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"share_id": "kbs-00000001",
"organization_id": "org-00000001",
"org_name": "AI 技术团队",
"permission": "read",
"source_tenant_id": 1,
"shared_at": "2025-08-15T10:00:00+08:00"
}
],
"success": true
}
```
## GET `/shared-agents` - 获取共享智能体列表
获取当前用户通过组织共享获得的所有智能体。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/shared-agents' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"share_id": "as-00000001",
"organization_id": "org-00000001",
"org_name": "AI 技术团队",
"permission": "read",
"source_tenant_id": 1,
"shared_at": "2025-08-15T11:00:00+08:00"
}
],
"success": true
}
```
Reference in New Issue View Git Blame Copy Permalink