keepwork-sdk 1.0.0

package/dist-npm/types/src/store/PersonalPageStore.sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonalPageStore.sync.d.ts","sourceRoot":"","sources":["../../../../src/store/PersonalPageStore.sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,qBAAa,qBAAsB,SAAQ,qBAAqB;IAI9D;;;;;;OAMG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA8CxD;;;;;OAKG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBzD;;;OAGG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQpC;;;OAGG;IACH,oBAAoB,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAYtF;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA4B3C;;;;;;OAMG;IACG,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BpF;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IA2CzE;;;;;;;;OAQG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAsCxE;;;OAGG;IACH,iBAAiB,IAAI,IAAI;IAezB;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IA2BxC;;;;;;OAMG;IACG,cAAc,CAAC,SAAS,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IA6BxD;;OAEG;IACG,iBAAiB,CAAC,SAAS,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAM3D;;;OAGG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAW5C;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAUlC;;;;;;;;;OASG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBvF;;;;;;;;OAQG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBlG;;;;;;;;;OASG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EACb,QAAQ,UAAQ,EAChB,cAAc,CAAC,EAAE,MAAM,EACvB,UAAU,SAAM,GACf,OAAO,CAAC,MAAM,CAAC;IA2ElB;;;;;OAKG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOrE;;;;;;;;OAQG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,UAAQ,EAAE,OAAO,GAAE,cAAc,GAAG,IAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CA4G1G"}

package/dist-npm/types/src/store/PersonalPageStore.types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * PersonalPageStore.types.ts — PersonalPageStore 共享类型定义
+ *
+ * 被 PersonalPageStore.base / data / sync 三个分层文件共同使用，
+ * 避免循环导入。
+ */
+/** mountedFolder 规范化后的对象格式 */
+export interface MountedFolder {
+    /** 外部用户名 */
+    username: string;
+    /** 外部工作空间名 */
+    workspace: string;
+    /** 远端存储路径（默认继承 remoteStorePath）*/
+    remoteStorePath: string;
+}
+/** addSearchPath 注册的 URL 回退搜索路径 */
+export interface SearchPath {
+    /** 路径前缀（含 workspace，如 "myws/skills"） */
+    prefix: string;
+    /** 基础 URL（末尾含 /，如 "https://cdn.example.com/skills/"） */
+    baseUrl: string;
+    /** 是否只读（只读路径在 readFile 中优先级最高） */
+    isReadonly: boolean;
+}
+/** 站点树条目（来自 sdk.getSiteTree）*/
+export interface TreeEntry {
+    name?: string;
+    path?: string;
+    isTree?: boolean;
+    isBlob?: boolean;
+    children?: TreeEntry[];
+}
+/** 各页面的同步选项 */
+export interface PageSyncOptions {
+    useCache?: boolean;
+}
+/** 页面数据的版本元数据 */
+export interface PageMetadata {
+    version?: number;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+/** versionConflict 事件载荷 */
+export interface VersionConflictEvent {
+    pageKey: string;
+    localVersion: number;
+    remoteVersion: number;
+    localUpdatedAt: string;
+    remoteUpdatedAt: string;
+    localLength: number;
+    remoteLength: number;
+    tiebreaker: 'updated_at' | 'length';
+    resolution: 'local' | 'remote';
+}
+/** savePageDataTimeSeries 的 keyValue 条目 */
+export interface TimeSeriesKeyValue {
+    key: string;
+    value: unknown;
+    type?: 'unique' | 'replace' | 'addictive' | 'mean';
+    /** 内部字段，函数执行过程中填充 */
+    values?: unknown[];
+}
+/** listDir 的附加选项 */
+export interface ListDirOptions {
+    /** 是否显示以 '.' 开头的隐藏文件 */
+    showInvisibleFiles?: boolean;
+    /** 仅列出远端文件，跳过本地 */
+    remoteOnly?: boolean;
+    /** 跳过仅存在于本地磁盘（不在远端）的文件 */
+    skipLocalOnlyFile?: boolean;
+}
+/**
+ * PersonalPageStore 依赖的 SDK 最小接口（避免与主类循环引用）
+ */
+export interface IPersonalPageSDK {
+    token?: string | null;
+    user?: {
+        username?: string;
+        [key: string]: unknown;
+    } | null;
+    extractMainDomain?: (hostname: string) => string;
+    getUserProfile?: (opts?: {
+        useCache?: boolean;
+    }) => Promise<unknown>;
+    getMarkdownByFullPath?: (path: string, cb?: unknown, useCache?: boolean) => Promise<string | null>;
+    editMarkdownByFullPath?: (path: string, content: string, cb?: unknown, useCache?: boolean) => Promise<unknown>;
+    deleteMarkdownByFullPath?: (path: string, cb?: unknown) => Promise<unknown>;
+    getSiteTree?: (sitePath: string, recursive?: boolean, folderPath?: string, useCache?: boolean) => Promise<TreeEntry[]>;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=PersonalPageStore.types.d.ts.map

package/dist-npm/types/src/store/PersonalPageStore.types.d.ts.map

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

package/dist-npm/types/src/store/YMLParser.d.ts

@@ -0,0 +1,96 @@
+/**
+ * YMLParser — Keepwork 页面数据专用 YAML 序列化/反序列化工具
+ *
+ * 实现了一个轻量级的 YAML 子集解析器，用于读写存储在 PersonalPage 中的结构化数据。
+ * 支持 front-matter 格式（`---` 分隔的 YAML 头 + 正文），常用于页面元数据 + 内容分离。
+ *
+ * 注意：这不是一个完整的 YAML 实现；设计目标是覆盖 Keepwork 页面数据的实际存储格式，
+ * 保持与现有 Lua 端（KeepworkReposApi）序列化行为的兼容。
+ */
+/** objectToYaml 的选项 */
+export interface ObjectToYamlOptions {
+    /** 是否按字母顺序排序键，默认 true */
+    isSortKeys?: boolean;
+    /** 是否使用 front-matter 格式（将 content 键序列化为 --- 块后的正文），默认 false */
+    useFrontMatter?: boolean;
+}
+/** yamlToObject 的选项 */
+export interface YamlToObjectOptions {
+    /** 是否解析 front-matter 格式，默认 false */
+    useFrontMatter?: boolean;
+}
+/** 可序列化的 YAML 值类型（递归） */
+export type YamlValue = string | number | boolean | null | YamlValue[] | {
+    [key: string]: YamlValue;
+};
+declare class YMLParser {
+    /**
+     * 将 JavaScript 对象序列化为 YAML 字符串。
+     *
+     * 当 `useFrontMatter=true` 且对象含有 `content` 键时，
+     * 输出格式为：
+     * ```
+     * ---
+     * key1: value1
+     * ---
+     * <content 字符串>
+     * ```
+     *
+     * @param obj           - 要序列化的对象
+     * @param isSortKeys    - 是否按字母排序键（默认 true）
+     * @param useFrontMatter - 是否使用 front-matter 格式（默认 false）
+     * @returns 序列化后的 YAML 字符串
+     */
+    static objectToYaml(obj: Record<string, YamlValue>, isSortKeys?: boolean, useFrontMatter?: boolean): string;
+    /**
+     * 将 YAML 字符串反序列化为 JavaScript 对象。
+     *
+     * 解析顺序：
+     * 1. 若启用 `useFrontMatter` 且以 `---` 开头，先尝试 front-matter 解析
+     * 2. 回退尝试 JSON.parse（兼容旧版 JSON 存储格式）
+     * 3. 最终使用自有 YAML 行解析器
+     *
+     * @param yamlString    - YAML/JSON 字符串
+     * @param useFrontMatter - 是否解析 front-matter 格式（默认 false）
+     * @returns 解析后的对象，失败时返回空对象 `{}`
+     */
+    static yamlToObject(yamlString: string, useFrontMatter?: boolean): Record<string, YamlValue> | YamlValue[];
+    /**
+     * 递归解析 YAML 行数组，返回结构化对象。
+     * 支持嵌套对象、数组、标量值，兼容 YAML 缩进层级。
+     *
+     * @param lines - 预过滤的 YAML 行（已去除空行和注释行）
+     * @returns 解析结果对象或数组
+     */
+    static parseYamlLines(lines: string[]): Record<string, YamlValue> | YamlValue[];
+    /**
+     * 从 YAML 行数组中解析指定缩进层级的数组元素。
+     *
+     * @param lines      - YAML 行数组
+     * @param baseIndent - 数组元素所在的缩进列数
+     * @returns 解析出的数组
+     */
+    static parseArrayItems(lines: string[], baseIndent: number): YamlValue[];
+    /**
+     * 将 YAML 标量字符串解析为对应的 JS 原生类型。
+     *
+     * 支持：null/~、boolean、整数、浮点数、单引号/双引号字符串、
+     * 内联 JSON 对象/数组，其余回退为字符串。
+     *
+     * @param value - 原始 YAML 标量字符串（已 trim）
+     * @returns 解析后的值
+     */
+    static parseYamlValue(value: string): YamlValue;
+    /**
+     * 解析 front-matter 格式字符串：`---\n<yaml>\n---\n<content>`
+     *
+     * 解析成功后，YAML 头部字段与 `content`（正文字符串）合并到同一对象。
+     * 若格式不匹配（缺少第二个 `---`）则返回 null。
+     *
+     * @param str - 以 `---` 开头的字符串
+     * @returns 包含 content 键的解析对象，或 null（格式不符）
+     */
+    static _parseFrontMatter(str: string): Record<string, YamlValue> | null;
+}
+export default YMLParser;
+//# sourceMappingURL=YMLParser.d.ts.map

package/dist-npm/types/src/store/YMLParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"YMLParser.d.ts","sourceRoot":"","sources":["../../../../src/store/YMLParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uBAAuB;AACvB,MAAM,WAAW,mBAAmB;IAClC,yBAAyB;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,uBAAuB;AACvB,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,yBAAyB;AACzB,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,cAAM,SAAS;IACb;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,YAAY,CACjB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC9B,UAAU,UAAO,EACjB,cAAc,UAAQ,GACrB,MAAM;IAsET;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,YAAY,CACjB,UAAU,EAAE,MAAM,EAClB,cAAc,UAAQ,GACrB,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,SAAS,EAAE;IA0B1C;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,SAAS,EAAE;IA2G/E;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE;IAgFxE;;;;;;;;OAQG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS;IAqC/C;;;;;;;;OAQG;IACH,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,IAAI;CA+BxE;AAED,eAAe,SAAS,CAAC"}

package/dist-npm/types/src/tools/AgentTool.d.ts

@@ -0,0 +1,110 @@
+/**
+ * AgentTool.ts — Agent 任务派发与管理工具（TypeScript 版）
+ *
+ * 向 LLM 暴露三个工具函数：
+ * - `runAsyncAgentTask`：将任务委托给命名子 agent 异步执行
+ * - `getParentAgentContext`：获取父 agent 会话的上下文
+ * - `restartAgent`：重启当前 agent 会话（可指定新配置文件）
+ * - `getAgentConfig`：读取 agent 的配置字段
+ *
+ * 依赖：AgentRouter（跨 iframe 路由）、ChildSessionMixin（本地子 agent）
+ * 实现细节见 AgentTool.js，此文件提供类型声明和 TS 入口。
+ */
+/** 工具函数定义（OpenAI Function Calling 格式） */
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** AgentTool 运行时配置 */
+export interface AgentToolConfig {
+    /** 关联的 ChatSession */
+    _session?: AgentSession;
+    [key: string]: unknown;
+}
+/** ChatSession 最小接口（避免循环引用） */
+export interface AgentSession {
+    name?: string;
+    workspace?: string;
+    model?: string;
+    sandbox?: {
+        processTemplate?: (v: string) => Promise<string>;
+        _activePromptFile?: string | null;
+        _templateSourceFile?: string | null;
+    };
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    customTools?: unknown[];
+    options?: Record<string, unknown>;
+    _digitalHuman?: Record<string, unknown>;
+    _digitalHumanFrame?: Record<string, unknown>;
+    _pendingChildResults?: Array<unknown>;
+    _restartSignal?: {
+        promptFile?: string;
+        tools?: string[];
+        options?: Record<string, unknown>;
+        isRestartAgentSignal?: boolean;
+        timestamp?: number;
+    } | null;
+    _characterConfig?: Record<string, unknown>;
+    _isSummarizing?: boolean;
+    enqueueChildTask?: (name: string, task: string, tools: unknown, maxIter: number, sysPrompt: unknown, opts: unknown) => void;
+    getParentContext?: (count: number) => unknown;
+    restartAgent?: (promptFile: unknown, tools: string[], options: unknown) => Promise<{
+        configSource?: string;
+    }>;
+    _handleChildCallback?: (mode: string, seconds: number) => void;
+    _emitChildStream?: (event: unknown) => void;
+    send?: (task: string, opts: Record<string, unknown>) => Promise<unknown>;
+    clear?: () => void;
+}
+/** SDK 最小接口 */
+interface SDKRef {
+    agentRouter?: {
+        hasRemoteAgent: (name: string) => boolean;
+        submitTask: (name: string, payload: unknown, callbacks: unknown) => Promise<unknown>;
+    };
+    aiChat?: {
+        createSession: (opts: unknown) => AgentSession;
+    };
+}
+declare class AgentTool {
+    static readonly definitions: ToolDefinition[];
+    private sdk;
+    private config;
+    constructor(sdk: SDKRef);
+    /** 更新工具运行时配置（由 CopilotTools.setToolConfig 调用）。 */
+    setConfig(config: AgentToolConfig): void;
+    /**
+     * 执行 agent 工具操作。
+     * 核心逻辑（模板展开、路由选择、子 session 创建等）完整实现在此文件中。
+     *
+     * @param name   - 工具名
+     * @param args   - 工具参数
+     * @param config - 运行时配置（含 _session）
+     */
+    execute(name: string, args?: Record<string, unknown>, config?: AgentToolConfig): Promise<string>;
+    private currentAgentName;
+    private summarizeDebugValue;
+    /**
+     * 通过 session.sandbox.processTemplate 展开 ${...} 表达式。
+     * 若无 sandbox 或无 ${...} 则原样返回。
+     */
+    private expandTemplate;
+    /**
+     * 在 DigitalHuman / DigitalHumanFrame 路径下创建子 ChatSession 并执行任务。
+     * 结果通过 dh.sendMessage / dhf.sendMessage 发回给主会话。
+     * 立即返回确认字符串（fire-and-forget）。
+     * @private
+     */
+    private _runChildForDigitalHuman;
+    private _resolveCharacterConfig;
+    private _getNestedValue;
+}
+export default AgentTool;
+//# sourceMappingURL=AgentTool.d.ts.map

package/dist-npm/types/src/tools/AgentTool.d.ts.map

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

package/dist-npm/types/src/tools/AppTools.d.ts

@@ -0,0 +1,122 @@
+/**
+ * AppTools.ts — 浏览器端 DOM 自动化工具（TypeScript 完整实现）
+ *
+ * 向 LLM 暴露四个工具：
+ * - `read_app`：描述当前页面可见的可交互元素快照
+ * - `click_element`：按 selector / ref 点击元素
+ * - `type_in_app`：向输入框输入文本或触发按键
+ * - `screenshot_app`：委托外部 screenshotHandler 截图
+ *
+ * 特性：
+ * - data-ai-hint / data-ai-type 属性支持非交互元素
+ * - addIframe 注册子 iframe，自动合并到 read_app 结果
+ * - ignoreList / whiteList 过滤器（持久 + 单次调用两种粒度）
+ * - 元素 ref 数字索引，支持过期 ref 回退（aria-label → 文本匹配）
+ */
+/** OpenAI Function Calling 工具定义 */
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** AppTools 运行时配置（setConfig 参数） */
+export interface AppToolsConfig {
+    readHandler?: (filters: unknown, whiteList?: string[]) => Promise<unknown>;
+    screenshotHandler?: () => Promise<unknown>;
+    clickHandler?: (args: Record<string, unknown>) => Promise<unknown>;
+    typeHandler?: (args: Record<string, unknown>) => Promise<unknown>;
+    ignoreList?: string[];
+    whiteList?: string[];
+    [key: string]: unknown;
+}
+/**
+ * AppTools — 浏览器端 DOM 自动化工具（供 CopilotTools 注册为 'app' 分类）。
+ */
+declare class AppTools {
+    static readonly definitions: ToolDefinition[];
+    private sdk;
+    private _readHandler;
+    private _screenshotHandler;
+    private _clickHandler;
+    private _typeHandler;
+    private _refMap;
+    private _refMetaMap;
+    private _iframeRefMap;
+    private _ignoreList;
+    private _whiteList;
+    private _iframes;
+    private _pendingCalls;
+    private _callIdCounter;
+    private _instanceId;
+    private _onMessage?;
+    constructor(sdk: unknown);
+    setReadHandler(handler: (filters: unknown, whiteList?: string[]) => Promise<unknown>): void;
+    setScreenshotHandler(handler: () => Promise<unknown>): void;
+    setClickHandler(handler: (args: Record<string, unknown>) => Promise<unknown>): void;
+    setTypeHandler(handler: (args: Record<string, unknown>) => Promise<unknown>): void;
+    /** 设置持久 ignore 列表（CSS selectors），匹配的元素及其后代从 read_app 排除。 */
+    setIgnoreList(selectors: string[]): void;
+    /** 设置持久 white 列表（CSS selectors），非空时只返回匹配元素或其后代。 */
+    setWhiteList(selectors: string[]): void;
+    /** 更新运行时配置（由 CopilotTools.setToolConfig 调用）。 */
+    setConfig(config: AppToolsConfig): void;
+    /**
+     * 注册子 iframe 以参与 read_app / click_element / type_in_app 操作。
+     * iframe 内需已加载 keepworkSDK。
+     */
+    addIframe(iframe: HTMLIFrameElement): void;
+    /** 取消注册子 iframe。 */
+    removeIframe(iframe: HTMLIFrameElement): void;
+    /** 返回所有活跃 iframe（手动注册 + data-ai-hint 自动发现）。 */
+    private _getActiveIframes;
+    private _initMessageListener;
+    private _handleRequest;
+    /** 向子 iframe 的 AppTools 发送请求并等待响应。 */
+    private _queryIframe;
+    /** 清除 ref→element 映射（DOM 重大变化后调用）。 */
+    clearRefs(): void;
+    /**
+     * 执行指定工具函数（CopilotTools 分发入口）。
+     * @param name   - 工具名
+     * @param args   - 工具参数
+     * @param config - 运行时配置（当前未使用，预留扩展）
+     */
+    execute(name: string, args?: Record<string, unknown>, _config?: unknown): Promise<unknown>;
+    private _defaultReadApp;
+    private _passesFilter;
+    private _resolveScope;
+    private _isVisible;
+    private _describeElement;
+    private _getRole;
+    private _getAiHintRole;
+    private _isPressableElement;
+    private _getLabel;
+    private _getElementRefMeta;
+    private _getAriaLabelText;
+    private _getElementText;
+    private _parseRefMetadataFromReadResult;
+    private _getState;
+    private _buildSelector;
+    private _defaultClickElement;
+    private _defaultTypeInApp;
+    private _keyToCode;
+    private _resolveElement;
+    private _resolveStaleRefFallback;
+    private _resolveSelector;
+    private _getTargetHints;
+    private _firstText;
+    private _findByAriaLabel;
+    private _findByText;
+    private _truncate;
+    /**
+     * 发出 `dh:app-page-opened` postMessage 通知 DigitalHuman 页面切换。
+     * DigitalHuman 会根据 pageRouters 配置切换 agent 并发送唤醒文本。
+     * @param page - 页面名称（必须匹配 pageRouters 配置中的某个 key）
+     */
+    static postAppPageOpened(page: string): void;
+}
+export default AppTools;
+//# sourceMappingURL=AppTools.d.ts.map

package/dist-npm/types/src/tools/AppTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppTools.d.ts","sourceRoot":"","sources":["../../../../src/tools/AppTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkDH,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACtF;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3E,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAiBD;;GAEG;AACH,cAAM,QAAQ;IACZ,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,cAAc,EAAE,CA0D3C;IAEF,OAAO,CAAC,GAAG,CAAU;IACrB,OAAO,CAAC,YAAY,CAA+E;IACnG,OAAO,CAAC,kBAAkB,CAAyC;IACnE,OAAO,CAAC,aAAa,CAAsE;IAC3F,OAAO,CAAC,YAAY,CAAsE;IAC1F,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,aAAa,CAAyE;IAC9F,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,WAAW,CAA2C;IAC9D,OAAO,CAAC,UAAU,CAAC,CAA4B;gBAEnC,GAAG,EAAE,OAAO;IAOxB,cAAc,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAC3F,oBAAoB,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAC3D,eAAe,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IACnF,cAAc,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAElF,4DAA4D;IAC5D,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IAIxC,mDAAmD;IACnD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IAIvC,gDAAgD;IAChD,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAWvC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAI1C,oBAAoB;IACpB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAE7C,+CAA+C;IAC/C,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,oBAAoB;YAgBd,cAAc;IAqB5B,sCAAsC;IACtC,OAAO,CAAC,YAAY;IAoBpB,sCAAsC;IACtC,SAAS,IAAI,IAAI;IAIjB;;;;;OAKG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAAE,OAAO,GAAE,OAAY,GAAG,OAAO,CAAC,OAAO,CAAC;YAgC1F,eAAe;IA0D7B,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,kBAAkB;IAK1B,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,+BAA+B;IAWvC,OAAO,CAAC,SAAS;IAkCjB,OAAO,CAAC,cAAc;YA6BR,oBAAoB;YA+CpB,iBAAiB;IA0F/B,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,SAAS;IAQjB;;;;OAIG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAG7C;AAED,eAAe,QAAQ,CAAC"}

package/dist-npm/types/src/tools/ExecuteTool.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ExecuteTool.ts — 在当前浏览器上下文中安全执行任意 JavaScript 的工具
+ *
+ * 以 `AsyncFunction` 动态编译并运行代码，捕获 `console` 输出，
+ * 并通过 `copilot` 代理对象暴露 CopilotTools 的全部工具给代码内部调用。
+ *
+ * LLM 工具定义：`run_app_cmd`
+ */
+/** 工具函数定义（OpenAI Function Calling 格式） */
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** 捕获的 console 日志条目 */
+interface ConsoleLog {
+    level: string;
+    message: string;
+}
+/** execute() 调用配置 */
+export interface ExecuteConfig {
+    /** 关联的 ChatSession（用于访问 sandbox.copilot） */
+    _session?: {
+        sandbox?: {
+            copilot?: Record<string, (...args: unknown[]) => Promise<unknown>>;
+        };
+    };
+    [key: string]: unknown;
+}
+/** SDK 最小接口（避免循环引用） */
+interface SDKRef {
+    copilotTools?: {
+        execute: (toolName: string, params: unknown, config: unknown) => Promise<unknown>;
+    };
+}
+declare class ExecuteTool {
+    /** LLM 可见的工具定义列表 */
+    static readonly definitions: ToolDefinition[];
+    private sdk;
+    private config;
+    constructor(sdk: SDKRef);
+    /** 更新工具运行时配置（由 CopilotTools.setToolConfig 调用）。 */
+    setConfig(config: ExecuteConfig): void;
+    /**
+     * 执行指定工具函数。
+     *
+     * @param name   - 工具名（目前仅支持 'run_app_cmd'）
+     * @param args   - 工具参数
+     * @param config - 运行时配置（含 _session 等）
+     */
+    execute(name: string, args: {
+        command?: string;
+        timeout?: number;
+    } | string[] | unknown, config?: ExecuteConfig): Promise<string>;
+    /**
+     * 在安全沙箱中执行 JavaScript 代码。
+     *
+     * 执行环境：
+     * - `sdk`：KeepworkSDK 实例
+     * - `config`：调用方配置
+     * - `window` / `document`：当前浏览器环境
+     * - `console`：已捕获输出的代理 console
+     * - `copilot`：CopilotTools 的 Proxy，可调用任意已注册工具
+     *
+     * 单行表达式自动加 `return`；多行代码以语句形式执行。
+     *
+     * @param code   - 要执行的 JavaScript 代码字符串
+     * @param config - 运行时配置
+     * @returns 格式化的执行输出（含 console 日志 + 返回值）
+     */
+    runAppCmd(code: string, config?: ExecuteConfig): Promise<string>;
+    /**
+     * 创建 copilot 工具代理对象。
+     * 优先使用 session.sandbox.copilot（已配置完整代理）；
+     * 否则创建一个直接调用 sdk.copilotTools.execute 的 Proxy。
+     *
+     * @param config - 运行时配置
+     */
+    createCopilotProxy(config: ExecuteConfig): Record<string, unknown>;
+    /** 将任意值序列化为字符串（循环引用安全）。 */
+    stringifyValue(value: unknown): string;
+    /** 格式化捕获的 console 日志数组为字符串。 */
+    formatConsoleOutput(logs: ConsoleLog[]): string;
+    /** 组合 console 输出和执行结果为最终字符串。 */
+    formatExecutionOutput(result: unknown, logs: ConsoleLog[]): string;
+    /**
+     * 判断给定代码是否为单行 JS 表达式（可安全加 `return`）。
+     * 任何包含换行、分号或语句关键字的代码视为语句块。
+     */
+    isSingleExpression(code: string): boolean;
+}
+export default ExecuteTool;
+//# sourceMappingURL=ExecuteTool.d.ts.map

package/dist-npm/types/src/tools/ExecuteTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecuteTool.d.ts","sourceRoot":"","sources":["../../../../src/tools/ExecuteTool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED,uBAAuB;AACvB,UAAU,UAAU;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAqB;AACrB,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE;YACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;SACpE,CAAC;KACH,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,uBAAuB;AACvB,UAAU,MAAM;IACd,YAAY,CAAC,EAAE;QACb,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KACnF,CAAC;CACH;AAED,cAAM,WAAW;IACf,oBAAoB;IACpB,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,cAAc,EAAE,CAyB3C;IAEF,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,MAAM,CAAqB;gBAEvB,GAAG,EAAE,MAAM;IAIvB,kDAAkD;IAClD,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAMtC;;;;;;OAMG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE,GAAG,OAAO,EACjE,MAAM,GAAE,aAAkB,GACzB,OAAO,CAAC,MAAM,CAAC;IAelB;;;;;;;;;;;;;;;OAeG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAmD1E;;;;;;OAMG;IACH,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IA2BlE,2BAA2B;IAC3B,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAStC,+BAA+B;IAC/B,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM;IAO/C,gCAAgC;IAChC,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM;IAclE;;;OAGG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAU1C;AAED,eAAe,WAAW,CAAC"}

package/dist-npm/types/src/tools/FileTools.d.ts

@@ -0,0 +1,77 @@
+/**
+ * FileTools.ts — 工作空间文件操作工具（供 CopilotTools 注册为 'read'/'edit'/'search'/'fileOps' 分类）
+ *
+ * 所有文件操作均在 `sdk.personalPageStore` 的工作空间作用域内执行，
+ * 不允许访问主机文件系统。
+ *
+ * 支持的工具函数：
+ * - `read_file`：按行范围读取文件内容（可选 `${...}` 模板展开）
+ * - `list_dir`：列出目录内容
+ * - `replace_string_in_file`：单次字符串替换
+ * - `multi_replace_string_in_file`：批量字符串替换
+ * - `create_file`：创建新文件
+ * - `grep_search`：文本/正则搜索
+ */
+/** 工具函数定义（OpenAI Function Calling 格式） */
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** FileTools 运行时配置 */
+export interface FileToolsConfig {
+    /** 文件路径前缀（所有路径都会被拼接到此前缀下） */
+    pathPrefix?: string;
+    /** 工作空间名称（传递给 personalPageStore.withConfig） */
+    workspace?: string;
+    /** Mounted folder 配置 */
+    mountFolder?: unknown;
+    /** 关联的 ChatSession（用于 processTemplate 展开） */
+    _session?: {
+        sandbox?: {
+            processTemplate?: (content: string) => Promise<string>;
+            _templateSourceFile?: string | null;
+        };
+    };
+    [key: string]: unknown;
+}
+/** PersonalPageStore 作用域实例的最小接口 */
+interface ScopedStore {
+    readFile(pageName: string, startLine?: number, endLine?: number): Promise<string | null>;
+    replaceStringInFile(pageName: string, oldString: string, newString: string): Promise<string>;
+    grepSearch(query: string, isRegexp?: boolean, includePattern?: string, maxResults?: number): Promise<string>;
+    createFile(pageName: string, content?: string): Promise<string>;
+    listDir(path: string, recursive?: boolean): Promise<string>;
+    withConfig(config: Record<string, unknown>): ScopedStore;
+}
+/** SDK 最小接口 */
+interface SDKRef {
+    personalPageStore?: ScopedStore;
+}
+declare class FileTools {
+    static readonly readDefinitions: ToolDefinition[];
+    static readonly editDefinitions: ToolDefinition[];
+    static readonly searchDefinitions: ToolDefinition[];
+    /** 所有工具定义的合并（read + edit + search） */
+    static get definitions(): ToolDefinition[];
+    private sdk;
+    private config;
+    constructor(sdk: SDKRef);
+    /** 更新工具运行时配置（由 CopilotTools.setToolConfig 调用）。 */
+    setConfig(config: FileToolsConfig): void;
+    /**
+     * 执行文件操作工具。
+     * 所有路径经 `pathPrefix` 拼接后传入 `personalPageStore`，
+     * 不会直接操作主机文件系统。
+     *
+     * @param name   - 工具名
+     * @param args   - 工具参数
+     * @param config - 运行时配置（含 workspace / pathPrefix / _session 等）
+     */
+    execute(name: string, args?: Record<string, unknown>, config?: FileToolsConfig): Promise<string>;
+}
+export default FileTools;
+//# sourceMappingURL=FileTools.d.ts.map

package/dist-npm/types/src/tools/FileTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileTools.d.ts","sourceRoot":"","sources":["../../../../src/tools/FileTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACtF;AAED,sBAAsB;AACtB,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE;YACR,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;YACvD,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;SACrC,CAAC;KACH,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,mCAAmC;AACnC,UAAU,WAAW;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzF,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7F,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7G,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5D,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC;CAC1D;AAED,eAAe;AACf,UAAU,MAAM;IACd,iBAAiB,CAAC,EAAE,WAAW,CAAC;CACjC;AASD,cAAM,SAAS;IAGb,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,cAAc,EAAE,CAsC/C;IAEF,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,cAAc,EAAE,CA8D/C;IAEF,MAAM,CAAC,QAAQ,CAAC,iBAAiB,EAAE,cAAc,EAAE,CAkBjD;IAEF,sCAAsC;IACtC,MAAM,KAAK,WAAW,IAAI,cAAc,EAAE,CAEzC;IAID,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,MAAM,CAAuB;gBAEzB,GAAG,EAAE,MAAM;IAIvB,kDAAkD;IAClD,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAMxC;;;;;;;;OAQG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAAC,MAAM,CAAC;CAmHnB;AAED,eAAe,SAAS,CAAC"}