这份文档约束本仓库里的本地 Node 补环境流程,目标不是“一次性模拟浏览器”,而是基于 MCP 页面证据,让目标参数链路先跑通,再逐项补缺口。
- 先取证,再补环境
- 最小宿主,逐项回填
- 代理诊断优先,盲补禁止
- 每次补丁都要能追溯到代理日志、first divergence 与页面证据
本仓库默认把“本地补环境”和“外部语言调用”拆成两个阶段:
目标:
- 在 Node 里跑通目标链路
- 找出最小依赖集合
- 确认 first divergence
- 逐步删掉无关宿主和无关补丁
这一阶段的主产物是:
env/env.jsenv/polyfills.jsenv/entry.js
目标:
- 把已经跑通的链路提纯成可调用的完整 JS
- 减少对 Node 特有能力和调试脚手架的依赖
- 为 Python
execjs、quickjs或其他宿主提供稳定函数入口
这一阶段的目标产物通常是:
run/exported-runtime.js- 或其他单文件 / 少量文件的 bundle
关键原则:
- 不要一开始就用
Python + execjs做补环境 - 应该先在 Node 里补环境跑通,再导出可移植 JS
execjs更适合“调用提纯后的函数”,不适合“调试补环境过程”
阶段协议与进入条件见:docs/reference/pure-extraction.md
目标:
- 在 portable runtime 已可用后,继续提纯为可读纯算法
- 明确输入契约、随机/时间因子、固定常量和版本边界
- 为 Node / Python / 其他宿主提供可对齐的固定夹具
这一阶段的目标产物通常是:
run/pure-*.js- 可选
run/pure_*.py - task-local 固定夹具与验收记录
关键原则:
- 只有在
env rebuild跑通且服务端验收通过后,才进入纯算法提纯 - pure runtime 必须支持固定 runtimeContext 或同等控制项,以便跨语言对齐
- 可以保留少量版本绑定常量,但必须在 task artifact 里标出边界
- 纯算法实现仍属于 task-local 产物,不进入
scripts/cases/*或仓库公开实现层
先从浏览器侧拿证据,不要直接在 Node 里猜。
优先记录到 capture.json 的内容:
page.urlpage.titlecookieslocalStoragesessionStorage- 目标请求样本
- Hook 命中的函数名、参数摘要、返回值摘要
- 目标脚本源码或脚本定位信息
这些数据应来自 MCP 页面观察,不允许人工脑补敏感值或宿主状态。
env.js 只负责提供基础宿主对象和最小 shim,让目标脚本可以开始执行。
允许放在 env.js 的内容:
window/self/globaldocument/location/navigatorhistory/screen/canvaslocalStorage/sessionStorageatob/btoa- 最小
crypto外壳
不允许在这里堆站点定制逻辑、访问日志或大段猜测式补丁。
polyfills.js 专门负责代理诊断层。
推荐能力:
watchsafeFunctionmakeFunction- 对
window/document/navigator/storage/location的代理包装 - 统一的
[env:get]/[env:set]/[env:has]/[env:ownKeys]/[env:call]诊断日志
代理诊断层的职责是告诉你:
- 哪个对象路径被访问了
- 缺的是值、函数,还是返回对象
- first divergence 首次出现在什么位置
代理诊断层不是用来直接伪造完整浏览器的。
回填时只允许补当前 first divergence 对应的最小因果单元,而不是机械地一项项打地鼠。
一个补丁决策允许覆盖以下四类最小因果单元:
- 缺基础值:直接补常量,如
navigator.userAgent - 缺函数壳:用
makeFunction("createElement") - 缺返回对象:补最小返回结构,如
document.createElement()的返回对象 - 缺最小对象契约:只补该对象当前链路不可分割的最小接口集,如
localStorage.getItem/setItem/removeItem
这里的“一次补一项”指的是“一次只做一个补丁决策”,而不是“永远只改一个属性名”。
如果代理日志和 first divergence 已经证明当前缺口是同一个最小对象契约,可以一起补完该契约;
如果只是看到多个零散访问,但还没有确认同属一个因果单元,就仍然只补当前最先阻塞执行的那一项。
每次补丁都应该满足:
- 能指出来源于哪条代理日志、哪条
first divergence记录,以及哪条页面证据 - 能说明为什么只补这一项或这一个最小对象契约
- 补完后立刻复测
- 如果没有代理日志或没有
first divergence记录,则不允许补丁
| 观测现象 | 常见缺口类型 | 推荐补法 | 不该做什么 |
|---|---|---|---|
navigator.userAgent、location.href 这类读取返回 undefined |
基础值缺失 | 直接补最小常量值 | 不要顺手补整套 navigator / location 伪实现 |
document.createElement is not a function |
函数壳缺失 | 先用 makeFunction("createElement") 挂函数壳 |
不要直接补完整 DOM 实现 |
Cannot read properties of undefined (reading 'style') 且前一步刚调用了 createElement() |
返回对象结构缺失 | 给该函数补最小返回对象 | 不要把无关字段一并补全 |
localStorage.getItem is not a function |
宿主对象方法缺失 | 补 storage shim 的最小方法集 | 不要引入站点私有缓存值 |
| 同一对象连续出现多个接口缺失,且都指向同一 first divergence | 最小对象契约缺失 | 一次补该对象的最小接口集 | 不要顺手扩成完整浏览器对象 |
Illegal invocation / brand check 失败 |
宿主建模方式错误 | 先修对象形态或 this 绑定,再决定是否补值 | 不要把 brand-sensitive 对象直接套 Proxy 乱包 |
crypto.subtle / TextEncoder 缺失 |
平台 API 缺失 | 补最小平台 API 外壳或 polyfill | 不要臆造算法结果 |
以下做法都属于盲补,不应出现:
- 页面里还没确认依赖来源,就一次性补完整
window/document/navigator/crypto - 看到某个请求需要 Cookie,就手写真实 Cookie 原值进
env.js createElement缺失时,直接复制一整套第三方 DOM 模拟库- 只因为别的站点用过某个字段,就把相同字段硬塞到当前任务里
- 没有 first divergence 记录,只凭“脚本大概会读这个”去补宿主
职责:
- 提供基础宿主
- 提供最小 storage shim
- 提供最小编码/加密壳
禁止:
- 访问日志
- 大量站点定制分支
- 直接内联目标业务脚本
职责:
- 放代理诊断层
- 放可复用的函数伪装能力
- 放“缺函数壳”和“访问日志”的辅助逻辑
禁止:
- 大量业务值硬编码
- 直接替代
env.js作为基础宿主
职责:
- 先加载
env.js - 再加载
polyfills.js - 读
capture.json对应数据 - 加载目标脚本
- 输出 first divergence 和当前可调用状态
- 先跑一次
env/entry.js - 先看本地报错
- 再读代理诊断日志,定位首个异常访问
- 记录并确认当前
first divergence - 回到页面证据确认真实来源
- 只补当前
first divergence对应的最小因果单元 - 必要时再用
diff_env_requirements做辅助比对,而不是替代代理日志 - 立即重跑
env/entry.js
- 不要猜环境
- 不要一次性全量模拟浏览器
- 不要没有页面证据就补 cookie / storage / header / UA
- 不要没有代理日志和
first divergence记录就补宿主 - 不要把
diff_env_requirements当成第一依据,跳过代理日志直接补 - 不要把补环境逻辑直接塞进 MCP 核心运行时
每个任务目录至少应保持以下文件可复用:
env/env.jsenv/polyfills.jsenv/entry.jsenv/capture.json
这四个文件共同构成最小 local rebuild 骨架。
如果后续要给 Python execjs 或其他宿主使用,建议额外导出:
run/exported-runtime.js
如果后续要继续提纯为可读纯算法,建议再补:
run/pure-*.js- 可选
run/pure_*.py - 固定夹具与服务端验收记录
这些文件的目标不是继续调试补环境,而是暴露稳定函数入口并保留可对齐的纯算结果,例如:
genSign(...)getToken(...)buildHeaders(...)genABogus(pathQuery, runtimeContext)