
عاملهای برنامهنویس (coding agents) امروز بخش زیادی از کد فروشگاههای اینترنتی را مینویسند یا تغییر میدهند: افزونهی ووکامرس، اتصال درگاه پرداخت، پردازش وبهوک سفارش. این عاملها دانش عمومی خوبی دارند، اما دانش «تجربی» یک مهندس ارشد تجارت الکترونیک را ندارند؛ چیزهایی مثل اینکه چرا نباید روی شناسهی تلاش تحویل dedupe کرد یا چرا امضای وبهوک باید روی بایتهای خام بررسی شود.
یکی از راههای انتقال این دانش، «مهارت» (skill) است: پوشهای با یک فایل SKILL.md که نام، توضیح و دستورالعمل دارد و عامل وقتی کار با توضیح آن مطابقت داشت، آن را بارگذاری میکند. من مجموعهای متنباز از این مهارتها به نام commerce-agent-skills ساختهام. در این یادداشت دو موضوع را توضیح میدهم: اینکه چطور میشود مهارت را مثل کد قابل آزمون کرد، و یک مطالعهی موردی فنی دربارهی رایجترین خطای پنهان در پردازش وبهوک، یعنی تحویل دوباره پس از timeout.
این مجموعه از قالب Agent Skills پیروی میکند: یک پوشه، یک فایل SKILL.md با فیلدهای name و description، و در صورت نیاز فایلهای مرجع و اسکریپتهای کوچک. عامل ابتدا فقط نام و توضیح را میخواند و تصمیم میگیرد مهارت به کار مربوط است یا نه؛ بدنهی مهارت و فایلهای مرجع فقط وقتی لازم شد بارگذاری میشوند. این طراحی باعث میشود پنجرهی متنی عامل با دانش نامربوط پر نشود.
کنار هر مهارت یک «قاعده» (rule) هم هست: یک فایل Markdown کوتاه که میتوان آن را همیشه در متن عامل نگه داشت. تفاوت را اینطور خلاصه میکنم: مهارت برای یک کار است، قاعده برای همهی کارهای یک حوزه.
نسخهی 0.3.3 مجموعه ۲۹ مهارت دارد؛ از توسعهی افزونهی ووکامرس و امنیت افزونهی وردپرس تا پرداخت Stripe، درگاههای ایرانی مانند زرینپال، موجودی چندانباره، مرجوعی و بازپرداخت، قیمتگذاری B2B، بومیسازی فارسی و راستبهچپ، دسترسپذیری و کارایی ویترین، و طراحی ابزارهای MCP برای فروشگاه. (طراحی ابزارهای نوشتن امن در یک سرور MCP را در یادداشت «الگوی پیشنمایش، تأیید و ثبت در یک سرور MCP برای ووکامرس» شرح دادهام.)
متنی که قرار است رفتار یک عامل را شکل دهد، اگر آزمون نداشته باشد، بهمرور خراب میشود: توضیحش با محتوایش ناهماهنگ میشود، اصطلاحی از قلم میافتد یا یک تغییر ظاهراً بیخطر نکتهای کلیدی را حذف میکند. برای جلوگیری از این، سه لایهی کنترل در نظر گرفتهام.
هر مهارت یک فایل evals/tasks.json دارد. هر وظیفه یک صورت مسئله و دو فهرست بررسی است:
must_include: رشتههایی که پاسخ باید داشته باشد، معمولاً نام API یا فیلد.
must_not_include: رشتههایی که پاسخ نباید داشته باشد، معمولاً نشانهی یک اشتباه رایج.
برای هر وظیفه یک نمونهی حلشده هم هست که همهی بررسیها را پاس میکند. در آخرین نسخهی شاخهی اصلی مخزن، مجموع وظیفههای ارزیابی ۶۲ مورد است.
اعتبارسنج نسخهها، بخشهای لازم، سرفصلهای قاعده، پوشش دستهها و سبک نگارش را بررسی میکند. مهمترین بررسی این است: اگر رشتهای در must_include باشد که در خود مهارت، قاعده یا مرجعهایش آموزش داده نشده، اعتبارسنج خطا میدهد. یعنی نمیشود از عامل انتظار چیزی را داشت که مهارت به او یاد نداده است.
اسکریپت run-evals پاسخهایی را که از یک عامل جمع کردهاید امتیاز میدهد. امتیاز هر وظیفه نسبت بررسیهای پاسشده به کل بررسیهاست و وظیفه فقط وقتی پاس است که همهی بررسیها پاس شوند. فایل پاسخ گمشده صفر میگیرد.
node scripts/run-evals.mjs node scripts/run-evals.mjs --answers ./answers --min-score 0.8
فرمان اول نمونههای حلشده را بررسی میکند. فرمان دوم پاسخها را از مسیر answers/<skill>/<task-id>.md میخواند و اگر امتیاز زیر آستانه باشد با کد خروج ۱ پایان مییابد، پس میتوان آن را در CI گذاشت.
یک نکتهی صادقانه: این بررسیها از نوع تطبیق زیررشتهاند. پاس شدن آنها درستی پاسخ را فراتر از رشتههایی که نامبرده شده ثابت نمیکند. اجراکننده هم خودش وظیفهها را به عامل زنده نمیفرستد؛ پاسخهایی را که شما جمع کردهاید امتیاز میدهد.
دو حالت همزمان و شکست نیمهکاره که در ادامه آمدهاند، از بازخورد خوانندگان به مجموعه اضافه شدند؛ این تجربه را در نوشتهای دربارهی بازخورد خوانندگان توضیح دادهام.
فرض کنید فروشگاه شما وبهوک «سفارش پرداخت شد» را دریافت میکند. گیرنده رویداد را ذخیره میکند، سفارش را بهروز میکند، دستور ارسال (fulfillment) را میسازد و ایمیل تأیید میفرستد. اما فرستنده پیش از رسیدن پاسخ 2xx دچار timeout میشود و همان رویداد را دوباره میفرستد؛ اغلب با یک شناسهی تحویل جدید.
اگر گیرنده خودتوان (idempotent) نباشد، نتیجه دو بار ارسال، دو ایمیل یا دو بار کم شدن موجودی است. این رایجترین نوع تکرار در عمل است و بیصدا رخ میدهد.
dedupe روی شناسهی تحویل. در ووکامرس، هدر X-WC-Webhook-Delivery-ID برای هر تلاش یک شناسهی لاگ تازه است. پس تحویل دوباره با این کلید «جدید» دیده میشود. به همین دلیل در وظیفهی ارزیابی این رشته در فهرست must_not_include آمده است.
پاسخ 200 پیش از ذخیره. اگر فرایند بعد از پاسخ و پیش از نوشتن در پایگاه داده از کار بیفتد، رویداد برای همیشه گم میشود.
انجام همهی کارها پیش از پاسخ. گیرندهی کندی که رویداد را اعمال میکند و ایمیل را میفرستد و بعد پاسخ میدهد، خودش timeout را دعوت میکند.
رویهای که مهارت order-and-webhook-reliability آموزش میدهد چنین است:
بدنهی خام را پیش از هر تجزیهی JSON بخوانید.
امضا را با مقایسهی زمانثابت بررسی کنید و درخواست بدون امضا یا با امضای نامعتبر را پیش از نگاه کردن به نوع رویداد رد کنید.
رویداد را در یک صندوق ورودی پایدار (durable inbox) ذخیره کنید که روی یک کلید پایدار یکتا باشد.
فقط پس از موفقیت ذخیره پاسخ 2xx بدهید.
تغییر را فقط اگر این رویداد از نسخهی ذخیرهشده جدیدتر است اعمال کنید.
اگر رویداد ناقص یا خارج از ترتیب بود، سفارش را از منبع حقیقت بخوانید و همان را بنویسید.
کلید یکتای عملی: شناسهی رویداد ارائهدهنده، اگر در تلاشهای دوباره ثابت میماند؛ در غیر این صورت هش موضوع، شناسهی منبع و نسخهی منبع (در ووکامرس date_modified_gmt). هر ردیف صندوق وضعیتی دارد: stored، applied یا ignored.
کلید یکتا بهتنهایی کافی نیست. تحویل دوباره باید ردیف را در وضعیت applied پیدا کند، 2xx برگرداند و هیچ اثر جانبی اجرا نکند. این فقط وقتی برقرار است که هر اثر جانبی (ایمیل، موجودی، ارسال) در همان تراکنشی ثبت شود که ردیف را applied میکند، یا خودش روی شناسهی رویداد کلید خورده باشد. شبهکد زیر فقط یک نمونهی مفهومی برای توضیح ایده است و کد خود مخزن نیست:
BEGIN row = inbox.insert_or_get(event_key) if row.status == "applied": COMMIT; return 2xx apply_order_change(event) outbox.add("send_email", key=event_key) outbox.add("create_fulfillment", key=event_key) row.status = "applied" COMMIT return 2xx
یک کارگر جداگانه صف خروجی (outbox) را پردازش میکند و چون هر ورودی روی شناسهی رویداد کلید خورده، تکرار آن هم بیاثر است.
تحویل همزمان. گاهی همان رویداد در یک لحظه به دو سرور یا دو کارگر میرسد. اگر گیرنده اول صندوق را بخواند، چیزی پیدا نکند و بعد درج و اعمال کند (الگوی «بررسی، سپس درج»)، هر دو درخواست از بررسی رد میشوند و سفارش دو بار اعمال میشود. راه درست این است که رویداد با یک درج اتمی روی کلید یکتا «تصاحب» شود، مثلاً INSERT ... ON CONFLICT DO NOTHING، و فقط درخواستی که ردیف را واقعاً ساخته تغییر را اعمال کند. درخواست دیگر 2xx میدهد و هیچ کاری انجام نمیدهد. قفل کردن کل جدول لازم نیست؛ کلید یکتا تصمیم میگیرد.
شکست نیمهکاره. تصاحب نباید یک شکست را پنهان کند. اگر تحویل اول ردیف صندوق را درج کند و پیش از commit شدن تغییر سفارش از کار بیفتد، تحویل دوبارهای که فقط وجود ردیف را ببیند و 2xx بدهد، رویداد را برای همیشه گم میکند و سفارش هرگز «پرداختشده» نمیشود. راهحل این است که تغییر در همان تراکنشی اعمال شود که ردیف را applied میکند، تا خرابی هر دو را rollback کند؛ ردیفی که پس از timeout هنوز در وضعیت pending مانده، قابل تلاش دوباره است و تحویل بعدی آن را دوباره تصاحب و کار را کامل میکند. پاک کردن ردیف صندوق راهحل نیست. افزون بر این، برای هر تحویل یک ورودی ممیزی با کلید شناسهی رویداد ثبت میشود که میگوید آن تحویل چه کرد؛ مثلاً اول «failed: rolled back before apply» و بعد «applied». نتیجه: تاریخچهی سفارش دقیقاً یک تغییر وضعیت و هر دو تلاش را نشان میدهد.
این سناریو در نسخهی 0.3.2 به شکل وظیفهی redelivery-after-timeout اضافه شد. صورت مسئله همین داستان است و پاسخ باید چهار مفهوم applied، 2xx، side effect و timeout را داشته باشد و نباید به X-WC-Webhook-Delivery-ID تکیه کند. همان نسخه توضیح این حالت را به خود مهارت، فهرست بررسی و «دامها»یش و یک خط متناظر به قاعده اضافه کرد؛ چون اعتبارسنج اجازه نمیدهد وظیفه چیزی بخواهد که مهارت یاد نداده.
پس از آن دو وظیفهی دیگر هم به همین مهارت اضافه شد. وظیفهی concurrent-duplicate-delivery از پاسخ میخواهد مفاهیم unique key، ON CONFLICT، concurrent و 2xx را داشته باشد و نه به X-WC-Webhook-Delivery-ID تکیه کند و نه «قفل کل جدول» را پیشنهاد دهد. وظیفهی redelivery-after-partial-failure مفاهیم pending، same transaction، audit، exactly one و rolled back را میخواهد و پاک کردن ردیف صندوق را رد میکند. به این ترتیب این مهارت اکنون پنج وظیفهی ارزیابی دارد.
امضای ووکامرس به شکل base64(hmac_sha256(secret, raw_body)) است. تجزیهی JSON و امضای دوبارهی JSON.stringify هرگز مطابقت نمیکند، چون فرستنده بایتهای اصلی را امضا کرده است.
ووکامرس پس از بیش از پنج شکست پیاپی وبهوک را غیرفعال میکند (فیلتر woocommerce_max_webhook_delivery_failures با مقدار پیشفرض ۵).
پینگ فعالسازی رویداد سفارش نیست؛ 2xx بدهید و سفارشی نسازید.
اگر پایگاه داده در دسترس نیست، 503 برگردانید تا فرستنده دوباره بفرستد؛ کلید یکتا تکرار را امن میکند.
npx @sadrmanesh/commerce-agent-skills init npx @sadrmanesh/commerce-agent-skills add order-and-webhook-reliability stripe-payments
فرمان اول همهی مهارتها را در .agents/skills/ و همهی قاعدهها را در .agents/rules/ کپی میکند. فرمان دوم فقط مهارتهای نامبرده را نصب میکند.
ارزیابیها مبتنی بر زیررشتهاند؛ پاسخی میتواند رشتهها را داشته باشد و همچنان اشتباه باشد. خواندن پاسخهای ناموفق و نمونهای از پاسخهای موفق لازم است.
نمونههای حلشده امتیاز یک عامل زنده نیستند.
رویهی صندوق ورودی فرض میکند پایگاه داده تراکنش یا قید یکتایی دارد.
دانش تجربی تجارت الکترونیک را میتوان به شکلی بستهبندی کرد که عاملهای برنامهنویس از آن استفاده کنند، اما این بستهبندی باید مثل کد آزمون داشته باشد. مطالعهی موردی وبهوک تکراری نشان میدهد چرا: درس اصلی، یعنی «dedupe روی نسخهی منبع، نه شناسهی تحویل، و اثرهای جانبی داخل همان تراکنش»، در یک جمله جا میشود، اما اگر از متن مهارت حذف شود، عامل با اطمینان کامل کدی مینویسد که مشتری را دو بار ایمیل میکند.
کد منبع: github.com/sadrmanesh/commerce-agent-skills
گزارش فنی در Zenodo، DOI: 10.5281/zenodo.23883598
نسخهی نرمافزار در Zenodo، DOI: 10.5281/zenodo.23944676
مستندات: sadrmanesh.github.io/commerce-agent-skills
دیتاست مهارتها و ارزیابیها: huggingface.co/datasets/sadrmanesh/commerce-agent-skills
قالب Agent Skills: agentskills.io/specification
کد و مستندات پروژه: github.com/sadrmanesh/commerce-agent-skills