dsh-js-reverse-plugin 0.1.0

package/skills/iv8-env-runtime/scripts/defaults_audit.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""defaults_audit.py —— P2/P3 桥梁：审计 iv8 的 environment/config 默认值，算出「真正要配的清单」。
+
+作用（对应 SKILL.md 的 P2「monitor∩defaults 交集=要配的清单」）：
+    调 iv8.JSContext.get_defaults()（返回全部支持路径及默认值），做两件事：
+      1) 按前缀分组（location / canvas / navigator / screen / webgl / window / document …）
+         打印，并「标出空/占位默认」（''、about:blank、0.0 等）——这些是最可能需要覆盖的必配候选。
+      2) 若给了「目标读过的字段清单」（monitor_env.py 第①类 getter 的输出），
+         与 defaults 求交集 = 目标真正读到、且 iv8 有默认可覆盖的字段 = 真正要配的清单。
+
+    典型默认坑（务必核对，见 references/config-defaults-cheatsheet.md）：
+      - location.href 默认 'about:blank' —— 几乎必配（目标常读 origin/host/href 做校验）
+      - canvas.fingerprint.toDataURL.png 默认 '' —— canvas 指纹站必配
+      - navigator.* 已有 200+ 默认 —— 通常只需覆盖 userAgent（及联动字段）
+
+    environment（画像，JS 可观测，可含数组）与 config（引擎行为，仅标量，无数组）是两条独立通道；
+    本审计只帮定位「哪些默认是空壳需要填」，具体填什么值 / 一致性红线（UA↔platform↔时区↔语言↔webgl）
+    见 references/config-defaults-cheatsheet.md 与 references/patching-principles.md。
+
+关系与边界：
+    - 上游：scripts/monitor_env.py 的①类 getter 清单是本脚本 --read-fields 的输入。
+    - 下游：交集清单 → 填进 assets/env_starter.py 的 environment/config。
+    - 一致性静态校验（填错值自动拒）见 scripts/consistency_lint.py。
+    - 权威 API 契约见 references/iv8-api-contract.md。
+
+用法：
+    python defaults_audit.py                         # 全量分组 + 标空默认
+    python defaults_audit.py --group navigator       # 只看某前缀
+    python defaults_audit.py --empty-only            # 只列空/占位默认（必配候选）
+    python defaults_audit.py --read-fields fields.txt  # 与目标读过的字段求交集
+        fields.txt：每行一个字段路径，如 navigator.userAgent / location.href
+        （可直接从 monitor_env.py 第①类输出里摘）
+"""
+
+import argparse
+import sys
+
+try:
+    import iv8
+except ImportError:
+    sys.exit("未找到 iv8。先跑 scripts/preflight.py 确认安装（安装见 references/cross-platform-install.md）。")
+
+
+# 视为「空/占位」的默认值 —— 命中即列为必配候选
+_EMPTY_LITERALS = ("", "about:blank", "about://blank")
+
+
+def is_empty_default(value):
+    """判断一个默认值是否为空/占位（很可能需要覆盖）。"""
+    if value is None:
+        return True
+    if isinstance(value, str):
+        return value.strip() in _EMPTY_LITERALS
+    return False
+
+
+def group_of(path):
+    """取路径的一级前缀作为分组名。"""
+    return path.split(".", 1)[0] if "." in path else path
+
+
+def load_read_fields(path):
+    """读取目标读过的字段清单（每行一个路径，# 起始为注释）。"""
+    fields = set()
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            s = line.strip()
+            if not s or s.startswith("#"):
+                continue
+            # 容忍 monitor 输出里带计数前缀，如 "   42  navigator.userAgent"
+            token = s.split()[-1]
+            fields.add(token)
+    return fields
+
+
+def main():
+    ap = argparse.ArgumentParser(description="审计 iv8 默认值，定位必配候选 / 与目标读过字段求交集")
+    ap.add_argument("--group", default="", help="只显示该一级前缀（如 navigator / webgl）")
+    ap.add_argument("--empty-only", action="store_true", help="只列空/占位默认（必配候选）")
+    ap.add_argument("--read-fields", default="", help="目标读过的字段清单文件，求交集")
+    args = ap.parse_args()
+
+    defaults = iv8.JSContext.get_defaults()
+    print(f"iv8 get_defaults(): 共 {len(defaults)} 条支持路径\n")
+
+    # ---- 分组 ----
+    groups = {}
+    for path in sorted(defaults):
+        groups.setdefault(group_of(path), []).append(path)
+
+    def emit(path):
+        val = defaults[path]
+        flag = "  ⚠必配候选(空/占位)" if is_empty_default(val) else ""
+        print(f"    {path} = {val!r}{flag}")
+
+    for gname in sorted(groups):
+        if args.group and gname != args.group:
+            continue
+        rows = groups[gname]
+        if args.empty_only:
+            rows = [p for p in rows if is_empty_default(defaults[p])]
+            if not rows:
+                continue
+        print(f"[{gname}]  ({len(rows)} 条)")
+        for path in rows:
+            emit(path)
+        print()
+
+    # ---- 与目标读过的字段求交集 ----
+    if args.read_fields:
+        read = load_read_fields(args.read_fields)
+        default_paths = set(defaults)
+        # 直接命中 + 前缀命中（目标读 navigator.userAgent，defaults 有该路径）
+        hit = sorted(read & default_paths)
+        # 目标读了但 defaults 里没有的路径 → 可能是缺失 API / 陷阱，走 trap 纪律
+        miss = sorted(read - default_paths)
+
+        print("=" * 72)
+        print("交集（monitor∩defaults）= 目标读到且 iv8 有默认可覆盖 = 真正要配的清单")
+        print("=" * 72)
+        for path in hit:
+            emit(path)
+        if not hit:
+            print("    （无交集：目标读的字段都不在 defaults 里，见下方 miss）")
+
+        if miss:
+            print("\n" + "-" * 72)
+            print("⚠ 目标读了、但 defaults 无此路径 —— 可能是缺失 API / 反爬陷阱：")
+            print("  默认按陷阱处理，除非真机核对确有值。见 references/trap-blacklist.md")
+            print("-" * 72)
+            for path in miss:
+                print(f"    {path}")
+
+    print(
+        "\n[下一步] 交集清单填进 assets/env_starter.py 的 environment/config；\n"
+        "        填的值做一致性静态校验 → scripts/consistency_lint.py；\n"
+        "        值怎么填 / 一致性红线见 references/config-defaults-cheatsheet.md。"
+    )
+
+
+if __name__ == "__main__":
+    main()

package/skills/iv8-env-runtime/scripts/monitor_env.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""monitor_env.py —— P2 发现阶段核心工具：跑一遍目标 JS，抓 iv8 C++ 层监控日志分六类。
+
+作用（对应 SKILL.md 的 P2「起手跑 + 发现缺口」）：
+    用 iv8 mode='debug' 加载目标 JS 并触发一次签名/取数，把引擎在 C++ 层记录的
+    「浏览器 API 访问链路 + JS 内置反射路径」实时打到 stdout(fd1)/stderr(fd2)，
+    本脚本用 fd 重定向把它落盘再正则解析，按六类打印：
+        ① 属性读 getter   —— 目标读了哪些指纹字段（配 environment 的清单来源）
+        ② 属性写 setter   —— 目标改/挂了什么（常见是 XHR.open / fetch 的 hook）
+        ③ 方法调用 call
+        ④ 存在性探测 query（typeof / in，反爬最爱）
+        ⑤ 反射层 —— Object.keys / getOwnPropertyDescriptor / toString / JSON.* 等探测
+        ⑥ ⚠ 疑似缺失 API —— 目标摸了但 iv8 未实现（单列，见下方处置纪律）
+
+第⑥类「疑似缺失 API」的处置纪律（贯穿本 skill 的三态原则）：
+    默认按「陷阱」处理 —— 绝不无脑补。process / _phantom / __webdriver_script_fn /
+    StyleMedia / Float16Array 之类是反爬故意探测的不存在物，补了反而暴露。
+    只有在真机（真实 Chrome）核对确认「真实浏览器里此 API 确有值」时，才配置/补它。
+    详见 references/trap-blacklist.md 与 references/patching-principles.md。
+
+关系与边界：
+    - 本脚本只做「发现」：告诉你目标读了什么、探测了什么、摸了哪些缺失物。
+    - 「读了什么」→ 拿去 environment 配值，交集算法见 scripts/defaults_audit.py。
+    - 抛 TypeError 的 stub 窟窿（如 MessageChannel port=null）→ scripts/reproduce_stub_error.py。
+    - stub 替换按 references/patching-principles.md 的 iv8 原生补丁契约执行。
+    - 权威 API 契约见 references/iv8-api-contract.md；坑位版本门控见 references/version-gotchas.md。
+
+用法：
+    python monitor_env.py <目标JS路径> [--url <触发URL>] [--trigger <触发JS表达式文件>]
+                          [--env <environment JSON文件>] [--log <日志落盘路径>]
+
+    最小用法（零配跑，观察默认环境下都缺什么）：
+        python monitor_env.py ./target.js
+    带触发（脚本加载后还需调一次才产签名）：
+        python monitor_env.py ./target.js --trigger ./trigger.js
+    trigger.js 内是一段 JS（示例）：
+        var x = new XMLHttpRequest(); x.open('GET','https://api.example.com/d'); x.send();
+        window.__iv8__.eventLoop.drain(); window.__iv8__.netLog.entries;
+
+注意：社区版无真实网络栈，--url 只用于把 URL 拼进默认触发表达式；真请求/响应注入见
+      scripts/network_bridge.py 与 references/network-and-eventloop.md。
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from collections import Counter
+
+try:
+    import iv8
+except ImportError:
+    sys.exit("未找到 iv8。先跑 scripts/preflight.py 确认安装（安装见 references/cross-platform-install.md）。")
+
+
+# ---- 日志正则：匹配 iv8 debug 模式在 C++ 层打印的监控行 ----
+ANSI = re.compile(r"\x1b\[[0-9;]*m")
+RE_INST = re.compile(r"实例访问 - (.+?) -> (getter|setter|call|query)")
+RE_REFL = re.compile(r"反射层 - (.+?) - 目标：([^\[\-]+)")
+RE_MISS = re.compile(r"疑似缺失API - (\S+)")
+
+
+def build_default_trigger(url):
+    """没给 --trigger 时的兜底触发：发一次 XHR + drain + 读 netLog。
+
+    drain 是「drain-before-read」纪律：社区版异步 XHR 回调不排空就读不到结果。
+    完整事件循环推进语义见 references/network-and-eventloop.md。
+    """
+    if not url:
+        # 纯加载即产签名的目标：不触发，只 drain 一轮微任务
+        return "window.__iv8__.eventLoop.drain();"
+    safe_url = json.dumps(url)
+    return (
+        "var __x = new XMLHttpRequest();"
+        "__x.open('GET', %s, true);"
+        "try { __x.send(null); } catch (e) {}"
+        "window.__iv8__.eventLoop.drain();"
+        "window.__iv8__.netLog.entries;" % safe_url
+    )
+
+
+def run_and_capture(js_path, trigger_src, env, log_path):
+    """在 debug 模式下加载目标并触发一次，把 C++ 监控日志重定向到 log_path。"""
+    with open(js_path, "r", encoding="utf-8") as f:
+        js = f.read()
+
+    # fd1 + fd2 重定向到文件，捕获引擎层 debug 输出（Python print 也会进同一文件）
+    saved_out, saved_err = os.dup(1), os.dup(2)
+    fd = os.open(log_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+    os.dup2(fd, 1)
+    os.dup2(fd, 2)
+    os.close(fd)
+    try:
+        # mode='debug' 打开 API 监控；environment 只放 JS 可观测画像（可含数组）
+        with iv8.JSContext(environment=env, mode="debug") as ctx:
+            ctx.eval(js, name=os.path.basename(js_path))
+            if trigger_src:
+                ctx.eval(trigger_src, name="__trigger__")
+    finally:
+        os.dup2(saved_out, 1)
+        os.dup2(saved_err, 2)
+        os.close(saved_out)
+        os.close(saved_err)
+
+
+def parse_log(log_path):
+    """解析监控日志，返回六个 Counter。"""
+    reads, writes, calls, queries, refl, missing = (Counter() for _ in range(6))
+    total = 0
+    with open(log_path, "r", encoding="utf-8", errors="replace") as fh:
+        for raw in fh:
+            line = ANSI.sub("", raw)
+            total += 1
+            m = RE_INST.search(line)
+            if m:
+                api, kind = m.group(1).strip(), m.group(2)
+                if "__iv8__" in api:  # 工具对象自身不算目标行为
+                    continue
+                {"getter": reads, "setter": writes,
+                 "call": calls, "query": queries}[kind][api] += 1
+                continue
+            m = RE_REFL.search(line)
+            if m:
+                refl[f"{m.group(1).strip()} → {m.group(2).strip()}"] += 1
+                continue
+            m = RE_MISS.search(line)
+            if m:
+                missing[m.group(1)] += 1
+    return total, reads, writes, calls, queries, refl, missing
+
+
+def show(title, counter, top):
+    print(f"\n{'=' * 72}\n{title}\n  去重 {len(counter)} / 命中 {sum(counter.values())}\n{'=' * 72}")
+    for k, v in counter.most_common(top):
+        print(f"  {v:6d}  {k}")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="iv8 debug 监控：跑目标 JS，六类打印 API 访问链路")
+    ap.add_argument("js_path", help="目标 JS 文件路径")
+    ap.add_argument("--url", default="", help="触发用 URL（拼进默认 XHR 触发表达式）")
+    ap.add_argument("--trigger", default="", help="触发 JS 表达式文件路径（覆盖默认触发）")
+    ap.add_argument("--env", default="", help="environment 画像 JSON 文件路径（省略=零配跑）")
+    ap.add_argument("--log", default="", help="监控日志落盘路径（默认 <js>.monitor.log）")
+    args = ap.parse_args()
+
+    if not os.path.isfile(args.js_path):
+        sys.exit(f"目标 JS 不存在: {args.js_path}")
+
+    env = None
+    if args.env:
+        with open(args.env, "r", encoding="utf-8") as f:
+            env = json.load(f)
+
+    if args.trigger:
+        with open(args.trigger, "r", encoding="utf-8") as f:
+            trigger_src = f.read()
+    else:
+        trigger_src = build_default_trigger(args.url)
+
+    log_path = args.log or (args.js_path + ".monitor.log")
+
+    run_and_capture(args.js_path, trigger_src, env, log_path)
+    total, reads, writes, calls, queries, refl, missing = parse_log(log_path)
+
+    print(f"\n日志总行数: {total}  (原始: {log_path})")
+    show("① 属性读 getter —— 目标读了哪些字段（→ environment 配值清单来源）", reads, 60)
+    show("② 属性写 setter —— 目标改/挂了什么（常见 XHR.open / fetch hook）", writes, 30)
+    show("③ 方法调用 call —— 目标调了哪些 API", calls, 40)
+    show("④ 存在性探测 query（typeof / in，反爬最爱）", queries, 40)
+    show("⑤ 反射层 —— Object.keys / getOwnPropertyDescriptor / toString / JSON.*", refl, 30)
+    show("⑥ ⚠ 疑似缺失 API（目标摸了但 iv8 未实现）", missing, 80)
+    print(
+        "\n[⑥ 处置纪律] 默认按陷阱处理，除非真机核对确有值。\n"
+        "  绝不无脑补的探测物（process/_phantom/__webdriver_script_fn/StyleMedia/Float16Array 等）\n"
+        "  见 references/trap-blacklist.md；三态与补漏原则见 references/patching-principles.md。\n"
+        "[下一步] ① 读到的字段 → scripts/defaults_audit.py 求交集算真正要配的；\n"
+        "        抛 TypeError 的 stub 窟窿 → scripts/reproduce_stub_error.py。"
+    )
+
+
+if __name__ == "__main__":
+    main()

package/skills/iv8-env-runtime/scripts/network_bridge.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+network_bridge.py — iv8 真实网络桥接（阶段 P3，固化四步握手）
+
+======================================================================
+四步握手红线（社区版无真实网络传输栈，真请求必须走 Python 侧）：
+  1) JS 侧发起 XHR/fetch  —— iv8 只记账到 netLog，不真正发出请求。
+  2) 暂停在这里，从 netLog 取出目标请求（url/method/headers/body）。
+  3) Python 侧用真实 HTTP 客户端（requests / curl_cffi ...）真发，
+     代理 / TLS 指纹 / cookie 池 / verify 由调用者决定。
+  4) ctx.add_resource(url, body, status, headers) 注入响应，
+     再 eventLoop.drain() 推进事件循环 —— XHR 回调此时才命中注入的响应。
+  顺序错了（比如没 drain 就读结果，或没 add_resource 就 drain）都会拿到空/半成品。
+
+⚠ GIL 警告：
+  ctx.expose() 暴露给 JS 的 Python 函数，在被 JS 调用期间会持有 GIL 并阻塞
+  当前 V8 执行与其他 Python 线程，是完全同步阻塞的。因此：
+  - 暴露的桥接函数要尽量轻量，别在里面塞重逻辑；
+  - 高并发场景优先用下面 bridge_request() 的「外部真发 + add_resource 注入」模式，
+    而不是把 requests.get 直接 expose 进 JS 里循环调用。
+======================================================================
+
+用途：
+  提供一个可复用的 bridge_request()：在 iv8 里让目标 JS 发起请求 → 从 netLog 捞出
+  该请求 → Python 侧真发 → add_resource 注入响应 → drain 推进 → 返回真实响应。
+  以及 __main__ 里一段最小可跑演示。
+
+用法（库调用）：
+    import iv8, requests
+    from network_bridge import bridge_request
+    with iv8.JSContext(environment={...}) as ctx:
+        ctx.eval(open("target.js").read())
+        # 让目标 JS 发起它的请求（这里只入 netLog，不真发）
+        ctx.eval("window.startCollect()")
+        resp_text = bridge_request(
+            ctx,
+            url_substr="/api/collect",      # 用于在 netLog 中定位目标请求
+            session=requests.Session(),     # 由调用者提供，携带代理/cookie/TLS 策略
+            verify=False,                   # curl_cffi/requests 自签名场景可关
+        )
+
+本文件属于 iv8-env-runtime skill。
+交叉引用：事件循环 drain/advance 语义与 netLog 结构见
+         references/network-and-eventloop.md；
+         iv8 权威 API 见 references/iv8-api-contract.md。
+"""
+
+import sys
+
+
+def _find_entry(netlog, url_substr):
+    """在 netLog.entries 里按 url 子串定位目标请求，取最后一条匹配（通常是最新）。"""
+    match = None
+    for e in netlog:
+        if not isinstance(e, dict):
+            continue
+        if url_substr in str(e.get("url", "")):
+            match = e
+    return match
+
+
+def bridge_request(ctx, url_substr, session=None, method=None,
+                   extra_headers=None, verify=True, proxies=None, timeout=15):
+    """执行一次四步握手，返回注入到 iv8 后由 JS 侧收到的响应体文本。
+
+    参数：
+      ctx          : 已载入目标 JS 且已触发发请求的 iv8.JSContext。
+      url_substr   : 在 netLog 中定位目标请求的 url 子串。
+      session      : 调用者提供的 HTTP 客户端（requests.Session / curl_cffi.Session）；
+                     None 时用一次性 requests。代理/TLS 指纹/cookie 全由它决定。
+      method       : 覆盖请求方法；None 时用 netLog 记的方法。
+      extra_headers: 追加/覆盖到真发请求上的头（如补 cookie/referer）。
+      verify       : 传给客户端的 TLS 校验开关（curl_cffi 自签名场景常关）。
+      proxies      : 传给客户端的代理配置。
+      timeout      : 真发超时秒数。
+
+    返回：注入后的响应体文本（同时已 add_resource + drain，JS 侧回调已命中）。
+    """
+    # 步骤 2：从 netLog 捞出目标请求（此前 JS 已 step 1 发起，仅入账未真发）
+    netlog = ctx.eval("window.__iv8__.netLog.entries", to_py=True)
+    entry = _find_entry(netlog, url_substr)
+    if entry is None:
+        raise LookupError(
+            "netLog 中没有匹配 '{}' 的请求：确认目标 JS 已真的发起该请求，"
+            "且 url_substr 写对了。当前 netLog 有 {} 条。".format(url_substr, len(netlog)))
+
+    url = entry.get("url")
+    req_method = (method or entry.get("method") or "GET").upper()
+    headers = dict(entry.get("headers") or {})
+    if extra_headers:
+        headers.update(extra_headers)
+    body = entry.get("body") or entry.get("postData")
+
+    # 步骤 3：Python 侧真发（客户端由调用者决定，携带代理/cookie/TLS 指纹）
+    if session is None:
+        import requests
+        session = requests.Session()
+    resp = session.request(req_method, url, headers=headers, data=body,
+                           verify=verify, proxies=proxies, timeout=timeout)
+
+    # 步骤 4：注入响应 → drain 推进 → JS 侧 XHR 回调命中
+    ctx.add_resource(
+        url=url,
+        body=resp.text,
+        status=resp.status_code,
+        headers=dict(resp.headers),
+    )
+    ctx.eval("window.__iv8__.eventLoop.drain()")
+    return resp.text
+
+
+# ---------------------------------------------------------------------------
+# 最小可跑演示（需已安装 iv8 与 requests）：JS 发 XHR → 桥接真发 httpbin → 注入 → 读结果
+# ---------------------------------------------------------------------------
+def _demo():
+    try:
+        import iv8
+        import requests  # noqa: F401 —— bridge_request 内部用；此处仅校验可导入
+    except Exception as e:  # noqa: BLE001
+        print("[network_bridge][demo] 依赖缺失：{}；先跑 preflight.py。".format(e), file=sys.stderr)
+        return 2
+
+    with iv8.JSContext() as ctx:
+        ctx.eval("""
+            window.__iv8__.page.load({
+                baseURL: 'https://example.com',
+                html: '<html><body></body></html>'
+            });
+        """)
+        # 步骤 1：JS 侧发起异步 XHR（社区版只入 netLog，不真发）
+        ctx.eval("""
+            var xhr = new XMLHttpRequest();
+            xhr.open('GET', 'https://httpbin.org/get?foo=bar');
+            xhr.onload = function () { window._demoResult = xhr.responseText; };
+            xhr.send();
+        """)
+        # 步骤 2/3/4：桥接
+        body = bridge_request(ctx, url_substr="httpbin.org/get")
+        print("[network_bridge][demo] 注入响应长度：{}".format(len(body)))
+        got = ctx.eval("window._demoResult")
+        print("[network_bridge][demo] JS 侧收到长度：{}".format(len(got) if got else 0))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(_demo())

package/skills/iv8-env-runtime/scripts/parity_check.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""parity_check.py —— P4 验收对账：iv8 产物 vs 真机产物，逐字符/逐字段找首个差异。
+
+作用（对应 SKILL.md 的 P4「parity 对账 + 服务器判决唯一真相」）：
+    把「iv8 补环境跑出来的签名/token」和「真实浏览器抓到的同场景签名/token」放一起，
+    逐字符（或逐字段，若是 JSON/query-string）对比，定位第一个不一致的位置，
+    帮你把「补环境哪里还没对齐」收窄到具体字段。
+
+    ⚠ 铁律（本 skill 的验收真相层）：
+      本地一致只是「必要不充分」条件。parity 全绿也不代表过盾——
+      很多签名含时间戳/随机盐，本来就该逐次不同；对账目的是排查「结构性字段」对齐，
+      不是要求整串相等。**唯一的最终真相是把 iv8 产物发到目标服务器，看它判 200 / code=0。**
+      算出来被服务器拒 → 回 P3 继续补环境；返回 403（风控/IP/频率）→ 不是环境问题，别在补环境里空转。
+      服务器判决怎么读见 references/part2-discovery.md。
+
+对账模式（自动判定，也可 --mode 强制）：
+    - raw   ：整串逐字符对比，报首个差异下标 + 两侧上下文窗口
+    - kv    ：query-string（a=1&b=2）逐键对比，报缺键/多键/值不同
+    - json  ：JSON 逐字段递归对比，报首个路径差异
+
+关系与边界：
+    - 上游：iv8 产物来自 assets/env_starter.py 跑出的签名；真机产物来自 js-reverse MCP
+            或真实浏览器抓包（找入口/抓真机产物见 references/part1-entry-location.md）。
+    - 本脚本只做「本地一致性」这一必要条件；充分条件（服务器判决）由你手动发包核对。
+
+用法：
+    python parity_check.py <iv8产物> <真机产物> [--mode raw|kv|json] [--file]
+      默认两个位置参数是「值本身」；加 --file 则当作文件路径读取内容。
+      示例：
+        python parity_check.py "a_bogus=xxx" "a_bogus=yyy"
+        python parity_check.py iv8_out.txt real_out.txt --file
+        python parity_check.py iv8.json real.json --file --mode json
+"""
+
+import argparse
+import json
+import sys
+from urllib.parse import parse_qsl
+
+
+def _read(value, is_file):
+    if not is_file:
+        return value
+    with open(value, "r", encoding="utf-8") as f:
+        return f.read().strip()
+
+
+def guess_mode(a, b):
+    """自动判定对账模式。"""
+    for s in (a, b):
+        t = s.strip()
+        if t[:1] in "{[":
+            try:
+                json.loads(t)
+                return "json"
+            except ValueError:
+                pass
+    if ("=" in a and ("&" in a or "&" in b)) or ("=" in a and "=" in b and " " not in a):
+        return "kv"
+    return "raw"
+
+
+def check_raw(a, b):
+    """逐字符对比，返回 (是否一致, 报告文本)。"""
+    if a == b:
+        return True, f"完全一致（长度 {len(a)}）"
+    n = min(len(a), len(b))
+    idx = next((i for i in range(n) if a[i] != b[i]), n)
+    lo = max(0, idx - 20)
+    win_a = a[lo:idx + 20]
+    win_b = b[lo:idx + 20]
+    report = [
+        f"首个差异位置: 下标 {idx}（长度 iv8={len(a)} / 真机={len(b)}）",
+        f"  iv8 : ...{win_a!r}",
+        f"  真机: ...{win_b!r}",
+    ]
+    if idx < n:
+        report.append(f"  差异字符: iv8={a[idx]!r}  真机={b[idx]!r}")
+    else:
+        longer = "iv8" if len(a) > len(b) else "真机"
+        report.append(f"  前 {idx} 字符相同，{longer} 更长（尾部多出内容）")
+    return False, "\n".join(report)
+
+
+def check_kv(a, b):
+    """query-string 逐键对比。"""
+    da = dict(parse_qsl(a, keep_blank_values=True))
+    db = dict(parse_qsl(b, keep_blank_values=True))
+    keys = list(dict.fromkeys(list(da) + list(db)))
+    diffs = []
+    for k in keys:
+        if k not in da:
+            diffs.append(f"  [多键] 真机有、iv8 缺: {k}={db[k]!r}")
+        elif k not in db:
+            diffs.append(f"  [缺键] iv8 有、真机缺: {k}={da[k]!r}")
+        elif da[k] != db[k]:
+            diffs.append(f"  [值异] {k}: iv8={da[k]!r}  真机={db[k]!r}")
+    if not diffs:
+        return True, f"所有键值一致（共 {len(keys)} 键）"
+    return False, f"共 {len(diffs)} 处键差异:\n" + "\n".join(diffs)
+
+
+def _first_json_diff(a, b, path="$"):
+    """递归找 JSON 首个字段差异，返回路径描述或 None。"""
+    if type(a) is not type(b) and not (isinstance(a, (int, float)) and isinstance(b, (int, float))):
+        return f"{path}: 类型不同 iv8={type(a).__name__} 真机={type(b).__name__}"
+    if isinstance(a, dict):
+        for k in dict.fromkeys(list(a) + list(b)):
+            if k not in a:
+                return f"{path}.{k}: iv8 缺此键（真机={b[k]!r}）"
+            if k not in b:
+                return f"{path}.{k}: 真机缺此键（iv8={a[k]!r}）"
+            d = _first_json_diff(a[k], b[k], f"{path}.{k}")
+            if d:
+                return d
+        return None
+    if isinstance(a, list):
+        if len(a) != len(b):
+            return f"{path}: 数组长度不同 iv8={len(a)} 真机={len(b)}"
+        for i, (x, y) in enumerate(zip(a, b)):
+            d = _first_json_diff(x, y, f"{path}[{i}]")
+            if d:
+                return d
+        return None
+    if a != b:
+        return f"{path}: 值不同 iv8={a!r} 真机={b!r}"
+    return None
+
+
+def check_json(a, b):
+    try:
+        ja, jb = json.loads(a), json.loads(b)
+    except ValueError as e:
+        return False, f"JSON 解析失败: {e}（改用 --mode raw）"
+    diff = _first_json_diff(ja, jb)
+    if diff is None:
+        return True, "所有字段一致"
+    return False, "首个字段差异:\n  " + diff
+
+
+def main():
+    ap = argparse.ArgumentParser(description="iv8 产物 vs 真机产物 对账；服务器判决才是最终真相")
+    ap.add_argument("iv8_value", help="iv8 补环境产物（值，或加 --file 传路径）")
+    ap.add_argument("real_value", help="真机产物（值，或加 --file 传路径）")
+    ap.add_argument("--mode", choices=["raw", "kv", "json"], default="auto", help="对账模式（默认自动判定）")
+    ap.add_argument("--file", action="store_true", help="把两个位置参数当作文件路径读取")
+    args = ap.parse_args()
+
+    a = _read(args.iv8_value, args.file)
+    b = _read(args.real_value, args.file)
+
+    mode = args.mode if args.mode != "auto" else guess_mode(a, b)
+    print(f"对账模式: {mode}\n")
+
+    ok, report = {"raw": check_raw, "kv": check_kv, "json": check_json}[mode](a, b)
+    print(report)
+
+    print("\n" + "=" * 72)
+    if ok:
+        print("本地对账: 一致 ✓（必要条件满足）")
+    else:
+        print("本地对账: 不一致 ✗ → 回 P3 补环境（对准差异字段）")
+    print(
+        "⚠ 本地一致只是必要不充分。最终真相 = 把 iv8 产物发到目标服务器看判决:\n"
+        "   服务器 200 / code=0 才算翻过；被拒→回 P3；403（风控/IP/频率）→ 非环境问题。\n"
+        "   （含时间戳/随机盐的签名本就逐次不同，对账看结构性字段而非整串相等。）\n"
+        "   服务器判决怎么读见 references/part2-discovery.md。"
+    )
+    # 退出码：本地一致 0 / 不一致 1（便于脚本串联），但仍以服务器判决为准
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()