juhecli-sync 企微同步
juhecli-sync - 企业微信数据增量同步：消息同步与联系人数据同步
使用案例
同步最新消息同步联系人数据
同步消息
sync msg - 增量同步企微消息
>同步一下最新消息
// Agent 调用 db sync-status 获取初始 seq，再调用 sync msg
$juhe-cli sync msg --sync_key "12345" --limit 100
{
"data": {
"sync_key": "12399",
"continue_flag": 1,
"msg_list": [
{
"msg_id": "msg_001",
"content": "会议改到下午3点",
"from_username": "wxid_zhangsan",
"timestamp": 1710480000
}
]
}
}
同步联系人
sync multi_data - 同步联系人数据
>同步联系人数据
// Agent 调用 sync multi_data，business_id 设为 1（联系人类型）
$juhe-cli sync multi_data --business_id 1 --seq "" --limit 10
{
"data": {
"seq": "5678",
"continue_flag": 0,
"count": 15,
"contact_list": [
{
"username": "wxid_zhangsan",
"nickname": "张三",
"remark": "客户"
}
]
}
}
概述
企微同步 SKILL（juhecli-sync）负责将企业微信的消息和联系人数据增量同步到本地数据库。 通过 sync_key / seq 机制实现增量同步，确保本地数据与服务端保持一致。 同步后的数据可通过 db 系列 SKILL 查询使用。
sync_key 使用要点
sync_key 不能传 0 或空字符串。首次同步前需从 db sync-status 获取初始 seq 值， 后续使用每次同步返回的新 sync_key。触发方式
当用户用自然语言表达以下意图时，Agent 应激活此 SKILL：
- “同步消息” / “拉取最新消息” / “同步一下消息”
- “同步联系人” / “拉取最新联系人数据”
- “拉取最新数据” / “全量同步”
- “检查同步状态”（此时应引导至 db sync-status）
命令一览
| SKILL 名称 | 说明 |
|---|---|
juhecli-sync | 企微同步管理 - 同步消息、同步联系人数据，通过 sync_key 增量拉取 |
Agent 交互示例
sync msg - 首次同步消息
text
用户：帮我同步一下消息
Agent：好的，我先检查一下同步状态。
→ Agent 调用 db sync-status 获取初始 seq
Agent：获取到同步起点，开始同步消息。
→ Agent 调用 sync msg，使用 seq 作为 sync_key
Agent：消息同步完成，共拉取 87 条新消息。sync_key 禁忌
- 不要传 0 或空字符串
- 首次同步前，必须先从
db sync-status获取初始 seq - 每次同步后保存返回的新 sync_key，用于下次调用
limit(number) - 每次同步的消息数量上限，默认 100sync_key(string) [来自上次同步返回值] 或 [需查询] - 增量同步密钥，首次从 db sync-status 获取
sync msg - 持续增量同步
text
用户：再拉一批最新消息
Agent：好的，使用上次的同步位置继续拉取。
→ Agent 使用上次 sync msg 返回的 sync_key，调用 sync msg
Agent：增量同步完成，新增 23 条消息。sync multi_data - 同步联系人数据
text
用户：同步一下联系人数据
Agent：好的，我来同步联系人数据。
→ Agent 调用 sync multi_data，business_id 设为 1（联系人类型）
Agent：联系人数据同步完成，共更新 15 条记录。business_id(number) [用户提供] - 业务类型：1 = 联系人数据limit(number) - 每次同步数量，默认 10seq(string) [来自上次同步返回值] - 增量序列号，首次传空字符串
全量初始化同步
text
用户：这是一个新实例，帮我做全量同步
Agent：好的，我先检查同步状态，然后依次同步联系人和消息。
→ Agent 调用 db sync-status 获取初始 seq
→ Agent 调用 sync multi_data 同步联系人
→ Agent 调用 sync msg 同步消息
Agent：全量同步完成：
- 联系人：同步了 156 条
- 消息：同步了 500 条
后续可以定时做增量同步保持数据最新。参数来源速查
| 参数 | 来源标记 | 获取方式 |
|---|---|---|
sync_key | [来自上次同步返回值] | 上次 sync msg 返回值，Agent 应自动保存 |
sync_key（首次） | [需查询] | 必须先通过 db sync-status 获取 seq，将 seq 作为首次 sync_key |
business_id | [用户提供] | 用户指定同步的业务类型（1 = 联系人） |
seq | [来自上次同步返回值] | 上次 sync multi_data 返回值 |
典型工作流
工作流 1：首次同步消息
用户首次要求同步消息时，Agent 需按以下步骤操作：
- 查询同步状态：调用 db sync-status 获取当前 seq 值
- 首次同步：将 seq 作为 sync_key 调用 sync msg
- 保存位置：保存返回的新 sync_key，用于后续增量同步
工作流 2：持续增量同步
用户定期要求同步时，Agent 使用上次保存的 sync_key 调用 sync msg 拉取增量消息，然后保存新的 sync_key 供下次使用。
工作流 3：同步联系人数据
用户说“同步联系人”。Agent 调用 sync multi_data，business_id 设为 1，首次 seq 传空字符串，后续使用上次返回的 seq。
工作流 4：全量初始化
新实例部署后，用户要求全量同步。Agent 按顺序操作：
- 检查同步状态：调用 db sync-status 获取初始 seq
- 同步联系人：调用 sync multi_data（business_id=1）
- 同步消息：调用 sync msg，使用从 sync-status 获取的 seq 作为 sync_key
- 保存同步位置：保存 sync_key 和 seq 供后续增量同步使用
AI Agent 注意事项
sync_key绝不能传 0 或空字符串，首次必须从db sync-status获取- 每次同步后必须保存返回的 sync_key / seq，丢失会导致数据不一致
- 建议设置定时任务，每 5-10 分钟执行一次增量同步
- 首次同步建议使用较大 limit 值，后续可适当减小
- 同步失败时检查 sync_key 是否过期，必要时从
db sync-status重新获取 business_id参数由用户指定业务类型，Agent 需确认用户意图