07-模式手册

Part 7 · 模式手册

SKILL.md 讲业务表达层，query-guide.md 讲具体怎么取数。模式手册是 query-guide 的核心——把”什么业务问题对应哪条命令”列成表，LLM 命中即抄。

7.1 为什么模式手册比 SOP 流程图更适合 LLM

SOP 流程图的问题

传统业务系统喜欢画 SOP 流程图：

用户问题
  │
  ▼
是否含价格类业务词？
  ├─ 是 → 是清单价还是采购价？
  │        ├─ 清单价 → 走 BqUnitPrice
  │        └─ 采购价 → 走 TalentMachinePrice
  └─ 否 → 是否含指标类业务词？
           ├─ 是 → ...
           └─ 否 → ...

LLM 执行这种流程图的痛点：

每个分支节点都是一次推理：5 层分支 = 5 次推理 + 累积误差；
难以处理复合问题：“X 项目的钢筋单价和综合单价”既是清单价又是指标 → 流程图卡住；
难以维护：加一种新场景要重画图、改多个分支；
可调试性差：LLM 走错了不知道在哪个节点错。

模式手册的优势

| ID | 命中关键词 | 命令模板 |
|---|---|---|
| M1.1 | X 项目 单指标（X 单方 / 含量 / 造价）| agg-project-indicator + {...} |
| M1.6 | 区域 + 面积 + 多指标 | agg-project-indicator + measureGroups + {...} |
| M2.3 | 项目内 X 清单 Top-N | agg-unit-price + groupBy + orderBy + {...} |

LLM 拿到问题：

扫一遍模式表的”命中关键词”列；
找到最匹配的一条（或几条）；
抄”命令模板”列填参数。

单次匹配 + 填空，比”5 层分支推理”快得多、错率低得多。

心理学解释

模式手册本质上把”决策”问题转化成”模式识别 + 模板填空”问题。后者是 LLM 的强项。

类比：考试时给你”5 道大题让你自由发挥”和”50 道选择题”——选择题平均分一定更高。

7.2 模式的提取方法

方法 1：从测评集反推（推荐）

最可靠的方法：先有测评集，再从测评集反推模式手册。

操作步骤：

收集 30-50 道代表性问题（业务方真实问题 + 团队脑暴）；
每道问题人工解出最优命令路径（你和业务方一起 walk through）；
按”命令 + 关键参数组合”聚类——同命令 + 同核心参数集 = 一个模式；
每个聚类抽出关键词触发器：用户问什么样的问题会走这个模式？
写成表格的一行。

cost-query 实例：

测评题 Q1: 深圳10万平米以上项目的土建单方造价和钢筋含量指标是多少？
人工解：
  cost-query agg-project-indicator --params '{
    "cityName": "深圳",
    "buildAreaMin": 100000,
    "groupBy": ["projectName"],
    "measureGroups": [
      {"alias": "土建单方造价", "bzItemName": "土建工程费", "isEndCost": 0, "indicatorType": "建面单方"},
      {"alias": "钢筋含量",     "bzItemName": "钢筋",       "isEndCost": 1, "indicatorType": "含量"}
    ]
  }'

聚类：「区域 + 面积 + 多指标」
触发关键词：cityName + buildAreaMin/Max + 多指标
模式 ID：M1.6

聚类时同模式可能涵盖 3-5 道测评题；不同模式之间触发关键词应该清晰可区分。

方法 2：按 cube + verb 切分（次选）

如果没有测评集，先按 cube × verb 切分模式空间：

cube	find（明细）	agg（汇总）
ProjectIndicator	—	M1.*
BqUnitPrice	M2 明细	M2 聚合
TalentMachinePrice	M3 明细	M3 聚合
…	…	…

然后每个 (cube, verb) 组合下细分 1-5 个具体模式。

这种方法的问题：容易漏掉复合问题模式（一个问题涉及多 cube）。所以仍推荐从测评集反推。

方法 3：从生产 Bad case 沉淀（持续治理用）

上线后用户问的问题会暴露原模式手册没覆盖的场景。流程：

业务方反馈”这种问题答不好”；
在测评集加该问题；
人工解出最优路径；
看是不是已有模式没匹配上 → 调触发关键词；或是不是缺新模式 → 加新模式 M2.x；
跑测评验证。

7.3 模式条目的字段约定

每条模式包含：

字段	内容	例
ID	M<类>.<序号>	M1.6
命中关键词	用户问题里出现什么关键词触发	”区域 + 面积 + 多指标”
命令模板	直接抄就能跑的命令（含 placeholder）	agg-project-indicator + measureGroups + {…}
关键参数说明	哪个参数填什么	cityName=用户原话；bzItemName 必须查 §2.2 标准词
典型场景例	1-2 个真实问题	”深圳 10 万平米以上项目的土建单方和钢筋含量”

槽位标注规则

每个 placeholder 按风险标注，告诉 LLM 怎么填：

标注	含义	例
`<原话>`	低风险，直接抄用户原话	`cityName="深圳"`
`<原话+contains>`	低风险但需 contains	`productTypeName="住宅"` 匹配”住宅-超高层”
`<原话×10000>`	低风险 + 单位换算	”10 万方” → `buildAreaMin=100000`
`<查附录B.x>`	中风险，参考对照表	`tmTopType=` 查附录
`<查附录B.x 必查>`	高风险，必须从对照表抄	`bzItemName="土建工程费"`
`<auto:find-dimension>`	长尾词，对照表没有 → 探测	—

7.4 维度风险分级

模式手册里高频出现”高风险词必须先标准化”——这套风险分级是模式手册的前置条件。

三档风险

风险等级	处理	例
低风险	跳过标准化，直接到执行；返回结果时校验标准名	钢筋 / 混凝土 / 防水 / 模板 / 住宅 / 地下室 / 明确项目名 / 明确城市名
中风险	可先直查；返回混杂时退回标准化	车库 / 商业 / 办公 / 安装 / 土建 / 结构 / 门窗 / 保温
高风险	必须先标准化（find-dimension）	建安 / 精装 / 粗装 / 公区 / 刚需/改善/高端住宅 / 钢筋大类 / 人材机分类与规格

风险分级的依据

唯一性：标准词只有一个 → 低风险；可能对应多个 → 高风险；
歧义性：词义在不同上下文不同 → 高风险；
跨模板差异：在不同业务模板里映射不同 → 高风险（如”建安”在房开 = 建筑安装工程费，在东航 = 建筑工程 + 安装工程）；
业务方反馈：业务用户经常用这词的什么变体 → 高频变体 = 高风险。

你的领域怎么分级

先列出业务用户高频用词，对每个词问：

标准词唯一吗？
同样的词在不同子领域语义一致吗？
业务用户常用这词的同义词、缩略词、别名是什么？

回答 1=否 / 2=否 / 3=多个变体都进入高风险。

cost-query 实例：

“建安”高风险：可能映射”建筑安装工程费”/“建筑工程”/“安装工程”，跨模板不一致；
“钢筋”低风险：标准词就是”钢筋”，几乎没歧义。

7.5 复合问题判别与拆段

用户经常问”X 项目里 Y 是多少” / “X 和 Y 哪个更便宜” 这种复合问题——一个提问含多个子查询。

识别复合问题

含以下关键词的提问通常是复合问题：

显式连接词：“其中”、“分别”、“再看”、“先 X 再 Y”、“对比”、“vs”；
嵌套表述：“X 项目的”+“Y 是多少”（先锁项目再问指标）；
对标类：“对比历史” / “对比同业态” / “对比可比项目”（先锁画像再找可比集合）；
口径并列：“只看 X 业态” / “按项目级看 vs 按业态看” / “整体 X vs 住宅 X”。

拆段处理

显式连接词类：拆两段串行执行。

用户问题："广东省内有土方开挖项目的有哪些？其中 T-总部大楼项目的综合单价是多少？"

段一：M2.6（含某清单的项目）
  cost-query agg-unit-price --params '{"keyword": "土方开挖", "provinceName": "广东", "groupBy": ["projectName", "cityName"]}'
  → 命中 5 行（含 T-总部大楼）

段二：用段一结果作输入，匹配 M2.4（项目内某清单的综合单价）
  cost-query agg-unit-price --params '{"projectName": "T-总部大楼", "keyword": "土方开挖", "groupBy": ["bqName", "name"]}'
  → 命中 1 行：4.09 元/m³

口径并列类：必须 batch 双段，不能合并为单查。

用户问题："X 项目按项目级看建安单方和按业态看建安单方各是多少？"

batch 双段：
  段一 M1.9（项目级）：agg-project-indicator + bzItemName=建安 + isEndCost=0
  段二 M1.13（业态级）：agg-project-indicator + bzItemName=建安 + isEndCost=0 + groupBy=[productTypeName]

合并为单查的话 isJianAn 推断不一致（项目级要 0、业态级要 1），结果会错。

7.6 反模式黑名单

模式手册的反面：什么写法绝对不要用。

反模式的来源

测评 Bad case 沉淀：测评中 LLM 反复犯的错抽象成反模式条目；
DSL 编译器报错统计：报错最多的写法列出来；
业务用户反馈：用户说”这答得不对”的常见原因分析。

cost-query 反模式黑名单（query-guide §4.3，7 条）

#	触发条件	原因	改用
1	`dimensionName=TalentMachineType` + keyword 含价格类词	分类字典不含价格	agg-unit-price
2	verb=find + filters 含 measure 字段 gte+lte	find 不能做聚合后 having	agg-X + havingMin/Max
3	groupBy 含 measure 字段	measure 不是分组维度	移除该项
4	productTypeName operator=equals + 口语词	字典实际值是”X-Y”前缀化	改 contains
5	bzItemName contains “钢筋” 不显式 isEndCost	同名父子混算	显式 isEndCost=1
6	verb=find + cube=ProjectIndicator + 不限定 bzItemName	父子混算	显式 bzItemName + isEndCost
7	跨项目硬传 bzItemCode	跨模板编码不通用	改用 bzItemName + isEndCost

反模式条目的写法

| # | 触发条件 | 原因 | 改用 |
|---|---|---|---|
| 1 | <什么时候 LLM 会写这种错的> | <为什么这是错的，最好附数据后果> | <该用什么替代> |

触发条件：具体到字段 / 参数组合，不写”用户没注意时”这种含糊话；
原因：业务后果 + 数据后果都写（“会让 5 万㎡被 SUM 到 130 万㎡”）；
改用：直接给替代命令，不要给抽象建议。

反模式 vs 编译器自动行为

两者关系：

能用代码兜底的 → 做进编译器自动行为（如 ProjectIndicator 的 isEndCost 默认）；
代码兜不住的（场景太多 / 误判风险高） → 写进反模式黑名单让 LLM 自律。

双重保险最稳：编译器兜底 + 反模式提醒。cost-query 的 ProjectIndicator 父子混算就是双重保险——defaultFilters: isEndCost=1 + 反模式第 5-6 条。

7.7 query-guide.md 的整体结构

cost-query 的 query-guide.md 478 行，结构：

# 查询路径执行指南 v2

`cost-query` 事实取数手册。SKILL.md 负责业务表达，本文负责取数。

阅读路径：§0 必读铁律 → §1 模式手册（命中即抄）→ §2 槽位填法 → §3 fallback（未命中）→ §4 进阶

---

## §0 必读铁律
（6 条高频铁律，含 D1 机械撤宽 / D2 NULL 不切 cube / D3 撤宽即终点）

## §1 模式手册
### §1.0 路由判定（业务词 → cube 路由）
### §1.1 M1 项目指标（指令 agg-project-indicator）
### §1.2 M2 清单价格聚合
### §1.3 M2 清单价格明细
### §1.4 M3 人材机价格
### §1.5 M4 清单指标
### §1.6 M5 项目定位 / 建造标准
### §1.7 M6 清单项人材机消耗明细

## §2 槽位填法
### §2.1 标注规则（按风险分级）
### §2.2 科目对照表（bzItemName + isEndCost）
### §2.3 indicatorType 对照表（中文枚举）
### §2.4 时间词对照表（today=YYYY-MM-DD 实时计算）
### §2.5 人材机大类（tmTopType 仅 4 类）
### §2.6 业态判断（必须 contains 不能 equals）
### §2.7 价格类 keyword / tmName 选词拆词
### §2.8 默认参数兜底

## §3 标准流程（速查未命中时）
### §3.1 Schema 路由
### §3.2 槽位提取（特殊情况）
### §3.3 维度标准化
### §3.4 选指令
### §3.5 执行与错误自救
### §3.6 0 行 / 全 NULL 纠偏与撤宽

## §4 进阶
### §4.1 measureGroups 写法规约
### §4.2 切片器字段表
### §4.3 模型自律反模式（7 条）

## §5 参考文档

你的领域怎么组织

通用部分（直接抄）：

§0 必读铁律（D1-D3 跨领域通用）；
§3 标准流程（schema 路由 / 槽位提取 / 标准化 / 选指令 / 错误自救 / 撤宽）；
§4.1 业务封装的写法规约（如果你的领域有 measureGroups 类封装）；
§4.3 反模式（条目重写，框架通用）。

领域专属（必须重写）：

§1 模式手册（M1-Mn）；
§1.0 路由判定（业务词 → cube 路由）；
§2 槽位填法（你领域的对照表）；
§4.2 切片器字段表。

7.8 模式手册的演进节奏

第 1 阶段：3-5 个模式（MVP 周）

只覆盖核心 cube 的核心查询场景。配 5-10 道测评题验证。

第 2 阶段：10-15 个模式（第 1 个月）

每个 cube 至少 1 个 find + 1 个 agg 模式。配 20-30 道测评题。

第 3 阶段：15-20 个模式（第 2 个月）

按业务方真实问题分布扩展。复合问题、对标问题、口径并列问题进入手册。配 40-50 题测评。

第 4 阶段：20+ 个模式（生产稳定期）

按生产 Bad case 持续治理。每月 1-3 个新模式加入。

cost-query 目前 39 个模式（M1-M6）是持续治理累积的结果。急不得——堆模式不如打磨已有的稳定性。

7.9 检查清单

完成模式手册首版后逐项检查：

每条模式有唯一 ID（M<类>.<序号>）；
每条模式有清晰的”命中关键词”列；
每条模式有可直接抄的”命令模板”；
命令模板里的 placeholder 都标注了风险等级；
高风险 placeholder 都有对应的对照表（§2 槽位填法）；
复合问题判别规则已明文（“其中”/“分别”等关键词）；
反模式黑名单至少 5 条（覆盖测评中的 80% 错误模式）；
模式覆盖了至少 30 道测评题（覆盖率 = 命中的测评题数 / 总测评题数 ≥ 80%）；
query-guide.md 行数 < 600 行（cost-query 项目铁律：500 行；你的领域 MVP 阶段不强制，但超 800 行考虑分文件）。

7.10 接下来读什么

要看模式手册怎么和测评闭环 → 读 Part 8 测评驱动迭代；
要看 cost-query 完整 query-guide → 读 ontology-model 仓 query-guide.md；
要看脚手架的模板 → 读 scaffold/skill-template/references/query-guide.md.template。

Part 7 完。读完应能回答：“为什么模式手册比 SOP 好、怎么从测评集反推模式、模式条目怎么写、风险分级怎么做、复合问题怎么拆、反模式怎么沉淀、模式手册的演进节奏”。