mcpads/create-kr-patch-template

# 复古游戏韩文补丁项目模板 在确定平台和实现语言之前，这是首先建立补丁项目必须遵守的验证边界的起点。平台信息、文件格式、字体、压缩、补丁格式和工具选择将在目标调查后由项目确定。 此仓库中的 Rust 代码并非强制实现，而是可替换的参考实现。即使改用其他语言，只要对 [`conformance/`](conformance/) 中的反例判定出相同的结果即可。关于韩文化的判定方法由 [create-retro-game-kr-patch](https://github.com/mcpads/create-retro-game-kr-patch) 解释，而此模板以可执行的形式提供了在迭代构建中必须防止的失败。 ## 固定的边界 - 支持的原始文件通过大小和强哈希值进行标识。 - 对每个最终二进制产物的所有更改，都必须汇集到基于已验证原始文件的全局计划中，并且在应用之前，必须声明行为者、目的、预期原始文件和目标区域。 - 互相重叠的写入、保护区域的写入、预期原始文件不匹配以及未注册的最终更改总是会导致失败。 - 机器码区域不能被数据写入替换。如果没有实际对比汇编源码和 ISA 配置文件的项目验证器，机器码写入也会失败。 - 产品构建的根输入必须是纯源文件。如果将调查或 PoC 产物，或在流水线之外预先处理的衍生物作为产品输入连接，将会失败。 - 产品阶段生成的衍生物必须能够在同一产品图中重新生成，并且每个产物只能有一个生产者。 - 声称进行无更改往返的解析器、编解码器和重组阶段，必须在字节级别重现其声明的全部边界。 - 开发构建允许保留尚未完成翻译的项目作为原文，或使用明确选择的草稿。只有候选发布版本才要求对声明范围内的完成情况和当前翻译快照进行人工批准。 - 构建报告使用强哈希值标识所有的源输入和结果。执行成功不是附加到构建状态的标志，而是作为与相应的结果哈希绑定的独立证据进行记录。 在此边界内，调查顺序、实验次数、工具、数据格式和 CLI 命令不作固定。Agent 可以添加必要的子命令和目标实现，并从能够以最低成本改变当前判断的证据开始调查。 这里的纯源文件是指用户提供的原始文件以及受版本控制的翻译、配置和源码等可以作为产品起点的输入。在 `work/` 或 `out/` 中生成的文件、手动预处理的结果和 PoC 输出，即使附加了哈希值，也不会提升为纯源文件。 ## 调查与产品构建 调查和 PoC 是一个可以自由失败和丢弃的空间。当由此得出的结论成为产品所必需时，不要复制 PoC 结果文件，而是实现一个从纯源文件中重新生成相同结果的产品阶段。 ``` 순수 원천 ── 제품 단계 ── 제품 단계 ── 최종 이미지 └──── 검증 보고서 조사 입력 ── 탐색/PoC ── 관찰·근거 ╳ 제품 단계의 입력 ``` 产品图并非固定的步骤顺序。相互独立的步骤可以并行实现，当新证据推翻判断时，只需更改相关步骤。但是，无论通过哪条路径执行，最终产物都必须仅依靠已注册的产品图和纯源文件进行重现。 候选扫描器和基于评分的启发式方法是调查工具。一旦确认了地址、结构和常量，就应将它们移至可审查的目标规范中，并使用原始字节再次验证。产品构建可以检查是否找到了声明的值，但不应在每次执行时都选择最看似合理的候选项作为写入目标。 ## 仓库结构 - `assets/`：用于翻译片段和直接编写的字体、图形源码的项目骨架 - `config/`：目标项目需要填充的配置骨架 - [`src/`](src/)：将翻译选择、编码与二进制布局分离的产品实现骨架 - `tests/translation/`、`tests/placement/`：验证这两个实现边界及其连接的骨架 - [`research/`](research/)：与产品图分离的调查记录和可重现的 PoC 源码 - `conformance/`：不依赖于特定语言的强制判定和反例 - `adapters/emucap/`：可选的运行时验证适配器 - `reference/rust/crates/patch-guard/`：实现了上述判定的 Rust 参考库 - `reference/rust/examples/synthetic-cli/`：仅使用自构输入的可替换 CLI 示例 - `reference/python/poc/`：与产品 CLI 分离的 Python PoC 示例 - `AGENTS.md`：扩展此模板的 Agent 必须遵守的工作边界 目标项目可以复制合成示例并添加平台实现，也可以使用其他语言重新创建验证核心和 CLI。与其修改参考库以引入平台异常，不如扩展目标适配器和验证器，这样更容易保留边界。 ## 运行参考实现 ``` cd reference/rust cargo run -p synthetic-cli -- make-source --output out/demo/source.bin # 未用作产品输入的 Python 调查示例 python3 ../python/poc/scan_ascii.py \ --source out/demo/source.bin \ --evidence out/research/poc.json # 将未完成项保留为原文的开发 build cargo run -p synthetic-cli -- build \ --mode development \ --source out/demo/source.bin \ --translations examples/synthetic-cli/assets/demo.in-progress.json \ --output out/demo/development.bin \ --report out/demo/development-report.json # 声明范围已完成的 release candidate cargo run -p synthetic-cli -- build \ --mode release-candidate \ --source out/demo/source.bin \ --translations examples/synthetic-cli/assets/demo.complete.json \ --output out/demo/release.bin \ --report out/demo/release-report.json # 与从相同输入中新创建的结果进行字节级比较 cargo run -p synthetic-cli -- verify \ --mode release-candidate \ --source out/demo/source.bin \ --translations examples/synthetic-cli/assets/demo.complete.json \ --output out/demo/release.bin ``` `build` 没有接收 PoC 产物的选项。合成示例中的指针、编码和校验和只是为了完整运行自制格式而提供的示例，并非可以迁移到其他游戏的知识。 ## 扩展到目标项目时 1. 调查支持的原始文件和消费路径，并将针对特定目标的格式、地址和编码放在参考核心之外。 2. 将提取、编码、布局、重新插入和完整性修正全部连接到从纯源文件中重新生成的产品图中。 3. 在将解析器、编解码器、重组器放入产品路径之前，通过将无更改的输入通过相同路径来验证整体边界。未知结构应原样保留或在写入前拒绝，不保证字节一致性的转换也应将其更改包含在写入计划中。 4. 翻译资产格式应根据项目情况自行决定，但要验证稳定 ID、受保护的原文、控制 token、选择状态以及与审查快照绑定的发布批准。 5. 将更改最终产物的所有实现连接到 Expected Write 和整体 diff 审计。 6. 如果更改了机器码，请添加一个执行汇编源码、完整的 ISA 配置文件、组装结果匹配以及全范围解码检查的验证器。 7. 可以自由添加必要的 CLI 子命令，但旁路命令也必须通过相同的静态检查。 8. 区分运行时资产已存储的事实和实际被消费的事实。验证目标所需的存储、引用、加载、转换、驻留和消费边界，并将证据准确地绑定到结果哈希上。 9. 将重新应用分发补丁的结果与构建产物的等同性，以及实际执行路径，与构建分开进行验证。 对于运行时验证，建议使用 [emucap 适配器](adapters/emucap/)。此选择并非强制，可以替换为提供准确产物标识和独立证据的其他观察手段。如果选择了 `emucap`，请勿将安装和连接方法复制到项目中，而应遵循公开的发行版文档和本仓库的轻量级连接规则。 原始镜像和已打补丁的完整镜像不进行提交。仓库中只保留直接编写或已确认分发条件的输入，以及无法重现原始文件的结果。 ## 自我验证 默认不创建远程 CI。Agent 将在本地运行以下检查，而产生外部执行成本的自动化将由项目用户自行选择。 ``` python3 -m unittest discover -s reference/python/poc -p '*_tests.py' cd reference/rust cargo fmt --all -- --check cargo clippy --all-targets --all-features -- -D warnings cargo test --locked ```

标签：Rust, 可视化界面, 可重复构建, 复古游戏, 模板项目, 游戏汉化, 网络流量审计, 补丁工具, 逆向工具, 通知系统