DDS 플러그인 SDK
공개 DDS Plugin SDK 1.2 설치·API·워크플로·캐시·도구 스트림·LSP와 지원 정책을 확인하세요.
아래 User workspace 예제는 사용자가 명시적으로 연결하는 자체 개발 호스트를 설명합니다. 독립 SDK 예제의 호스트로 WSL·컨테이너·서버 중 하나를 선택하세요. 일반 Digital Design Studio Windows 앱은 Windows에서 기본 실행됩니다. 선택한 SDK 호스트가 검색·권한·지원 플러그인 기능을 관리하며 관리 Cloud 엔진 작업은 자체 실행 경로를 사용합니다.
1. SDK 설치
DDS Plugin SDK 1.2.1은 JavaScript API, TypeScript 선언, 언어 기능, 테마, 워크스페이스 도구와 명령 작업을 제공합니다. 선택적 저장소로 작업 이력·명시적 재실행을 지원하고 검증된 텍스트·바이너리 결과를 원본 삭제·프로세스 재시작 후에도 복구합니다. Node.js 22 또는 24를 사용하세요. 공식 GitHub 릴리스에서 안정 SDK 릴리스를 설치합니다. 독립 명령 플러그인은 설치 후 개발 도구를 사용하세요:
1.0.0은 안정 SDK API·18개 호스트 적합성 검사·지원/이전 정책·실측 복합 부하 검증을 제공합니다. 새 플러그인은 >=1.0.0 <2.0.0을 사용합니다. 이 공개 결과는 독립 SDK의 API 적합성과 기능 동작을 설명합니다.
0.13.0은 여섯 개발 템플릿, 정의에서 타입·스키마 생성, 결정적 테스트 시나리오와 선택적 로컬 진단을 추가합니다. 저장소 밖에서 실제 패키지와 생성한 프로젝트를 검사하며, 합성 fixture 재생과 loopback 디버깅은 명시적으로 선택합니다.
0.12.0은 범위별 타입 설정과 명시적 마이그레이션, 실행 범위의 비밀 참조, 구조화된 명령 입력·출력, 다국어 카탈로그와 접근성 메타데이터를 추가합니다. 공개 SDK와 독립 예제에서 설정 충돌·잘못된 입력·권한 철회·번역 fallback을 검증했습니다. 독립 SDK 호스트 API와 예제로 이 기능을 사용하세요.
0.11.0은 서명 도움말·지연 자동완성·제한 스니펫, 검토한 다중 파일 편집과 rename, format/code action, 의미 토큰·접기·인레이 힌트·계층형 심볼을 추가합니다. 제안·검토·현재 권한·조건부 적용을 구분하고, 오래된 문서 결과는 표시하거나 적용하지 않습니다. 독립 호스트와 예제에서 이 공개 SDK 기능을 사용하세요.
0.10.0은 브라우저 스트리밍 다운로드, 선택 파일 업로드, 혼합 전송 큐와 Worker OPFS 체크포인트 복구를 추가합니다. 현재 권한·파일 identity·청크/전체 해시를 검증하고, 전송된 바이트와 저장 검증 완료를 구분합니다. 호스트와 브라우저 저장 위치를 명시적으로 선택해 이 공개 SDK 예제를 실행하세요.
0.9.0은 운영자가 선택한 로컬 폴더의 파일 트리·파일명/본문 검색·변경 감시를 추가합니다. HTTP 클라이언트와 프로젝트 API에서 사용하고, 외부 변경이 발생해도 편집 snapshot과 미저장 초안은 유지합니다. 아래 프로젝트 도구 예제로 생성부터 검색·변경 감지·충돌 처리까지 확인하세요.
mkdir hello-dds-plugin
cd hello-dds-plugin
npm init -y
npm install --ignore-scripts --save-exact "https://github.com/Altifigence/dds-plugin-sdk/releases/download/v1.2.1/altifigence-dds-plugin-sdk-1.2.1.tgz"
첫 진단 예제는 신뢰하는 코드를 로컬 테스트 호스트에서 실행합니다. 테마는 기존 DDS XML 가져오기를 사용합니다. 기존 도구 통합은 플러그인과 외부 도구에서 확인하세요.
2. 첫 플러그인 작성
새 프로젝트에 plugin.mjs를 만드세요. 이 플러그인은 일반 텍스트 문서를 검사하고 NOTE가 있는 각 줄에 정보 수준의 진단을 표시합니다.
plugin.mjs
import { createDiagnosticsResult, definePlugin } from '@altifigence/dds-plugin-sdk';
export default definePlugin({
manifestVersion: 1,
id: 'hello-diagnostics',
name: 'Hello Diagnostics',
publisher: 'example',
version: '0.1.0',
protocolVersion: 1,
entry: './plugin.mjs',
capabilities: ['diagnostics'],
permissions: ['document.read', 'diagnostics.publish'],
supportedHosts: ['test-host'],
license: 'Apache-2.0',
}, context => context.registerDiagnosticsProvider({languages: ['plaintext']}, {
provideDiagnostics(request, {signal}) {
signal.throwIfAborted();
const diagnostics = [];
const lines = request.snapshot.text.split(/\r\n|\n|\r/);
for (let line = 0; line < lines.length; line++) {
const character = lines[line].indexOf('NOTE');
if (character !== -1) diagnostics.push({
range: {start: {line, character}, end: {line, character: character + 4}},
severity: 'info',
code: 'todo',
source: 'hello-diagnostics',
message: 'Review this marked line before sharing the document.',
});
}
return createDiagnosticsResult(request, diagnostics);
},
}));
매니페스트는 프로토콜 버전 1, diagnostics 기능, test-host 호스트, document.read와 diagnostics.publish 권한을 선언합니다. 제공자는 문서 스냅샷과 AbortSignal을 받습니다. 진단 범위는 0부터 시작하는 줄 번호와 UTF-16 문자 오프셋을 사용합니다.
3. 로컬 실행
plugin.mjs 옆에 run.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();
}
node run.mjs
예상 출력입니다. 출력하는 줄 번호와 열 번호는 1부터 시작합니다.
Hello Diagnostics: 1 diagnostic
info 2:1 Review this marked line before sharing the document.
4. 플러그인 테스트
아래 테스트를 plugin.test.mjs로 저장하세요. 진단 범위를 확인하고 문서를 수정하면 진단이 사라지는지 검사합니다.
plugin.test.mjs
import assert from 'node:assert/strict';
import test from 'node:test';
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';
test('reports a NOTE and clears it after editing', async () => {
const host = createTestHost();
try {
await host.activate(plugin);
const document = {
uri: 'memory:///hello.txt',
languageId: 'plaintext',
modelVersion: 1,
workspaceRevision: 'test-1',
text: 'NOTE: write a plugin.\n',
};
host.setDocument(document);
const result = await host.requestDiagnostics();
assert.equal(result.diagnostics.length, 1);
assert.equal(result.diagnostics[0].code, 'todo');
assert.deepEqual(result.diagnostics[0].range, {
start: {line: 0, character: 0},
end: {line: 0, character: 4},
});
host.setDocument({...document, modelVersion: 2, text: 'Done.\n'});
assert.equal((await host.requestDiagnostics()).diagnostics.length, 0);
} finally {
host.dispose();
}
});
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');
node export-theme.mjs
명령은 hello-theme.xml을 만들고 Created hello-theme.xml을 출력합니다. DDS에서 플러그인 → 테마 설치…를 열고 XML을 선택한 뒤 Hello Ocean의 적용을 선택하세요. 밝게·어둡게 표시 설정을 바꿔 두 팔레트를 확인합니다.
설정 → 일반 → 외관 → XML 가져오기를 사용할 수도 있습니다. 교체하기 전에 XML 내보내기로 현재 테마를 저장하세요. 이 과정은 XML 외형 데이터를 테마 설정으로 가져옵니다.
테마 가이드에서 지원하는 모든 토큰과 수치를 확인하세요. Hello Ocean 예제에는 전체 테마, 바로 가져올 XML과 로컬 HTML 미리보기가 있습니다.
테마 XML 형식 참고
Hello Ocean XML과 편집용 JSON을 내려받으세요. XML 하나에 밝은·어두운 팔레트, 각 모드의 선택 색상 역할 28개, 명시적인 모양 설정 4개가 모두 들어 있습니다. XML을 로컬 파일로 저장한 뒤 가져오세요. 직접 제작한 SDK 예제에는 Apache-2.0이 적용됩니다. 다시 공유할 때 고지를 유지하세요.
먼저 설정 → 일반 → 외관 → XML 내보내기로 현재 테마를 백업하세요. 내려받은 XML을 가져온 뒤 초안을 확인하고 적용을 선택합니다. 변경 취소는 적용된 테마를 유지합니다. 밝은·어두운 모드를 바꾸며 두 팔레트를 확인하세요. 복구하려면 기본 제공 테마를 선택하거나 백업 XML을 가져옵니다. 가져오기가 거부되면 기존 테마가 유지됩니다.
DDS·ALcad·공유 편집기·프로젝트 탐색·설정·팝업은 해당 프로필의 공통 작업공간 팔레트를 사용합니다. Cloud와 데스크톱은 같은 테마 형식을 사용하며, 각 프로필에서 별도로 가져와야 합니다. gdsBackground는 GDS 캔버스 배경을 따로 조절합니다. 다른 설계 캔버스·레이어·시뮬레이션 색상은 자체 설정을 사용할 수 있습니다. XML은 해당 테마 프로필의 팔레트와 외형 수치를 담습니다.
요소 | 규칙 |
|---|---|
| 루트 1개, 공백 제거 후 이름 1–80 UTF-16 코드 단위, XML 전체는 UTF-8 기준 최대 65,536바이트. |
| 둘 다 필수이며, 각각 아래 기본 색상 6개가 모두 필요합니다. |
| v2의 선택 재정의 값입니다. 생략한 역할은 해당 모드의 DDS 기본값을 따릅니다. |
| v2의 선택 숫자 설정입니다. |
버전 1 | 두 팔레트만 포함합니다. 기존 v1 파일도 지원하며 SDK는 v2를 내보냅니다. |
필수 팔레트 키 | 용도 |
|---|---|
| 작업공간 바깥 배경 |
| 프로젝트 탐색 |
| 도구 패널과 컨트롤 |
| 주 작업공간과 설정 |
| 본문 텍스트 |
| 보조 텍스트 |
선택 색상 역할 키 (28개) | 용도 |
|---|---|
| 공통 검색 배경·텍스트·안내 문구 |
| 호환용 필드이며 현재 공통 검색창에는 테두리가 없습니다 |
| 선택한 행과 텍스트 |
| 편집기 탭 |
| 도구 영역·패널 경계·팝업 |
| 키보드 포커스 외곽선 |
| 상태 색상과 AI 구체 배경 |
| 자동완성 목록과 상세 패널 배경 |
| 자동완성·상세·보조 텍스트 |
| 키보드로 선택한 제안 |
| 포인터를 올린 제안 |
| GDS 뷰어 캔버스 배경 |
HintsBox는 공통 코드 자동완성 기능입니다. 색상은 사용자 지정 → 세부 색상과 모양 → HintsBox, GDS 배경은 표시에서 조절합니다. 검색 배경·텍스트·안내 문구의 대비를 유지하려면 세 색상을 함께 편집하세요. 아래 조각은 v2 테마 루트 안에 넣으며, 완전한 두 팔레트도 유지해야 합니다.
XML v2 fragment
<tokens mode="dark">
<color key="search" value="#214556"/>
<color key="searchText" value="#e8f4fb"/>
<color key="searchPlaceholder" value="#adcadb"/>
</tokens>
모양 설정 | 허용값 | 현재 DDS 기본값 |
|---|---|---|
| 정수 0–24 | 14 |
| 정수 0–16 | 6 |
| 정수 0–24 | 16 |
| 숫자 0.6–1 | 0.72 |
모양 값은 <metrics> 안에 <number key="popoverOpacity" value="0.9"/>처럼 단위 없이 씁니다. 반지름의 단위는 픽셀입니다. SDK는 생략한 값을 채우지 않으며 설치된 DDS 버전의 기본값을 사용합니다. 일정한 외형을 원하면 값을 명시하세요. Hello Ocean은 16·8·12·0.9를 의도적으로 지정합니다. 투명도 줄이기·강제 색상 접근성 설정은 최종 표시를 바꿀 수 있습니다.
색상은 6자리 #RRGGBB만 허용합니다. 알파값·CSS 색 이름·변수·URL·스타일은 거부합니다. 중복 키나 모드, 알 수 없는 요소·속성, 네임스페이스, DTD·엔티티·처리 명령도 거부합니다. XML 선언과 주석은 허용합니다. 가져오기가 실패하면 파일 크기·버전·두 팔레트의 필수 색상·허용값을 확인하고, 수정하지 않은 백업으로 다시 시도하세요. 다른 편집기의 테마는 이 DDS 형식으로 변환해야 합니다.
6. 사용자 환경에서 워크스페이스 실행
사용자의 WSL, 컨테이너 또는 서버 환경에서 호스트, SDK, 플러그인과 도구를 실행하세요. 프로젝트 파일은 사용자가 정한 루트에 있습니다. 독립 SDK 클라이언트는 연결을 통해 파일을 읽고 수정하며 플러그인 메타데이터와 명령 결과를 받습니다. 플러그인 코드는 사용자 환경에서 실행됩니다.
앞에서 만든 SDK 프로젝트에 이 도우미를 copy-workspace-example.mjs로 저장하세요. 예제의 라이선스 경로를 유지하면서 편집할 서버, 플러그인, 도구와 샘플 프로젝트를 복사합니다.
copy-workspace-example.mjs
import { cp, copyFile, mkdir } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';
const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await mkdir('./user-host/examples', {recursive: true});
await cp(path.join(sdkRoot, 'examples/user-workspace'), './user-host/examples/user-workspace', {
recursive: true, force: false, errorOnExist: true,
});
await copyFile(path.join(sdkRoot, 'LICENSE'), './user-host/LICENSE');
console.log('Created user-host');
node copy-workspace-example.mjs
샘플 프로젝트는 user-host/examples/user-workspace/project에 있습니다. 해당 환경에서 명시적으로 생성한 토큰으로 서버를 시작하세요.
WSL / Linux / container
export DDS_WORKSPACE_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
node user-host/examples/user-workspace/server.mjs
PowerShell
$env:DDS_WORKSPACE_TOKEN = node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))"
node user-host/examples/user-workspace/server.mjs
서버는 Workspace server: http://127.0.0.1:4777/dds/workspace/v1과 워크스페이스 ID·세대를 출력합니다. 클라이언트 터미널에서 DDS_WORKSPACE_TOKEN 환경변수에 생성한 토큰을 설정하세요. 이 운영자 자격 증명은 DDS Account 토큰과 별개입니다. 샘플 서버는 Ctrl+C로 중단합니다.
같은 프로젝트의 다른 터미널에서 DDS_WORKSPACE_TOKEN을 동일한 비밀 값으로 설정한 뒤 개발용 클라이언트를 실행하세요.
node user-host/examples/user-workspace/client.mjs http://127.0.0.1:4777
클라이언트는 샘플 파일을 나열하고 design.sv에 Inspect project file을 실행합니다. JSON 결과에는 실제 자식 프로세스가 계산한 tool: "module-counter"와 modules: 1이 포함됩니다. 예제가 샘플 파일에 메모를 추가하도록 하려는 경우에만 클라이언트 명령 끝에 --edit를 붙이세요.
자신의 프로젝트를 사용하려면 server.mjs의 마지막 인자로 절대 디렉터리를 전달하세요. 서버, 플러그인 모듈과 설치한 도구도 같은 사용자 환경에 두세요. server.mjs는 플러그인을 명시적으로 가져오고 이름이 지정된 백엔드를 고정 실행 파일과 인자에 연결합니다.
server.mjs backend mapping
'module-counter': createProcessBackend({
executable: process.execPath,
args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
cwd: root,
env: {},
})
이 연결을 승인한 설치 도구나 사용자 백엔드로 바꾸세요. ctx.workspace.readFile과 writeFile은 선택한 루트에 상대적인 경로를 사용합니다. ctx.backends.invoke("module-counter", input, {signal})은 설정된 백엔드 이름만 호출합니다. 프로세스 어댑터는 표준 입력으로 크기가 제한된 JSON을 보내고 표준 출력으로 JSON을 받습니다. 요청이 지정한 셸 명령을 사용하거나 호스트의 환경 변수를 상속하지 않습니다.
원격 서버에는 사용자가 관리하는 인증된 HTTPS 엔드포인트 또는 로컬 루프백으로 연결되는 비공개 터널을 사용하세요. 컨테이너 포트 연결이나 TLS는 사용자 환경에서 설정합니다. 예제는 기본적으로 루프백에 바인딩하며 바인딩 주소를 바꿔도 TLS가 추가되지는 않습니다. 신뢰하는 플러그인과 도구는 호스트 프로세스의 운영체제 권한으로 실행됩니다.
서버 설정, 출처, 파일 리비전, 취소와 제한된 결과는 사용자 워크스페이스 예제와 워크스페이스 프로토콜을 확인하세요.
언어 기능
SDK 0.7.0은 자동완성·호버·정의·참조·평면 문서 심볼을 제공합니다. manifest v2의 capabilities에 사용할 기능을 선언하고, permissions에 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();
}
node language-demo.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/hello-language/run.mjs
첫 명령은 A local LED signal.을 출력합니다. 두 번째 명령은 포함된 예제로 다섯 기능을 모두 확인합니다. let name = value 형식의 작은 학습용 언어를 사용하며 예제의 자체 제공자가 그 언어를 구현합니다.
기능 | 요청 입력 | 결과 데이터 |
|---|---|---|
|
| 최대 500개의 |
|
|
|
|
| 최대 500개의 워크스페이스 상대 경로 |
|
| 최대 500개의 워크스페이스 상대 경로 |
|
| 최대 500개의 평면 |
위치는 0부터 시작하는 줄과 UTF-16 문자 오프셋입니다. 자동완성 삽입 문자열·호버·설명은 일반 텍스트입니다. 호스트는 위치로 이동하기 전에 대상 파일과 범위를 확인해야 합니다. 결과에는 요청·프로젝트/세션·문서 버전의 식별 정보가 유지됩니다. 스냅샷 변경, 취소, 시간 초과, 등록 해제 또는 종료 시 진행 중인 요청을 끝내고 늦게 도착한 결과를 폐기합니다.
이 API는 신뢰하는 코드를 실행하는 SDK 호스트의 기능입니다. 독립 호스트가 등록한 언어 제공자를 호출하며 LSP 브리지는 명시적인 별도 프로세스 설정을 사용합니다. 0.3.0 이전 호스트는 새 capability를 거부합니다. 선택자·제한·수명 주기는 언어 기능 안내를 확인하세요.
프로젝트 편집 세션
@altifigence/dds-plugin-sdk/workspace-client에서 createWorkspaceProject와 applyTextEdits를 가져옵니다. 호스트가 createWorkspaceClient를 연결하고 워크스페이스 식별 정보·고지·접근 권한을 검토한 뒤 createWorkspaceProject(client)를 호출하세요. 프로젝트는 해당 연결에 묶입니다. 재연결하면 같은 워크스페이스 ID와 generation이어도 검토를 거쳐 새 프로젝트를 만들어야 합니다.
API | 동작 |
|---|---|
| 선택한 워크스페이스 루트 안의 한 디렉터리를 조회합니다. |
| 파일을 읽고 변경 불가능한 내용과 리비전을 편집 세션에 보관합니다. |
| 파일이 없을 때만 생성한 뒤 세션을 반환합니다. |
| 마지막으로 확인한 |
| 서버의 리비전이 보관한 리비전과 같을 때만 저장합니다. |
| 한 스냅샷을 기준으로 |
| 충돌이나 결과가 불확실한 쓰기 뒤에 최신 내용과 리비전을 명시적으로 읽습니다. |
| 소유한 작업을 취소합니다. 프로젝트를 종료해도 호출자가 소유한 client 연결은 유지됩니다. |
설치한 패키지의 전체 HTTP 예제를 실행하세요. 자체 임시 샘플 워크스페이스를 만들고 편집·두 번째 세션의 충돌·명시적 다시 읽기·Unicode·재연결을 검사한 다음, 서버를 종료하고 그 임시 디렉터리를 삭제합니다.
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는 자동 병합이나 재시도를 하지 않습니다. 서버가 저장한 뒤에 시간 초과·취소·응답 유실이 발생할 수 있으므로 취소가 롤백을 보장하지 않습니다. 세션별 저장 또는 다시 읽기는 한 번에 하나만 진행할 수 있습니다.
텍스트 편집은 원본 스냅샷의 0부터 시작하는 줄과 UTF-16 오프셋을 사용합니다. 겹친 범위·분리된 surrogate pair·잘못된 위치를 저장 전에 거부합니다. 프로젝트에는 열렸거나 여는 중인 세션이 최대 64개, 한 번 저장할 때 편집이 최대 500개입니다. 기존 workspace protocol v1을 그대로 사용하므로 SDK 0.2.x 서버에서도 동작하며 루트·보호 경로·읽기 전용 제한을 유지합니다. 수명 주기와 크기 제한은 워크스페이스 프로젝트 안내를 확인하세요.
API 레퍼런스
플러그인 API는 @altifigence/dds-plugin-sdk에서 가져옵니다. 패키지에는 동일한 API의 TypeScript 선언이 포함되어 있습니다.
API | 용도 |
|---|---|
| 매니페스트를 검증하고 활성화 함수를 선언합니다. |
| 선택한 언어 ID에 |
| 요청 식별 정보를 유지한 검증된 결과를 만듭니다. |
| 언어 제공자를 등록하고 검증된 요청 식별 정보로 결과를 만듭니다. |
| 매니페스트 버전, 식별 정보, 권한, 지원 호스트와 진입 모듈을 검증합니다. |
| URI, 언어, 모델 버전, 워크스페이스 리비전과 텍스트를 검증합니다. |
| 프로토콜, 요청, 범위, 문서 식별 정보와 진단 필드를 검증합니다. |
| 오류, 자원 제한과 프로토콜 버전을 확인합니다. |
개발용 호스트는 @altifigence/dds-plugin-sdk/testing에서 가져옵니다.
테스트 호스트 API | 용도 |
|---|---|
| 로컬 호스트를 만듭니다. 두 옵션 모두 선택 사항이며 기본 권한은 문서 읽기와 진단을 허용합니다. |
| 플러그인을 활성화하고 해제 가능한 활성화 객체를 반환합니다. |
| 현재 문서를 설정합니다. 텍스트를 바꾸면 |
| 일치하는 제공자에게 진단을 요청합니다. 두 옵션 모두 선택 사항입니다. |
| document.read와 language.provide를 명시적으로 승인한 뒤 선언된 언어 기능을 요청합니다. |
| 등록을 제거하고 진행 중인 작업을 취소합니다. 테스트를 마치면 호스트를 해제하세요. |
요청에는 requestId, 프로젝트·세션 scope, 그리고 uri, languageId, modelVersion, workspaceRevision, text를 포함한 스냅샷이 있습니다. createDiagnosticsResult로 이 식별 정보를 유지하세요. 결과에는 diagnostics 배열이 있으며 원문 텍스트는 포함하지 않습니다.
오류에는 invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable, budget_exceeded 등의 code가 있습니다. 기본 요청 제한 시간은 5초이며 1–30,000ms로 지정할 수 있습니다. 문서는 UTF-8 기준 262,144바이트, 결과는 진단 500개로 제한됩니다. 전체 제한은 LIMITS에서 확인하세요.
SDK 1.0.0은 별도 모듈도 제공합니다. Node 전용 워크스페이스와 패키징 모듈은 사용자 환경에서 사용하세요.
가져올 모듈 | API |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
플러그인 패키징과 배포
포함된 배포용 플러그인 예제로 시작하세요. 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');
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"
]
}
예제를 검증하고 패키징하세요.
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 archive의 원래 peer는 유지됩니다. 안정 버전 설치를 위해 검증한 새 플러그인 버전을 패키징하세요. 게시자는 재패키징 과정에서 선언된 peer 범위와 릴리스 메타데이터를 명시적으로 갱신합니다.
내려받은 플러그인 검증
SDK 1.2.1의 dds-plugin verify는 정확한 기존 0.3.x~0.13.x·RC1·현재 stable 플러그인 메타데이터를 검사합니다. .tgz와 .tgz.release.json을 함께 보관하세요. 원래 peer는 유지됩니다. 앞에서 만든 패키지는 다음과 같이 검사합니다.
Verify the packaged example
npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz
gzip/tar 구조와 크기 제한, 정확한 파일 허용 목록, 각 파일의 해시, manifest·고지·라이선스·생성된 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 플러그인 아카이브는 원래 peer 범위를 유지한 채 검증할 수 있습니다. 1.0에 설치하려면 발행자가 검증하고 새 버전으로 패키징해야 합니다. 새로 제외된 파일이 있으면 제거하고 새 플러그인 버전을 발행하세요. 이 검증기는 DDS 플러그인 패키지용이며 SDK npm tarball은 릴리스 SHA-256으로 확인합니다.
아카이브 검증 안내와 패키징·검증·변조 거부 전체 예제를 참고하세요.
권한, 라이선스와 데이터 사용
매니페스트의 요청 권한과 동작을 허용하는 호스트의 권한 부여는 별개입니다. 활성화하기 전에 사용자에게 플러그인 식별 정보, 버전, 실제 라이선스, 워크스페이스 범위와 요청 권한을 보여주세요. 백엔드를 연결하기 전에는 운영자, 전송 데이터, 목적, 보유기간과 개인정보 고지를 설명하세요.
기록 | 의미 |
|---|---|
| 정확한 패키지, 워크스페이스와 권한에 대한 호스트의 접근 결정입니다. |
| 사용자가 정보고지를 확인한 기록입니다. |
| 사용자가 게시자의 실제 플러그인 약관 수락 여부를 선택한 기록입니다. |
| 선택적 처리가 동의를 근거로 하는 경우의 별도 선택입니다. |
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 테스트를 소스에서 실행하려면 다음 명령을 사용하세요.
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개 |
요청·응답 / 파일 내용 | UTF-8 기준 1,600,000 / 262,144바이트 |
클라이언트는 거부된 응답의 읽지 않은 본문과 시간 초과·취소된 스트림을 정리합니다. 쓰기가 시작된 뒤 시간 초과가 발생하면 저장 결과가 불확실할 수 있으므로 재시도 전에 파일을 다시 읽으세요. 명시적 경로 제외 목록과 함께 파일 내용도 검토하고 신뢰한 플러그인 코드가 호스트 프로세스의 운영체제 접근 권한으로 실행됨을 고려하세요. 호스트 배포 시 보안 업데이트 안내와 워크스페이스 제한을 확인하세요.
개발 도구
위에서 SDK 1.2.1을 설치한 프로젝트에서 별도의 명령 플러그인 프로젝트를 만드세요. 생성 파일을 저장할 새 대상 디렉터리를 선택하세요. 골격을 만든 뒤 의존성 설치와 플러그인 실행은 명시적으로 진행합니다. 명령·테스트·manifest·발행자 고지·고정한 SDK 의존성과 Apache-2.0 LICENSE/NOTICE를 생성합니다.
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는 플러그인을 import하지 않고 Node, SDK 경로, manifest, 라이선스, 고지, 배포 허용 파일을 읽어 검사합니다. 오류가 있으면 종료 코드 1을 반환하고 예제 publisher·지원 URL은 경고로 표시합니다. 배포 전 실제 값과 라이선스를 검토하세요.
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가 필요합니다. 신뢰하는 로컬 코드의 import와 활성화를 자식 프로세스에서 실행하며, 배포 허용 파일과 dds-package.json만 감시합니다. 각 실행에 시간 제한과 stdout/stderr 256 KiB 한도를 적용하고 Ctrl+C로 감시 및 소유한 프로세스 트리를 정리합니다. 자식 프로세스는 사용자의 운영체제 권한과 상속한 환경으로 실행됩니다. 기본 테스트 호스트는 문서 읽기와 진단을 제공하며 파일·백엔드 연동은 별도 workspace 호스트와 명시적인 권한으로 설정하세요.
--job으로 진행률·로그를 확인하고 --timeout-ms로 일반 명령 최대 30초, 작업 최대 30분을 설정합니다. /devtools의 Node API는 initPlugin, doctorPlugin, runPluginDev입니다. 감시 동작과 자원 정리는 개발 도구 안내를 참고하세요.
장시간 명령 작업
0.4.0 SDK 호스트·서버에 jobs: true를 지정하면 일반 요청 제한보다 오래 실행되는 명령을 작업으로 처리할 수 있습니다. 기본값은 비활성화입니다. 진행률, 지정한 백엔드의 로그, 해시로 고정한 결과 파일을 확인하는 전체 로컬 HTTP 예제를 실행하세요.
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);
}
조회 코드는 연결한 client와 report 파일을 등록하는 analyze 명령이 설정됐다고 가정합니다. 시작 요청 전에 작업 ID를 보관하세요. 연결 해제나 조회 요청 취소는 작업 실행을 취소하지 않습니다. 같은 호스트 세대에 다시 연결해 명시적으로 조회·취소하세요. 보관 중 같은 ID·입력으로 시작을 재시도하면 기존 작업을 반환하고 인수가 다르면 충돌합니다. 호스트 재시작 시 메모리의 작업 기록은 사라집니다. 재시작 뒤 저장 기록을 복구하려면 아래의 별도 0.8 저장소를 켜세요.
상태는 running, succeeded, failed, cancelled, timed_out입니다. 취소 뒤 늦은 출력은 버리지만 이전 부작용을 되돌리지는 않습니다. 종료하지 않은 제공자 작업은 실행 슬롯을 계속 사용합니다. 동시 작업 4개, 기록 32개, 작업당 내부 호출 32개, 이벤트 256개/64 KiB, 조회당 이벤트 64개, 결과 파일 16개로 제한합니다. 실행은 기본 5분·최대 30분이고 실제 실행이 끝난 종료 기록은 마지막 이벤트로부터 15분 후 만료됩니다.
텍스트 결과 파일은 workspace 내부 상대 경로의 UTF-8 256 KiB까지 지원합니다. 호스트가 기존 권한으로 읽고 SHA-256을 기록하며 이후 바이트가 바뀌면 읽기를 거부합니다. 바이너리·대용량 시뮬레이션 출력은 선택 기능인 바이너리 결과 API를 사용하세요. 취소 후 일부 결과가 남을 수 있으므로 작업의 최종 상태로 성공을 확인하세요. 기존 0.3 클라이언트는 기존 v1 메서드를 계속 사용하고 독립 SDK 작업은 클라이언트와 호스트 모두 0.4 이상을 사용합니다. 정확한 계약과 한도는 작업 안내를 참고하세요.
워크스페이스 파일 변경 관찰
project.watchFiles()는 명시한 상대 파일 경로 1–16개를 주기적으로 관측합니다. SDK 1.0.0은 지원 서버에서 리비전만 조회하고 구형 서버에서는 기존 제한된 파일 읽기를 사용합니다. 아래 코드는 호스트가 승인하고 연결한 client를 사용합니다. 외부 편집기에서 design.sv를 바꾸면 반복을 끝내며 기존 편집 snapshot은 그대로 유지됩니다.
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는 첫 기준만 기록하고 동일 revision은 중복 알리지 않습니다. not_found만 삭제로 취급하며 권한·보호 경로·크기·전송 오류는 관찰을 종료합니다.
UI의 미저장 초안은 별도로 보존하세요. 관찰은 초안과 편집 스냅샷을 보존합니다. 호출자가 다시 읽기·병합·저장을 명시적으로 선택하며 저장 시 보관한 revision으로 충돌을 확인합니다. 지정 순서대로 파일을 하나씩 읽으므로 관측 사이의 변경은 합쳐질 수 있습니다. 관찰할 파일 경로를 직접 선택하며 각 이벤트는 관측한 경로와 리비전을 설명합니다. 읽기 전용과 쓰기 가능 서버 모두 기존 루트·파일 크기·보호 경로 제한을 적용합니다.
파일·작업 관찰은 첫 next()에서 시작하고 소비자가 멈춰 있는 동안 백그라운드 조회를 하지 않습니다. 클라이언트당 두 종류를 합해 최대 8개이며 관찰자당 next() 하나만 대기할 수 있습니다. 동시 요청은 conflict로 실패합니다. break나 return()은 대기 중 읽기를 끝내고 프로젝트 폐기는 해당 파일 관찰을 종료합니다. 연결 해제·재연결·client 폐기는 기존 관찰자를 무효화하며 AbortSignal은 cancelled로 종료합니다. 늦은 응답은 전달하지 않습니다.
intervalMs는 250–60,000ms이고 기본 1,000ms이며 파일 목록을 한 차례 읽은 뒤나 새 작업 이벤트를 기다릴 때 적용합니다. requestTimeoutMs는 요청당 1–30,000ms이며 생략하면 client의 요청 제한을 따릅니다. 전체 timeoutMs는 첫 next()부터 소비자 대기까지 포함한 1–1,800,000ms입니다. 파일은 기본 전체 제한이 없고 작업은 기본 30분입니다. 만료되면 budget_exceeded와 함께 관찰 슬롯을 반환합니다. WORKSPACE_OBSERVATION_LIMITS에서 한도를 확인할 수 있습니다.
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()은 최종 snapshot을 반환합니다. 아래 코드는 연결한 client, 명시적으로 시작한 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);
변경할 수 없는 update에는 snapshot·events·after·nextCursor·dropped·hasMore가 들어 있습니다. 페이지당 최대 64개 이벤트를 처리한 뒤 nextCursor를 job ID·워크스페이스 식별자와 함께 보관하세요. dropped는 만료된 과거 이벤트 수입니다. snapshot이 이벤트 페이지보다 최신일 수 있으므로 종료 상태여도 hasMore가 true이면 계속 읽습니다. 마지막 페이지까지 읽으면 반복이 끝납니다. waitForJob()도 같은 페이지를 모두 읽고 succeeded·failed·cancelled·timed_out을 반환하므로 Promise 완료만으로 성공이라 판단하지 말고 state를 확인하세요.
반복 중단이나 관찰 시간 초과는 관찰만 종료합니다. 서버 명령은 완료되거나 cancelJob()을 명시적으로 호출할 때까지 계속됩니다. 호스트가 승인한 재연결 뒤 같은 workspace ID·generation을 확인하고 보관한 job ID·커서로 새 관찰자를 만드세요. 식별자가 같아도 이전 관찰자는 무효입니다. 없거나 만료된 작업과 전송 오류는 재제출 없이 보고하며 메모리 작업은 호스트 재시작 후 유지되지 않습니다. 영구 저장 복구는 새 연결에서 recoverJob()으로 수행하며 실시간 관찰자를 세대 간에 그대로 재사용하지 않습니다.
기존 v1 hello·작업 계약은 유지됩니다. 파일 관찰은 0.3.2/0.4/0.5 호스트에서 기존 읽기로 전환하고 작업 관찰은 작업을 활성화한 0.4 이상 호스트가 필요합니다. 관찰 전에 호스트 작업 기능을 확인하세요. 미지원 응답은 요청을 종료하여 명령 실행에 대한 명시적 제어를 유지합니다. 이 관찰 기능은 독립 SDK 클라이언트와 호스트에서 실행됩니다. 관찰 안내와 호환성을 참고하세요.
파일 리비전 조회와 조건부 읽기
SDK 0.6.0은 연결한 client에 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);
이미 승인하고 연결한 client를 사용하고 미저장 초안은 캐시와 별도로 유지하세요. 조건부 읽기는 한 파일 snapshot을 읽고 해시를 계산하지만 이후 조회에서는 다시 바뀔 수 있습니다. 저장할 때는 반환한 본문과 함께 받은 리비전을 사용하세요. 이 호출은 편집 세션 snapshot을 바꾸거나 초안을 병합하지 않습니다. 변경 없는 응답에는 content 필드가 없고 빈 파일로 바뀐 응답에는 content: “”가 있습니다.
파일 감시는 지원 서버에서 리비전 조회를 자동 사용합니다. 선택 기능인 fs.capabilities·fs.revision·fs.readIfChanged는 기존 v1 hello·파일 메서드를 유지합니다. 알려진 0.6 이전 SDK 워크스페이스 호스트에는 새 메서드를 탐색하지 않고 fs.read를 사용합니다. 다른 호스트는 기능 조회에 응답하거나 요청 ID가 일치하는 unsupported 오류를 반환해야 합니다. false로 표시한 기능은 각각 기존 제한된 읽기로 전환하며 구형 서버의 응답에는 여전히 본문 전체가 포함됩니다.
기능 캐시는 현재 연결에만 적용하고 재연결·권한 회수 시 지웁니다. 잘못된 응답, 경로·리비전 불일치, 권한·인증·전송 오류와 시간 초과를 미지원으로 취급하지 않습니다. 지원한다고 밝힌 기능이 이후 실패해도 기존 읽기로 몰래 전환하지 않습니다. AbortSignal은 기능 조회와 읽기에 모두 적용하고 timeoutMs는 HTTP 요청별 제한입니다. 연결이 바뀌면 이전 호출은 무효가 됩니다.
서버는 매번 안전한 전체 파일 읽기와 SHA-256 계산을 수행합니다. UTF-8·262,144바이트 제한과 보호 경로·링크 검사도 유지합니다. 표본별 안전한 디스크 읽기와 SHA-256 계산을 유지하며 네트워크 응답량을 줄입니다. Windows의 Node 22.23.1에서 200,000바이트 파일을 변경 없이 20번 조회한 결과, 전체 읽기는 4,003,974바이트, 리비전 조회는 3,867바이트(99.903% 감소), 조건부 읽기는 4,247바이트(99.894% 감소)였습니다. 기능 탐색 응답은 포함하고 HTTP 헤더·TLS·처음 hello/본문 기준 조회는 제외했습니다. 저장소에서 npm run benchmark:files로 같은 조건을 재현할 수 있습니다.
SDK는 안정 1.x API를 제공합니다. 기존 0.3.2·0.4·0.5·0.6 클라이언트는 0.7 호스트에서도 원래 API를 사용할 수 있습니다. 연결한 독립 SDK 클라이언트에서 이 리비전 API를 사용하세요. 전체 계약과 이전 방법은 파일 리비전 안내를 참고하세요.
대용량·바이너리 작업 결과
SDK 0.7.0은 선택 기능으로 바이너리 결과 파일을 지원합니다. 신뢰하는 명령이 이미 생성한 워크스페이스 파일을 등록하면 호스트가 SHA-256과 크기를 기록합니다. 클라이언트는 최대 64 KiB씩 읽고 Node 다운로드 도우미는 중단된 파일을 이어받아 전체 결과를 검증합니다. 등록 파일의 최대 크기는 1 GiB이며 기존 UTF-8 파일·텍스트 결과 API의 256 KiB 제한은 유지됩니다.
서버가 소유한 플러그인 호스트에서 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};
});
이미 승인하고 연결한 client와 기존 jobId를 사용하세요. 저장 대상은 호출자가 관리하는 실제 디렉터리 안의 절대 경로여야 합니다. 도우미는 destination + “.dds-part”에 쓰며 기존 최종 파일을 덮어쓰지 않습니다.
Javascript
import {downloadJobBinaryArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const capabilities = await client.getBinaryArtifactCapabilities();
if (!capabilities.enabled) throw new Error('Binary results are not enabled');
const reference = await client.getJobBinaryArtifact(jobId, 'trace');
const receipt = await downloadJobBinaryArtifact(client, reference, {
destination: absoluteDownloadPath, resume: true,
signal: abortController.signal,
onProgress({receivedBytes, totalBytes}) {
console.log(receivedBytes, totalBytes);
},
});
console.log(receipt.verified, receipt.revision);
작업·워크스페이스·호스트 세대가 포함된 {jobId, scope, artifact} 참조 전체를 보관하세요. 중단 후 같은 호스트 세대에 명시적으로 다시 연결하고 저장한 참조와 resume: true를 사용하면 기존 부분 파일을 다시 해시하고 남은 부분만 요청합니다. 조각·전체 수신 데이터·실제 임시 파일의 SHA-256을 검사한 뒤 최종 파일을 만듭니다. 동기식 진행률 콜백은 검증 완료를 뜻하지 않으며 최종 반환값의 verified: true가 완료를 확인합니다. 손상된 부분 파일은 직접 정리하거나 새 저장 경로를 선택해야 합니다.
listJobBinaryArtifacts(jobId)는 기존 텍스트 결과와 별도로 등록된 바이너리 메타데이터를 반환합니다. readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?})는 정규 base64·조각 SHA-256·정확한 범위·EOF 표시를 반환합니다. /artifacts의 decodeBinaryArtifactData로 Uint8Array를 얻습니다. 브라우저 소비자는 전체 파일 해시를 별도로 검증해야 하며 조각 검사만으로 완성 파일과 참조의 일치를 확인할 수는 없습니다.
바이너리와 텍스트 결과는 작업당 16개 등록 한도와 ID 공간을 공유합니다. 바이너리 등록·읽기는 호스트/워크스페이스당 4개, Node 다운로드는 프로세스당 4개로 제한합니다. Node 다운로드의 timeoutMs는 전체 기한으로 기본·최대 30분이고 requestTimeoutMs는 요청당 기본 5초·최대 30초입니다. 최종 파일 생성에는 NTFS·ext4 같은 하드링크 지원 파일시스템이 필요합니다. 호출자가 관리하는 디렉터리와 신뢰하는 작성자를 사용하세요. 파일 검사는 호스트 프로세스의 운영체제 권한으로 수행됩니다.
선택 메서드 artifacts.capabilities·artifacts.list·artifacts.read는 기존 v1 hello·작업 snapshot·이벤트를 유지합니다. 0.7 이전 호스트는 기능 비활성으로 처리하며 클라이언트는 그 결과와 읽기·실행에 대한 명시적 제어를 유지합니다. 인증·잘못된 응답·전송 오류는 그대로 실패합니다. 재연결·권한 회수·작업 만료·호스트 세대 변경은 이전 호출을 무효화합니다. 작업은 기존처럼 종료 작업의 마지막 이벤트부터 15분간 메모리에 보관합니다. 취소된 작업에는 일부 도구 출력이 남을 수 있으므로 작업의 최종 상태로 성공을 확인하세요. 이는 기본 실시간·원본 참조 API의 동작입니다. 아래의 별도 보관 API는 재시작 후에도 파일을 유지합니다.
npm run example:artifacts는 실제 2 MiB 파일의 중단·재연결·남은 부분 이어받기를 실행하며 npm run benchmark:artifacts는 8 MiB를 사용합니다. Windows 로컬 측정에서 8,388,625바이트를 129개 조각 요청으로 전송했고 65,536바이트부터 이어받아 최종 SHA-256을 검증했습니다. Base64 인코딩으로 JSON 응답 본문은 총 11,257,419바이트였습니다. 전송 중 메모리 사용을 제한하고 받은 파일 전체를 검증합니다. 전체 계약은 바이너리 결과 안내를 참고하세요. 독립 SDK 클라이언트와 호스트에서 이 전송을 실행하세요.
작업 저장·이력 조회와 명시적 재실행
SDK 0.8.0은 workspace 외부의 운영자 소유 디렉터리에 선택적으로 작업을 보관합니다. 절대 경로·고정 workspace 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()는 요청한 기록의 저장을 기다릴 뿐 작업 완료를 기다리지 않습니다. 복구 응답은 현재 연결과 원래 실행 scope를 구분하고 live·completed·interrupted·expired·missing·corrupt·unsupported를 반환합니다. 중단된 작업은 자동 재실행하지 않고 마지막 저장 이후 불확실성은 unrecordedTail로 표시합니다.
Javascript
const capabilities = await client.getJobStorageCapabilities();
const query = {limit: 16, commandId: 'analyze'};
const page = await client.listJobHistory(pluginId, artifactSha256, query);
const prior = await client.recoverJob(pluginId, previousJobId, artifactSha256);
const attempt = await client.retryCommandJob(pluginId, previousJobId,
reviewedFreshInput, artifactSha256, {jobId: crypto.randomUUID()});
상태·복구 상태·명령·시작 시간·이전 실행으로 이력을 조회합니다. 최대 32개씩 시작 시간 내림차순, 작업 ID 순서로 반환합니다. 커서는 60초 동안 같은 조건과 항목 구성을 유지합니다. 새 작업은 기존 페이지에 추가되지 않고 삭제·권한 회수된 항목은 제외되며 만료는 표시합니다. 재시작하면 커서를 새로 얻어야 합니다. artifactCount·snapshotCount·resultAvailability는 저장된 참조 정보이며 현재 파일 검증 증거가 아닙니다.
명시적 재실행에는 새 작업 ID·새로 검증한 입력·현재 승인된 동일 패키지·사용 가능한 명령이 필요합니다. attemptOf가 원래 작업을 가리키며 기존 기록은 바꾸지 않습니다. 같은 ID·입력·부모 작업·기한으로 다시 요청하면 재시작 이후에도 보관된 시도를 반환합니다. 삭제·만료된 기록은 이 중복 실행 방지 근거를 제공할 수 없습니다. 대기 요청을 취소한 뒤에도 이미 수락한 실행은 계속될 수 있습니다. 재시도를 결정하기 전에 새 작업 ID로 상태를 조회하세요.
기본적으로 원시 입력·결과 본문·진행 메시지·파일 표시명은 보관하지 않고 로그는 마스킹합니다. 운영자의 결정적인 마스킹 함수가 검토한 텍스트만 별도로 저장할 수 있습니다. 토큰·비밀 입력·이전 동의를 복원하지 않으며 현재 workspace·플러그인 식별자·읽기 권한과 당시 모든 권한을 다시 확인합니다. 작업 메타데이터의 기본 한도는 256개·64 MiB·24시간, 최대 기간은 7일입니다. 제거·정리는 명시적 호스트 작업입니다.
로컬 저장소는 단일 작성자 잠금과 workspace·루트 식별자·메타데이터 검증을 사용합니다. 명시적 잠금 복구는 같은 머신에서 확실히 종료된 PID만 허용합니다. 알 수 없거나 손상된 파일은 운영자가 확인해야 합니다. Windows 파일 동기화·이름 변경은 검증한 프로세스 종료 후 복구에 사용되며 실제 영속성은 파일시스템과 저장장치의 동작을 따릅니다. 작업 저장, 이력과 durable-jobs 예제를 참고하세요.
결과 보관과 재시작 후 다운로드
파일 저장소를 켜면 await job.addArtifact() 또는 job.addBinaryArtifact()가 파일 전체를 복사·검증한 뒤 등록합니다. 텍스트는 256 KiB, 바이너리는 최대 1 GiB입니다. 수신 데이터와 실제 임시 파일 모두 SHA-256을 검사합니다. 취소·디스크 부족·원본 변경·부분 쓰기는 사용할 수 있는 결과로 공개하지 않습니다. 파일 저장 후 작업 기록 전 강제 종료되면 운영자가 확인할 미참조 파일이 남을 수 있습니다.
Javascript
import {downloadStoredJobArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const list = await client.listStoredJobArtifacts(pluginId, jobId, artifactSha256);
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, artifactSha256);
const receipt = await downloadStoredJobArtifact(client, reference, {
destination: absoluteOutputPath, resume: true,
});
console.log(receipt.storage, receipt.snapshotId, receipt.verified);
목록은 원본 참조와 snapshot 메타데이터를 나누고 retained·expired·missing·corrupt·unsupported를 표시합니다. retained는 메타데이터 상태이며 getStoredJobArtifact()가 메타데이터와 보관 파일 전체를 검증한 뒤 현재 세대의 새 참조를 반환합니다. 각 읽기에서 현재 권한과 파일 식별자를 다시 확인합니다. 원본 삭제는 보관본에 영향을 주지 않고 보관본 누락 시 원본으로 자동 전환하지 않습니다. 텍스트 보관본은 client.readStoredJobArtifactText(textReference)로 읽습니다.
재시작 뒤 현재 권한으로 다시 연결하여 새 참조를 얻으세요. snapshot ID·store ID·해시는 유지되지만 이전 세대 참조는 거부됩니다. resume: true는 저장된 .dds-part 부분 파일을 해당 보관본과 다시 비교하고 조각·전체 임시 파일을 검증한 뒤 기존 대상 파일을 덮어쓰지 않고 완성합니다. 파일뿐 아니라 작업 메타데이터도 유효하게 보관되어야 합니다. 브라우저 소비자는 전체 해시를 검증해야 하며 아래 Worker 어댑터가 명시적인 브라우저 디스크 이어받기를 제공합니다.
파일 보관 기본값은 256개·256 MiB·24시간이고 총 용량 최대 4 GiB·기간 최대 7일입니다. 한 번에 최대 64 KiB씩 동시 4개 읽기를 허용합니다. inspect()로 사용량·만료 시각·손상·orphan을 조회하고 remove(snapshot)·prune()으로 명시적으로 제거·정리합니다. 진행 중인 작업과 각 읽기 요청은 보호하지만 분할 요청 사이에 만료·삭제되면 다음 읽기가 중단됩니다. 선택적 orphan 정리는 알려진 단일 링크 파일만 제거하며 손상·불명확한 항목은 별도 확인해야 합니다.
파일 보관은 로그 마스킹과 별도로 실제 프로젝트 내용을 저장하므로 운영자가 선택해야 합니다. 재시작 뒤에도 현재 플러그인·명령·패키지 해시·workspace와 당시 권한을 확인합니다. 유지보수 작업을 마친 뒤 server.close(), artifacts.close(), store.close() 순서로 기다리며 닫으세요. 독립 SDK 호스트에서 파일 보관 기능을 설정하고 사용하세요.
npm run example:stored-artifacts는 실제 자식 프로세스 재시작·원본 삭제·검증된 부분 다운로드 이어받기·이력·명시적 재실행을 확인합니다. npm run example:durable-jobs는 강제 프로세스 종료도 다룹니다. 전체 계약은 결과 보관을 참고하세요. 0.7 이하의 알려진 호스트는 알 수 없는 메서드를 보내지 않고 저장 기능 비활성으로 처리합니다. 기존 실시간·원본 참조 API의 동작은 유지됩니다.
프로젝트 변경 감시
운영자가 서버의 projects 옵션과 허용 root를 직접 지정합니다. 기본값은 비활성이며 구형 0.3~0.8 SDK 서버에는 새 기능 조회를 보내지 않고 미지원으로 표시합니다. 지원 프로필은 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();첫 이벤트는 전체 snapshot입니다. 이후 changes는 기존 revision을 기준으로 한 변경 목록이며, 이벤트 손실·초기 스캔 중 변경·불완전 스캔·느린 소비자 큐 초과는 전체 snapshot을 포함한 resync와 사유로 표시합니다. 이름 변경은 삭제/생성으로 표현할 수 있습니다. 각 파일은 관측 시점에 개별 검증합니다. 결과 뷰는 이 표본들을 모으므로 중간 쓰기는 합쳐져 나타날 수 있습니다.
구독은 서버·클라이언트당 최대 4개, 이벤트 큐는 구독당 최대 4개입니다. 기본 유휴 임대는 30초이며 이후 읽기는 not_found가 될 수 있습니다. 길게 멈춘 뒤에는 새 iterator를 만들어 초기 snapshot을 받으세요. break/return/취소/dispose는 구독을 해제하며 연결이 끊겨 종료 요청이 전달되지 않으면 임대 만료가 남은 자원을 정리합니다.
기본 스캔 한도는 깊이 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는 그 root 기준 상대 경로입니다. 검색 패턴에는 리터럴 텍스트와 문서화된 제한 glob 문법을 사용하세요. 대소문자를 무시할 때는 ASCII A–Z만 접어 원문 UTF-16 위치를 보존합니다.
const tree = await project.listTree({root: 'rtl', pageSize: 16});
const names = await project.searchFiles({root: 'rtl', query: '**/*.sv', mode: 'glob'});
const query = {root: 'rtl', include: ['**/*.sv'], query: 'module ', pageSize: 16};
let page = await project.searchText(query);
for (const item of page.items) {
console.log(item.entry.path, item.entry.revision, item.match.range, item.match.snippet);
}
if (page.nextCursor) {
const next = await project.searchText({...query, cursor: page.nextCursor});
console.log(next.stale, next.items.map(item => item.state));
if (next.nextCursor) await project.releaseProjectQuery(next.nextCursor);
}
if (tree.nextCursor) await project.releaseProjectQuery(tree.nextCursor);
if (names.nextCursor) await project.releaseProjectQuery(names.nextCursor);검색 결과에는 원본 내용 SHA-256, 0부터 시작하는 UTF-16 범위, 제한된 snippet이 포함됩니다. cursor는 최초 결과의 구성원을 고정하고 최대 60초 동안 같은 조회에만 사용합니다. 다음 페이지는 현재 내용을 다시 확인해 current/changed/missing/unverified를 표시하며, 새 파일은 새 조회에서만 포함됩니다. 원래 match와 revision은 바꾸지 않습니다.
텍스트 파일은 최대 256 KiB, 검색어는 256 UTF-16 단위, snippet은 512 단위입니다. 기본 최대 결과는 256개(설정 상한 512), 기본 페이지는 32개(상한 64), 기본 응답은 64 KiB(상한 128 KiB)입니다. 바이너리·잘못된 UTF-8·바이트/깊이/시간/응답 제한은 결과의 불완전 여부와 사유로 드러납니다. 동시에 2개 조회와 8개 보관 cursor view만 허용하며 필요가 끝난 cursor는 명시적으로 해제합니다.
초안 보존과 재접속
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이 다르면 기존 cursor를 해제하고 같은 root/filter로 다시 조회하세요. 감시는 edit.snapshot이나 호출자가 보관한 draft를 변경하지 않습니다. 외부 수정·삭제·이동 후 저장은 기존 CAS 조건으로 충돌을 알리며, 사용자가 reload·병합·별도 저장 중 처리 방법을 선택합니다.
클라이언트는 연결 세대·root/filter·query hash·페이지 위치·snapshot SHA-256·이벤트 연속성을 검사합니다. 권한 철회·연결 해제·재접속 뒤 늦은 응답은 폐기합니다. 구독 cursor와 검색 cursor는 서로 다르며 재접속 시 자동 재사용하지 않습니다. 서버의 revokeProjects()는 관련 작업을 종료하고 새 서버 세대에서 다시 설정해야 합니다.
npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browser독립 설치 패키지의 Node 예제는 생성·검색·외부 변경·초안 보존·CAS 충돌·재접속을 검증합니다. 브라우저 예제는 출력된 loopback URL에서 Run scenario를 눌러 같은 흐름을 확인합니다. 임시 작업공간만 사용하고 서버를 종료하면 해당 임시 데이터가 정리됩니다. HTTP 요청 기본 제한은 5초이므로 더 큰 스캔에는 클라이언트·서버 제한을 명시적으로 조정하세요.
Project observation · Tree/search contracts · HTTP project tools
브라우저 결과 스트리밍과 검증
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);브라우저 helper는 64 KiB 이하 청크를 하나씩 받고 선택 sink의 저장을 기다린 뒤 다음 청크를 읽습니다. 범위·identity·base64·청크 해시와 전체 수신 해시를 확인하고, readback sink는 저장 파일 전체를 다시 읽어 검증합니다. 두 전체 해시가 일치해야 stored이며 재읽기가 없으면 received와 storedSha256: null입니다. 바이트 진행률 100%만으로 완료를 표시하지 않습니다.
파일 handle·OPFS 디렉터리와 필요한 권한은 앱이 선택합니다. 앱이 선택과 권한을 관리하며 명시적으로 선택한 저장 위치와 승인된 접근을 SDK에 전달합니다. 비동기 writable sink는 close 전 staging을 유지하며 확정 전 오류에는 버립니다. 새로고침 후 이어받기에는 아래 Worker adapter를 씁니다. 파일당 1 GiB·직접 전송 최대 4개·전체 30분 기한을 적용합니다.
선택 파일 업로드
import {uploadFile} from '@altifigence/dds-plugin-sdk/uploads';
import {createBrowserUploadSource} from '@altifigence/dds-plugin-sdk/uploads-browser';
// The operator separately configures uploads.directory/principalId/roots/fileSystem
// on the Node workspace server, and grants workspace.write to this pinned plugin.
const source = createBrowserUploadSource(selectedFile);
const status = await uploadFile(client, source, {
uploadId: crypto.randomUUID(), pluginId, artifactSha256: pluginPin,
path: 'input/trace.bin', expectedRevision: null, signal,
});
if (status.state === 'committed' && status.commitReceipt.verified) {
showCommittedUpload(status.commitReceipt);
}
// To recover a previously selected upload ID, pass the same specification and
// source with recover: true. The helper queries current authority and rehashes it.업로드는 기본 비활성입니다. 운영자가 로컬 Node workspace·분리 staging 디렉터리·허용 root·principal을 설정하고 정확한 archive pin의 선택 플러그인에 workspace.write를 승인합니다. helper는 시작 전에 선택 source 전체를 해시합니다. 서버는 순차 64 KiB 청크·정확한 중복·전체 해시를 검증하고 대상 revision 조건을 확인한 뒤 확정합니다. staging 바이트는 일반 workspace 목록에 나타나지 않습니다.
expectedRevision: null은 대상이 없어야 하고 SHA-256 값은 현재 대상 해시가 일치해야 합니다. 취소는 서버가 확인한 prefix를 보관합니다. 명시적 recover는 현재 권한으로 조회하고 같은 source·specification을 검증한 뒤 일치하는 prefix부터 재개합니다. commit 응답 유실은 조회 전까지 불확실하며 자동 재확정이나 rollback 근거가 아닙니다. 상한은 파일당 1 GiB·store 4 GiB·활성 세션 4개이며 기본 한도는 더 작습니다. 기존 0.3~0.9 host에는 새 메서드 probe 없이 업로드 비활성을 반환합니다.
파일 전송 큐
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();호출자 소유 큐에 upload·live download·stored download를 함께 등록합니다. 보관 작업 32개·동시 단계 4개·연결별 동시성·64~256 KiB 청크 예약·전송 속도·재시도를 제한합니다. 포화된 연결은 건너뛰고 우선순위 앞당김을 제한해 작은 실행 가능 작업의 기아를 막습니다. pause는 현재 단계의 결과를 받은 뒤 기다리므로 저장 잠금을 보유할 수 있습니다. 전체 기한에는 대기와 pause도 포함됩니다.
자동 재시도는 멱등성이 확인된 동일 청크 작업 중 SDK가 확인한 429/503·네트워크 단절·요청 timeout에만 backoff·jitter와 횟수 한도로 적용됩니다. begin/commit·권한·checksum·범위·source/sink 오류는 호출자가 명시적으로 검토하도록 제어를 반환합니다. acknowledged/transferred/attempted/retried/resumed/remaining 바이트를 구분하고 검증된 receipt만 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가 필요합니다. 새로고침 후 호출자가 디렉터리와 partial UUID를 다시 선택하고 현재 권한으로 저장 결과 참조를 얻습니다. sink는 정해진 data/metadata 파일 두 개에 전체 snapshot identity·만료·현재/이전 prefix 해시를 저장하며 token·grants·이전 연결 scope는 보관하지 않습니다. 각 데이터 청크를 flush한 다음 작은 metadata stream을 close합니다.
sink와 helper가 각각 prefix를 다시 해시합니다. 기록된 prefix가 일치한 경우에만 미기록 tail을 정리합니다. metadata가 실제 파일보다 앞서면 이전 checkpoint의 바이트와 해시가 일치할 때만 되돌립니다. 손상·삭제·만료·다른 snapshot은 자동 재시작 없이 거부합니다. origin 공통 독점 잠금은 다른 탭을 거부하고 재읽기까지 유지되며 close·Worker 종료 후 해제됩니다. 그 뒤에도 명시적 복구가 필요합니다.
로컬 metadata는 16 KiB·열린 sink 세션은 4개까지입니다. 보관 기본값은 1시간, 최대 24시간이며 host snapshot 만료를 넘지 않습니다. 브라우저가 quota·저장소 삭제를 관리하며 같은 origin의 스크립트가 저장소 접근 권한을 공유합니다. 복구는 이 저장소 규칙 아래 기록한 checkpoint를 사용합니다. Windows Chromium 154에서 취소·새로고침·host 재시작·두 탭 충돌·소유 탭 종료 후 복구와 전체 저장 해시를 확인했습니다. 이 검증 결과는 해당 브라우저와 운영체제 조합을 대상으로 합니다.
npm run example:browser-artifacts
npm run example:uploads-browser
npm run example:transfer-queue-browser
npm run example:browser-resumeStreaming · Uploads · Transfer queue · Worker recovery
서명 도움말과 자동완성 지원
manifest v2에 필요한 signature-help·completion-resolve·completion-snippets를 선언합니다. completion 확장에는 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);앱이 현재 위치와 호스트를 제공합니다. prepare는 문서·파일을 쓰지 않고 미리보기 데이터만 반환합니다. 서명은 최대 16개·서명당 인자 64개와 UTF-16 인자 라벨 범위를 지원합니다. 자동완성 resolve는 제공자 데이터를 숨기고 호스트의 일회용 토큰을 반환하며 선택 라벨·삽입 문자열·범위를 유지합니다. 토큰은 제공자·scope·문서에 묶이며 60초·128개·4MiB·실제 resolver 4개로 제한됩니다. 문서나 제공자가 바뀌면 폐기합니다.
스니펫은 $n, ${n}, ${n:literal}, $0와 문서화된 escape·반복값·탭 이동점만 지원합니다. 변수·중첩·choice·transform·실행 명령을 거부하고 UTF-16/CRLF 경계·겹치는 추가 편집을 검사합니다. 제공자는 호스트 프로세스의 운영체제 권한으로 실행되는 신뢰한 코드입니다. 취소를 무시하는 실제 작업은 종료될 때까지 동시성 슬롯을 점유합니다.
검토한 워크스페이스 편집과 이름 변경
prepare-rename은 검증된 범위·placeholder 또는 null, rename은 WorkspaceEdit 제안 또는 null을 반환합니다. 제안은 중복되지 않는 상대 파일 경로의 edit·create·move·delete를 지원합니다. 원본 SHA-256·대상 부재·보호 경로·UTF-16 범위와 한도를 검사합니다. 언어 capability는 제안을 승인하며 워크스페이스 클라이언트가 별도 승인된 파일 접근과 변경 권한을 제공합니다.
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);호출자는 연결·승인된 workspace client와 신뢰한 journal을 사용합니다. 미리보기는 전체 before/after와 digest를 포함하고, 적용에는 검토한 planId/digest 및 현재 true를 반환하는 host 정책이 필요합니다. 전체 파일 사전 검사를 거친 뒤 각 작업에서 기존 파일별 CAS와 현재 write/manage 권한을 확인합니다. journal은 각 변경 전 intent와 변경 후 receipt를 저장·재읽기합니다. 충돌·불확실성은 이후 쓰기를 중단합니다. 각 파일은 자체 CAS 작업으로 확정되므로 중단된 계획에도 이미 확정된 파일이 있을 수 있습니다.
선택 workspace-edits-node adapter는 지정 workspace 밖에 제한된 journal을 저장하고 디렉터리 identity·단일 writer 잠금·일반 파일·checksum checkpoint를 검사합니다. 프로세스 종료 뒤 recoverStaleLock은 명시적으로 선택하며 죽은 소유자임이 확인될 때만 회수합니다. 복구는 현재 바이트로 applied/not-applied/conflicted/unknown을 보고하고 다음 동작은 호출자가 선택합니다. 보상은 새 역방향 제안을 만들고 다시 검토해야 합니다. Windows에서는 어댑터가 파일 동기화와 이름 변경 작업을 수행합니다. 보고한 내구성 검사는 프로세스 종료와 복구를 대상으로 하며 실제 영속성은 파일시스템과 저장장치의 동작을 따릅니다. 변경 32개·편집 1,000개·파일당 256KiB·미리보기 8MiB·journal 보관 계획 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에는 path와 tabSize/insertSpaces 옵션이 필요하며 범위 포맷에만 선택 범위를 전달합니다. 결과는 null 또는 현재 snapshot 해시를 가진 현재 파일 편집 한 개입니다. 범위 편집은 선택 안에 머뭅니다. endOfLine의 preserve·lf·crlf는 삽입 텍스트에 적용되고 편집하지 않은 바이트는 유지됩니다. 동일한 내용은 null로 정규화하며 prepareFormatting은 쓰기를 하지 않습니다.
호스트는 액션 요청·resolve 토큰을 승인된 진단 revision과 현재 snapshot에 묶습니다. 이후 진단 게시·문서 변경·제공자 해제는 이전 선택을 무효화하고, 늦게 끝난 이전 진단 호출은 더 최신 bundle을 덮어쓰지 않습니다. 액션은 최대 100개이며 일반 라벨·제한된 진단 참조·편집 제안·비공개 resolve 데이터 또는 비활성 이유를 담습니다. 알 수 없는 명령·URL·shell 필드는 거부합니다. 액션 편집은 선택 범위 밖도 포함할 수 있으므로 전체 제안을 검토해야 하며 포맷·액션이 자체 쓰기를 승인하지 않습니다.
의미 강조·접기·힌트·심볼
import {decodeSemanticTokens} from '@altifigence/dds-plugin-sdk';
const tokens = await host.requestLanguage('semantic-tokens',
previousResultId ? {previousResultId} : {});
host.validateLanguageResult(tokens); // actual current host-owned result only
renderWhitelistedTokens(decodeSemanticTokens(tokens.data, currentDocumentText));
const folds = await host.requestLanguage('folding-ranges', {});
const hints = await host.requestLanguage('inlay-hints', {range: visibleRange});
const symbols = await host.requestLanguage('document-symbol-tree', {});
for (const result of [folds, hints, symbols]) host.validateLanguageResult(result);
// Render labels as text nodes. Release results when no longer retained.
host.releaseLanguageResult(tokens);의미 토큰은 고유 이름·호스트 소유 스타일 키 9개의 legend와 토큰별 정수 5개(줄/시작 차이·UTF-16 길이·타입 인덱스·modifier bit)를 사용합니다. 토큰의 겹침·surrogate 분할·줄 교차·문서 밖 위치를 거부합니다. 호스트는 항상 전체 정규화 배열과 호스트 UUID, full/delta/fallback 상태를 반환합니다. 별도 semantic-tokens-delta capability가 provideDelta를 활성화하며 이전 제공자 데이터에 연결합니다. 캐시는 identity·토큰을 보관하고 이전 문서 본문은 보관하지 않습니다.
캐시 기준은 제공자·scope·URI·언어에 묶이고 최대 8개·4MiB·60초를 적용합니다. 정상적으로 증가한 문서 버전은 증분 기준을 유지할 수 있지만 이전 결과 표시는 즉시 stale입니다. 기준 소실·만료·null delta·다른 제공자 기준 ID에는 원래 기한 내 전체 요청을 한 번만 허용합니다. 잘못된 데이터·제공자 오류에는 재시도하지 않습니다. 비활성화·등록 해제·문서 교체는 해당 기준을 지웁니다. 표시 직전에 validateLanguageResult를 호출하며 복사·해제·stale 객체는 거부합니다.
의미 토큰 20,000개·타입 64개·modifier 16개·delta edit 64개를 제한합니다. 접기는 1,000범위·깊이 32이며 교차를 거부합니다. 인레이 힌트는 요청 범위 안의 한 줄 일반 라벨 1,000개까지입니다. 계층형 심볼은 전체 1,000개·깊이 16이며 자식·selection 포함과 형제 정렬·비겹침을 검사합니다. 기존 flat document-symbols 계약은 유지됩니다. 브라우저 예제에서 full/delta/fallback·접기·이동·lifecycle을 실행하며 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-browserAssistance · Reviewed edits · Formatting/actions · Display
타입 설정과 비밀 참조
/settings는 플러그인별 운영자 소유 메모리 저장소를 제공합니다. 버전이 있는 정의에 키·데이터 스키마·기본값·허용 user/workspace 범위·표시 정보를 선언합니다. 유효 값은 default < user < workspace 순서로 키 전체를 교체합니다. read(workspaceId)는 변경 불가 values·sources와 저장소 공통 revision을 반환합니다. 중첩 객체를 재귀 병합하지 않으며 기본값도 없는 값은 생략됩니다.
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)는 새 상태를 검증한 뒤 revision이 같을 때만 확정합니다. 실패·취소·시간 초과는 기존 정의·상태를 보존합니다. export/import는 일반 데이터이며 영속화·암호화는 운영자가 담당합니다. 키 64개·workspace 계층 32개·상태 1MiB·실제 migration 1개를 제한합니다.
workspace 플러그인은 settings와 settings.read를 선언하고 운영자는 해당 저장소와 권한을 연결합니다. context.settings는 플러그인·선택 workspace에 묶인 읽기 전용 API입니다. /secrets resolver는 별도로 플러그인·workspace·명령 목록·수명에 묶인 불투명 참조를 발급합니다. manifest의 secrets.resolve 선언과 host 승인이 필요합니다. 입력 필드는 type: object 및 format: dds-secret-reference로 선언합니다. 일반 문자열이나 닮은 객체는 비밀 접근 권한을 주지 않습니다.
검증된 입력의 참조만 명령의 options.secrets.withSecret에서 사용할 수 있습니다. 실행마다 새 ID를 만들고 조회·callback 전후에 scope·만료·철회·현재 승인을 확인합니다. callback은 undefined를 반환하고 취소·종료 때 지워지는 바이트 복사본을 받습니다. 제공자 오류는 정제합니다. 해당 승인이 필요한 효과보다 먼저 lease를 얻으세요. 기본 수명은 60초·최대 1시간이며 참조 128개·실제 lease 8개·비밀 바이트 16KiB를 제한합니다. 신뢰한 프로세스 내 코드는 호스트 프로세스의 운영체제 권한으로 실행되며 복사본을 보관할 수 있습니다. 실제 값을 설정·bundle·로그·결과에 넣지 마세요. 민감 데이터를 다룰 때는 임의 앱 문자열도 명시적으로 분류하세요.
구조화된 명령 스키마와 폼
명령은 schemaVersion: 1 envelope의 inputSchema·outputSchema를 선언할 수 있습니다. 기존 primitive parameters도 유지하며 parameters와 inputSchema의 동시 선언은 거절합니다. host는 handler·job 시작 전에 입력 검증·기본값 적용을 하고 성공 발표 전에 출력을 검증합니다. 출력에는 기본값을 적용하지 않습니다. 새 schema/display metadata에는 0.12를 이해하는 peer가 필요합니다. 구형 strict validator는 새 필드를 거절하며 기존 정의의 동작은 유지합니다.
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);제한된 subset은 닫힌 객체·배열·문자열·유한 수·안전 정수·boolean·null·primitive enum·범위·검증된 기본값을 지원합니다. 알 수 없는 키워드·원격 참조·정규식·union·자동 변환·accessor·사용자 prototype을 거부합니다. 스키마는 32KiB·깊이 8·노드 128개, 값은 64KiB까지입니다. 명령 전체의 metadata 예산은 16KiB입니다. 로컬 DataValidationError는 code·reason과 /input/options/names/0 같은 알려진 필드 경로를 반환합니다. HTTP·job 오류는 거부한 값 없이 안전한 코드만 노출합니다.
describeDataForm은 경로·타입·선택지·기본값·필수 여부·비밀 참조 힌트를 반환합니다. 공통 display metadata는 일반 label/help/order 및 접근성 이름·설명·키보드 힌트를 담습니다. 렌더링·상호작용은 host가 구현합니다. 스키마는 일반 폼 데이터를 제공하며 렌더링·자원 접근·명령 실행은 호스트가 명시적으로 구현합니다.
다국어와 접근성 메타데이터
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 base tag와 순환 없는 명시적 fallback을 사용합니다. 선호 언어 최대 8개를 exact tag·상위 tag·기본 언어 순서로 협상합니다. 기본 언어가 전체 키를 정의하며 번역은 키를 생략할 수 있지만 새 키를 만들 수 없습니다. 키별 조회는 지정한 fallback 순서 뒤 기본값을 사용합니다. 번역·인자는 정확히 같은 {name} placeholder 집합을 가져야 합니다. ICU 표현식 없는 일반 문자열 치환입니다. resolveMessage가 실제 출처 locale·direction을 반환하므로 RTL 페이지의 영어 fallback에는 lang=en·dir=ltr을 적용할 수 있습니다.
숫자는 decimal/percent, 날짜는 명시적 epoch와 기본 UTC, 복수형은 호출자가 문구를 선택할 Intl cardinal/ordinal category를 지원합니다. Intl 데이터와 지원 여부는 host 책임입니다. validateLocalizedSurfaces는 manifest·명령·설정·schema 키와 theme display sidecar를 검사하고 최종 표시 길이·누락 번역을 확인합니다. 기존 theme JSON/XML 호환성은 유지합니다. 카탈로그는 언어 32개·키 256개·256KiB로 제한하며 정적 라벨에는 placeholder를 쓸 수 없습니다.
/accessibility 도우미는 누락된 이름·정규화한 단축키 중복·light/dark theme의 명시적 불투명 색상 쌍 대비를 보고합니다. 보고서는 검사 힌트로 사용하며 OS 단축키 등록과 앱 접근성 평가는 호스트가 관리합니다. 독립 예제에는 EN/KO·일부 아랍어·긴 라벨 fixture가 있습니다. 범위별 설정·거절/철회된 참조·잘못된 필드·Ctrl+Enter·대기 중 언어 전환을 실행하며 desktop/mobile 및 light/dark 배치를 확인했습니다.
npm run example:configuration
npm run example:configuration-browser개발 템플릿과 코드 생성
6개 템플릿·정확한 archive 의존성·생성 검토·충돌 보존·doctor 검사를 제공합니다.
결정적 테스트와 재생
명시한 합성 fixture·가상 시간·장애·제한된 해시 trace·자원 정리를 제공합니다.
로컬 진단과 디버깅
선택형 로컬 profile과 임시 loopback·전체 기한이 있는 신뢰한 자식 디버거를 제공합니다.
호스트 적합성 검사
18개 버전형 프로필이 supported·unsupported·failed를 구분하며 custom adapter 권한은 명시적으로 유지합니다.
SDK 지원과 이전
export 목록·안정/선택/실험 정책·정확한 peer·런타임 날짜·이전 예제를 확인하세요.
릴리스 수용 검증
릴리스의 복합 장애 workload와 실측 성능 기준은 독립 SDK의 기능 동작을 설명합니다.
1.1 의존성·출처·업데이트 도구
1.1.0은 검토한 의존성의 결정적 오프라인 번들·CycloneDX SBOM·운영자 소유 Ed25519 키의 분리 서명·digest에 고정한 승인/버전 교체/롤백·명시적 upstream 변경 비교를 제공합니다. Node 전용 5개 entry point와 types/schemas/독립 예제를 포함합니다. 호스트가 서명 검토 후 실행을 명시적으로 승인하고 기존 작업은 원래 hash를 유지합니다. 운영자가 배포 경로를 선택하고 독립 SDK 도구로 활성화·롤백·upstream 비교를 호출합니다.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjs1.2 워크플로·캐시·도구 스트림·LSP
1.2.0은 검토한 명령의 DAG·단계별 job/grants·영속 checkpoint와 명시적 새 attempt 재개, 실제 파일 내용 기반 결정적 cache와 증분 실행, 제한된 UTF-8/JSONL/text 도구 스트림, 선택적 stdio LSP 3.17 브리지를 제공합니다. 새 export 7개를 포함해 50개 export·107개 schema·타입·독립 설치 예제를 제공하며 런타임 npm 의존성은 없습니다. tool-streams parser는 브라우저에서도 동작하고 워크플로/저장소/외부 프로세스/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