pr-draft-summary

PR 草稿摘要

用途

在符合条件的代码工作完成后，生成本仓库要求的、可直接用于 PR 的摘要：一段简洁的摘要，加上可直接用于 PR 的标题，以及以 "This pull request ..." 开头的草稿描述。该内容应可直接粘贴到 openai-agents-python 的 PR 中。

触发时机

• 用户明确请求 PR 草稿时，优先于下面的自动触发排除规则。
• 对于自动调用，仅涉及拼写、注释或格式的修改属于编辑性改动，即使位于运行时/测试路径下，只要不改变行为或契约，也应跳过自动草稿。
• 每次给出最终回复前，检查当前任务是否修改了运行时代码（src/agents/）、测试（tests/）、示例（examples/）、构建/测试配置，或具有行为影响的文档。
• 如果有，则在完成必要验证之后、发送最终回复之前运行此技能。不要因为改动规模看起来较小而决定是否运行。
• 即使用户没有要求创建 pull request，也要对符合条件的仅本地或未提交工作运行此技能。生成此文本并不授权创建分支、提交、推送或开启 pull request。
• 仅在以下情况跳过：琐碎或仅限对话的任务；没有行为影响的仓库元信息/纯文档任务；明确调用 $release-candidate-prep 交接，且使用完整的 $final-release-review 报告作为发布专用 PR 描述；或用户明确表示不要包含 PR 草稿块。此例外仅适用于准备发布候选版本本身，不适用于实现或修改发布准备技能。

自动收集的输入（不要询问用户）

• 当前分支：git rev-parse --abbrev-ref HEAD。
• 工作区：git status -sb。
• 未跟踪文件：git ls-files --others --exclude-standard（与 git status -sb 配合使用，确保它们被展示；--stat 不包含这些文件）。
• 已变更文件：git diff --name-only（未暂存）和 git diff --name-only --cached（已暂存）；大小通过 git diff --stat 和 git diff --stat --cached 获取。
• 最新发布标签（优先使用支持远程的查询）：LATEST_RELEASE_TAG=$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*' 2>/dev/null || git tag -l 'v*' --sort=-v:refname | head -n1)。
• 基准引用（使用分支的上游，回退到 origin/main）：
  • BASE_REF=$(git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || echo origin/main)。
  • BASE_COMMIT=$(git merge-base --fork-point "$BASE_REF" HEAD || git merge-base "$BASE_REF" HEAD || echo "$BASE_REF")。
• 相对于基准分叉点领先的提交：git log --oneline --no-merges ${BASE_COMMIT}..HEAD。
• 本仓库的分类信号：运行时（src/agents/）、测试（tests/）、示例（examples/）、文档（docs/、mkdocs.yml）、构建/测试配置（pyproject.toml、uv.lock、Makefile、.github/）。

工作流

1. 无需询问用户即可运行上述命令；先计算 BASE_REF/BASE_COMMIT，以便后续命令复用它们。
2. 如果没有已暂存、未暂存或未跟踪的更改，并且相对于 ${BASE_COMMIT} 没有领先的提交，请简要回复未检测到代码更改，并跳过输出 PR 块。
3. 根据"Category signals"下列出的已修改路径推断更改类型；将其归类为 feature、fix、refactor 或 docs-with-impact，并且仅当差异改动了已发布的公共 API、外部配置、持久化数据、序列化状态或通信协议时，才标记向后兼容风险。该风险应以 LATEST_RELEASE_TAG 为基准判断，而不是未发布的分支专属改动。
4. 使用关键路径（前 5 项）和 git diff --stat 输出，用 1–3 个简短句子总结更改；需明确指出来自 git status -sb/git ls-files --others --exclude-standard 的未跟踪文件，因为 --stat 不包含它们。如果工作树干净但相对于 ${BASE_COMMIT} 有领先的提交，则使用这些提交信息进行总结。
5. 为描述选择主导动词：feature → adds，bug fix → fixes，refactor/perf → improves 或 updates，仅文档 → updates。
6. 建议分支名称。如果已基于 main，则保持不变；否则根据主要领域提出 feat/<slug>、fix/<slug> 或 docs/<slug>（例如 docs/pr-draft-summary-guidance）。
7. 如果当前分支与 issue-<number>（仅含数字）匹配，则保留该分支建议。可在可用时选择性地获取轻量的 issue 上下文（例如通过 GitHub API），但如果不可用，不要阻塞或重试。存在 issue 编号时，使用原生的同仓库引用 #<number>，并包含自动关闭语句，例如 This pull request resolves #<number>.。不要添加显式的 issue URL，也不要将引用包装为 Markdown 链接。
8. 使用下方模板起草 PR 标题和描述。遵守仓库范围内的 GitHub 可直接粘贴规则：同仓库的 issue 或 PR 必须精确使用 #123，跨仓库引用使用 owner/repo#123；在可直接复制的块中，切勿输出 [PR #123](https://github.com/owner/repo/pull/123)、[#123](...)、Codex 导航链接、本地文件链接、仅限 Codex 的引用标记或脚注，或应用指令。对于不使用原生 GitHub issue 或 pull-request 语法的 API 文档、设计说明及其他目标的普通描述性链接，应予保留。
9. 返回该块之前规范化引用：将每个同仓库 URL 或 openai/openai-agents-python#<number> 引用替换为 #<number>，将每个跨仓库 issue 或 pull-request URL 替换为 owner/repo#<number>，然后重新检查完整的块。如果仍存在 Markdown 链接形式的 issue 或 pull-request 标签、同仓库的限定引用，或裸露的 GitHub issue 或 pull-request URL，则不要返回该块。
10. 仅输出"Output Format"中的块。任何周围的状态说明应保持简短，并使用英文。

Output Format

完成任务时，在任何简短的状态说明之后添加此简洁的 Markdown 块（仅限英文），除非任务属于已记录的跳过情形，或用户表示不需要。

# Pull Request Draft

## Branch name suggestion

git checkout -b <kebab-case suggestion, e.g., feat/pr-draft-summary-skill>

## Title

<single-line imperative title, which can be a commit message; if a common prefix like chore: and feat: etc., having them is preferred>

## Description

<include what you changed plus a draft pull request title and description for your local changes; start the description with prose such as "This pull request resolves/updates/adds ..." using a verb that matches the change (you can use bullets later), explain the change background (for bugs, clearly describe the bug, symptoms, or repro; for features, what is needed and why), any behavior changes or considerations to be aware of, and you do not need to mention tests you ran.>

保持精炼——块周围不要有冗余文字，并避免在 Changes 与描述之间重复细节。除非特别要求，无需列出测试。