项目多级索引系统 (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: 美国英语

切换方式

•

配置文件方式（推荐）

bash

# 创建配置文件
mkdir -p .claude
cat > .claude/locale-config.json << 'EOF'
{
  "language": "en-US",
  "fallback": "zh-CN"
}
EOF

•
命令方式
code
```
/set-language
```
•
环境变量方式
bash
```
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 多平台核心 + 适配器系统

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

🏗️ 架构说明

1. Claude Code 插件模式 (当前)

2. Universal 通用模式 (多平台)

📚 快速导航

Claude Code 插件 (当前模式)

Universal 通用核心

🚀 执行流程

通用流程（所有命令）

命令概览

/init-index - 初始化索引系统

/update-index - 更新索引

/check-index - 一致性检查

/set-language - 切换语言

🔧 PostToolUse Hook 自动更新

🌍 多语言支持

支持的语言

切换方式

技术术语

📖 扩展阅读

🎯 设计原则

🔗 相关文档

`/init-index` - 初始化索引系统

`/update-index` - 更新索引

`/check-index` - 一致性检查

`/set-language` - 切换语言