Local GPU Imagegen

本地 GPU 图像生成

English | 简体中文

一个以 MCP 为先的控制平面，为你现有的 ComfyUI 配置提供加密模型身份、明确审批和持久运行证据。

无需修改配置，即可通过 Codex 运行受支持的 ComfyUI 工作流。

uvx local-gpu-imagegen verify
uvx local-gpu-imagegen setup codex --apply

设置会保存一个已解析且固定版本的启动器，其等效命令为 uvx --from local-gpu-imagegen==0.9.1 local-gpu-imagegen serve；它不依赖临时 uvx 环境中的控制台脚本。如果旧条目报告 client_setup_drift，只需移除该客户端条目，然后重新应用设置。启动 ComfyUI 无法修复 MCP 启动器故障；客户端加载服务后才会检查后端是否就绪。

向 Codex 提问：

Run this supported ComfyUI API workflow from Codex: <path>.
Use this prompt: <prompt>. Preserve every other workflow setting.

此路径需要 Python 3.11 或 3.12、Codex、已运行的本地 ComfyUI 实例、已安装的模型，以及一个使用受支持内置拓扑的常规 txt2img API 工作流。它使用你现有的本地图像后端和模型，不会在无提示的情况下下载或切换模型。它不会安装后端、下载模型、转换 UI 格式的 JSON，也不会执行需要不受支持的自定义节点的工作流。下文介绍了一个明确的 Windows 便携式托管启动选项。

v0.9 支持的主机范围为搭载 NVIDIA 的 Windows 10/11 x64。单个 py3-none-any wheel 仅表示采用纯 Python 打包，并不代表存在单独的 Linux 版本，也不意味着支持在 Linux 上托管生成。Ubuntu CI 会验证平台无关的 MCP、打包、现有后端和不受支持平台相关约定；Windows 则运行完整的便携式引导套件。

ComfyUI 负责生成图像。Local GPU Imagegen 负责管理生成过程中的权限、可复现性、审核和恢复。

五分钟快速入门 | 启动手册 | 替代方案

使用你自己的 ComfyUI 工作流

保留的 Codex 工作流接入会话检查并注册了受支持的图，并绑定了其中的确切模型组件；它没有提交提示词，也没有使用 GPU。历史生成图像记录仍可用于技术审计，但 v0.9 不会将其用作宣传视觉素材，也不会将其作为图像质量优越的证据。

此路径需要现有的本地图像后端和模型；不会在无提示的情况下下载或切换模型。

分步引导初始化（Windows NVIDIA）

对于现有环境，运行 bootstrap status，并且只复用经过验证的便携根目录、检查点和回环端点。对于零环境设置，bootstrap plan 会显示确切的便携压缩包、检查点、字节上限、许可证 URL、SHA-256 哈希、磁盘/显存要求以及有界回滚；bootstrap apply 需要输入显示的明确确认。下载支持断点续传，且绝不会静默进行。固定范围为 Windows 10/11 x64，搭载 NVIDIA RTX 20 系列或更新型号、10 GiB 显存和 30 GiB 可用磁盘空间。无需 Docker。此无模型初始化约定不能证明图像生成能力或已达到生产就绪状态。

不带 --apply 时，setup 只读。应用路径会委托给客户端的官方 mcp add 命令；Local GPU Imagegen 不会直接编辑客户端配置文件，也不会下载模型。

**信任证明：**保留的普通路由结果来自一次已安装的 Codex 会话。发现阶段未加载权重；信任和路由身份均明确；成功轮次受到限制；审核使用了原始分辨率 PNG；最终定稿与已审核的字节绑定；运行状态仍可恢复。这些证据证明的是这一个结果，并不证明已完整通过 9+3 验收、达到经测量的性能，或已达到生产就绪状态。

**v0.9 本地验收：**使用用户批准的 ComfyUI 压缩包和 SDXL 检查点构建的全新 Windows/NVIDIA 安装达到了托管就绪状态，恰好提供了十七个 MCP 工具，并定稿了一张经过审核的非人类环境图像，其源文件与最终文件的哈希值逐字节一致。该产物仍保留在本地，需单独进行净化导出，且不会打包在该软件包中。两次独立的角色尝试均未通过严格的手部、眼睛或尾巴审核；因此，不能证明突出人物的解剖结构质量。

可选的托管 ComfyUI 启动

Windows 设置可以注册一个现有的便携版根目录，以便托管启动：

uvx local-gpu-imagegen setup codex --apply `
  --auto-start-comfyui `
  --comfyui-root "<ComfyUI_windows_portable>"

此可选命令会验证固定的便携版目录结构，并在 127.0.0.1:8188 注册 python_embeded\python.exe -s ComfyUI\main.py。它不会安装 ComfyUI，也不会下载模型。已经运行的端点会被复用，但不会被接管或停止。MCP 进程启动的子进程仅会在 MCP 退出时、且队列为空的情况下停止；队列非空时会保留该进程并报告情况。 两种模式都会使用现有后端和模型，不会静默下载或切换模型。工作流执行仍仅限于受支持的内置拓扑；托管启动不会移除或管理所选便携版安装中已有的自定义节点。

该动画是确定性的模拟协议演示，不代表模型输出，也不能作为图像质量证据。它仍是协议和测试证据的补充。无模型测试涵盖协议和后端契约，不涵盖图像质量、更广泛的指定客户端生成、性能或完整的 9+3 验收。

对于 Claude Code，请使用 uvx local-gpu-imagegen setup claude-code --apply。使用 codex mcp remove local-gpu-imagegen 或 claude mcp remove --scope user local-gpu-imagegen 移除这些条目。使用 uvx local-gpu-imagegen doctor 检查本地后端是否就绪。设置契约和等效的 stdio 启动方式均已验证；已保留一次 Codex 已安装客户端生成记录，而 Claude Code 生成仍待完成。请参阅客户端兼容性。

DeepSeek Harness (DSH) 通过相同的标准 stdio MCP 协议连接，无需设置命令：通过 dsh plugin --profile <name> add 注册服务，或让任何兼容 MCP 的客户端指向 scripts/mcp_server.py。一次由 DSH 驱动的真实运行已针对一个正在运行的 ComfyUI 检查点完成完整的 discover_models (api_only) → recommend_models → start_run → get_run → generate_round 序列，并生成了 round-01.png 产物；initialize/tools/list/ping、verify_mcp.py 和 verify_client_configs.py 均已通过。

在发布到 PyPI 之前，请安装已验证的 wheel 或源码检出版本，然后使用等效的 local-gpu-imagegen verify 和 local-gpu-imagegen setup ... 命令。

为什么选择本项目

• **从你的 Agent 运行受支持的工作流：**检查并注册常规 ComfyUI API 图，而不是将它们重建为一次性脚本。
• **复用或显式管理你的后端：**ComfyUI 是现有工作流的主要路径；可选的 Windows 便携版管理器无需接管现有进程，即可免去手动启动。AUTOMATIC1111/Forge 和 Diffusers 仍是兼容路径。
• **让运行可复现：**在持久化清单中冻结工作流、模型标识、提示词、设置、种子、预算和输出哈希。
• **使用已安装的 CLI：**验证就绪状态，并将设置工作交给官方 Codex 或 Claude Code 命令，无需检出源代码。
• **明确模型权限：**发现过程绝不会加载权重，生成也不会悄然下载或切换模型。
• **保留结构化证据：**路由、预算、尝试记录、图像哈希、审核结果和恢复操作都会以机器可读的形式持久保存。
• **由用户决定是否验收：**原始分辨率审核和后续按字节绑定的最终确认，将生成的图像与已接受的最终图像区分开来。
• **Agent 引导的工作流：**内置的 Agent Skill 可将自然语言需求转化为经过目录约束并经确认的运行。
• **三种交付配置：**独立插画、演示视觉素材和 UI 视觉资源共用一套确定性的运行与审核约定。
• **可审计的热修订：**不可变的子运行会记录保留/更改约定，并使用提示词优化、img2img 或经过明确确认的局部重绘。
• **依赖精简的 MCP 层：**协议检查和测试使用 Python 标准库，无需 GPU。
• **范围聚焦：**图像生成与规划、记忆及无关的 Agent 功能相互独立。

实验性构图控制

黄金路径使用常规的 sdxl-txt2img。sdxl-regional-txt2img 和 sdxl-two-stage-copy-subject 路由仍属实验性功能，不属于黄金路径，也不会在常规路由失败时提供回退。保留的负面证据并不能证明视觉质量有所提升。

图像质量边界

模型和工作流质量由用户提供。本地 GPU Imagegen 提供明确的执行、审核、恢复和证据记录；它不会修改扩散算法，也不保证提示词工作流能改善图像。如今，即使替代结果看起来更干净，只要将请求中的产品媒介、主体、实际用途或素材槽位替换为其他内容，审核就会将其视为语义替换和约束失败。

请参阅图像质量控制和冻结的工作流无回归门槛。保留的门槛结果为 FAIL_WORKFLOW_REGRESSION；没有证据支持公开宣称图像质量更优。

源代码检出与后端设置

1. 验证 MCP 服务

Python 3.11 或 3.12 即可完成此检查。无需 GPU、模型或 AI 客户端。

python .\scripts\verify_mcp.py

预期结果：

{
  "ok": true,
  "transport": "stdio",
  "python": "<current-python>",
  "server": {"name": "local-gpu-imagegen", "version": "0.9.1"},
  "protocolVersion": "2024-11-05",
  "tools": [
    "local_gpu_branch_run",
    "local_gpu_cleanup_run",
    "local_gpu_confirm_mask",
    "local_gpu_discover_models",
    "local_gpu_finalize_run",
    "local_gpu_generate_image",
    "local_gpu_generate_round",
    "local_gpu_get_run",
    "local_gpu_imagegen_check",
    "local_gpu_list_profiles",
    "local_gpu_prepare_mask",
    "local_gpu_recommend_models",
    "local_gpu_record_review",
    "local_gpu_register_workflow",
    "local_gpu_set_model_trust",
    "local_gpu_start_run",
    "local_gpu_inspect_workflow"
  ]
}

2. 选择后端

后端	适用场景	设置	网络行为
WebUI	已安装 AUTOMATIC1111 或 Forge	启动时启用 API 访问	提示词／图像会发送到配置的 WebUI URL
ComfyUI	已在运行 ComfyUI，且希望执行经过审核的图	自行启动；或者针对一个现有的 Windows 便携版安装，选择 setup --auto-start-comfyui --comfyui-root <root>	提示词／图像只会发送到本地回环地址或单独确认的端点
Diffusers	希望使用自包含的 Python 管线	使用 scripts/install.ps1 创建项目 .venv	除非明确允许，否则会阻止下载模型／LoRA

检查当前就绪状态：

python .\scripts\check_gpu.py

该命令会返回 JSON。ready: false 是有效的诊断状态，并非协议故障。

托管启动需显式选择，且仅适用于 Windows 便携版。它会强制使用 Python -s 隔离模式，防止用户站点的 Torch 软件包污染便携式运行环境； 在后台启动，避免 MCP 初始化延迟；首次托管就绪检查会等待，最长不超过已配置的启动超时时间。 doctor 本身始终为只读操作，绝不会启动后端。

要在特定虚拟环境下验证 MCP 服务，并通过 MCP 调用就绪检查：

python .\scripts\verify_mcp.py `
  --python .\.venv\Scripts\python.exe `
  --check-readiness

3. 连接 MCP 客户端

随附的 .mcp.json 使用相对命令和 cwd。对于使用全局配置的客户端，请将 <project-root> 替换为此克隆项目的绝对路径：

{
  "mcpServers": {
    "local-gpu-imagegen": {
      "command": "python",
      "args": ["<project-root>\\scripts\\mcp_server.py"]
    }
  }
}

重启客户端，然后在首次生成前调用 local_gpu_imagegen_check。

4. 请求视觉素材

随附的 Agent Skill 可接受普通请求。例如：

创建一幅 16:9 的独立动漫角色插画，不含生成的文字。最多进行两轮成功生成，保持禁用下载，并在更改种子前先询问。

该 Skill 不会根据检查点文件名猜测，也不会悄悄选择后端。它会发现当前本地资源清单，应用用户本地信任设置，推荐一条确切路径，并在下载模型前等待确认。

Agent Skill 工作流

1. 当清单未知时，以 api_only 模式调用 local_gpu_discover_models。更广泛的扫描需要先展示计划，并在访问文件系统前获得明确确认。
2. 只有在展示一个确切身份并获得针对该身份的明确信任确认后，才使用 local_gpu_set_model_trust。私人使用和公开证据属于不同范围。
3. 针对预期的授权范围调用 local_gpu_list_profiles。复用已知的简要值，只询问缺失的高影响边界条件。
4. 调用 local_gpu_recommend_models。它会返回一条确切路线和最多两个备选方案，且不会放宽硬性要求。
5. 展示确切解析出的 model_choice、后端、身份强度／哈希或绑定警告、工作流、编译器、尺寸和预算。展示后等待新的明确确认。
6. 启动冻结路线 → 读取持久化的冻结运行 → 构建完整的生成计划 → 消耗不超过已确认的成功轮次预算。添加提示词和参数前，从该次运行中复制所有路线、身份、工作流、编译器、策略和预算字段。保留的图像会消耗一个轮次；后端故障不会。
7. 在具备视觉能力的主机上，展示并检查原始全分辨率图像。按照完整评估标准记录所需的解剖结构、脚部／接触、手部／物体以及文本／水印检查；仅查看预览不足以完成检查。检查未通过或结果不确定时，必须进行 refine 或 explore。refine 会保留种子；explore 会更改种子。
8. 当符合条件的审核返回质量状态 candidate 时，展示其局限性、图像 SHA-256 和确切的 finalize:<run_id>:<round_number>:<image_sha256> 值，然后停止。只有之后的用户消息中包含所展示的该值时，才可授权最终确定；Agent 不能接受自己的候选结果。
9. 在纯文本主机上，仅保留一个成功轮次，标记为 review unavailable，报告未经审核的路径，然后停止。不得编造评分，也不得调用审核／最终确定工具。

候选结果经过审核或最终确定后，用户可以描述需要保留和更改的内容。该 Skill 会提供可审计的保留／更改约定，另行询问一至三个轮次的修订预算，并且只在确认后创建不可变的子运行。它会选择破坏性最小的模式：同一种子的提示词优化，然后是低强度 img2img，最后是需要明确确认蒙版叠加效果的修补。无蒙版保留只能尽力而为。

对于可选的 copy-subject-v1 路线，Agent 会在确认前展示两个归一化区域的小数值和百分比、两个区域各自的提示词和强度、确切的 sdxl-regional-txt2img 路线，以及成功轮次预算。该运行的几何参数会被冻结。优化可以更改区域提示词或强度，但移动区域需要新确认的根运行或子运行；区域能力不可用或发生漂移时，绝不会回退到仅使用提示词的 sdxl-txt2img。

对于可选的 sdxl-two-stage-copy-subject 路线，local_gpu_set_model_trust 接受确切的 two_stage_layout；调用方绝不提供 control_sha256。服务端会归一化该布局、检查随附的工作流、推导控制摘要，并在展示的信任确认中包含工作流、组件包和控制摘要。批准和后续路由都要求归一化后的布局、工作流、组件包、端点和模型身份保持一致。Agent 还会展示像素几何参数和百分比、基础种子和派生主体种子、主体条件以及两阶段预算。一个轮次消耗两个阶段单元，并保留三个按角色绑定的 PNG：基础产物、蒙版产物和最终产物。审核前会执行受保护像素和已保存蒙版关卡；部分结果会直接停止，不会回退。基础产物和最终产物都要经过全分辨率阶段审核，只有最终产物可以成为候选结果。首次 GPU 实际运行关卡严格限定为一个两阶段轮次。 较早的单次 copy-subject-v1 区域路由仍作为保留的负面证据和实验性兼容方案。其无模型控制契约仍有用，但观测到的输出并不能证明视觉质量有所提升。在保留完整分辨率验收结果之前，任何一路由都不会被视为图像质量提升的正面证据。

自适应流程为：发现 -> 按需建立信任 -> 限定范围的目录 -> 简报 -> 精确路由推荐 -> 显示后确认 -> 启动 -> 读取已持久化的运行记录 -> 构建完整计划 -> 生成 -> 检查完整分辨率图像 -> 审核 -> 优化／探索或显示候选项 -> 等待用户稍后发送消息 -> 定稿。配置的 max_rounds 必须介于 1 和 3 之间，紧迫性或沉没成本都不能延长此限制。

视觉配置与范围

配置	支持的子类型	交付重点
standalone-illustration	character、environment、wallpaper	独立完整的插画输出。
presentation-visual	cover、section、content-background	仅含视觉内容的幻灯片素材，并遵守安全区域和叠加限制。
ui-visual-asset	hero、section-illustration、rectangular-background、decorative-texture	可组合到界面中的栅格视觉素材。

不包括完整的 PPT 演示文稿。不包括前端代码和组件。不包括生产用图标、SVG 和透明 PNG。不包括自动分割。不保证纹理无缝。本项目生成可供检查的栅格素材，而非幻灯片布局或界面实现。

安全地使用自带模型

发现分为四个级别：api_only、selected_folders、common_locations 和 full_drive。文件系统发现分为两个阶段：index 记录有限的元数据，不打开检查点载荷；fingerprint 仅为明确选定的已索引候选项计算 SHA-256。.ckpt 始终保持不透明，扫描不会跟随符号链接、目录联接或重解析点。

信任信息存储在仓库之外的操作系统用户状态目录中，可通过 LOCAL_GPU_IMAGEGEN_STATE_DIR 覆盖。只有用于 private 的 backend_binding 身份才能获得信任。对于拆分的 ComfyUI 路由，信任工具会先提供一个非变更检查操作，将主模型、文本编码器、VAE 和经过审核的工作流绑定为一个规范的 SHA-256 捆绑包。该捆绑包的确切摘要会纳入后续的信任确认和路由令牌。只有在每个组件都有确切的来源、许可证和输出再分发元数据时，经过加密校验的捆绑包才可成为 public_evidence 候选项；验收授权方必须批准同一捆绑包，方可导出。

安全工作流接入

现有的 ComfyUI API 格式工作流如果是使用单个检查点或拆分模型拓扑的普通 txt2img 图，可以在调用方不提供节点 ID 的情况下进行检查和注册。限定流程如下：

API-only discovery (when current inventory is absent)
-> local_gpu_inspect_workflow
-> display hashes, inferred binding, components, limitations, confirmation
-> later exact user confirmation
-> local_gpu_register_workflow
-> separate local_gpu_set_model_trust with `registered_workflow_id`

检查会读取一个明确指定的本地 JSON 文件，接受裸 API 图或唯一的 prompt 封装，并报告 source_sha256、workflow_sha256、拓扑、推断出的绑定、自有输出和组件身份。可注册的结果包括 register_workflow:<source_sha256>:<proposal_digest>；诊断结果不包含确认信息。UI 格式不会转换；注册不会授予模型信任或公共权限。我们保留了零 GPU 的真实客户端接入证据；生成证据则单独保存。

项目不捆绑模型权重。仓库目录包含可审计 ID civitai/anything-v5@30163，对应已审核的本地 WebUI 检查点；下载仍未获批准。其他本地模型只有经过发现和明确授权后，才能加入私有目录。模型质量仍取决于用户的模型。本项目增加了更安全的路由、持久化审核和热修订，而非声称拥有更出色的提示词转换器。

ComfyUI 附带经过审核的工作流文件：sd15-txt2img-v1.json、sdxl-txt2img-v1.json、sdxl-regional-txt2img-v1.json、sdxl-two-stage-copy-subject-v1.json、z-image-turbo-txt2img-v1.json 和 anima-txt2img-v1.json。发现功能会区分 CheckpointLoaderSimple、UNETLoader、CLIPLoader 和 VAELoader。私有的后端绑定路由仍可只绑定主加载器，但拆分工作流若要满足公共证据资格，则必须具备当前 API 身份，以及每个冻结组件的文件系统 SHA-256 身份。纯拆分模型安装可能没有检查点选项。Shell、Python/脚本/进程执行、网络/下载/webhook/fetch 节点、命令、未知自定义节点、未绑定参数和资源超限都会被拒绝。

这些工作流文件不包含、不安装、不信任模型权重，也不授予其许可。Z-Image 和 Anima 仍需精确的本地发现、用户批准和已确认的路由。Anima 是可选的动漫路由；鉴于其上游权重限制，不得将其作为商业用途或公共证据的默认选项。ComfyUI 适配器：已通过契约测试；本地 Z-Image 和 Anima 适配器执行：已观察；公共验收证据：未保留。

工具参考

公共 MCP 接口恰有十七个工具：两个兼容性工具，以及十五个高级发现/接入/运行/修订工具。

local_gpu_imagegen_check

报告 Python 包、CUDA 设备、WebUI 可访问性和总体就绪状态。即使工具调用本身成功，机器也可能尚未就绪。

local_gpu_generate_image

支持：

• txt2img、img2img 和图像修复
• 固定种子
• WebUI 检查点和采样器选择
• Diffusers 调度器选择
• LoRA 加载
• VAE 平铺和可选 CPU 卸载
• 明确指定 CPU 回退
• 明确允许下载模型/LoRA

工具架构会在启动后端进程前验证类型、范围、枚举、未知字段、图像模式要求和尺寸。

这两个兼容性工具与十五个高级工具并行保留。尤其是，低级 local_gpu_generate_image 兼容性工具保持不变：其可选模型值仍是直接的兼容性透传，并非由目录控制的 Agent 工作流。其 WebUI/Diffusers 选项和明确的模型下载控制也保持不变。

高级运行工具

工具	职责
local_gpu_discover_models	规划或执行范围受限的 API/文件系统清点，不加载模型权重。
local_gpu_inspect_workflow	检查一个普通的 ComfyUI API txt2img 工作流，并返回诊断信息或可注册的哈希值和绑定信息。
local_gpu_register_workflow	重新检查一份精确提案，并在之后通过摘要绑定的确认后，存储其不可变的已注册工作流副本。
local_gpu_set_model_trust	检查一组经过审核的组件而不进行修改，或在确认后于用户本地状态中批准／撤销一个精确身份。
local_gpu_recommend_models	返回一条确定性路线，至多再提供两个附有说明的备选方案。
local_gpu_list_profiles	列出已注册的用例配置文件和当前后端能力。
local_gpu_start_run	持久化已确认的意图、配置文件、约束、后端选择和轮次预算。
local_gpu_get_run	读取持久化清单及其 recoverable_next_actions。
local_gpu_branch_run	从一个经过审核的父轮次创建不可变的子运行，并保留或更改契约。
local_gpu_prepare_mask	准备用户提供的蒙版或矩形／多边形蒙版，并返回范围受限的 JPEG 叠加图。
local_gpu_confirm_mask	在获得用户明确批准后，确认未发生变化的已准备蒙版。
local_gpu_generate_round	生成一个根轮次或固定模式的子轮次，并可选择返回范围受限的 JPEG 预览图。
local_gpu_record_review	存储评分标准分数、必需的结构化视觉检查、硬性失败项、约束和保留结果、评述以及下一步操作。
local_gpu_finalize_run	验证与图像绑定的用户确认，并将指定的合格轮次发布为最终本地 PNG。
local_gpu_cleanup_run	删除中间文件，或删除整个已确认的运行目录。

max_rounds 必须在 1 到 3 之间。只有成功保留的 PNG 轮次才会计入预算；后端失败会记录为一次尝试，但不消耗轮次。每次新的审核都要求 full_resolution_inspected: true，并须说明是否存在显著人物，同时明确记录对肢体分离、脚部／接触、手部／持握物体以及文字／水印的观察结果。人体解剖结构检查不能标为 not_applicable；任何必需检查结果为 fail 或 uncertain 时，只能请求 refine 或 explore。

符合条件的审核会显示质量状态 candidate，而非 accepted，并绑定运行、轮次和保留图像的 SHA-256 哈希值。Agent 会显示原始图像、局限性、哈希值和精确的 finalize:<run_id>:<round_number>:<image_sha256>，然后等待用户之后发送消息。local_gpu_finalize_run 要求提供该精确确认，以及指定的 round_number 和摘要。它会在运行锁定期间重新验证候选项，然后发布指定的已审核轮次，不会用评分更高的轮次替换它；只有已发布的结果会获得 accepted 状态。

不符合条件的已审核产物永远不会发布。如果确认的预算尚有剩余，可选择 refine 或 explore；否则保留该产物并请求用户作出新的决定，不予发布。现有的已完成清单和较低层级的存储兼容路径中仍可能包含 needs_user_review，但缺少结构化视觉检查的未完成旧版审核无法生成公共引擎候选项。

local_gpu_list_profiles 返回范围内合并后的目录和当前能力。local_gpu_start_run 要求提供已展示的精确 route_token、授权范围、模型、后端、尺寸、工作流和编译器。身份信息发生漂移时，会在调用后端前失败；根运行和子运行绝不会静默切换路线。

运行文件、重试与恢复

默认的持久化布局如下：

outputs/
  runs/
    <run_id>/
      manifest.json
      parent-source.png
      round-01.png
      round-01-preview.jpg
      final.png
      final-upscaled.png
      masks/
        mask-01.png
        mask-01-overlay.jpg

outputs/runs/<run_id>/manifest.json 是已确认输入、尝试、轮次、审核、警告、最终元数据和状态修订的事实来源。成功完成第一轮后会保留 round-01.png，也可能创建 round-01-preview.jpg；后续轮次使用相同的连字符预览命名模式。引用 round-01.preview.jpg 的已存储旧版清单仍可读取，不会被重写。完成最终处理后会发布 final.png。预览文件是可选的：MCP 响应可能包含有大小限制的 JPEG 预览，而 full_image_path 指向本地全分辨率 PNG。预览警告或编码失败不会导致已验证的 PNG 被丢弃。

不可变的子运行会将选定的父级 PNG 复制到 parent-source.png，记录父级溯源信息和哈希值，且绝不会写入父级清单。Img2img 和 inpaint 使用该保留源文件。Inpaint 还需要已确认的 masks/mask-01.png；审批前会返回 masks/mask-01-overlay.jpg。更改源文件或蒙版的字节内容会使确认失效。

每个生成请求都需要一个 idempotency_key。使用相同请求重复提交同一个键时，会返回已完成的轮次，或报告该尝试正忙；将该键用于不同输入则会被拒绝。中断后，调用 local_gpu_get_run 并遵循 recoverable_next_actions。如果已保留经过验证的完整 PNG，引擎可以回收过期尝试并恢复创建预览。

清理操作需要明确执行。对于 intermediates 和 all，确认内容必须与 run_id 完全一致。intermediates 范围会保留清单和已发布的最终文件；all 会删除已确认的运行目录。

可选的 Anime Real-ESRGAN 后处理

仅适用于 Anime 的 4 倍后处理需显式启用，且在本地执行。工具根目录只能通过 LOCAL_GPU_IMAGEGEN_REALESRGAN_DIR 配置；服务仅接受该根目录下的 realesrgan-ncnn-vulkan.exe 以及受支持的模型对之一：realesrgan-x4plus-anime 或 realesr-animevideov3-x4。它不接受任意可执行文件路径或模型名称，也不会下载二进制文件或模型。

不会自动运行后处理器。即使 upscale_policy: auto 也只记录了许可：调用方必须将完全相同的 postprocess 对象传给 local_gpu_finalize_run，且已确认的风格必须为 anime。请求成功时会保留原始 final.png，返回 final-upscaled.png，并在最终后处理元数据中记录模型、缩放比例、源文件和输出文件路径、哈希值、尺寸及 MIME 类型。后处理不可用或失败时，会回退到原始最终文件，并附带结构化警告。真实二进制文件、GPU、质量和性能方面的行为仍未经验证。

独立使用

通过已在运行的 WebUI 生成：

python .\scripts\generate_image.py `
  --backend webui `
  --prompt "a small robot reading a circuit diagram, clean concept art" `
  --width 1024 --height 1024 --seed 42

创建项目本地的 Diffusers 环境：

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

Diffusers 默认不会获取缺失的模型文件。查看模型许可和存储空间要求后，可针对特定运行选择启用：

.\.venv\Scripts\python.exe .\scripts\generate_image.py `
  --backend diffusers `
  --model stabilityai/sd-turbo `
  --allow-download `
  --prompt "a compact lunar research station, technical concept art" `
  --seed 42

兼容性工具的文件默认写入 outputs/。可通过 LOCAL_GPU_IMAGEGEN_OUTPUT_DIR 或 --output-dir 覆盖此设置。高级运行会在该输出根目录下使用 runs/<run_id>/ 布局。

架构

flowchart LR
    A["MCP client"] -->|"stdio JSON-RPC"| B["Thin MCP server"]
    B --> H["Discovery + trust + capability router"]
    H --> C["Frozen route + durable run engine"]
    C --> E["AUTOMATIC1111 / Forge adapter"]
    C --> I["Reviewed ComfyUI workflow adapter"]
    C --> F["Diffusers compatibility runner"]
    E --> G["Full local PNG + bounded preview"]
    I --> G
    F --> G
    G --> C
    C --> B
    B --> A

传输层负责 JSON-RPC、架构、验证、分发、超时和结构化结果。运行引擎负责编排，并将持久化状态交由 RunStore 管理；后端加载和图像生成则由 scripts/generate_image.py 负责。

详细的控制流程和错误模型请参阅架构。

安全与隐私

• MCP 进程不会使用特定于应用的云端图像 API。
• 已确认的局域网 WebUI/ComfyUI 端点会将提示词和源图像发送到该服务。环回地址属于本地；每个局域网端点都需要精确确认传输，公共互联网端点会被拒绝。
• 发现过程不会跟随链接，也不会加载检查点载荷。范围更广的文件系统扫描需要使用未更改且未过期的计划，并进行精确确认。
• 信任状态保存在 Git 之外。私有信任绝不会授权公开证据，且会递归拒绝凭据。
• 用户运行 scripts/install.ps1 时，该脚本会下载 Python 软件包。
• Diffusers 模型和 LoRA 下载需要 --allow-download 或 MCP allow_download: true。
• 禁用模型安全检查器必须显式操作，且默认关闭。
• 输入图像和生成文件仍是普通本地文件；请根据其敏感程度，使用合适的操作系统权限保护其目录。

在将 WebUI API 暴露到 localhost 之外之前，请参阅 安全。

测试

该测试套件无需 GPU，也不会下载模型：

python -m unittest discover -s tests -v
python .\scripts\verify_mcp.py

覆盖范围包括协议初始化/列表/连通性检查、精确的十七工具契约、有界发现/引导/信任/路由、WebUI 和 ComfyUI 适配器契约、持久化的根级/子级状态转换、固定的双区域 SDXL 路由/条件设置/耗尽行为、蒙版确认、幂等性、过期尝试恢复、原子发布、有界预览处理、模拟/无模型动漫循环、全部九个固定简报和三个子级修订、假运行器后处理，以及下载策略。

项目状态

已验证：

• stdio MCP 初始化、工具列表、ping 和工具契约
• 结构化工具成功／错误结果
• 在模拟／无模型覆盖下的十五个高级发现／引导／运行／修订工具和两个兼容性工具
• 自适应 Agent Skill 简报、精确模型确认、成功轮次预算，以及如实的纯文本停止策略
• 精确的本地模型身份、用户本地信任、确定性路由和漂移拒绝契约
• 在模拟运行器测试下，明确仅适用于动漫的 Real-ESRGAN 适配器行为
• 经契约测试的 WebUI 和 ComfyUI 适配器成功／失败路径
• 持久化清单的状态转换、幂等性、恢复、审查、最终确认和清理契约
• 三个 Profile 契约，以及不可变的保留／更改子运行和已确认的几何信息／用户蒙版
• 固定的副本／主体几何信息、区域条件、路由漂移拒绝，以及两轮无模型区域垂直切片
• 服务端派生的双阶段控制身份、绑定到控制项的信任确认、矛盾绑定拒绝，以及精确的无模型路由恢复
• 覆盖九个固定简报和三个子修订的模拟后端契约矩阵
• 默认仅限本地的 Diffusers hub 策略
• 可安装的 serve、doctor、verify、config 和默认只读的 setup CLI 契约，包括隔离的 wheel 冒烟测试
• 官方 Codex 和 Claude Code 设置契约解析，以及等效的精确十七工具 stdio 启动；Claude Desktop 仍是旧版仅渲染模板

声称达到 1.0 之前尚待完成：

• 完整且保留证据的 9+3 真实主机／视觉验收矩阵
• 真实 Real-ESRGAN 二进制／GPU 执行证据
• 除保留的 Codex 结果外，更多生成的命名客户端会话证据，包括 Claude Code
• 实测性能或 VRAM 数据
• 任何生产就绪声明

模拟／无模型矩阵是确定性的协议证据，并非保留的真实 Codex／视觉／GPU 结果。它使用模拟后端测试九个固定简报和三个子修订；不能证明视觉质量。已观察到通过项目适配器调用本地 Z-Image 和 Anima，但这属于本地开发验证，不是公开验收证据。历史生成图像记录仍是技术审计材料，不是 v0.9 宣传视觉素材。测试套件不会加载生产模型、GPU 后端或 Real-ESRGAN 二进制文件。不会声称具备生产能力、性能、VRAM、图像质量优势、保证生成 Star，或更广泛的命名客户端生成能力。

此仓库没有获批的 v0.9 宣传图像，也没有完整的真实 9+3 图像验收矩阵。不会作出笼统的图像质量、性能或 VRAM 声明。请使用上述就绪状态命令检查目标环境。

文档

• 架构和错误模型
• 故障排查
• 客户端兼容性
• 协议演示边界
• 发布检查清单
• Stable Diffusion 集成说明
• 贡献指南
• 更新日志

许可证

基于 MIT License 发布。模型权重、后端应用和生成内容各自保留其许可证和条款；此仓库不会为它们重新授权。