feat: Enhance AI integration for Cutout, Image Box, and Image Lasso tools with unified settings and improved shape selection

openspec/changes/gate-cutout-ai-options/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-31

openspec/changes/gate-cutout-ai-options/design.md

@@ -0,0 +1,46 @@
+## Context
+
+Cutout、Image Box 和 Image Lasso 都通过 View3D WorkSpaceTool 设置暴露 `Fit to Foreground`。共享绘制函数当前先绘制禁用的属性，再在末尾追加 AI 设置按钮；Cutout 还直接绘制 `Generate Normal Map`，并始终在 shape pie 中提供两个本地 shape 和两个 Depth shape。
+
+AI 可用性已经由 `ai_status()` / `ai_ready()` 统一表示，包含运行环境和所需模型状态。实现应继续复用该状态，不引入第二套环境判定。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 三个工具在 AI 未就绪时都将 AI 设置入口放在工具设置开头。
+- 所有依赖 AI 的属性在未就绪时不可编辑，且遗留值不会触发 AI job。
+- Cutout shape pie 根据 AI 可用性展示两个或四个候选。
+- 保持共享绘制和状态判定逻辑集中，便于 Image Box、Image Lasso 与 Cutout 复用。
+
+**Non-Goals:**
+
+- 不删除或重构四个 Cutout shape 及其节点资产。
+- 不改变 AI 环境安装流程、模型目录、job 协议或生成算法。
+- 不调整 Image Line 和 Image Polyline；它们没有 `Fit to Foreground` 设置。
+
+## Decisions
+
+### 复用单一 AI 状态绘制一组设置
+
+在共享图像交互模块中拆出小型绘制函数：同一个 `ai_status()` 结果先决定是否绘制设置按钮，再决定相关属性行是否启用。Cutout 使用这些函数组合 `Fit to Foreground`、本地 mesh spacing 和 `Generate Normal Map`；Image Box 与 Image Lasso 继续通过共享区域设置入口绘制。
+
+相比每个工具分别查询状态和创建按钮，这能保证按钮顺序、文案与禁用条件一致，也避免一次绘制中状态变化造成不一致。
+
+### shape pie 在创建时按 AI 可用性过滤
+
+`open_shape_pie` 在读取 Cutout 工具设置时查询一次 `ai_ready()`：未就绪时只创建 `Surface` 和 `Balloon` 按钮；就绪时再追加 `Depth Balloon` 和 `Depth Surface`。四个 shape 的定义、索引和执行支持保持不变。
+
+相比禁用两个 Depth 按钮，直接隐藏能把无 AI 环境时的选择明确收敛为两个可执行结果，并符合用户期望的两项菜单。
+
+### 在交互边界清除不可用的 AI 选项
+
+传给 Cutout operator 的 `generate_normal` 必须同时满足设置为真和 `ai_ready()`。`Fit to Foreground` 继续通过共享 `apply_region_settings` 做相同门控。这样即使 `.blend` 文件或先前会话保留了真值，选择本地 shape 也不会弹出 AI 安装流程。
+
+相比在 operator 执行阶段静默改写参数，在设置读取边界门控更直接，并使 pie 按钮携带的参数准确表达实际操作。
+
+## Risks / Trade-offs
+
+- [AI 状态查询可能涉及模型状态扫描] → 每个设置绘制或 shape pie 打开过程只查询一次并复用结果。
+- [隐藏 Depth shape 后用户可能不知道完整能力] → 设置开头持续显示带有当前缺失状态文案的 AI 设置按钮。
+- [旧文件保留已勾选的 AI 属性] → UI 置灰且交互参数显式与 `ai_ready()` 合取，不依赖用户手动清除。

openspec/changes/gate-cutout-ai-options/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+Cutout 的 AI 依赖目前只在 `Fit to Foreground` 附近提示，无法覆盖 `Generate Normal Map` 和两个 Depth shape，用户可能在选择后才发现环境不可用。Image Box 与 Image Lasso 的同类入口位置也不一致，需要统一为可预期的工具设置体验。
+
+## What Changes
+
+- AI 环境未就绪时，在 Cutout、Image Box 和 Image Lasso 的工具设置开头显示 AI 环境设置按钮。
+- AI 环境未就绪时，禁用 `Fit to Foreground`；Cutout 同时禁用 `Generate Normal Map`。
+- AI 环境未就绪时，Cutout shape 菜单只显示不依赖 AI 的 `Surface` 和 `Balloon`；环境就绪后显示包含两个 Depth 模式的四个 shape。
+- Cutout 读取设置时忽略 AI 环境未就绪状态下遗留的 AI 选项值，确保本地 shape 不触发 AI job。
+
+## Capabilities
+
+### New Capabilities
+
+- `image-tool-ai-availability`: 定义 Cutout、Image Box 和 Image Lasso 根据 AI 环境可用性呈现设置与可执行模式的行为。
+
+### Modified Capabilities
+
+无。
+
+## Impact
+
+- 影响 Blender View3D 工具设置绘制与区域工具共享交互逻辑。
+- 影响 Cutout shape pie 的候选项与设置值传递。
+- 不新增依赖，不改变服务器协议、节点资产或已有 shape 实现。

openspec/changes/gate-cutout-ai-options/specs/image-tool-ai-availability/spec.md

@@ -0,0 +1,53 @@
+## ADDED Requirements
+
+### Requirement: AI setup entry precedes dependent tool settings
+当 AI 环境或所需模型未就绪时，系统 SHALL 在 Cutout、Image Box 和 Image Lasso 的工具设置开头显示 AI 设置按钮，并使用当前 AI 状态对应的设置文案。
+
+#### Scenario: Cutout AI setup entry is first
+- **WHEN** AI 未就绪且用户激活 Cutout 工具
+- **THEN** 工具设置 SHALL 先显示 AI 设置按钮，再显示 `Fit to Foreground`、`Mesh Sampling Spacing` 和 `Generate Normal Map`
+
+#### Scenario: Image region tool AI setup entry is first
+- **WHEN** AI 未就绪且用户激活 Image Box 或 Image Lasso
+- **THEN** 工具设置 SHALL 先显示 AI 设置按钮，再显示 `Fit to Foreground`
+
+#### Scenario: AI setup entry is omitted when ready
+- **WHEN** AI 环境和所需模型均已就绪
+- **THEN** Cutout、Image Box 和 Image Lasso 的工具设置 SHALL 不显示 AI 设置按钮
+
+### Requirement: AI-dependent settings follow AI availability
+系统 SHALL 仅在 AI 环境和所需模型均已就绪时允许启用图像区域工具的 AI 依赖设置。
+
+#### Scenario: Dependent settings are disabled without AI
+- **WHEN** AI 未就绪
+- **THEN** Cutout 的 `Fit to Foreground` 和 `Generate Normal Map` SHALL 不可编辑
+- **THEN** Image Box 和 Image Lasso 的 `Fit to Foreground` SHALL 不可编辑
+- **THEN** Cutout 的 `Mesh Sampling Spacing` SHALL 保持可编辑
+
+#### Scenario: Dependent settings are enabled with AI
+- **WHEN** AI 环境和所需模型均已就绪
+- **THEN** Cutout 的 `Fit to Foreground` 和 `Generate Normal Map` SHALL 可编辑
+- **THEN** Image Box 和 Image Lasso 的 `Fit to Foreground` SHALL 可编辑
+
+### Requirement: Cutout shape choices follow AI availability
+系统 SHALL 根据 AI 可用性限制 Cutout shape pie 中的可选 shape，同时保留四种 shape 的底层实现。
+
+#### Scenario: Two local shapes without AI
+- **WHEN** AI 未就绪且用户完成 Cutout 区域选择
+- **THEN** shape pie SHALL 只显示 `Surface` 和 `Balloon`
+
+#### Scenario: Four shapes with AI
+- **WHEN** AI 环境和所需模型均已就绪且用户完成 Cutout 区域选择
+- **THEN** shape pie SHALL 显示 `Surface`、`Balloon`、`Depth Balloon` 和 `Depth Surface`
+
+#### Scenario: Runtime RNA menu shape assignment
+- **WHEN** a displayed Cutout shape is selected on a Blender version that exposes modifier inputs through runtime RNA
+- **THEN** the system SHALL assign the matching string enum identifier and create the shape successfully
+
+### Requirement: Stale AI settings do not trigger generation
+系统 MUST 在区域交互读取设置时忽略 AI 未就绪状态下遗留为真的 AI 依赖选项。
+
+#### Scenario: Local Cutout remains local with stale settings
+- **WHEN** AI 未就绪、`Fit to Foreground` 或 `Generate Normal Map` 的保存值为真，且用户选择 `Surface` 或 `Balloon`
+- **THEN** Cutout operator SHALL 接收关闭的 AI 依赖选项
+- **THEN** 操作 SHALL 不因这些遗留值启动 AI job 或打开 AI 设置流程

openspec/changes/gate-cutout-ai-options/tasks.md

@@ -0,0 +1,21 @@
+## 1. 统一 AI 设置绘制
+
+- [x] 1.1 在共享图像交互模块中提取可复用的 AI 设置入口和 AI 依赖属性绘制函数，单次绘制复用同一状态
+- [x] 1.2 调整 Image Box、Image Lasso 及其区域 operator 设置，使未就绪时的 AI 设置按钮位于依赖属性之前
+- [x] 1.3 调整 Cutout 工具设置顺序，使 AI 设置入口开头只出现一次，并分别门控 `Fit to Foreground` 与 `Generate Normal Map`，保持 mesh spacing 可用
+
+## 2. 门控 Cutout 交互
+
+- [x] 2.1 根据 `ai_ready()` 在 Cutout shape pie 中选择两个本地 shape 或完整四个 shape
+- [x] 2.2 在 Cutout 交互读取边界忽略 AI 未就绪时遗留的 `Generate Normal Map` 真值，并保持 `Fit to Foreground` 的既有门控
+
+## 3. 验证行为
+
+- [x] 3.1 补充共享工具设置测试，验证 AI 设置按钮顺序、依赖属性启用状态以及 Cutout 非 AI 属性可用性
+- [x] 3.2 补充 Cutout pie 测试，验证 AI 未就绪时两个 shape、就绪时四个 shape及遗留 AI 设置不会传入 operator
+- [x] 3.3 运行相关 Blender addon 与 Cutout interaction 测试并确认通过
+
+## 4. Blender 5.2 Enum Compatibility
+
+- [x] 4.1 Convert integer menu indices to string enum identifiers for runtime RNA modifier inputs while preserving the legacy ID property path
+- [x] 4.2 Add regression tests for runtime enum and non-enum modifier inputs, then run the related test suite