132 lines
5.1 KiB
Markdown
132 lines
5.1 KiB
Markdown
# 通用代码变更记忆机制
|
||
|
||
本文件用于复杂网页端补环境 case 中的所有关键代码修改，不只适用于浏览器 API。它覆盖 `result/` 源码、`src/env/`、`src/signer/`、`src/request/`、TLS 客户端封装、addon helper、路径处理、异步流程、Cookie 生成、参数生成、入口脚本等任何可能反复修改或回退的工程逻辑。
|
||
|
||
## 目标
|
||
|
||
避免在多轮修复中反复写回旧错误逻辑。每次修改关键源码时，不把“当前报错消失”草率视为无验证范围的固定结论，而是记录：改了什么、为什么改、旧逻辑为什么错、验证了什么、失败方案不能再写回什么、当前验证范围和遗留风险。
|
||
|
||
## 触发条件
|
||
|
||
满足任一条件时必须启用：
|
||
|
||
- case 难度较高、对话多轮、或已经出现同一函数 / 同一文件反复修改。
|
||
- 修改 `case/result/` 下任何最终交付源码。
|
||
- 修改 signer、request、env、addon helper、TLS、路径、异步流程、Cookie 生成等关键逻辑。
|
||
- 为解决报错而替换一段旧逻辑，存在之后又写回旧逻辑的风险。
|
||
- 用户反馈“你又把之前错的逻辑写回去了”或类似问题。
|
||
|
||
## 文件位置
|
||
|
||
默认维护：
|
||
|
||
```text
|
||
case/notes/代码变更记忆.md
|
||
```
|
||
|
||
不存在时先创建。可以用脚本初始化：
|
||
|
||
```bash
|
||
node scripts/check_change_memory.js --case-dir case --init --markdown
|
||
```
|
||
|
||
## 修改前必须做
|
||
|
||
1. 读取 `case/notes/代码变更记忆.md`。
|
||
2. 搜索本次准备修改的文件名、函数名、类名、参数名、错误关键词和相关模块名。
|
||
3. 如果记忆中存在“禁止回退”或“已失败尝试”，先确认本次修改不会写回这些内容。
|
||
4. 如果确实需要覆盖历史结论，必须在新记录中写明新的证据，而不是直接删除旧记录。
|
||
|
||
## 修改后必须做
|
||
|
||
每次关键源码修改后立即追加一条记录。不要等最终总结时再补写。
|
||
|
||
### 记录模板
|
||
|
||
```md
|
||
## 变更 001 - 简短标题
|
||
|
||
- 时间：YYYY-MM-DD HH:mm
|
||
- 涉及文件：result/src/env/install-env.js；result/src/signer/index.js
|
||
- 涉及函数 / 模块：installNavigator；buildSign
|
||
- 当前状态：临时修复 / 当前验证通过 / 已失败 / 被替代 / 稳定基线
|
||
|
||
### 修改前逻辑
|
||
|
||
简述旧代码做了什么，不要只写“旧逻辑错误”。
|
||
|
||
### 问题证据
|
||
|
||
记录触发错误的命令、堆栈、fixture 差异、日志、RuyiTrace 证据、接口响应或用户反馈。
|
||
|
||
### 本次修改
|
||
|
||
说明实际改了哪些代码、哪些文件、哪些函数，不要只写“优化了”。
|
||
|
||
### 修改理由
|
||
|
||
解释为什么选择这次改法。只能把“当前验证通过”写成当前状态，不能写成永久正确。
|
||
|
||
### 已失败尝试
|
||
|
||
列出已经证明失败或不可靠的方案，包括失败原因。
|
||
|
||
### 禁止回退
|
||
|
||
明确以后不要写回什么，例如“不要再把 userAgent 改成实例 data descriptor；除非有新浏览器样本证明该站点只检测实例属性”。
|
||
|
||
### 验证命令
|
||
|
||
```bash
|
||
node result/final.js
|
||
node scripts/compare_fixture.js --fixture case/fixtures/sample.fixture.json --actual case/tmp/node-output.json --field sign --markdown
|
||
```
|
||
|
||
### 验证结果
|
||
|
||
记录通过 / 失败、输出摘要、关键字段差异。
|
||
|
||
### 当前验证范围
|
||
|
||
说明只验证了哪些 fixture、哪些接口、哪些运行环境、哪些 Node 版本或 TLS 客户端。
|
||
|
||
### 遗留风险
|
||
|
||
记录尚未覆盖的检测点、样本不足、环境差异、登录态限制等。
|
||
```
|
||
|
||
## 状态定义
|
||
|
||
| 状态 | 含义 |
|
||
|---|---|
|
||
| 临时修复 | 只解决当前报错或部分样本，不能作为稳定基线 |
|
||
| 当前验证通过 | 已通过当前列出的验证范围，但仍可能被新检测推翻 |
|
||
| 已失败 | 明确失败，后续不得无证据写回 |
|
||
| 被替代 | 旧方案被新方案替换，保留原因和替代依据 |
|
||
| 稳定基线 | 经多组样本、最终入口和请求验证通过，仍需记录验证范围 |
|
||
|
||
## 重要原则
|
||
|
||
- 不使用无验证范围的绝对结论；使用“当前验证通过”“稳定基线”等有范围的状态。
|
||
- 不删除失败记录；失败记录是防止回退的证据。
|
||
- 不把当前报错消失等同于真实浏览器一致。
|
||
- 不把浏览器 API 规则写死成全局真理；同一 API 的放置位置、描述符和行为必须以目标浏览器样本、RuyiTrace、fixture 和检测证据为准。
|
||
- 对与补环境无关的工程错误同样记录，例如路径拼接、异步顺序、请求重试、JSON 序列化、TLS 客户端参数、模块导出等。
|
||
- 如果修改涉及安全边界、请求次数、登录态或敏感数据，必须在遗留风险中说明授权范围。
|
||
|
||
## 交付前检查
|
||
|
||
交付前至少运行：
|
||
|
||
```bash
|
||
node scripts/check_change_memory.js --case-dir case --markdown
|
||
```
|
||
|
||
如果本轮修改过关键源码，还要按文件检查：
|
||
|
||
```bash
|
||
node scripts/check_change_memory.js --case-dir case --changed result/src/env/install-env.js --require-entry --markdown
|
||
```
|
||
|
||
检查未通过时，不要交付最终结果；先补齐记忆记录或说明用户明确豁免。
|