/check-index

description: 检查项目索引系统的完整性和一致性

/check-index - 检查索引一致性

运行全面的索引系统健康检查，验证文档与代码的同步状态。

> **📌 当前版本 (v1.0)**: 基本检查功能已实现，高级参数将在 v2.0 实现 > > 当前支持：文件头完整性、文件夹索引、依赖关系、结构规范性检查 > 计划中 (v2.0)：`--fix`, `--report`, `--deep`, `--strict`, `--save` 等参数

功能说明

这将验证以下内容： 1. **文件头完整性** - 检查所有代码文件是否有 Input/Output/Pos 注释 2. **文件夹索引完整性** - 验证每个代码文件夹是否有 FOLDER_INDEX.md 3. **内容一致性** - 确认索引内容与实际文件匹配 4. **依赖关系验证** - 检测循环依赖和无效引用 5. **结构规范性** - 验证文档格式是否符合标准

使用方法

基本用法

/check-index

带参数用法

/check-index --fix              # 自动修复发现的问题
/check-index --report json      # 输出 JSON 格式报告
/check-index --deep             # 深度检查（包括语法验证）

参数说明

| 参数 | 说明 | 默认值 | 示例 | |------|------|--------|------| | `--fix` | 自动修复发现的问题 | false | `--fix` | | `--report <format>` | 报告格式 (text/json/md) | text | `--report json` | | `--deep` | 深度检查（验证代码语法） | false | `--deep` | | `--strict` | 严格模式（任何问题都报错） | false | `--strict` | | `--save` | 保存报告到文件 | false | `--save` |

检查项目

1. 文件头完整性检查

验证每个代码文件是否包含必需的注释块：

检查项:
  ✓ 是否有文件头注释
  ✓ Input 字段是否存在
  ✓ Output 字段是否存在
  ✓ Pos 字段是否存在
  ✓ Input 内容是否与实际 import 匹配
  ✓ Output 内容是否与实际 export 匹配

2. 文件夹索引检查

验证每个包含代码的文件夹：

检查项:
  ✓ 是否有 FOLDER_INDEX.md
  ✓ 索引中列出的文件是否都存在
  ✓ 是否有文件未被索引
  ✓ 架构说明是否清晰（3 行规则）
  ✓ 自指声明是否存在

3. 依赖关系检查

分析项目的依赖结构：

检查项:
  ✓ 检测循环依赖 (A→B→C→A)
  ✓ 验证依赖的文件是否存在
  ✓ 识别孤立模块（无依赖、无被依赖）
  ✓ 检测过度耦合（单个模块被 10+ 模块依赖）
  ✓ 验证第三方依赖是否已安装

4. 结构规范性检查

确保文档格式统一：

检查项:
  ✓ Markdown 语法是否正确
  ✓ Mermaid 图是否可渲染
  ✓ 文件头注释格式是否符合语言规范
  ✓ 链接是否有效

示例输出

完整通过

索引一致性检查报告
==================

✅ 文件头完整性: 57/57 (100%)
✅ 文件夹索引: 8/8 全部正常
✅ 依赖关系: 无循环依赖，无孤立模块
✅ 结构规范性: 符合标准

🎉 索引系统运行完美！

发现问题

索引一致性检查报告
==================

⚠️ 文件头完整性: 55/57 (96.5%)
  缺少文件头注释:
    - src/utils/legacy.js
    - src/temp/test.ts

  Input/Output 不匹配:
    - src/services/auth.ts
      实际 import: bcrypt, ./models/User
      文件头 Input: ./models/User (缺少 bcrypt)

✅ 文件夹索引: 8/8 全部正常

⚠️ 依赖关系: 发现 1 个循环依赖
  - src/a.ts → src/b.ts → src/c.ts → src/a.ts
  建议: 提取共享逻辑到新模块

  孤立模块:
    - src/utils/unused.ts (无依赖、无被依赖)
  建议: 考虑删除或集成到系统中

✅ 结构规范性: 符合标准

修复建议:
1. 运行 /update-index 补充缺失的文件头注释
2. 手动重构循环依赖
3. 检查孤立模块是否仍需要

JSON 格式报告

{
  "timestamp": "2025-12-22T10:30:00Z",
  "summary": {
    "passed": false,
    "score": 92.5,
    "issues": 4
  },
  "fileHeaders": {
    "total": 57,
    "valid": 55,
    "missing": ["src/utils/legacy.js", "src/temp/test.ts"]
  },
  "dependencies": {
    "circular": [
      ["src/a.ts", "src/b.ts", "src/c.ts", "src/a.ts"]
    ],
    "orphaned": ["src/utils/unused.ts"]
  }
}

自动修复功能

使用 `--fix` 参数可自动修复以下问题：

可自动修复:
  ✓ 缺失的文件头注释 → 自动生成
  ✓ Input/Output 不匹配 → 重新分析并更新
  ✓ 缺失的 FOLDER_INDEX.md → 自动创建
  ✓ 索引中的无效链接 → 移除或更正

需手动修复:
  ✗ 循环依赖 → 需要重构代码
  ✗ 语法错误 → 需要修复代码
  ✗ 孤立模块 → 需要架构决策

使用场景

场景 1: 日常健康检查

# 每周运行一次
/check-index

场景 2: 提交前验证

# 确保索引同步
/check-index --strict

场景 3: 重构后验证

# 重构完成后
/check-index --deep

场景 4: 生成报告

# 生成报告供团队审查
/check-index --report md --save

集成到 CI/CD

可在 CI 流程中运行检查：

# 在 GitHub Actions 中
- name: Check Index
  run: claude /check-index --strict --report json

注意事项

• ✅ 检查不会修改任何文件（除非使用 `--fix`）
• ✅ 可安全地在生产代码库运行
• ⚠️ 深度检查可能耗时较长（大型项目 5+ 分钟）
• ⚠️ 循环依赖需要手动重构代码

性能指标

| 项目规模 | 基本检查 | 深度检查 | |---------|---------|---------| | 小型 (<100 文件) | <5 秒 | <15 秒 | | 中型 (100-500) | <15 秒 | <1 分钟 | | 大型 (500-1000) | <30 秒 | <3 分钟 | | 超大型 (1000+) | <1 分钟 | <5 分钟 |

---

遵循 `skills/project-multilevel-index/SKILL.md` 中的"命令 3: 检查索引"流程执行。