KeyInfo Bot
fca5c80516
Constraint: The public marketplace must not contain internal MCP endpoints, shared keys, project keys, or user-token workflows. Rejected: Publishing every configured KeyInfo MCP server | internal knowledge, Firecrawl, and Outline servers are not public distribution targets. Confidence: high Scope-risk: moderate Directive: Keep MCP publication behind an explicit allowlist and verify hidden plugin metadata before pushing. Tested: python scripts/validate_marketplace.py; temporary CODEX_HOME marketplace list/add/remove for mcp-playwright; hidden rg scan for internal MCP URLs and key markers. Not-tested: Live Playwright MCP browser tool invocation inside a fresh Codex session.
138 lines
5.6 KiB
Markdown
138 lines
5.6 KiB
Markdown
# EAPIL Codex 插件市场
|
||
|
||
这是 EAPIL 维护的 Codex 插件市场。首要用途是让 AI agent 能稳定安装公共 skills、MCP 插件和第三方 Codex plugin。
|
||
|
||
## 给 AI 的安装流程
|
||
|
||
当用户要求安装或使用 EAPIL 插件时，优先执行：
|
||
|
||
```bash
|
||
codex plugin marketplace add https://git.playones.com/arechen/EapilSkillMarket.git --ref main
|
||
codex plugin marketplace upgrade eapil-skill-market
|
||
codex plugin list --marketplace eapil-skill-market
|
||
codex plugin add <plugin-id>@eapil-skill-market
|
||
```
|
||
|
||
使用 `codex plugin list --marketplace eapil-skill-market` 输出里的精确 `plugin-id`。不要猜测中文名、翻译名或 display name。
|
||
|
||
如果插件刚安装到当前 Codex 会话中，启动新的 Codex thread 或新的 Codex 调用后再依赖新增 skills/hooks/MCP/app 配置。
|
||
|
||
卸载插件：
|
||
|
||
```bash
|
||
codex plugin remove <plugin-id>@eapil-skill-market
|
||
```
|
||
|
||
## 本地调试安装
|
||
|
||
从本仓库 checkout 调试：
|
||
|
||
```bash
|
||
codex plugin marketplace add .
|
||
codex plugin list --marketplace eapil-skill-market
|
||
codex plugin add docx@eapil-skill-market
|
||
```
|
||
|
||
临时干净环境验收：
|
||
|
||
```bash
|
||
tmp_home="$(mktemp -d)"
|
||
CODEX_HOME="$tmp_home" codex plugin marketplace add /path/to/EapilSkillMarket
|
||
CODEX_HOME="$tmp_home" codex plugin list --marketplace eapil-skill-market
|
||
CODEX_HOME="$tmp_home" codex plugin add <plugin-id>@eapil-skill-market
|
||
CODEX_HOME="$tmp_home" codex plugin remove <plugin-id>@eapil-skill-market
|
||
CODEX_HOME="$tmp_home" codex plugin marketplace remove eapil-skill-market
|
||
rm -rf "$tmp_home"
|
||
```
|
||
|
||
## MCP 插件
|
||
|
||
当前公开仓库只发布 `mcp-playwright`。KeyInfo 主项目里还维护了内部知识库、Firecrawl、Outline 等 MCP，但这些依赖内部地址、项目 Key、shared key 或用户私有 token，不能进入公开 Git 仓库。
|
||
|
||
`mcp-playwright` 是本地 MCP 插件：
|
||
|
||
- 插件 ID：`mcp-playwright`
|
||
- MCP server id：`playwright`
|
||
- 本地命令：`bunx @playwright/mcp@latest`
|
||
- 鉴权：无
|
||
|
||
安装后如需覆盖启用状态或审批策略，可在用户 Codex 配置里追加：
|
||
|
||
```toml
|
||
[plugins."mcp-playwright@eapil-skill-market".mcp_servers.playwright]
|
||
enabled = true
|
||
```
|
||
|
||
后端自动同步公开 MCP 时只读取 `SKILL_MARKET_PUBLIC_MCP_IDS` allowlist，默认值是 `playwright`。除非确认目标 MCP 可公开、无内部 URL/密钥泄露风险，否则不要加入 allowlist。
|
||
|
||
## 官方插件能力
|
||
|
||
本市场按 Codex 官方插件能力校验和发布，插件可以包含：
|
||
|
||
- `skills`：`./skills/` 下的一个或多个 `SKILL.md`。
|
||
- `mcpServers`：通常是 `./.mcp.json`，允许 MCP-only 插件。
|
||
- `apps`：通常是 `./.app.json`，用于 app connector metadata。
|
||
- `hooks`：插件作用域 Codex hooks，可为路径、路径数组、inline object 或 object 数组。
|
||
- `interface` / `assets`：`interface.logo`、`interface.composerIcon`、`interface.screenshots` 可引用插件内 `assets/` 文件或公开 URL。
|
||
|
||
市场校验器会检查 plugin id、manifest `name` 和目录名必须是 ASCII kebab-case；中文只能用于 `interface.displayName`、说明文案和分类等展示字段。
|
||
|
||
## 仓库结构
|
||
|
||
```text
|
||
.agents/plugins/marketplace.json
|
||
plugins/codex/
|
||
.agents/plugins/marketplace.json
|
||
plugins/<plugin-id>/
|
||
.codex-plugin/plugin.json
|
||
skills/<skill-name>/SKILL.md # 可选
|
||
.mcp.json # 可选
|
||
.app.json # 可选
|
||
hooks/ # 可选
|
||
assets/ # 可选
|
||
config/external-sources.json
|
||
scripts/validate_marketplace.py
|
||
```
|
||
|
||
## 维护规则
|
||
|
||
- README 正文统一使用简体中文；插件 ID、命令、配置键和上游专有名称保留原文。
|
||
- 日常发布保留普通线性 Git 历史，使用普通 `git add -A`、`git commit`、`git push`，让 Codex marketplace 刷新获得增量传输收益。
|
||
- 只有误同步大文件或用户明确要求历史清理时，才做一次性历史压缩。
|
||
- 每次新增、替换、重命名、移除 public skill/plugin，或新增 hooks/MCP/apps/assets 等能力后，都要同步更新本 README 和 `plugins/codex/README.md`。
|
||
- 不要同步 README-only 预览 GIF/截图。skill/reference 真正需要的图片保留并压缩为 WebP。
|
||
- 第三方插件本地化写入 `config/external-sources.json` 的 `manifestOverrides` 和 `skillDescriptions`，不要直接手改生成 manifest。
|
||
- KeyInfo 内部 MCP 默认不公开。公开 MCP 必须经过 `SKILL_MARKET_PUBLIC_MCP_IDS` allowlist，并确认无内部 URL、shared key、项目 key 或用户 token 泄露风险。
|
||
|
||
## 第三方同步
|
||
|
||
第三方来源记录在 `config/external-sources.json`。
|
||
|
||
支持的适配器：
|
||
|
||
- `codex-plugin`：上游已经是 Codex plugin。
|
||
- `claude-skill`：上游是 Claude-style skill，会转换为 Codex plugin。
|
||
|
||
PowerShell 独立同步：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\sync_external_plugins.ps1
|
||
```
|
||
|
||
带代理：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\sync_external_plugins.ps1 -Proxy http://127.0.0.1:2085
|
||
```
|
||
|
||
## 发布前验证
|
||
|
||
```bash
|
||
python scripts/validate_marketplace.py
|
||
rg -n "<plugin-id>|<display-name>" README.md plugins/codex/README.md
|
||
```
|
||
|
||
对包含 `skills` 的插件，可额外运行系统 `validate_plugin.py`。不要用旧 validator 降级官方能力；MCP-only、app-only 或 hooks-only 插件以本仓库 marketplace 校验和 Codex 实装验收为准。
|
||
|
||
对新增插件，还要使用临时 `CODEX_HOME` 安装，并执行最小安全调用，证明 Codex 能加载该插件。MCP-only 插件至少要验证 marketplace list/add 成功，并检查 `.mcp.json` 已进入插件缓存；真实 MCP tool 调用可能依赖本地命令、浏览器权限或 token。
|