juhecli-device 设备管理
juhecli-device — 查询当前 app_key 下所有未过期设备列表，获取 GUID 等基础信息
使用案例
查看我有多少台设备设备 xxx 还在有效期吗切换到设备2
列出所有设备
查询当前 app_key 下的全部设备
>列出所有设备
// Agent 调用 device list 查询设备
$juhe-cli device list
{
"data": {
"list": [
{
"guid": "xxxx-xxxx-xxxx",
"client_type": 257,
"description": "企微-生产",
"expired_at": 0,
"uin": ""
},
{
"guid": "yyyy-yyyy-yyyy",
"client_type": 257,
"description": "企微-测试",
"expired_at": 0,
"uin": "1688856900xxxxxx"
}
]
}
}
检查设备状态
获取设备列表并判断有效期
>设备 xxx 还在有效期吗
// Agent 调用 device list 查看设备过期时间
$juhe-cli device list
{
"data": {
"list": [
{
"guid": "xxxx-xxxx-xxxx",
"client_type": 257,
"description": "企微-生产",
"expired_at": 1735689600,
"uin": "1688856900xxxxxx"
}
]
}
}
// expired_at > 0 表示设备仍在有效期内
概述
设备管理 SKILL 是所有其他 SKILL 的前置依赖。它查询当前 app_key 下所有未过期设备列表， 返回的 guid 字段是后续所有命令（登录、联系人、消息、群组等）的核心参数来源。
SKILL 定位
此 SKILL 的返回值
guid 是其他所有企微/个微 SKILL 的必需参数。 AI Agent 在执行任何企微操作前，应先调用此 SKILL 获取 guid。触发方式
用户可能会这样自然地表达需求：
- "查看设备列表"
- "有哪些设备"
- "我的设备"
- "看看我有几个设备"
命令列表
| SKILL 名称 | 说明 |
|---|---|
juhecli-device | 设备管理 - 查询当前 app_key 下所有未过期设备列表 |
详细命令说明
获取设备列表 (device list)
查询当前 app_key 下所有未过期的设备信息。自动使用配置文件中的 app_key 和 app_secret 进行认证，用户无需提供任何参数。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
app_key | string | 是 | [配置文件] | 自动读取，初始化时已写入 |
app_secret | string | 是 | [配置文件] | 自动读取，初始化时已写入 |
返回值
| 字段 | 说明 | 用途 |
|---|---|---|
guid | 设备唯一标识符 | 所有其他命令的核心参数 |
| 设备名称 | 设备的显示名称 | 帮助用户识别目标设备 |
| 过期时间 | 设备到期时间 | 判断设备是否可用 |
核心返回值
返回的
guid 是所有后续 SKILL 命令的必需参数。AI Agent 应在首次使用时缓存此值， 避免重复查询。Agent 交互示例
查看设备列表
text
用户: "查看我的设备"
AI: 好的，正在查询您的设备列表...
[Agent 调用 device list]
您有以下 2 个设备：
1. 设备1 (GUID: xxx-xxx-xxx, 到期: 2026-12-31)
2. 设备2 (GUID: yyy-yyy-yyy, 到期: 2026-06-30)
两个设备均在有效期内，可以正常使用。多设备选择
text
用户: "我有哪些设备？"
AI: [Agent 调用 device list]
您有 2 个设备：
1. 设备1 (到期: 2026-12-31)
2. 设备2 (到期: 2026-06-30)
用户: "用设备2登录"
AI: 好的，使用设备2 (GUID: yyy-yyy-yyy) 进行登录...
[Agent 使用该 guid 调用 login 相关命令]典型工作流
设备管理是所有操作的第一步，典型流程如下：
- 用户首次与 AI Agent 交互时，Agent 先调用
device list获取 guid - 从返回结果中记录 guid，用于后续所有操作
- 后续调用登录、联系人、消息等 SKILL 时，自动携带 guid 参数
- 当用户切换设备时，重新查询并更新 guid
text
// 完整工作流示例
用户: "帮我登录企业微信"
AI: 好的，先查看您的设备...
[Agent 调用 device list]
找到设备1 (GUID: xxx-xxx-xxx)，接下来为您获取登录二维码...
[Agent 使用 guid 调用 login qrcode]
请扫描二维码登录。
用户: "扫码完成了"
AI: [Agent 调用 login check 确认状态]
登录成功！现在可以使用企微功能了。错误处理
| 错误 | 原因 | 处理方式 |
|---|---|---|
| app_key/app_secret 未配置 | 未完成初始化配置 | 提示用户先完成初始化配置 |
| 网络错误 | API 地址不可达 | 检查网络连接，稍后重试 |
| 设备列表为空 | 所有设备已过期 | 提示用户联系管理员续期或添加新设备 |