概述
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)。
创建客户端
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 也相同。
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)。
同样属于
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 错误。
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,与其他生成接口行为一致。