dsh-h3-image 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 dsh-h3-image contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+NOTE: This license covers the plugin source code only. The MiniMax H3-Image
+model weights are distributed separately by MiniMax under the MiniMax H3
+Image Community License Agreement (shown inside the setup wizard before any
+download), and the upstream MLX engine is Apache-2.0. See
+THIRD_PARTY_NOTICES.md.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# dsh-h3-image
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** | [简体中文](README.zh.md)
+
+> **Name reserved.** This package version (0.2.0) ships the full local
+> pipeline: the read-only environment check, the one-time setup wizard
+> (venv → pinned engine clone → license gate → sha256-verified weight
+> download with resume → smoke test, each long step a background job that
+> survives restarts), and text-to-image. Nothing here calls any cloud
+> service.
+
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH)
+plugin bundle that runs the open-source **MiniMax H3-Image** text-to-image
+model **entirely on your own Apple Silicon Mac**, through the
+[MLX](https://github.com/ml-explore/mlx) engine. No API keys, no accounts, no
+per-image fees, no egress during generation.
+
+## What you get
+
+| Tool | Purpose |
+| --- | --- |
+| `h3_status` | Read-only health check: platform, unified memory, venv, engine commit, weights, text encoder, free disk — each red item carries a fix hint. |
+| `h3_setup` | The one-time setup wizard as a resumable state machine: `check → venv → engine → license → weights → smoke`. Long steps (engine install, ~59 GB of downloads + conversion) run as detached background jobs — submit returns a `job_id` in seconds, `action=poll` reads progress from the engine's own on-disk state, and an interrupted download resumes from `.part` on re-run. A dead job is reported `interrupted`, never "done". `action=license` shows the community license; acceptance is recorded only by you. `action=reset` clears the local state record. |
+| `h3_image` | Text-to-image: one engine subprocess per call, internal deadline, one generation at a time (a second call gets an immediate `busy`), PNG verified before it is reported, output lands in your session workspace. |
+
+## Requirements
+
+- Apple Silicon Mac (the engine is arm64-only; Intel/Windows/Linux are
+  declined by `h3_status`, not by a crash).
+- **48 GB+ unified memory recommended**; 32 GB machines are warned-then-
+  confirmed, below 32 GB is refused.
+- ~60 GB free disk during setup (measured peak on a from-zero install; the
+  steady state after the engine deletes source shards is ~53 GB — see the
+  resource ledger below).
+- DSH ≥ 0.2.2-rc.1, Node ≥ 22.19.
+
+## Resource ledger (measured, bare-metal acceptance 2026-11-12/13)
+
+Every number below comes from one from-zero acceptance run on a 275 GB
+Apple Silicon machine (no reuse candidates, fresh venv/engine/weights) —
+not from estimates.
+
+| Item | Measured |
+| --- | --- |
+| Disk peak (incremental, whole setup) | 58.6 GB (54.6 GiB): DiT pack 21.5 + text encoder 28.2 + one in-flight source shard 5.4 + venv 1.1 |
+| Disk steady state (post-setup) | 53.2 GB (source shards deleted by the engine after conversion) |
+| venv creation | ~18 s (reuses a suitable standalone CPython when found; reports a miss otherwise) |
+| Engine clone + pip install | ~72 s |
+| Weights: per transformer shard (download 5.5 GB + Q8 convert + delete) | ~4–5 min |
+| Weights: resume segment (7 shards + 28.2 GB text encoder) | 41 min |
+| Smoke generation | 30 s wall / 10.8 s engine time (1 MP, 6 steps) |
+| Generation peak memory (engine metrics) | 27.5 GB per image at 1 MP |
+| Host memory in use during the run | 274 GB — includes a resident inference server; the plugin's own footprint is the 27.5 GB above |
+
+Interrupted steps resume: a killed download continues from its `.part`
+(Range requests), and finished shards are never re-fetched — verified by
+the acceptance run's resume audit (zero re-downloads of completed shards).
+
+## Licenses — read before downloading weights
+
+This plugin's **code** is MIT. It does not ship, re-host or re-distribute the
+model. The setup wizard downloads the weights from the official Hugging Face
+repository at a pinned revision, and **shows you the MiniMax H3 Image
+Community License Agreement — including its territorial exclusions — before
+any byte is fetched. You accept it yourself; the plugin never accepts on your
+behalf.** The upstream engine is Apache-2.0. See
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+## Install (DSH)
+
+```
+plugin_manager → install_bundle → <this repo or the npm package>
+```
+
+Then enable the bundle in your profile and run `h3_status` — it tells you
+exactly what the machine still needs.
+
+## Development
+
+```sh
+npm test                                   # unit tests (pure check logic)
+npm run release                            # gates + pack + tarball scan
+```
+
+Two release gates run in CI and on `prepack`:
+`scripts/check-release-safety.mjs` (no machine fingerprints, no AppleDouble,
+no secrets — in source **and** in the built tarball) and
+`scripts/check-version-consistency.mjs` (package.json ↔ CHANGELOG ↔ locales ↔
+pinned revisions).

package/README.zh.md

@@ -0,0 +1,80 @@
+# dsh-h3-image
+
+[English](README.md) | **简体中文**
+
+> **名称已占位。** 当前版本（0.2.0）交付完整本地链路：只读环境体检、一键安装
+> 向导（venv → 钉定引擎 clone → 许可确认 → sha256 校验的权重下载（支持断点
+> 续传）→ 冒烟出图，每个长步骤都是重启不丢的后台任务），以及本地文生图。
+> 全程不调用任何云服务。
+
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）
+插件包，通过 [MLX](https://github.com/ml-explore/mlx) 引擎在你的 **Apple
+Silicon Mac 上完全本地**运行开源的 **MiniMax H3-Image** 文生图模型。
+零 API 密钥、零账号、零按图计费，生图过程零出网。
+
+## 提供什么
+
+| 工具 | 用途 |
+| --- | --- |
+| `h3_status` | 只读体检：平台、统一内存、venv、引擎 commit、权重、文本编码器、可用磁盘——每一项红灯都附修复提示。 |
+| `h3_setup` | 一次性安装向导，可续跑的状态机：`check → venv → engine → license → weights → smoke`。长步骤（引擎安装、约 59 GB 下载 + 转换）以脱离进程组的后台任务运行——提交秒级返回 `job_id`，`action=poll` 从引擎自己的磁盘状态读进度，中断的下载重跑即从 `.part` 续传。进程已死的任务如实报 `interrupted`，绝不谎报"完成"。`action=license` 展示社区许可，只有你本人确认才会记录接受。`action=reset` 清除本机状态记录。 |
+| `h3_image` | 文生图：每次调用一个引擎子进程，内置截止时间，同一时刻只跑一张（第二路立即收到 `busy`），PNG 结构校验通过才报成功，产物落在会话工作区。 |
+
+## 环境要求
+
+- Apple Silicon Mac（引擎仅支持 arm64；Intel/Windows/Linux 在 `h3_status`
+  检查阶段即明确拒绝，而不是崩溃）。
+- **推荐 48 GB 及以上统一内存**；32 GB 机器先警告再确认，低于 32 GB 拒绝。
+- 安装期约 60 GB 可用磁盘（from-zero 安装的实测峰值；引擎删除源分片后的
+  稳态约 53 GB——见下方资源账表）。
+- DSH ≥ 0.2.2-rc.1，Node ≥ 22.19。
+
+## 资源账（实测，裸机验收 2026-11-12/13）
+
+下表每个数字都来自 275 GB Apple Silicon 机器上的一次 from-zero 验收运行
+（无复用候选、全新 venv/引擎/权重）——不是估算。
+
+| 项目 | 实测 |
+| --- | --- |
+| 磁盘峰值（增量，整个安装过程） | 58.6 GB（54.6 GiB）：DiT 打包 21.5 + 文本编码器 28.2 + 在途源分片 5.4 + venv 1.1 |
+| 磁盘稳态（安装完成后） | 53.2 GB（源分片由引擎转换后自行删除） |
+| venv 创建 | 约 18 秒（能发现合适的独立 CPython 就复用，探测不到如实报 miss） |
+| 引擎 clone + pip 安装 | 约 72 秒 |
+| 权重：每个 transformer 分片（下载 5.5 GB + Q8 转换 + 删除） | 约 4–5 分钟 |
+| 权重：续传段（7 分片 + 28.2 GB 文本编码器） | 41 分钟 |
+| 冒烟出图 | 墙钟 30 秒 / 引擎耗时 10.8 秒（1 MP，6 步） |
+| 单图内存峰值（引擎 metrics） | 1 MP 每图 27.5 GB |
+| 运行期间主机已用内存 | 274 GB——含常驻推理服务；插件自身占用即上行 27.5 GB |
+
+中断可续：被杀的下载从 `.part` 继续（Range 请求），已完成分片绝不重下——
+验收运行的续传对账为证（零重下已完成分片）。
+
+## 许可——下载权重前必读
+
+本插件的**代码**是 MIT。**不打包、不转载、不分发模型。** 安装向导从官方
+Hugging Face 仓库按钉定 revision 下载权重，并且**在任何一个字节下载之前，
+向你展示 MiniMax H3 Image 社区许可协议（含其地域排除条款）。由你本人接受；
+插件永不代你接受。** 上游引擎为 Apache-2.0。见
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
+
+## 安装（DSH）
+
+```
+plugin_manager → install_bundle → <本仓库或 npm 包>
+```
+
+然后在 profile 中启用该 bundle，跑一次 `h3_status`——机器还缺什么它逐项
+告诉你。
+
+## 开发
+
+```sh
+npm test                                   # 单元测试（纯检查逻辑）
+npm run release                            # 门禁 + 打包 + tarball 扫描
+```
+
+两道发布门禁在 CI 和 `prepack` 上运行：
+`scripts/check-release-safety.mjs`（零机器指纹、零 AppleDouble、零密钥——
+源码**和**构建出的 tarball 都扫）与
+`scripts/check-version-consistency.mjs`（package.json ↔ CHANGELOG ↔ locale ↔
+钉定 revision 一致性）。

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security policy
+
+## Design summary
+
+- **No secrets.** The plugin has no API keys, tokens, or credentials of any
+  kind. Local inference needs none.
+- **Zero runtime egress.** Generation is pure local subprocess work. The only
+  network activity in the plugin's lifetime is the setup wizard fetching the
+  pinned engine (GitHub) and weights (huggingface.co, or an optional
+  hf-mirror you explicitly choose). Every fetched file is sha256-verified
+  against a value recorded in `lib/pinned.js`.
+- **Sandboxed outputs.** Generated images are written inside the session
+  workspace by default; an `output_dir` outside the workspace is rejected.
+- **Subprocess discipline.** The engine runs as a child process from the
+  pinned commit inside an isolated venv; prompts are passed as arguments,
+  never interpolated into a shell string. Concurrency gate = 1.
+- **License self-acceptance.** Weight download requires the user's own
+  acceptance of the MiniMax community license (including its territorial
+  terms); the plugin records the acceptance timestamp locally and never
+  accepts on the user's behalf.
+
+## Reporting a vulnerability
+
+Open a **private security advisory** on the GitHub repository
+(`aiohow/dsh-h3-image` → Security → Report a vulnerability). Please do not
+open a public issue for unfixed vulnerabilities. We aim to respond within 7
+days.
+
+## Out of scope
+
+- Vulnerabilities in the upstream engine (`minimax-h3-mlx`) or model weights
+  — report those to their respective upstreams; we will pin a fixed revision
+  promptly if a release affects users.
+- Attacks that already require code execution on your machine.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,32 @@
+# Third-party notices
+
+dsh-h3-image (plugin code) is MIT-licensed. It does **not** bundle, vendor,
+re-host or re-distribute any of the following; the setup wizard downloads
+each item from its official upstream at a pinned revision, on the user's
+machine, after the user accepts the respective license where required.
+
+## MLX engine — `minimax-h3-mlx`
+
+- Upstream: <https://github.com/mrbizarro/minimax-h3-mlx>
+- License: Apache-2.0 (see the upstream `LICENSE`)
+- Pinned commit: recorded in `lib/pinned.js` (`ENGINE.commit`). The wizard
+  clones and checks out exactly this commit; `main` is never followed.
+
+## Model weights — `MiniMaxAI/MiniMax-H3-Image` (+ text encoder from `MiniMaxAI/MiniMax-H3`)
+
+- Upstream: <https://huggingface.co/MiniMaxAI/MiniMax-H3-Image>
+- License: MiniMax H3 Image Community License Agreement (upstream `LICENSE`
+  file). **The license includes territorial exclusions** — read the upstream
+  LICENSE text yourself before downloading; the wizard shows it and requires
+  your explicit acceptance. The plugin never accepts on your behalf.
+- Pinned revisions: recorded in `lib/pinned.js` (`WEIGHTS.revision`,
+  `TEXT_ENCODER.revision`); every downloaded file is verified against a
+  recorded sha256.
+
+## Runtime — Python ≥ 3.13 + MLX
+
+- The wizard creates an isolated virtual environment on your machine and
+  installs the engine's declared dependencies (MLX is Apple-licensed, other
+  packages under their own licenses). The plugin ships none of them.
+
+No trademark or brand assets of MiniMax are included in this package.

package/assets/te_setup.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Text-encoder fetch driver for dsh-h3-image (bundled asset, not engine code).
+
+Why this exists instead of calling the engine's download_selected.py: that
+script downloads three repos including video/audio VAEs and a pruned bf16
+checkpoint this plugin's image path never loads, and it takes no pinning
+parameters. This driver downloads EXACTLY the pinned file set, verifies the
+main safetensors against a pinned sha256 + byte size, and honours a reuse
+candidate list (sha256 verdict only — a size match alone never authorizes
+reuse; it is reused by symlink, never by copy).
+
+Progress contract (parsed by lib/jobs.js, all flushed):
+    [te n/N] fetched <name>
+    [te n/N] reused <name> (<path>)
+    [te n/N] skipped <name> (already present)
+    TE OK
+
+Resumability: huggingface_hub keeps .incomplete part files and resumes them;
+small files are atomic via .part + rename.
+
+Mirror: set HF_ENDPOINT before launching (e.g. https://hf-mirror.com) —
+hf_hub_download honours it. Nothing here hardcodes an endpoint.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import sys
+from pathlib import Path
+
+
+def sha256_of(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 22), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--dest", type=Path, required=True, help="text-encoder folder (the engine's --text-dir)")
+    ap.add_argument("--meta-dest", type=Path, required=True, help="folder for upstream meta (FL2VA/...)")
+    ap.add_argument("--repo", required=True)
+    ap.add_argument("--revision", required=True)
+    ap.add_argument("--files", required=True, help="comma-separated file list from the pinned package")
+    ap.add_argument("--main-file", default="text_encoder.safetensors")
+    ap.add_argument("--sha256", required=True, help="pinned sha256 of the main file")
+    ap.add_argument("--bytes", type=int, required=True, help="pinned byte size of the main file")
+    ap.add_argument("--meta-repo", required=True)
+    ap.add_argument("--meta-revision", required=True)
+    ap.add_argument("--meta-files", required=True, help="comma-separated upstream paths (kept under meta-dest)")
+    ap.add_argument("--candidates-file", type=Path, default=None, help="newline list of size-matching candidate paths to hash")
+    args = ap.parse_args()
+
+    # Xet high-performance mode is documented by Hugging Face for large single
+    # files; harmless when the endpoint does not serve Xet.
+    os.environ.setdefault("HF_XET_HIGH_PERFORMANCE", "1")
+    from huggingface_hub import hf_hub_download
+
+    files = [f for f in args.files.split(",") if f]
+    total = len(files)
+    args.dest.mkdir(parents=True, exist_ok=True)
+
+    def download(repo: str, revision: str, name: str, dest: Path) -> Path:
+        dest.mkdir(parents=True, exist_ok=True)
+        return Path(hf_hub_download(repo, filename=name, revision=revision, local_dir=str(dest)))
+
+    reused = False
+    main_path = args.dest / args.main_file
+    if main_path.exists() and main_path.stat().st_size == args.bytes and sha256_of(main_path) == args.sha256:
+        print(f"[te 1/{total}] skipped {args.main_file} (already present, sha256 match)", flush=True)
+        reused = True
+    else:
+        candidate_ok = False
+        if args.candidates_file is not None and args.candidates_file.exists():
+            for line in args.candidates_file.read_text().splitlines():
+                cand = Path(line.strip())
+                if not cand.is_file() or cand.stat().st_size != args.bytes:
+                    continue  # size mismatch: not even worth hashing
+                print(f"[te 0/{total}] hashing reuse candidate {cand.name} ({args.bytes / 1e9:.1f} GB)", flush=True)
+                if sha256_of(cand) == args.sha256:
+                    # Exact digest match (design D3): reuse by symlink, never copy.
+                    if main_path.exists() or main_path.is_symlink():
+                        main_path.unlink()
+                    main_path.symlink_to(cand)
+                    print(f"[te 1/{total}] reused {args.main_file} (sha256 verified)", flush=True)
+                    candidate_ok = True
+                    reused = True
+                    break
+                print(f"[te 0/{total}] candidate {cand.name} hash MISMATCH — will download", flush=True)
+        if not candidate_ok:
+            got = download(args.repo, args.revision, args.main_file, args.dest)
+            size = got.stat().st_size
+            if size != args.bytes:
+                print(f"SIZE MISMATCH {args.main_file}: got {size}, expected {args.bytes}", flush=True)
+                return 3
+            digest = sha256_of(got)
+            if digest != args.sha256:
+                print(f"SHA256 MISMATCH {args.main_file}: got {digest}, expected {args.sha256}", flush=True)
+                got.unlink(missing_ok=True)
+                return 3
+            print(f"[te 1/{total}] fetched {args.main_file} (sha256 verified)", flush=True)
+
+    rest = [f for f in files if f != args.main_file]
+    for i, name in enumerate(rest, start=2):
+        target = args.dest / name
+        if target.exists() and target.stat().st_size > 0:
+            print(f"[te {i}/{total}] skipped {name} (already present)", flush=True)
+            continue
+        download(args.repo, args.revision, name, args.dest)
+        print(f"[te {i}/{total}] fetched {name}", flush=True)
+
+    for name in [f for f in args.meta_files.split(",") if f]:
+        target = args.meta_dest / name
+        if target.exists() and target.stat().st_size > 0:
+            print(f"[te meta] skipped {name} (already present)", flush=True)
+            continue
+        download(args.meta_repo, args.meta_revision, name, args.meta_dest)
+        print(f"[te meta] fetched {name}", flush=True)
+
+    print("TE OK", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-h3-image bundle patch: insert this package's Host half.
+# Loaded only when the profile selects the bundle
+#   (dsh.profile.bundles: [..., "dsh-h3-image"]) or the entry is added
+# to the profile's cordis.patch.yml as an `insert`.
+- insert:
+    - id: h3-image
+      name: dsh-h3-image
+      config: {}

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36">
+  <rect x="6" y="5.5" width="24" height="17" rx="3" fill="none" stroke="#4c6ef5" stroke-width="2.4"/>
+  <circle cx="13.5" cy="11.5" r="2.2" fill="#4c6ef5"/>
+  <path d="M8.6 19.6l5.2-5.8 3.8 4.2 3.4-3.9 5.4 5.5z" fill="#4c6ef5"/>
+  <path d="M22.4 23.4l-3.4 5.2h3.1l-1.1 3.9 4.9-5.9h-3.1l2.1-3.2z" fill="#2f9e8f"/>
+</svg>