docs: restructure into core-concept pages and split admin API

2026-09-22 16:11:29 +00:00 · 2026-08-14 06:41:08 +08:00 · 2026-08-14 06:41:08 +08:00 · a9e50fba50
commit a9e50fba50
parent db49e1f01c
27 changed files with 946 additions and 1203 deletions
--- a/docs/zh/guide/routes.md
+++ b/docs/zh/guide/routes.md
@ -0,0 +1,86 @@
+# 路由与目标
+
+路由决定哪些事件被转发到哪个频道（Discord 或 Telegram）。它们以 JSON 数组形式存储在 Cloudflare KV 的 `config:routes` 键下，可通过 [Web 控制台](./configuration#web-控制台)、[Admin API](../api/admin) 或 `config.example.yaml` 管理。
+
+**没有默认路由**——每条路由都必须定义自己的目标。未配置任何路由时不会转发任何事件。每个实例最多可保存 **200 条路由**。
+
+## 路由模式
+
+```json
+{
+  "id": "unique-route-id",
+  "name": "Human-readable name",
+  "enabled": true,
+  "groupId": "my-group",
+  "fallback": false,
+  "stop": false,
+  "discordRoleIds": ["111111111111111111"],
+  "filters": [
+    { "type": "event", "match": "push" },
+    { "type": "repo", "match": "org/repo", "exclude": false }
+  ],
+  "targets": [
+    {
+      "platform": "discord",
+      "channelId": "REQUIRED_CHANNEL_ID",
+      "threadId": "OPTIONAL_THREAD_ID"
+    }
+  ]
+}
+```
+
+`targets` 的每一项都是一个推送目标，因此一条路由可同时转发到多个频道（例如一个 Discord 频道**和**一个 Telegram 群组）。`target.platform` 选择平台：`discord`（默认）或 `telegram`。**Discord** 目标要求 `target.channelId`（可选 `target.threadId` 指定子区）；**Telegram** 目标要求 `target.chatId`（群组/超级群组 id，如 `-1001234567890`），可选 `target.topicId`（话题的 `message_thread_id`，相当于 Discord 子区）。没有默认频道回退。
+
+| 字段             | 类型     | 必需 | 说明                                                                        |
+|------------------|----------|------|-----------------------------------------------------------------------------|
+| `groupId`        | string   | 是   | 路由所属[分组](./groups)的 id                                               |
+| `fallback`       | boolean  | 否   | 为 `true` 时仅在没有其他非 fallback 路由匹配时才触发；其自身过滤器被忽略    |
+| `stop`           | boolean  | 否   | 为 `true` 且该路由匹配时，不再评估后续路由                                  |
+| `discordRoleIds` | string[] | 否   | 路由触发时要提醒的 Discord 身份组 id；仅对 Discord 目标生效                 |
+
+## Discord 身份组提醒
+
+在路由上设置 `discordRoleIds` 可在其触发时提醒一个或多个 Discord 身份组（角色）。提醒（`<@&roleId>`）会加在路由所有 **Discord** 目标的消息内容前；Telegram 目标忽略该字段。只有当机器人拥有 `Mention Everyone` 权限（或身份组标记为可提及）且能看到该身份组时，提醒才会触发通知。
+
+```json
+{
+  "id": "release-notify",
+  "name": "Notify on Release",
+  "enabled": true,
+  "groupId": "default",
+  "discordRoleIds": ["111111111111111111", "222222222222222222"],
+  "filters": [{ "type": "event", "match": "release" }],
+  "targets": [{ "platform": "discord", "channelId": "REQUIRED_CHANNEL_ID" }]
+}
+```
+
+也可以在管理控制台的 _Discord 身份组提醒_ 中填写身份组 id。
+
+## 过滤器
+
+每条路由携带 `filters` 数组（全部匹配才触发——AND 逻辑）。见[过滤器类型](./configuration#过滤器类型)参考与[过滤器教程](./filters)。
+
+## 自定义路由示例
+
+```json
+[
+  {
+    "id": "backend-prs",
+    "name": "Backend PRs",
+    "enabled": true,
+    "groupId": "backend-team",
+    "filters": [
+      { "type": "repo", "match": "myorg/backend" },
+      { "type": "event", "match": "pull_request" },
+      { "type": "actor", "match": "[bot]", "exclude": true }
+    ],
+    "targets": [
+      {
+        "platform": "telegram",
+        "chatId": "-1001234567890",
+        "topicId": "9876543210"
+      }
+    ]
+  }
+]
+```