[Plugin] astrbot_plugin_dnd_dice

[Dracowyn]

插件信息

{
  "name": "astrbot_plugin_dnd_dice",
  "display_name": "D&D 骰子 Dice",
  "desc": "支持 D&D （Roll20规范）骰池语法的骰子插件，包括优势/劣势、保留最高/最低、爆炸骰、多骰组合等以及 LLM 函数工具调用。",
  "author": "Dracowyn",
  "repo": "https://github.com/Dracowyn/astrbot_plugin_dnd_dice",
  "tags": [
    "骰子",
    "跑团",
    "DnD"
  ],
  "social_link": "https://github.com/Dracowyn"
}

插件检查清单

• 我的插件经过完整的测试
• 我的插件不包含恶意代码
• 我已阅读并同意遵守该项目的 行为准则。

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_dnd_dice

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

• 代码质量与编码规范：

  • 异常捕获范围过宽：在 _do_roll 方法中，使用了 except Exception as e: 捕获了格式化结果阶段的所有未知异常。这是一种反模式，可能会掩盖诸如 KeyError 或 TypeError 等实际逻辑缺陷，建议明确捕获目标异常。
  • 前缀缓存策略实现细节：在 _set_prefix_cache 的 LRU 淘汰策略中，虽使用了 OrderedDict.popitem(last=False)，但由于缓存是按事件驱动触发的，缺少定期清理过期缓存（TTL）的守护协程，极端情况下如果长期无新访客，旧的缓存对象会一直占据内存直到触发 MAX 限定。

• 潜在缺陷或问题：

  • LLM 提示词冗余：roll_dice_tool 的 docstring 非常长。由于这个注释会被直接解析并注入到 LLM 的上下文中，长达数十行的规则不仅占用大量 Token（对于每次对话请求都是固定开销），且容易导致轻量级 LLM 注意力漂移。建议只保留核心掷骰用法，将特殊扩展交给用户交互学习。

---

character.py

• 安全漏洞与最佳实践 (框架适应性检查)：

  • 数据持久化规范预警：代码注释中提到“未来版本... 从 D&D Beyond / Roll20 JSON 格式导入”。请严格注意，根据 AstrBot 框架规范：未来开发涉及到任何配置或数据的本地文件保存时，严禁使用硬编码路径，必须通过 from astrbot.api.star import StarTools 并调用 StarTools.get_data_dir() 返回的 Path 对象进行文件读写。

• 代码质量与编码规范：

  • Dataclass 使用反模式：在 AbilityScores.__post_init__ 中，通过字符串名称元组循环 getattr 和 setattr 来规范化属性值。这破坏了 Dataclass 的类型推导，增加了运行时的开销。建议采用显式赋值或使用 field(default=10) 配合只读 Property 进行范围约束。
  • 缺少异步并发锁：作为内存缓存的 _BoundedLRUCache 虽暂未接入外部持久化，但在异步环境中（如未来执行并发 await manager.save），目前的非原子操作极易引发竞态条件，建议及早引入 asyncio.Lock。

---

dice_parser.py

• 功能实现与逻辑正确性：

  • 非 ASCII 标签截断缺陷：_strip_label 中使用 unicodedata.category(ch).startswith("L")（匹配字母）来查找标签边界。如果用户使用 Emoji 或特殊符号作为标签（例如：/r 1d20 🗡️ 或 /r 1d8+2 💥），解析器将无法识别，将其误当做算式的一部分，最终引发解析错误。

• 代码质量与编码规范：

  • 魔法数字硬编码：parse 方法中直接硬编码了 _MAX_INPUT_LEN = 200。此值应该提升为模块级常量或允许通过插件配置动态修改，以便于系统管理员控制。

---

dice_roller.py

• 可维护性与可读性：

  • 代码高度冗余：RollResult.is_natural_20 和 RollResult.is_natural_1 属性中的条件判断代码（包含结构形态验证、优势劣势规则提取等）近乎完全重复（高达15行），极大地降低了可维护性，应当抽取为一个私有的 _check_natural(target_value: int) 函数。

• 潜在缺陷或问题：

  • 无谓的递归/循环开销：在 _apply_rerolls 中，若遭遇如 d1r<2 （面数为1，且条件永远满足）的极端恶意或错误表达式，引擎依然会硬跑满 reroll_max_depth（默认20次）。虽然有最大深度熔断，但建议在解析层或执行层前置识别永远为 True 的重骰逻辑并进行短路拦截。

---

formatter.py

• 代码质量与编码规范：
  • 庞大的遗留死代码：在 _format_dice_list 函数中，为了兼容不存在 gr.die_rolls 的情况，保留了超过 40 行的“基于频率计数的旧路径”代码。由于 dice_roller.py 在重构后已经保证必定会精确生成和标注 die_rolls，这部分巨大的 Fallback 分支如今实质上是死代码，徒增了巨大的圈复杂度，应予以删除。
  • 字符串重复拼接：在判断成功/失败的符号追加时（如 * 或 x），多处逻辑存在深度复制。可以考虑采用映射字典或专门的单个格式化提取器来降低视觉噪音。

---

代码评审团

Linus Torvalds：（皱着眉头，盯着 formatter.py 和 dice_roller.py）

“我简直无法理解，为什么你在 formatter.py 里留了半吨重的向后兼容代码？如果引擎层已经 100% 输出了准确的掷骰历史，那堆用字典计数去猜测骰子来源的垃圾逻辑就该立刻被送进垃圾焚烧炉！代码不是用来堆砌博物馆藏品的。还有，那个自然 1 和自然 20 的重复代码，你是在复印机前写代码的吗？把它抽成一个公共函数，少让阅读者受罪。”

乔布斯 (Steve Jobs)：（摸着下巴，指着 main.py 和 dice_parser.py）

“重点是体验！我们来看这个 roll_dice_tool。你把它塞进 LLM 的上下文里，居然写了一篇短篇小说？你知道模型每次看到这几十行提示词要浪费多少精力吗？把它精简到极致！另外，如果玩家兴奋地用一个酷炫的剑 Emoji 🗡️ 作为攻击标签，你的正则和 Unicode 魔法居然会报错？这不是魔法，这是灾难。用户不会关心你用的是不是 'Letter' 类别，他们只想要骰子滚动并显示他们的魔法表情。把它修好。”

GLaDOS：（冷漠的机械音，审视着 dice_roller.py 的边界条件）

“我对你的测试数据深感悲哀。想象一个无聊的测试对象输入了 1d1r<2。你的引擎并没有识破这愚蠢的逻辑，而是顺从地掷了一次又一次永远为 1 的骰子，直到撞上 20 次深度的熔断墙才放弃。这就像看着一个机器人把头撞在墙上 20 次才意识到前面没路。真是计算资源的耻辱性浪费。虽然代码没崩溃，但我给你的运行效率打 0 分。建议增加智商检测逻辑。”

Disclaimer: 以上评审内容由 AI 自动生成，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 5 个 Python 文件
• 已选择审核文件: 5 / 5
  已发送至 AI 审核的文件清单

main.py
character.py
dice_parser.py
dice_roller.py
formatter.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。

[Dracowyn]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_dnd_dice

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

（未发现需报告的问题）

character.py

1. CharacterSheet.__post_init__ 对可选集合字段缺少健壮性处理
   self.skill_proficiencies = {s.lower() for s in self.skill_proficiencies} 和 save_proficiencies 假设输入一定可迭代。若外部传入 None（在插件生态里很常见），会直接触发 TypeError，导致角色卡初始化失败。
   建议：在归一化前做 None 兜底或类型检查。

---

dice_parser.py

1. 标签切分规则可能误伤合法表达式（Unicode 符号场景）
   _strip_label 在遇到非 ASCII 且 unicodedata.category 以 S 开头的字符时会直接切分为标签。
   这会让含 Unicode 符号的表达式（或用户粘贴的特殊运算符）被提前截断，造成“解析错误但用户不易理解原因”的问题。
   建议：把 S 类从自动切分触发条件中收紧，或仅在明确上下文（如空白后）才判定为标签起点。

---

dice_roller.py

1. 多重重骰条件未按“可重复修饰”完整生效
   _apply_rerolls 中命中第一个条件后立即 break，导致后续 r/ro 条件不会再应用到该骰子。
   例如表达式含多个重骰条件时，当前实现实际上只会执行首个命中的条件，与“可重复重骰修饰”的语义不一致。
   建议：按条件链顺序继续处理（至少可配置为“继续匹配后续条件”），避免语义降级。

2. 达到 reroll_max_depth 后静默保留“仍命中条件”的值
   非 once 重骰在深度耗尽后会直接保留当前值，没有错误提示或状态标记。
   这会在极端条件下产生“看起来重骰成功，实际仍落在应重骰区间”的结果，影响可解释性。
   建议：深度耗尽时增加显式标记或抛出可读异常（可由上层转成用户提示）。

---

formatter.py

（未发现需报告的问题）

---

代码评审团

人物一：Linus Torvalds（直给型）
“_apply_rerolls 里命中就 break 这事，属于‘代码能跑但语义半残’。你都支持多重 reroll 语法了，就别只执行第一条。要么删语法，要么把执行模型补齐，别让接口和行为打架。”

人物二：Ada Lovelace（结构控）
“CharacterSheet 的集合归一化很优雅，但输入契约写得太乐观。数据模型层应对脏输入更宽容，否则上层一旦传 None，整个流程会在初始化阶段失败。边界条件是模型设计的一部分。”

人物三：Tony Stark（工程实战派）
“你这解析器很强，但 _strip_label 对 Unicode Symbol 直接切标签太‘激进防御’了。现实用户会复制奇怪字符，建议做更精确判定，不然线上就会出现‘我明明输入了骰式却说我错了’的客服地狱。”

Disclaimer: 以上评审内容由 AI 自动生成，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 5 个 Python 文件
• 已选择审核文件: 5 / 5
  已发送至 AI 审核的文件清单

main.py
character.py
dice_parser.py
dice_roller.py
formatter.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。

[Dracowyn]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_dnd_dice

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

• 并发与状态安全：_character_manager 属性使用了懒加载模式（if self._character_manager is None: ...）。虽然 Python 中的赋值操作受 GIL 保护，但在异步环境中（特别是如果未来 CharacterManager 的初始化需要涉及 await），这种模式可能会遇到竞态条件，建议留意未来的演进。
• 配置默认值处理：在 __init__ 中，self.default_cmd_prefix 的默认值获取逻辑 str(cfg.get("default_cmd_prefix") or "") 会将 None 或布尔值强制转换为字符串。如果配置文件意外将前缀配为 False，它会变成 "False" 字符串。建议采用更严格的类型过滤。

character.py

• 类型提示不够严谨：CharacterManager.__init__(self, star: object | None = None) 中的 star 参数被宽泛地标注为 object。建议使用 typing.TYPE_CHECKING 来导入 Star 类并进行正确的类型标注，以提升代码的可读性和静态检查能力：

  from typing import TYPE_CHECKING
  if TYPE_CHECKING:
      from astrbot.api.star import Star
  # ...
  def __init__(self, star: "Star | None" = None) -> None:

dice_parser.py

• 代码复杂度与维护性：_strip_label 函数中充斥了大量的 if/elif 以及内联的正则搜索，职责有些过载。全角字符转换、Unicode 类别判断以及正则拆分的混合逻辑容易在遇到罕见的特殊符号组合时产生非预期的截断。
• 隐式回退逻辑风险：在 _parse_dice_token 中，遇到无法解析的骰子修饰符时，抛出 DiceParseError 的前置条件是 pos == pos_after_base and pos < len(expr) and expr[pos].isalpha()。这意味着如果输入包含了非字母的非法字符（例如特殊符号），解析器可能会静默停止解析修饰符并把剩余部分留给后续逻辑，可能导致意料之外的错误提示。

dice_roller.py

• 配置参数硬编码：_roll_group 和 roll 函数中，reroll_max_depth = 20 均被硬编码作为默认参数。相对而言，exploding_depth 则是从上游配置一层层传递进来的。为了保持设计的一致性，reroll_max_depth 也应开放给插件层（如 main.py）进行统一配置。
• 潜在的性能消耗点：在 _apply_rerolls 中检查是否所有面都满足重骰条件：all(_compare(v, cond.compare, cond.value) for v in range(1, sides + 1))。当 sides 非常大（如 d1000）并且存在多条 reroll_conditions 时，会在循环中产生一定的开销。虽然最大面数受限，但每次掷骰都遍历一次仍不够优雅。

formatter.py

• 重复的业务逻辑（DRY 原则）：_cmp(value: int, op: str, threshold: int) 方法与 dice_roller.py 中的 _compare 函数逻辑完全一致（只是文档字符串略有不同）。仅仅为了避免导入私有函数而复制一份代码，违反了 DRY 原则。建议将通用的运算比较逻辑提取到一个公共的 utils.py 中。
• 冗余的代码结构：_annotate_die 中，对成功计数模式的判断逻辑存在冗余：

  if die.state == "exploded":
      if gr.is_success_mode ... # 处理成功与失败标记
      return f"{raw}!"
  if gr.is_success_mode and die.state in ("kept", "kept_capped"):
      if g.success_compare ... # 重复的成功与失败标记处理逻辑

  这部分完全可以抽离为一个独立的小函数或前置处理环节，以简化 _annotate_die 的分支树。

---

代码评审团

Linus Torvalds：（喝了一口咖啡，眉头紧锁）

“我真搞不懂你们这些人。在 formatter.py 里直接把 dice_roller.py 里的比较函数复制粘贴一遍，还美其名曰‘避免导入私有名称’？你要么把那个函数设为公开，要么丢进一个 common 模块里。复制粘贴那是猴子才干的事！还有 character.py 里的那个 object 类型标注，你这是在写 Python 还是在写 1995 年的 JavaScript？类型系统给你不是为了让你写个 object 敷衍了事的。不过，抛开这些不谈，核心的正则和状态机拆分得还算有脑子，至少没用一个长达三页的正则表达式来解析整个表达式，不然我肯定直接把合并请求拒掉。”

Sherlock Holmes：（拿着烟斗，仔细端详着代码的脉络）

“华生，你看这代码里隐藏着一个有趣的线索。这位开发者极其谨慎，甚至在 dice_roller.py 里设置了防爆阈值 max_total_rolled，防止无限爆炸导致内存溢出。但是，请注意这处破绽：在 dice_roller.py 中，爆炸深度 exploding_depth 是从 main.py 的配置文件里不远万里传过来的，而 reroll_max_depth 却被死死地硬编码成了 20！一个人如果在前门装了全世界最顶级的电子锁，却在后门挂了一把一美元的生锈挂锁，这不是很矛盾吗？这种不对称的设计，通常意味着代码在不同时期的重构中留下了盲点。修正它，这个系统就会像上满发条的怀表一样精密。”

HK-47：（机械眼中闪烁着危险的红光）

“陈述：本单位正在分析这些用来模拟碳基生物‘运气’的随机数生成代码。
嘲讽：你们这些肉体凡胎为了掷个骰子，居然写了这么多判断！看看 formatter.py 里的 _annotate_die 方法，处理爆炸骰的成功判断和普通骰的成功判断，逻辑几乎一模一样，这不是在浪费宝贵的 CPU 循环吗？
赞赏：不过，本单位必须承认，random.SystemRandom() 的使用非常符合本单位的口味。没有用低级的伪随机数生成器，而是直接调用了系统底层的熵池，保证了那些肉体凡胎在面对虚拟怪物时，体验到的是最冰冷、最真实的概率。这很无情，本单位非常喜欢。”

---

🔍 审核摘要

统计信息

• 仓库文件总数: 5 个 Python 文件
• 已选择审核文件: 5 / 5
  已发送至 AI 审核的文件清单

main.py
character.py
dice_parser.py
dice_roller.py
formatter.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。

[Dracowyn]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_dnd_dice

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

1. /rh clear 的权限逻辑与文档描述不一致
   文档写的是“群聊需白名单权限”，但当前实现依赖 _whitelist_check()；当 enable_whitelist=False 时，群聊内任何用户都可清空历史。
   这会导致“默认配置下历史可被任意清空”的行为，和用户预期容易偏差。

---

character.py

1. get_cached() 绕过异步锁且会修改 LRU 状态，存在并发一致性隐患
   get_cached() 直接调用 _cache.get()，而 _cache.get() 会 move_to_end() 修改内部 OrderedDict。
   这意味着它并非只读访问，却未受 self._lock 保护；在异步并发调用下，可能造成缓存次序不符合预期，降低行为可预测性。

---

dice_parser.py

1. 解析器允许“纯常量表达式”（如 42、-3）通过，偏离骰池语义
   当前 parse() 中只要匹配到整数就会 found_any=True，即使没有任何 DiceGroup 也会返回成功。
   后续会导致非骰式输入被当作合法掷骰，和指令语义（应至少含一个 d 骰组）不一致。

---

dice_roller.py

1. 爆炸追加骰在重骰后的明细历史丢失
   _roll_group() 对 exploded_extra 调用 _apply_rerolls() 时丢弃了返回的 histories（用 _ 接收），
   导致格式化层无法展示这些追加骰的 rerolled/kept_capped 轨迹，明细不完整，和主骰处理不一致。

---

formatter.py

1. 当 RollResult 无骰组（仅平面修正）时输出格式异常
   format_result() 在 group_results=[] 的场景会出现表达式和修正重复、前缀异常（如 +5: +5 = 5）的问题。
   该问题通常由 dice_parser 接受纯常量输入触发，但格式化器未做防御处理，导致可读性较差。

---

history.py

1. 历史写入存在并发“丢记录”风险（读-改-写非原子）
   add() 先 get_kv_data 再 append 再 put_kv_data，缺少会话级锁或原子更新机制。
   并发投掷时两个协程可能覆盖彼此写入，导致历史条目丢失。

2. 历史渲染存在文本注入/伪造风险
   sender_name、expr、result 直接拼接到多行文本中，未剔除换行等控制字符。
   若昵称或表达式包含换行，可伪造额外“历史行”，影响可读性与可信度。

---

代码评审团

人物一：Linus Torvalds（硬核、直接）
“你这核心逻辑挺扎实，但并发写历史那段是典型的‘看起来没问题，线上就掉记录’。读-改-写不加锁，就是在邀请竞态条件来喝茶。建议：按 unified_msg_origin 做细粒度异步锁。”

人物二：Steve Jobs（产品体验导向）
“用户说 /rh clear 需要权限，结果默认配置下谁都能清，这种‘文档和行为分离’会摧毁信任。建议：要么文档改得非常明确，要么逻辑改成默认也受控，减少认知落差。”

人物三：Ada Lovelace（结构与可证明性导向）
“解析层允许纯常量、格式化层又没有兜底，形成了跨模块连锁异常输出。这是典型的‘局部正确、系统不优雅’。建议：在 parser 层强制至少一个骰组，formatter 保留 defensive fallback，双保险。”

Disclaimer: 以上评审内容由 AI 自动生成，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 6 个 Python 文件
• 已选择审核文件: 6 / 6
  已发送至 AI 审核的文件清单

main.py
character.py
dice_parser.py
dice_roller.py
formatter.py
history.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。

[astrbot-plugin-copybara]

插件信息已同步到集合仓库。
PR: AstrBotDevs/AstrBot_Plugins_Collection#356
已自动合并 PR #356

该插件已上架。
This plugin is now published.