npm - @arcaneorion/dsh-teaching-board - Versions diffs - 0.4.1 → 0.5.1 - Mend

@arcaneorion/dsh-teaching-board 0.4.1 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

package/skills/stage-panel/submode/ml/SKILL.md ADDED Viewed

@@ -0,0 +1,9 @@
+# ml —— ML 可视化面板（面板交互模式·DSH 版）
+可视化模板 `templates/gd.html`（如梯度下降过程）；
+示例参数 `examples/gd.json`（可视化目标与参数样例）。
+## 投递（DSH 原生）
+- 训练/优化过程可视化渲染 → `stage_panel`；
+- 可配合 `stage_choice` 切换视角（损失曲线 / 参数平面 / 批次动画）。

package/skills/stage-panel/submode/ml/examples/gd.json ADDED Viewed

@@ -0,0 +1,7 @@
+{
+  "title": "梯度下降：拟合 y = wx + b",
+  "subtitle": "前端实时计算 · 拖滑块看学习率如何改变收敛路径 · 不走任何 run 通道",
+  "data_points": [[0, 1], [1, 3], [2, 5], [3, 7]],
+  "config": {"lr": 0.05, "iterations": 200, "init_w": 0, "init_b": 0},
+  "target": {"w": 2, "b": 1, "note": "y = 2x + 1 的真值"}
+}

package/skills/stage-panel/submode/ml/templates/gd.html ADDED Viewed

@@ -0,0 +1,217 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>梯度下降可视化</title>
+<style>
+  :root {
+    --bg: #0d1518; --panel: #10191d; --deep: #0a1013;
+    --line: #1f2d33; --text: #cfe3ea; --dim: #6f8a96;
+    --blue: #4fc4cf; --gold: #e8b96b; --pink: #e57373; --green: #6bd098;
+    --mono: ui-monospace, "SF Mono", "JetBrains Mono", Consolas, monospace;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--text);
+    font: 14px/1.5 -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif; }
+  .wrap { padding: 18px 22px 30px; max-width: 1180px; margin: 0 auto; }
+  h1 { font-size: 19px; margin: 0 0 2px; font-weight: 600; }
+  .sub { color: var(--dim); font-size: 13px; margin-bottom: 16px; }
+  .ctrl { display: flex; flex-wrap: wrap; gap: 18px 26px; align-items: end;
+    background: var(--panel); border: 1px solid var(--line); border-radius: 10px;
+    padding: 14px 18px; margin-bottom: 16px; }
+  .ctrl label { display: flex; flex-direction: column; gap: 5px; font-size: 12px; color: var(--dim); }
+  .ctrl .val { color: var(--blue); font-family: var(--mono); font-size: 13px; }
+  .ctrl input[type=range] { width: 170px; accent-color: var(--blue); cursor: pointer; }
+  .ctrl button { background: var(--deep); color: var(--text); border: 1px solid var(--line);
+    border-radius: 7px; padding: 8px 14px; cursor: pointer; font-size: 13px; }
+  .ctrl button:hover { border-color: var(--blue); color: var(--blue); }
+  .ctrl button.on { background: var(--blue); color: #06181b; border-color: var(--blue); }
+  .readouts { display: flex; gap: 22px; font-family: var(--mono); font-size: 13px; }
+  .readouts span b { color: var(--gold); font-weight: 600; }
+  .readouts .warn { color: var(--pink); }
+  .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; }
+  .card { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px 8px; }
+  .card h2 { font-size: 13px; margin: 0 0 8px; color: var(--dim); font-weight: 500; }
+  .card svg, .card canvas { width: 100%; height: 230px; display: block; }
+  .legend { display: flex; gap: 14px; font-size: 11px; color: var(--dim); margin-top: 4px; flex-wrap: wrap; }
+  .legend i { display: inline-block; width: 14px; height: 0; border-top: 2px solid; vertical-align: middle; margin-right: 4px; }
+  @media (max-width: 820px) { .grid { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1 id="title">梯度下降：拟合 y = wx + b</h1>
+  <div class="sub" id="subtitle">前端实时计算 · 拖滑块看学习率如何改变收敛路径 · 不走任何 run 通道</div>
+  <div class="ctrl">
+    <label>学习率 lr <span class="val" id="lrVal">0.050</span>
+      <input type="range" id="lr" min="-3" max="0" step="0.01" value="-1.30"></label>
+    <label>迭代次数 <span class="val" id="itVal">200</span>
+      <input type="range" id="it" min="10" max="500" step="10" value="200"></label>
+    <label>数据噪声 <span class="val" id="nsVal">0.00</span>
+      <input type="range" id="ns" min="0" max="1.5" step="0.05" value="0"></label>
+    <label>初始 w <span class="val" id="iwVal">0.0</span>
+      <input type="range" id="iw" min="-1" max="3" step="0.1" value="0"></label>
+    <label>初始 b <span class="val" id="ibVal">0.0</span>
+      <input type="range" id="ib" min="-1" max="2" step="0.1" value="0"></label>
+    <div style="display:flex;gap:8px">
+      <button id="play">▶ 播放训练</button>
+      <button id="reset">重置</button>
+    </div>
+    <div class="readouts" id="ro"></div>
+  </div>
+  <div class="grid">
+    <div class="card"><h2>① 数据与拟合直线</h2>
+      <svg id="fit" viewBox="0 0 400 230" preserveAspectRatio="none"></svg>
+      <div class="legend"><span><i style="border-color:var(--gold)"></i>数据点</span>
+        <span><i style="border-color:var(--blue)"></i>当前模型</span>
+        <span><i style="border-color:var(--dim);border-top-style:dashed"></i>真值 y=2x+1</span></div></div>
+    <div class="card"><h2>② Loss 等高面 + 梯度下降路径</h2>
+      <canvas id="surf" width="460" height="230"></canvas>
+      <div class="legend"><span>横轴=w · 纵轴=b · 颜色=loss（深=低）· 白线=GD 路径</span></div></div>
+    <div class="card"><h2>③ Loss 曲线（对数纵轴）</h2>
+      <svg id="loss" viewBox="0 0 400 230" preserveAspectRatio="none"></svg>
+      <div class="legend"><span><i style="border-color:var(--pink)"></i>loss</span></div></div>
+    <div class="card"><h2>④ 参数轨迹 w, b</h2>
+      <svg id="param" viewBox="0 0 400 230" preserveAspectRatio="none"></svg>
+      <div class="legend"><span><i style="border-color:var(--blue)"></i>w→2.0</span>
+        <span><i style="border-color:var(--green)"></i>b→1.0</span></div></div>
+  </div>
+</div>
+<script>
+const DATA = __ML_DATA__;
+document.getElementById('title').textContent = DATA.title || '梯度下降：拟合 y = wx + b';
+document.getElementById('subtitle').textContent = DATA.subtitle || '';
+const BASE = DATA.data_points || [[0,1],[1,3],[2,5],[3,7]];
+const TARGET = DATA.target || {w:2.0, b:1.0};
+const W_RANGE = [0, 3.6], B_RANGE = [-0.5, 2.6];
+const $ = id => document.getElementById(id);
+function loss(w,b,d){let s=0;for(const[x,y]of d){const e=w*x+b-y;s+=e*e;}return s/d.length;}
+function train(d,lr,iters,iw,ib){
+  let w=iw,b=ib;const n=d.length;const h=[{w,b,l:loss(w,b,d)}];
+  for(let i=0;i<iters;i++){
+    let dw=0,db=0;
+    for(const[x,y]of d){const e=w*x+b-y;dw+=2*e*x/n;db+=2*e/n;}
+    w-=lr*dw;b-=lr*db;h.push({w,b,l:loss(w,b,d)});
+    if(!isFinite(w)||!isFinite(b)||Math.abs(w)>1e6||Math.abs(b)>1e6)break;
+  }
+  return h;
+}
+function noisy(){const ns=+$('ns').value;return BASE.map(([x,y])=>[x,y+(Math.random()-0.5)*2*ns]);}
+// ---- SVG helpers ----
+const NS='http://www.w3.org/2000/svg';
+function el(t,a){const e=document.createElementNS(NS,t);for(const k in a)e.setAttribute(k,a[k]);return e;}
+function axis(svg,x0,y0,x1,y1){
+  svg.appendChild(el('line',{x1:x0,y1:y0,x2:x1,y2:y0,stroke:'#2a3a42','stroke-width':1}));
+  svg.appendChild(el('line',{x1:x0,y1:y0,x2:x0,y2:y1,stroke:'#2a3a42','stroke-width':1}));
+}
+function fitPlot(hist,step){
+  const svg=$('fit');svg.innerHTML='';const W=400,H=230,M=34;
+  axis(svg,M,H-M,W-8,H-8);
+  const xs=BASE.map(p=>p[0]),ys=BASE.map(p=>p[1]);
+  const xmin=Math.min(...xs)-0.5,xmax=Math.max(...xs)+0.5;
+  const ymin=Math.min(...ys)-1,ymax=Math.max(...ys)+2;
+  const sx=x=>M+(x-xmin)/(xmax-xmin)*(W-M-8);
+  const sy=y=>H-M-(y-ymin)/(ymax-ymin)*(H-M-8);
+  // target line
+  svg.appendChild(el('line',{x1:sx(xmin),y1:sy(TARGET.w*xmin+TARGET.b),x2:sx(xmax),y2:sy(TARGET.w*xmax+TARGET.b),stroke:'#6f8a96','stroke-width':1.5,'stroke-dasharray':'5 4'}));
+  // data
+  for(const[x,y]of BASE)svg.appendChild(el('circle',{cx:sx(x),cy:sy(y),r:4.5,fill:'#e8b96b'}));
+  // current model
+  const s=hist[Math.min(step,hist.length-1)];
+  if(s&&isFinite(s.w)&&isFinite(s.b))
+    svg.appendChild(el('line',{x1:sx(xmin),y1:sy(s.w*xmin+s.b),x2:sx(xmax),y2:sy(s.w*xmax+s.b),stroke:'#4fc4cf','stroke-width':2.4}));
+}
+function lossPlot(hist,step){
+  const svg=$('loss');svg.innerHTML='';const W=400,H=230,M=34;
+  axis(svg,M,H-M,W-8,H-8);
+  const ls=hist.map(h=>Math.max(h.l,1e-9));
+  const lmin=Math.min(...ls),lmax=Math.max(...ls);
+  const lx=i=>M+i/(hist.length-1)*(W-M-8);
+  const ly=l=>H-M-(Math.log(Math.max(l,1e-9))-Math.log(lmin))/(Math.log(lmax)-Math.log(lmin)||0)*(H-M-8);
+  let d='';for(let i=0;i<=Math.min(step,hist.length-1);i++){d+=(i?'L':'M')+lx(i).toFixed(1)+' '+ly(hist[i].l).toFixed(1);}
+  svg.appendChild(el('path',{d,stroke:'#e57373','stroke-width':2,fill:'none'}));
+}
+function paramPlot(hist,step){
+  const svg=$('param');svg.innerHTML='';const W=400,H=230,M=34;
+  axis(svg,M,H-M,W-8,H-8);
+  const ws=hist.map(h=>h.w),bs=hist.map(h=>h.b);
+  const lo=Math.min(...ws,...bs,TARGET.w,TARGET.b)-0.3,hi=Math.max(...ws,...bs,TARGET.w,TARGET.b)+0.3;
+  const sx=i=>M+i/(hist.length-1)*(W-M-8);
+  const sy=v=>H-M-(v-lo)/(hi-lo)*(H-M-8);
+  svg.appendChild(el('line',{x1:M,y1:sy(TARGET.w),x2:W-8,y2:sy(TARGET.w),stroke:'#4fc4cf','stroke-width':1,'stroke-dasharray':'4 4',opacity:.4}));
+  svg.appendChild(el('line',{x1:M,y1:sy(TARGET.b),x2:W-8,y2:sy(TARGET.b),stroke:'#6bd098','stroke-width':1,'stroke-dasharray':'4 4',opacity:.4}));
+  let dw='',db='';
+  for(let i=0;i<=Math.min(step,hist.length-1);i++){dw+=(i?'L':'M')+sx(i).toFixed(1)+' '+sy(hist[i].w).toFixed(1);db+=(i?'L':'M')+sx(i).toFixed(1)+' '+sy(hist[i].b).toFixed(1);}
+  svg.appendChild(el('path',{d:dw,stroke:'#4fc4cf','stroke-width':2,fill:'none'}));
+  svg.appendChild(el('path',{d:db,stroke:'#6bd098','stroke-width':2,fill:'none'}));
+}
+// ---- loss surface heatmap (canvas) + GD path ----
+function surfPlot(hist,step){
+  const cv=$('surf'),ctx=cv.getContext('2d');const W=cv.width,H=cv.height;
+  const gw=64,gh=32;const cw=W/gw,chh=H/gh;
+  const [wa,wb]=W_RANGE,[ba,bb]=B_RANGE;
+  let grid=new Float32Array(gw*gh),lmax=0;
+  for(let j=0;j<gh;j++)for(let i=0;i<gw;i++){
+    const w=wa+(wb-wa)*i/(gw-1),b=ba+(bb-ba)*j/(gh-1);
+    const l=Math.log1p(loss(w,b,BASE));grid[j*gw+i]=l;if(l>lmax)lmax=l;
+  }
+  for(let j=0;j<gh;j++)for(let i=0;i<gw;i++){
+    const t=grid[j*gw+i]/(lmax||1);
+    // dark-teal (low) -> gold (high)
+    const r=Math.round(20+t*220),g=Math.round(40+t*150),b=Math.round(50+t*80);
+    ctx.fillStyle=`rgb(${r},${g},${b})`;ctx.fillRect(i*cw,j*chh,cw+1,chh+1);
+  }
+  // GD path
+  const px=w=>(w-wa)/(wb-wa)*W,py=b=>(b-ba)/(bb-ba)*H;
+  ctx.strokeStyle='#f4f7f9';ctx.lineWidth=1.6;ctx.beginPath();
+  for(let i=0;i<=Math.min(step,hist.length-1);i++){
+    const x=px(hist[i].w),y=py(hist[i].b);i?ctx.lineTo(x,y):ctx.moveTo(x,y);
+  }
+  ctx.stroke();
+  const s=hist[Math.min(step,hist.length-1)];
+  if(s){ctx.fillStyle='#e57373';ctx.beginPath();ctx.arc(px(s.w),py(s.b),4,0,7);ctx.fill();}
+  // frame
+  ctx.strokeStyle='#1f2d33';ctx.lineWidth=1;ctx.strokeRect(0,0,W,H);
+}
+let hist,step=0,timer=0,d;
+function compute(){
+  const lr=Math.pow(10,+$('lr').value);
+  $('lrVal').textContent=lr.toFixed(3);
+  const it=+$('it').value;$('itVal').textContent=it;
+  $('nsVal').textContent=(+$('ns').value).toFixed(2);
+  $('iwVal').textContent=(+$('iw').value).toFixed(1);
+  $('ibVal').textContent=(+$('ib').value).toFixed(1);
+  d=noisy();hist=train(d,lr,it,+$('iw').value,+$('ib').value);
+  step=0;redraw();updateRO();
+}
+function redraw(){fitPlot(hist,step);lossPlot(hist,step);paramPlot(hist,step);surfPlot(hist,step);}
+function updateRO(){
+  const s=hist[step];
+  const diverged=s.l>hist[0].l*1.5||!isFinite(s.l);
+  $('ro').innerHTML=`<span>step <b>${step}</b></span><span>w=<b>${s.w.toFixed(3)}</b></span><span>b=<b>${s.b.toFixed(3)}</b></span><span>loss=<b>${s.l.toFixed(5)}</b></span>${diverged?'<span class="warn">⚠ 发散</span>':''}`;
+}
+$('play').addEventListener('click',function(){
+  if(timer){clearInterval(timer);timer=0;this.textContent='▶ 播放训练';this.classList.remove('on');return;}
+  this.textContent='⏸ 暂停';this.classList.add('on');
+  const it=+$('it').value;const dur=2200;const dt=Math.max(20,dur/it);
+  timer=setInterval(()=>{
+    step=Math.min(step+Math.max(1,Math.floor(it/40)),hist.length-1);
+    redraw();updateRO();
+    if(step>=hist.length-1){clearInterval(timer);timer=0;$('play').textContent='▶ 播放训练';$('play').classList.remove('on');}
+  },dt);
+});
+function applyConfig(){const c=DATA.config||{};if(c.lr!=null)$('lr').value=Math.log10(c.lr);if(c.iterations!=null)$('it').value=c.iterations;if(c.init_w!=null)$('iw').value=c.init_w;if(c.init_b!=null)$('ib').value=c.init_b;$('ns').value=0;}
+$('reset').addEventListener('click',()=>{applyConfig();compute();});
+['lr','it','ns','iw','ib'].forEach(id=>$(id).addEventListener('input',()=>{if(timer){clearInterval(timer);timer=0;$('play').textContent='▶ 播放训练';$('play').classList.remove('on');}compute();}));
+applyConfig();
+compute();
+</script>
+</body>
+</html>

package/skills/stage-panel/submode/quant/SKILL.md ADDED Viewed

@@ -0,0 +1,9 @@
+# quant —— 因子回测仪表盘（面板交互模式·DSH 版）
+模板 `templates/dashboard.html`（因子指标/净值/回撤仪表盘）；
+因子数据导出辅助脚本 `references/export_backtest_data.py`（用 `nix shell nixpkgs#python311 -c python3 ...` 运行）。
+## 投递（DSH 原生）
+1. 回测结果整理成 self-contained dashboard HTML → `stage_panel`；
+2. 需要下钻/切换因子等动作 → `stage_choice`（点选 = 用户消息）。

package/skills/stage-panel/submode/quant/references/export_backtest_data.py ADDED Viewed

@@ -0,0 +1,192 @@
+"""
+回测数据导出脚本 — Quant Panel 参考实现
+------------------------------------
+将此脚本复制到你的量化项目中，适配你的因子计算和回测引擎。
+输出 JSON 文件供 `localweb quant` 命令使用。
+Schema 要求见 localweb/quant/SKILL.md
+"""
+import json
+import numpy as np
+from pathlib import Path
+OUTPUT_DIR = Path(__file__).parent / "output"
+class NpEncoder(json.JSONEncoder):
+    def default(self, obj):
+        if isinstance(obj, (np.integer,)):
+            return int(obj)
+        if isinstance(obj, (np.floating,)):
+            return float(obj)
+        if isinstance(obj, np.ndarray):
+            return obj.tolist()
+        if isinstance(obj, np.bool_):
+            return bool(obj)
+        if isinstance(obj, pd.Timestamp):
+            return obj.isoformat()
+        return super().default(obj)
+def long_short_metrics(long_short: "pd.Series") -> dict:
+    """多空绩效：年化夏普、胜率、最大回撤、累计收益"""
+    import pandas as pd
+    ls = long_short.dropna()
+    if len(ls) == 0:
+        return {"sharpe_annual": 0, "win_rate": 0, "max_drawdown": 0, "total_return": 0}
+    monthly_mean = float(ls.mean())
+    monthly_std = float(ls.std())
+    sharpe = float(monthly_mean / monthly_std * np.sqrt(12)) if monthly_std else 0
+    win_rate = float((ls > 0).mean())
+    cum = (1 + ls).cumprod()
+    peak = cum.cummax()
+    dd = (cum - peak) / peak
+    max_dd = float(dd.min()) if len(dd) else 0
+    total_ret = float(cum.iloc[-1] - 1) if len(cum) else 0
+    return {
+        "sharpe_annual": round(sharpe, 3),
+        "win_rate": round(win_rate, 4),
+        "max_drawdown": round(max_dd, 4),
+        "total_return": round(total_ret, 4),
+    }
+def factor_distribution(factor_df: "pd.DataFrame") -> dict:
+    """因子值分布统计"""
+    import pandas as pd
+    df = factor_df.copy()
+    df["date"] = pd.to_datetime(df["date"])
+    latest_date = df["date"].max()
+    latest = df[df["date"] == latest_date].dropna(subset=["factor_value"])
+    if len(latest) < 20:
+        return {"histogram": [], "stats": {}, "date": str(latest_date.date())}
+    vals = latest["factor_value"].dropna()
+    counts, bins = np.histogram(vals, bins=20)
+    histogram = [
+        {"bin_start": round(float(bins[i]), 4), "bin_end": round(float(bins[i + 1]), 4), "count": int(c)}
+        for i, c in enumerate(counts)
+    ]
+    stats = {
+        "mean": round(float(vals.mean()), 4),
+        "std": round(float(vals.std()), 4),
+        "min": round(float(vals.min()), 4),
+        "p25": round(float(vals.quantile(0.25)), 4),
+        "p50": round(float(vals.quantile(0.50)), 4),
+        "p75": round(float(vals.quantile(0.75)), 4),
+        "max": round(float(vals.max()), 4),
+        "skew": round(float(vals.skew()), 3),
+        "n_stocks": int(len(vals)),
+    }
+    return {"histogram": histogram, "stats": stats, "date": str(latest_date.date())}
+def cross_section_detail(merged: "pd.DataFrame") -> dict:
+    """每组 Top 10 股票明细"""
+    import pandas as pd
+    df = merged.copy()
+    df["date"] = pd.to_datetime(df["date"])
+    latest_date = df["date"].max()
+    latest = df[df["date"] == latest_date].copy()
+    if len(latest) < 20:
+        return {"groups": {}, "date": str(latest_date.date())}
+    latest["quantile"] = pd.qcut(
+        latest["factor_value"].rank(method="first"),
+        q=5, labels=False, duplicates="drop",
+    )
+    groups = {}
+    for q in sorted(latest["quantile"].unique()):
+        sub = latest[latest["quantile"] == q].sort_values("factor_value", ascending=(q == 0))
+        stocks = []
+        for _, row in sub.head(10).iterrows():
+            stocks.append({
+                "symbol": str(row["symbol"]),
+                "factor_value": round(float(row["factor_value"]), 4),
+                "forward_return": round(float(row["forward_return"]), 4),
+            })
+        all_grp = latest[latest["quantile"] == q]
+        groups[f"G{int(q)}"] = {
+            "count": int(len(all_grp)),
+            "factor_mean": round(float(all_grp["factor_value"].mean()), 4),
+            "factor_std": round(float(all_grp["factor_value"].std()), 4),
+            "forward_mean": round(float(all_grp["forward_return"].mean()), 4),
+            "top10": stocks,
+        }
+    return {"groups": groups, "date": str(latest_date.date())}
+def export_one(name: str, label: str, factor_df, backtest_result) -> dict:
+    """
+    组装单个因子的完整回测数据。
+    参数:
+      name: 因子键名 (如 "momentum")
+      label: 因子显示名 (如 "动量(12-1月)")
+      factor_df: 因子 DataFrame [date, symbol, factor_value]
+      backtest_result: run_backtest() 返回的 dict
+    返回: 符合 Quant Panel Schema 的 dict
+    """
+    ic_series = backtest_result["ic_series"]
+    cum_returns = backtest_result["cum_returns"]
+    long_short = backtest_result["long_short"]
+    gr = backtest_result["group_returns"]
+    merged = backtest_result["merged_data"]
+    return {
+        "label": label,
+        "ic_summary": {
+            k: (float(v) if isinstance(v, (np.floating, float)) else v)
+            for k, v in backtest_result["ic_summary"].items()
+        },
+        "ic_series": [
+            {"date": str(d.date()), "ic": float(v)}
+            for d, v in ic_series.items()
+        ],
+        "cum_returns": {
+            f"G{int(q)}": [
+                {"date": str(d.date()), "cum_return": float(v)}
+                for d, v in s.items()
+            ]
+            for q, s in sorted(cum_returns.items())
+        },
+        "long_short": [
+            {"date": str(d.date()), "return": float(v)}
+            for d, v in long_short.items()
+        ],
+        "long_short_metrics": long_short_metrics(long_short),
+        "group_avg_return": {
+            f"G{int(q)}": round(float(gr[gr["group"] == q]["return"].mean()), 6)
+            for q in sorted(gr["group"].unique())
+        },
+        "factor_distribution": factor_distribution(factor_df),
+        "cross_section": cross_section_detail(merged),
+    }
+# ============================================================
+# 使用示例 (根据你的项目修改)
+# ============================================================
+if __name__ == "__main__":
+    import pandas as pd
+    # 替换为你的因子注册表和回测引擎导入
+    # from factors import FACTOR_REGISTRY, calc_factor
+    # from backtest_factor.engine import run_backtest
+    # 示例:
+    # data = {}
+    # for name, (label, func) in FACTOR_REGISTRY.items():
+    #     try:
+    #         factor_df = calc_factor(name)
+    #         result = run_backtest(factor_df, factor_name=label)
+    #         data[name] = export_one(name, label, factor_df, result)
+    #     except Exception as e:
+    #         data[name] = {"label": label, "error": str(e)}
+    #
+    # OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    # out_path = OUTPUT_DIR / "backtest_data.json"
+    # with open(out_path, "w", encoding="utf-8") as f:
+    #     json.dump(data, f, ensure_ascii=False, indent=2, cls=NpEncoder)
+    # print(f"导出完成: {out_path}")
+    print("参考模板 — 请复制到你的项目并修改导入路径和因子注册表。")