先問大家一個(gè)問題當(dāng)你在 AI 對(duì)話里說“幫我畫一張銷量趨勢(shì)圖”時(shí)你希望 AI 直接給出一段能運(yùn)行的 ECharts 代碼還是給你一張已經(jīng)渲染好的圖表頁面很多人的實(shí)際體驗(yàn)是AI 能寫代碼但代碼經(jīng)常跑不起來能識(shí)別數(shù)據(jù)但生成的圖表樣式完全不在線甚至同一個(gè) Skill 在 A 客戶端能用換到 B 客戶端就失效。這篇文章要講的就是我自己在 GitHub 上開源的一個(gè)高星圖表 Skill 項(xiàng)目的大版本更新。我會(huì)從 Skill 的設(shè)計(jì)理念、目錄結(jié)構(gòu)、配置方式、核心流程、常見坑位和工程實(shí)踐幾個(gè)維度展開盡量讓讀者既能理解 Skill 是什么也能直接照著配置一個(gè)屬于自己的圖表生成能力。如果你是 AI Agent 的開發(fā)者、知識(shí)庫搭建者或者日常用 Claude、ChatGPT 等工具做數(shù)據(jù)可視化這篇文章會(huì)比較適合你。讀完你可以掌握 Skill 的基本規(guī)范學(xué)會(huì)如何把圖表生成能力拆成可復(fù)用的 Skill 文件并了解這個(gè)開源項(xiàng)目更新后新增了哪些能力、解決了哪些舊版本痛點(diǎn)。2. 了解 Skill先搞清楚它解決什么問題Skill 這個(gè)概念在 AI 應(yīng)用圈子里越來越熱尤其是 Claude 的 Skills、ChatGPT 的 GPT Actions、各類 Agent 框架里的 Plugin本質(zhì)上都是一種“把特定能力封裝成可復(fù)用單元”的思路。簡單來講Skill 就是給大模型提供的一套“說明書 工具集合”告訴模型在什么場景下調(diào)用什么腳本、按什么流程輸出什么格式的內(nèi)容。圖表 Skill 則是專門用于“數(shù)據(jù)可視化”的 Skill。它解決的問題是大模型本身并不擅長精確控制圖形位置、顏色、動(dòng)畫和交互但它擅長理解自然語言意圖、分析數(shù)據(jù)結(jié)構(gòu)、選擇圖表類型。通過 Skill我們可以把“理解用戶需求”、“選擇圖表類型”、“生成圖表配置”、“輸出可運(yùn)行代碼”這幾個(gè)步驟固定下來讓每次生成的結(jié)果都穩(wěn)定可復(fù)現(xiàn)。比如傳統(tǒng)方式讓 AI 畫圖模型可能隨機(jī)發(fā)揮這次的代碼用 ECharts下次用 Chart.js再下次直接給一段 SVG。而圖表 Skill 會(huì)約定好輸出格式、代碼模板、數(shù)據(jù)字段映射規(guī)則最終用戶拿到的是風(fēng)格統(tǒng)一、配置完整、能直接預(yù)覽的方案。2.1 圖表 Skill 和普通提示詞的區(qū)別很多人會(huì)問我不就是用一段提示詞讓 AI 畫圖嗎為什么要多此一舉搞一個(gè) Skill這里有一個(gè)非常關(guān)鍵的區(qū)別提示詞是一次性的Skill 是結(jié)構(gòu)化的。普通提示詞是你在對(duì)話里說的話模型只能基于當(dāng)前上下文理解而 Skill 是一個(gè)文件目錄里面包含說明文檔、示例代碼、校驗(yàn)?zāi)_本、依賴配置。模型在執(zhí)行任務(wù)前會(huì)先讀取 Skill 目錄下的SKILL.md了解你預(yù)先定義的規(guī)則再調(diào)用你準(zhǔn)備好的工具腳本。這意味著規(guī)則可以長期復(fù)用不用每次重復(fù)描述。代碼生成邏輯可以被版本管理團(tuán)隊(duì)可以協(xié)作維護(hù)?？梢约尤胱詣?dòng)化校驗(yàn)比如 JSON 配置合法性檢查。輸出格式高度可控適合接入自動(dòng)化流水線。2.2 圖表 Skill 的典型應(yīng)用場景結(jié)合項(xiàng)目里收到的用戶反饋圖表 Skill 最常見的應(yīng)用場景有這么幾類數(shù)據(jù)分析報(bào)告自動(dòng)生成從數(shù)據(jù)庫讀取指標(biāo)自動(dòng)產(chǎn)出趨勢(shì)圖、占比圖、雷達(dá)圖。運(yùn)營周報(bào)可視化給出一組 Excel 或 CSV 數(shù)據(jù)快速生成適合公眾號(hào)、飛書文檔里的圖表。教學(xué)課件制作老師用自然語言描述成績分布Skill 生成適合演示的餅圖、柱狀圖。大屏可視化設(shè)計(jì)結(jié)合 ECharts 的科技感樣式生成帶動(dòng)態(tài)線條、中心占比的炫酷大屏組件。低代碼平臺(tái)圖表組件對(duì)接Skill 輸出標(biāo)準(zhǔn)化 JSON讓低代碼平臺(tái)直接解析渲染。這次大更新正是圍繞這些場景做了很多針對(duì)性優(yōu)化。3. 大更新之前先回顧舊版的設(shè)計(jì)思路在介紹新功能之前我想先簡單回顧一下這個(gè)項(xiàng)目早期的設(shè)計(jì)。這個(gè) Skill 最初是我在解決一個(gè)具體問題時(shí)的產(chǎn)物我當(dāng)時(shí)頻繁使用 AI 生成圖表但發(fā)現(xiàn)每次都要在提示詞里寫一堆要求比如“用 ECharts要求折線圖顏色不要超過三種字體要顯示中文”而且換一個(gè)對(duì)話窗口就得重新說一遍。痛定思痛我把這套“要求”沉淀成了文檔和模板放進(jìn)一個(gè)統(tǒng)一的 Skill 目錄里。舊版的設(shè)計(jì)大致是這樣chart-skill/ ├── SKILL.md ├── templates/ │ ├── bar_chart.json │ ├── line_chart.json │ ├── pie_chart.json │ └── radar_chart.json ├── examples/ │ ├── demo_data.csv │ └── generated_demo.html └── scripts/ └── validate_chart.pySKILL.md是核心入口告訴模型“你是圖表生成助手請(qǐng)按以下規(guī)則輸出”templates文件夾存放各種圖表的 JSON 模板模型參考模板生成配置examples提供輸入示例和預(yù)期輸出scripts/validate_chart.py用來校驗(yàn)生成的 JSON 是否符合 ECharts 配置規(guī)范。舊版上線后GitHub 上的關(guān)注度超出了我的預(yù)期。很多人通過這個(gè) Skill 解決了“AI 生成的圖表代碼跑不起來”的痛點(diǎn)。但與此同時(shí)用戶也反饋了很多問題這些問題構(gòu)成了這次大更新的核心驅(qū)動(dòng)力。3.1 舊版的主要痛點(diǎn)用戶反饋比較集中的問題有四個(gè)。第一模板機(jī)制太僵硬。舊版依賴固定 JSON 模板遇到用戶描述“我想做一個(gè)中心顯示數(shù)字、周圍散發(fā)動(dòng)態(tài)線條的圖”這種需求時(shí)模板匹配邏輯無法覆蓋模型只能在固定模板上硬改生成結(jié)果經(jīng)常出現(xiàn)配置沖突。第二數(shù)據(jù)處理能力弱。舊版只把 CSV 數(shù)據(jù)原樣交給模型模型經(jīng)常搞錯(cuò)字段類型比如把銷售額讀成字符串導(dǎo)致圖表坐標(biāo)軸數(shù)值異常。第三缺少代碼級(jí)驗(yàn)證。validate_chart.py只能校驗(yàn) JSON 語法校驗(yàn)不了配置項(xiàng)的瀏覽器兼容性比如某些高版本特性在低版本 ECharts 里根本不支持。第四對(duì)多端輸出適配不足。不同平臺(tái)渲染環(huán)境不一樣有的需要完整 HTML有的只需要 option 配置有的要適配移動(dòng)端。舊版沒有做輸出分層用戶拿到的成品經(jīng)常需要手動(dòng)調(diào)整。4. 大更新整體架構(gòu)從“模板匹配”到“生成管線”這次大更新沒有在舊代碼上面打補(bǔ)丁而是把整體架構(gòu)重新梳理了一遍核心思路從“模板匹配”轉(zhuǎn)變成了“生成管線”。所謂生成管線就是把圖表生成過程拆成幾個(gè)固定階段每個(gè)階段由 Skill 里的獨(dú)立模塊負(fù)責(zé)模型按照管線順序執(zhí)行。新的項(xiàng)目結(jié)構(gòu)長這樣chart-skill/ ├── SKILL.md ├── config/ │ ├── skill.yaml │ └── chart_register.json ├── modules/ │ ├── data_parser.py │ ├── chart_selector.py │ ├── option_builder.py │ ├── style_engine.py │ └── output_renderer.py ├── presets/ │ ├── default_theme.json │ ├── tech_dark_theme.json │ ├── business_light_theme.json │ └── minimal_theme.json ├── examples/ │ ├── sales_data.csv │ ├── user_requests.txt │ └── expected_output/ └── scripts/ ├── run_pipeline.py ├── validate_option.py └── create_skill_package.py這個(gè)結(jié)構(gòu)把原來只有“模板校驗(yàn)”的 Skill 擴(kuò)展成了“解析-選擇-構(gòu)建-美化-輸出”的五段式管線。下面我會(huì)逐個(gè)模塊解釋它的作用和更新思路。4.1 SKILL.md 的重新設(shè)計(jì)SKILL.md是整個(gè) Skill 的靈魂文件模型執(zhí)行任務(wù)前首先讀取它。新版不再是一段簡短的“你是圖表專家”提示詞而是寫成了結(jié)構(gòu)化指令文檔包含元信息、執(zhí)行流程、輸出規(guī)范和邊界約束。我們先來看SKILL.md的關(guān)鍵片段--- name: chart-skill description: 根據(jù)用戶描述和數(shù)據(jù)文件生成 ECharts 可視化方案 version: 2.0.0 author: your-name license: MIT --- # 圖表生成 Skill ## 角色定義 你是一名資深前端可視化工程師擅長 ECharts 圖表設(shè)計(jì)與實(shí)現(xiàn)。 ## 執(zhí)行流程 當(dāng)你收到用戶的圖表需求時(shí)必須按以下順序執(zhí)行 1. 調(diào)用 modules/data_parser.py 解析輸入數(shù)據(jù)。 2. 調(diào)用 modules/chart_selector.py 判斷最佳圖表類型。 3. 調(diào)用 modules/option_builder.py 構(gòu)建 ECharts option。 4. 調(diào)用 modules/style_engine.py 應(yīng)用主題樣式。 5. 調(diào)用 modules/output_renderer.py 輸出最終結(jié)果。 ## 輸出規(guī)范 - 所有輸出必須包含完整可運(yùn)行的 ECharts option。 - 輸出格式根據(jù)用戶要求支持三種 - json只輸出 option 配置。 - html輸出帶完整引入 ECharts CDN 的 HTML 文件。 - vue輸出 Vue 組件中的 option 片段。 ## 邊界約束 - 不要修改原始數(shù)據(jù)文件。 - 如果數(shù)據(jù)字段無法識(shí)別必須向用戶詢問不得自行猜測。 - 禁止使用自定義圖形注冊(cè)方式生成圖表統(tǒng)一使用 ECharts 標(biāo)準(zhǔn)配置。注意新版SKILL.md里的version、author、license信息這是為了讓 Skill 本身也能被版本管理。如果你在團(tuán)隊(duì)內(nèi)部通過 Git 倉庫分發(fā)版本號(hào)會(huì)幫助你追蹤變更。4.2 配置層skill.yaml 和 chart_register.jsonSkill 的行為不能全部寫死在提示詞里因?yàn)樘崾驹~越長模型越容易遺漏細(xì)節(jié)。所以新版引入了配置層把“哪些圖表類型可用”“各類型對(duì)應(yīng)什么模板”這類信息放到結(jié)構(gòu)化文件里。config/skill.yaml內(nèi)容示例name: chart-skill version: 2.0.0 default_theme: business_light supported_charts: - line - bar - pie - radar - scatter - funnel - gauge - hexagon output_formats: - json - html - vue max_data_rows: 5000 locale: zh-CN這里的supported_charts指定了 Skill 支持的圖表類型模型在chart_selector階段會(huì)參考這個(gè)列表做選擇題。hexagon是這次新增的“六邊形圖表”類型是很多用戶催更的功能后面我會(huì)專門介紹。config/chart_register.json則維護(hù)圖表類型和配置模塊的映射關(guān)系{ line: { module: option_builder, method: build_line, requires: [xAxis, yAxis, series] }, bar: { module: option_builder, method: build_bar, requires: [xAxis, yAxis, series] }, pie: { module: option_builder, method: build_pie, requires: [series] }, hexagon: { module: option_builder, method: build_hexagon, requires: [indicator, series] } }這樣做的好處是模型只需要根據(jù)chart_register.json找到對(duì)應(yīng)方法而不需要記憶每個(gè)圖表的全部配置細(xì)節(jié)。模板和邏輯分離后續(xù)新增圖表類型只需要注冊(cè)一個(gè)方法。4.3 數(shù)據(jù)解析模塊從“無腦讀取”到“智能識(shí)別”舊版直接讓模型讀 CSV結(jié)果經(jīng)常把數(shù)值列讀成字符串。新版增加了data_parser.py專門做數(shù)據(jù)清洗和類型推斷。下面是一個(gè)簡化版示例演示如何解析帶表頭的 CSV 并推斷字段類型# 文件路徑modules/data_parser.py import csv import json from datetime import datetime def parse_csv(file_path): 解析 CSV 文件推斷字段類型輸出標(biāo)準(zhǔn)化數(shù)據(jù)結(jié)構(gòu)。 with open(file_path, r, encodingutf-8) as f: reader csv.DictReader(f) rows list(reader) if not rows: raise ValueError(CSV 文件為空) columns list(rows[0].keys()) parsed {col: [] for col in columns} for row in rows: for col in columns: raw_value row[col].strip() parsed[col].append(convert_value(raw_value)) return { columns: columns, rows: parsed, row_count: len(rows), column_types: infer_types(parsed) } def convert_value(raw_value): 嘗試轉(zhuǎn)換值類型失敗則返回原始字符串。 # 處理空值 if raw_value or raw_value.lower() null: return None # 嘗試整數(shù) try: return int(raw_value) except ValueError: pass # 嘗試浮點(diǎn)數(shù)注意處理千分位逗號(hào) try: return float(raw_value.replace(,, )) except ValueError: pass # 嘗試日期 try: return datetime.strptime(raw_value, %Y-%m-%d).date().isoformat() except ValueError: pass return raw_value def infer_types(parsed_data): 根據(jù)實(shí)際值推斷每一列的類型。 type_map {} for col, values in parsed_data.items(): non_null [v for v in values if v is not None] if not non_null: type_map[col] empty elif all(isinstance(v, int) for v in non_null): type_map[col] integer elif all(isinstance(v, float) for v in non_null): type_map[col] float elif all(isinstance(v, str) for v in non_null): type_map[col] string elif all(hasattr(v, isoformat) for v in non_null): type_map[col] date else: type_map[col] mixed return type_map if __name__ __main__: # 簡單測試 sample examples/sales_data.csv result parse_csv(sample) print(json.dumps(result, ensure_asciiFalse, indent2, defaultstr))在SKILL.md的執(zhí)行流程中模型會(huì)先調(diào)用這個(gè)腳本解析數(shù)據(jù)然后根據(jù)column_types來決定哪些列適合做 X 軸、哪些適合做 Y 軸、哪些適合做維度。這比直接把原始文件丟給模型要可靠得多。4.4 圖表選擇模塊根據(jù)數(shù)據(jù)結(jié)構(gòu)自動(dòng)推薦類型圖表類型的選擇容易踩坑。用戶說“我要對(duì)比幾個(gè)部門的預(yù)算”模型可能隨手生成一個(gè)折線圖但實(shí)際上數(shù)據(jù)是離散的類別對(duì)比柱狀圖更合適。chart_selector.py的目標(biāo)是提供一套啟發(fā)式規(guī)則讓模型“先判斷再作圖”。# 文件路徑modules/chart_selector.py def select_chart_type(data, user_hintNone): 根據(jù)數(shù)據(jù)結(jié)構(gòu)和用戶意圖推薦圖表類型。 返回推薦類型和理由說明。 column_types data[column_types] row_count data[row_count] # 低于 30 行的數(shù)據(jù)優(yōu)先考慮柱狀圖或餅圖超過 30 行折線圖更合適 if row_count 30: return { chart_type: line, reason: 數(shù)據(jù)行數(shù)超過 30折線圖更適合展示連續(xù)趨勢(shì)。 } # 如果所有數(shù)值列只有一列且描述中包含占比份額等關(guān)鍵詞選擇餅圖 value_cols [c for c, t in column_types.items() if t in (integer, float)] category_cols [c for c, t in column_types.items() if t in (string, date)] if user_hint: hint user_hint.lower() if 占比 in hint or 份額 in hint or 比例 in hint: return {chart_type: pie, reason: 用戶明確提到占比/份額使用餅圖。} if 趨勢(shì) in hint or 變化 in hint: return {chart_type: line, reason: 用戶明確提到趨勢(shì)/變化使用折線圖。} if 對(duì)比 in hint or 排名 in hint: return {chart_type: bar, reason: 用戶明確提到對(duì)比/排名使用柱狀圖。} if 六邊形 in hint or 能力 in hint: return {chart_type: hexagon, reason: 用戶明確提到六邊形/能力使用六邊形圖。} # 缺省邏輯 if len(value_cols) 1 and len(category_cols) 1: return {chart_type: bar, reason: 存在類別維度和數(shù)值指標(biāo)柱狀圖是通用對(duì)比方案。} return {chart_type: pie, reason: 默認(rèn)使用餅圖展示構(gòu)成關(guān)系。}這個(gè)模塊不追求十全十美但能顯著減少模型“亂選類型”的問題。用戶如果對(duì)自己的需求有明確傾向也可以通過提示詞覆蓋自動(dòng)推薦結(jié)果。4.5 樣式引擎這次更新的重頭戲舊版的最大短板是視覺風(fēng)格不穩(wěn)定。同一個(gè)圖表這次生成出來是藍(lán)白配色下次變成紅黑配色再下次可能用了很奇怪的漸變。新版引入了style_engine.py和presets/目錄。預(yù)設(shè)主題包括default_theme.json默認(rèn)主題適合大多數(shù)場景。business_light.json商務(wù)淺色適合 PPT 和報(bào)告。tech_dark.json科技深色適合大屏帶發(fā)光效果和動(dòng)態(tài)線條。minimal_theme.json極簡風(fēng)格干凈留白。我們看一個(gè)簡化版的style_engine.py# 文件路徑modules/style_engine.py import json import os def load_theme(theme_name): 加載預(yù)設(shè)主題文件。 preset_dir os.path.join(os.path.dirname(__file__), .., presets) theme_path os.path.join(preset_dir, f{theme_name}.json) if not os.path.exists(theme_path): raise FileNotFoundError(f主題 {theme_name} 不存在) with open(theme_path, r, encodingutf-8) as f: return json.load(f) def apply_theme(option, theme_namebusiness_light): 將主題應(yīng)用到 ECharts option 上。 會(huì)合并 color、backgroundColor、textStyle 等字段。 theme load_theme(theme_name) # 合并顏色 if color in theme: option[color] theme[color] # 合并背景色 if backgroundColor in theme: option[backgroundColor] theme[backgroundColor] # 合并文本樣式 if textStyle in theme: text_style option.get(textStyle, {}) text_style.update(theme[textStyle]) option[textStyle] text_style # 處理標(biāo)題樣式 if title in theme and title in option: option[title].update(theme[title]) # 處理圖例樣式 if legend in theme and legend in option: option[legend].update(theme[legend]) return option用戶反饋里提到的“中心是數(shù)字占比周圍散發(fā)長短不一的動(dòng)態(tài)線條”效果我在tech_dark主題里做了專門優(yōu)化。這個(gè)效果本質(zhì)上是把series配置成pie和lines組合中心用graphic元素顯示數(shù)字外圍用lines系列生成隨機(jī)長短的動(dòng)畫線條。如果你需要獨(dú)立實(shí)現(xiàn)這個(gè)效果可以參考下面的 ECharts 核心片段option { backgroundColor: #0f1c2e, graphic: [ { type: text, left: center, top: 42%, style: { text: 68%, textAlign: center, fill: #ffffff, fontSize: 48, fontWeight: bold } } ], series: [ { type: pie, radius: [55%, 70%], center: [50%, 50%], label: { show: false }, data: [ { value: 68, name: 完成率, itemStyle: { color: #3fa7ff } }, { value: 32, name: 缺口, itemStyle: { color: #1a3455 } } ] }, { type: lines, coordinateSystem: polar, data: generateRandomLines(24), lineStyle: { color: #3fa7ff, width: 1, opacity: 0.6, curveness: 0.2 }, effect: { show: true, period: 4, trailLength: 0.6, symbol: circle, symbolSize: 3 } } ], polar: { center: [50%, 50%], radius: 65% } }; function generateRandomLines(count) { const lines []; for (let i 0; i count; i) { lines.push({ coords: [ [0, 0], [Math.random() * 10 5, Math.random() * 360] ] }); } return lines; }這段代碼在 ECharts 5.x 中可以直接運(yùn)行。如果你部署在大屏上配合tech_dark主題的動(dòng)態(tài)感會(huì)更強(qiáng)。4.6 多格式輸出json、html、vue 三端適配新版在輸出層做了很大的調(diào)整。output_renderer.py負(fù)責(zé)根據(jù)用戶需求輸出不同格式j(luò)son只輸出純 ECharts option方便嵌入已有項(xiàng)目。html輸出完整 HTML 文件包含 ECharts CDN 引入和初始化邏輯。vue輸出 Vue 3 組件里的options數(shù)據(jù)和mounted初始化代碼。以html輸出為例渲染邏輯大致是這樣的# 文件路徑modules/output_renderer.py HTML_TEMPLATE !DOCTYPE html html langzh-CN head meta charsetUTF-8 title{title}/title script srchttps://cdn.jsdelivr.net/npm/echarts5/dist/echarts.min.js/script style body {{ margin: 0; padding: 20px; background: {background}; }} #chart {{ width: 100%; height: 600px; }} /style /head body div idchart/div script const chart echarts.init(document.getElementById(chart)); const option {option_json}; chart.setOption(option); window.addEventListener(resize, () chart.resize()); /script /body /html def render_html(option, titleChart): background option.get(backgroundColor, #ffffff) option_json json.dumps(option, ensure_asciiFalse, indent2) return HTML_TEMPLATE.format( titletitle, backgroundbackground, option_jsonoption_json )這個(gè)模板看起來簡單但解決了幾個(gè)常見問題自動(dòng)添加resize監(jiān)聽、自動(dòng)適配背景色、CDN 版本固定。用戶不會(huì)再因?yàn)閣indow.resize漏寫導(dǎo)致頁面縮放圖表不跟著變。5. 完整實(shí)戰(zhàn)從 GitHub 拉取 Skill 到生成第一張圖表前面講了架構(gòu)現(xiàn)在帶大家實(shí)操一遍完整的流程。我會(huì)以“獲取項(xiàng)目、配置環(huán)境、運(yùn)行管線、生成圖表”四個(gè)步驟為例。5.1 從 GitHub 獲取項(xiàng)目開源項(xiàng)目一般托管在 GitHub 上。如果你是用git clone方式獲取命令如下git clone https://github.com/your-name/chart-skill.git cd chart-skill如果你項(xiàng)目的目錄名不叫chart-skill以實(shí)際倉庫名為準(zhǔn)。國內(nèi)訪問 GitHub 速度不理想時(shí)可以使用 GitHub 鏡像站或加速下載工具。這里強(qiáng)調(diào)一點(diǎn)下載開源項(xiàng)目請(qǐng)盡量從原始倉庫地址獲取避免使用不明來源的二次打包文件防止代碼被篡改。5.2 環(huán)境準(zhǔn)備這個(gè)項(xiàng)目的核心代碼使用 Python 3 編寫不依賴第三方包標(biāo)準(zhǔn)庫即可運(yùn)行。也就是說只要你的電腦安裝了 Python 3.8 及以上版本就能直接跑通數(shù)據(jù)解析和管線腳本。可以用下面的命令檢查 Python 版本python3 --version如果你在 Windows 環(huán)境可能需要使用python而不是python3根據(jù)你的環(huán)境變量設(shè)置調(diào)整即可。5.3 準(zhǔn)備演示數(shù)據(jù)examples/目錄下我放了一份示例銷售數(shù)據(jù)sales_data.csv內(nèi)容大致如下月份,銷售額,訂單量,客戶數(shù) 2024-01,128000,342,58 2024-02,142000,378,64 2024-03,156000,401,69 2024-04,138000,366,61 2024-05,172000,421,77 2024-06,188000,458,83 2024-07,195000,472,86 2024-08,210000,503,92 2024-09,226000,531,98 2024-10,218000,517,95 2024-11,254000,589,106 2024-12,276000,632,114這份數(shù)據(jù)包含日期、金額、數(shù)量、客戶數(shù)四個(gè)字段適合測試柱狀圖、折線圖和混合圖。5.4 運(yùn)行數(shù)據(jù)解析模塊先直接運(yùn)行數(shù)據(jù)解析模塊看看結(jié)果python modules/data_parser.py預(yù)期輸出會(huì)顯示字段類型推斷結(jié)果。如果你看到月份被推斷為string而不是date是正常的因?yàn)?024-01這個(gè)格式默認(rèn)沒有轉(zhuǎn)換成日期我建議保留為字符串類型在 ECharts 中直接用類目軸顯示會(huì)更直觀。5.5 調(diào)用 Skill 生成圖表Skill 的常規(guī)使用方式是在支持 Skill 的 AI 客戶端中引用SKILL.md路徑。假設(shè)你使用的是 Claude Desktop、Cherry Studio 或類似的 Skill 客戶端你需要在當(dāng)前會(huì)話中加載這個(gè)目錄。加載后你可以直接輸入需求用 examples/sales_data.csv 的數(shù)據(jù)畫一張?jiān)露蠕N售額柱狀圖使用 business_light 主題輸出 html 格式。模型會(huì)按照SKILL.md的執(zhí)行流程調(diào)用各模塊最終生成一個(gè) HTML 文件。如果你不希望依賴 AI 客戶端也可以直接運(yùn)行管線腳本python scripts/run_pipeline.py \ --data examples/sales_data.csv \ --chart bar \ --theme business_light \ --format html \ --output output/sales_bar.htmlrun_pipeline.py是一個(gè)簡化版的調(diào)度腳本它把數(shù)據(jù)解析、圖表選擇、配置構(gòu)建、樣式應(yīng)用、輸出渲染串聯(lián)起來。腳本執(zhí)行完成后會(huì)在output/目錄生成一個(gè)可打開的 HTML 圖表文件。5.6 驗(yàn)證生成的圖表配置為了減少“代碼跑不起來”的問題新版增加了validate_option.py校驗(yàn)?zāi)_本python scripts/validate_option.py output/option.json它會(huì)遞歸檢查 option 中是否有未定義的系列類型、是否缺少必填字段、series 長度是否匹配。校驗(yàn)通過后才建議把配置投入生產(chǎn)。6. 新增亮點(diǎn)六邊形圖表與個(gè)性化圖表生成這次更新有一個(gè)讓我印象很深的需求很多用戶希望生成“六邊形圖表”用于能力評(píng)估、技能畫像、綜合素質(zhì)展示。六邊形圖表本質(zhì)上是 ECharts 的雷達(dá)圖radar但做了一些視覺定制指標(biāo)點(diǎn)放在六邊形的頂點(diǎn)上連線形成封閉多邊形中心位置可以顯示綜合評(píng)分。為了這個(gè)功能我在chart_register.json里新增了hexagon類型并在option_builder.py中實(shí)現(xiàn)了build_hexagon方法。核心邏輯是讓模型把多列數(shù)值歸一化到 0-100 區(qū)間然后生成雷達(dá)圖配置。下面是一個(gè)六邊形圖表的 option 示例{ radar: { indicator: [ { name: 技術(shù)深度, max: 100 }, { name: 業(yè)務(wù)理解, max: 100 }, { name: 溝通協(xié)作, max: 100 }, { name: 學(xué)習(xí)能力, max: 100 }, { name: 抗壓能力, max: 100 }, { name: 創(chuàng)新能力, max: 100 } ], radius: 65%, shape: polygon, splitNumber: 5, axisName: { color: #333, fontSize: 14 }, splitArea: { areaStyle: { color: [rgba(63, 167, 255, 0.02), rgba(63, 167, 255, 0.04)] } } }, series: [ { type: radar, data: [ { value: [92, 78, 85, 88, 90, 82], name: 當(dāng)前員工, areaStyle: { color: rgba(63, 167, 255, 0.3) }, lineStyle: { color: #3fa7ff, width: 2 } }, { value: [80, 75, 80, 85, 82, 78], name: 團(tuán)隊(duì)平均, areaStyle: { color: rgba(255, 159, 64, 0.2) }, lineStyle: { color: #ff9f40, width: 2, type: dashed } } ] } ] }如果你在 AI 對(duì)話里提到了“六邊形”、“能力雷達(dá)”、“員工畫像”這些詞chart_selector.py會(huì)優(yōu)先推薦hexagon類型不再需要用戶手寫完整 radar 配置。7. 常見問題與排查清單新版本上線后用戶咨詢的問題集中在幾個(gè)固定場景。我把高頻問題的排查方案整理成表格方便你直接對(duì)照處理。問題現(xiàn)象常見原因解決思路Skill 加載后在 AI 客戶端中不生效客戶端不支持讀取本地目錄或路徑含中文/空格確認(rèn)客戶端支持 Skill 功能路徑建議使用純英文或把 Skill 打包為插件格式生成的圖表中文亂碼HTML 缺少charsetutf-8或 ECharts CDN 加載失敗檢查輸出 HTML 模板是否包含 meta charset優(yōu)先使用 jsdelivr 等穩(wěn)定 CDN下載項(xiàng)目后沒有SKILL.md倉庫默認(rèn)分支不是 main或克隆不完整檢查分支名使用git clone -b main指定分支確認(rèn)倉庫根目錄文件完整run_pipeline.py提示找不到模塊當(dāng)前工作目錄不在項(xiàng)目根目錄先執(zhí)行cd到項(xiàng)目根目錄再運(yùn)行腳本生成的 option 在 ECharts 中報(bào)錯(cuò)series 類型或字段名錯(cuò)誤使用validate_option.py校驗(yàn)對(duì)照 ECharts 官方文檔確認(rèn)版本兼容性大屏圖表動(dòng)態(tài)效果不明顯未使用tech_dark主題或 effect 配置未開啟指定--theme tech_dark檢查effect.show是否為 true想把 Skill 集成到自己的 Agent 項(xiàng)目缺少環(huán)境變量或配置映射閱讀config/skill.yaml將supported_charts與 Agent 的意圖識(shí)別模塊對(duì)接除了表格里的問題還有一個(gè)非常容易踩的坑在 Python 腳本中直接使用from modules.xxx import導(dǎo)入模塊時(shí)不同系統(tǒng)對(duì)當(dāng)前路徑的處理方式不同。如果你在 Windows 的 PowerShell 下執(zhí)行務(wù)必先確認(rèn)當(dāng)前目錄是項(xiàng)目根目錄。如果你在 VS Code 里調(diào)試建議先把工作目錄設(shè)置為項(xiàng)目根目錄。8. 最佳實(shí)踐與工程建議前面把功能都過了一遍這一節(jié)我想分享一些從項(xiàng)目維護(hù)和社區(qū)反饋中沉淀下來的工程建議這些建議在你自己開發(fā) Skill 時(shí)同樣適用。8.1 把提示詞和可執(zhí)行代碼分開管理這是 Skill 設(shè)計(jì)中最重要的一條原則。SKILL.md里寫清楚“做什么”scripts/和modules/里寫清楚“怎么做”。如果你把所有邏輯都塞進(jìn)提示詞模型每次運(yùn)行時(shí)都要處理大量文本容易出錯(cuò)且執(zhí)行不穩(wěn)定。更好的做法是提示詞只描述流程和邊界具體的數(shù)據(jù)處理、校驗(yàn)、渲染交給腳本。8.2 為每個(gè) Skill 維護(hù)一份版本元信息我建議在 Skill 項(xiàng)目根目錄或者config/skill.yaml里寫清楚版本號(hào)、依賴環(huán)境、作者、許可證。如果不寫版本團(tuán)隊(duì)里多個(gè)人同時(shí)維護(hù)時(shí)很容易出現(xiàn)“這個(gè)腳本改了但不知道是哪個(gè)版本”的問題。引入 Git 標(biāo)簽或者 GitHub Release 也是很好的做法。8.3 數(shù)據(jù)安全邊界要提前劃清圖表 Skill 通常需要讀取數(shù)據(jù)文件這里要特別強(qiáng)調(diào)不要在 Skill 里內(nèi)置“讀取任意路徑文件”的能力更不要允許模型自動(dòng)修改原始數(shù)據(jù)文件。在SKILL.md的邊界約束里明確寫出“禁止修改原始數(shù)據(jù)”并讓腳本在讀取文件時(shí)校驗(yàn)文件擴(kuò)展名和大小。涉及敏感數(shù)據(jù)時(shí)建議在沙箱環(huán)境運(yùn)行并做好脫敏處理。8.4 輸出結(jié)果要做兩級(jí)校驗(yàn)第一級(jí)是語法校驗(yàn)即 JSON 是否能被正確解析第二級(jí)是業(yè)務(wù)校驗(yàn)即圖表是否適合表達(dá)當(dāng)前數(shù)據(jù)。如果你的 Skill 有能力運(yùn)行 ECharts 的 SSR 渲染可以把生成的配置用echarts的 nodejs 端渲染一次確認(rèn)沒有運(yùn)行時(shí)錯(cuò)誤。如果不具備條件至少保留validate_option.py之類的靜態(tài)校驗(yàn)?zāi)_本。8.5 不要迷信某一個(gè) CDN國內(nèi)訪問 ECharts CDN 有時(shí)不穩(wěn)定尤其是公共服務(wù)器的網(wǎng)絡(luò)波動(dòng)。在輸出 HTML 時(shí)可以考慮提供多個(gè) CDN 源備用或者提示用戶下載 ECharts 到本地。不過 CDN 選擇屬于部署細(xì)節(jié)建議把可用性測試納入 Skill 的驗(yàn)收流程。8.6 考慮輸出分層和二次編輯需求用戶拿到圖表的最終目的往往不是“看一次”而是“放進(jìn)報(bào)告里再改改”。如果 Skill 輸出的 HTML 是純靜態(tài)的后續(xù)修改會(huì)很麻煩。我在新版中加入了“配置導(dǎo)出”按鈕用戶可以在頁面上調(diào)整顏色、標(biāo)題后直接導(dǎo)出 JSON。類似思路可以引用到你自己的項(xiàng)目里不要只輸出一次性的結(jié)果給用戶留一條可編輯的路徑。8.7 遇到類型推斷不準(zhǔn)時(shí)給用戶糾錯(cuò)入口即使是精心設(shè)計(jì)的數(shù)據(jù)解析模塊也無法覆蓋所有真實(shí)數(shù)據(jù)場景。我的做法是當(dāng)column_types中存在mixed類型時(shí)在輸出中提示用戶手動(dòng)指定字段類型而不是讓模型擅自處理。如果你在生成管道中發(fā)現(xiàn)了同樣的現(xiàn)象建議參考這個(gè)處理策略。9. 后續(xù)規(guī)劃與可復(fù)用思路這次大更新并不是終點(diǎn)項(xiàng)目迭代的方向會(huì)集中在三個(gè)方面。第一是支持更多圖表類型和視覺主題計(jì)劃補(bǔ)充?；鶊D、關(guān)系圖、儀表盤圖等同時(shí)增加暗黑科技、漸變玻璃擬態(tài)等主題風(fēng)格。第二是增加“數(shù)據(jù)源對(duì)接”能力不再局限于 CSV 文件支持直接連接 MySQL、PostgreSQL、SQLite 等數(shù)據(jù)庫讓 Skill 能直接查詢指標(biāo)生成圖表。第三是完善多語言支持讓 Skill 的說明文檔和輸出內(nèi)容能適配英文、日文等場景。如果你也想開發(fā)類似的 Skill我的建議是不要一開始追求大而全先從一個(gè)痛點(diǎn)場景出發(fā)。比如你先做“銷售周報(bào)圖表生成”這個(gè)細(xì)分能力跑通后沉淀出data_parser、chart_selector、output_renderer這些通用模塊再逐步擴(kuò)展到更多場景。這個(gè)開源項(xiàng)目就是這么一步步走過來的。實(shí)際去動(dòng)手配置一次你才會(huì)更清楚地理解“提示詞”和“Skill”之間的差別。如果你用它生成了不錯(cuò)的圖表或者后續(xù)自己封裝了新的圖表類型也歡迎分享出來一起迭代。