聚合智能
juhe-cli 开放平台
返回首页

juhecli-db 数据库查询

juhecli-db - 数据库查询核心依赖，提供联系人、消息、群聊、同步状态查询，驱动跨命令工作流

使用案例

账号 Hanson 的客户中有谁意向程度比较高搜索最近的群聊消息查询同步状态

搜索联系人张三

db contact search - 按关键词搜索联系人
>搜索联系人张三
// Agent 调用 db contact search 查询联系人
$juhe-cli db contact search --keyword "张三"
{ "data": { "list": [ { "username": "wxid_zhangsan", "nickname": "张三", "remark": "客户", "user_id": "zhangsan" } ] } }

查看聊天记录

db msg list - 查看与联系人的消息记录
>看看我和张三的聊天记录
// Agent 先调用 db contact search 获取 username，再调用 db msg list
$juhe-cli db msg list --username "wxid_zhangsan" --limit 20
{ "data": { "list": [ { "content": "合同已经发你邮箱了", "from_username": "wxid_zhangsan", "timestamp": 1710480000, "msg_type": 1 }, { "content": "好的，我看看", "from_username": "wxid_self", "timestamp": 1710480120, "msg_type": 1 } ] } }

概述

数据库查询 SKILL（juhecli-db）是整个生态的核心依赖组件。 用于查询由同步服务存储的企业微信数据，包括联系人、消息记录、群聊信息和同步状态。 几乎所有跨命令工作流都需要先通过此 SKILL 获取 ID 和基础数据。

核心依赖

发送消息前查联系人 ID、查看聊天记录、搜索历史消息、检查同步健康度等操作都依赖此 SKILL。 使用前需确保同步服务已运行。

触发方式

当用户用自然语言表达以下意图时，Agent 应激活此 SKILL：

  • “搜索联系人张三” / “找一下李四的信息”
  • “查看和张三的聊天记录” / “看看最近的消息”
  • “搜索包含合同的消息” / “找一下关于xxx的历史消息”
  • “查看群列表” / “我有哪些群”
  • “同步状态怎么样” / “检查一下同步是否正常”

命令一览

SKILL 名称说明
juhecli-db数据库查询 - 查询 juhe-sync 同步的联系人/消息/群聊/同步状态，是跨命令工作流的核心依赖

Agent 交互示例

db contact search - 搜索联系人（最核心的前置操作）

text
用户：帮我找一下张三的信息

Agent：好的，我来搜索。
→ Agent 调用 db contact search，keyword 为“张三”

Agent：找到以下联系人：
1. 张三（备注：客户-张三 / username: wxid_zhangsan / user_id: zhangsan）
2. 张三丰（备注：供应商 / username: wxid_zhangsanfeng / user_id: zhangsanfeng）
请问是哪位？
  • guid (string) [需查询] - 实例 GUID，通过 device list 获取
  • keyword (string) [用户提供] - 搜索关键词（匹配姓名、备注名、微信号等）

返回值（核心字段）：

  • username - 个微 ID（用于个微命令的 to_username 参数）
  • user_id - 企微 ID（用于企微命令的 conversation_id 参数）
  • nickname - 昵称
  • remark - 备注名

最关键的字段

db contact search 返回的 username 是后续绝大多数操作的关键输入： 发消息、查聊天记录、建群、邀请入群等都依赖它。务必保存此字段。

db contact search → db msg list - 查看聊天记录

text
用户：看看我和张三的聊天记录

Agent：好的，我先找到张三，然后查看聊天记录。
→ Agent 调用 db contact search 查询张三，获取 username
→ Agent 调用 db msg list，传入 username

Agent：您和张三最近的聊天记录：
[10:30] 张三：合同已经发你邮箱了
[10:32] 你：好的，我看看
[10:45] 张三：有问题随时联系
...
需要查看更多吗？
  • guid (string) [需查询] - 实例 GUID
  • username (string) [需查询] - 来自 db contact search 返回值，不能直接用人名
  • limit (number) - 消息数量，默认 20

db msg search - 搜索历史消息

text
用户：搜索一下包含“合同”的消息

Agent：好的，我来搜索历史消息。
→ Agent 调用 db msg search，keyword 为“合同”

Agent：找到以下包含“合同”的消息：
1. [2024-03-15 10:30] 张三：合同已经发你邮箱了
2. [2024-03-14 16:22] 李四：合同条款确认一下
3. [2024-03-12 09:15] 王五：新合同模板已上传
...
需要查看某条消息的详细内容吗？
  • guid (string) [需查询] - 实例 GUID
  • keyword (string) [用户提供] - 搜索关键词
  • start_time (string) - 开始时间（可选）
  • end_time (string) - 结束时间（可选）

db contact list - 联系人列表

text
用户：列出所有联系人

Agent：好的，我来获取联系人列表。
→ Agent 调用 db contact list

Agent：联系人列表（第1页，共20条）：
1. 张三 - 备注：客户-张三
2. 李四 - 备注：供应商
...
需要翻页查看更多吗？
  • guid (string) [需查询] - 实例 GUID
  • page (number) - 页码，默认 1
  • limit (number) - 每页数量，默认 20

db room list - 获取群聊列表

text
用户：我有哪些群

Agent：好的，我来查看群列表。
→ Agent 调用 db room list

Agent：您的群聊列表：
1. 项目讨论群（room_username: xxx@chatroom）
2. 销售组（room_username: yyy@chatroom）
3. 客户服务群（room_username: zzz@chatroom）
...
  • guid (string) [需查询] - 实例 GUID
  • page (number) - 页码
  • limit (number) - 每页数量

返回值：

  • room_username - 群 ID（格式如 xxx@chatroom）
  • nickname - 群名称

db sync-status - 查看同步状态

text
用户：同步状态正常吗

Agent：好的，我来检查。
→ Agent 调用 db sync-status

Agent：同步状态正常：
- 最后同步时间：10分钟前
- 联系人数量：156
- 消息数量：2,340
- 同步序列号：seq_xxx
  • guid (string) [需查询] - 实例 GUID

返回值：seq（同步序列号）、最后同步时间、各数据类型统计。其中 seq 是 sync msg 首次同步时 sync_key 的来源。

关键字段映射

db 查询返回值是其他命令的核心输入，以下是字段流转关系：

来源命令返回字段流向
db contact searchusername→ db msg list 的 username 参数；→ 发消息命令的 to_username / conversation_id 参数
db contact searchuser_id→ 企微命令的 conversation_id 参数
db room listroom_username→ 群操作命令的 room_id / room_username 参数
db sync-statusseq→ sync msg 首次同步的 sync_key 参数

参数来源速查

参数来源标记获取方式
guid[需查询]通过 device list 获取实例 GUID
keyword[用户提供]用户直接指定搜索关键词
username[需查询]通过 db contact search 获取，不能直接用人名
start_time / end_time[用户提供]用户指定时间范围（可选）

典型工作流

工作流 1：按姓名查 ID 后发消息

用户说“给张三发消息说你好”。Agent 分步操作：

  1. 搜索联系人：调用 db contact search，keyword 为“张三”
  2. 确认人员：如果返回多人，列出让用户确认
  3. 发送消息：使用返回的 username（个微）或 user_id（企微）调用对应的发消息命令

工作流 2：查看聊天记录

用户说“看看我和张三的聊天记录”。Agent 分步操作：

  1. 查找联系人：调用 db contact search 查询张三，获取 username
  2. 获取记录：调用 db msg list，传入 username，返回聊天消息列表

工作流 3：搜索历史消息

用户说“搜索关于合同的消息”。Agent 直接调用 db msg search，传入关键词“合同”，可选择指定时间范围缩小结果。

工作流 4：检查同步健康度

用户说“同步状态怎么样”。Agent 调用 db sync-status，返回同步序列号、最后同步时间和数据统计。如果发现异常，提醒用户可能需要重新执行 sync msg。

AI Agent 注意事项

  • db contact search 是最常用的前置命令，几乎所有发消息/查记录操作都需先调用它获取 username
  • 搜索结果有多人时，应列出供用户选择确认，不要自行假设
  • username 用于个微命令（to_username），user_id 用于企微命令（conversation_id），注意区分
  • db msg list 的 username 参数来自 db contact search，不能直接用人名
  • db sync-status 的 seq 是 sync msg 首次同步时 sync_key 的来源
  • 定期检查 sync-status 确保数据同步正常，异常时提醒用户