printing-press

/printing-press

无需在繁琐的阶段拉扯上浪费一个小时，直接为 API 生成最实用、最高效的 CLI。

/printing-press Notion
/printing-press Discord codex
/printing-press --spec ./openapi.yaml
/printing-press --har ./capture.har --name MyAPI
/printing-press https://postman.com/explore
/printing-press https://postman.com

v2 改动说明

旧版 Skill 拖慢了交付节奏：

• 在写出代码之前要求编写过多强制性的调研文档
• 代码写好之后又存在过多相互独立的后期验证阶段
• 容易在极后期才发现原本显而易见的失败问题

当前版本采用统一的精简闭环：

1. 解析规范并编写一份调研简报（research brief）
2. 执行代码生成
3. 构建并补齐价值最高的缺口（gaps）
4. 执行一次集中发布检查（shipcheck）
5. （可选）运行真实 API 冒烟测试

相关产物（Artifacts）仍会保留，但仅生成对下一步有实际实质帮助的内容。

运行模式

默认模式（Default）

常规模式。由 Claude 统一负责调研、生成编排、代码实现及验证。

Codex 模式（Codex Mode）

若参数中包含 codex 或 --codex，则将纯代码编写任务下发给 Codex CLI 处理。

适合交给 Codex 的任务：

• 编写 store/数据层代码
• 编写工作流命令
• 修复无效标记 (dead flags) / 死代码 / 路径问题
• 编辑 README cookbook 示例

保留给 Claude 的任务：

• 前期调研与产品定位
• 筛选并决定哪些功能缺口最为关键
• 评估验证结果与做出发布决策

若 Codex 连续失败 3 次，则停止委派任务，转为本地直接完成。

润色/优化模式（Polish Mode，独立 Skill）

若需要对现有 CLI 进行二次优化与改进，请使用独立的 polish skill：

/printing-press-polish redfin

详情请参考 printing-press-polish Skill。它会运行诊断工具、修复验证失败项、清理死代码、优化描述信息与 README，并提示是否发布。

规则规范

• 切勿交付未经真实目标行为测试的 CLI。 go build 和 verify 的通过率仅仅代表结构无误，并不代表功能正确。阶段 5 的机械化测试矩阵会覆盖每一个子命令 + --json + 错误路径；若该矩阵未被完整执行，则此 CLI 绝不可交付。快速检查（Quick Check）是最低门槛；当用户要求严谨全面时，必须执行完整吃狗粮测试（Full Dogfood）。
• 狗粮测试（dogfood）期间发现的 Bug 必须在交付前修复，严禁归为“留待 v0.2 处理”。 如果改动 1-3 个文件就能解决，立刻修复。ship-with-gaps 已不再作为默认裁定方案（详见阶段 4）。当前会话中的上下文是最清晰的；把问题留给可能永远不会去处理的 v0.2 待办列表，本质上就是把已知损坏的 CLI 交付出去。
• 阶段 1.5 中批准的功能均属于交付范围。 严禁在构建过程中将属于交付范围的功能降级为桩代码（stub）。若发现实现方案不可行，必须带着修改后的清单返回阶段 1.5，并获取用户的明确再次批准。
• 严禁在 AskUserQuestion 选项、阶段描述或参考文档中为子任务标注人类耗时预估（如“约 15-30 分钟”、“约 1 小时”、“快速修复”）。实际干活的是 Agent 而非用户；Agent 凭空捏造的时间预估极不可靠，反而会让用户对提示词失去信任。应当改为描述工作量范围（如代码行数、涉及文件数、相对体量）。唯一的例外是真正受限于客观物理时间的预估：整个 CLI 的运行预估（提前建立用户预期——大多数 CLI 生成需要 30+ 分钟）、工具安装耗时（go install 约需 10 秒）以及受网络限制的 printing-press 子命令耗时（如 crowd-sniff 扫描 npm + GitHub 约需 5-10 分钟）。任何仅受限于 Agent 推理时间的任务都不是时间限制任务——请一律描述工作量范围。
• 在开展契约调研时必须使用原始抓取内容。 当阅读官方文档、鉴权/错误/限流页面、端点参考、OpenAPI/Postman 链接，或其精确标识符会直接影响生成的 CLI 的源码页面时，请阅读 references/fetch-docs.md 并使用其中的 fetch-docs.sh 辅助工具。只有在只需要快速了解概要（TL;DR）、且丢失字段级细节也完全可接受时，才允许使用 WebFetch。
• 以“交付速度”为第一优化目标，而非“文档撰写耗时”。
• 只要先前的调研结果足够好，就尽量直接复用。
• 切勿将同一个设计思路分散写到多个强制性产物中。
• 该 Skill 生成的持久化文件须存放在 $PRESS_RUNSTATE/（工作状态）或 $PRESS_MANUSCRIPTS/（归档）目录下。短寿命的命令抓取记录可以使用 /tmp/printing-press/，且用完后必须及时删除。
• 无需为吃狗粮测试（dogfood）、死代码审计、运行时验证和最终评分单独设立叙述性的阶段，应将其统部署为一个集中发布检查（shipcheck）模块。
• 尽早运行低成本、高信号量的检查项。
• 优先修复阻碍性问题（blockers）和高杠杆的失败项。
• 在 generate、dogfood、verify 和 scorecard 全流程中复用相同的规范路径（spec path）。
• YAML、JSON、本地路径以及 URL 均可作为验证工具的合法规范输入。
• 验证修复循环最多执行 2 次，除非用户明确要求增加次数。

密钥与个人隐私信息（PII）保护（核心硬性规则）

以下规则绝无妥协余地，在整个运行过程中必须时刻严格遵守。

API Key 具体值、Token 具体值、密码以及 Session Cookie 绝对不允许出现在任何产物中，包括源码、手稿、证明文件、README、HAR 或任何提交到 git 的文件中。环境变量名称（例如 STEAM_API_KEY）和占位符（例如 "your-key-here"）则是安全的。

在阶段 5.6（归档）期间及发布之前，请阅读并应用 references/secret-protection.md 中的相关要求：

• 产物明细值的扫描与自动脱敏
• HAR 文件中认证信息的剥离（请求头、查询字符串、Cookie）
• 运行期间 API Key 的处理规范
• Session 状态的清理顺序

预检（Preflight）

本节内容必须在向用户展示任何提示信息之前运行——包括下文的导向与简报流程（Orientation and Briefing flow）。 二进制文件缺失或可用的升级信息，是用户在决定针对某个 API 展开工作 之前 必须了解的信息。在预检完成且 references/setup-checks.md 中的所有信号均已处理完毕之前，切勿调用 AskUserQuestion、打印导向说明或与用户发生任何交互。

<!-- PRESS_SETUP_CONTRACT_START -->

# min-binary-version: 4.0.0

# 先获取 scope 路径 — 用于检测本地构建
_scope_dir="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
_scope_dir="$(cd "$_scope_dir" && pwd -P)"

_press_repo=false
if [ -d "$_scope_dir/cmd/cli-printing-press" ] && [ -f "$_scope_dir/go.mod" ]; then
  _press_repo=true
fi

_resolve_press_bin() {
  if command -v cli-printing-press >/dev/null 2>&1; then
    command -v cli-printing-press
    return 0
  fi
  if command -v printing-press >/dev/null 2>&1 && printing-press version --json >/dev/null 2>&1; then
    command -v printing-press
    return 0
  fi
  return 1
}

# 针对前三个版本号组件进行严格的 semver 小于比较。预发布后缀自动折叠为其 GA 对应版本（完全可行：我们不发布预发布 tag）。
_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
  }'
}

_source_press_version() {
  sed -nE 's/^var[[:space:]]+Version[[:space:]]*=[[:space:]]*"([^"]+)".*/\1/p' \
    "$_scope_dir/internal/version/version.go" 2>/dev/null | head -n 1
}

_rebuild_local_press_bin_if_stale() {
  if [ "$_press_repo" != "true" ] || [ ! -x "$_scope_dir/cli-printing-press" ]; then
    return 0
  fi

  _local_v="$("$_scope_dir/cli-printing-press" version --json 2>/dev/null | sed -nE 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p')"
  _source_v="$(_source_press_version)"
  if [ -z "$_local_v" ] || [ -z "$_source_v" ] || ! _semver_lt "$_local_v" "$_source_v"; then
    return 0
  fi

  echo ""
  echo "[local-binary-stale] local build v$_local_v is older than source v$_source_v"
  if ! command -v go >/dev/null 2>&1; then
    echo "[setup-error] local cli-printing-press binary is stale and Go is not on PATH, so it cannot be rebuilt."
    return 1 2>/dev/null || exit 1
  fi

  if (cd "$_scope_dir" && go build -o ./cli-printing-press ./cmd/cli-printing-press); then
    echo "[local-binary-rebuilt] rebuilt $_scope_dir/cli-printing-press"
    echo ""
  else
    echo "[setup-error] local cli-printing-press binary is stale and rebuild failed."
    return 1 2>/dev/null || exit 1
  fi
}

# 当在 printing-press 仓库内部运行时优先选择本地构建。
# Lefthook 可能会保持 ./cli-printing-press 最新，但 hook 可能会缺失或被禁用。在信任它之前与签出的源码版本做对比。
_rebuild_local_press_bin_if_stale || { return 1 2>/dev/null || exit 1; }
if [ "$_press_repo" = "true" ] && [ -x "$_scope_dir/cli-printing-press" ]; then
  export PATH="$_scope_dir:$PATH"
  echo "Using local build: $_scope_dir/cli-printing-press"
elif ! _resolve_press_bin >/dev/null; then
  # 如果二进制文件在 ~/go/bin 中但不在用户的交互式 PATH 中，扩充 PATH。
  if [ -x "$HOME/go/bin/cli-printing-press" ]; then
    export PATH="$HOME/go/bin:$PATH"
  elif [ -x "$HOME/go/bin/printing-press" ] && "$HOME/go/bin/printing-press" version --json >/dev/null 2>&1; then
    export PATH="$HOME/go/bin:$PATH"
  else
    # 拒绝：cli-printing-press 二进制文件是必需的，我们不会自动安装它。README 的安装流程是唯一权威事实来源；
    # 隐式自动安装会在不透明的 Skill 调用内部掩盖失败模式（网络、错误的 GOPATH）。
    echo ""
    echo "[setup-error] cli-printing-press binary not found."
    echo ""
    if command -v go >/dev/null 2>&1; then
      echo "Install it in your terminal:"
      echo "  go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest"
    else
      echo "Go 1.26.5 or newer is also not installed. Install Go from https://go.dev/dl/, then:"
      echo "  go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest"
    fi
    echo ""
    echo "Verify with: cli-printing-press --version"
    echo "Then re-run /printing-press."
    return 1 2>/dev/null || exit 1
  fi
fi

# 验证 Go 工具链在 PATH 上。代码生成后会运行基于 Go 的质量检查门禁（go mod tidy、go vet 等），
# 写入数千行脚手架代码后才抛错会导致前面耗费 5+ 分钟。提前Fail-fast验证只需一个 command -v 调用，即可将后期不透明的报错转化为 30 秒内可操作的中断。
if ! command -v go >/dev/null 2>&1; then
  echo ""
  echo "[setup-error] Go toolchain not found."
  echo ""
  echo "The Printing Press generator runs Go-based quality gates after generation."
  echo "Install Go 1.26.5 or newer from https://go.dev/dl/, then verify with:"
  echo "  go version"
  echo "Then re-run /printing-press."
  echo ""
  return 1 2>/dev/null || exit 1
fi

# 验证已安装的 Go 环境可以编译并运行常见的标准库导入。解压不完整的 Go 环境可能会留下一部分可用的二进制文件以响应 `go version`，
# 但却缺失 $GOROOT/src 下的包，导致在后面的 Go 质量检查门禁期间崩溃。
_go_smoke_root="${PRINTING_PRESS_GO_SMOKE_DIR:-$HOME/.printing-press-smoke}"
if ! mkdir -p "$_go_smoke_root"; then
  echo ""
  echo "[setup-error] Unable to create Go smoke-test workspace at $_go_smoke_root."
  echo "Set PRINTING_PRESS_GO_SMOKE_DIR to a writable non-temp directory and retry."
  echo ""
  return 1 2>/dev/null || exit 1
fi
_go_smoke_dir="$(mktemp -d "$_go_smoke_root/stdlib.XXXXXX" 2>/dev/null || true)"
if [ -z "$_go_smoke_dir" ]; then
  echo ""
  echo "[setup-error] Unable to create Go smoke-test workspace under $_go_smoke_root."
  echo "Set PRINTING_PR