plugin-write

DeepSeek Harness プラグインの作成

プラグインパッケージを作成します。まずリポジトリモードとプラグイン形式を分類し、次に該当するリファレンスファイルを読み、最後に変更内容を網羅する最小限のゲートで公開エントリを検証します。

まずリポジトリモードを選択する

対象	適用するルール
公式 deepseek-harness モノレポ内のパッケージ	以下のリポジトリ内パッケージ、tsconfig、ドキュメント、ルートゲートのルールを使用します。
外部からインストール可能な DSH プラグイン	そのリポジトリのパッケージレイアウトとスクリプトを維持します。対象となる正確な DSH バージョンで公開されているパッケージとエクスポートのみを使用します。private、ワークスペースのバージョン、ルート tsconfig への登録、モノレポ専用の README ゲートはコピーしないでください。
新しい DSH ホストに適合させる既存のプラグイン	references/version-adaptation.md を読み、バージョンコリドー全体を構築し、7 分類のタッチポイント事前確認を実施します。変更が breaking で、ユーザーがまだ実装を承認していない場合は、移行計画を提示して確認を待ちます。承認後、このスキルの形式別リファレンスを使用する前に、バージョン適合を完了します。形式別の例が、対象のソース、型宣言、リリースノートに優先することは決してありません。

Cordis、Schemastery、DSH のパッケージ名とバージョン範囲は、対象となる正確なバージョンのマニフェストから導き出します。現在の例ではスコープ付きの @deepseek-ai/* 識別子を使用しています。古い対象では異なる場合があり、それぞれで公開されている契約に従う必要があります。

新しい外部プラグインでは、公開識別子を選ぶ前に references/naming-conventions.md を読んでください。プラグインリポジトリのルートに dsh-plugin.naming.json を作成し、最終的なパッケージ検証の前に、同梱の読み取り専用バリデーターを実行します。互換性エラーは対象契約の失敗として扱い、プレフィックスに関する警告はコミュニティからの推奨事項として扱います。--strict を使用するのは、プラグインが衝突耐性プロファイルを採用する場合に限ります。これは公式 Harness マニフェストでも、グローバルな名前の予約でもありません。既存の外部プラグインでは、命名規則からの逸脱を報告しますが、ユーザーが互換性を破る名前変更を明示的に承認しない限り、公開済みの名前を維持します。公式モノレポ内のパッケージには、この外部向け命名プロファイルではなく、対象のチェックアウトに厳密に従います。

オフラインの宣言検証に合格したら、references/registry-check.md を読み、公開ネットワークにアクセスできる場合は、別途中央検索を実行します。対象 Harness の正確なバージョンを指定し、証拠として報告されたインデックスの SHA-256 とソース URL を保持します。検索完了後に一致がなかった場合は「審査済みの一致なし」としてのみ扱い、タイムアウト、不正な形式のデータ、未対応の契約、入力サイズ超過、ネットワーク障害は「不明／未確認」として扱います。オンライン検索によってローカルマニフェストを変更したり、公開済みのインターフェース名を自動で変更したり、自動検出された候補を予約済みにしたりしてはなりません。中央登録を明示的に選択した場合は、v2 エントリ全体を準備し、中央リポジトリの check コマンドと verify-source コマンドを実行してから、registry/entries にコピーします。検証は PR の提出を許可するものではありません。正式な予約は、ソースの裏付けがあるエントリが中央レジストリで審査され、マージされた場合にのみ成立します。

次にプラグインの形式を分類します

必要な機能	形式	リファレンス
ファイルの読み取り、コマンドの実行、Web の検索に使う、モデルから呼び出し可能なツール	ツールプラグイン	references/tool-plugin.md
新しいモデルプロバイダー	LLM アダプタープラグイン	references/llm-adapter-plugin.md
権限、ポリシー、メトリクス、テレメトリーのためのリクエスト、ツール、ターンのインターセプト	フックプラグイン	references/hook-plugin.md
ctx を通じてほかのプラグインが利用する機能	サービスプラグイン	references/service-plugin.md
cordis.yml を通じて提供する、ユーザーが設定可能な動作	設定プラグイン	references/config-plugin.md

プラグインでは、設定可能なツールプラグインや、ツールも登録するサービスなど、複数の形式を自由に組み合わせられます。含まれる各形式は、それぞれ独自の契約を満たす必要があります。要件が上記の5つの形式のいずれにも当てはまらない場合は、既存の拡張ポイントに対応づけ、そこに登録するプラグインを作成してください。Agent ループを直接変更してはいけません。

目的	方法
モデルから呼び出し可能な機能を追加する	ctx.tools に登録します
モデルプロバイダーを追加する	ctx.llm にアダプターを登録します
1つのセッションに異なる機能セットを提供する	Agent プリセットで組み立てます
Shell 実行を追加する	ctx.bash バックエンドを実装して登録します
永続的なターミナル実行を追加する	ctx.pty バックエンドを登録し、dsh-tool-pty を読み込みます
人間向けのコマンドを追加する	ctx.commands に登録します
バックグラウンドタスクを追加する	ctx.tasks に登録します
ファイルシステムへのアクセスやポリシーを追加する	ctx.fs プロバイダーを実装するか、fs/* ポリシーイベントをリッスンします
起動するプロセスを制限する	ctx.sandbox バックエンドを使用します
リクエスト、ツール、ターンをインターセプトする	agent/* または tools/* イベントを使用します。ターン停止イベントは agent/turn-stopping です
モデルから参照できるコンテキストを追加する	agent.inject() を呼び出します
UI またはエディターとの連携を追加する	ctx.agents を動作させ、session/event から描画します
Web クライアントの会話ノードを追加する	ConversationNodeDefinition とキー付きレンダラーを登録します
永続的なセッション状態を追加する	SessionEventMap を拡張し、ログから描画して再生します
実行中のセッションをフォークする	ctx.sessions.fork(source, boundary?, childSessionId?) を呼び出します
登録の適用範囲を1つの Agent に限定する	その Agent の agent.ctx を使用します

パッケージのチェックリスト

1. リポジトリ内パッケージを作成する — 公式モノレポ内に限り、packages/<group>/<pkg>/ を作成し、package.json、tsconfig.json、src/index.ts、README.md を配置します。対象のチェックアウトから packages/core/tools/package.json をコピーし、名前、説明、依存関係を調整します。対象バージョンの不変条件を維持してください。private: true、ルートパッケージの version、type: module、main: "lib/index.js"、types: "lib/types/index.d.ts"、exports["."] の types と default の両方が lib を指すこと、peer dependencies と development dependencies で同じ対象 Cordis 範囲を指定すること、すべての DSH peer dependency を development dependencies にも指定すること、対象 Schemastery パッケージを dependencies に指定すること、対象の files 構成とパッケージ固有のランタイム成果物を維持することが必要です。CLI アプリケーションパッケージにはビルド済みの bin を含めてください。宣言されていないソースや古い成果物を公開しないでください。対象のチェックアウトの相対インポート規約に従ってください。役割が一致する既存のグループを優先してください。新しいグループはコンテナーに限られ、パッケージはその直下に配置する必要があります。

2. リポジトリ内パッケージを登録する — 公式モノレポ内に限り、対象のチェックアウトの開発ガイドで指定されているとおりに、パッケージを Host または Client の集約先に追加します。通常のパッケージは、いずれか一方の集約先にのみ所属します。過去の例外やファイル一覧を、対象バージョンを確認せずにコピーしないでください。外部プラグインは Harness のルート設定を変更してはなりません。

3. 外部パッケージを作成する — 既存のパッケージマネージャーとビルドシステムを維持します。新しいプラグインの場合は、外部向けの命名ポリシーを適用し、検証済みの dsh-plugin.naming.json を含めてください。既存のプラグインの場合は、公開されているインターフェースを黙って改名しないでください。main、types、exports、files、任意の bin、パッケージ構成または Profile のメタデータ、およびパッケージ化した tarball の整合性を保ちます。すべてのランタイム依存関係を明示的に宣言し、コンパイルに必要な DSH peer dependencies を development dependencies にも指定します。リポジトリ内のテンプレートにあるという理由だけで、公開可能な外部プラグインを private にしたり、ワークスペースのバージョン範囲を指定したりしないでください。

4. パッケージ構成を選択する — 置き換え可能な機能の場合、サービス定義、プロバイダー、コンシューマーがそれぞれ独立して進化する場合に限り、別々のパッケージに分割します。単一目的のプラグインは、1 つのパッケージにまとめます。

5. リポジトリ内パッケージの README を作成する — 対象のモノレポで必要な場合に限り、パッケージ固有のサービス API、設定、イベント、拡張ポイント、設計上の注意事項を最初に記載します。README の末尾には、対象のチェックアウトにある標準の「モデル体験」の順序と「既知の制限事項」セクションを配置します。直接、条件付き、上限付き、ライフサイクル、補助モデルの各インターフェースをそれぞれ独立した H3 で説明し、その下に次の 3 つの H4 セクションを配置します。各 H4 セクションには散文の段落を 1 つ記載してください。パッケージが所有する安定したテキストを引用します。ツールの Schema インターフェースについては、生成されたツールカタログにすでに記載されている内容との差異のみを説明してください。「KV Cache への影響」では、追記のみの増加、安定した反復プレフィックス、以前のリクエストトークンの置き換え、独立したモデルリクエストを区別します。その後、再利用を無効にするパッケージの変更を列挙します。

   ## Model Experience
   
   ### Request Surface and Activation Conditions
   
   #### What the Model Sees
   
   Name the exact data-dependent field, link to the generated catalog with an anchor, or introduce the verbatim text below.
   
   ##### Place the Verbatim Field Text Here When Needed
   
   ```markdown
   Copy any stable system-prompt body or other long nongenerated literal exactly from source.
   ```
   
   #### Token Impact
   
   State whether the impact is fixed, conditional, retained, replaced, capped, or has zero direct token impact.
   
   #### KV Cache Impact
   
   Describe append-only, prefix-stable, replacement, or independent behavior, including exact conditions that may invalidate reuse.
   
   ## Known Limitations and Deferred Work
   
   - **Consumer-visible gap** — State the exact missing operation or condition, its consequence, and any maintainer constraint.
   

6. 検証する — 新しい外部プラグインの場合は、まず node <plugin-write-skill>/scripts/validate-names.mjs --manifest ./dsh-plugin.naming.json を実行します。--strict は、衝突耐性のあるコミュニティプロファイルの場合にのみ追加してください。検証に合格した後、ネットワークにアクセスできる場合は node <plugin-write-skill>/scripts/query-registry.mjs --manifest ./dsh-plugin.naming.json --harness-version <exact-semver> を実行し、クエリを利用できなかった場合は「利用可能」ではなく「不明」と報告します。プロキシ変数が設定されていて、Node の組み込み fetch でインデックスにアクセスできない場合は、references/registry-check.md に従ってください。Node 20-23 が自動的にそれらの変数を使用するかのように示してはなりません。その後、該当する以下の検証ブロック、重点チェック、変更された動作に必要なカバレッジゲートを実行します。

執筆時のルール

• すべての登録を副作用として扱います。ctx ヘルパーまたは破棄関数を指定した ctx.effect() を使って登録し、プラグインのアンロード時に、すべてのイベントリスナー、ツール、タイマー、その他のリソースをクリーンアップしてください。
• 新しい動作は、文書化された拡張ポイントに追加してください。agent-loop は変更しないでください。
• 公開サービスメソッドと型付きイベントには、@param と @returns を含む JSDoc を記述してください。対象となる Cordis の Events インターフェースを宣言マージして型付きイベントを定義し、@mode でディスパッチモードを記述してください。
• 調整可能な値をハードコードしないでください。デプロイ環境によって異なる可能性がある値は、cordis.yml で変更できる、検証済みの Config フィールドにしてください。
• モデルが認識するすべての内容は、セッションログから再構成できるようにしてください。
• 設定エラーは明示的に失敗させてください。参照先オブジェクトが見つからない場合に、黙って処理をスキップしてはいけません。プロセス内の型付き呼び出し元を信頼せず、パーサー、設定、配線、プロセスの各境界で検証してください。

検証

公式 Harness モノレポ内のパッケージでは、対象チェックアウトの最新のルートコマンドを使用してください。以下の名前はあくまで例です。実行前に、実際に存在することを確認してください。

pnpm install            # Register the workspace
pnpm run doc-sync
pnpm run constraints && pnpm run typecheck && pnpm run lint
pnpm run build && pnpm run hygiene

外部プラグインでは、独自のインストール、型チェック、テスト、静的チェック、ビルドの各コマンドを使用してください。公開可能な成果物をパッケージ化して内容を確認し、対象の DSH を正確に実行する隔離された Profile に読み込んでください。アップグレードの場合は、コールドスタートして、メッセージ → ツール → 返信のフロー、またはそれに相当する中核フローを 1 回完了してください。未検証のまま残るプロバイダー、オペレーティングシステム、UI、認証情報の各境界をすべて報告してください。

変更箇所に応じてテストを選択してください。ロジックにはユニットテストを実施し、リポジトリのカバレッジゲートを実行してください。プロバイダーの認証情報を利用でき、実行が許可されている場合は、実際の API を使ったエンドツーエンドテストを実施してください。モデル、プロトコル、またはユーザーに表示される動作には、認証情報を使わないスナップショットを使用してください。ユーザーに表示されるプラグインには、実際の構成を用いたテストを実施してください。パッケージに bin エントリがある場合は、ネイティブ Node 上でビルド済み成果物のスモークテストも必要です。これらのルールに従って必要最小限のテストを完了し、別の Skill は読み込まないでください。

リファレンスの一覧は references/README.md を参照してください。