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

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

1. 概述

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

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

1.1 核心价值

2. 触发条件

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

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）

CRM 域（8）

办公域（8）

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

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

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

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

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

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：

7. 代码生成强制规则

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

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

8. 高频踩坑速查

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

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