Birinchi plagin

Har bir qo‘shmoqchi bo‘lgan narsangiz uchun — yangi model provayderi, yangi tool, ruxsat siyosati, buyruq, fon ishi, editor bilan integratsiya — aniq, hujjatlashtirilgan joy bor. Loyiha maqsaddan mexanizmga (goal → mechanism) xaritalashni yuritadi: «nimani qo‘shmoqchisiz → qayerga borasiz».

Bu xarita saytda lookup shaklida, va u bo‘limning qolgan qismini oziqlantiradigan fayldan generatsiya qilinadi — demak, u repozitoriyadan chetga chiqa olmaydi.

Eng ko‘p ishlatiladigan joy: tool pipeline

Ko‘pchilik aynan tool pipeline’ga ulanadi — va aynan u yerda xato qilish eng oson. To‘rt nuqta bor:

Birinchi plagin: uch qadam

Model foydalanishi mumkin bo‘lgan tool qo‘shish — eng keng tarqalgan holat. Struktura har doim bir xil: kerakli narsani e’lon qiling, tool’ni tasvirlang, nima qilishini yozing. To‘rtinchi qadam yo‘q.

export const name = 'example-changelog'
export const inject = ['tools']

export function apply(ctx) {
  ctx.tools.register(defineTool({
    name: 'read_changelog',
    description: 'Returns the recent entries from the project changelog.',
    parameters: {
      version: { type: 'string', required: true, description: 'Version to look up' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      // exec.signal lets the work be cancelled if the turn is aborted
      return await findEntry(args.version, exec.signal)
    },
  }))
}

Bu kod rasmiy tadqiqot saytidan olingan va beshta Cordis g‘oyasining barchasi ichida: bog‘liqlik e’lon qilingan (inject: ['tools']), kontekst qabul qilingan (apply(ctx)), ro‘yxatdan o‘tkazish sodir bo‘lgan (ctx.tools.register). Va bu ro‘yxatdan o‘tkazish — o‘zini bekor qiladigan effekt: qism yukdan tushganda tool tizimdan o‘zi yo‘qoladi, olib tashlash uchun hech narsa yozmaysiz. Tool’ning tasviri model ko‘rsatmalariga o‘zi tushadi.

To‘rtta qoida

1. Argumentlar tekshirilgan keladi. E’lon qilganingizga ko‘ra validatsiya qilingan, shuning uchun tanada ular to‘g‘ri tipda. Tasviringiz ifoda etmagan narsa (masalan, son musbat bo‘lishi kerak) — hali sizning mas’uliyatingiz.
2. Ma’lumot qaytaring, xabar emas. Odam o‘qiy oladigan tushuntirish alohida beriladi. Agar proza qaytarsangiz, uni qabul qiluvchini uni parslashga majbur qilasiz.
3. Istisnolar — haqiqiy xatoliklar uchun. Throw qilish natijani xato deb belgilaydi va bu infratuzilma xatolari uchun. To‘g‘ri, lekin istalmagan natija (masalan, buyruq yomon chiqib tugagan) — bu ma’lumotda ifodalanadi.
4. Bekor qilishga hurmat. Signal ishga tushganda — davom etayotgan ish to‘xtaydi.

Bepul keladigan ikkita narsa

Birinchisi — Code mode’da ishlaydi. Ro‘yxatdan o‘tgan har qanday tool qo‘shimcha integratsiyasiz mavjud bo‘ladi, tiplari xuddi shu tasvirdan olinadi.

Ikkinchisi — standart interfeys. Qanday ko‘rinishini belgilamasangiz, umumiy karta (generic card) paydo bo‘ladi. Terminal chiqishi, fayl o‘zgarishlari va qidiruv natijalari uchun alohida formatlar bor.

Nashr qilish

Plagin konfiguratsiya qatlami qo‘shadigan paket sifatida tarqatiladi. Tavsiya etilgan oqim:

1. Avval Creator mode’da sinang — u yerda plagin xotirada o‘rnatilib va yechib olinishi mumkin.
2. Keyin paket qilib chiqaring.
3. Boshqalar topishi uchun repozitoriya dsh-plugin teg’i bilan belgilanadi.

Xulosa

Yangi xatti-harakat uchun har doim hujjatlashtirilgan joy bor — maqsaddan mexanizmga xarita. Eng ko‘p ishlatiladigan joy — tool pipeline: before, around, after va observe. Minimal plagin uch qadam: e’lon qilish, tasvirlash, yozish. Ro‘yxatdan o‘tkazish o‘zini bekor qiladi, tool Code mode’da bepul ishlaydi va standart interfeysga ega bo‘ladi. Keyingi modulda nazariyaga o‘tamiz: muammo, qaytariladigan effektlar va teoremalar.