clickgo 6.11.0 → 7.0.0

package/dist/lib/command/data.d.ts

@@ -0,0 +1,27 @@
+import type { IDefinition, IMetadata, ISchema, TJson, TResult } from '../command';
+/**
+ * --- 检查命令定义的字段、支持的 schema 和 JSON 元数据，并保存独立快照 ---
+ * @param definition 命令定义；名称为 1–128 位 ASCII 字母、数字、_、.、-，说明不能为空白
+ * @returns 元数据快照；字段、回调类型、权限列表、注解或 schema 不合法返回 false；不检查授权或所属实例
+ */
+export declare function readMetadata<T extends Record<string, TJson>>(definition: IDefinition<T>): IMetadata | false;
+/**
+ * --- 按命令的输入 schema 校验 JSON 对象，并隔离调用方后续修改 ---
+ * @param args 输入数据，不转换类型、不补默认值、不删除额外字段
+ * @param schema 注册时已验证的输入 schema
+ * @returns 成功时 data 为独立参数；非 JSON 对象或约束不匹配返回 invalid-input
+ */
+export declare function readInput(args: unknown, schema: ISchema): TResult<Record<string, TJson>>;
+/**
+ * --- 检查业务结果的 JSON 结构及输出约束，生成可跨入口传输的独立结果 ---
+ * @param result 业务回调结果；成功须有 data，失败须有非空错误码和字符串说明
+ * @param schema 可选输出 schema，只校验成功结果的 data
+ * @returns 合法业务错误保留 code/message；成功数据复制；结构或约束不匹配返回 invalid-output
+ */
+export declare function readResult(result: unknown, schema?: ISchema): TResult;
+/**
+ * --- 复制已验证的 JSON，保持 JSON 往返语义，不与注册表共享对象 ---
+ * @param value 已通过 JSON 检查的元数据或业务数据
+ * @returns 独立快照
+ */
+export declare function copy<T>(value: T): T;

package/dist/lib/command/webmcp.d.ts

@@ -0,0 +1,84 @@
+import type { IMetadata, ISchema, TJson, TResult, TWebMcpRegistrationStatus } from '../command';
+/** --- 浏览器发布所需的命令身份与元数据，不持有业务执行函数 --- */
+export interface ICommand {
+    /** --- 每次注册使用不同标识，旧工具不能转向同名的新命令 --- */
+    'id': number;
+    'metadata': IMetadata;
+}
+/** --- 浏览器提供的工具注册能力；撤销信号只作用于本次工具发布 --- */
+export interface IContext {
+    'registerTool': (tool: {
+        'name': string;
+        'description': string;
+        'inputSchema': ISchema;
+        'execute': (args: Record<string, TJson>, options?: {
+            'signal'?: AbortSignal;
+        }) => Promise<string>;
+        'annotations'?: {
+            'readOnlyHint'?: boolean;
+            'consequentialHint'?: boolean;
+            'untrustedContentHint'?: boolean;
+        };
+    }, options: {
+        'signal': AbortSignal;
+    }) => void | Promise<void>;
+}
+/** --- 灰箱提供的命令选择、注册身份判断和统一执行入口 --- */
+export interface IRuntime<T extends ICommand> {
+    /** --- 当前允许代理发现的命令，由调用方按 exposed 筛选 --- */
+    'getCommands': (taskId: string) => T[];
+    /** --- 当前注册表仍持有同一个命令实例；不能只比较名称 --- */
+    'isCurrent': (taskId: string, command: T) => boolean;
+    /** --- 使用灰箱 executeAgent，重新检查权限、可用性、并发和取消 --- */
+    'execute': (taskId: string, command: T, args: Record<string, TJson>, options?: {
+        'signal'?: AbortSignal;
+    }) => Promise<TResult>;
+}
+/** --- 单个 App 的发布记录，与页面接入状态分开 --- */
+export interface IPublication<T extends ICommand> {
+    'context': IContext;
+    'tools': Map<T, AbortController>;
+    /** --- 最新一次串行同步的结果；撤销或注册失败为 false --- */
+    'pending': Promise<boolean>;
+    'status': TWebMcpRegistrationStatus;
+}
+/** --- 所选 App 的发布诊断；不触发注册，不读取其他 App --- */
+export interface IDiagnostics {
+    /** --- 失败优先于进行中，其余按已发布或空闲报告 --- */
+    'registrationStatus': TWebMcpRegistrationStatus;
+    'publishedTaskIds': string[];
+}
+/** --- 按 App 隔离并串行同步工具，撤销后拒绝迟到注册及旧工具调用 --- */
+export interface IPublisher<T extends ICommand> {
+    /**
+     * --- 发布或重同步；浏览器接口改变时先撤销旧发布 ---
+     * @param taskId 灰箱已确认仍存活的 App
+     * @param context 当前浏览器注册能力
+     * @returns 发布记录，pending 表示本轮同步是否成功
+     */
+    'publish': (taskId: string, context: IContext) => IPublication<T>;
+    /**
+     * --- 按注册表最新内容排队同步，失败工具可重试 ---
+     * @param taskId 所属 App
+     * @returns 无返回值；未发布过的 App 不处理
+     */
+    'refresh': (taskId: string) => void;
+    /**
+     * --- 撤销 App 工具及待完成发布，不改变页面级接入状态 ---
+     * @param taskId 所属 App
+     * @returns 无返回值
+     */
+    'disconnect': (taskId: string) => void;
+    /**
+     * --- 汇总所选 App 的工具发布状态 ---
+     * @param taskIds 所选 App 标识
+     * @returns 发布诊断
+     */
+    'describe': (taskIds: string[]) => IDiagnostics;
+}
+/**
+ * --- 创建浏览器发布器，内部组织同步队列、撤销信号和迟到结果处理 ---
+ * @param runtime 灰箱提供的公开命令选择、身份校验和执行能力
+ * @returns 独立发布器；不持有页面状态或决定业务授权
+ */
+export declare function create<T extends ICommand>(runtime: IRuntime<T>): IPublisher<T>;

package/dist/lib/command.d.ts

@@ -1,10 +1,9 @@
 import * as lCore from './core';
+import * as lTool from './tool';
 import * as lNative from './native';
 export { showPalette } from './command/palette';
 /** --- 命令输入与输出可跨浏览器、Native 和协议传输的 JSON 值 --- */
-export type TJson = null | boolean | number | string | TJson[] | {
-    [key: string]: TJson;
-};
+export type TJson = lTool.TJson;
 /** --- JSON Schema 2020-12 的命令校验子集；不支持的关键字在注册时拒绝 --- */
 export interface ISchema {
     '$schema'?: string;

package/dist/lib/core/package.d.ts

@@ -0,0 +1,23 @@
+import * as lZip from '../zip.js';
+import * as lTool from '../tool.js';
+import type { IAppPackage } from '../core.js';
+/** --- CGA 读取器所需的框架能力，供黑箱调用 --- */
+export interface IPackageIO {
+    /** --- 打开已解密的 ZIP 内容块，供读取器访问文件；失败返回 null --- */
+    'getZip': typeof lZip.get;
+    /** --- 将包内图标 Blob 转为可展示的 data URL --- */
+    'blob2DataUrl': typeof lTool.blob2DataUrl;
+    /** --- 按包内路径识别 MIME 类型，用于构造二进制文件 Blob --- */
+    'getMimeByPath': typeof lTool.getMimeByPath;
+}
+/**
+ * --- 校验 CGA 应用包并创建按需读取器，统一接入框架的 ZIP、图标和文件类型能力 ---
+ * @param blob CGA 应用包的二进制内容
+ * @returns 图标 data URL 和包读取器；包格式、认证或图标读取失败返回 false
+ */
+export declare function createPackage(blob: Blob): Promise<false | {
+    /** --- 无内嵌图标时为空字符串 --- */
+    'icon': string;
+    /** --- 按需读取文件，读取失败按 IAppPackage 契约返回 null --- */
+    'package': IAppPackage;
+}>;

package/dist/lib/core.d.ts

@@ -135,8 +135,9 @@ export declare function setBoot(b: clickgo.AbstractBoot): void;
  */
 export declare function trigger(name: TGlobalEvent, taskId?: string | boolean | KeyboardEvent, formId?: string | boolean | Record<string, any> | null, param1?: boolean | Error | string, param2?: string | Record<string, any>, param3?: boolean): Promise<void>;
 /**
- * --- cga blob 文件解包 ---
- * @param blob blob 对象
+ * --- 读取 CGA 应用包及其配置 ---
+ * @param blob CGA 应用包的二进制内容
+ * @returns 应用信息；包无法识别或缺少文本配置时返回 false
  */
 export declare function readApp(blob: Blob): Promise<false | IApp>;
 /**
@@ -303,6 +304,11 @@ export interface IAppPackage {
 }
 /** --- 应用文件包 config --- */
 export interface IAppConfig {
+    /**
+     * --- 固定应用 ID，如 net.example.notepad；Native 持久存储必填，跨位置和版本保持不变 ---
+     * 1-128 位字母、数字、点、下划线或连字符，以字母或数字开头。
+     */
+    'id'?: string;
     /** --- 应用名 --- */
     'name': string;
     /** --- 发行版本 --- */

package/dist/lib/dom.d.ts

@@ -199,8 +199,14 @@ export declare function isWatch(el: HTMLElement): boolean;
  * @param taskId 任务 id
  */
 export declare function clearWatch(taskId: lCore.TCurrent): void;
-/** --- 样式变化通知回调 --- */
-type TWatchStyleCallback = (name: string, value: string, old: string) => void | Promise<void>;
+/**
+ * --- 样式变化通知回调 ---
+ * @param name CSS 属性名
+ * @param value 当前计算样式值
+ * @param old 上次记录的计算样式值
+ * @returns 无返回值，可异步完成
+ */
+export type TWatchStyleCallback = (name: string, value: string, old: string) => void | Promise<void>;
 /**
  * --- 监听一个标签的计算后样式的变化 ---
  * @param el 对象
@@ -447,4 +453,3 @@ export interface IGetWatchInfoResult {
         };
     }>>;
 }
-export {};

package/dist/lib/native/secret.d.ts

@@ -0,0 +1,29 @@
+import type * as lCore from '../core';
+/**
+ * --- 查询 Native 系统密钥服务，无需 root 权限 ---
+ * @param current 当前 App
+ * @returns 是否可以安全保存敏感字符串
+ */
+export declare function isAvailable(current: lCore.TCurrent): Promise<boolean>;
+/**
+ * --- 读取当前 App 的加密字符串，按 config.id 隔离 ---
+ * @param current 当前 App
+ * @param key 非空 Unicode 存储键，最多 128 个 UTF-16 码元
+ * @returns 字符串，未找到为 null，缺少有效 App ID、宿主、密钥服务或读取失败为 false
+ */
+export declare function get(current: lCore.TCurrent, key: string): Promise<string | null | false>;
+/**
+ * --- 加密后保存字符串，按 config.id 隔离，不退回明文 ---
+ * @param current 当前 App
+ * @param key 非空 Unicode 存储键，最多 128 个 UTF-16 码元
+ * @param value 敏感字符串
+ * @returns 是否保存成功，安全存储不可用为 false
+ */
+export declare function set(current: lCore.TCurrent, key: string, value: string): Promise<boolean>;
+/**
+ * --- 删除加密记录，按 config.id 隔离 ---
+ * @param current 当前 App
+ * @param key 非空 Unicode 存储键，最多 128 个 UTF-16 码元
+ * @returns 是否删除成功，未找到时也返回成功
+ */
+export declare function remove(current: lCore.TCurrent, key: string): Promise<boolean>;

package/dist/lib/native/storage.d.ts

@@ -0,0 +1,30 @@
+import type * as lCore from '../core';
+import type * as lTool from '../tool';
+/** --- 小型配置允许保存的 JSON 数据 --- */
+export type TJson = lTool.TJson;
+/** --- 包装实际值，false/null 数据不会与失败/未找到混淆 --- */
+export interface IStoredValue<T extends TJson = TJson> {
+    'value': T;
+}
+/**
+ * --- 读取当前 App 的持久配置，按 config.id 隔离 ---
+ * @param current 当前 App
+ * @param key 非空 Unicode 存储键，最多 128 个 UTF-16 码元
+ * @returns JSON 值包装；未找到为 null，缺少有效 App ID、宿主或读取失败为 false
+ */
+export declare function get<T extends TJson = TJson>(current: lCore.TCurrent, key: string): Promise<IStoredValue<T> | null | false>;
+/**
+ * --- 保存当前 App 的持久配置，按 config.id 隔离 ---
+ * @param current 当前 App
+ * @param key 非空 Unicode 存储键，最多 128 个 UTF-16 码元
+ * @param value JSON 配置值，完整记录最大 1 MiB
+ * @returns 是否保存成功，普通网页或不支持此接口的宿主为 false
+ */
+export declare function set(current: lCore.TCurrent, key: string, value: TJson): Promise<boolean>;
+/**
+ * --- 删除当前 App 的持久配置，按 config.id 隔离 ---
+ * @param current 当前 App
+ * @param key 非空 Unicode 存储键，最多 128 个 UTF-16 码元
+ * @returns 是否删除成功，未找到时也返回成功
+ */
+export declare function remove(current: lCore.TCurrent, key: string): Promise<boolean>;

package/dist/lib/native.d.ts

@@ -1,4 +1,7 @@
 import * as lCore from './core';
+import type * as lNativeStorage from './native/storage';
+export * as storage from './native/storage';
+export * as secret from './native/secret';
 /**
  * --- 初始化系统级 ID，仅能设置一次 ---
  * @param id 系统级 ID
@@ -33,6 +36,18 @@ export declare function getCommandEntry(): Promise<ICommandEntry | null>;
  * @returns 连接设置；未启用为 null，无权限为 false
  */
 export declare function getMcpInfo(current: lCore.TCurrent): Promise<IMcpInfo | null | false>;
+/**
+ * --- 按当前 App 的固定 ID 访问独立的持久存储，无需 root 权限 ---
+ * @internal
+ * @hidden
+ * @param current 当前 App
+ * @param area 普通配置或敏感数据
+ * @param action 存储操作
+ * @param key 稳定存储键
+ * @param value 待存储值
+ * @returns 主进程结果；缺少有效 App ID、App 已退出、宿主不支持或通讯失败为 false
+ */
+export declare function callPersistence(current: lCore.TCurrent, area: 'storage' | 'secret', action: 'get' | 'set' | 'remove' | 'isAvailable', key?: string, value?: lNativeStorage.TJson): Promise<lNativeStorage.IStoredValue | string | boolean | null>;
 /**
  * --- 监听 native 传输过来的事件 ---
  * @param current 当前任务 ID

package/dist/lib/task.d.ts

@@ -263,6 +263,8 @@ export interface ITask {
     /** --- 已开始退出；框架释放异步资源期间拒绝新命令 --- */
     'ending'?: boolean;
     'id': string;
+    /** --- 启动时确定的固定 App ID，与运行实例 ID 和加载路径无关 --- */
+    readonly 'appId'?: string;
     'app': lCore.IApp;
     'class': lCore.AbstractApp;
     'customTheme': boolean;

package/dist/lib/tool.d.ts

@@ -430,11 +430,11 @@ export declare enum ESTATE {
     'COMMENT' = 4
 }
 /**
- * --- 状态机 ---
- * @param code 代码
- * @param start 开始位置
- * @param process 处理函数
- * @returns 是否继续
+ * --- 源码分段状态机，单词按 ASCII 字母、数字、_ 和 $ 识别 ---
+ * @param code 待扫描源码，CRLF 和 CR 统一为 LF
+ * @param start 归一化后的起始 UTF-16 索引
+ * @param process 片段回调，true 继续、false 停止；位置含首尾，bracket 是共享计数对象
+ * @returns 无返回值
  */
 export declare function stateMachine(code: string, start: number, process: (event: {
     'state': ESTATE;
@@ -497,6 +497,12 @@ export declare function loadAssets(urls: string[], opt?: {
  * @param style css 字符串
  */
 export declare function loadStyle(style: string): void;
+/**
+ * --- 判断 JS 值是否符合 JSON 数据约束；字符串按数据值接受，不解析其内容 ---
+ * @param value 待检查值；仅接受 null、布尔值、有限数、字符串、连续且无额外属性的数组和普通对象
+ * @returns 符合约束返回 true；循环、访问器、Symbol/非枚举属性或深度超过 64（根为 0）返回 false
+ */
+export declare function isJson(value: unknown): value is TJson;
 /**
  * --- 判断一个值是否是虚假的（为 null/undefined/空字符串/false/0） ---
  * @param val 要判断的值
@@ -570,5 +576,9 @@ export interface IRequestOptions {
     'load'?: (res: any) => void | Promise<void>;
     'error'?: () => void | Promise<void>;
 }
+/** --- JSON 数据值，不包含 undefined、BigInt、函数和非有限数 --- */
+export type TJson = null | boolean | number | string | TJson[] | {
+    [key: string]: TJson;
+};
 /** --- 虚假值类型 --- */
 export type TFalsy = false | '' | 0 | null | undefined | typeof NaN;