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

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

@@ -0,0 +1,306 @@
+import { LocalFilesFunctionCode, LocalFilesLimits } from './constants';
+import { ToolErrorReason } from './errors';
+import { SensitiveRuleInput } from './security/sensitiveFiles';
+import { SessionFileTransfer } from './transfer/SessionFileTransfer';
+/** 客户端插件被调用时 SDK 传入的第三个参数。 */
+export interface ToolContext {
+    requestId: string;
+    applicationId: string;
+    sessionId: string;
+    pluginCode: string;
+    functionCode: string;
+    signal?: AbortSignal;
+}
+export type ClientPluginContext = ToolContext;
+export interface ToolResult<T = unknown> {
+    code: number;
+    message: string;
+    data?: T;
+    truncated?: boolean;
+    warnings?: string[];
+}
+export type ClientPluginCallback = (result: ToolResult) => void;
+export type ApprovalFunctionCode = Extract<LocalFilesFunctionCode, 'apply_patch' | 'write_file' | 'upload_file' | 'download_file'>;
+export interface TextChangePreview {
+    type: 'text';
+    /** 修改前文本；新建文件时为 undefined。 */
+    before?: string;
+    after: string;
+    created: boolean;
+}
+export interface UploadPreview {
+    type: 'upload';
+    name: string;
+    size: number;
+    target: 'session';
+}
+export interface DownloadPreview {
+    type: 'download';
+    source: {
+        type: DownloadSource['type'];
+        /** 面向用户的来源描述，如「会话文件」或 URL 主机名。 */
+        label: string;
+    };
+    name?: string;
+    size?: number;
+    overwrite: boolean;
+}
+export type ApprovalPreview = TextChangePreview | UploadPreview | DownloadPreview;
+export interface ApprovalRequest {
+    id: string;
+    requestId: string;
+    sessionId: string;
+    functionCode: ApprovalFunctionCode;
+    /** 工作区相对路径。 */
+    path: string;
+    workspaceName: string;
+    preview: ApprovalPreview;
+    /** 调用被取消（停止回答、会话失活、更换工作区）时中止，确认 UI 应据此关闭。 */
+    signal: AbortSignal;
+}
+export type ApprovalHandler = (request: ApprovalRequest) => boolean | Promise<boolean>;
+export interface LocalFilesConfig {
+    enabled?: boolean;
+    /**
+     * `file-system-access`：网页里由用户选择目录。
+     * `host-bridge`：目录由宿主通过 `chrome.webview` 设置，页面不弹选择框。
+     */
+    backend?: 'file-system-access' | 'host-bridge';
+    /**
+     * 平台上的内置工具插件编码。文件工具和 run_python 使用同一个编码。
+     * 未配置时按 env 取 BUILTIN_TOOLS_PLUGIN_CODES。
+     */
+    pluginCode?: string;
+    /** 在默认 `['glodon.com']` 之外追加允许下载的域名后缀。 */
+    downloadUrlAllowlistAppend?: string[];
+    /** 在 SDK 敏感文件基线之外追加规则。 */
+    sensitiveRulesAppend?: SensitiveRuleInput[];
+    /** 只能调小；大于默认值的配置按默认值处理。 */
+    limits?: Partial<LocalFilesLimits>;
+    allowWorkspaceWideTextSearch?: boolean;
+    /** 写入与传输前的确认；未配置时这些工具一律拒绝执行。 */
+    onApprovalRequired?: ApprovalHandler;
+    /** 替换默认的会话文件上传/下载实现。 */
+    transfer?: Partial<SessionFileTransfer>;
+}
+export interface PythonApprovalRequest {
+    requestId: string;
+    sessionId: string;
+    path: string;
+    args: string[];
+    workspaceName: string;
+    signal: AbortSignal;
+}
+export type PythonApprovalHandler = (request: PythonApprovalRequest) => boolean | Promise<boolean>;
+export interface LocalPythonConfig {
+    enabled?: boolean;
+    /**
+     * 平台上的内置工具插件编码，须与文件工具相同。
+     * 未配置时跟随 localFiles.pluginCode，再按 env 取 BUILTIN_TOOLS_PLUGIN_CODES。
+     */
+    pluginCode?: string;
+    /** 运行脚本前的确认。与文件写入确认分开；未配置时一律拒绝。 */
+    onApprovalRequired?: PythonApprovalHandler;
+}
+export interface BuiltinPluginsConfig {
+    localFiles?: LocalFilesConfig;
+    localPython?: LocalPythonConfig;
+}
+export interface WorkspaceGrantInput {
+    grantId: string;
+}
+export interface ListDirectoryInput extends WorkspaceGrantInput {
+    path?: string;
+    offset?: number;
+    limit?: number;
+}
+export interface DirectoryEntry {
+    name: string;
+    path: string;
+    kind: 'file' | 'directory';
+    size?: number;
+    lastModified?: number;
+    sensitive?: boolean;
+}
+export interface ListDirectoryOutput {
+    path: string;
+    entries: DirectoryEntry[];
+    total: number;
+    hasMore: boolean;
+}
+export type TextEncodingName = 'utf-8' | 'gbk' | 'gb18030';
+export interface ReadFileInput extends WorkspaceGrantInput {
+    path: string;
+    startLine?: number;
+    endLine?: number;
+    maxBytes?: number;
+    encoding?: TextEncodingName;
+}
+export interface ReadFileOutput {
+    path: string;
+    content: string;
+    startLine: number;
+    endLine: number;
+    /** 仅在完整扫描了文件时返回。 */
+    totalLines?: number;
+    size: number;
+    encoding: TextEncodingName;
+    lineEnding: 'lf' | 'crlf';
+    hash?: string;
+}
+export interface StatFileInput extends WorkspaceGrantInput {
+    path: string;
+    includeHash?: boolean;
+}
+export interface StatFileOutput {
+    path: string;
+    kind: 'file' | 'directory';
+    size?: number;
+    lastModified?: number;
+    sensitive: boolean;
+    hash?: string;
+}
+export interface SearchFilesInput extends WorkspaceGrantInput {
+    pattern: string;
+    path?: string;
+    maxDepth?: number;
+    maxResults?: number;
+}
+export interface SearchFilesMatch {
+    path: string;
+    size?: number;
+    lastModified?: number;
+}
+export interface SearchFilesOutput {
+    matches: SearchFilesMatch[];
+}
+export interface SearchTextInput extends WorkspaceGrantInput {
+    path: string;
+    query: string;
+    caseSensitive?: boolean;
+    isRegex?: boolean;
+    glob?: string;
+    maxResults?: number;
+    contextLines?: number;
+}
+export interface SearchTextMatch {
+    path: string;
+    line: number;
+    column: number;
+    text: string;
+    before?: string[];
+    after?: string[];
+}
+export interface SearchTextOutput {
+    matches: SearchTextMatch[];
+    filesScanned: number;
+}
+export interface PatchEdit {
+    oldText: string;
+    newText: string;
+    replaceAll?: boolean;
+}
+export interface ApplyPatchInput extends WorkspaceGrantInput {
+    path: string;
+    expectedHash: string;
+    edits: PatchEdit[];
+}
+export interface WriteResultOutput {
+    path: string;
+    hash: string;
+    size: number;
+}
+export interface WriteFileInput extends WorkspaceGrantInput {
+    path: string;
+    content: string;
+    expectedHash?: string;
+    createDirectories?: boolean;
+}
+export interface WriteFileOutput extends WriteResultOutput {
+    created: boolean;
+}
+export interface UploadFileInput extends WorkspaceGrantInput {
+    path: string;
+    target?: string;
+    mimeHint?: string;
+}
+export interface UploadFileOutput {
+    fileId: string;
+    name: string;
+    size: number;
+    /** 平台预签名访问链接，给模型用于后续推理或对话。 */
+    url: string;
+}
+export type DownloadSource = {
+    type: 'sessionFile';
+    fileId: string;
+} | {
+    type: 'platformFile';
+    fileId: string;
+} | {
+    type: 'url';
+    url: string;
+};
+export interface DownloadFileInput extends WorkspaceGrantInput {
+    destPath: string;
+    source: DownloadSource;
+    overwrite?: boolean;
+    expectedHash?: string;
+}
+export interface DownloadFileOutput {
+    path: string;
+    size: number;
+    hash: string;
+}
+export type LocalWorkspaceStatus = 'unsupported' | 'none' | 'prompt' | 'granted' | 'denied';
+export interface WorkspaceChangedEvent {
+    status: LocalWorkspaceStatus;
+    displayName?: string;
+}
+export interface ToolEventBase {
+    requestId: string;
+    sessionId: string;
+    functionCode: LocalFilesFunctionCode;
+    path?: string;
+}
+export interface ToolProgressEvent extends ToolEventBase {
+    stage: 'reading' | 'uploading' | 'downloading' | 'writing' | 'done';
+    loaded: number;
+    total?: number;
+}
+export interface ToolFinishEvent extends ToolEventBase {
+    code: number;
+}
+export interface ToolErrorEvent extends ToolEventBase {
+    code: number;
+    message: string;
+    reason?: ToolErrorReason;
+}
+export interface ToolApprovalEvent extends ToolEventBase {
+    approvalId: string;
+}
+/** 目录树需要重读的范围。`paths` 为空时重读根目录和当前已展开的目录。 */
+export interface FilesChangedEvent {
+    paths: string[];
+}
+export interface LocalWorkspaceEventMap {
+    'workspace:changed': WorkspaceChangedEvent;
+    /** 本地目录有增删。短时间内的多次变化会合并成一次。 */
+    'files:changed': FilesChangedEvent;
+    'tool:start': ToolEventBase;
+    /** 只含摘要；完整预览只交给 onApprovalRequired。 */
+    'tool:approval-required': ToolApprovalEvent;
+    'tool:progress': ToolProgressEvent;
+    'tool:finish': ToolFinishEvent;
+    'tool:error': ToolErrorEvent;
+    'tool:cancelled': ToolEventBase;
+}
+export type LocalWorkspaceEventName = keyof LocalWorkspaceEventMap;
+export interface WorkspaceHandshake {
+    protocolVersion: '1.0';
+    capabilities: Record<LocalFilesFunctionCode, boolean> & {
+        cancellation: boolean;
+        atomicWrite: boolean;
+    };
+    limits: LocalFilesLimits;
+}

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

@@ -0,0 +1,2 @@
+import { JsonSchema } from './schemas';
+export declare function validateToolInput<T>(params: unknown, schema: JsonSchema): T;

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

@@ -0,0 +1,99 @@
+import { WorkspaceFileAdapter } from '../adapters/WorkspaceFileAdapter';
+import { ShowDirectoryPicker } from '../adapters/fsaTypes';
+import { LocalFilesLimits } from '../constants';
+import { SensitiveFilePolicy } from '../security/sensitiveFiles';
+import { SessionFileTransfer } from '../transfer/SessionFileTransfer';
+import { ApprovalHandler, LocalFilesConfig, LocalWorkspaceEventMap, LocalWorkspaceEventName, LocalWorkspaceStatus, WorkspaceHandshake } from '../types';
+import { KeyValueStore } from './handleStore';
+export interface LocalWorkspaceOptions {
+    applicationId: string;
+    config?: LocalFilesConfig;
+    /** 句柄与外发提示标记的存储，默认内存存储；BotClient 传入 IndexedDB 存储。 */
+    store?: KeyValueStore;
+    /** 默认使用 window.showDirectoryPicker；传 null 表示不支持。 */
+    picker?: ShowDirectoryPicker | null;
+    /** 默认会话文件传输的 API 来源；config.transfer 中的方法优先。 */
+    transfer?: SessionFileTransfer;
+    fetch?: typeof fetch;
+}
+/**
+ * 工作文件夹授权与运行状态。一个 BotClient 对应一个实例；UI 与纯 SDK 集成共用同一实例。
+ */
+export declare class LocalWorkspace {
+    readonly applicationId: string;
+    readonly limits: LocalFilesLimits;
+    readonly sensitive: SensitiveFilePolicy;
+    readonly downloadUrlAllowlist: string[];
+    readonly allowWorkspaceWideTextSearch: boolean;
+    readonly transfer: SessionFileTransfer;
+    readonly fetch: typeof fetch;
+    private readonly store;
+    private readonly picker?;
+    private readonly event;
+    private _status;
+    private _displayName?;
+    private _adapter;
+    private pendingHandle;
+    private approvalHandler?;
+    private activeCalls;
+    private readonly inflight;
+    private _ready;
+    private stopWatching;
+    private readonly pendingChangePaths;
+    private changeTimer;
+    private refreshAllVisible;
+    constructor(options: LocalWorkspaceOptions);
+    get status(): LocalWorkspaceStatus;
+    /** 当前（或待恢复的）文件夹名，不含绝对路径。 */
+    get displayName(): string | undefined;
+    get isSupported(): boolean;
+    /** 最近一次 restore() 完成前，工具调用会等待它。 */
+    get ready(): Promise<void>;
+    /** @internal 已授权时可用的 Adapter。 */
+    get adapter(): WorkspaceFileAdapter | null;
+    private get handleKey();
+    private get disclosureKey();
+    private setStatus;
+    private attachHandle;
+    /**
+     * 弹出目录选择框。必须在用户点击事件中调用。
+     * 用户取消时返回 false 且状态不变。
+     */
+    pick(): Promise<boolean>;
+    /** 读取上次的目录句柄并检查权限，不弹窗。 */
+    restore(): Promise<void>;
+    private doRestore;
+    /** 对已保存的目录重新申请权限。必须在用户点击事件中调用。 */
+    requestPermission(): Promise<boolean>;
+    /** 断开工作区并删除持久化句柄。状态立即变为未授权，存储删除在其后完成。 */
+    clear(): Promise<void>;
+    /** 直接挂载一个 Adapter（测试或自定义后端），视为已授权。 */
+    attachAdapter(adapter: WorkspaceFileAdapter, displayName?: string): void;
+    /**
+     * 通知目录树重读。`paths` 是相对工作区根的目录；省略时重读当前展开的全部目录。
+     * 短时间内的多次通知会合并成一次。
+     */
+    notifyFilesChanged(paths?: readonly string[]): void;
+    /** @internal 工具执行中遇到权限错误时调用，重新检查并更新状态。 */
+    handlePermissionLost(): Promise<void>;
+    isDisclosureAcknowledged(): Promise<boolean>;
+    acknowledgeDisclosure(): Promise<void>;
+    setApprovalHandler(handler?: ApprovalHandler): void;
+    get hasApprovalHandler(): boolean;
+    /** @internal */
+    getApprovalHandler(): ApprovalHandler | undefined;
+    /** @internal 占用一个并发名额；已满时返回 null。 */
+    acquireSlot(): (() => void) | null;
+    /** @internal 登记进行中的调用，更换或断开工作区时统一中止。 */
+    track(controller: AbortController): () => boolean;
+    /** 中止所有进行中的调用（含等待确认的请求）。 */
+    cancelAll(): void;
+    handshake(): WorkspaceHandshake;
+    on<K extends LocalWorkspaceEventName>(name: K, listener: (payload: LocalWorkspaceEventMap[K]) => void): () => void;
+    off<K extends LocalWorkspaceEventName>(name: K, listener: (payload: LocalWorkspaceEventMap[K]) => void): void;
+    private unwatchDirectory;
+    private cancelFilesChanged;
+    private flushFilesChanged;
+    /** @internal */
+    emit<K extends LocalWorkspaceEventName>(name: K, payload: LocalWorkspaceEventMap[K]): void;
+}

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

@@ -0,0 +1,11 @@
+export interface KeyValueStore {
+    get<T>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export declare function createMemoryStore(): KeyValueStore;
+/**
+ * IndexedDB 存储。DirectoryHandle 可被结构化克隆，必须存在 IndexedDB 中才能跨页面恢复。
+ * 不支持 IndexedDB 的环境退化为内存存储（刷新后需重新选择目录）。
+ */
+export declare function createIndexedDbStore(dbName?: string): KeyValueStore;

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

@@ -0,0 +1,7 @@
+import { FsaDirectoryHandle } from '../adapters/fsaTypes';
+/**
+ * 监听已授权的目录句柄。浏览器没有 FileSystemObserver 时返回空函数，
+ * 界面改为在窗口回到前台时重读。
+ * 回调收到的 paths 省略时，表示需要重读全部可见目录。
+ */
+export declare function watchDirectoryHandle(handle: FsaDirectoryHandle, onChange: (paths?: string[]) => void): () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glodon-aiot/bot-client-sdk",
-  "version": "3.25.1-alpha.6",
+  "version": "3.26.0-alpha.4",
   "author": "glodoncv",
   "description": "aiot bot client js sdk",
   "type": "module",
@@ -36,7 +36,9 @@
     "preview": "vite preview",
     "check": "yarn prettier --check .",
     "write": "yarn prettier --write .",
-    "lint": "eslint --ext .tsx,.ts --fix ./example -c .eslintrc.js"
+    "lint": "eslint --ext .tsx,.ts --fix ./example -c .eslintrc.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "devDependencies": {
     "@babel/core": "^7.20.12",
@@ -69,7 +71,8 @@
     "vite": "^4.1.1",
     "vite-plugin-dts": "^4.3.0",
     "vite-plugin-externalize-deps": "^0.9.0",
-    "vite-tsconfig-paths": "^5.1.4"
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^0.34.6"
   },
   "lint-staged": {
     "*.{js,css,md,jsx,less,ts,tsx,json}": "prettier --write"
@@ -79,7 +82,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@glodon-aiot/apis": "^3.25.1-alpha.6",
+    "@glodon-aiot/apis": "^3.26.0-alpha.4",
     "axios": "0.24.0",
     "buffer": "^6.0.3",
     "dayjs": "^1.11.13",