Imported from OmniSocKit/Open-Wecom-Skills (skills/SKILL.md). Install upstream with npx skills add OmniSocKit/Open-Wecom-Skills --skill skills. Copyright stays with the author.

Open WeCom Skills — 企业微信开发知识体系

你现在是企业微信开放能力专家。本 SKILL 是整个知识体系的入口与导航，指导你如何高效查阅和使用 skills/ 目录下的 41 个子 SKILL 文档。

1. 概述

Open WeCom Skills 是一套为 AI 深度优化的企业微信开发结构化知识库，源于六年企微生态实战经验：

精确 API 知识 — 每个接口的参数、响应、限制都有结构化定义，杜绝 AI 幻觉
踩坑指南 — 内置 Gotcha Guide，提炼真实项目中的边界条件与陷阱
即用代码模板 — Python / TypeScript / Go / Java / PHP 五语言模板

1.1 核心价值

无 SKILL	有 SKILL
AI 凭记忆编造 API 参数	AI 精确查阅接口定义
遗漏 WelcomeCode 20 秒时限	主动提醒关键限制
搞混 `follow_user` vs `follow_info`	参数语义完全准确
不知道 linkedcorp 全 POST	知道每个踩坑点

2. 触发条件

当用户的需求涉及以下关键词时，应激活本 SKILL 并按需加载对应子 SKILL：

关键词	说明
企业微信、WeCom、企微	泛指企微相关开发
`qyapi.weixin.qq.com`	企微 API 域名
`corpid`、`corpsecret`、`access_token`	认证凭证相关
通讯录、成员、部门	通讯录管理
客户联系、SCRM、外部联系人	CRM 域
群发、欢迎语、朋友圈	营销触达
审批、打卡、日程	办公域
微信客服、会话	客服域
JS-SDK、小程序、H5	客户端域
服务商、代开发、ISV	服务商模式
第三方应用、应用市场	第三方应用模式
会话存档、安全管理	高级域

3. 目录结构

skills/
├── SKILL.md                  ← 你正在阅读的入口文件
├── enterprise/               # 企业内部开发（30 个子 SKILL）
│   ├── wecom-core.md         #   认证基座（所有 SKILL 的前置依赖）
│   ├── wecom-contact.md      #   通讯录管理
│   ├── wecom-app.md          #   应用管理
│   ├── wecom-message.md      #   消息管理
│   ├── wecom-media.md        #   素材管理
│   ├── wecom-auth.md         #   身份验证
│   ├── wecom-jssdk.md        #   JS-SDK
│   ├── wecom-crm-*.md        #   CRM 域（8 个）
│   ├── wecom-approval.md     #   审批
│   ├── wecom-doc.md          #   文档
│   ├── wecom-meeting.md      #   会议
│   ├── wecom-office-*.md     #   办公域（4 个）
│   ├── wecom-kf.md           #   微信客服
│   ├── wecom-miniapp.md      #   小程序
│   ├── wecom-mobile-sdk.md   #   移动端 SDK
│   ├── wecom-advanced.md     #   高级功能
│   ├── wecom-security.md     #   安全管理
│   ├── wecom-data-intelligence.md  # 数据与智能
│   └── wecom-vertical.md     #   行业方案
├── isv/                      # 服务商代开发（8 个子 SKILL）
│   ├── wecom-isv-core.md     #   三级凭证体系
│   ├── wecom-isv-auth.md     #   授权流程
│   ├── wecom-isv-callback.md #   双通道回调
│   ├── wecom-isv-license.md  #   接口调用许可
│   ├── wecom-isv-billing.md  #   收银台
│   ├── wecom-isv-jssdk.md    #   JS-SDK 差异
│   ├── wecom-isv-provider.md #   服务商管理
│   └── wecom-isv-appendix.md #   错误码与兼容性
└── third-party/              # 第三方应用开发（3 个子 SKILL）
    ├── wecom-3rd-quickstart.md  # 快速入门
    ├── wecom-3rd-idconvert.md   # ID 转换
    └── wecom-3rd-data.md        # 数据 API

4. 子 SKILL 索引速查

4.1 企业内部开发 (`enterprise/`) — 30 SKILL

自建应用使用 corpid + corpsecret 获取 access_token，直接调用 API。

基础域（7）

子 SKILL	说明	API 数
`wecom-core`	必读基座 · access_token · 回调验签 · 频率限制 · 错误码	5
`wecom-contact`	成员 / 部门 / 标签 CRUD · 异步批量导入	35
`wecom-app`	应用管理 · 自定义菜单 · 工作台 · 自建机器人	20
`wecom-message`	消息发送 · 模板卡片 · 群聊 · 撤回	25
`wecom-media`	素材上传下载 · 图片 / 语音 / 文件	6
`wecom-auth`	OAuth2 · 扫码登录 · SSO · 二次验证	12
`wecom-jssdk`	网页 JS-SDK · 签名 · 分享 · 定位	30

CRM 域（8）

子 SKILL	说明	API 数
`wecom-crm-customer`	客户列表 · 详情 · 备注 · unionid 转换	8
`wecom-crm-tag`	企业标签 · 规则组标签 · 编辑客户标签	12
`wecom-crm-masssend`	群发消息 · 欢迎语 · 群发记录	10
`wecom-crm-contactway`	联系我 · 渠道活码 · 入群方式	14
`wecom-crm-moment`	客户朋友圈 · 发表 / 互动 / 统计	12
`wecom-crm-group`	客户群管理 · opengid 转换 · 加群方式	8
`wecom-crm-transfer`	在职 / 离职继承 · 接替状态查询	8
`wecom-crm-acquisition`	获客助手 · 获客链接 · 额度统计	10

办公域（8）

子 SKILL	说明	API 数
`wecom-approval`	审批模板 · 实例 CRUD · 流程推进	15
`wecom-doc`	文档 · 权限 · 收集表	15
`wecom-meeting`	会议 · 预约 / PSTN / 网络研讨会	12
`wecom-office-checkin`	打卡规则 · 记录 · 月度汇总	6
`wecom-office-calendar`	日历 · 日程 · 参与者管理	10
`wecom-office-email`	邮件 · 收件箱 · 群组邮箱	12
`wecom-office-wedrive`	微盘 · 文件管理 · 分块上传	18
`wecom-office-live`	直播 · 预约 / 统计 / 回放	8

客服域（1）· 客户端域（3）· 高级域（3）· 行业域（1）

子 SKILL	说明	API 数
`wecom-kf`	微信客服 · 会话 / 消息 / 知识库	22
`wecom-miniapp`	小程序 · 登录认证 · jwecom	15
`wecom-mobile-sdk`	iOS / Android / Harmony SDK	7
`wecom-advanced`	会话存档 · 企业支付 · 电子发票	40
`wecom-security`	文件防泄漏 · 设备 · 人事管理	18
`wecom-data-intelligence`	AI 模型 · 知识集 · 专区	35
`wecom-vertical`	家校 / 政民 / 上下游 / 互联 / 收款	90

4.2 服务商代开发 (`isv/`) — 8 SKILL

使用 suite_access_token / provider_access_token 三级凭证体系。

子 SKILL	说明
`wecom-isv-core`	必读基座 · 三级凭证 · 自建差异 · 多企业架构
`wecom-isv-auth`	授权流程 · 预授权码 · 永久授权码
`wecom-isv-callback`	双通道回调 · 指令回调 + 数据回调
`wecom-isv-license`	接口调用许可 · 购买 / 续期 / 激活
`wecom-isv-billing`	收银台 · 定价 · 收款订单
`wecom-isv-jssdk`	JS-SDK 签名差异 · 代开发模式
`wecom-isv-provider`	服务商管理 · 登录 · ID 转换
`wecom-isv-appendix`	错误码 · 频率限制 · 兼容性矩阵

4.3 第三方应用开发 (`third-party/`) — 3 SKILL

应用市场分发，凭证体系复用 ISV SKILL，业务 API 复用企业内部开发 SKILL。

子 SKILL	说明
`wecom-3rd-quickstart`	注册 → 授权 → 上架 → 推广全流程
`wecom-3rd-idconvert`	corpid / userid / external_userid 加密互转
`wecom-3rd-data`	获客组件 · 会话存档 · AI 模型接入

5. 使用工作流

收到企业微信开发需求时，遵循以下四步流程：

Step 1 — 识别所需的子 SKILL

根据用户需求关键词，对照第 2 节触发条件表和第 4 节索引速查，确定需要加载的子 SKILL 文件。

规则：wecom-core（或 ISV 场景下的 wecom-isv-core）是所有场景的前置依赖，必须优先阅读。

Step 2 — 加载子 SKILL 文档

读取对应的 .md 文件，获取精确的 API 定义、参数约束和踩坑指南：

# 示例：用户需要实现客户标签管理
1. 先读 skills/enterprise/wecom-core.md      （认证基座）
2. 再读 skills/enterprise/wecom-crm-tag.md   （标签 API）

Step 3 — 基于 SKILL 生成代码

严格依据子 SKILL 中的 API 定义生成代码，禁止凭记忆编造 API 参数。

Step 4 — 交叉验证

对照子 SKILL 中的 Gotcha Guide（踩坑指南），检查生成的代码是否遗漏关键约束。

6. 需求路由表

当用户描述业务需求时，快速定位应加载的子 SKILL：

需求关键词	推荐子 SKILL
成员、部门、标签、通讯录	`wecom-contact`
发消息、群聊、机器人、webhook	`wecom-message`
应用配置、菜单、工作台	`wecom-app`
登录、OAuth、身份、扫码	`wecom-auth`
客户、外部联系人、unionid	`wecom-crm-customer`
客户标签、规则组	`wecom-crm-tag`
群发、欢迎语	`wecom-crm-masssend`
联系我、渠道活码	`wecom-crm-contactway`
朋友圈	`wecom-crm-moment`
客户群	`wecom-crm-group`
离职继承、在职继承	`wecom-crm-transfer`
获客助手	`wecom-crm-acquisition`
审批、请假、报销	`wecom-approval`
会议、预约、录制	`wecom-meeting`
客服、对话、工单	`wecom-kf`
文档、表格、收集表	`wecom-doc`
图片、文件、素材	`wecom-media`
打卡、日程、邮件、微盘、直播	`wecom-office-*`
JS-SDK、H5、网页	`wecom-jssdk`
小程序	`wecom-miniapp`
支付、存档、安全	`wecom-advanced`
家校、政务、上下游	`wecom-vertical`
服务商、代开发、ISV	`wecom-isv-*`
第三方应用、应用市场	`wecom-3rd-*`

7. 代码生成强制规则

生成企业微信相关代码时，必须遵守以下规则（详见 wecom-core.md 第 7 节）：

Token 缓存 — 实现 access_token 缓存 + 过期前主动刷新，禁止每次请求都调用 gettoken
错误重试 — errcode=-1（系统繁忙）自动重试，最多 3 次，间隔递增
Token 失效处理 — errcode=42001/40014 时自动刷新 token 并重试一次
类型安全 — 强类型语言必须定义请求 / 响应的类型或结构体
超时设置 — HTTP 请求必须设置超时（建议 10 秒）
敏感信息隔离 — corpid / corpsecret 从环境变量读取，禁止硬编码
日志规范 — 记录请求路径、errcode、耗时，但 access_token 不得明文记录
幂等标注 — 代码注释中标注该操作是否幂等

8. 高频踩坑速查

以下是跨 SKILL 的高频陷阱，各子 SKILL 中有更详细的 Gotcha Guide：

陷阱	说明	涉及 SKILL
Token 互相覆盖	多实例部署各自获取 token，后获取的使先前的失效	`wecom-core`
WelcomeCode 20 秒过期	必须在 20 秒内使用，超时即失效	`wecom-crm-masssend`
`follow_user` vs `follow_info`	字段语义不同，混用会导致数据错误	`wecom-crm-customer`
linkedcorp 全 POST	企业互联的所有 API 都是 POST，即使是查询	`wecom-contact`
回调 5 秒超时	回调必须 5 秒内响应，建议异步处理业务逻辑	`wecom-core`
IP 白名单	服务器出口 IP 可能与预期不同（NAT / LB）	`wecom-core`
`external_userid` 不同调用方不同	不同应用获取的值不同，不可混用	`wecom-crm-customer`
审批模板 ID 与实例 ID 混淆	`template_id` 和 `sp_no` 是不同概念	`wecom-approval`

9. 安全说明

本知识库是纯知识交付，零副作用：

不调用外部 API — 不会向企业微信或任何第三方服务器发送请求
不需要凭证 — 不要求提供 corpid、secret、access_token 等敏感信息
不收集数据 — 不包含遥测、埋点、使用统计
内容可验证 — 所有 SKILL 内容基于开源知识库，可交叉校验

10. 相关资源

官方文档：https://developer.work.weixin.qq.com/document/
错误码查询：https://developer.work.weixin.qq.com/devtool/query
MCP Server：npx @omnisockit/mcp-server
GitHub：https://github.com/OmniSocKit/Open-Wecom-Skills

open-wecom-skills

About