掌握 Cloudflare Docs 风格指南核心规则：从写作规范到自动化评审落地

掌握 Cloudflare Docs 风格指南核心规则：从写作规范到自动化评审落地

【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs

导读

本文是 Cloudflare 官方文档（cloudflare-docs）技术写作规范的核心内容解析。文档仓库通过一个名为style-guide-review的 Agent 技能，把写作规则固化为可机械执行的 lint 检查。读完本文，你将掌握 Cloudflare Docs 的核心写作规则（术语大小写、标题、格式、敏感时间内容等），并理解这些规则在仓库自动化评审流程中的源码实现与验证方式，可直接用于规范自己的技术文档写作或搭建类似的文档评审流水线。

一、规则来源与评审机制概览

本文的主体内容来自 .flue/.agents/skills/style-guide-review/reference/always/core-content.md。它被 reference/manifest.json 标记为load: "always"，即任何包含新增内容行的 MDX 文件被评审时，都必须加载这份规则文件。

整个评审由 Flue 框架驱动，调用链如下：

• 技能入口 .flue/.agents/skills/style-guide-review/SKILL.md：定义评审 Agent 的工作方式——只做机械的模式匹配，不进行宽泛的散文式评审，不逐行比对所有规则，只加载与补丁匹配的参考文件并扫描新增行。
• 按文件评审的 Agent .flue/agents/style-guide-file.ts：每次评审只针对一个MDX 文件的新增行（带新文件行号），规则要求把新增内容当作不可信数据，绝不标记未改动的行。
• 可信代码驱动 .flue/lib/run-style-guide.ts：负责解析补丁中的新增行、并发调度每个文件的 Agent 实例、为每条发现分配稳定 ID，并将单文件失败降级为空结果而不会中断整个池。

评审结果只有两个严重级别，见 .flue/lib/style-guide-results.ts 中的StyleGuideFindingFromModelSchema：

级别	含义	触发时机
warning	明确的规则违反、清晰度问题或正确性问题	明确违反规则时必须上报
suggestion	规则覆盖但非强制要求的改进	规则规定可选的改进项

二、写作风格规则（Writing Style）

规则 1 的文本是检查的重点：只评审 PR 中新增的行，逐行与规则比对，没有违反就静默跳过，不得在推理中叙述自己正在检查哪些规则，也不得对“规则不适用”进行推理。

2.1 标点与缩写禁忌

正文散文（prose）中禁止使用缩写形式（contraction），例如don't、can't、won't、isn't、aren't、doesn't、didn't、hasn't、haven't、couldn't、wouldn't、shouldn't、it's、we're、you're、they're、I'm、let's、there's、that's、what's。命中即触发warning，需展开为完整形式。例外：代码块（fenced code block）或反引号跨度（backtick span）内的缩写不在此列。

同样属于warning级别的还有：

• 正文出现please：删除。
• 正文出现方向性词汇（above、below、as shown above、as noted below）：改为用名称或链接直接引用，避免依赖“上文/下文”这种易失效的指代。

2.2 动词与指引用语（suggestion 级别）

以下为suggestion级别的改进项，不强制但鼓励：

• click→ 改用select（针对 UI 元素的操作）。
• navigate to→ 改用go to。
• see the [link]或see [link]→ 改用refer to [link]。
• e.g.→ 改用for example或重构句子。
• i.e.→ 改用that is或重构句子。
• etc.→ 改用完整列举或and so on。
• LLM 式填充语（Note that、It is worth noting that、It is important to note that、Please note that、Keep in mind that）→ 删掉填充语，直接陈述事实。
• 被动语态若用主动语态更清晰 → 改写为主动语态。
• 三个及以上项目用and或or连接时缺少牛津逗号（Oxford comma）→ 补上最后一个并列项前的逗号。
• 分号连接两个独立分句 → 拆成两个句子。

牛津逗号规则在 .flue/evals/style-guide.eval.ts 中有两个方向相反的评测用例，值得注意：

• 缺失时被标记：新增行Workers support bindings for KV, R2 and D1.（and前没有逗号）→ 断言oxfordFindings.length大于 0。
• 已存在时不误报：...shared with the wrong audience, exposed in client code or a screenshare, or need to be refreshed...（最后一个or前的逗号已在）→ 断言 oxford 相关发现数量为 0。

这说明规则强调先确认逗号确实缺失再标记，防止 lint 工具误报。

三、术语与产品名规范（Terminology and Product Names）

3.1 专有名词正确形式

任何散文行若以错误形式使用下列术语，触发warning：

正确	错误形式
DDoS	DDOS、ddos、Ddos
Zero Trust	zero trust、Zero trust
CAPTCHA	Captcha、captcha
Internet（作为专有名词指全球网络时）	internet
SSL	ssl
TLS	tls
WAF	waf
Cloudflare Workers	cloudflare workers、CF Workers
Workers AI	workers ai

3.2 废弃术语替换表

使用下表左侧的废弃行话同样触发warning：

不再使用	应使用
whitelist	allowlist
blacklist	blocklist
master / slave	primary / replica
man-in-the-middle	on-path attack
sanity check	validate / smoke test
out-of-the-box	default
on-prem	on-premises
enable/disable（用于开关/切换）	turn on / turn off

另有一条suggestion：若示例域名是看起来真实但非保留域名（如yourdomain.com、mysite.com），改用example.com、example.org或myappexample.com，避免文档中的示例指向真实站点。

四、营销语言规则（Marketing Language）

当散文出现以下短语时触发suggestion，要求用直接陈述功能事实的语言替换：Perfect for、Best for、Best-in-class、Empowers you to、Enables you to、Essential for、Critical for，以及Modern <noun>/Built for <noun>这类句式。例外同样是代码块或反引号跨度内部。

这与 Cloudflare 文档“技术事实优先”的定位一致：不写营销口号，只写产品实际做什么。

五、时间敏感内容规则（Time-Sensitive Content）

这部分规则只对src/content/changelog/之外的路径生效（changelog 内容天然带时间信息，故豁免）。例外包括：代码块、反引号跨度、frontmatter 字段（如reviewed:、compatibility_date:）、URL、示例数据。

命中的短语一律suggestion并要求删除，以保证文档“历久弥新”（timeless）：

• 时间性短语：Coming soon、recently added、newly available、now available、just released。
• 月份名（January至December）：删除或改写成不包含月份。
• 四位年份（如2024、2025）：删除或改写成不包含年份。

也就是说，仓库中的文档正文不应出现“这个功能刚发布”“2024 年新增”这类会随时间过时的表述。

六、文件位置规则（File Locations）

若向src/content/新增图片文件，触发warning：图片必须放在src/assets/images/{product}/目录下，而非src/content/。

这条规则与仓库的实际资源组织一致：仓库中的图片统一存放在 src/assets/images 下，按产品分目录组织（如workers、cloudflare-one、waf等），内容目录src/content/docs下只放 MDX 正文。图片路径规范在评测用例中也有体现：正确写法是~/assets/images/cloudflare-challenges/precursor-rules.png这类以~/assets/images/开头的路径，而使用/images/前缀的 Markdown 图片或被标记为 warning。

七、标题规则（Headings）

• 正文中若出现裸的#（H1）标题 →warning：页面的titlefrontmatter 已经渲染出 H1，正文标题应从##开始。评测用例用新增行# Getting Started with Workers验证了该规则会命中warning。
• 标题跳级（如 H2 直接跳到 H4）→warning：标题层级必须连续。
• 标题使用标题式大小写（多个非专有名词大写）→suggestion：改用句首式大小写，只大写首词和专有名词。
• 标题以.、?、!、:结尾 →warning：移除结尾标点。
• 标题以-ing动词开头（Installing、Configuring、Setting up）→warning：改用祈使形式（Install、Configure、Set up）。
• frontmatter 的title:或sidebar.label:含 emoji →warning：移除。

八、格式规则（Formatting）

8.1 粗体与等宽（Bold and Monospace）

• 正文把程序或工具名加粗（如**wrangler**、**npm**、**bun**）→warning：改用等宽wrangler、npm、bun。
• 正文对开关状态的enabled/disabled使用斜体 →warning：不要斜体化开关状态。
• 应使用等宽的项目包括：IP 地址、端口号、API 命令（GET、POST）、终端命令、文件路径、文件名、配置键、数据类型、环境变量名、HTTP 头、HTTP 状态码、作为输入/输出的 URL、DNS 记录类型。

8.2 列表（Lists）

• 用有序列表（numbered list）列举非顺序项 →warning：无序项改用项目符号。
• 用项目符号列表（bulleted list）描述顺序步骤 →warning：流程步骤改用有序列表。
• 项目符号列表少于三个条目 →suggestion：考虑改写为散文。

8.3 表格（Tables）

• 表格没有列头 →warning：所有列头必须有标签。
• 表格用句子片段引入 →warning：用完整句子加冒号结尾引入表格。

8.4 提示框（Admonitions）

• 合法类型只有:::note、:::caution、:::tip。
• 同一小节内同类型提示框超过一个 →suggestion：合并或融入散文。
• 提示框内容能融入前后文 →suggestion：优先融入散文，减少提示框堆砌。

8.5 数字（Numbers）

• 正文用单个数字（0–9）表示非测量、非指标、非 UI 值的数量 →suggestion：拼写为单词，例如three options而非3 options。
• 数字和单位之间缺少空格 →warning：补上空格，例如128 GB而非128GB。

九、规则如何落地为自动化评审

了解规则本身之后，值得看看它在仓库中的工程化实现，这有助于你评估这套 lint 逻辑的可靠性与扩展方式。

9.1 文件筛选与并发控制

.flue/lib/style-guide-files.ts 定义了评审范围：

• 只有匹配正则^src\/content\/(docs|partials|changelog)\/.+\.mdx$的 MDX 文件会被评审。
• 文件必须包含新增行（additions > 0）且有补丁（patch）。
• 最多评审STYLE_GUIDE_MAX_FILES = 20个文件，按新增行数从大到小排序后截取。
• 并发上限STYLE_GUIDE_CONCURRENCY = 2，单文件硬超时为STYLE_GUIDE_FILE_TIMEOUT_MS = 10 * 60 * 1000（10 分钟），超时后该文件被降级为空结果并释放并发槽。

9.2 结构化结果与稳定 ID

.flue/lib/style-guide-results.ts 定义了模型返回的结构：findings数组 + 一行summary。模型返回的发现不带 ID，由可信代码在之后分配：

• ID 格式为SG-加 SHA-256 摘要前 12 位十六进制。
• 哈希键为{rule}:{path}:{evidence.trim()}，刻意排除行号，这样当周边行因部分修复而移位时，ID 依然稳定，便于后续 reconciler 对历史发现做消解。

9.3 结果合并与去重

mergeStyleGuideResults按 ID 用Map去重，并汇总warning与suggestion的数量生成最终摘要，例如：

2 warning(s) and 1 suggestion(s) found across 3 file(s).

若某个文件评审失败（超时、模型错误、无结果），它会返回空结果，且不会出现在reviewedFiles中，这样 reconciler 不会误消解针对该文件的旧发现。

9.4 参考文件的选择策略

SKILL.md 要求先读 manifest.json 作为参考文件清单的事实来源，再按补丁内容按需加载：

• load: "always"：core-content.md（本文主体），任何含新增内容行的 MDX 文件都读。
• load: "conditional"：包含 Markdown 链接时读links.md；包含围栏代码块时读code-blocks.md；包含import语句或 JSX 组件标签时读imports.md；改动 frontmatter 时读frontmatter.md；包含图片语法时读images.md。
• load: "component"：只有补丁中出现对应组件标签（如<Tabs、<CURL、<Steps等）时才加载相应组件参考文件。

这种“按需加载、默认不读所有文件”的机制，控制了每次评审的提示词长度和推理成本。

9.5 行为约束与验收测试

SKILL.md 对评审 Agent 的行为做了严格约束：不得自创规则、不得标记未改动的行、不得对每条规则做“不适用”的确认、只在确定某行匹配某条规则时上报一条发现、默认不发现。useAgentFinish钩子还会强制要求调用submit_style_guide工具，否则追加提醒信号，确保结果被结构化记录（见 style-guide-file.ts）。

eval/style-guide.eval.ts 提供了可运行的验收基准（基于 vitest-evals），覆盖了大量边界情形：

• 内部链接使用完整 URL → 标记warning；根相对路径链接 → 不报 warning。
• 正文 H1 →warning。
• 原始<img>标签 //images/前缀图片 / 引用式未解析~/别名图片 → 均被标记；代码块内的图片、正确的~/assets/images/Markdown 图片 → 不误报。
• 牛津逗号缺失标记、已存在不误报。
• 通过深路径导入 barrel 导出的组件（如~/components/ui/tabs/Tabs.astro）→warning；页面专用包装组件（如~/components/BaseSchemaProperties.astro）→ 不误报。

这些用例验证了规则引擎在“该标记时不漏、不该标记时不误报”两个方向上的行为，是评估真实模型评审质量的关键手段。

十、如何利用这套规则

如果你在 cloudflare-docs 仓库中贡献文档，需要注意：

• 改动任何src/content/docs、src/content/partials、src/content/changelog下的 MDX 时，新增行都会经过上述风格评审，建议在提交前自查：正文无缩写、无please、无方向词、无 LLM 填充语；专有名词大小写正确；标题从##开始且用句首式大小写；图片走~/assets/images/{product}/路径。
• 规则只作用于新增行，不评审未改动的内容，因此旧内容的历史问题不会被误报。
• 若想了解某条规则的具体边界（链接、代码块、图片、组件、frontmatter），可分别查阅.flue/.agents/skills/style-guide-review/reference/下对应的conditional/与components/参考文件。

结语

Cloudflare Docs 的风格规则并不复杂，但覆盖了技术写作中最容易反复出错的高频点：缩写、专有名词、标题层级、列表与表格结构、时间敏感表述和营销语言。通过.flue中的 Agent 技能与可信代码管线，这些规则被固化为可重复、可测试、可降级的自动化评审，既保证了千篇一律的机械一致性，也为文档的长期可维护性提供了机制保障。对于任何计划为开发者文档建立质量闸门或 lint 流程的团队，core-content.md 及其配套实现都是一个值得直接借鉴的范本。

【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs