api-status-communication

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Status Communication

API状态沟通

You are designing how an API platform tells its external consumers what is happening - the status page, incident updates, public postmortems, SLA/SLO reporting, and maintenance notices. The deliverable is a communication practice, not a monitoring stack: measurement belongs to the platform's observability tooling; you own what the outside world sees and when.

Trustworthiness is the design constraint every step below serves. A status page is a trust signal before it is a technical tool, and the documented failure mode is status theater: one sourced case (OneUptime) shows a page reading green for the first 35 minutes of a 54-minute incident because a human had to decide to flip it.

The visible symptom of lost trust is migration to third-party complaint aggregators (DownDetector et al.) - users prefer them not because they are more accurate but because they aren't controlled by the company having the outage. Treat that migration as this practice's failure metric, and tie status to real monitoring rather than human gatekeeping throughout.

你在设计API平台如何告知外部消费者正在发生的事情 - 状态页面、事件更新、公开事后分析、SLA/SLO报告和维护通知。交付物是一种沟通实践，而非监控技术栈：测量属于平台的可观测性工具；你掌控的是外部世界看到什么以及何时看到。

可信度是以下每一步所服务的设计约束。状态页面在成为技术工具之前首先是一个信任信号，记录在案的失败模式是“状态秀”（status theater）：一个引用的案例（OneUptime）显示，在54分钟的事件中，页面在前35分钟一直显示绿色，因为需要人类来决定是否切换状态。

信任丧失的明显症状是用户迁移到第三方投诉聚合器（DownDetector等） - 用户更喜欢它们不是因为它们更准确，而是因为它们不受发生故障的公司控制。将这种迁移视为该实践失败的指标，并始终将状态与真实监控而非人工把关绑定。

Clarifying questions

澄清问题

Ask these before designing anything; each answer changes a later step. Batch them - this is a tactical design task, not a strategy interview.

Existing status page or greenfield? If one exists, request its URL and the full update history of the last 2-3 incidents.
Is status set by monitoring today, or does a human flip it? Which health checks, latency thresholds, and uptime probes already exist?
Who reads the page: integrating developers, business stakeholders/end customers, enterprise customers - in what mix? (see next section)
Are there contractual SLAs with consequences attached, and do any contracts specify a maintenance-notice floor?
Does the status page share infrastructure with the platform itself (same DNS, CDN, cloud account)? (drives channel redundancy in step 3)
In the last few incidents, how did consumers actually find out - and did any third party report the outage before the page did?
Deadline and effort ceiling - three sub-questions:
- By when must this practice be live?
- Is it a one-off fix after a bad incident, or a compounding trust asset you will run for years?
- What can you spend: engineering hours to wire monitoring, an on-call rotation to hold cadence, budget for per-message channels?

Question 7 exists because the channel and postmortem menus diverge sharply on effort and on how long the payoff lasts, and neither ranking in steps 3 and 5 can be picked without it.

A hard deadline promotes the rungs hosted tooling gives you nearly free.
A compounding-asset mandate promotes out-of-band redundancy and the deep write-up.

If your harness has persistent memory, store the practice's core decisions: component model and blend rule, escalation thresholds, channel set, postmortem-depth policy, published SLA edge cases. Later runs - a live incident, a postmortem, a maintenance notice - start from the practice instead of re-deriving it.

在设计任何东西之前先问这些问题；每个答案都会改变后续步骤。批量提问 - 这是一个战术性设计任务，不是策略面试。

已有状态页面还是全新建设？如果已存在，请求其URL和最近2-3次事件的完整更新历史。
当前状态是由监控设置，还是由人工切换？已经存在哪些健康检查、延迟阈值和正常运行时间探针？
谁在阅读页面：集成开发者、业务利益相关者/终端客户、企业客户 - 比例如何？（见下一节）
是否存在带有后果的合同SLA，是否有任何合同规定了维护通知的最短期限？
状态页面是否与平台本身共享基础设施（相同的DNS、CDN、云账户）？（驱动第3步中的渠道冗余）
在最近几次事件中，消费者实际上是如何得知的 - 是否有第三方在页面之前报告了故障？
截止日期和精力上限 - 三个子问题：
- 这个实践必须何时上线？
- 是一次性修复糟糕事件后的补救，还是一个将持续运营多年的复利式信任资产？
- 你能投入什么：用于接入监控的工程工时、维持节奏的轮值待命、每条消息渠道的预算？

问题7之所以存在，是因为渠道和事后分析菜单在精力和收益持续时间上差异巨大，没有它就无法选择第3步和第5步中的任何一个排序。

硬性截止日期会推动使用托管工具几乎免费提供的阶梯。
复利式资产的要求会推动带外冗余和深度撰写。

如果你的框架有持久化记忆，请存储该实践的核心决策：组件模型和混合规则、升级阈值、渠道集合、事后分析深度策略、已发布的SLA边界情况。后续运行 - 实时事件、事后分析、维护通知 - 从该实践开始，而不是重新推导。

Reader roles

读者角色

Regardless of whoever bought the product, the people reading a status page during an incident split by role, and the two roles want different pages:

Integrating developers - want component-level technical detail: which endpoints, per-region scoping, latency numbers, timestamps, and a postmortem deep enough to trust. They wire status into their own alerting, which makes machine-readable push channels (webhook, RSS) first-class.
Business stakeholders and end customers - want plain language: is it down, what's affected, when will it be fixed. Latency metrics read as noise to them.

Audience-tiered pages are the established pattern for API providers when the mix demands it:

A public developer-facing page with API-level detail.
An enterprise page behind SSO showing SLA compliance.
Plain-language end-user messaging.

Default to one public developer-facing page and add tiers only when question 3 shows a real second audience - every extra tier is another surface to keep consistent during a live incident.

无论产品是谁购买的，事件期间阅读状态页面的人按角色划分，两种角色想要不同的页面：

集成开发者 - 想要组件级技术细节：哪些端点、按区域的范围、延迟数据、时间戳，以及足够深入以建立信任的事后分析。他们将状态接入自己的告警系统，这使得机器可读的推送渠道（webhook、RSS）成为一等公民。
业务利益相关者和终端客户 - 想要通俗易懂的语言：是否宕机、影响什么、何时修复。延迟指标对他们来说如同噪音。

当受众构成需要时，分层页面是API提供商的既定模式：

面向开发者的公开页面，包含API级别的详细信息。
SSO后面的企业页面，显示SLA合规性。
通俗易懂的终端用户消息。

默认使用一个面向开发者的公开页面，只有当问题3显示存在真实的第二受众时才添加层级 - 每个额外层级都是在实时事件期间需要保持一致的另一个表面。

Workflow

工作流程

Model the status vocabulary and component granularity.
Wire status to monitoring - the trust step.
Choose the channels: pull page plus push subscriptions.
Design the incident-lifecycle communication practice.
Set the postmortem policy.
Publish SLA/SLO reporting.
Set maintenance-window conventions.

Each step has a section below, in order.

建模状态词汇和组件粒度。
将状态接入监控 - 信任步骤。
选择渠道：拉取页面加推送订阅。
设计事件生命周期沟通实践。
设定事后分析策略。
发布SLA/SLO报告。
设定维护窗口约定。

每一步都在下面有对应章节，按顺序排列。

1. Model statuses and components

1. 建模状态和组件

Use the four de facto incident-lifecycle statuses below. Subscribers already read this vocabulary (it is Statuspage's, industry-wide); a custom set costs comprehension and buys nothing.
- Investigating - alerted, looking into a potential problem.
- Identified - cause or affected component confirmed.
- Monitoring - fix deployed, being watched.
- Resolved
Model component severity as breadth of impact, not felt severity - the single most load-bearing decision here.
- Degraded Performance: works but slow for everyone.
- Partial Outage: completely broken for a subset (e.g. one region).
- Major Outage: unavailable for everyone.
Cap the page at four visual states (operational / degraded / partial / major, the industry green-yellow-orange-red). Five severities across many components is a matrix no reader holds in their head mid-incident.
Aggregate the top-level page status from the worst component state, and document the blend rule you choose so it is applied consistently, not re-argued per incident.
Choose component granularity by the user's mental model of the product, never by internal architecture - forty microservice names turn the page into noise exactly when it must be parseable. Group into a handful of consumer-recognizable components (e.g. API, dashboard, webhooks, docs) rather than one flat internal list.
Scope regional incidents regionally: one data center down should read as a scoped partial outage, not a blanket "degraded" alarming users elsewhere - Cloudflare's page signals per-region for exactly this reason.
Note the uptime-math consequence now: Degraded Performance conventionally counts as 0% downtime in SLA arithmetic, so a headline uptime figure can look excellent while masking real incidents. Step 6 handles the honest-reporting side of this.

使用以下四个事实上的事件生命周期状态。订阅者已经熟悉这套词汇（这是Statuspage的，行业通用）；自定义状态集只会增加理解成本而没有任何收益。
- 调查中（Investigating） - 已收到告警，正在调查潜在问题。
- 已确认（Identified） - 已确认原因或受影响组件。
- 监控中（Monitoring） - 修复已部署，正在观察。
- 已解决（Resolved）
将组件严重程度建模为影响广度，而非感知严重度 - 这是这里最重要的决策。
- 性能降级：可用但对所有人来说缓慢。
- 部分中断：对子集完全不可用（例如一个区域）。
- 重大中断：对所有人不可用。
将页面限制为四种视觉状态（正常运行 / 降级 / 部分 / 重大，即行业中的绿-黄-橙-红）。跨多个组件的五种严重程度是一个矩阵，没有读者在事件期间能记住。
从最差的组件状态聚合顶级页面状态，并记录你选择的混合规则，以便一致地应用，而不是每次事件都重新争论。
根据用户对产品的心理模型选择组件粒度，绝不要根据内部架构 - 四十个微服务名称会在页面最需要可解析的时候将它变成噪音。分组为少数几个消费者可识别的组件（例如API、仪表盘、webhooks、文档），而不是一个扁平的内部列表。
按区域限定区域事件的范围：一个数据中心宕机应显示为有范围的部分中断，而不是向其他地区的用户发出笼统的“降级”警报 - Cloudflare的页面正是出于这个原因按区域发出信号。
现在注意正常运行时间计算的影响：性能降级在SLA计算中通常算作0%停机时间，因此头条正常运行时间数字可能看起来很漂亮，同时掩盖了真实事件。第6步处理诚实报告这一面。

2. Wire status to monitoring

2. 将状态接入监控

Tie page state directly to health checks, latency thresholds, and uptime data. No human gate decides whether customers "deserve to know" - that gate is what produced the 35-minute green lie.
Auto-open an Investigating incident from the monitoring alert; humans then add substance, scope, and cadence. The human role is enrichment, never first disclosure.
Write down your own staged escalation pipeline - the explicit rule for when an internal event becomes a public communication. Copy Cloudflare's citable staging below, set your own thresholds.
1. Events trigger alerts.
2. Some alerts become incidents of note.
3. All are triaged.
4. Some become problems.
5. "Major" problems trigger status-page updates.
6. P1 majors require a full published incident report.
Include at least one workflow-level probe (a real multi-step user journey), not only infrastructure checks: infrastructure-green and product-broken are different claims. The sourced cautionary case (Sentry) is a retailer at perfect uptime while checkout was silently broken for a user segment.
Hold the granularity tension honestly rather than resolving it by fiat: in almost any real outage most components still show green, and ThousandEyes' point is that a locked-out user does not care that everything but authentication is fine.
An all-red page fails the reader in the other direction - that is the "sea of green dots" criticism aimed at AWS, cutting both ways. Step 1's granularity is the mitigation here, not a slogan.
Aim for calibrated accuracy, not maximal alarm. A long green history honestly earned is itself valuable (Splunk): it stops one outage from reading as "the whole product is unreliable".
Expect transparency to pay back: the trust–transparency paradox documented around Cloudflare's practice is that openly admitting failure increases customer trust in the provider's competence to handle the next one. A well-run public incident is evidence, not only liability.

将页面状态直接绑定到健康检查、延迟阈值和正常运行时间数据。没有人工把关来决定客户是否“应该知道” - 正是这种把关产生了35分钟的绿色谎言。
从监控告警自动开启**调查中（Investigating）**事件；然后人类添加实质内容、范围和节奏。人类的角色是丰富信息，绝不是首次披露。
写下你自己的分阶段升级管道 - 明确内部事件何时成为公开沟通的规则。参考下面Cloudflare的可引用分级，设定你自己的阈值。
1. 事件触发告警。
2. 一些告警成为值得关注的事件。
3. 所有事件都被分诊。
4. 一些成为问题。
5. “重大”问题触发状态页面更新。
6. P1级重大问题需要完整的已发布事件报告。
至少包含一个工作流级探针（真实的多步骤用户旅程），而不仅仅是基础设施检查：基础设施绿色和产品损坏是不同的声明。引用的警示案例（Sentry）是一个零售商保持完美正常运行时间，而结账功能对一个用户群悄然损坏。
诚实地保持粒度张力，而不是通过武断解决：在几乎任何真实的故障中，大多数组件仍然显示绿色，ThousandEyes的观点是被锁定的用户不在乎除了认证之外的一切都正常。
全红页面则在另一个方向上让读者失望 - 这就是针对AWS的“绿色圆点海洋”批评，双向适用。第1步的粒度是这里的缓解措施，而不是口号。
目标是校准的准确性，而不是最大化的警报。诚实赢得的长期绿色历史本身就很有价值（Splunk）：它可以防止一次故障被解读为“整个产品不可靠”。
期待透明度的回报：围绕Cloudflare实践记录的信任-透明度悖论是，公开承认失败会增加客户对提供商处理下一次故障能力的信任。一次处理良好的公开事件是证据，而不仅仅是负担。

3. Choose the channels

3. 选择渠道

A status page is a pull channel - the customer has to go check it. Subscriptions (email, RSS, webhook, SMS) are push. Cloudflare's own self-critique of its pull-only page - it creates "confusion and wasted resources" during live incidents - is the design argument: a mature practice needs both, not either.

efficiency:

page + built-in email/RSS subscription > webhook push > SMS push

value during a live incident:
```
any push channel > the pull page alone
```

effort:

SMS push > webhook push > page + email/RSS subscription

Default rung: the status page with email and RSS subscription enabled. With hosted status tooling this comes nearly free, and subscription is a support-load lever, not a courtesy - letting affected users self-serve the answer measurably reduces inbound tickets during an incident (Atlassian).
Promote webhook push when question 3 says developers: an integrator audience wires status into its own alerting, and machine-readable push is what makes that possible. If the platform already runs webhook infrastructure, this rung gets cheap - the delivery machinery is sibling
```
samber/developer-platform-skills@webhook-platform-design
```
territory; you only define the status event.
Promote SMS/phone-grade push for enterprise customers with contractual SLAs - the audience whose contracts (question 4) often expect it, and the only rung whose per-message cost and deliverability work justify the effort.
Deleted, not demoted: SMS/phone-grade push with no contractual audience. When question 4 returns no SLAs with consequences and question 3 no enterprise tier, this rung leaves the menu rather than sitting at its bottom - per-message cost and deliverability work bought for nobody. Not parked last, because "we could add SMS later" reappears as scope every time an incident feels loud. Re-promotion trigger: the first contract that specifies a notification channel.
The starved option: out-of-band redundancy - hosting the page off the platform's own infrastructure and keeping at least one channel that works when your DNS or CDN is down. Highest effort, invisible value on a good day, so it loses every efficiency round; question 5 is what promotes it, because a status page that dies with the platform is worth nothing at the only moment it matters. Status pages becoming unreachable during the outage they should be reporting is a documented failure mode.
This ranking is a default, not a law. Re-rank against what you know about the user and say which answer moved which rung:
- An enterprise-heavy base promotes SMS.
- An integrator base that already consumes the platform's webhooks gets webhook push nearly free.
- A page already hosted on shared infrastructure makes redundancy the first task rather than the last.
- Question 7's effort ceiling decides how many rungs land in the first pass.

状态页面是一个拉取渠道 - 客户必须去查看。订阅（电子邮件、RSS、webhook、SMS）是推送。Cloudflare对自己纯拉取页面的自我批评 - 它在实时事件期间造成“混乱和资源浪费” - 就是设计论点：一个成熟的实践需要两者，而非二选一。

效率：

页面 + 内置电子邮件/RSS订阅 > webhook推送 > SMS推送

实时事件期间的价值：

任何推送渠道 > 单独的拉取页面

精力：

SMS推送 > webhook推送 > 页面 + 电子邮件/RSS订阅

默认阶梯：启用电子邮件和RSS订阅的状态页面。 使用托管状态工具这几乎免费，订阅是支持负载的杠杆，而非礼遇 - 让受影响的用户自助获取答案可显著减少事件期间的流入工单（Atlassian）。
提升webhook推送当问题3表明是开发者受众时：集成商受众将状态接入自己的告警系统，机器可读的推送使之成为可能。如果平台已经运行webhook基础设施，这个阶梯就变得便宜 - 投递机制是姊妹技能
```
samber/developer-platform-skills@webhook-platform-design
```
的领域；你只需定义状态事件。
提升SMS/电话级推送适用于有合同SLA的企业客户 - 这个受众的合同（问题4）通常期望它，也是唯一一个每条消息成本和可投递性工作能证明其价值的阶梯。
删除，而非降级：没有合同受众的SMS/电话级推送。 当问题4返回没有带后果的SLA且问题3没有企业层级时，这个阶梯从菜单中移除而不是放在底部 - 每条消息的成本和可投递性工作是为无人购买的。不放在最后，因为“我们以后可以添加SMS”每次事件感觉严重时都会作为范围再次出现。重新提升的触发条件：第一份指定通知渠道的合同。
被忽视的选项：带外冗余 - 将页面托管在平台自身基础设施之外，并保持至少一个在DNS或CDN宕机时仍能工作的渠道。最高精力，在好日子里价值不可见，所以它在每轮效率比较中都会输；问题5是提升它的因素，因为一个随平台一起死掉的状态页面在唯一重要的时刻毫无价值。状态页面在它们应该报告的故障期间变得不可达是一个记录在案的失败模式。
这个排序是默认值，不是法则。根据你对用户的了解重新排序，并说明哪个答案移动了哪个阶梯：
- 企业为主的用户群会提升SMS。
- 已经消费平台webhooks的集成商用户群几乎免费获得webhook推送。
- 已经托管在共享基础设施上的页面使冗余成为第一个任务而不是最后一个。
- 问题7的精力上限决定第一轮有多少阶梯落地。

4. Design the incident-lifecycle communication practice

4. 设计事件生命周期沟通实践

Run every incident through the four statuses of step 1, writing updates against Atlassian's five practices - the industry checklist:

Early - an update saying "still investigating, nothing new yet" beats silence; silence makes readers assume the worst.
Often - commit to a cadence: every update names the time of the next one, and that promise is kept even with nothing new to say.
Precise - facts over speculation; state what is confirmed, not what is suspected.
Consistent across channels - page, social, email must say the same thing at the same time; a customer mid-incident experiences "your service is broken" regardless of whose fault it technically is.
Own it with empathy - acknowledge impact, apologize when warranted, and never deflect to an upstream vendor even when the root cause is genuinely theirs.

Title incidents in plain language stating the nature of the problem ("Elevated error rates on the REST API in eu-west"), never internal codenames - internal template names exist for team organization and must not surface publicly. Map your internal severity vocabulary (SEV1-4 or equivalent) onto component states once, in writing, so responders know what to flip without debating it mid-incident.

See references/incident-update-templates.md for per-status update templates, a severity-to-component-state mapping, and good/bad update pairs.

让每个事件都经过第1步的四个状态，按照Atlassian的五个实践撰写更新 - 行业检查清单：

早期 - 一条说“仍在调查中，暂无新信息”的更新胜过沉默；沉默让读者做最坏的假设。
频繁 - 承诺一个节奏：每次更新都说明下一次更新时间，即使没有新消息也要遵守承诺。
精确 - 事实胜于猜测；说明已确认的内容，而不是怀疑的内容。
跨渠道一致 - 页面、社交媒体、电子邮件必须在同一时间说同样的话；事件中的客户体验是“你的服务坏了”，无论技术上是谁的错。
以同理心承担责任 - 承认影响，在适当的时候道歉，即使根本原因确实是上游供应商的，也绝不推卸。

用通俗语言为事件命名，说明问题的性质（“eu-west区域REST API错误率升高”），绝不要使用内部代号 - 内部模板名称用于团队组织，绝不能公开出现。将你的内部严重程度词汇（SEV1-4或同等）一次性书面映射到组件状态上，以便响应者知道该切换什么，而不必在事件中争论。

参见 references/incident-update-templates.md 了解各状态更新模板、严重程度到组件状态的映射，以及好/坏更新对比。

5. Set the postmortem policy

5. 设定事后分析策略

Publishing a postmortem externally is a deliberate decision - it affects legal exposure, customer trust, and reliability culture. The sourced default for developer platforms leans toward publishing anyway.

Google SRE's position is that a postmortem's value is proportional to the learning it creates, so sharing it "perhaps even with your customers" multiplies that value. Google SRE also calls a thoughtful and honest postmortem "a key tool in restoring shaken trust."

Depth ladder for what to publish per incident:

value for rebuilding developer trust:

engineering-blog postmortem > status-page summary postmortem > resolved-note only

effort:

engineering-blog postmortem > status-page summary postmortem > resolved-note only

compliance cost:
```
engineering-blog postmortem > status-page summary postmortem > resolved-note only
```
- the deep write-up triggers legal and comms sign-off on cause language and named third parties, and every rung is irreversible once published: you can append a correction, never unpublish an admission an enterprise customer already screenshotted.

efficiency:

status-page summary postmortem > resolved-note only > engineering-blog postmortem

Default rung: the status-page summary postmortem - impact, cause, fix, prevention in a few paragraphs, attached to the incident. Owed for any incident that consumers visibly felt.
Step down to a resolved-note only for brief blips with no consumer-visible impact beyond the incident entry itself.
Promote to a full public postmortem for major (P1-class) incidents - Cloudflare mandates a published incident report at that tier - and whenever trust is visibly shaken. For an API audience the engineering blog is the right channel: that audience is technical and reads the deep version for trust-building, not just resolution confirmation.
The full blog write-up is the starved rung - highest value, highest effort, loses every efficiency round - and the promotion conditions above are exactly what override that. This ranking is a default, not a law: re-rank against question 7 and the user's assets, and say which answer moved which rung.
An active engineering blog and practiced writers get the deep write-up nearly free, which flips the effort line.
A one-off fix under a hard deadline holds every incident at the summary rung.

Structure the external document around the three questions a customer actually has - why did this happen, could it have been worse, how do you make sure it won't happen again - and keep it blameless in the concrete sense: never name an individual human. Postmortems without follow-through are theater; action-item completion is part of this skill's measurement, not an afterthought.

See references/public-postmortem-structure.md for the full structure, the internal-to-external filtering step, blameless-writing rules, and a skeleton.

对外发布事后分析是一个深思熟虑的决定 - 它影响法律风险、客户信任和可靠性文化。对于开发者平台，引用的默认倾向仍然是发布。

Google SRE的立场是，事后分析的价值与其创造的学习成正比，因此分享它“甚至可能与你的客户分享”会倍增其价值。Google SRE还称深思熟虑且诚实的事后分析是“恢复动摇信任的关键工具”。

每个事件发布内容的深度阶梯：

重建开发者信任的价值：

工程博客事后分析 > 状态页面摘要事后分析 > 仅已解决说明

精力：

工程博客事后分析 > 状态页面摘要事后分析 > 仅已解决说明

合规成本：
```
工程博客事后分析 > 状态页面摘要事后分析 > 仅已解决说明
```
- 深度撰写会触发法律和公关对原因措辞和提及的第三方的签核，而且一旦发布每个阶梯都是不可逆的：你可以追加更正，但永远无法撤回企业客户已经截屏的承认。

效率：

状态页面摘要事后分析 > 仅已解决说明 > 工程博客事后分析

默认阶梯：状态页面摘要事后分析 - 用几段话说明影响、原因、修复、预防，附加到事件上。对于消费者能明显感受到的任何事件都是必须的。
降级为仅已解决说明适用于短暂的闪断，除了事件条目本身之外没有消费者可见的影响。
提升为完整的公开事后分析适用于重大（P1级）事件 - Cloudflare在该级别强制要求发布事件报告 - 以及每当信任明显动摇时。对于API受众，工程博客是正确的渠道：该受众是技术性的，阅读深度版本是为了建立信任，而不仅仅是确认解决。
完整的博客撰写是被忽视的阶梯 - 最高价值、最高精力、在每轮效率比较中都会输 - 而上面的提升条件正是覆盖它的因素。这个排序是默认值，不是法则：根据问题7和用户的资产重新排序，并说明哪个答案移动了哪个阶梯。
活跃的工程博客和熟练的写作者几乎免费获得深度撰写，这会翻转精力线。
在硬性截止日期下的一次性修复将每个事件保持在摘要阶梯。

围绕客户实际有的三个问题构建外部文档 - 为什么会发生、会不会更糟、你如何确保不再发生 - 并在具体意义上保持无指责：绝不指名道姓到具体个人。没有后续跟进的事后分析是表演；行动项完成是此技能衡量的一部分，而不是事后想法。

参见 references/public-postmortem-structure.md 了解完整结构、内部到外部的过滤步骤、无指责写作规则和骨架。

6. Publish SLA/SLO reporting

6. 发布SLA/SLO报告

Keep the three terms distinct in everything public:
- SLIs are measured metrics.
- SLOs are internal targets.
- SLAs are contractual commitments with consequences.
Publishing a number you privately treat as aspirational is how disputes start.
A public SLA/uptime page is a distinct artifact from the status page, not a rebrand: it shows historical uptime against commitments; the status page shows discrete current incidents and can cover components with no formal SLA at all. A mature practice offers both - they answer "are you meeting your number" and "what is happening right now" respectively.
Define the edge cases in writing before publishing any number, each a documented dispute source:
- The response-time threshold above which a slow response counts as down.
- Whether the SLA is evaluated service-wide or per affected component.
- That planned maintenance is excluded only when adequate notice was given.
Translate percentages into stakes: state targets as minutes of allowed downtime per month alongside the percentage, and show error-budget burn where that model is in use.
Publish incident history next to the headline uptime figure. Step 1's uptime-math caveat means the percentage alone can mask real degradation - the honest page lets a reader check the number against the incidents behind it. "Monitoring without reporting is just watching"; reporting is what turns the metric into either evidence of a kept promise or a transparent admission of a missed one.

See references/sla-maintenance-reporting.md for edge-case definitions, the percentage-to-minutes table, and worked examples.

在一切公开内容中保持三个术语的区分：
- SLIs 是测量的指标。
- SLOs 是内部目标。
- SLAs 是带有后果的合同承诺。
发布一个你私下视为理想化的数字就是争议的开始方式。
公开的SLA/正常运行时间页面是与状态页面不同的产物，而不是重新包装：它显示相对于承诺的历史正常运行时间；状态页面显示离散的当前事件，并且可以覆盖完全没有正式SLA的组件。成熟的实践提供两者 - 它们分别回答“你是否达到了你的数字”和“现在正在发生什么”。
在发布任何数字之前书面定义边界情况，每个都是记录在案的争议来源：
- 超过该响应时间阈值，慢响应就算作宕机。
- SLA是按整个服务评估还是按受影响的组件评估。
- 计划维护只有在给出充分通知时才被排除。
将百分比转化为利害关系：将目标表述为每月允许的停机分钟数以及百分比，并在使用该模型的地方展示错误预算消耗。
在头条正常运行时间数字旁边发布事件历史。第1步的正常运行时间计算警告意味着仅百分比可能掩盖真实的降级 - 诚实的页面让读者可以对照背后的事件来核查数字。“没有报告的监控只是观看”；报告是将指标转化为履行承诺的证据或错过承诺的透明承认。

参见 references/sla-maintenance-reporting.md 了解边界情况定义、百分比到分钟数表和实际示例。

7. Set maintenance-window conventions

7. 设定维护窗口约定

This skill owns the 24-hour-to-2-week notice horizon. The 6-12-month runway for deprecations and breaking changes is sibling

samber/developer-platform-skills@api-versioning-policy

territory - a maintenance window and a deprecation are different communications with different timelines; never blend them into one announcement.

Scale notice with impact and audience:
- Roughly 24 hours for minor low-impact work.
- Weeks plus reminder notifications for major changes.
- Enterprise customers conventionally get a week or more, even for changes that would be same-day for self-serve users.
Check question 4's contracts for hard floors - a 5-business-day contractual minimum is a documented real-world example.
State exact start and end times with an explicit time zone - ambiguous timing is the single most common cause of maintenance confusion - and schedule against the affected users' low-traffic hours, not the provider's office hours.
State scope precisely: which endpoints and features are affected and which stay available, never a blanket "the API will be down".
Post start and completion confirmations even for short windows; visible progress signals the work is controlled.
Publish through the status page plus at least one push channel, never the page alone (step 3's pull-vs-push logic applies to planned work too).
Do not treat SLA exclusion as trust exclusion: a badly communicated window still costs trust even when the arithmetic forgives it.

Notice templates live in references/sla-maintenance-reporting.md.

此技能负责24小时到2周的通知时间范围。6-12个月的弃用和破坏性变更时间线是姊妹技能

samber/developer-platform-skills@api-versioning-policy

的领域 - 维护窗口和弃用是具有不同时间线的不同沟通；绝不要将它们混为一个公告。

根据影响和受众调整通知规模：
- 大约24小时用于低影响的小型工作。
- 数周加提醒通知用于重大变更。
- 企业客户通常获得一周或更长时间，即使对于自助用户来说可能是当天的变更。
检查问题4的合同是否有硬性下限 - 5个工作日的合同最低期限是一个记录在案的真实案例。
明确说明确切的开始和结束时间以及时区 - 模糊的时间是维护混乱的最常见原因 - 并根据受影响用户的低流量时段安排，而不是提供商的工作时间。
精确说明范围：哪些端点和功能受影响以及哪些保持可用，绝不要笼统地说“API将停机”。
即使是短窗口也要发布开始和完成确认；可见的进度表明工作处于受控状态。
通过状态页面加至少一个推送渠道发布，绝不要仅页面（第3步的拉取vs推送逻辑同样适用于计划内工作）。
不要将SLA排除视为信任排除：即使计算上可以原谅，沟通不良的窗口仍然会消耗信任。

通知模板位于 references/sla-maintenance-reporting.md。

Failure modes

失败模式

Anti-pattern checklist - each is a direct audit finding:

Status theater: monitoring is red, the page is green, because a human hadn't decided to flip it yet.
A third-party aggregator or social media reports the outage before the status page does.
Silent degraded: latency doubles for everyone and nothing is posted because the service is "technically up".
Components mirror internal architecture; the page is unreadable mid-incident.
Severity modeled as felt badness instead of breadth of impact.
The status page shares infrastructure with the platform and goes down with it.
An open incident with no update and no promised next-update time.
A public update deflecting blame to an upstream vendor.
A postmortem that names an individual, or one whose action items quietly die.
A headline uptime percentage published with no incident history beside it.
A maintenance notice with no time zone, or a blanket "the API will be down".

反模式检查清单 - 每一项都是直接的审计发现：

状态秀：监控是红色，页面是绿色，因为人类还没有决定切换它。
第三方聚合器或社交媒体在状态页面之前报告了故障。
无声降级：所有人的延迟翻倍，但没有任何发布，因为服务“技术上仍在运行”。
组件镜像内部架构；页面在事件期间不可读。
严重程度建模为感知的糟糕程度而不是影响广度。
状态页面与平台共享基础设施并随之宕机。
一个没有更新且没有承诺下次更新时间的事件。
公开更新将责任推卸给上游供应商。
指名道姓的事后分析，或者行动项悄然消失的事后分析。
发布头条正常运行时间百分比但旁边没有事件历史。
没有时区的维护通知，或笼统的“API将停机”。

Measurement

衡量指标

Detection-to-disclosure lag: the first public status change is generated from monitoring; measure alert-fired-to-page-updated on every incident and drive it to minutes. A lag in tens of minutes means a human gate is still in the loop - the 35-minutes-green case is the anti-benchmark.
Third-party-first disclosures: zero incidents where an outside aggregator or social post beat the page. Binary, per incident.
Lifecycle completeness: every incident shows all four statuses with timestamps, and every update's next-update promise was kept.
Postmortem follow-through: track public action-item completion; below ~50% is the sourced threshold at which postmortems become theater, so set your target above it and report against it.
Support-load trend: inbound tickets during incidents should fall as status subscriptions grow - the sourced direction (Atlassian); no industry threshold exists, so baseline from your own next incident and improve against it.

The first three are gates - iterate the design until they pass. The last two are trends to watch afterwards, never pass thresholds.

检测到披露的延迟：第一个公开状态变更由监控生成；在每次事件上衡量从告警触发到页面更新的时间，并将其驱动到分钟级别。数十分钟的延迟意味着人工把关仍在循环中 - 35分钟绿色案例是反基准。
第三方优先披露：外部聚合器或社交媒体帖子超过页面的零事件。每个事件为二元指标。
生命周期完整性：每个事件显示所有四个状态及时间戳，并且每次更新的下次更新承诺都被遵守。
事后分析跟进：跟踪公开行动项完成率；低于约50%是引用的阈值，低于它事后分析就变成表演，所以将目标设定在它之上并据此报告。
支持负载趋势：随着状态订阅的增长，事件期间的流入工单应该下降 - 引用的方向（Atlassian）；不存在行业阈值，因此从你自己的下一次事件建立基线并持续改进。

前三个是门槛 - 迭代设计直到通过。后两个是之后观察的趋势，绝不是通过阈值。

Invocation examples

调用示例

"Design a status page for our public API - today we only tweet when something breaks."
"Our status page stayed green through yesterday's outage and customers found out from DownDetector - fix the practice, not just the page."
"Write the public postmortem for last week's 90-minute API outage and tell me whether it belongs on the status page or the engineering blog."
"We're taking the API down for a two-hour migration in ten days - plan the maintenance communication."

“为我们的公共API设计一个状态页面 - 今天我们只在出问题时发推文。”
“我们的状态页面在昨天的故障中一直保持绿色，客户从DownDetector得知 - 修复实践，而不仅仅是页面。”
“为上周90分钟的API故障撰写公开事后分析，并告诉我它应该放在状态页面还是工程博客上。”
“我们将在十天后进行两小时的API迁移停机 - 规划维护沟通。”

References

参考

references/incident-update-templates.md - per-status update templates, severity-to-component-state mapping, good/bad update pairs, the five-practices checklist expanded.
references/public-postmortem-structure.md - public postmortem structure, internal-to-external filtering, blameless-writing rules, action-item tracking, skeleton.
references/sla-maintenance-reporting.md - SLI/SLO/SLA distinctions, edge-case definitions, percentage-to-minutes table, maintenance-notice scaling and worked examples.