Unnamed Skill

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

🚀 执行流程

通用流程（所有命令）

1. 加载语言配置（必须）

   • 详见 core/i18n.md
   • 读取 .claude/locale-config.json
   • 加载对应语言文件到 LANG 对象

2. 初始化 Claude Code 适配器

   • 加载 universal/adapters/claude-code/adapter.md
   • 适配器提供平台特定的文件操作方法

3. 调用 Universal 核心工作流

   • 传入适配器实例和语言配置
   • 执行平台无关的核心逻辑

4. 输出结果

   • 使用 LANG 对象中的翻译文本
   • 替换占位符（如 {directory}, {count}）

命令概览

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

使用场景: 首次运行或重建整个索引系统

执行步骤:

1. 加载语言配置
2. 初始化 Claude Code 适配器
3. 调用 universal/core/generator/init-workflow.md
4. 适配器使用 Read/Write/Edit 工具执行文件操作
5. 输出总结报告

详细实现: commands_impl/init-index.md

核心工作流: ../../universal/core/generator/init-workflow.md

/update-index - 更新索引

使用场景: 文件修改后手动更新或 Hook 自动调用

执行步骤:

1. 加载语言配置
2. 初始化 Claude Code 适配器
3. 调用 universal/core/generator/update-workflow.md
4. 传入变更文件列表
5. 适配器执行增量更新
6. 报告更新结果

详细实现: commands_impl/update-index.md

核心工作流: ../../universal/core/generator/update-workflow.md

/check-index - 一致性检查

使用场景: 验证索引系统完整性

执行步骤:

1. 加载语言配置
2. 初始化 Claude Code 适配器
3. 调用 universal/core/generator/check-workflow.md
4. 适配器执行完整性检查
5. 生成检查报告

详细实现: commands_impl/check-index.md

核心工作流: ../../universal/core/generator/check-workflow.md

/set-language - 切换语言

使用场景: 快速切换界面语言

执行步骤:

1. 询问用户选择语言（zh-CN / en-US）
2. 创建或更新 .claude/locale-config.json
3. 验证语言文件存在
4. 确认切换成功

详细实现: commands_impl/set-language.md

🔧 PostToolUse Hook 自动更新

当检测到文件修改（Write/Edit）时：

1. 加载语言配置

2. 应用过滤规则（详见 locales/{language}/hooks.json）

   • 跳过索引文件自身
   • 跳过非代码文件
   • 跳过大文件（>500KB）
   • 跳过排除目录

3. 判断是否为结构性变更

   • 检查是否包含依赖关键字（import, require, use...）
   • 检查是否包含导出关键字（export, public, class...）

4. 执行更新

   • 结构性变更 → 调用 /update-index
   • 仅文件头变更 → 只更新文件头
   • 其他 → 跳过

5. 静默处理

   • 小改动：不提示
   • 重大变更：输出一行信息

🌍 多语言支持

支持的语言

• zh-CN: 简体中文（默认）
• en-US: 美国英语

切换方式

1. 配置文件方式（推荐）

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

2. 命令方式

   /set-language
   

3. 环境变量方式

   export CLAUDE_LOCALE=en-US
   

4. 初始化时询问

   • /init-index 会询问用户选择语言

技术术语

以下术语在所有语言中保持英文：

• Input, Output, Pos
• PROJECT_INDEX, FOLDER_INDEX
• SKILL.md

📖 扩展阅读

• 核心概念详解: core/concepts.md
• 国际化实现: core/i18n.md
• 语言文件: locales/zh-CN/ 和 locales/en-US/
• 文件模板: templates/

🎯 设计原则

1. 避免过度更新: 只在真正的结构性变化时更新索引
2. 保护用户内容: 更新时保留用户手动添加的注释
3. 清晰的反馈: 重要操作有明确提示
4. 性能优先: 大型项目使用增量更新
5. 易于理解: 文档清晰，示例丰富
6. 防止循环: 索引文件修改时不触发更新
7. 国际化: 支持多语言界面
8. 用户至上: 不确定的操作先询问用户

🔗 相关文档

• Universal 核心文档: ../../universal/
• 适配器开发指南: ../../universal/adapters/README.md
• 平台对比: ../../universal/.kiro/specs/platforms.yml

版本: 2.1.0 更新日期: 2025-12-23 新特性: 双模式架构 + Universal 多平台核心 + 适配器系统

Source: Claudate/project-multilevel-index — distributed by TomeVault.