Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

31.8 KB
Raw Blame

Contributing to OmniRoute (فارسی)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW


Thank you for your interest in contributing! This guide covers everything you need to get started.


راهاندازی محیط توسعه

پیشنیازها

  • Node.js نسخهٔ >=22.22.2 <23 یا >=24.0.0 <27 (پیشنهادی: 24 LTS)
  • npm نسخهٔ 10+

کاربران npm v11+‏ (Node 24+): پس از npm install، بررسی کنید که ماژولهای بومی نصب شده باشند: node -e "require('better-sqlite3')". اگر با خطای MODULE_NOT_FOUND مواجه شد، دستور npm approve-scripts better-sqlite3 && npm install را اجرا کنید. به عیبیابی مراجعه کنید.

  • Git

کلون و نصب

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install

متغیرهای محیطی

# فایل .env خود را از روی الگو ایجاد کنید
cp .env.example .env

# مقادیر محرمانهٔ موردنیاز را تولید کنید
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env

متغیرهای کلیدی برای توسعه:

متغیر مقدار پیشفرض توسعه توضیحات
PORT 20128 پورت سرور
NEXT_PUBLIC_BASE_URL http://localhost:20128 نشانی پایه برای فرانتاند
JWT_SECRET (در بالا تولید کنید) کلید محرمانهٔ امضای JWT
INITIAL_PASSWORD CHANGEME گذرواژهٔ ورود نخست
APP_LOG_LEVEL info سطح جزئیات گزارشها

تنظیمات داشبورد

داشبورد برای قابلیتهایی که از طریق متغیرهای محیطی نیز قابل پیکربندی هستند، گزینههای روشن/خاموش رابط کاربری ارائه میدهد:

محل تنظیمات گزینه توضیحات
تنظیمات ← پیشرفته حالت اشکالزدایی فعالسازی گزارش درخواستهای اشکالزدایی (رابط کاربری)
تنظیمات ← عمومی نمایش نوار کناری نمایش/پنهانکردن بخشهای نوار کناری

این تنظیمات در پایگاه داده ذخیره میشوند و پس از راهاندازی مجدد نیز باقی میمانند؛ همچنین در صورت تنظیمشدن، مقادیر پیشفرض متغیرهای محیطی را بازنویسی میکنند.

اجرای محلی

# حالت توسعه (بارگذاری مجدد خودکار)
npm run dev

# ساخت نسخهٔ تولیدی
npm run build    # next build → .build/next/ سپس assembleStandalone → dist/
npm run start

# کامپایل سریع و صرفاً بکاند/API برای تغییرات مشارکتکنندگان
npm run build:contributor

# ساخت انتشار (ساخت مجدد پاک + نشانگر HEAD — الزامی برای استقرار)
npm run build:release   # rm -rf .build dist && build + فایل dist/BUILD_SHA را مینویسد

# پیکربندی متداول پورت
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

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

ساختار خروجی ساخت

پوشه محتویات رهگیریشده
src/ کد منبع برنامه (TypeScript / TSX) بله
.build/ فایلهای میانی — خروجی next build (نادیدهگرفتهشده توسط git، distDir = .build/next) خیر
dist/ بستهٔ قابلانتشار — مونتاژشده توسط assembleStandalone (نادیدهگرفتهشده توسط git) خیر

خط لولهٔ ساخت در یک مرحله اجرا میشود:

npm run build
  └─ next build → .build/next/standalone  (خروجی Next.js)
  └─ assembleStandalone()                 (فایلهای مستقل + ایستا + عمومی + داراییهای بومی را کپی میکند)
       └─ خروجی: dist/                    (server.js, .next/static/, public/, node_modules/)

npm run build:release علاوه بر این، ابتدا هر دو پوشه را پاک میکند و dist/BUILD_SHA (= git rev-parse --short HEAD) را بهعنوان نشانگر صحت استقرار مینویسد.

npm run build:contributor از نمایهٔ ساخت صرفاً بکاند استفاده میکند. هنگام ساخت، فایلهای رابط کاربری داشبورد را بهطور موقت با فایلهای جایگزین ساده عوض میکند، کنترلکنندههای مسیر API را نگه میدارد و پس از ساخت، فایلهای اصلی را بازیابی میکند. برای تغییراتی که بر رابط کاربری داشبورد تأثیر میگذارند یا برای اعتبارسنجی کامل انتشار، از npm run build استفاده کنید؛ نمایهٔ مشارکتکنندگان جایگزینی برای ساخت انتشار نیست.

نکتهٔ استقرار روی VPS: پوشهٔ ایمیج راهدور /usr/lib/node_modules/omniroute/app/ بدون تغییر باقی مانده است. ابزارهای استقرار، محتویات dist/ را با rsync در آن همگامسازی میکنند. فقط مسیر خروجی ساخت درون مخزن تغییر کرده است (app/ → dist/).

نشانیهای پیشفرض:

  • داشبورد: http://localhost:20128/dashboard
  • API: http://localhost:20128/v1

گردشکار Git

⚠️ هرگز مستقیماً روی main کامیت نکنید. همیشه از شاخههای ویژگی استفاده کنید.

شاخهٔ پایهٔ PR: شاخهٔ فعال release/vX.Y.Z را هدف قرار دهید (نه main). برای آشنایی با مدل یک انتشار برای هر شاخه + برچسبگذاری هنگام عرضه، به docs/ops/BRANCHING_MODEL.md مراجعه کنید.

# از انتهای شاخهٔ انتشار فعال، شاخه بسازید (مثال: release/v3.8.49)
git fetch origin
git checkout -b feat/your-feature-name origin/release/v3.8.49
# ... تغییرات را اعمال کنید ...
git commit -m "feat: describe your change"
git push -u origin feat/your-feature-name
# یک Pull Request با base = release/v3.8.49 باز کنید

نامگذاری شاخهها

پیشوند کاربرد
feat/ ویژگیهای جدید
fix/ رفع باگها
refactor/ بازسازی ساختار کد
docs/ تغییرات مستندات
test/ افزودن/اصلاح تستها
chore/ ابزارها، CI و وابستگیها

پیامهای کامیت

از Conventional Commits پیروی کنید:

feat: افزودن قطعکنندهٔ مدار برای فراخوانیهای ارائهدهنده
fix: رفع حالت مرزی اعتبارسنجی کلید محرمانهٔ JWT
docs: بهروزرسانی SECURITY.md با محافظت از PII
test: افزودن تستهای واحد مشاهدهپذیری
refactor(db): یکپارچهسازی جدولهای محدودیت نرخ

دامنهها (v3.8): db، sse، oauth، dashboard، api، cli، docker، ci، mcp، a2a، memory، skills، cloud-agent، guardrails، compression، auto-combo، resilience، providers، executors، translator، domain، authz.


اجرای آزمونها

# همهٔ آزمونها (واحد + vitest + اکوسیستم + e2e)
npm run test:all

# یک فایل آزمون (اجراکنندهٔ بومی آزمون Node.js — بیشتر آزمونها از این استفاده میکنند)
node --import tsx/esm --test tests/unit/your-file.test.ts

# فقط آزمونهای واحدی که تحت تأثیر تغییر شما قرار گرفتهاند (همان انتخابگر TIA دروازهٔ CI، #8084)
npm run test:scoped            # تغییرات در آخرین commit (یا درخت کاری)
npm run test:scoped:staged     # فقط تغییرات staged — برای اجرا پیش از commit مناسب است
npm run test:scoped:full       # ابتدا نگاشت گراف import را بازسازی میکند (پس از افزودن/انتقال فایلها)
# خروج با کد 1 بههمراه «مجموعهٔ کامل را اجرا کنید» یعنی یک فایل مرکزی (tsconfig، package.json، …) یا یک
# منبع نگاشتنشده تغییر کرده است — انتخابگر بهشکل ایمن شکست میخورد و هرگز بیسروصدا چیزی را رد نمیکند.

# Vitest (سرور MCP، autoCombo، حافظهٔ نهان)
npm run test:vitest

# آزمونهای E2E (به Playwright نیاز دارد)
npm run test:e2e

# آزمون E2E کلاینتهای پروتکل (انتقالهای MCP، A2A)
npm run test:protocols:e2e

# آزمونهای سازگاری اکوسیستم
npm run test:ecosystem

# دروازهٔ پوشش: 60٪ دستورها/خطوط/توابع/شاخهها
npm run test:coverage
npm run coverage:report

# بررسی lint و قالببندی
npm run lint
npm run check

# آزمون سریع و کنترلشدهٔ ترکیب واقعی upstream (به دسترسی VPS و اعتبار واقعی ارائهدهنده نیاز دارد)
# با ارائهدهندگان واقعی ارتباط برقرار میکند — کمی هزینه دارد. هرگز در CI اجرا نمیشود. بدون دروازه بهدرستی رد میشود.
# نیازمند: دسترسی ssh [email protected] (یک snapshot فقطخواندنی از DB را از VPS بارگذاری میکند).
RUN_COMBO_LIVE=1 npm run test:combo:live

# آزمون سریع زندهٔ VPS در فاز 3 — اسکریپتهای سادهٔ Node ESM که مستقیماً به سرور زندهٔ .15 متصل میشوند.
# نیازمند: دسترسی ssh [email protected] (ترکیبها از طریق SSH sqlite ایجاد/حذف میشوند).
# با ارائهدهندگان واقعی ارتباط برقرار میکند (هزینهٔ اندک). فقط ترکیبهای __live_test__* را ایجاد/حذف میکند. هرگز در CI اجرا نمیشود.
# مقدار REQUIRE_API_KEY=false روی .15 است، بنابراین کلید API لازم نیست؛ اما در صورت تنظیم، COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY را رعایت میکند.
npm run test:combo:live:vps              # 7 سناریوی HTTP (اولویت/نوبتگردشی/وزندار/هزینه/ادغام/خودکار + سلامت)
npm run test:combo:live:vps:failover     # یک سناریوی واقعی failover میان ارائهدهندگان اضافه میکند (در مجموع 8 مورد)

نکات مربوط به پوشش:

  • npm run test:coverage پوشش کد منبع را برای مجموعهٔ اصلی آزمونهای واحد اندازهگیری میکند، tests/** را کنار میگذارد و open-sse/** را شامل میشود
  • درخواستهای ادغام باید دروازهٔ پوشش را برای دستورها/خطوط/توابع/شاخهها در سطح 60%+ نگه دارند
  • اگر یک PR کد عملیاتی را در src/، open-sse/، electron/ یا bin/ تغییر دهد، باید در همان PR آزمونهای خودکار را اضافه یا بهروزرسانی کند
  • npm run coverage:report گزارش تفصیلی فایلبهفایل را از آخرین اجرای پوشش نمایش میدهد
  • npm run test:coverage:legacy معیار قدیمیتر را برای مقایسهٔ تاریخی حفظ میکند
  • برای نقشهٔ راه مرحلهای بهبود پوشش، docs/ops/COVERAGE_PLAN.md را ببینید

الزامات درخواست ادغام

پیش از باز کردن یک PR، از مسیر طلایی مشارکت استفاده کنید تا چرخهٔ متمرکز مربوط به تغییرات خود را اجرا کنید. مجموعهٔ کامل آزمونهای واحد (4 بخش CI)، Vitest، دروازهٔ پوشش 60%+ و ساخت عملیاتی بر عهدهٔ CI هستند — اجرای محلی آنها هیچ اطلاعاتی فراتر از آنچه بررسیهای PR ارائه میکنند به دست نمیدهد و در سیستمهای ضعیفتر میتواند میزبان را اشباع کند (#8084):

  • فایلهای آزمونی را که تغییر شما را پوشش میدهند اجرا کنید: node --import tsx/esm --test tests/unit/<file>.test.ts
  • npm run lint را اجرا کنید
  • هر زمان کد عملیاتی تغییر میکند، آزمونهای خودکار را در همان PR اضافه یا بهروزرسانی کنید
  • هنگامی که کد عملیاتی تغییر کرده است، فایلهای آزمون تغییریافته یا افزودهشده را در توضیحات PR ذکر کنید
  • وقتی secretهای پروژه در CI پیکربندی شدهاند، نتیجهٔ SonarQube را در PR بررسی کنید

وضعیت فعلی آزمونها: 122 فایل آزمون واحد با پوشش موارد زیر:

  • مترجمهای ارائهدهندگان و تبدیل قالب
  • محدودسازی نرخ، circuit breaker و تابآوری
  • حافظهٔ نهان معنایی، idempotency و رهگیری پیشرفت
  • عملیات پایگاه داده و schema (21 ماژول DB)
  • جریانهای OAuth و احراز هویت
  • اعتبارسنجی endpointهای API ‏(Zod v4)
  • ابزارهای سرور MCP و اعمال scope
  • سیستمهای Memory و Skills

سبک کدنویسی

  • ESLint — پیش از commit کردن، npm run lint را اجرا کنید
  • Prettier — هنگام commit از طریق lint-staged بهطور خودکار قالببندی میشود (۲ فاصله، نقطهویرگول، کوتیشن دوتایی، عرض ۱۰۰ کاراکتر، ویرگول انتهایی es5)
  • TypeScript — تمام کدهای src/ از .ts/.tsx استفاده میکنند؛ open-sse/ از .ts/.js استفاده میکند؛ مستندسازی را با TSDoc (@param، @returns، @throws) انجام دهید
  • عدم استفاده از eval() — ESLint قواعد no-eval، no-implied-eval و no-new-func را اعمال میکند
  • اعتبارسنجی Zod — برای اعتبارسنجی تمام ورودیهای API از schemaهای Zod v4 استفاده کنید
  • نامگذاری: فایلها = camelCase/kebab-case، کامپوننتها = PascalCase، ثابتها = UPPER_SNAKE

مدیریت خطا / بلوکهای catch خالی

هرگز یک catch را بدون توضیح رها نکنید. آن را در یکی از دو دسته زیر طبقهبندی کنید (این کار، قاعده سختگیرانه «هرگز خطاهای جریانهای SSE را بیسروصدا نادیده نگیرید» را عملیاتی میکند):

  • عمدی (پاکسازی/تلهمتری best-effort خودمان) — بروز خطا در اینجا مورد انتظار و بیضرر است؛ یک توضیح یکخطی درباره دلیل آن اضافه کنید و چیزی لاگ نکنید (این قرارداد از ایجاد نویز ناشی از لاگکردن هر درخواست جلوگیری میکند).

    } catch {} // بستن controllerای که پس از قطع اتصال کلاینت از قبل بسته شده است، مورد انتظار است
    
  • نیازمند لاگ (کد خارجی/ارائهشده توسط فراخواننده، یا حالتی که نادیدهگرفتن خطا جریان کنترل را تغییر میدهد) — catch را حفظ کنید (هرگز اجازه ندهید جریان را مختل کند)، اما یک console.debug/warn همراه با اطلاعات زمینهای ثبت کنید تا خطا قابل کشف باشد.

    } catch (e) {
      console.debug("[STREAM] onFailure callback error:", e);
    }
    

برای مشاهده نمونههای اعمالشده، به open-sse/utils/stream.ts و open-sse/utils/streamHandler.ts مراجعه کنید.


ساختار پروژه

src/                        # TypeScript (.ts / .tsx)
├── app/                    # مسیریاب برنامه Next.js 16
│   ├── (dashboard)/        # صفحات داشبورد (۲۳ بخش)
│   ├── api/                # مسیرهای API (۵۱ دایرکتوری)
│   └── login/              # صفحات احراز هویت (.tsx)
├── domain/                 # موتور سیاستگذاری (policyEngine، comboResolver، costRules و غیره)
├── lib/                    # منطق اصلی کسبوکار (.ts)
│   ├── a2a/                # سرور پروتکل Agent-to-Agent v0.3
│   ├── acp/                # رجیستری Agent Communication Protocol
│   ├── compliance/         # موتور سیاستگذاری انطباق
│   ├── db/                 # ماژولهای دامنه SQLite + ۱۳۰ مهاجرت
│   ├── memory/             # حافظه پایدار مکالمه
│   ├── oauth/              # ارائهدهندگان، سرویسها و ابزارهای OAuth
│   ├── skills/             # چارچوب مهارت توسعهپذیر
│   ├── usage/              # ردیابی میزان استفاده و محاسبه هزینه
│   └── localDb.ts          # فقط لایه بازصادرکردن — هرگز منطق را اینجا اضافه نکنید
├── middleware/              # میانافزار درخواست (promptInjectionGuard)
├── mitm/                   # پراکسی MITM (گواهی، DNS، مسیریابی مقصد)
├── shared/
│   ├── components/         # مؤلفههای React (.tsx)
│   ├── constants/          # تعاریف ارائهدهندگان (۳۲۹)، محدودههای MCP، ۲۰ راهبرد مسیریابی
│   ├── utils/              # قطعکننده مدار، پاکساز و ابزارهای احراز هویت
│   └── validation/         # شِماهای Zod v4
└── sse/                    # خط لوله پراکسی SSE

open-sse/                   # فضای کاری @omniroute/open-sse
├── executors/              # ۱۵۰ ماژول اجراکننده (کلاسهای اجراکننده + ابزارهای ویژه هر ارائهدهنده)
├── handlers/               # ۱۱ کنترلکننده درخواست (گفتوگو، پاسخها، جاسازیها، تصاویر و غیره)
├── mcp-server/             # سرور MCP (۱۱۰ ابزار منحصربهفرد، ۳ انتقال، ۳۳ محدوده)
├── services/               # ۱۷۸ سرویس سطحبالا (combo، autoCombo، rateLimitManager و غیره)
├── translator/             # مترجمهای قالب (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
├── transformer/            # تبدیلکننده Responses API
└── utils/                  # ۲۲ ماژول کاربردی (جریان، TLS، پراکسی، ثبت رویداد)

electron/                   # برنامه دسکتاپ Electron (چندسکویی)

tests/
├── unit/                   # اجراکننده آزمون Node.js (۱٬۵۷۴ فایل آزمون)
├── integration/            # آزمونهای یکپارچهسازی
├── e2e/                    # آزمونهای Playwright
├── security/               # آزمونهای امنیتی
├── translator/             # آزمونهای ویژه مترجم
└── load/                   # آزمونهای بار

docs/
├── adr/                     # سوابق تصمیمهای معماری
├── architecture/            # معماری و تابآوری سیستم
├── comparison/              # مقایسه OmniRoute با جایگزینها
├── compression/             # راهنماها و قواعد فشردهسازی
├── dev/                     # راهنماهای توسعه
├── diagrams/                # نمودارهای معماری
├── frameworks/              # MCP، A2A، OpenCode، حافظه، مهارتها
├── guides/                  # راهنمای کاربر، Docker، راهاندازی، عیبیابی
├── i18n/                    # ترجمههای بینالمللیشده README
├── marketing/               # مطالب بازاریابی
├── ops/                     # استقرار، پراکسی، پوشش آزمون، انتشارها
├── providers/               # مستندات ویژه ارائهدهندگان
├── reference/               # مرجع API، متغیرهای محیطی، ابزارهای CLI، سطوح رایگان
├── releases/                # یادداشتهای انتشار
├── routing/                 # موتور ترکیب خودکار، بازپخش استدلال
├── screenshots/             # تصاویر داشبورد
├── security/                # محدودیتهای ایمنی، انطباق، پنهانکاری، توکنها
└── specs/                   # مشخصات طراحی

افزودن یک ارائهدهنده جدید

مرحله 1: ثبت ثابتهای ارائهدهنده

آنها را به src/shared/constants/providers.ts اضافه کنید — اعتبارسنجی با Zod هنگام بارگذاری ماژول انجام میشود.

مرحله 2: افزودن اجراکننده (در صورت نیاز به منطق سفارشی)

یک اجراکننده در open-sse/executors/your-provider.ts ایجاد کنید که اجراکننده پایه را گسترش دهد.

مرحله 3: افزودن مترجم (در صورت استفاده از قالبی غیر از OpenAI)

مترجمهای درخواست/پاسخ را در open-sse/translator/ ایجاد کنید.

مرحله 4: افزودن پیکربندی OAuth (در صورت مبتنی بودن بر OAuth)

اعتبارنامههای OAuth را در src/lib/oauth/constants/oauth.ts و سرویس را در src/lib/oauth/services/ اضافه کنید.

اگر ارائهدهنده بالادستی یک OAuth client_id/secret عمومی یا کلید Firebase Web API را در CLI عمومی / بسته مرورگر خود توزیع میکند، آن را بهصورت یک رشته ثابت در کد قرار ندهید. از resolvePublicCred() در open-sse/utils/publicCreds.ts استفاده کنید و یک ورودی بایتی پوشاندهشده به EMBEDDED_DEFAULTS اضافه کنید. گردشکار الزامی کامل در docs/security/PUBLIC_CREDS.md مستند شده است.

درون کنترلکنندهها/اجراکنندهها، پیامهای خطایی که به کلاینت میرسند باید از buildErrorBody() / sanitizeErrorMessage() در open-sse/utils/error.ts عبور کنند — هرگز err.stack یا err.message خام را در بدنه Response قرار ندهید. به docs/security/ERROR_SANITIZATION.md مراجعه کنید.

مرحله 5: ثبت مدلها

تعریفهای مدل را به open-sse/config/providerRegistry.ts اضافه کنید.

مرحله 6: افزودن آزمونها

آزمونهای واحد را در tests/unit/ بنویسید که حداقل موارد زیر را پوشش دهند:

  • ثبت ارائهدهنده
  • ترجمه درخواست/پاسخ
  • مدیریت خطا

چکلیست Pull Request

  • تستها با موفقیت اجرا میشوند (npm test)
  • بررسی Lint با موفقیت انجام میشود (npm run lint)
  • Build با موفقیت انجام میشود (npm run build)
  • نوعهای TypeScript برای توابع و رابطهای عمومی جدید اضافه شدهاند
  • هیچ مقدار محرمانه یا مقدار جایگزینی بهصورت hardcoded وجود ندارد
  • اطلاعات احراز هویت عمومی upstream از طریق resolvePublicCred() تعبیه شدهاند (به docs/security/PUBLIC_CREDS.md مراجعه کنید) و هرگز بهصورت literal درج نشدهاند
  • پاسخهای خطا از طریق buildErrorBody() / sanitizeErrorMessage() پردازش میشوند — هیچ stack trace خامی در بدنه پاسخها وجود ندارد (به docs/security/ERROR_SANITIZATION.md مراجعه کنید)
  • فرمانهای Shell (exec / spawn) مقادیر زمان اجرا را از طریق env ارسال میکنند، نه از طریق درونیابی رشتهای
  • همه ورودیها با schemaهای Zod اعتبارسنجی شدهاند
  • برای تغییرات قابل مشاهده برای کاربر، یک قطعه Changelog در مسیر changelog.d/{features|fixes|maintenance}/<PR>-<slug>.md اضافه شده است (به changelog.d/README.md مراجعه کنید) — فایل CHANGELOG.md را مستقیماً ویرایش نکنید؛ قطعهها هنگام انتشار تجمیع میشوند و هرگز میان PRها تداخل ایجاد نمیکنند
  • مستندات بهروزرسانی شدهاند (در صورت نیاز)
  • هیچ هشدار جدید CodeQL / Secret-Scanning ایجاد نشده است، یا هر هشدار با توجیه فنی و ارجاع به سند مرتبط در docs/security/ رد شده است
  • مسیرهایی که فرایندهای فرزند ایجاد میکنند (/api/mcp/، /api/cli-tools/runtime/) در src/server/authz/routeGuard.ts بهعنوان isLocalOnlyPath() طبقهبندی شدهاند — به قانون سختگیرانه شماره ۱۵ مراجعه کنید
  • هیچ trailer از نوع Co-authored-by برای AI/bot در پیامهای commit وجود ندارد (قانون سختگیرانه شماره ۱۶) — از همکاران انسانی که از کارشان دوباره استفاده شده است، با trailerهای استاندارد Co-authored-by: Name <email> قدردانی میشود

انتشار

انتشارها از طریق گردشکار /generate-release مدیریت میشوند. هنگامی که یک GitHub Release جدید ایجاد شود، بسته از طریق GitHub Actions بهطور خودکار در npm منتشر میشود.

برای استقرار روی VPS، از npm run build:release (نه npm run build) استفاده کنید — این فرمان یک بازسازی پاک انجام میدهد، بسته را در dist/ مونتاژ میکند و فایل نشانهگر dist/BUILD_SHA را مینویسد. سپس از مهارتهای /deploy-vps-*-cc استفاده کنید که با استفاده از rsync، پوشهٔ dist/ را به دایرکتوری راهدور app/ منتقل میکنند.


دریافت راهنمایی