konabot/docs/artifact.md

artifact 模块说明

konabot/common/artifact.py 用于管理项目运行过程中依赖的额外制品，尤其是二进制文件、外部工具和按平台区分的运行时资源。

适用场景

• 某个插件或公共模块依赖额外下载的可执行文件或二进制资源。
• 依赖需要按操作系统或架构区分。
• 希望在启动时统一检测、按需下载并校验哈希。

如果额外制品适合在镜像构建阶段直接打包进 Docker 镜像，也可以在 Dockerfile 中通过多阶段构建处理；但对于需要在运行环境按平台管理、懒下载或统一校验的资源，优先考虑复用 artifact.py。

推荐做法

• 新增额外制品时，先判断它更适合放进镜像构建阶段，还是更适合交给 artifact.py 管理。
• 如果该资源会被多个插件或环境复用，倾向于统一通过 ArtifactDepends 和 register_artifacts(...) 管理。
• 为下载资源提供稳定来源，并填写 sha256 校验值，不要只校验“能不能下载下来”。
• 使用 required_os 和 required_arch 限制平台，避免无意义下载。
• 需要代理时，确认其行为与当前 NoneBot2 配置兼容。

注意事项

• 不要把是否存在额外制品的判断散落到多个插件里各自实现。
• 不要跳过哈希校验，除非该资源确实无法提供稳定校验值，并且有明确理由。
• 如果一个新能力除了额外制品，还依赖 Linux 动态库、字体、浏览器或系统命令，仍然需要同步检查并更新 Dockerfile。
• 如果镜像构建和运行阶段都依赖该制品，要分别确认 builder 和 runtime 的可用性。