ascii-mini-charts 实测:3.6KB 的 ASCII 图表 Skill,有 4 个会让你看错数据的坑
先说清它是什么
你搜「MiniCharts Skill」,大概率会落到 ascii-mini-charts 上:一个 Agent Skill,作用是让 AI 助手在纯文本环境里画迷你趋势图 —— sparkline(一行字符的趋势线)、柱状图、折线图。
它的全部实现是一个 3.6KB 的 Python 脚本,加上一份 2.6KB 的 SKILL.md。没有依赖框架,只用标准库,读 JSON、输出字符。
截至 2026 年 11 月 11 日,源码仓库 github.com/full-stack-skills/ascii-skills 的数据:7 star、0 fork、1 watch、0 issue,Apache-2.0,2026 年 6 月 5 日创建,最后一次推送 2026 年 10 月 3 日,仓库体积 143 KB。它属于一个 13 个 skill 的合集,其中一个就是它。
安装方式(需要 Node 环境):
npx skills add full-stack-skills/ascii-skills --skill ascii-mini-charts
这篇不谈「有没有用」这种虚话。我把脚本下载下来跑了十几组数据,发现 4 个会让你看错数据的问题,其中两个会直接改变你对趋势的判断。文末给了一份 40 行的替代实现。
先说结论
需求是真的,这个实现不合格。
- 「在终端、日志、Markdown 里看趋势」是一个真实且长期存在的需求,ASCII 图是唯一解
- 但如果用它,你会在三个地方被误导:最低点看不见、柱状图丢柱子、尖峰被采样吃掉
- 它的文档和代码还有 4 处对不上,其中一处是官方示例的输出本身就是编的
- 真正的价值不在功能,在于它是一个「批量生产 skill」的标本 —— 这一点比 bug 更值得看
它能干什么:先跑一条正常数据
输入 12 天的日访问量,让它画一条趋势线:
echo '{"series":[880,910,905,930,960,1020,1180,1150,1090,1210,1250,1300]}' \
| python mini_charts.py --width 12 --annotated
输出:
...:-**=#%@ min=880 max=1300 cur=1300
趋势是对的:从 880 涨到 1300,中间在高位回踩过一次(1090)。作为「一眼看个大概」,它完成了任务。
然后问题从这里开始。
坑一:最低点是一个空格,图上看不见
脚本里的字符表是这样定义的:
charset = " .:-=+*#%@"
十个档位,第一档是空格。数据归一化后,最小值会被映射到索引 0,也就是什么都不画。
拿 1 到 10 的等差序列试一下:
echo '{"series":[1,2,3,4,5,6,7,8,9,10]}' | python mini_charts.py --width 10
输出(我用 cat -A 把空格显示出来):
.:-=+*#%@
开头那个空格就是数值 1。你看到的 10 个点,实际只有 9 个可见。
为什么这个重要:sparkline 最常见的用法是「看某个指标有没有掉下来」。而最低点恰好是空格 —— 也就是最该被看见的那个点,反而最不可见。如果序列是「平稳运行然后掉到 0」,你看到的会是一串字符后面突然什么都没有,看起来像数据截断。
坑二:柱状图会丢柱子
同一个 skill 的 --type bar 模式,画同一条访问量数据,8 格高:
#
##
# ###
## ###
######
#######
########
# #########
数一下最下面那行:[空格][#][空格]#########。12 个数据点,只有 10 根柱子。
消失的是 880 和 905 这两天 —— 它们都是接近最小值的点。原因在渲染逻辑里:
levels = [int(round(t * height)) for t in norm]
for row in range(height, 0, -1):
line.append("#" if lv >= row else " ")
归一化后的最小值是 0,乘以高度还是 0,而 lv >= row 里的 row 最小是 1,所以永远不成立,那根柱子一个 # 都不会画。
柱状图的用途是比大小。少两根柱子,读者会以为这两天没有数据,或者那天是 0。
坑三:采样会把尖峰吃掉(这个最严重)
当序列长度超过宽度时,脚本会做等距采样:
def _sample(values, width):
if len(values) <= width:
return values
out = []
for i in range(width):
idx = int(i * (len(values) - 1) / (width - 1))
out.append(values[idx])
return out
这是「均匀取点」,不是「分桶聚合」。只要尖峰不落在被取到的那个索引上,它就彻底消失。
我造了一组最能说明问题的数据:100 天,平时每天 100,第 37 天突发 900(模拟一次故障或一次活动),第 38 天 860,之后恢复。宽度 30:
echo '{"series":[100,100,...,900,860,100,...]}' | python mini_charts.py --width 30
实际输出,只有一行:
@
没了。 100 个点只剩一个 @ 孤零零地挂在开头第 12 位,后面什么都没有。
为什么:28 个采样点取值都是 100,归一化后 t=0,映射成空格;尾部空格被 rstrip() 剪掉;只有落在 37/38 附近的那一列是 900,画成 @。
更糟的是它在位置上还产生了误导:@ 出现在第 12 列(约 37% 位置),但因为后面全被剪掉,视觉上像「开头有个高点,然后数据没了」。
一张「今天系统崩过一次」的监控图,被画成了这样。趋势图最该暴露的就是异常值,而这个采样策略专门丢异常值。
坑四:文档和代码有 4 处对不上
这四处都属于「照着文档做会失败」的类型:
| SKILL.md 写的 | 脚本实际 |
|---|---|
type (sparkline | bar | line),三种 |
只有 sparkline 和 bar,传 line 直接报错 invalid choice: 'line' |
必须输出 chartMinimal、chartAnnotated、scaleNotes 三项 |
只出图和标注,没有 scaleNotes(归一化/异常值策略说明) |
width (default min(len(series), 30)),跟随序列长度 |
写死 default=30,不跟随 |
examples/sparkline.md 里的输出示意 |
和实际运行结果不一致 |
最后一条我单独说一下,因为它最能说明问题。官方示例给的输入是 [3,4,5,8,6,9,12,10,11,14]、宽度 20,示例里写的输出是:
..:-=+**#@
我用同样的输入和参数跑出来是:
.:=:+#*#@
除了长度都是 9 个可见字符,没一个位置是对的。示例里那个输出是手写的「示意」,不是运行结果。SKILL.md 自己还标注了「(ASCII-only,示意)」—— 算是诚实,但一个图表工具连自己的样例都不给真跑一遍,可信度是要打折的。
比 bug 更值得看的:这不是「一个项目」
我顺着仓库往上查了一层,发现 full-stack-skills 这个组织下有 57 个仓库,star 合计 162 个(平均每个还不到 3 颗)。命名规律高度统一:tauri-skills、threejs-skills、ddd-skills、electron-skills、uniapp-skills、firmware-skills、antd-skills、cocos-skills、git-skills、codereview-skills、teaching-skills……
而且绝大多数仓库的 pushed_at 都是 2026 年 10 月 3 日同一天。
再看 SKILL.md 的内容。我抽了三个不同的 skill:画表格的、画进度条的、把图片转 ASCII 的。它们都包含同样的两段:
「常见陷阱」5 条:版本兼容性、配置文件格式、环境变量、依赖冲突、大数据量注意避免 N+1 查询。
「使用流程」5 步:环境准备 → 配置初始化 → 核心功能使用 → 测试验证 → 部署上线。
一个把图片转成字符画的本地脚本,需要「注意 N+1 查询」,还要「部署上线」。这三份文档的这两段一个字都不差。
这是模板批量填充的典型痕迹。skill 本身可能有人认真写过(脚本逻辑是完整的、参数也做了边界处理),但文档层是流水线产物,没人回头校对。
一个自己关掉自己能力的触发器
最让我意外的是 SKILL.md 开头的这一条:
CRITICAL TRIGGER RULE — Use this skill ONLY when the user explicitly mentions the exact skill name:
ascii-mini-charts.
翻译过来:只有当用户准确说出「ascii-mini-charts」这个名字时,才可以使用本 skill。
这等于把 skill 最重要的能力关掉了。
Skill 的机制是:模型启动时看到所有 skill 的名字和描述,判断当前任务需要哪个,然后自动加载对应的 SKILL.md。也就是说,description 是写给模型做匹配用的 —— 你写「生成 ASCII 趋势图」,模型在该画趋势图时才会想起你。
而这条规则要求「用户必须喊全名」。现实中没人会对着 AI 说「请用 ascii-mini-charts 帮我画个图」。结果就是:这个 skill 永远不会被自动调用,只能被手动点名。
一个工具主动声明「不要默认用我」,通常只有两种解释:作者知道它在通用场景下不够好,或者它本来就是给「skill 展示柜」凑数的。不管是哪种,对使用者来说结论一样:它不是一个会被 AI 自然用上的能力。
那 ASCII 图表到底什么时候有用
这个需求是真实的。四个场景里,别的方案都不如它:
1. CI / 构建日志里看趋势。 流水线输出是纯文本,贴不了图。把最近 30 次构建耗时画成一行,失败率高的那几次一眼能看出来。
2. SSH 到没有图形界面的服务器。 不想装 Grafana、又想知道 CPU 最近一小时怎么走,一行字符比 top 快照有用。
3. Markdown 文档、纯文本邮件、工单系统。 这些地方嵌入图片要么不支持、要么要传附件。字符图直接粘贴就能看。
4. 终端 CLI 工具的输出。 一个自己写的小工具,最后打一行趋势图,体验会比让你去开浏览器好。
还有一个不那么常见、但很实用的:
5. 把趋势喂给大模型。 一张 800×400 的 PNG,走视觉模型要几千个 token;同样一段趋势用 40 个字符表示,大概 20 个 token。当你需要让模型「看一眼这条曲线有没有异常」,字符图便宜两个数量级。 这也是 ASCII sparkline 这两年重新被提起的原因之一。
40 行替代实现
上面四个坑,都不是「需要重构」才能修的。我重写了一版,40 行左右,标准库,接口兼容:
CHARS = ".-=+*#%@" # 最低档用可见字符,不用空格
def bucket(values, width):
"""等分桶取最大值 —— 保住尖峰。返回 (采样序列, 是否压缩过)。"""
n = len(values)
if n <= width:
return list(values), False
out = []
for i in range(width):
lo = i * n // width
hi = max(lo + 1, (i + 1) * n // width)
out.append(max(values[lo:hi]))
return out, True
def norm(values, mode="linear"):
v = [math.log(x + 1) for x in values] if mode == "log" else list(values)
lo, hi = min(v), max(v)
return [0.5] * len(v) if hi == lo else [(x - lo) / (hi - lo) for x in v]
def spark(values, width, mode):
s, squeezed = bucket(values, width)
return "".join(CHARS[int(round(t * (len(CHARS) - 1)))] for t in norm(s, mode)), s, squeezed
def bars(values, width, height, mode):
s, squeezed = bucket(values, width)
lv = [max(1, int(round(t * height))) for t in norm(s, mode)] # 最少留 1 格
rows = ["".join("#" if x >= r else " " for x in lv).rstrip()
for r in range(height, 0, -1)]
return "\n".join(rows), s, squeezed
关键四行改动:
CHARS去掉空格,最低档是.—— 最低点看得见bucket()每桶取max,不是等距取点 —— 尖峰不丢max(1, ...)—— 柱子最少 1 格,不会整根消失- 标注用采样后真实画出来的值,另外附一行说明「压成几列、什么归一化」—— 补上原版缺失的 scaleNotes
同样三组数据,对比一下:
12 天访问量(原版 → 修正版)
...:-**=#%@ ← 最低点 880 是空格
...--=#**%%@ ← 12 个点全可见
柱状图 12 根柱子(原版 → 修正版)
# ######### ← 12 个点画出 10 根
############ ← 12 根全在
100 天里一次 9 倍尖峰(原版 → 修正版)
@ ← 原版:只剩一个孤点,后面全空
...........@.................. ← 修正版:平稳 → 尖峰 → 恢复平稳
第三组是决定性的一组。原版把所有信息都丢了,修正版把「第 12 列位置有一次异常」这个事实完整地表达出来了。
怎么选
| 方案 | 适合谁 | 要注意 |
|---|---|---|
| 自己写 40 行 | 有 Python 环境、只画 sparkline 或柱状图 | 上面那份代码可以直接抄,接口兼容;改字符表就能调粗细 |
ascii-mini-charts |
只想抄它的 SKILL.md 结构做自己的 skill | 别直接用它的输出做判断;文档里 line 类型和 scaleNotes 都不存在 |
mcp-ascii-charts |
需要 MCP 协议接入、要线图/散点/直方图/ANSI 颜色 | TypeScript 写的 MCP server,MIT,种类更全;装法走 npm 全局 |
| 终端里临时看一眼 | 不想装任何东西 | gnuplot 的 dumb terminal、或者 sparkline 系列的小脚本都行 |
一句话收尾
这个 skill 真正的教训不是「它有几个 bug」,而是 skill 生态正在重复 npm 早期的那条路:57 个仓库、同一天推送、文档是模板填的、样例是手写的、最高频的词是「部署上线」。
skill 和普通库不一样 —— 它的受众是 AI,而 AI 不会替你怀疑文档。你写「我支持 line 类型」,模型就会去调用 --type line,然后报错。你写「输出 scaleNotes」,模型就会假装自己输出了。
所以装 skill 之前,至少把它的示例在本地跑一遍。 如果示例输出对不上,后面的一切都别信。
上面那个 ..:-=+**#@ 和真实输出 .:=:+#*#@ 的差别,就是全部答案。

