nocobase-data-analysis

目标

使用 NocoBase MCP 工具找到正确的集合，安全地查询业务数据，并生成可靠的摘要或分组分析。

前提条件

• NocoBase MCP 必须已可访问并完成身份验证。
• 如果 MCP 返回身份验证错误，例如 Auth required，请停止操作，并让用户先刷新 MCP 身份验证。

默认策略

1. 首先检查数据源路径。
2. 优先使用 main 数据源。
3. 如果目标集合不在 main 中，则检查其他已启用的数据源。
4. 找到集合后，在后续每次 resource_* 调用中都明确指定该 dataSource。
5. 只有在确认查询参数约定后，才优先使用 resource_query 进行计数和分组分析。
6. 如果查询结果可疑或需要交叉核对，则改用 resource_list 并手动计数。

实用参考资料：

• 常见业务分析模式见 references/analysis-patterns.md
• 指标定义和范围检查见 references/metric-checklist.md
• 业务术语与集合、字段的映射见 references/entity-mapping.md

发现数据源

• 如果用户明确指定了数据源，则直接使用该数据源。
• 否则从 main 开始。
• 如果在 main 中找不到目标集合，则调用 data_sources:list_enabled，逐一检查其他已启用的数据源。
• 如果多个数据源中都存在同名集合：
  • 如果其中包含 main，则默认使用 main；
  • 否则列出候选项，并说明使用哪一个。
• 在最终答复中说明使用了哪个数据源。

发现集合

• 如果用户给出了集合名称，则在查询前确认该集合存在。
• 如果用户使用“潜在客户”“用户”“订单”或“商机”等业务术语，则检查集合元数据，将业务术语映射到实际集合名称。
• 优先使用 collections:listMeta 快速查看概况。
• 需要准确字段名、关联目标或枚举选项时，再使用 collections:get，并设置 appends: ["fields"]。
• 可将 references/entity-mapping.md 用作常见业务名词及可能字段类别的通用参考。

查询约定检查

使用 resource_query 前，确认请求格式符合实际后端约定：

• 使用 measures[].aggregation，而不是 aggregate
• 使用 orders[].order，而不是 direction
• field 通常应作为字段路径数组传入，例如 ["id"] 或 ["owner", "nickname"]
• 如果结果会在输出或 having 中引用，请使用 alias

正确示例：

{
  "resource": "lead",
  "dataSource": "main",
  "measures": [
    { "aggregation": "count", "field": ["id"], "alias": "lead_count" }
  ]
}

{
  "resource": "lead",
  "dataSource": "main",
  "dimensions": [
    { "field": ["status"], "alias": "status" }
  ],
  "measures": [
    { "aggregation": "count", "field": ["id"], "alias": "lead_count" }
  ],
  "orders": [
    { "field": ["status"], "alias": "status", "order": "asc" }
  ]
}

推荐工作流

1. 确认可访问性

• 使用 auth:check。
• 如果身份验证失败，则停止操作。

2. 查找集合

• 首先检查 main。
• 如果未找到，则检查其他已启用的数据源。
• 如果字段名或关联关系不确定，则在查询前读取字段信息。

3. 从简单计数开始

• 使用 resource_query，并仅指定一个 count(id) 度量。
• 首次查询应尽量精简，以便快速验证结果格式。

4. 添加分组分析

常见分组视图：

• 按状态
• 按负责人
• 按来源
• 按部门
• 按创建日期或月份

对于关联标签，请使用如下字段路径：

• ["owner", "nickname"]
• ["mainDepartment", "title"]

5. 按需交叉核对

遇到以下情况时，使用 resource_list 重新检查：

• 分组行出现意料之外的重复；
• 数值结果看起来像记录 ID，而不是计数；
• 汇总结果与分组输出的总数不一致；
• 集合可能受 ACL 范围或隐藏筛选条件影响。

交叉核对时：

• 获取足够的行以覆盖可见数据集，或使用分页；
• 根据返回的记录手动计数和分组；
• 将手动结果与 resource_query 的结果进行比较。

6. 呈现结果

报告以下内容：

• 使用的集合；
• 使用的数据源；
• 总数；
• 关键分组明细；
• 任何注意事项，例如 ACL 范围、空值或采用手动验证作为回退方案。

分析入口

查询前先对用户请求分类：

• overview：查询当前总数和主要分布
• distribution：按状态、负责人、来源、团队或部门统计分组数量
• funnel：分析按阶段推进的业务进程
• trend：分析按日期或月份划分的时间变化
• ranking：按负责人、来源、客户或产品列出排名
• quality-check：检查缺失值、空值过多的字段、可疑状态或孤立关联

每种模式的推荐查询结构请参阅 references/analysis-patterns.md。

指标定义检查

返回答案前，先核实指标范围：

• 包含的时间范围
• 用于确定时间范围的时间字段
• 指标是总数、去重计数、总和还是平均值
• 是否应纳入已归档、非活跃、空值或其他终止状态
• 分组总数是否与总计一致

如果用户请求含糊，或指标可能存在多种解释，请使用 references/metric-checklist.md。

常见问题

• 不要假设数据集合位于 main；先检查 main，再搜索其他已启用的数据源。
• 找到数据集合后，不要省略 dataSource。
• 不要在查询度量中使用 aggregate；后端要求使用 aggregation。
• 不要在查询排序中使用 direction；后端要求使用 order。
• 不要假设可疑的聚合结果正确。
• 如果“计数”结果看起来像 36、54、80 或其他可能的记录 ID，请确认是否实际执行了聚合。
• 按关联标签分组时，必须使用真实的关联路径和目标字段，不要猜测标签。

验证清单

• MCP 已完成身份验证。
• 所选数据源中存在该数据集合。
• dimensions、measures、orders 和 filter 中使用的字段均实际存在。
• resource_query 使用 aggregation 和 order。
• 汇总总数与分组总数一致，或已解释任何差异。
• 最终答案说明数据源以及使用的任何验证回退方案。