建立版本管理体系:CHANGELOG + bump 脚本 + pyproject 元数据 + 一致性测试

新增:
- CHANGELOG.md:Keep a Changelog 1.1.0 格式,回填 V3.0.0–V3.3.3 历史
- tools/dev/bump_version.py:一键 bump major/minor/patch,
  同步 version.py / pyproject.toml / CHANGELOG.md,并创建 git tag。
  支持 --dry-run / --no-tag。
- tests/test_version_consistency.py:9 个用例确保
  version.py、pyproject.toml、CHANGELOG.md 三处版本号一致

修改:
- pyproject.toml 加 [project] 元数据,version=3.3.3(PEP 440 形式,
  与 douyin/core/version.py 同步;后者带 V 前缀,是单一事实来源)

后续会给 V3.0.0 → V3.3.3 补打 git tag。

回归:353 个 pytest 用例通过;bump_version dry-run 三种模式(patch/minor/major/set)
全部输出正确。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
CodexandClaude Opus 4.7 committed 2026-05-21 15:17:56 +08:00
1 parent 778c021272
commit e35e8a85bd
4 files changed
+587

No files matched your search

+145
View File
@@ -0,0 +1,145 @@
# Changelog
本项目所有显著变更都会记录在这里。
格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)(带 `V` 前缀,如 `V3.3.3`)。
变更类型:
- `Added` 新增
- `Changed` 调整
- `Deprecated` 即将废弃
- `Removed` 已移除
- `Fixed` 修复
- `Security` 安全相关
## [Unreleased]
### Added
- 引入完整的版本管理体系:
- `CHANGELOG.md`(Keep a Changelog 1.1.0 格式)
- `tools/dev/bump_version.py`(自动 bump major/minor/patch + 同步 `version.py` / `pyproject.toml` / `CHANGELOG.md` + 创建 git tag)
- `[project]` 元数据加入 `pyproject.toml`,与 `douyin/core/version.py` 保持单一事实来源
- 给所有历史版本(V3.0.0 → V3.3.3)补齐 git tag
### Changed
- README「版本更新日志」段简化为指向 `CHANGELOG.md` 与 git tags
## [V3.3.3] — 2025-12-28
### Added
- 30 分钟超时保护机制:长时间无成功参与时自动返回推荐页重启流程
### Fixed
- 模板与截图路径配置统一,使用 `douyin/core/path_config.py`
- 直播间检测模板文件路径错误
- GUI / Web GUI 中行为日志读取路径
### Changed
- 路径配置全量统一化:用 `path_config.py` 集中管理,简化维护
- 行为日志路径统一为 `path_config.get_actions_log_path()`
- 流程图与文档:反映 30 分钟超时检查、阶段诊断步骤、预约回退子流程
## [V3.3.2] — 2025-12-25
### Fixed
- 预约回退功能不生效:
- `needswitch` 配置未从 `config.json` 正确加载
- `self.reservations` 未从状态文件加载
- 预约回退逻辑加详细调试日志
### Changed
- 每次 `run_once_basic` 自动从状态文件加载预约队列,确保始终包含最新数据
## [V3.3.1] — 2025-12-14
### Added
- `live_room_match_threshold`:直播间检测阈值可配置
- `fudai_icon_max_wait_seconds`:福袋图标检测等待时间可配置
### Fixed
- 直播间检测模板文件路径警告
### Changed
- 阶段检测优先使用像素检测
- 合并阶段 1.5 与阶段 3 的 OCR 检测以减少冗余
## [V3.3.0]
### Changed
- 模块化重构:核心代码按职责拆分到 `douyin/` 各子包
- 阶段检测策略调整:像素检测优先
### Added
- GUI 截图 + OCR 联合调试功能
- 桌面 GUI「强制停止」按钮
### Fixed
- 多个已知问题(详情见 commit 历史)
## [V3.2.0]
### Added
- 高价值福袋预约功能(`high_value_fudai_*` 配置族)
- 高价值直播间回访功能(`high_value_room_revisit_*`)
### Changed
- 推荐页养号逻辑优化
## [V3.1.0]
### Added
- 推荐页养号功能:自动点赞 / 收藏 / 评论(按概率)
### Changed
- OCR 识别准确率提升
## [V3.0.0]
### Changed
- **重大更新**:OCR 引擎从 pytesseract 切换到 PaddleOCR
### Added
- 自动分辨率适配
### Fixed
- 大量已知问题
## V2.x
- 多分辨率支持
- 稳定性提升
- 各种 bug 修复
## V1.x
- 基础功能:福袋检测、参与、自动领奖
[Unreleased]: https://git.simgreek.com/simgreek/douyi_guaji_main/compare/v3.3.3...HEAD
[V3.3.3]: https://git.simgreek.com/simgreek/douyi_guaji_main/compare/v3.3.2...v3.3.3
[V3.3.2]: https://git.simgreek.com/simgreek/douyi_guaji_main/compare/v3.3.1...v3.3.2
[V3.3.1]: https://git.simgreek.com/simgreek/douyi_guaji_main/compare/v3.3.0...v3.3.1
[V3.3.0]: https://git.simgreek.com/simgreek/douyi_guaji_main/compare/v3.2.0...v3.3.0
[V3.2.0]: https://git.simgreek.com/simgreek/douyi_guaji_main/compare/v3.1.0...v3.2.0
[V3.1.0]: https://git.simgreek.com/simgreek/douyi_guaji_main/compare/v3.0.0...v3.1.0
[V3.0.0]: https://git.simgreek.com/simgreek/douyi_guaji_main/releases/tag/v3.0.0
+11
View File
@@ -1,3 +1,14 @@
[project]
# 项目元数据。版本号的"单一事实来源"是 douyin/core/version.py: APP_VERSION,
# 这里的 version 由 tools/dev/bump_version.py 与 version.py 同步维护。
# 注意:为兼容 PEP 440,这里去掉 "V" 前缀,仅保留数字部分(如 V3.3.3 → 3.3.3)。
name = "douyin_guaji"
version = "3.3.3"
description = "基于 ADB + OCR + 像素检测 + 模板匹配的抖音直播间福袋自动挂机工具"
readme = "README.md"
requires-python = ">=3.10"
authors = [{ name = "douyin_guaji" }]
[tool.pylint.messages_control]
disable = [
"broad-except",
+146
View File
@@ -0,0 +1,146 @@
"""版本号一致性测试。
确保以下 3 个位置保持同步:
1. douyin/core/version.py:APP_VERSION
2. pyproject.toml [project] version(PEP 440 形式,去掉 V 前缀)
3. CHANGELOG.md 顶部最新发布版本([Unreleased] 之后的第一个版本)
新增/修改时如果忘了同步,这个测试会失败。
"""
from __future__ import annotations
import re
from pathlib import Path
import pytest
PROJECT_ROOT = Path(__file__).resolve().parents[1]
# ============================================================
# 读取三个来源
# ============================================================
def _read_version_py() -> tuple[str, str]:
"""返回 (APP_VERSION, APP_BUILD_DATE)。"""
text = (PROJECT_ROOT / "douyin" / "core" / "version.py").read_text(encoding="utf-8")
ver = re.search(r'^APP_VERSION\s*=\s*"(V?[\d.]+)"', text, re.MULTILINE)
date = re.search(r'^APP_BUILD_DATE\s*=\s*"(\d{4}-\d{2}-\d{2})"', text, re.MULTILINE)
assert ver, "version.py 中找不到 APP_VERSION"
assert date, "version.py 中找不到 APP_BUILD_DATE"
return ver.group(1), date.group(1)
def _read_pyproject_version() -> str:
text = (PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8")
m = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
assert m, "pyproject.toml 中找不到 version 字段"
return m.group(1)
def _read_changelog_latest_version() -> str | None:
"""读 CHANGELOG.md 顶部第一个 ## [V...] 段的版本号;无则返回 None。"""
text = (PROJECT_ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
# 跳过 [Unreleased],找下一个 ## [VX.Y.Z] 段
found_unreleased = False
for line in text.splitlines():
if re.match(r"^##\s+\[Unreleased\]\s*$", line):
found_unreleased = True
continue
m = re.match(r"^##\s+\[(V?[\d.]+)\](?:\s*[—–-].*)?$", line)
if m:
return m.group(1)
if not found_unreleased:
# 没 Unreleased 也没具名版本,CHANGELOG 还没建好
return None
return None
# ============================================================
# 一致性断言
# ============================================================
class TestVersionConsistency:
def test_version_py_format(self):
"""APP_VERSION 应是 V<major>.<minor>.<patch> 形式。"""
ver, _ = _read_version_py()
assert re.fullmatch(r"V\d+\.\d+\.\d+", ver), (
f"APP_VERSION 应为 'V<major>.<minor>.<patch>' 格式,得到 {ver!r}"
)
def test_pyproject_version_format(self):
"""pyproject.toml version 应是 PEP 440 形式(无 V 前缀)。"""
ver = _read_pyproject_version()
assert re.fullmatch(r"\d+\.\d+\.\d+", ver), (
f"pyproject.toml version 应为 '<major>.<minor>.<patch>' 形式,得到 {ver!r}"
)
def test_version_py_and_pyproject_match(self):
"""version.py 与 pyproject.toml 的版本号必须一致(去掉 V 前缀对比)。"""
py_ver, _ = _read_version_py()
pep440 = py_ver.lstrip("Vv")
pyproject_ver = _read_pyproject_version()
assert pep440 == pyproject_ver, (
f"版本号不一致:version.py={py_ver} pyproject.toml={pyproject_ver}\n"
f"运行 `python tools/dev/bump_version.py set {py_ver}` 同步。"
)
def test_version_py_and_changelog_match(self):
"""CHANGELOG.md 顶部最新发布版本必须 ≤ version.py 当前版本。
通常等于;如果 [Unreleased] 段还有未发布的改动则可以不严格相等,
但 CHANGELOG 顶部不应超出当前 version.py 声明的版本。
"""
py_ver, _ = _read_version_py()
latest = _read_changelog_latest_version()
if latest is None:
pytest.skip("CHANGELOG.md 还没有具名版本段")
# 都规范化为带 V 前缀
py_norm = py_ver if py_ver.startswith("V") else "V" + py_ver
cl_norm = latest if latest.startswith("V") else "V" + latest
assert cl_norm == py_norm, (
f"CHANGELOG 顶部 = {latest}, 但 version.py 是 {py_ver}。\n"
f"如果是 release,应让 CHANGELOG 顶部版本与 version.py 一致;"
f"用 bump_version.py 可一键同步。"
)
def test_build_date_format(self):
_, date = _read_version_py()
assert re.fullmatch(r"\d{4}-\d{2}-\d{2}", date), (
f"APP_BUILD_DATE 应为 'YYYY-MM-DD',得到 {date!r}"
)
# ============================================================
# 别名兼容(VERSION / RELEASE_DATE / get_version_string)
# ============================================================
class TestVersionAliases:
def test_version_alias_strips_v_prefix(self):
from douyin.core.version import APP_VERSION, VERSION
assert VERSION == APP_VERSION.lstrip("Vv"), (
"VERSION 应是 APP_VERSION 去掉 V 前缀的别名"
)
def test_release_date_alias(self):
from douyin.core.version import APP_BUILD_DATE, RELEASE_DATE
assert RELEASE_DATE == APP_BUILD_DATE
def test_get_version_string(self):
from douyin.core.version import (
APP_BUILD_DATE,
APP_VERSION,
get_version_string,
)
s = get_version_string()
assert APP_VERSION in s
assert APP_BUILD_DATE in s
def test_app_name_not_empty(self):
from douyin.core.version import APP_NAME
assert isinstance(APP_NAME, str) and APP_NAME.strip()
+285
View File
@@ -0,0 +1,285 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""bump_version.py — 单一入口的版本号 bump 工具。
版本号"单一事实来源"是 douyin/core/version.py 的 APP_VERSION(带 V 前缀,SemVer)。
本脚本同步以下 4 个位置:
1. douyin/core/version.py: APP_VERSION 与 APP_BUILD_DATE
2. pyproject.toml: [project] version(PEP 440 不支持 V 前缀,所以去掉前缀)
3. CHANGELOG.md: 把 [Unreleased] 段重命名为新版本,并新建空 [Unreleased]
4. git tag: vX.Y.Z(小写 v + 纯数字,符合大多数工具习惯)
用法:
python tools/dev/bump_version.py patch # V3.3.3 → V3.3.4
python tools/dev/bump_version.py minor # V3.3.3 → V3.4.0
python tools/dev/bump_version.py major # V3.3.3 → V4.0.0
python tools/dev/bump_version.py set V3.5.0 # 指定版本
可选参数:
--no-tag 不创建 git tag(仅更新文件,由人手工 tag)
--dry-run 只打印会改什么,不实际写
示例完整流程:
python tools/dev/bump_version.py patch
git diff # 看自动改了什么
# 编辑 CHANGELOG.md 把 Unreleased 那段挪进去(脚本已自动重命名空段)
git commit -am "chore(release): bump version to V3.3.4"
git push --follow-tags
"""
from __future__ import annotations
import argparse
import datetime as _dt
import re
import subprocess
import sys
from pathlib import Path
from typing import Optional, Tuple
PROJECT_ROOT = Path(__file__).resolve().parents[2]
VERSION_PY = PROJECT_ROOT / "douyin" / "core" / "version.py"
PYPROJECT_TOML = PROJECT_ROOT / "pyproject.toml"
CHANGELOG_MD = PROJECT_ROOT / "CHANGELOG.md"
# ============================================================
# 当前版本:从 version.py 读取
# ============================================================
VERSION_RE = re.compile(r'^APP_VERSION\s*=\s*"(V?\d+\.\d+\.\d+)"', re.MULTILINE)
BUILD_DATE_RE = re.compile(r'^APP_BUILD_DATE\s*=\s*"(\d{4}-\d{2}-\d{2})"', re.MULTILINE)
def read_current_version() -> Tuple[str, str]:
"""返回 (当前版本号含V前缀, 构建日期)。"""
text = VERSION_PY.read_text(encoding="utf-8")
m = VERSION_RE.search(text)
if not m:
raise SystemExit(f"无法从 {VERSION_PY} 解析 APP_VERSION")
md = BUILD_DATE_RE.search(text)
return m.group(1), (md.group(1) if md else "")
def parse_semver(ver: str) -> Tuple[int, int, int]:
"""V3.3.3 → (3, 3, 3)。"""
s = ver.lstrip("Vv")
parts = s.split(".")
if len(parts) != 3:
raise SystemExit(f"版本号格式应为 X.Y.Z 或 VX.Y.Z,得到: {ver!r}")
try:
return int(parts[0]), int(parts[1]), int(parts[2])
except ValueError:
raise SystemExit(f"版本号包含非数字部分: {ver!r}")
# ============================================================
# 计算下一个版本号
# ============================================================
def compute_next(current: str, level: str) -> str:
"""level ∈ {major, minor, patch}。返回带 V 前缀的下一版本号。"""
major, minor, patch = parse_semver(current)
if level == "major":
return f"V{major + 1}.0.0"
if level == "minor":
return f"V{major}.{minor + 1}.0"
if level == "patch":
return f"V{major}.{minor}.{patch + 1}"
raise SystemExit(f"未知 level: {level!r}")
# ============================================================
# 文件改写
# ============================================================
def update_version_py(new_ver: str, build_date: str, *, dry_run: bool) -> None:
text = VERSION_PY.read_text(encoding="utf-8")
new_text = VERSION_RE.sub(f'APP_VERSION = "{new_ver}"', text, count=1)
new_text = BUILD_DATE_RE.sub(f'APP_BUILD_DATE = "{build_date}"', new_text, count=1)
if new_text == text:
print(f" [skip] {VERSION_PY.relative_to(PROJECT_ROOT)} 内容未变")
return
if dry_run:
print(f" [dry-run] {VERSION_PY.relative_to(PROJECT_ROOT)}: APP_VERSION={new_ver} APP_BUILD_DATE={build_date}")
return
VERSION_PY.write_text(new_text, encoding="utf-8")
print(f" [ok] {VERSION_PY.relative_to(PROJECT_ROOT)}: APP_VERSION={new_ver}")
PYPROJECT_VER_RE = re.compile(r'^version\s*=\s*"[^"]+"', re.MULTILINE)
def update_pyproject(new_ver: str, *, dry_run: bool) -> None:
if not PYPROJECT_TOML.exists():
print(f" [skip] {PYPROJECT_TOML.relative_to(PROJECT_ROOT)} 不存在")
return
text = PYPROJECT_TOML.read_text(encoding="utf-8")
# PEP 440 不支持 V 前缀
pep440 = new_ver.lstrip("Vv")
new_text = PYPROJECT_VER_RE.sub(f'version = "{pep440}"', text, count=1)
if new_text == text:
print(f" [skip] {PYPROJECT_TOML.relative_to(PROJECT_ROOT)} 中未找到 version 字段或值未变")
return
if dry_run:
print(f" [dry-run] {PYPROJECT_TOML.relative_to(PROJECT_ROOT)}: version={pep440}")
return
PYPROJECT_TOML.write_text(new_text, encoding="utf-8")
print(f" [ok] {PYPROJECT_TOML.relative_to(PROJECT_ROOT)}: version={pep440}")
CHANGELOG_UNRELEASED_RE = re.compile(
r"^## \[Unreleased\]\s*$",
re.MULTILINE,
)
def update_changelog(new_ver: str, build_date: str, *, dry_run: bool) -> None:
"""把 [Unreleased] 段改名为 [<新版本>] — <日期>,并在前面新建一个空 [Unreleased] 段。
bottom 的对比链接也顺手添加。
"""
if not CHANGELOG_MD.exists():
print(f" [skip] {CHANGELOG_MD.relative_to(PROJECT_ROOT)} 不存在")
return
text = CHANGELOG_MD.read_text(encoding="utf-8")
if not CHANGELOG_UNRELEASED_RE.search(text):
print(f" [skip] CHANGELOG.md 中未找到 [Unreleased] 段,跳过")
return
# 1) 把 ## [Unreleased] → ## [<new_ver>] — <date>,并在其上方插入新的 ## [Unreleased]
replacement = f"## [Unreleased]\n\n## [{new_ver}] — {build_date}"
new_text = CHANGELOG_UNRELEASED_RE.sub(replacement, text, count=1)
# 2) 维护底部的对比链接:把现有的 [Unreleased]: ...compare/<old>...HEAD 改成新的,
# 并新增 [<new_ver>]: ...compare/<old>...<new_tag>
cur_ver, _ = read_current_version()
cur_tag = "v" + cur_ver.lstrip("Vv")
new_tag = "v" + new_ver.lstrip("Vv")
# 替换 Unreleased 链接
unreleased_link_re = re.compile(
r"^\[Unreleased\]:\s*(.+?compare/)([^.]+)(\.\.\.HEAD)\s*$",
re.MULTILINE,
)
m = unreleased_link_re.search(new_text)
if m:
prefix = m.group(1)
# 替换为指向新 tag
new_unreleased = f"[Unreleased]: {prefix}{new_tag}...HEAD"
new_text = unreleased_link_re.sub(new_unreleased, new_text, count=1)
# 在 Unreleased 链接行下方插入新的对比链接
# 形如: [<new_ver>]: <prefix><cur_tag>...<new_tag>
new_compare_line = f"[{new_ver}]: {prefix}{cur_tag}...{new_tag}"
# 找到 [Unreleased]: 那一行,在其下一行插入
new_text = new_text.replace(
new_unreleased,
f"{new_unreleased}\n{new_compare_line}",
1,
)
if dry_run:
print(f" [dry-run] {CHANGELOG_MD.relative_to(PROJECT_ROOT)}: 重命名 [Unreleased] 为 [{new_ver}],新增空 [Unreleased]")
return
CHANGELOG_MD.write_text(new_text, encoding="utf-8")
print(f" [ok] {CHANGELOG_MD.relative_to(PROJECT_ROOT)}: [Unreleased] → [{new_ver}]")
# ============================================================
# git tag
# ============================================================
def create_git_tag(new_ver: str, *, dry_run: bool) -> None:
tag = "v" + new_ver.lstrip("Vv")
msg = f"Release {new_ver}"
cmd = ["git", "tag", "-a", tag, "-m", msg]
if dry_run:
print(f" [dry-run] git tag: {tag}")
return
res = subprocess.run(cmd, cwd=PROJECT_ROOT, capture_output=True, text=True)
if res.returncode == 0:
print(f" [ok] git tag: {tag}")
else:
# 已存在的 tag 不算致命错误,但要提醒
if "already exists" in (res.stderr or ""):
print(f" [warn] git tag {tag} 已存在")
else:
print(f" [err] git tag 失败: {res.stderr.strip()}")
# ============================================================
# main
# ============================================================
def main(argv: Optional[list[str]] = None) -> int:
parser = argparse.ArgumentParser(
description="单入口 bump 项目版本号(version.py + pyproject.toml + CHANGELOG.md + git tag)。",
)
parser.add_argument(
"level",
choices=["major", "minor", "patch", "set"],
help="bump 级别;'set' 时需要再传一个版本号参数",
)
parser.add_argument(
"version",
nargs="?",
help="当 level=set 时使用,例如 V3.5.0",
)
parser.add_argument(
"--no-tag",
action="store_true",
help="只更新文件,不创建 git tag",
)
parser.add_argument(
"--dry-run",
action="store_true",
help="只打印将要做什么,不实际写入",
)
args = parser.parse_args(argv)
cur_ver, cur_date = read_current_version()
print(f"当前版本: {cur_ver} (build {cur_date or 'n/a'})")
if args.level == "set":
if not args.version:
print("ERROR: level=set 需要传第二个参数(版本号)", file=sys.stderr)
return 1
# 规范化前缀
new_ver = args.version
if not new_ver.startswith(("V", "v")):
new_ver = "V" + new_ver
# 验证格式
parse_semver(new_ver)
else:
new_ver = compute_next(cur_ver, args.level)
new_date = _dt.date.today().isoformat()
print(f"目标版本: {new_ver} (build {new_date})")
print()
update_version_py(new_ver, new_date, dry_run=args.dry_run)
update_pyproject(new_ver, dry_run=args.dry_run)
update_changelog(new_ver, new_date, dry_run=args.dry_run)
if not args.no_tag:
create_git_tag(new_ver, dry_run=args.dry_run)
print()
if args.dry_run:
print("[dry-run] 没有写入任何改动。")
else:
print("✓ 完成。建议下一步:")
print(" 1. 编辑 CHANGELOG.md,把本版的 Added/Fixed/Changed 写到对应小节")
print(f" 2. git commit -am 'chore(release): bump version to {new_ver}'")
if not args.no_tag:
print(" 3. git push --follow-tags")
else:
print(f" 3. git tag -a v{new_ver.lstrip('Vv')} -m 'Release {new_ver}'")
print(" 4. git push --follow-tags")
return 0
if __name__ == "__main__":
sys.exit(main())