附录B-脚手架代码结构

附录 B · 脚手架代码结构

本附录详解 scaffold/ 目录每个文件的用途与使用方式。

B.1 总览

scaffold/
├── README.md                              # 使用入口
├── init.sh                                # 一键起步脚本（fork cost-query + 替换模板）
│
├── skill-template/                        # 业务表达层模板（必填）
│   ├── SKILL.md.template                  # SKILL.md 起步模板（含 TODO 注释）
│   └── references/
│       ├── query-guide.md.template        # 模式手册起步模板
│       ├── cli-mapping.md.template        # 指令导览起步模板
│       ├── dsl-spec.md.template           # DSL 语法（直接抄 cost-query 大部分）
│       └── terminology.md.template        # 业务词候选模板
│
├── scripts-template/                      # 编译层模板
│   ├── README.md                          # 编译层 fork 指引
│   ├── schema.yaml.template               # schema 编译源模板
│   └── 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            # 简化版跑批工具骨架

B.2 顶层文件

`README.md`

脚手架的入口说明：

适用范围（领域、技术栈、LLM 选择）；
起步步骤（5 步从 0 跑通 hello world）；
章节索引（与本指南 Part 1-10 的对应关系）。

`init.sh`

一键起步脚本。做的事情：

检查依赖（python / claude-code CLI / 数据库连接配置）；
拷贝 cost-query 的 scripts/ 目录到 <your-skill>/scripts/；
删除 cost-query 专属内容（schema.yaml / commands/*.yaml / data/ / references/schema/）；
用脚手架模板替换（SKILL.md / query-guide.md 等）；
提示用户后续步骤（编辑 schema.yaml / 写第一个二级指令 / 跑 hello world）。

使用：

cd /path/to/your-project
bash /path/to/ontology-model/docs/场景指南/问数/scaffold/init.sh <your-skill-name>

B.3 `skill-template/`：业务表达层

业务表达层的所有内容都需要根据你领域重写，但模板提供完整的章节结构与 placeholder。

`SKILL.md.template`

按 Part 6 §6.10 的编写顺序组织 17 个章节。每章节用  标出需要你填的内容。

关键 TODO：

业务专家角色定位（成本经理 → 你的角色）；
高危红线（保留 3 条结构，例子换成你的领域）；
意图识别表（保留 6 类主诉求，例子换成你的领域）；
归因框架（保留五差结构，重写差异类型）；
红线与替代动作表。

`references/query-guide.md.template`

按 Part 7 §7.7 的整体结构组织。§0 必读铁律 / §3 标准流程 / §4.1 业务封装写法规约可以保留 cost-query 措辞；§1 模式手册 / §2 槽位填法 / §4.3 反模式黑名单必须重写。

`references/cli-mapping.md.template`

指令导览，含决策表与二级指令清单。模板提供决策表骨架，你填具体指令。

`references/dsl-spec.md.template`

DSL 语法手册。大部分直接抄 cost-query（DSL 协议跨领域一致）；只需调整：

§6 Cube 速查表（换成你的 cube）；
§7 错误自救的”错写 → 正写”对照表（换成你 cube 的字段名）。

`references/terminology.md.template`

业务词 → 标准词候选。完全重写。

B.4 `scripts-template/`：编译层

编译层的 Python 代码全部直接 fork cost-query；只需要重写 schema.yaml 与 commands/*.yaml。

`schema.yaml.template`

提供完整 schema.yaml 结构示例，含：

cube 基本字段（table / role / grain / description）；
dimensions / measures / joins 完整字段约定；
inferredFilters / defaultFilters / friendlyAlias 自动行为示例；
routed measure 完整定义（如果你领域需要）；
维度 cube 示例。

`commands/find-entity.yaml.template`

find-X 二级指令模板：

verb: find
cube: <YourEntity>
description: 查 <YourEntity> 明细

params:
  <key_field_1>:
    type: string | array
    description: <说明>
  <key_field_2>:
    type: string
    description: <说明>
  limit:
    type: number
    default: 20

filters:
  - param: <key_field_1>
    member: <key_field_1>
    operator: contains
    array_op: in
  - param: <key_field_2>
    member: <key_field_2>
    operator: equals

dimensions:
  default: [<output_field_1>, <output_field_2>, ...]

`commands/agg-entity.yaml.template`

agg-X 二级指令模板：

verb: aggregate
cube: <YourEntity>
description: 汇总 <YourEntity>

params:
  measureGroups:                # 如果你的领域适合 measureGroups 封装
    required: false
    type: array
    schema:
      type: object
      required: [alias, indicatorType]
  <filter_field_1>:
    type: string
  groupBy:
    type: array
  orderBy:
    type: array
  limit:
    type: number
    default: 20

filters:
  - param: <filter_field_1>
    member: <filter_field_1>
    operator: contains

builder: _builder.build_agg_<your_entity>   # 可选：自定义编译逻辑

`commands/_ext/batch.py.template`

batch builder 跨领域直接抄 cost-query。commands/_ext/batch.py 不需改动。

`commands/_ext/find_dimension.py.template`

find-dimension builder 需要改 cube_map：

# 改这里
CUBE_MAP = {
    "<YourDim1>": "<YourDim1>",
    "<YourDim2>": "<YourDim2>",
    # ...
}

其它逻辑保持。

B.5 `eval-template/`：测评

`测试问题集.md.template`

提供 5 道样例题，覆盖 L1-L4 + M1-M3 模式：

# 测试问题集

## Q1 (L1 / M1.1): <你的领域 L1 事实题>

### 参考答案
- 期望路径：M1.1
- 关键参数：<具体参数填法>
- 期望结论：<具体数值或列表>
- 期望边界：<口径标注要求>
- 评分要点：
  - CLI 正确性（60 分）：路径选对 / 参数填对
  - 结论质量（40 分）：数值正确 / 口径标注 / 边界说明

## Q2 (L2 / M1.2): <你的领域 L2 判断题>
...

## Q3 (L3 / M2.x): <你的领域 L3 归因题>
...

## Q4 (L4 / 复合): <你的领域 L4 动作题>
...

## Q5 (边界 / 0 行): <故意问数据库里没有的>
...

`eval-runner.py.template`

简化版跑批工具骨架。完整实现细节见 Part 8 §8.4。

模板提供：

起 claude -p 进程的封装；
stream-json 解析；
评分员调用与打分解析；
报告生成。

如果你的项目使用 cctest，可以省略 eval-runner.py，直接接入 cctest。

B.6 使用脚手架的步骤

Step 1：跑 init.sh

bash scaffold/init.sh my-sales-query

这会在你项目的 .claude/skills/my-sales-query/ 创建完整目录。

Step 2：编辑 schema.yaml

按 Part 3 + 模板填入你的 cube 定义。

Step 3：跑 fetch-schema

cd .claude/skills/my-sales-query
python scripts/fetch_schema.py

生成 references/schema/_index.yaml 等速查版。

Step 4：写第一个二级指令

按模板编辑 scripts/commands/agg-<your-entity>.yaml。

Step 5：跑 hello world

my-sales-query-cli aggregate --dsl '{
  "cube": "<YourFactCube>",
  "dimensions": ["<some_field>"],
  "measures": [{"member": "<some_measure>", "agg": "count", "alias": "cnt"}],
  "limit": 10
}'

返回 10 行数据 = 编译层跑通。

Step 6：编辑 SKILL.md

按 Part 6 + 模板填入业务专家定位、L1-L4、归因框架等。

Step 7：写第一份测评集

5 道题（按模板）。

Step 8：用 Claude Code 跑端到端

启动 Claude Code 会话，加载你的 skill，手动跑 5 道题验证。

B.7 脚手架不提供什么

脚手架不提供：

业务数据底座（你需要自己建宽表）；
LLM 接入配置（Claude API key 等）；
业务方提问的真实集合（你需要自己收集）；
领域专属的归因框架（必须根据领域重写）。

脚手架只提供：

跨领域通用的代码（DSL 编译器、二级指令框架、batch、find-dimension）；
文档骨架与 placeholder；
起步流程指引；
5 道测评样题作为参考。

B.8 脚手架的演进

本指南随 cost-query 主仓演进。脚手架的版本号在 README 中标注。

每次脚手架升级时：

新增能力会同步加到模板（如新的自动行为机制）；
已有模板的更新会提供 diff 文档；
重大改动会标注 BREAKING CHANGE。

各项目复刻后维护策略：

跟踪本指南的 release 节奏；
重要 fix（编译器 bug、错误自救改进）按 cherry-pick 同步；
业务专属内容（SKILL.md / 模式手册）独立演进，不跟随主仓。

附录B-脚手架代码结构

附录 B · 脚手架代码结构

B.1 总览

B.2 顶层文件

README.md

init.sh

B.3 skill-template/：业务表达层

SKILL.md.template

references/query-guide.md.template

references/cli-mapping.md.template

references/dsl-spec.md.template

references/terminology.md.template

B.4 scripts-template/：编译层

schema.yaml.template

commands/find-entity.yaml.template

commands/agg-entity.yaml.template

commands/_ext/batch.py.template

commands/_ext/find_dimension.py.template

B.5 eval-template/：测评

测试问题集.md.template

eval-runner.py.template