juhecli-workflows 工作流编排
juhecli-workflows - 意图路由与多步操作编排中枢，将自然语言需求转换为精确的操作序列
使用案例
账号 Hanson 给所有客户发节日祝福新客户自动打标签并发送欢迎消息
给张三发消息hello
多步工作流：搜索联系人 → 发送消息
>给张三发消息hello
// Agent 调用 db contact search 查询张三的 username
$juhe-cli db contact search --keyword "张三"
{
"data": {
"list": [
{
"username": "wxid_zhangsan",
"nickname": "张三",
"remark": "客户"
}
]
}
}
// Agent 使用返回的 username 调用 wx msg send_text 发送消息
$juhe-cli wx msg send_text --to_username "wxid_zhangsan" --content "hello"
{
"error_code": 0,
"err_msg": "",
"data": {
"msg_id": "msg_002"
}
}
搜索包含合同的消息
db msg search - 按关键词搜索历史消息
>搜索包含合同的消息
// Agent 调用 db msg search 搜索历史消息
$juhe-cli db msg search --keyword "合同"
{
"data": {
"list": [
{
"msg_id": "msg_101",
"content": "合同已经发你邮箱了",
"from_username": "wxid_zhangsan",
"timestamp": 1710480000
},
{
"msg_id": "msg_102",
"content": "合同条款确认一下",
"from_username": "wxid_lisi",
"timestamp": 1710393600
}
]
}
}
概述
工作流编排 SKILL（juhecli-workflows）是意图路由与多步操作的编排中枢。 当用户用自然语言描述操作意图时，通过此 SKILL 确定协议类型（企微/个微）、 路由到正确的操作序列、协调多个 SKILL 按顺序执行。 涵盖发送消息、创建群聊、好友管理、消息搜索转发等常见多步操作。
核心价值
将自然语言意图转换为精确的多步操作序列，自动协调 db、msg、room、contact 等 SKILL 协同工作。
触发方式
当用户的请求涉及多个步骤或需要跨 SKILL 协调时，Agent 应参考此编排 SKILL：
- “给张三发消息” / “给李四发图片”
- “创建一个群把张三李四拉进来”
- “搜索包含合同的消息转发给张三”
- “看看我和张三的聊天记录”
- “加某某为好友” / “修改备注” / “删除好友”
- “邀请张三进群” / “把李四踢出群” / “修改群名”
SKILL 包
| SKILL 名称 | 说明 |
|---|---|
juhecli-workflows | 跨命令工作流编排 - 意图路由表和常见多步操作的工作流指南 |
协议判断规则
执行任何操作前，必须先确定使用企微还是个微命令：
| 用户表述 | 协议类型 | 说明 |
|---|---|---|
| 用户明确说“个微/微信/个人微信” | 个微协议 | 使用 wx 前缀命令，参数名为 to_username（wxid 格式） |
| 用户明确说“企微/企业微信” | 企微协议 | 使用无前缀命令，参数名为 conversation_id（user_id 格式） |
| 无法判断 | 需询问 | 主动询问用户“是个人微信还是企业微信？” |
协议混淆是最大错误源
- 个微命令使用
wx前缀，参数名是to_username（wxid 格式） - 企微命令无前缀，参数名是
conversation_id（user_id 格式） - 混淆使用会导致命令执行失败
意图路由表
根据用户意图快速定位操作步骤和涉及的 SKILL：
| 用户意图 | 操作步骤 | 涉及 SKILL |
|---|---|---|
| 给某人发文本消息 | 查联系人 → 发消息 | juhecli-db + juhecli-msg 或 juhecli-wx-msg |
| 给某人发图片 | 查联系人 → 上传图片 → 发图片 | juhecli-db + juhecli-wx-cloud + juhecli-wx-msg |
| 查看某人聊天记录 | 查联系人 → 查消息列表 | juhecli-db |
| 搜索历史消息 | 按关键词搜索消息 | juhecli-db |
| 创建群并邀请人 | 查所有成员 → 创建群 | juhecli-db + juhecli-wx-room |
| 邀请人进群 | 查群 → 查人 → 邀请 | juhecli-db + juhecli-wx-room |
| 加某人为好友 | 搜索联系人 → 添加好友 | juhecli-wx-contact |
| 修改好友备注 | 查联系人 → 改备注 | juhecli-db + juhecli-wx-contact |
| 搜索消息并转发 | 搜索消息 → 查目标人 → 转发 | juhecli-db + juhecli-wx-msg |
详细工作流
工作流 1：发送文本消息
text
用户：给张三发消息，说“会议改到下午3点”
Agent：好的，我先查找张三的信息。
→ Agent 调用 db contact search，keyword 为“张三”
→ 返回: username: "wxid_zhangsan"（个微）/ user_id: "zhangsan"（企微）
Agent：找到了张三（备注：客户-张三）。确认发给他吗？
用户：确认
→ Agent 判断协议：
如果是个微 → 调用 wx msg send_text，to_username 为 wxid_zhangsan
如果是企微 → 调用 msg send_text，conversation_id 为 zhangsan
Agent：消息已发送给张三。参数名区分
- 个微接收人参数：
to_username，值为 wxid 格式 - 企微接收人参数：
conversation_id，值为 user_id 格式 - 搜索结果有多人时需让用户确认
工作流 2：发送图片
text
用户：给张三发一张图片
Agent：好的，我先找到张三。
→ Agent 调用 db contact search，获取张三的 username
Agent：请提供要发送的图片链接。
用户：https://example.com/photo.jpg
Agent：好的，我来上传图片并发送。
→ Agent 调用 wx cloud upload 上传图片，获取 file_id、aes_key、file_size、file_md5
→ Agent 调用 wx msg send_image，传入图片信息和张三的 username
Agent：图片已发送给张三。关键步骤：发图片必须先通过 wx cloud upload 上传到 CDN，获取返回的文件信息后才能发送。上传返回的 file_id、aes_key、file_size、file_md5 都要传给发送命令。
工作流 3：创建群并邀请成员
text
用户：创建一个项目群，把张三和李四拉进来
Agent：好的，我先查找张三和李四的信息。
→ Agent 调用 db contact search 查询张三，获取 wxid_zhangsan
→ Agent 调用 db contact search 查询李四，获取 wxid_lisi
Agent：已找到张三和李四，现在创建群。
→ Agent 调用 wx room create，传入两人的 username_list
Agent：项目群已创建成功！需要修改群名吗？
用户：改成“Q2项目组”
→ Agent 调用 wx room modify_name 修改群名
Agent：群名已修改为“Q2项目组”。关键步骤：建群前需要逐个查询每个成员的 username，全部获取后再统一传入创建命令。
工作流 4：搜索并转发消息
text
用户：搜索包含“合同”的消息，转发给张三
Agent：好的，我先搜索消息。
→ Agent 调用 db msg search，keyword 为“合同”
→ 返回消息列表（包含 msg_id、content、msg_type 等）
Agent：找到以下消息：
1. [03-15] 李四：合同已经发你邮箱了
2. [03-14] 王五：合同条款确认一下
请确认要转发哪条？
用户：第一条
Agent：好的，我来查找张三并转发。
→ Agent 调用 db contact search 查询张三，获取 username
→ Agent 调用 wx msg send_refer，引用原文转发给张三
Agent：消息已转发给张三。工作流 5：查看聊天记录
text
用户：看看我和张三的聊天记录
Agent：好的，我先查找张三。
→ Agent 调用 db contact search，获取张三的 username
→ Agent 调用 db msg list，传入 username，获取最近 20 条消息
Agent：您和张三最近的聊天记录：
[10:30] 张三：合同已经发你邮箱了
[10:32] 你：好的，我看看
[10:45] 张三：有问题随时联系
需要查看更多或搜索特定内容吗？工作流 6：好友管理
text
用户：加手机号 138xxxx 为好友
Agent：好的，我来发送好友申请。
→ Agent 调用 wx contact add，keyword 为手机号，附带验证消息
Agent：好友申请已发送，等待对方通过。text
用户：把张三的备注改成“客户-张三”
Agent：好的，我先查找张三。
→ Agent 调用 db contact search，获取张三的 username
→ Agent 调用 wx contact remark，修改备注
Agent：备注已修改为“客户-张三”。好友管理操作：添加好友（wx contact add）、搜索好友（db contact search）、修改备注（wx contact remark）、删除好友（wx contact delete）。修改和删除操作需先通过 db contact search 获取 username。
工作流 7：群组操作
text
用户：把张三邀请到项目群里
Agent：好的，我先查找张三和项目群的信息。
→ Agent 调用 db contact search 查询张三，获取 username
→ Agent 调用 db room list 或 room list 查找项目群，获取 room_username
→ Agent 调用 wx room invite 邀请张三
Agent：张三已邀请到项目群。text
用户：把李四踢出销售组
Agent：我先确认一下李四的信息。
→ Agent 调用 db contact search 查询李四
→ Agent 查找销售组的 room_username
→ Agent 调用 wx room kick 移除李四
Agent：李四已从销售组移除。群组操作：邀请入群（wx room invite）、踢出群（wx room kick）、修改群名（wx room modify_name）。所有操作都需先获取目标人的 username 和群的 room_username。
关键字段映射速查
db contact search 返回值 → 各命令输入
| 返回字段 | 用途 |
|---|---|
username | 个微所有命令的 to_username / username / room_username 参数 |
user_id | 企微命令的 conversation_id 参数 |
nickname | 显示名称，用于向用户确认是否为目标联系人 |
remark | 备注名，可用于搜索匹配和确认 |
wx cloud upload 返回值 → 发送命令输入
| 返回字段 | 用途 |
|---|---|
file_id | send_image / send_file 的 file_id 参数 |
aes_key | send_image / send_file 的 aes_key 参数 |
file_size | send_image / send_file 的 size 参数 |
file_md5 | send_image / send_file 的 md5 参数 |
AI Agent 注意事项
- 执行任何操作前先确认协议（企微/个微），不确定时主动询问用户
db contact search是最核心的前置操作，几乎所有工作流的第一步都是它- 搜索结果有多人时列出供用户确认，不要自行假设
- 发图片必须先
wx cloud upload上传，再使用返回值发消息 - 建群需要逐个查询每个成员的 username，再统一传入 create 命令
- 保存每步返回的关键字段（username、file_id、room_username 等），供后续步骤使用
- 遇到错误及时向用户反馈并请求指导，不要跳过步骤继续执行
常见陷阱
- 混淆企微和个微的参数格式（to_username vs conversation_id）
- 直接使用姓名作为参数，而非查询获得的 ID
- 忘记先上传文件就尝试发送图片/文件消息
- 建群时只查了部分成员的 ID 就发起创建
- 转发消息时缺少 refer_msg 的完整结构