setup
此技能是采用者项目提交的唯一框架产物。所有其他 apache-magpie 技能（安全、PR 管理、议题）都是指向此技能管理的、位于 <snapshot-dir> 处的已 gitignored 快照的 gitignored 符号链接。
采用模型是快照 + 代理覆盖 + 漂移感知更新（而非子模块、市场或供应商副本）：
- 框架下载到
<snapshot-dir>并在采用者仓库中被 gitignored。快照是构建产物，而非源码。 - 支持三种安装方法（参见
docs/setup/install-recipes.md获取可直接复制粘贴的配方）：- svn-zip — 来自 ASF 分发的已发布签名 ZIP（建议在发布版本上线后的生产环境使用）。
- git-tag — 锁定到特定的 Git 标签。
- 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运行之前的新克隆中不存在。 - 采用者对框架工作流的特定修改作为代理可读指令存储在
.apache-magpie-overrides/<skill-name>.md（已提交）中。它们会使框架技能本应运行的步骤失效或更改。参见overrides.md了解约定，以及docs/setup/agentic-overrides.md了解设计原理。
本地自我采用（仅框架检出）。唯一不能通过快照机制采用的仓库是 Apache Magpie 框架检出本身 — 将框架的远程快照放入自身会导致循环。相反，它通过 method:local 自我采用：每个规范的 magpie-<skill> 在 .agents/skills/ 中是一个已提交的符号链接，指向仓库内 ../../skills/<skill>/ 源码，并且每个其他活动代理目标（agents.md）— .claude/skills/（Claude Code）、.github/skills/（GitHub 的技能加载器），以及任何存在的保留目标 — 都获得一个已提交的中继符号链接（magpie-<skill> → ../../.agents/skills/magpie-<skill>）— 没有快照、没有远程获取、没有副本。这使得在开发框架的同时可以调用框架自身的技能，并且每个贡献者在新克隆上无需任何设置步骤即可激活这些技能。adopt 会通过结构检测框架检出并自动路由到那里（参见 adopt.md → 本地自我采用）。
两个锁文件
框架的锁文件模型将项目锁定的内容（已提交）与此机器实际获取的内容（本地）分开。这种分离是漂移检测和多安装程序支持的基础。
<committed-lock> — .apache-magpie.lock
提交在采用者仓库根目录。项目的版本锁定。仅由 /magpie-setup 编辑；请勿手动修改。
# .apache-magpie.lock — 已提交；项目的版本锁定。
method: <git-branch | git-tag | svn-zip>
url: <参见每个方法的格式>
# 对于 method=git-branch:
ref: main
# 对于 method=git-tag:
ref: v1.0.0 # 标签名称
commit: <SHA> # 提交时标签指向的提交
# 对于 method=svn-zip:
ref: 1.0.0 # 版本号
sha512: <hash> # 已发布 ZIP 的 SHA-512（用于重新获取时的验证）
下一个运行 /magpie-setup adopt 的采用者会读取此文件，并重新安装到项目声明的相同版本。这是“一次采用，所有后续用户获得相同内容”承诺的核心。
<local-lock> — .apache-magpie.local.lock
在采用者仓库根目录被 gitignored。本地快照的指纹。记录此机器获取的内容和时间。
# .apache-magpie.local.lock — 已 gitignored；每台机器。
source_method: <git-branch | git-tag | svn-zip>
source_url: <实际获取快照的 URL>
source_ref: <实际获取的分支/标签/版本>
fetched_commit: <当前磁盘上的提交 SHA>
fetched_at: <ISO-8601 时间戳>
每次调用框架技能时的漂移检查将此文件与 <committed-lock> 进行比较，并将任何不匹配作为建议的 /magpie-setup upgrade 呈现。
本目录中的详细信息文件
| 文件 | 用途 |
|---|---|
adopt.md | 首次采用指南 — 识别现有快照与需要引导，写入两个锁文件，询问用户要连接哪些技能族，创建 gitignored 的符号链接，搭建 .apache-magpie-overrides/，安装检出后钩子，更新项目文档。默认子操作。 |
upgrade.md | 根据提交的锁刷新 gitignored 快照，将代理覆盖和符号链接与新框架结构协调，呈现冲突。驱动漂移修复流程。 |
verify.md | 只读健康检查 — 快照存在且完整、两个锁文件同步、符号链接指向活动目标、.gitignore 正确、.apache-magpie-overrides/ 存在、漂移状态（已提交与本地）、setup 技能本身是否为最新。 |
agents.md | 代理目标注册表 — 框架技能符号链接在各个供应商目录中的位置，以及规范加中继模型：.agents/skills/ 是唯一的规范家目录（链接到快照/源码）；每个其他目标（claude-code、github、保留的专用目标如 Windsurf / Goose）都会获得每个技能指向 .agents/skills/ 的中继符号链接。定义活动目标选择、SKILL.md 格式可移植性以及仅限 Claude Code 的层（沙箱/钩子）。每个子操作用于目标集合的真实来源。 |
overrides.md | 代理覆盖文件管理 — 打开/搭建框架技能的覆盖、列出现有覆盖、在升级时框架更改底层技能结构时帮助协调。 |
unadopt.md | 撤销采用 — 删除快照、锁、符号链接、检出后钩子、.gitignore 条目、README.md / AGENTS.md / CONTRIBUTING.md 中的采用部分以及已提交的 setup 技能本身。默认保留 .apache-magpie-overrides/；--purge-overrides 也会删除它。在任何写入之前呈现完整的删除计划。 |
黄金法则
黄金法则 1 — 绝不要修改快照。 <snapshot-dir> 是构建产物，已 gitignored，并且从采用者的角度来看是只读的。采用者希望进行的每次修改都必须放入 .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 保持采用者仓库干净。 采用者仓库中 gitignored 的三样东西：
<snapshot-dir>（整个框架快照 — 可能有千兆字节大小）。<local-lock>（每台机器的状态）。setup adopt在每个活动目标目录中创建的magpie-*符号链接 —.agents/skills/中的规范符号链接（它们指向 gitignored 的快照）以及.claude/skills//.github/skills// 保留目标中的中继符号链接（它们指向规范条目）— 两者在新克隆中都会成为悬挂符号链接。唯一的例外是在每个目录中取消 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）；此前缀允许框架将来增长" } 翻译注意事项：这是完整的自定义指令，紧随其后的是用户消息。请以