项目多级索引系统 (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 查看器

📚 命令速查

💡 提示: Claude Code 命令需要前缀 /project-multilevel-index:

📖 命令详细说明

🎯 适用场景

查看 USE_CASES.md 了解 8 个真实应用场景：

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

🗺️ 平台支持

📖 平台详细对比

🏗️ 架构设计

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 行适配代码

平台引用方式

📖 详细说明: 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 - 自由使用、修改和分发

{
  "name": "project-multilevel-index-marketplace",
  "owner": {
    "name": "Claude Code Community",
    "email": "noreply@claudate.dev"
  },
  "metadata": {
    "description": "Official marketplace for Project Multi-level Index plugin - a fractal self-referential documentation system inspired by GEB"
  },
  "plugins": [
    {
      "name": "project-multilevel-index",
      "source": "./",
      "description": "分形多级索引系统 - 受《哥德尔、埃舍尔、巴赫》启发的自指文档系统。自动维护 PROJECT_INDEX、FOLDER_INDEX 和文件头注释,实现代码与文档的完美同步。",
      "version": "1.0.3",
      "category": "documentation",
      "tags": [
        "documentation",
        "index",
        "fractal",
        "self-reference",
        "dependency-graph",
        "mermaid",
        "GEB",
        "architecture",
        "auto-update",
        "i18n"
      ],
      "author": {
        "name": "Claude Code Community",
        "email": "noreply@claudate.dev"
      },
      "homepage": "https://github.com/Claudate/project-multilevel-index#readme",
      "repository": "https://github.com/Claudate/project-multilevel-index",
      "license": "MIT"
    }
  ]
}