聊天模式：结合源码和日志检查问题#

聊天模式可以帮助检查上传流程中的报错、定位可能的 bug。它能通过只读工具列出项目文件，搜索错误信息或代码标识符，再读取相关源码和运行日志。

例如，遇到“上传结束了，为什么没有继续发布”，可以让它查找对应日志，再对照上传完成判断、图片校验和发布前复核的代码，解释停在哪个条件上。这样给出的排查方向就有了本地项目的依据。

这一模式适合解释错误、梳理流程和提出修复建议。是否确实修好了问题，仍需要修改后的代码和运行结果来验证。

Agents 模式：由主控规划并调用浏览器工具#

Agents 模式可以调用自研的 小爱 Agents Browser Use 模块来操作浏览器。主控根据任务规划选择工具，在选定网页中读取页面结构、点击、填写或切换关联页面；每轮操作后再检查页面反馈，并决定是否更新计划、继续执行。执行过程和结果会显示在同一个聊天窗口里。

这使小爱的工作范围可以从上架工具自身的固定按钮，延伸到用户选定的其他网页。当前重点仍然是网页任务，以及为网页任务提供支持的本地资料读取和受限脚本处理。

目前已经具备的能力包括：

• 选择已有的目标网页及关联页面，在任务范围内逐页操作；
• 读取指定资料目录中的文本、图片、Excel 和 CSV；
• 查询项目内真实的 PH/ID 型号表，为型号匹配提供依据；
• 将选定的图片、视频和表格上传到网页；
• 在当前聊天的会话目录内创建辅助脚本、整理结果，并通过受控接口调用资料和网页操作能力。

这些能力对电商场景很有用。一项工作往往同时涉及表格、型号表、图片目录和多个编辑页，现在可以把相关资料与页面放到同一次任务中，让 Agent 按要求衔接处理。

图片上传也沿用内容校验思路：上传前固定文件并记录 SHA-256，上传后检查主图、SKU 图和页面标签；没有完成检查的页面，会阻止保存、更新或发布。Agent 与正式上架任务、批量工具之间也有互斥，避免同时控制页面。

需要注意，“停止任务”会停止后续操作，已经完成的网页操作不会自动撤销；切回聊天或关闭小爱窗口，也不会直接取消正在执行的任务。使用时可以在任务记录里查看进度，并通过停止按钮结束后续执行。

先检查素材、表格和计划#

• scan_listing_materials 只读扫描授权的资料目录，识别图片、视频和表格；检查图片能否读取及其尺寸，按文件名列出分组内缺号、重号，并将完整清单写入当前会话目录。一次最多检查 3000 个支持的文件；清单被截断时，需要继续检查对应子目录。
• inspect_listing_workbook 读取指定表格范围，寻找唯一表头，列出候选列与分页原始数据。若价格、型号或其他列存在歧义，只展示候选项，不会自行选定。
• validate_listing_workbook 检查必填变种字段、重复 SKU、重复的 Color 与 Model 组合，以及价格、库存、重量和尺寸。Shopee 单商品 100 个变种的限制只应用于 Shopee，不会套到 TK 或 Temu 上。
• create_listing_plan 根据已明确的店铺、地区、品牌、币种、商品名、图片顺序和变种生成会话内计划。必要信息缺失或有歧义时，会列出阻塞项，等信息补齐后再继续。

表格检查按明确指定的范围进行，每次最多处理 10,000 行；超出当前范围的数据会在报告里标明尚未检查。

按计划核对实际编辑页#

• inspect_listing_page 读取当前编辑页的标题、店铺与商品 ID 证据、表单字段、动态 VXE 表头和可见行；排除密码、密钥输入框与隐藏提示，避免把页面里不可见或不相关的内容当成实际商品数据。
• compare_listing_page_with_plan 按页面实际列标识，核对标题、店铺 ID、Color、Model、SKU、价格和库存。遇到虚拟表没有完整渲染全部数据行时，会明确标记未覆盖，不会给出“核对通过”的结论。

保存本次回执，再记录进度#

• capture_listing_checkpoint 在提交前记录当前页面和已有反馈，划定后续结果核对的起点。
• wait_listing_result 提交后等待检查点之后出现的新反馈，要求指定的成功文本全部出现；不会因为旧提示看起来像成功，就再次提交或当作本次结果。
• read_listing_failures 提取当前页面实际出现的错误、登录和验证码信息，照实报告证据，不猜原因，也不自动删除商品。
• record_listing_progress 按商品记录“计划中、处理中、跳过、失败、未确认”等状态。page_confirmed 只表示当前 ERP 页面出现了本次任务的新反馈；它不能证明电商平台最终已经上线，且必须关联同一个商品的真实回执。
• export_listing_report 将进度和页面反馈导出为 CSV 或 JSON，文件写入当前会话目录，之后可以从运行文件入口下载；CSV 中的公式文本会先转义。

实际使用时，通常先扫描素材、检查表格，再查询真实型号表并生成计划；网页任务执行后，先比对计划与编辑页，沿用原有服务器图片哈希和标签校验，再保存本次提交前的检查点，最后等待新的页面反馈、记录进度并导出报告。登录页、验证码、页面关闭、超时、旧通知、未知店铺或不完整的虚拟表格，都不能当成商品处理成功的证据。一次提交对应一次新的检查点，不能把之前的回执重复用于下一次提交。

会话脚本也可以调用这套工具。下面展示如何查看表格候选列，再按人工明确确认的列号校验一段数据；字段映射里没有确认的列，需要先解决歧义再继续：

1
const api = require(process.env.XIAOAI_SDK_PATH);
2

3
const preview = await api.listing.workbook('资料表格的完整路径.xlsx');
4
const check = await api.listing.validateWorkbook('资料表格的完整路径.xlsx', 'shopee', {
5
  header_row: 1,
6
  start_row: 2,
7
  end_row: 20,
8
  column_map_json: JSON.stringify({sku: 4, model: 3, color: 2, price: 5, stock: 6}),
9
});

其他脚本入口包括 api.listing.materials、createPlan、page、comparePlan、checkpoint、waitResult、failures、progress 和 report。脚本只写入当前会话目录，读取资料与操作页面仍由父进程的受控接口完成。资料目录和项目源码保持只读，执行中继续使用冻结后的图片文件以及原有服务器 SHA-256 与页面标签校验。

这批工具使用临时图片、CSV/表格和单独的无头浏览器进行测试，没有读取真实 API Key，也没有连接或发布真实商品。对应测试入口为：

1
& '.\.venv\Scripts\python.exe' -X utf8 test-listing-tools.py
2
node test-listing-page.cjs

图片校验保留，上传节奏重新整理#

这轮提速建立在之前的 SHA-256 校验之上。程序会在上传前固定本次选定的文件内容，上传完成后读取服务器原图，再与本地快照比较，避免运行过程中本地文件变化，让上传依据和校验依据出现偏差。

目前的校验范围是：

• 商品图先单独上传主图，再批量上传剩余图片；整组完成后检查图片总数，并核对第一张主图的服务器原图哈希。
• SKU 图先完成全部槽位的上传，再并发读取服务器原图，统一核对每个槽位的哈希、图片地址和页面变种标签。槽位里原本已有的图片也会参与检查。
• 发布前再次复核主图、全部 SKU 图和图片绑定关系，每次发布重试也重新检查。

这里需要说明一个具体边界：商品辅图仍做数量和加载检查，没有逐张做哈希校验；逐槽位检查覆盖的是全部 SKU 图。

这次优化主要落在上传过程中的等待方式。以前一些步骤依赖固定间隔，页面已经准备好了仍要继续等；现在会结合上传请求是否结束、服务器是否返回图片地址、目标槽位是否完成绑定，以及必要的图片加载状态，判断能否进入下一步。上传完成状态的轮询间隔最短为 100 毫秒，实际仍要等上述条件满足。

SKU 图也不再每上传一张就单独停下来读取服务器原图、计算哈希，而是完成这一轮上传后统一并发校验。这样可以减少校验过程的串行等待，也便于一次看清哪些槽位通过、哪些槽位需要修复。

并发校验和商品之间的等待衔接，是这次两个不同层面的提速点。 SKU 的上传仍按确定的槽位顺序进行，同一平台也只准备一个商品的图片。

重试机制：先判断异常，再决定怎么恢复#

这次重新整理了图片上传的重试机制。一次上传失败，可能是入口没有打开、请求暂时失败、图片没有绑定到目标槽位，也可能是服务器图片内容不一致。这些情况需要采取不同的恢复动作。

SKU 图最多进行 3 轮上传与修复。每轮结束后仍然检查全部槽位，避免只盯着刚刚重传的那一张，而漏掉页面其他位置的变化。

一个重要调整是：删除和重传之前，必须确认旧上传请求已经结束。 如果旧请求还在运行，新一轮上传就开始了，迟到的响应可能重新覆盖槽位，让页面状态和程序记录不一致。现在无法确认请求已经收尾时，会停止当前操作。

入口重试也有独立的次数限制。程序会先在当前位置不滚动重试 3 次；仍然无法操作，才在确认请求结束、商品身份和 SKU 标签正确后，尝试回到顶部再定位目标槽位。每个槽位最多允许 3 次这样的恢复，而且后续哈希修复不会重置这个计数。

这样，一次临时的菜单失灵有机会自行恢复；持续异常则会明确停下来，不会让一个商品无限消耗时间。

按照本轮测试记录，累计 10,000 条商品链接的分批上架测试中，上架率达到 99.8%。这组数据记录的是本轮测试批次内的上架结果；图片是否正确，仍由主图和 SKU 图各自的校验结果判断，不能只看一个总成功率。

修复 SKU 上传时界面反复跳动的问题#

之前上传 SKU 图时，页面有时会在多个位置之间来回跳动。尤其是 SKU 比较多、上传区域存在嵌套滚动容器的时候，连续定位、悬停和菜单点击会让这个问题更明显。

本次把滚动行为收敛到了必要的位置：

1. 槽位已经可见、上传入口可以操作时，直接在当前位置完成上传，不重复居中。
2. 槽位在视口外或被局部遮挡时，先确认上传请求结束，再进行一次必要定位。
3. 等待上传期间不反复滚动，也不通过侧边锚点来回跳转。
4. 上传期间临时关闭滚动锚定和平滑滚动，完成或异常退出后恢复原来的样式。

菜单点击也会检查实际位置是否可见、是否被遮挡，减少自动定位引起的额外滚动。前面提到的“回顶部再返回槽位”，只在原地重试失败后作为恢复手段触发。

这个修复一方面让界面稳定下来，另一方面也减少了重复定位和菜单重新打开所消耗的时间。

链接并行处理：把发布等待用起来#

单个商品的处理流程里，有一段时间花在等待 BigSeller 返回发布结果上。已经点击提交之后，程序仍要确认成功；原来的串行流程会等到这个商品全部结束，再开始处理下一条链接。

这次新增的链接并行处理，主要把这段等待与下一商品的准备过程重叠：

1
商品 A：填写与上传 → 图片复核 → 提交 → 等待发布结果 → 确认成功
2
                                         ↓ 同时进行
3
商品 B：                              填写与上传 → 图片复核 → 提交
4
                                                               ↑
5
                                                 先确认 A 已成功

每个平台的队列最多保留一个等待发布结果的商品和一个准备中的商品。A 实际点击提交后，B 可以开始填写标题、上传图片；B 自己提交之前，必须先确认 A 成功，并完成自身的图片总复核。如果 A 失败，就阻止后续提交，保留未发布的页面。

对应实现集中在 bigseller-publish-pipeline.js，两个平台的 Worker 分别创建自己的队列。当前队列的核心约束可以从这段源码看出来：

1
async drain() {
2
  if (this.pending) await this.pending;
3
  return !this.failed;
4
}
5

6
async submit(publish, { onSettled = () => {} } = {}) {
7
  if (!await this.drain()) return null;
8
  // 后续才启动当前商品的提交与结果等待。
9
}

上面摘取了方法开头，并省略后续实现。submit() 首先等待上一商品收尾，再判断是否允许继续；下一商品的准备工作可以提前进行，提交顺序依然受这个检查约束。

Shopee 还优化了当前批次编辑页的打开方式：按商品顺序快速发起开页，各页同时加载并核对身份，取消过去每打开一页固定等待 1.5 秒的间隔。核对后仍按原顺序处理，只打开当前批次需要的页面。

并行之后，日志和结果的归属也需要一起处理。现在事件会携带独立的 workerProductId，上一商品的发布结果、截图和耗时不会因为下一商品开始准备而被归到下一条记录里。TK 的成功判断也继续收紧，只接受本次更新后新增或内容发生变化的成功通知。