sequenceDiagram
  participant User as "外部用户"
  participant Channel as "聊天通道或第三方页面"
  participant DataMax as "DataMax 接入网关"
  participant Identity as "第三方用户与权限系统"
  participant Docs as "第三方文档库"
  participant Capability as "DataMax 能力服务"
  participant Action as "第三方产物或业务系统"

  User->>Channel: 发送问题或操作请求
  Channel->>DataMax: 提交标准化消息事件
  DataMax->>DataMax: 校验请求和幂等键
  DataMax->>Identity: 解析用户身份和有效权限
  DataMax->>Docs: 使用已授权的文档证据
  DataMax->>Capability: 生成回答、产物或动作请求
  Capability->>Action: 发送已确认的发布或业务动作
  Capability->>Channel: 返回回答、状态或确认请求
  Channel->>User: 展示给用户

X-V3-Connection-Id: generic-chat-main
X-V3-Timestamp: 2026-05-13T12:00:00Z
X-V3-Nonce: 01HXEXAMPLE
X-V3-Signature: sha256=...

method + "\n" + path + "\n" + timestamp + "\n" + nonce + "\n" + raw_body_sha256

{platform}:{tenant_external_id}:{message_external_id}

generic_chat:tenant-001:msg-20260513-0001

POST /v1/external/channels/{connection_id}/events
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "platform": "generic_chat",
  "tenant_external_id": "tenant-ext-001",
  "bot_external_id": "bot-v3",
  "conversation_external_id": "chat-risk-room",
  "thread_external_id": "thread-001",
  "sender_external_id": "user-10001",
  "message_external_id": "msg-20260513-0001",
  "message_type": "text",
  "text": "请基于我有权限查看的制度文档，说明本周采购审批需要注意什么。",
  "available_document_source_id": "src-docs",
  "available_document_external_ids": ["doc-001"],
  "business_datasource_ids": [],
  "requested_skills": [
    {
      "skill_id": "policy_risk_review",
      "version": "2026-05-20",
      "mode": "preferred",
      "arguments": {
        "focus": "procurement"
      }
    }
  ],
  "mention_external_user_ids": [],
  "attachment_refs": [],
  "idempotency_key": "generic_chat:tenant-ext-001:msg-20260513-0001",
  "received_at": "2026-05-13T12:00:00Z"
}

{
  "conversation_external_id": "chat-risk-room",
  "message_external_id": "msg-20260513-0002",
  "text": "请汇总这几个工作区分组里的制度差异。",
  "available_document_source_id": "src-docs",
  "dataset_external_ids": ["workspace-main", "workspace-archive"],
  "available_document_external_ids": ["extra-policy-doc-001"]
}

{
  "accepted": true,
  "assistant_run_id": "arun_01HXEXAMPLE",
  "idempotency_key": "generic_chat:tenant-ext-001:msg-20260513-0001",
  "reply": {
    "target_conversation_external_id": "chat-risk-room",
    "reply_type": "text",
    "text": "根据你当前权限可查看的制度文档，本周采购审批需要重点关注三点...",
    "task_status": "answered",
    "requires_confirmation": false
  }
}

{
  "platform": "generic_chat",
  "tenant_external_id": "tenant-ext-001",
  "bot_external_id": "bot-v3",
  "conversation_external_id": "conv-order-001",
  "sender_external_id": "user-10001",
  "message_external_id": "msg-order-image-001",
  "message_type": "image",
  "text": "请识别这张充值记录截图，按订单字段返回 JSON。",
  "output_format": "json",
  "requested_skills": [
    {
      "skill_id": "order_screenshot_extract",
      "mode": "required",
      "arguments": {
        "schema": {
          "record_type": "recharge_order"
        }
      }
    }
  ],
  "attachment_refs": [
    {
      "attachment_external_id": "img-order-001",
      "filename": "recharge-orders.png",
      "content_type": "image/png",
      "size_bytes": 2048,
      "download_url_redacted": "https://example.com/recharge-orders.png"
    }
  ],
  "idempotency_key": "chat:tenant-ext-001:msg-order-image-001",
  "received_at": "2026-06-04T10:00:00Z"
}

{
  "reply": {
    "reply_type": "card",
    "task_status": "answered",
    "text": "{...JSON...}",
    "card": {
      "type": "v3_order_screenshot_extract",
      "status": "answered",
      "extraction_id": "img-extract-xxx",
      "record_count": 1,
      "needs_review": false,
      "records": [
        {
          "recharge_amount": 100,
          "recharge_amount_raw": "$100",
          "pay_amount": 700,
          "pay_amount_raw": "$700",
          "payment_method": "alipay",
          "payment_method_label": "支付宝",
          "order_no": "A1778730534",
          "status": "success",
          "status_label": "成功",
          "created_at": "2026/5/14 11:48:54"
        }
      ]
    }
  }
}

POST /v1/external/channels/{connection_id}/events/stream
Host: v3.elepcloud.com
Content-Type: application/json
Accept: text/event-stream
Authorization: Bearer <DataMax inbound token>

// 示例 A：fetch POST 直接消费 SSE，适合第三方服务端或受控前端代理。
function parseSseFrames(chunkText, state) {
  state.buffer += chunkText;
  const frames = state.buffer.split('\n\n');
  state.buffer = frames.pop() || '';
  return frames.map((frame) => {
    const event = frame.match(/^event: (.+)$/m)?.[1] || 'message';
    const dataText = frame.match(/^data: (.+)$/m)?.[1] || '{}';
    return { event, data: JSON.parse(dataText) };
  });
}

async function streamExternalMessage({ url, token, requestBody, handlers }) {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      authorization: `Bearer ${token}`,
      accept: 'text/event-stream',
      'content-type': 'application/json',
    },
    body: JSON.stringify(requestBody),
  });
  if (!response.ok || !response.body) {
    throw new Error(`DataMax stream failed: ${response.status}`);
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  const state = { buffer: '', lastSequence: 0, lastEventId: '' };

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    const frames = parseSseFrames(decoder.decode(value, { stream: true }), state);
    for (const frame of frames) {
      const { event, data } = frame;
      if (data.sequence) state.lastSequence = data.sequence;
      if (data.event_id) state.lastEventId = data.event_id;

      if (event === 'external_channel.delta') {
        handlers.onDelta?.(data.delta || '');
      } else if (event === 'external_channel.completed') {
        handlers.onCompleted?.(data.data?.response || data.response);
      } else if (event === 'external_channel.needs_input') {
        handlers.onNeedsInput?.(data.data?.card || data.card || data);
      } else if (event === 'done') {
        handlers.onDone?.(data);
      } else if (event === 'error') {
        handlers.onError?.(data.error || data);
      } else {
        handlers.onProgress?.({
          event,
          phase: data.phase,
          status: data.status,
          text: data.display_text,
          statusUrl: data.status_url || data.data?.card?.status_url,
          pollAfterSeconds: data.poll_after_seconds || data.data?.card?.poll_after_seconds,
          artifactLink: data.artifact_links?.[0] || data.card?.public_url || data.data?.card?.public_url,
        });
      }
    }
  }
  return state;
}

// 示例 B：断线续传。保留原 requestBody 和 idempotency_key，只补 stream_since_sequence。
async function reconnectExternalStream({ url, token, requestBody, lastSequence, handlers }) {
  return streamExternalMessage({
    url,
    token,
    requestBody: {
      ...requestBody,
      stream_since_sequence: lastSequence,
    },
    handlers,
  });
}

// 示例 C：status_url 轮询兜底。适合 SSE 超时、浏览器切后台、网关限制长连接。
async function pollExternalStatus({ statusUrl, token, onProgress }) {
  let pollAfterSeconds = 15;
  while (statusUrl) {
    await new Promise((resolve) => setTimeout(resolve, pollAfterSeconds * 1000));
    const payload = await fetch(statusUrl, {
      headers: { authorization: `Bearer ${token}`, accept: 'application/json' },
    }).then((response) => response.json());

    const reply = payload.reply || {};
    onProgress?.(reply.text || reply.card?.status || reply.task_status || 'processing', payload);

    if (reply.artifact_links?.[0] || reply.reply_type === 'artifact_link') return payload;
    if (['failed', 'cancelled'].includes(reply.task_status)) return payload;

    statusUrl = reply.card?.status_url || statusUrl;
    pollAfterSeconds = reply.card?.poll_after_seconds || pollAfterSeconds;
  }
  return null;
}

// 示例 D：浏览器 EventSource 只能 GET，推荐第三方服务端做一层代理。
// 浏览器：
const source = new EventSource(`/v3-stream-proxy?message_id=${encodeURIComponent(messageId)}`);
source.addEventListener('external_channel.delta', (event) => appendText(JSON.parse(event.data).delta));
source.addEventListener('external_channel.completed', (event) => renderFinal(JSON.parse(event.data)));
source.addEventListener('done', () => source.close());

// 第三方服务端代理逻辑：
// 1. 根据 message_id 取出原 POST 请求体；
// 2. 调用 DataMax POST /events/stream；
// 3. 把 DataMax 返回的 SSE 原样转发给浏览器；
// 4. 浏览器重连时带上最后 event_id，服务端转成 Last-Event-ID 或 stream_since_sequence。

event: external_channel.started
data: {"schema":"v3.external_channel.sse.v1","event_id":"pending:000000","sequence":0,"phase":"started","status":"started","display_text":"DataMax 已开始处理本轮消息。","idempotency_key":"generic_chat:tenant-ext-001:msg-20260513-0001","conversation_external_id":"chat-risk-room","data":{"status":"started","idempotency_key":"generic_chat:tenant-ext-001:msg-20260513-0001"}}

event: external_channel.delta
data: {"index":0,"delta":"根据你当前权限可查看的制度文档，"}

event: external_channel.completed
data: {"schema":"v3.external_channel.sse.v1","event_id":"arun_01HXEXAMPLE:000100","sequence":100,"phase":"completed","status":"completed","display_text":"本轮处理已返回当前结果。","assistant_run_id":"arun_01HXEXAMPLE","idempotency_key":"generic_chat:tenant-ext-001:msg-20260513-0001","conversation_external_id":"chat-risk-room","data":{"response":{"accepted":true,"reply":{"reply_type":"text","text":"根据你当前权限可查看的制度文档..."}}}}

event: done
data: {"ok":true}

POST
<path-with-query>
<x-v3-timestamp>
<x-v3-nonce>
<x-v3-content-sha256>

{
  "schema": "v3.external_channel.outbound_reply.v1",
  "event_type": "assistant_reply",
  "trigger": "async_result_completed",
  "source_event_name": "assistant_run.external_channel_static_page_publish_completed",
  "assistant_run_id": "assistant-run-id",
  "idempotency_key": "outbound:assistant-run-id:hash",
  "conversation_external_id": "conv-20260518-0001",
  "reply": {
    "target_conversation_external_id": "conv-20260518-0001",
    "reply_type": "artifact_link",
    "text": "已依据客户需求生成可访问的报表页面。\n\n页面链接：https://v3.elepcloud.com/...",
    "card": {
      "public_url": "https://v3.elepcloud.com/..."
    },
    "artifact_links": [
      "https://v3.elepcloud.com/..."
    ],
    "task_status": "static_page_published",
    "requires_confirmation": false,
    "action_id": null,
    "confirmation_id": null
  },
  "artifact_links": [
    "https://v3.elepcloud.com/..."
  ],
  "task_status": "static_page_published",
  "requires_confirmation": false
}

{
  "accepted": true,
  "assistant_run_id": "arun_01HXEXAMPLE",
  "idempotency_key": "generic_chat:tenant-ext-001:msg-20260513-0001",
  "reply": {
    "target_conversation_external_id": "chat-risk-room",
    "reply_type": "task_status",
    "task_status": "processing"
  }
}

GET /v1/external/runs/{assistant_run_id}

{
  "assistant_run_id": "arun_01HXEXAMPLE",
  "status": "completed",
  "created_at": "2026-05-13T12:00:01Z",
  "completed_at": "2026-05-13T12:00:05Z",
  "reply": {
    "reply_type": "text",
    "text": "根据你当前权限可查看的制度文档，本周采购审批需要重点关注三点..."
  }
}

POST /v1/external/channels/{connection_id}/confirmations
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "assistant_run_id": "arun_01HXEXAMPLE",
  "action_id": "external-action-001",
  "confirmation_external_id": "confirm-001",
  "sender_external_user_id": "user-10001",
  "decision": "approved",
  "comment": "确认提交审批。",
  "idempotency_key": "generic_chat:tenant-ext-001:confirm-001",
  "confirmed_at": "2026-05-13T12:03:00Z"
}

GET /documents

{
  "items": [
    {
      "document_external_id": "doc-001",
      "title": "采购审批制度",
      "document_type": "pdf",
      "revision": "rev-20260513-01",
      "updated_at": "2026-05-13T10:20:00Z",
      "deleted": false,
      "content_url": "https://third-party.example.com/documents/doc-001/content",
      "acl_url": "https://third-party.example.com/documents/doc-001/acl"
    }
  ],
  "next_cursor": "cursor-002"
}

GET /documents/{document_external_id}/content

GET /documents/{document_external_id}/acl

{
  "document_external_id": "doc-001",
  "revision": "rev-20260513-01",
  "acl_hash": "sha256:...",
  "captured_at": "2026-05-13T10:21:00Z",
  "allow": [
    { "subject_type": "user", "subject_external_id": "user-10001", "level": "read" },
    { "subject_type": "department", "subject_external_id": "dept-finance", "level": "read" },
    { "subject_type": "role", "subject_external_id": "role-procurement-admin", "level": "manage" }
  ],
  "deny": [
    { "subject_type": "user", "subject_external_id": "user-99999", "reason": "restricted" }
  ]
}

POST /v1/external/channels/{connection_id}/documents/parse
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "source_id": "third-party-source-main",
  "dataset_id": "0f2f7b19-58ab-4b2b-9a8f-cc38bfbf8c9d",
  "dataset_external_id": "dataset-third-party-main",
  "dataset_title": "第三方资料库",
  "document_external_id": "doc-001",
  "revision_external_id": "rev-20260515-01",
  "title": "采购审批制度.docx",
  "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "content_url": "https://third-party.example.com/download/doc-001?expires=short",
  "metadata": {
    "business_category": "procurement"
  },
  "idempotency_key": "third-party-source-main:doc-001:rev-20260515-01"
}

GET /v1/external/channels/{connection_id}/documents/{document_external_id}/parse-detail?source_id={source_id}
Authorization: Bearer <DataMax inbound token>

PATCH /v1/external/channels/{connection_id}/documents/{document_external_id}/dataset
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "source_id": "third-party-source-main",
  "dataset_external_id": "dataset-third-party-archive",
  "dataset_title": "第三方归档资料库",
  "revision_external_id": "rev-20260515-01"
}

{
  "source_id": "hy-sql-traffic-area",
  "connector_kind": "mysql",
  "display_name": "hy_sql 区域经营库",
  "database_source": {
    "kind": "mysql",
    "database": "hy_sql",
    "connection_env": "THIRD_PARTY_HY_SQL_DATABASE_URL",
    "default_dataset_id": "31588c60-0885-47c4-81fe-4ff5c27de8e7",
    "row_limit": 5000,
    "tables": [{
      "table": "bi_contract_warning",
      "id_column": "parentcode",
      "id_columns": ["parentcode", "storecode", "txdate"],
      "title_column": "dist_name",
      "content_columns": ["shopdesc", "catgldesc", "dist_name"],
      "metadata_columns": ["storecode", "brandcode", "txdate"],
      "updated_at_column": "txdate",
      "object_type": "document",
      "content_type": "text/markdown"
    }]
  }
}

POST /v1/external/channels/{connection_id}/database-sources
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "source_external_id": "db-20260601-0001",
  "name": "生产经营库",
  "connector_kind": "mysql",
  "connection_env": "THIRD_PARTY_DB_MAIN_URL",
  "connection_url": null,
  "username": null,
  "password": null,
  "database": "hy_sql",
  "tables": ["bi_traffic_area"],
  "dataset_external_id": "xinbai-operating-analysis",
  "dataset_title": "新百经营分析数据集",
  "idempotency_key": "datasource:db-20260601-0001"
}

{
  "accepted": true,
  "source_external_id": "db-20260601-0001",
  "source_id": "db-20260601-0001",
  "source": {
    "id": "db-20260601-0001",
    "name": "生产经营库",
    "connector_kind": "mysql",
    "status": "ready"
  },
  "redacted_summary": {
    "kind": "mysql",
    "database": "hy_sql",
    "connection_env": "THIRD_PARTY_DB_MAIN_URL",
    "table_count": 0,
    "tables": []
  },
  "credential_status": "ready",
  "warnings": []
}

POST /v1/external/sources/{source_id}/database/test
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "database_source": {}
}

POST /v1/external/sources/{source_id}/database/schema
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "database_source": {}
}

{
  "source_id": "hy-sql-traffic-area",
  "connector_kind": "mysql",
  "redacted_summary": {},
  "schema": {
    "database": "hy_sql",
    "table_count": 2,
    "tables": [{
      "table": "bi_contract_warning",
      "column_count": 18,
      "approximate_row_count": 12000,
      "columns": [{
        "name": "storecode",
        "data_type": "varchar",
        "nullable": true
      }]
    }]
  }
}

POST /v1/external/sources/{source_id}/database/preview
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "table": "bi_contract_warning",
  "limit": 20,
  "database_source": {}
}

POST /v1/external/sources/{source_id}/database/profile
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "sample_limit": 100,
  "database_source": {}
}

{
  "source_id": "hy-sql-traffic-area",
  "connector_kind": "mysql",
  "redacted_summary": {},
  "profile": {
    "database": "hy_sql",
    "table_count": 2,
    "metric_count": 12,
    "dimension_count": 18,
    "tables": [{
      "table": "bi_contract_warning",
      "approximate_row_count": 12000,
      "metric_count": 8,
      "dimension_count": 10,
      "time_dimension_count": 1,
      "entity_column_count": 4,
      "text_column_count": 3,
      "mapping_confidence": 0.86
    }]
  }
}

POST /v1/external/sources/{source_id}/database/apply-profile
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "sample_limit": 100,
  "tables": ["bi_contract_warning"],
  "dry_run": true,
  "database_source": {}
}

POST /v1/external/sources/{source_id}/database/aggregate
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "table": "bi_contract_warning",
  "dimensions": ["dist_name", "txdate"],
  "metric": "quekou",
  "aggregation": "sum",
  "limit": 50,
  "scan_limit": 5000,
  "database_source": {}
}

POST /v1/external/sources/{source_id}/sync
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "sync_kind": "incremental",
  "dataset_id": "31588c60-0885-47c4-81fe-4ff5c27de8e7",
  "dataset_external_id": "xinbai-operating-analysis",
  "dataset_title": "新百经营分析",
  "checkpoint": {
    "txdate_after": "2026-05-01"
  },
  "connector_context": {
    "database_source": {
      "tables": [{
        "table": "bi_contract_warning"
      }]
    }
  }
}

{
  "accepted": true,
  "source_id": "hy-sql-traffic-area",
  "sync_run_id": "sync-20260531-0001",
  "sync_kind": "incremental",
  "status": "queued",
  "workflow_execution": {
    "id": "workflow-execution-id",
    "status": "running"
  },
  "enqueued_tasks": []
}

GET /v1/external/channels/{connection_id}/database-sources/{source_external_id}/status
Host: v3.elepcloud.com
Authorization: Bearer <DataMax inbound token>

{
  "source_id": "hy-sql-main",
  "connector_kind": "mysql",
  "redacted_summary": {
    "kind": "mysql",
    "database": "hy_sql",
    "connection_env": "THIRD_PARTY_HY_SQL_DATABASE_URL",
    "default_dataset_id": "5af2f8a6-0d3c-4a12-a77a-333333333333",
    "table_count": 1,
    "tables": ["bi_traffic_area"]
  },
  "status": {
    "config_valid": true,
    "dataset": {
      "dataset_id": "5af2f8a6-0d3c-4a12-a77a-333333333333",
      "key": "external-source-hy-sql-main-dataset-workspace-main",
      "title": "HY SQL 主数据集",
      "lifecycle": "active",
      "is_default": false,
      "dataset_external_id": "workspace-main"
    },
    "datasets": [{
      "dataset_id": "5af2f8a6-0d3c-4a12-a77a-333333333333",
      "key": "external-source-hy-sql-main-dataset-workspace-main",
      "title": "HY SQL 主数据集",
      "is_default": false,
      "dataset_external_id": "workspace-main",
      "document_count": 20,
      "indexed_document_count": 20,
      "indexed_chunk_count": 20,
      "retrieval_evidence_count": 20,
      "readiness": {
        "signal": "ready"
      }
    }],
    "dataset_readiness": {
      "signal": "ready",
      "document_count": 20,
      "indexed_document_count": 20,
      "indexed_chunk_count": 20
    },
    "table_readiness": [],
    "recent_sync_runs": [],
    "sync_readiness": {
      "signal": "ready",
      "status": "succeeded",
      "row_count": 20,
      "failed_row_count": 0,
      "row_failure_groups": []
    },
    "semantic_profile": {},
    "health_findings": {
      "signal": "ok",
      "items": []
    }
  }
}

POST /v1/external/channels/{connection_id}/events
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "platform": "generic_chat",
  "tenant_external_id": "tenant-ext-001",
  "bot_external_id": "bot-v3",
  "conversation_external_id": "conv-db-001",
  "sender_external_id": "user-10001",
  "message_external_id": "msg-db-001",
  "message_type": "text",
  "text": "按门店和品牌生成本月经营风险报表。",
  "default_prompt": "优先基于已同步数据库数据回答。",
  "output_format": "rich_text",
  "render_mode": "artifact",
  "artifact_type": "static_page",
  "business_datasource_ids": [
    "db-20260601-0001"
  ],
  "dataset_external_ids": [
    "xinbai-operating-analysis"
  ],
  "requested_skills": [],
  "idempotency_key": "third-party:tenant-ext-001:msg-db-001",
  "received_at": "2026-05-31T10:00:00Z"
}

GET /users
GET /departments
GET /groups
GET /roles
GET /users/{user_external_id}/memberships

{
  "items": [
    {
      "user_external_id": "user-10001",
      "display_name": "张三",
      "email": "zhangsan@example.com",
      "mobile": "+86-13800000000",
      "status": "active",
      "department_external_ids": ["dept-finance"],
      "group_external_ids": ["group-procurement"],
      "role_external_ids": ["role-requester"],
      "updated_at": "2026-05-13T09:00:00Z"
    }
  ],
  "next_cursor": null
}

{
  "text": "根据本轮经营数据和模板生成经营分析静态页",
  "artifact_type": "static_page",
  "template": {
    "source_id": "third-party-source-main",
    "document_external_id": "tpl-xinbai-static-page",
    "revision_external_id": "v1",
    "mode": "reference",
    "output_type": "static_page"
  },
  "dataset_external_ids": ["workspace-operating-data"],
  "available_document_external_ids": ["doc-operating-data-001"]
}

GET /v1/external/channels/{connection_id}/assistant-runs/{assistant_run_id}/reply
Host: v3.elepcloud.com
Authorization: Bearer <DataMax inbound token>

{
  "direct_html": true,
  "background": false
}

GET /v1/external/channels/{connection_id}/static-page-renders/{render_output_id}
Host: v3.elepcloud.com
Authorization: Bearer <DataMax inbound token>

GET /v1/external/channels/{connection_id}/static-page-renders/{render_output_id}/preview
Host: v3.elepcloud.com
Authorization: Bearer <DataMax inbound token>

GET /v1/external/channels/{connection_id}/static-page-renders/{render_output_id}/download
Host: v3.elepcloud.com
Authorization: Bearer <DataMax inbound token>

POST /v1/external/artifacts/{artifact_id}/publish
POST /v1/external/artifacts/{artifact_id}/revoke

POST /artifacts
POST /artifacts/{artifact_external_id}/revoke

{
  "action_id": "act-artifact-001",
  "assistant_run_id": "00000000-0000-0000-0000-000000000001",
  "action_type": "external_artifact.publish",
  "risk_level": "low_risk_write",
  "target_system": "third_party_artifact_api",
  "arguments_redacted": {
    "artifact_ref": "artifact-001",
    "target_system": "customer-portal",
    "visibility": "source_acl"
  },
  "confirmation_state": "not_required",
  "requester_summary": {
    "platform": "generic_chat",
    "tenant_external_id": "tenant-ext-001",
    "conversation_external_id": "chat-risk-room",
    "sender_external_id": "user-ext-001"
  },
  "raw_arguments_included": false
}

{
  "artifact_id": "artifact-001",
  "artifact_type": "report",
  "title": "采购审批风险分析",
  "owner_external_user_id": "user-10001",
  "visibility": "same_as_source_permissions",
  "download_url": "https://datamax.example.com/artifacts/artifact-001",
  "expires_at": "2026-06-13T00:00:00Z",
  "idempotency_key": "artifact:artifact-001:publish"
}

{
  "action_id": "act-001",
  "assistant_run_id": "arun-001",
  "action_type": "ticket.update_priority",
  "risk_level": "high_risk_write",
  "target_system": "ticketing",
  "confirmation_state": "confirmed",
  "arguments_redacted": {
    "ticket_id": "T-1001",
    "priority": "high"
  },
  "requester_summary": {
    "platform": "generic_chat",
    "tenant_external_id": "tenant-001",
    "conversation_external_id": "chat-risk-room",
    "sender_external_id": "user-a"
  },
  "raw_arguments_included": false
}

POST /v1/external/channels/{connection_id}/actions/{action_id}/result
Host: v3.elepcloud.com
Content-Type: application/json
Authorization: Bearer <DataMax inbound token>

{
  "external_request_id": "gateway-req-001",
  "status": "succeeded",
  "idempotency_key": "generic_chat:tenant-ext-001:result-001",
  "completed_at": "2026-05-14T10:30:00Z",
  "code": "OK",
  "message": "可选说明文本。DataMax 只记录 message 是否存在。",
  "result": {
    "artifact_id": "artifact-001",
    "status": "created"
  }
}

Authorization: Bearer <dispatch token>
X-V3-Connection-Id: generic-chat-main
X-V3-Timestamp: 2026-05-14T09:30:00Z
X-V3-Nonce: 01HX...
X-V3-Content-SHA256: <JSON 原始请求体的 sha256 hex>
X-V3-Signature: sha256=<HMAC-SHA256 hex>

{
  "reply_type": "text",
  "text": "根据你当前权限可查看的文档，本周采购审批需要关注以下三点：..."
}

{
  "reply_type": "requires_confirmation",
  "confirmation_id": "confirm-001",
  "title": "是否创建采购审批跟进工单？",
  "summary": "DataMax 将在第三方工单系统中创建一条普通优先级工单。",
  "risk_level": "medium",
  "actions": ["approve", "reject"]
}

GET /v1/external/integrations

GET /v1/external/integrations/{integration_id}/audit

GET /v1/external/integrations/generic-chat-main/audit?item_type=action&action_state=result_callback

GET /v1/external/integrations/generic-chat-main/audit?item_type=search_evidence

GET /v1/external/integrations/generic-chat-main/audit?item_type=action&action_id=act-001&limit=1

POST /v1/external/integrations/{integration_id}/retry

POST /v1/external/integrations/{integration_id}/disable

POST /v1/external/integrations/{integration_id}/rotate-secret

{
  "code": "external_channel_connection_not_found",
  "message": "未找到对应的第三方聊天通道连接。",
  "details": {
    "field": "connection_id"
  }
}