Skip to main content

企业微信 CLI 安装引导与自然语言翻译

wecom-cli 是企业微信提供的命令行程序,让人类和 AI Agent 都能在终端中操作企业微信。
本技能分为两大部分:
  1. 自动安装强制自动完成 CLI 和 Skills 的安装与初始化,无需询问用户
  2. 自然语言翻译 — 将用户的自然语言请求翻译为具体的 wecom-cli 命令并执行
⚠️ 重要:当本技能被激活时,你必须立即自动执行第一部分的全部检查与安装步骤,不要询问用户是否要安装,直接执行命令。只有在遇到无法自动解决的错误时(如 Node.js 未安装且无法自动安装)才向用户报告。

第一部分:自动安装(强制执行)

强制规则:本部分的所有步骤必须自动执行,不要向用户询问”是否要安装”或”是否继续”。直接运行命令,只在失败时报告错误。

步骤 1:检查 Node.js 版本(强制)

立即执行:
  • Node.js >= 18 → 继续下一步
  • 未安装或版本过低 → 停止并告知用户
    Node.js 18 或更高版本是必需的前置依赖,请先安装后重试。

步骤 2:检查并安装 wecom-cli(强制)

立即执行:
  • 已安装 → 记录版本号,继续下一步
  • 未安装(命令不存在)→ 立即自动安装,不要询问用户
macOS / Linux:
Windows:
安装完成后验证:
如果安装失败(如权限问题),macOS/Linux 尝试:
仍然失败时才向用户报告错误。
⚠️ 必须npm install -g 前设置 NPM_CONFIG_PREFIXQCLAW_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:
Windows:
判断逻辑:
  • 结果为 6(6 个 SKILL.md 都存在)→ Skills 已安装,继续下一步
  • 结果 < 6(任何一个缺失)→ 先检查 Git,再安装:
检查 Git 是否可用:
  • Git 可用 → 立即执行安装,不要询问用户
  • Git 未安装 → 停止并告知用户
    Git 是安装 Skills 的必要依赖(skills add 需要从 GitHub 拉取文件)。请先安装 Git:
    • macOS: xcode-select --installbrew install git
    • Windows: 下载 Git for Windows
    • Linux: sudo apt install gitsudo yum install git
安装完成后再次使用上述对应平台的检查命令验证。 验证结果为 6 则继续,否则报告安装失败。

步骤 4:检查凭证状态(强制)

立即检查凭证目录: macOS / Linux:
Windows:
⚠️ 注意:凭证目录可通过环境变量 WECOM_CLI_CONFIG_DIR 自定义,若该变量已设置,检查该目录下的 bot.encmcp_config.enc
判断逻辑:

步骤 5:初始化配置(仅凭证缺失时执行)

当步骤 4 判断需要初始化时,立即告知用户需要执行初始化并执行:
wecom-cli init 是交互式命令(需要用户扫码或输入凭证),因此这一步需要用户参与。告知用户:
  • 推荐扫码接入:终端会显示二维码,用企业微信 App 扫描即可
  • 备选手动输入:输入 Bot ID 和 Secret(获取方式参考 企业微信说明

步骤 6:验证安装(强制)

立即执行验证命令:
  • 返回正常结果 → 安装成功,展示功能概览卡片
  • 返回错误 → 凭证可能失效,提示用户重新执行 wecom-cli init

自动安装完整流程(AI 必须遵循)

安装问题排查


第二部分:自然语言翻译为 CLI 命令

翻译总则

当用户用自然语言描述企业微信操作时,按以下规则翻译为 CLI 命令:
  1. 识别意图 → 判断属于哪个品类(contact/doc/meeting/msg/schedule/todo)
  2. 确定方法 → 匹配具体的工具方法
  3. 提取参数 → 从自然语言中提取参数值,构建 JSON
  4. 执行命令 → 运行 wecom-cli <品类> <方法> '<json参数>'
  5. 解读结果 → 将 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_listget_todo_detail
  • 人员 ID 必须通过 contact get_userlist 转为姓名
  • 分页 has_more=true必须告知用户

🎥 会议(meeting)

关键规则
  • 时间格式 YYYY-MM-DD HH:mm
  • 查详情需两步:list_user_meetingsget_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_idtask_done=false 时需携带 task_id 重复调用
  • doc_type=3 是文档,doc_type=10 是智能表格
  • 支持 docidurl 两种定位方式
  • 字段更新只能改名不能改类型

翻译执行流程

当用户用自然语言提出请求时,按以下完整流程执行:

多步操作示例

示例 1:“帮我看看我的待办,然后给张三发消息说周报已提交”

翻译为

示例 2:“查一下我和张三明天下午都有空的时间,约个1小时的会”

翻译为

功能概览卡片

安装成功后,向用户展示以下功能概览:

注意事项

  1. 自动安装:本技能激活后必须自动执行安装检查和安装步骤,不要询问用户”是否安装”。只有 Node.js 缺失和 wecom-cli init(交互式)需要用户参与
  2. 前置条件:使用前需确保 Node.js >= 18 已安装,企业微信账号所在企业人数 ≤ 10 人
  3. 凭证安全:Bot ID 和 Secret 经 AES-256-GCM 加密存储在凭证目录(macOS/Linux: ~/.config/wecom/,Windows: %USERPROFILE%\.config\wecom\),请勿手动修改
  4. 凭证检测:执行任何操作前,先检查凭证目录下 bot.encmcp_config.enc 是否存在;两者都存在则无需 wecom-cli init,直接可用
  5. 自定义凭证路径:如用户设置了环境变量 WECOM_CLI_CONFIG_DIR,凭证文件位于该变量指定的目录下,检测时需先确认实际路径(macOS/Linux: echo $WECOM_CLI_CONFIG_DIR,Windows: echo $env:WECOM_CLI_CONFIG_DIR
  6. 重新初始化:如需更换 Bot,重新执行 wecom-cli init 即可覆盖旧凭证
  7. 平台支持:macOS (x64/arm64)、Linux (x64/arm64)、Windows (x64)
  8. 自然语言翻译精度:若意图不明确,应向用户追问具体需求而非猜测执行
  9. 破坏性操作:删除待办、取消会议/日程等操作执行前必须向用户确认
  10. 错误重试:遇到 HTTP 错误时主动重试,最多 3 次
  11. userid 禁止暴露:所有展示给用户的信息中,userid 必须替换为真实姓名