19 KiB
经验记录
本文件用于记录每次执行中出现的关键问题和解决方案。
2026-05-18-17-40-02 Web 导丝分割系统第一版
1. pytest 无法导入本地 backend 包
A. 具体问题：执行 pytest -q 时，tests/test_api.py 和 tests/test_segmentation.py 报 ModuleNotFoundError: No module named 'backend'。
B. 产生问题原因：项目是从空目录新建，尚未安装为 Python 包；pytest 启动时没有稳定地把项目根目录放入 pythonpath。
C. 解决问题方案：新增 pytest.ini，配置 pythonpath = . 和 testpaths = tests。
D. 后续如何避免问题：从零构建 Python 项目时同步添加 pytest 配置，或使用标准包管理配置声明测试路径。
2. scikit-image 0.26 参数变更警告
A. 具体问题：remove_small_objects 使用 min_size 时测试出现 FutureWarning。
B. 产生问题原因：当前环境的 scikit-image 版本将 min_size 标记为废弃参数，并引入 max_size 表达“移除小于等于该面积的对象”。
C. 解决问题方案：将 remove_small_objects(binary, min_size=...) 改为 remove_small_objects(binary, max_size=...)。
D. 后续如何避免问题：固定依赖版本后仍要关注测试警告；图像处理库升级时优先查看函数签名和文档。
3. 融合模式首帧过分割
A. 具体问题：视频第 0 帧没有前帧，融合模式覆盖率一度达到约 22%，明显偏宽。
B. 产生问题原因：时序差分在无前帧时退化为 Hessian，融合投票逻辑对无前帧使用了一票通过，导致边缘形态学噪声被并入。
C. 解决问题方案：融合模式统一使用两票通过，低响应时才回退到一票；同时将边缘形态学改成暗线候选约束下的边缘检测。
D. 后续如何避免问题：视频算法要单独检查首帧、丢帧和单图退化路径；融合策略必须记录每个子方法的置信约束。
2026-05-18-17-55-29 运行确认与演示视频录制
1. Playwright 安装下载卡住
A. 具体问题：尝试安装 playwright==1.55.0 用于浏览器录屏时，pip 长时间停留在大型 wheel 下载阶段，没有继续输出。
B. 产生问题原因：Playwright 包体积较大，当前网络下载速度或连接稳定性不足；继续等待会影响本次“确保可运行”的收口。
C. 解决问题方案：终止该安装进程，改用系统已有 google-chrome --headless 截取首页，并使用当前已安装的 OpenCV 将真实页面截图和真实 API 分割结果合成为演示 mp4。
D. 后续如何避免问题：演示录制优先复用本机已有工具；只有确实需要完整浏览器交互录屏时，再单独安装 Playwright 并预留下载时间。
2026-05-18-19-06-50 网页端工作台增强
1. CSS 覆盖 hidden 导致初始预览控件显示
A. 具体问题：Chrome headless 截图发现初始页面里本应隐藏的视频控件和图像预览同时显示，破坏首屏布局。
B. 产生问题原因：CSS 中对 #videoPreview、#imagePreview 设置了 display: block，其选择器优先级覆盖了浏览器对 hidden 属性的默认 display: none。
C. 解决问题方案：在全局 CSS 中增加 [hidden] { display: none !important; }，确保所有使用 hidden 的状态元素都能可靠隐藏。
D. 后续如何避免问题：前端页面涉及显隐状态时，必须用 headless 截图检查初始状态；如果自定义了 display 样式，需要显式保护 [hidden]。
2026-05-18-19-19-36 加载样例控制台提示处理
1. favicon.ico 404 干扰问题判断
A. 具体问题：点击“加载样例”后，浏览器控制台出现 /favicon.ico 404，同时还有 Unchecked runtime.lastError。
B. 产生问题原因：项目没有提供 /favicon.ico，浏览器会默认请求该资源并记录 404；runtime.lastError 更常见于浏览器扩展消息通道关闭，通常不是普通网页代码产生。
C. 解决问题方案：后端增加 /favicon.ico 响应，前端为“加载样例”增加明确的成功/失败状态提示和异常捕获。
D. 后续如何避免问题：网页端交付时补齐 favicon、状态提示和错误处理；遇到 runtime.lastError 时优先用无痕模式或禁用扩展排查来源。
2026-05-18-19-31-18 原始媒体查看入口增强
1. 文件加载后的原始内容查看入口不够明确
A. 具体问题：用户加载样例或上传视频/图像后，希望在“预览与结果”区域明确查看原始视频，否则不容易确认当前已加载内容。
B. 产生问题原因：页面虽然已有内嵌预览区域，但缺少显式的“查看原始视频/图像”操作入口，大尺寸查看也不方便。
C. 解决问题方案：在“预览与结果”标题区新增按文件类型切换文案的按钮；加载视频时显示“查看原始视频”，加载图像时显示“查看原始图像”；点击后打开原始媒体弹窗。
D. 后续如何避免问题：输入数据、处理中结果、最终结果应分别提供清晰入口，尤其是医学影像类工具需要让用户随时核对原始输入。
2026-05-18-19-37-10 原始视频与结果同级分栏
1. 原始媒体入口层级不符合用户预期
A. 具体问题：用户希望“查看原始视频”和“预览与结果”是同一级，而不是把原始视频查看作为“预览与结果”标题区里的按钮。
B. 产生问题原因：上一版将原始媒体查看入口作为辅助操作放在结果区标题右侧，信息架构上仍然偏向“结果主导”，不符合用户希望的左右对照工作流。
C. 解决问题方案：将右侧工作区拆成左右两个 workspace-pane：左侧固定展示原始视频/图像，右侧展示分割进度、摘要和结果帧；保留“放大查看”作为左侧面板内的辅助操作。
D. 后续如何避免问题：医学影像交互页面应优先考虑“原始输入”和“算法输出”并列对照，而不是把原始输入藏在结果区域的附属操作中。
2026-05-18-19-41-29 样例视频浏览器不显示画面
1. 样例视频控件显示但画面不渲染
A. 具体问题：用户点击“加载样例”后，左侧“查看原始视频”出现视频控件，但看不到原始视频画面。
B. 产生问题原因：内置样例视频由 OpenCV 直接写出，编码为 mpeg4/mp4v；Chrome 对这种 MP4 兼容性不如 H.264 稳定，可能只显示控件不显示画面。
C. 解决问题方案：修改样例生成脚本，生成后用 ffmpeg 转码为 libx264、yuv420p、faststart MP4；前端视频加载后调用 load() 并在 metadata 加载后轻微 seek 到 0.1s。
D. 后续如何避免问题：面向网页播放的样例视频统一转为 H.264/yuv420p，并用 Chrome 实际播放或截图验证，而不是只验证 OpenCV 能读取。
2026-05-18-19-46-56 样例视频旧缓存处理
1. 修复编码后用户仍看到黑色视频
A. 具体问题：样例视频已转为 H.264 后，用户点击“加载样例”仍然反馈左侧原始视频没有画面。
B. 产生问题原因：实测 Chrome 自动点击流程可以看到画面，视频元素 readyState=4 且 videoWidth/videoHeight 正常；用户端仍异常更可能是浏览器继续使用旧 mp4v 样例缓存。
C. 解决问题方案：后端 /api/samples 返回带 mtime_ns 的版本化 URL；前端加载样例时追加时间戳，并使用 fetch(..., { cache: "reload" }) 强制绕过旧缓存。
D. 后续如何避免问题：静态样例、模型文件、前端资源发生兼容性修复时，URL 必须版本化，避免用户浏览器继续使用旧缓存。
2026-05-18-19-56-47 双视频同步与当前帧多方法对比
1. 结果视频与原始视频时间轴不一致
A. 具体问题：结果视频由抽帧后的叠加帧组成，播放时长和原始视频不同；如果直接用同一个 currentTime 同步，会跳到错误画面。
B. 产生问题原因：后端按 frame_stride 抽取关键帧，结果视频用固定 result_fps 写出，源视频时间轴与结果视频时间轴天然不等长。
C. 解决问题方案：后端为每个结果帧返回 source_time、result_time、result_index；前端点击帧卡片或拖动任一视频时，使用最近结果帧的时间映射同步另一个视频。
D. 后续如何避免问题：凡是结果媒体来自抽样、降帧、裁剪或重编码，都必须在 API 中显式返回源时间与结果时间映射，前端不要假设两个视频时长一致。
2. 进度条循环动画造成任务状态误导
A. 具体问题：“正在上传、抽帧并执行导丝分割”的进度条一直往复跳动，看起来像任务卡住或没有真实进度。
B. 产生问题原因：旧样式使用 CSS 无限动画模拟进度，没有和前端请求阶段绑定。
C. 解决问题方案：移除无限动画，改为 JavaScript 按阶段设置固定进度：上传准备、抽帧、生成掩膜和叠加视频、整理结果、完成或失败。
D. 后续如何避免问题：耗时任务即使暂时没有后端实时进度，也要用单向推进的阶段式进度条，避免使用反复跳动的加载条表达处理进度。
2026-05-18-20-18-20 结果视频时长与原始视频对齐
1. 右侧结果视频只有约 1 秒
A. 具体问题：用户看到左侧原始视频为 6 秒，右侧“预览与结果视频”只有约 1 秒，两个播放器时长不一致。
B. 产生问题原因：后端把已抽取并分割的结果帧直接按固定 8fps 拼成结果视频；默认处理 12 帧时，结果视频只有约 12 / 8 = 1.5 秒，而不是原始 6 秒时间轴。
C. 解决问题方案：后端改为按原视频 source_fps 写完整结果视频；抽中的帧写入分割叠加画面，未抽中的帧写入原始画面；result_fps、result_duration、result_time 与源视频时间轴保持一致。前端双视频 seek 同步改为同一时间点同步。
D. 后续如何避免问题：任何面向并排对照的视频结果，都应优先保持与源视频相同时间轴；抽帧结果可以作为下方帧卡片展示，但主视频播放器不应只由抽帧结果压缩拼接。
2026-05-18-20-35-32 结果视频关键帧附近空白
1. 点击第 40 帧后右侧结果视频看起来没有叠加
A. 具体问题：下方结果列表中第 40 帧存在分割结果，但点击后右侧完整结果视频画面可能显示为纯原图，用户感知为“空白”。
B. 产生问题原因：上一版结果视频为了保持 6 秒完整时间轴，只在被抽中的关键帧写入一帧叠加图，其他帧写原始图。浏览器 seek 到关键帧附近时可能显示相邻未抽中帧，因此叠加结果只闪一帧，难以稳定看到。
C. 解决问题方案：后端在生成完整结果视频时维护最近一次分割掩膜；关键帧写真实叠加图，非关键帧用最近掩膜叠加到当前原始帧后写入，从而在关键帧之间持续显示分割提示。
D. 后续如何避免问题：当主视频播放器用于人工查看结果时，抽帧算法的关键帧结果不能只显示单帧；应使用持续叠加、插值或显式关键帧段落，保证用户拖动时能稳定看到结果。
2026-05-18-21-20-13 运动帧结果仍显得不匹配
1. 第 25、55、70 帧叠加结果与原始导丝位置有错位感
A. 具体问题：虽然关键帧附近不再空白，但用户观察第 25、55、70 帧时，右侧结果视频仍和左侧原始视频有不贴合的感觉。
B. 产生问题原因：上一版使用“最近一次分割掩膜持续叠加”来填充关键帧之间的视频画面。导丝是运动结构，旧掩膜套到后续当前帧上会形成残留或错位，尤其在弯曲和末端位置变化明显的帧上更突出。
C. 解决问题方案：后端生成右侧完整结果视频时改为每一帧都运行当前方法分割；max_frames 只控制下方结果卡片保存数量，不再控制主结果视频是否分割。关键帧卡片与视频对应帧用像素差测试校验一致性。
D. 后续如何避免问题：用于播放的结果视频必须逐帧使用当前帧结果；抽帧限制只能用于结果列表、调参预览或摘要，不应用来偷换主视频的逐帧分割语义。
2026-05-18-22-23-07 Docker 安装包与发布
1. Docker 构建阶段 OpenCV 安装段错误
A. 具体问题：用完整 requirements.txt 构建 Docker 镜像时，pip install 在安装 opencv-python 相关依赖后发生段错误，镜像无法稳定构建。
B. 产生问题原因：服务端容器只需要无界面 OpenCV 运行时，完整 opencv-python 轮子会携带 GUI 相关依赖，构建阶段资源和二进制兼容风险更高。
C. 解决问题方案：新增 requirements-docker.txt，将容器依赖收敛为运行时所需库，并使用 opencv-python-headless==4.13.0.92；Dockerfile 使用 --no-cache-dir --no-compile 安装，最终构建通过。
D. 后续如何避免问题：服务端 Docker 镜像优先使用 headless 图像处理依赖，并将开发依赖与容器运行依赖拆分，避免把本地开发包完整带入生产镜像。
2. Compose 模板注释块导致配置解析失败
A. 具体问题：纯净模板最初只注释了 build args 的值，保留了空的 args:，docker compose config 解析失败。
B. 产生问题原因：YAML 中空配置节点不是注释说明，Compose 会按实际配置校验类型。
C. 解决问题方案：将整个可选 args: 块都注释掉，只保留待填写说明；需要代理时再整体取消注释。
D. 后续如何避免问题：带 TODO 的 Compose 模板必须用 docker compose config 同时校验默认路径和可选 profile，确保注释示例不会变成无效配置。
3. 安装包夹带 Python 缓存
A. 具体问题：首次打包后安装包内包含 __pycache__ 和 .pyc，不符合纯净安装包预期。
B. 产生问题原因：自动化测试和 Docker 构建前已运行 Python 代码，工作目录中生成了缓存文件，打包清单没有排除。
C. 解决问题方案：重新打包时排除 __pycache__、.pyc、临时目录和发布目录，并新增 .gitignore 避免后续误提交。
D. 后续如何避免问题：发布包生成后必须执行包内文件检查，至少确认无缓存、无临时目录、无本地数据和无敏感配置外泄。
2026-05-18-23-35-23 使用视频配音与成片
1. 待配音素材不能进入 Gitea
A. 具体问题：待配音视频 下包含原始录屏、配音音频、中间文件和最终成片，文件体积较大且属于交付素材，不应上传到源码仓库。
B. 产生问题原因：该目录不在原 .gitignore 中，后续如果手动 git add . 容易误提交视频素材。
C. 解决问题方案：在 .gitignore 中加入 待配音视频/，并用 git check-ignore 校验原始视频、旁白音频和最终成片均被忽略。
D. 后续如何避免问题：所有录屏、配音、导出视频和临时剪辑目录都应先加入忽略规则，再生成大文件，提交前必须查看 git status --short。
2. 讯飞配音脚本运行条件不满足
A. 具体问题：配音工作流文档默认使用讯飞 PowerShell 脚本，但当前环境未设置讯飞三项环境变量，也没有 PowerShell 运行时。
B. 产生问题原因：该工作流来自 Windows/讯飞环境，当前执行环境是 Linux，缺少对应账号环境与脚本运行时。
C. 解决问题方案：保留工作流中的四段式配音稿、TTS、时长检查和视频合成步骤；TTS 引擎替换为当前环境可运行的中文神经配音工具，并记录实际声音和时长。
D. 后续如何避免问题：配音工作流应预先区分“讯飞凭证可用”和“本地/在线替代 TTS”两条路径；任务开始时先检查环境变量和运行时，避免到合成阶段才发现不可用。
3. 原视频时长与旁白时长不一致
A. 具体问题：原始录屏约 85.6 秒，目标视频约 1 分钟，直接换音轨会出现画面比旁白长的问题。
B. 产生问题原因：录屏展示节奏偏慢，而旁白文案按介绍视频压缩到了约 64 秒。
C. 解决问题方案：用 ffprobe 计算原视频和旁白时长，按 85.636 / 64.272 = 1.332400 对视频做轻度变速，原始音频静音并替换为新旁白，输出 H.264/AAC 兼容格式。
D. 后续如何避免问题：合成介绍视频时先确定旁白时长，再用可接受的变速范围调整画面；如果变速超过自然范围，应优先重新剪辑画面而不是强行加速。
2026-05-19-00-11-40 Ubuntu 配音工作流
1. PowerShell 配音脚本不能直接作为 Ubuntu 工作流
A. 具体问题：原有讯飞配音脚本是 PowerShell 版本，Ubuntu 环境直接执行门槛高，且命令示例不符合 Linux 用户习惯。
B. 产生问题原因：早期工作流面向 Windows/PowerShell，脚本入口、环境变量设置、路径写法和执行权限都与 Ubuntu 不同。
C. 解决问题方案：新增 Tools_scripts_XunFei-Ubuntu，用 Bash 包装入口和 Python WebSocket 客户端实现普通 TTS、超拟人 TTS、音频时长检查和视频合成；新增 配音生成工作流-Ubuntu-Agent.md 写明 Ubuntu 安装与执行步骤。
D. 后续如何避免问题：跨平台工作流应分开维护平台入口文档，不要只替换命令片段；至少要覆盖依赖安装、环境变量、执行权限和常见错误。
2. 无凭证环境下也需要可测试脚本
A. 具体问题：讯飞 TTS 真实请求需要 XF_APPID、XF_APIKEY、XF_APISECRET，没有凭证时无法验证配音稿解析和脚本基础逻辑。
B. 产生问题原因：TTS 网络请求和配音稿解析原本耦合在一起，缺少离线检查路径。
C. 解决问题方案：在 xfyun_tts_ubuntu.py 中加入 --dry-run，先解析配音稿并输出段落计划；只有真正合成时才检查讯飞凭证和发起 WebSocket 请求。
D. 后续如何避免问题：依赖外部账号、网络或付费接口的脚本都应提供 dry-run 或 validate 模式，方便在无凭证环境完成结构校验。
3. Ubuntu 视频合成需要避免编码兼容问题
A. 具体问题：不同来源的音频段可能编码、采样率和声道数不一致，直接 concat 容易失败或生成不可播放音轨。
B. 产生问题原因：ffmpeg concat demuxer 要求输入流参数一致，多段 TTS 音频不一定完全相同。
C. 解决问题方案：build_final_video_ubuntu.py 在合并音频目录时先把每段音频统一转为 48kHz 双声道 PCM WAV，再拼接并与视频合成，最终输出 H.264/AAC MP4。
D. 后续如何避免问题：多段音频拼接前先标准化采样率、声道和编码；最终成片统一使用 H.264/AAC/yuv420p/faststart。
2026-05-19-00-28-03 配音工具不纳入 Gitea 备份
1. 临时配音工具误纳入源码备份
A. 具体问题：Ubuntu 版配音工具和工作流文档属于本地辅助材料，用户明确说明它们和 待配音视频 一样不需要 Gitea 备份。
B. 产生问题原因：上一轮把“新建工具”理解为需要随仓库保存，未先确认这些本地配音工具是否属于源码交付范围。
C. 解决问题方案：从 Git 跟踪中移除 Tools_scripts_XunFei-Ubuntu/ 与 配音生成工作流-Ubuntu-Agent.md，并将它们加入 .gitignore 与 .dockerignore；待配音视频/ 继续保持忽略。
D. 后续如何避免问题：凡是视频、配音、录屏、临时工具和本地工作流材料，默认先按“不进入源码仓库”处理；只有用户明确要求备份时再纳入 Gitea。