ELI5 技术文档简化方法论cloudflare-docs 写作模式库、隐喻库与质量保障体系详解【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本文基于 cloudflare-docs 仓库中 ELI5 技能.agents/skills/eli5/的扩展示例参考手册 EXAMPLES_REFERENCE.md 展开。ELI5Explain Like Im 5是一套面向文档 Agent 的技术写作技能核心使命是把术语密集、假设读者已具备领域背景的技术文档改写成对开发者、IT 管理员、营销人员乃至学生都清晰可读的版本——简化的是语言绝不是事实。读完本文你将掌握五种内容类型的简化模式、十条技术邻近隐喻、ELI5 输出模板、质量检查清单与边界情况处理策略并看到这套方法论在仓库中的源码级定义与真实产出样例。一、参考手册在仓库中的定位EXAMPLES_REFERENCE.md 是 ELI5 技能的三份支撑材料之一它的定位在文件开头写得很明确SKILL.md 是可执行规范而这份参考手册存放的是会让 SKILL.md 变得过于庞大的详细示例与模式。当 Agent 需要详细指导或示例时按目录索引到对应章节取用即可。仓库内.agents/skills/eli5/目录的完整结构为eli5/ ├── README.md # 技能介绍与 9 步工作流概览 ├── SKILL.md # 技能定义9 步工作流、约束、对抗性审查协议、质量清单、反模式 ├── references/ │ ├── content-type-guide.md # 各内容类型的检测信号与策略687 行 │ ├── EXAMPLES_REFERENCE.md # 详细的 before/after 示例与输出模板1834 行 │ └── pattern-library.md # 常见清晰度问题的可复用转换模式634 行 └── recommendations/ └── internal-dns/ └── index.eli5.mdx # 示例产出Internal DNS 概览页的 ELI5 改写稿三份参考文档分工不同content-type-guide.md 负责怎么检测并简化某种类型的页面pattern-library.md 提供具体句式与结构怎么改的复用模式而本文主角 EXAMPLES_REFERENCE.md 则提供完整的前后对照长示例覆盖五种内容类型、十大隐喻、输出模板与边界情况。二、内容类型驱动的简化模式ELI5 的第一步是识别内容类型——SKILL.md 定义了五种类型Overview、Concept、How To、Reference、Tutorial每种类型有独立的检测信号和简化策略。参考手册对每种类型给出了目的、必备要素、分析焦点、简化步骤和完整的 before/after 示例。2.1 概览页Overview从技术优先到价值优先目的帮助用户快速理解某个产品/功能是什么以及自己是否需要它。必备要素开场利益陈述解决什么问题→ 问题/方案/收益结构 → Perfect for自我识别区 → 快速上手链接 → 技术架构分离到底部。分析焦点开场段是否回答了是什么与为什么功能是否用收益而非描述来解释是否有清晰的行动号召技术术语是否被定义或隔离简化路径EXAMPLES_REFERENCE.md 中 Overview 节的五个步骤用收益开头——把技术描述转化为价值主张问题框架——从用户面临的挑战切入功能→收益转换——把功能列表改写成结果陈述自我识别——增加带用户场景的Perfect for分离技术细节——把架构挪进可折叠区块。模式示例技术优先 → 收益优先❌ Before技术优先: ## Product X Product X 是一个分布式边缘计算平台利用 V8 isolates 提供亚毫秒级冷启动的 无服务器代码执行性能采用全球 anycast 网络部署按请求计费。 ✅ After收益优先: ## Product X 无需管理服务器即可在世界各地运行代码。数秒部署自动扩展按用量付费。 **它解决的问题** 维护全球基础设施昂贵而复杂。Product X 自动在 300 城市运行你的代码 替你处理全部基础设施。 **适合谁** - 需要全球快速性能的应用 - 想跳过服务器管理的团队 - 流量波动的项目从零扩展到百万级 [5 分钟快速上手 →] --- **给技术用户** 基于 V8 isolates 与全球 anycast 部署。[架构细节 →]这段示例完整呈现了该类型最核心的转换逻辑把我们有什么技术改写成你得到什么价值同时用分隔线和给技术用户区块保留深度信息实现渐进式披露。2.2 概念页Concept从纯技术解释到分层解释目的建立它为什么以这种方式工作的理解。必备要素开场类比/可视化 → 平实语言定义 → 为什么重要的商业价值 → 简化版工作原理 → 3-5 个真实使用场景 → 给高级用户的技术细节分离。简化路径类比开场建立心智模型→ 平实英语定义 → 价值优先先为什么后怎么工作→ 分层解释简单→详细→技术→ 具体示例。模式示例纯技术 → 分层解释以限流为例❌ Before纯技术: ## Rate Limiting 限流基于令牌桶算法控制请求吞吐可配置突发大小与补充速率参数。 超过限额的请求会收到 429 状态码。 ✅ After分层解释: ## Rate Limiting **可以把它想成** 一家有最大容量的夜店。即使 1000 人同时想进 一次也只放进受控的人数保持局面可管理。 **它是什么** 限流控制单位时间内有多少请求能打到你的网站。没有它无论是真实用户 还是攻击者引发的突发流量都可能压垮你的服务器。 **你为什么需要它** - 防止 DDoS 攻击拖垮网站 - 阻止爬虫抓取内容 - 保证所有用户的公平使用 - 让基础设施成本可预测 **它如何工作** 你设置一条规则比如每个 IP 每分钟 100 个请求。当有人超过限额 我们在时间窗口重置前阻止额外请求。 **真实场景** - 电商网站黑色星期五防止机器人抢购 - API 防止商品目录被爬取 - 论坛防止垃圾帖刷屏 --- **给技术用户** 实现令牌桶算法突发大小与补充速率可配置。超限返回 429 状态码并携带 Retry-After 头。[实现细节 →]注意其技巧类比必须技术邻近夜店容量控制是大多数人熟悉的排队/容量场景同时诚实地在底部说明Where this breaks down——该模式的分层让零基础读者与资深工程师各取所需。2.3 操作指南页How To从纯步骤到带上下文的双路径目的帮助用户成功完成具体任务。必备要素上下文完成什么、为什么做→ 前置条件前置 → 预期结果 → 时间估计若耗时→ 仪表盘路径UI 步骤→ API/CLI 路径折叠区内代码→ 验证步骤 → 常见问题与排查。简化路径补上下文 → 列前置条件 → 双路径指令仪表盘 API/CLI→ 给步骤加注释 → 加验证 → 处理常见坑。模式示例纯步骤 → 带上下文的多路径完整呈现了该模板的骨架## Enable Feature **这样做的作用** 通过 [具体机制] 保护你的站点免受 [具体威胁]。 **所需时间** 约 2 分钟 **前置条件** 账户管理员权限 **会发生什么** 启用后所有入站请求将[具体行为]。5 分钟内可在 Analytics 看到结果。 ### 通过仪表盘 1. 登录 dash.example.com 仪表盘 2. 从列表中选择你的站点 3. 在左侧边栏点击 **Security** 4. 找到 **Feature Name** 并切换到 **On** 5. 点击 **Save Changes** **注意** 变更立即生效但分析数据可能需要 5 分钟更新。 ### 通过 API details summary展开查看 API 示例/summary curl -X PATCH https://api.example.com/v1/settings \ -H Authorization: Bearer YOUR_TOKEN \ -d {feature_enabled: true} **响应** { success: true, result: { feature_enabled: true, updated_at: 2026-02-09T10:30:00Z } } [完整 API 文档 →] /details ## 验证是否生效 1. 在新浏览器标签页访问你的站点 2. 打开开发者工具F12 3. 在 Network 标签查看 [具体请求头/行为] 4. 你应该看到 [预期结果] ## 故障排查 **问题** 功能似乎未生效 **解决** 清理浏览器缓存并等待 5 分钟传播。仍无效检查 [前置条件]。该模板的关键工程点是details折叠API 路径服务于技术用户同时不吓跑新手。注意 SKILL.md 中的约束——如果原文只有一条路径不要自行创造缺失的路径只把它记为建议让作者确认。2.4 参考页Reference从字母序规格到按用途组织目的以易读的方式提供全面的技术细节。必备要素开场上下文何时使用这份参考→ 常见场景前置 → 按用途而非字母序组织 → 双层描述平实英语 技术规格→ 每个条目的实用示例 → 真实使用场景。简化路径加开场上下文 → 按用途重组 → 双层描述 → 加示例含预期结果→ 加何时使用决策指导。模式示例字母序纯规格 → 按用途组织以缓存头为例展示了完整的条目级模板——每条目包含作用 / 何时用 / 技术规格 / 示例 / 结果五个部分## Cache Headers Reference **何时使用** 控制内容缓存多久、谁能缓存。 ### 常见场景 场景 1静态资源图片、CSS、JS→ 缓存 1 年 场景 2博客文章 → 缓存 1 小时 场景 3用户仪表盘 → 永不缓存 --- ## 按用途分类的头 ### 长期缓存静态资源 #### max-age315360001 年 **作用** 内容缓存 1 年后才检查更新 **何时使用** 永不变化的文件如 logo-v2.png 或带版本哈希的 style.abc123.css **技术规格** 整数单位秒。范围0-315360001 年上限 **示例** Cache-Control: public, max-age31536000, immutable **结果** 首个访问者下载文件接下来一年内所有访问者拿到缓存版本 对源站零请求。 --- #### immutable **作用** 告知浏览器此文件永远不会变化 **何时使用** 与 max-age 组合用于版本化资源文件名含哈希/版本号 **技术规格** 无值出现即生效。 **示例** Cache-Control: public, max-age31536000, immutable **结果** 浏览器即使在刷新时也不会重新校验。适用于内容变化时哈希随之 变化的 style.abc123.css。 --- ### 频繁更新内容 #### max-age36001 小时 **作用** 内容缓存 1 小时 **何时使用** 偶尔更新但不需实时的内容如博客文章或产品页 **示例** Cache-Control: public, max-age3600 **结果** 缓存 1 小时到期后下一个请求回源检查更新。 #### no-cache **作用** 使用缓存版本前始终回源校验 **何时使用** 频繁变化但仍可短暂缓存的内容购物车、个性化页面 **示例** Cache-Control: no-cache **结果** 每个请求通过 If-Modified-Since 或 ETag 回源校验无变化则返回 304 并服务缓存版本。 --- ### 永不缓存 #### private, no-store **作用** 禁止一切缓存 **何时使用** 敏感数据账户信息、支付细节或高动态内容实时比分、直播聊天 **技术规格** 两个指令组合使用 **示例** Cache-Control: private, no-store **结果** 每个请求都从源站取最新数据任何位置都不缓存。按用途分组而非按字母序罗列是参考页简化最具价值的模式——用户在解决怎么缓存静态资源时不需要扫过全部指令再自行判断。2.5 教程页Tutorial从代码倾倒到解释式渐进目的通过真实应用教学逐步建立信心。必备要素你将构建什么带具体示例→ 适合谁含前置条件→ 时间估计 → 你将学到什么 → 渐进复杂度最小→完整→打磨→ 代码块解释这段代码做什么→ 排查章节 → 明确标记的可选增强。简化路径设定预期做什么/谁/时间/学习成果→ 最小起点用最简版本证明概念→ 渐进增强一次加一个功能→ 解释每个代码块 → 排查 → 标记可选。模式示例代码倾倒 → 解释式渐进以 URL 缩短器为例展示了教程的完整节奏——每一步包含代码、逐行解释、测试方法## 构建一个 URL 缩短器 ### 你将构建什么 一个可用的 URL 缩短器把短链重定向到长 URL、存储映射、跟踪点击统计。 **在线示例** short.example.com/github → github.com/cloudflare ### 适合谁 熟悉 JavaScript 的开发者。无需 Workers 经验但应理解 - HTTP 请求与响应 - JSON 数据格式 - 基本 async/await ### 所需时间 30-45 分钟 ### 你将学到什么 - 如何在边缘处理请求 - 在键值存储中存取数据 - 构建一个简单 API - 数秒内全球部署代码 --- ## 第 1 步创建你的第一个 Worker 从绝对最小版本开始——一个响应请求的 Worker // 入口每个 HTTP 请求都会执行 addEventListener(fetch, event { // 把请求交给我们的处理函数 event.respondWith(handleRequest(event.request)) }) // 处理函数处理请求并返回响应 async function handleRequest(request) { return new Response(你的 URL 缩短器将在这里, { headers: { content-type: text/plain } }) } **这段代码做什么** - **第 2 行** 监听入站 HTTP 请求 - **第 4 行** 调用 handleRequest 处理每个请求 - **第 8-12 行** 返回简单文本响应 **测试它** 部署后访问 Worker 的 URL应看到 你的 URL 缩短器将在这里——证明 Worker 已在运行。 ## 第 2 步添加 URL 解析 [逐步构建……] ## 常见问题 **问题** Error: Exceeded CPU limit **原因** 单个请求内做了太多计算 **解决** Workers 有 CPU 时间限制。把重计算移到后台任务 或使用 Durable Objects 处理长操作。 **问题** KV 数据不更新 **原因** KV 最终一致全球传播可能需要 60 秒 **解决** 测试时加缓存破坏参数?v2或写入与读取间等待 60 秒。 ## 可选增强 **添加点击统计**中难度在 KV 中记录点击数、重定向时自增、创建统计端点 **自定义短码**简单让用户自选短码、检查是否被占用、不可用时返回错误 **过期链接**中难度存储过期时间戳、重定向前检查、过期返回 404教程模式的核心纪律是不重写代码只解释代码每个代码块附带这段代码做什么把渐进增强与可选增强严格区分避免读者误以为所有功能都是必须的。三、简化原则从措辞到心智模型3.1 平实语言准则Plain Language Guidelines参考手册给出了五条句式层面的硬性准则每句一个观点Webhooks 会发送通知。这发生在事件出现时。而不是Webhooks 是 HTTP 回调会在平台发生特定事件时向你的指定端点发送包含事件数据的通知。主动语态优先系统发送通知而非通知由系统发送。具体名词优先你的端点收到一个 POST 请求而非接口抽象层促进了数据传输。同等准确时用常用词用 Use 而非 utilizeHelp 而非 facilitateStart 而非 initiate。短段落最多 3-4 句便于扫读、提供视觉留白、保持单主题聚焦。3.2 术语处理首次出现必定义APIApplication Programming Interface应用程序接口展开缩写CDNContent Delivery Network、CI/CDContinuous Integration/Continuous Deployment、HMACHash-based Message Authentication Code给技术术语提供上下文不要写配置 webhook 端点而写webhook 端点是我们发送通知的 URL把它配置到你的服务器。pattern-library.md 还提供了一张术语→平实英语对照词典.agents/skills/eli5/references/pattern-library.md例如 Implement→Set up、Utilize→Use、Egress→Outgoing data出站数据、Anycast→Routing to nearest server自动路由到最近位置、Propagation→Spreading, updating全球生效。同时SKILL.md 明令禁止同义词堆叠——定义过的概念不要再说也叫 X一个行为式定义足矣。3.3 隐喻库十条技术邻近隐喻ELI5 对隐喻有明确标准植根于读者可能熟悉的技术、关键概念 1:1 映射、比原概念更简单、诚实说明隐喻失效之处。参考手册维护了一个隐喻库每个都带Where this breaks down失效点声明#概念隐喻失效点1API餐厅菜单菜单列明可点的菜端点、可做的定制参数、你将得到的响应API 响应近乎瞬时API 会失败厨房缺食材需要错误处理2缓存图书馆预约台热门书放在前台快速取用缓存会过期缓存失效比隐喻复杂3负载均衡超市收银通道分散到多个通道堵了就改道负载均衡器知道服务器健康度、繁忙度可基于算法路由4Webhook门铃通知有人按门铃才提醒推送而非反复查看门口轮询门铃瞬时webhook 有网络延迟服务器宕机会导致失败像坏门铃5认证大楼门禁工牌出示工牌验证身份认证再检查可进入楼层授权数字认证用限时令牌可多因素验证6限流高速公路上匝道信号灯控制每分钟进入的车辆数限流通常是按用户独立的且按周期重置7数据库索引教科书后的索引不用读每页索引直接告诉你在哪几页数据变化时索引要更新选择索引字段是读/写速度的权衡8CDN本地仓库加州用户从加州仓库发货物理仓库库存唯一CDN 是所有地点存同一内容的副本更新需全量传播9容器海运集装箱标准化包装任意船/车/火车可运软件容器共享操作系统内核物理集装箱完全隔离10环境变量应用的设置面板不修改代码即可改变行为的配置值环境变量通常在启动前设定且按环境dev/staging/prod隔离参考手册还给出了创建新隐喻的五步法EXAMPLES_REFERENCE.md 第 858-866 行识别核心机制或目的 → 找到读者熟悉的技术邻近类比 → 关键概念 1:1 映射 → 测试是澄清了还是制造了新困惑 → 说明失效点。3.4 Why 优先的解释顺序参考手册规定内容组织顺序必须是问题Why→ 方案What→ 价值Why It Matters→ 使用场景When→ 实现How。以 webhook 为例问题构建应用时常需知道另一平台何时发生某事支付完成、上传结束、部署成功。持续轮询浪费资源并带来延迟。方案Webhook 在事件发生时立即向你的服务器推送消息。价值实时响应、节省资源、用户获得更快更新、只处理真实发生的事件。使用场景部署完成触发工作流、内容变化时更新数据库、支付成功发通知、系统间自动同步。实现创建接收通知的端点 URL → 配置要接收的事件 → 用签名验证请求来源 → 处理事件数据。理由是目的先于机制——这正是人类学习的顺序。3.5 多受众分层同一文档要同时服务不同知识水平的人参考手册给出了分层结构In Plain Language一句话人人可懂→ What It Is从基础建立理解的 2-3 段→ Why It Matters → When Youd Use This → Think of It Like隐喻然后分隔线再用For developers提供 API 引用与代码示例、For non-technical readers聚焦结果与业务影响。这与 2.1 节的给技术用户折叠区一脉相承。四、输出格式模板4.1 生成文件的完整模板当 Agent 执行完整简化时产出.eli5.md文件其结构EXAMPLES_REFERENCE.md 第 957-1108 行为# ELI5 Simplified: [原文档名] **Original:** [文件路径] **Simplified on:** [时间戳] **Sections simplified:** [章节列表] --- ## Simplification Overview **What was confusing:** - [模式 1 - 如缩写大量使用且未展开] - [模式 2 - 如假设读者已懂 HTTP 协议] **Approach taken:** - [策略 1 - 如为每个概念加一句话摘要] - [策略 2 - 如首次出现即展开所有缩写] --- ## Section: [原标题] ### Original Content [源文本原样保留格式不变] ### ⚠️ Issues Identified **Jargon术语:** [术语] - [问题所在、假设了什么] **Assumptions假设:** [假设了什么] **Unclear Logic逻辑不清:** [问题] ### ✨ Simplified Version **In Plain Language:** [无术语的一句话精炼] **What It Is:** [从基础建立的 2-3 段] **Why It Matters:** [价值主张与具体收益] **When Youd Use This:** [带语境的场景 1/2/3] **Think of It Like:** [技术邻近隐喻含完整展开] **Where this metaphor breaks down:** [诚实说明局限] **Common Pitfalls:** [误解 → 纠正] **Related Concepts:** [与已知概念的连接] --- [每个章节重复此结构] --- ## Summary Recommendations **Key Improvements Made:** [改进清单] **Patterns Noticed:** [元分析这份文档难懂的原因] ## ✅ Next Steps 1. Suggest additional improvements 2. Create a PR 3. Refine specific sections 4. Apply changes to original 5. Keep as reference该模板的关键设计是原样保留原文Original Content 区块逐字保存、格式不变——这保证了任何简化都可被审计对比事实核查有据可依。4.2 文件命名约定输入path/to/documentation.md→ 输出path/to/documentation.eli5.md输入api-reference.mdx→ 输出api-reference.eli5.mdx。.eli5后缀清晰标识简化版本同时保留原格式扩展名。仓库中的真实产出.agents/skills/eli5/recommendations/internal-dns/index.eli5.mdx正是这一约定的落地实例——它是一份针对 Internal DNS 概览页的完整改写稿保留了原文的Description、Plan、Example等所有 MDX 组件和三张 mermaid 图目标扩展比 1.89x135 → 255 行并在文末附带了完整的enhancement summary。4.3 Suggestions for Enhancement增强建议主简化完成后Agent 会追加一个增强建议章节每条建议包含六个字段行号引用、适用章节、当前做法、建议增强、为何有帮助、实现示例。参考手册给出了三个完整样例L45-52 添加双路径指令原文只有仪表盘路径建议补充 API 路径附curl -X PATCH .../settings/always_use_https请求与响应示例理由是同时服务 UI 用户与偏好代码的开发者L78-85 把技术细节移入折叠区原文把密码套件细节内联在主体解释中建议移入detailssummaryFor technical users/summary...折叠区附 TLS 1.3 AEAD 套件列表示例实现清晰的渐进披露L120-122 给出推荐默认值原文把所有加密模式Off/Flexible/Full/Full Strict等权罗列建议标出Recommended for most sites: Full (Strict)减少选择瘫痪L195-200 添加具体使用场景原文只有抽象收益陈述建议补一个黑色星期五 DDoS 攻击中真实顾客正常下单的场景化故事。何时启用该章节存在多路径机会Dashboard API、技术细节可折叠、缺少推荐默认值、抽象概念需要具体示例、渐进披露可改进、常见决策点缺指导。放置位置在Summary Recommendations之后、Next Steps之前。五、质量保障体系从检查清单到对抗性审查5.1 质量检查清单Quality Checklist参考手册规定任何简化内容定稿前必须逐项核对第 1309-1327 行技术准确性保持不变——没有改变或过度简化任何事实一句话摘要无术语地抓住本质术语被识别并解释或替换假设在 Issues 区块中被显式声明解释中Why先于What用例真实且实用隐喻关键概念 1:1 映射隐喻局限被承认常见坑确实常见不是编造的语气专业且尊重没有居高临下的措辞simplyjustobviously全程尊重读者智力。5.2 语气规则Tone Rules参考手册明令禁止居高临下的措辞Simply configure the endpoint...、Just add the webhook URL...、Obviously, youll need to...、Clearly, this requires...、As everyone knows...、Its easy to...、All you have to do is...。替代方案是尊重读者的表达To configure the endpoint, youll need to...、Add the webhook URL by...、This requires...、Heres how this works...。这与 SKILL.md 的基调一致——面向聪明但缺乏具体领域背景的读者。5.3 准确性不可妥协好的简化示例Webhooks 在指定事件发生时向你的端点 URL 发送 HTTP POST 请求。把它想成一个通知系统——我们调用你的服务器而不是你不断轮询我们的服务器。准确、清晰、有效用隐喻。坏的简化示例Webhooks 让程序之间互相交谈。过于含糊、丢失重要细节、实际没有帮助。当必须保留复杂准确性时使用渐进式披露**简化版** 限流控制你在一个时间段内能发起多少请求比如每分钟 100 次。 **更精确地说** 限流按 API key 生效采用滑动窗口重置。达到上限后 返回 429 状态码并带 Retry-After 头指示何时可以重试。这套准则与 SKILL.md 完全呼应简化意味着更清晰的语言而非降低精度如果简化后的解释在技术上是错的应该增加细微差别而不是省略它。同时 SKILL.md 特别强调 Cloudflare 特有实现可能与行业惯例不同任何净新增信息必须对照仓库中的src/content/docs/源文档核验并给出引用来源。5.4 不同内容类型的处理侧重API 文档聚焦端点目的、使用场景、发送参数解释参数用途而非仅类型、返回响应、常见用例、错误处理什么会出错通过解释参数用途、展示真实请求/响应示例、澄清常见误解来增值。架构文档聚焦被解决的问题、为何选择此方案、做出的权衡得到了什么/失去了什么、何时该架构合理、考虑过的替代方案通过解释决策理由、显式化权衡、连接业务需求来增值。代码文档聚焦代码达成什么、为何这样组织、使用的关键概念或模式、需要注意什么通过平实语言阅读指南、解释非显然的选择、展示部件如何组合来增值。5.5 对抗性审查Adversarial Review这是 SKILL.md 中定义的强制第 9 步提交前必须启动一个全新的子 Agent与当前会话隔离、不接触 ELI5 技能说明以怀疑论者身份逐条核验新增主张。审查重点是五类高风险内容简化机制描述听起来合理但机制错误的解释比原术语更糟、误导性细微差别如把 per-path 的 allow/disallow 机制说成全盘屏蔽、净新增主张每一条新信息都要有引用、Cloudflare 特有行为不得假设行业惯例适用于 Cloudflare 产品、跨类别过度概括所有记录每个请求这类量词是否真实普适。审查产出是一张带严重级别critical/high/medium/low的主张核查表每个问题必须引用证据来源。六、边界情况与处理策略参考手册为五类边界情况给出了明确策略第 1425-1553 行超长文档1000 行向用户提供四种处理选项——处理全部章节 / 聚焦指定章节列出清单/ 自动检测最复杂章节 / 分块处理如 1-10、11-20。自动检测逻辑包括计算术语密度每 100 词的术语数、统计假设指示词as you know、无解释的引用、识别没有用例或why陈述的章节优先处理复杂度得分最高的章节。已清晰的文档承认其清晰度只做小改进。明确列出要避免的行为——不添加不必要的冗长、不制造不存在的问题、不过度解释已清楚的内容、不为了有话可说而填充。产出格式是做得好的地方 小改进建议 总体评估。高技术含量内容先保准确绝不过度简化到错误分层解释High-level → How it works → Technical details加解释性散文但不改技术规格用渐进披露并明确各章节写给谁。代码密集文档不简化代码本身——代码必须保持准确不重写功能代码围绕代码添加解释性上下文这段代码做什么为什么这样组织关键理解点创建阅读指南逐段走读复杂代码。含组件的 MDX 文件聚焦散文内容、组件代码保持不动解释组件目的如CodeBlock组件显示带语法高亮和复制功能的代码除非文档本身就是讲 React/框架细节否则不深入框架实现。七、未来增强计划参考手册末尾记录了对未来迭代的规划第 1555-1619 行标注为documented for future implementation内联代码注释读取支持解析带内联文档的代码文件提取 docstring 与注释、简化注释中的技术语言、为复杂逻辑添加解释性散文、生成代码走读指南规划支持.js/.ts/.tsx/.py/.go/.rb/.java。多格式支持HTML 文档、PDF 技术论文、Confluence/Wiki 页面、OpenAPI 规范的可访问化。自动化复杂度评分术语密度每 100 词、可读性分数Flesch-Kincaid、SMOG 指数、假设检测标记假设知识的短语、上下文缺口分析识别缺失的why与when并按复杂度排序章节、聚焦高价值简化、生成复杂度报告。交互模式逐节处理并接收用户反馈、基于输入的实时精炼、迭代改进循环、不同隐喻的 A/B 测试。八、完整工作示例两份逐行对照参考手册第 1621-1786 行给出了两份完整的端到端示例展示全部要素如何组装。示例一API 文档POST /webhooks。原文档只有端点名、参数表endpoint/events/secret 三个参数及类型与响应说明简化版将其扩写为八个区块——In Plain Language设置自动通知特定事件发生时我们发送到你的服务器、What It Is对比轮询解释推送机制、Why It Matters实时更新、资源效率、可靠性、自动化、When Youd Use This部署通知、内容同步、监控、系统集成、Think of It Like门铃隐喻、Where this breaks down网络延迟与服务器宕机需要重试逻辑、Parameters Explained每个参数用行为而非类型定义endpoint 是你的服务器监听 webhook 事件的地址必须用 HTTPS、Common Pitfalls以为 webhook 100% 可靠与不验证签名两条纠正。它还特别用 RSS 类比收尾两者都推送更新但 webhook 可编程且适用于任意事件类型。示例二架构决策边缘部署架构。原文档一句话描述了利用 V8 isolates 的多租户全局分布式边缘架构简化版补上了完整论证链——Plain Language代码部署在全球服务器上用户就近响应、What It Is弗吉尼亚的服务器服务新加坡用户要跨半球往返边缘架构让请求由最近节点处理、Why It Matters速度、可靠性、规模、简单性、Think of It Like中心仓库 vs 各城本地仓库、Technical Approachisolates 微秒级启动 vs 容器 50-500ms 冷启动、Why this architecture列出评估过的三种方案传统服务器/容器 serverless/isolate 边缘并说明选择理由、Tradeoff made无任意系统库、执行时间受限为速度接受约束、Common Pitfalls假设与普通服务器相同——无持久本地存储、无后台任务期待 Node.js 兼容——实现的是 Web 标准。九、方法论在仓库中的闭环从规范到产出回顾整个体系ELI5 在 cloudflare-docs 中形成了一条完整的闭环可执行规范SKILL.md 定义了 9 步工作流接受文件→识别内容类型→施加增强约束→选择章节→分析问题→提取术语→生成对照→报告→对抗性审查、决策框架何时简化术语/加内容/点明后果/加术语气泡、18 项质量清单和 8 条反模式操作指南content-type-guide.md 提供五种内容类型的检测信号与检测决策树以及1.5-2x 保守扩展的硬约束复用模式pattern-library.md 提供术语词典、五种转换模式技术优先→收益优先、抽象→隐喻、纯步骤→多路径、字母序→按用途、代码倾倒→解释式渐进与隐喻模板详细示例本文主角 EXAMPLES_REFERENCE.md 提供逐行完整的长示例与输出模板真实产出index.eli5.mdx 是整套方法论应用在 Internal DNS 概览页上的完整成果——保留全部 MDX 组件与 mermaid 图补充了何时使用查询流程五步走三个带落地场景的用例Getting started 清单目标扩展 1.89x。整套方法论的最后一段哲学总结值得记住技术专长永远不应成为理解的门槛。每个人都值得获得清晰、准确、尊重人的文档。而 SKILL.md 的质量清单则给出了执行此哲学的落点技术准确、Why 先于 What、隐喻 1:1 映射且声明局限、不居高临下、保持 1.5-2x 的克制扩展、不重写本就正确的散文、每个简化描述的都是正确机制——因为一个听起来合理但机制错误的解释比原来的术语更糟。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ELI5 技术文档简化方法论：cloudflare-docs 写作模式库、隐喻库与质量保障体系详解
ELI5 技术文档简化方法论cloudflare-docs 写作模式库、隐喻库与质量保障体系详解【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本文基于 cloudflare-docs 仓库中 ELI5 技能.agents/skills/eli5/的扩展示例参考手册 EXAMPLES_REFERENCE.md 展开。ELI5Explain Like Im 5是一套面向文档 Agent 的技术写作技能核心使命是把术语密集、假设读者已具备领域背景的技术文档改写成对开发者、IT 管理员、营销人员乃至学生都清晰可读的版本——简化的是语言绝不是事实。读完本文你将掌握五种内容类型的简化模式、十条技术邻近隐喻、ELI5 输出模板、质量检查清单与边界情况处理策略并看到这套方法论在仓库中的源码级定义与真实产出样例。一、参考手册在仓库中的定位EXAMPLES_REFERENCE.md 是 ELI5 技能的三份支撑材料之一它的定位在文件开头写得很明确SKILL.md 是可执行规范而这份参考手册存放的是会让 SKILL.md 变得过于庞大的详细示例与模式。当 Agent 需要详细指导或示例时按目录索引到对应章节取用即可。仓库内.agents/skills/eli5/目录的完整结构为eli5/ ├── README.md # 技能介绍与 9 步工作流概览 ├── SKILL.md # 技能定义9 步工作流、约束、对抗性审查协议、质量清单、反模式 ├── references/ │ ├── content-type-guide.md # 各内容类型的检测信号与策略687 行 │ ├── EXAMPLES_REFERENCE.md # 详细的 before/after 示例与输出模板1834 行 │ └── pattern-library.md # 常见清晰度问题的可复用转换模式634 行 └── recommendations/ └── internal-dns/ └── index.eli5.mdx # 示例产出Internal DNS 概览页的 ELI5 改写稿三份参考文档分工不同content-type-guide.md 负责怎么检测并简化某种类型的页面pattern-library.md 提供具体句式与结构怎么改的复用模式而本文主角 EXAMPLES_REFERENCE.md 则提供完整的前后对照长示例覆盖五种内容类型、十大隐喻、输出模板与边界情况。二、内容类型驱动的简化模式ELI5 的第一步是识别内容类型——SKILL.md 定义了五种类型Overview、Concept、How To、Reference、Tutorial每种类型有独立的检测信号和简化策略。参考手册对每种类型给出了目的、必备要素、分析焦点、简化步骤和完整的 before/after 示例。2.1 概览页Overview从技术优先到价值优先目的帮助用户快速理解某个产品/功能是什么以及自己是否需要它。必备要素开场利益陈述解决什么问题→ 问题/方案/收益结构 → Perfect for自我识别区 → 快速上手链接 → 技术架构分离到底部。分析焦点开场段是否回答了是什么与为什么功能是否用收益而非描述来解释是否有清晰的行动号召技术术语是否被定义或隔离简化路径EXAMPLES_REFERENCE.md 中 Overview 节的五个步骤用收益开头——把技术描述转化为价值主张问题框架——从用户面临的挑战切入功能→收益转换——把功能列表改写成结果陈述自我识别——增加带用户场景的Perfect for分离技术细节——把架构挪进可折叠区块。模式示例技术优先 → 收益优先❌ Before技术优先: ## Product X Product X 是一个分布式边缘计算平台利用 V8 isolates 提供亚毫秒级冷启动的 无服务器代码执行性能采用全球 anycast 网络部署按请求计费。 ✅ After收益优先: ## Product X 无需管理服务器即可在世界各地运行代码。数秒部署自动扩展按用量付费。 **它解决的问题** 维护全球基础设施昂贵而复杂。Product X 自动在 300 城市运行你的代码 替你处理全部基础设施。 **适合谁** - 需要全球快速性能的应用 - 想跳过服务器管理的团队 - 流量波动的项目从零扩展到百万级 [5 分钟快速上手 →] --- **给技术用户** 基于 V8 isolates 与全球 anycast 部署。[架构细节 →]这段示例完整呈现了该类型最核心的转换逻辑把我们有什么技术改写成你得到什么价值同时用分隔线和给技术用户区块保留深度信息实现渐进式披露。2.2 概念页Concept从纯技术解释到分层解释目的建立它为什么以这种方式工作的理解。必备要素开场类比/可视化 → 平实语言定义 → 为什么重要的商业价值 → 简化版工作原理 → 3-5 个真实使用场景 → 给高级用户的技术细节分离。简化路径类比开场建立心智模型→ 平实英语定义 → 价值优先先为什么后怎么工作→ 分层解释简单→详细→技术→ 具体示例。模式示例纯技术 → 分层解释以限流为例❌ Before纯技术: ## Rate Limiting 限流基于令牌桶算法控制请求吞吐可配置突发大小与补充速率参数。 超过限额的请求会收到 429 状态码。 ✅ After分层解释: ## Rate Limiting **可以把它想成** 一家有最大容量的夜店。即使 1000 人同时想进 一次也只放进受控的人数保持局面可管理。 **它是什么** 限流控制单位时间内有多少请求能打到你的网站。没有它无论是真实用户 还是攻击者引发的突发流量都可能压垮你的服务器。 **你为什么需要它** - 防止 DDoS 攻击拖垮网站 - 阻止爬虫抓取内容 - 保证所有用户的公平使用 - 让基础设施成本可预测 **它如何工作** 你设置一条规则比如每个 IP 每分钟 100 个请求。当有人超过限额 我们在时间窗口重置前阻止额外请求。 **真实场景** - 电商网站黑色星期五防止机器人抢购 - API 防止商品目录被爬取 - 论坛防止垃圾帖刷屏 --- **给技术用户** 实现令牌桶算法突发大小与补充速率可配置。超限返回 429 状态码并携带 Retry-After 头。[实现细节 →]注意其技巧类比必须技术邻近夜店容量控制是大多数人熟悉的排队/容量场景同时诚实地在底部说明Where this breaks down——该模式的分层让零基础读者与资深工程师各取所需。2.3 操作指南页How To从纯步骤到带上下文的双路径目的帮助用户成功完成具体任务。必备要素上下文完成什么、为什么做→ 前置条件前置 → 预期结果 → 时间估计若耗时→ 仪表盘路径UI 步骤→ API/CLI 路径折叠区内代码→ 验证步骤 → 常见问题与排查。简化路径补上下文 → 列前置条件 → 双路径指令仪表盘 API/CLI→ 给步骤加注释 → 加验证 → 处理常见坑。模式示例纯步骤 → 带上下文的多路径完整呈现了该模板的骨架## Enable Feature **这样做的作用** 通过 [具体机制] 保护你的站点免受 [具体威胁]。 **所需时间** 约 2 分钟 **前置条件** 账户管理员权限 **会发生什么** 启用后所有入站请求将[具体行为]。5 分钟内可在 Analytics 看到结果。 ### 通过仪表盘 1. 登录 dash.example.com 仪表盘 2. 从列表中选择你的站点 3. 在左侧边栏点击 **Security** 4. 找到 **Feature Name** 并切换到 **On** 5. 点击 **Save Changes** **注意** 变更立即生效但分析数据可能需要 5 分钟更新。 ### 通过 API details summary展开查看 API 示例/summary curl -X PATCH https://api.example.com/v1/settings \ -H Authorization: Bearer YOUR_TOKEN \ -d {feature_enabled: true} **响应** { success: true, result: { feature_enabled: true, updated_at: 2026-02-09T10:30:00Z } } [完整 API 文档 →] /details ## 验证是否生效 1. 在新浏览器标签页访问你的站点 2. 打开开发者工具F12 3. 在 Network 标签查看 [具体请求头/行为] 4. 你应该看到 [预期结果] ## 故障排查 **问题** 功能似乎未生效 **解决** 清理浏览器缓存并等待 5 分钟传播。仍无效检查 [前置条件]。该模板的关键工程点是details折叠API 路径服务于技术用户同时不吓跑新手。注意 SKILL.md 中的约束——如果原文只有一条路径不要自行创造缺失的路径只把它记为建议让作者确认。2.4 参考页Reference从字母序规格到按用途组织目的以易读的方式提供全面的技术细节。必备要素开场上下文何时使用这份参考→ 常见场景前置 → 按用途而非字母序组织 → 双层描述平实英语 技术规格→ 每个条目的实用示例 → 真实使用场景。简化路径加开场上下文 → 按用途重组 → 双层描述 → 加示例含预期结果→ 加何时使用决策指导。模式示例字母序纯规格 → 按用途组织以缓存头为例展示了完整的条目级模板——每条目包含作用 / 何时用 / 技术规格 / 示例 / 结果五个部分## Cache Headers Reference **何时使用** 控制内容缓存多久、谁能缓存。 ### 常见场景 场景 1静态资源图片、CSS、JS→ 缓存 1 年 场景 2博客文章 → 缓存 1 小时 场景 3用户仪表盘 → 永不缓存 --- ## 按用途分类的头 ### 长期缓存静态资源 #### max-age315360001 年 **作用** 内容缓存 1 年后才检查更新 **何时使用** 永不变化的文件如 logo-v2.png 或带版本哈希的 style.abc123.css **技术规格** 整数单位秒。范围0-315360001 年上限 **示例** Cache-Control: public, max-age31536000, immutable **结果** 首个访问者下载文件接下来一年内所有访问者拿到缓存版本 对源站零请求。 --- #### immutable **作用** 告知浏览器此文件永远不会变化 **何时使用** 与 max-age 组合用于版本化资源文件名含哈希/版本号 **技术规格** 无值出现即生效。 **示例** Cache-Control: public, max-age31536000, immutable **结果** 浏览器即使在刷新时也不会重新校验。适用于内容变化时哈希随之 变化的 style.abc123.css。 --- ### 频繁更新内容 #### max-age36001 小时 **作用** 内容缓存 1 小时 **何时使用** 偶尔更新但不需实时的内容如博客文章或产品页 **示例** Cache-Control: public, max-age3600 **结果** 缓存 1 小时到期后下一个请求回源检查更新。 #### no-cache **作用** 使用缓存版本前始终回源校验 **何时使用** 频繁变化但仍可短暂缓存的内容购物车、个性化页面 **示例** Cache-Control: no-cache **结果** 每个请求通过 If-Modified-Since 或 ETag 回源校验无变化则返回 304 并服务缓存版本。 --- ### 永不缓存 #### private, no-store **作用** 禁止一切缓存 **何时使用** 敏感数据账户信息、支付细节或高动态内容实时比分、直播聊天 **技术规格** 两个指令组合使用 **示例** Cache-Control: private, no-store **结果** 每个请求都从源站取最新数据任何位置都不缓存。按用途分组而非按字母序罗列是参考页简化最具价值的模式——用户在解决怎么缓存静态资源时不需要扫过全部指令再自行判断。2.5 教程页Tutorial从代码倾倒到解释式渐进目的通过真实应用教学逐步建立信心。必备要素你将构建什么带具体示例→ 适合谁含前置条件→ 时间估计 → 你将学到什么 → 渐进复杂度最小→完整→打磨→ 代码块解释这段代码做什么→ 排查章节 → 明确标记的可选增强。简化路径设定预期做什么/谁/时间/学习成果→ 最小起点用最简版本证明概念→ 渐进增强一次加一个功能→ 解释每个代码块 → 排查 → 标记可选。模式示例代码倾倒 → 解释式渐进以 URL 缩短器为例展示了教程的完整节奏——每一步包含代码、逐行解释、测试方法## 构建一个 URL 缩短器 ### 你将构建什么 一个可用的 URL 缩短器把短链重定向到长 URL、存储映射、跟踪点击统计。 **在线示例** short.example.com/github → github.com/cloudflare ### 适合谁 熟悉 JavaScript 的开发者。无需 Workers 经验但应理解 - HTTP 请求与响应 - JSON 数据格式 - 基本 async/await ### 所需时间 30-45 分钟 ### 你将学到什么 - 如何在边缘处理请求 - 在键值存储中存取数据 - 构建一个简单 API - 数秒内全球部署代码 --- ## 第 1 步创建你的第一个 Worker 从绝对最小版本开始——一个响应请求的 Worker // 入口每个 HTTP 请求都会执行 addEventListener(fetch, event { // 把请求交给我们的处理函数 event.respondWith(handleRequest(event.request)) }) // 处理函数处理请求并返回响应 async function handleRequest(request) { return new Response(你的 URL 缩短器将在这里, { headers: { content-type: text/plain } }) } **这段代码做什么** - **第 2 行** 监听入站 HTTP 请求 - **第 4 行** 调用 handleRequest 处理每个请求 - **第 8-12 行** 返回简单文本响应 **测试它** 部署后访问 Worker 的 URL应看到 你的 URL 缩短器将在这里——证明 Worker 已在运行。 ## 第 2 步添加 URL 解析 [逐步构建……] ## 常见问题 **问题** Error: Exceeded CPU limit **原因** 单个请求内做了太多计算 **解决** Workers 有 CPU 时间限制。把重计算移到后台任务 或使用 Durable Objects 处理长操作。 **问题** KV 数据不更新 **原因** KV 最终一致全球传播可能需要 60 秒 **解决** 测试时加缓存破坏参数?v2或写入与读取间等待 60 秒。 ## 可选增强 **添加点击统计**中难度在 KV 中记录点击数、重定向时自增、创建统计端点 **自定义短码**简单让用户自选短码、检查是否被占用、不可用时返回错误 **过期链接**中难度存储过期时间戳、重定向前检查、过期返回 404教程模式的核心纪律是不重写代码只解释代码每个代码块附带这段代码做什么把渐进增强与可选增强严格区分避免读者误以为所有功能都是必须的。三、简化原则从措辞到心智模型3.1 平实语言准则Plain Language Guidelines参考手册给出了五条句式层面的硬性准则每句一个观点Webhooks 会发送通知。这发生在事件出现时。而不是Webhooks 是 HTTP 回调会在平台发生特定事件时向你的指定端点发送包含事件数据的通知。主动语态优先系统发送通知而非通知由系统发送。具体名词优先你的端点收到一个 POST 请求而非接口抽象层促进了数据传输。同等准确时用常用词用 Use 而非 utilizeHelp 而非 facilitateStart 而非 initiate。短段落最多 3-4 句便于扫读、提供视觉留白、保持单主题聚焦。3.2 术语处理首次出现必定义APIApplication Programming Interface应用程序接口展开缩写CDNContent Delivery Network、CI/CDContinuous Integration/Continuous Deployment、HMACHash-based Message Authentication Code给技术术语提供上下文不要写配置 webhook 端点而写webhook 端点是我们发送通知的 URL把它配置到你的服务器。pattern-library.md 还提供了一张术语→平实英语对照词典.agents/skills/eli5/references/pattern-library.md例如 Implement→Set up、Utilize→Use、Egress→Outgoing data出站数据、Anycast→Routing to nearest server自动路由到最近位置、Propagation→Spreading, updating全球生效。同时SKILL.md 明令禁止同义词堆叠——定义过的概念不要再说也叫 X一个行为式定义足矣。3.3 隐喻库十条技术邻近隐喻ELI5 对隐喻有明确标准植根于读者可能熟悉的技术、关键概念 1:1 映射、比原概念更简单、诚实说明隐喻失效之处。参考手册维护了一个隐喻库每个都带Where this breaks down失效点声明#概念隐喻失效点1API餐厅菜单菜单列明可点的菜端点、可做的定制参数、你将得到的响应API 响应近乎瞬时API 会失败厨房缺食材需要错误处理2缓存图书馆预约台热门书放在前台快速取用缓存会过期缓存失效比隐喻复杂3负载均衡超市收银通道分散到多个通道堵了就改道负载均衡器知道服务器健康度、繁忙度可基于算法路由4Webhook门铃通知有人按门铃才提醒推送而非反复查看门口轮询门铃瞬时webhook 有网络延迟服务器宕机会导致失败像坏门铃5认证大楼门禁工牌出示工牌验证身份认证再检查可进入楼层授权数字认证用限时令牌可多因素验证6限流高速公路上匝道信号灯控制每分钟进入的车辆数限流通常是按用户独立的且按周期重置7数据库索引教科书后的索引不用读每页索引直接告诉你在哪几页数据变化时索引要更新选择索引字段是读/写速度的权衡8CDN本地仓库加州用户从加州仓库发货物理仓库库存唯一CDN 是所有地点存同一内容的副本更新需全量传播9容器海运集装箱标准化包装任意船/车/火车可运软件容器共享操作系统内核物理集装箱完全隔离10环境变量应用的设置面板不修改代码即可改变行为的配置值环境变量通常在启动前设定且按环境dev/staging/prod隔离参考手册还给出了创建新隐喻的五步法EXAMPLES_REFERENCE.md 第 858-866 行识别核心机制或目的 → 找到读者熟悉的技术邻近类比 → 关键概念 1:1 映射 → 测试是澄清了还是制造了新困惑 → 说明失效点。3.4 Why 优先的解释顺序参考手册规定内容组织顺序必须是问题Why→ 方案What→ 价值Why It Matters→ 使用场景When→ 实现How。以 webhook 为例问题构建应用时常需知道另一平台何时发生某事支付完成、上传结束、部署成功。持续轮询浪费资源并带来延迟。方案Webhook 在事件发生时立即向你的服务器推送消息。价值实时响应、节省资源、用户获得更快更新、只处理真实发生的事件。使用场景部署完成触发工作流、内容变化时更新数据库、支付成功发通知、系统间自动同步。实现创建接收通知的端点 URL → 配置要接收的事件 → 用签名验证请求来源 → 处理事件数据。理由是目的先于机制——这正是人类学习的顺序。3.5 多受众分层同一文档要同时服务不同知识水平的人参考手册给出了分层结构In Plain Language一句话人人可懂→ What It Is从基础建立理解的 2-3 段→ Why It Matters → When Youd Use This → Think of It Like隐喻然后分隔线再用For developers提供 API 引用与代码示例、For non-technical readers聚焦结果与业务影响。这与 2.1 节的给技术用户折叠区一脉相承。四、输出格式模板4.1 生成文件的完整模板当 Agent 执行完整简化时产出.eli5.md文件其结构EXAMPLES_REFERENCE.md 第 957-1108 行为# ELI5 Simplified: [原文档名] **Original:** [文件路径] **Simplified on:** [时间戳] **Sections simplified:** [章节列表] --- ## Simplification Overview **What was confusing:** - [模式 1 - 如缩写大量使用且未展开] - [模式 2 - 如假设读者已懂 HTTP 协议] **Approach taken:** - [策略 1 - 如为每个概念加一句话摘要] - [策略 2 - 如首次出现即展开所有缩写] --- ## Section: [原标题] ### Original Content [源文本原样保留格式不变] ### ⚠️ Issues Identified **Jargon术语:** [术语] - [问题所在、假设了什么] **Assumptions假设:** [假设了什么] **Unclear Logic逻辑不清:** [问题] ### ✨ Simplified Version **In Plain Language:** [无术语的一句话精炼] **What It Is:** [从基础建立的 2-3 段] **Why It Matters:** [价值主张与具体收益] **When Youd Use This:** [带语境的场景 1/2/3] **Think of It Like:** [技术邻近隐喻含完整展开] **Where this metaphor breaks down:** [诚实说明局限] **Common Pitfalls:** [误解 → 纠正] **Related Concepts:** [与已知概念的连接] --- [每个章节重复此结构] --- ## Summary Recommendations **Key Improvements Made:** [改进清单] **Patterns Noticed:** [元分析这份文档难懂的原因] ## ✅ Next Steps 1. Suggest additional improvements 2. Create a PR 3. Refine specific sections 4. Apply changes to original 5. Keep as reference该模板的关键设计是原样保留原文Original Content 区块逐字保存、格式不变——这保证了任何简化都可被审计对比事实核查有据可依。4.2 文件命名约定输入path/to/documentation.md→ 输出path/to/documentation.eli5.md输入api-reference.mdx→ 输出api-reference.eli5.mdx。.eli5后缀清晰标识简化版本同时保留原格式扩展名。仓库中的真实产出.agents/skills/eli5/recommendations/internal-dns/index.eli5.mdx正是这一约定的落地实例——它是一份针对 Internal DNS 概览页的完整改写稿保留了原文的Description、Plan、Example等所有 MDX 组件和三张 mermaid 图目标扩展比 1.89x135 → 255 行并在文末附带了完整的enhancement summary。4.3 Suggestions for Enhancement增强建议主简化完成后Agent 会追加一个增强建议章节每条建议包含六个字段行号引用、适用章节、当前做法、建议增强、为何有帮助、实现示例。参考手册给出了三个完整样例L45-52 添加双路径指令原文只有仪表盘路径建议补充 API 路径附curl -X PATCH .../settings/always_use_https请求与响应示例理由是同时服务 UI 用户与偏好代码的开发者L78-85 把技术细节移入折叠区原文把密码套件细节内联在主体解释中建议移入detailssummaryFor technical users/summary...折叠区附 TLS 1.3 AEAD 套件列表示例实现清晰的渐进披露L120-122 给出推荐默认值原文把所有加密模式Off/Flexible/Full/Full Strict等权罗列建议标出Recommended for most sites: Full (Strict)减少选择瘫痪L195-200 添加具体使用场景原文只有抽象收益陈述建议补一个黑色星期五 DDoS 攻击中真实顾客正常下单的场景化故事。何时启用该章节存在多路径机会Dashboard API、技术细节可折叠、缺少推荐默认值、抽象概念需要具体示例、渐进披露可改进、常见决策点缺指导。放置位置在Summary Recommendations之后、Next Steps之前。五、质量保障体系从检查清单到对抗性审查5.1 质量检查清单Quality Checklist参考手册规定任何简化内容定稿前必须逐项核对第 1309-1327 行技术准确性保持不变——没有改变或过度简化任何事实一句话摘要无术语地抓住本质术语被识别并解释或替换假设在 Issues 区块中被显式声明解释中Why先于What用例真实且实用隐喻关键概念 1:1 映射隐喻局限被承认常见坑确实常见不是编造的语气专业且尊重没有居高临下的措辞simplyjustobviously全程尊重读者智力。5.2 语气规则Tone Rules参考手册明令禁止居高临下的措辞Simply configure the endpoint...、Just add the webhook URL...、Obviously, youll need to...、Clearly, this requires...、As everyone knows...、Its easy to...、All you have to do is...。替代方案是尊重读者的表达To configure the endpoint, youll need to...、Add the webhook URL by...、This requires...、Heres how this works...。这与 SKILL.md 的基调一致——面向聪明但缺乏具体领域背景的读者。5.3 准确性不可妥协好的简化示例Webhooks 在指定事件发生时向你的端点 URL 发送 HTTP POST 请求。把它想成一个通知系统——我们调用你的服务器而不是你不断轮询我们的服务器。准确、清晰、有效用隐喻。坏的简化示例Webhooks 让程序之间互相交谈。过于含糊、丢失重要细节、实际没有帮助。当必须保留复杂准确性时使用渐进式披露**简化版** 限流控制你在一个时间段内能发起多少请求比如每分钟 100 次。 **更精确地说** 限流按 API key 生效采用滑动窗口重置。达到上限后 返回 429 状态码并带 Retry-After 头指示何时可以重试。这套准则与 SKILL.md 完全呼应简化意味着更清晰的语言而非降低精度如果简化后的解释在技术上是错的应该增加细微差别而不是省略它。同时 SKILL.md 特别强调 Cloudflare 特有实现可能与行业惯例不同任何净新增信息必须对照仓库中的src/content/docs/源文档核验并给出引用来源。5.4 不同内容类型的处理侧重API 文档聚焦端点目的、使用场景、发送参数解释参数用途而非仅类型、返回响应、常见用例、错误处理什么会出错通过解释参数用途、展示真实请求/响应示例、澄清常见误解来增值。架构文档聚焦被解决的问题、为何选择此方案、做出的权衡得到了什么/失去了什么、何时该架构合理、考虑过的替代方案通过解释决策理由、显式化权衡、连接业务需求来增值。代码文档聚焦代码达成什么、为何这样组织、使用的关键概念或模式、需要注意什么通过平实语言阅读指南、解释非显然的选择、展示部件如何组合来增值。5.5 对抗性审查Adversarial Review这是 SKILL.md 中定义的强制第 9 步提交前必须启动一个全新的子 Agent与当前会话隔离、不接触 ELI5 技能说明以怀疑论者身份逐条核验新增主张。审查重点是五类高风险内容简化机制描述听起来合理但机制错误的解释比原术语更糟、误导性细微差别如把 per-path 的 allow/disallow 机制说成全盘屏蔽、净新增主张每一条新信息都要有引用、Cloudflare 特有行为不得假设行业惯例适用于 Cloudflare 产品、跨类别过度概括所有记录每个请求这类量词是否真实普适。审查产出是一张带严重级别critical/high/medium/low的主张核查表每个问题必须引用证据来源。六、边界情况与处理策略参考手册为五类边界情况给出了明确策略第 1425-1553 行超长文档1000 行向用户提供四种处理选项——处理全部章节 / 聚焦指定章节列出清单/ 自动检测最复杂章节 / 分块处理如 1-10、11-20。自动检测逻辑包括计算术语密度每 100 词的术语数、统计假设指示词as you know、无解释的引用、识别没有用例或why陈述的章节优先处理复杂度得分最高的章节。已清晰的文档承认其清晰度只做小改进。明确列出要避免的行为——不添加不必要的冗长、不制造不存在的问题、不过度解释已清楚的内容、不为了有话可说而填充。产出格式是做得好的地方 小改进建议 总体评估。高技术含量内容先保准确绝不过度简化到错误分层解释High-level → How it works → Technical details加解释性散文但不改技术规格用渐进披露并明确各章节写给谁。代码密集文档不简化代码本身——代码必须保持准确不重写功能代码围绕代码添加解释性上下文这段代码做什么为什么这样组织关键理解点创建阅读指南逐段走读复杂代码。含组件的 MDX 文件聚焦散文内容、组件代码保持不动解释组件目的如CodeBlock组件显示带语法高亮和复制功能的代码除非文档本身就是讲 React/框架细节否则不深入框架实现。七、未来增强计划参考手册末尾记录了对未来迭代的规划第 1555-1619 行标注为documented for future implementation内联代码注释读取支持解析带内联文档的代码文件提取 docstring 与注释、简化注释中的技术语言、为复杂逻辑添加解释性散文、生成代码走读指南规划支持.js/.ts/.tsx/.py/.go/.rb/.java。多格式支持HTML 文档、PDF 技术论文、Confluence/Wiki 页面、OpenAPI 规范的可访问化。自动化复杂度评分术语密度每 100 词、可读性分数Flesch-Kincaid、SMOG 指数、假设检测标记假设知识的短语、上下文缺口分析识别缺失的why与when并按复杂度排序章节、聚焦高价值简化、生成复杂度报告。交互模式逐节处理并接收用户反馈、基于输入的实时精炼、迭代改进循环、不同隐喻的 A/B 测试。八、完整工作示例两份逐行对照参考手册第 1621-1786 行给出了两份完整的端到端示例展示全部要素如何组装。示例一API 文档POST /webhooks。原文档只有端点名、参数表endpoint/events/secret 三个参数及类型与响应说明简化版将其扩写为八个区块——In Plain Language设置自动通知特定事件发生时我们发送到你的服务器、What It Is对比轮询解释推送机制、Why It Matters实时更新、资源效率、可靠性、自动化、When Youd Use This部署通知、内容同步、监控、系统集成、Think of It Like门铃隐喻、Where this breaks down网络延迟与服务器宕机需要重试逻辑、Parameters Explained每个参数用行为而非类型定义endpoint 是你的服务器监听 webhook 事件的地址必须用 HTTPS、Common Pitfalls以为 webhook 100% 可靠与不验证签名两条纠正。它还特别用 RSS 类比收尾两者都推送更新但 webhook 可编程且适用于任意事件类型。示例二架构决策边缘部署架构。原文档一句话描述了利用 V8 isolates 的多租户全局分布式边缘架构简化版补上了完整论证链——Plain Language代码部署在全球服务器上用户就近响应、What It Is弗吉尼亚的服务器服务新加坡用户要跨半球往返边缘架构让请求由最近节点处理、Why It Matters速度、可靠性、规模、简单性、Think of It Like中心仓库 vs 各城本地仓库、Technical Approachisolates 微秒级启动 vs 容器 50-500ms 冷启动、Why this architecture列出评估过的三种方案传统服务器/容器 serverless/isolate 边缘并说明选择理由、Tradeoff made无任意系统库、执行时间受限为速度接受约束、Common Pitfalls假设与普通服务器相同——无持久本地存储、无后台任务期待 Node.js 兼容——实现的是 Web 标准。九、方法论在仓库中的闭环从规范到产出回顾整个体系ELI5 在 cloudflare-docs 中形成了一条完整的闭环可执行规范SKILL.md 定义了 9 步工作流接受文件→识别内容类型→施加增强约束→选择章节→分析问题→提取术语→生成对照→报告→对抗性审查、决策框架何时简化术语/加内容/点明后果/加术语气泡、18 项质量清单和 8 条反模式操作指南content-type-guide.md 提供五种内容类型的检测信号与检测决策树以及1.5-2x 保守扩展的硬约束复用模式pattern-library.md 提供术语词典、五种转换模式技术优先→收益优先、抽象→隐喻、纯步骤→多路径、字母序→按用途、代码倾倒→解释式渐进与隐喻模板详细示例本文主角 EXAMPLES_REFERENCE.md 提供逐行完整的长示例与输出模板真实产出index.eli5.mdx 是整套方法论应用在 Internal DNS 概览页上的完整成果——保留全部 MDX 组件与 mermaid 图补充了何时使用查询流程五步走三个带落地场景的用例Getting started 清单目标扩展 1.89x。整套方法论的最后一段哲学总结值得记住技术专长永远不应成为理解的门槛。每个人都值得获得清晰、准确、尊重人的文档。而 SKILL.md 的质量清单则给出了执行此哲学的落点技术准确、Why 先于 What、隐喻 1:1 映射且声明局限、不居高临下、保持 1.5-2x 的克制扩展、不重写本就正确的散文、每个简化描述的都是正确机制——因为一个听起来合理但机制错误的解释比原来的术语更糟。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考