00-前言与判断

Part 0 · 前言与判断

在动手之前先判断：你的项目是不是真的应该做问数技能、你的数据底座是不是真的准备好、你的团队是不是真的能承担数据底线。

0.1 这份指南是什么 / 不是什么

是什么

跨业务领域的方法论：把 cost-query 沉淀里跨领域可复用的部分（架构分层、DSL 设计、SKILL 纪律、测评闭环）抽出来；
一份开发节奏指南：从立项前评估、数据底座建设、Schema 设计、DSL 编译层、二级指令、SKILL 业务表达、模式手册、测评迭代，到上线运维全周期；
一套反模式清单：cost-query 走弯路踩过的坑，能让其他领域少走 6-12 个月弯路；
一份脚手架代码包：可运行的 skeleton，让其他领域少写约 60% 的样板代码。

不是什么

不是「售楼版 cost-query 怎么做」的完整 demo：业务领域不同，硬抄会南橘北枳。本指南给「方法 + 清单」，让各领域自己推导；
不是 SQL 翻译器开发手册：问数技能 ≠「自然语言 → SQL」翻译。请见 §0.3 的「问数技能 vs SQL 翻译器」对比；
不是 Prompt Engineering 教程：本指南假设你已经熟悉 Claude Code / Skill / Subagent 等基础机制。不熟悉者请先读 Claude Code 官方文档；
不是数据建模指南：本指南假设你已经能把业务数据建成相对干净的星型宽表。如果数据底座质量差，问数技能再好也是无源之水（见 §0.4 立项前评估）。

0.2 问数技能 vs SQL 翻译器：一个本质区分

很多团队第一反应是”做一个自然语言转 SQL 的工具”。这是个完全错误的起点。

维度	SQL 翻译器	问数技能
角色定位	把自然语言翻译成 SQL，谁会写 SQL 谁就懂	业务专家的数据助手（成本经理 / 销售经理 / 工程经理）
对外输出	SELECT 结果表	结论 + 依据 + 用法 + 风险边界
错误处理	报 SQL 语法错或 0 行结果	主动识别口径不一致、样本不足、异常值；用业务话术给可放宽方向
数据底线	翻译就是任务，结果对错让用户自己判断	不补数 / 不混业态强判断 / 不用通识冒充数据库结论
意图分层	单层：用户问什么我答什么	L1（查事实）→ L2（做判断）→ L3（找原因）→ L4（给动作）四层
归因能力	无	内置领域归因框架（成本：量差/价差/配置差/条件差/口径差）
典型失败模式	翻译错语法、JOIN 关系错、口径错	错口径混算给强结论、样本不足强判断、把通识当数据
替代关系	高级用户用 BI 工具就够了	即使会写 SQL 的高级用户也用——因为它管的是”业务结论质量”，不是”SQL 写得对不对”

核心差异：SQL 翻译器是工具，问数技能是「能力 + 纪律」的组合。能力是把语言变成查询；纪律是知道什么时候不回答、不强判断、不补数。

不理解这个差异的团队会做出”看起来很厉害但业务用不起来”的产品——业务用户用了几次发现它给的结论靠不住（口径混乱、样本太少、强行回答没数据的问题），就再也不来了。

0.3 cost-query 演进 30 秒回顾

理解这段历史，能帮你跳过 cost-query 已经踩过的坑。

V1（2026-04-09 → 2026-04-21，约 2 周）  本体 + API
  目标：基于 OWL 本体 + HTTP API 的 OBDA（Ontology-Based Data Access）查询引擎
  形态：cost.ttl 既描述领域概念又描述 API 子命令 / 字段映射（cli:* 注解）；
        Python CLI（fire 框架 + 中间件管道）多步调用业务 API
  问题：API 路径长——典型 7 步（condition_auto_recognize → query_* 修正 → load_data → 翻页 → 中间件聚合 → …）
        LLM 编排错误率高；字段级映射全部塞在本体里，本体既管概念又管 API 参数，膨胀难维护
  关键沉淀：本体（cost.ttl）作为领域概念层；Agent + Skill + CLI 三层架构雏形

V2（2026-04-22 → 2026-05-08，约 2-3 周）  本体 + 宽表
  目标：把执行底层从"多步 API 编排"切到"DSL → SQL 直查星型宽表"
  形态：星型宽表（10+ 张 dim_cost_* 维度宽表 + 6 张 dws_/dwd_ 事实宽表）；
        scripts/schema.yaml 单一源；scripts/query.py 统一入口；
        14 个二级指令（find-X / agg-X / rank-X）+ 一级 DSL（find / aggregate / rank）双层抽象；
        本体定位升级为"领域概念 + 宽表锚点（dwh:table / dwh:grain / dwh:filter）"
  问题：LLM 还是要"自由发挥"——拿到问题先想用哪个 cube、哪个 verb、哪些参数；
        DSL 直查容易撞字段所有权差异（如 BqUnitPrice.cityName 不存在）；
        三个事实 cube 一度搁置注册
  关键沉淀：双层指令抽象（一级 DSL + 二级模板）、routed measure（同名多口径路由）、
        派生维度（{self} 占位符 + DATE_FORMAT 等 SQL 表达式）

V3（2026-05-09 → 2026-05-25，约 2-3 周）  速查表 + 模式手册
  目标：让 LLM 一次做对——速查表 + 模式手册
  形态：SKILL.md 引入"步骤 0 速查表"（M1-M5，22 个模式）；35 题问题集 + headless 跑批；
        schema 拆双层（编译源 vs AI 速查版）
  问题：分析能力（归因 / 动作建议）下沉得不够；用户挑战结论时容易认错补数
  关键沉淀：模式手册（命中即抄）、双层 schema、自动行为
        （inferredFilters / defaultFilters / friendlyAlias）

V4（2026-05-26 → 2026-06-02，约 1 周，当前）  业务表达层成熟
  目标：从"数据查询员"升级为"成本经理的数据助手"
  形态：SKILL.md 380 行；6 步执行总流程；L1-L4 意图分层；收口门；
        五差框架；数据底线红线；模式手册扩到 M1-M6 共 39 个模式；测评 71 题；
        cost-clean / dp-query 配套技能上线
  关键沉淀：业务表达层与编译层的纪律分离；归因驱动的下钻节制

整个项目从 2026-04-09 启动到 V4 锚点不到 2 个月——这正是本指南把执行计划压在 2 个月的依据：跨过的所有坑、踩过的所有 commit 路径，可以让后续项目少走 4-6 个月的弯路。

跨版本的共性教训：

第一版别拿给业务用：V1 走 API 编排路径长，LLM 多步调用错误率高；这种”看着能跑”的形态拿出去试用，业务方一旦发现答得不稳就再也不回头；
执行底层选对很关键：V1 → V2 把”多步 API 编排”换成”DSL → SQL 直查宽表”是最大的一次升级——单步出结果，错误面收窄，性能也稳；
本体只管概念、不管 API 参数：V1 把字段映射也塞进本体导致膨胀难维护；V2 起字段级映射下沉到 schema.yaml，本体回归概念层；
测评驱动重写：每次速查表 / SKILL 修改都用问题集跑一遍，比闭门造车快得多；
业务表达层与编译层要分离：V3 之前两者混在 SKILL.md 里，改业务话术会破坏 DSL；V4 显式分离后双方都能独立演进；
角色定位决定一切：V1-V3 都把自己当查询员，V4 把自己当业务专家——同样的代码、同样的数据，输出质量天差地别。

0.4 立项前评估清单

不是所有项目都该做问数技能。先用下面 5 项评估你的项目。4 项及以上”是”才建议立项。

评估项 1：数据底座是否准备好

业务数据已经汇集到独立的分析库（不是直接挂 OLTP）；
已经有相对干净的维度宽表（项目 / 城市 / 客户 / 产品等核心实体）；
已经有 1-3 张事实宽表（数据已星型化或者能在 1-2 个月内星型化）；
数据更新有相对稳定的节奏（每天 / 每小时 / 实时其中之一，不是”想起来跑一次”）。

如果只达到 1-2 条：先做半年的数据治理，再考虑问数。问数技能不能修数据底座的问题——它会把数据问题暴露得更厉害。

评估项 2：用户提问是否可结构化

业务用户的提问 80% 以上能落到「某口径下某指标」的形式（“深圳住宅的钢筋含量是多少” / “李四这个月业绩排名第几”）；
业务用户的提问 50% 以上有相对固定的角度（口径维度集合相对收敛，不是每天都有全新问法）。

如果提问完全自由、维度组合爆炸：问数技能仍可做，但模式手册难以收敛，错误率会偏高。建议优先做核心 20% 高频场景。

评估项 3：是否有可承担数据底线的业务方

业务方理解”无数据时不能补数”——而不是要求”必须给个答案”；
业务方理解”样本不足时只能弱结论”——而不是要求”看起来要像专家说话”；
业务方愿意接受”用户给的数字可能跟数据库不一致就反问，而不是直接信”。

如果业务方坚持”必须每次都给答案、必须像专家说话”：你们要做的是 PPT 工具不是问数工具，请别走这条路。

评估项 4：是否有可持续投入的迭代节奏

至少 1 个 AI 工程师 + 1 个业务产品 + 0.5 个数据工程师，集中投入 2 个月做 0→1；
上线后至少有 0.5 人持续做模式手册治理与 Bad case 修复；
业务方愿意每周抽 1-2 小时配合测评集设计与 Bad case review。

如果只能给 1 个全干工程师 1 个月做完：做个 demo 给老板看可以，做生产可用的别想。

评估项 5：是否有合适的 LLM 基础设施

已经接入 Claude / GPT-4 级别的模型（本指南以 Claude Code 为参考实现）；
已经能用 Skill / Subagent / MCP 等基础能力组装多步任务；
已经有 prompt 调优 / 测评 / 上线发布的基本流程。

如果 LLM 基建还在初级阶段：先把基建跑通（1-2 个月），再来做问数。

0.5 投入产出预判

典型投入（参考 cost-query 经验，按 2 个月计划压缩）：

阶段	时长	人力	主要工作
数据底座（前置）	视存量数据情况而定	数据工程主导	维度宽表 + 1-3 张事实宽表 + 本体定义
MVP 0→1（第 1 周）	1 周	2 人	1 张事实 cube + 3-5 个二级指令 + 5 题测评 + SKILL 雏形
模式手册 1→10（第 2-4 周）	3 周	2 人	10-15 个 M 模式 + 25-30 题测评 + 归因框架上线
内部试用 + 治理（第 5-8 周）	4 周	2 人	15-20 个模式 + 40-50 题测评 + Bad case 闭环 + 文档就位
生产上线 + 持续治理	持续	0.5 人	Bad case 闭环 / 模式扩展 / 反模式沉淀

典型产出（不保证，仅参考）：

第 1 周末：跑通 MVP demo（5 题 ≥ 3 题通过）；
第 1 个月末：业务方可看 demo（常见问题正确率 75%+）；
第 2 个月末：内部业务方试用（连续 2 轮总分 ≥ 80%）；
上线后持续治理：每月 1-3 个新模式 + Bad case 修复，长期稳定在 85%+。

注意：80% → 90% 的提升完全来自上线后测评驱动的反复治理——没有测评集就没有这条增长曲线。

0.6 接下来读什么

立项评估通过 → 读 Part 1 通用框架；
想看 cost-query 怎么具体落地 → 读附录 A · cost-query 设计方案速读；
想直接动手起步 → 读 Part 9 脚手架与启动模板并跑 scaffold/init.sh。

Part 0 完。读完应能判断：“我们这项目该不该做问数、做了之后大概什么节奏、踩坑预期是什么”。