目录结构
三块都在
uvpack/ 下，不需要跨目录引用。| 路径 | 说明 |
|---|---|
cpp/src/ | C++ 引擎源码，核心 bitmap_pack.cpp、nfp.cpp、packer.cpp、uv_layout.cpp |
cpp/*_test.py | C++ 侧性能与正确性测试 |
cpp/blender_plugin/ | 旧副本 v2.5.0，仅参考，勿改 |
blender_plugin/ | 正式插件 v2.7.2（id = uv_engine_tools） |
dev/ | 测试台：探针、bench、dev_cycle、dashboard、进度文档 |
开发流程
# 编译 + 部署 + 跑对比（macOS，Windows 见下方警告） bash dev/dev_cycle.sh # 编译+部署+对比 bash dev/dev_cycle.sh --no-build # 跳过编译，只跑对比 bash dev/dev_cycle.sh --seeds 5 # 跑 5 次取 median（随机算法用） # 离线跑分 / 自动测试 python dev/offline_bench.py python dev/auto_test_pack.py # 打包插件（仓库根执行） ./build.sh --module uv
Windows 注意：
dev_cycle.sh 是 macOS 专用，硬编码 /Users/lzc/...、clang++、.cpython-313-darwin.so。在 Windows 上直接跑会失败，需要另写一份编译命令。跑 dev_cycle.sh 还要求 Blender 开着、BlenderMCP addon 连上 9876 端口、Test_UVPack.blend 已加载。注意点
每条都附了原因，知道「为什么」才不会重踩。
| 注意点 | 注释 |
|---|---|
编译必须包含 bitmap_pack.cpp |
-undefined dynamic_lookup 会让漏掉的 .cpp 静默通过链接，运行期才崩。2026-08-31 就这样漏了该文件，Blender 侧一开 use_bitmap 直接崩溃。现已加「未定义符号护栏」，但编译时仍要确认文件列表。 |
不改 BitmapPackOptions 默认值 |
默认值 == 74.0% 定稿行为，已实测 overlap 0 / valid=Y。改了基线就失效，跑分不可比。 |
| 不追那 2.5 点利用率 | 已实验证否：邻域松弛重插入 74.0%→74.0% 零提升（+33ms 纯开销，根因是贪心 bottom-left 已局部最优）；8 档旋转反而降到 71.9% 且慢 2.6 倍。两个负结果存档在 dev/experiments/*.patch，别重做。 |
| 护栏可能骗你 | 回归护栏曾在 -79.7% 巨大倒退下打印 PASS——判定依赖不存在的 uvpm4_baseline.json，条件短路导致静默失效。现已加 GUARD_MAX_GAP_PCT 绝对差距护栏，但看到 PASS 仍建议扫一眼实际数值。 |
| 确认实际走哪条路径 | Blender 插件曾从未设置 use_bitmap，C++ 侧默认 false = 走旧凸包 NFP 路径。改动时先确认实际生效的是哪条，否则优化了半天没生效。 |
| 探针不能直接跑 | dev/ 下 40+ 个 _probe_*.py 硬编码 macOS 路径 /Users/lzc/Documents/Test/...，Windows 上用前先改路径。 |
不引用 _archive/blender_cpp_old_engine |
那是 UVpack 引擎的旧快照，缺 bitmap_pack.cpp，已废弃。 |
改动前必读（分级）
规则里已写成硬性门禁：未读项目根
AI_CONTEXT.md 之前禁止改任何代码。| 改动类型 | 必读 | 成本 / 说明 |
|---|---|---|
| 任何改动 | AI_CONTEXT.md | ~900 token 无条件必读 |
| 接手续做 / 动打包算法 | dev/HANDOFF.md | ~7.7k token 贵，只在真动算法时读 |
| 调参 / 性能优化 | dev/optimization_log.md | ~1.8k token |
| 动 Blender 插件 | blender_plugin/ | 小 |
纯咨询、只问问题、不改代码时，不需要读任何文件。