代码补全 API

概述

Trae 代码补全 API 提供了强大的智能代码补全功能，支持多种编程语言和框架。通过机器学习和静态分析技术，为开发者提供精确、上下文相关的代码建议。

核心功能

智能补全

• 语法补全：基于语言语法的智能提示
• 上下文补全：根据当前代码上下文提供相关建议
• 类型推断：基于类型信息的精确补全
• 导入补全：自动导入所需的模块和库

补全类型

interface CompletionItem {
  label: string;
  kind: CompletionItemKind;
  detail?: string;
  documentation?: string;
  insertText?: string;
  range?: Range;
  sortText?: string;
  filterText?: string;
}

enum CompletionItemKind {
  Text = 1,
  Method = 2,
  Function = 3,
  Constructor = 4,
  Field = 5,
  Variable = 6,
  Class = 7,
  Interface = 8,
  Module = 9,
  Property = 10,
  Unit = 11,
  Value = 12,
  Enum = 13,
  Keyword = 14,
  Snippet = 15,
  Color = 16,
  File = 17,
  Reference = 18
}

API 参考

补全提供者注册

registerCompletionItemProvider()

注册自定义补全提供者：

import { languages, CompletionItemProvider } from '@trae/api';

const provider: CompletionItemProvider = {
  provideCompletionItems(document, position, token, context) {
    const completions = [];
    
    // 添加自定义补全项
    completions.push({
      label: 'myFunction',
      kind: CompletionItemKind.Function,
      detail: 'Custom function',
      documentation: 'This is a custom function',
      insertText: 'myFunction($1)$0'
    });
    
    return completions;
  },
  
  resolveCompletionItem(item, token) {
    // 解析补全项的详细信息
    if (item.label === 'myFunction') {
      item.documentation = 'Detailed documentation for myFunction';
    }
    return item;
  }
};

// 注册提供者
const disposable = languages.registerCompletionItemProvider(
  'typescript', // 语言标识符
  provider,
  '.', '(' // 触发字符
);

内置补全功能

语言服务补全

// TypeScript/JavaScript 补全
const tsProvider = {
  provideCompletionItems(document, position) {
    // 获取当前位置的符号信息
    const word = document.getWordRangeAtPosition(position);
    const text = document.getText(word);
    
    // 基于 TypeScript 语言服务提供补全
    return getTypeScriptCompletions(document, position);
  }
};

// Python 补全
const pythonProvider = {
  provideCompletionItems(document, position) {
    // 基于 Python 语言服务提供补全
    return getPythonCompletions(document, position);
  }
};

代码片段补全

const snippetProvider = {
  provideCompletionItems(document, position) {
    const snippets = [
      {
        label: 'for',
        kind: CompletionItemKind.Snippet,
        insertText: 'for (let ${1:i} = 0; ${1:i} < ${2:array}.length; ${1:i}++) {\n\t$0\n}',
        documentation: 'For loop snippet'
      },
      {
        label: 'if',
        kind: CompletionItemKind.Snippet,
        insertText: 'if (${1:condition}) {\n\t$0\n}',
        documentation: 'If statement snippet'
      }
    ];
    
    return snippets;
  }
};

高级功能

上下文感知补全

const contextAwareProvider = {
  provideCompletionItems(document, position, token, context) {
    const line = document.lineAt(position.line);
    const lineText = line.text;
    
    // 根据当前行内容提供不同的补全
    if (lineText.includes('import')) {
      return getImportCompletions(document, position);
    }
    
    if (lineText.includes('function')) {
      return getFunctionCompletions(document, position);
    }
    
    if (lineText.includes('class')) {
      return getClassCompletions(document, position);
    }
    
    return getGeneralCompletions(document, position);
  }
};

智能导入补全

const importProvider = {
  provideCompletionItems(document, position) {
    const completions = [];
    
    // 扫描项目中的可用模块
    const availableModules = scanProjectModules();
    
    availableModules.forEach(module => {
      completions.push({
        label: module.name,
        kind: CompletionItemKind.Module,
        detail: `from ${module.path}`,
        insertText: module.name,
        additionalTextEdits: [
          {
            range: new Range(0, 0, 0, 0),
            newText: `import { ${module.name} } from '${module.path}';\n`
          }
        ]
      });
    });
    
    return completions;
  }
};

类型推断补全

const typeInferenceProvider = {
  provideCompletionItems(document, position) {
    const completions = [];
    
    // 获取当前位置的类型信息
    const typeInfo = getTypeAtPosition(document, position);
    
    if (typeInfo) {
      // 基于类型提供成员补全
      typeInfo.members.forEach(member => {
        completions.push({
          label: member.name,
          kind: getCompletionKind(member.kind),
          detail: member.type,
          documentation: member.documentation,
          insertText: member.name
        });
      });
    }
    
    return completions;
  }
};

补全配置

全局配置

// 配置补全行为
const completionConfig = {
  // 启用自动补全
  autoComplete: true,
  
  // 补全触发延迟（毫秒）
  triggerDelay: 100,
  
  // 最大补全项数量
  maxItems: 50,
  
  // 启用代码片段
  enableSnippets: true,
  
  // 启用自动导入
  enableAutoImport: true,
  
  // 补全排序策略
  sortStrategy: 'relevance' // 'relevance' | 'alphabetical'
};

// 应用配置
setCompletionConfiguration(completionConfig);

语言特定配置

// TypeScript 特定配置
const tsConfig = {
  includeAutomaticOptionalChainCompletions: true,
  includeCompletionsForModuleExports: true,
  includeCompletionsWithInsertText: true
};

// Python 特定配置
const pythonConfig = {
  enableJediCompletions: true,
  includeMagicMethods: false,
  includePrivateMembers: false
};

性能优化

异步补全

const asyncProvider = {
  async provideCompletionItems(document, position, token) {
    // 检查取消令牌
    if (token.isCancellationRequested) {
      return [];
    }
    
    // 异步获取补全项
    const completions = await fetchCompletionsAsync(document, position);
    
    // 再次检查取消令牌
    if (token.isCancellationRequested) {
      return [];
    }
    
    return completions;
  }
};

缓存机制

const cachedProvider = {
  cache: new Map(),
  
  provideCompletionItems(document, position) {
    const cacheKey = `${document.uri.toString()}:${position.line}:${position.character}`;
    
    // 检查缓存
    if (this.cache.has(cacheKey)) {
      return this.cache.get(cacheKey);
    }
    
    // 生成补全项
    const completions = generateCompletions(document, position);
    
    // 缓存结果
    this.cache.set(cacheKey, completions);
    
    return completions;
  }
};

增量更新

const incrementalProvider = {
  lastDocument: null,
  lastCompletions: [],
  
  provideCompletionItems(document, position) {
    // 检查文档是否发生变化
    if (this.lastDocument && document.version === this.lastDocument.version) {
      // 过滤现有补全项
      return this.filterExistingCompletions(position);
    }
    
    // 生成新的补全项
    const completions = generateCompletions(document, position);
    this.lastDocument = document;
    this.lastCompletions = completions;
    
    return completions;
  }
};

调试和测试

补全调试

const debugProvider = {
  provideCompletionItems(document, position, token, context) {
    console.log('Completion requested at:', position);
    console.log('Trigger character:', context.triggerCharacter);
    console.log('Trigger kind:', context.triggerKind);
    
    const completions = generateCompletions(document, position);
    
    console.log('Generated completions:', completions.length);
    
    return completions;
  }
};

补全测试

// 测试补全提供者
const testCompletion = async () => {
  const document = await workspace.openTextDocument({
    content: 'const x = ',
    language: 'typescript'
  });
  
  const position = new Position(0, 10);
  const completions = await provider.provideCompletionItems(document, position);
  
  assert(completions.length > 0, 'Should provide completions');
  assert(completions.some(c => c.label === 'console'), 'Should include console');
};

最佳实践

补全质量

// 提供高质量的补全项
const qualityProvider = {
  provideCompletionItems(document, position) {
    return [
      {
        label: 'myFunction',
        kind: CompletionItemKind.Function,
        detail: '(param: string) => void',
        documentation: {
          kind: 'markdown',
          value: '**myFunction**\n\nA utility function that processes strings.\n\n```typescript\nmyFunction("example");\n```'
        },
        insertText: 'myFunction(${1:param})$0',
        sortText: '0001' // 高优先级
      }
    ];
  }
};

用户体验

// 优化用户体验
const uxOptimizedProvider = {
  provideCompletionItems(document, position) {
    const completions = [];
    
    // 根据使用频率排序
    const sortedItems = getSortedByUsage();
    
    sortedItems.forEach((item, index) => {
      completions.push({
        ...item,
        sortText: index.toString().padStart(4, '0')
      });
    });
    
    return completions;
  }
};

错误处理

const robustProvider = {
  provideCompletionItems(document, position, token, context) {
    try {
      return generateCompletions(document, position);
    } catch (error) {
      console.error('Completion error:', error);
      
      // 返回基本补全项
      return getBasicCompletions();
    }
  }
};

相关 API

• 语言服务 API - 语言服务集成
• 编辑器 API - 编辑器操作
• 代码片段 API - 代码片段管理
• 诊断 API - 代码诊断