@furongjun1999/dsh-memory 0.6.1 → 0.7.0

package/md_cg/test_unify_scope.py

@@ -0,0 +1,182 @@
+# -*- coding: utf-8 -*-
+"""统一归一层作用域收窄守卫（2026-09-30 使用者裁定）
+
+口径：`semantic/unify.py::unify_query` **只对英文内容做翻译归一，中文内容
+原样不动**——query 按中文段/非中文段切开，中文段逐字保留、绝不送 segment。
+旧口径「含任一 ASCII 字母即整条归一」把中夹英 query 的中文部分逐字切开
+（「自我接纳」→「自 我 接 纳」），本件钉住收窄后的语义。
+
+**开关前提**：归一层缺省**关**（2026-09-30 使用者裁定，唯一开态 = 显式
+`MDCG_UNIFY_QUERY=1`）；本件第 1 节钉三态，其后各节一律**显式开**下跑。
+缺省态的三态与两侧一致性守卫见 `md_cg/test_unify_default_off.py`。
+
+两侧同源：期望值取自 `md_cg/semantic/unify_fixture.json`——Rust 侧
+`rust/src/atoms.rs::tests::unify_mixed_fixture_matches_python` 用 include_str!
+嵌入**同一份**文件；任一侧漂移即红（两侧逐位相同）。
+
+跑法：python -X utf8 -m md_cg.test_unify_scope
+"""
+import json
+import os
+import sys
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if HERE not in sys.path:
+    sys.path.insert(0, HERE)
+
+from md_cg.semantic.canonical import is_zh_char      # noqa: E402
+from md_cg.semantic.unify import unify_on, unify_query  # noqa: E402
+
+FIXTURE = os.path.join(HERE, "md_cg", "semantic", "unify_fixture.json")
+
+N = 0
+BAD = []
+
+
+# 生效条件：单参 cond 为真值判定、msg 为说明串；恒累加计数 N，cond 为假时把 msg 记入模块级 BAD（**不中断**）——收集式断言使「定点变异红了几项」可数（首条即停的 assert 风格数不出红项数）。
+def ok(cond, msg):
+    global N
+    N += 1
+    if not cond:
+        BAD.append(msg)
+
+
+# 生效条件：单参 text 为任意字符串，按 canonical.is_zh_char 切出其中的中文连续段，返回保序的段列表（无中文段时为空列表）；仅供本守卫做「中文段逐字保留」的结构判据。
+def zh_runs(text):
+    """文本里的中文连续段（判据同 unify_query：canonical.is_zh_char）。"""
+    out, buf = [], []
+    for ch in text:
+        if is_zh_char(ch):
+            buf.append(ch)
+        elif buf:
+            out.append("".join(buf))
+            buf = []
+    if buf:
+        out.append("".join(buf))
+    return out
+
+
+# ---- 1 · 开关三态（2026-09-30 使用者裁定：缺省由开翻为关；唯一开态 = 显式 "1"）----
+# 本件测的是**作用域收窄**语义，故从本节之后各节必须在**显式开**（=1）下跑：
+# 缺省已关（未设即关），若不显式开，下面 3~8 节全会退化成恒真（对实现零约束力）。
+# 缺省三态守卫另立一件：md_cg/test_unify_default_off.py（两件分工不同，勿互推）。
+ok(unify_on() is False,
+   "MDCG_UNIFY_QUERY 未设即关（缺省关，2026-09-30 翻）")
+os.environ["MDCG_UNIFY_QUERY"] = "0"
+try:
+    ok(unify_on() is False, "=0 显式关")
+    for t in ("I eat beef yesterday", "领养 LGBTQ 群体", "自我接纳",
+              "  beef 报告  ", "2024 报告"):
+        ok(unify_query(t) == t, "开关关：一律原样返回 %r" % t)
+finally:
+    os.environ.pop("MDCG_UNIFY_QUERY", None)
+os.environ["MDCG_UNIFY_QUERY"] = "1"
+ok(unify_on() is True, "=1 显式开（英文对照路要用）——本件余下各节的运行前提")
+
+# ---- 2 · 空/None/无 ASCII 字母：原样返回（未 strip 的入参）----
+ok(unify_query(None) is None, "None 原样")
+ok(unify_query("") == "", "空串原样")
+ok(unify_query("  自我接纳  ") == "  自我接纳  ",
+   "纯中文（无 ASCII 字母）原样返回入参本身（不 strip）")
+ok(unify_query("2024 报告") == "2024 报告", "纯中文+数字（无字母）原样")
+ok(unify_query("，。") == "，。", "纯标点（无字母）原样")
+
+# ---- 3 · 纯英文仍翻译（收窄不得关掉英文链路）----
+ok(unify_query("I eat beef yesterday") == "我 吃 牛肉 昨天",
+   "纯英文仍归一：%r" % unify_query("I eat beef yesterday"))
+ok(unify_query("wrote") == "写", "纯英文时态还原仍生效")
+
+# ---- 4 · 纯中文原样（旧口径会被逐字切开）----
+for t, why in (("自我接纳", "旧口径「自 我 接 纳」"),
+               ("慈善跑", "旧口径「慈 善 跑」"),
+               ("蜂群调度 依赖门禁", "旧口径逐字切开")):
+    ok(unify_query(t) == t, "纯中文原样（%s）：%r" % (why, t))
+
+# ---- 5 · fixture 逐位对拍（两侧同源：Rust 侧嵌同一份文件）----
+with open(FIXTURE, encoding="utf-8") as f:
+    FX = json.load(f)["cases"]
+ok(len(FX) >= 12, "fixture 用例数 >= 12：%d" % len(FX))
+for c in FX:
+    got = unify_query(c["in"])
+    ok(got == c["out"],
+       "fixture 逐位不符 [%s] in=%r got=%r want=%r"
+       % (c["name"], c["in"], got, c["out"]))
+
+# ---- 5b · 单侧钉：任务原型例（Python 侧形态）----
+# 这两例**不入共享 fixture**：非中文段是未登录的**大写**词（LGBTQ），两侧对
+# 「未命中词表的大写词」存在**既有**非对称（Python 保留原大小写 / Rust 经
+# normalize_en 一律 lower 化——用 rust 单测实测 `领养 lgbtq 群体` 取证，
+# 2026-09-30），故两侧钉不出同一期望值。此非本次收窄引入，也非本次范围；
+# 但它是端到端（Python 侧）实际生效的形态，故在此单侧钉死。
+for t in ("领养 LGBTQ 群体 支持 包容", "领养 机构 LGBTQ 群体 支持 包容"):
+    ok(unify_query(t) == t, "中夹英原型例：中文段逐字保留、英文片段原样：%r" % t)
+
+# ---- 6 · 结构判据（对**实现产物**断言）：混合 query 的中文段逐字保留 ----
+# 2026-09-30 清理批次（甲2）修假守卫：本节此前比的是 fixture 的**期望值**
+# （`run in c["out"]`——拿期望比期望），对实现零约束力：做「中文段也送
+# segment」变异时本节 0 项红。现改为直接调 `unify_query` 并对**产物**断言：
+# 中文段必须在产物里逐字出现，且其逐字切开形（`" ".join(run)`）不得出现。
+# 单字中文段（如「年」）的切开形与其本身同形，故切开判据只在 len(run) > 1
+# 时施加（否则是恒假的伪红）。
+for c in FX:
+    got = unify_query(c["in"])
+    for run in zh_runs(c["in"]):
+        ok(run in got,
+           "中文段未逐字保留（被改写）[%s] in=%r 段=%r got=%r"
+           % (c["name"], c["in"], run, got))
+        if len(run) > 1:
+            ok(" ".join(run) not in got,
+               "中文段被逐字切开（送了 segment）[%s] in=%r 段=%r got=%r"
+               % (c["name"], c["in"], run, got))
+# 原型例（任务口径原句）同样对产物断言：中文段逐字保留、英文片段不动
+for t in ("领养 LGBTQ 群体", "AI 记忆 系统", "自我接纳", "蜂群调度 依赖门禁"):
+    got = unify_query(t)
+    for run in zh_runs(t):
+        ok(run in got and " ".join(run) not in got,
+           "原型例中文段逐字保留 [%r] 段=%r got=%r" % (t, run, got))
+ok(zh_runs("领养 LGBTQ 群体") == ["领养", "群体"], "中文段抽取判据自检")
+
+# ---- 7 · 空白折叠为单空格（段内/段间）----
+ok(unify_query("  beef   报告  ") == "牛肉 报告", "前后空白+多空格折叠")
+ok(unify_query("beef\t报告") == "牛肉 报告", "制表符折叠为单空格")
+
+# ---- 8 · 异常降级为原样（不阻断检索主链路）----
+import md_cg.semantic.canonical as _cn   # noqa: E402
+_saved = _cn.query_atoms
+_cn.query_atoms = lambda _t: (_ for _ in ()).throw(RuntimeError("boom"))
+try:
+    src = "beef 报告"
+    ok(unify_query(src) == src, "链路抛异常 → 原样返回")
+finally:
+    _cn.query_atoms = _saved
+
+# ---- 9 · 中文判据边界（2026-09-30 清理批次乙2）：仅长度恰为 1 的串可为真 ----
+# 事实读数（本机实测，见清理批次回执）：留池条目 ⑥ 记「`is_zh_char("")` 返回
+# True」——**实测不成立**：`ZH_LO <= ch <= ZH_HI` 是链式比较，对空串即假，
+# 收紧前 `is_zh_char("")` 已返回 False。真实外溢面是**多字符串**——
+# 收紧前 `is_zh_char("中文")` 判真（首字符在区间即真）。两处消费点
+# （unify._runs / 本文件 zh_runs）均逐字符传入，故本收紧对存量行为零变更，
+# 只把判据面（长度恰为 1）钉死。
+ok(is_zh_char("") is False, "空串不是中文（判据面外）")
+ok(is_zh_char("中文") is False, "多字符串为假（首字符在区间亦然）")
+ok(is_zh_char("中a") is False, "多字符串为假（汉字+ASCII 混合）")
+ok(is_zh_char("中") is True, "单汉字为真")
+ok(is_zh_char("\u4e00") is True, "区间下界单汉字为真")
+ok(is_zh_char("\u9fff") is True, "区间上界单汉字为真")
+ok(is_zh_char("\u4dff") is False, "区间下界外单字符为假（U+4DFF）")
+ok(is_zh_char("\ua000") is False, "区间上界外单字符为假（U+A000）")
+ok(is_zh_char("a") is False, "单 ASCII 字母为假")
+# 两侧边界语义一致性：Rust `text::is_zh` 收 char，天然无空/多字符二态；
+# 本侧判据收紧后，「长度 != 1 一律 False」与「按 char 判区间」等价
+# （见 rust/src/text.rs::is_zh docstring 的边界约定段）。
+for ch in ("\u4e00", "\u9fff"):
+    ok(is_zh_char(ch) and len(ch) == 1, "单字符区间内 → 真（与 Rust is_zh 等价）%r" % ch)
+
+os.environ.pop("MDCG_UNIFY_QUERY", None)   # 归还进程环境（本件全程已显式开完）
+
+if BAD:
+    print("[test_unify_scope] FAILED %d/%d 断言：" % (len(BAD), N))
+    for b in BAD:
+        print("  - " + b)
+    raise SystemExit(1)
+print("[test_unify_scope] %d 断言全绿（fixture %d 例，两侧同源）" % (N, len(FX)))

package/md_cg/whitebox_kb/aeis_core/time_core.py

@@ -7,6 +7,14 @@
 衰减率 γ 按对象配置；任何在本模块之外出现的衰减核实现
 （exp(-t/τ)、×(1-factor)、EMA 保持率）都是 bug——
 由 tools/time_core_lint.py 按 E5 口径机械化审计。
+（P3 落地：该审计器此前全仓不存在，现落在 **`md_cg/test_time_core_lint.py`**
+——`python -X utf8 -m md_cg.test_time_core_lint` 审计全仓四形态，指数核的
+**调用式 `exp(-…` 与点调用 `.exp(…)/.exp()`（Rust 写法）两种形态都入面**；
+另带登记表 + 等价性断言：`links.py` 同族半衰期（G2），以及 **Rust 读侧
+`rust/src/freshness.rs` 的指数核**（G11——从 Rust 源码抽常量与核表达式逐 Δt
+点与 `cred_factor` 对拍，因 Rust 无法被 Python 调用）。自带 `--mutate` 定点
+变异自证，其中 P4-M9 就是「把该 Rust 登记摘掉必须转红」那条。
+**不新开顶层 `tools/` 目录**：那会改 `WORKSPACE_INDEX.md` 的结构面。）
 规范依据：docs/概念钉死批_GPT四点评审_v0.1.md 钉死 3。
 """
 import math

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furongjun1999/dsh-memory",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "灵枢（Lingshu·líng shū）DeepSeek Harness 插件：完整大脑——长期记忆/知识飞轮/自我认知/递归反思接入 DSH，对话自动沉淀进 md_cg 认知图（md 文档）",
   "type": "module",
   "main": "lib/index.js",
@@ -20,6 +20,7 @@
     "lib",
     "src",
     "md_cg",
+    "utf8_boot.py",
     "data/policy.json",
     "skills",
     "README.md",
@@ -85,7 +86,7 @@
     "build": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "npm run build && node --import tsx --test \"test/*.test.ts\"",
     "prepare": "node -e \"const fs=require('fs');const tsc='node_modules/typescript/bin/tsc';fs.existsSync(tsc)?(fs.rmSync('lib',{recursive:true,force:true}),require('child_process').execFileSync(process.execPath,[tsc,'-p','tsconfig.json'],{stdio:'inherit'})):console.log('[prepare] 跳过构建：typescript 未安装（NODE_ENV=production 或 --omit=dev 会省略 devDependencies）——需要构建请用 npm install --include=dev')\"",
-    "gate": "python scripts/check_unreachable.py && python scripts/check_publish_artifact.py && python scripts/cogmap_sync.py check && python scripts/link_check.py && python scripts/workspace_index.py --check && python scripts/verify_discipline.py --allow-missing && python scripts/gate_rust_crate_test.py && python scripts/gate_rust_parity.py",
+    "gate": "python scripts/check_unreachable.py && python scripts/check_publish_artifact.py && python scripts/check_publish_smoke.py && python scripts/cogmap_sync.py check && python scripts/link_check.py && python scripts/workspace_index.py --check && python scripts/verify_discipline.py --allow-missing && python scripts/gate_rust_crate_test.py && python scripts/gate_rust_parity.py",
     "prepublishOnly": "npm run build && npm test && npm run gate"
   },
   "repository": {

package/skills/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "lingshu-skills",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "灵枢（AEIS）自我认知技能包——白箱条件化知识（Agent Skills 兼容导出）。本质是灵枢了解自身的工具：每个技能描述灵枢在什么条件下能做什么、怎么执行、克制什么（KCCS 四要素），由条件路由图精确路由，由灵枢 MCP 工具执行验证（物理基底）。",
   "author": {
     "name": "灵枢（AEIS）· CommonTrustProtocol"

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)