@yumiai/chat-widget 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.1] - 2025-03-17
+
+### Fixed
+
+- **子 Agent 状态与 notification_turns 对齐**：子 Agent 卡片的「已完成」改为优先依据后端下发的 `agent_end` 通知（与 jetagents notification_turns 的 agent start/stop 一致），不再仅凭「已有文字」误判为已停止；未收到 `agent_end` 时仍回退为「有内容且无进行中工具」则已完成。
+- 聚合器新增对 `agent_end` 的处理与每轮 `endedAgentInstanceIds` 的维护，Round 与 ChildAgentCard 支持 `endedAgentInstanceIds` 用于展示状态。

package/README.md

@@ -0,0 +1,187 @@
+# @yumiai/chat-widget
+
+Agent 对话 UI 组件 — 为 AI Agent 系统提供开箱即用的聊天界面。
+
+## 特性
+
+- **SSE 实时流式渲染** — POST-based Server-Sent Events，支持认证、自动重连
+- **Streamdown Markdown** — 代码高亮、Mermaid 图表、LaTeX 数学公式、CJK 排版优化
+- **多轮对话管理** — 轮次分隔、清屏滚动、动态置顶（带防抖与滞后阈值）
+- **子 Agent 嵌套** — 折叠式子 Agent 卡片，支持 `call_agent` 工具链路可视化
+- **工具调用卡片** — MCP 工具生命周期（生成 → 执行 → 完成），buffering 动画
+- **Todo/Checklist** — 实时任务进度面板，按 Phase → Group → Task 三级结构展示
+- **HITL 表单** — Human-in-the-Loop 交互，支持 JSON Schema / HTML Schema 动态表单
+- **产出物查看器** — 文件 Artifact 点击预览，支持文本/二进制类型识别
+- **打字机效果** — 基于 `requestAnimationFrame` 的逐字展开，自动对齐 Markdown 安全边界
+- **主题支持** — `light` / `dark` / `auto` 三种主题，CSS 变量驱动
+- **Adapter 模式** — 认证、API 地址、Token 刷新完全由消费方注入，零耦合
+
+## 安装
+
+```bash
+npm install @yumiai/chat-widget
+```
+
+**Peer Dependencies:**
+
+```json
+{
+  "react": "^18.0.0 || ^19.0.0",
+  "react-dom": "^18.0.0 || ^19.0.0",
+  "antd": "^5.0.0 || ^6.0.0"
+}
+```
+
+## 快速开始
+
+```tsx
+import { ChatWidget, DefaultJetAgentsAdapter } from '@yumiai/chat-widget'
+import '@yumiai/chat-widget/style.css'
+
+const adapter = new DefaultJetAgentsAdapter({
+  baseUrl: 'https://your-jetagents-server.com',
+  getToken: () => localStorage.getItem('access_token'),
+  refreshToken: async () => {
+    const res = await fetch('/api/auth/refresh', { method: 'POST' })
+    const { token } = await res.json()
+    localStorage.setItem('access_token', token)
+    return token
+  },
+  onAuthFailure: () => window.location.href = '/login',
+})
+
+function App() {
+  return (
+    <ChatWidget
+      adapter={adapter}
+      sessionId={123}
+      config={{
+        theme: 'light',
+        showPinnedArea: true,
+        enableTypewriter: true,
+        typewriterSpeed: 30,
+        displayLevels: [0, 1, 2],
+      }}
+      onReady={(api) => console.log('Widget ready', api)}
+      onError={(err) => console.error(err)}
+      height="100vh"
+      renderFooter={(api) => (
+        <input
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' && api) {
+              api.sendMessage(e.currentTarget.value, 'agent-666')
+              e.currentTarget.value = ''
+            }
+          }}
+          placeholder="输入消息..."
+        />
+      )}
+    />
+  )
+}
+```
+
+## 自定义 Adapter
+
+`DefaultJetAgentsAdapter` 适配 JetAgents 后端 API。对于其他后端系统，实现 `ChatWidgetAdapter` 接口即可：
+
+```tsx
+import type { ChatWidgetAdapter } from '@yumiai/chat-widget'
+
+class MyAdapter implements ChatWidgetAdapter {
+  async createSession(agentId: string) { /* ... */ }
+  async getSessionDetail(sessionId: number) { /* ... */ }
+  async getSessionHistory(sessionId: number) { /* ... */ }
+  async getResourceContent(sessionId: number, resourceId: string) { /* ... */ }
+  async submitHITLResponse(response) { /* ... */ }
+  getStreamUrl(): string { return '/api/stream' }
+  getAuthHeaders(): Record<string, string> { return {} }
+}
+```
+
+详细接口定义见 [docs/02-adapter-interface.md](docs/02-adapter-interface.md)。
+
+## API 参考
+
+### ChatWidgetProps
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `adapter` | `ChatWidgetAdapter` | **必填** | 后端适配器实例 |
+| `sessionId` | `string \| number` | — | 会话 ID，传入后自动加载历史 |
+| `config` | `ChatWidgetConfig` | `DEFAULT_CONFIG` | UI 配置 |
+| `renderHeaderExtra` | `(sessionId) => ReactNode` | — | 头部右侧额外内容插槽 |
+| `renderFooter` | `(api) => ReactNode` | — | 底部输入区插槽 |
+| `onReady` | `(api: ChatWidgetAPI) => void` | — | Widget 就绪回调 |
+| `onArtifactClick` | `(artifact: Artifact) => void` | — | 产出物点击回调 |
+| `onHITLSubmit` | `(response) => Promise<void>` | — | HITL 表单提交回调 |
+| `onStatusChange` | `(status: ExecutionStatus) => void` | — | 执行状态变化回调 |
+| `onError` | `(error: Error) => void` | — | 错误回调 |
+| `height` | `number \| string` | `600` | 容器高度 |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | 主题 |
+
+### ChatWidgetAPI
+
+通过 `onReady` 或 `renderFooter` 获取的 API 对象：
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `sendMessage` | `(message: string, agentId?: string) => void` | 发送消息并建立 SSE 连接 |
+| `getCurrentRound` | `() => Round \| null` | 获取当前轮次 |
+| `getAllRounds` | `() => Round[]` | 获取全部轮次 |
+| `scrollToBottom` | `() => void` | 滚动到底部 |
+| `getStatus` | `() => ExecutionStatus` | 获取执行状态 |
+
+## 构建
+
+```bash
+npm run build       # 生产构建（ESM + CJS + DTS）
+npm run dev         # 开发模式（watch）
+npm run test        # 运行测试
+npm run typecheck   # TypeScript 类型检查
+```
+
+## 发布
+
+```bash
+# 确保 .npmrc 中配置了 npm token
+npm version patch   # 升版本
+npm publish --access public
+```
+
+## 目录结构
+
+```
+chat-widget/
+├── src/
+│   ├── index.ts                    # 公共导出
+│   ├── types.ts                    # 类型定义
+│   ├── errors.ts                   # 错误类型
+│   ├── ChatWidget.tsx              # 主组件
+│   ├── ChatWidget.css              # 主样式
+│   ├── hooks/
+│   │   ├── useSSE.ts               # SSE 连接 Hook
+│   │   └── useMessageAggregator.ts # 消息聚合 Hook
+│   ├── adapters/
+│   │   ├── ChatWidgetAdapter.ts    # Adapter 接口
+│   │   └── DefaultJetAgentsAdapter.ts # JetAgents 默认适配器
+│   └── components/
+│       ├── PinnedArea.tsx          # 置顶区域
+│       ├── RoundHeader.tsx         # 轮次标题
+│       ├── MessageContent.tsx      # 消息内容渲染
+│       ├── ChildAgentCard.tsx      # 子 Agent 卡片
+│       ├── ToolCardBuffering.tsx   # 工具调用卡片
+│       ├── TodoCard.tsx            # Todo 进度面板
+│       ├── PlanCard.tsx            # 计划面板
+│       ├── SchemaFormRenderer.tsx  # HITL 表单渲染器
+│       └── renderers/              # 工具结果渲染器
+├── tests/                          # 集成测试
+├── docs/                           # 设计文档
+├── tsup.config.ts                  # 构建配置
+├── vitest.config.ts                # 测试配置
+└── package.json
+```
+
+## License
+
+Proprietary — YumiAI

package/dist/index.cjs

@@ -107,7 +107,8 @@ function extractTaskPurposeFromPreview(preview) {
 function useMessageAggregator() {
   const [state, setState] = (0, import_react.useState)({
     rounds: /* @__PURE__ */ new Map(),
-    currentInteractionId: null
+    currentInteractionId: null,
+    endedAgentInstanceIdsByRound: /* @__PURE__ */ new Map()
   });
   const [todoMap, setTodoMap] = (0, import_react.useState)(/* @__PURE__ */ new Map());
   const todoMapRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
@@ -117,6 +118,7 @@ function useMessageAggregator() {
   const roundIndexRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
   const processedChunksRef = (0, import_react.useRef)(/* @__PURE__ */ new Set());
   const callBatchToRoundRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
+  const endedAgentInstanceIdsByRoundRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
   const parsePlan = (0, import_react.useCallback)((content) => {
     try {
       const parsed = JSON.parse(content);
@@ -258,6 +260,18 @@ function useMessageAggregator() {
       } else if (!existingRoundForBatch) {
         callBatchToRoundRef.current.set(call_batch_id, interaction_id);
       }
+      if (msg.notification_type === "agent_end") {
+        const iid = interaction_id;
+        const aid = msg.agent_instance_id;
+        if (iid != null && aid != null) {
+          const prev = endedAgentInstanceIdsByRoundRef.current;
+          const set = new Set(prev.get(iid) || []);
+          set.add(aid);
+          endedAgentInstanceIdsByRoundRef.current = new Map(prev).set(iid, set);
+        }
+        latestInteractionId = interaction_id;
+        continue;
+      }
       let round = roundIndexRef.current.get(interaction_id);
       if (!round) {
         round = {
@@ -405,9 +419,14 @@ function useMessageAggregator() {
     }
     setState(() => {
       const newRounds = new Map(roundIndexRef.current);
+      const endedByRound = endedAgentInstanceIdsByRoundRef.current;
+      const endedAgentInstanceIdsByRound = new Map(
+        [...endedByRound.entries()].map(([k, v]) => [k, new Set(v)])
+      );
       return {
         rounds: newRounds,
-        currentInteractionId: latestInteractionId
+        currentInteractionId: latestInteractionId,
+        endedAgentInstanceIdsByRound
       };
     });
     if (todoMapChanged) {
@@ -422,8 +441,12 @@ function useMessageAggregator() {
     }
   }, [flushUpdates]);
   const getRoundsList = (0, import_react.useCallback)(() => {
-    return Array.from(state.rounds.values()).sort((a, b) => a.index - b.index);
-  }, [state.rounds]);
+    const endedByRound = state.endedAgentInstanceIdsByRound;
+    return Array.from(state.rounds.values()).map((r) => ({
+      ...r,
+      endedAgentInstanceIds: endedByRound.get(r.interactionId) || /* @__PURE__ */ new Set()
+    })).sort((a, b) => a.index - b.index);
+  }, [state.rounds, state.endedAgentInstanceIdsByRound]);
   const getCurrentRound = (0, import_react.useCallback)(() => {
     if (!state.currentInteractionId) return null;
     return state.rounds.get(state.currentInteractionId) || null;
@@ -443,7 +466,8 @@ function useMessageAggregator() {
       newRounds.set(interactionId, round);
       return {
         rounds: newRounds,
-        currentInteractionId: interactionId
+        currentInteractionId: interactionId,
+        endedAgentInstanceIdsByRound: prevState.endedAgentInstanceIdsByRound
       };
     });
   }, []);
@@ -452,6 +476,7 @@ function useMessageAggregator() {
     messageIndexRef.current.clear();
     callBatchToRoundRef.current.clear();
     processedChunksRef.current.clear();
+    endedAgentInstanceIdsByRoundRef.current.clear();
     const newRounds = /* @__PURE__ */ new Map();
     for (const round of rounds) {
       newRounds.set(round.interactionId, round);
@@ -464,7 +489,7 @@ function useMessageAggregator() {
       }
     }
     const lastId = rounds.length > 0 ? rounds[rounds.length - 1].interactionId : null;
-    setState({ rounds: newRounds, currentInteractionId: lastId });
+    setState({ rounds: newRounds, currentInteractionId: lastId, endedAgentInstanceIdsByRound: /* @__PURE__ */ new Map() });
   }, []);
   const finalizeRound = (0, import_react.useCallback)((interactionId) => {
     const round = roundIndexRef.current.get(interactionId);
@@ -480,9 +505,11 @@ function useMessageAggregator() {
       }
     }
     if (changed) {
+      const endedByRound = endedAgentInstanceIdsByRoundRef.current;
       setState(() => ({
         rounds: new Map(roundIndexRef.current),
-        currentInteractionId: interactionId
+        currentInteractionId: interactionId,
+        endedAgentInstanceIdsByRound: new Map([...endedByRound.entries()].map(([k, v]) => [k, new Set(v)]))
       }));
     }
   }, []);
@@ -492,6 +519,7 @@ function useMessageAggregator() {
     roundIndexRef.current.clear();
     processedChunksRef.current.clear();
     callBatchToRoundRef.current.clear();
+    endedAgentInstanceIdsByRoundRef.current.clear();
     todoMapRef.current.clear();
     if (rafId.current) {
       cancelAnimationFrame(rafId.current);
@@ -499,7 +527,8 @@ function useMessageAggregator() {
     }
     setState({
       rounds: /* @__PURE__ */ new Map(),
-      currentInteractionId: null
+      currentInteractionId: null,
+      endedAgentInstanceIdsByRound: /* @__PURE__ */ new Map()
     });
     setTodoMap(/* @__PURE__ */ new Map());
   }, []);
@@ -2280,14 +2309,20 @@ var ChildAgentCard = ({
   config,
   onArtifactClick,
   defaultExpanded = false,
-  parentTaskPurpose
+  parentTaskPurpose,
+  endedAgentInstanceIds
 }) => {
   const [isExpanded, setIsExpanded] = (0, import_react20.useState)(defaultExpanded);
   const contentRef = (0, import_react20.useRef)(null);
-  const hasActiveContent = children.some(
+  const allMessages = (0, import_react20.useMemo)(() => [message, ...children], [message, children]);
+  const hasExplicitEnd = endedAgentInstanceIds != null && endedAgentInstanceIds.has(message.agentInstanceId);
+  const hasActiveContent = allMessages.some(
     (m) => m.contentType === "text" && m.contentChunks.join("").trim()
   );
-  const status = hasActiveContent ? "completed" : "running";
+  const hasInProgressTool = allMessages.some(
+    (m) => m.toolPhase === "generating" || m.toolPhase === "executing"
+  );
+  const status = hasExplicitEnd ? "completed" : hasActiveContent && !hasInProgressTool ? "completed" : "running";
   (0, import_react20.useEffect)(() => {
     if (isExpanded && contentRef.current) {
       contentRef.current.scrollTop = contentRef.current.scrollHeight;
@@ -2763,7 +2798,8 @@ var ChatWidget = ({
                   config,
                   onArtifactClick: handleArtifactClick,
                   defaultExpanded: true,
-                  parentTaskPurpose: msg.taskPurpose
+                  parentTaskPurpose: msg.taskPurpose,
+                  endedAgentInstanceIds: round.endedAgentInstanceIds
                 },
                 `child-${childKey}-${agentInstanceId}`
               )