Skip to content
Back to search

project-multilevel-index

🎼 Fractal self-referential documentation system inspired by GEB. Auto-maintains code indexes, file headers & dependency graphs. Supports Claude Code (full auto) + VSCode/Cursor/Windsurf/Kiro (extension in dev).claude skill

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/claudate--project-multilevel-index/badge.svg)](/listings/claudate--project-multilevel-index)

HTML

<a href="/listings/claudate--project-multilevel-index"><img src="/api/listings/claudate--project-multilevel-index/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 27 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "project-multilevel-index-marketplace",
  3. "owner": {
  4. "name": "Claude Code Community",
  5. "email": "noreply@claudate.dev"
  6. },
  7. "metadata": {
  8. "description": "Official marketplace for Project Multi-level Index plugin - a fractal self-referential documentation system inspired by GEB"
  9. },
  10. "plugins": [
  11. {
  12. "name": "project-multilevel-index",
  13. "source": "./",
  14. "description": "分形多级索引系统 - 受《哥德尔、埃舍尔、巴赫》启发的自指文档系统。自动维护 PROJECT_INDEX、FOLDER_INDEX 和文件头注释,实现代码与文档的完美同步。",
  15. "version": "1.0.3",
  16. "category": "documentation",
  17. "tags": ["documentation", "index", "fractal", "self-reference", "dependency-graph", "mermaid", "GEB", "architecture", "auto-update", "i18n"],
  18. "author": {
  19. "name": "Claude Code Community",
  20. "email": "noreply@claudate.dev"
  21. },
  22. "homepage": "https://github.com/Claudate/project-multilevel-index#readme",
  23. "repository": "https://github.com/Claudate/project-multilevel-index",
  24. "license": "MIT"
  25. }
  26. ]
  27. }
README.md · README · 368 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 项目多级索引系统 (Project Multi-level Index)
  2. <div align="center">
  3. <img src="public/book.jpg" alt="哥德尔、埃舍尔、巴赫" width="300">
  4. > 受《哥德尔、埃舍尔、巴赫》启发的分形自指文档系统
  5. >
  6. > 让代码项目如赋格曲般自我指涉、自我维护、优雅和谐
  7. [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://github.com/Claudate/project-multilevel-index/releases)
  8. [![I18N](https://img.shields.io/badge/i18n-zh--CN%20%7C%20en--US-orange)](docs/development/I18N_GUIDE.md)
  9. [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  10. [![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-purple)](https://claude.ai/code)
  11. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](docs/development/CONTRIBUTING.md)
  12. **🌐 多平台代码文档自动化系统**
  13. CLI工具 + Claude Code插件 + VSCode扩展
  14. [简体中文](#) | [English](README_EN.md) | [📖 文档导航](#-文档导航)
  15. </div>
  16. ---
  17. ## 📖 核心理念
  18. **三级分形文档系统** - 自动维护项目的索引和依赖关系:
  19. ```
  20. PROJECT_INDEX.md (根索引)
  21. ├─ 项目概览、架构说明
  22. ├─ 目录结构导航
  23. └─ Mermaid 依赖关系图
  24. 每个文件夹/
  25. └─ FOLDER_INDEX.md (文件夹索引)
  26. ├─ 架构说明
  27. ├─ 文件清单
  28. └─ "本文件夹变化时,更新我"
  29. 每个文件
  30. └─ 文件头注释
  31. ├─ Input: 依赖什么
  32. ├─ Output: 提供什么
  33. ├─ Pos: 在系统中的定位
  34. └─ "我被更新时,更新我的注释和索引"
  35. ```
  36. ### 三大特性
  37. - **🔄 自相似性**:每个层级都有相同的索引结构
  38. - **🪞 自指性**:每个文档都声明"当我变化时,更新我"
  39. - **🎼 复调性**:代码与文档相互呼应,局部影响整体
  40. ---
  41. ## 🚀 快速开始
  42. ### 方法 1: CLI 工具 `codex`(推荐用于 CI/CD)
  43. **独立命令行工具** - 不依赖任何编辑器:
  44. ```bash
  45. # 1. 克隆并安装
  46. git clone https://github.com/Claudate/project-multilevel-index.git
  47. cd project-multilevel-index/cli
  48. npm install && npm run build && npm link
  49. # 2. 使用
  50. cd /your/project
  51. codex init
  52. ```
  53. **输出示例**:
  54. ```
  55. 🎼 Fractal Multi-level Index System
  56. ✔ Found 45 code files
  57. ✔ Generated 45 file headers
  58. ✔ Generated 8 folder indexes
  59. ✔ Generated PROJECT_INDEX.md
  60. ✅ Index system initialized successfully!
  61. ```
  62. 📖 [CLI完整文档](cli/README.md) | [实现说明](docs/development/CLI_IMPLEMENTATION.md)
  63. ---
  64. ### 方法 2: Claude Code 插件(推荐用于 Claude Code)
  65. **最简单的安装方式**:
  66. ```bash
  67. /plugin marketplace add Claudate/project-multilevel-index
  68. /plugin install project-multilevel-index
  69. ```
  70. **使用**:
  71. ```bash
  72. # 初始化索引
  73. /project-multilevel-index:init-index
  74. # 自动更新(Hook 自动触发,无需手动)
  75. # 修改代码文件后会自动更新索引
  76. ```
  77. 📖 [安装指南](docs/user-guide/INSTALL_GUIDE.md) | [快速上手](docs/user-guide/QUICKSTART.md)
  78. ---
  79. ### 方法 3: VSCode 扩展
  80. **完全自动化方案** - 已发布到 VSCode 市场
  81. **插件名称**: `SwiftScript`
  82. **安装地址**: [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=SwiftScript.project-multilevel-index)
  83. 支持平台:
  84. - ✅ VSCode
  85. - ✅ Cursor
  86. - ✅ Windsurf
  87. - ✅ Kiro
  88. 📖 [中文用户指南](vscode-extension/USER_GUIDE.md) | [English User Guide](vscode-extension/USER_GUIDE_EN.md) | [安装指南](vscode-extension/MANUAL_INSTALL_GUIDE.md)
  89. ---
  90. ## ⭐ 核心功能
  91. ### 🤖 自动化索引
  92. - ✅ **自动扫描**: 递归扫描项目中的所有代码文件
  93. - ✅ **智能分析**: 使用 AST 或正则分析依赖关系
  94. - ✅ **自动生成**: 文件头注释 + 文件夹索引 + 项目索引
  95. - ✅ **自动更新**: 文件修改时自动更新相关索引(Claude Code)
  96. ### 🌍 10+ 编程语言
  97. JavaScript/TypeScript • Python • Java/Kotlin • Rust • Go
  98. C/C++ • PHP • Ruby • Swift • C#
  99. 📖 [文件头示例](docs/user-guide/FILE_HEADERS.md)
  100. ### 📊 可视化依赖
  101. ```mermaid
  102. graph TB
  103. Controllers -->|调用| Services
  104. Services -->|使用| Models
  105. Services -->|使用| Utils
  106. ```
  107. 自动生成 Mermaid 依赖关系图,支持:
  108. - GitHub
  109. - VSCode (Mermaid 扩展)
  110. - Obsidian
  111. - 任何 Markdown 查看器
  112. ---
  113. ## 📚 命令速查
  114. | 命令 | 功能 |
  115. |------|------|
  116. | [`init-index`](docs/user-guide/COMMANDS.md#1-init-index---初始化索引系统) | 初始化索引系统 |
  117. | [`update-index`](docs/user-guide/COMMANDS.md#2-update-index---更新索引) | 手动更新索引 |
  118. | [`check-index`](docs/user-guide/COMMANDS.md#3-check-index---一致性检查) | 一致性检查 |
  119. | [`set-language`](docs/user-guide/COMMANDS.md#4-set-language---切换语言) | 切换语言 |
  120. > **💡 提示**: Claude Code 命令需要前缀 `/project-multilevel-index:`
  121. 📖 [命令详细说明](docs/user-guide/COMMANDS.md)
  122. ---
  123. ## 🎯 适用场景
  124. 查看 **[USE_CASES.md](docs/user-guide/USE_CASES.md)** 了解 8 个真实应用场景:
  125. 1. **开源项目文档维护** - 降低贡献门槛
  126. 2. **企业级微服务项目** - 架构可视化
  127. 3. **个人学习项目** - 记录成长过程
  128. 4. **技术债务重构** - 追踪重构进度
  129. 5. **API 设计评审** - 端点清单一目了然
  130. 6. **多团队协作** - 避免重复开发
  131. 7. **代码审查辅助** - 快速理解变更影响
  132. 8. **技术文档生成** - 自动生成 API 文档
  133. ---
  134. ## 🗺️ 平台支持
  135. | 平台 | 自动化程度 | 状态 | 文档 |
  136. |------|-----------|------|------|
  137. | **CLI 工具** | 手动命令 | ✅ 已发布 | [CLI README](cli/README.md) |
  138. | **Claude Code** | 完全自动 | ✅ 已发布 | [安装指南](docs/user-guide/INSTALL_GUIDE.md) |
  139. | **VSCode Extension** | 完全自动 | ✅ 已发布 | [用户指南](vscode-extension/USER_GUIDE.md) \| [User Guide (EN)](vscode-extension/USER_GUIDE_EN.md) |
  140. | **规则文件方案** | 半自动 | ✅ 可用 | [Cursor](examples/cursor-example/) \| [Windsurf](examples/windsurf-example/) \| [Kiro](examples/kiro-example/) |
  141. 📖 [平台详细对比](docs/user-guide/PLATFORM_SUPPORT.md)
  142. ---
  143. ## 🏗️ 架构设计
  144. **V2.0 引用分离架构** - 实现 DRY 原则和平台无关性
  145. ```
  146. ┌─────────────────────────────────────────────────┐
  147. │ 平台适配层 (Platform Adapters) │
  148. │ .kiro/steering/, .cursorrules, .windsurfrules │
  149. │ 职责: 引用或内联核心规则,适配平台特性 │
  150. └─────────────────┬───────────────────────────────┘
  151. │ 引用/生成
  152. ┌─────────────────▼───────────────────────────────┐
  153. │ 核心规则层 (Core Rules) │
  154. │ universal/core/rules/doc-maintenance.md │
  155. │ 职责: 单一真实来源,定义所有维护规则 │
  156. └─────────────────┬───────────────────────────────┘
  157. │ 调用
  158. ┌─────────────────▼───────────────────────────────┐
  159. │ 实现层 (Implementation) │
  160. │ universal/core/analyzer/ + generator/ │
  161. │ 职责: 具体的分析和生成逻辑 │
  162. └─────────────────────────────────────────────────┘
  163. ```
  164. ### 核心优势
  165. - ✅ **减少 66% 重复代码** - 从 774 行降至 350 行
  166. - ✅ **单一真实来源** - 只需维护一个核心规则文件
  167. - ✅ **自动化同步** - 通过脚本自动生成所有平台配置
  168. - ✅ **新平台支持快** - 只需 20-40 行适配代码
  169. ### 平台引用方式
  170. | 平台 | 引用方式 | 配置文件大小 |
  171. |------|---------|------------|
  172. | **Kiro** | 文件引用 `#[[file:...]]` | 30 行 |
  173. | **Cursor** | 核心要点 + 路径引用 | 40 行 |
  174. | **Windsurf** | 完全内联 (自动生成) | 290 行 |
  175. 📖 详细说明: [universal/core/rules/README.md](universal/core/rules/README.md)
  176. ---
  177. ## 📖 文档导航
  178. 📚 **[完整文档索引](docs/README.md)** - 查看所有分类文档
  179. ### 快速开始
  180. - [安装指南](docs/user-guide/INSTALL_GUIDE.md) - 详细的安装步骤
  181. - [快速上手](docs/user-guide/QUICKSTART.md) - 5分钟快速上手
  182. - [使用示例](docs/user-guide/EXAMPLES.md) - 完整的使用示例
  183. ### 核心文档
  184. - [命令参考](docs/user-guide/COMMANDS.md) - 所有命令的详细说明
  185. - [平台支持](docs/user-guide/PLATFORM_SUPPORT.md) - 各平台对比和选择建议
  186. - [文件头示例](docs/user-guide/FILE_HEADERS.md) - 10+ 种语言的文件头模板
  187. ### 高级主题
  188. - [国际化指南](docs/development/I18N_GUIDE.md) - 语言切换和配置
  189. - [使用案例](docs/user-guide/USE_CASES.md) - 8 个真实应用场景
  190. - [演示脚本](docs/planning/DEMO_SCRIPT.md) - 完整的演示录制指南
  191. ### 开发者
  192. - [贡献指南](docs/development/CONTRIBUTING.md) - 如何参与贡献
  193. - [CLI 实现说明](docs/development/CLI_IMPLEMENTATION.md) - CLI 工具技术细节
  194. - [VSCode 扩展计划](docs/development/VSCODE_EXTENSION_PLAN.md) - VSCode 扩展技术方案
  195. - [开发路线图](docs/development/IMPLEMENTATION_ROADMAP.md) - 整体开发进度
  196. ---
  197. ## 📝 文件头注释示例
  198. ### TypeScript
  199. ```typescript
  200. /**
  201. * Input: express, bcrypt, ./models/User
  202. * Output: router, POST /login, POST /register
  203. * Pos: API层-认证路由,处理用户登录注册
  204. *
  205. * 本注释在文件修改时自动更新
  206. */
  207. ```
  208. ### Python
  209. ```python
  210. """
  211. Input: flask, sqlalchemy, .models.User
  212. Output: UserController 类, /api/users 路由
  213. Pos: API层-用户控制器,处理用户HTTP请求
  214. 本注释在文件修改时自动更新
  215. """
  216. ```
  217. 📖 [查看所有语言示例](docs/user-guide/FILE_HEADERS.md)
  218. ---
  219. ## 🎬 完整示例项目
  220. 我们提供了三个平台的完整示例项目,包含实际代码和配置:
  221. - **[Cursor 示例](examples/cursor-example/)** - 完整的 TypeScript 项目
  222. - **[Windsurf 示例](examples/windsurf-example/)** - Windsurf 配置
  223. - **[Kiro 示例](examples/kiro-example/)** - Kiro 配置
  224. 每个示例包含:
  225. - ✅ 完整项目结构(Controllers/Services/Models/Utils)
  226. - ✅ 配置好的规则文件
  227. - ✅ 已生成的索引文件
  228. - ✅ 详细使用说明
  229. ---
  230. ## 💬 社区与支持
  231. ### 微信交流群
  232. 扫描二维码加入微信群,与其他用户交流使用经验:
  233. <div align="center">
  234. <img src="public/wechat-group-qrcode.png" width="200" alt="微信群二维码" />
  235. </div>
  236. 📖 [更多社区资源](docs/COMMUNITY.md)
  237. ### GitHub
  238. - 📋 [Issues](https://github.com/Claudate/project-multilevel-index/issues) - 报告问题
  239. - 💬 [Discussions](https://github.com/Claudate/project-multilevel-index/discussions) - 讨论交流
  240. - 🤝 [Contributing](docs/development/CONTRIBUTING.md) - 贡献指南
  241. ---
  242. ## 🎓 灵感来源
  243. 受道格拉斯·霍夫施塔特《哥德尔、埃舍尔、巴赫:集异璧之大成》启发:
  244. - **自指性**: 文档指向自己,声明"更新我"
  245. - **递归性**: 索引的索引的索引...
  246. - **怪圈**: 代码→文档→代码的无限循环
  247. - **分形**: 每个层级都是整体的缩影
  248. **让代码项目如赋格曲般,自我指涉、自我维护、优雅和谐。** 🎼
  249. ---
  250. ## 📜 许可证
  251. MIT License - 自由使用、修改和分发
  252. ---
  253. <div align="center">
  254. **开始使用 `/project-multilevel-index:init-index`,体验分形文档系统的魅力!** 🚀
  255. [⬆️ 返回顶部](#项目多级索引系统-project-multi-level-index)
  256. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.