# 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`: 客户端唯一标识符，建议使用时间戳+随机字符串

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

### 1.2 连接状态监控

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

```javascript
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标准格式：

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

### 2.1 初始化请求

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

**方法**: `initialize`

**请求参数**:
```json
{
    "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
                }
            }
        }
    }
}
```

**响应示例**:
```json
{
    "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`

**参数说明**:
```json
{
    "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`

**参数说明**:
```json
{
    "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`

**参数说明**:
```json
{
    "jsonrpc": "2.0",
    "method": "textDocument/didClose",
    "params": {
        "textDocument": {
            "uri": "file:///path/to/script.py"
        }
    }
}
```

---

## 4. 代码补全功能

### 4.1 请求代码补全

**方法**: `textDocument/completion`

**请求参数**:
```json
{
    "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."
        }
    }
}
```

**响应示例**:
```json
{
    "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`

**请求参数**:
```json
{
    "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("
        }
    }
}
```

**响应示例**:
```json
{
    "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`

**请求参数**:
```json
{
    "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"
        }
    }
}
```

**响应示例**:
```json
{
    "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服务健康状态

**响应示例**:
```json
{
    "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客户端列表

**响应示例**:
```json
{
    "active_clients": [
        {
            "client_id": "editor-1640000000000",
            "initialized": true,
            "document_count": 1,
            "documents": ["file:///test.py"]
        }
    ],
    "total_count": 1
}
```

---

## 8. 错误处理

### 8.1 LSP错误响应格式

```json
{
    "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集成示例

```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接口定义

```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 客户端优化

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

### 10.2 触发条件

建议在以下情况触发代码补全：
- 用户输入`.`字符
- 用户按下`Ctrl+Space`
- 输入标识符字符超过2个
- 用户停止输入500ms后

---

## 11. 注意事项

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

---

## 附录：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)` - 取消监听

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