OmniBox Spider Development

Description

--- name: omnibox-spider description: |- Develop, write, debug, and improve OmniBox spider sources (爬虫源). Use when the user asks to write an OmniBox spider script (JS or Python), create a new spider source, fix or debug an existing OmniBox source, convert a third-party video site API into an OmniBox spider, or ask questions about OmniBox spider development (API, SDK, annotations, return formats, environment variables, etc.). Also triggers on phrases like 写爬虫, OmniBox 爬虫, 爬虫源, spider source, OmniBox 脚本, 帮我写采集站脚本. --- # OmniBox Spider Skill > skill_meta > - last_updated: 2026-04-15 13:12 Asia/Shanghai > - source_docs: https://omnibox-doc.pages.dev/spider-development/introduction > - source_scope: introduction + getting-started + script-annotation-attributes + api-reference + sdk + repo env scan > - sync_note: 每次改动后如需分发，应重新打包 skill 文件 用于开发、编写、调试和改进 OmniBox 爬虫源。优先遵循最新官方文档： - https://omnibox-doc.pages.dev/spider-development/ ## 先做什么 收到 OmniBox 爬虫相关任务时： 1. 先读一次记忆（至少读当天 daily memory；如与历史决策/偏好有关，再补读相关 memory） 2. 再判断是 **JS** 还是 **Python** 3. 再判断是： - 新写采集站脚本 - 修 bug / 对接新站 - 网盘源 / 推送源 - 只问 API / SDK / 返回格式 4. 按需读取 references 中对应页面，不要一上来把所有文档都塞进上下文 ## 核心规则 ### 1) handler 签名统一 所有 handler 优先写成： - `(params, context)` 不要依赖全局变量读取调用上下文。 ### 2) 5 个方法按需实现 | 方法 | 用途 | |---|---| | `home` | 首页分类和推荐 | | `category` | 分类分页列表 | | `detail` | 视频详情 | | `search` | 搜索 | | `play` | 播放地址 | - 推送型脚本：通常只实现 `detail` + `play` - 常规影视源：建议实现全部 5 个 - 另外要记住：官方现在明确 `home()` 还可以返回 `filters` 与 `banner`，不是只有 `class + list` ### 3) `context` 不只看 `from`，还要知道另外 3 个字段什么时候该用 `context` 里当前官方明确写到： - `baseURL` - `headers` - `sourceId` - `from` 其中最常用的是： - `from`：端差异分支（`web` / `tvbox` / `uz` / `catvod` / `emby`） - `headers`：需要透传客户端 UA / Cookie 时使用 - `baseURL`：需要拼绝对链接时使用 - `sourceId`：涉及源内数据能力（如历史 / 收藏 / 标签页）时要知道它会被 SDK 读取 如果网页端、TV 端、UZ 端行为不同，统一从 `context.from` 分支；如果要拼链接、透传请求头、调用源内数据页，再分别考虑 `baseURL / headers / sourceId`。 ### 4) `play` 优先返回推荐格式 优先： ```js { urls: [{ name, url }], flag, header, parse, danmaku } ``` 说明： - `parse=0`：直链 - `parse=1`：需要客户端嗅探，**仅 ok影视 app 有效** - 其他客户端通常会忽略 `parse=1` ### 5) 错误必须安全返回 - JS：`try/catch` - Python：`try/except` - 出错时返回空结构，不要直接崩 ### 6) 必须打日志 至少记录： - 入口参数 - 请求 URL / 关键分支 - 返回数量 - 失败原因 ### 7) 环境变量优先复用现有命名（强制） 写新脚本时，先查已有变量，再决定是否新增： - 普通采集站 API → 优先 `SITE_API` - 弹幕接口 → 优先 `DANMU_API` - 网盘优先级 → 优先 `DRIVE_ORDER` - 网盘类型配置 → 优先 `DRIVE_TYPE_CONFIG` - 源名称映射 → 优先 `SOURCE_NAMES_CONFIG` - PanCheck / 盘搜 → 优先 `PANCHECK_*`、`PANSOU_*` - Emby → 优先 `EMBY_*` - 小雅 / AList / TVBox → 优先 `XIAOYA_*`、`ALIST_TVBOX_TOKEN` - 站点地址配置 → 优先沿用已有 `XXX_HOST` 风格 如果确实要新增变量，必须： 1. 命名清晰 2. 与现有变量不冲突 3. 在交付说明里解释为什么不能复用旧变量名 - 解析接口这类可跨源复用的配置，优先抽成全局环境变量（如 `PARSE_APIS`），不要无必要给每个源都造一套 `XXX_PARSE_APIS`。 ### 8) 每次改脚本后必须升级 `@version`（强制） 无论是修 bug、加功能、改排序、改刮削、改弹幕、改播放历史、改环境变量逻辑，只要脚本有变化，就必须同步升级 `@version`。 ### 8.5) 新建脚本默认必须补 `@downloadURL`（强制） - 只要是新建并准备落到 OmniBox-Spider 仓库的脚本，默认必须补 `@downloadURL`。 - `@downloadURL` 默认指向仓库主分支最终落地路径的原始文件地址；不要偷懒留空，也不要继续指向工作区调试文件名。 - 若最终仓库文件名不带 `.omnibox`，则 `@downloadURL` 也必须同步使用最终文件名。 默认规则： - 小修复 / 不改主要行为 → 升 **patch**（如 `1.1.1 -> 1.1.2`） - 新功能 / 明显增强 / 兼容旧配置 → 升 **minor**（如 `1.1.1 -> 1.2.0`） - 破坏兼容 / 大改结构 / 需要重配 → 升 **major**（如 `1.1.1 -> 2.0.0`） 以后只要我帮你改 OmniBox 脚本，默认都要： 1. 检查并修改 `@version` 2. 在交付说明中说明为什么升 patch / minor / major ### 9) 每次改脚本后必须做静态检查（强制） 每次修改完成后，至少做一次静态检查，最低要求是脚本在语法/编译层面正常： - JavaScript → `node --check script.js` - Python → `python3 -m py_compile script.py` 这一步是交付前必做项。不能只凭肉眼判断“看起来没问题”。 如果条件允许，还应顺手检查： 1. 关键变量是否误删 2. 新逻辑是否插在正确函数中 3. `@version` 是否已同步升级 ### 10) 每次改脚本后必须做关键路径回归检查（强制） 静态检查通过后，仍需检查关键运行路径是否被破坏。至少确认： - `detail()` 返回结构正常 - `vod_play_sources` 在有数据时非空 - `play()` 返回 `urls` - 关键环境变量没有被误删（如 `SOURCE_NAMES_CONFIG`） ### 11) 默认采用“最小改动”策略（强制） 修改 OmniBox 脚本时，默认遵循： 1. 先复制副本再改，尽量不碰源文件 2. 一次只解决一个明确目标 3. 不顺手重构无关逻辑 4. patch 前先确认插入锚点存在 ### 11.5) 站点如果是“下载区 / 网盘分享”模式，先按网盘源建模，不要把分享链接直接当剧集 如果详情页展示的是： - 网盘分享链接 - 下载地址 - 复制链接 - 115 / 百度 / 夸克 / 阿里 等分享 默认优先建模为： - **每个分享链接 = 一条线路** - **线路下再展开该分享中的具体视频文件 / 剧集** 而不是： - 直接把分享链接本身当成一个 episode - 或把下载按钮 URL 当成最终播放地址 优先顺序： 1. 先确认站点是“在线播放型”还是“下载区 / 网盘分享型” 2. 如果是网盘分享型，优先走 SDK： - `getDriveInfoByShareURL` - `getDriveFileList` - `getDriveVideoPlayInfo` 3. 只有在确认分享本身就是最终文件直链时，才把链接直接作为 episode 返回 ### 11.6) 多线路是否展开，优先遵循仓库现有配置，不要默认所有网盘都多线路 - 不要默认所有网盘都自动生成 `服务端代理 / 本地代理 / 直连`。 - 先看仓库同类网盘源的既有配置与命名约定，再决定是否展开多线路。 - 如果没有明确需求，默认优先给最小必要线路（通常 1 条）。 ### 11.7) 线路显示名优先信“明确证据”，不要盲信 SDK displayName - 如果分享 URL host 已经明确表明盘型（如 `115cdn.com / 115.com`），显示名应优先信 URL 自身，而不是盲信 SDK 误识别出来的 `displayName`。 - 同类网盘有多个分享时，应做稳定区分（如 `115网盘1 / 115网盘2`），不要让两个不同分享共用同名线路。 ### 12) 并发优化默认策略 - `play()`：可将播放地址链路与元数据/弹幕链路并行，优先保证主播放链路成功。 - `detail()`：默认不要全量 `Promise.all` 打满，优先使用限并发（建议 4）。 - 元数据、弹幕、刮削增强链路失败时，应尽量降级，不阻塞主链路返回。 ### 13) 优先考虑新版 SDK 的缓存能力 - 官方最新版 SDK 已明确提供：`getCache` / `setCache` / `deleteCache`。 - 对高频、重复、跨请求的解析结果，优先考虑缓存，而不是每次都重新打全链路。 - 尤其适合缓存： - 搜索结果 - `getDriveInfoByShareURL()` 的识别结果 - `detail()` 中的文件列表 / 递归视频文件结果 - 设计缓存时要注意：key 稳定、过期时间合理、失败时安全降级。 ### 14) `getVideoMediaInfo` 要晚用，不要太早打在搜索阶段 - 官方最新版 SDK 已明确提供 `getVideoMediaInfo(playUrl, headers)`（需完整版）。 - 它更适合在已经拿到真实可播地址后，用于： - 获取总时长 / 文件大小 - 给 `addPlayHistory` 写入 `totalDuration` - 在详情页里补媒体信息 - 不建议在搜索阶段大规模调用，否则很容易拖慢首屏返回。 ### 15) 新版 SDK 现在明确支持“源内数据页 + 全站追剧” - 官方文档现已明确：`getSourceFavoriteTags()` 可读取当前源收藏标签；`getSourceCategoryData(categoryType, page, pageSize)` 可读取源内分类数据。 - `getSourceCategoryData()` 当前官方写明支持： - `history`：当前源播放历史 - `favorite`：当前源收藏 - `follow`：**全站追剧（与当前源无关）** - 以及其它收藏标签名（可先 `getSourceFavoriteTags()`） - 如果用户要做“播放历史 / 收藏 / 追剧 / 收藏标签页”，优先考虑直接复用这组 SDK，而不是手搓本地存储或自造接口。 ### 16) 最新 SDK 文档下，优先把 `sdk-api.md` 当主入口，不再假设 JS / Python 页面分裂演进 - 官方当前 `sdk` 页已是统一入口，JavaScript / Python 共用同一套函数名。 - 以后回答 OmniBox SDK 问题时，默认优先同步： - `request / log / getEnv` - `getSourceFavoriteTags / getSourceCategoryData` - `getDriveFileList / getDriveVideoPlayInfo / getDriveInfoByShareURL / getDriveShareInfo` - `processScraping / getScrapeMetadata` - `sniffVideo / getVideoMediaInfo / getDanmakuByFileName / getAnalyzeSites / addPlayHistory` - `getCache / setCache / deleteCache` - 若旧经验与新文档冲突，优先以最新官方 `sdk` 页为准，再做实测验证。 ## 常见开发策略 ### 普通采集站 1. 先封装请求函数 2. 把站点字段映射为 OmniBox 标准字段 3. `detail` 中构建 `vod_play_sources` 4. `play` 返回直链或解析信息 ### 推送源 - 只做 `detail` + `play` - `detail` 负责把外部链接整理为线路和剧集 - `play` 负责最终播放地址 ### 网盘源 优先考虑这些 SDK： - `getDriveFileList` - `getDriveVideoPlayInfo` - `getDriveInfoByShareURL` - `processScraping` / `getScrapeMetadata` - `getDanmakuByFileName` ## references 读取指引 ### 只想快速上手 / 新建脚本 读： - `references/getting-started.md` - `references/js-template.md` 或 `references/py-template.md` ### 想确认返回结构 / handler 规范 读： - `references/api-reference.md` ### 想确认脚本头注释属性 读： - `references/script-annotation-attributes.md` ### 需要统一查看官方 SDK 能力（推荐） 读： - `references/sdk-api.md` 如果用户明确问“最新 SDK 有没有新增什么”“文档里现在支持哪些能力”“follow / 收藏标签 / 缓存 / 媒体信息怎么用”，先优先读 `references/sdk-api.md`。 ### 写 JavaScript 爬虫 读： - `references/javascript-sdk.md` - `references/js-template.md` - `references/sdk-api.md` ### 写 Python 爬虫 读： - `references/python-sdk.md` - `references/py-template.md` - `references/sdk-api.md` ### 需要理解整体能力与上下文 读： - `references/introduction.md` ### 需要复用仓库既有环境变量 读： - `references/environment-variables.md` - `references/environment-variables-cheatsheet.md` ### 需要判断这次该升哪个版本号 读： - `references/versioning.md` ### 需要确认修改后至少语法/编译正常 读： - `references/validation.md` ### 需要读取实战经验与防回归规则 读： - `references/lessons-learned.md` ### 用户明确要的是 ds / drpy-node / `var rule = {}` 读： - `references/ds-template-notes.md` 并先做 3 个判断： 1. 这是 **OmniBox 五方法 spider**，还是 **drpy-node `var rule`** 2. 当前卡点是 **建源 / 结构解析 / 播放链 / 仓库交付** 哪一层 3. 这次目标是先做 **最小可用版本**，还是已经进入 **上传前收尾** ## 重要提醒 - 官方最新文档在爬虫开发部分已收拢为：`introduction / getting-started / script-annotation-attributes / api-reference / sdk`，后续同步时优先按这 5 个页面校准。 - `home()` 官方现在明确可选返回： - `filters` - `banner` 写首页型源时别把它误以为只有 `class + list`。 - `category()` / `search()` 推荐返回里除了 `page / pagecount / list`，还应尽量补 `total`。 - 环境变量： - JS 优先 `process.env.KEY` - Python 优先 `os.environ.get("KEY")` - HTTP 请求返回后，通常要手动解析 JSON - 文档里明确了 `context` 是 Runner 注入，不要自己发明额外调用方式 - `vod_tag: "folder"` 是目录项，不是播放项 - UZ 端有 `search: 1` 这种专用字段，必要时才加 - `@version / @downloadURL / @indexs / @push / @dependencies` 是当前官方明确说明会被后端实际解析的注释属性；不要凭印象扩展“还有别的也会生效”。 - 磁力 / 电驴类详情分集，默认优先返回“短标题 + 简单 playId”结构；除非确有必要，不要在 `episodes[].playId` 里塞大段 JSON 元数据，否则某些端可能出现按钮空白、详情渲染异常或播放取值异常。 - 学到 drpy-node 体系后，默认把它当作 **另一种输出目标与工作流参考**，不是让 OmniBox 源直接套 `var rule = {}`。能吸收的是：分诊顺序、分阶段交付、播放专项验收红线；不能把宿主 API、全局函数、仓库上传动作原样搬进 OmniBox 运行器。 - 新建源时，默认先追求“最小可用链路”而不是一步做满：优先顺序通常是 `home/category/search/detail` 可用，再补稳定 `play()`，最后才是上传仓库、标签整理、额外增强。 - 修播放时，不能只因为返回了页面地址 / `parse:1` / 某个播放器壳就宣称“已修好”；至少要继续确认它不是假播放、空壳页、`play.html` 中转页或仅前端可见但客户端不可播。 - 遇到详情页先返回一层 `document.cookie = "fl_js_validator_..."; window.location.reload();` 这类 JS validator 页面时，不要把这层 HTML 当真实详情；应优先模拟浏览器补 cookie 后重试，再决定是否回退 API。 - 详情页拿不到真实播放列表时，不要伪造“主线路 / 第1集$详情页URL”这类假线路来凑结构；宁可明确返回空线路或走真实 API 回退，也不要制造会误导排障的假成功。 - 给站点补筛选前，先区分“独立子分类入口”和“真正的 class 筛选”：像 `韩剧 / 日剧 / 泰剧 / 欧美剧` 这类很多站其实是独立 `type_id`，不是 `class=韩剧` 这种剧情筛选值。 ## 交付风格 - 默认优先使用中文：日志、代码注释、变更说明、PR 标题/正文、交付说明等，除非上游项目或外部接口明确要求英文。 - 如果必须混用中英，优先保证对人看的说明部分为中文；仅保留必要的英文标识、变量名、接口字段、提交前缀等。 - 使用 GitHub CLI 创建/编辑 PR 时，正文优先写入 `.md` 临时文件后用 `--body-file` 传入，避免把字面 `\n` 误提交成一整段导致排版混乱。 - 涉及 OmniBox 网页端播放问题时，交付说明和 PR 描述要明确区分：是 `playId` / URL 透传问题、`context.from === "web"` 下 header 不可靠问题，还是嗅探/代理兜底问题，不要笼统写成“修复播放”。 当用户让你“写 OmniBox 爬虫”： - 默认直接给出可运行脚本 - 标明需要的环境变量 - 优先复用现有环境变量命名 - 标明注释属性 - 如果站点存在不确定字段，明确写 TODO / fallback - 必要时附带调试建议，但不要长篇空谈

Security Status