10-检查清单与FAQ
Part 10 · 检查清单与 FAQ
Section titled “Part 10 · 检查清单与 FAQ”立项 / 上线 / 治理三个关键节点的检查清单，加 cost-query 团队收集的常见踩坑 FAQ。
10.1 立项检查清单
Section titled “10.1 立项检查清单”立项前逐项确认，4 项及以上”是”才建议立项。
- 已经有相对独立的分析库（不是直接挂 OLTP）；
- 维度宽表（项目 / 客户 / 产品 / 城市等）已建成或能在 1 个月内建成；
- 至少 1 张事实宽表已经星型化；
- 数据更新节奏稳定（每天 / 每小时 / 实时）。
- 业务用户 80% 提问能落到「某口径下某指标」的形式；
- 业务用户提问的维度组合相对收敛（不是每天全新问法）；
- 至少有 30-50 道代表性问题能提前梳理出来；
- 业务方愿意每周 2 小时投入测评协同。
- 业务方理解”无数据时不能补数”；
- 业务方理解”样本不足时只能弱结论”；
- 业务方愿意接受”用户给的数字与数据库不一致时反问，不直接信”；
- 业务方理解上线后仍有 10-15% 的复杂场景需要人工兜底。
- 至少 1 个 AI 工程师集中参与（2 个月，60-80%）；
- 至少 1 个业务产品参与（前 2 个月 40-60%）；
- 至少 0.5 个数据工程师配合（前 1 个月集中）；
- 上线后至少 0.5 人持续做模式手册治理与 Bad case 修复。
LLM 基础设施
Section titled “LLM 基础设施”- 已接入 Claude / GPT-4 级别模型；
- 已经能用 Skill / Agent / MCP 等基础能力；
- Prompt 调优 / 测评 / 发布的基本流程已建立。
10.2 第 1 个月检查清单
Section titled “10.2 第 1 个月检查清单”第 1 个月末按以下逐项检查。
Schema 与 cube
Section titled “Schema 与 cube”- schema.yaml 已定义至少 1 个事实 cube + 3-5 个维度 cube；
- 每个 cube 有 description / grain / role；
- 数据语义陷阱已写进 description 明文；
- inferredFilters / defaultFilters / friendlyAlias 至少配置了 1 处；
- fetch_schema 已生成速查版（_index.yaml + 事实 cube 单文件 + dimensions.yaml）；
- 单事实 cube 单文件 < 500 行。
- 至少 3 个二级指令（覆盖 find / agg）；
- 每个指令
--info能打印参数清单； - 每个指令
--dry-run能打印编译出的 DSL； - 至少 1 个业务化封装（类似 measureGroups 这种）。
SKILL.md
Section titled “SKILL.md”- 核心定位明确（业务专家角色）；
- 数据底线 + 高危红线 已写；
- L1-L4 意图分层已写；
- 主查询后收口门已写；
- 领域归因框架已写（不是直接抄五差）；
- 红线与替代动作表已写；
- 行数控制在 250-350 行。
模式手册（query-guide.md）
Section titled “模式手册（query-guide.md）”- 至少 5-10 个模式；
- 每个模式有清晰的”命中关键词”列；
- 每个模式有可直接抄的”命令模板”；
- 槽位标注规则已建立（低/中/高风险）；
- 维度风险分级表已写；
- 反模式黑名单 ≥ 5 条；
- §0 必读铁律已写（D1-D3 至少覆盖 0 行机械撤宽）。
- 至少 20 题；
- L1-L4 各覆盖；
- 每题有 5 项参考信息（路径 / 参数 / 结论 / 边界 / 评分要点）；
- 跑批工具能跑通；
- CLI 分 + 结论分解耦评分；
- 全量测评总分 ≥ 75%。
- 已有 1-2 个业务方试用渠道；
- 每周至少 1 次业务方反馈收集；
- Bad case 流转流程已跑通（业务反馈 → 测评 → 治理）。
10.3 上线前检查清单
Section titled “10.3 上线前检查清单”生产上线前逐项确认。
- 测评集 ≥ 50 题；
- 连续 2 轮全量测评总分 ≥ 80%；
- CLI 分 ≥ 85%、结论分 ≥ 80%；
- 无单题低于 50 分；
- 复合问题（拆段）能力跑通；
- 0 行 / 全 NULL / 撤宽即终点 兜底能力跑通；
- 高危红线（不补数 / 不手写 SQL / 不混业态强判断）测评全通过。
- DSL 编译器在 100 次随机调用中错误率 < 1%；
- 数据库连接稳定（连续 1000 次查询无超时）；
- 平均查询延迟 < 3 秒（含 LLM 推理 + SQL 执行）；
- 单次最长延迟 < 30 秒；
- 异常情况有日志记录（错误堆栈 + DSL + SQL）；
- 已制定故障预案（数据库挂 / LLM API 挂 / Skill 加载失败）。
- 业务方对”L1-L4 输出深度”有共识；
- 业务方理解”数据底线 + 红线” 不会因为短期不满意而要求违反；
- 业务方理解”模式手册覆盖范围”——不在覆盖内的问题会得到诚实告知；
- 用户操作手册已写（业务方文档，1-2 页）；
- 试用阶段反馈渠道已建立（IM 群 / 工单系统）。
- 用户手册（业务方读）；
- 维护手册（研发读）；
- 测评报告归档；
- 已知问题清单（暂未支持的能力、已知 Bad case）；
- 变更日志（每次发布的变更点）。
持续治理机制
Section titled “持续治理机制”- 每周跑全量测评；
- 业务 Bad case 进入测评集的流程；
- 治理迭代节奏（推荐 1-2 周一轮）；
- 跨版本对比报告自动生成；
- 性能监控告警（延迟超阈值 / 错误率超阈值）。
10.4 常见踩坑 FAQ
Section titled “10.4 常见踩坑 FAQ”Q1：LLM 经常选错二级指令怎么办？
Section titled “Q1：LLM 经常选错二级指令怎么办？”症状：测评中 LLM 把”做汇总的问题”路由到 find-X 而不是 agg-X、把”找原因的问题”误用 find-X。
根因：模式手册的”命中关键词”列不够清晰；指令的 description 太抽象。
治理：
- 在模式手册的”命中关键词”列加更具体的触发词（“是多少”→ agg、“有哪些”→ find）；
- 在 cli-mapping.md 加”决策表”，明确什么时候选什么；
- 在反模式黑名单加”verb 误用”条目。
Q2：LLM 经常忘记加 isEndCost / isJianAn 这种关键参数怎么办？
Section titled “Q2：LLM 经常忘记加 isEndCost / isJianAn 这种关键参数怎么办？”症状：测评中 LLM 写 DSL 时遗漏关键 filter，导致父子混算或业态错切分。
根因：业务规则只写在 SKILL.md 而没做进编译器自动行为。
治理：
- 在 schema.yaml 加 inferredFilters / defaultFilters 在编译器层兜底；
- 双重保险：SKILL.md 提醒 + 编译器兜底；
- 加 dry-run 的 hint 输出（“已推断 isJianAn=1”）让 LLM 看到。
Q3：LLM 看到 0 行结果会反复改参数试探怎么办？
Section titled “Q3：LLM 看到 0 行结果会反复改参数试探怎么办？”症状：测评中 LLM 拿到 0 行后调用 5-6 次重试，改不同参数死磕。
根因：没明确”0 行机械撤宽”的铁律；LLM 本能想”再试一次”。
治理：
- 在 query-guide §0 写 D1 铁律：0 行 = 机械撤宽（filter → groupBy）；
- 在反模式黑名单加”逐参数试错”条目；
- 测评对”撤宽即终点”场景专门加题，分数权重提高。
Q4：LLM 在用户挑战结论时立刻认错补数怎么办？
Section titled “Q4：LLM 在用户挑战结论时立刻认错补数怎么办？”症状：测评对”用户说这数不对”的题，LLM 立刻道歉并编一个新数。
根因：模型默认”用户优先”，没明确数据底线优先级。
治理：
- SKILL.md 顶部”数据底线”明确”用户给出的数字只能作为待复核输入，不能冒充数据库结论”；
- 在意图识别里加”用户挑战结论”分支：先复盘查询过程，过程无问题则用证据说话；
- 测评对挑战题专门打分，违反数据底线直接 0 分。
Q5：业务方反馈”结论看起来对但口径模糊”怎么办？
Section titled “Q5：业务方反馈”结论看起来对但口径模糊”怎么办？”症状：业务方看到结论数值正确但不知道”这是哪个业态/哪个阶段/哪个时间窗”。
根因：SKILL.md 的”对外输出规范”没强制”边界”段落。
治理：
- 强化”结论-依据-用法-边界”四段叙事；
- 测评对”边界标注”专门评分，缺失边界扣 10-15 分；
- 在样本呈现纪律中加”打标近似样本”要求。
Q6：跨 cube 查询 LLM 经常写错 JOIN 关系怎么办？
Section titled “Q6：跨 cube 查询 LLM 经常写错 JOIN 关系怎么办？”症状：DSL 直查时 LLM 把 BqUnitPrice.cityName 写成自身字段（实际要走 JOIN City）。
根因：事实 cube 字段所有权差异没明示。
治理：
- 在 dsl-spec.md §7 错误自救加”错写 → 正写”对照表；
- 在 schema friendlyAlias 把跨 cube 字段包装成自身字段（编译期自动 JOIN）；
- 物理化高频跨 cube 字段（如把 cityName 直接物化进事实表）。
Q7：LLM 平均跑一个题要 20-30 秒，太慢怎么办？
Section titled “Q7：LLM 平均跑一个题要 20-30 秒，太慢怎么办？”症状：单题响应时间偏长，业务用户等不及。
根因：可能多个原因——SKILL.md 太长 / 模式手册查找太慢 / 多次重试 / SQL 执行慢。
治理：
- SKILL.md 控制在 300-400 行（更长会让首读加载慢）；
- 模式手册做成扁平表格（不要嵌套）；
- 编译器加错误自救机制（让 LLM 1 次重试就能修对，避免反复 retry）；
- SQL 慢查询单独优化（看是不是缺索引、统计信息不准）。
Q8：测评分数波动大（同样代码跑两次差 10 分以上）怎么办？
Section titled “Q8：测评分数波动大（同样代码跑两次差 10 分以上）怎么办？”症状：每次跑测评分数都不稳定，难以判断改动有没有效果。
根因：LLM 推理有概率成分；评分员也有概率成分。
治理：
- 每次跑 2-3 轮取平均；
- 阶段 A 用 temperature=0（如果 API 支持）；
- 阶段 B 评分用更结构化的打分点（不是自由发挥打分）；
- 关注”分布”而不是”均值”（看每题的稳定性）。
Q9：模式手册写到 30 个以后 LLM 反而错率升高怎么办？
Section titled “Q9：模式手册写到 30 个以后 LLM 反而错率升高怎么办？”症状：模式手册扩展过快后，LLM 在多个模式之间选错。
根因：模式手册过于细分，触发关键词重叠度高。
治理：
- 砍掉低频模式（测评中 < 5% 调用次数的），合并到通用模式；
- 提高每条模式的”命中关键词”差异度；
- 引入”匹配优先级”规则（如更窄优先 / 复合优先）；
- 必要时拆模式手册（按 cube 分多个文件）。
Q10：业务方加了一个新业务场景，但短期内来不及加测评题怎么办？
Section titled “Q10：业务方加了一个新业务场景，但短期内来不及加测评题怎么办？”症状：业务方临时加新场景，希望立刻支持，但完整治理流程要 1-2 周。
根因：缺乏”快速响应”通道。
治理：
- 设”快速支持”通道：业务方提需求 → 1-2 天内出 MVP 模式 → 标注”试用版本”；
- 1 周内补 3-5 道相关测评题；
- 2 周后评估是否升级到”正式模式”（按治理流程双轮验证）。
Q11：用户问的问题模式手册根本没覆盖怎么办？
Section titled “Q11：用户问的问题模式手册根本没覆盖怎么办？”症状：LLM 拿到问题没匹配任何模式，进入”自由发挥”模式，错误率高。
根因：模式手册覆盖不全 + fallback 路径不够明确。
治理：
- query-guide §3 写清”未命中走标准流程”的步骤（schema 路由 → 槽位提取 → 维度标准化 → 选指令 → 执行）；
- 在 SKILL.md 强调”未命中时谨慎执行 + 显式标注”；
- 把这类问题进入测评集，作为加新模式的依据。
Q12：跨 skill 协作（如 cost-query 想调用 sales-query）怎么办？
Section titled “Q12：跨 skill 协作（如 cost-query 想调用 sales-query）怎么办？”症状：业务方问”某项目的成本与售价”——需要跨成本和售楼两个 skill 取数。
根因：单 skill 只覆盖单领域。
治理：
- 不要把两个 skill 强行合并；
- 上层 agent 协调多 skill：成本数据走 cost-query、售楼数据走 sales-query，结果在 agent 层拼接；
- 模式手册不要写跨领域模式——保持单 skill 内聚。
10.5 维护手册要点
Section titled “10.5 维护手册要点”上线后维护手册应包含：
- 变更日志：每次发布的变更点 + 测评分变化；
- 已知问题清单：暂未支持的能力 + 已知 Bad case + workaround；
- 告警与监控：哪些指标超阈值需要人工介入；
- 应急预案：数据库挂 / LLM API 挂 / Skill 加载失败的处理；
- 测评归档：近 3 个月的全部测评结果保留位置；
- 模式手册治理记录：每月新增 / 修改 / 删除的模式 + 原因；
- 业务方反馈日志：每次反馈 + 处理状态 + 是否进测评。
10.6 用户操作手册要点
Section titled “10.6 用户操作手册要点”给业务方的操作手册（1-2 页），应包含：
- 支持的提问范围：哪些场景能问、哪些不能问；
- L1-L4 提问建议：什么样的问法能拿到什么深度的回答；
- 口径规范：项目名 / 时间窗 / 业态 / 阶段的标准表述；
- 挑战结论的正确姿势：发现数据不对怎么沟通（贴出数据来源、说明你的样本、对比口径）；
- 数据底线说明：什么场景会拒绝回答（无数据 / 样本不足 / 口径不一致）；
- 反馈渠道：Bad case 怎么提、加新场景怎么提。
10.7 接下来读什么
Section titled “10.7 接下来读什么”- 想看 cost-query 完整设计方案 → 读 附录 A · cost-query 设计方案速读；
- 想看脚手架代码结构 → 读 附录 B · 脚手架代码结构；
- 想查术语 → 读 附录 C · 术语表。
Part 10 完。读完应能回答：“立项 / 第 1 个月 / 上线前的检查清单各有哪些、12 个常见踩坑怎么应对、维护手册和用户手册各包含哪些”。