دادن مستندات به کلود یا کدکس

نسخهٔ یک‌فایلی مستندات، و پرامپت آماده‌ای که با آن می‌گویید «این سرویس را برایم وصل کن».

بیشتر کسانی که این روزها سگمنتیک را وصل می‌کنند، یک عامل هوش مصنوعی کنارشان نشسته است. این صفحه می‌گوید چه چیزی به آن عامل بدهید، و اگر ندهید چه چیزهایی را غلط انجام می‌دهد.

اگر می‌خواهید عامل به جای نوشتن کد، خود حساب شما را کوئری بزند، آن کار دیگری است و در صفحهٔ سرور MCP توضیح داده شده.

#سه فایل، و اینکه کدام را بدهید

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

curl -s https://segmentic.net/llms.txt
curl -s -o segmentic-docs.md https://segmentic.net/docs-en.md
curl -s -o segmentic-docs-fa.md https://segmentic.net/docs-fa.md
curl -s -o segmentic-openapi.json https://segmentic.net/openapi.json

فایل llms.txt انگلیسی است، هرچند نسخهٔ اصلی صفحه‌ها فارسی است. خوانندهٔ آن فایل یک مدل است که دارد انتخاب می‌کند کدام صفحه را بگیرد، نمونه‌های خود آن قرارداد انگلیسی‌اند، و هر مدلی که امروز استفاده می‌شود فهرست انگلیسی را مطمئن‌تر از فارسی می‌خواند. صفحه‌هایی که به آن‌ها اشاره می‌کند به هر دو زبان هستند و مجموعهٔ فارسی در پای همان فایل لینک شده.

فایلی به نام llms-full-fa.txt وجود ندارد. آن قرارداد یک نام دارد، و نام دومی که ما از خودمان بسازیم را هیچ‌چیز پیدا نمی‌کند. بستهٔ فارسی همان /docs-fa.md است.

فایل llms-full.txt پیش از اولین صفحه یک سرصفحه دارد که دو میزبان و دو نوع کلید را با لحن امری می‌گوید. آن سرصفحه تزیین نیست. عاملی که صفحه‌ها را بدون آن بگیرد، به سؤال‌های مربوط به میزبان و کلید از روی چیزی جواب می‌دهد که از محصول‌های تحلیلی دیگر به یاد دارد، و دو تا از گران‌ترین اشتباه‌هایش همین است: میزبان غلط و نوع کلید غلط.

#پرامپتی که می‌شود کپی کرد

همین‌طور که هست کپی کنید. برای اینکه اولین پیام یک نشست باشد نوشته شده، و هر بندش به این دلیل آنجاست که بدون آن، یک عامل آن را غلط انجام داده بود.

محصول من را به سگمنتیک وصل کن، که یک پلتفرم جمع‌آوری رویداد و ارسال پیام است.

اول https://segmentic.net/llms-full.txt را کامل بخوان. کل مستندات همان است.
از روی حافظه‌ات دربارهٔ محصول‌های تحلیلی دیگر جواب نده: میزبان‌ها، نام کلیدها،
کدهای خطا و مدل رویداد اینجا فرق دارند، و یک حدس باورپذیر یک بعدازظهر از من
می‌گیرد.

دو میزبان هست و دو نوع کلید. جای همدیگر را نمی‌گیرند.

  فرستادن رویداد، از سایت یا اپ موبایل من:
    میزبان   https://in.segmentic.net
    کلید     wk_seg_...   ذاتا عمومی است، داخل باندل سمت کاربر می‌رود،
                          و فقط می‌تواند رویداد بنویسد

  خواندن و مدیریت مخاطب و کمپین و گزارش، از بک‌اند من:
    میزبان   https://api.segmentic.net
    کلید     sk_seg_...   محرمانه، فقط سمت سرور، و مجوز حمل می‌کند

  پنلی که آدم با آن کار می‌کند:  https://app.segmentic.net

قاعده‌هایی که می‌خواهم بدون یادآوری دوباره رعایتشان کنی:

1. کلید sk_seg_ را هیچ‌جایی که به یک دستگاه می‌رسد نگذار. نه در کد مرورگر،
   نه در اپ موبایل، نه در متغیر محیطی با نام NEXT_PUBLIC_ یا VITE_، و نه در
   فایل پیکربندی سمت کاربر. اگر قابلیتی به آن نیاز دارد، آن فراخوانی روی
   سرور من انجام می‌شود.

2. پیش از انتخاب هر نام رویداد، صفحهٔ تعریف رویداد و فرهنگ‌نامهٔ رویدادها را
   بخوان. سرور هیچ قاعدهٔ نام‌گذاری‌ای را اجبار نمی‌کند و تقریبا هر رشته‌ای را
   می‌پذیرد. پس نام بد یک خطا نیست، تاریخچه است.

3. نام رویداد یا ویژگی موجود را هرگز حدس نزن. با کلید sk_seg_ از خود سرور
   بپرس:
     GET https://api.segmentic.net/v1/schema/events
     GET https://api.segmentic.net/v1/schema/traits
   نامی که وجود ندارد همه‌جا پذیرفته می‌شود و هیچ‌کس را نمی‌گیرد، که دقیقا
   شبیه یک مخاطب واقعی صفرنفره است. اگر به این مسیرها دسترسی نداشتی، به جای
   حدس‌زدن بایست و از من بپرس.

4. پیش از اینکه فرض کنی یک فراخوانی مدیریتی کار می‌کند،
   GET https://api.segmentic.net/v1/whoami را بزن. فهرست دقیق مجوزهای آن
   کلید را برمی‌گرداند. GET /v1/capabilities را هم بزن تا ببینی این نصب چه
   قابلیت‌هایی را سرو می‌کند و چه سقف‌هایی را اعلام می‌کند، و همان عددها را
   استفاده کن نه عددی که خودت در کد می‌نویسی.

5. پیش از نوشتن هر منطق تلاش دوباره، صفحهٔ کدهای خطا را بخوان. کد 401 یعنی
   اعتبارنامه غلط است و تلاش دوباره هیچ‌وقت درستش نمی‌کند. کد 429 با
   budget_exhausted یعنی صبر کن، و Retry-After می‌گوید چقدر. کد 503 گذراست و
   ارزش تلاش دوباره با فاصله دارد.

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

کارت را با پیشنهاد فهرست رویدادهایی شروع کن که محصول من باید بفرستد، و برای
هرکدام یک خط بنویس که به چه سؤالی جواب می‌دهد. تا وقتی سر آن فهرست به توافق
نرسیده‌ایم، هیچ کدی ننویس.

بسته به کار، دو چیز را شاید بخواهید اضافه کنید. اگر عامل دارد یکپارچه‌سازی سمت سرور می‌نویسد، زبان و فریم‌ورک را بگویید، چون مستندات با curl نوشته شده و در غیر این صورت خودش برایتان انتخاب می‌کند. اگر از قبل رویداد می‌فرستید و حالا پیام‌رسانی اضافه می‌کنید، بگویید از GET /v1/schema/events شروع کند و روی نام‌هایی کار کند که همین حالا هستند.

#عامل‌ها اینجا دقیقا چه چیزی را غلط می‌کنند

این‌ها هشدار کلی دربارهٔ مدل‌های زبانی نیستند. هرکدام یک شکست است که همین API تولید می‌کند، و بیشترشان در توضیح‌های سرور MCP نام برده شده‌اند، که بعد از تماشای کار عامل‌ها نوشته شده است.

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

خیلی بیشتر از نیازش می‌خواند، و بعد فکر می‌کند همه‌اش را دیده. مسیرهای GET /v1/segments و GET /v1/campaigns آرگومان‌های limit و cursor را می‌پذیرند و هر دو را نادیده می‌گیرند. هر کدام ۲۰۰ سطری را می‌دهند که تازه‌تر از همه به‌روز شده‌اند، از جمله کل درخت فیلتر هر سگمنت، پس عاملی که بپرسد «چه مخاطب‌هایی داریم» همان دویست‌تا را داخل کانتکست خودش می‌کشد. سقف بی‌صداست: نه next_cursor می‌آید، نه has_more، نه شماری. روی حسابی با ۲۵۰ سگمنت، عامل با اطمینان کامل فهرستی ناقص را کامل گزارش می‌کند و راهی هم نیست که به آن ۵۰ تای دیگر برسد.

روی فراخوانی گران در حلقه می‌افتد. شمردن یک مخاطب ۲۵ واحد از بودجهٔ ۶۰۰ واحدی هر دقیقه می‌برد، پس ۲۴ شمارش در دقیقه آن را ته می‌کشد. عاملی که واریاسیون‌های فیلتر را امتحان کند، در کمتر از یک دقیقه به budget_exhausted می‌خورد. به عامل کلید خودش را بدهید: بودجه برای هر کلید جدا شمرده می‌شود، پس یک عامل از کنترل خارج‌شده نمی‌تواند کلیدی را که خط سفارش‌های شما به آن وابسته است گرسنه بگذارد.

نرخ‌ها را در یک درصد جمع می‌کند. پیامک رسید خواندن ندارد، پس شمار بازشدن یک کمپین پیامکی صفر است و هیچ معنایی ندارد. هر نرخی در گزارش کمپین با صورت کسر و یک مخرج نام‌دار می‌آید، یعنی measurable_open و measurable_click کنار opened و clicked. عاملی که opened را بر issued تقسیم کند، برای پیامک نرخ بازشدن صفر درصد گزارش می‌کند که با اطمینان کامل غلط است. به او بگویید هر دو عدد را نقل کند.

وسط یک بازه را مثل یک اندازه‌گیری نقل می‌کند. بخش اثر افزوده lift و lift_low و lift_high را دارد. تخمین نقطه‌ای به‌تنهایی یک اندازه‌گیری نیست، وسط یک بازه است، و عاملی که فقط بگوید کمپین تبدیل را چند درصد بالا برد، تنها عددی را دور ریخته که می‌گوید اصلا کمپین کار کرده یا نه.

کلید یکتایی از خودش می‌سازد. در ارسال تراکنشی، کلید باید همان رویداد دنیای واقعی را شناسایی کند، مثلا order-8821-shipped. عاملی که کلید تصادفی بسازد، در هر تلاش دوباره یک کلید تازه دارد، و آن تلاش دوباره پیام دومی به گوشی یک آدم واقعی می‌فرستد.

پاسخ ۲۰۰ را «تحویل شد» می‌خواند. ارسال تراکنشی می‌تواند ۲۰۰ برگرداند با status برابر suppressed و یک reason، که یعنی پیام عمدا فرستاده نشده: لغو اشتراک، خاموش‌بودن کانال، فهرست منع، یا نبودن نشانی. پیش از اینکه به کسی بگویید اطلاع‌رسانی رفت، status را نگاه کنید.

بیشتر خطاهای اعتبارسنجی را نمی‌تواند بخواند. API عمومی برای خطاهای احراز هویت، مجوز، بودجه و فیلتر یک کد و یک پیام می‌دهد. چند هندلر پشت آن، شکل ساده‌تری می‌دهند که کلاینت‌ها نمی‌توانند پارسش کنند، پس عامل http 400 گزارش می‌کند و نمی‌تواند بگوید چرا. هر وقت این شد، خودتان همان فراخوانی را با curl بزنید و بدنه را بخوانید. جدول کاملش در صفحهٔ کدهای خطا است.

به متنی که خود تیم شما نوشته اعتماد می‌کند. نام سگمنت، نام کمپین و توضیح‌های فارسی به‌صورت متن ساده و بدون هیچ پوشش «محتوای نامعتمد» به مدل می‌رسند. اگر کسی نام یک سگمنت را دستوری بگذارد که به مدل نشانه رفته، مدل آن را دستور می‌خواند. فیلدهای متن آزاد پنل را یک کانال ورودی به عامل خودتان حساب کنید، چون همان هستند.

#بررسی چیزی که عامل ساخته

چهار دستور، به همان ترتیبی که ارزش دارد اجرا شوند.

curl -s https://api.segmentic.net/v1/whoami \
  -H "Authorization: Bearer sk_seg_REPLACE_ME"

{
  "tenant_id": 7,
  "api_key_id": 3,
  "role": "analyst",
  "permissions": [
    "analytics.read", "audit.read", "campaign.read", "data.export",
    "event.read", "journey.read", "member.read", "profile.read",
    "segment.read", "settings.read", "template.read"
  ],
  "scoped": false
}

curl -s https://api.segmentic.net/v1/capabilities \
  -H "Authorization: Bearer sk_seg_REPLACE_ME"

{
  "version": "v1",
  "features": {
    "segments": true,
    "campaigns": true,
    "analytics": true,
    "transactional": true,
    "export": false,
    "import": true,
    "journeys": true,
    "ingest": true,
    "async_exports": true,
    "campaign_approval": true
  },
  "limits": {
    "max_page_size": 100,
    "max_preview_rows": 100,
    "max_batch_size": 500,
    "estimate_sample": 100,
    "query_timeout_sec": 30
  }
}

مقدارهای features بالا را نمونه‌ای برای کپی‌کردن حساب نکنید. هر پرچم دقیقا یعنی «آیا این زیرسیستم روی این نصب سیم‌کشی شده»، پس از نصبی تا نصب دیگر فرق می‌کند و کل نکته‌اش خواندن آن است نه دانستنش. سه تای آن‌ها هم، export و import و journeys، روی این mux هیچ مسیری را باز نمی‌کنند: true بودنشان به شما نقطهٔ پایانی عمومی نمی‌دهد.

این سقف‌ها به جای مستندشدن، اعلام می‌شوند، تا هیچ کلاینت و هیچ عاملی عددی را در کد نبندد که ما بعدا عوضش می‌کنیم. اگر عامل به جای خواندن max_batch_size عدد 500 را داخل حلقهٔ دسته‌بندی نوشته، همان یک نکتهٔ بازبینی کد است.

curl -s https://api.segmentic.net/v1/schema/events \
  -H "Authorization: Bearer sk_seg_REPLACE_ME"

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

بعد چیزی را که به مرورگر می‌رود بگردید. این همان بررسی‌ای است که کسی انجامش نمی‌دهد و بیشتر از همه اهمیت دارد:

grep -r "sk_seg_" ./dist ./build ./.next ./public 2>/dev/null
grep -rn "NEXT_PUBLIC_.*SEG\|VITE_.*SEG" ./src 2>/dev/null

هرچه دستور اول پیدا کند یک راز است که حالا باید باطلش کنید، از مسیر تنظیمات، اتصال‌ها و یکپارچه‌سازی، کلیدهای API در پنل. باطل‌کردن از همان درخواست بعدی اثر می‌گذارد.