用途
本技能用于从智能体查询当前 Auto Ontology 实现，并对生成的 SQL、返回行和答案进行验证，不强制使用特定的 harness、SDK 或 LangGraph 模板。类型化的工作流产物、状态、门控和交接信息记录在 runtime-contract.yaml 中。
主要能力
- 通过 MCP 或经过认证的 Next.js REST 网关访问 Auto Ontology。
- 在提问前调用 check_readiness 确认语义层已编译且数据库连接可用。
- 使用 search_terms 发现术语在语义层中的含义。
- 使用 check_answerable 做低成本覆盖检查。
- 使用 ask_question 发起完整文本到 SQL 查询，返回答案、SQL 和行数据（上限 100 行，附带 row_count / truncated 信息）。
- 对结论性答案，依据 query-validation.md 校验实质意图、生成的 SQL、返回行、截断和文字描述。
- 通过 REST 回退路径进行术语发现：GET /api/terms、GET /api/terms/{term_id}、GET /api/exploration/tables/{table_id}/details、GET /api/exploration/graph。
- 支持聊天接口 POST /api/chat/completions，使用 SSE 返回 step / result / error / charts，最后以 [DONE] 结束。
使用方式
优先使用 MCP：当运行环境支持 MCP 时，连接 auto-ontology-mcp，客户端指向 …/mcp，由用户登录；MCP 服务器上不放置令牌。握手工具列表是实时事实来源（mcp/auto_ontology_mcp/tools.py），若握手信息与本技能描述冲突，以握手为准。典型顺序为 check_readiness → search_terms → check_answerable → ask_question。
REST 回退：当 MCP 不可用时，公共客户端调用经过认证的 Next.js 网关，而不是 FastAPI :3001。FastAPI 信任 x-auto-ontology-user-id 头，不应直接暴露。直接请求 FastAPI 时，不带 conversation_id 为无状态；带 conversation_id 则需要该内部头。认证方式支持浏览器会话 cookie、API token（x-api-key 或 Authorization: Bearer 用于 auto_ontology_… 令牌）、Auto Ontology 签发的 OAuth bearer（MCP 登录）、SSO id token（Authorization: Bearer <jwt>）。API 形状见 docs/openapi/auto-ontology-api.json，不要抓取全部约 87 个操作。写请求应移交 nvidia-ontology-management，本技能不会将只读问题转为变更操作。
聊天使用：POST /api/chat/completions 需要 chat:use 权限；带 conversation_id 的请求还需要 conversation:write，否则返回 403。省略 conversation_id 可获得一次性回答（无历史、无图表步骤）。提供客户端生成的 UUID 可创建或继续线程（需要 chat:use 和 conversation:write）。在进入下一轮前等待 [DONE]；重叠请求会返回 409 Conversation in progress。会话 id 返回 404 表示属于其他用户。API 创建的线程可在 UI 中以 /chat?focus=<conversation_id> 打开（当属于当前登录用户时）。
Python 示例（来自 Auto Ontology README，无额外 SDK）：
import os
import requests
session = requests.Session()
session.headers["x-api-key"] = os.environ["AUTO_ONTOLOGY_API_TOKEN"]
terms = session.get("https://ontology.example.com/api/terms").json()
answer = session.post(
"https://ontology.example.com/api/chat/completions",
json={"question": "How many orders shipped last week?"},
)
# response is SSE, not a single JSON object
适用场景
- 需要基于 Auto Ontology 语义层获得有依据的答案，并对 SQL 和返回行进行验证。
- 在 MCP 环境中进行语义层探索和受控问答。
- 需要通过 REST 回退路径查询术语和聊天接口。
- 需要检查 Auto Ontology 就绪状态、认证状态和会话管理。
限制
本技能只读取和验证答案，不直接暴露 FastAPI，不写入语义定义，不发布治理结果，也不提供原始模式浏览器。表变更和发布操作应移交 nvidia-ontology-management。不要将成功执行视为充分证据；在呈现决策性结果前，必须按 query-validation.md 检查总体、度量、单位、粒度、连接、血缘、状态、有效性、行、截断和答案文字。若无法验证某实质约束，应返回缺口而非更强断言。空或失败的答案应先检查就绪状态或编译状态，再改写问题。