ECharts版本升级

缘由

我们的一个组件库，是基于ECharts5.3.3版本之上进行扩展开发的，因此用到了ECharts的一些特性，并且通过patch-package的方式，修改了一部分ECharts的源码。
现在ECharts升级到版本6了，而且里面的一些新特性(比如断轴)也是我们想用的，因此将其进行了升级。
这次升级借助AI工具，极大的降低了成本，算是一次非常成功的AI提效案例。
这里记录下升级过程中的经验，便于下次升级时参考。

前置知识

Apache ECharts 6 升级指南：
https://echarts.apache.org/handbook/zh/basics/release-note/v6-upgrade-guide/

Apache ECharts 6 新特性：
https://echarts.apache.org/handbook/zh/basics/release-note/v6-feature/

遇到的问题

改为ESM，导出的问题

ECharts6改为ESM，导出的内容变更了，需要在每个引入ECharts源码的地方，修改引入路径，加上.js后缀。
这个通过编写一个脚本来批量修改解决了。

ECharts的API改了名字和位置

项目中会出现红线提醒，然后将红线提示的报错信息给到AI，让AI分析ECharts源码寻找新的API既可，类似这样：

1	`const gridRect = grid.coordinateSystem.getRect(); 报错: Property 'coordinateSystem' does not exist on type 'GridModel'.`

如何测试修改功能是否正常

这里其实存在2个问题：

如何了解某个修改具体的影响内容
如何编写测试用例
仍然是借助AI来实现，后文会给出Prompt。

如何分工以避免多人协作的冲突问题

按功能模块分工，保证互不影响。

成本统计

我们是4个人参与修改，中间插入了一些其他的事情，因此是断断续续的进行的。
粗略评估一下，应该在15人日左右，修改12人日，测试3人日。

修改技巧

判断哪些红线必须修改

开2个IDE，一个拉取当前的develop分支(A)，一个拉取feature/v6分支(B)，然后2个IDE都打开你准备修改的文件。

A中本身就有的红线提示，可以暂不修改，一般就是之前的一些TS问题(不过看到一些低级问题，可以随手改掉的，也建议一起改了；针对功能不明确的文件，也可以补充下注释)。

A中没有，B中有的红线提示，必改。

阅读代码

1
2

分析这下面的代码，然后按照执行流程，带我一步一步的阅读理解其逻辑，将讲解内容写入本地markdown文档
/Users/leozhou/git/test/standard-chart/packages/paradigm-chart/src/extension/series/dvMarker

查询新的API是什么(绝大部分修改都是这类问题)

1、单独开个页面，打开项目下的node_modules/echarts项目(一定是打开项目下的，不要单独git clone ECharts6到另外的项目，因为这样AI会关联分析)

2、将提示红线的语句和报错信息一起发给AI，即可查询到最新的API，类似这样即可：

1	`const gridRect = grid.coordinateSystem.getRect(); 报错: Property 'coordinateSystem' does not exist on type 'GridModel'.`

给修改的内容写个测试demo

在 @/Users/leozhou/git/test/standard-chart/packages/paradigm-chart/examples/components/grid/dvBoxLayout.html     │

仿照同级目录文件的格式,
给  /Users/leozhou/git/test/standard-chart/packages/paradigm-chart/src/extension/component/grid/dvBoxLayout.ts 写个demo    
注意设置一个每隔3秒，更新相关配置的功能，以便更直观的查看这个配置的效果和影响范围

写完记得更新/Users/leozhou/git/test/standard-chart/packages/paradigm-chart/examples/index.html  ，在合适的位置添加上对应的快捷链接

“注意设置一个每隔3秒，更新相关配置的功能，以便更直观的查看这个配置的效果和影响范围”这句话看情况添加，如果你想动态查看该配置的效果就加，否则一般不用加。

优化版本：

1、查看和理解<待分析的文件>，分析其实现的功能是什么，并在该文件中，以注释形式进行说明。
2、创建<Demo文件>及相关的js文件，仿照与其同级目录文件的格式,给<待分析的文件>写个测试demo，注意页面上增加更新相关配置的功能按钮，以便更直观的查看<待分析的文件>所实现的效果和影响范围，另外不要添加一些非必要的功能,只保留必要的测试功能,让我聚焦于验证<待分析的文件>的内容。
3、写完记得更新 <导航页面> ，在合适的位置添加上对应的快捷链接

## 待分析的文件 
/Users/leozhou/git/test/standard-chart/packages/paradigm-chart/src/extension/component/dataZoom/dvHandleOffset.ts

## Demo文件
/Users/leozhou/git/test/standard-chart/packages/paradigm-chart/examples/components/dataZoom/dvHandleOffset.html

## 导航页面
/Users/leozhou/git/test/standard-chart/packages/paradigm-chart/examples/index.html

基于现有Demo的配置去生成测试页面

比如这个：

http://datav.myhexin.com/example.html#/static-page?id=82

patch-package

分析修改的初衷和必要性

先分析下是否需要修改：

我现在在进行将这个库的依赖从ECharts5.3.3升级到6.0.0的操作
a00294b7893769934b48d3f21f0d7455c5ff173c  这个commit的内容是通过patch-package修改ECharts源码的操作
具体修改内容请通过  git show a00294b7893769934b48d3f21f0d7455c5ff173c -- patches/echarts+5.3.3.patch   查看
帮我分析下这个修改的目的是什么，具体解决什么问题，其逻辑是怎么实现的，该如何测试这个修改的效果(最好用可视化的形式帮我讲解下)，并帮我评估下在EChart6.0.0版本中，这个commit的内容，现在是否还有必要
请基于本地的node_modules/echarts下的真实代码进行分析
如有需要修改的，请告诉我具体应该修改哪些文件的哪些内容

修改流程

有一些需要注意的地方，建议按照如下流程走：

1、删除package.json中的这个script(因为这个脚本会大量改动 echarts 文件，如不先删除，会导致生成的patch文件包含巨量的无用信息)：

1	`"postprepare": "node scripts/enableEChartsLibsDTS.mjs",`

2、用npm install安装echarts，注意别用pnpm，因为pnpm的链接机制，会导致你之前的删除内容并未生效！

1	`rm -rf node_modules/echarts && npm i`

3、关闭编辑器(比如VSCode)保存文件时自动格式化的功能(因为自动保存时的格式化，会导致代码文件发生很多变更，进而导致打包进patch的代码非常多，有很多格式化的内容)

4、修改ECharts源码代码

5、执行如下命令，生成 patch 文件：

1	`npx patch-package echarts`

6、恢复package.json中的这个script

1	`"postprepare": "node scripts/enableEChartsLibsDTS.mjs",`

提交频率

改一个小功能点就提交一次

用Claude Code的command、其他IDE的智能提交都可以。

一些失败的尝试

让AI整体分析升级成本和方案

可能是因为代码库内容太多了，生成结果的幻觉问题很严重，基本不具备参考价值。

StandardChart是我们基于ECharts扩展的一个可视化图表库。这个库扩展了一些ECharts不支持的图表类型和特性，同时增加了额外的配置项。此外，我们还增加了主题相关的机制和功能。
目前我们的项目是基于ECharts 5.3.3版本开发的，然而ECharts现在已经升级到了6.0.0版本。因此，我们面临一个重要问题：需要将依赖的ECharts也进行升级。
基于这种情况，我们需要做的核心工作就是评估这次升级的影响范围以及确定具体的升级方法。具体来说，我们需要分析要改动哪些内容以及评估整个升级的成本。
项目下的StandardChart目录是我们的项目代码，ECharts-5.3.3目录存放着当前使用的ECharts版本。ECharts-6.0.0目录包含目前ECharts最新的，也就是我们要升级的版本的代码。
https://echarts.apache.org/handbook/zh/basics/release-note/v6-upgrade-guide/ 这个网页是 “Apache ECharts 6 升级指南”

升级的重点关注信息：
1、StandardChart中的每个组件都需要确认API兼容性，因为可能有些我们用到的API，在新版ECharts中发生了变更
2、patches下的内容也分析下，我们通过patch-package改了一些ECharts的源码，这部分也需要考虑下
3、部分新版ECharts已实现的补丁功能需要删除，比如：dvAlign、dvPadding等等，请仔细审查
4、新功能的适配问题(比如切换主题)
5、ESM的引入问题

希望能够基于我提供的这些信息，帮我分析这次升级的方案和成本，并制定详细的执行计划。

注意分析结果中不要出现模棱两可的内容，比如 API 或方法"可能变化"这种。通过对比两个不同版本的源码，明确判断这些变化是否确实会发生，通过理解它们的输入输出函数 API 的名称等信息，以及内部的逻辑来为我给出一个明确的答复，避免出现模棱两可的情况。

请调用尽可能多的Agent来完成该任务，生成尽量详细的文档，文档写入@docs/upgrade目录下的Markdown文件中。
请在任务全部完成后先进行自检；根据自检结果再进行优化操作。如此循环至少三次，方可视为完成整项任务
所有任务完成后，请梳理相关文档，对文档进行整理与优化
所有操作无需经过我确认，请自行执行即可。
注意当前的任务是分析和制定方案与计划，别更改项目的代码。
ultrathink

一次性执行

这是在上面的分析结果后执行的，经实践是不行的。

@docs/upgrade/ 基于这个目录下的方案，帮我执行 @standard-chart/ 升级到ECharts6的操作
请在任务全部完成后先进行自检；根据自检结果再进行优化操作。如此循环至少三次，方可视为完成整项任务
注意将修改过程日志，记入到docs/log 目录下的markdown文件中
所有操作无需经过我确认，请自行执行即可。

待改善的内容

我发现我们的代码中，有不少都是修改的lib/chart/xx/xxView.js的内容，也就是渲染之后的后处理，这会导致二次渲染吧？
这些应该是不大合理的，应该改为扩展才对。

#ECharts

可视化项目架构分析上一篇

混合架构-基于D3.js的程序设计下一篇