Repository navigation
docs(readme): embed compressed hero overview videos in EN and ZH READMEs - #9194
Conversation
Signed-off-by: LoopX Agent <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
Reviewer: model_agent · Gemini · Google DeepMind · self_reported
动机 / Motivation
首次访问 LoopX GitHub 仓库的开发者与技术评估者在打开中英文主页首屏时需要无需滚动或跳离即可看清控制面运转方式。 改动前 README.md 与 README.zh-CN.md 顶部只有徽章与目录链接,首个产品视频在第 155 至 179 行以静态 WebP 外链呈现,导致访客易在阅读长文前流失;改动后在开屏 div 闭合标签外紧接嵌入独立成段的 GitHub user-attachments 视频直链并附定制 t=0.0s 架构首帧封面,打开仓库首页第一屏即可原地播放演进概览且不向 Git 仓库提交任何二进制视频体积。 GitHub 在线渲染出带 1280x720 清晰首帧封面的原生 HTML5 内联视频播放器(英文主站 77s 3D 架构片 A、中文站 60s 机制片 C,均压至 7.8 MB +faststart),并在 tests/test_readme_presentation.py 固化结构定位测试防止链接误放回 HTML div 内部导致退化。 本次不向仓库提交 .mp4 二进制文件,不改写下方已有的 86s 研究工作台影片与文字稿链接,也不修改 README.ja.md 或既有安装命令。 英文主站 README 目前复用 77s 3D 架构短片并配备 100% 纯英文零号封面,但 3D 正片内部字幕尚为中文,英文全字幕 v2 成片仍待社区贡献者交付。
改动思路 / Approach
如果不直接在首屏嵌入可播放载体,访客必须下滑接近两百行才能遇到首个产品影片且点击后会跳离当前阅读流;而把完整 MP4 直接放进 Git 仓库不仅会导致每次 clone 下载数十 MB 冗余历史,还会触发仓内二进制视频的人工审核阻塞门。因此本次采用 GitHub 官方支持的 user-attachments 独立裸链模式:先将开源演示视频压缩至 7.8 MB(1280×720 H.264/AAC +faststart)并合成零号首帧封面避让正中播放图标,随后将资产直链紧贴开屏 <div align="center">...</div> 闭合标签之后作为独立段落插入,既保证 GitHub Markdown 渲染器原地展开原生 <video> 播放器,又保持 Git 仓库净增量仅为 37 行文本;同时在 tests/test_readme_presentation.py 增设结构守护用例 test_readme_hero_embeds_standalone_user_attachment_video_outside_html_div,防止后续编辑将直链缩回 HTML <div> 内导致无法展开视频。
具体改动 / Changes
- README.md:在第 19 行
</div>外新增独立段落直链https://github.com/user-attachments/assets/9b36c5ba-a4e6-4e94-aa96-9c1fb6c91f91(压缩至 7.83 MB、纯英文t=0.0s首帧封面的 77s 3D 架构短片)及居中小号英文字注,明确标注英文全字幕 v2 成片尚在制作并保留跳转至#see-loopx-in-action的锚点。 - README.zh-CN.md:在第 19 行
</div>外新增独立段落直链https://github.com/user-attachments/assets/f42a9f7a-cf73-47f1-931b-2c7c8666c682(压缩至 7.84 MB、中文t=0.0s首帧封面的 60s 核心机制片)及居中小号中文字注,保持与已有#看看-loopx-如何工作小节锚点及旧版 86s 研究工作台影片互不干扰。 - tests/test_readme_presentation.py:扩展既有 README 首屏测试模块,新增
test_readme_hero_embeds_standalone_user_attachment_video_outside_html_div,参数化校验中英文首页在</div>与快速开始锚点之间均且仅存在一条匹配USER_ATTACHMENT_RE的独立段落,禁止混入手写<video标签或放回<div>块内。
对主干的风险 / Risks
- 静态 Markdown 渲染差异风险:若外链资产被误放进
<div>内部,GitHub 会降级为普通纯文本链接;新增的test_readme_presentation.py单元测试已对该约束做明确负向拦截。 - 零运行态/零控制面副作用:本 PR 仅涉及文档首屏呈现与静态结构单元测试,不改变任何 Python/TypeScript 运行时默认开关、命令行协议、词表或数据存储契约;反例即在无网络或旧版客户端中,内联播放器会自然回退为指向官方资产的可点击链接。
- 剩余已知局限(非阻塞):当前英文主站所嵌 77s 3D 短片虽然定制了纯英文首帧封面并在注释如实标明进度,但正片内部 3D 节点字幕仍为中文,待社区贡献者完成纯英文 v2 成片后再另提小 PR 原地替换该
user-attachments链接即可。
我的整体评价 / Verdict
在 GitHub 远端分支实时预览中对 README.md(桌面 1280x960 与窄屏 390x844)及 README.zh-CN.md(桌面 1280x960)进行完整首屏与折叠视频卡对比检查,确认原生 video 标签按 1280x720 比例加载且 t=0.0s 自定义封面与说明文字无遮挡及横向溢出。 未点击播放完整 77s/60s 流媒体回放,仅在客户端验证了 DOM video readyState=4 首帧加载、宽度自适应及静态首帧视觉渲染;英文版全英配音字幕 v2 成片仍待社区贡献者交付。 全部 3 个改动文件已按精确 head 087408d8fcfeac2af63517fdfe5a860b71e36127 完成逐行核对与独立本地门禁验收:pytest 46 项通过、loopx check 公开边界零报错、canary premerge 全选 13 项检查零失败且 README.md / README.zh-CN.md 在远端 GitHub 预览中实证渲染出原生 <video>(无阻塞性缺陷)。
English verdict: APPROVE — Exact-head review on 087408d passes with zero blocking findings. Both README.md and README.zh-CN.md render inline 1280x720 HTML5 video cards via standalone user-attachment links outside the opening HTML block, guarded by tests/test_readme_presentation.py, pytest (46 passed), loopx check, and canary premerge (13/13 passed).
Signed-off-by: LoopX Agent <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
Reviewer: model_agent · Gemini · Google DeepMind · self_reported
动机 / Motivation
首次访问 LoopX GitHub 仓库的开发者与技术评估者在打开中英文主页首屏时需要无需滚动或跳离即可用对应母语看清多模型控制面运转方式。 改动前 README.md 与 README.zh-CN.md 顶部只有徽章与目录链接,首个产品视频在第 155 至 179 行以静态 WebP 外链呈现,导致访客易在阅读长文前流失;改动后在开屏 div 闭合标签外紧接嵌入独立成段的 GitHub user-attachments 视频直链并附定制 t=0.0s 架构首帧封面,中英文主页各自对应纯英文 60 秒与升级版中文 60 秒短片(均压至 7.85 MB +faststart),打开仓库首页第一屏即可原地播放演进概览且不向 Git 仓库提交任何二进制视频体积。 GitHub 在线渲染出带 1280x720 清晰首帧封面的原生 HTML5 内联视频播放器(英文主站 pure-EN 60s v2 片 C 7.85 MB +faststart,中文站 upgraded-ZH 60s v2 片 C 7.85 MB +faststart),并在 tests/test_readme_presentation.py 固化结构定位测试防止链接误放回 HTML div 内部导致退化。 本次不向仓库提交 .mp4 二进制文件,不改写下方已有的 86s 研究工作台影片与文字稿链接,也不修改 README.ja.md 或既有安装命令。
改动思路 / Approach
如果不直接在首屏嵌入可播放载体,访客必须下滑接近两百行才能遇到首个产品影片且点击后会跳离当前阅读流;而把完整 MP4 直接放进 Git 仓库不仅会导致每次 clone 下载数十 MB 冗余历史,还会触发仓内二进制视频的人工审核阻塞门。因此本次采用 GitHub 官方支持的 user-attachments 独立裸链模式:将社区刚交付的双语 v2 60 秒短片各自压至 7.85 MB(1280×720 H.264/AAC +faststart)并合成零号首帧封面避让正中播放图标,随后将资产直链紧贴开屏 <div align="center">...</div> 闭合标签之后作为独立段落插入,既保证 GitHub Markdown 渲染器原地展开原生 <video> 播放器、达成英文与中文完全原生对齐,又保持 Git 仓库净增量仅为 37 行文本;同时在 tests/test_readme_presentation.py 增设结构守护用例 test_readme_hero_embeds_standalone_user_attachment_video_outside_html_div,防止后续编辑将直链缩回 HTML <div> 内导致无法展开视频。
具体改动 / Changes
关键内容讲解
- README.md:在第 19 行
</div>外插入独立段落直链https://github.com/user-attachments/assets/6d459488-4834-40ef-90bc-d6649c4f0ef1(7.85 MB 纯英文60sv2短片及纯英文t=0.0s首帧封面)与居中小号英文字注,说明涵盖 Codex/Claude Code/Gemini/DeepSeek 多宿主协同、重规划、人工门禁与3%首读恢复,并保留#see-loopx-in-action锚点。 - README.zh-CN.md:在第 19 行
</div>外插入独立段落直链https://github.com/user-attachments/assets/eeb95ecd-6e5b-43d7-a8aa-b3d1b4449423(7.85 MB 升级版中文60sv2短片及中文t=0.0s首帧封面)与居中小号中文字注,保持与#看看-loopx-如何工作小节及既有 86s 影片互不干扰。 - tests/test_readme_presentation.py:扩展既有 README 首屏测试模块,参数化校验中英文首页在
</div>与快速开始锚点之间均且仅存在一条匹配USER_ATTACHMENT_RE的独立段落,禁止混入手写<video标签或放回<div>块内。
对主干的风险 / Risks
- 静态 Markdown 渲染差异风险:若外链资产被误放进
<div>内部,GitHub 会降级为普通纯文本链接;新增的test_readme_presentation.py单元测试已对该约束做明确负向拦截。 - 零运行态/零控制面副作用:本 PR 仅涉及文档首屏呈现与静态结构单元测试,不改变任何 Python/TypeScript 运行时默认开关、命令行协议、词表或数据存储契约;反例即在无网络或旧版客户端中,内联播放器会自然回退为指向官方资产的可点击链接。
- 已清除原 v1 局限:此前首轮提交中英文主页暂时复用中文音画的限制已随本次升级完全解决。
我的整体评价 / Verdict
在 GitHub 远端分支精确 head 实时预览中对 README.md(桌面 1280x960 与窄屏 390x844)及 README.zh-CN.md(桌面 1280x960)进行完整首屏与折叠视频卡对比检查,确认原生 video 标签按 1280x720 比例加载(readyState=4,桌面 1010x569、窄屏 322x200)且 t=0.0s 定制双语封面与说明文字无遮挡及横向溢出。 未在 GitHub 页面播放器内逐秒拖拽回放完整 60s 流媒体片段,仅通过本地逐帧 15 宫格抽检源片与客户端 DOM 验证 video readyState=4 首帧加载、自适应尺寸及静态首帧视觉渲染。 全部 3 个改动文件已按精确 head 3a079aaa690b5578064c8f779bdcb91988cc57fe 完成逐行核对与独立本地门禁验收:pytest 46 项通过、loopx check 公开边界零报错、canary premerge 全选 13 项检查零失败,且中英文 README 首屏已全面升级为原生双语 60 秒 v2 视频。
English verdict: APPROVE — Exact-head review on 3a079aa passes with zero blocking findings. Both README.md and README.zh-CN.md render inline 1280x720 HTML5 video cards via standalone user-attachment links to matching native-language 60s v2 explainers outside the opening HTML block, guarded by tests/test_readme_presentation.py, pytest (46 passed), loopx check, and canary premerge (13/13 passed).
Delivery Brief
main, the opening hero ends with text links and badges only; the first visual film sits below line 175 as a static WebP click-out link, losing visitors before they scroll.< 8 MB(1280×720H.264 + AAC+faststart,7.85 MBeach) bilingual60sv2explainer videos via standalone GitHubuser-attachmentsparagraphs immediately after the opening</div>container (outside the HTML<div>, where GitHub renders bareuser-attachmentsasset URLs as native inline HTML5<video>players with0binary bytes committed to Git).100%English audio/visual/captions + Englisht = 0.0scover slate) and README.zh-CN.md (100%Chinese audio/visual/captions + Chineset = 0.0scover slate) now carry native matching language cuts with custom center-cleart = 0.0sfirst-frame posters.test_readme_hero_embeds_standalone_user_attachment_video_outside_html_divintests/test_readme_presentation.pyverifying that both READMEs keep their hero attachment URL outside the opening<div>and before quick-start without inline<video>tags.README.md,README.zh-CN.md, andtests/test_readme_presentation.py.LinkedImageshero invariant tests intests/test_readme_presentation.pywere extended directly without touching unrelated sections, badges, orREADME.ja.md.First-Screen Visual Evidence
3a079aaa690b5578064c8f779bdcb91988cc57fe(codex/readme-hero-video-20261121)codex/readme-hero-video-20261121/README.mdandREADME.zh-CN.mdvs.main(DOMconfirmedvideoCount=1,readyState=4,videoWidth=1280,videoHeight=720rendered at1010×569on desktop1280×960and322×200on narrow390×844).main· EN Desktop1280×960)HEAD· ENv2 60sDesktop1280×960)HEAD· EN Narrow390×844)HEAD· ZHv2 60sDesktop1280×960)Verification
uv run --extra test python -m pytest tests/test_readme_presentation.py tests/test_dco_workflow.py tests/test_kiro_cli_host_surface.py->46 passed in 17.60suv run --extra test loopx check --scan-path README.md README.zh-CN.md tests/test_readme_presentation.py->0errors /0warnings / public boundary scan clean across3 filesuv run --extra test loopx canary premerge --from-git-diff --git-diff-base origin/main->passed(selected=13, failures=0,merge_gate_passed=true,manual_holds=0, includingcheck_rfc_bilingual.py)