# 通用代码变更记忆机制

本文件用于复杂网页端补环境 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
```

检查未通过时，不要交付最终结果；先补齐记忆记录或说明用户明确豁免。