Laras konteks alat ejen

Panduan ini merangkumi kerja praktikal di sekeliling permukaan alat dua peringkat: melihat apa yang dihantar oleh sesuatu larian, mengubahnya, dan mendiagnosis ejen yang memilih alat yang salah. Untuk mengetahui mengapa ia berfungsi begini, baca Konteks alat dan caching prompt.

Lihat apa yang sebenarnya dihantar oleh sesuatu larian

Buka sesuatu perbualan dan ketik penunjuk penggunaan konteks pada pengepala perbualan. Ia membina semula permukaan tepat yang akan dihantar oleh penghantaran seterusnya, tanpa menjalankan apa-apa. Lihat lagi (atau perintah /context) membuka penjelajah konteks penuh, tempat anda boleh memeriksa setiap alat.

Dua segmen penting di sini:

• Takrifan alat dan Alat MCP & dinamik — set residen, dengan kos token sebenar setiap alat.
• Alat dimuatkan atas permintaan — indeks tertunda. Setiap entri hanya dicaj pada namanya, kerana nama itulah sahaja yang dibawa oleh permintaan; membuka satu entri masih menunjukkan huraian dan skema penuhnya, jadi anda boleh melihat apa yang akan dikenakannya jika larian itu menariknya masuk.

Jika segmen tertunda kosong, penundaan dimatikan untuk pelayan ini. Semak --tool-deferral pada CLI cc_server.

Ubah alat mana yang dimuatkan lebih awal

Set residen ialah polisi, bukan konfigurasi — ia terletak dalam ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) dan terpakai pada setiap larian:

• residentBuiltins — perbendaharaan kata fail dan shell.
• residentDiscovery — search_tools dan list_my_tools. Jangan buang ini; inilah cara ejen mencapai semua yang lain.
• residentMcpTools — segelintir alat Control Center yang berbaloi menanggung skemanya pada setiap permintaan.
• Blok mengikut modus, untuk alat yang digunakan oleh modus tertentu hampir pada setiap pusingan.

Dua peraturan semasa menyuntingnya:

Tambah alat hanya jika kebanyakan larian menggunakannya. Setiap nama menanggung kos skemanya pada setiap permintaan bagi setiap larian, selamanya. Alat yang penting apabila digunakan tetapi jarang secara keseluruhan tergolong dalam bahagian tertunda — ejen tetap akan menemukannya.

Gunakan nama sebenar alat itu. Nama residen yang tidak sepadan dengan mana-mana alat bersifat lengai: tiada ralat, tiada amaran, alat itu hanya ditunda. test/tooling/resident_tool_names_test.dart menangkap perkara ini dan juga mengekalkan setiap modus di bawah 40 alat residen, dan itulah tujuan latihan ini — melepasi julat itu, pemilihan alat merosot secara boleh diukur.

Kata kerja yang diperlukan dan yang dipin bagi sesuatu modus ditambah secara automatik, jadi anda tidak pernah perlu menyenaraikan kata kerja output modus itu sendiri.

Diagnosis pilihan alat yang buruk

Apabila ejen menggunakan alat yang salah atau mendakwa ia tidak boleh melakukan sesuatu, tentukan yang mana antara tiga perkara ini yang telah berlaku.

1. Adakah ia mencarinya?

Setiap larian merekodkan alat tertunda yang dimuatkannya dan apa yang mencetuskannya — panggilan terus mengikut nama, atau pertanyaan search_tools. Buka strim peristiwa larian itu (Tetapan → Ruang kerja → Ejen → ejen → Log → Lihat) dan cari [harness] loaded N deferred tool(s).

• Tiada apa dilog, dan ejen berkata keupayaan itu tiada — ia tidak pernah mencarinya. Itu masalah prompt, bukan masalah pengambilan: indeks tertunda berada dalam prompt sistemnya bersama arahan supaya tidak mengisytiharkan sesuatu keupayaan tiada sehingga sesuatu carian kembali kosong.
• Carian dilog, tetapi tiada apa dimuatkan — kegagalan pengambilan yang tulen. Pergi ke langkah 2.
• Alat dimuatkan, yang salah digunakan — alat yang ditemuinya terlalu serupa. Pergi ke langkah 3.

2. Betulkan kegagalan pengambilan

search_tools memadankan nama, huraian dan nama argumen. Kegagalan hampir selalu bermakna huraian itu tidak mengandungi perkataan yang digunakan oleh ejen.

Tambahkan perkataan itu. Huraian ialah indeks pengambilan, jadi panjangkannya dan bukan memangkasnya — tulis perbendaharaan kata yang benar-benar akan ditaip oleh pengendali (“tetapkan”, “serahkan”, “berikan kepada”), bukan hanya kata nama dalaman. Memangkas huraian untuk menjimatkan token merugikan anda pada padanan carian dan ketepatan pemilihan sekali gus, dan hampir tidak menjimatkan apa-apa berbanding skema.

Jika alat yang betul wujud tetapi kedudukannya rendah, itulah tujuan argumen limit; huraian alat itu sendiri memberitahu ejen supaya meluaskan carian yang kelihatan hampir tetapi tersasar.

3. Betulkan alat yang kelihatan seiras

Jika dua alat mempunyai huraian yang akan dibaca sama oleh seseorang yang belum tahu bezanya, model itu sedang meneka. Cantumkan kedua-duanya menjadi satu alat dengan argumen yang membezakan.

ticket_relation dan ticket_pr_link mengikut pola ini: masing-masing mengendalikan pemautan dan penyahlautan melalui argumen yang membezakan. Pilihan yang dibuat di dalam satu panggilan, dengan konteks penuh permintaan itu, lebih boleh dipercayai daripada pilihan yang dibuat antara dua huraian yang kelihatan seiras.

Kekalkan alat sebagai berasingan apabila ia memerlukan pengawalan kelulusan, pengauditan atau pemaparan yang berbeza — itulah sebab penggabungan akan merugikan anda sesuatu yang nyata.

Pastikan cache prompt berfungsi

Kadar hit cache muncul dalam Kebolehcerapan → Wawasan sebagai Kadar cache. Perbualan panjang yang sihat berada pada kadar yang tinggi; jika ia sentiasa rendah, ada sesuatu yang menulis semula awalan pada setiap pusingan.

Punca biasa, mengikut susunan kebarangkalian:

• Apa-apa yang tidak deterministik pada awal prompt. Cap masa, id permintaan, atau set yang diulang dalam susunan yang berbeza-beza sudah cukup untuk melakukannya.
• Perubahan model atau usaha pada pertengahan perbualan. Kedua-duanya mengubah awalan. Subejen amat mudah tersalah di sini: menjalankan anak pada usaha yang lebih rendah untuk menjimatkan wang boleh menelan kos yang lebih tinggi daripada penjimatan melalui perkongsian cache yang hilang.
• Pemampatan yang kerap. Pemampatan menulis semula sejarah secara reka bentuk, jadi kosnya nyata; penyelesaiannya ialah memampatkan secara jarang dan mendalam, bukan kerap dan cetek.

Mematikan penundaan dengan --tool-deferral=off ialah ujian A/B yang sah untuk mengasingkan sama ada sesuatu perubahan tingkah laku datang daripada permukaan dua peringkat. Ia menghasilkan semula permintaan sebelum penundaan dengan tepat, jadi jika tingkah laku itu berterusan apabila ia dimatikan, permukaan itu bukan puncanya.