ni.agentkit 0.6.2__tar.gz → 0.7.0__tar.gz

{ni_agentkit-0.6.2 → ni_agentkit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ni.agentkit
-Version: 0.6.2
+Version: 0.7.0
 Summary: A Python-native Agent framework with first-class Skill support and multi-LLM adapter
 Author-email: Krix Tam <krix.tam@qq.com>
 License: MIT
@@ -153,8 +153,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.6.2-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.6.2.tar.gz             # 源码分发
+├── ni_agentkit-0.7.0-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.7.0.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.6.2 → ni_agentkit-0.7.0}/README.md

@@ -111,8 +111,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.6.2-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.6.2.tar.gz             # 源码分发
+├── ni_agentkit-0.7.0-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.7.0.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.6.2 → ni_agentkit-0.7.0}/__init__.py

@@ -31,7 +31,7 @@ from .tools.function_tool import FunctionTool, function_tool
 from .tools.structured_data import ResultFormatter, StructuredDataTool
 from .tools.sqlite_tool import SQLiteTool, SQLiteResultFormatter
 
-__version__ = "0.6.2"
+__version__ = "0.7.0"
 
 
 def get_docs_dir() -> str:

{ni_agentkit-0.6.2 → ni_agentkit-0.7.0}/docs/Architecture.md

@@ -575,6 +575,14 @@ agentkit/
 │   ├── structured_data.py   #   StructuredDataTool / ResultFormatter
 │   ├── sqlite_tool.py       #   SQLiteTool
 │   ├── nebula_tool.py       #   NebulaGraphTool
+│   ├── graph/               #   统一图接口层（Adapter/Repository/Tool）
+│   │   ├── protocols.py     #     GraphAdapter 协议
+│   │   ├── repository.py    #     GraphRepository（统一访问入口）
+│   │   ├── factory.py       #     create_graph_repository* 工厂
+│   │   ├── networkx_adapter.py
+│   │   ├── litegraph_adapter.py
+│   │   ├── nebula_adapter.py
+│   │   └── tool.py          #     GraphQueryTool
 │   └── skill_toolset.py     #   SkillToolset（4 个桥接工具）
 │
 ├── skills/                  # Skill 层
@@ -612,8 +620,8 @@ agentkit/
 │   └── schema.py            #   函数签名 → JSON Schema
 │
 ├── examples/                # 示例
-│   ├── standard/            #   标准版示例（01-18，含 9A/9B）
-│   ├── ollama/              #   Ollama 版示例（01-18，含 9A/9B）
+│   ├── standard/            #   标准版示例（01-18，含 8A/8B/8C、9A/9B/9C）
+│   ├── ollama/              #   Ollama 版示例（01-19，含 8A/8B/8C、9A/9B/9C）
 │   ├── quickstart.py
 │   └── test_ollama.py
 │

{ni_agentkit-0.6.2 → ni_agentkit-0.7.0}/docs/QuickStart.md

@@ -1,6 +1,6 @@
 # AgentKit 快速入门教程
 
-> 本教程将带你从零开始，通过 18 组由简到繁的示例（含 9A/9B），掌握 AgentKit 的核心用法。
+> 本教程将带你从零开始，通过 18 组由简到繁的示例（含 8A/8B/8C、9A/9B/9C），掌握 AgentKit 的核心用法。
 
 ---
 
@@ -21,6 +21,7 @@
 - [示例 8：记忆系统 — 跨会话长期记忆](#示例-8记忆系统--跨会话长期记忆)
 - [示例 9A：关系型数据库 — 防止 SQL 注入的参数化 Tool](#示例-9a关系型数据库--防止-sql-注入的参数化-tool)
 - [示例 9B：图数据库 — 配合 Mock 运行的 NebulaGraphTool](#示例-9b图数据库--配合-mock-运行的-nebulagraphtool)
+- [示例 9C：NebulaGraphTool 最小可执行示例（工具层直调）](#示例-9cnebulagraphtool-最小可执行示例工具层直调)
 - [示例 10：Skill 生命周期 — 管理外部资源连接池](#示例-10skill-生命周期--管理外部资源连接池)
 - [示例 11：编排增强 — 循环退出条件与并行提前终止](#示例-11编排增强--循环退出条件与并行提前终止)
 - [示例 12：RunContext 序列化与共享状态](#示例-12runcontext-序列化与共享状态)
@@ -608,60 +609,45 @@ asyncio.run(stream_demo())
 
 默认情况下，Agent 每次运行都是无状态的。配上记忆后，Agent 可以记住用户的偏好和历史。
 
-### 无需外部依赖的 SimpleMemory
+### 8A：SimpleMemory
 
 ```python
 from agentkit import Agent, Runner, BaseMemoryProvider, Memory
 
 class SimpleMemory(BaseMemoryProvider):
-    """轻量内存记忆——适合开发测试"""
     def __init__(self):
         self._store, self._counter = [], 0
-
     async def add(self, content, *, user_id=None, agent_id=None, metadata=None):
         self._counter += 1
         m = Memory(id=str(self._counter), content=content)
         self._store.append(m)
         return [m]
-
     async def search(self, query, *, user_id=None, agent_id=None, limit=10):
-        # 简单关键词匹配（生产环境用 Mem0 的向量搜索）
         query_words = set(query)
         scored = [(len(query_words & set(m.content)), m) for m in self._store]
         scored.sort(reverse=True, key=lambda x: x[0])
         return [m for s, m in scored[:limit] if s > 0]
-
     async def get_all(self, *, user_id=None, agent_id=None):
         return list(self._store)
-
     async def delete(self, memory_id):
         self._store = [m for m in self._store if m.id != memory_id]
         return True
 
-# 给 Agent 配上记忆
 memory = SimpleMemory()
-
 agent = Agent(
     name="personal-assistant",
     instructions="你是一个贴心的个人助手。根据记忆来个性化回答。",
     model="ollama/qwen3.5:cloud",
-    memory=memory,       # ← 加上这一行
+    memory=memory,
+    memory_async_write=False,
 )
 
-# 第 1 轮：告诉偏好
 Runner.run_sync(agent, input="我叫小明，我喜欢喝咖啡，讨厌喝茶", user_id="krix")
-
-# 第 2 轮：Agent 会记住偏好，推荐咖啡而不是茶
 result = Runner.run_sync(agent, input="帮我推荐一杯饮料", user_id="krix")
-print(result.final_output)  # "推荐拿铁！" — 基于记忆推荐
+print(result.final_output)  # 基于记忆推荐
 ```
 
-**要点**：
-- 默认不开启记忆，需要给 `Agent` 传 `memory=...` 参数
-- 配好后**不需要写额外代码**——框架自动在对话前检索记忆、对话后存储记忆
-- `user_id` 用于多用户隔离
-
-### 生产环境使用 Mem0
+### 8B：Mem0Provider（生产级）
 
 ```bash
 pip install mem0ai
@@ -678,11 +664,47 @@ memory = Mem0Provider({
     }
 })
 
-agent = Agent(memory=memory, ...)     # 替换 SimpleMemory 即可
+agent = Agent(memory=memory, ...)  # 先构建 memory，再注入 Agent
 ```
 
 Mem0 相比 SimpleMemory 的优势：**语义搜索**（理解意思而非关键词）、**持久化**（重启不丢失）、**智能提取**（从对话中自动抽取关键信息）。
 
+### 8C：自定义 Memory（文件持久化）
+
+```python
+import json
+from pathlib import Path
+from agentkit import BaseMemoryProvider, Memory, Agent
+
+class FileMemoryProvider(BaseMemoryProvider):
+    def __init__(self, file_path: str):
+        self.path = Path(file_path)
+        self.records = json.loads(self.path.read_text()) if self.path.exists() else []
+    async def add(self, content, *, user_id=None, agent_id=None, metadata=None):
+        new_id = str(len(self.records) + 1)
+        self.records.append({"id": new_id, "content": content, "user_id": user_id})
+        self.path.write_text(json.dumps(self.records, ensure_ascii=False, indent=2))
+        return [Memory(id=new_id, content=content)]
+    async def search(self, query, *, user_id=None, agent_id=None, limit=10):
+        q = query.lower()
+        out = [r for r in self.records if q in r["content"].lower()]
+        return [Memory(id=r["id"], content=r["content"]) for r in out[:limit]]
+    async def get_all(self, *, user_id=None, agent_id=None):
+        return [Memory(id=r["id"], content=r["content"]) for r in self.records]
+    async def delete(self, memory_id):
+        self.records = [r for r in self.records if r["id"] != memory_id]
+        self.path.write_text(json.dumps(self.records, ensure_ascii=False, indent=2))
+        return True
+
+memory = FileMemoryProvider("/tmp/agentkit_memory.json")
+agent = Agent(memory=memory, ...)
+```
+
+**要点**：
+- 默认不开启记忆，需要给 `Agent` 传 `memory=...` 参数
+- `SimpleMemory` 适合开发测试，`Mem0Provider` 适合生产语义检索
+- 自定义 `FileMemoryProvider` 可实现轻量持久化（进程重启后仍可读取）
+
 ---
 
 ## 示例 9A：关系型数据库 — 防止 SQL 注入的参数化 Tool
@@ -803,6 +825,63 @@ if __name__ == "__main__":
 
 ---
 
+## 示例 9C：NebulaGraphTool 最小可执行示例（工具层直调）
+
+如果你想先验证 `NebulaGraphTool` 本身（参数校验、查询模板拼接、formatter 输出）是否工作正常，可以不经过 LLM，直接调用工具执行。
+
+```python
+import asyncio
+from typing import Any
+from pydantic import BaseModel, Field
+from agentkit.runner.context import RunContext
+from agentkit.tools.nebula_tool import NebulaGraphTool
+from agentkit.tools.structured_data import ResultFormatter
+
+class MockSession:
+    def execute(self, query: str):
+        print(f"[MockSession] execute gql => {query}")
+        return "mock_result_set"
+    def release(self): pass
+
+class MockConnectionPool:
+    def get_session(self, user, password):
+        return MockSession()
+
+class MockNebulaFormatter(ResultFormatter):
+    def format(self, raw_result: Any) -> Any:
+        return {"summary": "Query succeeded (mock)", "data": [{"friend_name": "Bob"}]}
+
+class PersonQueryArgs(BaseModel):
+    name: str = Field(..., pattern=r"^[A-Za-z0-9_]+$")
+
+nebula_tool = NebulaGraphTool(
+    name="find_person_friends",
+    description="查询某个人在图谱中的朋友关系",
+    parameters_schema=PersonQueryArgs,
+    query_template='MATCH (v:person)-[:friend]->(e:person) WHERE id(v) == "{name}" RETURN e.name AS friend_name;',
+    space_name="social_graph",
+    connection_pool=MockConnectionPool(),
+    formatter=MockNebulaFormatter(),
+)
+
+async def main():
+    payload = await nebula_tool.execute(RunContext(input="demo"), {"name": "Alice_001"})
+    print(payload)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+运行文件：
+- `examples/standard/09c_nebula_graph_tool.py`
+- `examples/ollama/09c_nebula_graph_tool.py`
+
+**要点**：
+- 该示例不依赖真实 Nebula 集群，也不依赖 LLM，可用于本地快速验证 Tool 行为。
+- 后续接入真实 Nebula 时，只需替换 `connection_pool` 与（可选）`formatter`。
+
+---
+
 ## 示例 10：Skill 生命周期 — 管理外部资源连接池
 
 当 Skill 依赖外部资源（如数据库连接池、长期会话句柄）时，你需要确保在使用前正确初始化，并在结束时安全释放。
@@ -1159,9 +1238,12 @@ agent = Agent(name="assistant", instructions="...")
 | [`05_guardrail.py`](../examples/standard/05_guardrail.py) | 示例 5：安全护栏 |
 | [`06_orchestration.py`](../examples/standard/06_orchestration.py) | 示例 6：编排 Agent |
 | [`07_sync_async_stream.py`](../examples/standard/07_sync_async_stream.py) | 示例 7：同步/异步/流式运行 |
-| [`08_memory.py`](../examples/standard/08_memory.py) | 示例 8：记忆系统 |
+| [`08a_memory_simple_provider.py`](../examples/standard/08a_memory_simple_provider.py) | 示例 8A：记忆系统（SimpleMemory） |
+| [`08b_memory_mem0_provider.py`](../examples/standard/08b_memory_mem0_provider.py) | 示例 8B：记忆系统（Mem0Provider） |
+| [`08c_memory_file_provider.py`](../examples/standard/08c_memory_file_provider.py) | 示例 8C：记忆系统（文件持久化） |
 | [`09a_structured_data_sql.py`](../examples/standard/09a_structured_data_sql.py) | 示例 9A：关系型数据库 |
 | [`09b_structured_data_graph.py`](../examples/standard/09b_structured_data_graph.py) | 示例 9B：图数据库 |
+| [`09c_nebula_graph_tool.py`](../examples/standard/09c_nebula_graph_tool.py) | 示例 9C：NebulaGraphTool 最小可执行示例 |
 | [`10_skill_lifecycle.py`](../examples/standard/10_skill_lifecycle.py) | 示例 10：Skill 生命周期 |
 | [`11_orchestration_enhancement.py`](../examples/standard/11_orchestration_enhancement.py) | 示例 11：编排增强 |
 | [`12_run_context_serialization.py`](../examples/standard/12_run_context_serialization.py) | 示例 12：RunContext 序列化与共享状态 |
@@ -1183,9 +1265,12 @@ agent = Agent(name="assistant", instructions="...")
 | [`05_guardrail.py`](../examples/ollama/05_guardrail.py) | 示例 5：安全护栏 |
 | [`06_orchestration.py`](../examples/ollama/06_orchestration.py) | 示例 6：编排 Agent |
 | [`07_sync_async_stream.py`](../examples/ollama/07_sync_async_stream.py) | 示例 7：同步/异步/流式运行 |
-| [`08_memory.py`](../examples/ollama/08_memory.py) | 示例 8：记忆系统 |
+| [`08a_memory_simple_provider.py`](../examples/ollama/08a_memory_simple_provider.py) | 示例 8A：记忆系统（SimpleMemory） |
+| [`08b_memory_mem0_provider.py`](../examples/ollama/08b_memory_mem0_provider.py) | 示例 8B：记忆系统（Mem0Provider） |
+| [`08c_memory_file_provider.py`](../examples/ollama/08c_memory_file_provider.py) | 示例 8C：记忆系统（文件持久化） |
 | [`09a_structured_data_sql.py`](../examples/ollama/09a_structured_data_sql.py) | 示例 9A：关系型数据库 |
 | [`09b_structured_data_graph.py`](../examples/ollama/09b_structured_data_graph.py) | 示例 9B：图数据库 |
+| [`09c_nebula_graph_tool.py`](../examples/ollama/09c_nebula_graph_tool.py) | 示例 9C：NebulaGraphTool 最小可执行示例 |
 | [`10_skill_lifecycle.py`](../examples/ollama/10_skill_lifecycle.py) | 示例 10：Skill 生命周期 |
 | [`11_orchestration_enhancement.py`](../examples/ollama/11_orchestration_enhancement.py) | 示例 11：编排增强 |
 | [`12_run_context_serialization.py`](../examples/ollama/12_run_context_serialization.py) | 示例 12：RunContext 序列化与共享状态 |

{ni_agentkit-0.6.2 → ni_agentkit-0.7.0}/docs/README.md

@@ -3,7 +3,7 @@
 > Python 原生的 Agent 开发框架，内置一等公民级别的 Skill 支持和自研多模型适配层。
 
 [![Python](https://img.shields.io/badge/Python-≥3.11-blue.svg)](https://python.org)
-[![Version](https://img.shields.io/badge/Version-0.6.2-green.svg)]()
+[![Version](https://img.shields.io/badge/Version-0.7.0-green.svg)]()
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)]()
 
 ---
@@ -17,6 +17,7 @@
 | **双协作模式** | Handoff（控制权转移）+ as_tool（Agent 当工具调用），灵活覆盖所有协作场景 |
 | **编排 Agent** | SequentialAgent / ParallelAgent / LoopAgent，组合出任意复杂的工作流。支持 Loop 动态退出条件与 Parallel 提前取消增强 |
 | **@function_tool** | 一行装饰器把 Python 函数变成 LLM 工具，自动推断 JSON Schema。内建 `StructuredDataTool` 防止数据库注入 |
+| **图数据统一接口层** | 提供 `GraphAdapter + GraphRepository + GraphQueryTool`，开发/测试可切换 `networkx/litegraph`，生产可切换 `nebula` |
 | **安全内置** | Input/Output 双向 Guardrail + 三层权限控制；`run_skill_script` 当前为占位执行（SandboxExecutor 预留扩展） |
 | **记忆系统** | Mem0 集成，跨会话长期记忆 |
 | **9 个回调点** | before/after × agent/model/tool/handoff + error，任何环节可拦截定制 |
@@ -70,7 +71,7 @@ print(result.final_output)
 
 | 文档 | 说明 |
 |------|------|
-| **[QuickStart.md](QuickStart.md)** | 详细入门教程，包含 18 组从简到繁的完整示例（含 9A/9B） |
+| **[QuickStart.md](QuickStart.md)** | 详细入门教程，包含 18 组从简到繁的完整示例（含 8A/8B/8C、9A/9B/9C） |
 | **[Architecture.md](Architecture.md)** | 架构设计说明：六层分层、设计原则、核心流程 |
 | **[Reference.md](Reference.md)** | 完整 API 参考手册：所有类、方法、参数说明 |
 

{ni_agentkit-0.6.2 → ni_agentkit-0.7.0}/docs/Reference.md

@@ -21,6 +21,7 @@
   - [FunctionTool](#functiontool)
   - [BaseTool / BaseToolset](#basetool--basetoolset)
   - [StructuredDataTool (结构化数据源)](#structureddatatool-结构化数据源)
+  - [Graph 统一接口层（Adapter / Repository / Tool）](#graph-统一接口层adapter--repository--tool)
 - [Skill 类](#skill-类)
   - [Skill](#skill)
   - [SkillFrontmatter](#skillfrontmatter)
@@ -443,6 +444,50 @@ from agentkit.tools.nebula_tool import NebulaGraphTool
 
 ---
 
+### Graph 统一接口层（Adapter / Repository / Tool）
+
+用于在开发/测试/生产环境之间切换图后端，统一业务侧调用方式。
+
+```python
+from agentkit.tools.graph import (
+    GraphRepository,
+    GraphQueryTool,
+    NodeSpec,
+    EdgeSpec,
+    QuerySpec,
+    create_graph_repository,
+    create_graph_repository_from_env,
+)
+```
+
+**核心模型**：
+
+| 类型 | 关键字段 | 说明 |
+|------|----------|------|
+| `NodeSpec` | `node_id`、`label`、`properties` | 节点写入规范 |
+| `EdgeSpec` | `source_id`、`target_id`、`edge_type`、`directed`、`properties` | 边写入规范 |
+| `QuerySpec` | `operation`、`node_id/source_id/target_id`、`filters`、`limit` | 图查询参数规范（`neighbors/shortest_path/find_nodes/edges`） |
+| `GraphResult` | `backend`、`rows`、`summary`、`meta` | 统一查询返回结构 |
+
+**适配器与仓储**：
+
+| 组件 | 说明 |
+|------|------|
+| `GraphAdapter` | 适配器协议，统一 `upsert_node/upsert_edge/query/healthcheck/close` |
+| `NetworkXAdapter` | 开发态图后端，可选本地 JSON 持久化 |
+| `LiteGraphAdapter` | 基于 SQLite 的轻量图后端，适合测试与单机场景 |
+| `NebulaAdapter` | Nebula 生产后端适配器 |
+| `GraphRepository` | 业务统一入口，屏蔽底层后端差异 |
+| `create_graph_repository` | 按 `backend` + `config` 创建仓储 |
+| `create_graph_repository_from_env` | 按环境变量快速创建仓储（`AGENTKIT_GRAPH_*`） |
+
+**Tool 集成**：
+
+- `GraphQueryTool` 继承 `StructuredDataTool`，参数 Schema 固定为 `GraphQueryArgs`，底层通过 `GraphRepository.query()` 执行并返回标准化 `dict`。
+- 默认支持后端：`networkx` / `litegraph` / `nebula`。
+
+---
+
 ## Skill 类
 
 ### Skill

ni_agentkit-0.7.0/docs/TestReport.md

@@ -0,0 +1,92 @@
+# AgentKit 示例测试报告
+
+> 测试时间：`2026-04-27`  
+> 测试环境：`macOS (Apple Silicon)`  
+> 模型：Ollama `qwen3.5:cloud`  
+> AgentKit 版本：v0.7.0  
+> Thinking 模式：开启（默认）  
+> LLM 调用模式：非流式（默认）  
+> 缓存：开启（默认）  
+> 执行脚本：`examples/test_ollama.py`
+
+---
+
+## 测试结果
+
+| # | 示例 | 文件 | 耗时 | 状态 | 说明 |
+|---|------|------|-----:|:----:|------|
+| 1 | 基础对话 | `01_basic_chat.py` | 102.10s | ✅ | 运行通过 |
+| 2 | 工具调用 | `02_tool_calling.py` | 21.27s | ✅ | 运行通过 |
+| 3 | Skill 使用 | `03_skill_usage.py` | 62.60s | ✅ | 运行通过 |
+| 4 | 多 Agent 协作 | `04_multi_agent.py` | 194.60s | ✅ | 运行通过 |
+| 5 | 安全护栏 | `05_guardrail.py` | 8.23s | ✅ | 运行通过 |
+| 5H | HITL 工具触发（Playground 专用） | `05_human_in_the_loop.py` | 0.28s | ✅ | 运行通过 |
+| 6 | 编排 Agent | `06_orchestration.py` | 523.64s | ✅ | 运行通过（本轮最慢） |
+| 7 | 同步/异步/流式 | `07_sync_async_stream.py` | 19.73s | ✅ | 运行通过 |
+| 8 | 记忆系统（综合） | `08_memory.py` | 485.15s | ✅ | 运行通过 |
+| 8A | SimpleMemory | `08a_memory_simple_provider.py` | 30.39s | ✅ | 运行通过 |
+| 8B | Mem0Provider | `08b_memory_mem0_provider.py` | 0.25s | ✅ | 运行通过 |
+| 8C | 文件持久化 Memory | `08c_memory_file_provider.py` | 58.73s | ✅ | 运行通过 |
+| 9A | 结构化数据（SQL） | `09a_structured_data_sql.py` | 7.88s | ✅ | 运行通过 |
+| 9B | 结构化数据（图） | `09b_structured_data_graph.py` | 6.65s | ✅ | 运行通过 |
+| 9C | NebulaGraphTool（直调） | `09c_nebula_graph_tool.py` | 0.32s | ✅ | 运行通过 |
+| 10 | Skill 生命周期 | `10_skill_lifecycle.py` | 2.86s | ✅ | 运行通过 |
+| 11 | 编排增强 | `11_orchestration_enhancement.py` | 70.51s | ✅ | 运行通过 |
+| 12 | 序列化协议 | `12_run_context_serialization.py` | 0.27s | ✅ | 运行通过 |
+| 13 | Human in the Loop | `13_human_in_the_loop.py` | 5.81s | ✅ | 运行通过 |
+| 14 | Event 标准化 | `14_event_standardization.py` | 9.74s | ✅ | 运行通过 |
+| 15 | 多租户隔离 | `15_multi_tenant_isolation.py` | 0.31s | ✅ | 运行通过 |
+| 16 | 生命周期 Hooks | `16_lifecycle_hooks.py` | 0.26s | ✅ | 运行通过 |
+| 17 | Checkpoint + Handoff + Resume | `17_checkpoint_handoff_resume.py` | 0.17s | ✅ | 运行通过 |
+| 18 | ModelCosplay | `18_model_cosplay.py` | 0.17s | ✅ | 运行通过 |
+| 19 | HITL 确定性触发 | `19_hitl_deterministic.py` | 0.17s | ✅ | 运行通过（本轮最快） |
+| | **合计** | | **1612.09s** | **25/25** | |
+
+## 耗时分析
+
+- **最快示例**：19 HITL 确定性触发（0.17s）
+- **最慢示例**：6 编排 Agent（523.64s）
+- **耗时集中区间**：涉及多轮推理/记忆写入/编排循环的示例耗时显著更高
+
+## 各示例 LLM 调用次数估算
+
+| # | 示例 | LLM 调用次数 | 说明 |
+|---|------|:-----------:|------|
+| 1 | 基础对话 | 1 | 单次对话 |
+| 2 | 工具调用 | ~6 | 多次工具调用与回复生成 |
+| 3 | Skill 使用 | ~9 | load_skill + 工具调用 + 回复 |
+| 4 | 多 Agent 协作 | ~8 | as_tool + handoff 链路 |
+| 5 | 安全护栏 | ~3 | 拦截与放行混合路径 |
+| 5H | HITL 工具触发（Playground 专用） | ~0 | 仅触发挂起事件，不走 LLM |
+| 6 | 编排 Agent | ~12 | Sequential + Parallel + Loop |
+| 7 | 同步/异步/流式 | ~7 | 三种运行模式覆盖 |
+| 8 | 记忆系统（综合） | ~10 | 记忆读写与多轮对话 |
+| 8A | SimpleMemory | ~2 | 轻量关键词检索 |
+| 8B | Mem0Provider | ~0 | 未配置 `OPENAI_API_KEY` 时自动跳过 |
+| 8C | 文件持久化 Memory | ~2 | 本地文件读写 + 记忆检索 |
+| 9A | 结构化数据（SQL） | ~2 | 参数化查询 + 汇总 |
+| 9B | 结构化数据（图） | ~2 | 图查询 + 汇总 |
+| 9C | NebulaGraphTool（直调） | 0 | Mock 连接池直调，不依赖 LLM |
+| 10 | Skill 生命周期 | 1 | 单轮校验 |
+| 11 | 编排增强 | ~4 | loop_condition + early_exit |
+| 12 | RunContext 序列化 | 0 | 纯本地序列化 |
+| 13 | HITL 断点续跑 | ~3 | 挂起 + 恢复 |
+| 14 | 事件协议标准化 | 1 | 标准事件输出 |
+| 15 | 多租户隔离 | ~3 | 多会话隔离验证 |
+| 16 | 生命周期 Hooks | ~2 | Hook 链路验证 |
+| 17 | Checkpoint Handoff 恢复 | 0 | 自定义事件流，不依赖 LLM |
+| 18 | ModelCosplay | 0 | 仅验证模型改写开关与运行时覆盖逻辑，不调用 LLM |
+| 19 | HITL 确定性触发 | 0 | 自定义事件流，不依赖 LLM |
+
+## 已知问题
+
+| 问题 | 严重程度 | 说明 |
+|------|:--------:|------|
+| 运行异常 | - | 无，25 个示例全部通过 |
+
+## 运行方式
+
+```bash
+# 在 agentkit 目录执行
+python examples/test_ollama.py
+```

{ni_agentkit-0.6.2 → ni_agentkit-0.7.0}/examples/ollama/01_basic_chat.py

@@ -21,14 +21,15 @@ agent = Agent(
 )
 
 # 同步运行
-result = Runner.run_sync(agent, input="什么是量子计算？请用一句话解释。")
+if __name__ == "__main__":
+    result = Runner.run_sync(agent, input="什么是量子计算？请用一句话解释。")
 
-if result.success:
-    print(f"✅ 回复: {result.final_output}")
-else:
-    print(f"❌ 错误: {result.error}")
+    if result.success:
+        print(f"✅ 回复: {result.final_output}")
+    else:
+        print(f"❌ 错误: {result.error}")
 
-# 查看事件流
-print("\n📋 事件流:")
-for event in result.events:
-    print(f"  [{event.type}] {str(event.data)[:80]}")
+    # 查看事件流
+    print("\n📋 事件流:")
+    for event in result.events:
+        print(f"  [{event.type}] {str(event.data)[:80]}")

ni_agentkit-0.7.0/examples/ollama/05_human_in_the_loop.py

@@ -0,0 +1,42 @@
+"""
+示例 5（Playground/HITL 专用）：Human-in-the-loop Agent（Ollama 版）
+
+用途：
+- 提供一个可被 AgentHub `entry` 直接加载的 `agent` 实例；
+- 在工具执行前通过 `request_human_input(...)` 触发挂起，便于在 Playground 中演示 HITL。
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent
+from agentkit.tools.base_tool import request_human_input
+from agentkit.tools.function_tool import FunctionTool
+
+
+def confirm_action(action: str) -> str:
+    """敏感操作执行前请求人工确认。"""
+    request_human_input(f"即将执行敏感操作: {action}，请确认 (approve/reject)")
+
+
+def execute_action(action: str) -> str:
+    """执行操作（示例返回）。"""
+    return f"操作 '{action}' 已执行。"
+
+
+confirm_tool = FunctionTool.from_function(confirm_action)
+execute_tool = FunctionTool.from_function(execute_action)
+
+
+agent = Agent(
+    name="hitl-agent",
+    instructions=(
+        "你是一个需要人工审批的运维助手。"
+        "当用户要求执行敏感操作时，必须先调用 confirm_action 请求人工确认；"
+        "收到确认后再调用 execute_action。"
+    ),
+    # 使用纯本地模型，避免 cloud 变体在未鉴权/网络抖动时触发远端 502。
+    model="ollama/qwen3.5:4b",
+    tools=[confirm_tool, execute_tool],
+)

ni_agentkit-0.7.0/examples/ollama/08a_memory_simple_provider.py

@@ -0,0 +1,59 @@
+import asyncio
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, BaseMemoryProvider, Memory, Runner
+
+MODEL = "ollama/qwen3.5:cloud"
+
+
+class SimpleMemory(BaseMemoryProvider):
+    def __init__(self) -> None:
+        self._store: list[Memory] = []
+        self._counter = 0
+
+    async def add(self, content, *, user_id=None, agent_id=None, metadata=None):
+        self._counter += 1
+        item = Memory(id=str(self._counter), content=content)
+        self._store.append(item)
+        return [item]
+
+    async def search(self, query, *, user_id=None, agent_id=None, limit=10):
+        query_chars = set(query)
+        scored: list[tuple[int, Memory]] = []
+        for item in self._store:
+            overlap = len(query_chars & set(item.content))
+            if overlap > 0:
+                scored.append((overlap, item))
+        scored.sort(reverse=True, key=lambda x: x[0])
+        return [m for _, m in scored[:limit]]
+
+    async def get_all(self, *, user_id=None, agent_id=None):
+        return list(self._store)
+
+    async def delete(self, memory_id):
+        self._store = [m for m in self._store if m.id != memory_id]
+        return True
+
+
+async def main() -> None:
+    print("=== 示例 8A：SimpleMemory ===")
+    memory = SimpleMemory()
+    agent = Agent(
+        name="remembering",
+        instructions="你是贴心助手。根据记忆回答，回答简洁。",
+        model=MODEL,
+        memory=memory,
+        memory_async_write=False,
+    )
+
+    await Runner.run(agent, input="我叫小明，喜欢咖啡，讨厌茶。", user_id="user_001")
+    result = await Runner.run(agent, input="帮我推荐一杯饮料。", user_id="user_001")
+    print("推荐:", result.final_output)
+    print("记忆条数:", len(await memory.get_all()))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

ni_agentkit-0.7.0/examples/ollama/08b_memory_mem0_provider.py

@@ -0,0 +1,57 @@
+import asyncio
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner
+
+MODEL = "ollama/qwen3.5:cloud"
+
+
+async def main() -> None:
+    print("=== 示例 8B：Mem0Provider ===")
+    try:
+        from agentkit.memory.mem0_provider import Mem0Provider
+    except Exception:
+        print("未安装 mem0ai，跳过运行。")
+        print("安装: pip install mem0ai")
+        print("并启动 qdrant: docker run -p 6333:6333 qdrant/qdrant")
+        return
+
+    if not os.getenv("OPENAI_API_KEY"):
+        print("未设置 OPENAI_API_KEY，跳过运行。")
+        return
+
+    try:
+        memory = Mem0Provider(
+            {
+                "vector_store": {
+                    "provider": "qdrant",
+                    "config": {
+                        "collection_name": "agentkit_quickstart",
+                        "host": "localhost",
+                        "port": 6333,
+                    },
+                }
+            }
+        )
+    except Exception as exc:
+        print(f"Mem0 初始化失败，跳过运行: {exc}")
+        return
+
+    agent = Agent(
+        name="mem0-assistant",
+        instructions="你是贴心助手。根据记忆回答，回答简洁。",
+        model=MODEL,
+        memory=memory,
+        memory_async_write=False,
+    )
+
+    await Runner.run(agent, input="记住：我喜欢低糖拿铁。", user_id="user_001")
+    result = await Runner.run(agent, input="给我推荐一杯饮料。", user_id="user_001")
+    print("推荐:", result.final_output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())