Merge pull request #7050 from DDSRem-Dev/codex-comment-migration

docs: 统一全项目中文注释和结构化契约说明

scripts/release_notes.py

@@ -1,4 +1,6 @@
-"""发布工作流使用的原始提交记录生成器，不分类或改写提交标题。"""
+"""
+发布工作流使用的原始提交记录生成器，不分类或改写提交标题。
+"""
 
 import argparse
 import json
@@ -12,12 +14,16 @@ from urllib.parse import quote
 
 
 def command(*args: str) -> str:
-    """以参数列表执行发布工具；查询失败时终止，避免发布不完整记录。"""
+    """
+    以参数列表执行发布工具；查询失败时终止，避免发布不完整记录。
+    """
     return subprocess.run(args, check=True, capture_output=True, text=True).stdout
 
 
 def previous_tag(tag: str) -> str | None:
-    """选取低于当前版本的最近正式标签，兼容历史数字修订后缀，排除本版本和命名预发布标签。"""
+    """
+    选取低于当前版本的最近正式标签，兼容历史数字修订后缀，排除本版本和命名预发布标签。
+    """
     version = re.fullmatch(r"v(\d+)\.(\d+)\.(\d+)(?:-(\d+))?", tag)
     if version is None:
         raise ValueError(f"不支持的正式版本标签：{tag}")
@@ -33,7 +39,9 @@ def previous_tag(tag: str) -> str | None:
 
 
 def collect_commits(repository: str, source: str, previous: str | None) -> list[dict[str, Any]]:
-    """分页读取指定发布范围的提交及真实 GitHub 作者账号，支持直接提交。"""
+    """
+    分页读取指定发布范围的提交及真实 GitHub 作者账号，支持直接提交。
+    """
     if previous:
         endpoint = f"repos/{repository}/compare/{quote(previous, safe='')}...{source}?per_page=100"
         pages = json.loads(command("gh", "api", "--paginate", "--slurp", endpoint))
@@ -47,7 +55,9 @@ def collect_commits(repository: str, source: str, previous: str | None) -> list[
 
 
 def changelog(commits: list[dict[str, Any]]) -> str:
-    """保留提交标题、作者与链接，仅排除合并和自动发布快照，不合并同名提交。"""
+    """
+    保留提交标题、作者与链接，仅排除合并和自动发布快照，不合并同名提交。
+    """
     entries = []
     seen = set()
     for commit in commits:
@@ -69,7 +79,9 @@ def changelog(commits: list[dict[str, Any]]) -> str:
 
 
 def manual_summary(body: str) -> str:
-    """保留手工摘要及内部 Markdown；旧版自动记录不迁入用户摘要。"""
+    """
+    保留手工摘要及内部 Markdown；旧版自动记录不迁入用户摘要。
+    """
     match = re.search(r"^## 本次更新内容[ \t]*\r?$", body, re.MULTILINE)
     if match:
         remaining = body[match.end():]
@@ -81,7 +93,9 @@ def manual_summary(body: str) -> str:
 
 
 def release_body(summary: str, records: str, repository: str, previous: str | None, tag: str) -> str:
-    """生成后端固定三章节；首版无比较起点时仅保留空的版本对比章节。"""
+    """
+    生成后端固定三章节；首版无比较起点时仅保留空的版本对比章节。
+    """
     comparison = ""
     if previous:
         url = f"https://github.com/{repository}/compare/{previous}...{tag}"
@@ -90,7 +104,9 @@ def release_body(summary: str, records: str, repository: str, previous: str | No
 
 
 def main() -> None:
-    """向发布工作流传递完整正文；前端模式仅输出原始 changelog。"""
+    """
+    向发布工作流传递完整正文；前端模式仅输出原始 changelog。
+    """
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--repository", required=True)
     parser.add_argument("--tag", required=True)