@icen.ai/ui 0.5.0 → 0.8.0

package/dist/behaviors/ai-tools.d.mts

@@ -0,0 +1,81 @@
+/** 一个 UI 工具：模型可调用的可视化/交互能力 */
+interface AiToolDef<TInput = unknown> {
+    /** 工具名（模型侧 function name；建议 snake_case） */
+    name: string;
+    /** 给模型看的一段说明（何时用、返回什么） */
+    description: string;
+    /** 输入 JSON Schema（OpenAI function.parameters / MCP inputSchema 兼容） */
+    inputSchema: Record<string, unknown>;
+    /** 执行：input → 在 mount 上渲染；返回值作为工具结果（进回执/审计） */
+    run: (input: TInput, mount: HTMLElement) => unknown;
+    /** 结果呈现：'mount'（默认，渲染即呈现）/ 'data'（run 返回值为准，不占挂载位） */
+    present?: 'mount' | 'data';
+}
+interface AiToolRecord {
+    def: AiToolDef;
+    /** 挂载元素（present='mount' 时有值） */
+    el?: HTMLElement;
+    /** render_chart 等返回的句柄（可 update/destroy） */
+    handle?: unknown;
+    ts: number;
+    input: unknown;
+    result: unknown;
+}
+/** 注册（或覆盖同名）一个工具；第三方扩展入口 */
+declare function registerAiTool(def: AiToolDef): void;
+/** 全局下架一个工具（所有区域随即不可再调用它） */
+declare function unregisterAiTool(name: string): void;
+declare function getAiTool(name: string): AiToolDef | undefined;
+declare function listAiTools(): AiToolDef[];
+interface AiToolAreaOptions {
+    /** 工具白名单（精确名或 'chart-*' 通配；缺省 = 全部已注册工具） */
+    tools?: string[];
+    /** 最多同时挂载数（超出 LRU 淘汰最旧；缺省不限） */
+    max?: number;
+    /** 挂载项的最小高度提示（px，默认 240） */
+    itemMinHeight?: number;
+}
+interface AiToolArea {
+    el: HTMLElement;
+    /** 当前挂载数 */
+    readonly count: number;
+    /** 调用一个工具（模型 tool_call 的落地入口）：白名单外或未注册返回 null */
+    call(name: string, input: unknown): AiToolRecord | null;
+    /** 白名单内且未注册？ */
+    can(name: string): boolean;
+    /** 运行时改白名单 / 上限 */
+    setTools(tools: string[] | undefined): void;
+    setMax(max: number | undefined): void;
+    /** 清空全部挂载 */
+    clear(): void;
+    /** 挂载变化回调（call/evict/clear 后触发） */
+    onChange(fn: (records: AiToolRecord[]) => void): () => void;
+}
+/**
+ * 创建 AI 工具挂载区：宿主声明「这块区域归 AI 用」——可白名单工具、限数量
+ * （LRU 淘汰）。每次 call 渲染为一个 .ai-tools-item 卡（标题行 = 工具名 +
+ * 时间 + 移除钮，体 = 工具自己的渲染）。事件 icen:ai-tool-call / -result /
+ * -evict（bubbles），area 上也可原生 addEventListener。
+ */
+declare function createAiToolArea(el: HTMLElement, opts?: AiToolAreaOptions): AiToolArea;
+/** 导出为 OpenAI chat.completions tools 参数格式（可传 names / 通配过滤） */
+declare function aiToolsToOpenAI(names?: string[]): Array<{
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}>;
+/** 导出为 MCP tools 格式（name / description / inputSchema） */
+declare function aiToolsToMcp(names?: string[]): Array<{
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}>;
+/** 能力清单文本（贴 system prompt：可用工具 × 数据形态一览） */
+declare function aiToolsManifest(names?: string[]): string;
+/** 模型 tool_call 参数容错解析（JSON 字符串 / 对象直给 / 坏 JSON 返回 {}） */
+declare function parseAiToolArgs(raw: unknown): Record<string, unknown>;
+
+export { type AiToolArea, type AiToolAreaOptions, type AiToolDef, type AiToolRecord, aiToolsManifest, aiToolsToMcp, aiToolsToOpenAI, createAiToolArea, getAiTool, listAiTools, parseAiToolArgs, registerAiTool, unregisterAiTool };