AnyImage/AGENTS.md

AnyImage 开发约定

总则

• 说明性内容（提交说明、文档、注释、Mermaid 等）以中文为主，专有名词和约定俗成的表达可使用英文
• 动手前先读 docs/index.md；程序边界、调用流程和模块职责见 docs/development.md#程序设计
• 修改代码、依赖或执行方式后，同步更新 README.md 与对应主题文档，保持文档、测试和实现一致
• 优先选择依赖少、直接、易验证的实现；保留工作区中与当前任务无关的已有改动

项目结构

.
├── README.md                    # 用户入口与快速上手
├── docs/                        # 按功能拆分的设计与开发文档
├── pack.py                      # 构建各平台 Blender Extension ZIP
├── sync_models.py               # 准备并同步 ONNX 模型
├── src/anyimage/
│   ├── __init__.py              # Blender 注册入口
│   ├── operators.py             # Job Operator 与结果导入
│   ├── panel.py                 # 3D View 面板
│   ├── preferences.py           # Extension Preferences
│   ├── properties.py            # Scene 设置与动态枚举
│   ├── job_runtime.py           # BlendJob Runtime 配置
│   ├── blender/                 # Depth Plane、Surface 的 Blender 侧实现
│   ├── server/                  # Job、模型、ONNX 推理与输出实现
│   ├── assets/O_AnyImage.blend  # Geometry Nodes 与材质资产
│   └── wheels/                  # 随扩展分发的 BlendJob wheel
├── tools/                       # Blender 资产构建与验证脚本
└── tests/                       # Python 自动化测试

文档按主题定位：功能与使用 docs/features.md、Depth Plane docs/depth-plane.md、Surface docs/surface.md、输出格式 docs/outputs.md、Job Server docs/server.md、程序设计与开发 docs/development.md。

常见命令

优先在项目根目录使用 Git Bash；Windows 路径在 Bash 命令中使用正斜杠。

# 安装或同步开发依赖
uv sync

# 运行全部测试
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

# 本地 BlendJob wheel 内容变化后刷新锁文件
uv lock --refresh

资产脚本必须由 Blender 执行；具体入口与验证范围见 docs/development.md#资产构建与验证，不要用普通 Python 解释器运行。

命名规范

• 变量、函数、Docstring 使用英文；同一概念在代码和文档中使用统一表达
• 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 自身 Property 不加项目前缀，使用业务名称，如 input_path、process_res、resolution_level
• 扩展包名使用 Manifest 中的真实名称、版本和平台，例如 AnyImage.v0.11.2.windows-x64.zip；节点组名称沿用资产中的 O DA3 Depth Plane、O MoGe2 Surface 等既有名称

代码规范

• 避免不必要的嵌套，优先使用提前返回和小而明确的函数
• 只为特殊、非常规或存在兼容性原因的实现写注释，不复述代码本身
• 删除功能时同时删除无效参数、分支、测试和文档，不保留没有实际消费者的兼容层
• Blender 侧不载入 AI 依赖：UI、Operator 和结果导入放在 src/anyimage/ 或 src/anyimage/blender/，模型下载、ONNX 推理和输出放在 src/anyimage/server/
• 扩展级设置及其读取入口统一放在 preferences.py；使用 addon_preferences() 读取，不把 Blender Add-on Preferences 的定位、默认值或路径解析放进专门管理 BlendJob 的 runtime.py
• Job 参数使用可序列化的普通字典；Blender 数据只能在主线程的 Operator 响应阶段读写
• 新增或修改 Blender 类型时同步检查 src/anyimage/__init__.py 的注册与逆序注销，并补充对应测试
• 依赖版本、wheel 或 Manifest 改变时同步检查 pyproject.toml、uv.lock、blender_manifest.toml 和打包测试

文档与 Markdown 规范

• README.md 面向用户；实现原理放入 docs/ 对应主题，不在 README 堆叠内部细节
• 不使用 --- 分隔线；一级标题只在文档开头使用一次
• Mermaid 节点 ID 使用英文字符，节点显示文本可以使用中文
• 文档描述当前已实现行为；限制、默认值、命令和文件名必须能从代码或测试中验证