用途:系统排查内容提取失败或结果质量差的原因,定位根因并修复。适用情形包括:提取完成但大量页面失败;内容质量低;提取中途挂起或崩溃;导入后报告内容缺失;产品或商品数据缺失或错误。
必要参数与来源:输出目录(可通过 liberate_paths({ url }) 解析 siteDir,默认基础路径为 ~/Studio/_liberations/<host>);输出目录中的 output.wxr;输出目录中的 extraction-log.jsonl;源 URL(取自 WXR 的 <link> 元素或向用户询问)。
排查阶段:一、分诊,先调用 liberate_verify 获取 WXR 条目计数、失败 URL 与媒体下载、残留 CDN URL、质量评分分布和“需关注”摘要,再用 grep 统计 processed、failed、media_failed;将问题分类为高失败率(>30%,系统性)、个别页面失败(<30%)、无失败但质量低、崩溃或不完整、产品或商品缺失或错误。二、调查,对高失败率读取错误信息并用 curl -sI <failed-url> 探测状态码、重定向和头部,必要时通过 liberate_probe 连接 CDP 浏览器检查全局变量、Cookie、localStorage 和网络请求,并调用 liberate_detect 确认平台识别;对个别页面按错误类型分组抽查;对低质量内容运行 /qa 对比源站并检查适配器内容选择器;对崩溃检查 .liberation-lock、最后日志和 WXR 完整性;对产品问题检查 products.csv 与 products.jsonl、JSON-LD 的 @type:Product、classifyUrl 及字段质量。三、修复,调整适配器选择器、配置(如 --delay、--cdp-port、--token)或用 /qa 修补数据。四、验证,使用 --resume 重新提取并运行 /qa 对比失败数。五、记录,将平台特有发现写入 DISCOVERIES.md,适配器代码修复需提交。
重要规则:先读日志再判断;修复前先探测根因;一次只改一处并复测;不要掩盖真实失败;记录发现的平台问题。
限制:资料未提供具体的安装步骤、价格、支持的平台完整列表或性能保证;部分命令依赖 liberate_* MCP 工具与项目内脚本。