开发问数 Skill
问数 Skill 用来把某个数据场景中的查询条件、统计口径、字段解释和 TQL 模板沉淀为可复用能力。它不是一次性取数结果，而是让其它 Agent 在面对自然语言数据问题时，可以稳定识别业务对象、复用查询模板并解释结果。
真正的最佳实践不是在文档里堆大量 TQL 示例，而是把以下几件事做对：
- Skill 边界清楚，围绕一个主数据场景。
- 字段含义、类型、枚举、空值和关联关系解释完整。
- 查询模板覆盖有设计，既覆盖明细查询，也覆盖聚合统计。
- 模板提交前都经过实际执行验证。
- 最终 Skill 文件只保留可复用内容，不写过程记录和失败候选。
最快开始：用内置 Agent 生成问数 Skill
如果应用中已经有数据模型，优先使用平台内置的基于数据模型开发问数 Skill Agent。它会围绕指定模型组织开发流程，委派数据查询取数 Agent 生成并验证 TQL 模板，再把字段说明、查询模板和 Skill 使用说明提交为 Skill 元素。
可以这样发起：
基于 models.xxxx 这个模型，开发一个用于 <业务对象> 查询和统计的问数 Skill。
重点覆盖按核心字段查询明细、按状态/类型/时间筛选、聚合统计、TopN 排行。
内置 Agent 生成后，把这个 Skill 安装到目标业务助手、数据查询 Agent 或角色型 Agent 中。后续用户提问时，Agent 可以读取 Skill 中的字段说明和查询模板，复用已经验证通过的 TQL。
如果只是补充或验证一批查询模板，而不是生成完整 Skill，可以直接使用数据查询取数 Agent。
一个 Skill 专注一个数据场景
问数 Skill 的粒度要可控。推荐从一个主数据模型开始，让一个 Skill 专注一个清晰业务对象或数据场景。
这样做有三个好处：
- Agent 更容易判断用户问题是否属于该 Skill。
- 查询模板可以围绕同一套字段稳定组织。
- 字段解释、统计口径和空值规则更容易维护。
如果一个场景涉及多个模型，先确定主模型。关联模型只用于补充筛选、展示或解释口径；如果多个模型各自有独立问法、字段和统计口径，应拆成多个 Skill。
问数需求的普适分类
围绕一个数据模型，问数需求通常先分成两类：
- 基础查询：按模型字段筛选，返回明细记录。
- 聚合查询：按模型字段筛选、分组或计算，返回数量、去重数、汇总、分布、趋势、排行等结果。
分类只是覆盖维度，不等于模板数量。一个模型字段多、业务语义复杂时，每类下会有多条模板；字段少或查询价值低时，模板数量可以更少。设计模板时应把“字段语义”和“查询分类”组合起来看，而不是机械地为每个分类只生成一个模板。
用数据查询取数 Agent 生成和验证查询模板
查询模板的目标是降低 Agent 临场拼查询的负担。模板应做到参数替换后即可执行，而不是只写“支持按状态查询”“支持按月份统计”这类能力描述。
推荐流程：
- 用主模型 fullName 发起模板生成任务。
- 让
数据查询取数Agent 自行读取模型详情，理解字段和关联关系。 - 按基础查询和聚合查询设计候选模板。
- 每个候选模板都实际执行验证。
- 只把验证通过的模板放入最终模板集合。
- 失败候选、修正过程和无法验证原因只作为生成报告或评审信息，不进入最终 Skill 资源。
给数据查询取数 Agent 的任务应聚焦业务目标和交付物，不需要重复讲 TQL 语法。TQL 语法、函数能力、执行方式和失败修正由它的查询构建能力负责。
示例任务：
使用 models.xxxx 这个模型，围绕 <业务对象> 场景生成一组可复用的查询模板。
覆盖基础查询、组合筛选、聚合统计、分布分析、TopN 排行和空值分析。
每个候选模板都需要实际执行验证。
请直接生成一个 Markdown 模板文件，并返回文件路径。
核心文件体系
推荐文件结构：
skill-name/
├── SKILL.md
└── references/
├── data-model.md
└── query-template.md
三个文件的职责要分清：
| 文件 | 职责 | 不应包含 |
|---|---|---|
SKILL.md | 说明 Skill 的触发场景、使用目标、引用文件、分析流程和禁止事项 | 完整字段清单、大量 TQL、生成过程 |
references/data-model.md | 说明模型字段、类型、业务含义、枚举、空值、关联关系和类型风险 | 查询模板、一次性查询结果 |
references/query-template.md | 保存可复用的参数化查询模板、模板目录、执行语法、口径说明 | 验证状态、失败候选、修正过程 |
SKILL.md 怎么写
SKILL.md 负责让 Agent 判断“什么时候该用这个 Skill”。它应保持短而稳定，重点写：
- 业务对象和适用范围。
- 什么问题应该读取
references/data-model.md。 - 什么问题应该读取
references/query-template.md。 - 使用 Skill 时的分析流程。
- 禁止事项，例如不要臆造字段、不要混淆统计口径、不要执行数据写入。
description 要业务化，让其它 Agent 只看描述就知道这个 Skill 能处理什么问题。例如：
description: 当需要按客户、订单编号、订单状态、下单时间查询客户订单明细，并统计订单数量、订单金额汇总、状态分布和客户订单 TopN 时使用。
不要写成“用于模型问数”“支持基础查询和聚合查询”这类抽象描述。
data-model.md 怎么写
references/data-model.md 要帮助 Agent 正确理解字段和统计口径。至少包含：
| 内容 | 说明 |
|---|---|
| 模型信息 | 模型 fullName、标题、业务对象 |
| 完整字段清单 | 字段名、标题、类型、业务含义、查询用途、注意事项 |
| 关键字段语义 | 主体标识、名称、状态、类型、时间、金额、数量、关联对象 |
| 枚举和取值 | 状态、类型、阶段、轮次等字段的可用值和含义 |
| 空值规则 | 哪些字段可能为空，统计时是否单独计入或过滤 |
| 类型风险 | 文本型数值、日期字符串、公式字段、不能直接聚合的字段 |
| 关联关系 | 关联字段指向的模型，以及关联字段在本 Skill 中的用途 |
字段表应覆盖模型全部字段。无法判断业务含义时写“不确定”，不要省略字段。
query-template.md 怎么写
references/query-template.md 是问数 Skill 的核心参考文件。建议结构：
# <业务对象>查询模板
## 模板目录
| 编号 | 大类 | 模板标题 | 覆盖字段 | 适用问题 |
| --- | --- | --- | --- | --- |
## 执行语法
runFunction('models.services.ModelSvc', 'aiSelect', ['<TQL代码字符串>', 0, 50], True, '<业务化的查询场景标题>')
## 一、基础查询
### 1.1 <模板标题>
适用问题：
覆盖字段：
参数：
查询口径：
TQL：
## 二、聚合查询
### 2.1 <模板标题>
适用问题：
覆盖字段：
参数：
统计口径：
TQL：
模板正文只放最终可复用内容。最终提交的模板默认都是验证通过的，不需要在每个模板里写验证状态、验证记录或验证过程。
模板覆盖怎么评审
基础查询优先检查这些覆盖：
- 主体标识精确查询，例如编号、ID、单号。
- 名称或标题模糊查询。
- 状态、类型、分类筛选。
- 时间范围筛选。
- 关联对象筛选。
- 数值区间筛选。
- 多字段组合筛选。
- 明细查询的分页或
Limit策略。
聚合查询优先检查这些覆盖：
- 记录数。
- 去重数。
- 状态、类型、分类分布。
- 时间趋势。
- TopN 排行。
- 数值字段的合计、均值、最大值、最小值。
- 空值和非空统计。
没有适用字段时应说明原因，不要硬造模板。涉及类型转换、关联模型或复杂统计时，必须由数据查询取数 Agent 实际验证后再进入最终模板集合。
交付门禁
提交 Skill 前至少确认：
- Skill 标题和
description是具体业务化表达。 - 一个 Skill 只围绕一个主业务对象或主模型。
SKILL.md不堆字段清单和大量 TQL。data-model.md覆盖完整字段清单和关键口径。query-template.md开头有模板目录和统一执行语法。- 模板按基础查询和聚合查询组织，而不是按自然语言问法散乱堆砌。
- 每个模板都有参数说明、覆盖字段、查询口径或统计口径。
- 明细模板有分页或
Limit策略。 - 聚合模板说明统计口径。
- 进入最终模板集合的模板都已实际执行验证。
- 最终模板正文不包含验证状态、失败候选、修正过程或一次性查询结果。
- 不生成
README.md、CHANGELOG.md、过程报告等无关文件。
通用检查清单
开发或评审问数 Skill 时，按这份清单快速判断：
- 用户只看
description，能否知道这个 Skill 处理什么业务问题。 - Agent 是否能根据
SKILL.md判断何时读取字段说明和查询模板。 - 字段说明是否能防止 Agent 臆造字段、误用类型或混淆枚举。
- 查询模板是否覆盖主要字段和主要问法。
- 聚合模板是否把“数什么、按什么分组、按什么排序”说清楚。
- 模板是否足够具体，参数替换后即可执行。
- 模板是否已由内置 Agent 实际执行验证。
- 最终 Skill 文件是否只包含可复用内容，而不是生成过程。