@monaco-ai-editor/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+import * as MonacoType from 'monaco-editor';
+
+/** AI API 配置（OpenAI 兼容协议） */
+interface ApiConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    /** true = 流式输出（默认），false = 一次性返回 */
+    streamMode?: boolean;
+}
+/** SQL 表结构 Schema：{ 表名: [列名, ...] } */
+type SqlSchema = Record<string, string[]>;
+/** 待显示的内联补全（用于 AI 幽灵文本） */
+interface PendingCompletion {
+    lineNumber: number;
+    column: number;
+    insertText: string;
+}
+/** 一条聊天消息 */
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    isStreaming?: boolean;
+}
+/** 编辑器状态快照 */
+interface EditorSnapshot {
+    value: string;
+    language: string;
+    theme: string;
+    cursorLine: number;
+    cursorColumn: number;
+}
+/** 补全上下文，传给自定义 CompletionProvider */
+interface CompletionContext {
+    monaco: typeof MonacoType;
+    model: MonacoType.editor.ITextModel;
+    position: MonacoType.Position;
+    lineText: string;
+    /** 光标前的单词 */
+    currentWord: string;
+    fullText: string;
+    /** Monaco 自带的 triggerKind / triggerCharacter */
+    triggerCharacter?: string;
+}
+/**
+ * 扩展点：自定义补全提供者。
+ * 用户通过 EditorController 注册，运行时被聚合调度。
+ */
+interface CompletionProvider {
+    id: string;
+    /** 适用的语言（不传则全部语言） */
+    languages?: string[];
+    /** 触发字符（默认无） */
+    triggerCharacters?: string[];
+    /** 判断是否触发（同步） */
+    shouldTrigger?: (ctx: CompletionContext) => boolean;
+    /** 提供建议（可异步） */
+    provide: (ctx: CompletionContext) => Promise<MonacoType.languages.CompletionItem[]> | MonacoType.languages.CompletionItem[];
+}
+
+declare const SQL_KEYWORDS: string[];
+declare const SQL_FUNCTIONS: string[];
+declare const SQL_DATA_TYPES: string[];
+declare const LANGUAGES: readonly ["javascript", "typescript", "python", "json", "css", "html", "markdown", "rust", "go", "sql"];
+/** Monaco 编辑器支持的 UI 本地化语言 */
+declare const LOCALES: {
+    readonly ZH_CN: "zh-cn";
+    readonly EN: "en";
+    readonly DE: "de";
+    readonly ES: "es";
+    readonly FR: "fr";
+    readonly IT: "it";
+    readonly JA: "ja";
+    readonly KO: "ko";
+    readonly RU: "ru";
+};
+type Locale = (typeof LOCALES)[keyof typeof LOCALES];
+declare const THEMES: readonly [{
+    readonly value: "vs-dark";
+    readonly label: "Dark";
+}, {
+    readonly value: "light";
+    readonly label: "Light";
+}, {
+    readonly value: "hc-black";
+    readonly label: "High Contrast";
+}];
+declare const AI_INLINE_LANGUAGES: string[];
+
+/**
+ * 极简事件发射器，框架无关。
+ * 用于 EditorController / AiChatController / EditorBus 之间的事件通信。
+ */
+type Listener<T> = (payload: T) => void;
+declare class EventEmitter<EventMap> {
+    private listeners;
+    on<K extends keyof EventMap>(event: K, listener: Listener<EventMap[K]>): () => void;
+    off<K extends keyof EventMap>(event: K, listener: Listener<EventMap[K]>): void;
+    emit<K extends keyof EventMap>(event: K, payload: EventMap[K]): void;
+    removeAllListeners(): void;
+}
+
+interface EditorControllerEvents {
+    change: {
+        value: string;
+    };
+    cursor: {
+        line: number;
+        column: number;
+    };
+    ready: {
+        editor: MonacoType.editor.IStandaloneCodeEditor;
+    };
+    languageChange: {
+        language: string;
+    };
+    focus: void;
+    blur: void;
+}
+interface EditorControllerOptions {
+    container: HTMLElement;
+    language?: string;
+    theme?: string;
+    value?: string;
+    monaco: typeof MonacoType;
+    /** Monaco loader monaco-editor 路径配置 */
+    vsPath?: string;
+    sqlSchema?: SqlSchema;
+    apiConfig?: ApiConfig | null;
+    completionProviders?: CompletionProvider[];
+    /** Monaco editor options */
+    editorOptions?: MonacoType.editor.IStandaloneEditorConstructionOptions;
+}
+/**
+ * 框架无关的编辑器控制器。
+ * 封装 Monaco 实例的生命周期、核心操作、补全注册。
+ * 通过 EventEmitter 暴露编辑器事件，不依赖任何 UI 框架。
+ */
+declare class EditorController extends EventEmitter<EditorControllerEvents> {
+    private options;
+    private editor;
+    private monaco;
+    private sqlProviderRegistered;
+    private aiProviderRegistered;
+    private pendingCompletionRef;
+    private customProviders;
+    private disposables;
+    completed: boolean;
+    error: Error | null;
+    constructor(options: EditorControllerOptions);
+    private init;
+    private bindEditorEvents;
+    private registerCustomCompletionProviders;
+    getEditor(): MonacoType.editor.IStandaloneCodeEditor | null;
+    getValue(): string;
+    setValue(value: string): void;
+    insertText(text: string, range?: MonacoType.IRange): void;
+    format(): void;
+    focus(): void;
+    setLanguage(language: string): void;
+    setTheme(theme: string): void;
+    getCursorPosition(): {
+        line: number;
+        column: number;
+    };
+    getSelection(): MonacoType.IRange | null;
+    /**
+     * 触发 AI 行内补全（Ctrl+Alt+L 快捷键）。
+     * 需要提前设置 apiConfig（通过 setApiConfig 或构造函数传入）。
+     */
+    setApiConfig(config: ApiConfig | null): void;
+    getPendingCompletionRef(): {
+        current: PendingCompletion | null;
+    };
+    dispose(): void;
+}
+
+interface AiChatControllerEvents {
+    messageAdded: ChatMessage;
+    messageUpdated: ChatMessage;
+    cleared: void;
+    loadingChange: {
+        loading: boolean;
+    };
+    error: {
+        message: string;
+    };
+}
+/**
+ * AI 聊天控制器：管理消息列表、API 调用与流式响应。
+ * 框架无关：通过事件通知 UI 层更新。
+ */
+declare class AiChatController extends EventEmitter<AiChatControllerEvents> {
+    private messages;
+    private abortController;
+    private loading;
+    private apiConfig;
+    constructor(apiConfig: ApiConfig);
+    setApiConfig(config: ApiConfig): void;
+    getApiConfig(): ApiConfig;
+    getMessages(): readonly ChatMessage[];
+    isLoading(): boolean;
+    /** 发送消息，可选携带编辑器上下文 */
+    send(userInput: string, options?: {
+        editorContent?: string;
+        language?: string;
+    }): Promise<void>;
+    stop(): void;
+    clear(): void;
+    dispose(): void;
+}
+
+interface EditorBusEvents {
+    /** 编辑器已注册 */
+    'editor:ready': EditorController;
+    /** 编辑器即将卸载 */
+    'editor:dispose': void;
+    /** 编辑器内容变化 */
+    'editor:change': {
+        value: string;
+    };
+    /** 编辑器光标变化 */
+    'editor:cursor': {
+        line: number;
+        column: number;
+    };
+    /** 编辑器语言变化 */
+    'editor:languageChange': {
+        language: string;
+    };
+    /** 聊天面板已注册 */
+    'chat:ready': AiChatController;
+    /** 聊天面板卸载 */
+    'chat:dispose': void;
+    /** 聊天面板请求向编辑器插入代码 */
+    'chat:insertCode': {
+        code: string;
+    };
+    /** 聊天面板请求替换编辑器全部内容 */
+    'chat:replaceCode': {
+        code: string;
+    };
+}
+/**
+ * 编辑器与聊天面板的通信总线。
+ * 在两个组件都引入时由协调器（Coordinator）创建并共享，实现自动联动。
+ * 当只引入其中一个组件时，bus 可为 null，组件正常独立工作。
+ */
+declare class EditorBus extends EventEmitter<EditorBusEvents> {
+    private editor;
+    private chat;
+    registerEditor(controller: EditorController): () => void;
+    registerChat(controller: AiChatController): () => void;
+    getEditor(): EditorController | null;
+    getChat(): AiChatController | null;
+    /** 让聊天面板向编辑器请求当前内容 */
+    getEditorContent(): string;
+    /** 让聊天面板向编辑器请求当前语言 */
+    getEditorLanguage(): string | undefined;
+    /** 让聊天面板请求向编辑器插入代码 */
+    insertToEditor(code: string): void;
+    /** 让聊天面板请求替换编辑器全部内容 */
+    replaceEditor(code: string): void;
+}
+
+/**
+ * 注册 SQL 内置补全提供者。
+ * schemaRef 使用 ref 模式以支持动态更新。
+ * excludeLabelsRef（可选）使用 ref 模式，提供需要从内置关键字/函数中排除的 label
+ * （大写匹配）。用于让使用方的自定义词表覆盖内置同名项，避免重复提示。
+ */
+declare function registerSqlCompletion(monaco: typeof MonacoType, schemaRef: {
+    readonly current: SqlSchema;
+}, excludeLabelsRef?: {
+    readonly current: Set<string>;
+}): MonacoType.IDisposable;
+
+/** 非流式调用 OpenAI 兼容 API（使用原生 fetch，无 axios 依赖） */
+declare function fetchAiCompletionNonStream(config: ApiConfig, context: string, prefix: string, signal?: AbortSignal): Promise<string>;
+/** 流式调用（fetch + ReadableStream） */
+declare function fetchAiCompletionStream(config: ApiConfig, context: string, prefix: string, onChunk: (accumulated: string) => void, signal?: AbortSignal): Promise<void>;
+/** 注册 AI 内联幽灵文本提供者 */
+declare function registerAiInlineCompletion(monaco: typeof MonacoType, pendingRef: {
+    current: PendingCompletion | null;
+}): void;
+/**
+ * 注册 AI 补全命令（Ctrl+Alt+L 手动触发，流式更新幽灵文本）。
+ * 框架无关：通过函数引用方式读取最新的 apiConfig。
+ */
+declare function registerAiCompletionCommand(editor: MonacoType.editor.IStandaloneCodeEditor, getApiConfig: () => ApiConfig | null, pendingRef: {
+    current: PendingCompletion | null;
+}, onLoadingChange?: (loading: boolean) => void, onError?: (message: string) => void): MonacoType.IDisposable;
+
+export { AI_INLINE_LANGUAGES, AiChatController, type AiChatControllerEvents, type ApiConfig, type ChatMessage, type CompletionContext, type CompletionProvider, EditorBus, type EditorBusEvents, EditorController, type EditorControllerEvents, type EditorControllerOptions, type EditorSnapshot, EventEmitter, LANGUAGES, LOCALES, type Listener, type Locale, type PendingCompletion, SQL_DATA_TYPES, SQL_FUNCTIONS, SQL_KEYWORDS, type SqlSchema, THEMES, fetchAiCompletionNonStream, fetchAiCompletionStream, registerAiCompletionCommand, registerAiInlineCompletion, registerSqlCompletion };