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.
2026-06-11 10:09:37 +08:00
parent aa95508ed6
commit 6d2ece1590
7 changed files with 224 additions and 66 deletions
@@ -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": {
@@ -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/<plugin-name>` 目录都是独立插件，用户可以只安装自己需要的插件。插件内可以包含一个或多个相关 Skill。
@@ -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": []
+  }
+}
@@ -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/<name>/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/<plugin-name>
+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` 条目是否同步。
+- 已运行的验证命令和任何未验证风险。