From 58a648fd051c1e14fbca14c132fc1750a976d175 Mon Sep 17 00:00:00 2001 From: Harvey Zhao Date: Wed, 16 Sep 2026 11:26:06 +0800 Subject: [PATCH] docs(maintenance): [DOC-03] align AI entrypoints with migrated modules --- AGENTS.md | 37 ++++++++++++++----- .../2026-09-16-DOC-03-ai-entrypoints.md | 14 +++++++ refactor/plan.md | 2 +- refactor/progress.md | 7 ++++ refactor/tasks.json | 3 +- 5 files changed, 51 insertions(+), 12 deletions(-) create mode 100644 refactor/changes/2026-09-16-DOC-03-ai-entrypoints.md diff --git a/AGENTS.md b/AGENTS.md index af31a9ec3..f84c5721d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -150,18 +150,26 @@ For proxy/plugin work, prefer validating on the local demo page rather than reas ### Ecosystem packages -Most ecosystem packages follow this pattern: +Migrated ecosystem packages follow this pattern: ```text packages// - src/index.js + src/index.ts + src/*.ts # internal modules; see the package maintenance map src/*.less # optional - types/*.d.ts # optional but preferred for public APIs + types/*.d.ts # public compatibility declarations + ARCHITECTURE.md # maintenance map, or a maintenance section in README.md README.md package.json dist/* ``` +Read the package maintenance map before changing module ownership. Some packages +also expose accurate types through `/runtime`, with `.d.mts`/`.d.cts` declarations. +Do not replace historical root declarations with internal implementation types; +follow [the approved type policy](refactor/type-compatibility-policy.md) and each +package's recorded compatibility decisions. Check package.json for exact exports. + ### Demo and docs assets - `docs/assets/example/*.js`: runnable browser examples @@ -281,7 +289,8 @@ Keep examples realistic and runnable. Prefer local demo URLs or stable public sa ## Code Quality Expectations -- Follow existing plain JavaScript style in the repo. +- Follow the existing TypeScript style for migrated production modules and the + existing JavaScript style for tests, launchers and documented legacy exceptions. - Use ASCII unless a file already requires otherwise. - Match the minimal-comment style of neighboring files. - Avoid unnecessary abstraction; this codebase generally prefers direct implementation. @@ -314,20 +323,28 @@ This package now depends on modern `mediabunny` and supports HLS through `mediab Files to understand first: -- `packages/artplayer-proxy-mediabunny/src/index.js` -- `packages/artplayer-proxy-mediabunny/src/VideoShim.js` -- `packages/artplayer-proxy-mediabunny/src/MediaBunnyEngine.js` -- `packages/artplayer-proxy-mediabunny/src/input.js` -- `packages/artplayer-proxy-mediabunny/src/m3u8.js` +- `packages/artplayer-proxy-mediabunny/ARCHITECTURE.md` +- `packages/artplayer-proxy-mediabunny/src/index.ts` +- `packages/artplayer-proxy-mediabunny/src/VideoShim.ts` +- `packages/artplayer-proxy-mediabunny/src/MediaBunnyEngine.ts` +- `packages/artplayer-proxy-mediabunny/src/input.ts` +- `packages/artplayer-proxy-mediabunny/src/m3u8.ts` Key expectations: -- HLS source detection should happen in `input.js` +- HLS source detection should happen in `input.ts` - track selection should use actual pairable audio/video relationships - selector UI should mirror the behavior of `artplayer-plugin-hls-control` - selector cleanup is required when a later source no longer supports the same controls - avoid duplicate readiness events during load and track switches +For sustained playback, use `yarn test:mediabunny-soak` with explicit artifacts and +media; see [the long-test procedure](refactor/changes/2026-09-16-PKG-MB-09-hour-soak.md). +It shares port 8084 with ordinary browser tests. Do not start another browser +server or change the measured source, artifacts or media during a live run. +Use its live process handle and per-case progress samples to check progress; +an old report or a start snapshot does not prove current execution or completion. + ## When Unsure Start with the nearest sibling implementation instead of inventing a new pattern: diff --git a/refactor/changes/2026-09-16-DOC-03-ai-entrypoints.md b/refactor/changes/2026-09-16-DOC-03-ai-entrypoints.md new file mode 100644 index 000000000..0b23c7943 --- /dev/null +++ b/refactor/changes/2026-09-16-DOC-03-ai-entrypoints.md @@ -0,0 +1,14 @@ +# DOC-03：校正 AI 接续入口 + +核对当前源码后，发现根 `AGENTS.md` 仍列出 MediaBunny 五个不存在的旧 `.js` 文件， +通用包示例仍是 `src/index.js`，代码风格要求也未区分已迁移的 TypeScript。 +这些是维护入口的过期信息，不是重新开展用户保留的正式复盘。 + +本次改为实际 `.ts` 路径，优先链接 MediaBunny 的模块维护地图；通用包布局补充内部 +TS 模块和架构说明，并明确旧根声明与可选 `/runtime` 的区别，引用已批准的类型规则。 +同时记录普通浏览器与长测共用 8084，运行中必须保持被测输入不变，不能用旧报告代替 +活跃进程或终结结果。 + +验证仅针对文档：核验 AGENTS 中非占位的仓库路径存在，计划/链接校验与 diff 检查通过。 +没有改源码、测试、产物、依赖或公开 API；不重复运行播放器测试，也不干扰正在进行的 +MediaBunny 长测。DOC-03 已完成状态不变，本次是其维护记录的独立修正提交。 diff --git a/refactor/plan.md b/refactor/plan.md index 49e06de02..8460da2c3 100644 --- a/refactor/plan.md +++ b/refactor/plan.md @@ -507,7 +507,7 @@ - DOC-01: [记录](progress.md) - DOC-02: [记录](progress.md) -- DOC-03: [记录](progress.md) +- DOC-03: [记录](progress.md) [记录](changes/2026-09-16-DOC-03-ai-entrypoints.md) - DOC-04: [记录](progress.md) - DOC-05: [记录](changes/2026-09-10-DOC-05-task-commits.md) - DOC-06: [记录](changes/2026-09-10-DOC-06-dependencies-and-scripts.md) diff --git a/refactor/progress.md b/refactor/progress.md index 6c29a15e5..170f0bcb3 100644 --- a/refactor/progress.md +++ b/refactor/progress.md @@ -1,5 +1,12 @@ # 进度与证据 +## DOC-03 校正根 AI 接续指引 + +根AGENTS仍引用MediaBunny五个旧JS路径及过期源码风格，现已核对并改为实际TS入口， +补充包内架构地图、已批准的根/runtime类型边界和长测独占8084的接续规则。 +[记录](changes/2026-09-16-DOC-03-ai-entrypoints.md)。仅文档修正；没有开始正式复盘， +没有改变运行中的长测输入。任务计数不变。 + ## PKG-MB-09 数小时播放运行检查点 扩展现有长测为每段90..3600秒，默认时长/超时和断言不变；支持已安装候选映射， diff --git a/refactor/tasks.json b/refactor/tasks.json index 8eb91699d..0be26e630 100644 --- a/refactor/tasks.json +++ b/refactor/tasks.json @@ -54,7 +54,8 @@ "deliverable": "refactor 文档集与任务数据", "acceptance": "每包有独立步骤、依赖、交付物和验收条件", "evidence": [ - "progress.md" + "progress.md", + "changes/2026-09-16-DOC-03-ai-entrypoints.md" ] }, {