{AIP Title} — Playbook-平芜编程栈

{AIP Title} — Playbook

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow

Airflow 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 user's objective.} ```python # PROPOSED API — not yet implemented {Speculative code based on the AIP's 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），仅供参考

{AIP Title} — Playbook