闲鱼 Codex 全量选品助手

xianyu-shopping-assistant 是一个默认面向个人只读场景设计的 Codex 插件。你可以在一次 Codex 对话中描述想买的二手商品，插件会通过专用的可见 Chrome 只读采集当前账号可发现的闲鱼网页结果；优先详情形成有界缓存样本后可先给暂定条件建议并继续长尾，最终再由 Codex 逐页比较完整紧凑候选、维护最多 20 项滚动短名单，并给出最多 3 个正式购买建议。

这里的“全量”不是闲鱼平台数据库全量，而是当前账号在采集时能够连续翻到、且没有触发结构错误或安全停止的全部网页结果。采集频率保守，但仍不能保证账号零风险。详细边界见 安全与覆盖边界。

系统要求

• Windows x64；项目面向 Windows 10、Windows PowerShell 5.1 和当前 Windows 用户的 DPAPI。

• 已安装 Codex CLI，且 codex --version 可在 PowerShell 中正常执行。

• 已安装正式版 Google Chrome。插件不会读取日常 Chrome Profile。

• 从 GitHub 获取源码时需要 Git；也可以下载仓库源码压缩包后在解压目录中执行安装。

• 安装时可访问 Python 官方下载地址和 Python 包源；使用时可访问闲鱼网页版。

• 当前用户可写入 %LOCALAPPDATA% 和 %USERPROFILE%。

不需要预先安装系统 Python。安装脚本会验证 Python 官方安装器和固定组件的签名与 SHA-256，在 %LOCALAPPDATA%\XianyuShoppingAssistant 中构建无注册的独立 Python 3.12.10 和虚拟环境，不修改系统 PATH、py 或其他项目环境。

Related MCP server: Goofish MCP Server

安装

克隆仓库并进入项目根目录。先执行只读检查，再正式安装：

git clone https://github.com/YRMDLG/xianyu-shopping-assistant.git
Set-Location .\xianyu-shopping-assistant
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -CheckOnly
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

-CheckOnly 会检查 Codex CLI、Chrome、Python 官方下载端点、依赖锁和个人 marketplace 结构，不会下载文件、创建目录或安装插件。正式安装会验证 Python 安装器及 core、exe、lib 组件的 Authenticode 签名和固定摘要，以无注册行政映像构建独立解释器，再按哈希锁安装依赖并让 Codex 注册插件。

安装完成后，主要文件位于：

安装器已经校验 Codex 中的插件记录。也可以自行查看：

codex plugin list --json

插件列表只证明安装记录存在，codex mcp list 也不是插件 companion MCP 可发现性的充分验证。安装后必须新建 Codex 任务，让 Codex“查询闲鱼选品助手状态”；只有新任务实际调用只读 xianyu_get_status 并返回登录、风控和预算摘要，才算完成 MCP 发现性检查。

安装、更新或卸载后必须新建 Codex 任务，已有任务不会自动加载新的 Skill 或 MCP。

首次扫码与研究

1. 新建一个 Codex 任务。

2. 发送明确的购买需求。首次测试可直接使用下面的提示词：

   请用原始关键词“小米pad7S Pro 12+256”搜索闲鱼，排除配件、求购、维修、租赁和明显错型号。采集并在本地分析当前账号可发现的完整候选集，比较后最多推荐 3 个，并列出覆盖范围、失败项、价格位置、卖家公开证据和仍需人工核实的问题。

3. 若尚未保存登录态，Codex 会先请求你确认打开专用 Chrome。明确回复“确认打开专用 Chrome 登录窗口”后，插件才会打开可见窗口。

4. 使用手机扫码并完成手机端确认。登录窗口有固定等待时间；超时后重新在对话中确认登录即可，不要向 Codex 提供任何 Cookie 或登录凭据。

5. 登录成功后，插件保存经当前 Windows 用户 DPAPI 加密的专用登录态并开始任务。第一个搜索词会逐字保留为 小米pad7S Pro 12+256；Codex 只有在扩大召回确有必要时才会增加别名 小米 Pad 7S Pro 12+256。

6. 等待 Codex 按状态推进。原始关键词第一页落盘后可先显示一次只读“首屏市场快照”；详情达到严格的 8/10 门槛后可再显示带样本数和剩余量的暂定条件建议。每次本地进度等待最多 60 秒，同一任务会继续有界等待；正式结论仍需等待长尾。大数据集受固定间隔和滚动预算约束，可能需要数小时或跨天完成。

单个研究任务只在当前 Codex 任务的 MCP 运行时活动期间执行，不注册 Windows 服务、不托盘运行、不开机自启，也不会脱离 Codex 在后台继续。一次工具等待有固定上限，但整个研究耗时不固定；若 Codex 任务或应用被关闭，系统不能自动唤醒模型。已经落盘的检查点不会丢失；新建 Codex 任务后可以要求“继续已有的闲鱼研究任务”。若不知道 job_id，Codex 会从本地任务列表第一页开始以每页 50 条读到末页，拒绝缺失或重复游标，并在全部分页结果中按完整研究请求精确匹配，再用进度中的请求指纹确认原任务；不会只凭关键词猜测，也不会命中一条就提前停止。若中断发生在搜索翻页中，新进程会从第一页开始逐页重新导航，并用已保存的游标、内容指纹和页码证据校验连续性；每个校验页都会消耗一次搜索预算，但不会重复累计页面或商品。任一旧页已经漂移时，该关键词会停止并报告部分覆盖，不会直接跳到未知页。

采集使用两阶段漏斗。第一阶段完整保存当前账号可发现列表的标题/富标题、价格、地区、缩略图和有界短说明；所有结果仍留在 SQLite 和导出中，但明确错型号、配件/求购/维修/租赁、已知超出硬预算或公开文本明确出现不可接受瑕疵的项不再浪费详情导航。第二阶段按相关且预算内、不确定且预算内、相关但信息不足、其他保留项的顺序串行读取详情，保存完整描述、成色、公开卖家指标、最多 10 条同次导航被动返回的首屏评论，以及经过域名校验的商品图片 URL；不会滚动评论、遍历卖家历史或请求任意 URL。网页返回的无显式端口 HTTP 图片地址只有在主机精确属于三个固定阿里 CDN、无用户信息和 fragment 且路径非空时，才会在本地规范为同主机 HTTPS；图片客户端始终不发送 HTTP 请求。

为了缩短第一次看到有用信息的等待，进度会在原始关键词第一页提交后立即发布只读 first_page_snapshot。它只用已经落盘的标题、价格、地区、缩略图和短说明做本地硬筛与稳定排序，最多展示 10 项，不增加任何平台导航；必须明确标为“仅原始关键词第一页、详情中的成色和芝麻信用未核验、不是购买建议”。别名、第二页和后续数据不会混入这个快照，Codex 展示后仍继续采集。

详情阶段另提供严格有界的暂定预览。只有任务仍在 collecting_details，或明确因详情预算进入 waiting_budget，至少 8 个唯一详情尝试已经终结、至少 1 个成功，并且已经出现至少 3 个满足当前结构化偏好的候选时，provisional_preview.ready 才会变为 true；若前 8 项不足 3 个合格候选，则在 10 次尝试后兜底开放并如实报告不足。此时 Codex 可用 analysis_scope=provisional 一次读取最多 20 个本地前沿候选，再以每批最多 10 个和同一 snapshot_revision 读取已经缓存的详情，并先给一版醒目标注为“暂定预览 / 条件建议”的进度更新。暂定输出必须列出实际样本数、已尝试数、合格数、成功数和剩余详情数；它不代表最终排名、完整覆盖或商品仍在售。

暂定读取不会访问闲鱼，不增加搜索、详情或卖家导航，也不写入持久评分、排名、完整扫描证明或短名单；它不能补卖家画像、下载图片、刷新在售状态或提交补证据集合。给出暂定更新后，Codex 会继续轮询同一任务的长尾详情。默认 analysis_scope=final 的正式流程不变：只有全部列表和详情阶段冻结后才逐页扫描完整候选、补受限证据并输出 0 至 3 个正式购买建议。

预算、近新词、瑕疵词、可接受的公开芝麻等级和赠品词保存在独立版本化 selection_profile。档案中的最低价和最高价都是列表硬门槛；“预算差不多 2000–2500”这类近似区间只把 2500 设为档案硬上限，2000 保留在不可变研究请求中作为偏好价带下限，低于它的相关项仍采详情并作为异常低价风险降权。只有用户明确表示“低于下限不考虑”时才设置档案硬下限。后补档案时原 research_request、请求指纹和平台导航计数必须不变；普通包含词不会被当作赠品，赠品也只能有限加分，不能抵消超预算、明确瑕疵或信用不合格。默认的 final 候选只允许在当前完整分析快照可读时分页；否则统一返回可重试的 analysis_not_ready，不会拿旧评分继续推荐。严格有界的 provisional 缓存前沿是详情采集阶段的唯一例外，不能形成正式结论。常规推荐固定使用 stable/all/50 的 scan 精简投影逐页比较全部候选，并回显列表证据、筛选决策、详情信号、图片 URL 数量和在售证据；页间只保留计数不变量和最多 20 项滚动短名单，后页候选可以淘汰首页候选。服务端只有在 processed_unique=expected_total、分类闭包成立且末页游标为空时才接受短名单。随后 Codex 以每批最多 10 项读取本地详情，提交最多 20 个卖家候选、最多 10 个图片候选和最多 10 个一次性在售刷新候选；没有合格项时绑定空短名单、零新增平台导航并推荐 0 个。“卖家靠谱”“适合长期使用”等无法可靠结构化或无法由公开证据证明的自由要求只在滚动短名单详情内作为人工核实项，不能声称对完整数据集做了自由语义筛选。

最终答复应包含采集时间、关键词分别对应的页数和停止原因、原始数和去重数、相关性分类、详情/卖家/图片成功率、筛选档案 hash/revision、缓存状态、请求指纹、平台导航计数、覆盖结论，以及 0 至 3 个有真实证据的建议。公开信用缺失或来源冲突不能当作合格；一次性刷新明确不可用的商品不得推荐，状态未知只能作为待人工确认的条件备选。跨新任务恢复终态短名单时，每个推荐都必须从缓存详情自带的候选摘要恢复商品链接、价格百分位、评分组成、风险标签、详情信号和在售证据；缺少该摘要的候选不能推荐。证据不足时，合理结果可能是少于 3 个、本轮推荐 0 个或明确不建议购买。

短名单刷新后的标题、价格和在售状态按同一规则生效：只在所有 status=succeeded 的刷新 attempt 中选择编号最新的一次；非空刷新标题覆盖初次详情标题，刷新价格包括 0 在内都会覆盖初次详情价格。后续失败或暂停的 attempt 即使留下异常快照也不会覆盖较早的成功刷新。终态会用生效标题重新计算相关性、瑕疵和赠品信号；最终硬筛、市场统计、评分、候选分页与排序、详情、报告和导出统一使用这些生效值，初次详情值与刷新值仍分别保留为审计证据。

xianyu_enrich_candidates 的 retry_failed 和 confirm_retry 均默认为 false。普通研究以及未传这两个字段的旧调用不会重试已经终结的补证据步骤。只有两者同时为 true、任务已经是 completed 或 partial，并且提交的卖家、图片和在售候选集合与原持久短名单完全一致时，服务端才允许同一内部修复键执行一次兼容修复。

该修复只处理两类旧记录。旧在售记录必须同时具有 network_response 来源的 attempt 与 snapshot，二者都保存为 unknown 且包含 availability_status_invalid；首次 attempt 还必须成功完成真实详情导航且没有错误码。历史脱敏快照没有保存原始 itemStatus 值，因此这些条件只能证明旧 parse-invalid 证据适合一次重核验，不能证明当时的具体上游字段形态。另一类是来源可安全升级到固定 HTTPS 阿里 CDN 的 legacy HTTP 图片，且旧拒绝原因精确为 image_policy_rejected。修复不重新选择候选，不重试卖家画像、明确 unavailable、403/429、当前具体图片策略拒绝或其他失败。全局风险闸门一旦暂停，双确认也绝不产生重试；应按“诊断与风险恢复”处理，而不是重复调用工具。

研究报告在同一个 SQLite 只读快照中组装。若多个 MCP companion 同时活动并在读取前后改变任务 revision，xianyu_get_research_report 返回可重试的 report_snapshot_changed，不会在单次报告内混合 revision。Codex 必须丢弃该次报告和同 revision 的终态详情，重新读取一次最新进度后再读取整套终态证据，并在完成后复核 progress revision；连续第二次变化时停止并报告快照不稳定。

任务状态

partial 不等于“差不多完整”，completed 也不代表每个详情、卖家或图片都采集成功。始终以报告中的 coverage_conclusion、停止原因和成功率为准。

缓存复用

相同原始关键词、别名、研究价格、地区、词组和需求摘要组成同一规范化请求。独立 selection_profile 不参与该请求指纹；用完整显式档案重放同一研究请求只会在本地原子更新筛选证据，不得新建任务或产生平台导航。未结束的同条件任务无论已经运行多久都会复用原 job_id；终态任务则在 finished_at 后 10 分钟内复用。列表和进度会分别回显可直接重放的完整研究请求、筛选档案及稳定请求指纹，跨 Codex 新任务时应按采集身份精确匹配，再单独核对筛选档案，不能只比较关键词。缺少可信完成时间的异常终态不会作为缓存复用。

验证缓存复跑时，先确认首次任务已经终态、finished_at 非空，并且当前时间不晚于完成时间加 10 分钟。完成时间缺失或已经过窗时只报告无法验收，不重放请求。仍在窗口内才记录首次终态的 job_id、请求指纹、筛选档案 hash/revision，以及搜索、详情、卖家和总平台导航计数，再原样重放回显的完整研究请求与筛选档案。只有第二次返回同一 job_id、cache_reused=true、相同指纹、相同档案身份，并且四个导航计数全部不变，才说明本次复跑没有新增平台导航。

缓存复用不表示商品仍在售，也不表示每一页都来自缓存。失败或已取消的同条件任务也可能在 10 分钟窗口内被复用；不要通过反复改词绕过该窗口或安全预算。

诊断与风险恢复

默认诊断是只读操作。先关闭所有正在使用本插件的 Codex 任务，再运行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\doctor.ps1

诊断会显示脱敏的风险闸门、登录闸门、未收敛操作、worker 租约和隔离截止时间。它不会输出登录秘密，也不会自动解除暂停。

只有在你已经人工确认平台页面正常、所有 Codex/MCP worker 均已停止、租约已到期且隔离窗口已结束后，才可显式恢复全局风险闸门：

powershell -NoProfile -ExecutionPolicy Bypass -File .\doctor.ps1 -ResumeRisk -Confirm

该命令不是验证码或风控绕过工具。诊断拒绝恢复时，应保留暂停并处理它报告的本地状态，不要换号、换 IP 或连续重试。

更新

关闭所有使用本插件的 Codex 任务，在新版源码根目录先检查再更新：

powershell -NoProfile -ExecutionPolicy Bypass -File .\update.ps1 -CheckOnly
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
powershell -NoProfile -ExecutionPolicy Bypass -File .\update.ps1
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

更新会替换隔离虚拟环境和插件副本，安全合并个人 marketplace，并保留 SQLite、加密登录态、图片、日志和导出。更新完成后新建 Codex 任务。

卸载

关闭使用本插件的 Codex 任务。普通卸载移除 Codex 插件、插件副本和运行代码，但保留本地研究数据，便于以后重新安装复用：

powershell -NoProfile -ExecutionPolicy Bypass -File .\uninstall.ps1

只有下面的双确认命令会删除固定运行目录中的加密登录态、SQLite、图片、日志和导出；此操作不可恢复：

powershell -NoProfile -ExecutionPolicy Bypass -File .\uninstall.ps1 -PurgeData -Confirm

导出数据

只有明确要求时，Codex 才会调用导出工具。格式仅支持 UTF-8 jsonl 或带公式注入防护的 csv，文件只能写入 %LOCALAPPDATA%\XianyuShoppingAssistant\exports。当前导出 schema 为 v5，首条 metadata 记录的 schema_version 可用于识别格式；顶层 title、price_cents 使用最新成功刷新的生效值，initial_title、initial_price_cents 保留初次详情审计值。全部候选（包括列表硬筛跳过项）及其每次历史列表快照都会保留白名单清洗、最多 300 字的 list_excerpt。v5 仅导出通过 HTTPS、精确阿里图片域名、userinfo、端口和路径校验的公开列表 thumbnail_url；不导出详情图片 source_url、原始页面对象、本地缓存名或路径、Cookie 和其他凭据。工具会返回记录数和 SHA-256；导出文件不是加密文件，应按包含公开商品与卖家数据的普通数据集保管。

开发与验证

准备项目隔离开发环境：

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\bootstrap-dev.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\bootstrap-dev.ps1 -Check

运行发布 Gate：

.\.runtime\python.exe -m pytest -q
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

.\.runtime\python.exe -m ruff check .
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

.\.runtime\python.exe -m ruff format --check .
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

.\.runtime\python.exe -m pyright
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

.\.runtime\python.exe -m build --no-isolation
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

$env:PYTHONUTF8 = "1"
.\.runtime\python.exe "$env:USERPROFILE\.codex\skills\.system\plugin-creator\scripts\validate_plugin.py" .\plugin\xianyu-shopping-assistant
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

.\.runtime\python.exe "$env:USERPROFILE\.codex\skills\.system\skill-creator\scripts\quick_validate.py" .\plugin\xianyu-shopping-assistant\skills\xianyu-buying-assistant
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

git diff --check
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

$releaseFiles = @(git ls-files --cached --others --exclude-standard)
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$forbiddenRuntimeFiles = @(
    $releaseFiles | Where-Object {
        $_ -match '(^|/)(data|logs|exports|images|state|\.runtime)(/|$)' -or
        $_ -match '\.(dpapi|sqlite3?|db(?:-shm|-wal)?|log)$' -or
        $_ -match '(^|/)storage_state.*\.json$' -or
        ($_ -match '(^|/)\.env(?:\.|$)' -and $_ -notmatch '\.env\.example$')
    }
)
if ($forbiddenRuntimeFiles.Count -ne 0) {
    throw "发布集合包含运行态或敏感文件：$($forbiddenRuntimeFiles -join ', ')"
}

$secretPattern = @(
    'AKIA' + '[0-9A-Z]{16}',
    'gh[pousr]_' + '[A-Za-z0-9]{36,}',
    'github_' + 'pat_[A-Za-z0-9_]{20,}',
    'sk-proj-' + '[A-Za-z0-9_-]{40,}',
    'sk-' + '[A-Za-z0-9]{20,}',
    '-----BEGIN ' + '(RSA |EC |OPENSSH )?PRIVATE KEY-----'
) -join '|'
$secretFiles = @(& rg -l -a -e $secretPattern -- @releaseFiles)
$secretScanExit = $LASTEXITCODE
if ($secretScanExit -gt 1) { exit $secretScanExit }
if ($secretFiles.Count -ne 0) {
    throw "发布集合发现疑似凭据，命中文件：$($secretFiles -join ', ')"
}

$historySecretFiles = @()
$commits = @(git rev-list --all)
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
foreach ($commit in $commits) {
    $matches = @(& git grep -a -l -E $secretPattern $commit --)
    $historyScanExit = $LASTEXITCODE
    if ($historyScanExit -gt 1) { exit $historyScanExit }
    $historySecretFiles += $matches
}
$historySecretFiles = @($historySecretFiles | Sort-Object -Unique)
if ($historySecretFiles.Count -ne 0) {
    throw "可达 Git 历史发现疑似凭据，命中文件：$($historySecretFiles -join ', ')"
}

$historyRuntimeFiles = @(
    git log --all --name-only --format= |
        Where-Object {
            $_ -and (
                $_ -match '(^|/)(data|logs|exports|images|state|\.runtime)(/|$)' -or
                $_ -match '\.(dpapi|sqlite3?|db(?:-shm|-wal)?|log)$' -or
                $_ -match '(^|/)storage_state.*\.json$' -or
                ($_ -match '(^|/)\.env(?:\.|$)' -and $_ -notmatch '\.env\.example$')
            )
        } |
        Sort-Object -Unique
)
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
if ($historyRuntimeFiles.Count -ne 0) {
    throw "可达 Git 历史包含运行态或敏感路径：$($historyRuntimeFiles -join ', ')"
}

生成忽略提交的 CycloneDX SBOM：

New-Item -ItemType Directory -Force .\sbom | Out-Null
$env:PYTHONIOENCODING = "utf-8"
.\.runtime\python.exe -m cyclonedx_py environment --PEP-639 --pyproject .\pyproject.toml --spec-version 1.6 --output-reproducible --output-format JSON --output-file .\sbom\cyclonedx.json --validate .\.runtime\python.exe
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

$bom = Get-Content -Raw -Encoding utf8 .\sbom\cyclonedx.json | ConvertFrom-Json
if ($bom.bomFormat -ne "CycloneDX" -or $bom.specVersion -ne "1.6") {
    throw "SBOM 格式或规范版本不正确。"
}
if ($bom.metadata.component.name -ne "xianyu-shopping-assistant" -or $bom.metadata.component.version -ne "0.1.0") {
    throw "SBOM 项目根组件名称或版本不正确。"
}
$lockedComponentCount = @(
    Get-Content -Encoding utf8 .\requirements.lock |
        Where-Object { $_ -match "^[A-Za-z0-9][A-Za-z0-9._-]*==[^\s]+\s*\\$" }
).Count
if ($lockedComponentCount -eq 0 -or @($bom.components).Count -ne $lockedComponentCount) {
    throw "SBOM 组件数与哈希锁条目数不一致。"
}
$rootReference = $bom.metadata.component."bom-ref"
$rootDependency = @($bom.dependencies | Where-Object { $_.ref -eq $rootReference })
if ($rootDependency.Count -ne 1 -or @($rootDependency[0].dependsOn).Count -eq 0) {
    throw "SBOM 根组件没有唯一且非空的依赖图。"
}
Get-FileHash -LiteralPath .\sbom\cyclonedx.json -Algorithm SHA256

开发测试全部是离线测试；真实平台验收必须由用户扫码，并严格遵守 安全与覆盖边界 中的暂停规则。