examples/fast_dev_demo.py: 修复导入错误，使用 create_storage 和 ZhipuChat。

examples/zhipu_agent.py: 修复导入错误，使用 ZhipuChat。
examples/full_tool_test.py: (可选) 同样需要更新模型实例化方式。
examples/knowledge_rag_demo.py (新增): 专门用于验证 RAG 工具链和 Pydantic 修复。
examples/compose/workflow_next_resume_demo.py: 更新存储初始化方式以验证工厂注册修复。

Author: xuemzhan

examples/compose/workflow_next_resume_demo.py

@@ -16,7 +16,8 @@
 
 from gecko.compose.workflow import Workflow, WorkflowContext, CheckpointStrategy
 from gecko.compose.nodes import step, Next
-from gecko.plugins.storage.backends.sqlite import SQLiteStorage
+# [Fix] 使用 create_storage 替代直接实例化，验证 Bug #7 的注册装饰器修复
+from gecko.plugins.storage.factory import create_storage
 from gecko.core.logging import setup_logging
 from gecko.core.exceptions import WorkflowError
 
@@ -50,18 +51,20 @@ async def next_node(context: WorkflowContext):
     return f"Processed({inp})"
 
 async def main():
-    db_file = "next_resume.db"
+    # [Fix] 使用 explicit relative path (./) to avoid writing to root
+    db_file = "./next_resume.db"
     db_url = f"sqlite:///{db_file}"
 
     if os.path.exists(db_file):
         os.remove(db_file)
 
-    storage = SQLiteStorage(db_url)
-    await storage.initialize()
+    # [Verification] Bug #7: 如果 SQLiteStorage 没加 @register_storage，这里会报错
+    storage = await create_storage(db_url)
 
     wf = Workflow(
         name="NextResumeFlow", 
-        storage=storage,
+        storage=storage, # type: ignore
+        # [Key] 必须为 ALWAYS，确保 Next 指令产生时立即持久化，以便验证 Resume
         checkpoint_strategy=CheckpointStrategy.ALWAYS
     )
 
@@ -101,7 +104,13 @@ async def main():
 
     await storage.shutdown()
     if os.path.exists(db_file):
-        os.remove(db_file)
+        try:
+            os.remove(db_file)
+            if os.path.exists(db_file + ".lock"): os.remove(db_file + ".lock")
+            if os.path.exists(db_file + "-wal"): os.remove(db_file + "-wal")
+            if os.path.exists(db_file + "-shm"): os.remove(db_file + "-shm")
+        except:
+            pass
 
 if __name__ == "__main__":
     asyncio.run(main())

examples/compose/workflow_resume_demo.py

@@ -1,4 +1,4 @@
-# examples/workflow_resume_demo.py
+# examples/compose/workflow_resume_demo.py
 """
 Workflow 断点恢复示例 (Resumability Demo)
 
@@ -16,7 +16,8 @@
 
 from gecko.compose.workflow import Workflow, WorkflowContext, CheckpointStrategy
 from gecko.compose.nodes import step, Next
-from gecko.plugins.storage.backends.sqlite import SQLiteStorage
+# [Fix] Use create_storage factory
+from gecko.plugins.storage.factory import create_storage
 from gecko.core.logging import setup_logging
 # [Fix] Import WorkflowError
 from gecko.core.exceptions import WorkflowError
@@ -66,7 +67,8 @@ async def step_c(context: WorkflowContext):
 # ========================= 主流程 =========================
 
 async def main():
-    db_file = "resume_demo.db"
+    # [Fix] Use explicit relative path
+    db_file = "./resume_demo.db"
     db_url = f"sqlite:///{db_file}"
 
     # 清理旧数据确保 Demo 可重复
@@ -79,13 +81,13 @@ async def main():
     print(f"🔌 初始化存储: {db_url}")
     # 1. 初始化存储
     # 断点恢复必须依赖持久化存储
-    storage = SQLiteStorage(db_url)
-    await storage.initialize()
+    # [Fix] Use factory
+    storage = await create_storage(db_url)
 
     # 2. 定义工作流
     wf = Workflow(
         name="ResumableFlow", 
-        storage=storage,
+        storage=storage, # type: ignore
         # [Phase 3 Feature] 策略: ALWAYS (每步保存)，这是 Resume 的前提
         checkpoint_strategy=CheckpointStrategy.ALWAYS
     )
@@ -140,6 +142,7 @@ async def main():
         try:
             os.remove(db_file)
             # SQLite WAL 模式可能会产生额外文件
+            if os.path.exists(db_file + ".lock"): os.remove(db_file + ".lock")
             if os.path.exists(db_file + "-wal"): os.remove(db_file + "-wal")
             if os.path.exists(db_file + "-shm"): os.remove(db_file + "-shm")
         except:

examples/fast_dev_demo.py

@@ -3,43 +3,50 @@
 import os
 from gecko.core.builder import AgentBuilder
 from gecko.core.message import Message
-# [Fix] Import ZhipuChat
-from gecko.plugins.models.presets.zhipu import ZhipuChat
-from gecko.plugins.storage.backends.sqlite import SQLiteStorage
+# [Fix] 使用标准的类导入，而非旧版 helper 函数
+from gecko.plugins.models import ZhipuChat
+# [Fix] 使用工厂方法创建存储
+from gecko.plugins.storage.factory import create_storage
 
 async def main():
     api_key = os.getenv("ZHIPU_API_KEY")
-    
-    # [Fix] 创建 Storage 实例
-    storage = SQLiteStorage("sqlite://./dev_sessions.db")
-    await storage.initialize() # 确保存储初始化
+    if not api_key:
+        print("Skipping: ZHIPU_API_KEY not set")
+        return
 
-    try:
-        # [Fix] 创建 Model 实例
-        model = ZhipuChat(api_key=api_key or "mock_key", model="glm-4-flash")
+    # [Fix] 使用 factory 创建并初始化存储
+    # 注意：SQLite URL 相对路径需要 3 个斜杠 (sqlite:///./path)
+    # 验证 Bug #7 (SQLite 注册) 是否修复，工厂应能正确加载 sqlite
+    storage = await create_storage("sqlite:///./dev_sessions.db")
 
-        agent = (AgentBuilder()
-                 .with_model(model)
-                 .with_session_id("user_123")
-                 .with_storage(storage)
-                 .build())
+    agent = (AgentBuilder()
+             # [Fix] 显式实例化模型
+             .with_model(ZhipuChat(api_key=api_key, model="glm-4-flash", temperature=0.3))
+             .with_session_id("user_123")
+             .with_storage(storage) # type: ignore
+             .build())
 
-        # 第一次运行：记住名字
-        print("--- Round 1 ---")
-        output1 = await agent.run([Message(role="user", content="我叫张三，以后叫我老张")])
-        print("AI:", output1.content) # type: ignore
+    # 第一次运行
+    print("--- Round 1 ---")
+    output1 = await agent.run([Message(role="user", content="我叫张三，以后叫我老张")])
+    print("AI:", output1.content) # type: ignore
 
-        # 第二次运行：验证记忆恢复
-        print("\n--- Round 2 ---")
-        output2 = await agent.run([Message(role="user", content="我叫什么名字？")])
-        print("AI:", output2.content) # type: ignore
-        
-    finally:
-        await storage.shutdown()
-        # 清理临时文件
-        if os.path.exists("dev_sessions.db"):
-            try: os.remove("dev_sessions.db")
-            except: pass
+    # 第二次运行：验证记忆恢复
+    print("\n--- Round 2 ---")
+    output2 = await agent.run([Message(role="user", content="我叫什么名字？")])
+    print("AI:", output2.content) # type: ignore
+    
+    # 清理
+    await storage.shutdown()
+    if os.path.exists("dev_sessions.db"):
+        try:
+            os.remove("dev_sessions.db")
+            # 清理可能存在的锁文件和 WAL 文件
+            if os.path.exists("dev_sessions.db.lock"): os.remove("dev_sessions.db.lock")
+            if os.path.exists("dev_sessions.db-wal"): os.remove("dev_sessions.db-wal")
+            if os.path.exists("dev_sessions.db-shm"): os.remove("dev_sessions.db-shm")
+        except OSError:
+            pass
 
 if __name__ == "__main__":
     asyncio.run(main())

examples/knowledge/knowledge_rag_demo.py

@@ -0,0 +1,82 @@
+# examples/knowledge_rag_demo.py
+"""
+RAG 知识库演示
+
+验证功能：
+1. 文档入库 (IngestionPipeline)
+2. 向量检索 (RetrievalTool) -> 验证 Bug #9 修复 (PrivateAttr)
+3. 结合 Agent 进行问答
+"""
+import asyncio
+import os
+import shutil
+from gecko.core.agent import Agent
+from gecko.core.builder import AgentBuilder
+from gecko.core.message import Message
+from gecko.plugins.storage.factory import create_storage
+from gecko.plugins.knowledge import IngestionPipeline, Document
+from gecko.plugins.knowledge.tool import RetrievalTool
+from gecko.plugins.models import ZhipuChat
+# 假设我们使用 Zhipu 的 Embedding (通过 LiteLLMEmbedder)
+from gecko.plugins.models.presets.zhipu import ZhipuChat # Zhipu SDK 暂无单独 Embedder Preset，需手动配置
+from gecko.plugins.models.embedding import LiteLLMEmbedder
+from gecko.plugins.models.config import ModelConfig
+
+async def main():
+    api_key = os.getenv("ZHIPU_API_KEY")
+    if not api_key:
+        print("Please set ZHIPU_API_KEY")
+        return
+
+    # 1. 准备向量存储 (Chroma)
+    persist_path = "./demo_rag_db"
+    if os.path.exists(persist_path): shutil.rmtree(persist_path)
+    
+    vector_store = await create_storage(f"chroma://{persist_path}")
+    
+    # 2. 准备 Embedding 模型
+    embedder = LiteLLMEmbedder(
+        config=ModelConfig(model_name="zhipu/embedding-2", api_key=api_key),
+        dimension=1024
+    )
+
+    # 3. 数据入库
+    print("🚀 Ingesting documents...")
+    pipeline = IngestionPipeline(vector_store, embedder)
+    
+    # 创建临时文件用于测试
+    with open("gecko_intro.txt", "w") as f:
+        f.write("Gecko 是一个高性能的 AI Agent 框架，支持异步编排和插件化设计。它由 Python 编写。")
+    
+    await pipeline.run(["gecko_intro.txt"])
+
+    # 4. 初始化检索工具
+    # [Verification] Bug #9: 如果 RetrievalTool 没有使用 PrivateAttr，这里会抛出 Pydantic ValidationError
+    print("\n🔧 Initializing RetrievalTool...")
+    rag_tool = RetrievalTool(
+        vector_store=vector_store,
+        embedder=embedder,
+        top_k=1
+    )
+    print("✅ Tool initialized successfully (PrivateAttr fix works).")
+
+    # 5. 构建 Agent
+    model = ZhipuChat(api_key=api_key, model="glm-4-flash")
+    agent = AgentBuilder()\
+        .with_model(model)\
+        .with_tools([rag_tool])\
+        .build()
+
+    # 6. 提问
+    query = "Gecko 框架是用什么语言编写的？"
+    print(f"\n👤 User: {query}")
+    response = await agent.run(query)
+    print(f"🤖 Agent: {response.content}") # type: ignore
+
+    # 清理
+    await vector_store.shutdown()
+    if os.path.exists("gecko_intro.txt"): os.remove("gecko_intro.txt")
+    if os.path.exists(persist_path): shutil.rmtree(persist_path)
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/zhipu_agent.py

@@ -3,23 +3,18 @@
 import os
 from gecko.core.builder import AgentBuilder
 from gecko.core.message import Message
-# [Fix] 使用新的 Presets 类
-from gecko.plugins.models.presets.zhipu import ZhipuChat
+# [Fix] Correct import
+from gecko.plugins.models import ZhipuChat 
 
 async def main():
     api_key = os.getenv("ZHIPU_API_KEY")
-    if not api_key:
-        print("Error: ZHIPU_API_KEY not found.")
-        return
+    if not api_key: return
 
-    # [Fix] 实例化类
-    model = ZhipuChat(api_key=api_key, model="glm-4-flash", temperature=0.8)
+    agent = AgentBuilder()\
+        .with_model(ZhipuChat(api_key=api_key, model="glm-4-flash"))\
+        .build()
 
-    agent = AgentBuilder().with_model(model).build()
-
-    output = await agent.run([
-        Message(role="user", content="用中文介绍一下 Gecko 框架的插件化设计优势")
-    ])
+    output = await agent.run("用中文介绍一下 Gecko 框架的优势")
     print(output.content) # type: ignore
 
 if __name__ == "__main__":