gitwebhooks 2.3.1__tar.gz → 2.4.1__tar.gz

gitwebhooks-2.4.1/AGENTS.md

@@ -0,0 +1,293 @@
+# AGENTS.md — gitwebhooks
+
+> 轻量级 Git Webhook 服务器：接收 GitHub / Gitee / GitLab / 自定义平台的 webhook，按 INI 配置执行仓库部署命令。纯 Python 3 标准库实现，无外部运行时依赖。
+>
+> **⚠️ 最高编码准则见 [`CONSTITUTION.md`](./CONSTITUTION.md)（项目编码宪章）——所有 MUST 条款、合规分级与审查口径以宪章为准，冲突时宪章优先**。本文档为入口摘录，不重复宪章长文。
+
+## 项目概述
+
+| 项 | 值 |
+|----|----|
+| 语言 | Python（`requires-python = ">=3.6"`，classifiers 覆盖至 3.14） |
+| 运行时依赖 | **无**（仅标准库；`pyproject.toml` 的 `dependencies = []` 是硬约定） |
+| 开发依赖 | `pytest`、`pytest-cov`（可选，仅作测试运行器） |
+| 代码规模 | ~4.9k 行（`gitwebhooks/`） |
+| 配置格式 | INI（`configparser`） |
+| HTTP | 标准库 `http.server` |
+| 打包 | `setuptools`，可发布 PyPI，亦支持原地从源码运行 |
+| 当前版本 | `2.4.1`（`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 清单
+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       # 交互式配置向导（⚠️ 779 行，见宪章 §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）
+│   └── 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/*
+```
+
+## 测试与质量门禁
+
+**项目自带 runner（无需 pytest，推荐）**：
+
+```bash
+python3 -m tests            # 全量
+python3 -m tests -q         # 仅摘要
+python3 -m tests -f         # 失败即停
+python3 -m tests -v         # 详细
+python3 -m tests unit       # 只跑单元测试（也可传 integration）
+```
+
+**pytest 驱动（可选，需自行安装 `pytest`）**：
+
+```bash
+python3 -m pytest tests/
+```
+
+**语法静态校验**：
+
+```bash
+python3 -m compileall -q gitwebhooks
+```
+
+### 门禁纪律
+
+- 交付前至少跑 `python3 -m compileall -q gitwebhooks` + 爆炸半径内测试；
+- **如实区分**「本机真跑过 / 只做了静态检查 / 未执行」；声称通过时给出**实际计数**（跑了多少 / 失败 / 跳过）；
+- **禁止吞输出**（`>/dev/null`、`2>/dev/null`、`-q` 用于可能失败的命令）；
+- CLI 子命令增删时，**必须**核对全部引用点：`cli/__init__.py` 注册、`cli/help.py`、`README.md`、`README.zh.md`、`scripts/pre-release-check.sh`、相关测试。
+
+### ⚠️ 已知测试基线偏差
+
+以下 7 个测试模块直接 `import pytest`，**在未安装 pytest 的环境下整体无法导入**（报 `ModuleNotFoundError`）：
+
+```
+tests/unit/test_main.py                    tests/unit/test_prompts_config_level.py
+tests/unit/test_config_level.py            tests/unit/test_service_install_context.py
+tests/unit/test_install_service_logic.py   tests/integration/test_config_discovery.py
+tests/unit/cli/test_init_wizard.py
+```
+
+**基线（2026-10-12 实测，Python 3.14，无 pytest）**：`Ran 121 tests`，**0 failures + 7 errors**。
+- 7 个 error = 上述 pytest 导入失败（模块整体无法导入，不是因为断言失败）；
+- **0 failures**：此前的 `test_help_display_with_h_argument` 失败已修复（`-h` 现按标准约定返回码 0）。
+
+判定改动是否引入回归时，**必须与此基线对比**：新增 failure 才算回归；7 个 error 是既有环境缺陷，不得当作新缺陷，也不得隐去不报。宪章 §6.1 要求新测试用 `unittest` 编写，不新增 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；架构 / 命令变更 → 本文档；命令或配置项增删 → 核对 §「门禁纪律」的引用点清单；
+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`；漏一处会「识别了平台但无法验证」。 |
+| **pytest 依赖** | 7 个测试模块 `import pytest` 导致无 pytest 环境整体导入失败（见上「已知测试基线偏差」）。新测试用 `unittest`。 |
+| **配置常量分散风险** | 路径列表、Header 名、状态码、敏感字段关键词的唯一出处是 `utils/constants.py`；别处硬编码即漂移。 |
+| **命令执行信任边界** | `execute_deployment` 使用 `shell=True`。安全前提是「命令只来自本地配置文件」——**禁止**把请求体内容拼进命令。 |
+| **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) | **编码宪章（最高准则）**：适用范围、架构不变量、安全、测试、合规分级、审查矩阵 |
+| [`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.1/CONSTITUTION.md

@@ -0,0 +1,310 @@
+# gitwebhooks 项目编码宪章
+
+> 本宪章是 gitwebhooks 项目的**最高编码准则**，所有贡献者与自动化工具（AI 编码代理）均须遵守。
+> 「必须 (MUST)」「禁止 (MUST NOT)」为硬性规定；「建议 (SHOULD)」「不建议 (SHOULD NOT)」为强烈指引，
+> 偏离需有充分理由并在代码审查中说明。
+> 版本 v1.0；修订历史记录在 git log，不在本文维护。
+
+---
+
+## 〇、适用范围与文档层级
+
+### 0.1 适用范围（本宪章约束什么）
+
+本宪章约束**项目自有代码与文档**：任何人（含 AI 代理）在本仓库内编写、修改、审查的内容，包括：
+
+- Python 包 `gitwebhooks/`：`server.py`、`main/`、`cli/`、`config/`、`auth/`、`handlers/`、`models/`、`utils/`、`logging/`；
+- 测试套件 `tests/`（unit / integration / fixtures / utils）；
+- 打包与脚本：`pyproject.toml`、`MANIFEST.in`、`gitwebhooks-cli`、`scripts/`；
+- 配置模板 `gitwebhooks.ini.sample`；
+- 项目文档：`README.md`、`README.zh.md`、`AGENTS.md`、本宪章、`.dsh/skills/`。
+
+### 0.2 排除范围（不在宪章要求与审查范围）
+
+**依赖产物、解释器标准库与构建产物不受本宪章条款约束，审查时不判违规**：
+
+- Python 标准库与解释器自身；
+- 第三方依赖（`pytest`、`pytest-cov` 等）及其安装产物（`.venv/`、`venv/`、`site-packages`）；
+- 构建与缓存产物：`dist/`、`build/`、`*.egg-info/`、`__pycache__/`、`.pytest_cache/`；
+- 文档截图 `doc/*.png`（二进制资源）。
+
+说明：
+
+- **使用标准库惯例不构成违规**（如 `argparse` 的子命令风格、`configparser` 的取值方式）；
+- 例外：**写在上述产物之外的自有逻辑**仍受本宪章约束。
+
+### 0.3 文档层级
+
+standing instructions 分层如下，**冲突时以上级为准**：
+
+| 优先级 | 文件 | 职责 |
+|--------|------|------|
+| 1 | `CONSTITUTION.md`（本文件） | 编码宪章、质量门禁、安全与 Agent 纪律 |
+| 2 | `AGENTS.md` | Agent 入口（链接本宪章，摘录要点，不重复长文） |
+| 3 | `README.md` / `README.zh.md` | 用户手册（安装、配置、使用） |
+| 4 | `.dsh/skills/*` | 操作技能（如 `code-review` 代码审查口径） |
+
+- 下级文档**不得弱化**本宪章的 MUST 条款；
+- 细则性内容（使用示例、配置说明）以 `README*.md` 为准，本宪章不重复长文。
+
+---
+
+## 一、代码组织
+
+### 1.1 分层与职责
+
+- **必须**：保持既有的模块化分层，各层职责单一，依赖方向单向（上层依赖下层，禁止反向）：
+
+  | 层 | 路径 | 职责 |
+  |----|------|------|
+  | 入口 | `main/`、`cli/` | 参数解析、子命令分发、交互式向导 |
+  | 服务 | `server.py` | HTTP 服务器、请求生命周期编排 |
+  | 处理 | `handlers/` | 平台事件识别与仓库分发（按平台分文件） |
+  | 验证 | `auth/` | 各平台签名 / token 校验（工厂 + 每平台一文件） |
+  | 配置 | `config/` | INI 加载、注册表、配置数据模型 |
+  | 模型 | `models/` | 与框架无关的数据类与枚举 |
+  | 工具 | `utils/` | 常量、异常、命令执行、systemd 辅助 |
+
+- **必须**：`models/`、`config/`、`auth/`、`handlers/` 之间不得循环导入。
+- **必须**：`server.py` 只做编排——平台识别、验证、查表、派发；平台专属解析逻辑放对应 `handlers/<platform>.py`。
+- **建议**：新增平台支持时，**同时**新增 `handlers/<platform>.py` 与 `auth/<platform>.py`，并在两个工厂中各注册一处；不要用 `if platform == ...` 在主流程里分叉。
+
+### 1.2 规模指标（所有语言）
+
+- **必须**：圈复杂度 ≤ 10；嵌套 ≤ 3 层；方法 ≤ 80 行；参数 ≤ 5 个。
+- **必须**：DRY——同一逻辑出现 3 处及以上必须提取复用。
+- **必须**：消除魔法数字与魔法字符串，提取为 `utils/constants.py` 中的常量或类常量；HTTP 状态码、Header 名、消息文案一律走常量。
+- **建议**：单文件不超过 **400 行**；超过时按语义边界拆分（独立类型 > 独立函数组 > 辅助逻辑）。
+
+  > **已知存量偏差（基线，非许可）**：`gitwebhooks/cli/init_wizard.py`（779 行）、`gitwebhooks/cli/service.py`（352 行）、`gitwebhooks/cli/prompts.py`（322 行）超过 400 行。
+  > 这些文件**不允许继续变大**；触及它们时应评估拆分，拆分须作为独立任务登记，不得夹带在无关改动里。
+
+### 1.3 命名与目录
+
+- **必须**：模块与文件命名用完整小写单词或下划线（`init_wizard.py` 而非 `iw.py`）；与同目录既有风格一致。
+- **必须**：私有方法 / 函数使用**单下划线**前缀（如 `_parse_provider`），与现有代码一致；**不使用**双下划线前缀（`__init__`、`__post_init__` 等 dunder 除外）。
+- **必须**：公有 API 不加下划线前缀。
+- **必须**：配置节名与仓库标识遵循 `[owner/repo]` 约定；保留节名集合以 `utils/constants.py` 的 `RESERVED_SECTIONS` 为唯一出处。
+
+---
+
+## 二、注释与文档
+
+### 2.1 注释语言
+
+本仓库的注释与文案语言**按层就近一致**，不强制全仓统一；新增 / 修改时匹配**所在模块**的既有语言：
+
+| 层 | 语言 | 现状 |
+|----|------|------|
+| 核心模块（`server.py`、`models/`、`config/`、`auth/`、`handlers/`、`utils/`） | **英文** docstring 与注释 | 现有文件均为英文，保持一致 |
+| CLI 交互层（`cli/init_wizard.py`、`cli/prompts.py`、`cli/config.py`、`logging/setup.py`） | **中文** docstring 与注释 | 现有文件以中文为主，保持一致 |
+| 用户可见输出 | 交互式向导与 `config` 子命令用**中文**；`argparse` 帮助文案用**英文** | 现状如此 |
+| 治理文档（`CONSTITUTION.md`、`AGENTS.md`、`.dsh/skills/*`、`README.zh.md`） | **中文** | — |
+| commit message | **中文**（见 §9.3） | — |
+
+- **禁止**：在同一文件内新建中英混排的注释块（匹配不了就选该文件的主导语言）。
+- **禁止**：为「统一语言」而批量重写既有注释——那是无关 drive-by 改动（§3.1）。
+- **允许**：`gitwebhooks-cli` 等面向维护者的 shell 包装脚本使用中文注释（既有惯例）。
+- **必须**：代码标识符（类名、函数名、变量名、配置键）一律用**英文**。
+
+### 2.2 文档注释与同步
+
+- **必须**：对外暴露的 API（`WebhookServer` 公共方法、`handlers` / `auth` / `config` 的公共方法、CLI 子命令、枚举）具备用途与关键参数 / 返回值说明。
+- **必须**：注释解释**意图**而非复述代码；临时方案以 `TODO:` / `FIXME:` 标注并附原因。
+- **必须**：功能变更同步更新对应文档——用户可见行为（CLI 命令、配置项、平台支持）变更时更新 `README.md` **与** `README.zh.md`；架构或命令入口变更时更新 `AGENTS.md`。
+- **禁止**：为「将来可能用到」编写文档或注释。
+
+---
+
+## 三、编码原则
+
+### 3.1 最少编码
+
+- **必须**：以最少代码实现需求，拒绝冗余抽象（YAGNI / KISS）；不为可能的扩展提前设计。
+- **必须**：单次变更范围限于任务本身，**禁止**无关 drive-by 重构。
+- **必须**：**零外部运行时依赖**——`pyproject.toml` 的 `[project].dependencies` 必须保持为空数组。新增任何运行时依赖都需要用户明确批准，并在本宪章修订流程中登记。
+
+### 3.2 零死代码
+
+- **禁止**：未被调用的函数 / 方法 / 类 / 常量、未使用的 import、无引用的配置项。
+- **禁止**：生产路径残留调试输出（`print()` 用于调试、`breakpoint()`、`pdb`）；日志一律走 `logging`。
+- **必须**：触及旧代码时发现死代码**必须**移除或登记跟踪（见 §10.2 合规分级）。
+- **必须**：命令 / 子命令被移除时，同步清理**所有**引用点（`cli/__init__.py` 注册、`cli/help.py` 文案、README 两个语言版本、`scripts/pre-release-check.sh`、相关测试）。
+
+  > 存量偏差：`scripts/pre-release-check.sh` 曾校验已被移除的 `service` 子命令，属于此类漏改；该引用已修正为 `serve`。
+
+### 3.3 领域惯例（核心不变量）
+
+以下为本项目的**架构不变量**，违反视为 P1 及以上：
+
+- **必须**：配置驱动行为——仓库专属逻辑（工作目录、执行命令）**只**来自 INI 配置，**禁止**把仓库名或仓库专属分支写进 Python 代码。
+- **必须**：平台中立——各平台（GitHub / Gitee / GitLab / custom）地位平等，平台识别**只**依据请求 Header；除已文档化的 Header / 事件名差异外，不得有平台特权分支。
+- **必须**：平台标识与 Header / 事件名 / 常量集中定义，不得散落字面量（见 §1.2）。
+- **必须**：请求体解析同时支持 JSON 与 `application/x-www-form-urlencoded`；新增平台不得削减既有支持。
+- **必须**：命令执行异步非阻塞，且 `stdin=subprocess.DEVNULL`——避免继承 stdin 造成文件描述符泄漏。
+- **必须**（CLI 约定，遵循标准 Unix 工具规范）：
+  - `-h` / `--help` 在**每一个命令层级**（主命令、`serve`/`config`、其下动作）都必须可用，帮助输出到 **stdout**，退出码 **0**；
+  - `-v` / `--version` 在**主命令层**可用，输出到 stdout，退出码 0；
+  - 帮助文本是**单一来源**——由 argparse 从解析器定义生成；`help` 子命令与 `-h/--help` 必须输出**完全一致**的文本，**禁止**另外维护一份手写帮助字符串；
+  - 用法错误输出到 **stderr** 且退出码非 0；`help <未知命令>` 同样如此。
+
+---
+
+## 四、配置与数据正确性
+
+### 4.1 配置结构
+
+- **必须**：配置为 INI 格式、人类可读；新增配置项同步更新 `gitwebhooks.ini.sample`。
+- **必须**：配置文件查找优先级为 `~/.gitwebhooks.ini` > `/usr/local/etc/gitwebhooks.ini` > `/etc/gitwebhooks.ini`；该顺序以 `utils/constants.py` 的 `CONFIG_SEARCH_PATHS` 为唯一出处，不得在别处硬编码路径列表。
+- **必须**：找不到配置文件时给出**明确**错误信息（含已尝试的路径），不得静默使用默认值继续启动。
+- **必须**：缺失的必需配置项在**启动时**报错退出，不得推迟到收到 webhook 时才失败。
+
+### 4.2 数据正确性
+
+- **必须**：对外部输入（请求体、Header、配置值）做显式校验后再使用；不得依赖「调用方一定传对」。
+- **必须**：JSON 路径提取（如 custom 平台的 `identifier_path`）在路径不存在时返回明确失败，不得抛未捕获异常。
+- **必须**：命令执行使用仓库配置的 `cwd`，不得使用进程继承的当前目录。
+
+---
+
+## 五、安全与数据保护
+
+### 5.1 凭据
+
+- **必须**：密钥 / token **只**存在于配置文件，**禁止**硬编码进源码、测试或文档示例（示例值一律留空或写占位路径）。
+- **必须**：生成的配置文件权限为 **0600**（仅属主可读写）。
+- **禁止**：把 secret / token 原文写入日志或错误输出。日志中出现配置值时，敏感字段必须脱敏；敏感字段判定以 `utils/constants.py` 的 `SENSITIVE_KEYWORDS` 为准。
+- **必须**：`config view` 对敏感字段做高亮 / 提示，且**不得**改变「本地可读」这一前提去新增网络出口。
+
+### 5.2 命令执行
+
+- **必须**：执行命令使用 `shell=True` 时必须确认命令来源**仅为本地配置文件**（信任边界），并在代码注释中写明该前提。
+- **禁止**：将 webhook 请求体中的任意内容拼进待执行命令（命令注入）。
+- **必须**：命令执行失败（`OSError` / `SubprocessError`）记录 warning 并继续服务，不得让异常冒泡终止 HTTP 处理线程。
+
+### 5.3 请求与传输
+
+- **必须**：webhook 端点拒绝不支持的方法（如 GET 返回 403）。
+- **必须**：支持的各平台签名验证逻辑不得被静默跳过；`verify=False` 是**配置显式选择**，不是代码默认省略校验。
+- **必须**：SSL 证书与私钥路径在服务器启动前校验；文件缺失 / 不可读时明确报错。
+- **建议**：服务以非特权用户运行。
+
+---
+
+## 六、测试
+
+### 6.1 框架与覆盖
+
+- **必须**：测试位于 `tests/`，单元测试在 `tests/unit/`，端到端 / 集成测试在 `tests/integration/`，共享夹具在 `tests/fixtures/`，测试工具在 `tests/utils/`。
+- **必须**：测试可同时被 `unittest` 与 `pytest` 驱动——**导入了 `pytest` 的测试文件属于已知偏差**，不得新增；新测试统一用 `unittest.TestCase` 编写（`pytest` 仅作为可选的运行器）。
+
+  > **已知存量偏差**：`tests/unit/test_main.py`、`tests/unit/test_config_level.py`、`tests/unit/test_install_service_logic.py`、`tests/unit/test_service_install_context.py`、`tests/unit/test_prompts_config_level.py`、`tests/unit/cli/test_init_wizard.py`、`tests/integration/test_config_discovery.py` 直接 `import pytest`，导致无 pytest 环境下 **7 个测试模块整体无法导入**。修复方向是移除 `pytest` 依赖（改用 `unittest`），作为独立任务登记。
+
+- **必须**：Bug 修复附带**能复现该 bug 的测试**（先 Red 后 Green）。
+- **必须**：修改平台逻辑时，覆盖该平台的签名验证（成功 + 失败）与仓库识别路径。
+- **必须**：测试不得依赖外部网络、真实 Git 平台或固定端口（端口从 `get_free_port()` 之类的辅助函数获取）。
+
+### 6.2 验证纪律
+
+- **必须**：交付前真跑测试并**如实区分**「本机真跑过 / 只做了静态检查 / 未执行」；不得用「已验证」笼统概括。
+- **禁止**：吞输出——可能失败的命令不得 `>/dev/null`、`2>/dev/null`、`-q`；失败时输出是唯一线索。
+- **必须**：声称「测试通过」时给出**实际计数**（跑了多少、失败多少、跳过多少），并说明运行环境是否具备 `pytest`。
+- **禁止**：把「未安装依赖导致的导入错误」当作「改动引入的失败」，也**禁止**反过来把它当作正常基线而不报告。
+
+---
+
+## 七、工具链与质量门禁
+
+### 7.1 门禁命令
+
+| 目的 | 命令 | 说明 |
+|------|------|------|
+| 全量测试 | `python3 -m tests` | 项目自带 runner（`unittest` 驱动） |
+| 静默测试 | `python3 -m tests -q` | 仅输出摘要 |
+| 失败即停 | `python3 -m tests -f` | 快速定位 |
+| pytest 驱动（可选） | `python3 -m pytest tests/` | 需另装 `pytest`；非必需路径 |
+| 语法检查 | `python3 -m compileall -q gitwebhooks` | 快速静态校验 |
+
+- **必须**：交付前至少跑通 `python3 -m compileall -q gitwebhooks` 与爆炸半径内的测试。
+- **禁止**：以「pytest 未安装」为由跳过测试并声称通过（见 §6.2）。
+
+### 7.2 发布
+
+- **必须**：发布 PyPI **前**运行 `./scripts/pre-release-check.sh` 并全部通过；**禁止**跳过。
+- **必须**：版本号在 `pyproject.toml` 与 `gitwebhooks/__init__.py` 的 `__version__` **两处同步**；两处不一致视为 P1 缺陷。
+
+  > 这是一处已知的双源风险（无自动同步机制）。改版本时必须两处都改，并在提交前 `grep` 复核。
+- **必须**：发布流程 = ① 跑 `pre-release-check.sh` → ② 两处改版本号 → ③ 行为变更时更新两个 README → ④ 打语义化版本 tag → ⑤ 构建并上传。
+- **禁止**：未跑校验脚本就上传 PyPI。
+
+---
+
+## 八、文案与双语文档
+
+- **必须**：`argparse` 生成的帮助与错误文案使用**英文**；交互式向导与 `config` 子命令的面向用户提示使用**中文**（与现有实现一致，见 §2.1）。
+- **必须**：`README.md`（英文）与 `README.zh.md`（中文）描述同一事实；修改一处**必须**同步检查另一处，不得只改一边。
+- **禁止**：README 或任何用户可见输出中引用不存在的子命令或已删除的动作（如历史上的 `service`）——这属于 §3.2 的死引用，见 §10.3 审查矩阵。
+- **必须**：README 中的配置示例与 `gitwebhooks.ini.sample` 保持一致。
+
+---
+
+## 九、Agent 与工作流纪律
+
+### 9.1 计划与范围
+
+- **必须**：动手前先读代码验证事实，不假设 API / 文件存在（文档优先）。
+- **必须**：任务拆分为可独立验证的单元；涉及 3+ 文件或 30 分钟以上时拆分。
+- **禁止**：反复猜测试错（No Guess-Retry Loop）——遇报错先查权威来源（Python 官方文档、本项目 `README*.md` 与本宪章），确认根因再用最小复现验证。
+
+### 9.2 委派
+
+- **建议**：静态代码审查派给只读的审查者（加载 `.dsh/skills/code-review/SKILL.md`），影响面调研派独立的探索任务；**产出（代码与文档）一律由主代理完成**。
+- **必须**：只读审查者**不得**被授予写权限；其结论中的「必须运行才能确认」项标注为「需主代理跑门禁确认」，**禁止**把推测写成已验证。
+
+### 9.3 Git 纪律
+
+- **必须**：提交信息格式为 `<类型>: <简短描述>`，使用中文；类型取 `feat` / `fix` / `docs` / `refactor` / `test` / `chore`。
+- **禁止**：提交信息中出现 AI 归属签名、推广内容或 emoji（如 `🤖 Generated with ...`、`Co-Authored-By:` 形式的 AI 署名）。
+- **必须**：一次提交只含一项已完成的工作；**禁止**夹带无关文件。
+- **必须**：提交前确认改动通过其对应门禁（§7.1）；未过门禁的改动不得提交。
+- **禁止**：未经用户明确授权执行 `git commit` / `git push` / 改写历史。
+
+---
+
+## 十、修订与合规
+
+### 10.1 修订流程
+
+1. 记录拟修改内容与理由；
+2. 更新本文件并递增版本号；
+3. 同步 `AGENTS.md` 与本宪章引用到的其它文档；
+4. 以本次修订的口径复查存量代码的合规性。
+
+版本号遵循语义化版本：**MAJOR** = 原则移除或治理性不兼容变更；**MINOR** = 新增原则或实质性扩展；**PATCH** = 措辞澄清。
+
+### 10.2 合规分级
+
+审查发现按下列分级处理：
+
+| 级别 | 定义 | 处理 |
+|------|------|------|
+| **A（必须修）** | 违反 MUST / MUST NOT（安全、数据正确性、架构不变量、死代码、凭据泄露） | 阻塞交付，修复后**重跑门禁** |
+| **B（应当修）** | 违反 SHOULD，或存量偏差被本次改动**扩大** | 本轮修复或登记 backlog |
+| **C（可登记）** | 存量偏差、不影响本次改动的风格问题 | 登记跟踪，不阻塞交付 |
+
+- **必须**：存量偏差（本宪章已标注的「已知存量偏差」）不因一次无关改动而阻塞；但**扩大**既有偏差属于 A 级。
+
+### 10.3 审查矩阵
+
+| 改动类型 | 审查口径 |
+|----------|----------|
+| Python 源码 | 全套清单（宪章 → 分层 → 规模 → 安全 → 测试） |
+| CLI 子命令增删 | 额外核对**所有**引用点（注册、帮助、两个 README、脚本、测试）——见 §3.2 |
+| 配置项增删 | 额外核对 `gitwebhooks.ini.sample`、`RESERVED_SECTIONS`、两个 README |
+| 纯文档 | 只需文档一致性核对（双语文档同步、命令 / 配置示例真实存在、无悬空引用） |
+| 版本发布 | 额外核对两处版本号同步与 `pre-release-check.sh` 通过 |
+
+### 10.4 审查拒绝
+
+- 审查者**只报不改**；不得在审查中顺手修复。
+- 同一改动对 P2 / P3 只报一次，登记后放行；P0 / P1 修复后**重跑门禁**，不重跑同一审查实例。

{gitwebhooks-2.3.1 → gitwebhooks-2.4.1}/MANIFEST.in

@@ -1,7 +1,8 @@
 include README.md
 include README.zh.md
 include LICENSE
-include CLAUDE.md
+include AGENTS.md
+include CONSTITUTION.md
 include *.editorconfig
 include *.sample
 recursive-include doc *.png