printing-press-score

Name: printing-press-score
Author: mvanhorn

github.com/mvanhorn测试与质量4.9k6.4k 次安装今天更新

代码仓库

关于 printing-press-score

使用 cli-printing-press 评估生成的命令行工具，支持重评当前 CLI、按名称或路径评分，以及比较两个 CLI。

主要功能

01重评当前 CLI
02按名称或路径为 CLI 评分
03比较两个 CLI 的评分卡
04有 OpenAPI 规范时纳入评分

适用场景

01检查新生成的 CLI
02比较两个生成版 CLI
03发现 CLI 的评分差距

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mvanhorn/cli-printing-press --skill printing-press-score

安装后在 Claude Code 中输入/printing-press-score确认已加载。

详细介绍

/printing-press-score

根据 Steinberger 标准为生成的 CLI 评分。支持重新评分、按名称/路径评分，以及比较两个 CLI。

快速开始

/printing-press-score                              # rescore current CLI
/printing-press-score notion-pp-cli-4              # score by name
/printing-press-score ~/my-cli                     # score by path
/printing-press-score notion-pp-cli-4 vs notion-pp-cli-2  # compare two

前提条件

已安装 Go 1.26.10 或更高版本
cli-printing-press 二进制文件位于 PATH 中（使用 go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest 安装）

步骤 0：设置

运行任何其他命令前，先运行设置契约，以验证 cli-printing-press 二进制文件位于 PATH 中，并初始化作用域变量：

# min-binary-version: 4.0.0

# Derive scope first — needed for local build detection
_scope_dir="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
_scope_dir="$(cd "$_scope_dir" && pwd -P)"

# Prefer local build when running from inside the printing-press repo.
_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 "Using local build: $_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 "cli-printing-press found at ~/go/bin/cli-printing-press but not on PATH."
    echo "Add GOPATH/bin to your PATH:  export PATH=\"\$HOME/go/bin:\$PATH\""
  else
    echo "cli-printing-press binary not found."
    echo "Install with:  go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest"
  fi
  return 1 2>/dev/null || exit 1
fi

# Resolve and emit the absolute path the agent must use for every later
# `cli-printing-press` invocation. `export PATH` above only affects this one
# Bash tool call; subsequent calls open a fresh shell and resolve bare
# `cli-printing-press` against the user's default PATH, where a stale global
# can silently shadow the local build. The agent captures this marker and
# substitutes the absolute path into every later invocation.
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"

运行设置契约后，从标准输出中获取 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

去除无关词后，统计剩余标记的数量：

0 个标记 → 重新评分当前项目模式
1 个标记 → 单项评分模式
2 个标记 → 比较模式

步骤 2：解析 CLI 目录

对于每个 CLI 标识符，将其解析为目录路径：

如果标记包含 `/` 或 `.`

将其视为路径（绝对路径或相对路径）。验证目录是否存在。

如果标记是普通名称

按以下顺序尝试这些位置：

$PRESS_LIBRARY/<name>/ — 完全匹配
$PRESS_LIBRARY/<name>-pp-cli/ — 带有 -pp-cli 后缀
如果两者都不存在，使用 Glob 匹配 $PRESS_LIBRARY/<name>-pp-cli*
如果 Glob 恰好匹配一个目录，则使用该目录
如果 Glob 匹配多个目录，使用 AskUserQuestion 显示编号菜单

如果两者都不存在，则扫描当前运行状态和归档状态： 6. 使用 Glob 查找 $PRESS_RUNSTATE/runs/*/state.json 文件 7. 读取每个文件，查找 output_dir 或 working_dir 值中包含该名称的基本名称 8. 如果找到且目录存在，则使用该目录

如果无法解析任何结果，报告错误：“找不到 CLI ‘’。请提供路径或检查名称。”

重新评分当前项目（0 个标记）

使用 Glob 查找所有 $PRESS_CURRENT/*.json 文件
读取每个文件以获取 api_name、state_path 和 working_dir
筛选出 working_dir 在磁盘上确实存在的文件
如果没有找到，则使用 Glob 匹配 $PRESS_LIBRARY/*-pp-cli*，并改用这些目录
如果恰好找到一个 → 自动使用

如果找到多个 → 使用 AskUserQuestion 显示编号菜单：

Multiple CLIs found. Which one to score?
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)

如果没有找到 → 报告：“未找到生成的 CLI。请提供名称或路径。”

步骤 3：查找 Tier 2 评分所需的规范

对于每个已解析的 CLI 目录，查找 OpenAPI 规范：

检查 <cli-dir>/spec.json——生成期间，流水线会将 YAML 规范转换为 JSON
如果未找到，扫描 $PRESS_RUNSTATE/runs/*/state.json 文件，查找与此 CLI 目录匹配的文件。读取其 spec_path 字段。如果该文件在磁盘上存在，则使用它。
如果未找到规范，不带 --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/ 不会得分；解释学习循环方面的差距时，应指出缺少种子或未注册命令，而不是缺少文件。执行证明（verify 矩阵、learnings stats）属于 verify 和 dogfood；评分卡不会运行任何二进制文件。

对比模式

使用两个同时执行的 Bash 工具调用，并行运行两个评分卡命令：

# Call 1:
cli-printing-press scorecard --dir <path1> --spec <spec1> --json

# Call 2:
cli-printing-press scorecard --dir <path2> --spec <spec2> --json

解析两个 JSON 输出。

步骤 5：呈现输出

单项评分表

呈现内容丰富的 Markdown 表格。注意：Tier 1 维度均为 /10。Tier 2 维度中，TypeFidelity 和 DeadCode 为 /5，其余均为 /10。

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 解析失败 → 显示原始输出并报告解析错误

支持 Markdown

登录后评论

基本信息

作者: mvanhorn
仓库: mvanhorn/cli-printing-press
分类: 测试与质量
安装次数: 6,443
GitHub Stars: 4,866

报告问题