ce-commit-push-pr

Git 提交、推送和 PR

**询问用户：**使用当前工具列表中已有的宿主阻塞式提问工具（按能力匹配，而非按宿主特有名称匹配）。工具出现在当前列表中，即证明该工具存在；切勿调用面向用户的提问工具来确认它是否存在。如果列表中有匹配的工具但尚未加载，请使用宿主的工具发现原语加载该能力——不要搜索其他宿主的工具名称。只有在列表中没有此类工具，或实际提问调用出错时，才改为在聊天中询问；绝不要悄悄跳过提问。

模式

• 仅描述——用户只想要一段描述（“撰写／起草 PR 描述”“描述此 PR”、粘贴的 PR URL 或编号）。仅运行步骤 4 并输出结果。只有在用户提出要求时才应用。传入任何粘贴的 PR 引用，以便 Pre-A 解析范围。
• 更新描述——刷新或重写现有 PR 的描述，不涉及提交或推送意图。按下文的 Context 规则确认 PR 是否存在：退出码为 0 且结果为 [] 表示“没有开放的 PR”（告知用户并停止）；非零退出码表示未知（解决身份验证或连接问题，然后在确认 PR 是否存在之前停止）。存在开放的 PR 时，针对该 URL 在 PR 模式下运行步骤 4，然后运行步骤 5 进行预览、确认，并通过 gh pr edit 应用。
• 完整工作流——其他情况：运行步骤 1-5。如果意图或偏好要求采用堆叠式 PR，则改用堆叠模式。

mode:pipeline 修饰符，由 lfg 等编排调用方设置。以非交互方式运行解析出的模式，并抑制所有阻塞式提问。每个被抑制的提问都采用保守的默认值：不重写现有 PR、保留分支、无法解析基础分支时停止而不是猜测，并直接应用描述更新预览，因为该调用即表示应用意图。流水线堆叠模式仅使用此次调用中的意图和范围，并在交接时传递处理姿态。

堆叠模式（选择启用）

仅在选择启用时使用。 仅当意图或长期偏好要求采用多 PR 堆叠时进入此模式。明确提出堆叠请求属于必要意图——不要将其重新解读为带自定义 --base 的单个 PR。不要主动建议采用 PR 堆叠。如果用户没有提出此要求，拒绝无意义的堆叠（只有一个逻辑变更、人为拆分），并采用单个 PR。

在堆叠模式下，步骤 3 之前加载 references/stack-submit.md，并且仅遵循其中的探查、拓扑结构和回顾构建流程；该逐层提交流程将取代常规步骤 3。不要在此处提交。步骤 5 负责提交、处理 gh stack CLI 依赖项和遗留事项，以及交接姿态：默认使用 posture:stack-ready，只有在明确提出落地意图时才使用 posture:stack-land，并从最底部的开放非草稿 PR 开始。不要在此技能的参数提示中添加 posture:。

上下文

请在步骤 1 之前阅读 references/context.md。 该文件定义了命令表、退出代码的含义、分叉和分离 HEAD 陷阱，以及步骤 1-2 使用的分支和 PR 判定规则。其中两条规则也适用于此处。绝不询问是否要创建分支：分离 HEAD，或在默认分支上已有改动时，都要创建分支；若默认分支上没有改动，则报告并停止。对于约定式提交，存在歧义时默认使用 fix: 而非 feat:，除非用户另有要求。

运行过程受三条规则约束。

每次 git 和 gh 探查都必须单独以 argv 形式调用，收集和重新验证时均如此，且其退出状态决定控制流。参考文件说明了原因，并列出了此技能固定使用的两种组合操作方案。

探查输出只是快照。 在每项重要操作之前，重新验证分支、远程仓库和 PR 状态：步骤 3 推送前，步骤 5 创建前。

只有针对基础仓库的查询返回退出码为 0 的 []，才表示“没有待处理 PR”。 非零退出码表示未知，绝不表示“没有”。在分叉仓库检出时，使用 -R 指定基础仓库，并且只传递分支名称，因为 --head <owner>:<branch> 会悄无声息地返回 []。如果有结果，不要盲目选取索引 0：匹配 head 所有者和分支；若匹配结果不唯一，则停止。记下该条目的 URL 和正文——步骤 5 根据 URL 选择已有 PR 路径，步骤 4 重写已有正文。

构件根目录

启用归档时，只解析一次 <root>：它会在 <root>/explainers/ 下写入说明文档。

在组合任何构件路径之前，解析 CE 构件根目录 <root>。

• 读取 <repo-root>/.compound-engineering/config.yaml 中的 docs_root（<repo-root> = git rev-parse --show-toplevel）。不要从 config.local.yaml 读取。未设置时，<root> 恰好与之前一样为 docs。
• 验证已设置的值：它必须是仓库内的相对目录，经过真实路径和符号链接解析后仍位于仓库内，且既不能是仓库根目录，也不能位于 .git/ 下。否则停止并报错，指出 docs_root 及其值——绝不回退到 docs。
• 使用 <root> 作为唯一构件位置：若不存在则创建它；每个路径都组合为 <root>/<subdir>，并使用此技能自身的子目录；绝不同时读取 docs。

步骤 3：提交并推送

请阅读 references/commit-and-push.md，了解提交／推送机制，以及通过 references/branch-creation.md 处理默认分支的方式。如果堆栈模式已提交其各层，则跳至步骤 4；步骤 5 会提交这些内容。

项目发布门槛。 发布提交之前，从项目当前生效的说明和已纳入上下文的约定，以及适用于已提交路径的任何其他作用域说明中，确定所有适用的推送前或可供审查要求。只有针对即将发送的确切提交状态有效的证据才算满足要求；否则，在外部写入之前停止，并报告缺失或失败项。如果没有此类要求，则继续。

绝不使用 git add -A 或 git add .。在 add 和 commit 时都明确列出文件，以免包含无关的暂存文件。遵守 exclude:<paths>：保留这些文件并报告。

步骤 4：编写 PR 标题和正文

必须完整阅读 references/pr-description-writing.md——该文件定义标题和正文的内容规则，包括重写时保留现有 Related: / Fixes 的规则。随后阅读 references/compose.md，以确定编写前需要做出的三项判断：证据判断；教学判断，其中 pr_teaching_section 默认开启，pr_teaching_archive 默认关闭，且只有启用状态（非注释）的键才会改变任一设置；以及品牌判断，除非本次调用携带 branding:on，或用户在此提示中要求使用 Compound Engineering 品牌，否则品牌设置为关闭。

如果步骤 1 找到了现有 PR，则将其 URL 传给步骤 4，以便 PR 模式获取现有正文。

第 5 步：应用并报告

阅读 references/apply-and-handoff.md，了解应用、预览、归档和交接。执行 gh pr create 前，重新检查 PR 是否已存在：匹配的 PR 走已有 PR 路径，退出码为 0 且结果为 [] 时创建，非零退出码则阻止创建。通过 --body-file <path> 传递正文，绝不能使用标准输入——gh 即使正文为空也会以 0 退出。

在此处判定是否完成。 交互式完整工作流或流水线栈提交，只有在 ce-babysit-pr 接管已发布 PR 的后续跟进后，才算完成。仅报告 PR URL 不算成功。加载被调用方以选择监控模式。如果在此会话中运行它，请继续执行，直到其停止条件允许最终报告。

只有 babysit:off、CE 配置中的 auto_babysit: false，或 references/apply-and-handoff.md 中的“不要触发”情况可以跳过。其他监控方式都不能替代：包括 ci-watcher、gh pr checks --watch、手动编写的轮询，以及“稍后再做”。如果无法加载或启动 ce-babysit-pr，请停止并报告该事项受阻。