printing-press-score

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/printing-press-score

Score generated CLIs against the Steinberger bar. Supports rescoring, scoring by name/path, and comparing two CLIs.

根据Steinberger标准对生成的CLI进行评分。支持重新评分、按名称/路径评分以及两款CLI的对比功能。

Quick Start

快速开始

/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

/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

Prerequisites

前置要求

Go 1.21+ installed

printing-press

binary on PATH (install with

go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest

)

已安装Go 1.21+

PATH中存在

printing-press

二进制文件（通过

go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest

安装）

Step 0: Setup

步骤0：环境配置

Before any other commands, run the setup contract to verify the printing-press binary is on PATH and initialize scope variables:

bash

undefined

在执行其他命令前，运行配置脚本以验证printing-press二进制文件是否在PATH中，并初始化作用域变量：

bash

undefined

min-binary-version: 0.3.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.

当在printing-press仓库内运行时，优先使用本地构建版本。

if [ -x "$_scope_dir/printing-press" ] && [ -d "$_scope_dir/cmd/printing-press" ]; then export PATH="$_scope_dir:$PATH" echo "Using local build: $_scope_dir/printing-press" elif ! command -v printing-press >/dev/null 2>&1; then if [ -x "$HOME/go/bin/printing-press" ]; then echo "printing-press found at ~/go/bin/printing-press but not on PATH." echo "Add GOPATH/bin to your PATH: export PATH="$HOME/go/bin:$PATH"" else echo "printing-press binary not found." echo "Install with: go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest" fi return 1 2>/dev/null || exit 1 fi

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="$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 -->

After running the setup contract, check binary version compatibility. Read the `min-binary-version` field from this skill's YAML frontmatter. Run `printing-press version --json` and parse the version from the output. Compare it to `min-binary-version` using semver rules. If the installed binary is older than the minimum, warn the user: "printing-press binary vX.Y.Z is older than the minimum required vA.B.C. Run `go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest` to update." Continue anyway but surface the warning prominently.

Current-run state is resolved from `$PRESS_RUNSTATE`. Published CLIs are resolved from `$PRESS_LIBRARY`. Archived manuscripts are resolved from `$PRESS_MANUSCRIPTS`.

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

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

<!-- PRESS_SETUP_CONTRACT_END -->

运行配置脚本后，检查二进制版本兼容性。从本技能的YAML前置元数据中读取`min-binary-version`字段。运行`printing-press version --json`并从输出中解析版本号。使用semver规则将其与`min-binary-version`进行对比。如果已安装的二进制版本低于最低要求，向用户发出警告："printing-press binary vX.Y.Z is older than the minimum required vA.B.C. Run `go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest` to update." 仍继续执行操作，但需显著显示该警告。

当前运行状态从`$PRESS_RUNSTATE`获取。已发布的CLI从`$PRESS_LIBRARY`获取。已归档的脚本从`$PRESS_MANUSCRIPTS`获取。

Step 1: Parse Arguments

步骤1：解析参数

Read the user's input after

/printing-press-score

. The input is free-form — interpret intent, don't enforce syntax.

Noise words to strip:

compare

vs

versus

and

against

with

to

After stripping noise words, count the remaining tokens:

0 tokens → Rescore Current mode
1 token → Score Single mode
2 tokens → Compare mode

读取用户在

/printing-press-score

之后的输入。输入为自由格式——需解读用户意图，而非强制遵循语法。

需去除的冗余词汇：

compare

vs

versus

and

against

with

to

去除冗余词汇后，统计剩余的标记数量：

0个标记 → 重新评分当前模式
1个标记 → 单一CLI评分模式
2个标记 → 对比模式

Step 2: Resolve CLI Directories

步骤2：解析CLI目录

For each CLI identifier, resolve it to a directory path:

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

If the token contains

如果标记包含

或

Treat it as a path (absolute or relative). Verify the directory exists.

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

If the token is a plain name

如果标记为纯名称

Try these locations in order:

```
$PRESS_LIBRARY/<name>/
```
— exact match
```
$PRESS_LIBRARY/<name>-pp-cli/
```
— with -pp-cli suffix
If neither exists, Glob
```
$PRESS_LIBRARY/<name>-pp-cli*
```
If exactly one glob match exists and is a directory, use it
If multiple glob matches exist, present a numbered menu using AskUserQuestion

If neither exists, scan current-run and archived state: 6. Use Glob to find

$PRESS_RUNSTATE/runs/*/state.json

files 7. Read each, look for an

output_dir

working_dir

value whose basename contains the name 8. If found and the directory exists, use it

If nothing resolves, report the error: "Could not find CLI '<name>'. Provide a path or check the name."

按以下顺序尝试查找位置：

```
$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 '<name>'。请提供路径或检查名称是否正确。"

Rescore Current (0 tokens)

重新评分当前模式（0个标记）

Use Glob to find all
```
$PRESS_CURRENT/*.json
```
files
Read each to get
```
api_name
```
,
```
state_path
```
, and
```
working_dir
```
Filter to those whose
```
working_dir
```
actually exists on disk
If none are found, Glob
```
$PRESS_LIBRARY/*-pp-cli*
```
and use those directories instead
If exactly one → use it automatically

If multiple → present a numbered menu using 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)

If none found → report: "No generated CLIs found. Provide a name or path."

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

如果有多个条目 → 使用AskUserQuestion展示编号菜单：

找到多个CLI。请选择要评分的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)

如果未找到任何条目 → 报告："未找到生成的CLI。请提供名称或路径。"

Step 3: Find Spec for Tier 2 Scoring

步骤3：查找二级评分的规范文件

For each resolved CLI directory, find the OpenAPI spec:

Check
```
<cli-dir>/spec.json
```
— the pipeline converts YAML specs to JSON during generation
If not found, scan
```
$PRESS_RUNSTATE/runs/*/state.json
```
files for one matching this CLI's directory. Read its
```
spec_path
```
field. If that file exists on disk, use it.
If no spec found, proceed without
--spec
. Note to the user: "No spec found — spec-derived dimensions will be marked N/A and omitted from the denominator. Provide a spec path for full scoring."

针对每个解析出的CLI目录，查找OpenAPI规范文件：

检查
```
<cli-dir>/spec.json
```
—— 生成流水线会在生成过程中将YAML规范转换为JSON格式
如果未找到，扫描
```
$PRESS_RUNSTATE/runs/*/state.json
```
文件以查找与该CLI目录匹配的文件。读取其
```
spec_path
```
字段。如果该文件在磁盘上存在，使用该文件。
如果未找到规范文件，不添加
--spec
参数继续执行。向用户说明："未找到规范文件——基于规范的维度将标记为N/A，且不计入分母。请提供规范路径以获得完整评分。"

Step 4: Run Scorecard

步骤4：运行评分卡

Single Score Mode

单一评分模式

Run the scorecard command:

bash

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

If a spec was found, add

--spec <spec-path>

Parse the JSON output. The structure is:

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

is present, those dimensions should be rendered as

N/A

, not

0/x

, and should be described as omitted from the denominator rather than as fixable CLI defects. For backward compatibility, JSON still encodes the numeric fields as

; consumers must use

unscored_dimensions

to distinguish

N/A

from a real zero.

运行评分卡命令：

bash

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

如果找到规范文件，添加

--spec <spec-path>

参数。

解析JSON输出。输出结构如下：

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仍会将这些数字字段编码为

；使用者必须通过

unscored_dimensions

来区分

N/A

和真实的零分。

Compare Mode

对比模式

Run both scorecard commands in parallel using two simultaneous Bash tool calls:

bash

undefined

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

bash

undefined

Call 1:

调用1：

printing-press scorecard --dir <path1> --spec <spec1> --json

Call 2:

调用2：

printing-press scorecard --dir <path2> --spec <spec2> --json


Parse both JSON outputs.

printing-press scorecard --dir <path2> --spec <spec2> --json


解析两个JSON输出。

Step 5: Render Output

步骤5：渲染输出

Single Score Table

单一评分表格

Render a rich markdown table. Note: Tier 1 dimensions are all /10. Tier 2 dimensions are /10 except TypeFidelity and DeadCode which are /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

is non-empty, list the gaps:

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

unscored_dimensions

is non-empty, add a note after the table:

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

渲染一个丰富的Markdown表格。注意：一级维度满分均为10分。二级维度除TypeFidelity和DeadCode满分为5分外，其余均为10分。

评分卡：<api_name>

基础架构（一级维度）
| 维度名称       | 得分  |
|----------------|-------|
| 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  |

领域正确性（二级维度）
| 维度名称                  | 得分  |
|---------------------------|-------|
| 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   |

**总分：72/100 —— 等级B**

如果

gap_report

不为空，列出差距：

差距：
- <差距1>
- <差距2>

如果

unscored_dimensions

不为空，在表格后添加说明：

说明：path_validity、auth_protocol未进行评分，且不计入分母。请提供规范路径以获得完整评分。

Compare Table

对比表格

Render a side-by-side table with a delta column. Show the first CLI name and second CLI name as column headers. Calculate delta as (CLI 1 score - CLI 2 score). Show

+N

for positive,

-N

for negative,

—

for zero.

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名称和第二个CLI名称作为列标题。差值计算为（CLI1得分 - CLI2得分）。正数显示

+N

，负数显示

-N

，零显示

—

。

评分卡对比：<name1> vs <name2>

基础架构（一级维度）
| 维度名称       | <name1> | <name2> | 差值 |
|----------------|---------|---------|-------|
| Output Modes   | 8/10    | 5/10    | +3    |
| Auth           | 7/10    | 7/10    | —     |
| ...            |         |         |       |

领域正确性（二级维度）
| 维度名称                  | <name1> | <name2> | 差值 |
|---------------------------|---------|---------|-------|
| Path Validity             | 9/10    | 6/10    | +3    |
| ...                       |         |         |       |

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

Error Handling

错误处理

If the printing-press binary is not on PATH → show install instructions:

go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest

If the scorecard command fails → report the error with the full stderr output
If a CLI directory doesn't exist → report which name couldn't be resolved
If JSON parsing fails → show the raw output and report the parsing error

如果printing-press二进制文件不在PATH中 → 显示安装说明：

go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest

如果评分卡命令执行失败 → 报告错误并显示完整的stderr输出
如果CLI目录不存在 → 报告无法解析的名称
如果JSON解析失败 → 显示原始输出并报告解析错误

printing-press-score

Original

Translation

/printing-press-score

/printing-press-score

Quick Start

快速开始

Prerequisites

前置要求

Step 0: Setup

步骤0：环境配置

min-binary-version: 0.3.0

min-binary-version: 0.3.0

Derive scope first — needed for local build detection

先推导作用域——本地构建检测需要用到

Prefer local build when running from inside the printing-press repo.

当在printing-press仓库内运行时，优先使用本地构建版本。

Step 1: Parse Arguments

步骤1：解析参数

Step 2: Resolve CLI Directories

步骤2：解析CLI目录

If the token contains / or .

如果标记包含/或.

If the token is a plain name

如果标记为纯名称

Rescore Current (0 tokens)

重新评分当前模式（0个标记）

Step 3: Find Spec for Tier 2 Scoring

步骤3：查找二级评分的规范文件

Step 4: Run Scorecard

步骤4：运行评分卡

Single Score Mode

单一评分模式

Compare Mode

对比模式

Call 1:

调用1：

Call 2:

调用2：

Step 5: Render Output

步骤5：渲染输出

Single Score Table

单一评分表格

Compare Table

对比表格

Error Handling

错误处理

If the token contains
`/`
or
`.`

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