Merge pull request #411 from flashcatcloud/docs/member-notify-agent-instructions

openapi: add agent_instructions to MemberNotifyResponse

Author: ysyneu

.github/workflows/upload.yml

@@ -1,11 +1,14 @@
 # Upload documentation to Meilisearch for AI Q&A bot indexing.
 #
+# Every run syncs the whole doc set: all docs are upserted and index documents
+# whose source file is gone are deleted.
+#
 # Uses GitHub Environments for dev/prod separation. Create two environments in
 # Settings > Environments: "development" and "production".
 #
 # Per-environment secrets (all required, keep as secrets to hide Meilisearch endpoint):
 #   MEILI_ENDPOINT  - Meilisearch instance URL
-#   MEILI_API_KEY   - API key with documents write permission
+#   MEILI_API_KEY   - API key with documents read/write permission
 #   MEILI_INDEX     - Target index name
 #
 # Branch mapping: main -> production, test -> development
@@ -29,22 +32,19 @@ on:
         options:
           - production
           - development
-      full_upload:
-        description: 'Re-upload all docs (use after clearing index or changing settings)'
-        required: false
-        default: false
-        type: boolean
 
 jobs:
   upload:
     runs-on: ubuntu-latest
     environment: ${{ github.event.inputs.environment || (github.ref == 'refs/heads/main' && 'production' || 'development') }}
+    # One sync per index at a time: an older run listing the index while a
+    # newer one uploads would delete the newer run's added docs.
+    concurrency:
+      group: meilisearch-upload-${{ github.event.inputs.environment || (github.ref == 'refs/heads/main' && 'production' || 'development') }}
+      cancel-in-progress: false
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-        with:
-          # Need history for git diff in incremental mode
-          fetch-depth: 2
 
       - name: Install dependencies
         run: |
@@ -57,7 +57,6 @@ jobs:
           MEILI_ENDPOINT: ${{ secrets.MEILI_ENDPOINT }}
           MEILI_API_KEY: ${{ secrets.MEILI_API_KEY }}
           MEILI_INDEX: ${{ secrets.MEILI_INDEX }}
-          FULL_UPLOAD: ${{ github.event.inputs.full_upload || 'false' }}
         run: |
           chmod +x ./scripts/upload.sh
           bash ./scripts/upload.sh

api-reference/monitors.openapi.en.json

@@ -5923,6 +5923,7 @@
             "items": {
               "$ref": "#/components/schemas/InvestigationTarget"
             },
+            "maxItems": 20,
             "description": "Drill-down entries linked from the alert event detail page; at most 20 items, duplicates rejected. On update the field is presence-based: omit it to keep the current value, pass `[]` to clear.",
             "x-flashduty-preserve-absence": true
           },
@@ -6223,22 +6224,32 @@
       },
       "InvestigationTarget": {
         "type": "object",
-        "description": "Drill-down entry linked to alert events. A deliberately closed tagged union: new kinds require explicit server support.",
+        "description": "Alert-event drill-down entry. A deliberately closed tagged union: new kinds require explicit server support, and unknown fields inside a target are rejected.",
         "properties": {
           "kind": {
             "type": "string",
             "enum": [
-              "dashboard"
+              "dashboard",
+              "query"
             ],
-            "description": "Entry type; currently only `dashboard` is supported."
+            "description": "Entry kind: `dashboard` opens a dashboard panel, `query` opens an Explore query. It decides whether `dashboard` or `query` must be supplied; supplying the other one is rejected."
+          },
+          "time_range": {
+            "$ref": "#/components/schemas/InvestigationTimeRange",
+            "description": "Window around the event time, required on every saved entry. A zero-length window is rejected; defaults belong to the editor."
+          },
+          "query": {
+            "$ref": "#/components/schemas/QueryInvestigationTarget",
+            "description": "Configuration for the `query` kind; required when `kind` is `query`, and rejected when `kind` is `dashboard`."
           },
           "dashboard": {
             "$ref": "#/components/schemas/DashboardInvestigationTarget",
             "description": "Configuration for the `dashboard` kind; required when `kind` is `dashboard`."
           }
         },
         "required": [
-          "kind"
+          "kind",
+          "time_range"
         ]
       },
       "DashboardInvestigationTarget": {
@@ -6253,37 +6264,103 @@
             "type": "string",
             "description": "Panel ID inside the dashboard; must be a canonical UUIDv7. Optional."
           },
-          "variable_bindings": {
+          "variables": {
             "type": "object",
             "additionalProperties": {
-              "$ref": "#/components/schemas/InvestigationVariableBinding"
+              "type": "string"
             },
-            "description": "Dashboard variable bindings, keyed by dashboard variable name."
+            "description": "Dashboard variable values, keyed by variable name. Values may reference event labels through `{{ }}` templates; defaults to an empty object."
+          }
+        },
+        "required": [
+          "dashboard_id",
+          "variables"
+        ]
+      },
+      "InvestigationTimeRange": {
+        "type": "object",
+        "description": "Window around the alert event time, expressed as two offsets. Both directions must be non-negative and at least one must be greater than zero, so an entry never resolves to an empty window.",
+        "properties": {
+          "before_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 9007199254740,
+            "description": "Seconds to look back from the event time."
+          },
+          "after_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 9007199254740,
+            "description": "Seconds to look forward from the event time, so behaviour after the event stays visible."
           }
         },
         "required": [
-          "dashboard_id"
+          "before_seconds",
+          "after_seconds"
         ]
       },
-      "InvestigationVariableBinding": {
+      "QueryInvestigationTarget": {
         "type": "object",
-        "description": "Binding between a dashboard variable and alert event data.",
+        "description": "Explore query used by a `query` drill-down entry. The expression may reference event labels through `{{ }}` templates, while `args` values may not.",
         "properties": {
-          "source": {
+          "datasource_id": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1,
+            "maximum": 9007199254740991,
+            "description": "Data source the query runs against."
+          },
+          "query": {
+            "$ref": "#/components/schemas/DashboardQuery",
+            "description": "Query payload."
+          }
+        },
+        "required": [
+          "datasource_id",
+          "query"
+        ]
+      },
+      "DashboardQuery": {
+        "type": "object",
+        "description": "Query payload shared by dashboards and drill-down entries.",
+        "properties": {
+          "mode": {
             "type": "string",
             "enum": [
-              "event_label"
+              "instant",
+              "range",
+              "window"
             ],
-            "description": "Where the bound value comes from; currently only `event_label` (the alert event's label value) is supported."
+            "description": "Evaluation mode: `instant` evaluates at a single timestamp, `range` evaluates a stepped series, `window` returns raw rows inside a time window."
           },
-          "key": {
+          "expr": {
             "type": "string",
-            "description": "Alert event label name; must follow Prometheus label naming rules and must not be a reserved label."
+            "description": "Query expression in the target data source's language. May reference event labels through `{{ }}` templates."
+          },
+          "args": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Named query arguments; defaults to an empty object. Values are passed through verbatim and must not contain `{{ }}` templates."
+          },
+          "min_step_seconds": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "minimum": 1,
+            "maximum": 9007199254740,
+            "description": "Minimum step, in seconds. Only accepted when `mode` is `range`, and must be greater than zero; omit or pass null to let the server decide."
           }
         },
         "required": [
-          "source",
-          "key"
+          "mode",
+          "expr",
+          "args"
         ]
       }
     }

api-reference/monitors.openapi.zh.json

@@ -5923,6 +5923,7 @@
             "items": {
               "$ref": "#/components/schemas/InvestigationTarget"
             },
+            "maxItems": 20,
             "description": "告警事件详情页关联的排障入口列表，最多 20 项，不允许重复。更新接口中该字段按 presence 处理：省略时保留原配置，传 `[]` 清空。",
             "x-flashduty-preserve-absence": true
           },
@@ -6223,22 +6224,32 @@
       },
       "InvestigationTarget": {
         "type": "object",
-        "description": "告警事件的关联排障入口，为封闭的 tagged union：新增类型需服务端显式支持。",
+        "description": "告警事件的关联排障入口，为封闭的 tagged union：新增类型需服务端显式支持，入口内出现未知字段会被拒绝。",
         "properties": {
           "kind": {
             "type": "string",
             "enum": [
-              "dashboard"
+              "dashboard",
+              "query"
             ],
-            "description": "排障入口类型，目前仅支持 `dashboard`。"
+            "description": "入口类型：`dashboard` 打开仪表盘面板，`query` 打开 Explore 查询。它决定必须提供 `dashboard` 还是 `query`，提供另一个会被拒绝。"
+          },
+          "time_range": {
+            "$ref": "#/components/schemas/InvestigationTimeRange",
+            "description": "事件时间前后的取数窗口，每个已保存的入口都必填。长度为 0 的窗口会被拒绝；默认值由前端编辑器提供。"
+          },
+          "query": {
+            "$ref": "#/components/schemas/QueryInvestigationTarget",
+            "description": "`query` 类型的入口配置；`kind` 为 `query` 时必填，`kind` 为 `dashboard` 时不允许出现。"
           },
           "dashboard": {
             "$ref": "#/components/schemas/DashboardInvestigationTarget",
             "description": "`dashboard` 类型的入口配置；`kind` 为 `dashboard` 时必填。"
           }
         },
         "required": [
-          "kind"
+          "kind",
+          "time_range"
         ]
       },
       "DashboardInvestigationTarget": {
@@ -6253,37 +6264,103 @@
             "type": "string",
             "description": "仪表盘内目标面板 ID，须为规范的 UUIDv7；可选。"
           },
-          "variable_bindings": {
+          "variables": {
             "type": "object",
             "additionalProperties": {
-              "$ref": "#/components/schemas/InvestigationVariableBinding"
+              "type": "string"
             },
-            "description": "仪表盘变量绑定，键为仪表盘变量名。"
+            "description": "仪表盘变量取值，键为变量名。值可通过 `{{ }}` 模板引用事件标签；默认空对象。"
+          }
+        },
+        "required": [
+          "dashboard_id",
+          "variables"
+        ]
+      },
+      "InvestigationTimeRange": {
+        "type": "object",
+        "description": "以两个偏移量表示告警事件时间前后的取数窗口。两个方向都必须非负，且至少一个大于 0，因此入口不会解析出空窗口。",
+        "properties": {
+          "before_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 9007199254740,
+            "description": "相对事件时间向前回溯的秒数。"
+          },
+          "after_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 9007199254740,
+            "description": "相对事件时间向后延伸的秒数，用于保留事件发生后的表现。"
           }
         },
         "required": [
-          "dashboard_id"
+          "before_seconds",
+          "after_seconds"
         ]
       },
-      "InvestigationVariableBinding": {
+      "QueryInvestigationTarget": {
         "type": "object",
-        "description": "仪表盘变量与告警事件数据的绑定。",
+        "description": "`query` 类型入口使用的 Explore 查询。表达式可通过 `{{ }}` 模板引用事件标签，`args` 的值不允许包含模板。",
         "properties": {
-          "source": {
+          "datasource_id": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1,
+            "maximum": 9007199254740991,
+            "description": "查询所用的数据源。"
+          },
+          "query": {
+            "$ref": "#/components/schemas/DashboardQuery",
+            "description": "查询内容。"
+          }
+        },
+        "required": [
+          "datasource_id",
+          "query"
+        ]
+      },
+      "DashboardQuery": {
+        "type": "object",
+        "description": "仪表盘与排障入口共用的查询内容。",
+        "properties": {
+          "mode": {
             "type": "string",
             "enum": [
-              "event_label"
+              "instant",
+              "range",
+              "window"
             ],
-            "description": "绑定值来源，目前仅支持 `event_label`（取告警事件的标签值）。"
+            "description": "求值模式：`instant` 在单个时间点求值，`range` 求值一条按步长采样的曲线，`window` 返回时间窗口内的原始数据。"
           },
-          "key": {
+          "expr": {
             "type": "string",
-            "description": "告警事件标签名，须符合 Prometheus 标签命名规则，且不能使用保留标签。"
+            "description": "目标数据源语法下的查询表达式，可通过 `{{ }}` 模板引用事件标签。"
+          },
+          "args": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "命名查询参数，默认空对象。值按原样透传，不允许包含 `{{ }}` 模板。"
+          },
+          "min_step_seconds": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "minimum": 1,
+            "maximum": 9007199254740,
+            "description": "最小步长（秒）。仅在 `mode` 为 `range` 时可用，且必须大于 0；省略或传 null 由服务端决定。"
           }
         },
         "required": [
-          "source",
-          "key"
+          "mode",
+          "expr",
+          "args"
         ]
       }
     }