vlad/reverse-skills-max
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
da24c2bd206830822af121457bf51692ef7fc3aa
reverse-skills-max/vendor-new/xbsReverseSkill/web-js-env-patcher/references/ruyi-tooling.md

28 KiB
Raw Blame History

ruyiPage / RuyiTrace 集成流程

当新 case 从一开始选择 ruyiPage / RuyiTrace 作为取证模式，或需要检测、安装、采集、导入 ruyiPage / RuyiTrace 材料时读取本文件。不要等确认目标站点存在自动化、CDP、JS Hook 或浏览器指纹检测后才使用 ruyiPage / RuyiTrace。

来源与定位

  • ruyiPage：https://github.com/LoseNine/ruyipage
    • Python Firefox 自动化框架。
    • 基于 Firefox + WebDriver BiDi，不走 CDP。
    • 支持配套 Firefox runtime、指纹浏览器、网络抓包、请求拦截、Cookie、本地存储、拟人动作等。
  • RuyiTrace / 如意 Trace：https://github.com/LoseNine/Firefox-FingerPrint-Analyzer
    • Windows x64 桌面工具，随包包含定制 Firefox trace 内核。
    • 采集 NDJSON 运行时 DOM / JS API 调用日志。
    • 探针在浏览器内核层，适合为补环境提供高保真环境访问日志。

仅在用户授权的网页端 JS 补环境、防御性分析、学术研究场景中使用。不要用这些工具绕过登录、验证码、MFA、付费墙、服务条款或业务风控。

RuyiTrace 优先诊断原则

当用户确认取证模式为 ruyiPage + RuyiTrace 时，RuyiTrace NDJSON 不是可选参考，而是补环境阶段的优先证据源：

  1. 进入 Node.js 补环境前，必须先确认是否已经采集并导入 RuyiTrace NDJSON。
  2. 如果已有 NDJSON，先运行 import_ruyitrace_log.js 生成 notes/ruyitrace-summary.md，再阅读摘要和必要的原始日志片段。
  3. 遇到 ReferenceError、TypeError、输出不一致、缺失指纹对象、静默失败、toString / descriptor / accessor / 原型链 / document.all 异常等环境问题时，先回看 NDJSON，而不是直接盲补 env.js。
  4. 优先按以下证据定位：
    • api 调用频率和类别。
    • 与目标参数生成、请求发起、writer 写入时间邻近的调用。
    • stack.file / line / col 指向的 JS 文件、模块和函数。
    • navigator / screen / document / storage / canvas / WebGL / audio / crypto / performance / worker / iframe 等环境模块分类。
  5. 只有在 NDJSON 缺失、未覆盖当前路径、日志时间段不对应、或日志结论不足时，才使用 run_with_trace.js、Proxy trace、Hook 或断点作为补充。
  6. 输出补环境计划时，必须标明哪些环境依赖来自 RuyiTrace 证据，哪些只是 Node trace / 推断，避免把推断写成事实。
  7. RuyiTrace 长字符串字段可能被截断。导入日志后，如果任意字符串字段达到或接近 4000 字符，必须标记为疑似截断：真实长度写 unknown，最小长度写可见长度，不能把 4000 或可见长度解释为加密参数或指纹值真实长度。涉及 WebAPI / 指纹具体值时，未截断 RuyiTrace 值优先；RuyiTrace 未选择、缺失、未覆盖或疑似截断时，必须使用当前用户确认的取证工具在同一 fingerprint baseline 下补采完整值，不能由 AI 猜值。

如果用户选择了 ruyiPage + RuyiTrace 但尚无日志，不能默认等待用户手动 trace。应先检测 RuyiTrace 是否已安装；检测通过后优先用 scripts/capture_ruyitrace_log.js 自动启动随 RuyiTrace 提供的 trace Firefox 捕获 NDJSON，再导入摘要。只有自动捕获失败、需要登录 / 验证 / 权限交互、目标路径未覆盖、工具不可控，或用户明确选择手动取证时，才暂停并让用户手动协助采集 / 提供 NDJSON；用户明确确认无法提供后，才降级为 ruyiPage 网络证据 + Node trace 流程。

如果用户选择了 ruyiPage + RuyiTrace 但检测到 RuyiTrace 未安装或目录不完整，不得自动改成“仅 ruyiPage”，也不要只建议“仅使用 ruyiPage”。必须先引导用户安装 / 提供 RuyiTrace 路径，或让用户明确确认降级；用户选择安装时，需要等待用户安装完成并再次验证通过后才继续任何依赖 NDJSON 的流程。

取证工具选择权必须交给用户

新网页端补环境任务开始后、任何取证动作之前，先让用户选择：

请先选择本 case 的取证模式。后续抓包、JS 收集、Hook、断点、截图、RuyiTrace 日志采集等取证操作都会沿用该模式；如果后续需要切换工具，我会再次请求确认。

1. ruyiPage + RuyiTrace（推荐）：用 ruyiPage 做 Firefox/BiDi 自动化取证，用 RuyiTrace 采集 NDJSON 环境日志辅助补环境。
2. 仅 ruyiPage：只用 ruyiPage 打开页面、抓包、收集 JS，不采集 RuyiTrace 日志。
3. CloakBrowser：沿用 Chromium/CloakBrowser 方案取证。
4. 用户手动取证：你手动提供 cURL、HAR、JS 文件、调用栈截图、RuyiTrace 日志。
5. AI 自行决定：我根据目标风险和本机工具可用性提出建议，但仍会在启动浏览器前再次确认。

请回复你选择的编号，并说明是否已经安装 ruyiPage / RuyiTrace / CloakBrowser。

用户未选择前，不要直接启动浏览器工具；用户选择后，后续所有浏览器取证动作都必须沿用该选择，不能临时 fallback 到普通 Playwright、Puppeteer 或系统 Firefox。

验证码场景的 RuyiTrace 覆盖

如果目标是验证码 / 风控验证 / challenge / WAF 接口，RuyiTrace 自动捕获或手动捕获都必须覆盖完整链路：触发验证码、验证码组件初始化、用户交互事件、加密参数生成、verify / validate / challenge 接口发起、结果回调。

  • 用户提供完整流程时，自动捕获脚本应按该流程执行；若流程需要人工识别、登录、验证码答案或权限交互，暂停让用户完成。
  • 用户选择自己完成流程时，先启动 RuyiTrace 记录，再让用户操作；只有用户回复“已经完成触发到验证流程”后，才停止记录并导入 NDJSON。
  • 如果 notes/ruyitrace-summary.md 只覆盖页面加载、没有交互事件或 verify 接口附近调用栈，应要求重新采集，不得直接进入补环境。

本机工具检测

先运行检测脚本：

node scripts/check_external_tools.js --markdown
node scripts/check_external_tools.js --json
node scripts/check_external_tools.js --python python --ruyipage-install-dir <ruyipage-browsers-dir> --markdown
node scripts/check_external_tools.js --python python --ruyipage-browser-path <firefox.exe> --markdown

强制要求：选择 ruyiPage 时，不能只检测 import ruyipage 是否成功，也不能把系统 Firefox fallback 当作可用。必须确认：

  • ruyiPage Python 包可导入。
  • Python 环境具备 requests，或已准备 smart_fingerprint(manual_geo=...) 所需地理信息；否则默认智能指纹地理探测会失败。
  • Firefox 可执行文件来自 ruyiPage managed runtime，或来自用户明确提供且可验证的 ruyiPage 定制 Firefox。
  • runtime 根目录存在 install.json。
  • install.json.release、install.json.asset 或 runtime 目录名体现 ruyi 定制标识，例如官方 manifest 当前使用的 151-ruyi。
  • install.json.executable 指向的 Firefox 文件确实存在。

如果检测结果显示“系统 Firefox fallback / 未验证路径风险”，判定 ruyiPage 绕检测方案 不通过，暂停流程并要求用户提供定制 Firefox 路径或安装目录。

如果用户已安装但脚本未检测到，要求用户提供：

  • ruyiPage：Python 解释器路径，或确认当前 python 可以 import ruyipage。
  • ruyiPage runtime：python -m ruyipage path 输出的 Firefox 路径、--ruyipage-install-dir 指向的 managed runtime 根目录，或 --ruyipage-browser-path 指向的定制 Firefox 可执行文件路径。
  • RuyiTrace：RuyiTrace.exe 所在目录，或 RuyiTrace.exe 路径；该目录中应保留 firefox/ 子目录和 firefox/RUYI_DOMTRACE.txt。
  • 日志目录：RuyiTrace 生成 NDJSON 的目录。

示例：

node scripts/check_external_tools.js --python python --ruyitrace-home <RuyiTrace-dir> --markdown
node scripts/check_external_tools.js --python python --ruyipage-browser-path <verified-ruyipage-firefox.exe> --markdown

ruyiPage + RuyiTrace 但 RuyiTrace 未安装

当本 case 的取证模式已经确认为 ruyiPage + RuyiTrace，检测脚本返回 RuyiTrace 未安装、RuyiTrace.exe 不存在、firefox/ 子目录缺失，或 firefox/RUYI_DOMTRACE.txt 缺失时，按以下强制流程处理：

  1. 不要自动降级：不得把取证模式静默切换为“仅 ruyiPage”，也不得继续进入需要 RuyiTrace NDJSON 的补环境分析。
  2. 暂停并提示用户选择：必须让用户在“安装 / 提供 RuyiTrace 路径”和“明确降级为仅 ruyiPage”之间选择。
  3. 用户选择安装 / 提供路径时：
    • 若已安装但未检测到，要求用户提供 RuyiTrace.exe 路径或所在目录。
    • 若未安装，要求用户提供下载 / 安装目录。
    • 先用 download_ruyi_tool.js --tool ruyitrace --dest <download-dir> --dry-run --markdown 输出下载计划。
    • 用户确认后才下载；下载后提示用户解压 / 安装。
    • 等用户确认 RuyiTrace.exe 可打开、firefox/ 定制内核目录存在、日志目录可选择后，再重新运行检测。
  4. 用户选择降级时：
    • 记录“取证模式已由 ruyiPage + RuyiTrace 经用户确认降级为仅 ruyiPage”。
    • 后续不得再假设存在 NDJSON。
    • 补环境阶段使用 ruyiPage 网络证据、Hook / 断点证据、Node trace / Proxy trace 作为替代来源，并在输出中标明缺少 RuyiTrace 高保真日志。

提示模板：

你选择的是 ruyiPage + RuyiTrace，但当前未检测到可用的 RuyiTrace。该模式需要 RuyiTrace NDJSON 作为补环境优先证据源。

请选择：
1. 安装 / 提供 RuyiTrace 路径：我会先输出下载 / 安装计划，并等待你确认安装完成后再继续。
2. 明确降级为“仅 ruyiPage”：后续不采集 RuyiTrace NDJSON，补环境将使用 ruyiPage 网络证据 + Hook / Node trace 作为替代。

在你确认前，我不会自动降级，也不会继续需要 RuyiTrace 日志的流程。

未安装时的安装流程

只有当用户明确说未安装，并确认允许下载 / 安装时，才进入本节。

ruyiPage

先询问用户：

未检测到 ruyiPage 定制 Firefox runtime，或当前 ruyiPage 可能会退回系统 Firefox。请确认：

1. 你是否已经提前安装好 ruyiPage 定制 Firefox？
2. 如果已经安装，请提供 ruyiPage browsers 安装目录，或提供定制 Firefox 的可执行文件路径。
3. 如果没有安装，请提供希望安装到的目录。我会先输出安装计划；你确认后再执行安装。

推荐让用户自行在 Python 环境中安装：

python -m pip install ruyiPage --upgrade
python -m pip install requests --upgrade
python -m ruyipage install --install-dir <ruyipage-browsers-dir>
python -m ruyipage doctor --install-dir <ruyipage-browsers-dir>
python -m ruyipage path --install-dir <ruyipage-browsers-dir>

如果用户需要 async 支持：

python -m pip install "ruyiPage[async]" --upgrade

也可以使用随包安装脚本输出计划或在用户确认后安装：

node scripts/install_ruyipage_runtime.js --python python --install-dir <ruyipage-browsers-dir> --markdown
node scripts/install_ruyipage_runtime.js --python python --install-dir <ruyipage-browsers-dir> --install --markdown

如果用户已自行准备 Firefox、便携版 Firefox 或 Firefox 指纹浏览器，只有在它确认为 ruyiPage 定制 Firefox 或用户明确说明是等价指纹浏览器时才可跳过 runtime 安装；普通系统 Firefox 不能作为绕自动化检测的 ruyiPage 方案。

RuyiTrace

RuyiTrace 是桌面工具。安装原则：

  1. 先让用户提供下载目录。
  2. 仅在用户确认后下载 Release 资产。
  3. 下载完成后提示用户解压 / 安装，并保持 RuyiTrace.exe 与 firefox/ 子目录在同一目录。
  4. 等用户确认 RuyiTrace.exe 可以打开且“定制内核”状态正常后，再继续。

可用脚本查看下载计划或下载：

node scripts/download_ruyi_tool.js --tool ruyitrace --dest <download-dir> --dry-run --markdown
node scripts/download_ruyi_tool.js --tool ruyitrace --dest <download-dir> --markdown

如只需要 ruyiPage 配套 Firefox runtime，优先使用 python -m ruyipage install；需要离线下载时再使用：

node scripts/download_ruyi_tool.js --tool ruyipage-firefox --dest <download-dir> --dry-run --markdown

下载脚本只负责下载，不默认解压、安装或启动桌面程序。

ruyiPage 取证流程

用户选择 ruyiPage 后：

  1. 检查 ruyiPage 包、requests 依赖和 Firefox runtime，并确认 runtime 是 ruyiPage 定制 Firefox。
    • 如果只检测到系统 Firefox fallback，立即暂停，不启动浏览器。
    • 如果已找到定制 Firefox 但不是默认解析路径，启动时必须显式指定 browser_path / set_browser_path。
    • 如果缺少 requests，必须安装依赖或让用户提供 manual_geo；不要静默跳过智能指纹。
  2. 按“ruyiPage 启动硬约束”启动；任一硬约束失败时，停止并报告，不要继续取证。
  3. 确认是否需要登录；需要登录时让用户手动完成。
  4. 使用有头模式打开页面。
  5. 触发最少量必要业务动作。
  6. 收集：
    • Network / cURL / HAR。
    • JS bundle / chunk / sourcemap URL。
    • Cookie、本地存储键名、请求头、响应状态。
    • source / entry / builder / writer 链路证据。
  7. 单个取证动作完成并沉淀必要结论后，立即清理临时截图、失败下载、临时日志和无登录态 profile；登录态 profile 单独询问用户是否保留。

ruyiPage 启动硬约束

不要把“能启动浏览器”当作 ruyiPage 取证成功。每次 ruyiPage 取证都必须从一开始满足以下约束：

约束 要求
定制内核 必须显式使用已验证的 ruyiPage 定制 Firefox runtime；不得使用系统 Firefox fallback
有头模式 必须 headless(False) 或等价有头模式；不要用 headless 做高风控取证
独立 Profile 使用本 case 专用临时 user_dir / profile，不复用脏 profile
智能指纹 默认调用 opts.smart_fingerprint(require_country=None, base_dir=..., userdir=...)；如果地理探测失败，要求安装 requests 或提供 manual_geo，不要静默跳过
仿真注入 如果 smart_fingerprint() 返回 ctx，创建页面后必须执行 ctx.apply_emulation(page)
指纹一致性 第一次成功取证后写入 case/notes/fingerprint-baseline.json 和 baselineId；geolocation、timezone、locale、viewport、UA、Client Hints、screen、WebGL 与 smart_fingerprint 输出和出口 IP 保持一致；后续复用同一 base_dir / userdir，不要每次随机新指纹
拟人动作 设置 set_human_algorithm("windmouse") 或 "bezier"，优先使用拟人滚动 / 点击触发业务动作
取证时机 page.capture.start(...) 必须在 page.get(...) 之前执行
自检 导航后检查 navigator.webdriver，期望为 false；若为 true，判定当前取证不合格
验收 目标接口必须捕获到非失败响应；对跨域接口不要把单独的 OPTIONS preflight 当作业务取证成功
isTrusted 点击、拖拽、鼠标、键盘、滚动优先使用原生 BiDi / human actions；确需 JS 构造事件时必须带 ruyi: true；普通 dispatchEvent 不视为可信输入

这些约束只能降低普通自动化 / CDP / 指纹检测风险，不能保证绕过所有业务风控、登录、验证码、MFA、设备验证或服务端策略。

ruyiPage / RuyiTrace 指纹基线固定

  • ruyiPage 第一次成功取证后，把 smart_fingerprint 输出、profile / userdir、UA、Client Hints、locale、timezone、viewport、screen、WebGL 等写入 case/notes/fingerprint-baseline.json。
  • RuyiTrace 自动捕获或手动采集前先确认使用同一 case profile / baseline；如果 RuyiTrace 定制内核不能复用同一 profile，必须采样核心字段并写入 case/notes/fingerprint-baseline-diff.md，不一致时暂停。
  • 后续 Hook、截图、网络抓包、指纹 fixture 采样必须带同一 baselineId；缺少 baselineId 时不得把样本用于最终 env。
  • 如果用户更换代理、地区、语言、profile 或工具，生成新的 baseline，旧样本不能和新样本混用。

ruyiPage isTrusted 交互规则

高风控点击、拖拽、键盘输入、滚动和验证码交互优先使用 ruyiPage 原生 BiDi / human actions：

page.actions.move_to(page.ele("#btn")).click().perform()
page.actions.drag(page.ele("#source"), page.ele("#target"), duration=640, steps=16).perform()
page.actions.release()
page.actions.human_move(ele, algorithm="windmouse").perform()
page.actions.human_click(ele, algorithm="windmouse").perform()

如果必须构造 JS 事件，只允许使用 ruyiPage 的 ruyi: true 特定能力，并在取证报告中说明事件类型和参数：

new MouseEvent('click', { bubbles: true, clientX: 12, clientY: 24, ruyi: true });
new KeyboardEvent('keydown', { bubbles: true, key: 'Enter', code: 'Enter', ruyi: true });
new PointerEvent('pointerdown', { bubbles: true, pointerId: 1, clientX: 3, clientY: 5, ruyi: true });

普通 dispatchEvent(new MouseEvent(...))、new KeyboardEvent(...) 不得作为验证码或高风控交互主路径。无法保证可信输入时，暂停并让用户手动完成或切换工具。

示例骨架：

from ruyipage import FirefoxOptions, FirefoxPage

opts = FirefoxOptions()
opts.set_browser_path("<verified-ruyipage-managed-firefox>")
opts.set_user_dir("<case-browser-profile>")
opts.headless(False)
opts.set_window_size(1366, 900)
opts.set_human_algorithm("windmouse")

ctx = opts.smart_fingerprint(
    require_country=None,
    # 同一 case 固定该目录，避免每次随机生成不同指纹。
    base_dir="<case-tmp-fingerprint-dir>",
    # 同一 case 固定该 profile，后续 RuyiTrace / Hook / 指纹采样复用同一基线。
    userdir="<case-browser-profile>",
)

page = FirefoxPage(opts)
ctx.apply_emulation(page)
page.capture.start(targets="<target-api-keyword>", collect_bodies=True)
page.get("<target-page-url>")
assert page.run_js("return navigator.webdriver") is False
packets = page.capture.wait(timeout=30, count=1)

只有当 node scripts/check_external_tools.js --markdown 显示“默认解析路径是否为定制 Firefox：是”时，才可直接 FirefoxPage() 或 launch(headless=False)。否则必须显式指定已验证的定制 Firefox 路径。

ruyiPage 取证验收标准

  • JD pc_home_feed 类接口：至少捕获到 URL 包含 pc_home_feed 的 2xx 响应，并能看到请求 URL 中的加密 / 风控参数，例如 h5st。
  • 美团外卖 shopList 类跨域接口：必须区分 OPTIONS preflight 与真实业务请求；只有捕获到非 OPTIONS 的 2xx shopList 响应，才算取证成功。若返回登录 / Yoda / 401 风控信息，应按“需要登录 / 风控验证”流程暂停，不要宣称已绕过。

RuyiTrace 日志采集流程

用户选择 RuyiTrace 后，采集策略是 自动捕获优先，手动采集兜底。

自动捕获优先

检测到 RuyiTrace.exe、firefox/ 子目录、firefox/firefox.exe 和 firefox/RUYI_DOMTRACE.txt 完整后，不要默认让用户手动打开 GUI。优先使用随包脚本自动启动 RuyiTrace 的 trace Firefox，并通过 MOZ_DOM_TRACE 环境变量写出 NDJSON：

node scripts/capture_ruyitrace_log.js --url <target-page-url> --case-dir case --ruyitrace-home <RuyiTrace-dir> --dry-run --markdown
node scripts/capture_ruyitrace_log.js --url <target-page-url> --case-dir case --ruyitrace-home <RuyiTrace-dir> --duration 90 --import-after --markdown

执行要求：

  1. 自动创建或使用 case/ruyi-trace/logs/ 作为日志目录，使用 case/tmp/ruyitrace-profile/ 或用户确认的临时 Profile。
  2. 使用 RuyiTrace 随包 trace Firefox，而不是普通系统 Firefox、普通 Playwright、Puppeteer 或 ruyiPage 的 Firefox runtime。
  3. 设置 MOZ_DOM_TRACE=1、MOZ_DOM_TRACE_FILE=<case trace file>、MOZ_DOM_TRACE_LIMIT=<limit> 和 MOZ_DISABLE_LAUNCHER_PROCESS=1。
  4. 打开目标页面后触发最少量必要业务动作；如果需要登录、验证码、MFA、设备验证或权限确认，暂停让用户在该 trace Firefox 中手动完成，再继续采集。
  5. 自动捕获结束后，立即运行 import_ruyitrace_log.js 导入日志、生成 notes/ruyitrace-summary.md，并检查长字段截断风险。
  6. 如果自动捕获没有生成 NDJSON，先记录失败原因和已执行命令，再进入手动兜底；不要把“没有日志”误写成目标没有环境访问。

自动捕获成功后继续：

node scripts/import_ruyitrace_log.js --input <trace.ndjson> --case-dir case --truncation-threshold 3900 --markdown

手动采集兜底

只有在以下情况才要求用户手动采集：

  • 自动捕获启动失败或 RuyiTrace trace Firefox 无法写日志。
  • 目标必须由用户登录、验证、MFA、设备确认或完成复杂交互。
  • 用户明确要求使用 RuyiTrace GUI。
  • 自动采集的日志未覆盖目标参数生成路径，需要用户按指定动作重新采集。

手动流程：

  1. 打开 RuyiTrace.exe。
  2. 填写启动页面。
  3. 选择日志目录，建议选择当前 case 的 ruyi-trace/logs/ 或用户指定目录。
  4. 点击“开始采集”。
  5. 在浏览器中正常浏览并触发目标指纹 / 加密参数生成逻辑。
  6. 点击“停止采集”。
  7. 找到 trace_<时间戳>_<PID>.ndjson。
  8. 使用脚本复制到 case 并生成摘要：
node scripts/import_ruyitrace_log.js --input <trace.ndjson> --case-dir case --markdown
node scripts/import_ruyitrace_log.js --input <trace.ndjson> --case-dir case --truncation-threshold 3900 --markdown

高级手动启动方式仅在用户理解环境变量时使用：

set MOZ_DOM_TRACE=1
set MOZ_DOM_TRACE_FILE=<trace-output.ndjson>
set MOZ_DOM_TRACE_LIMIT=<max-lines>
set MOZ_DISABLE_LAUNCHER_PROCESS=1
<ruyitrace-firefox.exe> -no-remote -new-instance <target-page-url>

可选环境变量：

变量 用途
MOZ_DOM_TRACE=1 开启 trace
MOZ_DOM_TRACE_FILE=<path> 输出路径，PID 自动追加
MOZ_DOM_TRACE_LIMIT=<n> 单进程行数上限
MOZ_DOM_TRACE_PTYPE=<list> 启用 trace 的进程类型
MOZ_DISABLE_LAUNCHER_PROCESS=1 Windows 下避免 launcher 提前退出

RuyiTrace 长字段截断保护

RuyiTrace NDJSON 适合作为高保真环境访问日志，但长字符串字段可能因工具显示或记录限制被截断。典型风险是某个加密参数、长 token、长 Cookie、请求 body、dataURL 或大型对象序列化值真实长度为数万字符，但日志中只保留约 4000 字符。

硬性规则：

  • 导入 NDJSON 时必须运行带截断检测的脚本，默认阈值为 3900：
node scripts/import_ruyitrace_log.js --input <trace.ndjson> --case-dir case --truncation-threshold 3900 --markdown
  • 任何字符串字段长度达到或接近阈值时，统一标记：
    • truncationSuspected: true
    • visibleLength: <日志中可见长度>
    • minLength: <日志中可见长度>
    • actualLength: unknown
  • 不得写“该加密参数长度为 4000”。只能写“RuyiTrace 可见长度为 4000，疑似被截断，真实长度未知，至少 4000”。
  • 不得把 RuyiTrace 中的长字段可见值直接作为 fixture 期望值或最终参数值。
  • 如果该字段影响签名、指纹回放或最终请求验证，必须从以下来源补采完整值：
    1. HAR / cURL / Network 完整请求。
    2. ruyiPage collect_bodies=True 网络抓包。
    3. 专用 Hook 对 writer 或加密入口做分片落盘，并记录完整长度、SHA256、前后片段。
    4. 最终 Node.js signer 输出，并与浏览器样本的完整长度或 hash 对比。
  • 写入 notes/missing-env-priority.md、阶段报告或最终总结时，必须区分“RuyiTrace 未截断可用值”“RuyiTrace 可见但疑似截断值”和“其他来源补采完整值”。
  • 对 Canvas / WebGL / WebGPU / Audio / 字体 / DOM 几何、navigator、screen、window、document 等具体值：RuyiTrace 未截断值是优先来源；只要日志缺失、未覆盖或疑似截断，就改用已确认的 ruyiPage / Camoufox / CloakBrowser / 手动浏览器采样，并记录 baselineId、capturedBy、完整长度和 hash。不得把 AI 猜值、静态推断或 Node.js 模拟库结果写入最终 fixture。

摘要中出现 ## 长字段截断风险 时，后续分析要先处理完整值补采问题，再判断参数长度、结构、hash、编码或是否可复现。

如果截断字段是指纹 / WebAPI 返回值，例如 dataURL、WebGL 参数、字体探测结果、DOM 序列化结果或 Audio buffer 摘要，不得把 trace 可见片段直接写入 fingerprint.fixture.json 的最终 result；必须使用同一 case 已确认取证工具补采完整值，或显式阻塞等待用户提供完整真实浏览器材料。

根据 RuyiTrace 日志补环境

日志导入后按以下顺序分析。选择 ruyiPage + RuyiTrace 的 case，必须先完成本节，再进入 Node.js 缺失环境追踪：

  1. 统计 api 调用频率，优先处理高频或和目标参数生成邻近的 API。
  2. 按 stack.file / line / col 聚合，定位具体 JS 文件和函数。
  3. 分类到环境模块：
    • Navigator / Screen / Location / Storage。
    • Canvas / WebGL / Audio / WebRTC。
    • Crypto / Performance / Date / Random。
    • DOM / Element / CSS / Layout。
    • Worker / Service Worker / iframe。
  4. 将日志结论写入：
    • notes/ruyitrace-summary.md
    • notes/missing-env-priority.md：必须包含命中的 api、stack.file、line、col、环境模块分类、补齐优先级，以及“RuyiTrace 证据 / Node trace 补充 / 推断”标记。
    • notes/entry-chain.md
  5. 再进入 Node.js 缺失环境追踪和 fixtures 验证。

遇到环境错误时的处理顺序：

  1. 先在 notes/ruyitrace-summary.md 中搜索缺失对象、方法或相关模块，例如 navigator、document.cookie、localStorage、canvas、WebGL、performance。
  2. 摘要不足时，在原始 case/ruyi-trace/logs/*.ndjson 中按目标 JS 文件名、目标 API 关键词、调用栈行列号或时间窗口过滤。
  3. 将命中的 api、stack.file、line、col、参数摘要写入 notes/missing-env-priority.md。
  4. 再用 Node trace 复现缺失路径，确认哪些对象需要在 env.js 中固化；固化时要同时处理属性描述符、访问器、原型链、函数 / 访问器 / 实例对象 toString 保护。
  5. 如果 RuyiTrace 没有相关证据，明确标记“RuyiTrace 未覆盖”，再使用 Proxy trace / Hook / 断点继续排查。
  6. 交付前运行 node scripts/check_env_realism.js --case-dir case --require-ruyitrace --markdown；涉及 document.all 时加 --require-document-all。

日志可能很大。大文件处理原则：

  • 不把完整日志直接写入最终报告。
  • 先导入并生成摘要。
  • 必要时按行分块，优先分析和目标 API / 参数生成时间段相关的片段。
  • 原始日志保存在 case 内，任务结束前询问是否保留。