@cloudtower/eagle 4100.0.1 → 4100.0.3

package/dist/variables.scss

@@ -780,4 +780,4 @@ $green-green-a04-50: #1EC97F0A;
 $purple-purple-50: #7E41FF;
 $purple-purple-a20-50: #7E41FF33;
 $purple-purple-a16-50: #7E41FF29;
-$purple-purple-a10-50: #7E41FF1A;
+$purple-purple-a10-50: #7E41FF1A;

package/docs/core/LogView/guide.md

@@ -0,0 +1,187 @@
+# LogView
+
+## 简介
+
+LogView 是基于 xterm 封装的日志查看器组件，用于展示静态日志文本或通过 EventSource 追加的流式日志。组件内置顶部搜索栏、搜索结果导航、滚动缓冲控制、终端尺寸自适应，以及空状态和错误状态的自定义渲染能力。
+
+## 何时使用
+
+- 展示任务、主机、集群、控制器等对象的运行日志
+- 需要在大量日志中搜索关键字，并在匹配结果之间跳转
+- 需要接入 SSE / EventSource 实时追加日志流
+- 长时间运行的日志流需要限制历史缓冲行数，控制内存占用
+
+不要使用：
+
+- 展示结构化数据列表 --> 请用 `Table`
+- 仅展示短文本或状态描述 --> 请用 `Typo` / `Alert`
+- 需要编辑命令或交互式终端输入 --> LogView 默认禁用 stdin，需使用专门的终端组件
+
+## 基础用法
+
+通过 `content` 传入完整日志文本，换行内容会按终端逐行渲染。默认显示顶部搜索栏，用户输入关键字后可以在命中结果之间上下跳转。
+
+```tsx
+import React from "react";
+import { LogView } from "@cloudtower/eagle";
+
+const logContent = [
+  "[2026-04-24 14:30:00.101] INFO node-01 bootstrap started",
+  "[2026-04-24 14:30:01.233] INFO node-01 loading cluster metadata",
+  "[2026-04-24 14:30:04.889] ERROR node-03 failed to fetch event payload",
+].join("\n");
+
+const App = () => <LogView content={logContent} rows={16} />;
+```
+
+## 常见模式
+
+### 模式一：关闭搜索栏
+
+适用于只需要纯日志视图，或外层页面已经提供统一搜索入口的场景。
+
+```tsx
+import React from "react";
+import { LogView } from "@cloudtower/eagle";
+
+const App = () => <LogView content={logContent} rows={12} showSearch={false} />;
+```
+
+### 模式二：实时追加日志
+
+如果外部已经通过接口轮询、WebSocket 或其他方式拿到增量日志，可以把日志拼接为新的 `content` 传入。组件会在新内容以前一次内容为前缀时只追加增量，避免整屏清空重绘。
+
+```tsx
+import React, { useEffect, useState } from "react";
+import { LogView } from "@cloudtower/eagle";
+
+const App = () => {
+  const [logs, setLogs] = useState<string[]>([]);
+
+  useEffect(() => {
+    const timer = window.setInterval(() => {
+      setLogs((prevLogs) => [
+        ...prevLogs,
+        `[${new Date().toISOString()}] INFO receive log chunk`,
+      ]);
+    }, 1000);
+
+    return () => window.clearInterval(timer);
+  }, []);
+
+  return (
+    <LogView
+      content={logs.length > 0 ? `${logs.join("\n")}\n` : ""}
+      rows={14}
+      scrollback={1000}
+    />
+  );
+};
+```
+
+### 模式三：接入 EventSource 日志流
+
+启用 `eventSource` 后，通过 `eventSourceOptions` 配置 SSE 地址、事件名、重连和消息格式化逻辑。`formatMessage` 应返回写入终端的字符串；组件会在缺少换行时自动补充 `\n`。
+
+```tsx
+import React from "react";
+import { LogView } from "@cloudtower/eagle";
+
+const App = () => (
+  <LogView
+    rows={18}
+    eventSource
+    eventSourceOptions={{
+      url: "/api/tasks/task-001/logs/stream",
+      reconnect: true,
+      reconnectWait: 3,
+      formatMessage: (message) => {
+        const data = JSON.parse(message);
+
+        return `[${data.time}] ${data.level} ${data.content}`;
+      },
+      onError: (error) => {
+        console.error("日志流连接失败:", error);
+      },
+    }}
+  />
+);
+```
+
+### 模式四：自定义空状态和错误状态
+
+当没有 `content` 且未接收到日志数据时，可以通过 `emptyRenderer` 渲染空态。EventSource 连接报错时可以通过 `errorRenderer` 展示错误说明，并调用第三个参数 `reconnect` 触发重新连接。
+
+```tsx
+import React from "react";
+import { Button, LogView } from "@cloudtower/eagle";
+
+const App = () => (
+  <LogView
+    eventSource
+    eventSourceOptions={{
+      url: "/api/tasks/task-001/logs/stream",
+      reconnect: false,
+    }}
+    emptyRenderer={() => (
+      <div style={{ textAlign: "center" }}>等待日志输出...</div>
+    )}
+    errorRenderer={(_terminal, _error, reconnect) => (
+      <div style={{ textAlign: "center" }}>
+        <div>日志流连接失败</div>
+        <Button type="primary" onClick={reconnect}>
+          重新连接
+        </Button>
+      </div>
+    )}
+  />
+);
+```
+
+### 模式五：大日志量搜索优化
+
+日志量较大时，建议限制 `searchHighlightLimit`，并适当调大搜索框防抖时间，避免一次性高亮过多命中结果导致页面卡顿。
+
+```tsx
+import React from "react";
+import { LogView } from "@cloudtower/eagle";
+
+const App = () => (
+  <LogView
+    content={largeLogContent}
+    rows={18}
+    scrollback={100000}
+    searchHighlightLimit={1000}
+    searchInputProps={{
+      debounceWait: 400,
+      placeholder: "搜索日志关键字",
+    }}
+  />
+);
+```
+
+### 模式六：键盘快捷键
+
+LogView 默认接管终端区域内的翻页、复制和全选快捷键，以匹配日志查看体验。外层页面需要统一处理键盘行为时，可以关闭 `enableKeyboardShortcuts`。
+
+```tsx
+import React from "react";
+import { LogView } from "@cloudtower/eagle";
+
+const App = () => (
+  <LogView content={logContent} enableKeyboardShortcuts={false} />
+);
+```
+
+## 注意事项
+
+- `content` 适合静态日志或外部已合并好的实时日志；直接使用 SSE 时优先配置 `eventSource` 和 `eventSourceOptions`。
+- 大日志量场景下同时设置 `scrollback` 和 `searchHighlightLimit`，避免无限保留历史行和过多搜索高亮带来的性能问题。
+- `searchInputProps` 会覆盖内置搜索框属性，修改 `onChange`、`onSearchNext` 或 `onSearchPrev` 时要确认不会破坏日志搜索导航。
+- `emptyRenderer` 和 `errorRenderer` 会覆盖在终端上方，适合展示轻量提示和操作入口，不建议放置复杂表单。
+
+## 相关组件
+
+- `SearchInput`：LogView 顶部搜索栏基于 SearchInput 封装
+- `Table`：展示结构化日志列表或审计事件时使用
+- `Alert`：展示短提示、告警或错误说明时使用

package/docs/llms.txt

@@ -55,6 +55,7 @@ npm 包名：@cloudtower/eagle
 ## 数据展示
 
 - [Table](core/Table/guide.md): 表格组件，基于 antd Table 二次封装，支持排序、行选择、展开行、加载/错误状态
+- [LogView](core/LogView/guide.md): 日志查看器，基于 xterm 封装，支持静态日志、EventSource 流式日志、搜索导航和滚动缓冲控制
 - Tab: 标签页，封装 antd Tabs
 - Collapse: 折叠面板（继承 antd Collapse）
 - Tag: 标签，支持多种预设颜色
@@ -97,7 +98,8 @@ npm 包名：@cloudtower/eagle
 - Icon: 图标容器，统一图标尺寸和样式
 - BaseIcon: 基础图标，支持 SVG 图标渲染
 - Link: 链接，封装 antd Typography.Link
-- Typo: 排版样式集合，提供 Display/Heading/Label/Paragraph 等预定义的 Linaria 类名
+- Typo: 排版样式集合，提供 Display/Heading/Label/Paragraph 等预定义的 Linaria 类名；若需要根据 Figma Typography 名称查找对应样式，请使用公开导出的 `FIGMA_TO_TYPO`
+- Color: 颜色 token；若目标文件已依赖全局 Sass 变量或已有 `$...` 写法，优先使用 `dist/variables.scss` 中的 Sass 变量，否则优先使用公开导出的 `Color.*`
 - Loading: 加载中动画，三条竖线动画
 - CircleLoading: 圆形加载动画，旋转渐变圆形图标
 - Space: 间距组件，封装 antd Space

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudtower/eagle",
-  "version": "4100.0.1",
+  "version": "4100.0.3",
   "main": "dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "dist/src/index.d.ts",
@@ -24,18 +24,25 @@
     "typings": "tsc --emitDeclarationOnly && tsc-alias",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
-    "sync:color": "node tools/fetch-figma-color.js"
+    "check:color": "node tools/sync-figma-color.js --check",
+    "sync:color": "node tools/sync-figma-color.js --write",
+    "check:typography": "node tools/sync-figma-typography.js --check",
+    "sync:typography": "node tools/sync-figma-typography.js --write"
   },
   "dependencies": {
-    "@cloudtower/icons-react": "^4100.0.1",
-    "@cloudtower/parrot": "^4100.0.1",
+    "@cloudtower/icons-react": "^4100.0.3",
+    "@cloudtower/parrot": "^4100.0.3",
     "@cloudtower/rc-notification": "^4.6.1",
     "@linaria/core": "^4.2.2",
     "@linaria/react": "^4.3.0",
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/addon-search": "^0.15.0",
+    "@xterm/xterm": "^5.5.0",
     "antd": "4.5.0",
     "antd5": "npm:antd@5.14.0",
     "classnames": "2.3.2",
     "dayjs": "^1.11.10",
+    "eventsource": "^3.0.5",
     "react-beautiful-dnd": "^13.0.0",
     "react-copy-to-clipboard": "^5.1.0",
     "react-highlight-words": "^0.17.0",
@@ -79,8 +86,10 @@
     "@types/react-highlight-words": "^0.16.7",
     "@types/react-is": "^17.0.3",
     "@types/react-transition-group": "4.2.4",
+    "@types/xterm": "^3.0.0",
     "@vitejs/plugin-react": "^4.2.1",
     "copy-to-clipboard": "^3.3.3",
+    "dotenv": "^16.4.7",
     "history": "^4.9.0",
     "i18next": "^23.2.3",
     "jsdom": "^20.0.1",
@@ -116,5 +125,5 @@
     "vite": "^4.5.1",
     "vitest": "^3.1.1"
   },
-  "gitHead": "012a843c24a93ffc2ffe964b57cb9e545040a59c"
+  "gitHead": "a8964b044e5339e8122bf19f8b010f36e2ae7b16"
 }