# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Squirrel NUT Explorer 是一个 VS Code 扩展，用于通过 pvfUtility API 浏览和编辑 NUT (Squirrel 脚本) 文件。扩展提供了完整的语言支持功能，包括代码自动完成、悬停信息、定义跳转、函数签名帮助、代码格式化和错误检测。

## 构建命令

```bash
# 安装依赖
npm install

# 编译 TypeScript
npm run compile

# 监视模式编译
npm run watch

# 构建项目
npm run build

# VS Code 发布前构建
npm run vscode:prepublish
```

## 项目架构

### 核心组件

- **extension.ts**: 扩展入口点，注册所有提供者和命令
- **model/FileModel.ts**: 文件数据模型，管理文件状态和内容
- **provider/FileProvider.ts**: 树形视图提供者，管理文件列表显示
- **fileSystemProvider/SquirrelFileSystemProvider.ts**: 文件系统提供者，处理文件读写

### 语言功能提供者 (src/providers/)

- **completionProvider.ts**: 代码自动完成，包括基础完成和点号完成
- **hoverProvider.ts**: 悬停信息显示，显示函数、类、常量的文档
- **definitionProvider.ts**: 定义跳转，支持跨文件函数定义查找
- **signatureHelpProvider.ts**: 函数签名帮助，显示参数列表
- **onTypeFormattingProvider.ts**: 输入时格式化，在特定字符输入时触发格式化
- **documentFormattingProvider.ts**: 文档范围格式化
- **codeErrorProvider.ts**: 代码错误检测，包括语法检查和快速修复

### 核心功能模块

- **functionExtractor/FunctionExtractor.ts**: 函数提取器，解析 NUT 文件中的函数定义
- **functionExtractor/CacheManager.ts**: 缓存管理器，管理函数和文档的缓存
- **api/pvfUtilityApi.ts**: pvfUtility API 客户端，处理与后端服务的通信
- **utils/jsBeautifyManager.ts**: JS 美化管理器，处理代码格式化
- **utils/StringDetector.ts**: 字符串检测器，处理字符串边界检测

## 文件结构

```
src/
├── extension.ts                    # 扩展入口点
├── model/
│   └── FileModel.ts               # 文件数据模型
├── provider/
│   └── FileProvider.ts            # 树形视图提供者
├── fileSystemProvider/
│   └── SquirrelFileSystemProvider.ts  # 文件系统提供者
├── providers/                     # 语言功能提供者
│   ├── completionProvider.ts
│   ├── hoverProvider.ts
│   ├── definitionProvider.ts
│   ├── signatureHelpProvider.ts
│   ├── onTypeFormattingProvider.ts
│   ├── documentFormattingProvider.ts
│   └── codeErrorProvider.ts
├── functionExtractor/             # 函数提取和缓存
│   ├── FunctionExtractor.ts
│   └── CacheManager.ts
├── api/
│   └── pvfUtilityApi.ts          # API 客户端
├── utils/                         # 工具模块
│   ├── jsBeautifyManager.ts
│   └── StringDetector.ts
└── data/                          # 静态数据
    ├── squirrelApiData.ts        # Squirrel API 数据
    └── constantData.ts           # 常量数据
```

## 关键依赖

- **VS Code API**: 扩展开发的基础 API
- **TypeScript**: 项目开发语言
- **js-beautify**: 代码格式化库
- **pvfUtility API**: 后端服务 API，用于文件操作

## 配置项

扩展提供以下配置项：

- `squirrel.api.baseUrl`: pvfUtility API 基础 URL (默认: http://localhost)
- `squirrel.api.port`: pvfUtility API 端口 (默认: 27000)
- `squirrel.defaultDirectory`: 默认浏览目录 (默认: sqr)
- `squirrel.nutEncoding`: NUT 文件编码 (默认: UTF8)

## 开发注意事项

1. **缓存机制**: FunctionExtractor 使用缓存机制提高性能，文件保存时会更新对应缓存
2. **批量处理**: 文件按批次处理，避免内存溢出和阻塞
3. **错误处理**: 所有 API 调用都有异常处理，确保扩展稳定性
4. **中文支持**: 项目主要使用中文界面和注释，保持代码注释的语言一致性