feat(M5): API集成文档 - 对话接口、知识库管理、Python/Node.js/企微集成示例

docs/api-integration.md

@@ -0,0 +1,385 @@
+# Dify API 集成指南
+
+> 西安云美电子科技有限公司 - 企业知识库
+> 版本：v1.0 | 创建时间：2026-06-06
+
+---
+
+## 1. 概述
+
+Dify 提供完整的 RESTful API，支持将知识库对话能力集成到企业微信、钉钉、自建系统等渠道。本文档涵盖最常用的 API 接口及集成示例。
+
+**Base URL**: `http://<dify-host>/v1`
+
+---
+
+## 2. 认证方式
+
+所有 API 请求需在 Header 中携带 API Key：
+
+```
+Authorization: Bearer app-<your-api-key>
+```
+
+**获取 API Key**：Dify 控制台 → 应用 → API 访问 → 创建 API Key
+
+---
+
+## 3. 对话接口
+
+### 3.1 发送对话消息
+
+```
+POST /v1/chat-messages
+```
+
+**请求参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| query | string | ✅ | 用户输入的问题 |
+| inputs | object | ❌ | 额外输入参数 |
+| response_mode | string | ✅ | `blocking`（阻塞）或 `streaming`（流式） |
+| conversation_id | string | ❌ | 对话 ID，首次对话不传，后续传入上一次返回的 ID |
+| user | string | ✅ | 用户标识 |
+| files | array | ❌ | 上传文件列表 |
+
+**阻塞模式请求示例**
+
+```bash
+curl -X POST 'http://<dify-host>/v1/chat-messages' \
+  -H 'Authorization: Bearer app-<api-key>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": "差旅报销标准是什么？",
+    "inputs": {},
+    "response_mode": "blocking",
+    "user": "zhangsan"
+  }'
+```
+
+**阻塞模式响应**
+
+```json
+{
+  "task_id": "xxx",
+  "message_id": "xxx",
+  "conversation_id": "xxx",
+  "answer": "根据《差旅管理制度》第三章：\n\n1. 住宿标准：一线城市 500 元/晚...\n2. 交通标准：高铁二等座...",
+  "created_at": 1717632000
+}
+```
+
+**流式模式响应（SSE）**
+
+```
+data: {"event": "message", "message_id": "xxx", "conversation_id": "xxx", "answer": "根据", ...}
+data: {"event": "message", "message_id": "xxx", "conversation_id": "xxx", "answer": "根据《", ...}
+data: {"event": "message_end", ...}
+```
+
+### 3.2 获取对话历史
+
+```
+GET /v1/messages?conversation_id=<id>&user=<user>
+```
+
+**响应**
+
+```json
+{
+  "limit": 20,
+  "has_more": false,
+  "data": [
+    {
+      "id": "xxx",
+      "query": "差旅报销标准",
+      "answer": "根据《差旅管理制度》...",
+      "created_at": 1717632000
+    }
+  ]
+}
+```
+
+### 3.3 获取对话列表
+
+```
+GET /v1/conversations?user=<user>&last_id=<id>&limit=20&sort_by=-updated_at
+```
+
+### 3.4 重命名对话
+
+```
+PATCH /v1/conversations/<conversation_id>/name
+```
+
+```json
+{
+  "name": "报销相关问题"
+}
+```
+
+### 3.5 删除对话
+
+```
+DELETE /v1/conversations/<conversation_id>
+```
+
+---
+
+## 4. 知识库管理接口
+
+### 4.1 创建知识库
+
+```
+POST /v1/datasets
+```
+
+```json
+{
+  "name": "KB-RULE-制度流程",
+  "description": "公司各类管理制度和审批流程文档"
+}
+```
+
+### 4.2 获取知识库列表
+
+```
+GET /v1/datasets?page=1&page_size=20
+```
+
+### 4.3 上传文档到知识库
+
+**步骤一：创建上传任务**
+
+```
+POST /v1/datasets/<dataset_id>/document/create-by-file
+Content-Type: multipart/form-data
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| file | file | ✅ | 文档文件（PDF/Word/TXT/Markdown/Excel） |
+| indexing_technique | string | ✅ | `high_quality`（高质量）或 `economy`（经济） |
+| process_rule | object | ❌ | 分段规则 |
+
+**分段规则示例**
+
+```json
+{
+  "mode": "automatic",
+  "rules": {
+    "pre_processing_rules": [
+      {"id": "remove_extra_spaces", "enabled": true},
+      {"id": "remove_urls_emails", "enabled": false}
+    ],
+    "segmentation": {
+      "max_segmentation_tokens_length": 500,
+      "overlap_tokens_length": 50,
+      "separator": ["\n", "\n\n", "。", "！", "？", "；"]
+    }
+  }
+}
+```
+
+**步骤二：查询上传进度**
+
+```
+GET /v1/datasets/<dataset_id>/documents/<document_id>/indexing-status
+```
+
+### 4.4 通过文本创建文档
+
+```
+POST /v1/datasets/<dataset_id>/document/create-by-text
+```
+
+```json
+{
+  "name": "报销流程说明",
+  "text": "## 报销流程\n\n1. 填写报销单...\n2. 部门审批...\n3. 财务审核...",
+  "indexing_technique": "high_quality",
+  "process_rule": {
+    "mode": "automatic"
+  }
+}
+```
+
+### 4.5 获取知识库文档列表
+
+```
+GET /v1/datasets/<dataset_id>/documents?page=1&page_size=20
+```
+
+### 4.6 删除文档
+
+```
+DELETE /v1/datasets/<dataset_id>/documents/<document_id>
+```
+
+---
+
+## 5. 集成示例
+
+### 5.1 Python 集成示例
+
+```python
+import requests
+
+DIFY_BASE_URL = "http://<dify-host>/v1"
+API_KEY = "app-<your-api-key>"
+
+def chat(query: str, user: str = "default", conversation_id: str = None):
+    """发送对话消息"""
+    headers = {
+        "Authorization": f"Bearer {API_KEY}",
+        "Content-Type": "application/json"
+    }
+    data = {
+        "query": query,
+        "inputs": {},
+        "response_mode": "blocking",
+        "user": user,
+    }
+    if conversation_id:
+        data["conversation_id"] = conversation_id
+
+    resp = requests.post(
+        f"{DIFY_BASE_URL}/chat-messages",
+        headers=headers,
+        json=data,
+        timeout=30
+    )
+    result = resp.json()
+    return {
+        "answer": result.get("answer", ""),
+        "conversation_id": result.get("conversation_id", ""),
+        "message_id": result.get("message_id", ""),
+    }
+
+# 使用示例
+result = chat("差旅报销标准是什么？", user="zhangsan")
+print(result["answer"])
+```
+
+### 5.2 企业微信 Webhook 集成
+
+```python
+from flask import Flask, request, jsonify
+import requests
+
+app = Flask(__name__)
+
+DIFY_API_KEY = "app-<your-api-key>"
+DIFY_BASE_URL = "http://<dify-host>/v1"
+
+@app.route("/wecom/webhook", methods=["POST"])
+def wecom_webhook():
+    """企业微信消息回调"""
+    data = request.json
+    user_query = data.get("Content", "")
+    user_id = data.get("FromUserName", "unknown")
+
+    # 调用 Dify API
+    resp = requests.post(
+        f"{DIFY_BASE_URL}/chat-messages",
+        headers={"Authorization": f"Bearer {DIFY_API_KEY}"},
+        json={
+            "query": user_query,
+            "response_mode": "blocking",
+            "user": user_id,
+        },
+        timeout=30
+    )
+    answer = resp.json().get("answer", "暂无回复")
+
+    # 返回企业微信消息格式
+    return jsonify({
+        "msgtype": "text",
+        "text": {"content": answer}
+    })
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=5000)
+```
+
+### 5.3 Node.js 集成示例
+
+```javascript
+const axios = require('axios');
+
+const DIFY_BASE_URL = 'http://<dify-host>/v1';
+const API_KEY = 'app-<your-api-key>';
+
+async function chat(query, user = 'default') {
+  const { data } = await axios.post(
+    `${DIFY_BASE_URL}/chat-messages`,
+    {
+      query,
+      inputs: {},
+      response_mode: 'blocking',
+      user,
+    },
+    {
+      headers: {
+        'Authorization': `Bearer ${API_KEY}`,
+        'Content-Type': 'application/json',
+      },
+      timeout: 30000,
+    }
+  );
+  return {
+    answer: data.answer,
+    conversationId: data.conversation_id,
+  };
+}
+
+// 使用示例
+chat('差旅报销标准是什么？', 'zhangsan')
+  .then(result => console.log(result.answer));
+```
+
+---
+
+## 6. 错误处理
+
+| HTTP 状态码 | 说明 | 处理建议 |
+|:-----------:|------|---------|
+| 400 | 请求参数错误 | 检查请求体格式 |
+| 401 | API Key 无效 | 检查 Authorization Header |
+| 403 | 无权限访问 | 检查 API Key 权限配置 |
+| 429 | 请求频率超限 | 添加请求间隔/重试机制 |
+| 500 | 服务端内部错误 | 查看 Dify 服务日志 |
+
+**建议的重试策略**：
+
+```python
+import time
+
+def chat_with_retry(query, max_retries=3, retry_delay=2):
+    for attempt in range(max_retries):
+        try:
+            return chat(query)
+        except requests.exceptions.Timeout:
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(retry_delay * (attempt + 1))
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 429:
+                time.sleep(retry_delay * (attempt + 1))
+            else:
+                raise
+```
+
+---
+
+## 7. API 速率限制
+
+| 计划类型 | 限制 |
+|----------|------|
+| 自部署版 | 无官方限制，受服务器资源约束 |
+| 建议配置 | 单用户 ≥ 60 次/分钟 |
+
+---
+
+_最后更新: 2026-06-06_

tasks.md

@@ -42,7 +42,7 @@
 
 ## M5: API 集成文档
 
-- [ ] M5.1.1 编写 `docs/api-integration.md`（Dify API 集成指南：对话、知识库管理接口）
+- [x] M5.1.1 编写 `docs/api-integration.md`（Dify API 集成指南：对话、知识库管理接口）
 
 ---