> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 命令行工具
> 使用 Flashduty CLI 在终端中管理故障、值班、状态页和通知模板
## 概述
Flashduty CLI（`flashduty`）是一款命令行工具，可在终端中完成故障生命周期管理、值班查询、状态页发布、通知模板调试等操作，适用于运维脚本、本地排障以及与 AI 编程代理协同工作。
工具开源在 [flashcatcloud/flashduty-cli](https://github.com/flashcatcloud/flashduty-cli)，支持 macOS、Linux 和 Windows。
## 安装
```bash theme={null}
curl -sSL https://static.flashcat.cloud/flashduty-cli/install.sh | sh
```
默认安装到 `/usr/local/bin`，可通过环境变量 `FLASHDUTY_INSTALL_DIR` 自定义。
```powershell theme={null}
irm https://static.flashcat.cloud/flashduty-cli/install.ps1 | iex
```
默认安装到 `~\.flashduty\bin`，可通过环境变量 `FLASHDUTY_INSTALL_DIR` 自定义。
访问 [CDN 最新版本指针](https://static.flashcat.cloud/flashduty-cli/releases/latest) 获取最新版本号，然后从 `https://static.flashcat.cloud/flashduty-cli/releases/download//` 下载对应平台的二进制包，解压后放入 `PATH` 即可。
### 安装选项
| 环境变量 | 说明 | 默认值 |
| --------------------------- | ----------------------------------------- | ------------------------------------------------------ |
| `FLASHDUTY_VERSION` | 安装指定版本，如 `v0.6.0` | 最新版本 |
| `FLASHDUTY_INSTALL_DIR` | 安装目录 | `/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` |
## 认证
### 登录
```bash theme={null}
flashduty login
```
按提示输入 APP Key。获取方式：登录 [Flashduty 控制台](https://console.flashcat.cloud)，进入 **个人中心 > 个人信息**，复制 APP Key。
### 凭证解析顺序
CLI 按以下优先级查找 APP Key（高优先级在前）：
1. `--app-key` 命令行参数（脚本场景使用）
2. `FLASHDUTY_APP_KEY` 环境变量
3. 配置文件 `~/.flashduty/config.yaml`（由 `flashduty login` 写入）
### 配置文件
存储在 `~/.flashduty/config.yaml`，权限为 `0600`：
```yaml theme={null}
app_key: your_app_key
base_url: https://api.flashcat.cloud
```
### 配置命令
```bash theme={null}
flashduty config show # 查看当前配置（APP Key 已脱敏）
flashduty config set app_key KEY # 设置 APP Key
flashduty config set base_url URL # 覆盖 API 地址
```
## 全局参数
所有子命令均支持以下参数：
| 参数 | 说明 |
| ----------------- | -------------------------------------------------------- |
| `--output-format` | 输出格式：`table`（默认）、`json` 或 `toon`（紧凑、更省 token） |
| `--json` | 以 JSON 格式输出，是 `--output-format json` 的别名，便于通过 `jq` 等工具解析 |
| `--no-trunc` | 表格输出时不截断长字段 |
| `--base-url` | 覆盖 API 地址（私有部署场景） |
## 命令清单
### incident — 故障生命周期
```bash theme={null}
flashduty incident list [flags] # 列出故障（默认最近 24 小时）
flashduty incident get [...] # 查看故障详情（单个 ID 显示完整视图）
flashduty incident create [flags] # 创建故障（参数缺失时进入交互模式）
flashduty incident update [flags] # 更新故障字段
flashduty incident ack [...] # 认领故障
flashduty incident close [...] # 关闭（解决）故障
flashduty incident timeline # 查看故障时间线
flashduty incident alerts # 查看故障关联的告警
flashduty incident similar # 查找相似的历史故障
```
`incident list` 常用过滤参数：
| 参数 | 说明 | 默认值 |
| ------------ | --------------------------------------------------------- | ----- |
| `--progress` | 进度过滤：`Triggered`、`Processing`、`Closed` | 全部 |
| `--severity` | 等级过滤：`Critical`、`Warning`、`Info` | 全部 |
| `--channel` | 按协作空间 ID 过滤（逗号分隔，可多个）。旧参数 `--channel-id` 已废弃，仍可用但只接受单个 ID | - |
| `--query` | 按标题、标签或内容关键字自由搜索（也可直接输入 24 位故障 ID 或 6 位短编号进行精准查询） | - |
| `--since` | 起始时间（时长、日期、日期时间或 Unix 时间戳） | `24h` |
| `--until` | 截止时间 | `now` |
| `--limit` | 最大结果数 | `20` |
| `--page` | 页码 | `1` |
时间格式示例：`5m`、`1h`、`24h`、`168h`、`2026-04-01`、`2026-04-01 10:00:00`、`1712000000`。
#### 工作项与跟进项（work-item-\*）
`incident work-item-*` 管理挂靠在故障或复盘上的工作项，`--item-type` 区分两种类型：`action`（故障行动项，挂靠进行中的故障）与 `follow_up`（复盘跟进项，必须绑定复盘 ID）。
```bash theme={null}
flashduty incident work-item-create [flags] # 创建行动项/跟进项
flashduty incident work-item-list [flags] # 列出工作项
flashduty incident work-item-update [flags] # 更新标题/描述/状态/优先级
flashduty incident work-item-complete [flags] # 标记完成
flashduty incident work-item-convert [flags] # 将行动项转为复盘跟进项
flashduty incident work-item-delete [flags] # 删除工作项
flashduty incident work-item-assignees-reset # 重置负责人列表
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`（乐观锁，必须与当前存储版本一致）。
#### 复盘报告（post-mortem-\*）
复盘命令位于 `incident` 命令组下（没有独立的 post-mortem 顶层命令组）：
```bash theme={null}
flashduty incident post-mortem-init [...] # 用 1–10 个故障初始化复盘（--template-id 必填）
flashduty incident post-mortem-list [flags] # 列出复盘报告（服务端默认只看 published，加 --status drafting 查看草稿）
flashduty incident post-mortem-info # 查看报告详情
flashduty incident post-mortem-title-reset # 设置标题
flashduty incident post-mortem-content-reset # 替换正文 Markdown（--markdown-file）
flashduty incident post-mortem-basics-reset # 更新起始/关闭时间、最高等级、响应人元数据
flashduty incident post-mortem-follow-ups-reset # 设置跟进项（--follow-ups）
flashduty incident post-mortem-status-reset # 发布或退回草稿（--status drafting|published）
flashduty incident post-mortem-delete # 删除报告（不可逆）
```
模板命令：`post-mortem-template-list`、`post-mortem-template-info `、`post-mortem-template-upsert`（缺省 `--template-id` 时为创建，创建时 `--team-id` 必填）、`post-mortem-template-delete `（不可逆）。
#### 评论类型（comment-type-\*）
```bash theme={null}
flashduty incident comment-type-create [flags] # 创建（--name ≤40 字符且账户内唯一、--color #RRGGBB）
flashduty incident comment-type-list # 列出全部评论类型
flashduty incident comment-type-update # 更新名称/颜色
flashduty incident comment-type-delete # 删除
flashduty incident comment-type-reorder [...] # 按给定顺序重排（需给出账户内全部类型 ID）
```
### change — 变更记录
```bash theme={null}
flashduty change list [flags] # 列出变更记录（部署、配置变更等）
```
支持 `--channel`、`--since`、`--until`、`--type`、`--limit`、`--page`。
### member — 成员查询
```bash theme={null}
flashduty member list [flags] # 列出成员
flashduty member info-reset [flags] # 更新成员资料
flashduty member invite [flags] # 邀请新成员（单次最多 20 人）
```
`member list` 支持 `--query`（姓名/邮箱关键字搜索）、`--role-id`、`--page`、`--limit`、`--orderby`、`--asc`。
`member info-reset` 通过 `--member-id`、`--member-name`、`--email`、`--phone` 或 `--ref-id` 之一定位成员，要修改的字段经 `--data '{"updates":{...}}'` 传入（必填）；`--from api` 在账户关闭成员邀请时，可将更新后的邮箱/手机号直接标记为已验证。
`member invite` 的成员列表经 `--data '{"members":[...]}'` 传入；当账户关闭成员邀请且指定 `--from api` 时，成员会直接以启用状态创建（邮箱/手机号标记为已验证），不再发送邀请邮件。
### team — 团队管理
```bash theme={null}
flashduty team list [flags] # 列出团队及成员
flashduty team info --team-id # 查看单个团队详情
flashduty team upsert --team-name [flags] # 创建或更新团队（含 --team-id 时为更新）
flashduty team delete --team-id # 删除团队（不可逆）
```
`team list` 支持 `--query`（团队名称子串匹配）、`--page`、`--limit`、`--orderby`（`created_at`/`updated_at`/`team_name`）、`--asc`、`--person-id`（按成员 ID 过滤所属团队）。
`team info` 支持通过 `--ref-id`、`--team-name` 或 `--team-id` 指定团队（三选一）；同时提供多个字段时，按 `--ref-id` > `--team-name` > `--team-id` 的优先级取用。
`team upsert` 创建或更新团队：
* `--team-name`（必填，1–39 字符）
* `--team-id`（填写则为更新，否则创建）
* `--description`（最多 500 字符）
* `--person-ids`（成员 ID 列表；**会完整替换现有成员名单，更新前请先用 `team info` 确认当前成员**）
* `--emails`（按邮箱匹配并加入**已存在**的成员；不匹配任何现有成员的邮箱会被静默忽略，**不会发送邀请**）
* `--phones`（按手机号匹配并加入已存在的成员；不匹配的号码会被静默忽略，非 E.164 格式的号码按 `--country-code` 解析）
* `--country-code`（对非 E.164 格式的 `--phones` 号码应用默认国家码）
* `--ref-id`（外部系统引用 ID）
`team upsert` 的 `--emails` / `--phones` 只匹配并附加**现有成员**，不会发送任何邀请。需要邀请新成员加入组织时，请使用 `flashduty member invite`。
`team delete` 支持通过 `--team-id`、`--team-name` 或 `--ref-id` 指定团队，**操作不可逆**。
### channel — 协作空间查询
```bash theme={null}
flashduty channel list [flags] # 列出协作空间
```
支持 `--name`。
### channel escalate-rule-list — 分派策略查询
分派策略现已并入 `channel` 命令组，通过位置参数传入协作空间 ID：
```bash theme={null}
flashduty channel escalate-rule-list # 列出指定协作空间下的所有分派策略
```
其他分派策略管理命令：`escalate-rule-create`、`escalate-rule-update`、`escalate-rule-delete`（均在 `channel` 命令组下，`--channel-id` 为必填）。
### channel 静默/抑制/丢弃规则 — 降噪规则管理
协作空间级降噪规则通过 `channel` 命令组管理，规则语义与配置项参见[降噪管理](/zh/on-call/channel/noise-reduction)。三组命令（`silence-rule-*` 静默、`inhibit-rule-*` 抑制、`unsubscribe-rule-*` 丢弃）形态相同，各含 `list`/`create`/`update`/`enable`/`disable`/`delete` 六个动作：
```bash theme={null}
flashduty channel silence-rule-list # 列出静默规则（channel-id 为位置参数）
flashduty channel silence-rule-create [flags] # 创建（--rule-name 必填 1–39 字符，时间窗口与过滤条件经 --data 传入）
flashduty channel silence-rule-update --channel-id --rule-id # 更新
flashduty channel silence-rule-enable --channel-id --rule-id # 启用
flashduty channel silence-rule-disable --channel-id --rule-id # 停用
flashduty channel silence-rule-delete --channel-id --rule-id # 删除
```
`inhibit-rule-*` 与 `unsubscribe-rule-*` 用法相同；`inhibit-rule-create` 需 `--equals`（源与目标告警的配对标签键）。silence / inhibit 均可加 `--is-directly-discard` 让被抑制的告警直接丢弃而非合并。注意 `*-rule-create` 与 `*-rule-list` 的 `channel-id` 是位置参数，`*-rule-update`/`delete`/`enable`/`disable` 使用 `--channel-id` 标志；`--rule-id` 为 MongoDB ObjectID 字符串。
### field — 自定义字段查询
```bash theme={null}
flashduty field list [flags] # 列出自定义字段定义
```
支持 `--name`。
### status-page — 状态页管理
```bash theme={null}
flashduty status-page list # 列出状态页
flashduty status-page change-active-list # 列出活跃的变更事件
flashduty status-page change-create [flags] # 创建状态页事件
flashduty status-page change-timeline-create [flags] # 追加时间线更新
flashduty status-page draft-create [flags] # 创建状态页事件草稿（人工审阅后从控制台发布）
```
#### 事件草稿（draft-create）
`draft-create` 保存一份状态页事件草稿（故障事件或维护窗口），供人工在控制台审阅后发布——草稿本身不会对外发布：
```bash theme={null}
flashduty status-page draft-create \
--source 'ai_sre:sess_xxx' \
--data '{"draft":{"page_id":5750613685214,"type":"incident","name":"Web Console Degraded Performance","message":"We are investigating degraded performance affecting the web console.","status":"investigating","affected_components":[{"component_id":"01KC3GAZ6ZJE40H55GM31RPWZE","status":"degraded"}]}}'
```
* `--source`：起草来源的不透明标记（如 `ai_sre:sess_xxx`），最多 64 字符。
* `--data` 中的 `draft` 对象（必填，序列化后最多 64 KB，原样存储）。必填字段：`page_id`、`type`（`incident` 或 `maintenance`）、`name`、`message`；可选 `change_id`（大于 0 时表示向已有事件追加更新）、`status`、`affected_components`、`start_time`/`end_time`（Unix 秒，仅新建维护窗口使用）。
* 响应返回 `draft_id`（形如 `draft_[A-Za-z0-9]{22}`）与 `created_at`，控制台审阅链接携带 `draft_id`。
#### 从 Atlassian Statuspage 迁移
迁移任务为异步执行，需通过 `migration-status` 轮询进度：
```bash theme={null}
# 1. 迁移结构与历史记录
flashduty status-page migrate-structure \
--from atlassian \
--api-key $ATLASSIAN_STATUSPAGE_API_KEY
# 2. 查询迁移进度
flashduty status-page migration-status
# 3. 迁移邮件订阅者
flashduty status-page migrate-email-subscribers \
--from atlassian \
--source-page-id page_123 \
--target-page-id \
--api-key $ATLASSIAN_STATUSPAGE_API_KEY
# 4. 取消运行中的任务
flashduty status-page migration-cancel
```
其他可用子命令：`draft-create`、`change-delete`、`change-info`、`change-list`、`change-timeline-delete`、`change-timeline-update`、`change-update`、`component-upsert`、`component-delete`、`section-upsert`、`section-delete`、`info`、`subscriber-list`、`subscriber-import`、`subscriber-export`、`template-list`、`template-upsert`、`template-delete`。
### rum — RUM 应用与会话回放
用于管理 RUM 应用和导出会话回放数据。应用命令覆盖详情、批量读取、列表、Webhook 测试，以及创建、更新、删除。
```bash theme={null}
flashduty rum application-info # 查看单个应用详情
flashduty rum application-infos [...] # 批量查看多个应用
flashduty rum application-list [flags] # 列出可访问的应用
flashduty rum application-webhook-test # 向指定 Webhook 发送一条测试告警
flashduty rum application-create [flags] # 创建应用
flashduty rum application-update [flags] # 更新应用
flashduty rum application-delete # 删除应用
```
`application-list` 常用参数：
| 参数 | 说明 |
| -------------- | ------------------------------ |
| `--query` | 按应用名称搜索 |
| `--team-id` | 只看指定团队下的应用 |
| `--is-my-team` | 仅返回当前用户所属团队的应用 |
| `--orderby` | 排序字段：`created_at`、`updated_at` |
| `--asc` | 是否按升序排列 |
`application-create` / `application-update` 的核心字段：
| 参数 | 说明 |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `--application-name` | 应用名称，创建时必填，长度 1–40 字符 |
| `--type` | 应用类型：`browser`、`ios`、`android`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`、`miniprogram`、`harmony`、`electron` |
| `--team-id` | 归属团队 ID（创建时必填） |
| `--is-private` | 是否仅允许团队成员访问 |
| `--no-geo` | 是否禁用地理位置推断 |
| `--no-ip` | 是否禁用 IP 采集 |
| `--data` | 可补充 `alerting`（通知配置）和 `tracing`（链路追踪配置）对象 |
`application-webhook-test` 会返回 `ok`、`status_code` 和 `message`，可用于验证 RUM 告警 Webhook 是否真正收到了平台发出的测试事件。
#### 会话回放
```bash theme={null}
flashduty rum session-replay-metadata # 查看可回放会话的应用、设备、会话边界与 View 元数据
flashduty rum session-replay-segments # 读取会话回放分片
```
`session-replay-metadata` 的 `--ts` 可填写会话开始时间的 Unix 毫秒时间戳，用于区分不同时间窗口中复用的会话 ID。
`session-replay-segments` 常用参数：
| 参数 | 说明 |
| -------------------- | --------------------------------------------------------------------------------- |
| `--limit` | 单次返回分片数，范围 1–99，默认 20。 |
| `--search-after-ctx` | 上一页返回的分页游标；使用 URL 模式时从 `search_after_ctx` 字段取得，流式模式时从 `X-Search-After-Ctx` 响应头取得。 |
| `--ts` | 未提供 `--search-after-ctx` 时，从该时间点或之前最近的完整快照分片开始读取。 |
| `--url-mode` | 设为 `true` 时返回包含预签名下载 URL 的 JSON；默认 `false`，直接流式返回分片字节。URL 有效期为 1 小时。 |
| `--view-id` | 只读取指定 View 的分片；省略时遍历整个会话。 |
#### 错误摄入规则（error-ingestion-rules-\*）
错误摄入规则按过滤条件筛除或改写应用上报的错误事件：
```bash theme={null}
flashduty rum error-ingestion-rules-create [flags] # 创建（--rule-name 必填 1–128 字符，filters 经 --data 传入）
flashduty rum error-ingestion-rules-list # 列出规则
flashduty rum error-ingestion-rules-update [flags] # 更新（--application-id、--rule-id 必填）
flashduty rum error-ingestion-rules-enable [flags] # 启用
flashduty rum error-ingestion-rules-disable [flags] # 停用
flashduty rum error-ingestion-rules-delete [flags] # 删除
flashduty rum error-ingestion-rules-history-list # 查看修改历史（--orderby updated_at|version）
flashduty rum error-ingestion-rules-history-revert --version # 回滚到历史版本
```
`--description` 最长 512 字符；`create`/`list`/`history-list`/`history-revert` 以位置参数接收 `application-id`，`update`/`enable`/`disable`/`delete` 通过 `--application-id` 与 `--rule-id` 标志指定目标。
#### 预设严重级别规则（issue-preset-severity-rules-\*）
预设严重级别规则为匹配条件的错误预设等级，用于 issue 分级：
```bash theme={null}
flashduty rum issue-preset-severity-rules-create [flags] # 创建（--rule-name 必填、--severity Critical|Warning|Info 必填）
flashduty rum issue-preset-severity-rules-list # 列出规则
flashduty rum issue-preset-severity-rules-update [flags] # 更新
flashduty rum issue-preset-severity-rules-enable [flags] # 启用
flashduty rum issue-preset-severity-rules-disable [flags] # 停用
flashduty rum issue-preset-severity-rules-delete [flags] # 删除
flashduty rum issue-preset-severity-rules-reorder [flags] # 调整优先级（--drag-rule-id、--target-rule-id）
flashduty rum issue-preset-severity-rules-history-list # 修改历史
flashduty rum issue-preset-severity-rules-history-revert --version # 回滚
```
#### 资源信息（resource-info）
```bash theme={null}
flashduty rum resource-info [--no-cache] # 查看 RUM 套餐版本、配额与用量（--no-cache 跳过短缓存直接读源）
```
### oncall — On-call 许可证
```bash theme={null}
flashduty oncall license-list # 列出当前账户中持有有效 On-call 许可证的成员
```
该命令只读，返回成员 ID、名称及许可证类型：`fixed` 表示固定分配，`temporary` 表示当前临时许可证窗口内生效。
### template — 通知模板
```bash theme={null}
flashduty template get-preset --channel # 获取预设模板代码
flashduty template validate --channel --file # 验证并预览模板渲染结果
flashduty template variables [--category ] # 列出可用模板变量
flashduty template functions [--type custom|sprig|all] # 列出可用模板函数
```
支持的通知渠道：`dingtalk`、`dingtalk_app`、`feishu`、`feishu_app`、`wecom`、`wecom_app`、`slack`、`slack_app`、`telegram`、`teams_app`、`email`、`sms`、`zoom`。
### session — AI SRE 会话
用于巡查 AI SRE（以及其他 Flashduty 智能体）的会话：`session list` 列出调用者可见的会话，`session export` 将单个会话的完整事件流式导出，便于离线分析。
```bash theme={null}
flashduty session list [flags] # 列出智能体会话（默认按 updated_at 倒序，最新在前）
flashduty session export # 以 NDJSON 流式导出单个会话的完整事件
```
`session list` 常用参数：
| 参数 | 说明 | 默认值 |
| ----------------- | --------------------------------------------------------------------------------------- | -------- |
| `--app` | 列出哪个智能体应用的会话 | `ai-sre` |
| `--scope` | 可见范围：`all`（自己 + 所属团队，默认）、`personal`、`team` | `all` |
| `--status` | 归档状态：`active`（默认）、`archived`、`all` | `active` |
| `--team-id` | 仅保留指定团队 ID 的会话 | - |
| `--since` | 仅保留在该时间窗口内有更新的会话（客户端过滤），如 `30d`、`24h`、`2026-05-01` | - |
| `--limit` | 最多拉取的会话数 | `200` |
| `--page` | 起始页码（1 开始） | `1` |
| `--output-format` | 输出格式：`jsonl`（默认，每行一个会话对象，可直接管道给 `jq`）、`json`（完整信封；受 16 KiB 输出上限约束，见「输出格式」）、`toon`（紧凑编码） | `jsonl` |
服务端 `/safari/session/list` 单页上限为 100 条，超出 `--limit` 时 CLI 会自动向服务端翻页拉取，无需手动分页。API 本身没有时间窗口过滤，`--since` 是在拉取后于客户端按会话的 `updated_at` 进行过滤的。
`session export` 将会话事件以换行分隔 JSON（NDJSON）流式写入标准输出：第一行始终是 `session_meta` 信封，其后每行是一个事件（`user_message`、`llm_call`、`tool_call`、`subagent_dispatch`、`final_answer`、`agent_text`、`error`）。导出内容可能很大，建议重定向到文件而非直接打印到终端：
```bash theme={null}
flashduty session export > session.ndjson
flashduty session export --include-subagents > session.ndjson
```
| 参数 | 说明 |
| --------------------- | ------------------------------------------- |
| `--include-subagents` | 在每条 `subagent_dispatch` 之后递归内联该子智能体自身的完整事件流 |
### monit-query — 监控数据源统一工具调用
`monit-query` 对已配置的数据源执行**单个命名工具**，是查询与诊断的统一入口：查询工具（`.query`，覆盖 `prometheus`、`mysql`、`postgres`、`oracle`、`clickhouse`、`elasticsearch`、`loki`、`victorialogs`、`sls`、`tencent_cls`）与诊断工具（如 `mysql.overview`、`redis_node.slowlog`）都走它，无需经过告警规则层。旧 `monit-query data` 子命令已退役。数据源 ID 从 `monit datasource-list` 的 `id` 字段获取：
```bash theme={null}
flashduty monit datasource-list --type prometheus --json | jq '.[] | {id, name, type_ident, address}'
flashduty monit-query --tool 'prometheus.query' \
--params '{"expr":"sum(rate(http_requests_total[5m]))","execution":{"kind":"instant","to_ms":1789000000000}}'
flashduty monit-query --tool 'redis_node.slowlog' --params '{}'
```
| 参数 | 说明 |
| ----------------- | ------------------------------------------------------------------------------------- |
| `` | 数据源 ID（位置参数，必填，来自 `monit datasource-list`，最小 1） |
| `--tool` | 工具名（必填），以数据源类型为前缀，如 `prometheus.query`、`mysql.overview`、`redis_node.slowlog`；1–128 字符 |
| `--params` | 工具参数 JSON（可省略，省略即 `{}`；参数较长时传 `-` 从标准输入读取；显式 `null` 不合法） |
查询工具返回完整的 `explore_result.v1` 结构化结果：`format` 固定为 `explore_result.v1`，`result.kind` 为 `samples`（带完整标签集的即时样本）、`frames`（类型化表格/时序帧）或 `logs`（原始日志，含 `applied_limit` 与 `has_more`）三者之一。诊断工具的返回结构见下文 `monit datasource-tools-invoke`。
### monit datasource-tools-invoke — 数据源诊断工具
`monit datasource-tools-invoke` 对已配置的数据源执行**一次确定性的只读工具调用**，是结构化数据源诊断的现行路径（取代 `monit-query diagnose`），与上文 `monit-query` 命令等价，`monit-query` 为推荐路径。数据源 ID 从 `monit datasource-list` 的 `id` 字段获取：
```bash theme={null}
flashduty monit datasource-list --type redis_node --json | jq '.[] | {id, name, type_ident, address}'
flashduty monit datasource-tools-invoke --tool 'redis_node.slowlog' \
--data '{"params":{}}'
```
| 参数 | 说明 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--datasource-id` | 数据源 ID（必填，来自 `monit datasource-list`，最小 1） |
| `--tool` | 工具名（必填），以数据源类型为前缀，如 `mysql.overview`、`postgres.activity`、`redis_node.slowlog`、`kafka.consumer_lag`、`elasticsearch.cat`、`prometheus.metric_trends`、`loki.log_patterns`、`victorialogs.log_patterns`；1–128 字符 |
| `--data` | 工具参数 JSON（`{"params":{...}}`，可省略，省略即 `{}`；显式 `null` 不合法） |
| `--account-id` | 可选一致性校验，必须等于当前认证账户 |
语义与限制：
* **无工具目录、无自动重试、无回退**：一次调用只执行一个命名工具，参数需按各数据源工具约定填写，不要从命令行列表猜测。除诊断工具外，入口还支持 `.query` 查询工具（`prometheus`、`mysql`、`postgres`、`oracle`、`clickhouse`、`elasticsearch`、`loki`、`victorialogs`、`sls`、`tencent_cls`）。
* 要求所选集群内**全部**当前在线可路由的 Edge 会话支持 v0.71.0 基础调用协议（个别工具可能要求更新的实现）；普通数据源查询不受此版本限制。
* 请求体 ≤128 KiB；完整成功响应 ≤10 MiB；工具超时 ≤25 秒。
* 需要数据源 `enabled=true`；`alerting_enabled=false` 不阻塞诊断。
* 返回值：`data`（工具特定的 JSON 证据，原样保留、永不为 null，不含旧 diagnose 信封）、`tool`、`datasource_id`、可选 `summary`，以及 `truncated` 对象（含 `reason`，存在即表示结果被截断）。
错误按原样返回，常见错误码：`edge_upgrade_required`（Edge 版本过低）、`mixed_edge_versions`（集群内 Edge 版本混合）、`no_active_edge`（无可用在线 Edge）、`tool_not_supported`（工具不支持）、`invalid_request`（修正参数）、`source_too_large` / `result_too_large`（收窄请求范围）。出现 Edge 版本问题时不要轮换 Edge 或回退到旧版 diagnose。
### monit — 监控数据源与规则表达式预览
如果你想在保存规则前直接验证某条数据源表达式，可以使用 `preview-sync` 走一条同步预览请求，拿到原始结果。
```bash theme={null}
flashduty monit preview-sync [flags]
```
常用参数：
| 参数 | 说明 |
| ----------------- | ----------------------------------------------- |
| `--ds-name` | 数据源显示名（必填，需与控制台配置一致） |
| `--ds-type` | 数据源类型（必填），如 `prometheus`、`loki`、`elasticsearch` |
| `--expr` | 预览查询表达式（必填） |
| `--delay-seconds` | 将查询窗口整体向前平移若干秒，用于补偿采集延迟 |
| `--data` | 可补充 `args` 等数据源特定参数 |
#### 数据源管理（datasource-\*）
`monit datasource-*` 命令族管理监控数据源（由 OpenAPI 生成命令提供）：
```bash theme={null}
flashduty monit datasource-list [--type ] # 列出数据源（--type 按类型过滤，省略返回全部）
flashduty monit datasource-info --id # 查看单个数据源
flashduty monit datasource-create [flags] # 创建数据源（payload 经 --data 传入）
flashduty monit datasource-update [flags] # 更新数据源（--id 必填）
flashduty monit datasource-delete --id # 删除数据源（引用它的告警规则不被阻断，规则自动移出监控范围并关闭相关告警）
```
`datasource-create` / `datasource-update` 核心字段：
| 参数 | 说明 |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name` | 数据源显示名（必填）；查询/诊断 API 中的 `ds_name` 引用该名称 |
| `--type-ident` | 数据源类型（必填）：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`，以及 5 个**仅诊断**类型：`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka` |
| `--address` | 连接地址。除 `elasticsearch` 且 `deployment: cloud` 外必填。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 `http(s)://` 前缀的 endpoint。**Redis/MongoDB 诊断类型**：单个 `host:port`，IPv6 需加方括号，不接受 URI/userinfo/query；**Kafka**：1–32 个逗号分隔的唯一 `host:port` bootstrap 地址（payload 中不含 broker 列表）。规范化后最多 4096 字符 |
| `--edge-cluster-name` | 负责用该数据源评估规则的 Edge 集群名（必填） |
| `--note` | 可选备注 |
| `--enabled` | **业务执行**开关。创建时省略默认 `true`；更新时省略保留当前值；显式 `false` 停用（停用后业务查询与工具被拒绝）；`null` 不合法。**不影响 `alerting_enabled`** |
| `--alerting-enabled` | 是否允许该数据源评估告警。创建时省略：告警类类型默认 `true`，仅诊断类型默认 `false`；更新时省略保留当前值；`null` 不合法。5 个诊断类型拒绝 `true`；已有启用规则引用该数据源时关闭会以冲突错误拒绝 |
| `--data` | `payload` 配置块（必填），必须包含与 `type_ident` 同名的键，如 `{"payload":{"redis_node":{"database":0,"password":"..."}}}` |
`enabled` 与 `alerting_enabled` 相互独立：告警评估同时要求 `enabled=true` 与类型支持告警；`alerting_enabled=false` 不阻塞非告警查询与诊断工具，`monit datasource-list` 返回的 `alerting_enabled` 对仅诊断类型恒为 `false`。
**诊断类型 payload 与密钥处理**：
* `redis_node`：`database`（Redis 库号，默认 0）、`username` / `password`、`timeout_ms`（默认 3000，范围 1000–10000）。
* `redis_sentinel`：`username` / `password`、`timeout_ms`（默认 3000）。
* `mongodb_mongod` / `mongodb_mongos`：`auth_source`（认证库，默认 `admin`；用户名与密码须成对配置）、`username` / `password`、`timeout_ms`（默认 3000）、TLS 字段；不支持客户端证书。
* `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:...}` 引用会回显。**更新时省略这些字段以保留已存密钥，显式传空字符串表示清除**。
### alert — 告警与告警事件查询
```bash theme={null}
flashduty alert list [flags] # 列出告警（默认最近 24 小时）
flashduty alert get # 查看单条告警详情；detail 是同一命令的别名
flashduty alert-event list [flags] # 列出告警事件（默认最近 1 小时）
```
两个 `list` 命令常用过滤参数：`--severity`（`Critical,Warning,Info`）、`--channel`（逗号分隔协作空间 ID）、`--integration`（逗号分隔的集成 ID）、`--since`/`--until`、`--limit`（最大 100）、`--page`。`alert-event list` 另有 `--integration-type`，按逗号分隔的**插件键**过滤（如 `AliCloud,Prometheus`）——注意它取插件键而非集成 ID，按集成 ID 过滤请使用 `--integration`。
### automation — AI SRE 自动化规则
`automation` 命令组管理 AI SRE 的自动化规则——创建、查询、更新、删除、运行历史与触发，页面操作见[自动化](/zh/ai-sre/automations)。
```bash theme={null}
flashduty automation create [flags] # 创建规则
flashduty automation list [flags] # 列出调用者可见的规则
flashduty automation get # 查看单条规则
flashduty automation update [flags] # 更新规则的可变字段
flashduty automation delete [flags] # 删除规则（交互终端二次确认，--force 跳过）
flashduty automation runs [flags] # 列出规则的运行历史
flashduty automation templates [--locale zh-CN] # 列出预设模板
flashduty automation fire # 经 HTTP POST 触发器触发一次运行
```
`create` 常用参数：
| 参数 | 说明 |
| ----------------------------------------- | --------------------------------------------------------------------------- |
| `--name` | 规则名称（必填） |
| `--team-id` | 归属团队 ID；`0` 表示个人范围（默认）。作用域创建后不可变更 |
| `--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` 辅助参数 |
| `--disabled` | 以停用状态创建（默认启用） |
| `--schedule-enabled` | 是否启用周期触发器（默认 `true`） |
| `--http-post-trigger` | 创建并启用 HTTP POST 触发器；只传它且不带任何周期参数时，CLI 会写入占位 cron 并自动停用周期触发器 |
| `--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`、`--enable`/`--disable`、`--enable-schedule`/`--disable-schedule`、`--enable-http-post-trigger`/`--disable-http-post-trigger`、`--rotate-http-post-token`、`--environment-kind`/`--environment-id`。个人 / 团队作用域创建后不可变更，`update` 不提供改作用域的参数。
`runs` 支持 `--status`（`queued`/`running`/`retrying`/`succeeded`/`partial`/`failed`/`skipped`/`abandoned`）、`--trigger-kind`（`schedule`/`debug`/`http_post`）、`--since`/`--until`、`--page`、`--limit`。`fire` 用触发器的 Token 鉴权（`--token`，或环境变量 `FLASHDUTY_AUTOMATION_TRIGGER_TOKEN`），`--text` 传本次运行的上下文，`--data` 传完整 JSON 请求体（内联 JSON 或 `-` 读 stdin）。
**时区语义**：`--at` 与 `--cron-expr` 均按**规则时区**的本地挂钟时间理解——规则时区在创建时默认为调用者的成员时区，成员未设置时回退到账户时区。请直接传用户的本地时间，**不要**预先换算成 UTC。CLI 的 `create` / `update` 都没有 `--timezone` 参数：创建时如需固定其它时区，请改用生成命令 `flashduty safari automation-rule-create --timezone`；已创建规则的时区在 `update` 中不可更改。
### insight — 洞察查询
`insight` 命令族按时间窗口查询聚合的故障指标（响应时间、通知数等）：
```bash theme={null}
flashduty insight incidents [flags] # 列出带性能指标的故障（MTTA、MTTR、通知数）
flashduty insight top-alerts [flags] # 按标签维度统计最吵的告警来源
flashduty insight incident-export [flags] # 导出筛选后的故障列表为 CSV（重定向到文件）
```
`insight incidents` 常用参数：
| 参数 | 说明 | 默认值 |
| --------------------- | --------------------------------------------------------------------------- | ------------ |
| `--since` / `--until` | 时间窗口（与 `incident list` 相同的人性化格式） | `7d` / `now` |
| `--limit` | 最大结果数（上限 100） | `20` |
| `--page` | 页码 | `1` |
| `--fields` | `json`/`toon` 输出时的字段投影（逗号分隔，如 `incident_id,title,severity`）；表格模式忽略；至少指定一个字段 | 默认紧凑投影 |
`json`/`toon` 模式默认按紧凑字段投影：`incident_id`、`title`、`severity`、`channel_name`、`seconds_to_ack`、`seconds_to_close`、`notifications`（默认投影时 stderr 会提示可用 `--fields` 更换），输出受 16 KiB 上限约束，超出时行会被丢弃或单行截短，提示只写 stderr（详见下文「输出格式」的「结构化输出的字段投影」）。
`insight top-alerts`：`--label` 必填（`check` 或 `resource`），`--since`/`--until` 同前，`--limit` 默认 `10`（Top-K），返回每个标签值的告警数与事件数。
`insight incident-export`：按当前筛选条件输出一行 CSV（重定向到文件；`--start-time`/`--end-time` 为 Unix 秒）。导出端点单次返回且服务端会静默截断行数，因此命令写完后会核对 CSV 数据行数与同筛选条件 `incident-list` 的总数：不足时 CSV 仍会写出（stderr 打印 `rows=N`），并以非零退出码提示实际写出 vs 总数——请收窄时间窗口后重试。
### 全量命令覆盖
除上述精选命令外，CLI 现已通过 spec 驱动的代码生成实现对 Flashduty OpenAPI 的**全量覆盖**。当前 OpenAPI 含 **340 个 API 操作**，CLI 为其中 **337 个** 生成对应命令，其余操作（如 `session-read-export`）以手工实现命令提供（`session export` / `safari session-export`），并按资源组织为顶层命令组。除 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）
这些生成命令的叶子名称采用「资源-动作」形式（如 `flashduty safari a2a-agent-get`、`flashduty safari session-list`），其入参与返回字段直接映射到对应 API。鼓励用 `flashduty <资源> --help` 逐层探索：
```bash theme={null}
flashduty --help # 查看全部顶层命令组
flashduty safari --help # 查看 AI SRE 相关的生成命令
flashduty alert --help # 查看告警相关的生成命令
```
生成命令的时间窗口参数（`--start-time` / `--end-time`）与精选命令一样支持人性化的时间格式：相对时长（`7d`、`24h`，表示从当前往前推）、`+7d`（从当前往后推，即未来时间）、`now`、日期或日期时间（如 `2026-05-01`、`2026-05-01 10:00:00`）、Unix 秒级时间戳。此外，`--since` 和 `--until` 分别是 `--start-time` 和 `--end-time` 的别名，可互换使用；若两种写法同时传入且取值不同，CLI 会报冲突错误。
#### knowledge — AI SRE 知识库
`safari knowledge-*` 命令族管理 AI SRE 的**知识包**（Knowledge Pack）——账户或团队作用域下的版本化文件树（`DUTY.md` 加运行手册、FAQ、服务清单等），会话开始时会被加载进每个 AI SRE 沙箱。知识包的完整功能模型（`DUTY.md` 结构、`@引用`、账户/团队作用域、文件约束）参见 [管理知识](/zh/ai-sre/knowledge)。
```bash theme={null}
flashduty safari knowledge-get # 获取当前账户知识包（含文件列表）
flashduty safari knowledge-pack-list [flags] # 列出知识包
flashduty safari knowledge-pack-ensure --scope [--scope-id ] # 确保知识包存在（不存在则创建）
flashduty safari knowledge-pack-update [--scope ...] # 变更知识包作用域
flashduty safari knowledge-pack-delete # 删除知识包（不可逆）
flashduty safari knowledge-file-list [--pack-id ] # 列出知识包内的文件
flashduty safari knowledge-file-get --rel-path # 读取单个知识文件（内容为 Base64 编码）
flashduty safari knowledge-file-put --rel-path --content-b64 # 上传或覆盖知识文件
flashduty safari knowledge-file-delete --rel-path [--force] # 删除知识文件
```
常用参数：
| 参数 | 说明 |
| ------------ | ----------------------------------------------------- |
| `--pack-id` | 知识包 ID；省略时默认使用调用者账户作用域的知识包 |
| `--rel-path` | 文件相对知识包根目录的路径（必填，支持子目录，如 `runbooks/api-5xx.md`） |
| `--scope` | 知识包作用域：`account` 或 `team`（`knowledge-pack-ensure` 必填） |
| `--scope-id` | 团队 ID；`team` 作用域必填，`account` 作用域忽略 |
| `--force` | 删除文件时跳过「仍被其他文件引用」检查，引用方改为以警告形式返回 |
`knowledge-file-put` 的 `--content-b64` 必须是合法 UTF-8 文本的 Base64 编码，`--content-type` 省略时按文件扩展名推断。`knowledge-file-delete` 默认在文件仍被其他知识文件引用时阻止删除；加 `--force` 可强制执行，此时引用方会以警告形式返回。
#### artifacts — AI SRE 产物库
`safari artifact-*` 命令族管理 AI SRE 会话产出的**产物**（Artifact）——发布到产物库、共享与签名下载，产品功能见[产物](/zh/ai-sre/artifacts)：
```bash theme={null}
flashduty safari artifact-gallery-list [flags] # 列出产物（--scope all|personal|team、--query 标题搜索、--orderby created_at|updated_at、--limit 默认 20 上限 100、--page、--team-ids、--asc）
flashduty safari artifact-gallery-get # 查看产物详情（含公开分享状态）
flashduty safari artifact-gallery-publish-from-file --title # 将会话内产出的文件（pf_ 前缀）发布为产物
flashduty safari artifact-gallery-file-state [...] # 检查哪些文件已存在活跃产物（单次最多 50 个）
flashduty safari artifact-gallery-update [flags] # 重命名（--title）或转移范围（--team-id：0 转个人，正数转团队）
flashduty safari artifact-gallery-delete # 从产物库移除（源文件仍留在会话中）
flashduty safari artifact-sign [--share-token ] # 为文件生成短时签名 URL（下载/预览，5 分钟有效）
flashduty safari artifact-stream --t [--mode download|preview] # 用签名 token 下载或预览文件字节（--mode 其它取值回退到 download）
flashduty safari artifact-gallery-share-enable # 开启匿名公开分享，返回 public_url
flashduty safari artifact-gallery-share-revoke # 关闭公开分享（链接立即不可访问）
flashduty safari artifact-gallery-share-sync # 用最新内容刷新公开快照
```
公开分享与签名语义：
* `public_url` 是控制台 `/share/artifact/` 页面，**完全由 CDN 提供**；仅在分享期间存在，任何拿到链接的人无需登录即可查看。
* 公开快照按产物当前的 `file_id` 物化：当 `share_enabled=true` 且响应中 `share_file_id` 与 `file_id` 不一致时，公开快照已过期——调用 `artifact-gallery-share-sync` 刷新后再对外引用。
* `artifact-sign` 的签名 token 绑定调用账户与成员，有效期 5 分钟（响应 `expires_in`）；`download_url` / `preview_url` 是相对路径（`/safari/artifact/stream?...`），使用时需拼接 API base（`https://api.flashcat.cloud`）。
* 产物初始作用域继承来源会话（个人会话的产物归创建者个人，绑定团队的会话的产物归团队）；`can_edit` 决定调用者能否重命名/转移/删除/分享（创建者、所属团队成员或源会话管理者）。
### 工具命令
```bash theme={null}
flashduty login # 交互式登录
flashduty config show # 查看当前配置
flashduty config set # 设置配置项
flashduty version # 打印版本信息
flashduty whoami # 显示当前认证身份（账号 ID、邮箱、角色等）
flashduty update # 更新到最新版本
flashduty update --check # 仅检查是否有新版本，不安装
flashduty completion # 生成 Shell 自动补全（bash/zsh/fish/powershell）
```
`flashduty update` 会下载并执行平台安装脚本，将当前二进制替换为最新版本。`--check` 仅打印可用版本号，不修改本地文件。在终端中执行其他命令后，若检测到有新版本可用，CLI 会在 stderr 自动输出更新提示横幅。
启用 Shell 自动补全示例（zsh）：
```bash theme={null}
flashduty completion zsh > "${fpath[1]}/_flashduty"
```
## 输出格式
通过 `--output-format` 选择输出形态（`--json` 是 `--output-format json` 的别名），便于在不同场景下消费：
人类可读，列对齐，长字段截断显示。
```
ID TITLE SEVERITY PROGRESS CHANNEL CREATED
inc_abc123 DB connection timeout Critical Triggered Production 2026-04-10 10:23
inc_def456 High memory usage Warning Processing Staging 2026-04-10 09:15
Showing 2 results (page 1, total 2).
```
机器可解析。除下方列出的默认紧凑字段命令外，返回命令的完整响应数据；表格列截断不适用于 JSON。适合脚本、CI/CD 流水线消费。注意生成命令的**列表形态**响应在 `json` 模式下同样受 16 KiB 上限约束（见下方「生成命令的输出上限」）。
```bash theme={null}
flashduty incident list --json | jq '.[].title'
```
TOON（Token-Oriented Object Notation）对同构数组省去了 JSON 中每行重复的字段名，列表输出可显著减少 token 消耗，更适合喂给 AI / 智能体消费。下方列出的默认紧凑字段命令会按其字段投影输出，并受大小限制；生成命令的列表形态输出同样受 16 KiB 上限约束（见下方「生成命令的输出上限」）。
```bash theme={null}
flashduty incident list --output-format toon
```
TOON 不能直接用 `jq` 解析；需要管道给 `jq` 时请改用 `--json`。
表格视图但不截断长字段，便于复制粘贴或终端宽度较大的场景。
#### 生成命令的输出上限
由 OpenAPI 代码生成提供覆盖的生成命令（如 `safari session-list`、`monit datasource-list`、`safari a2a-agent-list` 等），其 `json` / `toon` 输出对**列表形态**的响应同样按 16 KiB 上限处理（与精选命令的两级行为一致，提示只写 stderr、不改写 stdout）：
1. **整页超限**：只输出能完整放下的前几行，每个值保持原样，stderr 提示实际输出了 N/M 行、其余行未输出。
2. **单行本身超限**：该行的字符串值以 `...` 截短，stderr 点名被截字段；标识符字段（以 `_id` / `_key` 结尾）不会被截短。
3. **行无法缩减到上限以内**：命令报错并点名字节数最大的字段（最多 3 个），请调低 `--limit` 或减少输出字段后重试。
**明细形态的单个对象**（如 `safari session-get` 的详情）不做截断、原样输出——截短后的值无法与真实短值区分，因此这类响应不受上限约束。生成命令大多没有 `--fields`，需要完整 JSON 时请通过 `--limit` 调小每页数量、配合 `--page` 分页逐页拉取（如 `flashduty safari session-list --limit 20 --page 2`），或按需收窄筛选条件。
### 结构化输出的字段投影
以下命令在 `json` 或 `toon` 输出时支持 `--fields`。用逗号分隔顶层响应字段；未知字段会直接报错，表格输出会忽略此参数。
| 命令 | 未指定 `--fields` 时的结构化输出 | 上限 |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `flashduty incident list` | `incident_id`、`title`、`incident_severity`、`progress`、`start_time`、`channel_id` | 16 KiB |
| `flashduty incident similar ` | `incident_id`、`title`、`incident_severity`、`progress`、`start_time`、`close_time`、`ack_time`、`alert_cnt`、`root_cause`、`score` | 16 KiB |
| `flashduty incident detail ` | 不指定 `--fields` 时返回完整详情；指定后只返回所选字段 | 仅投影输出为 8 KiB |
| `flashduty alert-event list` | `event_id`、`alert_id`、`event_severity`、`event_status`、`event_time`、`title` | 16 KiB |
| `flashduty channel escalate-rule-list ` | `rule_id`、`rule_name`、`status`、`priority`、`filters` | 16 KiB |
| `flashduty insight incidents` | `incident_id`、`title`、`severity`、`channel_name`、`seconds_to_ack`、`seconds_to_close`、`notifications` | 16 KiB |
例如，只导出故障编号、标题和处理进度：
```bash theme={null}
flashduty incident list --json --fields incident_id,title,progress
```
列表投影（`incident list`、`incident similar`、`alert-event list`、`channel escalate-rule-list`、`insight incidents`）超过 16 KiB 上限时，CLI 按三级行为处理，所有提示只写 stderr、不改写 stdout：
1. **整页超限**：只输出能完整放下的前 N 行，每个值保持原样、不再截短，stderr 提示实际输出了 N/M 行、其余行未输出；收窄 `--fields` 或调低 `--limit` 可让每页容纳更多行。
2. **单行本身超预算**：截短该行的字符串值并以 `...` 标记，stderr 点名被截短的字段；在被截短过的字段上匹配或过滤会漏数据，需要原始值时请收窄 `--fields` 或 `--limit`。标识符字段（以 `_id` 或 `_key` 结尾）在任何一级都不会被截短。
3. **行无法缩减到上限以内**：命令报错并点名字节数最大的字段（最多 3 个，含各自字节数），请减少 `--fields` 字段或调低 `--limit` 后重试。
`incident detail` 的投影超限行为不同：详情是单个对象，截断后的值与本身就很短的真实值无法区分，静默截短会返回错误数据，因此投影超过 8 KiB 时命令直接失败，错误信息会点名最大的字段（最多 3 个，含各自字节数）。此时请减少 `--fields` 中的字段，或直接省略 `--fields` 获取不受投影上限约束的完整详情。
未指定 `--fields` 而使用默认紧凑投影时，CLI 会在 stderr 打印一行提示，说明当前投影使用的字段、以及可通过 `--fields` 选择其他字段。该提示只写 stderr、不改写 stdout，管道给 `jq` 等工具时输出保持不变。
## Agent Skills
Flashduty CLI 内置一个名为 `flashduty` 的 Agent Skill，可让 Claude Code、Cursor、Codex、Gemini CLI、Windsurf 等 AI 编程代理通过 CLI 操作 Flashduty。
一键安装到当前机器上检测到的所有代理：
```bash theme={null}
npx skills add flashcatcloud/flashduty-cli -y -g
```
技能采用「路由 + 参考卡」结构：`SKILL.md` 承载认证、全局参数、安全规则等共享约定，并按领域索引参考卡——故障、告警、变更、值班与排班、协作空间与分派、状态页、洞察、监控、RUM 与 sourcemap、自动化、通知模板、成员与团队等。代理执行任务前先读取对应领域的参考卡，即可获得该领域的全部命令、参数与工作流，无需 `--help` 试探。
## 常见用法
通过 `flashduty incident get ` 在终端中快速查看故障详情，可将命令片段嵌入到通知模板里供值班同学一键复制。
```bash theme={null}
flashduty incident ack inc_001 inc_002 inc_003
flashduty incident close inc_001 inc_002 inc_003
```
```bash theme={null}
flashduty incident list --since 168h --limit 500 --json > incidents.json
```
然后通过 `jq` 处理或导入数据仓库。
```bash theme={null}
flashduty template validate --channel feishu --file templates/feishu.yaml
```
将上述命令加入 CI，可在模板提交时立即捕获语法或字段错误。
完整源码和问题反馈请访问 [GitHub 仓库](https://github.com/flashcatcloud/flashduty-cli)。