AnyImage/AGENTS.md

AnyImage 项目规范

总则

不管是代码还是文档，遵循「少就是多」的原则，以好理解为首要要求

• 说明性内容以中文为主，专有名词和约定俗成的表达可使用英文
• 修改代码、依赖或执行方式后，
  • 不保留旧路径、转发函数、兼容层或胶水代码
  • 仅过测试，不改同步改文档，不构建文档、产物
• 优先选择依赖少、直接、易验证的实现
• 复用来自 common 的函数，避免重复造轮子
• 确保文件名/文件夹名和内容边界一致

全面整理代码

当用户说「全面整理代码」时，依据本文件规范，直接执行以下整理：

• 按业务职责梳理代码结构与命名；简单功能用单文件，复杂 Operator 功能包统一以 operators.py 为入口，__init__.py 负责导出与注册清单。
• 沿真实调用链清理无用代码，不把仅有测试引用当作业务用途；查证动态调用、框架回调和注册入口后再删除。
• 精简测试，保留有效行为覆盖，使测试名称、归属与功能对应，并检查状态隔离。
• 同步整理 tools/nodes、docs/internals 和相关引用，使名称、说明与实际实现一致。本触发指令包含内部文档整理。
• 保留已有的其他修改和有效功能，运行全量测试并确认正常退出，检查旧引用与最终差异，简要报告调整及验证结果；不构建文档或产物。

查询文档

下列是重要文档

• 总览：内部实现的总揽
• 程序架构：进程边界、职责与调用主链
• Operator 索引：Operator 实现功能和对应源码
• 节点资产：节点组的构建与验证（节点组不在运行时新建）

常见命令

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

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

# 运行全部测试
uv run pytest

# 构建 Windows、macOS、Linux 扩展包到 dist/
uv run pack

# 构建并验证 Blender 节点资产
uv run build_node

# 准备、校验并同步 ONNX 模型到 R2
uv run sync_models

命名规范

• 变量、函数、Docstring 必须使用英文；同一概念在代码和文档中使用统一表达

• 函数的动作前缀应表达产物边界：generate_* 表示 AI 生成。build_* 表示代码层构建。create_* 表示 Blender 内创建

• 名称应说明业务职责，并与用户概念、公开协议和界面术语保持一致；不要使用脱离上下文后无法判断用途的宽泛名称

• 文件和目录名应表达稳定的业务分类和模块职责，不直接沿用函数名，也不按临时执行步骤命名

• 集合层使用复数，单项分类使用单数

• 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 等既有名称

文档规范

• 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 节点组规范

• 节点组统一存入 assets/O_AnyImage.blend，运行时按名称加载（load_node_group(group_name)）
• 根据节点资产说明构建节点组，禁止调用 bpy.data.node_groups.new() 新建