oh-my-opencode-slim 内置增强版 webfetch（smartfetch）：面向文档站点的智能抓取工具全解析

人工智能AI AgentAgent 编排AI 技能【免费下载链接】oh-my-opencode-slimLean, fine tuned Opencode multi agent suite · Mix any models · Auto delegate tasks项目地址https://gitcode.com/gh_mirrors/oh/oh-my-opencode-slim点击查看免费下载导读webfetch是 OpenCode 内置的网络抓取工具而 oh-my-opencode-slim 在 src/tools/smartfetch/ 目录下实现了一个增强版本并以同名webfetch注册覆盖默认实现。它面向文档站、静态页与结构化文本做了针对性优化支持llms.txt探测、Mozilla Readability 正文提取、LRU 缓存与条件重验证、二进制内容落盘以及可选的廉价次生模型secondary model总结。读完本文你将掌握该工具的全部参数语义、底层执行流程、缓存与重定向策略以及如何通过webfetch配置项指定专用总结模型。模块定位与职责划分根据 src/tools/smartfetch/codemap.mdsmartfetch 模块承担两项核心责任实现内置webfetch工具抓取远程文档执行重定向/origin 策略在合适时机探测llms.txt并返回归一化的 text/markdown/html 输出由 tool.ts 与 network.ts 承担围绕抓取步骤做内容整形HTML 提取、元数据/frontmatter 渲染、标题清理、缓存键、二进制持久化与次生模型回退由 utils.ts、cache.ts、binary.ts、secondary-model.ts 承担。模块内部刻意做了「传输/策略」与「渲染」的拆分network.ts只负责 URL 归一化、重定向白名单、charset/body 解码、响应头提取与 llms.txt 探测utils.ts只负责把抓到的内容变成干净的文本/markdown/html并生成 frontmatter 与面向用户的提示消息。工具参数详解createWebfetchTool在 tool.ts 中定义全部入参Zod schema下表为完整参数语义参数类型默认值说明urlURLstring必填要抓取的地址必须是合法的 HTTP/HTTPS URLformattext|markdown|htmlmarkdown抓取内容的输出格式timeoutnumber30超时秒数上限120见 constants.ts 的MAX_TIMEOUT_SECONDSpromptstring可选交给次生模型对抓取内容执行的提取任务extract_mainbooleantrue使用 Mozilla Readability 提取 HTML 正文关闭时返回整页 bodyprefer_llms_txtauto|always|neverauto优先使用/llms.txt或/llms-full.txtauto仅对文档类域名探测include_metadatabooleantrue在输出前附加 YAML frontmatter状态码、content type、charset、重定向链、缓存信息等save_binarybooleanfalse将二进制负载图片、PDF、音视频写入系统临时目录关闭时只返回元数据工具的描述字符串WEBFETCH_DESCRIPTION同样体现了定位见 constants.ts面向静态/文档页的更好提取支持 llms.txt 探测、内容聚焦的 HTML 提取、元数据、重定向与可选次生模型 prompt。核心数据流与执行流程tool.ts中的execute是唯一的编排入口。结合 codemap.md 的 Data Control Flow完整流程如下归一化与权限normalizeUrl处理 URLHTTP 升级、剥离 fragmentbuildPermissionPatterns生成权限模式与允许的 origin 集合随后ctx.ask弹出webfetch权限询问并同步计算缓存键buildCacheKeyllms.txt 探测当prefer_llms_txt为always或为auto且isDocsLikeUrl判定为文档类域名时probeLlmsText依次尝试/llms-full.txt与/llms.txt只跟随允许的重定向拒绝 HTML 与登录墙响应network.ts页面抓取回退当 llms.txt 不可用时fetchWithUpgradeFallback处理 HTTPS 升级回退、重定向强制、条件请求头用于重验证、二进制检测与有界 body 读取network.ts内容整形文本/HTML 负载经extractFromHtml、cleanFetchedMarkdown、extractHeadingsFromMarkdown、frontmatter、joinRenderedContent归一化二进制负载经saveBinary落盘并返回元数据消息utils.ts、binary.ts次生模型总结若调用方提供了prompt且配置了次生模型runSecondaryModelWithFallback会把输入截断到有界大小、为辅助会话禁用工具、在配置的模型链上重试若该步骤失败工具回退到基础抓取内容secondary-model.ts。值得注意的实现细节探测 llms.txt 与抓取页面共用一个AbortController但探测自身被runWithScopedTimeout限制在 8 秒内MAX_LLMS_PROBE_TIMEOUT_MS因此两者在单次调用内可并行受限执行。llms.txt 探测机制对于文档站点webfetch会在回退到页面本身之前先探测/llms-full.txt再探测/llms.txt。探测行为由prefer_llms_txt控制auto默认仅当域名看起来与文档相关时才探测。文档域判定逻辑isDocsLikeUrlnetwork.ts依赖 constants.ts 中的两组启发式后缀白名单.readthedocs.io、.readthedocs.org、.gitbook.io、.netlify.app、.vercel.app、docs.rs与前缀白名单docs.、developer.、dev.、wiki.always无条件探测若两种 llms.txt 变体都不存在则返回明确的失败消息buildLlmsRequiredMessagenever完全跳过探测。探测过程遵循同源重定向策略仅允许同一 origin并且会对结果做三重校验network.ts解析后的最终路径必须以/llms.txt或/llms-full.txt结尾响应不得为 HTMLcontent type 或 body 均检查不得命中登录墙titlelog in|sign in|login/title或 URL 中含 login 关键词。缓存侧同样有对应保护isInvalidLlmsResultcache.ts会逐项验证缓存的 llms 结果——路径不对、content type 是 HTML、body 以!doctype html开头或命中登录关键词时缓存条目会被驱逐并重新抓取。重定向策略与 HTTPS 升级重定向策略在 network.ts 的fetchWithRedirects中实现单次请求最多跟随MAX_REDIRECTS 10次跳转每次跳转前调用isPermittedRedirect校验协议必须一致、端口必须一致、目标不得带用户名/密码且目标 origin 必须在允许集合内跨 origin 重定向被拦截后返回blockedRedirect结果并生成buildRedirectResultMessage提示调用方直接抓取新的 URLutils.tshttp://URL 会先尝试https://upgradedToHttps标记在 HTTPS 请求因连接错误、被拦截的重定向或非 2xx 状态失败时回退到http://原始地址fetchWithUpgradeFallback。另一个值得注意的归一化细节URL 中的 fragment#anchor永远不会到达服务器RFC 3986 §3.5因此normalizeUrl会剥离 hash使同一文档的不同锚点请求共享一次网络请求与一个缓存条目。内容提取与质量信号HTML 正文提取当响应是 HTML 且extract_maintrue时utils.ts 的extractFromHtml会通过 JSDOM 构造 DOM读取title与link relcanonical提取前 12 个h1/h2/h3标题extractHeadingsFromMarkdown对 markdown 同样截取 12 个用 Mozilla Readability 解析正文new Readability(document).parse()若提取成功正文 HTML 经 TurndownService 转成 ATX 风格、fenced code block 的 markdown同时用extractStructuredText生成结构化纯文本提取失败则回退到整页 body。噪音抑制extractFromHtml的 JSDOM 构造被两层包装保护utils.tswithCssTreeWarningsSuppressedjsdom 内部用 css-tree 解析样式表而 css-tree 会绕过 virtualConsole 直接调用全局console.warn该包装临时替换console.warn屏蔽[csstree-match]前缀的警告其余警告原样放行withJsdomCssParsingErrorsSuppressed通过自定义VirtualConsole屏蔽 jsdom 的css-parsing类型错误避免解析噪音泄漏到宿主进程的 stderr 与 TUI。质量信号detectQualitySignalsutils.ts会为抓取结果打上三类信号写进 frontmatter 的quality_signals字段very_short_content正文少于 60 词possible_paywall命中付费墙/登录关键词如subscribe to continue、members only、premium content等正则模式high_boilerplate_ratio未启用正文提取、原始 HTML 字节数与渲染文本字节数之比 ≥ 10 且词数 1200提示页面样板代码占比过高。缓存设计缓存实现在 cache.ts核心参数为 50 MiB 容量上限、15 分钟 TTL 的内存 LRU 缓存。缓存键buildCacheKey对「URL extract_mainprefer_llms_txtsave_binary」做 JSON 序列化。注意渲染格式text/markdown/html不在键内——渲染结果从缓存的抓取结果派生因此切换格式不会触发冗余网络请求这是 codemap.md 强调的「按抓取形态缓存」设计规范 URL 别名cacheFetchResult会把结果同时写入请求 URL、最终 URL以及在协议/主机/端口/路径/查询完全一致时canonical URL 三个键让同文档的多个入口共享缓存条件重验证缓存条目携带ETag/Last-Modified时buildConditionalHeaders生成If-None-Match/If-Modified-Since上游返回304 Not Modified时tool.ts用陈旧条目合并新finalUrl与重定向链并标记cacheRevalidated: true后重新入缓存TTL 被刷新而无需重新下载内存计量calculateCacheSize对 llms.txt/纯文本页面将四个字段rawContent/html/markdown/text指向同一内容的场景按不同字符串去重计费避免重复占用缓存容量。二进制内容处理二进制检测遵循 network.ts 与 constants.ts 定义的流程显式二进制 MIMEimage/*、audio/*、video/*、application/pdf、application/zip、application/octet-stream直接判为二进制getBinaryKind将其归类为image/audio/video/pdf/binaryapplication/octet-stream与已知文本类型会被重查扫描前 2 KiB 的 null 字节与非打印字符looksLikeTextBody区分文本与二进制声明为text/plain但 body 看起来像 HTML 的内容会被升级为text/html以启用更好的正文提取looksLikeHtmlTextlooksHtmlPayload判定。下载限制分两档constants.ts未开启save_binary时MAX_BINARY_DOWNLOAD_BYTES 2 MiB开启save_binary时上限提升到MAX_RESPONSE_BYTES 10 MiB。超过上限的二进制内容返回metadataOnly: true的元数据消息含 content type、大小、Content-Disposition或 URL 推断出的文件名、binary kind、下载限制并取消响应体读取。开启save_binary时文件写入tmpdir/opencode-smartfetch/filenamebinaryDir可覆盖默认path.join(os.tmpdir(), opencode-smartfetch)见 tool.ts文件名经过sanitizeFilename处理过滤控制字符与:/\|?*防 Windows 保留名con/prn/aux等。readBodyLimitednetwork.ts在流式读取过程中按字节数截断超限即reader.cancel()并返回truncated标记withTruncationMarker会在输出末尾追加[..content truncated..]提示。次生模型总结链触发条件decideSecondaryModelUsesecondary-model.ts规定次生模型仅在以下条件全部成立时才被调用提供了非空prompt参数已配置至少一个次生模型抓取内容的 markdown 非空抓取内容词数 ≥ 25少于 25 词直接跳过reason 为content_too_short。模型解析优先级resolveSecondaryModelssecondary-model.ts在插件构造时于内存中解析模型链优先级从高到低webfetch.model专用模型最高优先级支持数组形式的多模型回退宿主配置中的small_model通过RuntimeConfig.smallModel()获取见 runtime.tsexploreragent 的模型RuntimeConfig.agent(explorer)librarianagent 的模型RuntimeConfig.agent(librarian)。解析完全在内存进行webfetch 热路径不读任何配置文件——所有值在插件构造时从已加载的合并配置捕获一次这一约束由 config-read-guard.test.ts 等测试保证。src/index.ts中createWebfetchTool的调用点src/index.ts正好体现了这一点webfetchModels由runtime.webfetch?.model归一化而来smallModelRef是() runtime.smallModel()的 getterexplorerModel/librarianModel通过pickAgentModelRef提取。执行方式runSecondaryModel支持两条通道v2 通道若宿主提供experimental_v2.generateTextctx.generate.text一次性生成通道则直接调用generateText(buildPrompt(...))不创建临时会话并复用与 v1 相同的buildPrompt嵌入、截断提示与 30 秒Promise.race超时语义v1 通道创建一个标题为smartfetch-secondary的临时 OpenCode 会话通过client.tool.ids查询全部工具 ID 并全部禁用tools: { id: false }随后调用client.session.prompt提交「系统提示 抓取内容 用户任务」的组合响应后带重试地删除临时会话deleteSessionSafely最多 3 次重试、间隔 500ms超时场景则先abortSessionWithTimeout再清理避免孤儿会话泄漏。输入内容会被截断到MAX_MODEL_CONTENT_CHARS 100_000字符截断时会在 prompt 末尾追加「只提供了长文档的前 N 个字符」的说明。runSecondaryModelWithFallback按模型链逐个尝试第一个返回可用文本非空且不是 No response from secondary model.的模型胜出整条链失败时tool.ts优雅回退到基础抓取内容并在 frontmatter 中记录secondary_model_skipped_reason: secondary_model_failed与错误信息。配置方式webfetch的配置项由 WebfetchConfigSchema 定义位于插件配置的webfetch键下。禁用增强版设置为false时跳过注册增强版OpenCode 使用其内置webfetch{ webfetch: { enabled: false } }schema.ts中enabled默认值为trueloader.ts在多层配置合并时会剥离各层默认的enabled字段确保「项目层未显式配置 enabled 时不会覆盖用户层的 false」这类语义正确见 loader.test.ts 的用例。专用次生模型{ webfetch: { model: openai/gpt-4o-mini } }多模型回退按优先级依次尝试{ webfetch: { model: [openai/gpt-4o-mini, anthropic/claude-3-haiku] } }带 variant 的对象形式{ webfetch: { model: [ openai/gpt-4o-mini, { id: anthropic/claude-3-haiku, variant: low-latency } ] } }model与 agent 模型配置同构string、string 数组、{id, variant}对象数组均可优先级高于small_model、agents.explorer.model、agents.librarian.model。回退链中的其他来源{ small_model: openai/gpt-4o-mini }或在插件配置的 agents 段{ agents: { explorer: { model: anthropic/claude-3-haiku }, librarian: { model: openai/gpt-4o-mini } } }配置的合并与深度合并逻辑见 loader.tsruntime.webfetch的读取见 runtime.ts。输出格式与元数据include_metadatatrue默认时文本类结果以 YAML frontmatter 前缀输出字段包括requested_url、final_url、canonical_url、status_code、source_content_type、source_kind、title、headings、used_llms_txt、extracted_main、redirect_chain、upgraded_to_https、cache_hit、cache_revalidated、word_count、quality_signals、truncated以及二进制场景的filename、binary_kind、download_limit_bytes、saved_path和次生模型场景的secondary_model格式provider/model、secondary_model_input_truncated等frontmatter 渲染逻辑见 utils.ts 与 tool.ts。frontmatter生成器对数组字段采用 YAML 列表缩进格式- item对未定义值直接跳过joinRenderedContent对 html 格式会把元数据放进!-- ... --注释对已含自身 frontmatter 的源内容则追加Source content:分隔段。注册与集成点src/index.ts 在runtime.webfetch.enabled ! false时把增强版webfetch注册进工具集覆盖 OpenCode 内置同名工具禁用条件还受 schema.ts 的enabled描述约束src/tools/smartfetch/index.ts 重新导出createWebfetchTool、WEBFETCH_DESCRIPTION与共享类型其他模块或文档可直接 import 而不触及实现文件webfetch权限可纳入插件的权限规则PermissionActionSchema位于 schema.ts配置详情参考 docs/configuration.mdcache.ts、network.ts、utils.ts被刻意设计为可复用的测试接缝缓存行为、重定向策略、llms 探测、标题提取、渲染/元数据辅助函数都可脱离完整工具入口单独验证。源码地图速查模块职责关键文件编排入口权限、缓存、llms 偏好、二进制/文本分支、元数据、次生模型集成src/tools/smartfetch/tool.ts网络层URL 归一化、重定向策略、charset/body 解码、响应头提取、llms 探测、HTTPS 升级回退src/tools/smartfetch/network.ts渲染层Readability Turndown 提取、标题清理、质量信号、frontmatter 生成src/tools/smartfetch/utils.ts缓存层LRU50 MiB / 15 分钟、条件重验证、canonical 别名、llms 结果失效src/tools/smartfetch/cache.ts二进制落盘持久化、MIME 到扩展名映射、安全文件名src/tools/smartfetch/binary.ts次生模型模型链解析、临时会话、内容截断、回退重试src/tools/smartfetch/secondary-model.ts常量超时、大小上限、文档域启发式、二进制 MIME 前缀、工具描述src/tools/smartfetch/constants.ts类型CachedFetch、BinaryFetch、FetchResult、SmartfetchOptions等src/tools/smartfetch/types.ts模块设计原则可概括为 codemap.md 强调的几点单一编排入口createWebfetchTool、传输策略与渲染彻底拆分、按抓取形态而非渲染格式做缓存键、全程优雅降级llms.txt 缺失、重定向被拦截、二进制仅元数据、次生模型失败都不会丢弃已抓取内容以及任何新增的 JSDOM 构造或 css-tree 触发点都必须包进withCssTreeWarningsSuppressed。整套实现既有详实的实操参数又有可审计的源码级策略是理解「面向文档抓取」类工具设计的完整样本。赞分享人工智能AI AgentAgent 编排AI 技能【免费下载链接】oh-my-opencode-slimLean, fine tuned Opencode multi agent suite · Mix any models · Auto delegate tasks项目地址https://gitcode.com/gh_mirrors/oh/oh-my-opencode-slim点击查看免费下载相关推荐oh-my-opencode-slim 增强版 webfetch 完全指南智能网页抓取、llms.txt 探测与次级模型提炼oh my opencode slim 增强版 webfetch 完全指南智能网页抓取、llms.txt 探测与次级模型提炼 本篇指南深入讲解 oh my o人工智能AI AgentAgent 编排AI 技能oh-my-opencode-slim 内置工具与能力全景apply_patch 救援、webfetch 增强、结构化代码搜索与后台任务控制oh my opencode slim 内置工具与能力全景apply_patch 救援、webfetch 增强、结构化代码搜索与后台任务控制 oh my op人工智能AI AgentAgent 编排AI 技能oh-my-opencode-slim 韩文版指南Opencode 多智能体编排插件的架构、安装与配置实战oh my opencode slim 韩文版指南Opencode 多智能体编排插件的架构、安装与配置实战 本文以 README.ko KR.md https人工智能AI AgentAgent 编排AI 技能上一篇PaddleSpeech python_kaldi_features 深度解析与 Kaldi compute-mfcc-feats 结果一致的 Python 特征提取实现下一篇AWTK跨平台GUI开发终极指南5步掌握SDL2桌面应用构建创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考