WebHomeTV 是基于鱼佬 WebHomeTV 二次开发的 Android 影音应用，它保留了点播、直播、解析、投屏等完整能力，并重点增强了WebHome 扩展脚本体系：你只需在真实影视网站的页面上注入一段 JavaScript，就能调用 App 内置的fmSDK，把网盘、磁力、直链一键送入原生播放器，无需重写整个网站。本文是一份面向新手的快速上手教程，带你 10 分钟从零写出第一个可用的 WebHomeTV 扩展脚本。

一、WebHome 扩展脚本是什么？

一句话概括：WebHome = 一个真实网页 + App 注入的fmSDK + 你写的扩展脚本。

App 在 WebView 里加载你的影视网站时，会自动注入window.fm命名空间，你的脚本就可以：

• 拦截页面上的下载/播放按钮，改走 App 原生播放链路；
• 把网盘分享（夸克、阿里、百度等）、磁力、电驴、迅雷链接推给 App 统一解析；
• 嗅探页面运行时动态出现的 m3u8/mp4 直链；
• 清理弹窗广告、给手机/电视两种形态重排版面；
• 用GM_addStyle注入样式、GM_getValue保存脚本配置。

完整的扩展开发指南在 webhome-devkit/README.md，本文只挑快速上手必需的部分讲。

二、10 分钟跑通第一个扩展

跟着下面 5 步走，就能看到你网站页面上的第一个"App 增强"效果：

1. 准备站点：确保点播配置里有一个带homePage的 WebHome 站点（api为csp_Builtin类型）。
2. 打开扩展管理：App 内进入 设置 → 增强功能 → WebHome 扩展，确认总开关已开启（默认开启）。
3. 新增代码源：点"新增" → 选择"代码"，绑定你的站点，粘贴这段最小脚本：

GM_log("hello", location.href); GM_addStyle("body{outline:4px solid #0f766e;}"); window.addEventListener("fmsdk", function () { fm.ext.toast("扩展已生效"); });

4. 保存即刷新：保存后 App 会自动刷新 WebHome 页面（扩展配置变更有 5 秒节流，避免连续保存反复刷新）。
5. 验证成功：页面出现绿色描边和"扩展已生效"的 toast；点"Debug"打开调试工作台，Console 里能看到[fm-ext] <id> hello ...。

✅ 看到绿色描边，恭喜你的 WebHomeTV 扩展脚本已经跑起来了。

三、三个最核心的 fm 接口

脚本真正"注入原生播放能力"，靠的是下面三个接口（参数细节见 webhome-devkit/README.md 第 7 章）：

最常用的是前两个。判断资源类型后分流即可：

function openResource(url) { var type = classify(url); // 自己写正则：magnet / quark / aliyun / media ... if (type === "media") { return fm.play(url, document.title, { headers: { Referer: location.href } }); } return fm.pan.play({ type: type, url: url, title: document.title }); }

💡 注意：fm.play/fm.pan.play都返回 Promise，记得加catch并在失败时fm.ext.toast()给用户反馈，不要静默失败。

四、扩展脚本从哪里加载？

WebHomeTV 支持三层扩展来源，优先级依次升高，同id时后者覆盖前者（调试改版时常用这个特性）：

1. 全局扩展：点播配置根级webHomeExtensions，必须用cspKeyRegex限定站点，默认禁用；
2. 站点扩展：站点对象里的extensions字段，天然绑定所属站点，默认启用——推荐新手用这里；
3. 用户扩展源：App 内"WebHome 扩展"管理页新增，支持文件、链接、代码、表单、文本 JSON 五种方式。

站点内联写法非常简单，甚至可以直接填一个远程 JS 地址：

{ "key": "mysite", "name": "我的站", "type": 3, "api": "csp_Builtin", "homePage": "https://example.com/", "extensions": [{ "id": "mysite-native-router", "runAt": "document-end", "js": ["https://example.com/mysite.js"] }] }

远程脚本会"网络优先"下载并缓存到 App 缓存目录，断网时自动回退缓存副本，所以扩展离线也能用。

五、双端适配：一份脚本同时服务手机和电视

WebHomeTV 同时跑在手机版和 TV 版上，脚本要用window.fongmiClient.isLeanback判断当前形态，而不是靠屏幕宽度猜：

• 手机端：注入按钮热区不小于 44×44 px，吸底元素避开手势条（用max(var(--fm-safe-bottom, 0px), env(safe-area-inset-bottom, 0px))去重）；
• 电视端：卡片/按钮补tabindex="0"让遥控器可聚焦，焦点样式用outline+ 背景提亮，且必须写:focus而不是:focus-visible（旧内核会丢弃整条规则）；
• 通用：布局尺寸读--fm-web-width/--fm-web-heightCSS 变量，监听fmviewport事件响应窗口变化。

六、别从零手写：模板与实战示例清单

仓库的 webhome-devkit/templates/extensions/ 目录提供了一整套可直接改CONFIG起飞的模板：

webhome-devkit/examples/extensions/ 下还有 4 个真实站点的实战案例（资源聚合面板、详情页重排、按集解析复用站点解密函数等），照着改是最快的学习路径。

七、调试与常见坑速查

开发主力工具是扩展管理页的Debug 调试工作台：Console（GM_log输出）、Network（Native 请求记录）、Elements（DOM 候选选择器）、代码编辑保存即预览。

⚠️ 最大的一个坑：旧电视盒子的 WebView 可能还是 Chromium 50~70，语法基线必须控制在 ES2017（async/await及以下）。可选链?.、空值合并??、逻辑赋值||=、正则命名捕获等写法会导致整个扩展静默消失（解析阶段就失败，连报错事件都不触发）。写完脚本全文搜索一遍这些字符再分发。

八、发布前自检清单

📋 分发你的 WebHomeTV 扩展脚本前，逐项确认：

• id/version固定（远程分发必须，避免自动 id 导致用户开关状态丢失）；
• 没有资源的页面不注入多余按钮，搜索、翻页、登录等原站功能不受影响；
• 所有 Promise 都有catch，失败有 toast 或GM_log；
• 无语法红线：?.、??、||=、replaceAll、structuredClone等一个都没有；
• CSS 避开了:is()/:has()/:focus-visible，flexgap有 margin 兜底；
• 没有把账号、Cookie 等隐私数据输出到远程日志。

完整清单和 16 章 AI 自动开发协议见 webhome-devkit/README.md 第 15、16 章；fmSDK 全部方法、WebHome 首页开发和网盘检测细节，见 webhome-devkit/docs/应用完整开发文档.md。

写在最后

WebHomeTV 扩展脚本的设计哲学是"增强而不是替换"——网站照常浏览，资源点一下就走 App 原生播放。从最小脚本到远程分发托管，整个链路都已经在 App 内闭环：代码源调试、Debug 工作台预览、保存即刷新。现在打开你的影视网站，10 分钟后让它拥有 App 原生播放能力吧。