[Feature]Discord适配器需要完善

[NLKASHEI]

Description / 描述

目前，Discord适配器尚不支持中文指令注册为斜杠指令，也不支持后续附加参数的添加，先前我试着完善了一下，但效果不佳，尚且需要各位大佬们共同携手完善，已提交但未审核的PR：#9125

Use Case / 使用场景

Discord命令注册相关

Willing to Submit PR? / 是否愿意提交PR？

• Yes, I am willing to submit a PR. / 是的，我愿意提交 PR。

Code of Conduct

• I have read and agree to abide by the project's Code of Conduct. /

[NLKASHEI]

另外值得一提的是，DISCORD的BOT回应也应该可以是VUE形式，而目前astrbot的DISCORD适配器尚不支持此类型的插件

[NLKASHEI]

---

1. 概述

修复版在保留原版 AstrBot + Pycord Discord 适配器整体架构的前提下，重点处理了：

1. 稳定性：未初始化访问、异常打挂事件循环、冷启动取 channel 失败等
2. 正确性：session 副作用、channel id 污染、音频链路、mention 剥离范围
3. 斜杠指令：参数 Option 化、重复注册、名称规范（含中文）、同步范围与配额
4. 可运维性：更明确的日志、单项失败隔离、关闭流程更干净

中文斜杠命令名：Discord CHAT_INPUT 允许 Unicode 字母/数字（含中文），修复版允许注册（须 1–32 位且 name == name.lower()）。原版正则未加 re.ASCII 时中文也能通过本地校验；修复版明确按 Unicode 规则校验并写清日志，避免误以为「Discord 不支持中文命令名」。

---

2. 初始化与生命周期

项目	原版	修复版
self.client	仅在 run() 内赋值，run 前访问易 AttributeError	__init__ 中 self.client = None，统一 _client_ready()
guild_id	配置原样使用（常为 str）	_normalize_guild_id → int | None，非法值打日志并置空
bot_self_id	主要依赖首条消息的 bot_id	_ensure_bot_self_id()：ready / 收消息 / 发送 / 处理 / slash 多处补齐
收消息异常	未统一捕获，可能影响上层回调	on_received 整体 try/except，单条失败不拖垮适配器
polling 任务	创建 task 后无 done 回调	add_done_callback，崩溃时打错误日志
token / proxy	直接 get	token strip，空串视为未配置；proxy 空串变 None
terminate	有清理逻辑，但 client 可能不存在	全程 client is not None 判断；cancel 后超时/取消分支更清晰；task 置 None

相关辅助方法（修复版新增）

• _client_ready()：client 与 client.user 均可用
• _ensure_bot_self_id()：从 client.user.id 回填
• _normalize_guild_id()：配置项安全转 int

---

3. 会话发送 send_by_session

项目	原版	修复版
改写 session.session_id	原地 split("_")[1]，污染调用方对象	仅本地变量解析，不修改传入 session
多段 _	split("_")[1] 只取第二段，易截错	rsplit("_", 1)[-1] 取最后一段
取 channel	仅 get_channel（缓存）	先缓存，失败再 fetch_channel（_resolve_channel）
事件构造	create_event	同样走 create_event（修复过程中曾内联过，最终恢复统一入口）
发送失败	异常直接上浮	打带 channel 的错误日志后再抛出

---

4. 消息转换与媒体

4.1 文本与 Mention

项目	原版	修复版
User mention 剥离	仅开头 bot 的 <@id> / <@!id>	同样只剥 本 bot；支持循环剥连续 bot mention
Role mention 剥离	bot 角色且开头匹配则剥一个	循环：可连续剥 bot user + bot role
误剥其它人 @	原版已尽量避免	保持「只剥 bot」，不用宽正则剥任意 mention
get_member	mention 检测侧有 try	剥离侧也加 try/except，避免偶发异常

4.2 附件与音频

项目	原版	修复版
content_type is None	需同时判断 truthy 再 startswith	ct = (content_type or "").lower()，更稳
空 url 附件	仍可能入链	无 url 直接跳过
Record	file + url	同样 file + url
音频落地	convert_message 内 MediaResolver 转 wav	保留；失败 try/except 打日志，保留原 URL
作者字段	display_name	display_name → name → "" 兜底

说明：中间某一版修复稿曾误删音频解析，当前修复版已与原版对齐并加强异常保护。

4.3 session / group id

项目	原版	修复版
_get_channel_id	str(getattr(..., None)) 可能得到 "None"	无 id 返回 ""
abm.session_id	str(message.channel.id)	安全取 id，无则 ""

---

5. 事件处理 handle_msg / create_event

项目	原版	修复版
create_event	有独立方法	保留，send_by_session 与 handle_msg 共用
客户端未就绪	检查 client.user	_client_ready()，并补 message.self_id
斜杠优先	interaction_followup_webhook 则 wake	相同
User / Role 提及唤醒	有	相同逻辑 + mentions 空列表与异常防护
非 discord.Message	忽略并 warning	相同

---

6. 斜杠指令注册与回调

这是修复版与原版差异最大的一块。

6.1 命令收集

项目	原版	修复版
插件是否激活	star_map[path].activated，缺 key 可能 KeyError	star_map.get(...)，无插件跳过
重复命令名	可重复 add_application_command	seen_names 去重并 warning
单条注册失败	可能中断整批	单命令 try/except，失败 continue
参数 Option	固定 一个可选 params: str	从 handler 签名 生成多个 Option；无参数时回退 原版式 params
Option 数量	恒为 1	最多 25，超出截断
Option 顺序	不适用	required 在前，符合 Discord 要求
*args / **kwargs	不涉及	建 Option 时跳过 VAR_POSITIONAL / VAR_KEYWORD
非法 option 名	无	校验小写 + 字符集，跳过
类型注解	无	get_type_hints + Optional 解包；int/float/bool/string
同步范围	sync_commands()	配置了 guild_id 时 sync_commands(guild_ids=[...])，便于调试、减轻全局延迟/配额
日配额 30034	有专门处理	保留；其它异常也 warning

6.2 命令名规则（含中文）

项目	原版	修复版
正则	^[-_'\w]{1,32}$（无 ASCII flag）	^[-_\w]{1,32}$（Unicode \w，中文可过）
小写	cmd_name != cmd_name.lower() 则跳过	相同
日志	debug「Skipping invalid…」	warning，说明可用中文/字母/数字/_/-，须小写 1–32
描述	多用 handler_metadata.desc	优先 docstring 首行，再 desc，再默认；空串/超长兜底（≤100）

结论：中文斜杠命令名可以注册（例如 /帮助），前提是名称本身满足 Discord 长度与字符规则。大写英文、空格、.、超长等仍会被跳过。

子命令（有 parent_command_names）与 CommandGroupFilter 仍不注册为 slash，与原版一致。

6.3 动态回调

项目	原版	修复版
签名	(ctx, params: str | None = None)	按 option 名生成显式参数 + *args/**kwargs 兜底；生成失败回退纯 kwargs
defer	wait_for(ctx.defer(), 2.5)	先看 response.is_done()，再 defer
defer 失败	打日志 return	尽量 ephemeral 提示用户后 return
业务异常	无统一捕获	_handle 内 try/except，followup 提示「指令执行出错」
参数拼命令串	cmd_name + " " + params	按 param_names 顺序拼接；含空格/引号用双引号转义，减少简单 split 错位
bool	随 str	序列化为 true / false
channel 为空	有 guild_id 兜底	相同，且 channel_id is None 时用 ""

---

7. 其它小改动

• 去掉对 shlex 的依赖，改为自实现双引号转义（避免 Windows/locale 差异）
• 常量：_DISCORD_MAX_OPTIONS = 25、_DISCORD_DESC_MAX = 100
• register_handler、元数据 meta()、平台注册装饰器与原版语义一致
• MediaResolver 正常使用（非死 import）

---

8. 已知限制（架构层，非本次必改）

1. 斜杠多参 → 文本命令串
   仍拼成 命令名 参数1 参数2… 交给 AstrBot CommandFilter。若下游只按空格拆且不认引号，含空格参数仍可能错位。

2. 有明确签名时不再提供万能 params
   handler 已有 foo, bar 时只有这两个 Option；自由长文本需写在某个 string 参数里。无参 handler 仍回退 params。

3. 复杂 Discord 类型
   未映射 User / Channel / Role / Attachment 等 Option 类型，一律 string/int/float/bool。

4. 子命令 / 命令组
   仍不注册为 Discord 原生 slash 子结构。

5. IDE / Pylance
   工作区若未安装 discord / astrbot，会出现导入与 @override 告警，与运行时逻辑无关。

---

9. 建议验证清单

上线或替换前建议在真实 Discord 环境覆盖：

• 无 token / 错误 token 日志与退出行为
• 普通消息、@bot、@角色（bot 拥有角色）唤醒
• 图片 / 语音附件（音频是否转成可用路径）
• 会话主动 send_by_session（含冷启动后首次发送）
• 无参 slash、多参 slash、参数含空格
• 中文命令名注册与触发（如 /帮助）
• 重复命令名、非法命令名日志
• guild_id 调试同步 vs 全局同步
• 正常 terminate：清命令、断连、无挂死 task

---

10. 变更对照速查

类别	是否修复/增强
client 未初始化崩溃	✅
session.session_id 原地修改	✅
channel 缓存未命中	✅ fetch_channel
"None" 污染 group/session id	✅
音频 MediaResolver	✅ 保留并加固
star_map KeyError	✅
slash 多 Option + 无参 params 回退	✅
重复 slash 名	✅
required option 顺序 / 最多 25 个	✅
中文命令名	✅ 明确允许
guild_id 类型与同步范围	✅
defer / 执行异常用户提示	✅
收消息 / 单项注册异常隔离	✅
mention 只剥 bot、可连续剥	✅
子命令组注册为 slash	❌ 仍不支持（同原版）
User/Channel 等 Option 类型	❌ 未做

---

待审核！