@1aboveio/skills 1.0.10 → 1.0.12

package/skills/risk-compliance/portfolio-payment-analysis/scripts/comparison_charts.py

@@ -0,0 +1,425 @@
+"""Standalone, offline week-comparison charts for report renderers.
+
+Append CSS to the report stylesheet and JS to its script. chart() returns an
+HTML fragment and its Markdown equivalent; identifiers should be unique per page.
+"""
+import hashlib
+import html
+import math
+import re
+from decimal import Decimal, InvalidOperation
+
+CSS = """
+.comparison-chart{max-width:100%;min-width:0;margin:24px 0;scroll-margin-top:90px}.comparison-chart h3{margin-bottom:8px}.comparison-chart select{max-width:100%;font:inherit;padding:6px}.comparison-chart select:focus-visible{outline:3px solid #c16613;outline-offset:3px}.comparison-legend{display:flex;flex-wrap:wrap;gap:8px 20px;margin:12px 0}.comparison-legend span{overflow-wrap:anywhere}.comparison-key{display:inline-block;width:12px;height:12px;margin-right:6px}.comparison-previous{background:#727c80}.comparison-current{background:#087b71}.comparison-chart svg{display:block;width:100%;height:auto;max-width:100%}.comparison-chart svg text{font-family:inherit;font-size:13px;fill:#344a51}.comparison-chart .comparison-table{width:100%;table-layout:fixed;border-collapse:collapse}.comparison-chart th,.comparison-chart td{white-space:normal;overflow-wrap:anywhere;text-align:left;padding:8px;border-bottom:1px solid #d8e2df}.comparison-chart details{max-width:100%}.comparison-chart select{min-height:44px}.comparison-chart [data-comparison-plot]{overflow-x:auto}.comparison-chart [data-comparison-plot]:focus-visible{outline:3px solid #c16613}@media(max-width:700px){.comparison-chart svg{min-width:760px;max-width:none}.comparison-chart [data-comparison-plot]::before{content:'横向滚动查看图表';display:block;font-size:12px;color:#536770;margin-bottom:8px}}
+"""
+
+CSS += """
+.comparison-chart details{overflow-x:auto}.comparison-chart[data-layout="time_series_chart"] .comparison-table{min-width:760px}.comparison-compact[data-layout="pie_pair"] .comparison-panel svg{min-width:0;max-width:300px}.comparison-compact [data-comparison-plot]{overflow-x:visible}.comparison-compact svg text{font-size:16px}.comparison-panels{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:16px}.comparison-panel{min-width:0}.comparison-panel h4{margin:4px 0}@media(max-width:700px){.comparison-compact svg{min-width:0;max-width:100%}.comparison-compact [data-comparison-plot]::before{content:none}.comparison-panels{grid-template-columns:1fr}.comparison-compact[data-layout="paired_bars"] [data-comparison-plot]{overflow-x:auto}.comparison-compact[data-layout="paired_bars"] svg{min-width:900px}.comparison-panel{overflow-x:auto}.comparison-compact .comparison-panel svg{min-width:520px;max-width:none}}
+"""
+
+# SVGs are pre-rendered from the same data as the table. Cloning a template
+# avoids parsing source labels as HTML or evaluating data as code in the browser.
+JS = """
+(()=>{let opened=[];
+window.addEventListener('beforeprint',()=>{
+ if(opened.length)return;
+ opened=[...document.querySelectorAll('details:not([open])')];
+ opened.forEach(detail=>detail.open=true);
+});
+window.addEventListener('afterprint',()=>{opened.forEach(detail=>detail.open=false);opened=[];});
+document.querySelectorAll('.comparison-chart').forEach(chart=>{
+ const select=chart.querySelector('select'), target=chart.querySelector('[data-comparison-plot]');
+ if(!select||!target)return;
+ select.addEventListener('change',()=>{
+  const template=chart.querySelectorAll('template')[select.selectedIndex];
+  if(!template)return;
+  target.replaceChildren(template.content.cloneNode(true));
+  chart.dataset.metric=select.options[select.selectedIndex].dataset.key;
+ });
+});})();
+"""
+
+
+def _esc(value):
+    return html.escape(str(value), quote=True)
+
+
+def _md(value):
+    text = html.escape(str(value), quote=False).replace('\n', ' ')
+    for char in ('\\', '*', '_', '[', ']', '`', '#', '|'):
+        text = text.replace(char, '\\' + char)
+    return text
+
+
+def _number(value):
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        number = Decimal(str(value))
+        return number if number.is_finite() else None
+    except (InvalidOperation, ValueError):
+        return None
+
+
+def _display(value, fmt):
+    number = _number(value)
+    if number is None:
+        return ''
+    if fmt == 'percent':
+        return f'{number * 100:,.2f}%'
+    if fmt == 'usd':
+        return f'USD {number:,.2f}'
+    return f'{number:,.0f}'
+
+
+def _value(category, series, metric):
+    return category.get('values', {}).get(series['key'], {}).get(metric['key'])
+
+
+def _svg(block, metric):
+    categories, series = block['categories'], block['series']
+    height = 75 + len(categories) * 48
+    left, right = 230, 640
+    values = [_number(_value(c, s, metric)) for c in categories for s in series]
+    maximum = Decimal(1) if metric['format'] == 'percent' else max([v for v in values if v is not None and v > 0] or [Decimal(1)])
+    title = block['title'] + ' — ' + metric['label']
+    out = [f'<svg viewBox="0 0 800 {height}" role="img" aria-label="{_esc(title)}"><title>{_esc(title)}</title>']
+    for i in range(5):
+        x = left + (right-left)*i/4
+        label = f'{i*25}%' if metric['format'] == 'percent' else _display(maximum*Decimal(i)/4, metric['format'])
+        out.append(f'<line x1="{x}" y1="25" x2="{x}" y2="{height-12}" stroke="#e2eae6"/><text x="{x}" y="18" text-anchor="middle">{_esc(label)}</text>')
+    for row, category in enumerate(categories):
+        y = 50 + row*48
+        label = str(category['label'])
+        short = label if len(label) <= 24 else label[:23]+'…'
+        out.append(f'<text x="8" y="{y+8}"><title>{_esc(label)}</title>{_esc(short)}</text>')
+        for index, s in enumerate(series):
+            value = _number(_value(category, s, metric))
+            display = _display(_value(category, s, metric), metric['format'])
+            color = '#727c80' if s['key'] == 'previous' else '#087b71'
+            yy = y + index*19
+            tooltip = _esc(f'{label} — {s["label"]}: {display}')
+            out.append(f'<text x="790" y="{yy+5}" text-anchor="end" style="fill:{color}">{_esc(display)}</text>')
+            if value is None:
+                continue
+            ratio = max(Decimal(0), min(Decimal(1), value/maximum))
+            x = left + (right-left)*float(ratio)
+            if metric['format'] == 'percent':
+                out.append(f'<circle cx="{x:.2f}" cy="{yy}" r="6" fill="{color}"><title>{tooltip}</title></circle>')
+            elif value == 0:
+                out.append(f'<text x="{left+5}" y="{yy+5}"><title>{tooltip}</title>0</text>')
+            else:
+                out.append(f'<rect x="{left}" y="{yy-6}" width="{x-left:.2f}" height="12" fill="{color}"><title>{tooltip}</title></rect>')
+    out.append('</svg>')
+    return ''.join(out)
+
+
+_BANDS = ('[0,25)', '[25,50)', '[50,100)', '[100,200)', '[200,500)', '[500,+inf)')
+
+
+def _axis_label(value, fmt):
+    if fmt == 'percent':
+        scaled=value*100
+        return f'{scaled:.0f}%' if scaled==scaled.to_integral_value() else f'{scaled:.2f}%'
+    if abs(value) >= 1000000:
+        return f'{value / Decimal(1000000):.1f}m'
+    if abs(value) >= 1000:
+        return f'{value / Decimal(1000):.1f}k'
+    return f'{value:,.0f}'
+
+
+def _compact_svg(block, metric, categories, series, maximum=None):
+    values = [_number(_value(c, s, metric)) for c in categories for s in series]
+    if maximum is None:
+        maximum = Decimal(1) if metric['format'] == 'percent' else max([v for v in values if v is not None and v > 0] or [Decimal(1)])
+    paired = len(series) == 2
+    width = 1000 if paired else 600
+    pitch = 34 if paired else 32
+    height = 50 + len(categories) * pitch
+    left, right = (240, 840) if paired else (185, 470)
+    title = block['title'] + ' — ' + metric['label'] + (' — ' + series[0]['label'] if len(series) == 1 else '')
+    out = [f'<svg viewBox="0 0 {width} {height}" role="img" aria-label="{_esc(title)}"><title>{_esc(title)}</title>']
+    for i in range(5):
+        x = left + (right-left)*i/4
+        label = _axis_label(maximum*Decimal(i)/4, metric['format'])
+        out.append(f'<line x1="{x}" y1="25" x2="{x}" y2="{height-5}" stroke="#e2eae6"/><text x="{x}" y="18" text-anchor="middle">{_esc(label)}</text>')
+    for row, category in enumerate(categories):
+        y = 43 + row * pitch
+        label = str(category['label'])
+        limit = 28 if paired else 18
+        short = label if len(label) <= limit else label[:limit-1] + '…'
+        out.append(f'<text x="4" y="{y+4}"><title>{_esc(label)}</title>{_esc(short)}</text>')
+        for index, s in enumerate(series):
+            raw = _value(category, s, metric)
+            value, display = _number(raw), _display(raw, metric['format'])
+            color = '#727c80' if s['key'] == 'previous' else '#087b71'
+            yy = y + index * 14
+            tooltip = _esc(f'{label} — {s["label"]}: {display}')
+            out.append(f'<text x="{width-5}" y="{yy+4}" text-anchor="end" style="fill:{color};font-size:12px"><title>{tooltip}</title>{_esc(display)}</text>')
+            if value is None or value == 0:
+                continue
+            else:
+                ratio = max(Decimal(0), min(Decimal(1), value/maximum))
+                out.append(f'<rect x="{left}" y="{yy-5}" width="{(right-left)*float(ratio):.2f}" height="9" fill="{color}"><title>{tooltip}</title></rect>')
+    out.append('</svg>')
+    return ''.join(out)
+
+
+def _histogram_svg(block, metric, categories, series, maximum):
+    title = block['title'] + ' — ' + metric['label'] + ' — ' + series['label']
+    out = [f'<svg viewBox="0 0 600 270" role="img" aria-label="{_esc(title)}"><title>{_esc(title)}</title>']
+    for i in range(5):
+        y = 210 - i * 45
+        label = _axis_label(maximum * Decimal(i) / 4, metric['format'])
+        out.append(f'<line x1="85" y1="{y}" x2="590" y2="{y}" stroke="#e2eae6"/><text x="80" y="{y+4}" text-anchor="end">{_esc(label)}</text>')
+    color = '#727c80' if series['key'] == 'previous' else '#087b71'
+    for i, category in enumerate(categories):
+        x = 85 + i * 84
+        raw = _value(category, series, metric)
+        value, display = _number(raw), _display(raw, metric['format'])
+        tooltip = _esc(f'{category["label"]} — {series["label"]}: {display}')
+        band_label = ('0–<25','25–<50','50–<100','100–<200','200–<500','500+')[i]
+        out.append(f'<text x="{x+42}" y="232" text-anchor="middle" style="font-size:14px">{_esc(band_label)}</text>')
+        if value is None or value == 0:
+            out.append(f'<text x="{x+42}" y="203" text-anchor="middle"><title>{tooltip}</title>{_esc(display)}</text>')
+        else:
+            bar_height = 180 * float(max(Decimal(0), min(Decimal(1), value/maximum)))
+            out.append(f'<rect x="{x}" y="{210-bar_height:.2f}" width="84" height="{bar_height:.2f}" fill="{color}" stroke="white"><title>{tooltip}</title></rect>')
+    return ''.join(out) + '</svg>'
+
+
+def _compact_plot(block, metric, layout):
+    categories, series = block['categories'], block['series']
+    if layout == 'paired_bars':
+        return _compact_svg(block, metric, categories, series)
+    if layout == 'histogram_pair':
+        lookup = {c['label']: c for c in categories if c['label'] in _BANDS}
+        plotted = [lookup.get(label, {'label': label, 'values': {}}) for label in _BANDS]
+        extra = [c for c in categories if c['label'] not in _BANDS]
+    else:
+        plotted, extra = categories, []
+    values = [_number(_value(c, s, metric)) for c in plotted for s in series]
+    maximum = Decimal(1) if metric['format'] == 'percent' else max([v for v in values if v is not None and v > 0] or [Decimal(1)])
+    panels = []
+    for s in series:
+        svg = _histogram_svg(block, metric, plotted, s, maximum) if layout == 'histogram_pair' else _compact_svg(block, metric, plotted, [s], maximum=maximum)
+        panels.append('<section class="comparison-panel"><h4><i aria-hidden="true" class="comparison-key comparison-'+_esc(s['key'])+'"></i>'+_esc(s['label'])+'</h4>'+svg+'</section>')
+    note = '<p>金额区间宽度不相等；以等宽类别显示，500+ 无上限，不表示密度或连续区间宽度。</p>' if layout == 'histogram_pair' else ''
+    if extra:
+        note += '<p>区间外或未知（不作为金额区间绘制）：' + '; '.join(_esc(c['label']) + ' — ' + ', '.join(_esc(s['label']) + ': ' + _esc(_display(_value(c, s, metric), metric['format'])) for s in series) for c in extra) + '</p>'
+    return note + '<div class="comparison-panels">' + ''.join(panels) + '</div>'
+
+
+_PALETTE = ('#087b71', '#727c80', '#c16613', '#426b94', '#a05178', '#759b47', '#8c6954', '#6b61a8')
+_SERIES_COLORS = {'visa_predispute':'#087b71','visa_dispute':'#426b94','mastercard_chargeback':'#c16613','visa':'#426b94','mastercard':'#c16613','mastercard_efm':'#c16613','vamp_ratio':'#6b61a8'}
+
+
+def _pie_colors(categories):
+    known={'None':'#727c80','3DS attempted':'#c16613','3DS validated':'#087b71'}
+    used={known[c['label']] for c in categories if c['label'] in known}
+    colors=[]
+    for i,category in enumerate(categories):
+        color=known.get(category['label'])
+        if color is None:
+            color=next((c for c in _PALETTE if c not in used),_PALETTE[i%len(_PALETTE)])
+        used.add(color)
+        colors.append(color)
+    return colors
+
+
+def _pie_plot(block, metric):
+    categories = block['categories']
+    colors = _pie_colors(categories)
+    legend = '<div class="comparison-legend">' + ''.join(
+        f'<span><i class="comparison-key" aria-hidden="true" style="background:{colors[i]}"></i>{_esc(c["label"])}</span>'
+        for i, c in enumerate(categories)) + '</div>'
+    panels = []
+    for series in block['series']:
+        values = [_number(_value(c, series, metric)) for c in categories]
+        known = [v for v in values if v is not None]
+        heading = '<h4>' + _esc(series['label']) + '</h4>'
+        if not known or any(v is None or v < 0 for v in values):
+            panels.append('<section class="comparison-panel">' + heading + '<p>数据不可用</p></section>')
+            continue
+        total = sum(known, Decimal(0))
+        if total == 0:
+            panels.append('<section class="comparison-panel">' + heading + '<p>合计为 0</p></section>')
+            continue
+        title = block['title'] + ' — ' + metric['label'] + ' — ' + series['label']
+        svg = [f'<svg viewBox="0 0 300 300" role="img" aria-label="{_esc(title)}"><title>{_esc(title)}</title>']
+        angle = -math.pi / 2
+        for i, (category, value) in enumerate(zip(categories, values)):
+            if value == 0:
+                continue
+            sweep = float(value / total) * 2 * math.pi
+            color = colors[i]
+            tooltip = _esc(f'{category["label"]} — {series["label"]}: {_display(value, metric["format"])}')
+            if value == total:
+                svg.append(f'<circle cx="150" cy="150" r="125" fill="{color}"><title>{tooltip}</title></circle>')
+            else:
+                x1, y1 = 150 + 125 * math.cos(angle), 150 + 125 * math.sin(angle)
+                x2, y2 = 150 + 125 * math.cos(angle + sweep), 150 + 125 * math.sin(angle + sweep)
+                svg.append(f'<path d="M 150 150 L {x1:.6f} {y1:.6f} A 125 125 0 {int(sweep > math.pi)} 1 {x2:.6f} {y2:.6f} Z" fill="{color}"><title>{tooltip}</title></path>')
+            angle += sweep
+        svg.append('</svg>')
+        amounts = '<div class="comparison-legend">' + ''.join(
+            f'<span><i class="comparison-key" aria-hidden="true" style="background:{colors[i]}"></i>{_esc(c["label"])}: {_esc(_display(v, metric["format"]))}</span>'
+            for i, (c, v) in enumerate(zip(categories, values))) + '</div>'
+        panels.append('<section class="comparison-panel">' + heading + ''.join(svg) + amounts + '</section>')
+    return legend + '<div class="comparison-panels">' + ''.join(panels) + '</div>'
+
+
+def _time_series_content(block):
+    unit, series, points = block['unit'], block['series'], block['points']
+    if unit not in ('count', 'usd', 'percent'):
+        raise ValueError('unsupported time series unit')
+    keys = [s['key'] for s in series]
+    if len(set(keys)) != len(keys):
+        raise ValueError('duplicate time series key')
+    colors = []
+    for i, s in enumerate(series):
+        color = s.get('color', _SERIES_COLORS.get(s['key'], _PALETTE[i % len(_PALETTE)]))
+        if not isinstance(color, str) or not re.fullmatch(r'#[0-9a-fA-F]{6}', color):
+            raise ValueError('time series color must be a six-digit hex color')
+        colors.append(color)
+    values = [[_number(p.get('values', {}).get(s['key'])) for p in points] for s in series]
+    observed = [v for row in values for v in row if v is not None]
+    low = min([Decimal(0)] + observed)
+    high = max([Decimal(0)] + observed)
+    if unit == 'count':
+        low,high=Decimal(math.floor(low/4))*4,Decimal(math.ceil(high/4))*4
+    if high == low:
+        high = low + Decimal(4 if unit=='count' else 1)
+    width = max(800, 80 * len(points) + 100)
+    left, right, top, bottom = 85, width - 30, 30, 240
+    def x(i):
+        return (left + right) / 2 if len(points) == 1 else left + (right-left)*i/max(1, len(points)-1)
+    def y(value):
+        return bottom - float((value-low)/(high-low)) * (bottom-top)
+    title = _esc(block['title'])
+    svg = [f'<svg viewBox="0 0 {width} 290" role="img" aria-label="{title}"><title>{title}</title>']
+    for i in range(5):
+        tick = low + (high-low)*Decimal(i)/4
+        yy = bottom - (bottom-top)*i/4
+        svg.append(f'<line x1="{left}" y1="{yy}" x2="{right}" y2="{yy}" stroke="#e2eae6"/><text x="{left-8}" y="{yy+4}" text-anchor="end">{_esc(_axis_label(tick, unit))}</text>')
+    for i, p in enumerate(points):
+        axis_label = str(p['label']) + ('*' if p.get('partial') else '')
+        svg.append(f'<text x="{x(i):.2f}" y="265" text-anchor="middle">{_esc(axis_label)}</text>')
+    for s, color, row in zip(series, colors, values):
+        previous = None
+        for i, value in enumerate(row):
+            if value is None:
+                previous = None
+                continue
+            xx, yy = x(i), y(value)
+            if previous is not None:
+                svg.append(f'<line x1="{previous[0]:.2f}" y1="{previous[1]:.2f}" x2="{xx:.2f}" y2="{yy:.2f}" stroke="{color}" stroke-width="2"/>')
+            point = points[i]
+            dates = ' – '.join(str(point[k]) for k in ('start', 'end') if point.get(k))
+            tooltip = f'{point["label"]}' + (f' ({dates})' if dates else '') + f' — {s["label"]}: {_display(value, unit)}'
+            if block.get('date_basis'):
+                tooltip += ' · ' + block['date_basis']
+            coverage=point.get('coverage')
+            if isinstance(coverage,dict) and 'valid_file_dates' in coverage:
+                tooltip += ' · 有效文件日期 '+str(coverage['valid_file_dates'])
+            svg.append(f'<circle cx="{xx:.2f}" cy="{yy:.2f}" r="4" fill="{color}"><title>{_esc(tooltip)}</title></circle>')
+            previous = (xx, yy)
+    svg.append('</svg>')
+    legend = ''.join(f'<span><i class="comparison-key" aria-hidden="true" style="background:{color}"></i>{_esc(s["label"])}</span>' for s, color in zip(series, colors))
+    headers = ['指标'] + [p['label'] for p in points]
+    rows=[]
+    if any(p.get('partial') for p in points):
+        rows.append(['期间范围（含首尾）'] + [
+            '不完整：' + ' 至 '.join(str(p.get(k) or '') for k in ('start', 'end')) if p.get('partial') else ''
+            for p in points])
+    for s in series:
+        rows.append([s['label']]+[_display(p.get('values',{}).get(s['key']),unit) for p in points])
+        if unit=='percent' and any(s['key'] in p.get('rate_details',{}) for p in points):
+            details=[p.get('rate_details',{}).get(s['key'],{}) for p in points]
+            for key,label in [('numerator','分子笔数'),('denominator','分母笔数')]:
+                rows.append([s['label']+' · '+label]+[_display(d.get(key),'count') for d in details])
+            rows.append([s['label']+' · 分母月份']+[str(d.get('denominator_start') or '')[:7] for d in details])
+    table = '<table class="comparison-table"><thead><tr>' + ''.join('<th scope="col">' + _esc(h) + '</th>' for h in headers) + '</tr></thead><tbody>'
+    table += ''.join('<tr><th scope="row">' + _esc(row[0]) + '</th>' + ''.join('<td>' + _esc(v) + '</td>' for v in row[1:]) + '</tr>' for row in rows) + '</tbody></table>'
+    note = '<p>' + _esc(block['status_note']) + '</p>' if block.get('status_note') else ''
+    if any(p.get('partial') for p in points):
+        note += '<p>* 不完整期间；具体日期见数据明细。</p>'
+    content = note + f'<div class="comparison-legend">{legend}</div>' + ''.join(svg) + '<details><summary>查看数据明细</summary>' + table + '</details>'
+    markdown = ''
+    if block.get('status_note'):
+        markdown += _md(block['status_note']) + '\n\n'
+    markdown += '| ' + ' | '.join(map(_md, headers)) + ' |\n| ' + ' | '.join('---' for _ in headers) + ' |\n'
+    markdown += '\n'.join('| ' + ' | '.join(map(_md, row)) + ' |' for row in rows)
+    return content, markdown, (note, legend, ''.join(svg), table)
+
+
+def _time_series_chart(block, identifier):
+    prefix = 'comparison-' + hashlib.sha256(str(identifier).encode('utf-8')).hexdigest()[:20]
+    title = _esc(block['title'])
+    if 'views' not in block:
+        _, md, (note, legend, svg, table) = _time_series_content(block)
+        return (f'<div class="comparison-chart" id="{prefix}" data-layout="time_series_chart"><h3>{title}</h3>{note}'
+                f'<div class="comparison-legend">{legend}</div><div data-comparison-plot tabindex="0">{svg}</div>'
+                f'<details><summary>查看数据明细</summary>{table}</details></div>',
+                '### ' + _md(block['title']) + '\n\n' + md)
+
+    views = block['views']
+    if not isinstance(views, list) or not views:
+        raise ValueError('time series views must be a non-empty list')
+    keys = [view.get('key') for view in views]
+    if any(not isinstance(key, str) or not re.fullmatch(r'[A-Za-z][A-Za-z0-9_-]*', key) for key in keys) or len(set(keys)) != len(keys):
+        raise ValueError('invalid or duplicate time series view key')
+    if block.get('default_view') not in keys:
+        raise ValueError('default time series view is not present')
+    selected = keys.index(block['default_view'])
+    rendered = [_time_series_content({**block, **view}) for view in views]
+    options = ''.join(f'<option value="{i}" data-key="{_esc(view["key"])}"' +
+                      (' selected' if i == selected else '') + f'>{_esc(view["label"])}</option>'
+                      for i, view in enumerate(views))
+    result = f'<div class="comparison-chart" id="{prefix}" data-layout="time_series_chart" data-metric="{_esc(keys[selected])}"><h3>{title}</h3>'
+    result += f'<label for="{prefix}-metric">选择指标</label> <select id="{prefix}-metric" aria-controls="{prefix}-plot">{options}</select>'
+    result += f'<div id="{prefix}-plot" data-comparison-plot tabindex="0">{rendered[selected][0]}</div>'
+    result += ''.join('<template>' + content + '</template>' for content, _, _ in rendered) + '</div>'
+    markdown = '### ' + _md(block['title']) + '\n\n' + '\n\n'.join(
+        '#### ' + _md(view['label']) + '\n\n' + md for view, (_, md, _) in zip(views, rendered))
+    return result, markdown
+
+
+def chart(block, identifier):
+    """Return (HTML, Markdown) for a comparison_chart or time_series_chart block."""
+    if block.get('type') == 'time_series_chart':
+        return _time_series_chart(block, identifier)
+    metrics, series = block['metrics'], block['series']
+    if not metrics or len(series) != 2 or {s['key'] for s in series} != {'previous', 'current'}:
+        raise ValueError('comparison chart requires metrics and previous/current series')
+    if any(m['format'] not in ('count', 'percent', 'usd') for m in metrics):
+        raise ValueError('unsupported comparison metric format')
+    layout = block.get('layout')
+    if layout not in (None, 'paired_bars', 'histogram_pair', 'bars_pair', 'pie_pair'):
+        raise ValueError('unsupported comparison layout')
+    if layout in ('histogram_pair', 'pie_pair') and any(m['format'] == 'percent' for m in metrics):
+        raise ValueError('histogram and pie metrics must be counts or amounts')
+    selected = next((i for i, m in enumerate(metrics) if m['key'] == block['default_metric']), None)
+    if selected is None:
+        raise ValueError('default metric is not present')
+    prefix = 'comparison-' + hashlib.sha256(str(identifier).encode('utf-8')).hexdigest()[:20]
+    svgs = [_pie_plot(block, metric) if layout == 'pie_pair' else _compact_plot(block, metric, layout) if layout else _svg(block, metric) for metric in metrics]
+    options = ''.join(f'<option value="{i}" data-key="{_esc(m["key"])}"'+(' selected' if i == selected else '')+f'>{_esc(m["label"])}</option>' for i, m in enumerate(metrics))
+    legend = ''.join(f'<span><i aria-hidden="true" class="comparison-key comparison-{_esc(s["key"])}"></i>{_esc(s["label"])}</span>' for s in series)
+    if layout in ('histogram_pair','bars_pair','pie_pair'):legend=''
+    description = '<p>'+_esc(block['description'])+'</p>' if block.get('description') else ''
+    headers = ['分类', '指标'] + [s['label'] for s in series]
+    rows = [[c['label'], m['label']] + [_display(_value(c, s, m), m['format']) for s in series] for c in block['categories'] for m in metrics]
+    table = '<table class="comparison-table"><thead><tr>'+''.join('<th scope="col">'+_esc(h)+'</th>' for h in headers)+'</tr></thead><tbody>'
+    table += ''.join('<tr><th scope="row">'+_esc(row[0])+'</th>'+''.join('<td>'+_esc(v)+'</td>' for v in row[1:])+'</tr>' for row in rows)+'</tbody></table>'
+    compact_class = ' comparison-compact' if layout else ''
+    result = f'<div class="comparison-chart{compact_class}" id="{prefix}" data-layout="{_esc(layout or "default")}" data-metric="{_esc(metrics[selected]["key"])}"><h3>{_esc(block["title"])}</h3>{description}'
+    result += f'<label for="{prefix}-metric">选择指标</label> <select id="{prefix}-metric" aria-controls="{prefix}-plot">{options}</select><div class="comparison-legend">{legend}</div>'
+    result += f'<div id="{prefix}-plot" data-comparison-plot tabindex="0" aria-label="可横向滚动的对比图">{svgs[selected]}</div>' + ''.join('<template>'+svg+'</template>' for svg in svgs)
+    result += '<details><summary>查看数据明细</summary>'+table+'</details></div>'
+    markdown = '### '+_md(block['title'])+'\n\n'
+    if block.get('description'):
+        markdown += _md(block['description'])+'\n\n'
+    markdown += '| '+' | '.join(map(_md, headers))+' |\n| '+' | '.join('---' for _ in headers)+' |\n'
+    markdown += '\n'.join('| '+' | '.join(map(_md, row))+' |' for row in rows)
+    return result, markdown

package/skills/risk-compliance/portfolio-payment-analysis/scripts/csv_export.py

@@ -0,0 +1,52 @@
+"""Spreadsheet-safe CSV writers.
+
+Text beginning with a formula marker or whitespace gets a leading apostrophe.
+The apostrophe is part of the CSV value; JSON and source data remain unchanged.
+Numeric strings are only exempted in explicitly designated numeric columns, after
+strict validation. Never designate identifiers or other source text as numeric.
+"""
+import csv
+import re
+
+_NUMERIC = re.compile(r'-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?\Z')
+
+
+def _cell(value, numeric=False):
+    if isinstance(value, str):
+        if numeric and _NUMERIC.fullmatch(value):
+            return value
+        if value and (value[0] in '=+-@' or value[0].isspace()):
+            return "'" + value
+    return value
+
+
+class _SafeWriter:
+    def __init__(self, writer, numeric_columns, dictionary=False):
+        self._writer = writer
+        self._numeric_columns = frozenset(numeric_columns)
+        self._dictionary = dictionary
+
+    def writerow(self, row):
+        if self._dictionary:
+            return self._writer.writerow({key: _cell(value, key in self._numeric_columns)
+                                          for key, value in row.items()})
+        return self._writer.writerow([_cell(value, index in self._numeric_columns)
+                                      for index, value in enumerate(row)])
+
+    def writerows(self, rows):
+        for row in rows:
+            self.writerow(row)
+
+    def writeheader(self):
+        # DictWriter's header contains field names, which are text, not numbers.
+        return self._writer.writerow({key: _cell(key) for key in self._writer.fieldnames})
+
+
+def safe_writer(handle, *, numeric_columns=(), **kwargs):
+    """Like csv.writer; numeric_columns contains zero-based numeric column indices."""
+    return _SafeWriter(csv.writer(handle, **kwargs), numeric_columns)
+
+
+def safe_dict_writer(handle, fieldnames, *, numeric_columns=(), **kwargs):
+    """Like csv.DictWriter; numeric_columns contains numeric field names."""
+    return _SafeWriter(csv.DictWriter(handle, fieldnames, **kwargs), numeric_columns, True)