docs: 将仓库代码注释统一为中文

2026-09-10 00:40:56 +08:00
parent 51c592841d
commit d703ab64e3
249 changed files with 707 additions and 900 deletions
@@ -1,4 +1,4 @@
-"""A-02 authenticated Core transport and secret-exposure acceptance driver."""
+"""A-02：Core 认证传输与机密泄露验收驱动。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""A-03 protocol, transport-limit, cancellation, and commit acceptance driver."""
+"""A-03：协议、传输限制、取消与提交验收驱动。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""B-01 scoped Stronghold and plaintext-exposure acceptance driver."""
+"""B-01：限定作用域的 Stronghold 与明文泄露验收驱动。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""B-02 Fernet-to-Stronghold migration acceptance driver."""
+"""B-02：Fernet 到 Stronghold 的迁移验收驱动。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""B-03 credential locking, password rotation, recovery, and edit availability."""
+"""B-03：凭据锁定、密码轮换、恢复与编辑可用性验收。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""B-04 transactional credential migration and confirmed cleanup oracle."""
+"""B-04：事务化凭据迁移与确认清理的判定器。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""C-03 execution-permit binding and legacy-launch rejection oracle."""
+"""C-03：执行许可绑定与旧版启动拒绝判定器。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""D-01 signed package, ZIP limits, and safe extraction acceptance driver."""
+"""D-01：签名包、ZIP 限制与安全解压验收驱动。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""D-03 crash, storage, configuration, dependency, and permission acceptance."""
+"""D-03：崩溃、存储、配置、依赖与权限验收。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""S-01 two-client offline chain and idempotent response-loss driver."""
+"""S-01：双客户端离线链与响应丢失幂等性验收驱动。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""S-02 resumable attachment and pull-boundary crash driver."""
+"""S-02：附件断点续传与拉取边界崩溃验收驱动。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""S-03 conflict matrix, first-bind, and rebind isolation acceptance driver."""
+"""S-03：冲突矩阵、首次绑定与重新绑定隔离验收驱动。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""S-04 real PostgreSQL, MinIO, and two-worker transaction acceptance."""
+"""S-04：真实 PostgreSQL、MinIO 与双工作进程事务验收。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""S-05 upload durability and cleanup races on the production stack."""
+"""S-05：生产栈上的上传持久性与清理竞争验收。"""

 from __future__ import annotations

@@ -159,7 +159,7 @@ def drop_complete_response(url: str, authorization: str) -> None:
    with socket.create_connection((parsed.hostname, parsed.port), timeout=10) as stream:
        stream.sendall(request)
        stream.shutdown(socket.SHUT_WR)
-        # The request is complete, but the client deliberately never reads its response.
+        # 请求已完成，但客户端特意不读取其响应。
        time.sleep(0.01)


@@ -1,4 +1,4 @@
-"""S-06 authorization, revocation, rate-limit, and readiness acceptance."""
+"""S-06：授权、撤销、速率限制与就绪状态验收。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""S-07 empty deployment, backup/restore, and migration safety acceptance."""
+"""S-07：空部署、备份与恢复、迁移安全验收。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""S-08 sync classification and logical-record compatibility acceptance driver."""
+"""S-08：同步分类与逻辑记录兼容性验收驱动。"""

 from __future__ import annotations

@@ -1,4 +1,4 @@
-"""S-09 sustained load, bounded upload RSS, and initial-sync acceptance."""
+"""S-09：持续负载、有界上传 RSS 与首次同步验收。"""

 from __future__ import annotations

@@ -33,7 +33,7 @@ MAX_SCHEDULE_GAP_SECONDS = 1.0


 class WindowsExecutionGuard:
-    """Keep the benchmark host awake while wall-clock acceptance is running."""
+    """执行按实际时间计量的验收期间，保持基准测试主机唤醒。"""

    ES_CONTINUOUS = 0x80000000
    ES_SYSTEM_REQUIRED = 0x00000001
@@ -259,7 +259,7 @@ def run_memory_uploads(stack: SyncProductionStack, clients: list[dict]) -> dict:
            )
            time.sleep(NETWORK_RTT_SECONDS / 2)
            assert response[0] == 200 and response[1]["offset"] == offset + CHUNK
-            # Four equal streams share an aggregate 100 Mbps client-side ceiling.
+            # 四个相等的流共享总计 100 Mbps 客户端上限。
            delay = (CHUNK * 8 * 4 / 100_000_000) - (time.monotonic() - started)
            if delay > 0:
                time.sleep(delay)
@@ -1,4 +1,4 @@
-"""Isolated PostgreSQL, MinIO, and multi-worker Sync acceptance stack."""
+"""隔离的 PostgreSQL、MinIO 与多工作进程 Sync 验收栈。"""

 from __future__ import annotations

@@ -82,7 +82,7 @@ def stop_tree(process: subprocess.Popen | None) -> None:


 class SyncProductionStack:
-    """Own a disposable production dependency stack for one acceptance case."""
+    """拥有一个验收案例的一次性生产依赖堆栈。"""

    def __init__(self, config: dict, data_root: Path, case_tag: str):
        self.config = config
@@ -420,8 +420,7 @@ class SyncProductionStack:
            except (OSError, TimeoutError, URLError):
                return None

-        # A small pool is enough to reach both workers without exhausting the
-        # Windows ephemeral-port/backlog budget before the fault matrix starts.
+        # 一个小池足以覆盖两个工作线程，而不会在故障矩阵启动之前耗尽 Windows 临时端口/积压预算。
        with ThreadPoolExecutor(max_workers=8) as pool:
            return {value for value in pool.map(probe, range(attempts)) if value}

@@ -1,7 +1,7 @@
-"""Build an onedir Core from the frozen packaging environment, then inventory it.
+"""在冻结依赖的打包环境中构建 onedir Core，并生成文件清单。

-Run: uv run --directory backend --group packaging python ../scripts/build-core.py
-Outputs remain in this worktree's ignored .build directory.
+运行：uv run --directory backend --group packaging python ../scripts/build-core.py
+输出保留在当前工作树中已忽略的 .build 目录内。
 """
 from __future__ import annotations
 import hashlib
@@ -1,9 +1,4 @@
-"""Windows component measurements, not the S-09 service/release benchmark.
-
-Build the current Rust library test executable, then run each fixed workload in
-its own process. Reports observed OS cumulative peaks, with sampling coverage.
-No third-party Python packages required. Usage: python scripts/measure-sync-memory.py
-"""
+"""Windows 组件测量，不是 S-09 服务/发布基准。构建当前的 Rust 库测试可执行文件，然后在其自己的进程中运行每个固定工作负载。报告观察到OS累积峰值，具有采样覆盖率。无需第三方 Python 软件包。用法： python 脚本/measure-sync-memory.py"""
 from __future__ import annotations
 import argparse
 import ctypes as c
@@ -1,4 +1,4 @@
-"""Documented command entry point for the production acceptance runner."""
+"""生产验收执行器的命令入口。"""

 from phase3_acceptance import main

@@ -1,4 +1,4 @@
-"""Fail-closed runner for the OpenNexus phase-three production acceptance IDs."""
+"""OpenNexus 第三阶段生产验收 ID 的默认拒绝型执行器。"""

 from __future__ import annotations

@@ -30,8 +30,7 @@ CASE_SUITES = {
    "e2e": tuple(f"E-{number:02d}" for number in range(1, 6)),
 }
 ALL_CASES = tuple(case for cases in CASE_SUITES.values() for case in cases)
-# A case becomes executable only when a repository-owned driver is registered here.
-# Component/unit test commands are deliberately not treated as production acceptance.
+# 只有在此注册了仓库自有驱动的案例才能执行；组件或单元测试命令不计入生产验收。
 CASE_DRIVERS: dict[str, dict[str, Any]] = {
    "A-02": {
        "driver": "scripts/acceptance_cases/a02_sidecar.py",
@@ -202,7 +201,7 @@ MAX_LOG_BYTES = 10 * 1024 * 1024


 class AcceptanceError(ValueError):
-    """A stable, user-actionable runner configuration error."""
+    """一个稳定的、用户可操作的运行器配置错误。"""


 def _utc_now() -> str: