@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/game-art/client/.env.example

@@ -0,0 +1,19 @@
+# CẤU HÌNH MÁY KHÁCH — chép thành `client/.env` rồi sửa.
+# `.env` đã .gitignore, ĐỪNG commit (có token). File .env.example này KHÔNG được chứa token thật.
+# Biến môi trường THẬT luôn thắng file này.
+
+# Danh sách node trong LAN, ngăn bằng dấu phẩy. Mỗi mục có thể mang token riêng:
+#   http://192.168.0.131:8765/mcp|token-rieng-cua-node
+GAMEART_REMOTE_NODES=http://192.168.0.131:8765/mcp,http://192.168.0.132:8765/mcp
+
+# Token dùng chung — PHẢI khớp token của node (xem server/.env của node). >= 16 ký tự.
+GAMEART_REMOTE_TOKEN=doi-thanh-dung-token-cua-node
+
+# Mọi node bận thì chờ tối đa bao lâu rồi báo lại (giây, mặc định 900 = 15 phút).
+#GAMEART_REMOTE_WAIT=900
+
+# Một node duy nhất (thay cho _NODES, tương thích bản cũ).
+#GAMEART_REMOTE_URL=http://192.168.0.131:8765/mcp
+
+# Trỏ file .env ở chỗ khác.
+#GAMEART_ENV_FILE=

package/plugins/phaser-casual-game-factory/skills/game-art/client/bgremove.py

@@ -0,0 +1,127 @@
+"""Xóa nền bằng BEN2 (PramaLLC/BEN2) qua thư viện `ben2` + PyTorch.
+
+Đây là công đoạn TÁCH NỀN "xịn" thay cho chroma-key: segmentation ngữ nghĩa
+(matting), không phụ thuộc màu nền, không để lại viền xanh (green fringe), và
+cứu được cả ca chủ thể TRÙNG màu key mà chroma-key bó tay. BEN2 (~94.6M tham số,
+license MIT) cho mép matting mượt hơn hẳn chroma-key.
+
+Xem hướng dẫn gốc: https://huggingface.co/PramaLLC/BEN2
+
+Thiết kế:
+  - Tự chứa: trọng số model tải về `models/` (root skill) (đặt qua HF_HOME) nên skill
+    mang đi đâu cũng chạy, không phụ thuộc cache HuggingFace toàn máy.
+  - Nạp LƯỜI: `from_pretrained()` chỉ gọi ở lần remove đầu tiên và cache lại —
+    import module này KHÔNG kéo theo torch, nhờ vậy test_imglib.py vẫn chạy offline.
+  - Rớt mềm: nếu thiếu `torch`/`ben2`, `available()` trả False; caller tự quay về
+    chroma-key (imglib.chroma_key) — KHÔNG lỗi.
+
+ENV:
+  BEN2_MODEL    repo/tên model để `from_pretrained` (mặc định "PramaLLC/BEN2").
+  BEN2_DEVICE   "cuda" | "cpu" | "auto" (mặc định "auto": CUDA nếu có, không thì CPU).
+  BEN2_REFINE   refine_foreground — BẬT mặc định (bớt rỉ màu nền ở mép). "0" để tắt.
+  HF_HOME       nơi chứa/nạp trọng số model (mặc định = models/ (root) cạnh file này).
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from PIL import Image
+
+# Trỏ cache HuggingFace vào thư mục skill TRƯỚC khi ben2/huggingface_hub được import
+# lần đầu, để trọng số tải về (và nạp lại) nằm gọn trong skill thay vì ~/.cache
+# toàn máy. Chỉ set nếu người dùng chưa tự khai báo HF_HOME.
+# Trọng số nằm ở models/ NGANG HÀNG client/ và server/ (dùng chung, không nằm trong
+# client/ để bản client mang đi không dính ~1GB). parent = client/, parent.parent = gốc skill.
+_DEFAULT_MODEL_DIR = Path(__file__).resolve().parent.parent / "models"
+os.environ.setdefault("HF_HOME", str(_DEFAULT_MODEL_DIR))
+os.environ.setdefault("HF_HUB_CACHE", str(_DEFAULT_MODEL_DIR / "hub"))
+
+_MODEL_NAME = os.environ.get("BEN2_MODEL", "PramaLLC/BEN2")
+# refine_foreground BẬT mặc định. Nó ước lượng lại MÀU tiền cảnh ở dải mép mềm, tức đúng chỗ
+# màu nền key rỉ vào chủ thể. Đo thật trên ảnh sinh có nền xanh: pixel mép mềm bị xanh trội tụt
+# từ 14.435 (58.0% dải mép) xuống 5.989 (25.5%) — mà alpha/coverage gần như không đổi, nên đây
+# thuần là bớt rỉ màu, không phải đổi hình. Giá: ~+0.4s/ảnh trên RTX 3060 (0.45s -> 0.88s).
+# Tắt bằng BEN2_REFINE=0 nếu cần chạy nhanh trên máy yếu.
+_REFINE = os.environ.get("BEN2_REFINE", "1") not in ("0", "", "false", "False")
+
+_model = None            # cache model BEN2 (nạp lười, chỉ 1 lần)
+_import_ok: bool | None = None   # None = chưa thử import
+
+
+def _try_import():
+    """Import torch + ben2 một lần, nhớ kết quả. True nếu dùng được."""
+    global _import_ok
+    if _import_ok is None:
+        try:
+            import numpy as _np
+            import torch
+            import ben2  # noqa: F401
+            # KIỂM CẢ CẦU NỐI numpy<->torch, không chỉ `import torch`. Với numpy 2.x, torch
+            # 2.4 vẫn import ĐƯỢC (chỉ cảnh báo) rồi mới chết ở `from_numpy` GIỮA lúc chạy —
+            # đo thật: available() trả True, sau đó BEN2 nổ "Numpy is not available" ở tận
+            # trong pipeline. Kiểm ở đây biến nó về đúng hợp đồng: rớt mềm về chroma-key.
+            torch.from_numpy(_np.zeros((1, 1), dtype=_np.uint8))
+            _import_ok = True
+        except Exception:
+            _import_ok = False
+    return _import_ok
+
+
+def available() -> bool:
+    """torch + ben2 có import được không (điều kiện cần để chạy BEN2)."""
+    return _try_import()
+
+
+def _pick_device():
+    import torch
+
+    want = os.environ.get("BEN2_DEVICE", "auto").lower()
+    if want == "cpu":
+        return torch.device("cpu")
+    if want == "cuda":
+        return torch.device("cuda")
+    # auto: CUDA nếu có, không thì CPU — giống ví dụ chính thức của BEN2.
+    return torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+
+def _get_model():
+    global _model
+    if _model is None:
+        import torch  # noqa: F401
+        from ben2 import BEN_Base
+
+        Path(os.environ["HF_HOME"]).mkdir(parents=True, exist_ok=True)
+        device = _pick_device()
+        model = BEN_Base.from_pretrained(_MODEL_NAME)
+        model.to(device).eval()
+        _model = model
+    return _model
+
+
+def warmup() -> bool:
+    """Tải trọng số + nạp model sẵn (kéo ~1GB ở lần đầu). True nếu sẵn sàng. KHÔNG ném lỗi.
+
+    Node gọi lúc khởi động để tải model trước, khỏi để request đầu gánh cả cú download.
+    """
+    if not available():
+        return False
+    try:
+        _get_model()
+        return True
+    except Exception:
+        return False
+
+
+def remove_background(img: Image.Image) -> Image.Image:
+    """Trả ảnh RGBA với alpha do BEN2 dự đoán (subject đục, nền trong suốt).
+
+    Ném lỗi nếu torch/ben2 không có — gọi `available()` trước để rớt về chroma-key.
+    Alpha ở đây là matte MỀM (0..255) nên mép đã anti-alias sẵn, hạ nguồn
+    (despeckle/bbox/fit_into của imglib) dùng thẳng được.
+    """
+    model = _get_model()
+    out = model.inference(img.convert("RGB"), refine_foreground=_REFINE)
+    if out.mode != "RGBA":
+        out = out.convert("RGBA")
+    return out

package/plugins/phaser-casual-game-factory/skills/game-art/client/codex_extract.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Móc ảnh sinh bởi imagegen ra khỏi session rollout JSONL của Codex CLI.
+
+Copy từ skill gpt-image-2 (agentspace.so, MIT) — nhúng vào game-art/server để skill
+tự chứa. Chạy được bằng cả `python` lẫn `python3` (codex_gen.sh tự chọn bản chạy được).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import pathlib
+import re
+import sys
+
+IMAGE_MAGIC_PREFIXES: dict[str, str] = {
+    "iVBORw0KGgo": "png",
+    "/9j/": "jpg",
+    "UklGR": "webp",
+}
+
+MIN_BLOB_LENGTH = 200
+BASE64_BLOB_PATTERN = re.compile(r'"([A-Za-z0-9+/=]{' + str(MIN_BLOB_LENGTH) + r',})"')
+
+
+def find_best_image_blob(session_paths: list[pathlib.Path]) -> tuple[str, str] | None:
+    """Trả (base64, ext) của blob ảnh LỚN NHẤT tìm thấy trong các file session."""
+    best: tuple[str, str, int] | None = None
+    for session_path in session_paths:
+        try:
+            text = session_path.read_text(errors="replace")
+        except OSError:
+            continue
+        for line in text.splitlines():
+            try:
+                obj = json.loads(line)
+            except ValueError:
+                continue
+            flat = json.dumps(obj)
+            for match in BASE64_BLOB_PATTERN.finditer(flat):
+                blob = match.group(1)
+                for magic, ext in IMAGE_MAGIC_PREFIXES.items():
+                    if blob.startswith(magic):
+                        if best is None or len(blob) > best[2]:
+                            best = (blob, ext, len(blob))
+                        break
+    if best is None:
+        return None
+    return best[0], best[1]
+
+
+ALLOWED_OUTPUT_EXTENSIONS: frozenset[str] = frozenset({".png", ".jpg", ".jpeg", ".webp"})
+
+FORBIDDEN_OUTPUT_PREFIXES: tuple[str, ...] = (
+    "/bin", "/boot", "/dev", "/etc", "/lib", "/proc",
+    "/sbin", "/sys", "/usr", "/System", "/Library",
+    "/var/root", "/var/log", "/var/db",
+)
+
+
+def validate_output_path(raw_out: str) -> pathlib.Path:
+    """Chuẩn hoá path ra; từ chối đuôi không phải ảnh và thư mục hệ thống."""
+    candidate = pathlib.Path(raw_out)
+    ext = candidate.suffix.lower()
+    if ext not in ALLOWED_OUTPUT_EXTENSIONS:
+        raise ValueError(
+            f"output path must end in one of {sorted(ALLOWED_OUTPUT_EXTENSIONS)}; got {ext!r}"
+        )
+
+    resolved = candidate.expanduser().resolve()
+    resolved_str = str(resolved)
+    alt_str = (
+        resolved_str[len("/private"):] if resolved_str.startswith("/private/") else None
+    )
+
+    def _is_under_forbidden(path_str: str) -> bool:
+        return any(
+            path_str == f or path_str.startswith(f + "/")
+            for f in FORBIDDEN_OUTPUT_PREFIXES
+        )
+
+    if _is_under_forbidden(resolved_str) or (alt_str and _is_under_forbidden(alt_str)):
+        raise ValueError(f"refusing to write under a system directory: {resolved}")
+
+    return resolved
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 3:
+        print(
+            "usage: codex_extract.py <out_path> <sessions_list_file>",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        out_path = validate_output_path(argv[1])
+    except ValueError as err:
+        print(f"invalid output path: {err}", file=sys.stderr)
+        return 2
+
+    sessions_list_path = pathlib.Path(argv[2])
+    session_paths = [
+        pathlib.Path(line)
+        for line in sessions_list_path.read_text().splitlines()
+        if line.strip()
+    ]
+
+    result = find_best_image_blob(session_paths)
+    if result is None:
+        print("IMAGE_NOT_FOUND_IN_SESSION", file=sys.stderr)
+        return 1
+
+    blob, _ext = result
+    image_bytes = base64.b64decode(blob)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_bytes(image_bytes)
+    print(out_path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/plugins/phaser-casual-game-factory/skills/game-art/client/codex_gen.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# codex_gen.sh — sinh 1 ảnh qua Codex CLI (tool imagegen / GPT Image 2), dùng session
+# ChatGPT user đã `codex login`. Chuyển thể từ skill gpt-image-2 (agentspace.so, MIT),
+# nhúng vào game-art để skill TỰ CHỨA (không phụ thuộc skill khác có cài hay không).
+#
+# Khác biệt so với bản gốc (lý do tồn tại của file này):
+#   - Chọn python THẬT SỰ CHẠY ĐƯỢC: Windows có stub `python3` của Microsoft Store nằm
+#     trong PATH nhưng chạy là chết -> `command -v python3` một mình cho kết quả dối.
+#     Thử chạy `-c pass` thật, rớt về `python` nếu python3 hỏng.
+#
+# Cơ chế — HAI đời codex, thử theo thứ tự:
+#   1. codex-cli ~0.145+ (đo thật trên máy này): tool image_gen tích hợp GHI FILE ảnh
+#      xuống $CODEX_HOME/generated_images/<uuid>/*.png. Snapshot-diff thư mục đó,
+#      lấy file ảnh mới LỚN NHẤT.
+#   2. codex-cli ~0.111 (đời cũ): imagegen KHÔNG ghi file — ảnh nằm base64 trong session
+#      rollout jsonl dưới ~/.codex/sessions/. Diff sessions rồi nhờ codex_extract.py móc ra.
+# `--enable image_generation` giữ nguyên (đời mới coi flag lạ vẫn chạy, đời cũ cần nó);
+# `--ephemeral` thì CẤM (đường 2 mất session = mất ảnh).
+#
+# Usage:
+#   codex_gen.sh --prompt "<text>" --out <path.png> [--ref <image>]... [--timeout-sec N]
+#
+# LƯU Ý SONG SONG: cơ chế snapshot-diff sessions KHÔNG an toàn khi chạy 2 lượt codex
+# cùng lúc (lượt nọ nhặt nhầm session của lượt kia). Chạy các lượt codex TUẦN TỰ.
+#
+# Exit codes:
+#   0 success (path in trên stdout)
+#   2 sai args
+#   3 thiếu CLI (codex / python)
+#   4 ảnh --ref không tồn tại
+#   5 codex exec hỏng (login? mạng? model?)
+#   6 không thấy session file mới
+#   7 không móc được ảnh từ session (feature chưa bật, hết quota, hoặc bị từ chối)
+
+set -euo pipefail
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+PROMPT=""
+OUT=""
+REF_IMAGES=()
+TIMEOUT_SEC=300
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --prompt)      PROMPT="$2"; shift 2 ;;
+    --out)         OUT="$2"; shift 2 ;;
+    --ref)         REF_IMAGES+=("$2"); shift 2 ;;
+    --timeout-sec) TIMEOUT_SEC="$2"; shift 2 ;;
+    -h|--help)     sed -n '2,30p' "$0"; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ -z "$PROMPT" ]] && { echo "Missing --prompt" >&2; exit 2; }
+[[ -z "$OUT" ]]    && { echo "Missing --out" >&2; exit 2; }
+
+# CHẾ ĐỘ MƯỢN MÁY: có GAMEART_REMOTE_NODES (hoặc _URL) thì đẩy cả lượt sinh sang node (nơi có
+# `codex login`) rồi ghi ảnh về đúng --out của máy này. Dòng lệnh trong SKILL.md không đổi
+# một chữ nào — chỉ khác ở env. Máy chủ tự xếp hàng TUẦN TỰ cho codex, thứ mà nhiều máy
+# khách gọi song song chắc chắn phá vỡ (cơ chế snapshot-diff session ở dưới).
+if [[ -n "${GAMEART_REMOTE_NODES:-}" || -n "${GAMEART_REMOTE_URL:-}" ]]; then
+  PY_BIN="$(command -v python3 || command -v python || true)"
+  [[ -z "$PY_BIN" ]] && { echo "remote mode can luong python" >&2; exit 3; }
+  REF_ARGS=()
+  for r in ${REF_IMAGES[@]+"${REF_IMAGES[@]}"}; do REF_ARGS+=("--ref" "$r"); done
+  exec "$PY_BIN" "$SCRIPT_DIR/remote_codex.py"     --prompt "$PROMPT" --out "$OUT" --timeout-sec "$TIMEOUT_SEC"     ${REF_ARGS[@]+"${REF_ARGS[@]}"}
+fi
+
+command -v codex >/dev/null 2>&1 || {
+  echo "codex CLI not found. Install Codex CLI and run 'codex login' first." >&2
+  exit 3
+}
+
+# python3 có thể là stub MS Store (command -v thấy nhưng chạy là hỏng) -> thử chạy thật.
+PY=""
+for cand in python3 python; do
+  if "$cand" -c "pass" >/dev/null 2>&1; then PY="$cand"; break; fi
+done
+[[ -z "$PY" ]] && { echo "no working python found (tried python3, python)" >&2; exit 3; }
+
+CODEX_ROOT="${CODEX_HOME:-$HOME/.codex}"
+SESSIONS_ROOT="$CODEX_ROOT/sessions"
+IMAGES_ROOT="$CODEX_ROOT/generated_images"
+mkdir -p "$SESSIONS_ROOT" "$IMAGES_ROOT"
+
+before="$(mktemp)"; after="$(mktemp)"
+before_imgs="$(mktemp)"; after_imgs="$(mktemp)"
+stdout_log="$(mktemp)"; stderr_log="$(mktemp)"
+new_sessions_file="$(mktemp)"
+trap 'rm -f "$before" "$after" "$before_imgs" "$after_imgs" "$stdout_log" "$stderr_log" "$new_sessions_file"' EXIT
+
+find "$SESSIONS_ROOT" -type f -name 'rollout-*.jsonl' -print 2>/dev/null | sort > "$before" || true
+find "$IMAGES_ROOT" -type f \( -name '*.png' -o -name '*.jpg' -o -name '*.jpeg' -o -name '*.webp' \) -print 2>/dev/null | sort > "$before_imgs" || true
+
+# Cố ý KHÔNG --ephemeral: cần session rollout nằm trên đĩa để móc ảnh ra.
+args=(exec --skip-git-repo-check --sandbox read-only --color never --enable image_generation)
+if [[ ${#REF_IMAGES[@]} -gt 0 ]]; then
+  for img in "${REF_IMAGES[@]}"; do
+    [[ -f "$img" ]] || { echo "Reference image not found: $img" >&2; exit 4; }
+    args+=(-i "$img")
+  done
+fi
+
+instruction="Use the imagegen tool to generate the image for the following request."
+if [[ ${#REF_IMAGES[@]} -gt 0 ]]; then
+  instruction+=" Use the attached image(s) as visual reference / input for image-to-image. The FIRST attached image is the FIRST image referenced in the request."
+fi
+instruction+=$'\nRequirements: generate the image directly, return only the image, no explanation.\n\nRequest:\n'"$PROMPT"
+
+# `-i` là flag variadic (<FILE>...) — prompt truyền positional sẽ bị nuốt làm tên file.
+# Đưa prompt qua stdin (codex exec đọc stdin khi không có positional).
+
+TO=""
+if   command -v timeout  >/dev/null 2>&1; then TO="timeout"
+elif command -v gtimeout >/dev/null 2>&1; then TO="gtimeout"
+fi
+
+set +e
+if [[ -n "$TO" ]]; then
+  printf '%s' "$instruction" | "$TO" "$TIMEOUT_SEC" codex "${args[@]}" >"$stdout_log" 2>"$stderr_log"
+else
+  printf '%s' "$instruction" | codex "${args[@]}" >"$stdout_log" 2>"$stderr_log"
+fi
+rc=$?
+set -e
+
+if [[ $rc -ne 0 ]]; then
+  echo "codex exec failed (exit=$rc). stderr tail:" >&2
+  tail -n 40 "$stderr_log" >&2 || true
+  exit 5
+fi
+
+# --- Đường 1 (codex mới): file ảnh mới dưới $CODEX_HOME/generated_images ---
+find "$IMAGES_ROOT" -type f \( -name '*.png' -o -name '*.jpg' -o -name '*.jpeg' -o -name '*.webp' \) -print 2>/dev/null | sort > "$after_imgs" || true
+new_img="$(comm -13 "$before_imgs" "$after_imgs" | while IFS= read -r f; do
+  [[ -f "$f" ]] && printf '%s\t%s\n' "$(wc -c < "$f")" "$f"
+done | sort -rn | head -n 1 | cut -f2-)"
+
+if [[ -n "$new_img" ]]; then
+  # Copy nguyên bytes kể cả khi đuôi khác OUT (jpg -> .png): PIL phía sau
+  # (process_raws/_open_rgba) mở theo NỘI DUNG, không theo đuôi file.
+  mkdir -p "$(dirname "$OUT")"
+  cp "$new_img" "$OUT"
+  echo "$OUT"
+  exit 0
+fi
+
+# --- Đường 2 (codex cũ): móc base64 từ session rollout mới ---
+find "$SESSIONS_ROOT" -type f -name 'rollout-*.jsonl' -print 2>/dev/null | sort > "$after" || true
+
+# Gom MỌI session file mới — một lượt codex exec có thể đẻ nhiều rollout (imagegen chạy
+# trong sub-turn) nên phải quét hết, không nhặt bừa cái cuối.
+comm -13 "$before" "$after" > "$new_sessions_file" || true
+
+if [[ ! -s "$new_sessions_file" ]]; then
+  echo "No new session rollout file under $SESSIONS_ROOT" >&2
+  tail -n 40 "$stderr_log" >&2 || true
+  exit 6
+fi
+
+set +e
+"$PY" "$SCRIPT_DIR/codex_extract.py" "$OUT" "$new_sessions_file"
+py_rc=$?
+set -e
+
+if [[ $py_rc -ne 0 ]]; then
+  echo "Image payload not found in any new session file" >&2
+  echo "(imagegen likely did not run; stderr tail:)" >&2
+  tail -n 30 "$stderr_log" >&2 || true
+  exit 7
+fi

package/plugins/phaser-casual-game-factory/skills/game-art/client/envfile.py

@@ -0,0 +1,121 @@
+"""Nạp file `.env` — KHÔNG phụ thuộc gói ngoài.
+
+Vì sao tự viết thay vì dùng `python-dotenv`: máy khách chỉ cần Pillow + numpy + mcp +
+curl_cffi + httpx, và thêm một dependency chỉ để đọc mấy dòng `KEY=VALUE` là bắt mọi máy
+cài thêm một thứ có thể thiếu đúng lúc cần nhất. File này ~40 dòng, không có gì để hỏng.
+
+QUY TẮC: biến môi trường THẬT luôn THẮNG file .env (dùng `setdefault`). Nhờ vậy đăng ký MCP
+bằng `claude mcp add ... -e KEY=VALUE` vẫn đè được file, và một máy có thể tạm đổi node bằng
+env của phiên làm việc mà không phải sửa file.
+
+Thứ tự tìm (dừng ở file ĐẦU TIÊN thấy):
+    1. $GAMEART_ENV_FILE            — chỉ định thẳng, ưu tiên cao nhất
+    2. <thư mục skill>/.env         — cạnh SKILL.md, chỗ tự nhiên nhất để đặt
+    3. <thư mục skill>/server/.env
+
+PHẢI gọi TRƯỚC khi import các module đọc env ở cấp module (gemini_image_mcp, bgremove,
+upscale, remote_proto đều đọc `os.environ` ngay lúc import) — gọi sau thì file coi như
+không tồn tại, và triệu chứng là "đã tạo .env mà vẫn không ăn".
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# envfile.py nằm ở client/. `_SKILL` = gốc skill (cha của client/ và server/).
+_SELF_DIR = Path(__file__).resolve().parent
+_SKILL = _SELF_DIR.parent
+
+loaded_from: str | None = None      # để tool báo cáo lại: đã nạp từ file nào
+
+
+def candidates(base: Path | None = None) -> list[Path]:
+    """Thứ tự tìm .env. `base` = thư mục CỦA ENTRY đang chạy (client/ hay server/).
+
+    Client và node có `.env` RIÊNG trong thư mục mỗi bên (token/cấu hình khác nhau), nên
+    entry truyền thư mục của nó vào để đọc đúng file. Thứ tự:
+      1. $GAMEART_ENV_FILE   — chỉ định thẳng, ưu tiên tuyệt đối
+      2. <base>/.env         — .env cùng thư mục entry (client/.env hoặc server/.env)
+      3. <gốc skill>/.env    — .env dùng chung, phòng khi đặt ở gốc
+    """
+    base = base or _SELF_DIR
+    out = []
+    explicit = os.environ.get("GAMEART_ENV_FILE", "").strip()
+    if explicit:
+        out.append(Path(explicit))
+    out.append(base / ".env")
+    if base.resolve() != _SKILL.resolve():
+        out.append(_SKILL / ".env")
+    return out
+
+
+def parse(text: str) -> dict[str, str]:
+    """Đọc nội dung .env. Nhận `KEY=VALUE`, `export KEY=VALUE`, nháy đơn/kép, `#` chú thích."""
+    out: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        key, sep, val = line.partition("=")
+        if not sep:
+            continue
+        key = key.strip()
+        if not key:
+            continue
+        val = val.strip()
+        if len(val) >= 2 and val[0] == val[-1] and val[0] in ("'", '"'):
+            val = val[1:-1]          # có nháy -> giữ NGUYÊN VĂN, kể cả dấu #
+        else:
+            # Cắt chú thích cuối dòng, nhưng chỉ khi có KHOẢNG TRẮNG trước `#`. Không có luật
+            # này thì `GAMEART_REMOTE_WAIT=900  # 15 phút` biến thành số "900  # 15 phút" và
+            # int() nổ ngay lúc import; còn cắt vô điều kiện thì token chứa `#` bị xén cụt.
+            for i, ch in enumerate(val):
+                if ch == "#" and i > 0 and val[i - 1].isspace():
+                    val = val[:i]
+                    break
+            val = val.strip()
+        out[key] = val
+    return out
+
+
+def load(path: str | os.PathLike | None = None, override: bool = False,
+         base: Path | None = None) -> dict[str, str]:
+    """Nạp .env vào os.environ. Trả các cặp ĐÃ ĐỌC ĐƯỢC (kể cả cặp bị env thật đè).
+
+    `base`: thư mục của entry đang gọi (client/ hay server/) — để đọc đúng `.env` của bên đó.
+    `path`: ép đọc một file cụ thể (bỏ qua tìm kiếm).
+    Không thấy file -> trả {} và im lặng: chạy không có .env là hoàn toàn bình thường.
+    """
+    global loaded_from
+    paths = [Path(path)] if path else candidates(base)
+    for p in paths:
+        try:
+            if not p.is_file():
+                continue
+            data = parse(p.read_text(encoding="utf-8"))
+        except Exception:
+            continue        # .env hỏng KHÔNG được làm chết MCP server
+        for k, v in data.items():
+            if override:
+                os.environ[k] = v
+            else:
+                os.environ.setdefault(k, v)
+        loaded_from = str(p)
+        return data
+    return {}
+
+
+def info() -> dict:
+    """Báo cáo cho tool chẩn đoán — chỉ TÊN biến, KHÔNG bao giờ trả giá trị.
+
+    Token nằm trong .env; đổ nguyên giá trị vào output của tool là rò rỉ nó vào transcript,
+    log, và bất cứ đâu output đi tới.
+    """
+    return {
+        "loaded_from": loaded_from,
+        "searched": [str(p) for p in candidates()],
+        "keys": sorted(k for k in os.environ
+                       if k.startswith(("GAMEART_", "GEMINI_", "BEN2_", "ESRGAN_"))),
+    }