docs: 可用性修订（基于 Don't Make Me Think 与写给大家看的设计书） by debidong · Pull Request #1033 · flashcatcloud/flashduty-docs

debidong · 2026-10-09T08:16:52Z

背景

以《Don't Make Me Think》（Steve Krug）和《写给大家看的设计书》（Robin Williams）的可用性与版式原则为依据，对 zh/en 全部文档做了一轮可用性修订。中英文同步修改。所有改动只调整表达、结构和导航，不新增产品事实；凡是数字或能力描述存在冲突的地方，都只采用能在仓库里核实的数据或改成中性措辞，无法核实的列在文末「待确认问题」中。

共 8 个提交，910 个文件变更（+2975 / −7022，删除行主要来自去掉标题下的分隔线）。

改动（按原则分组）

1. 页面要不言自明：去掉写给工程师看的实现细节

49 处 zh + 49 处 en（24 对页面）中「后端 / 前端 / 组件 / 契约 / 落地」类描述改写为用户视角：用户看到什么、能做什么。例如 dashboards.mdx「后端契约已经支持，但前端渲染器尚未落地」→「暂不支持，在类型选择器中不可选」；escalation-rule.mdx「最多 39 个字符（后端限制 40）」→「最多 39 个字符」。
对 API 用户有用的事实予以保留，并指向 Open API（如仪表盘回收站的恢复接口）。
涉及页面：Monitors（仪表盘、数据源、告警规则、查询工作台）、On-call（分派策略、降噪、作战室、行动项、自定义表单、故障时间线）、平台（组织信息、定价）、RUM 数据安全、AI SRE（会话、自动化、MCP、IM、产物、环境、Apps）。

2. 首页清晰、任务优先

首页（zh/en）的 description 补上 AI SRE，与正文和站点描述一致。
首屏改为 6 个任务入口卡片：接入第一条告警、配置值班与分派、查找告警集成、开始 AI 排障、接入 RUM SDK、创建告警规则。
8 个默认折叠的 Accordion 展开为简短的能力列表加入口链接。各产品的「适用场景」移入对应的产品介绍页（on-call / rum / monitors），没有删除。
产品视频移到产品介绍之后，并去掉 autoPlay。
AI SRE「快速开始」卡片原来指向会话页，现改为指向真正的 ai-sre/quickstart。

3. 导航：名称唯一、链接文字与目标一致、方便扫读

新增告警集成总览页 on-call/integration/alert-integration/overview（zh/en），作为「告警集成」组的第一页：先列 4 种通用接入方式，再按 A–Z 列出全部 290 个集成。
集成侧边栏名称统一：334 对页面（告警集成 + 变更集成，zh/en）的 sidebarTitle 只保留产品名，去掉「告警集成 / 集成 / 告警事件 / 指引」等不一致的后缀；修正 zh title 缺空格（如「Prometheus告警集成」）和「邮件Email集成」。
集成分组排序：两个集成分组按 slug 字母序排列，4 种通用方式（标准告警事件、邮件、HTTP 拉取、DB 拉取）置顶。
冲突命名改为唯一：
- 首页侧边栏「状态页」→「Flashduty 服务状态」，与 On-call 的状态页功能区分开。
- AI SRE 的「控制台」页 →「控制台对话」，与顶栏的「控制台」按钮区分开，并同步更新 43 处链接文字。
- 两个「自定义操作」→「故障自定义操作」/「Webhook 自定义操作」。
- OpenAPI 下的「Go SDK」→「Go SDK 快速上手」。
- AI SRE「MCP」→「MCP 外部工具」，开发者「MCP Server」→「Flashduty MCP Server」。
- AI SRE 侧边栏「了解上下文 / 了解知识 / 了解记忆」去掉多余的「了解」。
- platform/team-members 的 zh 标题「组织管理」→「团队管理」，与正文和英文一致。
链接文字与目标不符的卡片：
- 入门指南「路由规则」卡片原来链到「集成数据」，现改为链到 routing-rules。
- on-call.mdx「通知触达」卡片 → 改名「分派策略」，与目标页一致。
孤儿页 openapi/rate-limits 加入 API 导航。

4. 维护信任：修正错误和前后矛盾的说法

prometheus：api.flascat.cloud → api.flashcat.cloud、Promtheus 拼写、加粗多余空格（** Prometheus**）、「测是否」→「侧是否」。
URL 拼写修正，并在 docs.json 加 redirect：
- zh/stsatuspage → zh/statuspage
- rum/error-tracking/erro-reporting/* → error-reporting/*（zh/en，用 :slug* 通配跳转）
- 站内链接和旧 redirect 的目标已同步更新。
集成数量：首页「267」、On-call 介绍「100+」、对比页「267」统一为「290+」（仓库中有 290 个工具集成文档，另有 4 种通用方式）。
首页 API 数量「354」与 API 目录页写的「365」不一致，首页改为中性的「全部接口」。
上手时间：去掉 On-call 介绍卡片里的「5 分钟完成接入」，首页不再写分钟数；入门指南自身的「10 分钟」保留。
首页 Monitors 的名称与产品页对齐为「告警引擎」，入口文案「创建首个监控任务」→「部署 monitedge 并创建首条告警规则」（与产品页一致）。
作为当前核心 Web 指标的 FID → INP（首页场景、rum.mdx、rum/performance/overview）。SDK 采集字段、术语表里对 FID 的事实描述保留。
入门指南不再把协作空间比喻成「作战室」，因为作战室是另一个独立功能。

5. 视觉层级：对比、亲密性、重复

删除紧跟在标题下的 --- 分隔线：4302 处、744 个页面。分隔线会把标题和它的内容隔开，而且只有部分页面这样写。
修正跳级标题（h2 → h4）：RUM 分析页、CLI、blueking / keep / elastalert2。servicedesk-plus-sync 里用 h6 写的「注意」改为 <Note>。
152 个标题为「展开 / Expand」的 Accordion → 「查看专属/共享集成的配置步骤」（76 个文件）。
129 张图片的时间戳或空 alt（如 2025-09-18-15-05-10）→ 用「页面标题：章节」生成的描述。
入门指南一句话里的 5 处加粗精简为 0 处。
AI SRE 15 个子页面（zh/en 共 30 个）顶部重复的 3 行计费 Info 框 → 一行指向「开通与计费」的提示，完整信息保留在概述页、快速开始页和 ai-sre 介绍页。
分派策略页：「复制分派策略」原来插在「六个核心要素」之前，现移到第 6 个要素之后，引言处加了锚点链接。

6. 写作一致性

zh 第二人称统一为「您」（多数用法）：527 处，118 个页面。跳过 compliance/ 下的法律文本、代码、行内代码和「」“”引号里的界面原文。
界面路径分隔符统一为「→」：=> / > / -> 共 258 处，160 个页面（zh/en）。statuspage/widgets 中表示优先级顺序的 > 保留不改。

有意没有改的内容

集成页的 <div className="hide">：integration-docs/scripts/build.mjs 会在控制台内嵌文档中移除这些块，属于有意设计，不动。
296 个集成页的统一模板 / snippet：没有做。改动面太大，而且集成页还会被打包给控制台内嵌（integration-docs），风险高，建议单独立项。本 PR 只统一了侧边栏名称、Accordion 标题、alt 和明显错误。
Monitors 产品页的「同比 / 环比 / 复合告警」表格和 on-call.mdx 的「告警噪音降低 90%」：无法从仓库核实，按要求保留原文，见下方问题。
合并重复页面：AI SRE 的 ai-sre.mdx 和 ai-sre/overview.mdx、两个 Go SDK 页没有合并，只改了名称以消除歧义。合并需要内容负责人决定保留哪一版。
法律文本（compliance/）：未改动。
英文孤儿页 en/rum/error-tracking/error-reporting.mdx（不在导航中）和 en/rum/quickstart/faq.mdx（中文没有对应页）保持原样，没有删除。
英文标题大小写（Title Case 与 sentence case 混用）：本次未统一。

待确认问题

Monitors 同比 / 环比 / 复合告警：monitors.mdx 的「告警规则类型」表格写了这些类型，但首页和各告警规则文档只写了阈值判定、数据缺失、数据存在三种判定方式。哪种说法是准的？
「将告警噪音降低 90% 以上」（on-call.mdx 出现 3 次）：是否有出处？没有的话建议改成中性措辞。
集成数量：对外宣传用 290+（以文档数为准）可以吗？对比页里 PagerDuty / Opsgenie 的数字也需要定期复核。
API 数量：API 目录页写「365 个接口」，表格实际有 367 行。以哪个为准？
AI SRE 计费提示：子页面已收敛为一行。如果法务或商务要求每页都完整展示，可以回退该提交中的这部分。

验证

npx mint broken-links：通过（no broken links found）
npx mint validate：通过（build validation passed）
integration-docs：node scripts/build.mjs && node scripts/check.mjs 通过（348 keys zh/en）
本地 mint dev 渲染首页（移动端 390px）已人工检查。桌面端截图在本地超时，未看到集成总览页的渲染效果，请在 Preview 部署中复查首页和集成总览页。
注意：合并后会触发「Upload integration docs to OSS」工作流（路径 zh/on-call/integration/**），控制台内嵌的集成文档会随之更新（主要变化是 Accordion 标题和 alt）。

- prometheus: api.flascat.cloud -> api.flashcat.cloud, Promtheus, bold spacing, 测->侧 - fix skipped heading levels (h2->h4) in RUM analytics, cli, blueking/keep/elastalert2 - servicedesk-plus-sync: h6 notes -> <Note> - rename zh/stsatuspage -> zh/statuspage, rum/error-tracking/erro-reporting -> error-reporting (zh/en), update links and add redirects

A '---' right under a heading detaches the heading from its content (proximity) and was used inconsistently. 4302 rules in 744 zh/en pages.

- 152 '展开'/'Expand' accordions -> '查看专属/共享集成的配置步骤' (zh/en) - 129 timestamp/empty image alts -> page + section description

- zh: 你 -> 您 (527 occurrences, 118 pages); skipped compliance/ legal docs, inline code and quoted UI strings - zh/en: '=>', ' > ', '->' between UI path segments -> ' → ' (258 occurrences, 160 pages); statuspage/widgets.mdx kept '>' as it denotes priority order

Replace backend/frontend/component/contract wording with what users see and can do (49 zh + 49 en edits in 24 page pairs: Monitors dashboards, data sources, alert rules, escalation rules, AI SRE sessions/automations/MCP, etc.). API-relevant facts are kept and pointed at the Open API where applicable.

…d integrations - integrations: sidebarTitle = product name only (334 zh/en pairs); fix missing spaces in zh titles; groups sorted alphabetically by slug, with the generic methods (standard alert, email, HTTP pull, DB pull) kept on top - rename conflicts: 状态页 -> Flashduty 服务状态; AI SRE 控制台 -> 控制台对话 (and link texts); 自定义操作 -> 故障自定义操作 / Webhook 自定义操作; OpenAPI Go SDK -> Go SDK 快速上手; MCP -> MCP 外部工具 / Flashduty MCP Server - AI SRE: drop the redundant 了解 prefix in sidebar labels - zh team-members title 组织管理 -> 团队管理 (matches content and en) - add orphan openapi/rate-limits to API nav

- home (zh/en): description lists all four products; task entry cards first; accordions unfolded into short capability lists + links; video moved below products (no autoplay); AI SRE quickstart card now points to ai-sre/quickstart; API count replaced by neutral wording; Monitors name aligned with product page - use-case lists moved from home to on-call/rum/monitors intro pages - new on-call/integration/alert-integration/overview (zh/en): generic methods + all 290 integrations A-Z, first page of the 告警集成 group - integration count: 267 / 100+ -> 290+ (verified: 290 tool guides + 4 generic) - on-call.mdx: card 通知触达 -> 分派策略 (matches target); drop '5 分钟完成接入' - quickstart: 路由规则 card now links to routing-rules; trim 5x bold sentence; channel no longer described as a 作战室 (a separate feature) - FID -> INP where listed as a current Core Web Vital - AI SRE sub-pages: 3-line billing Info callout -> one-line pointer to overview

…lements The page announces six elements and then interrupted them with a secondary operation; it now follows element 6 as its own section, linked from the intro.

…repeat core concepts

…n and billing details to rules and outcomes

… copy and implementation notes

…es in user terms, drop API fields and error strings

…y, field names and form mechanics

…n-lapse rules

…d stream-frame API details into an API section

…drop UI copy and internal API routes

… names and console routes; keep rules

…arnings in user terms

…integrations — replace UI walkthroughs with rules and outcomes

…data sources, query workbench, alert rule guide)

…o current pages

…ts, integration permission notes — state the rule, drop UI copy and field names

debidong · 2026-10-09T10:05:31Z

第二轮精简（按页面逐段判断）

针对评审意见「第一轮清理不彻底，多为关键词替换」，这一轮逐页逐段判断：用户完成任务是否需要这段内容。规则和结果保留，实现机制删掉。中英文同步修改，产品事实不变。

范围：29 个页面（中英各 29 篇），按产品域拆成多个 commit：

AI SRE：overview、sessions、mcp、agents、skills、init、automations、artifacts、knowledge
Monitors：dashboards、data-sources、quickstart（告警规则）、explore、alert-rules/tencent-cls、alert-rules/sls
On-call：statuspage、create-manage-page、war-room、search-view-incident、templates、escalation-rule、noise-reduction、integrate-data
平台：pricing、team-members、organization-info、permission-design
RUM：app-management、error-viewing

中文 29 页合计约 59.5 万字节 → 48.3 万字节（−19%）（中英合计 1.41 MB → 1.17 MB）。

主要删减类型

逐字照录的界面文案：空状态、toast、报错、悬停提示、面板说明
逐个列举按钮或角标，以及悬停才出现之类的交互细节
内部路由、接口路径、字段名和查询参数，例如 /safari/...、chat?session_id=、team_id=0、check_nodata.enabled、monit_available、*_war_room_enabled
按 QA 用例口吻写的权限与边界条件，改为「谁能做什么 / 不能做时怎么办」
重复叙述：同一规则在多个渠道或页面重复出现时，合并为一张表或改为交叉链接

代表性改动

页面（中文）	之前	之后
ai-sre/sessions	60.1 KB	27.4 KB（仅 API 集成需要的细节移到「通过 API 集成会话」一节，未删除）
monitors/dashboards	31.2 KB	16.3 KB
ai-sre/mcp	28.5 KB	18.7 KB
monitors/data-sources	36.5 KB	24.7 KB
monitors/explore	11.4 KB	7.3 KB
on-call/statuspage	15.1 KB	12.6 KB（准入规则按建议精简为 3 行，并链接到 pricing#订阅过期后会发生什么）
on-call/templates	卡片字段开关在 5 个渠道各写一遍	合并为一张渠道 × 开关对照表

链接

localhost / 127.0.0.1：逐一检查过，剩余的都是配置示例或 curl 示例，不是文档链接，无需修改。状态页里此前提到的 localhost:3000 链接在当前版本中已不存在。
12 处 https://docs.flashduty.com/... 绝对链接（多为已重定向的旧 /zh/flashduty/rum/... 路径；en/standard-alert 原来指向 /zh）已改为指向当前页面的相对链接。

检查：mint broken-links、mint validate、api_path_redirects.py --check、lint_openapi.py 均通过。另外核对了改名或删除的标题在站内是否还有锚点引用。

说明：本轮中途一次提交（1fe823af、5951a819、ef6ff2ca）误删了 3 个页面的几个小节标题和 1 个 Tip，已在 3dbe9b3 中恢复。集成类页面和 changelog 基本没有改动。

…into one table, merge pie rules into chart types, drop tooltip copy

…rge duplicate ranking lists into one table; error viewing — condense symbol panel

…allation list; drop duplicate tip and error copy

…se card, move close consequences to Close section, link templates, drop internal permission key

…pdate rules with technical details in an accordion, drop routes and internal fields

…current behavior, not a change note

debidong · 2026-10-09T10:20:43Z

第三批：RUM / AI SRE / On-call 精简 + 集成页模板修复

范围：9faa7cca..5377e3c5，共 14 个提交，中英文同步修改。

核心页面精简

14 个中文页面合计 258,795 → 237,359 字节，英文页面同步精简。

页面	zh 前 → 后	主要改动
rum/explorer/analytics	8998 → 6007	URL 参数合并为一张表；饼图规则并入图表类型表；删除 tooltip 原文
ai-sre/artifacts	15978 → 11453	列表/详情页的 UI 规格（300ms 防抖、路由、列定义、移动端隐藏项）压成要点；`publish_artifact` 的版本校验返回值移入「技术细节」折叠块；删除 `can_edit`、`team_id`、`pinned_at` 等内部字段
ai-sre/insight	13884 → 11956	删除 `INSIGHT_MIN_MSGS`、`entry_mix` 等内部名；三处重复的「只读」提醒合并为一处；下一步建议改为两类列表
ai-sre/skills	20709 → 18382	两段内置 Skill 长 Note 改为表格；「覆盖上传」改写为用户操作视角，API 参数缩成一段；作用域长段拆成要点
ai-sre/agents	27483 → 25870	删除 `TaskMaxConcurrentPerSession` 等常量和报错原文；删除重复的 Subagent Note；精简任务卡片说明
ai-sre/apps、im	21167 → 19331，18704 → 16983	连接步骤与授权说明改为用户视角，删除内部字段
on-call/incident/search-view-incident	23441 → 22102	标签深链改为「来源 / 标签 / 链接」表；删除内部上下文标签
on-call/incident/handle-update-incident	12542 → 12168	详见下方问题修复
platform/permission-design、on-call/analytics/insights、ai-sre/environments、RUM native/miniprogram	小幅精简	删除内部 ID、错误码和标语式标题；合并重复的排行列表

集成页模板级修复

58 个文件、116 处 <details><summary>Expand/展开</summary> 改为带描述标题的 Accordion：「查看专属/共享集成的配置步骤」「View dedicated/shared integration setup steps」。
原有的 "Show steps for…" 和「使用…集成」标题统一为同一措辞。
integration-docs 的 build/check 和 bundle 测试均通过。

问题修复

volcengine-rtc、ucloud-cloudwatch：「推送模式」一行误写成「企微告警」（从 WeCom 页复制过来的），已改正。
处理故障页：IM「关闭」卡片误写「点击卡片即可完成认领」。
「重新打开故障」一节中关于关闭后果的段落已移到「关闭故障」一节。
「详情请参考默认模板」补上了链接。
「时间线完整将完整记录」病句已改。
删除了 AiSreChatVisit 权限键名。
templates：飞书卡片「更多操作」原先写成更新说明（「已调整…不再…」），改为描述当前行为。

检查

以下检查均通过：

mint broken-links
mint validate
api_path_redirects --check
lint_openapi

待确认

rum/analytics/native 的稳定性指标一节写 Crash-free 率应 ≥99.5%，参考表却写 99%。未修改，需产品确认。

…oper/go-sdk with redirects; link error code list

…droid SDK, RUM performance)

…uplicating it

…n ids, voice/SMS region card walls as tables, merged pricing/License answers, separate 'not receiving notifications' section, fixed list numbering

…ordion ids, condensed overview cards

…de quoted third-party UI

…ring (一、/I.), merge empty 'In <tool>' headings with their push-config section, fix heading jumps; fix copy-pasted product names (UCloud page said Volcengine RTC, Volcengine event page said CM Metrics, Uptime Kunma); remove duplicated OceanBase status table

…numeric H2 prefixes

…upe permission notes, merge Slack error FAQs

…ered steps so lists no longer break

…s en↔zh; fix copy-pasted 'WeCom bot' text, stale section refs, empty Zabbix heading, zh punctuation and UI-term formatting

…nested tabs), SSO role/team sync (lead with overwrite semantics), engine-lost alert, RUM Explorer overview

…om forms, filter conditions, widgets

…e automations, /init consent, promote Skill format/built-ins to H2

…ondense performance diagnosis, turn non-link best-practice cards into lists

…s in SQL/log alert-rule pages; fix Zabbix parameter list

…ror reporting and distributed tracing pages

…hree repeated default-value warnings into one

…f a wall of paragraphs

debidong · 2026-10-09T10:59:13Z

可用性改造：全部轮次总结（第 1–4 轮）

按 Krug（《Don't Make Me Think》）和 Williams（亲密性、对齐、重复、对比）两条原则，对中英文文档做了同步改造。所有改动都只调整结构和措辞，没有新增或改动任何产品事实。

总量

整个 PR（相对 merge-base ca399e1b）：改动 972 个 .mdx 页面（中文 505 个，英文 467 个），共 8,404,512 → 8,194,066 字节（-2.5%），59 个提交。其中有 1 个提交来自另一个处理“你/您”的 agent，这个数字也包含了它。
第 4 轮（相对 5377e3c5）：改动 274 个页面（中文 139 个，英文 135 个），共 2,478,845 → 2,435,899 字节（-1.7%），19 个提交。
每次推送前都跑过以下检查：mint broken-links、mint validate、api_path_redirects --check、lint_openapi、integration-docs build/check，以及 node test。另外用脚本对比了改动前后的标题和锚点，结果为 0 处失效。

各轮内容

第 1 轮（审计和首批修复）：清理营销腔和重复内容，统一 UI 路径写法，修正错误链接。
第 2–3 轮（按判断精简）：处理长段落和 UI 文案的照搬，把卡片墙改成表格，Note/Warning 去重，统一中文标点。
第 4 轮（本轮）：
- IM 集成：钉钉的权限合并成一张表。企业微信、飞书、Slack、Teams 重新排序，“所需权限”和“AI SRE 控制项”提升为 H2，修复列表编号。
- 集成页（约 296 个告警源和变更集成）：
  - 去掉“一、/I.”式的章节编号；
  - 把空的“在 X 中”标题并入推送配置；
  - 修复 122 个页面中编号步骤内的图片、代码和表格缩进，避免列表断开；
  - 修正复制粘贴导致的产品名错误（UCloud 页写成了 Volcengine RTC 等）；
  - 修复 Zabbix 页的空标题和参数列表。
- On-call：
  - FAQ 按主题加跳转链接，并给每个折叠项加了稳定 id；
  - 故障列表/详情页重排了详情区的小节，内部事件码收进折叠块，复盘操作表改成一句话，AI 总结的版本提示调到正确位置；
  - 告警管理、自定义表单（批量并集表单）、过滤条件、状态页挂件都做了精简；
  - 模板、作战室页把“常见问题”移到页末。
- Monitors：
  - FAQ 的预览报错整理成“原因/处理”表；
  - 告警规则页去掉了 H2 的数字前缀；
  - SQL/日志类告警规则页的子项和 SQL 示例改为正确嵌套在步骤下。
- AI SRE：
  - Agent 页改成 A2A 在前、Subagent 在后；
  - 自动化、/init（安全约束从折叠块改为列表）、会话、产物都做了精简；
  - Skill 格式和内置 Skill 提升为 H2；
  - 落地页的计费内容改为链接到概述，不再重复。
- RUM：
  - data-query 页有两个重复的“AI 自然语言查询”H2，已合并为一个；
  - 性能诊断页精简；
  - Explorer 概览把标签页改成 H2；
  - iOS advanced-config 和 data-collection 的中英文对齐；
  - 不可点击的“最佳实践”卡片改成列表（OpenAPI 页同样处理）。
- 平台/开发者：
  - SSO 页改为先讲各协议，再讲角色/团队映射，三处重复的“默认值”警告合并为一处；
  - 角色/团队同步页先讲覆盖语义；
  - Go SDK 两页合并（已加重定向），各服务说明拆成独立的 H3。

推断措辞（建议复核）

钉钉权限用途说明句
Slack OAuth 引导语
Teams 的 Warning 合并
角色/团队同步页的精简：删掉了“角色删除在检查成员绑定之前即被拦截 / 强制删除仅解除成员绑定”这两条内部细节
自定义表单批量交互的改写
仅中文页面有的内容所做的英文翻译：iOS 页面、New Relic 排查、Web 凭证
早前几轮：handle-update-incident、volcengine/ucloud 推送模式、权限设计、insight 空状态、artifacts 摘要

待确认的产品事实（未改动）

Crash-free 99.5 还是 99
“同环比”
90% 阈值
On-call FAQ 中的版本名称
OceanBase 映射行
statuspage 路线图文案
标签增强 API 延迟：中文写 < 1s，英文写 < 500ms
企业微信的“智能机器人/API 模式”与“企微智能体/AI 助理”两套 AI SRE 配置可能重叠（目前两套都保留，并放在相邻位置）
iOS error.source 的取值列表中英文不一致

未做的事项及原因

ai-sre.mdx 与 ai-sre/overview 没有完全合并：受导航结构限制，只做了去重。
集成页只做了结构规范化：没有逐页重写成统一模板，以免引入未经验证的配置细节。
developer/cli、MCP Server 等参考页只轻改：这些是接口参考，内容本身就密集。
compliance/ 和生成的 OpenAPI 参考：按要求跳过。
en/rum/error-tracking/error-reporting.mdx：这是一个孤立页面（不在导航中，也没有中文版），保留原样，没有删除。

…ancement API latency < 500ms (zh+en)

…' AI SRE setups into one section matching the product UI (Workspace → Smart Robot → API mode, trusted-domain callback URL)

…of error-reporting/web, not in nav); redirect the bare error-reporting paths to the Web page

debidong · 2026-10-09T11:05:23Z

根据 Bowen 对待确认问题的答复所做的修改

数值统一（中英文同步）
- 无崩溃率：rum/analytics/native 指标表中原写“99% 以上”，改为 99.5% 以上，与同页概述保持一致。
- 标签增强 API 延迟建议：中文原写 < 1s，改为 < 500ms，与英文一致。
- 配置项“超时时间 1–3 秒，默认 2 秒”属于另一项设置，未改动。
90%：保持原样，没有添加任何出处说明。
企业微信的两套 AI SRE 配置：已合并为一节“配置 AI SRE 智能机器人”。
- 依据：fc-saas-web 的 pages/IntegrationCenter/detail/Source/IM/components/WecomBotSettings.tsx 中只有一套“智能机器人配置”，具体如下：
  - 字段为 settings.wecom.bot_token 和 bot_encoding_aes_key；
  - 回调 URL 是 https://<可信域名>/event/push/wecom/bot?integration_key=…；
  - 配置路径为“工作台 → 智能机器人 → API 模式创建 → API 配置”；
  - 只在 Wecom.tsx 的 mode === 'self'（企业自建应用）下显示。
- 原文档里的“企微智能体/AI 助理”一节描述的是同一个回调和同一组凭据，只是写成了“应用管理 → AI 助理”这条控制台没有的路径，因此判断为重复内容。
- 合并后保留的内容：两套凭据相互独立的警告、AI SRE 开通前提、需先校验可信域名、echostr 校验、支持的消息类型、拉取式流式说明，以及排查问题。
- 没有删除任何页面，所以不需要加重定向。
孤立页 en/rum/error-tracking/error-reporting.mdx：已删除。
- 功能仍然存在：flashcatcloud/browser-sdk 中有 packages/core/src/domain/error/trackRuntimeError.ts、packages/rum-react/src/domain/error/addReactError.ts 和 errorBoundary 相关代码。
- 该页是重复内容：它是 rum/error-tracking/error-reporting/web.mdx 的旧版英文稿，章节结构完全相同。新版中英文都已在导航中，所以没有再补一份中文页。
- 新增重定向：/{zh,en}/rum/error-tracking/error-reporting → …/error-reporting/web。已有的 erro-reporting/:slug* 拼写纠正重定向保留不变。
同环比：没有找到明确的产品依据，保持原样。

检查结果：mint broken-links、mint validate、api_path_redirects、lint_openapi、integration-docs 和 node test 全部通过，标题锚点失效数为 0。

debidong and others added 26 commits October 9, 2026 16:02

docs: remove horizontal rules placed directly under headings

9a120c7

A '---' right under a heading detaches the heading from its content (proximity) and was used inconsistently. 4302 rules in 744 zh/en pages.

docs: descriptive accordion titles and image alt text

ef35d18

- 152 '展开'/'Expand' accordions -> '查看专属/共享集成的配置步骤' (zh/en) - 129 timestamp/empty image alts -> page + section description

docs(escalation-rule): move 'copy rule' after the six configuration e…

0341bdf

…lements The page announces six elements and then interrupted them with a secondary operation; it now follows element 6 as its own section, linked from the intro.

chore: regenerate API path redirect ordering in docs.json

68240ad

docs: fix bold spans that CommonMark leaves as literal asterisks

4780f06

Merge origin/main into docs/usability-pass

bed0759

docs(statuspage): condense creation limits note, drop FAQ items that …

37c5742

…repeat core concepts

docs(platform): condense subscription-expiry, invite, join-restrictio…

95450db

…n and billing details to rules and outcomes

docs(monitors): rewrite dashboards page around tasks; drop routes, UI…

690cb61

… copy and implementation notes

docs(monitors): data sources — describe team authorization and switch…

5951a81

…es in user terms, drop API fields and error strings

docs(monitors): alert rule guide — keep rules and limits, drop UI cop…

1fe823a

…y, field names and form mechanics

docs(monitors): condense query workbench page

ef6ff2c

docs(ai-sre): overview — condense activation, closing and subscriptio…

299a351

…n-lapse rules

docs(ai-sre): sessions — rewrite around tasks; move queue-withdraw an…

6b726aa

…d stream-frame API details into an API section

docs(ai-sre): MCP — condense marketplace flow, auth and scope rules; …

7829bc2

…drop UI copy and internal API routes

docs(ai-sre): agents, skills, init, automations — drop UI copy, field…

20a67a3

… names and console routes; keep rules

docs(ai-sre): artifacts and knowledge — describe cards, sharing and w…

4d71bdc

…arnings in user terms

docs(on-call): war room, incident timeline, templates, copy dialogs, …

d5f6198

…integrations — replace UI walkthroughs with rules and outcomes

fix(monitors): restore headings and Tip lost in the condensing pass (…

3dbe9b3

…data sources, query workbench, alert rule guide)

docs: replace absolute docs.flashduty.com links with relative links t…

596a0bc

…o current pages

docs(monitors, rum, platform): CLS/SLS no-data rules, GitHub repo hin…

9faa7cc

…ts, integration permission notes — state the rule, drop UI copy and field names

debidong added 3 commits October 9, 2026 18:07

docs: RUM analytics, insights, environments, WeCom — fold URL values …

a596910

…into one table, merge pie rules into chart types, drop tooltip copy

docs(rum): native/mini program dashboards — drop tagline headings, me…

d71aa43

…rge duplicate ranking lists into one table; error viewing — condense symbol panel

docs(ai-sre): apps — condense GitHub/GitLab connection steps and inst…

21f7d0e

…allation list; drop duplicate tip and error copy

debidong added 3 commits October 9, 2026 18:17

docs(on-call): handle incidents — fix copy-paste 'acknowledge' on clo…

588bfcc

…se card, move close consequences to Close section, link templates, drop internal permission key

docs(ai-sre): artifacts — condense list/detail UI spec, user-facing u…

21bca86

…pdate rules with technical details in an accordion, drop routes and internal fields

docs(on-call): templates — describe Feishu card More Actions menu as …

5377e3c

…current behavior, not a change note

debidong added 19 commits October 9, 2026 18:24

docs(developer): merge duplicate OpenAPI Go SDK quickstart into devel…

4fef6c1

…oper/go-sdk with redirects; link error code list

docs(zh): use full-width punctuation in Chinese prose (go-sdk, iOS/An…

bb38d97

…droid SDK, RUM performance)

docs(ai-sre): landing page links to overview for billing instead of d…

5e5daca

…uplicating it

docs(on-call): restructure FAQ — topic jump links and stable accordio…

e40861e

…n ids, voice/SMS region card walls as tables, merged pricing/License answers, separate 'not receiving notifications' section, fixed list numbering

docs(monitors): FAQ — preview errors as a cause/fix table, stable acc…

9f6e8ce

…ordion ids, condensed overview cards

docs: fix product-name spellings (FlashDudy, FlashDuty, Oncall) outsi…

a1e87ea

…de quoted third-party UI

docs(im,monitors): single DingTalk permission table, fix lists; drop …

aee02ad

…numeric H2 prefixes

docs(im): restructure WeCom, Lark, Slack, Teams pages; fix lists, ded…

0213452

…upe permission notes, merge Slack error FAQs

docs(integrations): indent images, code blocks and tables inside numb…

582c283

…ered steps so lists no longer break

docs: sync iOS advanced-config/data-collection and Web SDK credential…

206979a

…s en↔zh; fix copy-pasted 'WeCom bot' text, stale section refs, empty Zabbix heading, zh punctuation and UI-term formatting

docs: condense AI SRE sessions/artifacts, label enhancement (flatten …

b0e7017

…nested tabs), SSO role/team sync (lead with overwrite semantics), engine-lost alert, RUM Explorer overview

docs(on-call): condense incident list/details, alert management, cust…

d4efdc6

…om forms, filter conditions, widgets

docs(ai-sre): reorder Agents page (A2A first, Subagent last), condens…

dce41db

…e automations, /init consent, promote Skill format/built-ins to H2

docs(rum,openapi): merge duplicate AI query sections in data-query, c…

2d32116

…ondense performance diagnosis, turn non-link best-practice cards into lists

docs(monitors): nest sub-bullets and SQL examples under numbered step…

b1e5f91

…s in SQL/log alert-rule pages; fix Zabbix parameter list

docs: move FAQ sections to the end of templates, war room, RUM web er…

f79e602

…ror reporting and distributed tracing pages

docs(platform): SSO — protocols first then role/team mapping; merge t…

6009cd8

…hree repeated default-value warnings into one

docs(developer): Go SDK — give each service note its own H3 instead o…

0eefd8e

…f a wall of paragraphs

debidong added 3 commits October 9, 2026 19:02

docs: align conflicting numbers — crash-free target ≥99.5%, label-enh…

fa7b491

…ancement API latency < 500ms (zh+en)

docs(im): WeCom — merge the duplicate 'Smart Robot' and 'WeCom AI Bot…

31670e3

…' AI SRE setups into one section matching the product UI (Workspace → Smart Robot → API mode, trusted-domain callback URL)

docs(rum): remove orphan en error-reporting page (outdated duplicate …

da2b333

…of error-reporting/web, not in nav); redirect the bare error-reporting paths to the Web page

debidong merged commit fc01291 into main Oct 10, 2026
2 checks passed

debidong deleted the docs/usability-pass branch October 10, 2026 02:48

Navigation Menu

Repository navigation

docs: 可用性修订（基于 Don't Make Me Think 与写给大家看的设计书） - #1033

docs: 可用性修订（基于 Don't Make Me Think 与写给大家看的设计书）#1033
debidong merged 62 commits into
mainfrom
docs/usability-pass

debidong commented Oct 9, 2026

Uh oh!

debidong commented Oct 9, 2026 •

edited

Loading

Uh oh!

debidong commented Oct 9, 2026

Uh oh!

debidong commented Oct 9, 2026

Uh oh!

debidong commented Oct 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

debidong commented Oct 9, 2026

背景

改动（按原则分组）

1. 页面要不言自明：去掉写给工程师看的实现细节

2. 首页清晰、任务优先

3. 导航：名称唯一、链接文字与目标一致、方便扫读

4. 维护信任：修正错误和前后矛盾的说法

5. 视觉层级：对比、亲密性、重复

6. 写作一致性

有意没有改的内容

待确认问题

验证

Uh oh!

debidong commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

第二轮精简（按页面逐段判断）

Uh oh!

debidong commented Oct 9, 2026

第三批：RUM / AI SRE / On-call 精简 + 集成页模板修复

核心页面精简

集成页模板级修复

问题修复

检查

待确认

Uh oh!

debidong commented Oct 9, 2026

可用性改造：全部轮次总结（第 1–4 轮）

总量

各轮内容

推断措辞（建议复核）

待确认的产品事实（未改动）

未做的事项及原因

Uh oh!

debidong commented Oct 9, 2026

根据 Bowen 对待确认问题的答复所做的修改

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

debidong commented Oct 9, 2026 •

edited

Loading