@malette/agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,404 @@
+# @malette/agent-sdk
+
+Agent SDK for Malette - Complete agent conversation capabilities
+
+## 介绍
+
+`@malette/agent-sdk` 是一个专注于 **Agent 对话交互** 的端到端 SDK，提供了完整的会话管理、消息流式传输、工具确认、Plan Mode 等对话相关功能。
+
+### 设计边界
+
+**SDK 包含：**
+- ✅ 会话管理（创建、列表、消息历史）
+- ✅ 消息发送与流式传输（SSE）
+- ✅ 工具确认与批量确认
+- ✅ Plan Mode（计划生成、确认、执行、人工输入）
+- ✅ Multi-Agent 思考过程展示
+- ✅ 文件上传与媒体处理
+- ✅ 会话分享与回放
+- ✅ 完整的 UI 组件（ChatWindow, MessageBubble 等）
+
+**SDK 不包含：**
+- ❌ Agent CRUD（创建、更新、删除 Agent）
+- ❌ Tool CRUD（创建、更新、删除工具）
+- ❌ Agent-Tool 绑定管理
+
+> **设计决策**：Agent/Tool 管理属于配置层面，对话交互属于运行时层面。将两者分离可以让 SDK 更专注于对话体验，同时保持灵活性。
+
+## 安装
+
+```bash
+npm install @malette/agent-sdk
+```
+
+## 快速开始
+
+### 1. 使用通用 AgentChat 组件（推荐）
+
+最简单的方式是直接使用 `AgentChat` 组件，它包含了完整的会话管理、对话、分享和回放功能：
+
+```tsx
+'use client';
+
+import { AgentChat } from '@malette/agent-sdk';
+
+export default function AgentPage() {
+  return (
+    <AgentChat
+      agentId="your-agent-id"
+      projectId="your-project-id"
+      agentName="我的 Agent"
+      agentType="BUILTIN"
+      welcomeMessage="你好！我是你的 AI 助手"
+      tools={[]}
+      onNavigateBack={() => window.history.back()}
+      onNavigateToSettings={() => window.location.href = '/settings'}
+      onNavigateToReplay={(sessionId) => {
+        window.location.href = `/replay?sessionId=${sessionId}`;
+      }}
+    />
+  );
+}
+```
+
+### 2. 使用 ShareReplayPage 组件
+
+用于分享回放页面：
+
+```tsx
+'use client';
+
+import { ShareReplayPage } from '@malette/agent-sdk';
+
+export default function SharePage({ params }: { params: { shareId: string } }) {
+  return (
+    <ShareReplayPage
+      shareId={params.shareId}
+      onNavigateBack={() => window.history.back()}
+    />
+  );
+}
+```
+
+### 3. 基础对话
+
+如果你需要更细粒度的控制，可以使用底层组件和服务：
+
+```tsx
+'use client';
+
+import {
+  useAgentStore,
+  sessionService,
+  messageService,
+  useSSE,
+  ChatWindow,
+  createAndStartSession
+} from '@malette/agent-sdk';
+
+export default function Playground() {
+  const { currentSession, setCurrentSession, addSession } = useAgentStore();
+  const { sendMessage } = useSSE();
+
+  // 创建会话
+  const handleNew = async () => {
+    const session = await createAndStartSession(projectId, agentId, '新对话');
+    if (session) {
+      addSession(session);
+      setCurrentSession(session);
+    }
+  };
+
+  // 发送消息
+  const handleSend = async (content: string) => {
+    if (currentSession) {
+      await sendMessage(currentSession.sessionId, content);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleNew}>新建对话</button>
+      {currentSession && (
+        <ChatWindow sessionId={currentSession.sessionId} />
+      )}
+    </div>
+  );
+}
+```
+
+### 2. 使用组件
+
+```tsx
+import {
+  ChatWindow,
+  MessageBubble,
+  ToolConfirmDialog,
+  PlanConfirmDialog,
+  ShareModal
+} from '@malette/agent-sdk';
+
+// 完整的对话窗口
+<ChatWindow sessionId="xxx" />
+
+// 单个消息气泡
+<MessageBubble message={message} isStreaming={false} />
+
+// 工具确认弹窗
+<ToolConfirmDialog
+  open={showConfirm}
+  onConfirm={handleConfirm}
+  onCancel={handleCancel}
+/>
+
+// Plan 确认弹窗
+<PlanConfirmDialog
+  plan={currentPlan}
+  onConfirm={handlePlanConfirm}
+  onReject={handlePlanReject}
+/>
+
+// 分享弹窗
+<ShareModal
+  sessionId="xxx"
+  isOpen={shareOpen}
+  onClose={() => setShareOpen(false)}
+/>
+```
+
+### 3. 文件上传
+
+```tsx
+import { uploadOSS, getFileUrl, getImageUrl } from '@malette/agent-sdk';
+
+// 上传文件到 OSS
+const handleUpload = async (file: File) => {
+  const result = await uploadOSS(file);
+  const url = await getFileUrl(result.key);
+  console.log('文件 URL:', url);
+};
+
+// 获取图片缩略图
+const imageUrl = getImageUrl('file-key');
+```
+
+## API 概览
+
+### 服务层
+
+#### Session 服务
+```typescript
+sessionService.create(data)           // 创建会话
+sessionService.get(sessionId)         // 获取会话详情
+sessionService.update(sessionId, data) // 更新会话
+sessionService.delete(sessionId)      // 删除会话
+sessionService.list(params)           // 获取会话列表
+sessionService.getMessages(sessionId, params) // 获取消息列表
+sessionService.updateTitle(sessionId, title) // 更新会话标题
+```
+
+#### Message 服务
+```typescript
+messageService.send(data)             // 发送消息（非流式）
+messageService.sendStream(data)       // 发送消息（流式 SSE）
+messageService.getThoughtsStream(messageId) // 获取思考过程流
+messageService.cancel(messageId)      // 取消消息执行
+messageService.getDetail(messageId)   // 获取消息详情
+messageService.delete(messageId)      // 删除消息
+```
+
+#### Tool Call 服务
+```typescript
+toolCallService.confirm(data)         // 确认/拒绝工具调用
+toolCallService.confirmBatch(ids, approved) // 批量确认
+toolCallService.getPending(toolCallId) // 获取待确认的工具调用
+```
+
+#### Plan 服务
+```typescript
+planService.confirm(planId, data)     // 确认/拒绝计划
+planService.provideHumanInput(planId, stepId, data) // 提供人工输入
+planService.pause(planId)             // 暂停计划
+planService.resume(planId)            // 恢复计划
+planService.cancel(planId)            // 取消计划
+planService.retry(planId)             // 重试失败步骤
+planService.skip(planId)              // 跳过失败步骤
+planService.getDetail(planId)         // 获取计划详情
+planService.getStatus(planId)         // 获取计划状态
+```
+
+#### Share 服务
+```typescript
+shareService.create(data)             // 创建分享
+shareService.get(shareId)             // 获取分享信息
+shareService.update(data)             // 更新分享
+shareService.delete(shareId)          // 删除分享
+shareService.listMy()                 // 获取我的分享列表
+shareService.listBySession(sessionId) // 获取会话的分享列表
+shareService.getPublicContent(shareId, token) // 获取公开分享内容
+shareService.isPasswordRequired(shareId) // 检查是否需要密码
+shareService.verifyPassword(data)     // 验证分享密码
+shareService.isValid(shareId)         // 检查分享是否有效
+```
+
+#### 便捷方法
+```typescript
+createAndStartSession(projectId, agentId, title) // 快速创建并进入会话
+getSessionWithMessages(sessionId, params) // 获取会话及其消息历史
+confirmAllPendingToolCalls(toolCallIds) // 确认所有待确认的工具调用
+rejectAllPendingToolCalls(toolCallIds, reason) // 拒绝所有待确认的工具调用
+generateSessionTitle(userMessage, assistantMessage) // 生成会话标题
+```
+
+### Store 管理
+
+```typescript
+// 会话状态
+useSessions()           // 获取会话列表
+useCurrentSession()     // 获取当前会话
+useSessionsLoading()    // 获取加载状态
+
+// 消息状态
+useMessages()           // 获取所有消息
+useCurrentThoughts()    // 获取当前思考过程
+usePendingToolCalls()   // 获取待确认的工具调用
+
+// Chat UI 状态
+useIsStreaming()        // 是否正在流式输出
+useIsThinking()         // 是否正在思考
+useStreamingContent()   // 流式内容
+useChatError()          // 聊天错误信息
+
+// Plan Mode 状态
+useChatUI().currentPlan           // 当前计划
+useChatUI().showPlanConfirmDialog // 是否显示计划确认弹窗
+useChatUI().showHumanInputDialog  // 是否显示人工输入弹窗
+
+// 工具函数
+findMessageById(messageId)        // 根据 ID 查找消息
+findSessionById(sessionId)        // 根据 ID 查找会话
+hasPendingToolCalls()             // 检查是否有待确认的工具调用
+isConversationActive()            // 检查是否正在进行对话
+```
+
+### Hooks
+
+```typescript
+// SSE 流式传输
+const { sendMessage, reconnect, abort, isConnected } = useSSE({
+  onComplete: (content) => { /* 消息完成回调 */ }
+});
+
+// SSE 连接状态
+const { isConnected, connect, disconnect } = useSSEConnection();
+```
+
+### 组件
+
+| 组件 | 说明 |
+|------|------|
+| `AgentChat` | **通用对话组件** - 包含完整的会话管理、对话、分享功能（推荐使用） |
+| `ShareReplayPage` | **分享回放页面** - 用于公开分享的回放功能 |
+| `ChatWindow` | 完整的对话窗口组件 |
+| `MessageBubble` | 消息气泡组件 |
+| `MessageImage` | 图片渲染组件 |
+| `MessageVideo` | 视频渲染组件 |
+| `ImagePreview` | 图片预览弹窗 |
+| `ThinkingProcess` | 思考过程展示组件 |
+| `MultiAgentThoughts` | Multi-Agent 思考时间线 |
+| `ToolConfirmDialog` | 工具确认弹窗 |
+| `ToolConfirmCard` | 工具确认卡片 |
+| `PlanCard` | Plan 步骤卡片 |
+| `PlanConfirmDialog` | Plan 确认弹窗 |
+| `PlanProgressPanel` | Plan 进度面板 |
+| `HumanInputDialog` | 人工输入弹窗 |
+| `ShareModal` | **分享弹窗** - 用于创建和管理分享 |
+| `ParameterDisplay` | 参数展示组件 |
+| `StreamingJsonDisplay` | 流式 JSON 展示 |
+
+## 类型定义
+
+SDK 提供了完整的 TypeScript 类型支持：
+
+```typescript
+import type {
+  AgentSession,
+  AgentMessage,
+  AgentThought,
+  ToolCall,
+  ExecutionPlan,
+  PlanStep,
+  ChatUIState,
+  // ... 更多类型
+} from '@malette/agent-sdk';
+```
+
+## 文件服务
+
+```typescript
+import {
+  uploadOSS,
+  getFileUrl,
+  getImageUrl,
+  getHDImageUrl,
+  resolveMediaUrl,
+  embedding
+} from '@malette/agent-sdk';
+
+// 上传文件
+const result = await uploadOSS(file, (progress) => {
+  console.log('上传进度:', progress.percent);
+});
+
+// 获取文件/图片 URL
+const fileUrl = await getFileUrl('file-key');
+const imageUrl = getImageUrl('image-key');
+const hdUrl = getHDImageUrl('image-key');
+
+// 解析媒体 URL
+const { url, hdUrl, isVideo } = resolveMediaUrl({ fileId: 'xxx' });
+
+// 图片 embedding
+const embeddingData = await embedding('image-path');
+```
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式（watch）
+npm run dev
+
+# 构建
+npm run build
+
+# 清理
+npm run clean
+```
+
+## 依赖
+
+```json
+{
+  "dependencies": {
+    "zustand": "^5.0.2",
+    "js-cookie": "^3.0.5",
+    "ali-oss": "^6.18.0"
+  },
+  "peerDependencies": {
+    "react": "^18",
+    "react-dom": "^18",
+    "antd": "^5.0.0",
+    "lucide-react": "^0.453.0",
+    "react-markdown": "^10.0.0",
+    "marked": "^15.0.0",
+    "highlight.js": "^11.0.0"
+  }
+}
+```
+
+## 许可证
+
+MIT