visualknowledge 0.2.3 → 0.2.5

package/frontend/src/components/ChatArea.jsx

@@ -1,19 +1,38 @@
 /**
  * ChatArea - 滚动容器组件
  *
- * 自动滚动到底部（当 messages 变化或 isStreaming 变化时）
+ * 智能自动滚动：仅在用户处于底部附近时自动跟随，
+ * 用户向上滚动时保持位置不被拉回。
  */
 
 import { html } from 'htm/react';
 import { useRef, useEffect } from 'react';
 
+const STICKY_THRESHOLD = 80;
+
 export function ChatArea({ children }) {
   const containerRef = useRef(null);
+  const userScrolledUp = useRef(false);
+
+  // 监听用户手动滚动
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    const onScroll = () => {
+      const distFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+      userScrolledUp.current = distFromBottom > STICKY_THRESHOLD;
+    };
+
+    el.addEventListener('scroll', onScroll, { passive: true });
+    return () => el.removeEventListener('scroll', onScroll);
+  }, []);
 
+  // 内容变化时：仅在用户没有主动上滑时自动滚到底部
   useEffect(() => {
-    if (containerRef.current) {
-      containerRef.current.scrollTop = containerRef.current.scrollHeight;
-    }
+    const el = containerRef.current;
+    if (!el || userScrolledUp.current) return;
+    el.scrollTop = el.scrollHeight;
   }, [children]);
 
   return html`<div className="chat-area" ref=${containerRef}>${children}</div>`;

package/frontend/src/components/widgets/HtmlWidget.jsx

@@ -38,7 +38,7 @@ export function HtmlWidget({ html: htmlContent, onFullscreen }) {
       <iframe
         ref=${iframeRef}
         sandbox="allow-scripts allow-same-origin"
-        style=${{ width: '100%', height: '460px', border: 'none', display: 'block' }}
+        style=${{ width: '100%', height: hasContent ? undefined : '0px', border: 'none', display: 'block' }}
       />
     </${WidgetContainer}>
   `;
@@ -52,10 +52,10 @@ function _writeHtml(iframe, content) {
     doc.write(content);
     doc.close();
 
-    // 调整高度
+    // 根据实际内容调整高度，随内容增长逐步扩大
     try {
-      const h = Math.max(doc.body.scrollHeight, doc.documentElement.scrollHeight, 300);
-      iframe.style.height = Math.min(h + 20, 1200) + 'px';
+      const h = Math.max(doc.body.scrollHeight, doc.documentElement.scrollHeight, 0);
+      iframe.style.height = Math.min(h + 16, 1200) + 'px';
     } catch (_) {}
   } catch (e) {
     console.warn('[HtmlWidget] write failed:', e);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "visualknowledge",
-    "version": "0.2.3",
+    "version": "0.2.5",
     "description": "Interactive AI Chat with Visualization - one-click launch via npx",
     "bin": {
         "visualknowledge": "./bin/visualknowledge.js"

package/skills/visualize.py

@@ -14,6 +14,11 @@ SKILLS = {
         "trigger": ["qkv", "query key value", "注意力计算", "注意力权重", "softmax"],
         "description": "详细展示 Q/K/V 计算过程"
     },
+    "ring_graph": {
+        "name": "环形/链表可视化（JS动态计算）",
+        "trigger": ["环形", "链表", "环", "cycle", "ring", "floyd", "判圈", "龟兔赛跑", "快慢指针", "循环链表", "环形链表", "约瑟夫"],
+        "description": "用 JS 动态计算坐标画环形链表/Floyd判圈/循环队列，绝不手算坐标"
+    },
     "generic_pipeline": {
         "name": "通用流程图",
         "trigger": ["流程", "步骤", "过程", "pipeline", "workflow"],
@@ -152,8 +157,231 @@ def get_skill_prompt():
 - **Transformer 架构图** (transformer_architecture): transformer, attention, 自注意力
 - **神经网络流程图** (neural_network_flow): 神经网络, CNN, 卷积, 池化
 - **注意力机制详解** (attention_detail): QKV, 注意力权重, softmax
+- **环形/链表可视化** (ring_graph): 环形链表、判圈算法、快慢指针、循环队列
 - **通用流程图** (generic_pipeline): 流程, 步骤, pipeline
 
+---
+
+### ⚠️ 环形/链表可视化规范（ring_graph）— 矩形环 + JS 动态计算
+
+**核心原则：用矩形画环，不用圆形！** 环形结构画成矩形路径（上排→右下→下排←左上闭合），坐标由 JS 自动计算。
+
+#### 为什么用矩形？
+1. 矩形只需要水平/垂直线，无需三角函数，坐标100%正确
+2. 圆形需要 sin/cos 计算角度，AI 极易算错导致节点错位、箭头断开
+3. 矩形环更清晰：上排→右转→下排→左转→回到入口，首尾相连就是环
+
+#### 矩形环布局原理
+```
+[tail...] → [5] → [4] → [6]      ← 上排（环的前半，从左到右）
+             ↑              ↓
+             [8] ← [7]            ← 下排（环的后半，从右到左，最终连回入口）
+```
+
+- 上排 = ringNodes 的前半部分，从左到右，用 → 连接
+- 下排 = ringNodes 的后半部分，从右到左，用 ← 连接
+- 右侧 = 上排末尾 ↓ 连到下排首个
+- 左侧 = 下排末尾 ↑ 连回入口（环闭合！）
+
+#### 必须照搬的 JS 模板（直接复制，只改数据部分）
+
+```html
+<div style="max-width:860px;margin:0 auto;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;color:inherit;background:transparent;padding:20px">
+<style>
+.ring-legend{display:flex;gap:16px;justify-content:center;flex-wrap:wrap;margin-top:16px;font-size:12px}
+.ring-legend span{display:flex;align-items:center;gap:4px}
+.ring-dot{width:12px;height:12px;border-radius:50%;display:inline-block}
+</style>
+
+<h3 style="text-align:center;font-size:16px;margin-bottom:4px">Floyd 判圈算法 — 龟兔赛跑</h3>
+<p style="text-align:center;font-size:12px;opacity:0.5;margin-bottom:16px">slow 走 1 步 · fast 走 2 步 · 必在环内相遇</p>
+
+<div id="ring-container"></div>
+
+<script>
+(function() {
+  // ===== 只需修改这里的数据 =====
+  var tailNodes = [3, 2, 1];        // tail 部分（从左到右）
+  var ringNodes = [5, 4, 6, 7, 8];  // 环部分（顺序排列，第一个是入口）
+  var entryIdx = 0;                  // 环入口在 ringNodes 中的下标
+  var meetIdx = 3;                   // 相遇点下标（-1=无）
+  // ==============================
+
+  var NR = 24;           // 节点半径
+  var GAP = 90;          // 同行节点间距
+  var V_GAP = 110;       // 上下排间距
+  var PAD = 50;          // 左右边距
+  var ARROW_PAD = 6;     // 箭头离节点边缘的间隙
+
+  var ringLen = ringNodes.length;
+  var tailLen = tailNodes.length;
+
+  // 将环节点分成上排和下排
+  var topCount = Math.ceil(ringLen / 2);
+  var botCount = ringLen - topCount;
+
+  // 计算上排起始 X（让上排在 tail 右侧）
+  var tailEndX = tailLen > 0 ? PAD + (tailLen - 1) * GAP : PAD - GAP;
+  var ringStartX = tailEndX + GAP;
+  var topY = PAD + NR;
+  var botY = topY + V_GAP;
+
+  // 所有节点坐标（统一索引）
+  var nodes = []; // { x, y, val, role }
+
+  // Tail 节点
+  for (var i = 0; i < tailLen; i++) {
+    nodes.push({ x: PAD + i * GAP, y: topY, val: tailNodes[i], role: 'tail' });
+  }
+
+  // 上排环节点
+  var topStart = nodes.length;
+  for (var i = 0; i < topCount; i++) {
+    var ri = i;
+    nodes.push({ x: ringStartX + i * GAP, y: topY, val: ringNodes[ri], role: 'ring', ringIdx: ri });
+  }
+
+  // 下排环节点（从右到左排列，所以 X 从上排末尾开始递减）
+  var botStart = nodes.length;
+  for (var i = 0; i < botCount; i++) {
+    var ri = topCount + i;
+    nodes.push({ x: ringStartX + (topCount - 1) * GAP - i * GAP, y: botY, val: ringNodes[ri], role: 'ring', ringIdx: ri });
+  }
+
+  // SVG 尺寸
+  var allX = nodes.map(function(n){ return n.x; });
+  var W = Math.max.apply(null, allX) + PAD + NR + 10;
+  var H = botY + NR + PAD;
+
+  // 边缘点计算（从圆心出发，沿方向偏移半径）
+  function edgePt(x1, y1, x2, y2, r) {
+    var dx = x2 - x1, dy = y2 - y1;
+    var len = Math.sqrt(dx * dx + dy * dy);
+    if (len < 1) return { x: x1, y: y1 };
+    return { x: x1 + dx / len * r, y: y1 + dy / len * r };
+  }
+
+  // 画箭头连线
+  function line(x1, y1, x2, y2, color, marker) {
+    var p1 = edgePt(x1, y1, x2, y2, NR + ARROW_PAD);
+    var p2 = edgePt(x2, y2, x1, y1, NR + ARROW_PAD);
+    return '<line x1="' + p1.x.toFixed(1) + '" y1="' + p1.y.toFixed(1) +
+           '" x2="' + p2.x.toFixed(1) + '" y2="' + p2.y.toFixed(1) +
+           '" stroke="' + color + '" stroke-width="2" marker-end="url(#' + marker + ')"/>';
+  }
+
+  // 画节点
+  function circle(n, fill, stroke, sw) {
+    var s = '<circle cx="' + n.x.toFixed(1) + '" cy="' + n.y.toFixed(1) + '" r="' + NR +
+            '" fill="' + fill + '" stroke="' + stroke + '" stroke-width="' + sw + '"/>';
+    s += '<text x="' + n.x.toFixed(1) + '" y="' + n.y.toFixed(1) +
+         '" fill="#f1f5f9" font-size="14" font-weight="bold" text-anchor="middle" dominant-baseline="central">' + n.val + '</text>';
+    return s;
+  }
+
+  var svg = '<svg viewBox="0 0 ' + W + ' ' + H + '" style="width:100%;max-width:' + W + 'px;margin:0 auto;display:block">';
+  svg += '<defs>';
+  svg += '<marker id="arr" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto"><path d="M0,0 L8,3 L0,6" fill="#94a3b8"/></marker>';
+  svg += '<marker id="arr-g" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto"><path d="M0,0 L8,3 L0,6" fill="#16a34a"/></marker>';
+  svg += '<marker id="arr-r" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto"><path d="M0,0 L8,3 L0,6" fill="#e11d48"/></marker>';
+  svg += '</defs>';
+
+  // ---- Step 1: 画连线（先画线，节点覆盖在上面）----
+
+  // Tail → Tail 箭头
+  for (var i = 0; i < tailLen - 1; i++) {
+    svg += line(nodes[i].x, nodes[i].y, nodes[i+1].x, nodes[i+1].y, '#94a3b8', 'arr');
+  }
+
+  // Tail 末尾 → 环入口（上排第一个）
+  if (tailLen > 0) {
+    svg += line(nodes[tailLen-1].x, nodes[tailLen-1].y, nodes[topStart].x, nodes[topStart].y, '#16a34a', 'arr-g');
+    // "a 步" 标注
+    var mx = (nodes[tailLen-1].x + nodes[topStart].x) / 2;
+    var my = nodes[topStart].y - NR - 10;
+    svg += '<text x="' + mx.toFixed(0) + '" y="' + my.toFixed(0) + '" fill="#16a34a" font-size="11" text-anchor="middle">a 步</text>';
+  }
+
+  // 上排 → 箭头（从左到右）
+  for (var i = 0; i < topCount - 1; i++) {
+    svg += line(nodes[topStart+i].x, nodes[topStart+i].y, nodes[topStart+i+1].x, nodes[topStart+i+1].y, '#94a3b8', 'arr');
+  }
+
+  // 上排末尾 ↓ 下排首个（右侧垂直箭头）
+  if (botCount > 0) {
+    svg += line(nodes[topStart+topCount-1].x, nodes[topStart+topCount-1].y,
+                nodes[botStart].x, nodes[botStart].y, '#94a3b8', 'arr');
+  }
+
+  // 下排 ← 箭头（从右到左）
+  for (var i = 0; i < botCount - 1; i++) {
+    svg += line(nodes[botStart+i].x, nodes[botStart+i].y, nodes[botStart+i+1].x, nodes[botStart+i+1].y, '#94a3b8', 'arr');
+  }
+
+  // 下排末尾 ↑ 回到环入口（左侧闭合箭头！这是环的关键！）
+  var closeFrom = nodes[botStart + botCount - 1];
+  var closeTo = nodes[topStart]; // 入口 = 上排第一个
+  svg += line(closeFrom.x, closeFrom.y, closeTo.x, closeTo.y, '#16a34a', 'arr-g');
+
+  // ---- Step 2: 画节点（覆盖在连线上面）----
+
+  // Tail 节点
+  for (var i = 0; i < tailLen; i++) {
+    svg += circle(nodes[i], '#1e293b', '#64748b', 2);
+  }
+
+  // 环节点
+  for (var i = 0; i < ringLen; i++) {
+    var n = nodes[topStart + i];
+    var fill = '#1e293b', stroke = '#64748b', sw = 2, label = '';
+    if (i === entryIdx) {
+      fill = '#16a34a20'; stroke = '#16a34a'; sw = 3; label = '入口';
+    } else if (i === meetIdx) {
+      fill = '#e11d4820'; stroke = '#e11d48'; sw = 3; label = '相遇点';
+    }
+    svg += circle(n, fill, stroke, sw);
+    if (label) {
+      var ly = n.y < (topY + botY) / 2 ? n.y - NR - 10 : n.y + NR + 14;
+      svg += '<text x="' + n.x.toFixed(1) + '" y="' + ly.toFixed(1) + '" fill="' + stroke + '" font-size="10" text-anchor="middle">' + label + '</text>';
+    }
+  }
+
+  // 起点指针标注
+  if (tailLen > 0) {
+    var p = nodes[0];
+    svg += '<text x="' + p.x.toFixed(0) + '" y="' + (p.y + NR + 16).toFixed(0) + '" fill="#d97706" font-size="11" font-weight="bold" text-anchor="middle">🐢 slow</text>';
+    svg += '<text x="' + p.x.toFixed(0) + '" y="' + (p.y + NR + 30).toFixed(0) + '" fill="#2563eb" font-size="11" font-weight="bold" text-anchor="middle">🐇 fast</text>';
+  }
+
+  svg += '</svg>';
+  document.getElementById('ring-container').innerHTML = svg;
+})();
+</script>
+
+<div class="ring-legend">
+  <span><span class="ring-dot" style="background:#16a34a"></span> 环入口</span>
+  <span><span class="ring-dot" style="background:#e11d48"></span> 相遇点</span>
+  <span><span class="ring-dot" style="background:#d97706"></span> 🐢 慢指针</span>
+  <span><span class="ring-dot" style="background:#2563eb"></span> 🐇 快指针</span>
+</div>
+
+<p style="text-align:center;font-size:13px;margin-top:16px;opacity:0.7">
+<strong>关键公式：</strong>a + b = k·c → <strong>a = k·c − b</strong><br/>
+从起点走 a 步 = 从相遇点走 a 步 → 必在<strong style="color:#16a34a">入口</strong>汇合
+</p>
+</div>
+```
+
+#### 使用规则（必读）
+1. **直接复制上面的模板**，只修改 `tailNodes`、`ringNodes`、`entryIdx`、`meetIdx` 这4个数据变量
+2. **绝不手写 SVG 坐标** — JS 自动计算所有矩形布局位置
+3. **绝不手算三角函数** — 矩形布局只需要水平/垂直间距
+4. 环的闭合由代码自动处理：下排末尾 ↑ 连回上排入口（入口 = `ringNodes[entryIdx]`）
+5. `entryIdx` = 环入口在 `ringNodes` 中的下标，`meetIdx` = 相遇点下标（无则设 -1）
+6. 可根据具体算法修改标题、副标题、图例和底部公式
+7. 节点数量建议 ≤ 8，太多可适当合并
+8. **分步确认流程**：① 确认 tail→entry 连线正确 ② 确认上排→右转→下排方向正确 ③ 确认下排末尾连回入口形成闭环
+
 ### 使用规则
 1. 涉及架构/流程/数据变换/神经网络结构/算法步骤 → **必须用 ```html**
 2. 简单关系图/时序图/饼图 → 用 ```mermaid