掌握 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例如dont、cant、wont、isnt、arent、doesnt、didnt、hasnt、havent、couldnt、wouldnt、shouldnt、its、were、youre、theyre、Im、lets、theres、thats、whats。命中即触发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 Names3.1 专有名词正确形式任何散文行若以错误形式使用下列术语触发warning正确错误形式DDoSDDOS、ddos、DdosZero Trustzero trust、Zero trustCAPTCHACaptcha、captchaInternet作为专有名词指全球网络时internetSSLsslTLStlsWAFwafCloudflare Workerscloudflare workers、CF WorkersWorkers AIworkers ai3.2 废弃术语替换表使用下表左侧的废弃行话同样触发warning不再使用应使用whitelistallowlistblacklistblocklistmaster / slaveprimary / replicaman-in-the-middleon-path attacksanity checkvalidate / smoke testout-of-the-boxdefaulton-premon-premisesenable/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移除。八、格式规则Formatting8.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 * 100010 分钟超时后该文件被降级为空结果并释放并发槽。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: alwayscore-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考