项目多级索引系统 (Project Multi-level Index)
受《哥德尔、埃舍尔、巴赫》启发的分形自指文档系统
让代码项目如赋格曲般自我指涉、自我维护、优雅和谐
🌐 多平台代码文档自动化系统
CLI工具 + Claude Code插件 + VSCode扩展
📖 核心理念
三级分形文档系统 - 自动维护项目的索引和依赖关系：
PROJECT_INDEX.md (根索引)
├─ 项目概览、架构说明
├─ 目录结构导航
└─ Mermaid 依赖关系图
每个文件夹/
└─ FOLDER_INDEX.md (文件夹索引)
├─ 架构说明
├─ 文件清单
└─ "本文件夹变化时，更新我"
每个文件
└─ 文件头注释
├─ Input: 依赖什么
├─ Output: 提供什么
├─ Pos: 在系统中的定位
└─ "我被更新时，更新我的注释和索引"
三大特性
- 🔄 自相似性：每个层级都有相同的索引结构
- 🪞 自指性：每个文档都声明"当我变化时，更新我"
- 🎼 复调性：代码与文档相互呼应，局部影响整体
🚀 快速开始
方法 1: CLI 工具 codex（推荐用于 CI/CD）
独立命令行工具 - 不依赖任何编辑器：
# 1. 克隆并安装
git clone https://github.com/Claudate/project-multilevel-index.git
cd project-multilevel-index/cli
npm install && npm run build && npm link
# 2. 使用
cd /your/project
codex init
输出示例:
🎼 Fractal Multi-level Index System
✔ Found 45 code files
✔ Generated 45 file headers
✔ Generated 8 folder indexes
✔ Generated PROJECT_INDEX.md
✅ Index system initialized successfully!
方法 2: Claude Code 插件（推荐用于 Claude Code）
最简单的安装方式：
/plugin marketplace add Claudate/project-multilevel-index
/plugin install project-multilevel-index
使用：
# 初始化索引
/project-multilevel-index:init-index
# 自动更新（Hook 自动触发，无需手动）
# 修改代码文件后会自动更新索引
方法 3: VSCode 扩展
完全自动化方案 - 已发布到 VSCode 市场
插件名称: SwiftScript
安装地址: VSCode Marketplace
支持平台：
- ✅ VSCode
- ✅ Cursor
- ✅ Windsurf
- ✅ Kiro
📖 中文用户指南 | English User Guide | 安装指南
⭐ 核心功能
🤖 自动化索引
- ✅ 自动扫描: 递归扫描项目中的所有代码文件
- ✅ 智能分析: 使用 AST 或正则分析依赖关系
- ✅ 自动生成: 文件头注释 + 文件夹索引 + 项目索引
- ✅ 自动更新: 文件修改时自动更新相关索引（Claude Code）
🌍 10+ 编程语言
JavaScript/TypeScript • Python • Java/Kotlin • Rust • Go C/C++ • PHP • Ruby • Swift • C#
📖 文件头示例
📊 可视化依赖
graph TB
Controllers -->|调用| Services
Services -->|使用| Models
Services -->|使用| Utils
自动生成 Mermaid 依赖关系图，支持：
- GitHub
- VSCode (Mermaid 扩展)
- Obsidian
- 任何 Markdown 查看器
📚 命令速查
| 命令 | 功能 |
|---|---|
init-index | 初始化索引系统 |
update-index | 手动更新索引 |
check-index | 一致性检查 |
set-language | 切换语言 |
💡 提示: Claude Code 命令需要前缀
/project-multilevel-index:
📖 命令详细说明
🎯 适用场景
查看 USE_CASES.md 了解 8 个真实应用场景：
- 开源项目文档维护 - 降低贡献门槛
- 企业级微服务项目 - 架构可视化
- 个人学习项目 - 记录成长过程
- 技术债务重构 - 追踪重构进度
- API 设计评审 - 端点清单一目了然
- 多团队协作 - 避免重复开发
- 代码审查辅助 - 快速理解变更影响
- 技术文档生成 - 自动生成 API 文档
🗺️ 平台支持
| 平台 | 自动化程度 | 状态 | 文档 |
|---|---|---|---|
| CLI 工具 | 手动命令 | ✅ 已发布 | CLI README |
| Claude Code | 完全自动 | ✅ 已发布 | 安装指南 |
| VSCode Extension | 完全自动 | ✅ 已发布 | 用户指南 | User Guide (EN) |
| 规则文件方案 | 半自动 | ✅ 可用 | Cursor | Windsurf | Kiro |
📖 平台详细对比
🏗️ 架构设计
V2.0 引用分离架构 - 实现 DRY 原则和平台无关性