تولید کد

از مدل‌های AvalAI برای نوشتن، بازبینی، refactor و debug کد با APIهای سازگار با OpenAI استفاده کنید.

راهنمای رسمی code generation در OpenAI، Responses API را برای workflowهای کدنویسی مبتنی بر API و Codex را برای مهندسی نرم‌افزار agentic پیشنهاد می‌کند. در AvalAI همین الگو را با AVALAI_API_KEY و https://api.avalai.ir/v1 به کار ببرید: برای workflowهای جدید از /v1/responses شروع کنید، برای ادغام‌های موجود Chat Completions را نگه دارید، و وقتی agent در ترمینال یا editor می‌خواهید از راه‌اندازی Codex استفاده کنید.

انتخاب Workflow کدنویسی

Workflow	مسیر پیشنهادی	نکته
تولید کد یا debug یک‌مرحله‌ای	/v1/responses	از instructions، ورودی کوتاه و response.output_text استفاده کنید.
دستیار کدنویسی chat-based موجود	/v1/chat/completions	اگر app پایدار است نگه دارید؛ وقتی به آیتم‌های Responses، reasoning یا ابزارها نیاز دارید، flow به flow مهاجرت کنید.
ویرایش repo، تست و review	Codex با AvalAI به‌عنوان provider	راه‌اندازی Codex را ببینید.
refactorهای بزرگ	Responses همراه retrieval/tool loop خودتان	فقط فایل‌های مرتبط را بفرستید؛ وقتی ابزار یا reasoning دارید آیتم‌های response.output را حفظ کنید.

Agentهای Skill-aware و Apply Patch

OpenAI ابزار apply_patch را به‌عنوان ابزار Responses/Agents SDK مستند کرده است که آیتم‌های ساختاریافته apply_patch_call برای ساخت، به‌روزرسانی و حذف فایل برمی‌گرداند. در AvalAI این را قابلیت ویرایش میزبانی‌شده و وابسته به route بدانید، نه تضمین عمومی. اگر route انتخابی شما صریحا از tools: [{"type": "apply_patch"}] پشتیبانی نمی‌کند، از مدل یک unified diff معمولی بخواهید و آن را در workflow بازبینی خودتان، session کدکس یا patch harness backend اعمال کنید.

وقتی apply-patch harness می‌سازید، مدل فقط پیشنهاد diff بدهد و enforcement در برنامه شما بماند:

• مسیرها را به workspace مجاز محدود کنید و directory traversal را رد کنید؛
• patchها را در یک کپی scratch یا transaction اعمال کنید، اگر ممکن است؛
• برای هر call_id دقیقا یک apply_patch_call_output با status: "completed" یا status: "failed" و خطای کوتاه برگردانید؛
• بعد از هر دور ویرایش، test، linter یا git diff --check را اجرا کنید و failureها را مثل input عادی به مدل برگردانید؛
• برای حذف فایل، تغییر dependency، binary تولیدشده، migration یا rewrite گسترده approval انسانی بگیرید.

Skillهای OpenAI bundleهای نسخه‌دار با manifest به نام SKILL.md هستند که می‌توانند agentهای shell یا coding را راهنمایی کنند. در برنامه‌های AvalAI، Skill را instruction و code ممتاز بدانید: پیش از استفاده review کنید، آن را به workflowهای مشخص محصول map کنید و اجازه ندهید کاربر نهایی هر Skill دلخواهی را از catalog باز attach کند. اگر Skill میزبانی‌شده روی route شما فعال نیست، همان دانش را در docs مخزن، prompt templateها، توضیح ابزارها یا فایل‌های runtime محلی خودتان نگه دارید.

قالب Brief برای Task کدنویسی

مثال‌های code generation در OpenAI فراخوانی مدل را ساده نگه می‌دارند: ورودی task، instructions اختیاری در سطح سیستم، و مدل کدنویسی با reasoning effort بالاتر. برای appهای AvalAI، این ورودی را به یک brief کوتاه و تکرارپذیر تبدیل کنید:

• هدف: یک جمله درباره تغییر، bug یا سوال review.
• فایل‌های مجاز: مسیر دقیق فایل‌هایی که مدل می‌تواند inspect یا edit کند.
• زمینه: فقط source مرتبط، excerpt مستندات، stack trace یا contract API.
• محدودیت‌ها: non-goalهایی مثل «public API را تغییر نده»، «dependency جدید اضافه نکن» یا «متن RTL را سالم نگه دار».
• خروجی مورد انتظار: diagnosis، unified diff، فایل جایگزین، test plan یا review note.
• راستی‌آزمایی: commandی که انسان یا agent بعد از اعمال patch باید اجرا کند.

نمونه ورودی برای /v1/responses:

Goal: Fix the empty-state bug in the billing table.
Allowed files: src/components/BillingTable.tsx, tests/BillingTable.test.tsx
Context: The table renders nothing when invoices=[]; expected copy is "No invoices yet".
Constraints: Keep existing props and CSS classes. Do not add dependencies.
Expected output: Short diagnosis, minimal unified diff, and targeted test command.
Verification: npm test -- BillingTable.test.tsx

این brief را به‌عنوان input استفاده کنید و رفتار پایدار را در instructions نگه دارید. اگر مدل tool call، reasoning item یا چند آیتم خروجی برگرداند، response.output را بخوانید؛ از response.output_text فقط برای متن نهایی قابل‌خواندن توسط انسان استفاده کنید.

انتخاب مدل

مدلی را انتخاب کنید که با پیچیدگی کار هماهنگ باشد:

• gpt-5.5: انتخاب پیش‌فرض قوی برای کدنویسی همراه استدلال عمومی.
• gpt-5.3-codex: بهینه‌شده برای workflowهای agentic coding به سبک Codex.
• claude-opus-4-8: مناسب برای codebaseهای بزرگ و استدلال long-context.
• kimi-k2.7-code: جایگزین coding-focused قوی وقتی تنوع provider می‌خواهید.

پیش از production، جزئیات مدل‌ها و صفحه ارائه‌دهنده‌ها را بررسی کنید؛ availability، طول context و پشتیبانی route می‌تواند متفاوت باشد.

توسعه Frontend و Agentهای متکی بر مستندات

راهنمای code generation در OpenAI تأکید می‌کند مدل‌های جدید GPT وقتی داخل یک agent harness اجرا شوند، برای توسعه frontend بسیار قوی هستند. در AvalAI، تولید UI را با یک brief محدود و دقیق ایمن‌تر کنید، نه با درخواست مبهم:

• framework، package manager، component library و فایل‌هایی را که اجازه تغییر دارند مشخص کنید؛
• screenshot، tokenهای CSS، الزامات accessibility و breakpointهای responsive را اضافه کنید؛
• از مدل یک مسیر پیاده‌سازی بخواهید، سپس app را اجرا کنید و با هدف بصری مقایسه کنید؛
• متن قابل مشاهده برای کاربر، theme tokenها و نیازهای RTL/LTR را برای محصولات دوزبانه صریح بنویسید.

برای دستیارهای کدنویسی متکی بر docs، به حافظه مدل برای جزئیات API اعتماد نکنید. ابتدا صفحه مستندات، changelog یا convention داخلی مرتبط را retrieve کنید، سپس فقط excerptهای لازم را به /v1/responses بدهید. از مدل بخواهید excerpt استفاده‌شده را cite کند و رفتار API نامطمئن را به‌عنوان assumption علامت بزند. این نسخه قابل‌حمل AvalAI از الگوی docs-agent در OpenAI است.

مثال Responses

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model=os.getenv("AVALAI_MODEL", "gpt-5.5"),
    instructions=(
        "You are a senior software engineer. Return a concise diagnosis, "
        "then a minimal patch suggestion. Do not invent files."
    ),
    input="Find the likely null pointer bug in this code:\\n\\n...paste code here...",
    reasoning={"effort": "high"},
)

print(response.output_text)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: process.env.AVALAI_MODEL ?? "gpt-5.5",
  instructions:
    "You are a senior software engineer. Return a concise diagnosis, then a minimal patch suggestion. Do not invent files.",
  input: "Find the likely null pointer bug in this code:\\n\\n...paste code here...",
  reasoning: { effort: "high" },
});

console.log(response.output_text);

Bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "instructions": "You are a senior software engineer. Return a concise diagnosis, then a minimal patch suggestion. Do not invent files.",
    "input": "Find the likely null pointer bug in this code:\n\n...paste code here...",
    "reasoning": { "effort": "high" }
  }'

جایگزین Chat Completions

وقتی دستیار کدنویسی موجود هنوز بر Chat Completions ساخته شده یا مدل انتخابی فقط chat compatibility دارد، از این شکل استفاده کنید.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

completion = client.chat.completions.create(
    model=os.getenv("AVALAI_MODEL", "gpt-5.5"),
    messages=[
        {"role": "system", "content": "You are a senior software engineer."},
        {
            "role": "user",
            "content": "Refactor this function for readability:\\n\\n...code...",
        },
    ],
)

print(completion.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const completion = await client.chat.completions.create({
  model: process.env.AVALAI_MODEL ?? "gpt-5.5",
  messages: [
    { role: "system", content: "You are a senior software engineer." },
    { role: "user", content: "Refactor this function for readability:\\n\\n...code..." },
  ],
});

console.log(completion.choices[0].message.content);

Bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "You are a senior software engineer."},
      {"role": "user", "content": "Refactor this function for readability:\n\n...code..."}
    ]
  }'

چک‌لیست Prompting

• زبان، framework، نسخه runtime و فایل‌هایی را که اجازه تغییر دارند مشخص کنید.
• از مدل یک patch حداقلی یا فایل کامل جایگزین بخواهید، نه هر دو.
• خروجی تست ناموفق، stack trace و پیام خطای دقیق را اضافه کنید.
• برای repoهای بزرگ، فقط فایل‌های مرتبط را retrieve کنید و از مدل بخواهید قبل از تغییر کد assumptionها را فهرست کند.
• برای refactor، non-goalها را مشخص کنید؛ مثل «public API را تغییر نده» یا «schema دیتابیس را تغییر نده».
• برای کد تولیدشده، قبل از release تست و linter را اجرا کنید؛ خروجی مدل را draft بدانید.

Workflow بازبینی، Diff و امنیت

برای کار روی repository، از مدل بخواهید خروجی را در شکلی قابل review تولید کند:

• وقتی task چند فایل را لمس می‌کند، پیش از کد یک plan کوتاه بخواهید.
• برای بازبینی patch، unified diff یا فایل‌های جایگزین با نام روشن را ترجیح دهید.
• از مدل بخواهید تغییرهای public API، گام‌های migration و پوشش test را توضیح دهد.
• ابتدا testهای هدفمند را اجرا کنید، سپس وقتی patch پایدار شد testها یا linterهای گسترده‌تر را اجرا کنید.
• کد تولیدشده را untrusted بدانید: dependencyهای جدید، shell commandها، مسیر فایل‌ها، SQL، regex، منطق authentication و network callها را پیش از اجرا review کنید.
• برای کد security-sensitive، یک threat-model pass بخواهید و مدل را ملزم کنید assumptionها، input validation، authorization checkها و مرزهای secrets-handling را مشخص کند.

نکات مهاجرت

• messages → input همراه instructions اختیاری در سطح بالا.
• choices[0].message.content → response.output_text.
• برای agentهای کدنویسی tool-using، response.output را بررسی کنید و آیتم‌های typed مثل reasoning، function_call و function_call_output را حفظ کنید.
• برای ویرایش فایل‌هایی که خروجی آن‌ها تا حد زیادی معلوم است، اگر باید روی Chat Completions بمانید خروجی‌های پیش‌بینی‌شده را ببینید.

راهنماهای مرتبط

• Responses در مقابل Chat Completions
• مهندسی پرامپت
• فراخوانی تابع
• راه‌اندازی Codex
• خروجی‌های پیش‌بینی‌شده