assist/.agents/summary/interfaces.md

Interfaces / 接口与集成

REST API 概览

所有 API 以 /api/ 为前缀，返回 JSON。认证通过 Flask session 或 JWT。

工单 (workorders)

Method	Path	说明
GET	/api/workorders	工单列表（分页）
POST	/api/workorders	创建工单
GET	/api/workorders/<id>	工单详情
PUT	/api/workorders/<id>	更新工单
DELETE	/api/workorders/<id>	删除工单
POST	/api/workorders/ai-suggestion	生成 AI 建议
POST	/api/workorders/import	批量导入

知识库 (knowledge)

Method	Path	说明
GET	/api/knowledge	知识条目列表
POST	/api/knowledge	添加条目
GET	/api/knowledge/search	搜索知识库
GET	/api/knowledge/stats	统计信息
POST	/api/knowledge/upload	文件导入
PUT	/api/knowledge/<id>/verify	验证条目

对话 (chat / conversations)

Method	Path	说明
POST	/api/chat/sessions	创建会话
GET	/api/chat/sessions	活跃会话列表
POST	/api/chat/message	发送消息
POST	/api/chat/message/stream	流式消息 (SSE)
GET	/api/conversations	对话历史

租户 (tenants)

Method	Path	说明
GET	/api/tenants	租户列表
POST	/api/tenants	创建租户
PUT	/api/tenants/<id>	更新租户
DELETE	/api/tenants/<id>	删除租户
GET	/api/tenants/feishu-groups	飞书群列表

认证 (auth)

Method	Path	说明
POST	/api/auth/login	登录
POST	/api/auth/logout	登出
GET	/api/auth/status	认证状态
POST	/api/auth/register	注册

Agent

Method	Path	说明
POST	/api/agent/chat	Agent 对话
GET	/api/agent/status	Agent 状态
POST	/api/agent/tools/execute	执行工具

飞书同步 (feishu-sync)

Method	Path	说明
GET	/api/feishu-sync/status	同步状态
POST	/api/feishu-sync/from-feishu	从飞书拉取
POST	/api/feishu-sync/<id>/to-feishu	推送到飞书
GET/POST	/api/feishu-sync/config	同步配置

WebSocket 接口

• 端口: 8765
• 协议: JSON 消息
• 功能: 实时聊天，客户端连接后通过 JSON 消息与 RealtimeChatManager 交互

外部集成

sequenceDiagram
    participant User as 用户
    participant Feishu as 飞书
    participant LongConn as 飞书长连接服务
    participant DM as DialogueManager
    participant LLM as Qwen API
    participant KB as KnowledgeManager

    User->>Feishu: 发送消息
    Feishu->>LongConn: 事件推送
    LongConn->>DM: 处理消息
    DM->>KB: 知识库检索
    KB-->>DM: 相关知识
    DM->>LLM: 生成回复
    LLM-->>DM: AI 回复
    DM->>Feishu: 回复消息

装饰器接口

装饰器	位置	功能
@handle_errors	decorators.py	统一异常捕获，返回标准错误响应
@require_json(fields)	decorators.py	验证请求体为 JSON 且包含必填字段
@with_service(name)	decorators.py	从 ServiceManager 注入服务实例
@rate_limit(max, period)	decorators.py	基于 IP 的频率限制
@cache_response(timeout)	decorators.py	响应缓存