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 之前,至少把它的示例在本地跑一遍。 如果示例输出对不上,后面的一切都别信。

上面那个 ..:-=+**#@ 和真实输出 .:=:+#*#@ 的差别,就是全部答案。

腾讯云精选福利

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注