跳转到主要内容

概述

go-flashduty 是 Flashduty 官方开源的 Go 客户端,覆盖 Flashduty Open API 的每一个 REST 接口。它采用与 go-github 一致的设计风格——服务分组、类型化请求与响应、可组合传输层——并与 OpenAPI 规范保持严格 1:1:每个方法对应且仅对应一次 HTTP 调用,返回 (*T, *Response, error),不做任何跨接口的隐式聚合或增强。
SDK 故意保持”薄”。诸如短 ID 解析、跨接口编排等消费侧逻辑应放在调用方(CLI / MCP)中,而不是塞进 SDK 或滥用某个接口。这样 SDK 始终与 API 一一对应,可预测、可生成、可校验。
模块路径为 github.com/flashcatcloud/go-flashduty,包名为 flashduty,源码遵循 Apache-2.0 协议开源在 flashcatcloud/go-flashduty。

Open API 参考

全部接口的请求参数与响应字段说明。

命令行工具

在终端中直接操作 Flashduty 的 CLI。

安装

1

要求 Go 1.24+

请确认本地 Go 工具链版本不低于 1.24。
2

获取依赖

3

导入包

快速开始

以下是一个最小可运行示例:构造客户端、列出处于”已触发”状态的故障,并处理返回的三元组 (数据, *Response, error)。
每次调用都返回三个值:
app_key 用于鉴权,SDK 会自动将其作为查询参数注入每个请求。请在 Flashduty 控制台的 个人中心 → APP Key 中创建,详见个人设置。也可以改用 OAuth 访问令牌鉴权:用 NewClientWithAccessToken 创建客户端,见创建客户端。

创建客户端

NewClient 接收 app_key 与零到多个 Option。app_key 为空会直接返回错误。默认 Base URL 为 https://api.flashcat.cloud,默认 HTTP 超时为 30 秒,默认 User-Agent 为 go-flashduty。
私有化部署:用 WithBaseURL 将客户端指向您自有的 Flashduty 网关地址即可,其余调用方式完全不变。

OAuth 访问令牌

除 app_key 之外,SDK 也支持用 OAuth 访问令牌鉴权:NewClientWithAccessToken(accessToken, opts...) 返回的客户端在 JSON、GET 与文件上传请求上都发送 Authorization: Bearer <token>,并且不再注入 app_key 查询参数——两者是二选一,不是叠加。令牌为空会直接返回错误(flashduty: access token is required);除此之外它与 NewClient 完全一致,所有 Option 照旧可用,默认 Base URL、超时与 User-Agent 也相同。
访问令牌由 Flashduty 的 OAuth 授权服务器签发,该服务器地址就是 API 基础地址(默认 https://api.flashcat.cloud)。客户端在 /.well-known/oauth-authorization-server 发现它,走授权码 + PKCE 流程换取令牌;令牌以所属账户的身份调用公开 API,权限与同一账户的 app_key 相同。令牌只在签发它的部署上有效,因此用访问令牌鉴权时不要用 WithBaseURL 指向其他网关。

服务与方法

接口按服务分组挂在客户端上:调用约定统一为 client.<Service>.<Method>(ctx, req),返回 (*T, *Response, error)。例如 client.Incidents.List(ctx, req)、client.Sessions.ReadInfo(ctx, req)。
所有标识符、服务字段名与方法名均与生成代码保持一致。具体每个服务有哪些方法、请求与响应类型,请以 services_gen.go 与各服务文件,以及 Open API 参考 为准。会话的写入与事件流方法不在 Open API 参考的覆盖范围内,见下文「AI SRE 会话」。
以下服务有需要额外说明的行为:

公共集成与专属集成

公共集成是账户级的(/integration/*),在集成中心管理,通过订阅或路由接入协作空间,用 client.Integrations 调用。专属集成属于某一个协作空间(/channel/integration/*),用 client.DedicatedIntegrations 调用,它提供 8 个方法:ReadInfo、ReadList、WriteCreate、WriteUpdate、WriteDelete、WriteEnable、WriteDisable、WriteRotateKey。 读取专属集成要求您具备协作空间查看、协作空间管理或集成中心查看之一,并且目标空间对您可见;写入要求协作空间管理权限,以及目标空间的管理资格。共用的集成类型目录(/integration/type/list)同样接受这三项读取权限;限制了接口范围的 App Key 还须允许 integration.api:read:typeList 才能查询。 按集成的实际归属选择服务,不要用集成 ID 去猜类型:ReadInfo、WriteUpdate 等只接受专属集成 ID,传公共集成 ID 会被拒绝。权限不足时不会自动改用另一组接口。两类接口都用管理用的 App Key 鉴权,响应里的 integration_key 用于事件上报,不能当作管理凭据使用;列表和详情会返回完整集成 Key,不要记录完整响应。 更新专属集成时省略字段即保留原值。ChannelIntegrationUpdateRequest.Description 是 *string,最长 499 个字符:nil 保留原描述,指向空字符串则清空描述。Settings 为 nil 时保留现有配置,传非 nil 的空 map 会提交 {} 作为替换配置,其中被脱敏成 ****** 或省略的敏感字段仍保留已存值。

状态页草稿

client.StatusPages.DraftCreate(POST /status-page/draft/create)把一次状态页事件草稿存下来,供人工在控制台审阅后发布,不会直接对外可见:draft 为任意 JSON,按原文存储、序列化后不超过 64 KB,其中 page_id、type(incident 或 maintenance)、name、message 会被校验;change_id(> 0 时表示追加到已有事件的一次更新)、status、affected_components 可选,新建 maintenance 时可用 start_time / end_time(Unix 秒)指定窗口。请求上的 source 是草稿来源标记(≤ 64 字符);响应返回 draft_id(匹配 draft_[A-Za-z0-9]{22}),控制台的审阅链接即携带它。

知识

client.Knowledge 对应 /safari/knowledge/* 的 9 个 API 操作:知识侧为 PackReadGet(获取账户知识)、PackReadList(列出知识)、PackWriteEnsure(确保知识存在)、PackWriteUpdate(变更知识作用域)、PackWriteDelete(删除知识);知识文件侧为 FileReadGet、FileReadList、FileWritePut(上传/覆盖)、FileWriteDelete。相关导出类型包括 KnowledgePackItem、KnowledgeFileItem、KnowledgeWarning 以及各 Knowledge*Request / Knowledge*Response。

AI SRE 产物

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,删掉该行即可,否则无法编译。
作战室创建触发器的字段在创建与更新两侧的语义不同:
  • 创建侧是普通值:AutomationRuleCreateRequest.WarRoomTriggerEnabled(bool)、WarRoomChannelIDs([]int64)、WarRoomSeverities([]string)。更新侧三者都是指针(*bool / *[]int64 / *[]string),nil 表示该字段保持不变,非 nil 才会发送。
  • 服务端按「给了就建」判定:WarRoomTriggerEnabled 为 true,或 WarRoomChannelIDs 非空时,才会创建该触发器——此时协作空间列表与严重程度列表(Critical / Warning / Info)都必须非空,缺任一个会以参数错误拒绝;只给严重程度不会创建触发器。
  • 更新时传空切片等同于省略:服务端把空列表按未提供处理、保留原值,所以过滤条件只能用非空列表整体替换,无法用空数组清空。
  • 读回时 AutomationRuleItem.WarRoomTriggerEnabled 恒有值(没有该触发器时为 false),WarRoomTriggerID、WarRoomChannelIDs、WarRoomSeverities 则为空("" / 空切片)。
字段含义与触发时机见自动化 · 作战室创建触发。

规则分组

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。 client.Diagnostics.QueryExplore(POST /monit/query/explore,monit-read-query-explore)对已配置的数据源执行探索查询,返回数据源原生形态的 explore_result.v1:ExploreData.format 恒为 explore_result.v1,result.kind 取 frames(列式表格或时序,见 ExploreFrame / ExploreField)、samples(带标签的瞬时值 ExploreSample)或 logs(日志条目 ExploreLogEntry,最多 1000 条,被截断时 has_more 为 true、applied_limit 给出实际生效的上限),execution.effective_step_seconds 回显应用 max_data_points 与 min_step_seconds 之后实际使用的步长。请求字段:datasource_id(取自 /monit/datasource/list,必须是当前账户下的数据源)、expr(数据源原生语言的查询表达式,如 PromQL、LogsQL、SQL)、args(Grafana 风格宏变量替换的字符串键值;请求中必填,没有宏变量时传空表 map[string]string{}——Go 的 nil map 会序列化为 null,不符合 schema)与 execution(QueryExploreExecution:kind 取 instant / range / window,to_ms 在三种模式下都必填,range 另需 from_ms 与 max_data_points,window 另需 from_ms,min_step_seconds 仅在 range 下接受)。与 QueryData 的分工:需要数据源原生结果形态(含原始日志)时用 QueryExplore,需要稳定的 query_result.v1 契约时用 QueryData。该接口需要「数据源查看」(monit)权限,并要求受支持的部署运行 monit-edge v0.68.0 及以上版本。

RUM 远程配置与仓库关联

client.Applications(RUM 应用)除应用管理外还覆盖 RUM 远程配置的 5 个方法:RemoteConfigReadGet(POST /rum/application/remote-config/get,读取当前生效的配置与 version)、RemoteConfigReadHistoryList(/rum/application/remote-config/history/list,分页列出已发布的历史版本)、RemoteConfigReadPreview(/rum/application/remote-config/preview,用模拟客户端的 env / app_version / sdk 上下文评估一份草稿配置,返回命中的 hit_rule_index 与最终下发的 values,不发布)、RemoteConfigWriteUpdate(/rum/application/remote-config/update,发布一份完整的新配置)、RemoteConfigWriteHistoryRevert(/rum/application/remote-config/history/revert,把历史版本的内容重新发布为新版本)。主要类型:RemoteConfig(enabled、activation、default、rules、custom、refresh_on_foreground)、RemoteConfigValues(四个可下调的 SDK 开关)、RemoteConfigRule(match 条件加 set 取值)、RemoteConfigHistoryItem(含 version、reason、content_hash、updated_by),以及 GetRemoteConfigRequest / ListRemoteConfigHistoryRequest / PreviewRemoteConfigRequest / UpdateRemoteConfigRequest / RevertRemoteConfigRequest 与各自的 *Response。应用本身的 WriteCreate / WriteUpdate / ReadInfo / ReadInfos / ReadList 还带 repositories 字段([]RUMApplicationRepository,仅存在于请求体,不是顶层标志):把应用关联到构建它的代码仓库,有序,第一项为主仓库,最多 10 项;每项为 Repo(owner/name 形式的 GitHub 仓库,必填)加可选的 Subdir(应用在仓库内所在的目录,相对仓库根目录,. 表示仓库根目录,空值保存为 .)。创建时传入即建立关联;更新时按 presence 处理——传入即整体替换、传空数组清空关联、省略则保持不变;ReadInfo / ReadInfos / ReadList 会把它回显在 RUMApplicationItem 上。关联本身不授予任何访问权限:AI 会话只能读取账户 GitHub App 安装已授权的仓库。该字段目前只在 API/SDK 层提供,控制台的应用管理页不暴露仓库关联设置。

数据源工具调用

client.DataSources.ToolsInvoke(POST /monit/datasource/tools/invoke,monit-datasource-tools-invoke)在某个已配置数据源上执行一个确定性工具:tool 名称由数据源类型前缀修饰(如 mysql.overview),params 为工具专属 JSON 参数(省略视为 {},显式 null 非法);除诊断工具外,入口支持 <type>.query 查询工具(prometheus、mysql、postgres、oracle、clickhouse、elasticsearch、loki、victorialogs、sls、tencent_cls),/monit/query/data 入口保持不变。该接口要求 monit-edge v0.71.0 及以上版本。请求体上限 128 KiB,完整成功响应上限 10 MiB,单工具超时至多 25 秒;响应为 DatasourceToolResult(data 为工具专属 JSON、永不为 null,summary 可选,出现 truncated 时其 reason 说明截断原因)。 调用 <type>.query 查询工具时用 NewDatasourceQueryInvokeRequest(datasourceID, tool, params) 构造请求,params 传对应的类型化结构(每个工具一种):PrometheusQueryParams、MySQLQueryParams、PostgresQueryParams、OracleQueryParams、ClickHouseQueryParams、ElasticsearchQueryParams、LokiQueryParams、VictoriaLogsQueryParams、SLSQueryParams、TencentCLSQueryParams。这些结构都由 expr 加 execution 组成(DatasourceQueryExecution:kind 取 instant / range / window,from_ms / to_ms 为 Unix 毫秒的 *int64;range 还要求 max_data_points,可选 min_step_seconds 抬高计算步长),可选字段都是指针——nil 时不发送该键,由服务端取默认值。查询工具的 params 不可为空:NewDatasourceQueryInvokeRequest(..., nil) 直接返回错误,与通用请求「省略即 {}」的规则不同。执行模式受数据源类型约束:Prometheus 与 Loki 用 instant / range(instant 只带 to_ms),SQL 类型(MySQL、Postgres、Oracle、ClickHouse 以及走 SQL 的 Elasticsearch)与 SLS、Tencent CLS 用 window,VictoriaLogs 原始日志用 window、统计查询用 instant / range;Loki、VictoriaLogs、SLS、Tencent CLS 的 limit / direction 只作用于原始日志检索,SLSQueryParams 另需 project / logstore,TencentCLSQueryParams 另需 region / topic_id / syntax。

Prometheus 标签值

client.DataSources.ReadPrometheusLabelValues(ctx, dataSourceID, labelName)(GET /monit/prometheus/api/v1/label/{label_name}/values,monit-prometheus-read-label-values)通过监控代理列出某个 Prometheus 兼容数据源上单个标签的全部取值:标签名放在 URL 路径上(SDK 会做路径转义),目标数据源由 X-DSID 请求头指定——SDK 用 dataSourceID 自动设置该头(传 0 或 labelName 为空都直接报错),ID 从 /monit/datasource/list 获取,必须是当前账户下 Prometheus 兼容类型的数据源。这是唯一一个成功响应体不是 Flashduty {request_id, data} 信封的方法:响应直接解码为 PrometheusLabelValuesResponse(status 为 success 时 data 是标签值字符串数组;为 error 时携带 errorType 与 error)。未到达数据源前的失败(X-DSID 非法、数据源不存在、数据源不是 Prometheus 类型)以 text/plain 返回,数据源自身的失败则用它自己的 JSON 错误形态;SDK 对两者一视同仁,把原始响应体原样放进 *ErrorResponse.Message。有两类情况不返回错误:请求不带 X-DSID,以及该数据源所在 monit-edge 集群里有实例版本低于 v0.35.0(不支持资源代理)——两者都返回 200 与空的 Prometheus 兼容结果,/api/v1/labels、/api/v1/series、/api/v1/label/{label_name}/values 的 data 是空数组,/api/v1/metadata 的 data 是空对象。也就是说读到空结果时不要当成「这个标签没有取值」,先确认 X-DSID 是否带上、edge 是否需要升级。受支持的部署要求 monit-edge v0.35.0 及以上版本。

数据源配置

client.DataSources 的 payload 按 type_ident 选择类型专属配置块。当前允许的 type_ident 共 15 种:prometheus、loki、mysql、oracle、postgres、clickhouse、elasticsearch、sls、tencent_cls、victorialogs,以及诊断专用类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos、kafka——诊断专用类型的 alerting_enabled 恒为 false(不阻止非告警查询与工具调用),且拒绝传 true。连接地址规则:Redis/MongoDB 诊断类型为单个 host:port(IPv6 需加方括号),不接受 URI、userinfo 或 query;kafka 为 1–32 个以逗号分隔、互不重复的 host:port bootstrap 地址(规范化后至多 4096 字符);mongodb_mongod / mongodb_mongos 的配置块中 auth_source 默认为 admin,用户名与密码必须成对配置,不支持客户端证书;Redis 节点配置的 database 默认为 0。诊断类型的 password 与 Kafka 的 tls_key 等敏感字段支持 ${env:NAME} 引用:响应中字面值会被省略(仅当存储值本身就是 ${env:...} 引用时才回显),更新时省略这些字段即保留原值,显式传空字符串则清除。 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 仍只需一次方法调用即可取到。
  • 序列化(出站):非零值序列化为带引号的 RFC3339 字符串(TimestampMilli 用 RFC3339Nano 以保留毫秒精度)。零值序列化为裸整数 0——一个”未设置”哨兵,而非 1970 年的日期,并被 json:",omitempty" 丢弃。
  • 反序列化(入站):既兼容数字 epoch(线上原始形态),也兼容 RFC3339 字符串(使序列化后的值可无损往返),还接受 null(→ 0)。
请求侧时间字段仍为 int64,API 在 wire 上要求数字 epoch。注意:多数接口取秒,但 RUM 与 webhook 历史相关接口取毫秒。请求与响应共用的类型同样如此:AlertRuleV2(AlertRules.ReadInfoV2 / WriteCreateV2 / WriteUpdateV2 的返回类型,对应 POST /monit/rule/v2/info、/v2/create、/v2/update)的 created_at / updated_at 在 SDK 中仍是裸 int64(Unix 秒,带 omitempty),而不是 Timestamp。这类字段不支持 Unix() / String() / IsZero(),需要自行把秒值转成时间;按 Timestamp 示例写 rule.UpdatedAt.Unix() 会编译不过。
同样属于 AlertRuleV2(AlertRules.ReadInfoV2 / WriteCreateV2 / WriteUpdateV2 的返回类型)的 investigation_targets 也换了形状,形状如下:
  • 字段本身是 []InvestigationTarget,最多 20 项且不允许重复;整个列表序列化后还不得超过 32 KiB(32768 字节),超限报 investigation_targets must not exceed 32768 bytes。更新接口按 presence 处理——省略保留原配置,传 [] 清空。每个入口可带可选的 purpose:一句话纯文本,说明该入口帮助确认什么排查意图(文本里不要写换行,服务端按 ≤512 字节校验,且必须是合法 UTF-8、不含控制字符;控制台的输入框限 200 个字符,因此 API 侧可以比控制台多填一些,但 200 个中文字符就可能超过 512 字节)。purpose 不是模板,也不参与告警身份与去重。
  • 每个入口是封闭的 tagged union,Kind 决定必须提供哪个子对象:dashboard(打开仪表盘面板)必须给 Dashboard,query(打开 Explore 查询)必须给 Query,提供另一个会被拒绝,入口内出现未知字段同样会被拒绝。
  • TimeRange(InvestigationTimeRange:BeforeSeconds 与 AfterSeconds)在每个已保存的入口上都必填——两个方向都非负,且至少一个大于 0。
  • Dashboard 入口(DashboardInvestigationTarget)的变量是 Variables:map[string]string,键为变量名、值为字面取值,可用 {{ }} 模板引用事件标签。DashboardID 与 Variables 必填,TargetID 可选;DashboardID 与 TargetID 都必须是规范的 UUIDv7。
  • Query 入口用 QueryInvestigationTarget:Query(必填)为 DashboardQuery——Mode 取 instant / range / window,Expr 是目标数据源原生语法的表达式且可用 {{ }} 模板,Args 是原样透传的命名参数、不允许出现模板,MinStepSeconds 仅在 Mode 为 range 时接受;DatasourceID 可省略(或填 0),表示使用告警事件自身的数据源。

分页

所有列表接口共享 ListOptions,将其内嵌在请求结构体中即可。零值会被省略,不会覆盖服务端默认值(后端默认 p=1、limit=20)。 响应侧,*Response 携带 Total、HasNextPage 与 SearchAfterCtx。推荐用 search-after 游标逐页遍历:

错误处理

Flashduty API 返回的未成功调用——无论是信封中携带了错误,还是 HTTP 状态非 2xx——都会返回 *ErrorResponse。它带有 Code、Message、可选的 Reason 与 RequestID 字段,排障时把 RequestID 提供给支持团队即可定位。Reason 携带服务端给出的可选原因(信封内的 DutyError 同样带有该字段,JSON 字段为 reason,omitempty);非空时它也会被追加到错误字符串末尾,形如 , reason X。 当 API 返回 429 时,错误被提升为 *RateLimitError:它内嵌 *ErrorResponse(所以 errors.As 取 *ErrorResponse 仍然成立),并额外带上 RetryAfter 提示。Code 与 Open API 的错误码列表一一对应。
对于生成接口,如果您收到的是带非 JSON 响应体的非 2xx 响应,SDK 会返回普通 error,而不是 *ErrorResponse。这表示响应来自网关、负载均衡器或代理等中间层,通常是请求超过了中间层超时。您可以重试请求,或将耗时较长的批量请求拆分为更小的批次;不要假定 errors.As(err, &apiErr) 能匹配此类错误。手写方法 client.DataSources.ReadPrometheusLabelValues 是例外:它不解析信封,而是把非 2xx 的原始响应体按原文放进 *ErrorResponse.Message 返回——平台的 text/plain 4xx/5xx 与数据源自身的 JSON 错误形态一视同仁,429 仍提升为 *RateLimitError。因此在这个方法上 errors.As(err, &apiErr) 是成立的,只是 Code 通常为空,需要读 Message 与 Response.StatusCode 判断原因。
类型化判定函数能省去字符串比较,并能穿透被包裹的错误(内部用 errors.As):

重试

核心客户端不内置自动重试。请通过传输层组合可选的 retry 子包——一个安全默认的重试型 http.RoundTripper。 github.com/flashcatcloud/go-flashduty/retry 的特性:
  • 重试条件:HTTP 429、任意 5xx(状态码 ≥ 500),以及传输错误。其他 4xx 与所有 2xx/3xx 立即返回。
  • 退避策略:确定性指数退避(MinWait * 2^attempt,每次上限为 MaxWait);无随机抖动。存在合法的整数 Retry-After 头时,以其为准(同样不超过 MaxWait)。
  • 安全回放:仅当请求体可回放(req.Body 为 nil 或 req.GetBody 非空)时才重试,每次重试都在请求的克隆上重建请求体,绝不修改调用方的原始 *http.Request。SDK 构造的所有请求都设置了 GetBody,因此 POST 请求体都可安全回放。
  • 尊重取消:等待退避期间若请求 context 被取消,立即返回 context 错误。
retry 子包是纯 net/http 实现,刻意不导入父级 flashduty 包,因此永远不会引入循环依赖。retry.New() 与 &retry.Transport{}(零值)都开箱即用。

AI SRE 会话

程序化驱动一个 AI SRE 会话分三步:写入用户轮次、订阅事件流取回回复、需要留档时导出整段转录。前两步用 client.Sessions.WriteMessage 与 client.Sessions.Subscribe,第三步用 流式导出 里的 client.Sessions.Export。

会话写入(创建会话 / 发送消息 / 上传附件)

用 client.Sessions.WriteMessage(POST /safari/session/message)发一个用户轮次。省略 SessionID 即新建会话,此时 AppName(如 ai-sre)与 EntryKind 必填,EntryKind 取 web、im 或 api。Query 是消息正文,最长 32000 个字符。 其余字段都可省略:
  • Parts:附加的消息片段,每项是 SessionMessagePart,Type 取 text 或 file。text 用 Text 字段;file 用 File(SessionFilePart 的 Mime、Filename、ObjectKey、Size),指向已上传到该会话的文件。
  • Surface:轮次的来源标记,例如 cli。
  • DeliveryMode:协商回复的投递方式。取 reply_only 时 agent 只用回复工具作答;响应的 SessionMessageAck.DeliveryMode 是服务端实际接受的方式,为空表示请求的投递方式未被接受。
  • Steering:把这条消息标记为「回合仍在运行时发出」。为 true 时,正在运行的那个回合会在下一个步骤把这条消息并入并由它作答,答复因此来自该回合的事件流,而不只是这条消息自己的调用;会话没有回合在运行时该字段被忽略,消息照常排队。
  • EnvironmentKind:执行环境,取 cloud 或 byoc;EnvironmentID 在该类型下指定具体环境。
  • TeamID:把新建会话绑定到某个团队,0 表示账户作用域。
WriteMessage 在服务端把该轮次持久入队后立即返回(HTTP 202),响应只有 SessionID、InvocationID、RootInvocationID 与实际授予的 DeliveryMode。轮次异步执行,回复不在这个响应里,要从会话事件流读取(见下文「会话事件流」)。 附件必须挂在已存在的会话下。要在第一条消息之前上传附件,先用 WriteCreate(POST /safari/session/create)建一个空会话:AppName 必填,EntryKind 取 web、im、api 或 automation,TeamID 创建后不可修改。 UploadAttachment(POST /safari/attachment/upload)把文件存到某个会话下。SessionAttachmentUploadRequest 的 SessionID、File、Filename 都必填,单个文件最大 50 MB。返回的 SessionAttachment 用 FilePart() 转成 SessionMessagePart,直接放进下一条消息的 Parts:
设置了 Parts 时服务端忽略 Query,文字要放进 text 类型的 Part。

会话事件流(Subscribe / SSE)

client.Sessions.Subscribe(POST /safari/session/subscribe,Accept: text/event-stream)打开会话的事件流,返回 io.ReadCloser。这条流先重放严格晚于游标的已持久事件,再持续推送实时帧;Export 则是对整段转录的一次性 NDJSON 读取,两者用途不同。 用 NewSessionFrameReader 与 Next() 读帧:
  • 游标:SessionSubscribeRequest.LastEventAt 是 Unix 毫秒,0 表示从会话开始重放;LastEventID 只在同一毫秒内的事件之间定序。把上一帧的 CreatedAt 与 EventID 填回这两个字段,就从该帧之后续读,断开后重连不会重复已处理的事件。
  • 生命周期:流在时间上没有上限,服务端在空闲一段时间后关闭它。流的存活时间由 ctx 决定,需要停止时取消 ctx。返回的 io.ReadCloser 由调用方持有并必须 Close。
  • 结束与错误:Next() 在收到 [DONE] 或流被正常关闭时返回 io.EOF;流内的错误记录返回 *SessionStreamError;其余情况(含 ctx 取消)返回传输错误。非 2xx 状态仍是常规 JSON 错误信封,Subscribe 会读取并关闭它,返回与生成接口一致的类型化错误,io.ReadCloser 为 nil。
  • 帧字段:SessionEventFrame 带 EventID、CreatedAt、Type、AgentPath、Payload(原始 JSON)、InvocationID、RootInvocationID、DeliveryMode、IsError 与 ErrorCode。持久事件有 EventID 与 CreatedAt,Type 是作者(user、assistant 等);临时帧(turn_complete、assistant_token 等)没有 EventID,Type 是帧类型。
  • 与 reply_only 的关系:用 DeliveryMode: "reply_only" 发送的轮次,回复只出现在这条流里,不会出现在 WriteMessage 的响应中。

流式导出

client.Sessions.Export 用于导出一个 AI SRE 会话的完整事件转录,返回的是 io.ReadCloser(NDJSON 流,application/x-ndjson),而非 JSON 信封。首行始终是一条 session_meta 信封,其后每行是一个会话事件;当 req.IncludeSubagents 为 true 时,每条 subagent_dispatch 行后会跟随子会话自身的完整事件流。 由于响应体可能很大,应当逐行读取并直接写入文件,不要把整段转录缓冲进内存。返回的 io.ReadCloser 是活动 HTTP 响应体,由调用方持有并必须 Close(defer 关闭即正确)。配合 NewExportScanner 可按行扫描,DecodeExportLine 可将一行解码为 ExportLine:
NewExportScanner 配置的单行缓冲区足以容纳转录中较宽的事件行(如 tool 输出、LLM 调用),不受默认 64KB token 上限限制。任何非 2xx 状态下,响应体仍是常规 JSON 错误信封——Export 会读取并关闭它,返回类型化错误(*ErrorResponse,429 时为 *RateLimitError),此时 io.ReadCloser 为 nil,与其他生成接口行为一致。