{AIP Title} — Playbook【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowAirflow version:{version}Required packages:{packages, if any beyond core}两个元信息字段各自对应一条真实的工作约束 - **Airflow version**AIP 功能往往只在新版本中可用手册必须声明适用版本。SKILL.md 定义了版本的来源规则——在 post 模式下优先从 PR diff 中搜索 versionadded:: / .. versionadded:: 指令这是 Airflow 文档 Sphinx 指令也出现在例如 [migrations-ref.rst](https://link.gitcode.com/i/b414151c970cfaa4bcefa6e5bcfbaa18) 等文档中如果 diff 中找不到才向用户询问目标版本。pre 模式下没有 PR 可查直接向用户询问。 - **Required packages**Airflow 3 将大量集成拆分为独立 provider 包见仓库 providers/ 目录下的 amazon、google、standard 等分布手册需要列出核心之外额外需要的依赖让读者在安装环节不踩坑。 紧随其后的 **Prerequisites** 章节要求写明版本要求、provider 包的安装步骤与配置前置条件。模板注释明确这一节覆盖版本要求、provider 包安装、配置前置三类信息为后文每个 recipe 的全局前提兜底。 ## 三、Overview面向实践者的动机转述 模板的 Overview 一节要求2–3 段取材自 AIP 的 motivation 章节并附有一条写作准则值得注意**Written for a practitioner, not a committee**写给实践者而不是委员会。 这与 AIP 原文的语体形成对照AIP 的动机章节论证为什么要立项而 Playbook 的 Overview 回答三个具体问题——该功能解决什么问题、此前用户处于什么状态、上线后用户的日常会发生什么变化。模板通过注释把这一改写要求固化下来保证不同 AIP 产出的手册在开头具有统一的信息密度和语体。 ## 四、双模式设计Recipes 与 User Stories 模板的主体由两个平行的章节构成分别对应 SKILL.md 定义的工作模式。模式判定规则在 [SKILL.md](https://link.gitcode.com/i/a5b570e9531d16446fd98d4c063eda33) 中命令行参数里**出现 PR URL 即进入 post-implementation 模式**以代码库中的真实实现为事实来源source of truth**没有 PR URL 则进入 pre-implementation 模式**以 AIP 规格本身为事实来源。模板的两个章节结构正是这两种模式产物差异的体现。 ### 4.1 Post-Implementation 模式Recipes 章节 模板中 Recipes 的逐条结构为 markdown ### {Recipe Title} **Goal:** {One sentence — what the user accomplishes with this recipe.} **Prerequisites:** {Anything specific to this recipe beyond the global prerequisites...} ​python {Code block — verified, adapted, or placeholder per the three-tier system.} ​ {If adapted, note below the block: Adapted from [source file path]} {Explanation: WHY this pattern works, not line-by-line narration.}四个要素各有明确职责Goal一句话说明用户借这个配方完成什么。SKILL.md的 Propose 阶段要求每个 recipe 映射到一个独立用例——若两个 API 类服务同一用例则合并若一个类服务多个用例则拆分。这一粒度规则保证手册以问题而非类为组织单位。Prerequisites只写超出全局前置条件的增量——某个 provider 包、某个配置开关、某个外部服务。代码块下方的来源标注Adapted from [source file path]是模板对改造型代码的强制溯源要求路径必须指向仓库内可验证的文件。解释段模板特别要求解释WHY this pattern works并明确禁止逐行叙述not line-by-line narration。这要求作者论证该模式为何是此场景的正确选择而不是翻译代码。4.2 Pre-Implementation 模式User Stories 章节功能尚未落地时模板切换为 User Stories 结构### {Story Title} **Goal:** {One sentence — the users objective.} ​python # PROPOSED API — not yet implemented {Speculative code based on the AIPs proposed API.} ​ {Brief explanation of what this code would accomplish and why the AIP proposes this approach.} **Open Design Questions:** - {Specific question about API ergonomics for this use case} - {Specific question about edge cases relevant to this story} - {Specific question about compatibility with existing Airflow patterns} - {Specific question about implementation feasibility or constraints}两个关键点与 post 模式形成鲜明对比强制的投机标记。SKILL.md规定 pre 模式的所有代码块首行必须包含# PROPOSED API — not yet implemented防止读者把拟议 API 当作可用接口。模板把这一注释直接写进了代码块骨架形成双重保险。开放设计问题Open Design Questions。模板要求每个 story 列出四个维度的具体问题API 易用性easy to use correctly and hard to misuse、边界情况异常输入、空分区、意外配置、与既有 Airflow 模式的兼容性catchup、backfill、动态任务映射、sensors、XCom、实现可行性。SKILL.md还加了一条质量红线问题必须针对该 story 的具体用例通用问题如错误处理怎么办)不算数。这一机制让 pre 模式手册不只是拟议 API 的使用预演而是对 AIP 作者的设计压力测试——这也是该技能存在的核心目的帮助 AIP 作者在实现前验证设计。五、三级代码块验证体系模板的诚实性机制模板中代码块注释的verified, adapted, or placeholder per the three-tier system指向 SKILL.md 中定义的三级体系这是整条工具链可信度的基石级别判定标准呈现规则Verified已验证该模式存在于代码库中源码、示例 DAG 或测试直接使用代码不加任何标记Adapted改造以新组合方式拼装已验证组件如用已验证的 mapper 搭配不同的 asset保持代码整洁块下方注明Adapted from [source file path]Unverified未验证代码库中无此模式的证据使用占位符未验证级别的标准占位形式为# TODO: Implement [description] # See: [reference or AIP section] ...三级体系把能证明什么、不能证明什么显式编码进文档格式读者看到无标记代码即知其经过代码库核实看到TODO占位即知该模式尚未在实现中落地。验证源被限定为三类——airflow-core/src/下的源码、示例 DAG 与测试文件对应仓库中的 airflow-core/src/ 与各 provider 包下的example_dags/目录。六、Not Yet Implemented未覆盖功能的显式账目模板末尾的Not Yet Implemented一节规定仅当用户在 Propose 阶段选择跳过未实现功能时才包含逐条列出被跳过的功能并各给一句取自 AIP 的一行描述若所有功能都已覆盖则整节省略## Not Yet Implemented - **{Feature name}** — {one-line description from AIP}【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考