clickgo 6.9.0 → 6.11.0

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

@@ -0,0 +1,7 @@
+import type { IAgentInfo } from '../command';
+/**
+ * --- 只介绍接入入口，实时 App ID 和命令参数由代理通过接口发现 ---
+ * @param info 当前环境的接入信息
+ * @returns 可复制的简短英文 Markdown，不嵌入运行实例快照
+ */
+export declare function format(info: IAgentInfo): string;

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

@@ -0,0 +1,18 @@
+import * as lCommand from '../command';
+/** --- 主进程只发送这四种操作，不接受任意代码或函数名 --- */
+export interface IRequest {
+    'method': 'listTasks' | 'list' | 'execute' | 'cancel';
+    'id': string;
+    'taskId'?: string;
+    'name'?: string;
+    'args'?: Record<string, lCommand.TJson>;
+}
+/**
+ * --- 接收 Native MCP 请求，按目标 taskId 直接读取或执行公开命令 ---
+ * @param request 主进程发来的操作
+ * @returns 共享命令结果或发现列表
+ */
+export declare function invoke(request: IRequest): Promise<lCommand.TResult | {
+    'ok': true;
+    'data': lCommand.IInfo[] | ReturnType<typeof lCommand.listTasks>;
+}>;

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

@@ -0,0 +1,10 @@
+import * as lForm from '../form';
+/**
+ * --- 打开原生命令调试面板，也可作为界面操作型代理的可选入口 ---
+ * @param current 发起操作的 Form，创建阶段使用其原生 Loading
+ * @param options 是否只显示应用允许代理调用的命令，默认显示全部内部命令
+ * @returns 面板关闭后完成；所属实例失效或正在创建时直接返回
+ */
+export declare function showPalette(current: lForm.AbstractForm, options?: {
+    'exposedOnly'?: boolean;
+}): Promise<void>;

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

@@ -0,0 +1,31 @@
+import type { ISchema, TJson } from '../command';
+/**
+ * --- 检查可序列化值，拒绝循环、非有限数和类实例；限制嵌套深度 ---
+ * @param value 待检查值
+ * @param seen 当前路径上的对象
+ * @param depth 当前深度
+ * @returns 是否为合法 JSON
+ */
+export declare function isJson(value: unknown, seen?: Set<object>, depth?: number): value is TJson;
+/**
+ * --- 注册时检查 schema，错误约束不能静默放行 ---
+ * @param schema 当前 schema
+ * @param root 根 schema
+ * @param seen 已检查的节点
+ * @returns 错误说明，合法时返回 null
+ */
+export declare function check(schema: ISchema | boolean, root?: ISchema, seen?: Set<ISchema>): string | null;
+/**
+ * --- 校验数据，不转换类型、不补默认值、不删除额外参数 ---
+ * @param value 待校验数据
+ * @param schema 当前 schema
+ * @param root 根 schema
+ * @param path 错误字段路径
+ * @param depth 递归深度
+ * @param ancestors 当前校验路径上的 schema，防止不推进数据的循环引用
+ * @returns 错误说明，匹配时返回 null
+ */
+export declare function validate(value: TJson, schema: ISchema | boolean, root?: ISchema, path?: string, depth?: number, ancestors?: Array<{
+    'schema': ISchema;
+    'path': string;
+}>): string | null;

package/dist/lib/command.d.ts

@@ -0,0 +1,271 @@
+import * as lCore from './core';
+import * as lNative from './native';
+export { showPalette } from './command/palette';
+/** --- 命令输入与输出可跨浏览器、Native 和协议传输的 JSON 值 --- */
+export type TJson = null | boolean | number | string | TJson[] | {
+    [key: string]: TJson;
+};
+/** --- JSON Schema 2020-12 的命令校验子集；不支持的关键字在注册时拒绝 --- */
+export interface ISchema {
+    '$schema'?: string;
+    '$ref'?: string;
+    '$defs'?: Record<string, ISchema | boolean>;
+    'title'?: string;
+    'description'?: string;
+    'default'?: TJson;
+    'examples'?: TJson[];
+    'type'?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+    'properties'?: Record<string, ISchema | boolean>;
+    'required'?: string[];
+    'additionalProperties'?: ISchema | boolean;
+    'items'?: ISchema | boolean;
+    'minItems'?: number;
+    'maxItems'?: number;
+    'uniqueItems'?: boolean;
+    'minLength'?: number;
+    'maxLength'?: number;
+    'pattern'?: string;
+    'minimum'?: number;
+    'maximum'?: number;
+    'exclusiveMinimum'?: number;
+    'exclusiveMaximum'?: number;
+    'enum'?: TJson[];
+    'const'?: TJson;
+    'allOf'?: Array<ISchema | boolean>;
+    'anyOf'?: Array<ISchema | boolean>;
+    'oneOf'?: Array<ISchema | boolean>;
+    'not'?: ISchema | boolean;
+}
+/** --- 所有入口共用的结果；错误码用于程序判断，message 用于说明 --- */
+export type TResult<T extends TJson = TJson> = {
+    'ok': true;
+    'data': T;
+} | {
+    'ok': false;
+    'error': {
+        'code': string;
+        'message': string;
+    };
+};
+/** --- 执行来源仅用于展示与记录，不是授权凭证 --- */
+export interface IContext {
+    'taskId': string;
+    'formId': string;
+    'panelId': string;
+    'source': 'user' | 'agent';
+    'signal': AbortSignal;
+}
+/** --- 与 MCP 工具描述对齐的公开命令元数据 --- */
+export interface IMetadata {
+    'name': string;
+    'title'?: string;
+    'description': string;
+    'inputSchema': ISchema & {
+        'type': 'object';
+    };
+    'outputSchema'?: ISchema;
+    /** --- 行为说明，不代替校验或授权 --- */
+    'annotations'?: {
+        'readOnlyHint'?: boolean;
+        'destructiveHint'?: boolean;
+        'idempotentHint'?: boolean;
+        'openWorldHint'?: boolean;
+        /** --- WebMCP 的重要或不可逆现实效果说明 --- */
+        'consequentialHint'?: boolean;
+        'untrustedContentHint'?: boolean;
+    };
+}
+/** --- 应用声明一次，界面、浏览器代理和 Native 适配器共享执行函数 --- */
+export interface IDefinition<T extends Record<string, TJson> = Record<string, TJson>> extends IMetadata {
+    /** --- 明确允许代理发现并调用；默认只允许应用内部调用 --- */
+    'exposed'?: boolean;
+    /** --- 默认拒绝同一命令并发；业务确认可并行时才开启 --- */
+    'concurrent'?: boolean;
+    /** --- 必须已经取得的框架权限；执行入口不弹授权窗 --- */
+    'permissions'?: string[];
+    /** --- true 为可用，false 或原因文本为不可用；每次执行重新检查 --- */
+    'enabled'?: () => boolean | string;
+    'execute': (args: T, context: IContext) => TResult | Promise<TResult>;
+}
+/** --- 不包含函数或内部对象的独立快照 --- */
+export interface IInfo extends IMetadata {
+    'taskId': string;
+    'formId': string;
+    'panelId': string;
+    'exposed': boolean;
+    'enabled': boolean;
+    'disabledReason': string;
+    'running': number;
+}
+/** --- 绑定一个应用实例，只能调用该实例明确公开的命令 --- */
+export interface IBridge {
+    'taskId': string;
+    'list': () => IInfo[];
+    'execute': (name: string, args?: Record<string, TJson>, options?: {
+        'signal'?: AbortSignal;
+    }) => Promise<TResult>;
+}
+/** --- 框架向网页发布的统一入口；按任务选择应用，只访问明确公开的命令 --- */
+export interface IPageBridge {
+    'getAgentInfo': (taskId?: string) => Promise<IAgentInfo | null | false>;
+    'getAgentGuide': (taskId?: string) => Promise<string | null | false>;
+    'listTasks': () => Array<{
+        'id': string;
+        'name': string;
+    }>;
+    'list': (taskId: string) => IInfo[];
+    'execute': (taskId: string, name: string, args?: Record<string, TJson>, options?: {
+        'signal'?: AbortSignal;
+    }) => Promise<TResult>;
+}
+/** --- 统一接入说明的生成选项；默认不读取或包含 HTTP 凭据 --- */
+export interface IAgentOptions {
+    /** --- 仅供应用主动导出 HTTP 连接设置，仍要求当前 App 已有 root 权限 --- */
+    'includeMcpCredentials'?: boolean;
+}
+/** --- 页面级 WebMCP 接入状态；ready 表示浏览器接口可用，不表示某个 App 的工具已发布 --- */
+export type TWebMcpStatus = 'unsupported' | 'ready';
+/** --- 工具发布诊断状态，不参与页面级接入事件 --- */
+export type TWebMcpRegistrationStatus = 'idle' | 'registering' | 'ready' | 'failed';
+/** --- 可展示或导出的接入信息；命令列表始终从对应入口实时查询 --- */
+export interface IAgentInfo {
+    'schemaVersion': 1;
+    'apps': ReturnType<typeof listTasks>;
+    'targetTaskId': string | null;
+    'browser': {
+        'url': string | null;
+        'api': string;
+    };
+    'webMcp': {
+        'supported': boolean;
+        /** --- 全页面共用的浏览器接入状态，不受目标 App 或工具数量影响 --- */
+        'status': TWebMcpStatus;
+        /** --- 所选 App 的发布诊断；多个 App 时优先报告失败及进行中的注册，不支持时为 null --- */
+        'registrationStatus': TWebMcpRegistrationStatus | null;
+        /** --- 已完成工具发布的 App，不表示这些 App 分别建立了浏览器连接 --- */
+        'publishedTaskIds': string[];
+    };
+    'native': lNative.ICommandEntry | null;
+    /** --- 只有显式导出且通过 root 检查时才包含 HTTP 凭据 --- */
+    'http': lNative.IMcpInfo | null;
+}
+/**
+ * --- 初始化页面级 WebMCP 接入状态，由框架在执行 Boot.main 前自动调用 ---
+ * @returns 无返回值
+ */
+export declare function init(): void;
+/**
+ * --- 构造成功结果 ---
+ * @param data 可跨入口传输的 JSON 数据
+ * @returns 成功结果
+ */
+export declare function success<T extends TJson>(data: T): TResult<T>;
+/**
+ * --- 构造业务失败结果，不抛异常 ---
+ * @param code 稳定的业务错误码
+ * @param message 可公开的错误说明
+ * @returns 失败结果
+ */
+export declare function failure(code: string, message: string): TResult<never>;
+/**
+ * --- 注册命令；重复名称、不支持的 schema 或已销毁的实例返回 false ---
+ * @param current 所属任务/Form/Panel；销毁时自动移除其命令
+ * @param definition 元数据、可用条件与唯一业务执行函数
+ * @returns 是否注册成功
+ */
+export declare function register<T extends Record<string, TJson>>(current: lCore.TCurrent, definition: IDefinition<T>): boolean;
+/**
+ * --- 取消尚在执行的命令并解除注册；取消是协作式，不回滚已产生的业务效果 ---
+ * @param current 所属任务/Form/Panel
+ * @param name 命令名称
+ * @returns 是否找到并移除命令
+ */
+export declare function unregister(current: lCore.TCurrent, name: string): boolean;
+/**
+ * --- 清理所属 Panel、Form 或整个任务的命令 ---
+ * @param current 所属任务/Form/Panel
+ * @returns 无返回值
+ */
+export declare function clear(current: lCore.TCurrent): void;
+/**
+ * --- 框架生命周期使用的按所属范围清理入口 ---
+ * @internal
+ * @param taskId 所属任务
+ * @param formId 所属 Form，不传时清理任务
+ * @param panelId 所属 Panel，不传时清理整个 Form
+ * @returns 无返回值
+ */
+export declare function clearOwner(taskId: string, formId?: string, panelId?: string): void;
+/**
+ * --- 获取独立元数据和当前状态，不导出业务函数 ---
+ * @param current 所属应用
+ * @returns 命令列表
+ */
+export declare function list(current: lCore.TCurrent): IInfo[];
+/**
+ * --- 获取仍可调用的 App 标识与名称，供网页及 Native 代理发现目标 ---
+ * @returns 未开始退出的 App 列表
+ */
+export declare function listTasks(): Array<{
+    'id': string;
+    'name': string;
+}>;
+/**
+ * --- 获取当前环境的统一接入信息，不另行维护命令清单或启用服务 ---
+ * @param current 限定目标 App；省略时由代理发现并选择 App
+ * @param options 是否主动导出 HTTP 连接凭据，默认不包含
+ * @returns 独立信息；目标已退出为 null，无权限导出凭据为 false
+ */
+export declare function getAgentInfo(current?: lCore.TCurrent, options?: IAgentOptions): Promise<IAgentInfo | null | false>;
+/**
+ * --- 生成简短英文接入说明，不嵌入临时 App ID；代理通过接口实时发现 ---
+ * @param current 校验当前 App 生命周期与凭据导出权限；省略时生成页面通用说明
+ * @param options 是否主动导出 HTTP 连接凭据，默认不包含
+ * @returns Markdown 说明；目标已退出为 null，无权限导出凭据为 false
+ */
+export declare function getAgentGuide(current?: lCore.TCurrent, options?: IAgentOptions): Promise<string | null | false>;
+/**
+ * --- 应用界面直接执行已注册的业务命令 ---
+ * @param current 所属任务/Form
+ * @param name 命令名称
+ * @param args 参数，默认空对象
+ * @param options 取消信号
+ * @returns 业务结果
+ */
+export declare function execute(current: lCore.TCurrent, name: string, args?: Record<string, TJson>, options?: {
+    'signal'?: AbortSignal;
+}): Promise<TResult>;
+/**
+ * --- 代理直接按 taskId 执行公开命令，与界面共用校验和业务执行器 ---
+ * @param taskId 目标 App
+ * @param name 命令名称
+ * @param args 参数，默认空对象
+ * @param options 取消信号
+ * @returns 结构化结果；未公开或不存在的命令返回 not-found
+ */
+export declare function executeAgent(taskId: string, name: string, args?: Record<string, TJson>, options?: {
+    'signal'?: AbortSignal;
+}): Promise<TResult>;
+/**
+ * --- 创建绑定单个 App 的可复用代理接口，调用方无需反复传入 taskId ---
+ * @param current 所属应用
+ * @returns 不可修改的桥接接口
+ */
+export declare function createBridge(current: lCore.TCurrent): IBridge;
+/**
+ * --- 网页入口直接读取框架的任务及命令状态，无需应用或宿主重复发布与清理 ---
+ * @returns 不可修改的网页命令接口
+ */
+export declare function createPageBridge(): IPageBridge;
+/**
+ * --- 显式重同步或重试当前 App 的工具发布；页面接入由框架自动管理 ---
+ * @param current 所属应用
+ * @returns 是否同步成功；浏览器不支持、App 已退出或注册失败时返回 false
+ */
+export declare function connectWebMcp(current: lCore.TCurrent): Promise<boolean>;
+/**
+ * --- 撤销当前 App 的 WebMCP 工具；不改变页面级接入状态，下次公开命令注册时自动发布 ---
+ * @param current 所属应用
+ * @returns 无返回值
+ */
+export declare function disconnectWebMcp(current: lCore.TCurrent): void;

package/dist/lib/core.d.ts

@@ -18,6 +18,7 @@ import * as mpegts from 'mpegts.js';
 import * as clickgo from '../clickgo';
 import * as lForm from './form';
 import * as lControl from './control';
+import type * as lCommand from './command';
 import * as lCore from './core';
 /**
  * --- 初始化系统级 ID，仅能设置一次 ---
@@ -107,6 +108,12 @@ export declare abstract class AbstractApp {
     onTaskStarted(taskId: string): void | Promise<void>;
     /** --- 任务结束事件 --- */
     onTaskEnded(taskId: string): void | Promise<void>;
+    /**
+     * --- 页面级 WebMCP 接入状态变化，所有 App 共用同一状态 ---
+     * @param status 浏览器接入状态，与 command.getAgentInfo 的 webMcp.status 一致
+     * @returns 无返回值
+     */
+    onWebMcpStatusChanged(status: lCommand.TWebMcpStatus): void | Promise<void>;
     /**
      * --- Launcher 显示状态改变事件 ---
      * @param state 是否显示
@@ -244,7 +251,7 @@ export interface IAvailArea {
     'oheight': number;
 }
 /** --- 全局事件类型 --- */
-export type TGlobalEvent = 'trayCreated' | 'trayChanged' | 'trayRemoved' | 'error' | 'screenResize' | 'configChanged' | 'formCreated' | 'formRemoved' | 'formTitleChanged' | 'formIconChanged' | 'formStateMinChanged' | 'formStateMaxChanged' | 'formShowChanged' | 'formFocused' | 'formBlurred' | 'formFlash' | 'formShowInSystemTaskChange' | 'formHashChange' | 'taskStarted' | 'taskEnded' | 'launcherShowChanged' | 'launcherFolderNameChanged' | 'hashChanged' | 'keydown' | 'keyup';
+export type TGlobalEvent = 'trayCreated' | 'trayChanged' | 'trayRemoved' | 'error' | 'screenResize' | 'configChanged' | 'formCreated' | 'formRemoved' | 'formTitleChanged' | 'formIconChanged' | 'formStateMinChanged' | 'formStateMaxChanged' | 'formShowChanged' | 'formFocused' | 'formBlurred' | 'formFlash' | 'formShowInSystemTaskChange' | 'formHashChange' | 'taskStarted' | 'taskEnded' | 'webMcpStatusChanged' | 'launcherShowChanged' | 'launcherFolderNameChanged' | 'hashChanged' | 'keydown' | 'keyup';
 /** --- 现场下载 app 的参数 --- */
 export interface ICoreFetchAppOptions {
     'notify'?: number | {

package/dist/lib/form.d.ts

@@ -1,4 +1,5 @@
 import * as lCore from './core';
+import * as lCommand from './command';
 import * as lDom from './dom';
 import * as lControl from './control';
 /**
@@ -324,6 +325,12 @@ export declare abstract class AbstractForm extends AbstractCommon {
     onTaskStarted(taskId: string): void | Promise<void>;
     /** --- 任务结束事件 --- */
     onTaskEnded(taskId: string): void | Promise<void>;
+    /**
+     * --- 页面级 WebMCP 接入状态变化，所有 Form 共用同一状态 ---
+     * @param status 浏览器接入状态，与 command.getAgentInfo 的 webMcp.status 一致
+     * @returns 无返回值
+     */
+    onWebMcpStatusChanged(status: lCommand.TWebMcpStatus): void | Promise<void>;
     /**
      * --- Launcher 显示状态改变事件 ---
      * @param state 是否显示

package/dist/lib/native.d.ts

@@ -4,6 +4,35 @@ import * as lCore from './core';
  * @param id 系统级 ID
  */
 export declare function initSysId(id: string): void;
+/** --- 本地 MCP 客户端连接设置；仅向已授权 root 的 App 提供 --- */
+export interface IMcpInfo {
+    'transport': 'streamable-http';
+    'url': string;
+    'token': string;
+}
+/** --- 当前 Native 的公开进程入口，不包含 HTTP 连接凭据 --- */
+export interface ICommandEntry {
+    'name': string;
+    'platform': string;
+    'command': string;
+    'args': string[];
+    'startup': 'existing' | 'auto';
+    'mcp': {
+        'enabled': boolean;
+        'discovery': boolean;
+    };
+}
+/**
+ * --- 取得软件自身的 CLI/stdio 入口和启动要求，无需读取连接凭据 ---
+ * @returns 公开入口信息；普通网页或尚未支持此接口的宿主为 null
+ */
+export declare function getCommandEntry(): Promise<ICommandEntry | null>;
+/**
+ * --- 读取 Native 主进程启用的 MCP 连接设置 ---
+ * @param current 当前 App
+ * @returns 连接设置；未启用为 null，无权限为 false
+ */
+export declare function getMcpInfo(current: lCore.TCurrent): Promise<IMcpInfo | null | false>;
 /**
  * --- 监听 native 传输过来的事件 ---
  * @param current 当前任务 ID

package/dist/lib/task.d.ts

@@ -260,6 +260,8 @@ export interface IThread {
 }
 /** --- 运行中的任务对象 --- */
 export interface ITask {
+    /** --- 已开始退出；框架释放异步资源期间拒绝新命令 --- */
+    'ending'?: boolean;
     'id': string;
     'app': lCore.IApp;
     'class': lCore.AbstractApp;