From b09f51ec64aa63b51f15b9ac8f9b56dd3ae86f38 Mon Sep 17 00:00:00 2001
From: ZJU_czx <952370295@qq.com>
Date: Thu, 3 Apr 2025 22:59:17 +0800
Subject: [PATCH] feat: update readme and demo data

---
 .gitignore                                    |  3 +
 app/tool/chart_visualization/README.md        | 83 +++++++++++++++----
 app/tool/chart_visualization/README_zh.md     | 72 ++++++++++++++--
 .../chart_visualization/python_execute.py     | 19 +++--
 .../chart_visualization/test/hack_demo.py     |  2 +-
 .../chart_visualization/test/simple_chart.py  |  2 +-
 workspace/amazon_sales_jan.csv                | 33 ++++++++
 7 files changed, 180 insertions(+), 34 deletions(-)
 create mode 100644 workspace/amazon_sales_jan.csv

diff --git a/.gitignore b/.gitignore
index 41dbbf2..4902d4c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,9 @@ data/
 # Workspace
 workspace/
 
+# not hack demo
+!workspace/amazon_sales_jan.csv
+
 ### Python ###
 # Byte-compiled / optimized / DLL files
 __pycache__/
diff --git a/app/tool/chart_visualization/README.md b/app/tool/chart_visualization/README.md
index 588d34c..9caed3c 100644
--- a/app/tool/chart_visualization/README.md
+++ b/app/tool/chart_visualization/README.md
@@ -21,20 +21,64 @@ cd app/tool/chart_visualization
 npm install
 ```
 
-## Tool Parameters
+## Tool
+### python_execute
+
+Execute the necessary parts of data analysis (excluding data visualization) using Python code, including data processing, data summary, report generation, and some general Python script code.
+
+#### Input
 ```typescript
 {
-  // Generates Python code for data processing to produce a CSV file
+  // Code type: data processing/data report/other general tasks
+  code_type: "process" | "report" | "others"
+  // Final execution code
   code: string;
-  // Parses user intent to generate chart description
-  chart_description: string;
-  // Final output type (png/html). HTML supports VChart rendering and interaction
-  output_type: 'png' | 'html'
 }
 ```
 
-## Output
-The final results will be saved locally in `png` or `html` format for subsequent use by agents.
+#### Output
+Python execution results, including the saving of intermediate files and print output results.
+
+### visualization_preparation
+
+A pre-tool for data visualization with two purposes,
+
+#### Data -> Chart
+Used to extract the data needed for analysis (.csv) and the corresponding visualization description from the data, ultimately outputting a JSON configuration file.
+
+#### Chart + Insight -> Chart
+Select existing charts and corresponding data insights, choose data insights to add to the chart in the form of data annotations, and finally generate a JSON configuration file.
+
+#### Input
+```typescript
+{
+  // Code type: data visualization or data insight addition
+  code_type: "visualization" | "insight"
+  // Python code used to produce the final JSON file
+  code: string;
+}
+```
+
+#### Output
+A configuration file for data visualization, used for the `data_visualization tool`.
+
+## data_visualization
+
+Generate specific data visualizations based on the content of `visualization_preparation`.
+
+### Input
+```typescript
+{
+  // Configuration file path
+  json_path: string;
+  // Current purpose, data visualization or insight annotation addition
+  tool_type: "visualization" | "insight";
+  // Final product png or html; html supports vchart rendering and interaction
+  output_type: 'png' | 'html'
+  // Language, currently supports Chinese and English
+  language: "zh" | "en"
+}
+```
 
 ## VMind Configuration
 
@@ -54,22 +98,31 @@ Default dimensions are unspecified. For HTML output, charts fill the entire page
 ### Theme
 Default theme: `'light'`. VChart supports multiple themes. See [Themes](https://www.visactor.io/vchart/guide/tutorial_docs/Theme/Theme_Extension).
 
-## Testing
+## Test
 
-Two test tasks with different difficulty levels are provided:
+Currently, three tasks of different difficulty levels are set for testing.
 
-### Basic Chart Generation Task
+### Simple Chart Generation Task
 
-Generates charts from given data and specific requirements. Execute with:
+Provide data and specific chart generation requirements, test results, execute the command:
 ```bash
 python -m app.tool.chart_visualization.test.simple_chart
 ```
-Results will be saved in `./data`, containing 9 different chart types.
+The results should be located under `workspace`, involving 9 different chart results.
 
 ### Simple Data Report Task
 
-Processes raw data with basic analysis requirements. Execute with:
+Provide simple raw data analysis requirements, requiring simple processing of the data, execute the command:
 ```bash
 python -m app.tool.chart_visualization.test.simple_report
 ```
-Results will also be saved in `./data`.
+The results are also located under `workspace`.
+
+### Manus Online Store Operation Analysis Replication
+
+Replicate the [Manus result](https://manus.im/share/c3onakN6Iajcm1Vt1xAVG7?replay=1), execute the command as follows:
+
+```
+python -m app.tool.chart_visualization.test.hack_demo
+```
+The results are also located under `workspace`.
diff --git a/app/tool/chart_visualization/README_zh.md b/app/tool/chart_visualization/README_zh.md
index bfcade8..cf7fe08 100644
--- a/app/tool/chart_visualization/README_zh.md
+++ b/app/tool/chart_visualization/README_zh.md
@@ -18,21 +18,68 @@ nvm install --lts
 cd app/tool/chart_visualization
 npm install
 ```
+## Tool
+### python_execute
 
-## 工具参数
+用python代码执行数据分析（除数据可视化以外）中需要的部分，包括数据处理，数据总结摘要，报告生成以及一些通用python脚本代码
+
+#### 输入
 ```typescript
 {
-  // 用于生产数据处理的python代码，最终得到csv文件
+  // 代码类型：数据处理/数据报告/其他通用任务
+  code_type: "process" | "report" | "others"
+  // 最终执行代码
   code: string;
-  // 解析用户意图，得到图表描述
-  chart_description: string;
+}
+```
+
+#### 输出
+python执行结果，带有中间文件的保存和print输出结果
+
+### visualization_preparation
+
+数据可视化前置工具，有两种用途，
+
+#### Data -〉 Chart
+用于从数据中提取需要分析的数据(.csv)和对应可视化的描述，最终输出一份json配置文件。
+
+#### Chart + Insight -> Chart
+选取已有的图表和对应的数据洞察，挑选数据洞察以数据标注的形式增加到图表中，最终生成一份json配置文件。
+
+#### 输入
+```typescript
+{
+  // 代码类型：数据可视化 或者 数据洞察添加
+  code_type: "visualization" | "insight"
+  // 用于生产最终json文件的python代码
+  code: string;
+}
+```
+
+#### 输出
+数据可视化的配置文件，用于`data_visualization tool`
+
+
+## data_visualization
+
+根据`visualization_preparation`的内容，生成具体的数据可视化
+
+### 输入
+```typescript
+{
+  // 配置文件路径
+  json_path: string;
+  // 当前用途，数据可视化或者洞察标注添加
+  tool_type: "visualization" | "insight";
   // 最终产物png或者html;html下支持vchart渲染和交互
   output_type: 'png' | 'html'
+  // 语言,目前支持中文和英文
+  language: "zh" | "en"
 }
 ```
 
 ## 输出
-最终以'png'或者'html'的形式保存在本地，供后续agent使用
+最终以'png'或者'html'的形式保存在本地，输出保存的图表路径以及图表中发现的数据洞察
 
 ## VMind配置
 
@@ -55,7 +102,7 @@ VMind本身也需要通过调用大模型得到智能图表生成结果，目前
 
 ## 测试
 
-当前设置了两种不能难度的任务用于测试
+当前设置了三种不同难度的任务用于测试
 
 ### 简单图表生成任务
 
@@ -63,7 +110,7 @@ VMind本身也需要通过调用大模型得到智能图表生成结果，目前
 ```bash
 python -m app.tool.chart_visualization.test.simple_chart
 ```
-结果应位于`./data`下，涉及到9种不同的图表结果
+结果应位于`worksapce`下，涉及到9种不同的图表结果
 
 ### 简单数据报表任务
 
@@ -71,4 +118,13 @@ python -m app.tool.chart_visualization.test.simple_chart
 ```bash
 python -m app.tool.chart_visualization.test.simple_report
 ```
-结果同样位于`./data`下
+结果同样位于`worksapce`下
+
+### Manus 在线商店运营分析复刻
+
+复刻[manus结果](https://manus.im/share/c3onakN6Iajcm1Vt1xAVG7?replay=1)，执行命令如下：
+
+```
+python -m app.tool.chart_visualization.test.hack_demo
+```
+结果同样位于`worksapce`下
diff --git a/app/tool/chart_visualization/python_execute.py b/app/tool/chart_visualization/python_execute.py
index 5ebcc95..a87b72a 100644
--- a/app/tool/chart_visualization/python_execute.py
+++ b/app/tool/chart_visualization/python_execute.py
@@ -7,15 +7,7 @@ class NormalPythonExecute(PythonExecute):
 
     name: str = "python_execute"
     description: str = (
-        """Execute Python code for in-depth data analysis / data report(task conclusion) / other normal task without direct visualization.
-# Note
-1. The code should generate a comprehensive text-based report containing dataset overview, column details, basic statistics, derived metrics, timeseries comparisons, outliers, and key insights.
-2. Use print() for all outputs so the analysis (including sections like 'Dataset Overview' or 'Preprocessing Results') is clearly visible and save it also
-3. Save any report / processed files / each analysis result in worksapce directory: {directory}
-4. Data reports need to be content-rich, including your overall analysis process and corresponding data visualization.
-4. You can invode this tool step-by-step to do data analysis from summary to in-depth""".format(
-            directory=config.workspace_root
-        )
+        """Execute Python code for in-depth data analysis / data report(task conclusion) / other normal task without direct visualization."""
     )
     parameters: dict = {
         "type": "object",
@@ -28,6 +20,15 @@ class NormalPythonExecute(PythonExecute):
             },
             "code": {
                 "type": "string",
+                "description": """Python code to execute.
+# Note
+1. The code should generate a comprehensive text-based report containing dataset overview, column details, basic statistics, derived metrics, timeseries comparisons, outliers, and key insights.
+2. Use print() for all outputs so the analysis (including sections like 'Dataset Overview' or 'Preprocessing Results') is clearly visible and save it also
+3. Save any report / processed files / each analysis result in worksapce directory: {directory}
+4. Data reports need to be content-rich, including your overall analysis process and corresponding data visualization.
+5. You can invode this tool step-by-step to do data analysis from summary to in-depth with data report saved also""".format(
+                    directory=config.workspace_root
+                ),
             },
         },
         "required": ["code"],
diff --git a/app/tool/chart_visualization/test/hack_demo.py b/app/tool/chart_visualization/test/hack_demo.py
index cbb66a0..36a50f3 100644
--- a/app/tool/chart_visualization/test/hack_demo.py
+++ b/app/tool/chart_visualization/test/hack_demo.py
@@ -13,7 +13,7 @@ async def run_flow():
 
     try:
         prompt = """Here's January sales data from my Amazon store. Could you analyze it thoroughly with visualizations and recommend specific, data-driven strategies to boost next month's sales by 10%?
-File Path: workspace/amazon_sales_jan2025.csv
+data_file_path = "workspace/amazon_sales_jan.csv"
 """
 
         flow = FlowFactory.create_flow(
diff --git a/app/tool/chart_visualization/test/simple_chart.py b/app/tool/chart_visualization/test/simple_chart.py
index 66f9547..011ba58 100644
--- a/app/tool/chart_visualization/test/simple_chart.py
+++ b/app/tool/chart_visualization/test/simple_chart.py
@@ -3,7 +3,7 @@ import asyncio
 from app.agent.data_analysis import DataAnalysis
 from app.logger import logger
 
-prefix = "帮我生成图表并保存在本地./data下，具体为:"
+prefix = "帮我生成图表并保存在本地，具体为:"
 tasks = [
     {
         "prompt": "帮我展示不同区域各商品销售额",
diff --git a/workspace/amazon_sales_jan.csv b/workspace/amazon_sales_jan.csv
new file mode 100644
index 0000000..4583b76
--- /dev/null
+++ b/workspace/amazon_sales_jan.csv
@@ -0,0 +1,33 @@
+
+Date,Orders,Unique Customers,Units Sold,Gross Sales,Shipping Revenue,Coupon Discounts,Amazon Fees,Product Costs,Net Profit
+2025-01-01,32,32,90,4889.77,207.99,21.85,971.12,2077.17,1819.62
+2025-01-02,36,36,96,4972.16,231.16,26.48,990.58,2519.63,1435.47
+2025-01-03,73,73,205,9825.29,404.94,102.72,2000.86,4654.32,3067.4
+2025-01-04,41,41,98,5130.56,324.75,63.76,1030.67,2400.23,1635.91
+2025-01-05,44,44,106,5568.8,290.83,38.01,1110.14,2507.41,1913.24
+2025-01-06,59,59,176,9520,398.19,76.52,1888.17,4210.95,3344.35
+2025-01-07,30,30,69,3671.35,116.31,67.24,758.09,1652.76,1193.26
+2025-01-08,33,33,76,3994.76,203.96,42.57,809.22,1754.02,1388.94
+2025-01-09,34,34,72,3951.52,170.48,54.09,802.75,1815.56,1279.12
+2025-01-10,23,23,62,3668.6,163.86,27.04,697.75,1558.88,1384.95
+2025-01-11,40,39,99,5613.62,227.37,60.28,1096.68,2162.3,2294.33
+2025-01-12,56,56,143,7360.95,337.38,86.23,1471.73,3128.14,2674.85
+2025-01-13,28,28,87,4824.28,178.06,38.84,932.81,2182.23,1670.4
+2025-01-14,79,79,224,11752.01,498.92,157.39,2296.52,5288.05,4010.05
+2025-01-15,31,31,83,4417.38,162.41,22.98,879.71,1812.87,1701.81
+2025-01-16,22,22,63,3059.84,143.63,35.2,628.26,1501.43,894.94
+2025-01-17,61,61,153,8402.49,266.58,102.95,1653.07,3557.96,3088.52
+2025-01-18,45,45,111,5675.84,272.96,115.73,1154,2722.39,1683.73
+2025-01-19,50,50,130,7414.15,291.18,58.19,1432.57,3145.7,2777.71
+2025-01-20,25,25,57,2764.26,127.84,12.99,553.08,1327.38,870.81
+2025-01-21,71,70,174,9422.4,448.88,94.24,1886.04,4215.84,3226.28
+2025-01-22,27,27,85,4452.05,123.86,43.29,876.61,2144.1,1388.06
+2025-01-23,23,23,52,2743.56,169.7,16.61,571.97,1170.05,984.94
+2025-01-24,27,27,57,2916.34,128.36,80.67,588.89,1460.32,786.47
+2025-01-25,41,41,103,5169.94,283.01,57.09,1031.37,2473.02,1608.45
+2025-01-26,34,34,79,3872.66,214.95,17.74,791.34,1878.31,1185.27
+2025-01-27,27,27,67,3819.79,163.96,11.69,736.01,1466.49,1605.6
+2025-01-28,29,29,73,3763.56,219.63,39.17,754.63,1756.67,1213.09
+2025-01-29,28,28,73,3815.55,166.24,33.68,768.02,1627.24,1386.61
+2025-01-30,28,28,83,4088.25,170.95,27.9,820.94,1915.65,1323.77
+2025-01-31,36,36,91,5263.66,153.04,78.98,1037.9,2082.35,2064.44