dsh-chart-ascii

DeepSeek Harness 的终端图表工具箱：bar_chart 把一组数值画成横向 / 纵向条形图，line_chart 画折线 / 散点 / 面积趋势图，sparkline 把整段序列压成一行迷你图。输入只需「标签,值」或纯数值，三张图都在字符网格里按显示宽度对齐。只读、零运行时依赖。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-chart-ascii
• npm：https://www.npmjs.com/package/dsh-chart-ascii

功能说明

在终端里看数字，最容易出问题的不是「看不到」，而是「看不出」：一列 40 个数字谁大谁小要靠心算，一段 200 个采样点的趋势要靠脑补。文本表格能对齐，但反映不出比例和形状。

本插件的做法是先解析成「标签 + 数值」序列，再把它映射到字符网格上——条形图用长度表示大小，折线图用位置表示高低，迷你图用八级块字符表示相对起伏。三张图都是纯文本输出，能直接贴进聊天、日志、Issue，也能落进 Markdown 与 Word 文档。

数值来源支持两路：text 传内联数据（每行一条），或 path 读文件。每行支持 北京,120、上海 98、制表符 / 分号 / 竖线 / 等号分隔，也支持只写数值自动编号；# 开头的注释行与空行跳过；带 % 后缀的数值（如 12.5%）会记录百分号标记并在展示时带上。无法识别出数值的行会被单独计数，不会静默丢弃。

三张图的取舍：

• 想比较大小、看占比 → bar_chart。条形长度按「绝对值最大项」等比缩放，最长的一条永远占满可用宽度，小数值也能看清相对关系。
• 想看趋势、找峰值拐点 → line_chart。按数值范围映射到行，点数超过设定值时自动等分降采样（桶内取平均），保证输出宽度可控。
• 想在报告里塞一行概览 → sparkline。不占地方，一眼看出这段序列是走高、走低还是震荡。

安装

npm install dsh-chart-ascii

安装后在 cordis.patch.yml 中加入：

- insert:
    - id: chart-ascii
      name: "dsh-chart-ascii"

使用说明

bar_chart

把一组数值画成条形图。默认横向，条形长度按最大值等比缩放；orientation=vertical 切换为纵向柱状图。

参数：path / text 二选一（text 优先）；orientation（horizontal | vertical，默认 horizontal）；style（block | ascii | dot，默认 block）；width 横向图最长条形宽度（默认 40，上限 200）；height 纵向图高度（默认 10，上限 40）；sort（none | asc | desc，默认 none）；limit 最多绘制条数（默认 20，上限 200）；show_value 是否显示数值（默认 true）；show_percent 是否显示占合计的比例（默认 false）。

北京 | ████████████████████████████████████████ 120 (28.0%)
上海 | █████████████████████████████████ 98 (22.9%)
深圳 | ██████████████████████████ 77 (18.0%)
广州 | ██████████████████████ 66 (15.4%)
杭州 | ██████████████████ 55 (12.8%)
成都 | ████ 12.5 (2.9%)

纵向模式把每一行放大成一列，底部按列宽展开标签，顶部标最大值、底部标 0：

120 |█            
    |█   █        
    |█   █   █    
    |█   █   █   █
    |█   █   █   █
  0 |█   █   █   █
    +-------------
     北京上海深圳广州

用户：把各城市销量用条形图对比一下，按占比排序

助手：调用 bar_chart，text 传数据，sort=desc、show_percent=true

用户：这几个模块的代码行数画成柱状图

助手：调用 bar_chart，orientation=vertical、height=8

line_chart

把一组数值画成趋势图。style=line 连成折线，scatter 只画点，area 在点下方填充。点数超过 points 时自动等分降采样。

参数：path / text 二选一（text 优先）；style（line | scatter | area，默认 line）；height 图形高度（默认 10，上限 40）；points 横轴最多点数（默认 60，上限 240）；marker 数据点字符（默认 *，需单个字符）；min / max 手动指定纵轴范围；sort（默认 none）；limit 最多使用点数（默认 0，即不截断）。

31 |     *| 
   |     ||*
   |   *||*|
   | *||||  
   |*|||*|  
 9 |  *|    
   +--------
    #0    #7
    共 8 个点；样式 line

底部一行是坐标轴标签（取首尾数据行的标签）与统计说明；发生降采样时会写明「按 N 个一组降采样为 M 个」。

用户：这个接口的响应时间波动怎么样

助手：调用 line_chart，text 传响应时间序列，height=8

用户：把这些点画成散点图，用 o 当标记

助手：调用 line_chart，style=scatter、marker=o

用户：纵轴统一按 0 到 100 画，方便和上一张图对比

助手：调用 line_chart，min=0、max=100

sparkline

把一组数值压成一行迷你图。三种字符风格：block 用 ▁▂▃▄▅▆▇█ 八级块字符，ascii 用 ._-~^*+@，dot 用 ·•●。width 可把序列压缩到指定字符数（按组取平均）。

参数：path / text 二选一（text 优先）；style（block | ascii | dot，默认 block）；width 输出字符数上限（默认 0，即不压缩，上限 240）；sort（默认 none）；limit 最多使用点数（默认 0）。

▅▆█▁▂

区间：1 ~ 9；共 5 个字符（原始 9 个点按 2 个一组降采样）

用户：用一行表示这 30 天的日活趋势

助手：调用 sparkline，text 传日活序列，width=30

用户：终端里不想出现块字符，换成 ASCII 的

助手：调用 sparkline，style=ascii

典型场景

• 数据快速成型：拿到一列数字，先 bar_chart 看分布，再 sparkline 看走势，不必开绘图库。
• 报告内嵌：sparkline 输出一行纯文本，可直接贴进日报、周报、Issue 评论。
• 占比分析：show_percent=true 后每条以占合计的比例展示，适合预算、流量、错误来源构成。
• 趋势巡检：监控采样值、响应时间、日活、内存占用等序列用 line_chart 看峰谷与拐点。
• 横向对比：sort=desc + limit=10 直接产出 Top N 排行，省掉手工排序。
• 异常点定位：line_chart 配合 min / max 固定纵轴，让不同批次的图可以直接叠着看。
• 中文标签：标签按显示宽度对齐（汉字算 2 列），中英文混排不会错位。
• 文档配图降级：需要放进纯文本环境（终端日志、CI 输出、邮件）时，字符图是唯一不会被吞掉的「图」。
• 宽窄自适应：终端窄就把 width 调小，line_chart 与 sparkline 会自动降采样而不是撑破屏幕。

安全边界

• 只读：三个工具都不写入、不修改、不删除文件；测试含源文件 size/mtime 不变的只读性断言。
• 不访问网络：解析与绘图全部在本地完成，无任何外部请求。
• 不执行输入：只做文本切分与数值运算，不做 eval、不加载模块、不解析表达式。
• 二进制拒绝：读取时检测 NUL 字节，疑似二进制文件直接拒绝解析。
• 多层上限：文件大小上限 51200 KB（默认 10240 KB）、输出字符上限 200000（默认 20000）、条形宽度上限 200、纵向高度上限 40、绘制条数上限 200、点数上限 240、输出条数上限 200。超限即截断或拒绝并显式提示。
• 不做趋势预测：图只反映输入数值的几何关系，不推断增长率、不判断异常、不给业务结论；坐标轴含义与统计口径（缩放基准、是否降采样）在输出中写明。
• 负值说明：条形图与纵向图按绝对值等比缩放，负值只影响显示长度、不影响数值本身，正负号在数值列保留。
• 不脱敏：标签原样进入输出，仅按显示宽度截断。数据里可能含密钥、路径、个人信息，需要分享输出前请先用 dsh-credential-scan 检查。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-text-stats | 先用 text-stats 算出词频 / 分布，再用本插件画成条形图 | | dsh-log-parse | 把日志统计的时间线数据交给本插件，画成错误趋势图 | | dsh-similarity | 相似度评分序列用 line_chart / sparkline 看整体分布 | | dsh-table-render | 需要精确数值时用表格，需要看比例时用本插件，二者互补 | | dsh-credential-scan | 分享图表输出前扫描其中是否混入密钥、令牌 | | dsh-csv-inspect | 先看清 CSV 的列结构，再挑出一列数值交给本插件 | | dsh-bench-compare | 多次基准测试结果画成条形图或折线图，直观看波动 | | dsh-session-exporter | 把分析过程中的图表与结论归档成记录 |

版本说明

• 0.1.0（2026-10-04）：初始版本。
  • bar_chart：横向 / 纵向条形图，三种字符风格、等比缩放、排序与条数上限、可选数值与占比
  • line_chart：折线 / 散点 / 面积三种样式，自动等分降采样、可自定义标记与纵轴范围
  • sparkline：三种字符风格的迷你图，支持按宽度压缩
  • 数据行支持逗号 / 空格 / 制表符 / 分号 / 竖线 / 等号分隔与纯数值，注释与空行跳过，失败行单独计数
  • 按显示宽度对齐（汉字算 2 列），纵向图按列宽展开中文标签
  • 二进制拒绝、多层上限与截断提示

RoadMap

v0.2（计划）

• bar_chart 增加 stack：同一标签多段数值的堆叠条形图
• line_chart 增加 overlay：多条序列画在同一网格上对比
• 新增 histogram：按自动分箱统计数值分布并画成直方图
• 输出可选 JSON 结构（刻度、点坐标），便于其他工具二次加工

v0.3（展望）

• 支持从 CSV 指定列名取值（column 参数），不必先手工抽列
• 纵向条形图按标签宽度自动旋转 / 分行，长标签不再截断
• 与 dsh-chart-diff 联动，对比两次采样结果的图形差异
• 支持热力图式的二维网格（配合分箱统计）

FAQ

Q：为什么最长的条形没有占满 width？ 条形长度是 round(|值| / 最大绝对值 × width)，最大项必然占满。若看起来偏短，通常是因为最大值明显高于其余项（长尾分布），此时可以用 limit 截断尾部，或改用 sparkline 看整体形状。

Q：所有数值都是 0 会怎样？ 不会报错，但不会画出任何条形，输出会明确提示「全部数值为 0，条形长度按 0 绘制」。纵向图同理。

Q：负值怎么处理？ 按绝对值参与长度缩放（负值也有长度），数值本身原样显示并保留负号。字符图没有真正的负轴，需要同时看正负时建议改用 dsh-table-render。

Q：line_chart 的点数和实际输出宽度是什么关系？ points 是横轴最多字符数，超过就等分降采样：factor = ceil(总点数 / points)，每 factor 个点取平均合成一个字符。输出末尾会写明「原始 N 个点按 K 个一组降采样为 M 个」，不会让你误以为看到的是全部原始点。

Q：marker 传多个字符为什么没生效？ 数据点必须占一个字符位，传多字符时会回退为默认的 *。

Q：中文标签为什么没有错位，但字数看起来对不齐？ 对齐按「显示宽度」计算，汉字占 2 列。所以一列中文标签在等宽字体下视觉对齐，但在按字符数看时会显得更窄。等宽字体终端里显示正常。

Q：纵向图的标签太长会被截断吗？ 列宽按最长标签动态取 2~6 列，超出部分截断并补省略号。标签较多或较长时建议改用横向模式，或先用文本工具缩短标签。

Q：sort 之后原来的顺序信息还在吗？ 排序是稳定的（相同数值保持输入顺序），但 bar_chart 的标签行号反映的是解析顺序。需要保留原始次序时用默认的 sort=none。

Q：数值精度会丢吗？ 不会。计算全程用浮点数，只有最终展示用 fmtNum（整数原样、小数最多两位）。合计与均值也是按原始值计算的。

Q：文件很大能处理吗？ 默认文件大小上限 10240 KB（可调到 51200 KB）。本插件需要一次性读入整个文件解析，超大文件建议先用 dsh-line-ops 抽样或 dsh-file-search 定位更小的目标文件。

Q：输出被截断了怎么办？ 输出超过 max_chars（默认 20000）时会截断并提示总字符数，可用 max_chars 调大（上限 200000），或收紧 limit / 缩小 width 让输出更紧凑。

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-chart-ascii
• npm：https://www.npmjs.com/package/dsh-chart-ascii

许可证

MIT