Claudate avatar

project-multilevel-index

分形多级索引系统 - 受《哥德尔、埃舍尔、巴赫》启发的自指文档系统。自动维护 PROJECT_INDEX、FOLDER_INDEX 和文件头注释,实现代码与文档的完美同步。

version
1.0.3
GitHub stars
140

Install

/plugin install project-multilevel-index@project-multilevel-index-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Claudate/project-multilevel-index.

Contents

Discovered from source

Skills 1

项目多级索引系统 (Project Multi-level Index)

🏗️ 架构说明

本技能现在采用 双模式架构:

1. Claude Code 插件模式 (当前)

  • 位置: skills/project-multilevel-index/
  • 用途: Claude Code CLI 专属,通过插件系统使用
  • 特性: Hooks 自动触发、插件市场分发

2. Universal 通用模式 (多平台)

  • 位置: universal/
  • 用途: 支持 Claude Code、Cursor、Kiro、Windsurf 等多平台
  • 特性: 平台无关的核心逻辑、适配器架构

关系: 插件模式内部调用 universal/core/ 的通用逻辑,两者共享核心引擎。


📚 快速导航

Claude Code 插件 (当前模式)

Universal 通用核心


🚀 执行流程

通用流程(所有命令)

  1. 加载语言配置(必须)

    • 详见 core/i18n.md
    • 读取 .claude/locale-config.json
    • 加载对应语言文件到 LANG 对象
  2. 初始化 Claude Code 适配器

    • 加载 universal/adapters/claude-code/adapter.md
    • 适配器提供平台特定的文件操作方法
  3. 调用 Universal 核心工作流

    • 传入适配器实例和语言配置
    • 执行平台无关的核心逻辑
  4. 输出结果

    • 使用 LANG 对象中的翻译文本
    • 替换占位符(如 {directory}, {count})

命令概览

/init-index - 初始化索引系统

使用场景: 首次运行或重建整个索引系统

执行步骤:

  1. 加载语言配置
  2. 初始化 Claude Code 适配器
  3. 调用 universal/core/generator/init-workflow.md
  4. 适配器使用 Read/Write/Edit 工具执行文件操作
  5. 输出总结报告

详细实现: commands_impl/init-index.md

核心工作流: ../../universal/core/generator/init-workflow.md


/update-index - 更新索引

使用场景: 文件修改后手动更新或 Hook 自动调用

执行步骤:

  1. 加载语言配置
  2. 初始化 Claude Code 适配器
  3. 调用 universal/core/generator/update-workflow.md
  4. 传入变更文件列表
  5. 适配器执行增量更新
  6. 报告更新结果

详细实现: commands_impl/update-index.md

核心工作流: ../../universal/core/generator/update-workflow.md


/check-index - 一致性检查

使用场景: 验证索引系统完整性

执行步骤:

  1. 加载语言配置
  2. 初始化 Claude Code 适配器
  3. 调用 universal/core/generator/check-workflow.md
  4. 适配器执行完整性检查
  5. 生成检查报告

详细实现: commands_impl/check-index.md

核心工作流: ../../universal/core/generator/check-workflow.md


/set-language - 切换语言

使用场景: 快速切换界面语言

执行步骤:

  1. 询问用户选择语言(zh-CN / en-US)
  2. 创建或更新 .claude/locale-config.json
  3. 验证语言文件存在
  4. 确认切换成功

详细实现: commands_impl/set-language.md


🔧 PostToolUse Hook 自动更新

当检测到文件修改(Write/Edit)时:

  1. 加载语言配置

  2. 应用过滤规则(详见 locales/{language}/hooks.json)

    • 跳过索引文件自身
    • 跳过非代码文件
    • 跳过大文件(>500KB)
    • 跳过排除目录
  3. 判断是否为结构性变更

    • 检查是否包含依赖关键字(import, require, use...)
    • 检查是否包含导出关键字(export, public, class...)
  4. 执行更新

    • 结构性变更 → 调用 /update-index
    • 仅文件头变更 → 只更新文件头
    • 其他 → 跳过
  5. 静默处理

    • 小改动:不提示
    • 重大变更:输出一行信息

🌍 多语言支持

支持的语言

  • zh-CN: 简体中文(默认)
  • en-US: 美国英语

切换方式

  1. 配置文件方式(推荐)

    # 创建配置文件
    mkdir -p .claude
    cat > .claude/locale-config.json << 'EOF'
    {
      "language": "en-US",
      "fallback": "zh-CN"
    }
    EOF
    
  2. 命令方式

    /set-language
    
  3. 环境变量方式

    export CLAUDE_LOCALE=en-US
    
  4. 初始化时询问

    • /init-index 会询问用户选择语言

技术术语

以下术语在所有语言中保持英文:

  • Input, Output, Pos
  • PROJECT_INDEX, FOLDER_INDEX
  • SKILL.md

📖 扩展阅读

  • 核心概念详解: core/concepts.md
  • 国际化实现: core/i18n.md
  • 语言文件: locales/zh-CN/ 和 locales/en-US/
  • 文件模板: templates/

🎯 设计原则

  1. 避免过度更新: 只在真正的结构性变化时更新索引
  2. 保护用户内容: 更新时保留用户手动添加的注释
  3. 清晰的反馈: 重要操作有明确提示
  4. 性能优先: 大型项目使用增量更新
  5. 易于理解: 文档清晰,示例丰富
  6. 防止循环: 索引文件修改时不触发更新
  7. 国际化: 支持多语言界面
  8. 用户至上: 不确定的操作先询问用户

🔗 相关文档


版本: 2.1.0 更新日期: 2025-12-23 新特性: 双模式架构 + Universal 多平台核心 + 适配器系统

Commands 3

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

/init-index - 初始化索引系统

初始化项目的多级索引系统,为整个代码库建立分形文档结构。

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

当前支持:基本初始化流程 计划中 (v2.0):--force, --lang, --max-depth, --dry-run, --exclude, --include-tests 等参数

功能说明

这将执行以下操作:

  1. 扫描项目结构 - 识别所有代码文件(支持 10 种语言)
  2. 生成文件头注释 - 为每个文件添加 Input/Output/Pos 注释
  3. 创建文件夹索引 - 在每个代码文件夹生成 FOLDER_INDEX.md
  4. 生成根索引 - 创建 PROJECT_INDEX.md 和 Mermaid 依赖关系图

使用方法

基本用法

/init-index

带参数用法

/init-index --force              # 强制覆盖现有索引
/init-index --lang ts,py         # 仅处理 TypeScript 和 Python
/init-index --max-depth 3        # 限制目录深度为 3 层
/init-index --dry-run            # 预览将生成的内容,不实际写入

参数说明

参数说明默认值示例
--force强制覆盖现有的索引文件false--force
--lang <languages>限定处理的语言(逗号分隔)全部--lang js,ts,py
--max-depth <number>限制扫描的目录深度无限制--max-depth 5
--dry-run预览模式,不实际写入文件false--dry-run
--exclude <patterns>额外的排除模式见配置--exclude "test/**,docs/**"
--include-tests包含测试文件false--include-tests

支持的语言

  • JavaScript/TypeScript (.js, .jsx, .ts, .tsx)
  • Python (.py)
  • Java/Kotlin (.java, .kt)
  • Rust (.rs)
  • Go (.go)
  • C/C++ (.c, .cpp, .h, .hpp)
  • PHP (.php)
  • Ruby (.rb)
  • Swift (.swift)
  • C# (.cs)

执行流程

  1. 确认项目根目录 - 询问用户确认当前目录
  2. 扫描代码文件 - 使用 Glob 工具快速扫描
  3. 分析依赖关系 - 解析每个文件的 import/export
  4. 生成文件头 - 智能插入或更新注释(保留用户自定义内容)
  5. 创建索引文件 - 从叶子文件夹到根目录逐级生成
  6. 生成依赖图 - 创建 Mermaid 可视化图表
  7. 输出报告 - 显示处理统计和后续建议

示例输出

✅ 索引系统初始化完成!

已生成:
- 57 个文件头注释
- 8 个 FOLDER_INDEX.md
- 1 个 PROJECT_INDEX.md
- 依赖关系图包含 25 个节点、38 条边

下一步:
- 查看 PROJECT_INDEX.md 了解整体架构
- 使用 /update-index 手动更新索引
- 使用 /check-index 检查一致性

注意事项

  • ⚠️ 如果文件已有头注释,将智能合并而非覆盖
  • ⚠️ 建议在初始化前提交当前代码到 Git
  • ⚠️ 大型项目(1000+ 文件)可能需要数分钟
  • ⚠️ 使用 --dry-run 可以先预览效果

故障排除

问题: 初始化卡住不动 解决: 可能遇到大文件,使用 --exclude 排除大文件目录

问题: 某些文件的依赖分析不准确 解决: 检查文件语法是否正确,或手动调整文件头注释

问题: 想重新生成所有索引 解决: 使用 --force 参数强制覆盖


遵循 skills/project-multilevel-index/SKILL.md 中的"命令 1: 初始化索引"流程执行。

/update-index - 更新索引

手动触发项目索引的增量或全量更新。

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

当前支持:自动检测变更并更新索引 计划中 (v2.0):--full, --file, --folder, --skip-deps, --verbose 等参数

功能说明

这将执行以下操作:

  1. 检测文件变更 - 识别自上次更新以来的代码变化
  2. 重新分析依赖 - 解析变更文件的 import/export 关系
  3. 更新文件头 - 刷新受影响文件的 Input/Output 注释
  4. 更新文件夹索引 - 同步 FOLDER_INDEX.md
  5. 刷新根索引 - 必要时重新生成 PROJECT_INDEX.md 和依赖图

使用方法

基本用法(增量更新)

/update-index

自动检测变更并仅更新受影响的文件。

全量更新

/update-index --full

重新扫描整个项目,等同于 /init-index --force。

指定文件更新

/update-index src/services/auth.ts
/update-index src/models/**/*.py

参数说明

参数说明默认值示例
--full全量更新整个项目false--full
--file <path>仅更新指定文件全部变更--file src/user.ts
--folder <path>仅更新指定文件夹全部变更--folder src/models
--skip-deps跳过依赖图重新生成false--skip-deps
--verbose显示详细处理日志false--verbose

更新策略

智能检测变更类型

变更内容变更类型更新范围
新增/删除文件Structural文件夹索引 + 根索引
Import 语句变化Structural文件头 + 文件夹索引 + 根索引
Export 声明变化Structural文件头 + 文件夹索引
函数签名改变Signature文件头 + 文件夹索引
仅文件头注释修改Header仅文件头
函数内部实现Implementation不更新

批量优化

如果短时间内多个文件变更:

  • 收集所有变更,批量处理
  • 每个文件夹的 FOLDER_INDEX 只更新一次
  • PROJECT_INDEX 仅在最后更新一次

示例输出

增量更新

检测到 3 个文件变更:
  ✓ src/services/auth.ts (新增 import bcrypt)
  ✓ src/models/User.ts (修改 export)
  ✓ src/utils/validator.ts (仅内部实现)

已更新:
  - 2 个文件头注释
  - 2 个 FOLDER_INDEX.md
  - 1 个 PROJECT_INDEX.md (更新依赖图)

耗时: 1.2 秒

全量更新

正在全量扫描项目...
发现 57 个代码文件

已更新:
  - 57 个文件头注释
  - 8 个 FOLDER_INDEX.md
  - 1 个 PROJECT_INDEX.md

耗时: 8.5 秒

使用场景

场景 1: 日常开发后同步

# 修改了几个文件后
/update-index

场景 2: 大规模重构后

# 重构了整个模块
/update-index --full

场景 3: 仅更新特定模块

# 只想更新某个文件夹
/update-index --folder src/auth

场景 4: 验证单个文件

# 检查某个文件的依赖是否正确
/update-index --file src/index.ts --verbose

注意事项

  • ✅ 更新会保留用户手动添加的注释
  • ✅ 仅在确实有变化时才写入文件
  • ✅ 自动跳过索引文件本身(防止循环)
  • ⚠️ 全量更新可能需要较长时间

与 Hook 自动更新的区别

特性Hook 自动更新手动 /update-index
触发方式文件修改后自动用户手动执行
处理范围单个文件可指定范围
输出详情简短提示详细报告
性能快速较慢(全面扫描)
适用场景日常编码重构、验证

遵循 skills/project-multilevel-index/SKILL.md 中的"命令 2: 更新索引"流程执行。

Sponsors

Details

Marketplace
Claudate/project-multilevel-index
Author
Claude Code Community
Category
Documentation
License
MIT