@furongjun1999/dsh-memory 0.6.1 → 0.7.1

package/utf8_boot.py

@@ -0,0 +1,237 @@
+# -*- coding: utf-8 -*-
+"""utf8_boot.py · 入口自保证 UTF-8（进程自保证，不依赖使用者 profile 的环境变量）。
+
+为什么放在**仓库根**、而不是 `md_cg/` 里
+------------------------------------------------------------------------
+本模块被 hive / md_cg / scripts 三处的**进程入口**共用。放进 `md_cg/` 会让
+`import md_cg` 拉起整个认知图包（`md_cg/__init__.py` 会 `import .mdcg`）——为一次
+UTF-8 检查付出「重包导入的启动成本 + hive/scripts 入口被绑上 md_cg 依赖方向」的
+双重代价。放仓库根 = 零第三方、零 md_cg 依赖、入口一行 `sys.path` 插入即可用。
+
+它解决什么（修前事实，本机 2026-09-29 实测）
+------------------------------------------------------------------------
+* `locale.getlocale()` = `('Chinese (Simplified)_China', '936')`，
+  `locale.getpreferredencoding(False)` = `cp936`；Python 裸 `open()` 的缺省编码
+  与 stdio 的控制台代码页都跟着 locale 走。
+* 清空 `PYTHONUTF8` / `PYTHONIOENCODING` 后实测：裸 `open()` 读 UTF-8 中文文件抛
+  `UnicodeDecodeError`；`sys.stdout.write("中文")` 静默产出 GBK 字节（`\\xd6\\xd0\\xce\\xc4`）；
+  裸 `open(p, "w")` 写中文落 GBK 字节——**静默坏**，比抛异常更难查。
+* 本机之所以没炸，是因为**环境里**有 `PYTHONUTF8=1` + `PYTHONIOENCODING=utf-8`，
+  且部分入口自己钉（`scripts/run_tests.py` 给子进程覆盖、`scripts/linux_verify.sh`
+  export、`src/lib/mdcg_client.ts` 设 PYTHONUTF8）。
+  ⇒ 正确性挂在「环境变量 + 每个入口记得设」上：换台没设的机器，或新入口漏设，
+  即走 GBK。本模块把该保证**下沉到进程自身**。
+
+三条路（`ensure_utf8` 的分支）
+------------------------------------------------------------------------
+0. **调用方不是进程入口（被 import）→ 只置 env 即返回**——绝不重启、绝不退出、绝不打
+   日志。见下「被 import 时不得重启（F6）」。
+1. `sys.flags.utf8_mode` 为真 → 立即返回（不重启、不打日志）；
+2. 为假 → **默认重启自身**（`-X utf8`）；重启后子进程 `utf8_mode` 已开 ⇒ 结构上
+   不可能二次重启（幂等，见守卫的「只重启一次」判据）；
+3. 显式退出通道：env `LINGSHU_UTF8_NO_REEXEC` 为真 → **fail-fast** 非 0 退出并打印
+   可执行指引（不能接受子进程的场景：嵌入式宿主、CI 调试、进程树审计）。
+
+无论走哪条路（含第 0 路），都会把 `PYTHONUTF8=1` 与 `PYTHONIOENCODING=utf-8` 置入
+`os.environ`，供本进程随后派生的子进程继承（执行器/编排器派生子进程时的第二道保险）。
+
+被 import 时不得重启（F6，2026-09-29 复核实测）
+------------------------------------------------------------------------
+本助手在七个入口里都是**模块级**调用，而其中数个入口**同时是被 import 的库**
+（`hive/serve_start.py` 被 `hive/hive_mcp/mcp_server.py` 导入、`hive/exec.py` 被
+`hive/orch.py` 导入）。若「被 import」也整进程重启：调用方正在处理的输入会被吞掉。
+复核员构造态实测（未加本判据前）：单会话解释器启动 2 次、第 3 条请求被吞、
+**无错误帧、rc=0**——静默坏，比抛异常更难查。故重启/fail-fast 只在
+「调用方模块 == `__main__`」时发生；被 import 时只置 env。
+
+fail-fast 指引必须**可照抄**（F2，2026-09-29 复核实测）
+------------------------------------------------------------------------
+指引此前一律印 `python -X utf8 <入口 __file__>`；而两个 MCP 入口的真实接入形态是
+`python -m md_cg.mcp_server` / `python -m hive.hive_mcp.mcp_server`（mcp.json 直连），
+照抄文件形态会 `ImportError: attempted relative import with no known parent package`
+（实测 rc=1）。故 `_guidance` 复用与 `reexec_argv()` **同一**判别（`__main__.__spec__`
+有 name 与 parent ⇒ `-m` 形态），印 `python -X utf8 -m <模块名>`。
+
+**禁用 `os.exec*` 系列**：Windows 上进程替换与标准句柄继承的语义不可靠，而 MCP 是
+**字节组帧**的 stdio 协议——重启必须显式传递 `stdin`/`stdout`/`stderr` 三个标准流，
+丢了组帧就是灾难。故本模块只用 `subprocess.run`（实测：父进程退出后子进程持有的
+管道句柄仍完好）。
+
+与设计裁决的一处偏离（已在回报中声明，理由是端到端组帧这条真判据）
+------------------------------------------------------------------------
+重启 argv 除 `-X utf8` 外**保留 `-m` 模块语义**：`python -m md_cg.mcp_server` 若按
+`sys.argv` 原样重启，会退化成「直跑文件」（`sys.path[0]` 变包目录、`__package__`
+丢失），`md_cg/mcp_server.py:3833` 的 `from .datapath import ...` 立即 ImportError
+——本机实测 `python -X utf8 md_cg/mcp_server.py` → rc=1、
+`ImportError: attempted relative import with no known parent package`。而
+`python -m md_cg.mcp_server` 正是 ZCode/DSH 的 mcp.json 接入形态（该文件头注第 14 行）。
+故 `-m` 形态按 `[python, -X, utf8, -m, <模块名>, *sys.argv[1:]]` 重建，其余形态原样
+`*sys.argv`；源码无法重放的解释器形态（`-c` / `-`，从命令行/stdin 读源码）**不重启**，
+只告警——那里重启会把源码丢掉（`python -X utf8 -c` 会转而从 stdin 读代码）。
+"""
+from __future__ import annotations
+
+import locale
+import os
+import subprocess
+import sys
+
+__all__ = ["ensure_utf8", "launch_hint", "reexec_argv", "NO_REEXEC_ENV",
+           "EXIT_UTF8_REQUIRED"]
+
+#: 显式退出通道：置真值即不自动重启，改为 fail-fast 非 0 退出
+NO_REEXEC_ENV = "LINGSHU_UTF8_NO_REEXEC"
+#: fail-fast 退出码（非 0；指引文案里点名「怎么改」）
+EXIT_UTF8_REQUIRED = 2
+#: 真值判定集（去空白 + 转小写后比对；未设 / 空串 / 其它值一律视为否）
+_TRUTHY = frozenset(("1", "true", "yes", "on", "y", "t"))
+#: 源码无法重放的解释器形态（`-c` 从命令行读、`-` 从 stdin 读）：重启会丢源码
+_UNREBUILDABLE_ARGV0 = frozenset(("-c", "-"))
+#: 结构化退出码：解释器形态无法重放时「不重启也不假装已保证」的退出码（守卫熔断未命中）
+_EXIT_UNREBUILDABLE = 3
+
+
+# 生效条件：env name 存在且其值去空白转小写后落在 _TRUTHY 内返回 True；未设、空串或其它值返回 False。
+def _truthy(name: str) -> bool:
+    """env 真值判定（唯一口径：去空白 + 小写 + 白名单比对）。"""
+    return (os.environ.get(name) or "").strip().lower() in _TRUTHY
+
+
+# 生效条件：无入参；把 PYTHONUTF8=1 与 PYTHONIOENCODING=utf-8 写入 os.environ（覆盖旧值，幂等），随后派生的子进程按此继承，无返回值。
+def _set_child_env() -> None:
+    """置子进程继承面（第四条）：PYTHONUTF8=1 + PYTHONIOENCODING=utf-8。"""
+    os.environ["PYTHONUTF8"] = "1"
+    os.environ["PYTHONIOENCODING"] = "utf-8"
+
+
+# 生效条件：无入参；`__main__.__spec__` 同时有 name 与 parent（`python -m pkg.mod` 形态）时返回该模块名，否则返回 None（直跑文件时 `__spec__` 为 None）。
+def _m_module_name() -> str | None:
+    """本进程是否以 `python -m <模块>` 启动；是则返回模块名，否则 None。
+
+    **单点判别**：`reexec_argv()`（重启 argv）与 `launch_hint()`（fail-fast 指引文案）
+    共用本函数——两处各写一份必然漂移，而指引印错的代价是使用者照抄后撞墙（F2）。
+    """
+    main = sys.modules.get("__main__")
+    spec = getattr(main, "__spec__", None)
+    name = getattr(spec, "name", None)
+    if name and getattr(spec, "parent", None):
+        return name
+    return None
+
+
+# 生效条件：entry 为入口标识或 None；本进程经 `python -m` 启动时返回 `-m <模块名>`，其余形态返回 entry 本身（None 时回落占位 `<entry>`）。
+def launch_hint(entry: str | None) -> str:
+    """「照抄即可跑」的启动形态（`-X utf8` 之后的那一段）。
+
+    -m 形态 → `-m <模块名>`（模块名可被 python 重新 import，等同使用者的原始命令）；
+    其余形态 → `entry`（通常 `__file__`，绝对路径）。
+    """
+    name = _m_module_name()
+    if name:
+        return "-m %s" % name
+    return entry or "<entry>"
+
+
+# 生效条件：无入参；调用 ensure_utf8 的模块 `f_globals` 与 `sys.modules['__main__'].__dict__` 同一时返回 True；取不到调用帧时返回 False（保守：不重启）。
+def _caller_is_process_entry() -> bool:
+    """调用 `ensure_utf8` 的模块是否**就是本进程入口**（`__main__`）。
+
+    F6 判据本体：只在「本模块即进程入口」时重启/fail-fast——被 import 时重启会吞掉
+    调用方正在处理的输入（复核实测：无错误帧、rc=0，静默）。用 `f_globals` 与
+    `__main__.__dict__` 的**同一性**比对：`python -m pkg.mod` 下入口模块的 `__name__`
+    也是 `"__main__"`，故 -m 与直跑文件两种入口形态得到同一判定。
+    """
+    try:
+        frame = sys._getframe(1)                  # ensure_utf8 自身的帧
+        globs = frame.f_back.f_globals            # 调用 ensure_utf8 的那一帧
+    except (ValueError, AttributeError):
+        return False                              # 取不到调用帧：不重启（静默重启的代价更大）
+    return globs is getattr(sys.modules.get("__main__"), "__dict__", None)
+
+
+# 生效条件：无入参；sys.argv[0] 为 -c/- （源码不可重放）时返回 None；本进程经 python -m 启动（_m_module_name 非空）时返回 [exe, -X, utf8, -m, 模块名, *sys.argv[1:]]；其余形态返回 [exe, -X, utf8, *sys.argv]。
+def reexec_argv() -> list | None:
+    """重启自身的 argv（保留 -m 模块语义）；源码不可重放时返回 None。"""
+    if sys.argv and sys.argv[0] in _UNREBUILDABLE_ARGV0:
+        return None
+    name = _m_module_name()
+    if name:
+        return [sys.executable, "-X", "utf8", "-m", name, *sys.argv[1:]]
+    return [sys.executable, "-X", "utf8", *sys.argv]
+
+
+# 生效条件：entry 为入口标识（通常 __file__）或 None，cause 为原因短句；返回「可执行指引」多行文本——启动形态经 launch_hint 复用 -m 判别（-m 入口印 `python -X utf8 -m <模块名>`，其余印 `<entry>`），并含 PYTHONUTF8=1 写法、当前 locale 缺省编码、以及取消 NO_REEXEC_ENV 的出路；全为 ASCII 与中文，无任何凭据。
+def _guidance(entry: str, cause: str) -> str:
+    """fail-fast / 无法重启时的可执行指引（照抄即可跑）。"""
+    try:
+        pref = locale.getpreferredencoding(False)
+    except Exception:                                     # noqa: BLE001
+        pref = "?"
+    hint = launch_hint(entry)                             # F2：与 reexec_argv 同一判别
+    return (
+        "utf8_boot: 入口需要**进程级 UTF-8**，但当前解释器未启用"
+        "（sys.flags.utf8_mode=0，locale 缺省编码=%s）。\n"
+        "  入口：%s\n"
+        "  原因：%s\n"
+        "请改用下列任一方式启动（可照抄）：\n"
+        "    python -X utf8 %s\n"
+        "    PYTHONUTF8=1 python %s        # Windows cmd: set PYTHONUTF8=1 && python ...\n"
+        "或取消环境变量 %s（让入口自动以 -X utf8 重启自身）。\n"
+        % (pref, entry, cause, hint, hint, NO_REEXEC_ENV)
+    )
+
+
+# 生效条件：text 给出后优先以 UTF-8 字节写 sys.stderr.buffer（不受控制台代码页影响），buffer 不可用时回落文本层写入；两级都失败则静默返回，无返回值。
+def _emit(text: str) -> None:
+    """把指引写到 stderr——**显式 UTF-8 字节**，不随控制台代码页漂移。"""
+    try:
+        sys.stderr.buffer.write(text.encode("utf-8"))
+        sys.stderr.buffer.flush()
+        return
+    except Exception:                                     # noqa: BLE001
+        pass
+    try:
+        sys.stderr.write(text)
+        sys.stderr.flush()
+    except Exception:                                     # noqa: BLE001
+        pass
+
+
+# 生效条件：entry 为入口标识或 None；先把 PYTHONUTF8/PYTHONIOENCODING 置入 env；调用方非进程入口（本助手被 import）时立即返回（不重启/不退出/不打日志）；sys.flags.utf8_mode 为真时立即返回（不重启、不打日志）；为假且 LINGSHU_UTF8_NO_REEXEC 为真时向 stderr 打印可执行指引并以 EXIT_UTF8_REQUIRED 退出；为假且该 env 非真时以 reexec_argv() 重启自身（显式传递 stdin/stdout/stderr 三流）并以子进程退出码退出；重启 argv 为 None（-c/- 形态）或子进程无法启动（OSError）时打印指引并以 _EXIT_UNREBUILDABLE / EXIT_UTF8_REQUIRED 退出；无返回值（不返回即在重启或退出的路上）。
+def ensure_utf8(entry: str | None = None) -> None:
+    """入口自保证 UTF-8 —— 唯一调用点，**必须在任何文件/库 I/O 之前**。
+
+    生效条件：`utf8_mode` 已开时置 env 后立即返回（不重启、不打日志）；未开且
+    **本模块不是进程入口**（本助手被 import）时置 env 后立即返回——不重启、不退出、
+    不打日志（F6：被 import 时重启会静默吞掉调用方的输入）；未开且
+    `LINGSHU_UTF8_NO_REEXEC` 为真时向 stderr 打印可执行指引并以
+    ``EXIT_UTF8_REQUIRED``(2) 退出；未开且该 env 非真时以 ``reexec_argv()`` 重启
+    自身（``-X utf8``，显式传递 stdin/stdout/stderr）并以子进程退出码退出——重启后
+    子进程 ``utf8_mode`` 已开，故不会二次重启；``-c``/``-`` 形态（源码不可重放）
+    不重启，打印指引后以 ``3`` 退出。
+
+    不适用条件：本进程已在 UTF-8 模式下运行、或本助手是被 import 的（非进程入口）时，
+    只置子进程继承面、不做任何重启——即「已在 utf8 模式」「被 import」两者都是幂等
+    且安静的（子进程不会再重启）。**入口若以非 `__main__` 形态被 import，则不获得
+    重启保证**（这是有意的：静默重启的代价高于少一次保证）。
+    """
+    _set_child_env()
+    if sys.flags.utf8_mode:
+        return                                            # ②：已开 → 不重启、不打日志
+    if not _caller_is_process_entry():
+        return                                            # F6：被 import → 只置 env，静默
+    target = entry or (sys.argv[0] if sys.argv else "<entry>")
+    if _truthy(NO_REEXEC_ENV):
+        _emit(_guidance(target, "%s 已置真：禁止自动重启" % NO_REEXEC_ENV))
+        raise SystemExit(EXIT_UTF8_REQUIRED)              # ③：显式退出通道
+    argv = reexec_argv()
+    if argv is None:
+        _emit(_guidance(target, "解释器以 -c/- 读源码，argv 无法重放（不重启）"))
+        raise SystemExit(_EXIT_UNREBUILDABLE)
+    try:
+        proc = subprocess.run(argv, stdin=sys.stdin, stdout=sys.stdout,
+                              stderr=sys.stderr)          # 三流显式传递：字节组帧
+    except OSError as exc:
+        _emit(_guidance(target, "重启自身失败：%r" % (exc,)))
+        raise SystemExit(EXIT_UTF8_REQUIRED)
+    raise SystemExit(proc.returncode)