chore(release): 版本升到 0.1.1 + 版本号收敛为单一真源

为 v0.1.1 发版做准备。

版本号此前散落在 5 处（pyproject.toml / src/main.py 的 FastAPI(version=) /
web/package.json / README 的 docker pull 示例 / publish.yml 的示例文案），
升版必漏——`/openapi.json` 会报出与镜像 tag 不一致的版本，排查问题时误导。

- 新增 src/version.py：pyproject.toml 为唯一真源，运行时读取
  （tomllib，相对本文件定位项目根，容器里 /app/pyproject.toml 已 COPY）；
  读不到/内容损坏/字段缺失一律回落到 FALLBACK_VERSION，绝不抛异常
- src/main.py 的 FastAPI(version=) 改用 app_version()
- 升版 0.1.0 → 0.1.1：pyproject.toml、web/package.json、README、
  publish.yml 示例、FALLBACK_VERSION 同步
- 新增防漂移测试：断言五处版本一致，且 src/ 下不得再硬编码版本号

验证：965 测试 / 100% 行+分支覆盖；ruff、tsc、前端 104 测试全通过。

Author: RobbsLuo

.github/workflows/publish.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: '要打的版本号（如 v0.1.0，留空则跳过）'
+        description: '要打的版本号（如 v0.1.1，留空则跳过）'
         required: false
         default: ''
 

README.md

@@ -55,7 +55,7 @@ docker compose up -d
 
 ```bash
 docker compose pull
-# 或指定版本：docker pull ghcr.io/robbsluo/coding2api:v0.1.0
+# 或指定版本：docker pull ghcr.io/robbsluo/coding2api:v0.1.1
 ```
 
 推送新版本：打 tag `v*` 推到 main 即触发 publish workflow（见 `.github/workflows/publish.yml`），同时打 `<tag>` 和 `:latest` 到 GHCR。也可在 Actions 页面手动触发（填版本号）。

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "coding2api"
-version = "0.1.0"
+version = "0.1.1"
 description = "把 CodeBuddy 与 TRAE SOLO 上游通道统一封装为 OpenAI 兼容 API"
 readme = "README.md"
 requires-python = ">=3.12"

src/main.py

@@ -42,6 +42,7 @@
 from .stats.query import StatsQuery
 from .tasks.pacer import Pacer
 from .tasks.runner import build_runner
+from .version import app_version
 from .webapp import limits as _limits
 from .webapp import static as _static
 from .webapp.handlers import register_exception_handlers
@@ -177,7 +178,7 @@ async def lifespan(app_: FastAPI):
                     await closer()
             db.close()
 
-    app = FastAPI(title="Coding2API", version="0.1.0", lifespan=lifespan)
+    app = FastAPI(title="Coding2API", version=app_version(), lifespan=lifespan)
     # BodySizeLimitMiddleware 必须在最外层：FastAPI.add_middleware 会把后加
     # 的包在更外层，所以它在最后添加（见 build_app 末尾）。
     app.state.settings = config

src/version.py

@@ -0,0 +1,34 @@
+"""单一版本源：一切对外暴露的版本号都从这里取。
+
+此前版本号散落在 5 处（pyproject.toml / src/main.py 的 FastAPI(version=) /
+web/package.json / README 的 docker pull 示例 / publish.yml 的提示文案），
+升版时必漏——`/openapi.json` 会报出与镜像 tag 不一致的版本，排查问题时误导。
+
+规则：**pyproject.toml 是唯一真源**，运行时读取；读不到时（精简镜像、测试临时
+目录）回落到已发布版本号，绝不抛异常——版本号是展示信息，不该让服务起不来。
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+# 回落值：仅在读不到 pyproject.toml 时使用。升版时与 pyproject 一起改。
+FALLBACK_VERSION = "0.1.1"
+
+# 相对本文件定位项目根：src/version.py → 上一级即项目根
+_PYPROJECT = Path(__file__).resolve().parent.parent / "pyproject.toml"
+
+
+@lru_cache(maxsize=1)
+def app_version() -> str:
+    """读取项目版本号（pyproject.toml 为唯一真源，读不到则回落）。"""
+    import tomllib
+
+    try:
+        with _PYPROJECT.open("rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, ValueError):
+        return FALLBACK_VERSION
+    version = data.get("project", {}).get("version")
+    return version if isinstance(version, str) and version else FALLBACK_VERSION

tests/test_deployment_assets.py

@@ -273,3 +273,43 @@ def test_webapp_logging_module_does_not_open_files():
     assert "RotatingFileHandler" not in src
     assert "FileHandler" not in src
     assert "StreamHandler" in src
+
+
+def test_version_is_single_sourced_everywhere():
+    """版本号必须处处一致：pyproject（真源）/ 前端 / 回落常量 / README / publish 示例。
+
+    此前这些位置各写一遍，升版必漏——`/openapi.json` 会报出与镜像 tag 不同的
+    版本，排查问题时误导。这条测试就是防止再漂移。
+    """
+    import json
+    import re
+    import tomllib
+    from pathlib import Path
+
+    from src.version import FALLBACK_VERSION, app_version
+
+    root = Path(__file__).resolve().parent.parent
+    with (root / "pyproject.toml").open("rb") as handle:
+        canonical = tomllib.load(handle)["project"]["version"]
+    assert app_version() == canonical
+
+    package_json = json.loads((root / "web" / "package.json").read_text(encoding="utf-8"))
+    assert package_json["version"] == canonical, "web/package.json 版本未同步"
+
+    assert canonical == FALLBACK_VERSION, "src/version.py 回落值未同步"
+
+    readme = (root / "README.md").read_text(encoding="utf-8")
+    pulls = re.findall(r"coding2api:v(\d+\.\d+\.\d+)", readme)
+    assert pulls, "README 里找不到带版本的 docker pull 示例"
+    assert set(pulls) == {canonical}, "README 的 docker pull 示例版本未同步"
+
+    publish = (root / ".github" / "workflows" / "publish.yml").read_text(encoding="utf-8")
+    examples = re.findall(r"如 v(\d+\.\d+\.\d+)", publish)
+    assert set(examples) == {canonical}, "publish.yml 的示例版本未同步"
+
+    # 源码里不得再出现硬编码的版本号（除了单一版本源自己的回落常量）
+    for path in (root / "src").rglob("*.py"):
+        if path.name == "version.py":
+            continue
+        text = path.read_text(encoding="utf-8")
+        assert f'version="{canonical}"' not in text, f"{path} 硬编码了版本号"

tests/test_m0_coverage.py

@@ -209,3 +209,75 @@ def test_database_skips_mkdir_for_bare_filename(tmp_path, monkeypatch):
     apply_schema(database.connect())
     assert (tmp_path / "bare.sqlite3").exists()
     database.close()
+
+
+# --------------------------------------------------------- 单一版本源
+
+def test_app_version_reads_pyproject():
+    """版本号从 pyproject.toml 读取（唯一真源），与 tag 同源。"""
+    import tomllib
+
+    from src.version import app_version
+
+    with open("pyproject.toml", "rb") as handle:
+        expected = tomllib.load(handle)["project"]["version"]
+    assert app_version() == expected
+    # 带 v 前缀的 tag 去掉 v 后应与之一致（发布流程靠这个对齐）
+    assert expected.count(".") == 2 and not expected.startswith("v")
+
+
+def test_app_version_falls_back_when_pyproject_missing(monkeypatch, tmp_path):
+    """读不到 pyproject 时回落到常量，绝不抛异常（版本号不该让服务起不来）。"""
+    import src.version as version_module
+
+    monkeypatch.setattr(version_module, "_PYPROJECT", tmp_path / "nope.toml")
+    version_module.app_version.cache_clear()
+    try:
+        assert version_module.app_version() == version_module.FALLBACK_VERSION
+    finally:
+        version_module.app_version.cache_clear()
+
+
+def test_app_version_falls_back_on_corrupt_pyproject(monkeypatch, tmp_path):
+    """pyproject 内容损坏（非法 TOML）同样回落，不抛异常。"""
+    import src.version as version_module
+
+    broken = tmp_path / "pyproject.toml"
+    broken.write_text("this is not = = toml", encoding="utf-8")
+    monkeypatch.setattr(version_module, "_PYPROJECT", broken)
+    version_module.app_version.cache_clear()
+    try:
+        assert version_module.app_version() == version_module.FALLBACK_VERSION
+    finally:
+        version_module.app_version.cache_clear()
+
+
+def test_app_version_falls_back_on_missing_or_blank_field(monkeypatch, tmp_path):
+    """缺 [project].version、版本为空串、version 非字符串 → 全部回落。"""
+    import src.version as version_module
+
+    for content in ('[project]\nname = "x"\n',
+                    '[project]\nversion = ""\n',
+                    '[project]\nversion = 123\n'):
+        broken = tmp_path / "pyproject.toml"
+        broken.write_text(content, encoding="utf-8")
+        monkeypatch.setattr(version_module, "_PYPROJECT", broken)
+        version_module.app_version.cache_clear()
+        try:
+            assert version_module.app_version() == version_module.FALLBACK_VERSION
+        finally:
+            version_module.app_version.cache_clear()
+
+
+def test_app_version_is_cached():
+    """重复调用只解析一次（lru_cache）。"""
+    from src.version import app_version
+
+    assert app_version() is app_version()
+
+
+def test_openapi_reports_app_version():
+    """FastAPI 的 version 必须来自单一版本源（此前硬编码 0.1.0 会与 tag 漂移）。"""
+    from src.main import app_version
+
+    assert app_version()  # 可调用且非空（main 里的 import 绑定没断）

uv.lock

@@ -1,7 +1,7 @@
 {
   "name": "coding2api-web",
   "private": true,
-  "version": "0.1.0",
+  "version": "0.1.1",
   "packageManager": "pnpm@10.18.0",
   "type": "module",
   "scripts": {