چطور با plugin-eval کدکس هزینه‌ی توکن اسکیل را بسنجیم

اگر اسکیل یا پلاگین خودتان را برای کدکس می‌نویسید، فرمان codex plugin یک ارزیاب کامل روی همان کد محلی شما اجرا می‌کند و عدد می‌دهد. در اندازه‌گیری من روی کدکس 0.158.0 در ۱۰ مهر ۱۴۰۵، نصب پلاگین plugin-eval و بررسی یک اسکیل واقعی، نمره از 81 به 95 رفت و مصرف توکن هنگام فراخوانی از 1071 به 119 رسید؛ کل کار بدون هیچ کلید API و بدون تماس با شبکه انجام شد.

این ابزار دقیقا چه چیزی را می‌سنجد

یک اسکیل سه سطل هزینه دارد و هر سه جدا حساب می‌شوند. سطل اول trigger_cost_tokens است یعنی متنی که پیش از فراخوانی صریح در دسترس ایجنت است، مثل نام و توضیح اسکیل. سطل دوم invoke_cost_tokens است یعنی بدنه‌ی دستور که موقع صدا زدن اسکیل بارگذاری می‌شود. سطل سوم deferred_cost_tokens است یعنی فایل‌های مرجع که فقط بعدا و در صورت نیاز خوانده می‌شوند [1][2].

روش شمارش ساده و قابل بازسازی است: تعداد نویسه‌ی متن تقسیم بر چهار، گرد به بالا. اسکیلی که سنجیدم پیش از دست‌کاری 4283 بایت بود که می‌شود 1071 توکن، و توضیح description آن 424 نویسه بود که می‌شود 106 توکن [3].

این اعداد از فایل‌های JSON خود ابزار خوانده شده و نه از تخمین من. جمع سه سطل در هر دو حالت درست بسته می‌شود: 109 + 1071 + 27 = 1207 و 44 + 119 + 1098 = 1261. آن 54 توکن اضافه عیب نیست، چون ابزار جمع هزینه‌ی فعال را می‌سنجد نه هزینه‌ی کل بسته.

نصب: سه فرمان که واقعا کار می‌کند

پلاگین از یک مارکت‌پلیس می‌آید که کدکس از قبل در این ماشین داشت. نامش openai-api-curated است و ریشه‌اش را codex plugin marketplace list نشان می‌دهد. فهرست کامل آن مارکت‌پلیس ۵۰ پلاگین دارد [4].

# اول ببین کدکس چه مارکت‌پلیس‌هایی را می‌بیند
$ codex plugin marketplace list
MARKETPLACE         ROOT
openai-api-curated  /root/.codex/.tmp/plugins

$ codex plugin list | head -3
Marketplace `openai-api-curated`
/root/.codex/.tmp/plugins/.agents/plugins/api_marketplace.json

PLUGIN                                           STATUS         VERSION  SOURCE
game-studio@openai-api-curated                   not installed           /root/.codex/.tmp/plugins/plugins/game-studio

نصب با فرم name@marketplace انجام می‌شود. بدون بخش دوم، فرمان خطا می‌دهد و هیچ چیز نصب نمی‌کند.

$ codex plugin add plugin-eval
Error: plugin requires --marketplace unless passed as <plugin>@<marketplace>

$ codex plugin add plugin-eval@openai-api-curated
Added plugin `plugin-eval` from marketplace `openai-api-curated`.
Installed plugin root: /root/.codex/plugins/cache/openai-api-curated/plugin-eval/5fd93af4

$ codex plugin list | grep plugin-eval
plugin-eval@openai-api-curated                   installed, enabled  5fd93af4  /root/.codex/.tmp/plugins/plugins/plugin-eval

نکته‌ای که در خروجی تازه شمرده می‌شود آن است که نصب یک ورودی در config.toml می‌نویسد و همان ورودی وضعیت فعال را نگه می‌دارد.

[plugins."plugin-eval@openai-api-curated"]
enabled = true

پلاگین نصب‌شده یک CLI محلی هم هست و به node بیست یا بالاتر نیاز دارد؛ روی این ماشین node v26.7.0 بود. از پوشه‌ی کش بیرون بیاورید تا فرمان‌ها را از همان‌جا اجرا کنید.

$ cd /root/.codex/plugins/cache/openai-api-curated/plugin-eval/5fd93af4
$ node ./scripts/plugin-eval.js --help
Plugin Eval helps first-time skill authors start from chat and keep the workflow local-first.

Start here:
  plugin-eval start <path> [--request "<chat request>"] [--goal evaluate|budget|measure|benchmark|next] ...

Core workflows:
  plugin-eval analyze <path> [--format json|markdown|html] [--output <file>] ...
  plugin-eval explain-budget <path> [--format json|markdown] [--output <file>]
  plugin-eval measurement-plan <path> [--format json|markdown] [--observed-usage <file>] ...
  plugin-eval init-benchmark <path> [--output <benchmark.json>] [--model <model>] ...
  plugin-eval benchmark <path> [--config <benchmark.json>] ...

اگر مسیر کش عوض شد، همان مسیر مطلق کار نمی‌کند. راه پایدارتر npm link از داخل ریشه‌ی پلاگین است که فرمان plugin-eval را دائمی روی مسیر می‌سازد [3].

اولین اجرا: نمره‌ی ۸۱ و سه جراحی که خودش پیشنهاد می‌دهد

یک کپی از اسکیل داخلی خود پلاگین را به پوشه‌ی کاری بردم و همان را سنجیدم، تا ارزیاب روی هدف واقعی بیفتد نه روی نمونه‌ی ساختگی.

$ mkdir -p ~/work && cp -r skills/plugin-eval ~/work/my-skill
$ node ./scripts/plugin-eval.js analyze ~/work/my-skill --format markdown
# Plugin Eval Report: my-skill

## At a Glance
- Score: 81/100
- Grade: C
- Risk: high
- Checks: 1 fail, 1 warn, 2 info
- Active budget: 1180 tokens (excessive)
- Observed usage: not supplied

## Fix First
- [fail/error] invoke_cost_tokens is excessive relative to the current Codex baseline. Why: Budget pressure matters because always-loaded or frequently-loaded text can make the workflow feel expensive fast. Fix: Reduce repeated instruction text and move detail into deferred supporting files.
- [warn/warning] trigger_cost_tokens is heavy relative to the current Codex baseline. ...

عدد 1180 در خط Active budget با 1207 جدول فرق دارد، چون آن خط فقط سطل‌های فعال را جمع می‌زند. پس عدد داخل پرانتز را خودتان جمع کنید و به متن تکیه نکنید.

راه‌حل پیشنهادی خود ابزار هم مشخص است: تکرار متن دستور را کم کنید و جزئیات را به فایل‌های مرجع منتقل کنید، چون فشار روی سطل فعال تجربه‌ی کاربر را زود گران می‌کند [1].

اصلاح واقعی: از ۸۱ به ۹۵ با یک ویرایش

همان پیشنهاد را اجرا کردم. بدنه‌ی کامل SKILL.md را به references/full-guide.md منتقل کردم و در خود SKILL.md فقط یک راهنمای کوتاه با سه مرحله گذاشتم. توضیح description را هم از 424 نویسه به 163 نویسه کوتاه کردم و چهار عبارت محرک نگه داشتم.

$ wc -c ~/work/my-skill/SKILL.md
  4283 ~/work/my-skill/SKILL.md

$ mkdir -p ~/work/my-skill/references
$ cp ~/work/my-skill/SKILL.md ~/work/my-skill/references/full-guide.md
$ cat > ~/work/my-skill/SKILL.md <<'MD'
---
name: plugin-eval
description: Evaluate a local Codex skill or plugin. Use when the user says "evaluate this skill", "audit this skill", "why did this score that way", "what should I fix first".
---

# Evaluate Skill

Run the local CLI. Details live in `references/full-guide.md`.

1. `plugin-eval analyze <path> --format markdown`
2. Read At a Glance, Fix First, Recommended Next Step.
3. If the user asks for an analysis, also run `plugin-eval init-benchmark <path>`.
MD

$ wc -c ~/work/my-skill/SKILL.md
   474 ~/work/my-skill/SKILL.md

حالا همان اسکیل را دوباره سنجیدم. تفاوت را خود ابزار با مقایسه‌ی دو فایل JSON نشان داد.

$ node ./scripts/plugin-eval.js analyze ~/work/my-skill --format json --output ~/work/after.json
$ node ./scripts/plugin-eval.js compare ~/work/before.json ~/work/after.json --format markdown
# Plugin Eval Comparison: my-skill

## At a Glance
- Score delta: +14
- Grade: C -> A
- Risk: high -> medium
- Budget delta (trigger/invoke/deferred): -65 / -952 / +1071

اختلاف نمره از حساب ریاضی خود ابزار می‌آید، نه از حدس. جریمه‌ها پیش از اصلاح 18.75 و پس از آن 4.75 بود. با گرد کردن به نزدیک‌ترین عدد صحیح، 100 - 18.75 می‌شود 81 و 100 - 4.75 می‌شود 95 [1][3].

سه چیزی که این ابزار نمی‌گوید

اول اینکه روش کار همه‌ی اعداد این پست estimated-static است، نه اندازه‌گیری زنده. سند فنی خود پلاگین می‌گوید این نسخه توکن‌سنجی میزبان را در اختیار پلاگین نمی‌گذارد و تخمین محلی قطعی را جایگزین کرده است [1].

دوم اینکه آستانه‌ها ثابت مطلق نیستند. ابزار می‌گوید باندها در برابر یک مجموعه‌ی مرجع از اسکیل‌ها و پلاگین‌های منتشرشده‌ی کدکس کالیبره می‌شوند، آن هم وقتی که آن مجموعه محلی در دسترس باشد. عدد 48 برای سطل محرک و 220 برای سطل فراخوانی را همین کالیبراسیون تعیین کرده، پس با نسخه‌ی ابزار جابه‌جا می‌شوند [1].

سوم اینکه خود ابزار روی هدف خودش نمره‌ی 96 گرفت، اما با یک اخطار. کدکس پلاگین نصب‌شده را در پوشه‌ای به نام 5fd93af4 باز می‌کند و نام آن با نام plugin.json یکی نیست؛ همان تست manifest-name-directory-mismatch که 4.5 امتیاز کم می‌کند [1].

این هشدار اثر جانبی نصب است، نه ایراد در نوشتن پلاگین. برای دیدن هزینه‌ی یک بسته‌ی کامل، همان فرمان را روی ریشه‌ی پلاگین بزنید نه روی یک اسکیل.

$ node ./scripts/plugin-eval.js analyze . --format markdown
# Plugin Eval Report: 5fd93af4
- Score: 96/100
- Grade: A
- Risk: medium

مرز کاری که در این پست انجام شد

کدکس نسخه‌ی 0.158.0 روی این ماشین بود و codex doctor نسخه‌ی 0.160.0 را در دسترس گزارش کرد. هیچ ورود به حسابی انجام نشد، چون همان فرمان صراحتا خطای نبود اعتبارنامه را داد.

$ codex doctor | head -6
Codex Doctor v0.158.0 · linux-x86_64

Notes
   ↑ updates      0.160.0 available (current 0.158.0)
   ✗ auth         no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.

اثر عملی نبود اعتبارنامه این است که plugin-eval benchmark که نشست واقعی codex exec اجرا می‌کند اجرا نشد. پس هر عدد این پست تخمین ایستا است. راه رسیدن به عدد زنده همان مسیری است که ابزار پیشنهاد می‌کند: init-benchmark بعد benchmark، و بعد دادن فایل مصرف به measurement-plan [1][3].

اسکیلی که سنجیدم داخلی خود همین پلاگین بود، نه اسکیل شما؛ همان فرمان را روی مسیر اسکیل خودتان بزنید. برای دیدن اینکه چه چیزی در هر نشست کدکس بی‌دلیل توکن می‌گیرد، پست خواندن وضعیت واقعی پرچم‌های کدکس نقطه‌ی شروع است، و برای پلاگین‌های کلاد کد، هزینه‌ی پنهان هر اسکیل همان اندازه‌گیری را با فرمان‌های دیگری نشان می‌دهد.

قاعده‌ی کاربردی این اندازه‌گیری در یک جمله جمع می‌شود: نمره‌ی پایین تقریبا همیشه چند سطر تکراری در توضیح یا بدنه‌ی اسکیل است، و جابه‌جایی آن به فایل مرجع نمره را بالا می‌برد و زمان بارگذاری را کم می‌کند، در حالی که متن از بین نرفته است.

منابع

1. مخزن openai/plugins روی گیت‌هاب: پلاگین plugin-eval و سند فنی مدل بودجه — خوانده در ۱۰ مهر ۱۴۰۵
2. مستندات پلاگین‌ها: اجزای پلاگین و آنچه در هر نشست بارگذاری می‌شود — خوانده در ۱۰ مهر ۱۴۰۵
3. راهنمای ساخت پلاگین: نیازمندی node، فرم نصب با مارکت‌پلیس و قواعد مسیر — خوانده در ۱۰ مهر ۱۴۰۵
4. مستندات Skills & Plugins: تفاوت اسکیل و پلاگین و قواعد نام‌گذاری — خوانده در ۱۰ مهر ۱۴۰۵
5. Build plugins در کدکس: فرم‌های codex plugin marketplace add و ساخت دستی مارکت‌پلیس — خوانده در ۱۰ مهر ۱۴۰۵
6. مخزن openai/codex و فهرست انتشارهای کلاینت خط فرمان — خوانده در ۱۰ مهر ۱۴۰۵
7. مستندات Hooks: چرخه‌ی رویداد و اینکه کدکس اسکریپت قلاب پلاگین را خودکار اجرا نمی‌کند — خوانده در ۱۰ مهر ۱۴۰۵