Taobao Agent (淘宝桌面版 MCP 助手)

验证码叠加防护（captcha-guard）

captcha-guard 是独立补丁，默认关闭。它从不可变 ASAR 基线重建主进程和两个 preload，统一普通 MTop 与流式请求的验证状态。首次安全验证只显示一个 iframe；验证期间暂停自动化和后台 MTop 请求，直接返回 CAPTCHA_REQUIRED，不排队、不重放。验证 iframe 自身的网络访问保持可用。

npm run test:captcha                 # 无网络夹具、真实源代码锚点和语法检查
npm run test:captcha -- --install    # 完整客户端的临时副本：安装、独立恢复、UI 补丁组合及回滚
npm run captcha:status              # 只读检查补丁注册表、安装哈希及备份
npm run captcha:apply               # 只启用验证码防护；已关闭的客户端保持关闭
npm run captcha:restore             # 只恢复验证码防护，保留其他补丁
npm run client:stop                 # 使用结束后关闭客户端及其子进程

安装前会验证唯一转换锚点、JavaScript 语法、ASAR 内容与完整性、现有门禁/功能签名，以及 CSS 和解包 sidecar 哈希。源代码不兼容或安装文件发生外部漂移时拒绝覆盖。注册表升级为 v5，并保留原始 v4 注册表；declutter:apply all / declutter:restore all 仍只操作四个 UI 分组。后续 UI 操作会从同一基线重新组合验证码防护。

安装和恢复复用事务日志。写入失败时恢复完整的原有 ASAR、CSS 和注册表；进程中途退出后，再次运行同一命令会先恢复未完成事务。备份目录为 %APPDATA%\taobao\taobao-agent-declutter-backup，不要删除或手工改写其中的基线、哈希和 manifest.json。发现 DRIFTED 时先保留现场并检查客户端更新或其他补丁，不要强制覆盖。

正在运行的客户端会受控重启，并通过 Windows Shell 在交互桌面中最小化启动；安装前已经关闭的客户端会保持关闭。未使用客户端时不要将其留在后台。补丁不会删除缓存、修改下载的 CDN 文件或更新 skills/。现有功能解锁、UI 补丁及 declutter observer 保留。

MCP 工具发现（tools/list）和本地验证控制不会自动启动客户端，避免仅连接 MCP 就留下后台进程。客户端关闭时工具发现会返回连接错误；需要使用时先运行 npm run client:start，再刷新 MCP 工具连接。桥接器文件更新后，已有 MCP 连接需重新连接才能加载新逻辑。

手动完成滑块后，状态变为 verified_awaiting_confirmation。用户明确回复“已完成验证”之前，代理不得恢复页面操作。get_verification_status() 只读取本地状态和计数；resume_after_verification({ challengeId }) 仅在用户明确确认后调用，未完成或过期编号会被拒绝。关闭验证窗口仍保持暂停，使用“重新打开验证”按钮继续手动验证。验证参数仅保留在内存，绑定原始账号、API、版本和序列化请求数据，恢复后只供一个新发起的匹配请求使用。

本地页面工具保留登录检查并跳过 ABExperimentQuery；云工具保留原有流程。相同登录状态和账号不会再次触发凭据预热。MTop 页面未就绪返回 MTOP_NOT_READY，不当作网络错误进行三次重试。网络凭据刷新失败后冷却 60 秒，没有定时重试；账号变化或可信页面重新就绪才重置冷却。

测试夹具 scripts/captcha/fixtures/mtop-2.4.16.txt 来自本机已缓存的 SDK，只在隔离的假 DOM/传输环境中执行。测试不会调用淘宝 RPC 或外部网络。安装后需先由用户手动完成验证并确认，再执行少量只读操作及十分钟 CPU、内存和生命周期计数采样；验证再次出现时立即暂停。

用户确认且本地协调器恢复为 idle 后，可运行 node scripts/captcha/profile.js --manual-confirmed。采样默认持续十分钟，每五秒记录进程 CPU、工作集、私有内存及本地生命周期计数到 backup/captcha-investigation/profile-*.jsonl；进程变化或 CPU 不可读取时不会用零值冒充可靠测量。验证出现或客户端退出时立即停止，不会自动启动客户端、确认验证或调用页面工具。使用结束后运行 npm run client:stop。

Related MCP server: Taobao MCP Server

📖 项目简介

taobao-agent 是面向消费者与开发者的本地购物助理架构。它通过标准 Model Context Protocol (MCP) 将 淘宝桌面版（Windows Electron 客户端） 的内部原生能力暴露给 AI 编程助手与自主智能体（包括 Claude Desktop、Google Antigravity、Cursor、Cline 等）。

通过双向命名管道（Named Pipe IPC），智能体能够以高执行自由度完成商品自然语言搜索、多维度比价分析、商详与真实 SKU 价格提取、购物车增删、旺旺商家会话以及售后评价。

🏗️ 架构概览

flowchart TD
    subgraph AgentHost ["AI 智能体宿主 (Host)"]
        A["Claude Desktop / Antigravity / Cursor"]
    end

    subgraph Bridge ["本地 MCP 桥接层"]
        B["taobao-mcp-bridge.js (stdio JSON-RPC 2.0)"]
    end

    subgraph DesktopClient ["淘宝桌面版 (Windows Electron)"]
        C["Windows 命名管道: \\\\.\\pipe\\taobao-cli-rpc"]
        D["Main Process (app.asar - 已打补丁)"]
        E["Renderer / BrowserViews (DOM & WindVane)"]
        F["SecurityBodyguard / UTDID (原生会话)"]
    end

    A <-->|标准 stdio MCP 协议| B
    B <-->|命名管道 RPC| C
    C <--> D
    D <--> E
    D <--> F

✨ 核心特性

1. 原生 MCP 双向桥接 (taobao-mcp-bridge.js)

• 基于标准 JSON-RPC 2.0 stdio 协议，无缝接入各类 MCP 客户端。

• 30 秒超时防悬挂与 2 秒轻量 Ping 探测机制，确保连接高可用与资源释放。

• 自动唤起守护：检测到客户端未运行时，自动以窗口化最小化模式启动客户端。

2. 零字节偏移 ASAR 补丁工具 (scripts/patch-asar.js)

通过原位定长字节替换（In-place Binary Patching），不改动 ASAR 文件头或偏移量，实现安全免疫：

• 内测白名单放行（Gatekeeper Bypass，13 字节）：中和 if(_0x2505bf) 云控拦截，解决 内测期间仅开放部分用户使用 锁机报错。

• 消费能力解锁（Feature Unblocker，29 字节）：解除官方在 function am() 中对加购、聊天、评价工具的静默压制，原生放行 add_to_cart、open_chat、send_chat_message、submit_product_rating 与 keyboard。

• 一键原版还原（Restore）：自动生成 .original.bak 备份，随时恢复官方未修改版本。

3. 人机协同风控协同协议（Human-in-the-Loop Protocol）

• 自动识别淘宝安全校验与滑块拦截（安全验证、拖动滑块完成验证、RGV587_ERROR、验证码）。

• 立即暂停自动化调用，防止频繁重试导致风控升级；主动提示用户在已开启的桌面端窗口完成滑块验证后无缝继续任务。

4. 真实 SKU 价格等待机制

• 搜索列表页价格与默认商详价格通常为引流起步价（起步配件价）。

• 智能体严格遵循：进入商详 $\rightarrow$ DOM 扫描 $\rightarrow$ 精准 Index 点击 SKU $\rightarrow$ 等待 3 秒异步刷新 $\rightarrow$ 读取真实价格。

5. 结构化购物车安全防护

• 购物车扫描支持返回结构化 cartItems，包含精确的 deleteIndex。

• 严格遵循不修改/不删除用户既有加购商品的安全约束，保证资产安全。

📂 项目结构

taobao-agent/
├── README.md                        # [中文说明文档]
├── README_EN.md                     # [英文说明文档]
├── AGENTS.md                        # 智能体执行准则与工作区治理规范
├── UPSTREAM_SYNC_LOG.md             # 上游热更 Diff 审计与三原则决策日志
├── package.json                     # NPM 脚本与项目元数据
├── taobao-mcp-bridge.js             # Stdio MCP Bridge 连接 \\.\pipe\taobao-cli-rpc
├── skills/                          # 核心智能体技能定义
│   ├── taobao-native/               # 原生执行技能 (v1.0.61 基线)
│   ├── product-search-pipeline/     # 搜索分流与 Slot 提取 (v1.1.4 基线)
│   ├── shopping-recommendation/     # 导购比价策略与 4 层过滤 (v1.0.8 基线)
│   └── procurement-assistant/       # 批量采购与表格解析 (v1.0.62 基线)
└── scripts/                         # 维护与测试工具
    ├── check-diff.js                # 上游技能对比与审计工具
    ├── patch-asar.js                # 零偏移 ASAR 门禁与能力解锁补丁工具
    ├── declutter.js                 # 事务化界面精简与补丁组合管理
    ├── declutter-patches.js         # 纯函数补丁规则与 AST/CSS 转换
    ├── client-stop.js               # 受控关闭桌面端及其子进程
    ├── test-captcha.js              # 验证码叠加防护全量离线测试套件
    ├── test-declutter.js            # 界面精简 16 种组合与回滚迁移测试
    └── captcha/                     # 验证码防护主/渲染进程协调与诊断子系统

🚀 快速上手

环境准备

• 操作系统：Windows 10 / 11 64-bit

• 运行环境：Node.js >= 18.0.0

• 客户端：淘宝桌面版（默认安装路径位于 %LOCALAPPDATA%\Programs\taobao\）

1. 克隆代码仓库

git clone https://github.com/Schrodingers-Neko/taobao-agent.git
cd taobao-agent
npm install

2. 检查并应用 ASAR 补丁

# 检查当前客户端补丁状态
npm run patch:status

# 一键应用全部补丁（白名单放行 + 核心工具解锁）
npm run patch:all

注意：打补丁前脚本会自动在客户端目录创建 app.asar.original.bak。随时可通过 npm run restore 还原。

3. 启动淘宝桌面版

# 自动以窗口化且最小化（不打扰用户）模式启动客户端
npm run client:start

4. 配置 MCP 客户端

在你的 AI 客户端（如 Claude Desktop 或 Antigravity）的 MCP 配置文件中添加：

Claude Desktop 配置示例 (claude_desktop_config.json)

{
  "mcpServers": {
    "taobao-native": {
      "command": "node",
      "args": [
        "F:/projects/personal/taobao/taobao-mcp-bridge.js"
      ]
    }
  }
}

🛠️ NPM 常用指令

补丁分为 home-widgets（淘江湖、淘宝直播、淘金币）、search-promotions（搜索热词与促销标识）、main-menu（帮我挑、逛一逛、采购宝）和 toolbar（天气、桌面熊猫、截图按钮）。使用 all 可明确应用或恢复全部四个分组；应用和恢复必须指定目标。下方可选入口通过“全部”菜单管理，迁移时移除此前六个入口的 CSS 隐藏补丁。保留 88VIP、物流、购物车、推荐流设置和原生导航接口。

使用 npm run declutter:apply -- toolbar 或 npm run declutter:restore -- toolbar 可独立隐藏或恢复上述三个顶栏入口。保留足迹、设置、更多、头像、窗口按钮和现有截图快捷键。旧的三分组登记文件会自动升级，保留已启用状态和原始备份。

首页两个分组保留内置样式和原有覆盖文件，共用的新首页 CSS 加载修复仅在两个分组均恢复后移除。ASAR 始终由不可变原始内容和当前启用的分组组合生成；恢复全部分组后，ASAR 与 CSS 回到原始字节或原始不存在状态，保留基线已有的白名单绕过和工具解锁补丁。

新首页只注入带标记的精简规则，保留页面自身的主题样式。首页组件补丁同时隐藏目标组件各自的卡片容器，避免留下空白卡片，并保留 88VIP。搜索精简同时隐藏推广占位层，保留输入框、搜索按钮和独立的桌面搜索文档。重复操作若未改变已安装文件，则不重启客户端。

原始快照和版本化登记文件保存于 %APPDATA%\taobao\taobao-agent-declutter-backup。迁移保留已有备份。提交失败自动回滚，中断提交在下次修改命令时恢复。无关的 ASAR/CSS 变更或损坏的备份会阻止安装。状态检查仅验证已安装文件，不代表远程页面选择器的视觉效果已验证。客户端更新可能需要新的兼容基线，不应删除备份来绕过变更检测。独立的 npm run restore 仍为整个官方归档的恢复命令，不能用于单个界面分组恢复。

运行 node scripts/test-declutter.js 可验证十六种组合、独立切换、迁移与恢复流程；添加 --real 则对已安装客户端的临时副本验证重建与恢复。使用 --real-toolbar 可针对完整客户端副本验证顶栏分组的应用与恢复，并确认其他分组和 CSS 未变。

🛡️ 三原则治理机制 (Three-Way Filter Policy)

淘宝桌面客户端会不定期从官方 CDN 推送内部热更。当检测到上游技能更新时，本项目遵循严格的 三原则过滤：

详细审计记录见 UPSTREAM_SYNC_LOG.md。

⚠️ 免责声明

1. 本项目仅供技术研究、个人无障碍辅助及消费者自主权增强使用。

2. 自动化购物涉及资金交易，请在最终支付与结算环节保持人工核对确认。

3. 请合理控制调用频率，遵守平台服务使用条款。

📄 开源许可证

本项目基于 MIT License 开源。