hex

用途

Hex 是一个内部数据访问原语（Internal data access primitive），单一职责是：通过 MCP 执行一次 Hex 查询，轮询等待其完成，并返回与调用方提供的模式（pattern）相匹配的结构化结果。它由核心技能（core skills）调用，不面向直接使用。

Hex Threads 运行通常需要几分钟，因此该技能负责完整的 create → poll → extract 周期。

主要能力

接收调用方传入的三项输入：query（发送给 Hex 的完整、自包含提示）、pattern（目标数据的样子，如字段名、预期结构，由调用方提供，不得自行假设）、context（查询的标识性上下文，如账户名、实体 ID、时间范围）。
调用 create_thread 创建 Hex 线程。
调用 get_thread 轮询线程状态，约每 20 秒轮询一次，最多重试 10 次，直至状态为 IDLE。
线程达到 IDLE 后读取响应内容，依据调用方提供的 pattern 定位并提取目标值。
返回结构化输出，状态为 found、not_found、timeout 或 error。

使用方式

提示词构建（创建线程前必读）

Hex 的 Threads Agent 完全依据提示词决定查询哪些表、运行什么 SQL。模糊的提示会导致大范围表探索并显著拖慢响应；精确的提示可缩短数分钟查询时间。规则包括：

将所有内容批量放入一个提示。把调用方需要的每个指标和数据点都放进单次 create_thread 调用。不要用 continue_thread 获取额外字段——每次调用都会重新触发完整 agent 流水线并增加数分钟延迟。仅当初始响应中确实缺少某个被请求的数据点时，才将 continue_thread 作为最后手段。
锚定具体实体标识符。始终包含被查询实体的主键或标识符（如 account ID、org slug、user ID、opportunity ID），不要依赖 Hex 仅凭名称或描述推断实体。
使用精确的字段和表术语。使用调用方数据模型中的规范列名、表名和指标名；若调用方提供了已知列名，将其包含在提示中。
明确指定时间窗口。始终说明周期，如“过去 28 天”“从某日期到今天”“过去 6 个月按月”。
请求结构化输出。每个提示结尾加上：“Return results in a structured list or table.”
有原始 SQL 时直接传入。当调用方提供具体 SQL 查询时，直接传给 create_thread，agent 会原样执行，比自然语言探索更快。

自然语言查询示例：

"For account ID '12345': return (1) total revenue for the last 90 days, (2) number of active users this month, and (3) any plan or subscription changes in the last 30 days. Return results in a structured list."

原始 SQL 查询示例：

"Run this SQL: SELECT id, name, revenue, created_at FROM my-project.dataset.orders WHERE account_id = '12345' AND created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 90 DAY) ORDER BY created_at DESC"

执行步骤

创建 Hex 线程：调用 create_thread 并传入完整构建的提示。若调用失败（网络错误、认证错误），立即返回 status: "error" 及错误信息。
轮询完成：调用 get_thread 检查线程状态；每次轮询间隔约 20 秒；最多重试 10 次；状态非 IDLE（仍在处理）时继续轮询。若 10 次重试后仍未 IDLE，返回：

{ "status": "timeout", "value": null, "source": "Hex", "raw": "Hex query did not complete after 10 polling attempts." }

提取结果：线程达到 IDLE 后读取响应内容，依据调用方提供的 pattern 推理并提取目标值。
仅在最后手段使用 continue_thread：若某个确实被请求的数据点在响应中完全缺失（不只是未标注或格式不同），使用一次 continue_thread 专门询问它，之后重新提取。不要用它请求调用方原始查询中未包含的额外数据——那属于调用方侧错误。
返回结构化输出，匹配成功时：

{ "status": "found", "value": "<extracted value(s) matching the pattern>", "source": "Hex", "raw": "<full thread response for debugging>" }

无匹配时：

{ "status": "not_found", "value": null, "source": "Hex", "raw": "<full thread response for debugging>" }

约束

不要硬编码数据格式或字段名——pattern 来自调用方。
不要超出此处定义的 10 次轮询上限。
不要把部分结果当作成功返回——若模式匹配失败，返回 not_found。
不要调用其他技能或数据源——这是单一来源原语。
不要捏造数据。若 Hex 返回空或含糊结果，返回 not_found 并附原始输出供调用方检查。
不要把 continue_thread 当作标准后续机制——它开销大，每次查询最多使用一次，且仅当初始响应中确实缺少被请求的数据点时使用。

护栏

认证与错误处理

若 create_thread 返回认证错误（401/403 或 OAuth 失败），立即停止并返回 status: "error"——不要重试认证失败。
若 create_thread 返回瞬时错误（网络超时、5xx），重试一次；若重试仍失败，返回错误状态。
绝不向最终用户暴露原始 Hex API 错误信息。概括失败模式（认证、超时、未找到），不泄露内部细节。

查询安全

不执行写操作。Hex 线程是只读分析查询。若提示暗示变更（INSERT、UPDATE、DELETE），拒绝并返回错误。
不将原始用户输入直接作为 Hex 提示传入。始终将输入模板化到调用方查询定义的结构化格式中。

速率限制

将 get_thread 轮询限制为每个线程 10 次调用，不得超出——超出则返回 status: "timeout"。
不要递归链式调用此技能。一次调用处理一次查询。

适用场景

适用于核心技能需要从 Hex 获取数据、且调用方已提供明确查询提示、目标数据模式与上下文标识的场景。由于它是内部原语，不面向终端用户直接使用。

限制

仅支持只读分析查询，不支持任何写操作。
轮询有 10 次上限，超时即返回 timeout。
不调用其他技能或数据源。
不硬编码字段名或数据格式，全部依赖调用方提供的 pattern。
关于收费、价格、平台支持范围等信息，资料中暂未提供。