VisActor · fangsmile · Jun 25, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,208 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project Overview
+
+VTable is a high-performance multidimensional data analysis table component built on the VRender canvas engine. This is a Rush monorepo containing the core VTable library and related packages.
+
+## Essential Commands
+
+### Development Setup
+```bash
+# Install dependencies (required first time and after package.json changes)
+rush update
+
+# Build all packages
+rush build
+
+# Start development server for core vtable package
+cd packages/vtable && rushx demo
+
+# Start documentation site
+rush docs
+
+# Run tests
+rush test
+
+# Run linting
+rush eslint
+
+# Fix dependency issues
+rush purge && rush update
+```
+
+### Working with Individual Packages
+```bash
+# Build specific package
+cd packages/[package-name] && rushx build
+
+# Run tests for specific package
+cd packages/[package-name] && rushx test
+
+# Start demo for specific package
+cd packages/[package-name] && rushx demo
+```
+
+### Git Workflow
+```bash
+# After making changes, update changelogs before committing
+rush change-all
+
+# Commit with conventional message format
+git commit -m "type: description"
+```
+
+## Architecture Overview
+
+### Package Structure
+- **packages/vtable**: Core VTable library with ListTable, PivotTable, and PivotChart components
+- **packages/vtable-gantt**: Gantt chart component
+- **packages/vtable-editors**: Table editor components
+- **packages/vtable-plugins**: Plugin system for extending functionality
+- **packages/vtable-export**: Export functionality (Excel, CSV, etc.)
+- **packages/vtable-search**: Search capabilities
+- **packages/vtable-calendar**: Calendar component
+- **packages/vtable-sheet**: Spreadsheet functionality (current development branch)
+  - **项目特性**: 电子表格组件，支持多sheet tab页签管理
+  - **核心架构**:
+    - `workSheetInstances`: 管理所有sheet tab实例的核心容器
+    - `work-sheet`: 单个sheet页签的实现，包含对应vtable实例
+  - **依赖关系**: 依赖vtable核心插件系统，需先安装vtable插件
+  - **当前开发重点**: 跨sheet tab公式计算支持
+  - **技术实现**: 基于VTable核心库扩展，每个sheet对应独立的VTable实例
+- **packages/react-vtable**: React wrapper
+- **packages/vue-vtable**: Vue wrapper
+- **packages/openinula-vtable**: OpenInula wrapper
+
+### Core Architecture
+The library is built on a canvas-based rendering system using VRender:
+
+1. **Table Types**:
+   - `ListTable`: Basic table with columns and rows
+   - `PivotTable`: Multi-dimensional data analysis
+   - `PivotChart`: Chart integration with tables
+
+2. **Rendering Pipeline**:
+   - Scenegraph-based rendering in `src/scenegraph/`
+   - Canvas-based graphics using VRender engine
+   - Custom layout system in `src/render/layout/`
+
+3. **Data Management**:
+   - Data source abstraction in `src/data/`
+   - Statistics and aggregation in `src/dataset/`
+   - Event system for data updates
+
+4. **Extension Points**:
+   - Plugin system for custom functionality
+   - Theme system for styling
+   - Custom cell renderers and editors
+
+### Testing Strategy
+- **Framework**: Jest with ts-jest preset
+- **Environment**: jest-electron for DOM/canvas testing
+- **Coverage Requirements**: 60% minimum for all metrics
+- **Test Location**: `__tests__/` directories within each package
+
+### Key Dependencies
+- **@visactor/vrender-***: Canvas rendering engine (v1.0.14)
+- **@visactor/vutils**: Utility functions (~0.19.1)
+- **lodash**: Utility library (4.17.21)
+
+### Development Notes
+- This is a Rush monorepo - always use `rush` commands instead of npm/yarn directly
+- Current branch: `feat/vtable-sheet` (spreadsheet functionality)
+- Main branches: `main`, `develop`
+- Node.js versions supported: 14.15.0+, 16.13.0+, 18.15.0+
+
+## vtable-sheet 项目详细信息
+
+### 项目路径
+`/Users/bytedance/VisActor/VTable/packages/vtable-sheet`
+
+### 核心功能需求
+- **跨sheet tab公式计算支持**: 实现不同sheet页签间的公式引用和计算
+- **多页签管理**: 支持创建、切换、删除sheet页签
+- **数据同步**: 确保跨sheet数据引用的实时更新
+
+### 技术架构
+- **核心入口**: vtable-sheet文件是整个组件的入口点
+- **实例管理**: workSheetInstances负责管理所有sheet实例
+- **单sheet实现**: 每个work-sheet包含独立的VTable实例
+- **插件依赖**: 依赖VTable核心插件系统提供基础功能
+
+### 跨Sheet公式功能实现
+
+#### 新增核心组件
+1. **CrossSheetFormulaManager** (`src/formula/cross-sheet-formula-manager.ts`)
+   - 管理跨Sheet公式引用关系
+   - 处理依赖关系映射和缓存
+   - 支持公式验证和错误处理
+
+2. **CrossSheetDataSynchronizer** (`src/formula/cross-sheet-data-synchronizer.ts`)
+   - 处理跨Sheet数据同步
+   - 支持批量数据更新
+   - 提供实时更新通知机制
+
+3. **CrossSheetFormulaValidator** (`src/formula/cross-sheet-formula-validator.ts`)
+   - 验证跨Sheet公式语法
+   - 检测循环依赖
+   - 提供详细的错误信息
+
+4. **CrossSheetFormulaHandler** (`src/formula/cross-sheet-formula-handler.ts`)
+   - 统一的跨Sheet公式处理接口
+   - 集成缓存、验证、同步功能
+   - 提供高性能的计算引擎
+
+#### 支持的公式类型
+- **基本引用**: `=Sheet1!A1`, `=Sheet2!B2:C4`
+- **函数计算**: `=SUM(Sheet1!A1:A10)`, `=AVERAGE(Sheet1!B1:B10)`
+- **跨表运算**: `=Sheet1!A1 + Sheet2!B1`
+- **条件判断**: `=IF(Sheet1!A1>100, "达标", "未达标")`
+- **复杂嵌套**: `=IF(AVERAGE(Sheet1!A1:A10)>50, SUM(Sheet1!B1:B10)*1.1, SUM(Sheet1!B1:B10))`
+
+#### 核心功能特性
+- ✅ **实时计算**: 源数据变化时自动更新依赖公式
+- ✅ **智能缓存**: 1秒TTL缓存机制，平衡性能与实时性
+- ✅ **错误处理**: 完善的错误检测和提示机制
+- ✅ **依赖管理**: 自动识别和管理跨Sheet依赖关系
+- ✅ **批量处理**: 支持批量公式计算和数据更新
+- ✅ **性能优化**: 异步处理，避免阻塞UI
+
+#### 使用示例
+```typescript
+// 设置跨Sheet公式
+const cell = { sheet: 'Summary', row: 1, col: 1 };
+const formula = '=SUM(SalesData!B2:E4)';
+await formulaManager.setCrossSheetFormula(cell, formula);
+
+// 获取计算结果
+const result = await formulaManager.getCrossSheetValue(cell);
+console.log(result.value); // 计算结果
+console.log(result.calculationTime); // 计算耗时
+
+// 验证公式
+const validation = formulaManager.validateCrossSheetFormula(cell);
+console.log(validation.valid); // 是否有效
+
+// 获取依赖关系
+const dependencies = formulaManager.getCrossSheetDependencies();
+```
+
+#### 测试覆盖
+- **单元测试**: `__tests__/cross-sheet-formula-simple.test.ts`
+- **集成测试**: `__tests__/integration/cross-sheet-integration.test.ts`
+- **演示页面**: `examples/cross-sheet-demo.html`
+- **使用文档**: `docs/cross-sheet-formula-guide.md`
+
+#### 性能指标
+- 100个跨Sheet公式计算 < 5秒
+- 20个公式批量重新计算 < 2秒
+- 缓存命中率 > 80%
+- 内存使用优化，支持大规模数据
+
+
+#### 使用限制
+- 跨Sheet公式目前主要用于读取操作，写入操作仍在原Sheet中进行
+- 复杂的跨Sheet引用可能需要异步处理以获得最佳性能
+- 循环依赖检测基于静态分析，运行时循环依赖需要额外的错误处理