PerryLink/dsh-plugin-guide

DeepSeek Harness プラグイン開発（dsh-plugin-guide）

公式資料に基づいて DeepSeek Harness プラグインを開発します。このスキルはワークフロー兼制約チェックリストです。事実の詳細はすべてナレッジベースの原文を参照し、記憶に頼って作り出しません。すべての「必須／禁止」条項は公式リポジトリ AGENTS.md、docs/、およびドキュメントサイトに基づいており、矛盾がある場合は公式原文が優先されます。

ナレッジベースの場所（順に探し、最初に存在するものを使う）

このスキルとナレッジベースは同一ディレクトリに配布されます（この SKILL.md があるディレクトリがナレッジベースのルートです）。パスはすべて相対パスです。guide/、references/ を伴わずにこのファイルだけをコピーした場合は、以下のフォールバックパスを探します：

1. このファイルと同じディレクトリ：./guide/（総合ガイド＋クイックリファレンス＋ドキュメントリンクインデックス）、./references/（調査レポートと公式ドキュメントの完全コピー references/official-docs/docs/）、./downloads/（元のダウンロード物、オプション）
2. ローカルのメインコピー：D:\deepseek-harness\Project\Plugins\dsh-plugin-guide\（サンプルパス。実際のインストール場所に合わせて調整）
3. 公式リポジトリのチェックアウト：D:\deepseek-harness\（docs/、vendor/cordis/、packages/、examples/）
4. オンライン：https://github.com/deepseek-ai/deepseek-harness 、 https://deepseek-harness.github.io/deepseek-harness/develop/basic/ 、 https://github.com/cordiverse/cordis

以降の相対パスは、特に断りがない限り上記の第 1 条（このスキルファイルがあるディレクトリ）を基準とします。

開発の前提（最初に必ず実施）

1. Cordis の概念をまだ読んでいない場合：references/official-docs/docs/cordis-primer.md を読む（5 つの概念、5 分）。手を動かして追いかけたい場合は references/official-docs/docs/cordis-tutorial/ の 01～07 を実行（API キーなしでも実行可能）。
2. guide/quick-reference.md（契約クイックリファレンス）＋ guide/plugin-dev-guide.md（完全なパス）を開く。公式／コミュニティドキュメントの URL 対照表は guide/links.md を参照。
3. ターゲット拡張ポイントを確認：references/official-docs/docs/architecture.md の「Where new behavior goes」表と references/official-docs/docs/cookbook/extension-cookbook.md の feature→mechanism 表を読む——新しい動作は必ずドキュメント化された拡張ポイントにフックし、agent-loop を変更してはならない。

必ず従うべきプラグイン契約（公式のレッドライン、一つずつ確認）

• プラグイン = モジュールが name ＋ apply(ctx, config)（＋オプションで inject: string[]）をエクスポート。依存するサービスは apply の前に準備完了。依存サービスが消えると自動アンロード、復旧後に自動リロード。
• 登録＝エフェクト：すべての貢献は ctx.effect() / ctx.on() / サービスの register() 経由で行う（disposer を返す）。決して手動で removeListener/clearInterval による後片付けをしない。
• waterfall リスナーは必ず next() を呼ぶ；呼ばない＝意図的なショートサーキット（インターセプトのセマンティクス）。emit/waterfall/parallel/serial/bail のセマンティクスはクイックリファレンス表を参照。
• モデル可視 ⇔ 記録済み：モデルリクエストに入るものはすべてセッションログから再構築可能でなければならない。新しくモデル可視な入力を追加する場合は、必ず新しい SessionEventMap セッションイベントを追加する。
• 型安全なイベント／サービスには declaration merging を使用（declare module '@deepseek-ai/cordis'）。イベントドキュメントには @mode を付記。
• 設定には Schemastery の Schema<Config> を使用（プレーンオブジェクト禁止）。不正な設定はロード時に明示的に失敗させる。調整可能なパラメータをハードコードしてはならない（判断基準：cordis.yml で変更できるか）。
• ツールは defineTool を使用：execute は output.schema で宣言された仕様通りの JSON 値のみを返す。exec.signal を尊重する。人間が読める内容は output.render に入れる。UI カードの presenter は純粋関数（I/O/タイマー/ランダム禁止）。
• 置換可能な能力は 3 層のシーム（Service Definition / Provider / Consumer）で設計する。事前に分解しない。
• パッケージング：バンドルマニフェスト `