create-context-tests

用途

create-context-tests 用于为 nao 智能体生成一套自然语言 → SQL 配对的测试套件，作为该智能体的质量基准，并通过 nao test 命令运行。它适用于用户希望建立或评估 nao 智能体可靠性的场景。

主要能力

nao test 会把每个自然语言提示送入智能体，执行智能体生成的 SQL 与测试中期望的 SQL，并对结果数据逐行比对。只有实际数据匹配（相同行、相同值）时测试才通过。该套件是可靠性基准，RULES.md 的每次变更都以此衡量。

参考文档：docs.getnao.io/nao-agent/context-engineering/evaluation。

测试数量

## Key Metrics Reference 中每个关键指标至少一个测试。然后为以下情况补充测试：时间范围（尤其是“last 8 weeks”/“last 30 days”）、CTE / 多步查询、边界情况（NULL、空窗口）、以及歧义措辞（“our users”“active”）以验证命名约定规则。

两条编写规则（适用于每个测试）

规则 1 — 提示词要像真实聊天。模糊、简短，不包含表/列/方法提示。测试验证智能体能否从真实用户输入得到正确答案。

反例："What was the churn rate from fct_subscriptions in Q1?" 正例："How's churn looking this quarter?"

反例："Compute MRR as SUM(mrr_amount) where status='active'" 正例："What's our MRR?"

规则 2 — 输出列名编码格式/单位，而非来源。列名传达如何解释该值。

反例：churn_rate_from_fct_subscriptions 正例：churn_rate_float_0_1

反例：mrr_amount_fct_stripe_mrr 正例：mrr_usd_dollars

反例：signup_at_dim_users 正例：signup_date_yyyy_mm_dd

命名模式：比率用 <metric>_float_0_1 或 <metric>_percentage_0_100；金额用 <metric>_<currency>_<unit>；计数用 <thing>_count；日期用 <thing>_date_yyyy_mm_dd。参见 templates/test.yaml。

使用方式

先询问一次：用户是否有可信的权威查询（Looker、仪表盘、既有基准）？如果有，把每个转换为测试（重写 SELECT 以应用规则 2；反向推导出符合规则 1 的提示词）。对于没有可信查询的指标，每个指标起草一个新测试。
平铺保存在 tests/ 下（不要子文件夹），每个测试一个 YAML 文件。使用 templates/test.yaml。
让用户验证——确认提示词符合其团队措辞，SQL 符合其对“真相”的定义。
运行 nao test。前置条件：

cd 进入项目目录（nao_config.yaml 所在处）。
在后台启动 nao chat（测试运行器复用 chat 服务器）。
在 nao_config.yaml 中配置 LLM。
首次运行会提示登录凭据——让用户手动输入，不要用脚本绕过。
如果看到 AI_APICallError: Not Found at https://api.anthropic.com/messages（缺少 /v1/），先运行 unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY（父智能体 CLI 泄漏了环境变量）。完整说明见 setup-context。

命令：nao test -m <model_id> -t 10（-t 表示并行度）

汇总结果：通过率、token 成本、墙钟时间。将其作为基线引用。
诊断失败（可选）：读取 tests/outputs/ 中每个失败项，找出规则缺口，提出最小修复，然后转到 write-context-rules（或对系统性问题转到 audit-context）。在修复之间重新运行，以便影响可归因。

适用场景

为 nao 智能体建立可靠性基准。
在修改 RULES.md 后评估影响。
验证命名约定规则、时间范围处理、多步查询和边界情况。

限制与护栏

测试的 SQL 必须原样执行——FROM 中不能有 <placeholder>。使用真实的表/列名。
绝不在提示词或输出列名中泄露答案（规则 1 + 2）。
每个指标一个测试是底线；覆盖测试在其后。
每次运行之间只应用一个上下文修复。
如果测试与 RULES.md 矛盾，停止并询问哪个正确——这是其中之一的 bug。

模板

templates/test.yaml — 单测试格式。