# 给 AI 代理的说明（S2Arm）

你在为 S2Arm 开发：把 Switch 游戏零配置移植到 iPhone / Mac / 安卓 / 鸿蒙。动手前按顺序读：

1. [CONTRIBUTING.md](CONTRIBUTING.md)：如何贡献、分支、提交、安全规矩。
2. [docs/贡献指南.md](docs/贡献指南.md)：开发流程、代码风格、测试要求。
3. [docs/坑记录.md](docs/坑记录.md)：先按当前任务关键词搜索坑记录标题和正文，只读匹配条目；不要把整份坑记录装进上下文。
4. [docs/贡献者开发测试套件.md](docs/贡献者开发测试套件.md)：**四步闭环**——自查（一条命令出标准化报告）→ 自纠（按症状查 `docs/排查/` 手册）→ 自修 → 提 PR 与回报。
5. [skills/s2arm-rootfix/SKILL.md](skills/s2arm-rootfix/SKILL.md)：**修任何问题前先加载**——先量再猜、修机制不修症状、对齐 Ryujinx 真值、先红后绿、负对照、报射程；按症状再加载 `skills/gfx-triage/` 或 `skills/native-triage/`。

必须遵守：
- 不直接推 `main`，只提 PR；只改 issue 写明的目录。
- **分支要短**：一个 PR 只做一件事，目标几小时内合入；做不完就拆成几个能各自验收的 PR。
- **main 红了先修 main**：你的合入弄红了 main，当轮修；修好前不往同一块堆新改动。
- **贡献者**提 PR 前跑 `bash tools/contrib_check.sh`，把摘要贴进 PR 描述（详见 [CONTRIBUTING.md](CONTRIBUTING.md) 验证改动章节）。
- 游戏文件、密钥、存档、资源包不进仓库、不进 PR / 评论。
- 通用层零专用配置：不写死游戏地址、不按函数名拦截游戏 SDK（唯一例外：直连前端接管三类图形 API 取函数入口）、未实现的服务一律报红，不返回成功兜底。
- 评论与 PR 用中文写清：问题、改动、实际验证、限制。
- 性能类改动给读数：先有全账再动手，能耗至少 3 局取中位并标热状态 / 充电，A/B 一次只差一个变量，读回 / 同步类以真机为准。读数格式用「期望 → 真结果」对位表。
- 踩到新坑或得到新的经验结论，**自己追加**到 [docs/坑记录.md](docs/坑记录.md)，随你的 PR 一起提交。只写客观事实：现象 → 根因 → 实验数据（期望 → 真结果，注明设备 / 包号或提交号 / 局数）→ 做法；不写主观判断、感想和过程叙述，没有读数支撑的不写。