@axiom-lattice/gateway 1.0.46 → 2.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/gateway@1.0.12 build /home/runner/work/agentic/agentic/packages/gateway
+> @axiom-lattice/gateway@2.0.0 build /home/runner/work/agentic/agentic/packages/gateway
 > tsup src/index.ts --format cjs,esm --dts --clean --sourcemap
 
 CLI Building entry: src/index.ts
@@ -9,13 +9,13 @@
 CLI Cleaning output folder
 CJS Build start
 ESM Build start
-CJS dist/index.js     24.48 KB
-CJS dist/index.js.map 49.67 KB
-CJS ⚡️ Build success in 72ms
-ESM dist/index.mjs     22.38 KB
-ESM dist/index.mjs.map 49.53 KB
-ESM ⚡️ Build success in 72ms
+ESM dist/index.mjs     23.98 KB
+ESM dist/index.mjs.map 51.37 KB
+ESM ⚡️ Build success in 87ms
+CJS dist/index.js     26.07 KB
+CJS dist/index.js.map 51.45 KB
+CJS ⚡️ Build success in 88ms
 DTS Build start
-DTS ⚡️ Build success in 6015ms
+DTS ⚡️ Build success in 6652ms
 DTS dist/index.d.ts  1.97 KB
 DTS dist/index.d.mts 1.97 KB

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @axiom-lattice/gateway
+
+## 2.0.0
+
+### Major Changes
+
+- dbfac55: streaming 断开续传
+
+### Patch Changes
+
+- Updated dependencies [dbfac55]
+  - @axiom-lattice/protocols@2.0.0
+  - @axiom-lattice/core@2.0.0

package/RESUME_STREAM_CONTENT_BASED.md

@@ -0,0 +1,326 @@
+# Content-Based Resume Stream
+
+## 概述 (Overview)
+
+**重要更新**: `resume_stream` 现在基于**内容匹配**而不是长度匹配。
+
+这是一个更实用的设计，因为在实际应用中，用户通常只能获取到已接收的**内容本身**，而不知道精确的字节长度。
+
+## 为什么要改变？(Why the Change?)
+
+### 之前的问题 (Previous Issues)
+
+使用 `known_content_length` 的问题：
+
+1. **内容处理**: 前端显示的内容可能经过格式化、转义、HTML渲染等处理
+2. **字符编码**: 多字节字符（如中文、emoji）的长度计算不准确
+3. **数据存储**: 内容存储到数据库或localStorage后，可能有格式变化
+4. **不直观**: 用户需要手动计算和追踪字符长度
+
+```typescript
+// ❌ 之前：需要追踪长度
+const knownLength = 150;  // 怎么知道是150？需要手动计算
+await resume_stream({ 
+  thread_id, 
+  message_id, 
+  known_content_length: knownLength 
+});
+```
+
+### 现在的优势 (Current Advantages)
+
+使用 `known_content` 的优势：
+
+1. **直观简单**: 直接传入已接收的内容字符串
+2. **无需计算**: 不需要手动计算或追踪长度
+3. **可靠匹配**: 基于内容本身匹配，更准确
+4. **易于存储**: 内容可以直接从UI、state、localStorage获取
+
+```typescript
+// ✅ 现在：直接使用内容
+const knownContent = getContentFromUI();  // 或从localStorage读取
+await resume_stream({ 
+  thread_id, 
+  message_id, 
+  known_content: knownContent 
+});
+```
+
+## 匹配算法 (Matching Algorithm)
+
+`getNewChunksSinceContent` 使用智能匹配算法：
+
+### 1. 精确匹配 (Exact Match)
+```typescript
+// 累积内容完全等于已知内容
+if (accumulatedContent === knownContent) {
+  // 返回后续所有chunks
+}
+```
+
+### 2. 后缀匹配 (Suffix Match)
+```typescript
+// 已知内容是累积内容的后缀
+if (accumulatedContent.endsWith(knownContent)) {
+  // 返回后续所有chunks
+}
+```
+
+### 3. 前缀匹配 (Prefix Match)
+```typescript
+// 已知内容是累积内容的前缀
+if (accumulatedContent.startsWith(knownContent)) {
+  // 返回剩余部分
+  const remaining = accumulatedContent.substring(knownContent.length);
+  // 智能重构chunks
+}
+```
+
+### 4. 降级处理 (Fallback)
+```typescript
+// 如果没有匹配
+// 返回所有chunks（最安全的降级策略）
+return allChunks;
+```
+
+## 使用示例 (Usage Examples)
+
+### 基本使用 (Basic Usage)
+
+```typescript
+// 1. 用户刷新前收到了部分内容
+const receivedContent = "Hello world! This is a streaming response...";
+
+// 2. 页面刷新后，从localStorage恢复内容
+const savedContent = localStorage.getItem('chat_content');
+
+// 3. 继续接收新内容
+const stream = await resume_stream({
+  thread_id: 'thread-123',
+  message_id: 'msg-456',
+  known_content: savedContent || '',
+});
+
+for await (const chunk of stream) {
+  displayNewContent(chunk.content);
+}
+```
+
+### React 示例 (React Example)
+
+```typescript
+function ChatMessage({ threadId, messageId }) {
+  const [content, setContent] = useState('');
+  
+  useEffect(() => {
+    // 从localStorage恢复
+    const saved = localStorage.getItem(`message_${messageId}`);
+    if (saved) {
+      setContent(saved);
+      
+      // 继续接收新内容
+      (async () => {
+        const stream = await resume_stream({
+          thread_id: threadId,
+          message_id: messageId,
+          known_content: saved,
+        });
+        
+        for await (const chunk of stream) {
+          setContent(prev => prev + chunk.content);
+        }
+      })();
+    }
+  }, [threadId, messageId]);
+  
+  // 保存内容
+  useEffect(() => {
+    localStorage.setItem(`message_${messageId}`, content);
+  }, [content, messageId]);
+  
+  return <div>{content}</div>;
+}
+```
+
+### 错误处理 (Error Handling)
+
+```typescript
+async function resumeWithRetry(threadId, messageId, knownContent, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const stream = await resume_stream({
+        thread_id: threadId,
+        message_id: messageId,
+        known_content: knownContent,
+      });
+      
+      for await (const chunk of stream) {
+        yield chunk;
+      }
+      
+      return; // 成功
+    } catch (error) {
+      console.error(`Resume attempt ${i + 1} failed:`, error);
+      if (i === maxRetries - 1) throw error;
+      
+      // 等待后重试
+      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
+    }
+  }
+}
+```
+
+## API 变更 (API Changes)
+
+### Before (之前)
+
+```typescript
+interface ResumeStreamOptions {
+  thread_id: string;
+  message_id: string;
+  known_content_length: number;  // ❌ 需要长度
+  poll_interval?: number;
+}
+```
+
+### After (现在)
+
+```typescript
+interface ResumeStreamOptions {
+  thread_id: string;
+  message_id: string;
+  known_content: string;  // ✅ 直接用内容
+  poll_interval?: number;
+}
+```
+
+### ChunkBuffer API
+
+```typescript
+// Before (之前)
+getNewChunksSinceLength(
+  threadId: string,
+  messageId: string,
+  knownContentLength: number
+): Promise<Chunk[]>
+
+// After (现在)
+getNewChunksSinceContent(
+  threadId: string,
+  messageId: string,
+  knownContent: string
+): Promise<Chunk[]>
+```
+
+## 性能考虑 (Performance Considerations)
+
+### 时间复杂度 (Time Complexity)
+- **匹配**: O(n×m) 其中 n = chunks数量, m = 平均chunk长度
+- **实践中**: 通常很快，因为chunks数量通常不多（< 100）
+
+### 优化建议 (Optimization Tips)
+
+1. **限制内容长度**: 只传递最后的N个字符用于匹配
+```typescript
+const lastNChars = 1000; // 只用最后1000字符匹配
+const knownContent = fullContent.slice(-lastNChars);
+```
+
+2. **使用哈希**: 对于超长内容，可以考虑使用内容哈希
+```typescript
+// 未来可能的优化
+const contentHash = hashContent(knownContent);
+await resume_stream({ 
+  thread_id, 
+  message_id, 
+  known_content_hash: contentHash 
+});
+```
+
+## 注意事项 (Important Notes)
+
+### ✅ 优点 (Advantages)
+
+1. **用户友好**: 不需要追踪长度
+2. **更可靠**: 基于内容本身，不受编码影响
+3. **易于实现**: 前端代码更简单
+4. **灵活匹配**: 多种匹配策略
+
+### ⚠️ 限制 (Limitations)
+
+1. **精确匹配**: 内容必须完全匹配（包括空格、换行）
+2. **性能**: 对于超大内容可能需要优化
+3. **编码**: 必须使用相同的编码格式
+
+### 💡 最佳实践 (Best Practices)
+
+1. **保存原始内容**: 不要对内容进行格式化后再保存
+```typescript
+// ✅ 好
+const rawContent = chunks.join('');
+localStorage.setItem('content', rawContent);
+
+// ❌ 不好
+const formatted = formatContent(chunks.join(''));
+localStorage.setItem('content', formatted);
+```
+
+2. **检查状态**: 恢复前先检查thread状态
+```typescript
+const status = await get_thread_status(threadId);
+if (status.status === 'completed') {
+  // 已完成，获取完整内容
+  const fullContent = await get_accumulated_content(threadId);
+} else {
+  // 继续streaming
+  await resume_stream({ ... });
+}
+```
+
+3. **处理失败**: 如果匹配失败，fallback到完整内容
+```typescript
+const stream = await resume_stream({
+  thread_id: threadId,
+  message_id: messageId,
+  known_content: knownContent || '',  // 空字符串会返回所有内容
+});
+```
+
+## 迁移指南 (Migration Guide)
+
+如果你正在使用旧版本的 `resume_stream`：
+
+```typescript
+// 旧代码 (Old Code)
+const knownLength = currentContent.length;
+await resume_stream({
+  thread_id,
+  message_id,
+  known_content_length: knownLength  // ❌
+});
+
+// 新代码 (New Code)
+await resume_stream({
+  thread_id,
+  message_id,
+  known_content: currentContent  // ✅
+});
+```
+
+简单改动：删除 `.length`，直接传内容！
+
+## 总结 (Summary)
+
+这次改动让 `resume_stream` 更加：
+- ✅ **实用** (Practical): 符合实际使用场景
+- ✅ **简单** (Simple): API更直观易用
+- ✅ **可靠** (Reliable): 基于内容匹配更准确
+- ✅ **灵活** (Flexible): 多种匹配策略
+
+**核心理念**: 用户知道的是内容，而不是长度！
+
+
+
+
+
+