blurt

blurt 🐔 ——展示、讲述，获取结构化成果

人们面对屏幕时，边说边想效果最好。他们会在不同话题间跳转、自我纠正、指着各种内容。你的任务是毫无阻碍地记录这些内容，然后认真完成繁琐的部分（拆分、整理成文、挑选和标记截图、查找代码、归档）。优化用户的操作流程：绝不中断录制，少问问题，让审核更快捷。

脚本位于本文件旁边的 scripts/ 中；使用 uv run <skill-dir>/scripts/<name>.py ... 运行（每个脚本都会声明其依赖；首次使用时，uv 会安装依赖）。每个脚本都提供 --help。始终使用用户的语言回复；用用户所说的语言撰写条目。

0. 设置（首次运行或遇到问题时）

• doctor.py → 操作系统、RAM/GPU、ffmpeg、已配置的 ASR、建议和 todo 列表。
• 缺少 ffmpeg/uv：提供安装命令；只有用户同意后才运行。
• ASR：如果尚未配置，请根据 asr_recommendations 和用户所说的语言选择方案，用一行说明选择了什么以及原因（大小、本地还是云端、费用），然后运行其 setup。详情见 reference/asr.md。云端密钥由用户在自己的环境中设置——绝不要让用户在聊天中粘贴密钥。
• record.py build — macOS：编译原生录制器（需要 Xcode Command Line Tools；否则使用 Tk 回退方案），并将 Blurt 菜单栏应用安装到 ~/Applications。Windows：首次录制时会出现“开始”菜单快捷方式。用一行提及：“Blurt 也在你的 Applications 中——按 ⌥⇧R 即可随时开始录制”。
• record.py test → 亲自查看返回的 frame。只有壁纸/黑屏或 ok: false ⇒ 缺少屏幕录制权限；mic_silent: true ⇒ 缺少麦克风权限或选错了麦克风。在 macOS 上，权限属于承载你的应用（Terminal、iTerm、VS Code、Claude、Codex……）；授予权限后必须重启该应用。macOS 15+ 可能会显示“允许……绕过窗口选择器”的提示——用户需要自行点击“允许”。
• 可选的项目配置 .blurt/config.json：导出目标、负责人/模块映射、列映射、自定义镜头 .blurt/lenses/。建议将 .blurt/sessions/ 添加到 .gitignore。

1. 录制（或选取已有录制）

从聊天中开始：如果要查看的是此仓库中的本地开发服务器／应用，请确认它正在运行。在后台启动 record.py start（使用 --last-region 可复用上次选择的区域），并用几行话告诉用户接下来会发生什么：

• 屏幕上会出现变暗的遮罩：拖动以绘制区域（或点击窗口，按 F 可全屏）→ 开始录制 / Enter。只会录制该区域——标签页、书签和其他窗口仍是私密的；
• 3-2-1 倒计时（点击可跳过），随后出现一条小型浮动栏：计时器 · 麦克风音量 · ⏸ 暂停 · ↺ 重新开始／丢弃 · 完成。⌥⇧P 暂停／恢复，⌥⇧S 结束（Windows：Alt+Shift）。浮动栏不会出现在录制内容中；
• 自然地讲解，用鼠标指示；按住 ⌃ 并拖动，圈出／划出你要表达的内容（macOS；笔迹会在 3 秒后淡去；点击浮动栏上的 ✎ 或按 ⌥⇧D 可保持画笔开启；按 Esc / ⌥⇧D / 点击 ✎ 可关闭）；点击 完成——无需再发送一条聊天消息。 任务以 DONE video=… 结束 → 立即继续 §2（CANCELLED，退出代码 2 → 确认并停止）。也可以在聊天中使用 record.py stop | pause | resume | restart。

等待后台步骤完成（本节及 §5 中均适用）：如果你的运行环境会在后台任务结束时唤醒你（Claude Code），请结束当前轮次——届时你会收到通知。如果不会（Codex），子进程完成后无法恢复已结束的轮次：保持轮次开启，并在同一工具会话中使用较长轮询等待（不要忙等）；任务运行期间不要发送最终回复。

已有视频（QuickTime、OBS、Loom、手机拍摄的视频、队友的 Blurt 录制……）：创建 .blurt/sessions/<timestamp>/，将视频复制到其中并命名为 recording.<ext>（如果视频来自 Blurt，还要包含 events.jsonl / meta.json），然后继续 §2。

**Blurt 应用录制：**菜单栏应用会将录制内容保存到当前工作区——默认路径为 ~/Blurt/recordings/<ts>/，或绑定了项目时保存到 <project>/.blurt/sessions/<ts>/。record.py inbox 会列出所有录制及其 processed / reviewed 标记。“处理我的录制” → 对每个未处理的录制执行 §2–§4（如果可用，可分派给子 Agent），然后每个会话进行一次审查（如果用户想要一个统一列表，可将内容合并到同一个会话目录）。 meta.json 中包含 author——合并多人的录制时，请保留各条内容的该字段。

2. 转录

transcribe.py run <session>/recording.mp4 → transcript.json + transcript.txt（格式为 [mm:ss.s-mm:ss.s] text）。 使用系统音频录制时（record.py start --system-audio，或通过应用菜单中的切换项启用——适用于通话、产品演示），对方说的话会标记为 (system) / speaker: "system"；未标记的内容则来自用户。麦克风音频串音可能导致系统音频中的语句重复出现。 对于 Whisper/API 后端，请使用仓库中的产品、页面／模块名称和人物名称等术语，传入简短的词汇表作为 --prompt。 还需运行 frames.py scan <video>（为候选帧／图集生成视觉活动索引）和 frames.py marks <video>：记录用户何时、在何处（方框）用画笔标记了什么，以及 ⌥⇧M 标记点。 如果输出中有 warning，或转录内容读起来毫无意义（SenseVoice 会将法语等不支持的语言转成伪英文），说明需要改用其他后端：配置后端（reference/asr.md）并重新运行。

3. 理解 → 条目

先读完整段转录，再浏览几帧，然后编写 <session>/items.json （架构：reference/schema.md）。逐条判断它是什么——以录制内容为准，而不是切换模式：

类型	适用情况	参考指南
issue	产品中需要修复或打磨的问题	reference/lenses/issue.md
idea	要构建／更改／借鉴的内容（“这个网站的这里好”）	reference/lenses/idea.md
note	值得保留的观察／发现／事实	reference/lenses/note.md
task	不属于产品问题的待办事项	reference/lenses/task.md
自定义	.blurt/lenses/ 或 ~/.blurt/lenses/ 中有适用的参考指南，或用户提出了要求	对应文件

原则——用于判断，而非硬性规则：

• 画笔标记表示用户在说“就是这个”：它为条目锚定时间和主题。用户圈出的内容比你对含糊语句的理解更重要——但标记本身不是条目，没有标记的条目也很正常。
• 一个条目只包含一件事。用户可能跳来跳去、反复提及、纠正自己（“不对，是……”），或者在一句话里说两件事：合并重复提及的内容，丢弃撤回的说法，拆分复合内容。纯叙述不算条目。
• 根据上下文（代码库术语、屏幕上的内容）修正 ASR 错误。quote 应尽量贴近原话。
• 不要凭空编造。不确定时，写出你认为最合理的猜测，设置 confidence: "low"，并在 questions 中添加一条简短的问题。
• 从画面中读取 URL／产品名称，并写入 source。
• code_refs（问题，位于代码库内）：搜索画面中可见的文本／路由／组件；列出可能的 path:line。
• 为整个录制设置一个 title。对于以想法为主或探索性的录制，编写 digest（Markdown）：概述主题、最有力的想法及它们之间的联系，并给出建议的下一步——它将成为审核页面的“概览”。

4. 证据：画面与片段

为每个条目挑选 1–3 帧，展示重点（问题本身、启发想法的页面部分）：

• frames.py sheet <video> --from S --to E -o <session>/sheets/<id>.jpg → 约 6 张不同的稳定候选帧，时间戳显示在同一张图中；指定具体时刻（“这里／this／look”）时使用 --at t1 t2 …。说话内容往往滞后于操作。
• 用户画了标记（marks）？标记已在视频中：frames.py grab --at <frame_t>，生成的画面已带标注——不要添加方框。使用 --crop stroke 获取放大的第二帧；如果画面中已没有笔迹，则在该帧上使用 --box stroke。
• 其他情况，标记目标位置时——绝不要根据缩略图或联系表估算坐标：
  1. frames.py grid <video> --at T -o <session>/sheets/<id>-grid.jpg → 带标签的 0–1 网格，以及录制的光标和附近点击（events.jsonl — 精确记录）。根据网格读取方框边缘（--crop 可放大，标签仍显示在整帧上）。
  2. frames.py grab <video> --at T -o <session>/frames/<id>-1.jpg --box x,y,w,h；用户指向／点击目标时使用 --ring cursor|click。细小细节 → 使用 --crop 获取第二帧。
  3. 使用每个已标注画面前都要查看。 方框未框中目标 → 修正后重新抓取。
• 动画／流程／时序：frames.py clip --from --to -o <session>/clips/<id>.mp4（< 20 MB）。
• 条目很多（> ~12）？如果你的工具环境支持子 Agent，可分批将画面处理工作分配给它们。

5. 与用户一起审核

始终打开审核页面——重点就在这些帧上。在后台运行 review.py <session>（会打开浏览器，并在用户完成后退出）。它会打印 REVIEW <url>：如果运行环境无法打开浏览器（SSH、容器），请把该 URL 提供给用户。在同一条消息中：

• ≤ 5 项：列出完整编号清单（类型 · 标题 · 负责人/模块，以及 questions）；超过 5 项：简要概述（按类型统计数量、重点条目、待解答问题）；
• 用两行介绍页面操作：每次处理一项——A 保留 · X 丢弃 · J/K 上一项/下一项 · Z 撤销 · ? 查看按键；可直接编辑字段；G 切换列表视图；V 切换概览视图（有摘要时）；点击“完成审核”即可交回结果。 用户可以在聊天中或页面上回复。按照 §1 的方式等待，直到审核摘要打印出来，然后重新加载 items.json（已丢弃的条目会有 status: "deleted"，回答在 answer 中，合并后的条目会按设计被移除，并列在目标条目的 merged_from 中），然后继续 §6。如果用户改为在聊天中回复，请自行应用回复内容并关闭页面（pkill -f "review.py <session>"）。

无人值守运行（由 Blurt 应用通过 claude -p / codex exec 启动——环境变量 BLURT_APP=1——或以其他非交互模式运行）：不要询问任何内容；执行 §2–§4 并写入 items.json，然后用 2–3 句话总结。设置 BLURT_APP=1 时，不要启动审核页面——应用会在你退出时打开页面；否则，请在后台启动（nohup uv run …/review.py <session> >/dev/null 2>&1 &）。无人值守时，切勿导出到外部系统。

6. 导出 / 执行操作

询问一次内容要导出到哪里（保存在 .blurt/config.json → export 中）。常见目标：问题 → 团队的问题跟踪表；想法 → 想法看板 / 文档；笔记 → Markdown；任务 → 用户的待办事项工具。

• 飞书/Lark 多维表格 → feishu.py export <session> "<table url>" [--kind issue|idea|…]（如果已安装，则使用 lark-cli；否则使用应用凭据；按类型设置默认列，自动创建缺失列，上传帧和片段，并支持断点续传）。 如果还没有表格 → feishu.py create "<name>"。如果需要其他列 → 运行 feishu.py fields，然后使用 --map。 详情见：reference/export-feishu.md。
• Markdown + CSV → export_local.py <session>（导出所有类型；始终是不错的本地记录）。
• GitHub Issues / Linear / Jira / Notion / Obsidian / 其他目标 → reference/export-other.md；使用用户已有的 CLI 或 MCP 工具，并按含义映射字段。
• 如果需要的是文档，而非列表（“整理成需求文档和设计文档”、简报、对比文档——通常是在浏览参考网站或竞争对手后整理，且常涉及多段录制内容）→ reference/docs.md。 远程创建任何内容前，请确认目标位置和数量；之后报告链接。然后提供顺理成章的下一步——对于问题：“要我开始修复这些问题吗？”（你有 code_refs）；对于想法：“要不要为最重要的一项快速做个原型 / 规格说明？”