Tugas Latar Belakang

Belum dirilis

Tugas latar belakang adalah fungsi yang terus berjalan selama Extension menyala, misalnya sinkronisasi setiap 15 menit. Tugas ini memerlukan service di dozin.capabilities. Daftarkan dengan api.registerService(definition).

ServiceDefinition

Field	Tipe	Wajib	Deskripsi
id	string	Tidak	Default-nya nama paket. Huruf kecil, angka, dan tanda hubung. Paling banyak 8 per Extension
name	string	Tidak	Ditampilkan di Pengaturan › Ekstensi, 1–80 karakter; default-nya id
start	'auto' | 'manual'	Tidak	Default manual. auto mulai bersama Extension setelah secrets-nya diisi. Pilihan pengguna yang berlaku
restart	{ policy?, maxRetries?, backoffSeconds? }	Tidak	policy: never, on-failure (default) atau always; maxRetries 0–100 (default 5); backoffSeconds 1–10 jeda, masing-masing 1–3600 detik (default 5, 30, 120)
stopTimeoutSeconds	number	Tidak	1–30, default 10: berapa lama Hentikan menunggu run selesai
run(ctx)	function	Ya	Lihat di bawah

Field yang tidak valid membuat seluruh tugas ditolak (registerService melempar TypeError); tidak ada yang diperbaiki untuk Anda.

run(ctx) Belum dirilis

Tugas itu sendiri. Berjalan sampai ctx.signal terpicu.

Nama	Tipe	Deskripsi
ctx	ServiceContext	Field dan fungsi di bawah ini

Mengembalikan Promise<void>. Selesai berarti run berakhir. Melempar error dihitung sebagai kegagalan dan dicoba ulang sesuai restart. Jika Hentikan ditekan dan run belum selesai dalam stopTimeoutSeconds, proses Extension dijalankan ulang.

Field ServiceContext

Field	Tipe	Deskripsi
serviceId	string	Key tugas: nama paket, atau <package>.<id>
runId	string	Run ini
signal	AbortSignal	Terpicu saat Hentikan, Mulai ulang, mematikan Extension, menghapus instalasinya, dan keluar dari Cowork. Periksa sebelum setiap permintaan
env	Readonly<Record<string, string>>	Nilai dari dozin.secrets. Tugas yang kekurangan nilai tidak akan mulai dan menampilkan "Konfigurasi belum lengkap"
dataDir	string	Folder data milik Extension, sekaligus folder kerjanya

ctx.status(text, level?, progress?) Belum dirilis

Mengatur baris yang ditampilkan di bawah tugas di Pengaturan › Ekstensi.

Nama	Tipe	Wajib	Deskripsi
text	string	Ya	Barisnya; paling banyak 300 karakter yang disimpan
level	'info' | 'warn' | 'error'	Tidak	Default info
progress	{ done: number, total: number }	Tidak	Ditampilkan sebagai progres

Tidak mengembalikan apa pun. Nilai dari dozin.secrets diganti dengan ***. Jangan masukkan data pribadi: baris ini terlihat oleh siapa pun yang ada di depan komputer.

ctx.status('Synced 52 patients', 'info', { done: 52, total: 52 });

ctx.log(text) Belum dirilis

Menulis satu baris ke log Extension. Nilai dari dozin.secrets diganti dengan ***. Tidak mengembalikan apa pun.

ctx.log('round started');

ctx.readJson(rel) Belum dirilis

Membaca file JSON di dalam dataDir.

Nama	Tipe	Wajib	Deskripsi
rel	string	Ya	Path relatif terhadap dataDir

Mengembalikan Promise<unknown>: nilai hasil parse, atau undefined jika file tidak ada. Reject dengan PATH_OUTSIDE_DATA untuk path kosong atau path di luar dataDir, dan dengan error parse jika file bukan JSON yang valid.

ctx.writeJson(rel, value) Belum dirilis

Menulis file JSON di dalam dataDir, menggantinya dalam satu langkah, sehingga crash tidak pernah meninggalkan file setengah jadi.

Nama	Tipe	Wajib	Deskripsi
rel	string	Ya	Path relatif terhadap dataDir
value	unknown	Ya	Apa pun yang diterima JSON.stringify

Mengembalikan Promise<void>. Reject dengan PATH_OUTSIDE_DATA untuk path kosong atau path di luar dataDir.

Setelah sebuah run berakhir, panggilan ctx.site dan ctx.agent darinya di-reject dengan RUN_ENDED.

Contoh

export function activate(api) {
  api.registerService({
    id: 'sync', name: 'Sync', start: 'auto',
    async run(ctx) {
      while (!ctx.signal.aborted) {
        const state = (await ctx.readJson('state.json')) ?? { runs: 0 };
        state.runs += 1;
        await ctx.writeJson('state.json', state);
        ctx.status(`Run ${state.runs} done`);
        await new Promise((resolve) => setTimeout(resolve, 15 * 60 * 1000));
      }
    }
  });
}

Terkait

• Permintaan Situs ctx.site
• Percakapan Layanan ctx.agent
• Entri dan Pendaftaran registerService