From 4fe2fd78c6b3dd64e38e28993032f90a06f3b6f6 Mon Sep 17 00:00:00 2001 From: ysyneu Date: Sat, 17 Oct 2026 03:43:19 -0700 Subject: [PATCH 1/5] docs(ai-sre): document IM attachments, automation execution place and console entry points --- en/ai-sre/agents.mdx | 8 +++--- en/ai-sre/automations.mdx | 57 ++++++++++++++++++++++++++++++------- en/ai-sre/environments.mdx | 4 ++- en/ai-sre/im.mdx | 26 +++++++++++++++-- en/ai-sre/mcp.mdx | 7 +++-- en/ai-sre/sessions.mdx | 19 ++++++++++++- en/ai-sre/skills.mdx | 13 ++++++++- zh/ai-sre/agents.mdx | 8 +++--- zh/ai-sre/automations.mdx | 58 ++++++++++++++++++++++++++++++-------- zh/ai-sre/environments.mdx | 4 ++- zh/ai-sre/im.mdx | 26 +++++++++++++++-- zh/ai-sre/mcp.mdx | 7 +++-- zh/ai-sre/sessions.mdx | 19 ++++++++++++- zh/ai-sre/skills.mdx | 13 ++++++++- 14 files changed, 226 insertions(+), 43 deletions(-) diff --git a/en/ai-sre/agents.mdx b/en/ai-sre/agents.mdx index 4f039a3e..8c8c612d 100644 --- a/en/ai-sre/agents.mdx +++ b/en/ai-sre/agents.mdx @@ -20,7 +20,7 @@ sidebarTitle: Agent Delegation doesn't make you wait. After AI SRE delegates a task to a remote agent, the conversation continues immediately. You can keep working or delegate several tasks at once. When the remote agent finishes, its result appears in the conversation as a new message. -Each A2A delegation appears in the conversation stream as a **task card** carrying an `A2A` badge. The card shows the remote agent name, task intent, run status, and usage metrics such as tool call count, tokens, and elapsed time. The run status is one of: initializing, in progress, awaiting input, awaiting authorization, completed, failed (including orphaned), interrupted, or killed. Click the card to view the full delegation trace in the right-hand panel. +Each A2A delegation appears in the conversation stream as one line: a robot icon, "Dispatched" plus the remote agent name, and the task intent. On the right it shows the run status and usage metrics such as tool call count, tokens, and elapsed time. The run status is one of: initializing, in progress, awaiting input, awaiting authorization, completed, failed (including orphaned), interrupted, or killed. Click the line to view the full delegation trace in the right-hand panel; the `A2A` badge sits in that panel's title, not on the line. **The instructions decide whether AI SRE picks this agent.** Before delegating, AI SRE sees only one `name: summary` line per agent and uses it to decide. The summary comes from the `summary:` line at the top of the instructions. The body is delivered in full only on the first delegation, so it can be long and detailed. See [Writing Instructions](#writing-instructions). @@ -266,14 +266,14 @@ The platform ships several **bootstrap Subagents** that work out of the box: | `general` | General-purpose worker with full tool access. Use it to offload work whose intermediate steps would otherwise pollute the parent's context (long reports, multi-file edits, end-to-end builds, repeated probing). Dispatch several in parallel for independent units of work | | `explore` | Read-only investigator restricted to `grep` / `glob` / `read`; it cannot write or execute. Returns a compact summary rather than raw search output — ideal for locating evidence inside a codebase or knowledge dump | -**In the conversation**: each dispatch also appears as a **task card** with the same statuses as an A2A delegation. Its badge reads `Agent` instead of `A2A`. The card also shows the **execution environment** of the dispatch (the cloud environment or the BYOC Runner's name). +**In the conversation**: each dispatch also appears as one line with the same statuses as an A2A delegation: a robot icon, "Dispatched" plus the subagent name (written as `subagent` when the name is a type synonym such as `agent` or `general`), and the task intent. The right side shows the **execution environment** of the dispatch (the cloud environment or the BYOC Runner's name) plus usage and status. Click the line to view the full trace in the right-hand panel; the `Agent` badge (`A2A` for A2A delegations) sits in that panel's title. **Runtime limits**: - **Concurrency cap**: a session runs **at most 20 Subagents at the same time**. Total dispatches are unlimited — each completion frees a slot; at the cap, AI SRE waits for running ones to finish before dispatching the rest. - **Nesting depth**: a dispatch chain nests **at most 3 levels deep**, preventing a Subagent from spawning itself indefinitely. -**Execution environment**: by default a subtask runs in the same environment as the current session and shares its filesystem, so it can read your workspace's files directly. AI SRE can also send a subtask to a fresh cloud environment (an ephemeral container with its own filesystem; it can reach the public internet but not your private network) or to an online BYOC Runner (account-scope Runners, plus the Runners of the team the session is bound to). If the chosen Runner is unusable, the dispatch fails with the reason and is not re-routed. A2A delegations cannot choose an environment; a remote agent executes in its own. See [Environments (BYOC)](/en/ai-sre/environments) for how the environments differ and how to pick one. +**Execution environment**: by default a subtask runs in the same environment as the current session and shares its filesystem, so it can read your workspace's files directly. AI SRE can also send a subtask to a fresh cloud environment (an ephemeral container with its own filesystem; it can reach the public internet but not your private network) or to a BYOC Runner (account-scope Runners, plus the Runners of the team the session is bound to). The candidate list includes every Runner that has ever connected, including ones currently offline; Runners that have never connected are not listed. Reachability is checked at dispatch time. If the chosen Runner is unusable, the dispatch fails with the reason and is not re-routed. A2A delegations cannot choose an environment; a remote agent executes in its own. See [Environments (BYOC)](/en/ai-sre/environments) for how the environments differ and how to pick one. **A cross-environment dispatch cannot read the parent's files**: a subtask sent to another environment gets its own sandbox or Runner directory and cannot see the parent session's files. AI SRE therefore puts everything the subtask needs into its task description, and results come back as text or through an external system such as git or a ticket. @@ -281,7 +281,7 @@ The platform ships several **bootstrap Subagents** that work out of the box: - Observe A2A delegation task cards and their sub-session panels within a session. + Observe A2A delegations and their sub-session panels within a session. Connect external tools to agents to expand their capability boundary during tasks. diff --git a/en/ai-sre/automations.mdx b/en/ai-sre/automations.mdx index c980a2ae..7e345684 100644 --- a/en/ai-sre/automations.mdx +++ b/en/ai-sre/automations.mdx @@ -21,7 +21,7 @@ When to use it: hand recurring routine inspections (such as a daily health check Entry point: **AI SRE → Automations** in the left navigation. -Every run produced by an automation is, at its core, still an AI SRE session — it is marked as hidden and not mixed into your everyday session list. You can always click into it from the run history to see the full conversation, tool calls, and artifacts of that run (except for a **War room created** run, which runs in the IM group — see "War room created" below). +Every run produced by an automation is, at its core, still an AI SRE session — it is marked as hidden and not mixed into your everyday session list. A run at the **Web** execution place can always be opened from the run history to see the full conversation, tool calls, and artifacts. The conversation of an **IM** run (including **War room created** runs) is in the IM group and cannot be opened from the console; see "Execution place" below. ## Creating an automation @@ -37,7 +37,17 @@ The page header offers two ways to create a rule. **Create via chat** opens a se -Either entry point leads to the same configuration form. +A template's create form can also be opened by link from other pages: `/ai-sre/automations/new?template=TEMPLATE_KEY`. If the link also carries `oncall_incident_channel_ids=ID1,ID2`, the channels of the **On-call incident** trigger are preselected. Such links can be shared and still work after a refresh. + +Either entry point leads to the same configuration form. Both console entries always create a rule at the **Web** execution place; to run a rule in an IM chat, create it from that IM conversation: + +### Create from an IM conversation (bound to the current session) + +When you ask the agent in an IM group or direct chat to create an automation without naming an execution place, the rule is bound to **this conversation** and inherits its scope (including the bound team). The CLI equivalent is to omit `--run-in` when running `flashduty automation create` from an IM conversation (see [CLI](/en/developer/cli)). + +- After binding, every run opens a new session in that chat instead of creating one in the console; the bound chat is fixed. +- To run it on **Web** instead, say so at creation (ask for execution on the Web console in the conversation, or add `--run-in web` on the CLI). It cannot be changed afterwards; recreate the rule. +- Do not pass chat, platform, integration, or session IDs yourself; the server resolves and authorizes the current session. ## Configuration fields @@ -46,8 +56,8 @@ The configuration form has the following fields: | Field | Required | Notes | |---|---|---| | Name | Yes | The rule name, up to 255 characters. Placeholder example: `Weekly on-call insights`. | -| Scope | Yes | Use the **scope selector** to choose **Personal** or a **Team**. Scope determines the rule's ownership and edit permissions. It also limits the self-hosted Runners you can select in **Environment** to account-global Runners and Runners of the scope's team. | -| Environment | No | Use the **environment picker** to choose the runtime environment: **Auto** (the system picks the best available environment, the default), **Cloud Sandbox**, or a **self-hosted (BYOC) Runner**. After picking a team scope, a team Runner that does not belong to that scope is cleared automatically. | +| Scope | Yes | Use the **scope selector** to choose **Personal** or a **Team**. Scope determines the rule's ownership and edit permissions. It also limits the self-hosted Runners you can select in **Environment** to account-global Runners and Runners of the scope's team. A scope cannot be changed after creation; the rule detail page shows it as **Pinned scope**. | +| Environment | No | Use the **environment picker** to choose the runtime environment: **Auto** (the system picks the best available environment, the default), **Cloud Sandbox**, or a **self-hosted (BYOC) Runner**. After picking a team scope, a team Runner that does not belong to that scope is cleared automatically. A rule at the **IM** execution place does not use the environment chosen here (see "Execution place" below). | | Task prompt | Yes | Describe the task for AI SRE to perform, written in a rich-text editor. This prompt is exactly what is sent to the agent on each run. Placeholder: `Describe the task for Flashduty AI SRE to perform.` | | Time zone | No | A field on the **Schedule** trigger card (see "Schedule (cron)" below): the **rule time zone** the cron expression is read in. Pick an IANA zone name (for example `Asia/Shanghai`) from a searchable dropdown; the options are ordered by their UTC offset. On create it defaults to your effective time zone (member time zone first, falling back to the account time zone). When no zone is available the field is left empty and the create request omits it. | @@ -55,6 +65,33 @@ The configuration form has the following fields: For **Environment**, "Auto" has the system pick the best available environment at each run; "Cloud Sandbox" is a platform-managed ephemeral sandbox; a self-hosted Runner runs on your own machine. See Environments for the differences and how to connect them. +## Execution place (where a rule runs) + +Each rule has an **execution place**, fixed at creation and not editable in the console afterwards: + +- **Web** (default): each run is a hidden session in the console. A rule created in the console always has this value. +- **IM**: runs happen in the IM group or direct chat the rule was bound to at creation. Every run **opens a new session** in that chat; when the IM integration has threads turned on, each run also opens a new thread. A retry of the same run reuses that session and thread; the bound chat never changes. + +The **Where it ran** column of the rule list and the same item in the detail page's configuration show this value (`IM` or `Web`). When one rule enables **War room created** along with other triggers, the column shows two badges: **War room → IM** and **Other triggers → Web**. **War room created** is the only trigger that ignores the rule's execution place; it runs in the war room's own group (see "War room created" below). + +A rule at the **IM** execution place differs from a Web rule in a few ways: + +- The console offers no **Clone**; to switch to Web, recreate the rule. +- The console does not expose these runs' sessions: the run history shows `-` in the Name column, clicking the row only shows **This analysis is in IM. Open IM to view it.**, and running it manually from the rule row does not open a session. +- It does not use the rule's **Environment**; it uses the environment already chosen in that chat (change it with `/env` in the conversation). The form still shows the environment picker, but it has no effect on IM runs. +- **A stale binding skips the run**: if the bound chat's scope or session has changed when a run fires (for example `/scope` changed the bound team in the group, or the group started a new session), the run is **skipped**, with status `Skipped` and reason `chat_scope_mismatch`. The rule stays enabled and is never moved to another chat; recreate the rule to change chats. + +### Specifying it through the API or CLI (`run_in`) + +Console-created rules are always **Web**. When creating through the API or CLI, set `run_in` explicitly: + +| Field | Type | Description | +|---|---|---| +| `run_in` | string | `current-chat`: bind the rule to the **live IM conversation** the caller authenticated from; only valid when the call is made from that IM conversation, and rejected anywhere else. `web`: run in the console. When omitted, calls from an IM conversation use `current-chat` and all others use `web`. | +| `team_id` | int64 | The rule's scope. An explicit `0` means personal; a value above `0` is a team in the account. When omitted, a call from an IM conversation inherits that conversation's scope. With `run_in=current-chat`, an explicit value must match the conversation's scope. | + +`update` does not accept `run_in`: like scope, the execution place cannot be changed after creation. For the CLI flags see [CLI](/en/developer/cli). + ## Triggers A rule must have **at least one trigger** configured. The current console form exposes **Schedule**, **Call via API**, **On-call incident**, and **War room created** in the "Triggers" section, and all four can be enabled at the same time. @@ -233,11 +270,11 @@ Run history is shown as a table with these columns: | Column | Notes | |---|---| -| Name | The title of the run's hidden session, or the session ID if it can't be resolved. A run merged into another analysis has no session of its own, so this shows its incident (`# `) and, on the line below, the analysis it joined | +| Name | The title of the run's hidden session, or the session ID if it can't be resolved; `-` for a run at the **IM** execution place (its conversation is in the IM group). A run merged into another analysis has no session of its own, so this shows its incident (`#<num> <title>`) and, on the line below, the analysis it joined | | Started at | The start time of the run | | Duration | How long the run took | | Triggers | The trigger type of the run, such as `Schedule`, `HTTP POST`, `On-call incident`, `Run manually`, or `War room created` (war_room_created) | -| Where it ran | Where the run happened: `IM` (the session is in the IM group, as for a war-room-created run) or `Web console` (a hidden session in the console) | +| Where it ran | Where the run happened: `IM` (the session is in the IM group, as for a war-room-created run) or `Web` (a hidden session in the console) | | Status | The status of the run (see the table below) | Run status values: @@ -249,7 +286,7 @@ Run status values: | `succeeded` | Succeeded | | `partial` | Partially succeeded | | `failed` | Failed | -| `skipped` | Skipped. Two situations share this status. Either the trigger decided not to run, for example because the rule's owner is inactive or the schedule stopped. Or the incident joined another running analysis (see "Merging similar incidents into one analysis" above) | +| `skipped` | Skipped. Three situations share this status. The trigger decided not to run, for example because the rule's owner is inactive or the schedule stopped. The incident joined another running analysis (see "Merging similar incidents into one analysis" above). Or, for a rule at the **IM** execution place, the bound chat's scope or session had changed when it fired (see "Execution place" above) | | `blocked` | Blocked. The run produced real output but stopped at a connector that needs a human. The connector isn't set up yet, or an admin must complete its authorization in the console | | `abandoned` | Abandoned (terminated by the system after running too long without completing) | @@ -259,7 +296,7 @@ Three filters are available above the table: - **Status**: filter by the run statuses above, or choose **All statuses**. - **Trigger type**: choose from `All trigger types` / `Run manually` / `Schedule` / `HTTP POST` / `On-call incident` / `War room created`. -Run records returned by the API also include `trigger_kind`, which can be `schedule`, `manual`, `http_post`, `oncall_incident`, `war_room_created`, or `debug`. `manual` means the run was started through the run-now API, `oncall_incident` means it was started by a matching On-call incident event, and `war_room_created` means it was started by the war-room-created trigger (its session is in the IM group). A run merged into another analysis has no `session_id` of its own. Instead, `joined_session_id` holds that analysis's session ID and `joined_session_name` holds its session name. If both are empty, the run has its own hidden session. +Run records returned by the API also include `trigger_kind`, which can be `schedule`, `manual`, `http_post`, `oncall_incident`, `war_room_created`, or `debug`. `manual` means the run was started through the run-now API, `oncall_incident` means it was started by a matching On-call incident event, and `war_room_created` means it was started by the war-room-created trigger (its session is in the IM group). A run with `execution_place` `im` returns no session identity: `session_id` and `joined_session_id` are empty and `result_json` is not sent, leaving only the status, time, and error fields. A run merged into another analysis has no `session_id` of its own. Instead, `joined_session_id` holds that analysis's session ID and `joined_session_name` holds its session name. If both are empty, the run has its own hidden session. Click a row to jump to the chat page of the hidden session for that run, where you can view the full messages, tool calls, and artifacts of that run. A run that happened in IM (for example, one started by the War room created trigger) does not navigate; it shows the message **This analysis is in IM. Open IM to view it.** — you read that analysis in the IM group. A run merged into another analysis has no session of its own, so clicking it opens the analysis that took over the incident. @@ -291,7 +328,7 @@ Each rule offers a set of actions in the **Actions** column: | Action | Notes | |---|---| | Enable / Disable | An inline switch. When disabled, the rule is kept but no longer triggers; disabling does not delete existing run history. | -| Run now | Starts one real run manually from the rule row. The action performs preflight checks first, then creates a hidden session for the run. Manual runs are limited to one per rule per minute. When **War room created** is the rule's only trigger, neither the list nor the detail page offers this action — such a rule produces no console run, and calling the run-now API returns an error. | +| Run now | Starts one real run manually from the rule row. The action performs preflight checks first. For a rule at the **Web** execution place it creates a hidden session and opens it; for an **IM** rule it opens a new session in the bound IM chat, and the console only shows **Manual run submitted. Check the run history for progress.** Manual runs are limited to one per rule per minute. When **War room created** is the rule's only trigger, neither the list nor the detail page offers this action — such a rule produces no console run, and calling the run-now API returns an error. | Clicking anywhere on the rule row opens its detail page, where you can edit the configuration, delete the rule, and view its run history (see "Run History" above). @@ -303,7 +340,7 @@ Above the list there are also two filters: **Scope** (All / Personal / Team, whe Automation rules share the two-level scope used by other AI SRE resources. For the general rules, see [Scope and permissions](/en/ai-sre/context#scope-and-permissions). What is specific to automations: -- **A rule's scope can't be changed after creation.** To move a rule, click **Clone** on the rule detail page and pick a new scope for the copy. +- **A rule's scope can't be changed after creation.** To move a rule, click **Clone** on the rule detail page and pick a new scope for the copy (rules at the **IM** execution place have no Clone). - A team rule keeps running after its creator leaves the team. A personal rule is disabled automatically once its creator is no longer an active account member. - A **personal rule** can be viewed and managed only by its creator. Account owners and admins see it in the list, but opening its detail page is denied. - **HTTP POST trigger** checks only the trigger URL's Bearer token: an external system holding the token can start a run, which creates a hidden session under the rule's personal or team scope. The On-call incident and War room created triggers don't use that token; their runs belong to the rule's scope in the same way. diff --git a/en/ai-sre/environments.mdx b/en/ai-sre/environments.mdx index 93ccf3ab..15911913 100644 --- a/en/ai-sre/environments.mdx +++ b/en/ai-sre/environments.mdx @@ -65,7 +65,9 @@ Go to **AI SRE → Customize → Environments → Cloud** to view, create, edit, Environment variables are visible in plaintext to everyone who uses this cloud environment template — do not put secrets or credentials here. </Warning> -**Platform-reserved environment variable names.** The platform injects the following variables; saving a template that sets any of them is rejected: `FLASHDUTY_APP_KEY`, `FLASHDUTY_BASE_URL`, `FLASHDUTY_DOCS_URL`, `PATH`, `HOME`, and the GitHub (`GH_TOKEN*`, `GIT_CONFIG_*`) and GitLab (`GITLAB_*`, `GLAB_*`) authentication and host variables. +**Platform-reserved environment variable names.** The platform injects the following variables; saving a template that sets any of them is rejected: `FLASHDUTY_APP_KEY`, `FLASHDUTY_BASE_URL`, `FLASHDUTY_DOCS_URL`, `FLASHDUTY_CONSOLE_URL`, `PATH`, `HOME`, and the GitHub (`GH_TOKEN*`, `GIT_CONFIG_*`) and GitLab (`GITLAB_*`, `GLAB_*`) authentication and host variables. + +`FLASHDUTY_CONSOLE_URL` is the console address. The agent expands it into clickable links when it cites incidents, alerts, channels, and schedules; when no console address is configured it is not injected, and the agent cites resources by ID in prose instead. It holds no secret, so the agent can read it. Even if a same-named variable is set some other way, the platform's value is used when commands run (on both the cloud Sandbox and self-hosted Runners). Use template environment variables only for non-sensitive business configuration; for secrets, use MCP member authorization or the relevant App integration. diff --git a/en/ai-sre/im.mdx b/en/ai-sre/im.mdx index 2334af00..008810b3 100644 --- a/en/ai-sre/im.mdx +++ b/en/ai-sre/im.mdx @@ -9,7 +9,7 @@ sidebarTitle: IM platform Incident response usually happens right inside your IM group — alerts come in, the team discusses in the channel, and someone spins up a war room. AI SRE puts the agent directly into that collaboration chain: **you never have to switch to the console. You can summon it from IM to investigate**, and your teammates can follow every step of its analysis in real time. -AI SRE's IM integration has two trigger modes: +AI SRE's IM integration has three trigger modes: <CardGroup cols={2}> <Card title="@Mention Summon" icon="at"> @@ -18,8 +18,13 @@ AI SRE's IM integration has two trigger modes: <Card title="War Room Auto-Diagnosis" icon="people-group"> When someone opens an IM war room for an incident, AI SRE runs a preliminary diagnosis and posts the findings to the war room if the account has an enabled **War room created** automation rule that the incident's channel and severity match. No one needs to summon it. </Card> + <Card title="Automation Replies in the Group" icon="clock"> + Ask AI SRE in a group to create an ordinary automation rule and it uses **this group** as the run location: when the rule later fires on a schedule, an API call, or an On-call incident, the run **opens a new session** in the original group and posts its conclusion there. Every run is a fresh session and does not carry over the group's earlier conversation; when the integration has thread replies on, each run also opens a new thread whose root message is the run's first real output (progress or conclusion), with no "started" placeholder posted before there is content. The binding and scope are fixed at creation and cannot move to another group: before each run they are re-checked, and if the group's team scope or session has changed the whole run is **skipped**. + </Card> </CardGroup> +The first two modes are started by a person; the third is started by an automation rule you configured. For how to create the rule and how its execution place and scope are fixed, see [Automations](/en/ai-sre/automations#execution-place-where-a-rule-runs). + ## Supported IM platforms AI SRE's IM interaction covers four major platforms. Each platform supports inbound @mentions (webhook), historical message reads, and outbound replies: @@ -57,7 +62,7 @@ In a connected IM group with **Allow AI SRE conversations in IM** on, **@mention The platform distinguishes between **group @mentions** and **direct messages**. Once mentioned, AI SRE puts a "processing" receipt on that message (see [Processing receipt](#processing-receipt)) and checks whether the message contains a slash command. </Step> <Step title="Bind to a session"> - Multiple @mentions within the same IM chat continue the **same agent session**, preserving context. For a new chat, AI SRE starts with the opening message of that IM thread and any associated incident as context. + Multiple @mentions within the same IM chat continue the **same agent session**, preserving context. For a new chat, AI SRE starts with the opening message of that IM thread and any associated incident as context. In a Feishu / Lark group with topic replies on, a topic session opened by a **top-level @** also pulls in the group messages from the **last 10 minutes** (up to that @), which is how an error text or screenshot posted just before the @ reaches the context; replies inside a topic read only that topic. </Step> <Step title="Read context and reply"> AI SRE reads the thread / chat history to build context, investigates autonomously, and posts its findings **in-thread**. Other people @mentioned in the original message are carried over into the reply, making it easy for multiple parties to collaborate in the group. @@ -68,6 +73,23 @@ In a connected IM group with **Allow AI SRE conversations in IM** on, **@mention The **reply mode** is configurable (off / first / all), controlling whether AI SRE @mentions the person who asked, and whether it replies **in-thread** or in the main channel. In a busy large group, in-thread replies keep the investigation discussion focused without flooding the channel. </Tip> +### Attachments and images + +AI SRE downloads images, documents and voice messages from the chat and hands them to the agent as files. This covers not only attachments on the message that **@mentions** it but also attachments on **earlier messages in the same thread or chat**: post an error screenshot, then add "@bot what is this?", and the model receives the screenshot. + +Per turn, the attachment quota is counted by type. The current message's attachments take quota first, and history fills the rest, newest first: + +| Type | Limit per turn | +| --- | --- | +| Images | 5 | +| Documents | 3 | +| Voice messages | 3 | + +- **History attachments that don't fit** are marked "not attached" in the prompt, so the model is never promised a file it doesn't have. +- **Rejected:** an attachment over 20 MiB, or a direct link that is not HTTPS. +- **Time budget for history:** history attachments not downloaded within about 5 seconds are treated as not attached, so a turn never waits on an old screenshot. +- **All attachments of the current message fail:** AI SRE does not call the agent and replies with a short failure notice asking you to retry or send a smaller file. A failed history attachment does not stop the turn. + ### Processing receipt Once the bot has your message, it first puts an emoji reaction on **the message you sent**, as an immediate "received, working on it" signal. The emoji is picked at random from a small set for each platform: diff --git a/en/ai-sre/mcp.mdx b/en/ai-sre/mcp.mdx index 09d7b700..4ff7258b 100644 --- a/en/ai-sre/mcp.mdx +++ b/en/ai-sre/mcp.mdx @@ -74,11 +74,14 @@ Row names share a namespace with template names: if a system already has a templ ## Adding an MCP server -Go to **Customize → Plugins → MCP**. The list page has two entries in the top-right corner: +Go to **Customize → Plugins → MCP**. The list page has three entries in the top-right corner: +- **Add from catalog**: jumps to **Customize → Plugins → Overview** (the plugin catalog described above), where you pick and install a curated MCP template; it then appears in this list. It needs MCP create permission. - **Add MCP**: opens a form for defining an MCP server by hand (its fields are listed under "Basic Fields" below). - **Add in chat**: opens a session with a prefilled prompt. The agent asks whether you want to connect your own service or install an existing one, checks the plugin catalog first, and searches the web for candidates if nothing matches. The button appears only when the target scope is unambiguous (you have account-level permission, or exactly one of your teams is selected). +When the list is empty and you are not searching, the page shows "The plugin catalog has N built-in MCP servers. Install one to use it in sessions." and, if you can create MCP servers, a **Browse built-in MCP servers** button that jumps there. When the catalog is empty or you are searching, the original "No MCP servers configured" prompt appears instead. + ### Basic fields | Field | Type | Required | Description | @@ -205,7 +208,7 @@ An MCP server may be bound to execution environments **other than the current se - The agent sees the connector's name, purpose and available environments, and asking for it by name gets an explanation rather than "not found". - The agent dispatches a subagent into the target environment to call it (see [Agents](/en/ai-sre/agents)) and brings the result back to the conversation. -- Only **online** account-level Runners, Runners of the team bound to the session, and the bound cloud environment are valid targets. For others the agent explains it cannot use them right now. +- Valid targets are account-level Runners, Runners of the team bound to the session, and the bound cloud environment. Any Runner that has ever connected is a candidate, including ones currently offline; Runners that have never connected are not. An offline Runner only reports that the environment is unavailable when the dispatch is attempted. - Only the main session can dispatch this way; subagents cannot dispatch further. Conversely, to make a connector directly usable **here**, add the current environment to that server's Execution Environment list (provided the server is reachable from this session). See [Environments (BYOC)](/en/ai-sre/environments) for how the environments themselves differ. diff --git a/en/ai-sre/sessions.mdx b/en/ai-sre/sessions.mdx index 36576da8..5ae7613f 100644 --- a/en/ai-sre/sessions.mdx +++ b/en/ai-sre/sessions.mdx @@ -84,6 +84,7 @@ Type a message in the input and press Enter. The input supports Markdown; type ` - **Supported types**: images, PDF, text / Markdown / CSV / HTML, Office documents, archives (`.zip` / `.rar`), and any UTF-8 text file (such as `.go`, `.py`, `.yaml`). Empty files are rejected. - **Size and count**: up to **50 MB** per file; up to **9 attachments** per message, **50 MB** in total. + - **Images**: an image whose longest side is above **8192** px, whose shortest side is below **11** px, or whose aspect ratio exceeds **200:1** is scaled down, padded with white, and **re-encoded**, so its stored format and file extension can change (for example a GIF is stored as PNG and keeps only its first frame). Such an image above **40 megapixels** is rejected; send a smaller one. A corrupt image or an unrecognized format variant fails to upload. Images inside a folder are stored as sent. - **Folders**: choose **Upload folder** from the plus menu or drag a folder onto the input. A folder can hold up to **50 files** (`node_modules` and dot-files are not counted). A larger folder is rejected as a whole, and individual files that do not qualify are skipped with the reason listed. A folder counts as 1 attachment and keeps its directory structure. - **How the agent reads them**: attachments are provided as text. For text over 64 KB only the beginning is provided directly, and the agent reads the full file from the sandbox when needed. Archives and folders are not expanded up front; the agent unpacks and reads them in the sandbox as needed. </Accordion> @@ -92,6 +93,8 @@ Type a message in the input and press Enter. The input supports Markdown; type ` These entry points usually pre-fill a question as well (for example, asking the agent to separate confirmed facts from inferences); edit it as you like before sending. No question is pre-filled when several references are brought in at once. + Entering from the **Let AI tune noise reduction** button in the header of **Channel details → Noise reduction → Alert grouping / Flapping detection** also adds that channel to the input as a reference capsule and pre-fills a question that starts with `/channel-noise`. This is the only entry that can start `/channel-noise`: typing it in an IM, automation, or API session is rejected. See [Skills](/en/ai-sre/skills). + In any session, type `@` to search incidents and insert a reference. Typing an email address does not trigger the search. </Accordion> <Accordion title="Knowledge and Skills" icon="book"> @@ -143,6 +146,18 @@ When the agent needs clarification, it adds a question card — single choice, m If you send a new message instead of answering, the question is treated as skipped and your message runs immediately. Answering a question that was already skipped or answered elsewhere sends your answer as a regular message. +### Operating console pages + +Some console pages **declare that AI can operate them**: each turn sends the agent the actions available on the page you are viewing, so on these pages the agent can read and fill in the form directly instead of only giving written advice. + +Currently this covers the **Alert grouping** and **Flapping detection** pages under a channel's Noise reduction; see [Noise reduction](/en/on-call/channel/noise-reduction). Other pages have no page actions, so the agent cannot operate them. Page actions exist only in console sessions, not in IM, API, or automation sessions. + +- **Reading** the form (fields, current values, options, whether writable) needs no authorization. +- **Filling** a field only writes the value into the form; it does not submit. Review it and click **Save** yourself. +- **Saving**, and other actions that take effect immediately, each pop up their own confirmation card in the conversation (above the input), listing "old value → new value" with **Cancel** and the action's own verb (such as **Save**). + +Before touching the page, the agent asks with a question card how to apply the change: fill the form for you to review and save, or save directly. While it works, the page gets a brand-colored highlight and an **AI is working on this page** bar at the top, which changes to **Done** when finished; you can click **Stop** to interrupt. Sending a new message or leaving the session voids any unanswered confirmation card. In a shared session opened read-only, page actions do not run. + ### When authorization is required When a tool or MCP call needs a credential or OAuth authorization, an **"Authorize [resource name] to continue"** card appears: @@ -169,7 +184,9 @@ Only the console shows the connection card. In IM and API sessions the agent pos ### Subagents -When the agent delegates work, a subagent line appears in the conversation. It shows the type (Agent / A2A), name, execution environment, status, and duration. After the run, it also shows tool calls, token usage, and any failure reason. Click it to open the subagent session side by side; it can be expanded to full screen. +When the agent delegates work, a subagent line appears in the conversation. It shows the name, execution environment, status, and duration. After the run, it also shows tool calls, token usage, and any failure reason. The line carries no type badge; the type (Agent / A2A) appears in the title of the side panel. Click it to open the subagent session side by side; it can be expanded to full screen. + +A running subagent can also **report progress to the main agent**. A report appears in the main conversation as a **Subagent report** line: collapsed it is just a robot icon and the title, and clicking it shows the full text, starting with the subagent's name (generic names such as `agent` and `general` are not shown) and followed by the body as an Output block. While the subagent is still running, the report first appears as the same line under that dispatch; once the permanent record settles, this line disappears, so a report never shows twice. After a page refresh only the permanent record remains. A subagent may also need you: diff --git a/en/ai-sre/skills.mdx b/en/ai-sre/skills.mdx index df754d96..da7324e7 100644 --- a/en/ai-sre/skills.mdx +++ b/en/ai-sre/skills.mdx @@ -39,6 +39,12 @@ The AI SRE runtime bundles these skills; no installation needed: There are more, including `init`, `insight`, `artifact-design`, `alert-governance`, `channel-noise` and `monit-query`. `monit-query` loads only when the account has an enabled Monitors data source. To see which skills a given session has, ask the agent. +### `channel-noise`: console entry only, and it writes settings + +**It starts only from a channel's noise-reduction page.** Click **Let AI tune noise reduction** on **Channel details → Noise reduction → Alert grouping** or **Flapping detection**: the AI SRE panel opens with the channel attached as a reference and a `/channel-noise` question pre-filled, and it starts when you send it. Typing `/channel-noise` in IM, automation rules, or the Open API is rejected with `/channel-noise can only be started from its entry in the console.` The agent also does not pick it on its own, so asking in plain language to "look at this channel's alert noise" does not trigger it. + +**It writes settings.** It reads the channel's own alert history (the last 30 days by default), locates where the noise comes from, estimates several candidate **alert grouping** and **flapping detection** settings, and recommends one. Only after you explicitly confirm does it write to the channel and read the result back. It changes only alert grouping and flapping detection; other noise-reduction settings such as incident merging, silence, inhibition, and drop get suggestions only, for you to adjust. On the page itself it fills the recommended values into the form and they take effect when you click **Save**; see [Operating console pages](/en/ai-sre/sessions#operating-console-pages). + ## Install from marketplace The skill Marketplace is part of the plugin catalog on **Customize → Plugins → Overview**, under the **Skill** category; search by name or description. @@ -82,7 +88,10 @@ Updating a modified skill **overwrites your local changes with the latest Market ## Custom Skills -In addition to installing from the Marketplace, you can upload your own skill packages. On the skill list page, click **Upload Skill** and fill in the form: +In addition to installing from the Marketplace, you can upload your own skill packages. The toolbar of the skill list page has two entries: + +- **Add from catalog**: jumps to the **Skill** category of **Customize → Plugins → Overview** (the catalog described under "Install from marketplace"), where you pick and install a curated skill template; it then appears in this list. It needs the permission to upload skills. +- **Upload Skill**: opens the upload form. Fill in: | Field | Type | Required | Description | | --- | --- | --- | --- | @@ -95,6 +104,8 @@ At upload time, the system validates the package. The archive must be a valid zi The system reads all metadata other than the skill name from the `SKILL.md` frontmatter, including description, version, tags, author, and tools. You don't enter it in the form. </Note> +When the list is empty and you are not searching, the page shows "The plugin catalog has N built-in skills. Install one to use it in sessions." and, if you can upload skills, a **Browse built-in skills** button that jumps there. When the catalog is empty or you are searching, the original "no skills" message appears instead. + ### Overwrite upload (replace) By default, uploading an archive whose name matches an existing skill is rejected. To replace a skill with a new version, choose "Replace" in its detail panel. You can also upload a skill with the same name and confirm the "Replace" dialog. The SkillID stays the same, so references such as `/<skill-name>` keep working; a replace never creates a new skill. diff --git a/zh/ai-sre/agents.mdx b/zh/ai-sre/agents.mdx index 8872230f..f5f70565 100644 --- a/zh/ai-sre/agents.mdx +++ b/zh/ai-sre/agents.mdx @@ -20,7 +20,7 @@ sidebarTitle: Agent 委派后无需等待：AI SRE 把任务交给远端 Agent 后会立即继续当前对话，您可以继续工作或同时委派多个任务；远端完成后，其结果作为一条新消息出现在对话中。 -每次 A2A 委派在对话流里以一张带 `A2A` 徽标的**任务卡片**呈现，显示远端 Agent 名、本次任务意图、运行状态（初始化 / 进行中 / 等待输入 / 等待授权 / 完成 / 失败（含孤儿任务）/ 中断 / 已终止）以及工具调用数、Token、耗时等用量；点击卡片可在右侧面板里查看该次委派的完整过程。 +每次 A2A 委派在对话流里以一行呈现：机器人图标 + “已派发〈远端 Agent 名〉”文案 + 本次任务意图，右侧显示运行状态（初始化 / 进行中 / 等待输入 / 等待授权 / 完成 / 失败（含孤儿任务）/ 中断 / 已终止）以及工具调用数、Token、耗时等用量；点击这一行可在右侧面板里查看该次委派的完整过程，`A2A` 徽标标在该面板标题上，不在对话流这一行上。 <Tip> **调用说明决定 AI SRE 会不会选中这个 Agent。** 委派前，AI SRE 只看到清单里的一行 `名称：简介`（简介取自调用说明开头的 `summary:`），据此判断要不要派给它；正文只在首次委派时完整送达，可以写长写细。写法见[调用说明的写法](#调用说明的写法)。 @@ -266,14 +266,14 @@ Agent Card 同时声明了 Flashduty 的“运行选项”A2A 扩展：调用方 | `general` | 通用执行器，拥有完整工具权限，适合把中间步骤会污染主对话上下文的工作（长报告、多文件改动、端到端构建、反复探查）整体外包出去；可并行派发多个处理相互独立的工作单元 | | `explore` | 只读调查器，仅限 `grep` / `glob` / `read`，不能写入或执行；返回浓缩摘要而非原始搜索输出，适合在代码库或知识转储中定位证据 | -**会话中的呈现**：每次派发在对话流里同样以一张**任务卡片**呈现，状态与 A2A 委派相同，但徽标是 `Agent`（A2A 委派为 `A2A`）。卡片右侧还标出这次派发所在的**执行环境**（云端环境或 BYOC Runner 名称）。 +**会话中的呈现**：每次派发在对话流里同样以一行呈现，状态与 A2A 委派相同——机器人图标 + “已派发〈子代理名〉”文案（子代理名是 `agent` / `general` 这类类型同义词时写作 `subagent`）+ 本次任务意图，右侧标出这次派发所在的**执行环境**（云端环境或 BYOC Runner 名称）与该次运行的用量、状态；点击这一行可在右侧面板里查看完整过程，`Agent` 徽标（A2A 委派为 `A2A`）标在该面板标题上。 **运行约束**： - **并发上限**：每个会话**同一时刻最多运行 20 个 Subagent**。累计派发数不限，完成一个就释放一个名额；达到上限时，AI SRE 会等运行中的任务完成后再派发其余的。 - **嵌套深度**：派发链**最多嵌套 3 层**，防止 Subagent 无限自我派生。 -**运行环境**：子任务默认与当前会话在同一个环境里运行，共用同一套文件系统，能直接看到您 workspace 里的文件。AI SRE 也可以把子任务派到一个全新的云端环境（临时容器，文件系统独立，可访问公网，访问不到您的内网），或派到一台在线的 BYOC Runner（账户级 Runner，以及当前会话所绑定团队的 Runner）。指定的 Runner 不可用时，派发会失败并说明原因，不会改派到其他环境。A2A 委派不能选环境，远端 Agent 在它自己的环境里执行。环境的区别与选择方式见[运行环境（BYOC）](/zh/ai-sre/environments)。 +**运行环境**：子任务默认与当前会话在同一个环境里运行，共用同一套文件系统，能直接看到您 workspace 里的文件。AI SRE 也可以把子任务派到一个全新的云端环境（临时容器，文件系统独立，可访问公网，访问不到您的内网），或派到一台 BYOC Runner（账户级 Runner，以及当前会话所绑定团队的 Runner）。候选清单包含所有曾连接过的 Runner（含当前离线的），从未连接的不列出；是否可达在派发时才校验。指定的 Runner 不可用时，派发会失败并说明原因，不会改派到其他环境。A2A 委派不能选环境，远端 Agent 在它自己的环境里执行。环境的区别与选择方式见[运行环境（BYOC）](/zh/ai-sre/environments)。 **跨环境派发时无法读取父会话的文件**：派到其他环境的子会话使用自己的沙箱或 Runner 目录，读不到父会话的文件。因此 AI SRE 会把子任务需要的全部信息写进任务描述，结果以文本返回，或经外部系统（git、工单）流转。 @@ -281,7 +281,7 @@ Agent Card 同时声明了 Flashduty 的“运行选项”A2A 扩展：调用方 <CardGroup cols={2}> <Card title="控制台对话" icon="comments" href="/zh/ai-sre/sessions"> - 在会话中观察 A2A 委派的任务卡片及其子会话面板。 + 在会话中观察 A2A 委派及其子会话面板。 </Card> <Card title="MCP（外部工具）" icon="plug" href="/zh/ai-sre/mcp"> 为 Agent 接入外部工具，扩展其在任务中的能力边界。 diff --git a/zh/ai-sre/automations.mdx b/zh/ai-sre/automations.mdx index cd67d286..44afcb79 100644 --- a/zh/ai-sre/automations.mdx +++ b/zh/ai-sre/automations.mdx @@ -21,7 +21,7 @@ sidebarTitle: 自动化 入口：左侧导航 **AI SRE → 自动化**。 <Note> -自动化跑出的每一次运行，本质上仍是一个 AI SRE 会话——只是它被标记为隐藏，不混进您的日常会话列表。您随时可以从运行历史点进去，看到这次运行完整的对话、工具调用与产物（跑在 IM 群里的 **作战室创建触发** 运行除外，见下文“作战室创建触发（War room created）”）。 +自动化跑出的每一次运行，本质上仍是一个 AI SRE 会话——只是它被标记为隐藏，不混进您的日常会话列表。**Web** 执行位置的运行随时可以从运行历史点进去，看到完整的对话、工具调用与产物；**IM** 执行位置的运行（含 **作战室创建触发**）的对话在 IM 群里，控制台点不进去，见下文“执行位置”。 </Note> ## 新建自动化 @@ -33,11 +33,19 @@ sidebarTitle: 自动化 选择 **从零开始**，进入空白表单，手动填写名称、任务提示词与触发方式。适合您已经清楚要让 Agent 做什么、想完全自定义提示词的场景。 </Step> <Step title="基于预设模板"> - 下方列出一组 **预设模板** 卡片（随界面语言显示中文或英文版本），常见的有 **值班周报**、**告警治理**、**故障自动分析**、**On-call 负载分析** 等。点击任一模板卡片，会用模板预置的名称与任务提示词预填表单，您在此基础上微调即可。 + 下方列出一组 **预设模板** 卡片（随界面语言显示中文或英文版本），常见的有 **值班周报**、**告警治理**、**故障自动分析**、**On-call 负载分析** 等。点击任一模板卡片，会用模板预置的名称与任务提示词预填表单，您在此基础上微调即可。其他页面也可以用链接直接打开某个模板的创建表单：`/ai-sre/automations/new?template=<模板键>`；链接再带上 `oncall_incident_channel_ids=<id>,<id>` 时，**On-call 故障触发** 的协作空间会一并选好。这类链接可以分享，刷新后仍然生效。 </Step> </Steps> -无论从哪条入口进入，接下来都是同一张配置表单。 +无论从哪条入口进入，接下来都是同一张配置表单。控制台的两个入口一律创建 **Web** 执行位置的规则；要让规则跑在某个 IM 群聊里，得从 IM 会话里创建： + +### 在 IM 会话里创建（绑定当前会话） + +在 IM 群聊或私聊里让 Agent 建一条自动化，不指定执行位置时，规则绑定到**当前这个会话**，并继承它的范围（包括绑定的团队）。命令行等同：在 IM 会话里发起 `flashduty automation create` 时省略 `--run-in`（见[命令行工具](/zh/developer/cli)）。 + +- 绑定后每次运行都在那个群聊里新开会话，不在控制台建会话；绑定的群聊固定不变。 +- 想让它跑在 **Web** 上，创建时要说清楚（在对话里要求用 Web 控制台执行，或命令行加 `--run-in web`）。规则建好后改不了，只能重建。 +- 不要自己传 chat、平台、集成或会话 ID，服务端负责解析并鉴权当前会话。 ## 配置字段 @@ -46,8 +54,8 @@ sidebarTitle: 自动化 | 字段 | 必填 | 说明 | |---|---|---| | 名称 | 是 | 规则名称，最长 255 字符。占位示例：`每周值班洞察`。 | -| 范围 | 是 | 通过 **范围选择器** 选 **个人**或某个 **团队**。范围既决定这条规则的归属与编辑权限，也限定 **执行 Environment** 里可选的自托管 Runner——只有账户全局的 Runner，以及与该范围同团队的 Runner 才可选。 | -| 执行环境 | 否 | 通过 **环境选择器** 选运行环境：**自动**（由系统挑选最优可用环境，默认值）、**云端沙箱**，或某个 **自托管（BYOC）Runner**。选了某个团队范围后，不属于该范围的团队 Runner 会被自动清除。 | +| 范围 | 是 | 通过 **范围选择器** 选 **个人**或某个 **团队**。范围既决定这条规则的归属与编辑权限，也限定 **执行 Environment** 里可选的自托管 Runner——只有账户全局的 Runner，以及与该范围同团队的 Runner 才可选。范围创建后不可修改，规则详情页把它展示为 **固定范围**。 | +| 执行环境 | 否 | 通过 **环境选择器** 选运行环境：**自动**（由系统挑选最优可用环境，默认值）、**云端沙箱**，或某个 **自托管（BYOC）Runner**。选了某个团队范围后，不属于该范围的团队 Runner 会被自动清除。**IM** 执行位置的规则不使用这里选的环境（见下文“执行位置”）。 | | 任务提示词 | 是 | 描述要让 AI SRE 执行的任务，用富文本编辑器撰写。这段提示词就是每次运行时发给 Agent 的内容。占位提示：`描述 Flashduty AI SRE 要执行的任务。` | | 时区 | 否 | **按周期执行** 触发卡片里的字段（见下文“按周期执行（cron）”）：cron 表达式所依据的 **规则时区**，用一个可搜索的下拉框选择 IANA 时区名（如 `Asia/Shanghai`），选项按下拉框里的 UTC 偏移排列。新建规则时默认为你的生效时区（成员时区优先，成员未设置时回退账户时区）；没有可用时区时该字段留空，创建请求不携带它。 | @@ -55,6 +63,33 @@ sidebarTitle: 自动化 **执行环境** 的“自动”会在每次运行时由系统挑选当前最优的可用环境；“云端沙箱”是平台托管的临时沙箱；自托管 Runner 则把运行落在您自己的机器上。三者的差异与连接方式见 <a href="/zh/ai-sre/environments">运行环境</a>。 </Note> +## 执行位置（规则跑在哪里） + +每条规则有一个 **执行位置**，创建时固定，之后不能在控制台修改： + +- **Web**（默认）：每次运行是控制台里的一个隐藏会话。控制台创建的规则一定是这个取值。 +- **IM**：运行发生在创建时绑定的 IM 群聊 / 私聊里。每次运行都在原群聊里**新开一个会话**；该 IM 集成开启话题时，每次运行还新开一个话题；同一次运行的重试复用这次的会话与话题；绑定的群聊永远不变。 + +规则列表的 **执行位置** 列和规则详情页“配置信息”里的 **执行位置** 都显示这个取值（`IM` 或 `Web`）。一条规则同时启用了 **作战室创建触发** 和其它触发时，这一列显示两枚徽标：**作战室触发→IM** 与 **其他触发→Web**。**作战室创建触发** 是唯一不使用规则执行位置的触发方式，它按作战室所在群执行，见下文“作战室创建触发（War room created）”。 + +**IM** 执行位置的规则与 Web 规则还有几点不同： + +- 控制台不提供 **克隆**；要换成 Web 执行，只能重建一条。 +- 控制台不暴露这类运行的会话：运行历史里“名称”列显示 `-`，点击该行只提示 **本分析位于 IM，请进入 IM 查看。**；从规则行手动执行也不会跳进会话。 +- 不使用规则上选的 **执行环境**，用的是该群聊已经选好的执行环境（可在会话里用 `/env` 更换）；表单照常显示环境选择器，但对 IM 运行不生效。 +- **绑定失效就跳过**：运行发生时，如果绑定群聊的范围或会话已经变了（例如在群里用 `/scope` 换过绑定的团队，或这个群重开过会话），本次运行会被**跳过**，运行历史里状态为 `已跳过`、原因 `chat_scope_mismatch`。规则保持启用，也不会被搬到别的群；要换群请重建规则。 + +### 经 API / CLI 创建时怎么指定（`run_in`） + +控制台创建的规则一律是 **Web**；经 API 或 CLI 创建时，用 `run_in` 明确指定： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `run_in` | string | `current-chat`：把规则绑定到鉴权来源所在的**实时 IM 会话**，只能在该 IM 会话里发起调用时使用，在别处传会被拒绝；`web`：在控制台里执行。省略时来自 IM 会话的调用取 `current-chat`，其余取 `web`。 | +| `team_id` | int64 | 规则的归属范围。显式 `0` 表示个人范围，大于 `0` 表示账户内的某个团队；省略时，来自 IM 会话的调用继承该会话的范围。`run_in=current-chat` 时，显式传入的值必须与该会话的范围一致。 | + +`update` 不接受 `run_in`：执行位置与范围一样，创建后不可变更。命令行对应参数见[命令行工具](/zh/developer/cli)。 + ## 触发方式 一条规则必须 **至少配置一种触发方式**。当前控制台表单在“触发方式”区提供 **按周期执行**、**经 API 调用**、**On-call 故障触发** 与 **作战室创建触发** 四种入口，四种可同时启用。 @@ -233,11 +268,11 @@ curl -X POST 'https://<触发地址>' \ | 列 | 说明 | |---|---| -| 名称 | 本次运行对应的隐藏会话标题，解析不到时显示会话 ID。被并入其它分析的运行没有自己的会话，改显示对应的故障（`#<num> <title>`），并在下一行标明并入了哪次分析 | +| 名称 | 本次运行对应的隐藏会话标题，解析不到时显示会话 ID；**IM** 执行位置的运行显示 `-`（对话在 IM 群里）。被并入其它分析的运行没有自己的会话，改显示对应的故障（`#<num> <title>`），并在下一行标明并入了哪次分析 | | 执行时间 | 本次运行的开始时间 | | 耗时 | 本次运行的持续时长 | | 触发方式 | 本次运行的触发类型标签，如 `定时`、`HTTP POST`、`On-call incident`、`手动执行` 或 `作战室创建触发` | -| 执行位置 | 本次运行跑在哪里：`IM`（会话在 IM 群里，例如作战室创建触发的运行）或 `Web 控制台`（控制台里的隐藏会话） | +| 执行位置 | 本次运行跑在哪里：`IM`（会话在 IM 群里，例如作战室创建触发的运行）或 `Web`（控制台里的隐藏会话） | | 状态 | 本次运行的状态（见下表） | 运行状态的取值： @@ -249,7 +284,7 @@ curl -X POST 'https://<触发地址>' \ | `succeeded` | 成功 | | `partial` | 部分成功 | | `failed` | 失败 | -| `skipped` | 已跳过。两种情形共用这个状态：触发时判定不执行（例如规则所有者已失效、周期已停止），或该故障被并入另一个正在运行的分析（见上文“相似故障合并分析”） | +| `skipped` | 已跳过。三种情形共用这个状态：触发时判定不执行（例如规则所有者已失效、周期已停止）；该故障被并入另一个正在运行的分析（见上文“相似故障合并分析”）；或 **IM** 执行位置的规则触发时，绑定群聊的范围 / 会话已经变了（见上文“执行位置”） | | `blocked` | 已阻塞。本次运行产生了真实输出，但停在等待人工处理的连接器上——某个连接器还没配置，或需要管理员在控制台完成授权 | | `abandoned` | 已放弃（长时间未完成被系统终止） | @@ -259,7 +294,7 @@ curl -X POST 'https://<触发地址>' \ - **状态**：按上表中的运行状态过滤，或选 **全部状态**。 - **触发类型**：`全部触发类型` / `手动执行` / `定时` / `HTTP POST` / `On-call incident` / `作战室创建触发` 六选一。 -API 返回的运行记录还包含 `trigger_kind`，可能取值为 `schedule`、`manual`、`http_post`、`oncall_incident`、`war_room_created` 或 `debug`。其中 `manual` 表示通过立即执行接口启动，`oncall_incident` 表示由匹配的 On-call 故障事件启动，`war_room_created` 表示由作战室创建触发启动（会话在 IM 群里）。被并入其它分析的运行不返回自己的 `session_id`，而是返回它并入的那次分析的会话 ID `joined_session_id` 与会话名 `joined_session_name`；这两个字段为空，表示这次运行有自己的隐藏会话。 +API 返回的运行记录还包含 `trigger_kind`，可能取值为 `schedule`、`manual`、`http_post`、`oncall_incident`、`war_room_created` 或 `debug`。其中 `manual` 表示通过立即执行接口启动，`oncall_incident` 表示由匹配的 On-call 故障事件启动，`war_room_created` 表示由作战室创建触发启动（会话在 IM 群里）。`execution_place` 为 `im` 的运行不返回会话身份：`session_id` 与 `joined_session_id` 为空，`result_json` 也不下发，只保留状态、时间与错误字段。被并入其它分析的运行不返回自己的 `session_id`，而是返回它并入的那次分析的会话 ID `joined_session_id` 与会话名 `joined_session_name`；这两个字段为空，表示这次运行有自己的隐藏会话。 点击一行，会跳转到这次运行对应的隐藏会话对话页，让您查看该次运行完整的消息、工具调用与产物。跑在 IM 群里的运行（例如作战室创建触发的运行）不跳转，而是弹出一句 **本分析位于 IM，请进入 IM 查看。**——这次分析的对话在 IM 群里读。被并入其它分析的运行没有自己的会话，点击它会打开接管这个故障的那次分析。 @@ -274,6 +309,7 @@ API 返回的运行记录还包含 `trigger_kind`，可能取值为 `schedule` | 执行超时未完成，已放弃 | 在规则详情页点击 **手动执行** 重试 | | 本次执行被中断 | 在规则详情页点击 **手动执行** 重试 | | 执行已结束，但没有生成最终回复 | 在规则详情页点击 **手动执行** 重试 | +| 绑定群聊的范围或会话已变化，本次未执行（`chat_scope_mismatch`） | 规则仍启用，仍在原群聊执行；需要换群请新建规则 | | 已并入另一次分析 | 点击该行打开接管故障的分析 | 其他原因直接显示系统记录的文本。 @@ -291,7 +327,7 @@ API 返回的运行记录还包含 `trigger_kind`，可能取值为 `schedule` | 操作 | 说明 | |---|---| | 启用 / 停用 | 行内开关。停用后规则保留，但不再触发；停用不会删除已有运行历史。 | -| 立即执行 | 在规则行手动启动一次真实运行。该操作会先做运行前检查，然后为本次运行创建一个隐藏会话；同一规则手动执行最多每分钟一次。当规则的唯一触发方式是 **作战室创建触发** 时，列表和详情页都不提供这个操作——这类规则不会产生控制台运行，调用立即执行接口会直接报错。 | +| 立即执行 | 在规则行手动启动一次真实运行。该操作会先做运行前检查。**Web** 执行位置的规则会新建一个隐藏会话并直接打开；**IM** 执行位置的规则在绑定的 IM 群聊里新开会话，控制台只提示 **手动执行已提交，请在执行历史中查看进度**。同一规则手动执行最多每分钟一次。当规则的唯一触发方式是 **作战室创建触发** 时，列表和详情页都不提供这个操作——这类规则不会产生控制台运行，调用立即执行接口会直接报错。 | 点击规则行任意位置会打开该规则的详情页，在详情页里可以编辑配置、删除规则，也能看到运行历史（见上文“运行历史”一节）。 @@ -303,7 +339,7 @@ API 返回的运行记录还包含 `trigger_kind`，可能取值为 `schedule` 自动化规则与其它 AI SRE 资源共用同一套两级作用域，通用规则见[作用域与权限](/zh/ai-sre/context#作用域与权限)。自动化特有的几点： -- **范围创建后不可修改**，需要换范围时，在规则详情页点击**克隆**，为副本选择新范围。 +- **范围创建后不可修改**，需要换范围时，在规则详情页点击**克隆**，为副本选择新范围（**IM** 执行位置的规则不提供克隆）。 - 团队规则在创建者离开团队后继续运行；个人规则在创建者不再是账户有效成员时自动停用。 - **个人规则**仅创建者本人可查看和管理。账户 Owner 与管理员能在列表中看到它，但进入详情页会被拒绝。 - **HTTP POST 触发**只校验触发地址的 Bearer Token：持有 Token 的外部系统可以触发，运行按规则的个人或团队范围创建隐藏会话。On-call 故障触发和作战室创建触发不使用该 Token，运行同样按规则的范围归属。 diff --git a/zh/ai-sre/environments.mdx b/zh/ai-sre/environments.mdx index 2471fee4..a17195ee 100644 --- a/zh/ai-sre/environments.mdx +++ b/zh/ai-sre/environments.mdx @@ -65,7 +65,9 @@ AI SRE 提供两类运行环境： 环境变量以明文形式对所有使用该云端环境模板的人可见——请勿在这里填写密钥或凭据。 </Warning> -**平台保留的环境变量名。** 以下变量由平台注入，模板里设置它们会在保存时被拒绝：`FLASHDUTY_APP_KEY`、`FLASHDUTY_BASE_URL`、`FLASHDUTY_DOCS_URL`、`PATH`、`HOME`，以及 GitHub（`GH_TOKEN*`、`GIT_CONFIG_*`）和 GitLab（`GITLAB_*`、`GLAB_*`）的认证与主机配置变量。 +**平台保留的环境变量名。** 以下变量由平台注入，模板里设置它们会在保存时被拒绝：`FLASHDUTY_APP_KEY`、`FLASHDUTY_BASE_URL`、`FLASHDUTY_DOCS_URL`、`FLASHDUTY_CONSOLE_URL`、`PATH`、`HOME`，以及 GitHub（`GH_TOKEN*`、`GIT_CONFIG_*`）和 GitLab（`GITLAB_*`、`GLAB_*`）的认证与主机配置变量。 + +`FLASHDUTY_CONSOLE_URL` 是控制台地址，Agent 用它把结论里引用的故障、告警、协作空间、值班表等拼成可点击的链接；没有配置控制台地址时不注入，Agent 改在正文里用资源 ID 指代。它不含密钥，Agent 可以读取。 即使通过其他方式设置了同名变量，执行命令时也以平台的值为准（云端 Sandbox 与自托管 Runner 相同）。模板中的环境变量只用于非敏感的业务配置；需要密钥时，请使用 MCP 的成员授权或相应的 App 集成。 diff --git a/zh/ai-sre/im.mdx b/zh/ai-sre/im.mdx index 703634b3..c50f58e2 100644 --- a/zh/ai-sre/im.mdx +++ b/zh/ai-sre/im.mdx @@ -9,7 +9,7 @@ sidebarTitle: IM 平台 排障往往就发生在您的 IM 群里——告警推过来、大家在群里讨论、拉个作战室。AI SRE 把 Agent 直接放进这条协作链路：**您不必切换到控制台，就能在 IM 里召唤它排查**，团队成员也能全程看到它的分析过程。 -AI SRE 的 IM 集成有两种触发方式： +AI SRE 的 IM 集成有三种触发方式： <CardGroup cols={2}> <Card title="@ 提及召唤" icon="at"> @@ -18,8 +18,13 @@ AI SRE 的 IM 集成有两种触发方式： <Card title="作战室自动诊断" icon="people-group"> 为故障开启 IM 作战室时，若账户里有一条启用中的 **作战室创建触发** 自动化规则、且这条故障的协作空间与严重程度命中该规则，AI SRE 会执行一轮初步诊断，并把结论作为一条分析消息发回作战室——无需任何人手动召唤。 </Card> + <Card title="群内自动化回帖" icon="clock"> + 在群里让 AI SRE 建一条普通自动化规则，它就把**当前这个群**作为运行位置：之后按周期、API 或 On-call 故障触发时，在原群里**新开一个会话**跑这一轮，结论直接回帖到群里。每次运行都是全新的会话，不带入群里的历史对话；集成开启话题回复时也新开一个话题，本次运行的第一条真实输出（进展或结论）就是话题的根消息，产出内容之前不会先发“已开始”之类的占位消息。绑定与范围在创建时固定、不能改到别的群：运行前会复核，群的团队范围或会话已变就整次**跳过**。 + </Card> </CardGroup> +前两种方式由人发起，第三种由您配好的自动化规则发起。规则怎么建、执行位置与范围怎么固定，见[自动化](/zh/ai-sre/automations#执行位置规则跑在哪里)。 + ## 支持的 IM 平台 AI SRE 的 IM 交互覆盖四个主流平台，每个平台都支持入站的 @ 提及（webhook）、历史消息读取与出站回复： @@ -57,7 +62,7 @@ IM 交互依赖您已在 Flashduty 中接入对应平台的机器人（用于告 平台区分**群聊 @ 提及**与**私聊消息**两种入口。被提及后，AI SRE 会给这条消息添加一个“处理中”回执（见[处理中回执](#处理中回执)），并识别消息里是否带有斜杠命令。 </Step> <Step title="绑定会话"> - 同一个 IM 会话里的多次 @ 提及，会续接到**同一个 Agent 会话**，从而保留上下文。若是新会话，AI SRE 会带入该 IM 线程的起始消息，以及（若有）关联的故障作为初始上下文。 + 同一个 IM 会话里的多次 @ 提及，会续接到**同一个 Agent 会话**，从而保留上下文。若是新会话，AI SRE 会带入该 IM 线程的起始消息，以及（若有）关联的故障作为初始上下文。在开启了话题回复的飞书 / Lark 群里，由**顶层 @** 新开的话题会话还会额外带入该群**最近 10 分钟**（截止到这条 @ 为止）的群消息，您在 @ 之前贴的报错文本或截图就是这样进入上下文的；话题内的回复只读它自己那个话题。 </Step> <Step title="读取上下文作答"> AI SRE 读取线程 / 会话的历史消息构建上下文，自主排查，并把结论**在线程内**回复。消息里一并 @ 到的其他人也会被保留为提及对象，在回复中带上，方便多方在群里协作。 @@ -68,6 +73,23 @@ IM 交互依赖您已在 Flashduty 中接入对应平台的机器人（用于告 **回复模式**可配置（off / first / all），决定 AI SRE 是否在回复时 @ 提问者、以及是在**线程内**还是主频道作答。在嘈杂的大群里，线程内回复能让排查讨论保持聚拢、不刷屏。 </Tip> +### 附件与图片 + +聊天里的图片、文档与语音，AI SRE 会自己下载并作为文件交给 Agent。不只是 **@ 它那条消息**上的附件，**同一线程 / 会话里更早的消息**上的附件也会一并带上：您先贴一张报错截图、再补一句“@bot 这个怎么回事”，模型拿到的是那张截图。 + +每轮的附件额度按类型计算，当前这条消息的附件先占额度，历史消息从剩下的额度里补，从最新的一条往前挑： + +| 类型 | 每轮上限 | +| --- | --- | +| 图片 | 5 个 | +| 文档 | 3 个 | +| 语音 | 3 个 | + +- **放不进额度的历史附件**：在提示里标注为“未附带”，不会承诺一个实际不存在的文件。 +- **超限即拒**：单个附件超过 20 MiB，或直链不是 HTTPS，都会被拒绝。 +- **历史附件有时间预算**：约 5 秒内没下载完的历史附件按“未附带”处理，排查不会为一张旧截图卡住。 +- **当前消息的附件全部失败**：AI SRE 不调用 Agent，直接回复“无法处理本次附带的附件。请重试，或发送较小的文件。”；历史附件失败不会中止排查。 + ### 处理中回执 收到您的消息后，机器人会先给**您发出的那条消息**添加一个表情回执，作为“已收到、正在处理”的即时信号。表情从该平台的一小组表情里随机选取： diff --git a/zh/ai-sre/mcp.mdx b/zh/ai-sre/mcp.mdx index 7e4f8bc7..02b153aa 100644 --- a/zh/ai-sre/mcp.mdx +++ b/zh/ai-sre/mcp.mdx @@ -74,11 +74,14 @@ sidebarTitle: "MCP 外部工具" ## 添加 MCP 服务器 -进入 **自定义 → 插件 → MCP** 页面，列表页右上角有两个入口： +进入 **自定义 → 插件 → MCP** 页面，列表页右上角有三个入口： +- **从插件目录添加**：跳到 **自定义 → 插件 → 概览**（插件目录，见上文“从市场安装 MCP 服务器”），挑选并安装预置的 MCP 模板，安装后出现在本列表中。需要 MCP 的创建权限。 - **添加 MCP**：点击后弹出表单，手工定义一台 MCP 服务器（字段见下文“基础字段”）。 - **在对话中添加**：新建一条预填提示的会话，由 Agent 询问您要接入自己的服务还是安装现成的，先查插件目录，没有再联网搜索候选供您选择。只有在能确定写入范围时（您有账户级权限，或当前只选中了一个您所属的团队）才显示此按钮。 +列表为空且没有在搜索时，页面显示“插件目录里有 N 个预置 MCP，安装后即可在会话中使用。”，并在有创建权限时给出 **浏览预置 MCP** 按钮直接跳转；插件目录为空或正在搜索时，仍显示“尚未配置 MCP 服务器。点击上方按钮添加。” + ### 基础字段 | 字段 | 类型 | 是否必填 | 说明 | @@ -205,7 +208,7 @@ MCP 服务器可能绑定在**当前会话之外的执行环境**中。由于不 - Agent 能看到这类连接器的名称、用途和可用环境，按名字询问时也会得到说明，而不是“找不到”。 - Agent 会派一个子代理到目标环境中调用它（见 [Agent](/zh/ai-sre/agents)），再把结果带回当前对话。 -- 只能派往**在线**的账户级 Runner、当前会话所绑定团队的 Runner，以及绑定的云端环境；其他环境 Agent 会说明暂时无法使用。 +- 可派往账户级 Runner、当前会话所绑定团队的 Runner，以及绑定的云端环境。曾连接过的 Runner（含当前离线的）都在候选里，从未连接的 Runner 不在；离线 Runner 要到派发时才会报该环境不可用的原因。 - 只有主会话能这样派发，子代理不能再派发。 在**当前**环境里直接可用，把它加进该服务器的“执行环境”列表即可（前提是它对这个会话可达）。运行环境本身的区别见 [运行环境（BYOC）](/zh/ai-sre/environments)。 diff --git a/zh/ai-sre/sessions.mdx b/zh/ai-sre/sessions.mdx index 636fac71..333e8071 100644 --- a/zh/ai-sre/sessions.mdx +++ b/zh/ai-sre/sessions.mdx @@ -84,6 +84,7 @@ sidebarTitle: "控制台对话" - **支持的类型**：图片、PDF、文本 / Markdown / CSV / HTML、Office 文档、压缩包（`.zip` / `.rar`），以及任何 UTF-8 编码的文本文件（如 `.go`、`.py`、`.yaml`）。空文件不能上传。 - **大小与数量**：单个文件最大 **50MB**；每条消息最多 **9 个附件**，总大小不超过 **50MB**。 + - **图片**：最长边大于 **8192** 像素、短边小于 **11** 像素、或长短边比超过 **200:1** 的图片，会被自动缩放、补白边后**重新编码**，存储格式和文件扩展名可能随之改变（例如 GIF 会存成 PNG，动图只保留第一帧）。这类图片超过 **4000 万像素** 会被拒绝，请换一张更小的；图片损坏或格式变体无法识别时上传失败。文件夹里的图片按原样保存，不做这一处理。 - **文件夹**：可以从加号菜单选择 **上传文件夹**，或把文件夹拖进输入区。一个文件夹最多 **50 个文件**（`node_modules` 和以 `.` 开头的文件不计入），超过时整个文件夹会被拒绝；不符合要求的单个文件会被跳过并列出原因。一个文件夹算 1 个附件，目录结构会保留。 - **Agent 如何读取**：附件以文本形式提供给 Agent；超过 64KB 的文本只直接提供开头部分，Agent 会在需要时从沙箱中读取完整文件。压缩包和文件夹不会直接展开，Agent 在沙箱中按需解包和读取。 </Accordion> @@ -92,6 +93,8 @@ sidebarTitle: "控制台对话" 这些入口通常还会预填一句提问（例如要求 Agent 区分已确认事实与推断），您可以修改后再发送。一次带入多个引用时不会预填提问。 + 从**协作空间详情 → 降噪处理 → 告警聚合 / 抖动检测**页头的 **让 AI 帮我配置降噪** 进入时，该协作空间同样会作为引用标签放进输入框，并预填一条以 `/channel-noise` 开头的提问。这是 `/channel-noise` 唯一能启动的入口：在 IM、自动化或 API 会话里输入该命令会被拒绝。详见 [Skill](/zh/ai-sre/skills)。 + 在任意会话中输入 `@` 可以搜索故障并插入引用。输入邮箱地址时不会触发搜索。 </Accordion> <Accordion title="知识与 Skill" icon="book"> @@ -143,6 +146,18 @@ Agent 需要您澄清信息时，会在对话中插入提问卡片，可能是 如果您不回答卡片而是直接发送新消息，提问会被视为跳过，您的消息立即执行。已经跳过或在其他设备回答过的提问，再提交答案会作为一条普通消息发送。 +### 操作控制台页面 + +有些控制台页面会**声明自己能被 AI 操作**：它把当前可用的动作清单和您所在的页面随每一轮消息发给 Agent，所以在这类页面上，Agent 不只给出文字建议，还能直接读取和填写页面上的表单。 + +目前支持的是协作空间降噪处理下的 **告警聚合** 与 **抖动检测** 两页，见[告警降噪](/zh/on-call/channel/noise-reduction)；其余页面没有页面动作，Agent 无法操作。页面动作只在控制台会话里存在，IM、API 和自动化会话中不会出现。 + +- **读取**表单（字段、当前值、可选项、是否可写）不需要授权。 +- **填写**字段只是把值写进表单，不会替您提交，您复核后自己点 **保存**。 +- **保存**这类立即生效的动作，每次都在对话里单独弹出确认卡片（显示在输入框上方）：列出「原值 → 新值」，按钮是 **取消** 和动作自带的动词（如 **保存**）。 + +操作页面之前，Agent 会先用提问卡片问您这次改动怎么落地：填进表单由您复核后自己保存，还是直接保存。执行期间页面四周出现品牌色高亮，顶部出现 **AI 正在操作页面** 状态条，完成后变为 **已完成**；您也可以点 **停止** 中断。发出新消息或离开会话后，尚未答复的确认卡片自动失效。以只读方式打开他人分享的会话时，页面动作不会执行。 + ### 需要授权时 工具或 MCP 调用缺少凭证或 OAuth 授权时，对话中会出现 **授权〈资源名〉以继续** 卡片： @@ -169,7 +184,9 @@ Agent 需要您澄清信息时，会在对话中插入提问卡片，可能是 ### 子任务（Subagent） -Agent 委派子任务时，对话中会出现一行子任务引用，显示类型（Agent / A2A）、名称、执行环境、状态与耗时，结束后显示工具调用数、Token 用量和失败原因。点击它会在右侧并排打开子会话，可以展开为全屏。 +Agent 委派子任务时，对话中会出现一行子任务引用，显示名称、执行环境、状态与耗时，结束后显示工具调用数、Token 用量和失败原因；这一行不带类型徽标，类型（Agent / A2A）标在右侧子会话面板的标题上。点击它会在右侧并排打开子会话，可以展开为全屏。 + +子任务运行中还可以**向主 Agent 汇报进展**。汇报在主对话里显示为一行 **子代理汇报**：收起时只有机器人图标和这行标题，点击展开查看全文——先显示子代理名（`agent`、`general` 这类通用名不显示），正文以 Output 输出块呈现。子任务仍在运行时，汇报先以同样的一行出现在该次派发下方；正式记录落定后这行自动消失，同一份汇报不会显示两次。刷新页面后只保留正式记录。 子任务还可能处于两种需要您处理的状态： diff --git a/zh/ai-sre/skills.mdx b/zh/ai-sre/skills.mdx index 24423c75..a25a9a98 100644 --- a/zh/ai-sre/skills.mdx +++ b/zh/ai-sre/skills.mdx @@ -39,6 +39,12 @@ AI SRE 运行时内置了以下 Skill，无需安装即可使用： 此外还有 `init`、`insight`、`artifact-design`、`alert-governance`、`channel-noise` 和 `monit-query` 等。`monit-query` 仅在账户里有已启用的 Monitors 数据源时才会加载。某条会话里实际可用的 Skill，直接问 Agent 即可。 +### `channel-noise`：只从降噪页进入，且会写配置 + +**只能从协作空间的降噪处理页面进入。** 在 **协作空间详情 → 降噪处理 → 告警聚合** 或 **抖动检测** 页面点击 **让 AI 帮我配置降噪**，会打开 AI SRE 面板，把该协作空间作为引用带入对话并预填 `/channel-noise` 提问，您发送后才启动。IM、自动化规则、Open API 里输入 `/channel-noise` 会被拒绝，提示 `/channel-noise can only be started from its entry in the console.`。它也不在 Agent 自行选用的 Skill 之列，用自然语言让 Agent“看看这个空间的告警噪音”不会触发它。 + +**它会写配置。** 它读取该协作空间自己的告警历史（默认近 30 天），先定位噪音来源，再估算若干组**告警聚合**与**抖动检测**候选设置并给出推荐；只有您明确确认后，才会写入该空间并回读复核。改动仅限告警聚合与抖动检测，事件聚合、静默、抑制、丢弃等其他降噪设置只给出建议，由您自行调整。在该页面上使用时，它把推荐值填入表单，由您点击 **保存** 后生效，见[操作控制台页面](/zh/ai-sre/sessions#操作控制台页面)。 + ## 从市场安装 Skill 市场位于 **自定义 → 插件 → 概览** 的插件目录中，归在 **Skill** 类别下，可按名称或描述搜索。 @@ -82,7 +88,10 @@ Skill 市场位于 **自定义 → 插件 → 概览** 的插件目录中，归 ## 自定义 Skill -除了从市场安装，您也可以上传自己的 Skill 包。在 Skill 列表页点击 **上传 Skill**，在表单中填写： +除了从市场安装，您也可以上传自己的 Skill 包。Skill 列表页的工具栏提供两个入口： + +- **从插件目录添加**：跳到 **自定义 → 插件 → 概览** 的 **Skill** 类别（即上文“从市场安装”的插件目录），挑选并安装预置的 Skill 模板，安装后出现在本列表中。需要上传 Skill 的权限。 +- **上传 Skill**：打开上传表单，在表单中填写： | 字段 | 类型 | 是否必填 | 说明 | | --- | --- | --- | --- | @@ -95,6 +104,8 @@ Skill 市场位于 **自定义 → 插件 → 概览** 的插件目录中，归 Skill 名以外的元数据（描述、版本、标签、作者、工具等）都从 `SKILL.md` 的 frontmatter 解析得到，无需在表单中重复填写。 </Note> +列表为空且没有在搜索时，页面显示“插件目录里有 N 个预置 Skill，安装后即可在会话中使用。”，并在有上传权限时给出 **浏览预置 Skill** 按钮直接跳转；插件目录为空或正在搜索时，仍显示“暂无 Skill”的原提示。 + ### 覆盖上传（Replace） 默认情况下，上传与已有 Skill 同名的归档会被拒绝。要用新版本替换已有 Skill，在检视面板选择“替换”，或在上传同名 Skill 时确认弹出的“替换”对话框。替换后 SkillID 不变，`/<skill-name>` 等引用继续有效；目标 Skill 不存在时不会新建。 From 8a50f65aae20324e4003866626c00fc85f9c99f5 Mon Sep 17 00:00:00 2001 From: ysyneu <ysyneu@gmail.com> Date: Sat, 17 Oct 2026 03:43:19 -0700 Subject: [PATCH 2/5] docs(on-call): document member auto-linking, literal wildcards, AI noise analysis and calendar updates --- en/on-call/channel/create-edit.mdx | 3 +- en/on-call/channel/integrate-data.mdx | 7 +++- en/on-call/channel/noise-reduction.mdx | 35 +++++++++++++++++-- en/on-call/comparison/vs-opsgenie.mdx | 2 +- en/on-call/comparison/vs-pagerduty.mdx | 2 +- .../configuration/filter-conditions.mdx | 2 ++ en/on-call/configuration/service-calendar.mdx | 10 +++--- en/on-call/incident/search-view-incident.mdx | 2 ++ en/on-call/incident/work-items.mdx | 16 ++++++++- .../alert-sources/aliyun-dataworks-op.mdx | 18 +++++----- .../alert-integration/routing-rules.mdx | 2 +- .../instant-messaging/dingtalk.mdx | 17 +++++++-- .../integration/instant-messaging/lark.mdx | 10 ++++++ .../integration/instant-messaging/slack.mdx | 8 +++-- zh/on-call/channel/create-edit.mdx | 3 +- zh/on-call/channel/integrate-data.mdx | 7 +++- zh/on-call/channel/noise-reduction.mdx | 35 +++++++++++++++++-- zh/on-call/comparison/vs-opsgenie.mdx | 2 +- zh/on-call/comparison/vs-pagerduty.mdx | 2 +- .../configuration/filter-conditions.mdx | 2 ++ zh/on-call/configuration/service-calendar.mdx | 10 +++--- zh/on-call/incident/search-view-incident.mdx | 2 ++ zh/on-call/incident/work-items.mdx | 16 ++++++++- .../alert-sources/aliyun-dataworks-op.mdx | 27 +++++++++++++- .../alert-integration/routing-rules.mdx | 2 +- .../instant-messaging/dingtalk.mdx | 17 +++++++-- .../integration/instant-messaging/lark.mdx | 10 ++++++ .../integration/instant-messaging/slack.mdx | 8 +++-- 28 files changed, 234 insertions(+), 43 deletions(-) diff --git a/en/on-call/channel/create-edit.mdx b/en/on-call/channel/create-edit.mdx index be7bc547..9b8ed0d3 100644 --- a/en/on-call/channel/create-edit.mdx +++ b/en/on-call/channel/create-edit.mdx @@ -86,7 +86,7 @@ The wizard pre-selects a grouping method for your subscription and marks that ca | :--- | :--- | | **Grouping fields** (rule-based grouping only) | `labels.check` by default; you can multi-select `labels.check`, `labels.service`, `labels.resource` and the alert title | | **Grouping time** | **Until the incident closes** (default) or **Fixed 60 minutes** | -| **Advanced settings → Strict grouping** (rule-based grouping only) | When on, an empty label counts as a distinct value; off by default | +| **Advanced settings → Strict grouping** (rule-based grouping only) | When on, an empty comparison field makes the alerts count as different, so they are not grouped; when off (default), a field that is empty on both sides counts as the same, but at least one comparison field must have a value, and alerts whose comparison fields are all empty are not grouped | | **Advanced settings → Fields used for the similarity judgement** (intelligent grouping only) | Fields used by the similarity judgement; `title`, `description`, `labels.service`, `labels.resource` by default | | **Advanced settings → Alert storm warning** | When on, reaching the merged-alert threshold (100 by default) records an alert storm event and notifies you; off by default | @@ -164,6 +164,7 @@ Drop rules differ from [silence rules](/en/on-call/channel/noise-reduction#silen | **Channel name** | Sort alphabetically by name | - Select **Sort** in the upper-right corner, then drag channel cards to change the display order. The new order applies to all users +- The pager at the bottom right of the list switches the page size (12 / 24 / 48 / 96, default 24). You can also type a custom size, up to 100 ### Changing configuration diff --git a/en/on-call/channel/integrate-data.mdx b/en/on-call/channel/integrate-data.mdx index d13d6202..f4a0bc86 100644 --- a/en/on-call/channel/integrate-data.mdx +++ b/en/on-call/channel/integrate-data.mdx @@ -69,7 +69,12 @@ A shared integration needs at least one routing rule, or Flashduty drops its ale ## Browsing and finding integrations -The Integration Center groups alert sources and change events by category. Narrow the list with a category chip, or search for the system you need. Click **All** to open the full catalog. +The Integration Center groups alert sources and change events by category. Browse the categories, or search for the system you need. + +- The add-integration panel renders one collapsible section per category. Only the tab's default category starts expanded (**Popular** on Alert Events, **CI/CD & deploy** on Change Events); click a title to expand the others. +- Search matches integration names and types across every category: each category with hits stays on screen with its matching entries, the section header shows hits out of that category's total (for example, `3 / 12`), and the matching part of a name is highlighted. Search skips **Popular**, whose entries already live in their real categories. +- When nothing matches, the panel shows **No results for "…"**. The Alert Events tab also offers **Standard alert event** (connects any system through a Webhook), and every tab can use **Request an integration** (SaaS only). The search term is carried into the form as the system name. +- **View all**, next to the search box, opens the full catalog: category navigation on the left, systems grouped by category on the right with each header showing the entry count. Hovering a card reveals a **+** in its top-right corner; clicking the card opens that integration's new-integration page. Searching inside the catalog also groups hits by category with hits out of total; with no match it shows only the empty state, since the fallback area at the bottom already offers the buttons. If the system you need is not listed, connect it with a generic integration, or click **Submit a request** at the bottom of the catalog. **Submit a request** is available on Flashduty SaaS only; private deployments do not show it. Field limits: system name 100, website or docs link 500 (must start with `http://` or `https://`), notes 2000, work email 200 characters; the work email is not needed when your account already has an email. diff --git a/en/on-call/channel/noise-reduction.mdx b/en/on-call/channel/noise-reduction.mdx index b87b9e58..fb033b14 100644 --- a/en/on-call/channel/noise-reduction.mdx +++ b/en/on-call/channel/noise-reduction.mdx @@ -60,6 +60,37 @@ When a monitoring system pushes alerts to Flashduty On-call, the system automati ![Alert Noise Reduction Flowchart](https://download.flashcat.cloud/flashduty/doc/en/fd/aggr-3.png) </Frame> +## Let AI configure noise reduction for you + +The header of the **Alert grouping** and **Flapping detection** pages carries a **Let AI tune noise reduction** button on the right. It opens [AI SRE](/en/ai-sre) in the side panel, takes this channel along as a context reference, and prefills a request for the page you are on: + +| Entry | Prefilled request (with channel "prod" as an example) | +| :--- | :--- | +| **Alert grouping** | `/channel-noise Analyze the alert noise in Channel "prod", then recommend and configure alert grouping` | +| **Flapping detection** | `/channel-noise Analyze the alerts that keep re-firing in Channel "prod", then recommend and configure flapping detection` | + +`/channel-noise` is the matching built-in [Skill](/en/ai-sre/skills), reachable only from this entry, and it tunes one channel per session. You can send the prefilled request as it is, or rewrite it first, for example to narrow the look-back window or to name the grouping dimensions you must keep. After that you keep talking in plain language to refine what you asked for. + +<Note> + **Prerequisite**: AI SRE is enabled for the account and you have permission to use AI SRE conversations. The button is hidden when either is missing. +</Note> + +The agent then works through these steps: + +<Steps> + <Step title="Read the channel's alert history"> + It pulls this channel's recent alerts, over an adjustable look-back window of up to 30 days. From them it counts the titles that fire most, bursts where one title fires many times in a short span (and the labels that vary inside a burst), alerts that keep re-firing, and each label's coverage and number of distinct values. Nothing is written in this step. + </Step> + <Step title="Recommend settings"> + It recommends a grouping method and dimensions, or a flapping observation window, state change threshold and mute duration, and says what the numbers are based on. On the Alert grouping page it also replays candidate dimensions through the page's own grouping preview, so it can give you an expected incident count and reduction instead of general advice. + </Step> + <Step title="Write only after you confirm"> + Nothing is written straight away. The agent can fill the recommended values into the form for you to review and save, or, when you choose to save directly, call the page's own save. In that case a confirmation card lists every setting it will change with its before and after value (for example, "Dimensions: `labels.check` → `labels.check` + `labels.service`"), and only your confirmation writes it. The change takes effect immediately and the page refreshes itself. + </Step> +</Steps> + +`/channel-noise` changes **Alert grouping** and **Flapping detection** only. For **Event aggregation**, silence rules, inhibit rules and drop rules it recommends what to change and names the page to change it on, but never writes. For how a reference tag travels with a message and how sessions are managed, see [Console chat](/en/ai-sre/sessions#attachments-and-context-references). + ## Event aggregation Go to Channel Details → **Noise Reduction** → **Event Aggregation** to configure. @@ -117,7 +148,7 @@ The Alert Grouping page offers three mutually exclusive methods. A choice takes In the create wizard, methods your subscription doesn't include are greyed out, with the tooltip "Your current subscription does not support this grouping method". The API field `group_method` carries the same choice: `i` (intelligent grouping), `p` (rule-based grouping), `n` (no grouping); see [Incident webhook](/en/on-call/integration/webhooks/incident-webhook). -Switching methods opens a confirmation dialog first; nothing takes effect until you click **Save**. +Clicking another method card shows that method's settings right below, with no confirmation dialog, and any draft you filled in before switching is kept. Nothing takes effect until you click **Save**. ### Common configuration @@ -127,7 +158,7 @@ Switching methods opens a confirmation dialog first; nothing takes effect until | **Window Timing Start** | Only configurable when the aggregation window is enabled. **Incident trigger** (default): Fixed timer starts from incident creation, stops grouping when the window duration is reached. **Alert merges into incident**: Timer resets each time a new alert merges in, the window recalculates from the last merge | | **Window Duration** | Only configurable when the aggregation window is enabled. Set the duration of the aggregation window, minimum 1 minute. Rule-based grouping and intelligent grouping share the same cap: 24 hours by default, extendable to 30 days on request (contact the Flashduty team to enable) | | **Alert Storm Warning** | When merged alert count reaches a configured threshold, the system records an alert storm event in the incident timeline and triggers a warning notification, prompting urgent handling. You can configure up to 5 thresholds, each ranging from 2 to 10,000 | -| **Strict Grouping** | When enabled, empty label values are treated as different; when disabled, empty values are treated as the same (not supported for intelligent grouping) | +| **Strict Grouping** | When enabled, a missing comparison field makes the alerts count as different, so they are not grouped; when disabled, a field that is empty on both sides counts as the same, but at least one comparison field must have a value, and alerts whose comparison fields are all empty are not grouped (not supported for intelligent grouping) | <Tabs> <Tab title="Intelligent Grouping"> diff --git a/en/on-call/comparison/vs-opsgenie.mdx b/en/on-call/comparison/vs-opsgenie.mdx index 93458454..30973cad 100644 --- a/en/on-call/comparison/vs-opsgenie.mdx +++ b/en/on-call/comparison/vs-opsgenie.mdx @@ -124,7 +124,7 @@ Response solves "closing the loop quickly once the right person is found": a sin | --- | --- | --- | | **AI Summaries & Post-Mortems** | Built-in AI incident summaries and one-click AI post-mortems | No equivalent | | **Autonomous Troubleshooting Agent** | [AI SRE](/en/ai-sre): a fully capable autonomous Agent loop connected to your real environment — cloud sandbox + self-hosted Runner executing diagnostic commands dynamically, extensible without limit through Skills, MCP, Subagents, and A2A; with an enabled Monitors data source, it can **query data sources directly through the alerting engine**, no Runner needed | No equivalent | -| **Native IM Troubleshooting** | [Group-chat @-mentions and private-chat troubleshooting](/en/ai-sre/im) across Feishu/Lark, DingTalk, WeCom, and Slack, with automatic initial diagnosis driven by a matching automation rule once a war room is created | No equivalent | +| **Native IM Troubleshooting** | [Group-chat @-mentions and private-chat troubleshooting](/en/ai-sre/im) across Feishu/Lark, DingTalk, WeCom, and Slack, with automatic initial diagnosis driven by a matching automation rule once a war room is created; an automation rule can also be bound to an IM chat at creation, run in that chat, and reply there | No equivalent | | **Billing** | Usage-based credits billing (1 credit = ¥1); activation is free, with gift credits each billing period | — | ### Platform & integrations diff --git a/en/on-call/comparison/vs-pagerduty.mdx b/en/on-call/comparison/vs-pagerduty.mdx index 74b1adb0..d38a4824 100644 --- a/en/on-call/comparison/vs-pagerduty.mdx +++ b/en/on-call/comparison/vs-pagerduty.mdx @@ -126,7 +126,7 @@ Flashduty has built-in AI summaries and AI post-mortems, plus [AI SRE](/en/ai-sr | --- | --- | --- | | **Product Form** | Autonomous SRE Agent: conversational troubleshooting + autonomous planning and execution + knowledge accumulation | AIOps for incident noise reduction/correlation; Advance as a generative AI assistant (summaries, Q&A, post-mortem drafts); four preset AI Agents each own a slice: SRE (diagnosis + pre-configured remediation), Scribe (meeting notes), Shift (scheduling), Insights (data Q&A) | | **Troubleshooting & Remediation** | Cloud sandbox + self-hosted [Runner (BYOC)](/en/ai-sre/environments), dynamically executing diagnostic commands and querying monitoring data and logs within your environment—**able to investigate problems it has never seen before**; with an enabled Monitors data source, it can **query data sources directly through the alerting engine**, no Runner needed | SRE Agent can automatically analyze logs/metrics and match them against historical incidents; remediation actions depend on **pre-configured** Automation Actions scripts | -| **Native IM Collaboration** | [Group-chat @-mentions and private-chat troubleshooting](/en/ai-sre/im) across Feishu/Lark, Dingtalk, WeCom, and Slack, with **automatic initial diagnosis driven by a matching automation rule once a war room is created** | Primarily Slack and Teams, no China-region IM support | +| **Native IM Collaboration** | [Group-chat @-mentions and private-chat troubleshooting](/en/ai-sre/im) across Feishu/Lark, Dingtalk, WeCom, and Slack, with **automatic initial diagnosis driven by a matching automation rule once a war room is created**; an automation rule can also be bound to an IM chat at creation, run in that chat, and reply there | Primarily Slack and Teams, no China-region IM support | | **Code Repositories & K8s** | [GitHub/GitLab App](/en/ai-sre/apps) accesses code repositories from within the sandbox and can submit PRs/MRs/Issues; a Kubernetes App connects to clusters at the namespace level | — | | **AI Automation Tasks** | [Automations](/en/ai-sre/automations) trigger on a cron schedule, by HTTP API, on incident events, or when a war room is created, with built-in templates for alert noise analysis, incident post-mortems, on-call insights, and more; on-call incident triggers support **similar-incident merge analysis** | Relies on the separate Event Orchestration and Runbook Automation product lines | | **Extensibility** | [Skills marketplace](/en/ai-sre/skills), [MCP external tools](/en/ai-sre/mcp), [Subagent and A2A delegation](/en/ai-sre/agents), **with no ceiling on the extension surface** | SRE Agent is limited to toggling official preset connectors (for example, Datadog, Splunk, CloudWatch) and appending prompt-style Skills; it doesn't support mounting arbitrary MCP tools to its own agents, has no subagent spawning, and cross-vendor agent collaboration is still in early access | diff --git a/en/on-call/configuration/filter-conditions.mdx b/en/on-call/configuration/filter-conditions.mdx index 0c9a6735..bc515924 100644 --- a/en/on-call/configuration/filter-conditions.mdx +++ b/en/on-call/configuration/filter-conditions.mdx @@ -77,6 +77,8 @@ Target values are always strings; the format decides the matching method: **rege - `*` matches zero or more characters - `?` matches a single character + Every other character matches **literally** and is never treated as a regular expression: the `[` and `]` in `host[0-9]*`, the `(`, `)` and `|` in `(a|b)*`, and the `.` in `host.*` are ordinary characters, so `host[0-9]*` only matches values that start with the literal text `host[0-9]`. To use a character class or a group, write a regular expression instead, for example `/^host[0-9]+.*$/`. + **Example**: - `labels.check`: `outage*` — matches when check label starts with "outage" diff --git a/en/on-call/configuration/service-calendar.mdx b/en/on-call/configuration/service-calendar.mdx index 747ef785..4b78c50e 100644 --- a/en/on-call/configuration/service-calendar.mdx +++ b/en/on-call/configuration/service-calendar.mdx @@ -22,7 +22,7 @@ description: Service calendars define workdays and rest days, working with escal ## Creating a calendar -Go to **Configuration → Service Calendar** and click **Add Calendar**. +Go to **Configuration → Service Calendar** and click **Create**, then fill in the form in the **Create Service calendar** panel on the right. | Configuration | Description | | --- | --- | @@ -45,8 +45,8 @@ New calendars default to all workdays. After creation, open the calendar detail | Action | Description | | --- | --- | | **Modify Basic Info** | Calendar name, description, management team | -| **Link Holidays** | On the calendar detail page, link national holiday calendars. The system automatically marks statutory holidays as rest days and make-up workdays as workdays; you can adjust or unlink them at any time | -| **Bulk Mark Rest Days** | Quickly mark by day of week, for example, every Saturday and Sunday as rest days | +| **Link Holidays** | On the calendar detail page, link national holiday calendars. The system automatically marks statutory holidays as rest days and make-up workdays as workdays; you can adjust or unlink them at any time. The dropdown lists only the holiday calendars of the current interface language (an already-linked calendar of another language stays in the list so you can unlink it), and several can be linked at once; selecting or clearing an option saves and takes effect immediately, with no separate save step | +| **Bulk Mark Rest Days** | Quickly mark by day of week, for example, every Saturday and Sunday as rest days. A week must keep at least one workday: once only one workday is left, its toggle can no longer be switched to a rest day. With no rest day set, all seven days count as workdays | | **Adjust Dates** | Click a date, or click two dates to select the days between them, then click **Set as workday**, **Set as day off**, or **Reset to default** in the action bar below. The note is optional | ![Edit Calendar](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/doc/rili-1.png) @@ -63,9 +63,11 @@ The first item in this order that has a setting for the day decides it: 2. **Linked holiday calendars**: a make-up workday wins over holiday rest days 3. **Weekly rest days**: rest days marked by day of week +Within one calendar, a day keeps only the last manual setting. Setting dates again (as a workday or a day off) that are already covered by an existing setting overwrites it: an existing setting entirely inside the selected range is deleted, one that only partly overlaps is shortened, and one spanning the whole range is split in two. + A day with none of these settings is a workday. Clicking **Reset to default** on a day clears its manual setting, and the day goes back to the holiday calendars and weekly rest days. -On the calendar, yellow marks a day off and green marks a workday set manually or by a holiday make-up day. Uncolored days follow the weekly settings and are workdays. +On the calendar, yellow marks a day off and green marks a workday set manually or by a holiday make-up day. Uncolored days follow the weekly settings and are workdays. Days set manually on this calendar additionally carry a ring around them, telling them apart from days decided by a holiday calendar or by the weekly rule. Hover over a day to see which layer decided it and which settings it overrides (listed with a strikethrough). ## FAQ diff --git a/en/on-call/incident/search-view-incident.mdx b/en/on-call/incident/search-view-incident.mdx index 0c7a96a3..ccbb5d44 100644 --- a/en/on-call/incident/search-view-incident.mdx +++ b/en/on-call/incident/search-view-incident.mdx @@ -245,6 +245,8 @@ The limits above apply to the **Manage comment types** dialog in the console. In The timeline records every operation on [action items and follow-ups](/en/on-call/incident/work-items) with an icon, alongside comments, acknowledgments, and other events. These operations are create, update, change assignees, complete, delete, convert an action to a follow-up, and link a follow-up to the post-mortem. When the incident closes, one record summarizes the unfinished actions that Flashduty converted. +When a create or assignee-change record carries assignees, the sentence continues with "assigned to …". Members alone appear one by one as avatar plus name. If AI SRE is among the assignees, the record uses a joint signature: member names joined by ", ", ending with "and AI SRE" (for example, "John, Jane and AI SRE"). + ### AI SRE action records AI SRE sometimes acts on behalf of a member, for example when an [automation rule](/en/ai-sre/automations) writes its conclusion back to the incident. The timeline signs these actions **`{{name}} and AI SRE`**, because AI SRE uses that member's identity and permissions. diff --git a/en/on-call/incident/work-items.mdx b/en/on-call/incident/work-items.mdx index 3de4649c..20c74611 100644 --- a/en/on-call/incident/work-items.mdx +++ b/en/on-call/incident/work-items.mdx @@ -33,10 +33,22 @@ In the **Actions** card on the incident overview page, click **Add an action** ( | :--- | :---: | :--- | | **Title** | Yes | A brief description of the work to be done, up to **512** characters | | **Description** | No | Additional details about what needs to be done, up to **65535** characters | -| **Assignees** | No | Search and multi-select from account members; no limit on the number | +| **Assignees** | No | Search and multi-select from account members; no limit on the number. You can also pick the **AI SRE** option pinned at the top of the list (sub-label **Assign to AI**) to hand the item to the account's AI SRE | Once created, the action item appears in the card and the incident timeline records an "action created" event. Members assigned as assignees receive a personal notification prompting them to follow through (sent through **email and in-app push** by default; you can adjust notification channels in [Personal Settings](/en/on-call/configuration/personal-settings)). +### Assigning to AI SRE + +The assignee picker pins **AI SRE** above the member list, separated from it by a divider. Search never filters it out, so it stays in the results whatever you type. Selecting it hands the item to the account's AI SRE, and you can keep member assignees alongside it. Action items and follow-ups share the same create/edit dialog, so the field behaves the same for both. + +- The card shows the assignment as an **AI SRE** avatar next to the member avatars (up to 2 avatars, with the rest collapsed into `+N`) +- Hovering the AI SRE avatar opens a hover card that names the member whose identity and permissions the AI SRE runs with, and offers **Continue conversation**, which opens the session behind this run in the AI SRE panel +- When the run came from an IM session, the hover card only says **IM sessions can't be viewed on the web yet** and offers no entry point +- Opening the session requires AI SRE to be enabled for the account and AI SRE chat permission for you; personal sessions (visible only to their creator) and expired sessions can't be continued +- On the incident timeline, this work item's record lists the assignees with a joint signature (for example, "John and AI SRE") + +To list everything handed to AI SRE, use `flashduty incident work-item-list --assignee-type ai_sre` in the [CLI](/en/developer/cli). + ### Edit and delete - Members with incident update permission can click the item title, or use **Edit** in the **More** menu, to change the title, description, or assignees @@ -79,6 +91,8 @@ Access to action items and follow-ups follows these rules: Access to action items also follows the incident's **collaboration space**. Only account owners, account admins, and members with access to that space can work on them. Manual incidents without a collaboration space are visible to all account members. This matches the access rules of the incident itself. +**Assignees** in the table above means account members. A work item assigned to **AI SRE** is executed by the AI: AI SRE is not an account member, so the member-facing completion permission and personal notification above don't apply to it (when the same item also has member assignees, those members are notified as usual). + ## Closed incidents Once an incident is closed, the Actions card becomes read-only while the Follow-ups card unlocks for editing: diff --git a/en/on-call/integration/alert-integration/alert-sources/aliyun-dataworks-op.mdx b/en/on-call/integration/alert-integration/alert-sources/aliyun-dataworks-op.mdx index 3bef8c3e..4ddfb839 100644 --- a/en/on-call/integration/alert-integration/alert-sources/aliyun-dataworks-op.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/aliyun-dataworks-op.mdx @@ -125,19 +125,21 @@ Key fields from the push message are preserved as labels on the alert event and | Label | Source field | Description | | ----- | ------------ | ----------- | -| alert_type | title | Alert family (DataWorks_Remind) | +| alert_type | message.title | Alert family: DataWorks_Remind, DataWorks_Baseline_Alert, or DataWorks_Event_Remind | | remind_name | remind_name | Rule name | -| remind_unit | remind_unit | Monitoring granularity (Task, ScheduleResourceGroup) | +| remind_unit | remind_unit | Monitoring granularity (Task, Baseline, Project, BizProcess, ScheduleResourceGroup, DiResourceGroup) | | remind_type | remind_type | Raw trigger condition | -| occur_time | occur_time | Raw occurrence time string | +| occur_time | occur_time | Raw occurrence time string (2021-07-13 16:16:20); set for all three alert families | | remind_founder | remind_founder | Rule creator | | more_information | more_information | Operation Center instance URL | -| task_size / number_of_alerts | same-name fields | Task count / nth alert notification | -| node_id_list / node_name_list / node_owner_list | same-name fields | Node IDs / names / owners (comma-separated, up to 5) | -| resource_group_name / threshold / duration | same-name fields | Resource group name / threshold / duration (minutes), resource group monitoring only | +| task_size / number_of_alerts | same-name fields | Task count / nth alert notification; generated only when greater than 0 | +| node_id_list / node_name_list / node_owner_list | same-name fields | Node IDs / names / owners (comma-separated, up to 5); non-resource-group monitoring only | +| resource_group_name / threshold / duration | same-name fields | Resource group name / threshold / duration (minutes); resource group monitoring only | | baseline_name / baseline_owners | same-name fields | Baseline name / baseline owners | -| cycle_number / key_instance / sla_time / buffer / status | same-name fields | Cycle number / key instance / SLA time / buffer (minutes) / baseline status | -| task_name / task_owner_name / event_type / event_name | same-name fields | Task name / owner / event type / event name | +| cycle_number / key_instance / sla_time / buffer / status | same-name fields | Cycle number (1 for a daily baseline) / key instance / SLA time / buffer (minutes) / baseline status (dangerous or overSla) | +| task_name / task_owner_name / event_type / event_name | same-name fields | Task name / owner / event type (ERROR or SLOW) / event name | + +Empty-valued fields do not produce labels. The alert title comes from the family's name field: `remind_name` for custom alerts, `baseline_name` for baseline alerts, and `task_name` for event alerts. </div> diff --git a/en/on-call/integration/alert-integration/routing-rules.mdx b/en/on-call/integration/alert-integration/routing-rules.mdx index a2bca34d..81365612 100644 --- a/en/on-call/integration/alert-integration/routing-rules.mdx +++ b/en/on-call/integration/alert-integration/routing-rules.mdx @@ -24,7 +24,7 @@ Go to Integration Center → Alert Events → Integration Details → **Routing* | Method | Example | Recognition rule | | :------- | :----------------------- | :-------------------------------- | | **Exact** | `cpu.idle<10%` | When nothing else matches, values must be identical | -| **Wildcard** | `host * down` | A value containing `*` or `?` and no `/` prefix/suffix is treated as a wildcard | +| **Wildcard** | `host * down` | A value containing `*` or `?` and no `/` prefix/suffix is treated as a wildcard (other characters match literally; use `/.../` for a regular expression) | | **Regex** | `/api-server-\d+/` | A value wrapped in `/` is treated as an RE2 regex | | **CIDR** | `cidr:192.168.1.0/24` | A value prefixed with `cidr:` matches by IP range | | **Numeric** | `num:gt:0.95` | A value prefixed with `num:` plus a comparison operator (`gt`/`ge`/`lt`/`le`) is compared numerically | diff --git a/en/on-call/integration/instant-messaging/dingtalk.mdx b/en/on-call/integration/instant-messaging/dingtalk.mdx index 4439f5db..b5536b35 100644 --- a/en/on-call/integration/instant-messaging/dingtalk.mdx +++ b/en/on-call/integration/instant-messaging/dingtalk.mdx @@ -56,13 +56,13 @@ After either option, follow the 6 steps in the next section, "Finish setup in Di ### 1. Grant permissions -Go to Development Configuration → **Permission Management** and request the permissions in the table below. Basic notifications need only the Basic group; War Room adds the second group (`qyapi_get_member_by_mobile` is also used for one-click user linking); a Dingtalk AI streaming card template adds the third. The integration detail page shows which basic permissions are missing and links straight to each one. +Go to Development Configuration → **Permission Management** and request the permissions in the table below. Basic notifications need only the Basic group; War Room adds the second group (`qyapi_get_member_by_mobile` is also used for automatic member linking and one-click user linking); a Dingtalk AI streaming card template adds the third. The integration detail page shows which basic permissions are missing and links straight to each one. | Group | Official permission name | Purpose | | :--- | :--- | :--- | | Basic (required) | `qyapi_robot_sendmsg` | Send bot messages for basic notifications, session-webhook bot replies, standard interactive cards, War Room messages, and downloading files received by the bot | | Basic (required) | `qyapi_chat_manage` | Get group chat information for standard notifications, Cool Apps, and bot message delivery | -| Basic (required) | `qyapi_get_member_by_mobile` | Get Dingtalk user IDs by phone number for one-click user linking and inviting members to War Rooms | +| Basic (required) | `qyapi_get_member_by_mobile` | Get Dingtalk user IDs by phone number for automatic member linking, one-click user linking, and inviting members to War Rooms | | When War Room is enabled | `qyapi_chat_read` | Read group chat information for War Room group status checks and member handling | | When War Room is enabled | `qyapi_chat_base_read` | Read basic group chat information for War Room group queries | | When using AI streaming cards | `Card.Instance.Write` | Create and deliver AI SRE streaming cards; required only when a Dingtalk AI streaming card template is enabled | @@ -217,11 +217,24 @@ In the **Linked Users** tab of the integration detail page, filter members by ** Members receive Dingtalk notifications only after they are linked. If linking fails, verify that the member's phone number matches their Dingtalk account. +### Automatic linking + +Members do not need to do anything: the system links them automatically, once right after you save the integration and then once an hour across every enabled Dingtalk integration. + +Automatic linking resolves each member's verified phone number in the personal center to a Dingtalk account ID (Dingtalk has no lookup by email), equivalent to the member logging into Flashduty with the same phone number on Dingtalk. Two limits delay retries: + +- A member Dingtalk answered for but no binding was created (the phone number is unknown on the Dingtalk side, or that Dingtalk account is already linked to another member) is not looked up again for 7 days; changing the member's phone number triggers a new attempt +- When the Dingtalk app lacks the `qyapi_get_member_by_mobile` permission (error code 60011) or the server IP is outside the app's whitelist (error code 60020), automatic linking pauses for that integration for 24 hours; fix the permission or whitelist and save the integration again to resume + +**One-Click Link** ignores the 7-day window above and looks everyone up again right away; if it reports **No new members linked**, this run produced no new binding (for example the phone number is unknown on the Dingtalk side, or the matching Dingtalk account is already linked to another member). + ## FAQ <AccordionGroup> <Accordion title="Messages cannot be delivered to individuals, operation log shows 'App not linked'?"> Go to Dingtalk → Workspace → Search app name → **Open App**, and sign in once to link your Dingtalk and Flashduty accounts. Flashduty needs this identity to deliver messages. + +If the member has already verified a phone number in the personal center, the system may have linked the account automatically, without any sign-in; check the current linking status in the **Linked Users** tab of the integration detail page. </Accordion> <Accordion title="Message card buttons not working or showing errors?"> diff --git a/en/on-call/integration/instant-messaging/lark.mdx b/en/on-call/integration/instant-messaging/lark.mdx index 8e6a7ad0..80416d8c 100644 --- a/en/on-call/integration/instant-messaging/lark.mdx +++ b/en/on-call/integration/instant-messaging/lark.mdx @@ -136,11 +136,21 @@ In the **Linked Users** tab of the integration detail page, filter members by ** Members receive Feishu/Lark notifications only after they are linked. If linking fails, verify that the member's phone number or email matches their Feishu/Lark account. +### Automatic linking + +Members do not need to do anything: the system links them automatically, once right after you save the integration and then once an hour across every enabled Feishu/Lark integration. + +Automatic linking resolves each member's verified phone number or email in the personal center in batches of 50 to obtain Feishu/Lark account IDs. Feishu returns an empty `user_id` both for accounts it cannot find and for users outside the app's **visibility scope**, so both count as not found. If the Feishu/Lark app lacks contact permissions (error codes 99991672 / 99991679) or Feishu rejects its credentials, automatic linking pauses for that integration for 24 hours; grant the permissions and save the integration again to resume. + +A member whose Feishu/Lark account was not found is not looked up again for 7 days; changing the member's contact information triggers a new attempt. **One-Click Link** ignores the 7-day window and looks everyone up again right away; if it reports **No new members linked**, this run produced no new binding. + ## FAQ <AccordionGroup> <Accordion title="Messages cannot be delivered to individuals, operation log shows 'App not linked'?"> Go to Feishu/Lark → Workspace → Search app name → **Open App**, and sign in once to link your Feishu/Lark and Flashduty accounts. Flashduty needs this identity to deliver messages. + +If the member has already verified a phone number or email in the personal center, the system may have linked the account automatically, without any sign-in; check the current linking status in the **Linked Users** tab of the integration detail page. </Accordion> <Accordion title="Message card buttons not working or showing errors?"> diff --git a/en/on-call/integration/instant-messaging/slack.mdx b/en/on-call/integration/instant-messaging/slack.mdx index 8a5d57cf..b36131b6 100644 --- a/en/on-call/integration/instant-messaging/slack.mdx +++ b/en/on-call/integration/instant-messaging/slack.mdx @@ -33,11 +33,13 @@ After completing the previous steps, in the Flashduty On-call integration config Configure the AI SRE switches under **Enhanced Features**. They are enabled by default; see [IM platform](/en/ai-sre/im) for what each one does. In Slack, **Allow AI SRE conversations in IM** also controls the `/fd` command. -## Linked users +## Member linking -In the **Linked Users** tab of the integration detail page, filter members by **All / Linked / Unlinked**, or search by name or email. Click **One-Click Link** to match members to Slack accounts by their phone number or email and link them automatically, the same result as a member logging into Flashduty from Slack. +The Slack integration has no member-linking page: the integration detail page shows only the configuration page, with no **Linked Users** tab and no **One-Click Link** button, and Flashduty does not exchange member phone numbers or emails for Slack account IDs to link them in bulk. -Members receive Slack notifications only after they are linked. If linking fails, verify that the member's email matches their Slack account. +Slack identifies members by **email**: when a member acts on an alert card in Slack, Flashduty reads that Slack account's email and matches it against the member emails of the account, treating a match as that member. So there is nothing to link member by member, but the member's Slack email and Flashduty member email must match. When they do not, the system replies in Slack with a note that no member matched. + +Slack is connected per **workspace**: once the OAuth authorization in [Install app](#install-app) completes, channel notifications, @mentioning AI SRE in a group chat, and War Rooms are available in that workspace. <span id="aisre-permissions"></span> <span id="war-room-scope"></span> diff --git a/zh/on-call/channel/create-edit.mdx b/zh/on-call/channel/create-edit.mdx index b64cf739..462a41d1 100644 --- a/zh/on-call/channel/create-edit.mdx +++ b/zh/on-call/channel/create-edit.mdx @@ -87,7 +87,7 @@ keywords: ["协作空间", "创建管理", "业务隔离", "团队协作", "告 | :--- | :--- | | **聚合字段**（仅规则聚合） | 默认 `labels.check`，可多选 `labels.check`、`labels.service`、`labels.resource`、告警标题 | | **聚合时间** | **持续到故障关闭**（默认）或 **固定 60 分钟** | -| **高级配置 → 严格聚合**（仅规则聚合） | 开启后空值标签视为不同项；默认关闭 | +| **高级配置 → 严格聚合**（仅规则聚合） | 开启后任一比较字段为空即视为不同、不聚合；关闭（默认）时两边都为空的字段视为相同，但至少要有一个字段有值，所有比较字段都为空时不聚合 | | **高级配置 → 参与判断的信息**（仅智能聚合） | 参与相似度判断的字段；默认 `title`、`description`、`labels.service`、`labels.resource` | | **高级配置 → 风暴提醒** | 开启后合入告警数达到阈值（默认 100）时记录告警风暴事件并通知；默认关闭 | @@ -165,6 +165,7 @@ keywords: ["协作空间", "创建管理", "业务隔离", "团队协作", "告 | **空间名称** | 按名称字典序排序 | - 使用右上角 **排序** 功能进入排序模式，通过拖拽协作空间卡片调整显示顺序，排序结果对所有用户生效 +- 列表右下角的分页器可切换每页显示条数（12 / 24 / 48 / 96，默认 24），也可输入自定义条数，上限 100 条 ### 变更配置 diff --git a/zh/on-call/channel/integrate-data.mdx b/zh/on-call/channel/integrate-data.mdx index 720133ca..6d6d0e7c 100644 --- a/zh/on-call/channel/integrate-data.mdx +++ b/zh/on-call/channel/integrate-data.mdx @@ -70,7 +70,12 @@ Flashduty On-call 提供两种告警接入方式： ## 浏览与查找集成 -集成中心按分类组织告警源与变更事件，您可以用分类胶囊缩小范围，也可以直接搜索目标系统。点击 **全部** 可打开完整的集成目录。 +集成中心按分类组织告警源与变更事件，您可以逐个分类浏览，也可以直接搜索目标系统。 + +- 添加集成面板为每个分类渲染一个可折叠区块，只有当前页签的默认分类默认展开（告警事件页签为 **热门**，变更事件页签为 **CI/CD 与部署**），其余点标题展开。 +- 搜索框跨全部分类匹配集成名称或类型：命中的分类连同命中条目一起展示，分类标题右侧显示「命中数 / 该分类总数」（例如 `3 / 12`），名称中与搜索词相同的部分高亮。搜索不涉及 **热门**，其中的集成本来就归在各自的分类里。 +- 没有任何命中时显示 **没有找到「搜索词」**：告警事件页签额外给出 **标准告警事件** 入口（通过 Webhook 接入任意系统），所有页签都可以点 **提交集成需求**（仅 SaaS 环境），搜索词会带入表单的系统名称。 +- 点击搜索框旁的 **查看全部** 打开完整的集成目录：左侧分类导航，右侧按分类列出系统，分类标题右侧是条目数；鼠标悬停卡片时右上角出现 **+**，点击卡片进入该集成的新建页。在目录里搜索同样按分类分组并显示「命中数 / 总数」；没有命中时只显示空状态，不再重复按钮，用底部的兜底区即可。 找不到要接入的系统时，可以用通用集成接入，或在目录底部点击 **提交需求**。**提交需求** 入口只在 Flashduty SaaS 环境提供，私有化部署不显示。表单字段上限：系统名称 100、官网或文档链接 500（需以 `http://` 或 `https://` 开头）、补充说明 2000、工作邮箱 200 个字符；账号已绑定邮箱时无需填写工作邮箱。 diff --git a/zh/on-call/channel/noise-reduction.mdx b/zh/on-call/channel/noise-reduction.mdx index 31fcb6d6..926e86b7 100644 --- a/zh/on-call/channel/noise-reduction.mdx +++ b/zh/on-call/channel/noise-reduction.mdx @@ -61,6 +61,37 @@ keywords: ["告警降噪", "告警聚合", "静默策略", "抑制策略", "噪 ![告警降噪流程图](https://docs-cdn.flashcat.cloud/images/png/6fec1c4fa6318119ab5c7f69f0c3cd55.png) </Frame> +## 让 AI 帮你配置降噪 + +**告警聚合** 与 **抖动检测** 的页头右侧各有一个 **让 AI 帮我配置降噪** 按钮。点击后会在右侧打开 [AI SRE](/zh/ai-sre) 面板，把该协作空间作为上下文引用带入会话，并按您所在的页面预填一条请求： + +| 入口 | 预填的请求（以协作空间「生产环境」为例） | +| :--- | :--- | +| **告警聚合** | `/channel-noise 帮我分析协作空间「生产环境」的告警噪音，推荐并配置告警聚合` | +| **抖动检测** | `/channel-noise 帮我分析协作空间「生产环境」里反复触发的告警，推荐并配置抖动检测` | + +`/channel-noise` 是对应的内置 [Skill](/zh/ai-sre/skills)，只从这个入口进入，一次只调一个协作空间。预填的请求可以直接发送，也可以在发送前改写，例如限定回看的时间范围，或说明必须保留哪些聚合维度；发送后仍可继续用自然语言追问或调整要求。 + +<Note> + **前提**：账户已启用 AI SRE，且您有使用 AI SRE 对话的权限。不满足任一条件时，该按钮不显示。 +</Note> + +之后 Agent 按以下步骤工作： + +<Steps> + <Step title="读取该空间的告警历史"> + 拉取该协作空间最近的告警，回看范围可以调整，最长 30 天。它据此统计高频告警标题、同一标题在短时间内集中触发的爆发及其内部发生变化的标签、反复触发的告警，以及各标签的覆盖率和取值数量。这一步只读。 + </Step> + <Step title="给出建议"> + 推荐聚合方式与聚合维度，或推荐抖动检测的观测窗口、状态变化次数与静默时长，并说明依据。在告警聚合页，它还会用页面自身的聚合预览试算候选维度，给出预计的故障数量与降噪幅度，而不是只给一般性建议。 + </Step> + <Step title="确认后写入"> + 改动不会直接落库。Agent 可以把推荐值填进表单，由您检查后点 **保存**；也可以在您选择直接保存时调用页面自身的保存动作，此时会先给出一张确认卡片，逐条列出变更项与变更前后的值（如「聚合维度：`labels.check` → `labels.check` + `labels.service`」），确认后才写入。保存后立即生效，页面自动刷新。 + </Step> +</Steps> + +`/channel-noise` 只修改 **告警聚合** 与 **抖动检测** 两项配置；**事件聚合**、静默策略、抑制策略和排除规则它只给建议并指出对应的配置页面，不写入。引用标签如何随消息发送、会话如何管理，见 [控制台对话](/zh/ai-sre/sessions#附件与上下文引用)。 + ## 事件聚合 进入 协作空间详情 → **降噪处理** → **事件聚合** 进行配置。 @@ -118,7 +149,7 @@ keywords: ["告警降噪", "告警聚合", "静默策略", "抑制策略", "噪 不可用的方式在创建向导里显示为置灰不可选，悬停提示「当前订阅暂不支持该聚合方式」。方式对应 API 字段 `group_method` 的枚举值：`i`（智能聚合）、`p`（规则聚合）、`n`（不聚合），详见 [故障 Webhook](/zh/on-call/integration/webhooks/incident-webhook)。 -切换聚合方式时会先弹出确认框，确认后仍需点击 **保存** 才生效。 +点击另一张方式卡片，页面下方直接显示该方式需要的配置项（不再弹出确认框），切换前已填写的草稿会保留；点击 **保存** 才生效。 ### 通用配置 @@ -128,7 +159,7 @@ keywords: ["告警降噪", "告警聚合", "静默策略", "抑制策略", "噪 | **窗口计时起点** | 仅在聚合窗口开启时可配置。**故障触发**（默认）：从故障创建时开始固定计时，到达窗口时长后停止聚合；**告警合入故障**：每次有新告警合入时重置计时，窗口从最后一次合入开始重新计算 | | **窗口时长** | 仅在聚合窗口开启时可配置。设置聚合窗口的持续时间，最小 1 分钟。规则聚合与智能聚合共享同一上限开关：默认最大 24 小时，开通后可扩展至 30 天（需联系 Flashduty 团队开启） | | **风暴预警** | 当合入告警数达到设定阈值时，系统在故障时间线中记录告警风暴事件并触发预警通知，提醒您加急处理。支持配置最多 5 个阈值，每个阈值范围为 2 - 10,000 | -| **严格聚合** | 开启时，空值标签视为不同项；关闭时，空值标签视为相同项（智能聚合不支持） | +| **严格聚合** | 开启时，任一参与比较的字段缺失即视为不同，不会聚合；关闭时，两边都为空的字段视为相同，但至少要有一个参与比较的字段有值，全部为空时不聚合（智能聚合不支持） | <Tabs> <Tab title="智能聚合"> diff --git a/zh/on-call/comparison/vs-opsgenie.mdx b/zh/on-call/comparison/vs-opsgenie.mdx index 19a1233b..af5da800 100644 --- a/zh/on-call/comparison/vs-opsgenie.mdx +++ b/zh/on-call/comparison/vs-opsgenie.mdx @@ -124,7 +124,7 @@ Response 解决「找到人之后怎么快速闭环」：一条时间线、一 | --- | --- | --- | | **AI 摘要与复盘** | 内置 AI 故障摘要、AI 一键生成复盘 | 无对等能力 | | **自治排障 Agent** | [AI SRE](/zh/ai-sre)：接入真实环境的自治 Agent loop，云端沙箱 + 自托管 Runner 动态执行诊断命令，可通过 Skills、MCP、Subagent 与 A2A 无上限扩展；账户有已启用的 Monitors 数据源时，可经告警引擎**直连数据源查询**，无需 Runner | 无对等能力 | -| **IM 原生排障** | 飞书/钉钉/企微/Slack [群聊 @ 召唤、私聊排障](/zh/ai-sre/im)，作战室创建后，由匹配的自动化规则自动发起初步诊断 | 无对等能力 | +| **IM 原生排障** | 飞书/钉钉/企微/Slack [群聊 @ 召唤、私聊排障](/zh/ai-sre/im)，作战室创建后，由匹配的自动化规则自动发起初步诊断；自动化规则还可以在创建时绑定到某个 IM 会话，在该群里执行并把结论回帖到该群 | 无对等能力 | | **计费** | 按 credits 用量计费（1 credit = ¥1），开通免费，每个计费周期赠送体验额度 | — | ### 平台与集成 diff --git a/zh/on-call/comparison/vs-pagerduty.mdx b/zh/on-call/comparison/vs-pagerduty.mdx index eaadeb4d..ff235fdd 100644 --- a/zh/on-call/comparison/vs-pagerduty.mdx +++ b/zh/on-call/comparison/vs-pagerduty.mdx @@ -118,7 +118,7 @@ Flashduty 内置 AI 摘要与 AI 复盘，并提供 [AI SRE](/zh/ai-sre)：接 | --- | --- | --- | | **产品形态** | 自治 SRE Agent：对话式排障 + 自主规划执行 + 知识沉淀 | AIOps 事件降噪/关联；Advance 生成式 AI 助手（摘要、问答、复盘草稿）；四个预置 AI Agent 各管一段：SRE（诊断+预配置修复）、Scribe（会议记录）、Shift（排班）、Insights（数据问答） | | **排障与修复方式** | 云端沙箱 + 自托管 [Runner（BYOC）](/zh/ai-sre/environments)，在您的环境中动态执行诊断命令、查询监控与日志，**可排查未预设过的问题**；账户有已启用的 Monitors 数据源时，可经告警引擎**直连数据源查询**，无需 Runner | SRE Agent 可自动分析日志/指标并匹配历史事件；修复动作依赖**预先配置**的 Automation Actions 脚本 | -| **IM 原生协同** | 飞书/钉钉/企业微信/Slack [群聊 @ 召唤、私聊排障](/zh/ai-sre/im)，**作战室创建后，由匹配的自动化规则自动发起初步诊断** | Slack、Teams 为主，无国内 IM | +| **IM 原生协同** | 飞书/钉钉/企业微信/Slack [群聊 @ 召唤、私聊排障](/zh/ai-sre/im)，**作战室创建后，由匹配的自动化规则自动发起初步诊断**；自动化规则还可以在创建时绑定到某个 IM 会话，在该群里执行并把结论回帖到该群 | Slack、Teams 为主，无国内 IM | | **代码仓库与 K8s** | [GitHub/GitLab App](/zh/ai-sre/apps) 沙箱内访问代码仓库、提交 PR/MR/Issue；Kubernetes App 按 namespace 接入集群 | — | | **AI 自动化任务** | [自动化](/zh/ai-sre/automations)按 cron、HTTP API、故障事件或作战室创建触发，内置告警噪音分析、事故复盘、值班洞察等模板；On-call 故障触发支持**相似故障合并分析** | 依赖 Event Orchestration 与 Runbook Automation 独立产品线 | | **可扩展性** | [Skills 市场](/zh/ai-sre/skills)、[MCP 外部工具](/zh/ai-sre/mcp)、[Subagent 与 A2A 委派](/zh/ai-sre/agents)，**扩展面不设上限** | SRE Agent 限于启停官方预置连接器（Datadog、Splunk、CloudWatch 等）与追加提示词式 Skill；不支持为自家 Agent 挂载任意 MCP 工具，无子 Agent 派生，跨厂商 Agent 协作尚在 early access | diff --git a/zh/on-call/configuration/filter-conditions.mdx b/zh/on-call/configuration/filter-conditions.mdx index fdba8369..5184770f 100644 --- a/zh/on-call/configuration/filter-conditions.mdx +++ b/zh/on-call/configuration/filter-conditions.mdx @@ -78,6 +78,8 @@ keywords: ["过滤条件", "条件匹配", "告警筛选", "规则配置", "标 - `*` 可匹配零个或多个任意字符 - `?` 可匹配单个任意字符 + 除 `*` 和 `?` 之外的字符都按**字面**匹配，不会被当作正则：`host[0-9]*` 里的 `[`、`]`，`(a|b)*` 里的 `(`、`)`、`|`，`host.*` 里的 `.` 都只是普通字符，`host[0-9]*` 只匹配以字面量 `host[0-9]` 开头的值。要用字符类或分组，请写成正则，例如 `/^host[0-9]+.*$/`。 + **示例**： - `labels.check`：`宕机*` — check 标签以"宕机"作为前缀，即匹配 diff --git a/zh/on-call/configuration/service-calendar.mdx b/zh/on-call/configuration/service-calendar.mdx index 012dd130..2bb5e0db 100644 --- a/zh/on-call/configuration/service-calendar.mdx +++ b/zh/on-call/configuration/service-calendar.mdx @@ -23,7 +23,7 @@ keywords: ["服务日历", "工作日", "休息日", "节假日", "差异化处 ## 创建日历 -进入 **配置中心 → 服务日历**，点击 **新增日历**。 +进入 **配置中心 → 服务日历**，点击 **创建**，在右侧面板 **创建服务日历** 中填写信息。 | 配置项 | 说明 | | --- | --- | @@ -46,8 +46,8 @@ keywords: ["服务日历", "工作日", "休息日", "节假日", "差异化处 | 操作 | 说明 | | --- | --- | | **修改基础信息** | 日历名称、描述、管理团队 | -| **关联节假日** | 在日历详情页关联国家节假日日历，系统自动将法定假日标记为休息日、调休补班日标记为工作日，可随时调整或取消关联 | -| **批量标记休息日** | 按星期几快速标记，如每周六、日为休息日 | +| **关联节假日** | 在日历详情页关联国家节假日日历，系统自动将法定假日标记为休息日、调休补班日标记为工作日，可随时调整或取消关联。下拉中只列出当前界面语言对应的节假日日历（已关联的其他日历会保留在列表中，便于取消关联），可同时关联多个；勾选或取消即保存生效，无需另行保存 | +| **批量标记休息日** | 按星期几快速标记，如每周六、日为休息日。一周至少保留一个工作日，只剩最后一个工作日时它的按钮不可再切换为休息日；未设置任何休息日时七天全部按工作日计 | | **调整日期** | 点击一个日期，或先后点击两个日期选中一段日期，在下方操作栏点击 **设为工作日**、**设为休息日** 或 **恢复默认**，备注选填 | ![编辑日历](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/doc/rili-1.png) @@ -64,9 +64,11 @@ keywords: ["服务日历", "工作日", "休息日", "节假日", "差异化处 2. **关联的节假日日历**：调休补班日优先于节假日休息日 3. **每周休息日**：按星期几批量标记的休息日 +同一个日历内，同一天只保留最后一条手动设置。在已有设置覆盖到的日期上再次点击 **设为工作日** 或 **设为休息日**，旧设置会被覆盖：完全落在本次选中范围内的旧设置被删除，部分重叠的被截短，跨越整个范围的被拆成两段。 + 以上都没有设置的日期为工作日。对日期点击 **恢复默认** 会清除手动设置，该日期回到节假日日历和每周休息日的判定。 -日历上黄色表示休息日，绿色表示手动设置或节假日补班的工作日，没有颜色的日期按每周设置为工作日。 +日历上黄色表示休息日，绿色表示手动设置或节假日补班的工作日，没有颜色的日期按每周设置为工作日。由本日历手动设置的日子还会额外描一圈边框，与节假日日历或每周规则决定的日子区分开；将鼠标悬停在某一天上，可以看到是哪一层决定了这一天，以及被它覆盖掉的设置（以删除线列出）。 ## 常见问题 diff --git a/zh/on-call/incident/search-view-incident.mdx b/zh/on-call/incident/search-view-incident.mdx index fe2ac0ec..05955870 100644 --- a/zh/on-call/incident/search-view-incident.mdx +++ b/zh/on-call/incident/search-view-incident.mdx @@ -246,6 +246,8 @@ AI 总结仅适用于由告警自动触发的故障，手动创建的故障不 [行动项与跟进项](/zh/on-call/incident/work-items)的每一次操作都会以带图标的记录写入时间线，与评论、认领等事件并列展示：创建、更新、更换负责人、完成、删除，行动项转为跟进项，跟进项关联到复盘。故障关闭时自动转换的未完成行动项会汇总为一条记录。 +创建和更换负责人的记录带有指派对象时，句子后接「，指派给 …」：只有成员时按「头像 + 名字」逐个列出；负责人中含 AI SRE 时改用联合署名，成员名以「、」相连，最后以「和 AI SRE」收尾（例如「张三、李四 和 AI SRE」）。 + ### AI SRE 代操作记录 AI SRE 代某位成员执行的动作（例如[自动化规则](/zh/ai-sre/automations)跑完一轮排查后把结论写回故障）会以 **`{{name}} 和 AI SRE`** 联合署名记入时间线，因为 AI SRE 使用的是该成员的身份和权限。 diff --git a/zh/on-call/incident/work-items.mdx b/zh/on-call/incident/work-items.mdx index 1abe926a..789e4ca7 100644 --- a/zh/on-call/incident/work-items.mdx +++ b/zh/on-call/incident/work-items.mdx @@ -33,10 +33,22 @@ keywords: ["行动项", "跟进项", "工作项", "故障处理", "故障复盘" | :--- | :---: | :--- | | **行动项标题** | 是 | 简要描述要完成的工作，最长 **512** 字符 | | **描述** | 否 | 补充需要执行的具体内容，最长 **65535** 字符 | -| **负责人** | 否 | 支持搜索并从账户成员中多选，不限制人数 | +| **负责人** | 否 | 支持搜索并从账户成员中多选，不限制人数；也可以选择固定在列表顶部的 **AI SRE**（副文案 **分配给 AI 执行**），把这条工作项交给账号的 AI SRE 执行 | 创建成功后，行动项会展示在卡片中，并在故障时间线上记录一条"创建了行动项"事件。被指定为负责人的成员会收到一条个人通知，提醒其跟进处理（默认通过**邮件和应用内推送**发送，可在[个人设置](/zh/on-call/configuration/personal-settings)中调整通知渠道）。 +### 指派给 AI SRE + +负责人选择器把 **AI SRE** 固定在成员列表上方，与成员之间用一条分隔线隔开；它不参与搜索过滤，输入任何关键词都会留在结果里。选中后，这条工作项交给账号的 AI SRE 执行，同时仍可以保留成员负责人。行动项与跟进项共用同一个创建/编辑弹窗，负责人字段行为一致。 + +- 卡片上以 **AI SRE** 头像展示该指派，与成员头像并列（最多显示 2 个头像，其余折叠为 `+N`） +- 鼠标悬停 AI SRE 头像会弹出悬浮卡，写明 AI SRE 以哪位成员的身份和权限执行，并提供 **接续对话** 入口，点击会在 AI SRE 面板中打开这次执行关联的会话 +- 执行来自 IM 会话时，悬浮卡只给出 **IM 会话暂不支持在 Web 查看** 的说明，不提供进入入口 +- 打开会话要求账号已启用 AI SRE，且您拥有使用 AI SRE 对话的权限；个人会话（仅创建者可见）或已失效的会话无法接续 +- 故障时间线上，这条工作项记录会以联合署名列出指派对象（例如「张三 和 AI SRE」） + +需要列出所有交给 AI SRE 的工作项时，使用 [CLI](/zh/developer/cli) 的 `flashduty incident work-item-list --assignee-type ai_sre`。 + ### 编辑与删除 - 拥有故障更新权限的成员，点击行动项标题，或通过 **更多** 菜单中的 **编辑** 打开弹窗，修改标题、描述或负责人 @@ -79,6 +91,8 @@ keywords: ["行动项", "跟进项", "工作项", "故障处理", "故障复盘" 此外，行动项的读写还受故障所属**协作空间**约束：只有账号所有者、账号管理员，以及能访问这个故障所属协作空间的成员才能操作；如果故障是手动创建、未挂载协作空间，则保持账户内可见，账户成员均可访问。这与故障本身的访问规则一致。 +上表中的「负责人」指账户成员。指派给 **AI SRE** 的工作项由 AI SRE 执行：AI SRE 不是账户成员，上表针对成员的完成权限与个人通知都不适用于它（同一条工作项上还选了成员负责人时，成员负责人照常收到通知）。 + ## 已关闭故障 故障关闭后，行动项卡片进入只读状态，跟进项卡片同时解锁为可编辑： diff --git a/zh/on-call/integration/alert-integration/alert-sources/aliyun-dataworks-op.mdx b/zh/on-call/integration/alert-integration/alert-sources/aliyun-dataworks-op.mdx index 0de01214..5bdb8ee1 100644 --- a/zh/on-call/integration/alert-integration/alert-sources/aliyun-dataworks-op.mdx +++ b/zh/on-call/integration/alert-integration/alert-sources/aliyun-dataworks-op.mdx @@ -70,7 +70,7 @@ DataWorks 智能监控自定义 Webhook 推送的消息统一包裹在 `message` | `DataWorks_Baseline_Alert` | 基线告警 | 基线预警与破线 | | `DataWorks_Event_Remind` | 事件告警 | 任务出错与变慢 | -连通性测试消息仅用于验证推送地址，不会产生告警事件。 +连通性测试消息（`message.content` 非空）仅用于验证推送地址，不会产生告警事件。 </div> @@ -118,6 +118,31 @@ DataWorks 智能监控 Webhook 属于**一次性事件**：官方协议只定义 </div> +## 标签 +<div className="md-block"> + +推送消息中的关键字段会作为标签保留在告警事件上，可用于路由、静默和通知模板渲染： + +| 标签 | 来源字段 | 说明 | +| ---- | -------- | ---- | +| `alert_type` | `message.title` | 告警类型，取值为 `DataWorks_Remind`、`DataWorks_Baseline_Alert` 或 `DataWorks_Event_Remind` | +| `remind_name` | `remind_name` | 规则名称 | +| `remind_unit` | `remind_unit` | 监控粒度：Task、Baseline、Project、BizProcess、ScheduleResourceGroup、DiResourceGroup | +| `remind_type` | `remind_type` | 原始触发条件 | +| `occur_time` | `occur_time` | 原始发生时间字符串，格式 `2021-07-13 16:16:20`；三类告警都会生成 | +| `remind_founder` | `remind_founder` | 规则创建人 | +| `more_information` | `more_information` | 运维中心周期实例 URL | +| `task_size` / `number_of_alerts` | 同名字段 | 任务数量、第几次告警；任务数量大于 0、告警次数大于 0 时才生成 | +| `node_id_list` / `node_name_list` / `node_owner_list` | 同名字段 | 节点 ID、节点名、责任人列表，英文逗号分隔、最多 5 个；非资源组监控时生成 | +| `resource_group_name` / `threshold` / `duration` | 同名字段 | 资源组名、阈值、持续时间（分钟）；仅资源组监控时生成 | +| `baseline_name` / `baseline_owners` | 同名字段 | 基线名、基线责任人 | +| `cycle_number` / `key_instance` / `sla_time` / `buffer` / `status` | 同名字段 | 周期号（天基线为 1）、当前关键实例、承诺时间、基线余量（分钟）、基线状态（`dangerous` 为预警、`overSla` 为破线） | +| `task_name` / `task_owner_name` / `event_type` / `event_name` | 同名字段 | 异常任务名、任务责任人、事件类型（`ERROR` 出错、`SLOW` 变慢）、事件名称 | + +空值字段不会生成标签。告警标题取自各告警族的名称字段：自定义告警取 `remind_name`，基线告警取 `baseline_name`，事件告警取 `task_name`。 + +</div> + ## 常见问题 <div className="md-block"> diff --git a/zh/on-call/integration/alert-integration/routing-rules.mdx b/zh/on-call/integration/alert-integration/routing-rules.mdx index c7780cfa..dd1b767b 100644 --- a/zh/on-call/integration/alert-integration/routing-rules.mdx +++ b/zh/on-call/integration/alert-integration/routing-rules.mdx @@ -25,7 +25,7 @@ keywords: ["路由规则", "告警路由", "分发策略", "协作空间", "分 | 方式 | 示例 | 识别规则 | | :------- | :----------------------- | :-------------------------------- | | **精确匹配** | `cpu.idle<10%` | 不符合其他任何格式时，字符串完全相等才算匹配 | -| **通配匹配** | `host * down` | 值包含 `*` 或 `?` 且没有 `/` 前后缀时按通配处理 | +| **通配匹配** | `host * down` | 值包含 `*` 或 `?` 且没有 `/` 前后缀时按通配处理（其它字符按字面匹配，需要正则请用 `/.../`） | | **正则匹配** | `/api-server-\d+/` | 值以 `/` 为前后缀时按 RE2 正则处理 | | **CIDR 匹配** | `cidr:192.168.1.0/24` | 值以 `cidr:` 为前缀时按 IP 段匹配 | | **数值匹配** | `num:gt:0.95` | 值以 `num:` + 比较符（`gt`/`ge`/`lt`/`le`）为前缀时按数值大小匹配 | diff --git a/zh/on-call/integration/instant-messaging/dingtalk.mdx b/zh/on-call/integration/instant-messaging/dingtalk.mdx index 8f1ca78c..da09a3a0 100644 --- a/zh/on-call/integration/instant-messaging/dingtalk.mdx +++ b/zh/on-call/integration/instant-messaging/dingtalk.mdx @@ -57,13 +57,13 @@ keywords: ["钉钉", "即时消息", "告警通知", "IM集成", "钉钉机器 ### 1. 开通权限 -进入 开发配置 → **权限管理** 页面，按需申请下表权限。基础通知只需要“基础”一组；开启作战室时再加第二组（`qyapi_get_member_by_mobile` 也用于一键关联用户）；启用钉钉 AI 流式卡片模板时再加第三组。集成详情页会显示缺少哪些基础权限，并提供直达每项权限的链接。 +进入 开发配置 → **权限管理** 页面，按需申请下表权限。基础通知只需要“基础”一组；开启作战室时再加第二组（`qyapi_get_member_by_mobile` 也用于自动关联成员）；启用钉钉 AI 流式卡片模板时再加第三组。集成详情页会显示缺少哪些基础权限，并提供直达每项权限的链接。 | 分组 | 官方权限名称 | 用途 | | :--- | :--- | :--- | | 基础（必需） | `qyapi_robot_sendmsg` | 发送机器人消息，用于基础通知、会话机器人回复、普通版互动卡片、作战室消息，以及下载机器人接收到的文件 | | 基础（必需） | `qyapi_chat_manage` | 获取群聊信息，用于普通通知、酷应用和机器人消息投递 | -| 基础（必需） | `qyapi_get_member_by_mobile` | 根据手机号获取钉钉用户 ID，用于一键关联用户和邀请成员进入作战室 | +| 基础（必需） | `qyapi_get_member_by_mobile` | 根据手机号获取钉钉用户 ID，用于自动关联成员、一键关联用户和邀请成员进入作战室 | | 开启作战室时需要 | `qyapi_chat_read` | 读取群聊信息，用于作战室群状态确认和群成员处理 | | 开启作战室时需要 | `qyapi_chat_base_read` | 读取群聊基础信息，用于作战室群查询 | | 使用 AI 流式卡片时需要 | `Card.Instance.Write` | 创建并投放 AI SRE 流式卡片；仅在启用钉钉 AI 流式卡片模板时需要 | @@ -218,11 +218,24 @@ keywords: ["钉钉", "即时消息", "告警通知", "IM集成", "钉钉机器 成员完成关联后，才能收到钉钉消息通知。关联失败时，请确认成员的手机号与钉钉账号一致。 +### 自动关联 + +成员无需手动操作，系统会自动完成关联：保存集成后立即尝试一次，之后每小时再自动扫描一次，覆盖所有已启用的钉钉集成。 + +自动关联使用成员在个人中心已验证的手机号换取钉钉账号 ID（钉钉不支持按邮箱查询），效果等同于成员用同一手机号在钉钉登录 Flashduty。有两处限制会让重试延后： + +- 钉钉答复过、但没能建立绑定的成员（例如手机号在钉钉侧查不到，或该钉钉账号已经绑定到其他成员），7 天内不再重复尝试；成员的手机号发生变化时会重新尝试 +- 钉钉应用缺少 `qyapi_get_member_by_mobile` 权限（错误码 60011），或服务器 IP 不在应用白名单内（错误码 60020）时，该集成的自动关联暂停 24 小时；补齐权限或白名单后重新保存集成即可恢复 + +**一键关联** 会忽略上面的 7 天重试窗口，立即重新查询一次；如果提示 **没有关联到新成员**，说明本次查询没有产生新的绑定（例如手机号在钉钉侧查不到，或对应钉钉账号已经绑定到其他成员）。 + ## 常见问题 <AccordionGroup> <Accordion title="消息无法投递到个人，操作记录提示「未关联应用」？"> 前往 钉钉 → 工作台 → 搜索应用名称 → **打开应用**，完成一次登录以关联钉钉与 Flashduty 账号，系统才能获取用户身份并推送消息。 + +如果成员在个人中心已经验证过手机号，系统也可能已经自动完成关联，无需成员登录；可在集成详情页的 **关联用户** 页签确认当前关联状态。 </Accordion> <Accordion title="消息卡片按钮点击无效或报错？"> diff --git a/zh/on-call/integration/instant-messaging/lark.mdx b/zh/on-call/integration/instant-messaging/lark.mdx index 8a254f9c..8ecb4d7d 100644 --- a/zh/on-call/integration/instant-messaging/lark.mdx +++ b/zh/on-call/integration/instant-messaging/lark.mdx @@ -136,11 +136,21 @@ keywords: ["飞书", "Lark", "即时消息", "告警通知", "IM集成"] 成员完成关联后，才能收到飞书消息通知。关联失败时，请确认成员的手机号或邮箱与飞书账号一致。 +### 自动关联 + +成员无需手动操作，系统会自动完成关联：保存集成后立即尝试一次，之后每小时再自动扫描一次，覆盖所有已启用的飞书集成。 + +自动关联使用成员在个人中心已验证的手机号或邮箱，分批（每批 50 个）调用飞书接口换取账号 ID。飞书对查不到的账号和不在应用 **可见范围** 内的用户都返回空 `user_id`，两者都按「未找到」处理。如果飞书应用缺少通讯录权限（错误码 99991672 / 99991679）或凭证被飞书拒绝，该集成的自动关联会暂停 24 小时，补齐权限并重新保存集成后即可恢复。 + +查询过、但没有查到对应飞书账号的成员，7 天内不会重复尝试；成员的联系方式发生变化时会重新尝试。**一键关联** 会忽略这个 7 天窗口，立即重新查询一次；如果提示 **没有关联到新成员**，说明本次查询没有产生新的绑定。 + ## 常见问题 <AccordionGroup> <Accordion title="消息无法投递到个人，操作记录提示「未关联应用」？"> 前往 飞书 → 工作台 → 搜索应用名称 → **打开应用**，完成一次登录以关联飞书与 Flashduty 账号，系统才能获取用户身份进行消息推送。 + +如果成员在个人中心已经验证过手机号或邮箱，系统也可能已经自动完成关联，无需成员登录；可在集成详情页的 **关联用户** 页签确认当前关联状态。 </Accordion> <Accordion title="消息卡片按钮点击无效或报错？"> diff --git a/zh/on-call/integration/instant-messaging/slack.mdx b/zh/on-call/integration/instant-messaging/slack.mdx index bec08702..20cca802 100644 --- a/zh/on-call/integration/instant-messaging/slack.mdx +++ b/zh/on-call/integration/instant-messaging/slack.mdx @@ -34,11 +34,13 @@ keywords: ["Slack", "即时消息", "告警通知", "IM集成", "协作工具"] 在 **增强功能** 中配置 AI SRE 开关，默认均为开启，各开关含义见 [IM 平台](/zh/ai-sre/im)。Slack 的 **允许在 IM 中使用 AI SRE** 同时控制 `/fd` 命令。 -## 关联用户 +## 成员关联 -在集成详情页的 **关联用户** 页签中，可按 **全部 / 已关联 / 未关联** 筛选成员，也可按名称或邮箱搜索。点击 **一键关联**，系统会用成员的手机号或邮箱匹配 Slack 账号并自动关联，效果等同于成员在 Slack 中登录 Flashduty。 +Slack 集成不提供成员关联页面：集成详情页只有配置页，没有 **关联用户** 页签，也没有 **一键关联** 按钮；Flashduty 不会用成员的手机号或邮箱去换取 Slack 账号 ID 做批量绑定。 -成员完成关联后，才能收到 Slack 消息通知。关联失败时，请确认成员的邮箱与 Slack 账号一致。 +Slack 集成按**邮箱**识别成员：成员在 Slack 中操作告警卡片时，Flashduty 读取该 Slack 账号的邮箱，并与当前账户下的成员邮箱比对，匹配到即视为该成员。所以这里不需要逐个成员绑定，但要保证成员的 Slack 邮箱与 Flashduty 成员邮箱一致；邮箱不一致时，系统会在 Slack 中回复一条提示，说明未能匹配到成员。 + +Slack 的接入以**工作区**为单位：完成 [安装应用](#install-app) 的 OAuth 授权后，该工作区内的频道通知、群聊中 @ AI SRE 和作战室即可使用。 <span id="aisre-permissions"></span> <span id="war-room-scope"></span> From 687f56169b426078b80a9266b2639d1baee83f9d Mon Sep 17 00:00:00 2001 From: ysyneu <ysyneu@gmail.com> Date: Sat, 17 Oct 2026 03:43:19 -0700 Subject: [PATCH 3/5] docs(monitors,rum): document rule folders, dashboard search, issue resolve modes and auto-analysis --- .../alert-rules/investigation-entries.mdx | 16 ++++++--- en/monitors/dashboards/dashboards.mdx | 10 ++++-- en/monitors/data-sources/data-sources.mdx | 2 +- en/monitors/engine/engine-lost-alert.mdx | 2 +- en/monitors/engine/engine.mdx | 2 +- en/monitors/explore/explore.mdx | 2 +- en/monitors/folders/folders.mdx | 17 ++++++++++ en/monitors/quickstart/quickstart.mdx | 8 +++-- en/rum/error-tracking/error-viewing.mdx | 15 +++++++-- en/rum/error-tracking/issue-alerts.mdx | 2 ++ en/rum/error-tracking/issue-status.mdx | 33 ++++++++++++++----- en/rum/explorer/data-query.mdx | 3 +- en/rum/quickstart/app-management.mdx | 2 ++ .../alert-rules/investigation-entries.mdx | 16 ++++++--- zh/monitors/dashboards/dashboards.mdx | 10 ++++-- zh/monitors/data-sources/data-sources.mdx | 2 +- zh/monitors/engine/engine-lost-alert.mdx | 2 +- zh/monitors/engine/engine.mdx | 2 +- zh/monitors/explore/explore.mdx | 2 +- zh/monitors/folders/folders.mdx | 17 ++++++++++ zh/monitors/quickstart/quickstart.mdx | 8 +++-- zh/rum/error-tracking/error-viewing.mdx | 15 +++++++-- zh/rum/error-tracking/issue-alerts.mdx | 2 ++ zh/rum/error-tracking/issue-status.mdx | 33 ++++++++++++++----- zh/rum/explorer/data-query.mdx | 3 +- zh/rum/quickstart/app-management.mdx | 2 ++ 26 files changed, 178 insertions(+), 50 deletions(-) diff --git a/en/monitors/alert-rules/investigation-entries.mdx b/en/monitors/alert-rules/investigation-entries.mdx index ac8a48a8..0a69d1b3 100644 --- a/en/monitors/alert-rules/investigation-entries.mdx +++ b/en/monitors/alert-rules/investigation-entries.mdx @@ -49,7 +49,7 @@ The limit is **20 entries**: once you reach 20 the two add buttons become disabl | Field | Required | Notes | |------|------|------| | **Purpose** | No | One sentence on what this entry helps confirm. Single-line plain text; line breaks are replaced with spaces. The console caps the input at 200 characters and the purpose must also be **≤512 bytes**. The purpose is **not** rendered as a template and is **not** part of duplicate identity (two entries that differ only in purpose are still duplicates). It is shown to responders and read by AI SRE to judge each entry's intent | -| **Time range** | Yes | "**From** N **min before the alert to** M **min after**". A new entry defaults to 60 minutes before and 0 minutes after. Both directions must be non-negative and at least one must be greater than 0 | +| **Time range** | Yes | "**From** N **min before the alert to** M **min after**". A new entry defaults to 60 minutes before and 30 minutes after. Both directions must be non-negative and at least one must be greater than 0 | Time range semantics: @@ -62,7 +62,7 @@ Time range semantics: | Field | Notes | |------|------| -| **Dashboard** | Search by title or description and pick a dashboard; the folder path of the selection is shown below the picker. **Changing the dashboard clears the target object and the variable values**, because both belong to the previous dashboard | +| **Dashboard** | Search by title or description and pick a dashboard; the folder path of the selection is shown below the picker. The picker opens with the dashboards in **the rule's own folder** (20 per page; click `Load more dashboards` for more), and typing a keyword switches to a search by title or description across folders. **Changing the dashboard clears the target object and the variable values**, because both belong to the previous dashboard | | **Open at** | `Whole dashboard`, or a tab / section / panel inside the dashboard; each option shows its full breadcrumb path. A whole-dashboard entry opens the dashboard itself | | **Variable values** | One input per template variable of that dashboard. Leave it empty to use the dashboard's own default | @@ -120,11 +120,19 @@ outcome:="failure" ## Previewing an entry -Click the eye icon on an entry to open the **Preview investigation entry** dialog, which renders that entry from a real event snapshot so you can confirm the jump before relying on it. +Click the eye icon on an entry to open the **Preview investigation entry** dialog. The dialog picks how to preview depending on whether the entry uses template variables. + +**Entries without template variables: a static preview of the current configuration.** When neither the dashboard variable values nor the query contain `{{`, the dialog renders the entry from the **current form and the current time**, **including unsaved changes**. The rule does not need to be saved or to have an active alert. The window is anchored on the moment you open the dialog: start = now - the "before" duration, end = now + the "after" duration. + +- If a query entry has no datasource set and the rule matches more than one, a **Preview datasource** picker appears at the top, listing the datasources the rule matches. Nothing is rendered until you pick one, and it says `Select a datasource to preview this query.` +- If the rule currently matches no datasource, it says `This rule has no matching datasource. Configure a rule datasource first.` Configure the rule's datasource under "Data source and query" first. + +**Entries with template variables: a preview from a real alert's event snapshot.** As soon as any dashboard variable value or the query contains `{{`, the dialog renders from an alert snapshot instead: - Prerequisites: the **rule must be saved** (otherwise it says `Save the rule first, then preview once it has an alert.`) and the rule must **currently have an active alert** (otherwise `This rule has no active alerts. Preview will be available once an alert fires.`). The dialog picks a sample from the rule's active alerts, with paging above 20. - The preview uses the selected alert's **event snapshot** and **does not include unsaved changes in the form**, so save the rule and wait for it to fire before previewing a new configuration. -- Clicking an entry in the dialog opens the target in a new tab. If that alert has no snapshot matching this entry, it says `This alert has no matching snapshot for this entry. Select an alert generated after the configuration took effect.`; if the alert has no snapshot at all, it says `This alert has no investigation links. Select an alert generated after the configuration took effect.` + +In both modes, clicking an entry in the dialog opens the target in a new tab. In snapshot mode, if that alert has no snapshot matching this entry, it says `This alert has no matching snapshot for this entry. Select an alert generated after the configuration took effect.`; if the alert has no snapshot at all, it says `This alert has no investigation links. Select an alert generated after the configuration took effect.` ## Validation and limits diff --git a/en/monitors/dashboards/dashboards.mdx b/en/monitors/dashboards/dashboards.mdx index 7b457cfc..f27777db 100644 --- a/en/monitors/dashboards/dashboards.mdx +++ b/en/monitors/dashboards/dashboards.mdx @@ -17,8 +17,9 @@ Whether you can view or edit a dashboard depends on its **folder** — see [Perm The left side is the folder tree shared with alert rules; the right side lists the dashboards in the current folder. Folders are created, renamed, moved and deleted on the tree — see [Folder management](/en/monitors/folders/folders). -- The box above the folder tree on the left searches the **current folder** only; the search term and page are kept in the page address, so links can be shared and returning from a dashboard restores the list. -- **Global search** at the top right of the page looks across every folder you can read (only folders you can read are listed), ignoring the folder you are currently in: it matches a dashboard's **title or description**, with multiple keywords separated by spaces. Each result shows the title, its folder path and the description, and clicking one opens that dashboard; results are paged 20 at a time and there is a **Retry** button if the request fails. This dialog's search state lives only in the dialog — closing it discards the search, and it is never written into the page address. +- The box above the folder tree on the left searches the **current folder** only; the search term and page are kept in the page address, so links can be shared and returning from a dashboard restores the list; the page size you choose is remembered in the browser and reused the next time you open this list. +- **Search all dashboards** at the top right of the page looks across every folder you can read (only folders you can read are listed), ignoring the folder you are currently in: it matches a dashboard's **title or description**, with multiple keywords separated by spaces (up to 128 characters). Each result shows the title and its folder path (long paths wrap in full), and clicking one opens that dashboard; results are paged 20 at a time and there is a **Retry** button if the request fails. It is not a dialog: it expands in place, and results appear in a dropdown panel below it. Its search state lives only in the search box. Click the ✕ on the right, press `Esc`, or click outside the panel to close it; closing discards the search, and it is never written into the page address. +- When the box is open but empty, the panel lists the **5 most recently opened** dashboards (title plus full folder path); clicking one opens it and moves it to the top. This history is kept only in the current account's browser, is never uploaded, and **Clear history** empties it. - Each row's **More** menu offers: move to another folder, clone to this folder, clone to another folder. A clone is a new dashboard whose title gets a "copy" suffix and **does not carry version history**; moving or cloning into another folder requires read access to that folder. ## Create and save a dashboard @@ -205,7 +206,9 @@ Dashboards **cannot** be shared publicly or anonymously. Anyone opening a link m ## Fullscreen and query details -Hover over a panel title to **Edit** (requires management permission), go **Fullscreen**, or **Retry**. +Hover over a panel title to **Edit** (requires management permission), go **Fullscreen**, or **Refresh**. + +- **Refresh**: this icon appears in the hover actions once the panel's query has finished; click it to re-run that panel's query immediately. - In fullscreen you can change that panel's time range without affecting the others. - In fullscreen you can **Copy panel link** or **Download data CSV**. @@ -268,3 +271,4 @@ If someone saves the dashboard while you are viewing it, the page loads the late | Versions kept | 20 | | Trash retention | 30 days | | Dashboard definition size | 1 MiB | +| Search-all-dashboards keyword length | 128 characters | diff --git a/en/monitors/data-sources/data-sources.mdx b/en/monitors/data-sources/data-sources.mdx index e3604856..8ec4c9e1 100644 --- a/en/monitors/data-sources/data-sources.mdx +++ b/en/monitors/data-sources/data-sources.mdx @@ -41,7 +41,7 @@ The list shows only the data sources you are allowed to query, with these column - **Associated Alert Engine**: the engine cluster that runs queries, with its online status - **Enable datasource**: turns the data source on or off — see [Enable and alert evaluation](#enable-and-alert-evaluation) -You can search by name, type, connection URL or remarks. The list refreshes engine status every 5 seconds. +You can search by name, type, connection URL or remarks. The list refreshes engine status every 5 seconds. The page size you choose is remembered in the browser and reused the next time you open this list. ## Data source permissions (team authorization) diff --git a/en/monitors/engine/engine-lost-alert.mdx b/en/monitors/engine/engine-lost-alert.mdx index a6a53541..809da866 100644 --- a/en/monitors/engine/engine-lost-alert.mdx +++ b/en/monitors/engine/engine-lost-alert.mdx @@ -14,7 +14,7 @@ For an engine cluster composed of multiple instances, as long as at least one in ## Alert rule list -The list shows the configured rules and their main parameters (see [Create an alert rule](#create-an-alert-rule) for what each means). You can search by keyword, customize the displayed columns, and enable or disable a rule with its switch. +The list shows the configured rules and their main parameters (see [Create an alert rule](#create-an-alert-rule) for what each means). You can search by keyword, customize the displayed columns, and enable or disable a rule with its switch. The page size, and which columns are shown and in what order, are remembered in the browser and reused the next time you open this list. ## Create an alert rule diff --git a/en/monitors/engine/engine.mdx b/en/monitors/engine/engine.mdx index 9e11f7eb..d5fcf3c1 100644 --- a/en/monitors/engine/engine.mdx +++ b/en/monitors/engine/engine.mdx @@ -12,7 +12,7 @@ The alert engine page contains three tabs: **Alert Engine Status**, **Engine Ins ## Alert engine status -Displays information about all registered alert engine instances. The list auto-refreshes every 5 seconds. +Displays information about all registered alert engine instances. The list auto-refreshes every 5 seconds. The page size you choose is remembered in the browser and reused the next time you open this list. | Column | Description | |--------|-------------| diff --git a/en/monitors/explore/explore.mdx b/en/monitors/explore/explore.mdx index 6389d15f..62df59c1 100644 --- a/en/monitors/explore/explore.mdx +++ b/en/monitors/explore/explore.mdx @@ -38,7 +38,7 @@ The result area auto-layouts based on data source and query type: - **Prometheus**: Split pane — line chart (Graph) on top, raw samples (Raw) below, with a draggable splitter. - **Other data sources**: Single result pane showing log view, table view, or samples view depending on the query type. -The samples view shows 20 rows per page; the table view shows 100 rows per page by default, or 200 or 500. +The samples view shows 20 rows per page by default; the table view shows 100 rows per page by default, or 200 or 500. The browser remembers the page size for both views, so it stays after a refresh or a new query. ### Graph features diff --git a/en/monitors/folders/folders.mdx b/en/monitors/folders/folders.mdx index 78ae32fe..260c4a21 100644 --- a/en/monitors/folders/folders.mdx +++ b/en/monitors/folders/folders.mdx @@ -29,6 +29,23 @@ When a folder is selected, the right side displays its detailed information: | **Updated At** | Last modification time | | **Created At** | Creation time | +## Move rules to another folder + +You can move alert rules to a different folder. The rules themselves do not change, only where they belong. + +- **One rule**: choose **Move** in the `⋮` menu at the end of its row. +- **Several rules**: select them, then click **Move** above the list. + +Both open the **Move to another folder** dialog: + +| Action | Description | +|------|------| +| **Search folders** | Type a keyword to filter the folder tree by name; matches keep their full path | +| Choose a folder | Click the target folder in the tree | +| **Confirm** | Stays disabled while the selected folder is the rule's current folder | + +If the folder tree fails to load, you see `Failed to load folders` and a **Retry** button. After a successful move the list refreshes; if it fails, the rules stay in their original folder. + ## Team access control Folders support team-based access control by binding teams to folders to restrict operation permissions. diff --git a/en/monitors/quickstart/quickstart.mdx b/en/monitors/quickstart/quickstart.mdx index 52497266..de89c612 100644 --- a/en/monitors/quickstart/quickstart.mdx +++ b/en/monitors/quickstart/quickstart.mdx @@ -236,9 +236,9 @@ Section 6 configures **investigation entries**: it wires each alert straight to | **Add dashboard entry** | Pick a dashboard and target the whole dashboard, a tab, a section or a panel, setting the values of that dashboard's template variables | | **Add query entry** | Store an initial query (data source + query type + query + query parameters) that runs on the alert event's own data source by default | | **Purpose** | One sentence on what this entry helps confirm; optional | -| **Time range** | "N min before the alert to M min after", anchored on the alert event time; defaults to 60 minutes before and 0 after | +| **Time range** | "N min before the alert to M min after", anchored on the alert event time; defaults to 60 minutes before and 30 after | -You can add up to 20 entries and drag them into any order (order only affects display). The eye icon on an entry opens a **preview** rendered from one of the rule's real alerts. Entries take effect when you save the rule and are rendered into a snapshot delivered with the alert event, so editing the rule does not change alerts already produced. +You can add up to 20 entries and drag them into any order (order only affects display). The eye icon on an entry opens a **preview**: entries without template variables are previewed from the current form and the current time, and entries with template variables from the snapshot of one of the rule's real alerts. Entries take effect when you save the rule and are rendered into a snapshot delivered with the alert event, so editing the rule does not change alerts already produced. <Warning> Saving investigation entries requires every alert engine instance in the cluster to be `v0.75.3` or later; otherwise the save is rejected. @@ -325,7 +325,9 @@ If some rules fail to update, you see the number of failures and the first reaso ### Batch move -After selecting multiple rules, you can batch move them to another folder. +After selecting multiple rules, click **Move** above the list to move them to another folder. To move one rule, choose **Move** in the `⋮` menu at the end of its row. + +Both open the **Move to another folder** dialog: pick the target folder in the tree, or filter by name in **Search folders** first. **Confirm** stays disabled while the selected folder is the current one. After a successful move the list refreshes. See [Folder management](/en/monitors/folders/folders). ## Import alert rules diff --git a/en/rum/error-tracking/error-viewing.mdx b/en/rum/error-tracking/error-viewing.mdx index 5c4ebab9..aa93aaa0 100644 --- a/en/rum/error-tracking/error-viewing.mdx +++ b/en/rum/error-tracking/error-viewing.mdx @@ -39,7 +39,7 @@ The Issue list can be **sorted by priority**, and the Priority filter is include ## Issue status -An Issue is For Review, Reviewed, Resolved, or Ignored. For the transition rules, see [Issue status](./issue-status). +An Issue is For Review, Reviewed, Resolved, or Ignored. Resolved has two modes, "Resolved" and "Resolved in next version", which you switch in the status dropdown. For the transition rules, see [Issue status](./issue-status). ## Filtering and sorting @@ -128,7 +128,7 @@ The system first classifies by error type and message. For example, a request wi ## Regression -A resolved Issue that occurs again in a different version reopens and is marked as a regression. For the trigger conditions, see [Issue status](./issue-status). +A resolved Issue that occurs again reopens and is marked as a regression. With "Resolved", any recurrence reopens it, including in the same version; with "Resolved in next version", only a newer version does. See [Issue status](./issue-status#resolve-mode). ## Issue details @@ -230,6 +230,17 @@ Click any Issue to open the details panel and view more information. </Accordion> </AccordionGroup> +### Header actions + +The top right of the Issue details panel has two AI SRE buttons. They show only when AI SRE is enabled for the account: + +| Button | Shown when | What it does | +|------|----------|------| +| **Auto-analyze** | You can create AI SRE automation rules | Opens the AI SRE automation create form with the "RUM Issue 故障分析" preset template and the application's alert channels filled in. Once saved, the automation analyzes incidents that this application's Issue alerts raise from then on | +| **AI fix** | You can access AI SRE sessions | Opens an AI SRE session with the current Issue attached to the input box as a reference tag. See [Sessions: Attachments and context references](/en/ai-sre/sessions#attachments-and-context-references) | + +**Auto-analyze** is triggered by incidents, so the application must be able to raise them first. When you click the button, RUM reads the application's alert settings. Only if alerting is on, delivery is **Flashduty channel**, and at least one channel is selected does it go straight to the create form, with channels already picked from the application's alert settings; confirm and click **Create**. Otherwise it shows "This application has no On-call alerting yet. Issues must raise incidents to trigger auto-analysis, so set up alerting first." and jumps to the application's **Alert settings** tab. For the template and form fields, see [Automations](/en/ai-sre/automations). + ## Issue alerts In **Application management**, edit the application, turn on **Alerts**, and select a channel or Webhook. For setup, see [Issue alerts](./issue-alerts). diff --git a/en/rum/error-tracking/issue-alerts.mdx b/en/rum/error-tracking/issue-alerts.mdx index d2bbe8af..86a8e459 100644 --- a/en/rum/error-tracking/issue-alerts.mdx +++ b/en/rum/error-tracking/issue-alerts.mdx @@ -169,6 +169,8 @@ RUM alerts pass through four layers in order: data filtering, alert grading, ale With Flashduty channel delivery, you can process RUM alerts further in the [Alert Pipeline](/en/on-call/integration/alert-integration/alert-pipelines). For example, adjust severity by affected user count, suppress repeated alerts in a time window, or customize alert titles. When you choose Webhook delivery, RUM alerts do not enter this On-call processing chain; handle payload transformation, routing, and notification in your receiver. +The [Auto-analyze](/en/rum/error-tracking/error-viewing#header-actions) automation on the Issue details page is triggered by incidents, and only Flashduty channel delivery turns Issue alerts into incidents. It therefore works only for applications that deliver to channels; Webhook delivery raises no incidents and cannot trigger it. + ## Further reading <CardGroup cols={2}> diff --git a/en/rum/error-tracking/issue-status.mdx b/en/rum/error-tracking/issue-status.mdx index 0a95f74e..2bc2d6e5 100644 --- a/en/rum/error-tracking/issue-status.mdx +++ b/en/rum/error-tracking/issue-status.mdx @@ -12,7 +12,7 @@ In Error Tracking, all Issues have a status that helps you categorize and priori | **For Review** | New or regressed Issues that need attention | | **Reviewed** | Categorized Issues that need fixing, now or later | | **Ignored** | Issues that don't need further investigation or handling | -| **Resolved** | Issues that have been fixed and no longer occur | +| **Resolved** | Issues that have been fixed and no longer occur. Resolved comes in two modes, **Resolved** and **Resolved in next version**, which differ in what happens when the error comes back (see [Resolve mode](#resolve-mode)) | <Info> All newly discovered Issues have an initial status of **For Review**. Flashduty automatically updates status based on specific conditions, and you can also manually adjust it. @@ -37,18 +37,21 @@ Properly configuring your application's `version` tag is crucial for accurately ## Auto-reopen issues -Flashduty has Issue detection capability. When a resolved Issue reappears, the system automatically reopens it and marks it as **For Review** status, and adds a **Regression** label. +Flashduty has Issue detection capability. When a resolved Issue reappears and meets the condition set by its **resolve mode**, the system automatically reopens it and marks it as **For Review** status, and adds a **Regression** label. ### What is regression? -Regression refers to previously fixed problems unexpectedly reappearing after code updates. Flashduty's regression detection automatically identifies these situations, reopening related Issues instead of creating duplicate Issues, thereby preserving the complete context and history of the problem. +Regression refers to a previously fixed problem appearing again, most often an unexpected return after a code update. Flashduty's regression detection automatically identifies these situations, reopening related Issues instead of creating duplicate Issues, thereby preserving the complete context and history of the problem. ### Regression detection mechanism +When an error is grouped into a **Resolved** Issue, whether it counts as a regression depends on the Issue's **resolve mode** (see [Resolve mode](#resolve-mode)): + <Warning> -Regression detection is triggered when any of the following conditions are met: -- If a **Resolved** error reappears in an updated version of the code -- If a **Resolved** error reappears when no version tag is set +- **Resolved in next version** (default): only a version the Issue has not seen before triggers detection +- **Resolved**: any recurrence triggers detection, including repeats in the same version +- An error without a `version` tag triggers detection in both modes +- An error that occurred before the Issue's resolve time does not trigger detection (duplicate delivery, or an old error an SDK buffered offline and sent late) </Warning> Once regression is detected, Flashduty will: @@ -64,7 +67,7 @@ Once regression is detected, Flashduty will: ### Associated version configuration -Regression detection considers the service version information when the error occurred. Detection is only triggered in new versions after the Issue is marked as **Resolved**. +Regression detection considers the service version information when the error occurred. With **Resolved in next version** (default), detection is triggered only in a version the Issue has not seen before, after it was marked **Resolved**. With **Resolved**, versions are not compared, so a recurrence in the same version also triggers detection. ```javascript window.FC_RUM.init({ @@ -80,6 +83,20 @@ window.FC_RUM.init({ Without a version tag, a resolved Issue that gets new errors is still marked "Regression". However, the system can't tell whether the errors came from a new version. </Note> +## Resolve mode + +In the status dropdown, **Resolved** is split into two options by what should happen when the error comes back. Both set the Issue to resolved: + +| Dropdown option | Behavior on recurrence | +|------|------| +| **Resolved** | Reopens whenever it occurs again, including in the same version | +| **Resolved in next version** | Reopens only when it occurs in a version the Issue has not seen before | + +- You can switch between the two at any time in the status dropdown. Switching only the mode does not change the Issue's statistics or alert state. +- New Issues default to **Resolved in next version**, and so do Issues the system resolves automatically. +- An error without a `version` tag reopens the Issue in both modes, because without version information old and fixed code cannot be told apart. +- On reopening, the Issue goes to **For Review**, is marked as a regression, and records when and in which version it regressed. The status cell in the list is narrow, so both modes show as **Resolved**; the details panel adds a "Resolved in next version" label next to it. + ## Manually update status You can manually update Issue status anywhere Issues are displayed, including the Issue list or details panel. @@ -88,7 +105,7 @@ You can manually update Issue status anywhere Issues are displayed, including th <img src="https://docs-cdn.flashcat.cloud/images/png/a57c54a6a28915dec4480a9db9411e30.png" alt="Manually Update Status" style={{maxWidth: "600px", margin: "0 auto", display: "block"}} /> </Frame> -Click the current status and select the new status from the dropdown menu. +Click the current status and select the new status from the dropdown menu. The dropdown has 5 options: **For Review**, **Reviewed**, **Resolved**, **Resolved in next version**, and **Ignored**. The two resolved options each show their reopen behavior beneath them; see [Resolve mode](#resolve-mode). ## Best practices diff --git a/en/rum/explorer/data-query.mdx b/en/rum/explorer/data-query.mdx index 7cfd6702..817068f9 100644 --- a/en/rum/explorer/data-query.mdx +++ b/en/rum/explorer/data-query.mdx @@ -93,6 +93,7 @@ Use `attribute:term` syntax to search specific attributes: |----------|------| | `browser_name:Chrome` | Search for browsers with value `Chrome` | | `view_name:*/detail` | Search for view names ending with `/detail` | +| `browser_name:*` | Search for events that have this field: a lone `*` as the whole value means the field exists, and is not a wildcard | | `-resource_status_code:0` | Search for resources with status code not `0` | | `os_name:"Mac OS X"` | Search for OS names with value `"Mac OS X"` | @@ -203,7 +204,7 @@ The on-error capture switches live in [Remote Configuration](../quickstart/app-m Search for views with loading time over 3 seconds on mobile devices: ``` - device_type:mobile view_loading_time:>3s + device_type:Mobile view_loading_time:>3s ``` </Accordion> <Accordion title="Geographic Location Search"> diff --git a/en/rum/quickstart/app-management.mdx b/en/rum/quickstart/app-management.mdx index 3a949f38..a278b205 100644 --- a/en/rum/quickstart/app-management.mdx +++ b/en/rum/quickstart/app-management.mdx @@ -26,6 +26,8 @@ To meet the data security requirements of different business scenarios, RUM appl In private applications, if other members need to view content, they can be temporarily authorized to access it by sharing the incident link. </Note> +Read permission on an application also applies to data queries: the viewer's queries and the data query API return event data filtered by application read permission. If a query explicitly names an application you cannot read, the whole batch fails instead of silently dropping that part. If a query names no application, the server excludes the applications you cannot read from the results (private applications where you are neither the creator nor in the managing team). The account owner and administrators can read every application, so nothing is excluded for them. A single request can name at most 50 applications; above that the whole batch returns a parameter error. + ## Create application <Frame caption="RUM Application Creation Interface"> diff --git a/zh/monitors/alert-rules/investigation-entries.mdx b/zh/monitors/alert-rules/investigation-entries.mdx index 9a8d424d..d957b542 100644 --- a/zh/monitors/alert-rules/investigation-entries.mdx +++ b/zh/monitors/alert-rules/investigation-entries.mdx @@ -49,7 +49,7 @@ keywords: ["调查入口", "排查入口", "告警规则", "仪表盘入口", " | 字段 | 必填 | 说明 | |------|------|------| | **调查用途** | 否 | 一句话说明这个入口帮助确认什么。单行纯文本，换行符会被替换为空格；控制台把输入框限制为 200 个字符，同时要求不超过 **512 字节**。用途**不渲染模板**，也不参与去重身份（两个入口只有用途不同仍然算重复）。它面向值班人员展示，也供 AI SRE 判断每个入口的意图 | -| **时间范围** | 是 | 「**告警前** N **分钟，至告警后** M **分钟**」，新建入口默认为告警前 60 分钟、告警后 0 分钟。两个方向都必须非负，且至少一个大于 0 | +| **时间范围** | 是 | 「**告警前** N **分钟，至告警后** M **分钟**」，新建入口默认为告警前 60 分钟、告警后 30 分钟。两个方向都必须非负，且至少一个大于 0 | 时间范围的语义： @@ -62,7 +62,7 @@ keywords: ["调查入口", "排查入口", "告警规则", "仪表盘入口", " | 字段 | 说明 | |------|------| -| **仪表盘** | 按标题或描述搜索并选择仪表盘；选中后下方会显示它所在的分组路径。**更换仪表盘会清空定位对象与变量取值**（它们都属于旧仪表盘） | +| **仪表盘** | 按标题或描述搜索并选择仪表盘；选中后下方会显示它所在的分组路径。打开选择器时默认列出**规则所在分组**的仪表盘（每页 20 条，点 `加载更多仪表盘` 继续加载），输入关键词后改为按标题或描述跨分组搜索。**更换仪表盘会清空定位对象与变量取值**（它们都属于旧仪表盘） | | **定位到** | `整个仪表盘`，或仪表盘内的某个标签页 / 分组 / 图表，选项后跟完整路径面包屑。整个仪表盘的入口打开仪表盘本身 | | **变量取值** | 该仪表盘的每个模板变量一个输入框；留空表示使用仪表盘自己的默认值 | @@ -120,11 +120,19 @@ outcome:="failure" ## 预览跳转 -点击入口右侧的眼睛图标打开 **预览调查入口** 弹窗，它按真实事件的快照渲染这个入口，用来在保存前确认跳转是否符合预期。 +点击入口右侧的眼睛图标打开 **预览调查入口** 弹窗。弹窗按入口是否使用模板变量选择预览方式。 + +**不使用模板变量的入口：按当前配置静态预览。** 入口的仪表盘变量取值和查询语句里都没有 `{{` 时，弹窗直接用表单里的**当前配置和当前时间**渲染这个入口，**包含尚未保存的修改**。这既不需要规则已保存，也不需要规则有活跃告警。窗口以打开弹窗的时刻为锚点：开始 = 当前时间 − 告警前时长，结束 = 当前时间 + 告警后时长。 + +- 查询入口没有指定数据源、而规则匹配到多个数据源时，弹窗顶部会出现 **预览数据源** 选择框，选项是该规则匹配到的数据源。没有选定之前不渲染预览，并提示 `请选择预览数据源。`。 +- 规则当前没有匹配到任何数据源时提示 `该规则暂无匹配的数据源，请先配置规则数据源。`，此时先到「数据源与查询」配置规则的数据源。 + +**使用模板变量的入口：按真实告警的事件快照预览。** 只要入口的任一仪表盘变量取值或查询语句里出现 `{{`，弹窗就改用告警快照渲染： - 前置条件：**规则必须已经保存**（否则提示 `请先保存规则，产生告警后再预览`），并且该规则**当前有活跃告警**（否则提示 `该规则暂无活跃告警，产生告警后可预览`）。弹窗顶部从该规则的活跃告警里选一条作样本，超过 20 条时可以翻页。 - 预览用的是所选告警的**事件快照**，**不包含表单里尚未保存的修改**；因此要先保存规则、等它产生告警，才能预览新改的配置。 -- 弹窗里点入口再打开目标（新页签）。如果这条告警没有与该入口对应的快照，会提示 `该告警中没有与此入口对应的快照，请选择配置生效后产生的告警`；整条告警都没有快照时提示 `该告警没有调查入口快照，请选择配置生效后产生的告警`。 + +两种方式下都可以在弹窗里点入口打开目标（新页签）。快照方式下，如果这条告警没有与该入口对应的快照，会提示 `该告警中没有与此入口对应的快照，请选择配置生效后产生的告警`；整条告警都没有快照时提示 `该告警没有调查入口快照，请选择配置生效后产生的告警`。 ## 校验与限制 diff --git a/zh/monitors/dashboards/dashboards.mdx b/zh/monitors/dashboards/dashboards.mdx index 3622ccaa..518d5695 100644 --- a/zh/monitors/dashboards/dashboards.mdx +++ b/zh/monitors/dashboards/dashboards.mdx @@ -17,8 +17,9 @@ keywords: ["仪表盘", "Dashboard", "面板", "模板变量", "同环比", "版 页面左侧是与告警规则共用的目录树，右侧是当前目录下的仪表盘。目录的创建、重命名、移动和删除都在树上完成，规则见[文件夹管理](/zh/monitors/folders/folders)。 -- 左侧目录上方输入框的搜索只在**当前目录**内进行；搜索词和页码会保留在页面地址中，链接可以分享，从仪表盘返回列表时也会还原。 -- 页面右上角的 **全局搜索** 则在当前账号所有可读目录里查找仪表盘（只列出您有权读取的目录），不受当前所在目录限制：匹配仪表盘的**标题或描述**，多个关键词用空格分隔；每条结果给出标题、所在目录路径和描述，点击即可打开该仪表盘；结果每页 20 条，请求失败时可以点 **重试**。这个弹窗的搜索状态只存在于弹窗内，关闭即丢弃，也不会写入页面地址。 +- 左侧目录上方输入框的搜索只在**当前目录**内进行；搜索词和页码会保留在页面地址中，链接可以分享，从仪表盘返回列表时也会还原；每页条数的选择则记在浏览器本地，下次打开这个列表时沿用。 +- 页面右上角的 **搜索全部仪表盘** 则在当前账号所有可读目录里查找仪表盘（只列出您有权读取的目录），不受当前所在目录限制：匹配仪表盘的**标题或描述**，多个关键词用空格分隔，关键词最长 128 个字符；每条结果给出标题与所在目录路径（目录较长时会换行完整显示），点击即可打开该仪表盘；结果每页 20 条，请求失败时可以点 **重试**。它不是弹窗，而是就地展开的搜索框，结果出现在它下方的下拉面板里；搜索状态只存在于这个搜索框内，点右侧的 ✕、按 `Esc` 或点击面板外部即关闭，关闭即丢弃，也不会写入页面地址。 +- 打开搜索框但还没输入关键词时，面板会列出**最近打开**的 5 个仪表盘（标题 + 完整目录路径），点击其中一个即可打开，并把它移到列表最前。这份记录只保存在当前账号的浏览器本地，不会上传到服务端，可用 **清除记录** 清空。 - 每行的 **更多** 菜单提供：移动到其他分组、克隆到本分组、克隆到其他分组。克隆会生成一个标题带“副本”后缀的新仪表盘，**不带历史版本**；移动或克隆到其他目录时，您需要对目标目录可读。 ## 新建与保存仪表盘 @@ -205,7 +206,9 @@ keywords: ["仪表盘", "Dashboard", "面板", "模板变量", "同环比", "版 ## 全屏与查询详情 -鼠标悬停在面板标题上时，可以 **编辑**（需管理权限）、**全屏** 或 **重试**。 +鼠标悬停在面板标题上时，可以 **编辑**（需管理权限）、**全屏** 或 **刷新**。 + +- **刷新**：面板查询完成后，悬停操作里会出现该图标，点击立即重新查询该面板。 - 全屏时可以单独修改该面板的时间范围，不影响其他面板。 - 全屏时可以 **复制面板链接** 或 **下载数据 CSV**。 @@ -268,3 +271,4 @@ keywords: ["仪表盘", "Dashboard", "面板", "模板变量", "同环比", "版 | 保留的历史版本 | 20 | | 回收站保留时长 | 30 天 | | 单个仪表盘定义 | 1 MiB | +| 搜索全部仪表盘的关键词长度 | 128 个字符 | diff --git a/zh/monitors/data-sources/data-sources.mdx b/zh/monitors/data-sources/data-sources.mdx index 71476538..24590f21 100644 --- a/zh/monitors/data-sources/data-sources.mdx +++ b/zh/monitors/data-sources/data-sources.mdx @@ -41,7 +41,7 @@ Monitors 支持以下 15 种数据源类型： - **关联告警引擎**：负责查询的引擎集群及其在线状态 - **启用数据源**：开启或停用该数据源，见[启用与告警评估](#启用与告警评估) -可以按名称、类型、连接地址或备注搜索。列表每 5 秒自动刷新引擎连接状态。 +可以按名称、类型、连接地址或备注搜索。列表每 5 秒自动刷新引擎连接状态。每页条数的选择记在浏览器本地，下次打开这个列表时沿用。 ## 数据源权限（团队授权） diff --git a/zh/monitors/engine/engine-lost-alert.mdx b/zh/monitors/engine/engine-lost-alert.mdx index d6029fea..e37ffba3 100644 --- a/zh/monitors/engine/engine-lost-alert.mdx +++ b/zh/monitors/engine/engine-lost-alert.mdx @@ -14,7 +14,7 @@ keywords: ["引擎失联", "告警引擎", "monitedge", "失联告警", "健康 ## 告警规则列表 -列表展示已配置的规则及其主要参数（含义见下文 [新建告警规则](#新建告警规则)），支持按关键字搜索、自定义显示列，并可用开关直接启用或禁用规则。 +列表展示已配置的规则及其主要参数（含义见下文 [新建告警规则](#新建告警规则)），支持按关键字搜索、自定义显示列，并可用开关直接启用或禁用规则。每页条数的选择，以及列的显隐与顺序，都记在浏览器本地，下次打开这个列表时沿用。 ## 新建告警规则 diff --git a/zh/monitors/engine/engine.mdx b/zh/monitors/engine/engine.mdx index 37b77446..89abc0ce 100644 --- a/zh/monitors/engine/engine.mdx +++ b/zh/monitors/engine/engine.mdx @@ -12,7 +12,7 @@ keywords: ["告警引擎", "monitedge", "引擎安装", "引擎状态", "API Key ## 告警引擎状态 -展示所有已注册的告警引擎实例信息，列表每 5 秒自动刷新。 +展示所有已注册的告警引擎实例信息，列表每 5 秒自动刷新。每页条数的选择记在浏览器本地，下次打开这个列表时沿用。 | 列信息 | 说明 | |--------|------| diff --git a/zh/monitors/explore/explore.mdx b/zh/monitors/explore/explore.mdx index 0248a752..e426a65f 100644 --- a/zh/monitors/explore/explore.mdx +++ b/zh/monitors/explore/explore.mdx @@ -38,7 +38,7 @@ keywords: ["查询工作台", "Explore", "即时查询", "Prometheus", "Loki", " - **Prometheus**：上下分屏，上方折线图（Graph）、下方原始样本（Raw），支持拖拽分隔。 - **其他数据源**：单结果区，根据查询类型展示日志视图、表格视图或样本视图。 -样本视图每页 20 条；表格视图默认每页 100 条，可切换为 200 或 500 条。 +样本视图默认每页 20 条；表格视图默认每页 100 条，可切换为 200 或 500 条。两类视图的每页条数由浏览器记住，刷新页面或重新查询后仍沿用上次的选择。 ### 图表功能 diff --git a/zh/monitors/folders/folders.mdx b/zh/monitors/folders/folders.mdx index d75b9bc3..7f06756f 100644 --- a/zh/monitors/folders/folders.mdx +++ b/zh/monitors/folders/folders.mdx @@ -29,6 +29,23 @@ Monitors 使用树形文件夹结构来组织和管理告警规则。每条告 | **更新时间** | 最后修改时间 | | **创建时间** | 创建时间 | +## 移动规则到其他文件夹 + +您可以把告警规则移到别的文件夹。规则本身不变，只是换了归属。 + +- **单条规则**：点击行尾 `⋮` 菜单里的 **移动**。 +- **多条规则**：勾选规则后，点击列表上方的 **移动**。 + +两种入口都打开 **移动到其他分组** 对话框： + +| 操作 | 说明 | +|------|------| +| **搜索分组** | 输入关键词按名称过滤文件夹树，命中结果保留完整层级路径 | +| 选择文件夹 | 在树里点击目标文件夹 | +| **确定** | 选中的就是规则当前所在的文件夹时，按钮保持禁用 | + +文件夹树加载失败时会显示 `加载分组失败` 和 **重试**。移动成功后提示 `移动成功`，列表自动刷新；失败时提示 `移动失败`，规则仍留在原文件夹。 + ## 团队访问控制 文件夹支持基于团队的访问控制，通过为文件夹绑定团队来限制操作权限。 diff --git a/zh/monitors/quickstart/quickstart.mdx b/zh/monitors/quickstart/quickstart.mdx index ce6605bb..bbe57fb3 100644 --- a/zh/monitors/quickstart/quickstart.mdx +++ b/zh/monitors/quickstart/quickstart.mdx @@ -237,9 +237,9 @@ Go 模板可以使用以下变量： | **添加仪表盘入口** | 选择仪表盘并可定位到整个仪表盘、某个标签页、分组或图表，同时为该仪表盘的模板变量指定取值 | | **添加查询入口** | 保存一份初始查询（数据源 + 查询类型 + 查询语句 + 查询参数），默认在告警事件自己的数据源上执行 | | **调查用途** | 一句话说明这个入口帮助确认什么，可选 | -| **时间范围** | 「告警前 N 分钟，至告警后 M 分钟」，以告警事件时间为锚点，默认告警前 60 分钟、告警后 0 分钟 | +| **时间范围** | 「告警前 N 分钟，至告警后 M 分钟」，以告警事件时间为锚点，默认告警前 60 分钟、告警后 30 分钟 | -最多 20 个入口，可以拖动调整顺序（顺序只影响展示）；点击入口右侧的眼睛图标可以按该规则的一条真实告警**预览跳转**。入口随规则保存生效，渲染成快照后随告警事件下发，因此改规则不会影响已经产生的告警。 +最多 20 个入口，可以拖动调整顺序（顺序只影响展示）；点击入口右侧的眼睛图标可以**预览跳转**：不使用模板变量的入口按当前表单配置和当前时间预览，使用模板变量的入口按该规则的一条真实告警快照预览。入口随规则保存生效，渲染成快照后随告警事件下发，因此改规则不会影响已经产生的告警。 <Warning> 保存调查入口需要集群内所有告警引擎实例为 `v0.75.3` 或以上版本，否则保存会被拒绝。 @@ -326,7 +326,9 @@ Go 模板可以使用以下变量： ### 批量移动 -勾选多条规则后，可以将它们批量移动到其他文件夹中。 +勾选多条规则后，点击列表上方的 **移动**，将它们批量移动到其他文件夹。只移动一条时，点击该行行尾 `⋮` 菜单里的 **移动**。 + +两种入口都打开 **移动到其他分组** 对话框：在树里选择目标文件夹，或先在 **搜索分组** 框里按名称过滤；选中的就是当前文件夹时 **确定** 保持禁用。成功后提示 `移动成功` 并刷新列表。详见[文件夹管理](/zh/monitors/folders/folders)。 ## 导入告警规则 diff --git a/zh/rum/error-tracking/error-viewing.mdx b/zh/rum/error-tracking/error-viewing.mdx index a632d08b..0a1f32f7 100644 --- a/zh/rum/error-tracking/error-viewing.mdx +++ b/zh/rum/error-tracking/error-viewing.mdx @@ -40,7 +40,7 @@ Issue 列表支持按**优先级**排序，筛选条件默认包含「优先级 ## Issue 状态 -Issue 有待处理、处理中、已解决和已忽略 4 种状态，流转规则见 [Issue 状态](./issue-status)。 +Issue 有待处理、处理中、已解决和已忽略 4 种状态；其中已解决按复现后的处理方式分为「已解决」与「在下一版本中解决」两种，可在状态下拉中切换。流转规则见 [Issue 状态](./issue-status)。 ## 筛选与排序 @@ -129,7 +129,7 @@ Flashduty 在创建 Issue 时为其标注可能的错误原因分类，用于缩 ## 问题复现 -已解决的 Issue 在不同版本再次出现时会重新打开，并标记为问题复现。触发条件见 [Issue 状态](./issue-status)。 +已解决的 Issue 再次出现时会重新打开，并标记为问题复现：解决方式为「已解决」时任何再次出现都会重开（同一版本也算），为「在下一版本中解决」时只有新版本再次出现才重开。详见 [Issue 状态](./issue-status#解决方式)。 ## Issue 详情 @@ -231,6 +231,17 @@ Issue 列表支持两种查看模式：侧栏模式和全屏模式。默认以 </Accordion> </AccordionGroup> +### 头部操作 + +Issue 详情面板右上角提供两个 AI SRE 相关的按钮，只在账户已开启 AI SRE 时显示： + +| 按钮 | 显示条件 | 作用 | +|------|----------|------| +| **开启自动分析** | 当前成员有创建 AI SRE 自动化规则的权限 | 打开 AI SRE 自动化的创建表单，预填预设模板「RUM Issue 故障分析」与该应用的告警协作空间；保存后，这条自动化负责分析该应用后续由 Issue 告警生成的故障 | +| **AI 修复** | 当前成员有 AI SRE 会话的访问权限 | 打开 AI SRE 会话，并把当前 Issue 作为引用标签带进输入框，见[会话 · 附件与上下文引用](/zh/ai-sre/sessions#附件与上下文引用) | + +**开启自动分析** 以故障为触发条件，所以该应用要先能产生故障。点击按钮时，RUM 会读取该应用的告警设置：告警已开启、投递方式为 **Flashduty 协作空间**、且至少选了一个协作空间时，才直接跳到创建表单，协作空间已按应用的告警配置选好，确认后点 **创建** 即可。不满足时提示「该应用还没开启 On-call 告警。异常要先生成故障才能触发自动分析，请先完成告警设置。」，并跳到该应用的 **告警设置** 页签。模板内容与表单字段见[自动化](/zh/ai-sre/automations)。 + ## 异常告警 在「应用管理」中编辑应用，开启「告警」并选择协作空间或 Webhook。配置方法见 [Issue 告警](./issue-alerts)。 diff --git a/zh/rum/error-tracking/issue-alerts.mdx b/zh/rum/error-tracking/issue-alerts.mdx index 06c374b0..4652f94a 100644 --- a/zh/rum/error-tracking/issue-alerts.mdx +++ b/zh/rum/error-tracking/issue-alerts.mdx @@ -178,6 +178,8 @@ RUM 告警依次经过数据过滤、告警分级、告警处理和告警分派 选择 Flashduty 协作空间投递时，您可以在 Flashduty 的[告警处理 Pipeline](/zh/on-call/integration/alert-integration/alert-pipelines) 中进一步处理 RUM 告警，例如根据影响用户数调整告警级别、按时间窗口抑制重复告警、自定义告警标题格式等。选择 Webhook 投递时，RUM 告警不会进入这条 On-call 处理链路，请在您的接收端完成格式转换、路由和通知。 +Issue 详情页的[开启自动分析](/zh/rum/error-tracking/error-viewing#头部操作)以故障为触发条件，而只有 Flashduty 协作空间投递才会由 Issue 告警生成故障，所以它只对协作空间投递的应用生效：Webhook 投递不产生故障，无法触发这条自动化。 + ## 延伸阅读 <CardGroup cols={2}> diff --git a/zh/rum/error-tracking/issue-status.mdx b/zh/rum/error-tracking/issue-status.mdx index 56966aee..1039d670 100644 --- a/zh/rum/error-tracking/issue-status.mdx +++ b/zh/rum/error-tracking/issue-status.mdx @@ -13,7 +13,7 @@ keywords: ["RUM", "异常追踪", "用户监控", "前端监控"] | **待处理** | 需要关注的新问题或复现的问题 | | **处理中** | 已分类且需要修复的问题，可立即或稍后处理 | | **已忽略** | 不需要进一步调查或处理的问题 | -| **已解决** | 已修复且不再发生的问题 | +| **已解决** | 已修复且不再发生的问题；按复现后的处理方式分为**已解决**与**在下一版本中解决**两种（见[解决方式](#解决方式)） | <Info> 所有新发现的 Issue 初始状态为**待处理**。Flashduty 会根据特定条件自动更新状态，您也可以手动调整。 @@ -38,18 +38,21 @@ Flashduty 会自动将不活跃或已解决的 Issue 标记为**已解决**： ## 自动重新打开 Issue -Flashduty 具备 Issue 检测功能，当已解决的 Issue 再次出现时，系统会自动重新打开并标记为**待处理**状态，并添加**问题复现**标签。 +Flashduty 具备 Issue 检测功能，当已解决的 Issue 再次出现、且满足该 Issue **解决方式**设定的条件时，系统会自动重新打开并标记为**待处理**状态，并添加**问题复现**标签。 ### 什么是问题复现？ -复现指的是先前已修复的问题在代码更新后意外重新出现。Flashduty 的回归检测可自动识别这些情况，将相关 Issue 重新打开，而不是创建重复的 Issue，从而保留问题的完整上下文和历史记录。 +复现指的是先前已修复的问题再次出现，常见场景是代码更新后意外回归。Flashduty 的回归检测可自动识别这些情况，将相关 Issue 重新打开，而不是创建重复的 Issue，从而保留问题的完整上下文和历史记录。 ### 复现检测机制 +错误被聚合进**已解决**的 Issue 时，是否判定为复现取决于该 Issue 的**解决方式**（见下文[解决方式](#解决方式)）： + <Warning> -当满足以下任一条件时，复现检测将被触发： -- 如果**已解决**的错误在代码的更新版本中重新出现 -- 如果在未设置版本标签的情况下，**已解决**状态的错误再次出现 +- 解决方式为**在下一版本中解决**（默认）：只有该 Issue 之前未出现过的新版本中再次出现才触发检测 +- 解决方式为**已解决**：任何再次出现都触发检测，同一版本内的重复出现同样算复现 +- 错误未携带 `version` 标签时，两种解决方式都会触发检测 +- 错误的发生时间早于该 Issue 的解决时间时不会触发（重复上报，或 SDK 离线缓存后补传的旧错误） </Warning> 一旦检测到问题复现，Flashduty 会： @@ -65,7 +68,7 @@ Flashduty 具备 Issue 检测功能，当已解决的 Issue 再次出现时， ### 关联版本配置 -复现检测会考虑错误发生的服务版本信息，只有在 Issue 标记为**已解决**后的新版本中才会触发检测。 +复现检测会考虑错误发生的服务版本信息：解决方式为**在下一版本中解决**（默认）时，只有在 Issue 标记为**已解决**之后的、之前未出现过的新版本中才会触发检测；解决方式为**已解决**时不比较版本，同一版本中再次出现也会触发。 ```javascript window.FC_RUM.init({ @@ -81,6 +84,20 @@ window.FC_RUM.init({ 如果不设置版本标签，当已解决的 Issue 再次发生错误时，系统仍会将其标记为「问题复现」，但无法确定是否在新版本中发生。 </Note> +## 解决方式 + +在状态下拉里，**已解决**按「该错误再次出现时如何处理」拆成两个选项，两者的状态都是已解决： + +| 下拉选项 | 复现时的行为 | +|------|------| +| **已解决** | 之后再出现就重新打开：同一版本内的再次出现同样会重开 | +| **在下一版本中解决** | 只有新版本再出现才重新打开：仅该 Issue 之前未出现过的新版本中再次出现才重开 | + +- 两个选项可随时在状态下拉里互相切换；只切换解决方式不改动 Issue 的统计数据，也不改变告警状态。 +- 新建 Issue 默认是**在下一版本中解决**，系统自动解决 Issue 时也使用这一方式。 +- 错误未携带 `version` 标签时，两种解决方式都会重开：没有版本信息就无从区分修复前后的代码。 +- 重开时 Issue 会被置为**待处理**并标记「问题复现」，同时记录复现发生的时间与版本。列表中状态单元格受宽度限制，两种解决方式都显示为**已解决**；详情面板会在**已解决**旁额外标出「在下一版本中解决」。 + ## 手动更新状态 您可以在任何显示 Issue 的地方手动更新其状态，包括 Issue 列表或详情面板。 @@ -89,7 +106,7 @@ window.FC_RUM.init({ <img src="https://docs-cdn.flashcat.cloud/images/png/a57c54a6a28915dec4480a9db9411e30.png" alt="手动更新状态" style={{maxWidth: "600px", margin: "0 auto", display: "block"}} /> </Frame> -只需点击当前状态，然后从下拉菜单中选择新状态即可。 +只需点击当前状态，然后从下拉菜单中选择新状态即可。下拉中共 5 个选项：**待处理**、**处理中**、**已解决**、**在下一版本中解决**、**已忽略**；两个「已解决」选项下方会显示各自的重开说明，区别见[解决方式](#解决方式)。 ## 最佳实践 diff --git a/zh/rum/explorer/data-query.mdx b/zh/rum/explorer/data-query.mdx index 2ab56340..f96e055e 100644 --- a/zh/rum/explorer/data-query.mdx +++ b/zh/rum/explorer/data-query.mdx @@ -94,6 +94,7 @@ RUM 查看器的查询由**词项**（terms）和**操作符**（operators）组 |----------|------| | `browser_name:Chrome` | 检索值为 `Chrome` 的浏览器 | | `view_name:*/detail` | 检索以 `/detail` 结尾的视图名称 | +| `browser_name:*` | 检索包含该字段的事件：`*` 单独作为整个值表示字段存在，不是通配符 | | `-resource_status_code:0` | 检索状态码不为 `0` 的资源 | | `os_name:"Mac OS X"` | 检索值为 `"Mac OS X"` 的系统名称 | @@ -204,7 +205,7 @@ session_sampled_for_error:true 检索移动设备上加载时间超过 3 秒的视图： ``` - device_type:mobile view_loading_time:>3s + device_type:Mobile view_loading_time:>3s ``` </Accordion> <Accordion title="地理位置检索"> diff --git a/zh/rum/quickstart/app-management.mdx b/zh/rum/quickstart/app-management.mdx index cdfb179e..2cc8a9d3 100644 --- a/zh/rum/quickstart/app-management.mdx +++ b/zh/rum/quickstart/app-management.mdx @@ -27,6 +27,8 @@ RUM 应用是承载前端性能监控数据的容器，用于采集、存储和 私有应用中，其他成员若需查看内容，可以通过分享故障链接的方式临时授权访问。 </Note> +除可见范围外，这层读权限还会落到数据查询上：查看器的查询与数据查询接口返回的事件数据同样按应用读权限过滤。如果查询中显式点名了您读不到的应用，整批查询会直接失败，而不是只丢弃那部分数据；如果查询没有点名任何应用，服务端会自动从结果中排除您读不到的应用（私有应用中您既不是创建者、也不在其管理团队内的那些）。账户所有者与账户管理员可以读取账户内的全部应用，因此对他们不会有任何数据被排除。单次请求最多可点名 50 个应用，超过上限时整批查询返回参数错误。 + ## 创建应用 <Frame caption="RUM 应用创建界面"> From 9d07a2cc28bda946ba5d412e1ba0931a07a0ee64 Mon Sep 17 00:00:00 2001 From: ysyneu <ysyneu@gmail.com> Date: Sat, 17 Oct 2026 03:43:19 -0700 Subject: [PATCH 4/5] docs(developer,openapi): add new CLI/SDK commands and APP key exposure steps --- en/developer/cli.mdx | 83 ++++++++++++++++++++++++++++++------- en/developer/go-sdk.mdx | 32 +++++++++++++- en/openapi/api-catalog.mdx | 2 +- en/openapi/introduction.mdx | 16 +++++++ zh/developer/cli.mdx | 83 ++++++++++++++++++++++++++++++------- zh/developer/go-sdk.mdx | 32 +++++++++++++- zh/openapi/api-catalog.mdx | 2 +- zh/openapi/introduction.mdx | 16 +++++++ 8 files changed, 232 insertions(+), 34 deletions(-) diff --git a/en/developer/cli.mdx b/en/developer/cli.mdx index 453e0ad8..acc117e1 100644 --- a/en/developer/cli.mdx +++ b/en/developer/cli.mdx @@ -18,7 +18,7 @@ The tool is open source at [flashcatcloud/flashduty-cli](https://github.com/flas curl -sSL https://static.flashcat.cloud/flashduty-cli/install.sh | sh ``` -Installs to `/usr/local/bin` by default. Override with the `FLASHDUTY_INSTALL_DIR` environment variable. +Installs to the directory of the `flashduty` already on your `PATH` by default, so an upgrade replaces that copy in place; when there is no `flashduty` on `PATH`, it installs to `/usr/local/bin`. Override the directory with the `FLASHDUTY_INSTALL_DIR` environment variable. </Tab> <Tab title="Windows (PowerShell)"> @@ -39,13 +39,15 @@ Read the latest version from the [CDN latest version pointer](https://static.fla | Variable | Description | Default | |----------|-------------|---------| | `FLASHDUTY_VERSION` | Install a specific version, for example, `v1.5.12` | latest | -| `FLASHDUTY_INSTALL_DIR` | Custom install directory | `/usr/local/bin` (shell), `~\.flashduty\bin` (PowerShell) | +| `FLASHDUTY_INSTALL_DIR` | Custom install directory | the directory of the `flashduty` already on `PATH`, else `/usr/local/bin` (shell); `~\.flashduty\bin` (PowerShell) | | `MIRROR_URL` | Override the release asset download mirror prefix used by the installer script; must use `https://` | `https://static.flashcat.cloud/flashduty-cli` | | `FLASHDUTY_UPDATE_BASE_URL` | Override the base URL used by `flashduty update` and the automatic update check | `https://static.flashcat.cloud/flashduty-cli` | | `INSTALLED_NAME` | Command name to install as, for example, `fduty` | `flashduty` | A copy installed under another command name uses that name in help output, error messages, and shell completion scripts; `flashduty update` replaces the running binary in place, under its own name and directory, instead of installing a default-named copy elsewhere. +After installing, the script re-checks `PATH`: if the `flashduty` your shell actually runs is not the copy it just installed (an older copy earlier on `PATH` shadows it), it tells you to remove that copy or move the new directory ahead of it. When the current process is managed by flashduty-runner (`FLASHDUTY_MANAGED_BY_RUNNER=1`), the script refuses to run and tells you to upgrade the runner instead — the runner ships a CLI copy it was built and verified against, and replacing it in place desyncs the two. + ## Authentication ### Log in @@ -94,14 +96,16 @@ flashduty config set base_url URL # Override the API endpoint ## Global flags -All subcommands accept these flags: +These flags are registered on the root command; every subcommand accepts them except `--version`: | Flag | Description | |------|-------------| | `--output-format` | Output format: `table` (default), `json`, or `toon` (compact, token-efficient) | | `--json` | Alias for `--output-format json`; emit JSON for parsing with `jq` or similar tools | | `--no-trunc` | Disable column truncation in table output | +| `--fields` | In `json`/`toon` output, keep only the named top-level fields (comma-separated): each row of a list, or the keys of a single record. Table output ignores it and a stderr note says so; a name that matches no key is reported on stderr together with the keys the output does carry, and output that is neither an object nor a list of objects fails the command. See "Field projections for structured output" below | | `--base-url` | Override the API endpoint (for private deployments) | +| `--version` | Print the version — the same single line as `flashduty version`. That meaning exists only on the root command; a command that defines its own `--version` (for example the optimistic-locking version on mutating verbs) follows its own description | ## Command catalog @@ -116,7 +120,7 @@ flashduty incident ack <id> [<id2>...] # Acknowledge incidents flashduty incident close <id> [<id2>...] # Close (resolve) incidents flashduty incident merge <target-id> --source <ids> # Merge incidents into a target incident flashduty incident timeline <id> # View an incident timeline -flashduty incident alerts <id> # List alerts associated with an incident +flashduty incident alerts <id> # List alerts associated with an incident (--limit default 10, --page) flashduty incident similar <id> # Find similar historical incidents flashduty incident feed <id> [flags] # View an incident's paginated feed (timeline entries) ``` @@ -141,7 +145,7 @@ Common filter flags for `incident list`: | `--is-rare` | Only outlier incidents | `false` | | `--is-snoozed` | Only snoozed incidents | `false` | | `--ever-muted` | Only incidents that were ever silenced | `false` | -| `--since` | Start time (duration, date, datetime, or unix timestamp); the `--since` to `--until` window must be under 31 days | `24h` | +| `--since` | Start time (duration, date, datetime, or unix timestamp); the `--since` to `--until` window must be under 31 days | `24h` (`30d` when `--progress` lists only `Triggered,Processing`) | | `--until` | End time | `now` | | `--asc` | Sort ascending (oldest first) | `false` (newest first) | | `--limit` | Max results (max 100) | `20` | @@ -151,6 +155,8 @@ Time format examples: `5m`, `1h`, `24h`, `168h`, `2026-04-01`, `2026-04-01 10:00 `incident feed <id>` reads an incident's feed (timeline entries) page by page. `--asc` lists the oldest entries first (the default is newest first). `--types` filters by comma-separated entry types, for example `i_comm,i_assign`; each entry's `type` field gives its actual type. `--limit` (max 100) and `--page` paginate the result. +`incident alerts <id>` lists the alerts attached to that incident; `--limit` defaults to `10` and `--page` starts at `1`. + #### Create, update, and merge `incident create` requires `--title` (3–200 characters) and `--severity`, and prompts for missing values in a terminal. There are three ways to assign people, which can be combined: `--assign` (member IDs), `--assign-emails` (member emails, comma-separated; emails that match no member are ignored), and `--escalate-rule-id` with `--escalate-layer` (assign the people at that zero-based layer of the escalation rule; `--escalate-layer` requires `--escalate-rule-id`). @@ -185,6 +191,8 @@ flashduty incident work-item-post-mortem-bind [flags] # Bind converte Key flags for `work-item-create`: `--item-type` (required, `action` or `follow_up`), `--title` (required, up to 512 characters), `--idempotency-key` (required idempotency key, up to 128 characters), `--post-mortem-id` (required for `follow_up`, forbidden for `action`), `--assignee-ids` (initial assignees, a legacy alias). Mutating verbs (`update`/`complete`/`convert`/`delete`/`assignees-reset`) require `--version` (optimistic locking — it must match the stored version). +A work item's status accepts only four values — `open`, `in_progress`, `done`, `cancelled`: `work-item-create --status` defaults to `open` when omitted or blank, `work-item-update --status` can only move it to one of those four, `work-item-complete --target-status` accepts `done` alone (any other value is rejected), and `work-item-convert --target-status` takes one of the four. + A work item's assignees can be members or the account's **AI SRE**: - `work-item-create` and `work-item-assignees-reset` accept an `assignees` field (each entry shaped `{type, id?}`, where `type` is `person` or `ai_sre`; an `ai_sre` entry carries no `id`, and at most 20 entries are allowed), which can only be passed as JSON through `--data`. `--assignee-ids` is the equivalent legacy alias (an all-`person` list); the two are mutually exclusive and sending both returns an error. @@ -492,7 +500,25 @@ flashduty rum resource-info [--no-cache] # View the RUM plan version, quotas, flashduty oncall license-list # List people with active On-call licenses in the current account ``` -This read-only command returns each person's ID, name, and license type: `fixed` is explicitly assigned, while `temporary` is active for the current temporary-license window. +This read-only command returns each person's ID, name, and license type: `fixed` is explicitly assigned, while `temporary` is active for the current temporary-license window. The response also carries `release_limited`, which is `true` once the account has used up its license-release quota for the current billing period; while it is `true`, releasing a member's seat fails with the error code `NoLicense`. That quota is the [limit on the number of License releases in each billing period](/en/platform/pricing). + +### calendar — Service calendars + +A service calendar is what escalation rules and silence rules use to tell working days from rest days; the console-side configuration and layer precedence are described in [Service Calendar](/en/on-call/configuration/service-calendar). The group is generated from the OpenAPI (see "Full command coverage" below): `<cal-id>` (shaped `cal.<uuid>`) is positional and comes from the `cal_id` of the `items[]` rows returned by `calendar list`; `list` returns account-created calendars only, so pass `--kind region.official.holiday` for public-holiday calendars (they are filtered by the caller's locale unless you add `--no-locale`). + +```bash +flashduty calendar list [--kind personal|region.official.holiday] [--no-locale] # List calendars +flashduty calendar info|update|delete <cal-id> # Get / update / delete a calendar +flashduty calendar event-list <cal-id> [--year <y>] [--month <m>] [--day <d>] # List events; the response also carries days +flashduty calendar event-upsert <cal-id> --start-at <date> --end-at <date> --is-off <bool> [--event-id <id>] [--summary <text>] +flashduty calendar event-delete <cal-id> [--event-id <id> | --start-at <date> --end-at <date>] +``` + +Three things only `--help` and the responses themselves reveal: + +- **`event-delete` both deletes a single event and clears a date range.** Pass `--event-id` to delete one event, or `--start-at` and `--end-at` (both `YYYY-MM-DD`; `end_at` is exclusive and must be later than `start_at`) to clear every event the calendar itself holds over `[start_at, end_at)`. The cleared days fall back to the linked holiday calendars and the weekly workdays — the same effect as clicking **Reset to default** on those dates in the console. +- **`event-upsert` trims the calendar's other own events off the same days**: an event fully inside the range is deleted, one partly inside is shortened, and one spanning the range is split in two, so the latest write decides those days (`--summary` is optional). +- **The `event-list` response carries `days` beside the `items` row array**: keyed by `YYYY-MM-DD`, it gives every day in the requested scope its `is_off`, the `event_id` that decided it, and the `layer` that decided it — `custom` (the calendar's own events) beats `holiday` (a linked holiday calendar), which beats `weekly` (the weekly workdays); inside one layer a working-day event beats a rest day; a missing `layer` means no event covers that day, which counts as a working day. Read `days` to tell whether a day is a rest day; do not infer it from `items`, since one day can hold events from several layers. ### template — Notification templates @@ -629,12 +655,17 @@ Core fields for `datasource-create` / `datasource-update`: - `kafka`: `sasl_mechanism` (`none` default / `plain` / `scram-sha-256` / `scram-sha-512`, the latter three require username and password), `username` / `password`, `timeout_ms` (default 5000), TLS fields (`tls_min_version` defaults to 1.2, max 1.3). - Passwords and `kafka.tls_key` support `${env:NAME}` references (resolved on the edge); literal values are omitted from responses, only `${env:...}` references are echoed. **On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear**. -#### Dashboards and rule folders (dashboard-* / folder-list) +#### Dashboards and rule folders (dashboard-* / folder-*) The `monit dashboard-*` family manages monitor dashboards (provided by generated OpenAPI commands). A dashboard is a `dashboard.v1` document: pass the `definition` in `--data` when creating or updating. `update`, `delete`, `move`, and `restore` all require `--expected-revision` — if the revision you send is not the current one, the call is rejected with `DashboardRevisionConflict`, so re-read and submit again. ```bash flashduty monit folder-list # List every monitor rule folder, to get a folder-id (top-level array, use jq '.[]') +flashduty monit folder-health # Read folder health summaries, including issues in descendant folders (paged envelope, use jq '.items[]') +flashduty monit folder-create --name <folder-name> [flags] # Create a folder (--name required, no . / ,; --parent-id parent folder, 0 = root; --note note; --team-id team, 0 = account-wide) +flashduty monit folder-update --id <folder-id> --name <folder-name> # Update a folder's name, note, and team assignment (--id and --name required) +flashduty monit folder-move <dest-parent-id> --id <folder-id> # Move a folder and its descendants (dest-parent-id is positional and always required; 0 moves it to the root) +flashduty monit folder-delete --id <folder-id> # Delete a folder (empty folders only: child folders, rules, or dashboards make the call fail) flashduty monit dashboard-list <folder-id> # List the dashboards in one folder (paged envelope, use jq '.items[]') flashduty monit dashboard-search --query "payments" # Search dashboards by title and description (at least one word) flashduty monit dashboard-get <dashboard-id> # Read a dashboard, including its definition and current revision @@ -654,6 +685,8 @@ flashduty monit dashboard-runtime-variables-preview # Preview draf flashduty monit dashboard-runtime-queries-resolve <panel-id> [<id2>...] # Resolve panel queries: expressions with variables substituted, and the bound datasource ``` +The `monit folder-*` commands manage the folders themselves. `folder-health` returns a `{items:[...]}` paged envelope in which each entry carries only `folder_id` and `has_issue` (`has_issue` marks a folder whose visible descendants include active alerts or rule runtime issues), and `folder-list` returns a top-level array — read both with `--json | jq`. `folder-create` and `folder-update` return the updated folder object; `folder-move` and `folder-delete` return no folder object. A folder name may not contain `.`, `/`, or `,`. `folder-move` requires `dest-parent-id` even when moving to the root (`0`), and `folder-delete` accepts only an empty folder — child folders, rules, or dashboards inside it make the call fail, so empty it yourself first. + Panel runtime and variable resolution take their time window and variable selections as JSON objects in `--data` (time uses millisecond `from_ms` / `to_ms` timestamps). `dashboard-panel-preview` and `dashboard-runtime-variables-preview` need a `context`: `kind: existing` with a `dashboard_id` targets a stored dashboard, `kind: new` with a `folder_id` targets a folder that does not hold one yet. `dashboard-runtime-queries-resolve` takes two further flags that shape the result: `--max-data-points` (int, 2–5000; both the downsampling target and what decides the step the built-in time variables render with — omit it or send `null` for the server default of 100) and `--preserve-builtin-variables` (bool, off by default): when set, the **built-in time variables** stay verbatim in the resolved expressions so a caller with its own execution window can render them, while user variables are still resolved. The sibling commands `dashboard-panel-run` and `dashboard-panel-preview` already carried `--max-data-points`, likewise a 2–5000 downsampling target. @@ -681,8 +714,9 @@ This command only reads the value set of one label; to fetch time series from an ### alert — Alert and alert-event queries ```bash -flashduty alert list [flags] # List alerts (default: last 24h) +flashduty alert list [flags] # List alerts (default: last 24h; 30d with --active) flashduty alert get <alert_id> # Get full detail of one alert; detail is an alias +flashduty alert events <alert_id> # List the raw events that make up one alert (--limit, --page) flashduty alert-event list [flags] # List alert events (default: last 1h) ``` @@ -695,6 +729,10 @@ Common filter flags for both `list` commands: `--severity` (`Critical,Warning,In - `--asc`: sort oldest first by start time (the default is newest first). - `--by-updated-at`: apply `--since`/`--until` to the last-updated time instead of the start time. `alert-event list` also supports `--asc` (oldest first; newest first by default), but has no `--by-updated-at` counterpart. +`alert list` also filters by state through `--active` (active alerts only) and `--recovered` (recovered alerts only). They are mutually exclusive — passing both is an error — and passing neither applies no state filter. Active alerts can be older than a day, so with `--active` and no `--since` the window widens to 30 days by default (the window actually sent is reported by the stderr note). + +`alert events <alert_id>` lists the raw events that make up one alert: leave `--limit` unset to take the server default of 20 (max 100), and `--page` starts at 1. It reads events for a single alert; for a time-window query across alerts use `alert-event list`. + ### automation — AI SRE automation rules The `automation` command group manages AI SRE automation rules — create, query, update, delete, run history, and triggering. See [Automations](/en/ai-sre/automations) for the console workflow. @@ -715,11 +753,12 @@ Common `create` flags: | Flag | Notes | |------|-------| | `--name` | Rule name (required) | -| `--team-id` | Scope team ID; `0` means personal scope (default). The scope is immutable after creation | +| `--team-id` | Scope team ID; an explicit `0` means personal scope and `>0` means that team; when omitted the field is not sent, so the server inherits the authenticated IM conversation's scope when one is available and otherwise applies its normal default. With `--run-in current-chat`, the team ID you pass must match that conversation's scope — it cannot switch the conversation to a different personal or team scope. The scope is immutable after creation | +| `--run-in` | Execution destination: `current-chat` binds the rule to the current IM conversation, `web` runs it in the web console. When omitted the server decides — it selects `current-chat` for an authenticated IM invocation and `web` otherwise. The server rejects `current-chat` outside a live IM conversation | | `--schedule` | Schedule helper: `hourly`, `daily`, `weekly`, or `cron`; defaults to `daily` when omitted | | `--at` | `HH:MM` local time (in the rule's timezone); for `hourly` only the minute is used (default 0), for `daily`/`weekly` both hour and minute (default 09:00) | | `--weekday` | Weekday for `weekly`: `sun`–`sat` or `0`–`7` (`0` and `7` both mean Sunday; defaults to Monday) | -| `--cron-expr` | Exact 5-field cron expression (interpreted in the rule's timezone); overrides the `--schedule` helpers | +| `--cron-expr` | A supported 5-field cron expression (interpreted in the rule's timezone); overrides the `--schedule` helpers. The minute must be a fixed `0`–`59` integer, so the fastest schedule is hourly; minute wildcards, ranges, lists, and steps are unsupported, and expressions such as `*/15 * * * *` or `0,30 * * * *` are rejected | | `--timezone` | IANA timezone name (for example, `Asia/Shanghai`) that `--at` and `--cron-expr` are interpreted in; when omitted the server uses the caller's member timezone, then the account timezone, then `Asia/Shanghai`. A timezone the server cannot load is rejected | | `--disabled` | Create the rule disabled (enabled by default) | | `--schedule-enabled` | Whether the schedule trigger is enabled (default `true`) | @@ -727,7 +766,9 @@ Common `create` flags: | `--prompt` / `--prompt-file` | Task prompt, exactly one required; `--prompt-file` reads from a file (`-` for stdin) | | `--environment-kind` / `--environment-id` | Runtime environment: `cloud` or `byoc` (`byoc` requires `--environment-id`); empty means automatic | -`update` accepts `--name`, `--prompt`/`--prompt-file`, `--schedule`/`--at`/`--weekday`/`--cron-expr`/`--timezone`, `--enable`/`--disable`, `--enable-schedule`/`--disable-schedule`, `--enable-http-post-trigger`/`--disable-http-post-trigger`, `--rotate-http-post-token`, and `--environment-kind`/`--environment-id`. The personal/team scope is immutable after creation, so `update` exposes no scope flag. +When you create a rule from an IM conversation, omitting `--run-in` lets the server bind the rule to that conversation and inherit its scope; you neither need to nor should pass a chat, platform, integration, or session ID — the server resolves and authorizes the current conversation. Once bound to a conversation, every ordinary run starts a fresh execution session and, where the IM integration creates threads, a fresh IM thread, and it stays on the conversation and immutable scope captured at creation rather than reusing an old session or thread; a retry of the same run reuses that run's execution identity. If the bound conversation's scope no longer matches the rule when it runs, the run is skipped — the rule is never moved or run in another conversation. War-room Automations keep their existing behavior. Because each run starts from a fresh context, write the prompt so it carries the chat context it needs (the service, the team, the delivery target) and do not refer to "above" or to an earlier session. Like the scope, the execution destination is immutable after creation. + +`update` accepts `--name`, `--prompt`/`--prompt-file`, `--schedule`/`--at`/`--weekday`/`--cron-expr`/`--timezone`, `--enable`/`--disable`, `--enable-schedule`/`--disable-schedule`, `--enable-http-post-trigger`/`--disable-http-post-trigger`, `--rotate-http-post-token`, and `--environment-kind`/`--environment-id`. The personal/team scope and the execution destination (`--run-in`) are both immutable after creation, so `update` exposes neither. `update`'s `--cron-expr` carries the same constraint as `create`: the minute must be a fixed `0`–`59` integer, so the fastest schedule is hourly, and minute wildcards, ranges, lists, and steps are unsupported. `runs` supports `--status` (`queued`/`running`/`retrying`/`succeeded`/`partial`/`failed`/`skipped`/`abandoned`), `--trigger-kind` (server-side values `schedule`/`debug`/`manual`/`http_post`/`oncall_incident`/`war_room_created`, where `war_room_created` is a run triggered by a war room being created), `--since`/`--until`, `--page`, and `--limit`. `fire` authenticates with the trigger's token (`--token`, or the `FLASHDUTY_AUTOMATION_TRIGGER_TOKEN` environment variable); `--text` passes context for the run, and `--data` passes a full JSON request body (inline JSON or `-` to read stdin). @@ -879,6 +920,8 @@ inc_abc123 DB connection timeout Critical Triggered Production 2026 inc_def456 High memory usage Warning Processing Staging 2026-04-10 09:15 Showing 2 results (page 1, total 2). ``` + +A generated command's list response that carries fields beyond the row array (`items` / `docs` / `list`) — for example `calendar event-list`'s `days` or `oncall license-list`'s `release_limited` — prints an extra line after the row table: `Also in the response: <fields> (use --json to see it).` Those fields never appear in the table; use `--json` or `--output-format toon` to read them. </Tab> <Tab title="JSON (--json / --output-format json)"> @@ -906,6 +949,14 @@ Table view with no column truncation — useful for copy-paste or wide terminals </Tab> </Tabs> +### Time-window note + +Commands that query a time range print the window they actually sent to stderr in the local timezone, for example `note: window 2026-10-08T14:00:00+08:00..2026-10-09T14:00:00+08:00 (1d, ended now)`. The parenthesised part carries the span and where the end sits relative to now (`ended 3m ago` / `ends in 2h`); when the window comes from a default rather than from `--since`/`--until` you typed, the note names that default (an `--progress` filter of open states only, or `--active`). + +This covers `incident list`, `alert list`, `alert-event list`, `change list`, `audit search`, `insight`, `oncall`, `monit-query` (when its tool params carry an execution window), and every generated command whose `--start-time`/`--end-time` resolve. A command that leaves one side to `--data` or to the server default prints no note, because the window was never fully resolved by the CLI. A query with a single evaluation timestamp reads `note: instant <time> (…)` instead. + +Use it to catch a window you did not intend: a default wider than you expected (`--active` widens it to 30 days), or an epoch read in the wrong timezone, which lands the window in the future and reads `ends in 7h`. The note goes only to stderr, so stdout stays byte-identical for `jq` and toon consumers. + ### Generated-command output bound Generated commands (the ones covering the OpenAPI through the code generator, such as `safari session-list`, `monit datasource-list`, `safari a2a-agent-list`) apply a 16 KiB bound to **list-shaped** responses in `json`/`toon` mode. The reduction has three tiers, plus a machine-readable marker: @@ -917,15 +968,19 @@ Generated commands (the ones covering the OpenAPI through the code generator, su **A reduced list envelope is rebuilt with the reduction written into the payload.** A list envelope is a response whose row array is named `items`, `docs`, or `list`, and whose other fields are all scalars (`total`, `has_next_page`, `search_after_ctx`, …). Examples are `monit datasource-list` and `safari session-list`. Once a reduction happens, the CLI rebuilds that envelope and adds fields to the payload, so a script sees the reduction without parsing stderr: - **Rows withheld**: the payload carries `truncated: true` together with `emitted_rows: N` (N is the number of rows actually emitted). The envelope's `total`, `has_next_page`, and `search_after_ctx` still describe the page as the server returned it. They **can't** tell you whether you got everything: a page cut to 7 of 100 rows keeps the original pagination fields. To collect all rows, re-request with a `--limit` no larger than the rows you actually received, then follow the returned cursor. -- **Only long values clipped** (no rows withheld): the payload carries `truncated: true` alone, and stderr names the clipped fields. Re-requesting cannot restore them: narrow the filter, lower the rows per page, or switch to a curated command that supports field projections. +- **Only long values clipped** (no rows withheld): the payload carries `truncated: true` alone, and stderr names the clipped fields. Re-requesting cannot restore them: narrow the filter, lower the rows per page, or keep only the fields you need with the global `--fields`. + +**A response whose row array carries non-scalar siblings is not bounded.** When the row array is named `items` / `docs` / `list` but the response also has object or array fields beside it (for example `calendar event-list`'s `days` map), it cannot be squeezed under 16 KiB without losing fields, so it prints whole, exactly like the **detail-shaped single objects** in the last paragraph of this section: no `truncated` / `emitted_rows` marker, and no value shortened. **Bare top-level arrays** (such as the curated `incident list` and `insight incidents`) have nowhere to carry the marker, so a reduction is announced on stderr only. -**Detail-shaped single objects** (for example, `safari session-get`) are never bounded or shortened — a shortened id or status would pass for a real value, so these responses print untouched. Most generated commands have no flag that narrows their output. An occasional `--fields` selects request-body fields, not output fields. For complete JSON, lower `--limit` and page through with `--page` (for example, `flashduty safari session-list --limit 20 --page 2`), or narrow the filter. +**Detail-shaped single objects** (for example, `safari session-get`) are never bounded or shortened — a shortened id or status would pass for a real value, so these responses print untouched. Generated commands can narrow their output fields with the global `--fields` (see "Global flags" and "Field projections for structured output" below; where an occasional command spells `--fields` as a request-body field selector, such as `monit rule-update-fields`, it does not apply to the output). For complete JSON, lower `--limit` and page through with `--page` (for example, `flashduty safari session-list --limit 20 --page 2`), or narrow the filter. ### Field projections for structured output -The following commands support `--fields` with `json` or `toon` output. Supply comma-separated top-level response fields; an unknown field fails immediately, and table output ignores this flag. +`--fields` is a global flag (see "Global flags"): every command accepts it in `json` or `toon` output, and it takes a comma-separated list of top-level fields to keep, applied to each row of a list or to the keys of a single record. The projection runs on the response: for a list envelope (row array named `items`, `docs`, or `list`, with only scalar paging fields beside it) it narrows that row array and leaves the paging fields intact; a field no row of the response carries is left out and stderr reports it as matching no key, listing the keys the output does carry; output that is neither an object nor a list of objects fails the command and tells you to drop `--fields`. Table output ignores `--fields`, and stderr says so. + +The curated commands in the table below fall back to a default compact projection when `--fields` is omitted, and are size-bounded; each of them defines its own `--fields` (same meaning as the global one), so a misspelled field name fails immediately and lists the names that are valid. Every other command — all the generated ones included — has no default projection: on those, `--fields` applies to the raw fields of the API response, and a name that matches no key only produces the stderr note above. | Command | Structured output when `--fields` is omitted | Limit | | --- | --- | --- | diff --git a/en/developer/go-sdk.mdx b/en/developer/go-sdk.mdx index d2b4e30b..2a943b9c 100644 --- a/en/developer/go-sdk.mdx +++ b/en/developer/go-sdk.mdx @@ -153,7 +153,7 @@ Endpoints are grouped by service and hang off the client: the call convention is | `client.Account` | Account | | `client.AuditLogs` | Audit logs | | `client.AlertRules` | Alert rules | -| `client.RuleFolders` | Rule folders; `List` lists every monitor folder the caller can read (`POST /monit/folder/list`) | +| `client.RuleFolders` | Rule folders; `ReadList` lists every folder the caller can read (`POST /monit/folder/list`), `ReadHealth` returns folder health summaries (`POST /monit/folder/health`, including active alerts and rule runtime issues in visible descendants), and `WriteCreate` / `WriteUpdate` / `WriteMove` / `WriteDelete` create, update, move, and delete folders; the old `List` is kept as a compatibility alias for `ReadList` | | `client.AlertEnrichment` | Alert enrichment | | `client.DataSources` | Data sources | | `client.Dashboards` | Dashboards; panel preview and run, panel query resolution (`QueryReadResolve`), variable resolution, plus dashboard read/write, move/restore, and revision history | @@ -165,7 +165,7 @@ Endpoints are grouped by service and hang off the client: the call convention is | `client.Analytics` | Analytics | | `client.A2aAgents` | A2A Agents | | `client.Artifacts` | AI SRE artifacts | -| `client.Automations` | AI SRE automations | +| `client.Automations` | AI SRE automations (`RuleReadGet` / `RuleReadList` / `RuleWriteCreate` / `RuleWriteUpdate` / `RuleWriteDelete` / `RuleWriteRun` / `RunReadList` / `TemplateReadList`); on create, the execution destination comes from `AutomationRuleCreateRequest.RunIn` (`current-chat` / `web`; omitted lets the server decide) and the scope from that struct's `TeamID` (a `*int64`: an explicit `0` is personal scope, omitted inherits the authenticated IM conversation's scope); `AutomationRuleUpdateRequest` no longer has `TeamID` | | `client.Knowledge` | AI SRE Knowledge (the knowledge itself and its files) | | `client.McpServers` | MCP Servers | | `client.Sessions` | AI SRE sessions | @@ -198,6 +198,20 @@ The following services have behavior that needs extra explanation: `client.Artifacts` (AI SRE artifacts) covers the 11 operations under `/safari/artifact/*`: on the gallery read side `ReadGet` (get a single published artifact by ID), `ReadList` (list artifacts visible to the caller, with title substring search and `scope` (`all` / `personal` / `team`) plus `team_ids` filtering), and `ReadGetFileState` (probe up to 50 presented-file IDs in one call for ones that already have a live published artifact); on the file side `ReadSign` (issue short-lived download/preview URLs for a presented file, valid 5 minutes, `expires_in` is fixed at 300) and `ReadStream` (download or preview the file's bytes with a signed token — the success body is a file, not a JSON envelope, with the raw bytes on `Response.Raw`); on the write side `WritePublish` (publish a session-produced file to the gallery), `WriteUpdate` (rename the artifact or transfer it between personal and team scope), and `WriteDelete` (detach it from the gallery; the source file stays with its session); public sharing `WriteShareEnable` (turn on anonymous public sharing and return the public link — anyone with the link can view it, no login required), `WriteShareRevoke` (turn sharing off; the link stops resolving immediately), and `WriteShareSync` (refresh the public snapshot with the latest content — when `share_enabled` is true and `share_file_id` differs from `file_id`, the snapshot is stale and calling this refreshes it). Exported types include `PublishedArtifactItem`, `ArtifactShareState`, `SignedUrLs`, and the various `Artifact*Request` / `Artifact*Response` structs. +### Automation rules + +`client.Automations` covers `/safari/automation/*`. A rule's **execution destination** (scope and where it runs) is fixed at creation time: + +- `AutomationRuleCreateRequest.RunIn` (`run_in`) is `current-chat` (binds the rule to the authenticated live IM conversation) or `web` (runs in the web console). Omitted, the server decides: `current-chat` for an authenticated IM invocation, `web` otherwise. Sending `current-chat` outside a live IM conversation is rejected. +- `AutomationRuleCreateRequest.TeamID` (`team_id`) is a `*int64`: an explicit `0` means personal scope and a value greater than 0 picks a team in the account. Omitted, it inherits the authenticated IM conversation's scope when one is present; otherwise the server applies its normal default. A `current-chat` rule's scope must match that conversation's scope. +- `AutomationRuleUpdateRequest` no longer has `TeamID` (nor `RunIn`): scope and execution destination are immutable after creation. Old code that set `TeamID` on an update request should drop the line — otherwise it will not compile. + +### Rule folders + +`client.RuleFolders` covers the six operations under `/monit/folder/*`. `ReadList` (`POST /monit/folder/list`) and `ReadHealth` (`POST /monit/folder/health`) take no request body. The first returns a flat `[]FolderItem` that you rebuild into a tree in the client from `ParentID` / `ParentPath` (dashboards and alert rules share that same tree); the second returns a `FolderHealthOutput`, whose `FolderHealthItem.HasIssue` marks a folder that — or whose visible descendant — has active alerts or rule runtime issues. On the write side `WriteCreate` (`/monit/folder/create`) and `WriteUpdate` (`/monit/folder/update`) return the `FolderItem`, while `WriteMove` (`/monit/folder/move`) and `WriteDelete` (`/monit/folder/delete`) return only a `*Response`. Further exported types are `FolderCreateRequest`, `FolderUpdateRequest`, `FolderMoveRequest`, and `FolderDeleteRequest`. + +Request fields: `FolderCreateRequest.Name` is required and may not contain a period, slash, or comma, and a `ParentID` of 0 or omitted creates a root folder. `FolderUpdateRequest` requires both `ID` and `Name` and replaces the editable fields — omitting `Note` clears the note and omitting `TeamID` resets it to 0 (account-wide). `FolderMoveRequest` requires `DestParentID` even when moving back to the root (pass 0), and a folder cannot be moved under itself or one of its descendants. `FolderDeleteRequest` carries only `ID`; only an empty folder can be deleted, so child folders, alert rules, or dashboards inside it make the call fail with HTTP 409 and `FolderNotEmpty`. + ### Diagnostic queries `client.Diagnostics.QueryData` runs a synchronous query through `POST /monit/query/data` and returns a stable `query_result.v1` structured result (`result.kind` is one of `frames`, `records`, or `samples`). This API requires monit-edge v0.65.0 or later. For log-pattern and metric-trend analysis, use `client.DataSources.ToolsInvoke` with `prometheus.metric_trends`, `loki.log_patterns`, or `victorialogs.log_patterns`. @@ -239,6 +253,20 @@ For `client.DataSources`, the `payload` selects a type-specific configuration bl `enabled` and `alerting_enabled` are independent: `enabled` (whether business execution is enabled) defaults to true on create; `alerting_enabled` (whether alert evaluation is allowed; alerting also requires `enabled` true and an alerting-capable type) defaults to true for alerting types and false for diagnostic-only types on create. On update, omitting either preserves the current value and an explicit `null` is invalid; disabling (`enabled` false) is rejected with a conflict when enabled rules reference the datasource. Also note that `payload` is always `null` in `/monit/datasource/list` responses (the list query does not read the payload column); it is populated in create/update/info responses. +### Service calendar events + +`client.Calendars` covers `/calendar/*`. + +`CalEventIDRequest` (`CalEventDelete`, `POST /calendar/event/delete`) supports two usages: pass `EventID` to delete a single event, or omit it and pass both `StartAt` and `EndAt` (`YYYY-MM-DD`, `EndAt` exclusive) to clear the calendar's own events off those days, with the cleared days falling back to the linked holiday calendars and the weekly workdays. Pass one or the other; `CalID` is always required. + +`CalEventUpsert` (`POST /calendar/event/upsert`) creates or updates an event the calendar owns over `[StartAt, EndAt)` (`IsOff` true marks a day off, false a working-day override): omit `EventID` to create a new event, and a given `EventID` must be an existing event of that calendar. The write first takes the calendar's other own events off the same days — an event fully inside the range is deleted, one partly inside is shortened, and one spanning the range is split in two — so the latest write decides those days. `EndAt` must be later than `StartAt`, and `Summary` is optional. + +`CalEventList` (`POST /calendar/event/list`) scopes the range with `Year` / `Month` / `Day` on `CalEventListRequest` (with `Month` and `Day` both 0 it returns the whole year). Alongside `Items` (events sorted by `StartAt`) and `Total`, `CalEventListResponse` carries a required `Days`: a `map[string]CalDay` keyed by `YYYY-MM-DD` that gives the resolved state of every day in that scope. Each `CalDay` reports `IsOff`, `EventID` (the event that decided the day, absent when no event covers it), and `Layer` (`custom` / `holiday` / `weekly`). Days resolve by layer precedence: the calendar's own events (`custom`) outrank the linked holiday calendars (`holiday`), which outrank the weekly workdays (`weekly`). Inside one layer a working-day event beats a day off, so a make-up workday from a holiday calendar wins over holiday rest days. A day no event covers is a working day. + +### Incident work items + +The `WorkItem*` methods on `client.Incidents` (`/incident/work-item/*`) manage an incident's action items and post-mortem follow-ups. Work-item status is a closed enum: `Status` on `CreateWorkItemRequest` / `UpdateWorkItemRequest` and `TargetStatus` on `ConvertWorkItemRequest` accept only `open`, `in_progress`, `done`, or `cancelled`, with creation taking `open` when the field is omitted or blank and `TargetStatus` being optional. `WorkItemComplete`'s `CompleteWorkItemRequest.TargetStatus` accepts only `done`; any other value is rejected. + ## Response timestamps Time fields in responses are self-describing `Timestamp` (Unix seconds) or `TimestampMilli` (milliseconds) types. Types shared by requests and responses are the exception (see the warning below). They serialize to RFC3339 strings in the local time zone, so JSON, logs, and LLM-facing output are directly readable; the raw epoch is still one method call away. diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index 3af575a2..4908ffe2 100644 --- a/en/openapi/api-catalog.mdx +++ b/en/openapi/api-catalog.mdx @@ -515,7 +515,7 @@ The `POST /safari/session/get` response includes a `pending_messages` field alon | `query` | string | The message text, consistent with the send-ack frame | | `parts` | array | The message's parts (`text` / `file` / `ref` / `skill`), passed through verbatim (optional) | -Only plain human messages are included. Messages from automation, child-session notifications, and parent initial messages (they carry `source`), and messages holding question answers (`function_response`), are excluded. The content matches the `user_message_enqueued` frame payload. +Only plain human messages are included. Messages from automation, child-session notifications, and parent initial messages (they carry `source`), messages holding question answers (`function_response`), and messages holding batched page-action receipts (`function_responses`) are excluded. The content matches the `user_message_enqueued` frame payload. </Note> ### Automations diff --git a/en/openapi/introduction.mdx b/en/openapi/introduction.mdx index 9755566e..42076f19 100644 --- a/en/openapi/introduction.mdx +++ b/en/openapi/introduction.mdx @@ -71,6 +71,22 @@ An APP Key's effective access is constrained by both its permission scope and th You can edit an existing APP Key's name and permission scope from the APP Key list. +### What to do if an APP key is exposed + +If an APP key may have been exposed (for example, committed to a public repository or shown in logs or screenshots), replace it: + +<Steps> + <Step title="Create a replacement key"> + In **Personal center → APP Key**, create a new APP key. + </Step> + <Step title="Switch your integrations"> + Move every integration, script, and configuration that uses the old key to the new key, and confirm the calls work. + </Step> + <Step title="Disable or delete the old key"> + Disable or delete the old key in the APP key list. Requests that use it then return `401 Unauthorized`. + </Step> +</Steps> + ### Passing the APP key Pass the key as the `app_key` query parameter: diff --git a/zh/developer/cli.mdx b/zh/developer/cli.mdx index e7cde660..42471294 100644 --- a/zh/developer/cli.mdx +++ b/zh/developer/cli.mdx @@ -18,7 +18,7 @@ Flashduty CLI（`flashduty`）是一款命令行工具，可在终端中完成 curl -sSL https://static.flashcat.cloud/flashduty-cli/install.sh | sh ``` -默认安装到 `/usr/local/bin`，可通过环境变量 `FLASHDUTY_INSTALL_DIR` 自定义。 +默认安装到 `PATH` 上已有的那份 `flashduty` 所在目录，便于就地升级替换掉旧副本；`PATH` 上没有 `flashduty` 时才安装到 `/usr/local/bin`。可通过环境变量 `FLASHDUTY_INSTALL_DIR` 自定义安装目录。 </Tab> <Tab title="Windows (PowerShell)"> @@ -39,13 +39,15 @@ irm https://static.flashcat.cloud/flashduty-cli/install.ps1 | iex | 环境变量 | 说明 | 默认值 | |----------|------|--------| | `FLASHDUTY_VERSION` | 安装指定版本，如 `v1.5.12` | 最新版本 | -| `FLASHDUTY_INSTALL_DIR` | 安装目录 | `/usr/local/bin`（Shell）、`~\.flashduty\bin`（PowerShell） | +| `FLASHDUTY_INSTALL_DIR` | 安装目录 | `PATH` 上已有 `flashduty` 所在目录，否则 `/usr/local/bin`（Shell）；`~\.flashduty\bin`（PowerShell） | | `MIRROR_URL` | 覆盖安装脚本的 Release 资产下载镜像前缀，需以 `https://` 开头 | `https://static.flashcat.cloud/flashduty-cli` | | `FLASHDUTY_UPDATE_BASE_URL` | 覆盖 `flashduty update` 及自动更新检查的下载基础 URL | `https://static.flashcat.cloud/flashduty-cli` | | `INSTALLED_NAME` | 安装后的命令名，例如 `fduty` | `flashduty` | 以自定义命令名安装的副本，在帮助、错误信息与 Shell 自动补全中都使用该名称；`flashduty update` 按正在运行的可执行文件名与所在目录就地替换自身，而不是另装一份默认命名的副本。 +安装脚本结束时会再核对一次 `PATH`：若当前 Shell 实际运行的 `flashduty` 不是刚装的那份（被更靠前的旧副本抢占），会在输出里提示删掉旧副本或把新目录提前。若当前进程由 flashduty-runner 托管（`FLASHDUTY_MANAGED_BY_RUNNER=1`），脚本会拒绝执行并提示改为升级 runner——runner 自带一份与它一同验证过的 CLI，就地替换会让两者失配。 + ## 认证 ### 登录 @@ -94,14 +96,16 @@ flashduty config set base_url URL # 覆盖 API 地址 ## 全局参数 -所有子命令均支持以下参数： +以下参数注册在根命令上；除 `--version` 外，其余所有子命令均可使用： | 参数 | 说明 | |------|------| | `--output-format` | 输出格式：`table`（默认）、`json` 或 `toon`（紧凑、更省 token） | | `--json` | 以 JSON 格式输出，是 `--output-format json` 的别名，便于通过 `jq` 等工具解析 | | `--no-trunc` | 表格输出时不截断长字段 | +| `--fields` | `json`/`toon` 输出时只保留指定的顶层字段（逗号分隔），作用于列表的每一行或单个记录；表格输出忽略该参数，并在 stderr 提示它未生效。字段名未命中时 stderr 会列出实际可用的键；输出不是对象或对象列表时命令直接报错。详见下文「结构化输出的字段投影」 | | `--base-url` | 覆盖 API 地址（私有部署场景） | +| `--version` | 打印版本信息，与 `flashduty version` 输出相同的一行。这个含义只在根命令上有；个别命令自己定义了 `--version`（例如变更类命令的乐观锁版本号），那些命令按自己的说明生效 | ## 命令清单 @@ -116,7 +120,7 @@ flashduty incident ack <id> [<id2>...] # 认领故障 flashduty incident close <id> [<id2>...] # 关闭（解决）故障 flashduty incident merge <target-id> --source <ids> # 将多个故障合并到目标故障 flashduty incident timeline <id> # 查看故障时间线 -flashduty incident alerts <id> # 查看故障关联的告警 +flashduty incident alerts <id> # 查看故障关联的告警（--limit 默认 10、--page） flashduty incident similar <id> # 查找相似的历史故障 flashduty incident feed <id> [flags] # 查看故障的分页动态流（时间线条目） ``` @@ -141,7 +145,7 @@ flashduty incident feed <id> [flags] # 查看故障的分页动态流（时间 | `--is-rare` | 仅看新奇故障 | `false` | | `--is-snoozed` | 仅看已暂缓的故障 | `false` | | `--ever-muted` | 仅看曾被静默的故障 | `false` | -| `--since` | 起始时间（时长、日期、日期时间或 Unix 时间戳），与 `--until` 的窗口须小于 31 天 | `24h` | +| `--since` | 起始时间（时长、日期、日期时间或 Unix 时间戳），与 `--until` 的窗口须小于 31 天 | `24h`；`--progress` 只含 `Triggered,Processing` 时为 `30d` | | `--until` | 截止时间 | `now` | | `--asc` | 按时间升序（最早的在前） | `false`（最新在前） | | `--limit` | 最大结果数（上限 100） | `20` | @@ -151,6 +155,8 @@ flashduty incident feed <id> [flags] # 查看故障的分页动态流（时间 `incident feed <id>` 按页读取故障的动态流（时间线条目）：`--asc` 让最旧的条目在前（默认最新在前），`--types` 按逗号分隔的条目类型过滤（如 `i_comm,i_assign`，条目的 `type` 字段给出实际类型），另有 `--limit`（最大 100）与 `--page`。 +`incident alerts <id>` 列出该故障关联的告警，支持 `--limit`（默认 `10`）与 `--page`（默认 `1`）。 + #### 创建、更新与合并 `incident create` 的 `--title`（3–200 字符）与 `--severity` 必填，在终端中缺少时会交互提示。指派方式有三种，可组合使用：`--assign`（成员 ID 列表）、`--assign-emails`（成员邮箱，逗号分隔；不匹配任何成员的邮箱会被忽略）、`--escalate-rule-id` 加 `--escalate-layer`（从该分派策略的指定环节（从 0 开始）起，指派该环节的人员；`--escalate-layer` 必须与 `--escalate-rule-id` 一起使用）。 @@ -185,6 +191,8 @@ flashduty incident work-item-post-mortem-bind [flags] # 将已转换 `work-item-create` 关键参数：`--item-type`（必填，`action` 或 `follow_up`）、`--title`（必填，最多 512 字符）、`--idempotency-key`（必填幂等键，最多 128 字符）、`--post-mortem-id`（`follow_up` 必填，`action` 禁止）、`--assignee-ids`（初始负责人，旧别名）。更新类操作（`update`/`complete`/`convert`/`delete`/`assignees-reset`）均需传 `--version`（乐观锁，必须与当前存储版本一致）。 +工作项状态只接受 `open` / `in_progress` / `done` / `cancelled` 四个取值：`work-item-create --status` 省略或留空时默认 `open`，`work-item-update --status` 只能改成这四个值之一，`work-item-complete --target-status` 只接受 `done`（其它取值会被拒绝），`work-item-convert --target-status` 可传这四个值之一。 + 工作项的负责人可以是成员，也可以是**本账户的 AI SRE**： - `work-item-create` 与 `work-item-assignees-reset` 接受 `assignees` 字段（每项形如 `{type, id?}`，`type` 取 `person` 或 `ai_sre`；`ai_sre` 项不带 `id`，最多 20 项），该字段只能通过 `--data` 传 JSON。`--assignee-ids` 是等价的旧别名（相当于全部为 `person`），两者互斥，同时传会报错。 @@ -492,7 +500,25 @@ flashduty rum resource-info [--no-cache] # 查看 RUM 套餐版本、配额与 flashduty oncall license-list # 列出当前账户中持有有效 On-call 许可证的成员 ``` -该命令只读，返回成员 ID、名称及许可证类型：`fixed` 表示固定分配，`temporary` 表示当前临时许可证窗口内生效。 +该命令只读，返回成员 ID、名称及许可证类型：`fixed` 表示固定分配，`temporary` 表示当前临时许可证窗口内生效。响应还带 `release_limited`：本账户在本计费周期内的 License 释放次数已用尽时为 `true`，此时释放成员席位会以错误码 `NoLicense` 失败；该额度即[每个计费周期的释放次数上限](/zh/platform/pricing)。 + +### calendar — 服务日历 + +服务日历是分派策略与静默规则判断工作日/休息日的依据，控制台侧的配置与层级优先级见[服务日历](/zh/on-call/configuration/service-calendar)。该命令组由 OpenAPI 生成（见下文「全量命令覆盖」）：`<cal-id>`（形如 `cal.<uuid>`）为位置参数，取自 `calendar list` 响应 `items[]` 里的 `cal_id`；`list` 默认只列账户自有日历，列公共节假日日历要加 `--kind region.official.holiday`（默认按调用者所在地区过滤，加 `--no-locale` 取消过滤）。 + +```bash +flashduty calendar list [--kind personal|region.official.holiday] [--no-locale] # 列出日历 +flashduty calendar info|update|delete <cal-id> # 查看 / 修改 / 删除日历 +flashduty calendar event-list <cal-id> [--year <y>] [--month <m>] [--day <d>] # 列出事件，响应另带 days +flashduty calendar event-upsert <cal-id> --start-at <date> --end-at <date> --is-off <bool> [--event-id <id>] [--summary <text>] +flashduty calendar event-delete <cal-id> [--event-id <id> | --start-at <date> --end-at <date>] +``` + +以下三点只能从 `--help` 和响应本身看出来： + +- **`event-delete` 兼具删除单条事件与清空日期区间两种用法**。传 `--event-id` 删除一条事件；或传 `--start-at` 与 `--end-at`（均为 `YYYY-MM-DD`，`end_at` 为开区间、必须晚于 `start_at`）清空该日历自身在 `[start_at, end_at)` 内的全部事件。被清空的日期回落到关联的节假日日历与每周工作日，效果相当于在控制台里对这些日期点击**恢复默认**。 +- **`event-upsert` 会裁剪同区间内该日历自身的其他事件**：完全落在区间内的被删除、部分重叠的被缩短、跨越区间的被拆成两条，因此这些天以最后一次写入为准（`--summary` 可选）。 +- **`event-list` 的响应除行数组 `items` 外还有 `days`**：按 `YYYY-MM-DD` 给出请求范围内每一天的解析结果，含 `is_off`、决定该天的 `event_id` 与层级 `layer`——`custom`（日历自有事件）优先于 `holiday`（关联的节假日日历），再优先于 `weekly`（每周工作日）；同一层级内工作日事件优先于休息日；`layer` 缺失表示没有任何事件覆盖该天，按工作日计。判断某天是否休息请读 `days`，不要从 `items` 反推：同一天可能同时存在多层事件。 ### template — 通知模板 @@ -629,12 +655,17 @@ flashduty monit datasource-delete --id <datasource-id> # 删除数据源（引 - `kafka`：`sasl_mechanism`（`none` 默认 / `plain` / `scram-sha-256` / `scram-sha-512`，后三者需用户名与密码）、`username` / `password`、`timeout_ms`（默认 5000）、TLS 字段（`tls_min_version` 默认 1.2，最高 1.3）。 - 密码与 `kafka.tls_key` 支持 `${env:NAME}` 引用（在 Edge 上解析）；字面值不会出现在响应中，仅 `${env:...}` 引用会回显。**更新时省略这些字段以保留已存密钥，显式传空字符串表示清除**。 -#### 仪表盘与规则分组（dashboard-* / folder-list） +#### 仪表盘与规则分组（dashboard-* / folder-*） `monit dashboard-*` 命令族管理监控仪表盘（由 OpenAPI 生成命令提供）。仪表盘本身是一份 `dashboard.v1` 文档，创建与更新时通过 `--data` 传入 `definition`；`update` / `delete` / `move` / `restore` 都要求 `--expected-revision`——传入的版本不是当前版本时以 `DashboardRevisionConflict` 拒绝，需要重新读取后再提交。 ```bash flashduty monit folder-list # 列出全部监控规则分组，用于取 folder-id（返回顶层数组，用 jq '.[]'） +flashduty monit folder-health # 查看分组健康摘要，含后代分组中的问题（分页信封，用 jq '.items[]'） +flashduty monit folder-create --name <folder-name> [flags] # 创建分组（--name 必填且不能含 . / ,；--parent-id 父分组，0=根；--note 备注；--team-id 团队，0=账户级） +flashduty monit folder-update --id <folder-id> --name <folder-name> # 更新分组的名称、备注与团队归属（--id 与 --name 必填） +flashduty monit folder-move <dest-parent-id> --id <folder-id> # 移动分组及其后代（dest-parent-id 是位置参数，必须显式给出，0=移到根） +flashduty monit folder-delete --id <folder-id> # 删除分组（仅限空分组：内部还有子分组、规则或仪表盘时会被拒绝） flashduty monit dashboard-list <folder-id> # 列出某个分组下的仪表盘（分页信封，用 jq '.items[]'） flashduty monit dashboard-search --query "支付" # 按标题与描述搜索仪表盘（至少一个词） flashduty monit dashboard-get <dashboard-id> # 读取仪表盘详情，含 definition 与当前 revision @@ -654,6 +685,8 @@ flashduty monit dashboard-runtime-variables-preview # 预览草稿 flashduty monit dashboard-runtime-queries-resolve <panel-id> [<id2>...] # 解析面板查询：变量替换后的表达式与绑定到的数据源 ``` +`monit folder-*` 是分组本身的增删改查：`folder-health` 返回 `{items:[...]}` 分页信封（每项只有 `folder_id` 与 `has_issue`，`has_issue` 表示该分组或其可见后代存在活跃告警或规则运行问题），`folder-list` 返回顶层数组，用法都是 `--json | jq`；`folder-create` 与 `folder-update` 返回更新后的单个分组对象；`folder-move` 与 `folder-delete` 不返回分组对象。分组名不能含 `.`、`/`、`,`；`folder-move` 的 `dest-parent-id` 即使移到根（`0`）也必须显式给出；`folder-delete` 只接受空分组——内部还有子分组、规则或仪表盘时会被拒绝，需要先自行清空。 + 面板运行时与变量解析的时间窗口、变量选择都以 JSON 对象放在 `--data` 里（时间用 `from_ms` / `to_ms` 的毫秒时间戳）。`dashboard-panel-preview` 与 `dashboard-runtime-variables-preview` 需要一个 `context`：`kind: existing` 配 `dashboard_id` 指向已存仪表盘，`kind: new` 配 `folder_id` 指向尚未落库的分组。 `dashboard-runtime-queries-resolve` 另有两个影响解析结果的参数：`--max-data-points`（整数，取值 2–5000；既作降采样目标，也决定解析出的表达式里内置时间变量渲染出的步长，省略或传 `null` 时取服务端默认值 100）与 `--preserve-builtin-variables`（布尔，默认关）：开启后**内置时间变量**在解析结果里原样保留，交由自带执行窗口的调用方自行渲染，用户变量仍会被解析。兄弟命令 `dashboard-panel-run` 与 `dashboard-panel-preview` 早已带 `--max-data-points`，同为 2–5000 的降采样目标。 @@ -681,8 +714,9 @@ flashduty monit prometheus-api-v1-label-{label_name}-values job --data-source-id ### alert — 告警与告警事件查询 ```bash -flashduty alert list [flags] # 列出告警（默认最近 24 小时） +flashduty alert list [flags] # 列出告警（默认最近 24 小时；--active 时为 30 天） flashduty alert get <alert_id> # 查看单条告警详情；detail 是同一命令的别名 +flashduty alert events <alert_id> # 列出组成该告警的原始事件（--limit、--page） flashduty alert-event list [flags] # 列出告警事件（默认最近 1 小时） ``` @@ -690,6 +724,10 @@ flashduty alert-event list [flags] # 列出告警事件（默认最近 1 小时 `alert list` 另有 `--alert-ids`（逗号分隔的告警 ID）、`--alert-keys`（逗号分隔的告警去重键）、`--asc`（按开始时间升序，默认最新在前）、`--by-updated-at`（把 `--since`/`--until` 应用到最近更新时间，而不是开始时间）；`alert-event list` 也支持 `--asc`（升序，默认最新在前），但没有 `--by-updated-at`。 +`alert list` 还用 `--active`（只看活跃告警）与 `--recovered`（只看已恢复告警）筛选状态：二者互斥，同时传入会报错；只传其中一个时，`--active` 对应活跃、`--recovered` 对应已恢复，都不传则不加状态过滤。活跃告警可能早于一天，因此 `--active` 且未指定 `--since` 时默认窗口放宽到 30 天（实际生效的窗口见 stderr 的窗口提示）。 + +`alert events <alert_id>` 列出组成该告警的原始事件：`--limit` 默认取服务端默认的 20 条（上限 100），`--page` 从 1 开始。它按单个告警取事件，跨告警的时间窗查询用 `alert-event list`。 + ### automation — AI SRE 自动化规则 `automation` 命令组管理 AI SRE 的自动化规则——创建、查询、更新、删除、运行历史与触发，页面操作见[自动化](/zh/ai-sre/automations)。 @@ -710,11 +748,12 @@ flashduty automation fire <trigger_id> # 经 HTTP POST 触发器触 | 参数 | 说明 | |------|------| | `--name` | 规则名称（必填） | -| `--team-id` | 归属团队 ID；`0` 表示个人范围（默认）。作用域创建后不可变更 | +| `--team-id` | 归属团队 ID；显式 `0` 表示个人范围，`>0` 表示该团队；省略时不发送该字段，由服务端在可用时继承当前 IM 会话的作用域，否则取常规默认值。`--run-in current-chat` 时传入的团队 ID 必须与该会话的作用域一致，不能把会话改到别的个人或团队范围。作用域创建后不可变更 | +| `--run-in` | 执行位置：`current-chat` 把规则绑定到当前的 IM 会话，`web` 在 Web 控制台运行；省略时由服务端决定——在 IM 会话里发起选 `current-chat`，否则选 `web`。在非 IM 会话里传 `current-chat` 会被服务端拒绝 | | `--schedule` | 节奏辅助：`hourly`、`daily`、`weekly` 或 `cron`；省略时默认 `daily` | | `--at` | `HH:MM` 本地时间（按规则时区）；`hourly` 只取分钟（默认 0 分），`daily`/`weekly` 取小时与分钟（默认 09:00） | | `--weekday` | `weekly` 的星期：`sun`–`sat` 或 `0`–`7`（`0` 与 `7` 均表示周日，默认周一） | -| `--cron-expr` | 精确的 5 段 cron 表达式（按规则时区解释），优先级高于 `--schedule` 辅助参数 | +| `--cron-expr` | 支持的 5 段 cron 表达式（按规则时区解释），优先级高于 `--schedule` 辅助参数。分钟位必须是 `0`–`59` 的单一整数，因此最快只能每小时触发一次；分钟位的通配符、范围、列表与步长都不支持，`*/15 * * * *`、`0,30 * * * *` 这类写法会被拒绝 | | `--timezone` | IANA 时区名（如 `Asia/Shanghai`），`--at` 与 `--cron-expr` 按该时区解释；省略时由服务端依次取调用者的成员时区、账户时区，最后回退 `Asia/Shanghai`。服务端无法加载的时区会被拒绝 | | `--disabled` | 以停用状态创建（默认启用） | | `--schedule-enabled` | 是否启用周期触发器（默认 `true`） | @@ -722,7 +761,9 @@ flashduty automation fire <trigger_id> # 经 HTTP POST 触发器触 | `--prompt` / `--prompt-file` | 任务提示词，二选一必填；`--prompt-file` 从文件读取（`-` 表示 stdin） | | `--environment-kind` / `--environment-id` | 运行环境：`cloud` 或 `byoc`（`byoc` 需配合 `--environment-id`）；留空表示自动 | -`update` 可改字段：`--name`、`--prompt`/`--prompt-file`、`--schedule`/`--at`/`--weekday`/`--cron-expr`/`--timezone`、`--enable`/`--disable`、`--enable-schedule`/`--disable-schedule`、`--enable-http-post-trigger`/`--disable-http-post-trigger`、`--rotate-http-post-token`、`--environment-kind`/`--environment-id`。个人 / 团队作用域创建后不可变更，`update` 不提供改作用域的参数。 +从 IM 会话里创建规则时，省略 `--run-in` 即让服务端把规则绑定到当前会话，同时继承该会话的作用域；不需要（也不应该）自己传 chat、平台、集成或会话 ID——服务端负责解析并鉴权当前会话。绑定当前会话之后，每次普通运行都会新建一个执行会话，IM 集成建线程时也会新建线程，并始终留在创建时捕获的那个会话与不可变作用域上，而不是复用旧会话或旧线程；同一次运行的重试复用该次运行的执行身份。若运行发生时绑定会话的作用域已与规则不符，本次运行会被跳过，规则不会被搬到别的会话里执行。作战室触发的规则行为不变。由于每次运行都是全新上下文，提示词必须自带所需的聊天上下文（服务对象、团队、投递目标等），不要写「上文/上述」这类指代。执行位置与作用域一样创建后不可变更。 + +`update` 可改字段：`--name`、`--prompt`/`--prompt-file`、`--schedule`/`--at`/`--weekday`/`--cron-expr`/`--timezone`、`--enable`/`--disable`、`--enable-schedule`/`--disable-schedule`、`--enable-http-post-trigger`/`--disable-http-post-trigger`、`--rotate-http-post-token`、`--environment-kind`/`--environment-id`。个人 / 团队作用域与执行位置（`--run-in`）创建后不可变更，`update` 不提供这两类参数。`update` 的 `--cron-expr` 与 `create` 同一约束：分钟位必须是 `0`–`59` 的单一整数，最快每小时一次，不支持分钟位的通配符、范围、列表与步长。 `runs` 支持 `--status`（`queued`/`running`/`retrying`/`succeeded`/`partial`/`failed`/`skipped`/`abandoned`）、`--trigger-kind`（服务端取值 `schedule`/`debug`/`manual`/`http_post`/`oncall_incident`/`war_room_created`，其中 `war_room_created` 表示由作战室创建触发的运行）、`--since`/`--until`、`--page`、`--limit`。`fire` 用触发器的 Token 鉴权（`--token`，或环境变量 `FLASHDUTY_AUTOMATION_TRIGGER_TOKEN`），`--text` 传本次运行的上下文，`--data` 传完整 JSON 请求体（内联 JSON 或 `-` 读 stdin）。 @@ -868,6 +909,8 @@ inc_abc123 DB connection timeout Critical Triggered Production 2026 inc_def456 High memory usage Warning Processing Staging 2026-04-10 09:15 Showing 2 results (page 1, total 2). ``` + +生成命令的列表响应若在行数组（`items` / `docs` / `list`）之外还带其它字段（如 `calendar event-list` 的 `days`、`oncall license-list` 的 `release_limited`），表格会在行表格之后额外打印一行 `Also in the response: <字段> (use --json to see it).`，提示这些字段不在表格里，要看它们请用 `--json` 或 `--output-format toon`。 </Tab> <Tab title="JSON（--json / --output-format json）"> @@ -895,6 +938,14 @@ TOON 不能直接用 `jq` 解析；需要管道给 `jq` 时请改用 `--json`。 </Tab> </Tabs> +### 时间窗口提示 + +查询时间范围的命令会把本次实际发送的窗口按本地时区写到 stderr，例如 `note: window 2026-10-08T14:00:00+08:00..2026-10-09T14:00:00+08:00 (1d, ended now)`。括号里是窗口跨度与结束时间相对当前的位置（`ended 3m ago` / `ends in 2h`）；若窗口来自某个默认值而非你显式传入的 `--since`/`--until`，还会说明是哪个默认值（如 `--progress` 只含开放状态、`--active`）。 + +覆盖范围包括 `incident list`、`alert list`、`alert-event list`、`change list`、`audit search`、`insight`、`oncall`、`monit-query`（工具参数带执行窗口时），以及所有解析出 `--start-time`/`--end-time` 的生成命令（只给出一侧、另一侧交给 `--data` 或服务端默认的命令不输出该提示，因为窗口没有被完整确定）。只有一个时间点的查询写成 `note: instant <时刻> (…)`。 + +它用来核对窗口是否就是你要的那个：默认值可能比你预期的宽（例如 `--active` 会把默认窗口放宽到 30 天），把时间戳按错误时区解读会让窗口落到未来，此时提示形如 `ends in 7h`。提示只写 stderr，stdout 保持原样，`jq` 与 toon 消费方不受影响。 + ### 生成命令的输出上限 由 OpenAPI 代码生成提供覆盖的生成命令（如 `safari session-list`、`monit datasource-list`、`safari a2a-agent-list` 等），其 `json` / `toon` 输出对**列表形态**的响应按 16 KiB 上限处理。缩减分三级，另外会有一个机读标记： @@ -906,15 +957,19 @@ TOON 不能直接用 `jq` 解析；需要管道给 `jq` 时请改用 `--json`。 **列表信封会被重建并写入缩减标记**。列表信封指行数组名为 `items` / `docs` / `list`、同级只有 `total`、`has_next_page`、`search_after_ctx` 等标量字段的响应（如 `monit datasource-list`、`safari session-list`）；一旦发生缩减，CLI 会重建该信封并在 payload 中补写字段，脚本无需解析 stderr 也能发现缩减： - **整行被丢弃**：写入 `truncated: true` 与 `emitted_rows: N`（N 为实际输出的行数）。此时信封中的 `total`、`has_next_page`、`search_after_ctx` 仍是服务端原始分页的原样回显，**不能**用来判断是否已取全——被截成「100 行中前 7 行」的一页照样带着原来的分页字段。要取全请按实际收到的行数收窄 `--limit` 重新请求，再沿返回的游标继续翻页。 -- **只有长值被截短**（没有丢行）：只写 `truncated: true`，stderr 会点名被截字段。重新请求无法找回这些值，请收窄筛选条件、减少每页行数，或改用支持字段投影的精选命令。 +- **只有长值被截短**（没有丢行）：只写 `truncated: true`，stderr 会点名被截字段。重新请求无法找回这些值，请收窄筛选条件、减少每页行数，或用全局 `--fields` 只保留需要的字段。 + +**行数组还带非标量同级字段的响应不做缩减**。行数组为 `items` / `docs` / `list`、但同级还有对象或数组字段的响应（如 `calendar event-list` 的 `days` 地图），无法在不丢字段的前提下压进 16 KiB，因此整包原样输出、处理方式同本节末段的**明细形态的单个对象**：既不写 `truncated` / `emitted_rows`，也不截短任何值。 **顶层数组形态**的响应（如精选命令 `incident list`、`insight incidents`）没有信封可承载标记，缩减仍只写 stderr。 -**明细形态的单个对象**（如 `safari session-get` 的详情）不做截断、原样输出——截短后的值无法与真实短值区分，因此这类响应不受上限约束。生成命令大多没有可收窄输出的标志（个别命令的 `--fields` 是请求体的字段选择器，不作用于输出）；需要完整 JSON 时请通过 `--limit` 调小每页数量、配合 `--page` 分页逐页拉取（如 `flashduty safari session-list --limit 20 --page 2`），或按需收窄筛选条件。 +**明细形态的单个对象**（如 `safari session-get` 的详情）不做截断、原样输出——截短后的值无法与真实短值区分，因此这类响应不受上限约束。生成命令可以用全局 `--fields` 收窄输出的字段（见「全局参数」与下文「结构化输出的字段投影」；个别命令的 `--fields` 是请求体的字段选择器，如 `monit rule-update-fields`，不作用于输出）；需要完整 JSON 时请通过 `--limit` 调小每页数量、配合 `--page` 分页逐页拉取（如 `flashduty safari session-list --limit 20 --page 2`），或按需收窄筛选条件。 ### 结构化输出的字段投影 -以下命令在 `json` 或 `toon` 输出时支持 `--fields`。用逗号分隔顶层响应字段；未知字段会直接报错，表格输出会忽略此参数。 +`--fields` 是全局参数（见「全局参数」）：任意命令在 `json` 或 `toon` 输出时都能用它，逗号分隔要保留的顶层字段，作用于列表的每一行或单个记录。投影在返回结果上执行：列表信封（行数组为 `items`、`docs` 或 `list`，同级只有标量分页字段）只收窄其中的行数组，分页字段原样保留；某个字段在整个响应里都不存在时不会被写入输出，stderr 会提示该字段未匹配到任何键、并列出实际存在的键；输出既不是对象也不是对象列表时，命令报错并要求去掉 `--fields`。表格输出忽略 `--fields`，此时 stderr 会提示它未生效。 + +下表列出的精选命令在省略 `--fields` 时按默认紧凑投影输出，并受大小上限约束；它们各自定义了自己的 `--fields`（含义与全局一致），字段名写错会直接报错并列出具名可用的字段。其它命令——包括全部生成命令——不带默认投影，`--fields` 直接作用在接口返回的原始字段上，字段名未命中只会得到上面那条 stderr 提示。 | 命令 | 未指定 `--fields` 时的结构化输出 | 上限 | | --- | --- | --- | diff --git a/zh/developer/go-sdk.mdx b/zh/developer/go-sdk.mdx index 1ecada74..f6e1c7db 100644 --- a/zh/developer/go-sdk.mdx +++ b/zh/developer/go-sdk.mdx @@ -153,7 +153,7 @@ client, err := flashduty.NewClientWithAccessToken(accessToken, | `client.Account` | 账户 | | `client.AuditLogs` | 审计日志 | | `client.AlertRules` | 告警规则 | -| `client.RuleFolders` | 规则分组；`List` 列出调用方可读的全部监控规则分组（`POST /monit/folder/list`） | +| `client.RuleFolders` | 规则分组；`ReadList` 列出调用方可读的全部分组（`POST /monit/folder/list`）、`ReadHealth` 取分组健康摘要（`POST /monit/folder/health`，含可见后代分组的活跃告警与规则运行问题）、`WriteCreate` / `WriteUpdate` / `WriteMove` / `WriteDelete` 建改移删分组；旧的 `List` 保留为 `ReadList` 的兼容别名 | | `client.AlertEnrichment` | 告警字段加工 | | `client.DataSources` | 数据源 | | `client.Dashboards` | 仪表盘；面板试跑与执行、面板查询解析（`QueryReadResolve`）、变量解析，以及仪表盘的读写、移动/恢复与修订历史 | @@ -165,7 +165,7 @@ client, err := flashduty.NewClientWithAccessToken(accessToken, | `client.Analytics` | 分析 | | `client.A2aAgents` | A2A Agents | | `client.Artifacts` | AI SRE 产物 | -| `client.Automations` | AI SRE 自动化 | +| `client.Automations` | AI SRE 自动化（`RuleReadGet` / `RuleReadList` / `RuleWriteCreate` / `RuleWriteUpdate` / `RuleWriteDelete` / `RuleWriteRun` / `RunReadList` / `TemplateReadList`）；创建规则时执行位置用 `AutomationRuleCreateRequest.RunIn`（`current-chat` / `web`，省略由服务端决定），作用域用同结构的 `TeamID`（`*int64`：显式 0 表示个人作用域，省略表示继承已认证 IM 会话作用域）；`AutomationRuleUpdateRequest` 已无 `TeamID` | | `client.Knowledge` | AI SRE 知识（每份知识本身与其中的知识文件） | | `client.McpServers` | MCP Servers | | `client.Sessions` | AI SRE 会话 | @@ -198,6 +198,20 @@ client, err := flashduty.NewClientWithAccessToken(accessToken, `client.Artifacts`（AI SRE 产物）对应 `/safari/artifact/*` 的 11 个 API 操作：画廊读取侧 `ReadGet`（按 ID 获取单个已发布产物）、`ReadList`（分页列出调用方可见的产物，支持标题子串搜索、`scope`（`all` / `personal` / `team`）与 `team_ids` 过滤）、`ReadGetFileState`（批量探测会话展示文件是否已有上线产物，单次至多 50 个 ID）；文件侧 `ReadSign`（为展示文件签发短期有效的下载/预览 URL，有效期 5 分钟，`expires_in` 固定 300 秒）与 `ReadStream`（凭签名 token 下载或预览文件，成功响应体是文件而非 JSON 信封，原始字节放在 `Response.Raw`）；写入侧 `WritePublish`（把会话产生的文件发布为画廊产物）、`WriteUpdate`（重命名或转移个人/团队作用域）、`WriteDelete`（从画廊移除，源文件仍保留在会话中）；公开分享 `WriteShareEnable`（开启匿名公开分享并返回公开链接，任何人凭链接即可查看、无需登录）、`WriteShareRevoke`（关闭分享，链接立即失效）、`WriteShareSync`（把公开快照刷新为最新内容——当 `share_enabled` 为 true 且 `share_file_id` 与 `file_id` 不一致时表示快照已过期，调用它刷新）。相关导出类型包括 `PublishedArtifactItem`、`ArtifactShareState`、`SignedUrLs` 以及各 `Artifact*Request` / `Artifact*Response`。 +### AI SRE 自动化规则 + +`client.Automations` 对应 `/safari/automation/*`。规则的**执行目标**（作用域与执行位置）只在创建时确定： + +- `AutomationRuleCreateRequest.RunIn`（`run_in`）取 `current-chat`（把规则绑定到已认证的当前 IM 会话）或 `web`（在 Web 控制台执行）。省略该字段时由服务端决定：已认证的 IM 调用取 `current-chat`，其他调用取 `web`；在实时 IM 会话之外传 `current-chat` 会被服务端拒绝。 +- `AutomationRuleCreateRequest.TeamID`（`team_id`）是 `*int64`：显式传 0 表示个人作用域，大于 0 表示账户内的某个团队；省略时若存在已认证的 IM 会话则继承该会话的作用域，否则由服务端取常规默认值。`current-chat` 规则的作用域必须与该会话一致。 +- `AutomationRuleUpdateRequest` 已不再包含 `TeamID`（同样没有 `RunIn`）：作用域与执行位置创建后不可变。旧代码若在更新请求里设置 `TeamID`，删掉该行即可，否则无法编译。 + +### 规则分组 + +`client.RuleFolders` 覆盖 `/monit/folder/*` 的 6 个操作：`ReadList`（`POST /monit/folder/list`）与 `ReadHealth`（`POST /monit/folder/health`）不带请求体——前者返回扁平的 `[]FolderItem`，要用 `ParentID` / `ParentPath` 自行在客户端重建目录树（仪表盘与告警规则共用这棵树），后者返回 `FolderHealthOutput`，其中 `FolderHealthItem.HasIssue` 标记该分组或其可见后代是否有活跃告警或规则运行问题；写入侧 `WriteCreate`（`/monit/folder/create`）与 `WriteUpdate`（`/monit/folder/update`）返回 `FolderItem`，`WriteMove`（`/monit/folder/move`）与 `WriteDelete`（`/monit/folder/delete`）只返回 `*Response`。相关导出类型还有 `FolderCreateRequest`、`FolderUpdateRequest`、`FolderMoveRequest` 与 `FolderDeleteRequest`。 + +请求字段：`FolderCreateRequest.Name` 必填且不能包含句点、斜杠或逗号，`ParentID` 传 0 或省略即建在顶层；`FolderUpdateRequest` 必须同时传 `ID` 与 `Name`，它替换可编辑字段——省略 `Note` 会清空备注、省略 `TeamID` 会重置为 0（账户级）；`FolderMoveRequest` 即使移回顶层也必须显式传 `DestParentID`（传 0），且不能移动到自身或自己的后代之下；`FolderDeleteRequest` 只带 `ID`，只能删除空分组，分组内还有子分组、告警规则或仪表盘时返回 HTTP 409 与 `FolderNotEmpty`。 + ### 诊断查询 `client.Diagnostics.QueryData` 通过 `POST /monit/query/data` 执行同步查询，返回稳定的 `query_result.v1` 结构化结果（`result.kind` 为 `frames` / `records` / `samples` 之一），要求 monit-edge v0.65.0 及以上版本。日志模式和指标趋势分析统一使用 `client.DataSources.ToolsInvoke`，工具名称为 `prometheus.metric_trends`、`loki.log_patterns` 或 `victorialogs.log_patterns`。 @@ -239,6 +253,20 @@ out, _, err := client.DataSources.ToolsInvoke(ctx, req) `enabled` 与 `alerting_enabled` 相互独立：`enabled`（业务执行开关）创建时默认 true，`alerting_enabled`（是否允许参与告警评估；告警还要求 `enabled` 为 true 且类型支持告警）创建时对告警类型默认 true、对诊断专用类型默认 false；二者更新时省略均保留当前值，显式传 `null` 非法；当有启用的告警规则引用该数据源时，将其 `enabled` 置为 false 会以 conflict 拒绝。另外 `/monit/datasource/list` 响应中 `payload` 恒为 `null`（列表查询不读 payload 列），create/update/info 响应中才会填充。 +### 服务日历事件 + +`client.Calendars` 对应 `/calendar/*`。 + +`CalEventIDRequest`（`CalEventDelete`，`POST /calendar/event/delete`）有两种用法：传 `EventID` 删除单条事件；省略 `EventID` 并同时传 `StartAt` 与 `EndAt`（`YYYY-MM-DD`，`EndAt` 为开区间）则清空该日历自身在这段日期上的事件，被清空的日期回落到关联的节假日日历与每周工作日。两者二选一，`CalID` 始终必填。 + +`CalEventUpsert`（`POST /calendar/event/upsert`）在 `[StartAt, EndAt)` 上创建或更新一条该日历自有的事件（`IsOff` 为 true 表示休息日，false 表示工作日覆盖）：省略 `EventID` 即新建，传入的 `EventID` 必须是该日历已有的自身事件。写入会先把该日历自己的其他事件从同一段日期上摘掉——完全落在范围内的事件被删除，部分重叠的被截短，跨越整个范围的被拆成两段——因此这些日期以最后一次写入为准。`EndAt` 必须晚于 `StartAt`；`Summary` 为选填。 + +`CalEventList`（`POST /calendar/event/list`）用 `CalEventListRequest` 的 `Year` / `Month` / `Day` 划定范围（`Month` 与 `Day` 都为 0 时返回整年）。响应 `CalEventListResponse` 除 `Items`（按 `StartAt` 排序的事件）与 `Total` 外，还有一个必填的 `Days`：`map[string]CalDay`，键为 `YYYY-MM-DD`，给出该范围内每一天的最终状态。每个 `CalDay` 给出 `IsOff`、`EventID`（决定这一天的事件，没有任何事件覆盖时为空）与 `Layer`（`custom` / `holiday` / `weekly`）。日期按层优先级判定：该日历自有事件（`custom`）高于关联的节假日日历（`holiday`），再高于每周工作日（`weekly`）；同一层内工作日事件优先于休息日，因此节假日日历里的调休补班日会盖过节假日休息日。没有任何事件覆盖的日期为工作日。 + +### 故障工作项 + +`client.Incidents` 的 `WorkItem*` 方法（`/incident/work-item/*`）管理故障的行动项与复盘跟进项。工作项状态是封闭枚举：`CreateWorkItemRequest` / `UpdateWorkItemRequest` 的 `Status` 与 `ConvertWorkItemRequest` 的 `TargetStatus` 只接受 `open`、`in_progress`、`done`、`cancelled`，创建时省略或留空即取 `open`，`TargetStatus` 为选填。`WorkItemComplete` 的 `CompleteWorkItemRequest.TargetStatus` 只接受 `done`，传其他值一律被拒绝。 + ## 响应时间戳 响应中的时间字段是自描述的 `Timestamp`（Unix 秒）或 `TimestampMilli`（毫秒）类型（请求与响应共用的类型是例外，见下方警告）。它们序列化为本地时区的 RFC3339 字符串，因此 JSON、日志以及面向 LLM 的输出都直接可读；原始 epoch 仍只需一次方法调用即可取到。 diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 45d699fc..29ecf3cc 100644 --- a/zh/openapi/api-catalog.mdx +++ b/zh/openapi/api-catalog.mdx @@ -515,7 +515,7 @@ Flashduty Open API 提供 **372** 个接口，覆盖 On-call、Monitors、RUM、 | `query` | string | 消息文本，与发送回执帧一致 | | `parts` | array | 消息携带的 parts（`text` / `file` / `ref` / `skill`，原样透传，可选） | -只包含普通人类消息：自动化、子会话通知、父会话初启消息等带 `source` 的消息，以及提问作答（`function_response`）所在的消息不在其中。内容与 `user_message_enqueued` 帧的载荷一致。 +只包含普通人类消息：自动化、子会话通知、父会话初启消息等带 `source` 的消息，以及提问作答（`function_response`）与页面动作的批量回执（`function_responses`）所在的消息不在其中。内容与 `user_message_enqueued` 帧的载荷一致。 </Note> ### 自动化 diff --git a/zh/openapi/introduction.mdx b/zh/openapi/introduction.mdx index 9ed76dc2..05a8b6e3 100644 --- a/zh/openapi/introduction.mdx +++ b/zh/openapi/introduction.mdx @@ -72,6 +72,22 @@ APP Key 的实际可访问范围同时受其权限范围和创建者当前角色 您可以在 APP Key 列表中编辑已有密钥的名称和权限范围。 +### APP Key 泄露了怎么办 + +如果 APP Key 可能已泄露（例如被提交到公开代码仓库，或出现在日志、截图中），请按以下步骤处置： + +<Steps> + <Step title="创建替代密钥"> + 在 **个人中心 → APP Key** 中创建一个新的 APP Key。 + </Step> + <Step title="切换集成"> + 把使用旧密钥的集成、脚本和配置切换到新密钥，并确认调用正常。 + </Step> + <Step title="禁用或删除旧密钥"> + 在 APP Key 列表中禁用或删除旧密钥。之后使用旧密钥的请求返回 `401 Unauthorized`。 + </Step> +</Steps> + ### 传递 APP Key 通过 query 参数 `app_key` 传入： From 63ed200121eaa6d39ef31db1d452f8734d39af03 Mon Sep 17 00:00:00 2001 From: ysyneu <ysyneu@gmail.com> Date: Sat, 17 Oct 2026 03:43:19 -0700 Subject: [PATCH 5/5] docs(changelog): add entries for recent releases --- en/changelog/changelog.mdx | 55 ++++++++++++++++++++++++++++++++++++++ zh/changelog/changelog.mdx | 55 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) diff --git a/en/changelog/changelog.mdx b/en/changelog/changelog.mdx index 2c784ed6..b7a260ff 100644 --- a/en/changelog/changelog.mdx +++ b/en/changelog/changelog.mdx @@ -4,6 +4,61 @@ description: "This page documents important updates and feature releases for Fla keywords: ["Changelog", "Product Release", "Feature Updates", "Flashduty", "Version History"] --- +<Update label="2026-10-16" description="🤖 AI SRE automations can run in the IM chat that created them, RUM Issue gains a resolve mode, DingTalk and Feishu integrations link members automatically on save"> + +### AI SRE automations gain an execution place: rules can be bound to the IM chat that created them + +Each automation rule now has an **execution place**, fixed at creation: **Web** (default) or **IM**. When you ask the agent to create a rule in an IM group or direct chat, the rule is bound to that chat; the console's create entries always create **Web** rules. The execution place cannot be changed afterwards, and the console offers no **Clone** for IM rules. + +Every run of an IM rule opens a new session in the original chat and posts the conclusion back to that chat. If the chat's scope or session has changed by the time the rule fires (for example after `/scope` or `/new`), the run is **skipped** (reason `chat_scope_mismatch`) and the rule stays enabled. The rule list gains an **Execution place** column. See [AI SRE automations](/en/ai-sre/automations#execution-place-where-a-rule-runs). + +### RUM Issue resolve mode: Resolved / Resolve in next release + +The **Resolved** and **Resolve in next release** options in the issue status dropdown are two ways of handling recurrence for the same resolved state: + +- **Resolved**: if the error occurs again, even in the same version, the issue is reopened as pending and marked **regression**. +- **Resolve in next release** (default): the issue reopens only when the error appears in a version the issue has not seen before; repeats within the same version do not reopen it. + +You can switch between the two at any time. See [Issue status management](/en/rum/error-tracking/issue-status). + +### DingTalk and Feishu integrations link members automatically on save + +After you save or edit a DingTalk or Feishu integration, the system tries to link members right away and then rescans every enabled integration hourly: it exchanges each member's profile phone number (Feishu also uses email) for an IM account ID, with no action from the member and no need to sign in through IM first. To retry immediately, click **One-click link** on the integration detail page. WeCom still uses the page's **One-click link**. See [DingTalk](/en/on-call/integration/instant-messaging/dingtalk) and [Feishu](/en/on-call/integration/instant-messaging/lark). + +</Update> + +<Update label="2026-10-15" description="🤖 Let AI configure noise reduction for a channel, investigation-entry preview uses the current form, rule move gets a dialog"> + +### AI-assisted noise reduction: let AI analyze a channel's noise and configure it + +The **Alert grouping** and **Flapping detection** pages under a channel's **Noise reduction** gain a **Let AI configure noise reduction** button (shown when AI SRE is enabled for the account and you can access AI SRE sessions). It opens the AI SRE panel on the right with the channel as context and a prefilled question; the built-in **channel-noise** skill reads the channel's alert history and recommends grouping or flapping settings. + +Only **Alert grouping** and **Flapping detection** can be written, and each change needs your consent first; at the moment of saving, a confirmation card lists each changed field with its before and after values. Event grouping, silence, inhibition and drop rules only get suggestions. See [Noise reduction](/en/on-call/channel/noise-reduction). + +### Alert rules: simpler investigation-entry preview, a dialog for moving rules + +For an investigation entry whose variable values and query contain no `{{`, **Preview jump** uses the form's current values (including unsaved edits) and the current time, so you need not save the rule first and the rule need not have an active alert. Entries that use `{{ }}` still preview from an active alert's configuration snapshot. The default **time range** of a new entry is now **60** minutes before and **30** minutes after the alert. + +Moving rules in the rule list now opens a **Move to another folder** dialog with a search box for folders. See [Alert rules · Investigation entries](/en/monitors/alert-rules/investigation-entries) and [Folders](/en/monitors/folders/folders). + +</Update> + +<Update label="2026-10-12" description="🤖 One-click auto-analysis for RUM issues, AI SRE reads IM attachments, a global field-projection flag in the CLI"> + +### RUM Issue: turn on auto-analysis in one click + +The top right of the issue detail page gains an **Enable auto-analysis** button, shown when AI SRE is enabled for the account and you can create automation rules. It opens the AI SRE automation create form with the preset template "RUM Issue incident analysis" filled in. The application's alerts must be on, delivered to a **Flashduty channel** with at least one channel selected; otherwise you are asked to finish alert settings first. See [Issue overview and details](/en/rum/error-tracking/error-viewing#header-actions). + +### AI SRE reads IM attachments + +AI SRE downloads images, documents and voice messages from the chat and hands them to the agent as files, including attachments on earlier messages in the same thread or chat, not only on the @mention. Per turn: 5 images, 3 documents, 3 voice messages; an attachment over 20 MiB is rejected. See [IM integration · Attachments and images](/en/ai-sre/im#attachments-and-images). + +### CLI: global `--fields` projection + +The CLI gains a global `--fields` flag: with `json` / `toon` output it keeps only the listed top-level fields, on every command including OpenAPI-generated ones. Table output ignores the flag and says so on stderr. See [CLI](/en/developer/cli). + +</Update> + <Update label="2026-10-14" description="🧭 Investigation entries open the exact dashboard or query from an alert, alert-grouping rework, label-panel redesign, weekly and monthly scheduled notifications, dashboard global search"> ### Investigation entries: from an alert straight to a dashboard or the Query Workbench diff --git a/zh/changelog/changelog.mdx b/zh/changelog/changelog.mdx index 33ac5149..b85314d3 100644 --- a/zh/changelog/changelog.mdx +++ b/zh/changelog/changelog.mdx @@ -4,6 +4,61 @@ description: "本页面记录 Flashduty 产品的重要更新和功能发布" keywords: ["更新日志", "产品发布", "功能更新", "Flashduty", "版本记录"] --- +<Update label="2026-10-16" description="🤖 AI SRE 自动化可绑定到发起它的 IM 会话执行、RUM Issue 新增「解决方式」、钉钉与飞书集成保存后自动关联成员"> + +### AI SRE 自动化新增「执行位置」：规则可绑定到发起它的 IM 会话 + +自动化规则现在带一个 **执行位置**，创建时固定，取 **Web**（默认）或 **IM**。在 IM 群聊或私聊里让 Agent 建规则时，规则绑定到当前这个会话；控制台的创建入口始终创建 **Web** 规则。创建后执行位置不能修改，控制台也不提供 IM 规则的 **克隆**。 + +IM 规则的每一次运行都在原来的群聊里新开一个会话，结论也回帖到该群。如果执行时这个群聊的范围或会话已经变了（例如用过 `/scope`、`/new`），本次运行会被 **跳过**（原因 `chat_scope_mismatch`），规则保持启用。规则列表新增 **执行位置** 一列。详见 [AI SRE 自动化](/zh/ai-sre/automations#执行位置规则跑在哪里)。 + +### RUM Issue 新增「解决方式」：已解决 / 在下一版本中解决 + +Issue 状态下拉里的 **已解决** 与 **在下一版本中解决** 是同一个「已解决」状态按复现处理方式拆出的两个选项： + +- **已解决**：该错误之后再出现，即使还是同一个版本，也会把 Issue 重开为待处理并标记 **问题复现**； +- **在下一版本中解决**（默认）：只有 Issue 之前没见过的新版本里再次出现才重开，同一版本里的重复出现不会重开。 + +两个选项可随时互相切换。详见[Issue 状态管理](/zh/rum/error-tracking/issue-status)。 + +### 钉钉与飞书集成保存后自动关联成员 + +保存或编辑钉钉、飞书集成后，系统会立即尝试关联一次成员，之后每小时再扫描一遍已启用的集成：用成员个人资料里的手机号（飞书同时用邮箱）换取 IM 账号 ID，成员不需要手动操作，也不需要先在 IM 里登录一次。想立刻重试时，可在集成详情页点 **一键关联**。企业微信仍用页面上的 **一键关联**。详见[钉钉](/zh/on-call/integration/instant-messaging/dingtalk)与[飞书](/zh/on-call/integration/instant-messaging/lark)。 + +</Update> + +<Update label="2026-10-15" description="🤖 协作空间降噪新增「让 AI 帮我配置降噪」、调查入口预览按当前配置直接预览、规则移动改为对话框"> + +### AI 辅助降噪：让 AI 分析协作空间的噪音并直接配置 + +协作空间详情 → **降噪处理** 下的 **告警聚合** 与 **抖动检测** 两页，页头新增 **让 AI 帮我配置降噪** 按钮（账户已开启 AI SRE、且您有 AI SRE 会话访问权限时显示）。点击后右侧打开 AI SRE 面板，自动带上该协作空间的上下文和一句预填提问，由内置 **channel-noise** Skill 读取该空间的告警历史，给出聚合或抖动检测的建议。 + +真正会写进配置的只有 **告警聚合** 与 **抖动检测** 两项，且每次都先征求同意；保存的瞬间还会弹出确认卡片，逐行列出变更前后的值。事件聚合、静默、抑制与丢弃规则只给改动建议。详见[告警降噪](/zh/on-call/channel/noise-reduction)。 + +### 告警规则：调查入口预览更省事，规则移动有了对话框 + +变量取值与查询语句里都不含 `{{` 的调查入口，**预览跳转** 直接按表单当前的值（包括还没保存的修改）与当前时间预览，不需要先保存规则，也不要求规则已有活跃告警；用了 `{{ }}` 的入口仍从活跃告警里选一条，按告警事件里的配置快照预览。新建调查入口的 **时间范围** 默认值改为告警前 **60** 分钟 / 告警后 **30** 分钟。 + +规则列表的移动操作换成 **移动到其他分组** 对话框，顶部可搜索分组。详见[告警规则 · 调查入口](/zh/monitors/alert-rules/investigation-entries)与[文件夹管理](/zh/monitors/folders/folders)。 + +</Update> + +<Update label="2026-10-12" description="🤖 RUM Issue 一键开启自动分析、AI SRE 读取 IM 附件、CLI 新增全局字段投影参数"> + +### RUM Issue：一键开启自动分析 + +Issue 详情页右上角新增 **开启自动分析** 按钮，账户已开启 AI SRE、且当前成员有创建自动化规则的权限时显示：点击后打开 AI SRE 自动化的创建表单，预填预设模板「RUM Issue 故障分析」。该应用的告警需已开启、投递方式为 **Flashduty 协作空间** 并至少选了一个协作空间，否则会提示先完成告警设置。详见 [Issue 概览与详情](/zh/rum/error-tracking/error-viewing#头部操作)。 + +### AI SRE 读取 IM 附件 + +AI SRE 会把聊天里的图片、文档与语音下载下来作为文件交给 Agent，不只是 @ 它那条消息上的附件，同一线程 / 会话里更早的消息上的附件也会带上。每轮额度：图片 5 个、文档 3 个、语音 3 个；单个附件超过 20 MiB 会被拒绝。详见 [IM 集成 · 附件与图片](/zh/ai-sre/im#附件与图片)。 + +### CLI：全局 `--fields` 字段投影 + +CLI 新增全局参数 `--fields`：`json` / `toon` 输出时只保留逗号分隔的顶层字段，所有命令都可用，OpenAPI 生成的命令也在内。表格输出忽略该参数并在 stderr 提示。详见[命令行工具](/zh/developer/cli)。 + +</Update> + <Update label="2026-10-14" description="🧭 调查入口一键直达观测、告警聚合改版、标签面板重做、定时通知支持每周与每月、仪表盘全局搜索"> ### 调查入口：从告警一键跳到仪表盘或查询工作台