feat(pixel-perfect): expose an independent tool API

[huyanxius]

Parent

#489

Outcome

提供一个独立后端工具 API，负责输入校验和检测器、重建器编排，使浏览器可以直接调用完美像素化能力，而不进入默认生成管线。

Scope and exclusions

• 在 windup_app 下新增独立工具适配层与单独 API 路由。
• 自动模式调用网格识别器，再把显式网格契约传给重建器。
• 手动 pixel_size 模式绕过检测器并直接计算显式网格。
• 浏览器直接上传图片字节并接收 PNG，不依赖数据库、对象存储或媒体服务。
• 对原生子进程设置输入大小、超时与并发限制，并把失败映射为明确 API 错误。
• Docker 仅构建和复制两个原生二进制；不修改生成、工作流或 worker 调用链。
• 不包含前端入口、默认生成管线集成或小于 3px 的自动检测优化。

Acceptance criteria

• 独立端点支持自动检测和手动 pixel_size 两种模式。
• 成功响应包含重建 PNG 与检测元数据。
• 原生进程失败、超时、非法参数和资源超限均有稳定错误响应。
• API 测试使用真实二进制或边界级替身验证编排契约，不依赖生成服务。
• 应用装配只新增工具路由，不改变任何现有生成或工作流行为。
• Docker 能构建并运行两个固定版本的原生模块。

Blocked by

Pixel grid detector delivery and pixel grid reconstructor delivery.

[huyanxius]

Design update · 2026-08-21

工具 API 的原生调用方式由子进程 CLI 调整为 PyO3 原生扩展：

• 在 native/pixel-perfect/bindings/python/ 增加 binding crate，依赖 feat(pixel-grid): add an independent grid detector #490 与 feat(pixel-grid): add an explicit grid reconstructor #491 的两个纯 Rust library。
• Python 后端直接导入原生扩展，不再启动进程、传输 stdin/stdout 或维护二进制路径环境变量。
• maturin 在 Docker 构建阶段生成 Linux wheel；Rust 工具链不进入运行镜像。
• 原生扩展延迟加载；缺失时仅本工具返回不可用，不阻断 Windup 后端启动。
• Rust 计算释放 GIL，并与 API 侧并发上限共同避免 CPU 过度订阅。
• PyO3 与后端 worker 共享进程和资源；本次不提供进程级故障隔离或可强杀的硬超时。若后续要求独立故障域，再迁移为单独 Rust 服务。
• 修复 multipart 超限响应，使其继续遵守现有业务错误包络。

独立端点、<3px 默认边界、无数据库/对象存储依赖、不得进入默认生成管线等约束保持不变。

[nighca]

如果是

• 通过调用 rust 工具来实现
• 且只提供给前端用

那不如直接把能力编成 wasm 由前端自己 load 并调用，都不用走 backend 的 HTTP API。

只是 #489 (comment) 这里提到的问题我还是不理解：为啥这个处理不是生成管线的一部分