DeepSeek Harness: Framework Agen Open-Source di mana Benar-Benar Segalanya adalah Plugin

Tumpukan Agen Lengkap, Dilepas ke GitHub

DeepSeek merilis developer preview DeepSeek Harness (dsh) pada 13 Agustus 2026. Repositorinya berada di deepseek-ai/deepseek-harness. Menjelang akhir hari ia memiliki 1.6k bintang, 12.293 komit, dan 19 kontributor — angka-angka yang memberitahu bahwa ini bukan proyek iseng akhir pekan. Basis kodenya 97.1% TypeScript, dengan 1.6% CSS dan 0.7% Python. Versi paket saat publikasi: 0.1.0-rc.5。

Halaman arahannya ada di deepseek.com/harness dan dokumentasi pengembangnya di deepseek-harness.github.io/deepseek-harness。

Berlisensi MIT。

Pitch Satu Baris

Dari README: «Agen = Model + Harness»。

Model adalah jiwanya. Sebuah harness memungkinkan agen memahami lingkungannya, menggunakan alat, dan terus bekerja di pengaturan dunia nyata. Pandangan DeepSeek: setiap kemampuan — model, alat, keterampilan, sesi, kotak pasir, penyimpanan, loop, penjadwalan, dan UI — adalah plugin yang dapat ditukar。

Ini bukan slogan. Ini ditegakkan oleh arsitekturnya。

Cordis: Kernel di Balik Segalanya

DeepSeek Harness dibangun di atas Cordis, sebuah framework plugin yang di-vendor. Desain Cordis dideskripsikan dalam makalah berjudul A Programming Paradigm for Spatiotemporal Composability。

Seluruh framework tereduksi menjadi lima ide:

1. Plugin adalah objek yang mengimplementasikan Service. Bisa berupa fungsi dengan inject dan apply(ctx), atau subkelas Service。
2. Konteks adalah repositori layanan. Sebuah plugin mengklaim kunci stabil seperti ctx.tools, ctx.llm, atau ctx.sessions. Plugin lain menemukan layanan berdasarkan kunci alih-alih mengimpor implementasi konkret。
3. Deklarasikan dependensi layanan via inject. Plugin yang menyebut layanan yang dibutuhkan menunggu sampai layanan itu ada. Tidak ada urutan boot manual。
4. Event Bertipe untuk komunikasi. Empat mode pengiriman: emit (fire-and-forget), waterfall (gaya middleware dengan next()), parallel (semua pendengar berjalan bersamaan), dan serial (pendengar berjalan berurutan dengan nilai kembalian)。
5. Registrasi adalah efek yang dapat dibalikkan. Bagian prompt, skema alat, adapter, pendengar — semuanya terpasang melalui ctx.effect() sehingga reload dan pembongkaran melepasnya dengan terprediksi。

Model waterfall Cordis bekerja seperti around-middleware. Seorang pendengar menerima (...args, next). Panggil next() untuk mendelegasikan ke layanan berikutnya; kembalikan tanpa next() untuk memutus rangkaian. Untuk event keputusan tunggal, pemutusan rangkaian adalah desainnya — pendengar kebijakan dapat memiliki keputusan sepenuhnya。

Segalanya adalah Plugin (Benar-benar)

Daftar plugin di deepseek.com/harness merinci seluruh permukaan kemampuan:

• Models — backend LLM (DeepSeek, OpenAI, Anthropic, Bedrock, Vertex, Azure, Codex, ditambah endpoint kompatibel OpenAI apa pun)
• Tools — apa yang dapat dipanggil oleh model
• Skills — bundel prompt dan alat yang dapat digunakan kembali
• Sessions — manajemen status percakapan
• Sandboxes — tempat kode berjalan (PTY bash, backend lokal danger-full-access, kotak pasir asli berbasis landlock)
• Storage — persistensi sesi
• Loops — logika giliran agen
• Scheduling — pengiriman subagen dan tugas
• UI — Web UI yang disajikan di port 3080 secara default

Pengembang dapat memilih, menukar, atau memperluas salah satu dari ini melalui konfigurasi — tanpa perubahan sumber ke DeepSeek Harness itu sendiri. Plugin Config Catalog dihasilkan secara otomatis dari sumber (scripts/gen-config-catalog.ts) dan diverifikasi segar oleh CI, sehingga setiap bidang di blok config: pada cordis.yml cocok persis dengan tipe konfigurasi yang dideklarasikan plugin。

Empat Mode Runtime

Dokumentasi dilengkapi empat preset. Masing-masing menargetkan kasus penggunaan yang berbeda。

Standard Mode — agen pengkodean penuh: pengeditan file, shell, pencarian file dan web, keterampilan, perencanaan, tujuan, subagen, dan alur kerja. Ini adalah pengalaman Web UI default。

Code Mode — Segalanya di Standard, tetapi alat diekspos melalui Code Mode SDK sehingga model dapat menggabungkan operasi multi-langkah dalam satu program TypeScript. Satu program yang dihasilkan model menggantikan beberapa putaran pemanggilan alat。

Minimal Mode — Hanya dua alat: shell bash persisten dan str_replace_editor. Ini untuk benchmarking model di lingkungan yang disederhanakan. Tanpa keterampilan, tanpa perencanaan, tanpa subagen — kemampuan model mentah terhadap basis kode nyata。

Creator Mode — Dibangun untuk menulis preset agen kustom. Termasuk semua kemampuan mode Standard ditambah inspeksi runtime, eksperimen plugin Cordis di memori, dan panduan penulisan preset. Begitulah cara Anda membangun mode kelima, keenam, ketujuh。

Setiap Jalankan Dapat Dilacak

Di sinilah Harness membedakan dirinya dari sebagian besar peralatan agen. Segala sesuatu yang dilihat model dicatat dalam log sesi append-only:

• Prompt sistem
• Output penalaran
• Pemanggilan alat dan hasilnya
• Keputusan penjadwalan subagen
• Setiap penyuntikan konteks

Web UI memiliki tampilan Trajectory di mana Anda memeriksa catatan ini yang difilter menurut sumber. Lanjutkan, buat cabang, cari, dan putar ulang — keempat operasi bekerja terhadap aliran peristiwa yang sama. Tidak ada basis data jejak terpisah, tidak ada langkah ekspor. JSONL sesi adalah sumber kebenaran。

Untuk Python SDK, direktori sesi menyimpan JSONL tidak terkompresi yang berisi permintaan model yang dirakit dan pemanggilan alat. Contoh di examples/jsonrpc-agent/minimal.py menunjukkan ini dari awal hingga akhir。

Konfigurasi Model: DeepSeek + Apa Pun

Halaman konfigurasi model (Configure models) memiliki tiga lapisan。

DeepSeek Official. Buka Pengaturan → Model, tempel kunci API DeepSeek, simpan. Kuncinya hanya dapat ditulis. Setelah disimpan, UI menerima deskriptor yang telah disunting, tidak pernah teks biasa. Kunci berada di \$DSH_HOME/.credentials.yaml; halaman pengaturan hanya menyimpan referensi kredensial。

Catalog providers. Klik «Add provider», pilih Anthropic atau OpenAI, tempel kuncinya. Penyedia yang menggunakan autentikasi asli (Bedrock melalui kredensial AWS + wilayah, Vertex melalui proyek ADC, Azure melalui api-version, Codex melalui OAuth) tidak bekerja hanya dengan bidang kunci API — masing-masing membutuhkan jalur auth sendiri。

Custom providers. Untuk gerbang perusahaan, server yang di-host sendiri, atau penyedia mana pun yang tidak ada dalam katalog. Atur ID Penyedia huruf kecil (permanen — permintaan, sesi yang disimpan, default model, dan referensi kredensial semuanya menggunakannya), URL dasar, protokol API, kredensial, dan setidaknya satu model。

Model visual membutuhkan satu langkah tambahan. Karena endpoint kustom tidak memiliki cara untuk mengiklankan modalitas yang didukungnya, formulir tidak dapat mendeteksi dukungan vision secara otomatis. Anda menambahkan input: [text, image] ke model di \$DSH_HOME/settings.yaml. Jika semua model kustom Anda menerima gambar, atur defaultInput: [text, image] sekali di tingkat penyedia alih-alih per model. Bidang input adalah pernyataan, bukan pemeriksaan — jika Anda mengklaim model melakukan vision tetapi endpoint sebenarnya tidak, penyedia menolak permintaan alih-alih Harness。

Pemecahan masalah dijelaskan langsung dalam dokumentasi:

• MISSING_CREDENTIAL → simpan kunci penyedia melalui halaman Model atau ekspor variabel env yang direferensikan
• UNKNOWN_MODEL → pilih model yang dikonfigurasi, atau tambahkan model yang hilang ke penyedia kustom
• «Get available models returns 401» → periksa kuncinya. Penemuan model memanggil endpoint GET /models yang kompatibel dengan OpenAI. Jika layanan Anda tidak mengeksposnya, masukkan model secara manual。
• «Image rejected before send» → model tidak mendeklarasikan modalitas image. Tambahkan input: [text, image]。
• «Provider rejects a request with an image» → model mengklaim kemampuan vision yang sebenarnya tidak dimiliki endpoint-nya. Hapus image dari daftar dan mulai sesi baru (gambar lama tetap berada di log sesi dan terus mengulangi permintaan yang sama)。

Memulai: Tiga Jalur

Jalur 1: npx @deepseek-ai/dsh web

Instal Node.js, jalankan satu perintah. Web UI dimulai di http://127.0.0.1:3080. Itu saja. Tidak ada klon, tidak ada build, tidak ada pnpm。

npx @deepseek-ai/dsh web

Kemudian: Pengaturan → Model → tempel kunci API DeepSeek. Pilih ruang kerja (direktori tempat dsh dipanggil berfungsi). Mulai sesi:

Ringkas repositori ini dan identifikasi paket-paket utamanya。

Agen membaca dan mengedit file ruang kerja, menjalankan perintah, mendelegasikan pekerjaan, dan memelihara rencana. Operasi apa pun yang membutuhkan persetujuan di bawah kebijakan izin aktif akan memunculkan dialog di Web UI sebelum dieksekusi。

Jalur 2: Klon dan Bangun dari Sumber

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Jalur 3: Python SDK

Persyaratan: Python 3.10+, Linux x64 / Linux arm64 / macOS 14+ pada arm64, endpoint yang kompatibel dengan DeepSeek。

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

Atur kredensial:

export DEEPSEEK_API_KEY=sk-your-key-here
# Optional:
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

Jalankan tugas terhadap ruang kerja terisolasi:

python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

Untuk kode Anda sendiri, titik masuk SDK adalah DeepSeekHarness sebagai manajer konteks:

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )
    print(result.final_response)

DeepSeekHarness secara malas memulai runtime yang dibundel dan menggunakannya kembali sampai blok with keluar. Gunakan kembali ID sesi yang sama untuk mempertahankan proses Bash (direktori kerja, variabel env, fungsi shell). Gunakan ID sesi baru untuk tugas mandiri。

Komposisi minimal jsonrpc-agent sengaja jarang: hanya bash persisten dan str_replace_editor sebagai alat yang berhadapan dengan model. Timeout Bash 300 detik. Batas output editor 16.000 karakter. Pemadatan konteks dinonaktifkan. Sistem berkas menggunakan backend lokal murni — jalur editor dapat menangani apa pun yang dapat dilihat oleh proses runtime. Dokumentasi memperingatkan secara eksplisit: «Jalankan ini hanya di dalam checkout atau wadah sekali pakai». Backend PTY persisten juga membutuhkan substrat terminal POSIX — tidak ada dukungan Windows untuk komposisi ini。

Tulis Plugin Pertama Anda

Tutorial: Your first plugin。 Plugin adalah modul TypeScript yang mengekspor fungsi apply:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

Daftarkan dalam patch cordis.yml:

- insert:
  - id: hello
    name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

Boot dengan hamparan:

pnpm dsh web --patch ./scratch-plugin/cordis.yml

Pembersihan otomatis adalah fitur andalannya. Apa pun yang didaftarkan melalui ctx — pendengar acara, alat, pengatur waktu — dibersihkan saat plugin dibongkar. Tidak ada removeListener atau clearInterval manual. Untuk pembersihan eksplisit (koneksi jaringan), kembalikan pembuang dari ctx.effect()。

Dependensi dideklarasikan dengan inject:

export const name = 'my-tool-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  // ctx.tools is ready here
}

Cordis menunggu setiap layanan yang diperlukan sebelum memuat plugin。

Ada tiga bentuk plugin: fungsi (di atas), objek dengan apply, dan kelas yang memperluas Service. Gunakan bentuk kelas ketika plugin itu sendiri menyediakan layanan untuk dikonsumsi plugin lain。

Tulis Alat Pertama Anda

Tutorial: Build a tool。 Gunakan defineTool dari @deepseek-ai/dsh-tools:

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: {
        type: 'string',
        required: true,
        description: 'The name to greet',
      },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

defineTool menyimpulkan dan memvalidasi args dari parameters. execute mengembalikan nilai kanonik yang dideklarasikan oleh output.schema. output.render mengubah nilai kanonik tersebut menjadi konten yang berhadapan dengan model. Setelah restart dengan patch, tanyakan di Web UI: «Use the greet tool to greet Ada». Model memanggil greet dan menerima Hello, Ada!。

Langkah selanjutnya dari tutorial adalah plugin configuration, referensi penulisan alat (skema bersarang, nilai kanonik, pekerjaan latar belakang, kait kebijakan, Code Mode, kartu UI), dan capability layering (Definisi Layanan → Penyedia Layanan → pemisahan paket Konsumen)。

Mode Masuk CLI

Perintah @deepseek-ai/dsh adalah peluncur produk. Empat titik masuk:

Direktori pemanggil adalah akar ruang kerja default. Profil web dan headless diinisialisasi otomatis dari templat yang dikirim pada penggunaan pertama. Profil lain mana pun harus dibuat melalui dsh plugin。

Bendera peluncur didahulukan. Token pertama yang tidak dikenali peluncur menjadi argumen aplikasi. Contoh: dsh --profile web --port 8080 menyerahkan --port 8080 ke aplikasi web, bukan ke peluncur。

Direktori profil menyimpan package.json (ketergantungan plugin di luar pohon, ditambah manifes profil dsh.profile dengan daftar bundles berurutan) dan cordis.patch.yml (lapisan patch pengguna sendiri). Urutan komposisi di atas akar kosong adalah: patch setiap bundel dalam urutan dsh.profile.bundles → cordis.patch.yml profil → \$DSH_HOME/cordis.patch.yml tingkat rumah → hamparan --patch. Gunakan --dump-default-config dan --dump-config untuk memeriksa pohon yang terkomposisi tanpa mem-boot-nya。

Plugin Komunitas dan Ekosistem

Beri tag repositori plugin Anda dengan dsh-plugin di GitHub untuk kemudahan penemuan. Situs resmi menaut langsung ke halaman topik itu. Ada juga komunitas Discord DeepSeek Harness untuk diskusi。

Proyek menggunakan Diskusi GitHub untuk umpan balik dan laporan bug. Dokumentasi menaut ke CONTRIBUTING.md untuk alur kerja pengembangan, architecture.md untuk desain sistem, dan AGENTS.md untuk konvensi pengkodean khusus agen。

Developer Preview — Ya, Ini Akan Rusak

README menuliskan ini dengan huruf kapital: «THERE WILL BE COMPATIBILITY-BREAKING CHANGES.»

Plugin inti dan API masih terus berkembang. Halaman arahan mengatakannya langsung: «DeepSeek Harness tetap dalam developer preview dan masih diuji oleh pengembang yang membangun agen harness.»

Jika Anda membangun di atasnya, sematkan hash komit, jaga plugin Anda tetap ramping terhadap katalog konfigurasi, dan berharap untuk menguji ulang pada setiap peningkatan rc. Pembersihan otomatis plugin dan penyuntikan dependensi membuat pengujian ulang tidak sesakit framework monolitik, tetapi «developer preview» berarti persis seperti yang tertulis。

Apa yang Membuat Ini Berbeda

Sebagian besar framework agen saat ini dimulai dengan loop putaran dan menambahkan ekstensibilitas sebagai pemikiran terakhir. Harness membalikkannya: ekstensibilitas adalah framework-nya, dan loop putaran hanyalah plugin lain. Hasil yang dapat diamati adalah tiga hal yang biasanya tidak Anda dapatkan dalam satu paket:

• Tukar apa saja tanpa fork. Tidak suka sistem alat bawaan? Ganti. Ingin lapisan perutean LLM yang berbeda? Tukar penyedianya. Segalanya diselesaikan melalui kunci layanan Cordis。
• Kemampuan lacak secara default. Log append-only bukanlah add-on pengamatan. Ini adalah cara kerja sesi. Lanjutkan, buat cabang, cari, dan putar ulang semuanya menggunakan aliran yang sama。
• Preset yang dapat dikomposisikan, bukan flag fitur. Empat mode (Standard / Code / Minimal / Creator) hanyalah lapisan patch bundel plugin yang berurutan. Anda dapat melapisi preset Anda sendiri di atasnya dengan YAML alih-alih kode。

Apakah pendekatan ini menang atas SDK monolitik tergantung pada apakah ekosistem plugin menghasilkan cukup alat dan penyedia pihak ketiga untuk membuat cerita tukar/komposisi ulang menjadi nyata. Dengan 1.6k bintang dan 12k komit di hari pertama, momentumnya jelas ada。

Referensi

• Halaman arahan DeepSeek Harness
• deepseek-ai/deepseek-harness di GitHub
• Panduan memulai dokumentasi pengembang
• Panduan konfigurasi model
• Panduan Python SDK
• Tutorial plugin pertama Anda
• Tutorial membangun alat
• Panduan Dasar Cordis
• Katalog Konfigurasi Plugin
• CLI README
• Cordis di GitHub
• Makalah Cordis: A Programming Paradigm for Spatiotemporal Composability
• Topik komunitas dsh-plugin di GitHub
• Discord DeepSeek Harness