dsh-data-domain-knowledge 0.1.0-alpha.12 → 0.1.0-alpha.13

package/lib/types/images.d.ts

@@ -0,0 +1,26 @@
+/** Maximum decoded image size accepted by `images.publish`. */
+export declare const MAX_PUBLISHED_IMAGE_BYTES: number;
+export declare class ImagePublishError extends Error {
+    readonly code: string;
+    readonly suggestion?: string | undefined;
+    constructor(code: string, message: string, suggestion?: string | undefined);
+}
+export interface PublishKnowledgeImageInput {
+    filePath?: unknown;
+    contentBase64?: unknown;
+    filename?: unknown;
+    mimeType?: unknown;
+}
+export interface PublishedKnowledgeImage {
+    kb: string;
+    filename: string;
+    path: string;
+    url: string;
+    markdown: string;
+    mimeType: string;
+    bytes: number;
+    sha256: string;
+}
+/** Store one validated image using the knowledge assets content-hash bucket layout. */
+export declare function publishKnowledgeImage(rootDir: string, kb: string, input: PublishKnowledgeImageInput): Promise<PublishedKnowledgeImage>;
+//# sourceMappingURL=images.d.ts.map

package/lib/types/images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../src/images.ts"],"names":[],"mappings":"AAMA,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,QAAmB,CAAA;AAYzD,qBAAa,iBAAkB,SAAQ,KAAK;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAmB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM;gBAA3D,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAW,UAAU,CAAC,EAAE,MAAM,YAAA;CAIjF;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAuED,uFAAuF;AACvF,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAoFlC"}

package/lib/types/images.js

@@ -0,0 +1,196 @@
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { ASSETS_DIR, PUBLISHED_IMAGE_MARKER } from './layout.js';
+import { writeBufferAtomic, writeTextAtomic } from './fs-atomic.js';
+/** Maximum decoded image size accepted by `images.publish`. */
+export const MAX_PUBLISHED_IMAGE_BYTES = 20 * 1024 * 1024;
+const IMAGE_FORMATS = [
+    { mimeType: 'image/png', extension: '.png' },
+    { mimeType: 'image/jpeg', extension: '.jpg' },
+    { mimeType: 'image/gif', extension: '.gif' },
+    { mimeType: 'image/webp', extension: '.webp' },
+    { mimeType: 'image/avif', extension: '.avif' },
+    { mimeType: 'image/bmp', extension: '.bmp' },
+    { mimeType: 'image/svg+xml', extension: '.svg' },
+];
+export class ImagePublishError extends Error {
+    code;
+    suggestion;
+    constructor(code, message, suggestion) {
+        super(message);
+        this.code = code;
+        this.suggestion = suggestion;
+        this.name = 'ImagePublishError';
+    }
+}
+function invalid(message, suggestion) {
+    throw new ImagePublishError('IMAGE_INVALID', message, suggestion);
+}
+function normalizeMimeType(value) {
+    const mimeType = value.split(';', 1)[0].trim().toLowerCase();
+    return mimeType === 'image/jpg' ? 'image/jpeg' : mimeType;
+}
+function detectImageMimeType(bytes) {
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return 'image/png';
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return 'image/jpeg';
+    if (bytes.length >= 6 && (bytes.toString('ascii', 0, 6) === 'GIF87a' || bytes.toString('ascii', 0, 6) === 'GIF89a'))
+        return 'image/gif';
+    if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP')
+        return 'image/webp';
+    if (bytes.length >= 12 && bytes.toString('ascii', 0, 2) === 'BM')
+        return 'image/bmp';
+    if (bytes.length >= 12 && bytes.toString('ascii', 4, 8) === 'ftyp') {
+        const brands = bytes.toString('ascii', 8, Math.min(bytes.length, 32));
+        if (/(?:avif|avis)/.test(brands))
+            return 'image/avif';
+    }
+    // SVG is text, so recognize its root element after an optional XML declaration.
+    const text = bytes.toString('utf8', 0, Math.min(bytes.length, 4096)).replace(/^\uFEFF/, '').trimStart();
+    if (/^(?:<\?xml\b[^>]*>\s*)?<svg(?:\s|>)/i.test(text))
+        return 'image/svg+xml';
+    return undefined;
+}
+function decodeBase64(value) {
+    let encoded = value.trim();
+    let declaredMimeType;
+    if (encoded.startsWith('data:')) {
+        const match = /^data:([^;,]+);base64,([\s\S]*)$/i.exec(encoded);
+        if (!match)
+            invalid('content_base64 的 Data URI 格式无效。', '传标准 Base64，或传 data:image/png;base64,... 形式。');
+        declaredMimeType = normalizeMimeType(match[1]);
+        encoded = match[2];
+    }
+    encoded = encoded.replace(/\s+/g, '');
+    if (encoded.length > Math.ceil(MAX_PUBLISHED_IMAGE_BYTES * 4 / 3) + 8) {
+        throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`);
+    }
+    if (encoded.length % 4 === 1 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}={0,2}|[A-Za-z0-9+/]{3}=?)?$/.test(encoded)) {
+        invalid('content_base64 不是有效的 Base64。');
+    }
+    const bytes = Buffer.from(encoded, 'base64');
+    if (bytes.length === 0)
+        invalid('图片内容不能为空。');
+    if (bytes.length > MAX_PUBLISHED_IMAGE_BYTES) {
+        throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`);
+    }
+    if (bytes.toString('base64').replace(/=+$/, '') !== encoded.replace(/=+$/, ''))
+        invalid('content_base64 不是有效的 Base64。');
+    return { bytes, ...(declaredMimeType ? { declaredMimeType } : {}) };
+}
+function safeFilename(value, fallback, extension) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    const leaf = (raw.replace(/\\/g, '/').split('/').pop() ?? '').replace(/[\u0000-\u001f\u007f]/g, '');
+    const suppliedExtension = extname(leaf);
+    const stem = (suppliedExtension ? leaf.slice(0, -suppliedExtension.length) : leaf)
+        .replace(/[^\p{L}\p{N}._ -]/gu, '_')
+        .replace(/\s+/g, '-')
+        .replace(/^\.+$/, '')
+        .slice(0, 120);
+    return `${stem || fallback}${extension}`;
+}
+async function readExisting(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (cause) {
+        if (cause?.code === 'ENOENT')
+            return undefined;
+        throw cause;
+    }
+}
+/** Store one validated image using the knowledge assets content-hash bucket layout. */
+export async function publishKnowledgeImage(rootDir, kb, input) {
+    const filePath = typeof input.filePath === 'string' ? input.filePath.trim() : '';
+    const base64 = typeof input.contentBase64 === 'string' ? input.contentBase64 : '';
+    if (Boolean(filePath) === Boolean(base64)) {
+        invalid('file_path 和 content_base64 必须且只能提供一个。');
+    }
+    let bytes;
+    let sourceName = '';
+    let dataUriMimeType;
+    if (filePath) {
+        let details;
+        try {
+            details = await stat(filePath);
+        }
+        catch (cause) {
+            throw new ImagePublishError('IMAGE_SOURCE_NOT_FOUND', `图片文件无法读取：${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        if (!details.isFile())
+            throw new ImagePublishError('IMAGE_SOURCE_NOT_FILE', 'file_path 必须指向一个文件。');
+        if (details.size > MAX_PUBLISHED_IMAGE_BYTES) {
+            throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`);
+        }
+        try {
+            bytes = await readFile(filePath);
+        }
+        catch (cause) {
+            throw new ImagePublishError('IMAGE_SOURCE_NOT_FOUND', `图片文件无法读取：${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        sourceName = basename(filePath);
+    }
+    else {
+        const decoded = decodeBase64(base64);
+        bytes = decoded.bytes;
+        dataUriMimeType = decoded.declaredMimeType;
+    }
+    if (bytes.length === 0)
+        invalid('图片内容不能为空。');
+    if (bytes.length > MAX_PUBLISHED_IMAGE_BYTES) {
+        throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`);
+    }
+    const mimeType = detectImageMimeType(bytes);
+    if (!mimeType)
+        invalid('文件内容不是支持的图片格式（PNG、JPEG、GIF、WebP、AVIF、BMP、SVG）。');
+    const declaredMimeType = typeof input.mimeType === 'string' && input.mimeType.trim()
+        ? normalizeMimeType(input.mimeType)
+        : dataUriMimeType;
+    if (declaredMimeType && declaredMimeType !== mimeType) {
+        invalid(`声明的 MIME 类型 ${declaredMimeType} 与图片内容 ${mimeType} 不一致。`);
+    }
+    const format = IMAGE_FORMATS.find(item => item.mimeType === mimeType);
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    const bucket = sha256.slice(0, 12);
+    const filename = safeFilename(input.filename ?? sourceName, `image-${bucket}`, format.extension);
+    const assetDir = join(rootDir, ASSETS_DIR, bucket);
+    const assetPath = join(assetDir, filename);
+    let existing = await readExisting(assetPath);
+    let storedFilename = filename;
+    // The established bucket uses only the first 12 hash characters. If that prefix and the
+    // supplied filename both collide with different bytes, add more hash characters instead of
+    // replacing the existing asset.
+    if (existing && !existing.equals(bytes)) {
+        const extension = format.extension;
+        const stem = filename.slice(0, -extension.length);
+        storedFilename = `${stem}-${sha256.slice(12, 20)}${extension}`;
+        existing = await readExisting(join(assetDir, storedFilename));
+        if (existing && !existing.equals(bytes)) {
+            storedFilename = `image-${sha256}${extension}`;
+            existing = await readExisting(join(assetDir, storedFilename));
+        }
+    }
+    if (existing && !existing.equals(bytes)) {
+        throw new ImagePublishError('ASSET_NAME_COLLISION', '目标文件名已被不同内容占用，未覆盖现有图片。');
+    }
+    if (!existing?.equals(bytes))
+        await writeBufferAtomic(join(assetDir, storedFilename), bytes);
+    // Standalone hosted images have no SourceRaw or card by design. Keep that intent beside the
+    // asset so the orphan sweep does not mistake it for a disposable extraction artifact.
+    await writeTextAtomic(join(assetDir, PUBLISHED_IMAGE_MARKER), 'images.publish\n');
+    const relativePath = `${ASSETS_DIR}/${bucket}/${storedFilename}`;
+    const url = `/knowledge/assets/${encodeURIComponent(kb)}/${relativePath.split('/').map(encodeURIComponent).join('/')}`;
+    return {
+        kb,
+        filename: storedFilename,
+        path: relativePath,
+        url,
+        markdown: `![${storedFilename}](${url})`,
+        mimeType,
+        bytes: bytes.length,
+        sha256,
+    };
+}
+//# sourceMappingURL=images.js.map

package/lib/types/images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.js","sourceRoot":"","sources":["../../src/images.ts"],"names":[],"mappings":"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"}

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAsClD,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAiB,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAEpE,OAAO,EACL,YAAY,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,UAAU,IAAI,kBAAkB,EACnG,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAC9C,KAAK,UAAU,EACf,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAA;AAEzB,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,OAAO,EAAE,YAAY,IAAI,gBAAgB,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,KAAK,WAAW,EAAE,CAAA;AAC7G,OAAO,EAAE,WAAW,IAAI,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,oBAAoB,EAAE,CAAA;AAExH,eAAO,MAAM,IAAI,8BAA8B,CAAA;AAC/C;;;GAGG;AACH,eAAO,MAAM,MAAM,iCAAkC,CAAA;AAGrD,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,CAAA;AACxD,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAClC;;;;;;;;;GASG;AACH,OAAO,EAAE,MAAM,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AASvE,OAAO,EAAE,MAAM,EAAE,KAAK,qBAAqB,EAAE,CAAA;AAW7C,wBAAgB,qBAAqB,IAAI,cAAc,GAAG,SAAS,CAAgC;AAwRnG,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,GAAE,qBAA0B,GAAG,IAAI,CA4wDlF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAsClD,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAiB,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAGpE,OAAO,EACL,YAAY,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,UAAU,IAAI,kBAAkB,EACnG,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAC9C,KAAK,UAAU,EACf,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAA;AAEzB,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,OAAO,EAAE,YAAY,IAAI,gBAAgB,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,KAAK,WAAW,EAAE,CAAA;AAC7G,OAAO,EAAE,WAAW,IAAI,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,oBAAoB,EAAE,CAAA;AAExH,eAAO,MAAM,IAAI,8BAA8B,CAAA;AAC/C;;;GAGG;AACH,eAAO,MAAM,MAAM,iCAAkC,CAAA;AAGrD,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,CAAA;AACxD,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAClC;;;;;;;;;GASG;AACH,OAAO,EAAE,MAAM,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AASvE,OAAO,EAAE,MAAM,EAAE,KAAK,qBAAqB,EAAE,CAAA;AAW7C,wBAAgB,qBAAqB,IAAI,cAAc,GAAG,SAAS,CAAgC;AAwRnG,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,GAAE,qBAA0B,GAAG,IAAI,CAqyDlF"}

package/lib/types/index.js

@@ -16,6 +16,7 @@ import { agentLayout, defaultAgentRoot, ensureAgentLayout, intentRoot, knowledge
 import { PickerError, createDirectory, listDirectory, pickDirectory, pickerKind, pickerOf, } from './directory-picker.js';
 import { KNOWLEDGE_SETTINGS_SCHEMA, SETTINGS_NAMESPACE } from './settings-schema.js';
 import { DEFAULT_KB_ID, KnowledgeBases } from './knowledge-bases.js';
+import { ImagePublishError, publishKnowledgeImage } from './images.js';
 import { applyConvert, CONVERT_SETTINGS_NAMESPACE, CONVERT_SETTINGS_SCHEMA, MOUNT_PATH as CONVERT_MOUNT_PATH, } from './convert/host.js';
 import { applyIntent, INTENT_MOUNT_PATH, INTENT_SERVICE, } from './intent/host.js';
 export * from './types.js';
@@ -481,7 +482,7 @@ export function apply(ctx, pluginConfig = {}) {
         // 0044：非默认库的 runtime 也要拿到模型接缝。只传 `config` 不够 —— 默认库走上面
         // 那个 `new KnowledgeRuntime(... runtimeOptions())`，别的库走注册表这条支路，
         // 两边必须都带上，否则「新建一个库 → 导入文档」静默变成规则抽取。
-        runtimeOptions: () => ({ modelSeam: modelSeamFor, environmentGuard: () => environment.requireReady() }),
+        runtimeOptions: () => ({ resourceRoot: resourceRoot(config.agentRoot), modelSeam: modelSeamFor, environmentGuard: () => environment.requireReady() }),
     });
     compileModelForBase = id => bases.compileModelOf(id);
     runtime.baseId = bases.defaultId;
@@ -687,7 +688,7 @@ export function apply(ctx, pluginConfig = {}) {
     // 意图只保留固定的会话审计契约；可编辑词表不再属于插件配置。
     applyIntent(ctx, { intentRoot: () => intentRoot(config.agentRoot) });
     /**
-     * 需要本轮用户审批的写工具。
+     * 需要本轮用户审批的知识写工具。`images.publish` 只写入本地素材目录，按用户要求免审批。
      *
      * 0044 换过一批名字：`write_knowledge_card`（只接受已确认提议）退役了，因为正文现在
      * 只读、卡片由编译直接写入；`list_card_proposals` 也退役了，因为待办队列不存在了。
@@ -734,6 +735,27 @@ export function apply(ctx, pluginConfig = {}) {
             buildVersion: base.buildVersion,
         })),
     })));
+    ctx.tools.register(tool('images.publish', 'Publish one local image into a knowledge base assets bucket without user approval. Pass exactly one of `file_path` or `content_base64` (standard Base64 or a data URI); optional `filename` overrides the stored name, and optional `mime_type` must match the file bytes. Supports PNG, JPEG, GIF, WebP, AVIF, BMP and SVG up to 20 MiB. Returns the local asset URL and Markdown image reference.', {
+        file_path: { type: 'string', description: '宿主可读取的本地图片文件路径；与 content_base64 二选一' },
+        content_base64: { type: 'string', description: '图片的标准 Base64，或 data:image/...;base64,...；与 file_path 二选一' },
+        filename: { type: 'string', description: '可选文件名；默认使用 file_path 的文件名，Base64 输入默认 image-<hash>.<ext>' },
+        mime_type: { type: 'string', description: '可选 MIME 类型；必须与图片二进制内容一致' },
+        kb: { type: 'string', description: '知识库 id；省略时写入默认库' },
+    }, async (args) => withRuntime(args.kb, async (target) => {
+        try {
+            return success(await publishKnowledgeImage(target.rootDir, target.baseId, {
+                filePath: args.file_path,
+                contentBase64: args.content_base64,
+                filename: args.filename,
+                mimeType: args.mime_type,
+            }));
+        }
+        catch (cause) {
+            if (cause instanceof ImagePublishError)
+                return failure({}, cause.code, cause.message, false, cause.suggestion);
+            return failure({}, 'IMAGE_PUBLISH_FAILED', `图片写入失败：${cause instanceof Error ? cause.message : String(cause)}`, true);
+        }
+    })));
     ctx.tools.register(tool('add_source', 'Add or update a SourceRaw document (原始可追溯文档). DSH requests one user approval before execution.', { title: { type: 'string' }, content: { type: 'string', required: true }, external_id: { type: 'string' }, metadata: { type: 'json' }, source_id: { type: 'string' }, allow_duplicate_title: { type: 'boolean', description: '默认 false：标题与已有来源重复时拒收（SOURCE_TITLE_DUPLICATED），要求改标题。传 true 才允许并存。' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.addSource({ title: args.title, content: args.content, externalId: args.external_id, metadata: args.metadata, sourceId: args.source_id, ...(args.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}), lineage: lineageOf(args, exec) })), {
         call: addSourceCallView,
         meta: (args, value) => addSourceMetaOf(args, dataOf(value)),
@@ -939,7 +961,7 @@ export function apply(ctx, pluginConfig = {}) {
                         }
                         if (body?.action !== 'check' && body?.action !== 'install')
                             return send(res, 400, failure({}, 'ACTION_INVALID', 'action 必须是 check、install 或 cancel', false));
-                        return send(res, 200, success(environment.start(body.action)));
+                        return send(res, 200, success(environment.start(body.action, body.selection)));
                     }
                     catch (cause) {
                         return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause)));