# artifact 模块说明

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

## 适用场景

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

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

## 推荐做法

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

## 注意事项

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