DDS Plugin SDK

公開されている DDS Plugin SDK 1.2 をインストールし、ワークフロー、キャッシュ、ツールストリーム、LSP、および安定版 API を使用します。

以下の User workspace の例では、明示的に接続された顧客管理の開発ホストについて説明します。独立した SDK の例のホストとして WSL、コンテナー、サーバーから選択します。通常の Digital Design Studio Windows アプリは Windows 上でネイティブに動作します。選択した SDK ホストが検出、権限、プラグイン機能を管理し、マネージド Cloud エンジンジョブは独自の実行経路を使用します。

1. SDK をインストールする

DDS Plugin SDK 1.2.1 は、JavaScript API、TypeScript 宣言、言語プロバイダー、テーマ、ワークスペースツール、コマンドジョブを提供します。任意の永続ストアにより、ジョブ履歴、明示的な再試行、ソースの削除やプロセスの再起動後も残る検証済みのテキスト・バイナリスナップショットを追加できます。Node.js 22 または 24 を使用してください。安定版 SDK は、公式 GitHub リリースからインストールします。単独のコマンドプラグインには、インストール後に開発ツールを使用してください。

1.0.0 は、安定版 SDK API、18 のホスト適合性プロファイル、サポート・移行ポリシー、複合ワークロードの測定済み確認を公開します。新しいプラグインは >=1.0.0 <2.0.0 を使用します。これらの公開結果は、独立した SDK の API 適合性と機能動作を示します。

0.13.0 は、6 つの開発テンプレート、生成された型とスキーマ、決定的なテストシナリオ、任意のローカル診断を追加します。パッケージ化された SDK と生成されたプロジェクトはソースツリーの外で実行でき、合成リプレイとループバックデバッグは明示的に選択します。

0.12.0 は、スコープ付きの型付き設定と明示的な移行、実行スコープ内のシークレット参照、構造化されたコマンド入力・出力、ロケールカタログ、アクセシビリティーのメタデータを追加します。公開 SDK と独立したサンプルは、設定の競合、無効な入力、取り消された権限、翻訳フォールバックを確認します。独立した SDK ホスト API とサンプルから、これらの機能を使用します。

0.11.0 は、シグネチャヘルプ、遅延補完、範囲を限定したスニペット、レビュー付きの複数ファイル編集と名前変更、整形・コードアクション、セマンティックトークン、折りたたみ、ヒント、階層シンボルを追加します。提案、レビュー、現在の権限、条件付き適用は分離され、古いドキュメントの結果は表示も適用もできません。独立したホストとサンプルで、これらの公開 SDK 機能を使用します。

0.10.0 は、ブラウザーでのストリーミングダウンロード、選択したファイルのアップロード、混在転送キュー、Worker OPFS のチェックポイント復旧を追加します。転送では現在の権限、ファイルの識別情報、チャンク・全体のハッシュを確認し、バイト単位の進捗と検証済みの保存を分離します。ホストとブラウザーの保存先を明示的に選択して、これらの公開 SDK サンプルを実行します。

0.9.0 は、操作者が選択したローカルディレクトリに対し、スコープ付きプロジェクトツリー、ファイル名・テキストの検索、変更の監視を追加します。編集スナップショットと未保存の下書きを保持しながら、HTTP クライアントまたはプロジェクトヘルパーから使用してください。以下のプロジェクトサンプルでは、作成、検索、外部変更、競合処理を扱います。

Bash
mkdir hello-dds-plugin
cd hello-dds-plugin
npm init -y
npm install --ignore-scripts --save-exact "https://github.com/Altifigence/dds-plugin-sdk/releases/download/v1.2.1/altifigence-dds-plugin-sdk-1.2.1.tgz"

最初の診断サンプルは、ローカルのテストホストで信頼できるコードを使用します。テーマは、既存の DDS XML インポートを使用します。既存のツール連携については、プラグインとサードパーティーツールを参照してください。

2. 最初のプラグインを作成する

新しいプロジェクトに plugin.mjs を作成します。このプラグインはプレーンテキストドキュメントをチェックし、NOTE を含む各行に情報レベルの診断を報告します。

plugin.mjs

import { createDiagnosticsResult, definePlugin } from '@altifigence/dds-plugin-sdk';

export default definePlugin({
  manifestVersion: 1,
  id: 'hello-diagnostics',
  name: 'Hello Diagnostics',
  publisher: 'example',
  version: '0.1.0',
  protocolVersion: 1,
  entry: './plugin.mjs',
  capabilities: ['diagnostics'],
  permissions: ['document.read', 'diagnostics.publish'],
  supportedHosts: ['test-host'],
  license: 'Apache-2.0',
}, context => context.registerDiagnosticsProvider({languages: ['plaintext']}, {
  provideDiagnostics(request, {signal}) {
    signal.throwIfAborted();
    const diagnostics = [];
    const lines = request.snapshot.text.split(/\r\n|\n|\r/);
    for (let line = 0; line < lines.length; line++) {
      const character = lines[line].indexOf('NOTE');
      if (character !== -1) diagnostics.push({
        range: {start: {line, character}, end: {line, character: character + 4}},
        severity: 'info',
        code: 'todo',
        source: 'hello-diagnostics',
        message: 'Review this marked line before sharing the document.',
      });
    }
    return createDiagnosticsResult(request, diagnostics);
  },
}));

マニフェストはプロトコルバージョン 1、機能 diagnostics、ホスト test-host、権限 document.read と diagnostics.publish を宣言します。プロバイダーは、ドキュメントスナップショットと AbortSignal を受け取ります。診断範囲には、0 始まりの行番号と UTF-16 の文字オフセットを使用します。

3. ローカルで実行する

ファイル run.mjs を plugin.mjs の隣に作成します。プラグインを有効化し、ドキュメントを渡して診断を要求します。終了時には必ずホストを破棄してください。

run.mjs

import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';

const host = createTestHost();
try {
  await host.activate(plugin);
  host.setDocument({
    uri: 'memory:///hello.txt',
    languageId: 'plaintext',
    modelVersion: 1,
    workspaceRevision: 'example-1',
    text: 'Hello, DDS!\nNOTE: write a plugin.\n',
  });
  const result = await host.requestDiagnostics();
  console.log(`${plugin.manifest.name}: ${result.diagnostics.length} diagnostic`);
  for (const diagnostic of result.diagnostics) {
    console.log(`${diagnostic.severity} ${diagnostic.range.start.line + 1}:${diagnostic.range.start.character + 1} ${diagnostic.message}`);
  }
} finally {
  host.dispose();
}
Bash
node run.mjs

期待する出力(表示される行番号と列番号は 1 始まりです):

テキスト

Hello Diagnostics: 1 diagnostic
info 2:1 Review this marked line before sharing the document.

4. プラグインをテストする

このテストを plugin.test.mjs として保存します。診断範囲を確認し、ドキュメントを編集すると診断が消えることを確かめます。

plugin.test.mjs

import assert from 'node:assert/strict';
import test from 'node:test';
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';

test('reports a NOTE and clears it after editing', async () => {
  const host = createTestHost();
  try {
    await host.activate(plugin);
    const document = {
      uri: 'memory:///hello.txt',
      languageId: 'plaintext',
      modelVersion: 1,
      workspaceRevision: 'test-1',
      text: 'NOTE: write a plugin.\n',
    };
    host.setDocument(document);
    const result = await host.requestDiagnostics();
    assert.equal(result.diagnostics.length, 1);
    assert.equal(result.diagnostics[0].code, 'todo');
    assert.deepEqual(result.diagnostics[0].range, {
      start: {line: 0, character: 0},
      end: {line: 0, character: 4},
    });
    host.setDocument({...document, modelVersion: 2, text: 'Done.\n'});
    assert.equal((await host.requestDiagnostics()).diagnostics.length, 0);
  } finally {
    host.dispose();
  }
});
Bash
node --test plugin.test.mjs

テストは成功するはずです。独自の言語、キャンセル、無効な結果、大きなドキュメントのフィクスチャーを追加してください。以前のスナップショットの結果を拒否できるよう、ドキュメントのバージョンを最新に保ちます。

5. テーマを作成して適用する

このライト・ダークのパレットを theme.json として保存します。各パレットの 6 色は必須です。任意のセマンティックトークンで、検索、選択、HintsBox、GDS キャンバスをカスタマイズできます。省略したトークンには DDS の既定値を使用します。

theme.json

{
  "name": "Hello Ocean",
  "colors": {
    "light": {
      "backdrop": "#dbe8ef",
      "navigation": "#edf5f8",
      "tool": "#f3f8fb",
      "main": "#ffffff",
      "text": "#183b4e",
      "muted": "#486477"
    },
    "dark": {
      "backdrop": "#0c1922",
      "navigation": "#102430",
      "tool": "#17303e",
      "main": "#1c3949",
      "text": "#e8f4fb",
      "muted": "#adcadb"
    },
    "metrics": {
      "panelRadius": 16,
      "controlRadius": 8
    }
  }
}

ファイル export-theme.mjs をその隣に作成します。parseTheme は色データを検証し、serializeThemeXml は DDS XML バージョン 2 をエクスポートします。

export-theme.mjs

import { readFile, writeFile } from 'node:fs/promises';
import { parseTheme, serializeThemeXml } from '@altifigence/dds-plugin-sdk/themes';

const theme = parseTheme(await readFile('./theme.json', 'utf8'));
await writeFile('./hello-theme.xml', serializeThemeXml(theme), 'utf8');
console.log('Created hello-theme.xml');
Bash
node export-theme.mjs

このコマンドは hello-theme.xml を書き込み、Created hello-theme.xml を表示します。DDS で、プラグイン → テーマをインストール…を開き、XML を選択して、「適用」を選び、Hello Oceanを適用します。ライトとダークの外観を切り替え、両方のパレットを確認してください。

設定 → 一般 → 外観 → XMLを読み込む を使用することもできます。置き換える前に、現在のテーマを XMLを書き出す で保存してください。これにより、XML の外観データをテーマ設定にインポートします。

対応するトークンと寸法の全一覧は、テーマガイドにあります。Hello Ocean のサンプルには、完全なテーマ、そのままインポートできる XML、ローカル HTML プレビューが含まれています。

テーマ XML リファレンス

ダウンロードするファイルは、Hello Ocean XMLと、その編集可能な JSONです。XML には、完全なライト・ダークのパレット、各モードの全 28 個の任意の役割色、4 つの明示的な寸法値が含まれます。インポートする前に XML ファイルをローカルへ保存してください。これらのオリジナル SDK サンプルは Apache-2.0 を使用します。共有する際は、通知を保持してください。

現在のテーマをバックアップするには、まず 設定 → 一般 → 外観 → XMLを書き出す から始めます。ダウンロードした XML をインポートし、下書きを確認してから 適用 を選択します。変更を破棄 を選択すると、適用されたテーマが維持されます。ライト/ダークの外観を切り替えて両方のパレットを確認します。元に戻すには、組み込みテーマを選択するか、保存したコピーをインポートします。拒否されたインポートでは、現在のテーマが保持されます。

DDS、ALcad、共有エディター、プロジェクトナビゲーション、設定、ポップアップは、そのプロファイルの共有ワークベンチパレットを使用します。Cloud とデスクトップは同じテーマ形式を使用しますが、各プロファイルに個別にインポートしてください。gdsBackground は GDS キャンバスを独立して制御します。その他の設計キャンバス、レイヤー、シミュレーションの色には独自の設定がある場合があります。XML は、このテーマプロファイルのパレットと外観の数値設定を保持します。

要素

規則

<dds-theme version="2" name="Hello Ocean">

ルートは 1 つ。名前は前後の空白を除いて 1~80 UTF-16 コード単位。XML 全体は最大 65,536 UTF-8 バイト。

<palette mode="light">、<palette mode="dark">

両方とも必須で、それぞれに以下の 6 色が必要。

<tokens mode="light">、<tokens mode="dark">

任意の v2 上書き。省略した役割には、そのモードの DDS 既定値を使用。

<metrics>

任意の v2 数値上書き。

バージョン 1

両方のパレットのみ。既存の v1 ファイルには引き続き対応し、SDK エクスポーターは v2 を出力。

必須のパレットキー

用途

backdrop

ワークスペース外側の背景

navigation

プロジェクトナビゲーション

tool

ツールパネルと操作部品

main

メインワークスペースと設定

text

主なテキスト

muted

補助テキスト

任意の役割キー(28 個)

用途

search、searchText、searchPlaceholder

共有検索の背景、テキスト、プレースホルダー

searchBorder

互換性用フィールド。現在の共有検索欄には枠線なし

selection、selectionText

選択された行とテキスト

tabActive、tabInactive、tabText

エディターのタブ

rail、panelBorder、popover

ツールレール、パネルの境界、ポップアップ

focus

キーボードフォーカスの輪郭

success、warning、danger、info、aiBall

状態の色と AI ボールの背景

hintsBoxBackground、hintsBoxDetailsBackground

候補と詳細の背景

hintsBoxText、hintsBoxDetailsText、hintsBoxMutedText

候補、詳細、補助テキスト

hintsBoxSelectedBackground、hintsBoxSelectedText

キーボードで選択された候補

hintsBoxHoverBackground、hintsBoxHoverText

ポインターが置かれた候補

gdsBackground

GDS ビューアーのキャンバス背景

HintsBox は共有のコード候補機能です。その色は、カスタム → 詳細な色と形状 → ヒントボックスにあり、GDS の背景は、ディスプレイにあります。読みやすいコントラストになるよう、3 つの検索色をまとめて編集してください。この断片は v2 テーマの内側に置くものであり、2 つの完全なパレットは保持します。

XML v2 の断片

<tokens mode="dark">
  <color key="search" value="#214556"/>
  <color key="searchText" value="#e8f4fb"/>
  <color key="searchPlaceholder" value="#adcadb"/>
</tokens>

寸法値

許容値

現在の DDS 既定値

panelRadius

整数 0~24

14

controlRadius

整数 0~16

6

popoverRadius

整数 0~24

16

popoverOpacity

数値 0.6~1

0.72

寸法値は、<number key="popoverOpacity" value="0.9"/> の形式で <metrics> の内側に、単位なしで記述します。角丸の値はピクセルです。SDK は省略された寸法値を未設定のままにし、インストール済み DDS リリースが既定値を補います。一貫した外観にするには、値を明示的に設定してください。Hello Ocean は、意図的に 16、8、12、0.9 を設定しています。透明度を下げる設定や強制色の設定によって、最終的な表示が変わる場合があります。

各色は 6 桁の #RRGGBB である必要があります。アルファ値、CSS の名前、変数、URL、スタイルは拒否されます。重複したキーやモード、不明な要素・属性、名前空間、DTD、エンティティー、処理命令も拒否されます。XML 宣言とコメントは使用できます。インポートに失敗した場合は、ファイルサイズ、バージョン、2 つの完全なパレット、対応する値を確認し、変更していないバックアップで再試行してください。他のエディターのテーマは、この DDS 形式への変換が必要です。

6. 自分の環境でワークスペースを実行する

ホスト、SDK、プラグイン、ツールを、自分の WSL、コンテナー、サーバー環境で実行します。プロジェクトファイルは、選択したルート内に保持されます。独立した SDK クライアントは接続を通じてそれらを読み取り、編集します。プラグインのコードは自分の環境で動作し、独立した SDK クライアントはプラグインのメタデータとコマンド結果を受け取ります。

上記で作成した SDK プロジェクトに、このヘルパーを copy-workspace-example.mjs として保存します。サンプルのライセンスファイル配置を保持しながら、編集可能なサーバー、プラグイン、ツール、サンプルプロジェクトをコピーします。

copy-workspace-example.mjs

import { cp, copyFile, mkdir } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';

const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await mkdir('./user-host/examples', {recursive: true});
await cp(path.join(sdkRoot, 'examples/user-workspace'), './user-host/examples/user-workspace', {
  recursive: true, force: false, errorOnExist: true,
});
await copyFile(path.join(sdkRoot, 'LICENSE'), './user-host/LICENSE');
console.log('Created user-host');
Bash
node copy-workspace-example.mjs

サンプルプロジェクトは user-host/examples/user-workspace/project です。明示的に生成したトークンを使い、その環境でサーバーを起動します。

WSL / Linux / コンテナー

export DDS_WORKSPACE_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
node user-host/examples/user-workspace/server.mjs

PowerShell

$env:DDS_WORKSPACE_TOKEN = node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))"
node user-host/examples/user-workspace/server.mjs

サーバーは Workspace server: http://127.0.0.1:4777/dds/workspace/v1 と、ワークスペース ID、世代を表示します。クライアントのターミナルで、環境変数 DDS_WORKSPACE_TOKEN に生成したトークンを設定してください。これは操作者の資格情報であり、DDS Account トークンとは別です。サンプルサーバーは Ctrl+C で停止します。

同じプロジェクト内の別のターミナルで、DDS_WORKSPACE_TOKEN に同じシークレットを設定し、開発者用クライアントを実行します。

Bash
node user-host/examples/user-workspace/client.mjs http://127.0.0.1:4777

クライアントはサンプルファイルを一覧表示し、「プロジェクトファイルを検査」を、design.sv に対して実行します。JSON 結果には、実際の子プロセスが生成した tool: "module-counter" と modules: 1 が含まれます。サンプルファイルに注記を追加したい場合にのみ、クライアントコマンドへ --edit を追加してください。

自分のプロジェクトを使用するには、その絶対ディレクトリを server.mjs の最後の引数として渡します。サーバー、プラグインモジュール、インストール済みツールを、同じユーザー環境に置いてください。server.mjs はプラグインを明示的にインポートし、その名前付きバックエンドを固定の実行ファイルと引数に対応付けます。

server.mjs のバックエンド対応付け

'module-counter': createProcessBackend({
  executable: process.execPath,
  args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
  cwd: root,
  env: {},
})

この対応付けを、承認済みのインストール済みツールやカスタムバックエンドに置き換えます。ctx.workspace.readFile と writeFile は、選択したルートからの相対パスを使用します。ctx.backends.invoke("module-counter", input, {signal}) は、設定済みのバックエンド名だけを呼び出します。プロセスアダプターは、範囲を限定した JSON を stdin に送り、stdout に JSON を期待します。要求で指定されたシェルコマンドを使用せず、ホストの環境変数も継承しません。

リモートサーバーには、自分の認証済み HTTPS エンドポイント、またはローカルループバックで終端する非公開トンネルを使用します。コンテナーのポート対応付けや TLS は、自分の環境で設定してください。サンプルは既定でループバックにバインドしますが、バインドアドレスの変更で TLS が追加されるわけではありません。信頼されたプラグインとツールは、ホストプロセスの OS 権限で実行されます。

サーバー設定、オリジン、ファイルリビジョン、キャンセル、範囲を限定した結果については、ユーザーワークスペースのサンプルとワークスペースプロトコルを参照してください。

言語機能

SDK 0.7.0 は、補完、ホバー、定義、参照、フラットなドキュメントシンボルを提供します。マニフェスト v2 の機能に各機能を宣言し、権限 document.read と language.provide も宣言します。ホストは両方の権限を明示的に付与する必要があります。この完全なホバーのサンプルを、上記で作成したプロジェクトに language-demo.mjs として保存してください。

language-demo.mjs

import { definePlugin, createLanguageResult, createPluginHost } from '@altifigence/dds-plugin-sdk';

const plugin = definePlugin({
  manifestVersion: 2,
  id: 'hello-hover', name: 'Hello Hover', publisher: 'example', version: '1.0.0',
  protocolVersion: 1, entry: './language-demo.mjs', runtime: 'ui',
  capabilities: ['hover'],
  permissions: ['document.read', 'language.provide'],
  supportedHosts: ['test-host'], license: 'Apache-2.0',
  source: {visibility: 'open', licenseFile: 'LICENSE'},
}, context => context.registerLanguageProvider('hover', {languages: ['dds-demo']}, {
  provide(request, {signal}) {
    signal.throwIfAborted();
    return createLanguageResult(request, {text: 'A local LED signal.'});
  },
}));

const host = createPluginHost({grants: ['document.read', 'language.provide']});
try {
  await host.activate(plugin);
  host.setDocument({
    uri: 'memory:///demo.dds', languageId: 'dds-demo',
    modelVersion: 1, workspaceRevision: 'demo-1', text: 'led',
  });
  const result = await host.requestLanguage('hover', {position: {line: 0, character: 1}});
  console.log(result.data.text);
} finally {
  host.dispose();
}
Bash
node language-demo.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/hello-language/run.mjs

最初のコマンドは A local LED signal. を表示します。同梱の 2 つ目のサンプルは、let name = value を使う小さな学習用言語で 5 つの機能をすべて確認します。サンプル独自のプロバイダーが、その学習用言語を実装します。

機能

要求の入力

結果データ

completion

position

最大 500 個の {label, insertText, detail?, range?} 項目

hover

position

{text, range?} または null

definition

position

ワークスペース相対の {path, range} 位置、最大 500 件

references

position、任意の includeDeclaration

ワークスペース相対の {path, range} 位置、最大 500 件

document-symbols

{}

フラットな {name, kind, range, selectionRange, detail?} シンボル、最大 500 個

位置は、0 始まりの行番号と UTF-16 オフセットを使用します。補完の挿入はリテラルテキストであり、ホバーや詳細の文字列はプレーンテキストです。ホストは、位置をたどる前に対象ファイルと範囲を確認する必要があります。結果は、要求、プロジェクト・セッション、ドキュメントバージョンの識別情報を保持します。スナップショットの編集、キャンセル、タイムアウト、登録解除、破棄により、保留中の要求は終了し、遅れて届いた結果は破棄されます。

これらの API は、信頼された SDK ホスト内で動作します。独立したホストが登録済みの言語プロバイダーを呼び出します。LSP ブリッジには、明示的なプロセス設定を使用します。0.3.0 より古いホストは、新しい機能を拒否します。セレクター、上限、ライフサイクルの動作については、言語機能をお読みください。

プロジェクトの編集セッション

インポートするものは、createWorkspaceProject と applyTextEdits で、インポート元は @altifigence/dds-plugin-sdk/workspace-client です。ホストが createWorkspaceClient に接続し、ワークスペースの識別情報、通知、アクセスを確認した後、createWorkspaceProject(client) を呼び出します。プロジェクトは、正確な接続の関連付けを保持します。同じワークスペース ID と世代が返されても、再接続には新たに確認したプロジェクトが必要です。

API

動作

project.listFiles(path?, options?)

選択したワークスペースルート内の 1 つのディレクトリを一覧表示する。

project.openFile(path, options?)

ファイルを読み取り、その変更不能な内容とリビジョンを編集セッションに保持する。

project.createFile(path, content, options?)

ファイルが存在しない場合にのみ作成し、セッションを返す。

session.snapshot / session.state

最後に確認した {path, content, revision} と、現在の操作状態を読み取る。

session.save(content, options?)

サーバーのリビジョンが保持したリビジョンと一致する場合にのみ保存する。

session.saveEdits(edits, options?)

1 つのスナップショットに {range, text} の編集を適用し、リビジョンを確認した保存を 1 回行う。

session.reload(options?)

競合や結果が不確かな書き込みの後に、最新の内容とリビジョンを明示的に読み取る。

project.dispose() / session.dispose()

所有する作業をキャンセルする。プロジェクトを破棄しても、呼び出し元が所有するクライアントの接続は維持される。

インストール済みパッケージに含まれる完全な HTTP サンプルを実行します。独自の一時サンプルワークスペースを作成し、編集、競合する第 2 セッション、明示的な再読み込み、Unicode、再接続をテストした後、サーバーを閉じて一時ディレクトリを削除します。

Bash
node node_modules/@altifigence/dds-plugin-sdk/examples/project-session/run.mjs

期待する出力:Project session: HTTP edit, conflict, reload, Unicode and reconnect verified。サンプルのソースには、サーバーとクライアントの設定およびクリーンアップの全体が示されています。

オプションは signal と timeoutMs を受け付けます。試みた後に書き込みが失敗すると、needs-reload が残ります。UI の未保存の下書きを別途保持し、次の保存前に明示的に再読み込みしてください。SDK は、自動でマージや再試行を行いません。タイムアウト、キャンセル、応答の喪失は、サーバーが書き込みをコミットした後に起こる場合があります。要求をキャンセルしても、コミット済みの変更は残ります。各セッションでは、保留中の保存または再読み込みを 1 件許可します。

テキスト編集は、元のスナップショット、0 始まりの行番号、UTF-16 オフセットを使用します。重なり、サロゲートペアの分断、無効な範囲は、保存前に拒否されます。プロジェクトでは、開いている、または開きつつあるセッションを最大 64 個、1 回の保存あたり最大 500 件の編集を許可します。これらのヘルパーは、SDK 0.2.x サーバーを含む変更されていないワークスペースプロトコル v1 を使用し、ルート、保護パス、読み取り専用の制限を保持します。ライフサイクルとサイズ上限については、ワークスペースのプロジェクトをお読みください。

API リファレンス

プラグイン API は @altifigence/dds-plugin-sdk からインポートします。パッケージには、同じエクスポートに対する TypeScript 宣言が含まれます。

API

用途

definePlugin(manifest, activate)

マニフェストを検証し、アクティベーション関数を宣言する。

context.registerDiagnosticsProvider(selector, provider)

選択した言語 ID に対し provideDiagnostics(request, {signal}) を登録し、破棄可能な登録を返す。

createDiagnosticsResult(request, diagnostics)

要求の識別情報を使って、検証済みの結果を構築する。

context.registerLanguageProvider(kind, selector, provider) / createLanguageResult(request, data)

言語プロバイダーを登録し、検証済みの要求識別情報を持つ結果を構築する。

parseManifest(value)

マニフェストのバージョン、識別情報、権限、対応ホスト、エントリーモジュールを検証する。

parseDocumentSnapshot(value)

URI、言語、モデルバージョン、ワークスペースリビジョン、テキストを検証する。

parseDiagnosticsRequest(value) / parseDiagnosticsResult(value)

プロトコル、要求、スコープ、ドキュメント識別情報、診断フィールドを検証する。

PluginSdkError / ErrorCode / LIMITS / PROTOCOL_VERSION

型付きエラー、リソース上限、プロトコルバージョンを読み取る。

開発者用ホストのインポート元は @altifigence/dds-plugin-sdk/testing です:

テストホスト API

用途

createTestHost({scope, grants})

ローカルホストを作成する。両オプションは任意で、既定の付与ではドキュメントの読み取りと診断を許可する。

await host.activate(plugin)

プラグインを有効化し、破棄可能なアクティベーションを返す。

host.setDocument(snapshot)

現在のドキュメントを設定する。テキストを変更する際は、modelVersion を増やすか、workspaceRevision を変更する。

await host.requestDiagnostics({signal, timeoutMs})

対応するプロバイダーに診断を要求する。両オプションは任意。

await host.requestLanguage(kind, input, {signal, timeoutMs})

document.read と language.provide を明示的に付与して、宣言済みの言語機能を要求する。

host.deactivate(pluginId) / host.dispose()

登録を削除し、保留中の作業をキャンセルする。テスト終了時にホストを破棄する。

要求には requestId、プロジェクト・セッションの scope、および次のフィールドを持つスナップショットが含まれます。uri、languageId、modelVersion、workspaceRevision、text。この識別情報を保持するには、createDiagnosticsResult を使用します。結果には diagnostics 配列が含まれ、ソーステキストは省略されます。

エラーは code を公開し、これには invalid_contract、permission_denied、cancelled、stale_snapshot、provider_unavailable、budget_exceeded が含まれます。既定の要求タイムアウトは 5 秒で、受け付けるタイムアウトは 1~30,000 ms です。ドキュメントは 262,144 UTF-8 バイト、結果は診断 500 件までです。上限の全体については、LIMITSをお読みください。

SDK 1.0.0 は、個別のモジュールも提供します。Node 専用のワークスペースとパッケージ作成のインポートは、ユーザー環境で使用します。

インポート

API

@altifigence/dds-plugin-sdk

createPluginHost — v2 コマンド、明示的なワークスペース・バックエンドのポート

@altifigence/dds-plugin-sdk/themes

parseTheme, serializeThemeXml

@altifigence/dds-plugin-sdk/workspace-node

createNodeWorkspace, createProcessBackend, createWorkspaceServer, downloadJobBinaryArtifact, downloadStoredJobArtifact

@altifigence/dds-plugin-sdk/workspace-client

createWorkspaceClient, createWorkspaceProject, applyTextEdits, WORKSPACE_OBSERVATION_LIMITS; getFileCapabilities, getFileRevision, readFileIfChanged, watchFiles, watchJob, waitForJob; getBinaryArtifactCapabilities, listJobBinaryArtifacts, getJobBinaryArtifact, readJobBinaryArtifactChunk; getJobStorageCapabilities, listJobHistory, recoverJob, retryCommandJob; getArtifactStorageCapabilities, listStoredJobArtifacts, getStoredJobArtifact, readStoredJobArtifactChunk, readStoredJobArtifactText

@altifigence/dds-plugin-sdk/publishing

validatePluginPackage, packPlugin

@altifigence/dds-plugin-sdk/consent

createNotice, createPermissionGrant, isPermissionGranted, revokeConsentReceipt

@altifigence/dds-plugin-sdk/devtools

initPlugin, doctorPlugin, runPluginDev

@altifigence/dds-plugin-sdk/jobs

JOB_LIMITS, parseJobSnapshot, parseJobEvents、ジョブ型

@altifigence/dds-plugin-sdk/artifacts

BINARY_ARTIFACT_LIMITS, parseBinaryArtifactReference, parseBinaryArtifactChunk, decodeBinaryArtifactData

/job-storage / /job-storage-node

createNodeJobStore、永続ジョブ型

/job-history

parseJobHistoryQuery, parseJobHistoryPage、再試行の関係

/artifact-storage / /artifact-storage-node

createNodeArtifactStore、保存済み結果の型

プラグインをパッケージ化して公開する

同梱の、公開可能なプラグインから始めてください。SDK プロジェクトにこのヘルパーを保存し、そのファイルを新しい my-plugin ディレクトリへコピーします。

copy-publishable-example.mjs

import { cp } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';

const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await cp(path.join(sdkRoot, 'examples/publishable-plugin'), './my-plugin', {
  recursive: true,
  force: false,
  errorOnExist: true,
});
console.log('Created my-plugin');
Bash
node copy-publishable-example.mjs

自分のプラグインを説明するよう、plugin.json、plugin.mjs、disclosure.json とライセンスを編集します。開示内容は、マニフェストの発行者、プラグイン ID、バージョン、ライセンス、ソース公開範囲と一致する必要があります。配布する予定のファイルだけを dds-package.json に列挙してください。

dds-package.json

{
  "schemaVersion": 1,
  "files": [
    "plugin.json",
    "plugin.mjs",
    "disclosure.json",
    "LICENSE",
    "NOTICE"
  ]
}

サンプルを検証してパッケージ化します。

Bash
npx --no-install dds-plugin validate ./my-plugin
npx --no-install dds-plugin pack ./my-plugin --out ./dist

サンプルのメタデータを変更していない場合、pack は dist/example-hello-publisher-1.0.0.tgz と dist/example-hello-publisher-1.0.0.tgz.release.json を作成します。リリース JSON には、最終アーカイブの SHA-256、マニフェスト・開示のハッシュ、ファイル一覧が含まれます。配布前にこれらのファイルを確認してください。

アーカイブに入るのは、許可リストのファイル、dds-package.json、生成された npm メタデータだけです。検証はパッケージデータを確認し、パッケージ化は選択した配布経路で使うローカルアーカイブを作成します。CLI は非公開設定、キーファイル、リンクされたパスを拒否します。共有前に、選択したファイルの内容を確認してください。

配布経路

提供するもの

公開 GitHub リリース

バージョン付きアーカイブ、その外部リリース JSON、ライセンス、必要なソースへのアクセス。

非公開レジストリまたはダウンロード経路

同じバージョン付きファイル、対象利用者の認可、実際のプラグイン利用条件。

マニフェスト v2 は runtime、要求する権限、source: {visibility, licenseFile, repository?} を宣言します。公開範囲を open または closed に設定し、実際のライセンスファイルを含めます。自分が所有するコードには、オープンソースまたはプロプライエタリの条件を使用できますが、適用される SDK と依存関係の通知は引き続き有効です。受信者は実行可能な JavaScript とともに、宣言されたソース公開範囲とライセンスのメタデータを受け取ります。

開示フィールドと配布要件については、公開とライセンスに従ってください。生成したアーカイブとリリース JSON を、選択した GitHub リリース、非公開レジストリ、ダウンロード経路で配布します。

1.2.1 の CLI は、新しいプラグインパッケージに >=1.0.0 <2.0.0 を記録します。過去の 0.3~0.13 と、正確な 1.0.0-rc.1 のアーカイブは、元の peer 条件を保持します。安定版へのインストールには、新しいプラグインバージョンを検証して再パッケージ化してください。発行者は再パッケージ化の際に、宣言した peer 範囲とリリースメタデータを明示的に更新します。

ダウンロードしたプラグインを検証する

SDK 1.2.1 は、公開された正確な 0.3.x~0.13.x、RC1、現在の安定版プラグインメタデータに対して dds-plugin verify を提供します。.tgz と .tgz.release.json をまとめて保管してください。検証では元の peer 条件を保持します。上記で作成したパッケージを確認します。

パッケージ化したサンプルを検証する

npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz

このコマンドは、範囲を限定した gzip/tar 構造、正確なファイル許可リスト、各ファイルのハッシュ、マニフェスト、開示、ライセンス、生成された npm メタデータを確認します。リンク、安全でないパスや重複パス、余分なファイル、npm フック・依存関係を拒否します。ローカルアーカイブをその場所で読み取り、データとして検証します。成功時は JSON の受領記録を表示し、拒否時はコード 1 で終了します。

名前が変更されたダウンロードには、--metadata と、対応するリリース JSON を使用します。信頼できるリリース経路から期待する SHA-256 を独立して入手し、--sha256 で渡して、選択したバイト列を固定します。Node API も同じオプションを公開します。

verify-release.mjs

import { verifyPluginArchive } from '@altifigence/dds-plugin-sdk/publishing';

const receipt = await verifyPluginArchive(process.argv[2], {
  metadataPath: process.argv[3],
  expectedSha256: process.argv[4],
});
console.log(receipt.pluginId, receipt.pluginVersion, receipt.artifact.sha256);

コマンド verify-release.mjs を、アーカイブパス、メタデータパス、独立して入手した 64 文字の小文字ハッシュを 3 つの引数として実行します。checksumPinned は、指定したハッシュが一致する場合にのみ true になります。上限は、圧縮入力 12 MiB、ファイル内容 10 MiB、1 ファイル 4 MiB、256 ファイル、外部メタデータ 256 KiB です。

対となるメタデータは、一致するハッシュでアーカイブの整合性を記録します。両ファイルを置き換えると新たに一致する組を作れるため、期待するダイジェストは独立して信頼できるリリース経路から取得します。発行者と実行内容を確認し、ホスト権限を明示的に付与し、対象インストールの適合性をそれぞれ確認します。受領記録は、その呼び出し時に読み取ったバイト列を示します。使用前にファイルが変わる可能性がある場合は、実際のバイト列を再確認してください。既存の 0.3.x/0.4.x/0.5.x/0.6.x/0.7.x/0.8.x/0.9.x/0.10.x/0.11.x のプラグインアーカイブは、強化されたファイルポリシーを満たす限り引き続き検証できますが、1.0 へのインストールには発行者の検証と再パッケージ化が必要です。必要に応じて、新たに除外対象になったファイルを削除し、新しいプラグインバージョンを公開してください。この検証機能は DDS プラグインパッケージ用です。SDK の npm tarball は、リリースの SHA-256 を使用します。

参照する資料は、アーカイブの検証と、完全なパッケージ化・検証・改ざんのサンプルです。

権限、ライセンス、データ利用

マニフェストで要求する権限と、操作を有効にするホストの権限付与は別です。有効化する前に、プラグインの識別情報、バージョン、実際のライセンス、ワークスペースの範囲、要求する権限をユーザーに提示してください。バックエンドへの接続前に、その操作者、送信されるデータ、目的、保持、プライバシー通知を説明してください。

記録

意味

pluginPermissionGrant

正確なパッケージ、ワークスペース、権限に対するホストのアクセス判断。

noticeAcknowledgement

ユーザーが情報通知を確認した。

pluginLicenseAcceptance

ユーザーが、プラグイン発行者の実際の利用条件を受け入れるかどうかを選択した。

optionalPersonalDataConsent

任意の処理が同意を根拠とする場合の、別の選択。

SDK ワークスペースの承認は、技術的なアクセス判断です。プラグイン利用条件の受諾と任意の個人データ処理への同意は、それぞれの選択と記録種別で保存します。SDK は Apache-2.0 ライセンスと通知に従って使用します。

ホストの開発者は、移植可能な非同期ヘルパーを使い、バージョン付き通知を保持できます。例えば、これを notice.mjs として保存し、node notice.mjs を実行します。

notice.mjs

import { createNotice, parseNotice } from '@altifigence/dds-plugin-sdk/consent';

const notice = await createNotice({
  id: 'greet-data-use',
  version: '1.0.0',
  locale: 'en',
  purpose: 'Explain the greet command',
  text: 'The greet command uses the name you enter to return a greeting. It does not read project files or contact another backend.',
});
await parseNotice(notice);
console.log(notice.text);
console.log(`Notice text SHA-256: ${notice.contentSha256}`);

createPermissionGrant は、要求された権限の部分集合を、マニフェスト v2、成果物とマニフェストのハッシュ、ワークスペース世代、ホストの識別情報、通知、有効期限に関連付けます。isPermissionGranted は、ホストが提供した現在の識別情報と取り消しイベントを評価します。revokeConsentReceipt は別のイベントを作成します。その後、ホストは将来の認可済み呼び出しを停止する必要があります。

これらのヘルパーはローカルの記録を検証します。実際のユーザー選択、識別情報、保存、強制適用はホストが提供します。正確なフィールドについては、権限と同意を、明示的な許可・拒否・取り消しの実演については、対話型の権限サンプルをお読みください。ホストが発行者の利用条件と受諾記録を管理します。

ソース、リリース、貢献

ソースの入手先である、公式 SDK リポジトリには、ソース、スキーマ、サンプル、契約テストが含まれています。公開済みサンプルと SDK テストをソースから実行するには、次を実行します。

Bash
git clone --branch v1.2.1 --depth 1 https://github.com/Altifigence/dds-plugin-sdk.git
cd dds-plugin-sdk
npm ci
npm test
npm run example
npm run example:language
npm run example:project
npm run example:verify
npm run example:jobs
npm run example:observe
npm run benchmark:files
npm run example:artifacts
npm run benchmark:artifacts
npm run example:durable-jobs
npm run example:stored-artifacts

SDK のバグは、GitHub Issuesで、SDK バージョンと最小の再現手順を添えて報告してください。SDK は Apache-2.0 でライセンスされています。リポジトリのライセンスと通知を参照してください。バージョン付きアーカイブとリリースノートには、リリースページを使用します。

このリポジトリは、意図的に公開された開発者 SDK です。リリースの SDK ファイル、スキーマ、サンプル、通知は、公開範囲に従って構成されます。パッケージ確認は、公開された正確なファイル一覧を強制し、既知のシークレットや非公開パスのパターンを拒否します。パターン確認と合わせて、実際のリリース内容も確認してください。

セキュリティ更新とホストの上限

ワークスペースサーバーと SDK クライアントの両方を、0.3.2 以降に更新してください。更新されたファイル確認と要求上限を有効にするには、サーバーの更新をインストールしてください。アップグレードしたホストを再起動し、新しい世代を確認して、ワークスペースを使用する前に再承認を得てください。

Node ワークスペースホストは、保護ファイルや選択ルートの外のファイルを別名で参照できるハードリンクを拒否します。意図的に共有したプロジェクトファイルは、リンクが 1 つの通常ファイルにコピーしてください。資格情報ストアである .netrc、_netrc、.git-credentials、.gnupg、.kube、.docker、追加の SSH キー名、Windows のデバイス別名もブロックされます。パッケージ化とダウンロード検証では、対応する資格情報名のポリシーを適用します。

サーバーリソース

上限

同時に受信する本文

16。これを超えるアップロードは、ディスパッチ前に HTTP 429 を受け取る

実行中の要求

64。キャンセルは別のディスパッチ経路を使用

接続数 / ソケットごとの要求数

128 / 128

要求と応答 / ファイル内容

1,600,000 / 262,144 UTF-8 バイト

クライアントは、期限到達またはキャンセル時に、読み取られていない拒否応答や停止したストリームをキャンセルします。書き込み開始後のタイムアウトでは、その結果が不確かになる場合があります。再試行前にファイルを読み直してください。明示的なパス除外と合わせてファイル内容を確認し、信頼されたプラグインコードがホストプロセスの OS アクセス権で動作することを考慮してください。ホストの展開時には、セキュリティアップグレードガイドとワークスペースの上限を使用してください。

開発ツール

上記の SDK 1.2.1 をインストールした後、独立したコマンドプラグインプロジェクトを作成します。生成ファイル用の新しい保存先を選びます。スキャフォールド生成後に、依存関係のインストールとプラグイン実行を明示的に行います。生成されたスキャフォールドには、コマンド、テスト、マニフェスト、開示、固定された SDK 依存関係、および Apache-2.0 LICENSE/NOTICE が含まれます。

Bash
npx --no-install dds-plugin init ../my-command-plugin --id my-command-plugin --publisher example
cd ../my-command-plugin
npm install --ignore-scripts
npm run doctor
npm test
npx --no-install dds-plugin dev . --trust-local-code --command greet --input '{"name":"Ada"}'

Doctor は、プラグインをインポートせずにメタデータを読み取り、Node、SDK の解決、マニフェスト、ライセンス、開示、許可リストのパッケージファイルを確認します。エラーでは終了ステータス 1 となり、サンプルの発行者・サポート値は警告となります。配布前にそれらの値を置き換え、ライセンスを確認してください。

Bash
npx --no-install dds-plugin doctor . --json
npx --no-install dds-plugin dev . --trust-local-code --watch
npx --no-install dds-plugin dev . --trust-local-code --job --command greet --input '{"name":"Ada"}'
npm run pack:plugin

Dev には --trust-local-code が必要です。信頼されたローカルコードのインポート・有効化を子プロセスで実行し、許可リストのファイルと dds-package.json だけを監視します。各実行には期限と stdout/stderr の 256 KiB 上限があります。Ctrl+C は監視を止め、プロセスツリーをクリーンアップします。子プロセスはユーザーの OS 権限と継承した環境で動作します。既定のテストホストはドキュメントの読み取りと診断を提供します。ワークスペース・バックエンド連携には、別のワークスペースホストと明示的な権限を設定してください。

--job を使用するとジョブの進捗・ログを表示できます。--timeout-ms で、通常のコマンドでは最大 30 秒、ジョブでは最大 30 分を設定します。Node API は /devtools の initPlugin、doctorPlugin、runPluginDev です。監視の動作とリソースのクリーンアップについては、開発ツールのガイドを参照してください。

長時間実行するコマンドジョブ

通常の要求期限を超えてコマンドを実行するには、0.4.0 SDK ホスト・サーバーで jobs: true を有効にします。ジョブは既定で無効です。進捗、名前付きバックエンドのログ、ハッシュで固定された結果ファイルを報告する、完全なローカル HTTP サンプルを試してください。

Bash
node node_modules/@altifigence/dds-plugin-sdk/examples/command-jobs/run.mjs

期待する出力:Command job: progress, backend log and pinned result file verified. コマンドハンドラーは {signal, job} の任意の job を受け取ります。reportProgress、log、addArtifact、invokeBackend を提供します。既存の workspace.read/write と backend.invoke の権限付与が引き続き適用され、任意の実行ファイルパスは受け付けません。

JavaScript
await client.connect();
if (!(await client.getJobCapabilities()).enabled) throw new Error("Jobs are unavailable");
const jobId = crypto.randomUUID(); // Save before sending.
let job = await client.startCommandJob(pluginId, "analyze", {}, artifactSha256, {jobId, timeoutMs: 300_000});
let after = 0;
for (;;) {
  const page = await client.getJobEvents(jobId, after);
  after = page.nextCursor;
  if (page.dropped) console.log("Expired events:", page.dropped);
  for (const event of page.events) console.log(event.kind, event.data);
  job = await client.getJob(jobId);
  if (job.state !== "running" && !page.hasMore && after >= job.lastSequence) break;
  await new Promise(resolve => setTimeout(resolve, 250));
}
if (job.state === "succeeded") {
  const file = await client.readJobArtifact(jobId, "report");
  console.log(file.content);
}

ポーリングの断片は、接続済みクライアントと、report を登録する設定済み analyze コマンドを前提とします。開始前にジョブ ID を保存してください。ポーリング要求の切断や中止は実行をキャンセルしません。同じ世代に再接続し、明示的に照会・キャンセルします。同じ ID と入力で開始を再試行すると、保持済みジョブを再利用します。引数の変更は競合となります。ホストの再起動ではメモリー内の記録が失われます。再起動後にコミット済みメタデータを復旧するには、以下の別の 0.8 永続ストアを有効にしてください。

状態は running、succeeded、failed、cancelled、timed_out です。キャンセル後に遅れて届いた出力は破棄されますが、副作用は元に戻りません。終了処理が確定していないプロバイダーは、スロットを保持します。上限は、同時ジョブ 4 件、保持済み記録 32 件、ジョブごとの入れ子操作 32 件、ジョブごとのイベント 256 件・64 KiB、ページごとのイベント 64 件、成果物 16 個です。実行時間は既定で 5 分、最大 30 分です。終了状態が確定した記録は、最後のイベントから 15 分後に期限切れになります。

テキスト結果ファイルは、ワークスペース相対の UTF-8 で、最大 256 KiB です。ホストは既存の付与権限を使って読み取り、SHA-256 を記録し、後の読み取り時にバイト列が変わっていれば拒否します。バイナリや大きなシミュレーション出力には、任意のバイナリ結果 APIを使用します。キャンセル後に部分的な成果物が残る場合は、ジョブの最終状態で成功を確認します。旧 0.3 クライアントは既存の v1 メソッドを使用します。独立した SDK のジョブには、クライアントとホストの両方で 0.4 以降を使用します。正確な契約と上限については、ジョブを参照してください。

ワークスペースのファイルを監視する

project.watchFiles() は、明示的な相対ファイルパス 1~16 個をサンプリングします。SDK 1.0.0 は、対応ホストではリビジョンのみの要求を使用し、旧ホストでは既存の範囲を限定した読み取りを使用します。サンプルは、接続済みでホストが承認したクライアントを前提とします。外部エディターで design.sv を変更するとループが終了します。保持した編集スナップショットは変わりません。

JavaScript
import {createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
const project = createWorkspaceProject(client);
const edit = await project.openFile('design.sv');
const original = edit.snapshot;
try {
  for await (const change of project.watchFiles(['design.sv'], {intervalMs: 1000})) {
    console.log(change.kind, change.path, change.previousRevision, change.revision);
    if (change.kind !== 'initial') break;
  }
  console.log(edit.snapshot === original);
} finally { project.dispose(); }

イベントは変更不能な {kind, path, previousRevision, revision} です。最初のサンプルは initial を出力し、その後の変更は created、changed、deleted を出力します。存在しないファイルの revision は null です。includeInitial: false は通知せずに基準状態を記録し、リビジョンが同じならイベントは生成しません。削除を意味するのは not_found だけです。権限、保護パス、サイズ、トランスポートのエラーは監視を終了します。

UI の未保存のテキストは別途保持します。監視は下書きと編集スナップショットを保持します。呼び出し元が再読み込み、マージ、保存を明示的に選択し、保存時は保持したリビジョンで競合を確認します。パスは順に 1 つずつ読み取ります。サンプリングによる監視のため、中間の変更がまとめられる場合があります。サンプリング対象のファイルパスを明示的に選択し、各イベントで観測したパスとリビジョンを確認します。読み取り専用と書き込み可能の両方のサーバーで、既存のルート、ファイルサイズ、保護パスの制限が適用されます。

ファイルとジョブの両方の監視は、最初の next() で開始し、利用側が一時停止中はバックグラウンドでページを取得しません。クライアントごとに、稼働中の監視を合計最大 8 個共有します。保留中の next() は 1 つまでで、同時読み取りは conflict で失敗します。break または return() は保留中の読み取りを停止します。プロジェクトの破棄は、そのファイル監視を停止し、切断・再接続・破棄は、すべての旧監視を無効にします。AbortSignal は cancelled で監視を終了し、遅れた応答から結果が返されることはありません。

intervalMs は 250~60,000 ms(既定 1,000)で、ファイルの巡回間またはアイドル状態のジョブ読み取り間に適用します。requestTimeoutMs は要求ごとに 1~30,000 ms で、既定はクライアントの期限です。合計 timeoutMs は最初の next() から 1~1,800,000 ms で、利用側の一時停止を含みます。ファイルには既定で合計タイムアウトはなく、ジョブは既定で 30 分です。期限到達は budget_exceeded を報告し、スロットを解放します。これらの上限は WORKSPACE_OBSERVATION_LIMITS としてエクスポートされます。

Bash
node node_modules/@altifigence/dds-plugin-sdk/examples/workspace-observation/run.mjs

期待する出力:Workspace observation: file changes, retained draft and resumed job verified. 完全なサンプルは独自の一時ワークスペースを作成し、ファイル変更、下書きの競合、明示的なジョブ再開を確認します。すべてのオプションと存続期間の規則については、監視を参照してください。

ジョブを監視して再開する

client.watchJob() は jobs.events/get で既存のジョブを追跡し、waitForJob() はその終了状態のスナップショットを返します。この断片は、接続済みクライアント、明示的に開始された jobId、保存済み savedCursor(または undefined)を前提とします。ジョブ開始前に getJobCapabilities() を確認してください。監視は、コマンドの開始、再試行、キャンセルを行いません。

JavaScript
let after = savedCursor ?? 0;
for await (const update of client.watchJob(jobId, {after, intervalMs: 1000})) {
  if (update.dropped) console.log('Expired events:', update.dropped);
  for (const event of update.events) console.log(event.kind, event.data);
  console.log(update.snapshot.state, update.snapshot.progress);
  after = update.nextCursor;
}
const result = await client.waitForJob(jobId, {after, timeoutMs: 120000});
if (result.state === 'succeeded') console.log(result.result);
else console.log(result.state, result.error.code);

凍結された各更新には、snapshot、events、after、nextCursor、dropped、hasMore が含まれます。各ページで最大 64 件のイベントを処理し、処理後に nextCursor をジョブ ID とワークスペースの識別情報とともに記録します。dropped は、期限切れの履歴を報告します。スナップショットがイベントページより新しい場合があります。hasMore が true の間は、終了状態のスナップショットも読み続けてください。反復処理は最終ページ後に終了します。waitForJob() は同じページを最後まで読み取り、succeeded、failed、cancelled、timed_out を返します。解決した Promise をすべて成功と扱わず、state を確認してください。

反復処理の停止やタイムアウトは、監視だけを停止します。サーバーコマンドは、終了するか cancelJob() が明示的に呼び出されるまで続行します。ホスト承認済みの再接続後に、同じワークスペース ID と世代を確認し、保存したジョブ ID とカーソルで新しい監視を作成してください。識別情報が同じでも、古い監視は無効です。不足・期限切れのジョブやトランスポートの失敗は、再送信なしで報告されます。メモリー内のジョブはホスト再起動後に残りません。永続的な復旧は、新しい接続で recoverJob() を使用します。ライブ監視は、世代をまたいで再開しません。

既存の v1 hello とジョブ契約は変更されません。ファイル監視は、0.3.2/0.4/0.5 ホストでフォールバックします。ジョブ監視には、有効化された 0.4 以降のホストが必要です。監視前にホストのジョブ機能を確認します。非対応の応答は要求を終了し、コマンド実行の明示的な制御を維持します。この監視機能は独立した SDK クライアントとホストで動作します。監視と互換性を参照してください。

ファイルリビジョンと条件付き読み取り

SDK 0.6.0 は、接続済みクライアントに getFileCapabilities()、getFileRevision(path)、readFileIfChanged(path, knownRevision) を追加します。リビジョンの読み取りは、内容なしの {path, revision} を返します。一致する条件付き読み取りは {path, revision, notModified: true} を返し、変更された内容は notModified: false と content を返します。現在の内容には knownRevision: null を渡します。存在しないファイルは not_found で拒否されます。

JavaScript
let cached = await client.readFile('design.sv');
const current = await client.readFileIfChanged(cached.path, cached.revision);
if (!current.notModified) cached = current;
console.log(cached.content);
const metadata = await client.getFileRevision('design.sv');
console.log(metadata.revision);

すでに接続され、認可済みのクライアントを使用してください。未保存の下書きは、このキャッシュと分けて保持します。条件付き読み取りは、1 つのファイルスナップショットをハッシュ化して返しますが、その後の読み取りで別の変更を観測する場合があります。返された内容に属するリビジョンで保存してください。これらの呼び出しは、編集セッションのスナップショットを更新したり、下書きをマージしたりしません。変更なしの応答には content フィールドがありません。変更後が空のファイルには content: “” があります。

ファイル監視は、対応する場合、リビジョンのみの読み取りを自動で使用します。任意の fs.capabilities、fs.revision、fs.readIfChanged メソッドは、厳密な v1 hello と元のファイルメソッドを保持します。既知の 0.6 未満の SDK ワークスペースホストは、検出を試みず fs.read を使用します。その他のホストは、検出に応答するか、正しく対応付けられた unsupported エラーを返す必要があります。false の各機能は、それぞれ独自の範囲を限定した全体読み取りフォールバックを選びます。旧サーバーの応答は、引き続き内容全体を転送します。

機能は現在の接続に対してのみキャッシュされ、再接続や取り消しでリセットされます。無効な応答、パス・リビジョンの不一致、権限、認証、トランスポートの失敗、タイムアウトは、フォールバックを引き起こしません。提供されると示された操作が後で失敗しても、知らせずに機能を縮小しません。AbortSignal は検出と読み取りを対象とし、timeoutMs は各 HTTP 要求に適用されます。接続の変更は、古い操作を無効にします。

サーバーは、各サンプルに対し、保護付きのファイル全体の読み取りと SHA-256 計算を引き続き行います。UTF-8 検証、262,144 バイトの上限、保護パス・リンクの確認も維持されます。各サンプルの保護付きディスク読み取りと SHA-256 計算を維持しながら、ネットワーク応答のバイト数を削減します。ローカルの Node 22.23.1 Windows 測定では、変更なしの 200,000 バイトのサンプル 20 個について、全体読み取りが 4,003,974 バイト、リビジョンが 3,867 バイト(99.903% 減)、条件付き読み取りが 4,247 バイト(99.894% 減)を返しました。検出は含みますが、HTTP ヘッダー、TLS、最初の hello・内容の基準値は含みません。フィクスチャーを再現するには、チェックアウトで npm run benchmark:files を実行してください。

SDK は安定版の 1.x API を提供します。既存の 0.3.2、0.4、0.5、0.6 クライアントは、0.7 ホストで元の API を保持します。接続済みの独立した SDK クライアントから、このリビジョン API を使用します。完全な契約と移行規則については、ファイルリビジョンを参照してください。

大容量およびバイナリのジョブ結果

SDK 0.7.0 は、任意のバイナリ結果ファイル拡張を追加します。信頼されたコマンドが既存のワークスペースファイルを登録し、ホストが SHA-256 と長さを記録します。クライアントは 1 チャンク最大 64 KiB を読み取り、Node ダウンローダーは部分ファイルを再開して出力全体を検証します。記録されるファイルの最大値は 1 GiB です。既存の 256 KiB の UTF-8 ファイルとテキスト成果物 API は、その上限を維持します。

サーバーが所有するプラグインホストで jobs: true と binaryArtifacts: true を有効にします。両方とも既定は false です。明示的なトークン、操作者の通知、確認済みのプラグイン成果物ピン、有効な workspace.read の付与権限を保持してください。以下は、上記のワークスペース設定を基にします。読み取り専用ワークスペースでも、操作者が設定したツールで生成済みのファイルを登録できます。

JavaScript
const server = await createWorkspaceServer({
  root, workspaceId, token, notice,
  plugins: [{plugin, artifactSha256}],
  grants: ['workspace.read'],
  jobs: true, binaryArtifacts: true, writable: false,
});

startCommandJob で開始したコマンド内で結果を登録します。登録では、64 KiB バッファーを使い、既存のファイルをストリーミングで SHA-256 に通します。参照はそのソースファイルを指し、変更不能なコピーではありません。保護パス、トラバーサル、リンク、通常ファイル以外は拒否されます。その後のソース変更は conflict で失敗します。

JavaScript
context.registerCommand({id: 'collect', title: 'Collect trace'}, async (_, {job}) => {
  if (!job) throw new Error('Start this command as a job');
  const artifact = await job.addBinaryArtifact({
    id: 'trace', path: 'outputs/trace.fst', label: 'Simulation trace',
  });
  return {artifactId: artifact.id};
});

すでに接続され、認可済みのクライアントと、既存のジョブ ID を使用します。保存先は、呼び出し元が管理する実在する既存ディレクトリ内の絶対パスです。ヘルパーは destination + “.dds-part” を書き込み、既存の最終ファイルの上書きを拒否します。

JavaScript
import {downloadJobBinaryArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';

const capabilities = await client.getBinaryArtifactCapabilities();
if (!capabilities.enabled) throw new Error('Binary results are not enabled');
const reference = await client.getJobBinaryArtifact(jobId, 'trace');
const receipt = await downloadJobBinaryArtifact(client, reference, {
  destination: absoluteDownloadPath, resume: true,
  signal: abortController.signal,
  onProgress({receivedBytes, totalBytes}) {
    console.log(receivedBytes, totalBytes);
  },
});
console.log(receipt.verified, receipt.revision);

{jobId, scope, artifact} の参照全体を保持してください。中断後は、同じホスト世代に明示的に再接続し、その参照と resume: true でヘルパーを再度呼び出します。保存済みの先頭部分を再ハッシュ化し、不足する末尾部分だけを要求します。最終ファイルとして確定する前に、各チャンク、受信ストリーム全体、実際のステージングファイルの SHA-256 を確認します。最終的な verified: true の受領記録が完了を確認し、同期的な進捗コールバックは未検証のままです。破損した部分ファイルは、明示的に削除するか、新しい保存先が必要です。

listJobBinaryArtifacts(jobId) は、既存のテキスト結果とは別に、記録されたバイナリメタデータを返します。readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) は、チャンクの SHA-256、正確な範囲、EOF マーカーを含む正規の base64 を返します。/artifacts の decodeBinaryArtifactData は Uint8Array のバイト列を返します。ブラウザー側の利用者は、ファイル全体のハッシュを自分で検証する必要があります。個々のチャンクの確認だけでは、組み立てた出力が参照と一致することを証明できません。

バイナリとテキストの結果は、ジョブごとに 16 のスロットと ID 名前空間を共有します。バイナリの取り込み・読み取り操作はホスト・ワークスペースごとに 4 つ、Node のダウンロードはプロセスごとに 4 つまでです。Node ダウンロードの timeoutMs は合計期限で、既定の最大は 30 分です。requestTimeoutMs は既定 5 秒、最大 30 秒です。最終ファイルとしての確定には、NTFS や ext4 のようなハードリンク対応が必要です。呼び出し元が管理するディレクトリと信頼できる書き込み元を使用します。ファイルシステムの確認はホストプロセスの OS 権限で動作します。

任意の artifacts.capabilities、artifacts.list、artifacts.read は、既存の v1 hello、ジョブスナップショット、イベントを維持します。0.7 未満のホストは拡張が無効と報告し、クライアントはその機能結果と読み取り・実行の明示的な制御を維持します。認証、不正な応答、トランスポートのエラーは、エラーのままです。再接続、取り消し、ジョブの期限切れ、ホスト世代の変更は、古い操作を無効にします。ジョブの保持は、終了したジョブの最後のイベント後 15 分間、メモリー内で行われます。キャンセルされたジョブに、記録済みの部分的なツール出力が残る場合があります。ジョブの最終状態で成功を確認します。これは既定のライブ・ソース API の説明です。以下の別の保存済み結果 API は、再起動後もバイト列を保持します。

実際の 2 MiB 転送で、中断、再接続、末尾のみの再開を試すには npm run example:artifacts を実行します。npm run benchmark:artifacts は 8 MiB を使用します。ローカルの Windows 実行では、65,536 バイトの先頭部分から再開し、最終 SHA-256 を検証して、129 回のチャンク要求で 8,388,625 バイトを転送しました。base64 には追加の容量が必要で、JSON 応答本文の合計は 11,257,419 バイトでした。転送中のメモリー使用量を限定し、受信ファイル全体を検証します。完全な契約については、バイナリ成果物を参照してください。独立した SDK クライアントとホストから転送を実行します。

永続ジョブ、履歴、明示的な再試行

SDK 0.8.0 は、ワークスペースの外にある操作者所有のディレクトリ内に、任意の永続ストアを追加します。絶対パス、安定したワークスペース ID、確認済みプラグインコード、パッケージの SHA-256、トークン、通知を指定してください。サンプルはファイルのバイト列の保持も有効にします。ジョブメタデータだけを保存する場合は、jobStorage から artifacts を省略します。既存の v1 応答と、メモリーのみの既定動作との互換性は維持されます。

JavaScript
import {createNodeJobStore} from '@altifigence/dds-plugin-sdk/job-storage-node';
import {createNodeArtifactStore} from '@altifigence/dds-plugin-sdk/artifact-storage-node';
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
const store = await createNodeJobStore({directory, workspaceRoot: root, workspaceId});
const artifacts = await createNodeArtifactStore({jobStore: store});
const server = await createWorkspaceServer({
  root, workspaceId, token, notice, plugins: [{plugin, artifactSha256}],
  grants: ['workspace.read'], jobs: true, binaryArtifacts: true,
  jobStorage: {store, artifacts},
});

プロバイダーは、最初の実行意図が保存された後にのみ開始します。その後のチェックポイントは集約され、flushJobStore() は、コマンド完了ではなく要求されたチェックポイントを待ちます。復旧は、現在の接続と元の実行スコープを分離し、live、completed、interrupted、expired、missing、corrupt、unsupported を報告します。中断されたジョブは自動で再起動せず、その unrecordedTail は不明です。

JavaScript
const capabilities = await client.getJobStorageCapabilities();
const query = {limit: 16, commandId: 'analyze'};
const page = await client.listJobHistory(pluginId, artifactSha256, query);
const prior = await client.recoverJob(pluginId, previousJobId, artifactSha256);
const attempt = await client.retryCommandJob(pluginId, previousJobId,
  reviewedFreshInput, artifactSha256, {jobId: crypto.randomUUID()});

履歴は、状態、復旧上の扱い、コマンド、開始時刻、親の試行で絞り込みます。ページには最大 32 件が含まれ、開始時刻の降順、次にジョブ ID の順に並びます。カーソルは対象の集合を 60 秒間固定し、同じクエリーを再利用する必要があります。新しいジョブは除外され、削除済みや未認可の記録はスキップされ、期限切れは報告されます。再起動ではカーソルが失われます。artifactCount、snapshotCount、resultAvailability は、記録された参照を説明するものであり、現在のファイルの証明ではありません。

明示的な再試行には、新しいジョブ ID、新しく検証された入力、同じ現在承認済みのパッケージ、利用可能なコマンドが必要です。attemptOf は、新しい実行を、変更されていない親に関連付けます。同じ ID、入力、親、タイムアウトを繰り返すと、再起動後も、再実行せずに保持済みの試行を取得します。不足・期限切れの記録では、その保証は提供できません。受け付けられた実行は、待機中の要求がキャンセルされた後も続く場合があります。再試行を判断する前に、新しいジョブ ID を照会してください。

既定の保持では、生の入力、結果本文、進捗テキスト、成果物ラベルを省略し、ログの機密情報を削除します。確認済みテキストを保持するのは、明示的な決定的ホスト秘匿処理がある場合だけです。トークン、シークレット、古い同意は復元されません。現在のワークスペース・プラグインの識別情報、読み取り権限、記録されたすべての権限付与を再確認します。ジョブメタデータの既定値は、256 記録、64 MiB、24 時間で、最大 7 日間です。削除と期限切れ整理は、明示的なホスト操作です。

ローカルストアの書き込み元は 1 つで、ワークスペース・ルートの識別情報とメタデータの整合性を検証します。明示的な古いロックの復旧は、同じマシンで終了が証明された PID のロックだけを回収します。不明・破損ファイルには確認が必要です。Windows のファイル同期と名前変更は、確認されたプロセス終了後の復旧に使用されます。実際の永続性は、ファイルシステムと保存装置の動作に従います。ジョブストレージ、履歴、永続ジョブのサンプルを参照してください。

保存済み結果と再起動後のダウンロード

成果物ストアを有効にすると、await job.addArtifact() または job.addBinaryArtifact() は、登録前にファイル全体をコピーして検証します。テキストは引き続き 256 KiB、バイナリファイルは最大 1 GiB です。ソースストリームと実際のステージングファイルを SHA-256 で確認します。キャンセル、ディスク容量不足、変更、部分書き込みは、利用可能な結果を確定しません。クラッシュ前に確定されたものの、ジョブに記録されていないファイルは、操作者の確認用に残る場合があります。

JavaScript
import {downloadStoredJobArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const list = await client.listStoredJobArtifacts(pluginId, jobId, artifactSha256);
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, artifactSha256);
const receipt = await downloadStoredJobArtifact(client, reference, {
  destination: absoluteOutputPath, resume: true,
});
console.log(receipt.storage, receipt.snapshotId, receipt.verified);

一覧は、ソース参照とスナップショットメタデータを分離し、retained、expired、missing、corrupt、unsupported のスナップショットを報告します。retained はメタデータの状態です。getStoredJobArtifact() は、メタデータと保存ファイル全体を検証してから、新しい現在世代の参照を返します。各読み取りでは、現在の権限とファイルの識別情報を再確認します。ソースの削除は保存済みバイト列に影響せず、スナップショットがない場合に可変のソースへフォールバックすることはありません。テキストスナップショットには、client.readStoredJobArtifactText(textReference) を呼び出します。

再起動後は、現在の付与権限で再接続し、新しい参照を取得します。スナップショット ID、ストア ID、ダイジェストは安定したままで、古い世代は拒否されます。resume: true は、保存済み .dds-part の先頭部分をそのスナップショットと再照合し、チャンクとステージングファイル全体を検証して、保存先を上書きせずに確定します。読み取りには、ファイルのバイト列と、保持されたジョブメタデータの両方が必要です。ブラウザーでチャンクを扱う側は、完全なダイジェストを検証する必要があります。以下の Worker アダプターが、明示的なブラウザーディスクからの再開を提供します。

成果物ストレージの既定値は、256 ファイル、256 MiB、24 時間で、合計ストレージの最大値は 4 GiB、保持期間の最大値は 7 日間です。チャンクは最大 64 KiB、同時読み取りは 4 つです。inspect() は、使用量、有効期限、無効な項目、孤立ファイルを報告します。remove(snapshot) と prune() は、明示的な操作者操作です。稼働中のジョブと各読み取りは固定されますが、チャンク間で期限切れや削除が起こると、次の読み取りが止まる場合があります。任意の孤立ファイル整理は、認識できる単一リンクのファイルだけを削除します。破損や曖昧な項目には確認が必要です。

ファイルの保持は、ログの機密情報削除とは独立して、実際のプロジェクトのバイト列を保存します。意識して選択してください。再起動後も、現在のプラグイン・コマンド、パッケージハッシュ、ワークスペース、記録された権限付与が必要です。保守を終えた後、server.close()、artifacts.close()、store.close() を、この順に await します。独立した SDK ホストでファイルの保持を設定して使用します。

実際の子プロセス再起動、ソース削除、検証済み部分ダウンロードの再開、履歴、明示的な再試行を試すには、npm run example:stored-artifacts を実行します。npm run example:durable-jobs は、強制的なプロセス終了も扱います。保存済み結果を参照してください。既知の 0.7 以前のホストは、不明な検出要求を送らずにストレージ無効と報告します。既存のライブ・ソース API は、元の動作を維持します。

プロジェクトを監視する

操作者は、サーバー上でプロジェクトを明示的に有効化し、許可するルートを選択します。既定は無効です。既知の SDK 0.3~0.8 ホストは、新しい検出要求を送らずに利用不可と報告します。対応プロファイルは Windows・Linux のローカルファイルシステムを使用します。独立した SDK のプロジェクト API から、このサンプルを実行します。

import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
import {createWorkspaceClient, createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
// The operator chooses the workspace and its allowed local directories.
const server = await createWorkspaceServer({
  root: operatorWorkspace, workspaceId, token, notice,
  projects: {roots: ['rtl'], fileSystem: 'local'},
});
const client = createWorkspaceClient({url: server.url, token});
await client.connect();
const project = createWorkspaceProject(client);
if (!(await project.getProjectCapabilities()).enabled) {
  throw new Error('Project tools are unavailable');
}
const observer = project.watchProject({
  root: 'rtl', include: ['**/*.sv'], exclude: ['build/**'],
  intervalMs: 1000, debounceMs: 50,
}, {signal});
for await (const event of observer) {
  renderExternalView(event.snapshot, event.kind, event.reason);
}
project.dispose(); client.dispose(); await server.close();

最初のイベントは完全なスナップショットです。その後の変更は、以前のリビジョンに対する差分を持ちます。ヒントの喪失、初回スキャン中の変更、不完全なスキャン、利用側の遅延によるオーバーフローでは、理由付きの完全な再同期ビューを生成します。名前変更は削除・作成として現れる場合があります。各ファイルを観測時に個別に検証し、そのサンプルを組み合わせてビューを構成します。中間の書き込みはまとめて観測される場合があります。

サーバーとクライアントは、それぞれ 4 つの購読を許可し、ネイティブ購読ごとに 4 件のイベントをキューに保持します。既定のアイドルリースは 30 秒で、それより後の読み取りは not_found を返す場合があります。長い一時停止後は、初期スナップショット用に新しい反復処理を作成してください。break/return、キャンセル、破棄は購読を解放します。接続切断によりクリーンアップできない場合、残りのリモートリソースはリースの期限で失効します。

スキャン上限の既定値は、深さ 8、512 項目、1 ファイル 1 MiB、合計 16 MiB、10 秒です。設定可能な最大値は、深さ 32、1,000 項目、1 ファイル 16 MiB、合計 64 MiB、30 秒です。制限に達したファイルは、内容ハッシュなしのメタデータだけを持つ場合があります。complete と reasons を確認してください。期限はファイルシステム呼び出しの間で確認します。これらの呼び出しに使うホストプロセスの OS アクセス権を慎重に選択してください。

プロジェクトツリーと検索

listTree はツリーを返し、searchFiles はリテラルな部分文字列または範囲を限定した glob で相対ファイル名を検索し、searchText は UTF-8 ファイル内のリテラルテキストを検索します。root は必須で、include/exclude はそれからの相対指定です。検索パターンには、リテラルテキストと文書化された範囲内のファイル名 glob 構文を使用します。大文字と小文字を区別しない照合では、元の UTF-16 位置を安定して保持するため、ASCII A–Z だけを小文字に対応付けます。

const tree = await project.listTree({root: 'rtl', pageSize: 16});
const names = await project.searchFiles({root: 'rtl', query: '**/*.sv', mode: 'glob'});
const query = {root: 'rtl', include: ['**/*.sv'], query: 'module ', pageSize: 16};
let page = await project.searchText(query);
for (const item of page.items) {
  console.log(item.entry.path, item.entry.revision, item.match.range, item.match.snippet);
}
if (page.nextCursor) {
  const next = await project.searchText({...query, cursor: page.nextCursor});
  console.log(next.stale, next.items.map(item => item.state));
  if (next.nextCursor) await project.releaseProjectQuery(next.nextCursor);
}
if (tree.nextCursor) await project.releaseProjectQuery(tree.nextCursor);
if (names.nextCursor) await project.releaseProjectQuery(names.nextCursor);

テキストの一致には、内容の SHA-256、0 始まりの UTF-16 範囲、範囲を限定した抜粋が含まれます。カーソルは元の対象集合を最大 60 秒間固定し、同じクエリーを必要とします。その後のページは現在の内容を再確認し、項目を current、changed、missing、unverified として示します。新しいファイルは、新しいクエリーにのみ現れます。取り込まれた一致とリビジョンは変更されません。

テキストファイルは 256 KiB、クエリーは 256 UTF-16 単位、抜粋は 512 単位までです。既定値は、結果 256 件(最大 512)、1 ページ 32 項目(最大 64)、応答 64 KiB(最大 128 KiB)です。バイナリファイル、不正な UTF-8、バイト数・深さ・時間・応答の上限は、理由付きの不完全な結果として報告します。同時クエリーは 2 つ、保持されるカーソルビューは 8 つです。不要なカーソルは明示的に解放してください。

プロジェクトの下書きと再接続

const edit = await project.openFile('rtl/counter.sv');
const original = edit.snapshot;
const draft = original.content + '\n// unsaved draft';
const query = {root: 'rtl', include: ['**/*.sv'], query: 'module '};
let page = await project.searchText(query);
for await (const event of project.watchProject({root: 'rtl', include: query.include}, {signal})) {
  if (event.snapshot.revision !== page.snapshotRevision) {
    if (page.nextCursor) await project.releaseProjectQuery(page.nextCursor);
    page = await project.searchText(query); // keep the same explicit scope
  }
  renderTreeAndMatches(event.snapshot, page); // draft remains caller-owned
}
// A changed file causes conflict; a move/deletion can cause not_found.
try { await edit.save(draft); }
catch (error) {
  if (!['conflict', 'not_found'].includes(error.code)) throw error;
  showResolutionChoice(error, draft, original);
}
// Only an explicit edit.reload() replaces the edit snapshot.
project.dispose(); client.disconnect(); await client.connect();
const freshProject = createWorkspaceProject(client);
const freshObserver = freshProject.watchProject({root: 'rtl'});
console.log((await freshObserver.next()).value.cursor); // 1: full initial view
await freshObserver.return(); freshProject.dispose();

クエリーの snapshotRevision が、観測した snapshot.revision と異なる場合は、古いカーソルを解放し、同じルート・フィルターのクエリーを繰り返します。監視は edit.snapshot や呼び出し元が所有する下書きの内容を変更しません。外部変更、移動、削除の後は、元の CAS 条件が競合を報告します。呼び出し元が、明示的な再読み込み、マージ、別途保存を選択します。

クライアントは、接続世代、ルート・フィルター、クエリーハッシュ、ページ位置、スナップショットの SHA-256、イベントの連続性を確認します。取り消し、切断、再接続後の遅れた応答は破棄します。監視カーソルとクエリーカーソルは別で、自動では復元しません。server.revokeProjects() はプロジェクトアクセスを終了します。再有効化には、新しいサーバー世代が必要です。

npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browser

インストール済み Node サンプルは、作成、検索、外部変更、保持した下書き、CAS の競合、再接続を検証します。ブラウザーのサンプルでは、表示されたループバック URL を開き、シナリオを実行を選びます。独自の一時ワークスペースだけを使用し、サンプルサーバーが止まると削除します。HTTP 要求の既定は 5 秒です。大きなスキャンでは、クライアントとサーバーのタイムアウトを意識して設定してください。

プロジェクトの監視 · ツリー・検索の契約 · HTTP プロジェクトツール

ブラウザーの成果物をストリーミングして検証する

import {streamStoredJobArtifact} from '@altifigence/dds-plugin-sdk/artifact-transfer';
import {createOpfsFileSink} from '@altifigence/dds-plugin-sdk/artifact-transfer-browser';
// selectedDirectory belongs to the application; no picker or grant is opened by the SDK.
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, pluginPin);
const sink = await createOpfsFileSink(selectedDirectory, 'trace.bin', {overwrite: false});
const receipt = await streamStoredJobArtifact(client, reference, {sink, signal});
if (receipt.verification === 'stored') showSavedHash(receipt.storedSha256);

ブラウザーで安全に使えるヘルパーは、1 回につき最大 1 チャンクの 64 KiB を受け取り、選択した出力先を待ちながら、ファイル全体を逐次ハッシュ化します。書き込む前に、正確な範囲、識別情報、base64、各チャンクのハッシュを検証します。読み戻し対応の出力先は、保存されたバイト列を独立して読み直します。両方の全体ハッシュが一致した後にのみ、検証状態は stored になります。読み戻しがない場合、検証状態は received で、storedSha256 は null です。進捗が全バイトに達しても、完了ではありません。

アプリケーションがファイルハンドルや OPFS ディレクトリを選択し、必要な権限を付与します。選択と権限はアプリケーションが管理し、明示的に選んだ保存先と承認済みのアクセスを SDK アダプターに渡します。非同期のファイル・OPFS 書き込み出力先は、close までステージングを保持し、コミット前の失敗時には破棄します。再読み込み後も使える部分ファイルには、以下の専用 Worker アダプターを使用してください。上限は、ファイル 1 GiB、直接の同時ストリーム 4 つ、合計期限 30 分です。

選択したファイルをアップロードする

import {uploadFile} from '@altifigence/dds-plugin-sdk/uploads';
import {createBrowserUploadSource} from '@altifigence/dds-plugin-sdk/uploads-browser';
// The operator separately configures uploads.directory/principalId/roots/fileSystem
// on the Node workspace server, and grants workspace.write to this pinned plugin.
const source = createBrowserUploadSource(selectedFile);
const status = await uploadFile(client, source, {
  uploadId: crypto.randomUUID(), pluginId, artifactSha256: pluginPin,
  path: 'input/trace.bin', expectedRevision: null, signal,
});
if (status.state === 'committed' && status.commitReceipt.verified) {
  showCommittedUpload(status.commitReceipt);
}
// To recover a previously selected upload ID, pass the same specification and
// source with recover: true. The helper queries current authority and rehashes it.

アップロードは既定で無効です。操作者は、ローカル Node ワークスペース、分離されたステージングディレクトリ、許可ルート、1 つの主体を設定し、選択したプラグインの正確なアーカイブピンに workspace.write を付与します。ヘルパーは、開始前に選択したソースをハッシュ化します。サーバーは順序どおりの 64 KiB チャンクを受け付け、重複と内容全体を検証し、条件付きの対象確認後にのみコミットします。通常のワークスペース一覧には、ステージング中のバイト列は現れません。

expectedRevision: null は対象が存在しないことを要求し、SHA-256 は現在の対象が一致することを要求します。キャンセルでは、サーバーが受領確認した先頭部分を保持します。新しい明示的な recover 操作は、現在の権限を照会し、同じソース・仕様を検証して、一致する先頭部分からのみ再開します。コミット応答が失われた場合は、照会するまで結果は不確かです。コミットの繰り返しやファイルのロールバックを許可するものではありません。最大上限は 1 ファイル 1 GiB、1 ストア 4 GiB、稼働中セッション 4 つで、既定値はそれより低くなっています。既知の 0.3~0.9 ホストは、新しいメソッドを検出しようとせず、アップロード無効と報告します。

ファイル転送をスケジュールする

import {createTransferQueue} from '@altifigence/dds-plugin-sdk/transfer-queue';
const queue = createTransferQueue({
  concurrency: 2, perConnection: 1, bufferBytes: 131072,
  bytesPerSecond: 1048576, attempts: 3,
});
const unsubscribe = queue.subscribe(view => renderTransfer(view));
const download = queue.enqueueStoredDownload(client, reference, {sink});
download.pause(); // finishes the current stage, then waits at the next boundary
download.resume();
const receipt = await download.result;
queue.release(download.id);
unsubscribe(); await queue.dispose();

呼び出し元が所有するキューには、アップロード、ライブダウンロード、保存済みダウンロードのジョブを混在できます。保持ジョブ数(32)、同時ステージ数(4)、クライアント接続の並行処理数、復号されたチャンクの予約容量(64~256 KiB)、転送速度、再試行を制限します。実行条件を満たした作業は、飽和した接続の待機を越えて進行できます。優先的な先行開始の範囲を限定し、実行可能な小さいジョブが待ち続けることを防ぎます。一時停止したジョブは現在のステージを完了してから待機します。一時停止では、ストレージのロックが保持される場合があります。合計期限には、キュー待機と一時停止が含まれます。

自動再試行は、冪等な正確なチャンク操作中に SDK が認識する 429/503、ネットワーク喪失、要求タイムアウトに限られ、範囲を限定したバックオフとジッターを使用します。開始・コミット、認可、チェックサム、範囲、ソース、出力先の失敗では、呼び出し元に制御を戻して明示的な確認を求めます。acknowledgedBytes、transferredBytes、attemptedBytes、retriedBytes、resumedBytes、remainingBytes は別々です。検証済みの受領記録だけが completed を生みます。コミット済みファイルは cancel/dispose 後もその状態を保持します。

ブラウザーのダウンロードを再開する

// Run inside an application-owned dedicated Worker with OPFS + Web Locks.
import {createOpfsArtifactSink} from '@altifigence/dds-plugin-sdk/artifact-resume-browser';
import {streamStoredJobArtifact} from '@altifigence/dds-plugin-sdk/artifact-transfer';
await client.connect();
const fresh = await client.getStoredJobArtifact(pluginId, jobId, artifactId, pluginPin);
const sink = createOpfsArtifactSink({
  directory: selectedDirectory, partialId: selectedPartialId, reference: fresh,
});
const receipt = await streamStoredJobArtifact(client, fresh, {sink, resume: true, signal});
console.log(receipt.resumedBytes, receipt.receivedBytes, receipt.storedSha256);
// The first transfer omits resume, and refuses any existing files for that ID.
// A queue can use the same sink and explicit resume: true on a new stored download.

永続的な復旧には、専用 Worker、OPFS 同期アクセス、Web Locks が必要です。呼び出し元は再読み込み後にディレクトリと部分ファイルの UUID を選び直し、新しい承認済みの保存済み参照を取得します。出力先は、データとメタデータの正確な 2 つのファイル名、完全で変更不能なスナップショット識別情報、有効期限、現在・以前の先頭部分のハッシュを保存します。トークン、付与権限、古い接続スコープは保存しません。小さいメタデータストリームを閉じる前に、各データチャンクをフラッシュします。

出力先とヘルパーの両方が、先頭部分を独立して再ハッシュ化します。記録された先頭部分が一致した後にのみ、チェックポイントに記録されていない末尾を切り詰めます。メタデータが実際のファイルサイズより先を示す場合、そのバイト列とハッシュが一致する場合に限り、以前のチェックポイントへ戻れます。破損、項目不足、期限切れ、異なるスナップショットでは、知らせずに最初からやり直さず失敗します。オリジン全体の排他的ロックは別のタブを拒否し、読み戻し中も保持され、close または Worker の終了で解放されます。その後、開き直すには明示的な復旧が必要です。

ローカルメタデータは 16 KiB、開いている出力先セッションは 4 つまでです。保持は既定 1 時間、最大 24 時間で、ホストのスナップショット有効期限も上限となります。容量制限とデータの削除はブラウザーが管理し、同一オリジンのスクリプトはストレージへのアクセス権を共有します。復旧はこの保存規則のもとで記録されたチェックポイントを使用します。Windows の Chromium 154 で、保存ファイル全体のハッシュを用いて、キャンセル、再読み込み、ホスト再起動、2 タブの競合、所有タブの終了を試験しました。報告された確認結果は、このブラウザーと OS の組み合わせを対象とします。

npm run example:browser-artifacts
npm run example:uploads-browser
npm run example:transfer-queue-browser
npm run example:browser-resume

ストリーミング · アップロード · 転送キュー · Worker の復旧

シグネチャヘルプと補完支援

必要に応じて、マニフェスト v2 に signature-help、completion-resolve、completion-snippets を宣言します。補完の修飾機能には completion も必要です。ホストは document.read と language.provide を付与する必要があります。既存のリテラル補完は引き続き有効です。languageCapabilities() は、権限を付与せずに SDK の実装と上限を報告します。

const signatures = await host.requestLanguage('signature-help', {
  position, context: {triggerKind: 'invoked', isRetrigger: false},
});
const list = await host.requestLanguage('completion', {position});
if (list.data.length) {
  const detailed = list.data[0].resolveToken
    ? await host.resolveCompletion(list.data[0].resolveToken) : list;
  const preview = host.prepareCompletion(detailed, 0);
  showInsertionPreview(preview.content, preview.tabstops);
  host.releaseCompletion(detailed);
}
host.releaseCompletion(list);

アプリケーションは現在の位置とホストを提供し、準備処理はドキュメントやファイルを書き込まずにデータを返します。シグネチャヘルプは最大 16 シグネチャ、各 64 パラメーター、UTF-16 のパラメーターラベルオフセットに対応します。補完の解決は、プロバイダーデータを非公開に保ち、1 回限りのホストトークンを返し、選択したラベル・挿入・範囲を固定します。トークンはプロバイダー、スコープ、ドキュメントに関連付けられ、60 秒後に期限切れになります。上限は、128 項目、4 MiB、実際の解決操作 4 つです。ドキュメント・プロバイダーの変更は、トークンを破棄します。

スニペットは、$n、${n}、${n:literal}、$0、文書化されたエスケープに対応し、ミラーと順序付きタブストップを提供します。変数、入れ子、選択肢、変換、実行可能コマンドは拒否されます。UTF-16・CRLF の境界と、追加編集の重なりを確認します。プロバイダーはホストプロセスの OS 権限で動作する、信頼されたコードです。キャンセルを無視した処理は、完了するまで実際の保留スロットを占有します。

レビュー付きワークスペース編集と名前変更

prepare-rename は検証済みの範囲・プレースホルダーまたは null を返し、rename は WorkspaceEdit の提案または null を返します。提案は、互いに重ならない相対ファイルパスに対し、編集、作成、移動、削除をサポートします。現在のソース SHA-256、保存先の不在、保護パスポリシー、UTF-16 の編集範囲、上限を確認します。言語機能は提案を許可し、ワークスペースクライアントが個別に承認されたファイルアクセスと変更を提供します。

import {previewWorkspaceEdit, applyWorkspaceEdit, recoverWorkspaceEdit}
  from '@altifigence/dds-plugin-sdk/workspace-edits';
const preview = await previewWorkspaceEdit(client, proposal);
// Show every change, conflict and required capability; obtain this exact review.
const receipt = await applyWorkspaceEdit(client, preview, {
  reviewed: approvedReview, // {planId, digest} from that review
  journal,
  authorize: (request, {signal}) => currentHostPolicy(request, signal),
});
// After interruption, current-authority readback does not replay changes.
const observed = await recoverWorkspaceEdit(client, journal, preview.planId);

呼び出し元は、接続済みの認可されたワークスペースクライアントと、信頼されたジャーナルを使用します。プレビューには完全な変更前後のスナップショットとダイジェストが含まれます。apply には、レビュー済みの planId/digest と、true を返す現在のホストポリシーが必要です。すべてのファイルを事前確認し、その後の各操作は、既存のファイル単位の CAS と、現在の書き込み・管理機能を使用します。ジャーナルは、各変更前に実行意図を永続化して読み戻し、変更後に受領記録を永続化して読み戻します。競合や不確かな結果では、後続の書き込みを停止します。各ファイルは個別の CAS 操作でコミットするため、中断した計画にはコミット済みのファイルが含まれる場合があります。

任意の workspace-edits-node アダプターは、選択ワークスペースの外に範囲を限定したジャーナルを保存し、その識別情報を関連付けます。単一書き込み元のロック、通常ファイル、チェックサムのチェックポイントを使用します。プロセス終了後の recoverStaleLock は、明示的な選択であり、終了が証明された所有者のロックだけを回収します。復旧は現在のバイト列から applied/not-applied/conflicted/unknown を報告し、次の操作を呼び出し元に委ねます。補償処理は、新たなレビュー用に、新しい逆方向の提案を作成します。Windows ではアダプターがファイルを同期し、名前変更操作を実行します。報告された永続性の確認はプロセス終了と復旧を対象とし、実際の永続性はファイルシステムと保存装置の動作に従います。上限には、32 変更、1,000 編集、1 ファイル 256 KiB、8 MiB プレビュー、保持ジャーナル計画 64 件が含まれます。

整形と診断のコードアクション

const formatted = await host.requestLanguage('format-range', {
  path: 'main.dds', range: selectedRange,
  formatOptions: {tabSize: 2, insertSpaces: true, endOfLine: 'preserve'},
});
const formatProposal = host.prepareFormatting(formatted);
await host.requestDiagnostics();
const actions = await host.requestLanguage('code-actions', {
  path: 'main.dds', range: selectedRange,
  context: {triggerKind: 'invoked', only: ['quickfix']},
});
if (actions.data.length && !actions.data[0].disabled) {
  const selected = actions.data[0].resolveToken
    ? await host.resolveCodeAction(actions.data[0].resolveToken) : actions;
  if (!selected.data[0].disabled) {
    const fixProposal = host.prepareCodeAction(selected, 0);
    showWorkspaceEditProposal(fixProposal); // separate preview, review and apply
  }
  host.releaseCodeActions(selected);
}
host.releaseCodeActions(actions);

format-document と format-range は、パスと tabSize/insertSpaces オプションを必要とします。選択範囲を受け取るのは範囲整形だけです。結果は null、または現在のスナップショットハッシュを持つ、現在のファイルへの正確に 1 つの編集です。範囲編集は選択範囲内に収まります。endOfLine は、挿入テキストに対し preserve、lf、crlf を選択し、未編集のバイト列は変わりません。内容が同一の提案は null に正規化します。prepareFormatting は書き込みを行いません。

ホストは、アクション要求と解決トークンを、受け入れた診断リビジョンと現在のスナップショットに関連付けます。その後の診断公開、ドキュメント変更、プロバイダー破棄は、古い選択を無効にします。順序が入れ替わった診断呼び出しは、新しく受け入れたバンドルを上書きしません。最大 100 件のアクションは、プレーンなラベル、範囲を限定した診断インデックス、提案された編集、非公開の解決データ、または無効化されている理由を持ちます。不明な command/URL/shell フィールドは拒否されます。アクションの編集は選択範囲を超える場合があるため、提案全体を確認してください。整形やアクションが、自分の書き込みを承認することはありません。

セマンティック表示、折りたたみ、ヒント、シンボル

import {decodeSemanticTokens} from '@altifigence/dds-plugin-sdk';
const tokens = await host.requestLanguage('semantic-tokens',
  previousResultId ? {previousResultId} : {});
host.validateLanguageResult(tokens); // actual current host-owned result only
renderWhitelistedTokens(decodeSemanticTokens(tokens.data, currentDocumentText));
const folds = await host.requestLanguage('folding-ranges', {});
const hints = await host.requestLanguage('inlay-hints', {range: visibleRange});
const symbols = await host.requestLanguage('document-symbol-tree', {});
for (const result of [folds, hints, symbols]) host.validateLanguageResult(result);
// Render labels as text nodes. Release results when no longer retained.
host.releaseLanguageResult(tokens);

セマンティックトークンは、一意の名前とホスト所有の 9 スタイルキーを持つ凡例を使用します。各トークンには、行・開始位置の差分、UTF-16 長、型インデックス、修飾子ビットという 5 つの整数があります。トークンの重なり、サロゲートの分断、行をまたぐこと、現在のドキュメントの外に出ることはできません。ホストは常に、正規化された完全な配列とホスト UUID を返し、updateKind は full/delta/fallback です。別の semantic-tokens-delta 機能は、プロバイダーが所有する以前のデータに対する provideDelta を有効にします。キャッシュに保存するのは識別情報とトークンデータであり、古いドキュメントテキストではありません。

キャッシュの基準は、プロバイダー、スコープ、URI、言語に関連付けられ、上限は 8 項目、4 MiB、60 秒です。通常の増加するドキュメントバージョンでは、古い表示結果を期限切れにしながら、差分基準となる可能性のあるデータを保持します。基準の喪失・期限切れ、null の差分、プロバイダー基準 ID の不一致は、元のタイムアウト内で最大 1 回の全体フォールバックを許可します。無効なデータやプロバイダーエラーは、再試行せずに失敗します。無効化、登録解除、ドキュメント置換は、影響を受ける基準を消去します。表示直前に validateLanguageResult を呼び出してください。コピーされた、解放された、または古いオブジェクトは失敗します。

上限は、セマンティックトークン 20,000 個、トークン型 64 個、修飾子 16 個、差分編集 64 件です。折りたたみは、深さ 32 で 1,000 範囲を許可し、交差する範囲を拒否します。インレイヒントは、要求範囲内の単一行のプレーンラベルを 1,000 個許可します。階層シンボルは、合計 1,000 項目、16 レベルを許可し、子と選択範囲が親に含まれ、同階層の項目は順序付きで重ならない必要があります。元のフラットな document-symbols 契約は変更されません。ブラウザーサンプルは full/delta/fallback、折りたたみ、移動、ライフサイクルを試験します。HTML のようなヒントも、リテラルテキストのままです。

npm run example:assistance
npm run example:workspace-edits
npm run example:language-editing
npm run example:language-display
npm run example:language-display-browser

支援 · レビュー付き編集 · 整形・アクション · 表示

型付き設定とシークレット参照

/settings モジュールは、1 つのプラグイン用に操作者所有のメモリーストアを提供します。バージョン付き定義は、各キー、データスキーマ、既定値、許可するユーザー・ワークスペーススコープ、表示メタデータを宣言します。有効な値は default < user < workspace の順で、キー全体を置き換えます。read(workspaceId) は、変更不能な値、値の出所、ストア全体のリビジョンを返します。入れ子のオブジェクトは再帰的にマージしません。既定値のない不足した値は、不在のままです。

import {createSettingsStore} from '@altifigence/dds-plugin-sdk/settings';
const settings = createSettingsStore({schemaVersion: 1, pluginId: 'example',
  version: 1, settings: {count: {
    schema: {schemaVersion: 1, schema: {
      type: 'integer', minimum: 1, maximum: 10, default: 2,
    }}, scopes: ['user', 'workspace'], display: {label: 'Count'},
  }},
});
settings.update({workspaceId: 'selected-project', scope: 'workspace',
  expectedRevision: settings.read('selected-project').revision, values: {count: 4}});
const effective = settings.read('selected-project');
// Mount as createPluginHost({settings: {example: settings}, ...}).

書き込みはトランザクション全体を検証し、expectedRevision の CAS を使用します。reset は 1 層からキーを削除し、readOnly には既定値と、書き込み可能スコープがないことが必要です。購読は同期的な変更を集約し、破棄可能なハンドルを返します。明示的な migrate(nextDefinition, callback, options) は次の状態を検証し、リビジョンがまだ一致する場合にのみコミットします。失敗、キャンセル、タイムアウトは、古い定義と状態を保持します。エクスポート・インポートはプレーンなデータであり、永続化と暗号化は操作者が管理します。上限には、64 キー、32 ワークスペース層、1 MiB のエクスポート状態、実際の移行 1 件が含まれます。

ワークスペースプラグインは settings と settings.read を宣言し、操作者が、その付与権限を持つ対応ストアをマウントします。context.settings は読み取り専用で、プラグインと選択したワークスペースに関連付けられます。/secrets リゾルバーは、プラグイン、ワークスペース、コマンド許可リスト、有効期間に対する不透明な参照を別途発行します。マニフェストは secrets.resolve を宣言し、ホストはそれを付与する必要があります。入力フィールドは、format: dds-secret-reference を持つ type: object を使用します。通常の文字列や似た形のオブジェクトに、シークレットの権限はありません。

コマンドの options.secrets.withSecret から利用できるのは、検証済み入力内の参照だけです。各実行には新しい ID があり、リゾルバーは解決処理とコールバックの前後で、スコープ、有効期限、取り消し、現在の認可を確認します。コールバックは undefined を返し、中止時とあらゆる終了時に消去されるコピーを受け取ります。プロバイダーのエラーは機密情報が削除されます。その権限を必要とする副作用の前に、リースを取得してください。参照の既定有効期間は 60 秒、最大 1 時間です。上限は、128 参照、実際のリース 8 個、シークレット情報 16 KiB です。信頼されたプロセス内コードは、ホストプロセスの OS 権限で動作し、コピーを保持できます。シークレット情報を設定、バンドル、ログ、結果に入れないでください。機密データを扱う際は、任意のアプリケーション文字列も明示的に分類してください。

構造化コマンドスキーマとフォーム

コマンドは、schemaVersion: 1 のエンベロープを使って inputSchema と outputSchema を宣言できます。既存のプリミティブな parameters は引き続きサポートしますが、parameters と inputSchema の同時宣言は拒否されます。ホストは、ハンドラーやジョブを開始する前に入力を検証して既定値を適用し、その後、成功を公開する前に出力を検証します。出力の既定値は適用しません。新しいスキーマ・表示メタデータには、0.12 を認識する peer が必要です。古い厳密な検証機能はそれを拒否し、旧定義は元の動作を維持します。

import {parseCommandInput, parseCommandOutput} from '@altifigence/dds-plugin-sdk';
const command = {id: 'summarize', title: 'Summarize',
  inputSchema: {schemaVersion: 1, schema: {
    type: 'object', additionalProperties: false,
    properties: {names: {type: 'array', minItems: 1, maxItems: 8,
      items: {type: 'string', minLength: 1, maxLength: 64}}}, required: ['names'],
  }}, outputSchema: {schemaVersion: 1, schema: {type: 'integer', minimum: 0}},
};
const input = parseCommandInput({names: ['Ada']}, command);
parseCommandOutput(input.names.length, command);

範囲を限定したサブセットは、閉じたオブジェクト、配列、文字列、有限数、安全な整数、ブール値、null、プリミティブ列挙値、範囲制約、検証済みの既定値に対応します。不明なキーワード、リモート参照、正規表現、共用体、型変換、アクセサー、カスタムプロトタイプは拒否されます。スキーマは 32 KiB、深さ 8、128 ノード、値は 64 KiB までです。完全なコマンドは、16 KiB のメタデータ予算を維持します。ローカルの DataValidationError は、code、reason、/input/options/names/0 のような既知のフィールドパスを公開します。HTTP とジョブの失敗は、拒否された値を含めず、安全なコードを公開します。

describeDataForm は、パス、型、選択肢、既定値、必須フラグ、シークレット参照のヒントを返します。共有表示メタデータは、リテラルの label/help/order と、アクセシビリティー用の名前、説明、キーボードヒントを持ちます。表示と操作はホストが管理します。スキーマはリテラルのフォームデータを提供し、表示、リソースへのアクセス、コマンド実行はホストが明示的に実装します。

ローカライズとアクセシビリティーのメタデータ

import {parseLocaleCatalog, resolveMessage, localizeDisplay}
  from '@altifigence/dds-plugin-sdk/localization';
const catalog = parseLocaleCatalog({schemaVersion: 1, defaultLocale: 'en',
  messages: {en: {title: 'Run', done: '{count} results'},
    ko: {title: '실행', done: '결과 {count}개'}, ar: {}}, fallbacks: {ar: ['en']},
});
const message = resolveMessage(catalog, 'ko-KR', 'done', {count: 2});
const display = localizeDisplay(catalog, 'ko', {
  labelKey: 'title', accessibility: {nameKey: 'title', shortcut: 'Control+Enter'},
});
// Render message.text as textContent; use message.locale and message.direction.
// Preserve raw values and command IDs when the display language changes.

カタログは、正規の BCP 47 基本タグと、循環のない明示的なフォールバックの辺を使用します。最大 8 つの優先言語から、正確なタグ、次に祖先、最後に既定を選択します。既定のロケールは全キーを定義します。翻訳はキーを省略できますが、新しいキーは作れません。キーごとの検索は、順序付きフォールバックの辺、次に既定に従います。各翻訳とその引数は、正確な {name} プレースホルダーの集合に一致する必要があります。これは ICU 式を使わない、リテラルの補間です。resolveMessage は、実際のソースロケールと方向を報告するため、RTL ページ内の英語フォールバックは lang=en と dir=ltr を保持できます。

数値整形は decimal/percent に対応します。日付整形は、明示的なエポックを使用し、既定は UTC です。複数形の選択は、呼び出し元によるメッセージ選択のために、Intl の基数・序数カテゴリーを返します。Intl のデータと対応状況はホストが管理します。validateLocalizedSurfaces は、マニフェスト・コマンド・設定・スキーマのキーと、テーマ表示の付随データを確認し、解決された表示長や不足する翻訳も対象にします。テーマの JSON/XML との互換性は維持されます。カタログの上限は、32 ロケール、256 キー、256 KiB です。静的ラベルにプレースホルダーは含められません。

/accessibility ヘルパーは、不足する名前、正規化後に重複するショートカット、ライト・ダークテーマでの明示的な不透明色ペアのコントラストを報告します。これらの報告を確認のヒントとして使い、OS のキー割り当てとアプリケーションのアクセシビリティー評価はホストが管理します。独立したサンプルには、EN/KO、一部のアラビア語、長いラベルのフィクスチャーが含まれます。スコープ付き設定、拒否・取り消し済みの参照、無効なフィールド、Ctrl+Enter、保留中コマンドの言語変更を試験します。ブラウザーのレイアウトは、デスクトップ・モバイルのサイズで、ライト・ダークテーマの両方を確認しました。

npm run example:configuration
npm run example:configuration-browser

設定 · シークレット参照 · コマンドスキーマ · ローカライズ

開発テンプレートと生成

6 つのテンプレート、正確なアーカイブ依存関係、生成内容のレビュー、競合の保持、doctor による確認。

完全な契約、サンプル、上限

決定的なテストとリプレイ

明示的な合成フィクスチャー、仮想時間、障害、範囲を限定したハッシュのみのトレース、リソースのクリーンアップ。

完全な契約、サンプル、上限

ローカル診断とデバッグ

明示的に有効化するローカルプロファイルと、一時的なループバックエンドポイント・合計期限を持つ、信頼された子デバッガー。

完全な契約、サンプル、上限

ホストの適合性

18 のバージョン付きプロファイルが、対応、非対応、失敗した契約を区別します。カスタムアダプターは、明示的な権限を保持します。

完全な契約、サンプル、上限

SDK のサポートと移行

エクスポート一覧、安定・任意・実験的機能のポリシー、正確な peer 条件、ランタイムの日付、移行サンプルを参照してください。

完全な契約、サンプル、上限

リリースの受け入れ

リリースの複合障害ワークロードと測定された性能基準は、独立した SDK の機能動作を示します。

完全な契約、サンプル、上限

1.1 依存関係、来歴、更新ツール

1.1.0 は、レビュー済み依存関係の決定的なオフラインバンドル、CycloneDX SBOM、操作者所有の Ed25519 キーによる分離署名、ダイジェストに関連付けた承認・有効化・ロールバック、明示的な上流比較を追加します。5 つの Node 専用エントリーポイントには、宣言、スキーマ、独立したサンプルが含まれます。ホストは署名の確認後に実行を明示的に許可し、古いジョブは元のハッシュを保持します。操作者が配布経路を選び、独立した SDK ツールから有効化、ロールバック、上流比較を呼び出します。

node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjs

バンドル、署名、更新、上流の完全なガイド

1.2 ワークフロー、キャッシュ、ツールストリーム、LSP

1.2.0 は、ステップごとのジョブ・権限付与を持つレビュー済みコマンド DAG、永続チェックポイント、明示的な新しい試行による復旧、決定的な内容ベースのキャッシュと増分実行、範囲を限定した UTF-8/JSONL/テキストのツールストリーム、任意の stdio LSP 3.17 ブリッジを追加します。7 つの新しいエントリーポイントにより、パッケージは 50 エクスポート、107 スキーマとなり、宣言と独立したインストール済みサンプルを備え、ランタイムの npm 依存関係は 0 です。ツールストリームのパーサーはブラウザーでも動作しますが、ワークフロー、ストア、外部プロセス、LSP には Node が必要です。実際のアダプターは TypeScript 5.9.3 と language-server 5.3.0 を使用して確認しました。LSP ブリッジはドキュメントのバージョンに関連付けた診断を受け付けます。操作者がワークフローの試行を明示的に確認・開始し、独立した SDK ホスト、ストア、外部プロセスを設定します。

node node_modules/@altifigence/dds-plugin-sdk/examples/workflows/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs

ワークフロー、キャッシュ、ツール、LSP の完全なガイド