ce-pr-description

CE PR 描述

生成符合 Conventional Commits 风格的标题和价值优先的正文，用于描述拉取请求的工作内容。返回结构化的 {title, body_file} 供调用方应用——此技能不会调用 gh pr edit 或 gh pr create，也不会请求交互式确认。

为什么单独设立此技能：多个调用方需要复用相同的写作逻辑，而不需要 ce-commit-push-pr 中面向单个 PR 的交互式脚手架。ce-pr-stack 的拆分工作流会批量逐层运行此技能；ce-commit-push-pr 则会在完整流程和刷新模式路径中运行此技能。提取出来后，写作原则就只有一个可信来源。

命名理由： 使用 ce-pr-description，而不是 git-pr-description。堆叠和创建 PR 都是 GitHub 功能；名称中的“PR”指的是 GitHub 产物。使用 ce- 前缀符合所有技能的插件命名约定。

---

输入

输入是自由格式的提示。将其解析为两部分：

• PR 引用（如果存在）。 以下任一形式均视为有效：完整的 GitHub PR URL（https://github.com/owner/repo/pull/NN）、pr:<number> 或 pr:<URL>、单独的井号形式（#NN），或仅由数字组成的参数（561）。提取 PR 引用，并将参数的其余部分视为引导文本。
• 其他所有内容均为引导文本（例如“强调基准测试”或“把性能方面写好”这样的“重点”提示）。它可以与 PR 引用组合，也可以单独出现。

无需遵循特定语法——将参数视为自然语言，并识别其中出现的 PR 引用。如果没有 PR 引用，则默认描述当前分支。

模式选择

调用方传入的内容	模式
没有 PR 引用（参数为空或只有引导文本）	当前分支模式——描述 HEAD 相对于仓库默认基分支的提交
有 PR 引用（URL、pr:、#NN 或单独的数字）	PR 模式——描述指定的 PR

引导文本始终为可选内容。如果存在，请将其与基于差异内容的叙述结合；不要让它凌驾于价值优先原则之上，也不要编造差异内容无法支持的信息。

可选的 base:<ref> 覆盖项（仅限当前分支模式）。 如果调用方已知目标基分支（例如，ce-commit-push-pr 已检测到 origin/develop 或 origin/release/2026-04 为目标），则可以传入 base:<ref>，明确指定基分支。该引用必须能在本地解析。此项会覆盖当前分支模式下的自动检测；PR 模式会忽略它（PR 已通过 baseRefName 指定自己的基分支）。大多数调用无需此项——自动检测（现有 PR 的 baseRefName → origin/HEAD）已涵盖常见情况。

示例：

• ce-pr-description → 当前分支，无重点，自动检测基分支
• ce-pr-description emphasize the benchmarks → 当前分支，重点 =“强调基准测试”
• ce-pr-description base:origin/develop → 当前分支，基分支固定为 origin/develop
• ce-pr-description base:origin/develop emphasize perf → 同上 + 重点
• ce-pr-description pr:561 → PR #561，无重点
• ce-pr-description #561 do a good job with the perf story → PR #561，重点 =“把性能方面写好”
• ce-pr-description https://github.com/foo/bar/pull/561 emphasize safety → foo/bar 中的 PR #561，重点 =“强调安全性”

输出

返回包含两个字段的结构化结果：

• title——符合 conventional-commit 格式：type: description 或 type(scope): description。少于 72 个字符。根据意图选择 type（feat/fix/refactor/docs/chore/perf/test），而非根据文件类型。选择最具体且有用的 scope（技能或 Agent 名称、CLI 区域或共享标签）；如果没有单一标签能让描述更清晰，则省略。
• body_file——OS 临时文件的绝对路径（通过 mktemp 创建），其中包含遵循以下写作原则的正文 Markdown。不要在返回结果中直接输出正文。

调用方决定是否通过 gh pr edit、gh pr create 应用更改，或直接丢弃；调用方会从 body_file 读取正文（例如，--body "$(cat "$BODY_FILE")"）。此技能本身不会调用这些命令。无需清理——mktemp 文件存放在 OS 临时存储中，由 OS 按自身计划回收。

---

此技能不会做什么

• 不会交互式请求确认。如果 diff 对某些重要事项存在歧义（例如，重点提示与实际更改冲突），应在返回结果中指出歧义，或告知调用方——不要直接提示用户。
• 不会切换分支。当前分支模式描述用户当前检出分支的 HEAD；PR 模式描述指定的 PR。两种模式都不会检出其他分支。
• 不会编写对比并请求确认的叙述（“这是自上一版本以来的更改”）。描述应说明最终状态；对比并请求确认的表述由调用方负责。
• 不会通过 gh pr edit 或 gh pr create 自动应用更改。返回结果后即停止。

交互式搭建流程（确认提示、对比并请求确认、应用步骤）由调用方负责。

---

步骤 1：解析 diff 和提交列表

解析输入（参见上文的输入），并根据所选模式分支处理。

当前分支模式（未提供 PR 引用时的默认模式）

按以下优先级确定比较基准：

1. 调用方提供的 base:<ref>——如果存在，则原样使用。调用方确认这是正确的基准。该 ref 必须能在本地解析。
2. 现有 PR 的 baseRefName——如果当前分支在此仓库中已有打开的 PR，则使用该 PR 的基准。这可处理目标分支并非默认分支的功能分支（例如 develop），前提是 PR 已打开。
3. 仓库默认分支（origin/HEAD）——对于尚无 PR 且调用方未提供基准的分支，使用此项作为回退。

# Detect current branch (fail if detached HEAD)
CURRENT_BRANCH=$(git branch --show-current)
if [ -z "$CURRENT_BRANCH" ]; then
  echo "Detached HEAD — current-branch mode requires a branch. Pass a PR reference instead."
  exit 1
fi

# Priority: caller-supplied base: > existing PR's baseRefName > origin/HEAD > origin/main
if [ -n "$CALLER_BASE" ]; then
  BASE_REF="$CALLER_BASE"
elif EXISTING_PR_BASE=$(gh pr view --json baseRefName --jq '.baseRefName'); then
  BASE_REF="origin/$EXISTING_PR_BASE"
elif DEFAULT_HEAD=$(git rev-parse --abbrev-ref origin/HEAD); then
  BASE_REF="$DEFAULT_HEAD"
else
  BASE_REF="origin/main"
fi

当路径“未配置”时，gh pr view 和 git rev-parse --abbrev-ref origin/HEAD 都会以非零状态码退出；elif 链根据退出码而非被抑制的 stderr 来执行。PR 不存在或 origin/HEAD 无法解析时产生的 stderr 仅供参考，可以接受。

如果 $BASE_REF 无法在本地解析（git rev-parse --verify "$BASE_REF" 失败），调用方（或用户）需要先获取它。应优雅退出并显示 "Base ref $BASE_REF does not resolve locally. Fetch it before invoking the skill."——不要尝试恢复。

收集 merge base、提交列表和完整 diff：

MERGE_BASE=$(git merge-base "$BASE_REF" HEAD) && echo "MERGE_BASE=$MERGE_BASE" && echo '=== COMMITS ===' && git log --oneline $MERGE_BASE..HEAD && echo '=== DIFF ===' && git diff $MERGE_BASE...HEAD

如果提交列表为空，则报告 "No commits between $BASE_REF and HEAD" 并优雅退出——没有内容需要描述。

如果在步骤 1 中找到现有 PR，还要捕获其正文，以便在步骤 3 中保留证据。

PR 模式（当输入包含 PR 引用时）

将引用规范化为 gh pr view 接受的形式：纯数字（561）、完整 URL（https://github.com/owner/repo/pull/561），或从 pr:561 或 #561 中提取的数字。gh pr view 的位置参数接受纯数字、URL 和分支名称，不接受 owner/repo#NN 这种简写形式。对于没有 URL 的跨仓库数字引用，调用方应使用 -R owner/repo；此技能接受完整 URL 作为最简单的跨仓库路径，大多数调用方也会使用这种方式。

gh pr view <pr-ref> --json number,state,title,body,baseRefName,baseRefOid,headRefName,headRefOid,headRepository,headRepositoryOwner,isCrossRepository,commits,url

关键 JSON 字段：headRefOid（PR head SHA，优先于从 commits 中按索引取值）、baseRefOid（基础分支 SHA）、headRepository + headRepositoryOwner（PR 源代码仓库）、isCrossRepository。不存在 baseRepository 字段——基础仓库就是 gh pr view 所查询的仓库。

如果返回的 state 不是 OPEN，则报告 "PR <number> is <state> (not open); cannot regenerate description"，并正常退出，不输出内容。期望获得 {title, body_file} 的调用方必须处理此空结果。

通过解析 URL 中的 <owner>/<repo> 路径段，并与 git remote get-url origin 进行比较（去除 .git 后缀；处理 [email protected]:owner/repo 和 https://github.com/owner/repo 两种格式），确定 PR 是否位于当前工作目录所属的仓库中。 如果 URL 中的仓库与 origin 的仓库匹配，则使用本地 Git 路径（情况 A）；否则使用仅 API 路径（情况 B）。纯数字和 #NN 格式默认指向当前仓库 → 情况 A。

情况 A → 情况 B 回退： 即使 URL 中的仓库与 origin 匹配，本地克隆也可能无法使用此 PR 的引用——例如浅克隆、分离状态下缺少基础分支、离线、身份验证问题或 GHES 特有问题。如果情况 A 中的 fetch 或 git merge-base 失败，则回退到情况 B，而不是让此技能失败。在面向调用方的输出中注明已回退。

情况 A — PR 位于当前仓库中：

直接从上面的 JSON 响应中的 headRefOid 读取 PR head SHA。通过一次调用获取基础引用和 head SHA（如果引用已在本地，fetch 操作是幂等的）：

PR_HEAD_SHA=<headRefOid from JSON>
git fetch --no-tags origin <baseRefName> $PR_HEAD_SHA

在后续命令中使用显式的 $PR_HEAD_SHA，可避免 FETCH_HEAD 的多引用排序问题（git rev-parse FETCH_HEAD 只返回第一个获取的引用的 SHA，这会导致多引用 fetch 悄然出错）。

MERGE_BASE=$(git merge-base origin/<baseRefName> $PR_HEAD_SHA) && echo "MERGE_BASE=$MERGE_BASE" && echo '=== COMMITS ===' && git log --oneline $MERGE_BASE..$PR_HEAD_SHA && echo '=== DIFF ===' && git diff $MERGE_BASE...$PR_HEAD_SHA

如果显式 SHA fetch 被拒绝（在 GitHub 上很少见，但某些 GHES 配置可能会禁止获取非 tip SHA），则回退到获取 refs/pull/<number>/head，并根据 pull-ref 模式从 .git/FETCH_HEAD 中读取 PR head SHA：

git fetch --no-tags origin "refs/pull/<number>/head"
PR_HEAD_SHA=$(awk '/refs\/pull\/[0-9]+\/head/ {print $1; exit}' "$(git rev-parse --git-dir)/FETCH_HEAD")

情况 B — PR 位于其他仓库中：

完全跳过本地 Git。从 API 读取 diff 和提交列表：

gh pr diff <pr-ref>
gh pr view <pr-ref> --json commits --jq '.commits[] | [.oid[0:7], .messageHeadline] | @tsv'

使用相同的分类、框架构建和撰写流程。在面向调用方的输出中注明使用了 API 回退。

同时，保存现有 PR 正文，以便在步骤 3 中保留证据（两种情况均适用）。

---

步骤 2：撰写前对提交分类

扫描提交列表，并对每个提交进行分类：

• 功能提交——实现 PR 的目标（新功能、有意进行的重构、设计更改）。这些提交决定描述内容。
• 修补提交——迭代过程中的工作（代码审查修复、lint 修复、测试修复、rebase 冲突解决、样式清理）。读者无需了解这些提交。

确定描述篇幅时，在脑中扣除修补提交：一个包含 12 个提交、其中 9 个是修补提交的分支，实际上是一个包含 3 个提交的 PR。

Step 3：决定是否提供证据

根据完整的分支差异，判断是否可以采集证据。

可以提供证据的情况：差异改变了可观察的行为，且可通过工作区演示，例如 UI、CLI 输出、可运行代码中的 API 行为、生成的构件或工作流输出。

无法提供证据的情况：

• 仅涉及文档、Markdown、变更日志、发布元数据、CI/配置、测试，或纯内部重构
• 行为依赖于无法获取的凭据、付费或云服务、机器人令牌、仅部署环境提供的基础设施，或未提供的硬件

此技能不会提示用户采集证据。判断逻辑如下：

1. PR 模式调用（任何形式：纯编号、#NN、pr:<N> 或完整 URL，即任何可解析为现有 PR 且已读取其正文的输入），并且现有正文包含带有图片嵌入的 ## Demo 或 ## Screenshots 部分：除非引导文本要求更新或删除，否则原样保留。将保留的区块包含在返回的正文中。无论调用方使用哪种输入形式，此规则都适用；关键在于 PR 是否存在，以及是否已读取其正文。
2. 当前分支模式或不包含证据区块的 PR 模式：完全省略证据部分。如果调用方想要采集证据，应单独调用 ce-demo-reel 并插入结果，或者在采集后使用更新的引导文本要求此技能重新生成。

不要将测试输出标记为 “Demo” 或 “Screenshots”。任何保留的证据区块都应放在 Compound Engineering 徽章之前。

---

Step 4：确定叙述框架，再评估篇幅

明确 PR 的叙述框架：

1. 之前：有什么故障、限制或无法实现？（一句话。）
2. 之后：现在可以实现什么，或有哪些改进？（一句话。）
3. 范围说明（仅适用于 2 个或更多看起来可独立拆分的事项）：这些事项为什么要一起提交？（一句话。）

这个框架将作为开篇。对于小型且简单的 PR，仅“之后”的句子就可以构成完整描述。

---

Step 5：评估变更规模

评估规模（文件数、差异量）和复杂度（设计决策、权衡、跨领域关注点），以选择描述深度：

变更类型	描述方式
小型且简单（错别字、配置、依赖升级）	用 1-2 句话，不加标题。少于约 300 个字符。
小型但不简单（错误修复、行为变更）	简短叙述，约 3-5 句话。除非涉及 2 个不同的关注点，否则不加标题。
中型功能或重构	先说明叙述框架（之前/之后/范围），再说明变更内容及原因。指出设计决策。
大型或具有重要架构意义	叙述框架 + 最多 3-5 项设计决策说明 + 1-2 句话的测试总结 + 关键文档链接。目标约 100 行，最多 150 行。对于包含许多机制的 PR，使用 Summary 级别的表格列出这些机制；不要为每个机制创建一个 H3 子章节。审阅者关注的是决策，而非清单，细节由差异和规格文件承载。如果发现自己写了 10 个以上的子章节，请合并为表格。
性能改进	如有数据，提供改进前后的测量结果。使用 Markdown 表格效果很好。

拿不准时，宁可写得更短。让描述的分量与变更的分量相匹配。大型 PR 需要更有选择性，而不是更多内容。

---

Step 6：遵循写作原则

写作风格

如果仓库上下文中记录了风格偏好，请遵循。否则：

• 使用主动语态。不要使用破折号或 -- 替代形式；改用句号、逗号、冒号或括号。
• 句子长短要有变化。不要连续写 3 个长度相似的句子。
• 不要先提出一个观点，紧接着又解释它。相信读者能够理解。
• 使用通俗英语。可以使用技术术语，但不要使用商业套话。
• 不要使用填充语：“值得注意的是”“重要的是”“本质上”“为了”“利用”“运用”。
• 数字用阿拉伯数字表示（“3 个文件”），不要拼写成单词（“三个文件”）。

编写原则

• 突出价值：开篇说明现在可以实现什么，或什么问题已得到修复，而不是描述改动了什么。更隐蔽的问题是先讲实现机制（“将硬编码的捕获代码块替换为分层技能”），而不是先讲结果（“证据捕获现在适用于 CLI 工具和库，不再局限于 Web 应用”）。
• 不要让开篇段落孤立：如果描述中任何位置使用了 ## 标题，开篇内容也必须放在标题下（例如 ## Summary）。对于没有分节的短描述，直接使用段落即可。
• 描述最终结果，而非过程：描述应涵盖最终状态，而不是实现过程。不要写迭代历史、调试步骤、开发期间出现的中间失败，也不要写开发期间发现并修复的 Bug。重新生成已有 PR 的描述时也一样：应根据当前状态重写，而不是记录自上个版本以来的改动。例外：对理解设计选择至关重要的过程细节。
• 提交记录冲突时，以最终差异为准：提交列表只是辅助信息，并非事实来源。如果提交记录描述了后来被修改或撤销的中间步骤，应根据整个分支的差异描述最终状态。
• 解释不明显之处：如果差异本身已能说明问题，就不要复述。应把篇幅用于解释差异中看不出来的内容：为何采用这种方案、舍弃了哪些方案，以及审核者应留意什么。
• 结构要有助于理解：标题、项目符号和表格应服务于理解，而非必备模板。
• 用 Markdown 表格呈现数据：前后对比、性能数字或选项权衡都很适合用表格表达。
• 不要保留空章节：如果某个章节不适用，就省略。不要写“N/A”或“None”。
• 测试计划——仅在不明显时添加：当测试需要审核者不易想到的边缘情况、难以验证的行为或特定设置时，应包含测试计划。若唯一有用的建议只是“运行测试”，则省略。如果分支新增了测试文件，应说明这些文件覆盖的内容。
• 不要添加 Commits 章节：GitHub 已在单独的标签页中显示提交列表。在 PR 正文中添加 Commits 章节只是重复信息，没有提供额外背景。除非需要说明提交的顺序或发布理由，否则应省略。
• 不要添加 Review / process 章节：不要添加描述审核者应如何审核的章节（例如检查清单或流程项目）。流程信息无助于审核者评估代码。对于需要仔细检查的特定非显而易见之处，应直接在相关改动旁说明。

可视化沟通

仅当变更在结构上足够复杂、以至于审阅者难以仅凭文字还原思维模型时，才加入可视化辅助。

核心区别——结构与并行变化：

• 当变更具有拓扑结构时（包含有向关系的组件，例如调用、流转、依赖、状态转换和数据路径），使用 Mermaid 图。图表能清楚表达“A 与 B 通信，B 与 C 通信，C 不会反向与 A 通信”，而表格无法做到。
• 当变更具有单一形态的并行变化时（N 个事物拥有相同属性，但属性值不同），使用 Markdown 表格。表格能清晰表达“选项 1 的成本为 X，选项 2 的成本为 Y，选项 3 的成本为 Z”。

架构变更几乎总是涉及拓扑结构（组件 + 边），所以 Mermaid 通常是正确选择——“相互作用的组件”表格会丢失边，变成一份平面列表。表格仅用于真正并行的数据：变更前后测量值、选项权衡、标志矩阵、配置枚举。

适合加入可视化的情况（架构／流程优先使用 Mermaid，而非表格）：

PR 变更……	可视化辅助
涉及 3 个或更多相互作用组件的架构变更（这些组件之间存在有向关系——谁调用谁、谁拥有何物、哪个技能委派给哪个技能）	Mermaid 组件图或交互图。不要用表格替代——表格无法显示边。
存在不明显顺序的多步骤工作流或数据流	Mermaid 流程图
存在 3 个或更多状态且转换并非简单直接的状态机	Mermaid 状态图
涉及 3 个或更多相关实体的数据模型变更	Mermaid ERD
前后性能或行为测量值对比（相同指标，不同数值）	Markdown 表格
选项或标志的权衡（对不同变体评估相同属性）	Markdown 表格
功能矩阵／兼容性网格	Markdown 表格

不确定时，问自己：“这些信息是有边（A → B），还是有行（属性 × 变体）？” 有边 → Mermaid。有行 → 表格。架构几乎必然有边。

适合省略所有可视化的情况：

• 范围仅需“1-2 句话”即可说明
• 文字已经表达清楚
• 图表只是以视觉形式复述差异
• 机械性变更（重命名、依赖升级、配置、格式调整）

格式细节：

• Mermaid（拓扑结构的默认选择）。通常使用 5-10 个节点；对于真正复杂的变更，最多使用 15 个节点。使用 TB 方向。源码应易于阅读，以便作为替代说明。
• ASCII 图用于需要在框内加入丰富内容的注释流程。宽度最多 80 列。
• Markdown 表格仅用于并行变化数据。
• 将可视化放在相关内容处，不要单独设节。
• 当文字说明与可视化冲突时，以文字说明为准。

加入图表前，请根据变更内容核实生成的图表。

编号和引用

PR 描述中的列表项前不要加 #——GitHub 会将 #1、#2 识别为问题引用并自动创建链接。

引用实际的 GitHub 问题或 PR 时，请使用 org/repo#123 或完整 URL。除非已核实，否则不要只写 #123。

应用重点提示

如果提供了 focus: 提示，请将其与基于差异得出的叙述结合起来。将重点提示视为引导，而非覆盖：不要编造差异内容不支持的信息，也不要仅因为重点提示未提及某项重要内容就将其省略。如果重点提示与差异存在实质性冲突（例如，重点提示要求“包含基准测试”，但差异中没有基准测试），请以调用方可见的方式指出冲突（留下简短的行内备注或告知调用方），不要编造内容。

---

Step 7：撰写标题

标题格式：type: description 或 type(scope): description。

• 类型按意图选择，而非按文件扩展名或差异形态选择。新增功能用 feat，修复缺陷用 fix，保持行为不变的改动用 refactor，仅修改文档用 docs，工具或维护工作用 chore，性能优化用 perf，仅修改测试用 test。如果 fix 和 feat 看起来都适用，默认选 fix：修复异常或缺失行为的改动即使通过添加代码实现，也属于 fix。只有用户此前无法实现的功能才用 feat。用户可以另行指定。
• 范围（可选）是最精确且有用的标签：技能或 Agent 名称、CLI 功能区，或共享功能区。如果没有单一标签能让标题更清晰，就省略。
• 描述使用祈使语气、小写，总长度少于 72 个字符。末尾不加句号。
• 如果仓库最近的提交中能看到标题惯例，请遵循该惯例。

破坏性变更使用 !（例如 feat!: ...），或在正文中使用 BREAKING CHANGE: 页脚说明。

---

Step 8：撰写正文

按以下顺序组织正文：

1. 开篇 —— 第 4 步的叙述框架，深度按第 5 步选择。如果描述中其他位置使用了 ## 标题，则在标题下撰写（例如 ## Summary）；否则直接写一段文字。
2. 正文分节 —— 仅保留对本次改动有价值的分节：改动内容及原因、设计决策、数据表格，以及在复杂度需要时加入的可视化辅助。完全省略空分节。
3. 测试计划 —— 仅在按写作原则来看不言自明时才添加；否则省略。
4. 证据块 —— 仅包含第 3 步中保留的区块（如有）。不要编造或使用占位内容。
5. Compound Engineering 徽章 —— 添加徽章页脚，并以 --- 分隔。如果现有正文（针对 pr: 输入）已包含徽章，则跳过。

徽章：

---

[![Compound Engineering](https://img.shields.io/badge/Built_with-Compound_Engineering-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
![HARNESS](https://img.shields.io/badge/MODEL_SLUG-COLOR?logo=LOGO&logoColor=white)

Harness 查询表：

Harness	LOGO	COLOR
Claude Code	claude	D97757
Codex	（省略 logo 参数）	000000
Gemini CLI	googlegemini	4285F4

模型标识： 将空格替换为下划线。如果上下文窗口和思考级别已知，则附加到括号中。示例：Opus_4.6_(1M,_Extended_Thinking)、Sonnet_4.6_(200K)、Gemini_3.1_Pro。

---

Step 8b：压缩

将正文写入临时文件之前，重新阅读整理好的正文，并按以下要求精简：

• 如果正文分节重复了 ## Summary 中已有的内容，请删除。Summary 和差异内容应足以让读者了解改动。
• 如果“Testing”或“Test plan”超过 2 段，请压缩成项目符号。
• 如果“Commits”分节列出了提交日志，请删除——GitHub 会在单独的标签页中显示这些内容。
• 如果“Review”或流程相关分节罗列了审阅步骤，请删除。确实不明显的审阅提示应移到相关改动的描述中。
• 如果正文包含 5 个或更多 H3 子节，且每节各自描述一种机制，请将其合并到一个标题下，每种机制占表格的一行。仅为 2–3 项真正的设计决策保留文字说明形式的 H3 重点说明。
• 如果正文长度超出目标表格所示范围 30% 以上，请将最长的非 Summary 分节压缩一半。

价值优先检查。 重新阅读 Summary 的第一句话。如果它描述的是内容如何移动、重命名或新增（“此 PR 引入三级自动修复……”），请改为突出现在可以实现什么，或什么问题已得到修复（“文档审查此前会产生 14 项以上需要用户判断的问题；此 PR 将其减少到 4–6 项。”）。

大型 PR 应有所取舍，而非面面俱到。

第 9 步：返回 {title, body_file}

将合成后的正文写入 OS 临时文件，然后返回标题和文件路径。不要调用 gh pr edit、gh pr create 或任何其他会产生更改的命令。不要要求用户确认——调用方负责应用更改。

BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/ce-pr-body.XXXXXX") && cat > "$BODY_FILE" <<'__CE_PR_BODY_END__' && echo "$BODY_FILE"
<the composed body markdown goes here, verbatim>
__CE_PR_BODY_END__

引用的哨兵值 '__CE_PR_BODY_END__' 可防止正文中的 $VAR、反引号、${...} 以及任何字面量 EOF 被展开或与终止符冲突。将 echo "$BODY_FILE" 与 && 链接，这样 mktemp 或写入失败时，就不会以成功状态退出并返回一个指向不存在文件的路径。

将返回内容格式化为带有清晰标签的区块，以便调用方准确提取：

=== TITLE ===
<title line>

=== BODY_FILE ===
<absolute path to the mktemp body file>

不要在返回区块中输出正文 Markdown——调用方会从 BODY_FILE 读取。

如果第 1 步正常退出（PR 已关闭/合并、范围无效、提交列表为空），则不要创建正文文件——只返回原因字符串。

返回区块是交接内容，不代表任务已完成。 如果由父技能（例如 ce-commit-push-pr）调用，则输出返回区块后，继续执行父流程的剩余步骤（通常是使用返回的标题和正文文件调用 gh pr create 或 gh pr edit）。除非是用户直接调用且没有父工作流，否则不要在返回区块后停止。

---

跨平台说明

此技能不会直接提问。如果 diff 对某些需要调用方决定的内容存在歧义（例如，关注重点与实际更改冲突，或证据在技术上可以捕获，但调用方未预先暂存），请在返回内容中指出歧义，或向调用方简短说明——不要调用平台提问工具。

需要向用户提问的调用方，应负责使用各自平台的阻塞式提问工具：Claude Code 中的 AskUserQuestion（如果尚未加载其 schema，先调用 ToolSearch，参数为 select:AskUserQuestion）、Codex 中的 request_user_input、Gemini 中的 ask_user、Pi 中的 ask_user（需要 pi-ask-user 扩展）。只有在运行环境中不存在阻塞式工具或调用出错时（例如 Codex 编辑模式），才在聊天中使用带编号的选项作为后备方案——不要仅仅因为需要加载 schema 就这样做。绝不要默默跳过提问。