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. 進行產出（Generate）
3. 實作最具高價值缺口的程式碼
4. 執行一次發佈檢查（shipcheck）區塊
5. （可選）執行線上 API 的 Smoke 測試

過程仍會產出產物（Artifacts），但僅保留對下一步驟有實質幫助的內容。

運作模式（Modes）

預設模式（Default）

一般模式。由 Claude 負責研究、產出排程、程式碼實作與驗證。

Codex 模式（Codex Mode）

若引數包含 codex 或 --codex，將純程式碼撰寫任務委派給 Codex CLI 處理。

適合委派給 Codex 的任務：

• 撰寫資料儲存／資料層程式碼
• 撰寫工作流程指令
• 修復失效標籤（dead flags）／廢棄程式碼（dead code）／路徑問題
• 編輯 README cookbook 範例

保留由 Claude 處理的任務：

• 前期研究與產品定位
• 選擇哪些功能缺口切中要害
• 驗證結果與最終發佈決策

若 Codex 連續失敗 3 次，即停止委派，改回由本地端接手完成。

精修模式（Polish Mode，獨立 Skill）

如需對現有的 CLI 進行二次優化與改善，請使用獨立的 polish Skill：

/printing-press-polish redfin

詳情請參閱 printing-press-polish Skill。它會執行診斷、修復驗證失敗項目、清理廢棄程式碼、修飾描述與 README，並提供發佈選項。

規則（Rules）

• 切勿發佈未針對真實目標進行行為測試的 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 批准的功能屬於發佈範疇（shipping scope）。 請勿在建置中期將發佈範疇內的功能降級為預留存根（stub）。若實作可行性降低，請帶着修正後的清單回到階段 1.5 並取得明確的重新批准。
• 切勿在 AskUserQuestion 選項、階段說明或參考檔案中，估算子任務的人力工時（例如「~15-30 分鐘」、「~1 小時」、「快速修復」）。實際執行工作的是 Agent，而不是使用者；Agent 憑空捏造的時間估計極不準確，也會讓使用者對 Prompt 失去信任。請改為描述工作範疇（程式碼行數、異動檔案數、相對規模）。唯一的例外是針對真正受限於客觀時間的事項提供實際耗時估算：整個 CLI 的執行歷程（預先設定使用者預期 — 多數 CLI 需要 30 分鐘以上）、工具安裝（go install 約需 10 秒），以及執行網路受限作業的 printing-press 子指令（crowd-sniff 掃描 npm + GitHub 約需 5-10 分鐘）。任何僅受限於 Agent 推理時間的事項都不屬於客觀時間限制 — 請一律描述工作範疇。
• 使用原始擷取內容（raw captures）進行合約與規格研究。 在閱讀官方文件、驗證／錯誤／速率限制頁面、端點參考資料、OpenAPI/Postman 連結，或其確切標示符會影響產出 CLI 的原始碼頁面時，請參閱 references/fetch-docs.md 並使用其提供的 fetch-docs.sh 輔助工具。僅在可以接受遺失欄位級細節的快速概覽（TL;DR）情境下，才使用 WebFetch。
• 以「最短發佈時間（time-to-ship）」為首要優化目標，而非「最短文件撰寫時間（time-to-document）」。
• 只要先前的研究結果已經夠好，就應直接重複使用。
• 切勿將單一概念分散記錄在多個強制產物中。
• 本 Skill 產生的持久性檔案需存放於 $PRESS_RUNSTATE/（執行狀態）或 $PRESS_MANUSCRIPTS/（存檔）。短暫的指令擷取內容可存放在 /tmp/printing-press/，且使用後必須移除。
• 請勿將 dogfood 實測、廢棄程式碼稽核、執行階段驗證與最終評分拆分為單獨的敘述階段。請將它們視為單一發佈檢查（shipcheck）區塊整合處理。
• 優先在前期執行成本低、訊號強（high-signal）的檢查。
• 優先修復阻礙性問題（blocker）與高槓桿率的失敗項目。
• 在 generate、dogfood、verify 和 scorecard 中重複使用相同的規格路徑。
• YAML、JSON、本地路徑與 URL 皆為驗證工具支援的有效規格輸入來源。
• 除非使用者明確要求，否則驗證修復迴圈最多執行 2 次。

機密與個人資料保護（核心鐵則）

以下規則無妥協餘地，在整個執行過程中隨時適用。

API Key 的明文數值、Token 數值、密碼及 Session Cookie 絕對不得
出現在任何產物中：包含原始碼、文稿、證明文件、README、HAR 檔案，或任何提交至 git 的內容。環境變數名稱（例如 STEAM_API_KEY）與預留占位符（例如 "your-key-here"）則為安全內容。

在階段 5.6（歸檔）期間以及發佈之前，請閱讀並套用
references/secret-protection.md 以進行：

• 產物的精確數值掃描與自動遮蔽（auto-redaction）
• HAR 驗證資訊清除（標頭、查詢字串、Cookie）
• 執行期間的 API Key 處理規則
• Session 狀態清除順序

展前檢查（Preflight）

本節必須在向使用者顯示任何 Prompt 前執行 — 包含下方的 Orientation 與 Briefing 流程。 缺少二進位檔或有可用更新，是使用者在決定深入某個 API 之前就需要知道的資訊。在 Preflight 完成且 references/setup-checks.md 中的所有訊號均處理完畢前，切勿呼叫 AskUserQuestion、列印引導文案或與使用者進行互動。

<!-- PRESS_SETUP_CONTRACT_START -->

# min-binary-version: 4.0.0

# 首先計算作用域 — 本地建置檢測所需
_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
}

# 針對前三個版號組件進行嚴格的新舊比較（Strict-older semver compare）。
# 預先發佈（Pre-release）後綴會折疊為正式發佈版本（GA）進行比較（可接受：我們不發佈預先發佈標籤）。
_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 為最新狀態，但 Hooks 可能不存在或被停用。
# 在信任該二進位檔之前，請先與檢出的原始碼版本進行比較。
_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 的安裝流程才是唯一事實來源；
    # 靜默自動安裝會將失敗模式（網路、錯誤的 GOPATH）隱藏在不透明的 Skill 呼叫內部。
    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 等），
# 因此若缺少 `go`，要在 5 分鐘後才會顯現。當 Go 存在時，提前檢查僅需花費一次 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