手写一个最小 oh-my-pi Marketplace从 marketplace.json 格式到插件安装全流程【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本篇以 oh-my-pi 仓库自带的docs/skills/examples/mini-marketplace最小示例为主线完整讲解 marketplace 目录清单marketplace.json的字段规范、相对路径插件源的工作原理以及如何在 TUI 与 CLI 中把本地目录注册为插件市场并安装插件。读完你可以照此格式在自己的 Git 仓库或本地目录中发布一个可被 oh-my-pi 识别与安装的插件市场。什么是 marketplace 与 catalog在 oh-my-pi 中marketplace插件市场是一个 Git 仓库或本地目录根目录下必须包含一份名为marketplace.json的目录清单catalog。这份清单罗列了市场内可用插件及其来源、描述与元数据。plugin插件则是包含 Claude/OMP 插件内容的目录例如 skills、slash commands、agents、rules、hooks、tools、MCP servers 或 LSP servers也可以声明omp.extensions扩展模块。catalog 在 marketplace 根目录内的查找顺序有明确优先级对应 fetcher.ts 中的CATALOG_RELATIVE_PATHS.omp-plugin/marketplace.json首选oh-my-pi 原生路径.claude-plugin/marketplace.jsonClaude Code 兼容回退路径也就是说一个仓库可以同时发布两份 catalogoh-my-pi 读取.omp-plugin/副本Claude Code 读取.claude-plugin/副本两边格式相同。官方文档 marketplace.md 明确说明当 omp 是唯一消费方时优先使用.omp-plugin/路径若要保持 Claude Code 兼容性则发布到.claude-plugin/。mini-marketplace 示例选择的是.claude-plugin/marketplace.json兼容路径这正是它想演示的要点之一同一个格式、同一个加载位置本地市场与线上发布市场并无区别把/marketplace add指向这个文件夹即可加载。示例目录结构拆解仓库中 mini-marketplace 的实际文件布局如下docs/skills/examples/mini-marketplace/ .claude-plugin/ marketplace.json ← catalog 目录清单 README.md my-plugin/ package.json ← omp.extensions 清单 index.ts ← 扩展入口文件各文件职责文件作用.claude-plugin/marketplace.json市场目录清单声明市场名、归属者与插件条目my-plugin/package.json插件自身的 npm 清单通过omp.extensions字段声明扩展入口my-plugin/index.ts扩展入口导出默认函数注册session_start事件回调注意插件目录与 catalog 位于同一目录树内这是相对路径 source 能够生效的前提——安装时系统直接在 marketplace 根目录内解析./my-plugin。marketplace.json 的最小字段要求示例中的 catalogmarketplace.json内容如下{ name: example-marketplace, owner: { name: example }, description: Minimal marketplace demonstrating the catalog format, plugins: [ { name: my-plugin, description: Minimal extension bundled with this marketplace example, source: ./my-plugin } ] }对照解析器 fetcher.ts 的校验逻辑可以确认三个必需顶层字段字段类型说明namestring市场名必须是小写字母/数字/连字符/点组成首尾须为字母或数字最长 64 字符owner.namestring市场归属者名称pluginsarray插件条目数组每一项至少需要name与source示例还多写了一个顶层description字段。解析器在通过必需字段校验后会用展开spread方式保留所有额外顶层字段对应源码中的 Extra fields are preserved 注释因此这类附加元数据不会导致解析失败运行时行为只依赖必需字段与插件条目。若 catalog JSON 无法解析、或必需字段缺失/非法整个 catalog 会被拒绝而单个插件条目非法时解析器会记录 warning 并跳过该条不影响其他合法条目继续可用。插件条目的 source 字段插件条目中source是必填字段。字符串形式的 source必须以./开头否则解析器直接报错must start with ./。安装时相对路径会在 marketplace 根目录内解析并且有路径越界防护解析结果若逃逸出 marketplace 根目录会抛出resolves outside marketplace root异常见 source-resolver.ts。除字符串外source还支持对象形式可覆盖更多发布场景{ source: url, url: https://github.com/org/repo.git, sha: abc123... } { source: github, repo: org/repo, ref: main, sha: abc123... } { source: git-subdir, url: https://github.com/org/monorepo.git, path: plugins/my-plugin, ref: main } { source: npm, package: scope/my-plugin, version: 1.0.0 }其中npm类型目前仅能被解析有专门的必填字段校验安装时会被拒绝并提示npm plugin sources are not yet supported. Use git-based sources instead.生产发布请使用相对路径、GitHub、URL 或 git-subdir 来源。安装从本地目录加载示例市场将 mini-marketplace 注册为市场并安装插件有两种等价入口。TUI 内命令/marketplace add ./docs/skills/examples/mini-marketplace /marketplace install my-pluginexample-marketplace/marketplace add的参数就是市场来源支持 GitHub 简写owner/repo、Git URL、直链 JSON catalog URL、以及./path、~/path、/path本地目录等格式分类规则见 fetcher.ts。这里的./相对路径会被识别为 local 类型并解析为绝对路径后存入注册表。插件以namemarketplace标识安装即my-pluginexample-marketplace。CLI 等价命令omp plugin marketplace add ./docs/skills/examples/mini-marketplace omp plugin install my-pluginexample-marketplace两条命令与 TUI 版本一一对应。安装流程在 manager.ts 的installPlugin中依次完成查市场注册表 → 读 catalog 定位插件 → 解析 source → 计算版本号 → 缓存插件目录 → 写入installed_plugins.json→ 在对应 scope 的node_modules中创建符号链接并更新omp-plugins.lock.json运行时状态。安装 scope 与生效时机安装默认作用于user scope所有项目可用也可通过--scope project仅对当前项目生效project 安装会 shadow 同名 user 安装被 shadow 的条目在listInstalledPlugins中带shadowedBy标记且禁用的 project 安装不会 shadowuser 安装见 manager.ts。TUI 的安装操作会更新磁盘状态并使发现缓存失效但不会刷新当前会话skills、slash commands、MCP servers 需要执行/reload-plugins重新加载tools、hooks 或扩展模块则需要重启会话。插件侧omp.extensions 清单与运行时加载marketplace 安装不仅缓存目录还会把插件作为运行时包接入。插件根目录的package.json通过omp字段声明扩展模块package.json{ name: my-plugin, version: 0.1.0, homepage: https://omp.sh, omp: { extensions: [./index.ts] } }扩展加载器在 loader.ts 中读取清单readExtensionManifest依次查找pkg.omp与pkg.pi字段取extensions数组将每个入口解析为绝对路径未显式声明时也会回退到index.ts/index.js。这解释了 mini-marketplace 中 index.ts 的存在意义——它导出一个默认函数作为扩展工厂// ts-nocheck — example file; install oh-my-pi/pi-coding-agent before running import type { ExtensionAPI } from oh-my-pi/pi-coding-agent; export default function myPlugin(pi: ExtensionAPI) { pi.on(session_start, async (_event, ctx) { ctx.ui.notify(my-plugin loaded from example marketplace!, info); }); }运行时marketplace 安装与npm install、omp plugin link走的是同一套 surface安装器在 scope 的node_modules/下为缓存目录创建符号链接Windows 上使用 junction并在omp-plugins.lock.json中记录版本与启用状态manager.ts。插件版本号按「catalog 条目 version → 插件 manifest.claude-plugin/plugin.json、plugin.json、package.json依次尝试→ source 中的 git SHA 前 7 位 →0.0.0」的优先级推导#resolvePluginVersion同文件 L417-L443。命名规则市场名与插件名catalog 解析器通过isValidNameSegment强制校验详见 fetcher.ts 的name断言以一个小写字母或数字开头、结尾只包含小写字母、数字、连字符-与点.最长 64 个字符。插件 IDnamemarketplace总长不得超过 128 字符。合法示例my-plugin、code-review、wordpress.com、ai-firstify非法示例-bad、bad-、.bad、Bad、under_score下划线不被允许。mini-marketplace 中市场名example-marketplace与插件名my-plugin均符合该规范。从示例走向生产发布mini-marketplace 演示的是最小可用形态生产发布时可参考官方文档 marketplace.md 补充顶层元数据metadata.description、metadata.version、metadata.pluginRoot均为可选设置pluginRoot后相对路径 source 会先拼接该前缀再解析见 source-resolver.ts。插件条目完整字段除name/source外description、version、author、homepage、repository、license、keywords、category、tags均为可选元数据lspServers与dapAdapters会在安装时被写入缓存的.lsp.json/.dap.json或.dap.yaml、.dap.yml且路径有防目录逃逸校验manager.ts。来源类型注意通过直链 catalog URLhttps://...*.json添加的市场只缓存 catalog JSON其插件不能使用./相对字符串 source——安装器会直接报错并要求改用 git 或本地来源manager.ts。市场更新/marketplace update [name]只刷新 catalog不重装插件marketplace.autoUpdate配置off/notify/auto控制启动时对超过 24 小时未更新的 catalog 做尽力刷新。简而言之复制mini-marketplace的目录骨架把marketplace.json中的name、owner.name、plugins[].name与source换成你自己的市场名与插件路径用/marketplace add指向该目录即可完成一次本地插件市场的最小闭环验证。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考