简介

通用电商浏览器自动化底座 Skill，带 CC 套壳 UI，降低小白使用门槛。

详细介绍

电商 Agent 浏览器 Skill

这是一个面向电商场景的通用浏览器自动化 Skill。它的目标不是把某个平台的操作写死成脚本，而是给 Agent 一套稳定、可观察、可执行、可复盘的浏览器底座，让模型像人一样理解页面、选择路径、执行动作，并把适合沉淀的流程逐步变成更快的工具能力。

当前代码从 PDD Agent 项目中抽取而来，拼多多商家后台是第一个已验证的垂直场景。后续可以继续扩展到淘宝、京东、抖音商城、拼多多消费者端、其他电商后台和通用网页任务。

交流群

QQ 交流群：553930061

有问题可进群反馈交流。

UI 和产品定位

这个项目的桌面 UI 本质上是 Claude Code（CC）的电商场景套壳：底层仍然围绕 Agent、Skill、浏览器工具和模型决策来工作，UI 负责把账号登录、素材拖入、任务输入、运行日志、模型配置、打包依赖等流程做成普通用户更容易理解和使用的界面。

因此它不是要替代 Claude Code，而是专门为小白用户降低使用门槛：

不需要用户自己配置复杂命令行环境。
不需要用户理解 skill 路径、浏览器 profile、Playwright、模型路由等底层细节。
通过桌面按钮和自然语言任务，把“会用聊天窗口”变成“能让 Agent 操作店铺”。
高级用户仍然可以直接使用本仓库里的 CLI、recipe、adapter 和 browser skill 能力。

模型能力说明

这个项目比较看模型能力。底层 Skill 尽量把网页信息、可点击目标、动作反馈、截图/局部证据、网络请求和经验库都整理好，但最终仍然是模型在做页面理解、路径选择、异常恢复和业务判断。

如果使用 GPT-5.5 或 Opus 4.7/4.8 这类强推理模型，并把推理强度拉满，复杂电商任务会明显更好用，尤其是商品发布、改价、SKU 修改、跨页面排错、弹窗处理、经验复用取舍、接口 CLI 化判断这类长链路任务。

如果使用国内的 DeepSeek、MiMo 等模型，也可以跑，并且项目已经专门做了优化：

1M 上下文窗口适配。
轻量 pageView，避免把重复 DOM/坐标信息塞满上下文。
可点击元素短 id 协议，减少模型输出格式错误。
动作后 pageChange 反馈，让模型能根据页面变化继续判断。
证据句柄和渐进式读取，按需再看局部 DOM、截图、区域文本和网络请求。
Flash/Pro 路由和诊断流程，普通任务走便宜模型，不确定时再切更强模型诊断。

不过需要说清楚：DeepSeek、MiMo 在复杂页面理解、长链路自主探索、细粒度视觉布局判断、异常恢复和业务取舍上，整体效果通常不如顶级强推理模型。它们更适合简单任务、成本敏感任务、已有经验路径、固定流程和半自动辅助场景。真要追求稳定自主完成，建议优先使用强模型并拉满推理强度。

项目定位

本项目是“电商 Agent”的浏览器 Skill 层，适合放在更大的桌面 App、CLI Agent 或多 Agent 系统下面使用。

它负责三件事：

感知网页：把浏览器页面、弹窗、表单、列表、按钮、滚动状态、截图和局部区域信息整理成模型可理解的证据。
执行动作：根据模型选择的目标执行点击、输入、滚动、上传、检查、抓包、请求复用等动作。
复盘沉淀：把稳定、低自由度、高重复的流程沉淀成 recipe 或 CLI adapter，让后续任务更快。

它不应该做的事：

不替模型判断“哪个商品是真的商品”。
不替模型判断“这个按钮是不是当前目标”。
不替模型判断“任务是否已经成功”。
不因为历史经验存在，就强制模型按经验走。
不把页面信息过度删减后再交给模型。

核心原则是：模型是大脑，脚本是感知和执行工具。

核心能力

1. 持久化浏览器会话

支持使用持久化 Chromium profile 保存登录态。不同平台、不同账号可以隔离存放，避免频繁掉登录态，也避免把登录态打进安装包。

已实现的方向包括：

商家账号 profile
消费者账号 profile
PDD、淘宝、京东、抖音等平台 profile 命名空间
可见浏览器登录流程
已打开浏览器的 CDP 接入

2. 页面结构化观察

Skill 会优先读取 DOM、accessibility tree、可见文字、表单、列表、表格、弹窗和滚动状态，生成模型可读的轻量页面视图。

页面视图里，可点击元素会带短 id，例如：

[a] 批量下架
[b] 删除
[c] 确认
商品名称：桌面收纳盒
30日销量：128

模型只需要选择当前页面里的短 id，工具内部再映射到真实 DOM 或坐标执行。短 id 是机械定位标记，不是业务判断。

3. 文字模型与视觉模型混合感知

纯文字模型可以使用结构化页面信息完成任务。

视觉模型可以额外使用截图、局部放大截图、区域文字检索和坐标信息，用来处理：

图标按钮
遮挡和浮层
canvas 或非标准组件
页面布局判断
小区域二次放大识别

视觉信息不作为小字、价格、库存、销量、商品 ID 等关键字段的唯一依据。关键业务字段应通过 DOM、局部 inspect 或接口结果再次确认。

4. 目标驱动执行

Skill 的设计目标是让 Agent 围绕用户目的工作，而不是被固定流程绑死。

例如用户说“把店里所有商品下架”，Agent 应该先观察页面，判断是否有批量下架、全选、分页、筛选、确认弹窗等更高效路径；如果有，就选择更快路径，而不是被迫一条一条点。

经验库是提速工具，不是限制工具。模型可以选择：

完全使用经验
部分使用经验
放弃经验重新探索
先走页面，再沉淀新经验

5. 动作后反馈和上下文控制

每次点击、输入、滚动或上传后，工具会返回页面变化证据。模型根据变化判断下一步。

对于大页面，Skill 支持“轻量主上下文 + 证据句柄”的模式：

当前页面只把必要可见文字和短 id 放进主上下文
大型 DOM、截图、完整证据放在 artifact / evidenceRef 里
模型需要时再按点、区域、行、卡片、截图局部渐进读取
已经过期的页面细节可以丢弃，只保留摘要

这样可以避免把几十万 token 的重复结构塞进上下文，也避免模型忘记协议。

6. 滚动探索

页面观察会返回滚动状态，例如是否还有下方内容、当前可视范围、文档高度等。模型可以像人一样决定是否继续下滑、回到顶部、切换标签页或搜索目标。

7. 请求捕获与 CLI 化

Skill 支持通过浏览器上下文记录 GET、POST、XHR、fetch 等网络请求，并生成候选 adapter。

适合 CLI 化的场景：

客服消息列表
聊天记录读取
发送回复
固定筛选查询
数据报表读取
低自由度、结构稳定的批量操作

不适合直接 CLI 化的场景：

高自由度商品发布
类目复杂且经常变化的表单
需要模型理解素材和页面反馈的流程
风控、验证码、人工确认强的流程

是否 CLI 化由模型根据任务、页面、接口稳定性和验证证据判断。工具只负责抓取、执行和返回证据。

项目结构

.
├─ SKILL.md                         # Skill 使用规则和 Agent 行为约束
├─ package.json                     # Node/Playwright CLI 入口
├─ scripts/
│  ├─ pdd-operator.mjs              # 当前主 CLI，保留旧名兼容
│  ├─ validate-recipes.mjs          # recipe 校验
│  ├─ setup.mjs                     # 依赖检查和安装辅助
│  ├─ verify-*.mjs                  # 通用能力、VLM、真实流程验证脚本
│  └─ lib/
│     ├─ browser-intelligence.mjs   # 通用浏览器感知/句柄/混合观察能力
│     ├─ persistent-session.mjs     # 持久化浏览器会话
│     ├─ snapshot.mjs               # 页面结构化快照
│     ├─ locator.mjs                # 短 id、定位和候选处理
│     ├─ actions.mjs                # 点击、输入、上传、滚动等动作
│     ├─ recipes.mjs                # recipe 执行
│     ├─ accounts.mjs               # 平台/账号/profile 管理
│     └─ product-*.mjs              # 电商商品理解和发布相关辅助
├─ recipes/                         # 可复用流程模板
├─ schemas/                         # recipe 和商品输入 schema
├─ guides/                          # 垂直场景操作指南
├─ references/                      # 架构、轨迹、故障恢复、覆盖计划
├─ fixtures/                        # 测试样例
└─ agents/                          # Agent 配置样例

快速开始

安装依赖：

npm install

检查环境：

npm run doctor

校验 recipe：

npm run validate:recipes

检查 CLI 语法：

node --check scripts/pdd-operator.mjs

查看帮助：

npm run help

常用命令示例

观察页面：

node scripts/pdd-operator.mjs browser.observe-light --url https://example.com --out page.json

连接已打开的 Chrome：

node scripts/pdd-operator.mjs browser.observe-light --cdp-url http://127.0.0.1:9222 --out page.json

查看浏览器标签页：

node scripts/pdd-operator.mjs browser.tabs --include-text --out tabs.json

检查局部区域：

node scripts/pdd-operator.mjs browser.inspect-region --x 240 --y 420 --w 600 --h 220 --out region.json

局部放大截图：

node scripts/pdd-operator.mjs browser.zoom-crop --x 240 --y 420 --w 600 --h 220 --scale 2 --out crop.json

记录网络请求：

node scripts/pdd-operator.mjs browser.network-record --duration 5000 --out network.json

执行模型确认过的 adapter：

node scripts/pdd-operator.mjs browser.adapter-run --adapter-file adapter.json --params "{\"page\":1}" --out adapter-result.json

适合的任务

这个 Skill 适合处理各种电商浏览器任务，例如：

商品发布
商品上下架
商品改价
SKU、库存、规格修改
店铺商品列表监控
竞品店铺销量观察
客服消息读取和回复
售后、订单、物流、报表查询
平台后台菜单探索
固定流程 CLI 化

它也可以作为更通用的网页任务底座使用，只是当前文档和 recipe 仍包含较多电商/PDD 场景。

与拼多多场景的关系

当前仓库保留了 pdd-operator 命令和一批 PDD 后台 recipe，这是因为它们已经经过真实环境验证。

新的项目定位是：

browser.* / session.* 是通用浏览器底座
PDD 是第一个电商平台适配层
其他平台可以复用同一套浏览器感知、短 id、持久化 profile、动作反馈、抓包和 adapter 机制
平台专属规则应该放在平台 adapter / guide / recipe 中，不要污染通用浏览器层

设计原则

模型判断，工具执行。
页面信息尽量完整，但主上下文保持轻量。
点击目标用短 id，坐标作为 fallback。
视觉用于布局和不规则组件，关键字段用结构化证据确认。
每次动作后必须观察变化。
经验库只提供参考，不强制路线。
CLI 化必须有模型批准和业务验证。
登录态只存在本机 profile，不进入仓库和安装包。
测试脚本可以验证能力，但不能替代真实流程测试。

安全和边界

本项目会操作真实浏览器和真实电商后台。使用时应注意：

不要提交登录态、cookie、token、运行日志和截图证据。
不要把测试店铺和正式店铺混用。
涉及删除、下架、改价、发货、退款等状态改变操作时，应让模型读取页面反馈并确认结果。
网络 adapter 不能只看 HTTP 200，必须看业务字段和页面状态验证。
平台协议变化后，旧 adapter 应重新抓取和验证。

当前状态

已验证能力包括：

持久化浏览器 profile
消费者/商家登录态入口
结构化页面观察
短 id 点击协议
动作后页面变化反馈
商品发布、上下架、改价等 PDD 真实流程
VLM 混合感知基础流程
店铺商品监控接口读取和结果校验
Windows 便携包发布到 GitHub Release

仍在演进的方向：

更多平台 adapter
更完整的通用电商 schema
更稳定的跨平台商品理解层
更系统的 CLI 化经验库
多 Agent 分工和任务复盘

Release

Windows 便携包放在 GitHub Release，不提交到 git 仓库历史中。

当前版本：

v0.1.95
PDD.Agent-0.1.95-win.zip

电商浏览器自动化 Skill

简介