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

package/dist/src/AgentSession.d.ts

@@ -3,12 +3,21 @@ import { MCPConfig } from './Config';
 import { default as Session, QuestionBody, QuestionConfig } from './Session';
 import { default as BotClient } from './BotClient';
 export default class AgentSession extends Session {
+    private readonly inflightCalls;
     constructor(token: string, _id?: string, _data?: Partial<ISession>, lazyload?: boolean, application?: IApplication, client?: BotClient);
     prepareConnection(): Promise<boolean>;
     registerMcpFromClientConfig(): Promise<boolean>;
     addMcpServers(mcpServers: MCPConfig): Promise<boolean>;
     listMcpServers(): Promise<MCPConfig>;
     sendQuestion(questionBody: QuestionBody, configs: QuestionConfig): Promise<false | undefined>;
+    /**
+     * 调用客户端插件：传入第三个参数 context（旧插件可忽略），结果最多回传一次，
+     * 停止回答或调用被取消后不再回传。
+     */
+    private invokeClientPlugin;
+    private abortClientPluginCalls;
     stopAnswer(): void;
+    inactivate(immediately?: boolean): boolean;
+    destroy(): string;
     private convertKnowledgesToChatFormat;
 }

package/dist/src/BotClient.d.ts

@@ -1,8 +1,9 @@
 import { default as Session } from './Session';
 import { BotClientConfig } from './Config';
-import { IApplication, IPrompt, ISession, ISessionPrompt, SessionQueryParams } from '@glodon-aiot/apis';
+import { LocalWorkspace } from './localFiles/workspace/LocalWorkspace';
+import { IApplication, IPrompt, ISession, ISessionArtifact, ISessionPrompt, SessionQueryParams } from '@glodon-aiot/apis';
 import { default as EventBus } from './EventBus';
-export type ClientEventName = 'ready' | 'application:loaded';
+export type ClientEventName = 'ready' | 'application:loaded' | 'error';
 export interface SDKConfig {
     analytics: {
         enabled: boolean;
@@ -25,8 +26,13 @@ export default class BotClient {
     private _ready?;
     private _questionContextMaxLength?;
     private _promptVariables?;
+    private _localWorkspace?;
+    private _disconnectHost?;
     constructor(_token: string, //AIoT resource token
     configs: BotClientConfig, lazyload?: boolean, sdkConfigs?: SDKConfig);
+    private setupLocalWorkspace;
+    /** 启用 builtinPlugins.localFiles 后可用；UI 与纯 SDK 集成共用此实例。 */
+    get localWorkspace(): LocalWorkspace | undefined;
     private checkReady;
     get ready(): boolean | undefined;
     private set ready(value);
@@ -44,6 +50,10 @@ export default class BotClient {
     get activeSession(): string;
     set activeSession(sessionId: string);
     private createSession;
+    /**
+     * 获取会话产出物。不传 sessionId 时取当前活跃会话。没有产出物时返回空数组。
+     */
+    getArtifacts(sessionId?: string): Promise<ISessionArtifact[]>;
     getSessions(queryParams?: SessionQueryParams): Promise<Session[]>;
     loadSession(sessionId?: string, sessionParams?: Partial<ISession & {
         promptVariables?: ISessionPrompt[];

package/dist/src/Config.d.ts

@@ -1,3 +1,5 @@
+import { BuiltinPluginsConfig, LocalFilesConfig, LocalPythonConfig } from './localFiles/types';
+import { LocalWorkspace } from './localFiles/workspace/LocalWorkspace';
 export interface McpServer {
     type: 'sse';
     url: string;
@@ -17,6 +19,8 @@ export interface BotClientConfig {
     loadRelatedQuesions?: boolean;
     mcp?: MCPConfig;
     stream?: boolean;
+    /** SDK 内置插件。文件、命令和技能工具注册到同一个 pluginCode。 */
+    builtinPlugins?: BuiltinPluginsConfig;
 }
 export interface AgentPluginRegistor {
     [key: string]: Function;
@@ -36,11 +40,29 @@ export declare let configuration: {
     env: string;
     apiRoot: string;
     applicationId: string;
+    /** 最终生效的插件表 = 业务插件 + 内置插件，由 configure() 计算，不要直接修改。 */
     plugins: AgentPluginMap;
+    /** 集成方传入的原始 plugins。 */
+    businessPlugins: AgentPluginMap;
+    builtinPlugins: BuiltinPluginsConfig | undefined;
     mcp: (MCPConfig | undefined);
     loadRelatedQuesions: boolean;
     stream: boolean;
 };
+export declare function setActiveLocalWorkspace(workspace?: LocalWorkspace): void;
+export declare function getActiveLocalWorkspace(): LocalWorkspace | undefined;
+/** 当前已注册到 configuration.plugins 的内置文件工具编码；未注册时返回 undefined。 */
+export declare function getRegisteredLocalFilesPluginCode(): string | undefined;
+/** 当前已注册到 configuration.plugins 的脚本工具所在插件编码；未注册时返回 undefined。 */
+export declare function getRegisteredLocalPythonPluginCode(): string | undefined;
+/** 显式配置优先，其次按 env 取默认值；都没有时返回 undefined。 */
+export declare function resolveLocalFilesPluginCode(config: LocalFilesConfig | undefined, env: string): string;
+/** 显式配置优先，其次跟随文件工具编码，最后按 env 取默认值。 */
+export declare function resolveLocalPythonPluginCode(config: LocalPythonConfig | undefined, env: string, filesPluginCode?: string): string;
+/**
+ * 重新计算 configuration.plugins，返回本次新出现的问题（相同问题只报告一次）。
+ */
+export declare function refreshBuiltinPlugins(): Error[];
 /**
  * 配置SDK，可以在SDK被使用前被调用，该方法被调用后将改变是否debug模式、是否测试环境等基本配置
  * @param param {debug?: boolean; env?: 'dev' | 'test' | 'prod';}

package/dist/src/Session.d.ts

@@ -1,4 +1,4 @@
-import { ChatMessageRole, IApplication, IChatMessage, ICommentParam, ISession, ISessionPrompt, CVForceApi, ChatHistoryParams, IKnowledge } from '@glodon-aiot/apis';
+import { ChatMessageRole, IApplication, IChatMessage, ICommentParam, ISession, ISessionArtifact, ISessionPrompt, CVForceApi, ChatHistoryParams, IKnowledge } from '@glodon-aiot/apis';
 import { MCPConfig } from './Config';
 import { Socket } from 'socket.io-client';
 import { default as EventBus } from './EventBus';
@@ -212,6 +212,10 @@ export default abstract class Session {
      * @param params - 评论参数，包含评论相关的信息，如消息 ID 等
      * @returns 返回调用 API 提交评论后的响应结果
      */
+    /**
+     * 获取当前会话的产出物。没有产出物时返回空数组。
+     */
+    getArtifacts(): Promise<ISessionArtifact[]>;
     postMessageComment(params: ICommentParam): Promise<string>;
     /**
      * 清除当前会话的上下文信息

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

@@ -1,2 +1,4 @@
-import { CVForceApi } from '@glodon-aiot/apis';
+import { AIShopApi, CVForceApi } from '@glodon-aiot/apis';
 export declare function getCVForceService(apiBase: string, token: string, errorHandler: (status: number, message: string) => void): CVForceApi;
+/** 平台文件上传与查询，base 为 `${apiRoot}/aishop`。 */
+export declare function getAIShopService(apiBase: string, token: string, errorHandler: (status: number, message: string) => void): AIShopApi;

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/index.d.ts

@@ -1,5 +1,7 @@
-export type { AgentPluginRegistor, AgentPluginMap, MCPConfig, McpServer } from './Config';
-export { configure, configuration } from './Config';
+export type { AgentPluginRegistor, AgentPluginMap, BotClientConfig, MCPConfig, McpServer } from './Config';
+export { configure, configuration, getRegisteredLocalFilesPluginCode, getRegisteredLocalPythonPluginCode, resolveLocalFilesPluginCode, } from './Config';
+export type { ISessionArtifact } from '@glodon-aiot/apis';
 export { default as BotClient } from './BotClient';
 export { default as Session } from './Session';
 export { default as AgentPlugin } from './AgentPlugin';
+export * from './localFiles';

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

@@ -0,0 +1,20 @@
+import { RemoveOptions, WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource } from './WorkspaceFileAdapter';
+import { FsaDirectoryHandle } from './fsaTypes';
+/**
+ * 基于用户授权的 DirectoryHandle 的工作区。只通过逐级 getDirectoryHandle / getFileHandle
+ * 访问子树，不使用任何绝对路径。FSA 不暴露符号链接目标，链接的处理以浏览器行为为准。
+ */
+export declare class FileSystemAccessAdapter implements WorkspaceFileAdapter {
+    private readonly root;
+    constructor(root: FsaDirectoryHandle);
+    get displayName(): string;
+    private resolveDirectory;
+    private resolveFile;
+    stat(path: string): Promise<WorkspaceEntry>;
+    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

@@ -0,0 +1,43 @@
+import { CommandRequest, CommandResult } from '../../builtinTools/command';
+import { WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource } from './WorkspaceFileAdapter';
+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;
+        stdout: string;
+        stderr: string;
+    }>;
+    writeFile(path: string, source: WriteSource, options?: WriteOptions): Promise<void>;
+}

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

@@ -0,0 +1,21 @@
+import { RemoveOptions, WorkspaceEntry, WorkspaceFileAdapter, WriteOptions, WriteSource } from './WorkspaceFileAdapter';
+/** 内存工作区：用于测试与契约基准，语义与 FileSystemAccessAdapter 一致。 */
+export declare class MemoryWorkspaceAdapter implements WorkspaceFileAdapter {
+    readonly displayName: string;
+    private root;
+    constructor(files?: Record<string, string | Uint8Array>, displayName?: string);
+    /**
+     * 直接写入文件（含中间目录），用于构造测试数据或模拟外部修改。
+     * 以 `/` 结尾的路径表示创建空目录。
+     */
+    seed(path: string, content?: string | Uint8Array, lastModified?: number): void;
+    private resolveDirectory;
+    private resolveNode;
+    stat(path: string): Promise<WorkspaceEntry>;
+    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

@@ -0,0 +1,40 @@
+export interface WorkspaceEntry {
+    name: string;
+    kind: 'file' | 'directory';
+    size?: number;
+    lastModified?: number;
+}
+export type WriteSource = string | Uint8Array | AsyncIterable<Uint8Array>;
+export interface WriteOptions {
+    createDirectories?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * 工作区磁盘原语。路径均为已规范化的工作区相对路径，根目录为空字符串。
+ * 失败时抛出与 FSA 同名的 DOMException（NotFoundError、TypeMismatchError 等），
+ * 由工具层统一映射为错误码，保证不同后端语义一致。
+ */
+export interface WorkspaceFileAdapter {
+    readonly displayName: string;
+    stat(path: string): Promise<WorkspaceEntry>;
+    listEntries(path: string, signal?: AbortSignal): Promise<WorkspaceEntry[]>;
+    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>;