softwareone-platform/issue-to-pr

開啟 PR

為當前分支在偵測到的 PR 平台（Azure DevOps 或 GitHub）上開啟一個提取請求。標題和描述會根據呼叫使用者自己過去的 PR 慣例來撰寫，而非固定風格，然後顯示供確認。未經明確批准，絕不建立 PR——開啟 PR 是一個對外行動。

此技能是後端無關的：平台特定的操作（建立 PR、重複檢查、標籤、反向移植連結）位於 resources/backends/ 下的後端配接器參考文件中，而票證連結操作位於 resources/trackers/ 下的追蹤器配接器參考文件中。技能主體會偵測平台和追蹤器，載入相符的配接器並遵循其配方——它自身不包含任何 az/gh 特定欄位解析，也不包含任何追蹤器特定的 ID/URL 解析。它借用了 PR 建立流程的安全護欄，但刻意更狹窄：它為分支當前的狀態開啟 PR——如果分支尚未在遠端，則先發布到遠端，因為 PR 需要它。它不會合併基礎分支，不會刪除分支，也不會審查評論（那是 resolve-pr-comments 的職責）。

步驟 0 — 偵測平台 + 追蹤器，載入配接器，宣布

在執行其他操作之前，解析此運行目標的後端和追蹤器：

• PR 平台 — 從 git remote get-url origin：
  • dev.azure.com 或 *.visualstudio.com → Azure DevOps（resources/backends/azure-devops.md）。
  • github.com → GitHub（resources/backends/github.md）。
  • 不明確或其他主機 → 說明限制，並詢問使用者要定位哪個平台，而非猜測。
• 問題追蹤器（優先級——先匹配者勝出）：
  1. 明確配置優先： 如果 .claude/pr-lifecycle.json（可選，已 gitignore）指定了追蹤器類型，則使用它（並從中獲取 Jira 基礎 URL）。
  2. 否則從現有票證引用推斷類型：[A-Z][A-Z0-9]+-\d+ → Jira（任一平台）；純數字問題引用 → GitHub Issues——但僅在 GitHub 遠端上（在 Azure DevOps 上 #<n> 是工作項目的連結，不是 GitHub 問題，因此純數字在那裡不表示 GitHub Issues）。
  3. 否則按平台預設：GitHub 遠端 → GitHub Issues（零配置）；Azure DevOps 遠端 → Jira。
  4. 完全沒有票證 → 不產生追蹤器行（與現在相同）。
  • Jira → resources/trackers/jira.md；GitHub Issues → resources/trackers/github-issues.md。
• 宣布偵測到的平台和追蹤器，使錯誤猜測無法沉默發生。

載入匹配的後端和追蹤器配接器，並透過它們執行以下步驟的平台/追蹤器特定部分。此主體中唯一的後端接縫是用於選擇配接器的遠端字串辨識——除此之外無欄位存取。（配接器路徑相對於插件根目錄——plugins/pr-lifecycle/resources/backends/ 和 resources/trackers/——而非技能目錄。）

步驟 1 — 偵測目標分支

• 讀取儲存庫自身的預設分支；切勿假設。 git symbolic-ref --short refs/remotes/origin/HEAD 會產生 origin/<branch>——剝離前綴。該引用由 git clone 寫入，因此由 git init + git fetch 建立的遠端可能缺少它；然後直接用 git ls-remote --symref origin HEAD 詢問遠端，此操作是唯讀的，不會更改任何本地狀態。
• 僅當兩者都無法解析時，才回退到遠端實際擁有的 main/master——如果兩者都存在，則詢問。正在進行重新命名的儲存庫會將舊的保留為過時分支，因此沉默地選擇會導致 PR 基於錯誤的目標，這也會使步驟 2 的領先計數和步驟 3 學習呼叫者慣例所用的歷史失效。
• 如果當前分支定位到一個發布線（例如 release/2.5），則將其視為反向移植（請參閱下面的反向移植格式）。
• 如果正確的目標確實不明確，則詢問而非猜測。

步驟 2 — 前置條件（如果任何一個失敗則停止並報告）

在起草任何內容之前執行這些操作，因為每個都是常見的首次運行障礙：

• 有提交可供 PR。 分支必須領先於目標：git fetch，然後 git rev-list --count origin/<target>..HEAD 必須大於 0。
• 在遠端上——如果需要則發布。 建立 PR 需要源分支在遠端上。尚未推送的分支不是停止條件：確認後，open-pr 會發布它（git push -u origin <branch>）作為步驟 4 中建立的一部分。（以非互動方式運行時，它不會推送也不會建立——請參閱步驟 4。）
• 無重複。 通過後端配接器的重複檢查配方檢查是否存在從此源到目標的現有開放 PR。如果存在，停止並引導使用者前往該 PR——不要建立第二個 PR，也不要在此處修改現有 PR。

步驟 3 — 學習呼叫者的慣例，然後起草

從 git config user.email（首選）和 user.name 識別呼叫者，然後讀取他們在此儲存庫中最近的已合併 PR：git log <target> --author="<email or name>"（嘗試兩種形式；僅當兩者都返回無結果時才視為「無歷史」）。從最近幾個中，通過多數決推斷標題大小寫和描述佈局（分節 vs 純項目符號列表）——最新（按提交日期）打破平局，單個先前的 PR 則直接使用。宣布結果（從您過去的 K 個 PR 中學習到 或 無匹配歷史 -> 使用預設值），使錯誤猜測無法沉默發生。

學習涵蓋此儲存庫和此呼叫者如何編寫內容，而不僅僅是排版：標題大小寫、描述佈局（分節 vs 純項目符號列表）、以及標題的票證前綴形狀——帶括號的（[acme-123] …）、不帶括號的（acme-123 …）、慣用提交類型（fix(scope): …）或完全沒有前綴。從相同的歷史中讀取形狀；如果觀察到的 PR 不帶有票證前綴，則不要添加一個。以下預設值是在沒有歷史可供學習時使用的，絕非強加給明顯使用其他方式的儲存庫的格式。

學習絕不能丟棄或重新排序以下強制性內容——票證連結、摘要和要點；第 4 項中的圖表是可選的，而第 5 項中的來源頁尾預設為關閉，但當來源頁尾選擇加入時，學習必須將其保留在最後且絕不丟棄。如果此儲存庫是單一作者，請不要將學習偏向它——重要的慣例是呼叫者的慣例，無論技能在哪個儲存庫中運行。

預設格式（回退方案；呼叫者學習到的慣例會覆蓋呈現）

標題： 從追蹤器配接器衍生票證 ID 及其大小寫：

• Jira 追蹤器： [acme-xxxxx] <簡潔的一行摘要>——帶括號的小寫金鑰（配接器也會產生用於 URL 的大寫形式）。
• GitHub Issues 追蹤器： #<n> <簡潔的一行摘要>——使用 #<n> 引用代替括號形式。
• 未找到票證：省略票證行，並以此儲存庫命名無票證 PR 的方式命名標題。ad-hoc <摘要> 是僅當步驟 3 中的歷史沒有提供任何可複製的內容時的回退方案——它是一個團隊的標記，而非要引入到從未使用過它的儲存庫中的慣例。純 <摘要> 是更安全的預設值。
• 兩個或更多不同的票證 ID 表示應詢問是哪一個，而不是沉默地取第一個。

描述（標準 PR）：

1. 票證連結——由追蹤器配接器建構：對於 Jira，https://<jira_base_url>/browse/<KEY>（大寫金鑰）；對於 GitHub Issues，#<n>（GitHub 會自動連結同一儲存庫的問題）。這是第一行，以便平台自動連結；僅在沒有票證時才省略整行。
2. 摘要——一或兩個句子。
3. 描述——一個項目符號列表，每個離散更改一個項目符號，格式為動作加上簡短的為什麼/影響。省略檔案/類別/方法/路徑識別符——描述意圖，不要貼上 diff。
4. 一個簡短的 ASCII 圖表，包裹在圍欄程式碼區塊中（可選）——僅當圖表能讓審閱者比文字更快掌握變更時才包含一個；否則省略它。當你包含時：一個真正的等寬結構圖（方框/箭頭，或一個小樹/表格——絕非偽裝成圖表的散文），保持高階，包裹在三重反引號圍欄中，使用純 ASCII 字符（+ - | > v）繪製，不是 Mermaid；將任何寬或複雜的圖表拆分為較小的圖表，而不是強制一個不可讀的區塊。完整的繪圖指南、圍欄/編碼理由和一個說明性形狀：resources/diagram-guidance.md。
5. AI 來源標記（選擇加入——預設關閉）——頁尾（一個 --- 分隔線，然後是 🤖 _使用 Claude Code 起草。_）和步驟 4 中應用的 ai-assisted 標籤僅在調用請求明確要求標記/標示/標註 PR 為 AI 輔助時（或傳遞明確的選擇加入）才添加。缺少該措辭——包括每個自動化的 resolve-issue 管道調用，其不帶有此類措辭——則兩者都不添加。在與平台/追蹤器/學習結果相同的行上宣布決定（來源標記：關閉（說 "標記為 AI 輔助" 以添加），或 來源標記：開啟（頁尾 + 盡力標籤）），使沉默丟棄標記成為不可能。選擇加入時，頁尾是每條路徑上的最後一個元素——在學習到的慣例主體之後附加，且絕不讓學習丟棄或重新排序它——並且它在 Azure DevOps 和 GitHub 上呈現相同，是可攜式標記；標籤是平台原生的徽章（盡力而為——請參閱步驟 4）。如果團隊將來需要強制性的 AI 揭露以進行審計，屆時將其作為配置標誌重新引入——現在故意不建置。

反向移植（目標是 release/*）：

• 標題（Jira 追蹤器）：[acme-xxxxx] [release] <摘要>；（GitHub Issues 追蹤器）：#<n> [release] <摘要>。
• 描述是票證連結，然後是 cherry pick from <PR-link>，其中後端配接器提供 PR 連結語法（Azure DevOps !<pr_number>，GitHub #<pr_number>——兩者都呈現為指向該 PR 的連結），然後——僅當來源標記選擇加入時（步驟 3，第 5 項）——AI 來源頁尾（--- + 🤖 _使用 Claude Code 起草。_）。沒有摘要區塊、項目符號或圖表——真正的審查發生在原始 PR 上。
• 詢問使用者（或接受作為輸入）從中 cherry-pick 的源 PR 編號，並重複使用該 PR 的一行摘要作為 <摘要>。反向移植僅學習標題大小寫，而非描述佈局。

在每一條路徑上（包括反向移植）： 標題和描述使用英文。不要添加自己的 git Co-Authored-By 尾部——這是提交的關注點，而非 PR 描述的，並且此儲存庫是否想要一個是由儲存庫自己的歷史（git log -n 50 --format=%b | grep -c '^Co-Authored-By'）決定的，而非此技能決定。預設不添加；如果儲存庫的提交經常攜帶它，則遵循它而不是覆蓋它。AI 來源頁尾和 ai-assisted 標籤是不同的東西，並且預設關閉——僅在步驟 3（頁尾）和步驟 4（標籤）中描述的明確選擇加入時添加——並且絕不是被禁止的尾部。

步驟 4 — 呈現、確認、建立

顯示起草的標題和描述，並讓使用者編輯它們。然後：

• 獨立模式： 僅在使用者明確確認後才建立。如果源分支尚未在遠端上，則先發布它（git push -u origin <branch>），然後通過後端配接器的建立配方建立 PR——將完整描述寫入臨時檔案並將其作為配接器的 body-file 標誌傳遞，永遠不要作為內聯字串。配接器記錄平台的檔案編碼陷阱（例如 Azure DevOps 的 az.cmd cp1252/UTF-8 @<file> 怪癖）以及——僅當來源標記選擇加入時（步驟 3）——如何應用 ai-assisted 標籤（Azure DevOps 通過 --labels 內聯建立標籤；GitHub 在建立後使用 gh pr edit --add-label 添加它，因為 gh pr create --label 在標籤不存在時會中止）。選擇加入時，標籤在任何情況下都是盡力而為（請參閱說明的限制）；預設情況下不應用任何標籤。返回 PR URL。
• 無法獲得確認（以非互動方式運行，或在無法提示的子代理內部）：不要推送分支，也不要建立 PR。 列印準備好的標題和描述供使用者手動建立，並說明這一點。不要在非互動上下文使用瀏覽器開啟標誌（例如 Azure DevOps --open）。當來源標記選擇加入時，列印的描述已經帶有頁尾；告訴使用者在他們建立 PR 時添加 ai-assisted 標籤。預設情況下（無選擇加入），不會列印或提及任何標記。

不變規則：未經明確的人工確認，絕不發布分支或開啟 PR——兩者都是對外行動。

安全護欄

• 切勿自動解決合併衝突——停止並報告它們。
• 切勿刪除分支。
• 未經明確要求，切勿強制推送。

說明的限制

• 如果偵測到的平台的 PR 工具缺失或未經身份驗證（請參閱每個後端配接器的前置條件——例如 Azure DevOps 的 az + azure-devops 擴充功能，GitHub 的已認證 gh），請說明並列印準備好的標題和描述以供手動建立——不要靜默失敗。
• 學習到的慣例是盡力而為：如果 squash 工作流程未留下描述主體，大小寫仍來自提交主體，並且佈局回退到預設值——已宣布，而非沉默。
• 來源標記預設為關閉——除非調用請求明確選擇加入（步驟 3，第 5 項），否則沒有頁尾也沒有標籤。選擇加入時，ai-assisted 標籤是盡力而為：如果平台拒絕它（Azure DevOps 上不允許即興 PR 標籤的組織，或 GitHub 上尚不存在的標籤），則丟棄標籤，僅使用頁尾建立 PR（即已選擇加入的標記），並說明這一點——後端配接器記錄了每種平台的行為。