AreChen
bfe3275e21
Constraint: Chinese users need localized plugin and skill descriptions while third-party sources must remain syncable from upstream. Rejected: Editing third-party generated files by hand | Sync would overwrite them and make localization drift from config. Rejected: One plugin per Three.js skill | Users should install one domain package while Codex can still select individual skills inside it. Confidence: high Scope-risk: moderate Directive: Keep plugin IDs and skill names in English kebab-case; put user-facing Chinese text in manifest fields, SKILL.md descriptions, or external-source overrides. Tested: Codex manual confirms duplicate skills are not merged; powershell sync_external_plugins.ps1 with proxy; python scripts\\validate_marketplace.py; validate_plugin.py for all plugins; codex plugin list local marketplace; codex plugin add/remove eapil-threejs. Not-tested: Codex Desktop visual refresh after pulling the updated remote marketplace.
131 lines
5.2 KiB
Markdown
131 lines
5.2 KiB
Markdown
# EAPIL Skill Market 维护指南
|
||
|
||
本仓库是 Codex 自定义插件市场，面向中文用户分发可选安装的技能包。后续维护时，以本文件作为仓库级工作约定。
|
||
|
||
## 关键原则
|
||
|
||
- 插件是分发单位，skill 是插件内部的能力单位。一个插件可以包含多个 skill。
|
||
- 市场中的插件默认使用 `policy.installation: "AVAILABLE"`，不要改成 `INSTALLED_BY_DEFAULT`，除非明确要求所有用户默认安装。
|
||
- 面向用户展示的名称、说明、分类可以使用中文。插件 ID、skill `name`、目录名保持英文 kebab-case，避免破坏安装标识和脚本路径。
|
||
- Codex 对同名 skill 不做合并；用户目录、仓库目录、插件目录里如果出现同名 skill，它们可能同时出现在选择器里。维护时尽量使用清晰、稳定的 skill 名称，避免让用户看到多个无法区分的同名入口。
|
||
- 第三方插件生成目录是同步产物。不要为了本地化直接手改 `plugins/codex/plugins/superpowers` 或 `plugins/codex/plugins/ui-ux-pro-max` 里的生成内容；应改 `config/external-sources.json` 的覆盖配置，再重新同步。
|
||
|
||
## 当前结构
|
||
|
||
市场入口：
|
||
|
||
- `.agents/plugins/marketplace.json`：仓库根市场入口，适合 Git 市场直接添加。
|
||
- `plugins/codex/.agents/plugins/marketplace.json`：兼容稀疏路径安装的嵌套市场入口。
|
||
|
||
插件目录：
|
||
|
||
- `plugins/codex/plugins/eapil-pdf`
|
||
- `plugins/codex/plugins/eapil-pptx`
|
||
- `plugins/codex/plugins/eapil-xlsx`
|
||
- `plugins/codex/plugins/eapil-threejs`
|
||
- `plugins/codex/plugins/superpowers`
|
||
- `plugins/codex/plugins/ui-ux-pro-max`
|
||
|
||
Three.js 相关 skill 统一放在 `eapil-threejs` 一个插件内，不再拆成多个 `eapil-threejs-*` 插件。这样用户只需要安装一个 Three.js 技能包，安装后 Codex 仍然可以在包内按具体 skill 选择场景、材质、灯光、交互、动画等工作流。
|
||
|
||
## 第三方 skill 引入流程
|
||
|
||
第三方来源统一配置在 `config/external-sources.json`：
|
||
|
||
- `adapter: "codex-plugin"`：上游本身已经是 Codex plugin，例如 `obra/superpowers`。
|
||
- `adapter: "claude-skill"`：上游是 Claude-style skill，需要转换成 Codex plugin，例如 `nextlevelbuilder/ui-ux-pro-max-skill`。
|
||
|
||
同步命令：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\sync_external_plugins.ps1
|
||
```
|
||
|
||
如果本地访问 GitHub 不稳定：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\sync_external_plugins.ps1 -Proxy http://127.0.0.1:18085
|
||
```
|
||
|
||
只同步某个来源：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\sync_external_plugins.ps1 -Only ui-ux-pro-max -Proxy http://127.0.0.1:18085
|
||
```
|
||
|
||
第三方本地化规则：
|
||
|
||
- 用 `manifestOverrides` 覆盖插件展示层字段，例如 `description`、`interface.displayName`、`interface.shortDescription`、`interface.category`、`interface.defaultPrompt`。
|
||
- 用 `skillDescriptions` 覆盖复制后 `SKILL.md` frontmatter 的 `description`。
|
||
- 覆盖配置会在每次同步后自动应用，因此不会阻碍后续拉取上游更新。
|
||
- `config/external-sources.lock.json` 记录上游 commit 和同步时间，不要手工编造。
|
||
|
||
## 自制 skill 添加流程
|
||
|
||
新增自制 skill 时优先判断分发粒度：
|
||
|
||
- 如果它是独立领域能力，创建一个新插件，例如 `eapil-pdf`。
|
||
- 如果它是某个已有领域的一部分，放进已有插件的 `skills/` 下，例如 Three.js 的新增材质、加载、调试类能力放进 `eapil-threejs`。
|
||
|
||
自制插件最低结构：
|
||
|
||
```text
|
||
plugins/codex/plugins/<plugin-name>/
|
||
.codex-plugin/plugin.json
|
||
skills/<skill-name>/SKILL.md
|
||
```
|
||
|
||
新增自制插件后必须同时更新两个 marketplace：
|
||
|
||
- `.agents/plugins/marketplace.json`
|
||
- `plugins/codex/.agents/plugins/marketplace.json`
|
||
|
||
两个 marketplace 的插件列表、分类和安装策略应保持一致；只有 `source.path` 前缀不同。
|
||
|
||
自制插件中文展示建议：
|
||
|
||
- `plugin.json` 的 `description`、`interface.shortDescription`、`interface.longDescription`、`interface.category` 可以使用中文。
|
||
- `SKILL.md` frontmatter 的 `description` 可以使用中文，也可以保留必要英文关键词帮助英文触发。
|
||
- `name` 字段保持英文 kebab-case。
|
||
|
||
## 验证
|
||
|
||
每次改动后至少运行：
|
||
|
||
```powershell
|
||
python scripts\validate_marketplace.py
|
||
```
|
||
|
||
涉及单个插件结构时运行：
|
||
|
||
```powershell
|
||
python C:\Users\cmx27\.codex\skills\.system\plugin-creator\scripts\validate_plugin.py plugins\codex\plugins\<plugin-name>
|
||
```
|
||
|
||
需要验证 Codex 安装行为时：
|
||
|
||
```powershell
|
||
codex plugin marketplace add . --json
|
||
codex plugin list --marketplace eapil-skill-market --available --json
|
||
codex plugin add <plugin-name>@eapil-skill-market --json
|
||
codex plugin remove <plugin-name>@eapil-skill-market --json
|
||
```
|
||
|
||
本地测试安装后记得移除测试插件，避免 Codex Desktop 显示为已启用而误判为市场默认安装。
|
||
|
||
## 提交要求
|
||
|
||
提交信息应说明为什么改，而不只是列出改了什么。推荐包含：
|
||
|
||
```text
|
||
<intent line>
|
||
|
||
Constraint: <约束>
|
||
Rejected: <拒绝的方案> | <原因>
|
||
Confidence: <low|medium|high>
|
||
Scope-risk: <narrow|moderate|broad>
|
||
Directive: <后续维护提醒>
|
||
Tested: <已验证>
|
||
Not-tested: <未验证>
|
||
```
|