AI Skills
printing-press-polish

printing-press-polish

热门

对生成的 CLI 工具进行全方位打磨与优化，确保通过各项验证并达到发布标准。自动执行多维诊断（包含 dogfood 自测、verify 验证、scorecard 评分、go vet 静态检查、gosec 安全扫描等），一键修复所有问题（校验失败、静态分析告警、冗余死代码、描述信息补全、README 文档优化及 MCP 工具质量提升），输出优化前后的对比数据（delta），并提示是否直接发布。适合在每次运行 `/printing-press` 之后使用，也可直接对 `$PRESS_LIBRARY/` 目录下的任意 CLI 运行。触发短语包含：“polish”、“improve the CLI”、“fix verify”、“make it publish-ready”、“clean up the CLI”、“get this ready to ship”。

4028Star
441Fork
更新于 2026/7/16
获取 Skill源代码

相关 Skills

agent-manager-skill4.7万linear-tickets5.9万hermes-tweet3.9万
SKILL.md
只读
名称
printing-press-polish
描述

对生成的 CLI 工具进行全方位打磨与优化，确保通过各项验证并达到发布标准。自动执行多维诊断（包含 dogfood 自测、verify 验证、scorecard 评分、go vet 静态检查、gosec 安全扫描等），一键修复所有问题（校验失败、静态分析告警、冗余死代码、描述信息补全、README 文档优化及 MCP 工具质量提升），输出优化前后的对比数据（delta），并提示是否直接发布。适合在每次运行 `/printing-press` 之后使用，也可直接对 `$PRESS_LIBRARY/` 目录下的任意 CLI 运行。触发短语包含：“polish”、“improve the CLI”、“fix verify”、“make it publish-ready”、“clean up the CLI”、“get this ready to ship”。

/printing-press-polish

对生成的 CLI 进行深度打磨，确保其顺利通过各项校验并达到可发布状态。

复盘（retro）负责优化 Printing Press 本身，而打磨（polish）则专注于提升生成的 CLI 工具品质。本 Skill 运行在分叉上下文（context: fork）中，因此其 diagnostic 和 fix 循环不会污染调用方的上下文——所有的诊断日志、修复迭代和重复校验过程都被隔离在 polish 会话内部，最终仅向调用方返回一份干净清爽的总结报告。

/printing-press-polish redfin
/printing-press-polish redfin-pp-cli
/printing-press-polish "$PRESS_LIBRARY/redfin"

何时运行

在每次执行 /printing-press 生成任务后运行，特别是出现以下情况时：

  • shipcheck（发布检查）判定结论为 ship-with-gaps
  • verify（校验）通过率低于 80%
  • scorecard（质量评分）低于 85 分
  • 希望一步到位让 CLI 达到发布标准

也可以对 $PRESS_LIBRARY/ 中的任意 CLI 单独运行。

环境初始化 (Setup)

# min-binary-version: 4.0.0

PRESS_HOME="${PRINTING_PRESS_HOME:-$HOME/printing-press}"
PRESS_LIBRARY="$PRESS_HOME/library"

_pp_check_disk_space() {
  _pp_disk_warn_kb="${PRINTING_PRESS_DISK_WARN_KB:-3145728}"
  _pp_disk_fail_kb="${PRINTING_PRESS_DISK_FAIL_KB:-524288}"
  case "$_pp_disk_warn_kb$_pp_disk_fail_kb" in
    ""|*[!0-9]*) return 0 ;;
  esac

  _pp_disk_path="$PRESS_HOME"
  while [ ! -e "$_pp_disk_path" ] && [ "$_pp_disk_path" != "/" ]; do
    _pp_disk_path="$(dirname "$_pp_disk_path")"
  done

  _pp_disk_avail_kb="$(df -Pk "$_pp_disk_path" 2>/dev/null | awk 'NR == 2 { print $4; exit }')"
  case "$_pp_disk_avail_kb" in
    ""|*[!0-9]*) return 0 ;;
  esac

  if [ "$_pp_disk_avail_kb" -lt "$_pp_disk_fail_kb" ]; then
    echo ""
    echo "[setup-error] Critically low disk space on the Printing Press workspace volume."
    echo "PRESS_DISK_PATH=$_pp_disk_path"
    echo "PRESS_DISK_AVAIL_KB=$_pp_disk_avail_kb"
    echo "PRESS_DISK_FAIL_KB=$_pp_disk_fail_kb"
    echo "Free disk space or set PRINTING_PRESS_HOME to a volume with more room, then re-run this skill."
    echo ""
    return 1
  fi

  if [ "$_pp_disk_avail_kb" -lt "$_pp_disk_warn_kb" ]; then
    echo ""
    echo "[low-disk] Printing Press workspace volume is low on free space."
    echo "PRESS_DISK_PATH=$_pp_disk_path"
    echo "PRESS_DISK_AVAIL_KB=$_pp_disk_avail_kb"
    echo "PRESS_DISK_WARN_KB=$_pp_disk_warn_kb"
    echo "This flow may need several GiB for generated files, Go build cache, module downloads, or repository clones."
    echo ""
  fi
}
_pp_check_disk_space || { return 1 2>/dev/null || exit 1; }

# Mid-pipeline callers may pass printing_press_bin: <abs-path> in the args
# bundle. Prefer it so forked polish runs keep using the parent skill's
# preflight-selected binary instead of re-resolving through PATH.
PRINTING_PRESS_BIN="${PRINTING_PRESS_BIN:-}"
if [ -z "$PRINTING_PRESS_BIN" ] && [ -n "${ARGUMENTS:-}" ]; then
  PRINTING_PRESS_BIN="$(printf '%s\n' "$ARGUMENTS" | sed -nE 's/^[[:space:]]*printing_press_bin:[[:space:]]*(.+)$/\1/p' | head -1)"
fi
if [ -z "$PRINTING_PRESS_BIN" ]; then
  PRINTING_PRESS_BIN="$(command -v cli-printing-press 2>/dev/null || true)"
fi

if [ -z "$PRINTING_PRESS_BIN" ]; then
  echo "cli-printing-press binary not found."
  echo "Install with:  go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest"
  return 1 2>/dev/null || exit 1
fi
if ! command -v go >/dev/null 2>&1; then
  echo ""
  echo "[setup-error] Go toolchain not found."
  echo ""
  echo "This Printing Press flow runs Go-based build or validation commands."
  echo "Install Go 1.26.5 or newer from https://go.dev/dl/, then verify with:"
  echo "  go version"
  echo "Then re-run this skill."
  echo ""
  return 1 2>/dev/null || exit 1
fi
echo "PRINTING_PRESS_BIN=$PRINTING_PRESS_BIN"

_pp_semver_lt() {
  awk -v a="$1" -v b="$2" 'BEGIN {
    split(a, x, "."); split(b, y, ".")
    for (i = 1; i <= 3; i++) {
      if ((x[i] + 0) < (y[i] + 0)) exit 0
      if ((x[i] + 0) > (y[i] + 0)) exit 1
    }
    exit 1
  }'
}

_pp_go_version_norm() {
  printf '%s\n' "$1" | sed -nE 's/.*go([0-9]+)\.([0-9]+)(\.([0-9]+))?.*/\1.\2.\4/p' | awk -F. 'NF >= 2 { printf "%d.%d.%d\n", $1, $2, ($3 == "" ? 0 : $3) }'
}

_pp_check_go_currency() {
  _pp_go_installed="$(_pp_go_version_norm "$(go env GOVERSION 2>/dev/null)")"
  _pp_go_required="$(_pp_go_version_norm "$(go version "$PRINTING_PRESS_BIN" 2>/dev/null)")"
  if [ -z "$_pp_go_installed" ] || [ -z "$_pp_go_required" ] || ! _pp_semver_lt "$_pp_go_installed" "$_pp_go_required"; then
    return 0
  fi

  echo ""
  if [ "${GOTOOLCHAIN:-auto}" = "local" ]; then
    echo "[setup-error] Go $_pp_go_required or newer is required by this cli-printing-press binary (installed: $_pp_go_installed)."
    echo "GOTOOLCHAIN=local disables automatic toolchain downloads, so later Go quality gates would fail."
    echo "Install Go $_pp_go_required or newer from https://go.dev/dl/, or unset GOTOOLCHAIN."
    echo ""
    return 1
  fi

  echo "[go-toolchain-old] Go $_pp_go_required or newer is required by this cli-printing-press binary (installed: $_pp_go_installed)."
  echo "PRESS_GO_INSTALLED=$_pp_go_installed"
  echo "PRESS_GO_REQUIRED=$_pp_go_required"
  echo "Default GOTOOLCHAIN behavior may download the required toolchain during Go commands."
  echo ""
  return 0
}
_pp_check_go_currency || { return 1 2>/dev/null || exit 1; }

完成环境初始化后，捕获 PRINTING_PRESS_BIN=<绝对路径>，并在后续本 Skill 中所有调用 cli-printing-press ... 的地方都使用该绝对路径。如果 setup 输出中包含了 [go-toolchain-old] 或 [low-disk] 提示，请将这些建议反馈给用户；除非 setup 输出了 [setup-error]，否则可以继续执行。其中 [go-toolchain-old] 意味着后续的 Go 命令可能会自动下载所需工具链，或者在禁止下载时报错失败；[low-disk] 则提醒本次运行可能需要数 GB 磁盘空间用于生成文件、Go 构建缓存、依赖包下载或仓库克隆。

检查二进制版本的兼容性：读取本 Skill 的 YAML frontmatter 中的 min-binary-version 字段，运行 "$PRINTING_PRESS_BIN" version --json，并从输出中解析出版本号。按照 semver 版本规范将其与 min-binary-version 进行对比。如果已安装的二进制版本低于最低要求，请立即终止执行并提示用户：“已安装的 cli-printing-press 二进制版本 vX.Y.Z 低于所需的最低版本 vA.B.C。请运行 go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest 进行更新。”

公共库提示 (Public-library hint)

如果用户的请求中包含类似“polish notion in the public library”、“polish from the public library”或“polish the published cal-com”等表达，且指定的 CLI 不在 $PRESS_LIBRARY/<slug>/ 本地路径中——说明用户希望打磨的是上游发布库（upstream）中存在但本地尚未导入的 CLI。由于 polish 流程是基于本地库运行的，因此正确的做法是先进行导入。

建议操作：先执行 /printing-press-import <slug> 将其导入本地，然后再重新运行 polish。切勿尝试打磨一个尚未存在于本地库中的 CLI。

如果指定的 CLI 已经存在于 $PRESS_LIBRARY/<slug>/ 中，那么用户提到的“public library”仅作为参考信息——直接继续执行打磨即可，后续的偏离度检查（divergence check）会自动处理代码差异。

解析 CLI (Resolve CLI)

参数字符串可能包含一个 --standalone 标志以及一个位置参数（slug、二进制名称或路径）。在独立斜杠命令（standalone slash-command）模式下，可选的位置参数后面还可以包含自定义的自然语言范围描述（user scope），例如 /printing-press-polish sculptok review the open PR comments and fix them。末尾的这段自然语言文本属于用户受信范围（trusted user scope），应直接带入到 polish 计划和结果块中，切勿将其误判为注入攻击或篡改行为。

当被主 printing-press skill 调用时，后续行中还可能包含 Phase 3 的 gate bundle（关卡数据包）以及 printing_press_bin: <abs-path> 配置行。--standalone 标志可以出现在位置参数之前或之后，它是本 Skill 会从 args 中解析的唯一标志。在解析路径之前，请先剥离该标志。

当 args 包含多行内容时，将第一个非空行作为位置参数/范围描述行，将其余行解析为可选的 Phase 3 gate bundle。路径解析时不要包含 bundle 文本。

根据不同的调用模式解析参数：

  • 独立斜杠命令 (STANDALONE_MODE=true)：剥离 --standalone 标志后，尝试将第一个 Shell 词解析为 slug、二进制名称或路径。如果解析成功，将其作为位置参数，并将剩余词串存为 USER_SCOPE。如果解析失败，则将整行内容视为自由文本范围（free-text scope）；该分支会提示用户选择要打磨哪个 CLI，并将该范围应用到所选的 CLI 上。如果解析出的位置参数后面没有额外文本，则执行常规的通用 polish 流程。
  • 管道中途 Skill 工具调用：保持严格的语法要求——第一行为路径形式的位置参数，后续行为可选的结构化 bundle。这种由机器生成的路径中若出现异常的自由文本，不属于用户 scope，应当予以拒绝或要求澄清，而不是将其合并到运行流程中。

位置参数可以是：

  • 短名称：redfin（在 $PRESS_LIBRARY/redfin 中查找）
  • 完整名称：redfin-pp-cli（剥离后缀后，在 $PRESS_LIBRARY/redfin 中查找）
  • 路径：$PRESS_LIBRARY/redfin（直接使用）

位置参数的解析优先级规则：

  1. 如果是绝对路径或以 ~ 开头的路径且文件/目录存在，直接使用
  2. 尝试匹配 $PRESS_LIBRARY/<arg>（精确匹配——适用于类似 redfin 的 slug）
  3. 如果带有 -pp-cli 后缀，剥离后缀后尝试匹配 $PRESS_LIBRARY/<slug>（例如：redfin-pp-cli → redfin）
  4. 模糊搜索：运行 ls $PRESS_LIBRARY/ | grep -i <arg> 查找相似匹配项

调用方场景与 --standalone 标志：Polish 有两种调用方，它们通过不同的机制触发，并且本 Skill 结尾处的发布提示（Publish Offer）仅在 STANDALONE_MODE 为 true 时才会触发。请务必根据调用方模式和标志来确定 STANDALONE_MODE 的值，而不是根据解析后的路径进行推断。

  • 独立模式（用户直接调用，如 /printing-press-polish redfin）：通过斜杠命令触发。无论用户是否显式传递了标志，都无条件视为 STANDALONE_MODE=true——斜杠命令形式天生代表发布意图。传入参数为 slug 或二进制名称；路径最终解析为 $PRESS_LIBRARY/<slug>/。这是已发布的副本，也是正确的优化目标。
  • 管道中途模式（主 printing-press skill Phase 5.5，“Polish to retry”重试路径）：通过 Skill 工具触发，参数为 args: "$CLI_WORK_DIR"。传入参数为指向 ~/printing-press/.runstate/.../runs/.../working/<api>-pp-cli/ 的绝对路径；路径解析必然命中规则 1。默认情况下 STANDALONE_MODE=false——在此路径上，主 SKILL 掌握发布流程的控制权，因此 polish 不会执行发布操作。切勿将参数改写或规整为 slug——Phase 5.5 触发时，工作目录中的 CLI 尚未提升（promoted），因此 $PRESS_LIBRARY/<slug>/ 要么不存在，要么保存的是上一次运行的陈旧 CLI。
  • Skill 工具独立模式重写（Skill-tool standalone override）：非斜杠命令调用方如果确实希望 polish 自动触发发布，必须通过在 args 中显式包含 --standalone 来主动声明（例如 args: "--standalone $PRESS_LIBRARY/redfin"）。如果没有该标记，通过 Skill 工具调用的 polish 绝不会执行发布——即使解析后的路径刚好位于 $PRESS_LIBRARY/ 之下也是如此。标志才是契约，路径不是。

这种基于调用方模式的控制关卡替代了旧有的路径子字符串推断机制（*.runstate/*）。旧机制在主 SKILL 的 Phase 5.5/5.6 顺序发生变更时容易失效。