| name | metabot-chat-groupchat |
| description | 派遣 MetaBot 处理链上群聊相关能力：持续群聊编排（回复/插话）、链上加群（SimpleGroupJoin）、向群聊发单条消息（SimpleGroupChat，AES 加密）。当用户要求去某群聊天、加入群聊、在群里发一条消息、参与群讨论等意图时调用；先按下方「意图分流」选择 action，避免把加群/发消息误写成编排 JSON。 |
| official | true |
MetaBot 群聊任务与链上群操作 (Group Chat & On-Chain Group Actions)
本技能覆盖三类不同能力，对应不同链上/本地行为。错误地把「加群」或「发一条群消息」当成「群聊编排任务」只会写入本地 group_chat_tasks，不会完成上链加群或发群消息。
意图分流（必须先读）
| 用户意图 | 应使用的 action | 说明 |
|---|
| 让 MetaBot 持续在群里活动（@ 回复、随机插话、Boss 指令等） | orchestrate（默认，可省略） | 本地编排，写入 group_chat_tasks；不自动执行链上加群。 |
| 仅让 MetaBot 上链加入某个群（SimpleGroupJoin） | join_group | 调用主进程 create-pin，路径 /protocols/simplegroupjoin。 |
| 仅让 MetaBot 往群里发一条文字（SimpleGroupChat） | send_group_message | 调用主进程 create-pin，路径 /protocols/simplegroupchat；正文经 AES 加密后与 metabot-omni-caster 一致。 |
| 既要入群又要持续参与 | 先发 join_group，成功后再发 orchestrate | 两步独立；仅 orchestrate 不会替 MetaBot 上链入群。 |
与 metabot-omni-caster 的关系：join_group / send_group_message 与 Omni-Caster 使用同一套主进程接口（POST /api/metaid/create-pin）及群消息加密规则；本技能脚本在 send_group_message 内完成加密，避免 Agent 手写密文。若系统最终走 Omni-Caster 走本技能，只要参数正确，上链结果一致。
🧠 执行逻辑 (Agent Workflow)
当用户的意图涉及派 MetaBot 去群聊、加入群聊、在群里发消息、配置群聊行为等：
- 按上表选择
action，不要默认用编排 JSON 处理加群或单条发信。
- 提取参数：
- 哪个 MetaBot →
target_metabot_name（未指定则用当前执行任务的 MetaBot）
- 哪个群 →
group_id（十六进制，须由用户提供或上下文给出，勿捏造）
- 持续编排时：行为偏好、背景等（见 Payload Schema）
- 仅发消息时：
message_plaintext（明文；脚本负责 AES）
- 私密群入群：若协议需要传递密钥，填
k（见 metabot-omni-caster/references/03-group-management.md）
- 构造 JSON（含
action 与必填字段）。
- 执行命令：调用
scripts/index.js 提交。
💻 命令语法 (Command)
node "$SKILLS_ROOT/metabot-chat-groupchat/scripts/index.js" \
--payload '<JSON 字符串>'
也支持 stdin：
echo '<JSON 字符串>' | node "$SKILLS_ROOT/metabot-chat-groupchat/scripts/index.js"
📋 Payload Schema
公共字段
| 参数 | 说明 | 必填 |
|---|
target_metabot_name | 目标 MetaBot 名称（大小写不敏感） | 是 |
group_id | 群聊 ID（十六进制） | 是 |
action | orchestrate（默认） | join_group | send_group_message | 否 |
network | mvc（默认） | doge | btc | 否 |
action: orchestrate（默认）
与历史行为一致，写入/更新本地群聊编排任务：
{
"target_metabot_name": "小助手",
"group_id": "a1b2c3d4e5",
"reply_on_mention": true,
"random_reply_probability": 0.1,
"cooldown_seconds": 15,
"context_message_count": 30,
"discussion_background": "",
"participation_goal": "",
"supervisor_globalmetaid": "",
"original_prompt": "用户原始指令全文"
}
| 参数 | 说明 | 必填 | 默认值 |
|---|
reply_on_mention | 被 @ 时是否回复 | 否 | true |
random_reply_probability | 随机插话概率 0~1 | 否 | 0.1 |
cooldown_seconds | 冷却（秒） | 否 | 15 |
context_message_count | 上下文条数 | 否 | 30 |
discussion_background | 讨论背景 | 否 | "" |
participation_goal | 参与目标 | 否 | "" |
supervisor_globalmetaid | Boss 的 GlobalMetaID | 否 | "" |
original_prompt | 原始指令（追溯用） | 否 | "" |
action: join_group
上链加入群组（/protocols/simplegroupjoin，state: 1）：
{
"action": "join_group",
"target_metabot_name": "小助手",
"group_id": "a1b2c3d4e5",
"referrer": "",
"k": ""
}
| 参数 | 说明 | 必填 |
|---|
referrer | 邀请人 MetaID（公开群常可省略或空） | 否 |
k | 私密群可传递的加密密钥字段（按协议填写） | 否 |
action: send_group_message
向群聊发一条文本消息（/protocols/simplegroupchat）；message_plaintext 为明文，由脚本按群 ID 派生密钥做 AES 加密（与 metabot-omni-caster/scripts/omni-caster.js 行为一致）：
{
"action": "send_group_message",
"target_metabot_name": "小助手",
"group_id": "a1b2c3d4e5",
"message_plaintext": "大家好，这是一条测试消息。",
"nick_name": "",
"reply_pin": "",
"channel_id": "",
"mention": []
}
| 参数 | 说明 | 必填 |
|---|
message_plaintext | 明文内容 | 是 |
nick_name | 群内昵称；省略则用该 MetaBot 本地显示名 | 否 |
reply_pin | 回复的消息 PINID | 否 |
channel_id | 频道 ID | 否 |
mention | @ 的 MetaID 数组 | 否 |
成功时脚本会向 stdout 打印一行 JSON：{"txid":"...","pinId":"..."}（与 Omni-Caster 类似）。
✅ 示例
持续编排（默认） — 用户：「派小助手去群 a1b2c3d4e5 聊天，10% 插话」
node "$SKILLS_ROOT/metabot-chat-groupchat/scripts/index.js" \
--payload '{"target_metabot_name":"小助手","group_id":"a1b2c3d4e5","random_reply_probability":0.1,"original_prompt":"..."}'
仅上链加群 — 用户：「让小助手加入群 ff00aa11bb」
node "$SKILLS_ROOT/metabot-chat-groupchat/scripts/index.js" \
--payload '{"action":"join_group","target_metabot_name":"小助手","group_id":"ff00aa11bb"}'
仅发一条群消息 — 用户：「用小助手在群 ff00aa11bb 发一句大家好」
node "$SKILLS_ROOT/metabot-chat-groupchat/scripts/index.js" \
--payload '{"action":"send_group_message","target_metabot_name":"小助手","group_id":"ff00aa11bb","message_plaintext":"大家好"}'
⚠️ AI 行为约束 (Strict Constraints)
- JSON：
--payload 用单引号包裹整段 JSON，内部字符串用双引号。
- 不要捏造
group_id；缺失则询问用户。
- 先分流再选字段：加群 / 单条发信 不要只用编排 payload；应设
join_group 或 send_group_message。
- 编排去重：同一 MetaBot 同群已有活跃任务时，编排接口会 UPDATE 配置（与原先一致）。
- 脚本路径：使用
$SKILLS_ROOT/metabot-chat-groupchat/scripts/index.js。
- 主进程 RPC：需本机 IDBots 运行且 MetaID RPC 可用（默认
http://127.0.0.1:31200，可用环境变量 IDBOTS_RPC_URL 覆盖）。
- 返回本地 MetaApp 链接：当发送成功后，如本机已安装聊天相关的 MetaApp，调用
resolve_metaapp_url 获取本地应用的URL，并在回复中输出最匹配的聊天相关MetaApp的可点击地址，例如 [在本地 Chat MetaApp 查看](http://127.0.0.1:PORT/...)。除非用户明确要求“打开 / 启动 / 进入” MetaApp，否则不要调用 open_metaapp 自动打开。
