DDS Plugin SDK

सार्वजनिक DDS Plugin SDK 1.2 इंस्टॉल करें और वर्कफ़्लो, कैश, टूल स्ट्रीम, LSP और स्थिर API का उपयोग करें।

नीचे दिए गए उपयोगकर्ता कार्यक्षेत्र के उदाहरण एक स्पष्ट रूप से जुड़े, ग्राहक के नियंत्रण वाले विकास होस्ट का वर्णन करते हैं। इन स्वतंत्र SDK उदाहरणों के होस्ट के लिए WSL, कंटेनर या सर्वर चुनें। सामान्य Digital Design Studio Windows ऐप Windows पर नेटिव रूप से चलता है। चुना SDK होस्ट खोज, अनुमतियाँ और प्लगइन क्षमताएँ सँभालता है; प्रबंधित Cloud इंजन जॉब अपना निष्पादन पथ उपयोग करती हैं।

1. SDK इंस्टॉल करें

DDS Plugin SDK 1.2.1 में JavaScript API, TypeScript घोषणाएँ, भाषा प्रदाता, थीम, कार्यक्षेत्र टूल और कमांड जॉब उपलब्ध हैं। वैकल्पिक टिकाऊ स्टोर जॉब इतिहास, स्पष्ट पुनः प्रयास और सत्यापित टेक्स्ट/बाइनरी स्नैपशॉट जोड़ते हैं, जो स्रोत हटने और प्रक्रिया पुनः शुरू होने के बाद भी रहते हैं। Node.js 22 या 24 का उपयोग करें। स्थिर SDK रिलीज़ इंस्टॉल करने के लिए देखें: आधिकारिक GitHub रिलीज़। स्वतंत्र कमांड प्लगइन के लिए इंस्टॉलेशन के बाद उपयोग करें: विकास टूल:

1.0.0 स्थिर SDK API, होस्ट अनुरूपता के 18 प्रोफ़ाइल, समर्थन/माइग्रेशन नीति और संयुक्त कार्यभार की मापी गई जाँचें प्रकाशित करता है। नए प्लगइन >=1.0.0 <2.0.0 का उपयोग करते हैं। ये प्रकाशित परिणाम स्वतंत्र SDK की API अनुरूपता और कार्यात्मक व्यवहार का वर्णन करते हैं।

0.13.0 छह विकास टेम्पलेट, जनरेट किए गए प्रकार और स्कीमा, नियतात्मक परीक्षण परिदृश्य और वैकल्पिक स्थानीय निदान जोड़ता है। पैक किया गया SDK और जनरेट किए गए प्रोजेक्ट स्रोत ट्री के बाहर चलते हैं; कृत्रिम रीप्ले और लूपबैक डिबगिंग स्पष्ट रूप से चुने जाते हैं।

0.12.0 सीमित दायरे वाली टाइपयुक्त सेटिंग और स्पष्ट माइग्रेशन, निष्पादन के दायरे वाले सीक्रेट संदर्भ, संरचित कमांड इनपुट/आउटपुट, लोकेल कैटलॉग और सुलभता मेटाडेटा जोड़ता है। सार्वजनिक SDK और स्वतंत्र उदाहरण सेटिंग संघर्ष, अमान्य इनपुट, निरस्त अधिकार और अनुवाद फ़ॉलबैक की जाँच करते हैं। इन सुविधाओं का उपयोग स्वतंत्र SDK होस्ट API और उदाहरणों से करें।

0.11.0 सिग्नेचर सहायता, ज़रूरत पड़ने पर पूर्णता, सीमित स्निपेट, समीक्षा किए गए बहु फ़ाइल संपादन और नाम बदलना, फ़ॉर्मैटिंग/कोड कार्रवाइयाँ, सिमैंटिक टोकन, फ़ोल्डिंग, संकेत और पदानुक्रमित प्रतीक जोड़ता है। प्रस्ताव, समीक्षा, मौजूदा अधिकार और शर्त के अनुसार लागू करना अलग रहते हैं; पुराने दस्तावेज़ के परिणाम दिखाए या लागू नहीं किए जा सकते। इन सार्वजनिक SDK सुविधाओं का उपयोग स्वतंत्र होस्ट और उदाहरणों में करें।

0.10.0 ब्राउज़र में स्ट्रीमिंग डाउनलोड, चुनी हुई फ़ाइल के अपलोड, मिश्रित ट्रांसफ़र कतार और Worker OPFS चेकपॉइंट पुनर्प्राप्ति जोड़ता है। ट्रांसफ़र मौजूदा अधिकार, फ़ाइल पहचान और खंड/पूरी फ़ाइल के हैश की जाँच करते हैं और बाइट प्रगति को सत्यापित संग्रहण से अलग रखते हैं। होस्ट और ब्राउज़र संग्रहण गंतव्य स्पष्ट रूप से चुनकर ये सार्वजनिक SDK उदाहरण चलाएँ।

0.9.0 ऑपरेटर द्वारा चुनी गई स्थानीय डायरेक्टरी के लिए सीमित दायरे वाले प्रोजेक्ट ट्री, फ़ाइल नाम/टेक्स्ट खोज और बदलाव का निरीक्षण जोड़ता है। संपादन स्नैपशॉट और बिना सहेजे ड्राफ़्ट रखते हुए इन्हें HTTP क्लाइंट या प्रोजेक्ट हेल्पर से उपयोग करें। नीचे के प्रोजेक्ट उदाहरण निर्माण, खोज, बाहरी बदलाव और संघर्ष संभालना कवर करते हैं।

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

पहला निदान उदाहरण स्थानीय परीक्षण होस्ट में विश्वसनीय कोड उपयोग करता है। थीम मौजूदा DDS XML आयात का उपयोग करती हैं। मौजूदा टूल एकीकरण के लिए देखें: प्लगइन और तृतीय पक्ष टूल.

2. अपना पहला प्लगइन लिखें

नए प्रोजेक्ट में plugin.mjs बनाएँ। यह प्लगइन सादे पाठ दस्तावेज़ों की जाँच करता है और NOTE वाली प्रत्येक पंक्ति पर एक सूचनात्मक नैदानिक रिपोर्ट करता है।

plugin.mjs

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

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

मैनिफ़ेस्ट प्रोटोकॉल संस्करण 1 और यह क्षमता घोषित करता है: diagnostics; होस्ट है: test-host; अनुमतियाँ हैं: document.read और diagnostics.publish। प्रदाता को दस्तावेज़ का स्नैपशॉट और यह मिलता है: AbortSignal। निदान की रेंज शून्य से शुरू होने वाली पंक्तियाँ और UTF-16 वर्ण ऑफ़सेट उपयोग करती हैं।

3. इसे स्थानीय रूप से चलाएँ

बनाएँ: run.mjs, इसके पास: plugin.mjs। प्लगइन सक्रिय करें, दस्तावेज़ दें और निदान माँगें। काम पूरा होने पर होस्ट को हमेशा डिस्पोज़ करें।

run.mjs

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

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

अपेक्षित आउटपुट (छपी हुई पंक्ति और स्तंभ एक से शुरू होते हैं):

टेक्स्ट

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

4. अपने प्लगइन का परीक्षण करें

इस परीक्षण को इस नाम से सहेजें: plugin.test.mjs। यह निदान की रेंज जाँचता है और पुष्टि करता है कि दस्तावेज़ संपादित करने पर निदान हट जाता है।

plugin.test.mjs

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

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

परीक्षण सफल होना चाहिए। अपनी भाषा, रद्दीकरण, अमान्य परिणाम और बड़े दस्तावेज़ों के लिए फ़िक्स्चर जोड़ें। दस्तावेज़ का संस्करण वर्तमान रखें ताकि पुराने स्नैपशॉट के परिणाम अस्वीकार हों।

5. थीम बनाएँ और लागू करें

इस लाइट/डार्क पैलेट को theme.json के रूप में सहेजें। प्रत्येक पैलेट में छह रंग आवश्यक हैं। वैकल्पिक सिमेंटिक टोकन खोज, चयन, HintsBox और GDS कैनवास को अनुकूलित करते हैं; छोड़े गए टोकन DDS डिफ़ॉल्ट का उपयोग करते हैं।

theme.json

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

बनाएँ: export-theme.mjs, इसके पास। parseTheme रंगों का डेटा सत्यापित करता है और serializeThemeXml DDS XML संस्करण 2 निर्यात करता है।

export-theme.mjs

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

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

कमांड लिखती है: hello-theme.xml और प्रिंट करती है: Created hello-theme.xml। DDS में खोलें: प्लगइन्स → स्थापित विषय ..., XML चुनें, फिर चुनें: लागू करें, इस थीम के लिए: Hello Ocean। दोनों पैलेट देखने के लिए हल्के और गहरे रूप के बीच बदलें।

आप यह भी उपयोग कर सकते हैं: सेटिंग → सामान्य → रूप-रंग → XML आयात करें। बदलने से पहले मौजूदा थीम सहेजें: XML निर्यात करें। इससे XML रूप डेटा थीम कॉन्फ़िगरेशन में आयात होता है।

यह थीम मार्गदर्शिका सभी समर्थित टोकन और मापदंड सूचीबद्ध करती है। यह Hello Ocean उदाहरण पूरी थीम, आयात के लिए तैयार XML और स्थानीय HTML पूर्वावलोकन देता है।

थीम XML संदर्भ

डाउनलोड करें: Hello Ocean XML और उसका संपादन योग्य JSON। XML में पूरे हल्के और गहरे पैलेट, प्रत्येक मोड के सभी 28 वैकल्पिक भूमिका रंग और चार स्पष्ट मापदंड हैं। आयात से पहले XML फ़ाइल स्थानीय रूप से सहेजें। ये मूल SDK उदाहरण यह लाइसेंस उपयोग करते हैं: Apache-2.0; इन्हें साझा करते समय यह बनाए रखें: सूचना।

मौजूदा थीम का बैकअप लेने के लिए पहले खोलें: सेटिंग → सामान्य → रूप-रंग → XML निर्यात करें। डाउनलोड किया XML आयात करें, ड्राफ़्ट की समीक्षा करें, फिर चुनें: लागू करें. बदलाव छोड़ें लागू थीम को बनाए रखता है। दोनों पैलेट की समीक्षा के लिए हल्का/गहरा रूप बदलें। पुनर्प्राप्ति के लिए अंतर्निहित थीम चुनें या अपनी सहेजी प्रति आयात करें। अस्वीकार किया गया आयात मौजूदा थीम को बनाए रखता है।

DDS, ALcad, साझा एडिटर, प्रोजेक्ट नेविगेशन, सेटिंग और पॉपअप उस प्रोफ़ाइल में साझा वर्कबेंच पैलेट का उपयोग करते हैं। Cloud और डेस्कटॉप में समान थीम फ़ॉर्मैट उपयोग होता है; प्रत्येक प्रोफ़ाइल में अलग आयात करें। gdsBackground GDS कैनवस को स्वतंत्र रूप से नियंत्रित करता है। अन्य डिज़ाइन कैनवस, लेयर और सिमुलेशन रंगों की अपनी सेटिंग हो सकती हैं। XML इस थीम प्रोफ़ाइल के पैलेट और रूप के संख्यात्मक मान रखता है।

एलिमेंट

नियम

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

एक रूट; खाली किनारे हटाने के बाद 1–80 UTF-16 कोड यूनिट का नाम; पूरे XML के लिए अधिकतम 65,536 UTF-8 बाइट।

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

दोनों अनिवार्य हैं; प्रत्येक में नीचे दिए गए छह रंग हों।

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

वैकल्पिक v2 ओवरराइड। छोड़ी गई भूमिकाएँ उस मोड के DDS डिफ़ॉल्ट का पालन करती हैं।

<metrics>

वैकल्पिक v2 संख्यात्मक ओवरराइड।

संस्करण 1

केवल दोनों पैलेट। मौजूदा v1 फ़ाइलें अभी भी समर्थित हैं; SDK निर्यातक v2 निकालता है।

अनिवार्य पैलेट कुंजी

उपयोग

backdrop

बाहरी कार्यक्षेत्र की पृष्ठभूमि

navigation

प्रोजेक्ट नेविगेशन

tool

टूल पैनल और नियंत्रण

main

मुख्य कार्यक्षेत्र और सेटिंग

text

मुख्य टेक्स्ट

muted

गौण टेक्स्ट

वैकल्पिक भूमिका कुंजियाँ (28)

उपयोग

search, searchText, searchPlaceholder

साझा खोज की पृष्ठभूमि, टेक्स्ट और प्लेसहोल्डर

searchBorder

संगतता फ़ील्ड; मौजूदा साझा खोज फ़ील्ड में बॉर्डर नहीं हैं

selection, selectionText

चुनी हुई पंक्तियाँ और टेक्स्ट

tabActive, tabInactive, tabText

एडिटर टैब

rail, panelBorder, popover

टूल रेल, पैनल सीमाएँ और पॉपअप

focus

कीबोर्ड फ़ोकस की रूपरेखा

success, warning, danger, info, aiBall

स्थिति के रंग और AI गेंद की पृष्ठभूमि

hintsBoxBackground, hintsBoxDetailsBackground

सुझाव और विवरण की पृष्ठभूमियाँ

hintsBoxText, hintsBoxDetailsText, hintsBoxMutedText

सुझाव, विवरण और गौण टेक्स्ट

hintsBoxSelectedBackground, hintsBoxSelectedText

कीबोर्ड से चुना गया सुझाव

hintsBoxHoverBackground, hintsBoxHoverText

पॉइंटर के होवर वाला सुझाव

gdsBackground

GDS व्यूअर कैनवस की पृष्ठभूमि

HintsBox साझा कोड सुझाव सुविधा है। इसके रंग यहाँ मिलते हैं: कस्टम → विस्तृत रंग और आकार → HintsBox और GDS की पृष्ठभूमि यहाँ: प्रदर्शन। पठनीय कॉन्ट्रास्ट के लिए खोज के तीनों रंग साथ संपादित करें। यह खंड v2 थीम के अंदर रखा जाता है; दोनों पूरे पैलेट बनाए रखें:

XML v2 खंड

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

मापदंड

अनुमत मान

मौजूदा DDS डिफ़ॉल्ट

panelRadius

पूर्णांक 0–24

14

controlRadius

पूर्णांक 0–16

6

popoverRadius

पूर्णांक 0–24

16

popoverOpacity

संख्या 0.6–1

0.72

मापदंड इस तरह लिखें: <number key="popoverOpacity" value="0.9"/>, इसके अंदर: <metrics>, बिना इकाई के। त्रिज्या के मान पिक्सेल में हैं। SDK छोड़े गए मापदंड अनुपस्थित रखता है; इंस्टॉल की गई DDS रिलीज़ अपने डिफ़ॉल्ट देती है। समान रूप के लिए स्पष्ट मान सेट करें। Hello Ocean जानबूझकर 16, 8, 12 और 0.9 सेट करता है। कम पारदर्शिता और बाध्य रंग की सेटिंग अंतिम रेंडरिंग बदल सकती हैं।

हर रंग छह अंकों वाला होना चाहिए: #RRGGBB; अल्फ़ा, CSS नाम, वैरिएबल, URL और स्टाइल अस्वीकार होते हैं। दोहराई गई कुंजियाँ या मोड, अज्ञात एलिमेंट/एट्रिब्यूट, नेमस्पेस, DTD, एंटिटी और प्रोसेसिंग निर्देश अस्वीकार होते हैं। XML घोषणाएँ और टिप्पणियाँ अनुमत हैं। आयात विफल हो तो फ़ाइल का आकार, संस्करण, दोनों पूरे पैलेट और समर्थित मान जाँचें, फिर अपरिवर्तित बैकअप के साथ पुनः प्रयास करें। दूसरे एडिटर की थीम को इस DDS फ़ॉर्मैट में बदलना पड़ता है।

6. अपने परिवेश में कार्यक्षेत्र चलाएँ

होस्ट, SDK, प्लगइन और टूल अपने WSL, कंटेनर या सर्वर परिवेश में चलाएँ। प्रोजेक्ट फ़ाइलें आपके चुने रूट में रहती हैं। स्वतंत्र SDK क्लाइंट कनेक्शन से उन्हें पढ़ता और संपादित करता है; उसे प्लगइन मेटाडेटा और कमांड परिणाम मिलते हैं, जबकि प्लगइन कोड आपके परिवेश में चलता है।

ऊपर बनाए गए SDK प्रोजेक्ट में इस हेल्पर को इस नाम से सहेजें: copy-workspace-example.mjs। यह उदाहरण के लाइसेंस फ़ाइल लेआउट को बनाए रखते हुए संपादन योग्य सर्वर, प्लगइन, टूल और नमूना प्रोजेक्ट कॉपी करता है।

copy-workspace-example.mjs

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

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

नमूना प्रोजेक्ट है: user-host/examples/user-workspace/project। उस परिवेश में स्पष्ट रूप से जनरेट किए टोकन से सर्वर शुरू करें:

WSL / Linux / कंटेनर

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

PowerShell

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

सर्वर प्रिंट करता है: Workspace server: http://127.0.0.1:4777/dds/workspace/v1, साथ में कार्यक्षेत्र ID और जेनरेशन। क्लाइंट टर्मिनल में DDS_WORKSPACE_TOKEN पर्यावरण चर को जनरेट किए टोकन पर सेट करें। यह ऑपरेटर क्रेडेंशियल है, DDS Account टोकन से अलग। नमूना सर्वर Ctrl+C से रोकें।

उसी प्रोजेक्ट के दूसरे टर्मिनल में सेट करें: DDS_WORKSPACE_TOKEN, उसी सीक्रेट पर, और डेवलपर क्लाइंट चलाएँ:

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

क्लाइंट नमूना फ़ाइलें सूचीबद्ध करता है और चलाता है: प्रोजेक्ट फ़ाइल जाँचें, इसके लिए: design.sv। JSON परिणाम में शामिल हैं: tool: "module-counter" और modules: 1, जिन्हें वास्तविक चाइल्ड प्रक्रिया बनाती है। क्लाइंट कमांड में जोड़ें: --edit, केवल तब जब आप उदाहरण से नमूना फ़ाइल में टिप्पणी जुड़वाना चाहें।

अपना प्रोजेक्ट उपयोग करने के लिए इसकी निरपेक्ष डायरेक्टरी अंतिम आर्ग्यूमेंट के रूप में दें: server.mjs। सर्वर, प्लगइन मॉड्यूल और इंस्टॉल किए टूल उसी उपयोगकर्ता परिवेश में रखें। server.mjs प्लगइन स्पष्ट रूप से आयात करता है और उसके नामित बैकएंड को निश्चित निष्पादन योग्य फ़ाइल और आर्ग्यूमेंट से मैप करता है:

server.mjs बैकएंड मैपिंग

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

इस मैपिंग को अपने अनुमोदित इंस्टॉल किए टूल या कस्टम बैकएंड से बदलें। ctx.workspace.readFile और writeFile चुने हुए रूट के सापेक्ष पथ उपयोग करते हैं; ctx.backends.invoke("module-counter", input, {signal}) केवल कॉन्फ़िगर किया बैकएंड नाम बुलाता है। प्रक्रिया एडैप्टर stdin पर सीमित JSON भेजता है और stdout पर JSON चाहता है। यह अनुरोध से मिले शेल कमांड का उपयोग नहीं करता और होस्ट से कोई परिवेश वैरिएबल नहीं लेता।

रिमोट सर्वर के लिए अपना प्रमाणित HTTPS एंडपॉइंट या स्थानीय लूपबैक पर समाप्त होने वाला निजी टनल उपयोग करें। अपने परिवेश में कंटेनर पोर्ट मैपिंग या TLS कॉन्फ़िगर करें। उदाहरण डिफ़ॉल्ट रूप से लूपबैक पर बाइंड होता है; इसका बाइंड पता बदलने से TLS नहीं जुड़ता। विश्वसनीय प्लगइन और टूल आपकी होस्ट प्रक्रिया के OS अधिकार से चलते हैं।

सर्वर कॉन्फ़िगरेशन, ओरिजिन, फ़ाइल संशोधन, रद्दीकरण और सीमित परिणाम के लिए देखें: उपयोगकर्ता कार्यक्षेत्र उदाहरण और कार्यक्षेत्र प्रोटोकॉल।

भाषा सुविधाएँ

SDK 0.7.0 पूर्णता, होवर, परिभाषा, संदर्भ और समतल दस्तावेज़ प्रतीक देता है। मैनिफ़ेस्ट v2 की क्षमताओं में प्रत्येक सुविधा घोषित करें, साथ में ये अनुमतियाँ: document.read और language.provide। होस्ट को दोनों अनुमतियाँ स्पष्ट रूप से देनी चाहिए। ऊपर बनाए प्रोजेक्ट में यह पूरा होवर उदाहरण इस नाम से सहेजें: language-demo.mjs:

language-demo.mjs

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

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

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

पहली कमांड प्रिंट करती है: A local LED signal.। बंडल किया दूसरा उदाहरण छोटी शिक्षण भाषा से पाँचों सुविधाएँ जाँचता है, इसमें उपयोग होता है: let name = value; उदाहरण का अपना प्रदाता यह शिक्षण भाषा लागू करता है।

सुविधा

अनुरोध इनपुट

परिणाम डेटा

completion

position

अधिकतम 500 {label, insertText, detail?, range?} आइटम

hover

position

{text, range?} या null

definition

position

अधिकतम 500 कार्यक्षेत्र सापेक्ष {path, range} स्थान

references

position, वैकल्पिक includeDeclaration

अधिकतम 500 कार्यक्षेत्र सापेक्ष {path, range} स्थान

document-symbols

{}

अधिकतम 500 समतल {name, kind, range, selectionRange, detail?} प्रतीक

स्थितियाँ शून्य से शुरू होने वाली पंक्तियाँ और UTF-16 ऑफ़सेट उपयोग करती हैं। पूर्णता में जोड़ा जाने वाला टेक्स्ट शाब्दिक है; होवर और विवरण स्ट्रिंग सादे टेक्स्ट हैं। किसी स्थान पर जाने से पहले होस्ट को लक्ष्य फ़ाइलें और रेंज जाँचनी चाहिए। परिणाम अनुरोध, प्रोजेक्ट/सत्र और दस्तावेज़ संस्करण की पहचान बनाए रखता है। स्नैपशॉट संपादन, रद्दीकरण, समय सीमा, पंजीकरण हटाने या डिस्पोज़ करने से लंबित अनुरोध समाप्त होते हैं और देर से आए परिणाम त्याग दिए जाते हैं।

ये API विश्वसनीय SDK होस्ट में काम करती हैं। स्वतंत्र होस्ट पंजीकृत भाषा प्रदाताओं को बुलाता है; LSP ब्रिज स्पष्ट प्रक्रिया कॉन्फ़िगरेशन उपयोग करता है। 0.3.0 से पुराने होस्ट नई क्षमताएँ अस्वीकार करते हैं। चयनकर्ता, सीमाएँ और जीवनचक्र व्यवहार के लिए पढ़ें: भाषा सुविधाएँ।

प्रोजेक्ट संपादन सत्र

आयात करें: createWorkspaceProject और applyTextEdits, इस मॉड्यूल से: @altifigence/dds-plugin-sdk/workspace-client। होस्ट के जुड़ जाने के बाद: createWorkspaceClient, और कार्यक्षेत्र पहचान, सूचना और एक्सेस की समीक्षा के बाद, कॉल करें: createWorkspaceProject(client)। प्रोजेक्ट सटीक कनेक्शन बाइंडिंग बनाए रखता है। फिर जुड़ने के लिए नए सिरे से समीक्षा किया प्रोजेक्ट चाहिए, भले ही वही कार्यक्षेत्र ID और जेनरेशन लौटें।

API

व्यवहार

project.listFiles(path?, options?)

चुने कार्यक्षेत्र रूट के अंतर्गत एक डायरेक्टरी सूचीबद्ध करें।

project.openFile(path, options?)

फ़ाइल पढ़ें और संपादन सत्र में उसकी अपरिवर्तनीय सामग्री तथा संशोधन रखें।

project.createFile(path, content, options?)

केवल फ़ाइल अनुपस्थित होने पर बनाएँ, फिर सत्र लौटाएँ।

session.snapshot / session.state

अंतिम पुष्ट मान पढ़ें: {path, content, revision}, और मौजूदा कार्रवाई की स्थिति।

session.save(content, options?)

केवल तभी सहेजें जब सर्वर संशोधन अभी भी रखे गए संशोधन से मेल खाता हो।

session.saveEdits(edits, options?)

एक स्नैपशॉट पर लागू करें: {range, text} संपादन, फिर संशोधन जाँच वाला एक सहेजना करें।

session.reload(options?)

संघर्ष या अनिश्चित लेखन के बाद नवीनतम सामग्री और संशोधन स्पष्ट रूप से पढ़ें।

project.dispose() / session.dispose()

स्वामित्व वाला काम रद्द करें; प्रोजेक्ट डिस्पोज़ करने पर कॉलर के स्वामित्व वाला क्लाइंट जुड़ा रहता है।

इंस्टॉल किए पैकेज में पूरा HTTP उदाहरण चलाएँ। यह अपना अस्थायी नमूना कार्यक्षेत्र बनाता है, संपादन, संघर्ष वाले दूसरे सत्र, स्पष्ट रीलोड, Unicode और पुनः कनेक्शन जाँचता है, फिर सर्वर बंद करता है और अस्थायी डायरेक्टरी हटाता है:

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

अपेक्षित आउटपुट: Project session: HTTP edit, conflict, reload, Unicode and reconnect verified। यह उदाहरण स्रोत पूरा सर्वर/क्लाइंट सेटअप और सफ़ाई दिखाता है।

विकल्प स्वीकार करते हैं: signal और timeoutMs। प्रयास के बाद विफल लेखन यह छोड़ता है: needs-reload; बिना सहेजे UI ड्राफ़्ट अलग रखें और दोबारा सहेजने से पहले स्पष्ट रूप से रीलोड करें। SDK अपने आप मर्ज या पुनः प्रयास नहीं करता। सर्वर द्वारा लेखन कमिट करने के बाद समय सीमा, रद्दीकरण या प्रतिक्रिया खोना हो सकता है; अनुरोध रद्द करने पर कमिट किए बदलाव बने रहते हैं। हर सत्र में एक लंबित सहेजना या रीलोड अनुमत है।

टेक्स्ट संपादन मूल स्नैपशॉट, शून्य से शुरू पंक्तियाँ और UTF-16 ऑफ़सेट उपयोग करते हैं। ओवरलैप, विभाजित सरोगेट जोड़े और अमान्य रेंज सहेजने से पहले अस्वीकार होते हैं। प्रोजेक्ट में अधिकतम 64 खुले या खुल रहे सत्र और प्रति सहेजना 500 संपादन अनुमत हैं। ये हेल्पर अपरिवर्तित कार्यक्षेत्र प्रोटोकॉल v1 उपयोग करते हैं, SDK 0.2.x सर्वर सहित, और रूट, सुरक्षित पथ तथा केवल पढ़ने की पाबंदियाँ बनाए रखते हैं। पढ़ें: कार्यक्षेत्र प्रोजेक्ट, जीवनचक्र और आकार सीमाओं के लिए।

API संदर्भ

प्लगइन API यहाँ से आयात करें: @altifigence/dds-plugin-sdk। पैकेज में इन्हीं एक्सपोर्ट की TypeScript घोषणाएँ हैं।

API

उपयोग

definePlugin(manifest, activate)

मैनिफ़ेस्ट सत्यापित करें और सक्रियण फ़ंक्शन घोषित करें।

context.registerDiagnosticsProvider(selector, provider)

पंजीकृत करें: provideDiagnostics(request, {signal}), चुनी भाषा ID के लिए; डिस्पोज़ करने योग्य पंजीकरण लौटाएँ।

createDiagnosticsResult(request, diagnostics)

अनुरोध पहचान से सत्यापित परिणाम बनाएँ।

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

भाषा प्रदाता पंजीकृत करें और सत्यापित अनुरोध पहचान वाला परिणाम बनाएँ।

parseManifest(value)

मैनिफ़ेस्ट संस्करण, पहचान, अनुमतियाँ, समर्थित होस्ट और प्रवेश मॉड्यूल सत्यापित करें।

parseDocumentSnapshot(value)

URI, भाषा, मॉडल संस्करण, कार्यक्षेत्र संशोधन और टेक्स्ट सत्यापित करें।

parseDiagnosticsRequest(value) / parseDiagnosticsResult(value)

प्रोटोकॉल, अनुरोध, दायरा, दस्तावेज़ पहचान और निदान फ़ील्ड सत्यापित करें।

PluginSdkError / ErrorCode / LIMITS / PROTOCOL_VERSION

टाइपयुक्त त्रुटियाँ, संसाधन सीमाएँ और प्रोटोकॉल संस्करण पढ़ें।

डेवलपर होस्ट यहाँ से आयात करें: @altifigence/dds-plugin-sdk/testing:

परीक्षण होस्ट API

उपयोग

createTestHost({scope, grants})

स्थानीय होस्ट बनाएँ। दोनों विकल्प वैकल्पिक हैं; डिफ़ॉल्ट अनुमतियाँ दस्तावेज़ पढ़ना और निदान देना अनुमत करती हैं।

await host.activate(plugin)

प्लगइन सक्रिय करें और डिस्पोज़ करने योग्य सक्रियण लौटाएँ।

host.setDocument(snapshot)

मौजूदा दस्तावेज़ सेट करें। बढ़ाएँ: modelVersion, या बदलें: workspaceRevision, जब उसका टेक्स्ट बदलें।

await host.requestDiagnostics({signal, timeoutMs})

मेल खाते प्रदाता से निदान माँगें; दोनों विकल्प वैकल्पिक हैं।

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

स्पष्ट document.read और language.provide अनुमतियों के साथ घोषित भाषा सुविधा माँगें।

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

पंजीकरण हटाएँ और लंबित काम रद्द करें; परीक्षण समाप्त होने पर होस्ट डिस्पोज़ करें।

अनुरोध में शामिल हैं: requestId, प्रोजेक्ट/सत्र scope और यह वाला स्नैपशॉट: uri, languageId, modelVersion, workspaceRevision और text। इस पहचान को बनाए रखने के लिए उपयोग करें: createDiagnosticsResult। परिणाम में यह ऐरे होता है: diagnostics, और स्रोत टेक्स्ट नहीं होता।

त्रुटियाँ यह प्रकट करती हैं: code, इनमें शामिल हैं: invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable और budget_exceeded। अनुरोध की डिफ़ॉल्ट समय सीमा 5 सेकंड है; स्वीकार्य समय सीमाएँ 1–30,000 ms हैं। दस्तावेज़ अधिकतम 262,144 UTF-8 बाइट और परिणाम अधिकतम 500 निदान तक सीमित है। पढ़ें: LIMITS, सभी सीमाओं के लिए।

SDK 1.0.0 अलग मॉड्यूल भी देता है। केवल Node वाले कार्यक्षेत्र और पैकेजिंग आयात उपयोगकर्ता परिवेश में होने चाहिए:

आयात

API

@altifigence/dds-plugin-sdk

createPluginHost — v2 कमांड, स्पष्ट कार्यक्षेत्र/बैकएंड पोर्ट

@altifigence/dds-plugin-sdk/themes

parseTheme, serializeThemeXml

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

createNodeWorkspace, createProcessBackend, createWorkspaceServer, downloadJobBinaryArtifact, downloadStoredJobArtifact

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

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

@altifigence/dds-plugin-sdk/publishing

validatePluginPackage, packPlugin

@altifigence/dds-plugin-sdk/consent

createNotice, createPermissionGrant, isPermissionGranted, revokeConsentReceipt

@altifigence/dds-plugin-sdk/devtools

initPlugin, doctorPlugin, runPluginDev

@altifigence/dds-plugin-sdk/jobs

JOB_LIMITS, parseJobSnapshot, parseJobEvents, जॉब प्रकार

@altifigence/dds-plugin-sdk/artifacts

BINARY_ARTIFACT_LIMITS, parseBinaryArtifactReference, parseBinaryArtifactChunk, decodeBinaryArtifactData

/job-storage / /job-storage-node

createNodeJobStore, टिकाऊ जॉब प्रकार

/job-history

parseJobHistoryQuery, parseJobHistoryPage, पुनः प्रयास संबंध

/artifact-storage / /artifact-storage-node

createNodeArtifactStore, संग्रहित परिणाम प्रकार

अपना प्लगइन पैक करें और प्रकाशित करें

शामिल किए गए इस उदाहरण से शुरू करें: प्रकाशन योग्य प्लगइन। इसकी फ़ाइलों को नई डायरेक्टरी में कॉपी करने के लिए अपने SDK प्रोजेक्ट में यह हेल्पर सहेजें: my-plugin।

copy-publishable-example.mjs

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

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

संपादित करें: plugin.json, plugin.mjs, disclosure.json और लाइसेंस, अपने प्लगइन का वर्णन करने के लिए। प्रकटीकरण को मैनिफ़ेस्ट के प्रकाशक, प्लगइन ID, संस्करण, लाइसेंस और स्रोत दृश्यता से मेल खाना चाहिए। केवल वितरण के लिए चुनी फ़ाइलें यहाँ सूचीबद्ध करें: dds-package.json:

dds-package.json

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

उदाहरण सत्यापित करें और पैक करें:

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

अपरिवर्तित उदाहरण मेटाडेटा के साथ, pack बनाता है: dist/example-hello-publisher-1.0.0.tgz और dist/example-hello-publisher-1.0.0.tgz.release.json। रिलीज़ JSON में अंतिम आर्काइव SHA-256, मैनिफ़ेस्ट/प्रकटीकरण हैश और फ़ाइल सूची होती है। वितरण से पहले इन फ़ाइलों का निरीक्षण करें।

केवल अनुमत सूची की फ़ाइलें, dds-package.json और जनरेट किया npm मेटाडेटा आर्काइव में जाते हैं। सत्यापन पैकेज डेटा जाँचता है और पैकिंग चुने वितरण चैनल के लिए स्थानीय आर्काइव बनाती है। CLI निजी कॉन्फ़िगरेशन, कुंजी फ़ाइलें और लिंक किए पथ अस्वीकार करता है; साझा करने से पहले चुनी फ़ाइलों की सामग्री की समीक्षा करें।

चैनल

क्या देना है

सार्वजनिक GitHub रिलीज़

संस्करण वाला आर्काइव, उसका बाहरी रिलीज़ JSON, लाइसेंस और आवश्यक स्रोत एक्सेस।

निजी रजिस्ट्री या डाउनलोड चैनल

वही संस्करण वाली फ़ाइलें, पाठकों का प्राधिकरण और वास्तविक प्लगइन शर्तें।

मैनिफ़ेस्ट v2 घोषित करता है: runtime, अनुरोधित अनुमतियाँ और source: {visibility, licenseFile, repository?}। दृश्यता सेट करें: open या closed, और वास्तविक लाइसेंस फ़ाइल शामिल करें। अपने स्वामित्व वाला कोड ओपन सोर्स या मालिकाना शर्तें उपयोग कर सकता है; लागू SDK और निर्भरता सूचनाएँ फिर भी लागू होती हैं। प्राप्तकर्ताओं को निष्पादन योग्य JavaScript के साथ घोषित स्रोत दृश्यता और लाइसेंस मेटाडेटा मिलता है।

प्रकटीकरण फ़ील्ड और वितरण आवश्यकताओं के लिए पढ़ें: प्रकाशन और लाइसेंसिंग। बना आर्काइव और रिलीज़ JSON अपने चुने GitHub रिलीज़, निजी रजिस्ट्री या डाउनलोड चैनल से वितरित करें।

1.2.1 CLI नए प्लगइन पैकेज में >=1.0.0 <2.0.0 दर्ज करता है। पुराने 0.3–0.13 और सटीक 1.0.0-rc.1 आर्काइव अपने मूल पीयर बनाए रखते हैं। स्थिर इंस्टॉलेशन के लिए नया प्लगइन संस्करण सत्यापित करें और फिर पैक करें; प्रकाशक फिर पैक करते समय घोषित पीयर रेंज और रिलीज़ मेटाडेटा स्पष्ट रूप से अपडेट करता है।

डाउनलोड किए प्लगइन को सत्यापित करें

SDK 1.2.1 सटीक जारी किए 0.3.x–0.13.x, RC1 और मौजूदा स्थिर प्लगइन मेटाडेटा के लिए dds-plugin verify देता है। .tgz और .tgz.release.json साथ रखें। सत्यापन मूल पीयर बनाए रखता है। ऊपर बनाया पैकेज जाँचें:

पैक किया उदाहरण सत्यापित करें

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

कमांड सीमित gzip/tar संरचना, सटीक फ़ाइल अनुमति सूची, हर फ़ाइल का हैश, मैनिफ़ेस्ट, प्रकटीकरण, लाइसेंस और जनरेट किया npm मेटाडेटा जाँचती है। यह लिंक, असुरक्षित या दोहरे पथ, अतिरिक्त फ़ाइलें और npm हुक/निर्भरताएँ अस्वीकार करती है। यह स्थानीय आर्काइव को उसी स्थान पर डेटा के रूप में पढ़ती और सत्यापित करती है। सफलता पर JSON रसीद प्रिंट होती है; अस्वीकृति पर निकास कोड 1 होता है।

नाम बदले डाउनलोड के लिए उपयोग करें: --metadata, मेल खाते रिलीज़ JSON के साथ। अपेक्षित SHA-256 विश्वसनीय रिलीज़ चैनल से स्वतंत्र रूप से लें और इसके साथ दें: --sha256, चुनी हुई बाइट निश्चित करने के लिए। Node API में वही विकल्प हैं:

verify-release.mjs

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

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

चलाएँ: verify-release.mjs, इसके तीन आर्ग्यूमेंट के रूप में आर्काइव पथ, मेटाडेटा पथ और स्वतंत्र रूप से लिया गया 64 वर्ण का लोअरकेस हैश दें। checksumPinned केवल तब true होता है जब दिया हैश मेल खाए। सीमाएँ हैं: 12 MiB संपीड़ित इनपुट, 10 MiB फ़ाइल सामग्री, प्रति फ़ाइल 4 MiB, 256 फ़ाइलें और 256 KiB बाहरी मेटाडेटा।

साथ का मेटाडेटा मेल खाते हैश से आर्काइव की अखंडता दर्ज करता है। दोनों फ़ाइलें बदलने पर नया मेल खाता जोड़ा बन सकता है, इसलिए अपेक्षित डाइजेस्ट स्वतंत्र रूप से विश्वसनीय रिलीज़ चैनल से लें। प्रकाशक और निष्पादन सामग्री की समीक्षा, स्पष्ट होस्ट अनुमतियाँ और लक्ष्य इंस्टॉलेशन का सत्यापन अलग चरणों में करें। रसीद उस कॉल में पढ़ी बाइट का वर्णन करती है; उपयोग से पहले फ़ाइल बदल सकती हो तो वास्तविक बाइट फिर जाँचें। मौजूदा 0.3.x/0.4.x/0.5.x/0.6.x/0.7.x/0.8.x/0.9.x/0.10.x/0.11.x प्लगइन आर्काइव मज़बूत फ़ाइल नीति पूरी करने पर सत्यापित किए जा सकते हैं; उन्हें 1.0 पर इंस्टॉल करने के लिए फिर भी प्रकाशक सत्यापन और पुनः पैकिंग चाहिए। ज़रूरत हो तो अब वर्जित फ़ाइलें हटाएँ और नया प्लगइन संस्करण प्रकाशित करें। यह सत्यापक DDS प्लगइन पैकेज के लिए है; SDK npm tarball अपने रिलीज़ SHA-256 उपयोग करते हैं।

देखें: आर्काइव सत्यापन और पूरा पैकेज/सत्यापन/छेड़छाड़ उदाहरण.

अनुमतियाँ, लाइसेंस और डेटा उपयोग

मैनिफ़ेस्ट में अनुरोधित अनुमतियाँ कार्रवाइयाँ सक्षम करने वाली होस्ट अनुमतियों से अलग हैं। सक्षम करने से पहले उपयोगकर्ता को प्लगइन पहचान, संस्करण, वास्तविक लाइसेंस, कार्यक्षेत्र दायरा और अनुरोधित अनुमतियाँ दें। किसी बैकएंड को जोड़ने से पहले उसके ऑपरेटर, भेजे डेटा, उद्देश्य, प्रतिधारण और गोपनीयता सूचना का वर्णन करें।

रिकॉर्ड

अर्थ

pluginPermissionGrant

सटीक पैकेज, कार्यक्षेत्र और अनुमतियों के लिए होस्ट एक्सेस निर्णय।

noticeAcknowledgement

उपयोगकर्ता ने सूचना पढ़ने की पुष्टि की।

pluginLicenseAcceptance

उपयोगकर्ता ने प्लगइन प्रकाशक की वास्तविक शर्तें स्वीकार करने या न करने का चयन किया।

optionalPersonalDataConsent

जब वैकल्पिक प्रोसेसिंग का आधार सहमति हो, तब अलग चयन।

SDK कार्यक्षेत्र अनुमोदन तकनीकी एक्सेस निर्णय है। प्लगइन शर्तों की स्वीकृति और वैकल्पिक व्यक्तिगत डेटा सहमति उनके अपने चयन और रिकॉर्ड प्रकार में दर्ज करें। SDK का उपयोग उसके Apache-2.0 लाइसेंस और सूचनाओं के अनुसार करें।

होस्ट डेवलपर पोर्टेबल एसिंक्रोनस हेल्पर से संस्करण वाली सूचना सुरक्षित रख सकते हैं। उदाहरण के लिए इसे इस नाम से सहेजें: notice.mjs और चलाएँ: node notice.mjs:

notice.mjs

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

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

createPermissionGrant अनुरोधित अनुमतियों के उपसमुच्चय को मैनिफ़ेस्ट v2, आर्टिफ़ैक्ट और मैनिफ़ेस्ट हैश, कार्यक्षेत्र जेनरेशन, होस्ट पहचान, सूचना और समाप्ति से बाँधता है। isPermissionGranted होस्ट द्वारा दी गई मौजूदा पहचान और निरस्तीकरण घटनाओं का मूल्यांकन करता है। revokeConsentReceipt अलग घटना बनाता है; इसके बाद होस्ट को भविष्य की अधिकृत कॉल रोकनी चाहिए।

ये हेल्पर स्थानीय रिकॉर्ड सत्यापित करते हैं। वास्तविक उपयोगकर्ता चयन, पहचान, संग्रहण और प्रवर्तन होस्ट देता है। सटीक फ़ील्ड के लिए पढ़ें: अनुमतियाँ और सहमति और स्पष्ट अनुमति/अस्वीकृति/निरस्तीकरण प्रदर्शन के लिए: इंटरैक्टिव अनुमति उदाहरण। होस्ट प्रकाशक की शर्तें और उनकी स्वीकृति के रिकॉर्ड सँभालता है।

स्रोत, रिलीज़ और योगदान

यह आधिकारिक SDK रिपॉज़िटरी स्रोत, स्कीमा, उदाहरण और अनुबंध परीक्षण रखती है। जारी किए उदाहरण और SDK परीक्षण स्रोत से चलाने के लिए:

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

SDK बग की रिपोर्ट करें: GitHub Issues पर, SDK संस्करण और न्यूनतम पुनरुत्पादन के साथ। SDK Apache-2.0 के तहत लाइसेंस प्राप्त है; रिपॉज़िटरी का लाइसेंस और सूचनाएँ देखें। संस्करण वाले आर्काइव और रिलीज़ नोट के लिए देखें: रिलीज़ पृष्ठ।

यह रिपॉज़िटरी जानबूझकर सार्वजनिक डेवलपर SDK है। इसकी रिलीज़ की घोषित SDK फ़ाइलें, स्कीमा, उदाहरण और सूचनाएँ इस विवरण के अनुसार हैं: सार्वजनिक दायरा। पैकेज जाँचें सटीक प्रकाशित फ़ाइल सूची लागू करती हैं और ज्ञात सीक्रेट तथा निजी पथ पैटर्न अस्वीकार करती हैं। इन पैटर्न जाँचों के साथ वास्तविक रिलीज़ सामग्री की भी समीक्षा करें।

सुरक्षा अपडेट और होस्ट सीमाएँ

अपने कार्यक्षेत्र सर्वर और SDK क्लाइंट दोनों को अपडेट करें: 0.3.2 या बाद के संस्करण पर। बेहतर फ़ाइल जाँच और अनुरोध सीमाएँ सक्रिय करने के लिए सर्वर अपडेट स्थापित करें। अपग्रेड किया होस्ट पुनः शुरू करें, नई जेनरेशन की समीक्षा करें और कार्यक्षेत्र उपयोग से पहले फिर अनुमोदन लें।

Node कार्यक्षेत्र होस्ट ऐसे हार्डलिंक अस्वीकार करता है जो सुरक्षित फ़ाइल या चुने रूट के बाहर की फ़ाइल के उपनाम हो सकते हैं। जानबूझकर साझा प्रोजेक्ट फ़ाइल को नियमित, एक लिंक वाली फ़ाइल में कॉपी करें। क्रेडेंशियल स्टोर जैसे .netrc, _netrc, .git-credentials, .gnupg, .kube और .docker, अतिरिक्त SSH कुंजी नाम और Windows डिवाइस उपनाम भी अवरुद्ध हैं। पैकेजिंग और डाउनलोड सत्यापन संबंधित क्रेडेंशियल नाम नीति लागू करते हैं।

सर्वर संसाधन

सीमा

एक साथ आने वाली बॉडी

16; अतिरिक्त अपलोड को डिस्पैच से पहले HTTP 429 मिलता है

निष्पादित अनुरोध

64; रद्दीकरण अलग डिस्पैच पथ उपयोग करता है

प्रति सॉकेट कनेक्शन / अनुरोध

128 / 128

अनुरोध और जवाब / फ़ाइल सामग्री

1,600,000 / 262,144 UTF-8 बाइट

क्लाइंट समय सीमा या रद्दीकरण पर बिना पढ़ी अस्वीकार प्रतिक्रियाएँ और रुकी स्ट्रीम रद्द करता है। लेखन शुरू होने के बाद समय सीमा आने से परिणाम अनिश्चित रह सकता है: पुनः प्रयास से पहले फ़ाइल फिर पढ़ें। स्पष्ट पथ निषेध के साथ फ़ाइल सामग्री की भी समीक्षा करें और विश्वसनीय प्लगइन कोड चलाते समय होस्ट प्रक्रिया के ऑपरेटिंग सिस्टम अधिकार ध्यान में रखें। होस्ट परिनियोजन के समय उपयोग करें: सुरक्षा अपग्रेड मार्गदर्शिका और कार्यक्षेत्र सीमाएँ।

विकास टूल

ऊपर SDK 1.2.1 स्थापित करने के बाद, एक अलग कमांड-प्लगइन प्रोजेक्ट बनाएँ। जनरेट फ़ाइलों के लिए नया गंतव्य चुनें; ढाँचा बनने के बाद निर्भरता स्थापना और प्लगइन निष्पादन स्पष्ट रूप से करें। मचान में एक कमांड, परीक्षण, घोषणापत्र, प्रकटीकरण, पिन की गई SDK निर्भरता और Apache-2.0 LICENSE/NOTICE शामिल हैं।

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

Doctor मेटाडेटा पढ़ता है और प्लगइन आयात किए बिना Node, SDK रिज़ॉल्यूशन, मैनिफ़ेस्ट, लाइसेंस, प्रकटीकरण और अनुमति सूची की पैकेज फ़ाइलें जाँचता है। त्रुटियाँ निकास स्थिति 1 देती हैं; उदाहरण प्रकाशक/समर्थन मान चेतावनियाँ हैं। वितरण से पहले ये मान बदलें और लाइसेंस की समीक्षा करें।

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

Dev के लिए --trust-local-code आवश्यक है। यह चाइल्ड में विश्वसनीय स्थानीय आयात/सक्रियण चलाता है और केवल अनुमति सूची की फ़ाइलों तथा dds-package.json पर नज़र रखता है। हर रन की समय सीमा और stdout/stderr की 256 KiB सीमा है। Ctrl+C निरीक्षण रोकता है और प्रक्रिया ट्री साफ़ करता है। चाइल्ड आपके ऑपरेटिंग सिस्टम अधिकार और प्राप्त परिवेश के साथ चलता है। डिफ़ॉल्ट परीक्षण होस्ट दस्तावेज़ पढ़ना और निदान देता है; कार्यक्षेत्र/बैकएंड एकीकरण के लिए अलग होस्ट और स्पष्ट अनुमतियाँ कॉन्फ़िगर करें।

जॉब प्रगति/लॉग प्रिंट करने के लिए --job उपयोग करें; सामान्य कमांड के लिए अधिकतम 30 सेकंड या जॉब के लिए 30 मिनट सेट करने हेतु --timeout-ms उपयोग करें। Node API /devtools में initPlugin, doctorPlugin और runPluginDev हैं। निरीक्षण व्यवहार और संसाधन सफ़ाई के लिए देखें: विकास टूल मार्गदर्शिका।

लंबे समय चलने वाली कमांड जॉब

सामान्य अनुरोध समय सीमा से अधिक चलने वाली कमांड के लिए 0.4.0 SDK होस्ट/सर्वर पर jobs: true सक्षम करें। जॉब डिफ़ॉल्ट रूप से अक्षम हैं। पूरा स्थानीय HTTP उदाहरण आज़माएँ, जो प्रगति, नामित बैकएंड लॉग और हैश से निश्चित परिणाम फ़ाइल बताता है:

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

अपेक्षित आउटपुट: Command job: progress, backend log and pinned result file verified. कमांड हैंडलर को {signal, job} में वैकल्पिक job मिलता है। यह reportProgress, log, addArtifact और invokeBackend देता है। मौजूदा workspace.read/write और backend.invoke अनुमतियाँ अभी भी लागू हैं; कोई मनमाना निष्पादन योग्य पथ स्वीकार नहीं होता।

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

पोलिंग स्निपेट जुड़े क्लाइंट और report पंजीकृत करने वाली कॉन्फ़िगर analyze कमांड मानकर चलता है। शुरू करने से पहले जॉब ID रखें। कनेक्शन हटाने या पोलिंग अनुरोध रोकने से निष्पादन रद्द नहीं होता; उसी जेनरेशन से फिर जुड़ें और स्पष्ट रूप से पूछें/रद्द करें। उसी ID और इनपुट से पुनः शुरू करने पर रखा जॉब उपयोग होता है; बदले आर्ग्यूमेंट संघर्ष करते हैं। होस्ट पुनः शुरू होने पर मेमोरी रिकॉर्ड खोते हैं। पुनः शुरू होने के बाद कमिट मेटाडेटा पाने के लिए नीचे अलग 0.8 टिकाऊ स्टोर सक्षम करें।

स्थितियाँ running, succeeded, failed, cancelled और timed_out हैं। रद्दीकरण के बाद देर का आउटपुट त्यागा जाता है; दुष्प्रभाव वापस नहीं होते। असमाप्त प्रदाता अपनी जगह बनाए रखते हैं। अधिकतम 4 एक साथ जॉब, 32 रखे रिकॉर्ड, प्रति जॉब 32 नेस्टेड कार्रवाइयाँ, प्रति जॉब 256 घटनाएँ/64 KiB, प्रति पृष्ठ 64 घटनाएँ और 16 आर्टिफ़ैक्ट हैं। रनटाइम का डिफ़ॉल्ट 5 मिनट और अधिकतम 30 मिनट है। समाप्त अंतिम रिकॉर्ड अपनी आखिरी घटना के 15 मिनट बाद समाप्त होते हैं।

टेक्स्ट परिणाम फ़ाइलें कार्यक्षेत्र के सापेक्ष UTF-8 हैं, अधिकतम 256 KiB। होस्ट मौजूदा अनुमति से पढ़ता है, SHA-256 दर्ज करता है और बाद में बाइट बदलने पर पढ़ना अस्वीकार करता है। बाइनरी या बड़े सिमुलेशन आउटपुट के लिए वैकल्पिक API उपयोग करें: बाइनरी परिणाम API। रद्दीकरण के बाद आंशिक आर्टिफ़ैक्ट रह सकते हैं; सफलता के लिए जॉब की अंतिम स्थिति देखें। पुराने 0.3 क्लाइंट मौजूदा v1 विधियाँ उपयोग करते हैं; स्वतंत्र SDK जॉब के क्लाइंट और होस्ट दोनों में 0.4 या बाद का संस्करण उपयोग करें। सटीक अनुबंध और सीमाओं के लिए देखें: जॉब।

कार्यक्षेत्र फ़ाइलों का निरीक्षण करें

project.watchFiles() 1–16 स्पष्ट सापेक्ष फ़ाइल पथों के नमूने लेता है। SDK 1.0.0 समर्थित होस्ट पर केवल संशोधन अनुरोध और पुराने होस्ट पर मौजूदा सीमित पढ़ना उपयोग करता है। उदाहरण जुड़ा, होस्ट अनुमोदित क्लाइंट मानता है। लूप समाप्त करने के लिए बाहरी एडिटर से design.sv बदलें; रखा संपादन स्नैपशॉट अपरिवर्तित रहता है।

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

घटनाएँ अपरिवर्तनीय {kind, path, previousRevision, revision} हैं। पहला नमूना initial देता है; बाद के बदलाव created, changed या deleted देते हैं। अनुपस्थित फ़ाइल का revision null है। includeInitial: false आधार चुपचाप दर्ज करता है और समान संशोधन कोई घटना नहीं देते। केवल not_found का अर्थ हटाना है; अनुमति, सुरक्षित पथ, आकार और ट्रांसपोर्ट त्रुटियाँ निरीक्षण समाप्त करती हैं।

बिना सहेजा UI टेक्स्ट अलग रखें। निरीक्षण ड्राफ़्ट और संपादन स्नैपशॉट सुरक्षित रखता है। कॉलर रीलोड, मर्ज या सेव स्पष्ट रूप से चुनता है और सेव के समय रखे संशोधन से संघर्ष की जाँच होती है। पथ क्रम से एक एक करके पढ़े जाते हैं; यह नमूना आधारित निरीक्षण है, इसलिए बीच के बदलाव एक साथ मिल सकते हैं। नमूना लेने के लिए सटीक फ़ाइल पथ चुनें; हर घटना देखे गए पथ और संशोधन का वर्णन करती है। मौजूदा रूट, फ़ाइल आकार और सुरक्षित पथ पाबंदियाँ केवल पढ़ने और लिखने योग्य सर्वर दोनों पर लागू हैं।

फ़ाइल और जॉब निरीक्षक अपनी पहली next() पर शुरू होते हैं, उपभोक्ता रुका हो तो पृष्ठ पृष्ठभूमि में नहीं लाते और प्रति क्लाइंट अधिकतम आठ सक्रिय निरीक्षकों की सीमा साझा करते हैं। एक next() लंबित हो सकती है; साथ में पढ़ना conflict से विफल होता है। break या return() लंबित पढ़ना रोकता है; प्रोजेक्ट डिस्पोज़ करने पर उसके फ़ाइल निरीक्षक रुकते हैं और कनेक्शन हटाना/फिर जोड़ना/डिस्पोज़ करना सभी पुराने निरीक्षक अमान्य करता है। AbortSignal cancelled के साथ निरीक्षण समाप्त करता है; देर के जवाब परिणाम नहीं दे सकते।

intervalMs 250–60,000 ms है (डिफ़ॉल्ट 1,000), जो फ़ाइल चक्रों या निष्क्रिय जॉब पढ़ने के बीच लागू होता है। requestTimeoutMs प्रति अनुरोध 1–30,000 ms है और डिफ़ॉल्ट क्लाइंट समय सीमा है। कुल timeoutMs पहली next() से 1–1,800,000 ms है, जिसमें उपभोक्ता विराम शामिल हैं। फ़ाइलों की डिफ़ॉल्ट कुल समय सीमा नहीं; जॉब की 30 मिनट है। समय सीमा budget_exceeded देती है और जगह मुक्त करती है। ये सीमाएँ WORKSPACE_OBSERVATION_LIMITS में एक्सपोर्ट हैं।

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

अपेक्षित आउटपुट: Workspace observation: file changes, retained draft and resumed job verified. पूरा उदाहरण अपना अस्थायी कार्यक्षेत्र बनाता है और फ़ाइल बदलाव, ड्राफ़्ट संघर्ष तथा स्पष्ट जॉब पुनः आरंभ जाँचता है। सभी विकल्प और जीवनकाल नियम के लिए देखें: निरीक्षण।

जॉब का निरीक्षण और पुनः आरंभ करें

client.watchJob() jobs.events/get से मौजूदा जॉब का अनुसरण करता है; waitForJob() अंतिम स्नैपशॉट लौटाता है। स्निपेट जुड़ा क्लाइंट, स्पष्ट रूप से शुरू किया jobId और savedCursor (या undefined) मानता है। जॉब शुरू करने से पहले getJobCapabilities() जाँचें। निरीक्षण कभी कमांड शुरू नहीं करता, पुनः प्रयास नहीं करता और रद्द नहीं करता।

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

हर फ़्रीज़ अपडेट में snapshot, events, after, nextCursor, dropped और hasMore हैं। प्रति पृष्ठ अधिकतम 64 घटनाएँ संभालें और प्रोसेसिंग के बाद nextCursor, जॉब ID और कार्यक्षेत्र पहचान दर्ज करें। dropped समाप्त इतिहास बताता है। स्नैपशॉट अपनी घटना पृष्ठ से नया हो सकता है; hasMore true हो तो अंतिम स्नैपशॉट पढ़ते रहें। अंतिम पृष्ठ के बाद इटरेटर समाप्त होता है। waitForJob() वही पृष्ठ पढ़कर succeeded, failed, cancelled या timed_out लौटाता है; हर resolved promise को सफलता मानने के बजाय state जाँचें।

इटरेटर रोकने या समय सीमा आने से केवल निरीक्षण रुकता है। सर्वर कमांड पूरी होने या स्पष्ट cancelJob() बुलाने तक चलती है। होस्ट अनुमोदित पुनः कनेक्शन के बाद वही कार्यक्षेत्र ID और जेनरेशन सत्यापित करें, फिर सहेजी जॉब ID और कर्सर से नया निरीक्षक बनाएँ। पहचान अपरिवर्तित हो तब भी पुराने निरीक्षक अमान्य हैं। अनुपस्थित/समाप्त जॉब और ट्रांसपोर्ट विफलताएँ पुनः जमा किए बिना बताई जाती हैं; मेमोरी जॉब होस्ट पुनः शुरू होने पर नहीं बचतीं। टिकाऊ पुनर्प्राप्ति नए कनेक्शन से recoverJob() उपयोग करती है; लाइव निरीक्षक जेनरेशन बदलने पर फिर नहीं चलते।

मौजूदा v1 hello और जॉब अनुबंध अपरिवर्तित हैं। फ़ाइल निरीक्षण 0.3.2/0.4/0.5 होस्ट पर फ़ॉलबैक उपयोग करता है; जॉब निरीक्षण के लिए सक्षम 0.4 या बाद का होस्ट चाहिए। निरीक्षण से पहले होस्ट की जॉब क्षमताएँ देखें। असमर्थित प्रतिक्रिया अनुरोध समाप्त करती है और कमांड निष्पादन पर स्पष्ट नियंत्रण बनाए रखती है। ये निरीक्षक स्वतंत्र SDK क्लाइंट और होस्ट से चलते हैं। देखें: निरीक्षण और संगतता.

फ़ाइल संशोधन और शर्त के अनुसार पढ़ना

SDK 0.6.0 जुड़े क्लाइंट में getFileCapabilities(), getFileRevision(path) और readFileIfChanged(path, knownRevision) जोड़ता है। संशोधन पढ़ना सामग्री बिना {path, revision} लौटाता है। मेल खाता सशर्त पढ़ना {path, revision, notModified: true} लौटाता है; बदली सामग्री notModified: false और content लौटाती है। मौजूदा सामग्री के लिए knownRevision: null दें। अनुपस्थित फ़ाइल not_found से अस्वीकार होती है।

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

पहले से जुड़ा, अधिकृत क्लाइंट उपयोग करें। बिना सहेजे ड्राफ़्ट इस कैश से अलग रखें। सशर्त पढ़ना एक फ़ाइल स्नैपशॉट हैश करके लौटाता है; बाद में पढ़ने पर नया बदलाव फिर दिख सकता है। लौटी सामग्री के संशोधन से सहेजें। ये कॉल संपादन सत्र स्नैपशॉट अपडेट या ड्राफ़्ट मर्ज नहीं करतीं। अपरिवर्तित जवाब में content फ़ील्ड नहीं होता; खाली बदली फ़ाइल में content: “”. होता है।

समर्थित होने पर फ़ाइल निरीक्षण अपने आप केवल संशोधन पढ़ना उपयोग करता है। वैकल्पिक fs.capabilities, fs.revision और fs.readIfChanged विधियाँ सख्त v1 hello और मूल फ़ाइल विधियाँ बनाए रखती हैं। ज्ञात 0.6 से पुराने SDK कार्यक्षेत्र होस्ट बिना प्रोबिंग fs.read उपयोग करते हैं। दूसरे होस्ट खोज का जवाब दें या सही सहसंबद्ध unsupported त्रुटि लौटाएँ। हर false क्षमता अपना सीमित पूरा पढ़ने का फ़ॉलबैक चुनती है; पुराने सर्वर की प्रतिक्रिया में पूरी सामग्री फिर भी ट्रांसफ़र होती है।

क्षमताएँ केवल मौजूदा कनेक्शन के लिए कैश होती हैं और पुनः कनेक्शन या निरस्तीकरण पर रीसेट होती हैं। अमान्य जवाब, पथ/संशोधन बेमेल, अनुमतियाँ, प्रमाणीकरण, ट्रांसपोर्ट विफलता और समय सीमा फ़ॉलबैक शुरू नहीं करतीं। घोषित कार्रवाइयाँ बाद में विफल हों तो उन्हें चुपचाप कम स्तर पर नहीं बदला जाता। AbortSignal खोज और पढ़ना कवर करता है; timeoutMs हर HTTP अनुरोध पर लागू है। कनेक्शन बदलना पुरानी कार्रवाई अमान्य करता है।

सर्वर हर नमूने पर अभी भी सुरक्षित पूरा फ़ाइल पढ़ना और SHA-256 गणना करता है। UTF-8 सत्यापन, 262,144 बाइट सीमा और सुरक्षित पथ/लिंक जाँच लागू रहती हैं। इससे नेटवर्क प्रतिक्रिया बाइट घटती हैं और हर नमूने पर सुरक्षित डिस्क पढ़ना तथा SHA-256 गणना बनी रहती है। स्थानीय Node 22.23.1 Windows माप में 200,000 बाइट के 20 अपरिवर्तित नमूनों ने पूरे पढ़ने में 4,003,974 बाइट, संशोधन में 3,867 (99.903% कम) और सशर्त पढ़ने में 4,247 (99.894% कम) लौटाए। खोज शामिल है; HTTP हेडर, TLS और शुरुआती hello/सामग्री आधार शामिल नहीं हैं। फ़िक्स्चर दोहराने के लिए चेकआउट में npm run benchmark:files चलाएँ।

SDK स्थिर 1.x API देता है। मौजूदा 0.3.2, 0.4, 0.5 और 0.6 क्लाइंट 0.7 होस्ट पर अपने मूल API रखते हैं। इन संशोधन API का उपयोग जुड़े स्वतंत्र SDK क्लाइंट से करें। पूरे अनुबंध और माइग्रेशन नियमों के लिए देखें: फ़ाइल संशोधन।

बड़े और बाइनरी जॉब परिणाम

SDK 0.7.0 वैकल्पिक बाइनरी परिणाम फ़ाइल एक्सटेंशन जोड़ता है। विश्वसनीय कमांड मौजूदा कार्यक्षेत्र फ़ाइल पंजीकृत करती है; होस्ट SHA-256 और लंबाई दर्ज करता है। क्लाइंट प्रति खंड अधिकतम 64 KiB पढ़ता है और Node डाउनलोडर आंशिक फ़ाइल फिर शुरू करके पूरा आउटपुट सत्यापित करता है। अधिकतम दर्ज फ़ाइल 1 GiB है; मौजूदा 256 KiB UTF-8 फ़ाइल और टेक्स्ट आर्टिफ़ैक्ट API अपनी सीमाएँ रखते हैं।

सर्वर के स्वामित्व वाले प्लगइन होस्ट पर jobs: true और binaryArtifacts: true सक्षम करें। दोनों का डिफ़ॉल्ट false है। स्पष्ट टोकन, ऑपरेटर सूचना, समीक्षा किया प्लगइन आर्टिफ़ैक्ट पिन और प्रभावी workspace.read अनुमति बनाए रखें। यह ऊपर के कार्यक्षेत्र सेटअप पर आधारित है; केवल पढ़ने वाले कार्यक्षेत्र ऑपरेटर के कॉन्फ़िगर टूल द्वारा पहले से बनी फ़ाइलें पंजीकृत कर सकते हैं।

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

startCommandJob से शुरू कमांड के अंदर परिणाम पंजीकृत करें। पंजीकरण 64 KiB बफ़र से मौजूदा फ़ाइल को SHA-256 में स्ट्रीम करता है। संदर्भ स्रोत फ़ाइल को इंगित करता है, अपरिवर्तनीय प्रति को नहीं। सुरक्षित पथ, ट्रैवर्सल, लिंक और गैर नियमित फ़ाइलें अस्वीकार होती हैं; बाद में स्रोत बदलाव conflict से विफल होते हैं।

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

पहले से जुड़ा, अधिकृत क्लाइंट और मौजूदा जॉब ID उपयोग करें। गंतव्य कॉलर के नियंत्रण वाली मौजूदा वास्तविक डायरेक्टरी का निरपेक्ष पथ है। हेल्पर destination + “.dds-part” लिखता है और मौजूदा अंतिम फ़ाइल पर लिखने से मना करता है।

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

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

पूरा {jobId, scope, artifact} संदर्भ रखें। बाधा के बाद उसी होस्ट जेनरेशन से स्पष्ट रूप से फिर जुड़ें और संदर्भ तथा resume: true के साथ हेल्पर फिर बुलाएँ। यह सहेजे प्रीफ़िक्स को फिर हैश करता है और केवल अनुपस्थित सफ़िक्स माँगता है। प्रकाशित करने से पहले हर खंड, पूरी प्राप्त स्ट्रीम और वास्तविक स्टेजिंग फ़ाइल का SHA-256 जाँचता है। अंतिम verified: true रसीद पूर्णता की पुष्टि करती है; सिंक्रोनस प्रगति कॉलबैक अभी असत्यापित हैं। दूषित आंशिक फ़ाइल स्पष्ट रूप से हटाएँ या नया गंतव्य चुनें।

listJobBinaryArtifacts(jobId) मौजूदा टेक्स्ट परिणाम से अलग दर्ज बाइनरी मेटाडेटा लौटाता है। readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) खंड SHA-256, सटीक रेंज और EOF चिह्न के साथ मानक base64 लौटाता है। /artifacts का decodeBinaryArtifactData Uint8Array बाइट लौटाता है। ब्राउज़र उपभोक्ता पूरे फ़ाइल हैश स्वयं सत्यापित करें; अलग खंड जाँच से संयुक्त आउटपुट का संदर्भ से मेल खाना प्रमाणित नहीं होता।

बाइनरी और टेक्स्ट परिणाम प्रति जॉब 16 जगह और ID नेमस्पेस साझा करते हैं। बाइनरी कैप्चर/पढ़ना प्रति होस्ट/कार्यक्षेत्र चार और Node डाउनलोड प्रति प्रक्रिया चार तक सीमित हैं। Node डाउनलोड का timeoutMs कुल समय सीमा है, डिफ़ॉल्ट अधिकतम 30 मिनट; requestTimeoutMs डिफ़ॉल्ट 5 सेकंड, अधिकतम 30 सेकंड है। प्रकाशन के लिए NTFS या ext4 जैसा हार्डलिंक समर्थन चाहिए। कॉलर के नियंत्रण वाली डायरेक्टरी और विश्वसनीय लेखक उपयोग करें; फ़ाइल सिस्टम जाँच होस्ट प्रक्रिया के ऑपरेटिंग सिस्टम अधिकारों से चलती है।

वैकल्पिक artifacts.capabilities, artifacts.list और artifacts.read मौजूदा v1 hello, जॉब स्नैपशॉट और घटनाएँ बनाए रखते हैं। 0.7 से पहले के होस्ट एक्सटेंशन अक्षम बताते हैं; क्लाइंट इस क्षमता परिणाम और पढ़ने तथा निष्पादन पर स्पष्ट नियंत्रण बनाए रखता है। प्रमाणीकरण, विकृत जवाब और ट्रांसपोर्ट त्रुटियाँ त्रुटि ही रहती हैं। पुनः कनेक्शन, निरस्तीकरण, जॉब समाप्ति या बदली होस्ट जेनरेशन पुराने ऑपरेशन अमान्य करती है। अंतिम जॉब की आखिरी घटना के बाद जॉब मेमोरी में 15 मिनट रहती है। रद्द जॉब दर्ज आंशिक टूल आउटपुट छोड़ सकती है; सफलता के लिए जॉब की अंतिम स्थिति देखें। यह डिफ़ॉल्ट लाइव/स्रोत API का वर्णन है। नीचे की अलग संग्रहित परिणाम API पुनः शुरू होने पर बाइट बनाए रखती है।

वास्तविक 2 MiB ट्रांसफ़र, बाधा, पुनः कनेक्शन और केवल सफ़िक्स पुनः आरंभ के लिए npm run example:artifacts चलाएँ; npm run benchmark:artifacts 8 MiB उपयोग करता है। स्थानीय Windows रन में 129 खंड अनुरोध से 8,388,625 बाइट ट्रांसफ़र हुए, 65,536 बाइट प्रीफ़िक्स से फिर शुरू किया गया और अंतिम SHA-256 सत्यापित हुआ। Base64 ओवरहेड जोड़ता है; JSON प्रतिक्रिया बॉडी कुल 11,257,419 बाइट थीं। ट्रांसफ़र मेमोरी उपयोग सीमित रखता है और प्राप्त पूरी फ़ाइल सत्यापित करता है। देखें: बाइनरी आर्टिफ़ैक्ट, पूरे अनुबंध के लिए। ट्रांसफ़र स्वतंत्र SDK क्लाइंट और होस्ट से चलाएँ।

टिकाऊ जॉब, इतिहास और स्पष्ट पुनः प्रयास

SDK 0.8.0 कार्यक्षेत्र के बाहर ऑपरेटर स्वामित्व वाली डायरेक्टरी में वैकल्पिक टिकाऊ स्टोर जोड़ता है। निरपेक्ष पथ, स्थिर कार्यक्षेत्र ID, समीक्षा किया प्लगइन कोड, पैकेज SHA-256, टोकन और सूचना दें। उदाहरण फ़ाइल बाइट प्रतिधारण भी सक्षम करता है; केवल जॉब मेटाडेटा रखने के लिए jobStorage से artifacts छोड़ें। मौजूदा v1 जवाब और केवल मेमोरी वाले डिफ़ॉल्ट संगत रहते हैं।

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

प्रदाता केवल शुरुआती आशय सहेजने के बाद शुरू होता है। बाद के चेकपॉइंट एक साथ मिलाए जाते हैं; flushJobStore() अनुरोधित चेकपॉइंट का इंतज़ार करता है, कमांड समाप्ति का नहीं। पुनर्प्राप्ति मौजूदा कनेक्शन को मूल निष्पादन दायरे से अलग रखती है और live, completed, interrupted, expired, missing, corrupt या unsupported बताती है। बाधित जॉब अपने आप पुनः शुरू नहीं होती; उसका unrecordedTail अज्ञात है।

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

इतिहास state, पुनर्प्राप्ति स्थिति, कमांड, शुरू समय और पैरेंट प्रयास से फ़िल्टर होता है। पृष्ठ में अधिकतम 32 प्रविष्टियाँ होती हैं, पहले शुरू समय के घटते क्रम और फिर जॉब ID में। कर्सर सदस्यता 60 सेकंड फ़्रीज़ करता है और वही क्वेरी फिर उपयोग करनी चाहिए; नई जॉब बाहर रहती हैं, हटे या अनधिकृत रिकॉर्ड छोड़े जाते हैं और समाप्ति बताई जाती है। पुनः शुरू होने पर कर्सर खोते हैं। artifactCount, snapshotCount और resultAvailability दर्ज संदर्भ बताते हैं, वर्तमान फ़ाइल प्रमाण नहीं।

स्पष्ट पुनः प्रयास के लिए नई जॉब ID, नया सत्यापित इनपुट, वही मौजूदा अनुमोदित पैकेज और उपलब्ध कमांड चाहिए। attemptOf नए रन को अपरिवर्तित पैरेंट से जोड़ता है। वही ID, इनपुट, पैरेंट और समय सीमा दोहराने पर रखा प्रयास बिना फिर चलाए मिलता है, पुनः शुरू होने के बाद भी। अनुपस्थित/समाप्त रिकॉर्ड यह गारंटी नहीं दे सकते। स्वीकारा निष्पादन प्रतीक्षा अनुरोध रद्द होने के बाद चल सकता है; पुनः प्रयास तय करने से पहले नई जॉब ID पूछें।

डिफ़ॉल्ट प्रतिधारण कच्चा इनपुट, परिणाम बॉडी, प्रगति टेक्स्ट और आर्टिफ़ैक्ट लेबल छोड़ता है; लॉग संपादित करके संवेदनशील विवरण हटाए जाते हैं। केवल स्पष्ट नियतात्मक होस्ट रेडैक्टर समीक्षा किया टेक्स्ट रखता है। टोकन, सीक्रेट और पुरानी सहमति कभी बहाल नहीं होती। मौजूदा कार्यक्षेत्र/प्लगइन पहचान, पढ़ने की अनुमति और हर दर्ज अनुमति फिर जाँची जाती है। जॉब मेटाडेटा का डिफ़ॉल्ट 256 रिकॉर्ड, 64 MiB और 24 घंटे, अधिकतम सात दिन है। हटाना और पुराने रिकॉर्ड काटना स्पष्ट होस्ट कार्रवाइयाँ हैं।

स्थानीय स्टोर में एक लेखक है, कार्यक्षेत्र/रूट पहचान सत्यापित होती है और मेटाडेटा अखंडता जाँची जाती है। स्पष्ट पुराने लॉक की पुनर्प्राप्ति केवल प्रमाणित मृत उसी मशीन की PID वापस लेती है। अज्ञात/दूषित फ़ाइल का निरीक्षण चाहिए। Windows फ़ाइल sync और rename जाँची गई प्रक्रिया समाप्ति के बाद पुनर्प्राप्ति में उपयोग होते हैं; स्थायित्व फ़ाइल सिस्टम और संग्रहण डिवाइस के व्यवहार के अनुसार होता है। देखें: जॉब संग्रहण, इतिहास और टिकाऊ जॉब उदाहरण।

संग्रहित परिणाम और पुनः शुरू होने के बाद डाउनलोड

आर्टिफ़ैक्ट स्टोर सक्षम हो तो await job.addArtifact() या job.addBinaryArtifact() पंजीकरण से पहले पूरी फ़ाइल कॉपी और सत्यापित करता है। टेक्स्ट 256 KiB तक सीमित रहता है; बाइनरी अधिकतम 1 GiB हैं। स्रोत स्ट्रीम और वास्तविक स्टेजिंग फ़ाइल SHA-256 से जाँची जाती हैं। रद्दीकरण, डिस्क भरना, बदलाव और आंशिक लेखन उपयोग योग्य परिणाम प्रकाशित नहीं करते। क्रैश से पहले प्रकाशित, पर जॉब में दर्ज न हुई फ़ाइलें ऑपरेटर निरीक्षण के लिए रह सकती हैं।

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

सूची स्रोत संदर्भ और स्नैपशॉट मेटाडेटा अलग रखती है और retained, expired, missing, corrupt या unsupported स्नैपशॉट बताती है। retained मेटाडेटा स्थिति है; getStoredJobArtifact() नई मौजूदा जेनरेशन का संदर्भ देने से पहले मेटाडेटा और पूरी संग्रहित फ़ाइल सत्यापित करता है। हर पढ़ना वर्तमान अधिकार और फ़ाइल पहचान फिर जाँचता है। हटे स्रोत संग्रहित बाइट को नहीं बदलते और अनुपस्थित स्नैपशॉट कभी परिवर्तनशील स्रोत पर फ़ॉलबैक नहीं करते। टेक्स्ट स्नैपशॉट के लिए client.readStoredJobArtifactText(textReference) बुलाएँ।

पुनः शुरू होने के बाद मौजूदा अनुमतियों से फिर जुड़ें और नया संदर्भ लें। स्नैपशॉट ID, स्टोर ID और डाइजेस्ट स्थिर रहते हैं; पुरानी जेनरेशन अस्वीकार होती है। resume: true सहेजा .dds-part प्रीफ़िक्स उस स्नैपशॉट से फिर जाँचता है, खंड और पूरी स्टेजिंग फ़ाइल सत्यापित करता है और गंतव्य पर बिना ओवरराइट प्रकाशित करता है। पढ़ने के लिए फ़ाइल बाइट के साथ रखा जॉब मेटाडेटा भी चाहिए। ब्राउज़र खंड उपभोक्ता पूरा डाइजेस्ट सत्यापित करें; नीचे Worker एडैप्टर स्पष्ट ब्राउज़र डिस्क पुनः आरंभ देता है।

आर्टिफ़ैक्ट संग्रहण का डिफ़ॉल्ट 256 फ़ाइलें, 256 MiB और 24 घंटे है, अधिकतम कुल संग्रहण 4 GiB और प्रतिधारण सात दिन। खंड अधिकतम 64 KiB हैं, चार समवर्ती पढ़ने के साथ। inspect() उपयोग, समाप्ति समय, अमान्य प्रविष्टि और अनाथ फ़ाइल बताता है। remove(snapshot) और prune() स्पष्ट ऑपरेटर कार्रवाइयाँ हैं। सक्रिय जॉब और अलग पढ़ना पिन किए जाते हैं; खंडों के बीच समाप्ति या हटाना अगला पढ़ना रोक सकता है। वैकल्पिक अनाथ सफ़ाई केवल पहचानी एक लिंक वाली फ़ाइलें हटाती है। दूषित या अस्पष्ट प्रविष्टि का निरीक्षण चाहिए।

फ़ाइल प्रतिधारण लॉग रेडैक्शन से स्वतंत्र वास्तविक प्रोजेक्ट बाइट रखता है। इसे सोचकर चुनें। पुनः शुरू होने के बाद भी मौजूदा प्लगइन/कमांड, पैकेज हैश, कार्यक्षेत्र और दर्ज अनुमतियाँ चाहिए। रखरखाव पूरा करें, फिर इसी क्रम में server.close(), artifacts.close() और store.close() को await करें। फ़ाइल प्रतिधारण स्वतंत्र SDK होस्ट पर कॉन्फ़िगर करें और उपयोग करें।

वास्तविक चाइल्ड प्रक्रिया पुनः शुरू करने, स्रोत हटाने, सत्यापित आंशिक डाउनलोड पुनः आरंभ, इतिहास और स्पष्ट पुनः प्रयास के लिए npm run example:stored-artifacts चलाएँ। npm run example:durable-jobs बलपूर्वक प्रक्रिया समाप्ति भी कवर करता है। देखें: संग्रहित परिणाम। ज्ञात 0.7 और पुराने होस्ट अज्ञात प्रोब के बिना संग्रहण अक्षम बताते हैं। मौजूदा लाइव/स्रोत API अपना मूल व्यवहार रखते हैं।

प्रोजेक्ट का निरीक्षण करें

ऑपरेटर सर्वर पर प्रोजेक्ट स्पष्ट रूप से सक्षम करता है और अनुमत रूट चुनता है। डिफ़ॉल्ट अक्षम है। ज्ञात SDK 0.3–0.8 होस्ट नए खोज प्रोब के बिना अनुपलब्ध बताते हैं। समर्थित प्रोफ़ाइल Windows/Linux स्थानीय फ़ाइल सिस्टम उपयोग करती है। यह उदाहरण स्वतंत्र SDK प्रोजेक्ट API से चलाएँ।

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

पहली घटना पूरा स्नैपशॉट है। बाद के बदलाव पिछले संशोधन से डेल्टा देते हैं; खोए संकेत, शुरुआती स्कैन के बदलाव, अधूरे स्कैन और धीमे उपभोक्ता के ओवरफ़्लो से कारण सहित पूरा पुनः सिंक दृश्य आता है। नाम बदलना हटाने/बनाने के रूप में दिख सकता है। हर फ़ाइल अपने निरीक्षण समय पर अलग सत्यापित होती है; दृश्य इन नमूनों को जोड़ता है और बीच के लेखन एक साथ मिल सकते हैं।

सर्वर और क्लाइंट प्रत्येक चार सदस्यताएँ देते हैं, प्रति नेटिव सदस्यता चार कतारबद्ध घटनाएँ। डिफ़ॉल्ट निष्क्रिय लीज़ 30 सेकंड है; बाद में पढ़ना not_found दे सकता है। लंबे विराम के बाद शुरुआती स्नैपशॉट के लिए नया इटरेटर बनाएँ। break/return, रद्दीकरण और डिस्पोज़ करना सदस्यताएँ मुक्त करते हैं; टूटा कनेक्शन सफ़ाई रोके तो बाकी रिमोट संसाधन अपनी लीज़ पर समाप्त होते हैं।

डिफ़ॉल्ट स्कैन सीमा: गहराई 8, 512 प्रविष्टियाँ, प्रति फ़ाइल 1 MiB, कुल 16 MiB और 10 सेकंड। कॉन्फ़िगर अधिकतम: गहराई 32, 1,000 प्रविष्टियाँ, प्रति फ़ाइल 16 MiB, कुल 64 MiB और 30 सेकंड। सीमित फ़ाइल में सामग्री हैश बिना मेटाडेटा हो सकता है; complete और reasons जाँचें। समय सीमा फ़ाइल सिस्टम कॉल के बीच जाँची जाती है; इन कॉल के लिए होस्ट प्रक्रिया के OS एक्सेस सोचकर चुनें।

प्रोजेक्ट ट्री और खोज

listTree ट्री लौटाता है, searchFiles सापेक्ष फ़ाइल नामों में शाब्दिक उपस्ट्रिंग या सीमित glob खोजता है और searchText UTF-8 फ़ाइलों में शाब्दिक टेक्स्ट ढूँढ़ता है। root अनिवार्य है; include/exclude इसके सापेक्ष हैं। खोज पैटर्न के लिए शाब्दिक टेक्स्ट और दस्तावेज़ित सीमित फ़ाइल नाम glob सिंटैक्स उपयोग करें। केस असंवेदनशील मेल केवल ASCII A–Z मोड़ता है ताकि मूल UTF-16 स्थितियाँ स्थिर रहें।

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

टेक्स्ट मेल में सामग्री SHA-256, शून्य आधारित UTF-16 रेंज और सीमित स्निपेट हैं। कर्सर मूल सदस्यता अधिकतम 60 सेकंड फ़्रीज़ करता है और वही क्वेरी चाहिए। बाद के पृष्ठ मौजूदा सामग्री फिर जाँचकर आइटम current, changed, missing या unverified चिन्हित करते हैं; नई फ़ाइल केवल नई क्वेरी में आती है। पकड़ा मेल और संशोधन अपरिवर्तित रहते हैं।

टेक्स्ट फ़ाइलें 256 KiB, क्वेरी 256 UTF-16 यूनिट और स्निपेट 512 यूनिट तक सीमित हैं। डिफ़ॉल्ट 256 परिणाम (अधिकतम 512), प्रति पृष्ठ 32 आइटम (अधिकतम 64) और 64 KiB प्रतिक्रिया (अधिकतम 128 KiB) हैं। बाइनरी फ़ाइल, अमान्य UTF-8 और बाइट/गहराई/समय/प्रतिक्रिया सीमाएँ कारण सहित अधूरे परिणाम बताती हैं। दो समवर्ती क्वेरी और आठ रखे कर्सर दृश्य हैं; अनुपयोगी कर्सर स्पष्ट रूप से मुक्त करें।

प्रोजेक्ट ड्राफ़्ट और पुनः कनेक्शन

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

क्वेरी snapshotRevision निरीक्षित snapshot.revision से अलग हो तो पुराना कर्सर मुक्त करें और वही root/filter क्वेरी दोहराएँ। निरीक्षण कभी edit.snapshot या कॉलर स्वामित्व वाली ड्राफ़्ट सामग्री नहीं बदलता। बाहरी बदलाव, स्थानांतरण या हटाने के बाद मूल CAS शर्त संघर्ष बताती है; कॉलर स्पष्ट रीलोड, मर्ज या अलग सहेजना चुनता है।

क्लाइंट कनेक्शन जेनरेशन, root/filter, क्वेरी हैश, पृष्ठ स्थितियाँ, स्नैपशॉट SHA-256 और घटना निरंतरता जाँचता है। निरस्तीकरण, कनेक्शन हटाने या पुनः जोड़ने के बाद देर की प्रतिक्रियाएँ त्यागी जाती हैं। निरीक्षण कर्सर और क्वेरी कर्सर अलग हैं और अपने आप बहाल नहीं होते। server.revokeProjects() प्रोजेक्ट एक्सेस समाप्त करता है; फिर सक्षम करने के लिए नई सर्वर जेनरेशन चाहिए।

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

इंस्टॉल किए Node उदाहरण निर्माण, खोज, बाहरी बदलाव, रखे ड्राफ़्ट, CAS संघर्ष और पुनः कनेक्शन सत्यापित करते हैं। ब्राउज़र उदाहरण के लिए प्रिंट किया लूपबैक URL खोलें और परिदृश्य चलाएँ चुनें। यह केवल अपना अस्थायी कार्यक्षेत्र उपयोग करता है, जो उदाहरण सर्वर रोकने पर हटता है। HTTP अनुरोध का डिफ़ॉल्ट पाँच सेकंड है; बड़े स्कैन के लिए क्लाइंट और सर्वर समय सीमा सोचकर कॉन्फ़िगर करें।

प्रोजेक्ट निरीक्षण · ट्री/खोज अनुबंध · HTTP प्रोजेक्ट टूल

ब्राउज़र आर्टिफ़ैक्ट स्ट्रीम और सत्यापित करें

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

ब्राउज़र में सुरक्षित हेल्पर एक समय में अधिकतम एक 64 KiB खंड लेता है, चुने सिंक का इंतज़ार करता है और पूरी फ़ाइल क्रमशः हैश करता है। लिखने से पहले सटीक रेंज, पहचान, base64 और हर खंड का हैश सत्यापित करता है। रीडबैक सिंक सहेजी बाइट स्वतंत्र रूप से फिर पढ़ता है; दोनों पूरे हैश मेल खाने पर ही verification stored होता है। रीडबैक बिना verification received और storedSha256 null है। सभी बाइट की प्रगति पूर्णता नहीं है।

ऐप फ़ाइल हैंडल या OPFS डायरेक्टरी चुनता है और ज़रूरी अनुमतियाँ देता है। स्पष्ट चुना गंतव्य और स्वीकृत एक्सेस SDK एडैप्टर को दें; चयन और अनुमतियाँ ऐप सँभालता है। एसिंक्रोनस फ़ाइल/OPFS लिखने योग्य सिंक close तक स्टेजिंग रखते हैं और कमिट से पहले विफलता पर त्यागते हैं। रीलोड सुरक्षित आंशिक फ़ाइलों के लिए नीचे समर्पित Worker एडैप्टर उपयोग करें। फ़ाइल सीमा 1 GiB, चार सीधे समवर्ती स्ट्रीम और 30 मिनट कुल समय सीमा है।

चुनी हुई फ़ाइलें अपलोड करें

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

अपलोड डिफ़ॉल्ट रूप से अक्षम हैं। ऑपरेटर स्थानीय Node कार्यक्षेत्र, अलग स्टेजिंग डायरेक्टरी, अनुमत रूट और एक principal कॉन्फ़िगर करता है, फिर चुने प्लगइन को उसके सटीक आर्काइव पिन पर workspace.write देता है। हेल्पर शुरू होने से पहले चुना स्रोत हैश करता है। सर्वर क्रमिक 64 KiB खंड स्वीकार करता है, दोहराव और पूरी सामग्री सत्यापित करता है और सशर्त लक्ष्य जाँच के बाद ही कमिट करता है। सामान्य कार्यक्षेत्र सूची में कोई स्टेजिंग बाइट नहीं दिखती।

expectedRevision: null के लिए लक्ष्य अनुपस्थित चाहिए; SHA-256 के लिए मेल खाता मौजूदा लक्ष्य चाहिए। रद्दीकरण स्वीकृत सर्वर प्रीफ़िक्स रखता है। नई स्पष्ट recover कार्रवाई मौजूदा अधिकार पूछती है, वही स्रोत/विनिर्देश सत्यापित करती है और केवल मेल खाते प्रीफ़िक्स से फिर शुरू करती है। खोई कमिट प्रतिक्रिया पूछे जाने तक अनिश्चित है; इससे कमिट दोहराने या फ़ाइल रोलबैक की अनुमति नहीं मिलती। अधिकतम प्रति फ़ाइल 1 GiB, प्रति स्टोर 4 GiB और चार सक्रिय सत्र हैं; डिफ़ॉल्ट कम हैं। ज्ञात 0.3–0.9 होस्ट नई विधियाँ प्रोब किए बिना अपलोड अक्षम बताते हैं।

फ़ाइल ट्रांसफ़र का समय तय करें

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

कॉलर स्वामित्व वाली कतार अपलोड, लाइव डाउनलोड और संग्रहित डाउनलोड जॉब मिलाती है। रखी जॉब (32), समवर्ती चरण (4), क्लाइंट कनेक्शन समवर्तिता, डिकोड खंड आरक्षण (64–256 KiB), दर और पुनः प्रयास सीमित होते हैं। पात्र काम भरे कनेक्शन के आगे बढ़ता है और सीमित प्राथमिकता बढ़त छोटी पात्र जॉब को लगातार वंचित रहने से बचाती है। रुकी जॉब अपना वर्तमान चरण पूरा कर फिर इंतज़ार करती है; विराम संग्रहण लॉक रख सकता है। कुल समय सीमा में कतार प्रतीक्षा और विराम शामिल हैं।

स्वचालित पुनः प्रयास केवल इडेम्पोटेंट सटीक खंड कार्रवाई के दौरान SDK द्वारा पहचाने 429/503, नेटवर्क टूटना या अनुरोध समय सीमा पर होता है, सीमित बैकऑफ़ और जिटर के साथ। begin/commit, प्राधिकरण, चेकसम, रेंज, स्रोत या सिंक विफलताएँ स्पष्ट समीक्षा के लिए नियंत्रण कॉलर को लौटाती हैं। acknowledgedBytes, transferredBytes, attemptedBytes, retriedBytes, resumedBytes और remainingBytes अलग हैं; केवल सत्यापित रसीद completed देती है। पहले से कमिट फ़ाइल cancel/dispose के बाद भी कमिट रहती है।

ब्राउज़र डाउनलोड फिर शुरू करें

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

स्थायी पुनर्प्राप्ति के लिए समर्पित Worker, OPFS sync access और Web Locks चाहिए। रीलोड के बाद कॉलर अपनी डायरेक्टरी और आंशिक UUID फिर चुनता है और नया अनुमोदित संग्रहित संदर्भ लेता है। सिंक दो सटीक डेटा/मेटाडेटा फ़ाइल नाम, पूरी अपरिवर्तनीय स्नैपशॉट पहचान, समाप्ति और मौजूदा/पिछले प्रीफ़िक्स हैश रखता है। टोकन, अनुमतियाँ या पुराना कनेक्शन दायरा नहीं रखता। छोटी मेटाडेटा स्ट्रीम बंद होने से पहले हर डेटा खंड फ़्लश होता है।

सिंक और हेल्पर दोनों प्रीफ़िक्स स्वतंत्र रूप से फिर हैश करते हैं। बिना चेकपॉइंट का अंत केवल दर्ज प्रीफ़िक्स मेल खाने पर काटा जाता है। वास्तविक फ़ाइल आकार से आगे के मेटाडेटा से पिछले चेकपॉइंट पर तभी लौट सकते हैं जब बाइट और हैश मेल खाएँ; भ्रष्टाचार, अनुपस्थित प्रविष्टि, समाप्ति या अलग स्नैपशॉट चुपचाप पुनः शुरू किए बिना विफल होते हैं। पूरे ओरिजिन का अनन्य लॉक दूसरे टैब को अस्वीकार करता है, रीडबैक तक रहता है और close या Worker समाप्ति पर मुक्त होता है। फिर खोलने के लिए स्पष्ट पुनर्प्राप्ति चाहिए।

स्थानीय मेटाडेटा 16 KiB और चार खुले सिंक सत्र तक सीमित है। प्रतिधारण डिफ़ॉल्ट एक घंटा, अधिकतम 24 घंटे है, जिसे होस्ट स्नैपशॉट समाप्ति सीमित करती है। ब्राउज़र संग्रहण कोटा और निष्कासन सँभालता है; उसी ओरिजिन की स्क्रिप्ट संग्रहण अधिकार साझा करती हैं। पुनर्प्राप्ति इन संग्रहण नियमों के अंतर्गत दर्ज चेकपॉइंट उपयोग करती है। Windows पर Chromium 154 में रद्दीकरण, रीलोड, होस्ट पुनः शुरू, दो टैब संघर्ष और स्वामी टैब समाप्ति पूरे सहेजे फ़ाइल हैश के साथ जाँची गई। दर्ज जाँचें इसी ब्राउज़र और ऑपरेटिंग सिस्टम संयोजन को कवर करती हैं।

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

स्ट्रीमिंग · अपलोड · ट्रांसफ़र कतार · Worker पुनर्प्राप्ति

सिग्नेचर सहायता और पूर्णता सहयोग

ज़रूरत के अनुसार मैनिफ़ेस्ट v2 में signature-help, completion-resolve और completion-snippets घोषित करें; पूर्णता संशोधक के लिए completion भी चाहिए। होस्ट को document.read और language.provide देने चाहिए। मौजूदा शाब्दिक पूर्णताएँ वैध रहती हैं। languageCapabilities() अनुमति दिए बिना SDK कार्यान्वयन और उसकी सीमाएँ बताता है।

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

ऐप मौजूदा स्थिति और होस्ट देता है; तैयारी दस्तावेज़ या फ़ाइल लिखे बिना डेटा लौटाती है। सिग्नेचर सहायता अधिकतम 16 सिग्नेचर, प्रत्येक में 64 पैरामीटर और UTF-16 पैरामीटर लेबल ऑफ़सेट देती है। पूर्णता रिज़ॉल्यूशन प्रदाता डेटा निजी रखता है, एक बार उपयोग वाला होस्ट टोकन लौटाता है और चुना लेबल/इंसर्शन/रेंज निश्चित करता है। टोकन प्रदाता, दायरा और दस्तावेज़ से बँधते हैं, 60 सेकंड में समाप्त होते हैं और 128 प्रविष्टि, 4 MiB तथा चार वास्तविक रिज़ॉल्वर कार्रवाई तक सीमित हैं। दस्तावेज़/प्रदाता बदलाव इन्हें त्यागते हैं।

स्निपेट $n, ${n}, ${n:literal}, $0 और दस्तावेज़ित एस्केप का समर्थन करते हैं, मिरर और क्रमबद्ध टैबस्टॉप के साथ। वैरिएबल, नेस्टिंग, विकल्प, रूपांतरण और निष्पादन योग्य कमांड अस्वीकार होते हैं। UTF-16/CRLF सीमाएँ और ओवरलैप वाले अतिरिक्त संपादन जाँचे जाते हैं। प्रदाता होस्ट प्रक्रिया के ऑपरेटिंग सिस्टम अधिकारों से विश्वसनीय कोड चलाते हैं; रद्दीकरण अनदेखा करने वाला प्रदाता पूरा होने तक अपनी वास्तविक लंबित जगह घेरे रखता है।

समीक्षा किए कार्यक्षेत्र संपादन और नाम बदलना

prepare-rename सत्यापित रेंज/प्लेसहोल्डर या null लौटाता है; rename WorkspaceEdit प्रस्ताव या null लौटाता है। प्रस्ताव अलग सापेक्ष फ़ाइल पथों पर संपादन, निर्माण, स्थानांतरण और हटाना देते हैं। मौजूदा स्रोत SHA-256, गंतव्य अनुपस्थिति, सुरक्षित पथ नीति, UTF-16 संपादन ज्यामिति और सीमाएँ जाँची जाती हैं। भाषा क्षमताएँ प्रस्ताव अधिकृत करती हैं; कार्यक्षेत्र क्लाइंट अलग स्वीकृत फ़ाइल एक्सेस और बदलाव देता है।

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

कॉलर जुड़ा अधिकृत कार्यक्षेत्र क्लाइंट और विश्वसनीय जर्नल उपयोग करता है। पूर्वावलोकन में पूरे पहले/बाद के स्नैपशॉट और डाइजेस्ट होते हैं; apply के लिए समीक्षा किया planId/digest और true लौटाने वाली मौजूदा होस्ट नीति चाहिए। हर फ़ाइल की पूर्व जाँच होती है, फिर हर कार्रवाई मौजूदा प्रति फ़ाइल CAS और वर्तमान write/manage क्षमताएँ उपयोग करती है। जर्नल हर बदलाव से पहले आशय सुरक्षित कर पढ़ता है और बाद में रसीद। संघर्ष या अनिश्चितता आगे का लेखन रोकती है; हर फ़ाइल अपनी CAS कार्रवाई से कमिट होती है, इसलिए बाधित प्लान में पहले से कमिट फ़ाइलें हो सकती हैं।

वैकल्पिक workspace-edits-node एडैप्टर चुने कार्यक्षेत्र के बाहर सीमित जर्नल रखता है, पहचान बाँधता है और एक लेखक लॉक, नियमित फ़ाइलें तथा चेकसम चेकपॉइंट उपयोग करता है। प्रक्रिया समाप्ति के बाद recoverStaleLock स्पष्ट चयन है और केवल प्रमाणित मृत स्वामी को वापस लेता है। पुनर्प्राप्ति मौजूदा बाइट से applied/not-applied/conflicted/unknown बताती है और अगली कार्रवाई कॉलर चुनता है। क्षतिपूर्ति नई समीक्षा के लिए नया उलटा प्रस्ताव बनाती है। Windows पर एडैप्टर फ़ाइलें सिंक करता है और उनका नाम बदलता है; दर्ज टिकाऊपन जाँचें प्रक्रिया समाप्ति और पुनर्प्राप्ति कवर करती हैं। स्थायित्व फ़ाइल सिस्टम और संग्रहण डिवाइस के व्यवहार के अनुसार होता है। सीमाओं में 32 बदलाव, 1,000 संपादन, प्रति फ़ाइल 256 KiB, 8 MiB पूर्वावलोकन और 64 रखे जर्नल प्लान हैं।

फ़ॉर्मैटिंग और निदान कोड कार्रवाइयाँ

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

format-document और format-range को पथ तथा tabSize/insertSpaces विकल्प चाहिए; केवल रेंज फ़ॉर्मैटिंग चयन लेती है। परिणाम null या मौजूदा स्नैपशॉट हैश वाला ठीक एक वर्तमान फ़ाइल संपादन है। रेंज संपादन चयन के अंदर रहते हैं। endOfLine जोड़े टेक्स्ट के लिए preserve, lf या crlf चुनता है; बिना संपादित बाइट अपरिवर्तित हैं। समान सामग्री प्रस्ताव null में सामान्यीकृत होते हैं। prepareFormatting कोई लेखन नहीं करता।

होस्ट कार्रवाई अनुरोध और resolve टोकन को स्वीकारे निदान संशोधन तथा मौजूदा स्नैपशॉट से बाँधता है। बाद का निदान प्रकाशन, दस्तावेज़ बदलाव या प्रदाता डिस्पोज़ करना पुराने चयन अमान्य करता है। क्रम से बाहर निदान कॉल नया स्वीकारा बंडल ओवरराइट नहीं करतीं। अधिकतम 100 कार्रवाइयों में सादे लेबल, सीमित निदान सूचकांक, प्रस्तावित संपादन, निजी resolve डेटा या अक्षम कारण हैं। अज्ञात command/URL/shell फ़ील्ड अस्वीकार हैं। कार्रवाई संपादन चयन से आगे जा सकते हैं, इसलिए पूरा प्रस्ताव देखें; फ़ॉर्मैटिंग और कार्रवाइयाँ कभी अपना लेखन अनुमोदित नहीं करतीं।

सिमैंटिक डिस्प्ले, फ़ोल्डिंग, संकेत और प्रतीक

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

सिमैंटिक टोकन अद्वितीय नामों और होस्ट की नौ स्टाइल कुंजियों वाली लीजेंड उपयोग करते हैं, साथ में प्रति टोकन पाँच पूर्णांक: delta line/start, UTF-16 length, type index और modifier bits। टोकन ओवरलैप, सरोगेट विभाजन, पंक्ति पार या मौजूदा दस्तावेज़ से बाहर नहीं जा सकते। होस्ट हमेशा पूरा सामान्यीकृत ऐरे और होस्ट UUID लौटाता है, updateKind full/delta/fallback के साथ। अलग semantic-tokens-delta क्षमता प्रदाता स्वामित्व वाले पुराने डेटा पर provideDelta सक्षम करती है; कैश पहचान और टोकन डेटा रखता है, पुराना दस्तावेज़ टेक्स्ट नहीं।

कैश आधार प्रदाता, दायरा, URI और भाषा से बँधता है, अधिकतम आठ प्रविष्टि, 4 MiB और 60 सेकंड तक। सामान्य बढ़ते दस्तावेज़ संस्करण संभावित डेल्टा आधार रखते हैं और पुराना डिस्प्ले परिणाम बासी बनाते हैं। खोया/समाप्त आधार, null डेल्टा या बेमेल प्रदाता आधार ID मूल समय सीमा में अधिकतम एक पूरा फ़ॉलबैक देते हैं। अमान्य डेटा या प्रदाता त्रुटि बिना पुनः प्रयास विफल होती है। निष्क्रिय करना, पंजीकरण हटाना और दस्तावेज़ बदलना प्रभावित आधार साफ़ करते हैं। रेंडरिंग से ठीक पहले validateLanguageResult बुलाएँ; कॉपी, रिलीज़ या बासी ऑब्जेक्ट विफल होता है।

सीमाएँ 20,000 सिमैंटिक टोकन, 64 टोकन प्रकार, 16 संशोधक और 64 डेल्टा संपादन हैं; फ़ोल्डिंग 32 गहराई के साथ 1,000 रेंज देती है और काटती रेंज अस्वीकार करती है। इनले संकेत अनुरोधित रेंज में 1,000 एक पंक्ति के सादे लेबल देते हैं। पदानुक्रमित प्रतीक कुल 1,000 प्रविष्टि और 16 स्तर देते हैं, अंदर समाहित बच्चे/चयन तथा क्रमबद्ध बिना ओवरलैप वाले भाई तत्वों के साथ। मूल समतल document-symbols अनुबंध अपरिवर्तित है। ब्राउज़र उदाहरण full/delta/fallback, फ़ोल्डिंग, नेविगेशन और जीवनचक्र जाँचता है; HTML जैसे संकेत शाब्दिक टेक्स्ट रहते हैं।

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

सहायता · समीक्षा किए संपादन · फ़ॉर्मैटिंग/कार्रवाइयाँ · डिस्प्ले

टाइपयुक्त सेटिंग और सीक्रेट संदर्भ

/settings मॉड्यूल एक प्लगइन के लिए ऑपरेटर स्वामित्व वाला मेमोरी स्टोर देता है। संस्करण वाली परिभाषा हर कुंजी, डेटा स्कीमा, डिफ़ॉल्ट, अनुमत user/workspace दायरा और डिस्प्ले मेटाडेटा घोषित करती है। प्रभावी मान default < user < workspace क्रम में हर पूरी कुंजी बदलते हैं। read(workspaceId) अपरिवर्तनीय मान, स्रोत और पूरे स्टोर का संशोधन लौटाता है। नेस्टेड ऑब्जेक्ट पुनरावर्ती मर्ज नहीं होते; डिफ़ॉल्ट बिना अनुपस्थित मान अनुपस्थित रहता है।

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

लेखन पूरा ट्रांज़ैक्शन सत्यापित करता है और expectedRevision CAS उपयोग करता है। reset एक लेयर से कुंजी हटाता है; readOnly के लिए डिफ़ॉल्ट आवश्यक है और कोई लिखने योग्य दायरा नहीं होना चाहिए। सदस्यताएँ सिंक्रोनस बदलाव मिलाती हैं और डिस्पोज़ करने योग्य हैंडल लौटाती हैं। स्पष्ट migrate(nextDefinition, callback, options) अगली स्थिति सत्यापित कर केवल संशोधन अभी मेल खाने पर कमिट करता है। विफलता, रद्दीकरण या समय सीमा पुरानी परिभाषा और स्थिति रखती है। निर्यात/आयात सादा डेटा है; स्थायित्व और एन्क्रिप्शन ऑपरेटर की ज़िम्मेदारी हैं। सीमा: 64 कुंजियाँ, 32 कार्यक्षेत्र लेयर, 1 MiB निर्यातित स्थिति और एक वास्तविक माइग्रेशन।

कार्यक्षेत्र प्लगइन settings और settings.read घोषित करते हैं और ऑपरेटर उस अनुमति के साथ मेल खाता स्टोर माउंट करता है। context.settings केवल पढ़ने योग्य है और प्लगइन तथा चुने कार्यक्षेत्र से बँधा है। /secrets रिज़ॉल्वर अलग से प्लगइन, कार्यक्षेत्र, कमांड अनुमति सूची और जीवनकाल के लिए अपारदर्शी संदर्भ देता है। मैनिफ़ेस्ट में secrets.resolve घोषित हो और होस्ट अनुमति दे। इनपुट फ़ील्ड type: object तथा format: dds-secret-reference उपयोग करते हैं; सामान्य स्ट्रिंग या दिखने में समान ऑब्जेक्ट कोई सीक्रेट अधिकार नहीं देते।

केवल सत्यापित इनपुट के संदर्भ कमांड के options.secrets.withSecret से उपलब्ध हैं। हर निष्पादन की नई ID है; रिज़ॉल्वर रिज़ॉल्यूशन और कॉलबैक के आसपास दायरा, समाप्ति, निरस्तीकरण और मौजूदा प्राधिकरण जाँचता है। कॉलबैक undefined लौटाता है और ऐसी प्रति पाता है जो abort और हर निकास पर साफ़ होती है। प्रदाता त्रुटियाँ संवेदनशील विवरण से साफ़ की जाती हैं। उस अधिकार के ज़रूरी प्रभावों से पहले लीज़ रखें। संदर्भ जीवनकाल डिफ़ॉल्ट 60 सेकंड, अधिकतम एक घंटा है; सीमाएँ 128 संदर्भ, 8 वास्तविक लीज़ और 16 KiB सामग्री हैं। विश्वसनीय इन प्रोसेस कोड होस्ट प्रक्रिया के ऑपरेटिंग सिस्टम अधिकारों से चलता है और प्रतियाँ रख सकता है। सामग्री कभी सेटिंग, बंडल, लॉग या परिणाम में न डालें; संवेदनशील डेटा सँभालते समय मनमानी ऐप स्ट्रिंग को स्पष्ट रूप से वर्गीकृत करें।

संरचित कमांड स्कीमा और फ़ॉर्म

कमांड schemaVersion: 1 एनवेलप में inputSchema और outputSchema घोषित कर सकती हैं। मौजूदा आदिम पैरामीटर समर्थित हैं; parameters और inputSchema साथ घोषित करना अस्वीकार है। होस्ट हैंडलर या जॉब शुरू करने से पहले इनपुट सत्यापित कर डिफ़ॉल्ट लागू करता है, फिर सफलता प्रकाशित करने से पहले आउटपुट सत्यापित करता है। आउटपुट डिफ़ॉल्ट कभी लागू नहीं होते। नए स्कीमा/डिस्प्ले मेटाडेटा को 0.12 समझने वाला पीयर चाहिए; पुराने सख्त सत्यापक अस्वीकार करते हैं, जबकि पुरानी परिभाषाएँ अपना व्यवहार रखती हैं।

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

सीमित उपसमुच्चय बंद ऑब्जेक्ट, ऐरे, स्ट्रिंग, सीमित संख्या, सुरक्षित पूर्णांक, बूलियन, null, आदिम enum, सीमा और सत्यापित डिफ़ॉल्ट देता है। अज्ञात कीवर्ड, रिमोट संदर्भ, regex, union, coercion, accessor और कस्टम प्रोटोटाइप अस्वीकार हैं। स्कीमा में 32 KiB, गहराई 8 और 128 नोड; मानों में 64 KiB अनुमत हैं। पूरी कमांड 16 KiB मेटाडेटा बजट रखती है। स्थानीय DataValidationError code, reason और /input/options/names/0 जैसे ज्ञात फ़ील्ड पथ देता है; HTTP और जॉब विफलताएँ अस्वीकार मान बिना सुरक्षित कोड देती हैं।

describeDataForm पथ, प्रकार, विकल्प, डिफ़ॉल्ट, अनिवार्य फ़्लैग और सीक्रेट संदर्भ संकेत लौटाता है। साझा डिस्प्ले मेटाडेटा शाब्दिक label/help/order और सुलभता नाम, विवरण तथा कीबोर्ड संकेत रखता है। रेंडरिंग और इंटरैक्शन होस्ट के नियंत्रण में हैं। स्कीमा शाब्दिक फ़ॉर्म डेटा देती हैं; रेंडरिंग, संसाधन एक्सेस और कमांड निष्पादन होस्ट स्पष्ट रूप से लागू करता है।

स्थानीयकरण और सुलभता मेटाडेटा

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

कैटलॉग विहित BCP 47 बेस टैग और स्पष्ट अचक्रीय फ़ॉलबैक किनारों का उपयोग करते हैं। आठ प्राथमिकताओं तक सटीक टैग, फिर पूर्वजों और डिफ़ॉल्ट पर बातचीत होती है। डिफ़ॉल्ट लोकेल सभी कुंजियों को परिभाषित करता है; अनुवाद कुंजियों को छोड़ सकते हैं लेकिन उनका आविष्कार नहीं कर सकते। प्रति-कुंजी लुकअप आदेशित फ़ॉलबैक किनारों का अनुसरण करता है, फिर डिफ़ॉल्ट। प्रत्येक अनुवाद और उसके तर्कों को सटीक {name} प्लेसहोल्डर सेट से मेल खाना चाहिए। यह ICU अभिव्यक्तियों के बिना शाब्दिक प्रक्षेप है। resolveMessage वास्तविक स्रोत लोकेल और दिशा की रिपोर्ट करता है, इसलिए RTL पृष्ठ के अंदर अंग्रेज़ी फ़ॉलबैक lang=en और dir=ltr बनाए रख सकता है।

संख्या फ़ॉर्मैटिंग decimal/percent देती है; तारीख फ़ॉर्मैटिंग स्पष्ट epoch और डिफ़ॉल्ट UTC उपयोग करती है; बहुवचन चयन कॉलर के संदेश चयन के लिए Intl cardinal/ordinal श्रेणी लौटाता है। Intl डेटा और समर्थन होस्ट के हैं। validateLocalizedSurfaces manifest/command/settings/schema कुंजियाँ और थीम डिस्प्ले sidecar जाँचता है, जिसमें रिज़ॉल्व डिस्प्ले लंबाई और अनुपस्थित अनुवाद हैं। थीम JSON/XML संगत है। कैटलॉग सीमा 32 लोकेल, 256 कुंजी और 256 KiB है; स्थिर लेबल में प्लेसहोल्डर नहीं हो सकते।

/accessibility हेल्पर अनुपस्थित नाम, दोहरे सामान्यीकृत शॉर्टकट और हल्के/गहरे थीम में स्पष्ट अपारदर्शी रंग जोड़ी कॉन्ट्रास्ट बताते हैं। इन रिपोर्ट को जाँच संकेत की तरह उपयोग करें; ऑपरेटिंग सिस्टम की बाइंडिंग और ऐप का सुलभता मूल्यांकन होस्ट सँभालता है। स्वतंत्र उदाहरण में EN/KO, आंशिक अरबी और लंबे लेबल फ़िक्स्चर हैं। यह दायरे वाली सेटिंग, अस्वीकृत/निरस्त संदर्भ, अमान्य फ़ील्ड, Ctrl+Enter और लंबित कमांड के दौरान भाषा बदलाव जाँचता है। ब्राउज़र लेआउट हल्के/गहरे थीम में डेस्कटॉप/मोबाइल आकार पर जाँचा गया।

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

सेटिंग · सीक्रेट संदर्भ · कमांड स्कीमा · स्थानीयकरण

विकास टेम्पलेट और जनरेशन

छह टेम्पलेट, सटीक आर्काइव निर्भरताएँ, जनरेशन समीक्षा, संघर्ष संरक्षण और doctor जाँच।

पूरे अनुबंध, उदाहरण और सीमाएँ

नियतात्मक परीक्षण और रीप्ले

स्पष्ट कृत्रिम फ़िक्स्चर, वर्चुअल समय, दोष, सीमित केवल हैश ट्रेस और संसाधन सफ़ाई।

पूरे अनुबंध, उदाहरण और सीमाएँ

स्थानीय निदान और डिबगिंग

स्वैच्छिक स्थानीय प्रोफ़ाइल और अस्थायी लूपबैक एंडपॉइंट तथा कुल समय सीमा वाला विश्वसनीय चाइल्ड डिबगर।

पूरे अनुबंध, उदाहरण और सीमाएँ

होस्ट अनुरूपता

18 संस्करण वाले प्रोफ़ाइल समर्थित, असमर्थित और विफल अनुबंध अलग करते हैं; कस्टम एडैप्टर स्पष्ट अधिकार रखते हैं।

पूरे अनुबंध, उदाहरण और सीमाएँ

SDK समर्थन और माइग्रेशन

एक्सपोर्ट सूची, स्थिर/वैकल्पिक/प्रयोगात्मक नीति, सटीक पीयर, रनटाइम तारीख और माइग्रेशन उदाहरण देखें।

पूरे अनुबंध, उदाहरण और सीमाएँ

रिलीज़ स्वीकृति

रिलीज़ के संयुक्त दोष कार्यभार और मापे प्रदर्शन मानदंड स्वतंत्र SDK का कार्यात्मक व्यवहार दर्ज करते हैं।

पूरे अनुबंध, उदाहरण और सीमाएँ

1.1 निर्भरता, उद्गम और अपडेट टूल

1.1.0 समीक्षा की निर्भरताओं के नियतात्मक ऑफ़लाइन बंडल, CycloneDX SBOM, ऑपरेटर स्वामित्व वाली Ed25519 कुंजियों से अलग हस्ताक्षर, डाइजेस्ट से बँधा अनुमोदन/सक्रियण/रोलबैक और स्पष्ट अपस्ट्रीम तुलना जोड़ता है। केवल Node वाले पाँच प्रवेश बिंदुओं में घोषणाएँ, स्कीमा और स्वतंत्र उदाहरण हैं। हस्ताक्षर की समीक्षा के बाद होस्ट निष्पादन की स्पष्ट अनुमति देता है और पुरानी जॉब अपना मूल हैश रखती हैं। ऑपरेटर वितरण चैनल चुनता है और इन स्वतंत्र SDK टूल से सक्रियण, रोलबैक और अपस्ट्रीम तुलना बुलाता है।

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

पूरी बंडल, हस्ताक्षर, अपडेट और अपस्ट्रीम मार्गदर्शिका

1.2 वर्कफ़्लो, कैश, टूल स्ट्रीम और LSP

1.2.0 प्रति चरण जॉब/अनुमति वाले समीक्षा किए कमांड DAG, टिकाऊ चेकपॉइंट और स्पष्ट नए प्रयास की पुनर्प्राप्ति; नियतात्मक सामग्री आधारित कैश और क्रमिक निष्पादन; सीमित UTF-8/JSONL/टेक्स्ट टूल स्ट्रीम; तथा वैकल्पिक stdio LSP 3.17 ब्रिज जोड़ता है। सात नए प्रवेश बिंदुओं से पैकेज में घोषणाओं और स्वतंत्र इंस्टॉल उदाहरण सहित 50 एक्सपोर्ट और 107 स्कीमा हैं, तथा शून्य रनटाइम npm निर्भरताएँ। टूल स्ट्रीम पार्सर ब्राउज़र में भी चलता है; वर्कफ़्लो, स्टोर, बाहरी प्रक्रिया और LSP को Node चाहिए। वास्तविक एडैप्टर TypeScript 5.9.3 और language-server 5.3.0 से जाँचे गए; LSP ब्रिज दस्तावेज़ संस्करण से बँधे निदान स्वीकार करता है। ऑपरेटर वर्कफ़्लो प्रयास स्पष्ट रूप से जाँचकर शुरू करता है और स्वतंत्र SDK होस्ट, स्टोर तथा बाहरी प्रक्रिया कॉन्फ़िगर करता है।

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

पूरी वर्कफ़्लो, कैश, टूल और LSP मार्गदर्शिका