feat: FastAPI Swagger/ReDoc API文档 + OpenAPI JSON导出

- 增强 main.py: 26个tag分组+详细描述+调用示例
- 导出 openapi_v3.0.json (11251行, 179个路径)
- /docs (Swagger UI) + /redoc (ReDoc) 可直接测试调用

Made-with: Cursor

sdk/app/main.py

@@ -52,12 +52,78 @@ async def _heartbeat_sweeper():
         await ws_hub.sweep_stale_devices(timeout_seconds=max(settings.WS_TIMEOUT, settings.WS_HEARTBEAT_INTERVAL * 3))
 
 
-# 创建FastAPI应用
+TAGS_METADATA = [
+    {"name": "消息管理", "description": "发送/获取/转发/撤回/名片/语音消息 — 8个端点"},
+    {"name": "好友管理", "description": "添加/通过/备注/删除/搜索/批量 — 8个端点"},
+    {"name": "群聊管理", "description": "创建/邀请/移除/公告/群名/群消息/欢迎语/退群 — 10个端点"},
+    {"name": "标签管理", "description": "创建/删除/打标/取标/查人 — 6个端点"},
+    {"name": "朋友圈管理", "description": "发布/点赞/评论/删除/封面/可见天数/分享链接 — 8个端点"},
+    {"name": "个人设置", "description": "获取资料/昵称/签名/头像/性别/地区 — 6个端点"},
+    {"name": "账号安全", "description": "状态/解封/安全中心/改密码/申诉/限制检查 — 9个端点"},
+    {"name": "收藏管理", "description": "收藏/收藏列表 — 2个端点"},
+    {"name": "支付", "description": "红包/转账/付款码/收款/钱包/账单/领红包 — 7个端点"},
+    {"name": "聊天设置", "description": "置顶/免打扰/清空记录 — 3个端点"},
+    {"name": "小程序", "description": "打开小程序 — 1个端点"},
+    {"name": "公众号", "description": "关注公众号 — 1个端点"},
+    {"name": "视频号", "description": "列表/点赞/评论/关注/分享 — 5个端点"},
+    {"name": "扫一扫", "description": "扫码/加好友/我的二维码/图片识别 — 4个端点"},
+    {"name": "通话", "description": "语音通话/视频通话 — 2个端点"},
+    {"name": "群发助手", "description": "群发消息 — 1个端点"},
+    {"name": "搜一搜", "description": "微信搜一搜 — 1个端点"},
+    {"name": "看一看", "description": "微信看一看 — 1个端点"},
+    {"name": "微信运动", "description": "步数/点赞 — 2个端点"},
+    {"name": "位置", "description": "发送位置/共享实时位置 — 2个端点"},
+    {"name": "表情", "description": "发送表情/表情包列表 — 2个端点"},
+    {"name": "文件管理", "description": "发送文件/下载文件 — 2个端点"},
+    {"name": "设置", "description": "勿扰/清缓存/检查更新/退出/切换账号 — 5个端点"},
+    {"name": "设备管理", "description": "设备列表/状态/截图/ADB控制"},
+    {"name": "AI Agent", "description": "自然语言控制手机"},
+    {"name": "防封监控", "description": "操作频率/内容/账号生命周期 — 2个端点"},
+]
+
 app = FastAPI(
-    title="工作手机SDK v3.0",
-    description="存客宝的AI手机控制引擎 - 支持微信/抖音/小红书等任意APP",
+    title="机擎 v3.0 · 工作手机SDK API",
+    description="""
+## 工作手机SDK — 微信全功能控制接口
+
+通过 ADB UI 自动化后端静默控制 Android 手机上的微信，**无需 Root**。
+
+### 核心能力
+- **98 个 API 端点**，覆盖微信全部功能
+- **96 个引擎方法**（WeChatADBEngine）
+- **23 个功能模块**（消息/好友/群聊/支付/解封/视频号/扫一扫...）
+- **导航缓存系统**：首次录制坐标，后续免 UI dump
+- **操作日志**：每次操作自动记录步骤/耗时/结果
+- **容错机制**：自动重试 3 次 + 状态恢复
+
+### 支持设备
+- Redmi Note 13 5G (Android 13, 1080×2400)
+- 微信 8.0.56
+
+### 调用方式
+```
+POST http://{服务器IP}:8899/api/v3/message/send
+Content-Type: application/json
+
+{
+  "device_id": "xgfe65eimrrofyws",
+  "platform": "wechat",
+  "to_id": "好友昵称",
+  "content": "你好"
+}
+```
+
+### 公共参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| device_id | string | ✅ | ADB 设备序列号 |
+| platform | string | ✅ | 固定 `wechat` |
+""",
     version="3.0.0",
     lifespan=lifespan,
+    openapi_tags=TAGS_METADATA,
+    docs_url="/docs",
+    redoc_url="/redoc",
 )
 
 # CORS配置