OnePlus15-Port-Script

Imported from yangFenTuoZi/OnePlus15-Port-Script (AGENTS.md). Install upstream with npx skills add yangFenTuoZi/OnePlus15-Port-Script. Copyright stays with the author.

AGENTS.md

本文件适用于 port/ 及其全部子目录。后续修改应以当前仓库实现为准；如用户给出更具体要求，以用户要求优先。

项目定位

这里维护 HyperOS 移植补丁模块，不是通用刷机脚本集合。修改目标是让补丁在明确的来源分区、目标分区和元数据约束下可重复执行，并尽量在写入工作树前暴露错误。

• common/<patch>/apply.sh：可被大部分机型组合复用的共享补丁、兼容处理与公共流程；位于 common 不代表无需检查底包前提。
• features/<patch>/apply.sh：按目标设备能力显式启用或配置的可复用硬件特性模块；例如 LTPO、超声波指纹或 Oplus 指纹协议。
• devices/<device>/<patch>/apply.sh：补丁逻辑或资源本身无法抽象为共享模块、只能服务指定设备时才使用。若逻辑可复用而仅硬件参数不同，应把逻辑放进 features，由对应机型组合入口提供 .props 参数文件；例如超声波指纹位置参数由 OP15_port.sh 传入，而不写进特性模块或从原包推断。
• port_main.sh：补丁发现、选择和隔离执行入口。
• OP15_port.sh：一加 15 当前组合流程。
• tools/tools.sh：Shell 公共接口、配置模板和安全文件操作。
• tools/partition_metadata.py：contexts/fsconfig 的复杂处理工具。
• tools/toolchain.sh：特殊 CLI 的统一解析入口；本机绝对路径只能写入未提交的 local.properties。

不要把设备专属逻辑下沉到通用工具，也不要把共享能力复制到多个补丁中。features 只能表达适用条件，不能成为隐藏具体机型硬编码的目录。

只维护当前版本

• 不为旧版脚本、旧函数名、旧环境变量或历史文件命名增加兼容层。
• 不扫描任意 *_config 目录，也不增加旧名称自动回退；只支持 tools.sh 明确定义的配置 profile。
• 删除或重命名公共接口前，先用 rg 检查仓库内全部调用方，并在同一改动中完成迁移。
• 发现当前实现、README 和生成数据不一致时，不要静默兼容；应统一当前规范或明确报告冲突。

配置目录与名称模板

配置目录优先级和名称模板必须集中定义在 tools/tools.sh，补丁内不得自行拼接 contexts/fsconfig 文件名。当前代码定义为：

两者同时存在时优先 DNA_config。如果后续调整模板，必须同时更新 tools/tools.sh、README、本文档和相关测试。

补丁必须通过以下接口取路径：

• get_config_path
• get_part_contexts_path
• get_part_fsconfig_path

不得在补丁中硬编码 DNA_config、config 或具体 metadata 文件名。

设备身份识别与传递

• init_port_env 必须在首个补丁修改工作树前集中识别底包与原包设备，并保证同一移植流程中的所有补丁消费同一份身份快照。
• 下游补丁统一读取 PORT_BASE_DEVICE_CODE、PORT_BASE_DEVICE_NAME、PORT_BASE_DEVICE_MODEL、PORT_BASE_DEVICE_MARKET_NAME 及对应的 PORT_SOURCE_DEVICE_*；机型 XML 使用 PORT_SOURCE_DEVICE_FEATURE_FILE。
• 补丁内不得写死原包或底包设备名、代号、机型 XML 文件名，也不得重新从可能已被前序补丁修改的 ODM 属性推断身份。
• 明确由组合流程选用的 SKU 附加 prop 不属于设备识别结果，可以由组合入口通过 DEVICE_IDENTITY_PROP 指定；公共补丁不得自行写死其文件名。附加 prop 不存在时只弱警告并跳过附加合并，基础设备标识写入继续执行。
• 依赖实际运行设备的面板、传感器、马达、指纹位置等能力或试错参数，不得从原包推断；优先从底包可靠配置读取，否则由目标机型组合入口通过校验过的 .props 文件显式提供。逻辑可参数化时放在 features，只有逻辑或资源仍无法复用时才放在 devices/<device>。设备专属目录名和专属预编译产物名不属于运行时身份识别接口。

分区语义

• odm、vendor 是底包的最终目标工作树。
• product、system、system_ext 是原包的最终目标工作树。
• mi_odm、mi_vendor 仅是额外来源目录，必须分别映射到最终 odm、vendor，不能成为最终分区名。
• mi_ext 由专用补丁合并到真实目标路径，不能把整个来源分区直接当作最终产物。
• contexts 路径以 / 开头；fsconfig 路径不以 / 开头。
• 注意工程中的 system 文件树通常位于 system/system/...，metadata 路径也必须与真实打包路径一致。

任何跨分区复制或迁移都必须同时检查文件路径、contexts 和 fsconfig 的来源与目标映射。

补丁实现规则

• apply.sh 由 port_main.sh 加载，不要在每个补丁中重复导入 tools/tools.sh。
• 补丁开头调用 init_port_env "${1:-}"，并根据复杂度启用 set -euo pipefail 或等价严格模式。
• 先完成依赖、来源文件、目标分区、metadata 和外部工具校验，再开始修改工作树。
• 创建新补丁前，必须先用 rg 检查现有 common、features 与 devices 补丁的相似语义、目标分区、来源和依赖；如果已有相似语义，应优先合并到现有补丁，不得为了极小改动新建孤立补丁。只有目标边界、生命周期、依赖或执行顺序确实独立时，才允许新建补丁，并说明拆分理由。
• 修复策略遵循最小侵入原则：优先通过补齐文件、替换资源、修改配置或属性，以及同步 metadata 解决问题；只有确认这些方式无法满足目标时，才允许修补 APK、DEX、二进制、HAL 或其他系统组件，并在补丁说明中写明不可避免的原因、影响范围、签名或完整性风险及验证边界。
• 补丁应可重复执行：已经完成的状态应安全跳过或得到相同结果，不能不断追加重复条目。
• 使用 std_print、skip_print、warn_print、err_print 输出简洁中文状态，不输出无意义调试噪声。
• 现有补丁中的 prop 子步骤不得因属性来源文件、目标文件、属性清单或预期属性条目缺失而失败；缺失时使用 warn_print 警告并只跳过对应 prop 子步骤，混合补丁的非 prop 主流程继续执行。已经存在但格式无效、属性重复、值冲突或符号链接不安全的文件仍应失败。
• 明确用于替换或修补既有文件的子步骤，若目标文件不存在，应使用 warn_print 警告并只跳过该子步骤；同一补丁中的独立迁移或其他处理继续执行。已经存在但类型错误、版本或校验不受支持、内容冲突或使用不安全符号链接的目标仍应失败。此规则不适用于本来就要新增的文件、跨分区迁移目标、生成产物或 metadata 输出，不得通过放宽 replace_file_if_different 等公共接口把新增与替换语义混为一谈。
• 临时文件必须使用 mktemp，并通过 trap 或明确清理路径回收。
• 优先使用 tools.sh 中已有的安全操作函数，不要重复实现复制、替换、属性合并或受控删除逻辑。
• 删除项目文件必须使用 remove_path_if_exists；不得使用宽泛变量、未解析 glob 或面向项目根目录的递归删除。
• 不要修改与当前补丁目标无关的分区内容。

contexts 与 fsconfig

复杂 metadata 逻辑放在 tools/partition_metadata.py，Shell 仅保留参数准备和薄封装。不要重新用大段 awk/sed 实现同一套合并、迁移或去重算法。

必须遵守以下规则：

• 补丁条目按路径覆盖目标旧条目。
• 修改 metadata 时对整个目标文件按路径去重。
• contexts 比较路径时忽略反斜杠转义差异，但写回时保留最终选中条目的原始表达形式。
• 注释和空行不是路径条目，不应因为路径去重而被吞掉。
• 按文件清单迁移时，清单内每个文件都必须同时存在 contexts 与 fsconfig 来源条目；缺少任何一项应在复制前失败。
• 按目录前缀迁移时，同时迁移 contexts 与 fsconfig，并处理 contexts 常见的 (/.*)? 等目录正则形式。
• 删除文件或目录时，同步删除该路径及子路径的 contexts/fsconfig 条目。
• 仅修改既有文件内容且不改变路径、所有者、权限或能力字段时，通常不需要改 fsconfig。
• 新增文件、跨分区复制文件、创建符号链接或新目录时，必须补齐最终分区 fsconfig；需要 SELinux 路径时同时补齐 contexts。
• 新生成的二进制、APK、RC 或配置文件不得依赖打包工具猜测权限。
• metadata 写回应保留目标文件模式，并使用原子替换；不要直接截断后原地拼接。

Shell 规范

• 所有变量展开默认加双引号，数组使用 "${array[@]}"。
• 路径参数先验证，再交给 cp、mv、chmod、find 等命令，并使用 -- 分隔选项。
• 搜索文件和文本优先使用 rg / rg --files。
• 不使用 eval，不依赖不受控的命令替换来生成删除或覆盖目标。
• 不覆盖 HOME、PATH 等通用环境变量作为临时状态。
• ShellCheck 抑制必须靠近对应代码，并注明原因；不要用全文件关闭掩盖新问题。
• 对全局变量或由 init_port_env 注入的变量，保持命名一致，不在局部重新定义含义不同的同名变量。

真实设备调试与 DSU 约束

涉及真实 Android 设备时，运行时数据提取与静态分析具有同等优先级，应根据问题选择并相互校验；需要运行时证据时，应尽早请求设备授权，并按以下顺序操作：

1. 如果发现环境中存在可用的 adb 设备，必须把授权询问置于首要位置，立即询问用户是否同意使用真实设备进行调试。取得明确同意前，不执行任何设备调试、读取、写入、日志采集、服务重启、mount 或重启操作；等待授权期间可以继续静态分析或其他不触碰设备的工作，但不得将静态推断当作运行时事实。设备存在性探测仅限于不改变设备状态的检查。

2. 开始调试前，先确认设备当前是否处于 DSU 移植系统。原系统只可用于提取分区文件；只有 DSU 系统才可用于直接调试、热更新分区和验证系统服务。

3. DSU 系统与原系统不共享 data 分区。因此，原系统的 /data/adb/ksu/log/ 不可能存储 DSU 系统的崩溃日志；采集崩溃日志时必须从 DSU 当前环境及其实际日志路径获取。

4. DSU 系统默认允许 adb root，但不一定能够访问 su。如果发现 adb 未处于 root shell，可在用户已授权的调试流程中执行：

   adb root

   不要把 su 是否可用当作判断 adb root 状态的依据。

5. 在用户已授权且已确认当前为 DSU 系统后，可以通过 mount 热更新分区，并重启相关系统服务进行测试。由于 data 的 F2FS 存在问题，所有 mount 源文件只能存放在 tmpfs。

6. 尽量不要擅自重启设备；只有确有必要时，先说明原因并征得用户同意。直接执行重启一定会进入原系统；如确需重启并希望下一次进入 DSU，应在获得同意后先使用以下命令将 DSU 单次固化到下一次启动：

   gsi_tool enable --single-boot --dsuslot dsu

用户协作与复现

• 应根据任务进展随时建立并更新临时备忘录，记录目标、关键事实、已完成工作、未决事项和验证结果，防止上下文压缩后丢失重要信息。
• 在修复多个相互独立或可安全拆分的问题时，可以启用子智能体并行处理，以缩短处理时间并减轻主智能体的上下文压力。拆分前应明确各子任务的边界，避免多个智能体同时修改同一文件或共享状态；最终由主智能体统一检查、整合并验证结果。
• 长日志读取、或者存在可以同时互补不干扰的多个反编译分析任务时，可以启用子智能体并行处理，以缩短处理时间并减轻主智能体的上下文压力。
• 默认用户会积极配合测试。需要用户操作、观察界面或提供现场结果时，直接提出具体请求即可，不要因为担心打扰而反复猜测。
• 对命令行难以可靠实现、需要交互操作，或需要大量命令反复试探才能复现的问题，优先请用户按最短且明确的步骤执行，并返回现象、日志或截图；请求应说明前置条件、预期结果和停止条件。
• 涉及真实设备的用户操作仍须遵守上一节的授权、DSU、挂载和重启约束。

Python 规范

• tools/partition_metadata.py 优先使用 Python 标准库，不为简单 metadata 操作增加第三方依赖。
• CLI 错误输出到 stderr，并返回非零状态；不要打印 Python traceback 作为正常用户错误。
• 路径、manifest、分区映射和输出目标必须在写入前验证。
• 保持操作确定性：相同输入应生成顺序稳定的相同输出。
• 测试或检查时设置 PYTHONDONTWRITEBYTECODE=1，不要把 __pycache__、.pyc 或临时输出留在仓库。

文档同步

以下变化必须同步更新 README：

• 配置目录优先级或文件名模板。
• 新增、删除或重命名补丁。
• 补丁所需来源分区、目标分区或外部依赖。
• 补丁新增的 contexts/fsconfig 迁移、权限写入或清理行为。
• 已知的设备限制、签名影响或刷机后才能确认的行为。

不要把未经设备验证的结论写成已经确认生效。

最低验证要求

修改 Shell、Python 或 metadata 逻辑后，至少执行：

git diff --check
rg --files -g '*.sh' -0 | xargs -0 -n1 bash -n
PYTHONDONTWRITEBYTECODE=1 python3 -c 'import ast, pathlib; ast.parse(pathlib.Path("tools/partition_metadata.py").read_text(encoding="utf-8"))'

修改过的 Shell 脚本还应运行 ShellCheck。对 SC2016、SC2154 等确有意图的情况，只允许有依据地局部处理。

metadata 改动还应覆盖以下行为测试：

• DNA_config 与 config 两套 profile 的检测、优先级和文件名生成。
• contexts/fsconfig 补丁覆盖和重复路径去重。
• contexts 转义路径匹配。
• manifest 迁移、目录前缀迁移和源条目缺失失败。
• 删除路径及子路径条目。
• 写回后目标文件模式保持不变。

可以使用临时工程做集成测试。除非用户明确要求，不要为了验证直接在真实解包分区树上执行整套移植补丁；交付时必须说明验证是静态检查、临时工程测试还是真实分区执行。

工作区约束

• 修改前先查看 git status --short 和相关文件 diff，保留用户已有改动。
• 不清理、不回滚、不格式化与当前任务无关的文件。
• 不生成提交、分支或推送，除非用户明确要求。
• 交付前再次检查 git diff --check、未跟踪临时文件和 Python 缓存。