# VSeed Agent Context (vseed 子包综述)

本文档面向后续 agent-code 与开发者，提供 VSeed 子包的架构、流程与关键模块的一页式上下文。

## 1. 目标与定位

VSeed 的目标是让 LLM 生成的 `VSeed DSL` 在上下文驱动下稳定落地为可渲染的 `VChart` / `VTable` Spec，从而支持智能生成与编辑图表。它本质是一个 **Spec Builder**：

- 输入：语义化 DSL（`VSeed DSL`）
- 输出：`VChart` 或 `VTable` 可渲染 Spec
- 核心过程：`AdvancedPipeline` + `SpecPipeline`

参考：

- `apps/website/docs/zh-CN/vseed/development/architecture.md`
- `apps/website/docs/zh-CN/vseed/development/designPhilosophy/vseed.md`

## 2. 核心流程（两段式 Pipeline）

### 2.1 Pipeline 总览

VSeed 将构建过程拆成两段，保证“可序列化中间态”和“不可序列化渲染态”分离：

1. **AdvancedPipeline**
   - 输入：`VSeed DSL`
   - 输出：`AdvancedVSeed`（中间态 DSL，可序列化）
   - 负责：数据重塑、默认推断、主题/样式、分析配置、编码建模

2. **SpecPipeline**
   - 输入：`AdvancedVSeed`
   - 输出：`Spec`（VChart / VTable 直接渲染配置，不可序列化）
   - 负责：将中间态细化为具体图表/表格 Spec

入口流程：

- `Builder.build()` → `buildAdvanced()` → `buildSpec()`
- 源码：
  - `packages/vseed/src/builder/builder/build.ts`
  - `packages/vseed/src/builder/builder/buildAdvanced.ts`
  - `packages/vseed/src/builder/builder/buildSpec.ts`

### 2.2 Pipeline 执行机制

- `execPipeline(pipeline, context, initialValue)`：按顺序 reduce 执行，每个 Pipe 返回 Partial 结果。
- Pipe 类型：`(result, context) => result`，无共享状态，依赖 context。
- 源码：`packages/vseed/src/pipeline/utils/pipeline.ts`

## 3. Builder 机制

`Builder` 是核心协调器：

- 管理 `vseed`、`advancedVSeed`、`spec`、`performance`、`locale`
- 支持：`prepare()`（执行 dynamicFilter）、`buildAdvanced()`、`buildSpec()`、`build()`
- 通过注册表选择不同 chartType 对应的 pipelines

源码：

- `packages/vseed/src/builder/builder/builder.ts`

### 3.1 注册与扩展

- **注册所有内置类型与主题**：`registerAll()`
  - `packages/vseed/src/builder/register/all.ts`
- **注册特定图表类型**：`registerLine()` 等
  - `packages/vseed/src/builder/register/chartType/*`
- **扩展 Pipe**：`updateAdvanced()` / `updateSpec()`
  - `packages/vseed/src/builder/register/custom.ts`
- **主题注册**：`registerLightTheme()` / `registerDarkTheme()` / `registerCustomTheme()`
  - `packages/vseed/src/builder/register/theme/*`

## 4. DSL / 类型体系

### 4.1 VSeed DSL

- `VSeed` 是 union 类型，覆盖所有图表/表格 chartType。
- 入口类型：`packages/vseed/src/types/vseed.ts`

### 4.2 AdvancedVSeed

`AdvancedVSeed` 是中间态 DSL，字段更丰富，含 encoding、reshape 信息、主题/样式/分析信息：

- 源码：`packages/vseed/src/types/advancedVSeed.ts`

### 4.3 Spec Pipeline 类型

Spec pipeline 支持多种输出：

- `VChartSpecPipeline`
- `PivotChartSpecPipeline`
- `ListTableSpecPipeline`
- `PivotTableSpecPipeline`

源码：`packages/vseed/src/types/pipeline/spec/spec.ts`

## 5. 数据重塑（Data Reshape）

核心模块：将任意维度/指标组合转换为适配图表的可视化编码结构。

### 5.1 foldMeasures（指标折叠）

- 把多指标折叠为单指标
- 生成 `foldInfo`（含统计信息）
- 保证“一条数据 = 一个图元”的映射

源码：`packages/vseed/src/dataReshape/foldMeasures.ts`

### 5.2 unfoldDimensions（维度合并）

- 合并多个维度为一个新维度（映射到视觉通道）
- 依赖 fold 后的数据保证无冲突
- 生成 `unfoldInfo`，包含颜色编码映射

源码：`packages/vseed/src/dataReshape/unfoldDimensions.ts`

### 5.3 dataReshapeByEncoding

- 组合调用：`foldMeasures` + `unfoldDimensions`
- 是“任意维度/指标 → 固定编码结构”的关键入口

源码：`packages/vseed/src/dataReshape/dataReshapeByEncoding.ts`

## 6. AdvancedPipeline 结构（示例）

以 line 为例（图表类 advanced pipeline）：

```
page → initAdvancedVSeed → defaultMeasures → defaultDimensions → defaultMeasureId
→ encodingAdapter(...) → pivotAdapter(...) → sortXBandAxis → sortLegend
→ lineConfig → theme → markStyle → annotation
```

源码：`packages/vseed/src/pipeline/advanced/chart/pipeline/line.ts`

表格类（table / pivotTable） advanced pipeline：

```
page → initAdvancedVSeed → defaultMeasures → defaultDimensions → cellStyle
→ records → tableConfig / pivotTableConfig → theme
```

源码：

- `packages/vseed/src/pipeline/advanced/table/pipeline/table.ts`
- `packages/vseed/src/pipeline/advanced/table/pipeline/pivotTable.ts`

## 7. SpecPipeline 结构（示例）

### 7.1 Line Spec Pipeline

- 支持 pivotAdapter：普通图表与透视图表分支
- 通过 pipe 组合实现 feature 复用

源码：`packages/vseed/src/pipeline/spec/chart/pipeline/line.ts`

### 7.2 Table Spec Pipeline

- table：columns / style / theme / cell
- pivotTable：rows / columns / indicators / theme / cell

源码：

- `packages/vseed/src/pipeline/spec/table/pipeline/table.ts`
- `packages/vseed/src/pipeline/spec/table/pipeline/pivotTable.ts`

## 8. 动态过滤（Dynamic Filter）

VSeed 支持在 DSL 中写动态过滤逻辑（code），在 build 前执行。

- `Builder.prepare()` 会：
  - 定位 DSL 中所有 `dynamicFilter`
  - 深拷贝相关路径
  - 注入 `__row_index`
  - 执行 code，写回 `filter.result`

源码：`packages/vseed/src/builder/builder/prepare.ts`

## 9. Pipeline 设计原则（与实现约束）

- 功能拆分为“原子 Pipe”，避免大而全的 if/else
- 组合式 pipeline 构建图表类型
- 适配器模式（如 pivotAdapter）承接条件分支

详见：

- `apps/website/docs/zh-CN/vseed/development/designPhilosophy/pipeline/pipelineDesign.md`
- `apps/website/docs/zh-CN/vseed/development/designPhilosophy/pipeline/advancedPipeline.md`
- `apps/website/docs/zh-CN/vseed/development/designPhilosophy/pipeline/specPipeline.md`

## 10. Agent 开发建议（面向新增功能）

- 新增图表类型：
  - 补齐 `types/chartType/*`
  - 新建 `advanced` pipeline + `spec` pipeline
  - `builder/register/chartType/*` 注册

- 新增功能：
  - 优先设计独立 Pipe
  - 避免在 Pipe 内进行大分支
  - 若存在条件流程，优先用 Adapter 组合

- 新增 DSL 字段：
  - 先更新 `types` 与 zod 校验
  - 在 advanced pipeline 中完成默认推断与 reshape
  - 在 spec pipeline 中映射到具体 spec

## 11. 快速入口参考

- API 入口：`packages/vseed/src/index.ts`
- 注册所有能力：`registerAll()`
- 快速开始：`apps/website/docs/zh-CN/vseed/guide/quickStart.mdx`