sharon8811/newsread

NewsRead README 演示视频

一条命令即可生成标准的演示 mp4：

.claude/skills/demo-video/scripts/run_demo.sh [output.mp4]
# 默认输出：docs/assets/newsread-demo.mp4

流程：启动隔离的后端（:8010，newsread_test 数据库）→ 注入演示数据 → 启动前端（:3010，开发模式）→ 使用系统 Chrome（无头模式，并注入 动画光标和字幕）录制脚本化的 Playwright 导览 → 用 ffmpeg 转换为 H.264 mp4。服务器会被关闭，测试数据库是唯一被触及的——用户真实的 :3000/:8000 上的 docker-compose 栈不会受到任何影响。

参数：DEMO_SCHEME=dark|light（默认 dark），DEMO_SPEED=1.15 （mp4 中的播放加速倍率），CHROME_PATH（备用浏览器二进制文件）。

前提条件（本机上通常都已满足）

• docker-compose Postgres 在 :5433 上运行（仅使用 newsread_test 数据库）
• backend/.venv 已同步（uv sync），frontend/node_modules 已安装
• ffmpeg 在 PATH 中，Google Chrome 已安装
• 网络访问 —— 导览会获取实时 Hacker News 评论、目录 feed 预览和 picsum 缩略图。离线时视频仍会录制，但这些部分会退化。
• 端口 8010/3010 空闲；arq 工作进程不得对测试数据库运行 （它会尝试刷新虚假的演示 feed —— 虽然无害但会产生噪音）。

标准导览展示的内容（加速前约 80 秒）

1. 加载收件箱上的标题卡片
2. 收件箱滚动 —— 自动阅读标记文章；未读计数减少
3. 旗舰文章（“SQLite: 比文件系统快 35%”）—— Markdown 格式 AI 摘要
4. 相关报道 —— 预置的嵌入向量聚类产生相同故事 + 相关层级
5. 实时 Hacker News 评论（在真实的 HN 帖子上显示评论）
6. 目录 —— 搜索“nasa”，打开 feed 预览模态框，使用快速设置订阅
7. 结束卡片

可调整的部分（修改这些以更改演示）

• scripts/seed_demo_data.py —— 演示用户（demo / demo-pass-1234）， 4 个虚构的 feed，约 16 篇手工编写的文章以及 markdown 格式的摘要预览， 手工制作的 pgvector 嵌入向量（余弦 ~0.08 为“相同故事”，~0.50 为 “相关”，随机 ≈ 正交则隐藏）。旗舰文章的 HN 帖子 ID 通过 Algolia API 实时解析。幂等操作；拒绝任何不是 newsread_test 的数据库 URL。
• scripts/record_tour.js —— 场景列表。首先执行一次未录制的预热通行证， 以便 Next 开发模式编译完成以及图片缓存，然后再开始录制。
• scripts/demo_helpers.js —— 注入的鼠标光标/字幕/标题卡片叠加层以及 模拟人工操作的输入原语。滚动使用真实的滚轮事件，因此 IntersectionObserver 的自动阅读行为与用户操作时完全一致。
• scripts/convert_to_mp4.sh —— webm 转换为 H.264/yuv420p/faststart mp4。

验证结果

未经查看不要发布视频。提取抽查帧：

ffmpeg -i docs/assets/newsread-demo.mp4 -vf fps=1/6 /tmp/demo-frames/f%02d.png

并查看其中几帧 —— 确认字幕清晰可读，摘要/相关/HN 部分确实出现， 并且订阅按钮已变为“已订阅”。如果缺少某个部分，请检查录制器日志 和 $WORK/backend.log（工作目录会在运行开始时打印）。

放入 README

GitHub 仅对通过其 Web 编辑器上传的 mp4 渲染视频播放器（在编辑 README.md 时拖放文件，这会生成一个 github.com/user-attachments/assets/... URL）—— 通过路径引用的已提交 .mp4 文件不会以内联方式渲染。因此： 将完成的 mp4 交给用户，并告诉他们在 github.com 上将其拖入 README。 将文件提交到 docs/assets/ 下作为规范副本仍然是可行的。

已知注意事项

• 目录场景中的订阅会触发后端对该 feed 的同步真实获取 —— 选择可靠 的 feed（导览搜索“nasa”）；等待时间允许 30 秒。
• 切勿通过 POST /api/feeds 注入 —— 它会同步获取 feed URL。 种子脚本直接插入 ORM 行。
• 前端 AI 摘要 UI 会在 /api/ai/status 报告未配置时完全隐藏； run_demo.sh 导出了一个占位的 NEWSREAD_OPENAI_API_KEY 使其渲染。 永远不会调用 LLM：摘要是预填充的，摘要端点会在存在摘要时直接返回。
• 种子向量上的嵌入 model 标签必须等于服务器的 NEWSREAD_OPENAI_EMBEDDING_MODEL —— run_demo.sh 为两个进程导出它； 不要使用与服务器不同的环境变量运行种子脚本。