核心摘要:
boykush/ai-plugins采用apm包管理机制统一分发共享 MCP 服务与 Skill 规则,各项目仅在apm.yml声明依赖并提交生成产物与apm.lock.yaml,兼顾 Claude Code 与 Codex 的仓库级隔离与 CI 漂移校验。
多仓库并行研发中,AI 编码助手的 MCP 服务器与 Skill 配置极易陷入两难:把配置放在全局目录(如 ~/.mcp.json 或 ~/.codex/config.toml)虽然省事,但单个代码库无法声明“我依赖哪些工具”;若把配置手写进每个仓库的 .mcp.json,同一份远程 MCP 定义又会在多个仓库中反复复制粘贴。GitHub 公开仓库 boykush/ai-plugins(截至 2026-11-22 快照显示 153 次提交、0 星标)给出了一套基于 apm(Agent Package Manager)的集中式包分发方案。

需要首先说明来源边界:该仓库为开发者个人跨仓配置工程实践,原文以日文工程笔记撰写,文中所列工作流命令与工具约束均来自该仓库 README 的公开说明,未包含第三方规模化压测数据,跨团队引入前需在本地核验 apm 工具链版本兼容性。
一、为什么用项目级包声明取代全局与复制粘贴
仓库作者在实践中遇到一个典型痛点:同一套 wiki 远程 MCP 服务器配置,先后被原封不动复制进了 dotfiles、adr 与 livt 三个不同仓库;同时,Codex 的插件市场机制在当时仅支持机器级生效(~/.codex/config.toml),无法按代码库独立声明依赖。

为此,boykush/ai-plugins 把可复用的定义收拢为 plugins/<name>/apm.yml 包,消费方仓库不再手写客户端配置,而是在自身根目录放置一份简洁的 apm.yml(指定 targets 为 claude 和 codex,并在 dependencies.apm 中引用目标包),随后运行 apm install:
| 维度 | 全局配置(~/.mcp.json 等) | 仓库手工复制 .mcp.json | ai-plugins + apm 包分发 |
| :— | :— | :— | :— |
| 仓库显式依赖 | 不支持,换机或新成员不可见 | 支持,但多仓同步修改成本高 | 在 apm.yml 声明,apm.lock.yaml 锁定版本 |
| 客户端适配范围 | 依赖人工分别维护 | Claude 与 Codex 格式需双份手写 | 单次 apm install 同步生成 .mcp.json 与 .codex/config.toml |
| 技能文件落盘 | 全局共享,易跨项目污染 | 需手动复制更新 | 自动展开至项目级 .claude/skills/ 与 .agents/skills/ |
| CI 漂移防线 | 无法校验 | 易被人工改乱 | 删除生成文件后重跑 apm install 并执行 git diff --exit-code |
作者特别提醒了一个容易踩坑的 CI 细节:不能只靠 apm install --frozen 加 git diff 做校验,因为当 .mcp.json 中已存在同名 MCP 服务器时,apm 会判定为“already configured”而跳过内容覆盖(即便加 --force 也不修改),从而漏检人工篡改的 URL;同时又绝不能删除 apm.lock.yaml,否则 apm 会把被手工改动的 Skill 视作非托管文件而拒绝还原。正确做法是保留 apm.lock.yaml,删除 .mcp.json 与 .codex/config.toml 后重新执行 apm install 再比对差异。
二、四类内容放置边界与上游插件转译流水线
为了防止共享配置仓变成大杂烩,仓库明确划分了“放与不放”的四条边界:
- 放入共享仓:在 2 个及以上仓库复用的 MCP 服务与 Skill(作者按
github-management扇出范围排除 fork 与 archive 仓库); - 仅放打包壳:随业务代码一同演进的上游仓库自行维护 Agent Plugins 格式,共享仓不保存其实体副本,而是通过
mise run generate读取上游固定 commit SHA 生成apm包定义; - 留在个人 dotfiles:绑定本机环境的钩子脚本、状态栏、
helix联动配置以及个人工作习惯策略,继续保留在dotfiles; - 由产品仓自发分发:面向特定外部终端用户的专属 MCP 服务由产品自身仓库直接交付。
在自动化转化层面,由于当时 apm 仅会把 Agent Plugins 1.0.0 打包产物展开至 copilot 目标而阻止对 Claude 与 Codex 安装,仓库通过 mise run generate 脚本将上游 mcp.json 中的 streamable-http 传输字段自动转译为 http,并将 skills/ 下的每个技能拆分为独立 dependencies.apm 条目写入 plugins/<name>/apm.yml,再配合 Renovate 定期升级上游 commit SHA。
三、对 OpenLX 自动化工程与规则治理的启示
在 OpenLX 多站点内容工程与智能体工具链治理中,“中心定义唯一真相源、项目按需拉取锁定版本、CI 删除产物重生成比对”的思路具有很强的通用性。与此同时,原文还记录了一个具体环境陷阱:若 ~/.apm 是指向不存在实体的符号链接,apm 会直接报 Refusing symlinked lifecycle lock path 拒绝启动。工程团队在引入同类工具链时,应提前把这类路径前置检查纳入初始化脚手架,并在受控分支验证无误后再推广至生产工作区。
参考来源
- 开源项目原件:
boykush/ai-plugins(GitHub 公开仓库主页,采集核验时间:2026-11-22):https://github.com/boykush/ai-plugins
本文首发于 OpenLX文旅GEO·文旅AI信源基础设施(https://openlx.cn/),转载请注明出处与完整链接。
