DDS Plugin SDK
安装公开的 DDS Plugin SDK 1.2,并使用工作流、缓存、工具流、LSP 及稳定版 API。
以下用户工作区示例说明了明确连接且由客户控制的开发主机。WSL 是这些示例的可选主机。常规 Digital Design Studio Windows 应用程序使用原生 Windows 文件和共享 UI/WASM 运行时。操作者为选定 SDK 主机配置发现、权限及插件功能;托管的 Cloud 引擎作业使用自己的执行模型。
1. 安装 SDK
DDS Plugin SDK 1.2.1 提供 JavaScript API、TypeScript 声明、语言提供器、主题、工作区工具和命令作业。可选持久存储增加作业历史、明确重试,以及经过验证的文本/二进制快照,即使源文件被删除或进程重启也可保留。请使用 Node.js 22 或 24。从官方 GitHub 发布页面安装稳定版 SDK。对于独立命令插件,安装后使用开发工具:
1.0.0 发布稳定 SDK API、18 个宿主一致性配置、支持/迁移政策,以及经过测量的混合工作负载检查。新插件使用 >=1.0.0 <2.0.0。已发布的功能验证覆盖 SDK API、宿主一致性和混合工作负载。请使用这些结果评估发布检查所验证的 SDK 行为。
0.13.0 增加六个开发模板、生成类型和模式、确定性测试场景,以及可选本地诊断。打包的 SDK 和生成项目可在源代码树之外运行;合成重放和环回调试需要明确选择。
0.12.0 增加限定范围的类型化设置与明确迁移、执行范围内的秘密引用、结构化命令输入/输出、语言目录和无障碍元数据。公共 SDK 和独立示例检查设置冲突、无效输入、撤销权限及翻译回退。请通过独立 SDK 宿主 API 和独立示例使用这些功能。
0.11.0 增加签名帮助、延迟补全、有界片段、经审查的多文件编辑和重命名、格式化/代码操作、语义令牌、折叠、提示和层次符号。提案在条件应用前经过审查和当前权限检查;显示及应用要求当前文档结果。独立示例在明确配置的公共 SDK 宿主中验证这些功能。
0.10.0 增加浏览器流式下载、所选文件上传、混合传输队列和 Worker OPFS 检查点恢复。传输会检查当前权限、文件身份及分块/整体哈希值,同时区分字节进度与经过验证的存储。请使用这些公共 SDK 示例,配合明确配置的宿主和由应用负责的集成。
0.9.0 为操作者选定的本地目录增加限定范围的项目树、文件名/文本搜索和变更观测。可通过 HTTP 客户端或项目辅助工具使用它们,同时保留编辑快照和未保存草稿。以下项目示例涵盖创建、搜索、外部变更和冲突处理。
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();
}
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();
}
});
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 种可选角色颜色,以及四个明确的度量值。导入之前,将 XML 文件保存到本地。这些原创 SDK 示例采用 Apache-2.0;分享时请保留声明。
请先从 设置 → 常规 → 外观 → 导出 XML 开始以备份你当前的主题。导入下载的 XML,审查草稿,然后选择 应用。放弃更改 会保留已应用的主题。切换浅色/深色外观以审查两种调色板。如需恢复,请选择内置主题或导入已保存的副本。被拒绝的导入会保留当前的主题。
DDS、ALcad、共享编辑器、项目导航、设置和弹窗使用该配置文件中的共享工作台配色。Cloud 和桌面使用相同主题格式;应在各自配置文件中分别导入。gdsBackground 独立控制 GDS 画布。其他设计画布、层和仿真颜色可能有自己的设置。XML 包含此主题配置文件的配色和外观度量值。
元素 | 规则 |
|---|---|
| 仅有一个根元素;去除首尾空白后的名称长度为 1–80 个 UTF-16 代码单元;整个 XML 最多 65,536 个 UTF-8 字节。 |
| 两者均为必需,且各自包含以下六种颜色。 |
| 可选 v2 覆盖项。省略的角色使用该模式的 DDS 默认值。 |
| 可选 v2 数值覆盖项。 |
版本 1 | 仅包含两套配色。现有 v1 文件仍受支持;SDK 导出器输出 v2。 |
必需配色键 | 用途 |
|---|---|
| 工作区外围背景 |
| 项目导航 |
| 工具面板和控件 |
| 主工作区和设置 |
| 主文本 |
| 次要文本 |
可选角色键(28 个) | 用途 |
|---|---|
| 共享搜索背景、文本和占位文本 |
| 兼容字段;当前共享搜索字段不显示边框 |
| 选中行和文本 |
| 编辑器标签页 |
| 工具栏、面板边界和弹窗 |
| 键盘焦点轮廓 |
| 状态颜色和 AI 球背景 |
| 建议与详情背景 |
| 建议、详情和次要文本 |
| 键盘选中的建议 |
| 指针悬停的建议 |
| GDS 查看器画布背景 |
HintsBox 是共享代码建议功能。其颜色设置位于自定义 → 详细颜色和形状 → 提示框,GDS 背景位于显示。请一起编辑三种搜索颜色,确保对比度便于阅读。此片段应放在 v2 主题内;请保留两套完整配色:
XML v2 片段
<tokens mode="dark">
<color key="search" value="#214556"/>
<color key="searchText" value="#e8f4fb"/>
<color key="searchPlaceholder" value="#adcadb"/>
</tokens>
度量值 | 允许的值 | 当前 DDS 默认值 |
|---|---|---|
| 整数 0–24 | 14 |
| 整数 0–16 | 6 |
| 整数 0–24 | 16 |
| 数值 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. 在自己的环境中运行工作区
在自己的 WSL、容器或服务器环境中运行宿主、SDK、插件和工具。项目文件保留在您选择的根目录下。独立 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 / 容器
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。JSON 结果包含 tool: "module-counter" 和 modules: 1,由真实子进程生成。仅当希望示例向示例文件追加备注时,才在客户端命令中添加 --edit。
要使用自己的项目,将其绝对目录作为最后一个参数传给 server.mjs。将服务器、插件模块和已安装工具保留在同一用户环境中。server.mjs 会明确导入插件,并将其命名后端映射到固定可执行文件和参数:
server.mjs 后端映射
'module-counter': createProcessBackend({
executable: process.execPath,
args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
cwd: root,
env: {},
})
请用经批准的已安装工具或自定义后端替换此映射。ctx.workspace.readFile 和 writeFile 使用相对于选定根目录的路径;ctx.backends.invoke("module-counter", input, {signal}) 只调用已配置的后端名称。进程适配器通过 stdin 发送有界 JSON,并期待 stdout 返回 JSON。它不使用请求提供的 shell 命令,也不继承宿主的任何环境变量。
远程服务器应使用您自己的经过身份验证的 HTTPS 端点,或终止于本地环回的私有隧道。在自己的环境中配置容器端口映射或 TLS。示例默认绑定环回地址;更改绑定地址不会增加 TLS。可信插件和工具以宿主进程的操作系统权限运行。
服务器配置、来源、文件修订、取消和有界结果请参阅用户工作区示例和工作区协议。
语言功能
SDK 0.7.0 提供补全、悬停、定义、引用和扁平文档符号。请在清单 v2 功能中声明每项功能,以及 document.read 和 language.provide 权限。宿主必须明确授予这两项权限。将此完整悬停示例保存为 language-demo.mjs,放在上述创建的项目中:
language-demo.mjs
import { definePlugin, createLanguageResult, createPluginHost } from '@altifigence/dds-plugin-sdk';
const plugin = definePlugin({
manifestVersion: 2,
id: 'hello-hover', name: 'Hello Hover', publisher: 'example', version: '1.0.0',
protocolVersion: 1, entry: './language-demo.mjs', runtime: 'ui',
capabilities: ['hover'],
permissions: ['document.read', 'language.provide'],
supportedHosts: ['test-host'], license: 'Apache-2.0',
source: {visibility: 'open', licenseFile: 'LICENSE'},
}, context => context.registerLanguageProvider('hover', {languages: ['dds-demo']}, {
provide(request, {signal}) {
signal.throwIfAborted();
return createLanguageResult(request, {text: 'A local LED signal.'});
},
}));
const host = createPluginHost({grants: ['document.read', 'language.provide']});
try {
await host.activate(plugin);
host.setDocument({
uri: 'memory:///demo.dds', languageId: 'dds-demo',
modelVersion: 1, workspaceRevision: 'demo-1', text: 'led',
});
const result = await host.requestLanguage('hover', {position: {line: 0, character: 1}});
console.log(result.data.text);
} finally {
host.dispose();
}
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 个扁平 |
位置使用从零开始的行号和 UTF-16 偏移。补全插入是字面文本;悬停和详情字符串是纯文本。宿主必须先检查目标文件和范围,再跳转到位置。结果保留请求、项目/会话及文档版本身份信息。编辑快照、取消、超时、注销或释放,会结束待处理请求并丢弃迟到结果。
这些 API 在可信 SDK 宿主内运行。宿主应用负责集成语言功能显示,并明确配置 LSP 进程。新增功能要求 0.3.0 或更高版本的宿主。有关选择器、限制和生命周期行为,请阅读语言功能。
项目编辑会话
导入 createWorkspaceProject 和 applyTextEdits,来源为 @altifigence/dds-plugin-sdk/workspace-client。宿主连接 createWorkspaceClient 并检查工作区身份、声明和访问权限后,调用 createWorkspaceProject(client)。项目保留确切的连接绑定。重新连接需要一个经过新审查的项目,即使返回相同工作区 ID 和代次也如此。
API | 行为 |
|---|---|
| 列出选定工作区根目录下的一个目录。 |
| 读取文件,并在编辑会话中保留其不可变内容和修订。 |
| 仅在文件不存在时创建,然后返回会话。 |
| 读取最后确认的 |
| 仅当服务器修订仍与保留修订匹配时保存。 |
| 针对一个快照应用 |
| 发生冲突或写入结果不确定后,明确读取最新内容和修订。 |
| 取消拥有的工作;释放项目仍会让调用者拥有的客户端保持连接。 |
在已安装软件包中运行完整 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 不会自动合并或重试。服务器提交写入后,也可能发生超时、取消或响应丢失;取消请求不会撤销已提交更改。每个会话允许一个待处理保存或重新加载。
文本编辑使用原始快照、从零开始的行号和 UTF-16 偏移。重叠、拆分代理对和无效范围会在保存前被拒绝。项目最多允许 64 个已打开或正在打开的会话,每次保存最多 500 项编辑。这些辅助工具使用未更改的工作区协议 v1,包括 SDK 0.2.x 服务器,并保留根目录、受保护路径和只读限制。生命周期和大小限制请阅读工作区项目。
API 参考
从 @altifigence/dds-plugin-sdk 导入插件 API。软件包包含相同导出项的 TypeScript 声明。
API | 用途 |
|---|---|
| 验证清单并声明激活函数。 |
| 注册 |
| 使用请求身份信息构建经过验证的结果。 |
| 注册语言提供器,并使用经过验证的请求身份信息构建结果。 |
| 验证清单版本、身份、权限、受支持宿主和入口模块。 |
| 验证 URI、语言、模型版本、工作区修订和文本。 |
| 验证协议、请求、范围、文档身份和诊断字段。 |
| 读取类型化错误、资源限制和协议版本。 |
从 @altifigence/dds-plugin-sdk/testing 导入开发宿主:
测试宿主 API | 用途 |
|---|---|
| 创建本地宿主。两个选项均可省略;默认授权允许文档读取和诊断。 |
| 激活插件并返回可释放的激活对象。 |
| 设置当前文档。更改文本时,递增 |
| 向匹配的提供器请求诊断;两个选项均可省略。 |
| 使用明确的 document.read 和 language.provide 授权,请求已声明的语言功能。 |
| 移除注册并取消待处理工作;测试结束时释放宿主。 |
请求包括 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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
打包与发布插件
从内置的可发布插件开始。在 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 Release | 带版本的归档、其外部发布 JSON、许可证,以及任何必需的源代码访问方式。 |
私有注册表或下载渠道 | 相同的带版本文件、受众授权及实际插件条款。 |
清单 v2 声明 runtime、请求的权限和 source: {visibility, licenseFile, repository?}。将可见性设置为 open 或 closed,并包含实际许可证文件。您拥有的代码可以使用开源或专有条款;适用的 SDK 和依赖声明仍然有效。接收者会收到可执行 JavaScript,以及声明的源代码可见性和许可证元数据。
披露字段和分发要求请参阅发布和许可证。请通过选定的 GitHub 发布、私有注册表或下载渠道分发带版本的归档。
1.2.1 CLI 在新插件包中记录 >=1.0.0 <2.0.0。历史 0.3–0.13 和确切的 1.0.0-rc.1 归档保留原始 peer 范围。要在稳定版上安装,请验证并重新打包新的插件版本;发布者在重新打包时明确更新所声明的 peer 范围和发布元数据。
验证下载的插件
SDK 1.2.1 提供 dds-plugin verify,用于确切已发布的 0.3.x–0.13.x、RC1 和当前稳定版插件元数据。将 .tgz 与 .tgz.release.json 放在一起。验证保留原始 peer 范围。检查上述创建的软件包:
验证打包后的示例
npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz
此命令检查有界 gzip/tar 结构、确切文件允许列表、每个文件哈希值、清单、披露信息、许可证和生成的 npm 元数据。它拒绝链接、不安全或重复路径、额外文件及 npm 钩子/依赖。它就地读取并验证本地归档,仅处理数据。成功时打印 JSON 回执;拒绝时以代码 1 退出。
对于改名后的下载文件,使用 --metadata 并提供匹配的发布 JSON。通过可信发布渠道独立获取预期 SHA-256,并使用 --sha256 固定所选字节。Node API 提供相同选项:
verify-release.mjs
import { verifyPluginArchive } from '@altifigence/dds-plugin-sdk/publishing';
const receipt = await verifyPluginArchive(process.argv[2], {
metadataPath: process.argv[3],
expectedSha256: process.argv[4],
});
console.log(receipt.pluginId, receipt.pluginVersion, receipt.artifact.sha256);
运行 verify-release.mjs,将归档路径、元数据路径和独立获取的 64 字符小写哈希值作为三个参数。checksumPinned 仅在所提供哈希值匹配时为 true。限制为 12 MiB 压缩输入、10 MiB 文件内容、每个文件 4 MiB、256 个文件和 256 KiB 外部元数据。
配对元数据提供基于哈希的完整性:替换两个文件后可以产生新的匹配哈希值。请通过可信发布渠道确认发布者身份,审查代码中的恶意软件,并由宿主明确决定权限授予及 DDS 安装资格验证。回执描述的是该次调用读取的字节;如果使用前文件可能变化,请重新检查实际字节。现有 0.3.x/0.4.x/0.5.x/0.6.x/0.7.x/0.8.x/0.9.x/0.10.x/0.11.x 插件归档在满足强化文件政策时仍可验证;在 1.0 上安装它们仍需要发布者验证和重新打包。如有需要,移除新排除的文件并发布新插件版本。此验证器针对 DDS 插件包;SDK npm tarball 使用其发布 SHA-256。
权限、许可证与数据使用
清单中请求的权限,与宿主用于启用操作的授权不同。启用前,应向用户提供插件身份、版本、实际许可证、工作区范围和请求权限。连接后端之前,说明后端运营方、发送的数据、目的、保留期限和隐私声明。
记录 | 含义 |
|---|---|
| 针对确切软件包、工作区和权限作出的宿主访问决定。 |
| 用户确认已知悉信息声明。 |
| 用户选择是否接受插件发布者的实际条款。 |
| 当可选处理以同意为依据时,单独作出的选择。 |
SDK 工作区批准是技术访问决定。请将插件条款接受和可选个人数据同意记录为不同的选择。请按照 Apache-2.0 许可证条款使用 SDK。
宿主开发者可以使用可移植异步辅助工具保留带版本的声明。例如,将以下内容保存为 notice.mjs,并运行 node notice.mjs:
notice.mjs
import { createNotice, parseNotice } from '@altifigence/dds-plugin-sdk/consent';
const notice = await createNotice({
id: 'greet-data-use',
version: '1.0.0',
locale: 'en',
purpose: 'Explain the greet command',
text: 'The greet command uses the name you enter to return a greeting. It does not read project files or contact another backend.',
});
await parseNotice(notice);
console.log(notice.text);
console.log(`Notice text SHA-256: ${notice.contentSha256}`);
createPermissionGrant 将请求的权限子集绑定到清单 v2、产物与清单哈希值、工作区代次、宿主身份、声明及到期时间。isPermissionGranted 评估宿主提供的当前身份信息和撤销事件。revokeConsentReceipt 创建单独事件;宿主随后必须停止未来的授权调用。
这些辅助工具验证本地记录。宿主负责提供实际用户选择、身份、存储和执行约束。确切字段请阅读权限与同意授权;明确允许/拒绝/撤销的演示请参阅交互式权限示例。发布者和宿主通过自己的分发流程管理协议。
源代码、发布与贡献
此官方 SDK 仓库包含源代码、模式、示例和契约测试。从源代码运行已发布示例和 SDK 测试:
git clone --branch v1.2.1 --depth 1 https://github.com/Altifigence/dds-plugin-sdk.git
cd dds-plugin-sdk
npm ci
npm test
npm run example
npm run example:language
npm run example:project
npm run example:verify
npm run example:jobs
npm run example:observe
npm run benchmark:files
npm run example:artifacts
npm run benchmark:artifacts
npm run example:durable-jobs
npm run example:stored-artifacts
通过 GitHub Issues 报告 SDK 缺陷,并提供 SDK 版本和最小复现步骤。SDK 采用 Apache-2.0 许可证;请查看仓库许可证和声明。带版本的归档和发布说明请查看发布页面。
该仓库发布开发者 SDK。已声明的 SDK 文件、模式、示例和声明构成其公开范围。软件包检查执行确切的已发布文件清单,并拒绝已知秘密信息和私有路径模式。请结合模式检查审查所选发布内容,识别分发文件中披露的数据。
安全更新与宿主限制
将工作区服务器和 SDK 客户端同时更新到 0.3.2 或更高版本。请安装服务器更新,以启用升级后的文件检查和请求限制。重启升级后的宿主,检查新的代次,并在使用工作区前重新取得批准。
Node 工作区宿主拒绝可能指向受保护文件或所选根目录外文件的硬链接。对于有意共享的项目文件,应复制为常规单链接文件。诸如 .netrc、_netrc、.git-credentials、.gnupg、.kube 和 .docker 的凭据存储、其他 SSH 密钥名称,以及 Windows 设备别名也会被阻止。打包和下载验证采用相匹配的凭据名称政策。
服务器资源 | 限制 |
|---|---|
并发传入请求体 | 16;超过数量的上传会在分派前收到 HTTP 429 |
执行中的请求 | 64;取消使用独立分派路径 |
连接数 / 每个套接字的请求数 | 128 / 128 |
请求与响应 / 文件内容 | 1,600,000 / 262,144 个 UTF-8 字节 |
达到期限或取消时,客户端会取消尚未读取的被拒绝响应和停滞的数据流。写入开始后超时,可能使结果不确定:重试之前重新读取文件。请结合路径排除审查文件内容中的秘密信息。可信插件代码使用宿主进程的操作系统访问权限。部署宿主时,请使用安全升级指南和工作区限制。
开发工具
安装上述 SDK 1.2.1 后,创建一个单独的命令插件项目。请为生成文件选择新目标;创建脚手架后,明确执行依赖安装及插件运行。生成的脚手架包含命令、测试、清单、披露、固定的 SDK 依赖项以及 Apache-2.0 LICENSE/NOTICE。
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;示例发布者/支持值会产生警告。分发前,替换这些值并检查许可证。
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 打印作业进度/日志;使用 --timeout-ms 设置超时,普通命令最多 30 秒,作业最多 30 分钟。Node API 为 /devtools 中的 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 授权仍然适用;不接受任意可执行文件路径。
await client.connect();
if (!(await client.getJobCapabilities()).enabled) throw new Error("Jobs are unavailable");
const jobId = crypto.randomUUID(); // Save before sending.
let job = await client.startCommandJob(pluginId, "analyze", {}, artifactSha256, {jobId, timeoutMs: 300_000});
let after = 0;
for (;;) {
const page = await client.getJobEvents(jobId, after);
after = page.nextCursor;
if (page.dropped) console.log("Expired events:", page.dropped);
for (const event of page.events) console.log(event.kind, event.data);
job = await client.getJob(jobId);
if (job.state !== "running" && !page.hasMore && after >= job.lastSequence) break;
await new Promise(resolve => setTimeout(resolve, 250));
}
if (job.state === "succeeded") {
const file = await client.readJobArtifact(jobId, "report");
console.log(file.content);
}
轮询片段假定客户端已连接,并配置了注册 report 的 analyze 命令。启动前保留作业 ID。断开连接或中止轮询请求不会取消执行;重新连接到同一代次,并明确查询或取消。使用相同 ID 和输入重试启动,会复用保留的作业;参数变更产生冲突。宿主重启会丢失内存记录。启用下文独立的 0.8 持久存储,可在重启后恢复已提交元数据。
状态为 running、succeeded、failed、cancelled 和 timed_out。取消后迟到输出被丢弃;副作用不会回滚。尚未完成清理的提供器仍占用其槽位。最多有 4 个并发作业、32 条保留记录、每作业 32 个嵌套操作、每作业 256 个事件/64 KiB、每页 64 个事件和 16 个产物。运行时间默认为 5 分钟,上限为 30 分钟。已稳定的终止记录会在最后一个事件后 15 分钟过期。
文本结果文件为相对于工作区的 UTF-8 文件,最多 256 KiB。宿主使用现有授权读取它们,记录 SHA-256,并在字节变化后拒绝后续读取。对于二进制或较大的仿真输出,使用可选的二进制结果 API。取消后可能留下部分产物;请检查作业终止状态以确认成功。旧版 0.3 客户端继续使用现有 v1 方法;独立 SDK 作业要求两端均为 0.4,并使用明确配置的宿主/客户端。确切契约和限制请参阅作业。
观测工作区文件
project.watchFiles() 对 1–16 个明确的相对文件路径进行采样。SDK 1.0.0 在支持的宿主上使用仅修订请求,在较旧宿主上使用现有有界读取。示例假定客户端已连接并获宿主批准。用外部编辑器更改 design.sv 可结束循环;保留的编辑快照保持不变。
import {createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
const project = createWorkspaceProject(client);
const edit = await project.openFile('design.sv');
const original = edit.snapshot;
try {
for await (const change of project.watchFiles(['design.sv'], {intervalMs: 1000})) {
console.log(change.kind, change.path, change.previousRevision, change.revision);
if (change.kind !== 'initial') break;
}
console.log(edit.snapshot === original);
} finally { project.dispose(); }
事件为不可变的 {kind, path, previousRevision, revision}。首次采样发出 initial;后续变化发出 created、changed 或 deleted。缺失文件的 revision 为 null。includeInitial: false 会静默记录基线,相同修订不会产生事件。只有 not_found 表示删除;权限、受保护路径、大小和传输错误会结束观测。
单独保留 UI 中未保存的文本。重新加载、合并及保存草稿由调用者明确执行,编辑保存仍可能与保留修订冲突。路径按顺序逐一读取;这是采样观测,因此中间变化可能被合并。此 API 对明确选定的文件路径采样;调用应用负责目录发现和重命名处理。现有根目录、文件大小及受保护路径限制同时适用于只读和可写服务器。
文件和作业观测器均在首次 next() 时启动,消费者暂停时不会在后台获取页面,每个客户端共享最多八个活动观测器。只能有一个待处理 next();并发读取以 conflict 失败。break 或 return() 会停止待处理读取;释放项目会停止其文件观测器,断开/重新连接/释放会使所有旧观测器失效。AbortSignal 以 cancelled 结束观测;迟到响应不能产生结果。
intervalMs 为 250–60,000 ms(默认 1,000),在文件遍历之间或空闲作业读取之间应用。requestTimeoutMs 为每个请求 1–30,000 ms,默认采用客户端期限。总 timeoutMs 从首次 next() 起为 1–1,800,000 ms,包括消费者暂停时间。文件默认没有总超时;作业默认为 30 分钟。达到期限会报告 budget_exceeded 并释放槽位。这些限制以 WORKSPACE_OBSERVATION_LIMITS 导出。
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()。观测绝不会启动、重试或取消命令。
let after = savedCursor ?? 0;
for await (const update of client.watchJob(jobId, {after, intervalMs: 1000})) {
if (update.dropped) console.log('Expired events:', update.dropped);
for (const event of update.events) console.log(event.kind, event.data);
console.log(update.snapshot.state, update.snapshot.progress);
after = update.nextCursor;
}
const result = await client.waitForJob(jobId, {after, timeoutMs: 120000});
if (result.state === 'succeeded') console.log(result.result);
else console.log(result.state, result.error.code);
每个冻结的更新包含 snapshot、events、after、nextCursor、dropped 和 hasMore。每页处理最多 64 个事件,并在处理后将 nextCursor 与作业 ID 和工作区身份一同记录。dropped 报告已过期历史。快照可能比事件页更新;hasMore 为 true 时,继续读取终止快照。迭代器在最后一页之后结束。waitForJob() 读取相同页面直至结束,并返回 succeeded、failed、cancelled 或 timed_out;请检查状态,不要将每个已解决的 promise 都视为成功。
停止迭代器或超时,只会停止观测。服务器命令继续运行,直到结束或明确调用 cancelJob()。经宿主批准重新连接后,验证相同工作区 ID 和代次,再使用保存的作业 ID 和游标创建新观测器。即使身份未变,旧观测器也已失效。缺失/过期作业和传输失败会被报告,不会重新提交;内存作业无法在宿主重启后保留。持久恢复通过新连接使用 recoverJob();实时观测器不会跨代次恢复。
现有 v1 hello 和作业契约保持不变。文件观测在 0.3.2/0.4/0.5 宿主上回退;作业观测要求已启用的 0.4 或更高版本宿主。宿主为不受支持的作业报告错误,由调用者明确选择后续命令。这些观测 API 通过独立 SDK 宿主/客户端运行。参阅观测和兼容性。
文件修订与条件读取
SDK 0.6.0 为已连接客户端增加 getFileCapabilities()、getFileRevision(path) 和 readFileIfChanged(path, knownRevision)。修订读取返回 {path, revision},不带内容。条件匹配时返回 {path, revision, notModified: true};内容变化时返回 notModified: false 和 content。要获取当前内容,请传入 knownRevision: null。缺失文件以 not_found 拒绝。
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 计算。在 Windows 上使用本地 Node 22.23.1 测量 20 次未变化的 200,000 字节样本,完整读取返回 4,003,974 字节,修订读取为 3,867 字节(减少 99.903%),条件读取为 4,247 字节(减少 99.894%)。包含发现请求;不包含 HTTP 头、TLS 及最初 hello/内容基线。在检出仓库中运行 npm run benchmark:files 可复现该测试样本。
SDK 现在具有稳定的 1.x API,功能检查覆盖文档所述的文件修订行为。现有 0.3.2、0.4、0.5 和 0.6 客户端在 0.7 宿主上保留原始 API。请使用独立 SDK 宿主/客户端验证这些 API。完整契约和迁移规则请参阅文件修订。
大型与二进制作业结果
SDK 0.7.0 增加可选二进制结果文件扩展。可信命令注册现有工作区文件;宿主记录其 SHA-256 和长度。客户端每块最多读取 64 KiB,Node 下载器可恢复部分文件,并验证完整输出。记录的文件最大为 1 GiB;现有 256 KiB UTF-8 文件和文本产物 API 保留原有限制。
在服务器拥有的插件宿主上启用 jobs: true 和 binaryArtifacts: true。两者默认为 false。保留明确的令牌、操作者声明、经审查的插件产物固定值及有效 workspace.read 授权。以下内容基于上述工作区设置;只读工作区可注册操作者配置的工具已生成的文件。
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 失败。
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”,并拒绝覆盖现有最终文件。
import {downloadJobBinaryArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const capabilities = await client.getBinaryArtifactCapabilities();
if (!capabilities.enabled) throw new Error('Binary results are not enabled');
const reference = await client.getJobBinaryArtifact(jobId, 'trace');
const receipt = await downloadJobBinaryArtifact(client, reference, {
destination: absoluteDownloadPath, resume: true,
signal: abortController.signal,
onProgress({receivedBytes, totalBytes}) {
console.log(receivedBytes, totalBytes);
},
});
console.log(receipt.verified, receipt.revision);
保留完整的 {jobId, scope, artifact} 引用。中断后,明确重新连接到同一宿主代次,并使用该引用和 resume: true 再次调用辅助工具。它重新计算已保存前缀的哈希值,并仅请求缺失后缀。发布前,它检查每块、完整接收流和实际暂存文件的 SHA-256。最终 verified: true 回执确认完成;同步进度回调仍未经验证。损坏的部分文件需要明确移除或使用新目标。
listJobBinaryArtifacts(jobId) 返回已记录的二进制元数据,与现有文本结果分开。readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) 返回规范 base64、分块 SHA-256、确切范围及 EOF 标记。/artifacts 中的 decodeBinaryArtifactData 返回 Uint8Array 字节。浏览器使用者必须自行验证整个文件的哈希值;单独分块检查不能证明组装后的输出与引用匹配。
二进制和文本结果在每个作业中共享 16 个槽位和同一 ID 命名空间。每个宿主/工作区最多四个二进制捕获/读取操作,每个进程最多四个 Node 下载。Node 下载的 timeoutMs 为总期限,默认最多 30 分钟;requestTimeoutMs 默认 5 秒,最多 30 秒。发布需要 NTFS 或 ext4 等文件系统的硬链接支持。请使用操作者控制下的可信目标并管理并发写入者;文件系统检查使用宿主进程的操作系统权限执行。
可选 artifacts.capabilities、artifacts.list 和 artifacts.read 保留现有 v1 hello、作业快照及事件。早于 0.7 的宿主报告扩展禁用;由调用者明确选择后续文本读取或命令。身份验证、格式错误响应和传输错误仍然是错误。重新连接、撤销、作业过期或宿主代次变化会使旧操作失效。作业在终止作业的最后事件后仍在内存中保留 15 分钟。取消的作业可能留有已记录的部分工具输出;请检查作业终止状态以确认成功。这描述默认的实时/源文件 API。下文独立的已存储结果 API 可跨重启保留字节。
运行 npm run example:artifacts,可进行真实的 2 MiB 传输,包含中断、重新连接及仅后缀恢复;npm run benchmark:artifacts 使用 8 MiB。本地 Windows 运行通过 129 个分块请求传输了 8,388,625 字节,恢复了 65,536 字节前缀,并验证最终 SHA-256。Base64 增加开销;JSON 响应体共 11,257,419 字节。此有界内存传输保留文件字节,并使用 base64 传输。完整契约请参阅二进制产物。请使用独立 SDK 宿主/客户端执行此传输流程。
持久作业、历史与明确重试
SDK 0.8.0 在工作区之外由操作者拥有的目录中增加可选持久存储。提供绝对路径、稳定工作区 ID、经审查的插件代码、软件包 SHA-256、令牌和声明。示例还启用文件字节保留;从 jobStorage 中省略 artifacts,可只保存作业元数据。现有 v1 响应和仅内存默认模式保持兼容。
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 未知。
const capabilities = await client.getJobStorageCapabilities();
const query = {limit: 16, commandId: 'analyze'};
const page = await client.listJobHistory(pluginId, artifactSha256, query);
const prior = await client.recoverJob(pluginId, previousJobId, artifactSha256);
const attempt = await client.retryCommandJob(pluginId, previousJobId,
reviewedFreshInput, artifactSha256, {jobId: crypto.randomUUID()});
历史按状态、恢复处置、命令、启动时间和父尝试筛选。每页最多 32 条,先按启动时间降序,再按作业 ID 排序。游标将成员集合冻结 60 秒,并必须复用同一查询;新作业被排除,已删除或未授权记录被跳过,到期会被报告。重启会丢失游标。artifactCount、snapshotCount 和 resultAvailability 描述已记录引用,而非当前文件证明。
明确重试需要新的作业 ID、新验证的输入、相同且当前获批准的软件包,以及可用命令。attemptOf 将新运行关联到未更改的父尝试。重复相同 ID、输入、父尝试和超时,会获取保留的尝试而不重新运行,包括重启后。缺失/过期记录无法提供这一保证。等待请求被取消后,已接受的执行仍可能继续;决定是否重试前,查询新作业 ID。
默认保留不包含原始输入、结果体、进度文本和产物标签;日志会脱敏。只有明确配置的确定性宿主脱敏器才保留经审查文本。令牌、秘密信息和旧同意授权绝不会恢复。当前工作区/插件身份、读取权限和每项已记录授权都会重新检查。作业元数据默认为 256 条记录、64 MiB 和 24 小时,最长七天。移除和清理是明确的宿主操作。
本地存储只有一个写入者,验证工作区/根目录身份,并检查元数据完整性。明确的过期锁恢复只会回收能够证明已死亡的同机 PID。未知/损坏文件需要检查。在 Windows 上,文件同步和重命名支持进程重启恢复;请针对目标文件系统单独验证断电行为。参阅作业存储、历史和持久作业示例。
已存储结果与重启后下载
启用产物存储后,await job.addArtifact() 或 job.addBinaryArtifact() 会在注册前复制并验证完整文件。文本仍限制为 256 KiB;二进制文件最多 1 GiB。源数据流和实际暂存文件都进行 SHA-256 检查。取消、磁盘已满错误、修改和部分写入不会发布可用结果。崩溃前已发布但尚未被作业记录的文件,可能保留供操作者检查。
import {downloadStoredJobArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const list = await client.listStoredJobArtifacts(pluginId, jobId, artifactSha256);
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, artifactSha256);
const receipt = await downloadStoredJobArtifact(client, reference, {
destination: absoluteOutputPath, resume: true,
});
console.log(receipt.storage, receipt.snapshotId, receipt.verified);
列表将源引用与快照元数据分开,并报告 retained、expired、missing、corrupt 或 unsupported 快照。retained 是元数据状态;getStoredJobArtifact() 会验证元数据和整个已存储文件,再返回当前代次的新引用。每次读取重新检查当前权限和文件身份。删除源文件不影响已存储字节,缺失快照绝不回退到可变源文件。文本快照请调用 client.readStoredJobArtifactText(textReference)。
重启后,使用当前授权重新连接并获取新引用。快照 ID、存储 ID 和摘要保持稳定;旧代次会被拒绝。resume: true 会针对该快照重新检查已保存的 .dds-part 前缀,验证分块及整个暂存文件,并在不覆盖目标的情况下发布。读取既需要保留的作业元数据,也需要文件字节。浏览器分块使用者必须验证完整摘要;下文 Worker 适配器提供明确的浏览器磁盘恢复。
产物存储默认限制为 256 个文件、256 MiB 和 24 小时,总存储上限为 4 GiB,保留期限上限为七天。每块最多 64 KiB,最多四个并发读取。inspect() 报告用量、到期时间、无效条目和孤立文件。remove(snapshot) 与 prune() 是明确的操作者操作。活动作业和单次读取会被固定保留;分块之间发生过期或移除,可停止下一次读取。可选孤立文件清理只移除识别出的单链接文件。损坏或含糊的条目需要检查。
文件保留会存储实际项目字节,与日志脱敏无关。请有意选择。重启后仍需要当前插件/命令、软件包哈希值、工作区和已记录授权。完成维护后,依次等待 server.close()、artifacts.close() 和 store.close()。请在明确配置的独立 SDK 宿主中使用这些保留和关闭 API。
运行 npm run example:stored-artifacts,可测试真实子进程重启、源文件删除、经过验证的部分下载恢复、历史和明确重试。npm run example:durable-jobs 还涵盖强制终止进程。参阅已存储结果。已知 0.7 和更早宿主报告存储禁用,不发起未知探测。现有实时/源文件 API 保留原始行为。
观测项目
操作者在服务器上明确启用项目并选择允许的根目录。默认禁用。已知 SDK 0.3–0.8 宿主无需新的发现探测就会报告不可用。支持的文件系统配置为 Windows/Linux 本地存储。此独立 SDK 示例使用明确配置的宿主/客户端。
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
import {createWorkspaceClient, createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
// The operator chooses the workspace and its allowed local directories.
const server = await createWorkspaceServer({
root: operatorWorkspace, workspaceId, token, notice,
projects: {roots: ['rtl'], fileSystem: 'local'},
});
const client = createWorkspaceClient({url: server.url, token});
await client.connect();
const project = createWorkspaceProject(client);
if (!(await project.getProjectCapabilities()).enabled) {
throw new Error('Project tools are unavailable');
}
const observer = project.watchProject({
root: 'rtl', include: ['**/*.sv'], exclude: ['build/**'],
intervalMs: 1000, debounceMs: 50,
}, {signal});
for await (const event of observer) {
renderExternalView(event.snapshot, event.kind, event.reason);
}
project.dispose(); client.dispose(); await server.close();首个事件是完整快照。后续变化携带相对于前一修订的增量;提示丢失、初始扫描期间变化、扫描不完整及慢消费者溢出,会产生附带原因的完整重新同步视图。重命名可能显示为删除/创建。每个文件分别验证。快照修订描述采样的文件状态,两次采样之间的中间写入可能合并。
服务器和客户端各允许四个订阅,每个原生订阅有四个排队事件。默认空闲租期为 30 秒;之后读取可能返回 not_found。长时间暂停后,创建新迭代器获取初始快照。break/return、取消和释放会释放订阅;连接中断导致无法清理时,剩余远程资源会随租期到期。
默认扫描限制为深度 8、512 个条目、每文件 1 MiB、总计 16 MiB 和 10 秒。可配置上限为深度 32、1,000 个条目、每文件 16 MiB、总计 64 MiB 和 30 秒。受限文件可能只包含元数据而没有内容哈希值;请检查 complete 和 reasons。期限在文件系统调用之间检查;请为这些调用有意选择宿主进程的操作系统访问权限。
项目树与搜索
listTree 返回树,searchFiles 通过字面子串或有界 glob 搜索相对文件名,searchText 在 UTF-8 文件中查找字面文本。root 必需;include/exclude 相对于它。请使用受支持的字面和有界 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 不同时,释放旧游标,并重复同一根目录/筛选查询。观测绝不会修改 edit.snapshot 或调用者拥有的草稿内容。外部变更、移动或删除后,原始 CAS 条件会报告冲突;调用者选择明确重新加载、合并或单独保存。
客户端检查连接代次、根目录/筛选、查询哈希值、页面位置、快照 SHA-256 和事件连续性。撤销、断开或重新连接后,迟到响应会被丢弃。监视游标和查询游标彼此独立,不会自动恢复。server.revokeProjects() 结束项目访问;重新启用需要新的服务器代次。
npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browser已安装的 Node 示例验证创建、搜索、外部变更、保留草稿、CAS 冲突和重新连接。浏览器示例请打开打印的环回 URL,并选择“运行场景”。它只使用自己的临时工作区,示例服务器停止时会移除该工作区。HTTP 请求默认五秒;较大扫描应有意配置客户端和服务器超时。
流式传输并验证浏览器产物
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 和每块哈希值。支持回读的接收端随后独立重新读取已保存字节;只有两次完整哈希值都匹配,才记录 stored 验证状态。不支持回读时,验证状态为 received,storedSha256 为 null。进度达到全部字节不代表完成。
应用选择文件句柄或 OPFS 目录,并授予所需权限。请向 SDK 适配器提供选定目标及其访问授权;应用负责选择器交互和目标选择。异步文件/OPFS 可写接收端保持暂存状态直到 close,并在提交前失败时丢弃暂存。要获取可安全跨重新加载保留的部分文件,使用下文专用 Worker 适配器。文件限制为 1 GiB,最多四个直接并发流,总期限为 30 分钟。
上传所选文件
import {uploadFile} from '@altifigence/dds-plugin-sdk/uploads';
import {createBrowserUploadSource} from '@altifigence/dds-plugin-sdk/uploads-browser';
// The operator separately configures uploads.directory/principalId/roots/fileSystem
// on the Node workspace server, and grants workspace.write to this pinned plugin.
const source = createBrowserUploadSource(selectedFile);
const status = await uploadFile(client, source, {
uploadId: crypto.randomUUID(), pluginId, artifactSha256: pluginPin,
path: 'input/trace.bin', expectedRevision: null, signal,
});
if (status.state === 'committed' && status.commitReceipt.verified) {
showCommittedUpload(status.commitReceipt);
}
// To recover a previously selected upload ID, pass the same specification and
// source with recover: true. The helper queries current authority and rehashes it.上传默认禁用。操作者配置本地 Node 工作区、隔离暂存目录、允许的根目录和一个主体,然后在选定插件的确切归档固定值上授予 workspace.write。辅助工具在开始前预先计算所选源文件哈希值。服务器接受顺序 64 KiB 分块,验证重复块及完整内容,并仅在条件目标检查通过后提交。普通工作区列表中不会出现暂存字节。
expectedRevision: null 要求目标不存在;SHA-256 要求当前目标匹配。取消会保留服务器已确认前缀。新的明确 recover 操作查询当前权限,验证相同源文件/规格,并仅恢复匹配前缀。提交响应丢失时,在查询之前结果不确定;它不构成重复提交或回滚文件的许可。最大限制为每文件 1 GiB、每存储 4 GiB 和四个活动会话;默认值更低。已知 0.3–0.9 宿主报告上传禁用,不探测新方法。
安排文件传输
import {createTransferQueue} from '@altifigence/dds-plugin-sdk/transfer-queue';
const queue = createTransferQueue({
concurrency: 2, perConnection: 1, bufferBytes: 131072,
bytesPerSecond: 1048576, attempts: 3,
});
const unsubscribe = queue.subscribe(view => renderTransfer(view));
const download = queue.enqueueStoredDownload(client, reference, {sink});
download.pause(); // finishes the current stage, then waits at the next boundary
download.resume();
const receipt = await download.result;
queue.release(download.id);
unsubscribe(); await queue.dispose();调用者拥有的队列混合上传、实时下载和已存储下载作业。它限制保留作业(32)、同时阶段(4)、客户端连接并发、解码分块预留(64–256 KiB)、速率和重试。可执行工作可以绕过已饱和连接继续推进,有界的优先级提前启动可防止小型可执行作业长期得不到执行。暂停作业先完成当前阶段,再等待;暂停可能保留存储锁。总期限包括排队等待和暂停。
自动重试仅限 SDK 识别的 429/503、网络断开,或幂等确切分块操作中的请求超时,并采用有界退避和随机抖动。请明确处理 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 同步访问和 Web Locks。重新加载后,调用者重新选择目录和部分文件 UUID,并获取新的获批准存储引用。接收端存储两个确切的数据/元数据文件名、完整不可变快照身份、到期时间及当前/前一前缀哈希值。它不存储令牌、授权或旧连接范围。每个数据块先刷新到存储,然后关闭小型元数据流。
接收端和辅助工具各自独立重新计算前缀哈希值。只有记录的前缀匹配后,才裁剪未记录检查点的尾部。元数据超出实际文件大小时,只有对应字节和哈希值匹配,才能回退到前一个检查点;损坏、条目缺失、过期或快照不同都会失败,不会静默重新开始。覆盖整个来源的排他锁会拒绝另一标签页,在回读期间保持占用,并在关闭或 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签名帮助与补全辅助
按需在清单 v2 中声明 signature-help、completion-resolve 和 completion-snippets;补全修饰功能还需要 completion。宿主必须授予 document.read 和 language.provide。现有字面补全仍然有效。languageCapabilities() 报告 SDK 实现及其限制,不授予权限。
const signatures = await host.requestLanguage('signature-help', {
position, context: {triggerKind: 'invoked', isRetrigger: false},
});
const list = await host.requestLanguage('completion', {position});
if (list.data.length) {
const detailed = list.data[0].resolveToken
? await host.resolveCompletion(list.data[0].resolveToken) : list;
const preview = host.prepareCompletion(detailed, 0);
showInsertionPreview(preview.content, preview.tabstops);
host.releaseCompletion(detailed);
}
host.releaseCompletion(list);应用提供当前位置和宿主;准备过程返回数据,不写入文档或文件。签名帮助支持最多 16 个签名、每个 64 个参数及 UTF-16 参数标签偏移。补全解析将提供器数据保持私有,返回一次性宿主令牌,并固定选定标签/插入/范围。令牌绑定提供器、范围和文档,60 秒后过期,限制为 128 条、4 MiB 和四个实际解析操作。文档/提供器变化会丢弃它们。
片段支持 $n、${n}、${n:literal}、$0 和文档规定的转义,包含镜像和有序制表停靠位。变量、嵌套、选择项、变换和可执行命令会被拒绝。系统检查 UTF-16/CRLF 边界和重叠的额外编辑。提供器作为可信进程内代码,以宿主进程权限运行;忽略取消会让实际待处理槽位继续被占用,直到提供器完成。
经审查的工作区编辑与重命名
prepare-rename 返回经过验证的范围/占位文本或 null;rename 返回 WorkspaceEdit 提案或 null。提案支持针对互不相交的相对文件路径执行编辑、创建、移动和删除。系统检查当前源文件 SHA-256、目标不存在、受保护路径政策、UTF-16 编辑几何及限制。语言功能授权提案;工作区客户端提供单独批准的文件访问和修改。
import {previewWorkspaceEdit, applyWorkspaceEdit, recoverWorkspaceEdit}
from '@altifigence/dds-plugin-sdk/workspace-edits';
const preview = await previewWorkspaceEdit(client, proposal);
// Show every change, conflict and required capability; obtain this exact review.
const receipt = await applyWorkspaceEdit(client, preview, {
reviewed: approvedReview, // {planId, digest} from that review
journal,
authorize: (request, {signal}) => currentHostPolicy(request, signal),
});
// After interruption, current-authority readback does not replay changes.
const observed = await recoverWorkspaceEdit(client, journal, preview.planId);调用者使用已连接且获授权的工作区客户端和可信日志。预览包含完整前后快照及摘要;应用需要已审查的 planId/digest,以及返回 true 的当前宿主政策。每个文件先预检,再由每项操作使用现有逐文件 CAS 和当前写入/管理功能。日志在每次修改前持久保存并回读意图,在修改后保存回执。冲突或不确定会停止后续写入;每个文件保留自己的 CAS 事务边界。
可选 workspace-edits-node 适配器在选定工作区之外存储有界日志,绑定其身份,并使用单写入者锁、普通文件和校验和检查点。进程终止后,recoverStaleLock 是明确选择,只回收已证明死亡的所有者。恢复根据当前字节报告 applied/not-applied/conflicted/unknown;由调用者明确决定后续操作。补偿会创建新的逆向提案供重新审查。在 Windows 上,适配器同步文件并执行重命名操作;检查覆盖进程终止和恢复,持久性由文件系统及存储设备决定。限制包括 32 项变更、1,000 项编辑、每文件 256 KiB、8 MiB 预览和 64 个保留日志计划。
格式化与诊断代码操作
const formatted = await host.requestLanguage('format-range', {
path: 'main.dds', range: selectedRange,
formatOptions: {tabSize: 2, insertSpaces: true, endOfLine: 'preserve'},
});
const formatProposal = host.prepareFormatting(formatted);
await host.requestDiagnostics();
const actions = await host.requestLanguage('code-actions', {
path: 'main.dds', range: selectedRange,
context: {triggerKind: 'invoked', only: ['quickfix']},
});
if (actions.data.length && !actions.data[0].disabled) {
const selected = actions.data[0].resolveToken
? await host.resolveCodeAction(actions.data[0].resolveToken) : actions;
if (!selected.data[0].disabled) {
const fixProposal = host.prepareCodeAction(selected, 0);
showWorkspaceEditProposal(fixProposal); // separate preview, review and apply
}
host.releaseCodeActions(selected);
}
host.releaseCodeActions(actions);format-document 和 format-range 需要路径及 tabSize/insertSpaces 选项;只有范围格式化接收选区。结果为 null,或恰好一个带当前快照哈希值的当前文件编辑。范围编辑限定在选区内。endOfLine 为插入文本选择 preserve、lf 或 crlf;未编辑字节保持不变。内容完全相同的提案会规范化为 null。prepareFormatting 不执行写入。
宿主将操作请求和解析令牌绑定到已接受的诊断修订及当前快照。后续诊断发布、文档变化或提供器释放会使旧选项失效。乱序诊断调用不会覆盖较新的已接受诊断包。最多 100 个操作包含纯文本标签、有界诊断索引、提议编辑、私有解析数据或禁用原因。未知 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);语义令牌使用具有唯一名称和九个宿主所有样式键的图例,每个令牌另有五个整数:增量行/起点、UTF-16 长度、类型索引和修饰位。令牌不能重叠、拆分代理对、跨行或超出当前文档。宿主始终返回完整规范化数组和宿主 UUID,updateKind 为 full/delta/fallback。独立的 semantic-tokens-delta 功能启用针对提供器所拥有旧数据的 provideDelta;缓存存储身份和令牌数据,不保存旧文档文本。
缓存基线绑定到提供器、范围、URI 和语言,最多八条、4 MiB 和 60 秒。普通递增文档版本会保留可能的增量基线,同时使旧显示结果过期。基线丢失/过期、null 增量或提供器基线 ID 不匹配,最多允许在原始超时内进行一次完整回退。无效数据或提供器错误直接失败,不重试。停用、注销和文档替换会清除受影响基线。渲染前立即调用 validateLanguageResult;复制、已释放或过期对象会失败。
限制为 20,000 个语义令牌、64 个令牌类型、16 个修饰符和 64 项增量编辑;折叠允许 1,000 个范围、深度 32,并拒绝交叉范围。内嵌提示允许所请求范围内 1,000 个单行纯文本标签。层次符号允许总计 1,000 项和 16 层,子项/选区必须包含于父项,兄弟项有序且不重叠。原始扁平 document-symbols 契约保持不变。浏览器示例测试 full/delta/fallback、折叠、导航及生命周期;类似 HTML 的提示仍然是字面文本。
npm run example:assistance
npm run example:workspace-edits
npm run example:language-editing
npm run example:language-display
npm run example:language-display-browser类型化设置与秘密引用
/settings 模块为一个插件提供由操作者拥有的内存存储。带版本的定义声明每个键、数据模式、默认值、允许的用户/工作区范围及显示元数据。有效值按 default < user < workspace 的顺序替换整个键。read(workspaceId) 返回不可变值、来源及整个存储的修订。嵌套对象不会递归合并;没有默认值的缺失值仍然缺失。
import {createSettingsStore} from '@altifigence/dds-plugin-sdk/settings';
const settings = createSettingsStore({schemaVersion: 1, pluginId: 'example',
version: 1, settings: {count: {
schema: {schemaVersion: 1, schema: {
type: 'integer', minimum: 1, maximum: 10, default: 2,
}}, scopes: ['user', 'workspace'], display: {label: 'Count'},
}},
});
settings.update({workspaceId: 'selected-project', scope: 'workspace',
expectedRevision: settings.read('selected-project').revision, values: {count: 4}});
const effective = settings.read('selected-project');
// Mount as createPluginHost({settings: {example: settings}, ...}).写入验证完整事务,并使用 expectedRevision CAS。reset 从一个层移除键;readOnly 要求默认值且没有可写范围。订阅合并同步变化并返回可释放句柄。明确的 migrate(nextDefinition, callback, options) 验证下一个状态,仅在修订仍匹配时提交。失败、取消或超时保留旧定义和状态。导出/导入是纯数据;操作者负责持久化和加密。限制包括 64 个键、32 个工作区层、1 MiB 导出状态和一个实际迁移。
工作区插件声明 settings 和 settings.read,操作者以该授权挂载匹配存储。context.settings 为只读,绑定到插件和选定工作区。/secrets 解析器另行签发绑定插件、工作区、命令允许列表和生命周期的不透明引用。清单必须声明 secrets.resolve,宿主必须授予该权限。输入字段使用 type: object 和 format: dds-secret-reference;普通字符串和外观相似的对象不具有秘密访问权限。
只有已验证输入中的引用,才能通过命令的 options.secrets.withSecret 使用。每次执行有新的 ID;解析器在解析和回调前后检查范围、到期、撤销和当前授权。回调返回 undefined,并接收一个副本,副本在中止及每次退出时被清除。提供器错误会脱敏。在执行需要该权限的副作用之前,应先取得租用。默认引用生命周期为 60 秒,最多一小时;限制为 128 个引用、8 个实际租用和 16 KiB 材料。请仅以宿主进程权限运行可信代码,因为此类代码可以保留副本。绝不要将材料放入设置、包、日志或结果;处理秘密信息时,请明确分类任意应用字符串。
结构化命令模式与表单
命令可使用 schemaVersion: 1 封装声明 inputSchema 和 outputSchema。现有基本类型参数仍受支持;同时声明 parameters 和 inputSchema 会被拒绝。宿主在启动处理器或作业前验证输入并应用输入默认值,然后在发布成功前验证输出。绝不会应用输出默认值。新的模式/显示元数据需要理解 0.12 的对端;旧严格验证器会拒绝它,而旧定义保留原行为。
import {parseCommandInput, parseCommandOutput} from '@altifigence/dds-plugin-sdk';
const command = {id: 'summarize', title: 'Summarize',
inputSchema: {schemaVersion: 1, schema: {
type: 'object', additionalProperties: false,
properties: {names: {type: 'array', minItems: 1, maxItems: 8,
items: {type: 'string', minLength: 1, maxLength: 64}}}, required: ['names'],
}}, outputSchema: {schemaVersion: 1, schema: {type: 'integer', minimum: 0}},
};
const input = parseCommandInput({names: ['Ada']}, command);
parseCommandOutput(input.names.length, command);有界子集支持封闭对象、数组、字符串、有限数值、安全整数、布尔值、null、基本类型枚举、界限和经过验证的默认值。未知关键字、远程引用、正则表达式、联合类型、强制转换、访问器和自定义原型会被拒绝。模式允许 32 KiB、深度 8 和 128 个节点;值允许 64 KiB。完整命令仍受 16 KiB 元数据预算约束。本地 DataValidationError 提供 code、reason 和已知字段路径,如 /input/options/names/0;HTTP 和作业失败提供安全代码,不暴露被拒绝的值。
describeDataForm 返回路径、类型、选择项、默认值、必填标志和秘密引用提示。共享显示元数据携带字面 label/help/order,以及无障碍名称、描述和键盘提示。宿主负责渲染和交互。这些模式描述字面数据,供宿主负责渲染和明确交互。
本地化与无障碍元数据
import {parseLocaleCatalog, resolveMessage, localizeDisplay}
from '@altifigence/dds-plugin-sdk/localization';
const catalog = parseLocaleCatalog({schemaVersion: 1, defaultLocale: 'en',
messages: {en: {title: 'Run', done: '{count} results'},
ko: {title: '실행', done: '결과 {count}개'}, ar: {}}, fallbacks: {ar: ['en']},
});
const message = resolveMessage(catalog, 'ko-KR', 'done', {count: 2});
const display = localizeDisplay(catalog, 'ko', {
labelKey: 'title', accessibility: {nameKey: 'title', shortcut: 'Control+Enter'},
});
// Render message.text as textContent; use message.locale and message.direction.
// Preserve raw values and command IDs when the display language changes.目录使用规范 BCP 47 基础标签,以及明确且无环的回退边。最多八项语言偏好先协商确切标签,再协商祖先标签和默认语言。默认语言定义全部键;翻译可省略键,但不能创造新键。逐键查找先遵循有序回退边,再使用默认语言。每项翻译及其参数必须匹配确切的 {name} 占位符集合。这是字面插值,不含 ICU 表达式。resolveMessage 报告实际源语言和方向,因此 RTL 页面中的英语回退内容可保留 lang=en 和 dir=ltr。
数字格式支持小数/百分比;日期格式使用明确的纪元时间,默认 UTC;复数选择返回 Intl 基数/序数类别,由调用者选择消息。宿主负责 Intl 数据和支持。validateLocalizedSurfaces 检查清单/命令/设置/模式键及主题显示附属文件,包括解析后的显示长度和缺失翻译。主题 JSON/XML 保持兼容。目录限制为 32 种语言、256 个键和 256 KiB;静态标签不能包含占位符。
/accessibility 辅助工具报告缺失名称、重复规范化快捷键,以及明亮/深色主题中明确不透明颜色对的对比度。请在实现由宿主负责的操作系统按键绑定及评估无障碍性时使用这些提示。独立示例包含 EN/KO、部分阿拉伯语和长标签测试样本。它测试限定范围设置、被拒绝/撤销的引用、无效字段、Ctrl+Enter,以及待处理命令期间的语言变化。浏览器布局已在桌面/移动尺寸及明亮/深色主题下检查。
npm run example:configuration
npm run example:configuration-browser开发模板与生成
六个模板、确切归档依赖、生成审查、冲突保留和 doctor 检查。
确定性测试与重放
明确的合成测试样本、虚拟时间、故障、有界的仅哈希跟踪和资源清理。
本地诊断与调试
自愿启用的本地配置,以及具有临时环回端点和总期限的可信子进程调试器。
宿主一致性
18 个带版本配置区分受支持、不受支持和失败契约;自定义适配器保留明确权限。
SDK 支持与迁移
查看导出清单、稳定/可选/实验性政策、确切 peer 范围、运行时日期及迁移示例。
发布验收
已发布的版本检查结合故障工作负载和经过测量的性能防护,验证所测试的 SDK 行为。
1.1 依赖、来源与更新工具
1.1.0 增加经审查依赖的确定性离线包、CycloneDX SBOM、使用操作者拥有的 Ed25519 密钥生成的分离签名、绑定摘要的批准/激活/回滚,以及明确的上游比较。五个仅限 Node 的入口包含声明、模式和独立示例。宿主明确授予执行权限,旧作业保留原始哈希值。操作者管理分发、部署和监控。请使用独立示例验证离线包、签名、更新和上游契约。
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjs1.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