wowemulation-dev/cascette-py
GitHub: wowemulation-dev/cascette-py
一套用于解析、校验和下载暴雪 NGDP/CASC 格式游戏数据的 Python 工具集。
Stars: 6 | Forks: 0
# Cascette 工具
用于 NGDP/CASC 格式分析的 Python 工具。
## 概述
用于处理暴雪的 NGDP（Next Generation Distribution Pipeline）和 CASC（Content Addressable Storage Container）格式的 Python 包。提供命令行工具和编程 API，用于分析和解析游戏数据文件。
## 功能
- **格式支持**：支持 BLTE、Encoding、Root、Install、Download 和 Archive 格式的解析器
- **CDN 集成**：直接访问暴雪 CDN 和镜像服务
- **类型安全**：完整的类型提示和用于数据验证的 Pydantic 模型
- **异步支持**：针对网络请求的高效并发操作
- **缓存**：多层缓存以提升性能
- **CLI 接口**：提供功能丰富且包含全面子命令的命令行界面
- **测试覆盖率**：包含 48 个测试文件，强制要求至少 80% 的代码覆盖率
## 安装说明
### 开发环境安装
```
# 克隆仓库
git clone https://github.com/wowemulation-dev/cascette-py.git
cd cascette-py
# 安装依赖 (需要 uv: https://docs.astral.sh/uv/)
uv sync --all-extras
```
### 生产环境安装
```
uv pip install cascette-tools
```
## 快速入门
### 命令行使用
```
# 显示帮助
cascette --help
# 检查版本
cascette version
# 检查 CASC 格式文件
cascette inspect blte # Examine BLTE compressed files
cascette inspect encoding # Examine encoding files
cascette inspect config # Examine build/CDN config files
cascette inspect archive # Examine archive index files
cascette inspect download --product wow # Examine download manifest
cascette inspect stats # Show file statistics
cascette inspect compression # Analyze BLTE compression
cascette inspect coverage # Analyze content coverage
cascette inspect dependencies # Trace content key dependencies
# 从 CDN 下载数据
cascette cdn config # Fetch configuration files
cascette cdn encoding # Fetch encoding files
cascette cdn data # Fetch data archives
cascette cdn patch # Fetch patch files
cascette cdn build # Fetch complete build data
cascette cdn manifests # Fetch TACT manifests (versions/cdns)
cascette cdn batch # Batch fetch from hash list
# 处理 archive 索引
cascette archive examine # Examine archive index files
cascette archive find # Find entry by encoding key
cascette archive find-key # Find which archive contains a key
cascette archive extract-key # Extract data for an encoding key
cascette archive scan # Scan for archive-groups
cascette archive validate-mapping # Validate archive index mapping
# 验证格式
cascette validate format # Validate individual files
cascette validate integrity # Check checksums
cascette validate relationships # Validate cross-references
cascette validate roundtrip # Test parse/build cycle
cascette validate batch # Batch validate files
# 安装和管理游戏内容
cascette install resolve-manifests ... # Resolve all manifests from a build
cascette install discover-latest # Discover latest build for a product
cascette install scan-state # Scan a local installation
cascette install progress # Show installation progress
# 管理 TACT keys
cascette tact list # List known TACT keys
cascette tact search # Search for a specific key
cascette tact sync # Sync with wowdev/TACTKeys repository
cascette tact export # Export keys to JSON file
cascette tact stats # Show key database statistics
# 管理 listfiles
cascette listfile search # Search for file paths
cascette listfile lookup # Lookup by FDID or path
cascette listfile sync # Sync with wowdev/wow-listfile
cascette listfile export # Export listfile to file
cascette listfile stats # Show listfile statistics
```
### Python API 使用
```
from cascette_tools.core.types import Product, BuildInfo
from cascette_tools.core.config import AppConfig
# 配置应用程序
config = AppConfig()
# 使用类型进行验证
product = Product.WOW_CLASSIC
build_info = BuildInfo(
build_config="1234567890abcdef1234567890abcdef12345678",
cdn_config="abcdef1234567890abcdef1234567890abcdef12"
)
```
## 包结构
```
cascette_tools/
├── __main__.py # CLI entry point, registers 8 command groups
├── core/ # Shared functionality
│ ├── types.py # Pydantic models (BuildInfo, Product, CDNConfig, etc.)
│ ├── config.py # AppConfig with CDN URLs, timeouts, paths
│ ├── cdn.py # CDN client (Ribbit primary, community mirror fallback)
│ ├── cdn_archive_fetcher.py # Archive index downloading, HTTP range extraction
│ ├── cache.py # Multi-layer disk caching
│ ├── build_update.py # Build update orchestration
│ ├── containerless_storage.py # Containerless CASC storage mode
│ ├── containerless_update.py # Containerless update logic
│ ├── download_queue.py # Prioritized download queue management
│ ├── encoding_cache.py # Encoding file caching layer
│ ├── install_state.py # Installation state tracking
│ ├── integrity.py # Data integrity verification
│ ├── local_storage.py # Local CASC directory structure
│ ├── product_state.py # Battle.net agent state files
│ ├── shmem.py # Shared memory segment handling
│ ├── tact.py # TACT encryption key handling
│ └── utils.py # Hex conversion, MD5, Jenkins96 hash
├── formats/ # Binary format parsers
│ ├── base.py # FormatParser[T: BaseModel] abstract base
│ ├── blte.py # BLTE compression (modes: N/Z/L/E/F)
│ ├── blte_integration.py # BLTE integration helpers
│ ├── encoding.py # Encoding file (CKey/EKey lookup)
│ ├── root.py # Root file (versions 1-4)
│ ├── config.py # Build/CDN/product/patch config parsers
│ ├── build_info.py # .build.info file parser
│ ├── archive.py # CDN archive index
│ ├── cdn_archive.py # CDN archive format
│ ├── file_db.py # File database format
│ ├── install.py # Install manifest
│ ├── download.py # Download manifest
│ ├── patch_archive.py # Patch archive (PA) format
│ ├── size.py # Size-related format parsing
│ ├── zbsdiff.py # ZBSDIFF binary diff
│ └── tvfs.py # TVFS virtual file system
├── commands/ # Click CLI command groups (8 groups)
│ ├── archive.py # archive: examine, scan, find, find-key, extract-key, validate-mapping
│ ├── builds.py # builds: sync, list, search, stats, export, import
│ ├── cdn.py # cdn: config, data, build, encoding, batch, patch, manifests
│ ├── inspect.py # inspect: blte, encoding, config, archive, stats, compression, coverage, dependencies
│ ├── install.py # install: resolve-manifests, discover-latest, scan-state, progress, and more
│ ├── listfile.py # listfile: sync, search, lookup, export, stats, import
│ ├── tact.py # tact: sync, list, search, export, stats, import
│ └── validate.py # validate: format, integrity, roundtrip, relationships, batch
├── database/ # External data integrations
│ ├── wago.py # Wago.tools API client
│ ├── tact_keys.py # TACT key database
│ └── listfile.py # FileDataID-to-path mapping
└── crypto/ # Cryptographic utilities
└── jenkins.py # Bob Jenkins lookup3 hash
tests/ # Test suite (48 test files, 80% coverage minimum)
├── conftest.py # Shared fixtures for CLI mocking and CDN responses
├── test_cli.py # Main CLI integration tests
├── test_core/ # Core module tests
├── test_formats/ # Format parser tests
├── test_commands/ # CLI command tests
├── test_database/ # Database tests
└── test_crypto/ # Cryptographic utility tests
```
## 开发
### 前置条件
- Python 3.12 或更高版本
- [uv](https://docs.astral.sh/uv/) 包管理器
此外，[mise](https://mise.jdx.dev/) 可以按项目管理 Python 版本和 `uv` 等开发工具。安装 mise 后，在仓库根目录运行 `mise install` 即可自动设置固定的工具链。
### 开发环境设置
```
# 安装开发依赖
uv sync --all-extras
# 运行测试（强制要求最低 80% 覆盖率）
uv run pytest
# 运行测试并生成 HTML 覆盖率报告
uv run pytest --cov-report=html
# 类型检查
uv run pyright cascette_tools
# 代码格式化
uv run black cascette_tools tests
# Linting
uv run ruff check cascette_tools tests
```
## 代码质量与验证
### Python 代码验证
cascette-tools 包中的所有 Python 代码都必须通过以下验证步骤：
```
# Linting 和代码质量检查
uv run ruff check cascette_tools tests
# 类型检查和静态分析
uv run pyright cascette_tools
# 代码格式化（自动修复）
uv run black cascette_tools tests
# 测试覆盖率要求（通过 pyproject.toml 强制要求最低 80%）
uv run pytest
```
### Pre-commit 工作流
在提交更改之前：
```
# 运行所有质量检查
uv run ruff check cascette_tools tests && \
uv run pyright cascette_tools && \
uv run pytest
# 自动修复格式问题
uv run black cascette_tools tests
uv run ruff check --fix cascette_tools tests
```
### 类型安全
该包强制执行严格的类型检查：
- 所有函数都有类型提示
- 使用 Pydantic 模型进行数据验证
- 在严格模式下使用 `pyright` 捕获类型错误
- 为格式解析器使用泛型
### 测试策略
```
# 仅运行单元测试
uv run pytest -m unit
# 集成测试（可能需要网络）
uv run pytest -m integration
# 排除慢速测试以获取快速反馈
uv run pytest -m "not slow"
# 运行特定的测试文件
uv run pytest tests/test_formats/test_blte.py
# 运行并显示详细输出
uv run pytest -v
# 生成 HTML 覆盖率报告
uv run pytest --cov-report=html
# 在浏览器中打开 htmlcov/index.html
```
## 基础：Wago.tools 构建数据库
**关键**：我们整个格式演变分析都依赖于由 [Wago.tools](https://wago.tools) 维护的全面构建数据库。该数据库包含从 6.0.x (Warlords of Draenor) 到当前版本、涵盖所有产品的 1,900 多个 WoW 构建。
### 首次设置（必不可少）
```
# 获取产品的 TACT manifests（分析所需）
cascette cdn manifests wow
# 或者获取特定的 build 数据
cascette cdn build wow 11.0.2.56461
# 这将下载用于分析的 build 元数据和 manifest 文件
# 产品包括：wow, wow_classic, wow_classic_era, wow_classic_titan, wow_anniversary, wowt, wow_beta
```
Wago.tools 数据提供：
- 从 WoD 6.0.x 开始的完整构建历史
- 涵盖正式服、怀旧服、PTR 和 Beta 分支
- 随新版本发布定期更新
- 访问具有良好可用性的构建元数据
### 快速入门
获取构建数据后：
```
# 验证下载的文件
cascette validate batch test_data/
# 分析文件统计信息
cascette inspect stats
# 检查压缩效果
cascette inspect compression
```
## 命令分类
### 基础核心命令
**从这里开始 - 这些命令为所有其他分析提供数据：**
| 命令 | 用途 | 使用方法 |
|---------|---------|--------|
| **`cascette builds sync`** | **从 Wago.tools 和 BlizzTrack 获取构建数据库** | **`cascette builds sync`** |
### 核心检查命令
这些命令用于检查单个文件：
| 命令 | 用途 | 使用方法 |
|---------|---------|--------|
| `cascette inspect blte` | BLTE 解压缩与分析 | `cascette inspect blte -o ` |
| `cascette inspect encoding` | Encoding 文件分析与 content key 查找 | `cascette inspect encoding ` |
| `cascette inspect config` | Build 与 CDN 配置分析 | `cascette inspect config ` |
| `cascette inspect archive` | Archive 索引文件分析 | `cascette inspect archive ` |
| `cascette inspect download` | Download manifest 优先级与平台标签 | `cascette inspect download --product wow` |
| `cascette inspect stats` | 显示文件统计信息与元数据 | `cascette inspect stats ` |
| `cascette inspect compression` | 分析 BLTE 压缩效率 | `cascette inspect compression ` |
| `cascette inspect coverage` | 分析跨文件的内容覆盖率 | `cascette inspect coverage ` |
| `cascette inspect dependencies` | 追踪从 content key 到 encoding key 再到 archive 的依赖关系 | `cascette inspect dependencies ` |
### 验证套件
这些命令用于验证格式文件：
| 命令 | 用途 | 使用方法 |
|---------|---------|--------|
| `cascette validate format` | 验证单个格式文件 | `cascette validate format ` |
| `cascette validate integrity` | 检查文件校验和与完整性 | `cascette validate integrity ` |
| `cascette validate relationships` | 验证跨文件引用 | `cascette validate relationships ` |
| `cascette validate roundtrip` | 测试解析/构建周期的正确性 | `cascette validate roundtrip ` |
| `cascette validate batch` | 批量验证多个文件 | `cascette validate batch ` |
### CDN 下载命令
用于从暴雪 CDN 下载数据的命令：
| 命令 | 用途 | 使用方法 |
|---------|---------|--------|
| `cascette cdn config` | 从 CDN 获取配置文件 | `cascette cdn config ` |
| `cascette cdn encoding` | 通过 hash 获取 Encoding 文件 | `cascette cdn encoding ` |
| `cascette cdn data` | 从 CDN 获取数据 archive | `cascette cdn data ` |
| `cascette cdn patch` | 从 CDN 获取 patch 文件 | `cascette cdn patch ` |
| `cascette cdn build` | 获取完整的 build 信息 | `cascette cdn build ` |
| `cascette cdn manifests` | 获取 TACT manifest（versions 和 cdns） | `cascette cdn manifests ` |
| `cascette cdn batch` | 根据 hash 列表批量获取 | `cascette cdn batch ` |
### 实用命令
| 命令 | 用途 | 使用方法 |
|---------|---------|--------|
| `cascette tact list` | 列出已知的 TACT 加密密钥 | `cascette tact list` |
| `cascette tact sync` | 从仓库同步 TACT 密钥 | `cascette tact sync` |
| `cascette listfile search` | 搜索 FileDataID 到路径的映射 | `cascette listfile search ` |
| `cascette listfile sync` | 从仓库同步 listfile | `cascette listfile sync` |
| `cascette version` | 显示版本信息 | `cascette version` |
## 输出目录结构
所有分析结果都保存在 `results/` 目录中：
```
~/.local/share/cascette-tools/ # XDG data directory
├── wago_builds.db # SQLite build database
├── wago_cache/ # Wago API response cache (24-hour)
├── tact_keys.db # TACT key database
└── listfile.db # FileDataID mapping database
test_data/ # Downloaded CASC files (gitignored)
├── wago-builds-*.json
└── wow_*_*.dat/txt # Cached CASC files
```
## 推荐使用工作流
### 完整的端到端示例
以下是完成下载、检查和验证过程的推荐步骤：
```
# 步骤 1：获取 build 数据库（一次性设置）
cascette builds sync
# 步骤 2：验证下载的文件
cascette validate batch test_data/
# 步骤 3：分析文件统计信息
cascette inspect stats
# 步骤 4：检查压缩效果
cascette inspect compression
# 步骤 5：验证文件完整性
cascette validate integrity
# 步骤 6：检查数据存储
ls -lh ~/.local/share/cascette-tools/
```
### 0. 关键的第一步 - 获取构建数据库
在进行任何分析之前**必须**执行此操作：
```
# 从 Wago.tools 和 BlizzTrack 获取 build 数据库
cascette builds sync
# 这将创建一个包含 build 元数据的本地 SQLite 数据库
# 所有其他命令都会自动检测并使用此数据
```
如果没有这一步，就无法进行格式演变分析。
### 1. 初始设置与验证
验证工具是否正常工作：
```
# 获取 Wago build 数据库
cascette builds sync
# 测试获取 config 文件
cascette cdn config
# 验证下载的文件
cascette validate format
```
这会根据真实的 WoW 构建验证我们的格式文档，并缓存文件供将来分析。测试套件确保所有工具都能正常运行，并为网络操作设置了适当的超时。
### 2. 单个构建分析
要检查特定构建：
```
# 获取完整的 build（下载约 50MB 的数据）
cascette cdn build wow_classic_era 1.13.7.38704
# 检查该 build 中的特定文件
cascette inspect encoding bbf06e74 # Encoding file hash from build output
```
### 3. 格式分析
分析格式特征：
```
# 分析文件统计信息
cascette inspect stats
# 分析 BLTE 压缩效果
cascette inspect compression
# 分析跨文件的内容覆盖率
cascette inspect coverage
# 追踪文件依赖
cascette inspect dependencies
```
这些脚本按时间顺序检查构建，以确定格式发生更改的时间。专门的追踪器提供对特定格式方面的详细分析，并在 `results/` 目录中生成全面的报告。
### 4. Patch 系统分析
检查 NGDP patch 系统：
```
# 获取 patch 文件
cascette cdn patch
# 获取 patch 索引文件
cascette cdn patch --index
# 验证 patch 文件格式
cascette validate format
```
这些工具检查 PA (Patch Archive) 格式、ZBSDIFF1 patch 格式，以及 patch 配置中的 patch-entry 结构。
### 5. 单个文件分析
用于详细检查特定文件格式：
```
# 解压 BLTE 文件
cascette inspect blte compressed_file.blte -o decompressed.dat
# 检查 encoding 文件
cascette inspect encoding
```
### 6. 数据管理
管理已下载的数据：
```
# 列出下载的文件
ls -la test_data/
# 检查数据库状态
ls -lh ~/.local/share/cascette-tools/wago_builds.db
# 查看 Wago 缓存状态（24 小时缓存）
ls -la ~/.local/share/cascette-tools/wago_cache/
```
## 数据来源
### 主要来源：Wago.tools API
**所有格式分析的基础：**
- **API Endpoint**：`https://wago.tools/api/builds`
- **覆盖范围**：包含从 WoD 6.0.x 至今的 1,900 多个构建
- **产品**：wow、wow_classic、wow_classic_era、wow_classic_titan、wow_anniversary、wowt、wow_beta 等
- **时效性**：随着新版本的发布定期更新
- **可靠性**：由 WoW 开发社区维护
**数据结构**：每个构建包含：
- `build_config`：Build 配置文件的 hash
- `cdn_config`：CDN 配置的 hash
- `product_config`：特定产品的配置
- `version`：版本字符串（例如 "11.2.0.62706"）
- `created_at`：构建时间戳
- `is_bgdl`：后台下载标志
### 用于文件下载的 CDN 访问
工具会动态从暴雪的 Ribbit endpoint 获取 CDN 服务器列表。当 Ribbit 服务器不可用时，社区镜像（`cdn.arctium.tools`、Wago、`archive.wow.tools`）作为备用方案：
- Ribbit 服务器是文件检索的主要来源
- 社区镜像提供备用可用性
- 使用来自 Wago.tools 数据的 hash 获取实际文件
### 旧版构建信息
备用来源（不再作为主要来源）：
- `../docs/builds-20250821-133310.json` - 旧的归档构建列表
- 来自已知来源的手动构建配置 hash
- 跨越 WoW 资料片历史挑选的战略性构建
## 文件格式支持
### 支持的格式
| 格式 | 解析器 | 状态 | 备注 |
|--------|--------|---------|--------|
| BLTE | `formats/blte.py` | 可用 | 压缩模式 N、Z、L、E、F |
| Encoding | `formats/encoding.py` | 可用 | Content key 查找，支持 ESpec |
| Root | `formats/root.py` | 可用 | 版本 1-4，TSFM/MFST magic 检测 |
| TVFS | `formats/tvfs.py` | 可用 | Header 解析，table 分析，版本 1 格式 |
| Build Config | `formats/config.py` | 可用 | 所有字段类型，空格分隔的值 |
| Build Info | `formats/build_info.py` | 可用 | .build.info 解析/构建往返测试 |
| Install | `formats/install.py` | 基础 | Magic 检测，Header 解析 |
| Download | `formats/download.py` | 基础 | Magic 检测，Header 解析 |
| Archive | `formats/archive.py` | 可用 | CDN archive 索引，archive-groups |
| Patch Archive | `formats/patch_archive.py` | 可用 | PA 格式解析 |
| ZBSDIFF | `formats/zbsdiff.py` | 可用 | 二进制 diff 格式 |
### 检测到的格式版本
- **Root 文件**：版本 1-4，带自动版本检测
- **BLTE**：所有已知的压缩模式和 block 结构
- **Encoding**：基于分页的架构，集成了 ESpec
- **Config 文件**：从 WoD (6.0.x) 到 TWW (11.x) 的演变
## 缓存系统
### 存储位置
所有下载的文件都缓存在 `test_data/` 目录中：
- 首次运行时自动创建
- 完全被 git 忽略（参见 `.gitignore`）
- 使用描述性文件名进行组织
### 缓存命名规范
文件命名为：`{product}_{version}_{file_type}_{hash_prefix}.{extension}`
示例：
- `wow_classic_era_1.13.7.38704_root_b98595f5.dat`
- `wow_11.2.0.62706_encoding_bbf06e74.dat`
- `wow_classic_era_1.13.7.38704_build_config_ae66faee.txt`
### 缓存的优点
- **性能**：后续运行使用缓存数据，无需重新下载
- **离线开发**：在网络不可用时处理缓存文件
- **节省带宽**：避免冗余下载大文件
- **分析可追溯性**：文件名显示了确切的构建来源
## 依赖项
### 安装
该包使用基于 pyprojectl 的 Python 打包方式：
#### 标准安装
```
uv pip install cascette-tools
```
#### 开发环境安装
```
uv sync --all-extras
```
#### 核心依赖
该包需要：
- `click` - CLI 框架
- `pydantic` - 数据验证
- `httpx` - 异步 HTTP 客户端
- `rich` - 终端格式化
- `structlog` - 结构化日志
- `lz4` - LZ4 压缩
- `pycryptodome` - 加密支持（Salsa20、ARC4）
### 系统要求
- Python 3.12+（使用类型提示和 match 语句）
- 初次下载需要网络连接
- 完整缓存约需 200MB 磁盘空间
### 开发依赖
用于开发和测试：
- `pytest` - 测试框架
- `pytest-cov` - 覆盖率报告
- `pyright` - 类型检查
- `ruff` - 快速的 Python linter
- `black` - 代码格式化
- `beautifulsoup4` - Wiki 抓取脚本
## 错误处理与故障排除
### 常见问题
**CDN 连接超时**：
```
# 为慢速连接使用更长的超时时间
cascette cdn build --timeout 60 wow 11.2.0.62706
```
**缓存损坏**：
```
# 移除缓存数据并重试
rm -rf ~/.local/share/cascette-tools/cache/
cascette builds sync
```
**缺少构建数据**：
- 确保您已首先运行 `cascette builds sync`
- 验证构建配置 hash 是否正确
- CDN 上可能无法提供一些较旧的构建
### 调试选项
大多数命令支持详细输出：
```
cascette cdn build --verbose wow 11.2.0.62706
cascette inspect encoding
cascette --debug # Enable debug mode globally
```
## 开发工作流
### 添加新分析
1. 在 `cascette_tools/commands/` 中创建新的命令模块
2. 使用 `cascette_tools/formats/` 中现有的格式解析器
3. 通过 `main.add_command()` 在 `__main__.py` 中注册命令组
4. 在 `tests/` 目录中添加测试
### 测试更改
```
# 运行测试套件（强制要求最低 80% 覆盖率）
uv run pytest
# 类型检查
uv run pyright cascette_tools
# Linting
uv run ruff check cascette_tools tests
```
### 开发期间的缓存管理
```
# 检查数据库状态
ls -lh ~/.local/share/cascette-tools/
# 查看下载的测试数据
ls -la test_data/
```
## 格式检查方法论
检查工具使用系统化的分析方法来理解 NGDP/CASC 格式：
### 战略性构建选择
分析针对跨越 WoW 版本过渡的关键构建，而不是检查所有 1,900 多个构建。选定的构建代表：
- **主要资料片边界**：6.0.x (WoD)、7.x (Legion)、8.x (BfA)、9.x (Shadowlands)、10.x (Dragonflight)、11.x (TWW)
- **格式过渡点**：通过版本分析确定的、包含格式变更的构建
- **跨产品覆盖**：正式服、怀旧服 和经典怀旧服 变体
- **稳定性焦点**：选择稳定版本的初始构建，而不是不稳定的 PTR 或 Beta 构建
### 多层分析方法
每个检查工具在多个级别分析格式：
1. **Header 结构**：Magic 签名、版本号、字段计数、字节序检测
2. **内容分析**：数据模式、压缩类型、编码方案、标志结构
3. **演变追踪**：随时间的变化、功能采用模式、跨产品差异
4. **效率指标**：文件大小、压缩率、每条目字节数计算
### 通过真实数据进行验证
格式理解将针对实际的 CASC 文件进行验证：
- **直接访问 CDN**：使用已验证的 hash 从 cdn.arctium.tools 下载文件
- **二进制结构解析**：检查实际的字节布局，而不是理论规范
- **交叉引用验证**：跨多个构建比较发现以识别模式
- **边缘情况发现**：真实数据揭示了文档中未涵盖的格式差异
### 智能缓存系统
下载的文件使用描述性名称进行缓存，以启用离线分析：
- **来源追踪**：文件名包含产品、版本、文件类型和 hash 前缀
- **选择性缓存**：仅保留经过验证且成功解析的文件
- **开发效率**：后续分析运行使用缓存数据，无需重新下载
- **存储管理**：缓存清理工具管理磁盘使用量，同时保留重要样本
## 与主项目集成
这些工具在以下几个方面为 Rust 实现提供参考：
### 解析器设计
- **版本检测**：工具识别 WoW 历史中存在哪些格式版本
- **边缘情况**：真实数据揭示了其他地方未记录的解析边缘情况
- **性能模式**：分析表明哪些优化对不同文件大小至关重要
- **格式演变**：变更时间线指导向后兼容性要求
### 测试数据生成
- **已知的良好数据**：缓存文件为解析器验证提供测试向量
- **格式示例**：真实构建展示了跨不同 WoW 版本的格式用法
- **回归测试**：历史构建验证解析器是否能正确处理格式演变
- **边缘情况覆盖**：真实文件包含合成测试数据中不存在的差异
### 文档验证
- **格式准确性**：工具根据实际的 CASC 文件验证文档声明
- **演变时间线**：具有确切构建号的格式更改的精确过渡点
- **实现要求**：通过分析发现的现实世界约束和模式
- **跨产品验证**：确认 wow、wow_classic 和 wow_classic_era 之间的格式一致性
### 格式发现过程
检查方法遵循系统化的发现过程：
1. **初始调查**：`cascette builds sync` 从 Wago.tools 获取构建数据库
2. **战略抽样**：跨越 WoW 版本过渡选择构建，以识别格式更改
3. **详细分析**：CLI 检查命令 (`cascette inspect`) 针对真实文件验证格式假设
4. **验证**：针对多个构建测试格式解析器以确认一致性
5. **文档化**：使用确切的构建引用和过渡点记录发现
## 延伸阅读
- [Battle.net 安装过程分析](docs/battlenet-install-process.md)
- [完整安装 POC 计划](docs/full-install-poc-plan.md)
- [完整安装执行计划](docs/full-installation-execution-plan.md)
## 支持该项目
如果您觉得这个项目有用，请考虑
[赞助该项目](https://github.com/sponsors/danielsreichenbach)。
这目前是一个人在晚上和周末投入的努力。资金目标：
- **每周 20 小时** - 持续的资金支持，以便投入真正的开发时间，而不是挤在零碎的空闲时间里
- **公共 CDN 镜像** - 托管一个面向《魔兽世界》构建的社区镜像，确保历史游戏数据的长期可用性
## 贡献
有关开发设置和贡献指南，请参阅 [AGENTS.md](AGENTS.md)。
## 许可证
本项目采用以下任一许可证进行双重许可：
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) 或 )
- MIT 许可证 ([LICENSE-MIT](LICENSE-MIT) 或 )
您可以自行选择使用其中任一许可证。
### 贡献
除非您明确声明，否则根据 Apache-2.0 许可证的定义，您故意提交以包含在本作品中的任何贡献均应按上述方式进行双重许可，不得附带任何额外条款或条件。
**注意**：本项目不隶属于暴雪娱乐。这是一个基于《魔兽世界》模拟社区逆向工程的独立实现。
标签：CASC格式, Python, 安全规则引擎, 文件解析, 无后门, 暴雪NGDP, 游戏数据解析, 逆向工具