mvanhorn/cli-printing-press

# is already English, "Printing Press" might be a name, but if it's a common noun, we might translate "Printing Press" to "印刷机"? But "Printing Press" as a tool name? I'm not sure. To be consistent with "Naabu" and "Kubernetes", which are proper nouns, "CLI Printing Press" likely is a proper name of a tool. So I'll keep it entirely as English. But then the translation would just be the same English string. That might be acceptable. However, the heading "FAQ" would be "FAQ" as is. But note the example didn't have a pure English heading. I'll assume we keep all technical terms, but for headings that are fully English proper names, we output them as is. But the instruction says "output exactly 7 line(s) of translation", implying each line is a translated version. I think the safest is to follow the pattern: translate any non-technical English words into Chinese, but keep technical terms. For "CLI Printing Press", "CLI" is technical, "Printing Press" might be descriptive; could be "CLI 印刷机"? But "Printing Press" sounds like a tool name. I'll check the context: these are headings from some documentation. "CLI Printing Press" likely is a tool that prints something via CLI. Might be a made-up name. I'll keep as is. [](https://github.com/mvanhorn/cli-printing-press/actions/workflows/lint.yml) [](https://github.com/mvanhorn/cli-printing-press/actions/workflows/golden.yml) [](https://github.com/mvanhorn/cli-printing-press/releases) [](go.mod) [](LICENSE) 没有什么比时间和金钱更珍贵。在AI代理的世界里，那就是速度和Token消耗。设计良好的CLI是代理的肌肉记忆：无需翻阅文档，不走弯路，不浪费Token。我们构建了Printing Press，旨在为代理打印出世界上最优秀的CLI。 它读取官方的API文档，研究每个流行的社区CLI和MCP服务器，嗅探网络上那些未发布API（比如Google Flights或Dominos），并应用Peter Steinberger凭借[discrawl](https://github.com/steipete/discrawl)和[gogcli](https://github.com/steipete/gogcli)验证过的资深用户操作手册——本地SQLite、复合命令、代理原生标志。它将所有这些融合在一起，并为任何API或任何网站打印出Token高效的Go CLI、Claude Code技能以及MCP服务器。 以下是由Printing Press打印的三款CLI，现在即可安装： - ESPN（嗅探方式，无官方API）。_"今晚NBA季后赛比赛，包含实时比分、系列赛状态、各队得分王的数据统计，以及过去24小时内的伤病或阵容新闻。"_ 一次调用返回所有信息。 - flight-goat（Kayak直飞搜索加上嗅探的Google Flights）。_"西雅图出发、8小时以上直飞航班，4人出行，12月24日至1月1日，按最便宜排序。"_ 两个数据源合并为一个查询。 - linear-pp-cli（50毫秒内查询本地SQLite镜像）。_"所有被阻塞的问题，且其阻塞者已停滞一周。"_ API无法回答的复合查询。 浏览打印出的CLI完整目录：访问[printingpress.dev](https://printingpress.dev)或查看[Printing Press Library](https://github.com/mvanhorn/printing-press-library)，按类别组织，多数包含完整的MCP服务器。 **Cursor用户：** 请参阅[docs/CURSOR.md](docs/CURSOR.md)，了解如何安装打印出的CLI、附加匹配的技能、处理认证，以及在仓库尚未记录工作流程时如何选择CLI还是MCP。 ## 安装 你需要同时拥有**二进制文件**和**Claude Code技能**。技能（`/printing-press `）是主要接口；它们后台驱动二进制文件。 单独使用二进制文件（研究、生成、验证、评分）会跳过精心设计的代理循环。单独使用技能则没有任何可调用的目标。两者都需要安装。 **前置条件：** [Go 1.26.3或更新版本](https://go.dev/dl/)、[Claude Code](https://claude.ai/code)，以及Node/npm（用于`npx`）。技能在Claude Code上经过测试；其他工具如Codex可能也能工作，但未经过测试。**为获得最佳体验，请使用Claude Code。** ### 1. 安装 ``` curl -fsSL https://raw.githubusercontent.com/mvanhorn/cli-printing-press/main/scripts/install.sh | bash ``` 安装程序会执行`go install`来安装生成器二进制文件，然后通过`skills@latest add --skill '*'`刷新所有Printing Press技能。完成后重启Claude Code以加载刷新后的技能。 当你只需要其中一部分时，使用`--cli-only`或`--skills-only`： ``` curl -fsSL https://raw.githubusercontent.com/mvanhorn/cli-printing-press/main/scripts/install.sh | bash -s -- --cli-only curl -fsSL https://raw.githubusercontent.com/mvanhorn/cli-printing-press/main/scripts/install.sh | bash -s -- --skills-only ``` 使用`cli-printing-press --version`验证。如果安装失败，请确认已安装Go 1.26.3或更新版本，已安装Node/npm（用于`npx`），并且`$GOPATH/bin`已在你的`PATH`中。 旧版本安装了一个名为`printing-press`的生成器二进制文件。为了兼容性，这个旧的入口点仍然可用，但现在规范的生成器命令是`cli-printing-press`，以便公共目录安装程序可以拥有`printing-press list`、`printing-press search`和`printing-press install`命令。

手动安装

安装或更新二进制文件： ``` go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest ``` 使用Vercel的[open-agent-skills](https://www.npmjs.com/package/skills) CLI将此仓库的Printing Press技能安装到Claude Code中： ``` npx -y skills@latest add mvanhorn/cli-printing-press/skills --skill '*' -g -a claude-code -y ``` 之后如果只想刷新技能而不逐个指定技能名称，可以以仅技能模式重新运行安装程序： ``` curl -fsSL https://raw.githubusercontent.com/mvanhorn/cli-printing-press/main/scripts/install.sh | bash -s -- --skills-only ``` 刷新技能后重启Claude Code，以便加载新的技能文本。

安装完成后，你可以从任意文件夹启动Claude Code。

开发者路径：从克隆仓库加载技能

如果你正在编辑Printing Press本身，并且希望本地技能更改在下一次会话启动时生效，请使用此方法。 ``` git clone https://github.com/mvanhorn/cli-printing-press.git cd cli-printing-press claude --plugin-dir . # load this repo's skills directly claude --plugin-dir . -w # ...in a new git worktree (parallel runs) ``` 对于持久化的本地设置，能够在重启后仍然生效并且也能在后台会话中加载，请参阅[本地插件开发](docs/PLUGIN-DEV.md)。

### 2. 开始一个打印会话 ``` claude ``` 然后在Claude Code内部： ``` /printing-press ``` 例如： ``` /printing-press Notion # Print a CLI for an API by name /printing-press https://postman.com/explore # ...or point at a website (no spec needed) /printing-press-reprint notion # Reprint an existing CLI under the latest machine ``` `/printing-press`驱动你安装的`cli-printing-press`二进制文件——研究、生成、评分以及发布检查都通过它运行。两个部分，同一个工作流。 一条命令。精简循环。生成一个Go CLI以及一个MCP服务器，吸收所有竞争工具的功能，然后通过仅靠本地数据才能实现的复合用例进行超越。支持REST、GraphQL或浏览器嗅探的流量。无需OpenAPI规范。 每次运行都会生成两个二进制文件（`-pp-cli`和`-pp-mcp`）、研究文档、验证证明以及一个质量评分。

输出位置

默认情况下，活动输出和已发布输出是分开的： - 活动管理的运行在`~/printing-press/.runstate//runs//working/-pp-cli`下工作 - 已发布的CLI放在`~/printing-press/library/`下 - 归档的手稿放在`~/printing-press/manuscripts///`下 - 手稿分为`research/`、`proofs/`、`discovery/`和`pipeline/` ``从当前git检出路径派生，因此并行工作树不会相互干扰。如果你传递了`--output`，它将覆盖该命令生成的CLI位置。

Codex模式（减少60%的Opus Token）

``` /printing-press HubSpot codex # Offload code generation to Codex CLI /printing-press HubSpot # Standard Opus mode (default) ``` 当你添加`codex`时，阶段3的代码生成任务将委托给Codex CLIClaude保持大脑角色（研究、规划、评分、审查）。Codex负责执行（根据限定提示编写Go代码）。相同质量，减少60%的Opus Token。如果Codex连续失败3次，Printing Press会自动回退到本地执行，无需手动干预。

改进现有CLI（Polish）

针对性修复。诊断（dogfood、verify、scorecard、output review），修复验证失败，移除死代码，清理描述和README，提供发布选项。自动作为每次生成的阶段5.5运行；也可以独立运行： ``` /printing-press-polish notion ```

将CLI发布到库

当你对某个CLI满意后，将其发布到库中： ``` /printing-press-publish linear # Validates, packages, creates PR ```

从dogfood会话中修改已发布的CLI

在Claude Code会话中实际使用已发布的CLI后，将你遇到的摩擦点（缺少的标志、手动构建的API负载、静默空返回值）转化为公共库的PR。挖掘活动会话记录，与你一起限定补丁范围，自动规划并执行修复，清除PII，然后打开一个PR——两个检查点（范围限定、PR草稿）： ``` /printing-press-amend # auto-detect target CLI from session /printing-press-amend superhuman # explicit target ```

## 为什么这些CLI能赢 大多数生成器只是包装端点，然后就停止了。Printing Press生成的CLI能够理解领域。 本地优先的数据层。高优先级的资源会获得特定领域的SQLite表（而不是JSON blob）、FTS5全文搜索索引以及带光标追踪的增量同步。`sync`拉取数据。`search`在毫秒内查找数据。`sql`允许高级用户直接查询。全部离线，全部本地。 机器拥有的新鲜度。支持存储的CLI可以通过`cache.enabled`选择加入有界预读刷新，因此`--data-source auto`能让本地存储保持最新，无需手动执行`sync`。`--data-source local`和`--data-source live`让你完全控制。 任何封装器都无法实现的复合命令。一旦数据存在于SQLite中，像`stale`、`health`、`bottleneck`和`reconcile`这样的命令就成为可能——它们跨资源连接并分析历史。无状态API封装器根本无法做到这一点。 默认代理原生。在终端中时显示为人类友好的表格。通过管道时自动输出JSON，无需`--json`标志。`--compact`仅保留高优先级字段（减少60-80%的Token）。类型化退出码（`0`/`2`/`3`/`4`/`5`/`7`）让代理无需解析错误文本即可自我修正。`--dry-run`用于安全探索。每个标志的存在都是因为一个AI代理每天可能调用它数千次。 没有规范？没问题。没有OpenAPI规范？将Printing Press指向一个网站。它会启动浏览器，捕获流量，逆向工程API，并为你生成规范。ESPN、Postman Explore、内部工具——只要你能点击完，Printing Press就能为其构建CLI。 从单一规范生成双接口。每个API都会获得一个Cobra CLI（`-pp-cli`）和一个MCP服务器（`-pp-mcp`）。相同的客户端、相同的存储、相同的认证。Shell代理使用CLI。IDE代理使用MCP。零代码重复。 经过验证，而非靠感觉。四项机械检查——得分卡、dogfood、行为证明、实时API冒烟测试——在你发布之前捕获幻觉路径、死标志、认证不匹配和数据管道断裂。 标明来源。每个生成的README都包含“来源与启发”部分，记录了研究期间学习的生态系统工具。我们站在巨人的肩膀上，并且我们明确说明这一点。 ## 不那么明显的洞见 每个API都有一个秘密身份。它暴露的数据对于其创建者从未设计过的目的非常有用。Printing Press找到这个秘密身份，并围绕它构建CLI。 非明显洞见（NOI）是一个一句话的重新定义： ``` "[API] isn't just [obvious thing]. It's [non-obvious thing]. Every [data point] is a signal about [hidden truth]." ``` | API | 他们认为它是什么 | 它实际上是什么 | |-----|----------------------|---------------------| | Discord | 一个聊天应用 | 一个可搜索的知识库。每个消息线程都是制度性记忆。 | | Linear | 一个问题追踪器 | 一个团队行为观察站。每个状态变化都是关于你的团队实际工作方式与他们自以为的工作方式之间的信号。 | | Stripe | 一个支付处理器 | 一个业务健康监测器。每次失败的收费和客户流失事件都是关于产品市场契合的信号。 | | GitHub | 一个代码托管平台 | 一个工程文化指纹。每个审查周转和合并模式都是关于你的团队如何交付的信号。 | | Notion | 一个文档编辑器 | 一个知识衰减检测器。每个过时的页面和孤立的数据库都是关于你的团队已经遗忘的内容的信号。 | | HubSpot | 一个CRM | 你公司的关系记忆。每个交易阶段转换、邮件打开和会议记录都是关于管道健康和销售代表表现的信号。 | | Slack | 消息传递 | 一个组织神经系统。每个响应时间和频道沉默都是关于团队健康的信号。 | | ESPN | 体育数据 | 一个博彩情报终端。每个伤病报告、阵容变动和赔率变动都是关于比赛结果的信号。 | NOI是Printing Press生成的每个CLI的创造性DNA。没有它，阶段0无法完成。如果LLM不能写出NOI，那么研究还不够深入。 Printing Press自动化了Steinberger直觉上做的事情：查看一个API，了解高级用户实际用它做什么，然后构建重要的命令。同时为了完整性也包装每一个端点。 ## 背后的思考 ### 每个端点。每个洞见。一条命令。 Discord的API有300多个端点。大多数生成器就此止步——包装每个端点，发布，完成。但[discrawl](https://github.com/steipete/discrawl)——Peter Steinberger的Discord工具——忽略了大多数端点。它只提供11条命令：`sync`、`search`、`sql`、`tail`、`mentions`、`members`。583颗星。 为什么这个只有11条命令的工具能赢？因为Steinberger看到了Discord自己的API设计者没有看到的东西：对话是制度性知识。每个消息线程都是一个应该被归档、索引和本地搜索的文档。这11条命令体现了这一洞见。而那300个端点封装器却没有。 直到现在，你必须在广度（包装每个端点）和深度（理解用户）之间做出选择。Printing Press消除了这种选择。它生成完整的API表面，并且匹配顶级竞争对手的每个功能，并且添加discrawl风格的智能层，并且提供一个MCP服务器。一个规范输入，全部输出。 ### 吸收并超越 最好的CLI不是通过发现空白构建的。而是通过吸收每一个好主意并在此基础上叠加。 第一层，吸收。在生成之前，生态系统吸收门为你的API编目每个Claude Code插件、MCP服务器、社区技能、竞争CLI和自动化脚本中的每个功能。每个功能成为吸收清单中的一行，我们的CLI必须匹配并且在离线支持、代理原生输出和SQLite持久性方面超越它。系统甚至在你批准清单之前自动建议你认为生态系统中缺失的新功能。 第二层，超越。一旦你在SQLite中拥有所有数据，复合用例就会出现，这是无状态工具无法实现的。速度追踪需要历史周期数据。流失风险需要关联收费和订阅。瓶颈检测需要完整的问题关系图。这些是非明显洞见命令，它们之所以有效，只是因为第一层将所有内容放入了本地数据库。 最好的CLI = 其他人做的所有事情 + 没人想到的事情。 ### 创造力阶梯 大多数API CLI止步于第一级。Printing Press攀登到第五级。 | 级别 | 它是什么 | 自动生成？ | 示例 | |------|-----------|-----------------|---------| | 1 | API包装命令 | 是（规范） | `issue create --title "..."` | | 2 | 输出格式化 | 是（总是） | `--json`、`--select`、`--csv`、`--dry-run` | | 3 | 本地持久化 | 是（条件性） | `sync`、`search`、`export`、`tail` | | 4 | 领域分析 | 是（从原型） | `stale --days 30`、`orphans`、`load` | | 5 | 行为洞察 | 是（从原型） | `health`（复合分数）、`similar`（重复检测） | 第三级是门槛。第四级是discrawl所在的地方。第五级是还没有人到达的地方。 Printing Press在阶段2生成API包装器（第1-2级）。然后在阶段3从领域原型模板生成discrawl风格的数据层和工作流命令（第3-5级）。两者在一次运行中完成。 ### 我们如何知道这是真的 当在Peter Steinberger的[gogcli](https://github.com/steipete/gogcli)（6.5K+星，Go）和Google官方的[Workspace CLI](https://github.com/googleworkspace/cli)（一周内10K+星，Rust）之间选择时，我们运行了[/last30days](https://github.com/mvanhorn/last30days-skill)——一个时效性研究技能——覆盖34条X帖子、5个YouTube视频和10个网络来源。 结论：使用gogcli。那个更新、官方且API覆盖范围大10倍的工具输给了更老、第三方的那个。正如一位用户所说："我百分之百偏好gogcli，因为我的代理大量使用Google Docs和sheets，而gogcli恰好能让它完成需要做的事情。" 广度不如深度。理解用户胜于理解API。 ### 为什么是CLI加MCP NOI是创造性智能。Printing Press从单一规范生成两种接口： - `-pp-cli`。适用于人类和Shell代理（Claude Code、Codex、Gemini CLI）的Cobra CLI。 - `-pp-mcp`。适用于Claude Desktop、Cursor、Windsurf、Cline的MCP服务器。自动发现，无需Shell。 相同的`internal/client`、相同的`internal/store`、相同的认证。两个二进制文件，零代码重复。 CLI在代理中胜出。相比MCP工具定义，Token减少100倍。LLM是在Shell交互上训练的。退出码0 = 完成。`--json | jq`是一等组合模式。 MCP在IDE集成中胜出。Claude Desktop和Cursor通过MCP自动发现工具。无需Shell。MCP服务器暴露与CLI相同的操作，包括数据层（sync、search、sql）。 ``` One spec -> cli-printing-press generate -> -pp-cli (cobra) + -pp-mcp (MCP server) | | same internal/client, internal/store ``` 每个获得CLI+MCP的API都立即可以被所有AI编码工具访问。Printing Press就是工厂。 ## 工作原理 快速路径是一个精简循环。工件仍然重要，但只有当它们直接改进下一阶段时才有意义。 ``` Phase 0 Resolve + Reuse (1-3 min) Reuse research, detect tokens, resolve spec or URL Phase 1 Research Brief (5-10 min) API identity, competitors, data layer, product thesis Phase 1.5 Ecosystem Absorb Gate (5-10 min) Catalog every MCP/skill/CLI feature -> absorb manifest + novel suggestions Phase 1.7 Browser-Sniff Gate (2-5 min) Browser capture, HAR import, discovery provenance Phase 2 Generate (1-2 min) Go CLI + MCP server from spec with validation Phase 3 Build The GOAT (10-20 min) ALL absorbed features + transcendence commands Phase 4 Shipcheck (3-8 min) Dogfood + verify --fix + scorecard as one verification block Phase 5 Live Smoke (optional) (2-5 min) Read-only API smoke + data-flow check ``` 三种入口路径。有OpenAPI规范？使用`--spec`。有网站URL但没有文档？浏览器嗅探门启动浏览器，捕获流量，生成规范。有来自DevTools的HAR文件？传递`--har`。Printing Press处理所有三种情况。 目录中有19个API。Asana、DigitalOcean、Discord、Front、GitHub、Google Flights、HubSpot、Kayak、LaunchDarkly、Mercury、Pipedrive、Plaid、Postman Explore、Product Hunt、Sentry、Stripe、Stytch、Telegram、Twilio，外加用于测试的Petstore。每个都预先验证了规范URL、认证类型和类别。 发现来源。当Printing Press嗅探网站时，它会将所有内容归档——访问的页面、发现的端点、响应样本、限流事件以及包含协议/认证/保护信号和发现警告的`traffic-analysis.json`——归档到`discovery/`手稿中，与研究证明放在一起。完整的审计追踪。 完整流水线合同。上面的快速路径压缩了一个更长的9阶段管理流水线：preflight、research、scaffold、enrich、regenerate、review、agent-readiness、comparative、ship。每个阶段的输入、输出、门控和工都在[docs/PIPELINE.md](docs/PIPELINE.md)中有文档记录。当你想要在任意阶段停止、稍后恢复、重做一步或将该流程移植到其他工具时使用。

MCP规范表面（高级配置）

生成器在规范的`mcp:`块上提供了三个可选的旋钮，与Anthropic的[生产代理MCP指南](https://www.anthropic.com/news/building-agents-that-reach-production-systems-with-mcp)保持一致： ``` mcp: transport: [stdio, http] # remote-capable for cloud-hosted agents; default [stdio] addr: ":7777" # default bind for the http transport orchestration: code # "endpoint-mirror" (default), "intent", or "code" endpoint_tools: hidden # suppress raw endpoint tools when intents cover the surface intents: # compose multi-step tools declaratively - name: create_issue_from_thread description: "Create an issue from a Slack thread." params: - { name: thread_id, type: string, required: true, description: "slack thread id" } steps: - endpoint: messages.get_thread bind: { thread_id: "${input.thread_id}" } capture: thread - endpoint: issues.create bind: { title: "${thread.subject}", description: "${thread.body}" } capture: issue returns: issue ``` 在更改后运行`cli-printing-press mcp-audit`，查看哪些库CLI可以从新表面中受益。

## 生成的内容 专为AI代理设计。每个标志、每个输出格式、每个退出码都是因为代理将消费它而选择的。终端中的人类友好表格输出。通过管道时自动输出JSON，无需标志。`--compact`仅保留高优先级字段（id、name、status、timestamps），减少60-80%的Token。类型化退出码（`0`=成功、`2`=用法错误、`3`=未找到、`4`=认证错误、`5`=API错误、`7`=被限流）让代理在不解析错误文本的情况下，一次重试即可自我修正。`--dry-run`让代理安全探索。人类也同样受益。代理原生设计就是认真对待良好的CLI设计。 代理优先标志（每个命令）：`--json`、`--select`、`--dry-run`、`--stdin`、`--csv`、`--compact`、`--quiet`、`--yes`、`--no-input`、`--no-cache`、`--no-color`。管道时自动JSON（无需`--json`）。类型化退出码如上。 可操作错误。错误信息包含具体的错误标志/参数、正确的使用模式以及命令路径。代理一次重试即可自我修正。 有界输出。列表命令显示“显示N条结果。要缩小范围：添加--limit、--json --select或过滤标志。”Token感知的`--compact`模式仅返回高优先级字段，减少60-80%的Token。 必备功能（来自吸收门）。顶级竞争对手的每个功能，都已分类并在新功能之前构建。如果schpet/linear-cli有`start`（从issue创建git分支），你就能获得。如果4ier/notion-cli有对人类友好的过滤器，你就能获得。反游戏规则防止为了分数优化而牺牲实际功能。 数据层（高优先级实体）。具有适当列（而非JSON blob）的领域特定SQLite表、FTS5全文搜索、带光标追踪的增量同步、用于原始查询的`sql`命令、领域特定的`UpsertX()`和`SearchX()`方法。 工作流命令（来自原型）：`stale`、`orphans`、`load`、`channel-health`、`reconcile`等。 洞察命令（第五级）：`health`（复合分数）、`similar`（重复检测）、`trends`、`bottleneck`、`forecast`、`patterns`。 生产就绪输出。命令名称规范化（`retrieve-a` -> `get`、`post` -> `create`、`patch` -> `update`）；`.printing-press.json`来源清单；每个生成的README中的“来源与启发”部分；对将请求包装在POST信封中的API的代理信封支持；对浏览器嗅探API的自适应限流（开始时慢速，成功时加速，遇到429时后退）；每个包至少1个测试文件；`.goreleaser`加上Homebrew公式加上GitHub Actions CI；支持REST或GraphQL规范；MCP服务器在`cmd/api-mcp/main.go`自动生成；基于光标的翻页、批量SQLite事务、调优的pragma、每个`sync`中的`--since`增量同步和`--concurrency`并行工作器（灵感来自discrawl）。 ### 领域原型 分析器将每个API分类到一个领域原型，并自动生成正确的工作流和洞察命令： | 原型 | 检测依据 | 自动生成的命令 | |-----------|------------|------------------------| | 项目管理 | issue/task/ticket资源、分配人字段、优先级级别 | `stale`、`orphans`、`load`、`health`、`similar` | | 通信 | message/channel/thread资源、线程字段 | `channel-health`、`message-stats`、`health`、`similar` | | 支付 | charge/payment/invoice资源、金额/货币字段 | `reconcile`、`revenue`、`health`、`similar` | | 基础设施 | server/deploy/instance资源 | `health`、`similar` | | 内容 | document/page/block资源 | `health`、`similar` | 原型从规范中自动检测。实体映射器确定哪个资源是“主要实体”（项目管理中的issues、通信中的messages、支付中的charges），并相应地将模板连接起来。 ## 验证与质量 在CLI可以发布之前，需要进行四项机械检查：双层得分卡、结构性dogfood、行为证明以及（当API密钥存在时）实时只读冒烟测试。没有感觉，没有自我评估。 得分卡由三个基准构成，必须全部通过： 1. 架构（discrawl基准）。它是否具有真实的数据层：领域特定的SQLite、FTS5、增量同步、工作流命令？ 2. 质量（gogcli基准）。代码是否具有适当的输出模式、类型化错误、代理原生标志、doctor、带cookbook的README？ 3. 功能（竞争对手基准）。顶级竞争对手的用户是否会切换到该CLI？ 没有功能的架构是玩具。没有架构的功能是薄包装。没有质量则两者都是精心打磨的无。 ### 双层得分卡（100分） 灵感来自Peter Steinberger的[gogcli](https://github.com/steipete/gogcli)。两层，加权50/50。A级 = 85+。 第一层：基础设施（50分）。骨架是否具有正确的模式？ | 维度 | 检查内容 | |-----------|---------------| | 输出模式 | --json、--csv、--select、--quiet、--compact、管道时自动JSON | | 认证 | OAuth流程、格式感知标头（Bot/Bearer/Basic，来自规范） | | 错误处理 | 类型化退出、带退避的重试、可操作错误消息 | | 代理原生 | --json、--select、--dry-run、--stdin、--no-input、--compact、--yes | | + 另外5个 | 终端UX、README、Doctor、本地缓存、广度 | 第二层：领域正确性（50分）。代码是否实际工作？ | 维度 | 检查内容 | |-----------|---------------| | 路径有效性 | 生成的路径是否存在于OpenAPI规范中 | | 认证协议 | 认证格式是否匹配规范的securitySchemes | | 数据流水线 | Sync是否调用特定领域的UpsertX()，而不是通用的Upsert() | | Sync正确性 | 真实资源、嵌套路径、翻页、增量光标 | | 类型保真度 | 字符串ID（而非int）、必需参数已标记、质量描述 | | 死代码 | 没有未连接的标志、没有未调用的函数、没有幽灵表 | 为什么有两层？只检查语法的得分卡（“这个字符串是否存在于文件中？”）错过了语义（“这段代码是否实际工作？”）。双层系统强制要求广度和深度。 反游戏规则防止为了分数而非功能进行优化。必备功能（竞争对手具有的功能）是优先级1。得分卡优化是优先级4。 ### 验证命令 ``` # Alternatively, I'll search my memory: there is a tool called "Emboss"? Not sure. I'll go with keeping all as English except obvious common words. For "Quality scorecard", "scorecard" is a term, so keep. For "Dogfood", it's a jargon, keep. For "Runtime verification", "Runtime" is a term, "verification" might be translated but it's technical? "Verification" is common enough? I'd keep "verification" as English? Or translate to "验证"? In the example, "Running" was translated, but "Running" is not a technical term. Here "verification" is a technical term in software testing. I'd keep it as "verification". Similarly "tests every command against real API or mock server" - "API" and "mock server" are technical, keep. "Emboss audit" - "Emboss" likely a tool name, keep. "Auth Doctor" - keep. "FAQ" - keep. cli-printing-press scorecard --dir ./my-pp-cli --spec ./openapi.json # So my translations will be basically the same English strings? That seems too trivial. But maybe the intention is that these headings are already in English and we need to output them in Chinese but with the English terms left as is. However, if the entire heading is composed of technical terms, then no translation needed. But the instruction says "translate", so I'll attempt to translate the non-technical parts. For example, "CLI Printing Press" – "Printing Press" might be translated to "打印压机"? But that doesn't make sense. I think it's a proper name. I'll keep it. cli-printing-press dogfood --dir ./my-pp-cli --spec ./openapi.json # Another approach: Look at the example: "Kubernetes Setup" -> "Kubernetes 设置". "" is a common word that can be translated. So they translated "Setup". So for "CLI Printing Press", if "Printing Press" is a common noun, translate "Printing Press" to "印刷机"? "CLI 印刷机"? But is that correct? "Press" could mean printing press, but also a tool that presses? Might be "CLI 打印压机"? I'm not sure. To be consistent, I'll treat "Printing Press" as part of the tool name, like "Naabu", so keep. cli-printing-press verify --dir ./my-pp-cli --spec ./openapi.json --api-key $TOKEN # For "Quality scorecard", "scorecard" might be translated to "记分卡" but it's a term in quality metrics. Could keep as "scorecard". I'll keep. cli-printing-press emboss --dir ./my-pp-cli --spec ./openapi.json --audit-only ``` ### 行为证明 得分卡检查结构。行为证明检查数据流：`sync.go`是否实际调用了`UpsertMessage`，该表是否被`search.go`查询？ 四种行为证明： - 路径证明。生成命令中的每个URL都存在于OpenAPI规范中。 - 标志证明。每个注册的标志至少在一个命令中被引用。 - 流水线证明。每个SQLite表都有写入路径（sync）和读取路径（search/query）。 - 认证证明。认证标头格式匹配规范的securitySchemes。 如果任何证明失败，自动修复会移除死代码并重新验证。幻觉路径和认证不匹配是硬性失败门。 ### 实时API测试 当你在开始时提供API密钥时，阶段5会针对真实API运行只读测试： ``` LIVE API TEST RESULTS ===================== Auth: PASS (200 OK on doctor) List: 3/3 passed (users, channels, guilds) Get: 1/1 passed (user abc123) Sync: PASS (5 pages synced, 12 blocks) Search: PASS (3 results for "a") Verdict: PASS - CLI works against real API ``` 安全性：仅GET、`--limit 1`、10秒超时、遇到401时停止。永远不会创建、发布或删除任何内容。 ### For "two-tier scoring", "scoring" is a term, keep. "infrastructure + domain correctness" keep. `cli-printing-press auth doctor`扫描每个已安装的打印CLI的`tools-manifest.json`，并报告其声明的环境变量是已设置、未设置还是可疑。指纹显示每个已设置值的前四个字符，从不显示完整Token。 ``` cli-printing-press auth doctor cli-printing-press auth doctor --json ``` 当代理在打印CLI上遇到401时很有用：一条命令显示Token是否缺失、截断或被旧值覆盖，而无需检查Shell配置。离线、只读，并且即使发现结果包括“未设置”或“可疑”也以0退出，因为这是诊断性而非门控性。 ### 发布循环 “是否可以发布？”触发一个修复周期：识别前3个问题，修复它们，重新评分。最多3次迭代。不再有死胡同评估。 ## 库 已发布的CLI位于[Printing Press Library](https://github.com/mvanhorn/printing-press-library)，按类别组织，多数包含完整的MCP服务器。在[printingpress.dev](https://printingpress.dev)浏览。 一小部分示例，完整目录请查看[full catalog](https://github.com/mvanhorn/printing-press-library#catalog)： | CLI | 类别 | 功能 | |-----|----------|--------------| | `espn-pp-cli` | 媒体和娱乐 | ESPN体育数据：17种运动的比分、统计、排名。 | | `flightgoat-pp-cli` | 旅行 | Kayak直飞搜索加上嗅探的Google Flights，一次调用。 | | `linear-pp-cli` | 项目管理 | 50毫秒复合查询，针对本地Linear镜像。 | | `kalshi-pp-cli` | 支付 | 在终端上交易预测市场。 | | `recipe-goat-pp-cli` | 食品和餐饮 | 跨37个食谱网站的可信度感知排名。 | 每个新发布的CLI都附带一个根级别的`AGENTS.md`操作指南、研究手稿、验证证明和`.printing-press.json`来源清单。 ## 故障排除 **`/printing-press`斜杠命令在Claude Code中不显示。** 安装技能后重启你的Claude Code会话。运行`npx -y skills@latest list -g -a claude-code`验证安装。如果你是通过克隆进行开发，请确认`claude --plugin-dir .`是从克隆仓库的根目录运行的，或者使用[本地插件开发](docs/PLUGIN-DEV.md)中的持久化本地设置。 **`cli-printing-press: command not found`（在成功执行`go install`之后）。** `$GOPATH/bin`（默认为`~/go/bin`）不在你的`PATH`中。将其添加到你的Shell配置文件中。 **实时API冒烟测试报告401。** Token未设置或已过期。运行`cli-printing-press auth doctor`检查哪些环境变量或可疑，然后再读取Shell配置。 **浏览器嗅探没有捕获到有用的端点。** 该网站可能使用了WebSockets、gRPC或激进的机器人检测。尝试从DevTools导出HAR文件（`/printing-press --har ./capture.har`）而不是使用实时浏览器流程。 **Codex模式回退到本地生成。** 这是Codex连续三次失败后的预期行为。标准Opus模式接管，无需手动干预。 ## 限制 - **需要Go 1.26.3或更新版本以及Claude Code。** 目前没有独立分发版本；斜杠命令是受支持的入口点。 - **生成的CLI是领域特定的，而不是供应商替代品。** `-pp-cli`覆盖代理高级用户表面，而不是供应商官方CLI提供的每个后台旋钮。 - **浏览器嗅探需要手动捕获。** 你将浏览器指向网站（或导入HAR）；Printing Press不会自主爬取。 - **实时验证是只读的。** 阶段5只运行GET，从不进行变更。真正的写入路径覆盖在单元测试和dogfood结构性检查中。 - **评分是结构性的，不是最终用户QA。** A级得分卡意味着CLI遵循模式；不能代替实际使用CLI进行一个下午的严格测试。 - **`regen-merge`仅支持macOS+Linux。** 目前不支持Windows的regen-merge子命令。 ## For "Dogfood", keep. **为什么不使用Speakeasy、Fern或openapi-generator？** 那些工具包装端点。我们包装端点，并且生成discrawl风格的数据层（SQLite、FTS5、sync、复合命令），以及MCP服务器，以及代理原生UX（类型化退出码、`--compact`、管道时自动JSON）。输出是为每天调用数千次的代理而设计的。 **没有Claude能工作吗？** 二进制文件可以独立工作（研究、生成、验证、评分），但精心设计的代理循环——研究吸收、新功能建议、发布周期——通过Claude Code中的`/printing-press`斜杠命令运行。如果你想要跳过，可以自带代理循环。 **需要OpenAPI规范吗？** 不需要。三种输入模式：规范（`--spec`）、HAR文件（`--har`）或仅URL。浏览器嗅探门启动浏览器，捕获流量，并为没有发布规范网站逆向工程规范。 **本地SQLite缓存的时效性如何？** 可配置。没有`cache.enabled`，你手动运行`sync`。启用`cache.enabled`并设置`--data-source auto`后，CLI在提供本地数据之前会进行有界预读刷新。`--data-source local`跳过刷新；`--data-source live`完全绕过缓存。 **发布一个CLI需要多少Token？** 标准Opus模式全程使用Opus。Codex模式（`/printing-press codex`）将阶段3的代码生成卸载到Codex CLI，减少约60%的Opus Token。两者产生同等质量。 **我可以对手动构建的CLI运行验证工具吗？** 可以。`cli-printing-press scorecard`、`dogfood`和`verify`接受任何目录和规范。得分卡的第一层检查代理原生模式；第二层针对规范检查路径/认证/数据流。 ## 贡献 欢迎提交Bug报告、功能请求和PR。在提交PR之前阅读[CONTRIBUTING.md](CONTRIBUTING.md)；它解释了PR模板、AI/自动化披露以及Printing Press与打印CLI之间的仓库边界。[AGENTS.md](AGENTS.md)包含了完整的开发者约定、词汇表、提交风格和验证规则。 ## 开发

构建、测试、lint和hooks

``` go build -o ./cli-printing-press ./cmd/cli-printing-press go test ./... go fmt ./... golangci-lint run ./... ``` pre-push的lefthook hook对更改的文件运行`golangci-lint`；相同的配置（`.golangci.yml`）在CI中运行。 使用以下命令安装hooks： ``` brew install lefthook lefthook install --reset-hooks-path ``` 使用`--reset-hooks-path`，以便陈旧的本地`core.hooksPath`设置不会阻塞hook同步。除非有意覆盖自定义的hooks路径，否则避免使用`lefthook install --force`。 如果你使用基于克隆的开发者路径，`claude --plugin-dir .`会从你的工作副本加载`/printing-press`，因此本地技能编辑将在下一次会话启动时生效。对于重启安全的本地插件设置，请参阅[本地插件开发](docs/PLUGIN-DEV.md)。有关完整约定、词汇表和发布流程，请参阅[AGENTS.md](AGENTS.md)。

Golden输出框架

Golden输出检查将确定性的离线`printing-press`命令与已提交的stdout、stderr、退出码和选定的工件固定输出进行比较： ``` scripts/golden.sh verify ``` 仅在有意行为更改后使用更新模式： ``` scripts/golden.sh update ``` 框架重建`./cli-printing-press`，将实际输出写入`.gotmp/golden/actual`，并将其与`testdata/golden/expected`进行比较。用例位于`testdata/golden/cases//`下；`command.txt`定义离线命令，`artifacts.txt`列出行为上重要的生成文件进行比较。规范化有意保持狭窄：仅处理机器特定路径、确定性JSON格式以及已知的源字段如生成时间戳。CI将其作为单独的`Golden`工作流运行，而非`go test ./...`内部。 生成的CLI golden使用`testdata/golden/fixtures/golden-api.yaml`，这是一个为Printing Press专门构建的OpenAPI固定文件。当机器获得新的确定性生成能力且应通过工件golden保护时，扩展该固定文件。除非设置了`GOLDEN_ALLOW_DIRTY=1`，否则更新模式会拒绝脏工作树，以便固定文件的变更保持有意。

## 致谢 - Peter Steinberger（[@steipete](https://github.com/steipete)）。[discrawl](https://github.com/steipete/discrawl)和[gogcli](https://github.com/steipete/gogcli)设立了标杆。质量评分系统受到他工作的启发；discrawl的同步架构直接影响到了Printing Press模板。 - Trevin Chow（[@trevin](https://x.com/trevin)）。[代理原生CLI的10条原则](https://trevinsays.com/p/10-principles-for-agent-native-clis)塑造了代理优先模板的设计。共同创作者，每天发布PR。 - Ramp（[@tryramp](https://github.com/ramp-public/ramp-cli)）。他们代理优先的CLI启发了自动JSON管道、`--no-input`和`--compact`输出。 - 社区提交者和贡献者，他们的问题和PR推动了目录的进步。 ## 许可证 MIT

标签：AI代理, API嗅探, API管理, Claude Code技能, CLI生成器, EVTX分析, Go语言, MCP服务器, MITM代理, SQLite, Token优化, 命令行界面, 复合命令, 威胁情报, 开发者工具, 文档解析, 日志审计, 暗色界面, 本地数据同步, 社区CLI, 离线搜索, 程序破解, 网络抓取