From 6d2ece159062c099cd8debd7367002f1451edcc9 Mon Sep 17 00:00:00 2001 From: KeyInfo Bot Date: Thu, 11 Jun 2026 10:09:37 +0800 Subject: [PATCH] Make marketplace onboarding formal for Chinese users Add a market-source-adapter plugin so maintainers have a reusable workflow for adapting third-party skill repositories while replacing the old test-oriented README with official Chinese marketplace guidance. Constraint: Public plugins must remain installable as independent Codex plugins and Chinese-facing fields must be localized without changing stable plugin IDs. Rejected: Keep adapter guidance only in README | Maintainers need it as an installable skill available from the same marketplace and KeyInfo skill generation page. Confidence: high Scope-risk: narrow Directive: Add future third-party repository structures as explicit adapters or source config, not one-off copy steps. Tested: python scripts/validate_marketplace.py; python /Users/eapil/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/codex/plugins/market-source-adapter; python /Users/eapil/.codex/skills/.system/skill-creator/scripts/quick_validate.py backend/data/skill_market_repo/plugins/codex/plugins/market-source-adapter/skills/market-source-adapter; node local skills.json visibility check Not-tested: Installing market-source-adapter through Codex Desktop UI. --- .agents/plugins/marketplace.json | 12 ++ AGENTS.md | 7 +- README.md | 128 ++++++++++-------- .../codex/.agents/plugins/marketplace.json | 12 ++ plugins/codex/README.md | 22 ++- .../.codex-plugin/plugin.json | 38 ++++++ .../skills/market-source-adapter/SKILL.md | 71 ++++++++++ 7 files changed, 224 insertions(+), 66 deletions(-) create mode 100644 plugins/codex/plugins/market-source-adapter/.codex-plugin/plugin.json create mode 100644 plugins/codex/plugins/market-source-adapter/skills/market-source-adapter/SKILL.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index b2167356d..e25879022 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -148,6 +148,18 @@ }, "category": "开发工具" }, + { + "name": "market-source-adapter", + "source": { + "source": "local", + "path": "./plugins/codex/plugins/market-source-adapter" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "开发工具" + }, { "name": "eapil-gpt2-image", "source": { diff --git a/AGENTS.md b/AGENTS.md index 5d88996cf..6bc30be51 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,11 +17,10 @@ - `.agents/plugins/marketplace.json`：仓库根市场入口，适合 Git 市场直接添加。 - `plugins/codex/.agents/plugins/marketplace.json`：兼容稀疏路径安装的嵌套市场入口。 -插件目录： +插件目录统一放在 `plugins/codex/plugins//`。当前市场包含自制公开插件和可同步第三方插件，具体插件列表以两个 marketplace 文件为准： -- `plugins/codex/plugins/docx` -- `plugins/codex/plugins/superpowers` -- `plugins/codex/plugins/ui-ux-pro-max` +- `.agents/plugins/marketplace.json` +- `plugins/codex/.agents/plugins/marketplace.json` 当前市场只保留正式公开插件。历史测试插件不应继续出现在 marketplace 或 `plugins/codex/plugins/` 下，下一次发布或同步时也应移除未被索引的测试目录，避免用户安装到过期能力。 diff --git a/README.md b/README.md index d5658d018..24f916cb3 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,121 @@ -# EAPIL Skill Market +# EAPIL Codex 插件市场 -Codex custom plugin marketplace test repository. +这是 EAPIL 内部维护的 Codex 插件市场，面向中文用户分发可选安装的公开 Skill 和第三方插件。仓库已经作为正式市场使用，不再是测试仓库。 -## Desktop test +## 安装市场 -In **Add plugin marketplace**: +在 Codex Desktop 的“添加插件市场”中填写： -- Source: `https://git.playones.com/arechen/EapilSkillMarket.git` -- Git ref: `main` -- Sparse path: leave empty +- 来源：`https://git.playones.com/arechen/EapilSkillMarket.git` +- Git 引用：`main` +- 稀疏路径：留空 -After the marketplace is added, install only the plugin you need from the `EAPIL Skill Market` marketplace. +添加市场后，在 `EAPIL 技能市场` 中按需安装插件。安装或更新插件后，建议新开一个 Codex 线程，让新 Skill 进入上下文。 -If you want to use sparse checkout, enter both paths if the UI allows multiple lines: - -```text -.agents -plugins/codex -``` - -## CLI test +命令行安装： ```powershell codex plugin marketplace add https://git.playones.com/arechen/EapilSkillMarket.git --ref main codex plugin add docx@eapil-skill-market ``` -Sparse CLI form: +如果需要使用稀疏路径： ```powershell codex plugin marketplace add https://git.playones.com/arechen/EapilSkillMarket.git --ref main --sparse .agents --sparse plugins/codex codex plugin add superpowers@eapil-skill-market ``` -For local testing before pushing: +## 当前插件 -```powershell -codex plugin marketplace add . -codex plugin add ui-ux-pro-max@eapil-skill-market -``` +市场中的每个目录都是一个独立 Codex 插件，用户可以按需安装和卸载： -Start a new Codex thread after installing so the new skills are loaded into context. +- `superpowers`：规划、TDD、调试、代码评审和交付工作流。 +- `ui-ux-pro-max`：UI/UX 设计知识库。 +- `docx`：Word 文档创建、编辑和分析。 +- `pdf`：PDF 表单、文本、表格和文档处理。 +- `pptx`：演示文稿创建、编辑和分析。 +- `xlsx`：电子表格创建、编辑、分析和可视化。 +- `threejs`：Three.js 开发相关 Skill 集合。 +- `postgres`：PostgreSQL 查询与维护辅助。 +- `literature-review`：文献综述与论文阅读辅助。 +- `paper2code`：论文复现与代码实现辅助。 +- `find-skills`：帮助发现可安装 Skill。 +- `karpathy-guidelines`：Karpathy 风格的代码与模型训练指导原则。 +- `market-source-adapter`：第三方 Skill/插件仓库市场源适配流程。 +- `eapil-gpt2-image`：EAPIL 图像生成相关能力。 -## Plugins - -- `docx` -- `superpowers` -- `ui-ux-pro-max` - -List available plugins: +查看市场插件： ```powershell codex plugin list --marketplace eapil-skill-market ``` -Remove an installed plugin: +移除插件： ```powershell codex plugin remove docx@eapil-skill-market ``` -## External sync +## 维护原则 -Third-party plugins are configured in `config/external-sources.json` and synced with: +- 插件是安装单位，Skill 是插件内部能力单位。 +- 插件 ID、目录名和 Skill `name` 使用英文 kebab-case，避免破坏安装标识。 +- 面向用户的 `description`、`displayName`、`shortDescription`、`longDescription`、`category` 使用中文。 +- 第三方插件通过配置和适配器同步，不直接手改生成目录里的本地化内容。 +- 公开 Skill 应同时出现在市场仓库和 KeyInfo 的 Skill 生成页；私有 Skill 保留在 KeyInfo 内部下载/导出流程中。 + +## 第三方来源同步 + +第三方来源配置在 `config/external-sources.json`，当前支持： + +- `codex-plugin`：上游本身是 Codex 插件，例如 `obra/superpowers`。 +- `claude-skill`：上游是 Claude-style Skill，需要转换为 Codex 插件，例如 `nextlevelbuilder/ui-ux-pro-max-skill`。 + +同步时使用 KeyInfo 后端的市场同步逻辑，确保市场仓库和 KeyInfo 运行时 Skill 索引一起更新。市场仓库内的脚本可用于独立维护或本地验证： ```powershell powershell -ExecutionPolicy Bypass -File .\scripts\sync_external_plugins.ps1 ``` -If GitHub access is unstable locally, use the proxy: +如果本地访问 GitHub 不稳定，可以指定代理： ```powershell powershell -ExecutionPolicy Bypass -File .\scripts\sync_external_plugins.ps1 -Proxy http://127.0.0.1:18085 ``` -The sync script currently supports: +第三方本地化请写入 `manifestOverrides` 和 `skillDescriptions`，这些覆盖会在每次同步后重新应用。 -- `codex-plugin`: mirrors an upstream Codex plugin repo, used for `obra/superpowers`. -- `claude-skill`: converts one Claude-style skill directory into a Codex plugin, used for `nextlevelbuilder/ui-ux-pro-max-skill`. - -Use `manifestOverrides` and `skillDescriptions` in `config/external-sources.json` for local Chinese UI text and skill descriptions. These overlays are applied after each upstream sync, so do not edit generated third-party plugin files directly for localization. - -After sync, validate the marketplace: - -```powershell -python scripts\validate_marketplace.py -``` - -Periodic sync should call the script directly from a maintenance process, cron job, or service container. Keep the scheduling layer outside this repository; the repository only defines source config, generated plugin output, and validation. - -## Layout +## 仓库结构 ```text .agents/plugins/marketplace.json plugins/codex/ .agents/plugins/marketplace.json - plugins/docx/ + plugins// .codex-plugin/plugin.json - skills/docx/ - plugins/superpowers/ - .codex-plugin/plugin.json - skills/ - plugins/ui-ux-pro-max/ - .codex-plugin/plugin.json - skills/ui-ux-pro-max/ + skills//SKILL.md +config/external-sources.json +scripts/validate_marketplace.py +``` + +## 验证 + +提交前至少运行： + +```bash +python scripts/validate_marketplace.py +``` + +验证单个插件结构： + +```bash +python /Users/eapil/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/codex/plugins/ +``` + +本地测试市场安装： + +```powershell +codex plugin marketplace add . +codex plugin add market-source-adapter@eapil-skill-market ``` diff --git a/plugins/codex/.agents/plugins/marketplace.json b/plugins/codex/.agents/plugins/marketplace.json index a02e2b9e0..3dac7e534 100644 --- a/plugins/codex/.agents/plugins/marketplace.json +++ b/plugins/codex/.agents/plugins/marketplace.json @@ -148,6 +148,18 @@ }, "category": "开发工具" }, + { + "name": "market-source-adapter", + "source": { + "source": "local", + "path": "./plugins/market-source-adapter" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "开发工具" + }, { "name": "eapil-gpt2-image", "source": { diff --git a/plugins/codex/README.md b/plugins/codex/README.md index 9b27da2e3..04c837dbf 100644 --- a/plugins/codex/README.md +++ b/plugins/codex/README.md @@ -1,12 +1,24 @@ -# Codex Marketplace Root +# Codex 插件市场目录 -This directory can be used as a local marketplace root: +这个目录是 EAPIL Codex 插件市场的稀疏安装入口。通常推荐从仓库根目录添加市场，并把稀疏路径留空；只有在需要减少拉取范围时才使用本目录。 + +从仓库根目录安装市场： + +```powershell +codex plugin marketplace add https://git.playones.com/arechen/EapilSkillMarket.git --ref main +``` + +使用稀疏路径安装市场： + +```powershell +codex plugin marketplace add https://git.playones.com/arechen/EapilSkillMarket.git --ref main --sparse .agents --sparse plugins/codex +``` + +本地调试： ```powershell codex plugin marketplace add .\plugins\codex codex plugin add docx@eapil-skill-market ``` -For Git marketplace testing from the repository root, prefer the root `.agents/plugins/marketplace.json` entry and leave sparse checkout empty. - -Each skill directory is packaged as a separate plugin so users can install only what they need. +每个 `plugins/` 目录都是独立插件，用户可以只安装自己需要的插件。插件内可以包含一个或多个相关 Skill。 diff --git a/plugins/codex/plugins/market-source-adapter/.codex-plugin/plugin.json b/plugins/codex/plugins/market-source-adapter/.codex-plugin/plugin.json new file mode 100644 index 000000000..93f65afd4 --- /dev/null +++ b/plugins/codex/plugins/market-source-adapter/.codex-plugin/plugin.json @@ -0,0 +1,38 @@ +{ + "name": "market-source-adapter", + "version": "1.0.0", + "description": "用于把结构各异的第三方 skill 或 Codex 插件仓库适配进 EAPIL Skill Market，并同步到 KeyInfo 的 Skill 生成页。", + "author": { + "name": "EAPIL", + "url": "https://git.playones.com/arechen/EapilSkillMarket" + }, + "homepage": "https://git.playones.com/arechen/EapilSkillMarket", + "repository": "https://git.playones.com/arechen/EapilSkillMarket", + "license": "Proprietary", + "keywords": [ + "eapil", + "codex-skill", + "marketplace", + "adapter" + ], + "skills": "./skills/", + "interface": { + "displayName": "市场源适配器", + "shortDescription": "为第三方 skill/plugin 仓库设计同步适配方案。", + "longDescription": "当第三方仓库目录结构不统一时，市场源适配器用于判断仓库形态、确定插件分发粒度、编写同步适配逻辑，并确保公开插件同时出现在 EAPIL Skill Market 和 KeyInfo 的 Skill 生成页。", + "developerName": "EAPIL", + "category": "开发工具", + "capabilities": [ + "Read", + "Write" + ], + "defaultPrompt": [ + "使用市场源适配器帮我把这个第三方 skill 仓库接入 EAPIL Skill Market。" + ], + "websiteURL": "https://git.playones.com/arechen/EapilSkillMarket", + "privacyPolicyURL": "https://git.playones.com/arechen/EapilSkillMarket", + "termsOfServiceURL": "https://git.playones.com/arechen/EapilSkillMarket", + "brandColor": "#2563EB", + "screenshots": [] + } +} diff --git a/plugins/codex/plugins/market-source-adapter/skills/market-source-adapter/SKILL.md b/plugins/codex/plugins/market-source-adapter/skills/market-source-adapter/SKILL.md new file mode 100644 index 000000000..58bcadcca --- /dev/null +++ b/plugins/codex/plugins/market-source-adapter/skills/market-source-adapter/SKILL.md @@ -0,0 +1,71 @@ +--- +name: market-source-adapter +description: 当需要把目录结构各不相同的第三方 skill、Claude skill、Codex plugin 或技能集合仓库接入 EAPIL Skill Market，并确保它同时出现在 KeyInfo 的 Skill 生成页时使用。适用于新增外部市场源、设计同步适配器、改造 external-sources 配置、维护公开/私有 skill 分发边界。 +--- + +# 市场源适配器 + +用于把第三方 skill 或插件仓库接入 EAPIL Skill Market。目标不是一次性复制文件，而是形成可重复同步、可验证、可本地化的适配流程，并让公开插件同时进入： + +- EAPIL Skill Market 的 Codex 插件目录。 +- KeyInfo 的 `backend/data/skills_collection` 运行时目录和 `skills.json` 索引，从而出现在 Skill 生成页。 + +## 快速判断 + +先用 `rg --files` 或等价命令扫仓库结构，再按以下顺序分类： + +1. **Codex plugin**：存在 `.codex-plugin/plugin.json`，且 manifest 指向 `skills` 目录。优先使用现有 `codex-plugin` 适配器。 +2. **Claude-style skill**：存在 `.claude/skills//SKILL.md` 或单个 `SKILL.md` 配合 `skill.json` 元数据。优先使用或扩展 `claude-skill` 适配器。 +3. **单 skill 仓库**：只有一个明确的 `SKILL.md`，但路径不符合现有适配器。给该结构增加显式配置项或新适配器，不要写一次性复制脚本。 +4. **skill 集合仓库**：多个相关 `*/SKILL.md` 属于同一领域，例如 Three.js 系列。作为一个插件发布，插件下保留多个 skill。 +5. **混合仓库**：同时含 docs、examples、packages、多个无关 skill。先列出可发布单元，再决定拆成多个插件或只接入其中一个路径。 + +## 接入流程 + +1. **确认分发单元** + - 一个独立能力对应一个插件。 + - 一个强相关集合对应一个插件，插件内可以包含多个 skill。 + - 不相关的 skill 不要塞进同一个插件，避免用户无法按需安装/卸载。 + +2. **确定适配来源** + - 第三方公开来源写入市场仓库 `config/external-sources.json`。 + - 如果现有 `codex-plugin` 或 `claude-skill` 无法表达目录结构，在 KeyInfo `backend/skill_market.py` 增加命名清晰的新适配器。 + - 新适配器必须有测试覆盖，包括路径解析、manifest 生成、本地化覆盖和错误信息。 + +3. **本地化展示信息** + - 插件 ID、skill `name`、目录名使用英文 kebab-case。 + - `plugin.json` 的 `description`、`interface.displayName`、`shortDescription`、`longDescription`、`category` 使用中文。 + - 第三方内容不要直接手改生成文件；把中文覆盖放进 `manifestOverrides` 和 `skillDescriptions`，让下次同步还能保留本地化。 + +4. **同步到 KeyInfo 生成页** + - 公开第三方插件同步后必须调用或复用 `sync_third_party_catalog_skills`，把插件 skill 写入 `backend/data/skills_collection`。 + - `skills.json` 条目应包含 `visibility: "public"`、`marketSource: "third_party"`、`marketStatus: "published"` 和 `marketPluginName`。 + - 自有公开 skill 走管理员发布流程；第三方已由市场仓库追踪的 skill 不应再进入“发布全部待发布”。 + +5. **处理异常结构** + - 如果上游删除了某个 skill，下一次同步应移除市场插件中的旧文件，并更新 KeyInfo 运行时目录。 + - 如果路径匹配多个 `SKILL.md`，不要猜默认入口；把选择规则写进 source 配置或适配器测试。 + - 如果上游 manifest 缺字段，生成最小合法 Codex plugin manifest，并用中文覆盖补齐界面字段。 + +## 验证清单 + +在声称接入完成前运行与改动面匹配的验证： + +```bash +python scripts/validate_marketplace.py +python /Users/eapil/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/codex/plugins/ +uv run python -m pytest backend/tests/test_skill_market_publish.py backend/tests/test_skill_market_scheduler.py -q +node web/tests/skills-market-ui.test.mjs +``` + +如果新增了适配器，还要补并运行对应的后端测试。若需要证明 KeyInfo Skill 生成页可见，检查 `backend/data/skills_collection/skills.json` 中对应条目，并确认该条目为 `public`。 + +## 输出要求 + +完成接入时，报告以下内容： + +- 上游仓库、ref、commit。 +- 使用的适配器类型和插件名。 +- 市场仓库中生成或更新的插件路径。 +- KeyInfo 运行时目录和 `skills.json` 条目是否同步。 +- 已运行的验证命令和任何未验证风险。