KeyInfo Bot
488e2bd620
Constraint: This repository is a skill distribution snapshot, so download size matters more than historical auditability. Rejected: Preserve prior Git history | Old large blobs keep clone size high and do not help skill consumers. Confidence: high Scope-risk: broad Directive: Future market updates should be validated, then collapsed to a fresh snapshot commit before push. Tested: python scripts/validate_marketplace.py; validate_plugin.py plugins/codex/plugins/ppt-master; 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; git diff --check; Codex temp install/use test for ppt-master Not-tested: PowerShell execution because pwsh/powershell is not installed locally.
5.2 KiB
5.2 KiB
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/<plugin-name>/。当前市场包含自制公开插件和可同步第三方插件，具体插件列表以两个 marketplace 文件为准：
.agents/plugins/marketplace.jsonplugins/codex/.agents/plugins/marketplace.json
当前市场只保留正式公开插件。历史测试插件不应继续出现在 marketplace 或 plugins/codex/plugins/ 下，下一次发布或同步时也应移除未被索引的测试目录，避免用户安装到过期能力。
第三方 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 -ExecutionPolicy Bypass -File .\scripts\sync_external_plugins.ps1
如果本地访问 GitHub 不稳定：
powershell -ExecutionPolicy Bypass -File .\scripts\sync_external_plugins.ps1 -Proxy http://127.0.0.1:18085
只同步某个来源：
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.mdfrontmatter 的description。 - 覆盖配置会在每次同步后自动应用，因此不会阻碍后续拉取上游更新。
config/external-sources.lock.json记录上游 commit 和同步时间，不要手工编造。
自制 skill 添加流程
新增自制 skill 时优先判断分发粒度：
- 如果它是独立领域能力，创建一个新插件，例如
docx或新的英文 kebab-case 插件名。 - 如果它是某个已有领域的一部分，放进已有插件的
skills/下。一个目录下有多个相关 skill 时仍视为一个插件，用户安装和卸载以插件为单位。
自制插件最低结构：
plugins/codex/plugins/<plugin-name>/
.codex-plugin/plugin.json
skills/<skill-name>/SKILL.md
新增自制插件后必须同时更新两个 marketplace：
.agents/plugins/marketplace.jsonplugins/codex/.agents/plugins/marketplace.json
两个 marketplace 的插件列表、分类和安装策略应保持一致；只有 source.path 前缀不同。
自制插件中文展示建议：
plugin.json的description、interface.shortDescription、interface.longDescription、interface.category可以使用中文。SKILL.mdfrontmatter 的description可以使用中文，也可以保留必要英文关键词帮助英文触发。name字段保持英文 kebab-case。
验证
每次改动后至少运行：
python scripts\validate_marketplace.py
涉及单个插件结构时运行：
python C:\Users\cmx27\.codex\skills\.system\plugin-creator\scripts\validate_plugin.py plugins\codex\plugins\<plugin-name>
需要验证 Codex 安装行为时：
codex plugin marketplace add .
codex plugin list --marketplace eapil-skill-market
codex plugin add <plugin-name>@eapil-skill-market
codex plugin remove <plugin-name>@eapil-skill-market
本地测试安装后记得移除测试插件，避免 Codex Desktop 显示为已启用而误判为市场默认安装。
提交要求
提交信息应说明为什么改，而不只是列出改了什么。推荐包含：
<intent line>
Constraint: <约束>
Rejected: <拒绝的方案> | <原因>
Confidence: <low|medium|high>
Scope-risk: <narrow|moderate|broad>
Directive: <后续维护提醒>
Tested: <已验证>
Not-tested: <未验证>