Files
WebHooker/docs/zh/guide/message-format.md
T
RhenCloud e607d41432 feat(workflow): render workflow_run jobs as colored diff block
List each job on its own line with a status emoji and, for completed
jobs, the duration. Discord colors the diff fence: '+' green for
success, '-' red for other finished conclusions, plain for
running/queued/pending. Telegram/Feishu collapse it to inline code.

Sync AGENTS.md, README(s), docs guide and supported-events tables.
2026-09-26 14:58:00 +08:00

50 lines
3.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 消息格式
每个事件格式化器都会产出一条平台中立的消息(`NeutralMessage`),由平台驱动渲染为 Discord 嵌入或 Telegram HTML 消息。
## 标题
每个标题必须以仓库名开头,随后是可选的 `#number`,再是 `: 描述`:
```
{repo}{#number}: {subject} 例如 acme/widget#7: Add feature
```
仓库名取自 `payload.repository.full_name`(缺失时回退为通用的「repository」标签)。评论、审查与行内评论使用与其父对象相同的 `{repo}{#number}: {title}` 标题——绝不使用 `"Comment on org/repo"` 前缀。
## 链接
只有仓库头会被加超链接——整条标题永远不会整体链接:
- **Discord**(嵌入标题不支持局部链接):标题为仓库头 `{repo}{#number}`,链接到仓库;`: {subject}` 文本作为描述首行渲染,不带链接。
- **Telegram**(HTML 支持行内链接):单行标题保留描述文本,仅仓库头被包在链接中。
标题中不含冒号分隔符(`:` 后跟一个空格)的消息保持旧的整行链接行为。
提交哈希、分支与标签渲染为带超链接的行内代码(如 ``[`abc123d`](https://…/commit/abc123def456)``),仓库基地址不可用时回退为纯行内代码。
## 表情
事件专属表情由格式化器添加;分组级 `Group.emoji`(默认开启)关闭后会全部去除。里程碑进度条不受影响。见[消息语言](./i18n)。
## 来源平台标识
设置 `Group.forgeSources`(一组 `{ host, type, name? }` 条目)后,消息底部会标注匹配的来源——即 `type`(`github` / `gitea`)与事件来源一致、且 `host` 与仓库 URL 主机名一致的第一条配置,标识文本为其可选 `name`(未填回退为 host)——便于区分来自不同 forge 的事件。见[分组 → 来源平台标识](./groups#来源平台标识)。
## 原地更新
`workflow_run` 与 `check_run` 消息只发送一次,随运行进度原地编辑(queued → running → success/failure),不会重复发消息。追踪使用 KV `msg:*` 与每次运行的稳定 `updateKey`:`workflow_run` 以 workflow id 为键,`check_run` 则以 check 名 + commit SHA 为键(回退到 run id),因此每个阶段都换新 run id 的部署(例如 Cloudflare Pages)仍会编辑同一条消息。
## Workflow 作业
`workflow_run` 消息包含一个 **Jobs** 字段,以带颜色的 diff 代码块列出该次运行的全部作业(Discord):
```
+ build ✅ success · 1m 23s
deploy 🔄 running
lint ⏳ queued
- test ❌ failure · 0m 45s
```
每行格式为 `{作业名} {emoji}{状态}`,作业完成后追加耗时。成功的作业以 `+` 前缀(绿色),失败/其他已结束的作业以 `-` 前缀(红色),运行中/排队中/待定的作业使用普通空格(无颜色)。作业名截断至 200 字符,整个字段截断至平台字段上限。不支持 diff 的驱动(Telegram、飞书)会把该代码块渲染为单个行内代码片段。