@huicai/cli 2026.814.0 → 2026.1021.0

package/skills/report-craft/scripts/chart_render.py

@@ -0,0 +1,1222 @@
+#!/usr/bin/env python3
+# 报告图表引擎：结构化 spec → 出版级 PNG（300dpi，按版心物理尺寸出图）+ SVG。
+#
+# 与 render_diagram（结构图）是一对：那边画「系统长什么样」，这边画「数字是多少」。
+# 纪律同一条——**模型只给数据，版式、配色、标注由引擎负责**。
+# 模型手写 matplotlib 的通病：默认配色糊成一片、中文变方块、每个点都标数字、双纵轴制造假相关、
+# 饼图切十几块、柱子胖得像砖、图里的字比正文还大或小到看不清。这些都在这里一次性定死。
+#
+# 设计规则（来自数据可视化方法：先选图型、颜色最后定、颜色一律按「这个颜色干什么活」分配）：
+#   · 类别色 8 个固定顺序（已用校验脚本在白底上验证：相邻色盲 ΔE ≥ 9.1、常人视觉 ΔE ≥ 19.6），
+#     第 9 个系列不生成新色——并入「其他」；
+#   · 量级用单色梯度，正负/高于低于用蓝↔红发散色 + 灰中点；状态色（好/警/重/危）只给风险这类「状态」用；
+#   · 细标记：柱 ≤0.6cm 宽（≈23px@96dpi）、数据端 1mm 圆角、贴基线一端直角；相邻柱与堆叠段之间留 2px 白缝；
+#     线 1.5pt、圆点带白环；网格与坐标轴一律实线细线、退后；
+#   · ≥2 个系列必有图例；数字只标该标的（柱顶、线尾、极值），不在每个点上堆数字；
+#   · 文字只用墨色，不用系列色；**永远一根纵轴**（双纵轴直接拒绝，给出替代写法）；
+#   · 饼图只做 ≤6 块的构成，超出自动并「其他」；
+#   · 出图按版心物理尺寸 × 300dpi：插进 Word 后图里的字就是 9 磅，不会被缩放得忽大忽小。
+#
+# 用法：python chart_render.py <spec.json> <out.png>   （同名 .svg 一并产出）
+# 输出：最后一行 JSON（ok/png/svg/width_cm/height_cm/table_md/warnings）。
+
+import json
+import math
+import os
+import re
+import sys
+import datetime as _dt
+
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt                      # noqa: E402
+from matplotlib import font_manager, rcParams       # noqa: E402
+from matplotlib.path import Path                    # noqa: E402
+from matplotlib.patches import PathPatch, Rectangle, Polygon, Wedge   # noqa: E402
+
+# ── 调色板（数据可视化参考调色板，白底验证过）────────────────────────────
+PALETTE = ['#2a78d6', '#eb6834', '#1baf7a', '#eda100', '#e87ba4', '#008300', '#4a3aa7', '#e34948']
+LOW_CONTRAST = {'#1baf7a', '#eda100', '#e87ba4'}   # 白底对比度 <3:1：用到它们就必须有可见数值标注
+SEQ = ['#cde2fb', '#b7d3f6', '#9ec5f4', '#86b6ef', '#6da7ec', '#5598e7', '#3987e5',
+       '#2a78d6', '#256abf', '#1c5cab', '#184f95', '#104281', '#0d366b']   # 100→700
+POS, NEG, MID = '#2a78d6', '#e34948', '#f0efec'   # 发散：蓝↔红，灰中点
+STATUS = {'low': '#0ca30c', 'mid': '#fab219', 'high': '#ec835a', 'critical': '#d03b3b'}
+DEEMPH = '#c9c8c2'                                  # 强调图里「其余」用的退后灰
+INK1, INK2, MUTED = '#0b0b0b', '#52514e', '#898781'
+GRID, AXIS = '#e1e0d9', '#c3c2b7'
+SURFACE = '#ffffff'
+
+CM = 1 / 2.54
+FULL_W_CM, HALF_W_CM = 14.6, 7.2                   # A4 技术文档版心 14.66cm
+DPI = 300
+FS_TICK, FS_LABEL, FS_TITLE = 8.5, 9, 10.5
+
+_FONT_CANDIDATES = [
+    'PingFang SC', 'Hiragino Sans GB', 'Heiti SC', 'STHeiti', 'Source Han Sans SC', 'Noto Sans CJK SC',
+    'Microsoft YaHei', 'DengXian', 'SimHei', 'WenQuanYi Micro Hei', 'Droid Sans Fallback', 'Arial Unicode MS',
+]
+_FONT_FILES = [
+    '/System/Library/Fonts/PingFang.ttc', '/System/Library/Fonts/Hiragino Sans GB.ttc',
+    'C:/Windows/Fonts/msyh.ttc', 'C:/Windows/Fonts/simhei.ttf',
+    '/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc', '/usr/share/fonts/truetype/wqy/wqy-microhei.ttc',
+]
+
+
+class SpecError(ValueError):
+    """spec 写错了：信息要能直接照着改。"""
+
+
+def setup_font():
+    """挑一个能显示中文的无衬线字体；找不到返回 None（上层如实告警，图里中文会缺字）。"""
+    for name in _FONT_CANDIDATES:
+        try:
+            font_manager.findfont(name, fallback_to_default=False)
+        except Exception:
+            continue
+        rcParams['font.sans-serif'] = [name, 'DejaVu Sans']
+        rcParams['axes.unicode_minus'] = False
+        return name
+    for f in _FONT_FILES:
+        if not os.path.exists(f):
+            continue
+        try:
+            font_manager.fontManager.addfont(f)
+            name = font_manager.FontProperties(fname=f).get_name()
+            rcParams['font.sans-serif'] = [name, 'DejaVu Sans']
+            rcParams['axes.unicode_minus'] = False
+            return name
+        except Exception:
+            continue
+    return None
+
+
+def _base_rc():
+    rcParams.update({
+        'font.family': 'sans-serif', 'font.size': FS_LABEL, 'axes.edgecolor': AXIS, 'axes.linewidth': 0.6,
+        'axes.labelcolor': INK2, 'xtick.color': INK2, 'ytick.color': INK2,
+        'xtick.labelsize': FS_TICK, 'ytick.labelsize': FS_TICK, 'text.color': INK1,
+        'figure.facecolor': SURFACE, 'axes.facecolor': SURFACE, 'savefig.facecolor': SURFACE,
+        'svg.fonttype': 'none', 'lines.solid_capstyle': 'round', 'lines.solid_joinstyle': 'round',
+    })
+
+
+# ── 数字格式 ────────────────────────────────────────────────────────────────
+def fmt(v, decimals=None, unit='', signed=False):
+    """千分位 + 自适应小数（整数不带小数，其余最多 2 位、去尾零）；unit 为 % 时贴在数字后。"""
+    if v is None or (isinstance(v, float) and math.isnan(v)):
+        return '—'
+    auto = decimals is None
+    if auto:
+        decimals = 0 if abs(v - round(v)) < 1e-9 else (1 if abs(v * 10 - round(v * 10)) < 1e-9 else 2)
+    s = f'{abs(v):,.{decimals}f}'
+    if auto and decimals:
+        s = s.rstrip('0').rstrip('.') if '.' in s else s
+    if float(s.replace(',', '')) == 0:
+        v = 0                                         # 舍入后是 0 就别带负号（「-0」）
+    sign = '-' if v < 0 else ('+' if signed and v > 0 else '')
+    return sign + s + ('%' if unit == '%' else '')
+
+
+def label_dec(values):
+    """一张图的数值标注统一小数位：全是整数不带小数；≥100 取整、≥10 一位、其余两位（精确值在表里）。"""
+    vals = [abs(v) for v in values if v is not None]
+    if not vals or all(abs(v - round(v)) < 1e-9 for v in vals):
+        return 0
+    mx = max(vals)
+    return 0 if mx >= 100 else (1 if mx >= 10 else 2)
+
+
+def _num(x, where):
+    try:
+        v = float(x)
+    except (TypeError, ValueError):
+        raise SpecError(f'{where} 不是数字：{x!r}')
+    if math.isnan(v) or math.isinf(v):
+        raise SpecError(f'{where} 不是有限数字：{x!r}')
+    return v
+
+
+def nice_ticks(lo, hi, n=5):
+    """「好看」的刻度：步长取 1/2/2.5/5×10^k，覆盖 [lo, hi]。"""
+    if hi == lo:
+        hi = lo + 1
+    raw = (hi - lo) / max(n, 1)
+    mag = 10 ** math.floor(math.log10(raw))
+    step = next(m * mag for m in (1, 2, 2.5, 5, 10) if m * mag >= raw)
+    t0 = math.floor(lo / step) * step
+    t1 = math.ceil(hi / step) * step
+    ticks = []
+    t = t0
+    while t <= t1 + step * 1e-6:
+        ticks.append(round(t, 10))
+        t += step
+    return ticks
+
+
+def wrap_cjk(s, max_chars):
+    """中文标签按字数折行（最多两行，超出末尾省略号）。"""
+    s = str(s)
+    if max_chars <= 1 or len(s) <= max_chars:
+        return s
+    a, b = s[:max_chars], s[max_chars:]
+    if len(b) > max_chars:
+        b = b[:max_chars - 1] + '…'
+    return a + '\n' + b
+
+
+_WRAP_TOKEN = re.compile(r'[A-Za-z0-9][A-Za-z0-9.\-_/%:]*|\s+|.', re.S)
+_NO_LINE_START = set('，。；：、）」》”！？,.;:)')
+_NO_LINE_END = set('（「《“(〔［')
+
+
+def wrap_measured(cv, text, size, max_w_in):
+    """多行说明文字（图下注、里程碑说明）按实测宽度折行：**不截断**、英文词与数字日期不从中间断、行首不放标点。
+    标签用的 wrap_cjk 最多两行、超出就省略——拿它折图注，里程碑一多后半截就被悄悄吃掉了。"""
+    lines, cur = [], ''
+    for tok in _WRAP_TOKEN.findall(str(text or '')):
+        if tok == '\n':
+            lines.append(cur)
+            cur = ''
+            continue
+        if cur and cv.text_w_in(cur + tok, size)[0] > max_w_in:
+            lines.append(cur.rstrip())
+            cur = tok.lstrip()
+        else:
+            cur += tok
+    if cur:
+        lines.append(cur)
+    for k in range(1, len(lines)):                       # 禁头：行首的标点挪回上一行末尾
+        while lines[k] and lines[k][0] in _NO_LINE_START:
+            lines[k - 1] += lines[k][0]
+            lines[k] = lines[k][1:]
+        while lines[k - 1] and lines[k - 1][-1] in _NO_LINE_END:   # 禁尾：行末的开括号挪到下一行开头
+            lines[k] = lines[k - 1][-1] + lines[k]
+            lines[k - 1] = lines[k - 1][:-1]
+    return '\n'.join(l for l in lines if l)
+
+
+# ── 画布与坐标轴 ─────────────────────────────────────────────────────────────
+class Canvas:
+    """按物理尺寸建图；先量字再定页边距，保证坐标轴标签、图例、单位都不被裁。"""
+
+    def __init__(self, width_cm, height_cm):
+        self.w_in, self.h_in = width_cm * CM, height_cm * CM
+        self.fig = plt.figure(figsize=(self.w_in, self.h_in), dpi=DPI)
+        self.ax = self.fig.add_axes([0.1, 0.12, 0.85, 0.75])
+        self.top_items = []          # 图例/单位行，画在坐标区上方
+        self.warnings = []
+        self.note_in = 0.0           # 图下注（数据来源等）占的高度：layout 自动在底部让出来，免得压住横轴标签
+
+    def text_w_in(self, s, size=FS_TICK):
+        r = self.fig.canvas.get_renderer()
+        t = self.fig.text(0, 0, s, fontsize=size)
+        bb = t.get_window_extent(renderer=r)
+        t.remove()
+        return bb.width / DPI, bb.height / DPI
+
+    def resize(self, height_cm):
+        """按内容重定画布高度（甘特图的行数、折行、里程碑排数都要在量过字之后才知道）。"""
+        self.h_in = height_cm * CM
+        self.fig.set_size_inches(self.w_in, self.h_in)
+
+    def layout(self, left_in, right_in, top_in, bottom_in):
+        bottom_in = bottom_in + self.note_in
+        L = left_in / self.w_in
+        R = 1 - right_in / self.w_in
+        T = 1 - top_in / self.h_in
+        B = bottom_in / self.h_in
+        if R - L < 0.3 or T - B < 0.25:
+            raise SpecError('图太挤：标签太长或尺寸太小——缩短类别名，或改用 size:"full"')
+        self.ax.set_position([L, B, R - L, T - B])
+
+    def px_per_unit(self):
+        """当前坐标区里 x、y 各 1 个数据单位对应多少像素（用来把「1mm 圆角」换成数据单位）。"""
+        bb = self.ax.get_position()
+        x0, x1 = self.ax.get_xlim()
+        y0, y1 = self.ax.get_ylim()
+        pxw = bb.width * self.w_in * DPI
+        pxh = bb.height * self.h_in * DPI
+        return pxw / (x1 - x0), pxh / (y1 - y0)
+
+
+def style_axes(ax, value_axis='y', grid=True):
+    for s in ('top', 'right'):
+        ax.spines[s].set_visible(False)
+    if value_axis == 'y':
+        ax.spines['left'].set_visible(False)
+        ax.spines['bottom'].set_color(AXIS)
+        if grid:
+            ax.yaxis.grid(True, color=GRID, linewidth=0.5, linestyle='-')
+        ax.xaxis.grid(False)
+    else:
+        ax.spines['bottom'].set_visible(False)
+        ax.spines['left'].set_color(AXIS)
+        if grid:
+            ax.xaxis.grid(True, color=GRID, linewidth=0.5, linestyle='-')
+        ax.yaxis.grid(False)
+    ax.set_axisbelow(True)
+    ax.tick_params(length=0, pad=4)
+
+
+def rounded_bar(x0, x1, y0, y1, rx, ry, end='top'):
+    """柱形路径：数据端圆角、基线端直角（1/4 椭圆用三次贝塞尔近似）。end ∈ top/bottom/right/left。"""
+    k = 0.5523
+    if end in ('top', 'bottom'):
+        h = abs(y1 - y0)
+        ry = min(ry, h)
+        rx = min(rx, (x1 - x0) / 2)
+        if end == 'top':
+            verts = [(x0, y0), (x0, y1 - ry),
+                     (x0, y1 - ry + k * ry), (x0 + rx - k * rx, y1), (x0 + rx, y1),
+                     (x1 - rx, y1),
+                     (x1 - rx + k * rx, y1), (x1, y1 - ry + k * ry), (x1, y1 - ry),
+                     (x1, y0), (x0, y0)]
+        else:
+            verts = [(x0, y0), (x0, y1 + ry),
+                     (x0, y1 + ry - k * ry), (x0 + rx - k * rx, y1), (x0 + rx, y1),
+                     (x1 - rx, y1),
+                     (x1 - rx + k * rx, y1), (x1, y1 + ry - k * ry), (x1, y1 + ry),
+                     (x1, y0), (x0, y0)]
+    else:
+        w = abs(x1 - x0)
+        rx = min(rx, w)
+        ry = min(ry, (y1 - y0) / 2)
+        if end == 'right':
+            verts = [(x0, y0), (x1 - rx, y0),
+                     (x1 - rx + k * rx, y0), (x1, y0 + ry - k * ry), (x1, y0 + ry),
+                     (x1, y1 - ry),
+                     (x1, y1 - ry + k * ry), (x1 - rx + k * rx, y1), (x1 - rx, y1),
+                     (x0, y1), (x0, y0)]
+        else:
+            verts = [(x0, y0), (x1 + rx, y0),
+                     (x1 + rx - k * rx, y0), (x1, y0 + ry - k * ry), (x1, y0 + ry),
+                     (x1, y1 - ry),
+                     (x1, y1 - ry + k * ry), (x1 + rx - k * rx, y1), (x1 + rx, y1),
+                     (x0, y1), (x0, y0)]
+    codes = [Path.MOVETO, Path.LINETO, Path.CURVE4, Path.CURVE4, Path.CURVE4, Path.LINETO,
+             Path.CURVE4, Path.CURVE4, Path.CURVE4, Path.LINETO, Path.CLOSEPOLY]
+    return Path(verts, codes)
+
+
+def capsule_h(x0, x1, y0, y1, rx, ry):
+    """两端都圆角的横条（甘特图：开始与结束都是数据端，没有基线端）。"""
+    k = 0.5523
+    w = x1 - x0
+    rx = min(rx, w / 2)
+    ry = min(ry, (y1 - y0) / 2)
+    verts = [(x0 + rx, y0), (x1 - rx, y0),
+             (x1 - rx + k * rx, y0), (x1, y0 + ry - k * ry), (x1, y0 + ry),
+             (x1, y1 - ry),
+             (x1, y1 - ry + k * ry), (x1 - rx + k * rx, y1), (x1 - rx, y1),
+             (x0 + rx, y1),
+             (x0 + rx - k * rx, y1), (x0, y1 - ry + k * ry), (x0, y1 - ry),
+             (x0, y0 + ry),
+             (x0, y0 + ry - k * ry), (x0 + rx - k * rx, y0), (x0 + rx, y0)]
+    codes = [Path.MOVETO, Path.LINETO, Path.CURVE4, Path.CURVE4, Path.CURVE4, Path.LINETO,
+             Path.CURVE4, Path.CURVE4, Path.CURVE4, Path.LINETO,
+             Path.CURVE4, Path.CURVE4, Path.CURVE4, Path.LINETO,
+             Path.CURVE4, Path.CURVE4, Path.CURVE4]
+    return Path(verts, codes)
+
+
+LEGEND_ROW_IN = 0.24
+
+
+def _legend_item_w(cv, label, kind):
+    return (0.28 if kind == 'line' else 0.14) + cv.text_w_in(label, FS_LABEL)[0] + 0.22
+
+
+def legend_rows(cv, items):
+    """图例排几行：总宽不过画布一半多 → 一行，从坐标区左缘起排（与坐标轴对齐）；
+    否则从画布左缘起、按画布宽折成多行——五六个分组的甘特图图例一行排不下，右端会被裁掉。"""
+    ws = [_legend_item_w(cv, l, k) for l, _c, k in items]
+    if sum(ws) <= cv.w_in * 0.55:
+        return 'axes', [list(range(len(items)))], ws
+    avail = cv.w_in - 0.24
+    rows, cur, cur_w = [], [], 0.0
+    for i, w in enumerate(ws):
+        if cur and cur_w + w > avail:
+            rows.append(cur)
+            cur, cur_w = [], 0.0
+        cur.append(i)
+        cur_w += w
+    if cur:
+        rows.append(cur)
+    return 'margin', rows, ws
+
+
+def draw_legend_row(cv, items, y_in_from_top=0.06):
+    """图例：坐标区上方，左对齐；色块/短线在左、墨色文字在右（文字不用系列色）。放不下就折行。"""
+    fig = cv.fig
+    mode, rows, ws = legend_rows(cv, items)
+    x_start = cv.ax.get_position().x0 * cv.w_in
+    if mode == 'margin' or x_start + sum(ws) > cv.w_in - 0.1:     # 坐标区左缘起排会出画布：改从画布左缘起
+        x_start = 0.12
+    for r, row in enumerate(rows):
+        x = x_start
+        y = cv.h_in - y_in_from_top - 0.09 - r * LEGEND_ROW_IN
+        for i in row:
+            label, color, kind = items[i]
+            if kind == 'line':
+                fig.add_artist(plt.Line2D([x / cv.w_in, (x + 0.22) / cv.w_in], [(y + 0.045) / cv.h_in] * 2,
+                                          color=color, linewidth=1.5, transform=fig.transFigure))
+                x += 0.28
+            else:
+                fig.add_artist(Rectangle((x / cv.w_in, (y + 0.005) / cv.h_in), 0.09 / cv.w_in, 0.09 / cv.h_in,
+                                         facecolor=color, edgecolor='none', transform=fig.transFigure))
+                x += 0.14
+            fig.text(x / cv.w_in, (y + 0.05) / cv.h_in, label, fontsize=FS_LABEL, color=INK2, va='center')
+            x += cv.text_w_in(label, FS_LABEL)[0] + 0.22
+    return x_start
+
+
+def top_band(cv, legend_items, unit):
+    """坐标区上方要留多高：单位一行 + 图例若干行（有才留；行数与 draw_legend_row 用同一个排法算）。"""
+    h = 0.08
+    if unit:
+        h += 0.2
+    if legend_items:
+        h += LEGEND_ROW_IN * len(legend_rows(cv, legend_items)[1])
+    return h
+
+
+def draw_unit(cv, unit, y_top_in):
+    if unit:
+        x = cv.ax.get_position().x0
+        cv.fig.text(x, 1 - y_top_in / cv.h_in, f'单位：{unit}', fontsize=FS_TICK, color=MUTED, va='top')
+
+
+# ── 通用校验 ────────────────────────────────────────────────────────────────
+def get_series(spec, n_cat):
+    series = spec.get('series') or []
+    if not isinstance(series, list) or not series:
+        raise SpecError('缺 series：[{"name":"收入","values":[...]}]')
+    if len(series) > 8:
+        raise SpecError(f'系列 {len(series)} 个太多（上限 8）：把尾部并成「其他」，或拆成几张小图')
+    out = []
+    for i, s in enumerate(series):
+        vals = s.get('values')
+        if not isinstance(vals, list):
+            raise SpecError(f'series[{i}] 缺 values 数组')
+        if len(vals) != n_cat:
+            raise SpecError(f'series[{i}]「{s.get("name", "")}」有 {len(vals)} 个值，categories 有 {n_cat} 个——要一一对应')
+        out.append({'name': str(s.get('name') or f'系列{i + 1}'),
+                    'values': [_num(v, f'series[{i}].values[{j}]') for j, v in enumerate(vals)]})
+    return out
+
+
+def colors_for(series, spec):
+    """类别色按固定顺序给；highlight 指定一个系列时，其余退为灰（强调式，比 8 种颜色更能讲清一件事）。"""
+    hl = spec.get('highlight')
+    if hl is not None and len(series) > 1:
+        return [PALETTE[0] if s['name'] == str(hl) else DEEMPH for s in series]
+    return [PALETTE[i] for i in range(len(series))]
+
+
+def table_md(headers, rows):
+    head = '| ' + ' | '.join(headers) + ' |'
+    sep = '|' + '|'.join(['---'] * len(headers)) + '|'
+    body = ['| ' + ' | '.join(str(c) for c in r) + ' |' for r in rows]
+    return '\n'.join([head, sep] + body)
+
+
+def place_bar_labels(cv, cands, horizontal, n_s):
+    """柱顶/条端数值标注的摆放：先按英寸量出每个标注框，查两两重叠——
+    ① 都不重叠：居中放；② 两系列分组柱重叠：左柱标注右对齐、右柱左对齐（各自向组外侧让位）；
+    ③ 仍重叠：按数值大小贪心放，放不下的省略（返回省略个数，交给调用方提醒附表）。"""
+    ax, fig = cv.ax, cv.fig
+
+    def to_in(x, y):
+        px = ax.transData.transform((x, y))
+        return px[0] / fig.dpi, px[1] / fig.dpi
+
+    pad = 3.5 / 72
+    shift_pt = 2.0
+    shift = shift_pt / 72
+    sizes = [cv.text_w_in(c['text'], FS_TICK) for c in cands]
+
+    def box(c, wh, mode):
+        w, h = wh
+        if horizontal:
+            x, y = to_in(c['v'], c['pos'])
+            x0 = x + pad if c['v'] >= 0 else x - pad - w
+            return (x0, y - h / 2, x0 + w, y + h / 2)
+        x, y = to_in(c['pos'], c['v'])
+        y0 = y + pad if c['v'] >= 0 else y - pad - h
+        if mode == 'in_left':                      # 右缘收进柱右缘以内 δ，向左（组外侧）伸
+            x1 = to_in(c['c1'], c['v'])[0] - shift
+            return (x1 - w, y0, x1, y0 + h)
+        if mode == 'in_right':                     # 左缘收进柱左缘以内 δ，向右伸
+            x0 = to_in(c['c0'], c['v'])[0] + shift
+            return (x0, y0, x0 + w, y0 + h)
+        return (x - w / 2, y0, x + w / 2, y0 + h)
+
+    clr = 0.05                                     # 两个标注之间至少留 0.05 英寸（约 3.6pt），否则「120 116」读成一个数
+
+    def hit(a, b):
+        return a[0] < b[2] + clr and b[0] < a[2] + clr and a[1] < b[3] and b[1] < a[3]
+
+    def clean(boxes):
+        return not any(hit(boxes[a], boxes[b]) for a in range(len(boxes)) for b in range(a + 1, len(boxes)))
+
+    modes = ['center'] * len(cands)
+    boxes = [box(c, wh, 'center') for c, wh in zip(cands, sizes)]
+    keep = list(range(len(cands)))
+    if not clean(boxes):
+        ok = False
+        if n_s == 2 and not horizontal:
+            m2 = ['in_left' if c['i'] == 0 else 'in_right' for c in cands]
+            b2 = [box(c, wh, md_) for c, wh, md_ in zip(cands, sizes, m2)]
+            if clean(b2):
+                modes, boxes, ok = m2, b2, True
+        if not ok:
+            keep, placed = [], []
+            for k in sorted(range(len(cands)), key=lambda k: -abs(cands[k]['v'])):
+                if not any(hit(boxes[k], boxes[q]) for q in placed):
+                    placed.append(k)
+            # 一个系列只要有标注被挤掉，就整系列不标——半数有数、半数没数，读者会以为缺了数据
+            dropped = {cands[k]['i'] for k in range(len(cands)) if k not in placed}
+            keep = sorted(k for k in placed if n_s == 1 or cands[k]['i'] not in dropped)
+    for k in keep:
+        c, md_ = cands[k], modes[k]
+        if horizontal:
+            ax.annotate(c['text'], (c['v'], c['pos']), xytext=(3.5 if c['v'] >= 0 else -3.5, 0),
+                        textcoords='offset points', va='center', ha='left' if c['v'] >= 0 else 'right',
+                        fontsize=FS_TICK, color=INK1)
+            continue
+        anchor_x = c['c1'] if md_ == 'in_left' else (c['c0'] if md_ == 'in_right' else c['pos'])
+        ha = 'right' if md_ == 'in_left' else ('left' if md_ == 'in_right' else 'center')
+        dx = -shift_pt if md_ == 'in_left' else (shift_pt if md_ == 'in_right' else 0)
+        ax.annotate(c['text'], (anchor_x, c['v']), xytext=(dx, 3.5 if c['v'] >= 0 else -3.5),
+                    textcoords='offset points', ha=ha, va='bottom' if c['v'] >= 0 else 'top',
+                    fontsize=FS_TICK, color=INK1)
+    return len(cands) - len(keep)
+
+
+# ── 柱 / 条 / 堆叠 ───────────────────────────────────────────────────────────
+def render_bars(spec, cv, horizontal=False, stacked=False):
+    cats = [str(c) for c in (spec.get('categories') or [])]
+    if not cats:
+        raise SpecError('缺 categories（横轴类别）')
+    series = get_series(spec, len(cats))
+    cols = colors_for(series, spec)
+    unit = spec.get('unit', '')
+    ax = cv.ax
+    n_s, n_c = len(series), len(cats)
+    if stacked and any(v < 0 for s in series for v in s['values']):
+        raise SpecError('堆叠图不支持负值：正负混合请用分组柱或拆成两张图')
+
+    if stacked:
+        totals = [sum(s['values'][j] for s in series) for j in range(n_c)]
+        lo, hi = 0.0, max(totals + [0])
+    else:
+        allv = [v for s in series for v in s['values']]
+        lo, hi = min(allv + [0]), max(allv + [0])
+    ticks = nice_ticks(lo, hi)
+    vmin, vmax = ticks[0], ticks[-1]
+    pad = (vmax - vmin) * 0.08                     # 顶部给数值标注留位
+    legend_items = [(s['name'], c, 'bar') for s, c in zip(series, cols)] if n_s > 1 else []
+    band = top_band(cv, legend_items, unit)
+
+    # 先定坐标范围与刻度，再量标签宽度定页边距
+    if horizontal:
+        ax.set_ylim(n_c - 0.5, -0.5)
+        ax.set_xlim(vmin, vmax + (pad if vmax > 0 else 0))
+        ax.set_xticks(ticks)
+        ax.set_xticklabels([fmt(t) for t in ticks])
+        max_chars = 10
+        labels = [wrap_cjk(c, max_chars) for c in cats]
+        ax.set_yticks(range(n_c))
+        ax.set_yticklabels(labels)
+        lw = max(cv.text_w_in(l, FS_TICK)[0] for l in labels) + 0.12
+        cv.layout(min(lw, cv.w_in * 0.38), 0.45, band + 0.05, 0.32)
+        style_axes(ax, 'x')
+    else:
+        ax.set_xlim(-0.5, n_c - 0.5)
+        ax.set_ylim(vmin - (pad if vmin < 0 else 0), vmax + pad)
+        ax.set_yticks(ticks)
+        ax.set_yticklabels([fmt(t) for t in ticks])
+        slot_in = (cv.w_in * 0.82) / n_c
+        max_chars = max(2, int(slot_in / (FS_TICK / 72 * 1.05)))
+        labels = [wrap_cjk(c, max_chars) for c in cats]
+        ax.set_xticks(range(n_c))
+        ax.set_xticklabels(labels)
+        lw = max(cv.text_w_in(fmt(t), FS_TICK)[0] for t in ticks) + 0.1
+        two_line = any('\n' in l for l in labels)
+        cv.layout(lw, 0.12, band + 0.05, 0.42 if two_line else 0.3)
+        style_axes(ax, 'y')
+
+    # 柱宽：组宽 0.72 个槽位，单根不超过 0.6cm（三位数标注刚好压得住）；组内柱之间 2px 白缝
+    pxu_x, pxu_y = cv.px_per_unit()
+    along_px = pxu_y if horizontal else pxu_x          # 沿类别方向每单位像素
+    cap_units = (0.6 * CM * DPI) / along_px
+    group = 0.72
+    thick = min(group / (1 if stacked else n_s), cap_units)
+    gap_units = (2 / 96 * DPI) / along_px              # 2px@96dpi
+    r_units_along = (1.0 / 10 * CM * DPI) / along_px   # 1mm 圆角
+    r_units_val = (1.0 / 10 * CM * DPI) / (pxu_x if horizontal else pxu_y)
+
+    label_mode = spec.get('labels', 'auto')
+    ld = label_dec([v for s_ in series for v in s_['values']] + ([sum(s_['values'][j] for s_ in series) for j in range(n_c)]
+                                                               if stacked else []))
+    n_bars = n_c if stacked else n_c * n_s
+    show_vals = label_mode == 'all' or (label_mode == 'auto' and n_bars <= 16)
+    if any(c in LOW_CONTRAST for c in cols) and label_mode == 'none':
+        cv.warnings.append('用到了白底对比度 <3:1 的颜色（青/黄/粉），按规则应显示数值标注或在文中附数据表')
+
+    cands = []
+    for j in range(n_c):
+        if stacked:
+            base = 0.0
+            last = max((i for i in range(n_s) if series[i]['values'][j] > 0), default=None)
+            for i, s in enumerate(series):
+                v = s['values'][j]
+                if v <= 0:
+                    continue
+                c0, c1 = j - thick / 2, j + thick / 2
+                if horizontal:
+                    path = rounded_bar(base, base + v, c0, c1, r_units_val, r_units_along, 'right') if i == last \
+                        else Path([(base, c0), (base + v, c0), (base + v, c1), (base, c1), (base, c0)],
+                                  [Path.MOVETO, Path.LINETO, Path.LINETO, Path.LINETO, Path.CLOSEPOLY])
+                else:
+                    path = rounded_bar(c0, c1, base, base + v, r_units_along, r_units_val, 'top') if i == last \
+                        else Path([(c0, base), (c1, base), (c1, base + v), (c0, base + v), (c0, base)],
+                                  [Path.MOVETO, Path.LINETO, Path.LINETO, Path.LINETO, Path.CLOSEPOLY])
+                ax.add_patch(PathPatch(path, facecolor=cols[i], edgecolor=SURFACE, linewidth=1.5, zorder=3))
+                base += v
+            if show_vals and base > 0:
+                cands.append({'v': base, 'pos': j, 'c0': j - thick / 2, 'c1': j + thick / 2, 'i': 0,
+                              'text': fmt(base, ld)})
+        else:
+            total_w = thick * n_s + gap_units * (n_s - 1)
+            for i, s in enumerate(series):
+                v = s['values'][j]
+                c0 = j - total_w / 2 + i * (thick + gap_units)
+                c1 = c0 + thick
+                if horizontal:
+                    end = 'right' if v >= 0 else 'left'
+                    path = rounded_bar(0, v, c0, c1, r_units_val, r_units_along, end)
+                else:
+                    end = 'top' if v >= 0 else 'bottom'
+                    path = rounded_bar(c0, c1, 0, v, r_units_along, r_units_val, end)
+                ax.add_patch(PathPatch(path, facecolor=cols[i], edgecolor='none', zorder=3))
+                if show_vals:
+                    cands.append({'v': v, 'pos': (c0 + c1) / 2, 'c0': c0, 'c1': c1, 'i': i, 'text': fmt(v, ld)})
+    if cands:
+        skipped = place_bar_labels(cv, cands, horizontal, n_s if not stacked else 1)
+        if skipped:
+            cv.warnings.append(f'有 {skipped} 个数值标注会与相邻标注重叠，已省略（数值见返回的 table_md，正文里附表）')
+    if lo < 0:
+        (ax.axvline if horizontal else ax.axhline)(0, color=AXIS, linewidth=0.8, zorder=2)
+    y_cursor = 0.06
+    if unit:
+        draw_unit(cv, unit, y_cursor)
+        y_cursor += 0.2
+    if legend_items:
+        draw_legend_row(cv, legend_items, y_cursor)
+    rows = [[cats[j]] + [fmt(s['values'][j]) for s in series] for j in range(n_c)]
+    return table_md(['类别'] + [s['name'] for s in series], rows)
+
+
+# ── 折线 / 面积 ─────────────────────────────────────────────────────────────
+def render_line(spec, cv, area=False):
+    cats = [str(c) for c in (spec.get('categories') or [])]
+    if len(cats) < 2:
+        raise SpecError('折线图至少要 2 个类别点（时间点）')
+    series = get_series(spec, len(cats))
+    if spec.get('y2') or spec.get('secondary_axis'):
+        raise SpecError('不画双纵轴：两个量纲不同的指标请画两张图，或都换算成指数（起点=100）画在一根轴上')
+    cols = colors_for(series, spec)
+    unit = spec.get('unit', '')
+    ax = cv.ax
+    allv = [v for s in series for v in s['values']]
+    zero = spec.get('zero_baseline', True)
+    lo = min(allv + ([0] if zero else []))
+    hi = max(allv + ([0] if zero else []))
+    ticks = nice_ticks(lo, hi)
+    legend_items = [(s['name'], c, 'line') for s, c in zip(series, cols)] if len(series) > 1 else []
+    band = top_band(cv, legend_items, unit)
+    ax.set_xlim(-0.3, len(cats) - 1 + 0.3)
+    ax.set_ylim(ticks[0], ticks[-1])
+    ax.set_yticks(ticks)
+    ax.set_yticklabels([fmt(t) for t in ticks])
+    step = max(1, math.ceil(len(cats) / 12))
+    ax.set_xticks(range(0, len(cats), step))
+    ax.set_xticklabels([cats[i] for i in range(0, len(cats), step)])
+    lw = max(cv.text_w_in(fmt(t), FS_TICK)[0] for t in ticks) + 0.1
+    end_lab = len(series) <= 4 and spec.get('labels', 'auto') != 'none'
+    right = 0.55 if end_lab else 0.15
+    cv.layout(lw, right, band + 0.05, 0.3)
+    style_axes(ax, 'y')
+    xs = list(range(len(cats)))
+    ld = label_dec([s_['values'][-1] for s_ in series])
+    for s, c in zip(series, cols):
+        if area and len(series) == 1:
+            ax.fill_between(xs, [ticks[0] if not zero else 0] * len(xs), s['values'], color=c, alpha=0.1, linewidth=0, zorder=2)
+        ax.plot(xs, s['values'], color=c, linewidth=1.5, zorder=3)
+        mk = len(cats) <= 16
+        if mk:
+            ax.plot(xs, s['values'], linestyle='none', marker='o', markersize=5, markerfacecolor=c,
+                    markeredgecolor=SURFACE, markeredgewidth=1.2, zorder=4)
+    if end_lab:
+        # 线尾标注：几条线收在相近的值上时（290 / 297）标注会叠在一起——
+        # 先按像素排好，再逐个向上推开至少一个字高，最后整体回拉到居中，保持离各自线尾最近
+        h_pt = cv.text_w_in('0', FS_TICK)[1] * 72 + 1.5
+        ends = sorted(((ax.transData.transform((xs[-1], s_['values'][-1]))[1] / cv.fig.dpi * 72, s_['values'][-1])
+                       for s_ in series), key=lambda e: e[0])
+        pos = [e[0] for e in ends]
+        for k in range(1, len(pos)):
+            pos[k] = max(pos[k], pos[k - 1] + h_pt)
+        shift = (sum(e[0] for e in ends) - sum(pos)) / len(pos) if pos else 0
+        lo_pt = ends[0][0] - h_pt * (len(ends) - 1)
+        shift = max(shift, lo_pt - pos[0])
+        for (y0, v), y in zip(ends, pos):
+            ax.annotate(fmt(v, ld), (xs[-1], v), xytext=(6, y + shift - y0), textcoords='offset points',
+                        va='center', fontsize=FS_TICK, color=INK1)
+    if lo < 0 < hi:
+        ax.axhline(0, color=AXIS, linewidth=0.8, zorder=2)
+    y_cursor = 0.06
+    if unit:
+        draw_unit(cv, unit, y_cursor)
+        y_cursor += 0.2
+    if legend_items:
+        draw_legend_row(cv, legend_items, y_cursor)
+    rows = [[cats[j]] + [fmt(s['values'][j]) for s in series] for j in range(len(cats))]
+    return table_md(['类别'] + [s['name'] for s in series], rows)
+
+
+# ── 环形图（构成）───────────────────────────────────────────────────────────
+def render_pie(spec, cv):
+    cats = [str(c) for c in (spec.get('categories') or [])]
+    series = get_series(spec, len(cats))
+    if len(series) != 1:
+        raise SpecError('环形图只画一个系列（一个整体的构成）；多个整体请用堆叠条形图')
+    vals = series[0]['values']
+    if any(v < 0 for v in vals):
+        raise SpecError('构成图不能有负值')
+    items = sorted(zip(cats, vals), key=lambda x: -x[1])
+    if len(items) > 6:
+        tail = items[5:]
+        items = items[:5] + [('其他', sum(v for _, v in tail))]
+        cv.warnings.append(f'构成超过 6 块，已把最小的 {len(tail)} 项并为「其他」（多于 6 块的饼图读不出差别）')
+    total = sum(v for _, v in items)
+    if total <= 0:
+        raise SpecError('构成合计为 0')
+    unit = spec.get('unit', '')
+    ax = cv.ax
+    ax.set_axis_off()
+    # 左侧环、右侧图例表（名称 数值 占比）
+    d = min(cv.h_in - 0.3, cv.w_in * 0.42)
+    ax.set_position([0.04, (cv.h_in - d) / 2 / cv.h_in, d / cv.w_in, d / cv.h_in])
+    ax.set_xlim(-1.05, 1.05)
+    ax.set_ylim(-1.05, 1.05)
+    ax.set_aspect('equal')
+    ang = 90.0
+    for i, (name, v) in enumerate(items):
+        sweep = 360.0 * v / total
+        color = PALETTE[i] if name != '其他' else DEEMPH
+        ax.add_patch(Wedge((0, 0), 1.0, ang - sweep, ang, width=0.34, facecolor=color,
+                           edgecolor=SURFACE, linewidth=1.5))
+        ang -= sweep
+    ld = label_dec([v for _, v in items] + [total])
+    ax.text(0, 0.1, fmt(total, ld), ha='center', va='center', fontsize=FS_TITLE + 3, color=INK1, fontweight='semibold')
+    ax.text(0, -0.2, f'合计（{unit}）' if unit else '合计', ha='center', va='center', fontsize=FS_TICK, color=MUTED)
+    x0 = 0.04 + d / cv.w_in + 0.06
+    row_h = min(0.28, (cv.h_in - 0.4) / max(len(items), 1))
+    y = 0.5 + (len(items) * row_h) / 2 / cv.h_in
+    for i, (name, v) in enumerate(items):
+        color = PALETTE[i] if name != '其他' else DEEMPH
+        yy = y - (i + 0.5) * row_h / cv.h_in
+        cv.fig.add_artist(Rectangle((x0, yy - 0.045 / cv.h_in), 0.09 / cv.w_in, 0.09 / cv.h_in,
+                                    facecolor=color, edgecolor='none', transform=cv.fig.transFigure))
+        cv.fig.text(x0 + 0.16 / cv.w_in, yy, name, fontsize=FS_LABEL, color=INK1, va='center')
+        cv.fig.text(0.97, yy, f'{fmt(v, ld)}  （{v / total * 100:.1f}%）', fontsize=FS_LABEL, color=INK2,
+                    va='center', ha='right')
+    rows = [[n, fmt(v), f'{v / total * 100:.1f}%'] for n, v in items]
+    return table_md(['构成项', f'数值（{unit}）' if unit else '数值', '占比'], rows)
+
+
+# ── 瀑布图（逐项累加到总额）────────────────────────────────────────────────
+def render_waterfall(spec, cv):
+    items = spec.get('items') or []
+    if len(items) < 2:
+        raise SpecError('瀑布图至少 2 项：items:[{"name":"人员","value":240},…]')
+    names = [str(it.get('name', '')) for it in items]
+    vals = [_num(it.get('value'), f'items[{i}].value') for i, it in enumerate(items)]
+    total_label = spec.get('total_label', '合计')
+    unit = spec.get('unit', '')
+    ax = cv.ax
+    run = 0.0
+    tops, bots = [], []
+    for v in vals:
+        tops.append(max(run, run + v))
+        bots.append(min(run, run + v))
+        run += v
+    total = run
+    cats = names + [total_label]
+    ticks = nice_ticks(min(bots + [0]), max(tops + [total, 0]))
+    pad = (ticks[-1] - ticks[0]) * 0.08
+    ax.set_xlim(-0.5, len(cats) - 0.5)
+    ax.set_ylim(ticks[0], ticks[-1] + pad)
+    ax.set_yticks(ticks)
+    ax.set_yticklabels([fmt(t) for t in ticks])
+    slot_in = (cv.w_in * 0.82) / len(cats)
+    max_chars = max(2, int(slot_in / (FS_TICK / 72 * 1.05)))
+    labels = [wrap_cjk(c, max_chars) for c in cats]
+    ax.set_xticks(range(len(cats)))
+    ax.set_xticklabels(labels)
+    lw = max(cv.text_w_in(fmt(t), FS_TICK)[0] for t in ticks) + 0.1
+    band = top_band(cv, [], unit)
+    cv.layout(lw, 0.12, band + 0.05, 0.42 if any('\n' in l for l in labels) else 0.3)
+    style_axes(ax, 'y')
+    pxu_x, pxu_y = cv.px_per_unit()
+    thick = min(0.62, (0.45 * CM * DPI) / pxu_x)
+    rx = (1.0 / 10 * CM * DPI) / pxu_x
+    ry = (1.0 / 10 * CM * DPI) / pxu_y
+    run = 0.0
+    ld = label_dec(vals + [total])
+    for j, v in enumerate(vals):
+        c0, c1 = j - thick / 2, j + thick / 2
+        y0, y1 = (run, run + v)
+        color = SEQ[5] if v >= 0 else NEG
+        path = rounded_bar(c0, c1, y0, y1, rx, ry, 'top' if v >= 0 else 'bottom')
+        ax.add_patch(PathPatch(path, facecolor=color, edgecolor='none', zorder=3))
+        ax.annotate(fmt(v, ld, signed=True), (j, max(y0, y1)), xytext=(0, 3), textcoords='offset points',
+                    ha='center', fontsize=FS_TICK, color=INK1)
+        # 连接线：上一根柱的终点接到下一根柱的起点（实线细线，退后）
+        nxt = run + v
+        ax.plot([c1, c1 + 1 - thick], [nxt, nxt], color=AXIS, linewidth=0.6, zorder=2)
+        run = nxt
+    j = len(vals)
+    ax.add_patch(PathPatch(rounded_bar(j - thick / 2, j + thick / 2, 0, total, rx, ry, 'top' if total >= 0 else 'bottom'),
+                           facecolor=SEQ[9], edgecolor='none', zorder=3))
+    ax.annotate(fmt(total, ld), (j, max(total, 0)), xytext=(0, 3), textcoords='offset points', ha='center',
+                fontsize=FS_TICK, color=INK1, fontweight='semibold')
+    draw_unit(cv, unit, 0.06)
+    rows = [[n, fmt(v), f'{v / total * 100:.1f}%' if total else '—'] for n, v in zip(names, vals)] \
+        + [[total_label, fmt(total), '100%']]
+    return table_md(['项目', f'金额（{unit}）' if unit else '金额', '占比'], rows)
+
+
+# ── 龙卷风图（敏感性）──────────────────────────────────────────────────────
+def render_tornado(spec, cv):
+    base = _num(spec.get('base'), 'base')
+    items = spec.get('items') or []
+    if not items:
+        raise SpecError('龙卷风图要 items:[{"name":"授权单价","low":…,"high":…,"low_label":"-20%","high_label":"+20%"}]')
+    rows_in = []
+    for i, it in enumerate(items):
+        lo = _num(it.get('low'), f'items[{i}].low')
+        hi = _num(it.get('high'), f'items[{i}].high')
+        rows_in.append((str(it.get('name', f'因素{i + 1}')), lo, hi,
+                        str(it.get('low_label', '下调')), str(it.get('high_label', '上调'))))
+    rows_in.sort(key=lambda r: -abs(r[2] - r[1]))     # 影响最大的放最上面
+    unit = spec.get('unit', '')
+    metric = spec.get('metric', '指标')
+    ax = cv.ax
+    allv = [base] + [r[1] for r in rows_in] + [r[2] for r in rows_in]
+    ld = label_dec(allv)
+    labels = [wrap_cjk(r[0], 9) for r in rows_in]
+    lw = max(cv.text_w_in(l, FS_TICK)[0] for l in labels) + 0.12
+    legend_items = [(f'{metric}高于基准', POS, 'bar'), (f'{metric}低于基准', NEG, 'bar')]
+    band = top_band(cv, legend_items, '') + 0.16          # 再留一行给「基准」标注
+    cv.layout(min(lw, cv.w_in * 0.35), 0.2, band + 0.05, 0.42)
+    style_axes(ax, 'x')
+    # 条外侧的「数值（变动）」标注要占地方：先量每条标注多宽，再反解横轴范围，
+    # 保证最长那条也落在绘图区内——否则最左边的标注会压到因素名上
+    fs_v = FS_TICK - 0.5
+    ax_w_in = ax.get_position().width * cv.w_in
+    ext = []
+    for _, lo, hi, ll, hl in rows_in:
+        for v, lab in ((lo, ll), (hi, hl)):
+            if abs(v - base) >= 1e-12:
+                ext.append((v, 1 if v > base else -1, cv.text_w_in(f'{fmt(v, ld)}（{lab}）', fs_v)[0] + 0.1))
+    need_lo, need_hi = min(allv), max(allv)
+    for _ in range(8):
+        ticks = nice_ticks(need_lo, need_hi)
+        k = ax_w_in / ((ticks[-1] - ticks[0]) or 1)       # 每单位数据多少英寸
+        want_lo = min([need_lo] + [v - w / k for v, sd, w in ext if sd < 0])
+        want_hi = max([need_hi] + [v + w / k for v, sd, w in ext if sd > 0])
+        if want_lo >= ticks[0] - 1e-9 and want_hi <= ticks[-1] + 1e-9:
+            break
+        need_lo, need_hi = want_lo, want_hi
+    ax.set_xlim(ticks[0], ticks[-1])
+    lo_d, hi_d = min(allv), max(allv)
+    dticks = [t for t in nice_ticks(lo_d, hi_d) if ticks[0] <= t <= ticks[-1]]
+    if lo_d >= 0:
+        dticks = [t for t in dticks if t >= 0]              # 数据全为正时，不为给标注让位而标出负刻度
+    ax.set_xticks(dticks)
+    ax.set_xticklabels([fmt(t) for t in dticks])
+    ax.set_ylim(len(rows_in) - 0.5, -0.5)
+    ax.set_yticks(range(len(rows_in)))
+    ax.set_yticklabels(labels)
+    pxu_x, pxu_y = cv.px_per_unit()
+    thick = min(0.56, (0.45 * CM * DPI) / pxu_y)
+    rx = (1.0 / 10 * CM * DPI) / pxu_x
+    ry = (1.0 / 10 * CM * DPI) / pxu_y
+    for j, (name, lo, hi, ll, hl) in enumerate(rows_in):
+        for v, lab in ((lo, ll), (hi, hl)):
+            if abs(v - base) < 1e-12:
+                continue
+            color = POS if v > base else NEG
+            end = 'right' if v > base else 'left'
+            ax.add_patch(PathPatch(rounded_bar(base, v, j - thick / 2, j + thick / 2, rx, ry, end),
+                                   facecolor=color, edgecolor='none', zorder=3))
+            ax.annotate(f'{fmt(v, ld)}（{lab}）', (v, j), xytext=(4 if v > base else -4, 0), textcoords='offset points',
+                        ha='left' if v > base else 'right', va='center', fontsize=fs_v, color=INK1)
+    ax.axvline(base, color=INK1, linewidth=0.8, zorder=4)
+    ax.annotate(f'基准 {fmt(base, ld)}', (base, -0.5), xytext=(0, 2), textcoords='offset points', ha='center',
+                va='bottom', fontsize=FS_TICK, color=INK1, annotation_clip=False)
+    ax.set_xlabel(f'{metric}（{unit}）' if unit else metric, fontsize=FS_TICK, color=INK2)
+    draw_legend_row(cv, legend_items, 0.06)
+    rows = [[n, ll, fmt(lo), hl, fmt(hi), fmt(hi - lo)] for n, lo, hi, ll, hl in rows_in]
+    return table_md(['因素', '下调', f'{metric}', '上调', f'{metric}', '变动幅度'], rows)
+
+
+# ── 甘特图（进度）──────────────────────────────────────────────────────────
+def _parse_date(s, where):
+    s = str(s).strip()
+    for f in ('%Y-%m-%d', '%Y-%m', '%Y/%m/%d', '%Y/%m', '%Y.%m.%d', '%Y.%m'):
+        try:
+            return _dt.datetime.strptime(s, f).date()
+        except ValueError:
+            continue
+    raise SpecError(f'{where} 日期看不懂：{s!r}（写成 2026-10 或 2026-10-15）')
+
+
+def _month_end(d):
+    nxt = _dt.date(d.year + (d.month // 12), d.month % 12 + 1, 1)
+    return nxt - _dt.timedelta(days=1)
+
+
+def render_gantt(spec, cv):
+    tasks = spec.get('tasks') or []
+    if not tasks:
+        raise SpecError('甘特图要 tasks:[{"name":"需求分析","start":"2026-10","end":"2026-11","group":"第一阶段"}]')
+    rows = []
+    for i, t in enumerate(tasks):
+        s = _parse_date(t.get('start'), f'tasks[{i}].start')
+        e_raw = str(t.get('end', ''))
+        e = _parse_date(e_raw, f'tasks[{i}].end')
+        if len(e_raw.strip()) <= 7:                      # 只写到月 = 到月底
+            e = _month_end(e)
+        if e < s:
+            raise SpecError(f'tasks[{i}]「{t.get("name")}」结束早于开始')
+        rows.append((str(t.get('name', f'任务{i + 1}')), s, e, str(t.get('group', ''))))
+    groups = []
+    for r in rows:
+        if r[3] and r[3] not in groups:
+            groups.append(r[3])
+    if len(groups) > 8:
+        raise SpecError('分组超过 8 个：合并阶段或拆成两张图')
+    gcol = {g: PALETTE[i] for i, g in enumerate(groups)}
+    ms = []
+    for i, m in enumerate(spec.get('milestones') or []):
+        ms.append((str(m.get('name', f'里程碑{i + 1}')), _parse_date(m.get('date'), f'milestones[{i}].date')))
+    d0 = min([r[1] for r in rows] + [m[1] for m in ms])
+    d1 = max([r[2] for r in rows] + [m[1] for m in ms])
+    d0 = _dt.date(d0.year, d0.month, 1)
+    d1 = _month_end(d1)
+    today = spec.get('today')
+    today_d = _parse_date(today, 'today') if today else None
+    # 计划紧接着编制日开始（两个月内）：把编制日也纳入横轴，读者一眼看出「从现在起」
+    if today_d and today_d < d0 and (d0 - today_d).days <= 62:
+        d0 = _dt.date(today_d.year, today_d.month, 1)
+
+    def xo(d):
+        return (d - d0).days
+
+    ax = cv.ax
+    n = len(rows)
+    fs_ms = FS_TICK - 0.5
+    # ① 任务名：放得下就一行；放不下按可用宽度折行，行高随之加大（折行的名字压到下一行是基线里的真实翻车）
+    max_lab_in = cv.w_in * 0.40
+
+    def fit(name):
+        w = cv.text_w_in(name, FS_TICK)[0]
+        if w <= max_lab_in - 0.12:
+            return name
+        return wrap_cjk(name, max(4, int(len(name) * (max_lab_in - 0.12) / w)))
+    labels = [fit(r[0]) for r in rows]
+    maxlines = max(l.count('\n') + 1 for l in labels)
+    lw = min(max(cv.text_w_in(l, FS_TICK)[0] for l in labels) + 0.12, max_lab_in)
+    legend_items = [(g, gcol[g], 'bar') for g in groups] if len(groups) > 1 else []
+    band_top = top_band(cv, legend_items, '') + (0.18 if today_d else 0) + 0.05
+    bottom_in = 0.32
+    line_in = cv.text_w_in('里程碑', fs_ms)[1] * 1.2
+    row_in = max(0.62 * CM, (FS_TICK / 72) * 1.3 * maxlines + 0.1)
+    tail = max(8, int(xo(d1) * 0.025))                  # 右侧留白：末尾的里程碑菱形与标注不被裁
+    x_max = xo(d1) + 1 + tail
+    axes_w_in = cv.w_in - lw - 0.2
+    unit_in = axes_w_in / x_max                          # 1 天占多少英寸
+    # ② 里程碑标注：量宽度后贪心排进最多 3 行；还放不下就改成编号 + 图下注——相邻里程碑的名字叠成一团没人读得出
+    CIRCLED = '①②③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮⑯⑰⑱⑲⑳'
+    ms_sorted = sorted(ms, key=lambda m: m[1])
+
+    def arrange(texts):
+        ends, out = [], []
+        for text, d in texts:
+            w = cv.text_w_in(text, fs_ms)[0] + 0.06
+            cx = (xo(d) + 0.5) * unit_in
+            if cx - w / 2 >= 0 and cx + w / 2 <= axes_w_in:
+                x0, ha = cx - w / 2, 'center'
+            elif cx + w <= axes_w_in:
+                x0, ha = cx - 0.04, 'left'
+            else:
+                x0, ha = cx - w + 0.04, 'right'
+            row = next((k for k, e in enumerate(ends) if e + 0.05 <= x0), None)
+            if row is None:
+                if len(ends) >= 3:
+                    return None
+                ends.append(0.0)
+                row = len(ends) - 1
+            ends[row] = x0 + w
+            out.append((text, d, row, ha))
+        return out
+    placed = arrange(ms_sorted) if ms_sorted else []
+    note = ''
+    if ms_sorted and placed is None:
+        marks = [CIRCLED[i] if i < len(CIRCLED) else str(i + 1) for i in range(len(ms_sorted))]
+        placed = arrange([(mk, d) for mk, (_, d) in zip(marks, ms_sorted)]) or \
+            [(mk, d, 0, 'center') for mk, (_, d) in zip(marks, ms_sorted)]
+        note = '里程碑：' + '；'.join(f'{mk} {nm}（{d.isoformat()}）' for mk, (nm, d) in zip(marks, ms_sorted))
+    k_rows = 1 + max((p[2] for p in placed), default=-1)
+    dh_in = 0.07                                         # 菱形半高
+    band_in = (0.08 + 2 * dh_in + 0.04 + k_rows * line_in + 0.04) if ms_sorted else 0.0
+    note_lines = wrap_measured(cv, note, fs_ms, cv.w_in - 0.3) if note else ''
+    note_in = (note_lines.count('\n') + 1) * line_in + 0.06 if note else 0.0
+    # ③ 画布高度按行高算（用户给了 height_cm 就尊重）
+    if not spec.get('height_cm'):
+        cv.resize(min(18.0, (band_top + bottom_in + note_in + cv.note_in + n * row_in + band_in) / CM))
+    axes_h_in = max(cv.h_in - band_top - bottom_in - note_in - cv.note_in, 0.5)
+    band_units = band_in * n / max(axes_h_in - band_in, 0.2) if ms_sorted else 0.0
+    unit_y_in = axes_h_in / (n + band_units)
+    ax.set_ylim(n - 0.5 + band_units, -0.5)
+    ax.set_xlim(0, x_max)
+    months = []
+    d = d0
+    while d <= d1:
+        months.append(d)
+        d = _dt.date(d.year + (d.month // 12), d.month % 12 + 1, 1)
+    ax.set_yticks(range(n))
+    ax.set_yticklabels(labels)
+    cv.layout(lw, 0.2, band_top, bottom_in + note_in)
+    style_axes(ax, 'x')
+    ax.spines['left'].set_visible(False)                 # 左缘有月网格线了，再画轴线会成双线
+    # 月刻度：先量「2026-10」有多宽，再决定隔几个月标一个——标签挤在一起比少标几个更难读
+    lab_w = cv.text_w_in('2026-10', FS_TICK)[0] * 1.35
+    pxu_x0, _ = cv.px_per_unit()
+    month_w_in = 30.4 * pxu_x0 / DPI
+    step = next(k for k in (1, 2, 3, 6, 12) if month_w_in * k >= lab_w or k == 12)
+    shown = [m for i, m in enumerate(months) if i % step == 0]
+    ax.set_xticks([xo(m) for m in shown])
+    ax.set_xticklabels([f'{m.year}-{m.month:02d}' for m in shown])
+    ax.xaxis.grid(True, color=GRID, linewidth=0.5)
+    pxu_x, pxu_y = cv.px_per_unit()
+    thick = min(0.56, (0.4 * CM * DPI) / pxu_y)
+    rx = (1.0 / 10 * CM * DPI) / pxu_x
+    ry = (1.0 / 10 * CM * DPI) / pxu_y
+    for j, (name, s, e, g) in enumerate(rows):
+        c = gcol.get(g, PALETTE[0])
+        x0, x1 = xo(s), xo(e) + 1
+        ax.add_patch(PathPatch(capsule_h(x0, x1, j - thick / 2, j + thick / 2, rx, ry),
+                               facecolor=c, edgecolor='none', zorder=3))
+    if ms_sorted:
+        dh = dh_in / unit_y_in                            # 菱形半高（数据单位）
+        dw = dh_in / unit_in                              # 菱形半宽（天）
+        yb = n - 0.5 + (0.08 + dh_in) / unit_y_in
+        for text, d, row, ha in placed:
+            x = xo(d) + 0.5
+            ax.add_patch(Polygon([(x, yb - dh), (x + dw, yb), (x, yb + dh), (x - dw, yb)], closed=True,
+                                 facecolor=INK1, edgecolor=SURFACE, linewidth=0.8, zorder=5))
+            if row:
+                y_lab = yb + (dh_in + 3 / 72 + row * line_in) / unit_y_in
+                ax.plot([x, x], [yb + dh, y_lab - 0.02 / unit_y_in], color=AXIS, linewidth=0.6, zorder=4)
+            # 白底：下一行标注的引线从文字下面穿过，不压字
+            ax.annotate(text, (x, yb), xytext=(0, -(dh_in * 72 + 3 + row * line_in * 72)), textcoords='offset points',
+                        ha=ha, va='top', fontsize=fs_ms, color=INK1, annotation_clip=False, zorder=6,
+                        bbox=dict(boxstyle='square,pad=0.12', facecolor=SURFACE, edgecolor='none'))
+        if note:
+            # 从画布左缘起排（任务名那一栏下面是空的），折行宽度与起点用同一个口径，否则右端被裁
+            cv.fig.text(0.12 / cv.w_in, (cv.note_in + 0.03) / cv.h_in, note_lines, fontsize=fs_ms, color=INK2,
+                        va='bottom', ha='left')
+    if today_d and d0 <= today_d <= d1:
+        x = xo(today_d)
+        ax.axvline(x, color=MUTED, linewidth=0.8, zorder=4)
+        lab = f'编制日 {today_d.isoformat()}'
+        half = cv.text_w_in(lab, fs_ms)[0] / 2 / unit_in       # 半个标注宽（天）
+        ha = 'right' if x + half > x_max else ('left' if x - half < 0 else 'center')   # 贴边时往里让，不出画布
+        ax.annotate(lab, (x, -0.5), xytext=(0, 2), textcoords='offset points',
+                    ha=ha, va='bottom', fontsize=fs_ms, color=INK2, annotation_clip=False)
+    elif today_d and d1 < today_d:
+        cv.warnings.append(f'整张进度计划都早于 today（{today_d}）：若是立项前的计划，时间要顺延到编制日之后；若是补写归档请在文中说明')
+    y_cursor = 0.06 + (0.18 if today_d else 0)
+    if legend_items:
+        draw_legend_row(cv, legend_items, y_cursor)
+    trows = [[r[0], r[3] or '—', r[1].isoformat(), r[2].isoformat(), (r[2] - r[1]).days + 1] for r in rows]
+    return table_md(['任务', '阶段', '开始', '结束', '天数'], trows)
+
+
+# ── 风险矩阵（可能性 × 影响）──────────────────────────────────────────────
+LEVELS = [(20, '极高', 'critical'), (10, '高', 'high'), (5, '中', 'mid'), (0, '低', 'low')]
+
+
+def _level(score):
+    for th, name, key in LEVELS:
+        if score >= th:
+            return name, key
+    return '低', 'low'
+
+
+def render_matrix(spec, cv):
+    items = spec.get('items') or []
+    if not items:
+        raise SpecError('风险矩阵要 items:[{"id":"R1","name":"上游模型接口变更","p":3,"i":4}]（p=可能性 1-5，i=影响 1-5）')
+    p_labels = spec.get('p_labels') or ['极低', '较低', '中等', '较高', '极高']
+    i_labels = spec.get('i_labels') or ['极小', '较小', '中等', '较大', '重大']
+    cells = {}
+    rows = []
+    for k, it in enumerate(items):
+        p = int(_num(it.get('p'), f'items[{k}].p'))
+        i = int(_num(it.get('i'), f'items[{k}].i'))
+        if not (1 <= p <= 5 and 1 <= i <= 5):
+            raise SpecError(f'items[{k}] 的 p/i 要在 1~5 之间')
+        rid = str(it.get('id') or f'R{k + 1}')
+        cells.setdefault((p, i), []).append(rid)
+        lvl, _ = _level(p * i)
+        rows.append([rid, str(it.get('name', '')), p, i, p * i, lvl])
+    ax = cv.ax
+    ax.set_xlim(0.5, 5.5)
+    ax.set_ylim(0.5, 5.5)
+    ax.set_xticks(range(1, 6))
+    ax.set_xticklabels(i_labels)
+    ax.set_yticks(range(1, 6))
+    ax.set_yticklabels(p_labels)
+    legend_items = [(f'{name}（≥{th}）' if th else f'{name}（<5）', STATUS[key], 'bar') for th, name, key in LEVELS[::-1]]
+    band = top_band(cv, legend_items, '')
+    lw = max(cv.text_w_in(l, FS_TICK)[0] for l in p_labels) + 0.45
+    # 矩阵要方：按可用高度定宽度
+    h_avail = cv.h_in - band - 0.05 - 0.55
+    w_plot = min(h_avail, cv.w_in - lw - 0.3)
+    cv.layout(lw, cv.w_in - lw - w_plot, band + 0.05, 0.55)
+    for s in ax.spines.values():
+        s.set_visible(False)
+    ax.tick_params(length=0, pad=4)
+    ax.set_xlabel('影响程度', fontsize=FS_LABEL, color=INK2, labelpad=6)
+    ax.set_ylabel('发生可能性', fontsize=FS_LABEL, color=INK2, labelpad=6)
+    tint = {'low': 0.16, 'mid': 0.28, 'high': 0.30, 'critical': 0.32}
+    for p in range(1, 6):
+        for i in range(1, 6):
+            _, key = _level(p * i)
+            ax.add_patch(Rectangle((i - 0.5, p - 0.5), 1, 1, facecolor=STATUS[key], alpha=tint[key],
+                                   edgecolor=SURFACE, linewidth=1.5, zorder=2))
+            ids = cells.get((p, i))
+            if ids:
+                txt = '、'.join(ids) if len(ids) <= 2 else '、'.join(ids[:2]) + f'\n等{len(ids)}项'
+                ax.text(i, p, txt, ha='center', va='center', fontsize=FS_TICK, color=INK1, fontweight='semibold', zorder=3)
+    draw_legend_row(cv, legend_items, 0.06)
+    rows.sort(key=lambda r: (-r[4], r[0]))
+    # 格子里只放得下编号：右侧空白列出「编号 名称」，按分值从高到低，图自己就讲得清（不必翻表对编号）
+    list_x = lw + w_plot + 0.35
+    list_w = cv.w_in - list_x - 0.1
+    if list_w >= 1.6:
+        line_h = cv.text_w_in('R1', FS_TICK)[1] * 1.6
+        top_in = band + 0.12
+        cap = max(1, int((cv.h_in - top_in - 0.55 - cv.note_in) / line_h))
+        shown = rows if len(rows) <= cap else rows[:cap - 1]
+        for k, r in enumerate(shown):
+            y = 1 - (top_in + (k + 0.5) * line_h) / cv.h_in
+            _, key = _level(r[4])
+            cv.fig.add_artist(Rectangle((list_x / cv.w_in, y - 0.045 / cv.h_in), 0.09 / cv.w_in, 0.09 / cv.h_in,
+                                        facecolor=STATUS[key], edgecolor='none', transform=cv.fig.transFigure))
+            name, text = r[1], f'{r[0]}  {r[1]}'
+            while cv.text_w_in(text, FS_TICK)[0] > list_w - 0.2 and len(name) > 2:
+                name = name[:-1]
+                text = f'{r[0]}  {name}…'
+            cv.fig.text((list_x + 0.16) / cv.w_in, y, text, fontsize=FS_TICK, color=INK1, va='center')
+        if len(shown) < len(rows):
+            y = 1 - (top_in + (len(shown) + 0.5) * line_h) / cv.h_in
+            cv.fig.text((list_x + 0.16) / cv.w_in, y, f'……另有 {len(rows) - len(shown)} 项，见风险登记表',
+                        fontsize=FS_TICK, color=MUTED, va='center')
+    return table_md(['编号', '风险', '可能性', '影响', '分值', '等级'], rows)
+
+
+RENDERERS = {
+    'bar': lambda s, c: render_bars(s, c),
+    'column': lambda s, c: render_bars(s, c),
+    'hbar': lambda s, c: render_bars(s, c, horizontal=True),
+    'stacked': lambda s, c: render_bars(s, c, stacked=True),
+    'hstacked': lambda s, c: render_bars(s, c, horizontal=True, stacked=True),
+    'line': lambda s, c: render_line(s, c),
+    'area': lambda s, c: render_line(s, c, area=True),
+    'pie': render_pie,
+    'donut': render_pie,
+    'waterfall': render_waterfall,
+    'tornado': render_tornado,
+    'gantt': render_gantt,
+    'matrix': render_matrix,
+    'risk_matrix': render_matrix,
+}
+
+DEFAULT_H = {'pie': 6.2, 'donut': 6.2, 'matrix': 8.6, 'risk_matrix': 8.6}
+
+
+def render(spec, out_png):
+    t = str(spec.get('type', '')).strip().lower()
+    if t not in RENDERERS:
+        raise SpecError(f'不认识的图型「{t}」。可选：bar/hbar/stacked/hstacked/line/area/pie/waterfall/tornado/gantt/matrix')
+    font = setup_font()
+    _base_rc()
+    width = HALF_W_CM if spec.get('size') == 'half' else FULL_W_CM
+    if spec.get('width_cm'):
+        width = max(6.0, min(float(spec['width_cm']), 17.0))
+    height = spec.get('height_cm')
+    if not height:
+        if t == 'gantt':
+            n = len(spec.get('tasks') or [])
+            height = min(18.0, 2.2 + 0.62 * n + (0.9 if spec.get('milestones') else 0))
+        elif t in ('hbar', 'hstacked', 'tornado'):
+            n = len(spec.get('categories') or spec.get('items') or [])
+            height = min(18.0, 2.0 + 0.62 * n)
+        else:
+            height = DEFAULT_H.get(t, 7.2 if width > 10 else 6.0)
+    cv = Canvas(width, float(height))
+    note_lines = ''
+    if spec.get('note'):
+        note = str(spec['note'])
+        note_lines = wrap_measured(cv, note, FS_TICK - 0.5, cv.w_in - 0.3)
+        cv.note_in = (note_lines.count('\n') + 1) * cv.text_w_in('注', FS_TICK - 0.5)[1] * 1.2 + 0.1
+    if not font:
+        cv.warnings.append('本机没有找到中文字体，图里的中文会显示成方块——请安装思源黑体/微软雅黑等字体后重画')
+    tbl = RENDERERS[t](spec, cv)
+    if spec.get('title') and spec.get('show_title'):
+        cv.fig.suptitle(str(spec['title']), x=cv.ax.get_position().x0, ha='left', fontsize=FS_TITLE, color=INK1)
+    if note_lines:
+        cv.fig.text(0.12 / cv.w_in, 0.03 / cv.h_in, note_lines, fontsize=FS_TICK - 0.5, color=MUTED, va='bottom', ha='left')
+    os.makedirs(os.path.dirname(os.path.abspath(out_png)) or '.', exist_ok=True)
+    cv.fig.savefig(out_png, dpi=DPI, facecolor=SURFACE)
+    svg = os.path.splitext(out_png)[0] + '.svg'
+    cv.fig.savefig(svg, facecolor=SURFACE)
+    plt.close(cv.fig)
+    return {'ok': True, 'png': out_png, 'svg': svg, 'width_cm': round(width, 2), 'height_cm': round(cv.h_in / CM, 2),
+            'font': font, 'table_md': tbl, 'warnings': cv.warnings}
+
+
+def main(argv):
+    if len(argv) < 3:
+        print(json.dumps({'ok': False, 'error': '用法：chart_render.py <spec.json> <out.png>'}, ensure_ascii=False))
+        return 2
+    try:
+        with open(argv[1], encoding='utf-8') as f:
+            spec = json.load(f)
+        res = render(spec, argv[2])
+    except SpecError as e:
+        res = {'ok': False, 'error': str(e)}
+    except Exception as e:                                # 引擎自身出错：如实上报，不假装画好了
+        res = {'ok': False, 'error': f'绘图引擎出错：{type(e).__name__}: {e}'}
+    print(json.dumps(res, ensure_ascii=False))
+    return 0 if res.get('ok') else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))