reverse-skills-max: initial public release (restored, redacted, hardened)

vendor-new/xbsReverseSkill/web-js-env-patcher/references/cleanup.md

@@ -0,0 +1,145 @@
+# 临时产物清理规范
+
+当创建临时文件、测试文件、浏览器产物、缓存文件、中间产物或 case 目录时，使用本文件约束清理行为。
+
+## 总原则
+
+- **测试完成立即清理**：每次脚本测试、功能验证、浏览器取证小步骤完成后，第一时间清理本步骤产生的测试文件、临时文件、缓存文件、中间产物和空目录，不要等整个项目结束。
+- **产物先沉淀再删除**：删除前先把有价值结论写入 `notes/`、`result/` 或最终报告；确认无价值的原始临时文件再清理。
+- **临时内容集中存放**：测试文件必须放入系统临时目录或 `case/tmp/` / `case/.tmp/` / `case/cache/` 等可清理目录；不要把 throwaway 文件散落在项目根目录。
+- **脚本测试使用 finally**：编写测试命令时使用 `try/finally` 或等价逻辑，确保失败时也删除临时目录。
+- **每次交付前复查**：最终回复用户前，必须执行一次清理 dry-run 或说明未执行原因；若 dry-run 发现普通临时产物，应立即 `--force` 清理并再次 dry-run。最终交付还必须运行 `check_env_realism.js` 和 `check_final_artifact.js`，确认补环境真实性 / RuyiTrace 证据完整，且 `result/` 是规范项目目录、只有一个执行入口、没有多余测试文件、临时文件或自动化代码。
+- **敏感材料例外**：登录态 Profile、Cookie、localStorage、IndexedDB、Authorization 等敏感材料不自动删除或交付；删除前必须确认用户意图。
+
+## 目录约定
+
+建议 case 结构：
+
+```text
+case/
+├── js/
+│   ├── original/
+│   ├── pretty/
+│   └── extracted/
+├── requests/
+├── fixtures/
+├── notes/
+└── tmp/
+```
+
+默认 `tmp/`、`.tmp/`、`temp/`、`.temp/`、`cache/`、`.cache/`、`browser-temp/`、`downloads/failed/`、`__pycache__/`、`.pytest_cache/` 等都是可清理目录。最终产物应尽量简洁，只保留必要内容。
+
+最终 `result/` 目录应是规范项目目录，可以包含必要源码模块和配置模板，但只能有一个执行入口：
+
+```text
+result/
+├── final.js
+├── package.json
+├── config.example.json
+└── src/
+```
+
+或用户明确选择 Python 请求客户端时：
+
+```text
+result/
+├── final.py
+├── requirements.txt
+├── config.example.json
+└── src/
+```
+
+不要把临时 runner、测试脚本、trace、HAR、hook、截图、浏览器 Profile、`server.js`、`bridge.py` 留在最终交付目录。`env`、`signer`、`request` 等代码可以作为 `src/` 下的被调用模块保留，但不得成为第二执行入口。
+
+## 应清理的临时文件
+
+| 类型 | 清理时机 |
+|---|---|
+| 测试用输入 / 输出文件 | 单个测试命令完成后立即清理 |
+| 失败的 JS 下载文件 | JS 文件收集阶段结束后立即清理 |
+| 临时格式化文件 | 正式 pretty 文件生成后立即清理 |
+| hook 脚本 / 指纹采样 Hook | 调用栈或指纹终端 API 返回值确认并沉淀到 notes / fixtures 后立即清理 |
+| 临时 trace / JSONL / 调试日志 | 关键结论写入 notes 后立即清理 |
+| 临时 runner / scratch 脚本 | 正式 runner 生成或测试完成后立即清理 |
+| 重复样本副本 | fixtures 整理完成后立即清理 |
+| cache / `.cache` / `__pycache__` / `.pytest_cache` | 对应测试或脚本执行后立即清理 |
+| 空文件 / 空目录 | 每个测试或阶段结束时立即清理 |
+| 无登录态浏览器 Profile | 浏览器取证阶段结束后清理 |
+
+## 敏感文件
+
+以下文件按敏感材料处理：
+
+- 包含登录态的浏览器 Profile。
+- Cookie / localStorage / sessionStorage 导出。
+- Authorization 请求头。
+- 含真实 Cookie 或账号标识的 HAR。
+- 包含隐私账号信息的截图。
+
+默认不要把这些内容放入最终交付物，除非用户明确要求。优先做脱敏处理。
+
+## 清理检查表
+
+```markdown
+## 清理检查
+
+- [ ] 本次测试是否使用系统临时目录或 `case/tmp/`？
+- [ ] 单个测试完成后是否立即清理测试文件？
+- [ ] 是否删除临时失败下载文件？
+- [ ] 是否删除临时 hook 脚本？
+- [ ] 是否删除指纹采样 Hook，且只保留必要 fingerprint fixture？
+- [ ] 是否删除无用日志？
+- [ ] 是否删除缓存目录和中间产物？
+- [ ] 是否删除空目录？
+- [ ] 是否只保留必要请求样本？
+- [ ] 是否只保留必要 JS 文件？
+- [ ] 是否已将关键结论写入 notes？
+- [ ] 是否确认登录态 Profile 的处理方式？
+- [ ] 是否避免 Cookie / token 明文进入最终报告？
+- [ ] `result/` 是否是规范项目目录，且只有 `final.js` 或 `final.py` 一个执行入口？
+- [ ] 最终项目所有源码是否不包含 ruyiPage / Playwright / Puppeteer / Selenium / CloakBrowser 等自动化代码？
+- [ ] 最终请求是否由 Node.js / Python HTTP 客户端实现？
+- [ ] 是否已运行 `check_env_realism.js` 检查补环境真实性和 RuyiTrace 证据？
+- [ ] 是否已运行 `check_final_artifact.js`？
+- [ ] 最终回复前是否重新运行 dry-run 确认无普通临时产物残留？
+```
+
+## 脚本用法
+
+先预览：
+
+```bash
+node scripts/clean_case.js --case-dir case --dry-run --markdown
+```
+
+清理普通临时文件：
+
+```bash
+node scripts/clean_case.js --case-dir case --force --markdown
+```
+
+只有用户明确确认后，才删除 Profile：
+
+```bash
+node scripts/clean_case.js --case-dir case --force --include-profiles --markdown
+```
+
+清理后复查：
+
+```bash
+node scripts/clean_case.js --case-dir case --dry-run --json
+```
+
+期望 `remainingTempLike` 为空；如果不为空，说明仍有普通临时 / 缓存 / 中间产物残留，需要继续处理。
+
+补环境真实性复查：
+
+```bash
+node scripts/check_env_realism.js --case-dir case --markdown
+```
+
+最终产物复查：
+
+```bash
+node scripts/check_final_artifact.js --case-dir case --markdown
+```