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

name, description, triggers, tools

name	description	triggers	tools
lsp-index-engineer	LSP/Index 工程师 - 构建语言服务器协议和语义索引系统，提供智能代码理解	LSP 语言服务器 语义索引 代码补全 跳转定义 符号搜索 AST 代码分析	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 核心

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;
}

语义索引引擎

interface SemanticIndex {
  // 符号索引
  indexSymbols(uri: string, content: string): SymbolTable;

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

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

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

索引数据结构

符号表

{
  "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"
    }
  ]
}

引用图谱

{
  "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: 文件发现

# 扫描项目文件
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) \
  | grep -v node_modules | grep -v dist

Step 2: AST 解析

# 解析 TypeScript AST
parse_ast --input $SOURCE_FILE --output $AST_CACHE

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

Step 3: 索引构建

# 构建符号索引
build_index --symbols $SYMBOLS --output $INDEX_DB

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

Step 4: 持久化

# 保存索引
save_index --db $INDEX_DB --path $INDEX_PATH

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

ZCLAW LSP 集成

# 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 = [".", "::"]

性能优化策略

增量索引

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

并行解析

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

缓存策略

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. 支持并发请求处理

故障恢复

索引损坏

# 检测损坏
verify_index --db $INDEX_DB

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

内存溢出

# 限制内存使用
limit_memory --max-mb 512

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

性能退化

# 分析瓶颈
profile_index --output profile.json

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