magpie-setup

magpie-setup 是 Apache Magpie 框架在采用方仓库中唯一提交的框架技能，用于通过基于快照的机制接入并维护框架。采用模型为快照加智能体覆盖加漂移感知更新，而非子模块、应用市场或 vendored 副本。框架被下载到 snapshot-dir 并在仓库中 gitignore，快照属于构建产物而非源码。支持三种安装方式：svn-zip（ASF 发布的签名 zip，发布后推荐用于生产）、git-tag（固定到特定标签）、git-branch（跟踪分支尖端，默认 main）。两个锁文件记录框架版本：已提交的 .apache-magpie.lock 声明项目固定版本，本地 .apache-magpie.local.lock 记录各机器实际拉取的版本，二者漂移由 /magpie-setup upgrade 处理。软链接使框架技能可像本地技能一样调用，每个命名为 magpie-<framework-skill> 以避免命名冲突；.agents/skills/ 是唯一规范位置，其他智能体目标 .claude/skills/、.github/skills/ 等获得指向规范入口的转发软链接。采用方对框架工作流的修改以智能体可读指令形式存放于 .apache-magpie-overrides/ 下并提交。框架自身检出使用 method:local 本地自采用。子动作包括 adopt（默认，首次采用）、upgrade、worktree-init、verify、skill-sources、override、unadopt。核心规则：不得修改快照；已提交锁为项目固定而本地锁为每机事实；漂移需呈现并修复；.gitignore 保持仓库整洁；.agents/skills/ 为规范；仅本技能被复制而其余为软链接；覆盖在运行时读取；setup-* 与 list-* 两族始终安装；自更新后需重新加载进行中的 setup。