数据直查层（`data_*` 数据库 / 缓存 / 上游）

直接读数据库、缓存或上游平台，跳过 Service 层。全部只读。仅当 service_* 工具无法满足（自定义 filter、聚合统计、上游原始数据）时使用。

MongoDB

工具	参数	说明
`data_mongo_find`	`collection`(必填)、`filter`(JSON)、`fields`(字段投影数组)、`limit`(默认10,最大100)、`skip`、`sort`(JSON)	查询集合文档
`data_mongo_count`	`collection`(必填)、`filter`(JSON,可空)	统计符合条件的文档数
`data_mongo_export`	`collection`(必填)、`filter`(JSON)、`fields`(数组)、`sort`(JSON)、`max_docs`	全量导出到 NDJSON 文件，游标流式、内存常数级；仅回 localPath+count+summary
`data_mongo_aggregate`	`collection`(必填)、`pipeline`(JSON数组字符串,必填)、`max_docs`	聚合管道：在数据库侧完成过滤+关联(JOIN)+分组统计，结果流式落盘

collection 白名单（仅以下集合可查；$lookup/$graphLookup/$unionWith 引用的集合也必须在此列表内）： SiteInfoManageData、SiteInfoManageRecord、SimCardManage、SimCardMonthlyData、BatchDownloadConfig、SiteAnalysisConfig、StatisticsShutdown、StatisticsAlarm、SiteMonitorConfig、AutoUpdateConfigOption、AutoUpdateConfig

注意：UserInfo（内部用户身份数据）与 AiChatSessions（历史对话自由文本）已从白名单移除，不可直查，也不可作为 $lookup/$unionWith 的目标。

find/export 示例：

{ "collection": "SiteInfoManageData", "filter": "{\"sn\": \"xxx\"}", "limit": 10, "sort": "{\"createdAt\": -1}" }

用法提示：

filter / sort / pipeline 都是 JSON 字符串（如 "{\"sn\":\"xxx\"}"）。
分页用 skip + limit；大数据量导出用 data_mongo_export（不受 100 条上限）。
优先用对应的 service_* 工具；直查仅用于灵活筛选/聚合/关联。
所有 data_mongo_* 返回都无条件落盘：仅返回 localPath + summary，需用文件读取工具按 localPath 读取完整数据。

data_mongo_aggregate（聚合 / 跨集合 JOIN）

在数据库侧一次性完成"过滤 + 关联(JOIN) + 分组统计"，避免多次取数与 Agent 侧拼接，是大数据量关联任务的首选。

允许的只读阶段：$match、$project、$addFields/$set、$unset、$group、$sort、$limit、$skip、$count、$unwind、$lookup、$graphLookup、$unionWith、$facet、$bucket/$bucketAuto、$sortByCount、$replaceRoot/$replaceWith、$sample、$redact、$setWindowFields。

禁止的阶段（会被拒绝）：$out、$merge（写集合）、$function、$accumulator、$where（执行 JS）。

安全约束：

collection 及 $lookup/$graphLookup/$unionWith 引用的集合都必须在白名单内（含嵌套 pipeline，递归校验）。
每个阶段必须恰好一个顶层操作符。
结果超过 max_docs（默认 50000）会被截断。

字段字典（写 pipeline 必读）

SiteInfoManageData（站点信息，_id = 站点 SN）关键字段：

_id（站点 SN，20位）、iccId（SIM 卡 ICCID，20位；前 19 位 = GICCID）
province（州/省，如 "Puerto Rico"）、city、country（"United States"）、countryId、provinceId
activeStatus(1=已激活)、status(在线状态)、runStatus、connType、signal、batterySoc
installerName、version、realSysHdVersion、site(站点编码)、siteId
敏感字段（会被脱敏）：address/deviceAddress、longitude/latitude、contactNumber、userName/firstName/lastName、account、mac/deviceIp/imei

SimCardManage（SIM 卡，_id = GICCID 19位）关键字段：

_id（GICCID，19位）、status（UNKNOWN/NOT_ACTIVATED/ACTIVATED/DEACTIVATED/RETIRED）、platform（SmartHub/Acceleronix）
allDataUsage（累计用量，单位 KB）、month（yyyy-MM）、expirationTime、updateTime
敏感字段（会被脱敏）：imei、imsi、msisdn

SimCardMonthlyData（SIM 月用量）：simId(GICCID)、month、allDataUsage（单位 KB）、dailyUsage。

流量单位换算（写阈值必看）：allDataUsage、dailyUsage.dataUsage 一律为 KB。换算：1 MB = 1024 KB，1 GB = 1048576 KB。常用阈值：200MB = 204800、500MB = 512000、1GB = 1048576、2GB = 2097152。因此"流量大于 200M"应写 {"allDataUsage": {"$gt": 204800}}，不要用 200 或 200000000。

JOIN 关系图谱（跨集合关联键）

站点 ↔ SIM：SiteInfoManageData.iccId 取前 19 位 = SimCardManage._id（GICCID）。在 pipeline 中先用 $addFields 计算 giccid = $substrBytes(iccId, 0, 19)，再 $lookup 关联。
SIM ↔ 月用量：SimCardManage._id = SimCardMonthlyData.simId。

配方：波多黎各站点关联 SIM 信息（一步完成）

[
  { "$match": { "province": "Puerto Rico" } },
  { "$addFields": { "giccid": { "$substrBytes": ["$iccId", 0, 19] } } },
  { "$lookup": {
      "from": "SimCardManage",
      "localField": "giccid",
      "foreignField": "_id",
      "as": "sim"
  }},
  { "$project": {
      "sn": "$_id", "city": 1, "giccid": 1,
      "simStatus": { "$arrayElemAt": ["$sim.status", 0] },
      "simPlatform": { "$arrayElemAt": ["$sim.platform", 0] },
      "dataUsage": { "$arrayElemAt": ["$sim.allDataUsage", 0] }
  }}
]

调用（pipeline 作为 JSON 字符串传入）：

{ "collection": "SiteInfoManageData", "pipeline": "[{\"$match\":{\"province\":\"Puerto Rico\"}}, ...]" }

配方：按 SIM 流量阈值反向筛出站点信息（如"流量 > 200M 的站点"）

从 SIM 侧起点：先按用量过滤 SIM，再关联回站点，一步得到"高流量站点"清单。关键点：起点集合是 SimCardManage，用量阈值按 KB（200MB = 204800）；站点侧 iccId 前 19 位才等于 GICCID，故在 $lookup 的子 pipeline 里用 $substrBytes 对齐后再匹配。

[
  { "$match": { "allDataUsage": { "$gt": 204800 } } },
  { "$lookup": {
      "from": "SiteInfoManageData",
      "let": { "giccid": "$_id" },
      "pipeline": [
        { "$addFields": { "siteGiccid": { "$substrBytes": ["$iccId", 0, 19] } } },
        { "$match": { "$expr": { "$eq": ["$siteGiccid", "$$giccid"] } } },
        { "$project": { "sn": "$_id", "province": 1, "city": 1, "activeStatus": 1 } }
      ],
      "as": "sites"
  }},
  { "$match": { "sites": { "$ne": [] } } },
  { "$project": {
      "giccid": "$_id", "allDataUsage": 1, "platform": 1, "simStatus": "$status",
      "sites": 1
  }}
]

调用（pipeline 作为 JSON 字符串传入）：

{ "collection": "SimCardManage", "pipeline": "[{\"$match\":{\"allDataUsage\":{\"$gt\":204800}}}, ...]" }

说明：

阈值改其它值时按 KB 换算（见上面「流量单位换算」）。
只关心站点、不关心 SIM 明细时，可在末尾加 {"$unwind":"$sites"} + {"$replaceRoot":{"newRoot":"$sites"}} 直接输出站点文档。
只要计数（"有多少个这样的站点"）时，末尾用 {"$unwind":"$sites"} 后接 {"$count":"siteCount"}，不要把明细拉回上下文。

配方：按州统计站点数与激活率

[
  { "$group": {
      "_id": "$province",
      "total": { "$sum": 1 },
      "active": { "$sum": { "$cond": [{ "$eq": ["$activeStatus", 1] }, 1, 0] } }
  }},
  { "$sort": { "total": -1 } }
]

约束与反模式

跨集合关联必须在库侧一步完成（硬约束）：凡是"站点 ↔ SIM ↔ 月用量"之间的关联/条件筛选（如"流量>200M的站点""某州站点的SIM状态"），必须用 data_mongo_aggregate 的 $lookup 在数据库侧完成。禁止分别 data_mongo_find/data_sim_* 拉两张表的明细，再在 Agent 上下文里手工遍历、匹配、过滤——这会把大量数据灌入上下文导致膨胀/超时，正是要避免的反模式。
若一次聚合难以表达，可先用 $match+$group/$count 在库侧收敛出少量键（如符合条件的 GICCID/SN 列表），再用该小列表做下一步；始终让"大数据量筛选"发生在数据库侧。
不要用 $project/$group 把敏感字段（contactNumber/imei/longitude 等）重命名成新字段名或拼接进字符串——脱敏按字段名匹配，改名可能绕过脱敏，导致隐私外泄。保留敏感字段原名或直接不输出。
$lookup 关联大集合时注意被关联集合的关联字段应有索引（SimCardManage._id、SimCardMonthlyData.simId 已有）。
只需计数/分组时优先 $group，不要把明细 $push 出来再在 Agent 侧数。
需要把结果交给用户或后续脚本时，按 localPath 读取 NDJSON 文件处理。

Redis

工具	参数	说明
`data_redis_get`	`key`、`type`(string默认/hash/list/set)	读取 key 的值（仅支持 string 和 hash）
`data_redis_exists`	`key`	检查 key 是否存在并返回 TTL

PostgreSQL（告警快照）

工具	参数	说明
`data_pgsql_query_snapshot_data`	`sn`、`date`	按 SN 和日期查告警快照数据
`data_pgsql_query_snapshot_file_record`	`file_name`	查告警快照文件的解析记录

EMS 参数字典

工具	参数	说明
`data_emspara_pid_info`	`id`(PID ID 数字字符串)	通过 PID ID 查宏名和描述
`data_emspara_vid_info`	`id`(VID ID 数字字符串)	通过 VID ID 查宏名和描述

用于把 EMS 日志/参数中的数字 PID/VID 翻译成可读含义。

SIM 上游平台

优先用 service_sim_*（见主 SKILL.md 第 4 节）；需上游原始数据时用：

Acceleronix | 工具 | 参数 | 说明 | |------|------|------| | data_sim_acceleronix_card_info | iccid | 单张 SIM 详情 | | data_sim_acceleronix_card_list | page、size | SIM 卡列表 | | data_sim_acceleronix_batch_data_info | iccid_list(逗号分隔)、month(YYYYMM) | 批量用量信息 | | data_sim_acceleronix_data_pool_list | page、size | 流量池列表 | | data_sim_acceleronix_data_pool_sim_info | data_pool_id、page、size | 流量池中的 SIM 详情 |

SmartHub | 工具 | 参数 | 说明 | |------|------|------| | data_sim_smarthub_card_info | giccid | 单张 SIM 详细信息 | | data_sim_smarthub_batch_info | page、size | 批量 SIM 信息 |

注意：Acceleronix 用 iccid，SmartHub 用 giccid；月份参数 Acceleronix 批量用量为 YYYYMM。

data-direct-query.md 11 KB História Raw

数据直查层（data_* 数据库 / 缓存 / 上游）