tools-factory

# 古腾堡命令行工具 <p align="center"> <img src="gutenberg-cli.jpg" alt="gutenberg-cli_logo" width="500"/> </p> **一个为AI代理验证的工具工厂。** 从任何API表面到安全、验证的工具，任何代理运行时都可以使用 — Go命令行 + MCP服务器 + 代理技能 + SQLite/FTS5缓存 + 默认干预策略 + 哈希可验证证明工件。 ## 30秒演示 <img src="gutenberg.gif" width="500" > ```bash $ gutenberg quick https://catfact.ninja/fact gutenberg quick: 探测 https://catfact.ninja/fact gutenberg quick: 结果 = openapi-published (高) gutenberg quick: 从 https://catfact.ninja/docs?api-docs.json 下载规范 gutenberg quick: 在 library/tools/catfact 生成工具 gutenberg quick: 验证 catfact ← go build · cli-smoke · mcp-handshake · go test gutenberg quick: 验证成功 gutenberg quick: 安装 catfact → ~/.local/bin/catfact $ catfact fact ← A级 · 100/100 · ~30 秒端到端 GET https://catfact.ninja/fact 状态: 200 OK { "fact": "在仅仅7年内，一只未绝育的母猫和一只未阉割的公猫...", "length": 121 } ``` **一条命令。任何公共API。一个为AI代理工作的工具表面：命令行、MCP、技能、缓存、策略和证明。** 没有其他工具能做到这一点。 ## "quick" 命令的作用，分6个步骤 1. **探测** URL (`try`) — 分类为 `openapi-published / json-endpoint / html-content / spa / lazy-rendered / anti-bot-challenge / http-error` 2. **获取规范** （或种子HAR，如果没有公开的规范；自动推断baseUrl/模式） 3. **生成** Go命令行 + MCP服务器 + Claude技能 + OpenClaw技能 4. **验证** 通过构建 + 命令行烟雾测试 + MCP握手 + Go测试 → `proofs/verification.json` 5. **安装** 到 `~/.local/bin/<slug>` 6. **暴露heroes** — 零摩擦别名自动检测（例如 `catfact fact`, `github meta`, `tvmaze shows`) ## 或传递自然语言意图并路由到目录 ```bash $ gutenberg quick "top hacker news stories" gutenberg quick: 在目录中搜索 "top hacker news stories" gutenberg quick: 最高匹配：hacker-news topstories-json （分数=5） [...执行目录中的工具...] ``` --- ## 为什么选择古腾堡 当今大多数AI代理基础设施都提供模型并告诉您“自带工具”。古腾堡制造工具 - 并在任何代理调用它们之前确保它们实际上是有效的。 | 原语 | 它做什么 | |---|---| | **`forge` / `generate`** | OpenAPI / GraphQL / HAR / OpenAPI-from-Postman/Insomnia/curl → Go命令行 + MCP服务器 + Claude/OpenClaw技能 | | **`verify`** | 运行 `go build`, 命令行烟雾测试, MCP握手, `go test` — 编写 `proofs/verification.json`。 **无证明 = 非A级。** | | **`try <url>`** | 自动驾驶：分类站点 (`openapi-published / json-endpoint / html-content / spa / lazy-rendered / anti-bot-challenge / http-error`) 并告诉您确切的下一个命令 | | **`extract` / `scrape`** | 基于LLM的结构化提取（JSON模式验证，缓存TTL，Anthropic/OpenAI/Ollama提供程序）+ Firecrawl样式的markdown抓取 | | **`snapshot/replay`** | 生成的工具支持确定性记录 + 离线重放用于测试和CI | | **`vault`** | 所有生成的工具之间共享的AES-GCM加密令牌库 | | **`lockfile` + `diff` + `upgrade` + `watch`** | 固定规范哈希，语义差异，重新生成同时保留 `// gutenberg:keep` 块，轮询上游漂移 | | **`compare`** | 在同一意图上调用N个工具，查看结果并排 | | **`aggregator` 类型** | 一个配方 → 一个分出Go命令行，超过N个JSON源，带有 `merge.go` + `rank.go` | | **`heroes`** | 零摩擦别名自动检测（或通过 `x-gutenberg-hero`策划） — 例如 `espn nba`, `github meta`, `tvmaze shows` | ## 安装 古腾堡目前从GitHub仓库安装。npm软件包尚未发布，因此请勿使用 `npx gutenberg`。 完整工作流的先决条件： - Node.js 20+ - Go安装在 `PATH` 上（`go version` 必须有效），或 `GUTENBERG_GOROOT=/path/to/go` - Git和curl - 可选：`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, 或Ollama用于 `extract` / LLM路由的 `run` 从源代码安装： ```bash git clone https://github.com/JustVugg/gutenberg.git cd gutenberg npm install node bin/gutenberg.js doctor ``` 直接从仓库使用： ```bash node bin/gutenberg.js search "top hacker news stories" node bin/gutenberg.js try https://api.tvmaze.com/shows/1 ``` 或从本地checkout全局安装 `gutenberg` 命令： ```bash npm link gutenberg doctor ``` 生成的工具安装在 `~/.local/bin`。确保它在您的 `PATH` 上： ```bash export PATH="$HOME/.local/bin:$PATH" ``` 对于浏览器录制流程，仅需安装Playwright浏览器： ```bash npx playwright install chromium ``` ## 第一个工具 最快的端到端测试是 `quick`：它探测URL，生成工具，验证它，并安装生成的命令行。 ```bash gutenberg quick https://catfact.ninja/fact catfact fact ``` 如果您没有运行 `npm link`，请使用 `node bin/gutenberg.js` 代替 `gutenberg`。 从公共OpenAPI规范生成： ```bash curl -fsSL -o /tmp/github.json \ https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json gutenberg generate /tmp/github.json --out library/tools/github --name github --force --strict gutenberg verify library/tools/github gutenberg install library/tools/github github meta github call search/repos --param q=claude-code --select '[*].full_name' ``` 探测您从未见过的站点： ```bash gutenberg try https://www.thetrainline.com/it # → "spa, use record" gutenberg try https://it.wikipedia.org/wiki/Bologna # → "html-content, use scrape/extract" gutenberg try https://api.tvmaze.com/shows/1 # → "json-endpoint, seed-har + import + generate" ``` ## 古腾堡有效的工作（诚实表格） | 站点形状 | 推荐路径 | 成功率 | 我们已交付的示例 | |---|---|---|---| | **具有公共OpenAPI的API** | 直接 `generate` | ✅ ~95% | GitHub（1183个操作），Stripe（587），Sentry（209） | | **无规范但有JSON端点** | `seed-har` → `import-har` → `generate` | ✅ ~90% | ESPN，TVMaze，Wikipedia REST，公共JSON API | | **纯HTML内容站点** | `scrape` (+ `--structured`) 或 `extract` 带有模式 | ✅ ~80% | Wikipedia和内容/文档页面 | | **具有可达XHR的SPA** | `record` （Playwright）→ `import-har` | ⚠️ ~40% | 需要交互式触发 | | **SPA + Cloudflare Turnstile / 强防Bot** | `record --backend browserbase` （付费）— 或使用官方合作伙伴API | ❌ ~5% 使用免费工具 | thetrainline，lastminute，OpenTable，Subito.it | ## 非目标（古腾堡故意不做的事情） - **绕过反机器人保护。** Cloudflare Turnstile，JS挑战，基于指纹的机器人检测：古腾堡不试图击败它们。 当站点投资于阻止机器人时，这是一个产品决策，我们尊重。 对于合法的浏览器驱动的抓取，请使用官方的Browserbase后端（`record --backend browserbase`）。 - **解决CAPTCHAs。** 没有2Captcha风格的集成。 - **抓取违反ToS。** 每个生成的工具的README都告诉用户尊重速率限制，robots.txt和服务条款。 - **成为模型。** 古腾堡路由LLM调用（Anthropic / OpenAI / Ollama）但不训练或微调。 ## 命令 ```bash gutenberg doctor 探测运行时、LLM提供者、Browserbase gutenberg try <url> 自动驾驶 - 分类站点并选择下一个命令 gutenberg discover <url> 查找已发布的OpenAPI/Swagger gutenberg seed-har <url> [<url>...] 使用纯HTTP获取URL（s），发出HAR（无浏览器） gutenberg record <url> Playwright HAR记录 [--storage-state state.json] [--backend browserbase --key $KEY --project-id $PROJ] gutenberg login <url> --out state.json 有头登录流程，保存存储状态以供后续记录/提取 gutenberg import-har <har> HAR → OpenAPI（带有模式推断 + 身份验证嗅探器） gutenberg import-graphql <source> GraphQL SDL / 反射 → OpenAPI gutenberg generate <spec> --out <dir> OpenAPI → Go命令行 + MCP + Claude技能（+ openclaw，可选） [--strict] [--min-score 0.7] [--default-header 'k: v'] [--policy policy.json] gutenberg generate <recipe> --kind aggregator --out <dir> gutenberg verify <project-dir> 运行构建 + 命令行烟雾测试 + mcp-handshake + 测试；写入证明/ gutenberg install <project-dir> go build + 符号链接到 ~/.local/bin gutenberg install starter-pack 安装Hacker News，ESPN，Wikipedia，TVMaze，Open-Meteo，GitHub gutenberg scorecard <project-dir> 多维记分卡，带有验证徽章 gutenberg publish <tool-dir>|--all 验证证明 + 技能 + OpenClaw；同步注册表 gutenberg registry sync 从实际清单中重建library/registry.json gutenberg upgrade <project-dir> [--spec ...] 重新生成，保留 `// gutenberg:keep` 块，自动go mod tidy gutenberg watch <project-dir> <spec-url> 轮询规范URL，漂移时重新生成 gutenberg diff <old-spec> <new-spec> 语义规范差异 gutenberg extract <url> -p PROMPT -s SCHEMA 带有JSON模式验证的LLM提取 + --cache 1h gutenberg scrape <url> [--structured] 主内容markdown（用于重复模式的表格检测器） gutenberg search <intent> 目录发现：顶级匹配操作 gutenberg run <intent> [--no-llm] LLM路由（或顶级匹配）执行目录 gutenberg compare <tool-a> <tool-b> --op X 工具间并排调用 gutenberg site build 使用记分卡 + 英雄重建web/data.js ``` 生成的工具共享一个统一的子命令界面： ```bash <tool> operations [--json] 列出操作 <tool> heroes [--json] 列出自动检测的英雄别名 <tool> <hero-alias> 调用 --digest的快捷方式 <tool> call <op-id> [options] 调用时具有完全控制 --param k=v --path k=v --header 'k: v' --data '{...}' --yes --json | --compact | --digest | --select 'data.events[*].name' --stream 用于SSE/NDJSON端点 <tool> walk <op-id> --max N 自动分页（偏移/限制，光标，页面） <tool> sync 当地缓存读取操作（SQLite/FTS5） <tool> search <query> 完整文本缓存响应 <tool> resources [query] 在SQLite中搜索投影资源行 <tool> auth <status|client-credentials|device|pkce-start|pkce-finish|refresh> <tool> mcp 作为MCP stdio服务器运行 ``` ## 包含的目录 带有 `proofs/verification.json` 的21个验证目录条目： | 工具 | 操作 | 源 | 验证检查 | |---|---:|---|---| | github | 1183 | GitHub OpenAPI官方 | 构建 • 命令行 • mcp • 测试 | | stripe | 587 | Stripe OpenAPI官方 | 构建 • 命令行 • mcp • 测试 | | sentry | 209 | Sentry OpenAPI官方 | 构建 • 命令行 • mcp • 测试 | | espn | 4 | HAR种子 | 构建 • 命令行 • mcp • 测试 | | wikipedia-it | 5 | HAR种子（User-Agent 默认） | 构建 • 命令行 • mcp • 测试 | | tvmaze | 5 | HAR种子 | 构建 • 命令行 • mcp • 测试 | | multi-demo | 2 个源 | 聚合器（ESPN + Open-Meteo） | 构建 • 命令行 • 测试 | | dev-pulse | 2 个源 | 聚合器（GitHub + ESPN） | 构建 • 命令行 • 测试 | Plus CatFact, CoinGecko, Dog API, Exchange Rates, Hacker News, npm registry, Open-Meteo, PokeAPI, public holidays, PyPI, RandomUser, REST Countries, and TVMaze quick. 真相的完整源是 `library/registry.json`，由 `gutenberg registry sync` 生成。 Plus `library/recipes/` 中16+个常见源的配方模板（Hacker News, CoinGecko, PokeAPI, Open-Meteo, REST Countries, Nominatim, npm registry, PyPI, exchange rates, public holidays, Reddit, Spotify, Slack, …）。 ## 输出目标 `--targets go,mcp,skill,openclaw` 控制Go模块后发出内容： - **`go`** + **`mcp`** — Go二进制 + stdio MCP服务器（默认） - **`skill`** — `skills/<slug>/SKILL.md` （Claude Code技能格式） - **`openclaw`** — `openclaw/<slug>/skill.{json,md}` （agent-framework-neutral 模式） ## 架构差异 vs 其他开源工厂 与 **site2cli** （PyPI）和 **printingpress.dev** （~82 CLI，npm）相比，古腾堡独特地提供了： - 验证证明门控（无A级证明 `proofs/verification.json`） - `gutenberg try <url>` 自动驾驶 - 聚合器作为配方（声明式） - 快照/重放确定性模式（内置每个生成的工具） - 共享AES-GCM令牌库 - `lockfile` + `diff` + `upgrade` + `watch` - `cross-tool compare` - LLM提供者无关的提取（Anthropic / OpenAI / Ollama）+ 缓存TTL - HAR → OpenAPI 带有 **响应模式推断** 和 **身份验证方案嗅探器** - 带有 `--select` 和 `--stream` 的内置JSONPath，用于SSE/NDJSON 我们目前没有：他们的目录规模（82 vs 21）和打包的npm分发。目录随着配方和 `gutenberg publish --all --fix-assets` 而增长。 ## 运行测试 ```bash node --test tests/*.test.js ``` 本地网络依赖测试在拒绝 `127.0.0.1` 监听器的沙盒中干净地跳过。 浏览器测试仍需选择加入（`GUTENBERG_BROWSER_TESTS=1` 以运行实时Playwright）。 ## 环境变量 | 变量 | 什么 | |---|---| | `ANTHROPIC_API_KEY` | 为 `extract` / `run` 使用Anthropic | | `OPENAI_API_KEY` | 为 `extract` / `run` 使用OpenAI | | `OLLAMA_HOST` （默认为 `http://localhost:11434`）+ `GUTENBERG_LLM_PROVIDER=ollama` | 为 `extract` 使用本地或远程Ollama | | `BROWSERBASE_API_KEY` + `BROWSERBASE_PROJECT_ID` | `record --backend browserbase` 需要 | | `GUTENBERG_VAULT_KEY` （32字节十六进制） | 使用AES-GCM加密共享OAuth库 | | `GUTENBERG_TELEMETRY=1` + `GUTENBERG_TELEMETRY_FILE` | 选择加入本地JSONL日志的操作调用（永远不会发送任何地方） | | `<TOOL_ENV>_SNAPSHOT_MODE=record\|replay` + `<TOOL_ENV>_SNAPSHOT_DIR` | 确定性HTTP记录/重放每工具 | | `<TOOL_ENV>_AUTO_REFRESH=0` | 在生成的工具中禁用自动OAuth刷新 | ## 许可证 MIT. ## 状态 `v0.1.0` — 公开。诚实地说明其边界： - ✅ 在GitHub，Stripe，Sentry，ESPN，Wikipedia IT，TVMaze和公共API启动目录上验证端到端 - ✅ 已交付21个目录条目，16+个配方模板 - ❌ 无法绕过Cloudflare Turnstile / 强反Bot。 使用 `record --backend browserbase` 或官方合作伙伴API用于此类站点。