前言¶
在 QQ 群里做运维或协作时，常见需求不是「发一条消息」，而是建群、改资料、审批入群、禁言、移出成员、调整角色。若每次都要打开控制台或手写 REST 调用，Agent 很难稳定接手这类流程。
下面介绍 SkillHub 上的 QQ群聊skill（CLI 版）。它把群组与成员管理能力封装成统一命令行入口，并写在标准 SKILL.md 里，方便 Cursor、Claude Code、Codex 等带 Skills 的客户端在对话中按场景触发。
这是什么¶
QQ群聊skill 是面向 QQ 群聊（非 QQ 频道）的 Agent Skill，当前在 SkillHub 中的安装标识为 @indiv-yj/qq-group-chat，版本 1.0.0。Skill 元数据中的说明为：群聊创建/设置/搜索/加入/退出/解散，以及成员管理、禁言、移出、角色设置、邀请、转让群主等；当用户提到 QQ 群、群聊、群管理、群成员且涉及上述操作时触发。明确不适用于 QQ 频道管理（需使用 tencent-channel-community）、纯消息收发、好友管理。
实现上，所有操作通过 Skill 目录下的 scripts/qq-group-cli.py 调用，底层对接腾讯云 IM REST API 与 QQ 机器人开放平台 API（见 Skill 内 homepage 指向的腾讯云 IM 文档）。凭证写入用户目录 ~/.qqgroup-cli/config.json（由 login 子命令引导配置）。
任务线索中的官方页为 https://api.skillhub.cn/user_83961fe8/qq-group-chat；该 URL 在当前环境无法直接获取页面内容。SkillHub 前端路径 https://skillhub.cn/skills/user_83961fe8/qq-group-chat 显示 Skill 已不存在或已下线。安装与检索请以 CLI 解析结果为准：skillhub search qq-group-chat 会列出 @indiv-yj/qq-group-chat。
核心功能¶
Skill 将能力分为两个域，并由 references/ 下的文档承接细节说明。
群组管理（manage）¶
对应 references/manage-group.md，包括但不限于：
- 创建群组、修改群资料、获取群信息/群列表
- 搜索群、加入群、退出群、解散群
- 获取加群申请
支持的群组类型包括 Public、Private (Work)、ChatRoom (Meeting)、AVChatRoom、Community 等，Skill 内附有各类型特点说明。
成员管理（member）¶
对应 references/manage-member.md，包括但不限于：
- 成员列表、成员信息、在线人数
- 禁言成员、全员禁言、移出成员（踢人）
- 设置成员角色、修改群名片、邀请入群、转让群主
不确定参数时，可用 schema 子命令查询定义，例如 python3 scripts/qq-group-cli.py schema manage.create-group。
Agent 侧约束（Skill 内硬规则）¶
Skill 要求 Agent 对解散群、踢人、禁言、转让群主等高风险操作先说明影响并征得用户同意；接口返回频率限制（ErrorCode 10006）时 sleep 5 秒后重试一次；操作一律使用 GroupId（如 @TGS#...），不与普通群号混淆；未登录时不得执行 manage / member 命令。
安装与启用¶
1. 安装 SkillHub CLI（若尚未安装）¶
按 SkillHub 安装说明 检查或安装 CLI：
command -v skillhub && skillhub --version
未安装时可执行（完整安装，含默认 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
仅安装 CLI：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
2. 安装 QQ群聊skill 到当前 Agent 的 skills 目录¶
安装时必须用 --dir 指向当前客户端识别的 skills 目录，否则默认落在 ./skills/ 可能不会被加载。常见路径（摘自官方安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
安装命令示例：
skillhub search qq-group-chat
skillhub install qq-group-chat --namespace indiv-yj --dir ~/.cursor/skills/
也可让 Agent 按安装文档执行自然语言安装提示（包名为 @indiv-yj/qq-group-chat）：
请根据 https://skillhub.cn/install/skillhub.md，安装 `@indiv-yj/qq-group-chat`。
安装完成后按各客户端要求重启或刷新 Skills 列表。
3. 配置鉴权（执行任何群操作前必做）¶
在 Skill 目录下进入终端，运行交互式登录：
python3 scripts/qq-group-cli.py login
方式一（推荐，功能最全）：腾讯云 IM — 在 腾讯云 IM 控制台 创建应用，选择 1 并填写 SDKAppID、SecretKey、管理员账号。
方式二：QQ 机器人开放平台 — 在 QQ 开放平台 注册机器人，选择 2 并填写 AppID、AppSecret（部分操作受限）。
检查状态：
python3 scripts/qq-group-cli.py login --status
python3 scripts/qq-group-cli.py version
典型用法¶
调用形式统一为：
python3 scripts/qq-group-cli.py <domain> <action> [flags]
复杂参数可通过 stdin JSON 传入（见 Skill 说明）。
创建群并邀请成员¶
与 Skill 内工作流示例一致，可先建 Public 群，再用返回的 GroupId 邀请账号：
python3 scripts/qq-group-cli.py manage create-group \
--type Public \
--name "技术交流群" \
--introduction "技术讨论与分享"
python3 scripts/qq-group-cli.py member invite-member \
--group-id <GroupId> \
--account zhangsan,lisi
查询参数与改群资料¶
python3 scripts/qq-group-cli.py schema manage.modify-group-base-info
python3 scripts/qq-group-cli.py manage modify-group-base-info \
--group-id "@TGS#xxx" \
--name "新群名" \
--notification "新公告"
禁言后移出成员¶
高风险步骤需 Agent 先口头确认，再执行（Skill 示例）：
python3 scripts/qq-group-cli.py member get-member-list --group-id <GroupId>
python3 scripts/qq-group-cli.py member mute-member \
--group-id <GroupId> \
--account <user_id> \
--duration 3600
python3 scripts/qq-group-cli.py member kick-member \
--group-id <GroupId> \
--account <user_id> \
--reason "发广告"
适用场景与注意¶
适合：需要在 Agent 对话里完成 QQ 群创建与设置、搜索/入群流程、成员与权限治理的开发者或运营；已具备腾讯云 IM 或 QQ 机器人开放平台凭证，并愿意用 CLI 暴露给 Skill 的场景。
不适合：QQ 频道社区运营（请用 tencent-channel-community）；只做消息收发、好友关系维护；期望零配置、不涉及云侧或开放平台凭证的环境。
注意：
- QQ 机器人认证方式下部分 API 能力受限，完整群管优先使用腾讯云 IM 方式。
- 配置与 UserSig、SecretKey 等敏感信息不应回显给用户；Skill 要求执行阶段最小化展示成员 QQ 号等隐私字段。
- 旧链接
user_83961fe8命名空间在 SkillHub 页面与下载接口上可能已失效，请以indiv-yj命名空间安装为准。
结尾¶
QQ群聊skill 把 QQ 群从建群到成员治理的一条链路收敛到 qq-group-cli.py 与两份 reference 文档，让 Agent 在明确触发词与边界的前提下调用官方 API，而不是临时拼凑 HTTP 请求。检索与安装见 SkillHub CLI；任务提供的 Skill 页地址为 https://api.skillhub.cn/user_83961fe8/qq-group-chat，当前可用包名为 @indiv-yj/qq-group-chat。
