From 9da161fe6abe0a7fe3d1fbe627a64623efca2878 Mon Sep 17 00:00:00 2001 From: "flashduty[bot]" Date: Thu, 8 Oct 2026 08:14:49 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20doc-review=202026-10-08=20(diff)=20?= =?UTF-8?q?=E2=80=94=20CLI=20integration=20group,=20dashboard=20commands,?= =?UTF-8?q?=20API=20counts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - cli.mdx: add the new top-level integration command group to the coverage list - cli.mdx: correct the OpenAPI operation counts 338/334 -> 365/361 - cli.mdx: document monit dashboard-* and folder-list commands - personal-settings.mdx: drop Xiaomi from the Android app store list (delisted in console) - vs-pagerduty.mdx: 334 -> 361 generated CLI commands --- en/developer/cli.mdx | 31 +++++++++++++++++-- en/on-call/comparison/vs-pagerduty.mdx | 2 +- .../configuration/personal-settings.mdx | 2 +- zh/developer/cli.mdx | 31 +++++++++++++++++-- zh/on-call/comparison/vs-pagerduty.mdx | 2 +- .../configuration/personal-settings.mdx | 2 +- 6 files changed, 62 insertions(+), 8 deletions(-) diff --git a/en/developer/cli.mdx b/en/developer/cli.mdx index e9ba9776f..fd6eac427 100644 --- a/en/developer/cli.mdx +++ b/en/developer/cli.mdx @@ -595,6 +595,33 @@ 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) + +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 dashboard-list # 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 # Read a dashboard, including its definition and current revision +flashduty monit dashboard-outline # Read the tab / section / panel outline; --target-id keeps only the branch holding it +flashduty monit dashboard-create [flags] # Create: --dashboard-id (UUIDv7), --folder-id, --schema-version, and the definition in --data +flashduty monit dashboard-update [flags] # Update, with --message for a revision note +flashduty monit dashboard-move [flags] # Move to another folder without touching the definition +flashduty monit dashboard-delete [flags] # Delete: moves the dashboard to the trash, it is not removed outright +flashduty monit dashboard-trash-list # List trashed dashboards (kept for 30 days) +flashduty monit dashboard-restore [flags] # Restore from the trash; omit --folder-id to restore to the original folder, which must be passed explicitly when that folder is no longer writable +flashduty monit dashboard-revisions-list # List the revision history +flashduty monit dashboard-revisions-get --revision # Read the definition stored at one revision +flashduty monit dashboard-panel-run [flags] # Run a single panel: --dashboard-id, --panel-id; time and variables go in --data +flashduty monit dashboard-panel-preview # Preview a draft panel that has not been saved +flashduty monit dashboard-runtime-variables-resolve # Resolve dashboard variables (candidates and the effective selection) +flashduty monit dashboard-runtime-variables-preview # Preview draft variables +flashduty monit dashboard-runtime-queries-resolve [...] # Resolve panel queries: expressions with variables substituted, and the bound datasource +``` + +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. + #### `prometheus-api-v1-label-{label_name}-values` — Query Prometheus label values `GET /monit/prometheus/api/v1/label/{label_name}/values` (operationId `monit-prometheus-read-label-values`) carries a path parameter, so it is excluded from code generation and provided by a hand-written command. The command name follows the generated path-derived naming (the `monit` group plus the remaining path segments joined by hyphens), so it shows up under `flashduty monit --help` but cannot be guessed intuitively — use it as written here: @@ -691,14 +718,14 @@ In `json`/`toon` mode the rows default to the compact fields `incident_id`, `tit ### Full command coverage -Beyond the curated commands above, the CLI now provides **full coverage** of the Flashduty OpenAPI through a spec-driven code generator. The OpenAPI spec the generator reads contains **338 API operations**, and the CLI generates resource-organized commands for **334** of them; the remaining four are provided by hand-written commands — the streaming export `session-read-export` (`session export`), the multipart uploads `mapping-data-write-upload` and `skill-write-upload` (`enrichment mapping-data-upload`, `safari skill-upload`), and the path-parameterized `monit-prometheus-read-label-values` (`monit prometheus-api-v1-label-{label_name}-values`, see "Query Prometheus label values" below) — and are organized into top-level command groups alongside the generated ones. In addition to the On-call domain (incident, incident-trigger-subscription, change, channel, field, status-page, template, and more), it also covers: +Beyond the curated commands above, the CLI now provides **full coverage** of the Flashduty OpenAPI through a spec-driven code generator. The OpenAPI spec the generator reads contains **365 API operations**, and the CLI generates resource-organized commands for **361** of them; the remaining four are provided by hand-written commands — the streaming export `session-read-export` (`session export`), the multipart uploads `mapping-data-write-upload` and `skill-write-upload` (`enrichment mapping-data-upload`, `safari skill-upload`), and the path-parameterized `monit-prometheus-read-label-values` (`monit prometheus-api-v1-label-{label_name}-values`, see "Query Prometheus label values" below) — and are organized into top-level command groups alongside the generated ones. In addition to the On-call domain (incident, incident-trigger-subscription, change, channel, field, status-page, template, and more), it also covers: - **AI SRE (`safari`)**: a2a-agents, artifacts, automations, knowledge, mcp-servers, sessions, skills, and more - **Alerting & noise reduction**: alert, alert-event, enrichment (alert-rules, rule-sets), route - **On-call & scheduling**: calendar, schedule - **Platform administration**: account, member, person, team, role (roles-permissions), audit (audit-logs) - **Monitoring & RUM**: monit, rum, sourcemap -- **Integrations & webhooks**: datasource (IM integrations), webhook (integrations) +- **Integrations & webhooks**: datasource (IM integrations), integration (create, read, update, delete and key-rotation for alert- and change-source integrations), webhook (integrations) These generated leaf commands use a `resource-action` naming form (e.g. `flashduty safari a2a-agent-get`, `flashduty safari session-list`); their inputs and response fields map directly to the corresponding API. Explore them level by level with `flashduty --help`: diff --git a/en/on-call/comparison/vs-pagerduty.mdx b/en/on-call/comparison/vs-pagerduty.mdx index 1e9c69ecc..1b34ce662 100644 --- a/en/on-call/comparison/vs-pagerduty.mdx +++ b/en/on-call/comparison/vs-pagerduty.mdx @@ -230,7 +230,7 @@ Before reaching the team, alerts pass through routing, filtering, and transforma | Tool | Flashduty | PagerDuty | | --- | --- | --- | | **[Open API](/en/openapi/api-catalog)** | 330+ endpoints covering On-call, Monitors, RUM, AI SRE, and platform management, with bilingual docs | ✅ Full-featured REST API, mature documentation | -| **[CLI](/en/developer/cli)** | 334 generated API operation commands (plus four hand-written ones) + built-in Agent Skills, ready to hand directly to AI coding tools like Claude Code, Cursor, and Codex | No official CLI actively promoted: the community's most-used `pagerduty-cli` is an employee's personal project (officially not endorsed, and the author has announced it's archived); the official go-pagerduty library ships a limited `pd` command-line tool | +| **[CLI](/en/developer/cli)** | 361 generated API operation commands (plus four hand-written ones) + built-in Agent Skills, ready to hand directly to AI coding tools like Claude Code, Cursor, and Codex | No official CLI actively promoted: the community's most-used `pagerduty-cli` is an employee's personal project (officially not endorsed, and the author has announced it's archived); the official go-pagerduty library ships a limited `pd` command-line tool | | **SDK** | [Go SDK](/en/developer/go-sdk): a go-github-style wrapper covering 330+ API operations across 39 services | PagerDuty officially maintains go-pagerduty, python-pagerduty, and other client libraries | | **[Terraform Provider](/en/developer/terraform)** | 12 resource types + 13 data source types, managing collaboration spaces, escalation policies, schedules, and more as IaC | ✅ Official Terraform Provider, mature ecosystem | | **[MCP Server](/en/developer/mcp-server)** | 8 tool sets with 23 tools, deployable remotely, via Docker, or from source | ✅ Official MCP Server | diff --git a/en/on-call/configuration/personal-settings.mdx b/en/on-call/configuration/personal-settings.mdx index 6fa8d6b31..dacdf1402 100644 --- a/en/on-call/configuration/personal-settings.mdx +++ b/en/on-call/configuration/personal-settings.mdx @@ -166,7 +166,7 @@ When creating or editing an APP Key, choose its mode under **Permission Scope**. | Platform | Download Method | | --- | --- | | **iOS** | Search "Flashduty" in App Store | -| **Android** | Available on major app stores including Xiaomi, Huawei, Honor, OPPO, and vivo — search "Flashduty" to download (Harmony OS not currently supported) | +| **Android** | Available on major app stores including Huawei, Honor, OPPO, and vivo — search "Flashduty" to download (Harmony OS not currently supported) | If your phone brand is not listed above, you can click **Download here** on the APP management page to get an installation package QR code. Scan it with your phone to download. diff --git a/zh/developer/cli.mdx b/zh/developer/cli.mdx index 54ca8ee72..8a77c6046 100644 --- a/zh/developer/cli.mdx +++ b/zh/developer/cli.mdx @@ -595,6 +595,33 @@ flashduty monit datasource-delete --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） + +`monit dashboard-*` 命令族管理监控仪表盘（由 OpenAPI 生成命令提供）。仪表盘本身是一份 `dashboard.v1` 文档，创建与更新时通过 `--data` 传入 `definition`；`update` / `delete` / `move` / `restore` 都要求 `--expected-revision`——传入的版本不是当前版本时以 `DashboardRevisionConflict` 拒绝，需要重新读取后再提交。 + +```bash +flashduty monit folder-list # 列出全部监控规则分组，用于取 folder-id（返回顶层数组，用 jq '.[]'） +flashduty monit dashboard-list # 列出某个分组下的仪表盘（分页信封，用 jq '.items[]'） +flashduty monit dashboard-search --query "支付" # 按标题与描述搜索仪表盘（至少一个词） +flashduty monit dashboard-get # 读取仪表盘详情，含 definition 与当前 revision +flashduty monit dashboard-outline # 读取页签 / 分组 / 面板大纲；--target-id 只看包含该 ID 的分支 +flashduty monit dashboard-create [flags] # 新建：--dashboard-id（UUIDv7）、--folder-id、--schema-version、--data 里的 definition +flashduty monit dashboard-update [flags] # 更新，可用 --message 写一条版本说明 +flashduty monit dashboard-move [flags] # 移动到其它分组，不改 definition +flashduty monit dashboard-delete [flags] # 删除：移入回收站，不是物理删除 +flashduty monit dashboard-trash-list # 列出回收站中的仪表盘（保留 30 天） +flashduty monit dashboard-restore [flags] # 从回收站恢复；省略 --folder-id 还原到原分组，原分组已不可写时必须显式指定 +flashduty monit dashboard-revisions-list # 列出版本历史 +flashduty monit dashboard-revisions-get --revision # 读取某个版本保存的 definition +flashduty monit dashboard-panel-run [flags] # 运行单个面板：--dashboard-id、--panel-id，time 与 variables 走 --data +flashduty monit dashboard-panel-preview # 预览尚未保存的草稿面板 +flashduty monit dashboard-runtime-variables-resolve # 解析仪表盘变量（返回候选与生效选择） +flashduty monit dashboard-runtime-variables-preview # 预览草稿变量 +flashduty monit dashboard-runtime-queries-resolve [...] # 解析面板查询：变量替换后的表达式与绑定到的数据源 +``` + +面板运行时与变量解析的时间窗口、变量选择都以 JSON 对象放在 `--data` 里（时间用 `from_ms` / `to_ms` 的毫秒时间戳）。`dashboard-panel-preview` 与 `dashboard-runtime-variables-preview` 需要一个 `context`：`kind: existing` 配 `dashboard_id` 指向已存仪表盘，`kind: new` 配 `folder_id` 指向尚未落库的分组。 + #### `prometheus-api-v1-label-{label_name}-values` — 查询 Prometheus 标签值 `GET /monit/prometheus/api/v1/label/{label_name}/values`（operationId `monit-prometheus-read-label-values`）带路径参数，因此不参与代码生成，由手工实现命令提供。命令名沿用生成命令的路径派生写法（`monit` 组 + 路径剩余段连字符拼接），因此在 `flashduty monit --help` 下可见、但无法按直觉猜到，需要按本节的写法使用： @@ -691,14 +718,14 @@ flashduty insight incident-export [flags] # 导出筛选后的故障列表为 ### 全量命令覆盖 -除上述精选命令外，CLI 现已通过 spec 驱动的代码生成实现对 Flashduty OpenAPI 的**全量覆盖**。CLI 生成器读取的 OpenAPI 规范含 **338 个 API 操作**，CLI 为其中 **334 个** 生成对应命令，其余 4 个以手工实现命令提供——流式导出的 `session-read-export`（`session export`）、multipart 表单上传的 `mapping-data-write-upload` 与 `skill-write-upload`（`enrichment mapping-data-upload`、`safari skill-upload`）、带路径参数的 `monit-prometheus-read-label-values`（`monit prometheus-api-v1-label-{label_name}-values`，见下文「查询 Prometheus 标签值」）——并与生成命令一并按资源组织为顶层命令组。除 On-call 域（incident、incident-trigger-subscription、change、channel、field、status-page、template 等）外，还覆盖了： +除上述精选命令外，CLI 现已通过 spec 驱动的代码生成实现对 Flashduty OpenAPI 的**全量覆盖**。CLI 生成器读取的 OpenAPI 规范含 **365 个 API 操作**，CLI 为其中 **361 个** 生成对应命令，其余 4 个以手工实现命令提供——流式导出的 `session-read-export`（`session export`）、multipart 表单上传的 `mapping-data-write-upload` 与 `skill-write-upload`（`enrichment mapping-data-upload`、`safari skill-upload`）、带路径参数的 `monit-prometheus-read-label-values`（`monit prometheus-api-v1-label-{label_name}-values`，见下文「查询 Prometheus 标签值」）——并与生成命令一并按资源组织为顶层命令组。除 On-call 域（incident、incident-trigger-subscription、change、channel、field、status-page、template 等）外，还覆盖了： - **AI SRE（`safari`）**：a2a-agents、artifacts、automations、knowledge、mcp-servers、sessions、skills 等 - **告警与降噪**：alert、alert-event、enrichment（alert-rules、rule-sets）、route - **On-call 与日程**：calendar、schedule - **平台管理**：account、member、person、team、role（roles-permissions）、audit（audit-logs） - **监控与 RUM**：monit、rum、sourcemap -- **集成与 Webhook**：datasource（IM 集成）、webhook（integrations） +- **集成与 Webhook**：datasource（IM 集成）、integration（告警源 / 变更源集成的增删改查与密钥轮换）、webhook（integrations） 这些生成命令的叶子名称采用「资源-动作」形式（如 `flashduty safari a2a-agent-get`、`flashduty safari session-list`），其入参与返回字段直接映射到对应 API。鼓励用 `flashduty <资源> --help` 逐层探索： diff --git a/zh/on-call/comparison/vs-pagerduty.mdx b/zh/on-call/comparison/vs-pagerduty.mdx index e7dedbed3..359d2255d 100644 --- a/zh/on-call/comparison/vs-pagerduty.mdx +++ b/zh/on-call/comparison/vs-pagerduty.mdx @@ -230,7 +230,7 @@ PagerDuty AIOps 在超大规模事件关联场景上打磨多年，能力成熟 | 工具 | Flashduty | PagerDuty | | --- | --- | --- | | **[Open API](/zh/openapi/api-catalog)** | 330+ 个接口，覆盖 On-call、Monitors、RUM、AI SRE 与平台管理，双语文档 | ✅ REST API 完善，文档成熟 | -| **[CLI](/zh/developer/cli)** | 334 个生成的 API 操作命令（另有 4 个手工命令）+ 内置 Agent Skills，可直接配给 Claude Code、Cursor、Codex 等 AI 编程工具 | 无官方力推的完整 CLI：社区最常用的 `pagerduty-cli` 为员工个人项目（官方声明不背书、作者已宣布归档），官方 go-pagerduty 库附带功能有限的 `pd` 命令行小工具 | +| **[CLI](/zh/developer/cli)** | 361 个生成的 API 操作命令（另有 4 个手工命令）+ 内置 Agent Skills，可直接配给 Claude Code、Cursor、Codex 等 AI 编程工具 | 无官方力推的完整 CLI：社区最常用的 `pagerduty-cli` 为员工个人项目（官方声明不背书、作者已宣布归档），官方 go-pagerduty 库附带功能有限的 `pd` 命令行小工具 | | **SDK** | [Go SDK](/zh/developer/go-sdk)：go-github 风格封装，覆盖 330+ 个 API 操作、39 个服务 | 官方维护 go-pagerduty、python-pagerduty 等客户端库 | | **[Terraform Provider](/zh/developer/terraform)** | 12 类资源 + 13 类数据源，IaC 管理协作空间、分派策略、值班表等 | ✅ 官方 Terraform Provider，生态成熟 | | **[MCP Server](/zh/developer/mcp-server)** | 8 个工具集 23 个工具，支持远程、Docker、源码三种部署 | ✅ 官方 MCP Server | diff --git a/zh/on-call/configuration/personal-settings.mdx b/zh/on-call/configuration/personal-settings.mdx index 469fad2a4..e2e2865c3 100644 --- a/zh/on-call/configuration/personal-settings.mdx +++ b/zh/on-call/configuration/personal-settings.mdx @@ -167,7 +167,7 @@ APP Key 用于 API 请求认证。 | 平台 | 下载方式 | | --- | --- | | **iOS** | App Store 搜索"Flashduty" | -| **Android** | 已上架小米、华为、荣耀、OPPO、vivo 等主流应用市场，搜索"Flashduty"即可下载（暂不支持鸿蒙） | +| **Android** | 已上架华为、荣耀、OPPO、vivo 等主流应用市场，搜索"Flashduty"即可下载（暂不支持鸿蒙） | 如果您使用的手机品牌不在以上列表中，可以在 APP 管理页面点击**点此下载**获取安装包二维码，使用手机扫描即可下载。