先定义故障，再进入排障
本篇面向已经有 Agent Demo、正在接手部署的人。用一个原创的展览预览助手说明方法：它接受虚构展品清单，在浏览器里生成预览，再把结果交回网页。假设有人报告“任务日志写了完成，但网页没有预览”，第一步应确认完成究竟指命令退出、文件生成，还是用户已能访问。以下是说明性故障场景，没有声称实际运行过该系统。
建立一张事件卡：预期结果、实际结果、首次出现时间、源码与镜像版本、触发输入、任务编号、环境及最近变更。使用不含敏感信息的小清单复现，不先重启全部服务。把链路画成入口、Agent、浏览器进程、结果文件、网页读取五段，每段写清输入与输出。保留失败现场，避免反复覆盖唯一能解释问题的日志。
场景一：定位容器、网络与卷的断点
先确认各服务状态和时间范围，再读与失败任务相关的日志。docker compose logs 支持按服务查看输出，可以根据当前工具版本选择时间与行数范围；不要把整台机器的日志全部上传。比较应用启动、浏览器退出和结果交付的时间，注意时区及不同机器的时钟偏差。退出码为零只能说明相应进程的退出情况，不能证明另一个服务看见了文件。
在展览案例里，先问文件写在哪里、谁读取它。Agent 的 /app/out 与网页容器的 /srv/previews 即使名称相似，也不会自动共享。核对实际挂载、相对路径、运行用户和文件权限，再检查结果是否在临时层而非预期存储。通过两个服务在已授权测试目录读写一个无敏感标记文件，可以验证具体共享路径；不要开放整个宿主磁盘或扩大到管理员权限来省事。
网络另画调用方向。浏览器容器访问的 localhost 与宿主机、网页容器的 localhost 不同。按名称解析、连接、HTTP 状态、认证和业务响应拆开记录。检查真正的目标服务名与内部端口，不把外部浏览器使用的宿主地址直接搬进所有容器。如需访问宿主服务，按实际 Docker 平台核对支持方式。没有明确监听范围与授权调用方之前，不自动添加桥接或把端口发布给所有机器。
此阶段产物应是能复现的最小故障与证据对应表。例如“结果文件只在浏览器容器临时目录，网页读取的是独立卷”是可验证的定位；“Docker 不稳定”不是。提出修复时注明受影响配置、需要重建或重启的服务、数据保留条件和恢复办法。一次改一个层面，修完重新用同一输入验证，不把偶然成功当成根因已经解决。
场景二：浏览器启动、可见性与结果验收
没有弹出窗口不一定是失败。先确认任务需要无头执行、带界面执行，还是远程观察界面。Linux 上带界面的运行可能需要相应显示环境；无头执行则应通过页面内容、截图或记录验收。进程存在、远程调试端口可达和目标页面可读是不同检查，不能只凭启动日志判断用户看到了结果。
从最小页面开始：加载一个本地静态预览，读取明确标题并保存截图到已约定位置。通过后再加入真实应用的脚本、数据请求及登录条件。记录控制台错误、请求失败、页面地址和关键 DOM 状态。若需要追踪，Playwright 的 Trace Viewer 可帮助回看已有追踪中的动作、快照与相关诊断信息；先确认项目已实际采集追踪，不能把普通日志叫作 trace。
展览预览至少覆盖三条路径：正常清单显示全部预期卡片；某张图片缺失时出现备用信息；生成超时后网页给出可恢复错误。用稳定的界面语义定位元素，等待能说明完成的具体状态，避免仅增加固定睡眠。检查浏览器保存的文件是否真的被后续服务读取，网页上的下载链接是否指向当前任务，避免误把上一次成功文件当成本次输出。
截图与追踪可能包含页面内容、请求或会话信息，只在允许范围保留，分享前检查数据与目的地。本例使用虚构展品，不需要真实账号或私人浏览记录。若测试工具无法观察页面，应记录证据缺口，不宣称“命令已执行所以验收通过”。完成最小页面之后再接完整链路，可以区分浏览器环境问题与应用问题。
场景三：让修复进入可维护的发布流程
先保证版本与构建可复现，再考虑镜像体积。检查依赖锁定、构建上下文、资源收集与运行配置，随后评估多阶段构建及缓存。不能为了减少体积删掉尚未确认用途的浏览器依赖，造成生产再次缺字库或启动失败。保留必要诊断入口，同时控制谁能访问它；不把调试接口当作公开服务。
秘密不能进入源码、镜像层或前端文件。运行时变量也可能被日志或诊断命令显示，采用目标环境支持的秘密管理方式，并核对读取和日志处理。区分浏览器会话数据与普通临时文件，明确保留和清理条件。给任务设置关联编号，把服务日志、页面结果和交付文件对应起来；日志保留期限、轮转及磁盘压力要有负责人。
将故障复现输入作为回归用例，确认修复前能暴露问题、修复后检查正确结果；同时检查原来正常的清单。发布记录关联源码、镜像、配置、检查结果和已知限制。恢复计划不仅包含旧镜像，还包括共享卷及数据格式的兼容性。先在测试副本演练，生产发布后只在已授权范围做最小验收，不因排障方便执行破坏性清理。
可关联 Skill 与前提
本次目录检查没有找到原文 Docker 和 remote-browser 名称所对应的可核验 SkillPI 条目，不提供猜测安装链接。参考 Microsoft Playwright 项目的文档及 Docker 官方诊断说明，优先复用项目现有的受支持工具；它们有清楚的接口和维护来源，但仓库可访问并不等于本次环境已经测试。具体版本、依赖、许可证与接入成本应在实施前核对。
Webapp Testing 用于第二场景中的本地网页观察与交互检查。需要已启动测试服务、地址或启动命令、已授权数据及对应 Python/Playwright 依赖。它能帮助记录页面、截图和错误线索，不自动解决容器共享卷、远程桌面显示或发布权限，也不代表后端数据已经正确持久化。
Writing Guidelines 用于整理事件卡、复现步骤与维护交接说明，要求给出待审阅文件及规则来源。它检查表达与结构，不代替容器命令、浏览器执行和安全扫描。明确每个工具的职责，可以避免把“装了技能”误写成“系统已经修好”。
实操示例与 FAQ
可以给 Agent 这样的请求：“在展览预览测试环境复现日志完成但网页无结果的问题。先说明五段链路，核对失败任务的文件位置和读取方，再检查浏览器最小页面。使用虚构清单，保留限定时间日志，不显示秘密。返回根因证据、最小修复和回归结果；无法观测的步骤写为未知，不修改生产网络。”请求以症状开始，并约定输出，而不是同时安装一组无关工具。
浏览器打开却没有界面，先区分无头、显示环境和页面加载，不能直接判断为端口问题。镜像优化从哪里开始？先复现正常构建，再改变一项依赖或构建层并验证。运行正常但结果丢失怎么办？追踪实际写入与读取位置、任务编号及存储边界。日志中发现密钥怎么办？停止扩大传播，按团队既有事故流程处理泄露及凭据更新，不把含密钥日志贴入公开工单。
这些方法是否绑定模型？不绑定某个模型，但依赖实际工具和环境，不能承诺所有 Agent 都有相同能力。Finder 能代替诊断吗？它可以辅助找候选，根因仍由故障证据判断。什么时候算完成？故障可复现、修复可解释、相关回归通过、发布结果与恢复前提有记录，未覆盖部分清楚写出。原文中英文与参考来源保留在编辑记录，所有展览案例为原创教学设定，没有伪造线上测试或用户证言。