opensource/WeKnora
3
0
Fork 0
mirror of https://github.com/Tencent/WeKnora.git synced 2026-08-31 00:50:02 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
daa9ef500c245e2406bdccf36fd29957ffc24338
WeKnora/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

24 KiB
Raw Blame History

组织管理 API

返回目录

组织 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 --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
}'

响应:

{
    "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 --location 'http://localhost:8080/api/v1/organizations' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/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 --location 'http://localhost:8080/api/v1/organizations/org-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/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 --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
}'

响应:

{
    "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 --location --request DELETE 'http://localhost:8080/api/v1/organizations/org-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'

响应:

{
    "success": true
}

POST /organizations/join - 通过邀请码加入组织

请求参数:

  • invite_code: 邀请码（必填）

请求:

curl --location 'http://localhost:8080/api/v1/organizations/join' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "invite_code": "ABC123XY"
}'

响应:

{
    "success": true
}

POST /organizations/join-request - 提交加入申请

当组织开启了审核加入（require_approval: true）时使用。

请求参数:

  • invite_code: 邀请码（必填）
  • message: 申请留言（可选）
  • role: 申请角色（可选）

请求:

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"
}'

响应:

{
    "success": true
}

GET /organizations/search - 搜索组织

查询参数:

  • keyword: 搜索关键字（可选）
  • page: 页码（默认 1）
  • page_size: 每页条数（默认 20）

请求:

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'

响应:

{
    "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 --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"
}'

响应:

{
    "success": true
}

GET /organizations/preview/:invite_code - 预览组织信息

请求:

curl --location 'http://localhost:8080/api/v1/organizations/preview/ABC123XY' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/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 --location --request POST 'http://localhost:8080/api/v1/organizations/org-00000001/leave' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'

响应:

{
    "success": true
}

POST /organizations/:id/request-upgrade - 请求角色升级

请求参数:

  • requested_role: 期望角色（必填）
  • message: 申请理由（可选）

请求:

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": "需要管理员权限来管理知识库共享"
}'

响应:

{
    "success": true
}

POST /organizations/:id/invite-code - 生成邀请码

请求:

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'

响应:

{
    "data": {
        "invite_code": "NEW1CODE"
    },
    "success": true
}

GET /organizations/:id/search-users - 搜索可邀请用户

查询参数:

  • keyword: 用户名或邮箱关键字（可选）

请求:

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'

响应:

{
    "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 --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"
}'

响应:

{
    "success": true
}

GET /organizations/:id/members - 获取成员列表

请求:

curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/members' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/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 --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"
}'

响应:

{
    "success": true
}

DELETE /organizations/:id/members/:user_id - 移除成员

请求:

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'

响应:

{
    "success": true
}

GET /organizations/:id/join-requests - 获取加入请求列表

请求:

curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/join-requests' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/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 --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"
}'

响应:

{
    "success": true
}

POST /knowledge-bases/:id/shares - 共享知识库

请求参数:

  • organization_id: 目标组织 ID（必填）
  • permission: 权限级别（必填）

请求:

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"
}'

响应:

{
    "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 --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/shares' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/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 --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"
}'

响应:

{
    "success": true
}

DELETE /knowledge-bases/:id/shares/:share_id - 取消知识库共享

请求:

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'

响应:

{
    "success": true
}

POST /agents/:id/shares - 共享智能体

请求参数:

  • organization_id: 目标组织 ID（必填）
  • permission: 权限级别（必填）

请求:

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"
}'

响应:

{
    "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 --location 'http://localhost:8080/api/v1/agents/agent-00000001/shares' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/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 --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'

响应:

{
    "success": true
}

GET /shared-knowledge-bases - 获取共享知识库列表

获取当前用户通过组织共享获得的所有知识库。

请求:

curl --location 'http://localhost:8080/api/v1/shared-knowledge-bases' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/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 --location 'http://localhost:8080/api/v1/shared-agents' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/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