Skip to content
MyAgent Cookbook

附录A-cost-query设计方案速读

附录 A · cost-query 设计方案速读

Section titled “附录 A · cost-query 设计方案速读”

本附录是 ontology-model 仓内 cost-query 技能的参考实现导览。阅读本附录前请先读完 Part 1-9。

⚠️ 关于本页的 ../ 链接:文中指向 本体与查询引擎/、.claude/skills/cost-query/、cctest/ 等的相对链接,指的是原 cost-query 源项目里的文件,不在本 wiki 内,点击会 404。它们仅作来源标注,需要原文请到源仓库查看。

A.1 cost-query 是什么

Section titled “A.1 cost-query 是什么”

成本数据问数技能：让业务用户用自然语言查项目成本数据、做对标判断、找差异原因、给降本动作建议。

  • 领域：建筑工程成本管理；
  • 数据：星型宽表（7 事实 + 12 维度）；
  • 角色定位：成本经理的数据助手；
  • 当前版本：V4.0（锚点 = wide-table-optimize-new 分支 2026-06-02）。

A.2 关键文档清单

Section titled “A.2 关键文档清单”

按本指南各章对应位置：

本指南章节cost-query 对应文档
Part 0V4.0 设计方案 §1-2（定位与架构）
Part 1V4.0 §2（分层架构）+ SKILL.md（业务表达层）
Part 2成本数据本体解读 + 宽表字段详细信息
Part 3V4.0 §4（Schema 双层架构）+ scripts/schema.yaml + references/schema/
Part 4V4.0 §8（DSL 语义层扩展）+ V4.0 §10（编译层）+ dsl-spec.md
Part 5V4.0 §7（CLI 指令系统）+ cli-mapping.md + commands/
Part 6V4.0 §5（SKILL 层）+ SKILL.md
Part 7V4.0 §6.1（query-guide.md 结构）+ query-guide.md
Part 8cctest/README.md + ontology-model CLAUDE.md §评测技能

A.3 cost-query 关键文件速览

Section titled “A.3 cost-query 关键文件速览”
.claude/skills/cost-query/
├── SKILL.md                              # 380 行：业务专家角色 + 6 步执行流程 + L1-L4 + 收口门 + 五差框架
│
├── references/
│   ├── query-guide.md                    # 478 行：M1-M6 模式手册 + 槽位填法 + 反模式
│   ├── cli-mapping.md                    # 189 行：指令决策表 + 二级指令清单
│   ├── dsl-spec.md                       # 471 行：DSL 语法 + 错误自救
│   ├── terminology.md                    # 119 行：业务词 → 标准词候选
│   └── schema/                           # 速查版（自动生成）
│       ├── _index.yaml                   # 19 cube 索引
│       ├── ProjectIndicator.yaml
│       ├── ProjectIndicatorDetail.yaml
│       ├── BqUnitPrice.yaml
│       ├── TalentMachinePrice.yaml
│       ├── BqIndicator.yaml
│       ├── BqBzItemIndicator.yaml
│       ├── BqUnitTalentMachineDetail.yaml
│       └── dimensions.yaml               # 12 维度合并
│
└── scripts/
    ├── query.py                          # 2835 行：DSL 编译 + CLI 入口
    ├── _builder.py                       # 1603 行：YAML → DSL 渲染
    ├── _registry.py                      # 55 行：commands 自动注册
    ├── cli.py                            # 180 行：MySQL 直连
    ├── fetch_schema.py                   # 576 行：schema.yaml → 速查版
    ├── schema.yaml                       # 935 行：DSL 编译唯一源
    └── commands/                         # 15 个二级指令 YAML
        ├── _ext/
        │   ├── batch.py
        │   └── find_dimension.py
        └── *.yaml × 15

A.4 cost-query 演进脉络（V1 → V4）

Section titled “A.4 cost-query 演进脉络（V1 → V4）”
版本时间时长主要变化关键沉淀
V12026-04-09 → 2026-04-21约 2 周本体（cost.ttl）+ HTTP API 编排（OBDA）概念层抽象 + Agent/Skill/CLI 三层雏形
V22026-04-22 → 2026-05-08约 2-3 周切到星型宽表 + schema.yaml + DSL → SQL + 二级指令双层指令抽象、routed measure、派生维度
V32026-05-09 → 2026-05-25约 2-3 周速查表 + 模式手册 + 双层 schema + 35 题测评LLM 一次做对、自动行为
V42026-05-26 → 2026-06-02约 1 周成本经理角色 + L1-L4 + 收口门 + 五差框架 + 71 题测评 + cost-clean / dp-query 配套业务表达层成熟

整体周期约 8 周，正好对应本指南的「2 个月计划」。

详见 V3.0 设计方案 §1.1（V2 → V3 关键 commits）与 V4.0 设计方案 §1（定位与三层架构）。

A.5 cost-query 借鉴时的注意

Section titled “A.5 cost-query 借鉴时的注意”

直接可借鉴

Section titled “直接可借鉴”
  • 三层架构（SKILL → 编译 → 数据）；
  • 双层 schema；
  • DSL 三 verb + 自动行为；
  • 二级指令 YAML 格式；
  • batch / find-dimension 通用封装；
  • query.py / _builder.py 编译器核心；
  • 错误自救机制；
  • 测评驱动闭环。

必须重做

Section titled “必须重做”
  • 业务专家角色（成本经理 → 你的角色）；
  • 维度 / 事实 cube 清单（领域专属）；
  • 数据语义陷阱（领域专属）；
  • 维度风险分级（领域专属）；
  • 模式手册 M1-Mn（领域专属）；
  • 反模式黑名单（领域专属）；
  • 归因框架（五差 → 你的领域版本）；
  • 业务术语对照表；
  • 测评集。

关键参数对照

Section titled “关键参数对照”

cost-query 关键参数在你领域可能的对应：

cost-query 概念含义你的领域对应（举例）
cube数据立方数据立方（保留概念）
indicator（routed measure）多路由度量你领域的多口径金额 / 数量
routedKey路由参数路由参数（保留概念）
measureGroups跨 (维度, 度量) 组合的批量度量跨 (科目, 状态) / 跨 (业态, 阶段) 等组合
isJianAn / isEndCost业态切分 / 父子层级你领域类似的层级切分字段
priceTimeAfter/Before时间窗 filter时间窗 filter（保留概念）
find-dimension维度探测维度探测（保留概念）
batch批量执行批量执行（保留概念）

A.6 进一步阅读

Section titled “A.6 进一步阅读”

按目的：