闲鱼 Codex 自动研究与组合采购助手

xianyu-shopping-assistant 是一个默认面向个人只读场景设计的 Codex 插件。你可以在一次 Codex 对话中描述硬件采购需求；Skill 会区分自然语言和显式搜索词，用最多三次第一页预览校准关键词，再由按需 companion 通过专用可见 Chrome 采集当前账号可发现的闲鱼网页结果。Codex 最终比较的是满足目标数量、兼容性和真实总价闭包的完整购买方案，而不是孤立商品或页面最低标价。

v0.2 的结构化组合采购模型覆盖内存、存储和网卡，首个完整验收场景是笔记本内存 16GB × 2。旧任务和原有 MCP 参数保持可读、可恢复，但不会自动把 v0.1 非终态任务升级为组合采购任务。

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

系统要求

• 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. 发送明确的购买需求。首次组合采购测试可直接使用下面的提示词：

   我的设备是华硕天选 FA506IV。我确认要购买两根 16GB DDR4-3200 SO-DIMM、1.2V、Non-ECC 笔记本内存，总计 32GB。请先校准闲鱼关键词，再在真实两根总价、完整料号、兼容性和卖家风险都可核验时推荐 0 至 3 个完整购买方案；1Rx8/2Rx8 优先，2Rx8 只在价格接近时加分。

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

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

5. 登录成功后，插件保存经当前 Windows 用户 DPAPI 加密的专用登录态。Codex 先调用 xianyu_preview_research，每个候选词只访问第一页：最多自动修正两次、总预览最多三次。通过校准的第一页直接复用为正式任务第一页，不产生重复导航；未通过时会停止并询问，不会让错误词继续翻页。

6. 正式任务启动后，按需 companion 独立于 MCP stdio 继续采集。当前对话只保留一个与 job_id 绑定的 heartbeat：活跃采集通常约 10 分钟后检查，waiting_budget 直接等到 resume_at，终态或暂停后自动删除。原始关键词第一页仍可显示一次只读“首屏市场快照”；详情达到严格的 8/10 门槛后可显示一次暂定条件建议，正式结论仍需等待完整候选和购买方案闭包。大数据集可能需要数小时或跨天完成。

后台 Companion 与自动回话

companion 是当前 Windows 用户按需启动的单实例进程，通过仅限当前用户访问并带 DPAPI 认证材料的 Named Pipe 接受 MCP 请求。它独占 SQLite 平台 worker、预算恢复和唯一一套系统有头 Chrome；MCP stdio 断开或当前 Codex 回合结束不会停止非终态研究。它不是 Windows 服务，不注册开机启动，不驻留托盘，也不使用 Codex 内置浏览器。

• 电脑和 Codex 应保持运行。电脑睡眠期间采集和 heartbeat 都会延迟，唤醒后按 UTC 截止时间继续；系统重启后由下一次 Codex heartbeat 或工具调用重新启动 companion 并从 SQLite 检查点恢复。

• 同一 job_id 只能有一个绑定原对话的 heartbeat。活跃状态约 10 分钟后检查；预算等待不固定高频轮询，而是安排到 resume_at 与服务端 next_effective_check_at 中较晚的时间。

• companion 在 waiting_budget 时保留任务但关闭 Chrome；需要下一次平台导航时才重新打开同一专用可见 Chrome。采集期间 Chrome 窗口出现是正常行为，但同一时间不应出现双 worker 或双 Chrome。

• Codex 应用未运行时，heartbeat 无法自动回到原对话；恢复应用后才会继续检查。电脑保持唤醒时，已经启动的 companion 仍可继续当前后台采集。系统重启不会自行启动 companion。

• 没有非终态任务且无客户端 10 分钟后，companion 自动退出。删除 heartbeat 不等于取消研究；只有用户明确要求时才会调用取消工具。

已经落盘的检查点不会丢失；新建 Codex 任务后可以要求“继续已有的闲鱼研究任务”。若不知道 job_id，Codex 会从本地任务列表第一页开始以每页 50 条读到末页，拒绝缺失或重复游标，并在全部分页结果中按完整研究请求精确匹配，再用进度中的请求指纹确认原任务；不会只凭关键词猜测，也不会命中一条就提前停止。若中断发生在搜索翻页中，新进程会从第一页开始逐页重新导航，并用已保存的游标、内容指纹和页码证据校验连续性；每个校验页都会消耗一次搜索预算，但不会重复累计页面或商品。任一旧页已经漂移时，该关键词会停止并报告部分覆盖，不会直接跳到未知页。

关键词校准与组合采购

自然语言需求会原样保存为 request_text，不会直接拿整句话搜索。只有你明确说“关键词是 X”或“就搜 X”时，第一次预览才逐字使用该显式关键词。每轮预览只读第一页，并由服务端根据强相关、冲突品类和样本量判定；例如 16X2 若主要召回台式机内存会被拒绝，Codex 可改为 DDR4 3200 16G 笔记本内存。最多两个通过校准的词进入正式任务。

设备档案只保存你明确确认的事实。FA506IV 内存目标应形成 target_quantity=2，以及 DDR4、SO-DIMM、单条 16GB、JEDEC 3200 MT/s、1.2V、Non-ECC 等硬条件。x8 是性能偏好；2R 只能在有限价差内弱加分，不能为了 Rank 排除其他兼容方案。

组合引擎按以下优先级生成完整购买方案：明确套条、同一商品拍两件、同一卖家的两条同料号商品、跨卖家同料号组合。跨卖家组合始终是低优先级条件备选。每个方案都必须核对页面标价含义、包含数量、购买数量、运费、加价、可用数量、完整料号和兼容证据。

只有 status=complete、compatibility_status=pass、目标数量闭包、完整料号与配对证据充分，并且 total_price_min/total_price_max 都可确定的方案才会直接推荐。页面最低单条价不能当成两条总价；随机发货、未知价格口径、缺少标签或料号、兼容性未知和数量不足只能成为条件备选。完整方案不足时会推荐少于 3 个或 0 个；有可靠全新价格证据且二手没有合理优势时，可以明确“建议购买全新”，不会强行凑闲鱼商品。

采集使用两阶段漏斗。第一阶段完整保存当前账号可发现列表的标题/富标题、价格、地区、缩略图和有界短说明；所有结果仍留在 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 只更新同一个 heartbeat，让 companion 继续长尾详情。默认 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、缓存状态、请求指纹、平台导航计数和覆盖结论。每个推荐还要列出方案类型、组成商品与数量、页面价格口径、真实总价区间、配对依据、兼容性矩阵、卖家风险和核实话术。公开信用缺失或来源冲突不能当作合格；任一组成商品刷新为不可用时方案必须移除或降级，状态未知只能作为待人工确认的条件备选。证据不足时，合理结果可能是少于 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.2.1") {
    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

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