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

@arcaneorion/dsh-teaching-board 0.4.1 → 0.5.0

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 (36) hide show

package/skills/stage-panel/submode/quant/templates/dashboard.html ADDED Viewed

@@ -0,0 +1,381 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>因子回测仪表盘 · factor-lab</title>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
+<style>
+  :root {
+    /* 呼应 visual-style.md：蓝灰科幻底 + 高对比黄 + 硬黑描边 + 小圆角 */
+    --bg: #0f2233; --surface: #16334a; --surface2: #1b3d57;
+    --border: #07111b; --text: #dbeaf5; --text2: #93b3c9;
+    --accent: #ffd43b; --green: #7ee787; --red: #ff8a8a; --orange: #ffb454;
+    --line: #07111b;
+  }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    background: var(--bg); color: var(--text); min-height: 100vh;
+  }
+  .topbar {
+    background: var(--surface); border-bottom: 2px solid var(--border);
+    padding: 14px 24px; display: flex; align-items: center; gap: 16px;
+    position: sticky; top: 0; z-index: 100;
+  }
+  .topbar .logo { font-size: 18px; font-weight: 700; color: var(--accent); }
+  .topbar .sep { color: var(--text2); }
+  .topbar .sub { color: var(--text2); font-size: 13px; }
+  .tabs { display: flex; padding: 0 24px; background: var(--surface); border-bottom: 2px solid var(--border); overflow-x: auto; }
+  .tab { padding: 12px 20px; cursor: pointer; color: var(--text2); border-bottom: 2px solid transparent; font-size: 14px; white-space: nowrap; transition: all 0.2s; }
+  .tab:hover { color: var(--text); }
+  .tab.active { color: var(--accent); border-bottom-color: var(--accent); }
+  .tab.error { color: var(--red); opacity: 0.5; }
+  .tab.error.active { opacity: 1; border-bottom-color: var(--red); color: var(--red); }
+  .main { padding: 20px 24px; max-width: 1800px; margin: 0 auto; }
+  .section-title { font-size: 12px; font-weight: 600; color: var(--text2); text-transform: uppercase; letter-spacing: 1px; margin-bottom: 10px; margin-top: 24px; }
+  .metrics { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 10px; margin-bottom: 8px; }
+  .metric-card { background: var(--surface); border: 2px solid var(--border); border-radius: 6px; padding: 12px 14px; text-align: center; }
+  .metric-card .label { font-size: 10px; color: var(--text2); text-transform: uppercase; margin-bottom: 4px; }
+  .metric-card .value { font-size: 22px; font-weight: 700; font-variant-numeric: tabular-nums; }
+  .metric-card .value.positive { color: var(--green); }
+  .metric-card .value.negative { color: var(--red); }
+  .metric-card .value.neutral { color: var(--text); }
+  .charts { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; margin-bottom: 24px; }
+  .chart-box { background: var(--surface); border: 2px solid var(--border); border-radius: 6px; padding: 14px; }
+  .chart-box.full { grid-column: 1 / -1; }
+  .chart-box .title { font-size: 12px; font-weight: 600; color: var(--text2); margin-bottom: 10px; text-transform: uppercase; letter-spacing: 0.5px; }
+  .chart-box .canvas-wrap { position: relative; width: 100%; height: 260px; }
+  .chart-box .canvas-wrap canvas { width: 100% !important; height: 100% !important; }
+  .empty-state { display: flex; flex-direction: column; align-items: center; justify-content: center; padding: 60px 20px; color: var(--text2); text-align: center; }
+  .empty-state .icon { font-size: 48px; margin-bottom: 12px; }
+  .empty-state .msg { font-size: 15px; margin-bottom: 6px; }
+  /* 截面明细表 */
+  .xsec-box { background: var(--surface); border: 2px solid var(--border); border-radius: 6px; padding: 14px; }
+  .xsec-box .title { font-size: 12px; font-weight: 600; color: var(--text2); margin-bottom: 10px; text-transform: uppercase; letter-spacing: 0.5px; }
+  .xsec-tabs { display: flex; gap: 4px; margin-bottom: 12px; flex-wrap: wrap; }
+  .xsec-tab { padding: 6px 14px; border-radius: 4px; cursor: pointer; font-size: 12px; background: var(--surface2); color: var(--text2); border: 2px solid var(--border); transition: all 0.15s; }
+  .xsec-tab:hover { color: var(--text); }
+  .xsec-tab.active { background: var(--accent); color: var(--line); border-color: var(--accent); font-weight: 700; }
+  .xsec-tab.stats { font-size: 11px; color: var(--text2); padding: 6px 8px; }
+  table.xsec { width: 100%; border-collapse: collapse; font-size: 12px; font-variant-numeric: tabular-nums; }
+  table.xsec th { text-align: left; padding: 6px 10px; color: var(--text2); font-weight: 500; border-bottom: 2px solid var(--border); font-size: 10px; text-transform: uppercase; }
+  table.xsec td { padding: 5px 10px; border-bottom: 1px solid rgba(147,179,201,0.25); }
+  table.xsec tr:hover td { background: var(--surface2); }
+  table.xsec .sym { color: var(--accent); font-weight: 600; }
+  table.xsec .pos { color: var(--green); }
+  table.xsec .neg { color: var(--red); }
+  @media (max-width: 900px) { .charts { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<div class="topbar">
+  <span class="logo">factor-lab</span>
+  <span class="sep">/</span>
+  <span class="sub">单因子回测仪表盘</span>
+</div>
+<div class="tabs" id="tabs"></div>
+<div class="main">
+  <div class="section-title">📊 IC 分析</div>
+  <div class="metrics" id="icMetrics"></div>
+  <div class="section-title" style="margin-top:14px;">⚡ 多空绩效</div>
+  <div class="metrics" id="lsMetrics"></div>
+  <div class="section-title" style="margin-top:14px;">📈 图表</div>
+  <div class="charts">
+    <div class="chart-box"><div class="title">📈 Rank IC 时序</div><div class="canvas-wrap"><canvas id="icChart"></canvas></div></div>
+    <div class="chart-box"><div class="title">📊 IC 分布直方图</div><div class="canvas-wrap"><canvas id="icHist"></canvas></div></div>
+    <div class="chart-box"><div class="title">📉 分层累计收益</div><div class="canvas-wrap"><canvas id="cumChart"></canvas></div></div>
+    <div class="chart-box"><div class="title">⚡ 多空累计收益</div><div class="canvas-wrap"><canvas id="lsChart"></canvas></div></div>
+    <div class="chart-box"><div class="title">📋 分组月均收益</div><div class="canvas-wrap"><canvas id="barChart"></canvas></div></div>
+    <div class="chart-box"><div class="title">📅 每月多空收益</div><div class="canvas-wrap"><canvas id="lsMonthly"></canvas></div></div>
+    <div class="chart-box"><div class="title">📐 因子值分布 (最新截面)</div><div class="canvas-wrap"><canvas id="distChart"></canvas></div></div>
+    <div class="chart-box"><div class="title">🏆 全因子 ICIR 对比</div><div class="canvas-wrap"><canvas id="compareChart"></canvas></div></div>
+  </div>
+  <div class="xsec-box" id="xsecBox">
+    <div class="title">📋 截面明细 — 各组 Top 10 股票</div>
+    <div class="xsec-tabs" id="xsecTabs"></div>
+    <div id="xsecStats" style="font-size:11px;color:var(--text2);margin-bottom:8px;"></div>
+    <table class="xsec" id="xsecTable"></table>
+  </div>
+</div>
+<script>
+// ======================== 数据内嵌 ========================
+const allData = __BACKTEST_DATA__;
+let activeFactor = null;
+let selectedGroup = 'G0';
+function initTabs() {
+  const tabsEl = document.getElementById('tabs');
+  const factors = Object.entries(allData).filter(([k]) => !k.startsWith('_'));
+  if (factors.length === 0) {
+    tabsEl.innerHTML = '<div class="tab error">暂无数据</div>';
+    showEmpty('没有可用的回测数据。请运行: uv run --project .. python export_backtest_data.py');
+    return;
+  }
+  factors.forEach(([key, info]) => {
+    const tab = document.createElement('div');
+    tab.className = 'tab';
+    if (info.error) tab.className += ' error';
+    tab.textContent = info.label || key;
+    tab.dataset.key = key;
+    tab.addEventListener('click', () => selectFactor(key));
+    tabsEl.appendChild(tab);
+  });
+  const firstOk = factors.find(([k, v]) => !v.error);
+  selectFactor(firstOk ? firstOk[0] : factors[0][0]);
+}
+function selectFactor(key) {
+  activeFactor = key;
+  document.querySelectorAll('.tab').forEach(t => t.classList.toggle('active', t.dataset.key === key));
+  const info = allData[key];
+  if (!info || info.error) {
+    showEmpty(`因子 "${info?.label || key}" 数据不可用: ${info?.error || '未知错误'}`);
+    return;
+  }
+  selectedGroup = 'G0';
+  renderInfo(info);
+}
+// ======================== 渲染 ========================
+let charts = {};
+const CHART_BOX_ORDER = ['icChart','icHist','cumChart','lsChart','barChart','lsMonthly','distChart','compareChart'];
+function destroyCharts() {
+  Object.values(charts).forEach(c => c.destroy());
+  charts = {};
+}
+function showEmpty(msg) {
+  destroyCharts();
+  document.getElementById('icMetrics').innerHTML = '';
+  document.getElementById('lsMetrics').innerHTML = '';
+  // 图表区
+  document.querySelectorAll('.chart-box').forEach(box => {
+    const t = box.querySelector('.title');
+    box.innerHTML = '';
+    if (t) box.appendChild(t);
+    box.insertAdjacentHTML('beforeend', `<div class="empty-state"><div class="icon">📭</div><div class="msg">${msg}</div></div>`);
+  });
+  // 截面区
+  document.getElementById('xsecBox').style.display = 'none';
+}
+// 恢复 canvas 元素
+function restoreCanvases() {
+  document.querySelectorAll('.chart-box').forEach(box => {
+    const titleEl = box.querySelector('.title');
+    if (!box.querySelector('canvas') && titleEl) {
+      const titleText = titleEl.textContent;
+      let canvasId = '';
+      if (titleText.includes('IC 时序')) canvasId = 'icChart';
+      else if (titleText.includes('分布直方图') && titleText.includes('IC')) canvasId = 'icHist';
+      else if (titleText.includes('分层累计')) canvasId = 'cumChart';
+      else if (titleText.includes('多空累计')) canvasId = 'lsChart';
+      else if (titleText.includes('分组月均')) canvasId = 'barChart';
+      else if (titleText.includes('每月多空')) canvasId = 'lsMonthly';
+      else if (titleText.includes('因子值分布')) canvasId = 'distChart';
+      else if (titleText.includes('ICIR 对比')) canvasId = 'compareChart';
+      if (canvasId) {
+        box.innerHTML = '';
+        box.appendChild(titleEl);
+        box.insertAdjacentHTML('beforeend', `<div class="canvas-wrap"><canvas id="${canvasId}"></canvas></div>`);
+      }
+    }
+  });
+}
+function renderInfo(info) {
+  destroyCharts();
+  restoreCanvases();
+  document.getElementById('xsecBox').style.display = 'block';
+  // ---- IC 指标卡片 ----
+  const s = info.ic_summary;
+  const icMean = s['IC 均值'];
+  const icir = s['ICIR'];
+  const icCards = [
+    { L:'IC 均值', V:icMean, C:icMean>0.02?'positive':icMean<-0.02?'negative':'neutral', F:v=>v.toFixed(4) },
+    { L:'IC 标准差', V:s['IC 标准差'], C:'neutral', F:v=>v.toFixed(4) },
+    { L:'ICIR', V:icir, C:icir>0.5?'positive':icir<-0.5?'negative':'neutral', F:v=>v.toFixed(3) },
+    { L:'IC > 0 占比', V:s['IC > 0 占比'], C:s['IC > 0 占比']>0.55?'positive':'neutral', F:v=>(v*100).toFixed(1)+'%' },
+    { L:'|IC| > 0.02', V:s['|IC| > 0.02 占比'], C:'neutral', F:v=>(v*100).toFixed(1)+'%' },
+    { L:'月数', V:info.ic_series.length, C:'neutral', F:v=>v },
+  ];
+  document.getElementById('icMetrics').innerHTML = icCards.map(m => `<div class="metric-card"><div class="label">${m.L}</div><div class="value ${m.C}">${m.F(m.V)}</div></div>`).join('');
+  // ---- 多空指标卡片 ----
+  const lm = info.long_short_metrics || {};
+  const lsCards = [
+    { L:'年化夏普', V:lm.sharpe_annual||0, C:(lm.sharpe_annual||0)>0?'positive':'negative', F:v=>v.toFixed(2) },
+    { L:'胜率', V:lm.win_rate||0, C:(lm.win_rate||0)>0.5?'positive':'neutral', F:v=>(v*100).toFixed(1)+'%' },
+    { L:'最大回撤', V:lm.max_drawdown||0, C:(lm.max_drawdown||0)>-0.1?'positive':'negative', F:v=>(v*100).toFixed(1)+'%' },
+    { L:'累计收益', V:lm.total_return||0, C:(lm.total_return||0)>0?'positive':'negative', F:v=>(v*100).toFixed(1)+'%' },
+  ];
+  document.getElementById('lsMetrics').innerHTML = lsCards.map(m => `<div class="metric-card"><div class="label">${m.L}</div><div class="value ${m.C}">${m.F(m.V)}</div></div>`).join('');
+  // ---- 图表 1: IC 时序 ----
+  const icData = info.ic_series;
+  const icLabels = icData.map(d => d.date.slice(0, 7));
+  const icValues = icData.map(d => d.ic);
+  charts.ic = new Chart(document.getElementById('icChart'), {
+    type: 'bar', data: { labels: icLabels, datasets: [{ data: icValues, backgroundColor: icValues.map(v => v>=0?'rgba(38,166,154,0.7)':'rgba(239,83,80,0.6)'), borderWidth:0, borderRadius:2 }] },
+    options: chartOpts('bar', { plugins:{ tooltip:{ callbacks:{ label:ctx=>`IC: ${ctx.raw.toFixed(4)}` } } }, scales:{ y:{ title:{ display:true, text:'Rank IC' } } } })
+  });
+  // ---- 图表 2: IC 分布 ----
+  const bins=15, mn=Math.min(...icValues), mx=Math.max(...icValues), bw=(mx-mn)/bins||0.01;
+  const hd=Array(bins).fill(0); icValues.forEach(v=>{ const i=Math.min(Math.floor((v-mn)/bw),bins-1); hd[i]++; });
+  charts.hist = new Chart(document.getElementById('icHist'), {
+    type: 'bar', data: { labels: Array.from({length:bins},(_,i)=>(mn+bw*i).toFixed(2)), datasets: [{ data: hd, backgroundColor:'rgba(91,141,239,0.6)', borderWidth:0, borderRadius:2 }] },
+    options: chartOpts('bar', { scales:{ y:{ title:{display:true,text:'频数'} }, x:{ title:{display:true,text:'IC 值'} } } })
+  });
+  // ---- 图表 3: 分层累计收益 ----
+  const cum=info.cum_returns, gc=['#ef5350','#ffa726','#ffee58','#66bb6a','#26a69a'];
+  charts.cum = new Chart(document.getElementById('cumChart'), {
+    type: 'line', data: { datasets: Object.entries(cum).map(([g,pts],i)=>({ label:g, data:pts.map(p=>({x:p.date.slice(0,7),y:p.cum_return})), borderColor:gc[i], backgroundColor:'transparent', borderWidth:1.5, pointRadius:0, tension:0.1 })) },
+    options: chartOpts('line', { scales:{ y:{ title:{display:true,text:'累计收益 (1=基准)'} } }, plugins:{ tooltip:{ callbacks:{ label:ctx=>`${ctx.dataset.label}: ${(ctx.raw.y||ctx.raw).toFixed(3)}` } } } })
+  });
+  // ---- 图表 4: 多空累计收益 ----
+  const lsData = info.long_short;
+  if(lsData && lsData.length>0) {
+    let cl=1;
+    charts.ls = new Chart(document.getElementById('lsChart'), {
+      type: 'line', data: { datasets: [{ label:'Long-Short', data: lsData.map(p=>{ cl*=(1+p.return); return {x:p.date.slice(0,7),y:cl}; }), borderColor:'rgba(91,141,239,1)', backgroundColor:'rgba(91,141,239,0.1)', fill:true, borderWidth:2, pointRadius:0, tension:0.1 }] },
+      options: chartOpts('line', { scales:{ y:{ title:{display:true,text:'累计收益'} } } })
+    });
+  }
+  // ---- 图表 5: 分组月均收益 ----
+  const grAvg=info.group_avg_return, gk=Object.keys(grAvg).sort(), gv=gk.map(k=>grAvg[k]*100);
+  charts.bar = new Chart(document.getElementById('barChart'), {
+    type: 'bar', data: { labels:gk, datasets: [{ data:gv, backgroundColor:gv.map((_,i)=>i===0?'rgba(239,83,80,0.7)':i===gv.length-1?'rgba(38,166,154,0.7)':'rgba(91,141,239,0.6)'), borderWidth:0, borderRadius:3 }] },
+    options: chartOpts('bar', { scales:{ y:{ title:{display:true,text:'月均收益 (%)'} } }, plugins:{ tooltip:{ callbacks:{ label:ctx=>`${ctx.raw.toFixed(2)}%` } } } })
+  });
+  // ---- 图表 6: 每月多空收益柱状图 (NEW) ----
+  if(lsData && lsData.length>0) {
+    const lsLabels=lsData.map(d=>d.date.slice(0,7)), lsVals=lsData.map(d=>d.return*100);
+    charts.lsMonthly = new Chart(document.getElementById('lsMonthly'), {
+      type: 'bar', data: { labels:lsLabels, datasets: [{ data:lsVals, backgroundColor:lsVals.map(v=>v>=0?'rgba(38,166,154,0.6)':'rgba(239,83,80,0.5)'), borderWidth:0, borderRadius:2 }] },
+      options: chartOpts('bar', { scales:{ y:{ title:{display:true,text:'多空收益 (%)'} } }, plugins:{ tooltip:{ callbacks:{ label:ctx=>`${ctx.raw.toFixed(2)}%` } } } })
+    });
+  }
+  // ---- 图表 7: 因子值分布直方图 (NEW) ----
+  const fd = info.factor_distribution;
+  if(fd && fd.histogram && fd.histogram.length>0) {
+    const distBins=fd.histogram, distLabels=distBins.map(b=>b.bin_start.toFixed(2)), distCounts=distBins.map(b=>b.count);
+    charts.dist = new Chart(document.getElementById('distChart'), {
+      type: 'bar', data: { labels:distLabels, datasets: [{ data:distCounts, backgroundColor:'rgba(255,167,38,0.6)', borderWidth:0, borderRadius:1 }] },
+      options: chartOpts('bar', { scales:{ y:{ title:{display:true,text:'股票数'} }, x:{ title:{display:true,text:'因子值'} } } })
+    });
+  }
+  // ---- 图表 8: 全因子 ICIR 对比 ----
+  renderCompareChart();
+  // ---- 截面明细表 (NEW) ----
+  renderCrossSection(info);
+}
+// ======================== 全因子 ICIR 对比 ========================
+function renderCompareChart() {
+  const factors=Object.entries(allData).filter(([k,v])=>!k.startsWith('_')&&!v.error);
+  const labels=factors.map(([k,v])=>v.label), icirVals=factors.map(([k,v])=>v.ic_summary['ICIR']);
+  const icMeanVals=factors.map(([k,v])=>v.ic_summary['IC 均值']), hi=factors.findIndex(([k])=>k===activeFactor);
+  charts.compare = new Chart(document.getElementById('compareChart'), {
+    type: 'bar', data: { labels, datasets: [{ label:'ICIR', data:icirVals, backgroundColor:factors.map((_,i)=>i===hi?(icirVals[i]>0?'rgba(38,166,154,0.9)':'rgba(239,83,80,0.9)'):(icirVals[i]>0?'rgba(38,166,154,0.35)':'rgba(239,83,80,0.3)')), borderWidth:0, borderRadius:3 }] },
+    options: chartOpts('bar', { plugins:{ tooltip:{ callbacks:{ label:ctx=>{ const i=ctx.dataIndex; return [`ICIR: ${icirVals[i].toFixed(3)}`,`IC均值: ${icMeanVals[i].toFixed(4)}`]; } } }, legend:{display:false} }, scales:{ y:{ title:{display:true,text:'ICIR'} } } })
+  });
+}
+// ======================== 截面明细表 ========================
+function renderCrossSection(info) {
+  const xs = info.cross_section;
+  if(!xs || !xs.groups) { document.getElementById('xsecBox').style.display='none'; return; }
+  const groups = Object.keys(xs.groups).sort();
+  // 顶部 Tab 导航
+  const tabsHtml = groups.map(g => {
+    const gd = xs.groups[g];
+    const fwdMean = gd.forward_mean ? (gd.forward_mean*100).toFixed(2) : '-';
+    return `<span class="xsec-tab ${g===selectedGroup?'active':''}" data-group="${g}" onclick="switchGroup('${g}')">${g}</span>`;
+  }).join('');
+  document.getElementById('xsecTabs').innerHTML = tabsHtml;
+  switchGroupTable(xs);
+}
+function switchGroup(g) {
+  selectedGroup = g;
+  document.querySelectorAll('.xsec-tab').forEach(t => t.classList.toggle('active', t.dataset.group===g));
+  const info = allData[activeFactor];
+  if(info) switchGroupTable(info.cross_section);
+}
+function switchGroupTable(xs) {
+  const gd = xs.groups[selectedGroup];
+  if(!gd) return;
+  const fwdMean = gd.forward_mean ? (gd.forward_mean*100).toFixed(2) : '-';
+  document.getElementById('xsecStats').innerHTML = `${selectedGroup}: ${gd.count} 只 | 因子均值=${gd.factor_mean.toFixed(4)} | 因子标准差=${gd.factor_std.toFixed(4)} | 下月均收益=${fwdMean}%`;
+  const stocks = gd.top10 || [];
+  if(stocks.length===0) { document.getElementById('xsecTable').innerHTML='<tr><td colspan="4">无数据</td></tr>'; return; }
+  document.getElementById('xsecTable').innerHTML = `<thead><tr><th>#</th><th>代码</th><th>因子值</th><th>下月收益</th></tr></thead><tbody>${
+    stocks.map((s,i) => `<tr>
+      <td style="color:var(--text2)">${i+1}</td>
+      <td class="sym">${s.symbol}</td>
+      <td>${s.factor_value.toFixed(4)}</td>
+      <td class="${(s.forward_return||0)>=0?'pos':'neg'}">${s.forward_return?((s.forward_return)*100).toFixed(2)+'%':'-'}</td>
+    </tr>`).join('')
+  }</tbody>`;
+}
+// ======================== 图表配置 ========================
+function chartOpts(type, overrides={}) {
+  const base = {
+    responsive:true, maintainAspectRatio:false, animation:{duration:400},
+    plugins:{
+      legend:{ labels:{ color:'#93b3c9', usePointStyle:true, boxWidth:8, padding:12, font:{size:11} } },
+      tooltip:{ backgroundColor:'#16334a', borderColor:'#07111b', borderWidth:2, titleColor:'#dbeaf5', bodyColor:'#dbeaf5', padding:10 }
+    },
+    scales:{
+      x:{ ticks:{ color:'#93b3c9', maxTicksLimit:12, maxRotation:45, font:{size:10} }, grid:{ color:'rgba(147,179,201,0.2)' } },
+      y:{ ticks:{ color:'#93b3c9', font:{size:10} }, grid:{ color:'rgba(147,179,201,0.2)' }, beginAtZero: type==='bar' }
+    }
+  };
+  return deepMerge(base, overrides);
+}
+function deepMerge(target, source) {
+  const out = Object.assign({}, target);
+  for(const key of Object.keys(source)) {
+    if(source[key] && typeof source[key]==='object' && !Array.isArray(source[key])) out[key]=deepMerge(target[key]||{},source[key]);
+    else out[key]=source[key];
+  }
+  return out;
+}
+initTabs();
+</script>
+</body>
+</html>

package/src/index.js CHANGED Viewed

@@ -3,6 +3,11 @@
  * 定位：会话内「教学平面」——把 agent 生成的 self-contained HTML 投影为可讲解、
  * 可勾画、可截图的板书界面。
  *
+ * 两层都在这个包里：
+ *   能力层 = 本文件注册的 stage_* 工具 + client 半的「面板」视图；
+ *   行为层 = src/skills.js 把包内 skills/stage-panel/ 注册成 bundled skill。
+ * 挂上插件就同时拿到两者——不再依赖任何 preset 单独装一份使用手册。
+ *
  * 原生设计（单一数据流）：只注册模型工具，无私有状态、无 RPC、无 wait。
  * 「面板」状态 = 会话中最近一次 stage_* 工具调用的参数（client 从会话快照消费）；
  * 用户点选/回传 = 真实用户消息（DSH 原生输入流）。
@@ -13,11 +18,17 @@
  * 消息进入会话，模型在下一轮就能看见。这与 stage_choice 的机制完全一致。
  */
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { createSkillProvider } from './skills.js'
 export const name = 'teaching-board'
 export const inject = ['tools']
 export function apply(ctx) {
+  // 行为层：把自带的使用手册发布进技能目录。这里用可选读取而不是 inject——
+  // 技能注册是增益，不该让白板因为缺 skills 服务而整个不挂载。
+  const skills = ctx.get('skills')
+  if (skills !== undefined) skills.registerProvider(createSkillProvider)
   const textRender = (_args, value) => [{ type: 'text', text: value }]
   ctx.tools.register(defineTool({

package/src/skills.js ADDED Viewed

@@ -0,0 +1,88 @@
+/** 教学平面的「行为层」：把本包自带的使用手册注册成一个 bundled skill。
+ *
+ * 为什么由插件自己注册：纪律要跟着能力走。任何挂载本插件的会话（不论用哪个 preset）
+ * 都应该在技能目录里看到 stage-panel。手册若只放在某个 preset 的 skills/ 里，
+ * 其余会话就会停在「有工具、没纪律」的状态——白板能开，但不知道该怎么用。
+ *
+ * 与官方 @deepseek-ai/dsh-skill-badge 同一模式：list() 只给候选，get() 才读正文；
+ * resourceBase 指向本包目录，正文里的相对路径（references/…、submode/…）才能解析。
+ * provider 由 skills 服务托管，随插件 fiber 一起注销，不需要手动 cleanup。
+ */
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+const SKILL_NAME = 'stage-panel'
+const PROVIDER_NAME = 'teaching-board'
+const SKILL_DIR = new URL('../skills/stage-panel/', import.meta.url)
+const SKILL_BODY_URL = new URL('SKILL.md', SKILL_DIR)
+const RESOURCE_BASE = { kind: 'directory', path: fileURLToPath(SKILL_DIR) }
+const INVOCATION = { modelInvocable: true, userInvocable: true }
+/** `@deepseek-ai/dsh-skill` 导出的 BUNDLED_SKILL_RANK，随包发布技能的档次。
+ *  这里写字面量而不 import：本插件只依赖 dsh-tools，不为了一个排序常量多一条依赖边。
+ *  rank 只用于同一层内的重名排序（project > runtime > user），跨层由层远近决定。 */
+const BUNDLED_SKILL_RANK = 600
+/** frontmatter 缺 description 时的兜底；正常情况下以 SKILL.md 为准（单一真相）。 */
+const FALLBACK_DESCRIPTION = 'DSH 教学平面（板书面板）使用手册。'
+/** 拆掉正文首部的 YAML frontmatter：它服务于「被文件系统扫描」那种用法，
+ *  由 provider 读取时属于元数据而非正文。只解析需要的一层 key: value。 */
+function splitFrontmatter(raw) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw)
+  if (match === null) return { meta: {}, content: raw }
+  const meta = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const entry = /^([A-Za-z][\w-]*)\s*:\s*(.*)$/.exec(line.trim())
+    if (entry !== null) meta[entry[1]] = entry[2].trim()
+  }
+  return { meta, content: raw.slice(match[0].length).replace(/^\n+/, '') }
+}
+/** 构造 stage-panel 的 bundled 技能 provider（交给 ctx.skills.registerProvider）。 */
+export function createSkillProvider() {
+  let loaded
+  const load = () => {
+    if (loaded === undefined) {
+      loaded = readFile(SKILL_BODY_URL, 'utf8').then((raw) => {
+        const { meta, content } = splitFrontmatter(raw)
+        return { description: meta.description ?? FALLBACK_DESCRIPTION, content }
+      })
+    }
+    return loaded
+  }
+  return {
+    name: PROVIDER_NAME,
+    async list() {
+      let description = FALLBACK_DESCRIPTION
+      try {
+        description = (await load()).description
+      } catch {
+        // 手册文件缺失时仍让目录条目可用，正文读取会在 get() 处明确报错。
+      }
+      return [{
+        name: SKILL_NAME,
+        description,
+        invocation: INVOCATION,
+        provider: PROVIDER_NAME,
+        source: 'bundled',
+        resourceBase: RESOURCE_BASE,
+        rank: BUNDLED_SKILL_RANK,
+        locator: SKILL_BODY_URL,
+        path: fileURLToPath(SKILL_BODY_URL),
+      }]
+    },
+    async get() {
+      const { description, content } = await load()
+      return {
+        name: SKILL_NAME,
+        description,
+        invocation: INVOCATION,
+        provider: PROVIDER_NAME,
+        source: 'bundled',
+        resourceBase: RESOURCE_BASE,
+        content,
+        path: fileURLToPath(SKILL_BODY_URL),
+      }
+    },
+  }
+}