Cordis チュートリアル
Cordis は DeepSeek Harness を支えるプラグインフレームワークです。ツール、LLM アダプター、ファイルアクセス、エージェントループ自体などのすべての機能を、共有コンテキストにマウントするプラグインとして扱う小さなランタイムです。このチュートリアルでは Cordis を実践的に学びます。各章では、このリポジトリ内のスクラッチディレクトリで作成する実行可能な例を扱い、最後には実際の harness サービスに接続したプラグインを完成させます。
対象読者はエージェント開発者です。TypeScript の深い経験は必要ありません。以下の TypeScript の解説 で不慣れな構文を説明しており、各章では正確なコマンドと期待される出力を示します。
手順ではなく要点をまとめたリファレンスを読みたい場合は、Cordis 入門を参照してください。網羅的な API リファレンスは、サブシステムのページおよびCordis コア APIのページにある生成済みのcordis-surfaceリージョンにあります。
harness 自体のプラグイン（以下のランチャーではなく、cordis.ymlから読み込まれ Web UI で操作されるもの）を作成するには、最初の Harness プラグインから始めてください。
セットアップ
依存関係をインストールしたこのリポジトリのクローンが必要です。前提条件は開発ガイドに記載されています。このチュートリアルに API キーは必要ありません。すべての例はキーなしで実行できます。
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install各章で使用するスクラッチディレクトリを作成します。tmp/は gitignore の対象であるため、ここに書いた内容がバージョン管理に影響することはありません。
mkdir -p tmp/cordis-tutorial
cd tmp/cordis-tutorial各章では、このディレクトリから同じコマンドを実行します。
node --import tsx ../../vendor/cordis/bin.jsこの単一ファイルのランチャー（vendor/cordis/bin.jsを参照）はルートContextを作成し、Loader プラグインをマウントして、カレントディレクトリから./cordis.ymlを読み込むよう指示します。ほかのすべて、つまり存在するプラグインやその設定は、その YAML ファイルから取得されます。このファイルはすぐに作成します。--import tsxフラグにより、ビルド手順なしで Node が設定で指定された TypeScript ファイルを実行できます。
各章
- 最初のプラグイン — プラグインは関数であり、ローダーがそれをマウントします。
- ライフサイクルとエフェクト — Cordis が管理する登録は、プラグインがアンロードされると取り消されます。
- サービス —
ctxで機能を公開し、injectでそれに依存します。 - イベント — 型付きイベント、ブロードキャストディスパッチ、ウォーターフォールのショートサーキットを扱います。
- 設定 —
cordis.ymlから検証済みの設定を取得し、不正な入力は明確に失敗させます。 - コンポジションと HMR — プラグインツリーとしての設定ファイル、ホットリロード、そして読み込まれないプラグインの診断を扱います。
- harness への組み込み — 実際の harness サービスに対してモデルから呼び出せるツールを登録します。
TypeScript の解説
これらの例では、通常のモダン JavaScript に加えて、次の 3 つの TypeScript 機能を使用します。
- 型注釈 は、実行時の動作を変えずに値を記述します。
ctx: Contextはctxが Cordis のコンテキスト API を持つことを示し、who: stringはテキストを受け取り、string[]は文字列の配列を意味します。 import type { Context } from '@deepseek-ai/cordis'は型情報のみをインポートします。実行時には消えるため、注釈だけのためにContextを必要とするプラグインファイルでも、実行時の依存関係は追加されません。- 宣言のマージ （
declare module '@deepseek-ai/cordis' { ... }）は、Cordis がすでに宣言しているインターフェースに独自のエントリを追加します。たとえば、新しいctx.greeterプロパティやイベント名の型です。実行時の配線は生成されません。プラグインが別途サービスを提供するか、イベントを発行します。第 3 章でこのパターンを詳しく示します。
第 5 章では、設定オブジェクトのフィールドを記述するinterfaceと、スキーマが検証するオブジェクトフィールドを示すSchema<Config>のようなジェネリック型も使用します。これらの宣言は示されているとおりにコピーできます。周囲の本文で、それぞれが何を結び付けるのかを説明します。