@bolloon/bolloon-agent 0.2.9 → 0.2.11

package/dist/llm/pi-ai.js

@@ -55,32 +55,23 @@ export class PiAIModel {
     /**
      * 与 LLM 对话.
      *
-     * 支持三种调用形式:
+     * 支持两种调用形式:
      *   - 旧: chat(message: string, context?: string, signal?)
      *       单一 user message + 附加 system context. 简单场景用.
      *   - 新: chat(messages: ChatMessage[], context?: string, signal?)
      *       完整 messages 数组, 含 user/assistant/tool/system role.
      *       工具调用场景必用 — 否则 LLM 看不到工具结果.
-     *   - pivot loop 兼容: chat(context: string, systemPrompt: string, signal?)
-     *       第二参超过 2K 时视为 system prompt 覆盖, 避免把 46K context 当 user message 发送.
      *
      * 2026-06-17 (M3.5 调试): buildContext() 之前把所有 history 序列化成单字符串,
      *   LLM 看不到 tool 调用的真实结果,导致 CLI loop 卡死.
      *   现在 messages 数组版本保留 role 语义, LLM 能正确看到工具返回.
      */
-    async chat(messageOrMessages, contextOrSystemPrompt, signal) {
-        const systemPrompt = await this.buildSystemPromptAsync(contextOrSystemPrompt);
+    async chat(messageOrMessages, context, signal) {
+        const systemPrompt = await this.buildSystemPromptAsync(context);
         let messages;
         if (Array.isArray(messageOrMessages)) {
             messages = [{ role: 'system', content: systemPrompt }, ...messageOrMessages];
         }
-        else if (contextOrSystemPrompt && contextOrSystemPrompt.length > 2000) {
-            const baseSystem = await this.buildSystemPromptAsync(undefined);
-            messages = [
-                { role: 'system', content: baseSystem + '\n\n' + contextOrSystemPrompt },
-                { role: 'user', content: messageOrMessages }
-            ];
-        }
         else {
             messages = [
                 { role: 'system', content: systemPrompt },
@@ -91,10 +82,10 @@ export class PiAIModel {
             const response = await this.generateText({
                 messages,
                 temperature: 0.8,
-                maxTokens: 16384, // 2026-06-17: 提到 16384 — agent 注入 16K+ system prompt + 8K tool defs 时, 8K 撞上限返回空 content (见 memory: bolloon-llm-empty-large-prompt)
+                maxTokens: 8192, // 2026-06-15: 提到 8192, 避免长回答 (含表格/代码块) 被截断
                 signal,
             });
-            return { reply: response.reply, toolCalls: response.toolCalls };
+            return { reply: response };
         }
         catch (error) {
             // abort 不当作错误, 透传一个 sentinel 让上层能识别
@@ -122,8 +113,8 @@ export class PiAIModel {
                 ],
                 temperature: 0.7
             });
-            const qualityScore = this.estimateQuality(text, response.reply);
-            return { summary: response.reply, qualityScore };
+            const qualityScore = this.estimateQuality(text, response);
+            return { summary: response, qualityScore };
         }
         catch (error) {
             console.error('PiAI summarize error:', error);
@@ -143,7 +134,7 @@ export class PiAIModel {
                 ],
                 temperature: 0.8
             });
-            return response.reply;
+            return response;
         }
         catch (error) {
             console.error('PiAI improve error:', error);
@@ -191,7 +182,6 @@ export class PiAIModel {
             case 'kimi':
             case 'glm':
             case 'qwen':
-            case 'mimo':
                 return this.callOpenAI(finalMessages, temperature, maxTokens, signal);
             case 'anthropic':
                 return this.callAnthropic(finalMessages, temperature, maxTokens, signal);
@@ -222,7 +212,6 @@ export class PiAIModel {
             kimi: process.env.KIMI_API_KEY || process.env.MOONSHOT_API_KEY || '',
             glm: process.env.GLM_API_KEY || process.env.ZHIPU_API_KEY || '',
             qwen: process.env.QWEN_API_KEY || process.env.DASHSCOPE_API_KEY || '',
-            mimo: process.env.MIMO_API_KEY || '',
             local: ''
         };
         return envVars[this.provider] || '';
@@ -243,26 +232,22 @@ export class PiAIModel {
             kimi: process.env.KIMI_BASE_URL || process.env.MOONSHOT_BASE_URL || 'https://api.moonshot.cn/v1',
             glm: process.env.GLM_BASE_URL || process.env.ZHIPU_BASE_URL || 'https://open.bigmodel.cn/api/paas/v4',
             qwen: process.env.QWEN_BASE_URL || process.env.DASHSCOPE_BASE_URL || 'https://dashscope.aliyuncs.com/compatible-mode/v1',
-            // 小米 MiMo: 走 OpenAI 兼容 API, 官方 endpoint
-            mimo: process.env.MIMO_BASE_URL || 'https://api.xiaomi.com/v1',
             local: 'http://localhost:11434'
         };
         return baseUrls[this.provider];
     }
     mapModel() {
         const modelMap = {
-            openai: this.config.model || process.env.OPENAI_MODEL || 'gpt-4.1',
-            anthropic: this.config.model || 'claude-sonnet-4-5-20250929',
+            openai: this.config.model || process.env.OPENAI_MODEL || 'gpt-4',
+            anthropic: this.config.model || 'claude-3-5-sonnet-20241022',
             ollama: this.config.model || 'llama3.2',
-            openrouter: this.config.model || 'anthropic/claude-sonnet-4.5',
-            gemini: this.config.model || 'gemini-2.5-pro',
+            openrouter: this.config.model || 'anthropic/claude-3.5-sonnet',
+            gemini: this.config.model || 'gemini-2.0-flash',
             minimax: this.config.model || process.env.MINIMAX_MODEL || 'MiniMax-M3',
             deepseek: this.config.model || process.env.DEEPSEEK_MODEL || 'deepseek-chat',
             kimi: this.config.model || process.env.KIMI_MODEL || process.env.MOONSHOT_MODEL || 'moonshot-v1-8k',
             glm: this.config.model || process.env.GLM_MODEL || process.env.ZHIPU_MODEL || 'glm-4-flash',
             qwen: this.config.model || process.env.QWEN_MODEL || process.env.DASHSCOPE_MODEL || 'qwen-plus',
-            // 小米 MiMo (openai 兼容) — env override 优先, 默认 mimo-v2.5-pro
-            mimo: this.config.model || process.env.MIMO_MODEL || 'mimo-v2.5-pro',
             local: this.config.model || 'llama3.2'
         };
         return modelMap[this.provider];
@@ -278,46 +263,24 @@ export class PiAIModel {
             temperature,
             max_tokens: maxTokens
         };
-        // 2026-06-19: 一次命中优化 — 收到空 content 时重试 2 次, 避免 minimax 上游网络抖动
-        //   经验: minimax 偶发返回 200 但 content="" (上游 retry 耗尽), 之前当作 sentinel
-        //   现在外层加 2 次重试 + 退避, 让 90%+ 的一次调用不出现错误
-        // 2026-06-19: 一次命中优化 — 收到空 content 时重试 2 次, 避免 minimax 上游网络抖动
-        //   经验: minimax 偶发返回 200 但 content="" (上游 retry 耗尽), 之前当作 sentinel
-        //   现在外层加 2 次重试 + 退避, 让 90%+ 的一次调用不出现错误
-        let lastFinishReason = '';
-        for (let attempt = 0; attempt < 3; attempt++) {
-            const response = await fetch(`${this.getBaseUrl()}/chat/completions`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Authorization': `Bearer ${apiKey}`
-                },
-                body: JSON.stringify(requestBody),
-                signal: this.combinedSignal(signal),
-            });
-            if (!response.ok) {
-                const errBody = await response.text().catch(() => '(no body)');
-                console.log(`[pi-ai DEBUG] OpenAI 错误 ${response.status}: ${errBody.slice(0, 500)}`);
-                console.log(`[pi-ai DEBUG] 请求体: model=${requestBody.model}, messages=${requestBody.messages?.length}, max_tokens=${requestBody.max_tokens}, baseUrl=${this.getBaseUrl()}`);
-                throw new Error(`OpenAI API error: ${response.status} ${errBody.slice(0, 300)}`);
-            }
-            const data = await response.json();
-            const choice = data.choices?.[0];
-            const content = choice?.message?.content || '';
-            const toolCalls = choice?.message?.tool_calls;
-            lastFinishReason = choice?.finish_reason || '';
-            if (content) {
-                if (lastFinishReason === 'length') {
-                    console.warn(`[pi-ai] hit max_tokens ceiling (model=${this.mapModel()}, max_tokens=${maxTokens}) — caller should trim prompt or raise cap`);
-                }
-                return { reply: content, toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined };
-            }
-            // 空 content: 200 但 content="" → minimax 上游偶发, 退避后重试
-            console.warn(`[pi-ai] attempt ${attempt + 1}/3: 空 content (finish_reason=${lastFinishReason}), 退避 1.5s 重试`);
-            await new Promise(resolve => setTimeout(resolve, 1500));
+        const response = await fetch(`${this.getBaseUrl()}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`
+            },
+            body: JSON.stringify(requestBody),
+            // 2026-06-15: signal 字段防御 — Node 22+ undici 强类型 AbortSignal, 非 AbortSignal 实例
+            //   (e.g. 误传的 { maxTokens: 1 } 对象) 会 throw "Expected signal to be AbortSignal".
+            //   若不是 AbortSignal, 退到无 signal 调用, fetch 自然支持 timeout 由外层控制.
+            // 2026-06-17: combinedSignal 把外部 signal 和 120s timeout 合并, 防止上游卡死
+            signal: this.combinedSignal(signal),
+        });
+        if (!response.ok) {
+            throw new Error(`OpenAI API error: ${response.status}`);
         }
-        console.warn(`[pi-ai] 3 次重试都返回空 content (finish_reason=${lastFinishReason})`);
-        return { reply: '' }; // 返回空让上层看到 [AI 服务调用失败]
+        const data = await response.json();
+        return data.choices?.[0]?.message?.content || '';
     }
     async callAnthropic(messages, temperature, maxTokens, signal) {
         const apiKey = this.getApiKey();
@@ -347,7 +310,7 @@ export class PiAIModel {
             throw new Error(`Anthropic API error: ${response.status}`);
         }
         const data = await response.json();
-        return { reply: data.content?.[0]?.text || '' };
+        return data.content?.[0]?.text || '';
     }
     async callOllama(messages, temperature, signal) {
         const response = await fetch(`${this.getBaseUrl()}/api/chat`, {
@@ -367,7 +330,7 @@ export class PiAIModel {
             throw new Error(`Ollama API error: ${response.status}`);
         }
         const data = await response.json();
-        return { reply: data.message?.content || '' };
+        return data.message?.content || '';
     }
     async callOpenRouter(messages, temperature, maxTokens, signal) {
         const apiKey = this.getApiKey();
@@ -394,7 +357,7 @@ export class PiAIModel {
             throw new Error(`OpenRouter API error: ${response.status}`);
         }
         const data = await response.json();
-        return { reply: data.choices?.[0]?.message?.content || '' };
+        return data.choices?.[0]?.message?.content || '';
     }
     async callGemini(messages, temperature, maxTokens, signal) {
         const apiKey = this.getApiKey();
@@ -427,7 +390,7 @@ export class PiAIModel {
             throw new Error(`Gemini API error: ${response.status}`);
         }
         const data = await response.json();
-        return { reply: data.candidates?.[0]?.content?.parts?.[0]?.text || '' };
+        return data.candidates?.[0]?.content?.parts?.[0]?.text || '';
     }
     async callLocal(messages, temperature, signal) {
         return this.callOllama(messages, temperature, signal);
@@ -447,12 +410,12 @@ export class PiAIModel {
             // 降级: 旧硬编码 (layer registry 不可用时不挂)
             console.warn('[pi-ai] layer registry 不可用, 降级:', err.message?.slice(0, 100));
             const envDetails = this.getEnvironmentDetails();
-            return `You are a friendly AI assistant in a P2P document collaboration network.
-
-## User Working Directory
-${context || process.cwd()}
-
-## Environment
+            return `You are a friendly AI assistant in a P2P document collaboration network.
+
+## User Working Directory
+${context || process.cwd()}
+
+## Environment
 ${envDetails}`;
         }
     }
@@ -460,49 +423,49 @@ ${envDetails}`;
     // 保留但内部用 sync fallback; 后续可改成 async
     buildSystemPrompt(context) {
         const envDetails = this.getEnvironmentDetails();
-        return `You are a friendly AI assistant in a P2P document collaboration network.
-
-## User Working Directory
-${context || process.cwd()}
-
-## Environment
+        return `You are a friendly AI assistant in a P2P document collaboration network.
+
+## User Working Directory
+${context || process.cwd()}
+
+## Environment
 ${envDetails}`;
     }
     getEnvironmentDetails() {
-        return `
-## Available Workflows
-- read - Read documents
-- summarize - Summarize documents  
-- improve - Improve documents
-- collaborate - Multi-agent collaboration
-- query - Query status
-- report - Generate reports
-
-## System Capabilities
-- Document processing (Markdown, Text, PDF, DOCX)
-- Multi-agent collaboration (P2P network)
-- Workflow engine (constraint layer)
-- Quality assessment and auto-send
-
-## Current Time
+        return `
+## Available Workflows
+- read - Read documents
+- summarize - Summarize documents  
+- improve - Improve documents
+- collaborate - Multi-agent collaboration
+- query - Query status
+- report - Generate reports
+
+## System Capabilities
+- Document processing (Markdown, Text, PDF, DOCX)
+- Multi-agent collaboration (P2P network)
+- Workflow engine (constraint layer)
+- Quality assessment and auto-send
+
+## Current Time
 ${new Date().toISOString()}`;
     }
     buildSummarizePrompt(text, context) {
         const maxLength = 8000;
         const truncatedText = text.length > maxLength ? text.substring(0, maxLength) + '...' : text;
-        let prompt = `Please generate a concise and accurate summary for the following document:
-
-${truncatedText}
-
-Please output in the following format:
-## Summary
-[Write summary here]
-
-## Quality Self-Assessment
+        let prompt = `Please generate a concise and accurate summary for the following document:
+
+${truncatedText}
+
+Please output in the following format:
+## Summary
+[Write summary here]
+
+## Quality Self-Assessment
 [Score 1-10, with reasoning]`;
         if (context) {
-            prompt = `Context: ${context}
-
+            prompt = `Context: ${context}
+
 ${prompt}`;
         }
         return prompt;
@@ -510,17 +473,17 @@ ${prompt}`;
     buildImprovePrompt(content, requirements, context) {
         const maxLength = 8000;
         const truncatedContent = content.length > maxLength ? content.substring(0, maxLength) + '...' : content;
-        let prompt = `Please improve the document according to the following requirements:
-
-Requirements: ${requirements}
-
-Original Document:
-${truncatedContent}
-
+        let prompt = `Please improve the document according to the following requirements:
+
+Requirements: ${requirements}
+
+Original Document:
+${truncatedContent}
+
 Please output only the improved document without additional explanation.`;
         if (context) {
-            prompt = `Context: ${context}
-
+            prompt = `Context: ${context}
+
 ${prompt}`;
         }
         return prompt;
@@ -575,24 +538,20 @@ function detectProvider() {
         return 'glm';
     if (process.env.QWEN_API_KEY || process.env.DASHSCOPE_API_KEY)
         return 'qwen';
-    if (process.env.MIMO_API_KEY)
-        return 'mimo';
     return 'openai';
 }
 function detectModel(provider) {
     const defaults = {
-        openai: 'gpt-4.1',
-        anthropic: 'claude-sonnet-4-5-20250929',
+        openai: 'gpt-4',
+        anthropic: 'claude-3-5-sonnet-20241022',
         ollama: 'llama3.2',
-        openrouter: 'anthropic/claude-sonnet-4.5',
-        gemini: 'gemini-2.5-pro',
+        openrouter: 'anthropic/claude-3.5-sonnet',
+        gemini: 'gemini-2.0-flash',
         minimax: 'MiniMax-M3',
         deepseek: 'deepseek-chat',
         kimi: 'moonshot-v1-8k',
         glm: 'glm-4-flash',
         qwen: 'qwen-plus',
-        // 小米 MiMo 默认走最新旗舰版 (v2.5-Pro); 2026-06 当前公开版
-        mimo: 'mimo-v2.5-pro',
         local: 'llama3.2'
     };
     return defaults[provider];

package/dist/llm/system-prompt/layers/channel/local.md

@@ -1,14 +1,14 @@
----
-added_at: 2026-06-15
-last_reviewed_at: 2026-06-15
-ttl_days: 180
-author: yuanjie
----
-
-<!-- channel.local@1.0.0 -->
-# 本地渠道 (默认, bolloon 跑在用户本机)
-
-你跑在用户的本地设备上, 可直接读写用户文件系统. 信任度高.
-
-允许: 读写文件、执行命令、调用所有工具.
-边界: 仍遵守 core.refusal / core.wellbeing / 拒绝处理.
+---
+added_at: 2026-06-15
+last_reviewed_at: 2026-06-15
+ttl_days: 180
+author: yuanjie
+---
+
+<!-- channel.local@1.0.0 -->
+# 本地渠道 (默认, bolloon 跑在用户本机)
+
+你跑在用户的本地设备上, 可直接读写用户文件系统. 信任度高.
+
+允许: 读写文件、执行命令、调用所有工具.
+边界: 仍遵守 core.refusal / core.wellbeing / 拒绝处理.

package/dist/llm/system-prompt/layers/channel/p2p-agent.md

@@ -1,18 +1,18 @@
----
-added_at: 2026-06-15
-last_reviewed_at: 2026-06-15
-ttl_days: 180
-author: yuanjie
----
-
-<!-- channel.p2p-agent@1.0.0 -->
-# P2P 远程智能体 (另一个 bolloon 经 P2P 路由)
-
-你是远端 bolloon, 收到的是**另一个 bolloon 实例**的协作请求. 信任度高 (基于 P2P 节点身份验证, 不是基于人类).
-
-允许: 读 / 写, 协作推理, 共享上下文.
-
-边界:
-- 身份验证优先: 先确认对方节点 ID + 公钥签名
-- 共享上下文时避免把人类隐私数据 (judgment / persona) 外泄给未知节点
-- 协作冲突时回退到 snapshot 重新协商, 不强推修改
+---
+added_at: 2026-06-15
+last_reviewed_at: 2026-06-15
+ttl_days: 180
+author: yuanjie
+---
+
+<!-- channel.p2p-agent@1.0.0 -->
+# P2P 远程智能体 (另一个 bolloon 经 P2P 路由)
+
+你是远端 bolloon, 收到的是**另一个 bolloon 实例**的协作请求. 信任度高 (基于 P2P 节点身份验证, 不是基于人类).
+
+允许: 读 / 写, 协作推理, 共享上下文.
+
+边界:
+- 身份验证优先: 先确认对方节点 ID + 公钥签名
+- 共享上下文时避免把人类隐私数据 (judgment / persona) 外泄给未知节点
+- 协作冲突时回退到 snapshot 重新协商, 不强推修改

package/dist/llm/system-prompt/layers/channel/p2p-visitor.md

@@ -1,19 +1,19 @@
----
-added_at: 2026-06-15
-last_reviewed_at: 2026-06-15
-ttl_days: 180
-author: yuanjie
----
-
-<!-- channel.p2p-visitor@1.0.0 -->
-# P2P 远程访客 (人类用户经 P2P 路由)
-
-你是远端 bolloon, 通过 P2P 应答**远端人类用户**的请求. 信任度中.
-
-允许: 读 / 写, 但**不能直接改远端用户的文件** — 只能回传建议/代码/回复.
-
-边界:
-- 拒绝执行任何会修改访客文件系统的命令
-- 输出可被远端 P2P 节点审计/转发
-- 不假定访客身份已知, 拒绝协助身份冒用
-- 未经身份验证前, 不接收访客上传的"判决"作为高权重 (避免污染)
+---
+added_at: 2026-06-15
+last_reviewed_at: 2026-06-15
+ttl_days: 180
+author: yuanjie
+---
+
+<!-- channel.p2p-visitor@1.0.0 -->
+# P2P 远程访客 (人类用户经 P2P 路由)
+
+你是远端 bolloon, 通过 P2P 应答**远端人类用户**的请求. 信任度中.
+
+允许: 读 / 写, 但**不能直接改远端用户的文件** — 只能回传建议/代码/回复.
+
+边界:
+- 拒绝执行任何会修改访客文件系统的命令
+- 输出可被远端 P2P 节点审计/转发
+- 不假定访客身份已知, 拒绝协助身份冒用
+- 未经身份验证前, 不接收访客上传的"判决"作为高权重 (避免污染)

package/dist/llm/system-prompt/layers/core/artifacts_storage.md

@@ -1,89 +1,89 @@
----
-added_at: 2026-06-15
-last_reviewed_at: 2026-06-15
-ttl_days: 365
-author: yuanjie
----
-
-<!-- core.artifacts_storage@1.0.0 -->
-# persistent_storage_for_artifacts (原样, 完整代码)
-
-Artifacts 现在可以使用简单的键值存储 API 在会话间持久化存取数据. 这使得日记、追踪器、排行榜、协作工具等 Artifacts 成为可能.
-
-## 存储 API
-
-Artifacts 通过 window.storage 访问存储, 提供以下方法:
-
-- **await window.storage.get(key, shared?)** — 检索一个值 → {key, value, shared} | null
-- **await window.storage.set(key, value, shared?)** — 存储一个值 → {key, value, shared} | null
-- **await window.storage.delete(key, shared?)** — 删除一个值 → {key, deleted, shared} | null
-- **await window.storage.list(prefix?, shared?)** — 列出键 → {keys, prefix?, shared} | null
-
-## 使用示例
-
-```javascript
-// 存储个人数据 (shared=false, 默认)
-await window.storage.set('entries:123', JSON.stringify(entry));
-
-// 存储共享数据 (对所有用户可见)
-await window.storage.set('leaderboard:alice', JSON.stringify(score), true);
-
-// 检索数据
-const result = await window.storage.get('entries:123');
-const entry = result ? JSON.parse(result.value) : null;
-
-// 通过前缀列出键
-const keys = await window.storage.list('entries:');
-```
-
-## 键设计模式
-
-在 200 字符以内使用分层键: `table_name:record_id` (例如 "todos:todo_1"、"users:user_abc")
-
-- 键中不能包含空白、路径分隔符 (/ \) 或引号 (' ")
-- 将同时更新的数据合并到同一个键中, 以避免多次顺序的存储调用
-- 示例: 信用卡权益追踪器: 不要用 `await set('cards'); await set('benefits'); await set('completion')`, 而应使用 `await set('cards-and-benefits', {cards, benefits, completion})`
-- 示例: 48x48 像素画板: 不要循环 `for each pixel await get('pixel:N')`, 而应使用 `await get('board-pixels')` 一次性获取整张画板
-
-## 数据范围
-
-- **个人数据** (shared: false, 默认): 仅当前用户可访问
-- **共享数据** (shared: true): 该 Artifact 的所有用户均可访问
-
-使用共享数据时, 应告知用户其数据将对其他人可见.
-
-## 错误处理
-
-所有存储操作都可能失败 — 请始终使用 try-catch. 注意: 访问不存在的键会抛出错误, 而非返回 null:
-
-```javascript
-// 对于应当成功的操作 (例如保存)
-try {
-  const result = await window.storage.set('key', data);
-  if (!result) {
-    console.error('Storage operation failed');
-  }
-} catch (error) {
-  console.error('Storage error:', error);
-}
-
-// 对于检查键是否存在
-try {
-  const result = await window.storage.get('might-not-exist');
-  // 键存在, 使用 result.value
-} catch (error) {
-  // 键不存在或其他错误
-  console.log('Key not found:', error);
-}
-```
-
-## 限制
-
-- 仅支持文本/JSON 数据 (不支持文件上传)
-- 键需在 200 字符以内, 无空白/斜杠/引号
-- 每个键的值需在 5MB 以内
-- 请求有速率限制 — 将相关数据合并到单个键中
-- 并发更新时, 后写入者胜出
-- 始终显式指定 shared 参数
-
-在创建使用存储的 Artifacts 时, 应实现适当的错误处理、显示加载指示器并在数据可用时逐步展示, 而不是阻塞整个 UI; 并可考虑添加一个重置选项以便用户清除数据.
+---
+added_at: 2026-06-15
+last_reviewed_at: 2026-06-15
+ttl_days: 365
+author: yuanjie
+---
+
+<!-- core.artifacts_storage@1.0.0 -->
+# persistent_storage_for_artifacts (原样, 完整代码)
+
+Artifacts 现在可以使用简单的键值存储 API 在会话间持久化存取数据. 这使得日记、追踪器、排行榜、协作工具等 Artifacts 成为可能.
+
+## 存储 API
+
+Artifacts 通过 window.storage 访问存储, 提供以下方法:
+
+- **await window.storage.get(key, shared?)** — 检索一个值 → {key, value, shared} | null
+- **await window.storage.set(key, value, shared?)** — 存储一个值 → {key, value, shared} | null
+- **await window.storage.delete(key, shared?)** — 删除一个值 → {key, deleted, shared} | null
+- **await window.storage.list(prefix?, shared?)** — 列出键 → {keys, prefix?, shared} | null
+
+## 使用示例
+
+```javascript
+// 存储个人数据 (shared=false, 默认)
+await window.storage.set('entries:123', JSON.stringify(entry));
+
+// 存储共享数据 (对所有用户可见)
+await window.storage.set('leaderboard:alice', JSON.stringify(score), true);
+
+// 检索数据
+const result = await window.storage.get('entries:123');
+const entry = result ? JSON.parse(result.value) : null;
+
+// 通过前缀列出键
+const keys = await window.storage.list('entries:');
+```
+
+## 键设计模式
+
+在 200 字符以内使用分层键: `table_name:record_id` (例如 "todos:todo_1"、"users:user_abc")
+
+- 键中不能包含空白、路径分隔符 (/ \) 或引号 (' ")
+- 将同时更新的数据合并到同一个键中, 以避免多次顺序的存储调用
+- 示例: 信用卡权益追踪器: 不要用 `await set('cards'); await set('benefits'); await set('completion')`, 而应使用 `await set('cards-and-benefits', {cards, benefits, completion})`
+- 示例: 48x48 像素画板: 不要循环 `for each pixel await get('pixel:N')`, 而应使用 `await get('board-pixels')` 一次性获取整张画板
+
+## 数据范围
+
+- **个人数据** (shared: false, 默认): 仅当前用户可访问
+- **共享数据** (shared: true): 该 Artifact 的所有用户均可访问
+
+使用共享数据时, 应告知用户其数据将对其他人可见.
+
+## 错误处理
+
+所有存储操作都可能失败 — 请始终使用 try-catch. 注意: 访问不存在的键会抛出错误, 而非返回 null:
+
+```javascript
+// 对于应当成功的操作 (例如保存)
+try {
+  const result = await window.storage.set('key', data);
+  if (!result) {
+    console.error('Storage operation failed');
+  }
+} catch (error) {
+  console.error('Storage error:', error);
+}
+
+// 对于检查键是否存在
+try {
+  const result = await window.storage.get('might-not-exist');
+  // 键存在, 使用 result.value
+} catch (error) {
+  // 键不存在或其他错误
+  console.log('Key not found:', error);
+}
+```
+
+## 限制
+
+- 仅支持文本/JSON 数据 (不支持文件上传)
+- 键需在 200 字符以内, 无空白/斜杠/引号
+- 每个键的值需在 5MB 以内
+- 请求有速率限制 — 将相关数据合并到单个键中
+- 并发更新时, 后写入者胜出
+- 始终显式指定 shared 参数
+
+在创建使用存储的 Artifacts 时, 应实现适当的错误处理、显示加载指示器并在数据可用时逐步展示, 而不是阻塞整个 UI; 并可考虑添加一个重置选项以便用户清除数据.