gitwebhooks 2.4.0__tar.gz → 2.4.2__tar.gz

gitwebhooks-2.4.2/AGENTS.md

@@ -0,0 +1,291 @@
+# AGENTS.md — gitwebhooks
+
+> 轻量级 Git Webhook 服务器：接收 GitHub / Gitee / GitLab / 自定义平台的 webhook，按 INI 配置执行仓库部署命令。纯 Python 3 标准库实现，无外部运行时依赖。
+>
+> **⚠️ 最高编码准则见 [`CONSTITUTION.md`](./CONSTITUTION.md)（项目编码宪章）——所有 MUST 条款、合规分级与审查口径以宪章为准，冲突时宪章优先**。本文档为入口摘录，不重复宪章长文。
+
+## 项目概述
+
+| 项 | 值 |
+|----|----|
+| 语言 | Python（`requires-python = ">=3.7"`，classifiers 覆盖 3.7–3.14） |
+| 运行时依赖 | **无**（仅标准库；`pyproject.toml` 的 `dependencies = []` 是硬约定） |
+| 开发依赖 | `pytest`、`pytest-cov`（dev extra；**全量测试套件的运行器**） |
+| 代码规模 | 4.6k 行（`gitwebhooks/`，4570 行） |
+| 配置格式 | INI（`configparser`） |
+| HTTP | 标准库 `http.server` |
+| 打包 | `setuptools`，可发布 PyPI，亦支持原地从源码运行 |
+| 当前版本 | `2.4.2`（`pyproject.toml` 与 `gitwebhooks/__init__.py` **两处**） |
+
+**支持平台**：GitHub（HMAC-SHA1 签名）、Gitee（签名或密码）、GitLab（token）、custom（自定义 Header + JSON 路径识别）。
+
+## 宪章与文档层级
+
+**最高编码准则：[`CONSTITUTION.md`](./CONSTITUTION.md)** —— 所有贡献者与 AI 代理必须遵守其 MUST 条款；本文档与 `README*.md`、`.dsh/skills/` 不得弱化宪章要求，**冲突时以宪章为准**。
+
+| 优先级 | 文件 | 职责 |
+|--------|------|------|
+| 1 | `CONSTITUTION.md` | 编码宪章（MUST 条款、架构不变量、合规分级 A/B/C、审查矩阵） |
+| 2 | `AGENTS.md`（本文档） | Agent 入口：架构、命令、约束摘录 |
+| 3 | `README.md` / `README.zh.md` | 用户手册（安装、配置、使用；两语言须同步） |
+| 4 | `.dsh/skills/*` | 操作技能（`code-review` 代码审查口径） |
+
+## 架构
+
+依赖方向单向（上层依赖下层）：
+
+```
+main/  cli/        入口：参数解析、子命令分发、交互式向导
+   ↓
+server.py          HTTP 服务器、请求生命周期编排
+   ↓
+handlers/          平台事件识别 → 仓库分发 → 调用部署命令
+auth/              各平台签名 / token 校验（工厂 + 每平台一文件）
+   ↓
+config/            INI 加载、注册表、配置数据模型
+models/            与框架无关的数据类与枚举（Provider / WebhookRequest / 验证结果）
+utils/             常量、异常、命令执行、systemd 辅助
+```
+
+**请求处理流程**：`do_POST()` → `_parse_provider()`（按 Header 识别平台）→ `_parse_data()`（JSON / form-urlencoded）→ 平台处理器验证签名 / token → 提取仓库标识 → 查配置 → 异步执行配置的命令。
+
+**平台差异**（识别 Header / 仓库标识 / 验证方式）：
+
+| 平台 | 事件 Header | 仓库标识 | 验证 |
+|------|-------------|----------|------|
+| GitHub | `X-GitHub-Event` | `repository.full_name` | `X-Hub-Signature`（HMAC-SHA1） |
+| Gitee | `X-Gitee-Event` | `repository.full_name` | 签名或密码 |
+| GitLab | `X-Gitlab-Event` | `project.path_with_namespace` | `X-Gitlab-Token` |
+| custom | 配置的 `header_event` | 配置的 `identifier_path` | 配置的 `header_token` |
+
+## 文件结构
+
+```
+gitwebhooks-cli              # Bash 包装脚本：自动定位包并以 python3 -m gitwebhooks.main 运行
+pyproject.toml               # 打包、版本号（源 1）、入口点 gitwebhooks.main:main
+MANIFEST.in                  # sdist 清单
+CHANGELOG.md                 # 更新日志（Keep a Changelog；发布时必须更新）
+gitwebhooks.ini.sample       # 配置模板（改配置项须同步）
+scripts/pre-release-check.sh # 发布前校验（构建 + 隔离环境安装 + CLI 冒烟）
+gitwebhooks/
+├── __init__.py              # 包入口、__version__（源 2）、导出 WebhookServer / Provider / WebhookRequest
+├── server.py                # WebhookServer 与请求处理器：编排与派发
+├── main/
+│   ├── __init__.py          # create_parser / find_config_file / main（CLI 主函数）
+│   ├── __main__.py          # python3 -m gitwebhooks.main 入口
+│   └── version.py           # 版本输出
+├── cli/
+│   ├── __init__.py          # 子命令注册（serve / config / help）
+│   ├── serve.py             # cmd_serve：启动服务器 / systemd 安装卸载分发
+│   ├── service.py           # systemd 安装卸载实现（被 serve.py 调用，非子命令）
+│   ├── config.py            # cmd_init / cmd_view
+│   ├── init_wizard.py       # 交互式配置向导（⚠️ 785 行，见宪章 §1.2）
+│   ├── prompts.py           # 交互提示辅助
+│   └── help.py              # help 子命令（输出由 argparse format_help 生成，与 --help 同源）
+├── config/
+│   ├── loader.py            # INI 加载与自动查找
+│   ├── registry.py          # 配置注册表
+│   ├── models.py            # 配置数据类
+│   └── server.py            # 服务器 / SSL 配置
+├── auth/
+│   ├── verifier.py          # 验证器基类
+│   ├── factory.py           # 验证器工厂
+│   └── github.py gitee.py gitlab.py custom.py
+├── handlers/
+│   ├── base.py              # 处理器基类
+│   ├── request.py           # 请求数据解析
+│   ├── factory.py           # 处理器工厂
+│   └── github.py gitee.py gitlab.py custom.py
+├── models/
+│   ├── provider.py          # Provider 枚举（Github / Gitee / Gitlab / Custom）
+│   ├── request.py           # WebhookRequest 数据类
+│   ├── result.py            # 验证结果
+│   └── config.py            # 配置模型
+├── utils/
+│   ├── constants.py         # HTTP 常量、Header 名、路径、RESERVED_SECTIONS、SENSITIVE_KEYWORDS
+│   ├── exceptions.py        # 自定义异常（含 ConfigurationError）
+│   ├── executor.py          # execute_deployment（异步 subprocess；守护线程排空输出 + wait 回收）
+│   └── systemd.py           # systemd 检测与服务文件生成
+└── logging/setup.py         # 日志配置
+tests/
+├── __main__.py              # 项目自带 runner：python3 -m tests
+├── conftest.py              # 共享夹具（临时目录、空闲端口、服务器管理等）
+├── unit/                    # 单元测试（unit/cli/ 为 CLI 子命令测试）
+├── integration/             # 端到端 webhook / 配置发现 / 命令执行
+├── fixtures/                # 各平台 payload 与签名构造器
+└── utils/                   # 测试辅助（HTTP 客户端、线程内测试服务器）
+doc/                         # README 截图（二进制资源）
+.dsh/skills/                 # DSH 项目技能（项目唯一技能来源）
+```
+
+## 配置结构
+
+INI 格式（`configparser`），保留节名以 `utils/constants.py` 的 `RESERVED_SECTIONS` 为准：
+
+| 节 | 内容 |
+|----|------|
+| `[server]` | `address`、`port`、`log_file` |
+| `[ssl]` | `enable`、`key_file`、`cert_file` |
+| `[github]` / `[gitee]` / `[gitlab]` | `handle_events`、`verify`、`secret` |
+| `[custom]` | `header_name`、`header_value`、`header_token`、`header_event`、`identifier_path`、`handle_events`、`verify`、`secret` |
+| `[owner/repo]` | **仓库节**：`cwd`（工作目录）、`cmd`（收到 webhook 时执行的 shell 命令） |
+
+- 仓库节名必须为 `owner/repo`；`identifier_path` 是 JSON 路径（如 `project.path_with_namespace`），用点号分隔。
+- 改配置项**必须**同步 `gitwebhooks.ini.sample`、`RESERVED_SECTIONS` 与两个 README。
+
+**默认部署路径**：配置 `/usr/local/etc/gitwebhooks.ini`、日志 `/var/log/gitwebhooks.log`、CLI `/usr/local/bin/gitwebhooks-cli`、systemd 单元 `/usr/lib/systemd/system/gitwebhooks.service`。
+
+## 常用命令
+
+### 运行服务
+
+```bash
+# 从源码运行（开发模式，推荐）
+./gitwebhooks-cli serve -c gitwebhooks.ini.sample
+
+# 模块方式（等价）
+python3 -m gitwebhooks.main serve -c gitwebhooks.ini.sample
+
+# 不指定 -c：按优先级自动查找配置并打印所用路径
+./gitwebhooks-cli serve
+```
+
+> ⚠️ 启动服务器**必须**带 `serve` 子命令。`./gitwebhooks-cli -c file.ini`（无子命令）只会打印帮助并返回 0，不会启动服务。
+
+**配置文件查找优先级**（唯一出处 `utils/constants.py` 的 `CONFIG_SEARCH_PATHS`）：
+
+1. `~/.gitwebhooks.ini`（用户级，最高）
+2. `/usr/local/etc/gitwebhooks.ini`（本地级）
+3. `/etc/gitwebhooks.ini`（系统级）
+
+### 子命令
+
+```bash
+./gitwebhooks-cli --help              # 总览帮助（亦可 -h；每层级均支持）
+./gitwebhooks-cli help                # 等价形式：help 子命令
+./gitwebhooks-cli help serve          # 指定子命令帮助（serve / config）
+./gitwebhooks-cli serve --help        # 同上，标准 flag 形式（两者输出完全一致）
+./gitwebhooks-cli --version           # 版本（亦可 -v）
+
+# 配置：交互式向导（可指定级别 system/local/user）
+./gitwebhooks-cli config init
+sudo ./gitwebhooks-cli config init system
+./gitwebhooks-cli config view         # 查看配置，敏感字段高亮
+./gitwebhooks-cli config view -c /path/to/config.ini
+
+# systemd 服务（注意：是 serve 的子动作，不是独立的 service 子命令）
+sudo ./gitwebhooks-cli serve install [--force] [--dry-run] [--verbose] [--config-level user|local|system]
+./gitwebhooks-cli serve install --config-level user
+sudo ./gitwebhooks-cli serve uninstall [--purge]
+
+# systemd 运行时
+systemctl {start,stop,restart,status} gitwebhooks
+```
+
+> ⚠️ 独立的 `service` 子命令**已被移除**（见 git log `refactor: 彻底移除 service 命令`），改为 `serve install` / `serve uninstall`。文档或脚本中出现 `gitwebhooks-cli service ...` 即为过时引用。
+
+### 安装与发布
+
+```bash
+pip install .                          # 安装（无外部依赖）
+pip install -e ".[dev]"                # 开发安装（含 pytest）
+
+./scripts/pre-release-check.sh         # 发布前必须通过：构建 + 隔离 venv 安装 + CLI 冒烟
+python3 -m build && python3 -m twine upload dist/*
+```
+
+## 测试与质量门禁
+
+**全量测试（权威，必须用这个）** — 先装 dev extra：
+
+```bash
+pip install -e ".[dev]"     # 含 pytest
+python3 -m pytest tests/    # 228 个测试全跑，约 10 秒
+```
+
+**零依赖子集 runner**（`unittest`，**不是**全量）：
+
+```bash
+python3 -m tests            # 只跑到不依赖 pytest 的模块（当前 128 个）
+python3 -m tests -q         # 仅摘要
+python3 -m tests -f         # 失败即停
+python3 -m tests -v         # 详细
+```
+
+> ⚠️ `python3 -m tests` 跑不到 `tests/unit/test_main.py` 等 7 个 pytest 风格模块
+> （当前约 100 个测试），因此**不能**用它声称「测试全通过」。
+
+**语法静态校验**：
+
+```bash
+python3 -m compileall -q gitwebhooks
+```
+
+### 门禁纪律
+
+- 交付前跑 `python3 -m compileall -q gitwebhooks` + **全量** `python3 -m pytest tests/`；
+- **如实区分**「本机真跑过 / 只做了静态检查 / 未执行」；声称通过时给出**实际计数**（跑了多少 / 失败 / 跳过）；
+- **禁止吞输出**（`>/dev/null`、`2>/dev/null`、`-q` 用于可能失败的命令）；
+- CLI 子命令增删时，**必须**核对全部引用点：`cli/__init__.py` 注册、`cli/help.py`、`README.md`、`README.zh.md`、`scripts/pre-release-check.sh`、相关测试。
+
+### 测试基线
+
+**`python3 -m pytest tests/`（Python 3.14）**：`228 passed`，约 10 秒，**0 挂起**。
+
+**`python3 -m tests`（无 pytest）**：`Ran 128 tests`，5 个 error（pytest 风格模块无法导入）。这些 error 是**子集 runner 的已知限制**，不是代码缺陷。
+
+判定改动是否引入回归时，必须以**全量 pytest 结果**为准。
+
+## 代码审查
+
+代码 / 文档改动交付前，加载 **`.dsh/skills/code-review/SKILL.md`** 执行审查：按宪章输出 `P0–P3 × file:line × 依据条款 × 证据` 的结构化发现清单。
+
+- 审查**只报不改**；发现自己问题的「顺手修一下」不属于审查结论。
+- 涉及**必须运行才能确认**的项（如某失败是否被修复、某分支是否真的到达），标注「需主代理跑门禁确认」，**禁止**把推测写成已验证。
+- 合规分级与审查矩阵见宪章 §10.2 / §10.3。
+
+## Git 纪律
+
+- 提交格式 `<类型>: <简短描述>`（feat / fix / docs / refactor / test / chore），**使用中文**；
+- **禁止** AI 归属签名（`🤖 Generated with ...`）、`Co-Authored-By:` 形式的 AI 署名、emoji；
+- 一次提交只含一项已完成工作，禁止夹带无关文件；未过门禁不得提交；
+- 未经用户明确授权，**不得** `git commit` / `git push` / 改写历史。
+
+## 开发原则
+
+1. **文档优先**：改前先 `read` / `grep` 验证 API 与现有模式，不假设文件或函数存在；
+2. **禁止反复猜测试错**：遇报错先查权威来源（Python 官方文档、`README*.md`、本宪章）确认根因，再最小复现验证；
+3. **最小改动**：只改任务相关代码，拒绝过度抽象（YAGNI / KISS）；
+4. **匹配现有风格**：命名、目录、抽象层级与周边代码一致；注释 / docstring 语言**按层就近一致**（核心模块英文、CLI 交互层中文，见宪章 §2.1），代码标识符一律英文，commit 用**中文**；
+5. **同步文档**：用户可见行为变更 → 两个 README **+ `CHANGELOG.md` 的「未发布」小节**；架构 / 命令变更 → 本文档；命令或配置项增删 → 核对 §「门禁纪律」的引用点清单；
+6. **零依赖**：不引入运行时第三方依赖（`dependencies` 保持为空）；
+7. **版本双源**：改版本号必须同时改 `pyproject.toml` 与 `gitwebhooks/__init__.py`，提交前 `grep` 复核。
+
+## 常见陷阱
+
+| 问题 | 说明 |
+|------|------|
+| **`serve` vs `service`** | 独立 `service` 子命令已移除；systemd 管理是 `serve install` / `serve uninstall`。`cli/service.py` 是内部实现模块，不是子命令。 |
+| **版本双源** | `pyproject.toml` 与 `gitwebhooks/__init__.py` 各存一份版本号，无自动同步；`main/version.py` 从包 `__version__` 读取。 |
+| **两处平台注册** | 新增平台须同时改 `handlers/factory.py` 与 `auth/factory.py`，并加 `handlers/<p>.py` 与 `auth/<p>.py`；漏一处会「识别了平台但无法验证」。 |
+| **测试挂起（P0）** | 历史上两处：① `sys.exit` 被 mock 成 no-op ⇒ `while True` 无限重试；② patch 了 `gitwebhooks.main.WebhookServer`，但 `cmd_serve` 用的是 `gitwebhooks.cli.serve.WebhookServer` ⇒ **真实启动服务器**。测试若卡住，先查这两类。 |
+| **测试因「恰好成立」而通过** | 例：用 `main([])` 断言返回码，实际走的是「打印帮助」分支；`-m gitwebhooks.cli` 恒返回 1（模块不存在），却让「配置缺失返回 1」的断言通过。断言必须对应被测行为。 |
+| **配置常量分散风险** | 路径列表、Header 名、状态码、敏感字段关键词的唯一出处是 `utils/constants.py`；别处硬编码即漂移。 |
+| **命令执行信任边界** | `execute_deployment` 使用 `shell=True`。安全前提是「命令只来自本地配置文件」——**禁止**把请求体内容拼进命令。 |
+| **禁止创建无人读取的管道** | `stdout=PIPE` 而不读 ⇒ 输出超过管道缓冲区（Linux 64 KiB）后命令**永久阻塞**（「推送后没反应、无报错、无日志尾」）。当前实现用守护线程合并排空 `stdout`/`stderr` 并 `wait()` 回收；改动此处**必须**保持「有消费者 + 有回收」，回归测试见 `tests/unit/test_executor.py`。 |
+| **CLI 文档漂移** | README 两个语言版本与 `scripts/pre-release-check.sh` 曾残留已删除的 `service` 引用；增删子命令时按引用点清单全查。 |
+| **模块入口是 `gitwebhooks.main`** | `gitwebhooks.cli` 是子命令包，**没有** `__main__.py`，`python3 -m gitwebhooks.cli` 会失败；模块方式启动一律用 `python3 -m gitwebhooks.main`。 |
+| **帮助只有一个来源** | 帮助文本由 argparse 从解析器定义生成：`help.py` 不再持有手写文案。改选项后 `help <cmd>` 与 `<cmd> --help` 自动同步，不要另写一份帮助字符串。 |
+| **启动服务器必须带 `serve`** | `./gitwebhooks-cli -c file.ini`（无子命令）只打印帮助并返回 0，**不会**启动服务；正确写法是 `./gitwebhooks-cli serve -c file.ini`。文档一律以此为准。 |
+
+## 受控文档索引
+
+| 文档 | 内容 |
+|------|------|
+| [`CONSTITUTION.md`](./CONSTITUTION.md) | **编码宪章（最高准则）**：适用范围、架构不变量、安全、测试、合规分级、审查矩阵 |
+| [`CHANGELOG.md`](./CHANGELOG.md) | **更新日志**（Keep a Changelog）：各版本的用户可感知变更；发布时必须更新 |
+| [`AGENTS.md`](./AGENTS.md)（本文档） | Agent 入口：架构、命令、门禁、陷阱 |
+| [`README.md`](./README.md) | 用户手册（英文）：安装、配置、使用、发布 |
+| [`README.zh.md`](./README.zh.md) | 用户手册（中文） |
+| [`gitwebhooks.ini.sample`](./gitwebhooks.ini.sample) | 配置模板 |
+| [`.dsh/skills/code-review/SKILL.md`](./.dsh/skills/code-review/SKILL.md) | 代码审查口径与清单 |

gitwebhooks-2.4.2/CHANGELOG.md

@@ -0,0 +1,285 @@
+# 更新日志 (Changelog)
+
+本文件记录本项目所有值得注意的变更。
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本 (Semantic Versioning)](https://semver.org/lang/zh-CN/)。
+
+变更类型：`Added / 新增`、`Changed / 变更`、`Deprecated / 弃用`、`Removed / 移除`、
+`Fixed / 修复`、`Security / 安全`。
+
+> **关于历史条目**：本文件自 v2.4.1 起正式维护。v2.4.1 之前没有 git tag，
+> 早期条目由提交历史整理而成，日期取该版本最后一次提交的日期；
+> 版本切分以历史上的 `chore: 发布版本 X` 提交为准，可能与当时 PyPI 上的上传时点存在偏差。
+
+---
+
+## [未发布 / Unreleased]
+
+<!-- 发布新版本时：把本节的条目移动到新的版本号小节，并更新下方链接。 -->
+
+## [2.4.2] - 2026-10-12
+
+> ### ⚠️ 升级注意事项（行为变更）
+>
+> 本版修复了一个认证绕过。**若你的配置是 `verify=true` 但 `secret` 留空，或在 custom 平台把 `header_token` 显式留空，升级后这些请求会被拒绝（401）**——
+> 这在旧版是「静默放行」，也就是任何人只要不带 token 就能触发你的部署命令。
+> 升级后请为每个平台配置真实的 `secret`；确实不需要验证时请显式设 `verify=false`。
+>
+> 另外 `[ssl] enable` 写非布尔值（如 `maybe`）从「静默当作关闭」改为直接报错退出。
+
+### Fixed / 修复
+
+- **测试套件会永久挂起**（全量 `pytest` 跑不完——是「卡死」不是「慢」）。两处根因：
+  ① `test_ask_config_level_keyboard_interrupt_confirms` 把 `sys.exit` mock 成 no-op，
+  导致 `while True` 无限重试；② `test_main_*` 把 `gitwebhooks.main.WebhookServer` 打桩，
+  但 `cmd_serve` 实际使用 `gitwebhooks.cli.serve.WebhookServer`，于是**真的启动了服务器**。
+- **测试套件运行时间**约 55 秒降到约 10 秒。主因是每个集成测试都要等
+  `serve_forever()` 默认 0.5 秒的 `poll_interval` 才完成 teardown；另有 17 处固定
+  `time.sleep()`（合计约 12 秒）与每次服务器启动固定 0.25 秒等待。现改为条件轮询
+  （`WebhookTestCase.wait_until` / `wait_for_file` / `wait_for_log_contains`）。
+- 修复若干**从未真正运行过**的测试（此前因缺少 pytest 而整体无法导入）：
+  - `tests/unit/test_main.py` 3 个用例断言的是重构前的 CLI（无子命令即启动服务器）；
+  - `tests/unit/test_install_service_logic.py` 导入了已被删除的 `cmd_install`；
+  - `tests/integration/test_config_discovery.py` 在 `cwd=tmp_path` 下未传 `PYTHONPATH`，
+    且自身推算仓库根路径多了一层。
+- `tests/unit/test_config_loading.py` 用 `python -m gitwebhooks.cli`（该模块不可执行）
+  断言返回码 1，属于**因错误原因通过**；改用 `python -m gitwebhooks.main serve`，
+  现在真正验证配置缺失 / 非法 INI 的处理。
+- `tests/integration/test_edge_cases.py::test_large_command_output_handled` 名为「大输出」，
+  实际把输出**重定向进文件**，从未经过管道——正是它让管道阻塞缺陷长期未被发现。
+- `.gitignore` 现在覆盖 `*.env`（此前 `secret.env` 等不会被忽略）。
+- `scripts/pre-release-check.sh` 不再吞掉全部输出（原先连构建与安装都 `>/dev/null 2>&1`，
+  失败时没有任何线索）；现为成功静默、失败打印完整输出。
+- **部署命令输出超过管道缓冲区后会永久卡死**（表现为「推送后没反应、无报错、无日志尾」）。
+  `execute_deployment` 原先用 `stdout=PIPE, stderr=PIPE` 启动命令却**从不读取**这两个管道，
+  且 `Popen` 对象被直接丢弃 ⇒ 进程一直留在 `subprocess._active`、**管道读端永不释放**，
+  命令输出超过管道缓冲区（Linux 默认 64 KiB）后写端阻塞在 `write()`。
+  `composer install`、`git reset --hard`、`npm ci`、`docker build` 等输出量足以触发。
+  现由守护线程持续排空 stdout/stderr（合并读取）并在结束后 `wait()` 回收子进程。
+- 部署失败（非 0 退出码）现在会记录退出码与输出尾部，此前完全无迹可查。
+- 声明的最低 Python 版本修正为 **3.7**（原为 `>=3.6` 并带 3.6 分类器）。
+  包在 import 阶段即依赖 `dataclasses`（Python 3.7+ 才有），此前 3.6 用户会安装成功、
+  但 `import gitwebhooks` 必然失败。
+- **安全：空 secret 会放行未认证请求**。`gitlab` / `gitee` / `custom` 三个验证器直接比较
+  `signature == secret`，当配置里 `secret` 为空且请求未带 token 时 `'' == ''` 成立，
+  于是 `verify=True` 形同虚设——而未认证的 webhook 会触发部署命令（任意 shell）。
+  `github` 验证器本就有 `if not secret` 保护，现三者也补上同样的保护。
+- **声明支持的 Python 3.7 / 3.8 实际无法启动 CLI**：`cli/init_wizard.py` 用了
+  PEP 585 的 `tuple[bool, str]` 注解（3.9+ 才有），且没有 `from __future__ import annotations`；
+  该模块在 `main → cli → cli.config → init_wizard` 链上被无条件导入，故 3.7/3.8 上
+  `gitwebhooks-cli` 直接 `TypeError: 'type' object is not subscriptable`。改用 `typing.Tuple`。
+- **`custom` 在 `header_token` 显式留空时静默跳过验证**：`verify_enabled` 由「Header 名是否非空」
+  推导，因此 `verify=true` + `header_token=` 会让验证器无条件返回成功（违反宪章 §5.3）。
+  现改为由 `config.verify` 决定：`verify=false` 才放行，`verify=true` 必须真正校验。
+- `[ssl] enable` 写错（如 `maybe`）原先被静默当作「未启用 SSL」；现抛 `ConfigurationError`。
+- pipx 自动探测用了过时的 venv 名 `gitwebhooks-server`（包名是 `gitwebhooks`），该分支实际不可达。
+- `serve uninstall --purge` 删错文件：`cli/service.py` 写的是 `~/.gitwebhook.ini`（少一个 s），
+  与真实路径 `~/.gitwebhooks.ini` 不符，导致配置文件从未被清理。
+- 配置错误不再抛原生异常：`[ssl] enable=true` 但缺 `key_file`/`cert_file` 时原先冒泡
+  `configparser.NoOptionError`，`[server] port` 非整数时冒泡 `ValueError`；现均转为
+  带明确说明的 `ConfigurationError`。
+- `gitwebhooks.ini.sample` 现在可直接运行：原先 `[ssl] enable=true` 配占位证书路径、
+  且 `log_file=/var/log/...` 非 root 不可写，导致文档推荐的「从源码运行」命令必定失败。
+- README 中的 `~/.gitwebhook.ini` / `~/.gitwebhook.log` 拼写错误（共 12 处，中英各 6），
+  以及交互向导的默认日志路径同款拼写错误。
+
+### Changed / 变更
+
+- **完整测试套件改用 `python3 -m pytest tests/`**（`pytest` 本就是 `pyproject.toml` 的
+  dev extra），共 228 个测试；`python3 -m tests` 明确为**零依赖子集运行器**（128 个），
+  不再被当作「测试全通过」的依据。宪章 §6.1 / §7.1 同步更新。
+- 去除 `gitwebhooks/cli/serve.py` 中与 `gitwebhooks/main/__init__.py` 重复的
+  `find_config_file` 与 `format_config_error`（两份实现已漂移），改为复用后者。
+- `execute_deployment` 现在返回排空输出的工作线程（`Optional[threading.Thread]`），
+  便于调用方按需 join；原有调用方忽略返回值即可，行为不变。
+- 部署输出逐行记入日志（DEBUG 级），失败时把尾部重新以 WARNING 级输出。
+- **常量集中（宪章 §1.2/§1.3）**：各 handler 改为使用 `utils/constants.py` 的 Header 常量
+  （原先硬编码 `'X-Hub-Signature'` 等字面量）；`config/loader.py` 的保留节名改用
+  `RESERVED_SECTIONS`；`cli/service.py` 与 `cli/init_wizard.py` 的配置路径改用
+  `CONFIG_PATH_USER/LOCAL/SYSTEM`，不再各自硬编码路径列表。
+- 交互向导的配置级别菜单文案改用 `CONFIG_PATH_*` 常量（原先硬编码三个路径，已与常量漂移）。
+- README 的测试命令改为 `python3 -m pytest tests/`（完整套件）；原先写 `python3 -m unittest discover tests/`，
+  在未装 pytest 的环境下会报 5 个导入错误并退出非 0，且它并不是完整套件。
+- 测试辅助类 `TestServer` / `TestConfigBuilder` / `TestWebhookClient` 加 `__test__ = False`，
+  消除 pytest 的 26 条 `PytestCollectionWarning`。
+- `execute_deployment` 的 `shell=True` 处补上信任边界注释（宪章 §5.2 要求）。
+
+### Removed / 移除
+
+- 死代码清理（宪章 §3.2「零死代码」）：
+  - 10 个未使用的 import；
+  - 8 个无任何引用的函数：`check_systemd`、`get_cli_path`、`confirm_overwrite`、
+    `ask_question`、`validate_address`、`validate_path`、`validate_bool`、`validate_text`；
+  - `tests/utils/server_manager.py` 的 `TestServerProcess` 死类（同时含未使用的
+    `cli_script` 变量、指向不可执行模块的 `-m gitwebhooks.cli`，以及同款「创建未读管道」缺陷）；
+  - 无引用的测试工具 `tests/utils/certificate_generator.py` 与 `tests/utils/coverage_runner.py`。
+  - 6 个无引用的类方法：`VerifierFactory.get_verifier`、`HandlerFactory.from_headers`、
+    `ConfigurationRegistry.get_provider_config` / `get_repository_config` / `has_repository`、
+    `WebhookRequest.repo_identifier`；
+  - 4 个无引用常量：`prompts.QUESTIONS`、`prompts.PLATFORM_QUESTIONS`、
+    `service.E_SYSTEMD`、`service.E_EXISTS`；
+  - 生产与测试中共 20 处未使用的 import（上一轮只清理了生产侧 10 处）。
+  - 第二轮（独立复查发现）：`WebhookHandler.get_provider` 及 4 个平台覆写、
+    `tests/conftest.py` 的 5 个未被调用的辅助函数、`_read_log_file`、
+    9 个 `PayloadBuilder` 方法与 `generate_invalid_signature`、
+    14 个无引用的 fixture 常量，以及由此产生的 5 处 `Provider` 孤儿 import。
+
+## [2.4.1] - 2026-10-12
+
+### Fixed / 修复
+
+- **`-h` / `--help` 现在遵循标准 Unix 约定**：在主命令与每个子命令层级都可用，
+  输出到 stdout，退出码为 `0`。此前它会打印 `Error: -h/--help parameters are not supported.`
+  并以退出码 `1` 结束。
+- 帮助文本改为**由 argparse 从解析器定义生成**，`help <命令>` 与 `<命令> --help`
+  输出完全一致；删除 `cli/help.py` 中重复维护的手写帮助文案。
+- 修正文档中已失效的命令引用：
+  - 启动服务器必须带 `serve` 子命令（`./gitwebhooks-cli serve -c file.ini`）；
+    原文档写作 `./gitwebhooks-cli -c file.ini`，实际只会打印帮助。
+  - 模块入口是 `python3 -m gitwebhooks.main`（`gitwebhooks.cli` 无 `__main__.py`）。
+  - README 结构树删除不存在的 `cli.py` 与 `install.sh`。
+  - `cli/init_wizard.py` 的完成提示、`scripts/pre-release-check.sh` 的 CLI 检查
+    此前仍指向已移除的 `service` 子命令（导致发布前检查实际失效）。
+
+### Changed / 变更
+
+- `-v` / `--version` 注册为 argparse 参数，因此会出现在 `--help` 中；
+  不再由 `main()` 的预检查拦截（该预检查还会让 `serve -v` 意外打印版本号）。
+- 新增 `tests/unit/cli/test_help.py`（基于 `unittest`）覆盖各层级 `help`/`version`
+  的退出码、输出流与 `help <cmd>` ≡ `<cmd> --help` 的一致性。
+
+### 工程与治理 / Tooling & Governance
+
+- 迁移到 DSH 管理：新增 `CONSTITUTION.md`（项目编码宪章）与
+  `.dsh/skills/code-review`（代码审查技能）；`CLAUDE.md` 由 `AGENTS.md` 取代。
+- 清理其他 agent 工具残留：`.claude/`、`.specify/`、`.gitignore` 中的 SpecKit 段落、
+  4 个空的 `tests/test_*` 目录。
+- 修正 `.gitignore` 中拼错的配置文件名（`.gitwebhook.ini` → `.gitwebhooks.ini`），
+  避免用户本地配置与密钥被误提交。
+
+## [2.4.0] - 2026-01-16
+
+### Removed / 移除
+
+- 彻底移除 `service` 子命令及其向后兼容代码；systemd 服务管理改由
+  `serve install` / `serve uninstall` 承担（`gitwebhooks/cli/service.py` 保留为内部实现模块）。
+
+## [2.3.1] - 2026-01-16
+
+### Fixed / 修复
+
+- 修复 `serve` 命令显示弃用警告的问题。
+- 恢复被误删的 `gitwebhooks-cli` 脚本。
+
+## [2.3.0] - 2026-01-16
+
+### Added / 新增
+
+- 服务安装时的配置级别选择：`serve install --config-level user|local|system`。
+
+### Changed / 变更
+
+- 重构 CLI 命令结构，使其符合标准 Unix 工具规范。
+
+> 注：本次发布提交（`chore: 发布版本 2.3.0`）中 `pyproject.toml` 的版本号仍为 `2.2.0`，
+> 版本号是在紧随其后的 `chore: 更新 pyproject.toml 版本号到 2.3.0` 中才更新的。
+
+## [2.2.0] - 2026-01-15
+
+### Added / 新增
+
+- 配置文件优先级自动查找：未指定 `-c` 时依次查找
+  `~/.gitwebhooks.ini` → `/usr/local/etc/gitwebhooks.ini` → `/etc/gitwebhooks.ini`。
+
+## [2.1.4] - 2026-01-15
+
+### Changed / 变更
+
+- 统一项目命名为 `gitwebhooks`。
+
+### Fixed / 修复
+
+- 修复多个测试与实现问题。
+
+## [2.1.3] - 2026-01-14
+
+### Fixed / 修复
+
+- 修复配置初始化向导的多个问题。
+- 恢复被误删的 `constitution.md`。
+
+## [2.1.2] - 2026-01-14
+
+### Added / 新增
+
+- 发布前验证流程：`scripts/pre-release-check.sh`（构建 + 隔离环境安装 + CLI 冒烟）。
+
+### Fixed / 修复
+
+- 修复 CLI 入口点配置：`gitwebhooks.cli:main` → `gitwebhooks.main:main`。
+
+## [2.1.1] - 2026-01-14
+
+### Fixed / 修复
+
+- 修正 README 中的包名（`git-webhooks-server` → `gitwebhooks`）。
+
+## [2.1.0] - 2026-01-14
+
+### Added / 新增
+
+- 安装方法指导与服务文件自适应功能。
+
+## [2.0.0] - 2026-01-14
+
+首个发布到 PyPI 的版本，将原单文件实现重构为模块化包。
+
+### Added / 新增
+
+- 模块化包结构 `gitwebhooks/`：`models/`、`config/`、`auth/`、`handlers/`、`utils/`、`logging/`。
+- 完整测试套件（单元测试 + 集成测试）。
+- CLI 子命令取代 `install.sh`：`config init`（交互式配置向导）、`config view`（查看配置，敏感字段高亮）。
+
+### Changed / 变更
+
+- 安装方式简化为原地运行模式。
+- 源码按模块拆分，所有源码注释统一为英文。
+
+### Fixed / 修复
+
+- 修复 Gitee webhook 签名验证算法。
+- 修复 `install.sh --uninstall` 参数不生效的问题。
+- 修复服务模板与安装脚本缺少 `WorkingDirectory` 的问题。
+- 修复服务文件创建问题，并增加详细模式。
+
+### Removed / 移除
+
+- 移除旧的单文件实现与 `install.sh`。
+
+---
+
+## 2.0.0 之前（未发布到 PyPI）
+
+2020–2022 年间为单文件实现（`git-webhooks-server.py`），已具备以下能力：
+
+- 支持 GitHub、Gitee、GitLab 与自定义 webhook 源。
+- 按 Header 识别平台；支持签名 / token / 密码验证。
+- 支持指定需要处理的事件类型（`handle_events`）。
+- 自定义 webhook 通过 `identifier_path` 提取仓库标识。
+- 支持 SSL。
+- 修复重启后服务无法启动的问题。
+
+[未发布 / Unreleased]: https://gitee.com/holyhi/git-webhooks-server/compare/v2.4.2...HEAD
+[2.4.2]: https://pypi.org/project/gitwebhooks/2.4.2/
+[2.4.1]: https://pypi.org/project/gitwebhooks/2.4.1/
+[2.4.0]: https://pypi.org/project/gitwebhooks/2.4.0/
+[2.3.1]: https://pypi.org/project/gitwebhooks/2.3.1/
+[2.3.0]: https://pypi.org/project/gitwebhooks/2.3.0/
+[2.2.0]: https://pypi.org/project/gitwebhooks/2.2.0/
+[2.1.4]: https://pypi.org/project/gitwebhooks/2.1.4/
+[2.1.3]: https://pypi.org/project/gitwebhooks/2.1.3/
+[2.1.2]: https://pypi.org/project/gitwebhooks/2.1.2/
+[2.1.1]: https://pypi.org/project/gitwebhooks/2.1.1/
+[2.1.0]: https://pypi.org/project/gitwebhooks/2.1.0/
+[2.0.0]: https://pypi.org/project/gitwebhooks/2.0.0/