146 lines
6.0 KiB
Markdown
146 lines
6.0 KiB
Markdown
# 临时产物清理规范
|
||
|
||
当创建临时文件、测试文件、浏览器产物、缓存文件、中间产物或 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
|
||
```
|