企业官网建设流程全解析

Default filters

【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20+ data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI

• ordersqueries exclude rows wheredeleted_at IS NOT NULLunless the user asks about deletions.
• usersqueries default tois_active = true AND is_internal = false.

- **为什么重要：** 软删除对 schema 完全不可见；不写规则，Agent 就会产出"SQL 正确、行集错误"的结果——这是最隐蔽的一类 bug。 **解析：** 这是典型的"隐性约定"。几乎所有 SaaS 数据库都用软删除，但没有任何 schema 元数据能表达"默认要过滤掉已删除行"。写入 `## Default filters` 小节后，[`wren context instructions`](https://link.gitcode.com/i/d8ce0e02a8dbbcb2baa5603ad0a4fe11) 命令会在读取业务规则时自动将其注入到 LLM 的上下文。 ### 5. 魔法哨兵值（Magic sentinels） - **触发条件：** 数值列且探测 / raw 显示去重值中包含远离主体的离群值（本应全正的列中出现 -1、0，或出现 9999、99999999）且 description 不含 `[magic]`。 - **raw 关键词扫描：** "unknown"、"all"、"any"、"n/a"、"default"、"sentinel"、"-1 means"、"999 means"。 - **Sink：** 列 `properties.description`。 - **Tag：** `[magic] -1 = unknown; 0 = system user` / `[magic] 9999 = lifetime / no expiry`。 - **为什么重要：** 平均值和求和会被当成真实值的哨兵值"静默污染"。 **解析：** 工程上常用特殊数值表达业务状态：`-1` 表示"未知"、`9999` 表示"终身/无过期"。若 Agent 不知道这一点，`AVG(amount)` 会把 -1 当作真实负数参与计算。Step 4.5 的探测正是为此设计了 min/max 补充查询：`SELECT MIN(<col>) AS lo, MAX(<col>) AS hi FROM <model>`，一次就能暴露这类离群哨兵。 ### 6. 同义词 / 业务别名（Synonyms / business aliases） - **触发条件：** raw 使用某个业务术语，其能映射到某个 model / column / metric，但该术语在 MDL 的名称或描述中没有逐字出现。 - 示例："customer" → `customers`（而非 `accounts`、`customers_v3`）；"ARR" → `mrr * 12`；"DAU" → 每日去重活跃用户数。 - **Sink：** `knowledge/rules/` 下的 `## Naming conventions` 小节。 - **写入格式：** ```markdown ## Naming conventions - "ARR" in business docs = `subscriptions.mrr * 12`. Do not use the `revenue` table. - "customer" = the `customers` model (not `customers_v3`, that's the legacy raw mirror). - "active user" = a user with at least one event in the past 28 days, not `users.is_active`.

• 为什么重要：记忆检索（memory retrieval）按术语匹配；用户说业务语言，schema 说技术语言，两者之间的鸿沟需要显式桥梁。

解析：这一类别揭示了 enrich 的核心价值：它把"业务词典"写进规则库。注意第三个示例的微妙之处——"active user"的业务定义（28 天内至少有一次事件）与users.is_active列的技术定义不同，这种差异若不写明，Agent 会默认二者等价。

7. 日期 / 时间约定（Date / time conventions）

• 触发条件：column.type ∈ {DATE, TIMESTAMP, TIMESTAMP_TZ, TIMESTAMPTZ}且 description 不含[time]且满足任一：时区（TZ）歧义、事件时间 vs 记录时间歧义、时间粒度歧义。
• 名称提示：*_at、*_time、*_date、created_*、updated_*、as_of_*、effective_*。
• raw 关键词扫描："UTC"、"timezone"、"event time"、"as of"、"snapshot"、"month-end"、"fiscal"、"rolling"。
• Sink：列properties.description。
• Tag：[time] UTC; event time (not insert time); month-end snapshot for billing rows。
• 为什么重要：跨时区聚合、财年 vs 自然年分桶、"as-of" 快照会产生"干跑（dry-run）都通过但分桶错误"的数字。

解析：时间列是三类歧义的温床：时区歧义（存的是 UTC 还是本地时间）、事件时间 vs 记录时间歧义（created_at是事件发生时刻还是入库时刻）、粒度歧义（天级、月级还是月末快照）。这些歧义在dry-run阶段完全不可见——SQL 能编译、能执行、结果"看起来对"，只有对账时才发现分桶错了。

8. 跨系统标识符（Cross-system identifiers）

• 触发条件：列名包含外部系统标签（stripe_*、salesforce_*、intercom_*、hubspot_*、*_external_id、*_external_ref），或 raw 将内部 ID 映射到外部系统。
• Sink：knowledge/rules/下的## External identifiers小节。
• 写入格式：

  ## External identifiers - `users.stripe_customer_id` maps to a Stripe Customer object. NULL = not yet billed. - `orders.external_ref` is the source-system order ID; format varies by `orders.source` (`shopify` = 13-digit numeric, `manual` = free-form string).

• 为什么重要：Agent 对外部系统没有 schema；它需要显式的映射关系以及格式 / NULL 语义说明。

解析：外部 ID 列的核心问题有三层：映射到哪个外部对象、NULL 的业务含义、值的格式约束。只写"这是 Stripe ID"不够，还要写"NULL 表示尚未开票"和"shopify 来源是 13 位数字、manual 来源是自由文本"，Agent 才能正确处理 join 和校验。

9. 货币 / 区域（Currency / locale）

• 触发条件：任一 model 含有currency、locale、country、region、fx_rate、original_amount列，或 raw 提到 FX 汇率、多币种、非美元报表。
• Sink：knowledge/rules/下的## Currency小节。
• 写入格式：

  ## Currency - All amounts in `orders.amount` are USD-converted at order-time FX (see `orders.fx_rate`). Use `orders.original_amount` + `orders.currency` for source-currency analysis. - Display monetary values with 2 decimals and thousand separators.

• 为什么重要：没有规则时，Agent 会不加换算地直接求和混合币种的行。

解析：多币种是聚合查询的高危区。这一类别明确了两件事：存储口径（orders.amount是下单时按汇率折算的 USD）和展示口径（两位小数、千分位分隔符）。两者都属于 schema 无法表达、必须由规则注入 LLM 上下文的语义。

10. 规范表偏好（Canonical table preferences）

• 触发条件：schema 中存在相似表（users/users_v3、orders/orders_archive/orders_summary），或 raw 中出现 "use X not Y"、"deprecated"、"raw mirror"。
• Sink：knowledge/rules/下的## Canonical tables小节。
• 写入格式：

  ## Canonical tables - Use `customers` for analytics. `customers_v3` is the legacy raw mirror — do not query. - For order date ranges > 90 days, use `orders_summary`. `orders` is row-level only and slow on large windows.

• 为什么重要：没有显式规则时，Agent 会按"词汇接近度"选表，然后默默选错。

解析：数据仓库中"长得像的表"比比皆是：生产表、历史归档、预聚合汇总、旧版原始镜像。它们列名相近、含义迥异。若规则库只字不提，Agent 依据schema describe的词法相似度选表，几乎必然踩坑——而且这种错误同样静默。

再富集审计（Re-enrichment audit）

在追加新内容之前，先确认此前的 enrich 运行已经覆盖了什么：

# 列级 tag 检查 grep -rE '\[(enum|unit|null|magic|time|pii)\]' models/ # knowledge/rules/ 中由 enrich 写入的小节标题检查 grep -rE '^## (Default filters|Naming conventions|External identifiers|Currency|Canonical tables)' knowledge/rules/

【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20+ data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI