reverse-skills-max/vendor-new/xbsReverseSkill/web-reverse-env/references/02-module-contracts.md

模块输入输出契约

这份文档定义 future skill 每个核心模块的输入 / 输出边界，避免后续脚本和文档互相耦合。

1. 通用约定

所有模块尽量遵循同一套输入 / 输出字段。

输入

• target
  • 当前要补的对象名或模块名
• seed
  • 真实浏览器采集到的种子数据
• runtime
  • 当前 Node / jsdom / vm 里的运行时对象
• diagnostics
  • Proxy 吐环境日志、异常日志、堆栈、缺口清单
• options
  • 开关项，如 protectNative、strictDescriptor、logOpen

输出

• patchPlan
  • 本模块准备补哪些点
• patchCode
  • 可执行补丁代码或代码片段
• runtimeState
  • 补丁后应写入的运行态
• validation
  • 本模块对应的检查点
• residualRisk
  • 当前模块仍无法完全脚本化处理的风险

2. prototype-builder

输入

• target
• prototypeChainSnapshot
• instanceShapeSnapshot
• constructorMeta

输出

• patchPlan
  • 构造函数
  • 原型链
  • 实例创建
  • 全局挂载
• patchCode
  • 构造函数定义代码
  • Object.setPrototypeOf / defineProperty 代码
• validation
  • instanceof
  • Object.getPrototypeOf
  • constructor === Xxx

3. native-protector

输入

• functions
• getters
• setters
• expectedNativeStrings
• metaOverrides

输出

• patchPlan
  • 哪些函数要保护
  • 哪些 getter / setter 要保护
  • 是否启用 toString.toString 防护
• patchCode
  • Function.prototype.toString 接管代码
  • 每个函数的 native 保护代码
• validation
  • fn.toString()
  • fn.toString.toString()
  • fn.name
  • fn.length

4. descriptor-guard

输入

• target
• propertyDescriptors
• symbolTags
• constructorStrategy

输出

• patchPlan
  • 哪些属性用数据描述符
  • 哪些属性用访问器描述符
• patchCode
  • defineProperty / defineProperties
• validation
  • getOwnPropertyDescriptor
  • propertyIsEnumerable
  • ownKeys

5. navigator-module

输入

• seed.navigator
• seed.plugins
• seed.mimeTypes
• seed.userAgentData
• diagnostics.navigator

输出

• patchPlan
  • basic
  • plugin graph
  • async capability
  • automation flags
• patchCode
  • Navigator.prototype getter / method
  • plugins/mimeTypes 图结构构建
• runtimeState
  • navigator 实例值
• validation
  • webdriver
  • plugins.length
  • mimeTypes.length
  • getBattery
  • userAgentData

6. document-module

输入

• seed.document
• seed.cookie
• diagnostics.document
• specialCases.documentAll

输出

• patchPlan
  • basic document
  • cookie accessor
  • query API
  • special object
• patchCode
  • Document.prototype / HTMLDocument.prototype
  • document.cookie getter / setter
• validation
  • document.URL
  • document.readyState
  • document.cookie
  • document.all
• residualRisk
  • 若无底层支持，明确标记 document.all 为特殊风险

7. storage-module

输入

• seed.localStorage
• seed.sessionStorage
• seed.cookies
• diagnostics.storage

输出

• patchPlan
  • shape
  • state
  • cookie linkage
• patchCode
  • Storage.prototype
  • state merge logic
• runtimeState
  • 预置 key/value
• validation
  • length
  • getItem
  • setItem
  • removeItem
  • clear

8. fingerprint-module

输入

• seed.fingerprint
• seed.screen
• seed.navigator
• diagnostics.fingerprint

输出

• patchPlan
  • canvas
  • webgl
  • battery
  • screen
• patchCode
  • toDataURL
  • getContext
  • getParameter
  • getBattery
• runtimeState
  • 指纹种子池
• validation
  • canvas 输出
  • WebGL vendor / renderer
  • battery 值
  • screen / window 尺寸一致性

9. performance-module

输入

• seed.performance
• seed.windowMetrics
• diagnostics.performance

输出

• patchPlan
  • performance.now
  • performance.timeOrigin
  • performance.timing
  • 时间一致性修正
• patchCode
  • performance 对象与 timing 结构
• validation
  • performance.now()
  • performance.timeOrigin
  • performance.timing.navigationStart
  • 各 timing 字段前后顺序关系

10. crypto-module

输入

• seed.crypto
• diagnostics.crypto
• typedArraySupport

输出

• patchPlan
  • window.crypto
  • window.msCrypto
  • getRandomValues
  • subtle
• patchCode
  • getRandomValues 实现
  • typed array 校验与异常逻辑
• validation
  • Uint8Array
  • Uint16Array
  • Uint32Array
  • 长度超限异常

11. webrtc-module

输入

• seed.webrtc
• diagnostics.webrtc
• networkPolicy

输出

• patchPlan
  • RTCPeerConnection
  • RTCRtpSender
  • RTCRtpReceiver
  • RTCDataChannel
  • ICE candidate 路径
• patchCode
  • 构造函数与方法补丁
  • createOffer
  • createDataChannel
  • onicecandidate
• validation
  • 构造函数存在性
  • createOffer()
  • createDataChannel()
  • 是否泄露本地候选信息

12. audio-fingerprint-module

输入

• seed.audio
• diagnostics.audio

输出

• patchPlan
  • AudioContext
  • OfflineAudioContext
  • AudioBuffer
  • getChannelData
• patchCode
  • 构造函数
  • 音频缓冲返回值
  • 常见指纹链路模拟
• validation
  • new AudioContext()
  • new OfflineAudioContext()
  • getChannelData()
  • 是否满足基础音频指纹调用流程

13. worker-module

输入

• seed.worker
• diagnostics.worker
• messagePolicy

输出

• patchPlan
  • Worker
  • SharedWorker
  • postMessage
  • MessagePort
  • BroadcastChannel
• patchCode
  • 构造函数
  • 端口通信对象
  • message 事件
• validation
  • new Worker()
  • new SharedWorker()
  • postMessage
  • onmessage

14. math-precision-module

输入

• seed.math
• diagnostics.math
• baselineResults

输出

• patchPlan
  • 高风险数学函数差异校验
  • 浏览器 / Node 结果对照
• patchCode
  • 精度修正策略
  • 或风险标注代码
• validation
  • 与基线结果比对
  • 是否命中已知高风险函数

15. proxy-observer

输入

• targets
• logConfig
• skipRules
• maxDepth

输出

• patchCode
  • Proxy 包装代码
• diagnostics
  • missingPaths
  • descriptorAccess
  • prototypeAccess
  • invocationErrors
• validation
  • 是否成功捕获 get/set/has/apply/construct

16. stack-clean-module

输入

• runtimeError
• stackRules
• scriptName

输出

• patchCode
  • 栈清洗函数
• validation
  • 清洗前后栈帧差异
• residualRisk
  • 说明是否需要底层 runtime 配合

17. document-all-module

输入

• mode
  • native-addon
  • v8-api
  • fallback
• diagnostics.documentAll

输出

• patchPlan
  • 选择的实现路线
• patchCode
  • 若有底层支持，输出接线代码
  • 若无底层支持，输出降级兼容代码
• validation
  • == undefined
  • === undefined
  • typeof
  • 调用行为
• residualRisk
  • 清楚声明纯 JS 限制

18. 模块依赖关系

执行顺序建议：

1. prototype-builder
2. descriptor-guard
3. native-protector
4. 浏览器对象模块
5. performance-module
6. crypto-module
7. fingerprint-module
8. audio-fingerprint-module
9. webrtc-module
10. worker-module
11. proxy-observer
12. math-precision-module
13. stack-clean-module
14. document-all-module

如果站点在早期就卡死在 document.all，可以把最后一步提前。