ai-goofish-monitor 闲鱼登录态采集 Chrome 扩展（Xianyu Login State Extractor）使用与原理详解-开发者社区

后端
网页爬虫
AI 应用
前端
电商

【免费下载链接】ai-goofish-monitor

基于 Playwright 和AI实现的闲鱼多任务实时/定时监控与智能分析系统，配备了功能完善的后台管理UI。帮助用户从闲鱼海量商品中，找到心仪产品。

项目地址：https://gitcode.com/gh_mirrors/ai/ai-goofish-monitor

本篇技术指南完整讲解 ai-goofish-monitor 项目中chrome-extension目录下的闲鱼登录态采集扩展：它负责从真实浏览器中提取闲鱼（Goofish）登录态 Cookie、浏览器环境指纹与请求头，生成监控机器人可直接使用的 JSON 快照。读完本文，你将掌握该扩展的安装加载、一键采集、剪贴板导出流程，理解其基于 Manifest V3 +chrome.cookies/webRequest/scripting的底层实现原理，并学会将产出文件xianyu_state.json正确接入监控系统的登录态校验、任务绑定与多账号轮换链路。

扩展在项目中的定位

ai-goofish-monitor 是基于 Playwright 的闲鱼多任务实时/定时监控系统。监控爬虫以 Playwright 驱动 Chromium 访问闲鱼，而要维持"真实用户"身份，就必须携带真实账号的登录态。由于闲鱼 Cookie 中 HttpOnly 标记的字段无法通过页面 JavaScript 直接读取，常规的document.cookie方案存在天然盲区，因此仓库在 chrome-extension/README.md 中提供了专用浏览器扩展来打通这条链路：

This Chrome extension helps extract complete login state information from Xianyu (Goofish) for use with the monitoring robot. It also records browser environment hints and request headers to better mimic a real session.

其核心价值有两层：一是完整导出登录态（含 HttpOnly Cookie），二是连带记录浏览器环境与请求头，让监控端的 Playwright 会话能最大限度模拟真实浏览器指纹，降低被识别为自动化的风险。

安装：加载未打包的扩展

原文档给出了 4 步安装流程，按其操作即可：

打开 Chrome，地址栏访问chrome://extensions；
开启右上角的开发者模式（Developer mode）；
点击加载已解压的扩展程序（Load unpacked），选择仓库中的chrome-extension目录（即本指南所在的目录）；
加载完成后，扩展图标会出现在浏览器工具栏。

扩展的清单文件 chrome-extension/manifest.json 采用 Manifest V3（manifest_version: 3），版本号为1.1，扩展名为 "Xianyu Login State Extractor"。它声明了以下权限，理解这些权限有助于通过 Chrome 商店式的权限审核，也便于排查"为什么采集不到数据"类问题：

权限	用途
`activeTab`/`tabs`	定位当前活动标签页并读取其 URL，判断是否为 goofish.com 页面
`cookies`	通过`chrome.cookies`API 读取`.goofish.com`域下全部 Cookie（含 HttpOnly）
`scripting`	向当前页面注入采集脚本，读取`navigator`/`screen`/`localStorage`/`sessionStorage`，并触发一次探测请求
`webRequest`	监听`onBeforeSendHeaders`捕获真实请求头（配合`extraHeaders`）
`storage`	保存用户同意状态与功能开关（见 xianyu-login-state-privacy.html 的权限说明）
`host_permissions`	`://.goofish.com/*`，限定只在闲鱼域名下工作

使用：三步拿到可用登录态

原文档的使用流程可归纳为"登录 → 采集 → 复制保存"：

浏览器导航至https://www.goofish.com并登录你的闲鱼账号；
点击工具栏上的扩展图标打开弹窗；
点击"Extract Login State"（弹窗内实际文案为"1.点击获取环境+登录状态"），扩展会一次性采集cookies + 环境 + 请求头，并自动过滤无用/超大字段；
采集完成后，完整 JSON 会显示在弹窗的文本域中，点击"Copy to Clipboard"（即"2.点击复制"）复制；
将 JSON 文本保存为xianyu_state.json（或自定义文件名），即可交给监控机器人使用。

弹窗界面由 chrome-extension/popup.html 与 chrome-extension/popup.js 实现：extractBtn发起chrome.runtime.sendMessage({ type: 'captureSnapshot' })请求，stateOutput以JSON.stringify(snapshot, null, 2)格式化展示结果，copyBtn通过navigator.clipboard.writeText复制；采集期间按钮会进入禁用态并显示"采集中，请稍候..."，成功/失败均有 4 秒后自动消失的状态提示条（status区域的success/error样式）。

采集了什么：快照数据字段全解

点击采集后，后台 Service Worker chrome-extension/background.js 的buildSnapshot()会拼装出一个完整快照对象，字段结构如下（结合buildSnapshot源码整理）：

{ "capturedAt": "2026-10-13T04:00:00.000Z", "pageUrl": "https://www.goofish.com/", "page": { "pageUrl": "...", "referrer": null, "visibilityState": "visible" }, "env": { "navigator": { "userAgent": "Mozilla/5.0 ...", "platform": "Win32", "language": "zh-CN", "languages": ["zh-CN", "zh", "en-US", "en"], "hardwareConcurrency": 8, "deviceMemory": 8, "maxTouchPoints": 0, "webdriver": false, "doNotTrack": null, "userAgentData": { "brands": [...], "mobile": false, "platform": "Windows" } }, "screen": { "width": 1920, "height": 1080, "devicePixelRatio": 1, "colorDepth": 24 }, "intl": { "timeZone": "Asia/Shanghai", "locale": "zh-CN" } }, "storage": { "local": { "...": "..." }, "session": { "...": "..." } }, "meta": { "droppedStorageKeys": { "local": [], "session": [] } }, "headers": { "user-agent": "...", "accept": "...", "sec-ch-ua": "...", "...": "..." }, "cookies": [ { "name": "...", "value": "...", "domain": ".goofish.com", "path": "/", "expires": 1760328000, "httpOnly": true, "secure": true, "sameSite": "Lax" } ] }

各字段含义与采集逻辑对应关系如下：

cookies：chrome.cookies.getAll({ url })拉取当前标签页 origin 下全部 Cookie，并归一化sameSite（Chrome 的no_restriction→None、unspecified→Lax等，见mapSameSiteValue），同时保留httpOnly、secure、domain、path、expirationDate等属性；
env.navigator：来自页面注入脚本读取的navigator对象，filterEnvData()会主动剔除vendor等易变字段，仅保留userAgent、platform、language(s)、hardwareConcurrency、deviceMemory、maxTouchPoints、webdriver、doNotTrack与userAgentData（通过navigator.userAgentData.toJSON()获取）；
env.screen：screen.width/height、devicePixelRatio、colorDepth（filterEnvData同样做了字段瘦身，丢弃availWidth等冗余项）；
env.intl：Intl.DateTimeFormat().resolvedOptions()的timeZone与locale，用于让 Playwright 侧对齐时区与语言；
storage：localStorage/sessionStorage快照，单键值超过 4096 字节（MAX_STORAGE_ENTRY_LENGTH）的条目会被丢弃并记录到meta.droppedStorageKeys，避免超大字段撑爆配置文件；
headers：captureHeaders()通过webRequest.onBeforeSendHeaders监听真实请求头，并经filterHeaders()的白名单过滤（user-agent、accept、accept-language、referer、sec-ch-ua系列、sec-fetch-*、origin、cache-control等约 17 项），只保留对反检测最有价值的字段。

工作原理：三层 API 协同

原文档对原理仅有一句概括——"The extension uses thechrome.cookiesAPI to access all cookies for the.goofish.comdomain, including those with the HttpOnly flag set."结合 chrome-extension/background.js 源码，实际由三部分协同完成：

1. Cookie 采集（cookies API）：chrome.cookies.getAll({ url })属于浏览器扩展特权 API，不受页面 JavaScript 的 HttpOnly 限制，因此能拿到_m_h5_tk、cookie2等签名型登录凭证。采集结果被包装成 PlaywrightstorageState兼容的{ name, value, domain, path, expires, httpOnly, secure, sameSite }结构（见captureCookies）。

2. 页面环境采集（scripting API）：chrome.scripting.executeScript向当前标签页注入一段匿名函数，一次性读取location.href、document.referrer、visibilityState、navigator、screen、Intl与两类 storage。所有读取都包裹在try/catch中，即使个别属性被站点禁用也不会导致整个采集失败。

3. 请求头捕获（webRequest API）：captureHeaders()先注册onBeforeSendHeaders监听器（urls: ["*://*.goofish.com/*"]且限定tabId），再通过chrome.scripting注入一段fetch(\${window.location.origin}/__codex_probe?ts=${Date.now()}`)触发一次轻量探测请求，从而捕获带extraHeaders的完整请求头；2 秒超时兜底（setTimeout(() => cleanup(null), 2000)`），监听器只解析一次后即注销，不拦截、不修改任何流量。

产出接入：从 xianyu_state.json 到监控机器人

保存的xianyu_state.json是整个监控系统登录态的事实来源，后端在多个层次引用它：

默认路径常量：后端在 src/config.py 定义STATE_FILE = "xianyu_state.json"，src/infrastructure/config/settings.py 中也可通过环境变量STATE_FILE覆盖默认文件名；
启动强校验：CLI 入口 spider_v2.py 启动时检查STATE_FILE、任务绑定的account_state_file与state/目录，三者全无则直接报错退出："未找到登录状态文件。请在 state/ 中添加账号或配置 account_state_file"；
Web API 管理：路由 src/api/routes/login_state.py 提供POST /api/login-state（校验 JSON 合法性后写入xianyu_state.json）与DELETE /api/login-state（删除文件），后台 UI 的登录态页面即通过该接口保存/清除状态；src/api/routes/settings.py 也会探测该文件是否存在以展示状态；
多账号轮换：src/rotation.py 的load_state_files(state_dir)可加载state/目录下多个 JSON 作为账号池，配合任务配置中的account_state_file实现每任务固定账号或多账号轮换（相关校验见 src/domain/models/task.py）。

重要：扩展导出的不仅是 Cookies。在 src/scraper.py 的爬虫会话初始化逻辑中，若检测到快照包含env、headers、page、storage等增强字段，就会走"增强快照"分支：storage_state只取cookies数组，同时调用_build_context_overrides()（src/scraper.py）用快照中的userAgent、Accept-Language、timeZone、viewport、devicePixelRatio、maxTouchPoints覆盖 Playwright 上下文默认值，并用_build_extra_headers()（src/scraper.py）把白名单外的请求头写入extra_http_headers。换言之，你复制的环境指纹越真实，Playwright 模拟的会话就越接近真人。若快照不含这些增强字段（如旧版导出），则退化为直接作为storage_state文件路径使用，两种格式均兼容。

数据安全与隐私边界

扩展的数据处理遵循"本地拼装、用户主动触发、不上传"原则，详见仓库根目录的隐私说明 xianyu-login-state-privacy.html：

仅在用户点击"提取"的瞬间读取当前页面的登录 Cookie、请求头与浏览器环境，不监听、不常驻采集；
数据只在内存中拼装为 JSON，由用户手动复制到剪贴板，不写入任何远程服务器；
webRequest仅用于读取请求头生成 JSON，不拦截或修改任何网络流量；
storage权限只保存用户同意状态与功能开关，不存放敏感数据；
用户可随时关闭或卸载扩展，即停止一切采集行为。

常见问题与排查建议

根据源码逻辑，可预判以下典型问题：

提示"请先打开 goofish.com 页面"：getActiveGoofishTab()校验当前活动标签页 URL 必须包含goofish.com，请先切回闲鱼页面再点扩展图标；
采集超时/无请求头：captureHeaders依赖 2 秒内的探测请求，若页面网络异常或扩展权限被浏览器禁用（如隐私模式下未开启允许），会回退为null空对象，可检查扩展详情页的站点访问权限；
JSON 过大：超大 storage 键已被MAX_STORAGE_ENTRY_LENGTH = 4096自动丢弃，并在meta.droppedStorageKeys中标记；若文件仍偏大，可手动精简storage字段（多数情况下爬虫只需 cookies/env/headers）；
爬虫提示找不到登录态文件：确认导出的 JSON 保存位置与STATE_FILE（默认仓库根目录xianyu_state.json）或任务绑定的account_state_file路径一致，多账号场景可放入state/目录参与轮换。

小结

闲鱼登录态采集扩展是 ai-goofish-monitor"真实会话模拟"链路的第一环：它用最少的浏览器权限（cookies+webRequest+scripting），在一次点击内产出"登录态 + 环境指纹 + 请求头"三位一体的 JSON 快照；监控端在 src/scraper.py 中无缝消费这份快照，把采集到的真实指纹逐项映射为 Playwright 上下文参数。无论你使用单账号的xianyu_state.json，还是通过state/目录构建多账号池，这套"真实浏览器取证 → 机器人会话复刻"的机制都是保障监控任务稳定运行的基础设施。