1.0.11 预备
This commit is contained in:
睿 安
151
CLAUDE.md
151
CLAUDE.md
@@ -4,105 +4,110 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||||||
|
|
||||||
## Project Overview
|
## Project Overview
|
||||||
|
|
||||||
Squirrel NUT Explorer 是一个 VS Code 扩展，用于通过 pvfUtility API 浏览和编辑 NUT (Squirrel 脚本) 文件。扩展提供了完整的语言支持功能，包括代码自动完成、悬停信息、定义跳转、函数签名帮助、代码格式化和错误检测。
|
Squirrel NUT Explorer is a VS Code extension for browsing and editing NUT (Squirrel script) files through the pvfUtility API. The extension provides comprehensive language support features including code completion, hover information, definition jumping, function signature help, code formatting, and error detection.
|
||||||
|
|
||||||
## 构建命令
|
## Build Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 安装依赖
|
# Install dependencies
|
||||||
npm install
|
npm install
|
||||||
|
|
||||||
# 编译 TypeScript
|
# Compile TypeScript
|
||||||
npm run compile
|
npm run compile
|
||||||
|
|
||||||
# 监视模式编译
|
# Watch mode compilation
|
||||||
npm run watch
|
npm run watch
|
||||||
|
|
||||||
# 构建项目
|
# Build project
|
||||||
npm run build
|
npm run build
|
||||||
|
|
||||||
# VS Code 发布前构建
|
# VS Code pre-publish build
|
||||||
npm run vscode:prepublish
|
npm run vscode:prepublish
|
||||||
```
|
```
|
||||||
|
|
||||||
## 项目架构
|
## High-Level Architecture
|
||||||
|
|
||||||
### 核心组件
|
### Core Components
|
||||||
|
|
||||||
- **extension.ts**: 扩展入口点，注册所有提供者和命令
|
1. **Extension Entry Point** (`src/extension.ts`):
|
||||||
- **model/FileModel.ts**: 文件数据模型，管理文件状态和内容
|
- Registers all providers and commands
|
||||||
- **provider/FileProvider.ts**: 树形视图提供者，管理文件列表显示
|
- Initializes core services and manages extension lifecycle
|
||||||
- **fileSystemProvider/SquirrelFileSystemProvider.ts**: 文件系统提供者，处理文件读写
|
|
||||||
|
|
||||||
### 语言功能提供者 (src/providers/)
|
2. **Data Model** (`src/model.ts`):
|
||||||
|
- `FileModel` class manages file state, content, and API communication
|
||||||
|
- Handles connection to pvfUtility API and file operations
|
||||||
|
- Manages file list and content caching
|
||||||
|
|
||||||
- **completionProvider.ts**: 代码自动完成，包括基础完成和点号完成
|
3. **Tree View Provider** (`src/provider.ts`):
|
||||||
- **hoverProvider.ts**: 悬停信息显示，显示函数、类、常量的文档
|
- Implements `vscode.TreeDataProvider` for displaying files in the explorer view
|
||||||
- **definitionProvider.ts**: 定义跳转，支持跨文件函数定义查找
|
- Manages UI representation of files and folders
|
||||||
- **signatureHelpProvider.ts**: 函数签名帮助，显示参数列表
|
|
||||||
- **onTypeFormattingProvider.ts**: 输入时格式化，在特定字符输入时触发格式化
|
|
||||||
- **documentFormattingProvider.ts**: 文档范围格式化
|
|
||||||
- **codeErrorProvider.ts**: 代码错误检测，包括语法检查和快速修复
|
|
||||||
|
|
||||||
### 核心功能模块
|
4. **File System Provider** (`src/fileSystemProvider.ts`):
|
||||||
|
- Implements `vscode.FileSystemProvider` for virtual file handling
|
||||||
|
- Bridges VS Code file operations with pvfUtility API
|
||||||
|
|
||||||
- **functionExtractor/FunctionExtractor.ts**: 函数提取器，解析 NUT 文件中的函数定义
|
### Language Feature Providers (`src/providers/`)
|
||||||
- **functionExtractor/CacheManager.ts**: 缓存管理器，管理函数和文档的缓存
|
|
||||||
- **api/pvfUtilityApi.ts**: pvfUtility API 客户端，处理与后端服务的通信
|
|
||||||
- **utils/jsBeautifyManager.ts**: JS 美化管理器，处理代码格式化
|
|
||||||
- **utils/StringDetector.ts**: 字符串检测器，处理字符串边界检测
|
|
||||||
|
|
||||||
## 文件结构
|
1. **Completion Provider** (`src/providers/completionProvider.ts`):
|
||||||
|
- Provides code completion for functions, keywords, constants, and variables
|
||||||
|
- Includes both basic completion and dot notation completion for object methods
|
||||||
|
|
||||||
```
|
2. **Hover Provider** (`src/providers/hoverProvider.ts`):
|
||||||
src/
|
- Shows detailed information when hovering over code elements
|
||||||
├── extension.ts # 扩展入口点
|
- Displays function signatures, descriptions, and parameter details
|
||||||
├── 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 # 常量数据
|
|
||||||
```
|
|
||||||
|
|
||||||
## 关键依赖
|
3. **Definition Provider** (`src/providers/definitionProvider.ts`):
|
||||||
|
- Enables "Go to Definition" functionality for cross-file function references
|
||||||
|
|
||||||
- **VS Code API**: 扩展开发的基础 API
|
4. **Signature Help Provider** (`src/providers/signatureHelpProvider.ts`):
|
||||||
- **TypeScript**: 项目开发语言
|
- Shows function parameter information during typing
|
||||||
- **js-beautify**: 代码格式化库
|
|
||||||
- **pvfUtility API**: 后端服务 API，用于文件操作
|
|
||||||
|
|
||||||
## 配置项
|
5. **Formatting Providers** (`src/providers/onTypeFormattingProvider.ts`, `src/providers/documentFormattingProvider.ts`):
|
||||||
|
- Handle code formatting on type and document formatting
|
||||||
|
|
||||||
扩展提供以下配置项：
|
6. **Code Error Provider** (`src/providers/codeErrorProvider.ts`):
|
||||||
|
- Implements code diagnostics and quick fixes
|
||||||
|
|
||||||
- `squirrel.api.baseUrl`: pvfUtility API 基础 URL (默认: http://localhost)
|
### Core Functionality Modules
|
||||||
- `squirrel.api.port`: pvfUtility API 端口 (默认: 27000)
|
|
||||||
- `squirrel.defaultDirectory`: 默认浏览目录 (默认: sqr)
|
|
||||||
- `squirrel.nutEncoding`: NUT 文件编码 (默认: UTF8)
|
|
||||||
|
|
||||||
## 开发注意事项
|
1. **Function Extractor** (`src/functionExtractor.ts`):
|
||||||
|
- Parses NUT files to extract function definitions
|
||||||
|
- Manages function caching for performance
|
||||||
|
- Provides cross-file function reference capabilities
|
||||||
|
|
||||||
1. **缓存机制**: FunctionExtractor 使用缓存机制提高性能，文件保存时会更新对应缓存
|
2. **API Client** (`src/apiClient.ts`):
|
||||||
2. **批量处理**: 文件按批次处理，避免内存溢出和阻塞
|
- Handles all HTTP communication with pvfUtility API
|
||||||
3. **错误处理**: 所有 API 调用都有异常处理，确保扩展稳定性
|
- Manages file listing, content retrieval, and file saving
|
||||||
4. **中文支持**: 项目主要使用中文界面和注释，保持代码注释的语言一致性
|
|
||||||
|
3. **API Parser** (`src/providers/apiParser.ts`):
|
||||||
|
- Provides built-in Squirrel language documentation
|
||||||
|
- Manages API functions, classes, and constants information
|
||||||
|
|
||||||
|
## Key Dependencies
|
||||||
|
|
||||||
|
- **VS Code API**: Foundation for extension development
|
||||||
|
- **TypeScript**: Development language
|
||||||
|
- **Node.js HTTP/HTTPS modules**: For API communication (no external HTTP libraries)
|
||||||
|
|
||||||
|
## Configuration Options
|
||||||
|
|
||||||
|
The extension provides these configuration options:
|
||||||
|
|
||||||
|
- `squirrel.api.baseUrl`: pvfUtility API base URL (default: http://localhost)
|
||||||
|
- `squirrel.api.port`: pvfUtility API port (default: 8080)
|
||||||
|
- `squirrel.defaultDirectory`: Default directory to browse (default: sqr)
|
||||||
|
- `squirrel.nutEncoding`: NUT file encoding type (default: UTF8)
|
||||||
|
|
||||||
|
## Development Notes
|
||||||
|
|
||||||
|
1. **Caching Mechanism**: FunctionExtractor uses caching to improve performance. File caches are updated when files are saved.
|
||||||
|
|
||||||
|
2. **Batch Processing**: Files are processed in batches to prevent memory overflow and blocking.
|
||||||
|
|
||||||
|
3. **Error Handling**: All API calls include exception handling to ensure extension stability.
|
||||||
|
|
||||||
|
4. **Chinese Support**: The project primarily uses Chinese for UI and comments, maintaining consistency in code documentation.
|
||||||
|
|
||||||
|
5. **Virtual File System**: The extension uses VS Code's virtual file system API to provide a seamless editing experience for remote files.
|
||||||
|
|
||||||
|
6. **Performance Monitoring**: Function extraction includes performance monitoring to track efficiency.
|
||||||
Reference in New Issue
Block a user