AI Skills
printing-press-score

printing-press-score

熱門

對生成的 CLI 進行 Steinberger 評分，或並排比較兩個 CLI

4028星標
441分支
更新於 2026/7/16
獲取技能源代碼

相關技能

senior-architect4.5萬deployment-pipeline-design3.8萬cmux-backend2.5萬
SKILL.md
唯讀
名稱
printing-press-score
描述

對生成的 CLI 進行 Steinberger 評分，或並排比較兩個 CLI

版本
0.1.0

/printing-press-score

對生成的 CLI 進行 Steinberger 評分。支援重新評分、依名稱或路徑評分，以及比較兩個 CLI。

快速開始

/printing-press-score                              # 重新評分當前 CLI
/printing-press-score notion-pp-cli-4              # 依名稱評分
/printing-press-score ~/my-cli                     # 依路徑評分
/printing-press-score notion-pp-cli-4 vs notion-pp-cli-2  # 比較兩個 CLI

前置需求

  • 已安裝 Go 1.26.5 或更新版本
  • cli-printing-press 二進位檔在 PATH 中（使用 go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest 安裝）

步驟 0：設定

在執行任何其他指令前，先執行設定合約以確認 cli-printing-press 二進位檔在 PATH 中，並初始化範圍變數：

<!-- 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)"

# 若在 printing-press 儲存庫內執行，優先使用本地建置
_press_repo=false
if [ -x "$_scope_dir/cli-printing-press" ] && [ -d "$_scope_dir/cmd/cli-printing-press" ]; then
  _press_repo=true
  export PATH="$_scope_dir:$PATH"
  echo "使用本地建置：$_scope_dir/cli-printing-press"
elif ! command -v cli-printing-press >/dev/null 2>&1; then
  if [ -x "$HOME/go/bin/cli-printing-press" ]; then
    echo "在 ~/go/bin/cli-printing-press 找到 cli-printing-press，但不在 PATH 中。"
    echo "請將 GOPATH/bin 加入 PATH： export PATH=\"\$HOME/go/bin:\$PATH\""
  else
    echo "找不到 cli-printing-press 二進位檔。"
    echo "請使用以下指令安裝： go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest"
  fi
  return 1 2>/dev/null || exit 1
fi

# 解析並輸出 agent 在後續每次呼叫 `cli-printing-press` 時必須使用的絕對路徑。
# 上面的 `export PATH` 僅影響目前這個 Bash 工具呼叫；後續呼叫會開啟新的 shell，
# 並根據使用者的預設 PATH 解析裸 `cli-printing-press`，導致全域的過時版本可能
# 靜默覆蓋本地建置。Agent 應擷取此標記，並在後續每次呼叫中替換為絕對路徑。
if [ "$_press_repo" = "true" ]; then
  PRINTING_PRESS_BIN="$_scope_dir/cli-printing-press"
else
  PRINTING_PRESS_BIN="$(command -v cli-printing-press 2>/dev/null || true)"
fi
echo "PRINTING_PRESS_BIN=$PRINTING_PRESS_BIN"

PRESS_BASE="$(basename "$_scope_dir" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9_-]/-/g; s/^-+//; s/-+$//')"
if [ -z "$PRESS_BASE" ]; then
  PRESS_BASE="workspace"
fi

PRESS_SCOPE="$PRESS_BASE-$(printf '%s' "$_scope_dir" | shasum -a 256 | cut -c1-8)"
PRESS_HOME="${PRINTING_PRESS_HOME:-$HOME/printing-press}"
PRESS_RUNSTATE="$PRESS_HOME/.runstate/$PRESS_SCOPE"
PRESS_LIBRARY="$PRESS_HOME/library"
PRESS_MANUSCRIPTS="$PRESS_HOME/manuscripts"
PRESS_CURRENT="$PRESS_RUNSTATE/current"

mkdir -p "$PRESS_RUNSTATE" "$PRESS_LIBRARY" "$PRESS_MANUSCRIPTS" "$PRESS_CURRENT"

<!-- PRESS_SETUP_CONTRACT_END -->

執行設定合約後，從標準輸出擷取 PRINTING_PRESS_BIN=<abs-path> 這一行。此技能中後續每次 cli-printing-press ... 呼叫都必須使用該絕對路徑（直接代入值，而非字面 $PRINTING_PRESS_BIN 符記）— 上面的 export PATH 僅影響執行它的單一 Bash 工具呼叫，後續呼叫會開啟新的 shell，裸 cli-printing-press 會根據使用者的預設 PATH 解析，導致過時的全域版本可能覆蓋本地建置。

擷取二進位檔路徑後，檢查二進位檔版本相容性。讀取此技能 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 更新。」

當前執行狀態從 $PRESS_RUNSTATE 解析。已發布的 CLI 從 $PRESS_LIBRARY 解析。已封存的手稿從 $PRESS_MANUSCRIPTS 解析。

步驟 1：解析引數

讀取使用者在 /printing-press-score 之後的輸入。輸入是自由格式 — 請解讀意圖，不要強制語法。

要移除的雜訊詞： compare, vs, versus, and, against, with, to

移除雜訊詞後，計算剩餘的 token 數量：

  • 0 個 token → 重新評分當前模式
  • 1 個 token → 評分單一模式
  • 2 個 token → 比較模式

步驟 2：解析 CLI 目錄

對於每個 CLI 識別碼，將其解析為目錄路徑：

如果 token 包含 / 或 .

視為路徑（絕對或相對）。確認目錄存在。

如果 token 是純名稱

依序嘗試以下位置：

  1. $PRESS_LIBRARY/<name>/ — 完全符合
  2. $PRESS_LIBRARY/<name>-pp-cli/ — 加上 -pp-cli 後綴
  3. 如果兩者都不存在，使用 Glob 搜尋 $PRESS_LIBRARY/<name>-pp-cli*
  4. 如果剛好有一個 Glob 符合且為目錄，則使用它
  5. 如果有多個 Glob 符合，使用 AskUserQuestion 顯示編號選單

如果都不存在，掃描當前執行和封存狀態：
6. 使用 Glob 尋找 $PRESS_RUNSTATE/runs/*/state.json 檔案
7. 讀取每個檔案，尋找 output_dir 或 working_dir 值，其 basename 包含該名稱
8. 如果找到且目錄存在，則使用它

如果無法解析，回報錯誤：「找不到 CLI '<name>'。請提供路徑或檢查名稱。」

重新評分當前（0 個 token）

  1. 使用 Glob 尋找所有 $PRESS_CURRENT/*.json 檔案
  2. 讀取每個檔案以取得 api_name、state_path 和 working_dir
  3. 篩選出 working_dir 實際存在於磁碟上的項目
  4. 如果找不到，使用 Glob 搜尋 $PRESS_LIBRARY/*-pp-cli* 並改用那些目錄
  5. 如果剛好一個 → 自動使用
  6. 如果多個 → 使用 AskUserQuestion 顯示編號選單：
    找到多個 CLI。要評分哪一個？
1. stripe-pp-cli ($PRESS_LIBRARY/stripe-pp-cli)
2. notion-pp-cli ($PRESS_LIBRARY/notion-pp-cli)
3. linear-pp-cli ($PRESS_LIBRARY/linear-pp-cli)
  7. 如果找不到 → 回報：「找不到任何生成的 CLI。請提供名稱或路徑。」

步驟 3：尋找 Tier 2 評分的規格

對於每個解析出的 CLI 目錄，尋找 OpenAPI 規格：

  1. 檢查 <cli-dir>/spec.json — 管線在生成期間會將 YAML 規格轉換為 JSON
  2. 如果找不到，掃描 $PRESS_RUNSTATE/runs/*/state.json 檔案，尋找與此 CLI 目錄相符的項目。讀取其 spec_path 欄位。如果該檔案存在於磁碟上，則使用它。
  3. 如果找不到規格，在沒有 --spec 的情況下繼續。告知使用者：「找不到規格 — 規格衍生維度將標記為 N/A 並從分母中排除。請提供規格路徑以進行完整評分。」

步驟 4：執行評分卡

單一評分模式

執行評分卡指令：

cli-printing-press scorecard --dir <resolved-path> --json

如果找到規格，加上 --spec <spec-path>。

解析 JSON 輸出。結構如下：

{
  "api_name": "...",
  "steinberger": {
    "output_modes": 8,
    "auth": 7,
    "error_handling": 6,
    "terminal_ux": 9,
    "readme": 5,
    "doctor": 10,
    "agent_native": 7,
    "local_cache": 4,
    "breadth": 7,
    "vision": 6,
    "workflows": 3,
    "insight": 5,
    "path_validity": 0,
    "auth_protocol": 0,
    "data_pipeline_integrity": 7,
    "sync_correctness": 6,
    "type_fidelity": 4,
    "dead_code": 3,
    "total": 72,
    "percentage": 72
  },
  "overall_grade": "B",
  "gap_report": ["..."],
  "unscored_dimensions": ["path_validity", "auth_protocol"]
}

如果存在 unscored_dimensions，這些維度應顯示為 N/A，而非 0/x，並應描述為從分母中排除，而非可修復的 CLI 缺陷。為向後相容，JSON 仍將數值欄位編碼為 0；消費者必須使用 unscored_dimensions 來區分 N/A 與真正的零。

學習循環的計分是靜態行為導向，而非存在性導向：評分卡會對根指令上的 teach/recall/learnings 註冊以及非空的實體查詢種子（或規格中記錄的無實體逃脫）給予分數。學習循環預設為開啟，因此 internal/learn/ 存在不會獲得額外分數；在解釋學習缺口時，應指出缺少種子或未註冊的指令，而非缺少檔案。執行證明（驗證矩陣、learnings stats）屬於驗證和內部測試範疇；評分卡不會執行任何二進位檔。

比較模式

使用兩個同時的 Bash 工具呼叫平行執行兩個評分卡指令：

# 呼叫 1：
cli-printing-press scorecard --dir <path1> --spec <spec1> --json

# 呼叫 2：
cli-printing-press scorecard --dir <path2> --spec <spec2> --json

解析兩個 JSON 輸出。

步驟 5：呈現輸出

單一評分表格

呈現豐富的 Markdown 表格。注意：Tier 1 維度滿分皆為 10。Tier 2 維度滿分為 10，但 TypeFidelity 和 DeadCode 滿分為 5。

Scorecard: <api_name>

Infrastructure (Tier 1)
| Dimension      | Score |
|----------------|-------|
| Output Modes   | 8/10  |
| Auth           | 7/10  |
| Error Handling | 6/10  |
| Terminal UX    | 9/10  |
| README         | 5/10  |
| Doctor         | 10/10 |
| Agent Native   | 7/10  |
| Local Cache    | 4/10  |
| Breadth        | 7/10  |
| Vision         | 6/10  |
| Workflows      | 3/10  |
| Insight        | 5/10  |

Domain Correctness (Tier 2)
| Dimension               | Score |
|--------------------------|-------|
| Path Validity            | 9/10  |
| Auth Protocol            | 8/10  |
| Data Pipeline Integrity  | 7/10  |
| Sync Correctness         | 6/10  |
| Type Fidelity            | 4/5   |
| Dead Code                | 3/5   |

**Total: 72/100 — Grade B**

如果 gap_report 非空，列出缺口：

Gaps:
- <gap 1>
- <gap 2>

如果 unscored_dimensions 非空，在表格後加上備註：

Note: path_validity, auth_protocol were unscored and omitted from the denominator. Provide a spec path for full scoring.

比較表格

呈現並排表格，包含差異欄。以第一個 CLI 名稱和第二個 CLI 名稱作為欄標題。計算差異為（CLI 1 分數 - CLI 2 分數）。正數顯示 +N，負數顯示 -N，零顯示 —。

Scorecard Comparison: <name1> vs <name2>

Infrastructure (Tier 1)
| Dimension      | <name1> | <name2> | Delta |
|----------------|---------|---------|-------|
| Output Modes   | 8/10    | 5/10    | +3    |
| Auth           | 7/10    | 7/10    | —     |
| ...            |         |         |       |

Domain Correctness (Tier 2)
| Dimension               | <name1> | <name2> | Delta |
|--------------------------|---------|---------|-------|
| Path Validity            | 9/10    | 6/10    | +3    |
| ...                      |         |         |       |

| **Total**  | **72/100 (B)** | **56/100 (C)** | **+16** |

錯誤處理

  • 如果 cli-printing-press 二進位檔不在 PATH 中 → 顯示安裝說明：go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest
  • 如果評分卡指令失敗 → 回報錯誤並附上完整 stderr 輸出
  • 如果 CLI 目錄不存在 → 回報無法解析的名稱
  • 如果 JSON 解析失敗 → 顯示原始輸出並回報解析錯誤