LangSC 2.3.0__tar.gz → 2.5.0__tar.gz

{langsc-2.3.0 → langsc-2.5.0}/LangSC/__version__.py

@@ -2,6 +2,6 @@
 # Keep __version__ a plain string literal: setup.cfg reads it statically via
 # `version = attr: LangSC.__version__.__version__`, so it must stay AST-parseable
 # (no computed expression) to avoid importing the package at build time.
-__version__ = "2.3.0"
+__version__ = "2.5.0"
 
 VERSION = tuple(int(x) for x in __version__.split("."))

{langsc-2.3.0 → langsc-2.5.0}/LangSC/_utils.py

@@ -2,9 +2,66 @@
 
 import os
 import re
+import struct
+import platform
 import chardet
 
 
+def _win_short_path(path):
+    """返回 Windows 8.3 短路径(纯 ASCII);路径不存在或该卷禁用 8.3 名称时返回 None。"""
+    import ctypes
+    GetShortPathNameW = ctypes.windll.kernel32.GetShortPathNameW
+    GetShortPathNameW.restype = ctypes.c_uint
+    buf = ctypes.create_unicode_buffer(32768)
+    n = GetShortPathNameW(str(path), buf, len(buf))
+    if n == 0 or n >= len(buf):
+        return None
+    short = buf.value
+    try:
+        short.encode("ascii")   # 8.3 被禁用时会原样返回长路径(仍含非 ASCII)→ 视为失败
+    except UnicodeEncodeError:
+        return None
+    return short
+
+
+def native_path(path):
+    """把文件系统路径编码为原生 C 库 fopen() 所需的字节(跨平台)。
+
+    - POSIX(Linux/macOS):UTF-8 字节。POSIX fopen 直接按字节打开,文件系统即
+      UTF-8,故中文路径可用。
+    - Windows:按当前 ANSI 代码页(中文系统通常是 GBK)编码;若路径含该代码页
+      无法表示的字符,则退化为其 8.3 短路径(纯 ASCII)。两者都能被引擎编译期
+      绑定的 ANSI fopen 打开。
+
+    解决:BCC/GPF 原先在 Linux/macOS 也发 GBK 路径 → 打不开中文目录;JSS 原先在
+    Windows 发 UTF-8 路径 → 打不开中文目录。统一由本函数按平台给出正确字节。
+    """
+    if platform.system() != "Windows":
+        return os.fsencode(path)          # Linux/macOS:UTF-8(含 surrogateescape)
+    try:
+        return path.encode("mbcs")        # Windows:当前 ANSI 代码页(GBK),与现状一致
+    except UnicodeEncodeError:
+        short = _win_short_path(path)
+        if short is not None:
+            return short.encode("mbcs")
+        raise ValueError(
+            "路径含当前 ANSI 代码页无法表示的字符,且无法获取 8.3 短路径"
+            "(该卷可能禁用了 8.3 名称):%r。请改用 ASCII 路径,或在该卷启用 8.3 名称。"
+            % path
+        )
+
+
+def format_native_load_error(lib_name, err):
+    """构造原生库(.dll/.so/.dylib)加载失败时的可诊断错误信息。"""
+    bits = 8 * struct.calcsize("P")
+    return (
+        "LangSC 无法加载原生库 {lib}(系统={sys} 架构={mach} Python={bits}位):{err}\n"
+        "请确认:1) 安装的 LangSC 与当前系统/架构匹配(建议从 PyPI 重新安装以获取对应平台的包);"
+        "2) Windows 需已安装 VC++ 运行库;3) Linux/macOS 需确保该库的依赖项齐全。"
+    ).format(lib=lib_name, sys=platform.system(), mach=platform.machine(),
+             bits=bits, err=err)
+
+
 def detect_file_encoding(file_path, sample_size=1024*10):
     """Detect file encoding by BOM or chardet."""
     with open(file_path, 'rb') as f:
@@ -26,20 +83,30 @@ def detect_file_encoding(file_path, sample_size=1024*10):
 
     result = chardet.detect(raw_sample)
     encoding = result['encoding']
-
-    if encoding is None:
-        return 'ascii'
-    elif encoding.lower() == 'gb2312':
+    confidence = result.get('confidence') or 0
+
+    # 检测不出(空/过短/二进制)时回退 utf-8 而非 ascii:ascii 对任何非 ASCII 字节
+    # 都会在后续 open 时抛行级 decode 错;utf-8 是 ascii 的超集,更安全的默认。
+    if encoding is None or confidence < 0.3:
+        return 'utf-8'
+    enc = encoding.lower()
+    # gb2312/gb18030 统一按 gbk 家族处理(python 的 gbk/gb18030 均可解码)
+    if enc == 'gb2312':
         return 'gbk'
-    else:
-        return encoding
+    return encoding
 
 
 def is_file_format(file_path):
-    """Determine file type: 'Table', 'FSA', or 'BCC'."""
+    """Determine file type: 'Table', 'FSA', or 'BCC'.
+
+    用探测到的编码 + errors='ignore' 打开:避免 GBK 的 Table/FSA 文件在 UTF-8
+    locale 系统上因默认编码解码失败而被裸 except 吞掉、误判成 'BCC'。判别前缀
+    ('FSA '/'Table ') 均为 ASCII,errors='ignore' 不影响匹配。
+    """
     ret = "BCC"
     try:
-        with open(file_path, "rt") as f:
+        encoding = detect_file_encoding(file_path)
+        with open(file_path, "rt", encoding=encoding, errors="ignore") as f:
             no = 0
             for line in f:
                 line = line.strip()
@@ -52,7 +119,7 @@ def is_file_format(file_path):
                 if re.search('^Table ', line):
                     ret = "Table"
                     break
-    except:
+    except Exception:
         return ret
     return ret
 
@@ -189,18 +256,29 @@ def write_idx_log(path, file_path, idx_log):
 
 
 def is_file_list(filelistname):
-    """Check if a file contains a list of file paths."""
-    with open(filelistname, "r") as f:
+    """Check if a file contains a list of file paths.
+
+    用探测到的编码打开(GBK 清单在 UTF-8 locale 下不再解码失败),空文件判为非清单。
+    """
+    try:
+        encoding = detect_file_encoding(filelistname)
         is_file = True
         is_possible = True
-        for line in f:
-            if not os.path.isfile(line.strip()):
-                is_file = False
-            if line.find("\\") == -1 and line.find("/") == -1:
-                is_possible = False
-    if is_file or is_possible:
-        return True
-    return False
+        has_line = False
+        with open(filelistname, "r", encoding=encoding, errors="ignore") as f:
+            for line in f:
+                if line.strip() == "":
+                    continue
+                has_line = True
+                if not os.path.isfile(line.strip()):
+                    is_file = False
+                if line.find("\\") == -1 and line.find("/") == -1:
+                    is_possible = False
+    except OSError:
+        return False
+    if not has_line:
+        return False
+    return bool(is_file or is_possible)
 
 
 def is_raw(file_path):
@@ -259,10 +337,18 @@ def check_words(all_words):
 
 
 def process_file(file_path, file_tmp, cmd, gpf=None):
-    """Process a raw file into corpus format."""
+    """Process a raw file into corpus format.
+
+    输出必须用 GBK 写:BCC 引擎按原始字节(二进制)读取语料并以 GBK 存储/匹配
+    (F2019.cpp 中有 GBK 字节哨兵,查询在 BCC_RunBCC 里由 UTF-8 转 GBK 后匹配)。
+    Windows 的默认文本编码恰为 GBK(cp936),故原先隐式可用;但 Linux/macOS 默认
+    UTF-8 会导致中文语料按 UTF-8 存入、与 GBK 查询无法匹配。显式 GBK 让各平台一致。
+    errors='replace':个别超出 GBK 的字符以占位符代替,避免整次索引崩溃(引擎本就
+    只支持 GBK)。
+    """
     encoding = detect_file_encoding(file_path)
-    with open(file_path, "r", encoding=encoding) as f_in:
-        with open(file_tmp, "w") as f_out:
+    with open(file_path, "r", encoding=encoding, errors="replace") as f_in:
+        with open(file_tmp, "w", encoding="gbk", errors="replace") as f_out:
             print("Doc {}".format(file_path), file=f_out)
             for line in f_in:
                 line = line.strip()

{langsc-2.3.0 → langsc-2.5.0}/LangSC/bcc.py

@@ -10,7 +10,7 @@ from ctypes import *
 from ._utils import (
     get_idx_info, get_file_info, is_same, get_bcc_files,
     write_idx_log, is_file_list, is_raw, process_file,
-    file2corpus, corpus,
+    file2corpus, corpus, format_native_load_error, native_path,
 )
 
 OS = platform.system()
@@ -45,20 +45,26 @@ class BCC:
         cfg_file_bcc = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'BCCconfig.txt')
         cfg_file_parser = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'Parser.lua')
 
-        self.library_bcc = cdll.LoadLibrary(dll_file_bcc)
+        try:
+            self.library_bcc = cdll.LoadLibrary(dll_file_bcc)
+        except OSError as e:
+            raise OSError(format_native_load_error(dll_name_bcc, e)) from e
 
         self.ParserBCC = cfg_file_parser
         self.ConfigBCC = cfg_file_bcc
         self.dataPath = dataPath
         self.RetBuff = create_string_buffer(''.encode(), self.buf_max_size)
 
+        self.dll_close = None
         if OS == "Windows":
             self.dll_close = win32api.FreeLibrary
-        elif OS == "Linux":
+        else:
+            # Linux / macOS：通过 libc 的 dlclose 释放句柄（原先缺 macOS 分支）
             try:
                 stdlib = CDLL("")
             except OSError:
-                stdlib = CDLL("libc.so")
+                # libc.so 在部分发行版是链接脚本不可 dlopen，用 libc.so.6
+                stdlib = CDLL("libc.so.6" if OS == "Linux" else "libc.dylib")
             self.dll_close = stdlib.dlclose
             self.dll_close.argtypes = [c_void_p]
 
@@ -75,6 +81,22 @@ class BCC:
     def __del__(self):
         return
 
+    def _enc_path(self, p):
+        """把路径编码为原生 C API 所需字节:POSIX→UTF-8,Windows→ANSI/短路径。
+
+        统一走 _utils.native_path,解决中文路径在 Linux/macOS 打不开的问题。
+        """
+        return native_path(p)
+
+    def _check_trunc(self, str_len):
+        """定长缓冲区被写满 → 结果很可能被截断,报错而非返回残缺数据(须在 string_at 前调用)。"""
+        if str_len >= self.buf_max_size:
+            raise RuntimeError(
+                "BCC 结果超出缓冲区上限(%d 字节)被截断。请缩小检索范围或分页(Number/PageNo)。"
+                % self.buf_max_size
+            )
+        return str_len
+
     def _init_bcc_data(self, path):
         """Initialize BCC data by scanning and indexing BCC corpus files.
 
@@ -132,14 +154,18 @@ class BCC:
         if IsBCCInit == 0:
             self.library_bcc.BCC_Init.argtypes = [c_char_p]
             self.library_bcc.BCC_Init.restype = c_int
-            IsBCCInit = self.library_bcc.BCC_Init(self.dataPath.encode('gbk', errors='strict'))
+            IsBCCInit = self.library_bcc.BCC_Init(self._enc_path(self.dataPath))
         lock.release()
 
         if IsBCCInit == 0 and query.find("Lua") == -1:
-            return json.loads("{}")
+            # 返回字符串 "{}"（而非 dict），保证 Run/_normalize 始终拿到字符串、
+            # 产出统一信封（records:[]）；否则空结果会让 Run 返回 dict，调用方
+            # json.loads(Ret) 直接 TypeError。
+            return "{}"
         self.library_bcc.BCC_RunBCC.argtypes = [c_char_p, c_char_p, c_char_p, c_char_p]
         self.library_bcc.BCC_RunBCC.restype = c_int
-        str_len = self.library_bcc.BCC_RunBCC(self.ParserBCC.encode(), self.dataPath.encode('gbk', errors='strict'), query.encode(), self.RetBuff)
+        str_len = self.library_bcc.BCC_RunBCC(self.ParserBCC.encode(), self._enc_path(self.dataPath), query.encode(), self.RetBuff)
+        self._check_trunc(str_len)
         ret = string_at(self.RetBuff, str_len)
         return ret.decode()
 
@@ -364,7 +390,7 @@ class BCC:
         filelist_ex = os.path.join(self.dataPath, "indexlistEx.tmp")
         gpf = self._get_gpf() if Param[0] == "Segment" else None
         file2corpus(filelist, filelist_ex, self.dataPath, Param[0], gpf=gpf)
-        ret = self.library_bcc.BCC_IndexBCC(self.ConfigBCC.encode(), filelist_ex.encode('gbk', errors='strict'), self.dataPath.encode('gbk', errors='strict'))
+        ret = self.library_bcc.BCC_IndexBCC(self.ConfigBCC.encode(), self._enc_path(filelist_ex), self._enc_path(self.dataPath))
         os.remove(filelist_ex)
         if filelist.find("indexlist.tmp") != -1:
             os.remove(filelist)
@@ -421,7 +447,7 @@ class BCC:
         elif Command == "Freq":
             Operation = 'Freq({},{},{})'.format(Number, Target, ContextNum)
         elif Command == "Count":
-            Operation = "Count()".format()
+            Operation = "Count()"
         else:
             Operation = "{}".format(Command)
         if not re.search(r"[\{\}]", Query):

{langsc-2.3.0 → langsc-2.5.0}/LangSC/gpf.py

@@ -12,21 +12,58 @@ from wordcloud import WordCloud
 
 from ._utils import (
     get_idx_info, get_file_info, is_same, get_gpf_files,
-    write_idx_log,
+    write_idx_log, format_native_load_error, native_path,
 )
 
 OS = platform.system()
 if OS == "Windows":
     import win32api
 
+# 注意:这些是模块级(进程级)初始化标志,与底层 DLL 的进程级全局状态对应。
+# 一个进程内 CRF/POS/GPF 引擎只初始化一次、共用同一套模型数据。因此在同一进程
+# 中创建多个 GPF 实例并期望各自加载不同的分词/词性模型是无效的——首个初始化的
+# 模型会被后续实例沿用。需要不同模型时,请在不同进程中分别运行。
 IsCRFInit = 0
 IsPOSInit = 0
 IsGPFInit = 0
 lock = threading.Lock()
 
 
+def _find_cjk_font():
+    """跨平台查找一个可渲染中文的字体文件路径;找不到返回 None。
+
+    用于词云(WordCloud 需显式 font_path 才能渲染中文)。原代码硬编码
+    c:/windows/fonts/simyou.ttf,在 Linux/macOS 上必然报错。
+    """
+    candidates = [
+        # Windows
+        "C:/Windows/Fonts/msyh.ttc", "C:/Windows/Fonts/simhei.ttf",
+        "C:/Windows/Fonts/simyou.ttf", "C:/Windows/Fonts/simsun.ttc",
+        # macOS
+        "/System/Library/Fonts/PingFang.ttc",
+        "/System/Library/Fonts/STHeiti Medium.ttc",
+        "/Library/Fonts/Arial Unicode.ttf",
+        # Linux(文泉驿 / Noto CJK,覆盖常见发行版路径)
+        "/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc",
+        "/usr/share/fonts/wenquanyi/wqy-zenhei/wqy-zenhei.ttc",
+        "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
+        "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+        "/usr/share/fonts/google-noto-cjk/NotoSansCJKsc-Regular.otf",
+    ]
+    for p in candidates:
+        if os.path.isfile(p):
+            return p
+    return None
+
+
 class GPF:
-    def __init__(self, dataPath="./data"):
+    def __init__(self, dataPath="./data", parser_url="https://cnlp.blcu.edu.cn/ice/api"):
+        # 远程句法分析网关（Tree/Chunk/Dep）：BSTService 公开端点
+        #   {parser_url}/v1/public/parser/{stree|chunk|dep}
+        # parser_url 为 API 基址（公网经 /ice/api 代理到 ice 应用；注意裸 /api
+        # 边缘禁 POST）。免登录、只读；替代已失效的 cit.blcu.edu.cn 直连。
+        # 可通过构造参数覆盖。
+        self.ParserURL = parser_url.rstrip("/")
         dataPath = dataPath.replace("\\", "/")
         if len(dataPath) > 1 and dataPath.endswith("/"):
             dataPath = dataPath[:-1]
@@ -59,7 +96,10 @@ class GPF:
         cfg_file_CRFModel = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'Segment.dat')
         cfg_file_POSData = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'idxPOS.dat')
 
-        self.library_gpf = cdll.LoadLibrary(dll_file_gpf)
+        try:
+            self.library_gpf = cdll.LoadLibrary(dll_file_gpf)
+        except OSError as e:
+            raise OSError(format_native_load_error(dll_name_gpf, e)) from e
 
         self.ParserBCC = cfg_file_parser
         self.ConfigGPF = cfg_file_gpf
@@ -100,7 +140,8 @@ class GPF:
             try:
                 stdlib = CDLL("")
             except OSError:
-                stdlib = CDLL("libc.so" if OS == "Linux" else "libc.dylib")
+                # libc.so 在部分发行版是链接脚本不可 dlopen，用 libc.so.6
+                stdlib = CDLL("libc.so.6" if OS == "Linux" else "libc.dylib")
             self.dll_close = stdlib.dlclose
             self.dll_close.argtypes = [c_void_p]
         # 绘图默认字体：Graphviz 渲染中文需宿主机存在对应 CJK 字体。
@@ -111,6 +152,26 @@ class GPF:
     def __del__(self):
         return
 
+    def _enc_path(self, p):
+        """把路径编码为原生 C API 所需字节:POSIX→UTF-8,Windows→ANSI/短路径。
+
+        统一走 _utils.native_path,解决中文路径在 Linux/macOS 打不开的问题。
+        """
+        return native_path(p)
+
+    def _check_trunc(self, str_len):
+        """检测定长缓冲区是否被写满(结果很可能被截断),是则报错而非返回残缺数据。
+
+        必须在 string_at(RetBuff, str_len) 之前调用:若底层返回的 str_len 超过缓冲
+        上限,直接 string_at 会越界读。
+        """
+        if str_len >= self.buf_max_size:
+            raise RuntimeError(
+                "结果超出缓冲区上限(%d 字节)被截断,无法完整返回。"
+                "请缩小查询/分页范围。" % self.buf_max_size
+            )
+        return str_len
+
     def _init_gpf_data(self, path):
         """Initialize GPF data by scanning and indexing Table and FSA files."""
         idxed_file2time = {}
@@ -137,7 +198,7 @@ class GPF:
 
         self.library_gpf.GPF_LatticeInit.argtypes = [c_void_p, c_char_p]
         self.library_gpf.GPF_LatticeInit.restype = c_int
-        self.library_gpf.GPF_DataInit(0, path_idx.encode('gbk', errors='strict'))
+        self.library_gpf.GPF_DataInit(0, self._enc_path(path_idx))
 
         for f in table_files:
             print("Indexing Table", f)
@@ -165,6 +226,7 @@ class GPF:
         self.library_gpf.GPF_GetTextByRange.argtypes = [c_void_p, c_int, c_int, c_char_p, c_int]
         self.library_gpf.GPF_GetTextByRange.restype = c_int
         str_len = self.library_gpf.GPF_GetTextByRange(self.hHandleGPF, begin, end, self.RetBuff, self.buf_max_size)
+        self._check_trunc(str_len)
         ret = string_at(self.RetBuff, str_len)
         return ret.decode()
 
@@ -175,6 +237,7 @@ class GPF:
         self.library_gpf.GPF_GetGrid.argtypes = [c_void_p, c_char_p, c_int]
         self.library_gpf.GPF_GetGrid.restype = c_int
         str_len = self.library_gpf.GPF_GetGrid(self.hHandleGPF, self.RetBuff, self.buf_max_size)
+        self._check_trunc(str_len)
         if str_len != 0:
             str_ret = string_at(self.RetBuff, str_len)
             json_data = json.loads(str_ret.decode())
@@ -228,11 +291,14 @@ class GPF:
         else:
             str_len = self.library_gpf.GPF_GetUnitsByNo(self.hHandleGPF, UnitNo.encode(), UExpress.encode(), kv.encode(), self.RetBuff, self.buf_max_size)
 
+        self._check_trunc(str_len)
         if str_len != 0:
             ret = string_at(self.RetBuff, str_len)
             json_data = json.loads(ret.decode())
             return json_data
-        return 0
+        # 空结果统一返回 []（原先返回 int 0,与有结果时的列表类型不一致,
+        # 调用方 for 迭代会得到非预期行为/报错）
+        return []
 
     def GetUnitKV(self, unitNo, key=""):
         return self.GetUnitKVs(unitNo, key)
@@ -291,6 +357,7 @@ class GPF:
         self.library_gpf.GPF_GetRelations.argtypes = [c_void_p, c_char_p, c_char_p, c_int]
         self.library_gpf.GPF_GetRelations.restype = c_int
         str_len = self.library_gpf.GPF_GetRelations(self.hHandleGPF, kv.encode(), self.RetBuff, self.buf_max_size)
+        self._check_trunc(str_len)
         if str_len != 0:
             ret = string_at(self.RetBuff, str_len)
             json_data = json.loads(ret.decode())
@@ -441,6 +508,13 @@ class GPF:
         return self.CallFSA(fsaName, param)
 
     def CallFSA(self, fsaName, **Others):
+        """运行 FSA 规则。
+
+        ⚠️ 安全警告:FSA 规则匹配后由底层引擎返回的 "operation" 会被本方法用
+        exec() 直接执行(见下方)。这意味着**加载并运行 FSA 规则等同于执行其中
+        内嵌的任意 Python 代码**。请仅对**可信来源**的 FSA 规则文件使用,切勿
+        运行来历不明/他人提供的规则。
+        """
         Param = ""
         for K, V in Others.items():
             if len(Param) != 0:
@@ -466,6 +540,8 @@ class GPF:
             offset += 4
             self.library_gpf.GPF_SetFSAPath(self.hHandleGPF, self.RetBuff[offset:offset+MatchPathLen[0]], MatchPathLen[0])
             offset += MatchPathLen[0]
+            # ⚠️ 执行底层引擎返回的 operation(任意 Python)。仅限可信 FSA 规则,
+            #    见 CallFSA 文档字符串的安全警告。
             exec(code.decode())
 
         return length
@@ -548,6 +624,13 @@ class GPF:
         Structure = Param[0]
         IsWeb = Param[1]
         table = Param[2]
+        if len(text) > self.Max_Length:
+            import warnings
+            warnings.warn(
+                "输入文本长度 %d 超过上限 %d,已截断:仅前 %d 个字符参与分析。"
+                % (len(text), self.Max_Length, self.Max_Length),
+                stacklevel=2,
+            )
         text = text[0:self.Max_Length]
         if Structure == "Segment" and IsWeb == False:
             Ret = self.Segment(text, table)
@@ -558,21 +641,8 @@ class GPF:
             Ret = Ret.strip(" ")
             Items = Ret.split(" ")
             return json.dumps(Items, ensure_ascii=False)
-        if Structure == "Tree":
-            url = 'https://cit.blcu.edu.cn/stree'
-            r = requests.post(url=url, data=text)
-            r.encoding = 'utf8'
-            return r.text
-        if Structure == "Chunk" :
-            url = 'https://cit.blcu.edu.cn/chunk/'
-            r = requests.post(url=url, data=text)
-            r.encoding = 'utf8'
-            return r.text
-        if Structure == "Dep":
-            url = 'https://cit.blcu.edu.cn/dep'
-            r = requests.post(url=url, data=text)
-            r.encoding = 'utf8'
-            return r.text
+        if Structure in ("Tree", "Chunk", "Dep"):
+            return self._parse_via_gateway(Structure, text)
 
         JS = self.CallService(text, Structure)
         if JS == "":
@@ -601,6 +671,128 @@ class GPF:
         Parm.append(IsWeb)
         Parm.append(table)
 
+    # --- 远程句法分析网关（Tree/Chunk/Dep → BSTService 公开端点）---
+
+    _PARSER_ENDPOINT = {"Tree": "stree", "Chunk": "chunk", "Dep": "dep"}
+
+    def _parse_via_gateway(self, structure, text):
+        """调用 BSTService 公开句法分析端点，并把结果转成渲染端可直接消费的结构。
+
+        端点: {ParserURL}/v1/public/parser/{stree|chunk|dep}，入参 {"text": text}。
+        返回 CommonResponse: {"success","code","message","data"}，data 为拍平结构：
+          - stree → {"tree": "(ROOT ...)"}
+          - chunk → {"chunks":[...], "pos":[...]}
+          - dep   → {"chunks":[...], "pos":[...], "ip":[...],
+                      "groups":[{"headId":int, "deps":[{"role":str,"subId":int}]}]}
+        本方法分别转为 Seq / Tree / Graph 形状（见 GetShowStructType），使
+        ShowStructure / Show* 无需改动即可渲染。返回 JSON 字符串。
+        """
+        endpoint = self._PARSER_ENDPOINT[structure]
+        url = self.ParserURL + "/v1/public/parser/" + endpoint
+        try:
+            r = requests.post(url, json={"text": text}, timeout=30)
+            r.encoding = "utf-8"
+            body = r.json()
+        except Exception as e:
+            raise RuntimeError("句法分析网关调用失败 (%s): %s" % (url, e)) from e
+        data = body.get("data") if isinstance(body, dict) else None
+        if data is None:
+            msg = body.get("message") if isinstance(body, dict) else str(body)
+            raise RuntimeError("句法分析网关返回异常: %s" % msg)
+        if structure == "Chunk":
+            Ret = self._adapt_chunk(data)
+        elif structure == "Dep":
+            Ret = self._adapt_dep(data)
+        else:  # Tree
+            Ret = self._adapt_tree(data)
+        return json.dumps(Ret, ensure_ascii=False)
+
+    @staticmethod
+    def _adapt_chunk(data):
+        """{chunks,pos} → ["组块/词性", ...]（Seq）"""
+        chunks = data.get("chunks") or []
+        pos = data.get("pos") or []
+        out = []
+        for i in range(len(chunks)):
+            tag = pos[i] if i < len(pos) else ""
+            out.append(chunks[i] + "/" + tag if tag else chunks[i])
+        return out
+
+    @staticmethod
+    def _adapt_dep(data):
+        """{chunks,groups:[{headId,deps:[{role,subId}]}]} → [[head,tail,role], ...]（Graph）
+
+        headId/subId 视为 chunks 的下标；越界或非整型时退化为直接用其值。
+        节点用 '下标:词'，避免同形词在图中被合并为同一节点。
+        """
+        chunks = data.get("chunks") or []
+
+        def node(idx):
+            # 节点 id 用双引号包裹后交给 DrawGraph 原样写入 DOT：
+            # 不加引号时 "2:破门" 会被当成"节点2端口破门"，且数字开头会触发
+            # DOT 数字解析歧义。带位置下标是为避免同形词被合并为同一节点。
+            if isinstance(idx, int) and 0 <= idx < len(chunks):
+                label = str(idx) + "：" + str(chunks[idx])
+            else:
+                label = str(idx)
+            return '"' + label.replace('"', "'") + '"'
+
+        triples = []
+        for g in data.get("groups") or []:
+            head = node(g.get("headId"))
+            for d in g.get("deps") or []:
+                triples.append([head, node(d.get("subId")), str(d.get("role", ""))])
+        return triples
+
+    @staticmethod
+    def _adapt_tree(data):
+        """{tree:"(ROOT (IP ...))"} → 嵌套结构（Tree，供 DrawTree 渲染）。
+
+        把 Penn 括号串解析为 {label: [子节点...]}（叶子为字符串）；同名兄弟用列表承载，
+        由 DrawTree 的 Tag 机制在渲染时去重。若 tree 非括号串则原样返回。
+        """
+        s = data.get("tree")
+        if isinstance(s, list):  # 上游偶发单元素数组
+            s = s[0] if s else ""
+        if not isinstance(s, str) or "(" not in s:
+            return data.get("tree", data)
+
+        pos = [0]
+
+        def skip_ws():
+            while pos[0] < len(s) and s[pos[0]].isspace():
+                pos[0] += 1
+
+        def read_token():
+            start = pos[0]
+            while pos[0] < len(s) and s[pos[0]] not in "()" and not s[pos[0]].isspace():
+                pos[0] += 1
+            return s[start:pos[0]]
+
+        def parse_node():
+            skip_ws()
+            pos[0] += 1  # '('
+            label = read_token()
+            children = []
+            while True:
+                skip_ws()
+                if pos[0] >= len(s) or s[pos[0]] == ")":
+                    break
+                if s[pos[0]] == "(":
+                    children.append(parse_node())
+                else:
+                    children.append(read_token())
+            if pos[0] < len(s) and s[pos[0]] == ")":
+                pos[0] += 1  # ')'
+            if len(children) == 1 and isinstance(children[0], str):
+                return {label: children[0]}
+            return {label: children}
+
+        try:
+            return parse_node()
+        except Exception:
+            return {"tree": s}
+
     # --- Service/Dot ---
 
     def CallService(self, sentence, name):
@@ -608,6 +800,7 @@ class GPF:
         self.library_gpf.GPF_CallService.argtypes = [c_void_p, c_char_p, c_char_p, c_char_p, c_int]
         self.library_gpf.GPF_CallService.restype = c_int
         str_len = self.library_gpf.GPF_CallService(self.hHandleGPF, name.encode(), sentence.encode(), self.RetBuff, self.buf_max_size)
+        self._check_trunc(str_len)
         ret = string_at(self.RetBuff, str_len)
         return ret.decode()
 
@@ -616,6 +809,7 @@ class GPF:
         self.library_gpf.GPF_CallDot.argtypes = [c_void_p, c_char_p, c_char_p, c_char_p, c_int]
         self.library_gpf.GPF_CallDot.restype = c_int
         str_len = self.library_gpf.GPF_CallDot(self.hHandleGPF, name.encode(), Dot.encode(), self.RetBuff, self.buf_max_size)
+        self._check_trunc(str_len)
         return string_at(self.RetBuff, str_len)
 
     def DotFile(self, dot_filename, img_filename):
@@ -757,7 +951,7 @@ class GPF:
         if IsGPFInit == 0:
             self.library_gpf.GPF_LatticeInit.argtypes = [c_void_p, c_char_p]
             self.library_gpf.GPF_LatticeInit.restype = c_int
-            IsGPFInit = self.library_gpf.GPF_DataInit(self.ConfigGPF.encode(), self.dataPath.encode('gbk', errors='strict'))
+            IsGPFInit = self.library_gpf.GPF_DataInit(self.ConfigGPF.encode(), self._enc_path(self.dataPath))
         lock.release()
 
     def GPFPersons(self):
@@ -1121,17 +1315,22 @@ class GPF:
         return DoctInfo
 
     def DrawTree(self, Json, Tag, Root=""):
+        # \u8282\u70b9\u540d\u5728\u5199\u5165 DOT \u65f6\u7edf\u4e00\u52a0\u5f15\u53f7\uff1a\u771f\u5b9e\u53e5\u6cd5\u6811\u7684 POS \u6807\u7b7e\u5e38\u542b\u8fde\u5b57\u7b26
+        # \uff08NP-SBJ\u3001VP-PRD\uff09\u6216\u6807\u70b9\uff0c\u4e0d\u52a0\u5f15\u53f7\u4f1a\u88ab DOT \u5f53\u4f5c\u975e\u6cd5 id \u89e3\u6790\u5931\u8d25\u3002
+        # Tag \u53bb\u91cd\u4ecd\u7528\u539f\u59cb\u6807\u7b7e\uff08\u8ffd\u52a0\u5168\u89d2\u7a7a\u683c\uff09\uff0c\u5f15\u53f7\u53ea\u5728\u8f93\u51fa\u65f6\u5305\u88f9\u3002
+        def q(x):
+            return '"' + str(x).replace("\\", "\\\\").replace('"', '\\"') + '"'
         DoctInfo = ""
         if isinstance(Json, list):
             for i in range(len(Json)):
                 if isinstance(Json[i], str) or isinstance(Json[i], int):
                     if Root == "":
                         if i < len(Json) - 1:
-                            DoctInfo += str(Json[i]) + "->"
+                            DoctInfo += q(Json[i]) + "->"
                         else:
-                            DoctInfo += str(Json[i]) + "\n"
+                            DoctInfo += q(Json[i]) + "\n"
                     else:
-                        DoctInfo += Root + "->" + str(Json[i]) + "\n"
+                        DoctInfo += q(Root) + "->" + q(Json[i]) + "\n"
                 else:
                     DoctInfo += self.DrawTree(Json[i], Tag, Root)
         elif isinstance(Json, dict):
@@ -1141,9 +1340,9 @@ class GPF:
                 else:
                     Tag[K] = Tag[K] + "\u3000"
                 if not Root == "":
-                    DoctInfo += Root + "->" + Tag[K] + "\n"
+                    DoctInfo += q(Root) + "->" + q(Tag[K]) + "\n"
                 if isinstance(V, str) or isinstance(V, int):
-                    DoctInfo += Tag[K] + "->" + str(V) + "\n"
+                    DoctInfo += q(Tag[K]) + "->" + q(V) + "\n"
                 else:
                     DoctInfo += self.DrawTree(V, Tag, Tag[K])
         return DoctInfo
@@ -1175,8 +1374,17 @@ class GPF:
         Script += Tail
         return Script
 
-    def ShowCloud(self, Json, Output):
-        wd = WordCloud(background_color="white", font_path="c:/windows/fonts/simyou.ttf")
+    def ShowCloud(self, Json, Output, font_path=None):
+        # 跨平台定位中文字体;原先硬编码 Windows 字体路径,在 Linux/macOS 必崩。
+        if font_path is None:
+            font_path = _find_cjk_font()
+        if font_path is None:
+            raise RuntimeError(
+                "生成词云需要一个中文字体,但未在系统常见位置找到。请安装 CJK 字体"
+                "(Linux:fonts-wqy-zenhei 或 Noto Sans CJK;Windows/macOS 一般自带),"
+                "或调用 ShowCloud(..., font_path=<字体文件路径>) 显式指定。"
+            )
+        wd = WordCloud(background_color="white", font_path=font_path)
         wd.generate_from_frequencies(json.loads(Json))
         wd.to_file(Output)
 

{langsc-2.3.0 → langsc-2.5.0}/LangSC/jss.py

@@ -20,7 +20,7 @@ import requests
 
 from ._utils import (
     detect_file_encoding, get_idx_info, get_jss_file_info, is_same,
-    get_jss_files, write_idx_log,
+    get_jss_files, write_idx_log, format_native_load_error, native_path,
 )
 
 OS = platform.system()
@@ -65,7 +65,10 @@ class JSS:
         self.dll_close = None
         self.library_jss = None
         dll_file_jss = os.path.join(os.path.dirname(os.path.abspath(__file__)), dll_name_jss)
-        self.library_jss = cdll.LoadLibrary(dll_file_jss)
+        try:
+            self.library_jss = cdll.LoadLibrary(dll_file_jss)
+        except OSError as e:
+            raise OSError(format_native_load_error(dll_name_jss, e)) from e
 
         if OS == "Windows":
             self.dll_close = win32api.FreeLibrary
@@ -73,7 +76,8 @@ class JSS:
             try:
                 stdlib = CDLL("")
             except OSError:
-                stdlib = CDLL("libc.so")
+                # libc.so 在部分发行版是链接脚本不可 dlopen，用 libc.so.6
+                stdlib = CDLL("libc.so.6")
             self.dll_close = stdlib.dlclose
             self.dll_close.argtypes = [c_void_p]
         else:
@@ -134,21 +138,39 @@ class JSS:
         name = os.path.splitext(os.path.basename(json_file))[0]
         encoding = detect_file_encoding(json_file)
 
-        # Read first record
-        if json_file.endswith('.jsonl'):
-            record_format = "jsonl"
-            with open(json_file, 'r', encoding=encoding) as f:
-                record = json.loads(f.readline().strip())
-        else:
-            record_format = "json"
-            with open(json_file, 'r', encoding=encoding) as f:
-                data = json.load(f)
-            if isinstance(data, list) and len(data) > 0:
-                record = data[0]
-            elif isinstance(data, dict):
-                record = data
+        # Read first record（对格式错误/空文件给出可诊断错误，而非裸 JSONDecodeError）
+        try:
+            if json_file.endswith('.jsonl'):
+                record_format = "jsonl"
+                record = None
+                with open(json_file, 'r', encoding=encoding, errors='replace') as f:
+                    for line in f:
+                        line = line.strip()
+                        if line:                      # 跳过空行，取首条有效 JSON
+                            record = json.loads(line)
+                            break
+                if record is None:
+                    raise ValueError("文件为空或没有有效的 JSON 行")
             else:
-                record = {}
+                record_format = "json"
+                with open(json_file, 'r', encoding=encoding, errors='replace') as f:
+                    data = json.load(f)
+                if isinstance(data, list) and len(data) > 0:
+                    record = data[0]
+                elif isinstance(data, dict):
+                    record = data
+                else:
+                    raise ValueError("顶层既非非空数组也非对象，无法推断字段")
+        except (json.JSONDecodeError, ValueError, OSError, UnicodeError) as e:
+            raise ValueError(
+                "无法从 %s 解析首条记录以自动生成索引配置：%s。"
+                "请确认它是合法的 JSON/JSONL（或手工提供 cfg_%s.txt）。"
+                % (json_file, e, name)
+            ) from e
+        if not isinstance(record, dict):
+            raise ValueError(
+                "%s 的首条记录不是 JSON 对象(dict)，无法生成字段配置。" % json_file
+            )
 
         # Build content: array fields get "[]" suffix
         content = {}
@@ -201,13 +223,18 @@ class JSS:
         # JL_CreateTable 第 7 参数 pBuildToolInfo（当前引擎 API；旧版 6 参数 DLL 在 cdecl 下忽略多余实参，向后兼容）
         self.library_jss.JL_CreateTable.restype = c_int
         self.library_jss.JL_CreateTable.argtypes = [c_char_p, c_char_p, c_char_p, c_char_p, c_int, c_char_p, c_char_p]
-        ret = self.library_jss.JL_CreateTable(cfg_filename.encode(), seg_fullname.encode(), dat_pathname.encode(), out_pathname.encode(), self.log_level, self.log_filename.encode(), b"LangSC")
+        # 路径参数统一走 native_path(POSIX→UTF-8,Windows→ANSI/短路径);
+        # log_filename 可能为空字符串,native_path 对其返回 b"",行为不变。
+        ret = self.library_jss.JL_CreateTable(
+            native_path(cfg_filename), native_path(seg_fullname),
+            native_path(dat_pathname), native_path(out_pathname),
+            self.log_level, native_path(self.log_filename), b"LangSC")
         return ret
 
     def _load_table(self, filename, name=""):
         self.library_jss.JL_Initialize.restype = c_void_p
         self.library_jss.JL_Initialize.argtypes = [c_char_p, c_int, c_char_p]
-        handle = self.library_jss.JL_Initialize(filename.encode(), self.log_level, self.log_filename.encode())
+        handle = self.library_jss.JL_Initialize(native_path(filename), self.log_level, native_path(self.log_filename))
         if not name:
             name = os.path.basename(filename)
         self.handles[name] = handle
@@ -216,16 +243,41 @@ class JSS:
 
     def Run(self, sql_statement, table=""):
         if not self.is_init:
-            return []
+            raise RuntimeError(
+                "JSS 未加载任何数据表(dataPath=%r)。请确认该目录下有可索引的 "
+                ".json/.jsonl 数据或已建好的索引;若目录为空或索引失败,查询无法执行。"
+                % self.dataPath
+            )
         if table and table in self.handles:
             handle = self.handles[table]
+        elif table:
+            raise KeyError(
+                "JSS 没有名为 %r 的表。已加载的表:%s"
+                % (table, list(self.handles.keys()))
+            )
         else:
             handle = next(iter(self.handles.values()))
         self.library_jss.JL_RunSql.restype = c_int
         self.library_jss.JL_RunSql.argtypes = [c_void_p, c_char_p, c_char_p, c_int]
         str_len = self.library_jss.JL_RunSql(handle, sql_statement.encode(), self.RetBuff, self.buf_max_size)
-        ret = string_at(self.RetBuff, str_len)
-        json_data = json.loads(ret.decode())
+        if str_len >= self.buf_max_size:
+            raise RuntimeError(
+                "JSS 结果超出缓冲区上限(%d 字节)被截断。请用 LIMIT 缩小结果集。"
+                % self.buf_max_size
+            )
+        raw = string_at(self.RetBuff, str_len).decode()
+        try:
+            json_data = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise RuntimeError(
+                "JSS 返回内容无法解析为 JSON(SQL=%r):%s。返回片段:%.200s"
+                % (sql_statement, e, raw)
+            ) from e
+        if not isinstance(json_data, dict) or "results" not in json_data:
+            raise RuntimeError(
+                "JSS 返回缺少 'results' 字段(SQL=%r)。可能是 SQL 语法错误或引擎报错。"
+                "返回内容:%.300s" % (sql_statement, raw)
+            )
         return json_data['results']
 
     def Terminate(self):

{langsc-2.3.0 → langsc-2.5.0}/LangSC.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: LangSC
-Version: 2.3.0
+Version: 2.5.0
 Summary: Language Structure Computation - GPF, BCC, and JSS unified package
 Author: endongxun
 Author-email: xunendong@gmail.com
@@ -260,14 +260,15 @@ result = gpf.Parse("自然语言处理", Structure="Segment")
 # 词性标注（默认）
 result = gpf.Parse("自然语言处理", Structure="POS")
 
-# 句法树（远程服务 https://cit.blcu.edu.cn/stree）
+# 句法树（远程服务：BSTService 网关 /v1/public/parser/stree）
 result = gpf.Parse("自然语言处理", Structure="Tree")
 
-# 短语分析（远程服务 https://cit.blcu.edu.cn/chunk/）
+# 短语/组块分析（远程服务：/v1/public/parser/chunk）
 result = gpf.Parse("自然语言处理", Structure="Chunk")
 
-# 依存分析（远程服务 https://cit.blcu.edu.cn/dep）
+# 依存分析（远程服务：/v1/public/parser/dep）
 result = gpf.Parse("自然语言处理", Structure="Dep")
+# 远程网关默认 https://cnlp.blcu.edu.cn/ice/api，可用 GPF(parser_url=...) 覆盖
 
 # 指定用户词表
 result = gpf.Parse("自然语言处理", Structure="Segment", Table="myDict")
@@ -1749,7 +1750,9 @@ Item:这 是 第 二 句
 | `BCCconfig.txt` | BCC | BCC 引擎配置（线程、内存、索引参数） |
 | `Parser.lua` | BCC | Lua 查询解析脚本 |
 | `base.lex` | JSS | 分词词典（affix/bm25 索引用） |
-| `Graph/dot.exe` | GPF | Graphviz DOT 工具（Windows 可视化） |
+
+> 可视化不再内置 Windows 的 `Graph/dot.exe`，自 2.3.0 起改用 `pygraphviz`（其 PyPI
+> wheel 自带全平台 Graphviz，`pip install` 即可，无需系统另装）。
 
 ### 9.3 线程安全
 
@@ -1777,6 +1780,28 @@ GPF 和 BCC 的初始化操作使用 `threading.Lock()` 保护，确保多线程
 文件名\t时间戳1\t时间戳2
 ```
 
+### 9.5 已知限制与跨平台注意事项
+
+- **数据路径优先用 ASCII/英文目录。** 底层 C 引擎按字节打开文件：wrapper 已按平台做
+  边界编码（POSIX→UTF-8，Windows→ANSI/8.3 短路径），因此：
+  - **JSS**：中文（非 ASCII）数据路径三平台均可用。
+  - **GPF**：中文路径按设计可用（Linux/macOS 走 UTF-8；Windows 走 ANSI）。
+  - **BCC**：其引擎在中文临时路径上自身 `fopen` 存在限制（Windows 亦然），**建议 BCC
+    的语料/索引目录使用 ASCII 路径**。
+  - 含当前 ANSI 代码页无法表示的字符（如 emoji、西里尔）时，Windows 会尝试 8.3 短路径；
+    若该卷禁用了 8.3 名称则会报明确错误——请改用 ASCII 路径。
+- **原生库为单架构（x86_64）。** 在 Apple Silicon（arm64 macOS）或 ARM Linux 上，若未提供
+  对应架构的 `.dylib`/`.so`，加载会失败并给出带系统/架构信息的报错；需为对应架构重新构建。
+- **远程句法分析**（`Parse` 的 `Tree`/`Chunk`/`Dep`）依赖 BSTService 公开网关
+  （默认 `https://cnlp.blcu.edu.cn/ice/api`，可用 `GPF(parser_url=...)` 覆盖），需联网且服务可用。
+  `Segment`/`POS` 为本地 DLL，不需联网。
+- **Graphviz 渲染中文需宿主机安装 CJK 字体**（模板用 `fontname="fangsong"`）。Windows/macOS
+  一般自带；**Linux 需安装**如 `fonts-wqy-zenhei` 或 Noto Sans CJK，否则中文显示为方框
+  （不影响出图成功）。词云 `ShowCloud` 会自动探测中文字体，找不到可传 `font_path=` 指定。
+- **Python ≥ 3.10**（匹配 `pygraphviz` 自带二进制 wheel 覆盖的 3.10–3.15）。
+- **进程级初始化**：同一进程内 CRF/POS/GPF 引擎只初始化一次、共用同一套模型。需要不同模型
+  时请在不同进程中分别运行（见 §9.3）。
+
 ---
 
 ## 10. 参考文献

{langsc-2.3.0 → langsc-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: LangSC
-Version: 2.3.0
+Version: 2.5.0
 Summary: Language Structure Computation - GPF, BCC, and JSS unified package
 Author: endongxun
 Author-email: xunendong@gmail.com
@@ -260,14 +260,15 @@ result = gpf.Parse("自然语言处理", Structure="Segment")
 # 词性标注（默认）
 result = gpf.Parse("自然语言处理", Structure="POS")
 
-# 句法树（远程服务 https://cit.blcu.edu.cn/stree）
+# 句法树（远程服务：BSTService 网关 /v1/public/parser/stree）
 result = gpf.Parse("自然语言处理", Structure="Tree")
 
-# 短语分析（远程服务 https://cit.blcu.edu.cn/chunk/）
+# 短语/组块分析（远程服务：/v1/public/parser/chunk）
 result = gpf.Parse("自然语言处理", Structure="Chunk")
 
-# 依存分析（远程服务 https://cit.blcu.edu.cn/dep）
+# 依存分析（远程服务：/v1/public/parser/dep）
 result = gpf.Parse("自然语言处理", Structure="Dep")
+# 远程网关默认 https://cnlp.blcu.edu.cn/ice/api，可用 GPF(parser_url=...) 覆盖
 
 # 指定用户词表
 result = gpf.Parse("自然语言处理", Structure="Segment", Table="myDict")
@@ -1749,7 +1750,9 @@ Item:这 是 第 二 句
 | `BCCconfig.txt` | BCC | BCC 引擎配置（线程、内存、索引参数） |
 | `Parser.lua` | BCC | Lua 查询解析脚本 |
 | `base.lex` | JSS | 分词词典（affix/bm25 索引用） |
-| `Graph/dot.exe` | GPF | Graphviz DOT 工具（Windows 可视化） |
+
+> 可视化不再内置 Windows 的 `Graph/dot.exe`，自 2.3.0 起改用 `pygraphviz`（其 PyPI
+> wheel 自带全平台 Graphviz，`pip install` 即可，无需系统另装）。
 
 ### 9.3 线程安全
 
@@ -1777,6 +1780,28 @@ GPF 和 BCC 的初始化操作使用 `threading.Lock()` 保护，确保多线程
 文件名\t时间戳1\t时间戳2
 ```
 
+### 9.5 已知限制与跨平台注意事项
+
+- **数据路径优先用 ASCII/英文目录。** 底层 C 引擎按字节打开文件：wrapper 已按平台做
+  边界编码（POSIX→UTF-8，Windows→ANSI/8.3 短路径），因此：
+  - **JSS**：中文（非 ASCII）数据路径三平台均可用。
+  - **GPF**：中文路径按设计可用（Linux/macOS 走 UTF-8；Windows 走 ANSI）。
+  - **BCC**：其引擎在中文临时路径上自身 `fopen` 存在限制（Windows 亦然），**建议 BCC
+    的语料/索引目录使用 ASCII 路径**。
+  - 含当前 ANSI 代码页无法表示的字符（如 emoji、西里尔）时，Windows 会尝试 8.3 短路径；
+    若该卷禁用了 8.3 名称则会报明确错误——请改用 ASCII 路径。
+- **原生库为单架构（x86_64）。** 在 Apple Silicon（arm64 macOS）或 ARM Linux 上，若未提供
+  对应架构的 `.dylib`/`.so`，加载会失败并给出带系统/架构信息的报错；需为对应架构重新构建。
+- **远程句法分析**（`Parse` 的 `Tree`/`Chunk`/`Dep`）依赖 BSTService 公开网关
+  （默认 `https://cnlp.blcu.edu.cn/ice/api`，可用 `GPF(parser_url=...)` 覆盖），需联网且服务可用。
+  `Segment`/`POS` 为本地 DLL，不需联网。
+- **Graphviz 渲染中文需宿主机安装 CJK 字体**（模板用 `fontname="fangsong"`）。Windows/macOS
+  一般自带；**Linux 需安装**如 `fonts-wqy-zenhei` 或 Noto Sans CJK，否则中文显示为方框
+  （不影响出图成功）。词云 `ShowCloud` 会自动探测中文字体，找不到可传 `font_path=` 指定。
+- **Python ≥ 3.10**（匹配 `pygraphviz` 自带二进制 wheel 覆盖的 3.10–3.15）。
+- **进程级初始化**：同一进程内 CRF/POS/GPF 引擎只初始化一次、共用同一套模型。需要不同模型
+  时请在不同进程中分别运行（见 §9.3）。
+
 ---
 
 ## 10. 参考文献

{langsc-2.3.0 → langsc-2.5.0}/README.md

@@ -236,14 +236,15 @@ result = gpf.Parse("自然语言处理", Structure="Segment")
 # 词性标注（默认）
 result = gpf.Parse("自然语言处理", Structure="POS")
 
-# 句法树（远程服务 https://cit.blcu.edu.cn/stree）
+# 句法树（远程服务：BSTService 网关 /v1/public/parser/stree）
 result = gpf.Parse("自然语言处理", Structure="Tree")
 
-# 短语分析（远程服务 https://cit.blcu.edu.cn/chunk/）
+# 短语/组块分析（远程服务：/v1/public/parser/chunk）
 result = gpf.Parse("自然语言处理", Structure="Chunk")
 
-# 依存分析（远程服务 https://cit.blcu.edu.cn/dep）
+# 依存分析（远程服务：/v1/public/parser/dep）
 result = gpf.Parse("自然语言处理", Structure="Dep")
+# 远程网关默认 https://cnlp.blcu.edu.cn/ice/api，可用 GPF(parser_url=...) 覆盖
 
 # 指定用户词表
 result = gpf.Parse("自然语言处理", Structure="Segment", Table="myDict")
@@ -1725,7 +1726,9 @@ Item:这 是 第 二 句
 | `BCCconfig.txt` | BCC | BCC 引擎配置（线程、内存、索引参数） |
 | `Parser.lua` | BCC | Lua 查询解析脚本 |
 | `base.lex` | JSS | 分词词典（affix/bm25 索引用） |
-| `Graph/dot.exe` | GPF | Graphviz DOT 工具（Windows 可视化） |
+
+> 可视化不再内置 Windows 的 `Graph/dot.exe`，自 2.3.0 起改用 `pygraphviz`（其 PyPI
+> wheel 自带全平台 Graphviz，`pip install` 即可，无需系统另装）。
 
 ### 9.3 线程安全
 
@@ -1753,6 +1756,28 @@ GPF 和 BCC 的初始化操作使用 `threading.Lock()` 保护，确保多线程
 文件名\t时间戳1\t时间戳2
 ```
 
+### 9.5 已知限制与跨平台注意事项
+
+- **数据路径优先用 ASCII/英文目录。** 底层 C 引擎按字节打开文件：wrapper 已按平台做
+  边界编码（POSIX→UTF-8，Windows→ANSI/8.3 短路径），因此：
+  - **JSS**：中文（非 ASCII）数据路径三平台均可用。
+  - **GPF**：中文路径按设计可用（Linux/macOS 走 UTF-8；Windows 走 ANSI）。
+  - **BCC**：其引擎在中文临时路径上自身 `fopen` 存在限制（Windows 亦然），**建议 BCC
+    的语料/索引目录使用 ASCII 路径**。
+  - 含当前 ANSI 代码页无法表示的字符（如 emoji、西里尔）时，Windows 会尝试 8.3 短路径；
+    若该卷禁用了 8.3 名称则会报明确错误——请改用 ASCII 路径。
+- **原生库为单架构（x86_64）。** 在 Apple Silicon（arm64 macOS）或 ARM Linux 上，若未提供
+  对应架构的 `.dylib`/`.so`，加载会失败并给出带系统/架构信息的报错；需为对应架构重新构建。
+- **远程句法分析**（`Parse` 的 `Tree`/`Chunk`/`Dep`）依赖 BSTService 公开网关
+  （默认 `https://cnlp.blcu.edu.cn/ice/api`，可用 `GPF(parser_url=...)` 覆盖），需联网且服务可用。
+  `Segment`/`POS` 为本地 DLL，不需联网。
+- **Graphviz 渲染中文需宿主机安装 CJK 字体**（模板用 `fontname="fangsong"`）。Windows/macOS
+  一般自带；**Linux 需安装**如 `fonts-wqy-zenhei` 或 Noto Sans CJK，否则中文显示为方框
+  （不影响出图成功）。词云 `ShowCloud` 会自动探测中文字体，找不到可传 `font_path=` 指定。
+- **Python ≥ 3.10**（匹配 `pygraphviz` 自带二进制 wheel 覆盖的 3.10–3.15）。
+- **进程级初始化**：同一进程内 CRF/POS/GPF 引擎只初始化一次、共用同一套模型。需要不同模型
+  时请在不同进程中分别运行（见 §9.3）。
+
 ---
 
 ## 10. 参考文献