stepflow-extension 文件夹 → 点击「选择文件夹」。stepflow-extension 文件夹 → 按住鼠标左键不放，将整个文件夹拖动到浏览器扩展管理页面的任意空白处 → 松开鼠标即完成加载。无需点击任何按钮。StepFlow 推荐使用离线安装包（.zip），而非通过浏览器商店安装。以下是原因：
安装包直接从官网 stepflows.cn 下载，不经过 Google / Edge 等第三方商店的中转和审核修改。你下载的就是我们打包的原版文件。
每次更新新版本，商店审核可能需要数天甚至数周。离线安装包在官网上线后立即可用，第一时间获取最新功能和安全修复。
Chrome 商店在国内部分地区访问不稳定或需要翻墙。离线安装包下载一次即可永久使用，不依赖任何外部服务。
离线安装包是未压缩的源码形式，你可以随时查看每一个 JavaScript 文件的内容，确认没有可疑代码。
安装后将
stepflow-extension 文件夹固定在一个位置，不要移动或删除它。如果需要更新，只需下载新版 zip 并覆盖同名文件即可。| 格式 | 文件类型 | 截图 | 可编辑 | 适用场景 |
|---|---|---|---|---|
| .html (打印为PDF) | ✅ 内嵌 | ❌ 只读 | 打印、存档、正式分享 | |
| Word | .doc | ✅ 内嵌 | ✅ 可编辑 | 企业文档、SOP、培训材料 |
| Markdown | .md | ✅ 内嵌base64 | ✅ 可编辑 | GitHub、技术文档平台 |
| HTML | .html | ✅ 内嵌 | ⚠️ 源码可编辑 | 在线查看、发送给他人 |
最常见的两个原因是 Service Worker 未就绪 和 content script 未注入。
扩展后台在空闲后会被浏览器休眠，首次点击需 0.5~2 秒唤醒，期间消息无法到达。
页面为 chrome://、edge://、file:// 等受保护协议，或页面早于扩展打开，注入失败。
首次安装后未在目标站点授权，或被浏览器限制为「仅在点击时运行」。
极少数情况下扩展内部消息通道异常，重新加载扩展可恢复。
操作被录制到了，但截图流水线被跳过或静默失败。常见原因：
默认 900ms 内的连续点击只保存第一次，快速操作时大量步骤被丢弃。
设置中「自动截图」被关闭，只记录操作类型和坐标，不生成截图。
单张截图超过 5MB（高分屏+高质量）时，chrome.storage.local 写入失败，步骤静默丢弃。
浏览器安全策略（如 DRM 内容页）拒绝截图，返回空图或报错。
StepFlow 每次点击后执行截图 → 图像解码 → Canvas 合成标注 → JPEG 编码 → 存储完整流水线，在低配设备或高分屏上容易感知延迟。
2K/4K/HiDPI 屏截图像素数是普通屏 2~4 倍，处理时间成倍增加。
OffscreenCanvas 绘制 + JPEG 编码通常耗时 80~400ms/步。
大截图接近 storage 5MB 上限时写入速度显著下降。
快速连点触发截图队列堆积，前一次未完成就开始下一次。
录制期间截图被逐条写入 chrome.storage.local，每张可能达数百 KB 到数 MB。步骤较多时存储总量可能超过 10MB，浏览器持续 I/O 操作导致整体变慢。
Word 导出乱码几乎都是文件编码与 Word 解析编码不匹配引起的。StepFlow 导出 UTF-8 编码，而 Windows 上旧版 Word 默认以 GBK/GB2312 打开。
PDF 图片模糊通常有三个来源：原始截图质量不足、PDF 转换时二次压缩，或打印缩放比例影响。
录制时质量设置为 50% 以下，JPEG 压缩伪影明显，放大到 PDF 打印尺寸后更清晰可见。
Chrome「打印 → 另存为 PDF」默认对嵌入图片降分辨率处理（DPI 约 96），比屏幕原始分辨率低。
打印时若缩放比例低于 100%，图片被等比缩小后嵌入 PDF，放大后就会模糊。
录制数据存储在 chrome.storage.local 中，以下情况会导致数据丢失：
在 Chrome 设置中「清除浏览数据」时，若勾选了「托管的应用程序数据」，扩展存储会被一并清除。
卸载扩展时 Chrome 会删除其所有本地存储数据，重装后历史记录无法恢复。
chrome.storage.local 默认上限 10MB，超出后新写入失败，极端情况下可能触发存储重置。
Chrome 多用户 Profile 之间数据不共享，切换 Profile 后看不到录制记录是正常的。
StepFlow 目前一次录制只绑定一个标签页（即开始录制时的活跃 Tab）。切换到其他标签页时，步骤仍会被记录，但截图只能截取切换时可见的那个标签页内容。
扩展更新后，旧版 Service Worker 和 content script 可能仍在内存中运行，新版代码未完全生效，导致行为异常或按钮无响应。
章节信息存储在会话的 chapters 字段中，以下情况会导致章节在导出文件中缺失：
点击「+章节」后未等待保存响应就关闭了查看器，章节数据可能未写入存储。
设置中「导出时包含章节标题」被关闭，所有格式导出都不会插入章节分隔。
章节分隔线依赖 CSS 样式，在 Word 或纯文本查看器中可能无法正确渲染。
标注合成发生在 Service Worker 的 OffscreenCanvas 中，以下情况会导致标注缺失：
录制横幅或右键菜单中选择了「✕ 无标注」，截图不会添加任何图形。
设置面板中「点击时合成标注到截图」被关闭，即使选了形状也不会出现标注。
截图文件解码失败或 OffscreenCanvas 在该浏览器版本不可用，会 fallback 到原始截图。
若标注颜色设置为白色或接近背景色，视觉上难以识别，并非真的缺失。
最常见原因是两次点击间隔小于「最小时间间隔」（默认 900ms），系统主动过滤了连续重复步骤。其次，截图文件过大导致 chrome.storage.local 写入失败时，步骤也会静默丢失（控制台可见 [StepFlow] 报错）。
默认 900ms 内的连续点击只保存第一次，快速操作时步骤被丢弃。
单张截图超出 chrome.storage.local 写入限制时，该步骤静默丢弃，无界面提示。
长时间无操作后 Worker 休眠，重新激活期间（0.5~2s）的点击可能被忽略。
点击后页面立即跳转或刷新，截图流水线未完成就被中断，该步骤丢失。
Service Worker 在空闲约 30 秒后会被浏览器强制休眠，内存中的录制状态会丢失。如果录制中途长时间没有操作，之后的点击可能无法被识别为有效步骤，停止后会话内容为空。
录制期间 30s+ 无操作，Worker 进入休眠，内存状态清空，录制事实上已中断。
所有步骤截图均因超限写入失败，步骤数据虽有记录但视作空会话。
录制期间关闭了目标标签页，content script 断开连接，后续步骤无法传递到后台。
Badge 更新依赖 chrome.action.setBadgeText，以下情况会导致红点不显示或延迟显示：
Worker 刚被唤醒（冷启动），首次 Badge 设置可能延迟 1~2 秒，并非录制失败。
若 StepFlow 被收进 Chrome 工具栏的「更多扩展」折叠菜单，红点可能显示在折叠区域内，不在主工具栏可见。
极少数情况下 Service Worker 启动失败，Badge API 调用未执行，重新加载扩展可恢复。
录制数据存储在 chrome.storage.local 中。提供两种清除方式：逐条删除（推荐，可选择性保留）和一键全清（开发者工具手动操作）。
扩展面板（popup）依赖 Service Worker 提供状态数据，若 Worker 处于休眠或初始化失败状态，面板内容可能无法渲染，按钮事件也无法绑定。
面板等待 Worker 响应状态，若 2~3 秒内未收到回复，会回退到默认空状态。
前一个消息未处理完，后续消息排队，面板初始化被挂起。
更新过程中文件未完全替换，导致 popup.js 加载异常或语法错误。
某些广告拦截器、隐私保护扩展可能干扰 StepFlow 的 DOM 或消息通信。
StepFlow 云端服务依赖 https://www.stepflows.cn/api 接口，登录或同步失败通常由网络、账号状态或接口异常引起。
公司内网、代理或防火墙可能拦截了 stepflows.cn 的请求。
密码区分大小写，若忘记密码可前往官网使用「忘记密码」功能重置。
服务器升级或维护期间，API 可能短暂不可用，稍后重试即可。
登录态 Token 长期未刷新可能失效，退出重新登录即可恢复。
导出文件在浏览器中通过 Blob URL 生成并触发下载，以下情况会导致下载失败或文件损坏。
Chrome 安全策略可能拦截自动下载，地址栏右侧会出现拦截提示。
50 步以上的录制 + 高质量截图，Blob 可能达 20~50MB，超出浏览器内存限制。
.html 文件没有默认浏览器关联，或 .md 文件没有文本编辑器，系统提示「无法打开」。
杀毒软件将自动下载的 HTML 文件误判为可疑文件，自动删除或隔离。
自定义区域录制可框选页面中的一部分，仅截取该区域内内容。适合教程聚焦、隐私保护和降低截图体积等场景。
只录制表单、图表或操作面板，排除页面顶部导航、侧边栏等无关元素。
框选区域时避开个人信息区（如头像、用户名、邮箱），截图不会包含隐私内容。
区域截图体积通常为全屏的 10~30%，存储和导出都更快，低配设备更流畅。
页面很长但只需要说明其中一块功能时，区域录制让教程更精简、重点更突出。
StepFlow 目前通过手动安装方式分发（开发者模式加载），不会自动更新。需要用户手动下载新版并覆盖安装。
可以。StepFlow 查看器支持对步骤进行多种编辑操作，包括修改标题、调整顺序、删除步骤、添加说明文字等。
StepFlow 导出的 HTML 文件使用标准 CSS 和 HTML5 语法，但不同浏览器对样式的解析存在细微差异，尤其是打印样式、阴影效果和渐变背景。
部分旧版浏览器需要 -webkit- 等前缀才能正确渲染 flex 布局和渐变背景。
Chrome 和 Edge 对 @media print 的支持较好，Safari 和 Firefox 在分页符处理上有差异。
若系统中缺少指定的中文字体，不同浏览器选择的回退字体不同，导致排版差异。
部分浏览器对 Base64 内嵌图片的加载优先级不同，可能导致页面打开时图片闪烁。
Chrome 出于安全考虑，禁止扩展程序在特定受保护页面上执行内容脚本，StepFlow 无法在这些页面上录制操作。
chrome://、edge://、about:// 等浏览器内部地址完全禁止扩展访问。
Google 禁止任何扩展在 Chrome Web Store 页面运行，防止恶意扩展操纵商店。
file:// 协议页面默认不允许扩展注入，需在扩展管理中手动开启「允许访问文件网址」。
部分公司/学校部署的 Chrome 企业策略可能额外限制了扩展的页面访问权限。
StepFlow 支持通过用户名 + 手机号验证码重置密码。请确保你还记得注册时使用的用户名和绑定的手机号。