DDS Plugin SDK

安裝公開的 DDS Plugin SDK 1.2,並使用工作流程、快取、工具串流、LSP 與穩定版 API。

以下的使用者工作區範例說明了明確連線且由客戶控制的開發主機。WSL 是這些範例的選用主機。一般 Digital Design Studio Windows 應用程式使用原生 Windows 檔案和共用 UI/WASM 執行階段。操作者為所選 SDK 主機設定探索、權限及外掛程式功能;受管理的 Cloud 引擎作業使用自己的執行模型。

1. 安裝 SDK

DDS Plugin SDK 1.2.1 提供 JavaScript API、TypeScript 宣告、語言提供者、佈景主題、工作區工具與命令工作。選用的持久儲存可加入工作歷程、明確重試,以及經驗證的文字/二進位快照;即使來源刪除或程序重新啟動,這些資料仍會保留。請使用 Node.js 22 或 24。從GitHub 官方版本安裝穩定版 SDK。若要建立獨立命令外掛,安裝後請使用開發工具:

1.0.0 發布穩定版 SDK API、18 個主機符合性設定檔、支援/遷移政策,以及經測量的混合工作負載檢查。新外掛使用 >=1.0.0 <2.0.0。已發布的功能驗證涵蓋 SDK API、主機符合性和混合工作負載。請使用這些結果評估版本檢查所驗證的 SDK 行為。

0.13.0 新增六個開發範本、產生的型別與結構描述、確定性測試情境,以及選用的本機診斷。封裝後的 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。診斷範圍使用從零開始的行號與 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

預期輸出(印出的行號與欄號從一開始):

文字

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。每個調色盤的六種顏色都是必填。選用的語意權杖可自訂搜尋、選取、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 種選用角色色彩,以及四個明確指定的尺寸參數。匯入前先將 XML 檔案儲存到本機。這些原創 SDK 範例採用 Apache-2.0;分享時請保留聲明。

請先從 設定 → 一般 → 外觀 → 匯出 XML 開始以備份您目前的佈景主題。匯入下載的 XML,審閱草稿,然後選擇 套用。取消變更 會保留已套用的佈景主題。切換淺色/深色外觀以審閱兩種調色盤。如需復原,請選擇內建佈景主題或匯入已儲存的複本。被拒絕的匯入會保留目前的佈景主題。

DDS、ALcad、共用編輯器、專案導覽、設定與彈出視窗,會使用該設定檔中的共用工作台調色盤。Cloud 與桌面版採用相同的佈景主題格式;請在各設定檔中分別匯入。gdsBackground 獨立控制 GDS 畫布。其他設計畫布、圖層與模擬色彩可有各自的設定。XML 承載此佈景主題設定檔的調色盤和外觀尺寸參數。

元素

規則

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

一個根元素;名稱去除頭尾空白後為 1–80 個 UTF-16 碼元;整份 XML 最多 65,536 個 UTF-8 位元組。

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

兩者皆為必填,各自包含下列六種顏色。

<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 背景位於顯示。請一起調整三種搜尋色彩,以保持易讀的對比。此片段應放在 v2 佈景主題內;請保留兩個完整調色盤:

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。降低透明度與強制色彩設定可能改變最終呈現。

每種顏色都必須是六位數的 #RRGGBB;Alpha、CSS 色彩名稱、變數、URL 與樣式皆會遭到拒絕。重複的鍵或模式、未知元素/屬性、命名空間、DTD、實體與處理指示也會遭到拒絕。允許 XML 宣告與註解。若匯入失敗,請檢查檔案大小、版本、兩個完整調色盤及支援值,再使用未變更的備份重試。其他編輯器的佈景主題必須轉換為此 DDS 格式。

6. 在您的環境中執行工作區

在您自己的 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}) 僅呼叫已設定的後端名稱。程序介接器會在 stdin 傳送有限制的 JSON,並預期 stdout 回傳 JSON。它不會使用要求所提供的 shell 命令,也不會繼承主機的任何環境變數。

遠端伺服器請使用您自己的已驗證 HTTPS 端點,或終止於本機回送位址的私人通道。請在您的環境中設定容器連接埠對應或 TLS。範例預設繫結回送位址;變更繫結位址並不會加入 TLS。受信任的外掛與工具會以主機程序的作業系統權限執行。

伺服器設定、來源、檔案修訂版本、取消與有限制結果的說明,請參閱使用者工作區範例與工作區通訊協定。

語言功能

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. 隨附的第二個範例使用包含 let name = value 的小型教學語言,檢查全部五項功能;範例本身的提供者實作該教學語言。

功能

要求輸入

結果資料

completion

position

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

hover

position

{text, range?} 或 null

definition

position

最多 500 個工作區相對的 {path, range} 位置

references

position,可選的 includeDeclaration

最多 500 個工作區相對的 {path, range} 位置

document-symbols

{}

最多 500 個平面的 {name, kind, range, selectionRange, detail?} 符號

位置使用從零開始的行號與 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?)

列出所選工作區根目錄下的一個目錄。

project.openFile(path, options?)

讀取檔案,並在編輯工作階段中保留其不可變的內容與修訂版本。

project.createFile(path, content, options?)

僅在檔案不存在時建立,然後回傳工作階段。

session.snapshot / session.state

讀取最後確認的 {path, content, revision} 及目前操作狀態。

session.save(content, options?)

僅在伺服器修訂版本仍與保留版本相符時儲存。

session.saveEdits(edits, options?)

對一份快照套用 {range, text} 編輯,接著執行一次經修訂版本檢查的儲存。

session.reload(options?)

衝突或寫入結果不確定後,明確讀取最新內容與修訂版本。

project.dispose() / session.dispose()

取消自身負責的工作;釋放專案後,呼叫端擁有的用戶端仍保持連線。

執行已安裝套件中的完整 HTTP 範例。它會建立自己的暫存範例工作區,測試編輯、發生衝突的第二個工作階段、明確重新載入、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 不會自動合併或重試。伺服器提交寫入後,仍可能發生逾時、取消或回應遺失;取消要求會保留已提交的變更。每個工作階段允許一個進行中的儲存或重新載入。

文字編輯使用原始快照、從零開始的行號與 UTF-16 位移。儲存前會拒絕重疊、切開代理對及無效範圍。專案最多允許 64 個已開啟或正在開啟的工作階段,每次儲存最多 500 次編輯。這些輔助工具使用未變更的工作區通訊協定 v1,包括 SDK 0.2.x 伺服器,並保留根目錄、受保護路徑與唯讀限制。生命週期與大小限制請參閱工作區專案。

API 參考

從 @altifigence/dds-plugin-sdk 匯入外掛 API。套件包含相同匯出項目的 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 Release

帶版本的封存檔、其外部版本 JSON、授權,以及任何必要的原始碼存取。

私人套件登錄或下載管道

相同的帶版本檔案、對象授權,以及實際的外掛條款。

資訊清單 v2 宣告 runtime、要求的權限與 source: {visibility, licenseFile, repository?}。將可見性設為 open 或 closed,並包含實際授權檔案。您擁有的程式碼可採用開源或專有條款;適用的 SDK 與相依套件聲明仍須遵守。接收者會收到可執行 JavaScript,以及宣告的原始碼可見性和授權中繼資料。

揭露欄位與散布要求請遵循發布與授權的說明。請透過所選 GitHub 版本、私人套件登錄或下載管道散布具版本的封存檔。

1.2.1 CLI 會在新外掛套件中記錄 >=1.0.0 <2.0.0。歷史 0.3–0.13 及精確的 1.0.0-rc.1 封存檔保留原始同儕相依版本。若要在穩定版安裝,請驗證並重新封裝新的外掛版本;發布者在重新封裝時明確更新所宣告的同儕版本範圍和版本中繼資料。

驗證下載的外掛

SDK 1.2.1 提供 dds-plugin verify,可驗證已發布的精確 0.3.x–0.13.x、RC1 及目前穩定版外掛中繼資料。請將 .tgz 與 .tgz.release.json 一起保留。驗證會保留原始同儕相依版本。檢查上述建立的套件:

驗證封裝的範例

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 字元小寫雜湊作為三個引數。checksumPinned 僅在提供的雜湊相符時為 true。限制為:12 MiB 壓縮輸入、10 MiB 檔案內容、每個檔案 4 MiB、256 個檔案,以及 256 KiB 外部中繼資料。

配對的中繼資料提供以雜湊為基礎的完整性:同時替換兩個檔案可產生新的相符雜湊。請透過受信任的發布管道確認發布者身分,檢閱程式碼中的惡意軟體,並由主機明確決定權限授予及 DDS 安裝資格驗證。收據描述該次呼叫讀取的位元組;若檔案在使用前可能變更,請重新檢查實際位元組。現有 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 工作區核准是技術上的存取決定。請將外掛條款接受及選用的個人資料同意記錄為不同的選擇。請依照 Apache-2.0 授權條款使用 SDK。

主機開發者可透過可攜式非同步輔助工具保留帶版本的聲明。例如,將此程式儲存為 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

請透過 GitHub Issues 回報 SDK 錯誤,並附上 SDK 版本與最小重現案例。SDK 採用 Apache-2.0 授權;請參閱儲存庫的授權與聲明。帶版本的封存檔與版本說明請使用版本頁面。

此儲存庫發布開發者 SDK。已宣告的 SDK 檔案、結構描述、範例與聲明構成其公開範圍。套件檢查會強制要求精確的已發布檔案清單,並拒絕已知的機密與私人路徑模式。請搭配模式檢查檢閱所選版本內容,識別散布檔案中揭露的資料。

安全更新與主機限制

請同時將工作區伺服器與 SDK 用戶端更新至 0.3.2 或更新版本。請安裝伺服器更新,以啟用升級後的檔案檢查和要求限制。重新啟動升級後的主機、檢閱其新世代,並再次取得核准後,才能使用工作區。

Node 工作區主機會拒絕可能指向受保護檔案或所選根目錄外檔案的硬連結。若專案檔案是刻意共用的,請將其複製成一般的單一連結檔案。以下憑證儲存也會遭到封鎖:.netrc、_netrc、.git-credentials、.gnupg、.kube 與 .docker,以及其他 SSH 金鑰名稱和 Windows 裝置別名。封裝與下載驗證會套用對應的憑證名稱政策。

伺服器資源

限制

同時傳入的本文

16;超額上傳會在派送前收到 HTTP 429

執行中的要求

64;取消使用獨立派送路徑

連線數/每個通訊端要求數

128 / 128

要求與回覆/檔案內容

1,600,000 / 262,144 個 UTF-8 位元組

到達期限或取消時,用戶端會取消尚未讀取的拒絕回應與停滯串流。寫入開始後逾時,可能導致結果不確定:重試前請重新讀取檔案。請搭配路徑排除檢閱檔案內容中的機密。受信任的外掛程式碼以主機程序的作業系統存取權限執行。部署主機時,請參閱安全升級指南與工作區限制。

開發工具

安裝上述 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。每次執行都有期限及 256 KiB stdout/stderr 上限。Ctrl+C 會停止監看並清理程序樹。子程序使用您的作業系統存取權限,並繼承您的環境。預設測試主機授予文件讀取和診斷權限;請為這些整合明確設定工作區主機及工作區/後端授權。

使用 --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 文字。重新載入、合併及儲存草稿由呼叫端明確執行,編輯儲存仍可能與保留的修訂版本衝突。路徑會依序逐一讀取;這是取樣觀察,因此中間的變更可能合併。此 API 對明確選取的檔案路徑取樣;呼叫應用程式負責目錄探索和重新命名處理。既有的根目錄、檔案大小與受保護路徑限制,適用於唯讀與可寫入伺服器。

檔案與工作觀察器都在第一次 next() 時啟動,取用端暫停時不會在背景取得頁面,且每個用戶端共用最多八個作用中的觀察器。允許一個進行中的 next();同時讀取會以 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;請檢查 state,不要將每個已解決的 promise 視為成功。

停止迭代器或逾時只會停止觀察。伺服器命令會繼續執行,直到完成或明確呼叫 cancelJob()。經主機核准重新連線後,請驗證工作區 ID 與世代相同,再使用儲存的工作 ID 與游標建立新觀察器。即使身分未變,舊觀察器仍失效。工作不存在/到期與傳輸失敗會直接回報,不會重新提交;記憶體內工作無法在主機重新啟動後保留。持久復原會搭配新連線使用 recoverJob();即時觀察器不會跨世代續接。

既有 v1 hello 與工作契約維持不變。檔案觀察在 0.3.2/0.4/0.5 主機上會回退;工作觀察需要已啟用的 0.4 或更新主機。主機針對不支援的工作回報錯誤,由呼叫端明確選擇後續命令。這些觀察 API 透過獨立 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);

請使用已連線且已授權的用戶端。尚未儲存的草稿應與此快取分開保留。條件式讀取會計算雜湊並回傳一份檔案快照;之後的讀取仍可能觀察到其他變更。儲存時使用回傳內容所屬的修訂版本。這些呼叫不會更新編輯工作階段快照或合併草稿。未變更的回覆沒有 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 測量中,20 次未變更的 200,000 位元組取樣,完整讀取回傳 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 與長度。用戶端每次最多讀取 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?}) 回傳標準 base64、區塊 SHA-256、精確範圍與 EOF 標記。/artifacts 的 decodeBinaryArtifactData 回傳 Uint8Array 位元組。瀏覽器取用端必須自行驗證完整檔案雜湊;個別區塊檢查無法證明組合後的輸出符合參照。

二進位與文字結果共用每個工作的 16 個配額與 ID 命名空間。二進位擷取/讀取操作,每個主機/工作區最多四個;Node 下載每個程序最多四個。Node 下載 timeoutMs 是總期限,預設最多 30 分鐘;requestTimeoutMs 預設 5 秒,最多 30 秒。發布需要 NTFS 或 ext4 等硬連結支援。請使用操作者控制下的受信任目的地並管理並行寫入者;檔案系統檢查使用主機程序的作業系統授權執行。

選用的 artifacts.capabilities、artifacts.list 與 artifacts.read 保留既有 v1 hello、工作快照與事件。早於 0.7 的主機回報擴充停用;由呼叫端明確選擇後續文字讀取或命令。驗證、格式錯誤回覆與傳輸錯誤仍屬錯誤。重新連線、撤銷、工作到期或主機世代變更會使舊操作失效。工作在記憶體內保留至終止工作的最後一個事件之後 15 分鐘。取消的工作可能留下記錄的部分工具輸出;請檢查工作終止狀態以確認成功。此處描述預設的即時/來源 API。下方獨立的儲存結果 API 可跨重新啟動保留位元組。

執行 npm run example:artifacts,進行實際 2 MiB 傳輸,涵蓋中斷、重新連線與僅續傳後綴;npm run benchmark:artifacts 使用 8 MiB。本機 Windows 執行以 129 次區塊要求傳輸 8,388,625 位元組,續傳 65,536 位元組前綴並驗證最終 SHA-256。Base64 會增加額外負擔;JSON 回應本文總計 11,257,419 位元組。此記憶體用量有限的傳輸保留檔案位元組,並使用 base64 傳輸。完整契約請參閱二進位產物。請使用獨立 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 小時,最多七天。移除與修剪是明確的主機操作。

本機儲存只有一個寫入者,會驗證工作區/根目錄身分並檢查中繼資料完整性。明確的過期鎖定復原,只會回收可證明已終止的同機 PID。未知/損壞檔案需人工檢查。在 Windows 上,檔案同步和重新命名支援程序重新啟動復原;請針對目標檔案系統個別驗證斷電行為。請參閱工作儲存、歷程與 durable-jobs 範例。

儲存結果與重新啟動後下載

啟用產物儲存後,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,保留期最多七天。區塊最多 64 KiB,允許四個同時讀取。inspect() 回報使用量、到期時間、無效項目與孤立檔案。remove(snapshot) 與 prune() 是明確的操作者操作。作用中的工作與個別讀取會被固定保留;區塊之間到期或移除可能使下一次讀取停止。選用的孤立檔案修剪僅移除可辨識的單一連結檔案。損壞或意義不明的項目需檢查。

檔案保留會獨立於記錄遮蔽,儲存實際專案位元組。請慎重選用。重新啟動後,仍需目前外掛/命令、套件雜湊、工作區與記錄的授權。完成維護後,依序等待 server.close()、artifacts.close() 與 store.close()。請在明確設定的獨立 SDK 主機中使用這些保留及關閉 API。

執行 npm run example:stored-artifacts,涵蓋實際子程序重新啟動、來源刪除、經驗證的部分下載續傳、歷程與明確重試。npm run example:durable-jobs 也涵蓋強制終止程序。請參閱儲存結果。已知 0.7 與更早主機會回報儲存停用,而不使用未知探測。既有即時/來源 API 保留原始行為。

觀察專案

操作者在伺服器上明確啟用專案,並選擇允許的根目錄。預設停用。已知 SDK 0.3–0.8 主機會回報不可用,而不發出新的探索探測。支援的檔案系統設定檔為 Windows/Linux 本機儲存。此獨立 SDK 範例使用明確設定的主機/用戶端。

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();

第一個事件是完整快照。後續變更會攜帶相對於先前修訂版本的差異;提示遺失、初始掃描期間的變更、掃描不完整及取用端過慢造成溢位,都會產生附有原因的完整重新同步檢視。重新命名可能以刪除/建立呈現。每個檔案分別驗證。快照修訂版本描述取樣的檔案狀態,兩次取樣之間的中間寫入可能合併。

伺服器與用戶端各允許四個訂閱,每個原生訂閱可排入四個事件。預設閒置租約為 30 秒;較晚的讀取可能回傳 not_found。長時間暫停後,請建立新的迭代器以取得初始快照。break/return、取消與釋放會解除訂閱;若連線中斷導致無法清理,剩餘遠端資源會隨租約到期。

預設掃描限制為深度 8、512 個項目、每個檔案 1 MiB、總計 16 MiB 與 10 秒。可設定的上限為深度 32、1,000 個項目、每個檔案 16 MiB、總計 64 MiB 與 30 秒。受限制的檔案可能只有中繼資料而沒有內容雜湊;請檢查 complete 與 reasons。期限在檔案系統呼叫之間檢查;請為這些呼叫有意選擇主機程序的作業系統存取權限。

專案樹與搜尋

listTree 回傳樹狀結構,searchFiles 以字面子字串或有限制的 glob 搜尋相對檔名,searchText 則在 UTF-8 檔案中尋找字面文字。root 為必填;include/exclude 相對於 root。請使用支援的字面和有限制的 glob 搜尋模式。不區分大小寫的比對僅轉換 ASCII A–Z,因此原始 UTF-16 位置保持穩定。

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、從零開始的 UTF-16 範圍,以及有限制的片段。游標會凍結原始成員集合最多 60 秒,且需要相同查詢。後續頁面重新檢查目前內容,並將項目標記為 current、changed、missing 或 unverified;新檔案只會出現在新查詢中。已擷取的符合項目與修訂版本保持不變。

文字檔案上限為 256 KiB,查詢為 256 個 UTF-16 碼元,片段為 512 個碼元。預設為 256 筆結果(最多 512)、每頁 32 個項目(最多 64),及 64 KiB 回應(最多 128 KiB)。二進位檔案、無效 UTF-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 不同時,請釋放舊游標,並重複相同的 root/filter 查詢。觀察絕不會變更 edit.snapshot 或呼叫端擁有的草稿內容。外部變更、移動或刪除後,原始 CAS 條件會回報衝突;呼叫端選擇明確重新載入、合併或另存。

用戶端會檢查連線世代、root/filter、查詢雜湊、頁面位置、快照 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 要求預設為五秒;較大型掃描請明確設定用戶端與伺服器逾時。

專案觀察 · 樹狀結構/搜尋契約 · 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);

可在瀏覽器安全使用的輔助工具,一次最多接收一個 64 KiB 區塊,等待所選接收端,並增量計算完整檔案雜湊。寫入前會驗證精確範圍、身分、base64 與每個區塊雜湊。回讀接收端接著會獨立重新讀取儲存的位元組;只有兩個完整雜湊都相符後,verification 才是 stored。沒有回讀時,verification 是 received,storedSha256 為 null。進度達到全部位元組不代表完成。

應用程式選擇檔案控制代碼或 OPFS 目錄,並授予所需權限。請向 SDK 介接器提供所選目的地及其存取授權;應用程式負責選取器互動和目的地選擇。非同步檔案/OPFS 可寫入接收端會保留暫存直到 close,並在提交前失敗時捨棄。若部分下載需要在重新載入後保留,請使用下方專用 Worker 介接器。檔案上限為 1 GiB,允許四個直接同時串流,總期限為 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 工作區、隔離暫存目錄、允許的根目錄與一個主體,再將 workspace.write 授予所選外掛,並繫結至其精確封存檔固定雜湊。輔助工具會在開始前先計算所選來源的雜湊。伺服器依序接受 64 KiB 區塊、驗證重複區塊與完整內容,並僅在條件式目標檢查後提交。暫存位元組不會出現在一般工作區清單中。

expectedRevision: null 要求目標不存在;SHA-256 則要求與目前目標相符。取消會保留已確認的伺服器前綴。新的明確 recover 操作會查詢目前授權、驗證相同來源/規格,並僅續傳相符的前綴。提交回應遺失時,在查詢前結果仍不確定;這不代表可以重複提交或回復檔案。上限為每個檔案 1 GiB、每個儲存 4 GiB,以及四個作用中工作階段;預設值較低。已知 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,並取得新的已核准儲存參照。接收端儲存兩個精確的資料/中繼資料檔名、完整不可變快照身分、到期時間,以及目前/前次前綴雜湊。它不儲存權杖、授權或舊連線範圍。每個資料區塊都會在小型中繼資料串流關閉前完成 flush。

接收端與輔助工具都會獨立重新計算前綴雜湊。只有記錄的前綴相符後,才會裁切尚未建立檢查點的尾端。若中繼資料超過實際檔案大小,只有位元組與雜湊皆相符時,才能回退至先前檢查點;損壞、項目遺失、到期或快照不同,都會失敗而不悄悄重新啟動。整個來源範圍的獨占鎖定會拒絕另一個分頁,在回讀期間持續持有,並在 close 或 Worker 終止時釋放。之後重新開啟需要明確復原。

本機中繼資料上限為 16 KiB,允許四個已開啟接收端工作階段。保留預設為一小時,上限為 24 小時,且不得超過主機快照到期時間。儲存遵循瀏覽器配額、資料逐出及同源指令碼授權。檢查點復原模型涵蓋下文測試的程序中斷情境;請在部署環境中驗證斷電行為。Windows 上的 Chromium 154 已測試取消、重新載入、主機重新啟動、雙分頁衝突及擁有者分頁終止,並檢查完整儲存檔案雜湊。請在每個目標瀏覽器/作業系統組合上執行資格驗證情境。

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 參數標籤位移。補全解析會保護提供者資料、回傳一次性主機權杖,並固定所選標籤/插入內容/範圍。權杖繫結提供者、範圍與文件,60 秒後到期,限制為 128 個項目、4 MiB 與四個實際解析器操作。文件/提供者變更會捨棄權杖。

片段支援 $n、${n}、${n:literal}、$0 及文件列出的跳脫,包含鏡像與有順序的定位點。變數、巢狀、選項、轉換與可執行命令皆會遭到拒絕。會檢查 UTF-16/CRLF 邊界與重疊的額外編輯。提供者作為受信任的程序內程式碼,以主機程序授權執行;若忽略取消,實際進行中的配額仍會被占用,直到提供者完成。

經審閱的工作區編輯與重新命名

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);

呼叫端使用已連線、已授權的工作區用戶端與受信任的日誌。預覽包含完整前後快照與摘要;套用需要經審閱的 planId/digest,以及回傳 true 的目前主機政策。每個檔案都會預先檢查,接著各操作使用既有的逐檔 CAS 與目前寫入/管理功能。日誌在每次變動前持久儲存並回讀意圖,之後記錄收據。衝突或不確定性會停止後續寫入;每個檔案保留自己的 CAS 交易邊界。

選用的 workspace-edits-node 介接器會將有限制的日誌儲存在所選工作區外,繫結其身分,並使用單一寫入者鎖定、一般檔案與檢查碼檢查點。程序終止後,recoverStaleLock 必須明確選用,且只回收已證明終止的擁有者。復原會依目前位元組回報 applied/not-applied/conflicted/unknown;由呼叫端明確決定後續操作。補償會建立新的反向提案以供重新審閱。在 Windows 上,介接器會同步檔案並執行重新命名操作;檢查涵蓋程序終止和復原,持久性由檔案系統及儲存裝置決定。限制包括 32 項變更、1,000 次編輯、每個檔案 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,或恰好一個目前檔案編輯,並附目前快照雜湊。範圍編輯必須留在選取範圍內。endOfLine 為插入文字選擇 preserve、lf 或 crlf;未編輯位元組保持不變。內容相同的提案會正規化為 null。prepareFormatting 不執行寫入。

主機會將動作要求與解析權杖繫結至已接受的診斷修訂版本與目前快照。後續診斷發布、文件變更或提供者釋放會使舊選取失效。亂序的診斷呼叫不會覆寫較新的已接受組合。最多 100 個動作可帶有純文字標籤、有限制的診斷索引、建議編輯、私人解析資料或停用原因。未知的命令/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);

語意權杖使用具唯一名稱及九個主機擁有樣式鍵的圖例,每個權杖另有五個整數:行/起點差異、UTF-16 長度、型別索引與修飾位元。權杖不得重疊、切開代理對、跨行或超出目前文件。主機一律回傳完整正規化陣列與主機 UUID,updateKind 為 full/delta/fallback。獨立的 semantic-tokens-delta 功能可針對提供者擁有的先前資料啟用 provideDelta;快取儲存身分與權杖資料,不儲存舊文件文字。

快取基準繫結提供者、範圍、URI 與語言,最多八個項目、4 MiB 與 60 秒。一般遞增的文件版本會保留可能的差異基準,同時使舊顯示結果過期。基準遺失/到期、null 差異或提供者基準 ID 不符時,允許在原始逾時內最多一次完整回退。無效資料或提供者錯誤會失敗,不會重試。停用、取消註冊與替換文件會清除受影響基準。呈現前請立即呼叫 validateLanguageResult;複製、釋放或過期的物件會失敗。

限制為 20,000 個語意權杖、64 種權杖型別、16 個修飾符與 64 個差異編輯;摺疊允許 1,000 個範圍、深度 32,並拒絕交錯範圍。行內提示允許在要求範圍內有 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 模組提供操作者擁有、供一個外掛使用的記憶體儲存。帶版本的定義宣告每個鍵、資料結構描述、預設值、允許的使用者/工作區範圍及顯示中繼資料。有效值會依 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 會從某一層移除鍵;readOnly 需要預設值且沒有可寫入範圍。訂閱會合併同步變更並回傳可釋放控制代碼。明確的 migrate(nextDefinition, callback, options) 會驗證下一個狀態,且僅在修訂版本仍相符時提交。失敗、取消或逾時會保留舊定義與狀態。匯出/匯入是純資料;持久儲存與加密由操作者負責。限制包括 64 個鍵、32 個工作區層、1 MiB 匯出狀態,以及一個實際遷移。

工作區外掛宣告 settings 與 settings.read,操作者以該授權掛載相符儲存。context.settings 是唯讀,並繫結至外掛與所選工作區。/secrets 解析器另行為外掛、工作區、命令允許清單與存續時間發出不透明參照。資訊清單必須宣告 secrets.resolve,且主機必須授予此權限。輸入欄位使用 type: object 搭配 format: dds-secret-reference;一般字串與外觀相似的物件不具機密授權。

只有經驗證輸入中的參照,才能透過命令的 options.secrets.withSecret 使用。每次執行都有新 ID;解析器會在解析與回呼前後檢查範圍、到期、撤銷及目前授權。回呼回傳 undefined,並接收一份在中止及每次離開時清除的副本。提供者錯誤會經過淨化。請先取得租約,再執行需要該授權的效果。參照預設存續 60 秒,最多一小時;限制為 128 個參照、8 個實際租約及 16 KiB 機密資料。請僅以主機程序授權執行受信任的程式碼,因為這類程式碼可保留副本。絕不要把機密資料放入設定、組合、記錄或結果;處理機密時,請明確分類任意應用程式字串。

結構化命令結構描述與表單

命令可使用 schemaVersion: 1 封套宣告 inputSchema 與 outputSchema。仍支援現有基本型別參數;同時宣告 parameters 與 inputSchema 會遭到拒絕。主機會在啟動處理函式或工作前驗證並套用輸入預設值,再在發布成功前驗證輸出。絕不套用輸出預設值。新的結構描述/顯示中繼資料需要理解 0.12 的同儕端;較舊的嚴格驗證器會拒絕,而舊定義保留既有行為。

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 基底標籤與明確、無循環的回退邊。最多八個偏好設定會先協商精確標籤,再尋找父層與預設值。預設語系定義所有鍵;翻譯可省略鍵,但不能新增鍵。逐鍵查找依序沿著回退邊,再查找預設值。每個翻譯及其引數都必須符合精確的 {name} 預留位置集合。這是字面插值,不含 ICU 運算式。resolveMessage 回報實際來源語系與方向,因此 RTL 頁面內的英文回退可以保留 lang=en 與 dir=ltr。

數字格式化支援十進位/百分比;日期格式化使用明確紀元時間,預設為 UTC;複數選擇回傳 Intl 基數/序數類別,供呼叫端選擇訊息。主機負責 Intl 資料與支援。validateLocalizedSurfaces 檢查資訊清單/命令/設定/結構描述鍵與佈景主題顯示附屬資料,包括解析後顯示長度與缺少翻譯。佈景主題 JSON/XML 仍相容。目錄限制為 32 個語系、256 個鍵與 256 KiB;靜態標籤不得包含預留位置。

/accessibility 輔助工具回報缺少名稱、重複的正規化快捷鍵,以及淺色/深色佈景主題中明確的不透明色彩組合對比。請在實作由主機負責的作業系統按鍵繫結及評估無障礙性時使用這些提示。獨立範例包含 EN/KO、部分阿拉伯文及長標籤測試資料。它測試具範圍的設定、拒絕/撤銷參照、無效欄位、Ctrl+Enter,以及命令進行中變更語言。瀏覽器配置已在桌面/行動裝置尺寸與淺色/深色佈景主題下檢查。

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

設定 · 機密參照 · 命令結構描述 · 在地化

開發範本與產生

六個範本、精確封存檔相依項目、產生審閱、衝突保留與 doctor 檢查。

完整契約、範例與限制

確定性測試與重播

明確的合成測試資料、虛擬時間、故障、有限制且僅含雜湊的追蹤,以及資源清理。

完整契約、範例與限制

本機診斷與偵錯

需主動選用的本機設定檔,以及具短暫回送端點與總期限的受信任子程序偵錯器。

完整契約、範例與限制

主機符合性

18 個帶版本設定檔區分支援、不支援與失敗的契約;自訂介接器保留明確授權。

完整契約、範例與限制

SDK 支援與遷移

請參閱匯出清單、穩定/選用/實驗政策、精確同儕相依項目、執行階段日期與遷移範例。

完整契約、範例與限制

版本驗收

已發布的版本檢查結合故障工作負載和經測量的效能防護,驗證所測試的 SDK 行為。

完整契約、範例與限制

1.1 相依項目、來源與更新工具

1.1.0 新增已審閱相依項目的確定性離線組合、CycloneDX SBOM、使用操作者擁有 Ed25519 金鑰的分離簽章、繫結摘要的核准/啟用/回復,以及明確的上游比較。五個僅限 Node 的進入點包含宣告、結構描述與獨立範例。主機明確授予執行權限,舊工作保留原始雜湊。操作者管理散布、部署和監控。請使用獨立範例驗證組合、簽章、更新和上游契約。

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 橋接。七個新進入點使套件達到 50 個匯出與 107 個結構描述,附宣告與獨立安裝範例,且執行階段 npm 相依項目為零。工具串流剖析器也可在瀏覽器運作;工作流程、儲存、外部程序與 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 指南