Cloudflare Docs 链接风格规范links.md规则解析与 Style-Guide 自动评审实现【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs导读本篇文章围绕 Cloudflare docs 文档仓库中 style-guide-review 技能包的链接规则参考文件 links.md 展开讲解在撰写 Cloudflare 开发者文档时内部链接与外部链接应当遵守的书写规范包括根路径、尾部斜杠、文件扩展名、链接文本措辞等要求。同时结合仓库中 style-guide 自动评审 AgentFlue 2.0的源码实现说明这些规则如何被机械地匹配到 PR 新增代码行上并输出可被结构化消费的 warning / suggestion 审查结果帮助文档贡献者在提交前规避常见的链接写法错误。一、规则文件背景style-guide-review 技能包.flue/.agents/skills/style-guide-review/是仓库内置的文档风格审查技能包其中SKILL.md 定义了整体任务作为“风格指南 linter”对 PR 中变更的 MDX 文档执行机械的模式匹配不进行宽泛的作文式审查manifest.json 声明了全部规则文件的加载条件reference/conditional/links.md 是链接规则的唯一权威来源。根据 manifest.json 的定义links.md属于load: conditional条件加载规则其加载触发条件是当补丁patch中包含 Markdown 链接、href、http、根相对路径或锚点时。也就是说只有在文档改动确实涉及链接书写时评审 Agent 才会加载并应用这套规则避免对无关改动做无意义检查。links.md本身仅约 20 行但每一条规则都对应着 Cloudflare 开发者文档的实际工程约束——它服务于 developers.cloudflare.com 这种根路径部署的静态站点链接写法直接关系到页面能否正确解析与跳转。二、链接硬性规则warning 级links.md的## Rules部分给出了五条必须遵守的硬性规则违反即触发warning级 finding。这些规则共同指向一个目标站点内链接必须使用以/开头的根相对路径且不带扩展名、带尾部斜杠、具有描述性文本。规则 1禁止使用完整域名 URL 指向站内页面如果链接指向站内页面internal page却写成完整 URLhttps://developers.cloudflare.com/...应改为根相对路径例如/workers/get-started/。原因在于完整 URL 会绕过站点的路由与重定向机制难以在预览环境、多域名镜像或本地构建中正确解析而根相对路径始终相对于站点根目录生效。规则 2禁止使用相对路径./、../文档内相对路径如./foo、../bar是warning级别的违规必须改用根相对路径。这与本任务文章生成所要求的“相对路径转换为仓库根起点”理念一致——但注意在 Cloudflare docs 的发布链路里链接最终解析的是站点根路径而非仓库根路径因此约定的是/product/page/形式。规则 3内部链接必须带尾部斜杠例如](/workers/get-started)缺少尾部斜杠应写成](/workers/get-started/)。尾部斜杠是 Cloudflare 文档路由的组成部分缺失会导致 404 或重定向跳转。规则 4内部链接不得包含文件扩展名](....mdx)、](....html)这类带扩展名的写法必须移除扩展名。文档源文件是 MDX但发布后的页面是目录路由.mdx不是对外 URL 的组成部分。规则 5链接文本必须具有描述性以下词汇不能作为链接文本here、this page、read more、click here、learn more、more information。链接文本应准确描述目标页面的内容既方便人类读者判断链接去向也有利于搜索引擎与辅助技术理解页面结构。三、措辞建议规则suggestion 级除上述硬性规则外links.md还定义了两条建议性措辞规则违反时触发suggestion改进建议非强制如果链接前使用了Learn more about...或To read more...句式建议改为refer to Page Title如果使用了refer the [Page] page或refer the [Page] documentation这类缺少介词to的写法建议改为refer to [Page]。这两条规则的目标是统一文档中的引用句式让“指向另一页”这一动作的表达保持一致。四、标准措辞模板Standard Phrasinglinks.md最后给出推荐的措辞范式作为文档写作时的直接参照场景推荐写法提供补充信息For more information, refer to Page Title.引导读者执行操作To do something, refer to Section Title.避免的写法See the [Page]→ 改为refer to [Page]避免的写法Learn more about [Page]→ 改为refer to [Page]注意links.md本身推荐的链接路径示例如/path/同样是根相对路径形式与硬性规则一脉相承。五、关联规则core-content 中的链接措辞链接规则并非孤立存在。在 style-guide-review 技能包中还有一份始终加载load: always的核心规则文件 core-content.md其中与链接相关的条款与links.md形成互补如果行文中出现see the [link]或see [link]建议替换为refer to [link]正文中的click一词建议替换为select针对 UI 元素操作连接词如e.g.、i.e.、etc.建议分别改写为for example、that is、and so on使文档更口语化、更贴近普通读者。这些规则与links.md一起构成对文档正文中“链接指向 引用措辞”两个维度的完整约束。六、源码实现规则如何在 PR 评审中生效规则文件的工程价值体现在其被 Agent 实际消费的方式上。在.flue/目录下整套 style-guide 自动评审由以下模块协作完成6.1 评审 Agentstyle-guide-file.tsstyle-guide-file.ts 是 per-file按文件的评审 Agent。关键点通过useSkill(styleGuideSkill)加载 SKILL.md并在 SKILL 指引下按需读取links.md等规则文件输入为initialData包含 PR 元数据、文件名、addedLines由可信代码预先解析的新增行及其行号与 head SHA唯一的返回通道是submit_style_guide工具由useTool定义其 schema 直接采用StyleGuideResultFromModelSchema使用useAgentFinish兜底若 Agent 未调用submit_style_guide就结束会追加一条 reminder 信号强制其提交确保审查结果不会丢失。6.2 结果模型style-guide-results.tsstyle-guide-results.ts 用 valibot 定义了模型返回的结构v.object({ severity: v.picklist([warning, suggestion]), path: v.string(), line: v.optional(v.number()), rule: v.string(), evidence: v.string(), suggestion: v.string(), })这与links.md中每条规则标注的→ **warning**/→ **suggestion**一一对应——规则文件标注严重级别模型按此级别产出 findings可信代码再通过assignFindingIds基于rule:path:evidence计算 SHA-256 派生稳定 IDSG-xxxxxxxxxxxx形式并刻意不把行号纳入哈希使部分修复后行号偏移时 ID 保持稳定便于 reconcile 流程对旧 finding 的追踪解决。6.3 调度驱动run-style-guide.tsrun-style-guide.ts 是 trusted-code 驱动对每个选中文件实例化一个独立 Agentinit(StyleGuideFile, { id: ${runId}:sg:${i} })以STYLE_GUIDE_CONCURRENCY 2的并发读取结果单文件超时STYLE_GUIDE_FILE_TIMEOUT_MS 10 * 60 * 1000时降级为空结果且不记入 reviewedFiles避免 reconcile 错误地消解未真正审查文件的旧 finding。6.4 文件选择与合并style-guide-files.tsstyle-guide-files.ts 定义了评审范围STYLE_GUIDE_REVIEWABLE_PATH_RE限定src/content/(docs|partials|changelog)/...mdx路径且要求文件有新增行和 patch按新增行数降序取前STYLE_GUIDE_MAX_FILES 20个文件mergeStyleGuideResults负责跨文件合并并按 ID 去重最终生成形如2 warning(s) and 1 suggestion(s) found across 3 file(s).的汇总摘要。6.5 新增行解析code-review-files.tslinks.md的规则只作用于“新增行”而新增行由 code-review-files.ts 中的parseAddedLines在可信 TypeScript 侧完成通过解析 unified diff 的 hunk 头 -old[,count] new[,count] 追踪新文件行号前缀行计入结果-删除行不推进计数\ No newline与 git 文件头均被跳过。这消除了模型自行解析 diff 格式的必要也让links.md的逐行匹配有了准确的行号依据。七、实战自查清单写文档时如何规避链接类 finding综合links.md与core-content.md可以沉淀为一份可直接对照的自查清单硬性检查warning站内链接一律使用/product/page/根相对路径杜绝https://developers.cloudflare.com/...完整 URL不使用./、../局部相对路径路径末尾补上/路径中不出现.mdx、.html等扩展名链接文本不用here、read more、click here等无描述性词汇。建议优化suggestion链接前不用Learn more about...、To read more...改用refer to Page Title不用refer the [Page] page改用refer to [Page]不用See the [Page]改用refer to [Page]优先套用标准句式For more information, refer to Page Title.或To do something, refer to Section Title.八、总结links.md虽然篇幅精炼却是 Cloudflare docs 链接书写规范的核心契约它明确了站内链接的路径形式根相对 尾部斜杠 无扩展名、链接文本的语义要求描述性而非占位词以及引用句式的统一范式。在仓库中这套规则被嵌入 style-guide-review 技能包经由 manifest.json 的条件加载机制在 PR 评审流水线中由 style-guide-file.ts Agent 机械匹配新增行最终以带warning/suggestion严重级别的结构化 findingsstyle-guide-results.ts提交给编排器合并去重。对于文档贡献者而言理解links.md的每一条规则就等于掌握了进入 Cloudflare docs 仓库的第一道链接质量关卡。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考