CHAPTER 03

CLI + 本体

CLI → 为 AI 设计的指令系统，业务和技术的胶水

本体 → 让 AI 更精确地理解和分析物理世界

P23 – P41 · 19 页 · 含「现场实战 B」手搓 CLI 问数 · 货值三倍 bug

P23 · 第三章开篇

CLI，是给 Agent 设计的指令系统

以前的 CLI 是给程序员看的；现在的 CLI，是给模型看的 —— 它在业务操作和技术指令之间架了一座桥。

📖 维基百科 · 命令行界面（CLI）

命令行界面是一种通过逐行文本命令与计算机程序交互的方式。用户输入命令、程序返回文本结果 —— 它出现得比图形界面更早，长期是程序员和系统管理员的主要工具。

传统 CLI · 给人用

· 服务对象：人类开发者
· 设计目标：覆盖所有功能选项
· 输出：给人读的文本日志、报错堆栈
· 命令来自：API / 工具的能力清单

AI 原生 CLI · 给模型用

· 服务对象：Agent（大模型）
· 设计目标：完成一个业务动作
· 输出：JSON + error_code + hint，机器可解析
· 命令来自：业务任务，不是 API 路径

业务操作

"查一下这个项目的去化率"

CLI

AI 更容易理解的桥

技术指令

DSL → SQL → 数据库

所以这是一次重新定义：CLI 没变形态，但服务对象从「人」换成了「模型」—— 观察 Claude Code / openclaw，它们执行指令最终都落到系统命令行。

P24 · 一个真实对比 · 杀手论据

同一个问题，两种发起方式

用户的业务问题是一样的 —— 区别只在于：AI 把它翻译成一长串脚本调用，还是一条 CLI 指令。

👤 用户提问 "帮我审一下『深圳湾一号 · 信宏城一期』这个清单的控制价"

AI 把这句话翻译成执行指令 —— 脚本模式 vs CLI 模式，效果天差地别 ↓

脚本模式 · 面向「文件」

# AI 得先知道脚本在哪、叫什么、参数怎么排 python3 /Users/x/.claude/skills/cost-audit/scripts/run_price_deviation_pipeline.py --project-name 深圳湾一号 --bq-name 信宏城一期 --mode indicator --coverage 1.0 --encoding utf-8-sig

· 含长路径 + 一堆参数，单次约 200 字符
· 路径猜错、Windows 引号、编码错全在这行翻车

CLI 模式 · 面向「指令」

# AI 只说「做什么」，不管脚本在哪 report-gen price create --project 深圳湾一号 --bq 信宏城一期 --coverage 1.0

· 统一命令 report-gen，单次约 100 字符
· 命令在 PATH 里 —— 无路径、单入口

真正的差距在累加 —— 一次「成本问数」请求，AI 往往要调 4 次工具（取数 / 算指标 / 拼报告 / 存文件），每次都要拼一遍路径：

脚本模式

200

≈ 800 字符

CLI 模式

100

≈ 400 字符

① 调脚本要拼路径，② 脚本生成文件还要再拼一次路径 —— 调用次数越多，问题越凸显：上下文被一行行长路径塞满，直接拖累 AI 的注意力和指令遵循能力。

P25 · 控制价审核 CLI 化

一个完整案例：控制价审核的 CLI 设计与优化结果

左边是把 9 步审核流程整体设计成的 CLI 命令面，右边是 CLI 化前后的实测对比。

① 控制价审核 CLI 设计 · 业务步骤 → report-gen 命令

# 定位与准备

1定位招标清单 → report-gen resolve-bq

2选审核模式 → report-gen confirm-audit-mode

3选对标历史项目 → report-gen confirm-similar

4设采样范围 → report-gen prefetch-benchmark

# 分析与核查

5扫造价指标 → report-gen scan

6异常指标归因 → report-gen insight

7单价偏离核查 → report-gen price create/poll/fetch

# 出报告与展示

8生成审核报告 → report-gen report

9工作台展示 → report-gen canvas open

report-gen 是统一命令、装在 PATH 里；每步业务动作 = 一个子命令，price 异步任务拆 create/poll/fetch。

② 优化结果 · 同项目脚本模式 → CLI 模式

实际用时

GPT-5.5 · 同一审核任务

79m→15m

错误率

工具调用失败占比

11%→0%

Token 消耗

完成整套审核

13M→2.9M

临时补丁脚本

模型出错时手写补洞

6→0

读源码次数

模型猜内部实现

96→0

GPT-5.5 + CLI 做到 0 报错、0 补丁、0 读源码 —— production-ready；弱模型 Qwen 同样降本 3 倍以上。

P26 · 改善的本质

CLI 化，把模型的动作空间收窄了

从"读文档、找脚本、拼命令、写临时脚本"，变成"调固定子命令 + 读结构化摘要"。

脚本模式下的问题	CLI 化后的改善	具体例子
猜脚本路径失败	CLI 在 PATH 里，模型不需知道物理位置	`report-gen price create` 直接能跑，不用先 `ls` 满地找脚本
Windows 路径 / 引号出错	CLI 接参数、内部处理路径	模型不再写 `"C:\Users\...\"` 这种被引号转义掉的路径
模型试图改 Skill 源码	Skill 目录无脚本可改 —— 物理隔离	模型想改 `_rewrite.py` 兜底 —— 现在目录里根本没有 .py
JSON / GBK 编码混乱	CLI 统一封装读写编码	不再出现 `UnicodeDecodeError: 'gbk'`，模型不碰大 JSON
字段名靠猜，KeyError	CLI 输出稳定 schema	模型不再猜 `dimension` / `业态` 这种字段名

核心机制：物理隔离强于文档约定 —— 不靠提示词求模型别乱来，而是让它"无路可走，只能走对的那条"。

P27 · 设计范式 · 飞书真实 CLI

好 CLI 不是 API wrapper，是 AI 的业务动作接口

命令树第一层是业务对象（文档 / 多维表格 / 知识库），不是 API URL —— 下面是飞书 CLI 的真实命令清单与调用示例。

① 飞书 CLI 命令清单（节选）

# 身份认证

feishu whoami · login · logout

# 文档

feishu create_doc <title> [folder]

feishu get_doc <document_id>

feishu add_blocks <doc_id> <json>

feishu insert_image <doc_id> <path>

# 多维表格

feishu create_bitable · create_table

feishu create_record · list_records

# 知识库

feishu list_wiki_spaces · create_wiki_node

feishu 是统一命令前缀，后面跟业务动词 —— 不是 POST /open-apis/docx/v1/... 这种 API 路径。

② 业务 SOP：「把销售达成报告发布到飞书」

1

确认身份能发文档

feishu whoami

查当前是不是「用户身份」—— 不是就先 login，否则建出来的文档别人看不到。

▼

2

在「销售月报」文件夹建文档

feishu create_doc "5月销售达成分析" <folder>

新建一篇空文档，拿到 doc_id 和可分享的 doc_url。

▼

3

把报告正文写进去

feishu add_blocks <doc_id> 报告内容

把分析结论、达成率表格分段追加进文档 —— 局部追加，不整篇覆盖。

▼

4

把图表配进去

feishu insert_image <doc_id> chart.png

插入达成率柱状图 —— 一篇图文并茂的飞书报告就发布好了。

这一串就是 Skill 里写的 SOP：什么业务步骤、用哪个命令、每步要干成什么。AI 照着走，不用自己猜 API。

飞书 CLI 的范式：左边一组业务命令，右边把它们编成业务 SOP —— Skill 只管「按这个顺序，每步调哪个命令」。

P28 · 从 CLI 到本体

为什么要做本体：模型会"飘"

模型有通识，但不够 —— 处理具体业务问题时输出不稳定。

同一个问题问两次 —— 模型两次给的口径，往往不一样：

"土建合同金额多少？"

Round 1

给了含税价 ¥2.4 亿

Round 2

又给了不含税 ¥2.12 亿

小结：含不含税没说死，两次差出一整个税点。

"这个项目单方成本？"

Round 1

按建筑面积除 → ¥4,250

Round 2

按可售面积除 → ¥5,600

小结：分母选哪个没定义，单方差一大截。

"土建总成本是多少？"

Round 1

只加末级科目 → ¥2.4 亿

Round 2

父子科目一起加 → ¥4.8 亿

小结：没说只算末级，金额直接翻倍。

每一次「飘」都是一次口径没对齐 —— 本体就是把含税口径、单方分母、末级科目这些规则一条条钉死，让 Round 1 和 Round 2 答得一模一样。

P29 · 概念定义

本体（Ontology）到底是什么

左边两个权威定义，右边用一张图把本体结构画出来 —— 以「成本合同」为例。

📖 维基百科 · 信息科学中的本体

对一个领域内概念、类别及其关系的形式化表示 —— 给出一套共享词汇，对类型、属性、个体、关系建模。

描述逻辑里 K = (TBox, ABox)：TBox 是概念模式，ABox 是事实断言。

🏢 Palantir · Foundry Ontology

组织的「数字孪生」 —— 把数据集映射到现实世界的对象、事件、流程，做成所有应用、AI 共用的语义层。

四个核心：对象 / 属性 / 链接 / 动作 —— 对象有业务含义，LLM 能直接查询推理。

本体结构图 · 以「成本合同」为例

📄 成本合同

对象 / 实体 —— 业务里的一个「东西」

围绕这个对象，本体记录三类信息 ↓

属性

签约金额
含税 / 不含税
结算状态

关系 / 链接

属于某项目
挂某成本科目
对应某供应商

规则 / 约束

结算 = 签约 + 补差
算成本默认
用不含税

一句话：本体就是把「业务世界长什么样」用这样一张结构图写下来 —— 让 AI 不靠通识猜，而是按业务真相推理。

P30 · 本体的两个概念

本体 = TBox + ABox

来自描述逻辑（Description Logic）的经典划分 —— 一个本体知识库 K = (TBox, ABox)。就这两个概念，没有第三层。

	TBox · 术语层	ABox · 断言层
是什么	Schema / 数据模型 —— 定义有哪些类、属性、关系、约束规则	Instance / 业务主数据 —— 描述真实数据的特征、数据之间的关联关系
回答的问题	「这个领域有哪些概念、它们结构上怎么定义」	「现实中具体有哪些东西、它们的值和关系是什么」
成本合同举例	成本合同这个类，有「签约金额 / 含税 / 结算状态」等属性；规则：结算金额 = 签约金额 + 补差	「土建总承包合同 HT-2026-018」这份具体合同 —— 签约 2.4 亿、属于深圳湾一号项目、挂在土建科目下、对应 XX 建工
稳定性	更稳定 —— 像字典/数据模型，不常变	更动态 —— 像业务流水，随真实数据不断变

TBox 定义

「术语组件」—— 用一套类与属性，把领域词汇与结构定义出来。是定义性的，像一本字典。

ABox 定义

「断言组件」—— 在 TBox 模型之上，陈述具体事实：某个实例属于哪个类、有什么值、和谁有关系。

TBox 管「概念该长什么样」，ABox 管「现实里真实发生了什么」 —— 两者合起来才是一个完整的本体知识库。

P31 · 本体 YAML 示例 ① · TBox

TBox 示例：成本问数的类型与约束

TBox 定义成本领域的类、属性、约束。上面是 TBox 定义，下面看一个业务问题怎么转成 DSL —— DSL 正是对 TBox 定义的「应用」。

TBox · 成本问数模式层

# TBox · 成本科目类型与约束
tbox:
  classes:
    - id: Class.ProjectIndicator
      label: 项目成本指标
      dimensionProperties:
        - {name: costSubject, label: 成本科目}
        - {name: isEndCost,   label: 是否末级科目}
        - {name: productType, label: 业态}
      measureProperties:
        - {name: jianAnAmount, label: 建安造价费}
        - {name: areaUnitCost, label: 建面单方}
  axioms:          # 口径铁律
    - rule: "默认只取末级科目 isEndCost=1"
    - rule: "父子科目不可混算（防重复）"

业务查询语言 → 查询 DSL（应用 TBox）

# ① 用户的业务问句
"深圳住宅的建安单方是多少？"

# ② 转成查询 DSL（每个字段都来自 TBox）
{
  cube: ProjectIndicator,   # ← TBox 的类
  measures: [areaUnitCost],  # ← TBox 属性
  filters: [
    {productType: 住宅},   # ← TBox 维度
    {city: 深圳}
  ]
  # isEndCost=1 由 axiom 自动补
}

DSL 不是凭空写的 —— 它的每个 cube、measure、filter 都必须在 TBox 里有定义。TBox 是 DSL 的「词典」。

P32 · 为什么需要 ABox

讲个故事：如果没有 ABox，会发生什么

成本经理抛来一个再正常不过的问题 —— 看看只有 TBox（Schema）、没有 ABox 的 AI 会卡在哪。

👤 成本经理问 "深圳湾一号的钢筋含量偏高，到底是为什么？"

😟 没有 ABox 的 AI

✓查到了 —— 钢筋含量 58kg/㎡，这一步靠 TBox 就够。

✗再往下问「为什么高」就卡住了 —— 它不知道这个项目具体层高多少、有没有地库。

✗只能用通识空答：「可能是设计原因、可能是标准高」—— 像没去过现场的实习生。

✗给不出能落地的结论，成本经理还得自己去翻数据。

😎 有 ABox 的 AI

✓同样查到 58kg/㎡，且知道同城样本只有 45 —— 确实偏高。

✓顺着 ABox 里的关联关系查到：这个项目层高 3.6m（样本 3.0m）。

✓再沿替代关系比对：当前木模方案，换铝模可降 8%。

✓给出结论：层高刚性 + 模板可优化 —— 有据可依、能落地。

差别就在这 —— ABox 装的是「这个项目具体长什么样、和谁有关」。没有它，AI 只会查数，不会归因。

P33 · 本体 YAML 示例 ② · ABox

ABox 示例：一个下钻查询动作

左边是 ABox 实例与关系的 YAML，右边演示一次下钻 —— 顺着 ABox 的「共振 / 替代」关系，从异常指标追到根因。

ABox · 成本科目实例 + 关系

# ABox · 真实业务事实
abox:
  instances:
    - {id: 土建工程, isEndCost: 0,
       amount: 2.4亿, areaUnitCost: 4250}
    - {id: 钢筋工程, parent: 土建工程,
       isEndCost: 1, contentRatio: 58kg/㎡}
  relations:
    # 共振：特征↑ 带动多个科目↑
    - {type: resonance, driver: 结构层高,
       affects: [钢筋工程, 混凝土工程]}
    # 替代：两个方案二选一
    - {type: substitute,
       options: [铝模方案, 木模方案]}

下钻查询：钢筋含量为什么偏高？

# Step 1 · 异常定位（L1/L2）
钢筋含量 58kg/㎡ > 同城样本 45  ⚠

# Step 2 · 沿 resonance 共振边下钻
钢筋工程 ←resonance← 结构层高
  → 查得该项目层高 3.6m（样本 3.0m）

# Step 3 · 沿 substitute 替代边比对
当前=木模方案，可选 铝模方案
  → 铝模含量低 8%，但需评估成本

# 结论：层高刚性 + 模板可优化

下钻不是让 AI 背科目 —— 是让它沿着 ABox 里的共振 / 替代关系，一步步追到根因。

P34 · ABox 的图谱结构

ABox 长什么样：一张成本科目图谱

把上一页的实例和关系画出来 —— ABox 本质就是一张节点（科目/特征）+ 边（共振/替代/父子）的图。

这张图谱里有三类边

父子 · contains

土建工程 → 钢筋 / 混凝土 / 模板 —— 科目逐级拆解。

共振 · resonance

结构层高 → 同时带动钢筋、混凝土 —— 一个特征驱动多个科目。

替代 · substitute

铝模 ⇄ 木模 —— 互斥方案，归因时要拉出来比对。

宽表把关系拍平了 —— ABox 图谱把它重新显式记下来。

P35 · 选型 · 建到哪一层

什么时候只建 TBox，什么时候要上 ABox

不是每个场景都要做完整本体 —— 按任务能力分级，决定建到哪一层。

只建 TBox 就够

· L1 事实查询 —— 查一个项目、科目的值
· L2 多维对比 —— 区域均值、项目排名、区间
有 Schema、有口径，就能查、能比

才需要上 ABox

· L3 归因分析 —— 沿共振/替代关系下钻根因
· L4 决策建议 —— 控价、谈判、降本建议
要顺着实例间的真实关系推理

查询类型	对接方式	典型场景
简单查询	CLI 对接 API	消息、待办 —— 取一条确定的数据，端点固定就够
复杂查询	CLI 对接宽表（+ 本体）	资管台账、交易台账、合同 / 成本台账 —— 要多维组合、下钻归因

一句话：简单查询 CLI 接 API，复杂查询 CLI 接宽表；能力只到 L1/L2 建 TBox，要做 L3/L4 才补 ABox。

P36 · 实战 B · 业务设计现场实战

售楼问数 sales-query · 6 张宽表 + 18 题

复刻「成本问数」的成熟做法 —— 不发明新东西,把售楼现有宽表 + 业务问题集打通成可问数的 Agent。

宽表(物理表)	Cube 名(本体)	行数	典型问数维度
dwd_s_salesbudget · 销售目标	SalesBudget	221	项目 / 业态 / 年月
dwd_s_room · 房间	Room	1,562	项目 / 楼栋 / 状态 / 户型
dim_s_building · 楼栋	Building	46	项目 / 业态
dwd_s_projectvalueabledetail · 楼栋货值	ProjectValue	207	项目 / 版本 / 层级
dwd_s_order · 认购	OrderDetail	142	项目 / 类型 / 状态 / 顾问
dwd_s_contract · 合同	ContractDetail	51	项目 / 类别 / 状态 / 顾问

L1 事实查询 · 8 题

"中建大公馆 2026 全年签约目标"、"各项目认购套数排名"。

L2 多维分析 · 7 题

"光谷天地每月认购金额趋势"、"按业态分组成交占比"。

L3 归因判断 · 3 题

"基准版项目全盘去化率"、"目标完成率风险研判"。

18 题端到端验证 100% 准确(8/8 + 7/7 + 3/3) —— 这是真库实测,不是 demo 跑通。

P37 · 实战 B · 架构设计现场实战

三层架构 · SKILL + CLI/DSL + 本体

用户问数 → SKILL 触发 → CLI 把 DSL 编译成 SQL → 本体自动注入护栏 → MySQL 真库取数。

用户问

"按置业顾问
统计成交"

→

① SKILL

命中触发
拼 DSL JSON

→

② CLI/DSL

find/aggregate/rank
编译 SQL

→

③ 本体

schema.yaml
注入护栏 WHERE

→

MySQL

真库取数

① SKILL · 触发与编排

YAML description 写触发词、正文写调用流程。不连数据库、不写 SQL,只输出 DSL JSON 给 CLI。

② CLI / DSL 引擎

三个一级指令:find(行级)/aggregate(GROUP BY)/rank(Top-N)。接口窄、错不了。

③ 本体 schema.yaml

6 个 Cube 含 defaultFilters(护栏) + friendlyAlias(中文短名) + routed measure(单价路由)。

🔒 4 道口径护栏(自动注入,用户无感)

① OrderDetail/ContractDetail.Status=激活 — 排除关闭单,避免业绩翻倍
② OrderDetail.OrderType=认购 — 排除小订,避免混口径
③ ProjectValue.Level=3 AND IsBenchmark=1 — 避免三倍累加 + 多版本叠加 ★ 见下一页 P40 真实 bug
④ SalesBudget.Month<=12 — 排除全年汇总行(Month=13),避免翻倍

把这页 + schema.yaml 给 Claude Code / Codex —— 同一套问数方法可快速复制到任何新业务场景。

P38 · 实战 B · 目录结构 & SKILL/schema 概要

把这套复制走 · sales-query 资产

本体目录 + 两份核心契约(SKILL.md + schema.yaml) —— 复制到任何新业务,改 schema 就行。

📁 目录结构

.claude/skills/sales-query/
├── SKILL.md                  98 行
├── scripts/
│   ├── schema.yaml          326 行 · ★ 本体
│   ├── query.py           1,896 行 · DSL 引擎
│   └── cli.py                180 行 · SQL 执行
├── references/
│   ├── dsl-spec.md           DSL 关键字 + 自救
│   ├── query-guide.md        问数指南
│   └── schema/              # 6 个 Cube 各一份
│       ├── SalesBudget.md
│       ├── Room.md / Building.md
│       ├── ProjectValue.md
│       ├── OrderDetail.md
│       └── ContractDetail.md
└── tests/
    ├── questions.yaml        18 题 baseline
    └── run_e2e.py            端到端测试

🤖 SKILL.md + schema.yaml 概要

SKILL.md(98 行) · 6 段

① YAML description 触发词 ② DSL 三指令导览 ③ 渐进披露:何时读 dsl-spec / schema md ④ Cube 速查表 ⑤ 7 类常见错+自救 ⑥ 不允许 JOIN 跨域

schema.yaml(326 行) · 每个 Cube 4 块

OrderDetail:
  table: dwd_s_order
  dimensions: [parentProjName, zygw, ...]
  measures: [cjTotal, cjBldArea, dealPrice]
  defaultFilters:        # 口径护栏
    - { field: status, value: 激活 }
    - { field: orderType, value: 认购 }
  friendlyAlias:         # 中文短名
    projectName: parentProjName

schema.yaml 是核心 —— 业务铁律(护栏)、字段映射(短名)、单价路由都写在这一份 YAML 里,改它就能复制到新业务。

P39 · 实战 B · DSL 设计 & 典型问答

DSL 设计 · find / aggregate / rank 三指令

通用 DSL,接口窄到只有 3 个一级指令 —— 模型填 JSON,引擎编 SQL,护栏自动注入。

DSL 指令	用途	关键字段	对应 SQL 语义
`find`	行级查询	cube · dimensions · filters · order · limit	SELECT ... WHERE ... LIMIT
`aggregate`	聚合分组	cube · dimensions · measures · filters · having · having	SELECT ... GROUP BY ... HAVING
`rank`	Top-N 排名	cube · rankBy · dimensions · measures · limit	SELECT ... ORDER BY ... LIMIT N

💬 4 个典型问答 · 真库返回

Q1 · 简单计数 · find

"中建大公馆 2026 全年签约目标"

sales-query find --dsl '{
  "cube":"SalesBudget",
  "filters":[
    {"member":"projectName","operator":"contains","values":["中建大公馆"]},
    {"member":"year","operator":"equals","values":[2026]},
    {"member":"month","operator":"equals","values":[13]}
  ],
  "dimensions":["budgetContractAmount"]
}'

→ 2600 万

Q2 · 分组排名 · aggregate

"各项目有效认购总金额"

sales-query aggregate --dsl '{
  "cube":"OrderDetail",
  "dimensions":["parentProjName"],
  "measures":[{"member":"cjTotal","agg":"sum"}]
}'

→ 光谷天地 38,236,887 / 售楼考核 53,985,433…
自动加 WHERE Status=激活 AND OrderType=认购

Q3 · 时间分桶 · aggregate

"光谷天地每月认购金额趋势"

{
  "cube":"OrderDetail",
  "dimensions":[{
    "member":"qsDate",
    "granularity":"month"
  }],
  "measures":[{"member":"cjTotal","agg":"sum"}]
}

→ 1月 112万 / 2月 187万 / 3月 223万 / 4月 1326万

Q4 · 计算度量 · 去化率

"基准版项目全盘去化率"

measures:[
  {"member":"soldValue","agg":"sum","alias":"已成交"},
  {"member":"totalValue","agg":"sum","alias":"全盘"},
  {"alias":"去化率",
   "calc":"${已成交}/${全盘}"}
]

→ 光谷天地 10.0% / 中建大公馆 0%
自动加 WHERE level=3 AND isBenchmark=1

3 个指令 + JSON 填空 —— 模型不写 SQL,只填结构化字段;护栏由引擎自动注入,口径不会错。

P40 · 实战 B · 真实踩坑现场实战

真实 bug 复盘：货值三倍累加 · 84 万 vs 28 万

这是售楼问数 sales-query 端到端测试中暴露的最有戏剧性的口径错误 —— 也是 defaultFilters 护栏存在的最好理由。

❌ AI 直接写 SQL

SELECT SUM(TotalValue)
FROM dwd_s_projectvalueabledetail
WHERE IsBenchmark=1

结果：84,900,000 元 (8490 万)
SQL 语法 100% 正确
但结果错 3 倍

✅ DSL 引擎自动加护栏

SELECT SUM(TotalValue)
FROM dwd_s_projectvalueabledetail
WHERE IsBenchmark=1
  AND Level=3  -- 自动加

结果：28,300,000 元 (2830 万)
用户不传 level，本体自动补
口径正确

🔍 根因 · 宽表反范式的代价

dwd_s_projectvalueabledetail 同一份货值在 Level=1/2/3 三层各存一份等额金额（楼栋明细/分区明细/版本总计行）。
不锁 Level 直接 SUM → 同一笔货值被累加 3 次。

🛡️ 解法 · schema.yaml 写护栏

ProjectValue:
  defaultFilters:
    - field: level
      value: 3
      unless: [level, hierarchyCode]
      hint: "默认 level=3
避免三倍累加"

护栏不是枷锁，是默认安全值 —— 业务铁律写在本体里，模型再厉害也绕不过。这是"本体即代码"的真实价值。

P41 · 第三章小结 · 回收 P22 伏笔

P22 的两个问题 · DSL 当场答出来

实战 A 答不了的，实战 B 一行 DSL 解决。这就是"API 固化 vs 本体灵活"的核心对比。

✅ 问题 ① · 按置业顾问聚合

sales-query aggregate --dsl '{
  "cube": "OrderDetail",
  "dimensions": ["zygw"],
  "measures": [
    {"member":"rowCount","agg":"count"},
    {"member":"cjTotal","agg":"sum"}
  ]
}'

置业顾问	套数	成交总额
系统管理员	57	8,135 万

✅ 问题 ② · 项目成交总价汇总

sales-query aggregate --dsl '{
  "cube": "OrderDetail",
  "filters": [
    {"member":"projectName",
     "operator":"contains",
     "values":["光谷天地"]}
  ],
  "measures": [{"member":"cjTotal","agg":"sum"}]
}'

项目	套数	成交总额
光谷天地	30	5,246 万

能力	实战 A · API 模式	实战 B · CLI + 本体
查明细台账（按项目/日期筛选）	✅ 快、稳、口径固定	✅
按任意维度聚合（GROUP BY）	❌ 没开端点就答不了	✅ aggregate 指令
排名 Top-N	❌	✅ rank 指令
加一个新查询维度	改 API + 重启服务	换 DSL 参数，0 改代码
业务口径（如只算激活单）	端点里写死	本体 defaultFilters 自动护栏

API 胜在稳定可控、口径写死；CLI+本体胜在灵活、新维度即问即答 —— 这就是垂直 Agent = Skill + 本体 + CLI 的核心价值。