Files

T

2026-08-23 22:02:06 +08:00

6.6 KiB

Raw Blame History

name, description

name	description
deb-publisher	构建并发布 Debian DEB 包：发现项目已有的 Makefile 和打包入口，使用 skill 自带的通用上传脚本提交包，校验包元数据与内容，并验证发布结果。触发词：构建 deb、发布 deb、上传 deb、提交 deb、推送 apt 仓库、打 Debian 包。仅分析打包逻辑时也可使用，但不会在未获授权时执行上传。

DEB Publisher

复用项目已有发布约定，安全地完成“发现入口 → 构建 → 检查 → 上传 → 验证”。

何时使用

用户要求构建、发布、上传或提交 .deb 包。
用户要求梳理或接通项目现有的 DEB 发布流程。
用户要求把已经生成的 .deb 推送到 APT/DEB 包仓库。

不适用

只需要安装或卸载本地 DEB 包。
目标是 RPM、APK、容器镜像或语言包管理器。
用户只要求设计全新的 Debian 打包体系；此时应先完成方案设计。

工作流

1. 发现项目约定

从项目根目录查找，不预设文件位置：

rg -n -i --hidden --glob '!.git' \
  'build-deb|upload-deb|publish-deb|dpkg-deb|debuild|curl.*deb|\.deb\b|aptly|reprepro'

重点检查：

Makefile、CI 配置、debian/、构建脚本和发布文档。
版本号、包名、架构、产物目录和仓库名如何传入。
发布端点、认证方式以及发布是否由构建目标自动触发。
项目根目录或发布文档是否提供 .env 配置；只确认变量名，不打印其值。
当前工作树和目标版本是否匹配。

优先复用已有构建入口。上传默认使用本 skill 的 scripts/upload_deb.sh，不要把它复制到项目中；仅当目标仓库协议不兼容时才复用或修改项目专属上传逻辑。

2. 确认发布边界

上传是外部写操作。仅当用户明确要求发布、上传或提交时执行；若用户只要求查看、诊断或构建，则停在相应阶段。

执行上传前确认：

目标服务和仓库来自项目配置或用户输入，不猜测生产端点。
认证令牌已通过环境变量、密钥系统或项目 .env 提供。
目标版本、架构和产物路径能够从构建配置推导。
相同版本是否允许覆盖；无法确认且可能覆盖时，先询问用户。

绝不把令牌写入命令输出、文件、提交或最终回复。不要用 set -x 执行含凭据的脚本。

如果项目根目录存在 .env，且当前 shell 尚未提供所需变量，上传前必须显式加载该文件；上传脚本不会自动读取 .env：

set -a
. "$PROJECT_ROOT/.env"
set +a

加载后确认 DEB_SERVER_URL、DEB_REPOSITORY、DEB_TOKEN 已非空；如配置了自定义上传路径，也确认 DEB_UPLOAD_PATH。不得输出 .env 内容、令牌或完整环境变量值。当前 shell 中已显式设置的值优先于 .env，若需覆盖 .env，加载后重新导出显式值。

3. 构建包

使用项目声明的构建目标，并显式传入版本。例如项目提供 Make 目标时：

make build-deb VERSION="$RELEASE_VERSION"

如果构建目标会自动上传，而当前仅获构建授权，应改用其纯构建子目标。执行前检查所需工具和环境，例如 Docker、dpkg-deb、编译器、SSH 访问或前端工具链。

不得擅自清理宽泛目录。若脚本包含 rm -rf，先解析并确认目标是明确、受限的构建目录。

4. 上传前检查

定位唯一目标产物；若匹配多个包，不凭文件时间猜测：

find <artifact-dir> -maxdepth 2 -type f -name '*.deb' -print
dpkg-deb --info <package.deb>
dpkg-deb --contents <package.deb>

至少验证：

文件存在、非空且 dpkg-deb --info 成功。
Package、Version、Architecture 与本次发布一致。
包内容包含预期的主程序或关键文件。
maintainer scripts 存在时权限正确，且没有明显的宿主机破坏性操作。

建议记录 SHA-256：

sha256sum <package.deb>

5. 发布

解析当前 SKILL.md 所在目录，以绝对路径调用随 skill 分发的脚本：

DEB_SERVER_URL="$DEB_SERVER_URL" \
DEB_TOKEN="$DEB_TOKEN" \
DEB_REPOSITORY="$DEB_REPOSITORY" \
  <skill-dir>/scripts/upload_deb.sh <exact-package-path.deb>

执行上述命令前，若配置来自项目 .env，先按第 2 步加载 .env；不要把 .env 复制到 skill 或项目之外的临时位置，也不要把 token 作为命令行参数。

不要把脚本复制进当前项目，也不要将 token 作为命令行参数。脚本默认请求 /api/v2/upload/package，以 multipart 字段 package、token、 repository_name 上传，接受 200 和 201 为成功。端点路径不同时可设置 DEB_UPLOAD_PATH。

调用前确认目标服务使用上述协议；不兼容时不要强行调用。传入刚刚校验过的确切路径，不要使用宽泛 glob。项目已有 make upload-deb 时，检查它是否只是包装了同一协议：如果是，直接使用 skill 脚本；若 CI 或其他人仍依赖 Make 目标，可将目标改为调用已安装 skill 的脚本，但不要提交脚本副本。

脚本支持多个确切文件路径，会汇总每个文件的结果，并在任一失败时返回非零。

6. 验证与汇报

发布成功不能只依据“curl 已执行”。综合检查：

上传命令退出码为零。
HTTP 状态和响应体明确表示成功。
若仓库提供只读查询、索引或下载地址，再确认该包和版本已可见。
若索引更新是异步的，报告“上传已接受，索引尚待更新”，不要声称已完全可用。

最终回复给出：

包名、版本、架构。
产物路径和 SHA-256。
目标服务/仓库的非敏感标识。
构建、上传及仓库可见性各自的验证结果。
任何未完成项或回滚/覆盖风险。

修改已有发布逻辑时

保持项目现有变量名和调用入口，避免无关重构。
修复行为缺陷时增加最小静态检查或可离线运行的测试。
可用 bash -n 检查脚本语法；项目有 ShellCheck 时一并运行。
skill 自带上传脚本是 SSOT；通用上传行为的修改应落在 skills/deb-publisher/scripts/upload_deb.sh，不要同步复制到业务项目。
不通过真实生产上传来测试脚本，除非用户明确授权并给出测试版本或测试仓库。

完成标准

仅分析：入口、调用链、配置来源和风险已被准确说明。
仅构建：DEB 已生成，元数据、内容和校验和通过检查，未发生上传。
发布：构建检查通过，服务端接受上传，且仓库可见性已验证或被准确标记为待更新。

6.6 KiB Raw Blame History Unescape Escape