dsh-gpt-image

dsh-gpt-image · GPT Image 出图台（DeepSeek Harness 插件）

把 GPT Image Playground（gpt-image2ground）的能力模型搬进 DSH：多服务商 · 多配置档 · 文生图 · 图生图/局部重绘 · 异步任务轮询 · 自定义接口模板 —— 变成 AI 自己就能调用的工具。

独立插件，零运行时依赖（只用 node: 内置模块），装进 profile 不需要再拉依赖树。

---

它和 Playground 的对应关系 · Feature parity

本插件比 Playground 多的几件事：

L–R：自动化编排

⚠ 单机游戏的硬约束（已确认）

Q1 装机数据回传 / Q2 效果反馈校准 / Q4 玩家数据补货 / P4 自动 A/B / J4 真实 A/B —— 这些全部依赖游戏端回传数据。单机游戏没有回传通道，所以：

你指出的冲突，逐个解法

你自检的 7 条，全部补上

诚实说明：三件"做不到"的事

auto action=maintenance 会给出完整维护清单（扫变更→清孤儿→查损坏→悬空结论→健康→备份→告警）， 配合 DSH 的定时任务就是无人值守的日常维护。

声明式流水线（N1）

name: 我的素材流水线
on: [manual, new_asset]
steps:
  - id: postprocess
    use: postprocess
    opts: {defringe: true, sharpen: true}
  - id: slice
    use: slice
  - id: validate
    use: validate
  - id: route
    use: route
  - id: auto_review
    use: auto_review
    opts: {min_confidence: 0.85, sample_after_approve: 0.1}
  - id: install
    use: install

改流程改这个配置，不改代码。pipeline-validate 会检查步骤依赖顺序（install 需要 review 前置）。

F–J：从生成到演进的闭环

F1 模板 ──→ F2 变体矩阵 ──→ batch 执行 ──→ F3 成本汇总
   ↑                                            │
   │                                            ↓
J1 风格指南 ←── 审核通过 ←── A2 规格/A1 后处理 ←──┘
   │                    │
   ↓                    ↓
J2 共享库          C1 派生变体 → C2 图集
                        │
                   H2 来源登记 / H3 备份 / H1 并发锁

质量地基（A–E）

核心思路：把「能不能用」从审美问题降级成技术问题。

工具：quality（check/batch/spec/fix/coherence/animation/variants/atlas/tags/preference/regression）

审核一次、之后自动到底

人只出现在两个地方：审核、冲突。其余全自动。

生成（本插件 / 外部脚本）
      ↓
  磁盘上的素材
      ↓
  审过？─否→ needsReview ──→ 【人：画廊勾选/对比视图拍板】
      │是                          ↓
      ↓                        approved
  直接用                          ↓
      ↓                   自动切片（继承源图结论）
      ↓                          ↓
      └────────→ needsInstall ←──┘
                     ↓
              install 自动装（无人值守）

队列（assets.json.queue，派生数据、可重算）：

needsReview / needsReReview 不阻塞已合格部分的安装。

切片规则的歧义（实测踩了三个坑）

网格从哪来？名字 + 清单 + 磁盘观测三者定，优先级从低到高：

所以 <name>_slices/ 里实际有几个文件才是事实来源；名字解析只用于"还没切过"的情况。

工具：assets（scan/review/clear/pending/changes/queue）、reprocess、quality 接口：/api/assets、/api/changes、/api/compare、/api/review、/api/reprocess

素材目录与审核（为什么以前看不到很多图）

根因：history.json 只记录本插件生成的图。而输出目录里还有大量图来自别处：

实测本机：目录里 916 张，本插件只记了 235 张 → 681 张是"只在文件夹里"的。

现在画廊改为扫磁盘，全部列出来，并给每张分类（source / slice / resized / preview / screenshot）， 顶部两排筛选条可按「类别」与「审核状态」过滤。

一件勾选：

审核结论按素材名也记一份，所以「重画同名的图」会继承你之前的判断（按文件路径的单独结论优先）。

数据落在 ~/.dsh/gpt-image/assets.json，与 history.json 分开 —— 前者是"人工判断"，后者是"生成记录"， 生命周期不同（重画不清掉结论，改结论也不动生成记录）。

给 AI 的约定（assets 工具 guidance 里会明说）：

• 挑素材给游戏用 → 优先 review=approved
• unreviewed 未经人确认，rejected 不要用
• kind=preview（画面里带名字）与 kind=screenshot 是给人看的，不要装进游戏

工具：_dsh_external_dsh_gpt_image_assets（scan / review / clear / pending） 接口：GET /gpt-image/api/assets、POST /gpt-image/api/review、POST /gpt-image/api/review-clear

花钱闸门：免费与付费分开算

免费档（单价 0）的语义是「无限额度」 —— 这是刻意的，因为 0 元没有可防的东西：

免费档在 check() 返回值里会明说 free: true、quota: 'unlimited'、remaining_today: null， 并在 skipped_locks 里列出「本次跳过了哪些锁」，避免用户疑惑「为什么没拦我」。

记账也是分开的（spend.json）：

{
  "records": [ { "images": 5, "cost": 0,    "free": true  },   // 免费：只记张数
               { "images": 3, "cost": 0.12, "free": false } ],  // 付费：记张数 + 金额
  "totals": { "free": { "images": 5, "runs": 1 },
              "paid": { "images": 3, "runs": 1, "cost": 0.12 } }
}

• todayFree() / todayPaid() 分开取；todaySpent() 只算付费（免费恒 0 元，天然不挤占预算）。
• 旧记录没有 free 字段时按金额推断，所以历史数据不会算错。

⚠️ 闸门按「本次实际使用的配置档」算价，不是激活档。 否则「激活档是免费 + 显式指定付费档」会绕过日预算与确认锁 = 漏钱。 7 处闸门调用都传 pricePerImage: priceForProfile(state, args.profile)，并有回归测试钉住。

余额显示怎么看

为什么分两块看：本地闸门才是真正会拦住出图的（真实生效）；上游账户计费多数中转站不提供接口， 且免费档的「额度」是占位数字。所以插件以本地为主、上游为参考，并在详情里如实标注来源。

工具：_dsh_external_dsh_gpt_image_balance（check_remote=false 只看本地不联网） 接口：GET /gpt-image/api/balance（?remote=0 跳过上游查询，面板轮询用）

自动纠错：baseUrl 少写 /v1（中转站最常见的坑）时，先按原样请求，404 自动补 /v1 重试； probe 还会直接告诉你「建议把 baseUrl 改成 xxx」。

---

省钱工作流：攒够一批再生成 · Accumulate, then spend

单价按 0.04 元/张 计（pool.json 里可改 pricePerImage），插件的工作方式是先攒后花：

scan(root="D:\AHC\doomsday-ember")
  → 体检：还缺 16 张素材 → 只登记进「需求池」，一张都不生成
pool(action="show")            → 待生成 16 张 · 阈值 8（卡牌类 12）· 现在跑要花 0.64 元
pool(action="flush", dry_run=true)  → 只规划：冷启动先 1 张探针、本轮最多几张、预计花费
pool(action="flush", confirm=true)  → 到阈值才一次性跑，跑完自动从池子划掉
install(root="D:\AHC\doomsday-ember")  → 按规格缩放(保留透明) → 写进游戏 → 立刻复核尺寸与引用
screenshot(mode="window", window="<游戏窗口>", attach=true)  → 重大改动后截图给用户看

两道花费闸门：①没到阈值不给跑（除非 force=true）；②一批超过 autoSpendLimit（默认 0.5 元） 必须显式 confirm=true。所有预估都写在返回里，先看数字再决定。

install 解决的正是黑屏：模型只能出 1024 级别大图，游戏要 40×60 这种规格；手工缩放很容易做出 几百字节的空图（wx_clear_tile_40x60.png 就是 450 字节 → 黑屏）。install 统一按规格缩放 （保留 alpha，实测 1024×1536 → 40×60 透明 3.4KB）→ 落到游戏真正读的位置（同名文件先备份 .bak-before-install）→ 复核，未登记的还会告诉你差哪一步。

---

多花钱的三个真 bug（已修 · Money-leak fixes）

自查真实使用数据时发现的三处「钱会漏掉」的地方，都已修好并有回归测试：

实测：拿历史里 starcraft-rts / flag_terran 的原参数再要一次 → skipped_duplicate = true, spent = 0，直接复用已有产物。

另外：硬规定不允许静默失效 —— 「画面内带名字」的预览图如果没做出来， 返回里会明确给出 label_warning + label_errors，不再悄悄跳过（你的历史里曾有 3/8 张没标签）。

---

第四轮：审批流 + 跨项目风格 + 图标集批量生成

1. 资产预算审批流（approval）

四道锁拦的是「单次张数/日预算」，但一次 5 元、10 元的大批采购属于"要跟人商量"的量级，单独拎出来：

batch(assets=[...6 个...], confirm=true)
  → needs_approval: true，返回待批准单（没花任何钱）
【待批准】batch · demo
  要花：0.24 CNY（6 张）
  用途：塔防第一批通用素材
  画什么：tower_fire、tower_ice、enemy_grunt、enemy_boss、icon_coin、icon_heart
  影响范围：src/game.js
  单号：apr_861af39046ac6d8c

approval(action="approve", token="apr_861af39046ac6d8c")
  → 已批准。把 approved_token 传给对应工具就会执行。

• 面板上点确认：新增「待批准」标签页，直接点批准/驳回；超 24h 未处理会标红
• 单子有签名：approvalToken() 由参数决定 —— 参数变了单子自动作废（防止批了 A 跑了 B）。实测：6 张批准后放行；改成 7 张立刻出新单号
• 阈值默认 5 元，approval action=set_threshold 可改；待批准单文本可直接贴进对话

2. 跨项目风格对比（cross_style）

你怀疑的「两个项目风格差异大」已经量化了，实测输出：

doomsday-ember  ↔ starcraft-rts      = 0.243  ← 两套美术语言，别互相参考
starcraft-rts   ↔ workbuddy-deploy   = 0.164  ← 差异最大
workbuddy-deploy↔ 连通性测试          = 0.496  ← 风格接近，可共享参考
警告：检测到跨项目风格差异明显：生成时请只用「同项目」的素材当风格参考。

配套强制约束：挑参考图时若没指定项目，直接拒绝跨项目挑（cross_project_blocked）——宁可没有参考图，也不要串味。面板新增「跨项目风格」页。

3. 图标集批量生成（sheet）· 切图后自动对齐

你说得对，你们本来就有这个习惯（147_whole、r42_cardart_sheet）。现在做成工具：

sheet(items=[9 个图标描述], project="tower-defense")
  → 1 个请求出 1536×1024 合集图 → 自动按 3×3 切开 → 每个图标自动对齐 → 缩放到游戏规格
  → requests_used: 1, requests_saved: 8

切图默认自动对齐（trim: true），交付的是「能直接用的图标」而不是「格子」：

实测（故意做了一张「图标大小不一、位置歪、还有空格子」的合集图）：

icon_1  格内 100×100 → 内容 20×20  → 输出 48×48  居中偏差 0.0/0.0
icon_2  格内 100×100 → 内容 60×40  → 输出 48×48  内容画成 48×32 垂直居中
icon_3  格内 100×100 → 内容 30×15  → 输出 48×48
icon_4  格内 100×100 → 内容 40×60  → 输出 48×48  内容画成 32×48 水平居中
icon_5  空间格子                       → 警告「没找到图标主体」
icon_6  格内 100×100 → 内容 25×25  → 输出 48×48

过程中修掉一个真 bug（坐标系）：contentBox 返回的是「格内相对坐标」， 跨格裁剪必须先用 absoluteBox() 转成整图绝对坐标 —— 第一版混用了，导致 图标被裁到角落甚至整张全透明（测试图里 icon_3/icon_6 空白）。现在两个坐标系显式分开， 并有专门的回归测试（tests/autotrim.test.js）锁死。

参数：trim（默认 true）、target_width/target_height（缩放规格）、mode（contain/stretch）、 padding（格子内缩）；items 支持逐格指定尺寸（[{name:"icon",width:48,height:48}]）。

本轮新增工具（3 个，共 20 个）

---

优化

新扩展

本轮修掉的 3 个真 bug

1. heatmap 缺 import → checkProject is not defined，工具直接报错
2. review 用错字段 → result.reviewed is not iterable（实际字段是 suspects/good_files）
3. 热度把预览图当素材 → 会把 xxx_labeled.png 报成"白花钱"

---

三项扩展 · Three extensions

新增工具

register 的一个关键保护

你的 src/84_assetmap.js 和 src/96_rpgasset.js 文件头写着「由 tools/build.mjs 自动生成，请勿手改」。 写它们等于白写（下次构建覆盖），所以 register 会识别并拒绝，同时告诉你该改哪个源文件：

84_assetmap.js skipped: 这是构建生成物（文件头写着「build.mjs」），改了会被下次构建覆盖

另外 register 兼容你项目的真实登记格式： "key":{"s":"data:image/png;base64,...","w":40,"h":60,"base":0,"g":"wx","label":"晴天叠加层"} —— 只替换 s/w/h，保留 base/g/label 等字段，写前备份 .bak-before-register。 action=audit 实测：96_rpgasset.js 里 323 项全部填了真图，没有破图。

---

每次要花钱的调用（generate / edit / batch / pool.flush）都必须先过 spend.js 的闸门， 记账落在 ~/.dsh/gpt-image/spend.json：

查账 / 改锁：

config(action="spend")                                  → 今天几张、多少钱、预算、日历、趋势
config(action="calibrate", images=12, actual_cost=0.48) → 用真实扣费校准单价
config(action="set_locks", patch={"dailyBudget":2})     → 改预算
config(action="set_locks", patch={"pricePerImage":0.03})→ 单价按 3 分算
config(action="set_locks", patch={"spendDisabled":true})→ 急停，别想花我一分钱

需求池只收真缺口：报告文档、tools/、scripts/、tests/、out/ 以及 _ 开头的临时名 全部过滤掉（实测清掉了 36 条垃圾，否则会为文档里的截图白花钱）。

风格参考：generate/batch/pool.flush 带 use_style_refs=true 时，会自动从 游戏现有素材（同分类优先）→ 本项目已生成的图里挑 1~2 张当参考图走图生图， 并追加「严格对齐参考图的画风/线条/配色」的提示词；也可显式传 style_refs=[路径]。

---

DSH 里只保留这一个生图插件（原来的「素材锻造炉」已整体并入本插件，不再单独安装）：

画廊里每条都带：

• 缩略图（透明图用棋盘底，一眼看出有没有抠干净）+ 完整提示词 + 模型/尺寸/质量/耗时
• 核对徽章：达标 / 规格不符 / 没被引用 / 用不上
• 核对明细：游戏要求（尺寸/透明/可平铺）↔ 实际生成，以及游戏代码里哪些文件引用了它
• 顶部可选项目、填游戏目录（会记住）、「体检」按钮跑一遍缺什么素材
• 每 5 秒自动刷新，AI 正在出图时能看着一张张冒出来

素材核对是怎么判的

规格要求从项目里的 待画素材清单.md 这类表格自动读（| 素材 | \key` | 40×60，透明、可平铺 |`）， 引用统计只看代码/配置（md/txt 清单与报告不算「在用」）。

---

安装 · Installation

从 DSH 商店装（推荐）

设置 → 插件 → 发现（Discover）→ 添加插件源，填：

https://gcore.jsdelivr.net/gh/yyfabab1/dsh-gpt-image@main/market-index.json

索引格式是 DSH 商店的 format 1；生成/校验方式见 docs/商店发布.md。

Windows 一键安装

:: 先只检查环境（不改任何文件、不重启）
一键安装.bat check

:: 确认没问题后正式装（会重启 DSH）
一键安装.bat

一键脚本会：检查 Windows / Node 20+ / 定位 DSH profile → 自检插件本体（工具数、侧栏配对）→ 建目录链接（失败自动改用复制）→ 重启 DSH → 打开 安装说明.html。 跳过重启：set AUTO_NORESTART=1。脚本本体是 install.ps1（UTF-8 BOM）， .bat 只做纯 ASCII 启动 —— 因为 .bat 里写 UTF-8 中文在 chcp 65001 下会被拆成碎命令（实测）。

⚠️ 跨机器风险：只在作者本机（Windows + Node 22）验证过。 完整风险清单见 安装说明.html（浏览器打开，含可点击的 API 申请入口）。

手动安装

# 本地路径（目录链接，改代码即时生效）
mklink /J "%USERPROFILE%\.dsh\profiles\web\node_modules\@dsh-external\dsh-gpt-image" "D:\你的路径\dsh-gpt-image"

# 或 npm 包
dsh plugin --profile web add @dsh-external/dsh-gpt-image

装完重启 DSH，模型侧会多出 _dsh_external_dsh_gpt_image_* 工具，浏览器可开 http://127.0.0.1:3080/gpt-image 面板。

自检

npm test                        :: 687 个测试应全过
node scripts\ inventory.mjs      :: 27 工具 / 32 路由 / 4 侧栏页配对

---

API Key 去哪申请

完整清单（含全部网址、每家文档、免费图床可达性实测）见 docs/API_KEYS.md， 或者直接浏览器打开 安装说明.html —— 那里的按钮点了就跳到官网注册页。

速查：

---

预览图开关（*_labeled.png）

每张生成的素材都会配一张「画面里印着素材名」的预览图 —— 素材一多就知道哪张是哪张。 但预览图默认一直是原尺寸，一张 1024×1024 素材的预览图也是完整 1024×1024 PNG（约 1MB）。 实测攒了 535 张、吃掉 928MB，直接把磁盘塞满。

现在有三档（config(action="set_label")）：

config(action="set_label", mode="small", max_side=384)   // 默认
config(action="set_label", mode="off")                   // 完全不要预览图
config(action="purge_labeled", dry_run=true)             // 先看有多少历史预览图
config(action="purge_labeled", dry_run=false)            // 真删

关掉时插件返回 skipped: true 而不是报错 —— 「跳过」和「失败」必须分开， 否则每次生成都会挂一条假的"预览图失败"警告。

动画变体 · Variants（同款换配色，不重跑管线）

一个动画做好后，"红/蓝阵营 / 缴获版 / 受损版"是常见需求。逐变体重跑「锚点→视频→抽帧」的代价是 每变体几分钟 + 每变体细节都可能不一样。变体继承只改颜色：

spritesheet(action="variant", sheet="soldier_walk_loop_sheet.png",
            variants=[{name:"walk_blue", preset:"blue"},
                      {name:"walk_red",  preset:"red"}])

预设 red/blue/green/purple/yellow/captured/damaged/ghost；也可手调 hue/saturation/ brightness/grayscale/tint/palette。只改颜色，alpha 与几何一个像素都不动； 帧数/格子/帧率/时序全部继承源表，JSON 里记下 variant_of 与 recolor 配方。

限制：hue 是全局旋转，会连肤色/金属色一起带走。只换制服用 palette 精确指定颜色对。

动画装机 · Install animations（按格子缩放）

静态图按整图宽高缩放；动画必须按格子算倍率（5×2 的表按整图缩放会得到 185.6 像素的格子 → 切帧错位）。

install(action="anim-list", project="xxx")                       // 有哪些动画
install(action="anim", project="xxx", root="D:\游戏",
        cell_width=96, cell_height=176)                          // 默认 dry_run

宽高倍率不一致会拒绝（拉伸会变形）并给出建议尺寸。产出：缩放后的精灵表 + <名字>.anim.json（帧坐标按缩放后重算）+ 同名备份 .bak-before-install。

产出目录收敛 · Output layout

副产物太多分不清哪个给游戏用。现在四类：

assets(action="layout",   project="xxx")   // 清点
assets(action="organize", project="xxx")   // 演练，默认 dry_run

整理只动 preview + intermediate，source 一个都不动（被引用着，移动即断引用）； derived 默认不动（切片可能就是游戏在用的单张），要动得显式 `include_derived=true