企业微信 CLI 安装引导与自然语言翻译
wecom-cli 是企业微信提供的命令行程序,让人类和 AI Agent 都能在终端中操作企业微信。
本技能分为两大部分:
- 自动安装 — 强制自动完成 CLI 和 Skills 的安装与初始化,无需询问用户
- 自然语言翻译 — 将用户的自然语言请求翻译为具体的
wecom-cli命令并执行
⚠️ 重要:当本技能被激活时,你必须立即自动执行第一部分的全部检查与安装步骤,不要询问用户是否要安装,直接执行命令。只有在遇到无法自动解决的错误时(如 Node.js 未安装且无法自动安装)才向用户报告。
第一部分:自动安装(强制执行)
强制规则:本部分的所有步骤必须自动执行,不要向用户询问”是否要安装”或”是否继续”。直接运行命令,只在失败时报告错误。
步骤 1:检查 Node.js 版本(强制)
立即执行:- Node.js >= 18 → 继续下一步
- 未安装或版本过低 → 停止并告知用户:
Node.js 18 或更高版本是必需的前置依赖,请先安装后重试。
- macOS/Linux 推荐使用 nvm:
nvm install 18 && nvm use 18 - Windows 推荐使用 nvm-windows 或直接从 Node.js 官网 下载安装
- macOS/Linux 推荐使用 nvm:
步骤 2:检查并安装 wecom-cli(强制)
立即执行:- 已安装 → 记录版本号,继续下一步
- 未安装(命令不存在)→ 立即自动安装,不要询问用户:
⚠️ 必须在npm install -g前设置NPM_CONFIG_PREFIX为QCLAW_NPM_GLOBAL_PREFIX的值(macOS/Linux 用export,Windows 用$env:)。Agent 子进程虽然注入了QCLAW_NPM_GLOBAL_PREFIX(macOS:~/Library/Application Support/QClaw/npm-global/,Windows:%APPDATA%/QClaw/npm-global/),但NPM_CONFIG_PREFIX可能在 exec tool 的 shell 环境中丢失,导致 npm 使用系统默认 prefix 安装到错误位置。 ⚠️ 禁止引导用户在外部终端手动执行npm install -g——外部终端的 npm prefix 不同,安装后 Agent 子进程仍然找不到。
步骤 3:检查并安装 Agent Skills(强制,不可跳过)
⚠️ 此步骤绝对不可跳过,即使 CLI 已安装、凭证已存在也必须执行此检查。Skills 是 LLM 调用企微功能的前提。首先检查 skills 是否已安装: macOS / Linux:
- 结果为 6(6 个 SKILL.md 都存在)→ Skills 已安装,继续下一步
- 结果 < 6(任何一个缺失)→ 先检查 Git,再安装:
- Git 可用 → 立即执行安装,不要询问用户:
- Git 未安装 → 停止并告知用户:
Git 是安装 Skills 的必要依赖(
skills add需要从 GitHub 拉取文件)。请先安装 Git:- macOS:
xcode-select --install或brew install git - Windows: 下载 Git for Windows
- Linux:
sudo apt install git或sudo yum install git
- macOS:
步骤 4:检查凭证状态(强制)
立即检查凭证目录: macOS / Linux:⚠️ 注意:凭证目录可通过环境变量判断逻辑:WECOM_CLI_CONFIG_DIR自定义,若该变量已设置,检查该目录下的bot.enc和mcp_config.enc。
步骤 5:初始化配置(仅凭证缺失时执行)
当步骤 4 判断需要初始化时,立即告知用户需要执行初始化并执行:wecom-cli init是交互式命令(需要用户扫码或输入凭证),因此这一步需要用户参与。告知用户:
- 推荐扫码接入:终端会显示二维码,用企业微信 App 扫描即可
- 备选手动输入:输入 Bot ID 和 Secret(获取方式参考 企业微信说明)
步骤 6:验证安装(强制)
立即执行验证命令:- 返回正常结果 → 安装成功,展示功能概览卡片
- 返回错误 → 凭证可能失效,提示用户重新执行
wecom-cli init
自动安装完整流程(AI 必须遵循)
安装问题排查
第二部分:自然语言翻译为 CLI 命令
翻译总则
当用户用自然语言描述企业微信操作时,按以下规则翻译为 CLI 命令:- 识别意图 → 判断属于哪个品类(contact/doc/meeting/msg/schedule/todo)
- 确定方法 → 匹配具体的工具方法
- 提取参数 → 从自然语言中提取参数值,构建 JSON
- 执行命令 → 运行
wecom-cli <品类> <方法> '<json参数>' - 解读结果 → 将 JSON 返回值翻译为用户友好的自然语言
⚠️ Windows (PowerShell) JSON 参数引号规则:PowerShell 对引号处理与 bash 不同。
- 简单 JSON(无嵌套双引号):
wecom-cli contact get_userlist '{}'可正常工作- 复杂 JSON(含双引号键值):需将外层改为双引号并转义内部双引号,例如:
- bash:
wecom-cli todo create_todo '{"content":"写周报"}'- PowerShell:
wecom-cli todo create_todo '{\"content\":\"写周报\"}'
品类与方法速查表
👤 通讯录(contact)
通讯录只有 get_userlist 一个方法,所有人员查找都走全量获取 + 本地筛选。
✅ 待办(todo)
关键规则:
- 查列表后必须查详情(
get_todo_list→get_todo_detail) - 人员 ID 必须通过
contact get_userlist转为姓名 - 分页
has_more=true时必须告知用户
🎥 会议(meeting)
关键规则:
- 时间格式
YYYY-MM-DD HH:mm - 查详情需两步:
list_user_meetings→get_meeting_info - 更新成员是全量覆盖,需先获取现有成员再合并
- 创建成功后展示会议号(每3位加
-分隔)
💬 消息(msg)
关键规则:
- 时间格式
YYYY-MM-DD HH:mm:ss,仅支持7天内 - chatid 通过
get_msg_chat_list按名称匹配 - 提到”群”时
chat_type=2,否则默认chat_type=1 - 发送前必须确认
- 非文本消息下载后必须告知路径并询问是否删除
📅 日程(schedule)
关键规则:
- 列表查询仅支持前后30天
- 返回的时间是 Unix 时间戳,需转为可读格式
- 未指定提醒时默认提前 15 分钟(
remind_before_event_secs: 900)
📄 文档 / 📊 智能表格(doc)
关键规则:
get_doc_content采用异步轮询:首次返回task_id,task_done=false时需携带task_id重复调用doc_type=3是文档,doc_type=10是智能表格- 支持
docid或url两种定位方式 - 字段更新只能改名不能改类型
翻译执行流程
当用户用自然语言提出请求时,按以下完整流程执行:多步操作示例
示例 1:“帮我看看我的待办,然后给张三发消息说周报已提交”
翻译为:示例 2:“查一下我和张三明天下午都有空的时间,约个1小时的会”
翻译为:功能概览卡片
安装成功后,向用户展示以下功能概览:注意事项
- 自动安装:本技能激活后必须自动执行安装检查和安装步骤,不要询问用户”是否安装”。只有 Node.js 缺失和
wecom-cli init(交互式)需要用户参与 - 前置条件:使用前需确保 Node.js >= 18 已安装,企业微信账号所在企业人数 ≤ 10 人
- 凭证安全:Bot ID 和 Secret 经 AES-256-GCM 加密存储在凭证目录(macOS/Linux:
~/.config/wecom/,Windows:%USERPROFILE%\.config\wecom\),请勿手动修改 - 凭证检测:执行任何操作前,先检查凭证目录下
bot.enc和mcp_config.enc是否存在;两者都存在则无需wecom-cli init,直接可用 - 自定义凭证路径:如用户设置了环境变量
WECOM_CLI_CONFIG_DIR,凭证文件位于该变量指定的目录下,检测时需先确认实际路径(macOS/Linux:echo $WECOM_CLI_CONFIG_DIR,Windows:echo $env:WECOM_CLI_CONFIG_DIR) - 重新初始化:如需更换 Bot,重新执行
wecom-cli init即可覆盖旧凭证 - 平台支持:macOS (x64/arm64)、Linux (x64/arm64)、Windows (x64)
- 自然语言翻译精度:若意图不明确,应向用户追问具体需求而非猜测执行
- 破坏性操作:删除待办、取消会议/日程等操作执行前必须向用户确认
- 错误重试:遇到 HTTP 错误时主动重试,最多 3 次
- userid 禁止暴露:所有展示给用户的信息中,userid 必须替换为真实姓名