
project-multilevel-index
分形多级索引系统 - 受《哥德尔、埃舍尔、巴赫》启发的自指文档系统。自动维护 PROJECT_INDEX、FOLDER_INDEX 和文件头注释,实现代码与文档的完美同步。
- version
- 1.0.3
- GitHub stars
- 140
Install
/plugin install project-multilevel-index@project-multilevel-index-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add Claudate/project-multilevel-index.
Contents
Discovered from sourceSkills 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 插件 (当前模式)
- 核心概念: core/concepts.md
- 国际化: core/i18n.md
- 命令实现:
- /init-index - 初始化索引系统
- /update-index - 更新索引
- /check-index - 一致性检查
- /set-language - 切换语言
Universal 通用核心
- 平台接口: ../../universal/core/platform-interface.md
- 分析器: ../../universal/core/analyzer/
- dependency-parser.md - 依赖分析
- export-parser.md - 导出分析
- position-inferrer.md - 位置推断
- 生成器: ../../universal/core/generator/
- init-workflow.md - 初始化工作流
- update-workflow.md - 更新工作流
- check-workflow.md - 检查工作流
- 适配器: ../../universal/adapters/
- claude-code/adapter.md - Claude Code 适配器
🚀 执行流程
通用流程(所有命令)
-
加载语言配置(必须)
- 详见 core/i18n.md
- 读取
.claude/locale-config.json - 加载对应语言文件到
LANG对象
-
初始化 Claude Code 适配器
- 加载
universal/adapters/claude-code/adapter.md - 适配器提供平台特定的文件操作方法
- 加载
-
调用 Universal 核心工作流
- 传入适配器实例和语言配置
- 执行平台无关的核心逻辑
-
输出结果
- 使用
LANG对象中的翻译文本 - 替换占位符(如
{directory},{count})
- 使用
命令概览
/init-index - 初始化索引系统
使用场景: 首次运行或重建整个索引系统
执行步骤:
- 加载语言配置
- 初始化 Claude Code 适配器
- 调用
universal/core/generator/init-workflow.md - 适配器使用 Read/Write/Edit 工具执行文件操作
- 输出总结报告
详细实现: commands_impl/init-index.md
核心工作流: ../../universal/core/generator/init-workflow.md
/update-index - 更新索引
使用场景: 文件修改后手动更新或 Hook 自动调用
执行步骤:
- 加载语言配置
- 初始化 Claude Code 适配器
- 调用
universal/core/generator/update-workflow.md - 传入变更文件列表
- 适配器执行增量更新
- 报告更新结果
详细实现: commands_impl/update-index.md
核心工作流: ../../universal/core/generator/update-workflow.md
/check-index - 一致性检查
使用场景: 验证索引系统完整性
执行步骤:
- 加载语言配置
- 初始化 Claude Code 适配器
- 调用
universal/core/generator/check-workflow.md - 适配器执行完整性检查
- 生成检查报告
详细实现: commands_impl/check-index.md
核心工作流: ../../universal/core/generator/check-workflow.md
/set-language - 切换语言
使用场景: 快速切换界面语言
执行步骤:
- 询问用户选择语言(zh-CN / en-US)
- 创建或更新
.claude/locale-config.json - 验证语言文件存在
- 确认切换成功
详细实现: commands_impl/set-language.md
🔧 PostToolUse Hook 自动更新
当检测到文件修改(Write/Edit)时:
-
加载语言配置
-
应用过滤规则(详见
locales/{language}/hooks.json)- 跳过索引文件自身
- 跳过非代码文件
- 跳过大文件(>500KB)
- 跳过排除目录
-
判断是否为结构性变更
- 检查是否包含依赖关键字(import, require, use...)
- 检查是否包含导出关键字(export, public, class...)
-
执行更新
- 结构性变更 → 调用
/update-index - 仅文件头变更 → 只更新文件头
- 其他 → 跳过
- 结构性变更 → 调用
-
静默处理
- 小改动:不提示
- 重大变更:输出一行信息
🌍 多语言支持
支持的语言
- zh-CN: 简体中文(默认)
- en-US: 美国英语
切换方式
-
配置文件方式(推荐)
# 创建配置文件 mkdir -p .claude cat > .claude/locale-config.json << 'EOF' { "language": "en-US", "fallback": "zh-CN" } EOF -
命令方式
/set-language -
环境变量方式
export CLAUDE_LOCALE=en-US -
初始化时询问
/init-index会询问用户选择语言
技术术语
以下术语在所有语言中保持英文:
- Input, Output, Pos
- PROJECT_INDEX, FOLDER_INDEX
- SKILL.md
📖 扩展阅读
- 核心概念详解: core/concepts.md
- 国际化实现: core/i18n.md
- 语言文件:
locales/zh-CN/和locales/en-US/ - 文件模板:
templates/
🎯 设计原则
- 避免过度更新: 只在真正的结构性变化时更新索引
- 保护用户内容: 更新时保留用户手动添加的注释
- 清晰的反馈: 重要操作有明确提示
- 性能优先: 大型项目使用增量更新
- 易于理解: 文档清晰,示例丰富
- 防止循环: 索引文件修改时不触发更新
- 国际化: 支持多语言界面
- 用户至上: 不确定的操作先询问用户
🔗 相关文档
- Universal 核心文档: ../../universal/
- 适配器开发指南: ../../universal/adapters/README.md
- 平台对比: ../../universal/.kiro/specs/platforms.yml
版本: 2.1.0 更新日期: 2025-12-23 新特性: 双模式架构 + Universal 多平台核心 + 适配器系统
Commands 3
/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: 检查索引"流程执行。
/init-index - 初始化索引系统
初始化项目的多级索引系统,为整个代码库建立分形文档结构。
📌 当前版本 (v1.0): 基本功能已实现,高级参数将在 v2.0 实现
当前支持:基本初始化流程 计划中 (v2.0):
--force,--lang,--max-depth,--dry-run,--exclude,--include-tests等参数
功能说明
这将执行以下操作:
- 扫描项目结构 - 识别所有代码文件(支持 10 种语言)
- 生成文件头注释 - 为每个文件添加 Input/Output/Pos 注释
- 创建文件夹索引 - 在每个代码文件夹生成 FOLDER_INDEX.md
- 生成根索引 - 创建 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)
执行流程
- 确认项目根目录 - 询问用户确认当前目录
- 扫描代码文件 - 使用 Glob 工具快速扫描
- 分析依赖关系 - 解析每个文件的 import/export
- 生成文件头 - 智能插入或更新注释(保留用户自定义内容)
- 创建索引文件 - 从叶子文件夹到根目录逐级生成
- 生成依赖图 - 创建 Mermaid 可视化图表
- 输出报告 - 显示处理统计和后续建议
示例输出
✅ 索引系统初始化完成!
已生成:
- 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等参数
功能说明
这将执行以下操作:
- 检测文件变更 - 识别自上次更新以来的代码变化
- 重新分析依赖 - 解析变更文件的 import/export 关系
- 更新文件头 - 刷新受影响文件的 Input/Output 注释
- 更新文件夹索引 - 同步 FOLDER_INDEX.md
- 刷新根索引 - 必要时重新生成 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: 更新索引"流程执行。
Hooks 2
Sponsors
Details
- Marketplace
- Claudate/project-multilevel-index
- Author
- Claude Code Community
- Category
- Documentation
- License
- MIT