DDS Plugin SDK
Pasang DDS Plugin SDK 1.2 publik dan gunakan alur kerja, cache, streaming alat, LSP, dan API stabil.
Contoh ruang kerja pengguna di bawah menggambarkan host pengembangan yang dikendalikan pelanggan dan dihubungkan secara eksplisit. WSL adalah salah satu host opsional untuk contoh tersebut. Aplikasi Windows Digital Design Studio biasa menggunakan berkas Windows native dan runtime UI/WASM bersama. Operator mengonfigurasi penemuan, izin, dan kapabilitas plugin untuk host SDK yang dipilih; tugas mesin Cloud terkelola menggunakan model eksekusinya sendiri.
1. Memasang SDK
DDS Plugin SDK 1.2.1 menyediakan API JavaScript, deklarasi TypeScript, penyedia bahasa, tema, alat ruang kerja, dan tugas perintah. Penyimpanan tahan lama opsional menambahkan riwayat tugas, percobaan ulang eksplisit, serta snapshot teks/biner terverifikasi yang tetap ada setelah sumber dihapus dan proses dimulai ulang. Gunakan Node.js 22 atau 24. Pasang rilis SDK stabil dari rilis GitHub resmi. Untuk plugin perintah mandiri, gunakan Alat Pengembangan setelah instalasi:
1.0.0 memublikasikan API SDK stabil, 18 profil kesesuaian host, kebijakan dukungan/migrasi, dan pemeriksaan beban kerja gabungan yang diukur. Plugin baru menggunakan >=1.0.0 <2.0.0. Validasi fungsional yang dipublikasikan mencakup API SDK, kesesuaian host, dan beban kerja gabungan. Gunakan hasil tersebut untuk menilai perilaku SDK yang diuji oleh pemeriksaan rilis.
0.13.0 menambahkan enam templat pengembangan, tipe dan skema yang dihasilkan, skenario pengujian deterministik, serta diagnostik lokal opsional. SDK yang dikemas dan proyek yang dihasilkan berjalan di luar pohon sumber; replay sintetis dan debugging loopback dipilih secara eksplisit.
0.12.0 menambahkan pengaturan bertipe dengan cakupan terbatas dan migrasi eksplisit, referensi rahasia dengan cakupan eksekusi, input/output perintah terstruktur, katalog locale, dan metadata aksesibilitas. SDK publik dan contoh independen memeriksa konflik pengaturan, input tidak valid, otoritas yang dicabut, dan alternatif terjemahan. Gunakan fitur ini melalui API host SDK mandiri dan contoh independen.
0.11.0 menambahkan bantuan signature, completion yang dimuat saat diperlukan, snippet terbatas, pengeditan multi-berkas dan rename yang ditinjau, pemformatan/tindakan kode, token semantik, folding, hint, dan simbol hierarkis. Usulan melewati peninjauan dan pemeriksaan otoritas saat ini sebelum penerapan bersyarat; penampilan dan penerapan memerlukan hasil dokumen terkini. Contoh independen menguji fitur ini dalam host SDK publik yang dikonfigurasi secara eksplisit.
0.10.0 menambahkan unduhan streaming browser, unggahan berkas terpilih, antrean transfer campuran, dan pemulihan checkpoint Worker OPFS. Transfer memeriksa otoritas saat ini, identitas berkas, serta hash chunk/seluruh berkas sambil memisahkan kemajuan byte dari penyimpanan terverifikasi. Gunakan contoh SDK publik ini dengan host yang dikonfigurasi secara eksplisit dan integrasi yang dikelola aplikasi.
0.9.0 menambahkan pohon proyek dengan cakupan terbatas, pencarian nama berkas/teks, dan pengamatan perubahan untuk direktori lokal yang dipilih operator. Gunakan dari klien HTTP atau helper proyek sambil mempertahankan snapshot pengeditan dan draf yang belum disimpan. Contoh proyek di bawah mencakup pembuatan, pencarian, perubahan eksternal, dan penanganan konflik.
mkdir hello-dds-plugin
cd hello-dds-plugin
npm init -y
npm install --ignore-scripts --save-exact "https://github.com/Altifigence/dds-plugin-sdk/releases/download/v1.2.1/altifigence-dds-plugin-sdk-1.2.1.tgz"
Contoh diagnostik pertama menggunakan kode tepercaya dalam host pengujian lokal. Tema menggunakan impor XML DDS yang sudah ada. Untuk integrasi alat yang sudah ada, lihat Plugin dan Alat Pihak Ketiga.
2. Menulis Plugin Pertama Anda
Buat plugin.mjs di proyek baru. Plugin ini memeriksa dokumen teks biasa dan melaporkan diagnostik informasi pada setiap baris yang berisi NOTE.
plugin.mjs
import { createDiagnosticsResult, definePlugin } from '@altifigence/dds-plugin-sdk';
export default definePlugin({
manifestVersion: 1,
id: 'hello-diagnostics',
name: 'Hello Diagnostics',
publisher: 'example',
version: '0.1.0',
protocolVersion: 1,
entry: './plugin.mjs',
capabilities: ['diagnostics'],
permissions: ['document.read', 'diagnostics.publish'],
supportedHosts: ['test-host'],
license: 'Apache-2.0',
}, context => context.registerDiagnosticsProvider({languages: ['plaintext']}, {
provideDiagnostics(request, {signal}) {
signal.throwIfAborted();
const diagnostics = [];
const lines = request.snapshot.text.split(/\r\n|\n|\r/);
for (let line = 0; line < lines.length; line++) {
const character = lines[line].indexOf('NOTE');
if (character !== -1) diagnostics.push({
range: {start: {line, character}, end: {line, character: character + 4}},
severity: 'info',
code: 'todo',
source: 'hello-diagnostics',
message: 'Review this marked line before sharing the document.',
});
}
return createDiagnosticsResult(request, diagnostics);
},
}));
Manifest mendeklarasikan protokol versi 1, kapabilitas diagnostics, host test-host, serta izin document.read dan diagnostics.publish. Penyedia menerima snapshot dokumen dan AbortSignal. Rentang diagnostik menggunakan baris berbasis nol dan offset karakter UTF-16.
3. Menjalankannya Secara Lokal
Buat run.mjs di samping plugin.mjs. Aktifkan plugin, berikan dokumen, dan minta diagnostik. Selalu dispose host setelah selesai.
run.mjs
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';
const host = createTestHost();
try {
await host.activate(plugin);
host.setDocument({
uri: 'memory:///hello.txt',
languageId: 'plaintext',
modelVersion: 1,
workspaceRevision: 'example-1',
text: 'Hello, DDS!\nNOTE: write a plugin.\n',
});
const result = await host.requestDiagnostics();
console.log(`${plugin.manifest.name}: ${result.diagnostics.length} diagnostic`);
for (const diagnostic of result.diagnostics) {
console.log(`${diagnostic.severity} ${diagnostic.range.start.line + 1}:${diagnostic.range.start.character + 1} ${diagnostic.message}`);
}
} finally {
host.dispose();
}
node run.mjs
Output yang diharapkan (baris dan kolom yang dicetak berbasis satu):
Teks
Hello Diagnostics: 1 diagnostic
info 2:1 Review this marked line before sharing the document.
4. Menguji Plugin Anda
Simpan pengujian ini sebagai plugin.test.mjs. Pengujian memeriksa rentang diagnostik dan memastikan bahwa pengeditan dokumen menghapus diagnostik.
plugin.test.mjs
import assert from 'node:assert/strict';
import test from 'node:test';
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';
test('reports a NOTE and clears it after editing', async () => {
const host = createTestHost();
try {
await host.activate(plugin);
const document = {
uri: 'memory:///hello.txt',
languageId: 'plaintext',
modelVersion: 1,
workspaceRevision: 'test-1',
text: 'NOTE: write a plugin.\n',
};
host.setDocument(document);
const result = await host.requestDiagnostics();
assert.equal(result.diagnostics.length, 1);
assert.equal(result.diagnostics[0].code, 'todo');
assert.deepEqual(result.diagnostics[0].range, {
start: {line: 0, character: 0},
end: {line: 0, character: 4},
});
host.setDocument({...document, modelVersion: 2, text: 'Done.\n'});
assert.equal((await host.requestDiagnostics()).diagnostics.length, 0);
} finally {
host.dispose();
}
});
node --test plugin.test.mjs
Pengujian seharusnya lolos. Tambahkan fixture untuk bahasa Anda sendiri, pembatalan, hasil tidak valid, dan dokumen besar. Pertahankan versi dokumen terkini agar hasil dari snapshot sebelumnya ditolak.
5. Membuat dan Menerapkan Tema
Simpan palet terang/gelap ini sebagai theme.json. Enam warna di setiap palet diperlukan. Token semantik opsional menyesuaikan pencarian, pilihan, HintsBox, dan kanvas GDS; token yang dihilangkan menggunakan default DDS.
theme.json
{
"name": "Hello Ocean",
"colors": {
"light": {
"backdrop": "#dbe8ef",
"navigation": "#edf5f8",
"tool": "#f3f8fb",
"main": "#ffffff",
"text": "#183b4e",
"muted": "#486477"
},
"dark": {
"backdrop": "#0c1922",
"navigation": "#102430",
"tool": "#17303e",
"main": "#1c3949",
"text": "#e8f4fb",
"muted": "#adcadb"
},
"metrics": {
"panelRadius": 16,
"controlRadius": 8
}
}
}
Buat export-theme.mjs di sampingnya. parseTheme memvalidasi data warna dan serializeThemeXml mengekspor XML DDS versi 2.
export-theme.mjs
import { readFile, writeFile } from 'node:fs/promises';
import { parseTheme, serializeThemeXml } from '@altifigence/dds-plugin-sdk/themes';
const theme = parseTheme(await readFile('./theme.json', 'utf8'));
await writeFile('./hello-theme.xml', serializeThemeXml(theme), 'utf8');
console.log('Created hello-theme.xml');
node export-theme.mjs
Perintah menulis hello-theme.xml dan mencetak Created hello-theme.xml. Di DDS, buka Pengaya → Pasang tema..., pilih XML, lalu pilih Terapkan untuk Hello Ocean. Beralih antara tampilan terang dan gelap untuk melihat kedua palet.
Anda juga dapat menggunakan Pengaturan → Umum → Tampilan → Impor XML. Simpan tema saat ini dengan Ekspor XML sebelum menggantinya. Ini mengimpor data tampilan XML ke konfigurasi tema.
Dokumen Panduan tema mencantumkan semua token dan metrik yang didukung. Contoh Hello Ocean menyertakan tema lengkap, XML siap impor, dan pratinjau HTML lokal.
Referensi XML Tema
Unduh XML Hello Ocean dan JSON yang dapat diedit. XML berisi palet terang dan gelap lengkap, seluruh 28 warna peran opsional pada setiap mode, dan empat metrik eksplisit. Simpan berkas XML secara lokal sebelum mengimpornya. Contoh SDK asli ini menggunakan Apache-2.0; pertahankan pemberitahuan saat membagikannya.
Mulailah dengan Pengaturan → Umum → Tampilan → Ekspor XML untuk mencadangkan tema saat ini. Impor XML yang diunduh, tinjau draf, lalu pilih Terapkan. Buang perubahan mempertahankan tema yang sudah diterapkan. Beralih antara tampilan terang/gelap untuk meninjau kedua palet. Untuk memulihkan, pilih tema bawaan atau impor salinan yang Anda simpan. Impor yang ditolak mempertahankan tema saat ini.
DDS, ALcad, editor bersama, navigasi proyek, pengaturan, dan popup menggunakan palet workbench bersama pada profil tersebut. Format tema yang sama digunakan oleh Cloud dan desktop; impor secara terpisah pada setiap profil. gdsBackground mengontrol kanvas GDS secara independen. Warna kanvas desain, lapisan, dan simulasi lainnya dapat memiliki pengaturan sendiri. XML membawa palet dan metrik tampilan untuk profil tema ini.
Elemen | Aturan |
|---|---|
| Satu root; nama yang telah dipangkas sepanjang 1–80 unit kode UTF-16; maksimal 65536 byte UTF-8 untuk keseluruhan XML. |
| Keduanya wajib, masing-masing dengan enam warna di bawah. |
| Penggantian v2 opsional. Peran yang tidak disertakan mengikuti default DDS untuk mode tersebut. |
| Penggantian numerik v2 opsional. |
Versi 1 | Hanya kedua palet. Berkas v1 yang ada tetap didukung; exporter SDK menghasilkan v2. |
Kunci palet wajib | Penggunaan |
|---|---|
| Latar belakang luar ruang kerja |
| Navigasi proyek |
| Panel dan kontrol alat |
| Ruang kerja utama dan pengaturan |
| Teks utama |
| Teks sekunder |
Kunci peran opsional (28) | Penggunaan |
|---|---|
| Latar belakang, teks, dan placeholder pencarian bersama |
| Bidang kompatibilitas; bidang pencarian bersama saat ini tidak memiliki border |
| Baris dan teks yang dipilih |
| Tab editor |
| Rel alat, batas panel, dan popup |
| Garis luar fokus keyboard |
| Warna status dan latar belakang bola AI |
| Latar belakang saran dan detail |
| Teks saran, detail, dan sekunder |
| Saran yang dipilih dengan keyboard |
| Saran yang ditunjuk pointer |
| Latar belakang kanvas penampil GDS |
HintsBox adalah fitur saran kode bersama. Temukan warnanya di bawah Kustom → Warna dan bentuk terperinci → HintsBox dan latar belakang GDS di bawah Tampilan. Edit ketiga warna pencarian bersama-sama agar kontrasnya mudah dibaca. Fragmen ini berada di dalam tema v2; pertahankan kedua palet lengkap:
Fragmen XML v2
<tokens mode="dark">
<color key="search" value="#214556"/>
<color key="searchText" value="#e8f4fb"/>
<color key="searchPlaceholder" value="#adcadb"/>
</tokens>
Metrik | Nilai yang diizinkan | Default DDS saat ini |
|---|---|---|
| Bilangan bulat 0–24 | 14 |
| Bilangan bulat 0–16 | 6 |
| Bilangan bulat 0–24 | 16 |
| Angka 0,6–1 | 0,72 |
Tulis metrik sebagai <number key="popoverOpacity" value="0.9"/> di dalam <metrics> tanpa satuan. Nilai radius dalam piksel. SDK membiarkan metrik yang tidak disertakan tetap tidak ada; rilis DDS terpasang menyediakan default-nya. Tetapkan nilai eksplisit untuk tampilan yang konsisten. Hello Ocean sengaja menetapkan 16, 8, 12, dan 0,9. Pengaturan pengurangan transparansi dan warna paksa dapat mengubah rendering akhir.
Setiap warna harus berupa #RRGGBB enam digit; alpha, nama CSS, variabel, URL, dan style ditolak. Kunci atau mode duplikat, elemen/atribut yang tidak dikenal, namespace, DTD, entity, dan instruksi pemrosesan ditolak. Deklarasi dan komentar XML diperbolehkan. Jika impor gagal, periksa ukuran berkas, versi, kedua palet lengkap, dan nilai yang didukung, lalu coba lagi dengan cadangan Anda yang tidak berubah. Tema dari editor lain perlu dikonversi ke format DDS ini.
6. Menjalankan Ruang Kerja di Lingkungan Anda
Jalankan host, SDK, plugin, dan alat di lingkungan WSL, container, atau server Anda sendiri. Berkas proyek tetap di bawah root yang Anda pilih. Klien SDK mandiri membaca dan mengeditnya melalui koneksi; klien tersebut menerima metadata plugin dan hasil perintah, sedangkan kode plugin berjalan di lingkungan Anda.
Di proyek SDK yang dibuat di atas, simpan helper ini sebagai copy-workspace-example.mjs. Helper menyalin server, plugin, alat, dan proyek sampel yang dapat diedit sambil mempertahankan tata letak berkas lisensi contoh.
copy-workspace-example.mjs
import { cp, copyFile, mkdir } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';
const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await mkdir('./user-host/examples', {recursive: true});
await cp(path.join(sdkRoot, 'examples/user-workspace'), './user-host/examples/user-workspace', {
recursive: true, force: false, errorOnExist: true,
});
await copyFile(path.join(sdkRoot, 'LICENSE'), './user-host/LICENSE');
console.log('Created user-host');
node copy-workspace-example.mjs
Proyek sampelnya adalah user-host/examples/user-workspace/project. Mulai server di lingkungan tersebut menggunakan token yang dihasilkan secara eksplisit:
WSL / Linux / container
export DDS_WORKSPACE_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
node user-host/examples/user-workspace/server.mjs
PowerShell
$env:DDS_WORKSPACE_TOKEN = node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))"
node user-host/examples/user-workspace/server.mjs
Server mencetak Workspace server: http://127.0.0.1:4777/dds/workspace/v1 beserta ID dan generasi ruang kerja. Di terminal klien, tetapkan DDS_WORKSPACE_TOKEN ke token yang dihasilkan. Token ini adalah kredensial operator, terpisah dari token DDS Account. Hentikan server sampel dengan Ctrl+C.
Dari terminal lain dalam proyek yang sama, atur DDS_WORKSPACE_TOKEN ke rahasia yang sama dan jalankan klien pengembang:
node user-host/examples/user-workspace/client.mjs http://127.0.0.1:4777
Klien menampilkan berkas sampel dan menjalankan Periksa berkas proyek untuk design.sv. Hasil JSON mencakup tool: "module-counter" dan modules: 1, yang dihasilkan oleh proses anak nyata. Tambahkan --edit ke perintah klien hanya jika Anda ingin contoh menambahkan catatan ke berkas sampel.
Untuk menggunakan proyek Anda sendiri, berikan direktori absolutnya sebagai argumen terakhir untuk server.mjs. Simpan server, modul plugin, dan alat terpasang di lingkungan pengguna yang sama. server.mjs secara eksplisit mengimpor plugin dan memetakan backend bernamanya ke executable dan argumen tetap:
Pemetaan backend server.mjs
'module-counter': createProcessBackend({
executable: process.execPath,
args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
cwd: root,
env: {},
})
Ganti pemetaan ini dengan alat terpasang yang Anda setujui atau backend kustom. ctx.workspace.readFile dan writeFile menggunakan jalur relatif terhadap root terpilih; ctx.backends.invoke("module-counter", input, {signal}) hanya memanggil nama backend yang dikonfigurasi. Adaptor proses mengirim JSON terbatas di stdin dan mengharapkan JSON di stdout. Adaptor tidak menggunakan perintah shell yang disediakan permintaan dan tidak mewarisi variabel lingkungan dari host.
Untuk server jarak jauh, gunakan endpoint HTTPS terautentikasi Anda sendiri atau tunnel privat yang berakhir di loopback lokal. Konfigurasikan pemetaan port container atau TLS di lingkungan Anda. Contoh secara default mengikat loopback; mengubah alamat bind-nya tidak menambahkan TLS. Plugin dan alat tepercaya berjalan dengan otoritas OS milik proses host Anda.
Lihat contoh ruang kerja pengguna dan protokol ruang kerja untuk konfigurasi server, origin, revisi berkas, pembatalan, dan hasil terbatas.
Fitur Bahasa
SDK 0.7.0 menyediakan completion, hover, definisi, referensi, dan simbol dokumen datar. Deklarasikan setiap fitur dalam kapabilitas manifest v2, serta izin document.read dan language.provide. Host harus memberikan kedua izin secara eksplisit. Simpan contoh hover lengkap ini sebagai language-demo.mjs di proyek yang dibuat di atas:
language-demo.mjs
import { definePlugin, createLanguageResult, createPluginHost } from '@altifigence/dds-plugin-sdk';
const plugin = definePlugin({
manifestVersion: 2,
id: 'hello-hover', name: 'Hello Hover', publisher: 'example', version: '1.0.0',
protocolVersion: 1, entry: './language-demo.mjs', runtime: 'ui',
capabilities: ['hover'],
permissions: ['document.read', 'language.provide'],
supportedHosts: ['test-host'], license: 'Apache-2.0',
source: {visibility: 'open', licenseFile: 'LICENSE'},
}, context => context.registerLanguageProvider('hover', {languages: ['dds-demo']}, {
provide(request, {signal}) {
signal.throwIfAborted();
return createLanguageResult(request, {text: 'A local LED signal.'});
},
}));
const host = createPluginHost({grants: ['document.read', 'language.provide']});
try {
await host.activate(plugin);
host.setDocument({
uri: 'memory:///demo.dds', languageId: 'dds-demo',
modelVersion: 1, workspaceRevision: 'demo-1', text: 'led',
});
const result = await host.requestLanguage('hover', {position: {line: 0, character: 1}});
console.log(result.data.text);
} finally {
host.dispose();
}
node language-demo.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/hello-language/run.mjs
Perintah pertama mencetak A local LED signal. Contoh kedua yang dibundel memeriksa kelima fitur menggunakan bahasa pengajaran kecil dengan let name = value; penyedia milik contoh ini mengimplementasikan bahasa pengajaran tersebut.
Fitur | Input permintaan | Data hasil |
|---|---|---|
|
| Hingga 500 |
|
|
|
|
| Hingga 500 lokasi |
|
| Hingga 500 lokasi |
|
| Hingga 500 simbol |
Posisi menggunakan baris berbasis nol dan offset UTF-16. Penyisipan completion berupa teks literal; string hover dan detail berupa teks biasa. Host harus memeriksa berkas dan rentang target sebelum mengikuti lokasi. Hasil mempertahankan identitas permintaan, proyek/sesi, dan versi dokumen. Mengedit snapshot, pembatalan, timeout, pembatalan registrasi, atau disposal mengakhiri permintaan tertunda dan membuang hasil yang datang terlambat.
API ini beroperasi di host SDK tepercaya. Aplikasi host mengintegrasikan tampilan fitur bahasa dan mengonfigurasi proses LSP secara eksplisit. Kapabilitas baru memerlukan host versi 0.3.0 atau lebih baru. Baca Fitur bahasa untuk selector, batas, dan perilaku siklus hidup.
Sesi Pengeditan Proyek
Impor createWorkspaceProject dan applyTextEdits dari @altifigence/dds-plugin-sdk/workspace-client. Setelah host Anda menghubungkan createWorkspaceClient dan meninjau identitas ruang kerja, pemberitahuan, serta akses, panggil createWorkspaceProject(client). Proyek mempertahankan pengikatan koneksi yang persis sama. Menghubungkan kembali memerlukan proyek yang baru ditinjau, meskipun ID dan generasi ruang kerja yang sama dikembalikan.
API | Perilaku |
|---|---|
| Menampilkan satu direktori di bawah root ruang kerja terpilih. |
| Membaca berkas dan mempertahankan konten serta revisinya yang tidak dapat diubah dalam sesi pengeditan. |
| Membuat hanya jika berkas tidak ada, lalu mengembalikan sesi. |
| Membaca |
| Menyimpan hanya jika revisi server masih cocok dengan revisi yang dipertahankan. |
| Menerapkan pengeditan |
| Secara eksplisit membaca konten dan revisi terbaru setelah konflik atau penulisan yang tidak pasti. |
| Membatalkan pekerjaan milik sendiri; disposal proyek membiarkan klien milik pemanggil tetap terhubung. |
Jalankan contoh HTTP lengkap dalam paket terpasang. Contoh membuat ruang kerja sampel sementara sendiri, menguji pengeditan, sesi kedua yang berkonflik, pemuatan ulang eksplisit, Unicode, dan koneksi ulang, lalu menutup servernya dan menghapus direktori sementara tersebut:
node node_modules/@altifigence/dds-plugin-sdk/examples/project-session/run.mjs
Output yang diharapkan: Project session: HTTP edit, conflict, reload, Unicode and reconnect verified. Sumber contoh menunjukkan penyiapan dan pembersihan server/klien lengkap.
Opsi menerima signal dan timeoutMs. Penulisan yang gagal setelah dicoba meninggalkan needs-reload; simpan draf UI yang belum disimpan secara terpisah dan muat ulang secara eksplisit sebelum menyimpan lagi. SDK tidak menggabungkan atau mencoba ulang secara otomatis. Timeout, pembatalan, atau respons yang hilang dapat terjadi setelah server melakukan commit penulisan; membatalkan permintaan membiarkan perubahan yang telah di-commit tetap ada. Setiap sesi mengizinkan satu penyimpanan atau pemuatan ulang tertunda.
Pengeditan teks menggunakan snapshot asli, baris berbasis nol, dan offset UTF-16. Tumpang tindih, pasangan surrogate yang terbelah, dan rentang tidak valid ditolak sebelum penyimpanan. Proyek mengizinkan maksimal 64 sesi terbuka atau sedang dibuka dan 500 pengeditan per penyimpanan. Helper ini menggunakan protokol ruang kerja v1 yang tidak berubah, termasuk server SDK 0.2.x, dan mempertahankan pembatasan root, jalur yang dilindungi, dan hanya baca. Baca Proyek ruang kerja untuk batas siklus hidup dan ukuran.
Referensi API
Impor API plugin dari @altifigence/dds-plugin-sdk. Paket menyertakan deklarasi TypeScript untuk ekspor yang sama.
API | Penggunaan |
|---|---|
| Memvalidasi manifest dan mendeklarasikan fungsi aktivasi. |
| Mendaftarkan |
| Membangun hasil yang tervalidasi menggunakan identitas permintaan. |
| Mendaftarkan penyedia bahasa dan membentuk hasil dengan identitas permintaan yang tervalidasi. |
| Memvalidasi versi manifest, identitas, izin, host yang didukung, dan modul entri. |
| Memvalidasi URI, bahasa, versi model, revisi ruang kerja, dan teks. |
| Memvalidasi protokol, permintaan, cakupan, identitas dokumen, dan bidang diagnostik. |
| Membaca kesalahan bertipe, batas sumber daya, dan versi protokol. |
Impor host pengembang dari @altifigence/dds-plugin-sdk/testing:
API host pengujian | Penggunaan |
|---|---|
| Membuat host lokal. Kedua opsi bersifat opsional; izin default mengizinkan pembacaan dokumen dan diagnostik. |
| Mengaktifkan plugin dan mengembalikan aktivasi yang dapat di-dispose. |
| Menetapkan dokumen saat ini. Naikkan |
| Meminta diagnostik dari penyedia yang sesuai; kedua opsi bersifat opsional. |
| Meminta fitur bahasa yang dideklarasikan dengan izin document.read dan language.provide eksplisit. |
| Menghapus registrasi dan membatalkan pekerjaan tertunda; dispose host saat pengujian berakhir. |
Permintaan mencakup requestId, proyek/sesi scope dan snapshot dengan uri, languageId, modelVersion, workspaceRevision dan text. Gunakan createDiagnosticsResult untuk mempertahankan identitas ini. Hasil berisi array diagnostics dan tidak menyertakan teks sumber.
Kesalahan menyediakan code, termasuk invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable dan budget_exceeded. Timeout permintaan default adalah 5 detik; timeout yang diterima adalah 1–30000 ms. Dokumen dibatasi 262144 byte UTF-8 dan hasil dibatasi 500 diagnostik. Baca LIMITS untuk batas lengkapnya.
SDK 1.0.0 juga menyediakan modul terpisah. Impor ruang kerja dan pengemasan khusus Node berada di lingkungan pengguna:
Impor | API |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Mengemas dan Memublikasikan Plugin Anda
Mulailah dengan plugin yang dapat dipublikasikan yang disertakan. Simpan helper ini di proyek SDK Anda untuk menyalin berkasnya ke direktori my-plugin baru.
copy-publishable-example.mjs
import { cp } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';
const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await cp(path.join(sdkRoot, 'examples/publishable-plugin'), './my-plugin', {
recursive: true,
force: false,
errorOnExist: true,
});
console.log('Created my-plugin');
node copy-publishable-example.mjs
Edit plugin.json, plugin.mjs, disclosure.json dan lisensinya untuk menjelaskan plugin Anda sendiri. Pengungkapan harus cocok dengan penerbit manifest, ID plugin, versi, lisensi, dan visibilitas sumber. Cantumkan hanya berkas yang ingin Anda distribusikan dalam dds-package.json:
dds-package.json
{
"schemaVersion": 1,
"files": [
"plugin.json",
"plugin.mjs",
"disclosure.json",
"LICENSE",
"NOTICE"
]
}
Validasi dan kemas contoh:
npx --no-install dds-plugin validate ./my-plugin
npx --no-install dds-plugin pack ./my-plugin --out ./dist
Dengan metadata contoh yang tidak diubah, pack membuat dist/example-hello-publisher-1.0.0.tgz dan dist/example-hello-publisher-1.0.0.tgz.release.json. JSON rilis berisi SHA-256 arsip akhir, hash manifest/pengungkapan, dan inventaris berkas. Periksa berkas ini sebelum distribusi.
Hanya berkas yang masuk daftar izin, dds-package.json, dan metadata npm yang dihasilkan yang masuk arsip. Validasi memeriksa data paket, dan pengemasan membuat arsip lokal untuk kanal distribusi yang Anda pilih. CLI menolak konfigurasi privat, berkas kunci, dan jalur bertaut; tinjau isi berkas yang Anda pilih sebelum membagikannya.
Saluran | Yang perlu disediakan |
|---|---|
GitHub Release publik | Arsip berversi, JSON rilis eksternalnya, lisensi, dan akses sumber yang diperlukan. |
Registry privat atau saluran unduhan | Berkas berversi yang sama, otorisasi audiens, dan ketentuan plugin yang sebenarnya. |
Manifest v2 mendeklarasikan runtime, izin yang diminta, dan source: {visibility, licenseFile, repository?}. Tetapkan visibilitas ke open atau closed dan sertakan berkas lisensi yang sebenarnya. Kode milik Anda dapat menggunakan ketentuan open source atau proprietari; pemberitahuan SDK dan dependensi yang berlaku tetap harus dipatuhi. Penerima memperoleh JavaScript executable bersama metadata visibilitas sumber dan lisensi yang dideklarasikan.
Ikuti Publikasi dan Lisensi untuk bidang pengungkapan dan persyaratan distribusi. Distribusikan arsip berversi melalui rilis GitHub, registry privat, atau kanal unduhan pilihan Anda.
CLI 1.2.1 mencatat >=1.0.0 <2.0.0 pada paket plugin baru. Arsip historis 0.3–0.13 dan versi tepat 1.0.0-rc.1 mempertahankan peer aslinya. Validasi dan kemas ulang versi plugin baru untuk instalasi stabil; penerbit memperbarui rentang peer dan metadata rilis yang dideklarasikan secara eksplisit saat pengemasan ulang.
Memverifikasi Plugin yang Diunduh
SDK 1.2.1 menyediakan dds-plugin verify untuk metadata plugin rilis tepat 0.3.x–0.13.x, RC1, dan stabil saat ini. Simpan .tgz dan .tgz.release.json bersama. Verifikasi mempertahankan peer asli. Periksa paket yang dibuat di atas:
Memverifikasi contoh yang dikemas
npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz
Perintah memeriksa struktur gzip/tar terbatas, daftar izin berkas yang persis sesuai, hash setiap berkas, manifest, pengungkapan, lisensi, dan metadata npm yang dihasilkan. Perintah menolak tautan, jalur tidak aman atau duplikat, berkas tambahan, dan hook/dependensi npm. Perintah membaca dan memvalidasi arsip lokal di tempat sebagai operasi data saja. Keberhasilan mencetak bukti JSON; penolakan keluar dengan kode 1.
Untuk unduhan yang namanya diubah, gunakan --metadata dengan JSON rilis yang sesuai. Dapatkan SHA-256 yang diharapkan secara independen melalui saluran rilis tepercaya dan berikan dengan --sha256 untuk mematok byte terpilih. API Node menyediakan opsi yang sama:
verify-release.mjs
import { verifyPluginArchive } from '@altifigence/dds-plugin-sdk/publishing';
const receipt = await verifyPluginArchive(process.argv[2], {
metadataPath: process.argv[3],
expectedSha256: process.argv[4],
});
console.log(receipt.pluginId, receipt.pluginVersion, receipt.artifact.sha256);
Jalankan verify-release.mjs dengan jalur arsip, jalur metadata, dan hash huruf kecil 64 karakter yang diperoleh secara independen sebagai tiga argumennya. checksumPinned bernilai true hanya jika hash yang diberikan cocok. Batasnya adalah 12 MiB input terkompresi, 10 MiB isi berkas, 4 MiB per berkas, 256 berkas, dan 256 KiB metadata eksternal.
Metadata pasangannya menyediakan integritas berbasis hash: mengganti kedua berkas dapat menghasilkan hash baru yang cocok. Pastikan identitas penerbit melalui kanal rilis tepercaya, tinjau kode terhadap malware, lalu lakukan pemberian izin dan kualifikasi instalasi DDS sebagai keputusan host yang eksplisit. Bukti menjelaskan byte yang dibaca selama panggilan tersebut; periksa ulang byte sebenarnya jika berkas dapat berubah sebelum digunakan. Arsip plugin 0.3.x/0.4.x/0.5.x/0.6.x/0.7.x/0.8.x/0.9.x/0.10.x/0.11.x yang ada tetap dapat diverifikasi jika memenuhi kebijakan berkas yang diperketat; memasangnya pada 1.0 tetap memerlukan validasi penerbit dan pengemasan ulang. Hapus berkas yang baru dikecualikan dan publikasikan versi plugin baru jika diperlukan. Verifier ini untuk paket plugin DDS; tarball npm SDK menggunakan SHA-256 rilisnya.
Lihat Verifikasi arsip dan contoh lengkap pengemasan/verifikasi/manipulasi.
Izin, Lisensi, dan Penggunaan Data
Izin yang diminta dalam manifest terpisah dari pemberian izin host yang mengaktifkan operasi. Berikan identitas plugin, versi, lisensi sebenarnya, cakupan ruang kerja, dan izin yang diminta kepada pengguna sebelum mengaktifkannya. Jelaskan operator backend, data yang dikirim, tujuan, retensi, dan pemberitahuan privasi sebelum menghubungkan backend tersebut.
Catatan | Makna |
|---|---|
| Keputusan akses host untuk paket, ruang kerja, dan izin yang persis sesuai. |
| Pengguna mengakui telah membaca pemberitahuan informasi. |
| Pengguna memilih apakah menerima ketentuan sebenarnya dari penerbit plugin. |
| Pilihan terpisah ketika pemrosesan opsional menggunakan persetujuan sebagai dasarnya. |
Persetujuan ruang kerja SDK merupakan keputusan akses teknis. Catat penerimaan ketentuan plugin dan persetujuan opsional atas data pribadi sebagai pilihan yang berbeda. Gunakan SDK sesuai ketentuan lisensi Apache-2.0.
Pengembang host dapat mempertahankan pemberitahuan berversi dengan helper asinkron portabel. Misalnya, simpan ini sebagai notice.mjs dan jalankan node notice.mjs:
notice.mjs
import { createNotice, parseNotice } from '@altifigence/dds-plugin-sdk/consent';
const notice = await createNotice({
id: 'greet-data-use',
version: '1.0.0',
locale: 'en',
purpose: 'Explain the greet command',
text: 'The greet command uses the name you enter to return a greeting. It does not read project files or contact another backend.',
});
await parseNotice(notice);
console.log(notice.text);
console.log(`Notice text SHA-256: ${notice.contentSha256}`);
createPermissionGrant mengikat subset izin yang diminta ke manifest v2, hash artefak dan manifest, generasi ruang kerja, identitas host, pemberitahuan, dan kedaluwarsa. isPermissionGranted mengevaluasi identitas saat ini dan peristiwa pencabutan yang diberikan host. revokeConsentReceipt membuat peristiwa terpisah; host kemudian harus menghentikan panggilan terotorisasi berikutnya.
Helper ini memvalidasi catatan lokal. Host menyediakan pilihan pengguna, identitas, penyimpanan, dan penegakan yang sebenarnya. Baca Izin dan persetujuan untuk bidang yang tepat dan contoh izin interaktif untuk demonstrasi izinkan/tolak/cabut yang eksplisit. Penerbit dan host mengelola perjanjiannya melalui proses distribusi masing-masing.
Sumber, Rilis, dan Kontribusi
Repositori SDK resmi berisi sumber, skema, contoh, dan pengujian kontrak. Untuk menjalankan contoh yang dirilis dan pengujian SDK dari sumber:
git clone --branch v1.2.1 --depth 1 https://github.com/Altifigence/dds-plugin-sdk.git
cd dds-plugin-sdk
npm ci
npm test
npm run example
npm run example:language
npm run example:project
npm run example:verify
npm run example:jobs
npm run example:observe
npm run benchmark:files
npm run example:artifacts
npm run benchmark:artifacts
npm run example:durable-jobs
npm run example:stored-artifacts
Laporkan bug SDK melalui GitHub Issues, dengan versi SDK dan reproduksi minimal. SDK berlisensi Apache-2.0; lihat lisensi dan pemberitahuan repositori. Gunakan halaman rilis untuk arsip berversi dan catatan rilis.
Repositori ini memublikasikan SDK pengembang. Berkas SDK yang dideklarasikan, skema, contoh, dan pemberitahuan menentukan cakupan publiknya. Pemeriksaan paket menegakkan inventaris berkas yang persis dipublikasikan dan menolak pola rahasia serta jalur privat yang diketahui. Tinjau isi rilis yang dipilih bersama pemeriksaan pola untuk mengidentifikasi pengungkapan dalam berkas yang didistribusikan.
Pembaruan Keamanan dan Batas Host
Perbarui server ruang kerja dan klien SDK Anda ke 0.3.2 atau lebih baru. Pasang pembaruan server untuk mengaktifkan pemeriksaan berkas dan batas permintaan yang ditingkatkan. Mulai ulang host yang telah diperbarui, tinjau generasi barunya, dan dapatkan persetujuan kembali sebelum menggunakan ruang kerja.
Host ruang kerja Node menolak hardlink yang dapat menjadi alias berkas yang dilindungi atau berkas di luar root terpilih. Salin berkas proyek yang sengaja dibagikan menjadi berkas biasa dengan satu tautan. Penyimpanan kredensial seperti .netrc, _netrc, .git-credentials, .gnupg, .kube dan .docker, nama kunci SSH tambahan, serta alias perangkat Windows juga diblokir. Pengemasan dan verifikasi unduhan menerapkan kebijakan nama kredensial yang sesuai.
Sumber daya server | Batas |
|---|---|
Body masuk secara bersamaan | 16; unggahan berikutnya menerima HTTP 429 sebelum dispatch |
Permintaan yang sedang dieksekusi | 64; pembatalan menggunakan jalur dispatch terpisah |
Koneksi / permintaan per socket | 128 / 128 |
Permintaan dan balasan / isi berkas | 1600000 / 262144 byte UTF-8 |
Klien membatalkan respons ditolak yang belum dibaca dan stream yang macet saat tenggat tercapai atau pembatalan. Timeout setelah penulisan dimulai dapat membuat hasilnya tidak pasti: baca ulang berkas sebelum mencoba kembali. Tinjau isi berkas serta pengecualian jalur untuk menemukan rahasia. Kode plugin tepercaya berjalan dengan akses sistem operasi milik proses host. Gunakan panduan peningkatan keamanan dan batas ruang kerja saat menerapkan host.
Alat Pengembangan
Setelah memasang SDK 1.2.1 di atas, buat proyek plugin perintah terpisah. Pilih tujuan baru untuk berkas yang dihasilkan; jalankan pemasangan dependensi dan eksekusi plugin secara eksplisit setelah pembuatan kerangka. Kerangka mencakup perintah, pengujian, manifes, pengungkapan, dependensi SDK yang disematkan, dan Apache-2.0 LICENSE/NOTICE.
npx --no-install dds-plugin init ../my-command-plugin --id my-command-plugin --publisher example
cd ../my-command-plugin
npm install --ignore-scripts
npm run doctor
npm test
npx --no-install dds-plugin dev . --trust-local-code --command greet --input '{"name":"Ada"}'
Doctor membaca metadata dan memeriksa Node, resolusi SDK, manifest, lisensi, pengungkapan, dan berkas paket dalam daftar izin tanpa mengimpor plugin. Kesalahan menghasilkan status keluar 1; nilai penerbit/dukungan contoh merupakan peringatan. Ganti nilai tersebut dan tinjau lisensi sebelum distribusi.
npx --no-install dds-plugin doctor . --json
npx --no-install dds-plugin dev . --trust-local-code --watch
npx --no-install dds-plugin dev . --trust-local-code --job --command greet --input '{"name":"Ada"}'
npm run pack:plugin
Dev memerlukan --trust-local-code. Dev menjalankan impor/aktivasi lokal tepercaya dalam proses anak dan hanya mengamati berkas dalam daftar izin serta dds-package.json. Setiap eksekusi memiliki tenggat dan batas stdout/stderr 256 KiB. Ctrl+C menghentikan pengamatan dan membersihkan pohon prosesnya. Proses anak berjalan dengan akses sistem operasi Anda dan mewarisi lingkungan Anda. Host pengujian default memberikan izin membaca dokumen dan diagnostik; konfigurasikan host ruang kerja serta izin ruang kerja/backend secara eksplisit untuk integrasi tersebut.
Gunakan --job untuk mencetak kemajuan/log tugas; gunakan --timeout-ms untuk menetapkan hingga 30 detik bagi perintah biasa atau 30 menit bagi tugas. API Node adalah initPlugin, doctorPlugin, dan runPluginDev di /devtools. Lihat panduan alat pengembangan untuk perilaku watch dan batas pembersihan.
Tugas Perintah yang Berjalan Lama
Aktifkan jobs: true pada host/server SDK 0.4.0 untuk menjalankan perintah melampaui tenggat permintaan biasa. Tugas dinonaktifkan secara default. Coba contoh HTTP lokal lengkap yang melaporkan kemajuan, log backend bernama, dan berkas hasil dengan hash yang dipatok:
node node_modules/@altifigence/dds-plugin-sdk/examples/command-jobs/run.mjs
Output yang diharapkan: Command job: progress, backend log and pinned result file verified. Handler perintah menerima job opsional dalam {signal, job}. Handler menyediakan reportProgress, log, addArtifact, dan invokeBackend. Izin workspace.read/write dan backend.invoke yang ada tetap berlaku; tidak ada jalur executable sembarang yang diterima.
await client.connect();
if (!(await client.getJobCapabilities()).enabled) throw new Error("Jobs are unavailable");
const jobId = crypto.randomUUID(); // Save before sending.
let job = await client.startCommandJob(pluginId, "analyze", {}, artifactSha256, {jobId, timeoutMs: 300_000});
let after = 0;
for (;;) {
const page = await client.getJobEvents(jobId, after);
after = page.nextCursor;
if (page.dropped) console.log("Expired events:", page.dropped);
for (const event of page.events) console.log(event.kind, event.data);
job = await client.getJob(jobId);
if (job.state !== "running" && !page.hasMore && after >= job.lastSequence) break;
await new Promise(resolve => setTimeout(resolve, 250));
}
if (job.state === "succeeded") {
const file = await client.readJobArtifact(jobId, "report");
console.log(file.content);
}
Snippet polling mengasumsikan klien yang terhubung dan perintah analyze yang dikonfigurasi untuk mendaftarkan report. Simpan ID tugas sebelum memulai. Memutuskan koneksi atau membatalkan permintaan polling tidak membatalkan eksekusi; hubungkan kembali ke generasi yang sama dan kueri/batalkan secara eksplisit. Pengulangan start dengan ID dan input yang sama menggunakan kembali tugas yang dipertahankan; argumen yang berubah berkonflik. Memulai ulang host menghilangkan catatan dalam memori. Aktifkan penyimpanan tahan lama 0.8 yang terpisah di bawah untuk memulihkan metadata yang telah di-commit setelah restart.
Statusnya adalah running, succeeded, failed, cancelled, dan timed_out. Output yang terlambat dibuang setelah pembatalan; efek samping tidak di-rollback. Penyedia yang belum tuntas mempertahankan slotnya. Batasnya adalah 4 tugas bersamaan, 32 catatan yang dipertahankan, 32 operasi bertingkat per tugas, 256 peristiwa/64 KiB per tugas, 64 peristiwa per halaman, dan 16 artefak. Runtime default adalah 5 menit dan dibatasi maksimal 30 menit. Catatan terminal yang tuntas kedaluwarsa 15 menit setelah peristiwa terakhirnya.
Berkas hasil teks adalah UTF-8 relatif terhadap ruang kerja hingga 256 KiB. Host membacanya dengan izin yang ada, mencatat SHA-256, dan menolak pembacaan berikutnya jika byte berubah. Untuk output simulasi biner atau lebih besar, gunakan API hasil biner opsional. Artefak parsial dapat tetap ada setelah pembatalan; periksa status terminal tugas untuk memastikan keberhasilan. Klien 0.3 yang lebih lama tetap menggunakan metode v1 yang ada; tugas SDK mandiri memerlukan 0.4 pada kedua sisi dan host/klien yang dikonfigurasi secara eksplisit. Lihat Tugas untuk kontrak dan batas yang tepat.
Mengamati Berkas Ruang Kerja
project.watchFiles() mengambil sampel 1–16 jalur berkas relatif yang eksplisit. SDK 1.0.0 menggunakan permintaan revisi saja pada host yang mendukung dan pembacaan terbatas yang ada pada host lama. Contoh mengasumsikan klien yang terhubung dan disetujui host. Ubah design.sv dengan editor eksternal untuk mengakhiri loop; snapshot pengeditan yang dipertahankan tetap tidak berubah.
import {createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
const project = createWorkspaceProject(client);
const edit = await project.openFile('design.sv');
const original = edit.snapshot;
try {
for await (const change of project.watchFiles(['design.sv'], {intervalMs: 1000})) {
console.log(change.kind, change.path, change.previousRevision, change.revision);
if (change.kind !== 'initial') break;
}
console.log(edit.snapshot === original);
} finally { project.dispose(); }
Peristiwa adalah {kind, path, previousRevision, revision} yang tidak dapat diubah. Sampel pertama menghasilkan initial; perubahan berikutnya menghasilkan created, changed, atau deleted. Berkas yang tidak ada memiliki revision null. includeInitial: false mencatat baseline tanpa keluaran, dan revisi yang sama tidak menghasilkan peristiwa. Hanya not_found yang berarti penghapusan; kesalahan izin, jalur yang dilindungi, ukuran, dan transport mengakhiri pengamatan.
Simpan teks UI yang belum disimpan secara terpisah. Pemuatan ulang, penggabungan, dan penyimpanan draf merupakan tindakan eksplisit pemanggil, dan penyimpanan hasil pengeditan tetap dapat berkonflik dengan revisi yang dipertahankan. Jalur dibaca satu per satu sesuai urutan; ini adalah pengamatan berbasis sampel, sehingga perubahan antara sampel dapat bergabung. API ini mengambil sampel jalur berkas yang dipilih secara eksplisit; aplikasi pemanggil mengelola penemuan direktori dan penanganan rename. Pembatasan root, ukuran berkas, dan jalur yang dilindungi yang ada berlaku pada server hanya baca maupun yang dapat ditulis.
Observer berkas dan tugas mulai pada next() pertama, tidak mengambil halaman latar belakang saat konsumen dijeda, dan berbagi batas maksimal delapan observer aktif per klien. Satu next() dapat tertunda; pembacaan bersamaan gagal dengan conflict. Break atau return() menghentikan pembacaan tertunda; disposal proyek menghentikan observer berkasnya, dan disconnect/reconnect/disposal membatalkan semua observer lama. AbortSignal mengakhiri pengamatan dengan cancelled; balasan terlambat tidak dapat menghasilkan hasil.
intervalMs adalah 250–60000 ms (default 1000), diterapkan di antara putaran berkas atau pembacaan tugas idle. requestTimeoutMs adalah 1–30000 ms per permintaan, dengan default tenggat klien. Total timeoutMs adalah 1–1800000 ms sejak next() pertama, termasuk jeda konsumen. Berkas tidak memiliki timeout total secara default; tugas menggunakan default 30 menit. Tenggat melaporkan budget_exceeded dan melepaskan slot. Batas ini diekspor sebagai WORKSPACE_OBSERVATION_LIMITS.
node node_modules/@altifigence/dds-plugin-sdk/examples/workspace-observation/run.mjs
Output yang diharapkan: Workspace observation: file changes, retained draft and resumed job verified. Contoh lengkap membuat ruang kerja sementara sendiri dan memeriksa perubahan berkas, konflik draf, serta pelanjutan tugas eksplisit. Lihat Pengamatan untuk semua opsi dan aturan masa hidup.
Mengamati dan Melanjutkan Tugas
client.watchJob() mengikuti tugas yang sudah ada menggunakan jobs.events/get; waitForJob() mengembalikan snapshot terminalnya. Snippet mengasumsikan klien yang terhubung, jobId yang dimulai secara eksplisit, dan savedCursor (atau undefined). Periksa getJobCapabilities() sebelum memulai tugas. Pengamatan tidak pernah memulai, mencoba ulang, atau membatalkan perintah.
let after = savedCursor ?? 0;
for await (const update of client.watchJob(jobId, {after, intervalMs: 1000})) {
if (update.dropped) console.log('Expired events:', update.dropped);
for (const event of update.events) console.log(event.kind, event.data);
console.log(update.snapshot.state, update.snapshot.progress);
after = update.nextCursor;
}
const result = await client.waitForJob(jobId, {after, timeoutMs: 120000});
if (result.state === 'succeeded') console.log(result.result);
else console.log(result.state, result.error.code);
Setiap pembaruan beku berisi snapshot, events, after, nextCursor, dropped, dan hasMore. Tangani maksimal 64 peristiwa per halaman dan catat nextCursor setelah memprosesnya, bersama ID tugas dan identitas ruang kerja. dropped melaporkan riwayat yang kedaluwarsa. Snapshot dapat lebih baru daripada halaman peristiwanya; terus baca snapshot terminal saat hasMore bernilai true. Iterator berakhir setelah halaman terakhir. waitForJob() menghabiskan halaman yang sama dan mengembalikan succeeded, failed, cancelled, atau timed_out; periksa status alih-alih menganggap setiap promise yang terpenuhi sebagai keberhasilan.
Menghentikan iterator atau timeout hanya menghentikan pengamatan. Perintah server berlanjut sampai selesai atau cancelJob() dipanggil secara eksplisit. Setelah koneksi ulang yang disetujui host, verifikasi ID dan generasi ruang kerja yang sama, lalu buat observer baru dengan ID tugas dan cursor yang disimpan. Observer lama tidak valid meskipun identitas tidak berubah. Tugas yang hilang/kedaluwarsa dan kegagalan transport dilaporkan tanpa pengiriman ulang; tugas dalam memori tidak bertahan setelah host dimulai ulang. Pemulihan tahan lama menggunakan recoverJob() dengan koneksi baru; observer langsung tidak dilanjutkan lintas generasi.
Kontrak hello v1 dan tugas yang ada tetap tidak berubah. Pengamatan berkas menggunakan alternatif pada host 0.3.2/0.4/0.5; pengamatan tugas memerlukan host 0.4 atau lebih baru yang diaktifkan. Host melaporkan kesalahan untuk tugas yang tidak didukung, lalu pemanggil memilih perintah berikutnya secara eksplisit. API pengamatan ini berjalan melalui host/klien SDK mandiri. Lihat Pengamatan dan Kompatibilitas.
Revisi Berkas dan Pembacaan Bersyarat
SDK 0.6.0 menambahkan getFileCapabilities(), getFileRevision(path), dan readFileIfChanged(path, knownRevision) ke klien yang terhubung. Pembacaan revisi mengembalikan {path, revision} tanpa konten. Pembacaan bersyarat yang cocok mengembalikan {path, revision, notModified: true}; konten yang berubah mengembalikan notModified: false dan content. Berikan knownRevision: null untuk konten saat ini. Berkas yang tidak ada ditolak dengan not_found.
let cached = await client.readFile('design.sv');
const current = await client.readFileIfChanged(cached.path, cached.revision);
if (!current.notModified) cached = current;
console.log(cached.content);
const metadata = await client.getFileRevision('design.sv');
console.log(metadata.revision);
Gunakan klien yang sudah terhubung dan diizinkan. Pisahkan draf yang belum disimpan dari cache ini. Pembacaan bersyarat menghitung hash dan mengembalikan satu snapshot berkas; pembacaan berikutnya tetap dapat melihat perubahan lain. Simpan dengan revisi milik konten yang dikembalikan. Panggilan ini tidak memperbarui snapshot sesi pengeditan atau menggabungkan draf. Balasan tanpa perubahan tidak memiliki bidang content; berkas kosong yang berubah memiliki content: “”.
Pengamatan berkas otomatis menggunakan pembacaan revisi saja jika didukung. Metode opsional fs.capabilities, fs.revision, dan fs.readIfChanged mempertahankan hello v1 yang ketat dan metode berkas asli. Host ruang kerja SDK sebelum 0.6 yang dikenal menggunakan fs.read tanpa probe. Host lain harus menjawab penemuan atau mengembalikan kesalahan unsupported yang dikorelasikan dengan benar. Setiap kapabilitas false memilih alternatif pembacaan penuh terbatasnya sendiri; respons server lama tetap mentransfer seluruh konten.
Kapabilitas hanya di-cache untuk koneksi saat ini dan direset saat koneksi ulang atau pencabutan. Balasan tidak valid, ketidakcocokan jalur/revisi, izin, autentikasi, kegagalan transport, dan timeout tidak memicu alternatif. Operasi yang diiklankan lalu gagal tidak diam-diam diturunkan. AbortSignal mencakup penemuan dan pembacaan; timeoutMs diterapkan pada setiap permintaan HTTP. Perubahan koneksi membatalkan operasi lama.
Server tetap melakukan pembacaan berkas penuh yang dijaga dan perhitungan SHA-256 untuk setiap sampel. Validasi UTF-8, batas 262144 byte, serta pemeriksaan jalur/tautan yang dilindungi tetap berlaku. Ini mengurangi byte respons jaringan sambil mempertahankan pembacaan disk yang dijaga dan perhitungan SHA-256 untuk setiap sampel. Pengukuran lokal Node 22.23.1 pada Windows atas 20 sampel 200000 byte tanpa perubahan mengembalikan 4003974 byte untuk pembacaan penuh, 3867 untuk revisi (99,903% lebih sedikit), dan 4247 untuk pembacaan bersyarat (99,894% lebih sedikit). Penemuan disertakan; header HTTP, TLS, dan baseline hello/konten awal dikecualikan. Jalankan npm run benchmark:files pada checkout untuk mereproduksi fixture.
SDK kini memiliki API 1.x stabil, dengan pemeriksaan fungsional yang mencakup perilaku revisi berkas yang didokumentasikan. Klien 0.3.2, 0.4, 0.5, dan 0.6 yang ada mempertahankan API aslinya pada host 0.7. Gunakan host/klien SDK mandiri untuk menguji API ini. Lihat Revisi berkas untuk kontrak lengkap dan aturan migrasi.
Hasil Tugas Besar dan Biner
SDK 0.7.0 menambahkan ekstensi berkas hasil biner opsional. Perintah tepercaya mendaftarkan berkas ruang kerja yang ada; host mencatat SHA-256 dan panjangnya. Klien membaca maksimal 64 KiB per chunk, dan pengunduh Node melanjutkan berkas parsial serta memverifikasi output lengkap. Berkas tercatat maksimum adalah 1 GiB; API berkas UTF-8 dan artefak teks 256 KiB yang ada mempertahankan batasnya.
Aktifkan jobs: true dan binaryArtifacts: true pada host plugin milik server. Keduanya default false. Pertahankan token eksplisit, pemberitahuan operator, pin artefak plugin yang ditinjau, dan izin workspace.read efektif. Berikut ini melanjutkan penyiapan ruang kerja di atas; ruang kerja hanya baca dapat mendaftarkan berkas yang sudah dihasilkan oleh alat yang dikonfigurasi operator.
const server = await createWorkspaceServer({
root, workspaceId, token, notice,
plugins: [{plugin, artifactSha256}],
grants: ['workspace.read'],
jobs: true, binaryArtifacts: true, writable: false,
});
Daftarkan hasil di dalam perintah yang dimulai dengan startCommandJob. Registrasi melakukan streaming berkas yang ada melalui SHA-256 menggunakan buffer 64 KiB. Referensi menunjuk ke berkas sumber itu, bukan salinan yang tidak dapat diubah. Jalur yang dilindungi, traversal, tautan, dan berkas nonreguler ditolak; perubahan sumber berikutnya gagal dengan conflict.
context.registerCommand({id: 'collect', title: 'Collect trace'}, async (_, {job}) => {
if (!job) throw new Error('Start this command as a job');
const artifact = await job.addBinaryArtifact({
id: 'trace', path: 'outputs/trace.fst', label: 'Simulation trace',
});
return {artifactId: artifact.id};
});
Gunakan klien yang sudah terhubung dan diizinkan serta ID tugas yang sudah ada. Tujuan adalah jalur absolut dalam direktori nyata yang sudah ada dan dikendalikan pemanggil. Helper menulis destination + “.dds-part” dan menolak menimpa berkas akhir yang sudah ada.
import {downloadJobBinaryArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const capabilities = await client.getBinaryArtifactCapabilities();
if (!capabilities.enabled) throw new Error('Binary results are not enabled');
const reference = await client.getJobBinaryArtifact(jobId, 'trace');
const receipt = await downloadJobBinaryArtifact(client, reference, {
destination: absoluteDownloadPath, resume: true,
signal: abortController.signal,
onProgress({receivedBytes, totalBytes}) {
console.log(receivedBytes, totalBytes);
},
});
console.log(receipt.verified, receipt.revision);
Simpan seluruh referensi {jobId, scope, artifact}. Setelah terputus, hubungkan kembali secara eksplisit ke generasi host yang sama dan panggil helper lagi dengan referensi tersebut serta resume: true. Helper menghitung ulang hash prefix yang disimpan dan hanya meminta suffix yang belum ada. Helper memeriksa SHA-256 untuk setiap chunk, seluruh stream yang diterima, dan berkas staging sebenarnya sebelum menerbitkan. Bukti akhir verified: true mengonfirmasi penyelesaian; callback kemajuan sinkron tetap belum terverifikasi. Berkas parsial yang rusak memerlukan penghapusan eksplisit atau tujuan baru.
listJobBinaryArtifacts(jobId) mengembalikan metadata biner tercatat secara terpisah dari hasil teks yang ada. readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) mengembalikan base64 kanonis dengan SHA-256 chunk, rentang yang tepat, dan penanda EOF. decodeBinaryArtifactData dari /artifacts mengembalikan byte Uint8Array. Konsumen browser harus memverifikasi sendiri hash seluruh berkas; pemeriksaan chunk individual tidak membuktikan output yang dirakit cocok dengan referensi.
Hasil biner dan teks berbagi 16 slot serta namespace ID per tugas. Operasi pengambilan/pembacaan biner dibatasi empat per host/ruang kerja, dan unduhan Node empat per proses. timeoutMs unduhan Node adalah tenggat total, dengan default maksimal 30 menit; requestTimeoutMs default 5 detik dengan maksimum 30 detik. Penerbitan memerlukan dukungan hardlink seperti NTFS atau ext4. Gunakan tujuan tepercaya di bawah kendali operator dan kelola penulis bersamaan; pemeriksaan sistem berkas berjalan dengan otoritas sistem operasi proses host.
artifacts.capabilities, artifacts.list, dan artifacts.read yang opsional mempertahankan hello v1, snapshot tugas, dan peristiwa yang ada. Host sebelum 0.7 melaporkan ekstensi dinonaktifkan; pemanggil memilih pembacaan teks atau perintah berikutnya secara eksplisit. Autentikasi, balasan tidak valid, dan kesalahan transport tetap menjadi kesalahan. Koneksi ulang, pencabutan, kedaluwarsa tugas, atau generasi host yang berubah membatalkan operasi lama. Retensi tugas tetap dalam memori selama 15 menit setelah peristiwa terakhir tugas terminal. Tugas yang dibatalkan dapat meninggalkan output alat parsial yang tercatat; periksa status terminal tugas untuk memastikan keberhasilan. Ini menjelaskan API langsung/sumber default. API hasil tersimpan yang terpisah di bawah mempertahankan byte setelah restart.
Jalankan npm run example:artifacts untuk transfer nyata 2 MiB dengan interupsi, koneksi ulang, dan pelanjutan suffix saja; npm run benchmark:artifacts menggunakan 8 MiB. Eksekusi lokal Windows mentransfer 8388625 byte dalam 129 permintaan chunk, melanjutkan prefix 65536 byte, dan memverifikasi SHA-256 akhir. Base64 menambah overhead; total body respons JSON adalah 11257419 byte. Transfer dengan penggunaan memori terbatas ini mempertahankan byte berkas dan menggunakan base64 untuk transport. Lihat Artefak biner untuk kontrak lengkap. Gunakan host/klien SDK mandiri untuk alur transfer ini.
Tugas Tahan Lama, Riwayat, dan Percobaan Ulang Eksplisit
SDK 0.8.0 menambahkan penyimpanan tahan lama opsional dalam direktori milik operator di luar ruang kerja. Berikan jalur absolut, ID ruang kerja stabil, kode plugin yang ditinjau, SHA-256 paket, token, dan pemberitahuan. Contoh juga mengaktifkan byte berkas yang dipertahankan; hilangkan artifacts dari jobStorage untuk hanya menyimpan metadata tugas. Balasan v1 yang ada dan default hanya memori tetap kompatibel.
import {createNodeJobStore} from '@altifigence/dds-plugin-sdk/job-storage-node';
import {createNodeArtifactStore} from '@altifigence/dds-plugin-sdk/artifact-storage-node';
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
const store = await createNodeJobStore({directory, workspaceRoot: root, workspaceId});
const artifacts = await createNodeArtifactStore({jobStore: store});
const server = await createWorkspaceServer({
root, workspaceId, token, notice, plugins: [{plugin, artifactSha256}],
grants: ['workspace.read'], jobs: true, binaryArtifacts: true,
jobStorage: {store, artifacts},
});
Penyedia mulai hanya setelah intent awalnya disimpan. Checkpoint berikutnya digabungkan; flushJobStore() menunggu checkpoint yang diminta, bukan penyelesaian perintah. Pemulihan memisahkan koneksi saat ini dari cakupan eksekusi asli dan melaporkan live, completed, interrupted, expired, missing, corrupt, atau unsupported. Tugas yang terputus tidak pernah dimulai ulang otomatis; unrecordedTail-nya tidak diketahui.
const capabilities = await client.getJobStorageCapabilities();
const query = {limit: 16, commandId: 'analyze'};
const page = await client.listJobHistory(pluginId, artifactSha256, query);
const prior = await client.recoverJob(pluginId, previousJobId, artifactSha256);
const attempt = await client.retryCommandJob(pluginId, previousJobId,
reviewedFreshInput, artifactSha256, {jobId: crypto.randomUUID()});
Riwayat memfilter status, disposisi pemulihan, perintah, waktu mulai, dan upaya induk. Halaman berisi hingga 32 entri, diurutkan berdasarkan waktu mulai menurun lalu ID tugas. Cursor membekukan keanggotaan selama 60 detik dan harus menggunakan ulang kueri yang sama; tugas baru dikecualikan, catatan yang dihapus atau tidak diizinkan dilewati, dan kedaluwarsa dilaporkan. Restart menghilangkan cursor. artifactCount, snapshotCount, dan resultAvailability menggambarkan referensi tercatat, bukan bukti berkas saat ini.
Percobaan ulang eksplisit memerlukan ID tugas baru, input baru yang tervalidasi, paket yang sama dan saat ini disetujui, serta perintah yang tersedia. attemptOf menautkan eksekusi baru ke induknya yang tidak berubah. Mengulang ID, input, induk, dan timeout yang sama mengambil upaya yang dipertahankan tanpa menjalankan ulang, termasuk setelah restart. Catatan yang hilang/kedaluwarsa tidak dapat memberikan jaminan itu. Eksekusi yang diterima dapat berlanjut setelah permintaan penunggu dibatalkan; kueri ID tugas baru sebelum memutuskan mencoba kembali.
Retensi default tidak menyertakan input mentah, body hasil, teks kemajuan, dan label artefak; log disamarkan. Hanya penyamar host deterministik yang eksplisit mempertahankan teks yang ditinjau. Token, rahasia, dan persetujuan lama tidak pernah dipulihkan. Identitas ruang kerja/plugin saat ini, izin baca, dan setiap pemberian izin yang tercatat diperiksa ulang. Metadata tugas menggunakan default 256 catatan, 64 MiB, dan 24 jam, dengan maksimum tujuh hari. Penghapusan dan pruning merupakan operasi host yang eksplisit.
Penyimpanan lokal memiliki satu penulis, memvalidasi identitas ruang kerja/root, dan memeriksa integritas metadata. Pemulihan lock usang yang eksplisit hanya mengambil kembali PID mesin yang sama yang terbukti telah mati. Berkas tidak dikenal/rusak memerlukan pemeriksaan. Pada Windows, sinkronisasi dan rename berkas mendukung pemulihan setelah proses dimulai ulang; uji perilaku saat listrik padam secara terpisah pada sistem berkas target. Lihat Penyimpanan tugas, Riwayat dan contoh durable-jobs.
Hasil Tersimpan dan Unduhan Setelah Restart
Dengan penyimpanan artefak diaktifkan, await job.addArtifact() atau job.addBinaryArtifact() menyalin dan memverifikasi seluruh berkas sebelum registrasi. Teks tetap dibatasi 256 KiB; berkas biner maksimal 1 GiB. Stream sumber dan berkas staging sebenarnya diperiksa SHA-256-nya. Pembatalan, kesalahan disk penuh, mutasi, dan penulisan parsial tidak menerbitkan hasil yang dapat digunakan. Berkas yang diterbitkan sebelum crash tetapi belum dicatat oleh tugas dapat tetap ada untuk pemeriksaan operator.
import {downloadStoredJobArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const list = await client.listStoredJobArtifacts(pluginId, jobId, artifactSha256);
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, artifactSha256);
const receipt = await downloadStoredJobArtifact(client, reference, {
destination: absoluteOutputPath, resume: true,
});
console.log(receipt.storage, receipt.snapshotId, receipt.verified);
Daftar memisahkan referensi sumber dari metadata snapshot dan melaporkan snapshot retained, expired, missing, corrupt, atau unsupported. retained adalah status metadata; getStoredJobArtifact() memverifikasi metadata dan seluruh berkas tersimpan sebelum mengembalikan referensi baru dengan generasi saat ini. Setiap pembacaan memeriksa ulang otoritas saat ini dan identitas berkas. Sumber yang dihapus tidak memengaruhi byte tersimpan, dan snapshot yang hilang tidak pernah beralih ke sumber yang dapat berubah. Untuk snapshot teks, panggil client.readStoredJobArtifactText(textReference).
Setelah restart, hubungkan kembali dengan izin saat ini dan dapatkan referensi baru. ID snapshot, ID penyimpanan, dan digest tetap stabil; generasi lama ditolak. resume: true memeriksa ulang prefix .dds-part yang disimpan terhadap snapshot tersebut, memverifikasi chunk dan seluruh berkas staging, serta menerbitkan tanpa menimpa tujuan. Pembacaan memerlukan metadata tugas yang dipertahankan serta byte berkas. Konsumen chunk browser harus memverifikasi digest lengkap; adaptor Worker di bawah menyediakan pelanjutan disk browser secara eksplisit.
Penyimpanan artefak menggunakan default 256 berkas, 256 MiB, dan 24 jam, dengan penyimpanan total maksimum 4 GiB dan retensi tujuh hari. Chunk maksimal 64 KiB, dengan empat pembacaan bersamaan. inspect() melaporkan pemakaian, waktu kedaluwarsa, entri tidak valid, dan berkas yatim. remove(snapshot) dan prune() adalah operasi operator yang eksplisit. Tugas aktif dan pembacaan individual dipatok; kedaluwarsa atau penghapusan di antara chunk dapat menghentikan pembacaan berikutnya. Pruning berkas yatim opsional hanya menghapus berkas satu tautan yang dikenali. Entri rusak atau ambigu memerlukan pemeriksaan.
Retensi berkas menyimpan byte proyek yang sebenarnya secara independen dari penyamaran log. Pilih secara sengaja. Plugin/perintah saat ini, hash paket, ruang kerja, dan izin tercatat tetap diperlukan setelah restart. Selesaikan pemeliharaan, lalu await server.close(), artifacts.close(), dan store.close(), sesuai urutan tersebut. Gunakan API retensi dan penghentian ini dalam host SDK mandiri yang dikonfigurasi secara eksplisit.
Jalankan npm run example:stored-artifacts untuk restart proses anak nyata, penghapusan sumber, pelanjutan unduhan parsial terverifikasi, riwayat, dan percobaan ulang eksplisit. npm run example:durable-jobs juga mencakup penghentian proses paksa. Lihat Hasil tersimpan. Host 0.7 dan sebelumnya yang dikenal melaporkan penyimpanan dinonaktifkan tanpa probe yang tidak dikenal. API langsung/sumber yang ada mempertahankan perilaku aslinya.
Mengamati Proyek
Operator secara eksplisit mengaktifkan projects dan memilih root yang diizinkan pada server. Default-nya dinonaktifkan. Host SDK 0.3–0.8 yang dikenal melaporkan tidak tersedia tanpa probe penemuan baru. Profil sistem berkas yang didukung adalah penyimpanan lokal Windows/Linux. Contoh SDK mandiri ini menggunakan host/klien yang dikonfigurasi secara eksplisit.
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
import {createWorkspaceClient, createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
// The operator chooses the workspace and its allowed local directories.
const server = await createWorkspaceServer({
root: operatorWorkspace, workspaceId, token, notice,
projects: {roots: ['rtl'], fileSystem: 'local'},
});
const client = createWorkspaceClient({url: server.url, token});
await client.connect();
const project = createWorkspaceProject(client);
if (!(await project.getProjectCapabilities()).enabled) {
throw new Error('Project tools are unavailable');
}
const observer = project.watchProject({
root: 'rtl', include: ['**/*.sv'], exclude: ['build/**'],
intervalMs: 1000, debounceMs: 50,
}, {signal});
for await (const event of observer) {
renderExternalView(event.snapshot, event.kind, event.reason);
}
project.dispose(); client.dispose(); await server.close();Peristiwa pertama adalah snapshot penuh. Perubahan berikutnya membawa delta terhadap revisi sebelumnya; hint yang hilang, perubahan saat pemindaian awal, pemindaian tidak lengkap, dan overflow konsumen lambat menghasilkan tampilan resync penuh dengan alasan. Rename dapat muncul sebagai delete/create. Setiap berkas diverifikasi secara terpisah. Revisi snapshot menggambarkan status berkas yang disampel, dan penulisan antara sampel dapat bergabung.
Server dan klien masing-masing mengizinkan empat langganan, dengan empat peristiwa dalam antrean per langganan native. Lease idle default adalah 30 detik; pembacaan berikutnya dapat mengembalikan not_found. Setelah jeda panjang, buat iterator baru untuk snapshot awal. break/return, pembatalan, dan disposal melepaskan langganan; jika koneksi terputus mencegah pembersihan, sumber daya remote yang tersisa kedaluwarsa bersama lease-nya.
Batas pemindaian default adalah kedalaman 8, 512 entri, 1 MiB per berkas, total 16 MiB, dan 10 detik. Maksimum yang dapat dikonfigurasi adalah kedalaman 32, 1000 entri, 16 MiB per berkas, total 64 MiB, dan 30 detik. Berkas yang dibatasi dapat membawa metadata tanpa hash konten; periksa complete dan reasons. Tenggat diperiksa di antara panggilan sistem berkas; gunakan akses OS proses host yang dipilih secara sengaja untuk panggilan tersebut.
Pohon Proyek dan Pencarian
listTree mengembalikan pohon, searchFiles mencari nama berkas relatif berdasarkan substring literal atau glob terbatas, dan searchText menemukan teks literal dalam berkas UTF-8. root wajib; include/exclude relatif terhadapnya. Gunakan mode pencarian literal dan glob terbatas yang didukung. Pencocokan tanpa membedakan huruf besar-kecil hanya melipat ASCII A–Z agar posisi UTF-16 asli tetap stabil.
const tree = await project.listTree({root: 'rtl', pageSize: 16});
const names = await project.searchFiles({root: 'rtl', query: '**/*.sv', mode: 'glob'});
const query = {root: 'rtl', include: ['**/*.sv'], query: 'module ', pageSize: 16};
let page = await project.searchText(query);
for (const item of page.items) {
console.log(item.entry.path, item.entry.revision, item.match.range, item.match.snippet);
}
if (page.nextCursor) {
const next = await project.searchText({...query, cursor: page.nextCursor});
console.log(next.stale, next.items.map(item => item.state));
if (next.nextCursor) await project.releaseProjectQuery(next.nextCursor);
}
if (tree.nextCursor) await project.releaseProjectQuery(tree.nextCursor);
if (names.nextCursor) await project.releaseProjectQuery(names.nextCursor);Kecocokan teks mencakup SHA-256 konten, rentang UTF-16 berbasis nol, dan snippet terbatas. Cursor membekukan keanggotaan asli maksimal 60 detik dan memerlukan kueri yang sama. Halaman berikutnya memeriksa ulang konten saat ini dan menandai item current, changed, missing, atau unverified; berkas baru hanya muncul pada kueri baru. Kecocokan dan revisi yang diambil tetap tidak berubah.
Berkas teks dibatasi 256 KiB, kueri 256 unit UTF-16, dan snippet 512 unit. Default adalah 256 hasil (maksimum 512), 32 item per halaman (maksimum 64), dan respons 64 KiB (maksimum 128 KiB). Berkas biner, UTF-8 tidak valid, serta batas byte/kedalaman/waktu/respons dilaporkan sebagai hasil tidak lengkap dengan alasan. Ada dua kueri bersamaan dan delapan tampilan cursor yang dipertahankan; lepaskan cursor yang tidak digunakan secara eksplisit.
Draf Proyek dan Koneksi Ulang
const edit = await project.openFile('rtl/counter.sv');
const original = edit.snapshot;
const draft = original.content + '\n// unsaved draft';
const query = {root: 'rtl', include: ['**/*.sv'], query: 'module '};
let page = await project.searchText(query);
for await (const event of project.watchProject({root: 'rtl', include: query.include}, {signal})) {
if (event.snapshot.revision !== page.snapshotRevision) {
if (page.nextCursor) await project.releaseProjectQuery(page.nextCursor);
page = await project.searchText(query); // keep the same explicit scope
}
renderTreeAndMatches(event.snapshot, page); // draft remains caller-owned
}
// A changed file causes conflict; a move/deletion can cause not_found.
try { await edit.save(draft); }
catch (error) {
if (!['conflict', 'not_found'].includes(error.code)) throw error;
showResolutionChoice(error, draft, original);
}
// Only an explicit edit.reload() replaces the edit snapshot.
project.dispose(); client.disconnect(); await client.connect();
const freshProject = createWorkspaceProject(client);
const freshObserver = freshProject.watchProject({root: 'rtl'});
console.log((await freshObserver.next()).value.cursor); // 1: full initial view
await freshObserver.return(); freshProject.dispose();Jika snapshotRevision kueri berbeda dari snapshot.revision yang diamati, lepaskan cursor lama dan ulangi kueri root/filter yang sama. Pengamatan tidak pernah memutasi edit.snapshot atau konten draf milik pemanggil. Setelah perubahan eksternal, pemindahan, atau penghapusan, kondisi CAS asli melaporkan konflik; pemanggil memilih pemuatan ulang, penggabungan, atau penyimpanan terpisah secara eksplisit.
Klien memeriksa generasi koneksi, root/filter, hash kueri, posisi halaman, SHA-256 snapshot, dan kesinambungan peristiwa. Respons terlambat dibuang setelah pencabutan, pemutusan koneksi, atau koneksi ulang. Cursor watch dan cursor kueri terpisah dan tidak dipulihkan otomatis. server.revokeProjects() mengakhiri akses proyek; pengaktifan kembali memerlukan generasi server baru.
npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browserContoh Node terpasang memverifikasi pembuatan, pencarian, perubahan eksternal, draf yang dipertahankan, konflik CAS, dan koneksi ulang. Untuk contoh browser, buka URL loopback yang dicetak dan pilih Run scenario. Contoh hanya menggunakan ruang kerja sementaranya, yang dihapus saat server contoh berhenti. Permintaan HTTP menggunakan default lima detik; konfigurasikan timeout klien dan server secara sengaja untuk pemindaian yang lebih besar.
Pengamatan proyek · Kontrak pohon/pencarian · Alat proyek HTTP
Streaming dan Verifikasi Artefak Browser
import {streamStoredJobArtifact} from '@altifigence/dds-plugin-sdk/artifact-transfer';
import {createOpfsFileSink} from '@altifigence/dds-plugin-sdk/artifact-transfer-browser';
// selectedDirectory belongs to the application; no picker or grant is opened by the SDK.
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, pluginPin);
const sink = await createOpfsFileSink(selectedDirectory, 'trace.bin', {overwrite: false});
const receipt = await streamStoredJobArtifact(client, reference, {sink, signal});
if (receipt.verification === 'stored') showSavedHash(receipt.storedSha256);Helper yang aman untuk browser menerima maksimal satu chunk 64 KiB pada satu waktu, menunggu sink terpilih, dan menghitung hash seluruh berkas secara inkremental. Helper memvalidasi rentang yang tepat, identitas, base64, dan hash setiap chunk sebelum menulis. Sink readback lalu membaca ulang byte tersimpan secara independen; verification menjadi stored hanya setelah kedua hash penuh cocok. Tanpa readback, verification menjadi received dan storedSha256 bernilai null. Kemajuan yang mencapai semua byte bukan penyelesaian.
Aplikasi memilih handle berkas atau direktori OPFS dan memberikan izin yang diperlukan. Berikan tujuan terpilih dan izin aksesnya kepada adaptor SDK; aplikasi mengelola interaksi picker dan pemilihan tujuan. Sink writable berkas/OPFS asinkron mempertahankan staging sampai close dan membuangnya jika gagal sebelum commit. Untuk berkas parsial yang aman saat reload, gunakan adaptor Worker khusus di bawah. Batas berkas adalah 1 GiB, empat stream langsung bersamaan, dan tenggat total 30 menit.
Mengunggah Berkas Terpilih
import {uploadFile} from '@altifigence/dds-plugin-sdk/uploads';
import {createBrowserUploadSource} from '@altifigence/dds-plugin-sdk/uploads-browser';
// The operator separately configures uploads.directory/principalId/roots/fileSystem
// on the Node workspace server, and grants workspace.write to this pinned plugin.
const source = createBrowserUploadSource(selectedFile);
const status = await uploadFile(client, source, {
uploadId: crypto.randomUUID(), pluginId, artifactSha256: pluginPin,
path: 'input/trace.bin', expectedRevision: null, signal,
});
if (status.state === 'committed' && status.commitReceipt.verified) {
showCommittedUpload(status.commitReceipt);
}
// To recover a previously selected upload ID, pass the same specification and
// source with recover: true. The helper queries current authority and rehashes it.Unggahan dinonaktifkan secara default. Operator mengonfigurasi ruang kerja Node lokal, direktori staging terisolasi, root yang diizinkan, dan satu principal, lalu memberikan workspace.write kepada plugin terpilih pada pin arsipnya yang tepat. Helper menghitung hash sumber terpilih sebelum memulai. Server menerima chunk 64 KiB berurutan, memverifikasi duplikat dan konten penuh, dan melakukan commit hanya setelah pemeriksaan target bersyarat. Tidak ada byte staging yang muncul dalam daftar ruang kerja normal.
expectedRevision: null memerlukan target yang belum ada; SHA-256 memerlukan target saat ini yang cocok. Pembatalan mempertahankan prefix server yang telah diakui. Operasi recover baru yang eksplisit mengueri otoritas saat ini, memvalidasi sumber/spesifikasi yang sama, dan hanya melanjutkan prefix yang cocok. Respons commit yang hilang tetap tidak pasti sampai dikueri; itu bukan izin untuk mengulang commit atau me-rollback berkas. Batas maksimum adalah 1 GiB per berkas, 4 GiB per penyimpanan, dan empat sesi aktif; default lebih rendah. Host 0.3–0.9 yang dikenal melaporkan unggahan dinonaktifkan tanpa probe metode baru.
Menjadwalkan Transfer Berkas
import {createTransferQueue} from '@altifigence/dds-plugin-sdk/transfer-queue';
const queue = createTransferQueue({
concurrency: 2, perConnection: 1, bufferBytes: 131072,
bytesPerSecond: 1048576, attempts: 3,
});
const unsubscribe = queue.subscribe(view => renderTransfer(view));
const download = queue.enqueueStoredDownload(client, reference, {sink});
download.pause(); // finishes the current stage, then waits at the next boundary
download.resume();
const receipt = await download.result;
queue.release(download.id);
unsubscribe(); await queue.dispose();Antrean milik pemanggil mencampur tugas unggah, unduh langsung, dan unduh tersimpan. Antrean membatasi tugas yang dipertahankan (32), tahap bersamaan (4), konkurensi koneksi klien, reservasi chunk yang didekode (64–256 KiB), laju, dan percobaan ulang. Pekerjaan yang memenuhi syarat dapat maju melewati koneksi yang jenuh, dan prioritas awal yang dibatasi mencegah tugas kecil yang memenuhi syarat tidak mendapat giliran. Tugas yang dijeda menyelesaikan tahap saat ini lalu menunggu; jeda dapat mempertahankan lock penyimpanan. Tenggat total mencakup waktu antre dan jeda.
Percobaan ulang otomatis terbatas pada 429/503 yang dikenali SDK, hilangnya jaringan, atau timeout permintaan selama operasi chunk tepat yang idempoten, dengan backoff dan jitter terbatas. Tangani begin/commit, otorisasi, checksum, rentang, serta kegagalan sumber atau sink secara eksplisit. acknowledgedBytes, transferredBytes, attemptedBytes, retriedBytes, resumedBytes, dan remainingBytes terpisah; hanya bukti terverifikasi yang menghasilkan completed. cancel/dispose menghentikan pekerjaan tersisa sementara berkas yang sudah di-commit mempertahankan byte-nya.
Melanjutkan Unduhan Browser
// Run inside an application-owned dedicated Worker with OPFS + Web Locks.
import {createOpfsArtifactSink} from '@altifigence/dds-plugin-sdk/artifact-resume-browser';
import {streamStoredJobArtifact} from '@altifigence/dds-plugin-sdk/artifact-transfer';
await client.connect();
const fresh = await client.getStoredJobArtifact(pluginId, jobId, artifactId, pluginPin);
const sink = createOpfsArtifactSink({
directory: selectedDirectory, partialId: selectedPartialId, reference: fresh,
});
const receipt = await streamStoredJobArtifact(client, fresh, {sink, resume: true, signal});
console.log(receipt.resumedBytes, receipt.receivedBytes, receipt.storedSha256);
// The first transfer omits resume, and refuses any existing files for that ID.
// A queue can use the same sink and explicit resume: true on a new stored download.Pemulihan persisten memerlukan Worker khusus, akses sinkron OPFS, dan Web Locks. Pemanggil memilih ulang direktori dan UUID parsialnya setelah reload serta memperoleh referensi tersimpan baru yang disetujui. Sink menyimpan dua nama berkas data/metadata yang tepat, identitas snapshot lengkap yang tidak dapat diubah, kedaluwarsa, serta hash prefix saat ini/sebelumnya. Sink tidak menyimpan token, pemberian izin, atau cakupan koneksi lama. Setiap chunk data di-flush sebelum stream metadata kecil ditutup.
Sink dan helper sama-sama menghitung ulang hash prefix secara independen. Tail yang belum di-checkpoint dipangkas hanya setelah prefix tercatat cocok. Metadata yang melampaui ukuran berkas sebenarnya dapat beralih ke checkpoint sebelumnya hanya jika byte dan hash tersebut cocok; kerusakan, entri yang hilang, kedaluwarsa, atau snapshot berbeda gagal tanpa diam-diam memulai ulang. Lock eksklusif seluruh origin menolak tab lain, tetap dipegang selama readback, dan dilepaskan saat close atau Worker berhenti. Membuka ulang kemudian memerlukan pemulihan eksplisit.
Metadata lokal dibatasi 16 KiB dan empat sesi sink terbuka. Retensi default satu jam, dengan maksimum 24 jam yang dibatasi kedaluwarsa snapshot host. Penyimpanan mengikuti kuota, eviction, dan otoritas skrip same-origin browser. Model pemulihan checkpoint mencakup skenario interupsi proses yang diuji di bawah; validasikan perilaku saat listrik padam di lingkungan penerapan. Chromium 154 pada Windows diuji untuk pembatalan, reload, restart host, konflik dua tab, dan penghentian tab pemilik dengan hash berkas tersimpan penuh. Jalankan skenario kualifikasi pada setiap kombinasi browser/OS target.
npm run example:browser-artifacts
npm run example:uploads-browser
npm run example:transfer-queue-browser
npm run example:browser-resumeStreaming · Unggahan · Antrean transfer · Pemulihan Worker
Bantuan Signature dan Bantuan Completion
Deklarasikan signature-help, completion-resolve, dan completion-snippets sesuai kebutuhan dalam manifest v2; modifier completion juga memerlukan completion. Host harus memberikan document.read dan language.provide. Completion literal yang ada tetap valid. languageCapabilities() melaporkan implementasi SDK dan batasnya, tanpa memberikan izin.
const signatures = await host.requestLanguage('signature-help', {
position, context: {triggerKind: 'invoked', isRetrigger: false},
});
const list = await host.requestLanguage('completion', {position});
if (list.data.length) {
const detailed = list.data[0].resolveToken
? await host.resolveCompletion(list.data[0].resolveToken) : list;
const preview = host.prepareCompletion(detailed, 0);
showInsertionPreview(preview.content, preview.tabstops);
host.releaseCompletion(detailed);
}
host.releaseCompletion(list);Aplikasi menyediakan posisi dan host saat ini; persiapan mengembalikan data tanpa menulis dokumen atau berkas. Bantuan signature mendukung hingga 16 signature, masing-masing 64 parameter, dan offset label parameter UTF-16. Resolusi completion menjaga data penyedia tetap privat, mengembalikan token host sekali pakai, dan menetapkan label/penyisipan/rentang terpilih. Token mengikat penyedia, cakupan, dan dokumen, kedaluwarsa setelah 60 detik, serta dibatasi 128 entri, 4 MiB, dan empat operasi resolver nyata. Perubahan dokumen/penyedia membuangnya.
Snippet mendukung $n, ${n}, ${n:literal}, $0, dan escape yang didokumentasikan, dengan mirror dan tabstop berurutan. Variabel, nesting, pilihan, transformasi, dan perintah executable ditolak. Batas UTF-16/CRLF dan pengeditan tambahan yang tumpang tindih diperiksa. Penyedia berjalan sebagai kode dalam proses yang tepercaya dengan otoritas proses host; pembatalan yang diabaikan tetap menempati slot tertunda yang sebenarnya sampai penyedia selesai.
Pengeditan Ruang Kerja dan Rename yang Ditinjau
prepare-rename mengembalikan rentang/placeholder yang tervalidasi atau null; rename mengembalikan usulan WorkspaceEdit atau null. Usulan mendukung edit, create, move, dan delete pada jalur berkas relatif yang tidak saling tumpang tindih. SHA-256 sumber saat ini, ketiadaan tujuan, kebijakan jalur yang dilindungi, geometri pengeditan UTF-16, dan batas diperiksa. Kapabilitas bahasa mengizinkan usulan; klien ruang kerja menyediakan akses berkas dan mutasi yang disetujui secara terpisah.
import {previewWorkspaceEdit, applyWorkspaceEdit, recoverWorkspaceEdit}
from '@altifigence/dds-plugin-sdk/workspace-edits';
const preview = await previewWorkspaceEdit(client, proposal);
// Show every change, conflict and required capability; obtain this exact review.
const receipt = await applyWorkspaceEdit(client, preview, {
reviewed: approvedReview, // {planId, digest} from that review
journal,
authorize: (request, {signal}) => currentHostPolicy(request, signal),
});
// After interruption, current-authority readback does not replay changes.
const observed = await recoverWorkspaceEdit(client, journal, preview.planId);Pemanggil menggunakan klien ruang kerja terhubung yang diizinkan dan jurnal tepercaya. Preview berisi snapshot sebelum/sesudah lengkap serta digest; apply memerlukan planId/digest yang ditinjau dan kebijakan host saat ini yang mengembalikan true. Setiap berkas diperiksa awal, lalu setiap operasi menggunakan CAS per berkas yang ada serta kapabilitas tulis/kelola saat ini. Jurnal menyimpan dan membaca ulang intent sebelum setiap mutasi serta bukti sesudahnya. Konflik atau ketidakpastian menghentikan penulisan berikutnya; setiap berkas mempertahankan batas transaksi CAS-nya sendiri.
Adaptor workspace-edits-node opsional menyimpan jurnal terbatas di luar ruang kerja terpilih, mengikat identitasnya, dan menggunakan lock satu penulis, berkas reguler, serta checkpoint checksum. Setelah proses berhenti, recoverStaleLock merupakan pilihan eksplisit dan hanya mengambil kembali pemilik yang terbukti telah mati. Pemulihan melaporkan applied/not-applied/conflicted/unknown berdasarkan byte saat ini; pemanggil menentukan tindakan berikutnya secara eksplisit. Kompensasi membuat usulan invers baru untuk peninjauan baru. Pada Windows, adaptor menyinkronkan berkas dan melakukan operasi penggantian nama; pemeriksaan mencakup penghentian dan pemulihan proses, dengan persistensi mengikuti sistem berkas dan perangkat penyimpanan. Batas mencakup 32 perubahan, 1000 pengeditan, 256 KiB per berkas, preview 8 MiB, dan 64 rencana jurnal yang dipertahankan.
Pemformatan dan Tindakan Kode Diagnostik
const formatted = await host.requestLanguage('format-range', {
path: 'main.dds', range: selectedRange,
formatOptions: {tabSize: 2, insertSpaces: true, endOfLine: 'preserve'},
});
const formatProposal = host.prepareFormatting(formatted);
await host.requestDiagnostics();
const actions = await host.requestLanguage('code-actions', {
path: 'main.dds', range: selectedRange,
context: {triggerKind: 'invoked', only: ['quickfix']},
});
if (actions.data.length && !actions.data[0].disabled) {
const selected = actions.data[0].resolveToken
? await host.resolveCodeAction(actions.data[0].resolveToken) : actions;
if (!selected.data[0].disabled) {
const fixProposal = host.prepareCodeAction(selected, 0);
showWorkspaceEditProposal(fixProposal); // separate preview, review and apply
}
host.releaseCodeActions(selected);
}
host.releaseCodeActions(actions);format-document dan format-range memerlukan jalur serta opsi tabSize/insertSpaces; hanya pemformatan rentang yang memerlukan pilihan. Hasilnya null atau tepat satu pengeditan berkas saat ini dengan hash snapshot saat ini. Pengeditan rentang tetap di dalam pilihan. endOfLine memilih preserve, lf, atau crlf untuk teks yang disisipkan; byte yang tidak diedit tetap tidak berubah. Usulan dengan konten identik dinormalisasi menjadi null. prepareFormatting tidak melakukan penulisan.
Host mengikat permintaan tindakan dan token resolve ke revisi diagnostik yang diterima serta snapshot saat ini. Publikasi diagnostik berikutnya, perubahan dokumen, atau disposal penyedia membatalkan pilihan lama. Panggilan diagnostik yang tidak berurutan tidak menimpa bundel lebih baru yang diterima. Hingga 100 tindakan membawa label biasa, indeks diagnostik terbatas, usulan pengeditan, data resolve privat, atau alasan dinonaktifkan. Bidang command/URL/shell yang tidak dikenal ditolak. Pengeditan tindakan dapat melampaui pilihan, jadi tinjau seluruh usulan; pemformatan dan tindakan tidak pernah menyetujui penulisannya sendiri.
Tampilan Semantik, Folding, Hint, dan Simbol
import {decodeSemanticTokens} from '@altifigence/dds-plugin-sdk';
const tokens = await host.requestLanguage('semantic-tokens',
previousResultId ? {previousResultId} : {});
host.validateLanguageResult(tokens); // actual current host-owned result only
renderWhitelistedTokens(decodeSemanticTokens(tokens.data, currentDocumentText));
const folds = await host.requestLanguage('folding-ranges', {});
const hints = await host.requestLanguage('inlay-hints', {range: visibleRange});
const symbols = await host.requestLanguage('document-symbol-tree', {});
for (const result of [folds, hints, symbols]) host.validateLanguageResult(result);
// Render labels as text nodes. Release results when no longer retained.
host.releaseLanguageResult(tokens);Token semantik menggunakan legend dengan nama unik dan sembilan kunci style milik host, serta lima bilangan bulat per token: delta baris/start, panjang UTF-16, indeks tipe, dan bit modifier. Token tidak dapat tumpang tindih, membelah surrogate, melintasi baris, atau keluar dari dokumen saat ini. Host selalu mengembalikan array penuh yang dinormalisasi dan UUID host, dengan updateKind full/delta/fallback. Kapabilitas semantic-tokens-delta terpisah mengaktifkan provideDelta terhadap data sebelumnya milik penyedia; cache menyimpan identitas dan data token, bukan teks dokumen lama.
Basis cache terikat ke penyedia, cakupan, URI, dan bahasa, dengan maksimal delapan entri, 4 MiB, dan 60 detik. Peningkatan versi dokumen biasa mempertahankan kemungkinan basis delta sambil membuat hasil tampilan lama menjadi usang. Basis yang hilang/kedaluwarsa, delta null, atau ID basis penyedia yang tidak cocok mengizinkan maksimal satu alternatif penuh dalam timeout asli. Data tidak valid atau kesalahan penyedia gagal tanpa percobaan ulang. Deactivate, unregister, dan penggantian dokumen menghapus basis yang terdampak. Panggil validateLanguageResult tepat sebelum rendering; objek yang disalin, dilepas, atau usang gagal.
Batasnya adalah 20000 token semantik, 64 tipe token, 16 modifier, dan 64 pengeditan delta; folding mengizinkan 1000 rentang dengan kedalaman 32 dan menolak rentang yang bersilangan. Inlay hint mengizinkan 1000 label biasa satu baris di dalam rentang yang diminta. Simbol hierarkis mengizinkan total 1000 entri dan 16 tingkat, dengan anak/pilihan yang terkandung serta saudara berurutan tanpa tumpang tindih. Kontrak document-symbols datar yang asli tidak berubah. Contoh browser menguji full/delta/fallback, folding, navigasi, dan siklus hidup; hint menyerupai HTML tetap berupa teks literal.
npm run example:assistance
npm run example:workspace-edits
npm run example:language-editing
npm run example:language-display
npm run example:language-display-browserBantuan · Pengeditan yang ditinjau · Pemformatan/tindakan · Tampilan
Pengaturan Bertipe dan Referensi Rahasia
Modul /settings menyediakan penyimpanan memori milik operator untuk satu plugin. Definisi berversi mendeklarasikan setiap kunci, skema data, default, cakupan user/workspace yang diizinkan, dan metadata tampilan. Nilai efektif mengganti setiap kunci secara keseluruhan dalam urutan default < user < workspace. read(workspaceId) mengembalikan nilai yang tidak dapat diubah, sumber, dan revisi seluruh penyimpanan. Objek bertingkat tidak digabungkan secara rekursif; nilai yang hilang tanpa default tetap tidak ada.
import {createSettingsStore} from '@altifigence/dds-plugin-sdk/settings';
const settings = createSettingsStore({schemaVersion: 1, pluginId: 'example',
version: 1, settings: {count: {
schema: {schemaVersion: 1, schema: {
type: 'integer', minimum: 1, maximum: 10, default: 2,
}}, scopes: ['user', 'workspace'], display: {label: 'Count'},
}},
});
settings.update({workspaceId: 'selected-project', scope: 'workspace',
expectedRevision: settings.read('selected-project').revision, values: {count: 4}});
const effective = settings.read('selected-project');
// Mount as createPluginHost({settings: {example: settings}, ...}).Penulisan memvalidasi seluruh transaksi dan menggunakan CAS expectedRevision. reset menghapus kunci dari satu lapisan; readOnly memerlukan default dan tidak boleh memiliki cakupan yang dapat ditulis. Langganan menggabungkan perubahan sinkron dan mengembalikan handle yang dapat di-dispose. migrate(nextDefinition, callback, options) eksplisit memvalidasi status berikutnya dan melakukan commit hanya jika revisinya masih cocok. Kegagalan, pembatalan, atau timeout mempertahankan definisi dan status lama. Ekspor/impor berupa data biasa; operator memiliki tanggung jawab persistensi dan enkripsi. Batas mencakup 64 kunci, 32 lapisan ruang kerja, status ekspor 1 MiB, dan satu migrasi nyata.
Plugin ruang kerja mendeklarasikan settings dan settings.read, dan operator memasang penyimpanan yang sesuai dengan izin tersebut. context.settings hanya baca dan terikat ke plugin serta ruang kerja terpilih. Resolver /secrets secara terpisah menerbitkan referensi opaque untuk plugin, ruang kerja, daftar izin perintah, dan masa hidup. Manifest harus mendeklarasikan secrets.resolve dan host harus memberikannya. Bidang input menggunakan type: object dengan format: dds-secret-reference; string biasa dan objek yang mirip tidak membawa otoritas rahasia.
Hanya referensi dalam input tervalidasi yang tersedia melalui options.secrets.withSecret milik perintah. Setiap eksekusi memiliki ID baru; resolver memeriksa cakupan, kedaluwarsa, pencabutan, dan otorisasi saat ini sebelum dan sesudah resolusi serta callback. Callback mengembalikan undefined dan menerima salinan yang dibersihkan saat abort dan setiap keluar. Kesalahan penyedia dibersihkan dari informasi sensitif. Tempatkan lease sebelum efek yang memerlukan otoritas tersebut. Masa hidup referensi default adalah 60 detik, maksimal satu jam; batasnya 128 referensi, 8 lease nyata, dan 16 KiB materi. Jalankan hanya kode tepercaya dengan otoritas proses host karena kode tersebut dapat mempertahankan salinan. Jangan pernah memasukkan materi ke pengaturan, bundel, log, atau hasil; klasifikasikan string aplikasi sembarang secara eksplisit saat menangani rahasia.
Skema dan Formulir Perintah Terstruktur
Perintah dapat mendeklarasikan inputSchema dan outputSchema menggunakan envelope schemaVersion: 1. Parameter primitif yang ada tetap didukung; deklarasi parameters dan inputSchema bersama ditolak. Host memvalidasi dan menerapkan default input sebelum memulai handler atau tugas, lalu memvalidasi output sebelum menerbitkan keberhasilan. Default output tidak pernah diterapkan. Metadata skema/tampilan baru memerlukan peer yang memahami 0.12; validator ketat lama menolaknya, sedangkan definisi lama mempertahankan perilakunya.
import {parseCommandInput, parseCommandOutput} from '@altifigence/dds-plugin-sdk';
const command = {id: 'summarize', title: 'Summarize',
inputSchema: {schemaVersion: 1, schema: {
type: 'object', additionalProperties: false,
properties: {names: {type: 'array', minItems: 1, maxItems: 8,
items: {type: 'string', minLength: 1, maxLength: 64}}}, required: ['names'],
}}, outputSchema: {schemaVersion: 1, schema: {type: 'integer', minimum: 0}},
};
const input = parseCommandInput({names: ['Ada']}, command);
parseCommandOutput(input.names.length, command);Subset terbatas mendukung objek tertutup, array, string, angka finite, bilangan bulat aman, boolean, null, enum primitif, batas, dan default tervalidasi. Keyword tidak dikenal, referensi remote, regex, union, coercion, accessor, dan prototipe kustom ditolak. Skema mengizinkan 32 KiB, kedalaman 8, dan 128 node; nilai mengizinkan 64 KiB. Perintah lengkap tetap memiliki anggaran metadata 16 KiB. DataValidationError lokal menyediakan code, reason, dan jalur bidang yang dikenal seperti /input/options/names/0; kegagalan HTTP dan tugas menyediakan kode aman tanpa nilai yang ditolak.
describeDataForm mengembalikan jalur, tipe, pilihan, default, flag wajib, dan hint referensi rahasia. Metadata tampilan bersama membawa label/help/order literal serta nama aksesibilitas, deskripsi, dan hint keyboard. Host bertanggung jawab atas rendering dan interaksi. Skema ini mendeskripsikan data literal untuk rendering yang dikelola host dan interaksi eksplisit.
Metadata Lokalisasi dan Aksesibilitas
import {parseLocaleCatalog, resolveMessage, localizeDisplay}
from '@altifigence/dds-plugin-sdk/localization';
const catalog = parseLocaleCatalog({schemaVersion: 1, defaultLocale: 'en',
messages: {en: {title: 'Run', done: '{count} results'},
ko: {title: '실행', done: '결과 {count}개'}, ar: {}}, fallbacks: {ar: ['en']},
});
const message = resolveMessage(catalog, 'ko-KR', 'done', {count: 2});
const display = localizeDisplay(catalog, 'ko', {
labelKey: 'title', accessibility: {nameKey: 'title', shortcut: 'Control+Enter'},
});
// Render message.text as textContent; use message.locale and message.direction.
// Preserve raw values and command IDs when the display language changes.Katalog menggunakan tag dasar BCP 47 kanonik dan tepi fallback asiklik yang eksplisit. Hingga delapan preferensi menegosiasikan tag persis, lalu leluhur dan default. Lokal default menentukan semua kunci; terjemahan dapat menghilangkan kunci tetapi tidak dapat menciptakannya. Pencarian per kunci mengikuti tepi fallback yang diurutkan, lalu default. Setiap terjemahan dan argumennya harus cocok dengan kumpulan placeholder {name} yang tepat. Ini adalah interpolasi harfiah tanpa ekspresi ICU. resolveMessage melaporkan lokal sumber dan arah yang sebenarnya, sehingga fallback bahasa Inggris di dalam halaman RTL dapat mempertahankan lang=en dan dir=ltr.
Pemformatan angka mendukung decimal/percent; pemformatan tanggal menggunakan epoch eksplisit dan UTC secara default; pemilihan bentuk jamak mengembalikan kategori cardinal/ordinal Intl untuk pilihan pesan pemanggil. Host bertanggung jawab atas data dan dukungan Intl. validateLocalizedSurfaces memeriksa kunci manifest/command/settings/schema dan sidecar tampilan tema, termasuk panjang tampilan hasil resolusi dan terjemahan yang hilang. JSON/XML tema tetap kompatibel. Batas katalog adalah 32 locale, 256 kunci, dan 256 KiB; label statis tidak boleh berisi placeholder.
Helper /accessibility melaporkan nama yang hilang, shortcut ternormalisasi duplikat, dan kontras pasangan warna opaque eksplisit dalam tema terang/gelap. Gunakan hint ini saat mengimplementasikan key binding sistem operasi yang dikelola host dan menilai aksesibilitas. Contoh independen menyertakan EN/KO, bahasa Arab parsial, dan fixture label panjang. Contoh menguji pengaturan dengan cakupan terbatas, referensi yang ditolak/dicabut, bidang tidak valid, Ctrl+Enter, dan perubahan bahasa selama perintah tertunda. Tata letak browser diperiksa pada ukuran desktop/mobile dalam tema terang/gelap.
npm run example:configuration
npm run example:configuration-browserPengaturan · Referensi rahasia · Skema perintah · Lokalisasi
Templat Pengembangan dan Generasi
Enam templat, dependensi arsip yang tepat, peninjauan generasi, pemeliharaan konflik, dan pemeriksaan doctor.
Kontrak lengkap, contoh, dan batas
Pengujian Deterministik dan Replay
Fixture sintetis eksplisit, waktu virtual, fault, trace terbatas yang hanya berisi hash, dan pembersihan sumber daya.
Kontrak lengkap, contoh, dan batas
Diagnostik Lokal dan Debugging
Profil lokal yang dipilih secara eksplisit dan debugger proses anak tepercaya dengan endpoint loopback sementara serta tenggat total.
Kontrak lengkap, contoh, dan batas
Kesesuaian Host
18 profil berversi membedakan kontrak yang didukung, tidak didukung, dan gagal; adaptor kustom mempertahankan otoritas eksplisit.
Kontrak lengkap, contoh, dan batas
Dukungan SDK dan Migrasi
Lihat inventaris ekspor, kebijakan stabil/opsional/eksperimental, peer yang tepat, tanggal runtime, dan contoh migrasi.
Kontrak lengkap, contoh, dan batas
Penerimaan Rilis
Pemeriksaan rilis yang dipublikasikan menggabungkan beban kerja fault dan pengaman kinerja terukur untuk memvalidasi perilaku SDK yang diuji.
Kontrak lengkap, contoh, dan batas
1.1 Alat Dependensi, Asal-usul, dan Pembaruan
1.1.0 menambahkan bundel offline deterministik dari dependensi yang ditinjau, SBOM CycloneDX, tanda tangan terpisah dengan kunci Ed25519 milik operator, persetujuan/aktivasi/rollback yang terikat digest, serta perbandingan upstream eksplisit. Lima entry point khusus Node menyertakan deklarasi, skema, dan contoh independen. Host memberikan izin eksekusi secara eksplisit, dan tugas lama mempertahankan hash aslinya. Operator mengelola distribusi, penerapan, dan pemantauan. Gunakan contoh independen untuk menguji kontrak bundel, tanda tangan, pembaruan, dan upstream.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjsPanduan lengkap bundel, tanda tangan, pembaruan, dan upstream
1.2 Alur Kerja, Cache, Stream Alat, dan LSP
1.2.0 menambahkan DAG perintah yang ditinjau dengan tugas/izin per langkah, checkpoint tahan lama, dan pemulihan upaya baru yang eksplisit; cache deterministik berbasis konten dan eksekusi inkremental; stream alat UTF-8/JSONL/teks terbatas; serta bridge stdio LSP 3.17 opsional. Tujuh entry point baru menjadikan paket memiliki 50 ekspor dan 107 skema dengan deklarasi serta contoh independen yang terpasang, tanpa dependensi npm runtime. Parser stream alat juga bekerja di browser; alur kerja, penyimpanan, proses eksternal, dan LSP memerlukan Node. Adaptor nyata diperiksa dengan TypeScript 5.9.3 dan language-server 5.3.0, dan bridge memerlukan diagnostik LSP berversi. Operator memulai pemulihan secara eksplisit dan mengonfigurasi integrasi layanan atau produk. Pemeriksaan adaptor ini memvalidasi perilaku SDK mandiri yang diuji.
node node_modules/@altifigence/dds-plugin-sdk/examples/workflows/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs