Apache Airflow breeze 命令在 Agent 隔离环境中的权限基线配置读懂 setup-isolated-setup-install 覆盖文件【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 仓库在本地开发中强制以breeze作为唯一开发入口AGENTS.md 明令禁止在宿主机直接运行pytest/python/airflow当 Agent 工具链如 Claude Code 类编码代理接入该仓库的隔离/安全构建环境时就需要为每台机器的.claude/settings.local.json预置一份 bash 命令放行基线避免每次调用 breeze 都触发交互式审批。本文以 .apache-magpie-overrides/setup-isolated-setup-install.md 为骨架结合仓库中 breeze shim、ADR 记录与 gitignore 规则完整解析这份权限白名单的每一条目、设计动机与落地位置帮助读者理解并复现一次安装、全机可跑 breeze、危险操作仍受控的隔离开发配置。这份覆盖文件是什么Skill Override 的定位与约束Apache Airflow 仓库根目录下存在一个.apache-magpie-overrides/目录存放针对apache-magpie 框架技能framework skill的代理可读覆盖指令按被修改技能命名例如setup-isolated-setup-install.md就是覆盖setup-isolated-setup-install这一技能的文件。根据同目录的 .apache-magpie-overrides/README.md框架技能在运行时run-time会先查阅该目录再执行默认行为目录中有一个硬性规则绝不修改仓库根目录下的.apache-magpie/快照本地修改一律落在.apache-magpie-overrides/框架层面的变更则需要走 PR 回到 magpie 框架本身。setup-isolated-setup-install.md所覆盖的技能负责为当前仓库完成隔离 / 安全的 Agent 设置——即把项目特定的 Bash 权限放行清单注入到采用者的项目级本地设置文件repo/.claude/settings.local.json中。之所以是覆盖而非独立文档是因为它要在技能原本执行的 settings merge其 Golden rules → 不要静默覆盖已有 settings 文件 的目标合并行为以及Step P里对项目本地设置文件的写入基础之上做增强将下面的白名单与 Step P 已写入的沙箱allowRead/allowWrite条目合并到同一个文件中、出现在同一份 diff 里、并以同样的审批流程生效。被覆盖功能的执行目标项目级 sandbox 权限文件要让理解落到实处先厘清写入目标文件的性质。仓库根 .gitignore 中有明确声明# Per-machine project-scope Claude Code settings (sandbox-allowlist /.claude/settings.local.json也就是说settings.local.json是**项目作用域project-scope但按机器隔离per-machine**的 Claude Code 设置文件其中承载的是 sandbox 的allowRead/allowWrite/permissions.allow类放行清单该文件已被 gitignore不会进入版本库、不进入 PR diff因此不存在共享的、需要评审维护的提交版 settings 文件同仓库也不会因本次覆盖引入一个提交进版本库的项目级.claude/settings.json——覆盖文件明确说明该路径在本仓库保持 gitignored.gitignore 第 136-143 行只放行了.claude/skills/下的若干子目录其余.claude/*均被忽略。因此这份覆盖的作用是在**安装时刻install time**为每台机器播种seed一份 breeze 的权限基线而不是建立一个由所有协作者共享、共同评审的策略文件。开发者自己额外追加的每机器级放行同样存在于这份settings.local.json中本次覆盖只播种 breeze 基线不触碰其余内容。需要添加的权限清单逐条解读覆盖文件要求将下列条目逐一加入permissions.allow若该键不存在则创建。注意两条硬性约束绝不删除或重排既有条目这是一个追加式additive合并已存在的条目是 no-op什么都不做天然幂等Bash(breeze *) Bash(ANSWERyes breeze *) Bash(SKIP_BREEZE_SELF_UPGRADE_CHECK1 breeze *) Bash(SKIP_BREEZE_SELF_UPGRADE_CHECKtrue breeze *) Bash(SKIP_BREEZE_SELF_UPGRADE_CHECK breeze *) Bash(uvx *dev/breeze*) Bash(uv run *dev/breeze*) Bash(docker ps *) Bash(docker info *)这 9 条规则可以按三个维度理解分组条目覆盖的调用形态裸 breeze 调用Bash(breeze *)不带任何环境变量前缀的 breeze 命令环境变量前缀形式Bash(ANSWERyes breeze *)交互确认场景非交互终端/CI 中预置ANSWERyes让 breeze 跳过确认提示环境变量前缀形式Bash(SKIP_BREEZE_SELF_UPGRADE_CHECK1 breeze *)/true breeze */ breeze *关闭 breeze 启动时安装版本旧于源码自升级检查的三种常见写法1、true、空值在 dev/CI 脚本中被普遍使用breeze shim 的直接启动Bash(uvx *dev/breeze*)、Bash(uv run *dev/breeze*)不经~/.local/bin/breeze软链、直接用 uvx/uv 从dev/breeze目录运行 breeze 的形态只读 docker 探测Bash(docker ps *)、Bash(docker info *)环境健康检查查看容器列表与 docker 守护进程信息之所以要同时放行 env-prefixed 形式是因为仓库的 dev/CI 脚本中普遍以ANSWERyes与SKIP_BREEZE_SELF_UPGRADE_CHECK包裹 breeze 命令如果不放行这些包装过的调用仍会命中权限审批。同理uvx *dev/breeze*与uv run *dev/breeze*两条是为了覆盖从本地源码跑 breeze 的 shim 机制具体见下文 ADR 0017 一节。为什么是这些命令breeze 作为唯一入口的必然结果覆盖文件给出的理由非常直接breeze 是 Apache Airflow 所有本地开发的指定入口mandated entrypoint。仓库的 AGENTS.md 与 CLAUDE.md 中都写着同一句硬性纪律——Never run pytest, python, or airflow commands directly on the host— always usebreeze见 AGENTS.md 第 25-26 行任何测试、类型检查、文档构建、CLI 调用都必须经由 breeze 派发到容器化环境中执行例如breeze run pytest tests -xvs、breeze testing helm-tests --use-xdist、breeze run airflow dags list、breeze build-docs、breeze ci selective-check --commit-ref ref等。由此得出本白名单设计的两个推论breeze 在仓库开发流程中是高频命令。如果没有上述 allow 条目Contributor 每次敲 breeze 都会触发一次 Bash 权限审批——对于一个贡献者持续运行的命令而言是纯粹的摩擦所以要在安装时刻就播种放行把交互摩擦降到零。breeze 内部驱动 docker所以其 docker 使用已被单条 breeze 调用覆盖。白名单无需再对docker run、docker exec等一一放行——它们发生在 breeze 进程内部权限模型把一整条 breeze 命令视为一个受信边界。非破坏性边界什么仍然被拦截这是整份白名单安全性的关键覆盖文件用强措辞划定了边界只有非破坏性命令被放行breeze 本身内部驱动 dockerdocker 的使用由单条 breeze 调用覆盖加上只读的docker ps/docker info。明确不在放行范围、因此仍然走逐次提示审批prompt-gated的操作包括docker rm、docker network prune、以及任何在 breeze 工作流之外向外写入writes outside the breeze workflow的命令。可以推断这套边界的设计意图是放行受控入口 只读探测而把容器的清理、网络裁剪等不可逆副作用始终握在人类审批手中防止 Agent 在自动执行链中误删共享开发资源。支撑机制之一breeze shim 与 ADR 0017白名单中的uvx *dev/breeze*与uv run *dev/breeze*并不是任意形态而是对应仓库当前推荐的 breeze 分发方式。仓库在 ADR 0017Useuvxto run breeze from local sources 中记录旧的uv tool install -e ./dev/breeze全局单实例安装模式在多 checkout / 多 git worktree、以及 Agent 化工作流多个短期 worktree 并行、自动创建销毁下会失效——各 worktree 的 breeze 版本不同、全局软链互相覆盖。ADR 0017 的决策是改用shim 脚本由 scripts/tools/setup_breeze一次性、按机器运行把一个小脚本写入~/.local/bin/breeze该脚本对当前所在 git worktree 执行exec env AIRFLOW_ROOT_PATH${breeze_root} SKIP_BREEZE_SELF_UPGRADE_CHECK1 \ uvx --from ${breeze_root}/dev/breeze --quiet breeze $其中breeze_root的解析顺序是当前 git worktree存在dev/breeze→ 环境变量$AIRFLOW_REPO_ROOT指向的 Airflow worktree发布文档会导出它供发布流程从非 Airflow 目录如 asf-dist SVN 检出区调用→ 安装时刻setup_breeze运行所在 worktreebaked-in 兜底。三条解析路径都仅用于当前目录不在 Airflow worktree 内的场合永远不会覆盖真实 worktree从而保住每 worktree 隔离。setup_breeze 本体scripts/tools/setup_breeze 第 31-58 行把这段 shim body 连同# breeze-shim-version: N标记写入~/.local/bin/breeze并检测/拒绝与历史遗留的uv tool install安装并存。这正是覆盖文件中那两条uvx/uv run规则存在的原因——shim 的真实执行形态就是uvx --from worktree/dev/breeze ... breeze若 Agent 直接调用了这种形态例如绕开 PATH 软链排查问题白名单必须能兜住它。两条SKIP_BREEZE_SELF_UPGRADE_CHECK前缀规则的动机也可以在此处得到源码印证shim 每次都注入SKIP_BREEZE_SELF_UPGRADE_CHECK1因为 uvx 环境随pyproject.toml/uv.lock变化自动重建源码侧的自升级提示无意义仓库各脚本中又以true、空值等变体出现故三种写法全部放行。支撑机制之二落地位置与 gitignore 的证据闭环整套配置的无共享文件主张在仓库中是可验证的写入目标是/.claude/settings.local.json在 .gitignore 中被显式忽略Per-machine project-scope Claude Code settings 注释下的/.claude/settings.local.json一行证明该文件只存在于 Contributor 本机仓库不维护任何提交版的项目级.claude/settings.json——.claude/*整体被 gitignore仅放行.claude/skills/下若干技能子目录佐证覆盖文件不引入 committed settings.json的说法因此这次播种属于一次性、逐机器行为它只向既有的settings.local.json追加breeze 基线条目Contributor 自己添加的其他 per-machine 放行不受影响后续若再次运行安装已存在条目为 no-op不会重复或覆盖。需要特别说明的适用范围限制这份覆盖文件的语义依赖apache-magpie 框架技能体系技能在运行时会先读取.apache-magpie-overrides/再决定行为且放行的 bash 形态breeze、uvx/uv、docker ps/info针对的是 Airflow 仓库breeze 唯一入口 docker 容器化测试这一具体开发模型。若读者在其他不采用 breeze 入口、或没有容器化测试约束的仓库中复用该清单应重新评估各条目的必要性而非照搬。小结setup-isolated-setup-install.md看似只是一小段权限清单实则是 Apache Airflow breeze 唯一入口 Agent 隔离开发两条工程决策的汇合点入口纪律AGENTS.md / CLAUDE.mdhost 上绝不直接跑 pytest/python/airflow决定了 breeze 是高频命令必须免审批分发机制ADR 0017 setup_breeze决定了放行清单必须覆盖uvx/uv run与SKIP_BREEZE_SELF_UPGRADE_CHECK前缀三种变体安全边界只放行 breeze 与只读 docker 探测docker rm、网络裁剪等一律留在审批态决定了自动化可以放手跑测试却无法破坏环境落地形态.gitignore 中 gitignored 的settings.local.json保证了整份基线是每机器追加式播种既不产生需要评审的共享文件也不触碰开发者自己的放行项。对于希望让 Agent 在 Airflow 仓库中流畅、安全地执行本地开发任务的团队这份覆盖文件本身就是一个可复用的最小放行面参考模板入口命令 其分发 shim 的等价形态 只读环境探测其余一律保持人工审批。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考