@glodon-aiot/bot-client-sdk 3.25.1-alpha.7 → 3.26.0-alpha.5

package/dist/src/localFiles/adapters/fsaTypes.d.ts

@@ -0,0 +1,41 @@
+export type FsaPermissionMode = 'read' | 'readwrite';
+export interface FsaPermissionDescriptor {
+    mode?: FsaPermissionMode;
+}
+export interface FsaWritableStream {
+    write(data: Uint8Array | Blob | string): Promise<void>;
+    close(): Promise<void>;
+    abort(reason?: unknown): Promise<void>;
+}
+export interface FsaHandleBase {
+    readonly name: string;
+    queryPermission?(descriptor?: FsaPermissionDescriptor): Promise<PermissionState>;
+    requestPermission?(descriptor?: FsaPermissionDescriptor): Promise<PermissionState>;
+    /** Chromium 部分版本支持；目录移动支持更晚。 */
+    move?(destination: FsaDirectoryHandle, name: string): Promise<void>;
+}
+export interface FsaFileHandle extends FsaHandleBase {
+    readonly kind: 'file';
+    getFile(): Promise<File>;
+    createWritable(options?: {
+        keepExistingData?: boolean;
+    }): Promise<FsaWritableStream>;
+}
+export interface FsaDirectoryHandle extends FsaHandleBase {
+    readonly kind: 'directory';
+    getDirectoryHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<FsaDirectoryHandle>;
+    getFileHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<FsaFileHandle>;
+    removeEntry(name: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    values(): AsyncIterableIterator<FsaDirectoryHandle | FsaFileHandle>;
+}
+export type ShowDirectoryPicker = (options?: {
+    id?: string;
+    mode?: FsaPermissionMode;
+}) => Promise<FsaDirectoryHandle>;
+export declare function getNativeDirectoryPicker(): ShowDirectoryPicker | undefined;

package/dist/src/localFiles/constants.d.ts

@@ -0,0 +1,51 @@
+import { Env } from '../Config';
+export declare const LOCAL_FILES_FUNCTION_CODES: readonly ["list_directory", "read_file", "stat_file", "search_files", "search_text", "apply_patch", "write_file", "upload_file", "download_file"];
+export type LocalFilesFunctionCode = (typeof LOCAL_FILES_FUNCTION_CODES)[number];
+/**
+ * 平台上的内置工具插件。本地文件工具和 `run_python` 都在这一个插件里。
+ * dev、test、prod、local 使用同一个 pluginCode。
+ */
+/** 平台插件编码。与内置工具 OpenAPI 的 pluginCode 一致。 */
+export declare const BUILTIN_TOOLS_PLUGIN_CODE = "builtin_tools";
+export declare const BUILTIN_TOOLS_PLUGIN_CODES: Record<Env, string>;
+/** 与 `BUILTIN_TOOLS_PLUGIN_CODES` 相同。文件工具和脚本工具共用一个插件编码。 */
+export declare const LOCAL_FILES_PLUGIN_CODES: Record<Env, string>;
+/** 本地 Python 脚本。与文件工具注册在同一个插件里。 */
+export declare const LOCAL_PYTHON_FUNCTION_CODE = "run_python";
+/** 与 `BUILTIN_TOOLS_PLUGIN_CODES` 相同。未单独配置时跟随文件工具的 pluginCode。 */
+export declare const LOCAL_PYTHON_PLUGIN_CODES: Record<Env, string>;
+export declare const PYTHON_DEFAULT_TIMEOUT_MS = 20000;
+export declare const PYTHON_MAX_TIMEOUT_MS = 120000;
+export declare const PYTHON_MAX_ARGS = 16;
+export declare const WORKSPACE_GRANT_ID = "current-workspace";
+export declare const KiB = 1024;
+export declare const MiB: number;
+/** 单文件上传/下载上限（MB），与 UI 拖拽上传共用。 */
+export declare const TRANSFER_FILE_SIZE_LIMIT_MB = 50;
+export interface LocalFilesLimits {
+    maxReadBytes: number;
+    maxWriteBytes: number;
+    maxSearchResults: number;
+    maxConcurrentRequests: number;
+    maxTransferBytes: number;
+    toolTimeoutMs: number;
+    searchTimeoutMs: number;
+    transferTimeoutMs: number;
+    approvalTimeoutMs: number;
+}
+export declare const DEFAULT_LIMITS: Readonly<LocalFilesLimits>;
+export declare const LIST_DIRECTORY_DEFAULT_LIMIT = 200;
+export declare const LIST_DIRECTORY_MAX_LIMIT = 1000;
+export declare const SEARCH_DEFAULT_DEPTH = 8;
+export declare const SEARCH_MAX_DEPTH = 16;
+export declare const TEXT_SEARCH_MAX_FILES = 2000;
+export declare const TEXT_SEARCH_MAX_FILE_BYTES: number;
+export declare const TEXT_SEARCH_MAX_LINE_CHARS = 500;
+export declare const TEXT_SEARCH_MAX_CONTEXT_LINES = 3;
+export declare const BINARY_SNIFF_BYTES: number;
+export declare const DEFAULT_DOWNLOAD_URL_ALLOWLIST: readonly string[];
+export declare const DEFAULT_IGNORED_DIRECTORIES: readonly string[];
+export declare const DEFAULT_IGNORED_FILE_PATTERNS: readonly string[];
+export declare const WRITE_FUNCTION_CODES: readonly LocalFilesFunctionCode[];
+export declare const SEARCH_FUNCTION_CODES: readonly LocalFilesFunctionCode[];
+export declare const TRANSFER_FUNCTION_CODES: readonly LocalFilesFunctionCode[];

package/dist/src/localFiles/createLocalFilesPlugin.d.ts

@@ -0,0 +1,11 @@
+import { LocalFilesFunctionCode } from './constants';
+import { ClientPluginCallback, ToolContext } from './types';
+import { LocalWorkspace } from './workspace/LocalWorkspace';
+export type LocalFilesHandler = (params: unknown, callback: ClientPluginCallback, context?: Partial<ToolContext>) => void;
+export type LocalFilesPluginTable = Record<string, Record<LocalFilesFunctionCode, LocalFilesHandler>>;
+export interface CreateLocalFilesPluginOptions {
+    pluginCode: string;
+    workspace: LocalWorkspace;
+}
+/** 组装内置本地文件插件表：`{ [pluginCode]: { [functionCode]: handler } }`。 */
+export declare function createLocalFilesPlugin({ pluginCode, workspace, }: CreateLocalFilesPluginOptions): LocalFilesPluginTable;

package/dist/src/localFiles/createLocalPythonPlugin.d.ts

@@ -0,0 +1,12 @@
+import { LOCAL_PYTHON_FUNCTION_CODE } from './constants';
+import { ClientPluginCallback, PythonApprovalHandler, ToolContext } from './types';
+import { LocalWorkspace } from './workspace/LocalWorkspace';
+export type LocalPythonHandler = (params: unknown, callback: ClientPluginCallback, context?: Partial<ToolContext>) => void;
+export type LocalPythonPluginTable = Record<string, Record<typeof LOCAL_PYTHON_FUNCTION_CODE, LocalPythonHandler>>;
+export interface CreateLocalPythonPluginOptions {
+    pluginCode: string;
+    workspace: LocalWorkspace;
+    onApprovalRequired?: PythonApprovalHandler;
+}
+/** 组装 run_python。配置合并时与文件工具放进同一个 pluginCode。 */
+export declare function createLocalPythonPlugin({ pluginCode, workspace, onApprovalRequired, }: CreateLocalPythonPluginOptions): LocalPythonPluginTable;

package/dist/src/localFiles/errors.d.ts

@@ -0,0 +1,34 @@
+export declare enum ToolCode {
+    Ok = 0,
+    BadRequest = 400,
+    Forbidden = 403,
+    NotFound = 404,
+    Timeout = 408,
+    Conflict = 409,
+    TooLarge = 413,
+    TooManyRequests = 429,
+    Cancelled = 499,
+    Internal = 500,
+    NotImplemented = 501
+}
+export type ToolErrorReason = 'workspace_not_granted' | 'path_outside_workspace' | 'sensitive_file' | 'user_rejected' | 'approval_unavailable' | 'url_not_allowed';
+export interface ToolErrorData {
+    reason?: ToolErrorReason;
+    ruleId?: string;
+    currentHash?: string;
+    [key: string]: unknown;
+}
+export declare class ToolError extends Error {
+    readonly code: ToolCode;
+    readonly data?: ToolErrorData;
+    constructor(code: ToolCode, message: string, data?: ToolErrorData);
+}
+export declare const WORKSPACE_NOT_GRANTED_MESSAGE = "\u5C1A\u672A\u6388\u6743\u5DE5\u4F5C\u6587\u4EF6\u5939\uFF0C\u8BF7\u5148\u5728\u52A9\u624B\u4E2D\u9009\u62E9\u6216\u6062\u590D\u8BBF\u95EE\u5DE5\u4F5C\u6587\u4EF6\u5939\u3002";
+export declare function workspaceNotGranted(): ToolError;
+export declare function cancelledError(): ToolError;
+export declare function throwIfAborted(signal?: AbortSignal): void;
+/**
+ * 把任意异常转换为可回传给平台的 ToolError。
+ * FSA 抛出的 DOMException 可能带有系统路径等信息，因此只按 name 映射为固定文案。
+ */
+export declare function toToolError(error: unknown): ToolError;

package/dist/src/localFiles/host/connectHostBridge.d.ts

@@ -0,0 +1,6 @@
+import { LocalWorkspace } from '../workspace/LocalWorkspace';
+/**
+ * 监听宿主推送的工程目录。宿主发 granted 后挂上适配器，页面不再调用选目录框。
+ * 同一页面只保留一条连接。
+ */
+export declare function connectHostBridge(workspace: LocalWorkspace): () => void;

package/dist/src/localFiles/host/protocol.d.ts

@@ -0,0 +1,46 @@
+/** 宿主与页面之间的通道名。根目录只由宿主设置，消息里不能带绝对路径。 */
+export declare const HOST_CHANNEL = "glodon-workspace";
+export interface HostWebView {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+/**
+ * 宿主声明的能力。
+ * - `sandbox-exec`：命令交给 SDK 沙箱包执行，支持 `exec` 消息。
+ * - `fs-mutate`：支持 `mkdir`、`remove`、`move` 消息。
+ */
+export type HostCapability = 'sandbox-exec' | 'fs-mutate';
+/** SDK 支持的沙箱包协议版本。宿主声明的 sandboxProtocol 不同时不使用宿主沙箱。 */
+export declare const SANDBOX_PROTOCOL = 1;
+export interface HostWorkspaceMessage {
+    channel: string;
+    type: 'workspace';
+    granted?: boolean;
+    displayName?: string;
+    capabilities?: HostCapability[];
+    sandboxVersion?: string;
+    sandboxProtocol?: number;
+}
+export interface HostResponseMessage {
+    channel: string;
+    id: string;
+    ok?: boolean;
+    name?: string;
+    entries?: unknown;
+    entry?: unknown;
+    contentBase64?: string;
+    exitCode?: number;
+    timedOut?: boolean;
+    stdout?: string;
+    stderr?: string;
+    /** shell 结束后的工作区相对目录。 */
+    cwd?: string;
+    message?: string;
+}
+export declare function parseHostMessage(data: unknown): Record<string, unknown> | undefined;
+export declare function getHostWebView(): HostWebView | undefined;

package/dist/src/localFiles/index.d.ts

@@ -0,0 +1,22 @@
+export * from './constants';
+export * from './types';
+export { ToolCode, ToolError, toToolError } from './errors';
+export type { ToolErrorData, ToolErrorReason } from './errors';
+export { LOCAL_FILE_TOOL_SCHEMAS, LOCAL_PYTHON_TOOL_SCHEMA } from './schemas';
+export { BUILTIN_TOOL_SCHEMAS } from '../builtinTools/schemas';
+export type { BuiltinToolSchema, JsonSchema, LocalFileToolSchema } from './schemas';
+export { createLocalFilesPlugin } from './createLocalFilesPlugin';
+export type { CreateLocalFilesPluginOptions, LocalFilesHandler, LocalFilesPluginTable, } from './createLocalFilesPlugin';
+export { LocalWorkspace } from './workspace/LocalWorkspace';
+export type { LocalWorkspaceOptions } from './workspace/LocalWorkspace';
+export { createIndexedDbStore, createMemoryStore } from './workspace/handleStore';
+export type { KeyValueStore } from './workspace/handleStore';
+export type { RemoveOptions, WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource, } from './adapters/WorkspaceFileAdapter';
+export { FileSystemAccessAdapter } from './adapters/FileSystemAccessAdapter';
+export { MemoryWorkspaceAdapter } from './adapters/MemoryWorkspaceAdapter';
+export type { FsaDirectoryHandle, ShowDirectoryPicker } from './adapters/fsaTypes';
+export { createDefaultSessionFileTransfer } from './transfer/SessionFileTransfer';
+export type { ResolvedDownload, SessionFileTransfer, UploadProgress, } from './transfer/SessionFileTransfer';
+export { getDownloadUrlAllowlist, isDownloadUrlAllowed, } from './security/downloadUrlPolicy';
+export { SDK_SENSITIVE_BASELINE } from './security/sensitiveFiles';
+export type { SensitiveRule, SensitiveRuleInput } from './security/sensitiveFiles';

package/dist/src/localFiles/limits.d.ts

@@ -0,0 +1,3 @@
+import { LocalFilesLimits } from './constants';
+/** 产品配置只能把限额调小；非法值或大于默认值的配置按默认值处理。 */
+export declare function resolveLimits(overrides?: Partial<LocalFilesLimits>): LocalFilesLimits;

package/dist/src/localFiles/schemas.d.ts

@@ -0,0 +1,29 @@
+import { LocalFilesFunctionCode } from './constants';
+export interface JsonSchema {
+    type?: 'object' | 'string' | 'integer' | 'number' | 'boolean' | 'array';
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: (string | number | boolean)[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    oneOf?: JsonSchema[];
+}
+export interface BuiltinToolSchema {
+    functionCode: string;
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+}
+export interface LocalFileToolSchema extends BuiltinToolSchema {
+    functionCode: LocalFilesFunctionCode;
+}
+/** 9 个工具的参数 Schema，同时作为平台注册时的草案。 */
+export declare const LOCAL_FILE_TOOL_SCHEMAS: Record<LocalFilesFunctionCode, LocalFileToolSchema>;
+/** run_python 的参数 Schema。与文件工具一起注册到同一个插件。 */
+export declare const LOCAL_PYTHON_TOOL_SCHEMA: BuiltinToolSchema;

package/dist/src/localFiles/security/downloadUrlPolicy.d.ts

@@ -0,0 +1,4 @@
+/** 有效 allowlist = 默认 `['glodon.com']` ∪ 追加项（去重、转小写）。 */
+export declare function getDownloadUrlAllowlist(append?: string[]): string[];
+export declare function isDownloadUrlAllowed(url: string, append?: string[]): boolean;
+export declare function isDownloadUrlAllowedByList(url: string, allowlist: string[]): boolean;

package/dist/src/localFiles/security/glob.d.ts

@@ -0,0 +1,3 @@
+export declare function globToRegExp(pattern: string, caseSensitive?: boolean): RegExp;
+export declare function matchGlob(pattern: string, target: string, caseSensitive?: boolean): boolean;
+export declare function basename(path: string): string;

package/dist/src/localFiles/security/pathPolicy.d.ts

@@ -0,0 +1,14 @@
+export declare function assertGrantId(grantId: unknown): void;
+export interface NormalizePathOptions {
+    /** 是否允许空字符串或 `.` 表示工作区根目录。 */
+    allowRoot?: boolean;
+    field?: string;
+}
+/**
+ * 把模型给出的路径规范化为 `a/b/c` 形式的工作区相对路径，根目录返回空字符串。
+ * 不合法的路径直接抛出 403，调用方不需要再做二次判断。
+ */
+export declare function normalizeWorkspacePath(input: unknown, { allowRoot, field }?: NormalizePathOptions): string;
+export declare function splitPath(path: string): string[];
+export declare function parentPath(path: string): string;
+export declare function joinPath(base: string, name: string): string;

package/dist/src/localFiles/security/sensitiveFiles.d.ts

@@ -0,0 +1,23 @@
+export type SensitiveOperation = 'read' | 'write' | 'search';
+export interface SensitiveRule {
+    id: string;
+    /** glob，匹配工作区相对路径，分隔符为 `/`。 */
+    pattern: string;
+    /** basename：只比较文件名（默认）；path：比较整段相对路径。 */
+    match?: 'basename' | 'path';
+    /** 默认三种操作都拦截。 */
+    operations?: SensitiveOperation[];
+    reason?: string;
+    source: 'sdk-baseline' | 'product' | 'enterprise';
+}
+export type SensitiveRuleInput = Omit<SensitiveRule, 'source'> & {
+    source?: 'product' | 'enterprise';
+};
+export declare const SDK_SENSITIVE_BASELINE: readonly SensitiveRule[];
+export declare class SensitiveFilePolicy {
+    readonly rules: readonly SensitiveRule[];
+    constructor(append?: SensitiveRuleInput[]);
+    match(path: string, operation: SensitiveOperation): SensitiveRule | null;
+    isSensitive(path: string): boolean;
+    static reasonOf(rule: SensitiveRule): string;
+}

package/dist/src/localFiles/tools/readTools.d.ts

@@ -0,0 +1,7 @@
+import { ListDirectoryInput, ListDirectoryOutput, ReadFileInput, ReadFileOutput, SearchFilesInput, SearchFilesOutput, SearchTextInput, SearchTextOutput, StatFileInput, StatFileOutput } from '../types';
+import { ToolImplementation } from './runtime';
+export declare const listDirectory: ToolImplementation<ListDirectoryInput, ListDirectoryOutput>;
+export declare const readFile: ToolImplementation<ReadFileInput, ReadFileOutput>;
+export declare const statFile: ToolImplementation<StatFileInput, StatFileOutput>;
+export declare const searchFiles: ToolImplementation<SearchFilesInput, SearchFilesOutput>;
+export declare const searchText: ToolImplementation<SearchTextInput, SearchTextOutput>;

package/dist/src/localFiles/tools/runtime.d.ts

@@ -0,0 +1,43 @@
+import { LocalFilesLimits, LocalFilesFunctionCode } from '../constants';
+import { WorkspaceEntry, WorkspaceFileAdapter } from '../adapters/WorkspaceFileAdapter';
+import { SensitiveFilePolicy, SensitiveOperation } from '../security/sensitiveFiles';
+import { SessionFileTransfer } from '../transfer/SessionFileTransfer';
+import { ApprovalPreview, ToolContext, ToolProgressEvent } from '../types';
+import { ToolError } from '../errors';
+export interface ToolRuntime {
+    adapter: WorkspaceFileAdapter;
+    workspaceName: string;
+    limits: LocalFilesLimits;
+    sensitive: SensitiveFilePolicy;
+    downloadUrlAllowlist: string[];
+    allowWorkspaceWideTextSearch: boolean;
+    transfer: SessionFileTransfer;
+    fetch: typeof fetch;
+    context: ToolContext;
+    signal: AbortSignal;
+    /** 请求用户确认；拒绝、无确认能力或被取消时抛出 ToolError。等待期间不计入工具超时。 */
+    requestApproval(path: string, preview: ApprovalPreview): Promise<void>;
+    progress(event: Pick<ToolProgressEvent, 'stage' | 'loaded' | 'total' | 'path'>): void;
+}
+export interface ToolOutput<T> {
+    data: T;
+    truncated?: boolean;
+    warnings?: string[];
+}
+export type ToolImplementation<I = any, O = unknown> = (input: I, runtime: ToolRuntime) => Promise<ToolOutput<O>>;
+export type ToolTable = Record<LocalFilesFunctionCode, ToolImplementation>;
+export declare function assertNotSensitive(runtime: ToolRuntime, path: string, operation: SensitiveOperation): void;
+/** 返回目标的元数据；不存在时返回 null，其他错误照常抛出。 */
+export declare function statOrNull(adapter: WorkspaceFileAdapter, path: string): Promise<WorkspaceEntry | null>;
+export declare function requireFile(adapter: WorkspaceFileAdapter, path: string): Promise<WorkspaceEntry>;
+export declare function sha256(data: ArrayBuffer | Uint8Array): Promise<string>;
+export declare function readBytes(blob: Blob): Promise<Uint8Array<ArrayBuffer>>;
+export declare function looksBinary(bytes: Uint8Array): boolean;
+export declare function blobLooksBinary(blob: Blob): Promise<boolean>;
+export declare function hasUtf8Bom(bytes: Uint8Array): boolean;
+/** 严格 UTF-8 解码，失败时抛出 400，用于写入类工具避免改变原文件编码。 */
+export declare function decodeUtf8Strict(bytes: Uint8Array): string;
+export declare function utf8ByteLength(text: string): number;
+export declare function yieldToMain(): Promise<void>;
+export declare function describeSize(bytes: number): string;
+export declare function tooLarge(limitBytes: number, what?: string): ToolError;

package/dist/src/localFiles/tools/transferTools.d.ts

@@ -0,0 +1,4 @@
+import { DownloadFileInput, DownloadFileOutput, UploadFileInput, UploadFileOutput } from '../types';
+import { ToolImplementation } from './runtime';
+export declare const uploadFile: ToolImplementation<UploadFileInput, UploadFileOutput>;
+export declare const downloadFile: ToolImplementation<DownloadFileInput, DownloadFileOutput>;

package/dist/src/localFiles/tools/writeTools.d.ts

@@ -0,0 +1,4 @@
+import { ApplyPatchInput, WriteFileInput, WriteFileOutput, WriteResultOutput } from '../types';
+import { ToolImplementation } from './runtime';
+export declare const applyPatch: ToolImplementation<ApplyPatchInput, WriteResultOutput>;
+export declare const writeFile: ToolImplementation<WriteFileInput, WriteFileOutput>;

package/dist/src/localFiles/transfer/SessionFileTransfer.d.ts

@@ -0,0 +1,40 @@
+import { CVForceApi } from '@glodon-aiot/apis';
+import { DownloadSource, ToolContext } from '../types';
+/** aishop `/v1/files`。上传返回的 url 会放进工具结果交给模型；进度事件和错误信息里不要带它。 */
+export interface PlatformFileClient {
+    postFile(file: File, onProgress?: (loaded: number, total: number) => void): Promise<{
+        id: string;
+        bytes?: number;
+        url?: string;
+    }>;
+    getFile(id: string): Promise<{
+        url?: string;
+        bytes?: number;
+    } | undefined>;
+}
+export interface UploadProgress {
+    loaded: number;
+    total: number;
+}
+export interface ResolvedDownload {
+    url: string;
+    headers?: Record<string, string>;
+    name?: string;
+    size?: number;
+}
+/** upload_file / download_file 与平台交互的部分，可通过配置整体或部分替换。 */
+export interface SessionFileTransfer {
+    upload(file: File, context: ToolContext, onProgress?: (progress: UploadProgress) => void): Promise<{
+        fileId: string;
+        url: string;
+    }>;
+    resolveDownload(source: Exclude<DownloadSource, {
+        type: 'url';
+    }>, context: ToolContext): Promise<ResolvedDownload>;
+}
+/**
+ * 默认实现。
+ * 上传走 aishop `POST /v1/files`，fileId 与预签名 url 都返回给调用方。
+ * 下载平台文件走 `GET /v1/files/{id}` 换链接后再拉取；会话文件仍走会话文件详情。
+ */
+export declare function createDefaultSessionFileTransfer(getApi: () => CVForceApi | undefined, getPlatformFiles?: () => PlatformFileClient | undefined): SessionFileTransfer;