PandaWiki API接口详解：知识管理与文档处理的核心功能

PandaWiki作为一个知识管理平台，提供了丰富的API接口用于文档处理、知识库管理以及对话交互等功能。本文将深入解析其核心API设计和使用方法，帮助开发者更好地理解和集成PandaWiki的功能。

应用管理API

应用更新与删除

PandaWiki提供了完整的应用生命周期管理API：

"/api/v1/app": {
    "put": {
        "summary": "Update app",
        "parameters": [{
            "schema": {
                "$ref": "#/definitions/domain.UpdateAppReq"
            }
        }]
    },
    "delete": {
        "summary": "Delete app",
        "parameters": [{
            "name": "id",
            "description": "app id"
        }]
    }
}

技术要点：

1. 更新操作采用PUT方法，符合RESTful规范
2. 请求体使用JSON格式，包含完整的应用更新信息
3. 删除操作通过查询参数传递应用ID
4. 两种操作都返回标准响应结构，包含操作状态信息

应用详情查询

"/api/v1/app/detail": {
    "get": {
        "parameters": [
            {"name": "kb_id", "description": "kb id"},
            {"name": "type", "description": "app type"}
        ],
        "responses": {
            "schema": {
                "$ref": "#/definitions/domain.AppDetailResp"
            }
        }
    }
}

使用场景：

• 根据知识库ID和应用类型获取特定应用的详细信息
• 返回数据包含应用配置、状态等核心信息
• 常用于前端展示应用详情页面或进行应用配置

对话管理API

对话列表获取

"/api/v1/conversation": {
    "get": {
        "parameters": [
            {"name": "kb_id", "required": true},
            {"name": "page", "minimum": 1},
            {"name": "per_page", "minimum": 1}
        ]
    }
}

功能特点：

1. 支持分页查询，确保大数据量下的性能
2. 可通过知识库ID过滤对话
3. 可选参数包括应用ID、远程IP和主题等
4. 返回结构化的对话列表数据

对话详情查询

"/api/v1/conversation/detail": {
    "get": {
        "parameters": [
            {"name": "X-SafePoint-User-ID", "in": "header"},
            {"name": "id", "description": "conversation id"}
        ]
    }
}

安全设计：

• 要求通过请求头传递用户ID进行身份验证
• 必须提供具体的对话ID
• 返回完整的对话详情，包括消息历史等信息

文档处理API

EPUB文档转换

"/api/v1/crawler/epub/convert": {
    "post": {
        "consumes": ["multipart/form-data"],
        "parameters": [
            {"name": "file", "type": "file"},
            {"name": "kb_id"}
        ]
    }
}

技术实现：

1. 使用multipart/form-data格式上传文件
2. 需要指定目标知识库ID
3. 返回转换结果和状态信息
4. 适用于电子书格式的知识导入

飞书文档集成

PandaWiki提供了完整的飞书文档集成方案：

1. 空间列表获取：列出所有可访问的飞书空间
2. 文档搜索：在指定空间内搜索文档
3. 文档内容获取：获取特定文档的详细内容
4. Wiki搜索：专门针对飞书Wiki内容的搜索

"/api/v1/crawler/feishu/list_spaces": {
    "post": {
        "summary": "FeishuListSpaces"
    }
}

集成优势：

• 完整的OAuth2.0授权流程支持
• 结构化返回飞书文档数据
• 支持批量操作和内容过滤
• 与PandaWiki知识库无缝对接

Notion文档集成

"/api/v1/crawler/notion/get_doc": {
    "post": {
        "summary": "GetDocs"
    }
}

功能特点：

• 支持获取Notion中的文档内容
• 可配置的文档导入选项
• 与PandaWiki的内容模型自动适配

最佳实践建议

1. 错误处理：所有API都返回标准化的错误响应，客户端应统一处理
2. 认证机制：敏感操作需要提供用户ID等认证信息
3. 性能优化：大数据量查询使用分页参数
4. 内容安全：文件上传接口应限制文件类型和大小
5. 异步处理：文档转换等耗时操作可考虑异步实现

通过这套API体系，PandaWiki实现了从文档采集、内容处理到知识应用的完整闭环，为开发者提供了强大的知识管理能力。