1broseidon/ketch

# ketch [](https://github.com/1broseidon/ketch/stargazers) [](https://pkg.go.dev/github.com/1broseidon/ketch) [](https://goreportcard.com/report/github.com/1broseidon/ketch) [](https://github.com/1broseidon/ketch/releases/latest) 一个用于网页搜索、代码搜索、库文档和爬取的无状态 CLI —— 单个二进制文件，无需 daemon，无需运行 API 服务器。 ## 为什么选择 ketch 大多数为 agent 准备的研究工具意味着要连接多个 provider SDK，每个 SDK 都有其特定的身份验证和响应格式。ketch 将它们整合到了一个二进制文件中，提供三种研究途径： - `ketch search` —— 网页搜索（Brave、DuckDuckGo、SearXNG、Exa、Firecrawl 或 Keenable） - `ketch code` —— 在公共仓库中 grep 真实的 OSS 源码（Grep、Sourcegraph 或 GitHub Code Search） - `ketch docs` —— 精选的、版本感知的库文档（Context7） 此外还有 `ketch scrape` 和 `ketch crawl`，可将任何 URL 或站点转换为干净的 markdown。 它同时为两类受众构建： - **人类**，他们想要一个快速的终端工具来完成原本需要使用 `curl | pandoc` 或浏览器标签页才能完成的工作。 - **AI agent**，它们想要结构化、可预测的输出（全面支持 `--json`）、用于控制流的已文档化退出代码，以及一次 `ketch config` 调用来发现哪些 backend 处于活跃状态 —— 无需环境探测，也无需编写针对各个 provider 的胶水代码。 操作员只需配置一次 backend（`ketch config set backend searxng`）；之后的每次 agent 调用只需直接执行 `ketch search` 或 `ketch scrape`，无需知道或关心背后使用的是哪个 provider。 ## 安装 ``` # Homebrew brew install 1broseidon/tap/ketch # go install go install github.com/1broseidon/ketch@latest # 或下载预构建的二进制文件 (linux/darwin/windows, amd64/arm64) # 从 https://github.com/1broseidon/ketch/releases ``` ## 快速开始 ``` $ ketch scrape https://go.dev/doc/effective_go --- url: https://go.dev/doc/effective_go title: Effective Go - The Go Programming Language words: 16582 --- 1. [Documentation](https://go.dev/doc/) 2. [Effective Go](https://go.dev/doc/effective_go) ... ## 介绍 Go is an open-source programming language that focuses on simplicity, reliability, and efficiency... ``` 零配置即可搜索真实的 OSS 代码： ``` $ ketch code "http.NewRequestWithContext" --lang go --limit 2 --- query: http.NewRequestWithContext lang: go backend: grepapp result_count: 2 --- harness/harness registry/app/remote/clients/registry/client.go (line 207) req, err := http.NewRequestWithContext(ctx, http.MethodGet, buildPingURL(c.url), nil) https://github.com/harness/harness/blob/main/registry/app/remote/clients/registry/client.go ... ``` 网页搜索需要先配置 backend —— 默认的 `brave` 需要一个免费的 API key： ``` ketch config set brave_api_key ketch search "golang error handling" ketch search "golang error handling" --scrape # fetch + extract full content per result ketch search "golang error handling" --multi # federate across every usable backend, rank-fused ``` `--multi` 会同时查询多个 backend，并通过 Reciprocal Rank Fusion（倒数排名融合）算法融合它们的排名结果（被多个搜索引擎高度评价的页面会浮升至顶部）， 根据 URL 进行去重，并为每个结果标记返回它的搜索引擎。 单独使用 `--multi`（或 `--multi=all`）会调用所有可用的 backend；`--multi=brave,exa` 可指定一个集合（请使用 `=` 格式）。参见 [`site/reference/commands.md`](./site/reference/commands.md)。 每个命令均支持 `--json` 以输出结构化数据： ``` ketch scrape https://example.com --json # {"url":"https://example.com","title":"Example Domain","markdown":"..."} ``` 通过 ketch 的可读性 + markdown pipeline 管道传输任何 HTML，无需进行抓取： ``` curl -L https://chain.sh/ketch | ketch extract cat page.html | ketch extract --select article --max-chars 4000 ``` ## 命令 | 命令 | 功能 | |---|---| | `search` | 网页搜索 —— Brave、DuckDuckGo、SearXNG、Exa、Firecrawl 或 Keenable | | `code` | grep 真实的 OSS 源码 —— Grep（默认）、Sourcegraph 或 GitHub Code Search | | `docs` | 库/框架文档 —— Context7（精选的、版本感知的代码片段） | | `scrape` | 获取 URL 并提取干净的 markdown；支持并发批量、JSON 数组、文件或标准输入 | | `extract` | 将通过管道传入的 HTML 转换为干净的 markdown（`curl ... \| ketch extract`）—— 无需抓取、无需缓存、无需浏览器 | | `crawl` | BFS 或 sitemap 爬取，支持可选的后台执行和状态追踪 | | `browser` | 管理用于渲染 JS 页面的无头 Chrome（`install`、`status`） | | `config` | 以 JSON 格式显示有效配置，或执行 `init` / `set` / `path` | | `cache` | 显示页面缓存统计信息，或执行 `clear` | | `doctor` | 对每个 backend、浏览器和缓存进行实时健康检查 —— 退出码 `0` 表示健康，`5` 表示已配置的途径出现故障 | | `mcp` | 通过 stdio 运行 ketch 作为 MCP 服务器（`mcp serve`）—— 将五大研究途径作为工具暴露 | | `version` | 打印版本号、commit 和构建日期 | 每个命令都支持 `-h/--help` 来查看其完整的 flag 列表；`--json` 是所有命令全局通用的唯一 flag。完整的 flag 参考文档位于 [1broseidon.github.io/ketch](https://1broseidon.github.io/ketch/)。 ### Backend | 途径 | 默认 | 其他可用选项 | 设置 | |---|---|---|---| | `search` | `brave` | `ddg`, `searxng`, `exa`, `firecrawl`, `keenable` | Brave 和 Firecrawl 需要免费 key（`ketch config set brave_api_key ` / `firecrawl_api_key`）；`ddg`、`searxng`、`exa` 和 `keenable` 零配置即可使用 | | `code` | `grepapp` | `sourcegraph`, `github` | Grep 和 Sourcegraph 无需任何配置；GitHub 使用 `gh auth login`、`$GITHUB_TOKEN` 或 `ketch config set github_token ` | | `docs` | `context7` | `local`（已规划，尚未实现） | 免费 key：`ketch config set context7_api_key ` | ## 为什么它非常适合 agent - **无状态、单一二进制文件。** 无需 daemon，无需保持服务器运行 —— 调用、获取结果、退出。 - **已文档化的退出代码**，而不仅仅是 stderr 文本，专为脚本化控制流设计：`2` 表示错误输入，`3` 表示未找到，`4` 表示上游/网络故障，`5` 表示缺少前置条件（例如没有 API key），`6` 表示已取消（SIGINT/SIGTERM）。 - **自动回退到 JS 渲染。** `ketch scrape` 和 `ketch crawl` 会检测 JS 外壳页面（React/Vue/Svelte 等 SPA、流式水合框架），并在需要时通过无头 Chrome 透明地重新获取 —— 无论哪种方式，输出格式保持一致。 - **针对 `scrape` 的智能输入检测。** 支持单个 URL、多个位置参数、JSON 数组、包含 URL 的文件或标准输入 —— 无需使用 `--batch` flag。 - **页面缓存。** 抓取内容会被缓存（bbolt，默认 TTL 72h）；重复的抓取和爬取会瞬间返回结果。使用 `--no-cache` 可绕过缓存。 - **一次调用即可发现能力。** `ketch config` 以 JSON 格式返回完整的有效配置和活跃的 backend，因此 agent 无需解析 `--help` 文本即可检查其能力。 ## 配置 ``` ketch config init # write a default config file ketch config set backend searxng # set a default backend ketch config set searxng_url http://my-searxng:8080 ketch config set browser chrome # enable browser fallback for JS-rendered pages ketch config # print effective config + available backends ketch config path # print the config file path ``` 其他可配置的 key 包括各 backend 的 API key 和 URL（`brave_api_key`、`context7_api_key`、`github_token`、`sourcegraph_url`、`exa_api_key`、`firecrawl_api_key`），`cache_ttl`、`url_rewrites`（在抓取前应用的正则表达式重写规则）以及 `spa_markers`（额外的 JS 外壳检测 token）。完整列表请参见[配置参考](https://1broseidon.github.io/ketch/)。 ## Agent 集成 将 agent 的系统提示词指向 ketch，而不是去教授它各种独立的搜索/抓取 API： ``` Use `ketch` for external research — web pages, OSS code, library docs. - `ketch search "query"` / `ketch search "query" --scrape` for web results with optional full content (add `--multi` to federate across backends and rank-fuse) - `ketch scrape [url...]` for clean markdown from one or more URLs - `ketch extract` for already-fetched/piped HTML (`curl ... | ketch extract`) — no fetch, no cache, no browser - `ketch code "query" --lang go` for real OSS code with repo/line context - `ketch docs "query" --library /org/repo` for version-aware library docs - All commands support `--json`. `ketch config` reports active backends. ``` 操作员只需配置一次 backend；agent 的提示词永远不需要提及 `ketch search` 背后使用的是哪个 provider。 ### MCP 服务器 对于使用 MCP 协议而不是通过 shell 调用的 agent，`ketch mcp serve` 会通过 stdio 运行相同的五大途径 —— `search`、`code`、`docs`、`scrape`、`crawl` —— 将其作为 MCP 工具暴露出来，并使用与 CLI 相同的配置和 backend。要在 Claude Code 中注册它： ``` claude mcp add ketch -- ketch mcp serve ``` 工具错误会将退出代码分类作为稳定的消息前缀携带：`[validation]`、`[not_found]`、`[upstream]`、`[precondition]`、`[cancelled]`。 ### Claude Code 插件 PATH 中的 CLI 就是 ketch 需要的一切 —— 但如果你希望 Claude Code 一步到位地连接 MCP 服务器和[捆绑的技能](./skills/ketch/)，这个仓库也可以作为插件市场使用： ``` claude plugin marketplace add 1broseidon/ketch claude plugin install ketch@ketch ``` 该插件会将 `ketch mcp serve` 注册为 MCP 服务器，并安装 ketch 研究技能。它不包含二进制文件：PATH 中必须存在 `ketch` >= v0.10.0（`brew install 1broseidon/tap/ketch` 或 `go install github.com/1broseidon/ketch@latest`）。 ## 许可证 [MIT](./LICENSE)

标签：EVTX分析, URL枚举, 日志审计