靳中伟 201877f0f0 完善在线脚本内置函数

2025-09-30 13:52:36 +08:00

14 KiB

Raw Blame History

VWED LSP代码补全服务接口文档

概述

VWED LSP代码补全服务基于Language Server Protocol（LSP）标准，通过WebSocket协议为前端脚本编辑器提供智能代码补全、函数签名提示、悬停信息等功能。该服务专门针对VWED内置模块和Python语法进行了优化。

基础URL: /lsp

协议: WebSocket + LSP (Language Server Protocol)

版本: v1.0

支持的功能:

VWED内置模块智能补全（api、function、event、timer等）
Python关键字和内置函数补全
变量和函数名补全
函数签名提示
悬停信息显示
语法验证
实时文档同步

1. WebSocket连接

1.1 建立LSP连接

连接地址: ws://localhost:8000/lsp/code-completion/{client_id}

参数说明:

client_id: 客户端唯一标识符，建议使用时间戳+随机字符串

连接示例:

const clientId = 'editor-' + Date.now();
const ws = new WebSocket(`ws://localhost:8000/lsp/code-completion/${clientId}`);

1.2 连接状态监控

连接建立后，客户端可通过以下方式监控连接状态：

ws.onopen = () => {
    console.log('LSP服务连接成功');
    // 发送初始化请求
    sendInitialize();
};

ws.onclose = () => {
    console.log('LSP服务连接已断开');
};

ws.onerror = (error) => {
    console.log('LSP服务连接错误:', error);
};

2. LSP协议消息

所有LSP消息都遵循JSON-RPC 2.0标准格式：

{
    "jsonrpc": "2.0",
    "id": 1,               // 请求ID（响应类消息必填）
    "method": "方法名",     // LSP方法名
    "params": {}           // 参数对象
}

2.1 初始化请求

客户端连接后必须首先发送初始化请求。

方法: initialize

请求参数:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "clientInfo": {
            "name": "VWED Editor",
            "version": "1.0.0"
        },
        "capabilities": {
            "textDocument": {
                "completion": {
                    "dynamicRegistration": false
                },
                "signatureHelp": {
                    "dynamicRegistration": false
                },
                "hover": {
                    "dynamicRegistration": false
                }
            }
        }
    }
}

响应示例:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "capabilities": {
            "completionProvider": {
                "triggerCharacters": [".", " "],
                "resolveProvider": false
            },
            "signatureHelpProvider": {
                "triggerCharacters": ["(", ","]
            },
            "hoverProvider": true,
            "textDocumentSync": {
                "openClose": true,
                "change": 2
            }
        },
        "serverInfo": {
            "name": "VWED Python Language Server",
            "version": "1.0.0"
        }
    }
}

3. 文档生命周期管理

3.1 打开文档

方法: textDocument/didOpen

参数说明:

{
    "jsonrpc": "2.0",
    "method": "textDocument/didOpen",
    "params": {
        "textDocument": {
            "uri": "file:///path/to/script.py",
            "languageId": "python",
            "version": 1,
            "text": "def boot():\n    VWED."
        }
    }
}

3.2 文档变更

方法: textDocument/didChange

参数说明:

{
    "jsonrpc": "2.0",
    "method": "textDocument/didChange",
    "params": {
        "textDocument": {
            "uri": "file:///path/to/script.py",
            "version": 2
        },
        "contentChanges": [
            {
                "text": "def boot():\n    VWED.api."
            }
        ]
    }
}

3.3 关闭文档

方法: textDocument/didClose

参数说明:

{
    "jsonrpc": "2.0",
    "method": "textDocument/didClose",
    "params": {
        "textDocument": {
            "uri": "file:///path/to/script.py"
        }
    }
}

4. 代码补全功能

4.1 请求代码补全

方法: textDocument/completion

请求参数:

{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "textDocument/completion",
    "params": {
        "textDocument": {
            "uri": "file:///path/to/script.py"
        },
        "position": {
            "line": 1,
            "character": 10
        },
        "context": {
            "documentText": "def boot():\n    VWED."
        }
    }
}

响应示例:

{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "isIncomplete": false,
        "items": [
            {
                "label": "api",
                "kind": 9,
                "detail": "VWED.api",
                "documentation": "VWED内置api模块",
                "insertText": "api",
                "sortText": "01_api"
            },
            {
                "label": "log",
                "kind": 9,
                "detail": "VWED.log",
                "documentation": "VWED内置log模块",
                "insertText": "log",
                "sortText": "01_log"
            },
            {
                "label": "register",
                "kind": 2,
                "detail": "(path, method, handler)",
                "documentation": "注册API接口",
                "insertText": "register",
                "sortText": "01_register"
            }
        ]
    }
}

4.2 补全项类型说明

补全项的kind字段使用LSP标准定义：

Kind	值	说明
Text	1	文本
Method	2	方法
Function	3	函数
Variable	6	变量
Module	9	模块
Keyword	14	关键字

4.3 VWED模块补全示例

当用户输入VWED.时，系统会返回以下模块补全：

api - API接口管理模块
function - 函数注册模块
event - 事件管理模块
timer - 定时器模块
log - 日志记录模块
task - 任务管理模块
data - 数据缓存模块
util - 工具函数模块
device - 设备控制模块

当用户输入VWED.api.时，系统会返回api模块的方法补全：

register() - 注册API接口
unregister() - 注销API接口
get_registered_apis() - 获取已注册的API列表

5. 函数签名提示

5.1 请求签名帮助

方法: textDocument/signatureHelp

请求参数:

{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "textDocument/signatureHelp",
    "params": {
        "textDocument": {
            "uri": "file:///path/to/script.py"
        },
        "position": {
            "line": 1,
            "character": 20
        },
        "context": {
            "documentText": "def boot():\n    VWED.api.register("
        }
    }
}

响应示例:

{
    "jsonrpc": "2.0",
    "id": 3,
    "result": {
        "signatures": [
            {
                "label": "VWED.api.register(path, method, handler)",
                "documentation": "注册API接口\n\npath: API路径\nmethod: HTTP方法\nhandler: 处理函数",
                "parameters": [
                    {
                        "label": "path",
                        "documentation": "API路径字符串"
                    },
                    {
                        "label": "method", 
                        "documentation": "HTTP方法(GET/POST/PUT/DELETE)"
                    },
                    {
                        "label": "handler",
                        "documentation": "处理函数"
                    }
                ],
                "activeParameter": 0
            }
        ],
        "activeSignature": 0,
        "activeParameter": 0
    }
}

6. 悬停信息

6.1 请求悬停信息

方法: textDocument/hover

请求参数:

{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "textDocument/hover",
    "params": {
        "textDocument": {
            "uri": "file:///path/to/script.py"
        },
        "position": {
            "line": 1,
            "character": 15
        },
        "context": {
            "documentText": "def boot():\n    VWED.api.register"
        }
    }
}

响应示例:

{
    "jsonrpc": "2.0",
    "id": 4,
    "result": {
        "contents": {
            "kind": "markdown",
            "value": "```python\nVWED.api.register(path, method, handler)\n```\n\n注册API接口到VWED动态路由系统"
        }
    }
}

7. HTTP管理接口

7.1 健康检查

接口地址: GET /lsp/health

功能说明: 检查LSP服务健康状态

响应示例:

{
    "status": "healthy",
    "service": "VWED LSP Code Completion",
    "active_connections": 2,
    "capabilities": [
        "textDocument/completion",
        "textDocument/signatureHelp",
        "textDocument/hover",
        "textDocument/didOpen",
        "textDocument/didChange",
        "textDocument/didClose"
    ]
}

7.2 获取活跃客户端

接口地址: GET /lsp/clients

功能说明: 获取当前连接的LSP客户端列表

响应示例:

{
    "active_clients": [
        {
            "client_id": "editor-1640000000000",
            "initialized": true,
            "document_count": 1,
            "documents": ["file:///test.py"]
        }
    ],
    "total_count": 1
}

8. 错误处理

8.1 LSP错误响应格式

{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
        "code": -32603,
        "message": "Internal error: 具体错误信息"
    }
}

8.2 常见错误代码

错误代码	说明
-32700	Parse error - JSON解析错误
-32601	Method not found - 方法未找到
-32603	Internal error - 服务器内部错误

9. 客户端集成示例

9.1 JavaScript集成示例

class VWEDLSPClient {
    constructor(editorElement) {
        this.editor = editorElement;
        this.ws = null;
        this.requestId = 1;
        this.clientId = 'editor-' + Date.now();
    }
    
    connect() {
        this.ws = new WebSocket(`ws://localhost:8000/lsp/code-completion/${this.clientId}`);
        
        this.ws.onopen = () => {
            this.sendInitialize();
            this.sendDidOpen();
        };
        
        this.ws.onmessage = (event) => {
            const message = JSON.parse(event.data);
            this.handleMessage(message);
        };
    }
    
    sendInitialize() {
        this.sendMessage({
            jsonrpc: "2.0",
            id: this.requestId++,
            method: "initialize",
            params: {
                clientInfo: { name: "VWED Editor", version: "1.0.0" },
                capabilities: {
                    textDocument: {
                        completion: { dynamicRegistration: false }
                    }
                }
            }
        });
    }
    
    requestCompletion(position) {
        this.sendMessage({
            jsonrpc: "2.0",
            id: this.requestId++,
            method: "textDocument/completion",
            params: {
                textDocument: { uri: "file:///script.py" },
                position: position,
                context: { documentText: this.editor.value }
            }
        });
    }
    
    sendMessage(message) {
        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
            this.ws.send(JSON.stringify(message));
        }
    }
    
    handleMessage(message) {
        if (message.method === 'textDocument/completion' && message.result) {
            this.showCompletions(message.result.items);
        }
    }
}

9.2 TypeScript接口定义

interface LSPPosition {
    line: number;
    character: number;
}

interface LSPCompletionItem {
    label: string;
    kind: number;
    detail?: string;
    documentation?: string;
    insertText?: string;
    sortText?: string;
}

interface LSPCompletionResult {
    isIncomplete: boolean;
    items: LSPCompletionItem[];
}

10. 性能优化建议

10.1 客户端优化

防抖处理: 对频繁的文档变更事件进行防抖处理
增量更新: 使用增量文档更新而非全量更新
连接复用: 同一编辑器实例复用WebSocket连接
缓存补全: 对补全结果进行适当缓存

10.2 触发条件

建议在以下情况触发代码补全：

用户输入.字符
用户按下Ctrl+Space
输入标识符字符超过2个
用户停止输入500ms后

11. 注意事项

连接管理: 客户端断开时应主动关闭WebSocket连接
文档同步: 确保客户端和服务端的文档内容同步
错误处理: 妥善处理网络异常和协议错误
资源清理: 及时清理不再使用的文档和连接资源

附录：VWED内置模块参考

A.1 VWED.api模块

register(path, method, handler) - 注册API接口
unregister(path, method) - 注销API接口
get_registered_apis() - 获取已注册API列表

A.2 VWED.log模块

info(message) - 记录信息日志
error(message) - 记录错误日志
debug(message) - 记录调试日志
warning(message) - 记录警告日志

A.3 VWED.function模块

register(name, handler) - 注册函数
unregister(name) - 注销函数
call(name, args) - 调用已注册函数

A.4 VWED.timer模块

create(interval, callback) - 创建定时器
destroy(timer_id) - 销毁定时器
get_active_timers() - 获取活跃定时器列表

A.5 VWED.event模块

listen(event_name, handler) - 监听事件
emit(event_name, data) - 触发事件
unlisten(event_name, handler) - 取消监听

更多模块详情请参考"在线脚本编辑接口文档"。

14 KiB Raw Blame History Unescape Escape

VWED LSP代码补全服务接口文档

概述

1. WebSocket连接

1.1 建立LSP连接

1.2 连接状态监控

2. LSP协议消息

2.1 初始化请求

3. 文档生命周期管理

3.1 打开文档

3.2 文档变更

3.3 关闭文档

4. 代码补全功能

4.1 请求代码补全

4.2 补全项类型说明

4.3 VWED模块补全示例

5. 函数签名提示

5.1 请求签名帮助

6. 悬停信息

6.1 请求悬停信息

7. HTTP管理接口

7.1 健康检查

7.2 获取活跃客户端

8. 错误处理

8.1 LSP错误响应格式

8.2 常见错误代码

9. 客户端集成示例

9.1 JavaScript集成示例

9.2 TypeScript接口定义

10. 性能优化建议

10.1 客户端优化

10.2 触发条件

11. 注意事项

附录：VWED内置模块参考

A.1 VWED.api模块

A.2 VWED.log模块

A.3 VWED.function模块

A.4 VWED.timer模块

A.5 VWED.event模块

14 KiB

Raw Blame History