DDS Plugin SDK

Cài đặt DDS Plugin SDK 1.2 công khai và sử dụng quy trình công việc, bộ nhớ đệm, luồng công cụ, LSP và các API ổn định.

Các ví dụ không gian làm việc người dùng bên dưới mô tả máy chủ phát triển do khách hàng kiểm soát được kết nối rõ ràng. WSL là một máy chủ tùy chọn cho các ví dụ đó. Ứng dụng Windows Digital Design Studio thông thường sử dụng tệp Windows gốc và bộ chạy UI/WASM dùng chung. Người vận hành cấu hình khám phá, quyền và khả năng plugin cho máy chủ SDK đã chọn; tác vụ bộ máy Cloud được quản lý dùng mô hình thực thi riêng.

1. Cài SDK

DDS Plugin SDK 1.2.1 cung cấp API JavaScript, khai báo TypeScript, nhà cung cấp ngôn ngữ, chủ đề, công cụ không gian làm việc và tác vụ lệnh. Kho bền vững tùy chọn thêm lịch sử tác vụ, thử lại rõ ràng và bản chụp văn bản/nhị phân đã xác minh còn tồn tại sau khi xóa nguồn và khởi động lại tiến trình. Dùng Node.js 22 hoặc 24. Cài bản SDK ổn định từ bản phát hành GitHub chính thức. Với plugin lệnh độc lập, dùng Công cụ phát triển sau khi cài:

1.0.0 công bố API SDK ổn định, 18 hồ sơ kiểm tra tính phù hợp máy chủ, chính sách hỗ trợ/chuyển đổi và kiểm tra khối lượng kết hợp đã đo. Plugin mới dùng >=1.0.0 <2.0.0. Kiểm chứng chức năng đã công bố bao trùm API SDK, tính phù hợp của máy chủ và khối lượng kết hợp. Dùng các kết quả đó để đánh giá hành vi SDK được kiểm tra trong bản phát hành.

0.13.0 thêm sáu mẫu phát triển, kiểu và schema được sinh, kịch bản kiểm tra xác định và chẩn đoán cục bộ tùy chọn. SDK đóng gói và dự án được sinh chạy ngoài cây nguồn; phát lại tổng hợp và gỡ lỗi loopback được chọn rõ ràng.

0.12.0 thêm thiết lập có kiểu theo phạm vi và chuyển đổi rõ ràng, tham chiếu bí mật theo phạm vi thực thi, đầu vào/đầu ra lệnh có cấu trúc, danh mục ngôn ngữ và siêu dữ liệu khả năng tiếp cận. SDK công khai và ví dụ độc lập kiểm tra xung đột thiết lập, đầu vào không hợp lệ, thẩm quyền bị thu hồi và phương án dịch dự phòng. Sử dụng các tính năng này thông qua API máy chủ SDK độc lập và các ví dụ độc lập.

0.11.0 thêm trợ giúp chữ ký, hoàn thành lười, đoạn mã giới hạn, chỉnh sửa nhiều tệp và đổi tên có xem xét, định dạng/hành động mã, token ngữ nghĩa, gấp mã, gợi ý và ký hiệu phân cấp. Đề xuất trải qua xem xét và kiểm tra thẩm quyền hiện tại trước khi áp dụng có điều kiện; hiển thị và áp dụng cần kết quả tài liệu hiện hành. Ví dụ độc lập kiểm tra các tính năng này trong máy chủ SDK công khai được cấu hình rõ ràng.

0.10.0 thêm tải xuống theo luồng trong trình duyệt, tải lên tệp được chọn, hàng đợi truyền hỗn hợp và phục hồi điểm kiểm tra Worker OPFS. Truyền dữ liệu kiểm tra thẩm quyền hiện tại, danh tính tệp và hàm băm khối/toàn tệp, đồng thời tách tiến độ byte khỏi lưu trữ đã xác minh. Dùng các ví dụ SDK công khai này với máy chủ được cấu hình rõ ràng và tích hợp do ứng dụng quản lý.

0.9.0 thêm cây dự án theo phạm vi, tìm tên tệp/văn bản và quan sát thay đổi cho thư mục cục bộ do người vận hành chọn. Dùng chúng từ ứng dụng khách HTTP hoặc trình trợ giúp dự án, đồng thời giữ bản chụp chỉnh sửa và bản nháp chưa lưu. Ví dụ dự án bên dưới bao gồm tạo, tìm kiếm, thay đổi bên ngoài và xử lý xung đột.

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"

Ví dụ chẩn đoán đầu tiên dùng mã đáng tin cậy trong máy chủ thử nghiệm cục bộ. Chủ đề dùng cơ chế nhập XML DDS hiện có. Với tích hợp công cụ hiện có, xem Plugin và công cụ bên thứ ba.

2. Viết plugin đầu tiên

Tạo plugin.mjs trong dự án mới. Plugin này kiểm tra các tài liệu văn bản thuần túy và báo cáo chẩn đoán thông tin trên mỗi dòng chứa 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);
  },
}));

Manifest khai báo phiên bản giao thức 1, khả năng diagnostics, máy chủ test-host và các quyền document.read cùng diagnostics.publish. Nhà cung cấp nhận bản chụp tài liệu và AbortSignal. Phạm vi chẩn đoán dùng dòng tính từ 0 và độ lệch ký tự UTF-16.

3. Chạy cục bộ

Tạo run.mjs cạnh plugin.mjs. Kích hoạt plugin, cung cấp tài liệu và yêu cầu chẩn đoán. Luôn giải phóng máy chủ khi hoàn tất.

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

Đầu ra dự kiến (dòng và cột được in tính từ 1):

Văn bản

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

4. Kiểm tra plugin

Lưu kiểm tra này thành plugin.test.mjs. Nó kiểm tra phạm vi chẩn đoán và xác nhận chỉnh sửa tài liệu xóa chẩn đoán.

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

Kiểm tra phải thành công. Thêm dữ liệu mẫu cho ngôn ngữ riêng, hủy, kết quả không hợp lệ và tài liệu lớn. Giữ phiên bản tài liệu hiện tại để từ chối kết quả từ bản chụp trước.

5. Tạo và áp dụng chủ đề

Lưu bảng màu sáng/tối này dưới dạng theme.json. Sáu màu trong mỗi bảng màu là bắt buộc. Các token ngữ nghĩa tùy chọn tùy chỉnh tìm kiếm, lựa chọn, HintsBox và canvas GDS; các token bị bỏ qua sẽ sử dụng giá trị mặc định của 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
    }
  }
}

Tạo export-theme.mjs cạnh nó. parseTheme xác minh dữ liệu màu và serializeThemeXml xuất XML DDS phiên bản 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

Lệnh ghi hello-theme.xml và in Created hello-theme.xml. Trong DDS, mở Plugins → Thiết lập chủ đề..., chọn XML rồi chọn Áp dụng cho Hello Ocean. Chuyển giữa giao diện sáng và tối để xem cả hai bảng màu.

Bạn cũng có thể dùng Cài đặt → Chung → Giao diện → Nhập XML. Lưu chủ đề hiện tại bằng Xuất XML trước khi thay thế. Thao tác này nhập dữ liệu giao diện XML vào cấu hình chủ đề.

Tài liệu hướng dẫn chủ đề liệt kê mọi token và chỉ số được hỗ trợ. Ví dụ Hello Ocean bao gồm chủ đề đầy đủ, XML sẵn sàng nhập và bản xem trước HTML cục bộ.

Tham chiếu XML chủ đề

Tải XML Hello Ocean và JSON có thể sửa của nó. XML chứa bảng màu sáng và tối đầy đủ, tất cả 28 màu vai trò tùy chọn trong mỗi chế độ và bốn chỉ số rõ ràng. Lưu tệp XML cục bộ trước khi nhập. Các ví dụ SDK gốc này dùng Apache-2.0; giữ thông báo khi chia sẻ chúng.

Bắt đầu với Cài đặt → Chung → Giao diện → Xuất XML để sao lưu chủ đề hiện tại. Nhập XML đã tải, xem bản nháp rồi chọn Áp dụng. Hủy thay đổi giữ chủ đề đã áp dụng. Chuyển giao diện sáng/tối để xem cả hai bảng màu. Để phục hồi, chọn chủ đề tích hợp hoặc nhập bản đã lưu. Nhập bị từ chối giữ nguyên chủ đề hiện tại.

DDS, ALcad, trình soạn thảo dùng chung, điều hướng dự án, thiết lập và cửa sổ bật lên dùng bảng màu workbench chung trong hồ sơ đó. Cloud và máy tính dùng cùng định dạng chủ đề; nhập riêng trong từng hồ sơ. gdsBackground điều khiển canvas GDS độc lập. Màu canvas thiết kế, lớp và mô phỏng khác có thể có thiết lập riêng. XML mang bảng màu và thông số giao diện cho hồ sơ chủ đề này.

Phần tử

Quy tắc

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

Một gốc; tên sau khi bỏ khoảng trắng đầu/cuối dài 1–80 đơn vị mã UTF-16; tối đa 65536 byte UTF-8 cho toàn bộ XML.

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

Cả hai bắt buộc, mỗi bảng có sáu màu bên dưới.

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

Ghi đè v2 tùy chọn. Vai trò bỏ qua theo mặc định DDS cho chế độ đó.

<metrics>

Ghi đè số v2 tùy chọn.

Phiên bản 1

Chỉ hai bảng màu. Tệp v1 hiện có vẫn được hỗ trợ; trình xuất SDK tạo v2.

Khóa bảng màu bắt buộc

Công dụng

backdrop

Nền ngoài không gian làm việc

navigation

Điều hướng dự án

tool

Bảng công cụ và điều khiển

main

Không gian làm việc chính và thiết lập

text

Văn bản chính

muted

Văn bản phụ

Khóa vai trò tùy chọn (28)

Công dụng

search, searchText, searchPlaceholder

Nền, văn bản và gợi ý tìm kiếm dùng chung

searchBorder

Trường tương thích; ô tìm kiếm chung hiện tại không có viền

selection, selectionText

Hàng được chọn và văn bản

tabActive, tabInactive, tabText

Tab trình soạn thảo

rail, panelBorder, popover

Thanh công cụ, ranh giới bảng và cửa sổ bật lên

focus

Viền tiêu điểm bàn phím

success, warning, danger, info, aiBall

Màu trạng thái và nền quả cầu AI

hintsBoxBackground, hintsBoxDetailsBackground

Nền gợi ý và chi tiết

hintsBoxText, hintsBoxDetailsText, hintsBoxMutedText

Văn bản gợi ý, chi tiết và phụ

hintsBoxSelectedBackground, hintsBoxSelectedText

Gợi ý được chọn bằng bàn phím

hintsBoxHoverBackground, hintsBoxHoverText

Gợi ý được trỏ chuột

gdsBackground

Nền canvas trình xem GDS

HintsBox là tính năng gợi ý mã dùng chung. Tìm màu của nó trong Tùy chỉnh → Màu sắc và hình dạng chi tiết → HintsBox và nền GDS trong Hiển thị. Sửa cả ba màu tìm kiếm cùng nhau để có độ tương phản dễ đọc. Đoạn này nằm trong chủ đề v2; giữ hai bảng màu đầy đủ:

Đoạn XML v2

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

Chỉ số

Giá trị cho phép

Mặc định DDS hiện tại

panelRadius

Số nguyên 0–24

14

controlRadius

Số nguyên 0–16

6

popoverRadius

Số nguyên 0–24

16

popoverOpacity

Số 0,6–1

0,72

Viết chỉ số dạng <number key="popoverOpacity" value="0.9"/> bên trong <metrics> không kèm đơn vị. Giá trị bán kính tính bằng pixel. SDK để chỉ số bị bỏ qua ở trạng thái vắng mặt; bản DDS đã cài cung cấp mặc định. Đặt giá trị rõ ràng để giao diện nhất quán. Hello Ocean chủ động đặt 16, 8, 12 và 0,9. Thiết lập giảm độ trong suốt và màu bắt buộc có thể thay đổi hiển thị cuối cùng.

Mỗi màu phải có dạng sáu chữ số #RRGGBB; alpha, tên CSS, biến, URL và style bị từ chối. Khóa hay chế độ trùng, phần tử/thuộc tính không biết, namespace, DTD, entity và chỉ dẫn xử lý bị từ chối. Khai báo và chú thích XML được phép. Nếu nhập thất bại, kiểm tra kích thước, phiên bản, hai bảng màu đầy đủ và giá trị được hỗ trợ, rồi thử lại với bản sao lưu không đổi. Chủ đề từ trình soạn thảo khác cần chuyển sang định dạng DDS này.

6. Chạy không gian làm việc trong môi trường của bạn

Chạy máy chủ, SDK, plugin và công cụ trong môi trường WSL, container hoặc máy chủ của bạn. Tệp dự án ở dưới gốc bạn chọn. Ứng dụng khách SDK độc lập đọc và sửa chúng qua kết nối; nó nhận siêu dữ liệu plugin và kết quả lệnh, trong khi mã plugin chạy trong môi trường của bạn.

Trong dự án SDK vừa tạo, lưu trình trợ giúp này thành copy-workspace-example.mjs. Nó sao chép máy chủ, plugin, công cụ và dự án mẫu có thể sửa, đồng thời giữ bố cục tệp giấy phép của ví dụ.

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

Dự án mẫu là user-host/examples/user-workspace/project. Khởi động máy chủ trong môi trường đó bằng token được sinh rõ ràng:

WSL / Linux / container

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

Máy chủ in Workspace server: http://127.0.0.1:4777/dds/workspace/v1 cùng ID và thế hệ không gian làm việc. Trong terminal của ứng dụng khách, đặt DDS_WORKSPACE_TOKEN thành token được sinh. Đây là thông tin xác thực người vận hành, riêng với token DDS Account. Dừng máy chủ mẫu bằng Ctrl+C.

Từ terminal khác trong cùng dự án, đặt DDS_WORKSPACE_TOKEN thành cùng bí mật rồi chạy ứng dụng khách phát triển:

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

Ứng dụng khách liệt kê tệp mẫu và chạy Kiểm tra tệp dự án cho design.sv. Kết quả JSON bao gồm tool: "module-counter" và modules: 1, do tiến trình con thực tạo ra. Chỉ thêm --edit vào lệnh ứng dụng khách khi bạn muốn ví dụ thêm ghi chú vào tệp mẫu.

Để dùng dự án riêng, truyền thư mục tuyệt đối của nó làm đối số cuối cho server.mjs. Giữ máy chủ, mô-đun plugin và công cụ đã cài trong cùng môi trường người dùng đó. server.mjs nhập plugin rõ ràng và ánh xạ backend có tên tới tệp thực thi và đối số cố định:

Ánh xạ backend server.mjs

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

Thay ánh xạ này bằng công cụ đã cài được phê duyệt hoặc backend tùy chỉnh. ctx.workspace.readFile và writeFile dùng đường dẫn tương đối với gốc đã chọn; ctx.backends.invoke("module-counter", input, {signal}) chỉ gọi tên backend đã cấu hình. Bộ điều hợp tiến trình gửi JSON có giới hạn trên stdin và chờ JSON trên stdout. Nó không dùng lệnh shell do yêu cầu cung cấp và không kế thừa biến môi trường từ máy chủ.

Với máy chủ từ xa, dùng điểm cuối HTTPS đã xác thực riêng hoặc đường hầm riêng kết thúc ở loopback cục bộ. Cấu hình ánh xạ cổng container hoặc TLS trong môi trường của bạn. Ví dụ mặc định bind loopback; đổi địa chỉ bind không thêm TLS. Plugin và công cụ đáng tin cậy chạy với thẩm quyền hệ điều hành của tiến trình máy chủ.

Xem ví dụ không gian làm việc người dùng và giao thức không gian làm việc để biết cấu hình máy chủ, origin, phiên bản tệp, hủy và kết quả giới hạn.

Tính năng ngôn ngữ

SDK 0.7.0 cung cấp hoàn thành, hover, định nghĩa, tham chiếu và ký hiệu tài liệu phẳng. Khai báo từng tính năng trong khả năng manifest v2, cùng quyền document.read và language.provide. Máy chủ phải cấp rõ cả hai quyền. Lưu ví dụ hover đầy đủ này thành language-demo.mjs trong dự án đã tạo:

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

Lệnh đầu in A local LED signal. Ví dụ thứ hai đóng gói kiểm tra cả năm tính năng bằng ngôn ngữ giảng dạy nhỏ với let name = value; nhà cung cấp riêng của ví dụ triển khai ngôn ngữ giảng dạy đó.

Tính năng

Đầu vào yêu cầu

Dữ liệu kết quả

completion

position

Tối đa 500 {label, insertText, detail?, range?} mục

hover

position

{text, range?} hoặc null

definition

position

Tối đa 500 vị trí {path, range} tương đối với không gian làm việc

references

position, tùy chọn includeDeclaration

Tối đa 500 vị trí {path, range} tương đối với không gian làm việc

document-symbols

{}

Tối đa 500 ký hiệu {name, kind, range, selectionRange, detail?} phẳng

Vị trí dùng dòng tính từ 0 và độ lệch UTF-16. Chèn hoàn thành là văn bản nguyên dạng; chuỗi hover và chi tiết là văn bản thuần. Máy chủ phải kiểm tra tệp và phạm vi đích trước khi theo vị trí. Kết quả giữ danh tính yêu cầu, dự án/phiên và phiên bản tài liệu. Sửa bản chụp, hủy, hết thời gian, hủy đăng ký hoặc giải phóng kết thúc yêu cầu chờ và bỏ kết quả đến muộn.

Các API này hoạt động trong máy chủ SDK đáng tin cậy. Ứng dụng máy chủ tích hợp hiển thị tính năng ngôn ngữ và cấu hình tiến trình LSP một cách rõ ràng. Khả năng mới cần máy chủ phiên bản 0.3.0 trở lên. Đọc Tính năng ngôn ngữ để biết bộ chọn, giới hạn và hành vi vòng đời.

Phiên chỉnh sửa dự án

Nhập createWorkspaceProject và applyTextEdits từ @altifigence/dds-plugin-sdk/workspace-client. Sau khi máy chủ kết nối createWorkspaceClient và xem xét danh tính, thông báo và quyền không gian làm việc, gọi createWorkspaceProject(client). Dự án giữ chính xác ràng buộc kết nối. Kết nối lại yêu cầu dự án mới đã xem xét, ngay cả khi cùng ID và thế hệ không gian làm việc trả về.

API

Hành vi

project.listFiles(path?, options?)

Liệt kê một thư mục dưới gốc không gian làm việc đã chọn.

project.openFile(path, options?)

Đọc tệp và giữ nội dung bất biến cùng phiên bản trong phiên chỉnh sửa.

project.createFile(path, content, options?)

Chỉ tạo khi tệp chưa tồn tại, rồi trả về phiên.

session.snapshot / session.state

Đọc {path, content, revision} được xác nhận gần nhất và trạng thái thao tác hiện tại.

session.save(content, options?)

Chỉ lưu nếu phiên bản máy chủ vẫn khớp phiên bản đã giữ.

session.saveEdits(edits, options?)

Áp dụng chỉnh sửa {range, text} trên một bản chụp rồi thực hiện một lần lưu có kiểm tra phiên bản.

session.reload(options?)

Chủ động đọc nội dung và phiên bản mới nhất sau xung đột hoặc lần ghi không chắc chắn.

project.dispose() / session.dispose()

Hủy công việc thuộc quyền quản lý; giải phóng dự án vẫn giữ ứng dụng khách thuộc người gọi kết nối.

Chạy ví dụ HTTP đầy đủ trong gói đã cài. Nó tạo không gian làm việc mẫu tạm riêng, kiểm tra sửa, phiên thứ hai xung đột, tải lại rõ ràng, Unicode và kết nối lại, rồi đóng máy chủ và xóa thư mục tạm đó:

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

Đầu ra dự kiến: Project session: HTTP edit, conflict, reload, Unicode and reconnect verified. Mã nguồn ví dụ thể hiện đầy đủ thiết lập máy chủ/ứng dụng khách và dọn dẹp.

Tùy chọn chấp nhận signal và timeoutMs. Lần ghi thất bại sau khi thử để lại needs-reload; giữ riêng mọi bản nháp giao diện chưa lưu và chủ động tải lại trước lần lưu khác. SDK không tự hợp nhất hay thử lại. Hết thời gian, hủy hoặc mất phản hồi có thể xảy ra sau khi máy chủ đã ghi; hủy yêu cầu vẫn giữ thay đổi đã ghi. Mỗi phiên cho phép một lần lưu hoặc tải lại đang chờ.

Chỉnh sửa văn bản dùng bản chụp gốc, dòng tính từ 0 và độ lệch UTF-16. Chồng lấn, tách cặp surrogate và phạm vi không hợp lệ bị từ chối trước khi lưu. Dự án cho phép tối đa 64 phiên mở hoặc đang mở và 500 chỉnh sửa mỗi lần lưu. Các trình trợ giúp này dùng giao thức không gian làm việc v1 không đổi, kể cả máy chủ SDK 0.2.x, và giữ hạn chế gốc, đường dẫn bảo vệ và chỉ đọc. Đọc Dự án không gian làm việc để biết vòng đời và giới hạn kích thước.

Tham chiếu API

Nhập API plugin từ @altifigence/dds-plugin-sdk. Gói bao gồm khai báo TypeScript cho cùng các export.

API

Công dụng

definePlugin(manifest, activate)

Xác minh manifest và khai báo hàm kích hoạt.

context.registerDiagnosticsProvider(selector, provider)

Đăng ký provideDiagnostics(request, {signal}) cho các ID ngôn ngữ đã chọn; trả về đăng ký có thể giải phóng.

createDiagnosticsResult(request, diagnostics)

Tạo kết quả đã xác minh bằng danh tính yêu cầu.

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

Đăng ký nhà cung cấp ngôn ngữ và tạo kết quả có danh tính yêu cầu đã xác minh.

parseManifest(value)

Xác minh phiên bản manifest, danh tính, quyền, máy chủ được hỗ trợ và mô-đun đầu vào.

parseDocumentSnapshot(value)

Xác minh URI, ngôn ngữ, phiên bản mô hình, phiên bản không gian làm việc và văn bản.

parseDiagnosticsRequest(value) / parseDiagnosticsResult(value)

Xác minh giao thức, yêu cầu, phạm vi, danh tính tài liệu và trường chẩn đoán.

PluginSdkError / ErrorCode / LIMITS / PROTOCOL_VERSION

Đọc lỗi có kiểu, giới hạn tài nguyên và phiên bản giao thức.

Nhập máy chủ phát triển từ @altifigence/dds-plugin-sdk/testing:

API máy chủ thử nghiệm

Công dụng

createTestHost({scope, grants})

Tạo máy chủ cục bộ. Cả hai tùy chọn đều không bắt buộc; cấp quyền mặc định cho phép đọc tài liệu và chẩn đoán.

await host.activate(plugin)

Kích hoạt plugin và trả về kích hoạt có thể giải phóng.

host.setDocument(snapshot)

Đặt tài liệu hiện tại. Tăng modelVersion hoặc đổi workspaceRevision khi thay đổi văn bản.

await host.requestDiagnostics({signal, timeoutMs})

Yêu cầu chẩn đoán từ nhà cung cấp phù hợp; cả hai tùy chọn đều không bắt buộc.

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

Yêu cầu tính năng ngôn ngữ đã khai báo với quyền document.read và language.provide rõ ràng.

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

Xóa đăng ký và hủy công việc đang chờ; giải phóng máy chủ khi kiểm tra kết thúc.

Yêu cầu bao gồm requestId, dự án/phiên scope và bản chụp có uri, languageId, modelVersion, workspaceRevision và text. Dùng createDiagnosticsResult để giữ danh tính này. Kết quả chứa mảng diagnostics và không chứa văn bản nguồn.

Lỗi cung cấp code, bao gồm invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable và budget_exceeded. Thời gian chờ yêu cầu mặc định là 5 giây; thời gian chờ được chấp nhận là 1–30000 ms. Tài liệu giới hạn 262144 byte UTF-8 và kết quả giới hạn 500 chẩn đoán. Đọc LIMITS để biết đầy đủ giới hạn.

SDK 1.0.0 cũng cung cấp mô-đun riêng. Import không gian làm việc và đóng gói chỉ dành cho Node thuộc môi trường người dùng:

Import

API

@altifigence/dds-plugin-sdk

createPluginHost — lệnh v2, cổng không gian làm việc/backend rõ ràng

@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, kiểu tác vụ

@altifigence/dds-plugin-sdk/artifacts

BINARY_ARTIFACT_LIMITS, parseBinaryArtifactReference, parseBinaryArtifactChunk, decodeBinaryArtifactData

/job-storage / /job-storage-node

createNodeJobStore, kiểu tác vụ bền vững

/job-history

parseJobHistoryQuery, parseJobHistoryPage, quan hệ thử lại

/artifact-storage / /artifact-storage-node

createNodeArtifactStore, kiểu kết quả đã lưu

Đóng gói và công bố plugin

Bắt đầu với plugin có thể công bố đi kèm. Lưu trình trợ giúp này trong dự án SDK để sao chép tệp của nó vào thư mục my-plugin mới.

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

Sửa plugin.json, plugin.mjs, disclosure.json và giấy phép để mô tả plugin của bạn. Thông tin công bố phải khớp nhà phát hành manifest, ID plugin, phiên bản, giấy phép và mức hiển thị mã nguồn. Chỉ liệt kê tệp bạn định phân phối trong dds-package.json:

dds-package.json

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

Xác minh và đóng gói ví dụ:

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

Với siêu dữ liệu ví dụ không đổi, pack tạo dist/example-hello-publisher-1.0.0.tgz và dist/example-hello-publisher-1.0.0.tgz.release.json. JSON phát hành chứa SHA-256 kho cuối cùng, hàm băm manifest/thông tin công bố và danh sách tệp. Kiểm tra những tệp này trước khi phân phối.

Chỉ các tệp trong danh sách cho phép, dds-package.json và siêu dữ liệu npm được sinh đi vào kho. Xác minh kiểm tra dữ liệu gói, còn đóng gói tạo kho cục bộ cho kênh phân phối bạn chọn. CLI từ chối cấu hình riêng, tệp khóa và đường dẫn liên kết; xem nội dung tệp đã chọn trước khi chia sẻ.

Kênh

Cần cung cấp

Bản phát hành GitHub công khai

Kho lưu trữ theo phiên bản, JSON phát hành bên ngoài, giấy phép và quyền truy cập mã nguồn bắt buộc nếu có.

Registry riêng hoặc kênh tải xuống

Cùng các tệp theo phiên bản, ủy quyền đối tượng nhận và điều khoản plugin thực tế.

Manifest v2 khai báo runtime, quyền yêu cầu và source: {visibility, licenseFile, repository?}. Đặt mức hiển thị thành open hoặc closed và bao gồm tệp giấy phép thực tế. Mã thuộc sở hữu của bạn có thể dùng điều khoản mã nguồn mở hoặc độc quyền; thông báo SDK và phụ thuộc áp dụng vẫn có hiệu lực. Người nhận nhận JavaScript thực thi cùng siêu dữ liệu mức hiển thị nguồn và giấy phép đã khai báo.

Làm theo Công bố và Cấp phép để biết trường công bố và yêu cầu phân phối. Phân phối kho lưu trữ có phiên bản qua bản phát hành GitHub, registry riêng hoặc kênh tải xuống bạn chọn.

CLI 1.2.1 ghi >=1.0.0 <2.0.0 trong gói plugin mới. Kho 0.3–0.13 trước đây và đúng 1.0.0-rc.1 giữ peer gốc. Xác minh và đóng gói lại phiên bản plugin mới để cài ổn định; nhà phát hành chủ động cập nhật phạm vi peer và siêu dữ liệu phát hành đã khai báo khi đóng gói lại.

Xác minh plugin đã tải

SDK 1.2.1 cung cấp dds-plugin verify cho đúng siêu dữ liệu plugin 0.3.x–0.13.x đã phát hành, RC1 và ổn định hiện tại. Giữ .tgz và .tgz.release.json cùng nhau. Xác minh giữ peer gốc. Kiểm tra gói vừa tạo:

Xác minh ví dụ đã đóng gói

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

Lệnh kiểm tra cấu trúc gzip/tar có giới hạn, danh sách tệp cho phép chính xác, từng hàm băm tệp, manifest, thông tin công bố, giấy phép và siêu dữ liệu npm được sinh. Nó từ chối liên kết, đường dẫn không an toàn hoặc trùng, tệp thừa và hook/phụ thuộc npm. Nó đọc và xác minh kho cục bộ tại chỗ dưới dạng thao tác chỉ với dữ liệu. Thành công in biên nhận JSON; bị từ chối thoát với mã 1.

Với bản tải đã đổi tên, dùng --metadata cùng JSON phát hành tương ứng. Lấy SHA-256 mong đợi độc lập qua kênh phát hành tin cậy và truyền bằng --sha256 để ghim byte đã chọn. API Node cung cấp cùng tùy chọn:

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

Chạy verify-release.mjs với đường dẫn kho, đường dẫn siêu dữ liệu và hàm băm chữ thường 64 ký tự lấy độc lập làm ba đối số. checksumPinned chỉ đúng khi hàm băm được cung cấp khớp. Giới hạn là đầu vào nén 12 MiB, nội dung tệp 10 MiB, mỗi tệp 4 MiB, 256 tệp và siêu dữ liệu ngoài 256 KiB.

Siêu dữ liệu ghép cặp cung cấp tính toàn vẹn dựa trên hàm băm: thay cả hai tệp có thể tạo hàm băm khớp mới. Xác lập danh tính nhà phát hành qua kênh phát hành đáng tin cậy, xem xét mã độc trong mã, rồi cấp quyền và đánh giá bản cài DDS bằng quyết định rõ ràng của máy chủ. Biên nhận mô tả byte được đọc trong lần gọi đó; kiểm tra lại byte thực nếu tệp có thể thay đổi trước khi dùng. Kho plugin 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 hiện có vẫn xác minh được khi đáp ứng chính sách tệp tăng cường; cài trên 1.0 vẫn cần nhà phát hành xác minh và đóng gói lại. Loại tệp mới bị cấm và công bố phiên bản plugin mới nếu cần. Trình xác minh này dành cho gói plugin DDS; tarball npm SDK dùng SHA-256 phát hành của chúng.

Xem Xác minh kho lưu trữ và ví dụ đầy đủ về đóng gói/xác minh/can thiệp.

Quyền, giấy phép và sử dụng dữ liệu

Quyền yêu cầu trong manifest tách biệt với quyền máy chủ cấp để bật thao tác. Cung cấp danh tính plugin, phiên bản, giấy phép thực tế, phạm vi không gian làm việc và quyền yêu cầu cho người dùng trước khi bật. Giải thích người vận hành backend, dữ liệu được gửi, mục đích, lưu giữ và thông báo quyền riêng tư trước khi kết nối backend đó.

Bản ghi

Ý nghĩa

pluginPermissionGrant

Quyết định quyền truy cập máy chủ cho đúng gói, không gian làm việc và quyền.

noticeAcknowledgement

Người dùng xác nhận đã đọc thông báo thông tin.

pluginLicenseAcceptance

Người dùng chọn có chấp nhận điều khoản thực tế của nhà phát hành plugin hay không.

optionalPersonalDataConsent

Lựa chọn riêng khi xử lý tùy chọn dùng sự đồng ý làm cơ sở.

Phê duyệt không gian làm việc SDK là quyết định truy cập kỹ thuật. Ghi nhận việc chấp nhận điều khoản plugin và đồng ý dữ liệu cá nhân tùy chọn thành các lựa chọn riêng. Sử dụng SDK theo điều khoản giấy phép Apache-2.0.

Nhà phát triển máy chủ có thể giữ thông báo theo phiên bản bằng các trình trợ giúp bất đồng bộ di động. Ví dụ, lưu thành notice.mjs và chạy 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 ràng buộc tập con quyền yêu cầu với manifest v2, hàm băm hiện vật và manifest, thế hệ không gian làm việc, danh tính máy chủ, thông báo và hạn hết hiệu lực. isPermissionGranted đánh giá danh tính hiện tại và sự kiện thu hồi do máy chủ cung cấp. revokeConsentReceipt tạo sự kiện riêng; máy chủ sau đó phải dừng các lệnh gọi được cho phép trong tương lai.

Các trình trợ giúp này xác minh bản ghi cục bộ. Máy chủ cung cấp lựa chọn người dùng thực tế, danh tính, lưu trữ và thực thi quyền. Đọc Quyền và sự đồng ý để biết trường chính xác và ví dụ quyền tương tác để xem minh họa cho phép/từ chối/thu hồi rõ ràng. Nhà phát hành và máy chủ quản lý thỏa thuận qua quy trình phân phối riêng của mình.

Mã nguồn, bản phát hành và đóng góp

Kho SDK chính thức chứa mã nguồn, schema, ví dụ và kiểm tra hợp đồng. Để chạy ví dụ đã phát hành và kiểm tra SDK từ nguồn:

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

Báo lỗi SDK qua GitHub Issues, kèm phiên bản SDK và cách tái hiện tối thiểu. SDK được cấp phép Apache-2.0; xem giấy phép và thông báo trong kho. Dùng trang phát hành để lấy kho theo phiên bản và ghi chú phát hành.

Kho này công bố SDK dành cho nhà phát triển. Tệp SDK, schema, ví dụ và thông báo đã khai báo xác định phạm vi công khai của nó. Kiểm tra gói thực thi danh sách tệp công bố chính xác và từ chối mẫu bí mật, đường dẫn riêng đã biết. Xem nội dung phát hành đã chọn cùng với kiểm tra mẫu để xác định dữ liệu tiết lộ trong các tệp được phân phối.

Cập nhật bảo mật và giới hạn máy chủ

Cập nhật cả máy chủ không gian làm việc và ứng dụng khách SDK lên 0.3.2 hoặc mới hơn. Cài bản cập nhật máy chủ để kích hoạt kiểm tra tệp và giới hạn yêu cầu đã nâng cấp. Khởi động lại máy chủ đã nâng cấp, xem thế hệ mới và xin phê duyệt lại trước khi dùng không gian làm việc.

Máy chủ không gian làm việc Node từ chối hardlink có thể trỏ tới tệp được bảo vệ hoặc tệp ngoài gốc đã chọn. Sao chép tệp dự án chia sẻ có chủ đích thành tệp thường một liên kết. Các kho thông tin xác thực như .netrc, _netrc, .git-credentials, .gnupg, .kube và .docker, tên khóa SSH bổ sung và bí danh thiết bị Windows cũng bị chặn. Đóng gói và xác minh bản tải áp dụng chính sách tên thông tin xác thực tương ứng.

Tài nguyên máy chủ

Giới hạn

Nội dung yêu cầu đến đồng thời

16; tải lên thêm nhận HTTP 429 trước khi phân phối

Yêu cầu đang thực thi

64; việc hủy dùng luồng phân phối riêng

Kết nối / yêu cầu mỗi socket

128 / 128

Yêu cầu và phản hồi / nội dung tệp

1600000 / 262144 byte UTF-8

Ứng dụng khách hủy phản hồi bị từ chối chưa đọc và luồng bị treo khi tới hạn hoặc hủy. Hết thời gian sau khi bắt đầu ghi có thể khiến kết quả không chắc chắn: đọc lại tệp trước khi thử lại. Xem xét cả nội dung tệp và đường dẫn loại trừ để tìm bí mật. Mã plugin đáng tin cậy chạy với quyền hệ điều hành của tiến trình máy chủ. Dùng hướng dẫn nâng cấp bảo mật và giới hạn không gian làm việc khi triển khai máy chủ.

Công cụ phát triển

Sau khi cài đặt SDK 1.2.1 ở trên, hãy tạo một dự án plugin lệnh riêng biệt. Chọn đích mới cho tệp được sinh; chủ động cài phần phụ thuộc và thực thi plugin sau khi tạo khung. Khung dự án bao gồm một lệnh, kiểm thử, manifest, thông cáo, phần phụ thuộc SDK đã ghim và 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 đọc siêu dữ liệu và kiểm tra Node, phân giải SDK, manifest, giấy phép, thông tin công bố và tệp gói trong danh sách cho phép mà không nhập plugin. Lỗi tạo mã thoát 1; giá trị nhà phát hành/hỗ trợ mẫu là cảnh báo. Thay các giá trị đó và xem giấy phép trước khi phân phối.

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 yêu cầu --trust-local-code. Nó chạy import/kích hoạt cục bộ đáng tin cậy trong tiến trình con và chỉ theo dõi tệp trong danh sách cho phép cùng dds-package.json. Mỗi lần chạy có hạn và giới hạn stdout/stderr 256 KiB. Ctrl+C dừng theo dõi và dọn cây tiến trình. Tiến trình con chạy với quyền hệ điều hành của bạn và kế thừa môi trường của bạn. Máy chủ thử nghiệm mặc định cấp quyền đọc tài liệu và chẩn đoán; cấu hình rõ ràng máy chủ không gian làm việc và quyền không gian làm việc/backend cho các tích hợp đó.

Dùng --job để in tiến độ/nhật ký tác vụ; dùng --timeout-ms để đặt tối đa 30 giây cho lệnh thường hoặc 30 phút cho tác vụ. API Node là initPlugin, doctorPlugin và runPluginDev trong /devtools. Xem hướng dẫn công cụ phát triển để biết hành vi theo dõi và giới hạn dọn dẹp.

Tác vụ lệnh chạy dài

Bật jobs: true trên máy chủ/server SDK 0.4.0 để chạy lệnh vượt hạn yêu cầu thông thường. Tác vụ mặc định tắt. Thử ví dụ HTTP cục bộ đầy đủ, báo tiến độ, nhật ký backend có tên và tệp kết quả đã ghim hàm băm:

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

Đầu ra dự kiến: Command job: progress, backend log and pinned result file verified. Trình xử lý lệnh nhận job tùy chọn trong {signal, job}. Nó cung cấp reportProgress, log, addArtifact và invokeBackend. Quyền workspace.read/write và backend.invoke hiện có vẫn áp dụng; không chấp nhận đường dẫn thực thi tùy ý.

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

Đoạn thăm dò giả định ứng dụng khách đã kết nối và lệnh analyze được cấu hình để đăng ký report. Giữ ID tác vụ trước khi bắt đầu. Ngắt kết nối hoặc hủy yêu cầu thăm dò không hủy thực thi; kết nối lại cùng thế hệ và chủ động truy vấn/hủy. Bắt đầu lại với cùng ID và đầu vào dùng lại tác vụ đã giữ; đối số khác gây xung đột. Khởi động lại máy chủ làm mất bản ghi trong bộ nhớ. Bật kho bền vững 0.8 riêng bên dưới để khôi phục siêu dữ liệu đã ghi sau khi khởi động lại.

Trạng thái là running, succeeded, failed, cancelled và timed_out. Đầu ra muộn bị bỏ sau khi hủy; tác dụng phụ không được hoàn tác. Nhà cung cấp chưa hoàn tất vẫn giữ slot. Tối đa 4 tác vụ đồng thời, 32 bản ghi giữ lại, 32 thao tác lồng mỗi tác vụ, 256 sự kiện/64 KiB mỗi tác vụ, 64 sự kiện mỗi trang và 16 hiện vật. Runtime mặc định 5 phút, tối đa 30 phút. Bản ghi kết thúc đã hoàn tất hết hạn 15 phút sau sự kiện cuối.

Tệp kết quả văn bản là UTF-8 tương đối với không gian làm việc, tối đa 256 KiB. Máy chủ đọc bằng quyền hiện có, ghi SHA-256 và từ chối lần đọc sau nếu byte đổi. Với đầu ra nhị phân hoặc mô phỏng lớn hơn, dùng API kết quả nhị phân tùy chọn. Hiện vật chưa hoàn chỉnh có thể còn lại sau khi hủy; kiểm tra trạng thái kết thúc của tác vụ để xác định thành công. Ứng dụng khách 0.3 cũ tiếp tục dùng phương thức v1 hiện có; tác vụ SDK độc lập cần 0.4 ở cả hai phía và máy chủ/ứng dụng khách được cấu hình rõ ràng. Xem Tác vụ để biết hợp đồng và giới hạn chính xác.

Quan sát tệp không gian làm việc

project.watchFiles() lấy mẫu 1–16 đường dẫn tệp tương đối rõ ràng. SDK 1.0.0 dùng yêu cầu chỉ phiên bản trên máy chủ hỗ trợ và đọc có giới hạn hiện có trên máy chủ cũ. Ví dụ giả định ứng dụng khách đã kết nối và được máy chủ phê duyệt. Đổi design.sv bằng trình soạn thảo ngoài để kết thúc vòng lặp; bản chụp chỉnh sửa được giữ không đổi.

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

Sự kiện là {kind, path, previousRevision, revision} bất biến. Mẫu đầu phát initial; thay đổi sau phát created, changed hoặc deleted. Tệp thiếu có revision null. includeInitial: false ghi mốc ban đầu âm thầm, và phiên bản bằng nhau không tạo sự kiện. Chỉ not_found nghĩa là xóa; lỗi quyền, đường dẫn bảo vệ, kích thước và truyền tải kết thúc quan sát.

Giữ văn bản giao diện chưa lưu riêng. Tải lại, hợp nhất và lưu bản nháp là hành động rõ ràng của bên gọi, và lưu chỉnh sửa vẫn có thể xung đột với phiên bản đã giữ. Đường dẫn được đọc lần lượt theo thứ tự; đây là quan sát lấy mẫu nên thay đổi trung gian có thể gộp lại. API này lấy mẫu các đường dẫn tệp được chọn rõ ràng; ứng dụng gọi quản lý khám phá thư mục và xử lý đổi tên. Hạn chế gốc, kích thước tệp và đường dẫn bảo vệ hiện có áp dụng trên máy chủ chỉ đọc và có thể ghi.

Cả quan sát tệp và tác vụ bắt đầu ở next() đầu tiên, không lấy trang nền khi bên tiêu thụ tạm dừng và dùng chung tối đa tám observer hoạt động mỗi ứng dụng khách. Một next() có thể chờ; đọc đồng thời thất bại với conflict. Break hoặc return() dừng đọc chờ; giải phóng dự án dừng observer tệp của nó, và ngắt/kết nối lại/giải phóng vô hiệu mọi observer cũ. AbortSignal kết thúc quan sát với cancelled; phản hồi muộn không thể cho kết quả.

intervalMs là 250–60000 ms (mặc định 1000), áp dụng giữa các lượt tệp hoặc lần đọc tác vụ nhàn rỗi. requestTimeoutMs là 1–30000 ms mỗi yêu cầu, mặc định theo hạn ứng dụng khách. Tổng timeoutMs là 1–1800000 ms từ next() đầu tiên, gồm thời gian bên tiêu thụ tạm dừng. Tệp mặc định không có tổng hạn; tác vụ mặc định 30 phút. Tới hạn báo budget_exceeded và giải phóng slot. Các giới hạn được export dưới WORKSPACE_OBSERVATION_LIMITS.

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

Đầu ra dự kiến: Workspace observation: file changes, retained draft and resumed job verified. Ví dụ đầy đủ tạo không gian làm việc tạm riêng và kiểm tra thay đổi tệp, xung đột bản nháp và tiếp tục tác vụ rõ ràng. Xem Quan sát để biết mọi tùy chọn và quy tắc vòng đời.

Quan sát và tiếp tục tác vụ

client.watchJob() theo dõi tác vụ hiện có bằng jobs.events/get; waitForJob() trả bản chụp kết thúc. Đoạn mã giả định ứng dụng khách đã kết nối, jobId được bắt đầu rõ ràng và savedCursor (hoặc undefined). Kiểm tra getJobCapabilities() trước khi bắt đầu tác vụ. Quan sát không bao giờ bắt đầu, thử lại hay hủy lệnh.

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

Mỗi cập nhật bất biến chứa snapshot, events, after, nextCursor, dropped và hasMore. Xử lý tối đa 64 sự kiện mỗi trang và ghi nextCursor sau khi xử lý cùng ID tác vụ và danh tính không gian làm việc. dropped báo lịch sử hết hạn. Bản chụp có thể mới hơn trang sự kiện của nó; tiếp tục đọc bản chụp kết thúc khi hasMore đúng. Iterator kết thúc sau trang cuối. waitForJob() đọc hết cùng các trang và trả succeeded, failed, cancelled hoặc timed_out; kiểm tra trạng thái thay vì coi mọi promise được giải quyết là thành công.

Dừng iterator hoặc hết thời gian chỉ dừng quan sát. Lệnh máy chủ tiếp tục tới khi xong hoặc cancelJob() được gọi rõ ràng. Sau khi kết nối lại được máy chủ phê duyệt, xác minh cùng ID và thế hệ không gian làm việc rồi tạo observer mới với ID tác vụ và cursor đã lưu. Observer cũ không hợp lệ dù danh tính không đổi. Tác vụ thiếu/hết hạn và lỗi truyền tải được báo mà không gửi lại; tác vụ trong bộ nhớ không tồn tại sau khởi động lại máy chủ. Phục hồi bền vững dùng recoverJob() với kết nối mới; observer trực tiếp không tiếp tục qua các thế hệ.

Hợp đồng hello v1 và tác vụ hiện có không đổi. Quan sát tệp dùng dự phòng trên máy chủ 0.3.2/0.4/0.5; quan sát tác vụ cần máy chủ 0.4 hoặc mới hơn đã bật. Máy chủ báo lỗi với tác vụ không được hỗ trợ, rồi bên gọi chủ động chọn lệnh tiếp theo. Các API quan sát này chạy qua máy chủ/ứng dụng khách SDK độc lập. Xem Quan sát và Tính tương thích.

Phiên bản tệp và đọc có điều kiện

SDK 0.6.0 thêm getFileCapabilities(), getFileRevision(path) và readFileIfChanged(path, knownRevision) cho ứng dụng khách đã kết nối. Đọc phiên bản trả {path, revision} không có nội dung. Đọc có điều kiện khớp trả {path, revision, notModified: true}; nội dung đổi trả notModified: false và content. Truyền knownRevision: null để lấy nội dung hiện tại. Tệp thiếu từ chối với 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);

Dùng ứng dụng khách đã kết nối và được cho phép. Giữ bản nháp chưa lưu riêng khỏi cache này. Đọc có điều kiện băm và trả một bản chụp tệp; lần đọc sau vẫn có thể thấy thay đổi khác. Lưu với phiên bản thuộc nội dung trả về. Các lệnh gọi này không cập nhật bản chụp phiên chỉnh sửa hay hợp nhất bản nháp. Phản hồi không đổi không có trường content; tệp rỗng đã đổi có content: “”.

Quan sát tệp tự dùng đọc chỉ phiên bản khi hỗ trợ. Phương thức fs.capabilities, fs.revision và fs.readIfChanged tùy chọn giữ hello v1 nghiêm ngặt và phương thức tệp gốc. Máy chủ không gian làm việc SDK trước 0.6 đã biết dùng fs.read mà không thăm dò. Máy chủ khác phải trả lời khám phá hoặc trả lỗi unsupported tương quan đúng. Mỗi khả năng false chọn phương án đọc đầy đủ có giới hạn riêng; phản hồi máy chủ cũ vẫn truyền toàn bộ nội dung.

Khả năng chỉ được cache cho kết nối hiện tại và đặt lại khi kết nối lại hoặc thu hồi. Phản hồi không hợp lệ, đường dẫn/phiên bản không khớp, lỗi quyền, xác thực, truyền tải và hết thời gian không kích hoạt dự phòng. Thao tác đã quảng bá sau đó thất bại không bị âm thầm hạ cấp. AbortSignal bao trùm khám phá và đọc; timeoutMs áp dụng cho từng yêu cầu HTTP. Đổi kết nối vô hiệu thao tác cũ.

Máy chủ vẫn đọc toàn tệp có bảo vệ và tính SHA-256 cho mỗi mẫu. Xác minh UTF-8, giới hạn 262144 byte và kiểm tra đường dẫn/liên kết bảo vệ vẫn có hiệu lực. Điều này giảm byte phản hồi mạng trong khi giữ thao tác đọc đĩa có bảo vệ và tính SHA-256 cho mỗi mẫu. Đo cục bộ Node 22.23.1 Windows với 20 mẫu 200000 byte không đổi trả 4003974 byte khi đọc đầy đủ, 3867 khi đọc phiên bản (ít hơn 99,903%) và 4247 khi đọc có điều kiện (ít hơn 99,894%). Bao gồm khám phá; loại header HTTP, TLS và mốc hello/nội dung ban đầu. Chạy npm run benchmark:files trong checkout để tái hiện dữ liệu mẫu.

SDK hiện có API 1.x ổn định, với kiểm tra chức năng bao trùm hành vi phiên bản tệp được mô tả. Ứng dụng khách 0.3.2, 0.4, 0.5 và 0.6 hiện có giữ API gốc trên máy chủ 0.7. Dùng máy chủ/ứng dụng khách SDK độc lập để kiểm tra các API này. Xem Phiên bản tệp để biết hợp đồng đầy đủ và quy tắc chuyển đổi.

Kết quả tác vụ lớn và nhị phân

SDK 0.7.0 thêm phần mở rộng tệp kết quả nhị phân tùy chọn. Lệnh đáng tin cậy đăng ký tệp không gian làm việc hiện có; máy chủ ghi SHA-256 và độ dài. Ứng dụng khách đọc tối đa 64 KiB mỗi khối, và trình tải Node tiếp tục tệp chưa hoàn chỉnh rồi xác minh đầu ra đầy đủ. Tệp ghi nhận tối đa 1 GiB; API tệp UTF-8 và hiện vật văn bản 256 KiB hiện có giữ giới hạn.

Bật jobs: true và binaryArtifacts: true trên máy chủ plugin thuộc server. Cả hai mặc định false. Giữ token rõ ràng, thông báo người vận hành, dấu ghim hiện vật plugin đã xem xét và quyền workspace.read có hiệu lực. Phần sau dựa trên thiết lập không gian làm việc bên trên; không gian chỉ đọc có thể đăng ký tệp đã được công cụ cấu hình của người vận hành tạo.

Javascript

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

Đăng ký kết quả trong lệnh bắt đầu bằng startCommandJob. Đăng ký truyền tệp hiện có qua SHA-256 bằng bộ đệm 64 KiB. Tham chiếu trỏ tới tệp nguồn đó, không phải bản sao bất biến. Đường dẫn bảo vệ, traversal, liên kết và tệp không thường bị từ chối; thay đổi nguồn sau đó thất bại với 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};
});

Dùng ứng dụng khách đã kết nối, được cho phép và ID tác vụ hiện có. Đích là đường dẫn tuyệt đối trong thư mục thực hiện có do người gọi kiểm soát. Trình trợ giúp ghi destination + “.dds-part” và từ chối ghi đè tệp cuối hiện có.

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

Giữ toàn bộ tham chiếu {jobId, scope, artifact}. Sau gián đoạn, chủ động kết nối lại cùng thế hệ máy chủ và gọi lại trình trợ giúp với tham chiếu đó cùng resume: true. Nó băm lại tiền tố đã lưu và chỉ yêu cầu hậu tố thiếu. Nó kiểm tra SHA-256 từng khối, toàn bộ luồng nhận và tệp tạm thực trước khi xuất bản. Biên nhận verified: true cuối xác nhận hoàn tất; callback tiến độ đồng bộ vẫn chưa được xác minh. Tệp chưa hoàn chỉnh bị hỏng cần xóa rõ ràng hoặc đích mới.

listJobBinaryArtifacts(jobId) trả siêu dữ liệu nhị phân ghi nhận riêng khỏi kết quả văn bản hiện có. readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) trả base64 chuẩn cùng SHA-256 khối, phạm vi chính xác và dấu EOF. decodeBinaryArtifactData từ /artifacts trả byte Uint8Array. Bên tiêu thụ trình duyệt phải tự xác minh hàm băm toàn tệp; kiểm tra từng khối không chứng minh đầu ra ghép khớp tham chiếu.

Kết quả nhị phân và văn bản chia sẻ 16 slot cùng namespace ID mỗi tác vụ. Thao tác chụp/đọc nhị phân giới hạn bốn mỗi máy chủ/không gian làm việc, tải Node bốn mỗi tiến trình. timeoutMs tải Node là tổng hạn, mặc định tối đa 30 phút; requestTimeoutMs mặc định 5 giây, tối đa 30 giây. Xuất bản cần hỗ trợ hardlink như NTFS hoặc ext4. Dùng đích đáng tin cậy do người vận hành kiểm soát và quản lý tiến trình ghi đồng thời; kiểm tra hệ thống tệp chạy với thẩm quyền hệ điều hành của tiến trình máy chủ.

artifacts.capabilities, artifacts.list và artifacts.read tùy chọn giữ hello v1, bản chụp tác vụ và sự kiện hiện có. Máy chủ trước 0.7 báo phần mở rộng tắt; bên gọi chủ động chọn lần đọc văn bản hoặc lệnh tiếp theo. Xác thực, phản hồi sai định dạng và lỗi truyền tải vẫn là lỗi. Kết nối lại, thu hồi, tác vụ hết hạn hay đổi thế hệ máy chủ vô hiệu thao tác cũ. Lưu giữ tác vụ vẫn trong bộ nhớ 15 phút sau sự kiện cuối của tác vụ kết thúc. Tác vụ bị hủy có thể để lại đầu ra công cụ chưa hoàn chỉnh đã ghi; kiểm tra trạng thái kết thúc tác vụ để xác định thành công. Phần này mô tả API trực tiếp/nguồn mặc định. API kết quả lưu riêng bên dưới giữ byte qua khởi động lại.

Chạy npm run example:artifacts cho truyền thực 2 MiB có gián đoạn, kết nối lại và tiếp tục chỉ hậu tố; npm run benchmark:artifacts dùng 8 MiB. Lần chạy Windows cục bộ truyền 8388625 byte trong 129 yêu cầu khối, tiếp tục tiền tố 65536 byte và xác minh SHA-256 cuối. Base64 thêm chi phí; nội dung phản hồi JSON tổng cộng 11257419 byte. Tính năng truyền bộ nhớ có giới hạn này giữ nguyên byte tệp và dùng base64 để truyền tải. Xem Hiện vật nhị phân để biết hợp đồng đầy đủ. Dùng máy chủ/ứng dụng khách SDK độc lập cho quy trình truyền này.

Tác vụ bền vững, lịch sử và thử lại rõ ràng

SDK 0.8.0 thêm kho bền vững tùy chọn trong thư mục thuộc người vận hành ngoài không gian làm việc. Cung cấp đường dẫn tuyệt đối, ID không gian làm việc ổn định, mã plugin đã xem xét, SHA-256 gói, token và thông báo. Ví dụ còn bật giữ byte tệp; bỏ artifacts khỏi jobStorage để chỉ lưu siêu dữ liệu tác vụ. Phản hồi v1 hiện có và mặc định chỉ bộ nhớ vẫn tương thích.

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

Nhà cung cấp chỉ bắt đầu sau khi ý định ban đầu được lưu. Điểm kiểm tra sau được gộp; flushJobStore() đợi điểm kiểm tra yêu cầu, không đợi hoàn tất lệnh. Khôi phục tách kết nối hiện tại khỏi phạm vi thực thi gốc và báo live, completed, interrupted, expired, missing, corrupt hoặc unsupported. Tác vụ bị gián đoạn không bao giờ tự khởi động lại; unrecordedTail của nó chưa biết.

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

Lịch sử lọc trạng thái, kết quả phục hồi, lệnh, thời gian bắt đầu và lần thử cha. Trang chứa tối đa 32 mục, xếp thời gian bắt đầu giảm dần rồi ID tác vụ. Cursor cố định tập thành viên trong 60 giây và phải dùng lại cùng truy vấn; tác vụ mới bị loại, bản ghi xóa hoặc không được phép bị bỏ qua và hết hạn được báo. Khởi động lại làm mất cursor. artifactCount, snapshotCount và resultAvailability mô tả tham chiếu đã ghi, không phải bằng chứng tệp hiện tại.

Thử lại rõ ràng cần ID tác vụ mới, đầu vào mới đã xác minh, cùng gói hiện được phê duyệt và lệnh khả dụng. attemptOf liên kết lần chạy mới với cha không đổi. Lặp cùng ID, đầu vào, cha và thời gian chờ lấy lần thử đã giữ mà không chạy lại, kể cả sau khởi động lại. Bản ghi thiếu/hết hạn không thể bảo đảm điều đó. Thực thi đã chấp nhận có thể tiếp tục sau khi yêu cầu chờ bị hủy; truy vấn ID tác vụ mới trước khi quyết định thử lại.

Lưu giữ mặc định bỏ đầu vào thô, nội dung kết quả, văn bản tiến độ và nhãn hiện vật; nhật ký được che nhạy cảm. Chỉ bộ che dữ liệu xác định của máy chủ được chỉ định rõ mới giữ văn bản đã xem xét. Token, bí mật và sự đồng ý cũ không bao giờ được khôi phục. Danh tính không gian làm việc/plugin hiện tại, quyền đọc và mọi quyền đã ghi được kiểm tra lại. Siêu dữ liệu tác vụ mặc định 256 bản ghi, 64 MiB và 24 giờ, tối đa bảy ngày. Gỡ và dọn là thao tác máy chủ rõ ràng.

Kho cục bộ có một tiến trình ghi, xác minh danh tính không gian làm việc/gốc và kiểm tra tính toàn vẹn siêu dữ liệu. Phục hồi khóa cũ rõ ràng chỉ thu hồi PID cùng máy đã chứng minh chết. Tệp không biết/bị hỏng cần kiểm tra. Trên Windows, đồng bộ tệp và đổi tên hỗ trợ phục hồi sau khởi động lại tiến trình; đánh giá riêng hành vi mất điện trên hệ thống tệp đích. Xem Lưu trữ tác vụ, Lịch sử và ví dụ tác vụ bền vững.

Kết quả đã lưu và tải sau khởi động lại

Khi bật kho hiện vật, await job.addArtifact() hoặc job.addBinaryArtifact() sao chép và xác minh toàn tệp trước khi đăng ký. Văn bản vẫn giới hạn 256 KiB; tệp nhị phân tối đa 1 GiB. Luồng nguồn và tệp tạm thực được kiểm tra SHA-256. Hủy, lỗi đầy đĩa, thay đổi và ghi dở không xuất bản kết quả dùng được. Tệp xuất bản trước khi crash nhưng chưa được tác vụ ghi nhận có thể còn để người vận hành kiểm tra.

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

Danh sách tách tham chiếu nguồn khỏi siêu dữ liệu bản chụp và báo bản chụp retained, expired, missing, corrupt hoặc unsupported. retained là trạng thái siêu dữ liệu; getStoredJobArtifact() xác minh siêu dữ liệu và toàn bộ tệp lưu trước khi trả tham chiếu mới thuộc thế hệ hiện tại. Mỗi lần đọc kiểm tra lại thẩm quyền hiện tại và danh tính tệp. Xóa nguồn không ảnh hưởng byte đã lưu, và bản chụp thiếu không bao giờ dự phòng sang nguồn có thể thay đổi. Với bản chụp văn bản, gọi client.readStoredJobArtifactText(textReference).

Sau khởi động lại, kết nối lại với quyền hiện tại và lấy tham chiếu mới. ID bản chụp, ID kho và giá trị băm giữ ổn định; thế hệ cũ bị từ chối. resume: true kiểm tra lại tiền tố .dds-part đã lưu với bản chụp đó, xác minh khối và toàn tệp tạm, rồi xuất bản không ghi đè đích. Đọc cần cả siêu dữ liệu tác vụ được giữ và byte tệp. Bên tiêu thụ khối trong trình duyệt phải xác minh toàn bộ giá trị băm; bộ điều hợp Worker bên dưới cung cấp tiếp tục trên đĩa trình duyệt một cách rõ ràng.

Lưu trữ hiện vật mặc định 256 tệp, 256 MiB và 24 giờ, tổng tối đa 4 GiB và lưu giữ bảy ngày. Khối tối đa 64 KiB, bốn lần đọc đồng thời. inspect() báo mức sử dụng, hạn, mục không hợp lệ và tệp mồ côi. remove(snapshot) và prune() là thao tác người vận hành rõ ràng. Tác vụ hoạt động và từng lần đọc được ghim; hết hạn hay gỡ giữa các khối có thể dừng lần đọc tiếp. Dọn tệp mồ côi tùy chọn chỉ xóa tệp một liên kết được nhận diện. Mục hỏng hoặc mơ hồ cần kiểm tra.

Lưu giữ tệp lưu byte dự án thực độc lập với che nhật ký. Hãy chủ động lựa chọn. Plugin/lệnh hiện tại, hàm băm gói, không gian làm việc và quyền đã ghi vẫn bắt buộc sau khởi động lại. Hoàn tất bảo trì, rồi await server.close(), artifacts.close() và store.close() theo thứ tự đó. Dùng các API lưu giữ và đóng này trong máy chủ SDK độc lập được cấu hình rõ ràng.

Chạy npm run example:stored-artifacts cho khởi động lại tiến trình con thực, xóa nguồn, tiếp tục tải dở đã xác minh, lịch sử và thử lại rõ ràng. npm run example:durable-jobs cũng bao trùm buộc kết thúc tiến trình. Xem Kết quả đã lưu. Máy chủ 0.7 và cũ hơn đã biết báo lưu trữ tắt mà không thăm dò không biết. API trực tiếp/nguồn hiện có giữ hành vi gốc.

Quan sát dự án

Người vận hành chủ động bật projects và chọn gốc được phép trên máy chủ. Mặc định tắt. Máy chủ SDK 0.3–0.8 đã biết báo chưa khả dụng mà không thăm dò khám phá mới. Hồ sơ hệ thống tệp được hỗ trợ là lưu trữ cục bộ Windows/Linux. Ví dụ SDK độc lập này dùng máy chủ/ứng dụng khách được cấu hình rõ ràng.

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

Sự kiện đầu là bản chụp đầy đủ. Thay đổi sau mang delta theo phiên bản trước; gợi ý mất, thay đổi khi quét đầu, quét không đầy đủ và tràn do bên tiêu thụ chậm tạo chế độ đồng bộ lại đầy đủ có lý do. Đổi tên có thể xuất hiện là xóa/tạo. Mỗi tệp được xác minh riêng. Phiên bản bản chụp mô tả trạng thái tệp được lấy mẫu, và các lần ghi trung gian có thể gộp giữa hai mẫu.

Máy chủ và ứng dụng khách mỗi bên cho phép bốn đăng ký, bốn sự kiện xếp hàng mỗi đăng ký gốc. Lease nhàn rỗi mặc định 30 giây; lần đọc sau có thể trả not_found. Sau tạm dừng dài, tạo iterator mới cho bản chụp đầu. break/return, hủy và giải phóng trả đăng ký; nếu kết nối hỏng ngăn dọn dẹp, tài nguyên từ xa còn lại hết hạn theo lease.

Giới hạn quét mặc định là độ sâu 8, 512 mục, mỗi tệp 1 MiB, tổng 16 MiB và 10 giây. Tối đa cấu hình là độ sâu 32, 1000 mục, mỗi tệp 16 MiB, tổng 64 MiB và 30 giây. Tệp bị giới hạn có thể mang siêu dữ liệu không có hàm băm nội dung; kiểm tra complete và reasons. Hạn được kiểm tra giữa các lệnh gọi hệ thống tệp; dùng quyền hệ điều hành của tiến trình máy chủ được lựa chọn chủ động cho các lệnh gọi đó.

Cây dự án và tìm kiếm

listTree trả cây, searchFiles tìm tên tệp tương đối bằng chuỗi con nguyên dạng hoặc glob giới hạn, và searchText tìm văn bản nguyên dạng trong tệp UTF-8. root bắt buộc; include/exclude tương đối với nó. Dùng các chế độ tìm nguyên dạng và glob giới hạn được hỗ trợ. So khớp không phân biệt hoa thường chỉ chuyển ASCII A–Z để vị trí UTF-16 gốc giữ ổn định.

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

Kết quả văn bản gồm SHA-256 nội dung, phạm vi UTF-16 tính từ 0 và đoạn trích giới hạn. Cursor cố định tập thành viên gốc tối đa 60 giây và cần cùng truy vấn. Trang sau kiểm tra lại nội dung hiện tại và đánh dấu mục current, changed, missing hoặc unverified; tệp mới chỉ xuất hiện trong truy vấn mới. Kết quả khớp đã chụp và phiên bản giữ nguyên.

Tệp văn bản giới hạn 256 KiB, truy vấn 256 đơn vị UTF-16 và đoạn trích 512 đơn vị. Mặc định 256 kết quả (tối đa 512), 32 mục mỗi trang (tối đa 64) và phản hồi 64 KiB (tối đa 128 KiB). Tệp nhị phân, UTF-8 không hợp lệ và giới hạn byte/độ sâu/thời gian/phản hồi được báo là kết quả chưa đầy đủ kèm lý do. Có hai truy vấn đồng thời và tám chế độ cursor giữ lại; chủ động giải phóng cursor không dùng.

Bản nháp dự án và kết nối lại

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

Khi snapshotRevision truy vấn khác snapshot.revision đã quan sát, giải phóng cursor cũ và lặp lại cùng truy vấn gốc/bộ lọc. Quan sát không bao giờ thay đổi edit.snapshot hay nội dung bản nháp thuộc người gọi. Sau thay đổi ngoài, di chuyển hoặc xóa, điều kiện CAS gốc báo xung đột; người gọi chủ động chọn tải lại, hợp nhất hay lưu riêng.

Ứng dụng khách kiểm tra thế hệ kết nối, gốc/bộ lọc, hàm băm truy vấn, vị trí trang, SHA-256 bản chụp và tính liên tục sự kiện. Phản hồi muộn bị bỏ sau thu hồi, ngắt hay kết nối lại. Cursor quan sát và cursor truy vấn riêng biệt, không tự khôi phục. server.revokeProjects() kết thúc quyền dự án; bật lại cần thế hệ máy chủ mới.

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

Ví dụ Node đã cài xác minh tạo, tìm kiếm, thay đổi ngoài, bản nháp giữ lại, xung đột CAS và kết nối lại. Với ví dụ trình duyệt, mở URL loopback được in và chọn Run scenario. Nó chỉ dùng không gian làm việc tạm, được xóa khi máy chủ ví dụ dừng. Yêu cầu HTTP mặc định năm giây; chủ động cấu hình thời gian chờ ứng dụng khách và máy chủ cho quét lớn hơn.

Quan sát dự án · Hợp đồng cây/tìm kiếm · Công cụ dự án HTTP

Truyền và xác minh hiện vật trong trình duyệt

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

Trình trợ giúp an toàn cho trình duyệt nhận tối đa một khối 64 KiB mỗi lần, đợi sink đã chọn và băm tăng dần toàn tệp. Nó xác minh phạm vi chính xác, danh tính, base64 và từng hàm băm khối trước khi ghi. Sink đọc lại sau đó độc lập đọc byte đã lưu; verification chỉ là stored sau khi cả hai hàm băm đầy đủ khớp. Không có đọc lại, verification là received và storedSha256 là null. Tiến độ đạt tất cả byte không phải hoàn tất.

Ứng dụng chọn handle tệp hoặc thư mục OPFS và cấp quyền cần thiết. Cung cấp đích đã chọn và quyền truy cập cho bộ điều hợp SDK; ứng dụng quản lý tương tác bộ chọn và lựa chọn đích. Sink ghi tệp/OPFS bất đồng bộ giữ vùng tạm tới close và bỏ nó khi thất bại trước commit. Để giữ phần tải dở an toàn qua tải lại, dùng bộ điều hợp Worker chuyên dụng bên dưới. Giới hạn tệp 1 GiB, bốn luồng trực tiếp đồng thời và tổng hạn 30 phút.

Tải lên tệp được chọn

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.

Tải lên mặc định tắt. Người vận hành cấu hình không gian làm việc Node cục bộ, thư mục tạm cách ly, gốc cho phép và một chủ thể, rồi cấp workspace.write cho plugin được chọn tại đúng dấu ghim kho của nó. Trình trợ giúp băm trước nguồn đã chọn trước khi bắt đầu. Máy chủ nhận khối 64 KiB tuần tự, xác minh bản trùng và toàn nội dung, chỉ commit sau khi kiểm tra đích có điều kiện. Byte tạm không xuất hiện trong danh sách không gian làm việc thông thường.

expectedRevision: null yêu cầu đích chưa tồn tại; SHA-256 yêu cầu đích hiện tại khớp. Hủy giữ tiền tố máy chủ đã xác nhận. Thao tác recover mới rõ ràng truy vấn thẩm quyền hiện tại, xác minh cùng nguồn/đặc tả và chỉ tiếp tục tiền tố khớp. Phản hồi commit mất là không chắc chắn tới khi truy vấn; không phải quyền lặp commit hay hoàn tác tệp. Tối đa 1 GiB mỗi tệp, 4 GiB mỗi kho và bốn phiên hoạt động; mặc định thấp hơn. Máy chủ 0.3–0.9 đã biết báo tải lên tắt mà không thăm dò phương thức mới.

Lập lịch truyền tệp

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

Hàng đợi thuộc người gọi trộn tác vụ tải lên, tải trực tiếp và tải đã lưu. Nó giới hạn tác vụ giữ lại (32), giai đoạn đồng thời (4), mức đồng thời kết nối ứng dụng khách, phần đặt trước khối giải mã (64–256 KiB), tốc độ và thử lại. Công việc đủ điều kiện tiếp tục vượt qua kết nối bão hòa, và ưu tiên khởi đầu có giới hạn tránh tác vụ nhỏ đủ điều kiện bị bỏ đói. Tác vụ tạm dừng hoàn tất giai đoạn hiện tại rồi đợi; tạm dừng có thể giữ khóa lưu trữ. Tổng hạn gồm thời gian chờ hàng đợi và tạm dừng.

Tự thử lại chỉ giới hạn ở 429/503 mà SDK nhận diện, mất mạng hoặc hết thời gian yêu cầu trong thao tác khối chính xác có tính lũy đẳng, với backoff và jitter giới hạn. Xử lý rõ ràng begin/commit, lỗi ủy quyền, tổng kiểm tra, phạm vi, nguồn hay sink. acknowledgedBytes, transferredBytes, attemptedBytes, retriedBytes, resumedBytes và remainingBytes riêng biệt; chỉ biên nhận đã xác minh tạo completed. cancel/dispose dừng công việc còn lại trong khi tệp đã commit vẫn giữ byte.

Tiếp tục tải xuống trình duyệt

// 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.

Phục hồi lâu dài cần Worker chuyên dụng, truy cập đồng bộ OPFS và Web Locks. Người gọi chọn lại thư mục và UUID phần tải dở sau tải lại, rồi lấy tham chiếu đã lưu mới được phê duyệt. Sink lưu hai tên tệp dữ liệu/siêu dữ liệu chính xác, toàn danh tính bản chụp bất biến, hạn và hàm băm tiền tố hiện tại/trước. Nó không lưu token, quyền hay phạm vi kết nối cũ. Mỗi khối dữ liệu được flush trước khi luồng siêu dữ liệu nhỏ đóng.

Cả sink và trình trợ giúp độc lập băm lại tiền tố. Phần đuôi chưa có điểm kiểm tra chỉ bị cắt sau khi tiền tố ghi nhận khớp. Siêu dữ liệu vượt kích thước tệp thực chỉ có thể quay lại điểm kiểm tra trước nếu byte và hàm băm đó khớp; hỏng, thiếu mục, hết hạn hay bản chụp khác thất bại mà không âm thầm bắt đầu lại. Khóa độc quyền toàn origin từ chối tab khác, được giữ qua đọc lại và trả khi đóng hoặc Worker kết thúc. Mở lại sau đó cần phục hồi rõ ràng.

Siêu dữ liệu cục bộ giới hạn 16 KiB và bốn phiên sink mở. Lưu giữ mặc định một giờ, tối đa 24 giờ và bị chặn bởi hạn bản chụp máy chủ. Lưu trữ tuân theo quota, loại bỏ dữ liệu và thẩm quyền script cùng origin của trình duyệt. Mô hình phục hồi điểm kiểm tra bao trùm các kịch bản gián đoạn tiến trình được thử bên dưới; kiểm chứng hành vi mất điện trong môi trường triển khai. Chromium 154 trên Windows đã được thử với hủy, tải lại, khởi động lại máy chủ, xung đột hai tab và kết thúc tab chủ, kèm hàm băm toàn tệp đã lưu. Chạy các kịch bản đánh giá trên từng tổ hợp trình duyệt/hệ điều hành đích.

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

Truyền theo luồng · Tải lên · Hàng đợi truyền · Phục hồi Worker

Trợ giúp chữ ký và hỗ trợ hoàn thành

Khai báo signature-help, completion-resolve và completion-snippets khi cần trong manifest v2; bộ sửa đổi hoàn thành cũng cần completion. Máy chủ phải cấp document.read và language.provide. Hoàn thành nguyên dạng hiện có vẫn hợp lệ. languageCapabilities() báo triển khai SDK và giới hạn mà không cấp quyền.

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

Ứng dụng cung cấp vị trí hiện tại và máy chủ; chuẩn bị trả dữ liệu mà không ghi tài liệu hay tệp. Trợ giúp chữ ký hỗ trợ tối đa 16 chữ ký, mỗi chữ ký 64 tham số và độ lệch nhãn tham số UTF-16. Phân giải hoàn thành giữ dữ liệu nhà cung cấp riêng tư, trả token máy chủ dùng một lần và cố định nhãn/chèn/phạm vi đã chọn. Token ràng buộc nhà cung cấp, phạm vi và tài liệu, hết hạn sau 60 giây, giới hạn 128 mục, 4 MiB và bốn thao tác resolver thực. Thay đổi tài liệu/nhà cung cấp loại bỏ chúng.

Đoạn mã hỗ trợ $n, ${n}, ${n:literal}, $0 và escape được mô tả, với bản sao và điểm dừng tab có thứ tự. Biến, lồng nhau, lựa chọn, biến đổi và lệnh thực thi bị từ chối. Ranh giới UTF-16/CRLF và chỉnh sửa bổ sung chồng lấn được kiểm tra. Nhà cung cấp chạy dưới dạng mã trong tiến trình đáng tin cậy với thẩm quyền tiến trình máy chủ; bỏ qua hủy vẫn chiếm slot chờ thực tế cho tới khi nhà cung cấp hoàn tất.

Chỉnh sửa không gian làm việc có xem xét và đổi tên

prepare-rename trả phạm vi/placeholder đã xác minh hoặc null; rename trả đề xuất WorkspaceEdit hoặc null. Đề xuất hỗ trợ sửa, tạo, di chuyển và xóa trên đường dẫn tệp tương đối không giao nhau. SHA-256 nguồn hiện tại, đích chưa tồn tại, chính sách đường dẫn bảo vệ, hình học chỉnh sửa UTF-16 và giới hạn được kiểm tra. Khả năng ngôn ngữ cấp quyền đề xuất; ứng dụng khách không gian làm việc cung cấp quyền truy cập tệp và thay đổi được phê duyệt riêng.

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

Người gọi dùng ứng dụng khách không gian làm việc đã kết nối, được cho phép và nhật ký đáng tin cậy. Xem trước chứa bản chụp trước/sau đầy đủ và giá trị băm; apply cần planId/digest đã xem xét cùng chính sách máy chủ hiện tại trả true. Mọi tệp được kiểm tra sơ bộ, rồi mỗi thao tác dùng CAS từng tệp hiện có và khả năng ghi/quản lý hiện tại. Nhật ký lưu bền và đọc lại ý định trước mỗi thay đổi, biên nhận sau đó. Xung đột hoặc không chắc chắn dừng ghi tiếp; mỗi tệp giữ ranh giới giao dịch CAS riêng.

Bộ điều hợp workspace-edits-node tùy chọn lưu nhật ký giới hạn ngoài không gian làm việc đã chọn, ràng buộc danh tính và dùng khóa một tiến trình ghi, tệp thường cùng điểm kiểm tra tổng kiểm tra. Sau kết thúc tiến trình, recoverStaleLock là lựa chọn rõ ràng và chỉ thu hồi chủ đã chứng minh chết. Phục hồi báo applied/not-applied/conflicted/unknown từ byte hiện tại; bên gọi chủ động quyết định hành động tiếp theo. Bù trừ tạo đề xuất đảo mới để xem xét mới. Trên Windows, bộ điều hợp đồng bộ hóa tệp và thực hiện thao tác đổi tên; kiểm tra bao trùm kết thúc và phục hồi tiến trình, còn lưu bền tuân theo hệ thống tệp và thiết bị lưu trữ. Giới hạn gồm 32 thay đổi, 1000 chỉnh sửa, 256 KiB mỗi tệp, xem trước 8 MiB và 64 kế hoạch nhật ký giữ lại.

Định dạng và hành động mã chẩn đoán

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 và format-range cần đường dẫn và tùy chọn tabSize/insertSpaces; chỉ định dạng phạm vi nhận vùng chọn. Kết quả là null hoặc đúng một chỉnh sửa tệp hiện tại với hàm băm bản chụp hiện tại. Chỉnh sửa phạm vi nằm trong vùng chọn. endOfLine chọn preserve, lf hoặc crlf cho văn bản chèn; byte không sửa giữ nguyên. Đề xuất có nội dung giống nhau được chuẩn hóa thành null. prepareFormatting không ghi.

Máy chủ ràng buộc yêu cầu hành động và token resolve với phiên bản chẩn đoán đã chấp nhận và bản chụp hiện tại. Công bố chẩn đoán sau, đổi tài liệu hoặc giải phóng nhà cung cấp vô hiệu lựa chọn cũ. Gọi chẩn đoán sai thứ tự không ghi đè gói mới hơn đã chấp nhận. Tối đa 100 hành động mang nhãn thuần, chỉ số chẩn đoán giới hạn, chỉnh sửa đề xuất, dữ liệu resolve riêng hoặc lý do tắt. Trường command/URL/shell không biết bị từ chối. Chỉnh sửa hành động có thể vượt vùng chọn, nên xem toàn đề xuất; định dạng và hành động không bao giờ tự phê duyệt việc ghi.

Hiển thị ngữ nghĩa, gấp mã, gợi ý và ký hiệu

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

Token ngữ nghĩa dùng bảng chú giải có tên duy nhất và chín khóa style thuộc máy chủ, cùng năm số nguyên mỗi token: delta dòng/bắt đầu, độ dài UTF-16, chỉ số kiểu và bit sửa đổi. Token không thể chồng lấn, tách surrogate, qua dòng hay vượt tài liệu hiện tại. Máy chủ luôn trả mảng chuẩn hóa đầy đủ và UUID máy chủ, với updateKind full/delta/fallback. Khả năng semantic-tokens-delta riêng bật provideDelta với dữ liệu trước thuộc nhà cung cấp; cache lưu danh tính và dữ liệu token, không lưu văn bản tài liệu cũ.

Cơ sở cache ràng buộc nhà cung cấp, phạm vi, URI và ngôn ngữ, tối đa tám mục, 4 MiB và 60 giây. Phiên bản tài liệu tăng thông thường giữ cơ sở delta có thể dùng, đồng thời làm kết quả hiển thị cũ lỗi thời. Cơ sở mất/hết hạn, delta null hoặc ID cơ sở nhà cung cấp không khớp cho phép tối đa một lần dự phòng đầy đủ trong hạn gốc. Dữ liệu không hợp lệ hoặc lỗi nhà cung cấp thất bại không thử lại. Vô hiệu hóa, hủy đăng ký và thay tài liệu xóa cơ sở bị ảnh hưởng. Gọi validateLanguageResult ngay trước hiển thị; đối tượng sao chép, đã giải phóng hay cũ thất bại.

Giới hạn là 20000 token ngữ nghĩa, 64 kiểu token, 16 bộ sửa đổi và 64 chỉnh sửa delta; gấp mã cho phép 1000 phạm vi, độ sâu 32 và từ chối phạm vi cắt nhau. Inlay hint cho phép 1000 nhãn thuần một dòng trong phạm vi yêu cầu. Ký hiệu phân cấp cho phép tổng 1000 mục và 16 cấp, với con/vùng chọn được chứa và anh em có thứ tự không chồng lấn. Hợp đồng document-symbols phẳng gốc không đổi. Ví dụ trình duyệt thử full/delta/fallback, gấp mã, điều hướng và vòng đời; gợi ý giống HTML vẫn là văn bản nguyên dạng.

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

Hỗ trợ · Chỉnh sửa có xem xét · Định dạng/hành động · Hiển thị

Thiết lập có kiểu và tham chiếu bí mật

Mô-đun /settings cung cấp kho bộ nhớ thuộc người vận hành cho một plugin. Định nghĩa theo phiên bản khai báo từng khóa, schema dữ liệu, mặc định, phạm vi người dùng/không gian làm việc được phép và siêu dữ liệu hiển thị. Giá trị hiệu lực thay toàn bộ từng khóa theo thứ tự default < user < workspace. read(workspaceId) trả giá trị, nguồn bất biến và phiên bản toàn kho. Đối tượng lồng không được hợp nhất đệ quy; giá trị thiếu không có mặc định vẫn vắng mặt.

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}, ...}).

Ghi xác minh toàn giao dịch và dùng CAS expectedRevision. reset xóa khóa khỏi một lớp; readOnly cần mặc định và không có phạm vi ghi. Đăng ký gộp thay đổi đồng bộ và trả handle có thể giải phóng. migrate(nextDefinition, callback, options) rõ ràng xác minh trạng thái tiếp và chỉ commit khi phiên bản vẫn khớp. Thất bại, hủy hoặc hết thời gian giữ định nghĩa và trạng thái cũ. Xuất/nhập là dữ liệu thuần; người vận hành quản lý lưu bền và mã hóa. Giới hạn gồm 64 khóa, 32 lớp không gian làm việc, trạng thái xuất 1 MiB và một chuyển đổi thực tế.

Plugin không gian làm việc khai báo settings và settings.read, và người vận hành gắn kho tương ứng với quyền đó. context.settings chỉ đọc, ràng buộc plugin và không gian làm việc đã chọn. Resolver /secrets cấp riêng tham chiếu opaque cho plugin, không gian làm việc, danh sách lệnh cho phép và vòng đời. Manifest phải khai báo secrets.resolve và máy chủ phải cấp nó. Trường đầu vào dùng type: object với format: dds-secret-reference; chuỗi thường và đối tượng trông giống không mang thẩm quyền bí mật.

Chỉ tham chiếu trong đầu vào đã xác minh mới khả dụng qua options.secrets.withSecret của lệnh. Mỗi thực thi có ID mới; resolver kiểm tra phạm vi, hết hạn, thu hồi và ủy quyền hiện tại quanh phân giải và callback. Callback trả undefined và nhận bản sao bị xóa khi hủy và mọi lần thoát. Lỗi nhà cung cấp được làm sạch. Đặt lease trước tác động cần thẩm quyền đó. Vòng đời tham chiếu mặc định 60 giây, tối đa một giờ; giới hạn 128 tham chiếu, 8 lease thực và 16 KiB dữ liệu bí mật. Chỉ chạy mã đáng tin cậy với thẩm quyền tiến trình máy chủ, vì mã có thể giữ bản sao. Không đưa dữ liệu bí mật vào thiết lập, gói, nhật ký hay kết quả; chủ động phân loại chuỗi ứng dụng tùy ý khi xử lý bí mật.

Schema lệnh có cấu trúc và biểu mẫu

Lệnh có thể khai báo inputSchema và outputSchema bằng phong bì schemaVersion: 1. Tham số nguyên thủy hiện có vẫn hỗ trợ; khai báo đồng thời parameters và inputSchema bị từ chối. Máy chủ xác minh và áp dụng mặc định đầu vào trước khi bắt đầu trình xử lý hoặc tác vụ, rồi xác minh đầu ra trước khi công bố thành công. Mặc định đầu ra không bao giờ được áp dụng. Siêu dữ liệu schema/hiển thị mới cần peer hiểu 0.12; trình xác minh nghiêm ngặt cũ từ chối, còn định nghĩa kế thừa giữ hành vi.

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

Tập con giới hạn hỗ trợ đối tượng đóng, mảng, chuỗi, số hữu hạn, số nguyên an toàn, boolean, null, enum nguyên thủy, ràng buộc và mặc định đã xác minh. Từ khóa không biết, tham chiếu từ xa, regex, union, ép kiểu, accessor và prototype tùy chỉnh bị từ chối. Schema cho phép 32 KiB, độ sâu 8 và 128 nút; giá trị cho phép 64 KiB. Lệnh đầy đủ giữ ngân sách siêu dữ liệu 16 KiB. DataValidationError cục bộ cung cấp code, reason và đường dẫn trường đã biết như /input/options/names/0; lỗi HTTP và tác vụ cung cấp mã an toàn không có giá trị bị từ chối.

describeDataForm trả đường dẫn, kiểu, lựa chọn, mặc định, cờ bắt buộc và gợi ý tham chiếu bí mật. Siêu dữ liệu hiển thị chung mang label/help/order nguyên dạng cùng tên, mô tả và gợi ý bàn phím cho khả năng tiếp cận. Máy chủ quản lý hiển thị và tương tác. Schema mô tả dữ liệu nguyên dạng để máy chủ hiển thị và quản lý tương tác rõ ràng.

Siêu dữ liệu bản địa hóa và khả năng tiếp cận

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.

Danh mục sử dụng các thẻ cơ sở BCP 47 chuẩn tắc và các cạnh dự phòng phi chu trình rõ ràng. Tối đa tám tùy chọn điều phối các thẻ chính xác, sau đó là tổ tiên và mặc định. Ngôn ngữ mặc định xác định tất cả các khóa; bản dịch có thể bỏ qua khóa nhưng không thể tạo khóa mới. Tra cứu từng khóa tuân theo các cạnh dự phòng có thứ tự, sau đó là mặc định. Mọi bản dịch và đối số của nó phải khớp với bộ giữ chỗ {name} chính xác. Đây là phép nội suy theo nghĩa đen không có biểu thức ICU. resolveMessage báo cáo ngôn ngữ nguồn và hướng thực tế, do đó dự phòng tiếng Anh bên trong trang RTL có thể giữ lại lang=en và dir=ltr.

Định dạng số hỗ trợ decimal/percent; định dạng ngày dùng epoch rõ ràng và mặc định UTC; chọn số nhiều trả loại cardinal/ordinal Intl để người gọi chọn thông điệp. Máy chủ quản lý dữ liệu và hỗ trợ Intl. validateLocalizedSurfaces kiểm tra khóa manifest/command/settings/schema và sidecar hiển thị chủ đề, gồm độ dài hiển thị đã phân giải và bản dịch thiếu. JSON/XML chủ đề vẫn tương thích. Giới hạn danh mục 32 ngôn ngữ, 256 khóa và 256 KiB; nhãn tĩnh không thể chứa placeholder.

Trình trợ giúp /accessibility báo tên thiếu, phím tắt chuẩn hóa trùng và độ tương phản cặp màu opaque rõ ràng trong chủ đề sáng/tối. Dùng các gợi ý này khi triển khai gán phím hệ điều hành do máy chủ quản lý và đánh giá khả năng tiếp cận. Ví dụ độc lập gồm EN/KO, tiếng Ả Rập một phần và dữ liệu mẫu nhãn dài. Nó thử thiết lập theo phạm vi, tham chiếu bị từ chối/thu hồi, trường không hợp lệ, Ctrl+Enter và đổi ngôn ngữ khi lệnh đang chờ. Bố cục trình duyệt đã kiểm tra ở kích thước máy tính/di động trong chủ đề sáng/tối.

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

Thiết lập · Tham chiếu bí mật · Schema lệnh · Bản địa hóa

Mẫu phát triển và sinh mã

Sáu mẫu, phụ thuộc kho chính xác, xem xét sinh mã, giữ xung đột và kiểm tra doctor.

Hợp đồng, ví dụ và giới hạn đầy đủ

Kiểm tra xác định và phát lại

Dữ liệu mẫu tổng hợp rõ ràng, thời gian ảo, lỗi, trace chỉ hàm băm có giới hạn và dọn tài nguyên.

Hợp đồng, ví dụ và giới hạn đầy đủ

Chẩn đoán và gỡ lỗi cục bộ

Hồ sơ cục bộ tùy chọn và trình gỡ lỗi con đáng tin cậy với điểm cuối loopback tạm cùng tổng hạn.

Hợp đồng, ví dụ và giới hạn đầy đủ

Tính phù hợp máy chủ

18 hồ sơ theo phiên bản phân biệt hợp đồng được hỗ trợ, không hỗ trợ và thất bại; bộ điều hợp tùy chỉnh giữ thẩm quyền rõ ràng.

Hợp đồng, ví dụ và giới hạn đầy đủ

Hỗ trợ SDK và chuyển đổi

Xem danh sách export, chính sách ổn định/tùy chọn/thử nghiệm, peer chính xác, ngày runtime và ví dụ chuyển đổi.

Hợp đồng, ví dụ và giới hạn đầy đủ

Nghiệm thu phát hành

Kiểm tra bản phát hành đã công bố kết hợp khối lượng lỗi và các ngưỡng hiệu năng đo được để xác minh hành vi SDK được thử.

Hợp đồng, ví dụ và giới hạn đầy đủ

1.1 Công cụ phụ thuộc, nguồn gốc và cập nhật

1.1.0 thêm gói ngoại tuyến xác định của phụ thuộc đã xem xét, SBOM CycloneDX, chữ ký tách rời bằng khóa Ed25519 thuộc người vận hành, phê duyệt/kích hoạt/hoàn tác ràng buộc giá trị băm và so sánh upstream rõ ràng. Năm điểm vào chỉ Node gồm khai báo, schema và ví dụ độc lập. Máy chủ chủ động cấp quyền thực thi và tác vụ cũ giữ hàm băm gốc. Người vận hành quản lý phân phối, triển khai và theo dõi. Dùng ví dụ độc lập để kiểm tra hợp đồng gói, chữ ký, cập nhật và upstream.

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

Hướng dẫn đầy đủ về gói, chữ ký, cập nhật và upstream

1.2 Quy trình, cache, luồng công cụ và LSP

1.2.0 thêm DAG lệnh đã xem xét với tác vụ/quyền từng bước, điểm kiểm tra bền vững và phục hồi lần thử mới rõ ràng; cache xác định dựa trên nội dung và thực thi tăng dần; luồng công cụ UTF-8/JSONL/văn bản giới hạn; cầu nối LSP 3.17 stdio tùy chọn. Bảy điểm vào mới đưa gói lên 50 export và 107 schema với khai báo và ví dụ đã cài độc lập, không có phụ thuộc npm runtime. Trình phân tích luồng công cụ cũng chạy trong trình duyệt; quy trình, kho, tiến trình ngoài và LSP cần Node. Bộ điều hợp thực đã kiểm tra với TypeScript 5.9.3 và language-server 5.3.0, và cầu nối yêu cầu chẩn đoán LSP có phiên bản. Người vận hành chủ động khởi tạo phục hồi và cấu hình tích hợp dịch vụ hoặc sản phẩm. Các kiểm tra bộ điều hợp này xác minh hành vi SDK độc lập được thử.

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

Hướng dẫn đầy đủ về quy trình, cache, công cụ và LSP