meshtastic_mqtt_server/doc/ACTIVE_QUERY_TOOL.md

活跃度查询工具

功能说明

当用户询问"当前有多少人活跃"或"现在有多少节点在线"时，AI 可以调用此工具查询实时活跃统计。

查询逻辑

活跃节点统计

• 查询数据库 nodeinfo 表的 updated_at 字段
• 统计指定时间范围内有更新记录的节点数量
• SQL: SELECT COUNT(*) FROM nodeinfo WHERE updated_at >= ?

活跃人数统计

• 查询数据库 text_message 表的 created_at 字段
• 统计指定时间范围内发送过消息的唯一用户数（按 from_id 去重）
• SQL: SELECT COUNT(DISTINCT from_id) FROM text_message WHERE created_at >= ?

参数说明

hours（可选）

• 类型：数字（浮点数）
• 说明：查询最近多少小时内的活跃数据
• 默认值：1 小时
• 取值范围：0.1 ~ 24 小时
• 示例：1、2、6、12、24、0.5

query_type（可选）

• 类型：字符串枚举
• 可选值：
  • both：同时查询节点和人数（默认）
  • nodes：仅查询活跃节点
  • users：仅查询活跃人数

使用示例

用户询问："现在有多少人活跃？"

AI 调用：

{
  "hours": 1,
  "query_type": "users"
}

返回：

最近 1.0 小时的活跃统计：

活跃人数：15 人

用户询问："最近6小时有多少节点在线？"

AI 调用：

{
  "hours": 6,
  "query_type": "nodes"
}

返回：

最近 6.0 小时的活跃统计：

活跃节点：25 个

用户询问："当前有多少人和节点活跃？"

AI 调用：

{
  "hours": 1,
  "query_type": "both"
}

或简化为（使用默认值）：

{}

返回：

最近 1.0 小时的活跃统计：

活跃节点：25 个
活跃人数：15 人

用户询问："今天有多少活跃用户？"

AI 调用（假设现在是下午3点）：

{
  "hours": 15,
  "query_type": "users"
}

返回：

最近 15.0 小时的活跃统计：

活跃人数：48 人

时间限制

• 默认时间：1 小时（用户未指定时间时）
• 最大时间：24 小时（超过24小时会自动限制到24小时）
• 最小精度：0.1 小时（6分钟）

这样设计的原因：

1. 默认1小时符合"当前活跃"的常见理解
2. 限制24小时避免查询过大范围影响性能
3. 支持小数便于精确控制时间范围（如0.5小时=30分钟）

技术实现

文件结构

internal/agents/active/
  ├── active.go          # 工具主逻辑
  └── active_test.go     # 单元测试

internal/store/
  └── active_store.go    # 数据库查询方法

核心接口

type ActiveStore interface {
    CountActiveNodes(since time.Time) (int64, error)
    CountActiveUsers(since time.Time) (int64, error)
}

工具注册

在 internal/ai/service.go 中通过空导入自动注册：

import (
    _ "meshtastic_mqtt_server/internal/agents/active"
    // ...
)

测试覆盖

• ✅ 默认查询（1小时，both）
• ✅ 指定时间查询（6小时、24小时）
• ✅ 仅查询节点
• ✅ 仅查询人数
• ✅ 时间限制（超过24小时自动限制）
• ✅ 工具启用状态检查

所有测试通过。

数据库性能

查询使用索引字段（updated_at、created_at），性能良好：

• nodeinfo 表通常记录数较少（几百到几千条）
• text_message 表使用 DISTINCT 去重，配合时间索引效率高
• 典型查询响应时间 < 10ms

使用场景

1. 实时监控："现在有多少人在线？"
2. 活跃度统计："最近一小时有多少活跃用户？"
3. 趋势分析："今天的活跃度怎么样？"
4. 对比分析："最近6小时有多少人活跃？"（可以多次查询不同时间范围对比）

与签到工具的区别

维度	活跃度查询	签到查询
数据源	nodeinfo + text_message	signs 表
统计维度	实时活跃（有更新/发消息）	主动签到
时间范围	最近N小时（最大24小时）	按自然日统计
用户意图	"现在有多少人在线"	"今天有多少人签到"
去重逻辑	自动按 from_id 去重	每节点每天仅一次