Skip to content

docs(readme): embed compressed hero overview videos in EN and ZH READMEs - #9194

Merged
loopx-agent merged 2 commits into
mainfrom
codex/readme-hero-video-20261121
Nov 21, 2026
Merged

loopx-agent merged 2 commits into
mainfrom
codex/readme-hero-video-20261121

Conversation

@loopx-agent

@loopx-agent loopx-agent commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Delivery Brief

  • Goal / Source: Surface a clean, immediate 60-second architectural overview video directly in the opening viewport of both README.md and README.zh-CN.md so first-time visitors understand how LoopX coordinates Codex, Claude Code, Gemini, and DeepSeek with independent verification, replanning, human approval gates, and 3% first-read session recovery before scrolling.
  • Current Gap: On 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.
  • Observable Result:
    • Embedded < 8 MB (1280×720 H.264 + AAC +faststart, 7.85 MB each) bilingual 60s v2 explainer videos via standalone GitHub user-attachments paragraphs immediately after the opening </div> container (outside the HTML <div>, where GitHub renders bare user-attachments asset URLs as native inline HTML5 <video> players with 0 binary bytes committed to Git).
    • Both README.md (100% English audio/visual/captions + English t = 0.0s cover slate) and README.zh-CN.md (100% Chinese audio/visual/captions + Chinese t = 0.0s cover slate) now carry native matching language cuts with custom center-clear t = 0.0s first-frame posters.
    • Added a parametrized regression test test_readme_hero_embeds_standalone_user_attachment_video_outside_html_div in tests/test_readme_presentation.py verifying that both READMEs keep their hero attachment URL outside the opening <div> and before quick-start without inline <video> tags.
  • Owning Boundary: README.md, README.zh-CN.md, and tests/test_readme_presentation.py.
  • Bounded Refactoring Disposition: Unnecessary — existing LinkedImages hero invariant tests in tests/test_readme_presentation.py were extended directly without touching unrelated sections, badges, or README.ja.md.

First-Screen Visual Evidence

  • Tested Revision: 3a079aaa690b5578064c8f779bdcb91988cc57fe (codex/readme-hero-video-20261121)
  • Render Boundary: Live GitHub Markdown renderer preview on pushed branch codex/readme-hero-video-20261121/README.md and README.zh-CN.md vs. main (DOM confirmed videoCount=1, readyState=4, videoWidth=1280, videoHeight=720 rendered at 1010×569 on desktop 1280×960 and 322×200 on narrow 390×844).
View Capture
Before (main · EN Desktop 1280×960) gh_readme_before_en
After (HEAD · EN v2 60s Desktop 1280×960) gh_readme_v2_en_desktop
After (HEAD · EN Narrow 390×844) gh_readme_v2_en_narrow
After (HEAD · ZH v2 60s Desktop 1280×960) gh_readme_v2_zh_desktop

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.60s
  • uv run --extra test loopx check --scan-path README.md README.zh-CN.md tests/test_readme_presentation.py -> 0 errors / 0 warnings / public boundary scan clean across 3 files
  • uv 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, including check_rfc_bilingual.py)

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 纯英文 60s v2 短片及纯英文 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 升级版中文 60s v2 短片及中文 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).

@loopx-agent
loopx-agent merged commit 00f47ed into main Nov 21, 2026
9 of 12 checks passed
@loopx-agent
loopx-agent deleted the codex/readme-hero-video-20261121 branch November 21, 2026 13:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant