visualknowledge 0.2.2 → 0.2.4

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

@@ -6,72 +6,18 @@
  */
 
 import { html } from 'htm/react';
-import { useState, useEffect, useRef } from 'react';
+import { useEffect, useRef } from 'react';
 import { WidgetContainer } from './WidgetContainer.jsx';
 
-const IFRAME_TIMEOUT_MS = 10000;
-
 export function HtmlWidget({ html: htmlContent, onFullscreen }) {
   const iframeRef = useRef(null);
-  const [status, setStatus] = useState('loading');
-  const timerRef = useRef(null);
-  const stableContentRef = useRef('');
 
-  // 检测内容是否稳定（连续相同内容说明流结束了）
+  // 流式写入：内容到达即写入 iframe
   useEffect(() => {
     if (!htmlContent) return;
-
-    // 内容变化时重置状态
-    if (htmlContent !== stableContentRef.current) {
-      setStatus('loading');
-      if (timerRef.current) clearTimeout(timerRef.current);
-    }
-
-    stableContentRef.current = htmlContent;
-  }, [htmlContent]);
-
-  // iframe 初始化 + 写入内容
-  useEffect(() => {
     const iframe = iframeRef.current;
-    if (!iframe || !htmlContent) return;
-
-    let settled = false;
-
-    const write = () => {
-      _writeHtml(iframe, htmlContent);
-      setStatus('done');
-      settled = true;
-      if (timerRef.current) clearTimeout(timerRef.current);
-    };
-
-    // 首次加载或 src 变化时等待 load 事件
-    const handler = () => {
-      write();
-    };
-
-    // 超时保护：即使 load 事件没触发也强制写入
-    timerRef.current = setTimeout(() => {
-      if (!settled) {
-        console.warn('[HtmlWidget] iframe load timeout, forcing write');
-        write();
-      }
-    }, IFRAME_TIMEOUT_MS);
-
-    iframe.addEventListener('load', handler);
-
-    // 如果 iframe 已经加载完成，直接写入
-    try {
-      if (iframe.contentDocument && iframe.contentDocument.readyState === 'complete') {
-        write();
-      }
-    } catch (_) {
-      // cross-origin or not ready yet, wait for load event
-    }
-
-    return () => {
-      iframe.removeEventListener('load', handler);
-      if (timerRef.current) clearTimeout(timerRef.current);
-    };
+    if (!iframe) return;
+    _writeHtml(iframe, htmlContent);
   }, [htmlContent]);
 
   const handleFullscreen = () => {
@@ -80,17 +26,19 @@ export function HtmlWidget({ html: htmlContent, onFullscreen }) {
     }
   };
 
+  const hasContent = htmlContent && htmlContent.trim().length > 0;
+
   return html`
     <${WidgetContainer}
       badge="visualize"
-      typeLabel=${status === 'loading' ? '正在生成可视化...' : '交互式可视化'}
-      status=${status}
+      typeLabel=${hasContent ? '交互式可视化' : '正在生成可视化...'}
+      status=${hasContent ? 'done' : 'loading'}
       onZoom=${handleFullscreen}
     >
       <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}>
   `;
@@ -104,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/frontend/src/lib/streamProcessor.js

@@ -126,6 +126,14 @@ export class StreamProcessor {
     // 返回 segments 的快照，包含当前活跃段
     const result = [...this._segments];
 
+    // 更新活跃的 codeblock segment，将流式缓冲区内容暴露给组件
+    if (this._phase === 'codeblock') {
+      const lastSeg = result[result.length - 1];
+      if (lastSeg && (lastSeg.type === 'mermaid' || lastSeg.type === 'html' || lastSeg.type === 'svg')) {
+        lastSeg.content = this._buffer;
+      }
+    }
+
     // 如果有活跃的文字段且不在 segments 中，追加它
     if (this._phase === 'text' && this._activeText) {
       // 检查是否已有未完成的 text segment（最后一个 segment 可能是待更新的 text）

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "visualknowledge",
-    "version": "0.2.2",
+    "version": "0.2.4",
     "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": "环形/链表可视化",
+        "trigger": ["环形", "链表", "环", "cycle", "ring", "floyd", "判圈", "龟兔赛跑", "快慢指针", "循环链表", "环形链表", "约瑟夫"],
+        "description": "展示环形链表、Floyd判圈算法、循环队列等需要闭合回路的图"
+    },
     "generic_pipeline": {
         "name": "通用流程图",
         "trigger": ["流程", "步骤", "过程", "pipeline", "workflow"],
@@ -152,8 +157,170 @@ def get_skill_prompt():
 - **Transformer 架构图** (transformer_architecture): transformer, attention, 自注意力
 - **神经网络流程图** (neural_network_flow): 神经网络, CNN, 卷积, 池化
 - **注意力机制详解** (attention_detail): QKV, 注意力权重, softmax
+- **环形/链表可视化** (ring_graph): 环形链表、判圈算法、快慢指针、循环队列
 - **通用流程图** (generic_pipeline): 流程, 步骤, pipeline
 
+---
+
+### ⚠️ 环形/链表可视化规范（ring_graph）
+
+环形链表、判圈算法、循环队列等**必须用内嵌 SVG**，不要用 flex+文字箭头，因为环路无法用 → ↓ 闭合。
+
+#### 核心原则
+1. **节点位置用三角函数计算**：把环上的节点均匀放在圆上，用 `(cx + r*cos(θ), cy + r*sin(θ))` 定位
+2. **非环节点排成一条直线**（tail 部分水平排列），最后一个非环节点指向环节点
+3. **箭头用 SVG `<line>` + `<marker>` 箭头标记**
+4. **整个 SVG 放在一个 HTML 容器 `<div>` 中**，配合标题和图例
+
+#### 布局方法
+```
+tail 节点（水平直线）        环上的节点（圆形排列）
+  3 → 2 → 1 → 5 ← 4
+              ↓       ↑
+              6 → 7 → 8
+```
+
+- tail 部分：从左到右水平排列，间距固定
+- 环部分：用圆排列，节点均匀分布在圆周上
+- 连线：SVG `<line>` 元素 + 箭头 marker
+
+#### 节点和箭头样式
+```css
+/* 节点 */
+.node {
+  fill: #1e293b;           /* 深色填充 */
+  stroke: #64748b;         /* 边框 */
+  stroke-width: 2;
+  r: 22;                   /* 半径 */
+}
+.node-label {
+  fill: #f1f5f9;           /* 白色文字 */
+  font-size: 14px;
+  font-weight: bold;
+  text-anchor: middle;
+  dominant-baseline: central;
+}
+
+/* 箭头连线 */
+.edge {
+  stroke: #94a3b8;
+  stroke-width: 2;
+  marker-end: url(#arrow);
+}
+
+/* 特殊高亮 */
+.node-entry { fill: #16a34a20; stroke: #16a34a; stroke-width: 3; }  /* 环入口 - 绿 */
+.node-meet  { fill: #e11d4820; stroke: #e11d48; stroke-width: 3; }  /* 相遇点 - 红 */
+.node-slow  { stroke: #d97706; stroke-width: 2.5; stroke-dasharray: 5,3; } /* 慢指针 - 橙 */
+.node-fast  { stroke: #2563eb; stroke-width: 2.5; stroke-dasharray: 8,4; } /* 快指针 - 蓝 */
+```
+
+#### 高质量示例：Floyd 判圈算法
+
+```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>
+
+<svg viewBox="0 0 700 380" style="width:100%;max-width:700px;margin:0 auto;display:block">
+<defs>
+  <marker id="arrow" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+    <path d="M0,0 L8,3 L0,6" fill="#94a3b8"/>
+  </marker>
+  <marker id="arrow-green" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+    <path d="M0,0 L8,3 L0,6" fill="#16a34a"/>
+  </marker>
+</defs>
+
+<!-- Tail 部分 (非环节点) -->
+<circle cx="80" cy="80" r="22" fill="#1e293b" stroke="#64748b" stroke-width="2"/>
+<text x="80" y="80" fill="#f1f5f9" font-size="14" font-weight="bold" text-anchor="middle" dominant-baseline="central">3</text>
+<line x1="102" y1="80" x2="148" y2="80" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+
+<circle cx="170" cy="80" r="22" fill="#1e293b" stroke="#64748b" stroke-width="2"/>
+<text x="170" y="80" fill="#f1f5f9" font-size="14" font-weight="bold" text-anchor="middle" dominant-baseline="central">2</text>
+<line x1="192" y1="80" x2="238" y2="80" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+
+<circle cx="260" cy="80" r="22" fill="#1e293b" stroke="#64748b" stroke-width="2"/>
+<text x="260" y="80" fill="#f1f5f9" font-size="14" font-weight="bold" text-anchor="middle" dominant-baseline="central">1</text>
+<line x1="282" y1="80" x2="418" y2="240" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+
+<!-- Tail → Entry 标注 -->
+<text x="360" y="140" fill="#16a34a" font-size="11" text-anchor="middle">a 步（到入口）</text>
+
+<!-- 环上的节点 (圆形排列，圆心 440,260 半径 100) -->
+<!-- 5: θ=270° → (440, 160) -->
+<circle cx="440" cy="160" r="22" fill="#16a34a20" stroke="#16a34a" stroke-width="3"/>
+<text x="440" y="160" fill="#f1f5f9" font-size="14" font-weight="bold" text-anchor="middle" dominant-baseline="central">5</text>
+<text x="440" y="130" fill="#16a34a" font-size="10" text-anchor="middle">入口</text>
+
+<!-- 4: θ=342° → (535, 229) -->
+<circle cx="535" cy="229" r="22" fill="#1e293b" stroke="#64748b" stroke-width="2"/>
+<text x="535" y="229" fill="#f1f5f9" font-size="14" font-weight="bold" text-anchor="middle" dominant-baseline="central">4</text>
+
+<!-- 6: θ=54° → (499, 341) -->
+<circle cx="499" cy="341" r="22" fill="#1e293b" stroke="#64748b" stroke-width="2"/>
+<text x="499" y="341" fill="#f1f5f9" font-size="14" font-weight="bold" text-anchor="middle" dominant-baseline="central">6</text>
+
+<!-- 7: θ=126° → (381, 341) -->
+<circle cx="381" cy="341" r="22" fill="#e11d4820" stroke="#e11d48" stroke-width="3"/>
+<text x="381" y="341" fill="#f1f5f9" font-size="14" font-weight="bold" text-anchor="middle" dominant-baseline="central">7</text>
+<text x="381" y="374" fill="#e11d48" font-size="10" text-anchor="middle">相遇点</text>
+
+<!-- 8: θ=198° → (345, 229) -->
+<circle cx="345" cy="229" r="22" fill="#1e293b" stroke="#64748b" stroke-width="2"/>
+<text x="345" y="229" fill="#f1f5f9" font-size="14" font-weight="bold" text-anchor="middle" dominant-baseline="central">8</text>
+
+<!-- 环上的箭头连线 (5→4→6→7→8→5) -->
+<line x1="461" y1="152" x2="514" y2="219" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+<line x1="555" y1="238" x2="518" y2="328" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+<line x1="489" y1="357" x2="395" y2="353" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+<line x1="363" y1="333" x2="328" y2="241" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+<line x1="348" y1="211" x2="418" y2="171" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+
+<!-- 距离标注 -->
+<text x="388" y="310" fill="#94a3b8" font-size="10" text-anchor="middle">b</text>
+<text x="330" y="276" fill="#94a3b8" font-size="10" text-anchor="middle">c</text>
+
+<!-- 图例说明 -->
+<text x="440" y="260" fill="#94a3b8" font-size="11" text-anchor="middle" font-style="italic">环长 c = b + 剩余</text>
+
+<!-- 指针 -->
+<text x="100" y="110" fill="#d97706" font-size="11" font-weight="bold">🐢 slow</text>
+<text x="100" y="124" fill="#2563eb" font-size="11" font-weight="bold">🐇 fast</text>
+<line x1="140" y1="107" x2="170" y2="90" stroke="#d97706" stroke-width="1.5" stroke-dasharray="4,2"/>
+<line x1="140" y1="120" x2="170" y2="90" stroke="#2563eb" stroke-width="1.5" stroke-dasharray="6,3"/>
+</svg>
+
+<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. **先算坐标再画**：确定圆心 `(cx, cy)` 和半径 `r`，用 `θ = i × 360°/n` 计算每个节点位置
+2. **箭头要指向圆心方向偏移**：`marker-end` 自动朝向，但起点要从节点边缘出发（不是圆心），终点停在目标节点边缘
+3. **Tail 节点水平排列**，最后一个 tail 节点画一条指向环节点的箭头线
+4. **闭合箭头**：最后一个环节点必须画箭头回到第一个环节点（这是关键！）
+5. **节点数量 ≤ 8**：太多节点看不清，适当合并或简化
+6. **用 `<text>` 标注距离**（a, b, c）和关键位置（入口、相遇点）
+7. **viewBox 要足够大**：确保所有节点和标注都在可视区域内
+
 ### 使用规则
 1. 涉及架构/流程/数据变换/神经网络结构/算法步骤 → **必须用 ```html**
 2. 简单关系图/时序图/饼图 → 用 ```mermaid