SKILL-CLI-本体-AUI设计

🎤 SKILL + CLI + 本体 + AUI 设计 · 实践分享讲义

一句话定位：把一个「会回答问题的 AI」，设计成一个「能在业务里稳定交付的 Agent」。

完整版 Harness 科普：https://harness.brightw.cc/

6 章 · 约 65 页 · 含 3 处现场实战 · 2026-05-21

---

目录

• 第一章 · Harness 是什么（P3–P8）
• 第二章 · Skill 为什么这么厉害（P9–P22 · 含实战 A）
• 第三章 · CLI + 本体（P23–P41 · 含实战 B）
• 第四章 · Aha moment（P42–P51 · 含实战 C）
• 第五章 · 评测（P52–P57）
• 第六章 · FAQ（P58–P61）
• 附录 A · 实战 A 源代码资产（SQL 查询 API）
• 附录 B · 实战 B 源代码资产（CLI + 本体问数）
• 附录 C · 实战 C 源代码资产（报告 Skill）

---

第一章 · Harness 是什么

章节主张（过渡页）

Agent 不是更聪明的模型，而是包着模型的那层”壳”。

三阶段演进 · 笨循环

P3 · 什么是 Harness？

互动一分钟 · 带着问题听。 互动暖场，无信息密度。

要点：先别急着翻下一页，在脑子里给 Harness 一个定义。模型大家都熟，可让模型「能干活」的那层东西，叫什么、做什么？现场讨论 1–2 分钟，下一页揭晓答案。

P4 · Agent = Model + Harness

一个公式说清楚：

Agent = Model + Harness

• Model：单次预测机器——会预测下一个 token 的「大脑」。
• Harness：把原始力量转化为「有用功」的装置。
• Agent：不只是会说话，而是能干活。

模型本身没变——真正让它**从「会回答」变成「能交付」**的，是外面那层 Harness。

「你要么是模型，要么是 Harness，没有中间地带。」

P5 · Prompt → Context → Harness 工程

工程认知的三阶段：

阶段	关心什么
STAGE 01 · Prompt 工程	「我这一次怎么问」。prompt 是一次请求，不是契约——换个说法结果就飘。
STAGE 02 · Context 工程	管理模型「能看到什么」：RAG、记忆、上下文压缩。必要，但还不够——它只管输入。
STAGE 03 · Harness 工程（当前）	所有 agent 框架、工具调用拆开看，都是 Harness 的一部分。它管的是「模型怎么持续地干活」。

Takeaway： Prompt 管一句话，Context 管输入，Harness 管整个运行时——一层比一层往「系统」走。

P6 · 一个「笨循环」，解决 4 件根本的事

Harness 的心脏 = 笨循环（感知—行动—再感知）：

• ① 生成 → ② 评估 → ③ 再来。
• 给「单次预测机器」装上一个不停转的循环——这就是 Harness 的本质。

笨循环之上要解决 4 件根本的事：

1. 工具调用 —— 给模型装上「手脚」：能读文件、跑命令、调接口，而不只是输出文字。
2. 记忆与上下文 —— 记忆、检查点、上下文压缩，让长任务不会「转着转着就忘了」。上下文窗口分布：系统 / 记忆-检查点 / 当前任务 / 余量。
3. 注意力管理 —— 在大量信息里聚焦当下该看的，避免被噪音带偏。
4. 领域能力注入 —— Skill + 本体 + CLI，把垂直领域的知识与动作灌进来。 ← 今天的主角。

P7 · AI 工程化是一项复杂系统工程

核心论点： 决定最终效果的，从来不是单一模型——而是下面每一个变量的叠加。

模型能力 + 上下文管理 + 工具设计 + 权限控制 + 验证机制 + 组织流程 + 复盘指标

两个关键认知：

• 产出本身带随机性：Agent 不是确定函数——同样的输入，输出会浮动。这是它的天性，不是 bug。
• 部件好 ≠ 整机好：就像造飞机，每个零件按图设计好，也不代表飞机上天就能平稳飞行。

Takeaway： 所以必须有一套管理方法和标准理论，去支撑每一个部件的设计——而不是碰运气调参。

P8 · 像造一辆车一样造 Agent

详细类比 —— 汽车关键系统 → Harness Agent：

🚗 汽车关键系统	→	🤖 Harness Agent
⚙️ 发动机 —— 提供动力，但单靠它车跑不起来	→	模型本身 —— 提供智能/推理力，单靠它也只是「会说话」
🔄 变速箱 —— 把动力转成可控节奏；档位没配好，动力再大也顿挫	→	笨循环与调度 —— 把模型的原始输出转成可控的执行节奏
🛞 底盘车架 —— 承载一切的结构基座，决定整车稳不稳	→	文件系统与上下文工程 —— 承载任务状态与材料的结构基座
📡 电控 / 传感 —— 感知环境、反馈状态，让行驶可被纠正	→	工具调用与评测反馈 —— 感知结果、反馈状态，让每次行动可被纠正

Takeaway： 造车靠需求管理、子系统拆分、集成验证、可靠性评估这一整套系统工程方法——造 Harness Agent 同理。今天，我们从最可上手的一块 Skill 切进去。

📖 完整版 Harness 科普 → https://harness.brightw.cc/

---

第二章 · Skill 为什么这么厉害

章节主张（过渡页）

不是更长的 prompt，而是按需展开的「渐进披露」。

含「现场实战 A」手搓 sql-query-api

P9 · 什么是 Skill？

互动暖场，无信息密度。

要点：很多人第一反应——Skill 不就是把 prompt 写长一点、写细一点？如果只是这样，为什么 Anthropic 要专门给它一套结构、一套加载机制？现场讨论 1–2 分钟。

P10 · Skill 是给 AI 用的，不是给人用的

一句话定位：

Skill 不是「提示词扩展」，是把一个场景的经验 / 流程 / 工具 / 输出契约沉淀成可复用资产。

给人看的说明书 → 给 AI 用的能力包，服务对象是 AI。

四个维度看 Skill：

1. 固化「容易踩的坑」 —— 把调用工具、跑业务时反复踩的坑写成规则，让 AI 不再每次重新犯错。
2. 固化垂直知识与 SOP —— 把垂直领域的专业判断、标准操作流程沉淀下来，AI 按既定路径走。
3. 消除「业务转技术」的偏差 —— 业务需求 → 技术脚本之间的指令偏差，靠 Skill 的明确契约抹平。
4. 两个视角看 Skill —— 一个是 Anthropic 的 Skill 标准，一个是「为 AI 设计」的研究视角。

P11 · SKILL.md + 渐进披露三级加载

机制：三级加载

层级	内容	关键点
L1 · metadata	常驻上下文 · ~1500 token / 40 个 Skill	只有 name + description 一直在。AI 靠它判断「该不该用这个 Skill」。
L2 · SKILL.md	按需载入 · 完整操作说明	真的要操作 Excel 时，才把正文读进来——流程、规则、注意事项。
L3 · references / scripts	关联资源 · 脚本运行	脚本不进 context，由 Harness 执行，AI 只读它打印的 stdout。

实例：把 Excel Skill 目录展开

xlsx/                        # Anthropic 自带的 Excel 技能
├─ SKILL.md                  # ◀ L1 metadata（描述常驻） / 正文：怎么读写/格式化表格 ◀ L2
├─ references/               # ◀ L3 按需读
│  ├─ formulas.md            # 公式用法
│  └─ formatting.md          # 样式规范
└─ scripts/                  # ◀ L3 只跑不读
   └─ recalc.py              # 公式重算引擎

为什么要分层： 用户没碰 Excel 时，整个技能只占 SKILL.md 头部那几十字；一旦说「改下这张表」，才逐层把正文、formulas.md、recalc.py 取进来。能力可以很大，context 始终很小。

P12 · 六大结构性缺陷——都源自训练方式本身

模型能力越强、翻车越多——「能做」和「做得好」之间，有一道根本的鸿沟。

1. 知识时效性断层 —— 训练有截止日期。截止之后的库版本、API 变更、新规则，模型一概不知。
   • 例：某 Python 库今年升到 v3、API 全变了，模型仍按一年前的 v2 写法生成代码——一跑就报错。
2. 私有知识不可获取 —— 企业内部口径、业务流程、专有方法论从未进入训练语料——模型根本没见过。
   • 例：「单方成本」到底含不含税、按哪个口径算——这是公司内部定义，模型只能瞎猜。
3. 会踩坑（毒性遗产） —— 训练数据里混着大量错误写法，模型学了也会照犯——这是训练的「副作用」。
   • 例：网上大量 Word 代码用 WidthType.PERCENTAGE 设表格宽度，模型照学——实际导出宽度全错。
4. 缺质量标准与规范 —— 不知道什么算「好」、输入输出该长什么样——没有契约，结果就飘。
   • 例：同样让写「分析报告」，模型有时给 3 段、有时给 3000 字，结构每次都不一样。
5. 不知该用什么工具 —— 同一个任务有多条技术路径，模型不知道哪条是团队认可的最佳实践。
   • 例：查数据该写 SQL 还是调 API？模型可能选了最差的一条——而团队明明有规定。
6. 缺样例参考 —— 没有「正确长这样」的范本，模型只能凭概率猜，每次输出形态都不一致。
   • 例：让出一份「投标评分表」，模型从没见过标准范本，只能拼凑——给个样例质量立刻不同。

P13 · Skill 如何逐一解决：用确定性的规则，覆盖概率性的推断

Skill 不是教模型新知识——是把模型「凭概率猜」的地方，换成「按规则做」。

六大缺陷	→	Skill 的解法
① 知识时效性断层	→	references/ 随时更新——知识与模型解耦。例：库升级到 v3，只改 references/api.md，AI 立刻按新版写。
② 私有知识不可获取	→	SKILL.md 编码私有流程、方法论、业务标准——把没见过的写进来。例：把「单方成本=不含税÷可售面积」直接写进 SKILL.md。
③ 会踩坑	→	用确定性规则明确「永远这样、永远别那样」。例：docx Skill 写死「Always DXA, never PERCENTAGE」。
④ 缺质量标准	→	精确定义输入输出规范与验收口径。例：规定报告必须六段式、每段结论前置——每次产出结构一致。
⑤ 不知用什么工具	→	scripts/ 把最佳技术路径编码成脚本。例：查数固定调 query.py，AI 不用纠结写 SQL 还是调 API。
⑥ 缺样例参考	→	正文 / references 内置范本——相当于一份**「永久 Few-shot」**。

Takeaway： 六大缺陷一个统一视角——凡是模型「靠概率猜不准」的地方，Skill 就用「确定性」把它钉死。

P14 · Anthropic 自带通用 Skill：docx / xlsx

官方 Skill 直接验证了理论——它们写的不是「知识」，是给模型排错的硬规则。

docx Skill 正文里的真实规则：

• Always use WidthType.DXA, never PERCENTAGE。
  • 模型常因训练数据混入而用 PERCENTAGE，生成的表格在 Word 里宽度错乱。
• Never use unicode bullets（•、▪）—— 用 Word 原生列表样式。
  • 直接打 unicode 符号看似「能用」，实际不是真列表，导不出大纲、改不动层级。
• xlsx Skill： 公式必须用引擎重算，不要手填计算结果。
  • 模型爱直接把算好的数填进单元格——数据一变，整张表就错。

对应缺陷 ③ 会踩坑： 这些规则不增加任何「能力」——它们存在的唯一目的，就是抵消训练数据里的错误倾向。

为什么是「给 AI 用」的证据： 这些话人类开发者根本不需要——人不会犯 WidthType 这种错。它只对 AI 有意义。

P15 · 真实业务 Skill：成本问数

把成本经理的专业判断、口径校验、归因框架——显性化成一套可执行规则。

SKILL 正文的核心规则：

• 5 步执行主线 —— 理解诉求 → 口径校验 → 取数 → 五差归因 → 结论。
  • 例：用户问「A 项目土建为什么超了」。AI 不直接答——先按主线走：确认是哪个口径的「土建」→ 取目标 vs 实际 → 拆五差 → 才下结论。
• 口径校验 —— 含税 / 不含税、单方口径、统计范围逐项确认。
  • 例：同一个「单方成本」含税 ¥4,800 / 不含税 ¥4,250；按建筑面积还是可售面积，结果差一截——Skill 强制先问清再算。
• 五差归因框架 + 深挖决策表
  • 例：超支 200 万怎么拆——五差：量差 / 价差 / 标准差 / 范围差 / 其他。查表 → 发现是「标准差」（精装标准提高）→ 继续下钻该科目。

逐条对照六大缺陷：

• ✓ 私有知识 —— 成本口径、归因框架进 SKILL.md。
• ✓ 质量标准 —— 口径校验就是输出规范。
• ✓ 样例 —— 决策表内置「该怎么追问」的范本。

一句话： Skill 把一位资深成本经理的脑子，沉淀成了文件——换谁来问，AI 都按同一套专业方法答。

P16 · 售楼业务 10 个词，30 秒看完

三个实战都用真库售楼数据——先给「非售楼专业」的观众一份小词典。

交易状态链（同一房号会经历）：

• 小订：意向阶段、付小额定金
• 认购：正式认购、付认购款
• 签约：合同签订（草签 → 网签）
• 网签：房管局备案，合同生效

单据状态：

• 激活：有效单 — 真实业绩
• 关闭：作废/转换 — 不计业绩
• 业绩统计前必须先过滤 Status=激活，否则关闭单也算进去 = 业绩翻倍。

人员 / 数据库字段：

• 置业顾问（zygw）：销售员，负责接待+成交
• 成交总价（cjTotal）：一笔单的实际成交金额
• 建面（cjBldArea）：建筑面积，含公摊

货值表的「层级」陷阱：

• 货值表 dwd_s_projectvalueabledetail 同一笔货值在 Level=1/2/3 三层各存一份等额金额（楼栋明细/分区明细/版本总计）。
• IsBenchmark=1：基准版货值（对外口径用这版）。
• 不锁 Level 直接 SUM = 同一笔货值算 3 次（实战 B P40 真实 bug）。

Takeaway： 看不懂某个词时翻回这页——不熟悉售楼业务也能完整看懂三个实战。

P17 · 实战 A · 业务 & 架构设计（现场实战）

业务： 售楼销售台账查询（API 模式）。复刻明源云售楼系统的「销售台账」界面——项目筛选、销售状态、签约状态、网签日期、置业顾问，一行 = 一笔交易。

统一台账端点流程：

用户问                Skill 胶水             FastAPI            真库 MySQL
"光谷天地一期         人话→端点+参数        /health            认购宽表 142
1208 有哪些交易"  →   scripts/query.py  →   /sales/ledger  →   + 合同宽表 51
                                                                UNION

🏗️ 架构设计 · 两层：

• API 层（提前做好）：FastAPI + pymysql 直连真库，dwd_s_order UNION dwd_s_contract 合成统一台账，对外仅暴露 /sales/ledger 一个查询端点。
• Skill 层（现场手搓）：YAML description 写触发词，query.py 把子命令映射成 HTTP query string——不连数据库、不写 SQL。

🔒 关键约束 · 4 条：

1. 端点固化：能查什么由端点和参数决定，新维度 = 改代码。
2. 枚举校验：销售状态/合同类别/销售单状态用 enum 限定。
3. 不做 mock 兜底：DB 不可用直接返 503，绝不编造数据。
4. 只读 SELECT：参数走占位符，杜绝注入。

Takeaway： 把 API 文档 + 这页架构图给 Claude Code / Codex——它就能复刻整套设计。这就是「业务设计 + 架构设计 = 可复制资产」。

P18 · 实战 A · 真库实测（现场实战）

与售楼系统界面截图逐字段对齐。 直连真库「售楼宽表库」· 142 条认购 + 51 条合同 · 同一房号「小订 → 认购 → 签约」多行还原。

对话流：

用户：查一下光谷天地一期 1208 那栋的销售台账

Claude · 命中 sql-query-api Skill：意图=销售台账查询，项目=光谷天地，关键词=1208

$ python3 scripts/query.py ledger \
    --project 光谷天地 --keyword 1208

真库连通 · 命中 4 条交易 ↓

GET /sales/ledger · 一房多行 · 真库数据：

字段	值
房号	2栋啊1208-住宅啊-1001
客户	aaa
成交总价	¥ 4,400,000
建筑面积	123.12 m²
置业顾问	系统管理员
销售状态（多行）	小订 → 认购 → 签约

✅ 数据来源 = 生产库 · 与售楼系统「销售台账」界面截图逐字段对上。

追问场景： 用户追问「按置业顾问统计每人成交套数和总额」。

Claude：当前 /sales/ledger 没开聚合参数——只返明细不做 GROUP BY，查不了。改 API、重启服务才行。

Takeaway： 追问那一下——**「按置业顾问聚合」**是 P22 留给实战 B 的钩子。

P19 · 实战 A · 目录结构 & SKILL 概要

两层目录 + 4 个核心文件 —— 贴给 Claude Code / Codex，它能照着复刻整套 API 模式 Skill。

📁 目录结构：

实战A-sql-query-api/
├── api/                    # API 服务（提前做好）
│   ├── API文档.md          # 317 行 · 给 AI 看的接口契约
│   ├── main.py             # 311 行 · FastAPI 服务
│   ├── run.sh
│   └── .env.example        # 数据库连接（脱敏）
└── skill/sql-query-api/    # Skill 胶水（现场手搓）
    ├── SKILL.md            # 150 行 · 触发词+流程
    └── scripts/
        └── query.py        # 306 行 · 子命令式 CLI

🤖 SKILL.md 概要 · 关键 6 段：

1. YAML description —— 写触发词（销售台账/合同/认购/光谷天地…）。
2. 前置条件 —— API 必须在 :8077 跑通，DB 必须连得上。
3. 端点清单 —— /health · /sales/ledger（枚举参数表）。
4. 调用流程 —— 理解意图 → 抽取参数 → 调 query.py → 整理回答。
5. 边界声明 —— 不连库不写 SQL · 503 时如实告知不编造。
6. 典型对话 —— 4-6 个真实问句示例。

API文档.md 同样关键 —— 端点 + 参数枚举 + 响应字段 + 真库示例，Claude Code 主要靠它复刻 API。

Takeaway： API文档.md + SKILL.md 这两份契约写好，Claude Code 自动产出 main.py 和 query.py。

P20 · 实战 A · CLI 设计 & 典型问答

CLI 设计 · query.py 子命令把人话→HTTP。CLI 是 Skill 和 API 之间的薄胶水——一个子命令对应一个端点，枚举参数防 AI 乱传。

子命令	映射端点	关键参数（枚举/范围）
health	GET /health	无 — 探活
ledger	GET /sales/ledger	--project · --keyword · --sale-status {小订/认购/预认购/签约} · --order-status {激活/关闭} · --contract-type {草签/网签} · --sign-start/end · --consultant · --limit 1-200

💬 典型问答 · 3 个真人会问的问题：

Q1 · 单房号交易历史 —— “光谷天地一期 1208 那栋的销售台账”

$ query.py ledger \
    --project 光谷天地 \
    --keyword 1208

→ 4 行（小订/认购/签约）

Q2 · 按日期范围筛交易 —— “2026 年 4 月签约的合同”

$ query.py ledger \
    --sale-status 签约 \
    --sign-start 2026-04-01 \
    --sign-end 2026-04-30

→ 9 条已签约合同

Q3 · ❌ 答不了的问题 —— “按置业顾问统计成交套数”

# /sales/ledger 没开
# group_by 参数
$ query.py 无法处理

→ 端点固化 → P22 伏笔

Takeaway： 子命令 + 枚举参数是 API 模式的灵魂——接口窄、AI 不会乱传，但也意味着新维度必须改代码。

P21 · 理论 Callback：刚才这个 Skill，印证了前面的理论

把实战 A 的产物拉回来，对照 P10–P13 的理论点——逐条打钩。

• ✓ 固化了工具调用？ query.py 把「子命令 + 参数」映射成「API 端点 + query string」——调用方式被钉死。对应 P10-①
• ✓ 固化了业务 SOP？ SKILL.md 写死调用流程：理解需求 → 抽参数 → 调脚本 → 整理回答。对应 P10-②
• ✓ 消除了「业务转技术」偏差？ 「海伦广场已审核合同」→ 精确的端点 + 参数，不靠模型每次猜。对应 P10-③ / P13-④
• ✓ 沉淀成可复用资产？ description 决定能否触发，正文是契约，脚本是最佳路径——三级结构齐全。对应 P10-④ / P11

Takeaway： 一个不到百行的 Skill，把业务经验、工具调用、输出契约全固化了——这就是「Skill 是给 AI 用的可复用资产」。

P22 · 留个伏笔：两个简单问题，API 答不了

实战 A 跑得很顺——但只要用户多问一步，API 模式的天花板就出来了。

❌ 问题 ①： 「按置业顾问统计每人的成交套数和成交总额」

根因：/sales/ledger 只返明细，没有 group_by 参数，也没有 sum/count 度量。

❌ 问题 ②： 「光谷天地的成交总价加起来是多少」

根因：API 端点是写死的明细查询，没开聚合参数——想加得改代码、加端点、重启服务。

API 模式的本质局限：

• 端点+参数 = 写死的契约
• 新维度 = 改代码 + 重启 + 发版
• 多维度交叉 / 下钻归因做不了

下一章用 CLI + 本体解决：

• DSL 让 AI 现场「拼」查询，不调死端点
• 本体 schema 写死业务口径（口径护栏）
• 同一个问题，待会用 aggregate 当场答出来

Takeaway： 这两个问题先记住——第三章用 DSL + 本体当场把它们答出来。

---

第三章 · CLI + 本体

章节主张（过渡页）

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

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

含「现场实战 B」手搓 CLI 问数 · 货值三倍 bug

P23 · CLI 是给 Agent 设计的指令系统

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

传统 CLI · 给人用 vs AI 原生 CLI · 给模型用：

传统 CLI · 给人用	AI 原生 CLI · 给模型用
服务对象：人类开发者	服务对象：Agent（大模型）
设计目标：覆盖所有功能选项	设计目标：完成一个业务动作
输出：给人读的文本日志、报错堆栈	输出：JSON + error_code + hint，机器可解析
命令来自：API / 工具的能力清单	命令来自：业务任务，不是 API 路径

桥意象：

业务操作                        CLI                          技术指令
"查一下这个项目的去化率"  →   AI 更容易理解的桥   →   DSL → SQL → 数据库

Takeaway： CLI 没变形态，但服务对象从「人」换成了「模型」——观察 Claude Code / openclaw，它们执行指令最终都落到系统命令行。

P24 · 同一个问题，两种发起方式（杀手论据）

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

脚本模式 · 面向「文件」：

# 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 里——无路径、单入口

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

• 脚本模式：200 × 4 ≈ 800 字符
• CLI 模式：100 × 4 ≈ 400 字符

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

P25 · 控制价审核 CLI 化：完整设计与优化结果

① 控制价审核 CLI 设计 · 9 步业务流程 → 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 · 同一审核任务）：

指标	脚本模式	CLI 模式
实际用时	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 / 业态 这种字段名

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

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

命令树第一层是业务对象（文档 / 多维表格 / 知识库），不是 API URL。

① 飞书 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。

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

P28 · 为什么要做本体：模型会「飘」

模型有通识，但不够——处理具体业务问题时输出不稳定。同一个问题问两次，模型两次给的口径往往不一样：

飘① 含税口径： “土建合同金额多少？”

• Round 1：含税价 ¥2.4 亿
• Round 2：不含税 ¥2.12 亿
• 小结：含不含税没说死，两次差出一整个税点。

飘② 单方分母： “这个项目单方成本？”

• Round 1：按建筑面积除 → ¥4,250
• Round 2：按可售面积除 → ¥5,600
• 小结：分母选哪个没定义，单方差一大截。

飘③ 父子科目： “土建总成本是多少？”

• Round 1：只加末级科目 → ¥2.4 亿
• Round 2：父子科目一起加 → ¥4.8 亿
• 小结：没说只算末级，金额直接翻倍。

Takeaway： 每一次「飘」都是一次口径没对齐——本体就是把含税口径、单方分母、末级科目这些规则一条条钉死。

P29 · 本体（Ontology）到底是什么

两个权威定义：

• 📖 维基百科 · 信息科学中的本体： 对一个领域内概念、类别及其关系的形式化表示——给出一套共享词汇，对类型、属性、个体、关系建模。描述逻辑里 K = (TBox, ABox)：TBox 是概念模式，ABox 是事实断言。
• 🏢 Palantir · Foundry Ontology： 组织的**「数字孪生」——把数据集映射到现实世界的对象、事件、流程，做成所有应用、AI 共用的语义层**。四个核心：对象 / 属性 / 链接 / 动作。

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

中心对象「📄 成本合同」围绕三类信息：

• 属性 —— 签约金额 / 含税·不含税 / 结算状态
• 关系 / 链接 —— 属于某项目 / 挂某成本科目 / 对应某供应商
• 规则 / 约束 —— 结算 = 签约 + 补差 / 算成本默认用不含税

Takeaway： 本体就是把**「业务世界长什么样」**写下来——让 AI 不靠通识猜，而是按业务真相推理。

P30 · 本体 = TBox + ABox

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

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

• TBox 定义： 「术语组件」—— 用一套类与属性，把领域词汇与结构定义出来。
• ABox 定义： 「断言组件」—— 在 TBox 模型之上，陈述具体事实：某个实例属于哪个类、有什么值、和谁有关系。

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

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

TBox 定义成本领域的类、属性、约束。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 自动补
}

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

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

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

😟 没有 ABox 的 AI：

• ✓ 查到了 —— 钢筋含量 58kg/㎡，这一步靠 TBox 就够。
• ✗ 再往下问「为什么高」就卡住了——它不知道这个项目具体层高多少、有没有地库。
• ✗ 只能用通识空答：「可能是设计原因、可能是标准高」——像没去过现场的实习生。
• ✗ 给不出能落地的结论，成本经理还得自己去翻数据。

😎 有 ABox 的 AI：

• ✓ 同样查到 58kg/㎡，且知道同城样本只有 45 —— 确实偏高。
• ✓ 顺着 ABox 里的关联关系查到：这个项目层高 3.6m（样本 3.0m）。
• ✓ 再沿替代关系比对：当前木模方案，换铝模可降 8%。
• ✓ 给出结论：层高刚性 + 模板可优化——有据可依、能落地。

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

P33 · 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%，但需评估成本

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

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

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

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

这张图谱里有三类边：

• 父子 · contains —— 土建工程 → 钢筋 / 混凝土 / 模板。科目逐级拆解。
• 共振 · resonance —— 结构层高 → 同时带动钢筋、混凝土。一个特征驱动多个科目。
• 替代 · substitute —— 铝模 ⇄ 木模。互斥方案，归因时要拉出来比对。

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

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

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

只建 TBox 就够：

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

才需要上 ABox：

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

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

Takeaway： 简单查询 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	项目 / 类别 / 状态 / 顾问

18 道题端到端验证 100% 准确（8/8 + 7/7 + 3/3）：

• L1 事实查询 · 8 题 —— “中建大公馆 2026 全年签约目标”、“各项目认购套数排名”。
• L2 多维分析 · 7 题 —— “光谷天地每月认购金额趋势”、“按业态分组成交占比”。
• L3 归因判断 · 3 题 —— “基准版项目全盘去化率”、“目标完成率风险研判”。

Takeaway： 这是真库实测，不是 demo 跑通。

P37 · 实战 B · 架构设计：三层架构 · SKILL + CLI/DSL + 本体（现场实战）

用户问                ① SKILL              ② CLI/DSL           ③ 本体              MySQL
"按置业顾问            命中触发              find/aggregate/rank   schema.yaml         真库取数
统计成交"        →    拼 DSL JSON      →   编译 SQL          →  注入护栏 WHERE  →

• ① 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 道口径护栏（自动注入，用户无感）：

1. OrderDetail/ContractDetail.Status=激活 — 排除关闭单，避免业绩翻倍
2. OrderDetail.OrderType=认购 — 排除小订，避免混口径
3. ProjectValue.Level=3 AND IsBenchmark=1 — 避免三倍累加 + 多版本叠加 ★ 见 P40 真实 bug
4. SalesBudget.Month<=12 — 排除全年汇总行（Month=13），避免翻倍

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

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

本体目录 + 两份核心契约（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（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

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

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

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

DSL 指令	用途	关键字段	对应 SQL 语义
find	行级查询	cube · dimensions · filters · order · limit	SELECT … WHERE … LIMIT
aggregate	聚合分组	cube · dimensions · measures · filters · 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

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

P40 · 真实 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，避免三倍累加"

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

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

实战 A 答不了的，实战 B 一行 DSL 解决。

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

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 万

API 模式 vs CLI + 本体 对比：

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

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

---

第四章 · Aha moment

章节主张（过渡页）

当文件系统、Skill、AUI 三块拼上，Agent 第一次「像同事」。

含「现场实战 C」手搓报告 Skill

P42 · Aha moment：三块能力组合的化学反应

相比原来”Agent + Tool 的 RAG 循环”，Skill 这套架构带来了三块能力的组合质变。

• 01 · 💻 给 AI 配文件系统 —— 上下文不再受窗口限制，等于给 Agent 配了一台能读写的电脑。
• 02 · 🔗 Skill 的串联 —— 垂直 Skill + 通用 Skill 串起来，把产物变成可交付的工作结果。
• 03 · 🗣️ AUI —— 把 AI 当作”用户”来设计交互，多了一层人机双向协作。

文件系统 + Skill 串联 + AUI = 给 AI 一台可操作的电脑 · AI Agent OS

P43 · 给 AI 配文件系统 = 给 Agent 配了一台电脑

文件系统让上下文变得”无限”—— AgentOS 的本质，就是 Agent 具备了操作文件目录的能力。

workspace/
  ├─ data/                  # 大资料 → 整理成索引
  │   ├─ index.json
  │   └─ raw-*.csv
  ├─ 报告-销售达成.md       # 临时产物
  ├─ 报告-销售达成.html     # 可对话修订
  └─ notes/                 # 小资料汇总整合

Agent 模式涌现的规划外惊喜：

• 问数后可一键生成报告
• 指标清洗支持对话式调整
• 控制价审核报告支持对话式增删修订

关键： 过程不直接入库 —— 产生临时 JSON / HTML / MD 文件，都能像在 Claude Code 里一样，通过对话 / Skill / 脚本反复调整。

Agent 把上下文做成了文件系统——大资料整理成索引，小资料汇总整合，自己管理自己的资料。

P44 · Skill 串联：让产物变成可交付的工作结果

做到 90% 和做到 100% 之间有巨大差别——只有 100% 跑通，才算完全自动化、真正帮用户把活干完。

售楼场景：AI 做完一份「销售达成分析报告」之后……

垂直 SKILL          垂直 SKILL          通用 SKILL          通用 SKILL
售楼问数        →   报告 Skill      →   企微文档        →    邮件
CLI + 本体取数      成文 + 可视化       同步保存归档        发给相关干系人

• A · 垂直 Skill 出产物 —— 问数 / 报告，解决某个业务领域内的专业问题，产出报告这类”半成品”。
• B · 通用 Skill 接真实工作 —— 企微文档 / 飞书 / 邮件，把产物延展到用户真实办公场景，完成”最后一公里”。

Takeaway： 垂直 Skill 的产物，靠通用 Skill 串联—— 让我们 Agent 的产物变成可交付的工作结果。

P45 · AUI：把 AI 当作「用户」来设计交互

关键命题——要为 AI 设计它的交互方式，并教会 AI 怎么跟用户交互。

以前 · UED	AUI 时代
设计用户怎么操作系统 —— 页面流：用户点击 A → 跳转 B → 填表 C → 提交 D。界面是产品经理和设计师提前画好的，用户在固定路径里操作。	设计用户与 AI 如何共同完成任务 —— 任务协作流：用户提目标 → AI 拆步骤 / 拉信息 / 组织界面 → 用户确认关键点 → AI 执行 → 展示证据 → 用户验收。

双向交互：

• ① 用户 → AI：表达、控制、确认、纠错、信任
• ② AI → 用户：呈现、引导、解释、证据、边界

AUI 不是少一个界面，而是多了一层双向交互。

P46 · 同一段对话，看清两个视角

对话流（金色 = 用户→AI · 蓝色 = AI→用户）：

用户【表达意图】： 帮我出一份本季度的销售达成报告。

AI【引导 · 弹确认】： 生成前先确认两个口径——Q1 项目范围：A 全部 / B 光谷天地 / C 手动指定；Q2 时间：A 全年 / B Q1 / C 截至最新月。

用户【确认范围】： Q1 选 A 全部项目，Q2 选 B 2026 Q1。

AI【拆步骤 · 呈现】： 已取数完成。整体达成率 36.1%，对比时间进度 33%——小幅领先。给你一张项目对比表格。

用户【纠错】： 光谷天地的口径不对，要排除小订。

AI【解释 · 证据 · 边界】： 已重算并展示取数 DSL作为证据。报告含敏感金额，需你确认后再同步企微文档。

Takeaway： 哪些是”用户用 AI”的设计（提问 / 补上下文 / 确认范围 / 纠错），哪些是”AI 跟用户交互”的设计（什么时候给一句话、给表格、弹确认、亮证据、让人介入）——AUI 要同时把两侧都设计好。

P47 · 如果 90% 字段能自动识别——还需要表单吗？

AUI 把表单交互重构成对话确认——不是少一个界面，是换一种协作方式。

以前 · 一张 10 字段表单： 项目名称*、业态类型*、签约金额*、签约日期*、客户来源、付款方式…侧边栏也放 10 个字段，用户逐个手填。

AUI · 对话 + 少量点选：

• ✓ 90% 字段——信息收集 / 感知 / 记忆自动识别并主动确认
• ? 仅剩 2–3 个字段需用户确认

用户基本只在 A/B/C 选项里做选择：

• (a) 不确定的项目
• (b) 不确定的实施范围
• (c) 多义口径二选一

表单不是必须的—— 对话 + 少量点选，一样可以承载录入。

P48 · 实战 C · 业务 & 架构设计：销售达成分析报告 Skill · 先问后做（现场实战）

业务从”一问一答”升级到”出报告”——关键约束：口径不抢答，先用 Ask Question 确认范围/时间，再调 sales-query 取数 → 成文。

🏗️ 架构设计 · 编排层： sales-report Skill 在 sales-query 之上做编排，不重复造轮子取数：

① Ask Question 确认口径 ② 调 sales-query 取 6 段数据 ③ 按报告模板成文 ④ 输出 MD（本页）/ HTML（P51）

💬 AUI · 现场弹的问诊：

Q1 · 项目范围
○ A 全部项目   ○ B 仅光谷天地   ○ C 自定义

Q2 · 分析时间
○ A 2026 全年   ○ B 2026 Q1   ○ C 至今

产物 · 销售达成分析报告.md（六段式 · 真实数字）：

# 销售达成分析报告（2026 全年 · 全部项目）

一、整体达成概览
  签约 36.1%（3831 万 / 1.062 亿）vs 时间 33%
  认购 30.1%（5148 万 / 1.711 亿）vs 时间 33%

二、按项目的达成差异
  ✅ 光谷天地 45.0% 领先
  ⚠️ 中建大公馆 7.7% 严重滞后
  ⚠️ 预留金项目 0% 未启动

三、按业态结构       四、按月度节奏
  住宅占 95%         1-3 月空转，4 月放量 31.8%

五、风险研判
  🔴 高：中建大公馆紧急排查推盘计划
  🔴 高：前三月空转，确认 5-6 月延续放量

六、口径与数据局限说明
  目标 Month=13 / 实际 Status=激活
  数据来源：sales-query 直连真库

Takeaway： 报告口径不靠 AI 瞎猜 —— Ask Question 把决策权交还用户。

P49 · 实战 C · 目录结构 & SKILL 概要

报告 Skill = 编排层 + 模板 + 生图脚本——取数复用实战 B，不重复造轮子。

📁 目录结构：

实战C-报告skill/skill/
├── SKILL.md                  # 触发词 + 先问后做
├── README.md                 # 使用说明
├── references/
│   └── report-template.md    # 六段式模板
├── scripts/
│   ├── build_html_report.py  # 350+ 行 · MD→HTML+ECharts
│   └── sample_data.json      # 样例数据
└── assets/
    └── echarts.min.js        # 离线兜底

# 产物
样例-销售达成分析报告.md    # 纯文本版
样例-销售达成分析报告.html  # 单文件 + 5 张图

🤖 SKILL.md 概要 · 6 段：

1. YAML description —— 触发词（销售达成/月报/分析报告）
2. 强制流程 ⭐ —— 生成前必须 Ask Question 确认口径
3. 取数复用 sales-query —— 不自己写 SQL，调实战 B 的 DSL
4. 六段式模板 —— 整体/项目/业态/时间/风险/口径
5. MD → HTML 生图 —— build_html_report.py 接 ECharts
6. 离线兜底 —— --echarts-local 内联 echarts.min.js

references/report-template.md 是关键 —— 六段式样式 + 每段所需数据字段，Claude 读它就知道每段该怎么填。

Takeaway： 三个 Skill 叠加 = 取数(B) + 编排(C 模板) + 生图(C 脚本) —— 每层职责单一，可独立换。

P50 · 实战 C · CLI 设计 & 典型问答

报告 Skill 不写 SQL，只在 sales-query 之上做编排；最后用 build_html_report.py 一键生图。

命令	用途	关键参数
build_html_report.py	MD + 数据 JSON → HTML 报告	--data sample_data.json · --out 报告.html · --echarts-local（离线）

💬 4 个典型问答 · 真实交互：

Q1 · 全年报告 —— “给我做一份 2026 销售达成报告”

# Ask Question:
Q1 项目范围? → A 全部
Q2 分析时间? → A 2026 全年

# Skill 调 sales-query 取数
# 按六段式生成 MD
# build_html_report → HTML

→ 报告含 36.1% 整体达成 / 5 图

Q2 · 指定项目报告 —— “中建大公馆 Q1 达成怎么样?”

# Ask Question:
Q1 项目范围? → B 中建大公馆
Q2 分析时间? → B 2026 Q1

# 单项目 + Q1 视图

→ 风险研判：🔴 严重滞后 7.7%

Q3 · 离线版报告 —— “做个能发邮件、无网也能看的”

build_html_report.py \
    --data data.json \
    --out 月报.html \
    --echarts-local   # 内联

→ 单文件 ~1 MB · 邮件附件可发

Q4 · ⚠️ 用户少答了 Ask Question —— “先做了再说，什么报告都行”

# Skill 拒绝抢答
# 仍然弹 Ask Question
# 说明：口径不明确
# 会产生不一致的报告

→ AUI 守住口径权

Takeaway： SKILL.md 把”先问后做”写成强制流程 —— Agent 不抢答，把决策权交还用户。这就是 AUI 的体现。

P51 · 升级成 ECharts 报告 + 第四章小结（现场实战）

真实数据 · 项目达成率对比：

光谷天地        ████████░░░░░░░░░  45.0% ✅
中建大公馆      █░░░░░░░░░░░░░░░░   7.7% ⚠️
预留金项目      ░░░░░░░░░░░░░░░░░   0%   ⚠️
                  时间进度基准 33% ┊
2026 月度签约：1月 — 2月 — 3月 — ┃ 4月反弹 ┃

关键达成数字：

指标	全年目标	实际完成	达成率
签约金额（万）	10,622	3,831	36.1%
认购金额（万）	17,111	5,148	30.1%
签约套数	12,255	28	0.23%

第四章小结：

• 💻 文件系统 · 无限上下文
• 🔗 Skill 串联 · 可交付结果
• 🗣️ AUI · 人机双向协作

🏗️ 架构 · 三个 Skill 串联：

sql-query-api（A）
  ↓  + Cube 抽象 + DSL
sales-query（B）
  ↓  + Ask Question + 模板
sales-report（C）—— 出报告

Takeaway： 三块组合 = 给 AI 一台可操作的电脑 —— AI Agent OS。

---

第五章 · 评测

章节主张（过渡页）

没有评测集，所有”我感觉变好了”都是错觉。

LLM-as-Judge → Agent-as-Judge · 三层金字塔

P52 · 为什么要讲评测

前面我们现场手搓了 3 个 Skill —— 数据查询、售楼问数、销售达成报告。做出来不算完：怎么证明它们真的有用、真的比不用强？

Takeaway： 没有评测，Agent 只是一个 Demo。评测才是把它从”看着能跑”变成”敢交付”的那道关。

本章三个维度：

1. 理念 —— 用什么标准评？不只是”准不准”，更要看”好不好”。
2. 方法 —— 怎么分层评？指标设计 + 三层金字塔。
3. 数据集 —— 拿什么评？评测集决定产品出厂质量。

P53 · 理念转变：LLM as Judge → Agent as Judge

要点：

• 以好坏为衡量：业务指标必须以”好不好”打分，既含业务指标，也含技术指标。
• 评测体系三件套：指标设计 + 评测集设计 + 评测工具设计，缺一不可。
• 综合评估：程序化评测（确定性、可重复）+ 大模型评测（主观质量）双轨并行。
• 引入 Sub-Agent：让 Agent 自己跑测试、自己判分——评测从单次打分升级为自动化流程。

Takeaway： LLM-as-Judge 只看”这一句答得对不对”；Agent-as-Judge 看”整个任务做得好不好”——评测主体也要会干活。

P54 · 评测指标设计：红线 + 质量层

🔴 红线层 · 一票否决： 不过线，质量层再高都没有意义。

• 数据准确率 100%
• 不造数据
• 不靠检索 / 记忆作答

🔵 质量层 · 综合回答质量：

指标	类别
任务完成度	业务
事实准确性	业务
业务诉求覆盖	业务
证据可追溯	技术
边界与风险	技术
业务表达	表达

P55 · 评测设计的三层金字塔

参考传统测试金字塔——Agent 评测同样分三层，越往下越确定、越频繁。

                ┌──────────┐
                │   L3 E2E │   端到端 · 真实环境
            ┌───┴──────────┴───┐
            │   L2 Skill 测试  │   单 Skill 独立拆解
        ┌───┴──────────────────┴───┐
        │       L1 单测            │   CLI 层基础验证
        └──────────────────────────┘

• L1 · 单测： 针对 CLI 层做基础验证——子命令、参数、JSON schema 是否稳定。
• L2 · Skill 测试： 一个业务 2–3 个 Skill，Mock CLI 输出，单个 Skill 独立拆解。如控制价审核把”指标分析”和”清单组价”拆开，7–8 步长链路简化为 1–2 步。
• L3 · E2E： ① CC 环境用 Sub-Agent 大规模提问，评估工具调用与用户回复；② 真实浏览器窗口测试，用 Browser Use / Codex 校验回复样式、排版、文字。

Takeaway： 底层覆盖广、跑得勤、最确定；顶层最接近真实但成本高——分层才跑得起、也信得过。

P56 · 评测集：决定出厂质量

参考案例：《评测数据集设计：成本问数》· 17 种子场景 / 102 案例 / L1–L4 分层。

• 行业参考：法律、医疗都靠高质量数据集——医疗有基于几十个国家医生临床对话整理的人工数据集。
• 就是竞争力：不管做成本 / 租赁 / 售楼，最好的评测集本身就是核心竞争力。
• 能力可证明：同一评测集，我们打 95、友商打 90——高下立判，不靠嘴说。

同一评测集 · 一把尺子量到底：

   我们的 Skill   vs   友商
       95                90

P57 · 评测怎么落地：CC 会话 JSONL 当数据源

评测要靠客观指标，不靠主观感觉。Claude Code 把每次会话流水自动落成 JSONL——这是一份现成的评测数据源。

四步流程：

STEP 01 固化测试剧本 → STEP 02 跑完导 JSONL → STEP 03 写提取脚本 → STEP 04 落客观指标

• STEP 01： 把标准任务写成可重复执行的剧本。
• STEP 02： CC 自动记录整段会话流水。
• STEP 03： 从 JSONL 解析出结构化字段。
• STEP 04： 输出可对比、可追溯的报表。

三类指标：

• 效率指标 —— 实际用时 · token 消耗 · Bash 调用次数
• 质量指标 —— 错误率 · 临时补丁次数 · 读源码次数
• 两个底线 —— 可重复（同剧本能复跑）+ 可追溯（每个数字回得到原始会话）

Takeaway： 把”我觉得变好了”换成”用时 79m→15m、错误率 11%→0%” —— 数字才有说服力。

---

第六章 · FAQ

章节主张（过渡页）

不是技术问题，是「你愿不愿意把流程交给 AI」的问题。

整体小结 · 人人都会做 Skill · 行动号召

P58 · 把六章串成一条链路

今天我们始终站在 Skill 的视角：从理解 Harness，到逐层拆 Skill、CLI+本体、Aha moment，最后用评测收口。

Harness    →   Skill         →   CLI + 本体      →   Aha moment        →   评测           →   FAQ
运行时底座     怎么做             可控执行            文件系统 / 串联        证明它真的           小结 + 号召
笨循环+4件事   能力沉淀为资产     + 理解边界          / AUI                 有用、更强           + 答疑

Takeaway： 引入 Harness 架构后，文件系统、Skill 串联、AUI 三块组合，产生了和传统「Agent + Tool 的 RAG 循环」完全不一样的化学反应。

坦诚说明： 本次集中在 Skill 与评测层面——上下文管理、记忆系统、工具调用等模块未深入展开，留作后续分享。

P59 · 人人都会做 Skill —— PO 负责效果，开发负责工程

建议 PO 都学会做 Skill。在业务原型阶段，业务效果由 PO 负责；开发承担工程化落地。

PO · 业务原型阶段 · 对效果负责：

• 定义场景、用户路径、业务目标
• 定义验收口径——什么算「做对了」
• 遇到 CRI 本体 / 宽表 API，找开发配合
• Mock 数据或连现有 API 都行，先把效果跑通
• 目标：PO 能独立把效果验证出来

开发 · 工程化阶段 · 对架构负责：

• 承担工程化落地与稳定性
• 站在架构视角设计新架构
• 目录即架构——文件结构就是系统结构
• 执行过程即运行时——跑起来才知道边界
• 为 PO 提供本体 / API / CLI 等底座能力

Takeaway： 分工不是「PO 提需求、开发实现」的旧模式——而是 PO 直接把业务效果做出来，开发把它工程化为可靠资产。

P60 · 动手做一个《XX 场景问数 Skill》

目标很具体——做一个自己业务场景的问数 Agent。按下面 4 步走，资料包已备齐。

步骤	阶段	名称	说明
1	认知	先看 Harness 网页	理解 Agent = Model + Harness——模型外面还要有工具、上下文、执行边界、日志、评测，才能真的干活。
2	方法	读《AI 问数构建指南》	一个标准 Skill 怎么做出来。重点不是写完 SKILL.md 就完事，而是要配齐问题集、本体、宽表/API、CLI/DSL、测试。
3	体验	部署 myyclaw 体验	先体验现有的成本问数、控制价审核等技能，感受 Agent 怎么触发技能、调用工具、返回结果、继续追问。
4	实战	复制一个问数场景	基于 cost-query 的设计文档和技能包，结合自己产品已有的宽表/API，做一个业务场景问数 Agent，并在 MyAgents 上跑通。

📦 配套资料包 Agent-Skill-快速学习资料包.zip（4 个文件，对应上面 4 步）：

1. Agent & Skill 快速学习指南 —— 先看这篇，串起 4 步
2. AI 问数 Agent 构建指南.pdf —— 标准 Skill 的方法论
3. cost-query 设计文档.md —— 可复用的设计样板
4. cost-query_skill.zip —— 成本问数完整技能包

Takeaway： 四份资料一条链路：Harness 建系统观 · 指南建方法论 · myyclaw 建体感 · cost-query 提供可复用样板。

P61 · FAQ / 答疑（Q&A）

互动暖场页，无信息密度。 预置 3 个常被问到的引导问题：

• Q1：怎么证明 Skill 真的有用？用什么衡量它比不用强？
• Q2：换一个模型，准确率会不会掉？评测集还能复用吗？
• Q3：Skill 写好了却不触发，是什么原因？怎么排查？

欢迎现场提问，也欢迎会后就你自己的业务场景一起讨论。

---

附录 A · 实战 A 源代码资产（SQL 查询 API）

目录树

实战A-sql-query-api/
├── 剧本-实战A.md
├── 测试结论-实战A.md
├── api/
│   ├── API文档.md           # 317 行 · 接口契约
│   ├── main.py              # 311 行 · FastAPI 服务
│   ├── run.sh
│   ├── requirements.txt
│   ├── .env / .env.example  # 数据库连接（脱敏）
│   └── __pycache__/
└── skill/sql-query-api/
    ├── SKILL.md             # 150 行 · 触发词 + 流程
    └── scripts/
        └── query.py         # 306 行 · 子命令式 CLI

SKILL.md 摘要

YAML frontmatter（触发词描述）：

查询售楼销售台账数据时使用。当用户询问小订 / 认购 / 预认购 / 签约的交易记录，或要按项目、房间/客户关键词、销售状态、销售单状态、合同类别、置业顾问、各类日期范围（签署 / 网签 / 业绩归属 / 关闭）筛选交易，或要查”交易台账 / 销售台账”时触发。

触发词示例：销售台账、交易台账、查台账、认购记录、小订记录、预认购记录、签约记录、网签合同、草签合同、按项目查交易、查某个房号的交易、按客户名查成交、置业顾问成交、某月签约了哪些、网签日期在某范围的合同、光谷天地的认购情况。

本 Skill 走 API 模式：通过本地 HTTP API（http://127.0.0.1:8077）查询，不连数据库、不写 SQL，能查什么由 API 端点参数固化。

这个 Skill 做什么： 把用户用自然语言提出的售楼台账查询需求，翻译成对一个只读销售台账查询 API的调用，再把返回的 JSON 整理成人话回答。

• API 已经在运行：Base URL http://127.0.0.1:8077，HTTP / GET，响应 JSON（UTF-8），无需鉴权。
• 数据口径：API 把”认购宽表 dwd_s_order”和”合同宽表 dwd_s_contract” UNION 成一张统一台账。一行 = 一笔交易记录——同一个房间的小订、认购、签约会各自独立成行，与售楼系统「销售台账」界面”同一房号多行不同销售状态”一致。

API 模式 · 能查什么由端点固化：

• 能查询的维度、能筛选的条件，完全由 API 的端点和参数决定，是固化的。
• Skill 只是一层”胶水”——它不连数据库、不拼 SQL、不做取数逻辑。
• 如果用户要的维度 API 没开放（典型：聚合统计），如实告诉用户”当前 API 不支持这种查询”，不要自己编算法、不要编造数字。

端点清单（2 个）：

1. GET /health —— 健康检查（无参数；先探活）。
   • 响应字段：status / db_connected / db_message / db_host / ledger_tables。
2. GET /sales/ledger —— 销售台账查询（核心端点；所有参数都是可选过滤条件，AND 关系）。

调用流程 4 步：

1. 理解需求 —— 弄清用户要查的是哪类交易、哪个项目、什么筛选条件。
2. 抽取参数 —— 把自然语言映射到 /sales/ledger 的参数上。
3. 调脚本 —— 先 health 探活，再 ledger 查询。
4. 整理回答 —— 把返回的行数、关键字段整理成人话。

口径要点（务必遵守）：

• 合同类别（草签/网签）、网签日期只有”签约”行才有值。小订 / 认购 / 预认购行的 ContractType 和 NetQsDate 都是 null。
• 审核状态：真库当前 AuditStatus 全部是「未审核」，查不到「已审核」记录是正常的。
• 503 = 数据库不可用：绝不编造任何数据。
• 400 = 参数非法：通常是枚举值传错。
• API 连不上：告诉用户”台账查询 API（http://127.0.0.1:8077）当前无法连接”。

API 文档关键片段

/sales/ledger 参数表：

参数	脚本选项	取值 / 说明
project	--project	项目名称，模糊匹配。如 光谷天地
keyword	--keyword	房间/客户关键词，模糊匹配。如 1208、一期
sale_status	--sale-status	枚举：小订 / 认购 / 预认购 / 签约
order_status	--order-status	枚举：激活 / 关闭
contract_type	--contract-type	枚举：草签 / 网签。仅对签约行有效
consultant	--consultant	置业顾问，模糊匹配
sign_start / sign_end	--sign-start/end	签署日期范围，YYYY-MM-DD
net_start / net_end	--net-start/end	网签日期范围。仅签约行有值
perf_start / perf_end	--perf-start/end	业绩归属日期范围
close_start / close_end	--close-start/end	关闭日期范围
limit	--limit	返回行数上限 1–200，默认 50

响应顶层字段： source（固定 database）、tables、cn_name、count、filters_applied、elapsed_ms、rows。

rows[] 关键字段： RoomInfo（房间全称）、ParentProjName（项目）、ProjName（分期）、BldName（楼栋）、RoomNum（房号）、CstAllName（客户）、sale_status（销售状态）、order_status（销售单状态）、CloseReasonType、ContractType、Zygw（置业顾问）、CjBldArea（成交建筑面积）、CjTotal（成交总价）、AuditStatus（审核状态）、sign_date、NetQsDate、YjgsDate、CloseDate。结果默认按 sign_date 倒序排列。

现场问答示例的真实返回数据

Q · “光谷天地一期 1208 那栋的销售台账” → 同一房号 4 条交易（小订 → 认购 → 签约）：

字段	值
房号	2栋啊1208-住宅啊-1001
客户	aaa
成交总价	¥ 4,400,000
建筑面积	123.12 m²
置业顾问	系统管理员
销售状态	小订 → 认购 → 签约

数据来源 = 生产库 · 与售楼系统「销售台账」界面截图逐字段对上。

❌ 答不了： “按置业顾问统计成交套数” —— /sales/ledger 没开 group_by 参数（→ P22 伏笔，由实战 B 接住）。

---

附录 B · 实战 B 源代码资产（CLI + 本体问数）

目录树

实战B-cli-本体问数/
├── 剧本-实战B.md
├── 售楼问数资料/
│   ├── 售楼V5.5宽表清单及口径-对外.xlsx
│   ├── 售楼数据分析场景清单.jpg
│   └── 数据库&宽表.md
└── 成本问数参考/                       # cost-query 作为参考实现
    ├── cost-query 设计文档.md
    ├── AI 问数 Agent 构建指南.pdf
    └── cost-query/
        ├── SKILL.md
        ├── pyproject.toml
        ├── requirements.txt
        ├── references/
        │   ├── dsl-spec.md
        │   ├── query-guide.md
        │   ├── terminology.md
        │   ├── feedback-templates.md
        │   ├── cli-mapping.md
        │   ├── schema/                  # TBox 文档
        │   └── abox/
        │       ├── feature_cards/
        │       └── indicator_cards/
        ├── scripts/
        │   ├── schema.yaml              # ★ 本体定义
        │   ├── query.py / cli.py
        │   ├── _builder.py / _registry.py
        │   ├── card.py
        │   ├── build_card_index.py
        │   ├── fetch_schema.py
        │   └── commands/
        ├── data/market-prices/
        └── log/

实战 B 目标 sales-query Skill 在 PPT 现场手搓，目录结构与 cost-query 同构（见 P38）：SKILL.md + scripts/schema.yaml + scripts/query.py + references/schema/<Cube>.md × 6 + tests/questions.yaml 18 题 baseline。

SKILL.md 摘要（参考 cost-query）

YAML frontmatter：

使用于用户基于成本数据库查询或分析项目、城市、业态、科目、清单、人材机、建造标准、造价指标、建面单方、含量、综合单价、签约价、结算价、合同价、材料/人工/机械价格、清单指标、成本合理性、方案比选、趋势、组价、降本、归因或异常检测等成本业务问题时。

核心原则：

• 中文交互：用简体中文回复。
• 业务优先：对外像成本经理一样说话，讲”结论、依据、风险、动作”；不暴露内部 schema、cube、DSL、CLI 参数、SQL、字段路由、文件路径等实现细节。

角色定位与数据底线： 本技能定位为成本经理的数据助手，不是报表查询员。成本问答必须基于可追溯数据。最终数值、判断和建议只能来自实际查询结果或用户提供的可核验材料。不得仅基于用户输入数字、模型通识、行业经验或记忆中的常识范围作答。 缺少数据时先查询；无法查询或无结果时，说明当前没有可支撑结论的数据，不要补数、猜数或用经验值替代。

执行主线总流程（5 步）：

1. Step 1 · 意图识别 —— 对照”意图分类表”判断主诉求：查事实 / 做判断 / 找原因 / 给动作 / 技术排查 / 需澄清。
2. Step 2 · 取数准备 —— 锁定业务口径（9 项口径校验清单）；维度风险判断（低/中/高三档，高风险必先用 find-dimension 标准化）；判断是否需要指标卡片；识别用户自带数字。
3. Step 3 · 执行取数 —— 按”内部执行规则”中的事实取数入口、指令选择、查询节制和维度风险判断执行。
4. Step 4 · 结果评估与深挖决策 —— 数据质量评估 + 深挖决策表（事实/判断/原因/动作不同路径），下钻执行规则。
5. Step 5 · 结论组织 —— 按问题类型选择输出模板；结论强度与数据支撑对齐；口径标注与风险提示。

意图分类表：

诉求	典型问法	输出重点
查事实	”是多少""有哪些""排名""平均值”	数值、列表、筛选条件、数据量、口径说明
做判断	”高不高""合理吗""能不能接受”	结论、对标样本、分位/差异、结论强度
找原因	”为什么贵""差在哪""是不是量价问题”	差异来源、贡献度、共振指标、可验证证据
给动作	”怎么降""按多少控""怎么谈”	优先级、建议区间、谈判抓手、风险边界

schema.yaml 关键片段（OrderDetail 类，含 defaultFilters 4 道护栏）

实战 B 售楼问数的 schema.yaml 结构示例（按 PPT P37/P38/P40 给出）：

# ═══════════════════════════════════════════════════════════════════════════
# sales-query DSL 语义层 schema
# 定义 cubes（宽表映射）+ dimensions（维度字段）+ measures（度量字段）
# 由 scripts/query.py 读取，配合 find/aggregate/rank 三指令编译 SQL
# ═══════════════════════════════════════════════════════════════════════════

version: "1.0.0"

cubes:

  OrderDetail:
    table: dwd_s_order
    description: 认购单明细 · 行级粒度 = 一笔认购
    primaryKey: id

    dimensions:
      parentProjName: { sql: "parent_proj_name", description: "项目名称" }
      zygw:           { sql: "zygw",             description: "置业顾问" }
      orderType:      { sql: "order_type",       description: "认购类型：小订 / 认购 / 预认购" }
      status:         { sql: "status",           description: "单据状态：激活 / 关闭" }
      qsDate:         { sql: "qs_date", type: time, description: "认购日期" }

    measures:
      cjTotal:    { sql: "cj_total",    defaultAgg: sum, description: "成交总价" }
      cjBldArea:  { sql: "cj_bld_area", defaultAgg: sum, description: "成交建面" }
      dealPrice:  { type: routed,                       description: "成交单价（路由）" }
      rowCount:   { type: count,                        description: "记录数" }

    defaultFilters:          # 口径护栏 · 自动注入 WHERE
      - { field: status,    value: 激活 }   # ① 排除关闭单，避免业绩翻倍
      - { field: orderType, value: 认购 }   # ② 排除小订，避免混口径

    friendlyAlias:           # 中文短名
      projectName: parentProjName

  ContractDetail:
    table: dwd_s_contract
    defaultFilters:
      - { field: status, value: 激活 }       # ③ 排除关闭合同

  ProjectValue:
    table: dwd_s_projectvalueabledetail
    description: 楼栋货值（同一笔货值在 Level=1/2/3 三层各存一份等额金额）
    defaultFilters:
      - field: level
        value: 3
        unless: [level, hierarchyCode]
        hint: "默认 level=3，避免三倍累加"  # ④ 见 P40 真实 bug
      - { field: isBenchmark, value: 1 }     # 只取基准版货值

  SalesBudget:
    table: dwd_s_salesbudget
    defaultFilters:
      - field: month
        operator: "<="
        value: 12
        hint: "排除全年汇总行 Month=13，避免翻倍"  # 4 道护栏中的第 4 条

4 道口径护栏汇总（自动注入，用户无感）：

1. OrderDetail/ContractDetail.Status=激活 — 排除关闭单
2. OrderDetail.OrderType=认购 — 排除小订，避免混口径
3. ProjectValue.Level=3 AND IsBenchmark=1 — 避免三倍累加（货值 bug 根因）
4. SalesBudget.Month<=12 — 排除全年汇总行

DSL 命令清单（find / aggregate / rank）

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

CLI 入口示意：

sales-query find --dsl '<JSON>'
sales-query aggregate --dsl '<JSON>'
sales-query rank --dsl '<JSON>'

现场问答示例的真实返回数据

问题 ① · 按置业顾问统计成交（P41 回收伏笔）：

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

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

问题 ② · 光谷天地成交总额（P41）：

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

Q · 中建大公馆 2026 全年签约目标（find · SalesBudget · Month=13）： → 2600 万

Q · 各项目有效认购总金额（aggregate · OrderDetail）： 光谷天地 38,236,887 / 售楼考核 53,985,433 …（自动加 WHERE Status=激活 AND OrderType=认购）

Q · 光谷天地每月认购金额趋势（aggregate · time granularity=month）： 1月 112万 / 2月 187万 / 3月 223万 / 4月 1326万。

Q · 基准版项目全盘去化率（计算度量）： 光谷天地 10.0% / 中建大公馆 0%（自动加 WHERE level=3 AND isBenchmark=1）。

🐛 货值三倍 bug 复盘（P40）：

• ❌ AI 直接写 SQL（SELECT SUM(TotalValue) FROM ... WHERE IsBenchmark=1） → 84,900,000 元（8490 万），SQL 语法 100% 正确，但结果错 3 倍。
• ✅ DSL 引擎自动加 AND Level=3 护栏 → 28,300,000 元（2830 万），口径正确。
• 根因：宽表反范式，同一笔货值在 Level=1/2/3 三层各存一份等额金额。
• 解法：schema.yaml 写 defaultFilters: level=3。

18 题端到端验证 · 100% 准确（8/8 L1 事实 + 7/7 L2 多维 + 3/3 L3 归因）——真库实测，不是 demo 跑通。

---

附录 C · 实战 C 源代码资产（报告 Skill）

目录树

实战C-报告skill/
├── 剧本-实战C.md
├── 测试结论-实战C.md
├── 样例-销售达成分析报告.md       # 产物 · 纯文本版
├── 样例-销售达成分析报告.html     # 产物 · 单文件 + 5 张图
└── skill/
    ├── SKILL.md                   # 触发词 + 先问后做
    ├── README.md                  # 使用说明
    ├── references/
    │   └── report-template.md     # 六段式模板
    ├── scripts/
    │   ├── build_html_report.py   # 350+ 行 · MD→HTML+ECharts
    │   └── sample_data.json       # 样例数据
    └── assets/
        └── echarts.min.js         # 离线兜底

SKILL.md 摘要

YAML frontmatter：

用于生成”销售目标达成”分析报告——把售楼问数（sales-query）取到的数据汇总成一份结构完整的报告。支持两种产物：① Markdown 版销售达成分析报告（整体概览/分项目/分业态/分时间/风险研判/口径说明）；② 内嵌 ECharts 图表的单文件 HTML 报告。

触发词：销售达成报告、做销售目标完成情况分析、生成达成率报告、把数据做成报告、要带图表的销售报告、ECharts 销售报告、HTML 版销售报告、月度/季度销售达成分析。

生成 MD 报告前必须用 Ask Question 跟用户确认 ① 分析项目范围 ② 分析时间。

技能定位： 本技能是销售经理的报告助手。它在 sales-query（实战 B，CLI 模式售楼问数）之上做一层”报告编排”。

• sales-query 负责”取数”——回答单个问题。
• sales-report 负责”成文”——把多次取数结果组织成结构化报告，并可视化。

产物	形态	用途
MD 报告	单个 .md 文件	文本版达成分析，便于评审、贴文档、二次编辑
HTML 报告	单个自包含 .html 文件	内嵌 ECharts 图表的可视化版，浏览器直接打开，便于汇报

核心原则：

1. 中文交互：用简体中文。
2. 先问后做：生成 MD 报告前必须用 Ask Question 跟用户确认 2 个关键问题（项目范围、分析时间）。
3. 数字必有出处：报告里每个带量级的数字必须来自 sales-query 的查询结果，或来自用户明确提供的示例数据。
4. 结构稳定：MD 报告固定六段式结构。
5. 业务语言：像销售经理一样说”结论、依据、口径、建议动作”，不暴露 SQL/DSL/字段名等实现细节。

执行主线 4 步：

1. Step 1 · 用 Ask Question 确认范围与时间（强制） —— 必须先用 Ask Question 工具向用户提问，确认两件事：
   • Q1 分析项目范围：A 全部项目 / B 仅光谷天地 / C 我手动指定
   • Q2 分析时间：A 2026 全年 / B 2026 Q1 / C 截至最新月份 / D 自定义
   • 未确认前不得直接生成报告。
2. Step 2 · 取数 —— 按确认的范围+时间，调用 sales-query（实战 B 技能）取齐六个章节所需的数据：
   • 整体达成 · 分项目 · 分业态 · 分时间 · 风险点
   • 如果 sales-query 不可用且用户提供了示例数据，使用用户提供的数据，并在报告口径说明里明确标注”数据来源为示例数据/蓝本报告，非实时查询”。
3. Step 3 · 生成 MD 报告 —— 按固定六段式结构：

   一、整体达成概览
   二、按项目的达成差异
   三、按业态的达成差异
   四、按时间周期的达成差异
   五、销售进度风险研判
   六、口径与数据局限说明

4. Step 4 · 生成 ECharts HTML 报告（按需） —— 当用户需要可视化时，把 MD 报告升级成单文件 HTML：

   python3 <技能目录>/scripts/build_html_report.py \
       --data <数据JSON路径> \
       --out  <输出.html路径>

   • HTML 自包含：内嵌 CSS 与 JS，仅 ECharts 通过 CDN 引入（https://cdn.jsdelivr.net/npm/echarts）。
   • 内置 3 类图表：各项目达成率柱状图、业态分布饼图、月度签约趋势折线图。
   • 无网兜底：--echarts-local <echarts.min.js路径> 把本地 ECharts 文件内联进 HTML。

禁止行为：

• 禁止跳过 Step 1 的 Ask Question 直接生成报告。
• 禁止杜撰数据；数字必须来自 sales-query 查询结果或用户明确提供的示例数据。
• 禁止在报告里隐瞒数据来源——示例数据/蓝本数据必须在口径说明里标注清楚。
• 禁止把 SalesBudget 的 Month=13 全年汇总行与 1-12 月明细混算。
• HTML 报告除 ECharts CDN/本地文件外，不得依赖其他外部资源。

CLI 命令清单

命令	用途	关键参数
build_html_report.py	MD + 数据 JSON → HTML 报告	--data <JSON> · --out <out.html> · --echarts-local <path>（离线模式）

现场问答示例的真实返回数据

Q1 · 全年报告： “给我做一份 2026 销售达成报告”

• Ask Question → Q1 全部 / Q2 2026 全年
• 调 sales-query 取数 → 六段式生成 MD → build_html_report → HTML
• 报告含 36.1% 整体签约达成 / 5 张图

Q2 · 指定项目报告： “中建大公馆 Q1 达成怎么样？”

• Ask Question → Q1 中建大公馆 / Q2 2026 Q1
• 单项目 + Q1 视图
• 风险研判：🔴 严重滞后 7.7%

Q3 · 离线版报告： “做个能发邮件、无网也能看的”

• build_html_report.py --data data.json --out 月报.html --echarts-local
• 单文件 ~1 MB · 邮件附件可发

Q4 · 用户少答了 Ask Question： “先做了再说，什么报告都行”

• Skill 拒绝抢答，仍然弹 Ask Question
• 说明：口径不明确会产生不一致的报告
• AUI 守住口径权

销售达成分析报告（2026 全年 · 全部项目）核心数字（PPT P48/P51）：

指标	全年目标	实际完成	达成率
签约金额（万）	10,622	3,831	36.1%
认购金额（万）	17,111	5,148	30.1%
签约套数	12,255	28	0.23%

项目对比（达成率 vs 时间进度 33% 基准线）：

项目	签约达成率	状态
光谷天地	45.0%	✅ 领先
中建大公馆	7.7%	⚠️ 严重滞后
预留金项目	0%	⚠️ 未启动

业态结构： 住宅占 95%。

月度节奏： 1-3 月空转 / 4 月放量 31.8%（4 月反弹）。

风险研判：

• 🔴 高：中建大公馆紧急排查推盘计划
• 🔴 高：前三月空转，确认 5-6 月延续放量

口径与数据局限说明： 目标 Month=13 / 实际 Status=激活；数据来源 = sales-query 直连真库。

---

📌 本文导入自内部分享《SKILL + CLI + 本体 + AUI 设计实践分享》讲义文字版。 ← 返回 实践分享 · Cookbook 概览