4.6 KiB
4.6 KiB
补环境分层与模块资产
本文件用于把补环境从“一坨 env.js”拆成可验证、可替换、可复用的模块。
Level 1 / 2 / 3 分层
| 层级 | 目标 | 常见模块 | 进入条件 | 交付要求 |
|---|---|---|---|---|
| Level 1 基础运行层 | 让目标 JS 在隔离 Node.js 运行上下文中安全加载并可调用入口 | window/self/globalThis、location、URLSearchParams、atob/btoa、TextEncoder、Date、console、setTimeout、Storage | 已有入口和 fixtures | 不暴露 Node；能记录缺失环境 |
| Level 2 指纹与对象真实性层 | 让环境更接近浏览器并通过常见检测 | navigator、screen、document、plugins、mimeTypes、crypto、performance、Canvas/WebGL/WebGPU/Audio/字体/DOM 几何值回放、属性描述符、原型链、toString | Level 1 能运行但输出不一致或出现检测 | 有 descriptor/accessor/prototype/native-like/Object.prototype.toString 记录；指纹终端 API 有真实采样值 |
| Level 3 目标 SDK 专用层 | 针对具体站点 SDK 的初始化、缓存、消息和异步行为 | SDK init、动态 chunk、Worker、WASM、postMessage、IndexedDB 摘要、请求封装 | 已确认目标 SDK 依赖 | 写入 notes，避免污染通用 env |
模块选择矩阵
| trace / 错误信号 | 优先模块 | 备注 |
|---|---|---|
ReferenceError: window / self |
base-env | 先建立全局别名 |
location.href/origin/pathname |
location-env | 由 fixture.pageUrl/apiUrl 生成 |
navigator.userAgent/language/platform |
navigator-env | 使用浏览器真实样本 |
document.cookie |
document-cookie-env | 敏感值脱敏记录 |
localStorage.getItem |
storage-env | 从 fixture 注入 key/value |
crypto.getRandomValues |
crypto-env | 需要固定随机源 |
performance.now |
time-env | 与 Date.now 联动 |
canvas/WebGL/WebGPU/Audio/字体/DOM 几何 |
fingerprint-env | 回放真实浏览器终端 API 返回值，不在 Node.js 中真实模拟渲染 |
Object.getOwnPropertyDescriptor |
descriptor-env / native-protect | 检查 enumerable/configurable/writable，区分 data descriptor 与 accessor descriptor |
Function.prototype.toString |
native-protect / native-addon | 普通函数、构造函数、getter、setter 都要保护 |
document.all |
native-addon | JS 难以完全模拟，优先 addon |
Worker/postMessage/WASM |
worker-wasm-env | 单独建消息链 |
推荐目录
case/
├── env/
│ ├── base-env.js
│ ├── navigator-env.js
│ ├── document-env.js
│ ├── storage-env.js
│ ├── crypto-time-env.js
│ ├── native-protect.js
│ └── target-sdk-env.js
├── result/
│ ├── final.js # 唯一执行入口；也可在用户选择 Python 请求客户端时为 final.py
│ └── src/ # 最终项目模块：env、signer、request、utils 等
└── notes/
├── entry-chain.md
├── missing-env-priority.md
└── silent-failure-checklist.md
Skill 自带模板位于 assets/env-modules/，使用前应复制到 case 中按目标调整，不要直接改 Skill 内模板。当前模板包括 native-protect.js、base-env.js、storage-env.js、document-env.js、fingerprint-env.js。
固化规则
- 探测阶段可以用 Proxy；交付阶段逐步替换为真实对象。
- 每补一个模块，只解决 trace 中实际出现的路径，避免大而全。
- 每轮补齐后跑 fixtures，对比目标参数，不以“不报错”为完成。
- 通用模块和目标 SDK 专用模块分开，避免把站点私有逻辑写进通用 env。
- 敏感 Cookie、token、localStorage 值只放在本地 fixture，不写入总结原文。
- 最终交付前运行
check_env_realism.js，确认原型链、属性描述符、访问器、函数 / 访问器 / 实例对象 toString 保护、document.all特殊对象处理和指纹值回放均有证据；涉及指纹时再运行check_fingerprint_fixture.js。 - 最终交付时，允许把已验证模块规范整理到
result/src/，但只能由result/final.js或result/final.py作为唯一入口串联调用；不要把测试脚本、临时 runner 或第二入口留在最终产物目录。
模块笔记模板
## 环境模块补齐记录
| 模块 | 触发证据 | 补齐内容 | 真实性处理 | 验证结果 |
|---|---|---|---|---|
| base-env | ReferenceError: window | window/self/globalThis | descriptor 已记录 | 通过加载 |
| storage-env | localStorage.getItem | 注入 key 列表 | Storage 原型待补 | sign 仍不一致 |