先問大家一個問題當你在 AI 對話里說“幫我畫一張銷量趨勢圖”時你希望 AI 直接給出一段能運行的 ECharts 代碼還是給你一張已經(jīng)渲染好的圖表頁面很多人的實際體驗是AI 能寫代碼但代碼經(jīng)常跑不起來能識別數(shù)據(jù)但生成的圖表樣式完全不在線甚至同一個 Skill 在 A 客戶端能用換到 B 客戶端就失效。這篇文章要講的就是我自己在 GitHub 上開源的一個高星圖表 Skill 項目的大版本更新。我會從 Skill 的設計理念、目錄結(jié)構(gòu)、配置方式、核心流程、常見坑位和工程實踐幾個維度展開盡量讓讀者既能理解 Skill 是什么也能直接照著配置一個屬于自己的圖表生成能力。如果你是 AI Agent 的開發(fā)者、知識庫搭建者或者日常用 Claude、ChatGPT 等工具做數(shù)據(jù)可視化這篇文章會比較適合你。讀完你可以掌握 Skill 的基本規(guī)范學會如何把圖表生成能力拆成可復用的 Skill 文件并了解這個開源項目更新后新增了哪些能力、解決了哪些舊版本痛點。2. 了解 Skill先搞清楚它解決什么問題Skill 這個概念在 AI 應用圈子里越來越熱尤其是 Claude 的 Skills、ChatGPT 的 GPT Actions、各類 Agent 框架里的 Plugin本質(zhì)上都是一種“把特定能力封裝成可復用單元”的思路。簡單來講Skill 就是給大模型提供的一套“說明書 工具集合”告訴模型在什么場景下調(diào)用什么腳本、按什么流程輸出什么格式的內(nèi)容。圖表 Skill 則是專門用于“數(shù)據(jù)可視化”的 Skill。它解決的問題是大模型本身并不擅長精確控制圖形位置、顏色、動畫和交互但它擅長理解自然語言意圖、分析數(shù)據(jù)結(jié)構(gòu)、選擇圖表類型。通過 Skill我們可以把“理解用戶需求”、“選擇圖表類型”、“生成圖表配置”、“輸出可運行代碼”這幾個步驟固定下來讓每次生成的結(jié)果都穩(wěn)定可復現(xiàn)。比如傳統(tǒng)方式讓 AI 畫圖模型可能隨機發(fā)揮這次的代碼用 ECharts下次用 Chart.js再下次直接給一段 SVG。而圖表 Skill 會約定好輸出格式、代碼模板、數(shù)據(jù)字段映射規(guī)則最終用戶拿到的是風格統(tǒng)一、配置完整、能直接預覽的方案。2.1 圖表 Skill 和普通提示詞的區(qū)別很多人會問我不就是用一段提示詞讓 AI 畫圖嗎為什么要多此一舉搞一個 Skill這里有一個非常關鍵的區(qū)別提示詞是一次性的Skill 是結(jié)構(gòu)化的。普通提示詞是你在對話里說的話模型只能基于當前上下文理解而 Skill 是一個文件目錄里面包含說明文檔、示例代碼、校驗腳本、依賴配置。模型在執(zhí)行任務前會先讀取 Skill 目錄下的SKILL.md了解你預先定義的規(guī)則再調(diào)用你準備好的工具腳本。這意味著規(guī)則可以長期復用不用每次重復描述。代碼生成邏輯可以被版本管理團隊可以協(xié)作維護?？梢约尤胱詣踊ｒ灡热?JSON 配置合法性檢查。輸出格式高度可控適合接入自動化流水線。2.2 圖表 Skill 的典型應用場景結(jié)合項目里收到的用戶反饋圖表 Skill 最常見的應用場景有這么幾類數(shù)據(jù)分析報告自動生成從數(shù)據(jù)庫讀取指標自動產(chǎn)出趨勢圖、占比圖、雷達圖。運營周報可視化給出一組 Excel 或 CSV 數(shù)據(jù)快速生成適合公眾號、飛書文檔里的圖表。教學課件制作老師用自然語言描述成績分布Skill 生成適合演示的餅圖、柱狀圖。大屏可視化設計結(jié)合 ECharts 的科技感樣式生成帶動態(tài)線條、中心占比的炫酷大屏組件。低代碼平臺圖表組件對接Skill 輸出標準化 JSON讓低代碼平臺直接解析渲染。這次大更新正是圍繞這些場景做了很多針對性優(yōu)化。3. 大更新之前先回顧舊版的設計思路在介紹新功能之前我想先簡單回顧一下這個項目早期的設計。這個 Skill 最初是我在解決一個具體問題時的產(chǎn)物我當時頻繁使用 AI 生成圖表但發(fā)現(xiàn)每次都要在提示詞里寫一堆要求比如“用 ECharts要求折線圖顏色不要超過三種字體要顯示中文”而且換一個對話窗口就得重新說一遍。痛定思痛我把這套“要求”沉淀成了文檔和模板放進一個統(tǒng)一的 Skill 目錄里。舊版的設計大致是這樣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是核心入口告訴模型“你是圖表生成助手請按以下規(guī)則輸出”templates文件夾存放各種圖表的 JSON 模板模型參考模板生成配置examples提供輸入示例和預期輸出scripts/validate_chart.py用來校驗生成的 JSON 是否符合 ECharts 配置規(guī)范。舊版上線后GitHub 上的關注度超出了我的預期。很多人通過這個 Skill 解決了“AI 生成的圖表代碼跑不起來”的痛點。但與此同時用戶也反饋了很多問題這些問題構(gòu)成了這次大更新的核心驅(qū)動力。3.1 舊版的主要痛點用戶反饋比較集中的問題有四個。第一模板機制太僵硬。舊版依賴固定 JSON 模板遇到用戶描述“我想做一個中心顯示數(shù)字、周圍散發(fā)動態(tài)線條的圖”這種需求時模板匹配邏輯無法覆蓋模型只能在固定模板上硬改生成結(jié)果經(jīng)常出現(xiàn)配置沖突。第二數(shù)據(jù)處理能力弱。舊版只把 CSV 數(shù)據(jù)原樣交給模型模型經(jīng)常搞錯字段類型比如把銷售額讀成字符串導致圖表坐標軸數(shù)值異常。第三缺少代碼級驗證。validate_chart.py只能校驗 JSON 語法校驗不了配置項的瀏覽器兼容性比如某些高版本特性在低版本 ECharts 里根本不支持。第四對多端輸出適配不足。不同平臺渲染環(huán)境不一樣有的需要完整 HTML有的只需要 option 配置有的要適配移動端。舊版沒有做輸出分層用戶拿到的成品經(jīng)常需要手動調(diào)整。4. 大更新整體架構(gòu)從“模板匹配”到“生成管線”這次大更新沒有在舊代碼上面打補丁而是把整體架構(gòu)重新梳理了一遍核心思路從“模板匹配”轉(zhuǎn)變成了“生成管線”。所謂生成管線就是把圖表生成過程拆成幾個固定階段每個階段由 Skill 里的獨立模塊負責模型按照管線順序執(zhí)行。新的項目結(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這個結(jié)構(gòu)把原來只有“模板校驗”的 Skill 擴展成了“解析-選擇-構(gòu)建-美化-輸出”的五段式管線。下面我會逐個模塊解釋它的作用和更新思路。4.1 SKILL.md 的重新設計SKILL.md是整個 Skill 的靈魂文件模型執(zhí)行任務前首先讀取它。新版不再是一段簡短的“你是圖表專家”提示詞而是寫成了結(jié)構(gòu)化指令文檔包含元信息、執(zhí)行流程、輸出規(guī)范和邊界約束。我們先來看SKILL.md的關鍵片段--- name: chart-skill description: 根據(jù)用戶描述和數(shù)據(jù)文件生成 ECharts 可視化方案 version: 2.0.0 author: your-name license: MIT --- # 圖表生成 Skill ## 角色定義 你是一名資深前端可視化工程師擅長 ECharts 圖表設計與實現(xiàn)。 ## 執(zhí)行流程 當你收到用戶的圖表需求時必須按以下順序執(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 應用主題樣式。 5. 調(diào)用 modules/output_renderer.py 輸出最終結(jié)果。 ## 輸出規(guī)范 - 所有輸出必須包含完整可運行的 ECharts option。 - 輸出格式根據(jù)用戶要求支持三種 - json只輸出 option 配置。 - html輸出帶完整引入 ECharts CDN 的 HTML 文件。 - vue輸出 Vue 組件中的 option 片段。 ## 邊界約束 - 不要修改原始數(shù)據(jù)文件。 - 如果數(shù)據(jù)字段無法識別必須向用戶詢問不得自行猜測。 - 禁止使用自定義圖形注冊方式生成圖表統(tǒng)一使用 ECharts 標準配置。注意新版SKILL.md里的version、author、license信息這是為了讓 Skill 本身也能被版本管理。如果你在團隊內(nèi)部通過 Git 倉庫分發(fā)版本號會幫助你追蹤變更。4.2 配置層skill.yaml 和 chart_register.jsonSkill 的行為不能全部寫死在提示詞里因為提示詞越長模型越容易遺漏細節(jié)。所以新版引入了配置層把“哪些圖表類型可用”“各類型對應什么模板”這類信息放到結(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階段會參考這個列表做選擇題。hexagon是這次新增的“六邊形圖表”類型是很多用戶催更的功能后面我會專門介紹。config/chart_register.json則維護圖表類型和配置模塊的映射關系{ 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找到對應方法而不需要記憶每個圖表的全部配置細節(jié)。模板和邏輯分離后續(xù)新增圖表類型只需要注冊一個方法。4.3 數(shù)據(jù)解析模塊從“無腦讀取”到“智能識別”舊版直接讓模型讀 CSV結(jié)果經(jīng)常把數(shù)值列讀成字符串。新版增加了data_parser.py專門做數(shù)據(jù)清洗和類型推斷。下面是一個簡化版示例演示如何解析帶表頭的 CSV 并推斷字段類型# 文件路徑modules/data_parser.py import csv import json from datetime import datetime def parse_csv(file_path): 解析 CSV 文件推斷字段類型輸出標準化數(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 # 嘗試浮點數(shù)注意處理千分位逗號 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ù)實際值推斷每一列的類型。 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í)行流程中模型會先調(diào)用這個腳本解析數(shù)據(jù)然后根據(jù)column_types來決定哪些列適合做 X 軸、哪些適合做 Y 軸、哪些適合做維度。這比直接把原始文件丟給模型要可靠得多。4.4 圖表選擇模塊根據(jù)數(shù)據(jù)結(jié)構(gòu)自動推薦類型圖表類型的選擇容易踩坑。用戶說“我要對比幾個部門的預算”模型可能隨手生成一個折線圖但實際上數(shù)據(jù)是離散的類別對比柱狀圖更合適。chart_selector.py的目標是提供一套啟發(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ù)值列只有一列且描述中包含占比份額等關鍵詞選擇餅圖 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 趨勢 in hint or 變化 in hint: return {chart_type: line, reason: 用戶明確提到趨勢/變化使用折線圖。} if 對比 in hint or 排名 in hint: return {chart_type: bar, reason: 用戶明確提到對比/排名使用柱狀圖。} 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ù)值指標柱狀圖是通用對比方案。} return {chart_type: pie, reason: 默認使用餅圖展示構(gòu)成關系。}這個模塊不追求十全十美但能顯著減少模型“亂選類型”的問題。用戶如果對自己的需求有明確傾向也可以通過提示詞覆蓋自動推薦結(jié)果。4.5 樣式引擎這次更新的重頭戲舊版的最大短板是視覺風格不穩(wěn)定。同一個圖表這次生成出來是藍白配色下次變成紅黑配色再下次可能用了很奇怪的漸變。新版引入了style_engine.py和presets/目錄。預設主題包括default_theme.json默認主題適合大多數(shù)場景。business_light.json商務淺色適合 PPT 和報告。tech_dark.json科技深色適合大屏帶發(fā)光效果和動態(tài)線條。minimal_theme.json極簡風格干凈留白。我們看一個簡化版的style_engine.py# 文件路徑modules/style_engine.py import json import os def load_theme(theme_name): 加載預設主題文件。 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): 將主題應用到 ECharts option 上。 會合并 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 # 處理標題樣式 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ā)長短不一的動態(tài)線條”效果我在tech_dark主題里做了專門優(yōu)化。這個效果本質(zhì)上是把series配置成pie和lines組合中心用graphic元素顯示數(shù)字外圍用lines系列生成隨機長短的動畫線條。如果你需要獨立實現(xiàn)這個效果可以參考下面的 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 中可以直接運行。如果你部署在大屏上配合tech_dark主題的動態(tài)感會更強。4.6 多格式輸出json、html、vue 三端適配新版在輸出層做了很大的調(diào)整。output_renderer.py負責根據(jù)用戶需求輸出不同格式json只輸出純 ECharts option方便嵌入已有項目。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 )這個模板看起來簡單但解決了幾個常見問題自動添加resize監(jiān)聽、自動適配背景色、CDN 版本固定。用戶不會再因為window.resize漏寫導致頁面縮放圖表不跟著變。5. 完整實戰(zhàn)從 GitHub 拉取 Skill 到生成第一張圖表前面講了架構(gòu)現(xiàn)在帶大家實操一遍完整的流程。我會以“獲取項目、配置環(huán)境、運行管線、生成圖表”四個步驟為例。5.1 從 GitHub 獲取項目開源項目一般托管在 GitHub 上。如果你是用git clone方式獲取命令如下git clone https://github.com/your-name/chart-skill.git cd chart-skill如果你項目的目錄名不叫chart-skill以實際倉庫名為準。國內(nèi)訪問 GitHub 速度不理想時可以使用 GitHub 鏡像站或加速下載工具。這里強調(diào)一點下載開源項目請盡量從原始倉庫地址獲取避免使用不明來源的二次打包文件防止代碼被篡改。5.2 環(huán)境準備這個項目的核心代碼使用 Python 3 編寫不依賴第三方包標準庫即可運行。也就是說只要你的電腦安裝了 Python 3.8 及以上版本就能直接跑通數(shù)據(jù)解析和管線腳本?？梢杂孟旅娴拿顧z查 Python 版本python3 --version如果你在 Windows 環(huán)境可能需要使用python而不是python3根據(jù)你的環(huán)境變量設置調(diào)整即可。5.3 準備演示數(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ù)四個字段適合測試柱狀圖、折線圖和混合圖。5.4 運行數(shù)據(jù)解析模塊先直接運行數(shù)據(jù)解析模塊看看結(jié)果python modules/data_parser.py預期輸出會顯示字段類型推斷結(jié)果。如果你看到月份被推斷為string而不是date是正常的因為2024-01這個格式默認沒有轉(zhuǎn)換成日期我建議保留為字符串類型在 ECharts 中直接用類目軸顯示會更直觀。5.5 調(diào)用 Skill 生成圖表Skill 的常規(guī)使用方式是在支持 Skill 的 AI 客戶端中引用SKILL.md路徑。假設你使用的是 Claude Desktop、Cherry Studio 或類似的 Skill 客戶端你需要在當前會話中加載這個目錄。加載后你可以直接輸入需求用 examples/sales_data.csv 的數(shù)據(jù)畫一張月度銷售額柱狀圖使用 business_light 主題輸出 html 格式。模型會按照SKILL.md的執(zhí)行流程調(diào)用各模塊最終生成一個 HTML 文件。如果你不希望依賴 AI 客戶端也可以直接運行管線腳本python scripts/run_pipeline.py \ --data examples/sales_data.csv \ --chart bar \ --theme business_light \ --format html \ --output output/sales_bar.htmlrun_pipeline.py是一個簡化版的調(diào)度腳本它把數(shù)據(jù)解析、圖表選擇、配置構(gòu)建、樣式應用、輸出渲染串聯(lián)起來。腳本執(zhí)行完成后會在output/目錄生成一個可打開的 HTML 圖表文件。5.6 驗證生成的圖表配置為了減少“代碼跑不起來”的問題新版增加了validate_option.py校驗腳本python scripts/validate_option.py output/option.json它會遞歸檢查 option 中是否有未定義的系列類型、是否缺少必填字段、series 長度是否匹配。校驗通過后才建議把配置投入生產(chǎn)。6. 新增亮點六邊形圖表與個性化圖表生成這次更新有一個讓我印象很深的需求很多用戶希望生成“六邊形圖表”用于能力評估、技能畫像、綜合素質(zhì)展示。六邊形圖表本質(zhì)上是 ECharts 的雷達圖radar但做了一些視覺定制指標點放在六邊形的頂點上連線形成封閉多邊形中心位置可以顯示綜合評分。為了這個功能我在chart_register.json里新增了hexagon類型并在option_builder.py中實現(xiàn)了build_hexagon方法。核心邏輯是讓模型把多列數(shù)值歸一化到 0-100 區(qū)間然后生成雷達圖配置。下面是一個六邊形圖表的 option 示例{ radar: { indicator: [ { name: 技術深度, max: 100 }, { name: 業(yè)務理解, max: 100 }, { name: 溝通協(xié)作, max: 100 }, { name: 學習能力, 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: 當前員工, areaStyle: { color: rgba(63, 167, 255, 0.3) }, lineStyle: { color: #3fa7ff, width: 2 } }, { value: [80, 75, 80, 85, 82, 78], name: 團隊平均, areaStyle: { color: rgba(255, 159, 64, 0.2) }, lineStyle: { color: #ff9f40, width: 2, type: dashed } } ] } ] }如果你在 AI 對話里提到了“六邊形”、“能力雷達”、“員工畫像”這些詞chart_selector.py會優(yōu)先推薦hexagon類型不再需要用戶手寫完整 radar 配置。7. 常見問題與排查清單新版本上線后用戶咨詢的問題集中在幾個固定場景。我把高頻問題的排查方案整理成表格方便你直接對照處理。問題現(xiàn)象常見原因解決思路Skill 加載后在 AI 客戶端中不生效客戶端不支持讀取本地目錄或路徑含中文/空格確認客戶端支持 Skill 功能路徑建議使用純英文或把 Skill 打包為插件格式生成的圖表中文亂碼HTML 缺少charsetutf-8或 ECharts CDN 加載失敗檢查輸出 HTML 模板是否包含 meta charset優(yōu)先使用 jsdelivr 等穩(wěn)定 CDN下載項目后沒有SKILL.md倉庫默認分支不是 main或克隆不完整檢查分支名使用git clone -b main指定分支確認倉庫根目錄文件完整run_pipeline.py提示找不到模塊當前工作目錄不在項目根目錄先執(zhí)行cd到項目根目錄再運行腳本生成的 option 在 ECharts 中報錯series 類型或字段名錯誤使用validate_option.py校驗對照 ECharts 官方文檔確認版本兼容性大屏圖表動態(tài)效果不明顯未使用tech_dark主題或 effect 配置未開啟指定--theme tech_dark檢查effect.show是否為 true想把 Skill 集成到自己的 Agent 項目缺少環(huán)境變量或配置映射閱讀config/skill.yaml將supported_charts與 Agent 的意圖識別模塊對接除了表格里的問題還有一個非常容易踩的坑在 Python 腳本中直接使用from modules.xxx import導入模塊時不同系統(tǒng)對當前路徑的處理方式不同。如果你在 Windows 的 PowerShell 下執(zhí)行務必先確認當前目錄是項目根目錄。如果你在 VS Code 里調(diào)試建議先把工作目錄設置為項目根目錄。8. 最佳實踐與工程建議前面把功能都過了一遍這一節(jié)我想分享一些從項目維護和社區(qū)反饋中沉淀下來的工程建議這些建議在你自己開發(fā) Skill 時同樣適用。8.1 把提示詞和可執(zhí)行代碼分開管理這是 Skill 設計中最重要的一條原則。SKILL.md里寫清楚“做什么”scripts/和modules/里寫清楚“怎么做”。如果你把所有邏輯都塞進提示詞模型每次運行時都要處理大量文本容易出錯且執(zhí)行不穩(wěn)定。更好的做法是提示詞只描述流程和邊界具體的數(shù)據(jù)處理、校驗、渲染交給腳本。8.2 為每個 Skill 維護一份版本元信息我建議在 Skill 項目根目錄或者config/skill.yaml里寫清楚版本號、依賴環(huán)境、作者、許可證。如果不寫版本團隊里多個人同時維護時很容易出現(xiàn)“這個腳本改了但不知道是哪個版本”的問題。引入 Git 標簽或者 GitHub Release 也是很好的做法。8.3 數(shù)據(jù)安全邊界要提前劃清圖表 Skill 通常需要讀取數(shù)據(jù)文件這里要特別強調(diào)不要在 Skill 里內(nèi)置“讀取任意路徑文件”的能力更不要允許模型自動修改原始數(shù)據(jù)文件。在SKILL.md的邊界約束里明確寫出“禁止修改原始數(shù)據(jù)”并讓腳本在讀取文件時校驗文件擴展名和大小。涉及敏感數(shù)據(jù)時建議在沙箱環(huán)境運行并做好脫敏處理。8.4 輸出結(jié)果要做兩級校驗第一級是語法校驗即 JSON 是否能被正確解析第二級是業(yè)務校驗即圖表是否適合表達當前數(shù)據(jù)。如果你的 Skill 有能力運行 ECharts 的 SSR 渲染可以把生成的配置用echarts的 nodejs 端渲染一次確認沒有運行時錯誤。如果不具備條件至少保留validate_option.py之類的靜態(tài)校驗腳本。8.5 不要迷信某一個 CDN國內(nèi)訪問 ECharts CDN 有時不穩(wěn)定尤其是公共服務器的網(wǎng)絡波動。在輸出 HTML 時可以考慮提供多個 CDN 源備用或者提示用戶下載 ECharts 到本地。不過 CDN 選擇屬于部署細節(jié)建議把可用性測試納入 Skill 的驗收流程。8.6 考慮輸出分層和二次編輯需求用戶拿到圖表的最終目的往往不是“看一次”而是“放進報告里再改改”。如果 Skill 輸出的 HTML 是純靜態(tài)的后續(xù)修改會很麻煩。我在新版中加入了“配置導出”按鈕用戶可以在頁面上調(diào)整顏色、標題后直接導出 JSON。類似思路可以引用到你自己的項目里不要只輸出一次性的結(jié)果給用戶留一條可編輯的路徑。8.7 遇到類型推斷不準時給用戶糾錯入口即使是精心設計的數(shù)據(jù)解析模塊也無法覆蓋所有真實數(shù)據(jù)場景。我的做法是當column_types中存在mixed類型時在輸出中提示用戶手動指定字段類型而不是讓模型擅自處理。如果你在生成管道中發(fā)現(xiàn)了同樣的現(xiàn)象建議參考這個處理策略。9. 后續(xù)規(guī)劃與可復用思路這次大更新并不是終點項目迭代的方向會集中在三個方面。第一是支持更多圖表類型和視覺主題計劃補充桑基圖、關系圖、儀表盤圖等同時增加暗黑科技、漸變玻璃擬態(tài)等主題風格。第二是增加“數(shù)據(jù)源對接”能力不再局限于 CSV 文件支持直接連接 MySQL、PostgreSQL、SQLite 等數(shù)據(jù)庫讓 Skill 能直接查詢指標生成圖表。第三是完善多語言支持讓 Skill 的說明文檔和輸出內(nèi)容能適配英文、日文等場景。如果你也想開發(fā)類似的 Skill我的建議是不要一開始追求大而全先從一個痛點場景出發(fā)。比如你先做“銷售周報圖表生成”這個細分能力跑通后沉淀出data_parser、chart_selector、output_renderer這些通用模塊再逐步擴展到更多場景。這個開源項目就是這么一步步走過來的。實際去動手配置一次你才會更清楚地理解“提示詞”和“Skill”之間的差別。如果你用它生成了不錯的圖表或者后續(xù)自己封裝了新的圖表類型也歡迎分享出來一起迭代。