Cloudflare Docs 样式审查 SKILL 深度解析基于规则引擎的 MDX 文档自动 Linter 设计与实践【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs导读本篇文章围绕 Cloudflare 官方文档仓库cloudflare-docs内置的style-guide-review技能SKILL展开剖析它如何用 AI Agent 对 Pull Request 中新增的 MDX 文档行执行机械式风格审查并返回结构化审查结果。阅读本文后你将掌握该技能的文件结构、参考规则的选择机制、warning/suggestion两级严重度模型、结构化输出协议以及它在仓库中对应的 Agent 实现、调度驱动、结果合并与自动化评测全链路可以直接复用于其他以 MDX 文档为主的仓库。一、背景为什么需要一个样式审查 AgentCloudflare 官方文档以 MDX 编写正文位于src/content/docs/、src/content/partials/、src/content/changelog/动辄数千个文件风格一致性只能靠审查自动化来兜底。style-guide-review正是为此设计的它不是一个“泛泛而谈”的评审助手而是一个机械式规则匹配器style-guide linter——只针对 Patch 中新增的行与显式规则做精确比对命中即产出结构化 finding。它的定位在 SKILL.md 的 frontmatter 中写得很明确Review changed MDX/docs files in a pull request against the Cloudflare docs style guide and return structured findings.其价值在于把原本依赖人工或自由文本评审的风格问题变成可量化、可机器消费的结构化数据severity path line rule evidence suggestion从而可以被下游代码评审管线进一步合并、去重、稳定去重地追踪。二、SKILL.md 的核心工作准则整个技能的行为约束集中体现在几条“铁律”上它们决定了这个 linter 与普通 essay 式评审的本质区别只做机械模式匹配You are a style-guide linter. Your task is mechanical pattern matching against explicit rules.尽量减少推理禁止做宽泛的论文式评审也禁止逐行穷举所有规则——只加载与 Patch 匹配的参考规则扫描新增行命中即停。不叙述、不解释、不列举不允许在推理中枚举或总结已加载的规则不允许叙述“接下来要检查哪些规则”直接进入扫描无违规时静默跳过Default to no finding。禁止发明规则规则只能来自已加载的参考文件参考文件中不存在的规则不得产出 finding。只审新增行只审查 Prompt 提供的新增行每条带有准确的 new-file 行号已由可信代码从 Patch 中预提取忽略未改动行与删除行。结构化输出不写散文唯一的结果出口是调用submit_style_guide工具。这些约束的工程意图很明显控制 Agent 的上下文消耗与不确定性让模型在“明确命中/不确定”两种状态下做最小决策从而保证审查结果的可复现性与低误报率。三、数据来源与工具边界SKILL.md 严格界定了 Agent 可以接触的三类数据3.1 Diff 数据直接注入 PromptPull Request 元数据number、title、base、head、待审查文件以及新增行line: content对直接由 Prompt 提供没有可供读取的工作区也不允许 Agent 自行解析任何 diff 格式。3.2 完整文件上下文只读工具按需使用read_repo_file工具用于读取待审查文件的完整当前内容固定钉在 PR head SHA 上仅在需要判定“新增行是否位于围栏代码块 / JSX 组件内部”这类上下文歧义时使用。规则明确禁止用它在仓库里浏览其他文件也禁止对未改动行产出 finding。3.3 风格指南参考打包技能资源所有规则参考文件都是打包的技能资源通过read_skill_resource工具读取参考文件清单reference/manifest.json是参考文件名的唯一事实来源必须先读它。四、参考规则的选择机制这是该技能最具工程价值的部分规则不是一次性全部加载而是按需、按类别精确加载以避免污染上下文窗口。4.1 三类加载条件以 manifest.json 为事实来源加载条件分为三类类别目录触发条件alwaysreference/always/对任何包含新增内容行的 MDX 文件必然加载conditionalreference/conditional/Patch 命中 manifest 中when字段描述的触发器componentreference/components/Patch 包含某个组件标签或导入了组件名由 manifest 的componentNames字段匹配对应关系在 rule-authoring.md 中有明确说明always每次必读conditional按条件读component只在出现对应组件时读且默认不读取全部组件参考文件。4.2 条件规则的精确触发条件linksPatch 包含 Markdown 链接、href、http、根相对路径或锚点code-blocksPatch 包含围栏代码块importsPatch 包含import语句或 JSX 组件标签frontmatterPatch 修改了文件顶部的 frontmatter 字段imagesPatch 包含图片语法[ 是唯一一份每次必读的规则文件覆盖面最广写作风格代码块与反引号内为豁免区缩写词dont、cant、wont等 17 个常见缩写→warning需移除please→warning移除方向词above、below、as shown above等→warning改用直接名称或链接引用click→suggestion改用selectnavigate to→suggestion改用go tosee the [link]→suggestion改用refer to [link]e.g./i.e./etc.→suggestion分别替换为for example、that is、完整列举或and so onLLM 式填充短语Note that、It is worth noting that、Keep in mind that等→suggestion直接陈述事实可改用主动语态的被动语态 →suggestion三项以上列举时最后一个连接词前缺少牛津逗号 →suggestion并附有误报豁免示例如exposed in client code or a screenshare, or need to be refreshed这种已带逗号的情况不得标记用分号连接两个独立分句 →suggestion拆成两句。术语与产品名错误写法一律warning包括DDoS/Zero Trust/CAPTCHA/Internet/SSL/TLS/WAF/Cloudflare Workers/Workers AI的各类大小写错误以及已废弃的措辞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。营销语言Perfect for、Best-in-class、Empowers you to、Modern noun、Built for noun等短语 →suggestion替换为直接描述功能的事实陈述。时效性内容仅针对src/content/changelog/之外的路径Coming soon、recently added、月份名称、四位年份 →suggestion文档需保持“永恒可读”frontmatter 字段如reviewed:、compatibility_date:与 URL 豁免。文件位置图片若被添加到src/content/→warning必须放到src/assets/images/{product}/。标题规则正文出现#一级标题 →warning页面titlefrontmatter 已渲染 H1应改为##标题跳级 →warning标题大小写 →suggestion统一 sentence case标题结尾带.、?、!、:→warning标题以-ing动词开头Installing等→warning改用祈使式Installfrontmatter 中title:/sidebar.label:含 emoji →warning。格式规则程序或工具名**wrangler**、**npm**→warning改用等宽字体enabled/disabled开关状态不得斜体 →warningIP 地址、端口、API 命令、终端命令、文件路径、配置键、数据类型、环境变量名、HTTP 头、HTTP 状态码、DNS 记录类型等必须用等宽字体有序列表用于非顺序项 →warning改用无序列表无序列表用于步骤流程 →warning改用有序列表少于三项的列表 →suggestion改为散文表格必须带列头、表前必须用完整句引导admonition 仅限:::note、:::caution、:::tip同一节同类 admonition 超一个 →suggestion合并正文单数字 →suggestion拼写完整three options数字与单位间缺空格128GB→warning。5.2 链接规则links.md 的核心约束是内部链接一律使用根相对路径内部链接写完整https://developers.cloudflare.com/...URL →warning改用/workers/get-started/使用相对路径./、../→warning缺少结尾斜杠 →warning带文件扩展名.mdx、.html→warning链接文字是here、this page、read more、click here等 →warning改用描述性文字标准措辞推荐For more information, refer to Page Title.。5.3 代码块规则code-blocks.md 要求围栏必须带语言标识符无合适语言时用txt语言名必须小写json而非JSON→warning命令行不得带$、%、PS前缀复制按钮会原样复制→warningLinux/macOS 用sh/bashWindows PowerShell 用powershellcmd.exe用txt行尾两个及以上空格 →suggestion改用br/命令与输出应分成两个块输出单独用txt块 →suggestion。此外还规定了组件替代建议在src/content/docs/与src/content/partials/下的 MDX 文件中裸ts/tsx/js/jsx围栏应改用TypeScriptExample含 Wrangler 配置键的toml/jsonc块应改用WranglerConfig纯包管理器安装命令的sh/bash块应改用PackageManagers。5.4 导入规则imports.md 规定可复用组件必须加入~/components桶导出即src/components.ts并从~/components导入页面专属包装组件如~/components/BaseSchemaProperties.astro允许深路径导入且不应被标记SubtractIPCalculator是例外其直接路径是 legacy shim新内容不应使用。5.5 Frontmatter 规则frontmatter.md 规定设置pcx_content_type后必须存在description:字段且pcx_content_type的值必须在白名单内changelog、concept、configuration、get-started、how-to、reference、tutorial等 21 个枚举值sidebar.label:含 emoji →warning。值得注意的是它明确排除了对reviewed:日期过期或缺失的标记。5.6 图片规则images.md 是仓库中配套测试最多的规则文件要点包括正文中裸img标签 →warning改用Alt text围栏代码块、JSX 组件属性、HTML/JSX 应用代码示例内为豁免区/images/...绝对路径或public/images/...→warning图片必须存放于src/assets/images/{product}/并通过~/assets/images/{product}/...引用可获得 Astro 资源优化、响应式变体与缓存破坏public/仅用于需要稳定静态 URL 的资源空 alt 文本 →suggestion补充描述性 alt引用式图片链接![Alt text][n]指向[n]: ~/assets/images/...→warning必须转为内联语法因为 Astro 资源管线只对内联语法解析~/assets/images/别名引用式定义会渲染为失效的页相对 URL。六、严重级别与结构化输出协议6.1 两级严重度warning明确的规则违规、清晰性问题或正确性问题suggestion规则覆盖但非强制要求的改进项。6.2 submit_style_guide 结果结构SKILL.md 明确给出了唯一的结果出口。模型必须以 JSON 形式调用submit_style_guide{ findings: [ { severity: warning, path: src/content/docs/example.mdx, line: 42, rule: No H1 in body, evidence: Line adds # Heading as a body H1, suggestion: Change to ## Heading } ], summary: One sentence. }协议细节findings允许为空数组line为可选字段模型不得输出idID 由下游可信代码分配evidence与suggestion保持简洁summary必须是一句话。七、仓库中的实现从 SKILL 到可运行的 AgentSKILL.md 只是行为契约真正把它变成可运行审查管线的是.flue/目录下的 Flue 2.0 实现。7.1 每文件一个 Agent 实例style-guide-file.ts 定义了style-guide-file这个 per-file 审查 Agent其装配方式与 SKILL.md 一一对应模型固定为cloudflare/cf/deepseek-ai/deepseek-v4-flash-0731L44通过useSkill(styleGuideSkill)加载本 SKILL.md并通过useBotRole()注入机器人角色见 bot-role.ts通过makeReadRepoFileTool(getGitHubToken, input.headSha)注册钉在 PR head SHA 上的read_repo_file工具通过useDataWriter(STYLE_GUIDE_FILE_DATA, { schema: StyleGuideResultFromModelSchema })声明结构化输出数据槽数据键为style_guide_file通过defineTool注册submit_style_guide工具运行函数把数据写入 data writeruseAgentFinish强制收尾如果模型结束对话前没有成功调用submit_style_guide就追加一条 reminder 信号提示“未记录任何结果请立即调用”buildPromptL61-L81按#PR号 标题 (base, head)、文件路径、带行号的新增行 JSON 序列化、以及“完成后必须恰好调用一次 submit_style_guide”的指令拼装提示词并明确要求把新增行内容当作不可信数据处理。7.2 可信代码调度驱动run-style-guide.ts 是可信代码侧的 fan-out 驱动器体现了“一个文件一个 Agent 实例Durable Object”的 2.0 架构用parseAddedLines(file.patch)来自 code-review-files.ts在可信代码中预解析新增行作为initialData投递对每个文件以${runId}:sg:${index}作为实例 ID 分发独立的 Agent读取结果时用AbortSignal.timeout(fileTimeoutMs)做硬超时单文件失败超时、模型错误、无结果降级为空结果且故意不写入reviewedFiles——这样协调器不会因为“实际没审到”而错误地消解既有 finding全部结果经mergeStyleGuideResults合并后返回。7.3 文件选择与结果合并style-guide-files.ts 把文件选择与合并抽成纯函数以便单元测试可审查路径正则/^src\/content\/(docs|partials|changelog)\/.\.mdx$/只审文档/片段/变更日志三类 MDXselectStyleGuideFiles过滤出有新增且带 patch 的文件按新增行数从大到小排序后截取前 20 个STYLE_GUIDE_MAX_FILESfan-out 并发上限为 2STYLE_GUIDE_CONCURRENCY单文件硬超时为 10 分钟STYLE_GUIDE_FILE_TIMEOUT_MSmergeStyleGuideResults按 finding ID 跨文件去重并生成N warning(s) and M suggestion(s) found across K file(s).或No style-guide issues found.的摘要。7.4 稳定 ID 分配style-guide-results.ts 定义了模型输出模式与公共类型并实现了 ID 分配assignFindingIds对rule:path:evidence.trim()计算 SHA-256取前 12 位十六进制拼成SG-xxx形式行号被排除在哈希之外这样局部修复导致周围行号漂移时 ID 依然稳定便于下游追踪与消解。八、规则如何编写与扩展rule-authoring.md 是面向维护者与“写规则”的 Agent 的指南与运行时审查无关也不会出现在 manifest 中。它给出了完整的规则工程规范规则格式每条规则是显式的 if/then 检查形如- If condition on added lines → **severity**: what to do.好规则的五个原则具体——条件必须可被机械模式匹配直接检查避免“请考虑提升清晰度”这类模糊指导包含误报豁免——规则可能误伤代码块、JSX 组件属性、应用代码示例时必须显式写出例外不与 CI 重复——新增规则前先确认仓库 CIbuild、typecheck、lint、链接校验、schema 校验没有覆盖面向新增行——规则应对着新增行本身编写必要时才用read_repo_file查上下文提供示例——正反例帮助模型精确匹配但要保持精简以节省上下文空间。接入新规则的完整流程在reference/对应子目录创建或编辑规则.md文件向reference/manifest.json添加id、file、load、when组件规则另加componentNames条目在 SKILL.md 的 reference selection 一节补充条件规则的加载条件至少添加两个 eval 用例——一个触发该规则的违规用例一个不触发的干净反例若该规则代表公开的文档规范同步更新.agents/references/style-guide.md。九、自动化评测用 eval 保证规则可验证style-guide.eval.ts 基于vitest-evals的describeEval与仓库自带的 Flue harness 运行验证了 SKILL 的绝大多数核心行为链接完整 URL 的内部链接被标记为warning规则名含 link/url/root-relative干净的根相对链接不产出 warning牛津逗号已带序列逗号的句子...in client code or a screenshare, or need to be refreshed不触发缺失序列逗号的Workers support bindings for KV, R2 and D1.必触发标题正文裸# Getting Started with Workers被标记warning图片裸img标签、/images/...路径、引用式图片链接均被标记而围栏代码块内的img、引用式语法、以及正确的[](https://link.gitcode.com/i/4ff4d2ec7e49b13d3a2ed4027d183bd5)内联语法均不产出 warning导入桶导出的组件走深路径导入import Tabs from ~/components/ui/tabs/Tabs.astro被标记warning页面专属包装组件BaseSchemaProperties深路径导入不被标记。每个用例还断言toolCalls(result)中包含submit_style_guide调用验证了“唯一结果出口”这条铁律。测试数据中固定的 PR 元数据#999baseproductionheadfix-link与 mock 的read_repo_file按 SHA 返回合成文件内容保证了评测的确定性。十、适用前提与限制该技能仅面向src/content/docs、src/content/partials、src/content/changelog下的 MDX 文件且单次最多审查 20 个文件按新增行数从大到小选取审查对象只包含 Patch 中新增的行未改动行、删除行、以及reviewed:日期是否过期均不在审查范围内规则文件必须存在于 manifest 中才会被加载组件参考文件默认不读取模型必须通过submit_style_guide恰好一次地提交结果否则useAgentFinish会追加提醒单个文件失败不会中断整个池子而是降级为空结果运行规则评测需要启动 Flue 开发服务器后另开终端执行pnpm run flue:dev与pnpm --dir .flue run evals见 rule-authoring.md 的 Evaluating rules 一节。总结style-guide-review是一个将“文档风格审查”彻底工程化的范例SKILL.md 定义机械式行为契约manifest 三分类参考规则实现按需加载以节省上下文warning/suggestion两级严重度与固定 JSON 结构让结果可以被可信代码合并、去重并分配稳定 ID而 eval 套件保证了每条规则的“有据可依、有测可验”。对于任何希望用 Agent 自动维护 MDX/文档风格一致性的团队这套“技能文件 参考清单 纯函数驱动 评测闭环”的组合都具备直接的迁移参考价值。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Docs 样式审查 SKILL 深度解析：基于规则引擎的 MDX 文档自动 Linter 设计与实践
Cloudflare Docs 样式审查 SKILL 深度解析基于规则引擎的 MDX 文档自动 Linter 设计与实践【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs导读本篇文章围绕 Cloudflare 官方文档仓库cloudflare-docs内置的style-guide-review技能SKILL展开剖析它如何用 AI Agent 对 Pull Request 中新增的 MDX 文档行执行机械式风格审查并返回结构化审查结果。阅读本文后你将掌握该技能的文件结构、参考规则的选择机制、warning/suggestion两级严重度模型、结构化输出协议以及它在仓库中对应的 Agent 实现、调度驱动、结果合并与自动化评测全链路可以直接复用于其他以 MDX 文档为主的仓库。一、背景为什么需要一个样式审查 AgentCloudflare 官方文档以 MDX 编写正文位于src/content/docs/、src/content/partials/、src/content/changelog/动辄数千个文件风格一致性只能靠审查自动化来兜底。style-guide-review正是为此设计的它不是一个“泛泛而谈”的评审助手而是一个机械式规则匹配器style-guide linter——只针对 Patch 中新增的行与显式规则做精确比对命中即产出结构化 finding。它的定位在 SKILL.md 的 frontmatter 中写得很明确Review changed MDX/docs files in a pull request against the Cloudflare docs style guide and return structured findings.其价值在于把原本依赖人工或自由文本评审的风格问题变成可量化、可机器消费的结构化数据severity path line rule evidence suggestion从而可以被下游代码评审管线进一步合并、去重、稳定去重地追踪。二、SKILL.md 的核心工作准则整个技能的行为约束集中体现在几条“铁律”上它们决定了这个 linter 与普通 essay 式评审的本质区别只做机械模式匹配You are a style-guide linter. Your task is mechanical pattern matching against explicit rules.尽量减少推理禁止做宽泛的论文式评审也禁止逐行穷举所有规则——只加载与 Patch 匹配的参考规则扫描新增行命中即停。不叙述、不解释、不列举不允许在推理中枚举或总结已加载的规则不允许叙述“接下来要检查哪些规则”直接进入扫描无违规时静默跳过Default to no finding。禁止发明规则规则只能来自已加载的参考文件参考文件中不存在的规则不得产出 finding。只审新增行只审查 Prompt 提供的新增行每条带有准确的 new-file 行号已由可信代码从 Patch 中预提取忽略未改动行与删除行。结构化输出不写散文唯一的结果出口是调用submit_style_guide工具。这些约束的工程意图很明显控制 Agent 的上下文消耗与不确定性让模型在“明确命中/不确定”两种状态下做最小决策从而保证审查结果的可复现性与低误报率。三、数据来源与工具边界SKILL.md 严格界定了 Agent 可以接触的三类数据3.1 Diff 数据直接注入 PromptPull Request 元数据number、title、base、head、待审查文件以及新增行line: content对直接由 Prompt 提供没有可供读取的工作区也不允许 Agent 自行解析任何 diff 格式。3.2 完整文件上下文只读工具按需使用read_repo_file工具用于读取待审查文件的完整当前内容固定钉在 PR head SHA 上仅在需要判定“新增行是否位于围栏代码块 / JSX 组件内部”这类上下文歧义时使用。规则明确禁止用它在仓库里浏览其他文件也禁止对未改动行产出 finding。3.3 风格指南参考打包技能资源所有规则参考文件都是打包的技能资源通过read_skill_resource工具读取参考文件清单reference/manifest.json是参考文件名的唯一事实来源必须先读它。四、参考规则的选择机制这是该技能最具工程价值的部分规则不是一次性全部加载而是按需、按类别精确加载以避免污染上下文窗口。4.1 三类加载条件以 manifest.json 为事实来源加载条件分为三类类别目录触发条件alwaysreference/always/对任何包含新增内容行的 MDX 文件必然加载conditionalreference/conditional/Patch 命中 manifest 中when字段描述的触发器componentreference/components/Patch 包含某个组件标签或导入了组件名由 manifest 的componentNames字段匹配对应关系在 rule-authoring.md 中有明确说明always每次必读conditional按条件读component只在出现对应组件时读且默认不读取全部组件参考文件。4.2 条件规则的精确触发条件linksPatch 包含 Markdown 链接、href、http、根相对路径或锚点code-blocksPatch 包含围栏代码块importsPatch 包含import语句或 JSX 组件标签frontmatterPatch 修改了文件顶部的 frontmatter 字段imagesPatch 包含图片语法[ 是唯一一份每次必读的规则文件覆盖面最广写作风格代码块与反引号内为豁免区缩写词dont、cant、wont等 17 个常见缩写→warning需移除please→warning移除方向词above、below、as shown above等→warning改用直接名称或链接引用click→suggestion改用selectnavigate to→suggestion改用go tosee the [link]→suggestion改用refer to [link]e.g./i.e./etc.→suggestion分别替换为for example、that is、完整列举或and so onLLM 式填充短语Note that、It is worth noting that、Keep in mind that等→suggestion直接陈述事实可改用主动语态的被动语态 →suggestion三项以上列举时最后一个连接词前缺少牛津逗号 →suggestion并附有误报豁免示例如exposed in client code or a screenshare, or need to be refreshed这种已带逗号的情况不得标记用分号连接两个独立分句 →suggestion拆成两句。术语与产品名错误写法一律warning包括DDoS/Zero Trust/CAPTCHA/Internet/SSL/TLS/WAF/Cloudflare Workers/Workers AI的各类大小写错误以及已废弃的措辞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。营销语言Perfect for、Best-in-class、Empowers you to、Modern noun、Built for noun等短语 →suggestion替换为直接描述功能的事实陈述。时效性内容仅针对src/content/changelog/之外的路径Coming soon、recently added、月份名称、四位年份 →suggestion文档需保持“永恒可读”frontmatter 字段如reviewed:、compatibility_date:与 URL 豁免。文件位置图片若被添加到src/content/→warning必须放到src/assets/images/{product}/。标题规则正文出现#一级标题 →warning页面titlefrontmatter 已渲染 H1应改为##标题跳级 →warning标题大小写 →suggestion统一 sentence case标题结尾带.、?、!、:→warning标题以-ing动词开头Installing等→warning改用祈使式Installfrontmatter 中title:/sidebar.label:含 emoji →warning。格式规则程序或工具名**wrangler**、**npm**→warning改用等宽字体enabled/disabled开关状态不得斜体 →warningIP 地址、端口、API 命令、终端命令、文件路径、配置键、数据类型、环境变量名、HTTP 头、HTTP 状态码、DNS 记录类型等必须用等宽字体有序列表用于非顺序项 →warning改用无序列表无序列表用于步骤流程 →warning改用有序列表少于三项的列表 →suggestion改为散文表格必须带列头、表前必须用完整句引导admonition 仅限:::note、:::caution、:::tip同一节同类 admonition 超一个 →suggestion合并正文单数字 →suggestion拼写完整three options数字与单位间缺空格128GB→warning。5.2 链接规则links.md 的核心约束是内部链接一律使用根相对路径内部链接写完整https://developers.cloudflare.com/...URL →warning改用/workers/get-started/使用相对路径./、../→warning缺少结尾斜杠 →warning带文件扩展名.mdx、.html→warning链接文字是here、this page、read more、click here等 →warning改用描述性文字标准措辞推荐For more information, refer to Page Title.。5.3 代码块规则code-blocks.md 要求围栏必须带语言标识符无合适语言时用txt语言名必须小写json而非JSON→warning命令行不得带$、%、PS前缀复制按钮会原样复制→warningLinux/macOS 用sh/bashWindows PowerShell 用powershellcmd.exe用txt行尾两个及以上空格 →suggestion改用br/命令与输出应分成两个块输出单独用txt块 →suggestion。此外还规定了组件替代建议在src/content/docs/与src/content/partials/下的 MDX 文件中裸ts/tsx/js/jsx围栏应改用TypeScriptExample含 Wrangler 配置键的toml/jsonc块应改用WranglerConfig纯包管理器安装命令的sh/bash块应改用PackageManagers。5.4 导入规则imports.md 规定可复用组件必须加入~/components桶导出即src/components.ts并从~/components导入页面专属包装组件如~/components/BaseSchemaProperties.astro允许深路径导入且不应被标记SubtractIPCalculator是例外其直接路径是 legacy shim新内容不应使用。5.5 Frontmatter 规则frontmatter.md 规定设置pcx_content_type后必须存在description:字段且pcx_content_type的值必须在白名单内changelog、concept、configuration、get-started、how-to、reference、tutorial等 21 个枚举值sidebar.label:含 emoji →warning。值得注意的是它明确排除了对reviewed:日期过期或缺失的标记。5.6 图片规则images.md 是仓库中配套测试最多的规则文件要点包括正文中裸img标签 →warning改用Alt text围栏代码块、JSX 组件属性、HTML/JSX 应用代码示例内为豁免区/images/...绝对路径或public/images/...→warning图片必须存放于src/assets/images/{product}/并通过~/assets/images/{product}/...引用可获得 Astro 资源优化、响应式变体与缓存破坏public/仅用于需要稳定静态 URL 的资源空 alt 文本 →suggestion补充描述性 alt引用式图片链接![Alt text][n]指向[n]: ~/assets/images/...→warning必须转为内联语法因为 Astro 资源管线只对内联语法解析~/assets/images/别名引用式定义会渲染为失效的页相对 URL。六、严重级别与结构化输出协议6.1 两级严重度warning明确的规则违规、清晰性问题或正确性问题suggestion规则覆盖但非强制要求的改进项。6.2 submit_style_guide 结果结构SKILL.md 明确给出了唯一的结果出口。模型必须以 JSON 形式调用submit_style_guide{ findings: [ { severity: warning, path: src/content/docs/example.mdx, line: 42, rule: No H1 in body, evidence: Line adds # Heading as a body H1, suggestion: Change to ## Heading } ], summary: One sentence. }协议细节findings允许为空数组line为可选字段模型不得输出idID 由下游可信代码分配evidence与suggestion保持简洁summary必须是一句话。七、仓库中的实现从 SKILL 到可运行的 AgentSKILL.md 只是行为契约真正把它变成可运行审查管线的是.flue/目录下的 Flue 2.0 实现。7.1 每文件一个 Agent 实例style-guide-file.ts 定义了style-guide-file这个 per-file 审查 Agent其装配方式与 SKILL.md 一一对应模型固定为cloudflare/cf/deepseek-ai/deepseek-v4-flash-0731L44通过useSkill(styleGuideSkill)加载本 SKILL.md并通过useBotRole()注入机器人角色见 bot-role.ts通过makeReadRepoFileTool(getGitHubToken, input.headSha)注册钉在 PR head SHA 上的read_repo_file工具通过useDataWriter(STYLE_GUIDE_FILE_DATA, { schema: StyleGuideResultFromModelSchema })声明结构化输出数据槽数据键为style_guide_file通过defineTool注册submit_style_guide工具运行函数把数据写入 data writeruseAgentFinish强制收尾如果模型结束对话前没有成功调用submit_style_guide就追加一条 reminder 信号提示“未记录任何结果请立即调用”buildPromptL61-L81按#PR号 标题 (base, head)、文件路径、带行号的新增行 JSON 序列化、以及“完成后必须恰好调用一次 submit_style_guide”的指令拼装提示词并明确要求把新增行内容当作不可信数据处理。7.2 可信代码调度驱动run-style-guide.ts 是可信代码侧的 fan-out 驱动器体现了“一个文件一个 Agent 实例Durable Object”的 2.0 架构用parseAddedLines(file.patch)来自 code-review-files.ts在可信代码中预解析新增行作为initialData投递对每个文件以${runId}:sg:${index}作为实例 ID 分发独立的 Agent读取结果时用AbortSignal.timeout(fileTimeoutMs)做硬超时单文件失败超时、模型错误、无结果降级为空结果且故意不写入reviewedFiles——这样协调器不会因为“实际没审到”而错误地消解既有 finding全部结果经mergeStyleGuideResults合并后返回。7.3 文件选择与结果合并style-guide-files.ts 把文件选择与合并抽成纯函数以便单元测试可审查路径正则/^src\/content\/(docs|partials|changelog)\/.\.mdx$/只审文档/片段/变更日志三类 MDXselectStyleGuideFiles过滤出有新增且带 patch 的文件按新增行数从大到小排序后截取前 20 个STYLE_GUIDE_MAX_FILESfan-out 并发上限为 2STYLE_GUIDE_CONCURRENCY单文件硬超时为 10 分钟STYLE_GUIDE_FILE_TIMEOUT_MSmergeStyleGuideResults按 finding ID 跨文件去重并生成N warning(s) and M suggestion(s) found across K file(s).或No style-guide issues found.的摘要。7.4 稳定 ID 分配style-guide-results.ts 定义了模型输出模式与公共类型并实现了 ID 分配assignFindingIds对rule:path:evidence.trim()计算 SHA-256取前 12 位十六进制拼成SG-xxx形式行号被排除在哈希之外这样局部修复导致周围行号漂移时 ID 依然稳定便于下游追踪与消解。八、规则如何编写与扩展rule-authoring.md 是面向维护者与“写规则”的 Agent 的指南与运行时审查无关也不会出现在 manifest 中。它给出了完整的规则工程规范规则格式每条规则是显式的 if/then 检查形如- If condition on added lines → **severity**: what to do.好规则的五个原则具体——条件必须可被机械模式匹配直接检查避免“请考虑提升清晰度”这类模糊指导包含误报豁免——规则可能误伤代码块、JSX 组件属性、应用代码示例时必须显式写出例外不与 CI 重复——新增规则前先确认仓库 CIbuild、typecheck、lint、链接校验、schema 校验没有覆盖面向新增行——规则应对着新增行本身编写必要时才用read_repo_file查上下文提供示例——正反例帮助模型精确匹配但要保持精简以节省上下文空间。接入新规则的完整流程在reference/对应子目录创建或编辑规则.md文件向reference/manifest.json添加id、file、load、when组件规则另加componentNames条目在 SKILL.md 的 reference selection 一节补充条件规则的加载条件至少添加两个 eval 用例——一个触发该规则的违规用例一个不触发的干净反例若该规则代表公开的文档规范同步更新.agents/references/style-guide.md。九、自动化评测用 eval 保证规则可验证style-guide.eval.ts 基于vitest-evals的describeEval与仓库自带的 Flue harness 运行验证了 SKILL 的绝大多数核心行为链接完整 URL 的内部链接被标记为warning规则名含 link/url/root-relative干净的根相对链接不产出 warning牛津逗号已带序列逗号的句子...in client code or a screenshare, or need to be refreshed不触发缺失序列逗号的Workers support bindings for KV, R2 and D1.必触发标题正文裸# Getting Started with Workers被标记warning图片裸img标签、/images/...路径、引用式图片链接均被标记而围栏代码块内的img、引用式语法、以及正确的[](https://link.gitcode.com/i/4ff4d2ec7e49b13d3a2ed4027d183bd5)内联语法均不产出 warning导入桶导出的组件走深路径导入import Tabs from ~/components/ui/tabs/Tabs.astro被标记warning页面专属包装组件BaseSchemaProperties深路径导入不被标记。每个用例还断言toolCalls(result)中包含submit_style_guide调用验证了“唯一结果出口”这条铁律。测试数据中固定的 PR 元数据#999baseproductionheadfix-link与 mock 的read_repo_file按 SHA 返回合成文件内容保证了评测的确定性。十、适用前提与限制该技能仅面向src/content/docs、src/content/partials、src/content/changelog下的 MDX 文件且单次最多审查 20 个文件按新增行数从大到小选取审查对象只包含 Patch 中新增的行未改动行、删除行、以及reviewed:日期是否过期均不在审查范围内规则文件必须存在于 manifest 中才会被加载组件参考文件默认不读取模型必须通过submit_style_guide恰好一次地提交结果否则useAgentFinish会追加提醒单个文件失败不会中断整个池子而是降级为空结果运行规则评测需要启动 Flue 开发服务器后另开终端执行pnpm run flue:dev与pnpm --dir .flue run evals见 rule-authoring.md 的 Evaluating rules 一节。总结style-guide-review是一个将“文档风格审查”彻底工程化的范例SKILL.md 定义机械式行为契约manifest 三分类参考规则实现按需加载以节省上下文warning/suggestion两级严重度与固定 JSON 结构让结果可以被可信代码合并、去重并分配稳定 ID而 eval 套件保证了每条规则的“有据可依、有测可验”。对于任何希望用 Agent 自动维护 MDX/文档风格一致性的团队这套“技能文件 参考清单 纯函数驱动 评测闭环”的组合都具备直接的迁移参考价值。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考