diff --git "a/docs/\345\217\257\350\247\202\346\265\213\346\216\245\345\205\245\346\214\207\345\215\227.md" "b/docs/\345\217\257\350\247\202\346\265\213\346\216\245\345\205\245\346\214\207\345\215\227.md"
index d457920..a4f78e8 100644
--- "a/docs/\345\217\257\350\247\202\346\265\213\346\216\245\345\205\245\346\214\207\345\215\227.md"
+++ "b/docs/\345\217\257\350\247\202\346\265\213\346\216\245\345\205\245\346\214\207\345\215\227.md"
@@ -671,6 +671,103 @@ Service 端口名命中白名单即可，无需写 job。以 oauth2-proxy 为例
 
 一期的两个适配器同步落地：GitHub 先行，GitCode 在 `Source` 接口定稿后并行接入。**契约与接口必须一次到位**——`platform` 标签、枚举归一、排序键抽象晚加等于全部序列换名。GitCode 接口实测若有阻塞，允许它的适配器在一期后段交付，但不允许先只做 GitHub 再回头改契约。
 
+#### 5.3.1 告警内容
+
+一期产出两类面向人的告警：**结果层**（workflow 失败）与**在途层**（排队过久）。自监控类告警（凭据失效、采集停摆等，见 5.2.3）规则形态相同，不在此重复。两条规则都在中心 Prometheus 评估，经 Alertmanager 发邮件。
+
+**失败告警**：只对门禁类 run 逐次告警（`schedule` / `push` / `workflow_dispatch`），PR 触发的失败不逐次报——实测单个仓约 1 次失败/小时，逐次报会淹没通知，PR 作者侧 GitHub 本来就会显示红叉。
+
+```yaml
+- alert: CIWorkflowRunFailing
+  expr: |
+    increase(ci_workflow_run_result_total{
+      conclusion="failure",
+      event=~"schedule|push|workflow_dispatch"
+    }[5m]) > 0
+  for: 1m
+  labels:
+    severity: critical
+    cluster: central
+  annotations:
+    summary: "{{ $labels.repo }} / {{ $labels.workflow }} 执行失败"
+    description: >-
+      仓库 {{ $labels.repo }}（{{ $labels.platform }}）的 workflow「{{ $labels.workflow }}」
+      在最近 5 分钟内出现失败，触发方式 {{ $labels.event }}。
+      指标不含 run 身份，请在 GitHub Actions 里按 workflow 名查最近一次红叉。
+    runbook: >-
+      1) 打开 https://github.com/{{ $labels.repo }}/actions 按 workflow 名筛选，定位失败 run；
+      2) 判断是代码问题、flaky 用例还是 runner 未启动（startup_failure）；
+      3) 若是定时/主干门禁连续失败，先恢复 main，再复盘。
+```
+
+用户收到的邮件（时延约 1～2 分钟）：
+
+> **主题**：`[CRITICAL][central] CIWorkflowRunFailing`
+>
+> **🔴 FIRING — CIWorkflowRunFailing @ central**
+>
+> | 字段 | 内容 |
+> | --- | --- |
+> | 集群 | central |
+> | 告警 | CIWorkflowRunFailing |
+> | 状态 | firing |
+> | 开始时间 | 2026-10-26 09:12:33 CST |
+> | 描述 | 仓库 vllm-project/vllm-ascend（github）的 workflow「Main2Main」在最近 5 分钟内出现失败，触发方式 schedule。指标不含 run 身份，请在 GitHub Actions 里按 workflow 名查最近一次红叉。 |
+>
+> **修复建议**
+>
+> 1) 打开 https://github.com/vllm-project/vllm-ascend/actions 按 workflow 名筛选，定位失败 run；2) 判断是代码问题、flaky 用例还是 runner 未启动（startup_failure）；3) 若是定时/主干门禁连续失败，先恢复 main，再复盘。
+>
+> `Alertmanager | 监控看板 | 本邮件由 CI 基础设施监控系统自动发送，请勿回复。`
+
+恢复后再发一封，主题变 `[RESOLVED][central] CIWorkflowRunFailing`，正文标题变 `✅ RESOLVED`，并多一行「恢复时间」。
+
+**排队过久告警**：告警对象是仓库，不是单个 run——指标按仓聚合，取的是该仓最久的排队时长。
+
+```yaml
+- alert: CIWorkflowQueueBacklog
+  expr: ci_workflow_oldest_queued_age_seconds > 1800
+  for: 10m
+  labels:
+    severity: critical        # 定 warning 会被中心黑洞吞掉，见下文「模板约束」
+    cluster: central
+  annotations:
+    summary: "{{ $labels.repo }} 有 run 排队超过 30 分钟"
+    description: >-
+      仓库 {{ $labels.repo }}（{{ $labels.platform }}）队列积压：最久的 run 已等待
+      {{ $value | humanizeDuration }}。常见原因是仓库并发上限已满或 runner 池没有空闲机器。
+    runbook: >-
+      1) 看同仓 runs_queued 是否持续上涨；
+      2) 查 ARC 对应 scale set 的 desired/running runner 是否卡在 0；
+      3) 若是长期排队而非故障，考虑调高该仓 concurrency 或扩卡池。
+```
+
+用户收到的邮件（时延约 7 分钟：B 路径 5 分钟轮询 + 抓取 + 评估）：
+
+> **主题**：`[CRITICAL][central] CIWorkflowQueueBacklog`
+>
+> **🔴 FIRING — CIWorkflowQueueBacklog @ central**
+>
+> | 字段 | 内容 |
+> | --- | --- |
+> | 集群 | central |
+> | 告警 | CIWorkflowQueueBacklog |
+> | 状态 | firing |
+> | 开始时间 | 2026-10-26 10:28:10 CST |
+> | 描述 | 仓库 vllm-project/vllm-ascend（github）队列积压：最久的 run 已等待 47m0s。常见原因是仓库并发上限已满或 runner 池没有空闲机器。 |
+>
+> **修复建议**
+>
+> 1) 看同仓 runs_queued 是否持续上涨；2) 查 ARC 对应 scale set 的 desired/running runner 是否卡在 0；3) 若是长期排队而非故障，考虑调高该仓 concurrency 或扩卡池。
+
+**模板约束**（中心 Alertmanager 现有 `email.infra.html`，接入前必须处理）：
+
+- **`cluster` 标签不能缺**。主题模板是 `[{{ severity }}][{{ cluster }}] {{ alertname }}`，正文标题是 `@ {{ cluster 或 project }}`；两者都没有时会渲染成 `[CRITICAL][] …` 和 `@ `。规则里显式写 `labels: cluster: central`，或给 CI 告警单独一个 receiver 改用 `{{ or .CommonLabels.cluster .CommonLabels.repo }}`（`datastat-email` 已是这种写法）。
+- **`severity: warning` 默认被黑洞丢弃**（路由树在 warning 之前没有 CI 前缀规则）。新告警要么定为 critical，要么在黑洞之前补 `alertname =~ "CIWorkflow.*"` 的路由。
+- **`repo` / `workflow` / `platform` 不会出现在表格里**：模板只渲染 `cluster` / `project` / `pod` / `node` / `instance` / `deployment` / `mount` / `endpoint`。要么把定位信息写进 `description`（上面两条就是这么做的），要么给模板加「仓库 / Workflow / 平台」三行。
+- **`runbook` 必填**：模板的「修复建议」表直接引用 `.Annotations.runbook`，缺了就是一格空白。
+- **`group_by` 要加维度**：根路由是 `[cluster, alertname]`，同一仓多个 workflow 失败会被并进同一封（`group_interval` 30 分钟）；需要按 workflow 分开时，在 CI 路由里改为 `[platform, repo, workflow, alertname]`。
+
 ### 5.4 详细设计
 
 #### 5.4.1 中心 aggregator
@@ -788,6 +885,15 @@ B+ 的调用量随活跃 run 数走（20~40 个 × 12 次/小时 ≈ 240~480 次
 | B+ | 20~40 个活跃 run × 12 | 240~480 |
 | 合计 | | **约 2,000~2,250（45%）** |
 
+表中「21 仓」是**开通了 ARC runner 的仓库数**，不是集群数也不是 scale set 数：它取自
+`opensourceways/ascend-ci-deployment` 仓 `projects/<org>/<repo>/` 下存在 `values.yaml` 的目录，
+按 `<org>/<repo>` 去重（一个仓可以有多个 scale set，只算一次），快照于该仓 commit `26ca84d1`（2026-10-20）。
+集群文档站的 [Cluster Map](https://ascend-gha-runners.github.io/docs/Cluster/) 由同一份部署配置自动生成，
+页面上标注的「21 Projects」与此一致，可用来交叉核对；部署新增仓库时按实际仓数线性重算这张表。
+
+其余系数：A 的 60 = 每分钟一轮 × 60 分钟；B 的 12 = 每 5 分钟一轮 × 12，两条列表指 `queued` 与 `in_progress`；
+B+ 的 12 同理，基数是该时刻在途的 run 数（实测 20~40）。
+
 GitCode 的限流规则未公开，接入前要实测；适配器里要有独立的配额余量指标。
 
 **两个适配器的差异**