project-multilevel-index

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

受《哥德尔、埃舍尔、巴赫》启发的分形自指文档系统

让代码项目如赋格曲般自我指涉、自我维护、优雅和谐

🌐 多平台代码文档自动化系统

CLI工具 + Claude Code插件 + VSCode扩展

简体中文 | English | 📖 文档导航

---

📖 核心理念

三级分形文档系统 - 自动维护项目的索引和依赖关系：

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!

📖 CLI完整文档 | 实现说明

---

方法 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 个真实应用场景：

1. 开源项目文档维护 - 降低贡献门槛
2. 企业级微服务项目 - 架构可视化
3. 个人学习项目 - 记录成长过程
4. 技术债务重构 - 追踪重构进度
5. API 设计评审 - 端点清单一目了然
6. 多团队协作 - 避免重复开发
7. 代码审查辅助 - 快速理解变更影响
8. 技术文档生成 - 自动生成 API 文档

---

🗺️ 平台支持

平台	自动化程度	状态	文档
CLI 工具	手动命令	✅ 已发布	CLI README
Claude Code	完全自动	✅ 已发布	安装指南
VSCode Extension	完全自动	✅ 已发布	用户指南 | User Guide (EN)
规则文件方案	半自动	✅ 可用	Cursor | Windsurf | Kiro

📖 平台详细对比

---

🏗️ 架构设计

V2.0 引用分离架构 - 实现 DRY 原则和平台无关性

┌─────────────────────────────────────────────────┐
│  平台适配层 (Platform Adapters)                 │
│  .kiro/steering/, .cursorrules, .windsurfrules  │
│  职责: 引用或内联核心规则,适配平台特性           │
└─────────────────┬───────────────────────────────┘
                  │ 引用/生成
┌─────────────────▼───────────────────────────────┐
│  核心规则层 (Core Rules)                        │
│  universal/core/rules/doc-maintenance.md        │
│  职责: 单一真实来源,定义所有维护规则             │
└─────────────────┬───────────────────────────────┘
                  │ 调用
┌─────────────────▼───────────────────────────────┐
│  实现层 (Implementation)                        │
│  universal/core/analyzer/ + generator/          │
│  职责: 具体的分析和生成逻辑                       │
└─────────────────────────────────────────────────┘

核心优势

• ✅ 减少 66% 重复代码 - 从 774 行降至 350 行
• ✅ 单一真实来源 - 只需维护一个核心规则文件
• ✅ 自动化同步 - 通过脚本自动生成所有平台配置
• ✅ 新平台支持快 - 只需 20-40 行适配代码

平台引用方式

平台	引用方式	配置文件大小
Kiro	文件引用 #[[file:...]]	30 行
Cursor	核心要点 + 路径引用	40 行
Windsurf	完全内联 (自动生成)	290 行

📖 详细说明: universal/core/rules/README.md

---

📖 文档导航

📚 完整文档索引 - 查看所有分类文档

快速开始

• 安装指南 - 详细的安装步骤
• 快速上手 - 5分钟快速上手
• 使用示例 - 完整的使用示例

核心文档

• 命令参考 - 所有命令的详细说明
• 平台支持 - 各平台对比和选择建议
• 文件头示例 - 10+ 种语言的文件头模板

高级主题

• 国际化指南 - 语言切换和配置
• 使用案例 - 8 个真实应用场景
• 演示脚本 - 完整的演示录制指南

开发者

• 贡献指南 - 如何参与贡献
• CLI 实现说明 - CLI 工具技术细节
• VSCode 扩展计划 - VSCode 扩展技术方案
• 开发路线图 - 整体开发进度

---

📝 文件头注释示例

TypeScript

/**
 * Input: express, bcrypt, ./models/User
 * Output: router, POST /login, POST /register
 * Pos: API层-认证路由，处理用户登录注册
 *
 * 本注释在文件修改时自动更新
 */

Python

"""
Input: flask, sqlalchemy, .models.User
Output: UserController 类, /api/users 路由
Pos: API层-用户控制器，处理用户HTTP请求

本注释在文件修改时自动更新
"""

📖 查看所有语言示例

---

🎬 完整示例项目

我们提供了三个平台的完整示例项目，包含实际代码和配置：

• Cursor 示例 - 完整的 TypeScript 项目
• Windsurf 示例 - Windsurf 配置
• Kiro 示例 - Kiro 配置

每个示例包含：

• ✅ 完整项目结构（Controllers/Services/Models/Utils）
• ✅ 配置好的规则文件
• ✅ 已生成的索引文件
• ✅ 详细使用说明

---

💬 社区与支持

微信交流群

扫描二维码加入微信群，与其他用户交流使用经验：

📖 更多社区资源

GitHub

• 📋 Issues - 报告问题
• 💬 Discussions - 讨论交流
• 🤝 Contributing - 贡献指南

---

🎓 灵感来源

受道格拉斯·霍夫施塔特《哥德尔、埃舍尔、巴赫：集异璧之大成》启发：

• 自指性: 文档指向自己，声明"更新我"
• 递归性: 索引的索引的索引...
• 怪圈: 代码→文档→代码的无限循环
• 分形: 每个层级都是整体的缩影

让代码项目如赋格曲般，自我指涉、自我维护、优雅和谐。 🎼

---

📜 许可证

MIT License - 自由使用、修改和分发

---

开始使用 /project-multilevel-index:init-index，体验分形文档系统的魅力！ 🚀

⬆️ 返回顶部