diff --git a/docs/design/18-toolchain-e2e-test.md b/docs/design/18-toolchain-e2e-test.md
new file mode 100644
index 0000000..56c2fa8
--- /dev/null
+++ b/docs/design/18-toolchain-e2e-test.md
@@ -0,0 +1,48 @@
+# §18. 工具链端到端验证测试
+
+> 日期：2026-06-09
+> 状态：执行中
+> 目标：用真实 Webhook 触发验证整条 Mail 通知链路
+
+## 前置确认
+
+- Gitea 用户名 ↔ Agent ID 映射：完全一致（admin, guanyu-dev, jiangwei-infra, pangtong-fujunshi, simayi-challenger, zhangfei-dev, zhaoyun-data）
+- Gitea 组织级 Webhook（Hook ID=28）：姜维确认最近 5 条投递全部 is_succeed=1
+- Daemon 在线：sanguo-moziplus-v2 运行中
+- 测试仓库：sanguo/moziplus-v2
+
+## 命名规范
+
+- Issue 标题：`[E2E-TEST] xxx`
+- PR 标题：`[E2E-TEST] xxx`
+- 分支名：`test/e2e-<timestamp>`
+
+## 验证步骤
+
+| 步骤 | 操作 | 触发事件 | 预期 Mail 通知 | 验证点 |
+|------|------|----------|---------------|--------|
+| 1 | 创建 Issue `[E2E-TEST] Issue指派测试`，assignee=zhangfei-dev | issues (assigned) | zhangfei-dev 收到 "Issue 指派" Mail | Mail to/模板正确 |
+| 2 | 开分支 `test/e2e-<ts>`，创建 PR `[E2E-TEST] Review请求测试` | pull_request (opened) | simayi-challenger 收到 "Review 请求" Mail | Mail to/风险级别/文件列表 |
+| 3 | PR Review APPROVED | pull_request_review (approved) | PR 作者(pangtong-fujunshi) 收到 "Review 通过 ✓" Mail | result=通过 ✓ |
+| 4 | PR Review REQUEST_CHANGES | pull_request_review (rejected) | PR 作者收到 "Review 驳回 ✗" Mail | result=驳回 ✗ |
+| 5 | Issue 上发评论 `[CI] CI 失败 — 分支: test/e2e-xxx, 错误: build timeout` | issue_comment | Issue 作者收到 "CI 失败" Mail | 模板含分支/错误摘要 |
+| 6 | 创建标题含"部署失败"的 Issue（无指派） | issues (opened) | jiangwei-infra + pangtong-fujunshi 各收到 "部署失败" Mail | 双收件人 |
+| 7 | 关闭步骤 1 的 Issue，再发 CI 失败评论 | issue_comment (closed issue) | 不产生 Mail（负面测试） | handler 跳过 closed |
+| 8 | 重发步骤 1 Webhook（相同 delivery ID） | 重复事件 | 不产生新 Mail（幂等测试） | 返回 duplicate |
+
+## 签名校验
+
+暂不测试（需恢复 GITEA_WEBHOOK_SECRET）。
+
+## Review 意见来源
+
+- 姜维（基础设施确认 + 边界验证建议）
+- 司马懿（遗漏点补充 + 命名规范 + 风险防范）
+
+---
+
+## 执行记录
+
+> 以下由自动化测试脚本填写
+
+（待填写）