設定
此技能是採用專案唯一提交的框架成品。其他所有的 apache-magpie 技能（安全性、PR 管理、議題）都是 gitignored 的符號連結，指向由此技能管理的 gitignored 快照 <snapshot-dir>。
採用模型是快照 + 代理覆蓋 + 漂移感知更新（非子模組、非市集、非廠商複製）：
- 框架被下載到
<snapshot-dir>，並在採用倉庫中被 gitignore。快照是建構成品，不是原始碼。 - 支援三種安裝方式（參見
docs/setup/install-recipes.md以獲取可直接複製貼上的配方）：- svn-zip — 來自 ASF 發行版的已發布、已簽署 zip（正式版本發布後，建議用於生產環境）。
- git-tag — 固定到特定的 git tag。
- git-branch — 追蹤分支的最新提交（預設：
main，即開發中的路徑）。
- 兩個鎖定檔案記錄框架版本。已提交的鎖定檔案宣告專案固定的版本；本機鎖定檔案記錄每台機器實際取得的版本。兩者之間的漂移會由
/magpie-setup upgrade發現並修復。 - 符號連結使框架的技能看起來就像存在於採用倉庫中一樣。每個符號連結命名為
magpie-<framework-skill>— 每個框架技能都以magpie-前綴安裝，以進行命名空間隔離，絕不會與採用者自己的技能衝突（例如，快照中的skills/pr-management-triage/變成magpie-pr-management-triage，透過/magpie-pr-management-triage呼叫）。.agents/skills/是唯一的規範家目錄：其magpie-*條目連結到<snapshot-dir>/skills/<framework-skill>/。所有其他代理目標（.claude/skills/、.github/skills/、……）都會獲得一個每個技能的薄型轉發符號連結，指向規範條目（.claude/skills/magpie-<n>→../../.agents/skills/magpie-<n>）— 無論採用專案之前使用何種佈局（參見agents.md）。這些符號連結是 gitignored 的，因為它們的目標在/magpie-setup執行前的全新 clone 中不存在。 - 採用者對框架工作流程的特定修改以代理可讀的指令形式存放於
.apache-magpie-overrides/<skill-name>.md（已提交）。它們會使框架技能原本會執行的步驟失效或更改。參見overrides.md了解合約，以及docs/setup/agentic-overrides.md了解設計理由。
本地自我採用（僅限框架檢出）。 無法透過快照機制採用的唯一倉庫是 Apache Magpie 框架檢出本身 — 將框架的遠端快照放入自身會造成循環。相反地，它使用 method:local 進行自我採用：.agents/skills/ 中的每個規範 magpie-<skill> 都是一個已提交的符號連結，指向倉庫內的 ../../skills/<skill>/ 原始碼，而每個其他活動的代理目標（agents.md）— .claude/skills/（Claude Code）、.github/skills/（GitHub 的技能載入器）以及任何現有的保留目標 — 都會獲得一個已提交的轉發符號連結（magpie-<skill> → ../../.agents/skills/magpie-<skill>）— 無需快照、無需遠端獲取、也無需複製。這使得框架自身的技能在開發框架時可被呼叫，並且每個貢獻者在全新 clone 上無需任何設定步驟即可使用它們。adopt 會從結構上檢測框架檢出並自動路由到該處（參見
adopt.md → 本地自我採用）。
兩個鎖定檔案
框架的鎖定檔案模型將專案固定的版本（已提交）與此機器實際取得的版本（本機）分開。這種分離是漂移檢測和多安裝程式支援的基礎。
<committed-lock> — .apache-magpie.lock
提交於採用倉庫根目錄。專案的固定版本。僅由 /magpie-setup 編輯；請勿手動修改。
# .apache-magpie.lock — 已提交；專案的固定版本。
method: <git-branch | git-tag | svn-zip>
url: <請參閱下方每種 method 的格式>
# 對於 method=git-branch：
ref: main
# 對於 method=git-tag：
ref: v1.0.0 # tag 名稱
commit: <SHA> # 提交鎖定時 tag 指向的 commit
# 對於 method=svn-zip：
ref: 1.0.0 # 版本號
sha512: <hash> # 已發布 zip 的 SHA-512（用於重新獲取驗證）
下一個執行 /magpie-setup adopt 的採用者會讀取此檔案，並重新安裝到專案聲明的相同版本。這是「一次採用，所有後續使用者獲得相同內容」承諾的核心。
<local-lock> — .apache-magpie.local.lock
在採用倉庫根目錄中被 gitignore。本機快照的指紋。記錄此機器取得的內容和時間。
# .apache-magpie.local.lock — gitignored；每台機器。
source_method: <git-branch | git-tag | svn-zip>
source_url: <快照實際獲取來源的 URL>
source_ref: <實際獲取的 branch / tag / version>
fetched_commit: <磁碟上目前的 commit SHA>
fetched_at: <ISO-8601 時間戳>
每次框架技能呼叫時的漂移檢查會將此與 <committed-lock> 進行比較，並將任何不匹配作為建議的 /magpie-setup upgrade 呈現。
此目錄中的詳細文件
| 檔案 | 用途 |
|---|---|
adopt.md | 首次採用指南 — 識別現有快照與需要引導的情況，寫入兩個鎖定檔案，詢問使用者要連接哪些技能系列，建立 gitignored 的符號連結，建立 .apache-magpie-overrides/，安裝 post-checkout hook，更新專案文件。預設子動作。 |
upgrade.md | 根據已提交的鎖定檔案重新整理 gitignored 快照，針對新的框架結構協調任何代理覆蓋和符號連結，呈現衝突。驅動漂移修復流程。 |
verify.md | 唯讀健康檢查 — 快照存在且完整、兩個鎖定檔案同步、符號連結指向有效的目標、.gitignore 正確、.apache-magpie-overrides/ 存在、漂移狀態（已提交 vs 本機）、以及 setup 技能本身是否為最新。 |
agents.md | 代理目標註冊表 — 框架技能符號連結在各個供應商目錄中的位置，以及規範加轉發模型：.agents/skills/ 是唯一的規範家目錄（連結到快照/原始碼）；每個其他目標（claude-code、github、保留的 native 目標如 Windsurf / Goose）都會獲得每個技能的轉發符號連結，指向 .agents/skills/。定義活動目標選擇、SKILL.md 格式可攜性，以及僅限 Claude Code 的層（sandbox/hooks）。每個子動作查詢目標集的唯一真相來源。 |
overrides.md | 代理覆蓋檔案管理 — 開啟/建立框架技能的覆蓋檔案、列出現有覆蓋、在升級時框架更改底層技能結構時協助協調。 |
unadopt.md | 反向採用 — 移除快照、鎖定檔案、符號連結、post-checkout hook、.gitignore 條目、README.md / AGENTS.md / CONTRIBUTING.md 中的採用章節，以及已提交的 setup 技能本身。預設保留 .apache-magpie-overrides/；--purge-overrides 也會將其移除。在任何寫入之前呈現完整的移除計畫。 |
黃金規則
黃金規則 1 — 絕不修改快照。 <snapshot-dir> 是建構成品，被 gitignore，並且從採用者的角度來看是唯讀的。採用者想要進行的每個修改都必須放入 .apache-magpie-overrides/（在那裡它被提交，並且在下次 upgrade 後仍然存在）。此技能以及任何其他在執行時查詢覆蓋的框架技能絕不寫入 <snapshot-dir>。
黃金規則 2 — <committed-lock> 是專案的固定版本；<local-lock> 是每台機器的真相。 它們服務於不同的目的，並位於不同的位置：
<committed-lock>宣告專案使用哪個版本。由第一個執行/magpie-setup adopt的採用者（或之後執行/magpie-setup upgrade並接受新固定版本的採用者）編輯。提升它是刻意的專案層級動作；提升內容會顯示在提出該動作的 PR 的git diff中。<local-lock>記錄此機器安裝的內容。由/magpie-setup adopt和/magpie-setup upgrade靜默更新。每個開發者、每個檢出、每個工作目錄各一份。
黃金規則 3 — 漂移會被發現，漂移會被修復。 每個框架技能（以及 /magpie-setup verify）在其執行開始時檢查 <committed-lock> 與 <local-lock> 的比較。若發現不匹配，技能會呈現差距並建議 /magpie-setup upgrade。使用者接受或推遲；如果接受，upgrade 會：
- 直接刪除
<snapshot-dir>。 - 根據已提交的鎖定檔案（專案選擇的新版本）重新安裝。
- 重新整理 gitignored 的框架技能符號連結 — 新增使用者選擇的技能系列所涵蓋的任何新框架技能，移除任何被重新命名或移除的框架技能。
- 根據新的框架結構協調代理覆蓋（呈現衝突；絕不自動改寫）。
- 將
<local-lock>更新為新的獲取內容。
黃金規則 4 — .gitignore 保持採用倉庫乾淨。 採用倉庫中三項被 gitignore 的內容：
<snapshot-dir>（整個框架快照 — 可能數 GB）。<local-lock>（每台機器的狀態）。setup adopt在每個活動目標目錄中建立的magpie-*符號連結 — 在.agents/skills/中的規範連結（它們指向被 gitignore 的快照）以及在.claude/skills//.github/skills// 保留目標中的轉發連結（它們指向規範條目）— 在全新 clone 中兩者都會懸空。每個目錄中唯一不被 gitignore 的例外是magpie-setup。
已提交：此技能（setup，作為規範的 .agents/skills/magpie-setup/ 加上其轉發連結）、<committed-lock>、.apache-magpie-overrides/ 目錄、.gitignore 條目本身、以及 adopt 子動作所做的任何專案文件更新。
黃金規則 5 — .agents/skills/ 是規範的；其他所有內容只是轉發到它。 無論採用專案之前如何組織其 .claude/skills/ 或 .github/skills/，adopt 始終以相同方式連接框架：規範的 magpie-* 連結位於 .agents/skills/ 中，而每個其他活動目標（.claude、.github、保留目標）都會獲得每個技能的轉發符號連結，指向規範條目（.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>）。採用者在這些目錄中自己的原生（非 magpie-）技能保持不變。參見 agents.md。
黃金規則 6 — 複製此技能，符號連結其餘部分；全部使用 magpie- 前綴。 此技能（原始碼 skills/setup/）是唯一被複製到採用倉庫中的框架技能 — 作為規範的 .agents/skills/magpie-setup/ 提交，並附帶從 .claude/skills/magpie-setup 和 .github/skills/magpie-setup 指向它的已提交轉發符號連結。所有其他框架技能都是符號連結（指向 gitignored 快照的規範連結，加上轉發連結），每個命名為 magpie-<framework-skill>（例如 magpie-security-issue-import → <snapshot-dir>/skills/security-issue-import/）。magpie- 前綴為每個框架技能建立命名空間，使其永遠不會與採用者自己的技能衝突。混合複製和符號連結 — 例如複製一個安全技能 — 會造成維護風險：複製會偏離框架的真相來源，而漂移檢測機制（假設框架版本位於 <snapshot-dir> 中）會靜默地錯誤應用。
黃金規則 7 — 代理覆蓋在執行時被讀取。 每個支援覆蓋的框架技能都會在其執行開始時檢查 .apache-magpie-overrides/<this-skill>.md 以獲取採用者特定的指令，並在執行預設行為之前應用它們。覆蓋檔案是代理解釋的純文字 markdown — 無模板引擎，無修補工具。參見 docs/setup/agentic-overrides.md 了解合約。
黃金規則 8 — 兩個系列始終被安裝；其餘是選擇加入。 兩個技能系列在每次 adopt / upgrade / worktree-init 執行時無條件地被連接，並且從不詢問使用者：
setup-*— 原始碼名稱以setup-開頭的每個框架技能，除了引導用的setup本身（根據規則 6 被複製為magpie-setup，而非符號連結）。具體來說：setup-isolated-setup-install、setup-isolated-setup-update、setup-isolated-setup-verify、setup-override-upstream、setup-shared-config-sync，以及框架未來新增的任何setup-*技能 — 每個都符號連結為magpie-setup-*。list-*— 發現系列；原始碼名稱以list-開頭的每個框架技能。目前只有list-skills（符號連結為magpie-list-skills）；此前綴讓框架未來可以增加...