video-transcripts

视频转录文本

快速入门

针对每个相关视频运行一次辅助脚本。<skill> 是此技能的目录：

bash <skill>/scripts/generate_video_transcript.sh \
  "https://uploads.linear.app/.../screen-recording.mov" \
  --title "PDF preview hyperlinks trigger leave-page modal"

或用于 GitHub 附件：

bash <skill>/scripts/generate_video_transcript.sh \
  "https://github.com/user-attachments/assets/..." \
  --title "Slash menu loses selection after confirm"

或用于 Screencastify 观看页面：

bash <skill>/scripts/generate_video_transcript.sh \
  "https://app.screencastify.com/watch/..." \
  --title "Bulk send expands filtered recipients"

或用于本地文件：

bash <skill>/scripts/generate_video_transcript.sh \
  "/absolute/path/to/video.mov" \
  --title "Preview hyperlink exits workflow"

对于需要身份验证的 Linear 上传，辅助脚本会自动尝试使用 macOS 本地 Linear 桌面应用中的 Cookie 重试。对于私有 GitHub 资源 URL，如果可用，辅助脚本会尝试使用 GITHUB_TOKEN、GH_TOKEN 或 gh auth token 重试。

适用场景

• GitHub 或 Linear issue、PR 或评论中包含屏幕录制。
• 附件 URL 指向 uploads.linear.app。
• 附件 URL 指向 GitHub 附件或私有 GitHub 资源主机。
• 跟踪工具链接到公开的 Screencastify 观看页面。
• 你需要时间轴形式的转录文本行，而不是含糊的摘要。
• 你希望结果采用以下准确的 XML 结构：

<video-transcripts>
<video-transcript title="...">
[00:00] (...)
</video-transcript>
</video-transcripts>

工作流

团队外的任何人都能看到的跟踪工具评论或回复（例如公开仓库中的评论），需要明确的消息授权；只有团队成员能看到的评论或回复，则遵循项目的消息规则。未获授权发布时，请在本地准备或返回转录文本。下方的缓存位置和复用规则不代表获得了发布权限。

1. 针对每个相关视频运行一次辅助脚本。
2. 为每次运行设置简短且聚焦于 Bug 的 --title。
3. 对于跟踪中的工作，共享规范缓存应放在跟踪工具中，紧邻其描述的证据。
4. 如果视频位于 issue 或 PR 正文中，请使用顶层跟踪工具评论。
5. 如果视频位于 Linear 评论中，请将转录缓存作为回复发布到该条具体评论下。
6. 如果视频位于 GitHub issue 或 PR 评论中，请针对该来源评论中的视频集合，使用一条专用顶层缓存评论。GitHub 不支持回复，因此应按来源容器分开缓存评论，不要将无关评论中的视频合并在一起。
7. 缓存评论或回复正文应以转录来源链接开头，随后是时间戳行：

[[Transcript](link to video or comment if not available)]
[00:00] (...)

8. 缓存辅助脚本生成的 XML 时，请移除 <video-transcripts> 和 <video-transcript ...> 包装行，并仅在来源链接后粘贴时间戳行。
9. 如果同一来源容器中有多个视频，请针对每个视频重复添加 [[Transcript](...)] 来源链接和时间戳行。
10. 辅助脚本可以运行时，不要手写或转述视频中的行为。请使用实际的转录文本输出。
11. 有视频 URL 时，将 [[Transcript](...)] 链接到该 URL。如果视频 URL 不可用或不稳定，则链接到包含该视频的来源评论。
12. 对于 uploads.linear.app 等跟踪工具托管的签名 URL，请去掉查询字符串，以免新签名使原本有效的缓存条目失效。对于 Screencastify，请使用稳定的 https://app.screencastify.com/watch/<id> URL 作为缓存依据，而不是带签名的 dash-assets HLS URL。
13. 除非后续工作流确实需要，否则不要在缓存的转录条目中添加 title 等装饰性元数据。
14. 对跟踪中的工作重新转录之前，请先按来源容器匹配缓存条目：
    • issue 或 PR 正文中的视频使用一条缓存评论
    • 每条包含视频的 Linear 评论对应一条回复
    • 每条包含视频的 GitHub issue 或 PR 评论对应一条专用 GitHub 缓存评论
15. 如果匹配的缓存已涵盖该来源容器当前规范化后的视频键，请复用该缓存。仅转录缺失或新增的视频证据。
16. 不要将 docs/ 用于跟踪工具原始转录缓存。那里是持久化的仓库知识空间，不是原始 issue 证据存放处。
17. 如果通过 codex exec 调用此工具，优先使用 -o <file>，以便在不包含 CLI 进度提示的情况下保存最终 XML。

输出契约

• 返回 XML，而非 Markdown。
• 每个观察到的操作或系统响应占一行，格式为 [MM:SS] (...)。
• 如果可辨认，请引用可见的 UI 文本。
• 仅描述可见的操作、屏幕变化，以及存在时的可听语音。
• 不要臆测隐藏状态、动机或实现细节。
• 优先使用简洁且信息量高的行，避免逐键记录。

模型策略

为提高成本效益，助手默认使用 gemini-3.1-flash-lite-preview。

如果输出格式错误、内容过于单薄或明显嘈杂，则使用 gemini-3-flash-preview 重试。

对于 Gemini 3 模型，助手会强制使用最少思考量，让输出预算用于转录，而非隐藏推理。

使用以下选项覆盖：

VIDEO_TRANSCRIPTS_MODEL=gemini-3-flash-preview bash <skill>/scripts/generate_video_transcript.sh ...

或：

bash <skill>/scripts/generate_video_transcript.sh ... \
  --model gemini-2.5-flash

说明

• 助手接受本地文件路径或远程 URL。
• 对于 uploads.linear.app URL，它会先尝试 LINEAR_COOKIE_HEADER，然后尝试 LINEAR_COOKIES_DB，最后回退到本地 Linear 桌面 Cookie 存储位置 ~/Library/Application Support/Linear/Cookies。
• 对于 GitHub 资源 URL，它会先尝试 GITHUB_TOKEN，然后尝试 GH_TOKEN，再尝试 gh auth token，最后回退到未经身份验证的下载。
• 对于 Screencastify 观看 URL，它会调用 https://umbrella.svc.screencastify.com/api/umbrellaService/watch/<id>，解析签名 HLS 清单，重写子播放列表以使分段保留签名，并使用 ffmpeg 重新封装录制内容。
• Screencastify URL 支持需要 ffmpeg。
• 它会先查找 GEMINI_API_KEY，再查找 GOOGLE_API_KEY。
• 如果两者都未设置，则会在失败前尝试读取 ~/.bash_profile。
• 需要保存请求和响应文件时，请使用 --debug-dir <dir>。
• 质量门槛会拒绝明显低质量的转录，例如反复出现不完整的输入片段，并自动回退。