企业官网建设流程全解析

用 ce-riffrec-feedback-analysis 把 Riffrec 录制转成结构化产品反馈

【免费下载链接】compound-engineering-pluginOfficial Compound Engineering plugin for Claude Code, Codex, Cursor, and more项目地址: https://gitcode.com/GitHub_Trending/ev/compound-engineering-plugin

当你手上已经有一个 Riffrec 抓取包（riffrec-*.zip，或解压后的录制目录），或者一段视频、录音、会议笔记形式的产品反馈，想把它变成可以跟进的结构化材料——要么是一份可以直接贴出去的 bug 报告，要么是一套能继续喂给需求头脑风暴的分析产物——Compound Engineering 插件里的ce-riffrec-feedback-analysisskill 就是为这个场景设计的。它是 Riffrec 这个独立录制工具的消费端：Riffrec 负责把屏幕、麦克风、控制台、网络请求和 DOM 事件同步录进一个riffrec-*.zip，这个 skill 负责把录制内容转成证据齐全的结构化反馈。

它跑在已安装 Compound Engineering 插件的 agent 主机上（Claude Code、Cursor、Codex 等）。本文以 Claude Code 的斜杠命令形式为例，Codex 中对应的调用形式是$skill-name。

前提条件

• 已安装 Compound Engineering 插件。Claude Code 下是：

  /plugin marketplace add EveryInc/compound-engineering-plugin /plugin install compound-engineering

  其他主机的安装方式见 README.md 的 Install 部分；已装过旧版本的用户升级前先看 docs/install/upgrading.md。

• 准备好一个输入源。skill 接受以下形式（来源：skills/ce-riffrec-feedback-analysis/references/analyzer.md）：

  • Riffrec 的.zip包，或解压后的录制目录（必须包含session.json和events.json）；
  • .mp4、.mov、.webm视频；
  • .m4a、.mp3、.wav音频；
  • 会议笔记.md文件。

• PATH 上有一个能实际运行的 Python 3 解释器（python3、python或py任一）。skill 会逐个执行候选命令来验证解释器可用，防止把 Windows Store 的桩程序当成可用解释器；全部不可用时该路径会停止并报告no working Python 3 interpreter on PATH。

• 如果需要把视频/音频里的语音转成文字稿，还需要环境变量OPENAI_API_KEY和系统里的curl。两者缺一时，转录会被跳过而不是报错，产物中会留下原因（见验证输出）。

如果还没有录制，先把 skill 跑一遍 setup 路径：/ce-riffrec-feedback-analysis how do I install and use Riffrec?。这条路径不运行分析器，而是走 Riffrec 的安装指引：以 Riffrec 项目 README 为当前安装命令的权威来源，把 Riffrec 的采集脚本接进你的 web 应用、放一个"Record feedback"入口（bug 按钮、开发者浮窗或键盘快捷键都行），并确认一次样例会话能产出一个可下载的riffrec-*.zip。安装指引还给了几条录制习惯，直接影响后续分析质量：复现问题时把问题说出口（文字稿是信号最高的产物）、点一下受影响的 UI 即使它没有反应（失败的点击是事件提取中最强的信号）、保持短而聚焦（多个短片段胜过一个长片段）、说明哪一步是故意操作哪一步是误触（分析器无法推断意图）。

三条路由：setup、quick、extensive

skill 没有开关参数，路径由输入本身和措辞决定（来源：docs/guides/ce-riffrec-feedback-analysis.md 与 skills/ce-riffrec-feedback-analysis/SKILL.md）：

一个 Riffrec 压缩包不带任何附加措辞进来时，skill 会先检查时长和事件数再选路径；仍然判断不清时，它会先问你一句再跑重活，而不是猜。如果输入本身很短且已经是文字，文档给出的建议是绕过这个 skill，直接把文字贴进/ce-brainstorm；录制内容是调试会话而不是产品反馈时走/ce-debug（ce-debug 文档）；只要文字稿时用专门的转写工具。

运行技能

调用形式是"文件路径 + 可选意图"。以下示例来自官方指南（文件名是文档示例，替换成你自己的录制即可）：

# 完整的 Riffrec zip，由时长和事件数决定走 quick 还是 extensive /ce-riffrec-feedback-analysis riffrec-2026-05-04-checkout-flow.zip # 视频、音频、文字笔记走同一个路由器 /ce-riffrec-feedback-analysis demo.mp4 /ce-riffrec-feedback-analysis voice-memo.m4a /ce-riffrec-feedback-analysis meeting-notes.md # 强制走短路径：只出一段 bug 报告，除非你要求否则不写文件 /ce-riffrec-feedback-analysis just transcribe this clip.mp4 # 较长的 walkthrough，只要分析产物，不启动 brainstorm /ce-riffrec-feedback-analysis extract the analysis from checkout-walkthrough.mp4, do not brainstorm

参数表（来源：指南的 Reference 一节）：

两点调用细节：

• 已经解压过录制的话，把整个录制目录传进去，而不是只传recording.webm。只传视频文件也能跑，但会丢掉事件日志和其余抓取上下文，而事件和timestamps正是 Riffrec 包比裸视频价值高的原因。
• 传解压目录时该目录必须同时含session.json和events.json，否则脚本会报Unsupported source directory: ... missing ...并停止。

底层分析器的直接调用

三条非 setup 路径最终都通过同一个分析器脚本 skills/ce-riffrec-feedback-analysis/scripts/analyze_riffrec_zip.py。如果你想在 skill 之外手动跑（比如脚本级排错），analyzer 契约文档给出的调用形状是：

SKILL_DIR="<ce-riffrec-feedback-analysis SKILL.md 所在目录的绝对路径>"; INPUT_PATH="<输入的绝对路径：zip、解压目录、视频、音频或笔记>"; OUTPUT_DIR="${OUTPUT_DIR:-}"; PY="$(for c in python3 python py; do command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1 && { echo "$c"; break; }; done)"; [ -n "$PY" ] || { echo "no working Python 3 interpreter on PATH" >&2; exit 1; }; ANALYZER_ARGS=("$INPUT_PATH"); [ -z "$OUTPUT_DIR" ] || ANALYZER_ARGS+=(--output-dir "$OUTPUT_DIR"); "$PY" "$SKILL_DIR/scripts/analyze_riffrec_zip.py" "${ANALYZER_ARGS[@]}"

其中SKILL_DIR换成你机器上该 skill 的实际安装目录，INPUT_PATH换成你的录制；OUTPUT_DIR仅在需要覆盖默认输出位置时才设置，留空时由脚本自己决定默认值。脚本自身的参数还有：--topic（写入requirements-kickoff.mdfrontmatter 的 kebab-case 主题名）、--model（转录模型，默认gpt-4o-mini-transcribe，可用环境变量RIFFREC_TRANSCRIBE_MODEL覆盖）、--no-transcribe（跳过媒体转录）、--max-moments（最多提取的截图数，默认 12）。分析器失败时，文档要求是报告退出码和 stderr 并停在该路径，不要用部分产物冒充成功。

快速路径：得到一份 bug 报告

quick 路径的完整流程（来源：quick-bug-report 参考）：

1. 用mktemp -d "${TMPDIR:-/tmp}/riffrec-quick-XXXXXX"创建一个临时输出目录（该命令只新建一个临时目录，无其他副作用），把INPUT_PATH指向你的录制，按上面的调用形状跑分析器，记下它打印的输出目录。
2. 只读临时输出里的analysis.md，跳过problem-analysis.md、review-prompt.md、requirements-kickoff.md、source-materials.md——那些文件是给 extensive 路径用的。
3. 从frames/里最多挑一两张直接展示所报问题的截图，优先选靠近口头抱怨、失败点击、控制台错误或失败网络请求的时间点。
4. 在对话里直接输出一份简洁 bug 报告，结构是：标题（一句话点明坏掉的行为）、复现步骤（从点击和文字稿重建）、预期 vs 实际、证据（带 timestamps 的文字稿引文 + 0–2 张截图引用）、建议的下一步（建 issue、开ce-debug，或升级成 extensive 分析）。

几个明确的行为边界：报告默认只打印在对话里，你要文件才写文件，且优先写成单份bug-report.md放在源录制旁边或你指定的路径；quick 路径不会自动创建docs/brainstorms/...；raw/和frames/只存在于临时目录，由操作系统回收，不提交。如果读文字稿时发现录制里其实有多个独立问题，skill 会停下来告知"This recording has more than one issue — switching to the extensive path."，然后改用非临时输出目录重跑分析器、切换到 extensive 路径。

详细路径：得到可进 brainstorm 的需求材料

extensive 路径的产出物（来源：extensive-analysis 参考）：

• analysis.md：会话摘要、文字稿、选定时刻、截图链接、候选发现与复查清单；
• problem-analysis.md：问题分类骨架，最终必须恰好包含 Visual/UI Problems、Functional Problems、Requirements、Usability/UX Problems 四个顶层类别；
• review-prompt.md：填入截图路径和文字稿的深度视觉分析提示词；
• source-materials.md：原始反馈位置、本地专属 raw 文件、文字稿、分块、本地专属 frames 和各产物之间的清单文件，是后续可追溯性的依据；
• requirements-kickoff.md：CE 风格的需求起点，含 Problem Frame、Actors、Key Flows、R-IDs、Acceptance Examples、Success Criteria、Scope Boundaries、Questions、Next Steps；
• analysis.json：结构化的会话、事件、文字稿、时刻和产物元数据；
• frames/与raw/：本地专属的提取截图与归一化后的抓取内容，默认不提交。

输出目录的默认规则（脚本实现）：如果当前工作目录存在docs/brainstorms/，产物落在docs/brainstorms/riffrec-feedback/<source-stem>/下；否则落在当前目录的riffrec-feedback/<source-stem>/。用户指定了目的地时用--output-dir覆盖。docs/brainstorms/riffrec-feedback/只是证据/启动产物区的例外约定，持久的计划产物仍由ce-brainstorm写到 plans 目录下。

流程上，skill 会依次读analysis.md、problem-analysis.md、review-prompt.md、requirements-kickoff.md，在 brainstorm 前读source-materials.md保持对原始证据的追溯，用平台的图片查看能力检查frames/里的高信号时刻（口头抱怨词如 "doesn't work"、"broken"、"confusing"、抱怨前后的点击、重复点击同一控件、控制台错误、失败请求、可见的 toast 和校验错误等），再把证据转成需求时严格区分"观察到的事实 / 推断 / 需求"三层。长媒体转录过大时会自动分块转录，各块文字稿带时间戳前缀，复查时仍能对应到大致视频区域；纯音频或纯笔记来源没有画面，视觉部分会明确标注无 frames 可用。

除非你说了 "extract only" 或 "analyze, do not brainstorm"，分析落地后 skill 会带着requirements-kickoff.md和source-materials.md调起/ce-brainstorm（ce-brainstorm 文档），由你确认、修正或重新归组捕获到的需求，再由 brainstorm 产出持久的 requirements-only 统一计划。整条链路在插件工作流中的位置是：

recording → /ce-riffrec-feedback-analysis → (extensive) → /ce-brainstorm → /ce-plan → /ce-work → (quick) → bug report in chat → (setup) → capture instructions

验证输出

判断运行是否符合预期，按路径分别核对：

• quick 路径：分析器打印出输出目录，随后对话里出现一份带证据的 bug 报告。报告完成即结束，磁盘上不应新增docs/brainstorms/...内容。
• extensive 路径：在输出目录下确认上表列出的analysis.md、problem-analysis.md、review-prompt.md、source-materials.md、requirements-kickoff.md、analysis.json以及frames/、raw/齐全；problem-analysis.md的顶层类别恰好是四个规定类别；随后ce-brainstorm被带料调起。指南里给过一个文档示例供参考量级：一个 8 分钟、47 个事件、覆盖多个 UI 面的包被判为 extensive，产出目录docs/brainstorms/riffrec-feedback/riffrec-2026-05-04-checkout-flow/，其中识别出四个问题——这只是官方指南的示例结果，你的录制会得到不同的时长、事件数和发现，不要把它当固定预期。
• 转录状态：没设OPENAI_API_KEY（或系统没有curl）时，转录状态是skipped，产物里会写明原因，例如OPENAI_API_KEY is not set. Re-run with the key available to transcribe the media file.；带了--no-transcribe则是skipped并写明 "—no-transcribe was passed"。看到这类标记时，检查产物中所有依赖文字稿的部分（候选发现、投诉词匹配）都会缺失或变弱，补齐 key 重跑或接受无文字稿的结果，二者都要明确。
• 分析器失败：按契约应看到退出码和 stderr 被报告、该路径停止，而不是拿到一组部分产物。

边界与限制

• 隐私默认：raw/和frames/默认只留在本地，除非你明确要求提交并确认隐私可接受；需要提交的文本产物（需求启动材料、分析摘要、来源清单）在确认不含敏感数据后可提交。提交到仓库的文档里用仓库相对路径引用截图，避免绝对本地路径。
• Riffrec 包信息更全：裸视频/录音走的是同一条路由，但事件和 timestamps 不在其中；只传recording.webm会丢失事件日志，所以传解压目录时传整个目录。
• quick 报告里不做代码映射：只有当工作区就是产品源码、且坏掉的界面在文字稿或可见 UI 中被明确点名时，才追加一行带置信度（High/Medium/Low）的 "Likely surface"；猜的映射属于 extensive 路径的事。
• extensive 的映射是支撑材料而非过滤器：映射到源码时按 Likely buggy surface / Missing or incomplete surface / Indirect surface / Unknown 分类并给出置信度与证据说明；找不到对应实现时文档建议明说"未找到该表面的当前实现"，而不是硬凑一个推测映射。

跑完 extensive 且确认需求无误后，下一步就是让/ce-brainstorm把捕获的需求归组、落成统一计划，再走/ce-plan、/ce-work；如果 quick 报告指向一个明确的失败现象，按指南建议转到/ce-debug去查。

【免费下载链接】compound-engineering-pluginOfficial Compound Engineering plugin for Claude Code, Codex, Cursor, and more项目地址: https://gitcode.com/GitHub_Trending/ev/compound-engineering-plugin