Blog Maguyva

Konteks yang mengembara bersama anda

Mon, 07 Sep 2026 00:00:00 GMT

Pengindeks Cursor sangat baik di dalam Cursor. Pelengkapan tab, penyuntingan sebaris, sembang, dan ejen dalam tetingkap itu sudah bersandar pada indeks projek yang dijalankan Cursor untuk ruang kerja yang dibuka. Jika Cursor ialah satu-satunya permukaan tempat anda menulis, dan indeks itu sudah menemui fail yang betul, kekallah di situ. Itu ialah kes jujur ‘kekal di tempat anda berada’, dan ia layak menjadi ayat pertama halaman ini.

Tulisan ini membincangkan separuh lain daripada minggu biasa. Repositori yang sama turut dibuka dalam Claude Code, disoal daripada Codex CLI, disemak pada mesin kedua, atau disoal oleh ejen yang berjalan dalam CI. Persoalannya bukan ‘pengindeks mana lebih baik’. Persoalannya ialah sama ada peta yang dipercayai ejen dalam satu tetingkap adalah peta yang sama yang dipercayainya dalam tetingkap seterusnya.

Maguyva ialah peta yang mengembara bersama anda itu. Ia adalah lapisan konteks pangkalan kod MCP jauh. Ejen menyoalnya dengan cara yang sama seperti ia menyoal mana-mana alat MCP lain. Hasil kembali sebagai laluan berperingkat dengan nombor baris. Cursor kekal sebagai editor. Konteks itulah yang bergerak.

Untuk apa pengindeks Cursor

Pengindeksan terbina dalam Cursor wujud supaya sembang, ejen dan carian di dalam editor boleh mengambil kod yang relevan berbanding hanya bergantung pada apa yang muat dalam tetingkap konteks mentah model. Itu reka bentuk yang betul untuk IDE. Indeks ini adalah asli kepada Cursor. Ia bukan pelayan MCP dan tidak boleh dicapai daripada klien lain.

Beginilah cara ia berfungsi, seperti yang diterangkan dalam dokumentasi awam Cursor dan penjelasan Cursor sendiri pada masa penulisan ini: laluan carian utama bukan lagi indeks embedding awan. Pasukan Cursor menyatakan di forum komuniti mereka bahawa carian semantik/berasaskan embedding khusus sedang dikurangkan demi mendapatkan semula berasaskan grep, kerana model masa kini sudah cukup baik meneroka pokok yang hidup dengan sendirinya. Sebagai gantinya ada Instant Grep, indeks carian tempatan yang dibina daripada n-gram, senarai terbalik dan penapis Bloom, disimpan dalam jadual carian yang dipetakan ke memori, supaya pertanyaan diselesaikan pada mesin pembangun sendiri berbanding pada pelayan.

Indeks itu sendiri hidup dalam direktori .git/cursor/ milik repositori sendiri, disauhkan pada commit git tertentu; perubahan sejak commit itu berlapis di atasnya berbanding mencetuskan imbasan baharu, dan indeks hanya dibina semula apabila keadaan tempatan telah menyimpang jauh daripada apa yang menjadi asas pembinaannya. Kerana ia terletak di dalam .git, ia tidak pernah dijejaki dan tidak pernah di-push — padam folder itu, dan indeks hilang. .gitignore dihormati kerana pembinaannya, kerana hanya kandungan yang dijejaki git layak, dan .cursorignore dikuatkuasakan pada laluan bacaan. Tiada lagi langkah embedding di sisi pelayan atau pangkalan data vektor jauh pada laluan itu. Dokumentasi terdahulu menerangkan reka bentuk berbantukan awan — penyulitan chunk, penyegerakan melalui pokok Merkle, penggunaan semula indeks antara ahli pasukan — dan pasukan Cursor sendiri sejak itu berkata reka bentuk itu sedang dikurangkan, jadi tulisan ini tidak lagi menerangkannya sebagai semasa.

Kekuatan yang menonjol di dalam editor ialah subejen Explore milik Cursor. Ia boleh melancarkan beberapa carian selari dalam tetingkap konteksnya sendiri pada model yang lebih pantas dan hanya mengembalikan penemuan yang relevan, supaya perbualan utama tidak membengkak dengan hasil carian. Itu kekuatan sebenar di dalam editor. Kekalkan ia.

Ruang kerja pelbagai punca disokong: konteks setiap folder yang dibuka tersedia untuk Agent. Sesetengah ciri bergantung git, seperti worktree, dilumpuhkan dalam persediaan pelbagai punca, dan Cloud Agents langsung tidak menyokong ruang kerja pelbagai punca.

Tiada satu pun daripada ini menjadi sebab untuk meninggalkan Cursor. Ia adalah penerangan tepat tentang peta yang sangat baik di tempat ia hidup.

Apa yang sebenarnya dimaksudkan ‘mengembara bersama anda’

Sesebuah peta mengembara bersama anda apabila soalan yang sama mengembalikan jenis jawapan yang sama, dengan petikan yang boleh anda buka, daripada lebih daripada satu klien.

Dalam Cursor: ‘Di manakah parseConfig ditakrifkan, dan siapa yang memanggilnya?’
Dalam Claude Code, pada repo yang sama: soalan yang sama.
Dalam Codex CLI, pada mesin semakan yang tidak pernah membuka tetingkap Cursor: soalan yang sama.
Dalam ejen CI yang bertutur MCP: soalan yang sama, terhadap snapshot yang dihoskan sama.

Jika setiap permukaan membina indeks persendiriannya sendiri, anda tidak mempunyai satu peta. Anda mempunyai beberapa cache yang semakin menyimpang. Indeks editor mungkin terkini untuk pokok di cakera. Sesi CLI mungkin ketinggalan sehari. Kerja CI mungkin melihat checkout yang berbeza. Dan ejen itu tetap akan kedengaran yakin.

Pengindeks Cursor tidak dimaksudkan untuk menyelesaikan itu. Kerana ia hidup di dalam editor, konteks yang dibinanya adalah untuk editor itu. Pembaca yang juga memerlukan CLI, saluran paip CI, atau editor yang berbeza memerlukan alat berasingan untuk permukaan tersebut. Itu fakta skop, bukan kecacatan. Maguyva ialah alat berasingan itu.

Bilangan bahasa yang diterbitkan untuk pengindeks Cursor tidak dinyatakan dalam bahan yang boleh digunakan tulisan ini. Maguyva menerbitkan sokongan untuk lebih daripada 279 bahasa dan teknologi berasaskan teks. Harga Cursor juga tidak disalin di sini; lihat halaman harga mereka. Maguyva mengenakan bayaran mengikut ruang kerja, bukan mengikut tempat duduk, dengan pelan yang diterbitkan pada $0, $19, $49 dan $149 bergantung pada liputan yang diindeks dan saiz ruang kerja.

Satu peta yang dihoskan, setiap klien MCP

Maguyva ialah pelayan MCP jauh. Anda menyambungkan GitHub, memilih repositori, dan saluran paip awan membina simbol, tepi graf dan peta berperingkat. Anda menambah kunci API pada konfigurasi MCP klien yang sudah anda gunakan. Maguyva mempunyai panduan persediaan untuk 24 klien MCP yang didokumenkan — termasuk Cursor — dan boleh berhubung dengan klien serasi MCP lain yang menyokong konfigurasi standard.

Halaman persediaan Cursor ialah laluan khusus editor jika di situlah anda bekerja. Pelayan yang sama menjawab Claude Code, VS Code, Windsurf, Codex CLI dan selebihnya. Anda tidak menukar editor. Anda memberikan setiap ejen permukaan alat yang sama: 11 alat MCP yang berorientasikan pelanggan merentasi carian, simbol, analisis kebergantungan, pengambilan fail, konteks repositori dan aliran kerja alat utiliti deterministik. Carian semantik, struktur, graf dan teks digabungkan menjadi hasil berperingkat.

Itulah manfaat kemudahalihan. Petikan yang anda semak dalam Cursor pagi ini mempunyai bentuk yang sama dengan petikan yang akan dikembalikan Codex CLI malam ini. Laluan fail dan nombor baris. Buka. Jika salah, anda akan melihatnya. Jika betul, perubahan seterusnya mempunyai tempat untuk mendarat. Dakwaan yang diluluskan ialah perubahan berhalusinasi yang lebih sedikit, bukan janji bahawa setiap perubahan adalah betul.

Kesegaran diterbitkan. Snapshot mempunyai cap masa, supaya ejen tahu versi pokok mana yang sedang dibacanya. Kadar pembinaan semula adalah harian pada pelan percuma dan setiap jam pada pelan berbayar. Batasan yang jujur ialah kerja tempatan yang tidak diselaraskan: perubahan yang hanya wujud dalam pokok kerja masih belum berada dalam peta yang dihoskan. Batasan ini adalah sama tidak kira klien mana anda gunakan untuk menyoal, dan itulah maksud sebenarnya. Hanyut antara klien bukan lagi batasan tersembunyi kedua.

Dokumentasi memberikan gelung pengaktifan yang terpakai untuk setiap klien: indeks repo yang sudah anda kenali, sambungkan klien, tanya satu soalan yang boleh anda sahkan. Lakukan itu sekali dalam Cursor. Lakukan lagi daripada CLI yang benar-benar anda gunakan pada hari semakan. Jika kedua-dua jawapan memetik pengendali yang sama, peta itu benar-benar telah mengembara bersama anda.

Bagaimana kedua-dua peta wujud bersebelahan

Gunakan kedua-duanya. Ia bukan alternatif dalam erti halaman perbandingan.

Kekalkan pengindeks Cursor dihidupkan untuk projek pada cakera. Biarkan Explore, Instant Grep dan ejen di dalam editor menggunakannya. Gelung itu adalah asli dan pantas.
Tambahkan Maguyva sebagai pelayan MCP dalam Cursor supaya sesi yang sama juga boleh menyoal peta ruang kerja yang dihoskan. Cursor ialah klien Maguyva yang didokumenkan. Anda tidak memilih satu indeks lalu memadam yang lain.
Tambahkan pelayan Maguyva yang sama kepada Claude Code, Codex CLI, atau mana-mana klien MCP lain yang menyentuh repo. Satu bentuk kunci API. Satu ruang kerja.
Jika ejen CI serasi MCP, arahkan ia ke pelayan yang sama. Ia akan membaca snapshot bercap masa yang sama seperti yang dibaca komputer riba.

Indeks editor kekal sebagai alat terbaik untuk ‘apa yang ada pada cakera dalam tetingkap ini, sekarang juga’. Peta yang dihoskan ialah alat terbaik untuk ‘bagaimana rupa ruang kerja ini bagi setiap ejen yang akan menyentuhnya hari ini’. Ayat-ayat itu tidak bersaing.

Kuota ruang kerja diterbitkan di halaman harga: repo, baris yang diindeks dan pengguna, dikenakan bayaran mengikut ruang kerja. Ejen dan manusia berkongsi bilangan pengguna yang sama. Mulakan secara percuma dengan repo yang sudah boleh anda nilai. Naikkan ruang kerja hanya selepas petikan bertahan daripada sentuhan dengan pokok itu.

Apa yang tidak didakwa halaman ini

Ia tidak mendakwa bahawa pengindeks Cursor lemah, tidak lengkap, atau sebab untuk menukar editor. Ayat pertama tulisan ini menyatakan sebaliknya.

Ia tidak mendakwa bahawa Maguyva menggantikan Instant Grep atau subejen Explore. Itu ciri-ciri Cursor. Ia kekal dalam Cursor.

Ia tidak mereka-reka bilangan bahasa, angka kependaman, atau penjimatan token untuk mana-mana produk. Angka yang tidak diketahui kekal tidak diterbitkan.

Ia tidak berpura-pura bahawa kerja tempatan yang belum di-push berada dalam peta yang dihoskan. Snapshot bercap masa menjadikan batasan itu kelihatan. Ia tidak menghapuskannya.

Ujian itu biasa sahaja. Indeks repo yang sudah anda kenali. Tanya satu soalan yang boleh anda sahkan, mula-mula dalam Cursor, kemudian dalam klien MCP kedua. Konteks yang mengembara bersama anda ialah petikan yang sama di kedua-dua tempat.

// same map, wherever you opened it.

Peta dahulu, semakan kemudian

Mon, 07 Sep 2026 00:00:00 GMT

Dua tugas berbeza berada di kedua-dua belah pull request. Sebelum ejen menulis, ia memerlukan peta pokok yang bakal diubahnya. Selepas ejen membuka PR, sesuatu perlu membaca perubahan itu berbanding selebihnya sistem dan meninggalkan komen yang boleh dijadikan tindakan oleh manusia.

Tugas-tugas ini kelihatan serupa dari jauh kerana kedua-duanya melibatkan ‘memahami pangkalan kod’. Ia bukan produk yang sama. Satu menjawab ‘di manakah perubahan ini sepatutnya mendarat?’. Satu lagi menjawab ‘apa yang dirosakkan diff ini yang akan terlepas pandang oleh linter baris demi baris?’. Mencampurkannya menghasilkan draf pertama yang lebih teruk dan semakan yang lebih bising.

Tulisan ini ialah panduan aliran kerja bersama. Maguyva ialah peta yang disoal ejen dahulu. Greptile ialah ejen semakan yang mengulas PR selepas itu. Pasangan ini saling melengkapi mengikut binaan: Maguyva tidak menyemak pull request, dan Greptile tidak menggantikan lapisan konteks yang digunakan ejen untuk menulisnya.

Kenapa pembahagian ini berguna

Ejen pengekodan yang bermula daripada prasyarat latihan ditambah beberapa fail yang ditampal akan mereka-reka laluan yang munasabah dan mengeditnya. Itu adalah kegagalan ‘fail yang salah’, dan ia adalah masalah pengambilan semula. Maguyva ialah lapisan konteks pangkalan kod MCP jauh: pengambilan semula semantik, struktur (AST), graf/kebergantungan dan teks digabungkan menjadi hasil berperingkat, ditambah carian simbol dan pengambilan fail. Jawapan yang berasas kembali sebagai path/file.ext:line, supaya anda boleh menolak kesilapan sebelum tampalan wujud. Dakwaan itu kekal sederhana: perubahan berhalusinasi yang lebih sedikit. Model masih boleh meneka. Cuma langkah pertama berhenti menjadi tekaan.

Greptile ialah ejen semakan kod berkuasa AI. Dengan kata-kata mereka sendiri, ia secara automatik menyemak setiap pull request dengan pemahaman penuh tentang pangkalan kod, dan meletakkannya bertentangan dengan linter tradisional yang menyemak fail secara berasingan berbanding keseluruhan sistem. Persediaan terdiri daripada memasang aplikasi GitHub atau GitLab dan memilih repositori. Tiada indeks tempatan yang perlu anda jalankan. Pengehosan ialah Greptile Cloud (mereka menyatakan pematuhan SOC 2 Type II, dengan laporan yang tersedia atas permintaan), dengan pilihan hos sendiri yang ditawarkan kepada perusahaan.

Aliran bernombor mereka sendiri ialah: sambung dan bina graf kebergantungan bagi setiap fungsi, kelas dan kebergantungan; pada setiap pull request, analisis perubahan menggunakan graf repo penuh itu dan terbitkan penemuan sebagai komen PR dengan pembetulan yang dicadangkan, dalam kira-kira tiga minit; setiap komen boleh menyerahkan isu kepada ejen pengekodan yang sudah digunakan pasukan. Mereka juga menyatakan membaca komen PR manusia terdahulu dari semasa ke semasa untuk mempelajari standard kod sesebuah pasukan dan mengurangkan cadangan yang bising. Sistem pembelajaran mereka, menurut mereka sendiri, memerlukan 2-3 minggu untuk menyesuaikan diri.

Itu adalah semakan, bukan penulisan draf. Kekuatan Greptile ialah konteks graf repo penuh terhadap perubahan yang sudah mendarat dalam PR, diikuti gelung tertutup yang menghantar penemuan itu ke Claude Code, Codex, Conductor, Cursor, atau Devin. Kekuatan Maguyva ialah peta berperingkat yang disoal ejen sebelum perubahan itu ditulis. Gunakan kedua-duanya. Jangan minta salah satu melakukan kerja yang lain.

Integrasi produk pihak pertama antara Maguyva dan Greptile tidak dinyatakan. Anda juga tidak memerlukannya. Maguyva bercakap dengan ejen melalui MCP. Greptile bercakap dengan GitHub atau GitLab melalui aplikasi mereka sendiri. Mereka bertemu di pull request. Tiada skrip pelekat, tiada cron yang menyalurkan satu alat ke alat yang lain. Pasangan ini tidak memerlukan bash kerana setiap produk sudah duduk pada permukaan yang menjadi miliknya.

Apa ini bukan

Ini bukan penghancuran Greptile. Ini bukan halaman ‘tukar penyemak anda’. Greptile dilancarkan di Hacker News pada 5 Mac 2024 sebagai syarikat Y Combinator W24, dan thread itu adalah cara ramai orang mula-mula mengenali produk ini. Jika begitulah caranya anda menemui mereka, teruskan menggunakan mereka. Halaman ini ialah separuh depan yang hilang daripada gelung itu: mensauhkan ejen terlebih dahulu supaya PR yang dilihat Greptile sudah menyasarkan fail yang betul.

Bahan pemasaran Greptile diketuai dengan dakwaan kelajuan semakan dan penangkapan pepijat. Anggap itu sebagai dakwaan Greptile sendiri, bukan angka yang disahkan secara bebas. Tulisan ini tidak mengulanginya sebagai fakta.

Liputan bahasa adalah kejujuran jenis yang sama. Greptile membingkai sokongan sebagai meliputi semua bahasa pengaturcaraan berbanding senarai yang disenaraikan; angka tepat tidak dinyatakan. Maguyva menerbitkan sokongan untuk lebih daripada 279 bahasa dan teknologi berasaskan teks, dengan pembahagian teknikal (AST disokong parser berbanding teks sahaja) di laman sesawang apabila soalannya teknikal. Ini adalah produk berbeza yang membuat dakwaan berbeza. Jangan campurkannya.

Harga Greptile tidak dinyatakan dalam bahan yang boleh digunakan tulisan ini. Pelan berbayar wujud; lihat halaman harga mereka. Maguyva mengenakan bayaran mengikut ruang kerja, bukan mengikut tempat duduk. Pelan bermula secara percuma. Halaman harga menyenaraikan peringkat yang diterbitkan jika anda memerlukan angka ruang kerja.

Aliran kerja

Tiga peringkat yang dinamakan. Laksanakan mengikut susunan ini. Jangan langkau mana-mana daripadanya pada kali pertama anda mencuba pasangan ini.

1. Konteks Maguyva

Indeks satu repositori yang sudah anda kenali. Sambungkan klien MCP tempat anda sudah menulis — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, atau klien serasi MCP lain. Maguyva mempunyai panduan persediaan untuk 24 klien MCP yang didokumenkan dan boleh berhubung dengan klien lain yang menyokong konfigurasi MCP standard.

Tanya satu soalan yang boleh anda nilai sebelum sesiapa menulis satu baris. ‘Di manakah tamat tempoh sesi dikendalikan, dan apa yang memanggilnya?’ adalah langkah pertama yang lebih baik daripada ‘betulkan auth’. Tuntut petikan. Buka hasil file.ext:line. Ikuti simbol itu. Sahkan kebergantungan yang bakal anda sentuh.

Maguyva mendedahkan 11 alat MCP yang berorientasikan pelanggan merentasi carian, simbol, analisis kebergantungan, pengambilan fail, konteks repositori dan aliran kerja alat utiliti deterministik. Empat mod pengambilan semula digabungkan menjadi hasil berperingkat; find_symbol ialah alat berasingan apabila anda sudah tahu namanya. Dokumentasi menerangkan laluan terpendek: mula secara percuma, indeks repo yang sudah anda kenali, sambungkan klien, kemudian tanya satu soalan yang boleh anda sahkan.

Snapshot mempunyai cap masa, supaya ejen boleh memberitahu versi pokok mana yang sedang dibacanya. Batasan yang jujur ialah kerja tempatan yang tidak diselaraskan. Jika perubahan hanya wujud dalam pokok kerja dan belum di-push, peta yang dihoskan masih belum mengandungi perubahan itu. Fail arahan (CLAUDE.md, AGENTS.md) masih mempunyai tempat di sini, untuk konvensyen dan apa yang tidak sepatutnya disentuh. Ia bukan peta yang hidup. Gunakan untuk tingkah laku. Gunakan Maguyva untuk fakta.

Jangan benarkan ejen membuka PR sebelum petikan bertahan sentuhan dengan repo. Pintu gerbang itu adalah keseluruhan tujuan peringkat ini.

2. PR ejen

Ejen yang sama kini menulis perubahan dalam klien yang sudah anda bayar. Maguyva bukan editor mahupun penyemak. Ejen masih menghasilkan diff. Anda masih membuka pull request pada GitHub atau GitLab sebagaimana yang sudah anda lakukan.

Apa yang sepatutnya berbeza ialah fail pertama. PR sepatutnya menamakan pengendali yang benar-benar melaksanakan tingkah laku itu, pemanggil yang akan rosak, dan ujian yang akan gagal jika perubahan itu salah. Jika peringkat 1 dilangkau, peringkat 3 akan membazir komennya pada perubahan yang mendarat di pakej yang salah. Greptile masih boleh menemui masalah sistemik. Ia tidak sepatutnya turut perlu pulih daripada laluan yang berhalusinasi.

Kekalkan PR terhad. Fail pertama yang berasas bukan lesen untuk menulis semula modul. Pasangan yang saling melengkapi ini berfungsi apabila ejen melakukan satu kerja dengan peta, kemudian meminta penyemak melakukan kerja lain pada diff yang terbatas.

3. Semakan Greptile

Greptile sudah bersambung dengan repositori melalui aplikasi GitHub atau GitLab. Pada pull request baharu, ia menganalisis perubahan menggunakan graf repo penuh yang dibinanya, dan menerbitkan penemuan sebagai komen dengan pembetulan yang dicadangkan. Bahan mereka sendiri meletakkan langkah ini pada kira-kira tiga minit.

Baca komen sebagaimana anda akan membaca rakan sepasukan yang teliti: buka lokasi yang dipetik, putuskan sama ada penemuan itu benar, kemudian bertindak. Di mana Greptile menawarkan ‘Fix with your Agent’, ia menghantar isu — laluan fail, nombor baris, kod yang dicadangkan — kepada Claude Code, Codex, Conductor, Cursor, atau Devin. ‘Fix All’ menghantar semua isu dalam semakan itu sekali gus. Mereka juga menyediakan Greptile MCP dan pemalam Claude Code untuk penyerahan itu. Maguyva tiada dalam senarai sasaran bernama itu; ketiadaan itu bukan masalah. Maguyva sudah melakukan kerjanya di peringkat 1. Ejen pengekodan yang menulis PR itu ialah pihak yang sepatutnya menerima muatan pembetulan.

Harapkan bunyi bising pada 2-3 minggu pertama sementara sistem pembelajaran Greptile menyesuaikan diri dengan komen yang benar-benar ditinggalkan pasukan anda. Itu jadual yang mereka nyatakan, bukan kecacatan pasangan itu. Semakan manusia kekal dalam gelung itu. Greptile ialah langkah pertama automatik, bukan butang gabung.

Jika komen Greptile menunjuk kepada fail yang tidak pernah disoal ejen di peringkat 1, itu isyarat yang berguna. Sama ada peta terlepas pandang seorang pemanggil, atau ejen melangkau satu petikan. Betulkan draf itu mengikut komen. Jangan lumpuhkan penyemak itu.

Cara mengekalkan pelengkap ini jujur

Maguyva sentiasa dahulu. Semakan PR dengan fail yang salah tetap sahaja semakan fail yang salah.
Greptile sentiasa selepas itu. Draf yang dipetik dengan baik masih memerlukan bacaan diff pada peringkat keseluruhan sistem.
Jangan minta Maguyva menerbitkan komen PR. Ia tidak melakukan itu.
Jangan minta Greptile menjadi lapisan pengambilan semula pertama ejen sementara ia masih memilih laluan. Itu bukan kerja yang direka untuk aplikasi GitHub atau GitLab mereka.
Jangan reka-reka saluran paip bash yang ‘menyegerakkan’ kedua-duanya. PR ialah antara muka itu.
Sahkan kedua-dua belah secara berasingan. Indeks repo yang sudah anda kenali. Tanya satu soalan yang boleh anda sahkan. Kemudian buka PR kecil dan baca apa yang sebenarnya dikomen Greptile.

Gelung itu menjadi biasa sebaik sahaja diberi nama. Peta dahulu. PR ejen. Semakan selepas itu. Setiap produk kekal pada sisi pull request yang menjadi kepakarannya.

// map first. review second. in that order.

Memberikan ejen AI konteks repo besar tanpa pengindeks tempatan

Fri, 14 Aug 2026 00:00:00 GMT

Repositori besar tidak muat dalam tetingkap konteks, dan jika anda pernah mengarahkan pengindeks komputer riba ke monorepo sebenar, anda tahu ia juga tidak muat dengan selesa di situ — RAM melonjak, pengindeksan pertama mengambil masa sejam, dan ejen anda tetap memulakan sesi seterusnya dengan meneka fail mana yang penting.

Jawapan biasa ialah menjalankan pengindeks di sebelah editor, dan untuk repo yang muat dengan selesa pada satu mesin, itu jawapan yang baik. Jika monorepo anda sudah diindeks dengan pantas dalam Cursor dan itu satu-satunya tempat anda memerlukan peta, tulisan ini tiada apa untuk ditambah — langkau sahaja.

Tulisan ini membincangkan kes lain — apabila ejen memerlukan peta repo besar yang boleh disoal, dan anda tidak mahu menjalankan pengindeks tempatan untuk mendapatkannya.

Bila pengindeks tempatan menjadi alat yang salah

Indeks tempatan mengandaikan kod itu hidup pada mesin yang menyoalnya, dan pada skala monorepo sebenar, andaian itu tertarik bahkan di dalam satu editor sahaja. Repo itu sekadar lebih besar daripada yang anda mahu kekal ‘panas’ pada komputer riba: anda bekerja dalam satu pakej sementara lingkungan impak berada tiga direktori jauhnya, dan pengindeksan sejuk pertama bagi pokok dua juta baris bukanlah sesuatu yang anda mahu lalui dua kali — sama ada pada mesin anda sendiri, atau pada pelari CI yang tidak pernah mengklon pokok itu sebelum ini. Atau seorang rakan sepasukan sepatutnya boleh menyoal peta yang sama seperti anda, tanpa menunggu mesin mereka sendiri berjuang melalui indeks yang sama.

Tiada satu pun daripada ini menjadi sebab untuk membuang pengindeks editor yang baik. Ia adalah sebab untuk turut memiliki peta yang dihoskan yang boleh disoal oleh mana-mana ejen anda melalui MCP.

Dan masalah skala itu lebih mendalam daripada ‘terlalu banyak fail untuk ditampal’. Pada pokok besar, soalan yang menarik hampir tidak pernah ‘tunjukkan saya fail ini’ — sebaliknya fail mana, simbol mana, siapa pemanggil, ujian mana. Ejen yang bermula dengan menyenaraikan src/ dan membaca tiga hasil pertama akan dengan gembira terlepas pengendali dalam apps/api dan klien yang dijana dalam packages/sdk. Apa yang anda perlukan ialah pengambilan yang dibina daripada keseluruhan pokok, kemudian diperingkat, kemudian dipetik.

Apa yang sebenarnya dimaksudkan ‘konteks repo besar’

Menumpahkan fail ke dalam prompt bukanlah konteks — ia adalah salinan pokok yang lebih kecil dan lebih teruk. Apa yang benar-benar diperlukan ejen anda ialah mengajukan soalan dan mendapatkan jawapan yang dipetik kembali: di mana simbol ini ditakrifkan dan siapa yang memanggilnya, apa yang bergantung pada modul yang saya akan ubah, fail ujian mana yang meliputi tingkah laku ini, dan bagaimana rupa pokok itu sekarang, bukan suku lepas.

Jawapan-jawapan itu mesti datang daripada indeks yang dibina daripada repo anda, bukan daripada ingatan model tentang repo orang lain, dan indeks itu mesti hidup di suatu tempat di luar tetingkap konteks ejen. Untuk masalah ini, ia juga sepatutnya hidup di suatu tempat di luar komputer riba anda.

Satu lagi perkara yang tidak dapat dilakukan fail arahan untuk anda: CLAUDE.md dan AGENTS.md ialah tempat yang betul untuk konvensyen dan tingkah laku, tetapi ia bukan peta yang hidup, berperingkat dan boleh disoal bagi pokok dua juta baris. Gunakan peraturan untuk tingkah laku; gunakan kepintaran repo untuk fakta.

Kami membina peta di awan, anda menyoalnya daripada mana-mana klien

Maguyva ialah lapisan konteks pangkalan kod MCP jauh. Anda menyambungkan GitHub, memilih repositori anda, dan boleh berlalu pergi sementara saluran paip awan menghurai pokok, membina simbol dan tepi graf, dan mengekalkan peta berperingkat — tidak pernah memerlukan pengindeks tempatan.

Apabila anda push kod, fail yang berubah dihurai secara berperingkat, dan lapisan graf serta pemeringkatan dibina semula mengikut jadual: harian pada pelan percuma, setiap jam pada pelan berbayar. Setiap snapshot mempunyai cap masa, supaya ejen anda boleh memberitahu versi pokok mana yang sedang dibacanya. Batasan jujur di sini ialah kerja tempatan yang tidak diselaraskan — perubahan yang hanya wujud dalam pokok kerja anda, tidak pernah di-push, masih belum berada dalam peta yang dihoskan.

Kemudian anda menyambungkan mana-mana klien yang sudah anda gunakan dengan menambah kunci API pada konfigurasi MCP-nya. Terdapat panduan persediaan untuk 24 klien MCP yang didokumenkan, dan mana-mana klien serasi MCP lain yang menyokong konfigurasi standard juga boleh berhubung. Jika Cursor ialah tempat anda tinggal, halaman Cursor menyusuri laluan itu; pelayan yang sama menjawab Claude Code, VS Code, Windsurf, Codex CLI dan selebihnya.

Anda tidak menukar editor. Anda memberikan ejen anda permukaan alat — 11 alat MCP merentasi carian, simbol, analisis kebergantungan, pengambilan fail dan konteks repositori — dengan liputan lebih daripada 279 bahasa dan teknologi berasaskan teks, yang bermaksud lebih daripada yang anda sangka pada monorepo yang sudah lama berhenti menjadi satu bahasa sahaja.

Jawapan kembali dengan asas yang kukuh, sebagai laluan fail dengan nombor baris. Carian semantik, struktur, graf dan teks digabungkan menjadi hasil berperingkat, supaya soalan seperti ‘apa yang bergantung pada parseConfig’ tidak memberi anda longgokan grep atau satu petikan semantik sahaja, tetapi segelintir tempat yang benar-benar penting.

Panduan konkrit

Jangan mulakan dengan mengindeks keseluruhan syarikat. Ini laluan yang berkesan:

Pilih satu repositori yang sudah anda kenali dengan baik — pakej yang boleh anda nilai secara manual lebih bernilai daripada pokok terbesar yang anda ada.
Mulakan secara percuma: 3 repo, 50 ribu baris diindeks, kesemua 11 alat, tiada kuota pertanyaan bulanan. Jika repo perwakilan anda lebih besar, halaman harga menyenaraikan peringkat ruang kerja ($0, $19, $49, $149) mengikut liputan yang diindeks — bukan mengikut bilangan tempat duduk.
Sambungkan GitHub dan tunggu pengindeksan pertama selesai. Anda tidak mengkompil apa-apa secara tempatan.
Sambungkan klien MCP — beberapa baris konfigurasi. Maguyva ialah pelayan MCP jauh, jadi tiada pemalam, tiada sambungan, dan tiada editor kedua untuk diguna pakai.
Tanya satu soalan yang boleh anda sahkan. ‘Apa yang bergantung pada parseConfig?’ atau ‘Di manakah tamat tempoh sesi log masuk dikendalikan?’ Kemudian buka hasil file.ext:line yang dipetik dan semak berbanding pokok di hadapan anda.
Hanya selepas petikan bertahan sentuhan itu, anda benarkan ejen mengedit.

Jika repo pertama sesuai dengan baik dan pokok anda besar, naikkan ruang kerja untuk sepadan dengan baris yang diindeks dan kadar pembinaan semula anda. Manusia dan ejen berkongsi bilangan pengguna yang sama — Maguyva mengenakan bayaran mengikut ruang kerja, bukan mengikut tempat duduk — jadi menambah ejen ketiga ke dalam gelung tidak membebankan anda apa-apa.

Ujian pengaktifan adalah sama seperti yang disyorkan dokumentasi untuk mana-mana larian pertama: indeks repo yang sudah anda kenali, tanya satu soalan yang boleh anda sahkan. Repo besar tidak mengubah ujian itu; ia hanya menjadikan fail pertama yang salah lebih mahal.

Apa yang perlu diperhatikan selepas disambungkan

Perhatikan tiga perkara. Kesegaran: pelan berbayar dibina semula setiap jam, pelan percuma setiap hari, dan kerja tempatan yang tidak di-push tidak akan berada dalam peta — itulah pertukaran yang anda terima. Skop: indeks set repo yang mewakili, bukan setiap fork yang diarkibkan; peringkat percuma sengaja disaiz untuk mengetahui sama ada jawapan berbaloi untuk dikekalkan. Dan pengesahan: peta repo besar yang tidak dapat memetik laluan dan nombor baris hanyalah enjin tekaan yang lebih perlahan, jadi jadikan ejen anda menunjukkan lokasi sebelum ia menghantar tampalan.

Kemudian jalankan ujian yang sama seperti yang akan anda jalankan pada repo kecil. Indeks repo yang sudah anda kenali. Tanya satu soalan yang boleh anda sahkan. Jika peta itu benar, ejen anda berhenti bermula daripada pokok sejuk.

// no laptop got hot building this map.

Kenapa ejen pengekodan AI anda berhalusinasi laluan fail

Fri, 14 Aug 2026 00:00:00 GMT

Tandanya bukan badan fungsi yang salah. Ia adalah perubahan yang yakin pada fail yang tidak wujud, atau pada fail yang wujud tetapi bukan fail yang melaksanakan tingkah laku itu.

Anda meminta pembetulan tamat tempoh sesi. Ejen membuka src/auth/session.ts. Laluan itu munasabah. Ia juga salah. Pengendali sebenar hidup dalam apps/api/src/middleware/expiry.ts, dinamakan semula dua penstrukturan semula yang lalu. Ejen itu tidak menipu anda. Ia melengkapkan rentetan berbentuk laluan berdasarkan prasyarat latihan ditambah apa sahaja yang sudah berada dalam tetingkap konteks.

Ini ialah corak kegagalan biasa pada repositori sebenar. Model boleh menulis kod. Kesilapannya ialah memilih tempat yang salah untuk menulisnya.

Kenapa ejen mereka-reka laluan

Ejen pengekodan ialah model ramalan token seterusnya yang dilengkapi alat. Apabila anda berkata ‘betulkan tamat tempoh sesi’, ia mesti menamakan satu fail sebelum ia boleh membaca atau menampal apa-apa. Jika ia belum mempunyai peta yang berasas, ia membina laluan daripada:

Konvensyen penamaan yang pernah dilihatnya dalam repositori lain. src/auth/session.ts adalah bentuk yang kerap.
Fail yang sudah berada dalam perbualan, yang mungkin adalah fail yang anda tampal minggu lepas, bukan yang penting sekarang.
Penyenaraian direktori yang secara kebetulan dijalankannya, tidak lengkap pada pokok yang besar.
Fail arahan. CLAUDE.md dan AGENTS.md memberitahu ejen cara berkelakuan. Ia bukan indeks hidup bagi simbol, pemanggil, atau laluan semasa.

Tiada satu pun sumber ini adalah peta repo ini, hari ini. Model itu mengisi jurang dengan cara yang sama ia mengisi mana-mana jurang: dengan kesinambungan berkebarangkalian tinggi. Kesinambungan itu selalunya kelihatan seperti laluan sebenar. Kadangkala fail itu wujud dan terletak di sebelah yang betul. Kadangkala ia wujud pada cabang yang digabungkan bulan lepas. Kadangkala ia tidak pernah wujud.

Grep tidak menyelamatkan anda di sini jika ejen langsung tidak mencari rentetan yang betul. Ejen meneka satu laluan, kemudian membaca apa yang dikembalikan laluan itu, kemudian mengeditnya. Langkah salah pertama ialah laluan itu, bukan tampalan itu.

Membaca fail juga bukan perkara yang sama dengan mencari yang betul. Claude Code, Cursor, Codex, dan alat serupa boleh membuka apa sahaja yang anda tunjukkan kepadanya. Persoalannya ialah sama ada mereka secara boleh dipercayai menemui fail yang betul, simbol yang penting, kebergantungan, ujian, dan lingkungan impak sebelum mengedit. Akses fail tanpa peta masih bermula dengan tekaan.

Mengedit fail yang salah adalah masalah pengambilan semula

Anggap laluan yang direka-reka itu sebagai kesilapan pengambilan semula, bukan kecacatan watak.

Jika ejen perlu mengembalikan path/file.ext:line sebelum ia dibenarkan mengedit, dua perkara akan berlaku. Pertama, anda boleh membuka petikan itu dan menolak kerja itu dalam sepuluh saat. Kedua, ejen perlu menyoal sesuatu yang benar-benar mengenali pokok itu.

Itulah kerja lapisan konteks pangkalan kod. Carian semantik sahaja tidak mencukupi. Petikan yang ‘kedengaran seperti tamat tempoh sesi’ masih boleh mendarat dalam pakej yang sudah luput. Anda juga memerlukan teks tepat apabila anda mengetahui rentetan itu, carian simbol apabila anda tahu namanya, carian struktur apabila anda tahu bentuknya, dan graf kebergantungan apabila anda memerlukan pemanggil dan lingkungan impak.

Maguyva ialah lapisan itu untuk ejen pengekodan yang serasi MCP. Ia bukan editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, dan klien MCP lain kekal di tempatnya. Ejen menyoal peta berperingkat sebelum menyentuh satu baris.

Dakwaan itu sengaja sederhana: perubahan berhalusinasi yang lebih sedikit. Maguyva tidak mengambil daripada model keupayaan untuk meneka. Ia mengubah langkah pertama lalai daripada ‘reka-reka laluan yang munasabah’ kepada ‘minta lokasi berperingkat, yang dipetik’.

Bagaimana rupa jawapan yang berasas

Jawapan yang berguna kepada ‘di manakah tamat tempoh sesi dikendalikan’ bukanlah satu perenggan. Ia adalah senarai lokasi yang ringkas:

apps/api/src/middleware/expiry.ts:48 - pengendali
apps/web/src/lib/auth-client.ts:112 - pemanggil
apps/api/tests/expiry.test.ts:20 - ujian yang akan gagal jika perubahan itu salah

Anda boleh membuka baris-baris ini. Jika salah, anda berhenti. Jika betul, ejen boleh mengedit. Pengesahan itulah intinya, bukan slogan.

Maguyva mendedahkan 11 alat MCP yang berorientasikan pelanggan merentasi carian, simbol, analisis kebergantungan, pengambilan fail, konteks repositori dan aliran kerja alat utiliti deterministik. Empat mod pengambilan semula (semantik, struktur, graf/kebergantungan, dan teks) digabungkan menjadi hasil berperingkat; carian simbol ialah alat MCP yang berasingan (find_symbol). Jawapan yang berasas kembali dengan laluan fail dan nombor baris, supaya anda boleh menilainya berbanding pokok di hadapan anda.

Dokumentasi menerangkan laluan terpendek: mula secara percuma, indeks repo yang sudah anda kenali, sambungkan klien, kemudian tanya satu soalan yang boleh anda sahkan.

Gelung yang mengubah perubahan pertama

Anda tidak memerlukan agama aliran kerja baharu. Anda memerlukan satu langkah tambahan sebelum tulisan pertama.

Tanya satu soalan yang sudah boleh anda nilai. ‘Kod mana yang mengendalikan log masuk dan tamat tempoh sesi?’ lebih baik daripada ‘betulkan auth’.
Tuntut petikan. Laluan fail dan nombor baris, bukan ringkasan ‘modul auth’.
Buka fail yang dipetik. Ikuti simbol itu. Sahkan kebergantungan yang bakal anda sentuh.
Hanya kemudian benarkan ejen menampal.

Jika langkah 2 tidak mengembalikan apa-apa yang berguna, ejen tiada hak untuk mengimprovisasi laluan. Ia mencari semula, atau anda menunjukkannya. Justeru satu pintu gerbang itulah yang menghasilkan perubahan berhalusinasi yang lebih sedikit. Model itu adalah model yang sama. Peta itulah yang berubah.

Fail arahan masih penting. Kekalkan ia. Gunakan untuk konvensyen, peraturan semakan, dan apa yang tidak sepatutnya disentuh. Jangan minta ia menjadi indeks. CLAUDE.md yang menyenaraikan tiga direktori penting akan lapuk seminggu selepas pembahagian pakej. Peta yang boleh disoal dikemas kini apabila repo dikemas kini.

Kegagalan yang berkaitan ialah fail yang hampir betul: ejen membuka auth.ts sedangkan tingkah laku hidup dalam auth-client.ts, atau menampal fail yang dijana berbanding sumber, atau mengedit salinan dalam packages/legacy kerana nama itu sepadan. Petikan tidak menjadikan kesilapan ini mustahil. Ia menjadikan kesilapan ini kelihatan sebelum diff itu mendarat.

Apa yang tidak akan dibetulkan peta untuk anda

Bersikap tenang tentang apa yang anda perolehi. Peta yang berasas tidak akan menjadikan setiap perubahan betul — ejen anda masih boleh menulis tampalan yang buruk tepat pada fail yang betul. Jika pangkalan kod anda bersandar pada dispatch dinamik, refleksi, atau monkey-patching, sesetengah carian simbol akan kembali lebih nipis daripada yang anda mahu, kerana itulah yang dilakukan ketaklangsungan masa jalan kepada mana-mana indeks statik. Dan jika anda mengharapkan peratusan — ‘laluan berhalusinasi berkurangan X%’ — anda tidak akan menemuinya di sini, kerana tiada sesiapa boleh mengukur angka itu secara jujur untuk repo anda selain diri anda sendiri.

Apa yang boleh anda jangkakan adalah lebih sempit dan lebih berguna: ejen berhenti memulakan perubahannya dengan laluan yang diteka. Langkah pertama itu menjadi berasas dalam peta sebenar, dan dari situlah datangnya perubahan berhalusinasi yang lebih sedikit. Segala-galanya selepas petikan itu — membaca diff, menilai tampalan itu — masih kerja anda, sebagaimana ia selalu berlaku.

Ujian ini hampir tidak membebankan anda apa-apa: indeks repo yang sudah anda kenali dan tanya satu soalan yang boleh anda sahkan. Mulakan dengan laluan yang pernah membakar anda. Jika petikan itu salah, anda akan melihatnya serta-merta. Jika betul, perubahan seterusnya ejen anda mempunyai tempat yang lebih baik untuk mendarat.

// it doesn't know the file. it knows how to find it.

Mengapa Kami Menaik Taraf Carian Kod kepada voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Angka penanda aras dalam penulisan ini mencerminkan leaderboard RTEB pada masa penerbitan (Jun 2026). Leaderboard berubah; anggap kedudukan itu sebagai satu cebisan masa, bukan fakta kekal.

Carian semantik hanya sebaik embeddings yang mendasarinya.

Apabila seorang ejen bertanya kepada Maguyva “di mana kita mengendalikan retry,” ia bukan sedang meng-grep perkataan “retry.” Ia sedang bertanya untuk makna — gelung backoff, circuit breaker, benda yang membalut panggilan yang tidak stabil. Soalan itu dijawab oleh satu model vektor yang mengubah kod menjadi satu titik dalam ruang dan mencari jirannya. Pilih model yang lebih baik dan setiap pertanyaan semantik dalam produk itu secara senyap menjadi lebih tajam.

Jadi kami menukar embeddings kami. Setakat Jun 2026, embeddings kod Maguyva berjalan pada voyage-4-large, menggantikan voyage-code-3.

Penanda Aras Itu

Kami tidak membuat keputusan ini berdasarkan perasaan semata-mata. Retrieval Embedding Benchmark (RTEB) yang bersifat awam menyusun kedudukan model embedding berdasarkan tugasan pengambilan sebenar, dan pada leaderboard Code miliknya voyage-4-large berada pada #1 keseluruhan (90.86) — mendahului gemini-embedding-2-preview (90.26) dan, yang lebih penting, mendahului model yang telah kami gunakan, voyage-code-3 (89.73, #3).

Itu adalah jurang mutlak yang kecil. Tetapi ia adalah jurang pada arah yang betul, pada satu penanda aras awam, pada tugasan tepat yang kami pedulikan: mengambil kod berdasarkan makna.

Kompromi Yang Kami Terima: Binary Quantization

Inilah bahagian yang biasanya ditinggalkan oleh kebanyakan penulisan jenis “kami menaik taraf model kami.”

Maguyva tidak menyimpan vektor kejituan penuh. Kami menyimpan embeddings yang binary-quantized: setiap vektor berdimensi 2048 dipadatkan menjadi satu signature 2048-bit — 256 byte setiap vektor. Signature itu dicari menggunakan jarak Hamming, diindeks dan dipartisikan mengikut tenant.

Itu ialah kompromi yang disengajakan. Binary quantization mengorbankan sedikit ketepatan pengambilan sebagai pertukaran untuk storan yang jauh lebih kecil dan matematik jarak yang pantas, murah, tanpa pangkalan data vektor berasingan untuk dikendalikan. Untuk sesuatu produk yang mengindeks keseluruhan repositori setiap workspace, ekonomi itu lebih penting daripada memerah pecahan terakhir sesuatu mata penanda aras.

voyage-4-large sesuai dengan reka bentuk ini tanpa memaksa migrasi lapisan storan: ia menghasilkan output berdimensi 2048, sama seperti voyage-code-3, jadi lajur bit(2048) kami dan laluan carian Hamming tidak berubah. Modelnya menjadi lebih baik; skemanya kekal sama.

Kod Hanyalah Permulaan

Maguyva adalah satu alat code-intelligence. Tetapi kami juga pengguna pertama produk kami sendiri (customer zero), dan kami menghalakannya kepada sesuatu yang lain: markdown yang hidup dalam repositori kami di sebelah kod. Rekod keputusan seni bina, runbook, kontrak, dokumen kewangan dan polisi — kesemuanya dikawal versi dalam Git, kesemuanya di sebalik MCP server yang sama, satu indeks semantik terhadap dokumen, bukan sekadar kod sumber.

Itulah tepat sebabnya keluasan voyage-4-large itu penting. Pada keluarga leaderboard RTEB yang sama ia berada pada #1 untuk kewangan, #1 untuk penjagaan kesihatan, dan #1 untuk pengambilan teks keseluruhan — mendahului Gemini Embedding milik Google, Embed v4 milik Cohere, dan text-embedding-3-large milik OpenAI. (Voyage adalah salah satu pencipta bersama RTEB, jadi kami membacanya sebagai satu isyarat awam yang kuat berbanding pengadil yang sepenuhnya neutral — tetapi ia dibandingkan bersemuka dengan setiap model komersial utama, pada set ujian berasingan yang tidak didedahkan kepada umum.) Indeks yang sama yang menemui fungsi yang tepat untuk seorang ejen turut menemui klausa yang tepat dalam sesuatu kontrak atau baris yang tepat dalam sesuatu polisi — dan pada domain-domain itu, voyage-4-large bukan satu kompromi, ia adalah peneraju.

Mengapa Kami Membayar Untuk Embeddings Premium

Terdapat cara yang lebih murah untuk melakukan carian, dan kebanyakannya percuma. Carian leksikal — BM25 dan seangkatan dengannya — memadankan kata kunci, berjalan secara setempat, dan tidak menelan sebarang kos. Model embedding sumber terbuka seperti BGE, Nomic, dan embeddinggemma memberikan capaian semantik yang sememangnya baik, dan anda boleh self-host ia dengan harga sebiji GPU. Maguyva turut menggunakan sisi percuma itu: setiap pertanyaan menggabungkan carian text, AST, graph, dan semantic. Bahagian yang tidak kami kurangkan kos sehingga menjejaskan kualiti ialah lapisan semantik.

Kami membayar setiap token untuk embeddings premium — voyage-4-large — dan bukannya menghoskan sendiri model percuma, atas dua sebab. Pertama, carian kata kunci sahaja tidak dapat menjawab “di mana kita mengendalikan retry” apabila kod itu menyebut backoff dan circuit breaker dan tidak pernah menyebut perkataan “retry” — makna adalah keseluruhan intipati embedding, dan pada domain yang kami khidmati model terbuka ketinggalan berbanding model premium: beberapa mata ketinggalan pada teks umum, dan lebih jauh ketinggalan dalam ceruk seperti kod, kontrak, dan kewangan. Kedua, dalam pengalaman kami kualiti pengambilan membentuk jawapan akhir lebih daripada model di hujung sana — seorang ejen yang kuat yang diberikan konteks yang salah masih menjawab dengan salah, dan ia tidak pernah melihat dokumen yang tidak pernah diberikan kepadanya.

Jadi embeddings premium adalah bil setiap token yang berskala dengan setiap repositori dan dokumen yang kami indeks — dan kami membayarnya dengan sengaja. Untuk hasil yang diperoleh pengguna kami, fungsi yang tepat atau klausa yang tepat, kami rasa kompromi itu berbaloi.

Bahagian Jujurnya

Dokumentasi Voyage sendiri masih melabelkan voyage-code-3 sebagai model yang dioptimumkan untuk kod. Jadi mengapa beralih?

Kerana kami membaca penanda aras awam, bukan sekadar jadual model vendor, dan penanda aras itu meletakkan voyage-4-large di atas untuk pengambilan kod. Ini adalah satu keputusan yang berpandangan jauh: ambil model yang lebih baharu, secara umumnya lebih kuat, dan sahkannya berbanding leaderboard awam pada tugasan yang penting. Kami selesa membuat pertaruhan itu kerana buktinya luas — voyage-4-large bukan sahaja menang pada kod, ia turut mendahului pada kewangan, penjagaan kesihatan, dan pengambilan keseluruhan.

Asas yang Tidak Kelihatan

Setiap tool yang kami dedahkan — carian semantik, pengumpulan konteks tugas, soal jawab berasaskan bukti — akhirnya bergantung kepada retrieval. Apabila retriever bertambah baik, ejen di hujung sana mendapat bukti yang lebih baik, melakukan lebih sedikit langkah yang salah, dan mengasaskan jawapannya pada kod yang tepat — atau klausa yang tepat, atau polisi yang tepat. Model embedding yang lebih tajam bukan satu ciri yang bergemerlapan. Ia ialah asas bagi segala-galanya yang lain, dan kami baru sahaja meninggikannya. Anda tidak akan perasan. Itulah intipatinya.

Penambahbaikan Kendiri Rekursif Bahasa: Menggilap Kecerdasan Kod Merentasi ~280 Bahasa

Tue, 26 May 2026 00:00:00 GMT

Angka dalam penulisan ini mencerminkan sistem pada masa penerbitan (Mei 2026). Lihat halaman pasukan kami untuk angka terkini.

Maguyva mengekstrak simbol, rujukan, dan graf kebergantungan daripada kod sumber dalam lebih kurang 280 bahasa. Setiap bahasa adalah handler tree-sitter tersuai — query, heuristik, kes pinggir — dan setiap handler boleh salah secara halus dengan caranya sendiri. Panggilan method dipancarkan sebagai bacaan. Fungsi diatributkan kepada skop pelingkung yang salah. Hubungan yang sebenarnya tidak wujud.

Anda tidak boleh mengauditnya secara manual. Tiada pasukan yang mampu membaca output pengekstrakan merentasi 280 grammar dan mengesan edge yang buruk. Jadi soalan yang menarik bukanlah “adakah pengekstrakan kami betul” — tetapi “bagaimana anda ketahui ia salah, pada skala seluas ini, tanpa manusia dalam setiap gelung.” Jawapan kami ialah penambahbaikan kendiri rekursif bahasa: gelung kualiti yang dipacu oleh ejen bahasa, LLM yang bertindak sebagai hakim, dan satu peraturan yang kami terus pelajari semula: hijau tidak sama dengan betul.

Hijau bukan bermakna betul

Setiap bahasa mempunyai suite fixture, dan gate pelepasan menilainya merentasi lima dimensi — ketepatan, integriti struktur, kelengkapan, kualiti, dan prestasi. Sesuatu bahasa menjadi GREEN hanya apabila, pada fixture-nya, precision ≥ 0.95, recall ≥ 0.99, dan F1 ≥ 0.97, dengan sekurang-kurangnya 20 edge yang dijangka untuk keyakinan statistik. Di bawah itu ia menjadi YELLOW atau RED, dan tidak dikeluarkan.

Gate itu perlu tetapi tidak mencukupi. Fixture mengesahkan terhadap fixture yang kami tulis sendiri. Ia mengekod kes-kes yang sudah kami fikirkan. Sesuatu handler boleh sempurna pada fixture-nya tetapi masih mengacau-balaukan corak yang hanya muncul dalam kod sebenar — satu idiom macro, method dengan kekangan pada jenis generik, satu ciri bahasa yang tiada siapa menulis fixture untuknya. GREEN bermaksud fixture lulus. Ia tidak bermaksud repositori sebenar diekstrak dengan bersih. Jadi gelung itu perlu meninggalkan fixture dan meneliti kod dalam penggunaan sebenar.

Gelung dalaman: semak sampel, nilai, baiki, buktikan

Gelung teras berjalan satu bahasa pada satu masa:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Beberapa perkara menjadikan ini berfungsi berbanding sekadar bergelut tanpa hala tuju.

Hakimnya adalah ejen itu sendiri, bukan panggilan API. Apabila kami berkata “LLM-sebagai-hakim,” maksud kami ejen bahasa itu sendiri membaca setiap edge yang disampel berbanding sumber sebenar dan mengklasifikasikannya dengan rubrik lima kategori yang tetap: adakah edge ini betul, positif palsu, hubungan yang betul dengan jenis yang salah, terikat pada skop yang salah, atau membawa metadata yang salah? Rubrik itulah asas penilaian ini — “kadar ralat 23%” tidak bermakna sehingga anda tahu sama ada itu kecacatan sebenar atau hakim tersalah kira.

Baiki satu perkara, kemudian buktikan. Setiap iterasi menukar tepat satu aset yang boleh disunting, kemudian menjalankan semula terhadap harness tetap dan mengekalkan perubahan itu hanya jika F1 bertambah baik dan pengklasifikasian semula kelihatan lebih baik. Jika tidak, ia dikembalikan. Tiada kelompok suntingan spekulatif, tiada “sepatutnya lebih baik.” Sesuatu perubahan mesti membuktikan haknya atau ia dibuang. Dan apabila sesuatu pembaikan kekal, ia dinaikkan taraf ke dalam suite fixture — supaya bug yang dibaikinya tidak dapat kembali secara senyap. Langkah kenaikan taraf itulah yang menjadikan gelung ini rekursif dan bukan sekadar berulang: setiap pusingan mengukuhkan rujukan pengesahan yang digunakan oleh pusingan seterusnya.

Pengajaran yang kami terus pelajari semula: metrik melebih-lebihkan laporan

Inilah perangkapnya, dan kami terus terjerumus ke dalamnya. Metrik korpus sekunder — kekerapan sasaran yang diekstrak tidak mempunyai simbol yang boleh diselesaikan, berapa banyak simbol kelihatan “yatim,” dan sebagainya — secara besar-besaran melebih-lebihkan masalah. Kebanyakannya adalah artifak paradigma, bukan bug.

Contoh paling jelas: llvm pernah menunjukkan kadar “sumber-tanpa-simbol” sebanyak 73% dan dicap sebagai bencana. Kami menyelidik lebih dalam. Ketepatan sebenar ialah 98.5%. “Simbol yang hilang” itu hampir kesemuanya rujukan luaran yang sah — panggilan ke pustaka piawai, ke framework, ke kod yang berada di luar repositori. Metrik itu mengukur sifat bahasa, bukan kecacatan dalam handler. Bahasa seperti Zig, COBOL, dan Odin menunjukkan kadar “yatim” sebanyak 65–70% dan sepenuhnya betul; COBOL tidak mempunyai sebarang ralat sebenar.

Jika kami membiarkan angka-angka itu memacu kerja ini, kami pasti menghabiskan berminggu-minggu “membaiki” handler yang sudah pun betul dan mengabaikan bahasa yang mempunyai bug sebenar yang senyap. Kesimpulannya tegas: metrik agregat sebaik-baiknya hanyalah isyarat triage yang kasar. Isyarat kualiti sebenar ialah semakan sampel dengan pengklasifikasian edge — melihat edge sebenar dalam repositori sebenar dan menilainya satu demi satu. Data mengatasi gerak hati, tetapi hanya sebaik sahaja anda tahu data mana yang bercakap benar.

Gelung luar: satu pasukan, bukan maraton

Satu bahasa pada satu masa akan mengambil masa yang tidak berkesudahan merentasi kesemua 280 bahasa itu, jadi gelung dalaman dibalut dalam satu gelung luar yang menjalankan banyak secara selari.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Setiap ejen bekerja dalam worktree pakai buang supaya mereka tidak dapat mengganggu satu sama lain. Orchestrator mengintegrasikan pembaikan mereka satu demi satu, setiap satu di sebalik semakan regresi manifest-penuh: perubahan yang membantu bahasanya sendiri tetapi secara senyap merosakkan tiga yang lain tidak akan digabungkan. Integrasi mesti lulus semakan dan disahkan sebelum sebarang perubahan dihantar ke repositori jauh — gate regresi menentukan apa yang selamat, manusia masih menentukan apa yang dikeluarkan. Kemudian kumpulan itu berputar ke set bahasa seterusnya dan keseluruhan proses berjalan semula.

Apa yang masih tidak sempurna

Hakim boleh tersilap, dan kesilapan itu mempunyai arah: ejen yang berjalan dengan konteks yang terlalu sedikit melebih-lebihkan laporan. Dalam satu kelompok, lapan bahasa ditandai pada ralat 5–20%; selepas pemeriksaan hanya satu bahasa yang mempunyai bug sebenar khusus bahasa — selebihnya adalah kesilapan hakim akibat terlepas pandang semantik bahasa itu sendiri (satu baris sumber secara sah memancarkan beberapa edge, ikatan parameter dimodelkan sebagai assignment, bahasa rujukan-per-pengecam). Itulah sebabnya kami mengambil sampel dengan dua seed dan menyilang semak, dan mengapa percanggahan antara hakim dan fixture dianggap sebagai isyarat yang paling menarik, bukan keputusan muktamad — kadangkala fixture itulah yang salah.

Kami juga jujur tentang sasaran itu. Matlamatnya ialah sifar ralat sebenar, tanpa kompromi — tetapi “sifar” adalah hala tuju yang kami usahakan secara berterusan, bahasa demi bahasa, bukan kotak yang ditanda. Sentiasa ada repositori lain dengan idiom lain.

Diperoleh, Bukan Didakwa

Segala yang Maguyva lakukan untuk seorang ejen — mencari simbol, menjejaki kebergantungan, menjawab soalan dengan rujukan kepada kod — bergantung pada ketepatan pengekstrakan yang mendasarinya. Merentasi 280 bahasa, “betul” tidak boleh didakwa sahaja; ia perlu diperoleh secara berterusan berbanding kod sebenar. Gelung ini adalah cara kami memperolehnya: kitaran semak-sampel-dan-baiki yang autonomi yang mencurigai metriknya sendiri, membuktikan setiap perubahan, dan mengubah setiap pembaikan menjadi pengawal terhadap regresi seterusnya. Ia tidak glamour. Ia adalah kerja yang membolehkan kami berkata “kami menyokong bahasa anda” dan memaksudkannya dengan sungguh-sungguh. Hijau itu mudah. Betul itu diperoleh.

Carian Fusion Pelbagai-Modal: Memilih Retriever Yang Tepat Untuk Setiap Pertanyaan

Wed, 15 Apr 2026 00:00:00 GMT

Nota reka bentuk terdahulu: artikel April 2026 ini menerangkan reka bentuk penghalaan pada waktu itu, bukan tingkah laku lalai semasa. Pembetulan September di bawah hanya menangani dakwaan pengukuran. Untuk penghalaan, pratetap dan kawalan modaliti eksplisit semasa, lihat Cara Ia Berfungsi.

Satu pertanyaan carian bukanlah satu perkara sahaja.

“di mana parseConfig ditakrifkan” mahukan simbol yang tepat — satu lokasi yang jitu, pantas. “bagaimana pengesahan (authentication) berfungsi” mahukan makna — sebaran kod berkaitan yang menerangkan sesuatu konsep. “apa yang akan rosak jika saya menukar fungsi ini” mahukan graf kebergantungan. “cari string ECONNREFUSED” mahukan padanan literal, tiada yang bijak-bijak.

Grep sangat baik untuk padanan literal dan berguna untuk sesetengah pemburuan rujukan, tetapi ia bukan graf kebergantungan dan ia tidak memahami makna. Embeddings merangkumi sisi semantik, tetapi ia adalah alat yang salah untuk string tepat dan analisis kesan. Kebanyakan alat carian kod memilih satu enjin dan memaksa setiap pertanyaan menggunakan enjin yang dipilih itu. Maguyva tidak terikat pada satu enjin. Ia mengetahui jenis soalan apa yang anda ajukan, kemudian menggabungkan empat retriever dalam nisbah yang sepatutnya untuk soalan itu.

Empat modaliti

Di sebalik tabir terdapat empat cara bebas untuk mencari kod:

semantic — carian vektor terhadap embeddings binari Voyage; mencari kod mengikut makna.
text — padanan trigram; mencari literal, string ralat, pengecam tepat.
structural — query AST; mencari takrifan, tandatangan (signature), dan konstruk bahasa.
graph — graf kebergantungan; mencari caller, callee, dan lingkungan impak.

Setiap satu kuat pada kelas soalan yang berbeza. Kuncinya ialah menentukan sejauh mana setiap satu patut dipercayai untuk pertanyaan yang ada di hadapan anda.

Pengklasifikasian niat

Sebelum sebarang pengambilan berjalan, satu classifier ringan menyusun pertanyaan itu ke dalam salah satu daripada enam niat, dengan skor keyakinan. Ia sengaja dibuat murah — heuristik tersusun, padanan pertama menang — kerana ia berjalan pada laluan panas (hot path) dan hanya menambah satu atau dua milisaat:

bermula dengan def , class , func , import … → find_definition (keyakinan 0.95)
“who calls” (siapa memanggil), “usages of” (penggunaan), “references to” (rujukan kepada) → find_references (0.90)
“impact” (kesan), “blast radius”, “what depends on” (apa yang bergantung pada) → impact_analysis (0.90)
"string" yang dipetik atau token ralat seperti traceback → exact_match (0.85–0.90)
satu pengecam CamelCase atau snake_case → find_definition (0.60–0.80)
“how” (bagaimana), “why” (mengapa), “explain” (terangkan), “architecture” (seni bina) → understand_code (0.75)
tiada yang sepadan → understand_code, keyakinan rendah (0.40)

Setiap niat membawa profil pemberat merentasi keempat-empat modaliti. Ini adalah angka sebenar:

Niat	semantic	text	structural (AST)	graph
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

Jadi “di mana parseConfig ditakrifkan” sangat bergantung pada AST (0.6). “bagaimana auth berfungsi” condong kepada vektor semantik (0.5). “apa yang bergantung kepada ini” hampir semuanya graf (0.7). “cari ECONNREFUSED” hampir semuanya trigram (0.9), dengan model embedding dimatikan sepenuhnya — kerana persamaan semantik adalah alat yang sama sekali tidak sesuai untuk string yang tepat.

Laluan pantas, dan laluan fusion

Apabila classifier itu yakin — skor ≥ 0.85 — dan pertanyaan itu adalah biasa, Maguyva melangkau fusion sepenuhnya dan menghalakan terus kepada satu modaliti dominan. “di mana X ditakrifkan” tidak memerlukan empat retriever; ia memerlukan indeks AST, sekarang. Laluan langsung itu dilaporkan semula sebagai fusion_strategy: "direct".

Segala yang kabur melalui fusion. Keempat-empat (atau tiga, pada preset lalai) modaliti berjalan secara selari, setiap satu memulangkan senarai hasilnya sendiri yang disusun mengikut kedudukan, dan kami menggabungkannya.

Reciprocal Rank Fusion Berpemberat

Menggabungkan retriever yang heterogen lebih sukar daripada yang kedengaran: persamaan kosinus 0.82 dan skor trigram 137 dan kesentralan graf 0.004 tidak berada pada skala yang sama, jadi anda tidak boleh sekadar menjumlahkannya. Reciprocal Rank Fusion mengelakkan masalah ini dengan membuang skor mentah dan hanya mengekalkan kedudukan (rank) yang diberikan oleh setiap enjin. Sumbangan sesuatu hasil daripada satu modaliti ialah:

contribution = weight × 1 / (k + rank + 1)

di mana rank adalah kedudukannya dalam senarai modaliti itu dan k adalah pemalar pelicinan (smoothing constant). Sumbangan dijumlahkan merentasi modaliti untuk sebarang hasil yang ditemui oleh lebih daripada satu enjin — persetujuan antara retriever secara semula jadi terapung ke atas. Kami menggunakan k = 40 pada preset lalai dan 60 pada thorough (quick berjalan semantik-sahaja, jadi fusion tidak pernah berlaku di situ). Kajian RRF asal mencapai k = 60 untuk pengambilan tujuan umum; kami menetapkan lalai yang sedikit lebih tajam, yang memberi persetujuan berkedudukan tinggi antara modaliti sedikit lebih banyak pemberat — dan kami tidak mengesyorkan penyelarasan manual.

Selain itu, hasil membawa satu boost kepentingan graf. Satu hub — fungsi yang menjadi sandaran keseluruhan pangkalan kod — sepatutnya mengatasi kedudukan nod daun yang kurang dikenali walaupun pada relevans tekstual yang sama, jadi kami mendarab setiap sumbangan dengan:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

Kesentralan datang daripada metrik PageRank/degree yang telah dikira lebih awal oleh pipeline, dan boost itu dihadkan pada 1.5× supaya sesuatu fungsi yang popular tidak boleh sepenuhnya mengubur fungsi yang kurang dikenali tetapi lebih relevan. Akhir sekali kami menurunkan taraf hasil daripada laluan vendor, build, dan arkib, dan dedupe kepada chunk terbaik bagi setiap fail.

Apa yang masih tidak sempurna

Pengelas niat ialah sekumpulan regex, bukan model terlatih. Ia mengendalikan bentuk pertanyaan lazim menggunakan heuristik, dan pertanyaan yang kabur kembali kepada understand_code serta gabungan yang condong kepada semantik. Versi terdahulu catatan ini menyatakan penurunan kadar carian tanpa hasil daripada sekitar 15% kepada bawah 5% sebagai peningkatan yang telah dicapai. Cadangan Disember 2025 sebenarnya menyenaraikan anggaran garis dasar dan sasaran; tiada set pertanyaan sokongan atau rekod pengukuran dibekalkan. Kami menarik balik dakwaan bahawa peningkatan itu telah dicapai; lihat bukti sumber dan pembetulan. Kami belum menggantikan pengelas dengan model terlatih kerana versi murah itu pantas dan cukup baik untuk peranan penghalaan yang dimaksudkan, dan kerana pengelas yang salah tetapi yakin lebih buruk daripada fallback yang jujur. Pemberat itu sendiri ialah prior yang dipilih secara manual, bukan dipelajari daripada data klik yang tidak kami kumpulkan.

Tanya Soalan Itu, Bukan Toolnya

Seorang ejen tidak sepatutnya perlu tahu sama ada hendak menggunakan grep atau embeddings atau graf panggilan — ia sepatutnya bertanya soalannya dalam istilah biasa dan mendapat jawapan yang betul. Fusion pelbagai-modal itulah yang membolehkan find_symbol, carian semantik, dan analisis kebergantungan berada di sebalik satu antara muka pertanyaan: sistem membaca bentuk soalan itu dan secara senyap menyusun retriever yang tepat untuknya. Model yang memberi skor kepada embeddings itu penting, tetapi begitu juga mengetahui bila tidak menggunakannya. Memilih tool yang tepat untuk setiap pertanyaan adalah satu jenis kualiti tersendiri, dan kami lebih rela memikul tanggungjawab itu daripada membebankannya kepada pemanggil.

// you bring the question. it brings the tools.

Observabiliti Ejen: Hooks, Alloy, dan Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Sistem ejen gagal dengan cara yang pelik.

Kadangkala model itu masalahnya. Kadangkala tool itu masalahnya. Kadangkala MCP server anda baik-baik sahaja, tetapi ejen memilih spesialis yang salah, atau menghabiskan separuh sesi melakukan kerja shell yang tidak anda jangkakan, atau secara senyap membazir kos dalam gelung yang kelihatan produktif dari luar.

Jika anda tidak dapat melihat perbezaannya, anda sebenarnya bukan mengendalikan sistem ejen. Anda sedang meneka.

Jadi kami membina stack observabiliti untuk aliran kerja kami sendiri: Claude Code, Codex, event hook Claude, event notify Codex, OpenTelemetry native, Grafana Alloy, dan Grafana Cloud di hujung yang satu lagi.

Bahagian yang menarik bukanlah “kami membina dashboard.” Bahagian yang menarik ialah kami terpaksa memecahkan telemetri kepada dua stream berbeza kerana tiada satu feed pun yang memberi kami gambaran keseluruhan.

Masalahnya: Telemetri Ejen Berpecah-belah

Ejen pengekodan moden sudah pun memancarkan sedikit telemetri. Itu membantu, tetapi tidak mencukupi.

OTEL native pandai menjawab soalan seperti:

Berapa banyak permintaan yang kami buat?
Berapa kos sesuatu sesi?
Di mana span dan trace berada?
Adakah kependaman melonjak?

Ia jauh lebih lemah dalam menjawab soalan seperti:

MCP server mana yang ejen bergantung kepadanya?
Adakah kegagalan ini berlaku dalam Bash, tool fail terbina-dalam, atau panggilan MCP?
Skill mana yang benar-benar diaktifkan?
Jenis subagent mana yang dihantar?
Adakah sesi itu melakukan kerja yang berguna, atau sekadar berpusing-pusing tanpa hala tuju?

Kelas soalan kedua itu lebih hampir kepada hooks berbanding trace.

Tetapi sebaliknya juga benar: sebahagian soalan prestasi yang paling penting lebih hampir kepada trace berbanding hooks.

Jika anda ingin tahu di mana kependaman sebenarnya terkumpul, span mana yang perlahan, atau sama ada sesi itu membazir masa dalam panggilan model berbanding pelaksanaan tool, anda memerlukan data trace selain event semantik.

Seni Bina Yang Akhirnya Kami Gunakan

Kami menjalankan dua laluan telemetri secara bersebelahan.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Pemisahan itu sengaja dilakukan.

Ia juga tidak simetri. Claude Code memberi kami antara muka hook kitar hayat yang jauh lebih kaya. Codex memberi kami OTEL native ditambah antara muka notify, jadi kami menormalkan event penyempurnaan giliran (turn-completion) dengan butiran yang lebih terhad kepada skema log yang sama, dan bukan berpura-pura kedua-dua runtime mendedahkan kawalan yang sama.

OTEL Native memberi kami stream garis dasar: log dan trace daripada runtime itu sendiri, ditambah metrik di mana runtime benar-benar memancarkannya.

Event hook dan notify memberi kami lapisan semantik: perkara seperti PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, dan metadata terklasifikasi yang benar-benar kami pedulikan semasa menyahpepijat gelagat ejen. Claude Code menyumbang stream event yang lebih kaya di sini. Codex menyumbang stream yang dinormalkan dengan butiran lebih terhad tetapi masih berguna.

Mengapa Hooks Diperlukan

Saluran paip hook kami memperkaya event sebelum ia sampai ke Loki.

Selain sekadar mengatakan “satu tool telah berjalan,” kami mengklasifikasikan event itu ke dalam medan seperti:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: backend MCP mana yang mengendalikan panggilan itu
bash_cli: keluarga arahan shell
subagent_type: jenis spesialis yang dihantar
agent_tool: sama ada sumbernya Claude Code atau Codex

Ini bermakna kami dapat bertanya soalan yang penting dari segi operasi:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Itu bukan medan hiasan semata-mata. Ia adalah perbezaan antara “ejen terasa perlahan” dengan “ejen menghabiskan sepuluh minit terakhir dalam operasi git yang sarat shell dengan kadar kegagalan tool yang tinggi.”

Satu butiran pelaksanaan yang kelihatan lebih pelik daripada sebenarnya: stream Loki kongsi masih menggunakan service_name="claude-code-hooks" sebagai label walaupun apabila event itu datang daripada Codex. Pemisahan sebenar antara runtime berlaku pada agent_tool.

Mengapa Alloy Berada Di Tengah

Grafana Alloy bukan sekadar forwarder dalam persediaan ini. Ia adalah sempadan polisi.

Kami mengarahkan stream OTEL native daripada Claude Code dan Codex ke proxy Alloy setempat pada localhost:4318, kemudian membenarkan Alloy membersihkan payload sebelum meneruskannya ke Grafana Cloud.

Itu penting kerana telemetri ejen yang mentah sarat dengan medan kardinaliti tinggi yang berguna untuk analisis tetapi teruk sebagai label yang diindeks:

session_id
prompt_id
kiraan token
tempoh
blob parameter tool

Jika anda mengindeks segala-galanya, anda akan mendapat letupan label dan hari yang teruk.

Jadi Alloy melakukan tiga perkara untuk kami:

Mengekalkan set label berkardinaliti rendah yang sangat kecil untuk diindeks.
Memindahkan medan yang bising tetapi berguna ke dalam metadata berstruktur.
Membuang sepenuhnya data yang tidak berguna.

Idea pentingnya mudah: perhatikan lebih banyak, indeks lebih sedikit.

Mengapa Stream Hook Memintas Alloy

Stream hook sudah dibentuk untuk Loki.

Pada masa send_event.py menghantar sesuatu event, kami sudah pun menentukan medan mana yang layak dilabel dan mana yang tergolong dalam badan JSON berstruktur. Stream itu terus ke gateway OTLP Grafana Cloud tanpa melalui satu lagi laluan menerusi Alloy.

Jadi sistem itu mempunyai pembahagian kerja yang jelas:

Alloy menjinakkan stream OTEL native yang mentah.
Pengayaan hook menjadikan event semantik boleh disoal (queryable).

Itu mengekalkan seni bina lebih ringkas berbanding cuba memaksa segala-galanya melalui satu laluan.

Apa Yang Dashboard Sebenarnya Tunjukkan

Tangkapan skrin di bawah diambil daripada salah satu dashboard observabiliti di sebalik aliran kerja ejen kami. Ia bukan penanda aras, dan angka-angka itu hanyalah cebisan pada satu-satu masa. Intinya ialah bentuk data itu: feed aktiviti, panggilan tool, kegagalan, prompt, dan pecahan mengikut ejen, tool terbina-dalam, penggunaan MCP, arahan shell, dan skill.

Bahagian yang berguna ialah dashboard ini berada pada stack Grafana yang sama dengan selebihnya telemetri ejen. Kami dapat menapis mengikut ejen sumber dan keluarga tool serta melihat merentasi runtime tanpa perlu mencipta cerita observabiliti yang berbeza untuk setiap sistem.

Salah satu dashboard langsung di sebalik aliran kerja ejen kami. Tangkapan skrin ini hanyalah satu cebisan daripada stack Grafana kongsi yang turut menerima telemetri daripada runtime dan sistem ejen kami yang lain. Klik imej untuk versi resolusi penuh.

Mengapa Trace Lebih Penting Daripada Yang Kelihatan Pada Mulanya

Log memberitahu kami kategori kerja apa yang berlaku. Trace memberitahu kami bagaimana kerja itu berlangsung mengikut urutan masa.

Perbezaan itu penting dalam sistem ejen kerana “perlahan” terlalu kabur untuk berguna.

Satu trace boleh memberitahu kami sama ada kesukaran itu datang daripada:

kependaman model
masa pelaksanaan tool
percubaan semula yang berulang
satu interaksi MCP yang amat mahal
ekor panjang operasi kecil yang kelihatan tidak berbahaya secara berasingan

Dalam praktiknya kami menggunakan stream hook dan trace Tempo bersama-sama.

Log hook menjawab: apa jenis perkara yang berlaku?
Trace menjawab: ke mana masa itu pergi?

Gabungan itulah yang mengubah observabiliti daripada sekadar dashboard kepada satu penjelasan.

Di Mana Codex Sesuai

Codex adalah sebahagian daripada stack yang sama, tetapi ia tidak sama seperti Claude Code.

Untuk Codex kami menyambungkan dua bahagian:

OTEL native daripada Codex ke Alloy
Webhook notify ke codex_notify.py, yang memetakan penyempurnaan giliran kepada skema Loki yang sama yang kami gunakan untuk event hook

Itu memberi kami penapis bersatu seperti agent_tool="codex-cli" di dalam stream log yang sama.

Peringatan jujur: payload notify Codex kini mengandungi butiran yang lebih terhad berbanding payload hook Claude Code kerana ia bukan jenis antara muka integrasi yang sama. Dalam persediaan kami hari ini, penyempurnaan giliran Codex boleh dinormalkan kepada skema kongsi, tetapi pengekstrakan tool demi tool yang kaya masih lebih baik dalam stream OTEL native berbanding dalam jambatan notify.

Itu bukan alasan untuk mengelakkan penulisan ini. Itulah sebenarnya intipati penulisan ini. Sistem observabiliti sebenar dibina daripada isyarat yang tidak sempurna.

Grafana Menerusi MCP Mengubah Segalanya

Peralihan yang lebih besar ialah Grafana bukan sekadar tempat manusia melawat dalam browser.

Dalam repositori ini kami turut mendedahkan Grafana menerusi MCP. Ini bermakna ejen dapat menyoal Loki, Prometheus, dan Tempo secara langsung dan bukannya menunggu manusia memeriksa dashboard secara manual terlebih dahulu.

Itu mengubah observabiliti menjadi input aktif kepada aliran kerja.

Ejen boleh bertanya:

Keluarga tool mana yang paling banyak gagal dalam sejam yang lepas?
MCP server mana yang mendominasi sesuatu sesi?
Adakah perubahan terkini mengurangkan kegagalan tool atau sekadar memindahkan kerja itu ke laluan yang lebih sarat shell dengan kesilapan yang sama?
Trace mana yang menunjukkan kependaman tertinggi atau percubaan semula yang berulang?

Sebaik sahaja anda mempunyai itu, anda sangat hampir kepada gelung penambahbaikan kendiri.

Daripada Dashboard Kepada Gelung Maklum Balas

Inilah bahagian yang kami dapati paling menarik.

Sebaik sahaja stack observabiliti boleh disoal daripada lapisan ejen, telemetri berhenti menjadi saluran pelaporan pasif dan menjadi isyarat kawalan.

Gelung itu kelihatan seperti ini:

Aktiviti ejen memancarkan trace, metrik, dan log hook yang diperkaya.
Grafana menyimpan bukti itu dalam Loki, Tempo, dan Prometheus di mana metrik wujud.
Ejen menyoal bukti itu menerusi Grafana MCP.
Sistem mengenal pasti campuran tool yang buruk, skill yang rapuh, penghalaan yang lemah, atau aliran kerja sarat shell yang terus menghasilkan kesilapan yang boleh dielakkan.
Ejen atau operator menyelaraskan prompt, config ejen, penerangan skill, peraturan penghalaan, atau akses tool.
Sesi seterusnya menghasilkan bentuk telemetri baharu, dan kitaran itu berulang.

Itulah caranya anda beralih daripada “dashboard yang menarik” kepada “sistem penambahbaikan yang boleh diukur.”

Matlamatnya bukan untuk memaksimumkan satu kategori tool. Ia adalah untuk mencapai campuran yang tepat antara CLI, tool terbina-dalam, panggilan MCP, dan skill untuk kerja yang benar-benar sedang dilakukan.

Apa Yang Ini Membolehkan Kami Jawab

Sebaik sahaja data kedua-dua runtime diterima oleh stack Grafana yang sama, kami dapat menjawab soalan operasi dengan jauh lebih pantas:

Adakah kegagalan tertumpu pada satu keluarga tool?
Adakah aliran kerja sarat shell mencipta kesilapan yang boleh dielakkan di mana sepatutnya wujud tool peringkat lebih tinggi?
MCP server mana yang menanggung beban kerja?
Adakah kami membayar untuk aktiviti ejen yang tidak menghasilkan kemajuan yang bermakna?
Adakah sesuatu sesi tidak sihat kerana model, tool, atau lapisan orkestrasi?

Ini amat berguna dalam aliran kerja pelbagai-ejen, di mana “ejen itu sibuk” hampir tidak memberitahu anda apa-apa.

Jika satu spesialis terus-menerus dihantar dan menghasilkan kadar kegagalan yang tinggi, itu adalah masalah penghalaan atau pembentukan prompt.

Jika satu MCP server mendominasi semua panggilan, itu mungkin seni bina yang baik atau tanda bahawa segala-galanya yang lain adalah beban yang tidak berguna.

Jika kegagalan tool melonjak sementara kos kekal tinggi, anda mempunyai masalah operasi, bukan masalah kualiti.

Jika kerja shell terus gagal dengan cara yang boleh dijangka dan boleh dielakkan di mana sepatutnya wujud tool peringkat lebih tinggi, itu adalah isyarat produk.

Jika satu skill sentiasa diaktifkan tetapi tidak meningkatkan hasil, itu adalah isyarat prompt atau penghalaan.

Pengajaran Sebenar

Pengajaran yang lebih mendalam di sini ialah observabiliti ejen memerlukan kedua-dua telemetri runtime dan telemetri aliran kerja.

Telemetri runtime memberitahu anda apa yang sistem lakukan.

Telemetri aliran kerja memberitahu anda apa yang ejen fikir ia sedang lakukan.

Kami memerlukan kedua-duanya.

Jika anda hanya menyimpan trace dan counter, anda terlepas lapisan semantik. Jika anda hanya menyimpan event hook, anda terlepas kependaman, span, dan gambaran runtime yang lebih luas.

Dan jika anda menyimpan kedua-duanya tetapi tidak pernah menyalurkannya semula ke lapisan ejen, anda hanya mempunyai pemantauan, bukan penyesuaian.

Gabungan itulah yang menjadikan sistem cukup boleh dijelaskan untuk dikendalikan dan cukup boleh diselaraskan untuk diperbaiki.

Apa Yang Masih Tidak Sempurna

Masih ada bahagian yang kasar.

Tidak setiap event hook merangkumi data tempoh dan token yang kami mahukan.
Sebahagian daripada paparan masa terbaik masih datang daripada trace Tempo, bukan log hook.
Codex hari ini kurang kaya secara semantik berbanding Claude Code dalam stream event yang diperkaya.
Tangkapan skrin dashboard menunjukkan paparan operasi langsung, bukan artifak pemasaran yang digilap.

Perkara terakhir itu adalah sengaja. Kami lebih suka menunjukkan panel instrumen sebenar berbanding berpura-pura sistem ejen secara ajaib menjelaskan diri sendiri.

Mengapa Ini Penting Untuk Maguyva

Maguyva adalah tentang memberi ejen kecerdasan kod yang lebih baik. Tetapi sebaik sahaja ejen benar-benar melakukan kerja yang berguna, satu keperluan baharu muncul serta-merta: anda perlu melihat bagaimana mereka berkelakuan.

Kualiti carian, kualiti penghalaan, pemilihan tool, dan kecekapan konteks semuanya menjadi masalah yang boleh diperhatikan.

Itulah sebabnya kami rasa ini berbaloi ditulis. Stack ejen masa depan bukan sekadar prompt dan tool. Ia adalah prompt, tool, dan lapisan instrumentasi yang memberitahu anda sama ada keseluruhannya berfungsi.

Jika anda membina aliran kerja ejen yang serius, observabiliti bukan infrastruktur pilihan. Ia adalah sebahagian daripada produk.

Mining Gelung: Bagaimana Perubahan Menjadi Memori Institusi

Tue, 03 Feb 2026 00:00:00 GMT

Angka dalam penulisan ini mencerminkan sistem pada masa penerbitan (Februari 2026). Lihat halaman pasukan kami untuk angka terkini.

Setiap pasukan kejuruteraan menghadapi cabaran yang sama: perubahan berlaku secara berterusan, tetapi sebab di sebalik perubahan itu hilang begitu sahaja. Enam bulan kemudian, seseorang bertanya “mengapa kita memilih untuk menggunakan DuckDB bagi stage pipeline?” dan jawapannya hanya wujud dalam kepala sesiapa yang membuat keputusan itu — jika mereka masih ada.

Kami membina aliran kerja mining yang menutup gelung ini. Perubahan mengalir melalui commit git, diproses oleh pipeline mining kami, menjadi entri changelog berstruktur dan rekod keputusan seni bina, kemudian disalurkan semula kepada ejen AI kami menerusi pertanyaan CLI. Hasilnya: memori institusi yang boleh dicapai oleh manusia dan AI.

Masalahnya: Keputusan Menguap Hilang

Pertimbangkan satu senario biasa. Seorang developer melakukan commit:

feat(canonical): add DuckDB runtime for pipeline stages

Commit ini mewakili satu pilihan seni bina yang signifikan. Pasukan itu menilai pilihan, mempertimbangkan trade-off, dan akhirnya memilih DuckDB atas sebab-sebab tertentu. Tetapi kesemua konteks itu hanya wujud dalam:

Satu thread Slack (kemungkinan besar telah dipadam)
Ingatan seseorang (pasti semakin pudar)
Satu komen dalam kod (mungkin, jika anda bertuah)

Tiga bulan kemudian, ahli pasukan baharu bertanya: “Patutkah saya guna DuckDB atau SQLite untuk stage baharu ini?” Tanpa memori institusi, mereka sama ada mencipta semula roda atau membuat pilihan yang tidak konsisten.

Gelung Itu: Daripada Commit Kepada Konteks

Aliran kerja mining kami mengubah sejarah git menjadi pengetahuan yang boleh disoal:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

Pandangan utamanya: kedua-dua changelog dan keputusan seni bina mengalir daripada sejarah git yang sama, diproses menerusi satu pipeline bersatu. Ini memastikan tiada apa-apa yang terlepas pandang.

Bagaimana Mining Berfungsi

Langkah 1: Segerakkan Indeks

uv run orkestra mine sync

Arahan ini mengimbas sejarah git dan membina satu indeks bagi semua commit. Ia mengekstrak isyarat berstruktur daripada setiap commit:

Jenis commit konvensional (feat, fix, chore, docs)
Scope (package atau kawasan yang mana)
Penanda breaking change
Fail yang disentuh dan metrik kerumitan

Langkah 2: Semak Status Liputan

uv run orkestra mine status

Berikut rupa status semasa kami:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15,637 commit diproses. 476 menjadi keputusan seni bina. 6,799 menjadi entri changelog. Setiap commit diklasifikasikan.

Langkah 3: Dapatkan Calon Untuk Semakan

uv run orkestra mine candidates --limit 50 --full

Ini memaparkan commit yang belum diproses lagi, dengan konteks penuh untuk pengklasifikasian:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Isyarat itu membantu membimbing pengklasifikasian: is_releasable_type: true mencadangkan ini patut muncul dalam changelog. Kiraan insertion yang besar dan fail infrastruktur mencadangkan ia mungkin juga satu keputusan seni bina.

Langkah 4: Klasifikasikan Commit

Dua laluan bercabang di sini: entri changelog dan keputusan seni bina.

Untuk entri changelog:

uv run orkestra mine classify abc123 --changelog added

Ini merekodkan bahawa commit abc123 patut muncul dalam changelog di bawah kategori “Added.”

Untuk keputusan seni bina:

Pertama, dapatkan ID keputusan yang sebenar:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Kemudian klasifikasikan dengan ID keputusan itu:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Ini memautkan commit itu kepada satu rekod keputusan yang akan dicipta atau dikemas kini.

Untuk pemprosesan kelompok (apa yang sebenarnya kami lakukan):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Format JSONL menyokong kedua-dua domain dalam satu pusingan:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Langkah 5: Render Output

uv run orkestra registry changelog render --package <pkg>

Ini menjana fail CHANGELOG.md setiap package daripada ledger. Changelog adalah artifak terbitan — padamkannya dan ia akan dijana semula dengan sempurna daripada ledger sumber.

Struktur Rekod Keputusan

Keputusan yang diekstrak menjadi fail YAML dengan metadata yang kaya:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Setiap keputusan memaut kembali kepada commit sumbernya. Setiap keputusan menentukan fail mana yang terlibat. Hubungan antara keputusan adalah eksplisit.

Integrasi CLI: Menyoal Memori Institusi

Di sinilah gelung itu ditutup. Ejen boleh menyoal keputusan menerusi CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Memulangkan keputusan tentang logik cuba semula, pengendalian ralat, corak pemulihan.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Memulangkan rekod keputusan yang lengkap dengan konteks, rasional, dan kesan.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Menunjukkan pilihan seni bina apa yang telah dibuat baru-baru ini.

Bagaimana Ejen Menggunakan Ini

Arahan garis dasar orchestrator kami merangkumi:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Apabila seorang ejen diminta untuk melaksanakan sesuatu yang berkaitan dengan DuckDB, ia boleh menyemak dahulu:

uv run orkestra registry decisions search --query "DuckDB"

Dan menemui DEC-PL-142, mempelajari:

Mengapa kami memilih DuckDB (context)
Bagaimana menggunakannya dengan betul (agent_guidance)
Fail apa yang perlu dilihat (files)
Keputusan berkaitan apa yang wujud (related)

Ejen itu tidak mencipta semula roda. Ia membina di atas corak yang telah ditetapkan.

Ujian Tiga Soalan

Bukan setiap commit layak mendapat rekod keputusan. Kami menggunakan Ujian Tiga Soalan untuk menapis:

Adakah ini sukar untuk dibuat? Adakah ia memerlukan analisis, penilaian trade-off, atau perdebatan yang signifikan?
Adakah ia mahal untuk diubah? Adakah membatalkan keputusan ini memerlukan kerja semula yang signifikan?
Adakah ia mempunyai kesan seluruh sistem? Adakah ia menjejaskan pelbagai package atau mewujudkan corak yang akan diikuti oleh yang lain?

Jika sesuatu commit menjawab “ya” kepada sekurang-kurangnya satu soalan ini, ia adalah calon untuk pengekstrakan keputusan. Kadar biasa kami: 1-4 keputusan bagi setiap 100 commit (kira-kira 1-4%).

Untuk entri changelog, kayu ukurnya lebih rendah: sebarang perubahan yang dilihat pengguna (ciri, pembaikan, penambahbaikan) direkodkan. Chore dalaman, kemas kini dokumentasi, dan refaktor lazimnya dilangkau. Kadar biasa kami: 30-50 entri changelog bagi setiap 100 commit.

Penyimpanan Data: Ledger Append-Only

Sistem mining menggunakan ledger JSONL append-only untuk operasi pelbagai-ejen yang bebas konflik:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Format JSONL dengan merge=union dalam .gitattributes bermakna pelbagai ejen boleh mengklasifikasikan commit secara serentak tanpa konflik merge. Setiap baris adalah bebas.

Gate Pengesahan

Sebelum sebarang sesi mining, kami menjalankan pengesahan:

uv run orkestra mine validate --quick

Ini menyemak:

Kesahihan format SHA
Pematuhan format ID keputusan
Tiada entri pendua untuk SHA yang sama
Keputusan yang dirujuk benar-benar wujud

Selepas pengklasifikasian, kami mengesahkan semula sebelum melakukan commit perubahan.

Mengapa Ini Penting

Gelung maklum balas yang kami bina menyelesaikan beberapa masalah:

Untuk ahli pasukan baharu: Daripada bertanya “mengapa kita buat X?”, mereka boleh mencari registri keputusan. Konteks itu terpelihara.

Untuk ejen AI: Mereka tidak beroperasi dalam ruang hampa. Mereka boleh menyoal pengetahuan institusi sebelum membuat cadangan. Apabila diminta menambah satu stage pipeline baharu, mereka boleh menemui corak DuckDB dan mengikutinya.

Untuk konsistensi seni bina: Keputusan bersifat eksplisit dan boleh dicari. Apabila seseorang mencadangkan pendekatan yang bercanggah dengan keputusan sedia ada, sistem boleh memaparkan konflik itu.

Untuk penjanaan changelog: Nota keluaran tidak lagi perlu disiapkan secara tergesa-gesa pada saat akhir. Ia adalah hasil sampingan daripada pengklasifikasian berterusan semasa pembangunan.

Untuk onboarding: Ejen baharu mewarisi konteks penuh pangkalan kod. Mereka bukan sahaja melihat kod — mereka melihat keputusan yang membentuknya.

Keadaan Semasa

Setakat hari ini:

15,637 commit diproses melalui pipeline
476 keputusan seni bina diekstrak dan didokumenkan
6,799 entri changelog direkodkan
Liputan 100% merentasi kedua-dua domain

Setiap commit sejak kami bermula telah diklasifikasikan. Memori institusi itu lengkap dan boleh disoal.

Bermula

Jika anda ingin melaksanakan sesuatu yang serupa:

Mulakan dengan commit konvensional. Pipeline mining berfungsi terbaik apabila commit mempunyai prefix berstruktur (feat:, fix:, chore:).
Takrifkan domain anda. Kami menggunakan domain seperti pipeline, agent-design, observability, data-modeling. Ini menyusun keputusan mengikut kawasan.
Bina tabiat pengklasifikasian. Mining berfungsi apabila pasukan kerap mengklasifikasikan commit. Pemprosesan kelompok dengan bantuan LLM membantu penskalaan.
Jadikan keputusan boleh disoal. Nilainya berganda apabila ejen boleh mencari keputusan menerusi CLI. Strukturkan output anda untuk penggunaan mesin.
Tutup gelung itu. Keputusan patut mempengaruhi kerja masa depan. Sertakan rujukan keputusan dalam arahan ejen dan senarai semak semakan kod.

Matlamatnya bukan dokumentasi yang sempurna. Ia adalah menjadikan sebab di sebalik perubahan boleh dicapai oleh manusia dan AI, hari ini dan enam bulan dari sekarang. Apabila perubahan menjadi memori institusi, pasukan membina di atas corak yang telah ditetapkan dan bukannya mencipta semula.

Aliran kerja mining adalah sebahagian daripada enjin orkestrasi kami, khususnya modul enjin konteks dalam package orkestrasi kami.

Skill Mining: Daripada 3,500 Calon Kepada 466 Keupayaan

Tue, 27 Jan 2026 00:00:00 GMT

Angka dalam penulisan ini mencerminkan sistem pada masa penerbitan (Januari 2026). Lihat halaman pasukan kami untuk angka terkini.

Masalah 3,500 Skill

Apabila kami mula membina satu sistem orkestrasi ejen, kami berhadapan dengan satu cabaran yang menarik: terdapat beribu-ribu bakal skill yang bertaburan merentasi ekosistem AI. Repositori GitHub, dokumentasi vendor, projek komuniti, corak dalaman - skill wujud di mana-mana. Tetapi yang mana penting? Yang mana berfungsi? Dan bagaimana anda menyenggara satu perpustakaan skill yang koheren yang benar-benar boleh digunakan oleh ejen?

Jawapan kami: satu gelung mining dan ingestion yang sistematik.

Angka Hari Ini

Lebih tiga bulan sedikit selepas Anthropic melancarkan Agent Skills pada 16 Oktober 2025, berikut kedudukan kami apabila penulisan ini diterbitkan pada 27 Januari 2026:

Metrik	Bilangan
Calon dikenal pasti	3,500+
Skill diterima pakai	466
Skill vendor	373
Skill dalaman	93
Vendor aktif	25+
Purata token setiap skill	2,834
Tool dirujuk	89
Tag unik	635

Kami telah menyemak lebih 3,500 calon skill. Kami telah menerima pakai 466. Itu adalah kadar penerimaan pakai 13% - dan keselektifan itu adalah sengaja.

Sistem Tier Pengetahuan

Bukan semua skill dicipta setara. Kami menyusunnya ke dalam lima lapisan pengetahuan (K0-K4), setiap satu mewakili skop kebolehterapan yang berbeza:

K0: Foundations (Universal)

Skill yang sepatutnya dimiliki oleh setiap ejen. Ini mewakili keupayaan “pemikir yang baik” yang berfungsi di mana-mana.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Skill K0 boleh dibawa ke mana-mana projek, mana-mana domain, mana-mana stack. Ia mengekod corak kognitif universal.

K1: Identities (Disiplin)

Skill “jurutera yang baik” atau “penyelidik yang baik” yang terpakai merentasi projek dalam sesuatu disiplin.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domains (Kepakaran Subjek)

Skill “pakar pangkalan data yang baik” atau “jurutera keselamatan yang baik” yang boleh dibawa dalam sesuatu bidang.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (Teknologi)

Skill “pengguna Supabase yang baik” atau “developer Cloudflare yang baik” untuk stack teknologi tertentu.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Project (Organisasi)

Skill khusus untuk organisasi dan aliran kerja kami.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

Gelung Mining

Fasa 1: Discovery

Skill datang dari mana-mana:

Repositori Vendor: AWS, Anthropic, Cloudflare, Supabase, dan penyumbang komuniti menerbitkan koleksi skill. Kami menjejaki 25+ root vendor.

Projek Komuniti: GitHub penuh dengan templat Claude Code, corak ejen, dan takrifan aliran kerja.

Corak Dalaman: Semasa pasukan kami menyelesaikan masalah, corak muncul. Ini diformalkan menjadi skill.

Perlombongan Dokumentasi: Dokumentasi teknikal selalunya mengandungi skill tersirat - prosedur, senarai semak, pokok keputusan.

Discovery adalah berterusan. Kami menggunakan backlog skill untuk menjejaki calon sebelum penilaian formal.

Fasa 2: Evaluation

Setiap calon melalui rubrik yang sama:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Kesemua lima kriteria produk mesti lulus. Inilah sebabnya 87% calon ditolak.

Kemudian setiap calon melalui satu semakan kepercayaan yang berasingan. Kami tidak menganggap repositori vendor rasmi, penyenggara komuniti yang terkenal, dan repositori GitHub rawak sebagai sumber kebenaran yang setara.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Vendor yang dipercayai mendapat semakan provenans yang lebih ringan, tetapi tetap perlu lulus semakan. Sumber yang tidak dipercayai atau tidak diketahui mendapat audit manual yang lebih mendalam, dan kami tidak melaksanakan skrip yang dibundel sehingga ia telah dibaca, diskop, dan diklasifikasikan sebagai selamat.

Analisis Jurang: Sebelum menerima pakai, kami mencari registri kami:

uv run orkestra skills search "<capability>"

Jika kami sudah mempunyainya, kami tidak memerlukannya. Jika kami mempunyai sesuatu yang hampir, kami mungkin merge dan bukan menerima pakai.

Skor Kedalaman dan Piawaian: Kami juga memberi skor kepada sejauh mana sesuatu calon menggunakan model agent-skill sepenuhnya. Satu SKILL.md yang bersendirian masih boleh berguna, tetapi skill yang lebih mendalam lebih bernilai apabila ia memisahkan arahan daripada rujukan, skrip, dan aset dengan cara yang digalakkan oleh agentskills.io.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Bintang GitHub boleh meningkatkan skor kredibiliti sedikit, tetapi ia tidak pernah menyelamatkan skill yang cetek atau tidak selamat. Satu repo berbintang tinggi dengan satu SKILL.md yang kabur dan skrip legap mendapat skor lebih rendah daripada satu repo yang lebih kecil dengan penerangan yang tepat, references/ yang dikurasi, dan helper atomik yang benar-benar memanfaatkan keupayaan skill sepenuhnya.

Analisis Struktur: Kami menyemak kualiti skill:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Jika sesuatu calon merangkumi skrip, semakan itu menjadi lebih ketat. Satu skill yang baik bukan sekadar berguna; ia mesti mudah difahami, mempunyai skop yang jelas, dan selamat untuk diserahkan kepada seorang ejen. Penapis keselamatan itu sahaja menyingkirkan sebahagian calon yang ketara yang sebenarnya menarik.

Fasa 3: Ingestion

Apabila sesuatu skill lulus penilaian, ia memasuki registri. Tetapi skill tidak pernah diterima pakai tanpa perubahan. Ia diubah suai supaya sesuai dengan sistem kami.

Pengubahsuaian Semasa Penerimaan Pakai:

Normalisasi Metadata: Setiap skill mendapat skema frontmatter kami
Penetapan K-Tier: Skill diletakkan dalam lapisan pengetahuan yang sesuai
Pengayaan Tag: Tag ditambah untuk discovery
Pengisytiharan Tool: Tool yang dibenarkan diisytiharkan secara eksplisit
Penjajaran Seksyen: Kandungan disusun semula untuk sepadan dengan templat kami

Satu YAML skill biasa selepas ingestion:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Fasa 4: Scope Assignment

Skill diberikan kepada scope - kategori yang menentukan ejen mana memuatkan skill mana:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Ejen mengisytiharkan scope mereka, dan skill diberikan secara automatik:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Fasa 5: Materialization

Skill tidak digunakan dalam bentuk YAML dalam persekitaran produksi. Ia dirender menjadi fail SKILL.md yang boleh dimuatkan oleh Claude Code:

uv run orkestra sync

Arahan ini:

Membaca semua takrifan YAML skill
Merendernya menerusi templat Jinja
Menulis fail SKILL.md ke .claude/skills/
Menyusun mengikut K-tier (foundations/, identities/, domains/, stacks/, project/)

Struktur output akhir:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Corak Scope Dorman

Salah satu corak kami yang paling berkuasa ialah skill “diterima pakai-tetapi-tidak-dimuatkan.” Kami memanggilnya dormant scope.

Pertimbangkan skill pengkomputeran saintifik daripada repositori k-dense-scientific. Kami telah menerima pakai 120+ skill merangkumi bioinformatik, kimia, pengkomputeran kuantum, dan informatik klinikal. Tetapi kebanyakan ejen kami tidak memerlukan molecular docking atau analisis ekspresi gen.

Daripada memuatkan kesemua 120 skill ke dalam setiap ejen (yang membazirkan tetingkap konteks), kami:

Menerima pakai skill itu dengan scope tertentu (contohnya, bioinformatics)
Mengekalkannya dorman - didaftarkan tetapi tidak dimuatkan
Mengaktifkannya hanya apabila seorang ejen mengisytiharkan scope itu

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Corak ini membolehkan kami mempunyai 466 skill dalam registri sementara ejen biasa hanya memuatkan 40-60 yang relevan.

Jenis Skill

Skill datang dalam tiga corak kognitif:

Workflow

Langkah prosedural tersusun: “1. Lakukan X, 2. Kemudian Y, 3. Akhirnya Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Discipline

Panduan kawalan gelagat: “Sentiasa X”, “Jangan sesekali Y”, “Utamakan Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist

Kriteria pengesahan: “Sahkan X”, “Verifikasi Y”, “Semak Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Gate Kualiti

Setiap skill mesti lulus pengesahan sebelum ia dikeluarkan:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Penerangan mesti 50-400 aksara dengan frasa pencetus (“Use when…”, “When you need…”) supaya Claude Code tahu bila hendak mencadangkannya.

Kami mengesahkan secara berterusan:

uv run orkestra validate --show-warnings

Ekosistem Vendor

373 skill vendor kami datang daripada:

Penyedia	Skill	Domain
AWS Agent	19	Perkhidmatan cloud
Anthropic	12	Penjanaan dokumen
Cloudflare	8	Pengkomputeran edge
Supabase	5	Pangkalan data
k-dense	100+	Pengkomputeran saintifik
silvainfm	4	Data science
Java Developer Kit	45+	Spring/Java
Vercel	1	Automasi browser

Setiap root vendor diisytiharkan dalam metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Apabila orkestra sync berjalan, skill vendor disymlink ke dalam .claude/skills/vendor/ dengan namespace penyedianya.

Apa Yang Kami Pelajari

Keselektifan berbaloi. Amat menggoda untuk menerima pakai segala-galanya yang kelihatan berguna. Tetapi setiap skill menelan kos token. Dengan purata 2,834 token setiap skill, konteks yang berlebihan cepat membebankan sistem. Kadar penerimaan pakai 13% kami mengekalkan konteks ejen yang ringkas.

Struktur membolehkan discovery. Sistem K-tier bukan sekadar penyusunan - ia tentang portabiliti. Skill K0 boleh digunakan semula di mana-mana. Skill K4 sengaja khusus projek. Kejelasan ini membantu manusia dan ejen mencari apa yang mereka perlukan.

Dormant scope membolehkan penskalaan. Anda boleh menerima pakai beratus-ratus skill tanpa memuatkannya semua. Scope membolehkan anda membina satu registri komprehensif sambil mengekalkan tetingkap konteks ejen individu boleh diurus.

Pengubahsuaian semasa penerimaan pakai adalah penting. Skill vendor mentah jarang sesuai dengan sistem anda. Proses ingestion - menambah metadata, memberikan tier, memperkaya tag - menjadikan skill luaran berfungsi secara dalaman.

Mining adalah berterusan. Angka 3,500 itu terus berkembang. Repo vendor baharu muncul. Corak komuniti terserlah. Aliran kerja dalaman menjadi mantap. Gelung ini tidak pernah berhenti.

Apa Seterusnya

Kami sedang mengusahakan beberapa penambahbaikan:

Pengesanan gap automatik: Memberi amaran apabila kegagalan ejen yang biasa boleh ditangani oleh satu skill yang belum diterima pakai
Aliran kerja deprecation skill: Proses formal untuk menghentikan penggunaan skill yang telah digantikan atau tidak digunakan
Kebergantungan silang-skill: Pengisytiharan eksplisit prasyarat skill
Analitik penggunaan: Menjejaki skill mana yang benar-benar dipanggil oleh ejen berbanding sekadar dimuatkan

Gelung skill mining adalah infrastruktur. Ia tidak glamour. Tetapi itulah yang menjadikan 41 ejen berfungsi secara koheren dengan 466 keupayaan sambil kekal dalam had konteks.

Itulah kisah bagaimana 3,500 menjadi 466. Bukan dengan mengabaikan 3,000 - tetapi dengan menilainya secara sistematik dan menerima pakai hanya apa yang berfungsi.

Mahu melihat sistem skill beraksi? Lihat uv run orkestra skills list untuk meneroka registri semasa kami.

Progressive Disclosure: Tetingkap CLI ke Dalam Sistem Ejen

Tue, 20 Jan 2026 00:00:00 GMT

Angka dalam penulisan ini mencerminkan sistem pada masa penerbitan (Januari 2026). Lihat halaman pasukan kami untuk angka terkini.

Sistem ejen bersifat legap mengikut reka bentuk. Ia membuat keputusan, memanggil tool, dan menyelaraskan kerja merentasi berpuluh-puluh spesialis. Tetapi apabila sesuatu tidak kena — atau apabila anda sekadar mahu memahami apa yang sedang berlaku — di manakah anda perlu lihat?

Jawapannya ialah progressive disclosure: satu antara muka berlapis yang mendedahkan tepat seberapa banyak kerumitan yang anda perlukan, tepat pada masa anda memerlukannya.

Masalah Kelegapan

Satu sistem orkestrasi ejen moden mungkin mempunyai:

40+ ejen spesialis, setiap satu dengan keupayaan berbeza
700+ skill merentasi automasi dalaman dan integrasi vendor
470+ keputusan seni bina yang membentuk gelagat
Berpuluh-puluh server tool MCP yang menyediakan keupayaan luaran

Kerumitan ini adalah sengaja. Ejen memerlukan akses kepada konteks yang kaya — pengetahuan domain, kecerdasan kod, skema pangkalan data — untuk membuat keputusan yang baik. Tetapi kekayaan yang sama itu mencipta satu masalah keterlihatan.

Bagaimana anda tahu ejen mana yang mengendalikan migrasi pangkalan data? Keputusan apa yang membentuk gelagat pemeringkatan sistem carian? Tool apa yang boleh dicapai oleh architecture advisor?

Tanpa akses berstruktur, anda terpaksa membaca kod sumber atau berharap dokumentasi itu terkini.

Progressive Disclosure sebagai Seni Bina

Progressive disclosure bukan sekadar corak UI. Ia adalah satu prinsip seni bina: menyusun maklumat dalam lapisan, setiap satu lebih mendalam daripada yang sebelumnya, supaya pengguna boleh berhenti pada tahap yang menjawab soalan mereka.

Untuk sistem ejen, ini diterjemahkan kepada arahan CLI pada kedalaman yang semakin meningkat:

Tahap	Arahan	Soalan Yang Dijawab
1	`orkestra system status`	Adakah segala-galanya sihat?
2	`orkestra agents list`	Ejen apa yang wujud?
3	`orkestra agents info <name>`	Apa yang dilakukan oleh ejen ini?
4	`orkestra decisions search`	Mengapa ia berfungsi sebegini?
5	Tool MCP Maguyva	Tunjukkan kod itu.

Setiap tahap menjawab satu soalan susulan yang semula jadi. Anda jarang perlu melompat terus ke tahap 5.

Tahap 1: Kesihatan Sistem

Soalan pertama sentiasa: adakah segala-galanya berfungsi?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Satu arahan. Empat angka. Cukup untuk mengetahui sistem itu telah dikonfigurasikan dan registri telah diisi.

Jika bilangan ejen jatuh secara tidak dijangka atau skill gagal dimuatkan, anda melihatnya di sini dahulu. Tiada keperluan menyelam ke dalam log.

Tahap 2: Inventori Ejen

Sebaik sahaja anda tahu sistem itu sihat, soalan seterusnya ialah: apa yang tersedia?

$ orkestra agents list

Ini memulangkan data berstruktur — nama ejen, penerangan, keutamaan model, liputan domain. Output itu adalah JSON secara lalai, memudahkan ia untuk di-pipe ke dalam jq untuk penapisan:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Mahukan ejen yang mengendalikan kerja pangkalan data? Arahan carian menyempitkan pencarian itu:

$ orkestra agents search "database"

Ini mengimbas nama, penerangan, dan keupayaan. Anda menemui spesialis yang tepat tanpa membaca 40 takrifan ejen.

Tahap 3: Kenali Ejen secara Mendalam

Menemui satu ejen yang kelihatan relevan? Arahan info mendedahkan segala-galanya:

$ orkestra agents info architecture-advisor

Output itu merangkumi:

Metadata: Nama, kategori, keutamaan model, penerangan
Domains: Kawasan pengetahuan mana yang diliputi oleh ejen ini
Identity: Sifat karakter (architect, strategist, knowledge-architect)
Panduan tool: Dokumentasi tool mana yang disuntik ke dalam konteks
Tools: Senarai penuh tool MCP yang boleh dicapai oleh ejen ini

Berikut satu sampel apa yang anda lihat:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Ini memberitahu anda dengan tepat apa yang boleh dilakukan oleh ejen itu. Tidak perlu membaca kod sumber.

Tahap 4: Arkeologi Keputusan

Ejen bergelagat mengikut keputusan yang didokumenkan. Apabila anda perlu memahami mengapa sesuatu berfungsi dengan cara tertentu, registri keputusan adalah sumber kebenaran.

$ orkestra decisions search "agent"

Ini memulangkan keputusan seni bina yang sepadan:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Setiap keputusan mempunyai provenans penuh — bila ia dibuat, mengapa, trade-off apa yang dipertimbangkan, commit mana yang melaksanakannya:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Ini adalah dokumentasi seni bina yang kekal terkini kerana ia di-mine daripada commit, bukan disenggara secara manual.

Tahap 5: Kecerdasan Kod Langsung

Apabila anda perlu melihat pelaksanaan sebenar — bukan metadata tentangnya — tool MCP Maguyva menyediakan akses langsung.

Dari dalam sesuatu sesi ejen:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Ini auto-menghalakan merentasi carian semantic, text, dan AST untuk mencari kod yang relevan. Untuk simbol khusus:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Untuk analisis kebergantungan:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Ini bukan sekadar pengganti grep. Ia memahami struktur graf (graph-aware), diindeks secara semantik, dan diintegrasikan dengan kecerdasan kod yang sama yang menggerakkan ejen itu sendiri.

Carian Bersatu Merentasi Registri

Kadangkala anda tidak tahu registri mana yang menyimpan jawapan itu. Carian bersatu merangkumi segala-galanya:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 padanan merentasi lima registri. Ringkasan itu memberitahu anda di mana untuk menyelam lebih dalam. Buang --summary untuk hasil terperinci, atau tambah --limit 5 untuk mengekalkan output yang boleh diurus.

Mengapa Ini Penting

Progressive disclosure bukan sekadar tentang kemudahan. Ia mengubah cara anda berinteraksi dengan sistem yang kompleks.

Penyahpepijatan menjadi terkawal. Apabila seorang ejen membuat keputusan yang tidak dijangka, anda tidak perlu grep menerusi log. Anda menyemak tool apa yang boleh dicapainya (agents info), keputusan apa yang membentuk gelagatnya (decisions search), dan menjejaki pelaksanaan jika perlu (intelligent_search).

Onboarding dipercepatkan. Ahli pasukan baharu tidak perlu membaca keseluruhan pangkalan kod. Mereka bermula dengan system status, meneroka dengan agents list, dan menyelam lebih dalam hanya apabila mereka bertembung dengan sesuatu yang mereka tidak faham.

Dokumentasi kekal terkini. Kerana CLI membaca daripada registri yang sama yang mengkonfigurasikan ejen, output itu sentiasa tepat. Tiada penyimpangan antara apa yang dikatakan oleh dokumentasi dan apa yang dilakukan oleh sistem.

CLI sebagai Antara Muka

Kami boleh sahaja membina satu dashboard web. Kami boleh sahaja menulis dokumentasi yang ekstensif. Sebaliknya, kami membina satu CLI yang membaca daripada sumber kebenaran.

CLI itu mempunyai kelebihan:

Boleh Digubah (Composable): Pipe output menerusi jq, integrasikan dengan skrip
Boleh Diskrip (Scriptable): Automasikan semakan, jana laporan
Pantas: Tiada pemuatan halaman, tiada aliran autentikasi
Tepat: Membaca konfigurasi sebenar, bukan representasi cache

Untuk sistem di mana ketepatan lebih penting daripada estetika, CLI menang.

Membina Progressive Disclosure Anda Sendiri

Jika anda sedang membina sistem ejen, pertimbangkan bagaimana pengguna akan memeriksanya:

Mulakan dengan semakan kesihatan. Satu arahan yang memberitahu anda sama ada perkara berfungsi.
Sediakan paparan inventori. Senaraikan apa yang wujud sebelum menerangkan apa yang ia lakukan.
Bolehkan pertanyaan bersasar. Carian mengatasi penyemakan imbas pada skala besar.
Dedahkan provenans. Benarkan pengguna menjejaki keputusan kembali kepada asal-usulnya.
Sambungkan kepada kecerdasan kod. Akhirnya, pengguna perlu melihat pelaksanaan.

Setiap lapisan menjawab satu soalan susulan. Bina ia mengikut urutan kekerapan — kebanyakan pengguna berhenti pada lapisan 2 atau 3. Hanya pengguna mahir yang mencapai lapisan 5.

Matlamatnya bukan untuk mendedahkan segala-galanya. Ia adalah untuk mendedahkan tepat apa yang diperlukan, tepat pada masa ia diperlukan. Itulah progressive disclosure yang diterapkan kepada seni bina ejen.

Ground Truths: Menambatkan Ejen AI kepada Realiti

Tue, 13 Jan 2026 00:00:00 GMT

Angka dalam penulisan ini mencerminkan sistem pada masa penerbitan (Januari 2026). Lihat halaman pasukan kami untuk angka terkini.

Ejen AI amat berkebolehan. Mereka boleh menaakul, mensintesis, dan menjana. Tetapi mereka mempunyai satu kelemahan asasi: mereka mereka-reka perkara. Bukan dengan niat jahat, tetapi dengan penuh keyakinan. Seorang ejen mungkin mencipta parameter API yang tidak wujud, merujuk konfigurasi yang tidak pernah ditakrifkan, atau menggunakan corak daripada data latihannya yang bercanggah dengan seni bina sebenar anda.

Mitigasi piawai ialah “beri ejen lebih banyak konteks.” Tetapi konteks boleh bercanggah. Dokumentasi menyimpang daripada pelaksanaan. Komen menipu. Malah kod pun boleh mengelirukan apabila dibaca tanpa memahami niat.

Kami memerlukan sesuatu yang lebih eksplisit. Sesuatu yang tidak boleh diabaikan atau disalahtafsir. Sesuatu yang dapat menambatkan ejen kepada realiti yang boleh disahkan.

Kami menamakannya Ground Truths.

Apakah itu Ground Truth?

Satu Ground Truth adalah pernyataan fakta yang eksplisit dan berversi yang mesti dihormati oleh ejen. Ia bukan dokumentasi. Ia bukan komen. Ia adalah entiti kelas pertama dalam sistem dengan:

Pengecam unik (seperti GT-MAG-015 atau GT-MAG-036)
Status kitar hayat (current, tentative, atau deprecated)
Skop (seluruh platform, khusus package, atau terikat domain)
Bukti (laluan fail, URL, atau rujukan yang membuktikan pernyataan itu)
Panduan ejen (arahan jelas tentang tindakan yang perlu dilakukan atau dielakkan)

Berikut contoh daripada platform kecerdasan kod Maguyva kami:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Ini bukan prosa. Ia adalah kontrak. Apabila seorang ejen bertemu dengan Ground Truth ini, ia tahu:

Lalai adalah deterministik (hasil kosong, bukan tekaan berasaskan padanan fuzzy)
Terdapat parameter khusus (find_similar, exact_match) dengan gelagat yang ditakrifkan
Bukti wujud dalam fail khusus yang boleh disahkan
Pernyataan itu telah disahkan pada tarikh tertentu

Anatomi Registri Ground Truth

Ground Truths hidup dalam registri YAML di bawah ai_assets/reference/ground_truths.yaml. Setiap package atau domain boleh mempunyai registrinya sendiri. Strukturnya ialah:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Registri itu merangkumi metadata tentang koleksi itu sendiri, konfigurasi render untuk penjanaan dokumentasi, dan pernyataan itu sendiri. Setiap pernyataan mengikuti skema ketat yang disahkan oleh model Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Cara Ejen Mengakses Ground Truths

Ground Truths didedahkan menerusi pelbagai saluran:

1. Dokumentasi Yang Dirender

Arahan orkestra sync mengubah registri YAML kepada markdown yang boleh dibaca:

uv run orkestra sync

Ini menjana fail GROUND_TRUTHS.md yang disertakan dalam konteks ejen. Output yang dirender mengumpulkan pernyataan mengikut status dan kategori:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Carian CLI

Ejen dengan akses shell boleh mencari Ground Truths secara programatik:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

Fungsi carian itu memberi skor kepada padanan merentasi pelbagai medan dengan relevans berpemberat:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Komposisi Konteks

Apabila ejen dirender daripada takrifan YAML, konteks mereka boleh merujuk registri Ground Truth:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Ini memastikan Ground Truths yang relevan dimuatkan sebelum ejen memulakan kerja.

Kategori Ground Truths

Melihat merentasi registri kami, Ground Truths berkumpul kepada beberapa corak:

Prinsip Produk

Kekangan tentang apa produk itu dan apa yang bukan:

“Maguyva bersifat baca-sahaja berhubung repositori pengguna; satu-satunya aset yang tidak boleh dibina semula ialah cache embeddings berbayar.” (GT-MAG-001)

Sempadan Seni Bina

Di mana tanggungjawab berada dan mengapa:

“Sempadan antara pipeline dan Maguyva adalah sengaja: pipeline boleh digunakan semula, Maguyva memegang logik khusus kod, dan CQRS memisahkan penulisan stage daripada bacaan server.” (GT-MAG-006)

Peraturan Anti-Halusinasi

Mandat eksplisit yang mengekalkan kontrak tool bersifat deterministik dan bukan diandaikan:

“Padanan simbol fuzzy adalah opt-in menerusi find_similar=true. Gelagat lalai memulangkan hasil kosong untuk simbol yang tidak wujud; exact_match=true menguatkuasakan padanan ketat dan melumpuhkan semua fallback fuzzy.” (GT-MAG-015)

Gate Kualiti

Piawaian yang mesti dikekalkan:

“Perubahan kepada infrastruktur kongsi (post_filters.py, relationship extractor, handler kongsi) MESTI disahkan terhadap SEMUA bahasa yang disokong menerusi penjanaan manifest penuh sebelum commit. Pengesahan satu bahasa sahaja tidak mencukupi untuk kod kongsi.” (GT-MAG-036)

Corak Kod

Keperluan pelaksanaan:

“Gunakan asyncio.to_thread() untuk kerja terikat-CPU dalam konteks async; corak loop.run_in_executor() yang deprecated tidak sepatutnya digunakan dalam kod baharu.” (GT-MAG-018)

Lifecycle Sesuatu Ground Truth

Ground Truths tidak statik. Ia berkembang menerusi lifecycle yang ditakrifkan:

Tentative

Satu kebenaran yang dicadangkan sedang dinilai. Pernyataan itu direkodkan tetapi mungkin berubah:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current

Satu kebenaran yang disahkan yang mesti dihormati oleh ejen. Bukti telah disahkan:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated

Satu kebenaran yang tidak lagi terpakai. Disimpan untuk rujukan sejarah dengan penunjuk kepada apa yang menggantikannya:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Mengapa Bukan Sekadar Dokumentasi?

Dokumentasi berkhidmat untuk tujuan yang berbeza. Ia menjelaskan. Ia mengajar. Ia boleh kabur, boleh menggunakan pengubah suai seperti “secara umum” atau “biasanya.”

Ground Truths tidak boleh kabur. Ia adalah dakwaan. Ia sama ada terpakai atau tidak.

Pertimbangkan perbezaannya:

Dokumentasi: “API secara umum memulangkan hasil kosong apabila simbol tidak dijumpai, walaupun padanan fuzzy mungkin diaktifkan dalam sesetengah konfigurasi.”

Ground Truth: “Gelagat lalai memulangkan hasil kosong untuk simbol yang tidak wujud; exact_match=true menguatkuasakan padanan ketat dan melumpuhkan semua fallback fuzzy.”

Yang pertama berguna untuk manusia yang sedang mempelajari sistem. Yang kedua boleh ditindaki oleh ejen yang membuat keputusan.

Panduan Ejen: Lakukan dan Elakkan

Sesetengah Ground Truths merangkumi panduan ejen yang eksplisit:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Ini menghapuskan kekaburan. Seorang ejen yang membaca ini tahu bukan sahaja apa yang benar, tetapi tindakan apa yang tersirat oleh kebenaran itu.

Pengesahan dan Penyenggaraan

Ground Truths memerlukan penyenggaraan. Kami menjejaki:

last_verified: Bila seseorang mengesahkan pernyataan itu masih terpakai
evidence: Fail yang membuktikan pernyataan itu (boleh disemak kewujudannya)
source: Dari mana kebenaran itu berasal (pemeriksaan CLI, semakan seni bina, pembelajaran pasca-insiden)

Sesuatu Ground Truth dengan tarikh pengesahan yang sudah lama atau pautan bukti yang rosak adalah isyarat untuk disiasat. Sama ada kebenaran itu masih sah dan memerlukan pengesahan semula, atau realiti telah berubah dan kebenaran itu memerlukan kemas kini.

Contoh Sebenar daripada Persekitaran Produksi

Sempadan Keselamatan

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Ground Truth ini menghalang satu kelas “penambahbaikan keselamatan” yang tersasar yang akan merosakkan produk.

Ketepatan pada Peringkat Pengekstrakan

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Ini datang daripada pengalaman yang menyakitkan. Ejen dahulunya menampal pek bahasa yang gagal dengan menambah penapis validator-sahaja yang menjadikan harness ujian kelihatan lebih hijau, sementara extractor Maguyva sebenar masih memancarkan edge yang salah. Peraturan itu memaksa pembaikan kembali ke laluan sebenar: config YAML, query, atau handler.

Penapisan Berbilang Tier

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Ini menghalang ejen daripada menambah penapis di tempat yang salah, satu kesilapan lazim yang menyebabkan regresi ketepatan.

Integrasi dengan Sistem Orkestrasi

Ground Truths adalah satu lapisan daripada sistem konteks yang lebih luas:

Keputusan Seni Bina (ADR) - Merekod mengapa kami memilih pendekatan A berbanding B
Ground Truths - Menyatakan apa yang secara muktamad benar sekarang
Corak Domain - Menerangkan cara melakukan sesuatu dengan betul
Anti-Corak - Menerangkan apa yang perlu dielakkan dan mengapa

Seorang ejen yang bekerja dalam sistem mempunyai akses kepada keempat-empat lapisan. Ground Truths menyediakan tambatan fakta, manakala keputusan menjelaskan sejarah, corak membimbing pelaksanaan, dan anti-corak memberi amaran tentang perangkap.

Mengukur Kesan

Sejak memperkenalkan Ground Truths, kami telah memerhatikan:

Kitaran “membaiki pembaikan yang berhalusinasi” yang lebih sedikit
Pembuatan keputusan ejen yang lebih yakin apabila fakta jelas
Semakan PR yang lebih baik kerana jangkaan bersifat eksplisit
Masa onboarding yang lebih singkat untuk ejen (dan manusia) baharu

Pelaburan dalam menyenggara Ground Truths berbaloi dengan penyahpepijatan yang berkurangan dan sempadan sistem yang lebih jelas.

Bermula

Untuk menambah satu Ground Truth ke sistem anda:

Cipta satu ground_truths.yaml dalam direktori ai_assets/reference/ package anda
Takrifkan metadata dan konfigurasi render
Tambah pernyataan mengikuti skema
Jalankan uv run orkestra sync untuk menjana dokumentasi
Sertakan registri itu dalam komposisi konteks ejen

Mulakan dengan fakta yang menyebabkan paling banyak kekeliruan atau kekangan yang paling kerap dilanggar. Itulah Ground Truths anda yang bernilai paling tinggi.

Kesimpulan

Ejen AI akan berhalusinasi. Itulah sifat semula jadinya. Tetapi kita boleh mencipta persekitaran di mana halusinasi dikekang, di mana fakta tertentu tidak boleh dipertikaikan, di mana ejen boleh menyemak andaian mereka berbanding realiti yang disahkan.

Ground Truths bukan penyelesaian yang lengkap. Ia memerlukan penyenggaraan. Faktanya boleh menjadi lapuk. Ia menambah overhead kepada proses pembangunan.

Tetapi ia menyediakan sesuatu yang bernilai: perbendaharaan kata fakta yang dikongsi yang dipercayai oleh manusia dan ejen. Dalam dunia di mana ejen semakin banyak mengambil bahagian dalam pembangunan perisian, asas kongsi itu menjadi penting.

Alternatifnya ialah kitaran tanpa henti ejen membuat kesilapan dengan penuh keyakinan dan manusia membetulkannya. Ground Truths memutuskan kitaran itu dengan menjadikan pembetulan itu eksplisit dan berkekalan.

Ejen anda berhak untuk tahu apa yang benar. Beritahu mereka.

Orkestra: Mengorkestrasi Ejen AI Pada Skala Besar

Tue, 06 Jan 2026 00:00:00 GMT

Angka dalam penulisan ini mencerminkan sistem pada masa penerbitan (Januari 2026). Lihat halaman pasukan kami untuk angka terkini.

Apabila kami mula membina dengan Claude Code, kami bertembung dengan satu masalah yang akhirnya dihadapi oleh setiap pasukan yang menggunakan pembantu pengekodan AI: satu ejen sahaja tidak dapat melakukan segala-galanya dengan baik.

Anda boleh meminta ejen menjadi pakar pangkalan data. Atau juruaudit keselamatan. Atau jurutera frontend. Tetapi sebaik sahaja anda memintanya menjadi ketiga-tiganya serentak, kualiti terjejas. Konteks menjadi cair. Arahan bercanggah. Ejen itu menjadi generalis yang sederhana dalam segala-galanya.

Jadi kami membina Orkestra.

Apakah itu Orkestra?

Orkestra adalah sistem orkestrasi ejen untuk Claude Code dan alatan pengekodan AI yang serupa. Ia menyelaraskan pelbagai ejen khusus, setiap satu dengan kepakaran yang berbeza, di bawah satu orchestrator yang menghalakan kerja kepada spesialis yang tepat.

Bayangkannya sebagai satu agensi pengambilan kakitangan untuk ejen AI. Orchestrator itu menerima satu tugas, mengenal pasti spesialis mana yang patut mengendalikannya, dan mewakilkan tugas itu dengan konteks yang tepat. Apabila kerja itu selesai, hasilnya mengalir semula kepada orchestrator untuk disintesis.

Angka-angka itu menceritakan kisahnya:

Komponen	Bilangan
Ejen spesialis	46
Skill boleh guna semula	466
Arketaip identiti	27
Mindset	11
Gaya komunikasi	10
Domain pengetahuan	21

Sistem Karakter: D&D untuk Ejen

Pandangan teras di sebalik Orkestra ialah gelagat ejen muncul daripada tiga primitif yang boleh digubah bersama:

Identity mentakrifkan apa ejen itu. Seorang architect mereka bentuk struktur sistem. Seorang debugger menjejaki kegagalan kepada punca akarnya. Seorang guardian menguatkuasakan pematuhan dan sempadan keselamatan. Kami mempunyai 27 arketaip identiti yang boleh dicampur.

Mindset mentakrifkan bagaimana ejen berfikir. Satu mindset analytical mengasaskan dakwaan pada bukti dan mengkuantifikasikan ketidakpastian. Satu mindset skeptical mempersoalkan andaian dan mencari bukti yang menyangkal. Satu mindset exploratory merangkul kekaburan dan mencuba pelbagai pendekatan.

Style mentakrifkan bagaimana ejen berkomunikasi. Satu style technical merangkumi nilai tepat dan merujuk fail khusus. Satu style concise membuang bahasa berbunga dan memulakan dengan jawapan. Satu style diplomatic mengimbangi kejujuran dengan kebijaksanaan berkomunikasi.

Seorang ejen menggabungkan primitif-primitif ini:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Komposisi ini mencipta seorang ejen yang mereka bentuk sistem (architect), menghubungkan pengetahuan merentasi domain (knowledge-architect), menetapkan hala tuju strategik (strategist), berfikir menerusi bukti dan data (analytical), dan berkomunikasi tanpa bahasa berbunga (concise).

Kekuatannya terletak pada letupan gabungan (combinatorial explosion). 27 identity darab 11 mindset darab 10 style menghasilkan hampir 3,000 personaliti ejen yang mungkin. Tetapi anda hanya mentakrifkan gabungan yang penting untuk kerja anda.

Skill: Modul Keupayaan Boleh Guna Semula

Skill adalah pengetahuan dan aliran kerja yang boleh dipanggil oleh ejen. Ia mengikuti satu sistem bertingkat berasaskan skop:

Tier	Nama	Skop	Contoh
K0	Foundations	Metodologi universal	Disiplin test-first, penyempurnaan berasaskan bukti
K1	Identities	Aliran kerja berasaskan peranan	Piawaian antara muka CLI, playbook prestasi
K2	Domains	Pengetahuan khusus domain	Corak migrasi pangkalan data, pengesahan aliran autentikasi (authentication)
K3	Stacks	Khusus teknologi	Deployment Cloudflare, operasi Supabase
K4	Project	Pangkalan kod ini sahaja	Aliran kerja dan konvensyen khusus projek

Skill dimuatkan secara lazy-loaded. Seorang ejen melihat nama dan penerangan skill semasa permulaan, tetapi kandungan skill penuh hanya dimuatkan apabila dicetuskan. Ini mengekalkan konteks ramping sambil menjadikan beratus-ratus skill boleh ditemui.

Setiap skill merangkumi:

Syarat pencetus yang jelas (“Gunakan apabila memigrasi skema pangkalan data”)
Panduan langkah demi langkah
Tool yang dibenarkan untuk aliran kerja itu
Kriteria kejayaan dan laluan pemulihan kegagalan

466 skill dalam registri kami merangkumi segala-galanya daripada pengasingan git worktree kepada aliran kerja penyelidikan web kepada pengesahan kesihatan deployment.

Mengapa Orkestrasi Penting

Seni bina ejen tunggal cepat bertembung dengan dinding:

Pencairan konteks. Tetingkap konteks 200k token kedengaran besar sehinggalah anda memuatkan skema pangkalan data, dokumentasi API, fixture ujian, dan pengetahuan domain. Spesialis boleh bekerja dengan konteks yang bersasar.

Percanggahan arahan. Memberitahu seorang ejen untuk “teliti tetapi pantas” dan “sahkan segala-galanya tetapi jangan over-engineer” mencipta ketegangan. Spesialis menyelesaikan ini dengan mempunyai skop yang jelas.

Kedalaman kepakaran. Seorang ejen generalis tahu sedikit tentang segala-galanya. Seorang ejen spesialis, digubah dengan identity dan skill yang tepat, mengetahui domainnya secara mendalam.

Orkestra melaksanakan orkestrasi rata (flat orchestration): satu orchestrator menyelaraskan pelbagai spesialis. Spesialis tidak boleh mencipta sub-spesialis. Ini menghalang letupan kerumitan sambil membolehkan kerja selari.

Orchestrator itu mempunyai akses kepada 2.2 juta token kapasiti efektif: tetingkapnya sendiri 200k ditambah 10 subagent serentak dengan 200k setiap satu. Kerja yang akan menghabiskan satu ejen sahaja berjalan dengan selesa merentasi pasukan itu.

Pipeline Rendering

Takrifan ejen hidup dalam YAML. Claude Code membaca Markdown. Orkestra merapatkan jurang ini dengan satu pipeline rendering yang deterministik:

YAML Registries → Jinja Templates → .claude/agents/*.md

Operator menyunting sumber YAML. Jalankan orkestra sync. Markdown yang dirender muncul dalam .claude/agents/. Claude Code mengambil perubahan itu.

Pemisahan ini berkhidmat untuk khalayak yang berbeza:

Sumber YAML merangkumi metadata lifecycle, tag, peraturan pengesahan, dan nota deprecation untuk tooling
Markdown yang dirender hanya merangkumi apa yang diperlukan oleh model: penerangan, tool, skill, dan panduan gelagat

Pipeline itu menggubah identity, mindset, style, dan skill menjadi satu prompt yang koheren. Seorang ejen architect-analytical-concise mendapat prompt sistem yang sangat berbeza daripada seorang ejen debugger-skeptical-technical, walaupun mereka berkongsi sesetengah skill yang mendasari.

Pengetahuan Domain: Corak Empat Fail

Setiap domain pengetahuan mengikuti struktur yang konsisten:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Struktur ini berkhidmat untuk pemuatan konteks ejen. Seorang ejen yang bekerja pada authentication memuatkan authentication/patterns.md untuk panduan dan authentication/anti-patterns.md untuk mengelakkan perangkap yang diketahui. Fail-fail itu bersaiz untuk pemuatan konteks yang cekap: cukup fokus untuk berguna, cukup komprehensif untuk berautoriti.

Kami menyenggara 21 domain peringkat atas termasuk analitik, authentication, data science, infrastruktur, pembelajaran mesin, prestasi, keselamatan, dan banyak lagi. Setiap domain boleh mempunyai sub-domain untuk granulariti yang lebih halus.

Values: Sistem Operasi

Semua ejen berkongsi satu lapisan asas values yang mentakrifkan bagaimana mereka beroperasi:

Kesederhanaan dahulu. Gunakan penyelesaian paling ringkas yang berfungsi. Tambah kerumitan hanya apabila wajar.

Baiki punca akar. Jangan sesekali menutup kegagalan dengan penyelesaian sementara tanpa membaiki puncanya. Jika pipeline gagal, nyahpepijat pipeline itu. Jika ujian gagal, baiki kod atau ujian itu.

Berasaskan bukti. Labelkan dakwaan sebagai “disahkan” (dengan penanda aras) atau “dianggarkan” (dengan andaian). Corak yang dikesan tidak sama dengan masalah yang disahkan.

Ekonomi konteks. Tool MCP menelan kos 0.1% konteks. Bacaan fail menelan kos 2% setiap satu. Gunakan kepakaran domain sebelum meneroka kod.

Values ini merambat kepada setiap spesialis menerusi pipeline rendering. Seorang ejen tidak boleh memintasnya menerusi komposisi.

CLI: Satah Kawalan

Orkestra dikeluarkan dengan satu CLI untuk menguruskan ekosistem ejen:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI itu adalah sumber kebenaran untuk ejen apa yang wujud, skill apa yang mereka ada, dan sama ada sistem itu sihat. Ia menjalankan pengesahan sebelum segerak (sync) untuk menangkap masalah lebih awal.

Pertimbangan Sumber Terbuka

Kami membina Orkestra untuk menyelesaikan masalah kami sendiri: menyelaraskan ejen AI pada skala besar untuk pangkalan kod yang kompleks. Corak yang kami temui bukan khusus untuk domain kami sahaja.

Sistem komposisi karakter (identity + mindset + style) terpakai kepada mana-mana pasukan yang mentakrifkan personaliti ejen.

Sistem tier skill (K0-K4) menyediakan satu model mental untuk menyusun keupayaan boleh guna semula mengikut skop.

Corak pipeline rendering (sumber YAML + templat + artifak yang dijana) memisahkan tanggungjawab tooling daripada keperluan model.

Model orkestrasi rata (satu koordinator, ramai spesialis) mengelakkan kerumitan sambil membolehkan paralelisme.

Sama ada Orkestra menjadi sumber terbuka bergantung kepada sama ada corak-corak ini bernilai untuk orang lain yang membina dengan Claude Code. Jika anda bertembung dengan dinding yang kami gambarkan, seni bina ini mungkin membantu.

Apa Yang Kami Pelajari

Membina Orkestra mengajar kami bahawa orkestrasi bukan tentang menjadikan ejen lebih bijak. Ia adalah tentang menjadikan mereka lebih fokus.

Satu ejen sahaja dengan arahan yang sempurna masih kehabisan konteks. Satu ejen sahaja dengan semua skill masih keliru tentang yang mana hendak digunakan. Satu ejen sahaja yang cuba menjadi segala-galanya menghasilkan hasil yang sederhana di mana-mana.

Empat puluh spesialis, setiap satu cemerlang dalam domain mereka, diselaraskan oleh satu orchestrator yang tahu bila hendak mewakilkan tugas: itulah cara kami mengeluarkan produk.

Angka-angka itu kurang penting berbanding seni bina. Anda mungkin memerlukan lima ejen atau lima puluh. Prinsipnya kekal: komposisi mengatasi keupayaan, pengkhususan mengatasi generalisasi, penyelarasan mengatasi kepahlawanan individu.

Orkestra menggerakkan ekosistem ejen di sebalik Maguyva, platform kecerdasan kod kami. Mahu tahu lebih lanjut? Hubungi pasukan kami.