Phát triển và phát hành Plugin SDK
Phát triển, xác minh, công cụ phát hành và quy trình 1.2, cache tăng dần, công cụ bên ngoài và cầu nối LSP công khai.
Hướng dẫn phát triển, xác minh và phát hành cho DDS Plugin SDK 1.2.0. Kiểm toán bảo mật và xác thực lỗ hổng đang chờ; trạng thái API ổn định và kiểm tra chức năng không cấu thành nghiệm thu bảo mật.
Mẫu phát triển và sinh dữ liệu
Chọn command, language, theme, job, browser hoặc configuration. init --dry-run báo đích đến, danh mục tệp, hash và xung đột mà không ghi hoặc cài đặt. init thông thường yêu cầu thư mục thực mới. Mỗi mẫu gồm mã nguồn, manifest, công bố thông tin, license/notice, kiểm thử, bên sử dụng có kiểu dữ liệu và ví dụ có thể thực thi. Các mẫu browser và configuration có demo loopback. Phụ thuộc được sinh ghim chính xác tệp nén GitHub.
npx --no-install dds-plugin init example-plugin --template configuration --dry-run
npx --no-install dds-plugin init example-plugin --template configuration
cd example-plugin
npm install --ignore-scripts
npm run doctor
npm test
npm run typecheck
npm run example
npm run browserdds-dev.json là dữ liệu JSON có giới hạn cho schema lệnh, thiết lập, danh mục ngôn ngữ và dữ liệu giao diện. generate xuất JSON runtime, các export ESM, kiểu đầu vào TypeScript thô/đã xác thực, kiểu đầu ra/thiết lập, JSON Schema và XML giao diện. Giá trị mặc định JSON Schema là chú thích; chỉ xác thực đầu vào SDK áp dụng giá trị mặc định. Việc sinh không import plugin của bạn. doctor kiểm tra sai lệch, metadata, module thiếu và việc các tệp runtime được sinh có nằm trong danh sách cho phép của gói hay không.
npx --no-install dds-plugin generate . --check
npx --no-install dds-plugin generate . --dry-run
# Review the new files, then use the previous digest from the report:
npx --no-install dds-plugin generate . --expected-digest <previous-digest>Thay thế yêu cầu đúng digest trước đó và các byte được sinh chưa thay đổi. Chỉnh sửa thủ công, tệp bổ sung, liên kết và khóa cũ ngăn việc thay thế. Khi lỗi, chỉ các mục chưa thay đổi thuộc lần thử đó bị xóa; các mục đã sửa hoặc chưa chắc chắn được giữ để kiểm tra. Tệp giới hạn ở 256, mỗi tệp 1 MiB và tổng 4 MiB. Khóa phối hợp các bộ sinh hợp tác; nó không bảo vệ khỏi bên ghi hệ thống tệp đồng thời thù địch hoặc giao dịch nguyên tử xuyên thư mục. Mẫu độc quyền yêu cầu điều khoản do bên gọi cung cấp và giữ các tệp license/notice SDK kế thừa.
Kiểm thử tất định và phát lại
createScenarioHost từ /testing gắn rõ ràng các fixture tệp, backend, thiết lập, bí mật và job trong bộ nhớ được chọn. Nó bắt đầu không có quyền được cấp hoặc khả năng. createTestClock cung cấp ID có seed, thời gian và timer mà không sửa global; timer cùng thời điểm giữ thứ tự chèn. Await việc tiến thời gian của clock để mở chờ ảo. UUID được sinh là dữ liệu kiểm thử, không phải entropy mật mã. Các giá trị mặc định createTestHost hiện có vẫn tương thích.
import {createScenarioHost} from '@altifigence/dds-plugin-sdk/testing';
const scenario = createScenarioHost({seed: 7, start: 1000,
files: {'example.txt': 'synthetic'}, grants: ['workspace.read'],
});
try {
// Activate your explicitly imported test plugin on scenario.host.
scenario.faults.enqueue({operation: 'file.read', kind: 'delay', delayMs: 25});
// Start its command, then await scenario.clock.advance(25).
} finally {
await scenario.dispose();
scenario.assertClean();
}Các cổng lỗi mô hình hóa trễ, từ chối, ngắt kết nối, hỏng dữ liệu, cạn tài nguyên và lệnh gọi bị bỏ; fixture sự kiện có thể bị bỏ, lặp hoặc đảo thứ tự mà không lặp tác động bên ngoài. replaceGrants vô hiệu hóa plugin mất quyền. Snapshot job bộ nhớ xác thực định danh, revision và hash, đồng thời mô hình hóa khôi phục bị gián đoạn mà không tự thực thi. Các fixture này không mô phỏng độ bền hệ thống tệp hoặc tìm các handle hệ điều hành. Sổ tài nguyên chủ sở hữu riêng theo dõi các tài nguyên được đăng ký rõ ràng. Teardown giữ số lượng đang chờ đối với callback phớt lờ hủy cho đến khi chúng thực sự hoàn tất. Có thể đọc inspect thiết lập sau dispose; đọc dữ liệu vẫn bị từ chối.
Ghi trace yêu cầu synthetic: true và danh mục fixture có giới hạn rõ ràng. Trace được xuất chỉ chứa loại thao tác, ID fixture, timing, seed/phiên bản và hash nối chuỗi. Dùng ID không nhạy cảm; hash không ẩn danh dữ liệu có thể đoán và SDK không thể phân loại đầu vào tùy ý là tổng hợp. Phát lại thuần kiểm tra thứ tự, hash và định danh fixture rồi trả đầu ra fixture được chọn; nó không nhận callback tác động. Giới hạn gồm 64 fixture, 1.024 sự kiện và trace 1 MiB. Chạy ví dụ development-tools đóng gói để kiểm tra lỗi, khôi phục, quyền riêng tư và dọn dẹp.
Chẩn đoán và gỡ lỗi cục bộ
import {createDiagnosticSession, profileHost}
from '@altifigence/dds-plugin-sdk/diagnostics';
const session = createDiagnosticSession({enabled: true, sampleEvery: 10});
const measured = profileHost(host, session);
try {
await measured.executeCommand('example', 'run', {});
} finally {
measured.dispose();
console.log(session.snapshot());
session.dispose();
}Chẩn đoán mặc định tắt và chỉ cục bộ. Báo cáo chứa mã thao tác/trạng thái/lỗi cố định, ID tương quan, thời lượng và số lượng tài nguyên; không có API cho nội dung tài liệu, đường dẫn, đầu vào, nội dung đầu ra hoặc văn bản ngoại lệ tùy ý. Số byte, độ sâu hàng đợi và số liệu bộ nhớ là ước tính rõ ràng của chủ sở hữu. profileTransport đo đến khi lệnh gọi được bọc resolve; với fetch là lúc nhận header phản hồi, không phải hoàn tất nội dung. Bản ghi hoàn tất dùng vòng đệm có giới hạn và hết hạn thụ động; không có timer chẩn đoán nền hoặc tải lên. Mặc định 128 sự kiện/60 giây; tối đa 256 sự kiện/5 phút, 64 span đang diễn ra và 256 KiB mỗi báo cáo.
npx --no-install dds-plugin dev . --trust-local-code --profile --command greet --input '{"name":"Ada"}'
npx --no-install dds-plugin dev . --trust-local-code --debug --debug-wait --timeout-ms 30000 --command greet --input '{"name":"Ada"}'Chế độ debug chỉ cung cấp inspector 127.0.0.1 tạm thời trong tiến trình con thuộc sở hữu. --debug-wait tạm dừng trước khi import plugin và yêu cầu --debug. Ngân sách chạy tổng bao gồm chờ debugger và tối đa 30 giây. Hoàn tất, hủy và hết thời gian chấm dứt tiến trình con cùng inspector thuộc sở hữu. Cả profiling và debug đều yêu cầu tin cậy mã cục bộ rõ ràng; cả hai không phải sandbox. Crash hoặc chấm dứt cưỡng bức có thể làm thiếu báo cáo profile, và stdout/stderr thô của plugin vẫn là luồng có giới hạn riêng không tự động che dữ liệu nhạy cảm.
Công cụ phát triển · Kiểm thử · Chẩn đoán · Tương thích
Tính tuân thủ của máy chủ
Module /conformance chạy các phép thử tổng hợp có phiên bản trên những adapter host, settings, workspace, localization, testing, diagnostics và development bạn cung cấp rõ ràng. Nó phân biệt hồ sơ được hỗ trợ, không được hỗ trợ và thất bại, đồng thời ghi máy chủ/phiên bản/runtime/nền tảng, ID kiểm tra, timing và dọn dẹp. Tính năng được khai báo với adapter thiếu hoặc hỏng sẽ thất bại; tính năng tùy chọn chưa biết được ghi lại mà không thử. Lệnh, quyền và hủy là bắt buộc theo mặc định.
import {runConformance, formatConformanceReport}
from '@altifigence/dds-plugin-sdk/conformance';
import {createPluginHost} from '@altifigence/dds-plugin-sdk';
const report = await runConformance({
identity: {host: 'My host', version: '1.0.0', runtime: 'Node 24', platform: 'linux-x64'},
features: ['commands', 'permissions', 'cancellation'],
adapters: {host: options => createPluginHost(options)},
});
console.log(formatConformanceReport(report));Thay host factory bằng adapter của bạn và cũng chạy kiểm thử plugin. Helper Node /conformance-node chỉ tạo fixture tạm mới và máy chủ loopback tạm thời. Ví dụ trình duyệt chạy các hồ sơ trình duyệt có sẵn và báo tính năng Node vắng mặt là không được hỗ trợ. Các phép thử nhanh lấy mẫu hợp đồng; ví dụ liên kết và kiểm thử phát hành bao phủ các đường ngôn ngữ, khôi phục và lưu trữ lớn hơn. Báo cáo là bằng chứng kiểm thử, không phải chứng nhận tin cậy.
Thời hạn mặc định 10 giây mỗi trường hợp, tối đa 30 giây. Hết thời gian hoặc hủy ngăn các trường hợp sau; dọn dẹp thất bại làm trường hợp thất bại, và dọn dẹp đang chờ vẫn chưa được xác minh. Adapter tin cậy trong cùng tiến trình có thể chặn đồng bộ và giữ quyền môi trường. Báo cáo loại bỏ nội dung lỗi nhà cung cấp, payload, token và đường dẫn; chọn nhãn định danh không nhạy cảm. Không báo cáo nào tự động được tải lên.
Hỗ trợ và di chuyển SDK
API_SUPPORT.json liệt kê mọi module export, tên runtime, khai báo, digest khai báo, môi trường và độ ổn định. API 1.x ổn định tuân theo phiên bản ngữ nghĩa: bổ sung tương thích dùng bản minor và thay đổi ổn định không tương thích yêu cầu bản major mới. artifact-resume-browser vẫn thử nghiệm và cần phiên bản SDK/trình duyệt chính xác cùng nghiệm thu trình duyệt mới. Vẫn cần khám phá khả năng tùy chọn và quyền hiện tại.
Chính sách dòng ổn định áp dụng từ 1.0.0. Bản minor ổn định mới nhất nhận sửa lỗi thông thường; bản minor trước vẫn đủ điều kiện nhận sửa lỗi bảo mật nghiêm trọng trong 90 ngày trên runtime được hỗ trợ. Không API ổn định nào bị đánh dấu ngừng dùng trong 1.0.0. Việc ngừng dùng được thông báo trong ít nhất hai bản minor và sáu tháng trước khi loại bỏ ở bản major. RC và preview được thay thế. Chính sách mã nguồn mở này không hứa thời gian phản hồi thương mại.
Nghiệm thu máy chủ và CLI bao gồm Windows/Linux với Node 22 hoặc 24 đã vá, cùng khai báo với TypeScript 5.9.3. Hỗ trợ Node 22 kết thúc ngày 2027-04-30 và Node 24 ngày 2028-04-30. Biên nhận phát hành xác định chính xác phiên bản patch, ảnh hệ điều hành và build trình duyệt. Các runtime khác và tổ hợp trình duyệt/lưu trữ cần nghiệm thu riêng. SDK vẫn không có phụ thuộc npm runtime.
Plugin 1.0 ổn định dùng >=1.0.0 <2.0.0; nâng mức tối thiểu khi sử dụng API mới hơn. Gói RC1 giữ peer chính xác 1.0.0-rc.1. Xác thực lại và công bố phiên bản plugin mới để thay đổi; giữ các tệp nén trước bất biến. Tệp nén cũ là đầu vào tương tác tương thích, không phải dòng được duy trì. Sau khi khởi động lại, thiết lập kết nối mới và quyền được cấp hiện tại; khôi phục đọc trạng thái đã commit mà không chạy lại công việc.
Nghiệm thu phát hành
Kiểm toán bảo mật và xác thực lỗ hổng đang chờ theo quyết định hoãn của chủ sở hữu ngày 2026-10-05. Kết quả chức năng, tương thích và hiệu năng không cấu thành nghiệm thu bảo mật. Việc rà soát được giữ lại sẽ tiếp tục riêng; không được mô tả bản phát hành này đã vượt qua kiểm toán đó.
Fixture kết hợp đồng thời kiểm tra ngôn ngữ/thiết lập, chỉnh sửa đã rà soát, job lệnh, theo dõi dự án, tải lên/tải xuống và lưu trữ giữ lại. Nó kiểm tra gián đoạn, phản hồi sai định dạng, thu hồi quyền, thay đổi generation, khôi phục và dọn tài nguyên. Kiểm thử hệ thống tệp/tiến trình riêng bao gồm tiến trình con bị dừng, hỏng dữ liệu, ghi lỗi, hết hạn và phớt lờ hủy. Báo cáo nghiệm thu RC liên kết các lệnh tái lập được và ranh giới từng kết quả.
Hiệu năng ghi năm mẫu tiến trình mới cho mỗi hồ sơ Windows/Linux và Node 22/24, gồm trung vị/độ phân tán, thời gian CPU, bộ nhớ lấy mẫu, timing import/khởi động/theo dõi và số payload đĩa/HTTP logic. Ngưỡng cơ sở lấy từ các mẫu đã đo và là hàng rào hồi quy thô, không phải SLA độ trễ. Chúng không đo lưu lượng đĩa vật lý hoặc bảo đảm tìm ra mọi handle hệ điều hành.
npm ci --ignore-scripts
npm run check
npm run example:conformance -- --json
npm run example:combined -- --faults
npm run benchmark:combined
npm run example:conformance-browserTuân thủ · Danh mục API · Chính sách hỗ trợ · Nghiệm thu RC
Nội dung bản phát hành 1.0 ổn định
Gói 1.0 ban đầu gồm 38 export và 86 schema với khai báo, ví dụ, LICENSE và NOTICE. 1.1 thêm các công cụ phát hành bên dưới; 1.2 thêm các phần workflow/cache/tool/LSP bên dưới. Biên nhận phát hành phân biệt chính xác mã nguồn/CI/digest, các bên sử dụng mới và bằng chứng trình duyệt được dùng lại.
Để hạ phiên bản, dừng công việc thuộc sở hữu và chọn rõ ràng các tệp nén SDK/plugin tương thích đã giữ lại cùng bản xuất cấu hình. Xem lại quyền hiện tại và tạo kết nối mới. Khôi phục kết quả chỉ đọc lại; tác động bên ngoài và thiết lập không tương thích không được tự động hoàn tác. Kiểm thử các định dạng và tính năng tùy chọn thực sự được dùng.
Nội dung phát hành, di chuyển và hỗ trợ
Bundle ngoại tuyến và SBOM
SDK 1.1 thêm năm điểm vào tùy chọn chỉ dành cho Node: /bundles, /provenance, /updates, /updates-node và /upstream. Gói chứa 43 export, 96 schema, khai báo và ví dụ có thể chạy mà không có phụ thuộc npm runtime. API 1.0 hiện có và tệp nén DDS .tgz chưa ký vẫn tương thích.
lockBundleDependency khóa cây tệp ESM/CommonJS đã rà soát vào phiên bản chính xác, nguồn HTTPS, digest tệp chuẩn tắc, bản đồ phụ thuộc, LICENSE/NOTICE và quyết định phân phối lại rõ ràng. Digest mô tả cây đã rà soát; không phải hash tệp nén upstream. createPluginBundle nhúng tệp nén plugin DDS gốc và metadata phát hành, đồ thị phụ thuộc không chu trình với một phiên bản mỗi gói và SBOM CycloneDX 1.6 tất định.
verifyPluginBundle kiểm tra chính xác snapshot byte có giới hạn. installPluginBundle yêu cầu expectedSha256, approved: true và thư mục mới dưới thư mục cha thuộc quyền điều hành. Nó không chạy npm, script vòng đời, tải xuống hoặc mã plugin. Các phụ thuộc không kế thừa quyền mới. SDK máy chủ là phụ thuộc riêng. Addon native, export map và giải phụ thuộc npm tùy ý nằm ngoài định dạng này.
Giới hạn: 32 gói phụ thuộc, 1.024 tệp sau mở rộng, 4 MiB mỗi tệp phụ thuộc, 32 MiB nội dung sau mở rộng và 48 MiB bundle đã mã hóa. Tệp nén gốc có giới hạn nhỏ hơn riêng. Phiên bản thiếu hoặc xung đột, chu trình, phụ thuộc mồ côi, hash thay đổi, thiếu license/NOTICE, đường dẫn/liên kết và xung đột tệp-thư mục bị từ chối. Cài đặt lỗi giữ đích mới để kiểm tra. Loại trừ các bên ghi đồng thời; công cụ này không phải sandbox hệ điều hành.
Chữ ký tách rời và sự tin cậy của người vận hành
createProvenanceStatement ràng buộc chính xác tên/phiên bản/SHA-256 bundle, nhà phát hành, revision nguồn và thời điểm cấp/hết hạn. signPluginProvenance dùng Ed25519 KeyObject thuộc bên gọi. canonicalProvenancePayload cung cấp DDS-PROVENANCE-V1 tiếp theo là JSON chuẩn tắc để bên ký khác tái tạo cùng payload. SDK không cung cấp khóa ký riêng hoặc thẩm quyền ký sản phẩm DDS.
verifyPluginProvenance nhận gốc tin cậy do người vận hành chọn, ràng buộc nhà phát hành/chủ thể, thời gian hiện tại, hiệu lực/thu hồi khóa và bằng chứng thu hồi có dấu thời gian. Xác minh ngoại tuyến dùng bằng chứng được cung cấp và áp dụng cùng ngân sách độ mới; nó không tự lấy thông tin thu hồi mới. Khóa gói mới chưa được tin cậy cho đến khi người vận hành thêm. Các gốc chồng lấn rõ ràng hỗ trợ luân chuyển. Lệch clock tối đa năm phút và tuổi bằng chứng tối đa 30 ngày; chọn giới hạn chặt hơn khi cần.
Biên nhận giữ checksum, chữ ký, nhà phát hành và chính sách riêng, đồng thời luôn trả executionAuthorized: false. Chữ ký không chứng minh mã an toàn hoặc cấp quyền thực thi, truy cập dữ liệu hay quyền sandbox. Gói chưa ký cũ yêu cầu envelope: null và allowUnsigned: true, vẫn báo chưa ký và nhà phát hành chưa xác minh. Kiểm toán bảo mật và xác thực lỗ hổng tiếp tục chờ độc lập.
Rà soát, kích hoạt và quay lui
createPluginUpdatePlan so sánh phiên bản cũ/mới, API, quyền được cấp, nguồn/hash phụ thuộc, công cụ khai báo, license, hash thiết lập, định danh di chuyển, chữ ký và khóa, rồi cố định digest rà soát. createPluginUpdateController sở hữu máy chủ và thiết lập hiện đang được ủy quyền cùng các cổng getPolicy/prepare của người vận hành. Stage xác minh và chụp snapshot ứng viên; approve phải khớp chính xác digest kế hoạch, quyền và ID khóa. Activate kiểm tra thiết lập hiện tại và làm mới tin cậy trước và sau khi chuẩn bị máy chủ ứng viên riêng.
wait hoãn kích hoạt khi có job đang chạy. retain-old giữ job cũ trên máy chủ/thiết lập/hash ban đầu và đưa các lần thực thi mới sang máy chủ mới sau chuyển đổi. execute trả hash plugin cùng từng kết quả. Job không bị hủy ngầm. Thay thế thiết lập vô hiệu hóa phê duyệt đang chờ; thay đổi đồng thời và chuẩn bị thất bại bảo toàn hoặc báo rõ trạng thái trước. Quay lui đặt gói/thiết lập cũ thành cập nhật mới được rà soát và yêu cầu tin cậy hiện tại cùng phê duyệt mới.
Chuẩn bị và di chuyển chạy qua các cổng tin cậy do người vận hành sở hữu. Quay lui hay lỗi đều không hoàn tác tệp bên ngoài, yêu cầu mạng hoặc tác động khác. reversible là metadata rà soát thay vì lời hứa hoàn tác tự động. Journal Node chỉ thêm, một bên ghi và nằm ngoài không gian làm việc, với CAS revision chính xác và giới hạn 256 bản ghi / 128 KiB mỗi envelope / tổng 8 MiB. Lưu trữ dưới quyền điều hành trước khi mở journal mới khi đạt giới hạn.
inspectNodeUpdateJournal đọc trạng thái lưu bền mà không phát lại. Crash trong lúc preparing hoặc xác nhận mơ hồ yêu cầu đọc lại máy chủ/thiết lập rõ ràng; reconcilePluginUpdateJournal ghi digest cũ/mới đã biết được phê duyệt cùng hash thiết lập. Phần đuôi hỏng cần người vận hành kiểm tra/sửa. recoverStaleLock chỉ khôi phục bên ghi trên cùng máy đã chứng minh không còn sống. Điều này không hứa giao dịch máy chủ/thiết lập xuyên tiến trình hoặc tính nguyên tử khi mất điện phổ quát.
Kiểm tra upstream và ứng viên rõ ràng
fetchUpstreamArtifact cần lời gọi rõ ràng, enabled: true, URL nguồn/phiên bản/digest chính xác, danh sách URL cho phép chính xác, chính sách ngoại tuyến, ngân sách byte và thời hạn. Đích chuyển hướng cũng phải được cho phép. Nó không gửi cookie hoặc header xác thực, không tự thử lại và báo verified / digest-mismatch / unavailable / offline / unverified cùng thời gian quan sát. Tag hoặc hash thay đổi cần rà soát mới. HTTP loopback chỉ khả dụng qua tùy chọn fixture rõ ràng.
Adapter có thể công bố upstream-manifest đã rà soát chứa danh mục API, revision nguồn chính xác, license/NOTICE đầy đủ và hash tệp. inspectUpstreamManifest ràng buộc metadata đó với byte đã tải; nó không phân tích mã nguồn tùy ý hoặc suy luận quyền phân phối lại. createUpstreamCandidate trả khác biệt API/tệp/license cùng patch before-digest/replacement-source. Khớp ma trận phiên bản chính xác mà chưa có kiểm tra chức năng của nhà phát triển vẫn chưa được xác minh; thiếu API bắt buộc là không được hỗ trợ.
Ứng viên được hỗ trợ vẫn cần con người rà soát. Mảng automaticActions của nó rỗng; các API này không tạo nhánh, merge, công bố, phê duyệt quyền mới hoặc cài monitor. Máy chủ sở hữu việc thực thi kiểm thử adapter và hủy. Ví dụ công khai đầy đủ bên dưới chỉ kiểm tra fixture cục bộ. API workflow/cache/tool/LSP có sẵn trong các phần 1.2 bên dưới.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjsKiểu dữ liệu, API, giới hạn và mã nguồn đầy đủ có thể chạy
Quy trình lệnh và khôi phục rõ ràng
SDK 1.2 thêm bảy export tùy chọn: /workflows, /workflows-node, /workflow-cache, /workflow-cache-node, /tool-streams, /tool-streams-node và /lsp-node. Gói hiện tại có 50 export, 107 schema, khai báo TypeScript và các ví dụ đã cài độc lập, không có phụ thuộc npm runtime. Chỉ /tool-streams dùng được trên trình duyệt; các export mới khác yêu cầu Node. Giao thức không gian làm việc hiện có và API 1.x vẫn tương thích. Plugin import API 1.2 mới phải khai báo 1.2.0 là phiên bản SDK tối thiểu.
prepareWorkflowPlan xác thực ID lệnh đã đăng ký, các bước duy nhất, phụ thuộc không chu trình, schema dữ liệu đầu vào/đầu ra đóng và các ràng buộc đầu ra bắt buộc trước thực thi. Mỗi đầu vào là literal {value} hoặc ràng buộc {step, path} đến phụ thuộc rõ ràng. Ràng buộc schema phải khớp chính xác. Kế hoạch bất biến ràng buộc lệnh, quyền, phạm vi và đầu vào vào SHA-256. run yêu cầu approved: true và đúng digest đã rà soát đó. Các cổng authorize và execute máy chủ vẫn thuộc người vận hành.
createCommandJobExecutor kết nối PluginHost hiện có được cô lập do resolveHost chọn, trả về chính xác phạm vi máy chủ, quyền bước và hash plugin. Quyền không bao giờ được kết hợp giữa các bước. Ủy quyền hiện tại được kiểm tra trước thực thi, sau kết quả và trước tái sử dụng. continue hoàn thành các nhánh độc lập và chặn các bước con của nhánh lỗi; fail-fast hủy các bước còn lại. Bản ghi giữ ID job/lần thử cha, từng job, digest đầu vào/đầu ra, hiện vật, lý do và dấu thời gian. Cache hit không có ID job mới và không thể tuyên bố các hiện vật job có thể thay đổi.
recover đọc checkpoint đã lưu và báo công việc pending/running là bị gián đoạn mà không thực thi. Resume thủ công cung cấp đúng bản ghi trước cùng previousAttemptId trong phê duyệt mới, tạo lần thử mới và chỉ giữ các kết quả thành công khớp và chưa hết hạn. retrySteps chạy lại các bước được chọn và con của chúng kể cả trong DAG không có thứ tự. Đầu ra hết hạn cần chọn retry rõ ràng; schema, đầu vào, quyền hoặc hash plugin thay đổi cần kế hoạch mới. Executor phớt lờ hủy vẫn được tính chưa hoàn tất và ngăn retry chồng lấn.
createNodeWorkflowStore dùng thư mục store/workspace thực, rời nhau, phạm vi và dấu định danh hệ thống tệp, một bên ghi, envelope có checksum và checkpoint CAS. Sau crash đã biết, recoverStaleLock rõ ràng chỉ chấp nhận chủ sở hữu cùng máy đã chứng minh không còn sống. Dọn dẹp mặc định xử lý bản ghi hỏng đã nhận diện và ghi chưa hoàn tất, giữ tệp/liên kết chưa biết. cleanup({expiredBefore}) cũng có thể xóa bản ghi trạng thái cuối đã hết hạn; bản ghi hoạt động được giữ để khôi phục. Windows không tuyên bố fsync thư mục hoặc độ bền khi mất điện. Giới hạn: 64 bước, 8 bước đồng thời, thời hạn quy trình 10 phút, 64 KiB mỗi kết quả, 1 MiB đầu ra kết hợp, bản ghi 2 MiB, 64 bản ghi giữ lại và lưu kết quả một phần tối đa 24 giờ.
Kiểu dữ liệu, API, giới hạn và ví dụ đầy đủ có thể chạy
Cache tất định và thực thi tăng dần
fingerprintWorkflowInputs hash các byte tệp thực tế cùng phiên bản SDK, phạm vi không gian làm việc/bảo mật, schema/đầu vào lệnh, hash plugin/công cụ, thiết lập, môi trường khai báo và quyền. Chỉ mtime và đường dẫn không bao giờ là định danh nội dung. Người vận hành khai báo rõ optIn, deterministic, declaredInputsComplete và secretDependent. Đầu vào chưa biết hoặc thiếu, không tất định, phụ thuộc bí mật, môi trường thiếu/chưa khai báo và đầu vào tham chiếu bí mật bỏ qua cache với lý do. Máy chủ cũng phải loại trừ bí mật thô và tác động phụ; SDK không thể suy luận đầu vào ẩn.
createWorkflowCache kiểm tra lại ủy quyền hiện tại khi lookup/fill/after-fill/hit/return, đồng thời xác minh hash giá trị, phạm vi, quyền và hạn dùng. Các miss đủ điều kiện đồng thời chia sẻ một fill; hủy một bên chờ không hủy các bên khác. Giá trị hết hạn hoặc hỏng là miss. TTL/LRU, ngân sách mục/giá trị và dọn store thuộc sở hữu kiểm soát lưu trữ; lỗi ghi vẫn trả kết quả đã tính cùng lý do rõ ràng. Kết quả tham chiếu bí mật không bao giờ được giữ. Giới hạn fingerprint là 64 tệp, mỗi tệp 4 MiB và tổng 16 MiB; giới hạn cache là 512 mục, 16 MiB byte giá trị giữ lại, tám fill và 60 giây mỗi fill.
Ví dụ workflow chỉ tra cache sau khi các phụ thuộc hiện tại thành công. Tệp thay đổi vô hiệu hóa bước của nó; đầu ra thay đổi vô hiệu hóa fingerprint đầu vào phụ thuộc. Phụ thuộc thất bại chặn bước cha trước khi tra kết quả cha trong cache. Biên nhận phân biệt hit, miss, shared và bypass, thực thi thực tế với tái sử dụng, bộ đếm cache, byte lưu trữ và timing cục bộ. Trạng thái cache bền vững dùng thư mục chủ sở hữu rời nhau và thay thế nguyên tử, có khôi phục ghi mồ côi/hỏng dữ liệu; nó không xóa tệp nguồn.
Kiểu dữ liệu, API, giới hạn và ví dụ đầy đủ có thể chạy
Luồng đầu ra công cụ đã đăng ký
createToolStreamParser là bộ giải mã UTF-8 JSONL/văn bản có giới hạn, dùng được trên nhiều môi trường. Await write(bytes, stdout/stderr) để có backpressure và chỉ finish sau khi cả hai luồng kết thúc. Nó bảo toàn ký tự nhiều byte bị chia và dòng cuối chưa trọn, phát các sự kiện log, progress, diagnostic và unknown tương quan. UTF-8 sai hoặc đạt giới hạn cứng ngừng phân tích. Đường dẫn chẩn đoán tương đối, vị trí có thứ tự và mức nghiêm trọng được xác thực; trình soạn thảo sử dụng cũng phải xác thực vị trí với văn bản tài liệu hiện tại. createJobToolEventSink nối tiến độ/nhật ký với JobReporter hiện có và để chẩn đoán cho sink thuộc bên gọi.
Runner Node tùy chọn nhận các đăng ký cố định của người vận hành: backend/tool/version, executable tuyệt đối và các pin triển khai được chọn, phép thử phiên bản chính xác, môi trường rõ ràng, schema đầu vào đóng và các vị trí đối số scalar bắt buộc. Vị trí tệp phải nêu tệp tương đối hiện có trong không gian làm việc. Lời gọi plugin chỉ chọn công cụ/phiên bản đã đăng ký và đầu vào đã xác thực; không thể chọn shell hoặc executable. Ủy quyền hiện tại được kiểm tra trước chuẩn bị/bắt đầu, tại sự kiện và sau hoàn tất. Biên nhận giữ mã thoát, lý do hủy/lỗi và thống kê đầu ra.
Literal bí mật/đường dẫn một dòng đã biết được che sau khi ghép dòng, kể cả phần bị chia; bí mật mã hóa hoặc chưa biết không tự động được phát hiện. Runner chỉ sở hữu tiến trình con trực tiếp/các pipe và đóng chúng khi hủy hoặc close. Nó không quét hay dừng cây tiến trình không liên quan hoặc tiến trình hậu duệ, và không phải sandbox hệ điều hành. Giới hạn: chunk 64 KiB, dòng 16 KiB, tổng đầu ra 2 MiB, 4.096 sự kiện, tám lần ghi xếp hàng, sink năm giây, 32 công cụ và bốn lần thực thi đồng thời. Phép thử riêng năm giây/16 KiB kiểm tra phiên bản đã cấu hình.
Fixture công cụ do SDK tạo và được phân phối lại kiểm thử UTF-8/JSONL phân mảnh, đầu ra cuối, thoát khác không, hủy và giới hạn. Adapter thực tế là TypeScript 5.9.3 với --noEmit --noLib --pretty false cùng fixture intrinsic-types dùng một lần tạo TS2322. Cung cấp rõ root TypeScript đã phê duyệt hiện có để chạy. SDK không bao giờ tự cài hoặc tải công cụ bên ngoài; hash được cung cấp không tự xác thực độc lập nhà phát hành.
Kiểu dữ liệu, API, giới hạn và ví dụ đầy đủ có thể chạy
Cầu nối LSP stdio công khai
createLspBridge nối tiến trình stdio được ghim và phê duyệt rõ ràng với các yêu cầu/provider ngôn ngữ SDK hiện có. Nó thương lượng tập con LSP 3.17 được hỗ trợ, vị trí UTF-16 và snapshot đầy đủ. capabilities báo hỗ trợ được quảng bá riêng với thực thi thành công. Ánh xạ hỗ trợ gồm completion, hover, definition, references, symbol phẳng/phân cấp, signature help, prepare-rename/rename, định dạng tài liệu/phạm vi, code action, semantic token đầy đủ, folding và inlay hint: 15 tính năng SDK.
syncDocument và closeDocument xử lý didOpen/didChange/didClose. Thay đổi phiên bản và generation hiện tại hủy công việc cũ, ID yêu cầu hoạt động trùng lặp bị từ chối và phản hồi muộn bị bỏ qua. URI cục bộ phải phân giải bên trong không gian làm việc không có liên kết; mã nguồn và đích chỉnh sửa yêu cầu ủy quyền hiện tại cùng snapshot chính xác đang mở hoặc do máy chủ cung cấp. Kết quả rename/format/action là đề xuất chỉnh sửa không gian làm việc có điều kiện với hash cơ sở, không bao giờ là chỉnh sửa tự áp dụng hoặc lệnh thực thi.
Chẩn đoán chỉ được chấp nhận với phiên bản tài liệu hiện tại. Thông báo không có phiên bản/đã cũ bị bỏ và đếm. Những tính năng không được hỗ trợ rõ ràng là completion resolve/snippet, code-action resolve, semantic delta, lệnh máy chủ, khả năng động, thao tác tài nguyên, truyền tải socket và chẩn đoán không có phiên bản. workspace/applyEdit trả applied:false. Giới hạn: thông điệp 1 MiB, header 8 KiB, phiên 64 MiB/20.000 thông điệp, 16 yêu cầu đang chờ và ghi xếp hàng, 32 tài liệu/tổng văn bản 4 MiB, thời hạn yêu cầu tối đa 30 giây và stderr bị bỏ 64 KiB.
close gửi shutdown/exit và thực hiện dọn tiến trình trực tiếp/pipe có giới hạn, phân biệt xác nhận đóng nhẹ nhàng, máy chủ từ chối/crash và việc tiến trình thực sự đóng. Máy chủ có thể xác nhận shutdown nhưng vẫn cần dừng tiến trình thuộc sở hữu. Không có tự khởi động lại hoặc phát lại: người vận hành tạo cầu nối mới và gửi lại rõ ràng các snapshot hiện tại được chọn. Kiểm thử tổng hợp bao phủ framing sai, crash/hết thời gian, hủy/phản hồi muộn, race tài liệu, từ chối shutdown, yêu cầu không được hỗ trợ và mọi tính năng đã ánh xạ.
Kiểm tra máy chủ độc lập thực tế dùng typescript-language-server cộng đồng 5.3.0 với TypeScript 5.9.3: completion, hover, definition, references, symbols, signature help, formatting và semantic tokens đều đạt. Các tệp triển khai được chọn và Node được ghim, đường dẫn tsserver cố định và tự lấy typings bị tắt. Phiên bản máy chủ này bỏ initialize.serverInfo tùy chọn và gửi chẩn đoán không có phiên bản, nên chẩn đoán của nó rõ ràng không được cầu nối này hỗ trợ; chẩn đoán có phiên bản được xác minh bằng máy chủ tổng hợp độc lập. Người vận hành phải tin cậy toàn bộ công cụ đã cài và quyền truy cập hệ điều hành của nó.
Nghiệm thu 1.2 gồm các bên sử dụng gói độc lập, khai báo, 107 schema, các adapter compiler/server thực tế và tương tác tương thích với tệp nén công khai lịch sử. Ví dụ workflow phân biệt khôi phục bền vững và retry rõ ràng với phát lại tự động. Kiểm toán bảo mật và xác thực lỗ hổng đang chờ theo quyết định hoãn của chủ sở hữu. Bản phát hành này không cấu thành nghiệm thu DDS UI, Engine, bộ lập lịch Cloud, Marketplace, trình cài đặt hoặc sandbox bảo mật.
Kiểu dữ liệu, API, giới hạn và ví dụ đầy đủ có thể chạy
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
node node_modules/@altifigence/dds-plugin-sdk/examples/tool-streams-browser/serve.mjsĐối với adapter thực tế, thêm đường dẫn tuyệt đối đến các bản cài hiện có đã được người vận hành phê duyệt. Ví dụ mặc định chỉ dùng fixture do SDK tạo và không bao giờ tải công cụ.
node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs --typescript-root /absolute/path/to/typescript
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs --typescript-root /absolute/path/to/typescript --language-server-root /absolute/path/to/typescript-language-server