ADBAgent OpenAPI 使用指南

请求示例

curl -s "$BASE/api/v1/sessions" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

返回字段：

响应示例：

{
  "sessions": [
    {
      "sessionId": "ses_xxxxx",
      "title": "我的分析任务",
      "model": "adb-qwen3.5-plus/qwen3.5-plus",
      "createdAt": "2026-01-01T10:00:00.000Z",
      "updatedAt": "2026-01-01T12:00:00.000Z"
    }
  ]
}

请求参数

请求示例

curl -s "$BASE/api/v1/sessions/$SID/messages?limit=50" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

返回字段：

响应示例：

{
  "messages": [
    {
      "id": "msg_xxxxx",
      "role": "user",
      "content": "查询本月销量最高的产品",
      "model": null,
      "createdAt": "2026-01-01T10:00:00.000Z"
    },
    {
      "id": "msg_yyyyy",
      "role": "assistant",
      "content": "根据分析结果...",
      "model": "adb-qwen3.5-plus/qwen3.5-plus",
      "createdAt": "2026-01-01T10:00:03.000Z"
    }
  ]
}

请求示例

curl -s -X POST "$BASE/api/v1/sessions/$SID/abort" \
  -H "Authorization: Bearer $TOKEN"

响应说明

成功时返回 HTTP 204，无响应体。

请求示例

curl -s -X DELETE "$BASE/api/v1/sessions/$SID" \
  -H "Authorization: Bearer $TOKEN"

响应说明

成功时返回 HTTP 204，无响应体。

请求示例

curl -s "$BASE/api/v1/sessions/$SID/rounds/$RID" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

返回字段：

响应示例：

{
  "roundId": "rnd_msg_xxxxx",
  "status": "completed",
  "question": "查询本月销量最高的产品",
  "answer": "根据分析结果...",
  "model": "adb-qwen3.5-plus/qwen3.5-plus",
  "duration": 3200
}

轮询示例脚本

以下脚本实现了自动轮询逻辑（建议间隔 2 秒）：

poll_round() {
  local sid=$1 rid=$2
  while true; do
    RESP=$(curl -s "$BASE/api/v1/sessions/$sid/rounds/$rid" \
      -H "Authorization: Bearer $TOKEN")
    STATUS=$(echo "$RESP" | jq -r '.status')
    case $STATUS in
      completed)
        echo "$RESP" | jq '{question, answer, model, duration}'
        return 0 ;;
      error)
        echo "$RESP" | jq '{question, answer, status}'
        return 1 ;;
      *)
        sleep 2 ;;
    esac
  done
}

# 用法：发送提问并等待结果
RID=$(curl -s -X POST "$BASE/api/v1/sessions/$SID/prompt" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"分析最近7天的用户活跃趋势"}' | jq -r '.roundId')
poll_round "$SID" "$RID"

前端对接示例

以下 JavaScript 示例展示如何使用 text 格式的 SSE 事件流：

async function streamChat(base, token, sessionId, question) {
  const controller = new AbortController();

  // 1. 订阅事件流
  const eventRes = await fetch(
    `${base}/api/v1/sessions/${sessionId}/events?format=text`,
    {
      headers: { 'Authorization': `Bearer ${token}` },
      signal: controller.signal
    }
  );

  // 2. 发送提问
  await fetch(`${base}/api/v1/sessions/${sessionId}/prompt`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text: question })
  });

  // 3. 读取事件流
  const reader = eventRes.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
  let answer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    const chunks = buffer.split('\n\n');
    buffer = chunks.pop() ?? '';

    for (const chunk of chunks) {
      const dataLine = chunk.split('\n')
        .find(l => l.startsWith('data:'));
      if (!dataLine) continue;
      const event = JSON.parse(dataLine.slice(5).trim());

      if (event.type === 'delta') {
        answer += event.content ?? '';
        console.log(event.content);  // 实时输出
      } else if (event.type === 'done') {
        controller.abort();
        return answer;
      } else if (event.type === 'error') {
        throw new Error(event.message);
      }
    }
  }
  return answer;
}

请求示例

curl -s "$BASE/api/v1/sessions/$SID/model" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

返回字段：

响应示例：

{
  "sessionId": "ses_xxxxx",
  "model": "adb-qwen3.5-plus/qwen3.5-plus",
  "globalDefault": "adb-qwen3.5-plus/qwen3.5-plus",
  "effective": "adb-qwen3.5-plus/qwen3.5-plus"
}

请求参数

请求示例

curl -s -X POST "$BASE/api/v1/sessions/$SID/model" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"adb-qwen3.5-plus/qwen3.5-plus"}' | jq .

响应说明

响应示例：

{
  "sessionId": "ses_xxxxx",
  "model": "adb-qwen3.5-plus/qwen3.5-plus",
  "message": "Model updated successfully"
}

请求示例

curl -s "$BASE/api/v1/datasources" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

返回字段：

响应示例：

{
  "data_sources": [
    {
      "name": "adb_mysql_default",
      "type": "adb_mysql",
      "description": "",
      "enabled": true,
      "configured": true,
      "gateway_status": "running",
      "connection": {
        "host": "xxx",
        "port": 3306,
        "user": "xxx",
        "database": "xxx"
      }
    }
  ]
}

请求示例

curl -s "$BASE/api/v1/datasources/adb_mysql_default" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

响应字段与"列出所有数据源"相同，额外包含 pool 对象（含 init_timeout_ms、query_timeout_ms、max_restart_count）。

请求示例

curl -s "$BASE/api/v1/datasources/adb_mysql_default/databases" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

响应示例：

{
  "databases": ["INFORMATION_SCHEMA", "my_database", "analytics_db"]
}

请求示例

curl -s "$BASE/api/v1/datasources/adb_mysql_default/my_database/tables" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

响应示例：

{
  "tables": ["orders", "users", "products"]
}

请求参数

请求示例

curl -s -X POST "$BASE/api/v1/datasources" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_datasource",
    "type": "adb_mysql",
    "connection": {
      "host": "xxx.xxx.xxx.xxx",
      "port": 3306,
      "user": "db_user",
      "password": "db_password",
      "database": "my_database"
    }
  }' | jq .

响应说明

成功时返回创建的数据源对象，结构与"列出所有数据源"中的元素相同。

请求示例

curl -s -X PUT "$BASE/api/v1/datasources/my_datasource" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": {
      "host": "new-host.xxx.xxx",
      "port": 3306,
      "user": "new_user",
      "password": "new_password",
      "database": "new_database"
    }
  }' | jq .

响应说明

成功时返回更新后的数据源对象。

请求示例

curl -s -X DELETE "$BASE/api/v1/datasources/my_datasource" \
  -H "Authorization: Bearer $TOKEN"

响应说明

成功时返回 HTTP 204，无响应体。

请求参数

请求示例

curl -s "$BASE/api/v1/skills?includeGlobal=true" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

返回字段：

响应示例：

{
  "skills": [
    {
      "name": "alibabacloud-analyticdb-mysql-copilot",
      "description": "ADB MySQL 数据库 AI 助手",
      "scope": "project",
      "builtIn": true,
      "permission": "allow"
    }
  ]
}

请求示例

curl -s "$BASE/api/v1/skills/my-custom-skill" \
  -H "Authorization: Bearer $TOKEN" | jq .

响应说明

响应字段与"列出已安装技能"相同，额外包含 content（SKILL.md 完整内容）和 trigger（触发条件）字段。

请求参数

请求示例

curl -s -X POST "$BASE/api/v1/skills" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "adb-sql-review",
    "description": "ADB MySQL SQL 审查技能",
    "content": "# ADB SQL Review\n\n## When to use\n适用于 SQL 性能审查。\n\n## Rules\n1. 检查 SELECT *\n2. 检查缺少 WHERE 子句\n"
  }' | jq .

响应说明

响应示例：

{
  "name": "adb-sql-review",
  "action": "added",
  "path": "/path/.opencode/skills/adb-sql-review/SKILL.md"
}

action 字段值为 added（新建）或 updated（更新）。

请求参数

请求示例

curl -s -X PATCH "$BASE/api/v1/skills/adb-sql-review/permission" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permission": "deny"}' | jq .

响应说明

成功时返回更新后的技能对象。

请求示例

curl -s -X POST "$BASE/api/v1/skills/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/tmp/adb-sql-review.zip" | jq .

响应说明

成功时返回安装的技能对象。/api/v1/skills/install 与 /api/v1/skills/upload 功能相同，两个端点均可使用。

请求示例

curl -s -o adb-sql-review.zip \
  "$BASE/api/v1/skills/adb-sql-review/download" \
  -H "Authorization: Bearer $TOKEN"

响应说明

成功时返回 HTTP 200，响应体为 ZIP 文件（application/zip）。

请求示例

curl -s -X DELETE "$BASE/api/v1/skills/adb-sql-review" \
  -H "Authorization: Bearer $TOKEN"

响应说明

成功时返回 HTTP 204，无响应体。