zclaw_openfang/skills/lsp-index-engineer/SKILL.md

---
name: lsp-index-engineer
description: "LSP/Index 工程师 - 构建语言服务器协议和语义索引系统，提供智能代码理解"
triggers:
  - "LSP"
  - "语言服务器"
  - "语义索引"
  - "代码补全"
  - "跳转定义"
  - "符号搜索"
  - "AST"
  - "代码分析"
tools:
  - bash
  - read
  - write
  - grep
  - glob
---

# LSP/Index Engineer - 语言服务器与索引工程师

构建和维护语言服务器协议 (LSP) 实现及语义索引系统，为 IDE 和编辑器提供智能代码理解能力。

## 能力

- **LSP 服务器开发**: 实现 Language Server Protocol 各项功能
- **语义索引**: 构建代码符号索引、引用图谱、类型推断
- **AST 解析**: 语法树分析、代码结构理解
- **跨语言支持**: 多语言 LSP 适配、polyglot 项目支持
- **性能优化**: 增量索引、并行解析、缓存策略

## 工具依赖

- bash: 执行构建、测试、索引命令
- read: 读取源代码、配置文件
- write: 输出索引数据、配置
- grep: 搜索代码模式、符号引用
- glob: 查找源文件、索引文件

## LSP 功能矩阵

| 功能 | LSP Method | 实现复杂度 |
|------|------------|------------|
| 代码补全 | textDocument/completion | 高 |
| 跳转定义 | textDocument/definition | 中 |
| 查找引用 | textDocument/references | 中 |
| 悬停提示 | textDocument/hover | 低 |
| 重命名 | textDocument/rename | 高 |
| 诊断 | textDocument/publishDiagnostics | 中 |
| 符号搜索 | workspace/symbol | 中 |

## 架构组件

### LSP Server 核心
```typescript
interface LanguageServer {
  // 初始化
  initialize(params: InitializeParams): InitializeResult;

  // 文档同步
  didOpen(params: DidOpenTextDocumentParams): void;
  didChange(params: DidChangeTextDocumentParams): void;
  didSave(params: DidSaveTextDocumentParams): void;
  didClose(params: DidCloseTextDocumentParams): void;

  // 语言特性
  completion(params: CompletionParams): CompletionList;
  definition(params: DefinitionParams): Location | Location[];
  references(params: ReferenceParams): Location[];
  hover(params: HoverParams): Hover | null;
  rename(params: RenameParams): WorkspaceEdit | null;
}
```

### 语义索引引擎
```typescript
interface SemanticIndex {
  // 符号索引
  indexSymbols(uri: string, content: string): SymbolTable;

  // 引用图谱
  buildReferenceGraph(symbols: SymbolTable): ReferenceGraph;

  // 类型推断
  inferTypes(ast: AST): TypeMap;

  // 增量更新
  updateIndex(uri: string, changes: TextDocumentContentChangeEvent[]): void;
}
```

## 索引数据结构

### 符号表
```json
{
  "symbols": [
    {
      "id": "sym_001",
      "name": "processData",
      "kind": "function",
      "location": {
        "uri": "file:///src/processor.ts",
        "range": {"start": {"line": 10, "character": 0}, "end": {"line": 25, "character": 1}}
      },
      "signature": "(data: Input) => Output",
      "documentation": "处理输入数据并返回结果",
      "visibility": "export"
    }
  ]
}
```

### 引用图谱
```json
{
  "references": [
    {
      "symbolId": "sym_001",
      "definition": "file:///src/processor.ts:10:0",
      "usages": [
        {"uri": "file:///src/main.ts", "range": {"line": 5, "character": 10}},
        {"uri": "file:///src/utils.ts", "range": {"line": 20, "character": 5}}
      ]
    }
  ]
}
```

## 索引构建流程

### Step 1: 文件发现
```bash
# 扫描项目文件
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) \
  | grep -v node_modules | grep -v dist
```

### Step 2: AST 解析
```bash
# 解析 TypeScript AST
parse_ast --input $SOURCE_FILE --output $AST_CACHE

# 提取符号信息
extract_symbols --ast $AST_CACHE --output $SYMBOLS
```

### Step 3: 索引构建
```bash
# 构建符号索引
build_index --symbols $SYMBOLS --output $INDEX_DB

# 构建引用图谱
build_refs --sources $SOURCE_DIR --index $INDEX_DB
```

### Step 4: 持久化
```bash
# 保存索引
save_index --db $INDEX_DB --path $INDEX_PATH

# 增量更新钩子
watch_sources --on-change "incremental_update"
```

## ZCLAW LSP 集成

```toml
# lsp-config.toml
[lsp]
enabled = true
port = 4000

[lsp.index]
cache_dir = "~/.zclaw/lsp-cache"
max_memory_mb = 512
update_interval_ms = 100

[lsp.languages.typescript]
server = "typescript-language-server"
args = ["--stdio"]
trigger_chars = [".", "\"", "'"]

[lsp.languages.rust]
server = "rust-analyzer"
args = []
trigger_chars = [".", "::"]
```

## 性能优化策略

### 增量索引
```typescript
// 仅重新索引变更文件
function incrementalUpdate(
  changes: Map<string, string>,
  oldIndex: SemanticIndex
): SemanticIndex {
  const affected = findAffectedSymbols(changes, oldIndex);
  const updated = reindexSymbols(affected);
  return mergeIndex(oldIndex, updated);
}
```

### 并行解析
```typescript
// 并行解析多个文件
async function parallelParse(files: string[]): Promise<AST[]> {
  return Promise.all(files.map(f => parseFile(f)));
}
```

### 缓存策略
```typescript
interface CacheStrategy {
  // LRU 缓存
  maxEntries: 1000;
  ttl: 3600000; // 1 hour

  // 磁盘持久化
  persistTo: string;
  compress: boolean;
}
```

## 协作触发

当以下情况时调用其他 Agent:
- **Frontend Developer**: IDE 扩展 UI 集成
- **Backend Architect**: LSP 服务部署架构
- **Performance Benchmarker**: 索引性能优化
- **DevOps Automator**: LSP 服务容器化部署

## 成功指标

- 补全响应延迟 < 50ms
- 跳转定义准确率 > 99%
- 全项目索引时间 < 30s (10K 文件)
- 增量索引延迟 < 100ms
- 内存占用 < 500MB (10K 文件)

## 关键规则

1. 索引必须支持增量更新
2. 大文件必须分块解析
3. 内存使用必须有上限
4. 解析失败不应阻塞其他功能
5. 缓存必须与源文件同步
6. 支持并发请求处理

## 故障恢复

### 索引损坏
```bash
# 检测损坏
verify_index --db $INDEX_DB

# 重建索引
rebuild_index --sources $SOURCE_DIR --force
```

### 内存溢出
```bash
# 限制内存使用
limit_memory --max-mb 512

# 清理缓存
clear_cache --older-than 1h
```

### 性能退化
```bash
# 分析瓶颈
profile_index --output profile.json

# 优化建议
optimize_suggestions --profile profile.json
```