AGENTS.md

项目简介

MoePlayer —— 一款中文友好的开源网页视频播放器（MIT 协议），fork 自已停止维护的 ckplayer X3。支持 mp4 / flv / m3u8 / ts 等格式，点播、直播、直播回放，PC 与移动端 H5。

目标定位：中文文档 + 主流浏览器/手机 H5 支持 + 官方 Moodle media 插件（media_moeplayer，独立仓库）。

注意：当前处于改造阶段 2（改名 + 模块化）。改名已完成：目录 moeplayer/、全局变量/API 为 MoePlayer（语言包全局变量 moeplayerLanguage）；单文件已拆分为 ES Module（源码在 src/，经 rollup 打包为 UMD 产物）。主函数 moeplayerEmbed 尚未内部拆分，仍是一个 ~6400 行的巨大函数，位于 src/core/moeplayerEmbed.js。

目录结构

├── index.html            # 演示/测试页（含 API 调用示例）
├── package.json          # npm 工程化入口,依赖与构建脚本
├── rollup.config.js      # rollup 配置:src/ 打包为 UMD 产物 + terser 压缩
├── scripts/build-css.js  # 构建脚本第二步:base.css + 主题拼接为三个皮肤产物
├── scripts/copy-libs.js  # 构建脚本第三步:从 node_modules 拷贝运行时库
├── src/                  # 播放器源码(ES Module,2026-07 由单文件拆分而来)
│   ├── index.js          # 入口:export default moeplayerEmbed
│   ├── language.js       # 默认中文语言包
│   ├── defaults.js       # videoObjectDefault 默认配置
│   ├── core/moeplayerEmbed.js # 主函数,【整体搬自旧单文件,内部未拆分,逻辑零改动】
│   ├── utils/            # 工具函数:type/dom/format/net/cookie/path
│   └── css/              # 皮肤源码(2026-07 皮肤系统现代化:CSS 变量 + SVG mask 图标)
│       ├── base.css      # 三皮肤共用结构样式 + 默认主题变量(--moe-* 定义在 .moeplayer 等作用域)
│       └── themes/       # default.css / red.css / ixigua.css,只覆盖 --moe-* 变量值
├── moeplayer/            # 播放器本体,部署时整个上传到网站
│   ├── js/moeplayer.js   # UMD 产物,【由 npm run build 自动生成,勿手改】
│   ├── js/moeplayer.min.js # 压缩版,同上
│   ├── css/moeplayer.css # 默认皮肤,【由 build-css.js 拼接生成,勿手改】
│   ├── css/moeplayer.red.css # 红色皮肤,同上
│   ├── css/moeplayer.ixigua.css # 西瓜皮肤(浅色),同上
│   ├── language/         # 语言包：zh.cn.js（默认内嵌）、zh.hk.js、en.js
│   ├── hls.js/           # hls.min.js,【由构建从 npm 包拷贝,勿手改】
│   └── mpegts.js/        # mpegts.js,同上(flv 播放也基于它,flv.js 已于阶段4移除)
└── video/                # 演示用视频与封面

构建与依赖

安装：npm install
构建：npm run build(即 rollup -c && node scripts/build-css.js && node scripts/copy-libs.js) —— 做三件事：
1. rollup 把 src/ 的 ES Module 打包为 UMD：moeplayer/js/moeplayer.js,并经 @rollup/plugin-terser 生成 moeplayer.min.js(保留 软件名称|版权 头部注释)
2. scripts/build-css.js 把 src/css/base.css 与各主题(src/css/themes/*.css)拼接为自包含的 moeplayer/css/moeplayer[.red|.ixigua].css(加版权注释头,用户只引一个文件,无 @import)
3. scripts/copy-libs.js 从 node_modules 拷贝 hls.js / mpegts.js 的产物及 LICENSE 到 moeplayer/ 对应目录
改动 src/ 后必须执行 npm run build 重新生成产物；moeplayer/js/ 与 moeplayer/css/ 下的 js、css 均为生成物,勿手改
皮肤机制：全部主题相关值是 CSS 自定义属性(--moe-*),定义在 .moeplayer, .moeplayer-menu, .moeplayer-error 作用域(菜单/错误框挂在 body 下)；按钮图标为 SVG data-URI + CSS mask,颜色跟随 --moe-icon-color,不再使用雪碧图 PNG；换肤=覆盖变量,新增主题=在 src/css/themes/ 加一个变量文件并登记到 scripts/build-css.js 的 themes 清单
升级依赖：改 package.json 版本号后 npm install && npm run build
Moodle 插件资源同步:npm run sync-moodle 把构建产物 moeplayer/ 拷贝到同级目录的 moodle-media_moeplayer 插件仓库(播放器升级后执行,插件仓库另行提交)
运行时机制：播放器用 getPath() 定位自身所在目录，按需动态 <script> 加载同级 hls.js/ 等目录里的文件，库挂全局变量（Hls/mpegts）。这个目录结构约定不能破坏
插件机制：未显式指定 plug 时按 URL 扩展名自动识别插件（.m3u8→hls.js，.flv/.ts/.m2ts→mpegts.js，识别不到走原生播放），只填 vars['plug']，canPlay 原生分流不变（iOS 上 m3u8 仍走原生 HLS）；flv 播放基于 mpegts.js，plug:'flv.js' 保留为兼容别名；plug:'dash.js' 已移除
rollup 配置要点：treeshake: false(完整保留所有工具函数,与旧单文件一致)；UMD name: 'MoePlayer'、exports: 'default',CJS/AMD/全局变量行为与旧 UMD 等价

测试方式

自动化冒烟测试：npm test(需先 npm run build)——Playwright 无头 Chrome 加载演示页,覆盖初始化/播放/暂停/seek/进度条点击/皮肤加载/JS 错误,脚本在 scripts/smoke.test.js
手动回归：npm run serve 起本地服务器(scripts/serve.js,支持 Range 请求),打开 http://localhost:8000。不要用 python3 -m http.server——它不支持 Range 请求,会导致 mp4 无法 seek(点击/拖动进度条静默失效)
移动端回归:iOS Safari 与微信内置浏览器各过一遍全屏与进度拖动(目前需真机手动)

代码风格

注释与文档使用中文（项目惯例）
src/ 为 ES Module 源码,但函数体保持旧单文件的 ES5 风格（var、函数式）,阶段 2/3 重构前不要在函数体内引入 ES6+ 语法；只允许模块级的 import/export 语句
主函数 moeplayerEmbed 整体搬迁、内部逻辑零改动；语言包替换机制（window.moeplayerLanguage）在其内部,勿动
moeplayer/ 下由构建生成的文件（js 两个产物、css 三个皮肤、hls.js/mpegts.js 目录内容）不要手动修改

Git 约定

主仓库在私有 Gitea：git.eryang.wang（待迁移，当前 origin 还是上游 gitee）
未经用户明确要求，不执行 git commit/push 等变更操作

改造路线图

~~工程化：npm + 构建脚本 + 依赖 npm 化~~（已完成）
改名 ckplayer → MoePlayer（已完成）+ 单文件拆分为 ES Module（已完成,src/ + rollup 打包；主函数 moeplayerEmbed 内部尚未拆分）+ README 重写
核心与 UI 分层、皮肤改用 CSS 变量 + SVG 图标
~~协议插件化：按 URL 自动识别 m3u8/flv/ts 插件、flv 改用 mpegts.js、移除 flv.js~~（已完成）；移动端 H5 兼容专项（审查已完成，修复待排期）
Moodle media 插件（独立仓库 moodle-media_moeplayer）
发布：Gitea 主仓库 + 中文文档站

7.0 KiB Raw Permalink Blame History Unescape Escape