quant1x 0.7.62.dev2__tar.gz → 0.8.0__tar.gz

quant1x-0.8.0/.githooks/commit-msg

@@ -0,0 +1,60 @@
+#!/bin/sh
+# commit-msg 钩子：提交信息编码校验（非法 UTF-8 / GBK 乱码 → 拒绝提交）
+# 校验逻辑见同目录 commit_msg_check.py
+hook_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+run_check() {
+    # 优先使用 python / python3；在 Windows 环境下回退到 py -3
+    if command -v python >/dev/null 2>&1; then
+        python -V >/dev/null 2>&1
+        probe=$?
+        if [ "$probe" -ne 126 ] && [ "$probe" -ne 127 ]; then
+            python "$hook_dir/commit_msg_check.py" "$1"
+            return $?
+        fi
+    fi
+    if command -v python3 >/dev/null 2>&1; then
+        python3 -V >/dev/null 2>&1
+        probe=$?
+        if [ "$probe" -ne 126 ] && [ "$probe" -ne 127 ]; then
+            python3 "$hook_dir/commit_msg_check.py" "$1"
+            return $?
+        fi
+    fi
+    if command -v py >/dev/null 2>&1; then
+        py -3 -V >/dev/null 2>&1
+        probe=$?
+        if [ "$probe" -ne 126 ] && [ "$probe" -ne 127 ]; then
+            py -3 "$hook_dir/commit_msg_check.py" "$1"
+            return $?
+        fi
+    fi
+    return 127
+}
+
+run_check "$1"
+check_rc=$?
+if [ "$check_rc" -eq 127 ]; then
+    echo "commit-msg 校验未通过：未找到可用 Python 解释器（python/python3/py -3）。" >&2
+    exit 1
+fi
+if [ "$check_rc" -ne 0 ]; then
+    echo "commit-msg 校验未通过，提交已中止。请修正提交信息后重试。" >&2
+    exit 1
+fi
+
+# 提交尾注/署名约束（仓库规则）：
+# - 禁止 Co-authored-by trailer
+# - 禁止 Copilot/AI 署名（包含历史常见 noreply 地址）
+msg_file="$1"
+if [ -n "$msg_file" ] && [ -f "$msg_file" ]; then
+    if tr -d '\r' < "$msg_file" | grep -Eiq '^[[:space:]]*co-authored-by[[:space:]]*:'; then
+        echo "commit-msg 校验未通过：禁止 Co-authored-by trailer。" >&2
+        exit 1
+    fi
+    if tr -d '\r' < "$msg_file" | grep -Eiq 'copilot@users\.noreply\.github\.com|^[[:space:]]*(copilot|ai)[[:space:]]*(署名|signature)[[:space:]]*:'; then
+        echo "commit-msg 校验未通过：禁止 Copilot/AI 署名信息。" >&2
+        exit 1
+    fi
+fi
+
+exit 0

quant1x-0.8.0/.githooks/commit_msg_check.py

@@ -0,0 +1,198 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2026 Quant1X <wangfengxy@sina.cn>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+"""commit-msg 校验：提交信息编码完整性检查（拒绝乱码/损坏文本）。
+
+Windows 下中文提交信息若经 GBK 命令行/控制台传递，会被错误转码并作为
+“合法 UTF-8 的乱码文本”写入提交对象（历史上有 daa14be / 8e49a85 两例）。
+本脚本只做两类判断，全部基于编码事实，不维护任何“乱码特征字”黑名单：
+
+一、硬性检查（编码损坏的直接证据）
+   - 必须整体是合法 UTF-8；
+   - 不含 NUL 字节、替换符 U+FFFD、私有区字符（PUA）。
+     这些都是正常输入不可能出现、只会由编码损坏产生的字符。
+
+二、round-trip 反推（乱码检测主逻辑）
+   乱码的产生链是确定的：
+       原始 UTF-8 字节流 → 被按编码 E 误读（得到“乱码字符”）
+       → 再以 UTF-8 存储（得到我们看到的文本）
+   因此把待检文本按 E 重新编码、再按 UTF-8 解码，若还原出的文本
+   “与原文不同且以汉字为主”，即可确认它是 E 误读的产物：
+       text.encode(E).decode('utf-8') → 原始中文
+   CANDIDATES 列出常见误读链（GB18030/CP1252/Latin-1/Shift_JIS/
+   EUC-KR/KOI8-R 等）。将来出现“UTF-8 被当作编码 X 读取”的新形态，
+   只需在 CANDIDATES 增补一行，无需维护字符表。
+
+   误报分析（为何“还原出汉字”是强信号）：
+   - 正常中文文本按 GBK/GB18030 整体编码后，字节流几乎必然无法构成
+     合法 UTF-8（单字双字节落点不在 UTF-8 合法区间内，序列连续性亦
+     不成立），解码必然失败；即便以 errors='replace' 宽容扫描，GBK
+     字节偶合出的 UTF-8 片段也只会落在 Latin 区（2 字节 UTF-8 编码
+     范围 U+0080..U+07FF 不含汉字），汉字必须由 3 字节 UTF-8 编码，
+     这种连续偶合几乎不可能成串出现。因此“还原文本含 >= 2 个汉字”
+     基本只可能来自真正的乱码。
+
+   字节丢失处理：误读链若带丢字节（历史两例即如此），还原会以
+   errors='replace' 进行，丢失处产生 U+FFFD。此时用 “FFFD 数 <= 还原
+   汉字数” 约束：真乱码还原后汉字是主体、FFFD 只是零星丢失位；
+   正常文本偶合还原出的汉字极少而 FFFD 占绝对多数，二者可明确区分。
+
+用法：
+    python commit_msg_check.py <commit-msg-file>
+    python commit_msg_check.py --debug <commit-msg-file>   # 诊断模式
+返回 0 通过；非 0 拒绝（信息输出到 stderr）。
+
+--debug 模式：对每个 CANDIDATE 打印 round-trip 诊断（encode 结果、
+解码模式、还原汉字数 / FFFD 数、是否命中），便于排查“新出现的乱码
+形态应归入哪条误读链”。
+"""
+import re
+import sys
+
+# 误读链候选，按仓库环境（Windows/中文）常见度排序；每条注明典型场景，
+# 日后按“实际观测到的新乱码形态”增补即可：
+#   gb18030   Windows 简体中文环境把 UTF-8 字节流按 GBK/CP936 读取后再以
+#             UTF-8 存储 —— 本仓库历史乱码（daa14be / 8e49a85）即此链；
+#             GB18030 是 GBK 的超集，覆盖其全部单/双字节形态
+#   cp1252    Windows 拉丁环境按 CP1252 读取 UTF-8（“é…” 型 mojibake）
+#   latin-1   逐字节无损映射的 ISO-8859-1，覆盖 cp1252 未包含的 0x80-0x9F 形态
+#   shift_jis 日文环境按 Shift_JIS/CP932 读取 UTF-8
+#   euc_kr    韩文环境按 EUC-KR 读取 UTF-8
+#   koi8_r    俄文/西里尔环境按 KOI8-R 读取 UTF-8
+CANDIDATES = [
+    ("gb18030", "UTF-8 被按 GBK/GB18030 误读"),
+    ("cp1252", "UTF-8 被按 CP1252 误读"),
+    ("latin-1", "UTF-8 被按 Latin-1(ISO-8859-1) 误读"),
+    ("shift_jis", "UTF-8 被按 Shift_JIS/CP932 误读"),
+    ("euc_kr", "UTF-8 被按 EUC-KR 误读"),
+    ("koi8_r", "UTF-8 被按 KOI8-R 误读"),
+]
+
+# 汉字集合（CJK 扩展 A + 统一表意 + 兼容表意）—— 还原文本“汉字量”判断用
+_HAN_RE = re.compile(r"[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]")
+
+
+def _roundtrip(enc, text):
+    """单候选 round-trip 反推。encode 失败（该编码不可能误读出此文本）返回 None。"""
+    try:
+        raw = text.encode(enc)
+    except UnicodeEncodeError:
+        return None
+    try:
+        recovered = raw.decode("utf-8")
+        mode = "strict"
+        loss = 0
+    except UnicodeDecodeError:
+        recovered = raw.decode("utf-8", errors="replace")
+        mode = "replace"
+        loss = recovered.count("\ufffd")
+    return {
+        "recovered": recovered,
+        "mode": mode,
+        "loss": loss,
+        "han": len(_HAN_RE.findall(recovered)),
+    }
+
+
+def detect_mojibake(text):
+    """命中返回 (encoding, label, recovered)，否则 None。"""
+    for enc, label in CANDIDATES:
+        r = _roundtrip(enc, text)
+        if r is None or r["recovered"] == text:
+            continue
+        if r["han"] >= 2 and r["loss"] <= r["han"]:
+            return enc, label, r["recovered"]
+    return None
+
+
+def _clean_preview(text, limit=72):
+    out = []
+    for ch in text:
+        if ch == "\ufffd":
+            continue
+        o = ord(ch)
+        if o < 32 and ch not in "\t\n":
+            continue
+        out.append(ch)
+    return "".join(out)[:limit]
+
+
+def _debug_report(text, valid_utf8):
+    sys.stderr.write("commit-msg 校验 --debug：\n")
+    if not valid_utf8:
+        sys.stderr.write("  文本非合法 UTF-8，round-trip 检测跳过（硬性检查已拒绝）\n")
+        return
+    for enc, label in CANDIDATES:
+        r = _roundtrip(enc, text)
+        if r is None:
+            sys.stderr.write("  %-9s %s\n" % (enc, "encode 失败——不可能为该编码误读产物"))
+            continue
+        same = r["recovered"] == text
+        hit = (not same and r["han"] >= 2 and r["loss"] <= r["han"])
+        verdict = "命中" if hit else ("还原=原文" if same else "未命中")
+        sys.stderr.write(
+            "  %-9s %s decode=%s han=%d loss=%d %s\n"
+            % (enc, r["mode"], verdict, r["han"], r["loss"], label)
+        )
+        if hit:
+            sys.stderr.write("      反推还原：%s\n" % _clean_preview(r["recovered"]))
+
+
+def check(path, debug=False):
+    with open(path, "rb") as f:
+        raw = f.read()
+    problems = []
+
+    if b"\x00" in raw:
+        problems.append("包含 NUL 字节")
+
+    try:
+        text = raw.decode("utf-8")
+        valid_utf8 = True
+    except UnicodeDecodeError as e:
+        problems.append("不是合法 UTF-8：%s" % e)
+        text = raw.decode("utf-8", errors="replace")
+        valid_utf8 = False
+
+    if "\ufffd" in text:
+        problems.append("含替换符 U+FFFD（编码损坏标记）")
+
+    if any("\ue000" <= ch <= "\uf8ff" for ch in text):
+        problems.append("含私有区字符 U+E000..U+F8FF（编码损坏迹象）")
+
+    if debug:
+        _debug_report(text, valid_utf8)
+
+    if valid_utf8:
+        hit = detect_mojibake(text)
+        if hit:
+            enc, label, recovered = hit
+            preview = _clean_preview(recovered)
+            problems.append(
+                "%s：round-trip 反推可还原为「%s%s」"
+                % (label, preview, "…" if len(recovered) > 72 else "")
+            )
+
+    if problems:
+        for p in problems:
+            sys.stderr.write("commit-msg 校验未通过：%s\n" % p)
+        sys.stderr.write(
+            "提示：Windows 下提交中文信息请走 UTF-8 文件方式，例如\n"
+            "  git commit -F .git/commit-msg.tmp\n"
+            "不要把中文直接写在命令行 -m 参数里。\n"
+        )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    debug = False
+    if args and args[0] == "--debug":
+        debug = True
+        args = args[1:]
+    if len(args) < 1:
+        sys.stderr.write("usage: commit_msg_check.py [--debug] <commit-msg-file>\n")
+        sys.exit(2)
+    sys.exit(check(args[0], debug=debug))

quant1x-0.8.0/.githooks/pre-commit

@@ -0,0 +1,45 @@
+#!/bin/sh
+# pre-commit 钩子：提交内容编码校验（新混入 BOM → 拒绝提交）
+# 校验逻辑见同目录 text_check.py
+hook_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+run_check() {
+    # 优先使用 python / python3；在 Windows 环境下回退到 py -3
+    if command -v python >/dev/null 2>&1; then
+        python -V >/dev/null 2>&1
+        probe=$?
+        if [ "$probe" -ne 126 ] && [ "$probe" -ne 127 ]; then
+            python "$hook_dir/text_check.py"
+            return $?
+        fi
+    fi
+    if command -v python3 >/dev/null 2>&1; then
+        python3 -V >/dev/null 2>&1
+        probe=$?
+        if [ "$probe" -ne 126 ] && [ "$probe" -ne 127 ]; then
+            python3 "$hook_dir/text_check.py"
+            return $?
+        fi
+    fi
+    if command -v py >/dev/null 2>&1; then
+        py -3 -V >/dev/null 2>&1
+        probe=$?
+        if [ "$probe" -ne 126 ] && [ "$probe" -ne 127 ]; then
+            py -3 "$hook_dir/text_check.py"
+            return $?
+        fi
+    fi
+    return 127
+}
+
+run_check
+check_rc=$?
+if [ "$check_rc" -eq 127 ]; then
+    echo "pre-commit 校验未通过：未找到可用 Python 解释器（python/python3/py -3）。" >&2
+    exit 1
+fi
+if [ "$check_rc" -ne 0 ]; then
+    echo "pre-commit 校验未通过，提交已中止。请去掉新混入的 BOM 后重试。" >&2
+    exit 1
+fi
+
+exit 0

quant1x-0.8.0/.githooks/text_check.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2026 Quant1X <wangfengxy@sina.cn>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+"""pre-commit 校验：拦截混进本次提交内容的 BOM。
+
+仓库一律 UTF-8 无 BOM —— 规定见 AGENTS.md 的「文件编码与行尾约定」。这东西肉眼
+不可见，Markdown 预览里往往也不显示，靠事后自查容易漏，故在提交这道口子上堵住。
+
+**为什么只查新增行，不扫整个文件**：CHANGELOG.md 现存 17 处行首 U+FEFF，是历史
+事实，已明确不予追溯修正。若钩子扫全文件，那么每改动一次该文件都会被拦下 ——
+规矩一旦扰民，最后的结果只会是被 `--no-verify` 绕过去。故这里只检查**本次提交
+新引入的行**：既往的不良留在原地不动，新的一个也不许进来。
+
+**为什么不查 CRLF**：行尾已由 `.gitattributes` 的 `text eol=lf` 兜住 —— 实测带
+CRLF 的文件 add 进暂存区时 git 就归一成了 LF，并打印 `CRLF will be replaced by
+LF`。钩子重复那一层只是徒增啰嗦，故不管。
+
+**如何取新增行**：`git diff --cached -U0 -- <文件>`，取以 `+` 开头且非 `+++`
+文件头的那些行。附带的好处是：二进制文件 git 只输出 `Binary files ... differ`
+而不产生 `+` 行，故无需另行判断是否二进制。
+
+**例外**：`.bat` / `.cmd` 整体豁免 —— 它们是 Windows 批处理，形态自成一格。
+
+用法：
+    python text_check.py
+返回 0 通过；非 0 拒绝（信息输出到 stderr）。
+"""
+import subprocess
+import sys
+
+BOM = b"\xef\xbb\xbf"
+
+# Windows 批处理整体豁免, 见 AGENTS.md 的文件编码与行尾约定
+EXEMPT_SUFFIXES = (".bat", ".cmd")
+
+
+def _git(args, binary=False):
+    """执行 git 子命令。失败即抛, 让钩子明确报错而不是静默放过。"""
+    proc = subprocess.run(
+        ["git"] + args, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(
+            "git %s 失败: %s" % (" ".join(args), proc.stderr.decode("utf-8", "replace"))
+        )
+    return proc.stdout if binary else proc.stdout.decode("utf-8", "replace")
+
+
+def staged_files():
+    """本次待提交(新增/复制/修改)的文件列表; -z 分隔, 文件名带空格也拆不开。"""
+    out = _git(["diff", "--cached", "--name-only", "-z", "--diff-filter=ACM"])
+    return [f for f in out.split("\0") if f]
+
+
+def added_lines(path):
+    """本次提交在该文件里新增的行(字节), 去掉 diff 的 `+` 号与 `+++` 文件头。"""
+    raw = _git(["diff", "--cached", "-U0", "--", path], binary=True)
+    return [
+        line[1:]
+        for line in raw.split(b"\n")
+        if line.startswith(b"+") and not line.startswith(b"+++")
+    ]
+
+
+def scan(path):
+    """本次新增行里的 BOM 数。"""
+    return sum(line.count(BOM) for line in added_lines(path))
+
+
+def main():
+    offenders = []
+    for path in staged_files():
+        if path.lower().endswith(EXEMPT_SUFFIXES):
+            continue
+        bom = scan(path)
+        if bom:
+            offenders.append((path, bom))
+
+    if not offenders:
+        return 0
+
+    sys.stderr.write("pre-commit 校验未通过：下列文件**本次新增的行**混进了 BOM\n\n")
+    for path, bom in offenders:
+        sys.stderr.write("  %s  BOM=%d\n" % (path, bom))
+    sys.stderr.write(
+        "\nU+FEFF 多半是某次编辑把自带 BOM 的一段文本拼接进来的 —— 它肉眼看不见,\n"
+        "所见只是 `- ` 与正文之间多了个位置。修法见 AGENTS.md 的「文件编码与行尾约定」。\n"
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{quant1x-0.7.62.dev2 → quant1x-0.8.0}/.gitignore

@@ -20,6 +20,9 @@ dist/
 *.egg-info/
 
 *.png
+# 应用与网站图标是交付物, 需入库 (由 scripts/gen_icons.py 从 logo.png 生成)
+!assets/icons/**/*.png
+
 *.pkl
 
 #visual studio
@@ -42,7 +45,10 @@ target/
 .env
 
 # vscode
-.vscode/launch.json
+.vscode/
 
 # setuptools_scm generated version file
 _version.py
+
+# Maven Wrapper 下载缓存（首次运行自动下载，不入库）
+.mvn/

{quant1x-0.7.62.dev2/.vscode → quant1x-0.8.0/.vscode-default}/c_cpp_properties.json

@@ -7,4 +7,4 @@
         }
     ],
     "version": 4
-}
+}

{quant1x-0.7.62.dev2/.vscode → quant1x-0.8.0/.vscode-default}/settings.json

@@ -1,13 +1,58 @@
 {
+    // ===== 编辑器与字体 (VS Code 内置) =====
+    "editor.fontFamily": "'Source Code Pro', 'Courier New', monospace",
+    "editor.fontVariations": false,
+    "editor.inlayHints.fontFamily": "",
+    "editor.inlineSuggest.fontFamily": "'Source Code Pro', 'Courier New', monospace",
+    "debug.console.fontFamily": "'Source Code Pro', 'Courier New', monospace",
+    "chat.editor.fontFamily": "default",
+    "chat.fontFamily": "default",
+
+    // ===== 终端 (VS Code 内置) =====
+    "terminal.integrated.fontFamily": "'FiraCode Nerd Font Mono', 'Courier New', monospace",
+    "terminal.integrated.scrollback": 10000,
+
+    // ===== Python =====
+    "python.analysis.autoImportCompletions": true,
+    "python.envFile": "${workspaceFolder}/.env",
+
+    // ===== Go =====
+    "go.diagnostic.vulncheck": "Imports",
+
+    // ===== CMake =====
+    "cmake.launchBehavior": "reuseTerminal",
+    "cmake.buildDirectory": "${workspaceFolder}/build",
+    "cmake.configureSettings": {
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+        "CMAKE_BUILD_TYPE": "Debug"
+    },
+    // "cmake.configureArgs": [
+    //     "-DVCPKG_PREFER_SYSTEM_LIBS=OFF",
+    //     "-DVCPKG_MANIFEST_MODE=OFF"
+    // ],
+    "cmake.buildArgs": [
+        "--config",
+        "Debug"
+    ],
+
+    // ===== vcpkg =====
+    // triplet 与工具链路径随平台, 见 .vscode-windows / .vscode-macos
+    //"vcpkg.general.enable": true,
+    //"vcpkg.target.useStaticLib": false,
+    //"vcpkg.target.installDependencies": true,
+    //"vcpkg.target.preferSystemLibs": false,
+    //"vcpkg.target.useManifest": false,
+
+    // ===== C++ 测试 (C++ TestMate) =====
     "testMate.cpp.test.advancedExecutables": [
         {
-            // macOS / Linux: executables produced by CMake usually have no extension
+            // macOS / Linux: 可执行文件通常无扩展名
             "pattern": "build/tests/catch2-*",
             "cwd": "${workspaceFolder}",
             "env": {}
         },
         {
-            // Windows: keep the existing .exe pattern
+            // Windows: 保留 .exe 模式
             "pattern": "build/tests/catch2-*.exe",
             "cwd": "${workspaceFolder}",
             "env": {}
@@ -25,7 +70,7 @@
                 "ASAN_OPTIONS": "detect_leaks=1",
                 "LSAN_OPTIONS": "suppressions=leaksanitizer.supp",
                 "DYLD_LIBRARY_PATH": "${command:cmake.buildDirectory}/lib"
-            },
+            }
         },
         "win32": {
             "type": "cppdbg"
@@ -34,33 +79,13 @@
         "program": "${exec}",
         "args": "${argsArray}",
         "cwd": "${command:cmake.launchTargetDirectory}",
-        "sourceFileMap": "${sourceFileMapObj}",
+        "sourceFileMap": "${sourceFileMapObj}"
     },
     "testMate.cpp.debug.noThrow": false,
-    "python.analysis.autoImportCompletions": true,
-    "python.envFile": "${workspaceFolder}/.env",
-    "cmake.buildDirectory": "${workspaceFolder}/build",
-    "cmake.configureSettings": {
-        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
-        "CMAKE_BUILD_TYPE": "Debug"
-    },
-    "cmake.buildArgs": [
-        "--config",
-        "Debug"
-    ],
-    "cmake.launchBehavior": "reuseTerminal",
-    "terminal.integrated.fontFamily": "'FiraCode Nerd Font Mono', 'Courier New', monospace",
-    "debug.console.fontFamily": "'Source Code Pro', 'Courier New', monospace",
-    "editor.inlayHints.fontFamily": "",
-    "editor.fontVariations": false,
-    "editor.fontFamily": "'Source Code Pro', 'Courier New', monospace",
-    "editor.inlineSuggest.fontFamily": "'Source Code Pro', 'Courier New', monospace",
-    "chat.editor.fontFamily": "default",
-    "chat.fontFamily": "default",
-    "terminal.integrated.scrollback": 10000,
-    "go.diagnostic.vulncheck": "Imports",
+
+    // ===== 代码运行 (Code Runner) =====
     "code-runner.executorMap": {
-    "python": "python scripts/run_module.py $fullFileName"
+        "python": "python scripts/run_module.py $fullFileName"
     },
-    "code-runner.runInTerminal": true,
-}
+    "code-runner.runInTerminal": true
+}

quant1x-0.8.0/.vscode-macos/settings.json

@@ -0,0 +1,11 @@
+{
+    // ===== Python =====
+    "python-envs.defaultEnvManager": "ms-python.python:pyenv",
+
+    // ===== CMake =====
+    // CMakeLists.txt 在 DEFINED ENV{VCPKG_ROOT} 缺失时 FATAL_ERROR, 故显式给出根目录,
+    // 不依赖外部终端环境。
+    // "cmake.configureEnvironment": {
+    //     "VCPKG_ROOT": "/Users/wangfeng/runtime/vcpkg"
+    // }
+}

quant1x-0.8.0/.vscode-windows/launch.json

@@ -0,0 +1,12 @@
+{
+    "configurations": [
+        {
+            "type": "cmake",
+            "request": "launch",
+            "name": "Debug portfile(s)",
+            "cmakeDebugType": "external",
+            "pipeName": "\\\\.\\pipe\\vcpkg_ext_portfile_dbg",
+            "preLaunchTask": "Debug vcpkg commands"
+        }
+    ]
+}

quant1x-0.8.0/.vscode-windows/settings.json

@@ -0,0 +1,19 @@
+{
+    // ===== vcpkg =====
+    // CMakeLists.txt 在 DEFINED ENV{VCPKG_ROOT} 缺失时 FATAL_ERROR, 故显式给出根目录,
+    // 不依赖外部终端环境; 工具链文件由同一根目录推导。
+    //"vcpkg.general.vcpkgPath": "d:\\runtime\\vcpkg",
+    // "vcpkg.target.hostTriplet": "x64-mingw-static",
+    // "vcpkg.target.defaultTriplet": "x64-mingw-static",
+
+    // ===== CMake =====
+    // "cmake.configureEnvironment": {
+    //     "VCPKG_ROOT": "d:\\runtime\\vcpkg"
+    // },
+    // "cmake.configureSettings": {
+    //     "CMAKE_TOOLCHAIN_FILE": "d:\\runtime\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake"
+    // }
+
+    // triplet 由 CMakeLists.txt 按编译器判定并以 FORCE 写入缓存, 此处不再重复指定:
+    // MinGW/GNU -> x64-mingw-static, MSVC/Clang -> x64-windows-static
+}

{quant1x-0.7.62.dev2 → quant1x-0.8.0}/AGENTS.md

@@ -17,6 +17,9 @@
 - Go 实现必须位于功能子目录中，例如 `data/t1/`
 - Go 包名必须与目录名完全一致（如 `package t1`）
 - **禁止**为了"方便"合并 Go 文件到根目录
+- Java 测试文件的 `package` 必须与 `tests/` 作为源码根目录时的目录层级一致；不应额外增加 `quant1x` 顶层包，但也不能省略 `tests` 根层级，例如 `tests/distributed/id` 对应 `package tests.distributed.id`
+- 若 IDE/编译器提示 `The declared package "distributed.id" does not match the expected package "tests.distributed.id"`，这是错误配置；必须修正为 `tests` 目录根层级与 package 一致，并禁止在 Java 测试里人为多加 `quant1x.` 这一层
+- 任何新增 Java 类/测试都必须遵循“模块目录 == package 层级（相对 tests 根目录）”的规则，避免出现 `quant1x.distributed.id`、`distributed.id` 这种与 `tests/` 根层级不一致的命名
 
 ## 三、命名规则
 
@@ -188,6 +191,71 @@ type Bar struct {
   - ❌ 在代码或提交信息中自行推断版本号
   - ❌ 修改 `CHANGELOG.md`、`pyproject.toml`、`Cargo.toml` 中的 `version` 字段
 
+## 提交信息规范
+
+- Git commit 的主题和正文必须使用中文，准确说明本次变更内容。
+- 提交信息不得自行添加版本号、Git Tag 或发布相关信息。
+- 所有代码变更（新特性、Bug 修复、重构、测试、文档、性能优化等）必须在提交主题中显式标注涉及的开发语言，确保多语言语义一致的审计性。
+- 主题必须采用统一模板：`<type>[<language>]：<summary>`。
+- `<type>` 取值建议：`feat`（新特性）、`fix`（修复）、`refactor`（重构）、`test`（测试）、`perf`（性能）、`docs`（文档）、`chore`（例行维护）。
+- `<language>` 允许值：`python`、`cpp`、`rust`、`go`、`multi`。若涉及多个语言，使用 `python+cpp`、`python+rust+go` 等形式，优先按语义顺序书写：`python+cpp` > `python+cpp+rust+go`。
+- 若是一处跨语言同步改动，正文必须补充：
+  1. 变更概述；
+  2. 涉及语言与文件范围；
+  3. 语义一致性说明；
+  4. 验证方式/测试命令。
+- 主题中禁止仅写“update / optimize / fix”这类空泛描述，必须指明对象和语言，例如：
+  - `feat[python]：为 runtime ringbuffer 增加原生 Python 语义实现`
+  - `fix[cpp+rust]：修正 vyukov 退避策略与 arm64 调度兼容性`
+  - `test[python]：补充 ringbuffer 回归测试覆盖 close 与 wait_for_close`
+  - `docs[multi]：同步更新 ringbuffer 契约与跨语言语义说明`
+- 若某次提交仅修改单一语言，主题中必须明确写出该语言；若跨语言同步提交，则必须写 `multi` 或多个语言组合；不得出现“无语言标记”的提交信息。
+- 主题和正文都应优先使用中文，必要时保留英文术语（如 `RingBuffer`、`QueueFullError`、`try_push`）作为对象标识。
+- 提交信息必须保持可审计、可分组、可检索，方便后续基于语言维度筛选 commit。
+
+示例：
+
+```text
+feat[python]：为 runtime ringbuffer 增加原生 Python 语义实现
+
+- 新增 quant1x/runtime/ringbuffer.py，保留 try_push / try_pop / push / pop / close / wait_for_close 语义
+- 目标为与 Go/C++/Rust 的 spec 契约保持一致，避免 Python 侧语义漂移
+- 验证：PYTHONPATH=. python -m unittest quant1x.runtime.ringbuffer_test
+```
+
+```text
+fix[cpp+rust]：修正 vyukov 退避策略，消除 arm64 争抢下的 convoy 效应
+
+- 调整 backoff 退避策略，统一 C++ 与 Rust 的调度行为
+- 重点修复 aarch64 上 yield/isb 差异导致的性能退化
+- 说明：该修复仅影响调度策略，不改变 ringbuffer 语义契约
+- 验证：cargo bench --bench vyukov_bench
+```
+
+```text
+test[python+go]：补充 ringbuffer 语义回归测试，覆盖 close 与阻塞等待行为
+
+- 以 Python 作为 spec 锚点，Go 侧对齐测试语义
+- 验证：python -m unittest quant1x.runtime.ringbuffer_test
+```
+
+### 提交前检查清单（Checklist）
+
+在执行 `git commit` 之前，AI 必须逐项核对：
+
+- [ ] 主题是否符合 `type[language]：summary` 模板？
+- [ ] `type` 是否真实反映本次变更类型（feat / fix / refactor / test / perf / docs / chore）？
+- [ ] `language` 是否准确标明本次涉及的开发语言，未标注或误标注均视为不合规？
+- [ ] 若涉及多语言，是否使用 `python+cpp`、`python+rust+go` 等组合形式，而非笼统写 `multi`？
+- [ ] 标题是否避免“update / optimize / fix”这类空泛描述，是否明确对象和影响？
+- [ ] 正文是否包含：变更概述、涉及语言与文件范围、语义一致性说明、验证方式/命令？
+- [ ] 若为跨语言同步改动，是否说明了语义一致性与测试验证方式？
+- [ ] 是否未包含版本号、Git Tag、发布相关字符串？
+- [ ] 是否使用中文为主，必要时保留英文术语作为对象标识？
+- [ ] 是否能在审计时根据语言维度快速过滤和回溯？
+
+提交未满足以上任一项，必须在提交前修正，不能直接提交。
+
 ## 十、一句话总结（给 AI 的记忆锚点）
 
 > Quant1X 是多语言语义同构系统，Python 是 Spec，C++ 是 Truth，Rust / Go 是对齐实现，I/O 边界死守 `snake_case`。