# Combot Automation Compact v3：LLM 指南和格式参考

请将本文件全文与规则需求一起提供给模型。它描述自动化编辑器接受的导入格式。规则语言是 Compact v3 JSON，不是 Python、YAML、JavaScript、旧版 Triggers v2，也不是任意“如果 → 那么”伪代码。
界面中的名称会翻译，但 JSON 值保持不变。例如，`Known Combot links` 对应编辑器中的“Combot 邀请链接”，`Combot custom admins` 对应“Combot 管理员”。不要用界面名称替换这些 JSON 值。

文档修订日期：2026 年 9 月 9 日。本参考已对照自动化编辑器和处理程序核对。完成的导入与 Telegram 检查在末尾单独列出：查看源码不能确定正在运行的服务版本。

## 1. 给模型的指令

将用户需求转换为自动化规则，不改变其含义。

1. 明确事件、条件、排除项、操作、操作接收者和回复目的地。涉及时间表时明确时区；涉及命令时明确是单独发送还是作为回复发送。除非用户要求，否则不要添加管理措施、奖励、随机性或删除。
2. 不要猜测用户 ID、话题、群聊地址、邀请、等级或已启用功能。话题名称不是 ID。缺少必要信息时请提问。可以单独提出回复措辞方面的假设，但不能将不完整规则说成准确解决方案。
3. 新规则始终生成 `en: false`。这是安全准备的约定，不是自动化本身的限制。省略 `en` 表示启用。
4. 只使用已记录的字段。对于标注“使用导出”的嵌套筛选，请索要类似配置的真实导出，不要编造结构。如果场景不受支持，请说明限制，不要通过删除条件掩盖问题。
5. 按“简短解释 → 一个可导入 JSON 代码块 → 手动设置和检查”回复。JSON 不得包含注释、省略号、占位 ID、字段外的解释行、尾随逗号，或 `when`、`if`、`then`、`conditions`、`actions`、`event` 等编造的键。
6. 返回结果前，推演一个匹配案例和一个不匹配案例。对于回复命令，请分别检查命令发送者与原消息作者。除非确实做过，否则不要声称已在 Combot 中测试规则。

配套 JSON Schema 用于辅助生成新的已禁用规则。其必填字段刻意比导入要求更严格，也不接受所有旧导出。复杂嵌套筛选只检查是否为对象。通过模式校验不能证明条件兼容、资源可用、符合套餐限制，或 Telegram 操作成功。

## 2. 应向导入框粘贴什么

根结构是一个对象，包含数字 `v: 3` 和规则数组 `t`。通常只返回一条规则。不要返回裸数组或 `{"triggers": [...]}`，它们不是导入对话框要求的格式。

一个完整的最小示例：

```json
{
  "v": 3,
  "t": [
    {
      "n": "课程信息命令",
      "en": false,
      "k": "c",
      "ctm": "p",
      "cm": ["/course_info"],
      "a": {
        "m": "a",
        "r": [
          {
            "i": "course_reply",
            "t": "s",
            "v": {
              "tx": "课程录播在群聊的置顶消息中。",
              "rp": "r"
            }
          }
        ]
      }
    }
  ]
}
```

`dv: "t3.compact.3"` 是可选的模式标记。新结果只需要 `v` 和 `t`。现有导入识别 `bundle` 包装，但生成时不需要使用。

不要在导入包内添加服务器 `id`、`revision`、`chat_id`、计算出的 `ck` 或 `$schema`。服务器会分配新的规则 ID。操作中的 `i` 不同，它是 `course_reply` 之类的本地行标识符，必须在该规则的操作中唯一，由 1–80 个拉丁字母、数字、`_` 或 `-` 组成。

同一个短键在不同层级有不同含义：根级 `t` 是规则列表，`a.r[].t` 是操作类型，`a.r[].v` 保存操作参数。不要混淆层级。

## 3. 规则主要字段

| 字段 | 含义 |
| --- | --- |
| `n` | 非空名称，编辑器中最多 80 个字符 |
| `d` | 可选描述，编辑器中最多 280 个字符 |
| `en` | 新的已禁用规则使用 `false` |
| `e` | 事件代码数组，命令除外 |
| `k`、`cm`、`ctm` | 命令模式，见下文 |
| `a` | 操作计划：`{"m":"a","r":[...]}` 或 `{"m":"r","r":[...]}` |
| `s`、`ti` | 在哪里检查事件：来源群聊、常规区域或指定话题 |
| `at` | 允许匹配的时间，是时间筛选而非计时器 |
| `wh`、`wx`、`wm` | 事件执行者：包含的组、排除项，以及组的组合方式 |
| `cgr` | 数值条件：入群时长、消息、警告、XP、声望 |
| `ua`、`ux`、`uar`、`ul`、`ulx` | 成员属性、字段值和语言 |
| `twh`、`twx`、`tcg`、`tua`、`tux`、`tur`、`tlg`、`tlx` | 检查事件中的另一位用户，例如被回复消息的作者或加入的成员 |
| `tv`、`tr`、`ty`、`cs`、`lmin`、`lmax` | 文本条件 |
| `mti`、`mtx`、`me`、`mex` | 消息类型和文本实体 |
| `il`、`ilc`、`ilx` | 入群申请的邀请链接 |
| `rct`、`rnt`、`rnx`、`rcy`、`rcx`、`rcn`、`rcm` | 回应条件 |
| `chl` | 指定任务清单的直接链接，用于该清单的任务变化事件 |
| `cl` | 默认的上一条回复清理：`n` 或 `ps` |
| `ov` | OR 分支条件集；复杂情况使用导出 |

不要填满每个字段。只添加用户要求且与所选事件相关的条件。例如，加入事件不需要消息关键词，汇总回应计数也没有可供自动奖励的特定用户。

## 4. 事件

| `e` | 何时运行 |
| --- | --- |
| `["m"]` | 新群聊消息 |
| `["em"]` | 消息编辑 |
| `["m","em"]` | 新消息或编辑 |
| `["lc"]`、`["el"]`、`["lc","el"]` | 关联频道的评论、编辑，或两者 |
| `["cp"]`、`["ec"]`、`["cp","ec"]` | 关联频道上下文中的帖子、编辑，或两者 |
| `["jr"]` | 入群申请 |
| `["nm"]` | 成员加入 |
| `["ml"]` | 成员离开或被移出 |
| `["cb"]`、`["rb"]` | 添加或移除助力 |
| `["mr"]` | 特定用户的回应发生变化 |
| `["rc"]` | 关联频道上下文中的匿名汇总回应计数更新 |
| `["ck"]` | 新建任务清单 |
| `["cd"]` | 清单任务被标记为完成 |
| `["ca"]` | 清单任务新增 |

不要组合 `["m","nm"]` 之类不相关的事件类型，请使用独立规则。允许使用上面列出的新建与编辑配对。不要生成隐藏的访客机器人模式 `gm`。

编辑是一次独立触发。对于 XP、声望、警告，或用户期待只发生一次的其他操作，不要自动添加编辑事件。

## 5. 普通命令和回复命令

普通命令，例如信息回复：

```json
{"k":"c","ctm":"p","cm":["/course_info"]}
```

管理员作为对成员消息的回复发送的命令：

```json
{"k":"c","cm":["/team_pause"]}
```

这些是规则字段片段，不是可单独导入的设置包。

不要为命令添加 `e`。在 `cm` 中提供非空的小写自定义斜杠命令列表，使用拉丁字母、数字和 `_`。不要将自己拟定的命令描述为 Combot 内置命令。对于回复命令，省略 `ctm`；不要在该字段写 `reply_target`、`r` 或人名。

普通命令没有用户操作的接收者。应使用发送消息，并且只有用户明确要求时才删除命令消息。禁言、警告、XP 及其他作用于人的操作需要回复命令。

在回复命令中，`wh` 检查命令发送者，`twh` 和其他 `t...` 字段检查被回复消息的作者。使用 `v.tg: "t"` 对后者执行操作。如果安娜回复伊利亚并发送 `/team_pause`，应限制伊利亚，而不是安娜。

只检查 `twh` 不会限制谁可以执行命令。管理员命令必须根据需求包含 `wh`。操作 `d` 删除的是命令本身，不是伊利亚的消息。

不要用 `tv` 中对 `/team_pause` 字符串的搜索替代命令模式。没有经核实的导出时，不要添加编辑器隐藏的命令条件，例如时间表。

## 6. 成员和排除项

`wh` 和 `wx` 使用以下精确字符串，不使用翻译后的标签：

`New members`, `Regular members`, `Ex-members`, `Whitelisted users`, `Admins`, `Telegram admins`, `Combot custom admins`, `Owner`.

包含列表为空时，不限制用户组。通常可以省略 `Anyone`。`wm: "o"` 要求匹配任意一个组；`wm: "a"` 要求匹配全部选定组。`wx` 中的排除项无论正向组是否匹配，都会阻止匹配。

示例：除管理员外，任何人都可以发送匹配消息：

```json
{"wx":["Telegram admins","Combot custom admins","Owner"]}
```

示例：只有 Telegram 管理员或群主可以执行命令：

```json
{"wh":["Telegram admins","Owner"],"wm":"o"}
```

不要混淆角色。`Combot custom admins` 描述的是 Combot 权限，不是 Telegram 管理员。在处理程序中，`Admins` 与 `Telegram admins` 一样，检查包含群主在内的 Telegram 管理员，不会额外包含 Combot 管理员。如果两组都允许，请同时列出 `Telegram admins` 和 `Combot custom admins`，并使用 `wm: "o"`。`Regular members` 表示已知的当前成员，而不是入群很久或发言很多的人。`New members` 使用群聊已有的新人设置与豁免，并非固定的“最初七天”。精确时长请使用 `cgr`。

不要生成 `Core members` 或 `Non-members`，因为没有为新规则提供可靠定义。缺少成员信息不能证明某人从未加入过群聊。

目标用户使用 `twh`、`twx` 和 `twm`。`Target self`、`Target bots`、`Target Combot` 和 `Target linked channel post` 等额外上下文值，应从合适的导出中获取，不要在发送者筛选中猜测。

对于 `nm` 和 `ml`，`wh`/`wx` 描述发起加入或移出操作的人，`twh`/`twx` 描述状态发生变化的成员。如果安娜添加伊利亚，新人条件应通过 `t...` 应用于伊利亚，而不是安娜。为操作选择 `v.tg` 不会交换这些条件。

`am: "o"` 检查 Telegram 管理员，`am: "n"` 排除 Telegram 管理员。这不能替代 `wh`/`wx` 中的角色组合。新规则优先使用明确的用户组。

## 7. 入群时长、活跃度、XP 和声望

数值条件放在 `cgr` 中，目标用户则放在 `tcg` 中。下面的片段表示成员入群不超过一小时，且已记录消息不超过五条：

```json
{
  "cgr": {
    "logic": "All",
    "statistics": {
      "rules": [
        {"metric":"joinedDays","unit":"h","op":"lte","value":"1"},
        {"metric":"messageCount","unit":"c","join":"and","op":"lte","value":"5"}
      ]
    }
  }
}
```

运算符：`eq` 表示等于，`gte` 表示至少，`lte` 表示至多。始终明确写出运算符。不要将“少于五”转换为 `lte: 5`；对于整数计数器，应使用 `lte: 4`。如果用户的意思是“至少”，不要用精确时长的 `eq` 检查，因为时间一直在流逝。

统计指标：

- `joinedDays`：加入此群聊后的时长，不是账号年龄或用户年龄。单位：`s`、`m`、`h`、`d`、`w`、`mo`。一天为 24 小时，一周为 7 天，这里一个月为 30 天。新规则必须明确包含单位。
- `messageCount`：此群聊中已记录的消息数，单位 `c`。
- `warns`：有效警告数，单位 `c`。

“一条已记录消息”写作 `{"metric":"messageCount","unit":"c","op":"eq","value":"1"}`。这不保证恰好执行一次，因为计数更新与事件处理可能分开进行。

其他分区：

```json
{
  "cgr": {
    "logic": "All",
    "xp": {
      "xp": {"rules":[{"op":"gte","value":"100"}]}
    },
    "reputation": {
      "reputation": {"rules":[{"op":"gte","value":"5"}]}
    }
  }
}
```

等级阈值使用 `cgr.xp.rank.rules`，但值必须来自群聊真实等级，不能编造名称。行支持 `join: "and" | "or"` 和 `mode: "include" | "exclude"`。简单条件使用明确的 AND，复杂 AND/OR 链使用真实导出。`cgr.logic: "All" | "Any"` 用于组合分区。数值排除行是一项禁止条件：同一条件分支中另一个分区的正向匹配不能绕过它。

不要创建距首次消息或首次其他活动的时间检查：`firstMessageAge` 和 `firstOtherActivityAge` 不可用。不要用总计 `messageCount` 承诺“上周活跃度”。不可用的数据不能自动变成零。

## 8. 用户属性和字段

`ua` 要求属性存在，`ux` 排除属性。精确值为：`Any username`、`Telegram Premium`、`Bot account`、`Any last name`。例如，`{"ux":["Bot account"]}` 排除机器人。

`ul` 和 `ulx` 用于包含和排除 Telegram 提供的用户语言代码。这不是消息的语言或国籍。不要根据成员姓名推断语言。

具体值条件放在 `uar` 中，目标用户则放在 `tur` 中。支持字段：`user_id`、`name`、`username`、`last_name`、`bio`。简介属于入群申请上下文，不是每位成员始终可用的资料字段。

用户名条件的结构如下：

```json
{
  "uar": {
    "username": {
      "rules": [
        {"mode":"include","matchType":"Exact match","values":["example_member"]}
      ]
    }
  }
}
```

这里展示的是结构，不是真实成员。实际需求中，只使用用户提供的用户名，不带 `@`；缺失时请提问。`values` 中的 ID 应以字符串提供。访问控制优先使用明确提供的 ID，因为名字和用户名可能变化。

这里的 `matchType` 使用完整字符串 `Exact match`、`Partial match` 和 `Regular expression`，不是消息文本代码 `f`、`p` 和 `r`。同一行中的值是备选项，行之间有 `join`。不要为这些字段编造 `Starts with` 或 `Ends with`。

`ual` 和 `tul`：`a` 表示全部规则，`o` 表示任意一组。在本生成规范中，`uag` 和 `tug` 分组结构需使用导出。

## 9. 文本和消息类型

使用字符串数组 `tv` 搜索短语。一个字符串匹配就足够。例如：

```json
{"tv":["录播在哪里","课程录播"],"tr":"p","ty":"p","cs":false}
```

`tr`：`p` 表示短语，`w` 表示单词，`r` 表示正则表达式。单词模式不要求列表中的每个词都出现。普通部分匹配也不保证单词边界：英文“cat”可能匹配“catalog”中的内容。

`ty`：`f` 表示整段文本，`p` 表示部分文本，`s` 表示开头，`e` 表示结尾，`r` 表示正则表达式。`cs: true` 启用区分大小写，`false` 或省略则关闭。简单常见问题只需要 `tv`，默认是不区分大小写的短语搜索。

`lmin` 和 `lmax` 限制文本长度。边界为空或为零，表示该侧不限。不要混淆文本长度与单词数量。

只有简单匹配不足时才使用正则表达式。模式应作为 JSON 字符串提供，正确转义反斜杠；不要自动添加 JavaScript 的 `/.../i` 分隔形式。对于完整单词要求或复杂否定，请解释匹配与不匹配示例。

`mti` 包含消息类型，`mtx` 排除消息类型。主要值为：`photo`、`video`、`animation`、`audio`、`document`、`sticker`、`voice`、`video_note`、`contact`、`location`、`poll`、`dice`、`game`、`paid_media`。例如，`{"mti":["voice"]}` 表示语音消息；`{"mti":["photo","video"]}` 表示照片或视频，而不是同时具备两种附件。

编辑器还有 `text` 和 `caption`，它们参与文本内容设置；不要将 `caption` 当作独立的 Telegram 附件类型。对于“仅照片说明”或严格区分文本与媒体说明的需求，请获取相应配置的导出。编解码器可能省略默认值，包括单独的 `text`；仅在输入 JSON 中出现该值，不能证明限制在导入后仍保留。

`me` 和 `mex` 要求或排除文本实体。值为：`bot_command`、`url`、`text_link`、`mention`、`hashtag`、`cashtag`、`email`、`phone_number`、`emoji`、`custom_emoji`、`bold`、`italic`、`underline`、`strikethrough`、`code`、`pre`、`spoiler`、`blockquote`、`expandable_blockquote`。`mel: "a"` 要求所有包含的实体，`"o"` 要求至少一个。任意可见或隐藏链接可写作：`{"me":["url","text_link"],"mel":"o"}`。

`mef` 限定具体链接、命令和其他实体；`mmo` 描述媒体属性；`mtg` 和 `mog` 是条件组；`csx`/`cse` 是字符集。这些复杂字段应根据真实导出生成。不要编造 `max_file_size`、`allowed_domains`、`mime`、`language` 或 `contains_all` 等替代字段。

## 10. 时间和群聊话题

`s`：`sc` 表示来源群聊，`gn` 表示常规区域，`st` 表示指定话题。选择后者时，`ti` 包含正数话题 ID。

导入会将选定的来源话题重置为整个来源群聊，将选定的发送话题重置为当前话题。即使 ID 正确也会发生，OR 分支同样如此。如果场景依赖话题，请在说明和必需的手动设置中明确指出。重新选择话题之前，不要声称结果已可直接启用。

`at` 设置允许处理事件的时间，不会安排独立发送。“晚上回答问题”可以实现，“没有传入事件也每天 19:00 发帖”需要定时发布功能，不是这个触发器。

机器人处理事件时检查的是当前时间，而不是原消息时间戳。即使原消息在夜间发送，早晨编辑时也检查早晨时段。

每周时段，周一至周五，UTC 09:00–18:00：

```json
{"at":{"m":"w","wd":[0,1,2,3,4],"tw":[{"startMinute":540,"endMinute":1080}]}}
```

`wd`：0 表示周一，6 表示周日。时间是自 UTC 午夜起算的整分钟，范围 0 到 1439。每周时段包含最后一分钟。跨夜时段的开始值可以大于结束值；星期几使用当前 UTC 日期，不是“班次”开始的日期。请检查午夜两侧，而不是猜测应选哪些天。

莫斯科时间 09:00 和 18:00 对应 UTC 06:00 和 15:00，即第 360 和 900 分钟。要在 18:00 准时停止匹配，最后允许的一分钟是 UTC 14:59，即 `endMinute: 899`。其他时区需要考虑偏移和可能的夏令时变化。不要未经换算就把本地时间当作 UTC 输入。

日期区间：

```json
{"at":{"m":"d","s":"2026-10-01T00:00:00Z","e":"2026-10-07T23:59:59Z"}}
```

这些示例展示结构，不是用户活动的实际日期。开始必须早于结束，此模式包含两端边界。`Z` 表示 UTC。

关闭时段（Closing hours）使用群聊已有设置：`{"at":{"m":"c"}}`；时段之外使用：`{"at":{"m":"c","i":true}}`。关闭时段模式包含开始，不包含结束。触发器不会配置群聊的关闭时间表。没有有效时间表时，不要承诺正向或反向条件能够工作。

## 11. 邀请链接、回应和任务清单

### 邀请

对于入群申请 `["jr"]`，`il` 接受 `Known Combot links`、`External invite link` 或 `Any source`。无需限制时可省略。

`Known Combot links` 表示此群聊 Combot 目录中的链接。`ilc` 和 `ilx` 列出该目录内包含与排除的链接代码；准确代码应来自导出或用户提供的数据。列表为空时，仍保留整个类别检查。

`External invite link` 表示已识别、但不在整个 Combot 目录中的链接，不是“除了我选的两个链接以外的所有情况”。来源未知或目录不可用时，不能当作外部链接。不要承诺此条件能捕获每个没有已知邀请的申请。

### 用户回应

事件 `["mr"]`。`rct` 包含 `added` 和/或 `removed`。`rnt` 和 `rnx` 用于包含或排除用户新状态中的回应。只要其中任一字段非空，`rct` 就必须包含 `added`。

只有 Telegram 提供 `user` 时，处理程序才运行 `mr`。以频道或匿名管理员身份发送、带有 `actor_chat` 的回应不会触发此事件。这与汇总回应数量 `rc` 不同。

```json
{"e":["mr"],"rct":["added"],"rnt":["👍"]}
```

回应值可以是普通表情、自定义表情 ID 字符串，或 `paid`。`rnt` 检查完整的新状态，而不只是差异。如果原本已有 👍，用户又添加另一个回应，条件可能再次匹配。这里的操作接收者 `u` 是更改回应的人，不会自动奖励消息作者。

### 汇总回应数量

事件 `["rc"]`。`rcy`/`rcx` 选择统计的回应类型。`rcn`/`rcm` 以非负整数设置数量下限与上限。零或省略表示该侧没有边界。

```json
{"e":["rc"],"rcy":["👍"],"rcn":10}
```

它检查更新时的当前数值，不是“首次达到十”。另一次匹配更新可能再次执行操作。匿名汇总计数没有特定的回应用户。

### 任务清单

对于 `["cd"]` 和 `["ca"]`，`chl` 将规则限定到一份清单。如果用户需要特定清单，请索要其消息的直接链接。如果需要群聊或话题中所有匹配清单，不要添加 `chl`。

支持 Telegram 直接链接，包括带话题编号的链接；不支持含 `?comment=` 的链接。不要编造地址。对于公开链接，事件处理程序必须知道群聊用户名；URL 表面上有效，并不能证明匹配。

## 12. 操作

`a.m: "a"` 按顺序执行每一行。`a.m: "r"` 执行所有标有 `fr: 1` 的行，并从未标记行中恰好随机选择一行（如果存在）。选中行保留原有顺序。除非用户要求随机性，否则使用模式 `a`；不要在随机模式以外添加 `fr`。

| 代码 `a.r[].t` | 操作 | 参数 `v` |
| --- | --- | --- |
| `s` | 发送消息 | `tx` 和格式，见下文 |
| `d` | 删除触发规则的消息 | 无参数 |
| `w` | 添加警告 | `tg`、正数 `c`，通常为 1 |
| `rw` | 移除警告 | `tg`、正数 `c`，通常为 1 |
| `m` | 限制发言 | `tg`、以秒为单位的时长 `du` |
| `b` | 封禁 | `tg`、以秒为单位的时长 `du` |
| `k` | 移出群聊，但允许重新加入 | `tg` |
| `um` | 解除发言限制 | `tg` |
| `ub` | 解除封禁 | `tg` |
| `du` | 删除机器人可获取的已保存用户消息 | `tg` |
| `x` | 调整 XP | `tg`、−99999 到 99999 之间的非零整数 `v` |
| `r` | 调整声望 | `tg`、−999 到 999 之间的非零整数 `v` |
| `ja` | 批准入群申请 | 仅限事件 `jr`，无参数 |
| `jd` | 拒绝入群申请 | 仅限事件 `jr`，无参数 |

不要混淆操作代码 `du` 与时长字段 `v.du`。时长单位是秒，不是分钟：一小时为 3600。禁言或封禁的时长为零表示没有指定结束时间，绝不能用它替代未知时长。如果用户需要，可以用单独消息写明原因；不要通过未记录字段承诺可自定义处罚原因。

用户操作接收者 `v.tg`：

- `u`：引发事件的参与者。
- `t`：由上下文定义的目标，例如被回复消息的作者，不是字面 ID。
- `l`：入群申请上下文中，Combot 目录记录的邀请链接创建者。
- `b`：相关上下文中的两个可用参与者，不是“群聊中的所有人”。

始终明确指定接收者。普通命令不支持用户操作。回复命令支持发送者、目标和两者。对于入群申请，如果同时需要申请人（`u`）和已知链接创建者（`l`），请使用独立操作；`b` 不表示申请人加链接创建者。编辑器在入群申请中提供链接创建者选项；不要在成员加入的逐步说明中提供相同选择。其他事件只使用该事件中可用的接收者。

未知目标不能让操作变成对命令发送者的处罚。不要承诺自动改用另一个人。操作 `du` 不保证删除成员的全部历史，机器人受可获取消息和 Telegram 能力限制。

场景依赖警告、等级或声望时，必须启用相应功能；管理操作需要机器人具备相应权限。解除禁言、解除封禁和批准入群申请是独立操作。

入群申请事件允许发送消息、对可用用户执行操作，以及 `ja`/`jd`；删除消息 `d` 不适用。对于没有消息的事件，不要添加删除或回复不存在消息的操作。

## 13. 回复文本和目的地

操作 `s` 的参数：

| 字段 | 含义 |
| --- | --- |
| `tx` | 非空文本，最多 4096 个字符；允许使用 Telegram 支持的 HTML |
| `d` | `sc`：来源群聊；`lg`：已配置日志频道；默认 `sc` |
| `tp` | `ct`：当前话题；`gn`：常规区域；`st`：指定话题；默认 `ct` |
| `to` | 指定话题的正数 ID，导入时重置 |
| `rp` | `r`：回复触发消息；省略：独立消息 |
| `cl` | `n`：保留上一条回复；`ps`：删除此行的上一条回复 |
| `bt` | URL 按钮行：由含 `text` 和 `url` 的对象组成的二维数组 |
| `ph` | 用于链接预览的图片 URL 数组 |
| `pa` | `true`：将预览放在文本上方 |

`rp: "r"` 在来源群聊的当前话题中会保留。不要承诺日志或其他话题中有相同的回复关联。不要在 `d` 中放任意外部群聊、频道或私信。

如果行级 `cl` 缺失，就继承规则设置。规则级 `cl: "ps"` 启用上一条回复清理；显式行级 `cl: "n"` 会覆盖它。清理属于特定规则、操作行和目的地。不同随机行不会合并为一个共用的“最后一条欢迎语”。

普通回复可以使用 `<b>课程信息</b>\n录播在置顶消息中。`。不要把 Markdown 当作 HTML 提供。请正确转义链接和文本。按钮和图片只使用用户提供的真实 URL；`ph` 不会发送相册。

已确认的消息上下文变量：`{name}`、`{uid}`、`{name_link}`、`{from.id}`、`{from.title}`、`{from.username}`、`{chat.id}`、`{chat.title}`、`{chat.username}`、`{message.id}`、`{message.timestamp}`、`{timestamp}`、`{group_name}`、`{reply_to_uid}`、`{reply_to_name}`、`{reply_to_name_link}`。可用性取决于事件。不要编造 `{target.name}`、`{user.first_name}`、`{reaction_count}` 等变量。

在回复命令中，`{from.title}` 描述命令发送者，而不是被处罚或奖励的成员。选择 `tg: "t"` 不会改变变量含义。如果不确定事件是否提供所需姓名，请使用中性措辞。

在加入事件中，`{from.title}` 同样不保证是新人的名字：如果安娜添加伊利亚，安娜就是执行者。请使用“欢迎加入 {chat.title}！”之类不带人名的通用欢迎语。

操作不是事务。禁言后的消息不能证明 Telegram 已应用禁言。不要将无条件的处罚确认写成已经核实的结果：这里没有记录独立的成功检查条件。

## 14. 分支、限额和不能承诺的能力

`ov` 包含同一规则的备选条件。它们共享父规则的事件和操作，不是独立场景。某个分支的排除项不是全局排除。如果禁止条件必须始终生效，请在每个分支保留它。带 `en: false` 的分支不参与匹配。

新的复杂 `ov`、`mtg`、`mog`、`uag`、`tug`、`mef` 和 `mmo` 应使用真实编辑器导出。不要创建递归 OR 树，也不要把独立操作链放入分支并期待它们独立执行。

导出中可能出现兼容字段 `mt`、`mtl`、`t`、`rmi` 和 `rme`。没有理由时，不要用它们替代已记录的主要设置。简单回复限制使用 `rm`：`a` 表示任意消息，`r` 表示仅回复，`rb` 表示回复机器人，`rc` 表示回复 Combot，`nr` 表示非回复。不要用 `rm: "cr"` 替代新的命令字段。

不要生成旧字段或内部字段 `lf`、`fc`、`lo`，也不要生成 UI 字段 `actions`、`destination`、`topic`、`applyTarget` 和 `alwaysRun`。Compact 格式有不同表示方式，部分设置甚至不是正在启用的功能。

规划限额：

- Free：最多 2 条已保存规则；Pro：最多 50 条；Business：最多 100 条。禁用规则也计数。评估剩余名额时请计入现有规则。
- 每条规则的额外 OR 分支：Free 0 个、Pro 2 个、Business 5 个。
- 每条规则最多 100 行操作，每次执行操作计划另有单独计算的 20 次操作预算。
- 每个不同目的地的一次发送成本为 1，带上一条回复清理则为 2。作用于用户的 Telegram 操作按接收者计数，因此 `b` 可能预留双倍额度。XP 和声望在此计算中成本为 0。随机模式计算必做行加上成本最高的随机选择。
- 这是内部计算，并非承诺包含所有辅助操作在内恰好只有二十次网络请求。如果下一行超出剩余预算，执行就会停止；已完成操作不会回滚。

不要承诺无事件的纯定时执行、“每小时最多一次”、一次性回应奖励、防止重复事件导致奖励滥用、仅首次跨越阈值、恰好执行一次、处理任意外部群聊、账号年龄，或任意历史时段的活跃度统计。如果其中某项不可缺少，请说明仅靠所描述规则还不够。

导入会新增规则副本，不会迁移旧版 Triggers v2。可以将旧规则的含义改写为 Compact v3，但不能将旧 JSON 当作可直接导入的结果。

## 15. 示例的验收场景

配套 `examples` 目录包含六个独立设置包，每个都有一条已禁用规则：

| 文件 | 匹配案例 | 附加检查 |
| --- | --- | --- |
| `01-course-command.json` | 成员输入 `/course_info` | 不含命令的普通文本不应触发回复 |
| `02-recording-faq.json` | 文本包含“录播在哪里” | 无关问题不应触发回复；部分搜索可以匹配较长短语 |
| `03-random-welcome.json` | 新成员加入 | 应选择一条欢迎语，而不是三条全发 |
| `04-moderator-reply-mute.json` | Telegram 管理员或群主回复成员并发送 `/team_pause` | 普通成员不能执行；管理员目标被排除；不带回复的命令不得限制发送者 |
| `05-known-link-join-request.json` | 申请使用 Combot 目录中的链接 | 外部或未知来源不得匹配；未选择具体链接时，所有已知链接都匹配 |
| `06-thumbs-up-reaction.json` | 用户添加回应，新状态中包含 👍 | 移除 👍 不匹配；重复的匹配变化可能再次发送消息 |

这些是供你的群聊使用的验收场景，不表示它们全部已经执行过。已完成检查见下文。每个示例都需要在你的群聊中检查设置和能力后再启用。

## 16. 格式来源和已完成验证

格式已对照 Rails `0d80ce4788ef5adc5c7c1b79e85c6b8be27cc00e` 和机器人 `ddc1a8a6b6ab99bd2517d783870495990c7058e5` 核对。这些主分支修订包含协调后的编辑器与自动化修复。已在 Codeberg 确认 Rails PR #78 和机器人 PR #56 合并，但未独立确定已部署进程的准确修订。

主要来源：`trigger_compact_codec_helpers.js`、`trigger_import_export_helpers.js`、`trigger_validation_helpers.js`、事件和操作注册表、`user_attribute_model_helpers.js`、`AutomationController`、`docs/MONGODB.md` 中的详细自动化契约，以及 `automation.py` 中的条件与操作处理。

六个原始示例曾使用编辑器源码编解码器在内存中检查：解码、重建、再次解码，以及规范化结果的稳定性。操作和禁用状态均保留。编解码器会省略部分默认值，因此比较使用规范化结果，而不是要求与输入 JSON 逐字节一致。

9 月 8 日，六个原始示例均通过 combot.org 生产编辑器导入、服务器保存和页面重载后检查了禁用状态。这不能替代对每个条件和操作的 Telegram 验证。

命令与常见问题案例曾在 Telegram 中检查：匹配请求收到了预期回复，对照请求没有收到。只有 `/course_info` 被更改为测试工具安全限制允许的唯一测试名称，其他示例设置保持不变。这些结果不会自动证明其他事件和操作。

对于 `06-thumbs-up-reaction.json`，使用个人身份添加 👍 产生了一条预期回复，移除则没有产生回复。身份和新旧回应集合通过独立的 Bot API 观察程序确认。该次运行未测试加入时的随机欢迎、实际禁言，以及真实入群申请的批准；导入不能证明操作执行。

创建的测试规则已移除，并检查了原始列表已恢复；结果消息仍留在测试群中。JSON Schema 是配套文档，没有接入产品，也不被描述为现有内置校验器。

9 月 9 日，编辑后的参考文档已对照 Rails `0d80ce4788ef5adc5c7c1b79e85c6b8be27cc00e` 和机器人 `0a491a6ee50c57e98c1d9de04819253d15214506` 核对。澄清内容涵盖编辑器名称上限、管理员组、事件参与者、操作接收者，以及可选任务清单链接。这是基于源码的文档审核，不是新的 Telegram 运行。本地化后的示例措辞未经过独立的线上测试。