代码库索引

索引基础

什么是代码库索引

Kiro 自动为代码库建立索引，以提供智能代码建议、导航和上下文感知的协助。索引系统分析您的整个项目结构，创建代码元素之间的关联映射，使 AI 能够更好地理解项目上下文。

索引的价值

  • 智能代码补全 - 基于项目上下文的精准建议
  • 跨文件导航 - 快速跳转到相关代码
  • 上下文感知 - AI 理解代码关系和依赖
  • 重构支持 - 安全的代码重构和重命名
  • 文档查找 - 快速访问相关文档和注释

自动索引机制

索引触发场景

Kiro 在以下三种主要场景下自动执行索引：

1. 项目导入

触发时机：首次打开工作空间或导入新项目

索引内容：

  • 扫描所有项目文件
  • 分析代码结构和依赖关系
  • 建立符号映射表
  • 生成项目拓扑结构

过程示例：

项目导入索引流程:
  1. 文件发现阶段:
     - 扫描目录结构
     - 识别代码文件类型
     - 过滤不必要的文件
  
  2. 内容分析阶段:
     - 解析语法结构
     - 提取符号定义
     - 分析导入导出关系
  
  3. 关系建立阶段:
     - 构建依赖图
     - 建立引用关系
     - 生成索引数据库

2. 文件变更

触发时机：创建、修改或删除文件时

增量索引特性：

  • 只重新索引变更的文件
  • 更新相关的依赖关系
  • 保持索引数据的一致性
  • 优化索引性能

变更处理示例：

// 当修改这个文件时
export function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// 索引系统会更新：
索引更新内容:
  - 函数签名变更
  - 导出符号更新
  - 影响的引用文件列表
  - 类型推断信息

3. 外部变更

触发时机：在 Kiro 外部修改文件时

检测机制：

  • 文件系统监控
  • Git 变更检测
  • 时间戳比较
  • 哈希值验证

重新索引策略：

外部变更处理:
  检测方式:
    - 文件修改时间检查
    - 文件内容哈希对比
    - Git 状态监控
  
  响应策略:
    - 即时重新索引变更文件
    - 批量处理多个变更
    - 后台异步处理
    - 优先级排序处理

手动索引控制

访问索引命令

通过命令面板访问索引功能：

  • macOS: Cmd+Shift+P
  • Windows/Linux: Ctrl+Shift+P

主要索引命令

1. 强制重新索引

命令: Kiro: Codebase Force Re-Index

用途：

  • 完整重新索引整个代码库
  • 解决索引不一致问题
  • 更新过时的索引信息

适用场景：

强制重新索引场景:
  - 大量外部文件变更后
  - 依赖项更新后
  - 索引数据损坏时
  - 性能问题排查
  - 项目结构重大调整后

2. 重建索引

命令: Kiro: Rebuild codebase index

用途：

  • 从头彻底重建索引
  • 清除所有现有索引数据
  • 建立全新的索引数据库

与强制重新索引的区别：

命令对比:
  强制重新索引:
    - 基于现有索引结构
    - 更新索引内容
    - 保留有效的索引数据
    - 执行速度较快
  
  重建索引:
    - 删除所有现有索引
    - 重新分析所有文件
    - 重新建立索引结构
    - 执行时间较长但更彻底

索引内容类型

源代码索引

支持的编程语言

主要语言支持:
  前端:
    - JavaScript (ES6+)
    - TypeScript
    - React JSX/TSX
    - Vue.js
    - HTML/CSS/SCSS
  
  后端:
    - Python
    - Go
    - Java
    - C#
    - Ruby
    - PHP
  
  数据:
    - JSON
    - YAML
    - XML
    - SQL

代码元素索引

// 索引的代码元素示例
class UserService {
  // 类定义 - 索引为符号
  constructor(apiClient) {
    // 构造函数 - 索引参数和类型
    this.client = apiClient;
  }
  
  async fetchUser(id) {
    // 方法定义 - 索引签名和返回类型
    return await this.client.get(`/users/${id}`);
  }
}

// 导出语句 - 索引为可用符号
export { UserService };

// 索引内容包括：
索引元素:
  - 类名: UserService
  - 方法: constructor, fetchUser
  - 参数: apiClient, id
  - 导出: UserService
  - 依赖: apiClient (外部依赖)
  - 类型信息: async, Promise 返回类型

文档索引

文档格式支持

支持的文档格式:
  标记语言:
    - Markdown (.md)
    - MDX (.mdx)
    - reStructuredText (.rst)
  
  文档工具:
    - JSDoc 注释
    - TypeDoc 注释
    - Sphinx 文档
    - GitBook
  
  README 文件:
    - 项目说明
    - 安装指南
    - API 文档
    - 使用示例

文档内容索引

# API 文档

## UserService 类

提供用户相关的 API 操作功能。

### 方法

#### fetchUser(id)

获取指定 ID 的用户信息。

**参数：**
- `id` (string): 用户唯一标识符

**返回：**
- `Promise<User>`: 用户对象

<!-- 索引内容包括：-->
索引文档元素:
  - 标题层级: API 文档 > UserService 类
  - 方法文档: fetchUser
  - 参数说明: id (string)
  - 返回类型: Promise<User>
  - 关键词: API, 用户, 操作功能

配置文件索引

项目配置

配置文件类型:
  包管理:
    - package.json (Node.js)
    - requirements.txt (Python)
    - go.mod (Go)
    - Cargo.toml (Rust)
  
  构建配置:
    - webpack.config.js
    - vite.config.js
    - tsconfig.json
    - babel.config.js
  
  项目设置:
    - .eslintrc
    - .prettierrc
    - .gitignore
    - docker-compose.yml

配置内容索引

// package.json 索引示例
{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.0.0",
    "axios": "^1.3.0"
  },
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

// 索引内容：
配置索引内容:
  - 项目名称: my-project
  - 版本: 1.0.0
  - 依赖包: react, axios
  - 可用脚本: dev, build
  - 构建工具: vite

依赖关系索引

依赖类型

依赖关系类型:
  直接依赖:
    - import/require 语句
    - 包依赖声明
    - 模块引用
  
  间接依赖:
    - 传递性依赖
    - 插件依赖
    - 工具链依赖
  
  开发依赖:
    - 测试框架
    - 构建工具
    - 代码质量工具

依赖图构建

// 依赖关系示例
// src/services/UserService.js
import { ApiClient } from '../utils/ApiClient.js';
import { Logger } from '../utils/Logger.js';

// src/utils/ApiClient.js
import axios from 'axios';

// 构建的依赖图：
依赖关系图:
  UserService:
    直接依赖:
      - ApiClient
      - Logger
    间接依赖:
      - axios (通过 ApiClient)
  
  影响分析:
    - 修改 ApiClient 会影响 UserService
    - axios 更新需要测试 ApiClient 和 UserService

启用功能

智能代码补全

上下文感知补全

// 基于索引的智能补全示例
class UserManager {
  constructor() {
    this.userService = new UserService(); // 补全建议基于索引
  }
  
  async getUser(id) {
    // 输入 this.userService. 时，IDE 会基于索引提供：
    // - fetchUser(id)
    // - updateUser(user)
    // - deleteUser(id)
    return await this.userService.fetchUser(id);
  }
}

类型推断补全

// TypeScript 类型推断示例
interface User {
  id: string;
  name: string;
  email: string;
}

// 基于索引的类型补全
const user: User = {
  // 输入时自动补全 User 接口的属性
  id: '',
  name: '',
  email: ''
};

跨文件导航

符号定义跳转

导航功能:
  跳转到定义:
    - 函数定义位置
    - 类定义位置
    - 变量声明位置
    - 类型定义位置
  
  查找引用:
    - 所有使用该符号的位置
    - 导入该模块的文件
    - 继承该类的子类

快捷导航

导航快捷键:
  跳转到定义: F12
  查看定义: Alt+F12
  查找引用: Shift+F12
  返回上一位置: Alt+Left
  前进到下一位置: Alt+Right

上下文感知建议

AI 助手增强

AI 功能增强:
  代码理解:
    - 基于项目上下文的代码解释
    - 识别代码模式和设计模式
    - 理解业务逻辑关系
  
  重构建议:
    - 安全的重命名操作
    - 代码提取和合并建议
    - 架构改进建议
  
  错误诊断:
    - 基于上下文的错误分析
    - 相关代码影响评估
    - 修复建议和示例

监控索引状态

Kiro 日志面板

访问日志

  1. 打开 Kiro 面板
  2. 选择”日志”选项卡
  3. 过滤索引相关日志

日志信息内容

日志记录内容:
  索引开始时间:
    - 触发原因 (自动/手动)
    - 索引范围 (全量/增量)
    - 预估处理时间
  
  进度信息:
    - 已处理文件数量
    - 总文件数量
    - 完成百分比
    - 当前处理的文件
  
  完成信息:
    - 总处理时间
    - 索引文件统计
    - 错误和警告数量
    - 索引数据库大小

示例日志输出

[2025-07-21 10:30:00] INFO: 开始代码库索引
[2025-07-21 10:30:00] INFO: 索引触发原因: 项目导入
[2025-07-21 10:30:01] INFO: 发现 1,247 个文件待处理
[2025-07-21 10:30:15] INFO: 进度: 25% (312/1,247 文件)
[2025-07-21 10:30:30] INFO: 进度: 50% (624/1,247 文件)
[2025-07-21 10:30:45] INFO: 进度: 75% (936/1,247 文件)
[2025-07-21 10:31:00] INFO: 索引完成
[2025-07-21 10:31:00] INFO: 总耗时: 60 秒
[2025-07-21 10:31:00] INFO: 成功索引: 1,247 文件
[2025-07-21 10:31:00] INFO: 索引大小: 15.7 MB

性能监控

索引性能指标

性能指标:
  处理速度:
    - 文件/秒处理率
    - 平均文件处理时间
    - 不同文件类型的处理速度
  
  资源使用:
    - CPU 使用率
    - 内存占用量
    - 磁盘 I/O 压力
  
  索引质量:
    - 符号识别准确率
    - 依赖关系完整性
    - 索引数据一致性

性能优化建议

优化策略:
  文件过滤:
    - 排除 node_modules 目录
    - 忽略构建输出目录
    - 跳过二进制文件
  
  增量处理:
    - 只处理变更文件
    - 智能依赖更新
    - 缓存处理结果
  
  资源管理:
    - 限制并发处理数
    - 分批处理大型项目
    - 后台低优先级处理

索引配置和自定义

配置文件设置

.kiro/indexing.yml 配置

# 索引配置示例
indexing:
  # 包含的文件模式
  include:
    - "src/**/*.{js,ts,jsx,tsx}"
    - "docs/**/*.md"
    - "*.json"
  
  # 排除的文件模式
  exclude:
    - "node_modules/**"
    - "dist/**"
    - "build/**"
    - "*.test.{js,ts}"
  
  # 索引选项
  options:
    deep_analysis: true
    dependency_tracking: true
    documentation_indexing: true
    performance_mode: "balanced"
  
  # 性能设置
  performance:
    max_file_size: "10MB"
    concurrent_files: 4
    batch_size: 100
    cache_duration: "24h"

项目特定配置

不同项目类型的优化

项目类型配置:
  前端项目:
    focus_areas:
      - "src/components/**"
      - "src/pages/**"
      - "src/hooks/**"
    priority_files:
      - "package.json"
      - "tsconfig.json"
  
  后端项目:
    focus_areas:
      - "src/api/**"
      - "src/models/**"
      - "src/services/**"
    priority_files:
      - "go.mod"
      - "requirements.txt"
  
  全栈项目:
    focus_areas:
      - "frontend/src/**"
      - "backend/src/**"
      - "shared/**"
    priority_files:
      - "package.json"
      - "docker-compose.yml"

故障排除

常见索引问题

索引不完整

症状：某些文件或符号未被索引

解决方案：

  1. 检查文件是否在排除列表中
  2. 验证文件格式是否支持
  3. 执行强制重新索引
  4. 检查文件权限和访问性

索引性能缓慢

症状：索引过程耗时过长

优化措施：

性能优化:
  文件级优化:
    - 减少索引文件数量
    - 排除大型文件
    - 使用性能模式
  
  系统级优化:
    - 增加可用内存
    - 使用 SSD 存储
    - 关闭实时扫描软件

索引数据损坏

症状：补全功能异常，导航失效

修复步骤：

  1. 执行 Kiro: Rebuild codebase index
  2. 清理索引缓存
  3. 重启 Kiro
  4. 检查磁盘空间和权限

页面最后更新：2025年7月21日