AntV可视化(MCP 1.8)避坑指南

AntV Visualization（MCP v1.8）Debug 指南

這篇是給在 AntV visualization tool（MCP 1.8） 上踩坑的你：
整理了常見錯誤、如何快速定位問題、還有一份實戰可用的 Prompt 模板。看完你就能穩穩產出圖、不再卡關。

特別是在LLM回傳時候遇到 cannot access local variable 'data_style' where it is not associated with a value ，到底該怎麼解決呢？

---

常見三種 Bug

1. 欄位名不對（schema mismatch）
   工具的 data 每筆資料必須長這樣：

   { "category": "<string>", "value": <number> }
   

   如果你直接把查詢結果的鍵丟進去（例如 id / revenue），就會出錯。

2. 型別不對（type mismatch）

   • value 一定要是 number（"409950.5" 這樣的 字串會被拒絕）
   • category 一定要 string。如果你的類別是數字 ID（例如 382327），要先轉成 "382327"。

3. style 參數導致的 provider bug
   在 1.8 版常見錯誤訊息：
   cannot access local variable 'data_style' where it is not associated with a value
   → 解法：完全不要傳 style（任何層級都不要帶）。

---

診斷流程

1. 對齊欄位名

   • 錯誤示例（會報：'category' is a required property）：

     [{"id":"382327","revenue":"409950.5"}]
     

   • 正確示例（把鍵名改成 category / value）：

     [{"category":"382327","value":409950.5}]
     

2. 修正數值型別

   • 錯誤訊息：'409950.5' is not of type 'number'
   • 修法：把 "409950.5" 轉成 409950.5

3. 把數字類別轉字串

   • 規則：作為類別軸（xField）的欄位若是數字，一律轉成字串。
   • 例如 382327 → "382327"

4. 移除 style

   • 不要在任何層級放 "style": ...
   • 包含工具入參與最終 AntV 規格都一樣。

5. 成功就停（避免多跑一輪）

   • Orchestrator 常見問題：maximum_iterations 預設為 3，成功後還會再跑 Round 3，導致產生「多餘輸出」。

   • 解法二選一：

     • 把 maximum_iterations 調成 2；或
     • 在 Prompt 加上「成功就立刻停止」的規則（見下方模板的第 8 點）。

---

實戰建議 Prompt

## Prompt for AntV VisualizationYou are a professional data visualization assistant.  
Your task is to generate **AntV charts** based on the user’s query and the provided database JSON results.### Context
...### Rules:1. Always use the provided database schema and JSON data.
2. Select the most appropriate chart type (e.g., line, bar, pie, scatter, area) that best fits the user’s intent.
3. Do not invent columns or metrics that are not present in the schema or JSON data.
4. Return **only valid AntV chart**, don't need explain.
5. If the query result contains only a single aggregated value, still return a minimal chart (e.g., single-bar or single-number visualization) instead of plain text.
6. When generating AntV chart specifications, do NOT include the field "style" at any level.
7. If the field used as a category (e.g., xField) is numeric in the query results,always convert it to a string before generating the chart specification.
8. If the field used as a value (e.g., yField) is numeric but expressed as a string, always convert it to a number.
9. Always map fields for the "data" array as:- "category": the categorical dimension or ID (converted to string if numeric).- "value": the numeric measure/metric (converted to number if string).Do not use other field names like `id` or `revenue`.
10. If the tool call succeeds and returns a valid response, stop immediately. Do not generate additional outputs or iterations.### Output:If the tool call succeeds, return the result strictly as a Markdown image in the following format:
`![]({{imageUrl}})`If no chart can be generated (e.g., invalid data), return plain text output instead.