Lompat ke kandungan utama

Panduan pembangun

💡TL;DR
Mulakan pada cabang ciri, pasang kebergantungan terkunci dan kedua-dua versi pelayar, kemudian bina serta jalankan semua ujian Jest. Perluas modul pemilik kontrak sedia ada. Selaraskan dokumentasi, ujian penyedia dan bukti aplikasi natif dengan perubahan tingkah laku.

Sediakan salinan kerja​

Klon repositori, baca AGENTS.md dan cipta cabang ciri. CI pemalam menggunakan Node 20 pada Linux/Windows. Laman awam disahkan dengan Node 24; pasang kebergantungan secara berasingan pada akar dan website/.

Dari akar repositori:

npm ci
npx --no-install playwright install --with-deps chromium
node node_modules/playwright-chromium/cli.js install chromium
npm run build
npm test -- --runInBand

Dua pakej Playwright boleh menggunakan revisi Chromium berbeza. Memasang satu sahaja tidak mencukupi untuk persekitaran bersih. main.js dijana dan diabaikan Git; bundle setempat lama bukan bukti komit baharu.

Kenal pasti pemilik sebelum menyunting​

TanggungjawabSumber utama
Kitar hayat pemalam, arahan dan penghalaan hossrc/main.ts
Pratetap penyedia, metadata protokol dan pengesahansrc/llmProviders.ts
Bentuk permintaan, penghantaran, ulangan dan penstrimansrc/llmUtils.ts
Definisi operasi, skema dan pemilihan CLI awamsrc/operations/, src/cliContracts.ts
Tugas fail, penyelidikan dan terjemahansrc/fileUtils.ts, src/searchUtils.ts, src/translate.ts
Tindakan aliran dan susunan bar sisisrc/workflowButtons.ts, src/ui/NotemdSidebarView.ts
Spesifikasi serta pemaparan rajahsrc/diagram/, src/rendering/
Rentetan UI dan bahasa UI disokongsrc/i18n/
Panduan awam dan terjemahanwebsite/docs/, website/i18n/
Panduan penyelenggara serta bukti bertarikhdocs/maintainer/

Bundle pengeluaran semasa serba lengkap, termasuk hos pratonton sebaris. Laluan calon hos paparan kendiri bukan kontrak aset yang dihantar. Jangan aktifkan tanpa menyelaraskan pembungkusan, aset keluaran, audit dan dokumentasi.

Laksanakan perubahan berskop​

  1. Hasilkan semula tingkah laku dan tambah ujian terfokus yang gagal sebelum perubahan tingkah laku.
  2. Ubah modul pemilik invarian. Sahkan input luaran di sempadannya; elakkan pengetahuan penyedia/operasi berulang pada pemanggil.
  3. Ulang ujian terfokus kemudian seluruh suite. Sertakan pembatalan, ralat dan ketekalan simpanan apabila operasi menulis fail.
  4. Kemas kini sumber panduan Inggeris dan bahasa terjejas. Dokumen perancangan, tugas dan walkthrough memerlukan versi Inggeris serta Cina lengkap dan berasingan di docs/.
  5. Periksa aplikasi pengguna sebenar apabila mengubah visual atau eksport natif. XML, tangkapan skrin atau binaan lulus sahaja tidak membuktikan kebolehsuntingan natif atau keterikatan penyambung.

Bagi penyedia baharu, tambah pratetap dalam llmProviders.ts, gunakan penghantaran sedia ada jika serasi, dan kemas kini llmProviders.test.ts, llmUtilsProviderSupport.test.ts, README serta ujian sambungan. Kekalkan penstriman dan pengendalian respons terganggu.

Bagi operasi, tentukan skema input/hasil, konteks, kesan sampingan serta tag pengendalian sebelum mendedahkannya. Entri daftar tidak terus menjadi titik akhir Agent awam. Lihat panduan Agent.

Sahkan perubahan​

npm run build
npm test -- --runInBand
npm run audit:i18n-ui
npm run audit:render-host
npm run lint:regressions -- --base-ref origin/main
git diff --check

Pintu lint membandingkan diagnostik individu dengan garis dasar. Hutang sedia ada tidak membenarkan ralat baharu; jumlah keseluruhan lebih rendah tidak menghalalkan regresi. Gunakan npm run benchmark:local-kb bagi perubahan dapatan setempat; laporkan korpus dan persekitaran, bukan janji kelajuan sejagat.

Untuk laman awam, gunakan Node 24:

npm --prefix website ci
npm --prefix website run build
npm --prefix website run audit:build
npm run docs:build

Program dokumentasi 1.9.9 menggunakan terjemahan yang ditulis dan disemak terus oleh Codex. Jangan jalankan skrip penulisan terjemahan lama atau memanggil titik akhir LM Studio/terjemahan untuk menyediakannya. Alat boleh memformat, mengesahkan dan memaparkan teks yang ditulis.

Uji dalam Obsidian dan aplikasi natif​

Gunakan Vault ujian. Skrip hos memerlukan penanda .notemd-host-verification dan mengesahkan bundle disalin. Asingkan Vault pengguna sebenar. Cuba kedua-dua obsidian help dan obsidian-cli help untuk integrasi CLI; rekod alat tiada, jangan anggap stub arahan sebagai ujian hos berjaya.

Pemeriksaan PowerPoint, CircuitikZ dan eksport slaid natif mempunyai prasyarat serta artifak sendiri. Ikut rekod penerimaan kebolehpercayaan bertarikh dan panduan keluaran. Nyatakan batas mudah alih dan versi minimum yang belum disahkan.

Sumbangan dan keluaran​

PR perlu menerangkan masalah, tingkah laku hasil, ujian dan batas berkaitan. Gunakan Issues untuk laporan boleh ulang. Jangan komit kelayakan API, bahan Vault peribadi atau hasil terjana tidak berkaitan.

Penerbitan dimiliki penerbit dan panduan dalam repositori: metadata selaras, tag angka, sumber bertag bersih, nota dwibahasa, aset draf disahkan, kemudian penerbitan serta deployment Pages yang jelas. Jangan alihkan tag awam untuk mengganti binari. .trellis/ ialah keadaan aliran setempat dan tidak boleh menjadi kebergantungan CI.

Seterusnya​