feat: MINICODE_COMMAND_ENCODING override for cp936/GBK command output

On Chinese Windows (cp936 OEM code page), legacy commands (dir, systeminfo,
batch scripts printing CJK) output GBK bytes; the UTF-8 default garbles them,
and a "try UTF-8 then cp936" fallback can't help (GBK bytes are frequently
valid UTF-8, decoding to wrong chars without ever falling back).

Add a MINICODE_COMMAND_ENCODING env override (default utf-8). Setting it to
cp936/gbk decodes such command output correctly. Verified end-to-end (GBK
output decodes to the right CJK chars under cp936). A bad encoding name falls
back to UTF-8 so execution never crashes. Documented in .env.example.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: QUSETIONS

.env.example

@@ -45,6 +45,14 @@ ANTHROPIC_MODEL=claude-sonnet-4-20250514
 MINI_CODE_LOG_LEVEL=WARNING
 # Options: DEBUG, INFO, WARNING, ERROR
 
+# --- Command output encoding ---
+# Encoding used to decode run_command output. Defaults to utf-8.
+# On Chinese Windows, set to cp936 (or gbk) so legacy commands that output in
+# the OEM code page (dir, systeminfo, batch scripts printing CJK) decode
+# correctly instead of mojibake. Pick whichever matches the majority of your
+# commands; a single value can't cover mixed utf-8 + cp936 output perfectly.
+# MINI_CODE_COMMAND_ENCODING=cp936
+
 # --- Workspace (for Docker) ---
 MINI_CODE_WORKSPACE=.
 

minicode/tools/run_command.py

@@ -18,6 +18,41 @@
 MAX_OUTPUT_CHARS = 200_000
 
 
+def _command_output_encoding() -> str:
+    """Encoding used to decode command output.
+
+    Override with the ``MINICODE_COMMAND_ENCODING`` env var — e.g. set it to
+    ``cp936`` (or ``gbk``) on Chinese Windows where legacy commands (``dir``,
+    ``systeminfo``, batch scripts printing CJK) output in the OEM code page and
+    would otherwise garble under the UTF-8 default. Defaults to ``utf-8``
+    (modern tools, and Python with ``PYTHONUTF8=1``).
+
+    A single global encoding can't be perfect for mixed output (a ``cp936``
+    override will garble UTF-8 tools, and vice-versa) — pick whichever matches
+    the majority of the commands you run.
+    """
+    return os.environ.get("MINICODE_COMMAND_ENCODING", "utf-8").strip() or "utf-8"
+
+
+def _decode_command_output(data: bytes | str | None) -> str:
+    """Decode subprocess output bytes using the configured command encoding.
+
+    Never raises: an unknown encoding name or a decode failure falls back to
+    UTF-8 with replacement chars so a bad ``MINICODE_COMMAND_ENCODING`` value
+    can't crash command execution.
+    """
+    if not data:
+        return ""
+    if isinstance(data, str):
+        return data
+    encoding = _command_output_encoding()
+    try:
+        return data.decode(encoding)
+    except (UnicodeDecodeError, LookupError):
+        return data.decode("utf-8", errors="replace")
+
+
+
 def _truncate_large_output(output: str, max_chars: int = MAX_OUTPUT_CHARS) -> str:
     """Truncate very large command output to prevent context bloat."""
     if len(output) <= max_chars:
@@ -338,7 +373,7 @@ def _run(input_data: dict, context) -> ToolResult:
                 if not timed_out:
                     process.wait()
 
-            output_str = output_bytes.decode("utf-8", errors="replace").strip()
+            output_str = _decode_command_output(bytes(output_bytes)).strip()
             output_str = output_str.replace("\r\n", "\n")
             output_str = _truncate_large_output(output_str)
 
@@ -359,19 +394,21 @@ def _run(input_data: dict, context) -> ToolResult:
             cwd=effective_cwd,
             env=os.environ.copy(),
             capture_output=True,
-            text=True,
-            encoding="utf-8",  # 显式指定 UTF-8
-            errors="replace",   # 无法解码时替换字符而非报错
             check=False,
             timeout=effective_timeout,
         )
-        output = "\n".join(part for part in [completed.stdout.strip(), completed.stderr.strip()] if part).strip()
+        output = "\n".join(
+            part for part in [
+                _decode_command_output(completed.stdout).strip(),
+                _decode_command_output(completed.stderr).strip(),
+            ] if part
+        ).strip()
         output = _truncate_large_output(output)
         return ToolResult(ok=completed.returncode == 0, output=output)
     except subprocess.TimeoutExpired as e:
         # Capture partial output from timeout
-        partial_stdout = (e.stdout or "").strip() if e.stdout else ""
-        partial_stderr = (e.stderr or "").strip() if e.stderr else ""
+        partial_stdout = _decode_command_output(e.stdout).strip()
+        partial_stderr = _decode_command_output(e.stderr).strip()
         partial = "\n".join(part for part in [partial_stdout, partial_stderr] if part)
         if partial:
             partial = f"\nPartial output:\n{_truncate_large_output(partial)}"

tests/test_run_command_encoding.py

@@ -0,0 +1,60 @@
+"""Tests for run_command output encoding (MINICODE_COMMAND_ENCODING).
+
+On Chinese Windows (cp936/GBK OEM code page), legacy commands output GBK bytes.
+The default UTF-8 decode garbles them, and a "try UTF-8 first" fallback can't
+help (GBK bytes are frequently valid UTF-8 → wrong chars, no fallback). The
+fix is an explicit override via MINICODE_COMMAND_ENCODING.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+
+def _reload(monkeypatch):
+    import minicode.tools.run_command as rc
+    return importlib.reload(rc)
+
+
+def test_default_encoding_is_utf8(monkeypatch) -> None:
+    monkeypatch.delenv("MINICODE_COMMAND_ENCODING", raising=False)
+    rc = _reload(monkeypatch)
+    assert rc._command_output_encoding() == "utf-8"
+    assert rc._decode_command_output("中文".encode("utf-8")) == "中文"
+
+
+def test_cp936_override_decodes_gbk(monkeypatch) -> None:
+    """The case UTF-8-first can't handle: GBK bytes decode correctly under cp936."""
+    monkeypatch.setenv("MINICODE_COMMAND_ENCODING", "cp936")
+    rc = _reload(monkeypatch)
+    assert rc._command_output_encoding() == "cp936"
+    assert rc._decode_command_output("目录文件".encode("gbk")) == "目录文件"
+
+
+def test_gbk_alias_works(monkeypatch) -> None:
+    monkeypatch.setenv("MINICODE_COMMAND_ENCODING", "gbk")
+    rc = _reload(monkeypatch)
+    assert rc._decode_command_output("目录".encode("gbk")) == "目录"
+
+
+def test_bad_encoding_name_falls_back_to_utf8(monkeypatch) -> None:
+    """An invalid MINICODE_COMMAND_ENCODING must not crash execution."""
+    monkeypatch.setenv("MINICODE_COMMAND_ENCODING", "not-a-real-codec")
+    rc = _reload(monkeypatch)
+    assert rc._decode_command_output("hello".encode()) == "hello"
+
+
+def test_decode_passthrough_and_empty(monkeypatch) -> None:
+    monkeypatch.delenv("MINICODE_COMMAND_ENCODING", raising=False)
+    rc = _reload(monkeypatch)
+    assert rc._decode_command_output(None) == ""
+    assert rc._decode_command_output(b"") == ""
+    assert rc._decode_command_output("already a str") == "already a str"
+
+
+def test_blank_override_falls_back_to_utf8(monkeypatch) -> None:
+    monkeypatch.setenv("MINICODE_COMMAND_ENCODING", "   ")
+    rc = _reload(monkeypatch)
+    assert rc._command_output_encoding() == "utf-8"