Adriwin06/BP-Decomp_Workflow

# Burnout Paradise 反编译工作流 本仓库是逆向工程 Burnout 5 / Burnout Paradise 的统筹工作区。它本身并不是反编译的源码树。它包含了分析数据库、参考资料、工作台账以及自动化工具，使得 agent 能够将 Xbox 360 版本重构为可编译的 PC C++ 代码。 恢复出的 C++ 代码位于 [`b5-decomp`](https://github.com/Adriwin06/b5-decomp) 子模块中。本仓库负责解答： - X360 目标版本中存在哪些函数； - 每个函数属于哪个翻译单元（TU）； - 每个单元有哪些可用的参考证据； - 哪些单元的状态为 todo、in progress、compiled、reviewed、blocked 或 done； - 如何认领、重构、验证、审查以及协调工作。 ## 优先阅读 对于重构工作，请按以下顺序阅读： 1. [`AGENTS.md`](AGENTS.md) - 每个 agent 和维护者的操作指南。 2. [`STRATEGY.md`](STRATEGY.md) - 技术方案与证据规则。 3. [`progress/README.md`](progress/README.md) - 台账与 `work` CLI 参考。 `CLAUDE.md` 的存在仅作为 Claude Code 的重定向。规范指令在 `AGENTS.md` 中共享，以便所有 agent 遵循相同的流程。 ## 为什么需要使用多个构建版本 没有任何单一的二进制文件能包含足够的信息。该工作流采用多源交叉验证： | 构建版本或产物 | 作用 | | --- | --- | | `BURNOUT_X360_ARTIST.XEX` | 目标/骨架。其符号、伪代码、汇编以及交叉引用（xrefs）定义了重构的内容。 | | `Burnout_External_PS3.ELF` | 符号丰富的 PS3 版本，用于验证名称和行为。 | | `DecFIGS_Burnout_Internal_PS3.ELF` | 提供 DWARF 源码/文件归属，以及声明、类型、枚举、全局变量、函数签名和局部变量的提示信息。 | | `BurnoutPR.exe` 和 `TUB_Burnout_PC_External.exe` | 去除符号的 PC 参考版本，有选择地用于查阅特定平台的代码路径。 | | `rwcore.lib` / `rwcore.pdb` / `rwcore_master.obj` | RenderWare 核心的类型与布局证据。 | | `references/Feb-2007/` | 真实的源码切片，在重叠部分用作最高保真度的模板。 | | `references/Wiki/` | 源自 burnout.wiki 的类型表。使用其名称/类型/语义，但绝对不使用其偏移量。 | 规范标识是一个标准化的全限定函数名，而不是地址。 地址是特定于构建版本的，绝不能视为在不同二进制文件之间保持稳定。 ## 仓库布局 | 路径 | 内容说明 | | --- | --- | | [`AGENTS.md`](AGENTS.md) | 与工具无关的操作指南：恢复行为、工作循环、服务器协调、重构规则、审查策略以及“禁止”规则。 | | [`STRATEGY.md`](STRATEGY.md) | 工作流的设计文档：目标、构建版本作用、标识模型、TU 模型、存根、验证、目标与阶段状态。 | | [`IDA Files/`](IDA%20Files/) | IDA Pro 数据库以及 RenderWare 库/PDB 输入。一些大型 `.i64` 文件被有意通过 git 忽略，必须在本地自行提供。 | | [`.ida-exports/`](.ida-exports/) | 从 IDA 导出的按函数生成的 JSON 文件：名称、原型、局部变量、伪代码、汇编、调用者和被调用者。已被 git 忽略。 | | [`references/`](references/) | 非反汇编证据：Feb-2007 源码切片、DecFIGS DWARF 产物、BPR 模块映射、wiki 索引以及命名约定。 | | [`tools/`](tools/) | IDAPython 导出器、后处理器、RenderWare 头文件生成器，以及 `tools/work/` 台账/重构辅助工具。 | | [`progress/`](progress/) | 共享的台账输入与输出：标识、TU 索引、依赖关系、状态镜像、目标、验证/审查配置，以及生成的审查包。 | | [`b5-decomp/`](https://github.com/Adriwin06/b5-decomp) | 包含已恢复的 C++ 代码、第三方库、RenderWare 头文件以及 CMake 项目文件的子模块。 | | [`build/`](build/) | 用于 `b5-decomp` 的本地构建树；不是事实的唯一来源。 | | [`.env.example`](.env.example) | 可选的工作服务器配置模板。只有在维护者分配给你 worker id 时，才将其复制到 `.env`。 | `progress/reviews/` 下生成的审查包以及 `b5-decomp/vendor/` 下的第三方 Markdown 是产物/上游文档，不是主要的工作流文档。 ## 前置条件 常规台账工作所需： - Python 3 - Git - Windows 上的 PowerShell - 已在 `b5-decomp/vendor/` 下初始化的子模块 编译门控所需： - Visual Studio/MSVC - `progress/verify.config.json` 指向真实的 `vcvars64.bat` 如果缺少 `vcvars`，`work submit` 将报告跳过编译门控并继续执行；这对于记录工作进展很有用，但无法捕捉编译器错误。 仅在重新生成分析导出文件或从 IDA 生成新的骨架时需要： - 带有 Hex-Rays 的 IDA Pro (`idat.exe`) - `IDA Files/` 下相关的 `.i64` 数据库 - 为目标数据库生成的 `.ida-exports/`。如果它们缺失或已过期，在进行重构工作之前请运行 IDA 导出脚本： tools/export_db.ps1 大体积或受许可限制的本地输入文件被有意地全部排除在提交之外。至少，重新生成导出文件的本地工作可能需要参考 README 文档中记录的、被 git 忽略的 PS3/PC IDB 文件以及 Feb-2007 源码树。 ## 全新克隆 / 恢复工作 在仓库根目录下执行： ``` work bootstrap ``` `bootstrap` 会初始化子模块，并根据已提交的状态重新构建 `progress/ledger.sqlite`：`progress/status.json`、`progress/tu_deps.json`、`progress/identity.json` 以及 `progress/tu_index.json`。 这足以恢复任务队列和状态台账。它不会重新生成被 git 忽略的 IDA 导出缓存。如果 `.ida-exports/` 不存在或与本地 IDA 数据库不匹配，请在重构 TU 之前生成它： ``` tools/export_db.ps1 # all configured IDA databases tools/export_db.ps1 -DbName "BURNOUT_X360_ARTIST.XEX" ``` 之后，简短的“continue”指令意味着： ``` work claim work show --full ``` 然后将 TU 重构到 `b5-decomp/src/` 中，进行编译/提交，并记录审查结果。 ## 核心工作循环 ``` work status # ledger counts and active goal work next -n 5 # preview ready work; reserves nothing work claim [-n N] # claim next ready TU(s) work claim [ ...] # claim specific TU(s) work show --full [--asm] # reconstruction dossier work stubs --list # unresolved callees and owning headers work submit [--files path ...] # compile gate, parity, reviewer packet work parity # standalone deterministic parity check work review --verdict pass # mark done after review/self-check work review --verdict fail # return to in_progress with notes work block "reason" # stop it being reclaimed ``` 编译门控是针对每个翻译单元进行的（`cl /c`，不进行链接）。目标是实现与 X360 版本在语义上的一致性，表现为类似源码的 PC C++ 代码，而不是字节级别的完全匹配。 ## 工具清单 权威的仓库工具清单位于 [`tools/README.md`](tools/README.md)。 概览如下： | 工具领域 | 入口点 | | --- | --- | | 日常台账工作 | `work bootstrap`, `work status`, `work next`, `work claim`, `work show`, `work submit`, `work parity`, `work review`, `work block` | | 目标范围界定与追踪 | `work goal ...`, `work goal import-trace`, `tools/work/trace_import.py` | | IDA 导出 pipeline | `tools/export_db.ps1`, `tools/ida_export_all.py`, `tools/ida_export_lineinfo.py`, `tools/ida_decompile.py` | | 派生台账构建器 | `tools/work/build_identity.py`, `tools/work/build_tu_index.py`, `tools/work/build_type_deps.py`, `work seed --deps` | | 重构辅助工具 | `tools/work/dossier.py`, `tools/work/gen_stubs.py`, `tools/work/gen_skeleton.py`, `tools/work/auto_draft.py` | | 验证/审查 | `tools/work/verify.py`, `tools/work/parity.py`, `progress/verify.config.json`, `progress/review.config.json` | | 参考与维护 | `tools/work/wiki_index.py`, `tools/work/check_vendor_lib.py`, `tools/work/reconcile_from_files.py`, `tools/work/find_local_redefs.py`, `tools/gen_rwcore_headers.py` | | 可选的服务器协调 | `work sync`, `work server-sync`, `work server-reset`, `work worker-add`, `work worker-list`, `work worker-revoke` | ## 目标与执行追踪 默认情况下，`work next` 会对整个程序按叶子优先进行排序。目标会将队列限定在一个成员集合中，这些集合可以是手动编写的 glob 匹配模式，也可以是执行派生的 Xenia 追踪记录： ``` work goal work goal show boot-trace work goal set boot-trace work goal clear work goal import-trace [--trace-dir .trace/funcdata] ``` 目标定义在 [`progress/goals.json`](progress/goals.json) 中。完整的 schema 和 Xenia 追踪流程记录在 [`references/GOAL_SCOPING.md`](references/GOAL_SCOPING.md) 中。 ## 可选的协调服务器 默认模式是本地的：台账和 git 是唯一的状态来源。如果维护者给了你服务器 URL 和 worker id，请将 `.env.example` 复制到 `.env` 并设置： ``` WORK_SERVER=https://... WORK_AGENT= WORK_LEASE_SECONDS=7200 ``` 配置好服务器后，`work claim` 在所有 agent 之间是原子操作的，并且实时的认领状态会保留在服务器上。与已提交代码绑定的持久状态（`done`，`blocked`）仍然通过 `progress/status.json` 进行同步。 ### 对不可达服务器的容错能力 配置好的服务器即使*宕机*，也不会中断工作循环 —— CLI 会优雅降级并在重新连接时自我修复，因此 agent 无需管理服务中断。 - **连接失败与拒绝请求。** *无法访问*的服务器被视为可恢复的中断；而*返回错误*（HTTP）的服务器则代表真实的决定。只有真正的**认证拒绝**（缺失/无效的 `WORK_AGENT`）才会阻止命令执行 —— 这是配置错误，而不是中断。 - **本地降级。** 在无法访问服务器期间，读取操作（`work next`，`work status`）会回退到本地的叶子优先排序和计数；写入操作（`work claim`，`work submit` → compiled，`work review`，`work block`/`unblock`）会应用到本地台账，并记录在一个**离线发件箱**（位于被 git 忽略的台账缓存中的 `pending_op` 表）中。 - **重连自我修复。** 在下一次服务器模式命令执行前，或者通过 `work sync` 按需执行时，发件箱会**自动重放**。`work status` 会显示队列操作计数，以及它报告的是服务器还是本地台账。 - **已完成的工作永远不会丢失。** `done`/`blocked` 持久化在 git（`progress/status.json`）中，因此即使在长时间中断后，它们也会通过 `work server-sync` 与服务器进行协调。只有*短暂存在*的认领层在离线时可能会发生冲突（租约可能在服务器上已过期，或者离线认领可能与其他 agent 发生冲突）。此类冲突会在同步期间被**报告** —— 绝不会被静默丢弃，也绝不会覆盖本地状态。 ``` work sync # flush queued offline ops (auto-runs otherwise) ``` 维护者命令： ``` work server-sync [--branch ] # preserve live claims/events work server-reset [--to ] # local reset + server reseed work worker-add "Name" [--admin] work worker-list work worker-revoke ``` ### 自动状态协调 由于每次认领/提交/审查都会镜像到服务器，已提交的 `progress/status.json` 是服务器持久状态的*派生*视图，而不是独立的来源。GitHub Action 会自动保持 git 与服务器同步，因此**从事反编译的人员只需将代码推送到 `b5-decomp` —— 他们不需要此工作流仓库的写入权限，也无需手动编辑 `status.json`。** 它会在**每次提交 b5-decomp 代码时**运行。通知工作流 [`b5-decomp/.github/workflows/notify-workflow.yml`](b5-decomp/.github/workflows/notify-workflow.yml) 会在每次推送到 b5-decomp 的 `dev` 分支时触发，并向此仓库的 [`.github/workflows/reconcile-status.yml`](.github/workflows/reconcile-status.yml) 发送一个 `repository_dispatch`（携带新的提交 SHA），随后该工作流将执行以下操作： 1. 根据服务器的 `GET /export/status` 重新生成 `progress/status.json`。服务器是**唯一的完全权威**：仅通过文件进行的协调可以恢复 `done`（因为其文件存在），但无法恢复 `blocked`（被阻断的 TU 不会留下任何文件），因此持久状态集是直接从服务器拉取的； 2. 将 `b5-decomp` 子模块指针推进到触发本次运行的提交； 3. 使用 `reconcile_from_files.py` 将服务器的 `done` 集合与已提交的 b5-decomp 文件进行交叉核对（非阻断性 —— 如果服务器将某个 TU 标记为 `done`，但其提交的文件缺失或仍为 trap-stub/partial，它只会发出警告）； 4. 以 bot 身份提交并推送重新生成的 `status.json` 以及更新的指针。 **设置（一次性）：** 通知工作流需要在 b5-decomp 仓库上设置一个 `WORKFLOW_DISPATCH_TOKEN` 密钥 —— 这是一个可以向此仓库发送 `repository_dispatch` 的 token。如果没有它，通知工作流将不会进行任何操作（因此不会破坏任何东西），但自动协调将不会触发。协调 Action 还具有手动 `workflow_dispatch` 触发器（可选择固定特定的 `b5_sha`）以便进行补录。 你也可以手动刷新已提交的镜像： ``` python tools/work/fetch_server_status.py # rewrite status.json from the server python tools/work/fetch_server_status.py --check # report drift, write nothing (exit 1 if stale) ``` 两点操作说明： - **服务器现在是 `blocked` 的持久化存储。** `done` 始终可以从已提交的文件中恢复，但被阻断的 TU 的状态和原因仅存在于服务器上 —— 因此请备份其数据库（`/var/lib/bp-work-server`）。bot 提交的 `status.json` 同时作为 `done`/`blocked` 集合的备份。 - **Action 会推送到默认分支。** 如果该分支受保护、禁止直接推送，请将 Action 指向一个旁支并自动创建 PR，而不是允许 bot 直接推送。 ## 自动化辅助工具 这些辅助工具是可选的。它们不能替代手动重构： ``` work auto --scan # find fully mechanical TUs work auto --run [-n N] # draft/gate safe forwarder/thunk-only TUs python tools/work/reconcile_from_files.py [--apply] python tools/work/find_local_redefs.py [--summary] python tools/work/wiki_index.py [--lookup ] python tools/work/check_vendor_lib.py ``` 在反编译之前，必须使用 `check_vendor_lib.py` 检查第三方 SDK 的 TU。如果脚本输出 `PRESENT`，请将该 TU 作为已被 PC 库或开源第三方源码覆盖的第三方代码进行阻断。如果输出 `MISSING`，则正常进行重构。 ## 重新生成 Pipeline 如果 `.ida-exports/` 已经存在且是最新的，大多数 agent 不需要重新生成导出文件。在没有此缓存的新机器上，或者每当 IDA 分析发生更改时，请先运行 IDA 数据库导出： ``` tools/export_db.ps1 # generate .ida-exports/ from IDA Files/*.i64 tools/export_db.ps1 -DbName "BURNOUT_X360_ARTIST.XEX" ``` 然后根据需要重新构建派生的 DecFIGS/台账产物： ``` python tools/build_source_tree.py python tools/work/build_identity.py python tools/work/build_tu_index.py work seed --deps --reset ``` 有关完整的脚本清单和命令详情，请查阅 `tools/README.md`。

标签：AI合规, Bash脚本, C++, 云资产清单, 安全意识培训, 工作流管理, 数据擦除, 游戏开发, 网络安全研究, 网络调试, 自动化, 逆向工具, 逆向工程