09-脚手架与启动模板

Part 9 · 脚手架与启动模板

本章把前 8 章的方法论落到「该写哪些文件、按什么顺序写」。配套的 scaffold/ 目录提供可运行起步包。

9.1 脚手架目录说明

scaffold/ 目录结构：

scaffold/
├── README.md                          # 脚手架使用说明
├── init.sh                            # 从 cost-query fork 起步的一键脚本
│
├── skill-template/                    # 业务表达层模板（fork 后改）
│   ├── SKILL.md.template              # 380 行 SKILL.md 模板
│   └── references/
│       ├── query-guide.md.template    # 模式手册模板
│       ├── cli-mapping.md.template    # 指令导览模板
│       ├── dsl-spec.md.template       # DSL 语法（保留 cost-query 大部分内容）
│       └── terminology.md.template    # 业务词模板
│
├── scripts-template/                  # 编译层（直接 fork cost-query，重点是 schema.yaml + commands/）
│   ├── README.md                      # 编译层 fork 指引
│   ├── schema.yaml.template           # schema 编译源模板（cube/dimension/measure/join 完整结构）
│   └── commands/
│       ├── _ext/
│       │   ├── batch.py.template      # batch 自定义 builder（直接抄）
│       │   └── find_dimension.py.template  # find-dimension 自定义 builder（改 cube_map）
│       ├── find-entity.yaml.template  # find-X 二级指令模板
│       └── agg-entity.yaml.template   # agg-X 二级指令模板
│
└── eval-template/                     # 测评模板
    ├── README.md                      # 测评搭建指引
    ├── 测试问题集.md.template          # 测评题模板（5 题样例）
    └── eval-runner.py.template        # 简化版跑批工具骨架

9.2 cost-query 当模板：哪些文件直接复制起步

Step 1：fork 编译层

# 在你的项目仓内
cp -r /path/to/ontology-model/.claude/skills/cost-query .claude/skills/<your-skill>
cd .claude/skills/<your-skill>

Step 2：清理 cost-query 专属内容

# 删除业务专属文件
rm scripts/schema.yaml                  # 重写
rm scripts/commands/*.yaml              # 重写
rm -rf scripts/data                     # cost-query 卡片数据
rm references/schema/*                  # 由 fetch-schema 重新生成
rm references/cost.ttl                  # 你领域有自己的本体（可选）

# 保留的核心代码
ls scripts/
# query.py                              ← 保留（DSL 编译器，跨领域通用）
# _builder.py                           ← 保留（按需调整自动行为规则）
# _registry.py                          ← 保留
# cli.py                                ← 改数据库连接字符串
# fetch_schema.py                       ← 保留
# commands/_ext/batch.py                ← 保留
# commands/_ext/find_dimension.py       ← 改 cube_map

# 保留的文档
ls references/
# dsl-spec.md                           ← 保留大部分（DSL 协议跨领域一致）
# 删 query-guide.md / cli-mapping.md / terminology.md（重写）

Step 3：用脚手架模板起新文件

# 拷贝业务层模板
cp -r /path/to/ontology-model/docs/场景指南/问数/scaffold/skill-template/SKILL.md.template SKILL.md
cp -r /path/to/ontology-model/docs/场景指南/问数/scaffold/skill-template/references/* references/

# 拷贝编译层 placeholder
cp /path/to/ontology-model/docs/场景指南/问数/scaffold/scripts-template/schema.yaml.template scripts/schema.yaml
cp /path/to/ontology-model/docs/场景指南/问数/scaffold/scripts-template/commands/find-entity.yaml.template scripts/commands/find-<your-entity>.yaml
cp /path/to/ontology-model/docs/场景指南/问数/scaffold/scripts-template/commands/agg-entity.yaml.template scripts/commands/agg-<your-entity>.yaml

Step 4：按模板的 TODO 注释填空

每个 .template 文件含  注释，标出”这里需要你定义”。按 TODO 填空。

Step 5：跑 fetch-schema 生成速查版

python scripts/fetch_schema.py
ls references/schema/
# 应该看到 _index.yaml + 你定义的事实 cube 单文件 + dimensions.yaml

Step 6：跑 hello world 验证

# 假设你的事实 cube 叫 SalesContract
cost-query <your-skill>-cli aggregate --dsl '{
  "cube": "SalesContract",
  "dimensions": ["projectName"],
  "measures": [{"member": "amount", "agg": "sum", "alias": "total"}],
  "limit": 10
}'

跑通 = DSL 编译成功 + 数据库连接成功 + 拿到 10 行结果。

9.3 第一周开发计划（0→1 MVP）

Day 1-2：数据底座盘点

列出你领域核心实体（项目 / 客户 / 产品 / 订单等）；
确认对应宽表已经在分析库；
选 1 张事实宽表作为 MVP 目标（不超过 50 列、有清晰业务粒度）；
列出 3-5 张该事实关联的维度宽表。

Day 3：写 schema.yaml

定义 1 个事实 cube + 3-5 个维度 cube；
每个 cube 含 description / grain / role；
写 join 关系；
跑 fetch_schema 看速查版生成。

Day 4：写第一个二级指令

按 scaffold/scripts-template/commands/agg-entity.yaml.template 起步；
定义参数清单；
跑 cost-query <cmd> --info 确认参数加载正常；
跑 cost-query <cmd> --dry-run --params '{...}' 确认编译出的 DSL 是预期的。

Day 5：写 SKILL.md 雏形

按 scaffold/skill-template/SKILL.md.template 起步；
重点写：核心定位、数据底线、L1-L4 意图分层、执行总流程；
模式手册可以先只放 3-5 个模式占位。

Day 6：写第一份测评集

写 5 道 L1-L4 各覆盖的代表性题；
每题写清参考路径 + 关键参数 + 期望结论。

Day 7：跑通端到端

用 Claude Code 起一个会话，加载你的 skill；
把 5 道题手动跑一遍；
看 LLM 选对二级指令吗？参数填对吗？结论符合期望吗？
至少 3 道题通过 = MVP 完成。

9.4 第一个月迭代计划（1→10 模式手册沉淀）

Week 2：扩 cube 与模式

加 1-2 张事实 cube；
模式手册扩到 8-10 个；
测评题扩到 15 题；
跑 1 轮自动测评（用脚手架的 eval-runner.py 简化版即可）。

Week 3：引入自动行为

在 schema.yaml 加 inferredFilters / defaultFilters / friendlyAlias；
跑测评看自动行为有没有正确触发；
反模式黑名单加 3-5 条（治理测评中常见错误）。

Week 4：引入归因能力

写领域归因框架（量价位时 / 进度成本质量安全 / 人岗事时…）；
测评题扩到 25-30 题，含 L3 归因题；
跑 2 轮测评做双轮验证。

第 1 个月末交付物

1 个 skill 含 2-3 个事实 cube + 5-8 个二级指令；
模式手册 10-15 个模式；
SKILL.md 包含完整 L1-L4 分层 + 归因框架；
测评集 25-30 题，总分 ≥ 75%；
反模式黑名单 5-10 条。

9.5 第二个月迭代计划（10→20 + 内部试用）

Week 5-6：扩覆盖 + 复合能力

把领域核心事实 cube 全部建上；
二级指令覆盖每个事实 cube 的 find + agg；
模式手册扩到 15-20 个；
测评集扩到 40-50 题；
复合问题（拆段）能力上线；
跑批工具升级（CLI 分 + 结论分解耦）。

Week 7：业务方试用

内部业务方试用（5-10 个用户）；
收集 Bad case，纳入测评集；
每周 1 轮速查表治理迭代。

Week 8：稳定与交付

Bad case 闭环治理；
跑 2 轮全量测评做双轮稳定性验证；
撰写用户操作手册与维护手册；
总分目标 80%+。

第 2 个月末交付物

全核心 cube 覆盖；
模式手册 15-20 个；
测评集 40-50 题，连续 2 轮总分 ≥ 80%；
内部业务方已开始使用；
反馈闭环（业务 → 测评 → 治理）跑顺；
用户手册 + 维护手册就位，具备生产上线条件。

9.6 关键里程碑与决策点

M1：第 1 周末

决策：MVP 是否跑通？

通过标准：5 道题中 ≥ 3 道走对路径 + 给出合理结论。

不通过的处理：检查 schema 定义、二级指令参数、SKILL.md 角色定位是否清晰。卡 1 周以上重新评估立项。

M2：第 1 个月末

决策：是否进入业务试用？

通过标准：测评集 25 题、总分 ≥ 75%、反模式 ≥ 5 条、归因能力上线。

不通过的处理：暂缓业务试用，集中治理 Bad case，下个月再评估。

M3：第 2 个月末

决策：是否生产上线？

通过标准：测评集 40-50 题、连续 2 轮总分 ≥ 80%、内部业务方满意度调查 ≥ 70%、用户手册与维护手册就位。

不通过的处理：把第 8 周延长到 2-3 周做收尾治理，不强压上线节点。生产上线后仍持续做模式手册治理与 Bad case 闭环（每月 1-3 个新模式）。

9.7 团队配置建议

最小团队（3 人）

1 个 AI 工程师（2 个月集中投入 60-80%，之后转持续维护 30-40%）：负责 schema / 二级指令 / SKILL.md / 编译器 fork；
1 个业务产品（前 2 个月 40-60% 投入，之后 20%）：负责角色定位 / L1-L4 / 归因框架 / 测评出题；
0.5 个数据工程师（前 1 个月集中，之后按需）：负责宽表建设 / ETL 任务。

团队节奏

每周固定节奏：

周一：开站会，看上周测评分变化、本周治理计划；
周二-周四：开发 + 治理；
周五：跑 1 轮测评，记录分数与 Bad case；
周末：归档报告，下周计划。

每月固定节奏：

月初：业务方 demo（让业务方看测评结果 + 试用最新版）；
月中：跨团队对齐（数据工程 / AI / 业务）；
月末：版本发布 + 月度总结。

9.8 常见踩坑（启动期）

坑 1：宽表没有建好就动手

数据底座未就绪时硬上 LLM 层，结果是 SQL 报错满天飞。

预防：Day 1 先盘点数据，宽表 < 70% 就绪就推迟立项。

坑 2：第一周追求完美

第一周试图覆盖所有 cube、所有指令、所有模式——结果 4 周还没跑通 MVP。

预防：MVP 只做 1 个事实 cube + 1 个二级指令 + 5 道题。

坑 3：没有测评集就改 SKILL.md

凭感觉改 prompt，改完不知道有没有破坏其它能力。

预防：Day 6 必须有 5 道测评题；之后每改 SKILL.md 都跑测评。

坑 4：业务方不参与

研发自己想”业务方应该问什么”——闭门造车，做出的东西业务方用不起来。

预防：Day 1 拉业务方进项目群，每周一次同步。

坑 5：把工程问题当模型问题

测评分上不去时第一反应是”换更强的模型”——实际可能是 schema 没设计好、模式手册覆盖不够、SKILL.md 纪律不到位。

预防：测评分 < 70% 时不动模型选型，先检查工程层。

9.9 接下来读什么

要看上线后的检查与 FAQ → 读 Part 10 检查清单与 FAQ；
要看脚手架完整结构 → 读附录 B 脚手架代码结构；
直接动手 → 跑 scaffold/init.sh。

Part 9 完。读完应能回答：“Day 1 到 Day 7 该做什么、Week 2 到 Week 12 的节奏、团队怎么配、启动期常见坑、关键里程碑判断标准”。