{
 "ok": true,
 "name": "创雪 API",
 "version": "1.0",
 "base": "https://snowfure.com/api",
 "entrypoints": {
  "manifest": "https://snowfure.com/api/v1/manifest",
  "llms": "https://snowfure.com/llms.txt",
  "console": "https://snowfure.com/admin/#/api/api",
  "chat": "https://snowfure.com/chat/"
 },
 "auth": {
  "how": "密钥三选一：查询串 ?key=… / 请求头 Authorization: Bearer … / X-API-Key: …",
  "kinds": [
   {
    "kind": "master",
    "ident": "owner",
    "desc": "主密钥（曾健本人，全权限，可颁发）",
    "where": "本机 ~/.hermes/.snowfure_live_key；控制台「接口 · 密钥」页可签发 sk_ 派生密钥"
   },
   {
    "kind": "issued",
    "ident": "apikey:<名字>",
    "desc": "已颁发的 sk_… 密钥，按 scopes 限权",
    "scopes": [
     "chat",
     "im",
     "docs",
     "admin"
    ]
   },
   {
    "kind": "sso",
    "ident": "<open_id>",
    "desc": "飞书 SSO 令牌（?t=… 换来的会话令牌），只能看自己的数据"
   }
  ],
  "self_check": "GET /api/v1/whoami → {\"ok\":true,\"ident\":\"…\",\"name\":\"…\"}"
 },
 "call": {
  "encoding": "UTF-8；POST 载荷 application/json；二进制（附件/语音）走 base64 字段",
  "cors": "Access-Control-Allow-Origin: *（浏览器可直连）",
  "paths": "下面 path 已含 /api 前缀；`$KEY` 换成你的密钥",
  "idempotency": "IM 发送带 client_msg_id 去重；对话可复用 conversation_id 续上下文"
 },
 "sse": {
  "endpoint": "POST /api/chat/stream",
  "content_type": "text/event-stream",
  "frame_format": "每帧一行 `data: <json>`，帧间空行",
  "events": [
   {
    "frame": "{\"snowfure\":{\"conversation_id\":\"…\",\"recall\":{…}}}",
    "when": "首帧：会话 id + 本轮召回统计（记忆/本体命中数）"
   },
   {
    "frame": "{\"choices\":[{\"delta\":{\"content\":\"字\"}}]}",
    "when": "逐字增量：把 content 依次拼接"
   },
   {
    "frame": "{\"choices\":[{\"finish_reason\":\"stop\"}],\"usage\":{…}}",
    "when": "收尾帧（可能带 usage 用量）"
   },
   {
    "frame": "[DONE]",
    "when": "流结束，客户端收到即停止读取"
   }
  ],
  "tips": [
   "用 SSE 客户端逐行读 data:；遇 [DONE] 关闭连接",
   "首帧的 conversation_id 存下来，下次带上它就续上下文",
   "断线重连不会重复计费：重发同一 conversation_id 即可"
  ]
 },
 "errors": [
  {
   "http": 401,
   "code": "UNAUTHORIZED",
   "when": "缺密钥 / 密钥错 / 已吊销"
  },
  {
   "http": 403,
   "code": "FORBIDDEN",
   "when": "身份没有该范围的数据权限"
  },
  {
   "http": 403,
   "code": "DEMO_DENIED",
   "when": "演示身份调用了本地数据接口（只放开模型对话与网络数据）"
  },
  {
   "http": 404,
   "code": "NOT_FOUND",
   "when": "对象不存在（会话/草稿/本体对象…）"
  },
  {
   "http": 400,
   "code": "BAD_ACTION",
   "when": "action 参数不认识"
  },
  {
   "http": 500,
   "code": "SAVE_FAIL / UPLOAD_FAIL / ASR_FAIL / MCP_FAIL / ARTS_FAIL",
   "when": "对应模块内部错误，error 字段有原因"
  }
 ],
 "agent_steps": [
  "1) 拿密钥：控制台 https://snowfure.com/admin/#/api/keys 签发 sk_…（或用已有主密钥）",
  "2) 自检：GET /api/v1/whoami?key=$KEY 确认身份",
  "3) 拿模型/智能体：GET /api/chat/agents（智能体清单）；模型名直接用 deepseek-flash / glm-5.3-flash 等网关型号",
  "4) 对话：POST /api/chat/stream（SSE）或 POST /api/chat/run（一次拿完）",
  "5) 产物/资料：GET /api/chat/arts、/api/chat/conversations、/api/chat/drafts",
  "6) 本体事实：GET /api/chat/onto、/api/chat/onto/graph、POST /api/chat/onto/query（SPARQL）",
  "7) 语音/文件：POST /api/chat/asr、/api/chat/upload",
  "8) 别把密钥写进代码：从环境变量读，例 export KEY=sk_…"
 ],
 "endpoints": [
  {
   "name": "chat_stream",
   "desc": "流式对话（SSE 逐字返回）",
   "method": "POST",
   "path": "/api/chat/stream",
   "url": "https://snowfure.com/api/chat/stream",
   "scope": "chat",
   "args": "model, messages",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/stream?key=$KEY' -H 'Content-Type: application/json' -d '{\"model\": \"glm-5.3\", \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}], \"conversation_id\": \"\", \"recall\": {\"mode\": \"auto\", \"layers\": [\"essence\", \"summary\"]}}'",
   "body_example": {
    "model": "glm-5.3",
    "messages": [
     {
      "role": "user",
      "content": "你好"
     }
    ],
    "conversation_id": "",
    "recall": {
     "mode": "auto",
     "layers": [
      "essence",
      "summary"
     ]
    }
   },
   "returns": "SSE 流（帧格式见 manifest.sse）"
  },
  {
   "name": "chat_run",
   "desc": "一次性问答（非流式）",
   "method": "POST",
   "path": "/api/chat/run",
   "url": "https://snowfure.com/api/chat/run",
   "scope": "chat",
   "args": "model, messages",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/run?key=$KEY' -H 'Content-Type: application/json' -d '{\"model\": \"glm-5.3\", \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}]}'",
   "body_example": {
    "model": "glm-5.3",
    "messages": [
     {
      "role": "user",
      "content": "你好"
     }
    ]
   },
   "returns": "{\"ok\":true,\"reply\":\"…\"}"
  },
  {
   "name": "list_conversations",
   "desc": "查 · 列出会话（按最近更新倒序，带 id/标题/模型/时间）",
   "method": "GET",
   "path": "/api/chat/conversations",
   "url": "https://snowfure.com/api/chat/conversations",
   "scope": "chat",
   "args": "limit?",
   "curl": "curl -s 'https://snowfure.com/api/chat/conversations?key=$KEY&limit=…'"
  },
  {
   "name": "get_conversation",
   "desc": "查 · 读一个会话的全部消息（含角色/内容/时间）",
   "method": "GET",
   "path": "/api/chat/conversation",
   "url": "https://snowfure.com/api/chat/conversation",
   "scope": "chat",
   "args": "id",
   "curl": "curl -s 'https://snowfure.com/api/chat/conversation?key=$KEY&id=…'"
  },
  {
   "name": "create_conversation",
   "desc": "增 · 新建空会话（返回新会话 id，可先起标题）",
   "method": "POST",
   "path": "/api/chat/conversations",
   "url": "https://snowfure.com/api/chat/conversations",
   "scope": "chat",
   "args": "title?, model?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/conversations?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "rename_conversation",
   "desc": "改 · 重命名会话标题（最长 60 字）",
   "method": "POST",
   "path": "/api/chat/rename",
   "url": "https://snowfure.com/api/chat/rename",
   "scope": "chat",
   "args": "id, title",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/rename?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "delete_conversation",
   "desc": "删 · 删除会话（软删除，可在回收站恢复）",
   "method": "DELETE",
   "path": "/api/chat/conversation",
   "url": "https://snowfure.com/api/chat/conversation",
   "scope": "chat",
   "args": "id",
   "curl": "curl -s 'https://snowfure.com/api/chat/conversation?key=$KEY&id=…'"
  },
  {
   "name": "delete_conversations",
   "desc": "删 · 批量删除多个会话（软删除，可回滚）",
   "method": "POST",
   "path": "/api/chat/conversations/delete",
   "url": "https://snowfure.com/api/chat/conversations/delete",
   "scope": "chat",
   "args": "ids（数组或逗号分隔，最多 200 个）",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/conversations/delete?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "extract_insights",
   "desc": "洞察 · 从多个会话原文里提取事实/决策/方法/待办/金句（异步：返回 job_id）",
   "method": "POST",
   "path": "/api/chat/insights",
   "url": "https://snowfure.com/api/chat/insights",
   "scope": "chat",
   "args": "ids（数组或逗号串）, prompt?（额外要求）",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/insights?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "insight_result",
   "desc": "查 · 取洞察提取结果（轮询，模型要跑 40-90 秒）",
   "method": "GET",
   "path": "/api/chat/insights/result",
   "url": "https://snowfure.com/api/chat/insights/result",
   "scope": "chat",
   "args": "job_id",
   "curl": "curl -s 'https://snowfure.com/api/chat/insights/result?key=$KEY&job_id=…'"
  },
  {
   "name": "list_deleted_conversations",
   "desc": "查 · 回收站：列出被删的会话（可恢复）",
   "method": "GET",
   "path": "/api/chat/conversations/trash",
   "url": "https://snowfure.com/api/chat/conversations/trash",
   "scope": "chat",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/chat/conversations/trash?key=$KEY'"
  },
  {
   "name": "restore_conversations",
   "desc": "改 · 从回收站恢复会话（回滚误删）",
   "method": "POST",
   "path": "/api/chat/conversations/restore",
   "url": "https://snowfure.com/api/chat/conversations/restore",
   "scope": "chat",
   "args": "ids",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/conversations/restore?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "purge_conversations",
   "desc": "彻底清除（仅回收站内，不可恢复）",
   "method": "POST",
   "path": "/api/chat/conversations/purge",
   "url": "https://snowfure.com/api/chat/conversations/purge",
   "scope": "chat",
   "args": "ids",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/conversations/purge?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "create_task",
   "desc": "增 · 新建提醒/推送任务（一次性 / 每天 / 每 N 分钟）",
   "method": "POST",
   "path": "/api/chat/tasks",
   "url": "https://snowfure.com/api/chat/tasks",
   "scope": "chat",
   "args": "action=add, title, body, mode, at_time, repeat, channel",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/tasks?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "delete_task",
   "desc": "删 · 删除任务",
   "method": "POST",
   "path": "/api/chat/tasks",
   "url": "https://snowfure.com/api/chat/tasks",
   "scope": "chat",
   "args": "action=delete, id",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/tasks?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "task_runs",
   "desc": "查 · 执行记录（每次投递的通道与回执）",
   "method": "GET",
   "path": "/api/chat/task/runs",
   "url": "https://snowfure.com/api/chat/task/runs",
   "scope": "chat",
   "args": "limit?",
   "curl": "curl -s 'https://snowfure.com/api/chat/task/runs?key=$KEY&limit=…'"
  },
  {
   "name": "list_im_tasks",
   "desc": "查 · 列曾健的任务（带编号 T1/T2…、进行中/已完成状态）",
   "method": "GET",
   "path": "/api/im/convos",
   "url": "https://snowfure.com/api/im/convos",
   "scope": "im",
   "args": "kind（固定 group，不用传）",
   "curl": "curl -s 'https://snowfure.com/api/im/convos?key=$KEY&kind（固定=…'"
  },
  {
   "name": "complete_task",
   "desc": "改 · 把任务标记为已完成（task 传编号如 T3，或会话 id）",
   "method": "POST",
   "path": "/api/im/convo/done",
   "url": "https://snowfure.com/api/im/convo/done",
   "scope": "im",
   "args": "task, done=1",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/convo/done?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "reopen_task",
   "desc": "改 · 重新打开已完成的任务（task 传编号如 T3，或会话 id）",
   "method": "POST",
   "path": "/api/im/convo/done",
   "url": "https://snowfure.com/api/im/convo/done",
   "scope": "im",
   "args": "task, done=0",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/convo/done?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "read_im_task",
   "desc": "查 · 读一个任务里的消息记录（谁说了什么）",
   "method": "GET",
   "path": "/api/im/messages",
   "url": "https://snowfure.com/api/im/messages",
   "scope": "im",
   "args": "conv, before?",
   "curl": "curl -s 'https://snowfure.com/api/im/messages?key=$KEY&conv=…'"
  },
  {
   "name": "send_im_task",
   "desc": "增 · 往任务里发一条消息（@ 谁谁回）",
   "method": "POST",
   "path": "/api/im/send",
   "url": "https://snowfure.com/api/im/send",
   "scope": "im",
   "args": "conv, text",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/send?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "rename_im_task",
   "desc": "改 · 重命名任务",
   "method": "POST",
   "path": "/api/im/convo/rename",
   "url": "https://snowfure.com/api/im/convo/rename",
   "scope": "im",
   "args": "id, title",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/convo/rename?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "delete_im_task",
   "desc": "删 · 删除任务",
   "method": "POST",
   "path": "/api/im/convo/delete",
   "url": "https://snowfure.com/api/im/convo/delete",
   "scope": "im",
   "args": "id",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/convo/delete?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "web_search",
   "desc": "查 · 联网搜索（Bing）拿标题/网址/摘要",
   "method": "GET",
   "path": "/api/kb/web_search",
   "url": "https://snowfure.com/api/kb/web_search",
   "scope": "docs",
   "args": "q, n?",
   "curl": "curl -s 'https://snowfure.com/api/kb/web_search?key=$KEY&q=…'"
  },
  {
   "name": "import_url",
   "desc": "改 · 抓网页正文入库（自动跑流水线+图谱）",
   "method": "POST",
   "path": "/api/kb/import_url",
   "url": "https://snowfure.com/api/kb/import_url",
   "scope": "docs",
   "args": "url, title?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/kb/import_url?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "web_pipeline",
   "desc": "改 · 联网搜索并抓前 N 篇自动入库（知识采集一条龙）",
   "method": "POST",
   "path": "/api/kb/web_pipeline",
   "url": "https://snowfure.com/api/kb/web_pipeline",
   "scope": "docs",
   "args": "q, n?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/kb/web_pipeline?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "kb_search",
   "desc": "查 · 知识库检索（上传入库的 PDF / Word / 表格 / 网页内容）",
   "method": "GET",
   "path": "/api/kb/search",
   "url": "https://snowfure.com/api/kb/search",
   "scope": "docs",
   "args": "q, limit?",
   "curl": "curl -s 'https://snowfure.com/api/kb/search?key=$KEY&q=…'"
  },
  {
   "name": "kb_list",
   "desc": "查 · 知识库文档清单",
   "method": "GET",
   "path": "/api/kb/docs",
   "url": "https://snowfure.com/api/kb/docs",
   "scope": "docs",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/kb/docs?key=$KEY'"
  },
  {
   "name": "list_arts",
   "desc": "汇总全部制品（图/文档）",
   "method": "GET",
   "path": "/api/chat/arts",
   "url": "https://snowfure.com/api/chat/arts",
   "scope": "chat",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/chat/arts?key=$KEY'"
  },
  {
   "name": "list_memories",
   "desc": "查 · 记忆列表（按 layer/domain/status/q 过滤；分层 SQL 下推，counts 与 items 严格同源）",
   "method": "GET",
   "path": "/api/chat/memories",
   "url": "https://snowfure.com/api/chat/memories",
   "scope": "chat",
   "args": "status?, layer?, domain?, q?, page?, page_size?",
   "curl": "curl -s 'https://snowfure.com/api/chat/memories?key=$KEY&status=…'",
   "returns": "{\"ok\":true,\"items\":[…],\"counts\":{\"approved\":20,\"belief\":1,\"fact\":16,…},\"layers\":[…],\"total\":20}"
  },
  {
   "name": "ingest_memory",
   "desc": "改 · 多模态记忆入库（PDF/图片/URL → 网盘 + 记忆双轨；skip_summary=true 时跳过 LLM 解读）",
   "method": "POST",
   "path": "/api/chat/memories/ingest",
   "url": "https://snowfure.com/api/chat/memories/ingest",
   "scope": "chat",
   "args": "type, data|url, filename?, domain?, layer?, instruction?, skip_summary?, remark?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/memories/ingest?key=$KEY' -H 'Content-Type: application/json' -d '{\"type\": \"url\", \"url\": \"https://mp.weixin.qq.com/s/xxx\", \"domain\": \"work\", \"layer\": \"summary\"}'",
   "body_example": {
    "type": "url",
    "url": "https://mp.weixin.qq.com/s/xxx",
    "domain": "work",
    "layer": "summary"
   },
   "returns": "{\"ok\":true,\"memory_id\":\"mc65ecf8f3cce\",\"drive_file_id\":\"dr_515af9cd5031475d\",\"drive_file_url\":\"/api/drive/file?id=dr_515af9cd5031475d\",\"layer\":\"summary\",\"extracted_chars\":2287}"
  },
  {
   "name": "batch_memories",
   "desc": "改 · 记忆批量操作（approve/reject/delete/layer 支持 ids[] 数组，单 id 兼容）",
   "method": "POST",
   "path": "/api/chat/memories",
   "url": "https://snowfure.com/api/chat/memories",
   "scope": "chat",
   "args": "action, ids[]|id, layer?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/memories?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "memory_conflicts",
   "desc": "查 · 同线索「前后说法不一」扫描（创雪 App 冲突提示的服务端口径）",
   "method": "POST",
   "path": "/api/chat/memories",
   "url": "https://snowfure.com/api/chat/memories",
   "scope": "chat",
   "args": "action=conflicts",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/memories?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "thing_ops",
   "desc": "事 · 创雪 App「做到」的五步流程（说清/方案/执行/交付/沉淀；add/list/update/delete）",
   "method": "POST",
   "path": "/api/chat/things",
   "url": "https://snowfure.com/api/chat/things",
   "scope": "chat",
   "args": "action, id?, thread?, title?, said?, way?, by?, stage?, steps?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/things?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "way_ops",
   "desc": "做法 · 可复用配方 = 做法市场（内置种子 + 用户沉淀；list/add/update/use）",
   "method": "POST",
   "path": "/api/chat/ways",
   "url": "https://snowfure.com/api/chat/ways",
   "scope": "chat",
   "args": "action, id?, q?, cat?, name?, steps?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/ways?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "list_drive_files",
   "desc": "查 · 开发者网盘文件清单（按 owner 隔离）",
   "method": "GET",
   "path": "/api/drive/files",
   "url": "https://snowfure.com/api/drive/files",
   "scope": "docs",
   "args": "category?, q?, limit?, offset?, parent_id?",
   "curl": "curl -s 'https://snowfure.com/api/drive/files?key=$KEY&category=…'",
   "returns": "{\"ok\":true,\"files\":[…]}"
  },
  {
   "name": "list_drive_folders",
   "desc": "查 · 网盘文件夹树（移动/整理用）",
   "method": "GET",
   "path": "/api/drive/folders",
   "url": "https://snowfure.com/api/drive/folders",
   "scope": "docs",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/drive/folders?key=$KEY'"
  },
  {
   "name": "get_drive_file",
   "desc": "查 · 网盘文件（raw=1 流式预览 / download=1 触发下载）",
   "method": "GET",
   "path": "/api/drive/file",
   "url": "https://snowfure.com/api/drive/file",
   "scope": "docs",
   "args": "id, raw?, download?",
   "curl": "curl -s 'https://snowfure.com/api/drive/file?key=$KEY&id=…'",
   "returns": "元数据 / raw=1 时直接流式返回文件二进制 / download=1 时附 Content-Disposition"
  },
  {
   "name": "upload_drive_stream",
   "desc": "改 · 大文件流式上传（body=原始字节，Content-Length 必须；不进内存，支持 GB 级视频）",
   "method": "POST",
   "path": "/api/drive/upload_stream",
   "url": "https://snowfure.com/api/drive/upload_stream",
   "scope": "docs",
   "args": "name, mime, parent_id?（query），body=二进制",
   "curl": "curl -s -X POST 'https://snowfure.com/api/drive/upload_stream?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "move_drive_item",
   "desc": "改 · 移动文件/文件夹（防环校验：不能移到自己的子孙里）",
   "method": "POST",
   "path": "/api/drive/move",
   "url": "https://snowfure.com/api/drive/move",
   "scope": "docs",
   "args": "id, target_parent_id",
   "curl": "curl -s -X POST 'https://snowfure.com/api/drive/move?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "rename_drive_item",
   "desc": "改 · 重命名文件/文件夹",
   "method": "POST",
   "path": "/api/drive/rename",
   "url": "https://snowfure.com/api/drive/rename",
   "scope": "docs",
   "args": "id, name",
   "curl": "curl -s -X POST 'https://snowfure.com/api/drive/rename?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "list_agents",
   "desc": "智能体清单",
   "method": "GET",
   "path": "/api/chat/agents",
   "url": "https://snowfure.com/api/chat/agents",
   "scope": "chat",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/chat/agents?key=$KEY'"
  },
  {
   "name": "get_sop",
   "desc": "读取 SOP 流程",
   "method": "GET",
   "path": "/api/chat/sop",
   "url": "https://snowfure.com/api/chat/sop",
   "scope": "chat",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/chat/sop?key=$KEY'"
  },
  {
   "name": "onto_schema",
   "desc": "本体对象类型（W3C 类层次+属性）",
   "method": "GET",
   "path": "/api/chat/onto/schema",
   "url": "https://snowfure.com/api/chat/onto/schema",
   "scope": "chat",
   "args": "scope?",
   "curl": "curl -s 'https://snowfure.com/api/chat/onto/schema?key=$KEY&scope=…'"
  },
  {
   "name": "onto_graph",
   "desc": "本体对象子图（节点+关系）",
   "method": "GET",
   "path": "/api/chat/onto/graph",
   "url": "https://snowfure.com/api/chat/onto/graph",
   "scope": "chat",
   "args": "type?, q?, hops?",
   "curl": "curl -s 'https://snowfure.com/api/chat/onto/graph?key=$KEY&type=…'"
  },
  {
   "name": "onto_object",
   "desc": "本体单个对象详情（属性+链接）",
   "method": "GET",
   "path": "/api/chat/onto/object",
   "url": "https://snowfure.com/api/chat/onto/object",
   "scope": "chat",
   "args": "uri",
   "curl": "curl -s 'https://snowfure.com/api/chat/onto/object?key=$KEY&uri=…'"
  },
  {
   "name": "onto_stats",
   "desc": "本体体检（文件/三元组/类/实例）",
   "method": "GET",
   "path": "/api/chat/onto",
   "url": "https://snowfure.com/api/chat/onto",
   "scope": "chat",
   "args": "scope?",
   "curl": "curl -s 'https://snowfure.com/api/chat/onto?key=$KEY&scope=…'"
  },
  {
   "name": "onto_query",
   "desc": "本体只读 SPARQL",
   "method": "POST",
   "path": "/api/chat/onto/query",
   "url": "https://snowfure.com/api/chat/onto/query",
   "scope": "chat",
   "args": "sparql, scope?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/onto/query?key=$KEY' -H 'Content-Type: application/json' -d '{\"sparql\": \"SELECT ?s ?p ?o WHERE {?s ?p ?o} LIMIT 5\"}'",
   "body_example": {
    "sparql": "SELECT ?s ?p ?o WHERE {?s ?p ?o} LIMIT 5"
   },
   "returns": "{\"ok\":true,\"rows\":[…]}\""
  },
  {
   "name": "onto_plan",
   "desc": "本体驱动：意图→SPARQL→事实→计划",
   "method": "POST",
   "path": "/api/chat/onto/plan",
   "url": "https://snowfure.com/api/chat/onto/plan",
   "scope": "chat",
   "args": "intent, scope?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/onto/plan?key=$KEY' -H 'Content-Type: application/json' -d '{\"intent\": \"重启微信上传网关\"}'",
   "body_example": {
    "intent": "重启微信上传网关"
   },
   "returns": "{\"ok\":true,\"facts\":[…],\"steps\":[…]}"
  },
  {
   "name": "onto_run",
   "desc": "本体驱动：按事实下发智能体执行",
   "method": "POST",
   "path": "/api/chat/onto/run",
   "url": "https://snowfure.com/api/chat/onto/run",
   "scope": "chat",
   "args": "peer, intent, facts, steps",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/onto/run?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "list_sop",
   "desc": "SOP 流程列表+当前全文",
   "method": "GET",
   "path": "/api/chat/sop",
   "url": "https://snowfure.com/api/chat/sop",
   "scope": "chat",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/chat/sop?key=$KEY'"
  },
  {
   "name": "save_sop",
   "desc": "保存/新建 SOP（action=save|new|delete|select）",
   "method": "POST",
   "path": "/api/chat/sop",
   "url": "https://snowfure.com/api/chat/sop",
   "scope": "chat",
   "args": "action, id, name, text, auto",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/sop?key=$KEY' -H 'Content-Type: application/json' -d '{\"action\": \"save\", \"id\": \"s…\", \"name\": \"流程名\", \"text\": \"第一步：… ｜ 参与：… ｜ 交付：… ｜ 验收：总督\"}'",
   "body_example": {
    "action": "save",
    "id": "s…",
    "name": "流程名",
    "text": "第一步：… ｜ 参与：… ｜ 交付：… ｜ 验收：总督"
   },
   "returns": "{\"ok\":true}"
  },
  {
   "name": "sop_ai",
   "desc": "AI 对话优化 SOP / 创建缺失智能体",
   "method": "POST",
   "path": "/api/chat/sop/ai",
   "url": "https://snowfure.com/api/chat/sop/ai",
   "scope": "chat",
   "args": "action=optimize|create, text, instruction, names",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/sop/ai?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "list_drafts",
   "desc": "公众号草稿清单",
   "method": "GET",
   "path": "/api/chat/drafts",
   "url": "https://snowfure.com/api/chat/drafts",
   "scope": "chat",
   "args": "q, status",
   "curl": "curl -s 'https://snowfure.com/api/chat/drafts?key=$KEY&q=…'"
  },
  {
   "name": "get_draft",
   "desc": "读取草稿正文",
   "method": "GET",
   "path": "/api/chat/draft",
   "url": "https://snowfure.com/api/chat/draft",
   "scope": "chat",
   "args": "id",
   "curl": "curl -s 'https://snowfure.com/api/chat/draft?key=$KEY&id=…'"
  },
  {
   "name": "draft_ai",
   "desc": "草稿 AI（润色/扩写/缩写/语气/翻译/排版/标题/摘要/封面/大纲/重写/全文润色）",
   "method": "POST",
   "path": "/api/chat/draft/ai",
   "url": "https://snowfure.com/api/chat/draft/ai",
   "scope": "chat",
   "args": "action, text, content, title, tone, style, instruction",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/draft/ai?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "draft_templates",
   "desc": "公众号 6 大场景模板",
   "method": "GET",
   "path": "/api/chat/draft/templates",
   "url": "https://snowfure.com/api/chat/draft/templates",
   "scope": "chat",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/chat/draft/templates?key=$KEY'"
  },
  {
   "name": "draft_snapshot",
   "desc": "草稿版本快照（save/list/restore/delete）",
   "method": "POST",
   "path": "/api/chat/draft/snapshot",
   "url": "https://snowfure.com/api/chat/draft/snapshot",
   "scope": "chat",
   "args": "id, op, snapshot_id, note",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/draft/snapshot?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "draft_kb_search",
   "desc": "草稿素材检索（记忆+网盘）",
   "method": "POST",
   "path": "/api/chat/draft/kb_search",
   "url": "https://snowfure.com/api/chat/draft/kb_search",
   "scope": "chat",
   "args": "q",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/draft/kb_search?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "draft_uploadimg",
   "desc": "草稿插图上传（落网盘+换微信永久URL，网关不可达降级站内链）",
   "method": "POST",
   "path": "/api/chat/draft/uploadimg",
   "url": "https://snowfure.com/api/chat/draft/uploadimg",
   "scope": "chat",
   "args": "data(base64), mime, name",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/draft/uploadimg?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "draft_mp_update",
   "desc": "本地改动回写微信草稿箱已有图文（draft/update）",
   "method": "POST",
   "path": "/api/chat/draft/mp_update",
   "url": "https://snowfure.com/api/chat/draft/mp_update",
   "scope": "chat",
   "args": "id",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/draft/mp_update?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "draft_mp_pull",
   "desc": "微信草稿箱拉回本地（无 media_id 列清单 / 有则导入全文）",
   "method": "POST",
   "path": "/api/chat/draft/mp_pull",
   "url": "https://snowfure.com/api/chat/draft/mp_pull",
   "scope": "chat",
   "args": "media_id?",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/draft/mp_pull?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "upload_file",
   "desc": "附件上传 + 内容识别",
   "method": "POST",
   "path": "/api/chat/upload",
   "url": "https://snowfure.com/api/chat/upload",
   "scope": "chat",
   "args": "name, data, mime",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/upload?key=$KEY' -H 'Content-Type: application/json' -d '{\"name\": \"a.png\", \"data\": \"<base64>\", \"mime\": \"image/png\"}'",
   "body_example": {
    "name": "a.png",
    "data": "<base64>",
    "mime": "image/png"
   },
   "returns": "{\"ok\":true,\"kind\":\"image\",\"url\":\"…\"}"
  },
  {
   "name": "asr_transcribe",
   "desc": "语音转文字",
   "method": "POST",
   "path": "/api/chat/asr",
   "url": "https://snowfure.com/api/chat/asr",
   "scope": "chat",
   "args": "data, mime",
   "curl": "curl -s -X POST 'https://snowfure.com/api/chat/asr?key=$KEY' -H 'Content-Type: application/json' -d '{\"data\": \"<base64 音频>\", \"mime\": \"audio/wav\"}'",
   "body_example": {
    "data": "<base64 音频>",
    "mime": "audio/wav"
   },
   "returns": "{\"ok\":true,\"text\":\"…\"}"
  },
  {
   "name": "im_list_convos",
   "desc": "IM 会话列表",
   "method": "GET",
   "path": "/api/im/convos",
   "url": "https://snowfure.com/api/im/convos",
   "scope": "im",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/im/convos?key=$KEY'"
  },
  {
   "name": "im_send",
   "desc": "发 IM 消息",
   "method": "POST",
   "path": "/api/im/send",
   "url": "https://snowfure.com/api/im/send",
   "scope": "im",
   "args": "conv, text",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/send?key=$KEY' -H 'Content-Type: application/json' -d '{\"conv\": \"<会话 id>\", \"text\": \"你好\"}'",
   "body_example": {
    "conv": "<会话 id>",
    "text": "你好"
   },
   "returns": "{\"ok\":true,\"seq\":123}"
  },
  {
   "name": "im_search",
   "desc": "IM 消息全文检索（限自己所在会话）",
   "method": "GET",
   "path": "/api/im/search",
   "url": "https://snowfure.com/api/im/search",
   "scope": "im",
   "args": "q, conv?, limit?",
   "curl": "curl -s 'https://snowfure.com/api/im/search?key=$KEY&q=…'"
  },
  {
   "name": "im_typing",
   "desc": "「正在输入」信令（广播不落库）",
   "method": "POST",
   "path": "/api/im/typing",
   "url": "https://snowfure.com/api/im/typing",
   "scope": "im",
   "args": "conv",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/typing?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "im_read",
   "desc": "已读上报（广播回执）",
   "method": "POST",
   "path": "/api/im/read",
   "url": "https://snowfure.com/api/im/read",
   "scope": "im",
   "args": "conv, upto",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/read?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "im_recall",
   "desc": "撤回自己发的消息（软删+广播）",
   "method": "POST",
   "path": "/api/im/msg/del",
   "url": "https://snowfure.com/api/im/msg/del",
   "scope": "im",
   "args": "conv, seq",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/msg/del?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "im_people",
   "desc": "IM 成员",
   "method": "GET",
   "path": "/api/im/people",
   "url": "https://snowfure.com/api/im/people",
   "scope": "im",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/im/people?key=$KEY'"
  },
  {
   "name": "im_contacts",
   "desc": "IM 通讯录（人+智能体）",
   "method": "GET",
   "path": "/api/im/contacts",
   "url": "https://snowfure.com/api/im/contacts",
   "scope": "im",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/im/contacts?key=$KEY'"
  },
  {
   "name": "im_plugins",
   "desc": "IM 插件注册表+在线状态",
   "method": "GET",
   "path": "/api/im/plugins",
   "url": "https://snowfure.com/api/im/plugins",
   "scope": "im",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/im/plugins?key=$KEY'"
  },
  {
   "name": "im_plugin_test",
   "desc": "测试插件连通",
   "method": "POST",
   "path": "/api/im/plugins/test",
   "url": "https://snowfure.com/api/im/plugins/test",
   "scope": "im",
   "args": "id",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/plugins/test?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "list_api_keys",
   "desc": "API 密钥清单",
   "method": "GET",
   "path": "/api/v1/keys",
   "url": "https://snowfure.com/api/v1/keys",
   "scope": "admin",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/v1/keys?key=$KEY'"
  },
  {
   "name": "list_apps",
   "desc": "IM 应用清单（app_id，不含密钥）",
   "method": "GET",
   "path": "/api/v1/apps",
   "url": "https://snowfure.com/api/v1/apps",
   "scope": "docs",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/v1/apps?key=$KEY'"
  },
  {
   "name": "create_app",
   "desc": "注册 IM 应用 → app_id/app_secret（harness 插件接入用）",
   "method": "POST",
   "path": "/api/v1/apps",
   "url": "https://snowfure.com/api/v1/apps",
   "scope": "docs",
   "args": "name, ident, engine, glyph",
   "curl": "curl -s -X POST 'https://snowfure.com/api/v1/apps?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "app_access_token",
   "desc": "应用换 token（仿飞书，2h 有效）",
   "method": "POST",
   "path": "/api/v1/auth/app_access_token/internal",
   "url": "https://snowfure.com/api/v1/auth/app_access_token/internal",
   "scope": "docs",
   "args": "app_id, app_secret",
   "curl": "curl -s -X POST 'https://snowfure.com/api/v1/auth/app_access_token/internal?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "im_ws_endpoint",
   "desc": "取 IM 长连接地址 + ClientConfig（仿飞书）",
   "method": "POST",
   "path": "/api/im/ws/endpoint",
   "url": "https://snowfure.com/api/im/ws/endpoint",
   "scope": "im",
   "args": "app_id, app_secret",
   "curl": "curl -s -X POST 'https://snowfure.com/api/im/ws/endpoint?key=$KEY' -H 'Content-Type: application/json' -d '{}'"
  },
  {
   "name": "im_ws_status",
   "desc": "IM 长连接在线状态（排查用）",
   "method": "GET",
   "path": "/api/im/ws/status",
   "url": "https://snowfure.com/api/im/ws/status",
   "scope": "im",
   "args": "",
   "curl": "curl -s 'https://snowfure.com/api/im/ws/status?key=$KEY'"
  }
 ],
 "count": 80
}