[codex] add neural watermark scaffold

.gitattributes

@@ -0,0 +1,4 @@
+resources/models/**/*.onnx filter=lfs diff=lfs merge=lfs -text
+artifacts/promoted/**/*.onnx filter=lfs diff=lfs merge=lfs -text
+artifacts/promoted/**/*.ckpt filter=lfs diff=lfs merge=lfs -text
+artifacts/promoted/**/*.safetensors filter=lfs diff=lfs merge=lfs -text

.github/workflows/python-engine.yml

@@ -6,61 +6,76 @@ permissions:
   contents: read
 
 jobs:
-  build:
+  python-smoke:
     runs-on: ubuntu-latest
     name: Test robust watermark engine
     defaults:
       run:
         working-directory: blind_watermark
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.10'
       - name: Install dependencies
         run: |
           pip install -r requirements.txt
-      - name: Smoke test — import and roundtrip
+      - name: Smoke test - import and roundtrip
         shell: python {0}
         env:
           PYTHONPATH: .
         run: |
           from rwm_engine import embed_watermark, extract_watermark, check_dependencies
           import numpy as np
+
           dep = check_dependencies()
           assert dep['ok'], f'Missing deps: {dep}'
+
           img = np.random.randint(0, 256, (800, 800, 3), dtype=np.uint8)
-          wm = embed_watermark(img, 'hello world', password=42, quality='balanced')
-          extracted = extract_watermark(wm, password=42, quality='balanced')
-          assert extracted == 'hello world', f'Roundtrip failed: {extracted}'
+
+          embedded = embed_watermark(
+              img,
+              'hello world',
+              password=42,
+              quality='balanced',
+          )
+          assert embedded['ok'], f'Embed failed: {embedded}'
+          assert embedded['image'] is not None, f'Embed image missing: {embedded}'
+          assert embedded['engine_used'] in {'legacy', 'neural'}, embedded
+
+          extracted = extract_watermark(
+              embedded['image'],
+              password=42,
+              quality='balanced',
+          )
+          assert extracted['ok'], f'Extract failed: {extracted}'
+          assert extracted['wm'] == 'hello world', f'Roundtrip failed: {extracted}'
+
           print('All tests passed.')
 
   mlwm-unit-tests:
     runs-on: ubuntu-latest
     name: MLWM unit tests
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.10'
-      - name: Run MLWM unit tests when present
-        shell: bash
+      - name: Install dependencies
+        run: |
+          pip install -r blind_watermark/requirements.txt
+      - name: Run MLWM unit tests
         run: |
-          if [ -d blind_watermark/tests ]; then
-            pip install -r blind_watermark/requirements.txt
-            python -m unittest discover -s blind_watermark/tests
-          else
-            echo "No blind_watermark/tests directory exists on this branch yet."
-          fi
+          python -m unittest discover -s blind_watermark/tests
 
   typecheck:
     runs-on: ubuntu-latest
     name: Typecheck
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
-          node-version: '20'
+          node-version: '24'
           cache: npm
       - name: Install dependencies
         run: npm ci

.gitignore

@@ -4,6 +4,7 @@ out
 .DS_Store
 .eslintcache
 *.log*
+
 # PyInstaller output (pre-built bwm_helper executable, generated via npm run build:python)
 resources/bin/
 build/
@@ -28,12 +29,27 @@ __pycache__/
 *.pyd
 .pytest_cache/
 .mypy_cache/
+.venv*/
+.ruff_cache/
+.hypothesis/
 
 # Build/cache artifacts
 coverage/
 *.tsbuildinfo
 tmp/
 temp/
+artifacts/mlwm_v1/runs/
+artifacts/mlwm_v1/tensorboard/
+artifacts/mlwm_v1/tmp/
+artifacts/promoted/**/*.tmp
+artifacts/promoted/**/*.log
+resources/models/neural_wm/*.tmp
+resources/models/neural_wm/*.pt
+resources/models/neural_wm/*.ckpt
+resources/models/neural_wm/*.safetensors
+resources/models/neural_wm/*.bin
+data/
+datasets/
 
 # Test images
-blind_watermark/测试图*.png
+blind_watermark/濞村鐦崶?.png

README.md

@@ -26,9 +26,21 @@ LuminCrypt is a desktop security toolkit for **Unicode hidden-character detectio
 - **Unicode hidden character detection**: finds zero-width characters, BiDi controls, homoglyphs, Unicode Tags, variation selectors, and non-standard spaces.
 - **Encrypted text watermarking**: embeds AES-256-GCM protected payloads into normal text with invisible Unicode carriers and robust redundancy.
 - **Blind image watermarking**: uses a Python image watermark engine based on block-DCT, QIM-style embedding, Reed-Solomon recovery, and multi-scale extraction.
+- **Learning-assisted robust watermarking**: includes an experimental MLWM v1 alpha engine for short image payloads, ONNX inference, attack simulation, benchmark manifests, and automatic fallback to the legacy image watermark engine.
 - **Batch processing and reports**: scans files in batches and exports detection results as JSON, CSV, or PDF.
 - **Local desktop workflow**: built with Electron, React, TypeScript, and a Python helper for image watermark processing.
 
+## Project Status
+
+| Area | Status |
+|---|---|
+| Unicode hidden-character detection | Usable |
+| Encrypted text watermarking | Usable |
+| Legacy image blind watermarking | Usable |
+| MLWM v1 neural image watermarking | Alpha, short payloads only |
+
+`mlwm-v1-alpha1` is the first promoted neural watermark candidate. It is suitable for internal alpha testing and controlled validation, not yet for unsupported industrial deployment claims.
+
 ## Screenshots
 
 <table>
@@ -52,7 +64,7 @@ LuminCrypt is a desktop security toolkit for **Unicode hidden-character detectio
 |---|---:|---|
 | Node.js | 18+ | Electron and frontend build |
 | npm | 9+ | Package manager |
-| Python | 3.10+ recommended | Required for the image watermark backend |
+| Python | 3.10+ runtime, 3.12 recommended for ML | Required for the image watermark backend and ML training tools |
 
 ## Quick Start
 
@@ -80,6 +92,18 @@ Run TypeScript checks:
 npm run typecheck
 ```
 
+Run Python image-watermark tests:
+
+```bash
+python -m unittest discover -s blind_watermark/tests
+```
+
+Install ML training dependencies only when you need to train or export candidate neural models:
+
+```bash
+pip install -r blind_watermark/requirements-ml.txt
+```
+
 ## Build
 
 ```bash
@@ -119,10 +143,25 @@ LuminCrypt/
 |       `-- components/ # React components
 |-- blind_watermark/
 |   |-- rwm_engine.py   # Image blind watermark engine
-|   `-- bwm_helper.py   # CLI bridge used by Electron
-`-- resources/          # Static assets and packaged binaries
+|   |-- bwm_helper.py   # CLI bridge used by Electron
+|   |-- mlwm/           # MLWM neural watermark training, export, and inference modules
+|   `-- tests/          # Python unit tests
+|-- configs/mlwm/       # MLWM training, export, and evaluation configs
+|-- docs/mlwm/          # MLWM architecture, training, and traceability docs
+`-- resources/          # Static assets, packaged binaries, and promoted ONNX models
 ```
 
+## MLWM v1 Alpha
+
+MLWM v1 is a learning-assisted robust image watermark path for short text or ID payloads. It combines deterministic payload framing, CRC and Reed-Solomon recovery, classical synchronization ideas, lightweight PyTorch encoder/decoder models, and ONNX Runtime inference for desktop use.
+
+Useful references:
+
+- [MLWM Architecture](docs/mlwm/architecture.md)
+- [MLWM Training](docs/mlwm/training.md)
+- [MLWM Traceability](docs/mlwm/traceability.md)
+- [Benchmark Protocol](docs/mlwm/benchmark_protocol.md)
+
 ## Search Keywords
 
 Unicode steganography, Unicode watermark, invisible watermark, AI watermark detection, zero-width character detector, homoglyph detection, BiDi control detector, text watermarking, blind image watermark, robust image watermarking, digital watermarking, image forensics, content provenance, Electron security tool.

README.zh-CN.md

@@ -26,9 +26,21 @@ LuminCrypt 是一款桌面安全工具箱，面向 **Unicode 隐藏字符检测*
 - **Unicode 隐藏字符检测**：识别零宽字符、BiDi 控制符、同形字符、Unicode Tags、变体选择器和特殊空格。
 - **加密文本水印**：使用 AES-256-GCM 保护载荷，并通过不可见 Unicode 字符写入普通文本，支持鲁棒冗余。
 - **图片盲水印**：使用 Python 图片水印引擎，基于 Block-DCT、QIM 风格嵌入、Reed-Solomon 恢复和多尺度提取。
+- **学习型鲁棒图片水印**：提供实验性的 MLWM v1 alpha 引擎，支持短载荷图片水印、ONNX 推理、攻击模拟、评测 manifest，并可自动回退到 legacy 图片水印引擎。
 - **批量处理和报告导出**：支持批量扫描，并可导出 JSON、CSV 或 PDF 检测结果。
 - **本地桌面流程**：使用 Electron、React、TypeScript 构建，图片水印能力由 Python helper 提供。
 
+## 项目状态
+
+| 模块 | 状态 |
+|---|---|
+| Unicode 隐藏字符检测 | 可用 |
+| 加密文本水印 | 可用 |
+| Legacy 图片盲水印 | 可用 |
+| MLWM v1 神经网络图片水印 | Alpha，仅支持短载荷 |
+
+`mlwm-v1-alpha1` 是第一个已提升的神经网络图片水印候选模型，适合内部 alpha 测试和可控验证；暂不建议直接宣称为无需边界说明的产业级能力。
+
 ## 截图
 
 <table>
@@ -52,7 +64,7 @@ LuminCrypt 是一款桌面安全工具箱，面向 **Unicode 隐藏字符检测*
 |---|---:|---|
 | Node.js | 18+ | Electron 和前端构建 |
 | npm | 9+ | 包管理 |
-| Python | 推荐 3.10+ | 图片水印后端需要 |
+| Python | 运行时 3.10+，ML 训练推荐 3.12 | 图片水印后端和 ML 训练工具需要 |
 
 ## 快速开始
 
@@ -80,6 +92,18 @@ npm run dev
 npm run typecheck
 ```
 
+运行 Python 图片水印测试：
+
+```bash
+python -m unittest discover -s blind_watermark/tests
+```
+
+只有在训练或导出神经网络候选模型时，才需要安装 ML 训练依赖：
+
+```bash
+pip install -r blind_watermark/requirements-ml.txt
+```
+
 ## 构建打包
 
 ```bash
@@ -119,10 +143,25 @@ LuminCrypt/
 |       `-- components/ # React 组件
 |-- blind_watermark/
 |   |-- rwm_engine.py   # 图片盲水印引擎
-|   `-- bwm_helper.py   # Electron 调用的 CLI 桥接
-`-- resources/          # 静态资源和打包二进制
+|   |-- bwm_helper.py   # Electron 调用的 CLI 桥接
+|   |-- mlwm/           # MLWM 神经网络水印训练、导出和推理模块
+|   `-- tests/          # Python 单元测试
+|-- configs/mlwm/       # MLWM 训练、导出和评测配置
+|-- docs/mlwm/          # MLWM 架构、训练和可追溯文档
+`-- resources/          # 静态资源、打包二进制和已提升的 ONNX 模型
 ```
 
+## MLWM v1 Alpha
+
+MLWM v1 是面向短文本或 ID 载荷的学习型鲁棒图片水印链路。它结合了固定 payload 协议、CRC 与 Reed-Solomon 恢复、经典同步思路、轻量 PyTorch 编码器/解码器，以及桌面端 ONNX Runtime 推理。
+
+相关文档：
+
+- [MLWM 架构](docs/mlwm/architecture.md)
+- [MLWM 训练](docs/mlwm/training.md)
+- [MLWM 可追溯方案](docs/mlwm/traceability.md)
+- [Benchmark 协议](docs/mlwm/benchmark_protocol.md)
+
 ## 关键词
 
 Unicode 隐写、Unicode 水印、不可见水印、AI 水印检测、零宽字符检测、同形字符检测、BiDi 控制符检测、文本水印、图片盲水印、鲁棒图片水印、数字水印、图片取证、内容溯源、Electron 安全工具。

artifacts/promoted/mlwm-v1-alpha1/benchmark.json

@@ -0,0 +1,71 @@
+{
+  "createdAt": "2026-04-27T04:10:42+00:00",
+  "validationSamples": 1497,
+  "evaluations": {
+    "clean": {
+      "checkpoint": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/best.ckpt",
+      "config": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/train_config_resolved.yaml",
+      "valDir": "data/val_images",
+      "strength": "clean",
+      "repeats": 3,
+      "batches": 96,
+      "samples": 1497,
+      "payloadAcc": 1.0,
+      "exactMatch": 1.0,
+      "decodeSuccess": 1.0,
+      "createdAt": "2026-04-27T04:07:27+00:00"
+    },
+    "medium": {
+      "checkpoint": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/best.ckpt",
+      "config": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/train_config_resolved.yaml",
+      "valDir": "data/val_images",
+      "strength": "medium",
+      "repeats": 3,
+      "batches": 96,
+      "samples": 1497,
+      "payloadAcc": 0.9989802042643229,
+      "exactMatch": 0.9641927083333334,
+      "decodeSuccess": 0.9921875,
+      "createdAt": "2026-04-27T04:07:53+00:00"
+    },
+    "hard": {
+      "checkpoint": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/best.ckpt",
+      "config": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/train_config_resolved.yaml",
+      "valDir": "data/val_images",
+      "strength": "hard",
+      "repeats": 3,
+      "batches": 96,
+      "samples": 1497,
+      "payloadAcc": 0.9915457831488715,
+      "exactMatch": 0.824001736111111,
+      "decodeSuccess": 0.912326388888889,
+      "createdAt": "2026-04-27T04:08:22+00:00"
+    },
+    "fullMedium": {
+      "checkpoint": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/best.ckpt",
+      "config": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/eval_full_attack.yaml",
+      "valDir": "data/val_images",
+      "strength": "medium",
+      "repeats": 3,
+      "batches": 96,
+      "samples": 1497,
+      "payloadAcc": 0.9992650349934896,
+      "exactMatch": 0.9615885416666666,
+      "decodeSuccess": 0.9895833333333334,
+      "createdAt": "2026-04-27T04:10:09+00:00"
+    },
+    "fullHard": {
+      "checkpoint": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/best.ckpt",
+      "config": "artifacts/mlwm_v1/runs/20260426T185428+0000_6107b38/eval_full_attack.yaml",
+      "valDir": "data/val_images",
+      "strength": "hard",
+      "repeats": 3,
+      "batches": 96,
+      "samples": 1497,
+      "payloadAcc": 0.9978663126627604,
+      "exactMatch": 0.9231770833333334,
+      "decodeSuccess": 0.9772135416666666,
+      "createdAt": "2026-04-27T04:10:42+00:00"
+    }
+  }
+}