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

package/dist/src/Config.d.ts

@@ -19,7 +19,7 @@ export interface BotClientConfig {
     loadRelatedQuesions?: boolean;
     mcp?: MCPConfig;
     stream?: boolean;
-    /** SDK 内置插件：本地文件工具和 run_python，注册到同一个 pluginCode。 */
+    /** SDK 内置插件。文件、命令和技能工具注册到同一个 pluginCode。 */
     builtinPlugins?: BuiltinPluginsConfig;
 }
 export interface AgentPluginRegistor {
@@ -53,7 +53,7 @@ export declare function setActiveLocalWorkspace(workspace?: LocalWorkspace): voi
 export declare function getActiveLocalWorkspace(): LocalWorkspace | undefined;
 /** 当前已注册到 configuration.plugins 的内置文件工具编码；未注册时返回 undefined。 */
 export declare function getRegisteredLocalFilesPluginCode(): string | undefined;
-/** 当前已注册到 configuration.plugins 的 run_python 所在插件编码；未注册时返回 undefined。 */
+/** 当前已注册到 configuration.plugins 的脚本工具所在插件编码；未注册时返回 undefined。 */
 export declare function getRegisteredLocalPythonPluginCode(): string | undefined;
 /** 显式配置优先，其次按 env 取默认值；都没有时返回 undefined。 */
 export declare function resolveLocalFilesPluginCode(config: LocalFilesConfig | undefined, env: string): string;

package/dist/src/builtinTools/browserRuntime/BrowserCommandRunner.d.ts

@@ -0,0 +1,26 @@
+import { WorkspaceFileAdapter } from '../../localFiles/adapters/WorkspaceFileAdapter';
+import { SensitiveFilePolicy } from '../../localFiles/security/sensitiveFiles';
+import { CommandRequest, CommandResult, CommandRunner } from '../command';
+import { WorkerLike } from './PythonRunner';
+export declare const NO_NODE_MESSAGE = "\u5F53\u524D\u73AF\u5883\u6CA1\u6709 Node\uFF0C\u8BF7\u6539\u7528 python3 \u6216 shell \u547D\u4EE4\u3002\n";
+export interface BrowserCommandRunnerOptions {
+    adapter: WorkspaceFileAdapter;
+    sensitive: SensitiveFilePolicy;
+    /** just-bash 浏览器构建的地址，默认 DEFAULT_BASH_MODULE_URL。 */
+    moduleURL?: string;
+    /** Pyodide 目录，默认 DEFAULT_PYODIDE_INDEX_URL。 */
+    pyodideIndexURL?: string;
+    createWorker?: (source: string) => WorkerLike;
+}
+/**
+ * 纯网页里的命令执行器：just-bash 解释 shell，文件读写落到当前工作区。
+ * 每条命令新建一个 shell，只有文件和 cwd 跨命令保留。
+ */
+export declare class BrowserCommandRunner implements CommandRunner {
+    private readonly options;
+    private readonly python;
+    constructor(options: BrowserCommandRunnerOptions);
+    private load;
+    private create;
+    exec(request: CommandRequest): Promise<CommandResult>;
+}

package/dist/src/builtinTools/browserRuntime/PythonRunner.d.ts

@@ -0,0 +1,67 @@
+import { WorkspaceFileAdapter } from '../../localFiles/adapters/WorkspaceFileAdapter';
+import { SensitiveFilePolicy } from '../../localFiles/security/sensitiveFiles';
+export declare const NO_PIP_MESSAGE: string;
+export declare const MAX_SYNC_FILE_BYTES: number;
+export declare const MAX_SYNC_TOTAL_BYTES: number;
+/** 把 shell 或工具传来的目录换成 Pyodide 里的工作区路径。 */
+export declare function toMount(cwd: string): string;
+/** Worker 的最小接口，测试里用 Node 的 worker_threads 实现。 */
+export interface WorkerLike {
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    terminate(): void;
+}
+export interface PythonRunnerOptions {
+    adapter: WorkspaceFileAdapter;
+    sensitive: SensitiveFilePolicy;
+    /** Pyodide 目录，以 `/` 结尾，默认 DEFAULT_PYODIDE_INDEX_URL。 */
+    indexURL?: string;
+    createWorker?: (source: string) => WorkerLike;
+}
+export interface PythonRequest {
+    /** `python3` 后面的参数。 */
+    args: string[];
+    /** shell 里的目录。`.` 或 `/workspace` 表示工作区根。 */
+    cwd: string;
+    stdin?: Uint8Array;
+    signal?: AbortSignal;
+}
+export interface PythonResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+type Invocation = {
+    mode: 'c' | 'm' | 'file';
+    target: string;
+    argv: string[];
+    stdin: Uint8Array;
+};
+/** 按 python3 命令行解析参数；不需要启动解释器的情况直接给出结果。 */
+export declare function parsePythonArgs(args: string[], cwd: string, stdin: Uint8Array): Invocation | PythonResult;
+/**
+ * 浏览器里的 python3：Pyodide 跑在专用 Worker 里，执行前把工作区文件快照同步进去，执行后把改动写回。
+ * 同一时间只跑一个请求；超时或取消时终止 Worker，下次重新创建。
+ */
+export declare class PythonRunner {
+    private readonly options;
+    private state?;
+    private queue;
+    private nextId;
+    constructor(options: PythonRunnerOptions);
+    private get indexURL();
+    private loadError;
+    private dispose;
+    private spawn;
+    run(request: PythonRequest): Promise<PythonResult>;
+    private runNow;
+    /** 执行前把整个工作区读进 Pyodide。 */
+    private collect;
+    private exists;
+    /** 把 Python 里的改动写回工作区，返回是否有写回失败。 */
+    private writeBack;
+}
+export {};

package/dist/src/builtinTools/browserRuntime/WorkspaceBashFs.d.ts

@@ -0,0 +1,51 @@
+import { BufferEncoding, CpOptions, FileContent, FsStat, IFileSystem, MkdirOptions, RmOptions } from 'just-bash/browser';
+import { WorkspaceFileAdapter } from '../../localFiles/adapters/WorkspaceFileAdapter';
+import { SensitiveFilePolicy } from '../../localFiles/security/sensitiveFiles';
+type EncodingOption = {
+    encoding?: BufferEncoding | null;
+} | BufferEncoding | undefined;
+interface DirentEntry {
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
+/**
+ * 把工作区挂到 just-bash 的一个目录。root 为空表示整个工作区。
+ * 收到的路径相对挂载点，以 `/` 开头。
+ */
+export declare class WorkspaceBashFs implements IFileSystem {
+    private readonly adapter;
+    private readonly root;
+    private readonly sensitive;
+    constructor(adapter: WorkspaceFileAdapter, root: string, sensitive: SensitiveFilePolicy);
+    private relative;
+    private shown;
+    private isRoot;
+    private guard;
+    private mapError;
+    private entry;
+    private ensureRoot;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    readFile(path: string, options?: EncodingOption): Promise<string>;
+    writeFile(path: string, content: FileContent, options?: EncodingOption): Promise<void>;
+    appendFile(path: string, content: FileContent, options?: EncodingOption): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    readdir(path: string): Promise<string[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    resolvePath(base: string, path: string): string;
+    getAllPaths(): string[];
+    chmod(path: string): Promise<void>;
+    symlink(_target: string, linkPath: string): Promise<void>;
+    link(_existingPath: string, newPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    utimes(path: string): Promise<void>;
+}
+export {};

package/dist/src/builtinTools/browserRuntime/assets.d.ts

@@ -0,0 +1,13 @@
+/** 公司 OBS 上的前端依赖目录，按 `<包名>/<版本>/` 存放。 */
+export declare const CDN_LIBS_ROOT = "https://cv-cdn.obs.cn-north-4.myhuaweicloud.com/glodon/libs/";
+/** 必须与 package.json 里 just-bash 的版本一致；升级时先上传新版本目录。 */
+export declare const JUST_BASH_VERSION = "3.6.0";
+export declare const DEFAULT_BASH_MODULE_URL = "https://cv-cdn.obs.cn-north-4.myhuaweicloud.com/glodon/libs/just-bash/3.6.0/just-bash.mjs";
+/** 必须与 package.json 里 pyodide 的版本一致；升级时先上传新版本目录。 */
+export declare const PYODIDE_VERSION = "314.0.7";
+export declare const DEFAULT_PYODIDE_INDEX_URL = "https://cv-cdn.obs.cn-north-4.myhuaweicloud.com/glodon/libs/pyodide/314.0.7/";
+/**
+ * 浏览器里可以 import 的第三方包，构建脚本按它们的依赖闭包上传 wheel 并改写 pyodide-lock.json。
+ * 调整后需要重新构建并上传新的 Pyodide 目录。
+ */
+export declare const PYODIDE_PACKAGES: string[];

package/dist/src/builtinTools/browserRuntime/loadBash.d.ts

@@ -0,0 +1,3 @@
+export type BashModule = typeof import('just-bash/browser');
+/** 第一次执行命令时才从 url 加载 just-bash，不进首屏。加载失败后下次重试。 */
+export declare function loadBash(url: string): Promise<BashModule>;

package/dist/src/builtinTools/browserRuntime/pyodideWorker.d.ts

@@ -0,0 +1,44 @@
+/** Emscripten 的 ErrnoError 不是 Error，只带 errno 和 code。 */
+declare function describe(error: any): any;
+declare function networkDenied(url: any): TypeError;
+/** 只放行 indexURL 下的资源（Pyodide 自身和白名单 wheel），其余请求一律拒绝。 */
+declare function guardNetwork(indexURL: any): void;
+declare function collector(): {
+    write(bytes: any): void;
+    finish(): string;
+};
+declare function init({ indexURL, packages, runner }: {
+    indexURL: any;
+    packages: any;
+    runner: any;
+}): Promise<void>;
+declare function dirname(path: any): any;
+/** 主脚本、`-c` 代码，以及主脚本目录和 cwd 下的 .py 文件里出现的 import。 */
+declare function sourcesToScan({ files, cwd, mode, target }: {
+    files: any;
+    cwd: any;
+    mode: any;
+    target: any;
+}): any[];
+declare function loadPackages(sources: any, stderr: any): Promise<void>;
+declare function lstat(path: any): any;
+declare function removeTree(path: any): void;
+declare function walk(path: any, files: any, dirs: any): void;
+declare function sameBytes(a: any, b: any): boolean;
+declare function execute(message: any): Promise<{
+    exitCode: any;
+    stdout: string;
+    stderr: string;
+    written: {
+        path: any;
+        data: any;
+    }[];
+    removed: any[];
+    createdDirs: any[];
+    removedDirs: string[];
+}>;
+declare const ROOTS: string[];
+declare const OUTPUT_LIMIT: number;
+declare let pyodide: null;
+declare let runPython: null;
+declare let sink: null;

package/dist/src/builtinTools/command.d.ts

@@ -0,0 +1,26 @@
+/** 在工作区里执行命令。由端侧宿主沙箱、浏览器运行时或测试注入实现。 */
+export interface CommandRequest {
+    /** shell 命令。与 argv 二选一。 */
+    command?: string;
+    /** 直接执行的程序和参数，不经过 shell。 */
+    argv?: string[];
+    /** 工作区相对目录。`.` 表示工作区根。 */
+    cwd: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** 命令结束后的工作区相对目录。shell 用来保留上次停留的目录。 */
+    cwd?: string;
+}
+export interface CommandRunner {
+    exec(request: CommandRequest): Promise<CommandResult>;
+}
+/** stdout、stderr 各自返回给模型的字符上限。 */
+export declare const MAX_COMMAND_OUTPUT_CHARS = 16000;
+export declare const OUTPUT_TRUNCATED_NOTE = "\n\u2026\u8F93\u51FA\u5DF2\u622A\u65AD";
+export declare function limitOutput(text: string): string;
+export declare function withOutputLimit(runner: CommandRunner): CommandRunner;

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

@@ -0,0 +1,17 @@
+export declare const BUILTIN_FUNCTION_CODES: readonly ["shell", "read_file", "write_file", "append_file", "run_file", "edit_file", "grep", "find", "load_skill", "read_skill_resource", "run_skill_script"];
+export type BuiltinFunctionCode = (typeof BUILTIN_FUNCTION_CODES)[number];
+/** 单次 read_file 按原文返回的上限。超出后结构化文本改为概览。 */
+export declare const MAX_READ_BYTES = 81920;
+/** write_file 单次覆盖写入的 UTF-8 字节上限。 */
+export declare const MAX_WRITE_BYTES = 81920;
+export declare const MAX_COMMAND_CHARS = 20000;
+/** shell 一开始停在工作区根目录。 */
+export declare const SHELL_CWD = ".";
+/**
+ * 浏览器 shell 把工作区挂在这里。命令里的工作区绝对路径会改写到这个前缀，
+ * 输出再换回以 / 开头的工作区路径。
+ */
+export declare const WORKSPACE_MOUNT = "/workspace";
+/** 技能目录在工作区根下。 */
+export declare const SKILLS_DIR = "skills";
+export declare const RUNNABLE_EXTENSIONS: readonly [".py", ".sh", ".js"];

package/dist/src/builtinTools/createBuiltinToolsPlugin.d.ts

@@ -0,0 +1,11 @@
+import { LocalWorkspace } from '../localFiles/workspace/LocalWorkspace';
+import { ClientPluginCallback, ToolContext } from '../localFiles/types';
+import { BuiltinFunctionCode } from './constants';
+export type BuiltinHandler = (params: unknown, callback: ClientPluginCallback, context?: Partial<ToolContext>) => void;
+export type BuiltinPluginTable = Record<string, Record<BuiltinFunctionCode, BuiltinHandler>>;
+export interface CreateBuiltinToolsPluginOptions {
+    pluginCode: string;
+    workspace: LocalWorkspace;
+}
+/** 组装内置工具插件：`{ [pluginCode]: { shell, read_file, ... } }`。 */
+export declare function createBuiltinToolsPlugin({ pluginCode, workspace, }: CreateBuiltinToolsPluginOptions): BuiltinPluginTable;

package/dist/src/builtinTools/overview.d.ts

@@ -0,0 +1,5 @@
+export declare function isStructuredPath(path: string): boolean;
+export declare function structureOverview(path: string, text: string): string;
+export declare function extensionOf(path: string): string;
+export declare function isImagePath(path: string): boolean;
+export declare function isPdf(path: string, bytes?: Uint8Array): boolean;

package/dist/src/builtinTools/paths.d.ts

@@ -0,0 +1,15 @@
+export declare const SYNTHETIC_DIRS: readonly ["input", "output", "uploads", "tmp"];
+export declare const SYNTHETIC_DIR_MESSAGE = "\u4E0D\u8981\u4F7F\u7528 input\u3001output\u3001uploads\u3001tmp\uFF0C\u4E5F\u4E0D\u8981\u65B0\u5EFA\u8FD9\u4E9B\u76EE\u5F55\u3002\u8BF7\u628A\u6587\u4EF6\u76F4\u63A5\u653E\u5728\u5DE5\u4F5C\u533A\u5DF2\u6709\u4F4D\u7F6E\u6216\u6839\u76EE\u5F55\u3002";
+export declare function mentionsSyntheticDir(text: string): boolean;
+export declare function isSyntheticCwd(cwd: string): boolean;
+/**
+ * 把工作区内绝对路径转成相对工作区根的路径。`/` 表示工作区根。
+ * 拒绝相对路径、盘符和 .. 。
+ */
+export declare function resolveWorkspacePath(input: string): string;
+export declare function resolveFilePath(input: string): string;
+export declare function resolveRunPath(input: string): string;
+export declare function toVirtualPath(relative: string): string;
+/** shell 回传的目录必须仍在工作区内。`.` 表示工作区根。 */
+export declare function isSafeCwd(cwd: string): boolean;
+export declare function skillRelative(skillName: string, relativeName: string): string;

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

@@ -0,0 +1,3 @@
+import { BuiltinToolSchema } from '../localFiles/schemas';
+import { BuiltinFunctionCode } from './constants';
+export declare const BUILTIN_TOOL_SCHEMAS: Record<BuiltinFunctionCode, BuiltinToolSchema>;

package/dist/src/builtinTools/tools.d.ts

@@ -0,0 +1,60 @@
+import { WorkspaceFileAdapter } from '../localFiles/adapters/WorkspaceFileAdapter';
+import { CommandRunner } from './command';
+export interface ToolIO {
+    adapter: WorkspaceFileAdapter;
+    runner?: CommandRunner;
+    signal?: AbortSignal;
+    timeoutMs: number;
+    shellCwd: {
+        cwd: string;
+    };
+}
+interface ToolOutput {
+    data: Record<string, unknown>;
+    truncated?: boolean;
+}
+export declare function readFile(input: {
+    path: string;
+    start_line?: number;
+    end_line?: number;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function writeFile(input: {
+    path: string;
+    content: string;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function appendFile(input: {
+    path: string;
+    content: string;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function editFile(input: {
+    path: string;
+    old_text: string;
+    new_text: string;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function grep(input: {
+    path: string;
+    pattern: string;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function find(input: {
+    path: string;
+    name: string;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function runFile(input: {
+    path: string;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function shell(input: {
+    command: string;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function loadSkill(input: {
+    skill_name: string;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function readSkillResource(input: {
+    skill_name: string;
+    resource_name: string;
+}, io: ToolIO): Promise<ToolOutput>;
+export declare function runSkillScript(input: {
+    skill_name: string;
+    script_name: string;
+    args?: string[];
+}, io: ToolIO): Promise<ToolOutput>;
+export {};

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

@@ -1,4 +1,4 @@
-import { WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource } from './WorkspaceFileAdapter';
+import { RemoveOptions, WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource } from './WorkspaceFileAdapter';
 import { FsaDirectoryHandle } from './fsaTypes';
 /**
  * 基于用户授权的 DirectoryHandle 的工作区。只通过逐级 getDirectoryHandle / getFileHandle
@@ -14,4 +14,7 @@ export declare class FileSystemAccessAdapter implements WorkspaceFileAdapter {
     listEntries(path: string, signal?: AbortSignal): Promise<WorkspaceEntry[]>;
     readFile(path: string): Promise<Blob>;
     writeFile(path: string, source: WriteSource, options?: WriteOptions): Promise<void>;
+    createDirectory(path: string): Promise<void>;
+    remove(path: string, options?: RemoveOptions): Promise<void>;
+    move(from: string, to: string): Promise<void>;
 }

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

@@ -1,19 +1,38 @@
+import { CommandRequest, CommandResult } from '../../builtinTools/command';
 import { WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource } from './WorkspaceFileAdapter';
-import { HostResponseMessage, HostWebView } from '../host/protocol';
+import { HostCapability, HostResponseMessage, HostWebView } from '../host/protocol';
 /**
  * 把工作区原语转成宿主消息。页面看不到绝对路径，目录由宿主在授权后推送。
  */
 export declare class HostBridgeAdapter implements WorkspaceFileAdapter {
     private readonly view;
     displayName: string;
+    /** 宿主最近一次 workspace 消息声明的能力。 */
+    capabilities: ReadonlySet<HostCapability>;
+    /** 宿主随 sandbox-exec 声明的沙箱包版本和协议。 */
+    sandboxVersion?: string;
+    sandboxProtocol?: number;
     private seq;
     private readonly pending;
     constructor(view: HostWebView, displayName?: string);
+    setCapabilities(value: unknown, sandbox?: {
+        version?: unknown;
+        protocol?: unknown;
+    }): void;
+    /** 声明了 sandbox-exec 且协议版本与 SDK 一致时才把命令交给宿主。 */
+    get canExec(): boolean;
+    private requireCapability;
     settle(message: HostResponseMessage): void;
     private call;
     stat(path: string): Promise<WorkspaceEntry>;
     listEntries(path: string, signal?: AbortSignal): Promise<WorkspaceEntry[]>;
     readFile(path: string): Promise<Blob>;
+    createDirectory(path: string): Promise<void>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    exec(request: CommandRequest): Promise<CommandResult>;
     runPython(path: string, args: string[], timeoutMs: number, signal?: AbortSignal): Promise<{
         exitCode: number;
         timedOut: boolean;

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

@@ -1,4 +1,4 @@
-import { WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource } from './WorkspaceFileAdapter';
+import { RemoveOptions, WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource } from './WorkspaceFileAdapter';
 /** 内存工作区：用于测试与契约基准，语义与 FileSystemAccessAdapter 一致。 */
 export declare class MemoryWorkspaceAdapter implements WorkspaceFileAdapter {
     readonly displayName: string;
@@ -15,4 +15,7 @@ export declare class MemoryWorkspaceAdapter implements WorkspaceFileAdapter {
     listEntries(path: string, signal?: AbortSignal): Promise<WorkspaceEntry[]>;
     readFile(path: string): Promise<Blob>;
     writeFile(path: string, source: WriteSource, options?: WriteOptions): Promise<void>;
+    createDirectory(path: string): Promise<void>;
+    remove(path: string, options?: RemoveOptions): Promise<void>;
+    move(from: string, to: string): Promise<void>;
 }

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

@@ -21,6 +21,20 @@ export interface WorkspaceFileAdapter {
     readFile(path: string): Promise<Blob>;
     /** 全部内容写完才提交；失败或取消时原文件保持不变，新建的文件不会残留。 */
     writeFile(path: string, source: WriteSource, options?: WriteOptions): Promise<void>;
+    /** 逐级创建目录，已存在时不报错。路径上有同名文件时抛 TypeMismatchError。 */
+    createDirectory?(path: string): Promise<void>;
+    /** 删除文件或目录。非空目录需要 recursive，否则抛 InvalidModificationError。不能删除根目录。 */
+    remove?(path: string, options?: RemoveOptions): Promise<void>;
+    /**
+     * 把 from 移到 to（to 是最终路径，不是目标目录）。to 的父目录必须存在。
+     * to 已是文件时覆盖；from 或 to 有一方是已存在的目录、或 to 在 from 之内时抛 InvalidModificationError。
+     */
+    move?(from: string, to: string): Promise<void>;
 }
+export interface RemoveOptions {
+    recursive?: boolean;
+}
+/** from 与 to 都已规范化；to 等于 from 或在 from 之下。 */
+export declare function isSameOrInside(from: string, to: string): boolean;
 export declare function domError(name: string, message?: string): DOMException;
 export declare function toChunks(source: WriteSource): AsyncIterable<Uint8Array>;

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

@@ -11,6 +11,8 @@ 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';

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

@@ -5,7 +5,8 @@ export type LocalFilesFunctionCode = (typeof LOCAL_FILES_FUNCTION_CODES)[number]
  * 平台上的内置工具插件。本地文件工具和 `run_python` 都在这一个插件里。
  * dev、test、prod、local 使用同一个 pluginCode。
  */
-export declare const BUILTIN_TOOLS_PLUGIN_CODE = "buildin_tools";
+/** 平台插件编码。与内置工具 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>;

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

@@ -9,11 +9,22 @@ export interface HostWebView {
         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;
@@ -27,6 +38,8 @@ export interface HostResponseMessage {
     timedOut?: boolean;
     stdout?: string;
     stderr?: string;
+    /** shell 结束后的工作区相对目录。 */
+    cwd?: string;
     message?: string;
 }
 export declare function parseHostMessage(data: unknown): Record<string, unknown> | undefined;

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

@@ -2,7 +2,8 @@ export * from './constants';
 export * from './types';
 export { ToolCode, ToolError, toToolError } from './errors';
 export type { ToolErrorData, ToolErrorReason } from './errors';
-export { BUILTIN_TOOL_SCHEMAS, LOCAL_FILE_TOOL_SCHEMAS, LOCAL_PYTHON_TOOL_SCHEMA } from './schemas';
+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';
@@ -10,7 +11,7 @@ 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 { WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource, } from './adapters/WorkspaceFileAdapter';
+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';

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

@@ -1,4 +1,4 @@
-import { LocalFilesFunctionCode, LOCAL_PYTHON_FUNCTION_CODE } from './constants';
+import { LocalFilesFunctionCode } from './constants';
 export interface JsonSchema {
     type?: 'object' | 'string' | 'integer' | 'number' | 'boolean' | 'array';
     description?: string;
@@ -9,6 +9,7 @@ export interface JsonSchema {
     minimum?: number;
     maximum?: number;
     minLength?: number;
+    maxLength?: number;
     minItems?: number;
     maxItems?: number;
     oneOf?: JsonSchema[];
@@ -26,5 +27,3 @@ export interface LocalFileToolSchema extends BuiltinToolSchema {
 export declare const LOCAL_FILE_TOOL_SCHEMAS: Record<LocalFilesFunctionCode, LocalFileToolSchema>;
 /** run_python 的参数 Schema。与文件工具一起注册到同一个插件。 */
 export declare const LOCAL_PYTHON_TOOL_SCHEMA: BuiltinToolSchema;
-/** 文件工具和 run_python。平台上对应同一个插件。 */
-export declare const BUILTIN_TOOL_SCHEMAS: Record<LocalFilesFunctionCode | typeof LOCAL_PYTHON_FUNCTION_CODE, BuiltinToolSchema>;

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

@@ -82,6 +82,19 @@ export interface LocalFilesConfig {
     onApprovalRequired?: ApprovalHandler;
     /** 替换默认的会话文件上传/下载实现。 */
     transfer?: Partial<SessionFileTransfer>;
+    /** shell、run_file、run_skill_script 的执行方式。宿主沙箱由宿主能力声明决定，不在这里配置。 */
+    commandRuntime?: CommandRuntimeConfig;
+}
+export interface CommandRuntimeConfig {
+    /** 没有宿主沙箱时，在页面里解释 shell 命令、用 Pyodide 运行 Python。 */
+    browser?: {
+        /** 默认 true。设为 false 后，没有宿主沙箱时命令返回 501。 */
+        enabled?: boolean;
+        /** just-bash 浏览器构建（ES Module）的地址。默认使用公司 OBS 上与 SDK 匹配的版本。 */
+        bashModuleURL?: string;
+        /** Pyodide 资源目录，以 `/` 结尾。默认使用公司 OBS 上与 SDK 匹配的版本。 */
+        pyodideIndexURL?: string;
+    };
 }
 export interface PythonApprovalRequest {
     requestId: string;
@@ -260,7 +273,7 @@ export interface WorkspaceChangedEvent {
 export interface ToolEventBase {
     requestId: string;
     sessionId: string;
-    functionCode: LocalFilesFunctionCode;
+    functionCode: string;
     path?: string;
 }
 export interface ToolProgressEvent extends ToolEventBase {

package/dist/src/localFiles/workspace/LocalWorkspace.d.ts

@@ -1,3 +1,4 @@
+import { CommandRunner } from '../../builtinTools/command';
 import { WorkspaceFileAdapter } from '../adapters/WorkspaceFileAdapter';
 import { ShowDirectoryPicker } from '../adapters/fsaTypes';
 import { LocalFilesLimits } from '../constants';
@@ -15,6 +16,8 @@ export interface LocalWorkspaceOptions {
     /** 默认会话文件传输的 API 来源；config.transfer 中的方法优先。 */
     transfer?: SessionFileTransfer;
     fetch?: typeof fetch;
+    /** shell、run_file、run_skill_script 的执行器。未设置时依次尝试宿主沙箱、浏览器运行时。 */
+    commandRunner?: CommandRunner;
 }
 /**
  * 工作文件夹授权与运行状态。一个 BotClient 对应一个实例；UI 与纯 SDK 集成共用同一实例。
@@ -27,6 +30,12 @@ export declare class LocalWorkspace {
     readonly allowWorkspaceWideTextSearch: boolean;
     readonly transfer: SessionFileTransfer;
     readonly fetch: typeof fetch;
+    commandRunner?: CommandRunner;
+    readonly browserRuntime: {
+        enabled: boolean;
+        bashModuleURL?: string;
+        pyodideIndexURL?: string;
+    };
     private readonly store;
     private readonly picker?;
     private readonly event;
@@ -36,6 +45,7 @@ export declare class LocalWorkspace {
     private pendingHandle;
     private approvalHandler?;
     private activeCalls;
+    private commandRunning;
     private readonly inflight;
     private _ready;
     private stopWatching;
@@ -84,6 +94,8 @@ export declare class LocalWorkspace {
     getApprovalHandler(): ApprovalHandler | undefined;
     /** @internal 占用一个并发名额；已满时返回 null。 */
     acquireSlot(): (() => void) | null;
+    /** @internal 同一工作区同一时间只跑一个命令；已有命令在运行时返回 null。 */
+    acquireCommand(): (() => void) | null;
     /** @internal 登记进行中的调用，更换或断开工作区时统一中止。 */
     track(controller: AbortController): () => boolean;
     /** 中止所有进行中的调用（含等待确认的请求）。 */