allium-investigation

Allium 调查

将其用于限定范围的调查，而非当前价格或余额查询。其输出应是一个结论，供他人检查、复跑和质疑。

直接使用 Allium MCP 工具——run_sql_query、get_query_run_results、 create_explorer_query、search_terminal、get_terminal_results、search_schemas、 search_docs——而不要只描述查询会显示什么。如果无法使用 MCP，请改用 allium-data 技能 / CLI。

输出要求

首先说明决策问题、调查对象、时间范围、网络和拟议指标。如果其中任何一项会实质性改变答案，请在查询前询问。

最后给出答案及直接支持答案的证据，并清楚标明解读和未解决的不确定性。如果结果将被分享、复用或用于决策，请按下方第 7 步收尾——将关键查询保存到 Explorer——不要只把证据留在聊天记录中。

调查工作流

1. 从头调查前先检查 Terminal

Allium 团队可能已经构建并维护了相关答案。在编写任何 SQL 之前，使用实体 / 指标 / 协议调用 search_terminal——这是仅搜索元数据的操作（仪表板标签、路径、类别、标签），不产生计算费用。如果某个仪表板看起来相关，使用其 dashboard_id 调用 get_terminal_results（不传 chart_id）以查看图表清单；然后再传入 chart_id 调用一次，以获取其 SQL 和 / 或最新的预计算数据行——此操作也不消耗计算单元，因为它仅读取现有定义和结果。如果它能直接回答问题，请引用它（对于预计算数据行，注明 result.queried_at），并链接到该仪表板，而不是从原始表重新推导相同内容。如果它接近但不完全符合，它仍比从零开始更适合作为起点——调整其 SQL，而不是推倒重来。

2. 选定数据源后再确定方法

如果 Terminal 仪表板未能直接回答问题，接下来运行 data-matching——它会定义数据契约，将候选表 / 端点与之比较，并通过 search_schemas / search_docs 使用有界查询验证覆盖情况。不要猜测表名，也不要仅仅因为某条链出现在列表中就推断数据覆盖；仅有目录条目并不代表已覆盖。选定数据源后，先确定原生网络，并将其与桥接或封装形式区分开来，再继续操作。

3. 编写数据计划

在主查询之前，记录：

• 指标定义和分母；
• 纳入、排除及实体归属规则；
• 时间粒度和时区；
• 可能推翻预期解读的检查项。

将其视为一个假设。如果发现的架构或首个结果与之不符，请修订计划。

4. 从小规模测试构建生产查询

对于小样本量、基数和单位检查，请使用 run_sql_query——它明确是临时的（不会保存，也不能用于图表或仪表板），正适合一次性检查。它会立即返回一个 run_id；使用该 run_id 调用 get_query_run_results，即可获取状态、列、行数和成本（如果查询仍在运行，请传入 poll_timeout_seconds）。如果运行失败、出错或返回零行，请修正 SQL 并重新运行——除非零行确实就是问题的答案，否则不要把空结果或失败的运行报告为答案。

小规模测试确认无误、准备运行实际要使用结果的查询后，请改用 create_explorer_query（并设置 run_on_creation=True），而不是先通过 run_sql_query 运行——将已经验证过的查询通过 run_sql_query 再运行一次并随后保存，会造成重复计算。这也意味着，到达第 7 步时，生产查询已经是一个已保存的 Explorer 查询。

查询已知资产或钱包的当前状态时，请使用 Realtime 数据。对于历史、比较、汇总或跨链问题，请使用 Explorer/SQL。不要将二者不同的新鲜度语义混在同一个未标注的指标中。

5. 验证结果

根据所用方法进行适当检查：

• 将总数与各组成部分进行核对；
• 检查联接是否造成重复累加，并确认 COUNT(DISTINCT ...) 是否符合预期的粒度；
• 确认代币单位、小数位数、美元换算和分母；
• 比较相邻时段，调查而不是平滑处理数据的不连续情况；
• 使用不同的汇总方式、筛选条件或样本，至少独立重新查询一个关键数字。

不要把与外部聚合器的结果一致视为证明。这可以作为合理性检查，但发布的结论需要有自己的方法和来源链路。

6. 提出审慎的结论

将陈述分为三类：

• **观察结果：**查询直接显示的内容。
• **解释：**合理的解释，需明确标注，并与支持证据关联。
• **未知事项：**现有数据无法证明的内容。

没有证据时，不要将相关性说成因果关系，不要将已标记的地址说成已验证的控制者，也不要将样本推及整个总体。

7. 确保结果可在 Explorer 中复现

如果结论只存在于聊天记录中，就无法复现——任何人想要重新查看，都得凭记忆重新输入 SQL。到第 4 步时，关键查询应该已经通过 create_explorer_query 保存；如果还没有，现在就保存，不要只留下一条未保存的 run_sql_query 结果。

单个结果——如果调查只产生了一个关键查询，通常单独使用它就足够了：可选择对其调用 create_explorer_visual（图表／数值／表格——选择适合数据的类型），并调用 share_explorer_query 返回链接。跳过本步骤的其余内容。

多个结果，计划用于构建仪表板——应用中的 Allium Assistant 可以构建仪表板，但在仪表板模式下无法编写 SQL；它只会组合告知它的已保存查询。目前没有 MCP 工具可以直接组合多查询仪表板，因此需要将提示词交给用户，由用户粘贴到 Assistant 中。保存每个查询后，输出一份：

Build me a dashboard.

Title: <short title>
Goal: <one sentence — what should this dashboard show?>

Queries:
- <query_id>: <one-line description>. Cols: <col> (stock→last), <col> (flow→sum), ...
- <query_id>: <one-line description>. Cols: ...

Filters: <optional, one line>
Elements: <optional, one line — e.g. "KPI: total_x (last); chart: y over time by chain">

绝不能省略的两项内容是查询 ID和每列的存量／流量标签——存量指标（供应量、余额、TVL、价格：汇总 last/first）被像流量指标（成交量、计数、手续费：汇总 sum）那样求和，是最常见的真实仪表板错误，而 Assistant 无法仅凭列名推断出这一点。如果提示词太长，应先将 Filters/Elements/Goal 缩短为短语，而不要删减查询或存量／流量标签。整体长度应远低于 800 个字符——简短到别人看一眼就能复制并直接粘贴到 Assistant 中，无需编辑。