This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-08
|
||||
@@ -0,0 +1,69 @@
|
||||
## Context
|
||||
|
||||
Debug 调用链跨越 Blender UI、Scene 参数、Operator、Server Job 和原始预测写出。`server/outputs/` 当前专用于 Debug；正式产物由 geometry 等模块生成。删除依据 `proposal.md` 的完整工作流边界进行，同时全面审查 tests、node_assets 和内部文档。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
目标是清除 Debug 入口及其专用依赖，精简有效测试，使节点资产模块和内部文档的名称对应实际职责。实施范围包括代码、测试和用户明确要求整理的内部文档；节点图行为与接口保持稳定，按用户补充要求将 `O Mesh Plane` 统一为 `O Image Plane`。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 按调用链删除
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[删除 Debug 主面板与四个子面板] --> B[删除四个 Debug Operator 与注册]
|
||||
B --> C[删除四个 Debug Job 与注册]
|
||||
C --> D[删除 Debug 序列化与帧复制]
|
||||
D --> E[按剩余引用清理属性与辅助函数]
|
||||
E --> F[验证正式功能与注册生命周期]
|
||||
```
|
||||
|
||||
直接删除实现与注册，使源码和可调用接口保持一致。清理 `server/outputs/` 整个专用包、`copy_frames` 实现和 `media/__init__.py` 导出，避免留下失去调用方的模块。
|
||||
|
||||
### 共用代码按引用决定归属
|
||||
|
||||
| 对象 | 处理 |
|
||||
| --- | --- |
|
||||
| `DebugPanel` 与四个模型子面板、`draw_da3_input_settings` | 删除并清理 `panel.py` 导入 |
|
||||
| `DebugDa3`、`DebugMoge2`、`DebugBen2`、`DebugUpscale` | 删除模块及所有注册项 |
|
||||
| Scene 的 `input_path`、`background_input_path`、`model`、`device`、`process_res`、`process_res_method`、`moge_resolution_level`、`moge_model`、`ref_view_strategy` | 核对剩余调用后删除 Debug 专用声明 |
|
||||
| Scene 的 `video_frames`、Cutout 和 Mask 参数 | 保留正式调用需要的属性 |
|
||||
| `da3_parameters`、`model_enum_items`、`moge2_model_enum_items` | 核对引用后删除专用函数及孤立导入 |
|
||||
| `moge2_parameters`、输入校验函数、偏好设置中的设备选择 | 保留正式调用使用的实现 |
|
||||
| DA3 模型适配器、ONNX 推理、目录及缓存 | 当前调用方仅为 Debug，整条删除 |
|
||||
| MoGe-2、BEN2、Upscale 模型适配器及模型目录 | 保留正式推理所需能力，Upscale 统一保留源 Alpha，删除专用开关 |
|
||||
|
||||
属性按所属类型检查；Operator 上同名的正式属性独立保留。MoGe-2 原始预测结构仍用于正式几何转换，保留其适配和数据校验。
|
||||
|
||||
### 测试随接口收缩
|
||||
|
||||
删除专用导出与 Debug 推理测试，将原本仅通过 Debug 覆盖的公共模型行为转到正式入口。更新 Blender 注册及逆序注销、Server Job 清单与打包清单测试，明确 Debug 接口和文件缺席；正式流程继续覆盖设备、模型选择、视频多帧及推理后的内存释放。
|
||||
|
||||
### 全面审查测试价值与归属
|
||||
|
||||
先逐文件记录实际验证的行为，再对每个用例决定保留、合并、重写或删除。保留能检测输出错误、协议破坏、数据丢失、取消与资源清理失败等实际问题的测试。删除失效功能测试、相同风险的重复断言，以及只复述实现细节且无法发现行为回归的测试；mock 和源码检查按其验证价值判断，不机械删去。
|
||||
|
||||
文件按稳定功能组织，类名和用例名描述实际行为及关键条件。已发现 `test_server_jobs.py` 混合媒体输入、下载、模型生命周期与 Job 输出，`test_blender_addon.py` 混合设备、运行时和 Operator 行为，应按职责拆分。`test_docs.py` 实际验证文档命令，应命名为对应命令职责。其他文件同样逐项审查，避免只处理这几个示例。共享 fixture 仅抽取确有复用的部分，测试通过情况不能代替覆盖价值判断。
|
||||
|
||||
### 节点资产按功能组织源码
|
||||
|
||||
梳理全部模块的构建对象、几何处理、布局和验证职责，形成现名到职责的映射，再确定重命名、合并或拆分。`build_depth_plane.py`、`build_cutout_modifiers.py` 等动作式文件名改为资产或业务分类命名，函数继续使用 `build_*` 表达构建动作。公共深度表面与布局模块依据实际调用范围命名，`node_graph.py` 和 `node_layout.py` 依据实际公共能力保留或细化。
|
||||
|
||||
一次更新模块导入、`tools/build_node.py` 的脚本列表、测试动态加载路径与文档路径，删除旧入口。将 `O Mesh Plane`、相关模块及函数统一命名为 `O Image Plane` / `image_plane`。使用项目配置的 Blender 修改现有 `.blend` 资产名称，比较保存前后全部节点组的接口、默认值、运算、连接和布局，验证功能一致。其他节点组名称保持稳定。
|
||||
|
||||
### 内部文档按最终实现重整
|
||||
|
||||
逐页核对总览、架构、Common、Runtime、产物、开发、节点资产和全部 Operator 说明。以当前源码中的注册、调用链、参数和产物协议为依据，合并重复说明，删除过期内容，按实际主题调整文件名与层次，并同步所有内部链接与 MkDocs 导航。
|
||||
|
||||
删除 Debug 专页及引用；节点资产页使用最终模块名及职责。实现流程用从上到下的 Mermaid 图，正文以中文正面说明当前职责。通过路径、导航、链接和源码交叉核对验收，不运行文档构建。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [误删同名正式参数或公共模型函数] → 逐项核查调用方，并运行正式工作流回归测试。
|
||||
- [注册表或包导出残留导致启动失败] → 验证扩展导入、注册与逆序注销、Server Job 清单和打包文件选择。
|
||||
- [并行变更修改相同文件] → 实施时基于最新工作区逐项修改，保留其他变更的逻辑与测试。
|
||||
- [旧脚本调用已删除 Debug 接口] → 调用方改用对应正式 Operator 或 Job；删除直接生效，不保留转发接口。
|
||||
- [精简测试掩盖回归] → 按行为和风险核对精简前后覆盖，保留独有场景，最终运行完整测试。
|
||||
- [节点模块重命名遗漏动态路径] → 核查构建启动器、脚本加载、测试和文档引用，并测试入口解析。
|
||||
- [文档沿用旧描述导致再次偏离] → 每页对照最终源码核验，尤其是节点组名、socket、Job 参数和输出协议。
|
||||
@@ -0,0 +1,35 @@
|
||||
## Why
|
||||
|
||||
模型调试入口已完成阶段性用途，继续保留会增加 UI、参数、Job 和测试的维护成本。结合删除工作，全面整理测试、节点资产源码和内部文档，让名称、职责、验证与实际功能保持一致。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **BREAKING**：移除 Debug 主面板、DA3 / MoGe-2 / BEN2 / Upscale 子面板及四个 `anyimage.debug_*` Operator。
|
||||
- **BREAKING**：移除 `debug-da3`、`debug-moge2`、`debug-ben2`、`debug-upscale` Job 和原始预测导出实现。
|
||||
- 删除 Debug 专用 Scene 属性、UI 辅助函数、参数组装、序列化与帧复制代码，清理注册、导入和导出。
|
||||
- 删除当前仅由 Debug 调用的 DA3 模型适配器、ONNX 推理、目录声明及缓存分支；Upscale 统一保留源 Alpha。
|
||||
- 根据正式功能的实际引用保留共用模型、输入处理、设备设置、视频帧数和推理能力。
|
||||
- 调整注册、Job、模型及打包测试，覆盖删除后的边界和正式功能回归。
|
||||
- 全面审查 `tests/` 的文件、测试类、用例和辅助代码，仅保留能发现实际行为回归或约束关键协议的测试，按验证功能整理名称和归属。
|
||||
- 全面梳理 `tools/node_assets/` 的构建、几何、布局及验证职责，重命名或拆并职责不符的模块，同步所有导入与脚本引用。
|
||||
- 全面重整 `docs/internals/`，逐页对照最终源码与功能逻辑修订内容、文件名和索引，清理 Debug 说明并同步 `mkdocs.yml` 导航。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `production-only-ai-workflows`：约束扩展仅暴露正式 AI 工作流，规定 Debug 入口及专用实现的移除和正式功能的可用性。
|
||||
- `maintainable-project-structure`：规定测试价值与命名、节点资产模块职责和内部文档与实现的一致性。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
无。当前 `openspec/specs/` 尚无已归档规范。
|
||||
|
||||
## Impact
|
||||
|
||||
- Blender：`panel.py`、`properties.py`、扩展与 Operator 注册、`operators/debug.py`、`common/ai.py`。
|
||||
- Server：`app.py`、`jobs/debug_predictions.py`、`outputs/`、`media/` 及仅被 Debug 引用的模型适配辅助逻辑。
|
||||
- 测试：整个 `tests/`，包含测试归属、名称、公共 fixture 和重复覆盖的整理。
|
||||
- 节点资产：整个 `tools/node_assets/`，以及 `tools/build_node.py`、相关测试和调用引用。
|
||||
- 文档：整个 `docs/internals/` 及 `mkdocs.yml` 导航；按用户明确要求同步实现说明。
|
||||
- 本次整理运行测试，不构建文档、扩展包或节点资产；节点资产整理保持现有节点图与资产接口行为。
|
||||
@@ -0,0 +1,37 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Tests protect meaningful behavior
|
||||
|
||||
维护者 MUST 审查全部测试文件、用例和辅助代码，按实际回归风险保留、合并、重写或删除。保留的测试 SHALL 验证可观察行为或关键协议，每项独有且仍适用的风险覆盖 MUST 保留。
|
||||
|
||||
#### Scenario: Audit completed
|
||||
- **WHEN** 全部测试整理完成
|
||||
- **THEN** 失效功能测试和无独立价值的重复测试已删除，保留用例能说明所保护的行为，完整测试通过
|
||||
|
||||
### Requirement: Test names reflect tested functionality
|
||||
|
||||
测试文件、类和函数 MUST 与其验证的功能、行为和关键条件相符；跨独立职责的测试集合 SHALL 按稳定功能拆分。
|
||||
|
||||
#### Scenario: Locate a behavior test
|
||||
- **WHEN** 按测试路径、类名和函数名查找某项功能
|
||||
- **THEN** 名称与测试主体的实际断言对应，共用辅助代码拥有明确的复用职责
|
||||
|
||||
### Requirement: Node asset modules reflect responsibilities
|
||||
|
||||
`tools/node_assets/` 的全部模块 MUST 按实际资产或业务职责审查命名与边界，所有重命名 MUST 同步导入、构建与验证入口及测试路径，并删除旧路径和转发层。
|
||||
|
||||
#### Scenario: Load reorganized asset tools
|
||||
- **WHEN** 启动器解析脚本并加载节点构建与验证模块
|
||||
- **THEN** 所有路径指向最终模块，文件名与构建对象、几何处理、布局或验证职责对应
|
||||
|
||||
#### Scenario: Preserve node behavior
|
||||
- **WHEN** 对重组后的节点构建函数运行针对性测试
|
||||
- **THEN** 普通图像平面统一使用 `O Image Plane` 名称，源码使用 `image_plane`；资产重命名前后接口、默认值、运算、连接及布局一致
|
||||
|
||||
### Requirement: Internal documentation matches implementation
|
||||
|
||||
`docs/internals/` 全部页面 MUST 与最终源码中的功能、职责、参数、调用链和产物对应，页面名称和目录索引 MUST 与主题对应。实现流程 SHALL 使用从上到下的 Mermaid 图。
|
||||
|
||||
#### Scenario: Read final implementation documentation
|
||||
- **WHEN** 按总览或 MkDocs 导航访问任一内部主题
|
||||
- **THEN** 链接有效，内容描述当前实现，源码路径和功能名称可核对，Debug 专页和过期 Debug 说明已清理
|
||||
@@ -0,0 +1,45 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Blender exposes production AI workflows
|
||||
|
||||
扩展 MUST 移除 Debug 主面板、DA3 / MoGe-2 / BEN2 / Upscale 子面板及四个 `anyimage.debug_*` Operator，并保持正式类型注册和逆序注销完整。
|
||||
|
||||
#### Scenario: Extension registration lifecycle
|
||||
- **WHEN** 扩展注册、注销并重新注册
|
||||
- **THEN** Debug 面板和 Operator 均不在注册清单中，正式面板与 Operator 正常可用
|
||||
|
||||
### Requirement: Server registers production jobs only
|
||||
|
||||
Server MUST 移除 `debug-da3`、`debug-moge2`、`debug-ben2` 和 `debug-upscale` Job 及其处理实现，不提供兼容入口。
|
||||
|
||||
#### Scenario: Registered jobs
|
||||
- **WHEN** Server 加载 Job 注册清单
|
||||
- **THEN** 四个 Debug Job 均缺席，正式 Job 保持已注册且可执行
|
||||
|
||||
### Requirement: Debug implementation is removed completely
|
||||
|
||||
源码和扩展文件选择 MUST 移除 Debug 专用模块、Scene 参数、UI 辅助函数、参数组装、原始预测序列化、帧复制及相应导入和导出。
|
||||
|
||||
#### Scenario: Source and packaging boundaries
|
||||
- **WHEN** 检查模块引用与扩展打包文件清单
|
||||
- **THEN** `operators/debug.py`、`server/jobs/debug_predictions.py`、`server/outputs/` 和 Debug 专用辅助实现均缺席，保留模块可正常导入
|
||||
|
||||
#### Scenario: Scene settings
|
||||
- **WHEN** 读取 `AnyImageSettings` 的属性声明
|
||||
- **THEN** Debug 专用属性已删除，正式使用的 `video_frames`、Cutout 和 Mask 属性保持可用
|
||||
|
||||
#### Scenario: Debug-only model dependencies
|
||||
- **WHEN** 加载模型目录与缓存 Resource
|
||||
- **THEN** DA3 模型声明、推理模块与缓存分支均已移除，正式 MoGe-2、BEN2 和 Upscale 模型保持可用
|
||||
|
||||
### Requirement: Shared production inference remains available
|
||||
|
||||
系统 SHALL 保持正式深度处理、Cutout、Remove Background 和 Upscale 所需的模型、输入校验、设备选择、多帧处理及内存释放行为。
|
||||
|
||||
#### Scenario: Production model requests
|
||||
- **WHEN** 正式 Operator 组装并提交 AI 请求
|
||||
- **THEN** 请求使用正式模型参数及 Add-on Preferences 设备设置，输入校验和视频帧数传递保持有效
|
||||
|
||||
#### Scenario: Production output and memory lifecycle
|
||||
- **WHEN** 正式 Job 完成单帧或多帧模型推理
|
||||
- **THEN** 生成对应正式产物，并按既有最终推理边界请求内存释放
|
||||
@@ -0,0 +1,53 @@
|
||||
## 1. Blender 入口与设置
|
||||
|
||||
- [x] 1.1 删除 Debug 主面板、四个子面板和专用绘制函数，清理 `panel.py` 导入及扩展注册项。
|
||||
- [x] 1.2 删除 `operators/debug.py` 及 Operator 注册项，验证正式类型注册与逆序注销。
|
||||
- [x] 1.3 按引用删除 Debug 专用 Scene 属性、枚举回调和 `da3_parameters`，保留正式输入校验、`moge2_parameters`、`video_frames` 及偏好设备设置。
|
||||
|
||||
## 2. Server 实现与依赖
|
||||
|
||||
- [x] 2.1 删除四个 Debug Job 的注册和 `jobs/debug_predictions.py`。
|
||||
- [x] 2.2 删除 `server/outputs/` 专用包、`copy_frames` 及媒体模块导出，清理孤立导入。
|
||||
- [x] 2.3 沿删除后的调用链检查模型适配与公共模块，移除仅服务 Debug 的分支，确认正式预测数据转换和产物写出仍完整。
|
||||
|
||||
## 3. 测试与验收
|
||||
|
||||
- [x] 3.1 删除 Debug 专用测试及测试模块加载，更新 Blender 注册与 Scene 属性断言。
|
||||
- [x] 3.2 更新 Server Job 注册和打包文件清单测试，验证 Debug Job、模块及导出缺席；使用文件选择检查，避免生成扩展包。
|
||||
- [x] 3.3 将 Debug 测试中仍适用的公共模型断言移到正式入口，验证模型选择、设备、输入校验、多帧、产物及最终推理内存释放。
|
||||
- [x] 3.4 运行 Debug 删除相关测试，复查 `src`、`tests`、`tools` 及运行配置中的 Debug 引用，确认无残留实现或失效导入。
|
||||
|
||||
## 4. 全部测试整理
|
||||
|
||||
- [x] 4.1 逐文件审查全部测试类、用例和辅助代码，列出保护的行为与风险，决定保留、合并、重写或删除。
|
||||
- [x] 4.2 删除失效、无独立价值的重复用例和单纯复述实现的断言，保留所有仍适用的独有行为覆盖。
|
||||
- [x] 4.3 按实际职责整理全部测试文件、类和函数名，拆分跨功能集合，包括 Blender 注册、设备、Runtime、媒体输入、模型下载与 Job 输出。
|
||||
- [x] 4.4 清理 fixture、动态导入和辅助函数，仅提取确有复用的代码，核对整理前后关键风险覆盖。
|
||||
|
||||
## 5. 节点资产源码整理
|
||||
|
||||
- [x] 5.1 遍历 `tools/node_assets/` 全部模块，核对文件名与构建对象、几何处理、布局及验证职责，确定目标命名和拆并方案。
|
||||
- [x] 5.2 按稳定功能重命名或拆并模块，同步全部导入、`tools/build_node.py` 脚本列表和测试加载路径，移除旧路径与转发代码。
|
||||
- [x] 5.3 通过针对性测试核对 socket 顺序、默认值、运算、连接和布局保持一致，将源码、测试、文档和正式资产中的 `O Mesh Plane` 统一为 `O Image Plane`。
|
||||
|
||||
## 6. 内部文档整理
|
||||
|
||||
- [x] 6.1 对照最终源码审查 `docs/internals/` 全部页面，核对功能名、路径、参数、调用链、产物和实际职责。
|
||||
- [x] 6.2 重整总览、架构、Common、Runtime、产物和开发说明，按主题调整文件名与层次，合并重复内容并删除过期说明。
|
||||
- [x] 6.3 重整全部 Operator 页面和索引，删除 Debug 专页与引用，以 Mermaid 流程说明正式功能主链。
|
||||
- [x] 6.4 更新节点资产文档，使模块名、节点组、接口、构建与验证流程对应实际实现。
|
||||
- [x] 6.5 同步 `mkdocs.yml` 导航和全部受影响的内部链接，检查链接与源码引用有效性。
|
||||
|
||||
## 7. 最终验收
|
||||
|
||||
- [x] 7.1 运行 `uv run pytest`，处理行为回归与测试收集问题，核对关键功能覆盖。
|
||||
- [x] 7.2 复查全部改名的旧路径、失效导入和文档引用，确认 tests、node_assets、docs/internals 的名称与内容边界一致。
|
||||
- [x] 7.3 核查最终差异并汇报主要删除、合并、重命名与验证结果；确认未构建文档、扩展包或重建节点资产；已有资产仅修改图像平面组名并验证内容一致。
|
||||
|
||||
## 验证结果
|
||||
|
||||
- `uv run pytest -q`：724 passed、2 xfailed、48 subtests passed，退出码 0。
|
||||
- 模拟 Blender 测试仅拦截 Python 导入，保留真实 `bpy` 模块身份，并恢复原有 AnyImage 模块，避免原生退出崩溃。
|
||||
- 23 个节点源码模块经 AST 比对，变化仅限命名与导入。
|
||||
- 使用项目配置的 Blender 对原有资产重命名；保存前后节点接口、属性、默认值、连接和布局一致。
|
||||
- 内部文档链接、Python 语法和 OpenSpec 严格校验通过。
|
||||
Reference in New Issue
Block a user