مستندات نسخه ۰٫۲

شروع کار با تارتانک

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

نکته امنیتی: برای استفاده از تارتانک نیازی به دریافت یا ذخیره‌کردن کلید OpenAI ندارید. حساب شما با یک توکن مستقل و قابل لغو به سامانه متصل می‌شود.

۱. نصب CLI

نسخه Node.js ۲۰ یا جدیدتر و Git روی سیستم شما لازم است. تا پیش از انتشار npm، نسخه آماده را مستقیماً از دامنه خود تارتانک نصب کنید:

$ npm install -g https://tcli.tartanak.com/downloads/tartanak-cli-0.2.0.tgz

پس از انتشار عمومی، دستور کوتاه npm install -g @tartanak/cli نیز همین نسخه را نصب می‌کند. SHA-256 بسته ↗

برای بررسی نصب می‌توانید از هر کدام از سه نام اجرایی استفاده کنید:

$ tartanak --version
Tartanak CLI 0.2.0 (engine 0.147.0)
$ tcli --help

دستور ورود یک آدرس و کد موقت نمایش می‌دهد. آدرس را در مرورگر باز کنید و ایمیل خود را با OTP تأیید کنید.

$ tartanak login
۱) https://tcli.tartanak.com/device را باز کنید
۲) کد ABCD-EFGH را تأیید کنید

نشست با permission محدود در ~/.tartanak/auth.json نگهداری و با فرمان داخلی کوتاه‌عمر تمدید می‌شود. تارتانک هیچ auth شخصی را از ~/.codex نمی‌خواند.

۳. اجرای اولین درخواست

وارد پوشه پروژه شوید و تارتانک را اجرا کنید:

$ cd my-project
$ tartanak
> خطای ورود کاربران را پیدا و تست کن

دستورهای کاربردی

tartanak exec "..." برای اجرای غیرتعاملی از مسیر API سازمانی
tartanak brain "..." برای درخواست از مغز خصوصی مالک روی VPS
tartanak brain-status برای وضعیت Device Code، runtime و حساب Codex
tartanak account برای حساب، نقش و اعتبار
tartanak models و tartanak model MODEL برای مدل‌ها
tartanak usage برای خلاصه مصرف حساب
tartanak doctor برای بررسی اتصال و نصب موتور
tartanak dashboard و tartanak docs برای بازکردن وب
tartanak logout برای لغو نشست فعلی

۴. اتصال هاب به Codex

حالت A: مغز خصوصی دستگاه‌های مالک، بدون API key

در صفحه مدیریت، بخش «مغز خصوصی Codex» را باز کنید و «شروع ورود با Device Code» را بزنید. VPS یک کد رسمی از Codex app-server می‌گیرد؛ شما در صفحه رسمی OpenAI وارد حساب ChatGPT خود می‌شوید و همان کد را تأیید می‌کنید. Codex توکن‌ها را داخل volume خصوصی tartanak_codex_home نگهداری و خودکار تازه می‌کند.

$ tartanak login
$ tartanak brain-status
$ tartanak brain "این خطا را تحلیل کن"
$ tartanak brain "ادامه بده" --thread THREAD_ID

این مسیر فقط برای ایمیل مالک تنظیم‌شده و دستگاه‌هایی است که خود مالک در تارتانک تأیید کرده است. app-server فقط از طریق stdio با backend صحبت می‌کند؛ WebSocket عمومی، دانلود auth.json، shell-command و endpoint نمایش توکن وجود ندارد. هر اجرا با شناسه، مدل، مدت و usage واقعی توکن ثبت می‌شود.

سقف ماهانه توکن

در همان صفحه مدیریت می‌توانید سقف کل مشترک و سقف پیش‌فرض هر دستگاه را تعیین کنید. مقدار اولیه سقف کل یک میلیارد و مقدار اولیه هر دستگاه پانصد میلیون توکن در ماه میلادی است. برای هر دستگاه نیز override جداگانه ۵۰۰ میلیون، یک میلیارد یا مقدار پیش‌فرض قابل انتخاب است. پیش از هر اجرا دو سقف به‌صورت تراکنشی بررسی می‌شوند و دو میلیون توکن ذخیره ایمنی موقت برای اجرای هم‌زمان نگه داشته می‌شود؛ پس از پایان، ذخیره با usage واقعی جایگزین می‌شود.

توکن‌های این حالت، مصرف ChatGPT/Codex هستند و قیمت API تومانی ندارند. این سقف داخلی تارتانک مستقل از rate limit حساب ChatGPT است. دستور tartanak brain-status سقف، مصرف و مانده کل و همان دستگاه را نشان می‌دهد.

حالت B: هاب چندکاربره با حسابداری تومانی

برای کاربران مستقل و کیف پول جدا، در OpenAI Platform یک Project و Service Account بسازید و credential را فقط در secretهای VPS قرار دهید:

OPENAI_API_KEY=sk-...
OPENAI_PROJECT_ID=proj_...
OPENAI_BASE_URL=https://api.openai.com/v1

این حالت مسیر tartanak و tartanak exec را برای اعضا فعال می‌کند و مصرف هر حساب را با usage رسمی API تسویه می‌کند. دو حالت مستقل‌اند و credential هیچ‌کدام به CLI ارسال نمی‌شود.

۵. اعتبار و محاسبه مصرف

پیش از ارسال درخواست، تارتانک تعداد ورودی را با شمارنده رسمی OpenAI به دست می‌آورد و اعتبار لازم برای بدترین حالت را موقتاً رزرو می‌کند. پس از پاسخ، صورتحساب فقط از usage نهایی ساخته و اضافه رزرو آزاد می‌شود. مقدار قابل استفاده همیشه «موجودی کل منهای رزروشده» است.

ورودی عادی، خواندن کش و نوشتن کش با سه نرخ مستقل محاسبه می‌شوند.
توکن reasoning داخل عدد خروجی قرار دارد و بار دوم شارژ نمی‌شود.
برای prompt بیش از ۲۷۲هزار توکن، نرخ long-context همان نسخه قیمت اعمال می‌شود.
شناسه هر درخواست برای هر کاربر یکتا است تا retry موجب دوباره‌کسرشدن نشود.
درخواست فاقد usage قطعی وارد صف تطبیق مالی می‌شود؛ مدیر می‌تواند پاسخ OpenAI را دوباره استعلام و با نسخه قیمت اصلی تسویه کند.

نرخ فروش از قیمت رسمی دلاری OpenAI، نرخ دلار ثبت‌شده توسط مالک و حاشیه سود ساخته می‌شود. نسخه قیمت هر درخواست تغییرناپذیر است تا گزارش تاریخی با تغییر تعرفه عوض نشود. مشاهده منبع رسمی قیمت‌ها ↗

۶. ثبت و انتشار در NPM

در npmjs.com/signup یک حساب بسازید، ایمیل را تأیید و 2FA را فعال کنید. سپس از منوی پروفایل Add an Organization را بزنید، نام tartanak و طرح رایگان public packages را انتخاب کنید. در ترمینال:

$ npm login
$ npm whoami
$ npm run pack:check --workspace @tartanak/cli
$ npm publish --workspace @tartanak/cli --access public --provenance=false

پس از انتشار اول، در Settings پکیج، GitHub Actions را به عنوان trusted publisher معرفی کنید و workflow موجود .github/workflows/publish-cli.yml را انتخاب کنید. ساخت حساب، پذیرش شرایط npm و تأیید 2FA باید توسط خود مالک انجام شود.

۷. امنیت

کلید OpenAI فقط در secretهای محیط سرور قرار دارد و هرگز به CLI ارسال نمی‌شود. توکن‌های کاربران کوتاه‌عمر، قابل چرخش و محدود به حساب خودشان هستند. retry شبکه برای درخواست مدل صفر است تا درخواست هزینه‌دار ناخواسته تکرار نشود و web search تعرفه‌دار تا تعریف سیاست جدا غیرفعال است. فرمان‌های حساس همچنان به تأیید کاربر در ترمینال نیاز دارند.