---
name: publish-docker-image
description: >-
  构建当前项目的 Docker 镜像，并将其上传到用户指定的镜像仓库。仅当用户显式指定
  $publish-docker-image、明确说“使用 publish-docker-image skill”，或由显式调用的 `$ack`
  根据用户明确的 Docker/OCI 镜像发布请求路由时使用；
  不要因普通编码、编辑 Dockerfile、本地构建、测试或一般 Docker 问题而自动触发。
---

# 发布 Docker 镜像

安全、可复现地构建当前提交对应的 Docker 镜像，并按用户指定的目标上传。

## 执行流程

1. 读取项目的 `AGENTS.md`、Dockerfile、构建脚本和相关发布文档。
2. 收集目标 registry、repository、tag、platform、构建上下文和 Dockerfile。优先使用用户已明确提供的值；缺少会改变发布结果的值时，停止并询问。
3. 检查 Git 工作区与当前提交。若存在未提交修改，明确说明镜像将包含哪些修改。
4. 按 [registry.md](references/registry.md) 检查仓库规则和认证状态。
5. 在执行外部写操作前，向用户展示完整镜像引用、platform、Dockerfile、构建上下文和源 commit。只有用户已明确要求上传到该目标时才继续。
6. 使用 [publish.sh](scripts/publish.sh) 构建并上传。不要自行拼接包含凭据的命令。
7. 检查命令退出状态，并尽可能获取远端 digest。
8. 汇报完整镜像引用、digest、platform、源 commit，以及是否包含未提交修改。

## 命令

默认构建并上传：

```bash
scripts/publish.sh \
  --registry REGISTRY \
  --repository NAMESPACE/IMAGE \
  --tag TAG \
  --platform PLATFORM
```

先验证而不构建或上传：

```bash
scripts/publish.sh \
  --registry REGISTRY \
  --repository NAMESPACE/IMAGE \
  --tag TAG \
  --platform PLATFORM \
  --dry-run
```

仅当用户明确要求本地构建时使用 `--load`。多平台镜像不能使用 `--load`。

## 安全边界

- 不把密码、访问令牌或 Docker 配置写入 skill、项目文件、命令参数或输出。
- 不主动执行 `docker login`；认证缺失时让用户通过交互式登录或其凭据管理器完成。
- 不覆盖已存在的 release tag，除非用户明确授权。无法可靠检查远端 tag 时说明这一限制。
- 不把 `latest` 作为隐含默认 tag。
- 不上传用户未指定的附加 tag。
- 不擅自修改 Dockerfile、发布配置、仓库权限或镜像保留策略。
- 若仓库、tag、platform 或目标环境存在歧义，在上传前询问用户。

## 验证

- 确认 `docker buildx build` 成功且启用了 `--push`。
- 优先用 `docker buildx imagetools inspect FULL_IMAGE_REF` 验证远端引用及平台。
- 记录远端 digest；若仓库不允许检查，明确报告只验证了 push 命令成功。
- 将发布所用的 Git commit 与工作区状态一并报告。