AI 能力总览
ApiGo 把 AI 能力分为四条主线：AI 问数（自然语言查数据）、AI 助手（多轮对话与操作确认）、AI 调用日志（审计与成功率）。本文给出整体关系，具体操作见各专题页。
能力地图
| 能力 | 面向对象 | 详细说明 |
|---|---|---|
| AI 问数 | 平台使用者 | AI 问数与 SQL 分析 |
| 智能助理对话 | 平台使用者 | 本文「智能助理」 |
| 调用日志与成功率 | 管理员 | AI 调用日志 |
AI 问数
用自然语言描述数据需求，系统结合语义层生成 SQL、执行查询并渲染图表：
- 选择项目与数据源，输入业务问题。
- 编排器解析意图，匹配场景与语义术语/指标。
- 生成 SQL，经过只读校验后执行。
- 结果以表格或图表返回，可继续追问。
AI 问数只允许只读查询。写操作、DDL、多语句等会被拦截；SQL 生成失败时会尝试自动修复，仍失败则返回可读的错误说明。完整流程与限制见 AI 问数与 SQL 分析。
智能助理
智能助理是平台内的对话式入口，采用 SSE 流式返回，支持多轮上下文。与普通问答不同，它可以：
- 调用平台工具查询接口、数据源、日志等资源；
- 在需要写入或高风险操作时生成确认卡片，由用户确认后才执行；
- 展示执行轨迹（Trace），包括每次工具调用、SQL、耗时与结果摘要；
- 按场景路由到不同的能力集，例如问数场景、运维场景、接口开发场景。
会话状态保存在 base_ai_agent_session_state，因此刷新页面或分多轮回复后仍能继续未完成的确认流程。
MCP 接入
平台提供两套 MCP 服务，协议均为 JSON-RPC 2.0 / MCP 2025-06-18：
| 入口 | 地址 | 鉴权 | 工具来源 |
|---|---|---|---|
| 应用 MCP | /mcp/{appCode} | X-AppKey | 已发布、认证方式为 app_key、发布协议包含 MCP 的接口 |
| 管理端 MCP | /api/box/mcp/{agentCode} | X-Agent-Key | 管理工具集（查询与管理平台资源） |
工具映射规则
接口要被外部 MCP 客户端看到，必须同时满足：
- 发布协议包含
MCP； - 已发布到
prod环境且处于上线状态； - 认证方式为
app_key； - 调用凭证已获得该接口权限；
- 应用的
mcpEnabled = 1。
工具的 name 优先取接口定义的 toolName，为空时使用 skillCode，再为空时按路径生成。工具描述来自接口文档与参数定义。
支持的方法
| 方法 | 处理位置 | 说明 |
|---|---|---|
initialize | 网关 | 返回协议版本与服务器能力 |
notifications/initialized | 网关 | 客户端初始化完成通知，无响应 |
tools/list | 网关 | 返回当前凭证可用的工具清单 |
tools/call | 执行链路 | 转换为 REST 运行时调用，经过认证、限流、IP、缓存与日志 |
MCP 只接受 POST；GET 返回 405。详见 MCP 接入。
受控访问模型
AI 不是绕过治理的旁路，所有能力都经过同一套边界：
- 数据隔离：会话、语义层、数据源均绑定项目，跨项目不可见。
- 只读优先：问数只执行查询；写操作需要显式确认或专属工具权限。
- 工具白名单：智能体只能调用已绑定的工具，读写工具分开授权。
- 完整审计：每次问答、工具调用、SQL 执行都写入 AI 审计日志，包含耗时、Token 与成功状态。
- 失败可追踪：失败原因按场景归类，成功率报表按场景与失败原因聚合。