dsh-js-reverse-plugin 0.1.0

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

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+preflight.py — iv8 环境就绪硬前置门（阶段 P0）
+
+用途：
+  在做任何补环境工作之前，先跑这一步。它按当前平台/架构/Python 版本判定
+  iv8 能否安装与运行，装错平台或版本直接硬阻断（sys.exit 非 0），并在成功时
+  打印已安装的 iv8.__version__ —— 这个版本号是「单一真相源」，
+  references/version-gotchas.md 的所有版本门控（E1 btoa、E2 MessageChannel、
+  E4 WASM 等）都以此处打印的实测版本为准，不要凭记忆判断。
+
+用法：
+  python3 scripts/preflight.py
+  退出码 0 = 环境就绪；非 0 = 阻断（终端会打印具体原因与修复指引）。
+
+约束（来自 iv8 README，实测 0.1.3）：
+  - Windows x64 / Linux x86_64：pip 官方源可装（PyPI，Python 3.9–3.14）。
+  - Linux aarch64：需自查 manylinux aarch64 wheel 是否可得。
+  - macOS 仅 Apple Silicon(arm64) 实验版，不上 PyPI，去 GitHub Releases 下 wheel。
+    支持 Python 3.11–3.14、macOS 14+。Intel Mac 或 Py<3.11 一律不支持。
+  - 项目强制用 uv 管理依赖（见 CLAUDE.md）。
+
+本文件属于 iv8-env-runtime skill。
+交叉引用：安装细节见 references/cross-platform-install.md；
+         版本坑门控见 references/version-gotchas.md（消费本脚本打印的版本号）。
+"""
+
+import platform
+import sys
+
+GH_RELEASES = "https://github.com/HanZzzzz000/iv8/releases"
+
+
+def _py_tag():
+    """把 3.11 -> 'cp311'，供拼 macOS wheel 名用。"""
+    return "cp{}{}".format(sys.version_info.major, sys.version_info.minor)
+
+
+def _fail(msg):
+    """打印阻断原因并以非 0 退出。"""
+    print("\n[preflight][阻断] " + msg, file=sys.stderr)
+    sys.exit(2)
+
+
+def _guide_install():
+    """按平台/架构/Python 版本给出安装指引；不支持的组合直接 _fail。
+
+    返回 True 表示「本平台应当已经能 import iv8」（走 PyPI 或已下载的 wheel），
+    仅用于决定后续冒烟测试的措辞。
+    """
+    system = platform.system()
+    machine = platform.machine().lower()
+    py = sys.version_info
+
+    print("[preflight] 平台检测：system={} machine={} python={}.{}.{}".format(
+        system, machine, py.major, py.minor, py.micro))
+
+    # ---- Windows ----
+    if system == "Windows":
+        if machine not in ("amd64", "x86_64"):
+            _fail("Windows 仅支持 x64（当前 machine={}），无预编译 wheel。".format(machine))
+        if not (3, 9) <= (py.major, py.minor) <= (3, 14):
+            _fail("iv8 支持 Python 3.9–3.14，当前 {}.{} 不在范围内。".format(py.major, py.minor))
+        print("[preflight] Windows x64：uv pip install iv8   （PyPI 官方源）")
+        return True
+
+    # ---- Linux ----
+    if system == "Linux":
+        if machine in ("x86_64", "amd64"):
+            if not (3, 9) <= (py.major, py.minor) <= (3, 14):
+                _fail("iv8 支持 Python 3.9–3.14，当前 {}.{} 不在范围内。".format(py.major, py.minor))
+            print("[preflight] Linux x86_64：uv pip install iv8   （PyPI，manylinux）")
+            return True
+        if machine in ("aarch64", "arm64"):
+            # aarch64 wheel 是否发布随版本变化，不写死结论，交给用户核对。
+            print("[preflight] Linux aarch64：README 明确的官方轮子是 x64 manylinux。")
+            print("            请自查 PyPI/Releases 是否提供 manylinux aarch64 wheel：")
+            print("              uv pip install iv8   # 若报 no matching distribution 即无 aarch64 轮")
+            print("            若确无 aarch64 wheel，则当前架构暂无本地安装路径。")
+            return False
+        _fail("Linux 未知架构 machine={}，无对应 wheel。".format(machine))
+
+    # ---- macOS ----
+    if system == "Darwin":
+        if machine != "arm64":
+            _fail("macOS 仅支持 Apple Silicon(arm64) 实验版；当前 machine={}（Intel Mac 不支持）。".format(machine))
+        if not (3, 11) <= (py.major, py.minor) <= (3, 14):
+            _fail("macOS 实验版仅支持 Python 3.11–3.14（且需 macOS 14+）；当前 {}.{} 不支持。".format(
+                py.major, py.minor))
+        tag = _py_tag()
+        wheel = "iv8-<ver>-{tag}-{tag}-macosx_14_0_arm64.whl".format(tag=tag)
+        print("[preflight] macOS Apple Silicon 实验版（不上 PyPI）：")
+        print("            1) 去 GitHub Releases 下载对应 wheel：{}".format(GH_RELEASES))
+        print("               文件名形如（<ver> 用实际版本替换，勿写死）：{}".format(wheel))
+        print("            2) 用 uv 安装：uv pip install ./{}".format(wheel))
+        return False  # 是否已装取决于用户是否下载过，冒烟测试会给出真实结论
+
+    _fail("未识别的操作系统 system={}。".format(system))
+
+
+def _smoke():
+    """import iv8 冒烟：ctx.eval('1+1')==2 且 navigator.webdriver==False，并打印版本号。"""
+    try:
+        import iv8
+    except Exception as e:  # noqa: BLE001 —— 需要把任何导入失败都转成清晰指引
+        _fail("import iv8 失败：{}\n"
+              "  说明 iv8 尚未安装或安装的 wheel 与当前平台/Python 不匹配。\n"
+              "  按上方安装指引用 uv 安装对应 wheel 后重跑本脚本。".format(e))
+
+    version = getattr(iv8, "__version__", "<未知>")
+
+    try:
+        with iv8.JSContext() as ctx:
+            one_plus_one = ctx.eval("1 + 1")
+            webdriver = ctx.eval("navigator.webdriver")
+    except Exception as e:  # noqa: BLE001
+        _fail("iv8 已导入但 JSContext 冒烟失败：{}".format(e))
+
+    if one_plus_one != 2:
+        _fail("冒烟异常：ctx.eval('1 + 1') 返回 {!r}（应为 2）。".format(one_plus_one))
+    if webdriver is not False:
+        _fail("冒烟异常：navigator.webdriver 返回 {!r}（应为 False）。".format(webdriver))
+
+    # ★ 单一真相源：把实测版本号打印出来，供 version-gotchas 门控消费。
+    print("\n[preflight][通过] iv8 冒烟成功。")
+    print("[preflight] iv8.__version__ = {}".format(version))
+    print("[preflight] ↑ 该版本号是版本门控唯一真相；references/version-gotchas.md")
+    print("            按此判断 E1(btoa)/E2(MessageChannel)/E4(WASM) 等坑是否已修，勿凭记忆。")
+    return version
+
+
+def main():
+    print("=" * 64)
+    print("iv8-env-runtime · P0 preflight（环境就绪硬前置门）")
+    print("=" * 64)
+    _guide_install()
+    _smoke()
+    print("\n[preflight] P0 通过，可进入 P1（找入口）。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""reproduce_stub_error.py —— P2 定位 stub 空壳窟窿：跑目标直到抛 TypeError，压缩打印异常栈。
+
+作用（对应 SKILL.md 的 P2「TypeError 栈=stub 窟窿」）：
+    iv8 对很多浏览器 API 给了「接口级 stub」——存在但内部为空壳（典型：
+    MessageChannel 构造出来 port1/port2 为 null）。目标 JS 一旦真去用它（如
+    core-js 的 microtask 降级链会 new MessageChannel() 再取 port.postMessage），
+    就在运行时抛 TypeError。本脚本分步 eval 目标（load → init → 触发），
+    第一处抛错即捕获，并把冗长的混淆源码行压掉，只留「异常类型 + 位置摘要」，
+    再打印一个「用 wrapNative 替换 stub」的提示模板。
+
+    这是「三态」里的中间态：stub 空壳（替换）——区别于「真实现（别动）」与
+    「陷阱缺失（绝不补）」。stub 的判定证据就是这里的 TypeError 栈。
+
+关系与边界：
+    - 上游：scripts/monitor_env.py 第⑥类「疑似缺失 API」提示哪里可能有窟窿；
+            本脚本用「真跑抛错」坐实是不是 stub 空壳（缺失=没有该 API；stub=有但为空壳）。
+    - 下游：确认是 stub → 按 references/patching-principles.md 的 iv8 原生补丁契约，
+            用 __iv8__.wrapNative 写一个有真机证据的最小替身。
+            本脚本只复现 MessageChannel / Worker 的 core-js 降级链与 iv8 调度问题。
+    - MessageChannel/Worker null port 属已知坑 E2，版本门控见 references/version-gotchas.md。
+    - 权威 API 契约见 references/iv8-api-contract.md。
+
+用法：
+    python reproduce_stub_error.py <目标JS路径> [--init <init表达式文件>] [--trigger <触发表达式文件>]
+                                   [--env <environment JSON文件>] [--patch <预置替身JS文件>]
+
+    - 不给 --patch：复现原始 TypeError（先看窟窿在哪）
+    - 给 --patch：把替身 JS 先注入再跑（验证替换后是否跑通），
+      --patch 文件内应是一段用 __iv8__.wrapNative 写的替身（示例见文末提示模板）。
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+try:
+    import iv8
+except ImportError:
+    sys.exit("未找到 iv8。先跑 scripts/preflight.py 确认安装（安装见 references/cross-platform-install.md）。")
+
+
+# wrapNative 替换 stub 的提示模板（以 MessageChannel 为例，别照抄值，按目标改）
+WRAPNATIVE_HINT = """\
+[提示] 若确认是 stub 空壳（如 MessageChannel port=null），用 __iv8__.wrapNative 替换：
+
+    window.MessageChannel = __iv8__.wrapNative(function() {
+        var p1 = { onmessage: null }, p2 = { onmessage: null };
+        p1.postMessage = function(d) {
+            if (p2.onmessage) setTimeout(function(){ p2.onmessage({ data: d }); }, 0);
+        };
+        p2.postMessage = function(d) {
+            if (p1.onmessage) setTimeout(function(){ p1.onmessage({ data: d }); }, 0);
+        };
+        return { port1: p1, port2: p2 };
+    }, 'MessageChannel');
+
+要点：
+  - wrapNative 让替身 toString() 显示 [native code]，降低可观测差异。
+  - 触发后需 __iv8__.eventLoop.advance(...) / drain() 排空 setTimeout 回调（微任务降级链）。
+  - 三态：stub=替换 / 真实现=别动 / 陷阱缺失=绝不补（见 references/patching-principles.md）。
+  - 完整替身必须按目标证据最小实现，并按 references/patching-principles.md 补后对账。
+"""
+
+
+def summarize_exception(exc, limit=1200):
+    """压缩 iv8 异常字符串：混淆目标的源码行可能是整份几十 KB bundle，这里裁掉只留位置。"""
+    text = str(exc) or repr(exc)
+    text = re.sub(r"\s+", " ", text).strip()
+    # iv8 异常串常形如 "... ( @ <line> : <col> ) -> <整行源码>"，裁掉 -> 之后
+    m = re.match(r"^(.*?\( @ \d+ : \d+ \))\s*->", text)
+    if m:
+        return m.group(1)
+    if len(text) > limit:
+        return text[:limit] + " ...<truncated>"
+    return text
+
+
+def run_step(ctx, label, source):
+    """执行一步，成功返回 (True, value)，抛错则打印压缩摘要返回 (False, None)。"""
+    print(f"\n== {label} ==")
+    try:
+        value = ctx.eval(source, name=label, to_py=True)
+    except Exception as exc:  # noqa: BLE001 —— 就是要捕获任意运行时异常
+        print("FAILED")
+        print("  exception type   :", type(exc).__name__)
+        print("  exception summary:", summarize_exception(exc))
+        return False, None
+    print("OK")
+    return True, value
+
+
+def main():
+    ap = argparse.ArgumentParser(description="跑目标直到抛 TypeError，压缩打印，定位 stub 空壳窟窿")
+    ap.add_argument("js_path", help="目标 JS 文件路径")
+    ap.add_argument("--init", default="", help="加载后的初始化表达式文件（如 xxx.init({...})）")
+    ap.add_argument("--trigger", default="", help="触发签名/取数的表达式文件")
+    ap.add_argument("--env", default="", help="environment 画像 JSON 文件路径")
+    ap.add_argument("--patch", default="", help="预置替身 JS 文件（先注入再跑，验证替换是否跑通）")
+    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)
+
+    with open(args.js_path, "r", encoding="utf-8") as f:
+        js = f.read()
+
+    def read_opt(path):
+        if not path:
+            return ""
+        with open(path, "r", encoding="utf-8") as fh:
+            return fh.read()
+
+    patch_src = read_opt(args.patch)
+    init_src = read_opt(args.init)
+    trigger_src = read_opt(args.trigger) or "window.__iv8__.eventLoop.drain();"
+
+    print("目标 JS   :", args.js_path)
+    print("JS 字节   :", len(js.encode("utf-8")))
+    print("预置替身  :", "有（--patch）" if patch_src else "无（复现原始报错）")
+
+    # prod 模式即可复现（不需要 debug 监控开销）
+    with iv8.JSContext(environment=env) as ctx:
+        if patch_src:
+            ok, _ = run_step(ctx, "inject patch (wrapNative 替身)", patch_src)
+            if not ok:
+                print("\n替身注入本身就抛错，先修替身。")
+                print(WRAPNATIVE_HINT)
+                return
+
+        ok, _ = run_step(ctx, "eval target", js)
+        if not ok:
+            print(WRAPNATIVE_HINT)
+            return
+
+        if init_src:
+            ok, _ = run_step(ctx, "init", init_src)
+            if not ok:
+                print(WRAPNATIVE_HINT)
+                return
+
+        ok, val = run_step(ctx, "trigger + drain", trigger_src)
+        if not ok:
+            print(WRAPNATIVE_HINT)
+            return
+
+        print("\n全部步骤跑通，未复现 stub 报错。")
+        if patch_src:
+            print("→ 替身有效：该 stub 窟窿已补上。")
+        else:
+            print("→ 目标此路径未触发 stub 窟窿（或缺口在别处）。")
+        if isinstance(val, list):
+            print(f"trigger 返回条目数: {len(val)}")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+run_target.py — iv8 标准 runner（阶段 P3，内联 drain-before-read 断言）
+
+用途：
+  用最小的确定性流程把目标反爬 JS 在 iv8 里跑起来并收割签名/token：
+    建 JSContext(environment=...) → 载入原始 JS → 求值入口表达式 → 收割结果。
+  它把一条容易被忘、忘了就得到「空 netLog / 半成品 token」的铁律固化进代码：
+    ★ 读取 netLog.entries / 任何异步产物之前，必须先 eventLoop.drain() 推进事件循环。
+  本脚本用 _read_netlog() 包装强制「先 drain 再读」，任何绕过它直接读 netLog
+  的写法在本 runner 里会被断言拦下。
+
+  deploy 绑定值（aid / script id / bdms 版本 / u 数组 / golden sum 等）一律不写死，
+  全部从函数参数或外部文件传入，运行时解析。
+
+用法（库调用，推荐）：
+    from run_target import run
+    result = run(
+        target_js_path="target.js",
+        environment={...},          # 见 assets/env_starter.py 起手模板
+        entry_expr="window.getSign('/api/x')",   # P1 定位到的真实生成入口
+        need_network=False,
+    )
+    # result = {"value": <入口返回值>, "netlog": [...已 drain 后的请求...]}
+
+用法（命令行）：
+    python3 scripts/run_target.py target.js env.json "window.getSign('/api/x')"
+
+本文件属于 iv8-env-runtime skill。
+交叉引用：
+  - 入口表达式 entry_expr 怎么定位见 references/part1-entry-location.md；
+  - environment 该配什么见 references/config-defaults-cheatsheet.md 与
+    assets/env_starter.py；
+  - stub 窟窿（MessageChannel/Worker 等）的 iv8 原生替换契约见
+    references/patching-principles.md；
+  - 真实网络桥接（need_network=True 的四步握手）见 scripts/network_bridge.py。
+"""
+
+import json
+import sys
+
+
+class DrainError(RuntimeError):
+    """未先 drain 事件循环就读取异步产物时抛出。"""
+
+
+def _new_context(environment, config=None, time_mode="logical"):
+    """创建一个最小配置的 JSContext。import 失败给清晰指引（先跑 preflight）。"""
+    try:
+        import iv8
+    except Exception as e:  # noqa: BLE001
+        raise RuntimeError(
+            "import iv8 失败：{}；请先跑 scripts/preflight.py 确认 P0 环境就绪。".format(e))
+    return iv8.JSContext(environment=environment or {}, config=config or None,
+                         time_mode=time_mode)
+
+
+def _read_netlog(ctx, drained_flag):
+    """★ 唯一允许的 netLog 读取通道：调用前必须已 drain。
+
+    drained_flag 是一个单元素 list（可变引用），run() 在调用 drain 后置 True。
+    若为 False 直接读 netLog，抛 DrainError —— 把「先 drain 再读」变成硬约束，
+    而不是一句注释里的提醒。
+    """
+    if not drained_flag[0]:
+        raise DrainError(
+            "读取 netLog.entries 之前未调用 eventLoop.drain()：异步 XHR/fetch 可能尚未落账，"
+            "会读到空或半成品。请先 ctx.eval(\"window.__iv8__.eventLoop.drain()\") 再读。")
+    return ctx.eval("window.__iv8__.netLog.entries", to_py=True)
+
+
+def run(target_js_path, environment, entry_expr,
+        need_network=False, config=None, time_mode="logical",
+        stub_setup_js=None, drain_max=None):
+    """跑目标 JS 并收割结果。
+
+    参数：
+      target_js_path : 原始目标 JS 文件路径（未改写）。
+      environment    : iv8 画像 dict（location.href 通常必配，默认 about:blank）。
+      entry_expr     : P1 定位到的真实「生成」入口表达式，其返回值即要收割的产物。
+      need_network   : 目标是否会发真实请求。社区版无真实网络栈，True 时请改用
+                       scripts/network_bridge.py 的桥接流程；这里仅收 netLog 便于观察。
+      config         : 引擎行为标量（timezone/permissions.* 等），可选。
+      time_mode      : 'logical'（默认）或 'system'（POW/时间差校验时用）。
+      stub_setup_js  : 可选，载入目标前先注入的 stub 替换/wrapNative 补丁 JS 字符串。
+                       补丁应依据目标证据最小实现；本 runner 不内置固定清单。
+      drain_max      : 传给 eventLoop.drain(max) 的上限，None=排空全部已到期任务。
+
+    返回：
+      {"value": <entry_expr 求值结果>, "netlog": [...]}
+    """
+    with open(target_js_path, "r", encoding="utf-8") as f:
+        js_code = f.read()
+
+    drained_flag = [False]  # 可变引用，drain 后置 True，给 _read_netlog 做硬断言
+    ctx = _new_context(environment, config=config, time_mode=time_mode)
+    try:
+        # 1) 载入目标之前先打有证据的最小 stub 补丁（如 MessageChannel/Worker 替换）
+        if stub_setup_js:
+            ctx.eval(stub_setup_js, name="stub_setup")
+
+        # 2) 载入原始目标 JS（不改写）
+        ctx.eval(js_code, name=target_js_path)
+
+        # 3) 求值真实生成入口，拿返回值
+        value = ctx.eval(entry_expr, name="entry_expr", to_py=True)
+
+        # 4) ★ 读任何异步产物（netLog）之前，强制 drain 推进事件循环
+        if drain_max is None:
+            ctx.eval("window.__iv8__.eventLoop.drain()")
+        else:
+            ctx.eval("window.__iv8__.eventLoop.drain({})".format(int(drain_max)))
+        drained_flag[0] = True
+
+        netlog = _read_netlog(ctx, drained_flag)
+
+        return {"value": value, "netlog": netlog}
+    finally:
+        try:
+            ctx.close()
+        except Exception:  # noqa: BLE001 —— 关闭失败不应掩盖主流程结果
+            pass
+
+
+def _load_json(path):
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def main(argv):
+    if len(argv) < 4:
+        print('用法：python3 run_target.py target.js env.json "<entry_expr>"', file=sys.stderr)
+        return 2
+    target_js = argv[1]
+    environment = _load_json(argv[2])
+    entry_expr = argv[3]
+
+    result = run(target_js, environment, entry_expr)
+    print("[run_target] 入口返回值：")
+    print(json.dumps(result["value"], ensure_ascii=False, indent=2, default=str))
+    print("[run_target] netLog 条目数（已 drain）：{}".format(len(result["netlog"])))
+    for e in result["netlog"]:
+        if isinstance(e, dict):
+            print("  {} {}".format(e.get("method", ""), e.get("url", "")))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/skills/iv8-jsvmp-recovery/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: iv8-jsvmp-recovery
+description: >-
+  以受控 iv8 中的原始 JavaScript/JSVMP 作为参考实现，结合静态解释器、Bytecode、Handler、Opcode、Record、CFG 分析和动态 Trace，恢复从声明的原始输入到最终签名、Token 或密文的独立可执行映射，并以精确等价验收。用于 JSVMP/VMP 语义恢复、字节码反汇编或反编译、Handler 准确语义、Record/虚拟函数边界、调用图或控制流、字符串恢复、静态结果与 Trace 对账、受控输入试验、以及 Python/JavaScript 独立实现的端到端复现。不负责通用外层 AST 解混淆、iv8 安装与通用补环境，也不把服务器接受当作 VM 语义等价的唯一证明。
+---
+
+# iv8 JSVMP Recovery
+
+## 主线
+
+始终围绕同一个目标展开分析：
+
+> 以受控 iv8 中的原始程序作为参考实现，结合静态分析和动态 Trace，恢复从声明的原始输入到最终输出的独立可执行映射，并以精确等价作为验收标准。
+
+把 Handler 命名、Record 拆分、CFG、字符串解密、Trace 和中间值对账都视为恢复这个映射的证据或手段，不把它们自身当作最终目标。
+
+## 正确性定义
+
+先声明原始输入合同：
+
+```text
+RawInput =
+    request
+  + environment
+  + behavior
+  + time
+  + randomness
+  + configuration
+  + initialState
+
+OracleOutput = OriginalVMP_in_Controlled_iv8(RawInput)
+RecoveredOutput = IndependentImplementation(RawInput)
+
+验收：RecoveredOutput === OracleOutput
+```
+
+把 `===` 解释为声明编码下的长度相同且逐字节或逐字符完全一致。不用“结构差不多”、“可以解密”、“服务器接受”或“某个中间值相同”代替这个命题。
+
+区分结论范围：
+
+- 固定基线精确相等，证明该受控执行实例已被复现。
+- 受控变体和静态全分支证据，用于扩大可声明的语义范围。
+- 不要把一个固定实例的成功推广为所有环境、状态和未执行路径的函数等价。
+
+## 原始输入边界
+
+从宿主可观测事实开始建模。允许输入请求、环境属性、原始行为事件或初始队列状态、时间源、随机源、SDK 配置、存储/网络响应和共享初始状态。
+
+不把下列 VM 派生值伪装为原始输入：
+
+- 已计算的摘要、风险位、特征向量或行为编码；
+- 已组装的 core、header、prefix、checksum 或 material；
+- 预计算的密钥流、密文、随机打包结果或最终签名。
+
+要求独立实现自己从 `RawInput` 计算这些派生值。
+
+## 领域判断
+
+保持以下区分：
+
+- Handler 是解释器操作实现，Opcode 是程序数据中的编码，两者不必然一一对应。
+- Record 是样本定义的 VM 程序单元，不天然等于源码函数、调用帧或基本块。
+- 机械语义描述操作数、栈/寄存器、PC、Frame、Scope 和副作用；业务语义还需要连接真实输入、消费者和最终输出。
+- 静态分析描述可能的分支和数据依赖；动态 Trace 证明某一受控输入下真实执行的路径和值。
+- 使用 Trace 对账、反驳和定位首个分歧；不把一次 Trace 当作全路径证明。
+- 只在字符串是加密/编码常量且恢复后能连接当前映射时解密；不把字节码数据、字符串索引或普通字面量统一视为“待解密字符串”。
+
+## 分析自由度
+
+根据证据自行选择正向、反向或交替分析；根据问题选择局部切片、主线 CFG 或全库 CFG；根据现有条件调整静态与动态的比例。
+
+不强制：
+
+- 先恢复所有 Handler；
+- 先反编译全部 Bytecode；
+- 先建立完整 CFG 或调用图；
+- 必须从入口正向或从输出反向；
+- 把某个案例的分析顺序复制到其他 VM。
+
+根据当前声明的输出和证据缺口收束范围。如果局部主线已经足以从原始输入精确复现最终输出，不要为了形式完整继续扩展不影响该命题的全库细节。
+
+## 不可接受的伪正确
+
+不要作出以下完成声明：
+
+- 写死最终输出或只复现一个常量字符串；
+- 公开入口仍然接收 VM 预计算中间字段；
+- 只因服务器接受请求就声称本地计算与原 VM 等价；
+- 只因 Trace 中数值相同就填入未证明的业务名称；
+- 把 Handler、Opcode、Record 或 Trace 覆盖数量直接当作源码函数数量；
+- 修改原始程序或执行环境后，仍把结果冒充为原始 Oracle；
+- 没有声明时间、随机、存储、网络、初始化顺序和共享状态。
+
+## 与相邻 Skill 的边界
+
+- 使用 `js-ast-deobfuscation` 处理外层 JavaScript、打包器、字符串隐藏、解释器宿主边界和 JSVMP 识别。
+- 使用 `iv8-env-runtime` 完成 iv8 安装、通用补环境、网络/事件循环接续和原始程序的稳定执行。
+- 在本 Skill 中消费已确认的 VM 边界和受控 Oracle，恢复 VM 内部映射并构建独立实现。
+
+原始程序尚不能受控复现时，先建立 Oracle 条件；尚未确认 VM 闭环时，先完成外层识别。不在本 Skill 中重写相邻 Skill 的工具和环境知识。
+
+## 证据与产物
+
+记录并持续区分：
+
+- 原始程序、Bytecode、配置和 `RawInput` 的版本与 Hash；
+- 已证明的机械语义、有证据的业务解释、推断和未知；
+- Oracle 运行条件、原始输出、Trace 覆盖和观测扰动；
+- 独立实现的输入合同、中间对账点和最终等价报告；
+- 完成声明的适用输入范围和未覆盖边界。
+
+不要强制统一产物文件名；优先沿用项目已有证据目录、坐标和格式。
+
+## Reference 路由
+
+只由本文件路由 reference；reference 不再继续路由其他 reference。
+
+- 需要判断 Handler、Opcode、Record、Frame、Scope、VM 函数、基本块、CFG 或 VM 字符串时，读取 [vmp-domain-model.md](references/vmp-domain-model.md)。
+- 需要建立受控 iv8 基线、定义 `RawInput`、区分派生字段、设计变体或声明精确等价时，读取 [controlled-oracle-and-equivalence.md](references/controlled-oracle-and-equivalence.md)。
+- 需要结合静态与 Trace、确定证据范围、评估 Handler 语义或定位首个分歧时，读取 [static-trace-evidence.md](references/static-trace-evidence.md)。
+- 当前对象是课程中的抖音 `a_bogus` 样本，或需要查看完整成功案例的证据结构时，读取 [case-study-douyin-a-bogus.md](references/case-study-douyin-a-bogus.md)。
+
+只读取当前问题需要的 reference。案例可用于提出假设，不能覆盖当前样本证据。
+
+## 精确等价脚本
+
+在声明固定输入精确等价时，执行 `scripts/verify-equivalence.py --help`，再用它对 `RawInput`、Oracle 输出和独立实现输出生成机器可读报告。
+
+该脚本只证明给定字节是否精确相等，不判断输入是否真正原始、实现是否独立，也不把单样本相等推广为全输入空间等价。

package/skills/iv8-jsvmp-recovery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "iv8 JSVMP Recovery"
+  short_description: "以受控 iv8 Oracle 恢复并精确验证 JSVMP 语义"
+  default_prompt: "Use $iv8-jsvmp-recovery to recover this JSVMP from declared raw inputs to an independently reproducible final output."