ketch

Ketch

将每个实时信息问题路由到 ketch 的五种研究方式之一——搜索、代码、文档、抓取、爬取——并使用操作员提供的传输方式；每次获取都要设置令牌预算，每项结论都要附上来源 URL。ketch 是一个无状态的二进制程序——调用、返回结果、退出——集成了网页搜索、开源软件代码检索、精选库文档以及页面／网站提取，因此完整的研究流程无需其他工具或守护进程。

传输方式：默认使用无状态 CLI，操作员配置了 MCP 时则使用 MCP

CLI 是 ketch 的本质：调用 → 返回结果 → 退出，每次调用都使用 --json，以退出代码控制流程，且无需守护进程。这是默认传输方式，也是零基础设施的使用途径。MCP 服务是为有需要的操作员提供的受支持替代方案，绝非前置条件。

在会话开始时、首次调用前，确定一次：

1. which ketch 执行成功 → 使用 CLI 作为传输方式：每次调用都使用 --json，以退出代码控制流程。
2. 同时检查工具列表中是否有 ketch 的工具——来自名为 ketch 的服务的 MCP 工具 search、code、docs、scrape、crawl 和 tag（在 Claude Code 中为 mcp__ketch__search、…），或 pi 中软件包提供的 ketch_search、ketch_code、ketch_docs、ketch_scrape、ketch_crawl 和 ketch_tag。如果存在，说明操作员有意配置了这些工具，使用它们进行研究调用是正确且合适的：它们提供结构化输出、逐 URL 错误信息，以及与 MCP 相同的选项和错误前缀。不要绕过操作员配置的工具，改用 shell 命令。（pi 的工具会替你运行 CLI，因此步骤 3 中的页面缓存权衡不适用于它们。）
3. 两者都可用 → 任一传输方式都可用于研究调用，但请注意这一权衡：正在运行的 MCP 服务会持有单进程页面缓存锁，因此并发的 CLI 抓取会静默地禁用缓存。
4. CLI 和 MCP 工具都不可用 → 尚未安装 ketch。可提出安装方式：brew install ketch、npm i -g ketch-cli 或 go install github.com/1broseidon/ketch@latest——这是操作员操作：提出建议并等待确认。

规则：使用操作员提供的传输方式——两者都可用时，研究调用任选其一；操作员操作始终使用 CLI。

tag 是下文操作员操作规则的唯一例外：它会更改本地状态，但 Agent 既是写入者也是读取者，因此 CLI 和 MCP 都提供此工具。

无论使用哪种传输方式，配置发现都通过 CLI 进行：ketch config 会以 JSON 格式输出生效的设置和可用后端；MCP 不提供配置工具。操作员操作——config set、cache、browser install、crawl --background／status／stop、doctor——特意不通过 MCP 提供，始终使用 CLI。

术语表

在 ketch 输出中仅使用以下术语。

术语	含义
surface	五种研究操作之一：search、code、docs、scrape、crawl
tag	跨 surface 归档的标签：搜索结果、代码结果、文档片段、抓取的页面、爬取的页面。它不是研究 surface，而是回答“我已经找到了什么？”，而不是“外面有什么？”
transport	调用 surface 的方式：CLI 二进制文件（默认）、可选的 MCP 工具，或 pi 包的 ketch_* 工具（通过 CLI 运行）
backend	surface 背后的提供方：auto（默认；一条回退链，而非提供方）/brave/ddg/searxng/exa/firecrawl/keenable/tavily/tinyfish/parallel/serpbase/degoog/serply/youcom（搜索）、grepapp/sourcegraph/github（代码）、context7（文档）
operator action	系统管理或诊断命令——config set、cache、browser install、后台爬取、doctor——按设计仅限 CLI 使用
error prefix	每个 ketch 错误的稳定类别：CLI 退出代码 2–6，与每个 MCP 工具错误开头的方括号前缀对应——[validation]、[not_found]、[upstream]、[precondition]、[cancelled]
fan-out	一个计划下要搜索的查询数量和要抓取的 URL 数量
token budget	每次调用的输出上限：抓取时的 max_chars/trim、文档中的 tokens、列表中的 limit/--minimal
probe	一次低成本只读调用，用于测试 surface 是否已配置且可访问

如何使用此技能

• 默认：通过一到两次路由调用回答一个问题。使用下方的 surface 路由表、token 预算和错误控制流程。
• ketch research <question>：深入的多来源研究——搜索 fan-out → 抓取最相关的结果 → 可选的代码/文档佐证 → 综合并引用来源的答案。阅读 references/verbs/ketch-research.md。
• ketch setup：通过 operator 配置 backend——探测当前状态、提出精确命令，仅在确认后进行更改。阅读 references/verbs/setup.md。任何调用返回 [precondition] / 退出代码 5 时，都要进入此 verb。

一个问题 = 一个计划。当首次搜索表明答案存在争议、包含多个部分或需要佐证时，将默认运行升级为 ketch research。

不可妥协的准则

1. 使用 operator 提供的 transport。 CLI 是默认方式；如果你的工具列表中有 MCP 工具，说明 operator 已选择启用——研究时使用这些工具，不要绕过它们改用 shell。两者都可用时，研究调用可任选其一（运行中的 MCP 服务会持有页面缓存锁，因此并发 CLI 抓取不会使用缓存）；operator action——配置、缓存、浏览器、后台爬取、doctor——始终使用 CLI。
2. 限制每次抓取。 对任何尚未查看过的页面抓取，都要设置 max_chars 4000–8000 并启用 trim——不加限制的页面可能耗费约 25k 个 token。若要跳过上限，必须说明一行理由（“已知页面约 200 个单词”）。
3. 为每条主张附上引用。 没有来源 URL 的研究综述不算交付成果。
4. 错误前缀用于控制流程。 先分类，再采取行动。切勿原样重试 [validation] 或 [not_found]。
5. 先提出，再更改。 只有在 operator 确认了精确命令后，才能执行 config set、browser install、docker 运行、安装等操作。绝不改动已正确配置且正常工作的值。
6. 以二进制文件为准，而非本文件。 ketch config 和 --help 才是事实依据；若它们与此处的表格不一致，请以二进制文件为准，并标记此技能已过时。

黄金决策轨迹

Request: "ketch research — do people actually use Go's iter.Seq in real projects, and what are the gotchas?"

Transport: operator wired mcp__ketch__* into this session → honor it; research calls go over MCP.
Plan: 2 queries · scrape top 3 · max_chars 6000 + trim · ≤8 calls

search {query: "Go iter.Seq real-world experience gotchas", limit: 5}
  → "[upstream] ddg rate limited" → an explicit backend failed; rotate to another
    usable provider from available_backends, retry once:
    search {query: ..., backend: "brave", limit: 5} → ok
search {query: "Go range-over-func adoption production", backend: "brave", limit: 5}
  → 10 results, 8 unique hosts → picked 3: official blog post, one experience
    report, one issue thread (primary sources over aggregators)

scrape {urls: [u1, u2, u3], max_chars: 6000, trim: true}
  → isError=false; checked results[] one by one: u1, u2 ok;
    u3.error = "[upstream] … 503" → dropped, will be named in synthesis

code {query: "iter.Seq", lang: "go", limit: 3}      # corroborate real usage
  → 3 repos with file/line URLs

Synthesis: five claims, each cited to its URL; u3 listed as unretrieved;
one conflict between u1 and u2 stated and attributed, not averaged.
Budget: 5 of 8 calls (the rate-limited attempt counts).

表面路由

按顺序匹配，首个匹配项优先：

问题需要	表面	不要用
当前网页、观点、新闻、比较	search	docs——它只包含精选的库文档
真实项目如何调用 API	code	search——博客讨论的是代码；code 通过 grep.app 搜索公开的 OSS 仓库
库本身的文档，且与版本对应	docs	对文档网站使用 scrape——docs 已经提取内容并控制了令牌预算
你已掌握的 URL 内容	scrape	search——绝不要重新查找已知 URL
同一网站上的多个页面	crawl	循环调用 scrape——crawl 会去重、限制范围并流式传输
你在本项目中先前已找到的内容	tag（operation: show）	再次使用 search——这些内容你已经查找过了

反过来说：search 查找 URL；scrape 读取 URL；crawl 读取网站；code 读取公开源代码；docs 读取库文档。如果你需要获取 search 每个结果的完整内容，可用 search 搭配 scrape: true，并按一次 scrape 的预算来规划。

使用 tag 维护工作集

如果工作跨越多个会话，或涉及不止少数几个来源， 请在之后还会用到的调用中传入 --tag <name>（CLI）或 tag（MCP）， 使用项目或工作范围命名，例如 remote-access，而不是 results-3。

它适用于所有表面，而且一个标签可以保存所有内容：search、code、 docs、scrape、crawl。因此，项目标签最终会将供应商的 文档、调用该文档的代码，以及解释未公开标志的文章保存在同一个列表中。 之后，tag show 会以 llms.txt 形式的索引返回这些内容——包含标题、URL、描述—— 最多显示最新的 50 条；你只需重新读取其中一个来源，而不必重新执行查找它们的搜索。 只为实际用过的来源添加标签，不要给每个结果都加标签。

使用 --limit N / MCP limit 缩小视图；显式设为 0 表示请求全部内容。 entries 统计整个标签中的条目，shown 统计返回的页面数。再次搜索前先阅读索引， 但默认不要请求大型标签的全部内容。

索引持久保存，其生命周期长于缓存的页面正文，因此几天后它仍能提供信息。cached: false 表示未确认有最新正文，并不表示链接已失效。 当 cache_status 为 unavailable 时，无法检查页面缓存； 书签仍然可用，来源仍然可以获取。code、docs 和未经过 scrape 的 search 结果天生会以这种状态开始，因为这些调用返回的是摘要，而非已获取的页面； 想要获取完整内容时，对 URL 使用 scrape。先阅读索引，然后只获取所需内容：整理整个标签会失去使用标签的意义。

将书签诊断与研究成功情况分开检查：CLI 警告会输出到 stderr（使用 --json 时为结构化内容），MCP 则会返回 warnings。写入失败 不会丢弃有用的研究结果。持久书签使用单独的文件； 测试实验室必须设置 KETCH_TAGS_PATH，同时隔离页面缓存。

令牌预算

调用	使用以下参数限制	测量成本
search，limit 5	limit	~1.4 KB
code，limit 3	limit	~0.7 KB
docs，默认预算	tokens（默认值 4000）	~3.3 KB
scrape，未知页面	max_chars 4000–8000 + trim	不受限制：最多约 100 KB（~25k 个令牌）
crawl（MCP）	max_pages + 每页 max_chars	默认 30 页，上限 100 页，最长耗时 3 分钟
tag show / MCP tag show	limit（默认值 50；0 表示全部）	来源元数据有界；不含页面正文
任意 CLI 列表	--minimal	输出量约减半

错误控制流程

退出码（CLI）	前缀（MCP）	含义	操作
2	[validation]	输入无效	修正调用；不做修改直接重试永远不会成功
3	[not_found]	未匹配到任何内容	更改查询或选择器；这不是服务中断
4	[upstream]	后端或网络故障	显式指定后端：切换到其他提供方（在 ketch config 中查看 available_backends）或重试一次。auto 已尝试所有可用提供方：重试一次，然后报告服务中断
5	[precondition]	缺少操作员配置	停止查找；运行 ketch setup
6	[cancelled]	已取消或超时	缩小范围后重新运行

情况 → 类别：未知后端、在 github 上使用 regexp → [validation]。选择器未匹配到内容、代码后端没有的 repo → [not_found]（对于 repo，请更改后端）。ddg 速率限制（扇出时很容易触发）、DNS 故障、grepapp 间歇性出现的 504 → [upstream]，切换后端或重试一次。缺少 API 密钥、文档后端 local（计划中，尚未实现）、未配置浏览器却使用 force_browser → [precondition]。有一种例外：CLI crawl 被 SIGINT 中断时会以 0 退出并返回部分结果，这是有意设计的。

注意事项

各项详细说明见 references/surfaces.md。

• 抓取纯域名时会自动探测 /llms.txt，并可能悄悄返回该文件，而非首页——title 字段会显示这一变化；使用 no_llms_txt 可选择不探测。
• docs 分两步：resolve 名称 → 核验匹配项 → 按 library ID 获取内容。Resolve 永远不会返回空结果——无效输入也会得到看似可靠的模糊匹配，因此要检查名称，而不只是信任度分数。
• 批量抓取会在成功调用中报告每个 URL 的失败：isError=false，且设置了 results[].error。请检查每个条目。
• regexp 仅适用于 grepapp 和 sourcegraph；github 会拒绝此参数，并提示改用这些后端。
• 后台抓取（--background、status、stop）仅限 CLI；MCP crawl 是同步的，且有上限。
• 页面缓存（bbolt，默认 TTL 为 72h）仅支持单进程：长时间运行的 MCP 服务会持有锁，因此并发的 CLI 抓取会悄悄禁用缓存——ketch doctor 会报告缓存被其他进程锁定。运行服务会降低 CLI 的性能；如果两者都要长期运行，优先仅使用 CLI。

错误 / 正确示例

错误： scrape {url: "https://docs.example.com"} —— 没有长度限制；你得到的要么是 llms.txt，要么是约 25k 个 token，取较糟的那个。 正确： scrape {url: "https://docs.example.com/quickstart", max_chars: 6000, trim: true} —— 如果你想要页面本身而不是站点的 llms.txt，再加上 no_llms_txt: true。

错误： 告诉用户必须运行 MCP 服务才能让 Agent 使用 ketch——CLI 加上提示词块即可实现零基础设施使用；而且长时间运行的服务会持有页面缓存锁，影响所有 CLI 调用。 正确： 默认使用 CLI；操作员已配置 MCP 时再使用 MCP——如果你的工具列表中有 mcp__ketch__* 工具，请用它们进行研究，而不是绕过操作员的配置去调用 shell。

错误： [upstream] ddg rate limited → 将完全相同的调用重试三次。 正确： 切换后端——使用 backend: "brave"（或 available_backends 中的其他提供方；auto 是一条调用链，不能作为轮换目标）——重试一次，并注明已切换。当 auto 本身失败时，它已经尝试了所有可用提供方：重试一次，然后报告服务中断。

错误： 尽管 resolve 的第一个匹配项名称并非你要查询的库，却因为它的信任度分数很高而直接用它获取文档。 正确： 核验名称、摘要数量和信任度；如果没有匹配项的名称与目标库相符，就说明这一点，而不是获取无关文档。

加载参考资料

• ketch research … → 开始前阅读 references/verbs/ketch-research.md。
• ketch setup、任何 [precondition] / 退出码 5，或安装操作 → 阅读 references/verbs/setup.md。
• 完整的标志 / 参数表、CLI↔MCP 名称映射、后端 / 密钥矩阵，或表现异常的功能界面 → 阅读 references/surfaces.md。

范围

范围内：两种传输方式下的五个研究界面、研究和设置动词、令牌预算、错误前缀控制流、后端配置。范围外：本地或私有代码库搜索（使用代码库工具）、需要身份验证或付费墙的页面、超出上限的批量归档爬取、超出 ketch 无头渲染回退范围的浏览器自动化。

为每次抓取设置上限；为每项陈述注明出处。