Merge pull request #155 from flashcatcloud/doc-review/auto-20260710-031713

docs: update API key and AI SRE workflows

Author: ysyneu

en/ai-sre/agents.mdx

@@ -135,7 +135,7 @@ A2A agents support three credential-supply modes that determine how credentials
     Each user provides their own key on first use; the key is encrypted and stored at the account level. Configure the Header name (required), placeholder, and help link (optional) in the Key Schema to guide users on first call.
   </Accordion>
   <Accordion title="Per-user OAuth (per_user_oauth)" icon="shield-halved">
-    Each user authorizes via the OAuth 2.1 flow; an authorization window pops up automatically on the first call to this A2A agent, and credentials are stored per user after completion.
+    Each user authorizes via the OAuth 2.1 flow; an authorization window pops up automatically on the first call to this A2A agent, and credentials are stored per user after completion. Before authorizing, choose an **execution environment** in the Credential dialog: a Cloud Sandbox or an online BYOC Runner; **Auto** is unavailable. OAuth requests run from the selected environment, so choose a BYOC Runner that can reach the service when its OAuth endpoint is private.
   </Accordion>
 </AccordionGroup>
 

en/ai-sre/automations.mdx

@@ -126,7 +126,19 @@ curl -X POST 'https://<trigger-url>' \
   -d '{"text":"Describe the event or context for this run."}'
 ```
 
-The `text` in the request body is passed to the agent as context for this run, on top of the task prompt configured on the rule. The optional `dedup_key` provides idempotency: the same trigger with the same `dedup_key` reuses the same run.
+The `text` in the request body is passed to the agent as context for this run, on top of the task prompt configured on the rule.
+
+On success, `data` returns the new hidden session. Save `session_id`, or use `session_url` to open the full conversation, tool calls, and artifacts for this run:
+
+```json
+{
+  "data": {
+    "type": "routine_fire",
+    "session_id": "<session-id>",
+    "session_url": "https://<console>/ai-sre/chat?session_id=<session-id>"
+  }
+}
+```
 
 <Tip>
 A rule can enable **both** "Schedule" and "Call via API" at the same time: it runs automatically on the cadence and can also be kicked off on demand from outside. Each trigger occupies its own row and can be **removed** independently.

en/ai-sre/mcp.mdx

@@ -147,11 +147,11 @@ Per-User API Key and per-user OAuth credentials are isolated **per user**, so be
 - **○ Disconnected**: no credential provided yet.
 - **⚠ Expired**: the credential has expired (OAuth token lapsed) and needs re-authorization.
 
-Shared-mode MCP servers have no per-user authorization step and render a dash ("—"). The chip is read-only; all authorization actions live in the MCP server's edit form.
+Shared-mode MCP servers have no per-user authorization step and render a dash ("—"). For a server that needs your personal credential, open the **Credential** dialog from its authorization entry in the list. It manages only your credential and never changes the server endpoint, authentication mode, or scope.
 
-**Actions in the edit form**: open an MCP server's edit form, and the **Authorization** section offers actions based on its authentication mode and your current credential state:
+**Actions in the Credential dialog**: the dialog offers actions based on its authentication mode and your current credential state:
 
-- **Per-User OAuth**: click **Authorize** (when disconnected) / **Reauthorize** (when connected or expired). A browser popup opens the authorization window (initiated via `/safari/credentials/oauth/initiate`, which returns an authorize URL opened in the popup).
+- **Per-User OAuth**: first choose an **execution environment**, then click **Authorize** (when disconnected) / **Reauthorize** (when connected or expired). Choose a Cloud Sandbox or an online BYOC Runner; **Auto** is not available. OAuth discovery, Dynamic Client Registration, token exchange, and later refreshes all run from that environment. On each open, the dialog prefers the last successful environment if it is still online, then an online runner bound to the connector, and finally the Cloud Sandbox. For an OAuth service reachable only on a private network, choose a BYOC Runner that can reach it. A browser popup then opens the authorization window (initiated via `/safari/credentials/oauth/initiate`, which returns an authorize URL opened in the popup).
 - **Per-User API Key**: click **Enter Key** (when disconnected) / **Update Key** (when connected) to open the secret-entry modal, which submits to `/safari/credentials/secret`.
 - **Revoke**: when a credential exists, click **Revoke** (via `/safari/credentials/revoke`) to delete your saved credential; the status returns to Disconnected.
 

en/monitors/quickstart/quickstart.mdx

@@ -71,7 +71,7 @@ There may be many alert rules. Monitors provides a tree-structured grouping for
 
 | Config Item | Description |
 |--------|------|
-| **Rule Name** | Name of the alert rule; does not support variable references (fixed names facilitate filtering and grouping operations) |
+| **Rule Name** | Name of the alert rule; does not support variable references (fixed names facilitate filtering and grouping operations). It must be unique within its group; imports, edits, and moves fail if the target group already contains that name |
 | **Additional Labels** | Similar to `labels` in Prometheus; attached to all alert events for filtering, routing, and inhibition |
 
 ### Data Source Selection

en/on-call/configuration/personal-settings.mdx

@@ -65,9 +65,11 @@ APP Keys are used for API request authentication.
 | Limit | Description |
 | --- | --- |
 | **Maximum Count** | Up to 5 per account |
-| **Permission Scope** | Has all API operation permissions |
+| **Permission Scope** | Choose **All permissions** or **Custom permissions**. All permissions adds no API restriction but remains limited by your current role; Custom permissions allows only the selected API scopes |
 | **Security Note** | Only displayed at creation, please save securely |
 
+When creating or editing an APP Key, choose its mode under **Permission Scope**. To give a script or third-party tool only the access it needs, select **Custom permissions** and choose its required API scopes. You must select at least one scope before saving. A key's scope never expands the permissions already granted to your current role.
+
 <Warning>
 - APP Key leakage may cause data security risks, please keep it confidential
 - Confirm no business dependencies before deletion; services using that key will fail immediately after deletion

zh/ai-sre/agents.mdx

@@ -135,7 +135,7 @@ A2A Agent 支持三种凭证供给方式，决定不同用户调用同一个远
     每个用户在首次调用时单独提供自己的密钥，密钥加密存储在账户级别。需在「密钥 Schema」中配置 Header 名称（必填）、占位符与帮助链接（可选），供首次调用时引导用户填写。
   </Accordion>
   <Accordion title="每用户 OAuth（per_user_oauth）" icon="shield-halved">
-    用户通过 OAuth 2.1 流程各自授权；首次调用该 A2A Agent 时自动弹出授权窗口，完成后凭证按用户隔离保存。
+    用户通过 OAuth 2.1 流程各自授权；首次调用该 A2A Agent 时自动弹出授权窗口，完成后凭证按用户隔离保存。授权前需在凭证对话框选择**执行环境**：可选云端 Sandbox 或在线的 BYOC Runner，不能使用「自动」。OAuth 请求从所选环境发起；远端 OAuth 服务仅在内网可达时，请选择能够访问它的 BYOC Runner。
   </Accordion>
 </AccordionGroup>
 

zh/ai-sre/automations.mdx

@@ -126,7 +126,19 @@ curl -X POST 'https://<触发地址>' \
   -d '{"text":"描述本次运行的事件或上下文。"}'
 ```
 
-请求体里的 `text` 会作为本次运行的上下文交给 Agent，叠加在规则配置好的任务提示词之上；可选的 `dedup_key` 用于幂等，相同 trigger 与相同 `dedup_key` 会复用同一次运行。
+请求体里的 `text` 会作为本次运行的上下文交给 Agent，叠加在规则配置好的任务提示词之上。
+
+请求成功后，响应的 `data` 会返回新建隐藏会话的信息。你可以保存 `session_id`，或直接使用 `session_url` 打开这次运行的完整对话、工具调用和产物：
+
+```json
+{
+  "data": {
+    "type": "routine_fire",
+    "session_id": "<session-id>",
+    "session_url": "https://<console>/ai-sre/chat?session_id=<session-id>"
+  }
+}
+```
 
 <Tip>
 一条规则可以 **同时** 启用「按周期执行」与「经 API 调用」：到点自动跑，也允许外部按需拉起。每种触发方式各占一行，可分别 **移除**。

zh/ai-sre/mcp.mdx

@@ -147,11 +147,11 @@ MCP 服务器支持三种**认证模式**，决定凭证如何提供给服务器
 - **○ 未连接**：尚未提供凭证。
 - **⚠ 已过期**：凭证已过期（OAuth 令牌到期），需重新授权。
 
-共享模式的 MCP 服务器不涉及按用户授权，此处显示为「—」。该角标只读，所有授权操作都在 MCP 服务器的编辑表单里。
+共享模式的 MCP 服务器不涉及按用户授权，此处显示为「—」。对需要个人凭证的服务器，从列表的授权入口打开**凭证**对话框；它只管理您自己的凭证，不会修改服务器的端点、认证模式或作用域配置。
 
-**编辑表单里的授权操作**：打开某台 MCP 服务器的编辑表单，「授权」区块会根据其认证模式与您当前的凭证状态给出操作：
+**凭证对话框里的授权操作**：对话框会根据其认证模式与您当前的凭证状态给出操作：
 
-- **每用户 OAuth**：点击 **去授权**（未连接时）/ **重新授权**（已连接或已过期时），浏览器会弹出授权窗口（经 `/safari/credentials/oauth/initiate` 发起，返回授权链接后在弹窗中打开）。
+- **每用户 OAuth**：先选择**执行环境**，再点击 **去授权**（未连接时）/ **重新授权**（已连接或已过期时）。可选择云端 Sandbox 或在线的 BYOC Runner，不能选择「自动」；OAuth 的发现、动态客户端注册、令牌交换和后续刷新都从所选环境发起。每次打开时会优先预选上次成功授权且仍在线的环境，否则预选绑定且在线的 Runner，最后回退到云端 Sandbox。OAuth 服务只能从内网访问时，请选择能访问它的 BYOC Runner。浏览器随后会弹出授权窗口（经 `/safari/credentials/oauth/initiate` 发起，返回授权链接后在弹窗中打开）。
 - **每用户密钥**：点击 **填密钥**（未连接时）/ **更新密钥**（已连接时），弹出密钥录入弹窗，提交到 `/safari/credentials/secret`。
 - **撤销**：已有凭证时可点击 **撤销**（经 `/safari/credentials/revoke`）删除自己保存的凭证，状态回到「未连接」。
 

zh/monitors/quickstart/quickstart.mdx

@@ -72,7 +72,7 @@ keywords: ["入门指南", "monitedge", "数据源", "告警规则", "快速开
 
 | 配置项 | 说明 |
 |--------|------|
-| **规则名称** | 告警规则的名称，不支持引用变量（固定名称便于过滤、聚合操作） |
+| **规则名称** | 告警规则的名称，不支持引用变量（固定名称便于过滤、聚合操作）。同一分组内必须唯一；导入、编辑或移动规则时如与目标分组中已有规则重名，操作会失败 |
 | **附加标签** | 类似 Prometheus 中的 `labels`，会附加到所有告警事件上，便于过滤、路由、抑制 |
 
 ### 数据源选择

zh/on-call/configuration/personal-settings.mdx

@@ -66,9 +66,11 @@ APP Key 用于 API 请求认证。
 | 限制 | 说明 |
 | --- | --- |
 | **数量上限** | 每个账号最多 5 个 |
-| **权限范围** | 拥有全部 API 操作权限 |
+| **权限范围** | 可选**全部权限**或**自定义权限**。全部权限不额外限制接口，但仍受当前用户角色权限约束；自定义权限只允许访问选中的接口范围 |
 | **安全提示** | 仅创建时显示，请妥善保存 |
 
+创建或编辑 APP Key 时，在「权限范围」中选择权限模式。需要为脚本或第三方工具提供最小权限时，选择**自定义权限**，再勾选它实际需要调用的接口；至少选择一个接口范围才能保存。权限范围不会扩大当前用户角色本来拥有的权限。
+
 <Warning>
 - APP Key 泄露可能导致数据安全风险，请务必保密
 - 删除前确认无业务依赖，删除后引用该 Key 的业务将立即失效