wecom-user-manager

---

name: wecom-user-manager description: 企业微信用户管理技能。支持管理员添加用户权限，用户首次登录自动激活。包含完整的用户生命周期管理。 metadata: { "openclaw": { "emoji": "👤", "requires": { "bins": ["python3"] } }, }

---

企业微信用户管理技能

> 完整的用户生命周期管理：添加用户 → 自动激活 → 权限管理

---

🎯 功能概述

管理员视角

✅ 添加用户权限（支持自然语言命令）

✅ 发送确认卡片

✅ 处理回调创建用户

用户视角

✅ 首次登录自动激活

✅ 自动获取真实姓名

✅ 欢迎消息和权限信息

---

📱 使用流程

流程 1：管理员添加用户

管理员：添加用户 zhangsan 店长 正义路
机器人：
┌────────────────────────────────┐
│ 请确认以下信息                  │
│ UserID: zhangsan               │
│                                │
│ 角色：店长                      │
│ 门店：昆明五华区正义路 60 号红谷  │
│                                │
│ ℹ️  姓名将在首次登录时自动获取  │
│                                │
│ [✅ 确认添加] [🔄 重新选择]    │
└────────────────────────────────┘
管理员点击确认：
✅ 用户添加成功！
ℹ️  姓名将在首次登录时自动获取

流程 2：用户首次登录

用户（首次）：你好
机器人：
👋 欢迎使用红谷门店经营助手！
检测到您是首次使用，正在激活账户...
✅ 账户已激活
姓名：张三
企业微信 ID: zhangsan
角色：店长
门店：1 家
现在可以开始使用了！

流程 3：用户再次登录

用户：早上好
机器人：
早上好，张三！有什么可以帮您？

---

🔧 核心功能

1. 添加用户

命令格式：

添加用户  <角色> <门店/地区>

支持的角色：

总部管理员/总部/管理员

区域经理/区域/大区

省份经理/省份/省级

城市经理/城市

店长

店员/导购

示例：

添加用户 zhangsan 店长 正义路
添加用户 liming 省份经理 云南
添加用户 wangwu 区域经理 西南区

2. 自动激活

触发条件：

用户首次发送任意消息

用户状态为"待激活_xxx"

激活流程： 1. 提取 UserID 和姓名 2. 检查用户状态 3. 更新用户名（从"待激活_" → 真实姓名） 4. 记录登录时间 5. 发送欢迎消息

3. 权限检查

可以添加用户的角色：

✅ 总部管理员

✅ 区域经理

✅ 省份经理

不可以添加用户的角色：

❌ 城市经理

❌ 店长

❌ 店员

---

📁 文件结构

wecom-user-manager/
├── SKILL.md                    # 技能文档（本文件）
├── handler.py                  # 消息处理器
├── auto_activate.py            # 自动激活脚本
├── references/
│   └── api-user-manager.md     # API 文档
└── tests/
    └── test_user_manager.py    # 测试脚本

---

🔗 API 接口

add_user — 添加用户

wecom_mcp call user add_user '{"userid": "zhangsan", "role": "store_manager", "store_id": "xxx"}'

activate_user — 激活用户

wecom_mcp call user activate_user '{"userid": "zhangsan", "name": "张三"}'

check_user — 检查用户状态

wecom_mcp call user check_user '{"userid": "zhangsan"}'

---

⚠️ 注意事项

1. UserID 格式

必须是企业微信中的真实 UserID

可以在企业微信管理后台查看

格式如：zhangsan、liming001、10001

2. 姓名获取

添加时无需提供姓名

首次登录时自动从企业微信获取

确保 UserID 与企业微信一致

3. 门店搜索

支持模糊搜索

输入关键词即可（如"正义路"）

如有多个匹配，会提示选择

4. 配置文件同步

工作区和插件目录的 users.json 需要保持同步

激活后自动同步

---

🧪 测试用例

测试 1：添加用户

python3 handler.py handle_message "添加用户 zhangsan 店长 正义路" "hq_admin_001"

测试 2：自动激活

python3 auto_activate.py check_and_activate "zhangsan" "张三"

测试 3：权限检查

python3 handler.py check_permission "store_clerk_001"
应返回：无权限

---

📊 用户状态流转

添加用户 → 待激活_xxx → (首次登录) → 真实姓名 → (后续登录) → 更新 last_login

| 状态 | username 前缀 | 操作 | |------|--------------|------| | 待激活 | 待激活_ | 激活并更新用户名 | | 已激活 | 其他 | 仅更新 last_login |

---

🎯 典型场景

场景 1：新店开业添加店长

管理员：添加用户 zhangsan 店长 正义路
→ 发送确认卡片
→ 管理员确认
→ 用户创建成功
zhangsan 首次登录：
→ 自动激活
→ 发送欢迎消息
→ 开始使用

场景 2：批量添加店员

管理员：添加用户 liming 店员 正义路
管理员：添加用户 wangwu 店员 正义路
管理员：添加用户 zhaoliu 店员 正义路
liming 首次登录：
→ 自动激活
→ "欢迎使用，liming！"

场景 3：添加省份经理

管理员：添加用户 sunqi 省份经理 云南
→ 发送确认卡片（不需要门店）
→ 管理员确认
→ 用户创建成功（可访问云南省所有门店）
sunqi 首次登录：
→ 自动激活
→ "欢迎使用，sunqi！您管理云南省所有门店"

---

🔍 故障排查

问题 1：用户未自动激活

症状：用户发送消息后，username 仍然是"待激活_xxx"

解决：

# 手动激活
python3 auto_activate.py check_and_activate "userid" "姓名"
检查配置文件
cat config/users.json | grep "userid"

问题 2：权限不足

症状：店长尝试添加用户时收到"权限不足"提示

解决：

只有总部/区域/省份经理可以添加用户

联系总部管理员添加

问题 3：配置文件不同步

症状：插件目录已激活，工作区仍是待激活

解决：

# 同步配置文件
cp plugin/config/users.json workspace/config/users.json

---

📝 最佳实践

1. 自动激活流程

// 企业微信插件消息处理
async function onMessage(message) {
    const { from_userid, from_name } = message;
    
    // 1. 自动激活
    const result = await activateUser(from_userid, from_name);
    
    // 2. 如果是首次激活，发送欢迎消息
    if (result.activated) {
        await sendWelcomeMessage(from_userid, result.message);
    }
    
    // 3. 继续处理其他消息
    await handleMessage(message);
}

2. 配置文件管理

# 启动时同步
cp workspace/config/users.json plugin/config/users.json
关闭时同步
cp plugin/config/users.json workspace/config/users.json

3. 日志记录

# 记录用户操作
logging.info(f"添加用户：{userid}, 角色：{role}")
logging.info(f"激活用户：{userid}, 姓名：{name}")

---

🎊 总结

wecom-user-manager 是一个完整的用户管理 Skill，包含：

1. ✅ 添加用户 - 支持自然语言命令 2. ✅ 自动激活 - 首次登录自动完成 3. ✅ 权限管理 - 严格的权限控制 4. ✅ 欢迎消息 - 个性化的用户体验

---

最后更新: 2026-03-28 版本: v1.0 (合并版) 状态: ✅ 已部署