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

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

📌 当前版本 (v1.0): 基本检查功能已实现，高级参数将在 v2.0 实现

当前支持：文件头完整性、文件夹索引、依赖关系、结构规范性检查计划中 (v2.0)：--fix, --report, --deep, --strict, --save 等参数

功能说明

这将验证以下内容：

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

使用方法

基本用法

/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: 检查索引"流程执行。