使用指南

反馈收集

HyperFrames 如何收集反馈、收集哪些数据以及如何退出。

HyperFrames 偶尔会询问渲染效果如何或 Studio 会话体验如何。本页解释我们为什么这样做、提示何时出现、收集哪些数据以及如何禁用它们。

为什么询问

我们使用匿名满意度评分来了解工具是否真的运行良好——而不仅仅是它是否没有错误地运行。一次耗时 10 分钟并生成损坏文件的渲染在日志中算作成功，但实际上算失败。反馈提示是我们获取该差距信号的唯一方式。

没有账户、邮箱或身份与响应关联。每次安装在设置时生成一个随机 UUID；这是唯一的标识符。

工作原理

CLI — 渲染后提示

在成功的 hyperframes render 之后，可能会出现一个简短提示：

How was this render? [1=poor 5=great, enter to skip]
Any details? (enter to skip)

显示时机：

首次成功渲染
之后每 15 次渲染一次（第 16、31、46 次...）
每个进程最多一次——同一会话中的重新渲染不会触发第二次提示
在静默模式（--quiet）、非 TTY shell 和 CI 环境中自动抑制

提示有 10 秒自动超时——如果你不响应，它会静默消失，CLI 正常继续。

渲染间隔可配置：

# 每 5 次渲染显示一次提示（而非 15 次，适合测试）
HYPERFRAMES_FEEDBACK_INTERVAL=5 hyperframes render --output out.mp4

Studio — 会话反馈栏

一个 32px 的细条会在预览区域底部周期性滑入：

首次会话绝不显示——仅从第 10 次开始
之后每 10 个会话一次（第 10、20、30 次...）
在页面加载 3 秒后滑入以避免闪烁
如果被忽略，20 秒后自动消失
任何交互（关闭或提交）后，会话计数器重置——再过 10 个会话后出现下一次提示

会话间隔可在构建时配置：

VITE_HYPERFRAMES_FEEDBACK_INTERVAL=3

无效值（非整数、零、负数）回退到默认值。

注意： 禁用 CLI 遥测（hyperframes telemetry disable）不会抑制 Studio 栏——Studio 反馈由单独的门控管理。提交的数据仍通过相同的匿名 PostHog 管道发送，因此相同的隐私保证适用。

`hyperframes feedback` 命令

你可以随时手动提交反馈：

# 快速评分
hyperframes feedback --rating 5

# 带详情的评分
hyperframes feedback --rating 3 --comment "render succeeded but GSAP timeline didn't animate text overlay"

标志	描述
`--rating`	满意度评分，1-5（必填）
`--comment`	可选的自由文本详情

此命令会自动收集 doctor 摘要、刷新遥测并退出。它出现在 hyperframes --help 的 Settings 组中。

Agent 运行时

当检测到 AI agent 时，HyperFrames 跳过交互式 readline 提示并打印结构化提示：

[hyperframes] Agent feedback: hyperframes feedback --rating <1-5> --comment "..."

Agent 可以使用上述 hyperframes feedback 命令提交反馈。

相同的节奏门控适用：提示仅在首次渲染时出现，然后每 15 次一次。

检测到的 agent 及其标记：

Agent	环境标记
Claude Code	存在 `CLAUDECODE`，或存在 `CLAUDE_CODE_ENTRYPOINT`
Codex	存在 `CODEX_THREAD_ID`、`CODEX_CI` 或 `CODEX_SANDBOX_NETWORK_DISABLED`
Cursor	`TERM_PROGRAM` 等于 `cursor`
GitHub Copilot Agent	`GITHUB_ACTIONS` 等于 `true` 且（存在 `COPILOT_AGENT_ID` 或 `RUNNER_NAME` 等于 `Copilot`）
Replit	存在 `REPL_ID` 或 `REPLIT_USER`
Hermes	存在 `HERMES_QUIET`
openclaw	存在 `OPENCLAW_STATE_DIR` 或 `OPENCLAW_CONFIG_PATH`
Pi	存在 `PI_CODING_AGENT`

仅检查这些变量的存在（或在某些情况下的值）——不会读取碰巧共享前缀的 API 密钥和密钥。

收集哪些数据

CLI 反馈

字段	值
`$survey_id`	`render_satisfaction`
`$survey_response`	评分（1-5）
`$survey_response_2`	自由文本评论（仅在提供时）
`render_duration_ms`	渲染所用时间（毫秒）
`doctor_summary`	系统上下文（见下文）

doctor_summary 是包含环境上下文的紧凑字符串——自动包含，因此报告问题时无需运行 hyperframes doctor：

os=darwin/arm64 node=v22.11.0 cpu=10cores mem=32GB ffmpeg=yes

在检测到这些环境时，还可能包含 wsl 或沙箱运行时标志。

Studio 反馈

字段	值
`$survey_id`	`studio_experience`
`$survey_response`	评分（1-5）
`$survey_response_2`	自由文本评论（仅在提供时）
`source`	`studio`
`doctor_summary`	浏览器上下文（平台、屏幕、CPU 核心数、设备内存、网络类型）

不收集的数据

文件路径或项目名称
合成内容、HTML 或视频文件
环境变量值
个人身份信息
IP 地址或精确位置

反馈是匿名的。每次安装有一个随机 UUID（anonymousId）——没有账户、登录或邮箱关联。

配置文件

CLI 将反馈状态持久化在 ~/.hyperframes/config.json 中：

{
"telemetryEnabled": true,
"anonymousId": "a1b2c3d4-...",
"telemetryNoticeShown": true,
"commandCount": 47,
"renderSuccessCount": 14,
"lastFeedbackPromptAt": 1
}

字段	描述
`renderSuccessCount`	所有会话中的成功渲染总数
`lastFeedbackPromptAt`	上次提示出现时的 `renderSuccessCount` 值——用于计算是否已过了 15 次渲染

Studio 在 localStorage 的 hyperframes-studio: 前缀下存储等效状态。

退出方式

CLI — 完全禁用遥测

禁用遥测会抑制 CLI 反馈提示和所有其他 CLI 使用跟踪：

# 通过 CLI 命令（持久化到 ~/.hyperframes/config.json）
hyperframes telemetry disable

# 或通过环境变量（每次会话）
HYPERFRAMES_NO_TELEMETRY=1 hyperframes render --output out.mp4

# 或通过 DO_NOT_TRACK（遵循全局标准）
DO_NOT_TRACK=1 hyperframes render --output out.mp4

禁用后，hyperframes feedback 命令将打印 Telemetry is disabled. Feedback not sent. 并退出，不发送任何内容。

CLI — 在不禁用遥测的情况下抑制输出

# 静默模式：渲染不产生任何渲染后输出（包括反馈提示）
hyperframes render --quiet --output out.mp4

CI 环境

当设置了 CI 环境变量时，CLI 反馈提示会自动抑制（GitHub Actions、CircleCI 等默认设置此变量）。

Studio

Studio 反馈栏不受 CLI 遥测设置影响。要在构建时禁用它，设置：

VITE_HYPERFRAMES_NO_FEEDBACK=1

设置为 "1" 后，该栏永不显示——shouldShowFeedback() 无条件返回 false，无论会话计数或 localStorage 状态如何。

会话间隔仍可独立配置：

VITE_HYPERFRAMES_FEEDBACK_INTERVAL=20