treg 的 Codex/ChatGPT 插件：单一源生成、本地验证与上架清单的全流程解析

后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载treg 是一个面向 Agent 的工具目录服务项目自称 OpenRouter for agent tools一个 token、一个代理入口即可按次计费调用数千个外部数据端点无需为每个数据商开户。本文聚焦仓库中plugin/目录下的Codex/ChatGPT 插件讲解它为什么被设计成分发包装层而非独立产品、技能文件如何从唯一源码自动生成、如何用 Codex CLI 在本地完成验证以及上架前清单文案必须守住的产品边界。读完你可以照搬这套流程在自己的仓库里复现同样的插件发布管线。插件在 treg 分发体系中的定位plugin/README.md第一句话就给出了它的定位distribution wrapper分发包装层不是第二个产品。它打包的正是treg skill bootstrap命令原本就会装进~/.codex/skills/的那份技能文件打包的目的是让用户在 ChatGPT 与 Codex 共用的插件目录里搜索到 treg。treg 共有五个橱窗shop window全部由同一个脚本渲染橱窗位置形态说明Codex / ChatGPTplugin/manifest MCP 连接器本文主角上架走审核队列Claude Code仓库根skills/treg/纯技能无连接器安装零配置、无 token见 docs/CLAUDE-PLUGIN.mdCursorplugins/treg/技能 MCP遵循 Cursor 自有目录规范DeepSeek Harnesspackage.jsondsh/npm 包MCP 行默认禁用见 docs/DSH-PLUGIN.mdMiniMaxplugins/minimax/纯技能包内禁止任何凭据见 docs/MINIMAX-PLUGIN.md五者都从src/treg/web/skill.md这一个源渲染区别只在于前置的 bootstrap 引导段落。build_plugin.py 的模块文档 明确记录了这种一个源、五个橱窗、四种 bootstrap的设计手抄一份技能文件等于制造第二个真相源产品每次迭代服务端副本都会变化插件却可能悄悄落后——所以必须生成并由 tests/test_plugin.py 在检查到陈旧副本时让测试失败。目录结构plugin/ ├── .codex-plugin/plugin.json # manifest 上架文案 ├── .mcp.json # MCP 连接器声明 ├── skills/treg/SKILL.md # GENERATED —— 禁止手改 └── assets/ # icon.svg / icon.png / logo.png品牌资产黑白 ▚ 标与刻意填充的图标plugin/assets/下有两张图logo.png1024×1024与icon.png512×512是纯黑白的▚标记——黑色圆角方块上两个白色象限。它们不是放大缩小的位图而是从 assets/brand/twitter/avatar-dark.svg 的几何参数按比例渲染的因此任意尺寸重渲染都精确viewBox 512 · 外圆角 rx 112 · 象限 140.5² 位于 (111,111) 与 (260.5,260.5)圆角 rx 20plugin/assets/icon.svg 特意选用实心版本而非透明的mark-white.svg白色透明标记在浅色背景上会消失而composerIcon渲染在宿主 UI 中其背景色我们无法控制实心版才能保证可见。值得注意的细节interface.brandColor仍是陶土色#e0703ftreg.to 的产品色。README 明确说明这是黑白标记旁的点缀色不算冲突但若品牌色迁移两处必须同步修改。技能是生成的一个源、两种转换、防漂移测试src/treg/web/skill.md是唯一源码同时承担三重职责在/skill.md提供 HTTP 服务、被treg skill bootstrap写入各 Agent、被渲染进本插件。生成命令python3 scripts/build_plugin.py # 重新生成全部插件 python3 scripts/build_plugin.py --check # 若任一已入库副本陈旧则失败也是测试与线上副本相比插件版本有两处不同都是因为插件到达之处没有服务器{BASE}被烘焙为公网部署地址。服务端按请求替换该占位符已安装的插件内没有任何机制做替换直接拷原始文件会把字面量{BASE}带出去页面上每个 URL 都会失效。从源码看build_plugin.py 中PUBLIC_BASE https://treg.torender()在最后out.replace({BASE}, PUBLIC_BASE)完成替换。前置一段 bootstrap。其他所有安装路径都隐含 CLI 已存在treg skill bootstrap只有装了 treg 才会运行插件是唯一可能落在完全没有 treg的机器上的路径没有 bootstrap首次运行会以command not found收场。此外render()还做了三件静态化工作剔除服务端按部署开关剥离的!--routed--标记静态副本无法感知部署设置但标记本身绝不能随包发出用加载目录时的实时数字替换{ENDPOINTS}/{PROVIDERS}占位符Claude 变体额外向 frontmatter 打上version:ClawHub 强制要求、Claude Code 忽略一份生成文件得以同时满足两个注册表。永远不要手改plugin/skills/treg/SKILL.md改src/treg/web/skill.md后重新生成tests/test_plugin.py 的test_the_plugin_skill_is_not_stale会直接运行build_plugin.py --check两份不一致即测试失败。Codex 专属 bootstrap先看工具再决定动作Codex 插件的 bootstrap 与其余变体不同因为它自带 MCP 连接器。渲染产物 plugin/skills/treg/SKILL.md 开头即要求 Agent先检查工具再行动能看到catalog_search、catalog_get、call、balance、my_tools—— treg 已连通直接用工具无需安装。整页 CLI 命令按映射理解treg catalog search→catalog_searchtreg call→call以此类推。看不到这些工具—— 说明这份副本以纯技能方式安装目录上传路径剥离了连接器配置改走 CLI 一次性配置curl -fsSL https://treg.to/install.sh | sh安装 CLItreg login登录首次登录即注册。新团队自带$1.00 免费余额首次调用前无需付费。连接器在但工具报错—— 说明还没有 token由用户在TREG_TOKEN环境变量中放入 token。bootstrap 反复强调一条纪律需要登录时直接说明并停下绝不向用户索要数据商的 API Key——那正是 treg 存在要避免的东西。对应的测试test_the_skill_maps_itself_onto_the_MCP_TOOLS断言五个工具名与TREG_TOKEN均出现在技能文本中且 manifest 的mcpServers指向./.mcp.json。本地验证无需桌面应用Codex CLI 自己会装README 特别注明不需要桌面应用Codex CLI 自己就能安装并加载插件已用 codex-cli 0.145.0 验证。关键认知市场清单marketplace manifest是用户侧文件刻意不属于插件本身。它位于~/.agents/plugins/marketplace.json且path是相对$HOME解析的——既不是相对 manifest也不是绝对路径{ name: superdesign-local, interface: { displayName: superdesign (local dev) }, plugins: [ { name: treg, source: { source: local, path: ./devs/superdesign/tools-registry-oss/plugin }, policy: { installation: AVAILABLE, authentication: ON_INSTALL }, category: Developer Tools } ] }然后按顺序执行codex plugin list # tregsuperdesign-local —— 未安装 codex plugin add tregsuperdesign-local # 末尾的 marketplace 后缀是必须的 codex plugin list # 已安装、已启用、0.7.1安装副本落在~/.codex/plugins/cache/$MARKETPLACE/$PLUGIN/$VERSION/。最后确认技能真的加载了——应显示为treg:tools-registrycodex exec --skip-git-repo-check List the names of every skill you have available.一个常见误区codex plugin marketplace add ./plugin不工作——该命令期望的是 marketplace 根目录而这个目录是单个插件。清单文案就是产品分类、能力与措辞纪律plugin/.codex-plugin/plugin.json中的category和capabilities不是凭空猜测而是对照 OpenAI 自家已上架插件的实际取值github是Developer Tools[Interactive, Write]gmail是Communicationopenai-templates是Productivity。官方文档不公布这两个列表所以 README 的建议是在发明取值前先读~/.codex/plugins/cache/下真实已安装 manifest。本仓库当前 manifest 取值plugin/.codex-plugin/plugin.json 声明category: Developer Tools、capabilities: [Interactive, Write]配套shortDescription: OpenRouter for agent tools正是项目定位句的前半段另有 3 条defaultPrompt示例提示。测试层面对这些约束做了硬性钉住test_category_and_capabilities_match_what_real_plugins_usecategory 只能是Developer Tools/Productivity/Communication之一capabilities 只能是Interactive/Write/Read子集test_at_most_three_default_promptsOpenAI 上传表单规定defaultPrompt至多 3 条该限制是付出一次上传往返才发现的test_every_declared_path_existsmanifest 引用的每个相对路径必须真实存在作者机器上能解析、别处不存在的路径是经典打包 bugtest_plugin_version_tracks_the_packagemanifestversion必须与 pyproject.toml 一致当前为0.21.2一个产品只允许一个版本号test_manifest_declares_what_the_directory_readsname/version/description/skills/interface及其子字段缺一不可。产品定位的措辞红线比较而非路由上架前必须核对version与 pyproject 一致且文案仍然准确描述 treg 的行为treg比较各数据商由 Agent 自己选择。treg不会自动路由也不会自动故障转移——README 直言 landing page 曾因这条表述被纠正过一次而目录列表比网页更难更正所以有测试专门守护test_the_listing_does_not_promise_routing对全部 manifest 断言文案中不得出现routes for you、automatic failover、fails over、picks the best provider等字样。这个边界来自项目章程见 docs/context/foundation/charter.md 及 docs/context/interface/skill.md 的技能规则treg 只是中继从不在数据商之间替你选择——只有你知道自己手里有哪些输入且 treg 只中继而从不改写你的请求。技能正文中关于选商的完整流程先匹配你实际持有的输入、再看WORKS成功率与样本量、再比价、最后用LAST OK破平正是这一立场的落地。配套技能内容速览装完插件能做什么插件交付的 SKILL.md 即产品最核心的能力说明完整内容见 plugin/skills/treg/SKILL.md几个关键机制值得了解目录与自有工具共用同一 tokenX-Treg-Token头鉴权代理在服务端注入凭据调用方永不持有密钥工具 上游 base URL 凭据绑定技能/包 配方SKILL.md 密钥 工具代理只中继、不建模上游。先看价格再花钱每个端点的价格都在treg catalog get里真实计费以响应头X-Treg-Cost-Micro微美元为准失败调用上游 4xx/5xx 中继免费。HTTP 状态码速查402 余额不足响应体带balance_micro、estimated_cost_micro、topup_url可机读字段503 provider_capacity_unavailable treg 自有账号额度耗尽不是你的余额未扣费响应体带resets_at与alternatives可换其他商。幂等重试调用超时或未见应答时携带相同Idempotency-Key重发treg 返回已存应答、不再调用上游、不再扣费结果标记replayed: true。生成类任务视频/图像生成是异步任务提交即返回任务 id--await轮询至完成退出码 0完成、2上游失败、3超时可续跑语音生成是同步的参考媒体必须是可以被厂商直接抓取的公网 URLtreg host可生成 30MB、7 天有效的临时公网地址。与其余橱窗的协同及下一步阅读理解本插件的最佳方式是把它放进五橱窗整体中看差异。与 Claude Code 插件skills/treg/的对比尤其能说明设计取舍Claude 版 manifest不声明连接器tests/test_plugin.py 的test_the_claude_plugin_declares_no_connector_in_its_manifest专门守护——因为安装时任何人尚未登录声明 MCP 服务器意味着五个永远在、每次调用都 401 的工具留空才让/plugin install成为零配置动作技能随后在首次运行时按install.sh → treg login → treg mcp install的承载顺序完成配置cmd_mcp_install在无 token 时会先sys.exit不写任何东西乱序执行等于静默空操作。而 Cursor 版plugins/treg/与 Codex 类似地自带 MCP却使用 Cursor 的环境变量语法${env:TREG_TOKEN}。想深入可继续阅读 docs/CLAUDE-PLUGIN.md含 ClawHub 双阶段发布等完整上架 runbook、docs/DSH-PLUGIN.md、docs/MINIMAX-PLUGIN.md以及渲染脚本 scripts/build_plugin.py 中五种 bootstrap 的完整源码。赞分享后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载相关推荐PentestGPT 仓库 teach 技能全解析面向多会话的 AI 教学代理工作区设计PentestGPT 仓库 teach 技能全解析面向多会话的 AI 教学代理工作区设计 导读 .agents/skills/teach/SKILL.md 定后端API网关MCP 服务dsh-pluginoh-my-codex 0.18.4 发布就绪评估全解补丁列车范围、PR 清单与本地验证门禁oh my codex 0.18.4 发布就绪评估全解补丁列车范围、PR 清单与本地验证门禁 docs/qa/release readiness 0.18.4人工智能AI AgentAgent 编排Agent 工作流CLI开发工具AI 技能Codex 插件清单规范详解plugin.json 与 marketplace.json 的字段、默认值与校验规则Codex 插件清单规范详解plugin.json 与 marketplace.json 的字段、默认值与校验规则 本篇技术指南围绕 Codex 内置 plu人工智能大模型AI Agent代码智能体AI 应用CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考