# 墩墩协同系统 API 接口文档 v1.1 > 生成时间：2026-07-01 > 线上域名：https://duncreator.cn > 文档维护：马维斯 --- ## 目录 1. [dun-ai-gateway 统一消息网关](#1-dun-ai-gateway-统一消息网关) 2. [MailRouter 邮件服务](#2-mailrouter-邮件服务) 3. [dun-ai-file 协同文件管理](#3-dun-ai-file-协同文件管理) 4. [错误码说明](#4-错误码说明) --- ## 1. dun-ai-gateway 统一消息网关 - **端口**：3003（内网）→ `https://duncreator.cn/api/gateway/`（外网） - **功能**：统一消息路由，打通飞书/企微/扣子/豆包全渠道 - **部署路径**：`/www/wwwroot/dun-ai-gateway/server.js` - **PM2 管理**：`dun-ai-gateway (id:30)` ### 1.1 统一消息路由 **POST** `/api/gateway/api/message` **说明**：统一消息入口，根据来源渠道自动路由到目标智能体 **请求头**： ``` Content-Type: application/json X-Source: feishu | wecom | coze | doubao ``` **入参示例**： ```json { "target": "huadao", "content": "请帮我分析这个需求的可行性", "context": { "channel": "feishu", "user_id": "ou_xxx" } } ``` **出参结构**： ```json { "code": 0, "msg": "success", "data": { "message_id": "msg_20260701_001", "target": "huadao", "reply": "已完成分析，该需求技术可行...", "timestamp": "2026-07-01T10:00:00Z" } } ``` --- ### 1.2 消息广播 **POST** `/api/gateway/api/broadcast` **说明**：向所有在线成员广播消息 **入参示例**： ```json { "content": "紧急通知：今晚22:00服务器维护，请大家提前保存工作", "priority": "high" } ``` **出参结构**： ```json { "code": 0, "msg": "broadcast sent", "data": { "recipients": 8, "delivered": 8, "broadcast_id": "bc_20260701_001" } } ``` --- ### 1.3 成员管理 **GET** `/api/gateway/api/members` **说明**：获取所有固定协同成员列表 **出参结构**： ```json { "code": 0, "data": { "members": [ {"id": "mavis", "name": "马维斯", "role": "全栈开发"}, {"id": "huadao", "name": "华道", "role": "前端主程"}, {"id": "x8", "name": "小8", "role": "WorkBuddy"}, {"id": "damao", "name": "大猫", "role": "全局管理员"}, {"id": "coze", "name": "扣子智能体", "role": "AI Agent"}, {"id": "dundun", "name": "墩墩AI助手", "role": "AI Agent"}, {"id": "doubao", "name": "豆包API", "role": "AI Engine"} ], "total": 7 } } ``` --- ### 1.4 消息日志查询 **GET** `/api/gateway/api/messages/log?limit=50&offset=0` **说明**：查询消息历史记录 **查询参数**： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | limit | int | 否 | 返回条数，默认 50，最大 200 | | offset | int | 否 | 偏移量，默认 0 | | channel | string | 否 | 按渠道筛选：feishu / wecom / coze / doubao | | target | string | 否 | 按目标成员筛选 | | start_time | string | 否 | 起始时间 ISO 8601 | | end_time | string | 否 | 结束时间 ISO 8601 | **出参结构**： ```json { "code": 0, "data": { "messages": [ { "id": "msg_20260701_001", "source": "feishu", "from": "damao", "to": "mavis", "content": "开始今天的开发任务", "timestamp": "2026-07-01T09:00:00Z" } ], "total": 128, "offset": 0, "limit": 50 } } ``` --- ### 1.5 条件消息查询 **POST** `/api/gateway/api/messages/query` **说明**：高级消息搜索，支持多条件组合 **入参示例**： ```json { "channel": "feishu", "target": "huadao", "keyword": "API文档", "date_range": { "start": "2026-06-25", "end": "2026-07-01" } } ``` **出参结构**：同 1.4 消息日志查询 --- ### 1.6 健康检查 **GET** `/api/gateway/health` **出参示例**： ```json { "status": "ok", "service": "dun-ai-gateway", "version": "1.0.2", "uptime": 86400 } ``` --- ## 2. MailRouter 邮件服务 - **端口**：3102（内网）→ `https://duncreator.cn/api/mail/`（外网） - **功能**：SMTP 邮件收发、分类、抄送同步 - **部署路径**：`/opt/mail-router/mailRouter.js` - **PM2 管理**：`mailrouter (id:31)` - **SMTP 账号**：`aidun@pddtech.cn` ### 2.1 发送邮件 **POST** `/api/mail/mail/send` **入参示例**： ```json { "to": ["huadao@example.com", "x8@example.com"], "cc": ["damao@example.com"], "subject": "API文档已就绪", "body": "三服务API文档已完成，详见附件", "body_type": "html", "attachments": [] } ``` **出参结构**： ```json { "code": 0, "msg": "email sent", "data": { "message_id": "", "accepted": ["huadao@example.com", "x8@example.com"], "timestamp": "2026-07-01T10:00:00Z" } } ``` --- ### 2.2 邮件分类 **POST** `/api/mail/mail/classify` **说明**：按规则自动分类邮件内容 **入参示例**： ```json { "subject": "API文档征求意见稿", "body": "...", "from": "damao@example.com" } ``` **出参结构**： ```json { "code": 0, "data": { "category": "开发文档", "confidence": 0.92, "tags": ["API", "文档", "评审"] } } ``` --- ### 2.3 任务抄送 **POST** `/api/mail/mail/cc` **说明**：将任务执行结果抄送给指定成员 **入参示例**： ```json { "task_id": "task_20260701_001", "task_name": "API文档生成", "result": "success", "cc_to": ["damao@example.com", "huadao@example.com"] } ``` **出参结构**： ```json { "code": 0, "msg": "cc sent", "data": { "cc_count": 2 } } ``` --- ### 2.4 邮件同步 **POST** `/api/mail/mail/sync` **说明**：同步最新邮件到本地 **入参示例**： ```json { "mailbox": "INBOX", "limit": 20 } ``` **出参结构**： ```json { "code": 0, "data": { "synced": 15, "latest_uid": 1024 } } ``` --- ### 2.5 邮箱列表 **GET** `/api/mail/mail/boxes` **出参结构**： ```json { "code": 0, "data": { "boxes": ["INBOX", "Sent", "Drafts", "Trash", "开发文档", "测试报告", "商品素材", "部署日志"] } } ``` --- ### 2.6 健康检查 **GET** `/api/mail/health` **出参示例**： ```json { "status": "ok", "service": "mailrouter", "version": "3.1.0", "uptime": 43200 } ``` --- ## 3. dun-ai-file 协同文件管理 - **端口**：3103（内网）→ `https://duncreator.cn/api/file/`（外网） - **功能**：文件分类 CRUD、全文搜索、统计 - **部署路径**：`/www/wwwroot/dun-ai-file/server.js` - **PM2 管理**：`dun-ai-file (id:29)` - **分类目录**：`/www/wwwroot/dun-ai-file/{dev-docs,test-reports,product-assets,deploy-logs}` ### 3.1 文件上传 **POST** `/api/file/api/files/:category` **路径参数**： | 参数 | 类型 | 说明 | |------|------|------| | category | string | dev-docs / test-reports / product-assets / deploy-logs | **请求格式**：`multipart/form-data` **表单字段**： | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | file | file | 是 | 上传的文件 | | description | string | 否 | 文件描述 | | tags | string | 否 | 逗号分隔的标签 | **出参结构**： ```json { "code": 0, "msg": "uploaded", "data": { "file_id": "f_20260701_001", "filename": "api-doc-v1.1.md", "category": "dev-docs", "size": 12345, "url": "/api/file/api/files/dev-docs/api-doc-v1.1.md", "timestamp": "2026-07-01T10:00:00Z" } } ``` --- ### 3.2 文件列表（按分类） **GET** `/api/file/api/files/:category` **查询参数**： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | limit | int | 否 | 默认 50 | | offset | int | 否 | 默认 0 | | sort | string | 否 | name / date / size，默认 date | **出参结构**： ```json { "code": 0, "data": { "files": [ { "file_id": "f_20260701_001", "filename": "api-doc-v1.1.md", "size": 12345, "timestamp": "2026-07-01T10:00:00Z" } ], "total": 42, "category": "dev-docs" } } ``` --- ### 3.3 文件下载 **GET** `/api/file/api/files/:category/:filename` **出参**：二进制文件流，`Content-Disposition: attachment` --- ### 3.4 文件删除 **DELETE** `/api/file/api/files/:category/:filename` **出参结构**： ```json { "code": 0, "msg": "deleted", "data": { "filename": "obsolete-doc.md", "category": "dev-docs" } } ``` --- ### 3.5 全文搜索 **GET** `/api/file/api/search?q=关键词&category=dev-docs` **查询参数**： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | q | string | 是 | 搜索关键词 | | category | string | 否 | 限定分类，不传则全量搜索 | **出参结构**： ```json { "code": 0, "data": { "results": [ { "file_id": "f_20260701_001", "filename": "api-doc-v1.1.md", "category": "dev-docs", "matches": ["API", "接口", "网关"], "score": 0.89 } ], "total": 3, "query": "API接口" } } ``` --- ### 3.6 统计信息 **GET** `/api/file/api/stats` **出参结构**： ```json { "code": 0, "data": { "total_files": 256, "total_size": "2.4 GB", "by_category": { "dev-docs": {"count": 58, "size": "156 MB"}, "test-reports": {"count": 32, "size": "89 MB"}, "product-assets": {"count": 120, "size": "1.8 GB"}, "deploy-logs": {"count": 46, "size": "312 MB"} } } } ``` --- ### 3.7 健康检查 **GET** `/api/file/health` **出参示例**： ```json { "status": "ok", "service": "dun-ai-file", "version": "1.0.0", "uptime": 129600 } ``` --- ## 4. 错误码说明 | 错误码 | 说明 | 建议处理 | |--------|------|----------| | 0 | 成功 | - | | 1001 | 参数缺失 | 检查必填参数 | | 1002 | 参数格式错误 | 检查参数类型 | | 1003 | 认证失败 | 检查 X-Source 头 | | 2001 | 目标成员不存在 | 检查成员 ID | | 2002 | 消息发送失败 | 重试或检查渠道连通性 | | 3001 | 邮件发送失败 | 检查 SMTP 配置 | | 3002 | 邮箱连接超时 | 检查网络连通性 | | 4001 | 文件不存在 | 检查 file_id 或路径 | | 4002 | 文件上传失败 | 检查文件大小/格式 | | 4003 | 存储空间不足 | 清理后重试 | | 5000 | 内部服务错误 | 查看服务日志 | --- ## 附录 A：线上 API 地址对照表 | 服务 | 内网端口 | 线上地址 | |------|----------|----------| | dun-ai-gateway | 3003 | `https://duncreator.cn/api/gateway/` | | mailrouter | 3102 | `https://duncreator.cn/api/mail/` | | dun-ai-file | 3103 | `https://duncreator.cn/api/file/` | **联调建议**：前端调用线上地址 `https://duncreator.cn/api/gateway/` 等同域接口，无需配置 CORS，直接用于前后端联调。 --- *文档版本：v1.1 | 最后更新：2026-07-01 | 马维斯*