{
  "version": "2026.10.31",
  "basePath": "/v1/operations",
  "auth": {
    "type": "bearer",
    "note": "企业管理员创建最小权限 API Key，仅保存在服务端。先用 GET /v1/capabilities 核对授权；文档不代表已开通。"
  },
  "gateway": {
    "basePath": "/v1/operations",
    "auth": "Bearer API Key",
    "operations": [
      {
        "id": "agents.read",
        "name": "读取智能体",
        "group": "会话接待",
        "path": "/v1/operations/agents.read",
        "method": "GET",
        "permissions": [
          "agent"
        ]
      },
      {
        "id": "conversations.read",
        "name": "读取文本对话记录",
        "group": "会话接待",
        "path": "/v1/operations/conversations.read",
        "method": "GET",
        "permissions": [
          "service"
        ]
      },
      {
        "id": "voice-records.read",
        "name": "读取语音记录",
        "group": "服务结果",
        "path": "/v1/operations/voice-records.read",
        "method": "GET",
        "permissions": [
          "service"
        ]
      },
      {
        "id": "analysis.read",
        "name": "读取总结分析",
        "group": "服务结果",
        "path": "/v1/operations/analysis.read",
        "method": "GET",
        "permissions": [
          "service",
          "agent"
        ]
      },
      {
        "id": "analysis.generate",
        "name": "总结分析 · 生成",
        "group": "服务结果",
        "path": "/v1/operations/analysis.generate",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "generate",
        "billable": true
      },
      {
        "id": "memory.read",
        "name": "读取历史记忆",
        "group": "客户资料",
        "path": "/v1/operations/memory.read",
        "method": "GET",
        "permissions": [
          "service"
        ]
      },
      {
        "id": "memory.ignore",
        "name": "历史记忆 · 忽略一条记录",
        "group": "客户资料",
        "path": "/v1/operations/memory.ignore",
        "method": "POST",
        "permissions": [
          "service",
          "memory.manage"
        ],
        "action": "ignore",
        "billable": false
      },
      {
        "id": "memory.unlink",
        "name": "历史记忆 · 排除一条历史记录",
        "group": "客户资料",
        "path": "/v1/operations/memory.unlink",
        "method": "POST",
        "permissions": [
          "service",
          "memory.manage"
        ],
        "action": "unlink",
        "billable": false
      },
      {
        "id": "memory.forget",
        "name": "历史记忆 · 遗忘",
        "group": "客户资料",
        "path": "/v1/operations/memory.forget",
        "method": "POST",
        "permissions": [
          "service",
          "memory.manage"
        ],
        "action": "forget",
        "billable": false
      },
      {
        "id": "memory.block",
        "name": "历史记忆 · 遗忘并禁止再次使用",
        "group": "客户资料",
        "path": "/v1/operations/memory.block",
        "method": "POST",
        "permissions": [
          "service",
          "memory.manage"
        ],
        "action": "block",
        "billable": false
      },
      {
        "id": "customers.read",
        "name": "读取客户资料",
        "group": "客户资料",
        "path": "/v1/operations/customers.read",
        "method": "GET",
        "permissions": [
          "customers"
        ]
      },
      {
        "id": "customers.save",
        "name": "客户资料 · 保存",
        "group": "客户资料",
        "path": "/v1/operations/customers.save",
        "method": "POST",
        "permissions": [
          "customers"
        ],
        "action": "save",
        "billable": false
      },
      {
        "id": "customers.import",
        "name": "客户资料 · 批量导入客户",
        "group": "客户资料",
        "path": "/v1/operations/customers.import",
        "method": "POST",
        "permissions": [
          "customers"
        ],
        "action": "import",
        "billable": false
      },
      {
        "id": "customers.importStart",
        "name": "客户资料 · 创建分批导入任务",
        "group": "客户资料",
        "path": "/v1/operations/customers.importStart",
        "method": "POST",
        "permissions": [
          "customers"
        ],
        "action": "importStart",
        "billable": false
      },
      {
        "id": "customers.crmSave",
        "name": "客户资料 · 保存跟进设置",
        "group": "客户资料",
        "path": "/v1/operations/customers.crmSave",
        "method": "POST",
        "permissions": [
          "customers"
        ],
        "action": "crmSave",
        "billable": false
      },
      {
        "id": "customers.crmFollowup",
        "name": "客户资料 · 添加跟进记录",
        "group": "客户资料",
        "path": "/v1/operations/customers.crmFollowup",
        "method": "POST",
        "permissions": [
          "customers"
        ],
        "action": "crmFollowup",
        "billable": false
      },
      {
        "id": "customers.fields",
        "name": "客户资料 · 保存自定义字段定义",
        "group": "客户资料",
        "path": "/v1/operations/customers.fields",
        "method": "POST",
        "permissions": [
          "customers"
        ],
        "action": "fields",
        "billable": false
      },
      {
        "id": "customers.bind",
        "name": "客户资料 · 将会话关联到客户",
        "group": "客户资料",
        "path": "/v1/operations/customers.bind",
        "method": "POST",
        "permissions": [
          "customers",
          "service"
        ],
        "action": "bind",
        "billable": false
      },
      {
        "id": "customer-crm.read",
        "name": "读取客户跟进",
        "group": "客户资料",
        "path": "/v1/operations/customer-crm.read",
        "method": "GET",
        "permissions": [
          "customers"
        ]
      },
      {
        "id": "email.read",
        "name": "读取邮件与AI接待",
        "group": "邮件接待",
        "path": "/v1/operations/email.read",
        "method": "GET",
        "permissions": [
          "service"
        ],
        "query": {
          "view": "mailbox"
        }
      },
      {
        "id": "email.mark",
        "name": "邮件与AI接待 · 标记单封邮件",
        "group": "邮件接待",
        "path": "/v1/operations/email.mark",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "mark",
        "billable": false
      },
      {
        "id": "email.saveDraft",
        "name": "邮件与AI接待 · 保存草稿",
        "group": "邮件接待",
        "path": "/v1/operations/email.saveDraft",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "saveDraft",
        "billable": false
      },
      {
        "id": "email.sendDraft",
        "name": "邮件与AI接待 · 发送草稿",
        "group": "邮件接待",
        "path": "/v1/operations/email.sendDraft",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "sendDraft",
        "billable": true
      },
      {
        "id": "blacklist.read",
        "name": "读取黑名单",
        "group": "客户资料",
        "path": "/v1/operations/blacklist.read",
        "method": "GET",
        "permissions": [
          "service"
        ]
      },
      {
        "id": "blacklist.import",
        "name": "导入黑名单",
        "group": "客户资料",
        "path": "/v1/operations/blacklist.import",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "import",
        "billable": false
      },
      {
        "id": "desk.read",
        "name": "读取工作台与工单",
        "group": "会话接待",
        "path": "/v1/operations/desk.read",
        "method": "GET",
        "permissions": [
          "service"
        ]
      },
      {
        "id": "desk.send",
        "name": "工作台与工单 · 发送消息",
        "group": "会话接待",
        "path": "/v1/operations/desk.send",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "send",
        "billable": false
      },
      {
        "id": "desk.note",
        "name": "工作台与工单 · 添加会话内部备注",
        "group": "会话接待",
        "path": "/v1/operations/desk.note",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "note",
        "billable": false
      },
      {
        "id": "desk.close",
        "name": "工作台与工单 · 关闭本人接待的会话",
        "group": "会话接待",
        "path": "/v1/operations/desk.close",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "close",
        "billable": false
      },
      {
        "id": "desk.endConversation",
        "name": "工作台与工单 · 结束进行中的会话",
        "group": "会话接待",
        "path": "/v1/operations/desk.endConversation",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "endConversation",
        "billable": false
      },
      {
        "id": "desk.reopen",
        "name": "工作台与工单 · 重新打开会话",
        "group": "会话接待",
        "path": "/v1/operations/desk.reopen",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "reopen",
        "billable": false
      },
      {
        "id": "desk.claim",
        "name": "工作台与工单 · 领取",
        "group": "会话接待",
        "path": "/v1/operations/desk.claim",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "claim",
        "billable": false
      },
      {
        "id": "desk.createTask",
        "name": "工作台与工单 · 创建任务",
        "group": "会话接待",
        "path": "/v1/operations/desk.createTask",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "createTask",
        "billable": false
      },
      {
        "id": "desk.createTicket",
        "name": "工作台与工单 · 创建工单",
        "group": "会话接待",
        "path": "/v1/operations/desk.createTicket",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "createTicket",
        "billable": false
      },
      {
        "id": "desk.transferTicket",
        "name": "工作台与工单 · 转派工单",
        "group": "会话接待",
        "path": "/v1/operations/desk.transferTicket",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "transferTicket",
        "billable": false
      },
      {
        "id": "desk.workStatus",
        "name": "工作台与工单 · 更新工单或待办状态",
        "group": "会话接待",
        "path": "/v1/operations/desk.workStatus",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "workStatus",
        "billable": false
      },
      {
        "id": "desk.handoff",
        "name": "工作台与工单 · 发起转接邀请",
        "group": "会话接待",
        "path": "/v1/operations/desk.handoff",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "handoff",
        "billable": false
      },
      {
        "id": "desk.acceptHandoff",
        "name": "工作台与工单 · 接受转接邀请",
        "group": "会话接待",
        "path": "/v1/operations/desk.acceptHandoff",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "acceptHandoff",
        "billable": false
      },
      {
        "id": "desk.cancelHandoff",
        "name": "工作台与工单 · 撤回转接邀请",
        "group": "会话接待",
        "path": "/v1/operations/desk.cancelHandoff",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "cancelHandoff",
        "billable": false
      },
      {
        "id": "desk.releaseToAI",
        "name": "工作台与工单 · 交回 AI 接待",
        "group": "会话接待",
        "path": "/v1/operations/desk.releaseToAI",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "releaseToAI",
        "billable": false
      },
      {
        "id": "knowledge.read",
        "name": "读取知识库",
        "group": "知识检索",
        "path": "/v1/operations/knowledge.read",
        "method": "GET",
        "permissions": [
          "knowledge"
        ]
      },
      {
        "id": "knowledge.save",
        "name": "知识库 · 保存",
        "group": "知识检索",
        "path": "/v1/operations/knowledge.save",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "save",
        "billable": false
      },
      {
        "id": "knowledge.preview",
        "name": "知识库 · 预览",
        "group": "知识检索",
        "path": "/v1/operations/knowledge.preview",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "preview",
        "billable": false
      },
      {
        "id": "knowledge.retrieve",
        "name": "知识库 · 检索",
        "group": "知识检索",
        "path": "/v1/operations/knowledge.retrieve",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "retrieve",
        "billable": true
      },
      {
        "id": "knowledge.index",
        "name": "知识库 · 建立索引",
        "group": "知识检索",
        "path": "/v1/operations/knowledge.index",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "index",
        "billable": true
      },
      {
        "id": "knowledge.publish",
        "name": "知识库 · 发布",
        "group": "知识检索",
        "path": "/v1/operations/knowledge.publish",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "publish",
        "billable": false
      },
      {
        "id": "knowledge.unpublish",
        "name": "知识库 · 撤回文档发布",
        "group": "知识检索",
        "path": "/v1/operations/knowledge.unpublish",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "unpublish",
        "billable": false
      },
      {
        "id": "knowledge.delete",
        "name": "知识库 · 永久删除文档",
        "group": "知识检索",
        "path": "/v1/operations/knowledge.delete",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "delete",
        "billable": false
      },
      {
        "id": "knowledge-sources.read",
        "name": "读取知识源",
        "group": "知识检索",
        "path": "/v1/operations/knowledge-sources.read",
        "method": "GET",
        "permissions": [
          "knowledge"
        ]
      },
      {
        "id": "knowledge-sources.save",
        "name": "知识源 · 新建或更新连接",
        "group": "知识检索",
        "path": "/v1/operations/knowledge-sources.save",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "save",
        "billable": false
      },
      {
        "id": "knowledge-sources.sync",
        "name": "知识源 · 立即同步",
        "group": "知识检索",
        "path": "/v1/operations/knowledge-sources.sync",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "sync",
        "billable": false
      },
      {
        "id": "knowledge-sources.pause",
        "name": "知识源 · 启用或暂停同步",
        "group": "知识检索",
        "path": "/v1/operations/knowledge-sources.pause",
        "method": "POST",
        "permissions": [
          "knowledge"
        ],
        "action": "pause",
        "billable": false
      },
      {
        "id": "desk-knowledge.read",
        "name": "读取客服知识检索",
        "group": "会话接待",
        "path": "/v1/operations/desk-knowledge.read",
        "method": "GET",
        "permissions": [
          "service"
        ]
      },
      {
        "id": "phone-calls.read",
        "name": "读取电话呼入呼出",
        "group": "电话外呼",
        "path": "/v1/operations/phone-calls.read",
        "method": "GET",
        "permissions": [
          "service"
        ],
        "query": {
          "view": "calls"
        }
      },
      {
        "id": "phone-calls.dial",
        "name": "电话呼入呼出 · 拨号",
        "group": "电话外呼",
        "path": "/v1/operations/phone-calls.dial",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "dial",
        "billable": true
      },
      {
        "id": "phone-calls.hangup",
        "name": "电话呼入呼出 · 挂断",
        "group": "电话外呼",
        "path": "/v1/operations/phone-calls.hangup",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "hangup",
        "billable": false
      },
      {
        "id": "phone-detail.read",
        "name": "读取电话详情",
        "group": "电话外呼",
        "path": "/v1/operations/phone-detail.read",
        "method": "GET",
        "permissions": [
          "service"
        ],
        "query": {
          "view": "call"
        }
      },
      {
        "id": "outbound-batches.read",
        "name": "读取批量外呼",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.read",
        "method": "GET",
        "permissions": [
          "service",
          "agent"
        ]
      },
      {
        "id": "outbound-batches.save",
        "name": "批量外呼 · 保存",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.save",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "save",
        "billable": false
      },
      {
        "id": "outbound-batches.start",
        "name": "批量外呼 · 启动批次",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.start",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "start",
        "billable": true
      },
      {
        "id": "outbound-batches.pause",
        "name": "批量外呼 · 暂停批次",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.pause",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "pause",
        "billable": false
      },
      {
        "id": "outbound-batches.resume",
        "name": "批量外呼 · 继续批次",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.resume",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "resume",
        "billable": true
      },
      {
        "id": "outbound-batches.cancel",
        "name": "批量外呼 · 取消批次",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.cancel",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "cancel",
        "billable": false
      },
      {
        "id": "outbound-batches.retry",
        "name": "批量外呼 · 为失败号码新建重试批次",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.retry",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "retry",
        "billable": false
      },
      {
        "id": "outbound-batches.importStart",
        "name": "批量外呼 · 开始导入",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.importStart",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "importStart",
        "billable": false
      },
      {
        "id": "outbound-batches.importChunk",
        "name": "批量外呼 · 上传导入分块",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.importChunk",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "importChunk",
        "billable": false
      },
      {
        "id": "outbound-batches.importComplete",
        "name": "批量外呼 · 完成导入",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.importComplete",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "importComplete",
        "billable": false
      },
      {
        "id": "outbound-batches.importCancel",
        "name": "批量外呼 · 取消导入",
        "group": "电话外呼",
        "path": "/v1/operations/outbound-batches.importCancel",
        "method": "POST",
        "permissions": [
          "service",
          "agent"
        ],
        "action": "importCancel",
        "billable": false
      },
      {
        "id": "billing.read",
        "name": "读取账单与消耗",
        "group": "服务结果",
        "path": "/v1/operations/billing.read",
        "method": "GET",
        "permissions": [
          "billing"
        ]
      },
      {
        "id": "service-analytics.read",
        "name": "读取服务运营分析",
        "group": "服务结果",
        "path": "/v1/operations/service-analytics.read",
        "method": "GET",
        "permissions": [
          "reports",
          "service"
        ]
      },
      {
        "id": "quality-reviews.read",
        "name": "读取质检复核记录",
        "group": "服务结果",
        "path": "/v1/operations/quality-reviews.read",
        "method": "GET",
        "permissions": [
          "reports",
          "service"
        ]
      },
      {
        "id": "callbacks.read",
        "name": "读取回调订阅",
        "group": "事件回调",
        "path": "/v1/operations/callbacks.read",
        "method": "GET",
        "permissions": [
          "applications",
          "agent",
          "service"
        ]
      },
      {
        "id": "callbacks.save",
        "name": "回调订阅 · 保存",
        "group": "事件回调",
        "path": "/v1/operations/callbacks.save",
        "method": "POST",
        "permissions": [
          "applications",
          "agent",
          "service"
        ],
        "action": "save",
        "billable": false
      },
      {
        "id": "callbacks.toggle",
        "name": "回调订阅 · 启用或停用",
        "group": "事件回调",
        "path": "/v1/operations/callbacks.toggle",
        "method": "POST",
        "permissions": [
          "applications",
          "agent",
          "service"
        ],
        "action": "toggle",
        "billable": false
      },
      {
        "id": "callbacks.test",
        "name": "回调订阅 · 测试",
        "group": "事件回调",
        "path": "/v1/operations/callbacks.test",
        "method": "POST",
        "permissions": [
          "applications",
          "agent",
          "service"
        ],
        "action": "test",
        "billable": true
      },
      {
        "id": "callbacks.retry",
        "name": "回调订阅 · 重试失败投递",
        "group": "事件回调",
        "path": "/v1/operations/callbacks.retry",
        "method": "POST",
        "permissions": [
          "applications",
          "agent",
          "service"
        ],
        "action": "retry",
        "billable": false
      },
      {
        "id": "callbacks.rotate",
        "name": "回调订阅 · 轮换签名密钥",
        "group": "事件回调",
        "path": "/v1/operations/callbacks.rotate",
        "method": "POST",
        "permissions": [
          "applications",
          "agent",
          "service"
        ],
        "action": "rotate",
        "billable": false
      },
      {
        "id": "callbacks.delete",
        "name": "回调订阅 · 删除订阅",
        "group": "事件回调",
        "path": "/v1/operations/callbacks.delete",
        "method": "POST",
        "permissions": [
          "applications",
          "agent",
          "service"
        ],
        "action": "delete",
        "billable": false
      },
      {
        "id": "email-customer.read",
        "name": "读取邮件关联客户与有效记忆",
        "group": "邮件接待",
        "path": "/v1/operations/email-customer.read",
        "method": "GET",
        "permissions": [
          "service"
        ],
        "query": {
          "view": "customerContext"
        }
      },
      {
        "id": "phone-records.export",
        "name": "导出电话记录",
        "group": "电话外呼",
        "path": "/v1/operations/phone-records.export",
        "method": "GET",
        "permissions": [
          "service"
        ],
        "query": {
          "view": "export"
        }
      },
      {
        "id": "business-data.snapshot",
        "name": "读取客户订单与物流快照",
        "group": "客户资料",
        "path": "/v1/operations/business-data.snapshot",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "customerSnapshot"
      },
      {
        "id": "business-data.lookup",
        "name": "查询订单或物流状态",
        "group": "客户资料",
        "path": "/v1/operations/business-data.lookup",
        "method": "POST",
        "permissions": [
          "service"
        ],
        "action": "lookup"
      },
      {
        "id": "customers.bindPreview",
        "name": "客户资料 · 预览会话与客户的关联",
        "group": "客户资料",
        "path": "/v1/operations/customers.bindPreview",
        "method": "GET",
        "permissions": [
          "customers",
          "service"
        ],
        "query": {
          "bindPreview": "1"
        }
      }
    ],
    "idempotency": "POST 必带 8–100 位 Idempotency-Key；同一业务重试保持原键与原参数。"
  },
  "conventions": {
    "requestId": "保留 X-Request-Id、时间和状态；提前拒绝时可能没有编号。异步受理不代表执行完成。",
    "pagination": "按接口使用 page/pageSize 或服务端返回的 cursor，不混用。文本与语音记录 pageSize 最大 100。",
    "errors": "错误正文按接口解析，常见格式 {error:string}。409 先核对版本与原结果；429 按 Retry-After 等待。",
    "time": "时间按字段说明使用 Unix 毫秒或带时区 ISO 字符串；未知值保留 null 或省略。"
  },
  "callbacks": {
    "method": "POST",
    "headers": [
      "X-Yunfu-Event-Id",
      "X-Yunfu-Timestamp",
      "X-Yunfu-Signature",
      "X-Yunfu-Delivery-Id",
      "X-Yunfu-Attempt"
    ],
    "signature": "sha256=hex(HMAC-SHA256(secret, timestamp + \".\" + raw_body))；timestamp 为 Unix 秒。接收方应以常量时间比较签名并限制 ±300 秒重放窗口。",
    "retry": "同事务事件队列，默认本人范围，可显式选择本企业事件。涵盖构建、记忆、配置、发布、工作流、服务状态、总结和 API 结果；仅登记的事件有效。最多自动尝试 5 次，间隔 30 秒、2 分钟、10 分钟、1 小时，依赖原生 scheduled。人工最多 10 次；可能重复或乱序，按事件 ID 去重；停用或变更不补发历史。"
  },
  "entries": [
    {
      "id": "agents.read",
      "group": "会话接待",
      "name": "读取智能体",
      "method": "GET",
      "currentPath": "/v1/operations/agents.read",
      "publicPath": "/v1/operations/agents.read",
      "status": "available",
      "description": "读取当前企业的草稿/发布状态及共享 revision；创建智能体前先取最新 revision。",
      "scopes": [
        "agent"
      ],
      "request": "?",
      "callbackEvents": [],
      "response": "{\n  \"revision\": 7,\n  \"agents\": [\n    {\n      \"id\": \"default\",\n      \"name\": \"售后助手\",\n      \"description\": \"\",\n      \"modelId\": \"text-model\",\n      \"archived\": false,\n      \"publishedVersion\": 0,\n      \"dirty\": true,\n      \"updated\": 1789603200000,\n      \"channels\": []\n    }\n  ],\n  \"workflows\": [],\n  \"channels\": [],\n  \"publicKnowledgeLibraries\": []\n}",
      "requestFields": [],
      "responseFields": [
        {
          "name": "revision",
          "type": "number",
          "description": "企业目录当前版本；POST createAgent 必须携带。",
          "required": true
        },
        {
          "name": "agents[]",
          "type": "{id,name,description,modelId,archived,publishedVersion,dirty,updated,channels}",
          "description": "智能体目录，包括草稿及已归档项目；不是仅返回已发布智能体。",
          "required": true
        },
        {
          "name": "workflows[]",
          "type": "{id,name,versions:[{version,name}]}",
          "description": "含 conversation 版本的工作流目录。",
          "required": true
        },
        {
          "name": "channels / publicKnowledgeLibraries",
          "type": "array",
          "description": "具备 channels 权限时返回，否则为空数组。",
          "required": true
        }
      ],
      "notes": [
        "权限由当前登录账号、企业及支持访问范围决定，不能通过传 tenant、actor 或 owner 扩大访问范围。"
      ],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "conversations.read",
      "group": "会话接待",
      "name": "读取文本对话记录",
      "method": "GET",
      "currentPath": "/v1/operations/conversations.read?scope=all&page=1&pageSize=20&sort=newest",
      "publicPath": "/v1/operations/conversations.read",
      "status": "available",
      "description": "按关键词、演练/正式服务范围、时间及分页查询当前坐席可见的文本对话；列表仅含摘要，完整消息用详情接口。",
      "scopes": [
        "service"
      ],
      "request": "?scope=all&page=1&pageSize=20&sort=newest",
      "response": "{\n  \"conversations\": [\n    {\n      \"id\": \"conv_example\",\n      \"name\": \"示例客户\",\n      \"scope\": \"service\",\n      \"isTest\": false,\n      \"testType\": null,\n      \"hasVoiceRecord\": false,\n      \"channel\": \"网页\",\n      \"unit\": \"客服部\",\n      \"tag\": \"咨询\",\n      \"handling\": \"AI\",\n      \"lifecycle\": \"OPEN\",\n      \"owner\": \"\",\n      \"ownerId\": null,\n      \"priority\": \"normal\",\n      \"summary\": \"咨询订单进度\",\n      \"messageCount\": 2,\n      \"time\": \"09:00\",\n      \"createdAt\": \"2026-09-17T01:00:00Z\",\n      \"updatedAt\": \"2026-09-17T01:01:00Z\",\n      \"closedAt\": null,\n      \"textService\": {\n        \"policy\": {\n          \"version\": 1,\n          \"source\": \"agent\",\n          \"agentVersion\": 3\n        },\n        \"idleClose\": {\n          \"enabled\": true,\n          \"minutes\": 30\n        }\n      },\n      \"idleCloseEvidence\": null,\n      \"closeReason\": null,\n      \"createdTime\": 1789606800000\n    }\n  ],\n  \"total\": 1,\n  \"page\": 1,\n  \"pageSize\": 20,\n  \"filters\": {\n    \"query\": \"\",\n    \"agentId\": \"\",\n    \"scope\": \"all\",\n    \"start\": \"\",\n    \"end\": \"\",\n    \"sort\": \"newest\",\n    \"page\": 1,\n    \"pageSize\": 20\n  },\n  \"asOf\": 1789606860000\n}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "query",
          "type": "string",
          "description": "搜索关键词，最多 200 字符；字段覆盖范围见各接口说明。",
          "required": false
        },
        {
          "name": "scope",
          "type": "all | test | service",
          "description": "记录范围，默认 all；演练记录和正式服务分别归类。",
          "required": false
        },
        {
          "name": "page",
          "type": "integer",
          "description": "从 1 开始，最大 10000。",
          "required": false
        },
        {
          "name": "pageSize",
          "type": "integer",
          "description": "1–100；默认值见接口说明。",
          "required": false
        },
        {
          "name": "start / end",
          "type": "string",
          "description": "开始/结束时间：YYYY-MM-DD 按 UTC 整日；ISO 时间必须带时区。结束日期包含整日，结束时间包含指定毫秒。",
          "required": false
        },
        {
          "name": "sort",
          "type": "newest | oldest | replies-desc | replies-asc | messages-desc | duration-desc | waiting-first",
          "description": "默认 newest；可按回复、消息数、时长和待处理优先排序。",
          "required": false
        },
        {
          "name": "agentId",
          "type": "string",
          "description": "仅查询指定智能体的对话，最多 100 字符；省略查询全部可见智能体。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "conversations[]",
          "type": "{id,name,scope,isTest,testType,hasVoiceRecord,channel,unit,tag,handling,lifecycle,owner,ownerId,priority,summary,messageCount,time,createdAt,updatedAt,closedAt,textService,idleCloseEvidence,closeReason,createdTime}",
          "description": "记录摘要；不包含完整消息。",
          "required": true
        },
        {
          "name": "conversations[].id / conversations[].scope / conversations[].messageCount",
          "type": "string / test|service / number",
          "description": "详情主键、记录范围和完整消息条数。",
          "required": true
        },
        {
          "name": "conversations[].createdAt / updatedAt / closedAt",
          "type": "string | null",
          "description": "原 ISO 时间；缺失为 null。",
          "required": false
        },
        {
          "name": "conversations[].textService",
          "type": "{policy?,idleClose:{enabled,minutes}} | null",
          "description": "会话开始时生效的无响应自动关闭策略；minutes 为 1–1440。旧会话可能为 null。",
          "required": false
        },
        {
          "name": "conversations[].closeReason",
          "type": "idle | window | duration | null",
          "description": "自动关闭原因：idle 客户无响应、window 服务窗口到期、duration 达到服务总时长；人工关闭或未关闭为 null。",
          "required": false
        },
        {
          "name": "conversations[].idleCloseEvidence",
          "type": "{policy,minutes,basis,messageId?,startedAt,deadline,closedAt,delayMs,delayReason} | null",
          "description": "仅 closeReason=idle 时返回：计时起点（basis 为 delivered_reply 或 opened）、截止与实际关闭时间（ISO）及延迟原因。",
          "required": false
        },
        {
          "name": "conversations[].handling",
          "type": "AI | HANDOFF | HUMAN | ASYNC",
          "description": "接待处理状态，保留实际大写枚举。",
          "required": true
        },
        {
          "name": "conversations[].lifecycle",
          "type": "OPEN | CLOSED",
          "description": "会话生命周期，保留实际大写枚举。",
          "required": true
        },
        {
          "name": "conversations[].testType",
          "type": "text | voice | null",
          "description": "已保存演练会话的类型；未记录为 null。两类均按 scope 归类，不另造一条会话。",
          "required": true
        },
        {
          "name": "conversations[].createdTime",
          "type": "number | null",
          "description": "有效创建时间转换的 Unix 毫秒；未知为 null，0 是有效时间。",
          "required": true
        },
        {
          "name": "total / page / pageSize",
          "type": "number",
          "description": "筛选后总数、当前页、每页条数；默认 pageSize=20。",
          "required": true
        },
        {
          "name": "filters / asOf",
          "type": "object / number",
          "description": "生效筛选条件和服务端响应时间（Unix 毫秒）。",
          "required": true
        }
      ],
      "notes": [
        "权限由当前登录账号、企业及支持访问范围决定，不能通过传 tenant、actor 或 owner 扩大访问范围。",
        "query 搜索编号、姓名、渠道、摘要和完整消息正文；最多 200 字符。",
        "按有效 createdAt 排序，未知创建时间排末尾，同时间按 id 升序；有日期筛选时排除未知创建时间。",
        "通过 service 权限及服务台可见范围过滤，普通坐席不会因此看到其他坐席私有记录。",
        "这是服务台消息记录接口，没有 kind=text 过滤；可能包含 testType=voice 的演练会话和语音关联文字会话，不能据此统计纯文本通话。语音主记录请使用 /v1/operations/voice-records.read。"
      ],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "voice-records.read",
      "group": "服务结果",
      "name": "读取语音记录",
      "method": "GET",
      "currentPath": "/v1/operations/voice-records.read?scope=all&page=1&pageSize=10&inputKind=all&status=all&mode=all&sort=newest",
      "publicPath": "/v1/operations/voice-records.read",
      "status": "available",
      "description": "查询已保存通话的摘要、输入方式与轮次，支持完整文本搜索、状态、智能体及配置版本筛选。",
      "scopes": [
        "service"
      ],
      "request": "?scope=all&page=1&pageSize=10&inputKind=all&status=all&mode=all&sort=newest",
      "response": "{\n  \"calls\": [\n    {\n      \"sessionId\": \"voice_example\",\n      \"agentId\": \"agent_example\",\n      \"agentName\": \"售后助手\",\n      \"conversationId\": \"\",\n      \"mode\": \"draft\",\n      \"scope\": \"test\",\n      \"created\": 1789603200000,\n      \"ended\": 1789603260000,\n      \"updated\": 1789603260000,\n      \"status\": \"ended\",\n      \"sourceStatus\": null,\n      \"inputKind\": \"audio\",\n      \"turns\": 1\n    }\n  ],\n  \"total\": 1,\n  \"page\": 1,\n  \"pageSize\": 10,\n  \"scope\": {\n    \"query\": \"\",\n    \"agentId\": \"\",\n    \"conversationId\": \"\",\n    \"inputKind\": \"all\",\n    \"scope\": \"all\",\n    \"recordScope\": \"all\",\n    \"status\": \"all\",\n    \"mode\": \"all\",\n    \"start\": \"\",\n    \"end\": \"\",\n    \"sort\": \"newest\",\n    \"page\": 1,\n    \"pageSize\": 10\n  },\n  \"filterKey\": \"服务端生成的筛选指纹\",\n  \"options\": {\n    \"agents\": [\n      {\n        \"id\": \"agent_example\",\n        \"name\": \"售后助手\"\n      }\n    ]\n  },\n  \"asOf\": 1789603260000\n}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "query",
          "type": "string",
          "description": "搜索关键词，最多 200 字符；字段覆盖范围见各接口说明。",
          "required": false
        },
        {
          "name": "scope",
          "type": "all | test | service",
          "description": "记录范围，默认 all；演练记录和正式服务分别归类。",
          "required": false
        },
        {
          "name": "page",
          "type": "integer",
          "description": "从 1 开始，最大 10000。",
          "required": false
        },
        {
          "name": "pageSize",
          "type": "integer",
          "description": "1–100；默认值见接口说明。",
          "required": false
        },
        {
          "name": "start / end",
          "type": "string",
          "description": "开始/结束时间：YYYY-MM-DD 按 UTC 整日；ISO 时间必须带时区。结束日期包含整日，结束时间包含指定毫秒。",
          "required": false
        },
        {
          "name": "sort",
          "type": "newest | oldest",
          "description": "默认 newest；排序依据见各接口说明。",
          "required": false
        },
        {
          "name": "agentId",
          "type": "string",
          "description": "智能体 ID，最多 100 字符。",
          "required": false
        },
        {
          "name": "conversationId",
          "type": "string",
          "description": "关联对话 ID，最多 100 字符；使用时另外要求 service 权限及该对话可见。",
          "required": false
        },
        {
          "name": "inputKind",
          "type": "all | audio | text | mixed | none",
          "description": "默认 all。",
          "required": false
        },
        {
          "name": "status",
          "type": "all | active | ended | handoff",
          "description": "默认 all。",
          "required": false
        },
        {
          "name": "mode",
          "type": "all | draft | published",
          "description": "默认 all。",
          "required": false
        },
        {
          "name": "minSeconds / maxSeconds",
          "type": "integer",
          "description": "通话时长下限 / 上限，单位秒，范围 0 至 31536000；下限不能大于上限。进行中通话按最近更新时间计算。",
          "required": false
        },
        {
          "name": "sessionIds",
          "type": "JSON string[]",
          "description": "仅 action=export 时使用，导出所选通话。最多 100 个唯一 ID，仍受当前筛选和访问权限限制，不能与 sessionId 同传。",
          "required": false
        },
        {
          "name": "pagination",
          "type": "offset | cursor",
          "description": "默认 offset 兼容旧客户端；大数据列表建议 cursor。",
          "required": false
        },
        {
          "name": "cursor",
          "type": "string",
          "description": "cursor 模式下一页使用 nextCursor；第一页面省略。绑定当前身份、权限和筛选，不能跨账户复用。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "calls[].sessionId",
          "type": "string",
          "description": "通话唯一编号；详情使用 sessionId 查询。",
          "required": true
        },
        {
          "name": "calls[].agentId / agentName",
          "type": "string",
          "description": "保存记录时的智能体 ID 与名称。",
          "required": true
        },
        {
          "name": "calls[].conversationId",
          "type": "string",
          "description": "关联文本/客户对话 ID，无关联为空字符串。",
          "required": true
        },
        {
          "name": "calls[].mode",
          "type": "string",
          "description": "draft 或 published；历史导入值见导入规范。",
          "required": true
        },
        {
          "name": "calls[].scope",
          "type": "test | service",
          "description": "对话演练或正式服务。",
          "required": true
        },
        {
          "name": "calls[].created / updated",
          "type": "number",
          "description": "Unix 毫秒；created 为通话开始时间。",
          "required": true
        },
        {
          "name": "calls[].ended",
          "type": "number | null",
          "description": "挂断的 Unix 毫秒；未记录/未挂断为 null。",
          "required": true
        },
        {
          "name": "calls[].status",
          "type": "active | ended | handoff",
          "description": "通话状态。",
          "required": true
        },
        {
          "name": "calls[].sourceStatus",
          "type": "string | null",
          "description": "导入前的来源状态；原生记录一般为 null。",
          "required": false
        },
        {
          "name": "calls[].inputKind",
          "type": "audio | text | mixed | none",
          "description": "按实际用户轮次输入计算；静默推进不计入用户输入；通话中打字仍是语音记录。",
          "required": true
        },
        {
          "name": "calls[].turns",
          "type": "integer",
          "description": "保存的问答轮次数，不含仅连接或开场白。",
          "required": true
        },
        {
          "name": "total / page / pageSize",
          "type": "number | null / number / number",
          "description": "默认 pageSize=10；cursor 模式 total=null，不执行全量 COUNT，page 仅为展示页码。",
          "required": true
        },
        {
          "name": "scope",
          "type": "VoiceRecordFilters & {recordScope}",
          "description": "生效筛选条件，recordScope 是 scope 的兼容别名。",
          "required": true
        },
        {
          "name": "filterKey",
          "type": "string",
          "description": "包含范围和分页的筛选指纹；可用于防止旧响应覆盖新查询。",
          "required": true
        },
        {
          "name": "options.agents[]",
          "type": "{id,name}",
          "description": "offset 模式为可访问范围内的智能体；cursor 模式仅本页选项，options.source=page，仍支持直接按 agentId 查询。",
          "required": true
        },
        {
          "name": "nextCursor / hasMore / totalExact",
          "type": "string|null / boolean / false",
          "description": "cursor 模式专有；nextCursor=null 表示已到末页。",
          "required": false
        },
        {
          "name": "asOf",
          "type": "number",
          "description": "服务端当前时间，Unix 毫秒。",
          "required": true
        }
      ],
      "notes": [
        "权限由当前登录账号、企业及支持访问范围决定，不能通过传 tenant、actor 或 owner 扩大访问范围。",
        "非 tenant_admin 额外限制为本人 actor 的通话。传 conversationId 还会检查真实服务台可见性。",
        "query 搜索 sessionId、agentName、问句和回答；按 created 和 sessionId 同向排序。",
        "cursor 模式的 query 或 inputKind 检索必须提供不超过 31 天的 start/end，避免无限扫描历史正文。普通无正文筛选列表不要求日期。游标不是一致性快照，新增导入的旧时间记录可能在后续页出现。",
        "详情和导出不按游标截断；导出仍限 500 条及 5 MB，海量导出应使用独立后台任务。",
        "详情内容不在 calls 中；用 sessionId 获取完整 turns。新语音会话的录音通过 控制台录音授权入口（不接受 API Key） 授权播放和下载，旧记录可能没有音频。"
      ],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "analysis.read",
      "group": "服务结果",
      "name": "读取总结分析",
      "method": "GET",
      "currentPath": "/v1/operations/analysis.read?kind=voice&id=voice_example",
      "publicPath": "/v1/operations/analysis.read",
      "status": "available",
      "description": "导出只接受 completed 且非 stale 的分析，否则返回 409。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "?kind=voice&id=voice_example",
      "response": "{\n  \"report\": null\n}",
      "requestFields": [
        {
          "name": "kind",
          "type": "conversation | voice | workflow",
          "description": "来源类型。",
          "required": true
        },
        {
          "name": "id",
          "type": "string",
          "description": "来源 ID，最多 150 字符。",
          "required": true
        },
        {
          "name": "format",
          "type": "md | json",
          "description": "下载附件；省略时返回 {report}。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "report",
          "type": "object | null",
          "description": "分析报告；尚未生成时为 null。",
          "required": true
        }
      ],
      "notes": [
        "导出只接受 completed 且非 stale 的分析，否则返回 409。",
        "Markdown 导出返回 text/markdown 附件，不是 JSON 响应。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "analysis.generate",
      "group": "服务结果",
      "name": "总结分析 · 生成",
      "method": "POST",
      "currentPath": "/v1/operations/analysis.generate",
      "publicPath": "/v1/operations/analysis.generate",
      "status": "available",
      "description": "生成可能调用模型并计费；语音演练会话必须先挂断。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"generate\",\"kind\":\"conversation\",\"id\":\"conversation_example\"}",
      "response": "{\n  \"report\": {\n    \"status\": \"queued\"\n  }\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "generate | finish-test",
          "description": "可省略，系统固定为 generate；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "kind",
          "type": "conversation | voice | workflow",
          "description": "来源类型。",
          "required": true
        },
        {
          "name": "id",
          "type": "string",
          "description": "来源 ID。",
          "required": true
        },
        {
          "name": "retry",
          "type": "boolean",
          "description": "明确请求重新尝试生成。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "report",
          "type": "object",
          "description": "分析任务状态；不代表已经完成。",
          "required": true
        }
      ],
      "notes": [
        "生成可能调用模型并计费；语音演练会话必须先挂断。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "memory.read",
      "group": "客户资料",
      "name": "读取历史记忆",
      "method": "GET",
      "currentPath": "/v1/operations/memory.read?kind=conversation&id=TEST-TEXT-xxx",
      "publicPath": "/v1/operations/memory.read",
      "status": "available",
      "description": "仅能从有权访问的会话解析主体，不接受任意手机号或设备查询。导出再次检查源权限。",
      "scopes": [
        "service"
      ],
      "request": "?kind=conversation&id=TEST-TEXT-xxx",
      "response": "{\n  \"status\": \"manual\",\n  \"items\": [],\n  \"usage\": []\n}",
      "requestFields": [
        {
          "name": "kind",
          "type": "string",
          "description": "conversation / voice / phone / workflow",
          "required": true
        },
        {
          "name": "id",
          "type": "string",
          "description": "已授权的原记录编号",
          "required": true
        },
        {
          "name": "all",
          "type": "boolean",
          "description": "分页查询全部关联",
          "required": false
        },
        {
          "name": "format",
          "type": "string",
          "description": "json 导出",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "items",
          "type": "array",
          "description": "通过原记录权限检查的历史",
          "required": false
        },
        {
          "name": "usage",
          "type": "array",
          "description": "实际提交模型请求的来源证据",
          "required": false
        }
      ],
      "notes": [
        "仅能从有权访问的会话解析主体，不接受任意手机号或设备查询。导出再次检查源权限。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "memory.ignore",
      "group": "客户资料",
      "name": "历史记忆 · 忽略一条记录",
      "method": "POST",
      "currentPath": "/v1/operations/memory.ignore",
      "publicPath": "/v1/operations/memory.ignore",
      "status": "available",
      "description": "把指定来源记录（一次会话、通话或电话）的记忆索引标记为忽略：读取它的历史记忆时不再返回任何历史材料，它也不再作为同一主体其他会话的历史材料。同一主体的其他记录不受影响；原始会话和通话记录不会被删除。",
      "scopes": [
        "service",
        "memory.manage"
      ],
      "request": "{\"action\":\"ignore\",\"kind\":\"conversation\",\"id\":\"YOUR_CONVERSATION_ID\",\"revision\":1,\"requestId\":\"YOUR_STABLE_REQUEST_ID\"}",
      "response": "{\"ok\":true}",
      "callbackEvents": [
        "memory.invalidated"
      ],
      "requestFields": [
        {
          "name": "kind",
          "type": "string",
          "required": true,
          "description": "记忆来源类型：conversation（文字会话）、voice（语音会话）、phone（电话记录）、workflow（工作流运行）。与 memory.read 的查询参数 kind 相同。API Key 身份不能操作 workflow 来源（见说明）。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "来源记录编号，最多 150 字符，与 memory.read 的查询参数 id 相同：conversation 为会话编号，voice 为语音会话编号，phone 为电话记录编号。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "当前来源的记忆索引版本：先调用 memory.read?kind=…&id=…，取返回的 row.revision（不小于 1 的整数）。不是 row.policyVersion，也不是 items[].revision。任何一次记忆操作成功后该值都会变化。"
        },
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务幂等编号，1–100 字符。同一 requestId 且 kind、id、revision、historyId 都相同的重试直接返回成功、不重复执行；内容不同返回 409。与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true：操作已生效，或同一 requestId 的重复请求已被识别。响应不返回新的 revision。"
        }
      ],
      "notes": [
        "调用前先读取 memory.read?kind=…&id=…：返回的 row 为 null（status 为 no_identity）表示该来源没有记忆索引，本操作会返回 404；否则使用 row.revision。操作成功后 revision 会变化，继续操作前需重新读取。",
        "忽略标记写入后，开放操作中没有取消它的方法。生效后 memory.read 对该来源返回 status 为 ignored。",
        "公共错误：400「记忆来源无效」（kind 不在四个取值内）；400「会话编号格式无效」（id 为空或超过 150 字符）；400「记忆修订号无效」（revision 不是不小于 1 的整数）；400「请求编号格式无效」（requestId 为空或超过 100 字符）；404「对话不存在或无权查看」「通话不存在或无权查看」「电话记录不存在」（来源记录不存在或当前身份不可见）；404「此会话没有记忆索引」；404「演练记忆不属于当前账号」；409「记忆状态已变化，请刷新」（revision 过期）；409「操作编号已用于其他内容」（requestId 已用于不同内容）；413（请求正文超过 6000 字符）。",
        "API Key 身份：密钥需同时具备 service 与 memory.manage 权限。kind 为 workflow 的来源还要求 agent 权限，而 memory.* 操作登记的权限不含 agent，因此 API Key 调用会返回 403「无权查看工作流分析」。演练（test）环境的记忆只有创建它的账号本人可以操作，其他情况返回 404。",
        "成功后会向已订阅的回调地址发送 memory.invalidated 事件，data 含 sourceKind、sourceId 和 status（此处为 ignore）；同一 requestId 的重复请求不会再次发送。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "memory.unlink",
      "group": "客户资料",
      "name": "历史记忆 · 排除一条历史记录",
      "method": "POST",
      "currentPath": "/v1/operations/memory.unlink",
      "publicPath": "/v1/operations/memory.unlink",
      "status": "available",
      "description": "从记忆中排除一条指定的历史记录（historyId）：之后同一主体的任何会话都不会再引用它，不只是当前这一个来源。主体的其他历史记录仍然有效；原始会话和通话记录不会被删除。",
      "scopes": [
        "service",
        "memory.manage"
      ],
      "request": "{\"action\":\"unlink\",\"kind\":\"conversation\",\"id\":\"YOUR_CONVERSATION_ID\",\"revision\":1,\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"historyId\":\"YOUR_HISTORY_INDEX_ID\"}",
      "response": "{\"ok\":true}",
      "callbackEvents": [
        "memory.invalidated"
      ],
      "requestFields": [
        {
          "name": "kind",
          "type": "string",
          "required": true,
          "description": "记忆来源类型：conversation（文字会话）、voice（语音会话）、phone（电话记录）、workflow（工作流运行）。与 memory.read 的查询参数 kind 相同。API Key 身份不能操作 workflow 来源（见说明）。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "来源记录编号，最多 150 字符，与 memory.read 的查询参数 id 相同：conversation 为会话编号，voice 为语音会话编号，phone 为电话记录编号。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "当前来源的记忆索引版本：先调用 memory.read?kind=…&id=…，取返回的 row.revision（不小于 1 的整数）。不是 row.policyVersion，也不是 items[].revision。任何一次记忆操作成功后该值都会变化。"
        },
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务幂等编号，1–100 字符。同一 requestId 且 kind、id、revision、historyId 都相同的重试直接返回成功、不重复执行；内容不同返回 409。与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "historyId",
          "type": "string",
          "required": true,
          "description": "要排除的历史记录的记忆索引编号，最多 100 字符：取 memory.read 返回的 items[].indexId（加 all=true 可分页列出全部历史）。它必须与当前来源属于同一记忆主体，且不能是当前来源自己。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true：操作已生效，或同一 requestId 的重复请求已被识别。响应不返回新的 revision。"
        }
      ],
      "notes": [
        "调用前先读取 memory.read?kind=…&id=…：返回的 row 为 null（status 为 no_identity）表示该来源没有记忆索引，本操作会返回 404；否则使用 row.revision。操作成功后 revision 会变化，继续操作前需重新读取。",
        "被排除的历史记录没有开放操作可以恢复。核对结果：重新读取 memory.read，该 indexId 不再出现在 items 中。",
        "公共错误：400「记忆来源无效」（kind 不在四个取值内）；400「会话编号格式无效」（id 为空或超过 150 字符）；400「记忆修订号无效」（revision 不是不小于 1 的整数）；400「请求编号格式无效」（requestId 为空或超过 100 字符）；404「对话不存在或无权查看」「通话不存在或无权查看」「电话记录不存在」（来源记录不存在或当前身份不可见）；404「此会话没有记忆索引」；404「演练记忆不属于当前账号」；409「记忆状态已变化，请刷新」（revision 过期）；409「操作编号已用于其他内容」（requestId 已用于不同内容）；413（请求正文超过 6000 字符）。 本操作另有：404「关联不存在」（historyId 缺失、不是字符串、不属于同一主体，或就是当前来源）；400「关联编号格式无效」（historyId 为空字符串或超过 100 字符）；被排除的历史记录本身对当前身份不可见时，同样返回上述 404。",
        "API Key 身份：密钥需同时具备 service 与 memory.manage 权限。kind 为 workflow 的来源还要求 agent 权限，而 memory.* 操作登记的权限不含 agent，因此 API Key 调用会返回 403「无权查看工作流分析」。演练（test）环境的记忆只有创建它的账号本人可以操作，其他情况返回 404。",
        "成功后会向已订阅的回调地址发送 memory.invalidated 事件，data 含 sourceKind、sourceId 和 status（此处为 unlink）；同一 requestId 的重复请求不会再次发送。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "memory.forget",
      "group": "客户资料",
      "name": "历史记忆 · 遗忘",
      "method": "POST",
      "currentPath": "/v1/operations/memory.forget",
      "publicPath": "/v1/operations/memory.forget",
      "status": "available",
      "description": "演练记录仅创建人可操作；正式记录需要独立记忆管理权限。清除不删除原始对话，已发给供应商的材料不能物理撤回。",
      "scopes": [
        "service",
        "memory.manage"
      ],
      "request": "{\"action\":\"forget\",\"kind\":\"conversation\",\"id\":\"TEST-TEXT-xxx\",\"revision\":1,\"requestId\":\"uuid\"}",
      "response": "{\n  \"ok\": true\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "string",
          "description": "可省略，系统固定为 forget；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "revision",
          "type": "number",
          "description": "当前记忆修订号",
          "required": true
        },
        {
          "name": "requestId",
          "type": "string",
          "description": "幂等操作编号",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "description": "记忆管理动作已提交；历史对话本身仍然保留。",
          "required": true
        }
      ],
      "notes": [
        "演练记录仅创建人可操作；正式记录需要独立记忆管理权限。清除不删除原始对话，已发给供应商的材料不能物理撤回。"
      ],
      "callbackEvents": [
        "memory.invalidated"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "memory.block",
      "group": "客户资料",
      "name": "历史记忆 · 遗忘并禁止再次使用",
      "method": "POST",
      "currentPath": "/v1/operations/memory.block",
      "publicPath": "/v1/operations/memory.block",
      "status": "available",
      "description": "把指定来源所属的记忆主体（同一智能体下的同一客户档案、电话号码或设备身份）标记为禁用：该主体已登记的全部历史记录立即失效（这一点与 memory.forget 相同），并且之后该主体的新会话也不再登记或使用历史记忆。原始会话和通话记录不会被删除。",
      "scopes": [
        "service",
        "memory.manage"
      ],
      "request": "{\"action\":\"block\",\"kind\":\"conversation\",\"id\":\"YOUR_CONVERSATION_ID\",\"revision\":1,\"requestId\":\"YOUR_STABLE_REQUEST_ID\"}",
      "response": "{\"ok\":true}",
      "callbackEvents": [
        "memory.invalidated"
      ],
      "requestFields": [
        {
          "name": "kind",
          "type": "string",
          "required": true,
          "description": "记忆来源类型：conversation（文字会话）、voice（语音会话）、phone（电话记录）、workflow（工作流运行）。与 memory.read 的查询参数 kind 相同。API Key 身份不能操作 workflow 来源（见说明）。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "来源记录编号，最多 150 字符，与 memory.read 的查询参数 id 相同：conversation 为会话编号，voice 为语音会话编号，phone 为电话记录编号。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "当前来源的记忆索引版本：先调用 memory.read?kind=…&id=…，取返回的 row.revision（不小于 1 的整数）。不是 row.policyVersion，也不是 items[].revision。任何一次记忆操作成功后该值都会变化。"
        },
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务幂等编号，1–100 字符。同一 requestId 且 kind、id、revision、historyId 都相同的重试直接返回成功、不重复执行；内容不同返回 409。与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true：操作已生效，或同一 requestId 的重复请求已被识别。响应不返回新的 revision。"
        }
      ],
      "notes": [
        "调用前先读取 memory.read?kind=…&id=…：返回的 row 为 null（status 为 no_identity）表示该来源没有记忆索引，本操作会返回 404；否则使用 row.revision。操作成功后 revision 会变化，继续操作前需重新读取。",
        "禁用是针对整个主体的，开放操作中没有解除禁用的方法，执行前请确认范围；只想清空已有历史而保留今后的记忆能力时，请改用 memory.forget。生效后 memory.read 对该主体已有的来源返回 status 为 blocked；之后新产生的会话不再建立记忆索引，读取时 status 为 no_identity。",
        "公共错误：400「记忆来源无效」（kind 不在四个取值内）；400「会话编号格式无效」（id 为空或超过 150 字符）；400「记忆修订号无效」（revision 不是不小于 1 的整数）；400「请求编号格式无效」（requestId 为空或超过 100 字符）；404「对话不存在或无权查看」「通话不存在或无权查看」「电话记录不存在」（来源记录不存在或当前身份不可见）；404「此会话没有记忆索引」；404「演练记忆不属于当前账号」；409「记忆状态已变化，请刷新」（revision 过期）；409「操作编号已用于其他内容」（requestId 已用于不同内容）；413（请求正文超过 6000 字符）。",
        "API Key 身份：密钥需同时具备 service 与 memory.manage 权限。kind 为 workflow 的来源还要求 agent 权限，而 memory.* 操作登记的权限不含 agent，因此 API Key 调用会返回 403「无权查看工作流分析」。演练（test）环境的记忆只有创建它的账号本人可以操作，其他情况返回 404。",
        "成功后会向已订阅的回调地址发送 memory.invalidated 事件，data 含 sourceKind、sourceId 和 status（此处为 block）；同一 requestId 的重复请求不会再次发送。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "customers.read",
      "name": "读取客户资料",
      "group": "客户资料",
      "method": "GET",
      "currentPath": "/v1/operations/customers.read",
      "publicPath": "/v1/operations/customers.read",
      "status": "available",
      "description": "GET 依照 view 等查询读取客户、字段、导入任务与已有分页；不是统一 cursor/limit REST 协议。批量导入必须按后台分批协议执行，失败项不代表全部成功。客户写入同时受字段、客户和目录版本约束。",
      "scopes": [
        "customers"
      ],
      "request": "?",
      "response": "{\"customers\":[],\"links\":[],\"page\":1,\"total\":0}",
      "requestFields": [],
      "responseFields": [
        {
          "name": "catalog",
          "description": "字段定义、目录 revision 和 fieldRevision。",
          "type": "object",
          "required": false
        },
        {
          "name": "customers / links",
          "description": "列表分支的客户及可见会话关联。",
          "type": "array",
          "required": false
        },
        {
          "name": "customer",
          "description": "单客户详情分支的资料。",
          "type": "object",
          "required": false
        },
        {
          "name": "jobs",
          "description": "importJobs 查询的批量导入进度。",
          "type": "array",
          "required": false
        },
        {
          "name": "page / total",
          "description": "页码分支的当前页与总数。",
          "type": "integer",
          "required": false
        },
        {
          "name": "nextCursor",
          "description": "游标分支的下一页标识，结束时为 null。",
          "type": "string | null",
          "required": false
        }
      ],
      "notes": [
        "响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。",
        "GET 依照 view 等查询读取客户、字段、导入任务与已有分页；不是统一 cursor/limit REST 协议。批量导入必须按后台分批协议执行，失败项不代表全部成功。客户写入同时受字段、客户和目录版本约束。",
        "应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "customers.save",
      "group": "客户资料",
      "name": "客户资料 · 保存",
      "method": "POST",
      "status": "available",
      "currentPath": "/v1/operations/customers.save",
      "publicPath": "/v1/operations/customers.save",
      "scopes": [
        "customers"
      ],
      "description": "新建或更新一位客户，保存姓名、联系方式、公司及自定义资料。",
      "request": "{\"requestId\":\"customer_example_1\",\"revision\":12,\"fieldRevision\":3,\"customer\":{\"name\":\"示例客户\",\"phone\":\"+8613800138000\",\"email\":\"customer@example.test\",\"company\":\"示例企业\"},\"action\":\"save\"}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，仍须请求头 Idempotency-Key。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "先查询 customers.read?schema=1，使用 catalog.revision。"
        },
        {
          "name": "fieldRevision",
          "type": "integer",
          "required": true,
          "description": "同一查询返回的 catalog.fieldRevision。"
        },
        {
          "name": "customer",
          "type": "object",
          "required": true,
          "description": "本次保存的客户资料。"
        },
        {
          "name": "customer.name",
          "type": "string",
          "requiredWhen": "新建客户",
          "description": "姓名，最多 200 字符；更新时省略则保留旧值。"
        },
        {
          "name": "customer.phone",
          "type": "string",
          "required": false,
          "description": "手机号，最多 200 字符。"
        },
        {
          "name": "customer.email",
          "type": "string",
          "required": false,
          "description": "邮箱，最多 200 字符；非空时须为有效邮箱。"
        },
        {
          "name": "customer.company",
          "type": "string",
          "required": false,
          "description": "公司名称，最多 200 字符。"
        },
        {
          "name": "customer.id",
          "type": "string",
          "requiredWhen": "更新已有客户",
          "description": "先查询 customers.read?id=客户编号，使用 customer.id。"
        },
        {
          "name": "customer.revision",
          "type": "integer",
          "requiredWhen": "更新已有客户",
          "description": "同一查询返回的 customer.revision，与目录 revision 不同。"
        },
        {
          "name": "customer.values",
          "type": "object",
          "required": false,
          "description": "按 catalog.fields 的键、类型和必填规则校验；更新时省略则保留旧值，新建默认为空对象。"
        },
        {
          "name": "customer.namespace",
          "type": "string",
          "requiredWhen": "externalId 非空且原档案没有 namespace",
          "description": "外部客户编号的来源范围，最多 200 字符；更新时省略则沿用原值。"
        },
        {
          "name": "customer.externalId",
          "type": "string",
          "required": false,
          "description": "外部客户编号，最多 200 字符；与 namespace 共同唯一。"
        },
        {
          "name": "validateOnly",
          "type": "boolean",
          "required": false,
          "description": "默认 false；true 只校验，不保存客户。"
        }
      ],
      "response": "{\"ok\":true,\"ids\":[\"USR_EXAMPLE\"],\"count\":1}",
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "requiredWhen": "保存成功",
          "description": "true 表示保存完成；仅校验时不返回。"
        },
        {
          "name": "ids",
          "type": "string[]",
          "requiredWhen": "保存成功",
          "description": "已保存客户的编号；仅校验时不返回。"
        },
        {
          "name": "count",
          "type": "integer",
          "required": true,
          "description": "本次保存或校验的客户数，为 1。"
        },
        {
          "name": "valid",
          "type": "boolean",
          "requiredWhen": "仅校验成功",
          "description": "true 表示校验通过，不代表已保存。"
        },
        {
          "name": "fieldRevision",
          "type": "integer",
          "requiredWhen": "仅校验成功",
          "description": "本次校验使用的字段版本。"
        }
      ],
      "callbackEvents": [],
      "notes": [
        "示例中的版本号须替换为读取值；保存不返回新版本，后续更新前须重新读取。",
        "更新时未提供的资料保留旧值；清空可选文本传空字符串，自定义字段按键更新。客户不会按手机号自动合并，重复外部身份会拒绝保存。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "customers.import",
      "group": "客户资料",
      "name": "客户资料 · 批量导入客户",
      "method": "POST",
      "currentPath": "/v1/operations/customers.import",
      "publicPath": "/v1/operations/customers.import",
      "status": "available",
      "description": "把一批客户资料（1–200 行）校验后同步写入客户档案：任一行不合格则整批都不写入。按 namespace + externalId 识别已有客户，strategy 为 update 时覆盖，否则报重复；没有外部编号的行总是新建。可以单独调用，也可以带 jobId 作为 customers.importStart 任务的一个分批。不会发送消息或拨打电话。",
      "scopes": [
        "customers"
      ],
      "request": "{\"action\":\"import\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"fieldRevision\":3,\"strategy\":\"create\",\"rows\":[{\"name\":\"示例客户\",\"namespace\":\"crm-main\",\"externalId\":\"CUST-1001\",\"phone\":\"13800138000\",\"email\":\"customer@example.test\",\"company\":\"示例企业\"}]}",
      "response": "{\"ok\":true,\"ids\":[\"USR-00000000-0000-4000-8000-000000000000\"],\"count\":1}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "客户目录版本号：先调用 customers.read?schema=1，取返回的 catalog.revision。本企业每次客户资料写入成功后该值都会 +1，而写入响应不返回新值，所以每次写入前都要重新读取。"
        },
        {
          "name": "fieldRevision",
          "type": "integer",
          "required": true,
          "description": "自定义字段版本：同一次 customers.read?schema=1 返回的 catalog.fieldRevision；不一致返回 409。"
        },
        {
          "name": "rows",
          "type": "object[]",
          "required": true,
          "description": "客户行数组。不带 jobId 时 1–200 行；带 jobId 时 1–100 行，且不能超出任务剩余行数。整个请求正文还受网关 150000 字符上限限制，超出返回 413，应减少每批行数。"
        },
        {
          "name": "rows[].name",
          "type": "string",
          "requiredWhen": "该行是新建客户（没有命中已有的 namespace + externalId）",
          "description": "客户姓名，去掉首尾空格后不能为空，最多 200 字符。覆盖已有客户时省略则保留原值。"
        },
        {
          "name": "rows[].namespace",
          "type": "string",
          "requiredWhen": "该行填写了 externalId",
          "description": "外部编号的来源范围（例如店铺或 CRM 连接的标识），最多 200 字符。"
        },
        {
          "name": "rows[].externalId",
          "type": "string",
          "required": false,
          "description": "外部客户编号，最多 200 字符。namespace + externalId 在企业内唯一，是导入识别已有客户的唯一依据；同一批内不能重复。省略则该行总是新建客户，不会按手机号或姓名合并。"
        },
        {
          "name": "rows[].phone",
          "type": "string",
          "required": false,
          "description": "联系电话，最多 200 字符，不校验号码格式；但不能提交带 * 号的脱敏号码（覆盖已有客户且与原号码的脱敏形式一致时视为未修改）。"
        },
        {
          "name": "rows[].email",
          "type": "string",
          "required": false,
          "description": "电子邮箱，最多 200 字符；非空时必须是 name@domain.tld 形式。"
        },
        {
          "name": "rows[].wechat",
          "type": "string",
          "required": false,
          "description": "微信号，最多 200 字符。"
        },
        {
          "name": "rows[].company",
          "type": "string",
          "required": false,
          "description": "所属企业，最多 200 字符。"
        },
        {
          "name": "rows[].category",
          "type": "string",
          "required": false,
          "description": "用户分类，最多 200 字符。"
        },
        {
          "name": "rows[].notes",
          "type": "string",
          "required": false,
          "description": "资料备注，最多 2000 字符。"
        },
        {
          "name": "rows[].values",
          "type": "object",
          "required": false,
          "description": "自定义字段值，键为 catalog.fields[].key（未停用的字段）。text、select 最多 500 字符，textarea 最多 2000 字符；number 为数字或数字字符串（绝对值不超过 1e15）；boolean 接受 true、false、\"是\"、\"否\"、\"1\"、\"0\"；date 为 YYYY-MM-DD；select 必须在该字段 options 内；multiselect 为 options 内的字符串数组（最多 30 项，也可传 JSON 数组字符串）。传 null 或空字符串清除该键。定义为必填的字段每行都必须有值。"
        },
        {
          "name": "rows[].tags",
          "type": "string[]",
          "required": false,
          "description": "客户标签，最多 20 个，每个 1–30 字符。省略则保留已有客户的标签（新建客户为空）。企业启用了标签组管理（catalog.tagGroupsManaged 为 true）时，只能使用 catalog.tagGroups 中适用于客户且未停用的标签。"
        },
        {
          "name": "strategy",
          "type": "string",
          "requiredWhen": "携带 jobId",
          "description": "重复数据策略：update 表示命中已有 namespace + externalId 的行覆盖该客户（行内未提供的资料保留原值）；create 或省略表示命中即报错「外部来源和编号已存在」。带 jobId 时必须与创建任务时的 strategy 相同。"
        },
        {
          "name": "jobId",
          "type": "string",
          "required": false,
          "description": "customers.importStart 返回的 jobId。携带后本次请求作为该任务的一个分批，写入成功后推进任务进度；只能由创建任务的同一账号使用。"
        },
        {
          "name": "offset",
          "type": "integer",
          "requiredWhen": "携带 jobId",
          "description": "本批第一行在任务中的位置，必须等于任务当前的 processed（首批为 0）：通过 customers.read?importJobs=1&jobId=任务编号 读取 jobs[0].processed。"
        },
        {
          "name": "validateOnly",
          "type": "boolean",
          "required": false,
          "description": "为 true 时只执行相同的校验并返回 valid、count、fieldRevision，不写入客户、不推进任务。默认 false。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "requiredWhen": "已写入（未使用 validateOnly）",
          "description": "固定为 true，表示本批已写入。"
        },
        {
          "name": "ids",
          "type": "string[]",
          "requiredWhen": "已写入（未使用 validateOnly）",
          "description": "按 rows 的顺序返回每行写入的客户编号：新建客户为 USR- 开头的新编号，覆盖时为原客户编号。"
        },
        {
          "name": "count",
          "type": "integer",
          "required": true,
          "description": "本批写入或校验通过的行数。"
        },
        {
          "name": "processed",
          "type": "integer",
          "requiredWhen": "携带 jobId 且已写入",
          "description": "任务累计已处理的行数。"
        },
        {
          "name": "jobId",
          "type": "string",
          "requiredWhen": "携带 jobId 且已写入",
          "description": "任务编号。"
        },
        {
          "name": "valid",
          "type": "boolean",
          "requiredWhen": "validateOnly 为 true 且校验通过",
          "description": "固定为 true，表示校验通过；不代表已写入。"
        },
        {
          "name": "fieldRevision",
          "type": "integer",
          "requiredWhen": "validateOnly 为 true 且校验通过",
          "description": "本次校验使用的字段版本。"
        },
        {
          "name": "error",
          "type": "string",
          "requiredWhen": "HTTP 400 且存在行校验错误",
          "description": "固定为「校验失败，未写入任何用户」。"
        },
        {
          "name": "errors",
          "type": "object[]",
          "requiredWhen": "HTTP 400 且存在行校验错误",
          "description": "每个不合格的行一项：errors[].row 是本批内从 1 开始的行号，errors[].error 是原因。"
        }
      ],
      "notes": [
        "调用前先读取 customers.read?schema=1，取 catalog.revision、catalog.fieldRevision 和字段定义 catalog.fields。revision 在每次写入成功后 +1，连续提交多批时每一批之前都要重新读取。",
        "本操作特有的错误：400 且响应带 errors[]（有行不合格，整批未写入，任务进度不变）；400「每批支持 1–200 位用户」（rows 为空、不是数组或超过 200 行）；400「分批大小或进度超出任务范围」（带 jobId 时超过 100 行或超出任务总行数）；404「导入任务不存在」（jobId 不存在或不属于当前账号）；409「资料已变化，请刷新后重试」（revision 过期）；409「字段定义已变化，请重新校验」（fieldRevision 过期）；409「任务进度已变化，请刷新任务后继续」（offset 不等于任务的 processed，或任务已完成）；409「导入字段定义或策略已变化，任务已暂停」（任务创建后字段定义有变化，或 strategy 与任务不一致）；413（正文超过 150000 字符）。",
        "重试：结果未知时保持原 requestId 和原正文重试，不会重复写入。没有 externalId 的行如果换一个 requestId 重发，会再次新建客户。",
        "rows[] 里的 id、revision、confirmation 不生效：导入不能按客户编号更新；写入的客户一律标记为未确认（confirmation 为 unconfirmed），来源记为「CSV 导入」。",
        "API Key 身份可以调用，没有额外限制；写入的操作人记为密钥所属的企业管理员。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "customers.importStart",
      "group": "客户资料",
      "name": "客户资料 · 创建分批导入任务",
      "method": "POST",
      "currentPath": "/v1/operations/customers.importStart",
      "publicPath": "/v1/operations/customers.importStart",
      "status": "available",
      "description": "登记一个分批导入任务（文件名、文件指纹、总行数、列映射和重复数据策略）并返回 jobId，用于把一个大文件（最多 100000 行）拆成多批提交并记录进度。本操作不写入任何客户；之后用 customers.import 携带 jobId 按顺序提交，每批最多 100 行，全部行提交完后任务变为 completed。每一批都是同步写入，没有后台处理。",
      "scopes": [
        "customers"
      ],
      "request": "{\"action\":\"importStart\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"fileName\":\"customers.csv\",\"fileHash\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"total\":250,\"mapping\":[\"name\",\"phone\",\"email\",\"company\"],\"strategy\":\"create\"}",
      "response": "{\"ok\":true,\"jobId\":\"IMPORT-00000000-0000-4000-8000-000000000000\"}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "客户目录版本号：先调用 customers.read?schema=1，取返回的 catalog.revision。本企业每次客户资料写入成功后该值都会 +1，而写入响应不返回新值，所以每次写入前都要重新读取。"
        },
        {
          "name": "fileName",
          "type": "string",
          "required": true,
          "description": "源文件名，1–200 字符，仅用于在任务列表中识别。"
        },
        {
          "name": "fileHash",
          "type": "string",
          "required": true,
          "description": "源文件指纹：64 个字符，只能包含小写十六进制字符（0-9、a-f）或连字符，例如文件的 SHA-256。之后可用它找回任务；服务端不核对它与实际数据是否对应。"
        },
        {
          "name": "total",
          "type": "integer",
          "required": true,
          "description": "任务总行数，1–100000 的整数。任务创建后不能修改。"
        },
        {
          "name": "mapping",
          "type": "string[]",
          "required": true,
          "description": "源文件各列对应的目标键，按列顺序排列，1–60 项；要跳过的列填空字符串。必须包含 name 或 enterpriseName，非空项不能重复。可用的键：name、namespace、externalId、phone、email、wechat、company、category、notes、tags、enterpriseName、enterpriseCreditCode、enterprisePhone、enterpriseEmail、values.<未停用自定义字段的 key>、notes:<URL 编码后的列名>。enterpriseName 不能与 company 同时使用，enterprisePhone 不能与 phone 同时使用，enterpriseEmail 不能与 email 同时使用，enterpriseCreditCode 不能与 namespace 或 externalId 同时使用。服务端只保存这份映射，不会用它转换 customers.import 提交的 rows。"
        },
        {
          "name": "strategy",
          "type": "string",
          "required": true,
          "description": "重复数据策略，create 或 update，含义同 customers.import；任务的每一批都必须使用相同的值。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，表示本次写入已提交。"
        },
        {
          "name": "jobId",
          "type": "string",
          "required": true,
          "description": "新任务编号（IMPORT- 开头），在 customers.import 中作为 jobId 使用。"
        }
      ],
      "notes": [
        "调用前先读取 customers.read?schema=1，取 catalog.revision。任务会记下创建时的 catalog.fieldRevision；之后字段定义一旦变化，该任务就不能继续，需要重新创建。",
        "后续步骤：调用 customers.import，携带 jobId、offset（等于任务当前的 processed）、与任务相同的 strategy，以及每批最多 100 行的 rows。进度通过 customers.read?importJobs=1&jobId=任务编号 读取 jobs[0].processed 与 jobs[0].status（ready → running → completed）；也可以用 importJobs=1&fileHash=文件指纹 找回任务。该查询只返回当前账号最近更新的 30 个任务。",
        "本操作特有的错误：400「文件信息无效，单任务最多 100000 行」（total 不是 1–100000 的整数，或 fileHash 格式不符）；400「字段映射无效或重复」；400「重复数据策略无效」；400「文件名格式无效」（fileName 为空或超过 200 字符）；409「资料已变化，请刷新后重试」（revision 过期）。",
        "API Key 身份可以调用。任务归属于密钥所属的企业管理员账号，只有同一账号可以继续提交和查询。开放操作中没有取消或删除导入任务的操作。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "customers.crmSave",
      "group": "客户资料",
      "name": "客户资料 · 保存跟进设置",
      "method": "POST",
      "currentPath": "/v1/operations/customers.crmSave",
      "publicPath": "/v1/operations/customers.crmSave",
      "status": "available",
      "description": "保存一位客户的跟进设置：负责人、跟进阶段、优先级、下次跟进时间，并可同时整体替换客户标签。不修改姓名、电话等档案字段（请用 customers.save），不新增跟进记录（请用 customers.crmFollowup），也不会联系客户。",
      "scopes": [
        "customers"
      ],
      "request": "{\"action\":\"crmSave\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"customerId\":\"YOUR_CUSTOMER_ID\",\"customerRevision\":4,\"crmRevision\":0,\"crm\":{\"ownerId\":\"YOUR_MEMBER_ID\",\"stage\":\"following\",\"priority\":\"normal\",\"nextAt\":0}}",
      "response": "{\"ok\":true,\"customerId\":\"YOUR_CUSTOMER_ID\",\"crmRevision\":1}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "customerId",
          "type": "string",
          "required": true,
          "description": "客户编号，最多 100 字符：取 customers.read 或 customer-crm.read 返回的 customer.id。已归档的客户按不存在处理。"
        },
        {
          "name": "customerRevision",
          "type": "integer",
          "required": true,
          "description": "客户档案版本：先调用 customer-crm.read?id=客户编号，取返回的 customer.revision。"
        },
        {
          "name": "crmRevision",
          "type": "integer",
          "required": true,
          "description": "跟进设置版本：同一次 customer-crm.read 返回的 crm.revision；从未保存过跟进设置的客户为 0。"
        },
        {
          "name": "crm",
          "type": "object",
          "required": true,
          "description": "完整的跟进设置。四个子字段每次都必须全部提供，不支持只传有变化的项。"
        },
        {
          "name": "crm.ownerId",
          "type": "string",
          "required": true,
          "description": "负责人的成员编号，最多 100 字符：取 customer-crm.read 返回的 owners[].id；空字符串表示不指定负责人。必须是本企业启用中且拥有客户或客服权限的成员。"
        },
        {
          "name": "crm.stage",
          "type": "string",
          "required": true,
          "description": "跟进阶段：new（新客户）、following（跟进中）、qualified（意向客户）、customer（已成交）、inactive（暂不跟进）。"
        },
        {
          "name": "crm.priority",
          "type": "string",
          "required": true,
          "description": "跟进优先级：normal（普通）、high（重点）、low（低优先）。"
        },
        {
          "name": "crm.nextAt",
          "type": "integer",
          "required": true,
          "description": "下次跟进时间，Unix 毫秒；0 表示不安排。大于 0 时必须晚于当前时间（与已保存的值相同时除外）、必须已指定负责人、且 stage 不能是 inactive；上限 4133980800000。"
        },
        {
          "name": "tags",
          "type": "string[]",
          "required": false,
          "description": "提供时整体替换该客户的标签：最多 20 个，每个 1–30 字符。省略则保留现有标签。企业启用了标签组管理（catalog.tagGroupsManaged 为 true）时，只能使用 catalog.tagGroups 中适用于客户且未停用的标签，客户已有的标签可以保留。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，表示本次写入已提交。"
        },
        {
          "name": "customerId",
          "type": "string",
          "required": true,
          "description": "本次保存的客户编号。"
        },
        {
          "name": "crmRevision",
          "type": "integer",
          "required": true,
          "description": "保存后的跟进设置版本（原值 +1）。客户档案的 customer.revision 也会 +1，但不在响应中，下次写入前需重新读取。"
        }
      ],
      "notes": [
        "调用前先读取 customer-crm.read?id=客户编号，取 customer.revision、crm.revision 和可选负责人 owners；本操作不需要目录 revision 和 fieldRevision。",
        "与 customers.save 的关系：customers.save 修改档案字段（姓名、联系方式、自定义字段），本操作修改跟进设置和标签；两者都会让同一客户的 customer.revision +1，交替调用时每次都要重新读取。",
        "本操作特有的错误：400「客户编号无效」；404「客户不存在」（含已归档）；409「客户或跟进资料已更新，请重新载入后编辑」（customerRevision 或 crmRevision 过期）；400「跟进设置格式无效」「请选择有效负责人、跟进状态和优先级」「下次跟进时间无效」「下次跟进时间须晚于当前时间」「设置跟进计划前，请先指定负责人」「暂不跟进的客户请清空下次跟进时间」（crm 校验）；400「负责人须为本企业启用且有客户或客服权限的成员」；400（tags 超过 20 个、单个标签为空或超过 30 字符，或启用标签组管理时选了已停用、不适用于客户的标签）；400「请先由企业管理员在标签管理创建标签，再重新选择」（启用标签组管理时使用了目录中没有的标签）；409「资料或权限已更新，请重新加载；输入已保留」（提交瞬间客户、跟进设置、负责人或密钥状态发生变化）。",
        "API Key 身份可以调用，没有额外限制：密钥身份具备客户管理权限，可以转派负责人、调整优先级和修改标签。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "customers.crmFollowup",
      "group": "客户资料",
      "name": "客户资料 · 添加跟进记录",
      "method": "POST",
      "currentPath": "/v1/operations/customers.crmFollowup",
      "publicPath": "/v1/operations/customers.crmFollowup",
      "status": "available",
      "description": "为一位客户追加一条跟进记录（沟通方式和内容），同时按请求中的 crm 保存跟进设置，并把最近跟进时间更新为当前时间。只写入业务记录，不会真的拨打电话或发送消息；记录写入后不能通过开放操作修改或删除。",
      "scopes": [
        "customers"
      ],
      "request": "{\"action\":\"crmFollowup\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"customerId\":\"YOUR_CUSTOMER_ID\",\"customerRevision\":4,\"crmRevision\":1,\"crm\":{\"ownerId\":\"YOUR_MEMBER_ID\",\"stage\":\"following\",\"priority\":\"normal\",\"nextAt\":0},\"followup\":{\"kind\":\"phone\",\"content\":\"已电话确认需求，客户希望下周收到报价。\"}}",
      "response": "{\"ok\":true,\"customerId\":\"YOUR_CUSTOMER_ID\",\"crmRevision\":2}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "customerId",
          "type": "string",
          "required": true,
          "description": "客户编号，最多 100 字符：取 customers.read 或 customer-crm.read 返回的 customer.id。已归档的客户按不存在处理。"
        },
        {
          "name": "customerRevision",
          "type": "integer",
          "required": true,
          "description": "客户档案版本：先调用 customer-crm.read?id=客户编号，取返回的 customer.revision。"
        },
        {
          "name": "crmRevision",
          "type": "integer",
          "required": true,
          "description": "跟进设置版本：同一次 customer-crm.read 返回的 crm.revision；从未保存过跟进设置的客户为 0。"
        },
        {
          "name": "followup",
          "type": "object",
          "required": true,
          "description": "本次要追加的跟进记录。"
        },
        {
          "name": "followup.kind",
          "type": "string",
          "required": true,
          "description": "沟通方式：note（跟进备注）、phone（电话沟通）、wechat（微信沟通）、email（邮件沟通）、meeting（会议沟通）。"
        },
        {
          "name": "followup.content",
          "type": "string",
          "required": true,
          "description": "跟进内容，1–3000 字符，去掉首尾空格后不能为空。"
        },
        {
          "name": "crm",
          "type": "object",
          "required": true,
          "description": "完整的跟进设置，必须提供。只想追加记录时，原样回传 customer-crm.read 返回的 crm.ownerId、crm.stage、crm.priority、crm.nextAt；修改其中的值会随本次请求一起保存。"
        },
        {
          "name": "crm.ownerId",
          "type": "string",
          "required": true,
          "description": "负责人的成员编号，最多 100 字符：取 customer-crm.read 返回的 owners[].id；空字符串表示不指定负责人。必须是本企业启用中且拥有客户或客服权限的成员。"
        },
        {
          "name": "crm.stage",
          "type": "string",
          "required": true,
          "description": "跟进阶段：new（新客户）、following（跟进中）、qualified（意向客户）、customer（已成交）、inactive（暂不跟进）。"
        },
        {
          "name": "crm.priority",
          "type": "string",
          "required": true,
          "description": "跟进优先级：normal（普通）、high（重点）、low（低优先）。"
        },
        {
          "name": "crm.nextAt",
          "type": "integer",
          "required": true,
          "description": "下次跟进时间，Unix 毫秒；0 表示不安排。大于 0 时必须晚于当前时间（与已保存的值相同时除外）、必须已指定负责人、且 stage 不能是 inactive；上限 4133980800000。"
        },
        {
          "name": "tags",
          "type": "string[]",
          "required": false,
          "description": "提供时整体替换该客户的标签：最多 20 个，每个 1–30 字符。省略则保留现有标签。企业启用了标签组管理（catalog.tagGroupsManaged 为 true）时，只能使用 catalog.tagGroups 中适用于客户且未停用的标签，客户已有的标签可以保留。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，表示本次写入已提交。"
        },
        {
          "name": "customerId",
          "type": "string",
          "required": true,
          "description": "本次保存的客户编号。"
        },
        {
          "name": "crmRevision",
          "type": "integer",
          "required": true,
          "description": "保存后的跟进设置版本（原值 +1）。客户档案的 customer.revision 也会 +1，但不在响应中，下次写入前需重新读取。"
        }
      ],
      "notes": [
        "调用前先读取 customer-crm.read?id=客户编号，取 customer.revision、crm.revision 和可选负责人 owners；本操作不需要目录 revision 和 fieldRevision。",
        "响应不返回新跟进记录的编号。需要时调用 customer-crm.read?id=客户编号 读取 followups[]（按时间倒序，每页 20 条，用返回的 nextCursor 作为 cursor 参数翻页）；每条记录含 id、kind、content、actorId、actorName、created、nextAt。",
        "本操作特有的错误：400「客户编号无效」；404「客户不存在」（含已归档）；409「客户或跟进资料已更新，请重新载入后编辑」（customerRevision 或 crmRevision 过期）；400「跟进设置格式无效」「请选择有效负责人、跟进状态和优先级」「下次跟进时间无效」「下次跟进时间须晚于当前时间」「设置跟进计划前，请先指定负责人」「暂不跟进的客户请清空下次跟进时间」（crm 校验）；400「负责人须为本企业启用且有客户或客服权限的成员」；400（tags 超过 20 个、单个标签为空或超过 30 字符，或启用标签组管理时选了已停用、不适用于客户的标签）；400「请先由企业管理员在标签管理创建标签，再重新选择」（启用标签组管理时使用了目录中没有的标签）；409「资料或权限已更新，请重新加载；输入已保留」（提交瞬间客户、跟进设置、负责人或密钥状态发生变化）。 另有 400「请填写跟进记录（1–3000 字）并选择沟通方式」（followup 缺失、kind 无效或 content 为空、超长）。",
        "重试：结果未知时保持原 requestId 和原正文重试，不会重复追加。如果首次请求其实已经成功，换一个 requestId 重发会因版本号已过期返回 409；重新读取版本后再提交才会追加第二条。",
        "与 customers.save 的关系：customers.save 修改档案字段（姓名、联系方式、自定义字段），本操作修改跟进设置和标签；两者都会让同一客户的 customer.revision +1，交替调用时每次都要重新读取。",
        "API Key 身份可以调用，没有额外限制；跟进记录的操作人（actorId、actorName）记为密钥所属的企业管理员。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "customers.fields",
      "group": "客户资料",
      "name": "客户资料 · 保存自定义字段定义",
      "method": "POST",
      "currentPath": "/v1/operations/customers.fields",
      "publicPath": "/v1/operations/customers.fields",
      "status": "available",
      "description": "用提交的列表整体替换企业的客户自定义字段定义（最多 50 个），成功后 catalog.fieldRevision 和 catalog.revision 各 +1。已有字段不能删除、不能改类型、不能移除已有选项，只能改名称、分组、是否必填、是否提供给智能体或停用。不修改任何客户已保存的字段值。",
      "scopes": [
        "customers"
      ],
      "request": "{\"action\":\"fields\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"fields\":[{\"key\":\"memberLevel\",\"label\":\"会员等级\",\"group\":\"业务资料\",\"type\":\"select\",\"options\":[\"普通\",\"黄金\"],\"required\":false,\"ai\":true,\"archived\":false}]}",
      "response": "{\"ok\":true}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "客户目录版本号：先调用 customers.read?schema=1，取返回的 catalog.revision。本企业每次客户资料写入成功后该值都会 +1，而写入响应不返回新值，所以每次写入前都要重新读取。"
        },
        {
          "name": "fields",
          "type": "object[]",
          "required": true,
          "description": "完整的字段定义列表，0–50 项：必须包含 customers.read?schema=1 返回的 catalog.fields 中全部已有字段（按 key 对应），再加上要新增的字段；缺少任何一个已有 key 都会被拒绝。数组顺序就是保存后的顺序。"
        },
        {
          "name": "fields[].key",
          "type": "string",
          "required": true,
          "description": "字段标识：字母开头，只含字母、数字、下划线，1–50 字符，列表内唯一，不能是 constructor、prototype 或 __proto__。它就是客户资料 values 对象里的键，创建后不能更改。"
        },
        {
          "name": "fields[].label",
          "type": "string",
          "required": true,
          "description": "字段显示名称，1–60 字符，不能全是空白。"
        },
        {
          "name": "fields[].type",
          "type": "string",
          "required": true,
          "description": "字段类型：text（单行文本）、textarea（多行文本）、number（数值）、boolean（是 / 否）、date（日期）、select（单选）、multiselect（多选）。已有字段不能更改类型。"
        },
        {
          "name": "fields[].options",
          "type": "string[]",
          "requiredWhen": "type 为 select 或 multiselect",
          "description": "选项列表：去掉空白和重复后 1–30 项，每项最多 80 字符。已有字段原来的选项必须全部保留，只能追加。"
        },
        {
          "name": "fields[].group",
          "type": "string",
          "required": false,
          "description": "分组名称，超过 40 字符的部分会被截断；省略或为空时为「业务资料」。"
        },
        {
          "name": "fields[].required",
          "type": "boolean",
          "required": false,
          "description": "是否必填，只有 true 生效；省略即为 false，不会沿用旧值。设为必填后，之后每次保存或导入客户都必须提供该字段的值。"
        },
        {
          "name": "fields[].ai",
          "type": "boolean",
          "required": false,
          "description": "是否允许作为客户变量提供给智能体。省略时已有字段沿用旧值，新字段默认为 true。"
        },
        {
          "name": "fields[].archived",
          "type": "boolean",
          "required": false,
          "description": "是否停用，只有 true 生效；省略即为 false，会把已停用的字段重新启用。停用后的字段不再接受新值，也不再做必填检查。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，表示本次写入已提交。"
        }
      ],
      "notes": [
        "调用前先读取 customers.read?schema=1，取 catalog.revision 和现有的 catalog.fields；在现有列表的基础上修改后整体提交。",
        "响应只有 ok，不返回新的 fieldRevision：保存后重新读取 customers.read?schema=1，再把新的 fieldRevision 用于 customers.save 和 customers.import。",
        "副作用：fieldRevision 变化后，尚未完成的分批导入任务不能继续（customers.import 返回 409），其他调用方持有的旧 fieldRevision 也会返回 409。",
        "本操作特有的错误：400「最多 50 个自定义字段」（fields 不是数组或超过 50 项）；400「字段标识无效或重复」；400「字段名称或类型无效」；400「已有字段不能更改类型，请创建新字段」；400「单选或多选字段需 1–30 个有效选项」；400「已有选项需保留，避免历史资料失效」；400「已有字段请停用，不可删除历史定义」；409「资料已变化，请刷新后重试」（revision 过期）。",
        "API Key 身份可以调用，没有额外限制。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "customers.bind",
      "group": "客户资料",
      "name": "客户资料 · 将会话关联到客户",
      "method": "POST",
      "currentPath": "/v1/operations/customers.bind",
      "publicPath": "/v1/operations/customers.bind",
      "status": "available",
      "description": "把一个会话关联到指定的客户档案（customerId 为空则解除该会话的客户关联），并记录关联原因。只调整这一个会话的归属：两份客户档案保持独立、不会合并；会话原先关联的是另一位客户时，基于旧关联的历史记忆授权会被撤销。",
      "scopes": [
        "customers",
        "service"
      ],
      "request": "{\"action\":\"bind\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"conversationId\":\"YOUR_CONVERSATION_ID\",\"conversationVersion\":5,\"linkRevision\":0,\"customerId\":\"YOUR_CUSTOMER_ID\",\"customerRevision\":4,\"reason\":\"客户来电确认与该档案为同一人\"}",
      "response": "{\"ok\":true,\"identityEvent\":{\"id\":\"00000000-0000-4000-8000-000000000000\",\"conversationId\":\"YOUR_CONVERSATION_ID\",\"fromCustomerId\":\"\",\"toCustomerId\":\"YOUR_CUSTOMER_ID\",\"fromName\":\"\",\"toName\":\"示例客户\",\"linkRevision\":1,\"reason\":\"客户来电确认与该档案为同一人\",\"actor\":\"示例管理员\",\"created\":1791201600000,\"source\":{\"platformId\":\"web\",\"platformName\":\"网页客服\",\"channelId\":\"YOUR_CHANNEL_ID\",\"channelName\":\"官网客服\",\"entryId\":\"YOUR_ENTRY_ID\",\"entryName\":\"默认入口\",\"entryKind\":\"web\",\"accountId\":\"\",\"externalId\":\"\",\"capturedAt\":\"2026-10-08T02:00:00.000Z\",\"configRevision\":3,\"provenance\":\"web_entry\",\"channelKey\":\"YOUR_CHANNEL_ID\",\"entryKey\":\"[\\\"YOUR_CHANNEL_ID\\\",\\\"YOUR_ENTRY_ID\\\"]\",\"label\":\"官网客服 / 默认入口\"},\"undoOf\":\"\"}}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "客户目录版本号：先调用 customers.read?schema=1，取返回的 catalog.revision。本企业每次客户资料写入成功后该值都会 +1，而写入响应不返回新值，所以每次写入前都要重新读取。"
        },
        {
          "name": "conversationId",
          "type": "string",
          "required": true,
          "description": "要调整关联的会话编号，必须是当前身份可见的会话。"
        },
        {
          "name": "conversationVersion",
          "type": "integer",
          "required": true,
          "description": "该会话当前的 version：取 customers.bindPreview 返回的 conversationVersion。"
        },
        {
          "name": "linkRevision",
          "type": "integer",
          "required": true,
          "description": "该会话当前客户关联的版本：同一次 customers.bindPreview 返回的 linkRevision；会话还没有关联任何客户时为 0。"
        },
        {
          "name": "customerId",
          "type": "string",
          "required": false,
          "description": "目标客户编号，最多 100 字符。省略或传空字符串表示解除该会话的客户关联。不能与会话当前关联的客户相同。"
        },
        {
          "name": "customerRevision",
          "type": "integer",
          "requiredWhen": "customerId 非空",
          "description": "目标客户档案的当前版本：同一次 customers.bindPreview 返回的 customerRevision。"
        },
        {
          "name": "reason",
          "type": "string",
          "required": true,
          "description": "关联原因，1–300 字符，会写入关联变更记录。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，表示本次写入已提交。"
        },
        {
          "name": "identityEvent",
          "type": "object",
          "required": true,
          "description": "本次关联变更的记录。"
        },
        {
          "name": "identityEvent.id",
          "type": "string",
          "required": true,
          "description": "关联变更记录编号。"
        },
        {
          "name": "identityEvent.conversationId",
          "type": "string",
          "required": true,
          "description": "会话编号。"
        },
        {
          "name": "identityEvent.fromCustomerId",
          "type": "string",
          "required": true,
          "description": "变更前关联的客户编号；空字符串表示原先没有关联。"
        },
        {
          "name": "identityEvent.toCustomerId",
          "type": "string",
          "required": true,
          "description": "变更后关联的客户编号；空字符串表示已解除关联。"
        },
        {
          "name": "identityEvent.fromName",
          "type": "string",
          "required": true,
          "description": "变更前客户的姓名，没有时为空字符串。"
        },
        {
          "name": "identityEvent.toName",
          "type": "string",
          "required": true,
          "description": "变更后客户的姓名，没有时为空字符串。"
        },
        {
          "name": "identityEvent.linkRevision",
          "type": "integer",
          "required": true,
          "description": "变更后的关联版本（原值 +1），下一次调整关联时作为 linkRevision 使用。"
        },
        {
          "name": "identityEvent.reason",
          "type": "string",
          "required": true,
          "description": "提交的关联原因。"
        },
        {
          "name": "identityEvent.actor",
          "type": "string",
          "required": true,
          "description": "操作人姓名。"
        },
        {
          "name": "identityEvent.created",
          "type": "integer",
          "required": true,
          "description": "变更时间，Unix 毫秒。"
        },
        {
          "name": "identityEvent.source",
          "type": "object",
          "required": true,
          "description": "会话的来源信息（平台、渠道、入口等）。"
        },
        {
          "name": "identityEvent.undoOf",
          "type": "string",
          "required": true,
          "description": "被撤销的关联记录编号；本操作固定为空字符串。"
        }
      ],
      "notes": [
        "需要账号同时具备 customers 与 service 权限：会话可见性来自客服工作台。",
        "调用前先读取 customers.bindPreview?conversationId=会话编号&customerId=客户编号：返回 catalogRevision（即 revision）、conversationVersion、linkRevision、customerRevision，以及两份档案的字段差异 conflicts，供人工确认是否为同一人。",
        "本操作特有的错误：409「资料已变化，请刷新后重试」（revision 过期）；409「会话不存在、不可见或已变化」（会话不可见，或 conversationVersion 过期）；409「用户不存在或资料已更新」（客户不存在、已归档，或 customerRevision 过期）；409「关联关系已变化」（linkRevision 过期）；400「关联对象未变化」（目标客户就是当前关联的客户，或会话本来就没有关联却要解除）；400「关联原因格式无效」（reason 为空或超过 300 字符）；400「用户编号格式无效」（customerId 超过 100 字符或不是字符串）。",
        "成功后该会话的客户服务记录改挂到新客户（解除关联时移除）；两份客户档案的资料都不会被修改或合并。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "customer-crm.read",
      "name": "读取客户跟进",
      "group": "客户资料",
      "method": "GET",
      "currentPath": "/v1/operations/customer-crm.read?id=%3Cid%3E",
      "publicPath": "/v1/operations/customer-crm.read",
      "status": "available",
      "description": "仅 GET，读取 CRM、跟进记录和可见资源。修改通过 customers.crmSave / customers.crmFollowup，不能用详情页 revision 代替 customerRevision/crmRevision。",
      "scopes": [
        "customers"
      ],
      "request": "?id=%3Cid%3E",
      "response": "{\"followups\":[],\"owners\":[],\"canManage\":false,\"canFollowup\":false,\"nextCursor\":null}",
      "requestFields": [
        {
          "name": "id (query)",
          "description": "客户编号，必填。",
          "type": "string",
          "required": true
        },
        {
          "name": "cursor (query)",
          "description": "服务端返回的不透明分页游标。",
          "type": "string",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "customer / crm / catalog",
          "description": "客户资料、跟进档案和字段定义；使用各自修订号。",
          "type": "object",
          "required": false
        },
        {
          "name": "owners / followups",
          "description": "可选负责人和本页跟进记录。",
          "type": "array",
          "required": false
        },
        {
          "name": "canManage / canFollowup",
          "description": "当前用户可执行的动作。",
          "type": "boolean",
          "required": false
        },
        {
          "name": "nextCursor",
          "description": "继续读取跟进记录的原样游标，结束时 null。",
          "type": "string | null",
          "required": false
        }
      ],
      "notes": [
        "响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。",
        "仅 GET，读取 CRM、跟进记录和可见资源。修改通过 customers.crmSave / customers.crmFollowup，不能用详情页 revision 代替 customerRevision/crmRevision。",
        "应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "email.read",
      "group": "邮件接待",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "读取邮件与AI接待",
      "method": "GET",
      "currentPath": "/v1/operations/email.read?view=mailbox&folder=inbox&page=1",
      "publicPath": "/v1/operations/email.read",
      "description": "查询授权邮箱与邮件，取得真实 messageId、bindingId 和草稿 revision。不返回客户记忆上下文。",
      "request": "?view=mailbox&folder=inbox&page=1",
      "response": "{\"folder\": \"inbox\", \"page\": 1, \"total\": 0, \"rows\": [], \"connections\": []}",
      "notes": [
        "只读取当前账号授权邮箱；邮箱匹配不是身份认证。",
        "示例未实际执行；AI可能计费，发送需用户明确授权。"
      ],
      "requestFields": [
        {
          "name": "view (query)",
          "type": "string",
          "description": "固定mailbox，不能切换到客户上下文",
          "required": true
        },
        {
          "name": "messageId (query)",
          "type": "string",
          "description": "可选真实邮件ID；读取单封可使用folder=all",
          "required": false
        },
        {
          "name": "folder (query)",
          "type": "string",
          "description": "邮件文件夹",
          "required": false
        },
        {
          "name": "q (query)",
          "type": "string",
          "description": "搜索当前范围正文/主题/联系人",
          "required": false
        },
        {
          "name": "page (query)",
          "type": "integer",
          "description": "从1开始，单页最多30条",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "rows",
          "type": "array",
          "description": "当前范围内授权邮件；包含正文和真实邮件ID",
          "required": false
        },
        {
          "name": "connections",
          "type": "array",
          "description": "当前账号可用邮箱连接",
          "required": false
        },
        {
          "name": "total",
          "type": "integer",
          "description": "当前过滤范围邮件数",
          "required": false
        }
      ],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "email.mark",
      "group": "邮件接待",
      "name": "邮件与AI接待 · 标记单封邮件",
      "method": "POST",
      "currentPath": "/v1/operations/email.mark",
      "publicPath": "/v1/operations/email.mark",
      "status": "available",
      "description": "修改一封收到的邮件的整理状态：已读、星标、归档、处理状态、分类、标签或 AI 待办状态。每次调用只改一封邮件的一个字段；不发送邮件，也不修改邮件内容。",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"mark\",\"messageId\":\"YOUR_MESSAGE_ID\",\"field\":\"review\",\"value\":\"done\"}",
      "response": "{\"messageId\":\"YOUR_MESSAGE_ID\",\"field\":\"review\",\"value\":\"done\"}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "messageId",
          "type": "string",
          "required": true,
          "description": "邮件编号，最多 100 个字符。取 email.read（如 ?view=mailbox&folder=inbox）返回的 rows[].id；只能是收到的邮件，已发送邮件和草稿不可标记。"
        },
        {
          "name": "field",
          "type": "string",
          "required": true,
          "description": "要修改的状态：read（已读）、star（星标）、archive（归档）、review（处理状态）、category（分类）、label（标签）、aiTask（AI 待办状态）。"
        },
        {
          "name": "value",
          "type": "string",
          "required": true,
          "description": "新值，类型随 field 而定。read、star、archive：JSON 布尔值 true 或 false；review：open（待处理）或 done（已处理）；category：primary、updates、promotions、social 或 spam；aiTask：open、done 或 dismissed；label：标签名称，1–32 个字符，不能含 <、> 或控制字符。"
        },
        {
          "name": "applied",
          "type": "boolean",
          "requiredWhen": "field 为 label",
          "description": "true 给邮件加上该标签，false 移除该标签；必须是 JSON 布尔值。"
        }
      ],
      "responseFields": [
        {
          "name": "messageId",
          "type": "string",
          "required": true,
          "description": "被修改的邮件编号。"
        },
        {
          "name": "field",
          "type": "string",
          "required": true,
          "description": "本次修改的状态名，与请求一致。"
        },
        {
          "name": "value",
          "type": "string",
          "required": true,
          "description": "保存后的值，类型随 field 而定：review、category、aiTask 返回请求中的字符串；read 返回已读时间的毫秒时间戳（数字），取消已读为 0；star、archive 返回数字 1 或 0；label 返回该邮件当前全部标签的字符串数组。"
        }
      ],
      "notes": [
        "前置条件：企业需已开通邮件应用；先调用 email.read 取得 rows[].id。本操作不需要版本号。",
        "没有批量接口：一次只处理一封邮件的一个字段，批量整理需逐封调用，并受密钥每分钟限额约束。",
        "标签：每封邮件最多 20 个标签。内置标签为 orders、refunds、shipping、billing、support、complaints、campaigns；添加其他名称时会自动在密钥所属账号的标签列表中创建该标签。",
        "AI 待办：只有邮件已有 AI 待办（email.read 返回的 rows[].ai_action_text 非空）时才能修改 aiTask，否则返回 409。",
        "错误：400 messageId 为空或过长、邮件不是收到的邮件、field 不在允许值内、value 类型或取值不符、标签名称无效、标签超过 20 个；403 企业未开通邮件应用；404 邮件不存在或对密钥所属账号不可见；409 标签被并发修改（“标签已变化，请刷新后重试”）或邮件、权限已变化。",
        "重复调用：read、star、archive、review、category 是覆盖写入，重复调用结果一致；其中 read=true 每次都会把已读时间更新为当前时间。",
        "API Key 调用的限制：密钥以所属管理员账号的身份执行，只能标记企业共享邮箱和该账号本人邮箱中的邮件；归属于其他成员的邮箱中的邮件返回 404。自定义标签也记在该账号名下。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "email.saveDraft",
      "group": "邮件接待",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "邮件与AI接待 · 保存草稿",
      "method": "POST",
      "currentPath": "/v1/operations/email.saveDraft",
      "publicPath": "/v1/operations/email.saveDraft",
      "description": "保存或修改当前账号草稿；修改需当前revision，保存不会发送。 可保存智能体绑定；未接入发信邮箱时允许空bindingId保存，发送仍必须使用有效邮箱。",
      "request": "{\"action\":\"saveDraft\",\"id\":\"stable-draft-id\",\"bindingId\":\"binding-id\",\"replyToId\":\"message-id\",\"recipient\":\"customer@example.test\",\"subject\":\"Re: 咨询\",\"body\":\"已核对的回复\"}",
      "response": "{\"draft\": {\"id\": \"stable-draft-id\", \"revision\": 1}}",
      "notes": [
        "只读取当前账号授权邮箱；邮箱匹配不是身份认证。",
        "示例未实际执行；AI可能计费，发送需用户明确授权。",
        "提供稳定 Idempotency-Key；生成保持 requestId，修改/发送携带当前草稿revision；未知结果沿用原ID核查。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。",
      "requestFields": [
        {
          "name": "action",
          "type": "string",
          "description": "可省略，系统固定为 saveDraft；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "id",
          "type": "string",
          "description": "稳定草稿ID；MCP新草稿同样必填",
          "required": false
        },
        {
          "name": "revision",
          "type": "integer",
          "description": "修改已有草稿时必须提供当前修订号",
          "required": false
        },
        {
          "name": "bindingId",
          "type": "string",
          "description": "可选当前账号可见邮箱连接ID；空值只保存草稿，不能发送。",
          "required": false
        },
        {
          "name": "replyToId",
          "type": "string",
          "description": "回复时传原邮件ID",
          "required": false
        },
        {
          "name": "recipient",
          "type": "string",
          "description": "收件人邮箱，未发送草稿可留空",
          "required": false
        },
        {
          "name": "subject",
          "type": "string",
          "description": "主题",
          "required": false
        },
        {
          "name": "body",
          "type": "string",
          "description": "纯文本正文",
          "required": false
        },
        {
          "name": "agentId",
          "type": "string",
          "description": "可选已发布智能体ID；空值表示默认邮件助手，随草稿保存并恢复。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "draft",
          "type": "object",
          "description": "已持久保存的草稿与当前修订号，不表示发送",
          "required": false
        }
      ]
    },
    {
      "id": "email.sendDraft",
      "group": "邮件接待",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "邮件与AI接待 · 发送草稿",
      "method": "POST",
      "currentPath": "/v1/operations/email.sendDraft",
      "publicPath": "/v1/operations/email.sendDraft",
      "description": "在用户明确授权后发送核对过的草稿。accepted不代表delivered，未知结果不应更换ID重发。",
      "request": "{\"action\":\"sendDraft\",\"id\":\"stable-draft-id\",\"revision\":1,\"confirmed\":true}",
      "response": "{\"draft\": {\"id\": \"stable-draft-id\", \"status\": \"sent\"}, \"message\": {\"status\": \"accepted\"}}",
      "notes": [
        "只读取当前账号授权邮箱；邮箱匹配不是身份认证。",
        "示例未实际执行；AI可能计费，发送需用户明确授权。",
        "提供稳定 Idempotency-Key；生成保持 requestId，修改/发送携带当前草稿revision；未知结果沿用原ID核查。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。",
      "requestFields": [
        {
          "name": "action",
          "type": "string",
          "description": "可省略，系统固定为 sendDraft；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "id",
          "type": "string",
          "description": "已核对的草稿ID",
          "required": true
        },
        {
          "name": "revision",
          "type": "integer",
          "description": "当前草稿修订号",
          "required": true
        },
        {
          "name": "confirmed",
          "type": "boolean",
          "description": "发送必须true；仍需用户对收件人和内容的明确授权",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "draft",
          "type": "object",
          "description": "发送处理后的持久草稿，sent不等于送达",
          "required": false
        },
        {
          "name": "message",
          "type": "object",
          "description": "实际邮件供应商状态；accepted不等于delivered",
          "required": false
        }
      ]
    },
    {
      "id": "blacklist.read",
      "name": "读取黑名单",
      "group": "客户资料",
      "method": "GET",
      "currentPath": "/v1/operations/blacklist.read",
      "publicPath": "/v1/operations/blacklist.read",
      "status": "available",
      "description": "读取当前企业的策略、全部分组及最多 1000 条名单。",
      "scopes": [
        "service"
      ],
      "request": "?",
      "requestFields": [],
      "response": "{\"groups\":[],\"entries\":[],\"stats\":{\"total\":0,\"active\":0,\"phone\":0,\"address\":0,\"customer\":0},\"canManage\":false}",
      "responseFields": [
        {
          "name": "groups",
          "type": "array",
          "description": "全部分组，含 id 和 name；导入时使用 id。"
        },
        {
          "name": "entries",
          "type": "array",
          "description": "最多 1000 条，启用优先、更新时间倒序；不是全量导出。"
        },
        {
          "name": "stats",
          "type": "object",
          "description": "当前返回的最多 1000 条记录的统计，不是全库计数。"
        }
      ],
      "notes": [
        "读取须单独授权 blacklist.read；不因具有导入权限而自动获得。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "blacklist.import",
      "name": "导入黑名单",
      "group": "客户资料",
      "method": "POST",
      "currentPath": "/v1/operations/blacklist.import",
      "publicPath": "/v1/operations/blacklist.import",
      "status": "available",
      "description": "按密钥所属企业批量新增黑名单。整批校验通过后写入，重复值跳过，不覆盖已有条目。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"entries\":[{\"kind\":\"phone\",\"value\":\"13800138000\",\"label\":\"拒绝营销\",\"reason\":\"客户要求\",\"expiresAt\":0}]}",
      "response": "{\"import\":{\"inserted\":1,\"duplicates\":0}}",
      "requestFields": [
        {
          "name": "entries",
          "type": "array",
          "required": true,
          "description": "每批 1–1000 条；建议每批 500 条。"
        },
        {
          "name": "kind",
          "type": "string",
          "required": true,
          "description": "phone 手机号、address 设备地址 / IP、customer 客户标识。"
        },
        {
          "name": "value",
          "type": "string",
          "required": true,
          "description": "必须为字符串；手机号最多 40 字符，其他值最多 200 字符。"
        },
        {
          "name": "groupId",
          "type": "string",
          "description": "本企业已有分组 ID，省略或空字符串为未分组。"
        },
        {
          "name": "label",
          "type": "string",
          "description": "备注标签，最多 80 字符。"
        },
        {
          "name": "reason",
          "type": "string",
          "description": "加入原因，最多 240 字符。"
        },
        {
          "name": "expiresAt",
          "type": "integer",
          "description": "Unix 毫秒时间戳；省略或 0 为永久，最远不超过当前时间后 10 年。"
        }
      ],
      "responseFields": [
        {
          "name": "import.inserted",
          "type": "integer",
          "description": "本批新增条数。"
        },
        {
          "name": "import.duplicates",
          "type": "integer",
          "description": "本批内部和已有名单中重复、未覆盖的条数。"
        }
      ],
      "callbackEvents": [
        "api.request.completed",
        "api.request.failed"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。",
      "notes": [
        "服务端集成使用 /v1/operations/blacklist.import 和 Bearer 密钥；/v1/operations/blacklist.import 仍要求同源登录 Cookie。",
        "API 只返回本批计数；Cookie 管理页另返回最新名单。导入权限不包含读取、删除、启停或修改策略。",
        "最多 1000 条且 JSON 正文不超过 150,000 个 UTF-16 码元（UTF-8 最多 450,000 字节），超限请拆批。",
        "任何无效行或跨企业分组使整批失败。手机号按现有规则归一化，设备地址及客户标识忽略大小写。",
        "不覆盖重复条目的启停状态、标签、原因、分组或有效期；导入不自动启用黑名单策略。",
        "超时用相同编号重试；409 时先核对调用记录，429 按 Retry-After 等待。不要更换编号盲目重复提交。",
        "Bearer 网关必须携带 Idempotency-Key；同一批重试保持请求编号和正文不变，新批次使用新编号。"
      ]
    },
    {
      "id": "desk.read",
      "name": "读取工作台与工单",
      "group": "会话接待",
      "method": "GET",
      "currentPath": "/v1/operations/desk.read",
      "publicPath": "/v1/operations/desk.read",
      "status": "available",
      "description": "GET 返回按角色和成员范围投影的 state；summary=1 返回接待摘要。send/note 发送消息或备注，claim 接管，close/endConversation 结束，reopen 重新接待，handoff/acceptHandoff/cancelHandoff 邀请、接收或撤回转接，createTask 创建待办，createTicket/transferTicket/workStatus 管理工单。API Key 写入仅在本地工作台存储模式支持；Go 远程模式尚未接入提交时撤权校验，拒绝网关写入。",
      "scopes": [
        "service"
      ],
      "request": "?",
      "response": "{\"state\":{\"conversations\":[]}}",
      "requestFields": [],
      "responseFields": [
        {
          "name": "state",
          "description": "本人权限投影后的工作台状态。summary=1 使用接待摘要协议。",
          "type": "object",
          "required": false
        },
        {
          "name": "state.tasks[].content",
          "description": "待办正文；旧记录和系统生成项可能没有此字段，此时使用 title。",
          "type": "string",
          "required": false
        },
        {
          "name": "state.tasks[].ticketId",
          "description": "可选的关联工单 ID；旧记录与独立待办可缺少此字段。可见工单下的跨人员待办可只读查看，修改仍校验待办负责人。",
          "type": "string",
          "required": false
        },
        {
          "name": "state.tickets[].content",
          "description": "工单正文；旧记录和系统生成项可能没有此字段，此时使用 title。",
          "type": "string",
          "required": false
        }
      ],
      "notes": [
        "响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。",
        "GET 返回按角色和成员范围投影的 state；summary=1 返回接待摘要。send/note 发送消息或备注，claim 接管，close/endConversation 结束，reopen 重新接待，handoff/acceptHandoff/cancelHandoff 邀请、接收或撤回转接，createTask 创建待办，createTicket/transferTicket/workStatus 管理工单。API Key 写入仅在本地工作台存储模式支持；Go 远程模式尚未接入提交时撤权校验，拒绝网关写入。",
        "createTask 可使用已授权的 desk.createTask 公开操作。先读取最新 revision 与本企业已启用成员，填写 data.title/content/owner/ownerId/due/kind；content 必填，最多 3000 个 UTF-16 单位，创建时保存 createdAt/updatedAt。企业管理员有 service 权限时读取本企业全部待办；客服仍按本人、主管组与有效转接授权范围读取。",
        "createTicket 使用相同的创建示例字段并将 action 改为 createTicket，kind 必须为有效工单模板；data.content 必填，最多 3000 个 UTF-16 单位，独立保存并记录 createdAt/updatedAt。工单状态流转和重开保留正文；旧记录和系统生成工单可缺少正文。",
        "cancelHandoff 仅当前负责人或正常企业管理员有 service 权限时可用，支持访问不可用；需最新 revision/version 及 data.offerId。有效邀请存在时不能重复 handoff；已接收或失效邀请不能撤回。撤回保留原负责人，不发送客户消息。",
        "releaseToAI 仅当前接待负责人可调用，使用最新 revision/version，可带不超过 1000 字的 data.handoffSummary。会话有未知结果、待审批动作，或接待组为影子/建议模式时拒绝交回；成功后由 AI 接待下一条访客消息，不等于已对客户发送回复。",
        "应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "desk.send",
      "name": "工作台与工单 · 发送消息",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.send",
      "publicPath": "/v1/operations/desk.send",
      "status": "available",
      "description": "工作台与工单 · 发送消息",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"send\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":1,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":1,\"data\":{\"text\":\"您好，已收到您的问题。\"}}",
      "response": "{\"state\":{\"revision\":2,\"conversations\":[]},\"result\":\"操作结果\"}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "description": "稳定业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，同时仍须 Idempotency-Key。",
          "required": true
        },
        {
          "name": "revision",
          "type": "integer",
          "description": "先读取 desk.read 返回的 state.revision。",
          "required": true
        },
        {
          "name": "id",
          "type": "string",
          "description": "已授权的会话编号。",
          "required": true
        },
        {
          "name": "version",
          "type": "integer",
          "description": "该会话当前 version；变更后须重新读取。",
          "required": true
        },
        {
          "name": "data",
          "type": "object",
          "description": "业务字段见请求示例；文本位于 data.text。",
          "required": true
        }
      ],
      "notes": [
        "示例中的 revision、version 和资源编号必须替换为当前读取值；未收到最终回执时，先读取原业务结果。",
        "发送前须接管且拥有会话；通道发送结果按业务回执核对。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.note",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.note",
      "publicPath": "/v1/operations/desk.note",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "工作台与工单 · 添加会话内部备注",
      "description": "在指定会话中追加一条内部备注（消息 role 为 note）。备注不属于对客消息，不触发任何渠道发送，也不改变会话的接待状态、负责人和 version。",
      "request": "{\"action\":\"note\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":3,\"data\":{\"text\":\"客户已提供订单号，等待仓库核实。\"}}",
      "response": "{\"state\":{\"revision\":13,\"conversations\":[{\"id\":\"YOUR_CONVERSATION_ID\",\"version\":3,\"lifecycle\":\"OPEN\",\"handling\":\"HUMAN\",\"owner\":\"示例管理员\",\"ownerId\":\"YOUR_ACCOUNT_ID\",\"messages\":[{\"id\":\"MSG-1a2b3c4d\",\"role\":\"note\",\"text\":\"客户已提供订单号，等待仓库核实。\",\"author\":\"示例管理员\",\"authorId\":\"YOUR_ACCOUNT_ID\",\"time\":\"10:30\",\"timestamp\":\"2026-11-16T02:30:00.000Z\"}]}]},\"result\":\"内部备注已保存\",\"executionReceipt\":null}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "会话编号：取 desk.read 返回的 state.conversations[].id。"
        },
        {
          "name": "version",
          "type": "integer",
          "required": true,
          "description": "该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。"
        },
        {
          "name": "data",
          "type": "object",
          "required": true,
          "description": "备注内容。"
        },
        {
          "name": "data.text",
          "type": "string",
          "required": true,
          "description": "备注正文，去除首尾空白后不能为空，最多 4000 个字符（含首尾空白）。"
        },
        {
          "name": "data.mentions",
          "type": "object[]",
          "required": false,
          "description": "要提及（@）的同事，最多 20 项；省略表示不提及。每项只允许 accountId、start、end 三个键，被提及成员会收到备注提及通知。"
        },
        {
          "name": "data.mentions[].accountId",
          "type": "string",
          "requiredWhen": "提供 data.mentions 时",
          "description": "被提及成员的账号编号：取 desk.read 返回的 state.members[].id；成员须为状态“已启用”、角色为企业管理员或人工客服。"
        },
        {
          "name": "data.mentions[].start",
          "type": "integer",
          "requiredWhen": "提供 data.mentions 时",
          "description": "data.text 中“@成员姓名”片段的起始下标，从 0 开始，按提交的原始 data.text 计算。"
        },
        {
          "name": "data.mentions[].end",
          "type": "integer",
          "requiredWhen": "提供 data.mentions 时",
          "description": "片段的结束下标（不含）。data.text 从 start 到 end 的内容必须恰好等于“@”加该成员在 state.members[] 中的 name，各片段不得重叠。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "提交后调用账号授权范围内的完整工作台快照，结构与 desk.read 的 state 相同；示例只保留与本操作相关的字段。"
        },
        {
          "name": "state.revision",
          "type": "integer",
          "required": true,
          "description": "提交后的工作台版本；下一次写入使用此值。"
        },
        {
          "name": "state.conversations",
          "type": "object[]",
          "required": true,
          "description": "会话列表；按 id 找到目标会话，核对其 version、lifecycle、handling、owner 与 ownerId。"
        },
        {
          "name": "state.conversations[].messages",
          "type": "object[]",
          "required": true,
          "description": "目标会话的消息；新备注是其中 role 为 note、authorId 为调用账号的最新一条。响应不单独返回新备注的编号。"
        },
        {
          "name": "result",
          "type": "string",
          "required": true,
          "description": "固定为“内部备注已保存”。"
        },
        {
          "name": "executionReceipt",
          "type": "object",
          "required": false,
          "description": "本操作固定返回 null。"
        }
      ],
      "notes": [
        "调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。",
        "状态前置：进行中的会话必须先由调用账号接管（handling 为 HUMAN 且 ownerId 为调用账号，可先调用 desk.claim），否则返回 403；已关闭的会话可直接添加备注。",
        "400：data.text 为空或超过 4000 个字符；出现 data.media；出现 data.replyToMessageId；data.mentions 不是数组、超过 20 项或某项格式不符。409：被提及成员已停用、角色不符，或 start/end 与“@姓名”不吻合。413：整个请求正文超过 20000 个字符。",
        "API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。",
        "API Key 调用不支持备注图片：只要正文出现 data.mediaIds（包括空数组）就返回 403。",
        "结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。",
        "错误响应正文为 {\"error\":\"原因说明\"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.close",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.close",
      "publicPath": "/v1/operations/desk.close",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "工作台与工单 · 关闭本人接待的会话",
      "description": "关闭调用账号正在人工接待的会话：lifecycle 变为 CLOSED、version 加 1，并写入一条系统消息；该会话尚未接收的转接邀请同时失效。只关闭会话，不关闭也不修改关联的工单与待办。提交成功后系统会异步触发会话结束后的分析、客户记忆与后续动作，其结果不在本响应中返回。",
      "request": "{\"action\":\"close\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":3}",
      "response": "{\"state\":{\"revision\":13,\"conversations\":[{\"id\":\"YOUR_CONVERSATION_ID\",\"version\":4,\"lifecycle\":\"CLOSED\",\"handling\":\"HUMAN\",\"owner\":\"示例管理员\",\"ownerId\":\"YOUR_ACCOUNT_ID\",\"closedAt\":\"2026-11-16T02:30:00.000Z\"}]},\"result\":\"会话已关闭\",\"executionReceipt\":null}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "会话编号：取 desk.read 返回的 state.conversations[].id。"
        },
        {
          "name": "version",
          "type": "integer",
          "required": true,
          "description": "该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "提交后调用账号授权范围内的完整工作台快照，结构与 desk.read 的 state 相同；示例只保留与本操作相关的字段。"
        },
        {
          "name": "state.revision",
          "type": "integer",
          "required": true,
          "description": "提交后的工作台版本；下一次写入使用此值。"
        },
        {
          "name": "state.conversations",
          "type": "object[]",
          "required": true,
          "description": "会话列表；按 id 找到目标会话，核对其 version、lifecycle、handling、owner 与 ownerId。"
        },
        {
          "name": "state.conversations[].lifecycle",
          "type": "string",
          "required": true,
          "description": "目标会话变为 CLOSED。"
        },
        {
          "name": "state.conversations[].closedAt",
          "type": "string",
          "required": true,
          "description": "目标会话的关闭时间，ISO 8601（UTC）。"
        },
        {
          "name": "result",
          "type": "string",
          "required": true,
          "description": "固定为“会话已关闭”。"
        },
        {
          "name": "executionReceipt",
          "type": "object",
          "required": false,
          "description": "本操作固定返回 null。"
        }
      ],
      "notes": [
        "调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。",
        "状态前置：会话必须进行中（lifecycle 为 OPEN）、handling 为 HUMAN 且 ownerId 为调用账号；不满足时返回 403，已关闭的会话再次关闭同样返回 403。会话由 AI 接待或在排队时，先调用 desk.claim 接管，或改用 desk.endConversation。",
        "与 desk.endConversation 的区别：两者都只把会话置为 CLOSED，都不处理工单。close 仅限调用账号本人人工接待中的会话，不需要 seq；endConversation 可结束任意进行中的会话，但必须提供 seq，并额外记录 terminatedAt。",
        "原生消息渠道（机器人连接）的会话：渠道回复仍在发送或结果待核对、渠道绑定已变化、或该渠道当前仅可查看时返回 409。",
        "API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。",
        "结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。",
        "错误响应正文为 {\"error\":\"原因说明\"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.endConversation",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.endConversation",
      "publicPath": "/v1/operations/desk.endConversation",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "工作台与工单 · 结束进行中的会话",
      "description": "结束一个进行中的会话，不要求先接管：以 API Key 调用时可结束本企业任意接待状态（AI、排队、人工、留言）的会话。lifecycle 变为 CLOSED、version 加 1，记录 terminatedAt 并写入一条系统消息；只结束会话，不关闭也不修改关联的工单与待办。提交成功后系统会异步触发会话结束后的分析、客户记忆与后续动作，其结果不在本响应中返回。",
      "request": "{\"action\":\"endConversation\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":3,\"seq\":6}",
      "response": "{\"state\":{\"revision\":13,\"conversations\":[{\"id\":\"YOUR_CONVERSATION_ID\",\"version\":4,\"lifecycle\":\"CLOSED\",\"handling\":\"AI\",\"owner\":\"AI 助手\",\"ownerId\":\"\",\"closedAt\":\"2026-11-16T02:30:00.000Z\",\"terminatedAt\":\"2026-11-16T02:30:00.000Z\"}]},\"result\":\"会话已结束\",\"executionReceipt\":null}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "会话编号：取 desk.read 返回的 state.conversations[].id。"
        },
        {
          "name": "version",
          "type": "integer",
          "required": true,
          "description": "该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。"
        },
        {
          "name": "seq",
          "type": "integer",
          "required": true,
          "description": "该会话当前的消息总数：取同一次 desk.read 返回的目标会话 messages 数组长度（系统消息和内部备注也计入）。缺失或与服务端不一致返回 409，用于避免在出现新消息后误结束。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "提交后调用账号授权范围内的完整工作台快照，结构与 desk.read 的 state 相同；示例只保留与本操作相关的字段。"
        },
        {
          "name": "state.revision",
          "type": "integer",
          "required": true,
          "description": "提交后的工作台版本；下一次写入使用此值。"
        },
        {
          "name": "state.conversations",
          "type": "object[]",
          "required": true,
          "description": "会话列表；按 id 找到目标会话，核对其 version、lifecycle、handling、owner 与 ownerId。"
        },
        {
          "name": "state.conversations[].lifecycle",
          "type": "string",
          "required": true,
          "description": "目标会话变为 CLOSED；handling、owner 和 ownerId 保持结束前的值。"
        },
        {
          "name": "state.conversations[].terminatedAt",
          "type": "string",
          "required": true,
          "description": "目标会话的结束时间，ISO 8601（UTC）。"
        },
        {
          "name": "result",
          "type": "string",
          "required": true,
          "description": "固定为“会话已结束”。"
        },
        {
          "name": "executionReceipt",
          "type": "object",
          "required": false,
          "description": "本操作固定返回 null。"
        }
      ],
      "notes": [
        "调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。",
        "状态前置：会话必须进行中（lifecycle 为 OPEN），已结束的会话返回 409；seq 必须等于当前消息总数，否则返回 409，需重新读取后再确认结束。seq 不是非负整数返回 400。",
        "与 desk.close 的区别：两者都只把会话置为 CLOSED，都不处理工单。close 仅限调用账号本人人工接待中的会话，不需要 seq；endConversation 可结束任意进行中的会话，但必须提供 seq，并额外记录 terminatedAt。",
        "原生消息渠道（机器人连接）的会话：渠道回复仍在发送或结果待核对、渠道绑定已变化、或该渠道当前仅可查看时返回 409。",
        "API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。",
        "结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。",
        "错误响应正文为 {\"error\":\"原因说明\"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.reopen",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.reopen",
      "publicPath": "/v1/operations/desk.reopen",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "工作台与工单 · 重新打开会话",
      "description": "重新打开一个已关闭的会话：lifecycle 变回 OPEN，原负责人被清空并转入待人工状态，随后按客服组策略重新分配（可能直接分配给在线客服、进入人工队列或转为留言跟进）；该会话下状态为“已解决”的客户问题改为“已重开”。不会交回 AI 接待，也不会重开关联的工单。",
      "request": "{\"action\":\"reopen\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":4}",
      "response": "{\"state\":{\"revision\":13,\"conversations\":[{\"id\":\"YOUR_CONVERSATION_ID\",\"version\":5,\"lifecycle\":\"OPEN\",\"handling\":\"HANDOFF\",\"owner\":\"售后客服组\",\"ownerId\":\"\"}]},\"result\":\"已重开会话\",\"executionReceipt\":null}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "会话编号：取 desk.read 返回的 state.conversations[].id。"
        },
        {
          "name": "version",
          "type": "integer",
          "required": true,
          "description": "该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "提交后调用账号授权范围内的完整工作台快照，结构与 desk.read 的 state 相同；示例只保留与本操作相关的字段。"
        },
        {
          "name": "state.revision",
          "type": "integer",
          "required": true,
          "description": "提交后的工作台版本；下一次写入使用此值。"
        },
        {
          "name": "state.conversations",
          "type": "object[]",
          "required": true,
          "description": "会话列表；按 id 找到目标会话，核对其 version、lifecycle、handling、owner 与 ownerId。"
        },
        {
          "name": "state.conversations[].handling",
          "type": "string",
          "required": true,
          "description": "重开后的接待状态，由客服组策略决定：HUMAN（已分配给某位客服）、HANDOFF（等待人工）或 ASYNC（留言跟进）。"
        },
        {
          "name": "state.conversations[].version",
          "type": "integer",
          "required": true,
          "description": "重开后的会话 version，至少比请求值大 1；后续操作必须使用响应中的新值。"
        },
        {
          "name": "result",
          "type": "string",
          "required": true,
          "description": "固定为“已重开会话”。"
        },
        {
          "name": "executionReceipt",
          "type": "object",
          "required": false,
          "description": "本操作固定返回 null。"
        }
      ],
      "notes": [
        "调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。",
        "状态前置：会话必须已关闭（lifecycle 为 CLOSED）；仍在进行中返回 409。",
        "409：原生消息渠道（机器人连接）的会话不能重开；会话原属客服组已停用或不存在。422：企业没有任何已启用的客服组。",
        "API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。",
        "结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。",
        "错误响应正文为 {\"error\":\"原因说明\"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.claim",
      "name": "工作台与工单 · 领取",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.claim",
      "publicPath": "/v1/operations/desk.claim",
      "status": "available",
      "description": "工作台与工单 · 领取",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"claim\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":1,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":1,\"data\":{}}",
      "response": "{\"state\":{\"revision\":2,\"conversations\":[]},\"result\":\"操作结果\"}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "description": "稳定业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，同时仍须 Idempotency-Key。",
          "required": true
        },
        {
          "name": "revision",
          "type": "integer",
          "description": "先读取 desk.read 返回的 state.revision。",
          "required": true
        },
        {
          "name": "id",
          "type": "string",
          "description": "已授权的会话编号。",
          "required": true
        },
        {
          "name": "version",
          "type": "integer",
          "description": "该会话当前 version；变更后须重新读取。",
          "required": true
        },
        {
          "name": "data",
          "type": "object",
          "description": "业务字段见请求示例；文本位于 data.text。",
          "required": true
        }
      ],
      "notes": [
        "示例中的 revision、version 和资源编号必须替换为当前读取值；未收到最终回执时，先读取原业务结果。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.createTask",
      "name": "工作台与工单 · 创建任务",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.createTask",
      "publicPath": "/v1/operations/desk.createTask",
      "status": "available",
      "description": "GET 返回按角色和成员范围投影的 state；summary=1 返回接待摘要。send/note 发送消息或备注，claim 接管，close/endConversation 结束，reopen 重新接待，handoff/acceptHandoff/cancelHandoff 邀请、接收或撤回转接，createTask 创建待办，createTicket/transferTicket/workStatus 管理工单。API Key 写入仅在本地工作台存储模式支持；Go 远程模式尚未接入提交时撤权校验，拒绝网关写入。",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"createTask\",\"requestId\":\"desk_example_1\",\"revision\":1,\"data\":{\"title\":\"退款回查\",\"content\":\"核对退款回执后于下午联系客户\",\"owner\":\"嘉宁\",\"ownerId\":\"owner-a\",\"due\":\"2026-10-13T09:00:00+08:00\",\"kind\":\"回访\"}}",
      "response": "{\"state\":{\"conversations\":[]}}",
      "requestFields": [
        {
          "name": "requestId",
          "description": "业务请求编号；它与网关 Idempotency-Key 均需保持稳定。",
          "type": "string",
          "required": false
        },
        {
          "name": "revision",
          "description": "先读取当前资源修订号；共享配置与单资源修订号不可混用。",
          "type": "integer",
          "required": false
        },
        {
          "name": "id",
          "description": "操作目标的真实资源 ID；不能使用其他企业 ID。",
          "type": "string",
          "required": false
        },
        {
          "name": "version",
          "description": "目标会话版本（适用时），与工作台 revision 不同。",
          "type": "integer",
          "required": false
        },
        {
          "name": "seq",
          "description": "send 所依赖的消息数量，保护并发回复。",
          "type": "integer",
          "required": false
        },
        {
          "name": "data.text",
          "description": "send/note 的正文，最多 4000 字。",
          "type": "string",
          "required": false
        },
        {
          "name": "data.content",
          "description": "createTask/createTicket 必填的独立待办/工单内容，不能为空，最多 3000 个 UTF-16 单位；与标题分开保存。",
          "type": "string",
          "required": false
        },
        {
          "name": "data.ticketId",
          "description": "仅 createTask 可选：关联当前可见的未完成工单，并自动继承其 conversationId；同时提交的 conversationId 必须一致。待办和工单状态独立，createTicket 不接受此字段。",
          "type": "string",
          "required": false
        },
        {
          "name": "data.offerId",
          "description": "cancelHandoff 必填，当前会话有效待接收邀请的 ID；撤回同一归属版本的全部待接收邀请。",
          "type": "string",
          "required": false
        },
        {
          "name": "data",
          "description": "操作数据：createTask/createTicket 的标题/内容/类型/负责人/截止时间，transferTicket 的目标，workStatus 的集合与状态等，以当前工作台协议为准。",
          "type": "object",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "description": "操作完成后的工作台状态；发生版本冲突时应重新读取。",
          "type": "object",
          "required": false
        },
        {
          "name": "state.tasks[].content",
          "description": "待办正文；旧记录和系统生成项可能没有此字段，此时使用 title。",
          "type": "string",
          "required": false
        },
        {
          "name": "state.tasks[].ticketId",
          "description": "可选的关联工单 ID；旧记录与独立待办可缺少此字段。可见工单下的跨人员待办可只读查看，修改仍校验待办负责人。",
          "type": "string",
          "required": false
        },
        {
          "name": "state.tickets[].content",
          "description": "工单正文；旧记录和系统生成项可能没有此字段，此时使用 title。",
          "type": "string",
          "required": false
        }
      ],
      "notes": [
        "响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。",
        "GET 返回按角色和成员范围投影的 state；summary=1 返回接待摘要。send/note 发送消息或备注，claim 接管，close/endConversation 结束，reopen 重新接待，handoff/acceptHandoff/cancelHandoff 邀请、接收或撤回转接，createTask 创建待办，createTicket/transferTicket/workStatus 管理工单。API Key 写入仅在本地工作台存储模式支持；Go 远程模式尚未接入提交时撤权校验，拒绝网关写入。",
        "createTask 可使用已授权的 desk.createTask 公开操作。先读取最新 revision 与本企业已启用成员，填写 data.title/content/owner/ownerId/due/kind；content 必填，最多 3000 个 UTF-16 单位，创建时保存 createdAt/updatedAt。企业管理员有 service 权限时读取本企业全部待办；客服仍按本人、主管组与有效转接授权范围读取。",
        "createTicket 使用相同的创建示例字段并将 action 改为 createTicket，kind 必须为有效工单模板；data.content 必填，最多 3000 个 UTF-16 单位，独立保存并记录 createdAt/updatedAt。工单状态流转和重开保留正文；旧记录和系统生成工单可缺少正文。",
        "cancelHandoff 仅当前负责人或正常企业管理员有 service 权限时可用，支持访问不可用；需最新 revision/version 及 data.offerId。有效邀请存在时不能重复 handoff；已接收或失效邀请不能撤回。撤回保留原负责人，不发送客户消息。",
        "releaseToAI 仅当前接待负责人可调用，使用最新 revision/version，可带不超过 1000 字的 data.handoffSummary。会话有未知结果、待审批动作，或接待组为影子/建议模式时拒绝交回；成功后由 AI 接待下一条访客消息，不等于已对客户发送回复。",
        "应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.createTicket",
      "name": "工作台与工单 · 创建工单",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.createTicket",
      "publicPath": "/v1/operations/desk.createTicket",
      "status": "available",
      "description": "工作台与工单 · 创建工单",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"createTicket\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":1,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":1,\"data\":{\"title\":\"订单售后\",\"owner\":\"接待客服\",\"ownerId\":\"YOUR_MEMBER_ID\",\"due\":\"2026-12-01T09:00:00+08:00\",\"kind\":\"退款\",\"content\":\"请核对订单并联系客户\",\"conversationId\":\"YOUR_CONVERSATION_ID\"}}",
      "response": "{\"state\":{\"revision\":2,\"conversations\":[]},\"result\":\"操作结果\"}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "description": "稳定业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，同时仍须 Idempotency-Key。",
          "required": true
        },
        {
          "name": "revision",
          "type": "integer",
          "description": "先读取 desk.read 返回的 state.revision。",
          "required": true
        },
        {
          "name": "id",
          "type": "string",
          "description": "已授权的会话编号。",
          "required": true
        },
        {
          "name": "version",
          "type": "integer",
          "description": "该会话当前 version；变更后须重新读取。",
          "required": true
        },
        {
          "name": "data",
          "type": "object",
          "description": "业务字段见请求示例；文本位于 data.text。",
          "required": true
        }
      ],
      "notes": [
        "示例中的 revision、version 和资源编号必须替换为当前读取值；未收到最终回执时，先读取原业务结果。",
        "kind 使用当前工单模板；due 为有效截止时间；data.conversationId 与顶层 id 一致。管理员须先开启自动创建工单。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.transferTicket",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.transferTicket",
      "publicPath": "/v1/operations/desk.transferTicket",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "工作台与工单 · 转派工单",
      "description": "把一张未完成的工单转派给另一位成员，并写入工单历史；不改变工单状态。工单关联了会话时同步交接会话：会话负责人改为接收人、接待状态变为人工接待（HUMAN）、会话 version 加 1，在会话中写入一条转派备注，并取消该会话待接收的转接邀请。未关联会话时只更改工单负责人。",
      "request": "{\"action\":\"transferTicket\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"id\":\"YOUR_TICKET_ID\",\"version\":3,\"data\":{\"fromOwnerId\":\"YOUR_CURRENT_OWNER_ID\",\"ownerId\":\"YOUR_MEMBER_ID\",\"reason\":\"需要售后专员跟进退款\"}}",
      "response": "{\"state\":{\"revision\":13,\"tickets\":[{\"id\":\"YOUR_TICKET_ID\",\"version\":2,\"status\":\"处理中\",\"owner\":\"售后专员\",\"ownerId\":\"YOUR_MEMBER_ID\",\"conversationId\":\"YOUR_CONVERSATION_ID\"}],\"conversations\":[{\"id\":\"YOUR_CONVERSATION_ID\",\"version\":4,\"lifecycle\":\"OPEN\",\"handling\":\"HUMAN\",\"owner\":\"售后专员\",\"ownerId\":\"YOUR_MEMBER_ID\"}]},\"result\":\"工单与关联会话已同步转派，聊天记录完整保留\",\"executionReceipt\":null}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "工单编号：取 desk.read 返回的 state.tickets[].id（不是会话编号）。"
        },
        {
          "name": "version",
          "type": "integer",
          "requiredWhen": "工单关联了会话（state.tickets[].conversationId 非空）",
          "description": "关联会话的 version：在 state.conversations[] 中找到 id 等于该工单 conversationId 的会话，取其 version；缺失或与当前值不相等返回 409。工单未关联会话时不使用此字段。"
        },
        {
          "name": "data",
          "type": "object",
          "required": true,
          "description": "转派参数。"
        },
        {
          "name": "data.fromOwnerId",
          "type": "string",
          "required": true,
          "description": "工单当前负责人的账号编号：取 state.tickets[].ownerId；工单尚未分配负责人时传空字符串。与服务端当前值不一致返回 409。"
        },
        {
          "name": "data.ownerId",
          "type": "string",
          "required": true,
          "description": "接收人的账号编号：取 desk.read 返回的 state.members[].id。接收人须状态为“已启用”，角色为人工客服、客服主管或企业管理员，且不能是当前负责人。"
        },
        {
          "name": "data.reason",
          "type": "string",
          "required": true,
          "description": "转派原因，去除首尾空白后不能为空，最多 500 个字符；写入工单历史和关联会话的转派备注。"
        },
        {
          "name": "data.ticketVersion",
          "type": "integer",
          "required": false,
          "description": "工单自身的 version：取 state.tickets[].version，工单没有该字段时传 0。提供时与当前值不一致返回 409；省略则不做此项校验。"
        },
        {
          "name": "data.departmentId",
          "type": "string",
          "required": false,
          "description": "接收人所属部门编号：取 state.members[].departmentId，无部门时为空字符串。提供时与接收人当前部门不一致返回 409；省略则不做此项校验。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "提交后调用账号授权范围内的完整工作台快照，结构与 desk.read 的 state 相同；示例只保留与本操作相关的字段。"
        },
        {
          "name": "state.revision",
          "type": "integer",
          "required": true,
          "description": "提交后的工作台版本；下一次写入使用此值。"
        },
        {
          "name": "state.tickets",
          "type": "object[]",
          "required": true,
          "description": "工单列表；目标工单的 owner、ownerId 已改为接收人，version 加 1，history 追加一条 action 为 transfer 的记录。"
        },
        {
          "name": "state.conversations",
          "type": "object[]",
          "required": true,
          "description": "会话列表；工单关联了会话时，该会话的 owner、ownerId 改为接收人，handling 为 HUMAN，version 加 1。"
        },
        {
          "name": "result",
          "type": "string",
          "required": true,
          "description": "工单关联了会话时为“工单与关联会话已同步转派，聊天记录完整保留”，否则为“工单已转派”。"
        },
        {
          "name": "executionReceipt",
          "type": "object",
          "required": false,
          "description": "本操作固定返回 null。"
        }
      ],
      "notes": [
        "调用前先用 desk.read 读取最新 state：取 state.revision；在 state.tickets 中取目标工单的 id、ownerId、version 和 conversationId；在 state.members 中选定接收人；工单关联了会话时再取该会话的 version。任一版本不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。",
        "状态前置：已完成的工单不能转派（409），需先用 desk.workStatus 改回“待处理”。",
        "409：data.fromOwnerId 与工单当前负责人不一致；关联会话的 version 已变化或关联会话不可用；关联会话进行中且接收人已达同时接待上限；关联会话进行中、接收人不是会话现负责人且当前不在坐席排班时间内。400：接收人不存在、未启用或角色不符；接收人就是当前负责人；data.reason 为空或超过 500 个字符。404：工单不存在。",
        "注意副作用：关联会话无论原先由 AI 接待、在排队还是已关闭，转派后 handling 都会变为 HUMAN 并归接收人负责。",
        "API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。",
        "以 API Key 调用时可转派本企业任意工单，不受“只能流转本人负责的工单”限制。",
        "结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。",
        "错误响应正文为 {\"error\":\"原因说明\"}。requestId 不符合格式、revision 不是非负整数返回 400。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.workStatus",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.workStatus",
      "publicPath": "/v1/operations/desk.workStatus",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "工作台与工单 · 更新工单或待办状态",
      "description": "更新一张工单或一条待办的处理状态，并记录完成证据或重开原因。不改变负责人，也不改变关联会话的状态：重开工单不会重开会话，完成工单也不会关闭会话。",
      "request": "{\"action\":\"workStatus\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"id\":\"YOUR_TICKET_ID\",\"data\":{\"collection\":\"tickets\",\"status\":\"处理中\"}}",
      "response": "{\"state\":{\"revision\":13,\"tickets\":[{\"id\":\"YOUR_TICKET_ID\",\"version\":2,\"status\":\"处理中\",\"owner\":\"示例管理员\",\"ownerId\":\"YOUR_ACCOUNT_ID\",\"conversationId\":\"YOUR_CONVERSATION_ID\"}],\"tasks\":[]},\"result\":\"工单状态已更新\",\"executionReceipt\":null}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "工单或待办的编号：工单取 desk.read 返回的 state.tickets[].id，待办取 state.tasks[].id（不是会话编号）。"
        },
        {
          "name": "data",
          "type": "object",
          "required": true,
          "description": "状态参数。"
        },
        {
          "name": "data.collection",
          "type": "string",
          "required": false,
          "description": "传 \"tickets\" 表示更新工单；省略或传其他任何值都按待办（state.tasks）处理。"
        },
        {
          "name": "data.status",
          "type": "string",
          "required": true,
          "description": "目标状态。工单允许的流转：待处理→处理中或已完成；处理中→待客户反馈或已完成；待客户反馈→处理中或已完成；已完成→待处理（重开）。待办只接受“处理中”（当前须为待处理）或“已完成”。"
        },
        {
          "name": "data.evidence",
          "type": "string",
          "requiredWhen": "data.status 为“已完成”",
          "description": "完成证据，去除首尾空白后不能为空，最多 2000 个字符。"
        },
        {
          "name": "data.reason",
          "type": "string",
          "requiredWhen": "把已完成的工单改回“待处理”（重开）",
          "description": "重开原因，去除首尾空白后不能为空，最多 500 个字符。工单的其他状态流转可选填，只保留前 500 个字符；待办不使用此字段。"
        },
        {
          "name": "data.ticketVersion",
          "type": "integer",
          "required": false,
          "description": "仅用于工单：取 state.tickets[].version，工单没有该字段时传 0。提供时与当前值不一致返回 409；省略则不做此项校验。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "提交后调用账号授权范围内的完整工作台快照，结构与 desk.read 的 state 相同；示例只保留与本操作相关的字段。"
        },
        {
          "name": "state.revision",
          "type": "integer",
          "required": true,
          "description": "提交后的工作台版本；下一次写入使用此值。"
        },
        {
          "name": "state.tickets",
          "type": "object[]",
          "required": true,
          "description": "工单列表；更新工单时目标工单的 status 为新状态，version 加 1，history 追加一条记录，完成时写入 evidence 与 completedAt。"
        },
        {
          "name": "state.tasks",
          "type": "object[]",
          "required": true,
          "description": "待办列表；更新待办时目标待办的 status 为新状态，完成时写入 evidence 与 completedAt。"
        },
        {
          "name": "result",
          "type": "string",
          "required": true,
          "description": "工单为“工单状态已更新”，重开工单为“工单已重开，关联会话状态保持不变”；待办为“处理状态已更新”。"
        },
        {
          "name": "executionReceipt",
          "type": "object",
          "required": false,
          "description": "本操作固定返回 null。"
        }
      ],
      "notes": [
        "调用前先用 desk.read 读取最新 state：取 state.revision，并在 state.tickets 或 state.tasks 中取目标记录的 id 和当前 status。revision 不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。本操作不使用顶层 version。",
        "工单（data.collection 为 \"tickets\"）：404 工单不存在；409 目标状态不在允许的流转内（包括传入未知状态值），或 data.ticketVersion 已变化；400 data.status 不是 1–30 个字符的非空字符串，或缺少必填的 data.evidence / data.reason。",
        "待办（省略 data.collection）：404 记录不存在；400 该待办是转接邀请（应改用 desk.acceptHandoff），或 data.status 不是“处理中”“已完成”；409 待办已完成或已取消，或要求改为“处理中”时当前状态不是“待处理”；400 完成时缺少 data.evidence。",
        "data.collection 拼写错误不会报参数错误，而是按待办查找，通常表现为 404 记录不存在。",
        "API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。",
        "以 API Key 调用时可更新本企业任意工单与待办；唯一例外是私域“交接”类待办，只有接收人本人可处理，否则返回 403。",
        "结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。",
        "错误响应正文为 {\"error\":\"原因说明\"}。requestId 不符合格式、revision 不是非负整数返回 400。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.handoff",
      "name": "工作台与工单 · 发起转接邀请",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.handoff",
      "publicPath": "/v1/operations/desk.handoff",
      "status": "available",
      "description": "工作台与工单 · 发起转接邀请",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"handoff\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":1,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":1,\"data\":{\"owner\":\"接待客服\",\"ownerId\":\"YOUR_MEMBER_ID\",\"reason\":\"需要售后处理\"}}",
      "response": "{\"state\":{\"revision\":2,\"conversations\":[]},\"result\":\"操作结果\"}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "description": "稳定业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，同时仍须 Idempotency-Key。",
          "required": true
        },
        {
          "name": "revision",
          "type": "integer",
          "description": "先读取 desk.read 返回的 state.revision。",
          "required": true
        },
        {
          "name": "id",
          "type": "string",
          "description": "已授权的会话编号。",
          "required": true
        },
        {
          "name": "version",
          "type": "integer",
          "description": "该会话当前 version；变更后须重新读取。",
          "required": true
        },
        {
          "name": "data",
          "type": "object",
          "description": "业务字段见请求示例；文本位于 data.text。",
          "required": true
        }
      ],
      "notes": [
        "示例中的 revision、version 和资源编号必须替换为当前读取值；未收到最终回执时，先读取原业务结果。",
        "owner 与 reason 必填；同名成员须使用 ownerId。此操作只创建邀请，对方接受前由原客服继续接待。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.acceptHandoff",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.acceptHandoff",
      "publicPath": "/v1/operations/desk.acceptHandoff",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "工作台与工单 · 接受转接邀请",
      "description": "以调用账号的身份接受一条发给自己的会话转接邀请：会话负责人改为调用账号、version 加 1，该邀请待办置为“已完成”，同一批其余邀请失效，并写入一条系统消息；接待状态保持人工接待。只能接受邀请对象是调用账号的邀请，不能代其他成员接受。",
      "request": "{\"action\":\"acceptHandoff\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":3}",
      "response": "{\"state\":{\"revision\":13,\"conversations\":[{\"id\":\"YOUR_CONVERSATION_ID\",\"version\":4,\"lifecycle\":\"OPEN\",\"handling\":\"HUMAN\",\"owner\":\"示例管理员\",\"ownerId\":\"YOUR_ACCOUNT_ID\"}],\"tasks\":[{\"id\":\"TD-1a2b3c4d\",\"kind\":\"转接邀请\",\"status\":\"已完成\",\"conversationId\":\"YOUR_CONVERSATION_ID\",\"owner\":\"示例管理员\",\"ownerId\":\"YOUR_ACCOUNT_ID\",\"handoffVersion\":3}]},\"result\":\"已确认接收转接\",\"executionReceipt\":null}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "会话编号：取 desk.read 返回的 state.conversations[].id。"
        },
        {
          "name": "version",
          "type": "integer",
          "required": true,
          "description": "该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "提交后调用账号授权范围内的完整工作台快照，结构与 desk.read 的 state 相同；示例只保留与本操作相关的字段。"
        },
        {
          "name": "state.revision",
          "type": "integer",
          "required": true,
          "description": "提交后的工作台版本；下一次写入使用此值。"
        },
        {
          "name": "state.conversations",
          "type": "object[]",
          "required": true,
          "description": "会话列表；按 id 找到目标会话，核对其 version、lifecycle、handling、owner 与 ownerId。"
        },
        {
          "name": "state.tasks",
          "type": "object[]",
          "required": true,
          "description": "待办列表；被接受的转接邀请 status 变为“已完成”，同一批其余邀请变为“已取消”。"
        },
        {
          "name": "result",
          "type": "string",
          "required": true,
          "description": "固定为“已确认接收转接”。"
        },
        {
          "name": "executionReceipt",
          "type": "object",
          "required": false,
          "description": "本操作固定返回 null。"
        }
      ],
      "notes": [
        "调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。",
        "状态前置：desk.read 的 state.tasks 中必须有一条 kind 为“转接邀请”、conversationId 为该会话、ownerId 为调用账号、status 为“待处理”的待办，且未过期（邀请发出后 15 分钟内有效）、其 handoffVersion 等于会话当前 version；否则返回 409。",
        "409：没有有效的转接邀请；会话已不是进行中的人工接待；当前不在坐席排班时间内；调用账号已达同时接待上限。",
        "原生消息渠道（机器人连接）的会话：渠道回复仍在发送或结果待核对、渠道绑定已变化、或该渠道当前仅可查看时返回 409。",
        "API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。",
        "以 API Key 调用时只能接受发给该管理员账号的邀请。接受成功还会把该账号的坐席状态置为在线（约 120 秒内有效），其间系统可能向它分配新的会话。",
        "结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。",
        "错误响应正文为 {\"error\":\"原因说明\"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.cancelHandoff",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.cancelHandoff",
      "publicPath": "/v1/operations/desk.cancelHandoff",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "工作台与工单 · 撤回转接邀请",
      "description": "撤回某会话尚未被接受的转接邀请：该会话当前归属版本下所有待接收的邀请都置为“已取消”，并写入一条内部备注。会话的负责人、接待状态和 version 都不变，不向客户发送消息。",
      "request": "{\"action\":\"cancelHandoff\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":3,\"data\":{\"offerId\":\"YOUR_HANDOFF_OFFER_ID\"}}",
      "response": "{\"state\":{\"revision\":13,\"conversations\":[{\"id\":\"YOUR_CONVERSATION_ID\",\"version\":3,\"lifecycle\":\"OPEN\",\"handling\":\"HUMAN\",\"owner\":\"原接待客服\",\"ownerId\":\"YOUR_CURRENT_OWNER_ID\"}],\"tasks\":[{\"id\":\"YOUR_HANDOFF_OFFER_ID\",\"kind\":\"转接邀请\",\"status\":\"已取消\",\"conversationId\":\"YOUR_CONVERSATION_ID\",\"owner\":\"受邀客服\",\"ownerId\":\"YOUR_MEMBER_ID\",\"handoffVersion\":3}]},\"result\":\"转接邀请已撤回，原负责人继续接待\",\"executionReceipt\":null}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "会话编号：取 desk.read 返回的 state.conversations[].id。"
        },
        {
          "name": "version",
          "type": "integer",
          "required": true,
          "description": "该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。"
        },
        {
          "name": "data",
          "type": "object",
          "required": true,
          "description": "撤回参数。"
        },
        {
          "name": "data.offerId",
          "type": "string",
          "required": true,
          "description": "要撤回的转接邀请编号，最多 100 个字符：取 desk.read 返回的 state.tasks[] 中 kind 为“转接邀请”、conversationId 等于该会话、status 为“待处理”的待办的 id。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "提交后调用账号授权范围内的完整工作台快照，结构与 desk.read 的 state 相同；示例只保留与本操作相关的字段。"
        },
        {
          "name": "state.revision",
          "type": "integer",
          "required": true,
          "description": "提交后的工作台版本；下一次写入使用此值。"
        },
        {
          "name": "state.conversations",
          "type": "object[]",
          "required": true,
          "description": "会话列表；按 id 找到目标会话，核对其 version、lifecycle、handling、owner 与 ownerId。"
        },
        {
          "name": "state.tasks",
          "type": "object[]",
          "required": true,
          "description": "待办列表；该会话当前归属版本下的转接邀请 status 变为“已取消”。"
        },
        {
          "name": "result",
          "type": "string",
          "required": true,
          "description": "固定为“转接邀请已撤回，原负责人继续接待”。"
        },
        {
          "name": "executionReceipt",
          "type": "object",
          "required": false,
          "description": "本操作固定返回 null。"
        }
      ],
      "notes": [
        "调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。",
        "状态前置：邀请必须仍然有效——status 为“待处理”、未过期（发出后 15 分钟内）、会话仍是进行中的人工接待、邀请的 handoffVersion 等于会话当前 version；否则返回 409（邀请已被接受、已过期或已失效）。",
        "400：data.offerId 缺失、为空或超过 100 个字符。desk.handoff 的响应不单独返回邀请编号，需在其返回的 state.tasks 或之后的 desk.read 中查找。",
        "API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。",
        "以 API Key 调用时可撤回本企业任意会话的有效邀请，不要求调用账号是该会话负责人。",
        "结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。",
        "错误响应正文为 {\"error\":\"原因说明\"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk.releaseToAI",
      "group": "会话接待",
      "method": "POST",
      "currentPath": "/v1/operations/desk.releaseToAI",
      "publicPath": "/v1/operations/desk.releaseToAI",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "工作台与工单 · 交回 AI 接待",
      "description": "把调用账号正在人工接待的会话交回 AI：接待状态变为 AI、version 加 1，并写入一条系统消息；非独占接待的会话负责人改为“AI 助手”。AI 在收到客户下一条消息后才继续回复，本操作本身不向客户发送任何回复。",
      "request": "{\"action\":\"releaseToAI\",\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"revision\":12,\"id\":\"YOUR_CONVERSATION_ID\",\"version\":3,\"data\":{\"handoffSummary\":\"已核实订单信息，客户等待物流更新。\"}}",
      "response": "{\"state\":{\"revision\":13,\"conversations\":[{\"id\":\"YOUR_CONVERSATION_ID\",\"version\":4,\"lifecycle\":\"OPEN\",\"handling\":\"AI\",\"owner\":\"AI 助手\",\"ownerId\":\"\"}]},\"result\":\"已交由 AI 继续接待\",\"executionReceipt\":null}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "会话编号：取 desk.read 返回的 state.conversations[].id。"
        },
        {
          "name": "version",
          "type": "integer",
          "required": true,
          "description": "该会话的 version：取同一次 desk.read 返回的 state.conversations[].version；缺失或与当前值不相等都返回 409。"
        },
        {
          "name": "data",
          "type": "object",
          "required": false,
          "description": "可选参数；不留交接备注时可省略。"
        },
        {
          "name": "data.handoffSummary",
          "type": "string",
          "required": false,
          "description": "交接备注，最多 1000 个字符；去除首尾空白后非空时，作为一条内部备注写入会话。省略或只有空白则不写备注。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "提交后调用账号授权范围内的完整工作台快照，结构与 desk.read 的 state 相同；示例只保留与本操作相关的字段。"
        },
        {
          "name": "state.revision",
          "type": "integer",
          "required": true,
          "description": "提交后的工作台版本；下一次写入使用此值。"
        },
        {
          "name": "state.conversations",
          "type": "object[]",
          "required": true,
          "description": "会话列表；按 id 找到目标会话，核对其 version、lifecycle、handling、owner 与 ownerId。"
        },
        {
          "name": "state.conversations[].handling",
          "type": "string",
          "required": true,
          "description": "目标会话变为 AI。"
        },
        {
          "name": "state.conversations[].ownerId",
          "type": "string",
          "required": true,
          "description": "非独占接待的会话变为空字符串（owner 为“AI 助手”）；独占接待的会话保留原负责人。"
        },
        {
          "name": "result",
          "type": "string",
          "required": true,
          "description": "固定为“已交由 AI 继续接待”。"
        },
        {
          "name": "executionReceipt",
          "type": "object",
          "required": false,
          "description": "本操作固定返回 null。"
        }
      ],
      "notes": [
        "调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。",
        "状态前置：会话必须进行中（lifecycle 为 OPEN，已关闭返回 409）、handling 为 HUMAN 且 ownerId 为调用账号，否则返回 403；调用账号需先通过 desk.claim 或 desk.acceptHandoff 成为负责人。",
        "409：会话的 unknown 为 true，或该会话存在未完成的“审批”“未知结果”类待办；会话所属客服组为影子运行或仅建议模式。400：data.handoffSummary 不是字符串或超过 1000 个字符；桌面连接器渠道的会话不支持交回 AI。",
        "原生消息渠道（机器人连接）的会话：渠道回复仍在发送或结果待核对、渠道绑定已变化、或该渠道当前仅可查看时返回 409。",
        "API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。",
        "结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。",
        "错误响应正文为 {\"error\":\"原因说明\"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge.read",
      "name": "读取知识库",
      "group": "知识检索",
      "method": "GET",
      "currentPath": "/v1/operations/knowledge.read",
      "publicPath": "/v1/operations/knowledge.read",
      "status": "available",
      "description": "GET 不传 id 列出文档；传 id 返回文档和切片。save 保存草稿，preview 仅切片，index 真实调用向量模型，retrieve 按智能体知识配置检索，publish 只发布已完成且匹配当前配置的索引，unpublish/delete 受版本与引用约束。",
      "scopes": [
        "knowledge"
      ],
      "request": "?",
      "response": "{\"documents\":[]}",
      "requestFields": [
        {
          "name": "agentId (query)",
          "description": "智能体配置类接口通过查询参数指定；默认 default。",
          "type": "string",
          "required": false
        },
        {
          "name": "query",
          "description": "retrieve 的检索问题，最多 2000 字。",
          "type": "string",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "documents",
          "description": "列表分支的文档元数据。",
          "type": "array",
          "required": false
        },
        {
          "name": "document",
          "description": "传 id 时返回文档详情。",
          "type": "object",
          "required": false
        },
        {
          "name": "chunks",
          "description": "详情分支对应当前草稿或发布代次的切片。",
          "type": "array",
          "required": false
        }
      ],
      "notes": [
        "响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。",
        "GET 不传 id 列出文档；传 id 返回文档和切片。save 保存草稿，preview 仅切片，index 真实调用向量模型，retrieve 按智能体知识配置检索，publish 只发布已完成且匹配当前配置的索引，unpublish/delete 受版本与引用约束。",
        "应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "knowledge.save",
      "name": "知识库 · 保存",
      "group": "知识检索",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge.save",
      "publicPath": "/v1/operations/knowledge.save",
      "status": "available",
      "description": "知识库 · 保存",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"save\",\"title\":\"退款说明\",\"content\":\"退款申请需提供订单号。\",\"chunkSize\":600,\"overlap\":80}",
      "response": "{\"ok\":true,\"chunks\":1}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "title",
          "type": "string",
          "description": "文档名称，最多 150 字。",
          "required": true
        },
        {
          "name": "content",
          "type": "string",
          "description": "已获授权的知识正文。",
          "required": true
        },
        {
          "name": "chunkSize",
          "type": "integer",
          "description": "分段长度，200–2000。",
          "required": true
        },
        {
          "name": "overlap",
          "type": "integer",
          "description": "重叠字符，0–500 且小于 chunkSize / 2。",
          "required": true
        },
        {
          "name": "id",
          "type": "string",
          "description": "更新现有文档时使用其编号。",
          "required": false,
          "requiredWhen": "更新已有文档"
        },
        {
          "name": "revision",
          "type": "integer",
          "description": "更新现有文档时使用当前版本。",
          "required": false,
          "requiredWhen": "更新已有文档"
        }
      ],
      "notes": [
        "先读取文档或智能体的当前版本，不照抄示例中的版本号。",
        "保存只返回 ok 与 chunks；新文档编号请从知识目录读取，不能从该响应推断。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge.preview",
      "name": "知识库 · 预览",
      "group": "知识检索",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge.preview",
      "publicPath": "/v1/operations/knowledge.preview",
      "status": "available",
      "description": "GET 不传 id 列出文档；传 id 返回文档和切片。save 保存草稿，preview 仅切片，index 真实调用向量模型，retrieve 按智能体知识配置检索，publish 只发布已完成且匹配当前配置的索引，unpublish/delete 受版本与引用约束。",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"preview\",\"content\":\"待检索的客服知识正文\",\"chunkSize\":500,\"overlap\":50}",
      "response": "{\"chunks\":[]}",
      "requestFields": [
        {
          "name": "id",
          "description": "操作目标的真实资源 ID；不能使用其他企业 ID。",
          "type": "string",
          "required": false
        },
        {
          "name": "revision",
          "description": "先读取当前资源修订号；共享配置与单资源修订号不可混用。",
          "type": "integer",
          "required": false
        },
        {
          "name": "agentId (query)",
          "description": "智能体配置类接口通过查询参数指定；默认 default。",
          "type": "string",
          "required": false
        },
        {
          "name": "title",
          "description": "save 文档标题，最多 150 字。",
          "type": "string",
          "required": false
        },
        {
          "name": "content",
          "description": "save/preview 正文，最多 50000 字。",
          "type": "string",
          "required": false
        },
        {
          "name": "chunkSize",
          "description": "切片长度 200–2000。",
          "type": "integer",
          "required": false
        },
        {
          "name": "overlap",
          "description": "重叠 0–500 且小于切片长度一半。",
          "type": "integer",
          "required": false
        },
        {
          "name": "query",
          "description": "retrieve 的检索问题，最多 2000 字。",
          "type": "string",
          "required": false
        },
        {
          "name": "mode",
          "description": "index 可指定 keyword 使用关键词索引；否则使用智能体当前配置的向量模型。",
          "type": "string",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "chunks",
          "description": "preview 返回切片数组；save/index 返回切片数量。",
          "type": "array | integer",
          "required": false
        },
        {
          "name": "ok",
          "description": "保存、索引或发布操作成功；检索/预览分支另有结构。",
          "type": "boolean",
          "required": false
        },
        {
          "name": "tokens / latency",
          "description": "index 返回使用量与毫秒耗时，未报告时不填充零。",
          "type": "number",
          "required": false
        },
        {
          "name": "hits",
          "description": "retrieve 返回匹配片段，含文档编号、内容和评分。",
          "type": "array",
          "required": false
        },
        {
          "name": "candidateCount / queryTokens / reason",
          "description": "retrieve 的候选数量、查询用量及无命中说明。",
          "type": "string",
          "required": false
        }
      ],
      "notes": [
        "响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。",
        "GET 不传 id 列出文档；传 id 返回文档和切片。save 保存草稿，preview 仅切片，index 真实调用向量模型，retrieve 按智能体知识配置检索，publish 只发布已完成且匹配当前配置的索引，unpublish/delete 受版本与引用约束。",
        "应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge.retrieve",
      "name": "知识库 · 检索",
      "group": "知识检索",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge.retrieve?agentId=YOUR_AGENT_ID",
      "publicPath": "/v1/operations/knowledge.retrieve",
      "status": "available",
      "description": "知识库 · 检索",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"retrieve\",\"query\":\"退款需要哪些材料？\",\"scope\":\"published\",\"expectedVersion\":1}",
      "response": "{\"scope\":\"published\",\"version\":1,\"hits\":[]}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "agentId (query)",
          "type": "string",
          "description": "已配置知识绑定的智能体编号。",
          "required": false
        },
        {
          "name": "query",
          "type": "string",
          "description": "检索问题，最多 2000 字。",
          "required": true
        },
        {
          "name": "scope",
          "type": "string",
          "description": "draft 或 published；默认 draft。",
          "required": false
        },
        {
          "name": "expectedVersion",
          "type": "integer",
          "description": "对应草稿 revision 或已发布 publishedVersion；用于核对目标版本。",
          "required": false
        }
      ],
      "notes": [
        "先读取文档或智能体的当前版本，不照抄示例中的版本号。",
        "检索按所选智能体的知识绑定与版本执行；published 需已有发布版本。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge.index",
      "name": "知识库 · 建立索引",
      "group": "知识检索",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge.index",
      "publicPath": "/v1/operations/knowledge.index",
      "status": "available",
      "description": "知识库 · 建立索引",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"index\",\"id\":\"YOUR_DOCUMENT_ID\",\"revision\":1}",
      "response": "{\"ok\":true}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "description": "已存在的知识文档编号。",
          "required": true
        },
        {
          "name": "revision",
          "type": "integer",
          "description": "知识目录读取的当前文档版本。",
          "required": true
        }
      ],
      "notes": [
        "先读取文档或智能体的当前版本，不照抄示例中的版本号。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge.publish",
      "name": "知识库 · 发布",
      "group": "知识检索",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge.publish",
      "publicPath": "/v1/operations/knowledge.publish",
      "status": "available",
      "description": "知识库 · 发布",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"publish\",\"id\":\"YOUR_DOCUMENT_ID\",\"revision\":2}",
      "response": "{\"ok\":true}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "description": "已存在的知识文档编号。",
          "required": true
        },
        {
          "name": "revision",
          "type": "integer",
          "description": "知识目录读取的当前文档版本。",
          "required": true
        }
      ],
      "notes": [
        "先读取文档或智能体的当前版本，不照抄示例中的版本号。",
        "须先完成当前草稿索引（ready），并满足已绑定智能体的向量配置。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge.unpublish",
      "group": "知识检索",
      "name": "知识库 · 撤回文档发布",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge.unpublish",
      "publicPath": "/v1/operations/knowledge.unpublish",
      "status": "available",
      "description": "撤回一篇知识文档的线上版本：清空它的已发布索引标记，线上检索立即不再命中这篇文档。正文、当前草稿索引和智能体的知识绑定都保留，不删除任何内容。",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"unpublish\",\"id\":\"YOUR_DOCUMENT_ID\",\"revision\":3}",
      "response": "{\"ok\":true}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "知识文档编号。先调用 knowledge.read，取 documents[].id。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "该文档的当前版本号，取 knowledge.read 返回的 documents[].revision。必须是 JSON 数字并与服务端完全一致，否则返回 409。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，表示已撤回。响应不返回新的 revision（服务端已加 1），后续操作前需重新调用 knowledge.read。"
        }
      ],
      "notes": [
        "前置条件：先调用 knowledge.read 取得 id 与 revision。本操作不读取 agentId 查询参数，也不要求文档处于某个状态；对一篇尚未发布的文档调用同样返回成功，并使 revision 加 1。",
        "对智能体的影响：接口不检查文档是否被智能体使用。已发布智能体如果绑定了这篇文档，会立即检索不到它，但绑定关系不会被移除；之后再发布这些智能体时，发布检查会因“知识尚未发布”而不通过，直到重新发布该文档或在智能体配置中解除绑定。",
        "可逆：文档 status 为 ready 且 draft_gen 非空时，用新的 revision 调用 knowledge.publish 即可重新上线，无需重建索引；重新上线的是当前草稿索引，不一定是撤回前的线上版本。若文档在此之前被改过（status 为 draft 或 error），需先调用 knowledge.index（会计费）。",
        "错误：404 文档不存在或未传 id；409 revision 与当前版本不一致（“文档版本已变化，请重新加载”）；409 文档正在索引且最近 180 秒内有更新（“文档正在索引，请等待完成后再操作”）；409 写入时文档版本或密钥授权已变化（“文档已更新”）。遇到 409 先重新读取再决定是否重试。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge.delete",
      "group": "知识检索",
      "name": "知识库 · 永久删除文档",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge.delete",
      "publicPath": "/v1/operations/knowledge.delete",
      "status": "available",
      "description": "永久删除一篇知识文档及其全部索引切片（草稿与已发布版本）。删除后无法恢复，也不会自动解除智能体对这篇文档的绑定。",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"delete\",\"id\":\"YOUR_DOCUMENT_ID\",\"revision\":3}",
      "response": "{\"ok\":true}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "知识文档编号。先调用 knowledge.read，取 documents[].id。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "该文档的当前版本号，取 knowledge.read 返回的 documents[].revision。必须是 JSON 数字并与服务端完全一致，否则返回 409。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，表示文档和切片已删除。"
        }
      ],
      "notes": [
        "前置条件：先调用 knowledge.read 取得 id 与 revision。草稿、已索引和已发布的文档都可以直接删除，不需要先调用 knowledge.unpublish；本操作不读取 agentId 查询参数。",
        "不可逆：接口直接删除文档和切片，没有回收站。需要保留内容时，请先用 knowledge.read?id=文档编号 读取正文自行备份。",
        "对智能体的影响：接口不检查文档是否被智能体使用。已发布智能体立即检索不到这篇文档，但智能体配置中仍保留该文档编号；之后再发布这些智能体时，发布检查会因“知识尚未发布”而不通过，需先在智能体配置中移除绑定。",
        "来自知识源同步的文档（source_id 非空）：如果知识源的 refs 仍包含对应引用，下一次同步会用相同的文档编号把它重新创建为草稿。要彻底移除，请先用 knowledge-sources.save 从 refs 中去掉该引用。",
        "错误：404 文档不存在或未传 id；409 revision 与当前版本不一致；409 文档正在索引且最近 180 秒内有更新；409 写入时文档版本或密钥授权已变化（“文档已更新，未执行删除”）。响应不确定时用同一个 Idempotency-Key 重试；换新键重试一篇已删除的文档会得到 404。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge-sources.read",
      "name": "读取知识源",
      "group": "知识检索",
      "method": "GET",
      "currentPath": "/v1/operations/knowledge-sources.read",
      "publicPath": "/v1/operations/knowledge-sources.read",
      "status": "available",
      "description": "GET 返回 sources/logs/scheduler。sync 执行已保存来源同步，save 保存连接，pause 启停；定时同步必须有原生 scheduled 调度。同步内容作为不可信知识，不具备修改系统指令或授权的能力。",
      "scopes": [
        "knowledge"
      ],
      "request": "?",
      "response": "{\"sources\":[],\"logs\":[]}",
      "requestFields": [],
      "responseFields": [
        {
          "name": "sources",
          "description": "来源列表，凭据已脱敏。",
          "type": "array",
          "required": false
        },
        {
          "name": "logs",
          "description": "最多 100 条同步记录。",
          "type": "array",
          "required": false
        },
        {
          "name": "scheduler",
          "description": "当前调度能力说明。",
          "type": "object",
          "required": false
        }
      ],
      "notes": [
        "响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。",
        "GET 返回 sources/logs/scheduler。sync 执行已保存来源同步，save 保存连接，pause 启停；定时同步必须有原生 scheduled 调度。同步内容作为不可信知识，不具备修改系统指令或授权的能力。",
        "应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "knowledge-sources.save",
      "group": "知识检索",
      "name": "知识源 · 新建或更新连接",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge-sources.save",
      "publicPath": "/v1/operations/knowledge-sources.save",
      "status": "available",
      "description": "新建或更新一个外部知识源连接，保存来源平台、文档引用、访问凭据和同步频率。保存本身不拉取任何内容；内容由 knowledge-sources.sync 或定时计划拉取成知识草稿。",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"save\",\"provider\":\"website\",\"name\":\"官网帮助文档\",\"appId\":{\"schemaVersion\":1,\"startUrl\":\"https://docs.your-company.com/\",\"maxPages\":100,\"maxDepth\":2,\"followSitemap\":false},\"refs\":[\"https://docs.your-company.com/\"],\"intervalHours\":24}",
      "response": "{\"ok\":true,\"id\":\"YOUR_SOURCE_ID\"}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "requiredWhen": "更新已有知识源",
          "description": "知识源编号，取 knowledge-sources.read 返回的 sources[].id。省略表示新建。"
        },
        {
          "name": "revision",
          "type": "integer",
          "requiredWhen": "更新已有知识源",
          "description": "该知识源的当前版本号，取 sources[].revision；必须是 JSON 数字并与服务端一致。"
        },
        {
          "name": "provider",
          "type": "string",
          "required": true,
          "description": "来源平台：website（网站/Sitemap）、http_api（通用 API）、notion、google_drive、slack、confluence、sharepoint、feishu、wecom、dingtalk。更新时不能更换平台。"
        },
        {
          "name": "name",
          "type": "string",
          "required": true,
          "description": "连接名称，1–80 个字符。"
        },
        {
          "name": "refs",
          "type": "string[]",
          "requiredWhen": "除钉钉统一应用方式（provider=dingtalk 且 authMode=platform）外的所有来源",
          "description": "要同步的文档引用，1–8 项，每项最多 500 个字符，重复项会合并。website：填与 appId.startUrl 相同的公网 HTTPS 起始页地址（实际抓取范围由 appId 决定）；http_api：读取接口的 HTTPS 地址，必须与 appId.origin 同域名；notion：页面链接或 32 位页面 ID；google_drive：文件链接或文件 ID；slack：频道 ID、“频道 ID:线程时间戳”或官方频道/线程链接；confluence：页面链接或数字页面 ID；sharepoint：页面 UUID；feishu：docs/docx/wiki 文档链接；wecom：文档链接或 docid；dingtalk 自建应用：文档链接或文档 ID。"
        },
        {
          "name": "appId",
          "type": "object",
          "requiredWhen": "provider 为 website、http_api、confluence、sharepoint，或 feishu、wecom、dingtalk 使用自建应用（authMode 不是 platform）",
          "description": "来源的非密钥配置。website、http_api、dingtalk 传对象（字段见下方 appId.*）；confluence 传站点地址字符串（如 https://your-team.atlassian.net）；sharepoint 传 Microsoft Graph 站点 ID 字符串；feishu、wecom 自建应用传应用 ID 字符串（1–120 位字母、数字、下划线或连字符）。notion、google_drive、slack 不使用此字段。该值会在 knowledge-sources.read 中以 app_id 原样返回，不要放入密钥。"
        },
        {
          "name": "appId.schemaVersion",
          "type": "integer",
          "requiredWhen": "provider 为 website 或 http_api",
          "description": "配置版本，固定为 1。"
        },
        {
          "name": "appId.startUrl",
          "type": "string",
          "requiredWhen": "provider 为 website",
          "description": "抓取起始页的公网 HTTPS 地址，最多 500 个字符，不能包含账号密码或 # 片段。"
        },
        {
          "name": "appId.maxPages",
          "type": "integer",
          "required": false,
          "description": "仅 website：最多抓取的页面数，1–500，省略为 100。"
        },
        {
          "name": "appId.maxDepth",
          "type": "integer",
          "required": false,
          "description": "仅 website：从起始页跟随同源链接的最大深度，0–5，省略为 2。"
        },
        {
          "name": "appId.followSitemap",
          "type": "boolean",
          "required": false,
          "description": "仅 website：true 时同时抓取站点 sitemap 中的页面，省略为 false。"
        },
        {
          "name": "appId.origin",
          "type": "string",
          "requiredWhen": "provider 为 http_api",
          "description": "业务接口的服务域名，只写协议和域名（如 https://api.your-company.com），必须是公网 HTTPS，不能带路径、查询、端口或凭据。"
        },
        {
          "name": "appId.auth",
          "type": "string",
          "requiredWhen": "provider 为 http_api",
          "description": "鉴权方式：bearer（secret 作为 Authorization: Bearer 发送）、header（secret 放入 appId.headerName 指定的请求头）或 none（不需要 secret）。"
        },
        {
          "name": "appId.headerName",
          "type": "string",
          "requiredWhen": "appId.auth 为 header",
          "description": "携带 secret 的请求头名称，如 X-API-Key；字母开头，只含字母、数字和连字符，最多 64 位，不能是 Authorization、Cookie、Host、Content-Length、Content-Type、Connection 或 Accept。"
        },
        {
          "name": "appId.recordsPath",
          "type": "string",
          "requiredWhen": "provider 为 http_api",
          "description": "响应 JSON 中资料列表的点分路径（如 data.items），最多 160 个字符；列表就在响应根部时传空字符串。"
        },
        {
          "name": "appId.idPath",
          "type": "string",
          "requiredWhen": "provider 为 http_api",
          "description": "每条资料中稳定标识字段的点分路径，不能为空。"
        },
        {
          "name": "appId.titlePath",
          "type": "string",
          "requiredWhen": "provider 为 http_api",
          "description": "每条资料中标题字段的点分路径，不能为空。"
        },
        {
          "name": "appId.contentPath",
          "type": "string",
          "requiredWhen": "provider 为 http_api",
          "description": "每条资料中正文字段的点分路径，不能为空。"
        },
        {
          "name": "appId.urlPath",
          "type": "string",
          "requiredWhen": "provider 为 http_api",
          "description": "每条资料中来源链接字段的点分路径；没有时传空字符串（不能省略该键）。"
        },
        {
          "name": "appId.updatedPath",
          "type": "string",
          "requiredWhen": "provider 为 http_api",
          "description": "每条资料中更新时间字段的点分路径；没有时传空字符串（不能省略该键）。"
        },
        {
          "name": "appId.nextCursorPath",
          "type": "string",
          "requiredWhen": "provider 为 http_api",
          "description": "响应 JSON 中下一页游标的点分路径；接口不分页时传空字符串（不能省略该键）。单次同步最多读取 5 页、200 条资料。"
        },
        {
          "name": "appId.cursorParameter",
          "type": "string",
          "requiredWhen": "appId.nextCursorPath 非空",
          "description": "翻页时携带游标的查询参数名，字母开头，只含字母、数字和下划线，最多 64 位，名称中不能含 token、secret、password 或 key。"
        },
        {
          "name": "appId.appKey",
          "type": "string",
          "requiredWhen": "provider 为 dingtalk 且使用自建应用",
          "description": "钉钉自建应用的 AppKey，最多 120 个字符。"
        },
        {
          "name": "appId.operatorId",
          "type": "string",
          "requiredWhen": "provider 为 dingtalk 且使用自建应用",
          "description": "有权读取目标文档的钉钉操作人 Union ID，最多 200 个字符。"
        },
        {
          "name": "secret",
          "type": "string",
          "requiredWhen": "新建需要凭据的来源；或更新时更换了 appId（http_api 为 origin、auth、headerName 任一变化）",
          "description": "访问凭据，最多 8192 个字符，不能含换行。notion：内部连接 Token；google_drive：有 drive.readonly 权限的 OAuth 访问令牌；slack：xoxb-/xoxp- OAuth Token；confluence：“邮箱:API 令牌”；sharepoint：Microsoft Graph 访问令牌；http_api：接口凭据；feishu、wecom、dingtalk 自建应用：应用密钥。website、http_api 的 auth=none 以及统一应用方式不需要。更新时省略则沿用已保存的凭据。凭据只加密保存，任何读取接口都不返回明文，只返回 secretSet。"
        },
        {
          "name": "authMode",
          "type": "string",
          "required": false,
          "description": "连接方式：platform（复用平台统一应用，仅 feishu、wecom、dingtalk 可用）或 custom（自建应用或自备凭据）。新建时省略按 custom 处理；更新时省略沿用原方式。"
        },
        {
          "name": "connectionId",
          "type": "string",
          "requiredWhen": "authMode 为 platform 的新建",
          "description": "企业已授权的统一应用连接编号，取 knowledge-sources.read 返回的 feishuConnections、wecomConnections 或 dingtalkConnections 中 available 为 true 的 id。"
        },
        {
          "name": "intervalHours",
          "type": "integer",
          "required": true,
          "description": "定时同步间隔（小时），只能是 0、1、6、24 或 168；0 表示只手动同步。钉钉统一应用方式必须为 0。大于 0 时，保存后该来源立即到期，等待调度拉取。"
        },
        {
          "name": "enabled",
          "type": "boolean",
          "required": false,
          "description": "是否启用同步。只有显式传 false 才停用；省略按 true 处理，因此更新一个已暂停的来源时省略此字段会把它重新启用。"
        },
        {
          "name": "targetLibraryId",
          "type": "string",
          "required": false,
          "description": "同步内容同时写入的帮助中心资料库编号，取 knowledge-sources.read 返回的 libraries 中 enabled 为 true 的 id，最多 100 个字符。传空字符串清除；更新时省略沿用原值。"
        },
        {
          "name": "exportDocument",
          "type": "object",
          "requiredWhen": "provider=dingtalk 且 authMode=platform 的首次保存",
          "description": "从钉钉导出的文档内容；钉钉统一应用方式不读取云端文档，只同步这里提交的正文。更新时省略沿用上次提交的内容。"
        },
        {
          "name": "exportDocument.title",
          "type": "string",
          "requiredWhen": "提供 exportDocument",
          "description": "文档标题，1–200 个字符。"
        },
        {
          "name": "exportDocument.content",
          "type": "string",
          "requiredWhen": "提供 exportDocument",
          "description": "文档正文，最多 50,000 个字符；更长的文档请拆成多个知识源。"
        },
        {
          "name": "exportDocument.fileName",
          "type": "string",
          "requiredWhen": "提供 exportDocument",
          "description": "导出文件名，最多 255 个字符，可为空字符串。"
        },
        {
          "name": "exportDocument.warnings",
          "type": "string[]",
          "requiredWhen": "提供 exportDocument",
          "description": "导入时需要提示的缺失内容说明，最多 50 条、每条最多 1000 个字符；没有时传空数组。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，表示连接已保存。"
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "知识源编号：新建时为新生成的编号，更新时为原编号。响应不返回 revision（新建后为 1，更新后加 1），后续 sync 或 pause 前请重新调用 knowledge-sources.read。"
        }
      ],
      "notes": [
        "前置条件：更新前先调用 knowledge-sources.read 取得 sources[].id 与 revision；新建不传 id。每个企业最多 20 个知识源，超出返回 409。",
        "凭据提交与回显：secret 只写不读，读取时只有 secretSet 表示是否已配置；appId 和 refs 会原样返回，不要在其中放密钥（http_api 的地址若带 token、secret、password、authorization、api_key 这类查询参数会被拒绝）。",
        "更新的副作用：保存会把来源状态重置为 ready 并清空上次错误；正在排队或执行的同步会因版本变化而中止，尚未写入的文档不再写入，也不生成同步记录；省略 enabled 会重新启用来源。",
        "错误：400 字段校验失败（未知 provider、refs 不是 1–8 项或格式不符、intervalHours 不在允许值内、缺少凭据、更换 appId 后未重新提供 secret、更新时更换 provider、authMode 无效等）；403 所选平台不适用于当前站点，或统一应用授权不属于当前企业、尚未完成授权；404 知识源不存在，或 targetLibraryId 不存在、已停用；409 revision 不一致（“来源已修改，请刷新后重试”）；409 “连接已达 20 个，或账户权限已变化”。",
        "归属与大小：知识源归属于保存它的企业管理员账号（API Key 调用时为密钥所属账号）；该账号停用或失去知识权限后，同步会被取消，来源可能被置为停用并标记为需要重新授权（status 为 reauthorize），需重新保存连接。请求正文最多 150,000 个字符。",
        "API Key 调用的限制：平台可用范围固定按中国站规则判定，provider 为 confluence 或 sharepoint 时固定返回 403“该知识平台仅适用于国际站”。",
        "重试：新建不按名称去重。响应不确定时用同一个 Idempotency-Key 重试会重放原结果；不要换新键重试，应先调用 knowledge-sources.read 确认是否已创建。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge-sources.sync",
      "group": "知识检索",
      "name": "知识源 · 立即同步",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge-sources.sync",
      "publicPath": "/v1/operations/knowledge-sources.sync",
      "status": "available",
      "description": "为一个已保存且启用的知识源排队一次后台拉取，立即返回 HTTP 202 和任务编号，不等待拉取完成。拉取到的内容写成知识文档草稿，不会自动建立索引或发布。",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"sync\",\"id\":\"YOUR_SOURCE_ID\",\"revision\":1}",
      "response": "{\"accepted\":true,\"taskId\":\"YOUR_TASK_ID\",\"sourceId\":\"YOUR_SOURCE_ID\",\"status\":\"queued\",\"reused\":false}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "知识源编号，取 knowledge-sources.read 返回的 sources[].id。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "该知识源的当前版本号，取 sources[].revision；必须是 JSON 数字并与服务端一致。"
        }
      ],
      "responseFields": [
        {
          "name": "accepted",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，表示任务已受理；不代表拉取成功。"
        },
        {
          "name": "taskId",
          "type": "string",
          "required": true,
          "description": "后台任务编号，对应进度查询中的 task_id。"
        },
        {
          "name": "sourceId",
          "type": "string",
          "required": true,
          "description": "本次同步的知识源编号。"
        },
        {
          "name": "status",
          "type": "string",
          "required": true,
          "description": "queued（排队中）或 running（已在执行）。"
        },
        {
          "name": "reused",
          "type": "boolean",
          "required": true,
          "description": "true 表示该来源已有排队或执行中的任务，本次调用没有新建任务；false 表示本次新排了任务。"
        }
      ],
      "notes": [
        "前置条件：先调用 knowledge-sources.read 取得 sources[].id 与 revision，并确认来源 enabled 为 1。成功的状态码是 202 而不是 200。",
        "查询进度：轮询 knowledge-sources.read?mode=progress，返回 sources[]（id、revision、status、error、last_at、next_at、lease_until、task_id、task_status、task_updated）；task_status 为 pending 或 leased 表示仍在排队或执行；长时间停在 pending 时，查看 knowledge-sources.read 返回的 scheduler.mode 与 scheduler.message 确认后台执行进程是否在线。结束后调用 knowledge-sources.read?selected=知识源编号（不带 mode），在 logs[] 中查看该来源最新一条记录（logs 只含全企业最近 100 条，selected 保证包含该来源最近一次的记录）：status 为 success、partial 或 error，detail 含 added、changed、unchanged、failures 以及每个引用的 results（outcome、documentId、error）。",
        "同步之后：新增或有变化的文档是草稿（status 为 draft），需要对每篇文档依次调用 knowledge.index 和 knowledge.publish 才会被线上检索命中；已在本地补齐并脱离同步的文档不会被覆盖。",
        "费用：同步只读取来源并写入草稿，不调用模型，不产生费用；向量化费用在后续的 knowledge.index 产生。",
        "错误：404 未传 id 或知识源不存在；409 revision 不一致；429“拉取暂未受理”——来源已停用、正在同步、距上次同步结束不足 15 秒、仍在来源平台限流冷却期，或排队中的同步任务已达上限（响应带 Retry-After，但来源停用时重试无效，需先调用 knowledge-sources.pause 并传 enabled=true）；409“旧配置的任务正在结束，请稍后重新拉取”；403 飞书、企业微信或钉钉统一应用的企业授权已失效。",
        "重复调用：同一知识源同一时间只有一个同步任务，重复调用返回同一个 taskId 且 reused 为 true。单次同步最长执行约 330 秒，附件下载合计不超过 64 MiB；超时后未处理的引用在同步记录中标为 not_processed，留待下次同步。",
        "已知限制：provider 为 dingtalk 且使用自建应用（authMode 为 custom）的知识源不能用本操作手动同步，固定返回 400“请选择当前企业的钉钉统一应用”，只能等待定时同步（intervalHours 大于 0）。",
        "API Key 调用：后台任务以密钥所属账号的身份执行；任务开始前该账号被停用或失去知识权限时，任务会被取消且不生成同步记录。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "knowledge-sources.pause",
      "name": "知识源 · 启用或暂停同步",
      "group": "知识检索",
      "method": "POST",
      "currentPath": "/v1/operations/knowledge-sources.pause",
      "publicPath": "/v1/operations/knowledge-sources.pause",
      "status": "available",
      "description": "GET 返回 sources/logs/scheduler。sync 执行已保存来源同步，save 保存连接，pause 启停；定时同步必须有原生 scheduled 调度。同步内容作为不可信知识，不具备修改系统指令或授权的能力。",
      "scopes": [
        "knowledge"
      ],
      "request": "{\"action\":\"pause\",\"id\":\"source_example\",\"revision\":1,\"enabled\":false}",
      "response": "{\"ok\":true}",
      "requestFields": [
        {
          "name": "id",
          "description": "操作目标的真实资源 ID；不能使用其他企业 ID。",
          "type": "string",
          "required": false
        },
        {
          "name": "revision",
          "description": "先读取当前资源修订号；共享配置与单资源修订号不可混用。",
          "type": "integer",
          "required": false
        },
        {
          "name": "provider / name / appId",
          "description": "来源平台、连接名称、应用编号；Notion 不需要 appId。",
          "type": "string",
          "required": false
        },
        {
          "name": "secret",
          "description": "首次保存或更换应用时必填连接凭据；只加密存储。",
          "type": "string",
          "required": false
        },
        {
          "name": "refs",
          "description": "来源平台的文档引用列表。",
          "type": "array",
          "required": false
        },
        {
          "name": "intervalHours",
          "description": "0/1/6/24/168。",
          "type": "integer",
          "required": false
        },
        {
          "name": "enabled",
          "description": "save/pause 的启用状态。",
          "type": "boolean",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "description": "save/pause 的成功标记，sync 返回独立同步报告。",
          "type": "boolean",
          "required": false
        }
      ],
      "notes": [
        "响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。",
        "GET 返回 sources/logs/scheduler。sync 执行已保存来源同步，save 保存连接，pause 启停；定时同步必须有原生 scheduled 调度。同步内容作为不可信知识，不具备修改系统指令或授权的能力。",
        "应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "desk-knowledge.read",
      "group": "会话接待",
      "name": "读取客服知识检索",
      "method": "GET",
      "currentPath": "/v1/operations/desk-knowledge.read?q=%E9%80%80%E6%AC%BE&page=1",
      "publicPath": "/v1/operations/desk-knowledge.read",
      "status": "available",
      "description": "人工客服可检索对内和公开知识；不放宽外部客户的公开内容边界。",
      "scopes": [
        "service"
      ],
      "request": "?q=%E9%80%80%E6%AC%BE&page=1",
      "response": "{\n  \"articles\": [],\n  \"total\": 0\n}",
      "requestFields": [
        {
          "name": "q",
          "type": "string",
          "description": "关键词，最多 80 字符。",
          "required": false
        },
        {
          "name": "libraryId",
          "type": "string",
          "description": "帮助中心 ID，最多 100 字符。",
          "required": false
        },
        {
          "name": "visibility",
          "type": "internal | public",
          "description": "限定内外部可见性；省略表示全部授权知识。",
          "required": false
        },
        {
          "name": "favorites",
          "type": "0 | 1",
          "description": "本人收藏筛选。",
          "required": false
        },
        {
          "name": "scope",
          "type": "all | enterprise | personal",
          "description": "全部、企业或本人资料，仍受当前登录主体权限限制。",
          "required": false
        },
        {
          "name": "content",
          "type": "all | documents",
          "description": "默认全部；documents 仅保留正文中实际引用可访问文件附件的资料，筛选在分页前完成。",
          "required": false
        },
        {
          "name": "category",
          "type": "string",
          "description": "精确分类，最多 40 字符；省略表示全部，空值表示未分类；个人资料暂未分类。",
          "required": false
        },
        {
          "name": "sort",
          "type": "updated | title",
          "description": "默认按最近更新，或按标题排序；并列值按更新时间和条目 ID 稳定排序。",
          "required": false
        },
        {
          "name": "page",
          "type": "integer",
          "description": "1 至 10000。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "articles / total",
          "type": "array / integer",
          "description": "有效且已发布的授权知识搜索结果。",
          "required": false
        },
        {
          "name": "categories",
          "type": "array",
          "description": "当前权限、资料范围、关键词、收藏及文件筛选下的分类计数，不受当前分类和分页影响。",
          "required": false
        }
      ],
      "notes": [
        "人工客服可检索对内和公开知识；不放宽外部客户的公开内容边界。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "phone-calls.read",
      "group": "电话外呼",
      "name": "读取电话呼入呼出",
      "method": "GET",
      "currentPath": "/v1/operations/phone-calls.read?view=calls&page=1&pageSize=100&compact=1&qMode=metadata",
      "publicPath": "/v1/operations/phone-calls.read",
      "status": "available",
      "description": "返回当前企业电话记录；不能将分页列表、unknown 结果或空转写当作呼叫完成凭据。",
      "scopes": [
        "service"
      ],
      "request": "?view=calls&page=1&pageSize=100&compact=1&qMode=metadata",
      "response": "{\n  \"calls\": [],\n  \"total\": 0,\n  \"page\": 1,\n  \"pageSize\": 100,\n  \"metrics\": {\n    \"total\": 0,\n    \"answered\": 0,\n    \"active\": 0,\n    \"unknown\": 0,\n    \"failed\": 0,\n    \"averageDuration\": 0,\n    \"answerRate\": null\n  },\n  \"canCall\": true,\n  \"canOutbound\": true,\n  \"canInbound\": false,\n  \"canTelephone\": true\n}",
      "requestFields": [
        {
          "name": "view",
          "type": "calls",
          "description": "电话列表模式；开放操作 phone-calls.read 固定此值。",
          "required": true
        },
        {
          "name": "page / pageSize",
          "type": "integer / 20|50|100",
          "description": "page 为 1–10000，默认 1；pageSize 默认 20，实际返回 page 可能钳制到最后一页。",
          "required": false
        },
        {
          "name": "compact",
          "type": "1",
          "description": "移除列表转写正文，messages 返回空数组；完整转写用详情或批量导出。",
          "required": false
        },
        {
          "name": "direction",
          "type": "inbound | outbound",
          "description": "省略表示两个方向。",
          "required": false
        },
        {
          "name": "status",
          "type": "queued | ringing | active | completed | failed | no_answer | canceled | unknown | live | finished",
          "description": "live 包含 queued/ringing/active，finished 包含四个终态；unknown 不属于失败或终态。",
          "required": false
        },
        {
          "name": "scope",
          "type": "all | service | test",
          "description": "默认 all；此电话记录接口不返回语音演练记录，test 当前为空。",
          "required": false
        },
        {
          "name": "lineId / batchId / planId",
          "type": "string",
          "description": "按真实资源编号筛选，各最多 100 字符。",
          "required": false
        },
        {
          "name": "q / qMode",
          "type": "string / metadata|all",
          "description": "q 最多 100 字符；qMode 默认 all，包含转写正文；建议列表显式 metadata。",
          "required": false
        },
        {
          "name": "start / end",
          "type": "Unix 毫秒",
          "description": "按创建时间筛选，start 包含、end 不包含；两者均传时 end 必须大于 start。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "calls",
          "type": "PhoneCall[]",
          "description": "当前页真实电话记录；compact=1 时 messages 为空。",
          "required": true
        },
        {
          "name": "total / page / pageSize",
          "type": "integer",
          "description": "总量和实际分页；按实际 page 与 total 判断结束。",
          "required": true
        },
        {
          "name": "metrics",
          "type": "PhoneMetrics",
          "description": "整个筛选范围的接听与时长统计；不是当前页统计或业务成功率。",
          "required": true
        }
      ],
      "notes": [
        "返回当前企业电话记录；不能将分页列表、unknown 结果或空转写当作呼叫完成凭据。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "phone-calls.dial",
      "group": "电话外呼",
      "name": "电话呼入呼出 · 拨号",
      "method": "POST",
      "currentPath": "/v1/operations/phone-calls.dial",
      "publicPath": "/v1/operations/phone-calls.dial",
      "status": "available",
      "description": "号码必须在用户授权范围内，线路及启用渠道需可外呼并通过并发、黑名单、服务权益和媒体就绪检查；调用会产生真实电话并可能计费。",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"dial\",\"requestId\":\"44444444-4444-4444-8444-444444444444\",\"channelId\":\"22222222-2222-4222-8222-222222222222\",\"to\":\"+8613800138000\",\"confirmed\":true}",
      "response": "{\n  \"call\": {\n    \"id\": \"33333333-3333-4333-8333-333333333333\",\n    \"status\": \"queued\"\n  },\n  \"notice\": \"\"\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "dial",
          "description": "可省略，系统固定为 dial；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "requestId",
          "type": "UUID 字符串",
          "description": "本次业务请求 ID，36 位；重试必须保留同一 ID、渠道和号码，与开放网关 Idempotency-Key 独立。",
          "required": true
        },
        {
          "name": "channelId",
          "type": "string",
          "description": "真实、已启用电话渠道 ID；其线路须可呼出、已同步注册或免注册就绪。不是 lineId。",
          "required": true
        },
        {
          "name": "to",
          "type": "E.164 string",
          "description": "已确认的真实被叫号码，含 + 国家区号；号码不能作为数值。",
          "required": true
        },
        {
          "name": "confirmed",
          "type": "true",
          "description": "用户已授权本次号码与线路的真实呼叫。",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "call",
          "type": "PhoneCall",
          "description": "当前真实通话记录；queued/unknown 不代表已接通。",
          "required": true
        },
        {
          "name": "notice",
          "type": "string?",
          "description": "网关拒绝或结果待确认时的提示；幂等回执可能省略。",
          "required": false
        },
        {
          "name": "duplicate",
          "type": "true?",
          "description": "同一业务 requestId 返回原记录，没有再次拨号。",
          "required": false
        }
      ],
      "notes": [
        "号码必须在用户授权范围内，线路及启用渠道需可外呼并通过并发、黑名单、服务权益和媒体就绪检查；调用会产生真实电话并可能计费。",
        "结果为 unknown 或网络超时时停止新拨号，先用原 call.id 查询详情；重放保留 requestId、正文和开放网关幂等键，不能用新 ID 将未知请求当作失败重拨。",
        "本接口依赖已绑定渠道的发布方案；小电话的 lineId/agentId 快速测试属于另一协议，不能混用。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "phone-calls.hangup",
      "group": "电话外呼",
      "name": "电话呼入呼出 · 挂断",
      "method": "POST",
      "currentPath": "/v1/operations/phone-calls.hangup",
      "publicPath": "/v1/operations/phone-calls.hangup",
      "status": "available",
      "description": "网关未明确接受时返回 503；读取原通话状态核实，不将请求已接受视为最终挂断、时长或并发已释放。",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"hangup\",\"id\":\"33333333-3333-4333-8333-333333333333\"}",
      "response": "{\n  \"requested\": true\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "hangup",
          "description": "可省略，系统固定为 hangup；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "id",
          "type": "string",
          "description": "同企业真实电话 call.id，最多 100 字符；不是线路、渠道或语音演练 ID。",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "requested",
          "type": "true?",
          "description": "网关已接受挂断请求；仍需读取通话详情核实最终终态。",
          "required": false
        },
        {
          "name": "ended",
          "type": "true?",
          "description": "记录已处于 completed/failed/no_answer/canceled，无需再次发送挂断。",
          "required": false
        }
      ],
      "notes": [
        "网关未明确接受时返回 503；读取原通话状态核实，不将请求已接受视为最终挂断、时长或并发已释放。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "phone-detail.read",
      "group": "电话外呼",
      "name": "读取电话详情",
      "method": "GET",
      "currentPath": "/v1/operations/phone-detail.read?view=call&id=33333333-3333-4333-8333-333333333333",
      "publicPath": "/v1/operations/phone-detail.read",
      "status": "available",
      "description": "call.summary 可能尚未上报或为空；缺失转写或总结时明确报告缺失，不能猜测通话结论。",
      "scopes": [
        "service"
      ],
      "request": "?view=call&id=33333333-3333-4333-8333-333333333333",
      "response": "{\n  \"call\": {\n    \"id\": \"33333333-3333-4333-8333-333333333333\",\n    \"status\": \"completed\",\n    \"summary\": \"\",\n    \"messages\": []\n  },\n  \"previous\": null,\n  \"next\": null,\n  \"canCall\": true,\n  \"canOutbound\": true,\n  \"canInbound\": false,\n  \"canTelephone\": true\n}",
      "requestFields": [
        {
          "name": "view",
          "type": "call",
          "description": "详情模式；开放操作 phone-detail.read 固定此值。",
          "required": true
        },
        {
          "name": "id",
          "type": "string",
          "description": "真实电话记录 ID，非 voiceSessionId，最多 100 字符。",
          "required": true
        },
        {
          "name": "direction / status / scope / lineId / batchId / planId / q / qMode / start / end",
          "type": "同电话列表筛选",
          "description": "可选，仅决定 previous/next；按 id 读取的详情独立于列表页和筛选范围。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "call",
          "type": "PhoneCall",
          "description": "完整电话记录，包含真实 summary、messages、结束原因和媒体回执（存在时）。",
          "required": true
        },
        {
          "name": "previous / next",
          "type": "string | null",
          "description": "当前筛选条件下相邻记录 ID；无记录时 null。",
          "required": true
        }
      ],
      "notes": [
        "call.summary 可能尚未上报或为空；缺失转写或总结时明确报告缺失，不能猜测通话结论。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "outbound-batches.read",
      "group": "电话外呼",
      "name": "读取批量外呼",
      "method": "GET",
      "currentPath": "/v1/operations/outbound-batches.read?page=1",
      "publicPath": "/v1/operations/outbound-batches.read",
      "status": "available",
      "description": "已实现：查询批次与号码进度，GET 不执行拨号。电话对话记录通过 /v1/operations/phone-calls.read?direction=outbound&batchId=... 筛选。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "?page=1",
      "response": "{\n  \"batches\": [],\n  \"total\": 0,\n  \"page\": 1,\n  \"pageSize\": 20\n}",
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "description": "批次详情编号；省略读取列表。",
          "required": false
        },
        {
          "name": "page",
          "type": "integer",
          "description": "从 1 开始；列表每页 20，号码每页 50。",
          "required": false
        },
        {
          "name": "status",
          "type": "string",
          "description": "草稿、预约、运行、暂停、完成、取消对应的英文状态。",
          "required": false
        },
        {
          "name": "view",
          "type": "string",
          "description": "import 查询号码导入进度；resources 查询线路和发布计划；templates 查询配置模板。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "batches / batch",
          "type": "array / object",
          "description": "批次元数据，不返回后台授权凭据。",
          "required": false
        },
        {
          "name": "metrics",
          "type": "object",
          "description": "sent/answered/active/failed/unknown 等真实计数，不把已接听当作业务成功。",
          "required": false
        },
        {
          "name": "recipients",
          "type": "array",
          "description": "详情页的号码、状态和 callId。",
          "required": false
        }
      ],
      "notes": [
        "已实现：查询批次与号码进度，GET 不执行拨号。电话对话记录通过 /v1/operations/phone-calls.read?direction=outbound&batchId=... 筛选。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "outbound-batches.save",
      "group": "电话外呼",
      "name": "批量外呼 · 保存",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.save",
      "publicPath": "/v1/operations/outbound-batches.save",
      "status": "available",
      "description": "已实现：原子队列占位和线路并发保护。离页执行依赖 Worker scheduled 及已部署电话媒体网关，初次启动和终态事件也会推进。未知回执不自动重拨。暂停/取消不挂断已发起电话。API 密钥撤销会阻止后续调度。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"save\",\"requestId\":\"batch_example_request_1\",\"name\":\"预约提醒\",\"lineId\":\"line_uuid\",\"agentId\":\"default\",\"version\":1,\"concurrency\":1,\"reserved\":1,\"recipients\":[{\"phone\":\"+8613800138000\",\"name\":\"示例\"}]}",
      "response": "{\n  \"batch\": {\n    \"id\": \"batch_uuid\",\n    \"status\": \"draft\",\n    \"revision\": 1\n  }\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "string",
          "description": "可省略，系统固定为 save；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "id / revision",
          "type": "string / integer",
          "description": "控制已存批次需最新编号和修订号。",
          "required": false
        },
        {
          "name": "requestId",
          "type": "string",
          "description": "save/retry 的稳定去重标识，16–100 位字母数字横线下划线。",
          "required": false
        },
        {
          "name": "lineId / agentId / version",
          "type": "string / integer",
          "description": "save 必填；固定已发布智能体版本，不修改线路原呼入绑定。",
          "required": false
        },
        {
          "name": "recipients",
          "type": "array",
          "description": "最多 200000 条 {phone,name}，同时受 900000 码元正文限制；大名单使用 importId。号码归一化去重，错误拒绝整批保存。",
          "required": false
        },
        {
          "name": "importId",
          "type": "string",
          "description": "完成校验且 status=ready 的本人导入任务 ID；提供时替代 recipients，完成保存后不可重复绑定批次。",
          "required": false
        },
        {
          "name": "concurrency / reserved",
          "type": "integer",
          "description": "批次并发和为其他通话预留的线路并发，两者之和不超过线路上限。",
          "required": false
        },
        {
          "name": "scheduledAt / windowStart / windowEnd",
          "type": "integer",
          "description": "预约 Unix 毫秒；每日北京时间分钟数，默认 09:00–18:00。",
          "required": false
        },
        {
          "name": "confirmed",
          "type": "boolean",
          "description": "start/resume 必须 true，确认名单授权和真实费用。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "batch",
          "type": "object",
          "description": "已保存批次。创建和重试都是草稿，不代表已拨号。",
          "required": false
        }
      ],
      "notes": [
        "已实现：原子队列占位和线路并发保护。离页执行依赖 Worker scheduled 及已部署电话媒体网关，初次启动和终态事件也会推进。未知回执不自动重拨。暂停/取消不挂断已发起电话。API 密钥撤销会阻止后续调度。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "outbound-batches.start",
      "group": "电话外呼",
      "name": "批量外呼 · 启动批次",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.start",
      "publicPath": "/v1/operations/outbound-batches.start",
      "status": "available",
      "description": "把草稿批次送入拨号队列：通过线路、智能体、时段与网关检查后，批次变为 running（有未到的预约时间则为 scheduled），由后台调度异步拨号。不会修改名单或批次配置，响应不代表号码已拨出。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"start\",\"id\":\"YOUR_BATCH_ID\",\"revision\":1,\"confirmed\":true}",
      "response": "{\"batch\":{\"id\":\"YOUR_BATCH_ID\",\"revision\":2,\"name\":\"预约提醒\",\"status\":\"running\",\"lineId\":\"YOUR_LINE_ID\",\"orderMode\":\"sequential\",\"lineRevision\":1,\"plan\":{\"type\":\"agent\",\"id\":\"YOUR_AGENT_ID\",\"version\":1,\"name\":\"预约提醒智能体\"},\"concurrency\":1,\"reserved\":0,\"scheduledAt\":0,\"schedule\":{\"enabled\":true,\"timezone\":\"Asia/Shanghai\",\"validFrom\":\"\",\"validUntil\":\"\",\"slots\":[{\"day\":1,\"start\":\"09:00\",\"end\":\"18:00\"}]},\"windowStart\":540,\"windowEnd\":1080,\"total\":1,\"notice\":\"\",\"created\":1767225600000}}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "批次 ID，最长 100 字符。取自 outbound-batches.save 响应的 batch.id，或 outbound-batches.read 列表的 batches[].id。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等。调用前用 outbound-batches.read 读取（列表 batches[].revision，或 ?id=批次ID 详情的 batch.revision）；后台调度自动暂停或完成批次时也会使它递增。"
        },
        {
          "name": "confirmed",
          "type": "boolean",
          "required": true,
          "description": "必须为 true，表示调用方确认名单已获得呼叫授权并接受真实通话费用；省略或为其他值返回 400。"
        }
      ],
      "responseFields": [
        {
          "name": "batch",
          "type": "object",
          "required": true,
          "description": "操作后的批次，字段与 outbound-batches.read 详情（?id=批次ID）的 batch 相同。"
        },
        {
          "name": "batch.id",
          "type": "string",
          "required": true,
          "description": "被操作的批次 ID，与请求的 id 相同。"
        },
        {
          "name": "batch.revision",
          "type": "integer",
          "required": true,
          "description": "操作成功后的新 revision（请求值加 1）；下一次控制操作使用此值。"
        },
        {
          "name": "batch.status",
          "type": "string",
          "required": true,
          "description": "scheduled（批次的 scheduledAt 晚于当前时间）或 running（立即进入拨号队列）。"
        },
        {
          "name": "batch.name",
          "type": "string",
          "required": true,
          "description": "批次名称。"
        },
        {
          "name": "batch.notice",
          "type": "string",
          "required": true,
          "description": "批次提示。人工控制成功后为空字符串；后台调度自动暂停批次时写入原因（如线路掉线、执行时间已截止、授权已变化）。"
        },
        {
          "name": "batch.total",
          "type": "integer",
          "required": true,
          "description": "批次号码总数。"
        },
        {
          "name": "batch.lineId",
          "type": "string",
          "required": true,
          "description": "批次使用的电话线路 ID。"
        },
        {
          "name": "batch.lineRevision",
          "type": "integer",
          "required": true,
          "description": "创建批次时固定的线路 revision；线路之后被修改会导致启动返回 422。"
        },
        {
          "name": "batch.plan",
          "type": "object",
          "required": true,
          "description": "批次固定的智能体发布版本：type（固定 agent）、id、version、name。"
        },
        {
          "name": "batch.concurrency",
          "type": "integer",
          "required": true,
          "description": "批次同时进行的最大通话数。"
        },
        {
          "name": "batch.reserved",
          "type": "integer",
          "required": true,
          "description": "为线路上其他通话预留的并发数。"
        },
        {
          "name": "batch.orderMode",
          "type": "string",
          "required": true,
          "description": "号码拨打顺序：sequential（按名单顺序）或 random（随机）。"
        },
        {
          "name": "batch.scheduledAt",
          "type": "integer",
          "required": true,
          "description": "预约开始时间（Unix 毫秒）；0 表示不预约。"
        },
        {
          "name": "batch.schedule",
          "type": "object",
          "required": true,
          "description": "允许拨号的时段配置：enabled、timezone、validFrom、validUntil、slots（每周时段），可能含 exceptions（日期例外）。"
        },
        {
          "name": "batch.windowStart",
          "type": "integer",
          "required": true,
          "description": "每日拨号开始时刻，以当天第几分钟表示（540 即 09:00）。"
        },
        {
          "name": "batch.windowEnd",
          "type": "integer",
          "required": true,
          "description": "每日拨号结束时刻，以当天第几分钟表示（1080 即 18:00）。"
        },
        {
          "name": "batch.created",
          "type": "integer",
          "required": true,
          "description": "批次创建时间（Unix 毫秒）。"
        }
      ],
      "notes": [
        "前置条件：批次状态必须是 draft 或 paused；scheduled、running、completed、canceled 返回 409“当前批次不能启动”。先用 outbound-batches.read 读取最新 revision，不一致返回 409“批次已变化，请刷新”；批次不存在返回 404。",
        "仅批次原提交账号可启动：API Key 所属企业管理员必须就是创建该批次的账号，且账号授权版本未变化，否则返回 403“仅原提交人且授权未变化时可以启动，请重新创建批次”。",
        "准入检查任一不满足即拒绝且不会拨号：企业未开通外呼或语音应用、或企业登录策略强制要求近期 MFA 时返回 403；拨号时段配置无效或已过截止时间返回 409；线路不存在或已删除返回 404；线路 revision 已变化、已停用、未允许呼出、未注册就绪，或“并发 + 预留”超过线路并发上限返回 422；智能体发布版本不可用或未开启语音返回 422 或 409；电话网关未部署、不可达或未就绪返回 503；企业数据任务并发已满返回 429。",
        "当前不在允许拨号的时段（时段未开放或未到生效时间）不会被拒绝：批次照常进入 running 或 scheduled，由后台调度在时段开放后拨号。",
        "启动与恢复不校验语音分钟或账户余额；计费准入在每通电话接入语音媒体时进行，启动成功不代表额度充足。",
        "异步生效：响应只表示批次已进入拨号队列，不代表号码已拨出或接通。请求返回后服务端尽力立即触发一轮调度，其余由后台定时调度按批次并发分页拨号；用 outbound-batches.read?id=批次ID 查看 metrics 与各号码状态。",
        "后台调度遇到线路掉线、执行时间截止、线路或授权变化时，会自动把批次改为 paused、写入 batch.notice 并递增 revision；排除原因后调用 outbound-batches.resume 继续。",
        "API Key 调用会把该密钥记为批次的拨号授权：密钥被撤销、轮换、到期或不再包含本操作后，后台调度停止拨号并自动暂停批次，需用有效密钥重新启动。",
        "start 与 resume 的服务端校验完全相同，二者都接受 draft 与 paused 状态的批次。",
        "成功后产生 outbound.batch.changed 回调事件（data.sourceId 为批次 ID，data.revision 为新 revision）。",
        "会产生真实通话费用。网关按 Idempotency-Key 缓存并重放原响应（包括 4xx）；结果未知时先读取批次状态，不要更换 Key 重复启动；修正条件后重新调用需使用新的 Idempotency-Key。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "outbound-batches.pause",
      "group": "电话外呼",
      "name": "批量外呼 · 暂停批次",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.pause",
      "publicPath": "/v1/operations/outbound-batches.pause",
      "status": "available",
      "description": "暂停运行中或已预约的批次：批次变为 paused，后台调度不再为它发起新呼叫，未拨号码保留待拨。不会挂断已发起或正在通话的电话。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"pause\",\"id\":\"YOUR_BATCH_ID\",\"revision\":2}",
      "response": "{\"batch\":{\"id\":\"YOUR_BATCH_ID\",\"revision\":3,\"name\":\"预约提醒\",\"status\":\"paused\",\"lineId\":\"YOUR_LINE_ID\",\"orderMode\":\"sequential\",\"lineRevision\":1,\"plan\":{\"type\":\"agent\",\"id\":\"YOUR_AGENT_ID\",\"version\":1,\"name\":\"预约提醒智能体\"},\"concurrency\":1,\"reserved\":0,\"scheduledAt\":0,\"schedule\":{\"enabled\":true,\"timezone\":\"Asia/Shanghai\",\"validFrom\":\"\",\"validUntil\":\"\",\"slots\":[{\"day\":1,\"start\":\"09:00\",\"end\":\"18:00\"}]},\"windowStart\":540,\"windowEnd\":1080,\"total\":1,\"notice\":\"\",\"created\":1767225600000}}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "批次 ID，最长 100 字符。取自 outbound-batches.save 响应的 batch.id，或 outbound-batches.read 列表的 batches[].id。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等。调用前用 outbound-batches.read 读取（列表 batches[].revision，或 ?id=批次ID 详情的 batch.revision）；后台调度自动暂停或完成批次时也会使它递增。"
        }
      ],
      "responseFields": [
        {
          "name": "batch",
          "type": "object",
          "required": true,
          "description": "操作后的批次，字段与 outbound-batches.read 详情（?id=批次ID）的 batch 相同。"
        },
        {
          "name": "batch.id",
          "type": "string",
          "required": true,
          "description": "被操作的批次 ID，与请求的 id 相同。"
        },
        {
          "name": "batch.revision",
          "type": "integer",
          "required": true,
          "description": "操作成功后的新 revision（请求值加 1）；下一次控制操作使用此值。"
        },
        {
          "name": "batch.status",
          "type": "string",
          "required": true,
          "description": "固定为 paused。"
        },
        {
          "name": "batch.name",
          "type": "string",
          "required": true,
          "description": "批次名称。"
        },
        {
          "name": "batch.notice",
          "type": "string",
          "required": true,
          "description": "批次提示。人工控制成功后为空字符串；后台调度自动暂停批次时写入原因（如线路掉线、执行时间已截止、授权已变化）。"
        },
        {
          "name": "batch.total",
          "type": "integer",
          "required": true,
          "description": "批次号码总数。"
        },
        {
          "name": "batch.lineId",
          "type": "string",
          "required": true,
          "description": "批次使用的电话线路 ID。"
        },
        {
          "name": "batch.lineRevision",
          "type": "integer",
          "required": true,
          "description": "创建批次时固定的线路 revision；线路之后被修改会导致启动返回 422。"
        },
        {
          "name": "batch.plan",
          "type": "object",
          "required": true,
          "description": "批次固定的智能体发布版本：type（固定 agent）、id、version、name。"
        },
        {
          "name": "batch.concurrency",
          "type": "integer",
          "required": true,
          "description": "批次同时进行的最大通话数。"
        },
        {
          "name": "batch.reserved",
          "type": "integer",
          "required": true,
          "description": "为线路上其他通话预留的并发数。"
        },
        {
          "name": "batch.orderMode",
          "type": "string",
          "required": true,
          "description": "号码拨打顺序：sequential（按名单顺序）或 random（随机）。"
        },
        {
          "name": "batch.scheduledAt",
          "type": "integer",
          "required": true,
          "description": "预约开始时间（Unix 毫秒）；0 表示不预约。"
        },
        {
          "name": "batch.schedule",
          "type": "object",
          "required": true,
          "description": "允许拨号的时段配置：enabled、timezone、validFrom、validUntil、slots（每周时段），可能含 exceptions（日期例外）。"
        },
        {
          "name": "batch.windowStart",
          "type": "integer",
          "required": true,
          "description": "每日拨号开始时刻，以当天第几分钟表示（540 即 09:00）。"
        },
        {
          "name": "batch.windowEnd",
          "type": "integer",
          "required": true,
          "description": "每日拨号结束时刻，以当天第几分钟表示（1080 即 18:00）。"
        },
        {
          "name": "batch.created",
          "type": "integer",
          "required": true,
          "description": "批次创建时间（Unix 毫秒）。"
        }
      ],
      "notes": [
        "前置条件：批次状态必须是 scheduled 或 running；draft、paused、completed、canceled 返回 409“当前批次不能执行此操作”。先用 outbound-batches.read 读取最新 revision，不一致返回 409“批次已变化，请刷新”；批次不存在返回 404。",
        "立即生效：暂停后不再发起新呼叫；暂停瞬间已提交给电话网关的呼叫仍会继续，其结果照常记录。",
        "继续拨号调用 outbound-batches.resume，需重新传 confirmed: true 并再次通过全部准入检查。",
        "不要求外呼服务处于开通状态，也不占用企业数据任务并发额度：外呼被关闭或导入拥塞时仍可执行。不限原提交人，具备权限的本企业管理员 API Key 均可调用。",
        "成功后产生 outbound.batch.changed 回调事件（data.sourceId 为批次 ID，data.revision 为新 revision）。",
        "并发修改导致提交失败时返回 409“批次或权限已变化”；重新读取 revision 后使用新的 Idempotency-Key 再调用。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "outbound-batches.resume",
      "group": "电话外呼",
      "name": "批量外呼 · 继续批次",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.resume",
      "publicPath": "/v1/operations/outbound-batches.resume",
      "status": "available",
      "description": "让已暂停的批次重新进入拨号队列：重新通过线路、智能体、时段与网关检查后，批次变为 running（有未到的预约时间则为 scheduled），后台调度从未拨号码继续。不会重拨已有结果的号码，响应不代表号码已拨出。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"resume\",\"id\":\"YOUR_BATCH_ID\",\"revision\":3,\"confirmed\":true}",
      "response": "{\"batch\":{\"id\":\"YOUR_BATCH_ID\",\"revision\":4,\"name\":\"预约提醒\",\"status\":\"running\",\"lineId\":\"YOUR_LINE_ID\",\"orderMode\":\"sequential\",\"lineRevision\":1,\"plan\":{\"type\":\"agent\",\"id\":\"YOUR_AGENT_ID\",\"version\":1,\"name\":\"预约提醒智能体\"},\"concurrency\":1,\"reserved\":0,\"scheduledAt\":0,\"schedule\":{\"enabled\":true,\"timezone\":\"Asia/Shanghai\",\"validFrom\":\"\",\"validUntil\":\"\",\"slots\":[{\"day\":1,\"start\":\"09:00\",\"end\":\"18:00\"}]},\"windowStart\":540,\"windowEnd\":1080,\"total\":1,\"notice\":\"\",\"created\":1767225600000}}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "批次 ID，最长 100 字符。取自 outbound-batches.save 响应的 batch.id，或 outbound-batches.read 列表的 batches[].id。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等。调用前用 outbound-batches.read 读取（列表 batches[].revision，或 ?id=批次ID 详情的 batch.revision）；后台调度自动暂停或完成批次时也会使它递增。"
        },
        {
          "name": "confirmed",
          "type": "boolean",
          "required": true,
          "description": "必须为 true，表示调用方确认名单已获得呼叫授权并接受真实通话费用；省略或为其他值返回 400。"
        }
      ],
      "responseFields": [
        {
          "name": "batch",
          "type": "object",
          "required": true,
          "description": "操作后的批次，字段与 outbound-batches.read 详情（?id=批次ID）的 batch 相同。"
        },
        {
          "name": "batch.id",
          "type": "string",
          "required": true,
          "description": "被操作的批次 ID，与请求的 id 相同。"
        },
        {
          "name": "batch.revision",
          "type": "integer",
          "required": true,
          "description": "操作成功后的新 revision（请求值加 1）；下一次控制操作使用此值。"
        },
        {
          "name": "batch.status",
          "type": "string",
          "required": true,
          "description": "scheduled（批次的 scheduledAt 晚于当前时间）或 running（立即进入拨号队列）。"
        },
        {
          "name": "batch.name",
          "type": "string",
          "required": true,
          "description": "批次名称。"
        },
        {
          "name": "batch.notice",
          "type": "string",
          "required": true,
          "description": "批次提示。人工控制成功后为空字符串；后台调度自动暂停批次时写入原因（如线路掉线、执行时间已截止、授权已变化）。"
        },
        {
          "name": "batch.total",
          "type": "integer",
          "required": true,
          "description": "批次号码总数。"
        },
        {
          "name": "batch.lineId",
          "type": "string",
          "required": true,
          "description": "批次使用的电话线路 ID。"
        },
        {
          "name": "batch.lineRevision",
          "type": "integer",
          "required": true,
          "description": "创建批次时固定的线路 revision；线路之后被修改会导致启动返回 422。"
        },
        {
          "name": "batch.plan",
          "type": "object",
          "required": true,
          "description": "批次固定的智能体发布版本：type（固定 agent）、id、version、name。"
        },
        {
          "name": "batch.concurrency",
          "type": "integer",
          "required": true,
          "description": "批次同时进行的最大通话数。"
        },
        {
          "name": "batch.reserved",
          "type": "integer",
          "required": true,
          "description": "为线路上其他通话预留的并发数。"
        },
        {
          "name": "batch.orderMode",
          "type": "string",
          "required": true,
          "description": "号码拨打顺序：sequential（按名单顺序）或 random（随机）。"
        },
        {
          "name": "batch.scheduledAt",
          "type": "integer",
          "required": true,
          "description": "预约开始时间（Unix 毫秒）；0 表示不预约。"
        },
        {
          "name": "batch.schedule",
          "type": "object",
          "required": true,
          "description": "允许拨号的时段配置：enabled、timezone、validFrom、validUntil、slots（每周时段），可能含 exceptions（日期例外）。"
        },
        {
          "name": "batch.windowStart",
          "type": "integer",
          "required": true,
          "description": "每日拨号开始时刻，以当天第几分钟表示（540 即 09:00）。"
        },
        {
          "name": "batch.windowEnd",
          "type": "integer",
          "required": true,
          "description": "每日拨号结束时刻，以当天第几分钟表示（1080 即 18:00）。"
        },
        {
          "name": "batch.created",
          "type": "integer",
          "required": true,
          "description": "批次创建时间（Unix 毫秒）。"
        }
      ],
      "notes": [
        "前置条件：批次状态必须是 paused（draft 也被接受）；scheduled、running、completed、canceled 返回 409“当前批次不能启动”。批次被后台自动暂停后 revision 已递增，先用 outbound-batches.read 读取最新 revision 与 batch.notice，revision 不一致返回 409“批次已变化，请刷新”。",
        "只继续状态仍为待拨的号码；已提交、已完成、失败、未接听或结果未知的号码不会重拨。重拨失败与未接听号码请用 outbound-batches.retry。",
        "因拨号时段已过截止时间而自动暂停的批次无法恢复（返回 409“时间配置无效或已截止，请重新创建批次”）；线路配置在批次创建后被修改（线路 revision 变化）的批次同样无法恢复（返回 422）；这两种情况需用 outbound-batches.save 新建批次。线路仅掉线后重新注册就绪的，可以恢复。",
        "仅批次原提交账号可启动：API Key 所属企业管理员必须就是创建该批次的账号，且账号授权版本未变化，否则返回 403“仅原提交人且授权未变化时可以启动，请重新创建批次”。",
        "准入检查任一不满足即拒绝且不会拨号：企业未开通外呼或语音应用、或企业登录策略强制要求近期 MFA 时返回 403；拨号时段配置无效或已过截止时间返回 409；线路不存在或已删除返回 404；线路 revision 已变化、已停用、未允许呼出、未注册就绪，或“并发 + 预留”超过线路并发上限返回 422；智能体发布版本不可用或未开启语音返回 422 或 409；电话网关未部署、不可达或未就绪返回 503；企业数据任务并发已满返回 429。",
        "当前不在允许拨号的时段（时段未开放或未到生效时间）不会被拒绝：批次照常进入 running 或 scheduled，由后台调度在时段开放后拨号。",
        "启动与恢复不校验语音分钟或账户余额；计费准入在每通电话接入语音媒体时进行，启动成功不代表额度充足。",
        "异步生效：响应只表示批次已进入拨号队列，不代表号码已拨出或接通。请求返回后服务端尽力立即触发一轮调度，其余由后台定时调度按批次并发分页拨号；用 outbound-batches.read?id=批次ID 查看 metrics 与各号码状态。",
        "后台调度遇到线路掉线、执行时间截止、线路或授权变化时，会自动把批次改为 paused、写入 batch.notice 并递增 revision；排除原因后调用 outbound-batches.resume 继续。",
        "API Key 调用会把该密钥记为批次的拨号授权：密钥被撤销、轮换、到期或不再包含本操作后，后台调度停止拨号并自动暂停批次，需用有效密钥重新启动。",
        "start 与 resume 的服务端校验完全相同，二者都接受 draft 与 paused 状态的批次。",
        "成功后产生 outbound.batch.changed 回调事件（data.sourceId 为批次 ID，data.revision 为新 revision）。",
        "会产生真实通话费用。网关按 Idempotency-Key 缓存并重放原响应（包括 4xx）；结果未知时先读取批次状态，不要更换 Key 重复启动；修正条件后重新调用需使用新的 Idempotency-Key。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "outbound-batches.cancel",
      "group": "电话外呼",
      "name": "批量外呼 · 取消批次",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.cancel",
      "publicPath": "/v1/operations/outbound-batches.cancel",
      "status": "available",
      "description": "永久终止批次：批次变为 canceled，所有尚未拨出的号码标记为已取消，之后不能再启动或恢复。不会挂断已发起或正在通话的电话，也不会删除批次与通话记录。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"cancel\",\"id\":\"YOUR_BATCH_ID\",\"revision\":2}",
      "response": "{\"batch\":{\"id\":\"YOUR_BATCH_ID\",\"revision\":3,\"name\":\"预约提醒\",\"status\":\"canceled\",\"lineId\":\"YOUR_LINE_ID\",\"orderMode\":\"sequential\",\"lineRevision\":1,\"plan\":{\"type\":\"agent\",\"id\":\"YOUR_AGENT_ID\",\"version\":1,\"name\":\"预约提醒智能体\"},\"concurrency\":1,\"reserved\":0,\"scheduledAt\":0,\"schedule\":{\"enabled\":true,\"timezone\":\"Asia/Shanghai\",\"validFrom\":\"\",\"validUntil\":\"\",\"slots\":[{\"day\":1,\"start\":\"09:00\",\"end\":\"18:00\"}]},\"windowStart\":540,\"windowEnd\":1080,\"total\":1,\"notice\":\"\",\"created\":1767225600000}}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "批次 ID，最长 100 字符。取自 outbound-batches.save 响应的 batch.id，或 outbound-batches.read 列表的 batches[].id。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等。调用前用 outbound-batches.read 读取（列表 batches[].revision，或 ?id=批次ID 详情的 batch.revision）；后台调度自动暂停或完成批次时也会使它递增。"
        }
      ],
      "responseFields": [
        {
          "name": "batch",
          "type": "object",
          "required": true,
          "description": "操作后的批次，字段与 outbound-batches.read 详情（?id=批次ID）的 batch 相同。"
        },
        {
          "name": "batch.id",
          "type": "string",
          "required": true,
          "description": "被操作的批次 ID，与请求的 id 相同。"
        },
        {
          "name": "batch.revision",
          "type": "integer",
          "required": true,
          "description": "操作成功后的新 revision（请求值加 1）；下一次控制操作使用此值。"
        },
        {
          "name": "batch.status",
          "type": "string",
          "required": true,
          "description": "固定为 canceled。"
        },
        {
          "name": "batch.name",
          "type": "string",
          "required": true,
          "description": "批次名称。"
        },
        {
          "name": "batch.notice",
          "type": "string",
          "required": true,
          "description": "批次提示。人工控制成功后为空字符串；后台调度自动暂停批次时写入原因（如线路掉线、执行时间已截止、授权已变化）。"
        },
        {
          "name": "batch.total",
          "type": "integer",
          "required": true,
          "description": "批次号码总数。"
        },
        {
          "name": "batch.lineId",
          "type": "string",
          "required": true,
          "description": "批次使用的电话线路 ID。"
        },
        {
          "name": "batch.lineRevision",
          "type": "integer",
          "required": true,
          "description": "创建批次时固定的线路 revision；线路之后被修改会导致启动返回 422。"
        },
        {
          "name": "batch.plan",
          "type": "object",
          "required": true,
          "description": "批次固定的智能体发布版本：type（固定 agent）、id、version、name。"
        },
        {
          "name": "batch.concurrency",
          "type": "integer",
          "required": true,
          "description": "批次同时进行的最大通话数。"
        },
        {
          "name": "batch.reserved",
          "type": "integer",
          "required": true,
          "description": "为线路上其他通话预留的并发数。"
        },
        {
          "name": "batch.orderMode",
          "type": "string",
          "required": true,
          "description": "号码拨打顺序：sequential（按名单顺序）或 random（随机）。"
        },
        {
          "name": "batch.scheduledAt",
          "type": "integer",
          "required": true,
          "description": "预约开始时间（Unix 毫秒）；0 表示不预约。"
        },
        {
          "name": "batch.schedule",
          "type": "object",
          "required": true,
          "description": "允许拨号的时段配置：enabled、timezone、validFrom、validUntil、slots（每周时段），可能含 exceptions（日期例外）。"
        },
        {
          "name": "batch.windowStart",
          "type": "integer",
          "required": true,
          "description": "每日拨号开始时刻，以当天第几分钟表示（540 即 09:00）。"
        },
        {
          "name": "batch.windowEnd",
          "type": "integer",
          "required": true,
          "description": "每日拨号结束时刻，以当天第几分钟表示（1080 即 18:00）。"
        },
        {
          "name": "batch.created",
          "type": "integer",
          "required": true,
          "description": "批次创建时间（Unix 毫秒）。"
        }
      ],
      "notes": [
        "前置条件：批次状态为 draft、scheduled、running 或 paused；completed、canceled 返回 409“当前批次不能执行此操作”。先用 outbound-batches.read 读取最新 revision，不一致返回 409“批次已变化，请刷新”；批次不存在返回 404。",
        "立即生效且不可恢复：已取消的批次调用 start 或 resume 返回 409。取消瞬间已提交给电话网关的呼叫仍会继续，其结果照常记录。",
        "取消后可用 outbound-batches.retry 为已确认失败或未接听的号码创建新批次；因取消而未拨出的号码不在重试范围内，需用 outbound-batches.save 重新提交。",
        "不要求外呼服务处于开通状态，也不占用企业数据任务并发额度：外呼被关闭或导入拥塞时仍可执行。不限原提交人，具备权限的本企业管理员 API Key 均可调用。",
        "成功后产生 outbound.batch.changed 回调事件（data.sourceId 为批次 ID，data.revision 为新 revision）。",
        "并发修改导致提交失败时返回 409“批次或权限已变化”；重新读取 revision 后使用新的 Idempotency-Key 再调用。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "outbound-batches.retry",
      "group": "电话外呼",
      "name": "批量外呼 · 为失败号码新建重试批次",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.retry",
      "publicPath": "/v1/operations/outbound-batches.retry",
      "status": "available",
      "description": "把源批次中已确认失败或未接听的号码复制成一个新的草稿批次，沿用源批次的线路、智能体版本、并发与拨号时段。不会修改源批次，也不会自动拨号；新批次需另行调用 outbound-batches.start。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"retry\",\"id\":\"YOUR_BATCH_ID\",\"revision\":5,\"requestId\":\"YOUR_STABLE_REQUEST_ID\"}",
      "response": "{\"batch\":{\"id\":\"YOUR_NEW_BATCH_ID\",\"revision\":1,\"name\":\"预约提醒 · 重试\",\"status\":\"draft\",\"lineId\":\"YOUR_LINE_ID\",\"orderMode\":\"sequential\",\"lineRevision\":1,\"plan\":{\"type\":\"agent\",\"id\":\"YOUR_AGENT_ID\",\"version\":1,\"name\":\"预约提醒智能体\"},\"concurrency\":1,\"reserved\":0,\"scheduledAt\":0,\"schedule\":{\"enabled\":true,\"timezone\":\"Asia/Shanghai\",\"validFrom\":\"\",\"validUntil\":\"\",\"slots\":[{\"day\":1,\"start\":\"09:00\",\"end\":\"18:00\"}]},\"windowStart\":540,\"windowEnd\":1080,\"total\":1,\"notice\":\"\",\"created\":1767225600000},\"duplicates\":0}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "源批次 ID，最长 100 字符。取自 outbound-batches.read 列表的 batches[].id。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "源批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等；用 outbound-batches.read 读取。"
        },
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "新批次的稳定业务去重标识，16–100 位字母、数字、下划线或连字符。同一 requestId 且待重试号码与配置未变时返回已创建的批次（duplicate: true）；内容不同返回 409。"
        }
      ],
      "responseFields": [
        {
          "name": "batch",
          "type": "object",
          "required": true,
          "description": "新建的重试批次（不是源批次），字段与 outbound-batches.read 详情的 batch 相同。"
        },
        {
          "name": "batch.id",
          "type": "string",
          "required": true,
          "description": "新批次 ID；启动与查询进度都使用此 ID。"
        },
        {
          "name": "batch.revision",
          "type": "integer",
          "required": true,
          "description": "新批次的 revision；首次创建时为 1。"
        },
        {
          "name": "batch.status",
          "type": "string",
          "required": true,
          "description": "首次创建时固定为 draft；同一 requestId 重复提交时返回该批次的当前状态。"
        },
        {
          "name": "batch.name",
          "type": "string",
          "required": true,
          "description": "批次名称。"
        },
        {
          "name": "batch.notice",
          "type": "string",
          "required": true,
          "description": "批次提示。人工控制成功后为空字符串；后台调度自动暂停批次时写入原因（如线路掉线、执行时间已截止、授权已变化）。"
        },
        {
          "name": "batch.total",
          "type": "integer",
          "required": true,
          "description": "批次号码总数。"
        },
        {
          "name": "batch.lineId",
          "type": "string",
          "required": true,
          "description": "批次使用的电话线路 ID。"
        },
        {
          "name": "batch.lineRevision",
          "type": "integer",
          "required": true,
          "description": "创建批次时固定的线路 revision；线路之后被修改会导致启动返回 422。"
        },
        {
          "name": "batch.plan",
          "type": "object",
          "required": true,
          "description": "批次固定的智能体发布版本：type（固定 agent）、id、version、name。"
        },
        {
          "name": "batch.concurrency",
          "type": "integer",
          "required": true,
          "description": "批次同时进行的最大通话数。"
        },
        {
          "name": "batch.reserved",
          "type": "integer",
          "required": true,
          "description": "为线路上其他通话预留的并发数。"
        },
        {
          "name": "batch.orderMode",
          "type": "string",
          "required": true,
          "description": "号码拨打顺序：sequential（按名单顺序）或 random（随机）。"
        },
        {
          "name": "batch.scheduledAt",
          "type": "integer",
          "required": true,
          "description": "预约开始时间（Unix 毫秒）；0 表示不预约。"
        },
        {
          "name": "batch.schedule",
          "type": "object",
          "required": true,
          "description": "允许拨号的时段配置：enabled、timezone、validFrom、validUntil、slots（每周时段），可能含 exceptions（日期例外）。"
        },
        {
          "name": "batch.windowStart",
          "type": "integer",
          "required": true,
          "description": "每日拨号开始时刻，以当天第几分钟表示（540 即 09:00）。"
        },
        {
          "name": "batch.windowEnd",
          "type": "integer",
          "required": true,
          "description": "每日拨号结束时刻，以当天第几分钟表示（1080 即 18:00）。"
        },
        {
          "name": "batch.created",
          "type": "integer",
          "required": true,
          "description": "批次创建时间（Unix 毫秒）。"
        },
        {
          "name": "duplicates",
          "type": "integer",
          "requiredWhen": "首次创建成功时",
          "description": "名单中被去重忽略的号码数。"
        },
        {
          "name": "duplicate",
          "type": "boolean",
          "requiredWhen": "同一 requestId 重复提交且内容一致时",
          "description": "固定为 true，表示返回的是此前已创建的批次，没有新建。"
        }
      ],
      "notes": [
        "前置条件：源批次状态必须是 paused、completed 或 canceled，且 revision 与当前值相等；运行中或已预约的批次需先调用 outbound-batches.pause。状态不符与 revision 不一致返回同一个 409“请先暂停或等待批次结束”，遇到时先重新读取批次。",
        "重试范围：只复制最近一次呼叫结果为 failed 或 no_answer 的号码；结果未知（unknown）、已完成、未拨出、已取消或被黑名单拦截的号码不会进入新批次。没有符合条件的号码返回 400“没有已确认失败或未接听的号码；未知结果不能重拨”。",
        "没有单独的重试号码数量上限，也不记录重试次数：每次使用新的 requestId 调用都会新建一个草稿批次，同一批失败号码可能因此进入多个批次，调用方需自行避免重复重试。企业未完成批次（draft、scheduled、running、paused）达到 100 个或线路已停用时返回 409。",
        "新批次沿用源批次的线路、智能体及其发布版本、并发、预留、号码顺序与拨号时段，名称为源批次名称加“ · 重试”（截断到 80 字符）；不沿用预约时间，启动后立即进入拨号队列。",
        "需要外呼服务处于开通状态（否则返回 403）。线路不存在或已删除返回 404；线路未允许呼出或“并发 + 预留”超过线路并发上限返回 422；智能体发布版本不可用返回 422；号码与线路拨号格式不匹配返回 422；requestId 格式不符返回 400。",
        "若源批次的拨号时段已过截止时间（schedule.validUntil），重试批次会沿用该时段，启动时返回 409“时间配置无效或已截止”；此时改用 outbound-batches.save 新建批次。",
        "成功新建后产生 outbound.batch.created 回调事件（data.sourceId 为新批次 ID）。",
        "网关按 Idempotency-Key 缓存并重放原响应（包括 4xx）；修正条件后重新调用需使用新的 Idempotency-Key，requestId 可保持不变。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "outbound-batches.importStart",
      "group": "电话外呼",
      "name": "批量外呼 · 开始导入",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.importStart",
      "publicPath": "/v1/operations/outbound-batches.importStart",
      "status": "available",
      "description": "每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"importStart\",\"requestId\":\"import_example_request_1\",\"source\":\"generic\",\"fileName\":\"contacts.csv\"}",
      "response": "{\n  \"importJob\": {\n    \"id\": \"import_example\",\n    \"status\": \"uploading\",\n    \"processed\": 1,\n    \"accepted\": 1,\n    \"duplicates\": 0,\n    \"errors\": 0,\n    \"errorSample\": []\n  }\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "importStart",
          "description": "可省略，系统固定为 importStart；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "requestId",
          "type": "string",
          "description": "稳定业务去重标识，16–100 位字母数字横线下划线；同一标识不能改变来源或文件名。",
          "required": true
        },
        {
          "name": "source",
          "type": "string",
          "description": "generic / qichacha / tianyancha / aiqicha。",
          "required": true
        },
        {
          "name": "fileName",
          "type": "string",
          "description": "文件名，可选，最多 160 字符。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "importJob",
          "type": "object",
          "description": "导入任务状态和 processed/accepted/duplicates/errors/errorSample（最多 30 条）统计。",
          "required": false
        }
      ],
      "notes": [
        "每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。",
        "只接收 JSON 数据，不接收文件上传或远程 URL，不会发起呼叫。外部 Skill 应在本地解析文件，逐块提交，再完成校验和保存草稿批次。",
        "complete 无有效号码时返回 failed，否则 ready。已完成的本人任务可再次查询；上传结束后不能继续提交。所有写入在提交时重新校验密钥及账号权限。",
        "分块请求结果未知时保持同一 Idempotency-Key 和正文重试；409 先核实任务状态，不换编号重复上传。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "outbound-batches.importChunk",
      "group": "电话外呼",
      "name": "批量外呼 · 上传导入分块",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.importChunk",
      "publicPath": "/v1/operations/outbound-batches.importChunk",
      "status": "available",
      "description": "每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"importChunk\",\"importId\":\"import_example\",\"rows\":[{\"phone\":\"+8613800138000\",\"name\":\"示例客户\"}]}",
      "response": "{\n  \"importJob\": {\n    \"id\": \"import_example\",\n    \"status\": \"uploading\",\n    \"processed\": 1,\n    \"accepted\": 1,\n    \"duplicates\": 0,\n    \"errors\": 0,\n    \"errorSample\": []\n  }\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "importChunk",
          "description": "可省略，系统固定为 importChunk；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "importId",
          "type": "string",
          "description": "本企业原提交人创建且账号 epoch 未变化的导入任务 ID，最多 100 字符。",
          "required": true
        },
        {
          "name": "rows",
          "type": "array",
          "description": "1–2000 行 {phone,name}；手机号必须字符串，姓名可省略且最多 80 字。通过 Bearer 网关建议每块最多 500 行，受 150000 码元正文限制。",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "importJob",
          "type": "object",
          "description": "导入任务状态和 processed/accepted/duplicates/errors/errorSample（最多 30 条）统计。",
          "required": false
        },
        {
          "name": "chunk",
          "type": "object",
          "description": "本次新接收数量和错误行；无效和重复号码不会写入有效名单。",
          "required": false
        }
      ],
      "notes": [
        "每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。",
        "只接收 JSON 数据，不接收文件上传或远程 URL，不会发起呼叫。外部 Skill 应在本地解析文件，逐块提交，再完成校验和保存草稿批次。",
        "complete 无有效号码时返回 failed，否则 ready。已完成的本人任务可再次查询；上传结束后不能继续提交。所有写入在提交时重新校验密钥及账号权限。",
        "分块请求结果未知时保持同一 Idempotency-Key 和正文重试；409 先核实任务状态，不换编号重复上传。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "outbound-batches.importComplete",
      "group": "电话外呼",
      "name": "批量外呼 · 完成导入",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.importComplete",
      "publicPath": "/v1/operations/outbound-batches.importComplete",
      "status": "available",
      "description": "每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"importComplete\",\"importId\":\"import_example\"}",
      "response": "{\n  \"importJob\": {\n    \"id\": \"import_example\",\n    \"status\": \"ready\",\n    \"processed\": 1,\n    \"accepted\": 1,\n    \"duplicates\": 0,\n    \"errors\": 0,\n    \"errorSample\": []\n  }\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "importComplete",
          "description": "可省略，系统固定为 importComplete；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "importId",
          "type": "string",
          "description": "本企业原提交人创建且账号 epoch 未变化的导入任务 ID，最多 100 字符。",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "importJob",
          "type": "object",
          "description": "导入任务状态和 processed/accepted/duplicates/errors/errorSample（最多 30 条）统计。",
          "required": false
        }
      ],
      "notes": [
        "每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。",
        "只接收 JSON 数据，不接收文件上传或远程 URL，不会发起呼叫。外部 Skill 应在本地解析文件，逐块提交，再完成校验和保存草稿批次。",
        "complete 无有效号码时返回 failed，否则 ready。已完成的本人任务可再次查询；上传结束后不能继续提交。所有写入在提交时重新校验密钥及账号权限。",
        "分块请求结果未知时保持同一 Idempotency-Key 和正文重试；409 先核实任务状态，不换编号重复上传。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "outbound-batches.importCancel",
      "group": "电话外呼",
      "name": "批量外呼 · 取消导入",
      "method": "POST",
      "currentPath": "/v1/operations/outbound-batches.importCancel",
      "publicPath": "/v1/operations/outbound-batches.importCancel",
      "status": "available",
      "description": "每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。",
      "scopes": [
        "service",
        "agent"
      ],
      "request": "{\"action\":\"importCancel\",\"importId\":\"import_example\"}",
      "response": "{\n  \"importJob\": {\n    \"id\": \"import_example\",\n    \"status\": \"canceled\",\n    \"processed\": 1,\n    \"accepted\": 1,\n    \"duplicates\": 0,\n    \"errors\": 0,\n    \"errorSample\": []\n  }\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "importCancel",
          "description": "可省略，系统固定为 importCancel；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "importId",
          "type": "string",
          "description": "本企业原提交人创建且账号 epoch 未变化的导入任务 ID，最多 100 字符。",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "importJob",
          "type": "object",
          "description": "导入任务状态和 processed/accepted/duplicates/errors/errorSample（最多 30 条）统计。",
          "required": false
        }
      ],
      "notes": [
        "每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。",
        "只接收 JSON 数据，不接收文件上传或远程 URL，不会发起呼叫。外部 Skill 应在本地解析文件，逐块提交，再完成校验和保存草稿批次。",
        "complete 无有效号码时返回 failed，否则 ready。已完成的本人任务可再次查询；上传结束后不能继续提交。所有写入在提交时重新校验密钥及账号权限。",
        "分块请求结果未知时保持同一 Idempotency-Key 和正文重试；409 先核实任务状态，不换编号重复上传。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "billing.read",
      "group": "服务结果",
      "name": "读取账单与消耗",
      "method": "GET",
      "currentPath": "/v1/operations/billing.read?start=2026-09-01&end=2026-09-18&page=1",
      "publicPath": "/v1/operations/billing.read",
      "status": "available",
      "description": "三段式分钟套餐和端到端余额消耗分开记账；未结算不是最终费用。",
      "scopes": [
        "billing"
      ],
      "request": "?start=2026-09-01&end=2026-09-18&page=1",
      "response": "{\n  \"summary\": {},\n  \"daily\": [],\n  \"entries\": [],\n  \"orders\": [],\n  \"page\": 1,\n  \"pageSize\": 20,\n  \"timezone\": \"Asia/Shanghai\"\n}",
      "requestFields": [
        {
          "name": "start / end",
          "type": "YYYY-MM-DD",
          "description": "上海时区日期，最多 366 天；默认当月至今。",
          "required": false
        },
        {
          "name": "orderId",
          "type": "string",
          "description": "订单筛选，最多 100 字符。",
          "required": false
        },
        {
          "name": "page",
          "type": "integer",
          "description": "1 至 10000，固定每页 20。",
          "required": false
        },
        {
          "name": "pagination / cursor",
          "type": "string",
          "description": "大账单可传 pagination=cursor；使用返回的 nextCursor 获取下一页。修改企业、日期或订单后从第一页重新读取。",
          "required": false
        },
        {
          "name": "recordId / kind",
          "type": "string",
          "description": "指定原始记录与类型，返回单次会话费用。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "summary / daily / entries / orders",
          "type": "object / array",
          "description": "汇总、每日消耗、账单明细和订单。",
          "required": false
        },
        {
          "name": "hasMore / nextCursor",
          "type": "boolean / string",
          "description": "仅游标模式返回；游标不是授权凭证，下一次请求仍重新校验账单权限。",
          "required": false
        },
        {
          "name": "amountMicros / packageMicros / walletMicros",
          "type": "integer",
          "description": "金额以微元表示，1 元 = 1000000 微元；分别为总额、套餐、余额扣费。",
          "required": false
        }
      ],
      "notes": [
        "三段式分钟套餐和端到端余额消耗分开记账；未结算不是最终费用。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "service-analytics.read",
      "group": "服务结果",
      "name": "读取服务运营分析",
      "method": "GET",
      "currentPath": "/v1/operations/service-analytics.read?reportVersion=2&filter=%7B%22timeMode%22%3A%22range%22%2C%22start%22%3A%222026-11-01%22%2C%22end%22%3A%222026-11-07%22%7D",
      "publicPath": "/v1/operations/service-analytics.read",
      "status": "available",
      "description": "读取当前企业的接待运营统计。带 reportVersion=2 时，按日期范围和筛选条件返回服务端汇总好的 report；不带时返回有容量上限的工作区快照 state，由调用方自行统计。只读，不修改任何数据。",
      "scopes": [
        "reports",
        "service"
      ],
      "request": "?reportVersion=2&filter=%7B%22timeMode%22%3A%22range%22%2C%22start%22%3A%222026-11-01%22%2C%22end%22%3A%222026-11-07%22%7D",
      "response": "{\"state\":{\"revision\":12,\"conversations\":[],\"issues\":[],\"tasks\":[],\"tickets\":[],\"members\":[],\"calls\":[]},\"report\":{\"analytics\":{\"total\":128,\"open\":9,\"closed\":119,\"closeRate\":0.93,\"aiReplyShare\":0.71,\"aiResolutionRate\":0.64,\"resolveRate\":0.88,\"issueCount\":40,\"ticketCount\":6,\"taskCount\":3},\"filterOptions\":{\"platforms\":[],\"connections\":[],\"entries\":[],\"owners\":[],\"channels\":[],\"units\":[],\"agents\":[]}},\"appliedFilter\":{\"query\":\"\",\"channel\":\"all\",\"sourcePlatform\":\"all\",\"sourceChannel\":\"all\",\"sourceEntry\":\"all\",\"dataset\":\"service\",\"recordScope\":\"service\",\"unit\":\"all\",\"owner\":\"all\",\"handling\":\"all\",\"reception\":\"all\",\"receptionMode\":\"all\",\"lifecycle\":\"all\",\"start\":\"2026-11-01\",\"end\":\"2026-11-07\",\"timeMode\":\"range\"},\"agentId\":\"\",\"statistics\":{\"mode\":\"paged-exact\",\"generatedAt\":1794787200000,\"refreshSeconds\":3600,\"channelCacheSeconds\":3600,\"fresh\":false}}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "reportVersion (query)",
          "type": "string",
          "required": false,
          "description": "传 2 使用报表模式（推荐，支持日期范围）。省略时为快照模式，此时除 fresh 外的其余查询参数都不生效。"
        },
        {
          "name": "filter (query)",
          "type": "string",
          "requiredWhen": "reportVersion=2",
          "description": "URL 编码后的 JSON 对象，编码前最多 8000 个字符，可只写需要的键。timeMode：all（默认，全部时间）、range（按 start、end），unknown 与 partial 只统计没有记录时间的数据；start、end：timeMode 为 range 时的起止时间，格式为 YYYY-MM-DD、YYYY-MM-DDTHH:mm[:ss] 或带 Z/±hh:mm 的 ISO 时间；dataset：service（默认）、simulation、test 或 all；recordScope：service（默认）、test 或 all；reception：all、human 或 ai；receptionMode：all、pure-ai、pure-human 或 mixed；channel、sourcePlatform、sourceChannel、sourceEntry、unit、owner、handling、lifecycle：默认 all；query：关键字，最多 200 个字符。其余值每个最多 120 个字符。"
        },
        {
          "name": "reportView (query)",
          "type": "string",
          "required": false,
          "description": "仅报表模式。要额外计算的视图：overview（默认，返回总览统计与筛选项）、source（来源统计，可用 sourceChannel 限定渠道）、work（工作量，增加 report.work）、diagnostics（接待诊断，增加 report.diagnostics）、custom（自定义图表，增加 report.custom）或 statistic（单项指标明细，增加 report.statistic）。"
        },
        {
          "name": "agentId (query)",
          "type": "string",
          "required": false,
          "description": "仅报表模式。只统计该智能体的会话，最多 120 个字符；省略或传 all 表示全部智能体。"
        },
        {
          "name": "page (query)",
          "type": "integer",
          "required": false,
          "description": "仅报表模式。明细分页的页码，1–1000000，默认 1；每页固定 100 行。"
        },
        {
          "name": "cursor (query)",
          "type": "string",
          "required": false,
          "description": "仅报表模式。上一页明细返回的 nextCursor，最多 2000 个字符。"
        },
        {
          "name": "diagnostic (query)",
          "type": "string",
          "required": false,
          "description": "仅 reportView=diagnostics。只保留某一类诊断：all（默认）、reply、handoff、delivery 或 business。"
        },
        {
          "name": "detailKind (query)",
          "type": "string",
          "required": false,
          "description": "仅 reportView=work。要展开明细的分组类型：daily、staff 或 tickets，与 detailKey 一起使用。"
        },
        {
          "name": "detailKey (query)",
          "type": "string",
          "required": false,
          "description": "仅 reportView=work。要展开的分组编号，取 report.work 中对应分组行的 id，最多 200 个字符。"
        },
        {
          "name": "cards (query)",
          "type": "string",
          "required": false,
          "description": "仅 reportView=custom。URL 编码后的 JSON 数组，最多 12 张图表卡片；每张卡片含 id（1–80 位字母、数字、下划线或连字符，不可重复）、chart（line、area、bar、donut、bubble、heatmap、table）、dimension（day、week、month、hour、platform、channel、entry、owner、unit、handling、lifecycle、content、sender）和 metric（如 conversations、closeRate、response、messages、aiShare）。缺少有效 id 的卡片会被忽略，不兼容的组合会被自动调整。"
        },
        {
          "name": "statisticLabel (query)",
          "type": "string",
          "required": false,
          "description": "仅 reportView=statistic。要查看明细的指标名称，最多 200 个字符。"
        },
        {
          "name": "statisticScope (query)",
          "type": "string",
          "required": false,
          "description": "仅 reportView=statistic。URL 编码后的 JSON 对象，编码前最多 2000 个字符，用于把明细限定到某一天（day，YYYY-MM-DD）、某个会话（conversationId）或某类角色（role：customer、ai 或 agent）。"
        },
        {
          "name": "fresh (query)",
          "type": "string",
          "required": false,
          "description": "两种模式均可传 1，跳过已保存的统计快照。"
        }
      ],
      "responseFields": [
        {
          "name": "state",
          "type": "object",
          "required": true,
          "description": "报表模式：只含已授权的配置与成员名单，会话、工单等历史数组为空，不能据此重新计算指标。快照模式：当前密钥可见的工作区数据（conversations 含消息、issues、tasks、tickets、members、calls、config），其中 knowledge、usage、audit 恒为空。"
        },
        {
          "name": "report",
          "type": "object",
          "requiredWhen": "reportVersion=2",
          "description": "服务端汇总结果。"
        },
        {
          "name": "report.analytics",
          "type": "object",
          "requiredWhen": "reportVersion=2",
          "description": "总览指标：total（会话数）、open、closed、closeRate、aiReplyShare、aiResolutionRate、resolveRate、issueCount、ticketCount、taskCount 等。比率是 0–1 的小数，分母为 0 时为 null。"
        },
        {
          "name": "report.filterOptions",
          "type": "object",
          "requiredWhen": "reportVersion=2",
          "description": "当前数据中可用的筛选项，按 platforms、connections、entries、owners、channels、units、agents 分组，每项含 value 与 label。"
        },
        {
          "name": "report.work",
          "type": "object",
          "requiredWhen": "reportView=work",
          "description": "按日期、成员和工单汇总的工作量。"
        },
        {
          "name": "report.diagnostics",
          "type": "object",
          "requiredWhen": "reportView=diagnostics",
          "description": "接待诊断的计数与分页明细，pagination 含 page、pageSize、total、totalPages、nextCursor。"
        },
        {
          "name": "report.custom",
          "type": "object[]",
          "requiredWhen": "reportView=custom",
          "description": "与 cards 一一对应的图表结果。"
        },
        {
          "name": "report.statistic",
          "type": "object",
          "requiredWhen": "reportView=statistic",
          "description": "单项指标的分页明细。"
        },
        {
          "name": "report.detail",
          "type": "object",
          "requiredWhen": "reportView=work 且提供了 detailKind 与 detailKey",
          "description": "所选分组的分页明细行，含 kind、key、rows 与分页信息。"
        },
        {
          "name": "appliedFilter",
          "type": "object",
          "requiredWhen": "reportVersion=2",
          "description": "服务端实际采用的完整筛选条件（未传的键已补默认值）。"
        },
        {
          "name": "agentId",
          "type": "string",
          "requiredWhen": "reportVersion=2",
          "description": "实际采用的智能体编号；统计全部智能体时为空字符串。"
        },
        {
          "name": "statistics",
          "type": "object",
          "required": true,
          "description": "统计口径与新鲜度。"
        },
        {
          "name": "statistics.mode",
          "type": "string",
          "required": true,
          "description": "paged-exact（报表模式，分页读取后精确汇总）或 bounded-exact（快照模式，容量内的完整数据）。两种模式都不会返回抽样或截断后的结果。"
        },
        {
          "name": "statistics.generatedAt",
          "type": "integer",
          "required": true,
          "description": "统计快照生成时的毫秒时间戳。重复读取同一快照时保持一致。"
        },
        {
          "name": "statistics.refreshSeconds",
          "type": "integer",
          "required": true,
          "description": "建议轮询间隔，单位为秒。当前报表和快照为 600，结束日期早于企业当地今天的报表为 3600。"
        },
        {
          "name": "statistics.channelCacheSeconds",
          "type": "integer",
          "required": true,
          "description": "统计快照的最长复用时间，单位为秒。报表返回 600、3600 或 0，0 表示本次按实时范围计算。旧版工作区快照上限为 20。"
        },
        {
          "name": "statistics.fresh",
          "type": "boolean",
          "required": true,
          "description": "传 fresh=1 时为 true。报表按实时范围计算时也为 true。false 表示允许使用缓存，可结合 generatedAt 判断数据时间。"
        }
      ],
      "notes": [
        "前置条件：密钥需同时具备 reports 与 service 权限。时间范围只在报表模式下可用：传 reportVersion=2，并在 filter 中设置 timeMode 为 range 以及 start、end；起始晚于结束或日期无法解析返回 400“请选择有效日期”。快照模式没有时间筛选。",
        "数据新鲜度按企业时区计算。当前汇总最多复用 10 分钟，已结束日期的汇总最多复用 1 小时。诊断、指标和工作明细按请求计算。旧版工作区快照最多复用 20 秒。按 statistics.refreshSeconds 轮询，需最新数据时传 fresh=1。",
        "容量上限：报表模式单次最长计算 90 秒，report 序列化后不超过约 419 万个字符，超出返回 503（“统计范围过大”“统计结果过大”或“统计分组过多”），需缩小日期或筛选范围。快照模式上限为 2,000 个会话、20,000 条消息、序列化后约 419 万个字符和 2 秒处理时间，超出返回 503 且不返回不完整数据，此时请改用报表模式或 conversations.read 分页读取明细。",
        "频率限制：服务端同时最多处理 4 个统计读取，超出返回 429，响应体含 retryAfter: 60 并带 Retry-After: 60；503 同样带 Retry-After: 60。此外仍受密钥每分钟限额约束。整个查询串不能超过 8000 个字符。",
        "错误：400 报表模式缺少 filter（“请选择统计范围”）、参数重复出现或超长、JSON 无法解析（“统计参数无效”）、筛选值不在允许范围（“统计筛选无效”）、reportView 无效（“统计视图无效”）、diagnostic、detailKind 或 page 无效（“统计明细范围无效”）；403 密钥缺少接待权限，或计算期间权限发生变化（“统计权限已变化，请刷新重试”）。",
        "API Key 调用的限制：不带时区的 start、end 以及按天分组固定按 Asia/Shanghai 时区解释，需要其他时区时请传带 Z 或 ±hh:mm 的时间。企业开启手机号隐私保护后，API Key 读到的手机号始终是脱敏值。"
      ],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "quality-reviews.read",
      "group": "服务结果",
      "name": "读取质检复核记录",
      "method": "GET",
      "currentPath": "/v1/operations/quality-reviews.read",
      "publicPath": "/v1/operations/quality-reviews.read",
      "status": "available",
      "description": "同时需要service与reports权限，会话来源受当前可见范围约束。",
      "scopes": [
        "reports",
        "service"
      ],
      "request": "?",
      "response": "{\n  \"items\": [],\n  \"conversations\": [],\n  \"trainingTasks\": [],\n  \"knowledgeDocuments\": [],\n  \"canManage\": true\n}",
      "requestFields": [
        {
          "name": "trainingTask",
          "type": "string",
          "description": "可选：读取本企业训练任务详情，还需team权限；响应改为{task}。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "items",
          "type": "object[]",
          "description": "最近200份候选中的可见复核，含原始AI快照、人工评分、历史及来源变更标记。",
          "required": false
        },
        {
          "name": "trainingTasks / knowledgeDocuments",
          "type": "object[]",
          "description": "按team/knowledge权限分别列出当前可关联的训练任务或已发布知识版本。",
          "required": false
        },
        {
          "name": "canManage",
          "type": "boolean",
          "description": "本人可提交复核；实际提交仍会重新验证。",
          "required": false
        },
        {
          "name": "task",
          "type": "object",
          "description": "trainingTask查询返回真实任务详情及版本，不新建或分配任务。",
          "required": false
        }
      ],
      "notes": [
        "同时需要service与reports权限，会话来源受当前可见范围约束。",
        "关联训练资料还需要team，知识资料需要knowledge；GO_API_URL远程工作台尚未启用复核案例，返回503。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "callbacks.read",
      "group": "事件回调",
      "name": "读取回调订阅",
      "method": "GET",
      "currentPath": "/v1/operations/callbacks.read",
      "publicPath": "/v1/operations/callbacks.read",
      "status": "available",
      "description": "仅订阅本人构建任务事件，不等于企业全部业务变更事件总线。",
      "scopes": [
        "applications",
        "agent",
        "service"
      ],
      "request": "?",
      "response": "{\n  \"subscriptions\": [],\n  \"deliveries\": [],\n  \"events\": {\n    \"outbound.batch.created\": \"外呼批次草稿已创建\",\n    \"outbound.batch.changed\": \"外呼批次控制状态已变更\",\n    \"outbound.batch.completed\": \"外呼批次全部号码已结束\",\n    \"service.config.changed\": \"智能体或渠道配置已更新\",\n    \"agent.published\": \"智能体已发布\",\n    \"workflow.saved\": \"工作流草稿已保存\",\n    \"workflow.published\": \"工作流已发布\",\n    \"service.state.changed\": \"客服会话或工单已更新\",\n    \"analysis.completed\": \"服务总结已完成\",\n    \"analysis.failed\": \"服务总结失败\",\n    \"api.request.completed\": \"API 请求已处理（不代表后台任务完成）\",\n    \"api.request.failed\": \"API 请求被业务接口拒绝\",\n    \"memory.linked\": \"记忆关联已登记\",\n    \"memory.invalidated\": \"记忆关联已失效\",\n    \"build.task.created\": \"构建任务已创建\",\n    \"build.task.review\": \"构建计划待确认\",\n    \"build.task.running\": \"构建开始执行\",\n    \"build.task.approval\": \"构建等待单次授权\",\n    \"build.task.step_completed\": \"构建步骤已完成\",\n    \"build.task.paused\": \"构建已暂停\",\n    \"build.task.failed\": \"构建执行受阻\",\n    \"build.task.completed\": \"构建已完成\",\n    \"build.task.cancelled\": \"构建已取消\",\n    \"build.task.planning\": \"构建重新规划\"\n  }\n}",
      "requestFields": [],
      "responseFields": [
        {
          "name": "subscriptions",
          "type": "array",
          "description": "本人订阅，不返回完整 URL、密钥或加密凭据。",
          "required": true
        },
        {
          "name": "deliveries",
          "type": "array",
          "description": "投递状态、attempts、nextAttempt、httpStatus、事件原始载荷。",
          "required": true
        },
        {
          "name": "events",
          "type": "object",
          "description": "当前可订阅事件注册表。",
          "required": true
        }
      ],
      "notes": [
        "仅订阅本人构建任务事件，不等于企业全部业务变更事件总线。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "callbacks.save",
      "group": "事件回调",
      "name": "回调订阅 · 保存",
      "method": "POST",
      "currentPath": "/v1/operations/callbacks.save",
      "publicPath": "/v1/operations/callbacks.save",
      "status": "available",
      "description": "仅公开 HTTPS 默认端口，拒绝私网、凭据 URL、片段及重定向；每次发送重新校验 DNS。",
      "scopes": [
        "applications",
        "agent",
        "service"
      ],
      "request": "{\"action\":\"save\",\"name\":\"构建进度\",\"endpoint\":\"https://receiver.example.com/events\",\"events\":[\"build.task.completed\",\"build.task.failed\"]}",
      "response": "{\n  \"id\": \"subscription_example\",\n  \"revision\": 1,\n  \"enabled\": false,\n  \"secret\": \"whsec_example_only\"\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "save",
          "description": "可省略，系统固定为 save；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "name",
          "type": "string",
          "description": "名称最多 80 字符。",
          "required": true
        },
        {
          "name": "endpoint",
          "type": "https URL",
          "description": "新建必填；更新留空保留原地址，替换地址会轮换签名密钥。",
          "required": false
        },
        {
          "name": "events",
          "type": "string[]",
          "description": "非空且不重复，限注册表内事件。",
          "required": true
        },
        {
          "name": "id / revision",
          "type": "string / integer",
          "description": "更新时均必填；最多 5 个订阅。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "id / revision / enabled",
          "type": "string / integer / boolean",
          "description": "保存后停用，需显式确认启用。",
          "required": true
        },
        {
          "name": "secret",
          "type": "string",
          "description": "仅创建或地址替换时返回一次，妥善存储，禁止写入日志。",
          "required": false
        }
      ],
      "notes": [
        "仅公开 HTTPS 默认端口，拒绝私网、凭据 URL、片段及重定向；每次发送重新校验 DNS。",
        "sha256=hex(HMAC-SHA256(secret, timestamp + \".\" + raw_body))；timestamp 为 Unix 秒。接收方应以常量时间比较签名并限制 ±300 秒重放窗口。",
        "同事务事件队列，默认本人范围，可显式选择本企业事件。涵盖构建、记忆、配置、发布、工作流、服务状态、总结和 API 结果；仅登记的事件有效。最多自动尝试 5 次，间隔 30 秒、2 分钟、10 分钟、1 小时，依赖原生 scheduled。人工最多 10 次；可能重复或乱序，按事件 ID 去重；停用或变更不补发历史。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "callbacks.toggle",
      "group": "事件回调",
      "name": "回调订阅 · 启用或停用",
      "method": "POST",
      "currentPath": "/v1/operations/callbacks.toggle",
      "publicPath": "/v1/operations/callbacks.toggle",
      "status": "available",
      "description": "启用或停用一个回调订阅。启用后新发生的已订阅事件开始投递到订阅地址；停用后不再生成新投递。不会修改地址、事件或密钥，也不补发停用期间的事件。",
      "scopes": [
        "applications",
        "agent",
        "service"
      ],
      "request": "{\"action\":\"toggle\",\"id\":\"YOUR_SUBSCRIPTION_ID\",\"revision\":1,\"enabled\":true}",
      "response": "{\"ok\":true,\"revision\":2}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "订阅 ID，最长 100 字符。取自 callbacks.save 响应的 id，或 callbacks.read 的 subscriptions[].id；只能操作 API Key 所属管理员账号名下的订阅。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "订阅当前 revision，必须是 JSON 整数且与服务端当前值完全相等。取自 callbacks.save 响应的 revision，或 callbacks.read 的 subscriptions[].revision。"
        },
        {
          "name": "enabled",
          "type": "boolean",
          "required": true,
          "description": "true 启用，false 停用。必须是 JSON 布尔值，否则返回 400“启用状态无效”。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "订阅的新 revision（原值加 1），下一次写入直接使用。"
        }
      ],
      "notes": [
        "前置条件：先用 callbacks.read 读取订阅的最新 revision。订阅不存在或不属于 API Key 所属管理员账号返回 404；revision 不一致返回 409“订阅版本已变化，请刷新”。",
        "启用（enabled: true）要求订阅未被删除，且调用方与订阅所属管理员账号都具备订阅内每个事件所需的权限（api.* 事件需 applications；outbound.*、memory.*、analysis.* 与 service.state.changed 需 service；其余事件需 agent），否则返回 403“订阅已删除或事件权限不足”。",
        "立即生效。只投递启用之后发生的事件；停用期间发生的事件不会入队，也不会在重新启用后补发。",
        "每次启停都会使订阅 revision 加 1：此前尚未送达（pending、retry）的投递会在下一轮调度被取消（status=cancelled），此前 dead 的投递也不能再用 callbacks.retry 重试。",
        "重复提交当前已有的状态（例如对已启用的订阅再次传 enabled: true）不会报错，但同样使 revision 加 1 并取消未送达的投递。",
        "callbacks.save 与 callbacks.rotate 成功后订阅都处于停用状态，需调用本操作重新启用。",
        "API Key 所属账号必须是企业管理员并具备 applications 与 agent 权限，否则返回 403。回调管理操作本身不产生 api.request.completed / api.request.failed 回调事件。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "callbacks.test",
      "group": "事件回调",
      "name": "回调订阅 · 测试",
      "method": "POST",
      "currentPath": "/v1/operations/callbacks.test",
      "publicPath": "/v1/operations/callbacks.test",
      "status": "available",
      "description": "调用 action=test 会向外部接收地址发送真实 webhook.test 验证事件，每人每分钟最多 10 次。",
      "scopes": [
        "applications",
        "agent",
        "service"
      ],
      "request": "{\"action\":\"test\",\"id\":\"subscription_example\",\"revision\":2}",
      "response": "{\n  \"eventId\": \"test:example\"\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "toggle | test | retry | dispatch",
          "description": "可省略，系统固定为 test；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "id / revision",
          "type": "string / integer",
          "description": "其余操作必须携带最新订阅版本。",
          "required": false
        },
        {
          "name": "enabled",
          "type": "boolean",
          "description": "toggle 必填。",
          "required": false
        },
        {
          "name": "deliveryId",
          "type": "string",
          "description": "retry 必填，只允许 dead 且尝试次数少于 10。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "ok / eventId / queued",
          "type": "boolean / string / boolean",
          "description": "按操作返回；queued 不是接收成功。",
          "required": false
        }
      ],
      "notes": [
        "调用 action=test 会向外部接收地址发送真实 webhook.test 验证事件，每人每分钟最多 10 次。",
        "最多自动尝试 5 次，后续可人工重试至总计 10 次；同一事件 ID 去重，不保证顺序或恰好一次。",
        "自动重试需要部署原生 scheduled 触发器；本地预览无常驻定时器，刷新不会投递。"
      ],
      "callbackEvents": [
        "outbound.batch.created",
        "outbound.batch.changed",
        "outbound.batch.completed",
        "service.config.changed",
        "agent.published",
        "workflow.saved",
        "workflow.published",
        "service.state.changed",
        "analysis.completed",
        "analysis.failed",
        "api.request.completed",
        "api.request.failed",
        "memory.linked",
        "memory.invalidated",
        "build.task.created",
        "build.task.review",
        "build.task.running",
        "build.task.approval",
        "build.task.step_completed",
        "build.task.paused",
        "build.task.failed",
        "build.task.completed",
        "build.task.cancelled",
        "build.task.planning"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "callbacks.retry",
      "group": "事件回调",
      "name": "回调订阅 · 重试失败投递",
      "method": "POST",
      "currentPath": "/v1/operations/callbacks.retry",
      "publicPath": "/v1/operations/callbacks.retry",
      "status": "available",
      "description": "把一条自动重试已耗尽（status=dead）的投递记录重新排队，由后台再向订阅地址发送一次。针对单条投递，不是整个事件或订阅；响应只表示已排队，不代表接收方已收到。",
      "scopes": [
        "applications",
        "agent",
        "service"
      ],
      "request": "{\"action\":\"retry\",\"id\":\"YOUR_SUBSCRIPTION_ID\",\"revision\":2,\"deliveryId\":\"YOUR_DELIVERY_ID\"}",
      "response": "{\"ok\":true}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "订阅 ID，最长 100 字符。取自 callbacks.save 响应的 id，或 callbacks.read 的 subscriptions[].id；只能操作 API Key 所属管理员账号名下的订阅。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "订阅当前 revision，必须是 JSON 整数且与服务端当前值完全相等。取自 callbacks.save 响应的 revision，或 callbacks.read 的 subscriptions[].revision。"
        },
        {
          "name": "deliveryId",
          "type": "string",
          "required": true,
          "description": "要重试的投递记录 ID，最长 200 字符。取自 callbacks.read 的 deliveries[].id，且该记录的 subscriptionId 必须等于本请求的 id。"
        }
      ],
      "responseFields": [
        {
          "name": "ok",
          "type": "boolean",
          "required": true,
          "description": "固定为 true，仅表示该投递已重新排队；投递结果用 callbacks.read 查询。"
        }
      ],
      "notes": [
        "前置条件：先用 callbacks.read 读取订阅的最新 revision。订阅不存在或不属于 API Key 所属管理员账号返回 404；revision 不一致返回 409“订阅版本已变化，请刷新”。",
        "订阅必须处于启用状态，且启用后所属账号的授权版本未变化，否则返回 409“请重新确认并启用订阅”。",
        "只能重试 status=dead 的投递（自动尝试 5 次均未成功），并且该投递生成后订阅 revision 未变化（期间没有保存、启停或轮换）、累计尝试次数 attempts 小于 10；不满足任一条件返回 409“仅可重试配置未变化且少于 10 次的失败投递”。pending、retry、sending、delivered、cancelled 状态均不可重试。",
        "每次调用只增加 1 次投递尝试：再次失败后投递回到 dead，可继续调用，直到累计 10 次（自动 5 次加人工最多 5 次）。",
        "异步生效：投递被置为 pending 并立即到期，由后台回调队列发送。用 callbacks.read 的 deliveries[] 查看 status、attempts、httpStatus 与 message，用 callbacks.read?delivery=投递ID 查看每次尝试的记录。",
        "重试沿用原事件 ID 与投递 ID（X-Yunfu-Event-Id、X-Yunfu-Delivery-Id 不变），时间戳与签名重新生成；接收方应按事件 ID 去重。",
        "callbacks.read 只返回最近 100 条投递记录；更早的投递需自行保存其 ID 才能重试。",
        "API Key 所属账号必须是企业管理员并具备 applications 与 agent 权限，否则返回 403。回调管理操作本身不产生 api.request.completed / api.request.failed 回调事件。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "callbacks.rotate",
      "group": "事件回调",
      "name": "回调订阅 · 轮换签名密钥",
      "method": "POST",
      "currentPath": "/v1/operations/callbacks.rotate",
      "publicPath": "/v1/operations/callbacks.rotate",
      "status": "available",
      "description": "为订阅生成新的签名密钥并在响应中返回一次；旧密钥立即作废，订阅被自动停用，尚未送达的投递被取消。不会改变回调地址和订阅事件；接收方换上新密钥后需重新启用订阅。",
      "scopes": [
        "applications",
        "agent",
        "service"
      ],
      "request": "{\"action\":\"rotate\",\"id\":\"YOUR_SUBSCRIPTION_ID\",\"revision\":2}",
      "response": "{\"secret\":\"whsec_EXAMPLE_ONLY\",\"enabled\":false,\"revision\":3}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "订阅 ID，最长 100 字符。取自 callbacks.save 响应的 id，或 callbacks.read 的 subscriptions[].id；只能操作 API Key 所属管理员账号名下的订阅。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "订阅当前 revision，必须是 JSON 整数且与服务端当前值完全相等。取自 callbacks.save 响应的 revision，或 callbacks.read 的 subscriptions[].revision。"
        }
      ],
      "responseFields": [
        {
          "name": "secret",
          "type": "string",
          "required": true,
          "description": "新的签名密钥，格式为 whsec_ 加 64 位十六进制字符。只在本次响应中返回，服务端加密保存，任何读取操作都不再返回；请立即安全保存，不要写入日志。"
        },
        {
          "name": "enabled",
          "type": "boolean",
          "required": true,
          "description": "固定为 false：轮换后订阅处于停用状态。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "订阅的新 revision；重新启用时传给 callbacks.toggle。"
        }
      ],
      "notes": [
        "前置条件：先用 callbacks.read 读取订阅的最新 revision。订阅不存在或不属于 API Key 所属管理员账号返回 404；revision 不一致返回 409“订阅版本已变化，请刷新”。",
        "启用或停用状态的订阅都可以轮换；已删除的订阅返回 409“订阅已删除”。",
        "立即生效，没有新旧密钥并存的过渡期：旧密钥在响应返回时已作废。",
        "轮换后订阅被自动停用：接收方换上新密钥后，用响应中的 revision 调用 callbacks.toggle（enabled: true）重新启用。停用期间发生的事件不会补发。",
        "轮换时尚未送达的投递（pending、retry、sending）全部被取消（status=cancelled，message 为“订阅密钥已轮换或订阅已删除”），不会用新密钥补发；轮换前 dead 的投递也不能再用 callbacks.retry 重试。已送达的记录保留。",
        "新密钥无法再次查询。唯一例外是使用相同 Idempotency-Key 与相同正文重放请求：网关在 24 小时内返回原响应（含同一 secret）。密钥丢失后只能再次轮换。",
        "API Key 所属账号必须是企业管理员并具备 applications 与 agent 权限，否则返回 403。回调管理操作本身不产生 api.request.completed / api.request.failed 回调事件。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "callbacks.delete",
      "group": "事件回调",
      "name": "回调订阅 · 删除订阅",
      "method": "POST",
      "currentPath": "/v1/operations/callbacks.delete",
      "publicPath": "/v1/operations/callbacks.delete",
      "status": "available",
      "description": "永久停用并清除一个回调订阅的地址与签名密钥，取消其尚未送达的投递。订阅记录与历史投递记录保留供审计查询，但订阅不能再启用或修改。",
      "scopes": [
        "applications",
        "agent",
        "service"
      ],
      "request": "{\"action\":\"delete\",\"id\":\"YOUR_SUBSCRIPTION_ID\",\"revision\":2}",
      "response": "{\"enabled\":false,\"revision\":3}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "订阅 ID，最长 100 字符。取自 callbacks.save 响应的 id，或 callbacks.read 的 subscriptions[].id；只能操作 API Key 所属管理员账号名下的订阅。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "订阅当前 revision，必须是 JSON 整数且与服务端当前值完全相等。取自 callbacks.save 响应的 revision，或 callbacks.read 的 subscriptions[].revision。"
        }
      ],
      "responseFields": [
        {
          "name": "enabled",
          "type": "boolean",
          "required": true,
          "description": "固定为 false：订阅已停用并删除。"
        },
        {
          "name": "revision",
          "type": "integer",
          "required": true,
          "description": "订阅的新 revision（原值加 1）。"
        }
      ],
      "notes": [
        "前置条件：先用 callbacks.read 读取订阅的最新 revision。订阅不存在或不属于 API Key 所属管理员账号返回 404；revision 不一致返回 409“订阅版本已变化，请刷新”。",
        "不可恢复：删除后回调地址与签名密钥被清除，再启用返回 403、再保存返回 409。如需恢复，用 callbacks.save 新建订阅（得到新的 ID 与密钥）。",
        "删除保留记录而非物理删除：订阅仍出现在 callbacks.read 的 subscriptions[] 中，名称加“[已删除] ”前缀、events 为空数组、enabled 为 false；历史投递记录与每次尝试的记录保留，仍可通过 callbacks.read 查询。",
        "删除时尚未送达的投递（pending、retry、sending）被取消（status=cancelled，message 为“订阅密钥已轮换或订阅已删除”）；已经发出的请求无法撤回。",
        "已删除的订阅不再计入“每个账号最多 5 个订阅”的数量上限。",
        "对已删除的订阅再次调用 delete 或 rotate 返回 409“订阅已删除”，不会改变记录。",
        "API Key 所属账号必须是企业管理员并具备 applications 与 agent 权限，否则返回 403。回调管理操作本身不产生 api.request.completed / api.request.failed 回调事件。"
      ],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "email-customer.read",
      "group": "邮件接待",
      "status": "available",
      "scopes": [
        "service"
      ],
      "callbackEvents": [],
      "name": "读取邮件关联客户与有效记忆",
      "method": "GET",
      "currentPath": "/v1/operations/email-customer.read?view=customerContext&messageId=message-id",
      "publicPath": "/v1/operations/email-customer.read",
      "description": "按服务端邮件的邮箱解析同企业客户；重复邮箱、归档和失效关联不自动读取记忆。返回受授权且对客可见的有效记忆与有界历史。",
      "request": "?view=customerContext&messageId=message-id",
      "response": "{\"messageId\": \"message-id\", \"association\": {\"status\": \"matched\", \"identityVerified\": false}, \"customer\": {\"id\": \"customer-id\"}, \"memory\": {\"status\": \"available\", \"entries\": []}, \"history\": []}",
      "notes": [
        "只读取当前账号授权邮箱；邮箱匹配不是身份认证。",
        "示例未实际执行；AI可能计费，发送需用户明确授权。"
      ],
      "requestFields": [
        {
          "name": "view (query)",
          "type": "string",
          "description": "固定customerContext",
          "required": true
        },
        {
          "name": "messageId (query)",
          "type": "string",
          "description": "可读邮件的真实ID",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "association",
          "type": "object",
          "description": "业务邮箱匹配状态，不是身份认证",
          "required": false
        },
        {
          "name": "customer",
          "type": "object|null",
          "description": "允许关联的客户摘要",
          "required": false
        },
        {
          "name": "memory",
          "type": "object",
          "description": "授权且对客可见的有效记忆，含状态与完整条件",
          "required": false
        },
        {
          "name": "history",
          "type": "array",
          "description": "同邮箱此前最多5封授权邮件",
          "required": false
        },
        {
          "name": "fingerprint",
          "type": "string",
          "description": "本次上下文指纹",
          "required": false
        }
      ],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "phone-records.export",
      "name": "导出电话记录",
      "group": "电话外呼",
      "method": "GET",
      "currentPath": "/v1/operations/phone-records.export?view=export&ids=11111111-1111-4111-8111-111111111111",
      "publicPath": "/v1/operations/phone-records.export",
      "status": "available",
      "description": "一次读取授权电话记录的完整转写与结论，返回 JSON；CSV 由调用方生成。",
      "scopes": [
        "service"
      ],
      "request": "?view=export&ids=11111111-1111-4111-8111-111111111111",
      "response": "{\"calls\":[]}",
      "requestFields": [
        {
          "name": "view",
          "description": "固定 export；操作网关 phone-records.export 会自动注入此查询参数。",
          "type": "string",
          "required": true
        },
        {
          "name": "ids",
          "description": "逗号分隔的 1–100 个唯一电话 UUID；全部需属于当前企业。",
          "type": "string",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "calls",
          "description": "按选择顺序返回完整 PhoneCall，含 messages/summary/cause/status/answered 等字段；无总结时 summary 为空。",
          "type": "array",
          "required": false
        }
      ],
      "notes": [
        "电话呼叫 UUID 与 voice-records 的 sessionId 不同；不得把电话 ID 传入 analysis.read?kind=voice。",
        "服务器返回 application/json，不是 CSV 文件。部分 ID 不存在或无权读取时整批返回 404，不静默导出部分数据。",
        "先通过 phone-calls.read 分页筛选，按每批最多 100 个 ID 导出。记录可能包含客户正文，保存到用户指定的本地位置。",
        "只读导出不会发起电话或生成收费分析。"
      ],
      "callbackEvents": [],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    },
    {
      "id": "business-data.snapshot",
      "group": "客户资料",
      "name": "读取客户订单与物流快照",
      "method": "POST",
      "currentPath": "/v1/operations/business-data.snapshot",
      "publicPath": "/v1/operations/business-data.snapshot",
      "status": "available",
      "description": "只读能力仅对正式会话生效：会话必须来自已支持的原生渠道，并已关联和核验客户；请求体不能覆盖客户、企业、渠道或商家账号。",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"customerSnapshot\",\"conversationId\":\"conv_example\"}",
      "response": "{\n  \"result\": {\n    \"platformId\": \"taobao\",\n    \"channelId\": \"channel_example\",\n    \"customerId\": \"cus_example\",\n    \"fetchedAt\": 1789693200000,\n    \"customer\": {\n      \"customerId\": \"cus_example\",\n      \"displayName\": \"客户\",\n      \"phoneMasked\": \"138****0000\",\n      \"emailMasked\": \"c***@example.com\",\n      \"locale\": \"zh-CN\",\n      \"level\": \"普通\",\n      \"tags\": []\n    },\n    \"orders\": [\n      {\n        \"orderId\": \"order_example\",\n        \"status\": \"shipped\",\n        \"amountPaid\": 199,\n        \"refundableAmount\": 0,\n        \"carrier\": \"示例物流\",\n        \"trackingNumber\": \"masked_tracking\",\n        \"logisticsStatus\": \"运输中\",\n        \"timeline\": [\n          \"2026-09-29 10:00 已揽收\"\n        ]\n      }\n    ]\n  }\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "customerSnapshot",
          "description": "可省略，系统固定为 customerSnapshot；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "conversationId",
          "type": "string",
          "description": "正式会话编号；必须属于当前企业且已关联并核验客户档案。",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "result.platformId / result.channelId",
          "type": "string",
          "description": "会话来源平台与渠道编号。",
          "required": true
        },
        {
          "name": "result.customerId",
          "type": "string",
          "description": "已核验客户编号。",
          "required": true
        },
        {
          "name": "result.fetchedAt",
          "type": "integer",
          "description": "从商家接口读取快照的时间戳，单位毫秒。",
          "required": true
        },
        {
          "name": "result.customer",
          "type": "object",
          "description": "按渠道授权返回的客户资料；联系方式仅返回脱敏值。",
          "required": false
        },
        {
          "name": "result.orders[]",
          "type": "array",
          "description": "订单和物流摘要；字段包括 orderId、status、amountPaid、refundableAmount、carrier、trackingNumber、logisticsStatus、timeline。",
          "required": false
        }
      ],
      "notes": [
        "使用企业管理员创建的 Bearer API Key；网关会将操作绑定到密钥所属企业与账号，不能通过请求体切换租户或客户。",
        "POST 网关必须携带 8–100 位 Idempotency-Key；同一标识只能重放同一请求，结果未知时不要换标识重复执行。",
        "只读能力仅对正式会话生效：会话必须来自已支持的原生渠道，并已关联和核验客户；请求体不能覆盖客户、企业、渠道或商家账号。",
        "当前支持美团、京东、淘宝、五八、拼多多、抖音、小红书、Amazon 和 eBay 渠道；是否能返回字段仍由渠道的“接入智能体的信息”权限及订单/物流 scope 决定。",
        "企业必须先在开放平台配置启用的客户订单只读连接器。连接器密钥只在服务端使用，绝不会通过 API 返回；目标地址必须为公开 HTTPS 且会重新校验 DNS。",
        "快照经过字段白名单、归属校验和大小限制；外部商家返回的文本不会被当作智能体指令。连接器不可用、超时或返回未知数据时会返回明确错误，不伪造订单结论。",
        "网关要求 Idempotency-Key；只读请求也使用同一请求语义以便安全重试，重复键返回缓存的同一快照结果。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "business-data.lookup",
      "group": "客户资料",
      "name": "查询订单或物流状态",
      "method": "POST",
      "currentPath": "/v1/operations/business-data.lookup",
      "publicPath": "/v1/operations/business-data.lookup",
      "status": "available",
      "description": "这是只读查询，不会发起退款、改价、改地址或其他订单写入；退款、订单更新和物流更新仍需后台客服提交并由人工审批。",
      "scopes": [
        "service"
      ],
      "request": "{\"action\":\"lookup\",\"conversationId\":\"conv_example\",\"kind\":\"logistics_lookup\",\"input\":{\"orderId\":\"order_example\",\"customerId\":\"cus_example\"}}",
      "response": "{\n  \"result\": {\n    \"orderId\": \"order_example\",\n    \"customerId\": \"cus_example\",\n    \"status\": \"shipped\",\n    \"amountPaid\": 199,\n    \"refundableAmount\": 0,\n    \"carrier\": \"示例物流\",\n    \"trackingNumber\": \"masked_tracking\",\n    \"timeline\": [\n      \"2026-09-29 10:00 已揽收\"\n    ]\n  }\n}",
      "requestFields": [
        {
          "name": "action",
          "type": "lookup",
          "description": "可省略，系统固定为 lookup；传入其他值返回 400。",
          "required": false
        },
        {
          "name": "conversationId",
          "type": "string",
          "description": "正式会话编号；必须属于当前企业并已关联客户。",
          "required": true
        },
        {
          "name": "kind",
          "type": "order_lookup | logistics_lookup",
          "description": "读取订单摘要或物流状态。",
          "required": true
        },
        {
          "name": "input.orderId",
          "type": "string",
          "description": "商家订单编号。",
          "required": true
        },
        {
          "name": "input.customerId",
          "type": "string",
          "description": "已核验客户编号，必须与会话关联客户一致。",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "result.orderId / result.customerId",
          "type": "string",
          "description": "经过归属校验后返回的订单与客户编号。",
          "required": true
        },
        {
          "name": "result.status",
          "type": "string",
          "description": "订单或物流状态，已限制长度。",
          "required": false
        },
        {
          "name": "result.amountPaid / result.refundableAmount",
          "type": "number | null",
          "description": "金额字段；未知时为 null，不用 0 代替未知。",
          "required": false
        },
        {
          "name": "result.carrier / result.trackingNumber",
          "type": "string",
          "description": "物流承运商和运单号；按渠道权限返回并可能脱敏。",
          "required": false
        },
        {
          "name": "result.timeline",
          "type": "string[]",
          "description": "最多 20 条经过长度限制的物流节点。",
          "required": false
        }
      ],
      "notes": [
        "使用企业管理员创建的 Bearer API Key；网关会将操作绑定到密钥所属企业与账号，不能通过请求体切换租户或客户。",
        "POST 网关必须携带 8–100 位 Idempotency-Key；同一标识只能重放同一请求，结果未知时不要换标识重复执行。",
        "这是只读查询，不会发起退款、改价、改地址或其他订单写入；退款、订单更新和物流更新仍需后台客服提交并由人工审批。",
        "服务端会将订单与当前会话关联客户做强一致校验，并只保留文档列出的字段；外部接口返回的任意说明不会作为提示词或系统指令执行。",
        "外部连接器返回 429、超时、无效 JSON 或归属不一致时，接口会返回明确错误；不会无限重试、伪造办结或隐瞒待处理状态。",
        "网关要求 Idempotency-Key；相同标识和请求可安全重放缓存结果，不能使用新标识绕过未知结果。"
      ],
      "callbackEvents": [],
      "idempotency": "POST 必带 Idempotency-Key；重试保留原键和原参数。结果未知时先核对业务结果。"
    },
    {
      "id": "customers.bindPreview",
      "group": "客户资料",
      "name": "客户资料 · 预览会话与客户的关联",
      "method": "GET",
      "currentPath": "/v1/operations/customers.bindPreview?bindPreview=1&conversationId=YOUR_CONVERSATION_ID&customerId=YOUR_CUSTOMER_ID",
      "publicPath": "/v1/operations/customers.bindPreview",
      "status": "available",
      "description": "读取把一个会话关联到某位客户前所需的全部版本号，并对比当前关联客户与目标客户的资料差异。只读，不修改关联。",
      "scopes": [
        "customers",
        "service"
      ],
      "request": "?bindPreview=1&conversationId=YOUR_CONVERSATION_ID&customerId=YOUR_CUSTOMER_ID",
      "response": "{\"catalogRevision\":12,\"conversationVersion\":5,\"linkRevision\":0,\"customerRevision\":4,\"from\":null,\"to\":{\"id\":\"YOUR_CUSTOMER_ID\",\"name\":\"示例客户\",\"revision\":4},\"source\":{\"channelName\":\"官网客服\",\"label\":\"官网客服 / 默认入口\"},\"conflicts\":[],\"effect\":\"仅调整当前会话关联；两份客户档案保持独立，旧记忆授权将撤销。\"}",
      "callbackEvents": [],
      "requestFields": [
        {
          "name": "conversationId (query)",
          "type": "string",
          "required": true,
          "description": "要关联的会话编号，必须是当前身份可见的会话。"
        },
        {
          "name": "customerId (query)",
          "type": "string",
          "required": false,
          "description": "目标客户编号，最多 100 字符；省略表示预览解除关联。"
        }
      ],
      "responseFields": [
        {
          "name": "catalogRevision",
          "type": "integer",
          "required": true,
          "description": "客户目录版本，作为 customers.bind 的 revision。"
        },
        {
          "name": "conversationVersion",
          "type": "integer",
          "required": true,
          "description": "会话当前 version，作为 customers.bind 的 conversationVersion。"
        },
        {
          "name": "linkRevision",
          "type": "integer",
          "required": true,
          "description": "会话当前客户关联的版本；没有关联时为 0。"
        },
        {
          "name": "customerRevision",
          "type": "integer",
          "requiredWhen": "customerId 非空",
          "description": "目标客户档案版本；省略 customerId 时不返回。"
        },
        {
          "name": "from",
          "type": "object",
          "required": true,
          "description": "会话当前关联的客户档案；没有关联时为 null。"
        },
        {
          "name": "to",
          "type": "object",
          "required": true,
          "description": "目标客户档案；省略 customerId 时为 null。"
        },
        {
          "name": "source",
          "type": "object",
          "required": true,
          "description": "会话来源（平台、渠道、入口）。"
        },
        {
          "name": "conflicts",
          "type": "object[]",
          "required": true,
          "description": "两份档案中都有值且不同的字段：{field,from,to}，field 为 name、phone、email、company、namespace 或 externalId。"
        }
      ],
      "notes": [
        "需要账号同时具备 customers 与 service 权限；会话不可见返回 404「对话不存在或无访问权限」，客户不存在返回 404「用户不存在」。",
        "企业开启号码隐私后，返回的手机号为脱敏值。"
      ],
      "idempotency": "只读查询可有界重试；429 按 Retry-After 等待。"
    }
  ],
  "routes": []
}