Add tools and tests for AnyImage model management and documentation

- Implement sync_models.py for preparing and uploading ONNX artifacts.
- Create build_node.py for building and validating Blender scripts.
- Add docs.py for building and previewing documentation with Mike or MkDocs.
- Introduce model_exports.py for exporting PyTorch models to ONNX format.
- Develop pack.py for packaging the project with dependencies for different platforms.
- Add test_sync_models.py to validate sync_models functionality.
- Add test_tool_commands.py to ensure repository tools have correct command scripts.
- Initialize tools package with __init__.py.

AGENTS.md

@@ -1,103 +1,90 @@
-# AnyImage 开发约定
+# AnyImage 项目规范
 
 ## 总则
 
-- 说明性内容（提交说明、文档、注释、Mermaid 等）以中文为主，专有名词和约定俗成的表达可使用英文
-- 动手前先读 `docs/index.md`；程序边界、调用流程和模块职责见 `docs/internals/index.md` 与 `docs/internals/architecture.md`
-- 修改代码、依赖或执行方式后，同步更新 `README.md` 与对应主题文档，保持文档、测试和实现一致
-- 优先选择依赖少、直接、易验证的实现；保留工作区中与当前任务无关的已有改动
+**不管是代码还是文档，遵循「少就是多」的原则，以好理解为首要要求**
 
-## 内部实现文档
+- 说明性内容以中文为主，专有名词和约定俗成的表达可使用英文
+- 修改代码、依赖或执行方式后，
+  - 不保留旧路径、转发函数、兼容层或胶水代码
+  - 仅过测试，不改同步改文档，不构建文档、产物
+- 优先选择依赖少、直接、易验证的实现
+- 复用来自 `common` 的函数，避免重复造轮子
+- 确保文件名/文件夹名和内容边界一致
 
-- [内部实现总览](docs/internals/index.md)：内部实现文档的统一入口
+## 查询文档
+
+下列是重要文档
+
+- [总览](docs/internals/index.md)：内部实现的总揽
 - [程序架构](docs/internals/architecture.md)：进程边界、职责与调用主链
-- [Operator 实现索引](docs/internals/operators/index.md)：源码功能与实现页的对应关系
-
-修改完整工作流时同步更新对应实现页。`operators/common/` 不单独建立页面，共享边界写入程序架构。
-
-## 模块与目录边界
-
-- 目录结构应能直接表达业务模块和职责；优先按用户可理解的功能或稳定能力组织，不按模糊的数据类型、临时步骤或界面摆放机械分组
-- 一个模块只承担一个可描述的职责。功能出现多个相对独立的交互、算法或构建阶段时再建立子目录，并让同一抽象层的实现并列
-- 公共层来自已经存在的复用，不来自对未来的猜测。没有真实共享消费者的代码留在所属模块；抽取后只暴露消费者需要的最小接口
-- 模块边界优先服从运行进程、依赖方向、数据所有权和生命周期。只在一侧处理的数据不为形式上的“共享”跨越边界；确因加载机制产生的例外应在架构文档中说明
-- 编排层只组合步骤和定义公开协议，原子能力放在所属领域模块。编排模块之间不互相导入实现，共享逻辑应下沉
-- 公开任务与界面入口不要求一一对应；边界由可复用计算、输入输出协议和失败语义决定。名称必须描述实际动作与产物，不暗示未承担的职责
-- 没有生产消费者的入口、兼容层和辅助协议应删除，不为测试便利单独保留
-- 移动或拆分模块时同步更新注册、导入、打包、测试和文档，不留下旧路径转发层
+- [Operator 索引](docs/internals/operators/index.md)：Operator 实现功能和对应源码
+- [节点资产](docs/internals/node-assets.md)：节点组的构建与验证（节点组不在运行时新建）
 
 ## 常见命令
 
-优先在项目根目录使用 Git Bash；Windows 路径在 Bash 命令中使用正斜杠。
-
 ```bash
 # 安装或同步开发依赖
 uv sync
 
+# 本地 BlendJob wheel 内容变化后刷新锁文件
+uv lock --refresh
+
 # 运行全部测试
 uv run pytest
 
-# 运行插件注册、Manifest 与打包相关的快速测试
-uv run pytest tests/test_addon.py tests/test_manifest.py tests/test_pack.py -v
-
 # 构建 Windows、macOS、Linux 扩展包到 dist/
-uv run python pack.py
+uv run pack
 
-# 本地 BlendJob wheel 内容变化后刷新锁文件
-uv lock --refresh
+# 构建并验证 Blender 节点资产
+uv run build_node
+
+# 准备、校验并同步 ONNX 模型到 R2
+uv run sync_models
 ```
 
-资产脚本必须由 Blender 执行；具体入口与验证范围见 [节点资产](docs/internals/node-assets.md)，不要用普通 Python 解释器运行。
-
-`tools/` 中的脚本按维护对象分组，并统一使用能够区分“构建”和“验证”等动作的命名。每个脚本都应有明确入口、文档或测试消费者；没有实际用途的脚本应删除。
-
 ## 命名规范
 
-- 变量、函数、Docstring 使用英文；同一概念在代码和文档中使用统一表达
-- 函数的动作前缀应表达产物边界：`generate_*` 表示 AI 生成，`build_*` 只在内存中构建值或几何，`create_*` 表示创建 Blender Image、Mesh、Material、Object 等真实数据
+- 变量、函数、Docstring 必须使用英文；同一概念在代码和文档中使用统一表达
+- 函数的动作前缀应表达产物边界：`generate_*` 表示 AI 生成。`build_*` 表示代码层构建。`create_*` 表示 Blender 内创建
 - 名称应说明业务职责，并与用户概念、公开协议和界面术语保持一致；不要使用脱离上下文后无法判断用途的宽泛名称
-- 文件和目录名应表达稳定的业务分类和模块职责，不直接沿用函数名，也不按临时执行步骤命名；集合层使用复数，单项分类使用单数，同一层级保持一致
-- Python 类使用大驼峰，不添加项目名前缀。Operator 使用动宾结构，如 `ConvertToDepthPlane`、`RemoveImageBackground`；Menu、Panel、AddonPreferences、PropertyGroup 分别使用实际类型后缀，如 `AnyImageImageMenu`、`ServerPanel`、`AnyImagePreferences`、`AnyImageSettings`
-- `bl_idname` 与挂载到公共 Blender RNA 类型的 Property 使用 `anyimage` 项目前缀：Operator 如 `anyimage.convert_to_depth_plane`，Menu 如 `ANYIMAGE_MT_image_context`，Panel 如 `ANYIMAGE_PT_server`，公共 Property 如 `Scene.anyimage_settings`
+- 文件和目录名应表达稳定的业务分类和模块职责，不直接沿用函数名，也不按临时执行步骤命名
+- 集合层使用复数，单项分类使用单数
+
+- Operator Class 使用动宾结构，如 `ConvertToDepthPlane`、`RemoveImageBackground`
+- Menu、Panel、AddonPreferences、PropertyGroup 分别使用实际类型后缀，如 `AnyImageImageMenu`、`ServerPanel`、`AnyImagePreferences`、`AnyImageSettings`
+- `bl_idname` 使用 `anyimage` 项目前缀：
+  - Operator 如 `anyimage.convert_to_depth_plane`
+  - Menu 如 `ANYIMAGE_MT_image_context`
+  - Panel 如 `ANYIMAGE_PT_server`
+  - 公共 Property 如 `Scene.anyimage_settings`
 - Operator 自身 Property 不加项目前缀，使用业务名称，如 `input_path`、`process_res`、`resolution_level`
 - 扩展包名使用 Manifest 中的真实名称、版本和平台，例如 `AnyImage.v0.11.2.windows-x64.zip`；节点组名称沿用资产中的 `O DA3 Depth Plane`、`O MoGe2 Surface` 等既有名称
-- 常量应表达领域约束、共享数值或稳定映射，不为字面量增加没有额外语义的同名别名；需要类型约束时使用集中映射或 Enum
-- 同一发布单元的版本只保留一个事实来源。只有存在独立兼容周期和实际消费者时，才引入额外版本或迁移状态
 
-## 代码规范
+## 文档规范
 
-- 避免不必要的嵌套，优先使用提前返回和小而明确的函数
-- 只为特殊、非常规或存在兼容性原因的实现写注释，不复述代码本身
-- 删除功能时同时删除无效参数、分支、测试和文档，不保留没有实际消费者的兼容层
-- Blender 侧不载入 AI 依赖：UI、Operator 和结果导入放在 `src/anyimage/` 或 `src/anyimage/operators/`，模型下载、ONNX 推理和输出放在 `src/anyimage/server/`
-- 扩展级设置及其读取入口统一放在 `preferences.py`；使用 `addon_preferences()` 读取，不把 Blender Add-on Preferences 的定位、默认值或路径解析放进专门管理 BlendJob 的 `runtime.py`
+- `README.md` 面向用户，不在其中堆叠内部细节。实现原理放入 `docs/internals` 对应主题
+- 文档只正面描述当前主题的职责与实现，不记录无关模块、未采用路径、历史差异、边界辩解、“不做什么”的排除性信息。
+- 实现原理用流程图替代文字，Mermaid 默认使用从上到下
+
+## Blender 开发规范
+
+- 扩展级设置及其读取入口统一放在 `preferences.py`；使用 `addon_preferences()` 读取
 - Job 参数使用可序列化的普通字典；Blender 数据只能在主线程的 Operator 响应阶段读写
 - 新增或修改 Blender 类型时同步检查 `src/anyimage/__init__.py` 的注册与逆序注销，并补充对应测试
 - 依赖版本、wheel 或 Manifest 改变时同步检查 `pyproject.toml`、`uv.lock`、`blender_manifest.toml` 和打包测试
-
+- `server/` 是 blendjob 后端代码，无法引用来自它上级文件夹的内容。共享函数需单独实现。
 
 ## Blender 节点组规范
 
-资产脚本必须由 Blender 执行；具体入口与验证范围见 [节点资产](docs/internals/node-assets.md)，不要用普通 Python 解释器运行。
-
-`tools/` 中的脚本按维护对象分组，并统一使用能够区分“构建”和“验证”等动作的命名。每个脚本都应有明确入口、文档或测试消费者；没有实际用途的脚本应删除。
-
-- 生产运行时使用的可复用节点组必须构建并存储在 `src/anyimage/assets/O_AnyImage.blend`，由统一资产加载入口按名称加载；不得在 `src/anyimage/` 中通过 `bpy.data.node_groups.new()` 动态创建。节点组新增、修改或删除时同步更新资产构建、验证、测试和节点资产文档
-
-- 不修改节点的 `name`，也不使用 `label` 覆盖节点标题；保留 Blender 为节点类型生成的默认名称和外观，避免读图时无法判断节点原型。用途应通过节点类型、参数、空间布局和必要的少量注释表达
-
-- 节点图优先依靠清晰的空间层次表达流程，不用五颜六色的 Frame 做分类；仅在重复区、模拟区等确有包裹语义时少量使用 Frame，并保持配色克制
-- 避免跨越大段节点图的连线；来自 Group Input 的参数可按使用区域放置多个 Group Input，并隐藏未连接的 sockets
-- 主处理链尽量保持为一根从左到右连续可见的几何主线，辅助字段和控制分支放在主线上下两侧，就近汇入消费者
-- 避免交错连线、节点重叠和不必要的回折；新增或重建节点组时检查节点坐标唯一性和主要连线方向
-- Repeat、Simulation、For Each Geometry Element 等具有输入/输出“头尾”的成对结构，应先确定完整包裹范围，再放置内部节点，保证头尾顺序、配对关系和区域边界一眼可辨
-- 作为修改器使用的 Geometry Nodes，除确实需要动态字段或其他结构的接口外，输入 socket 的 structure_type 应设为 SINGLE
-- 为接口 socket 设置符合业务含义的 `subtype`；例如表示 Blender 场景实际长度的浮点输入使用 `DISTANCE`，明确限制为 `0–1` 的比例使用 `FACTOR`，以 `0–100` 表示的百分比使用 `PERCENTAGE`，角度使用对应 subtype。无上限倍率等不符合范围语义的数值保留普通 Float，不为显示形式强套 subtype
-- 调整节点接口或布局后，应补充或更新 Blender 验证，检查 socket 顺序与结构、节点不重叠、Group Input 未使用输出已隐藏，以及几何主线可正常求值
-
-## 文档与 Markdown 规范
-
-- `README.md` 面向用户；实现原理放入 `docs/` 对应主题，不在 README 堆叠内部细节
-- 不使用 `---` 分隔线；一级标题只在文档开头使用一次
-- Mermaid 节点 ID 使用英文字符，节点显示文本可以使用中文
-- 文档描述当前已实现行为；限制、默认值、命令和文件名必须能从代码或测试中验证
+- 节点组统一存入 `assets/O_AnyImage.blend`，运行时按名称加载（`load_node_group(group_name)`）
+- 节点组通过[节点资产](docs/internals/node-assets.md)说明构建，禁止运行时调用 `bpy.data.node_groups.new()` 新建
+- 节点组变更须同步构建脚本、验证、测试和节点资产文档
+- 保留节点默认 `name` 和标题，不用 `label` 覆盖
+- 主链从左到右连续排列；辅助分支就近汇入，避免长线、交错、重叠和回折
+- Group Input 可按区域重复放置，并隐藏未连接 sockets
+- Frame 仅用于确有包裹语义的区域
+- Repeat、Simulation、For Each Geometry Element 等成对节点，确保位置正确，没有遮挡其他节点
+- 修改器 Geometry Nodes 的输入 socket 默认使用 `SINGLE`
+- socket `subtype` 按业务语义设置：长度用 `DISTANCE`，`0–1` 比例用 `FACTOR`，`0–100` 用 `PERCENTAGE`；无对应范围语义时保留默认
+- 接口或布局变更须验证 socket 顺序与结构、节点不重叠、未使用输出隐藏及几何求值