231 lines
14 KiB
Markdown
231 lines
14 KiB
Markdown
# 补环境代码可读性与中文注释规范
|
||
|
||
每次生成、重构或交付 `case/result/` 中的补环境代码前读取本文件。目标是让最终代码 **简洁、可读、可维护、中文注释正常显示**，并避免生成压缩、堆叠、无注释或乱码代码。
|
||
|
||
## 硬性原则
|
||
|
||
1. **先规划目录，再写代码**
|
||
写代码前先列出最终目录、每个文件职责和调用关系。不要边写边临时堆文件。
|
||
|
||
2. **按职责拆模块**
|
||
不要把所有补环境逻辑塞进一个 `env.js`。推荐结构：
|
||
|
||
```text
|
||
case/result/
|
||
├── final.js
|
||
├── 最终项目总结.md
|
||
└── src/
|
||
├── env/
|
||
│ ├── install-env.js
|
||
│ ├── native-api.js
|
||
│ ├── manifest.js
|
||
│ ├── core/
|
||
│ │ ├── descriptors.js
|
||
│ │ └── cookie-store.js
|
||
│ ├── browser-objects/
|
||
│ │ ├── window.js
|
||
│ │ ├── navigator.js
|
||
│ │ ├── document.js
|
||
│ │ ├── location.js
|
||
│ │ ├── screen.js
|
||
│ │ ├── xhr.js
|
||
│ │ └── storage.js
|
||
│ └── fingerprint/
|
||
│ ├── canvas.js
|
||
│ ├── webgl.js
|
||
│ └── dom-geometry.js
|
||
├── target/
|
||
│ └── entry.js
|
||
├── request/
|
||
│ └── client.js
|
||
└── utils/
|
||
└── normalize.js
|
||
```
|
||
|
||
如果需要 Node 诊断执行器、runtime probe 或 Akamai / Shape / F5 等高强度检测的本地执行器，应继续拆成下列职责，而不是把所有 WebAPI 放进 `src/signer/*probe*.js`：
|
||
|
||
```text
|
||
case/result/src/
|
||
├── signer/
|
||
│ ├── runtime_signer.py
|
||
│ └── akamai_runtime_probe.js # 只做入口和编排，建议少于 150 行
|
||
└── node-runtime/
|
||
├── bootstrap/
|
||
│ ├── read-stdin.js
|
||
│ ├── execute-script.js
|
||
│ └── result-recorder.js
|
||
├── utils/
|
||
│ ├── hash.js
|
||
│ ├── sanitize-url.js
|
||
│ └── body-summary.js
|
||
└── env/
|
||
├── install-env.js
|
||
├── native-api.js
|
||
├── node-leakage.js
|
||
├── browser-objects/
|
||
│ ├── window.js
|
||
│ ├── navigator.js
|
||
│ ├── document.js
|
||
│ ├── location.js
|
||
│ ├── history.js
|
||
│ ├── screen.js
|
||
│ ├── storage.js
|
||
│ ├── performance.js
|
||
│ └── events.js
|
||
├── fingerprint/
|
||
│ ├── canvas.js
|
||
│ ├── webgl.js
|
||
│ ├── audio.js
|
||
│ └── dom-geometry.js
|
||
└── network/
|
||
├── xhr.js
|
||
├── fetch.js
|
||
└── beacon.js
|
||
```
|
||
|
||
3. **signer / probe 不得承载补环境主体**
|
||
`src/signer/`、`src/request/`、`src/resources/`、`runtime_probe.js`、`probe.js`、`runner.js`、`diagnostic.js` 等文件只允许做编排、进程入口、请求封装、资源刷新或安全摘要输出；只要文件内实现了 `navigator`、`document`、`window`、`screen`、`Storage`、`XMLHttpRequest`、`fetch`、`Canvas`、`WebGL`、`Audio`、`performance`、DOM 构造链、事件系统等浏览器 WebAPI 主体，就必须拆入 `src/env/` 或 `src/node-runtime/env/` 下的真实模块。不得因为文件名叫 probe、runtime、signer 或 diagnostic 就豁免模块化要求。
|
||
|
||
4. **补环境代码必须可读**
|
||
禁止压缩代码、单行堆叠多个语句、过度匿名函数、无意义变量名、超长函数和超深嵌套。原始目标 bundle 如必须保留，应放到 `src/target/original/` 或等价目录，并与手写补环境代码分离。
|
||
|
||
5. **中文注释必须正常显示**
|
||
所有交付源码使用 UTF-8 无 BOM。不要使用未指定编码的 PowerShell / cmd 重定向写中文源码。中文注释中不得出现问号、连续问号或替换字符。
|
||
|
||
6. **WebAPI 实现必须可审计**
|
||
补环境源码不得把 WebAPI 写成无法审查的一行堆叠代码。禁止一行连续堆多个 `Object.defineProperty`、`Object.defineProperties`、`Object.assign`、函数定义或对象字面量方法。`install-env.js` 只负责装配，不应成为巨型文件；`navigator`、`screen`、`document`、`storage`、`indexedDB`、`canvas`、`webgl`、`events`、`worker`、`request` 等应按职责拆模块。
|
||
|
||
7. **普通 WebAPI 函数必须 addon-first**
|
||
不要在 WebAPI 主路径中直接写 `ctx.Blob = function(){}`、`ctx.indexedDB = { open() {} }`、`prototype = { getContext() {} }` 或 `ctx.URL.createObjectURL = function(){}`。普通函数也要提取为具名函数，并通过 addon-first helper 包装后再安装 descriptor。addon 不可用时才用 `NativeProtect` / JS fallback，并在注释与阶段报告中说明原因。
|
||
|
||
8. **浏览器对象私有状态不得泄露**
|
||
不要在浏览器可见对象上写 `this.__readyState`、`this._headers`、`__children`、`__parentNode`、`__responseHeaders`、`_store` 等内部字段。non-enumerable 也会被 `Object.getOwnPropertyNames`、`Reflect.ownKeys` 和 descriptor 检测到。内部状态优先使用 addon / xbs private API，其次使用模块级 `WeakMap`；XHR、fetch、Headers、Response、DOM 节点、EventTarget、Storage、Performance 等都适用。
|
||
|
||
9. **XHR/fetch 必须拆为网络环境模块并桥接 Session**
|
||
`XMLHttpRequest` / `fetch` / `Request` / `Response` / `Headers` / `sendBeacon` 的浏览器语义放在 `src/env/network/` 或 `src/node-runtime/env/network/`。需要真实请求时，网络模块只能调用 live session bridge；不得在 env 里直接调用 Node 宿主 `fetch`、`http`、`https`、`axios`、`undici`。fixture/default response 只能保留为 `offline-fixture` 诊断模式。
|
||
|
||
10. **构造函数错误必须可追溯**
|
||
构造函数的报错类型和 message 必须来自目标浏览器采样。不要写泛化 `throw new TypeError('Illegal constructor')`；需要在注释、fixture 或阶段报告中说明该错误来自哪个浏览器、哪个调用方式。
|
||
|
||
11. **addon 实例不再二次标记对象类型**
|
||
`markObjectType` 不是批准 API。addon 构造函数 / `createProtoChains` 实例工厂创建出的实例本身应已处理 `Object.prototype.toString`；只有 JS fallback 普通对象才允许 `markObjectToString` / `Symbol.toStringTag`，并必须写明 fallback 原因。
|
||
|
||
12. **注释说明“为什么”和“来源”**
|
||
注释不是逐行翻译代码，而是说明模块职责、浏览器样本来源、RuyiTrace 证据、fixture 匹配规则、addon-first 决策和 fallback 原因。
|
||
|
||
13. **isolated-vm 也必须文件化模块交付**
|
||
isolated-vm 底层确实需要把源码字符串交给 V8，但最终项目不得把补环境源码写成大段 `String.raw`、`CORE_SCRIPT`、`BROWSER_OBJECTS_SCRIPT`、`*_SCRIPT` 聚合字符串。正确做法是把 `navigator.js`、`document.js`、`window.js`、`canvas.js`、`webgl.js` 等作为真实源码文件保存，由宿主侧 runtime 使用 `fs.readFileSync` 读取，再通过 `compileScriptSync(source, { filename })` 或等价方法注入同一个 isolated-vm Context。只有少量 bootstrap 片段允许字符串形式，且必须少于 40 行、不能承载主要 WebAPI 实现，并写明原因。
|
||
|
||
## 中文注释要求
|
||
|
||
必须写中文注释的位置：
|
||
|
||
- 文件顶部：说明模块职责、输入来源和边界。
|
||
- 每个环境对象模块：说明模拟哪个浏览器对象。
|
||
- 关键 getter / setter：说明真实值来自 fixture、RuyiTrace、请求样本还是用户配置。
|
||
- native-like 函数和构造函数：说明挂载位置、浏览器行为和 addon-first 处理。
|
||
- fallback 分支：说明 addon 不可用、ABI 不兼容、API 调用失败或用户明确豁免的原因。
|
||
- 指纹值回放函数：说明匹配 key、采样来源和缺失样本时的处理。
|
||
- 加密参数生成入口：说明输入、输出和 fixtures 验证方式。
|
||
|
||
禁止：
|
||
|
||
```js
|
||
// 不合格：用问句解释实现
|
||
// 不合格：连续问号乱码示例
|
||
// 临时先这样
|
||
```
|
||
|
||
推荐：
|
||
|
||
```js
|
||
// 安装 Navigator 相关环境对象，字段值来自浏览器 fixture
|
||
function installNavigatorEnv(globalObject, fixture, nativeApi) {
|
||
// Navigator 构造函数错误信息来自 constructor-errors.fixture.json 中的浏览器采样
|
||
const Navigator = nativeApi.createNativeConstructor('Navigator', 0, function Navigator(isNew) {
|
||
if (isNew) {
|
||
return nativeApi.throwIllegalConstructor('Navigator');
|
||
}
|
||
return nativeApi.throwIllegalConstructor('Navigator');
|
||
});
|
||
|
||
// userAgent 使用真实浏览器采样值，不在 Node.js 中伪造默认值
|
||
nativeApi.defineNativeGetter(Navigator.prototype, 'userAgent', function getUserAgent() {
|
||
return fixture.browser.userAgent;
|
||
});
|
||
}
|
||
```
|
||
|
||
## 命名与函数拆分
|
||
|
||
- 函数名使用业务含义，例如 `installNavigatorEnv`、`createStorageArea`、`replayCanvasToDataURL`。
|
||
- 避免 `a`、`b`、`fn1`、`tmp`、`xxx` 作为长期变量名。
|
||
- 单函数建议不超过 90 行。
|
||
- 单文件建议不超过 500 行。
|
||
- 单行建议不超过 180 字符。
|
||
- 属性描述符、构造函数 callback、WebAPI 方法安装、`Object.assign`、`try/catch` 较长逻辑不得压成一行。
|
||
- 嵌套层级尽量不超过 6 层；复杂逻辑用提前返回或拆函数。
|
||
|
||
## isolated-vm 文件化加载示例
|
||
|
||
推荐由 `install-env.js` 只负责装配，由 runtime 顺序读取文件：
|
||
|
||
```js
|
||
const ENV_FILES = [
|
||
'src/env/core/descriptors.js',
|
||
'src/env/browser-objects/window.js',
|
||
'src/env/browser-objects/navigator.js',
|
||
'src/env/browser-objects/document.js',
|
||
'src/env/fingerprint/canvas.js',
|
||
'src/env/fingerprint/webgl.js',
|
||
];
|
||
|
||
function installEnv(runtime, config) {
|
||
runtime.setCopy('__ENV_CONFIG__', config);
|
||
runtime.runFiles(ENV_FILES);
|
||
runtime.runFile('src/env/install-all.js');
|
||
}
|
||
```
|
||
|
||
每个文件都应是正常 JavaScript 文件，文件顶部用中文说明模块职责。Context 内不需要也不应该直接 `require('./navigator.js')`；由宿主 runtime 读取文件内容后注入，既保持 isolated-vm 隔离，又保留源码文件结构、中文注释和 filename 栈定位。
|
||
|
||
## 最终交付前检查
|
||
|
||
交付前必须运行：
|
||
|
||
```bash
|
||
node scripts/check_code_quality.js --case-dir case --markdown
|
||
node scripts/check_object_shape_audit.js --case-dir case --markdown
|
||
node scripts/check_xhr_fetch_session_bridge.js --case-dir case --markdown
|
||
node scripts/check_trace_runtime_conformance.js --case-dir case --markdown
|
||
node scripts/check_xhr_fetch_semantics.js --case-dir case --require --require-no-send --out case/tmp/xhr-fetch-semantics-audit.json --markdown
|
||
node scripts/check_environment_closure.js --case-dir case --before-real-request --markdown
|
||
node scripts/check_webapi_addon_coverage.js --case-dir case --markdown
|
||
node scripts/check_env_realism.js --case-dir case --markdown
|
||
node scripts/check_final_artifact.js --case-dir case --markdown
|
||
```
|
||
|
||
如果 `check_code_quality.js` 或 `check_webapi_addon_coverage.js` 失败，必须立即停止后续补环境验证、真实请求验证和交付；先重构代码、拆分 signer/probe 中的 WebAPI 主体、修复中文注释、编码问题、普通 WebAPI 函数、普通对象和宿主透传，再重新运行检查。不得以“当前请求能跑通”“只是诊断脚本”“只是 probe”为理由跳过失败项。
|
||
|
||
## 常见修复方式
|
||
|
||
| 问题 | 修复方式 |
|
||
|---|---|
|
||
| 单个 `env.js` 太大 | 按 navigator、document、storage、fingerprint 拆模块 |
|
||
| isolated-vm 生成大段 `String.raw` | 改为真实 `.js` 文件，由 runtime.runFile / runtime.runFiles 读取后注入 Context |
|
||
| `script-browser-objects.js` / `script-core.js` 承载主要补环境 | 拆成 `browser-objects/navigator.js`、`document.js`、`window.js`、`fingerprint/canvas.js` 等模块 |
|
||
| 没有中文注释 | 增加文件头、对象说明、来源说明和 fallback 原因 |
|
||
| 中文注释有问号或乱码 | 用 UTF-8 重新写入，避免默认 shell 重定向 |
|
||
| 函数过长 | 拆成解析 fixture、创建构造函数、安装属性、安装实例四步 |
|
||
| 普通赋值太多 | 改为统一 helper，例如 `defineValue`、`defineNativeGetter` |
|
||
| 普通 WebAPI 函数 | 提取具名 callback，用 `addon.createNativeFunction` 或 addon-first helper 包装 |
|
||
| 普通 WebAPI 对象 | 用 `createProtoChains` 建立构造函数、prototype 和实例工厂，再安装 descriptor |
|
||
| 泛化 `Illegal constructor` | 先采样浏览器错误类型和 message，再用 `throwBrowserTypeError` / `throwIllegalConstructor` 等 helper 复现 |
|
||
| `markObjectType` | 删除该调用；addon 实例不需要二次标记，JS fallback 才用 `markObjectToString` 并记录原因 |
|
||
| `prototype = {}` | 改为 `createProtoChains` 或 `Object.defineProperties`，保留 `constructor` 和 `Symbol.toStringTag` |
|
||
| 直接复用宿主 Web API | 按浏览器样本和目标调用范围重建可控实现，不盲目透传 Node 宿主对象 |
|
||
| `this.__readyState` / `_headers` / `_store` | 改用 addon / xbs private API 或模块级 WeakMap |
|
||
| XHR/fetch 返回默认 200 / fixture | 标为 offline-fixture；真实请求时改为 live session bridge |
|
||
| Python curl_cffi 最终请求但 Node XHR 自己发请求 | 改为 final.py 持有同一 Session，Node 通过 IPC 请求 Python 发送 |
|
||
| target bundle 混入手写代码 | 原始 bundle 放 `src/target/original/`，入口包装放 `src/target/entry.js` |
|