7.3 KiB
group-admin：群创建、成员写入与管理
返回入口：DingTalk Chat Skill
用于建群、修改群资料、成员增删、邀请卡片分享、群主和管理员、禁言、公告、群设置、 入群审批、群身份、退出、解散和升级外部群。只读群发现、成员读取和邀请链接使用 group-discovery.md。
安全与目标
- 群目标统一使用当前 profile 下真实
openConversationId；支持自然群名的 Shortcut 由 CLI 唯一解析，多候选时停止。 - 解散群、踢人、转让群主、禁言、管理员和外部群升级都是高影响操作；以最终 Runtime gate 和精确 leaf Schema 为准确认对象、动作与影响。
- 所有自然成员和群主必须先完成唯一解析并按稳定 ID 去重，再开始任何写入；不得边解析边 产生部分副作用。
- 群公告会触达成员；
notice edit是整体替换，必须有完整新正文。
建群与基础资料
基础建群使用 `dws chat +chat-create`。已知成员 ID 传 `--users`，姓名/花名传 --member-query；群主默认当前用户，也可传 --owner-open-dingtalk-id 或
--owner-query。任一自然身份未唯一解析时，创建前整体停止。
dws chat +chat-create --name "项目冲刺群" --member-query "测试用户甲,测试用户乙" --format json
dws chat +chat-create --name "合作群" --member-query "测试用户甲" \
--owner-query "测试用户乙" --type EXTERNAL --format json
修改群名称优先使用接受群名或稳定 ID 的 +chat-update：
dws chat +chat-update --group <群名或openConversationId> --name "新群名" --format json
群头像和管理员级群开关使用 +chat-update-icon、+chat-update-settings；只有 Shortcut
尚未发布真实必需字段时才评估原子 group rename/update-icon/update-settings。
原子 chat group create 只用于 +chat-create 未发布的真实底层字段，并先读取精确 leaf
Schema。普通内部/外部群、话题群和显式群主已经由 +chat-create 覆盖，不回流到手工
aisearch → group create 链路。
成员与机器人写入
| 动作 | 入口与关键参数 |
|---|---|
| 添加成员 | group members add --id <cid> --users <userIds> |
| 移除成员 | group members remove --id <cid> --users <userIds> |
| 添加已知机器人 | +chat-add-bot 或精确原子 group members add-bot |
| 查看群内机器人 | +chat-bots --group <群名或cid> |
| 移除群内机器人 | +chat-remove-bot 或精确原子 group members remove-bot |
普通成员增删的 --users 只接受组织 userId，必须来自真实人员解析结果；不得把
+chat-members-list / +chat-members-get 返回的 openDingTalkId 直接传入。添加已知机器人
使用 robotCode；移除机器人使用当前群 +chat-bots 返回的真实 openBotId，两者不能互换。
缺少 openBotId 时在同一流程中先执行 +chat-bots，不必额外读取群发现 reference。只有需要
搜索未知机器人、区分 bot search / bot find、机器人发送或撤回、Webhook 时，才读取
chat-bot.md。
邀请卡片、群主、管理员与禁言
邀请链接只读走 +chat-invite-url。实际分享邀请卡片使用 group share-invite：--source
是被分享群，接收端在 --target 会话和 --receiver 单聊用户之间二选一。
dws chat group share-invite --source <sourceCid> --target <targetCid> --format json
dws chat group share-invite --source <sourceCid> --receiver <openDingTalkId> --format json
| 动作 | 入口与关键参数 |
|---|---|
| 转让群主 | +chat-transfer-owner --group <cid> --new-owner <稳定ID> |
| 设置/取消管理员 | group set-admin --group <cid> --users <ids> [--off] |
| 全员禁言/解除 | group-mute --group <cid> [--off] |
| 成员禁言/解除 | +chat-mute-member 或 group-mute-member |
| 查询禁言配置 | group get-mute-config --group <cid> |
原子 group-mute-member --mute-time 单位为毫秒。不要用展示名称代替稳定用户 ID，也不要
在未确认影响时执行转让、踢人或禁言。
群设置与当前用户偏好
管理员级群开关使用 +chat-update-settings 或原子 group update-settings。常见 settingKey
包括 authority、joinValidation、onlyAdminCanAtAll、searchable、
addFriendForbidden、onlyAdminCanDING、onlyAdminCanPinMsg 和
onlyAdminCanSendFile、groupEmailDisabled、groupLiveAuthority、
groupBillAuthority；只修改用户明确要求的字段。
新成员历史消息可见范围使用 group set-history --group <cid> --option <值>；option 只取
精确 leaf Schema 发布值，不按自然语言猜枚举。
当前登录用户自己的置顶、免打扰、群昵称和群备注使用 group user-settings query/set，
不是管理员群开关。单个群昵称/备注优先 group update-nick/update-alias。
dws chat group user-settings query --groups <cid1>,<cid2> --format json
dws chat group user-settings set \
--items '[{"openConversationId":"cid1","top":true,"mute":false}]' --format json
批量设置只传本次要改的字段；空字符串清除昵称或备注，不补用户未要求的值。
群公告
| 动作 | 原子入口 |
|---|---|
| 发布公告 | group notice create --group <cid> --content <完整Markdown> |
| 修改公告 | group notice edit --group <cid> --notice-id <id> --content <完整Markdown> |
| 查询公告 | group notice get/list |
定时公告 --run-at 使用带时区时间；notice list --scheduled 查询待发布公告。分页时沿真实
nextPageCursor 继续。修改前必须取得完整替换正文，不把增量片段当整篇公告。
入群审批与群身份
先用 group list-join-validations 取得真实 record-id/applicant/inviter，再执行
group audit-join-validation 或 +chat-audit-join。审批状态只使用精确 leaf Schema 发布值。
群身份使用 group-role / +chat-role-*：
list/add/update/remove管理身份定义；set-user/remove-user/query-user管理成员身份；openRoleId必须来自真实身份列表。
覆盖或清除成员身份前确认用户、群和完整角色集合，不能用展示名称猜 openRoleId。
退出、解散与外部群升级
- 当前用户退出群：
+chat-quit或精确原子group quit。 - 解散群：
group dismiss，不可逆。 - 普通群升级外部群：
group upgrade-to-external，不可逆。
这些动作必须以最终 Runtime gate 为准，不把示例中的确认参数当固定事实。
完成与错误
- 创建或更新后保留真实
openConversationId和任务结果；只对查询结果真实返回的字段执行读回验证。 - 写接口成功但现有查询未返回目标设置时，报告真实写入回执和不可独立读回的边界；不用群名、 成员数等其他字段代替验证，也不猜未发布的读回命令。
- 任一自然目标零命中或多候选时，在写入前整体停止。
- 逐项写入保留 succeeded/failed/unknown ledger，不用重试抹掉失败项。
- 分享邀请时
--target与--receiver只能二选一；接收对象不明确时先确认。 - 机器人进群失败时确认机器人身份和当前用户管理权限，不连续切换同义原子命令。