ni.agentkit 0.7.2__tar.gz → 0.7.4__tar.gz

{ni_agentkit-0.7.2 → ni_agentkit-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ni.agentkit
-Version: 0.7.2
+Version: 0.7.4
 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
@@ -31,11 +31,14 @@ Provides-Extra: google
 Requires-Dist: google-genai>=1.0.0; extra == "google"
 Provides-Extra: memory
 Requires-Dist: mem0ai>=0.1.0; extra == "memory"
+Provides-Extra: pdf
+Requires-Dist: pypdf>=5.0.0; extra == "pdf"
 Provides-Extra: all
 Requires-Dist: openai>=1.0.0; extra == "all"
 Requires-Dist: anthropic>=0.30.0; extra == "all"
 Requires-Dist: google-genai>=1.0.0; extra == "all"
 Requires-Dist: mem0ai>=0.1.0; extra == "all"
+Requires-Dist: pypdf>=5.0.0; extra == "all"
 Dynamic: license-file
 
 # AgentKit
@@ -53,7 +56,8 @@ Dynamic: license-file
 - 🧠 **多 LLM 适配器** — 自研统一适配层，5 个适配器覆盖主流 LLM（含 OpenAI Compatible）
 - 🛡️ **内置安全** — Guardrail 护栏 + 权限控制；`run_skill_script` 当前为占位执行（SandboxExecutor 预留扩展）
 - 🎭 **编排 Agent** — Sequential / Parallel / Loop 三种模式
-- 💾 **记忆系统** — 可选集成 Mem0，支持自定义记忆提供者
+- 💾 **记忆系统** — 可选集成 Mem0，支持自定义记忆提供者；`SimpleRAGAgent` 默认内置 `SQLiteMemoryProvider`
+- 📄 **SimpleRAGAgent** — 内置轻量 RAG（txt/md/markdown/pdf），支持 TF-IDF / BM25 / 向量检索，知识库与默认记忆统一落盘到 SQLite
 - ⚡ **全异步设计与 Hooks** — 底层全面采用 `asyncio`，流式响应（Streaming）、事件驱动（Event-Driven）、断点续跑机制（Checkpoint/Resume）。提供细粒度的 生命周期 Hooks，支持改写请求与结果。
 - 🏢 **多租户数据隔离** — 框架级支持 `user_id` / `session_id` 贯穿，Memory 默认分桶，Session 结束自动释放资源。
 - 🔗 **与大模型平台解耦** — 内置多模型支持，轻松对接 Ollama 等本地模型。
@@ -69,6 +73,7 @@ pip install "ni.agentkit[openai]"
 pip install "ni.agentkit[anthropic]"
 pip install "ni.agentkit[google]"
 pip install "ni.agentkit[memory]"
+pip install "ni.agentkit[pdf]"
 pip install "ni.agentkit[all]"
 ```
 
@@ -110,13 +115,13 @@ print(agentkit.get_examples_dir()) # 示例目录路径
 | 文档 | 说明 |
 |------|------|
 | [README](docs/README.md) | 项目概述与特性 |
-| [QuickStart](docs/QuickStart.md) | 18 组渐进式入门示例（含 9A/9B） |
+| [QuickStart](docs/QuickStart.md) | 18 组渐进式入门示例（含 8A/8B/8C、9A/9B/9C 与扩展示例） |
 | [Architecture](docs/Architecture.md) | 六层架构设计说明 |
 | [Reference](docs/Reference.md) | 完整 API 参考手册 |
 
 ## 🧪 示例
 
-安装包内含可运行示例（标准版 24 个 + Ollama 本地版 26 个）：
+安装包内含可运行示例（标准版 27 个 + Ollama 本地版 27 个）：
 
 ```bash
 # Ollama 本地版（无需 API Key）
@@ -150,8 +155,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.7.2-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.7.2.tar.gz             # 源码分发
+├── ni_agentkit-0.7.4-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.7.4.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.7.2 → ni_agentkit-0.7.4}/README.md

@@ -13,7 +13,8 @@
 - 🧠 **多 LLM 适配器** — 自研统一适配层，5 个适配器覆盖主流 LLM（含 OpenAI Compatible）
 - 🛡️ **内置安全** — Guardrail 护栏 + 权限控制；`run_skill_script` 当前为占位执行（SandboxExecutor 预留扩展）
 - 🎭 **编排 Agent** — Sequential / Parallel / Loop 三种模式
-- 💾 **记忆系统** — 可选集成 Mem0，支持自定义记忆提供者
+- 💾 **记忆系统** — 可选集成 Mem0，支持自定义记忆提供者；`SimpleRAGAgent` 默认内置 `SQLiteMemoryProvider`
+- 📄 **SimpleRAGAgent** — 内置轻量 RAG（txt/md/markdown/pdf），支持 TF-IDF / BM25 / 向量检索，知识库与默认记忆统一落盘到 SQLite
 - ⚡ **全异步设计与 Hooks** — 底层全面采用 `asyncio`，流式响应（Streaming）、事件驱动（Event-Driven）、断点续跑机制（Checkpoint/Resume）。提供细粒度的 生命周期 Hooks，支持改写请求与结果。
 - 🏢 **多租户数据隔离** — 框架级支持 `user_id` / `session_id` 贯穿，Memory 默认分桶，Session 结束自动释放资源。
 - 🔗 **与大模型平台解耦** — 内置多模型支持，轻松对接 Ollama 等本地模型。
@@ -29,6 +30,7 @@ pip install "ni.agentkit[openai]"
 pip install "ni.agentkit[anthropic]"
 pip install "ni.agentkit[google]"
 pip install "ni.agentkit[memory]"
+pip install "ni.agentkit[pdf]"
 pip install "ni.agentkit[all]"
 ```
 
@@ -70,13 +72,13 @@ print(agentkit.get_examples_dir()) # 示例目录路径
 | 文档 | 说明 |
 |------|------|
 | [README](docs/README.md) | 项目概述与特性 |
-| [QuickStart](docs/QuickStart.md) | 18 组渐进式入门示例（含 9A/9B） |
+| [QuickStart](docs/QuickStart.md) | 18 组渐进式入门示例（含 8A/8B/8C、9A/9B/9C 与扩展示例） |
 | [Architecture](docs/Architecture.md) | 六层架构设计说明 |
 | [Reference](docs/Reference.md) | 完整 API 参考手册 |
 
 ## 🧪 示例
 
-安装包内含可运行示例（标准版 24 个 + Ollama 本地版 26 个）：
+安装包内含可运行示例（标准版 27 个 + Ollama 本地版 27 个）：
 
 ```bash
 # Ollama 本地版（无需 API Key）
@@ -110,8 +112,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.7.2-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.7.2.tar.gz             # 源码分发
+├── ni_agentkit-0.7.4-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.7.4.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.7.2 → ni_agentkit-0.7.4}/__init__.py

@@ -13,6 +13,8 @@ from .llm.base import BaseLLM
 from .llm.registry import LLMRegistry
 from .llm.types import LLMConfig, LLMResponse, Message, ToolCall, ToolDefinition
 from .memory.base import BaseMemoryProvider, Memory
+from .rag.file_memory_provider import SQLiteMemoryProvider
+from .rag.simple_rag_agent import SimpleRAGAgent
 from .runner.events import Event, RunResult
 from .runner.runner import Runner
 from .safety.guardrails import (
@@ -55,5 +57,6 @@ __all__ = [
     "GuardrailResult", "InputGuardrail", "OutputGuardrail", "PermissionPolicy",
     "input_guardrail", "output_guardrail",
     "BaseMemoryProvider", "Memory",
+    "SimpleRAGAgent", "SQLiteMemoryProvider",
     "get_docs_dir", "get_examples_dir",
 ]

{ni_agentkit-0.7.2 → ni_agentkit-0.7.4}/agents/agent.py

@@ -293,11 +293,12 @@ class Agent(BaseAgent):
 
                 # 5. 调用 LLM（支持缓存）
                 cached = False
+                cache_key: str | None = None
 
                 # 检查缓存
                 if self.enable_cache:
                     cache = self._get_cache()
-                    cached_response = cache.get(messages, tool_defs if tool_defs else None)
+                    cache_key, cached_response = cache.get_with_key(messages, tool_defs if tool_defs else None)
                     if cached_response is not None:
                         response = cached_response
                         cached = True
@@ -318,7 +319,10 @@ class Agent(BaseAgent):
 
                     # 写入缓存
                     if self.enable_cache:
-                        cache.put(messages, tool_defs if tool_defs else None, response)
+                        if cache_key is not None:
+                            cache.put_with_key(cache_key, response)
+                        else:
+                            cache.put(messages, tool_defs if tool_defs else None, response)
 
                 cache_key_ms = 0.0
                 if self.enable_cache:

{ni_agentkit-0.7.2 → ni_agentkit-0.7.4}/docs/Architecture.md

@@ -471,6 +471,7 @@ agent.clear_cache()
 > - 缓存仅在单 Agent 实例内有效，重新创建 Agent 会清空缓存
 > - 默认最大 128 条缓存，LRU 淘汰最久未使用的条目
 > - 缓存实现内置 key 生成统计：`key_gen_calls / key_gen_total_ms / key_gen_last_ms / key_gen_avg_ms`
+> - 缓存实现对同一轮的缓存 key 计算做了复用（避免 miss 场景下重复算 key）
 
 ### 3. 记忆异步写入
 
@@ -616,12 +617,20 @@ agentkit/
 │   ├── base.py              #   BaseMemoryProvider
 │   └── mem0_provider.py     #   Mem0Provider
 │
+├── rag/                     # 轻量 RAG 核心模块
+│   ├── simple_rag_agent.py  #   SimpleRAGAgent（Agent 构建器）
+│   ├── document_store.py    #   本地文档加载、增量构建与 SQLite 持久化
+│   ├── loaders.py           #   txt / md / markdown / pdf 加载器
+│   ├── retrievers.py        #   TF-IDF / BM25 / Vector 检索器
+│   ├── sqlite_store.py      #   documents / chunks / memories 表结构
+│   └── file_memory_provider.py # SQLiteMemoryProvider + FileMemoryProvider 兼容别名
+│
 ├── utils/
 │   └── schema.py            #   函数签名 → JSON Schema
 │
 ├── examples/                # 示例
-│   ├── standard/            #   标准版示例（24 个：01-18 + 03B，含 8A/8B/8C、9A/9B/9C）
-│   ├── ollama/              #   Ollama 版示例（26 个：01-19 + 03B + 05_human_in_the_loop，含 8A/8B/8C、9A/9B/9C）
+│   ├── standard/            #   标准版示例（27 个：含 05_human_in_the_loop、19_hitl_deterministic、20_simple_rag_agent）
+│   ├── ollama/              #   Ollama 版示例（27 个：新增 20_simple_rag_agent）
 │   ├── quickstart.py
 │   └── test_ollama.py
 │

{ni_agentkit-0.7.2 → ni_agentkit-0.7.4}/docs/QuickStart.md

@@ -1,6 +1,6 @@
 # AgentKit 快速入门教程
 
-> 本教程将带你从零开始，通过 18 组由简到繁的示例（含 8A/8B/8C、9A/9B/9C），掌握 AgentKit 的核心用法。
+> 本教程将带你从零开始，通过 18 组由简到繁的主线示例（含 8A/8B/8C、9A/9B/9C）与扩展示例，掌握 AgentKit 的核心用法。
 
 ---
 
@@ -31,6 +31,7 @@
 - [示例 16：生命周期 Hooks 与 Callbacks](#16-生命周期-hooks-与-callbacks)
 - [示例 17：Checkpoint 深度恢复（Handoff 后挂起与原路径恢复）](#17-checkpoint-深度恢复handoff-后挂起与原路径恢复)
 - [示例 18：ModelCosplay（运行时改写预设模型）](#18-modelcosplay运行时改写预设模型)
+- [示例 20：SimpleRAGAgent（本地文档检索 + SQLite 记忆）](#20-simpleragagent本地文档检索--sqlite-记忆)
 - [性能提示](#性能提示)
 - [使用不同的 LLM](#使用不同的-llm)
 - [下一步](#下一步)
@@ -1178,6 +1179,46 @@ if __name__ == "__main__":
 
 ---
 
+## 示例 20：SimpleRAGAgent（本地文档检索 + SQLite 记忆）
+
+`SimpleRAGAgent` 是 AgentKit 内置的轻量 RAG 方案，默认支持：
+
+- 文档类型：`txt/md/markdown/pdf`
+- 检索器：`TF-IDF`、`BM25`、`Vector`（默认 `hybrid` 融合）
+- 存储：知识库 chunk 与默认记忆统一落盘到 `./.agentkit/rag/index.db`
+- 记忆：默认启用 SQLite 记忆，可通过 `enable_memory=False` 关闭
+
+```python
+from agentkit import Runner, SimpleRAGAgent
+
+rag = SimpleRAGAgent.from_directory(
+    knowledge_dir="./knowledge_base",
+    model="gpt-4o-mini",      # 任意 AgentKit 支持的模型标识
+    top_k=3,
+    default_retriever="hybrid",
+    storage_path=".agentkit/rag/index.db",  # 可选：自定义 SQLite 路径
+    enable_memory=True,                     # 可选：关闭时仅保留知识库检索
+)
+
+agent = rag.build_agent(name="simple-rag-assistant")
+result = Runner.run_sync(agent, input="请介绍一下 AgentKit 的核心能力")
+print(result.final_output)
+```
+
+如果知识库中包含 PDF，请额外安装：
+
+```bash
+pip install "ni.agentkit[pdf]"
+```
+
+`memory_file` 参数仍可继续传入，但当前版本会将其视为 SQLite 数据库路径，用于兼容旧代码。
+
+可运行文件：
+- `examples/standard/20_simple_rag_agent.py`
+- `examples/ollama/20_simple_rag_agent.py`
+
+---
+
 ## 性能提示
 
 当你感觉 Agent 响应较慢时，可以尝试以下优化：
@@ -1297,6 +1338,7 @@ agent = Agent(name="assistant", instructions="...")
 | [`03b_skill_tools_entry.py`](../examples/standard/03b_skill_tools_entry.py) | 示例 3B：Skill tools.entry 动态注册/发现 |
 | [`04_multi_agent.py`](../examples/standard/04_multi_agent.py) | 示例 4：多 Agent 协作 |
 | [`05_guardrail.py`](../examples/standard/05_guardrail.py) | 示例 5：安全护栏 |
+| [`05_human_in_the_loop.py`](../examples/standard/05_human_in_the_loop.py) | 扩展示例：HITL 工具触发（Playground） |
 | [`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：记忆系统（综合） |
@@ -1315,6 +1357,8 @@ agent = Agent(name="assistant", instructions="...")
 | [`16_lifecycle_hooks.py`](../examples/standard/16_lifecycle_hooks.py) | 示例 16：生命周期 Hooks 与 Callbacks |
 | [`17_checkpoint_handoff_resume.py`](../examples/standard/17_checkpoint_handoff_resume.py) | 示例 17：Checkpoint 深度恢复（Handoff + Resume） |
 | [`18_model_cosplay.py`](../examples/standard/18_model_cosplay.py) | 示例 18：ModelCosplay（运行时改写预设模型） |
+| [`19_hitl_deterministic.py`](../examples/standard/19_hitl_deterministic.py) | 扩展示例：HITL 确定性触发 |
+| [`20_simple_rag_agent.py`](../examples/standard/20_simple_rag_agent.py) | 示例 20：SimpleRAGAgent（本地文档检索 + SQLite 记忆） |
 
 ### 📁 `examples/ollama/` — Ollama 本地版（无需 API Key，完全本地运行）
 
@@ -1346,6 +1390,7 @@ agent = Agent(name="assistant", instructions="...")
 | [`17_checkpoint_handoff_resume.py`](../examples/ollama/17_checkpoint_handoff_resume.py) | 示例 17：Checkpoint 深度恢复（Handoff + Resume） |
 | [`18_model_cosplay.py`](../examples/ollama/18_model_cosplay.py) | 示例 18：ModelCosplay（运行时改写预设模型） |
 | [`19_hitl_deterministic.py`](../examples/ollama/19_hitl_deterministic.py) | 示例 19：HITL 确定性触发 |
+| [`20_simple_rag_agent.py`](../examples/ollama/20_simple_rag_agent.py) | 示例 20：SimpleRAGAgent（本地文档检索 + SQLite 记忆） |
 
 ---
 

{ni_agentkit-0.7.2 → ni_agentkit-0.7.4}/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.7.2-green.svg)]()
+[![Version](https://img.shields.io/badge/Version-0.7.4-green.svg)]()
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)]()
 
 ---
@@ -18,8 +18,9 @@
 | **编排 Agent** | SequentialAgent / ParallelAgent / LoopAgent，组合出任意复杂的工作流。支持 Loop 动态退出条件与 Parallel 提前取消增强 |
 | **@function_tool** | 一行装饰器把 Python 函数变成 LLM 工具，自动推断 JSON Schema。内建 `StructuredDataTool` 防止数据库注入 |
 | **图数据统一接口层** | 提供 `GraphAdapter + GraphRepository + GraphQueryTool`，开发/测试可切换 `networkx/litegraph`，生产可切换 `nebula` |
+| **SimpleRAGAgent** | 内置轻量 RAG 模块，支持 `txt/md/markdown/pdf` 文档加载、TF-IDF/BM25/向量检索，知识库与默认记忆统一落盘到 `./.agentkit/rag/index.db` |
 | **安全内置** | Input/Output 双向 Guardrail + 三层权限控制；`run_skill_script` 当前为占位执行（SandboxExecutor 预留扩展） |
-| **记忆系统** | Mem0 集成，跨会话长期记忆 |
+| **记忆系统** | Mem0 集成 + 自定义记忆提供者；`SimpleRAGAgent` 默认内置 `SQLiteMemoryProvider` |
 | **9 个回调点** | before/after × agent/model/tool/handoff + error，任何环节可拦截定制 |
 
 ---
@@ -35,6 +36,7 @@ pip install "ni.agentkit[openai]"    # OpenAI + 国内兼容厂商
 pip install "ni.agentkit[anthropic]" # Anthropic Claude
 pip install "ni.agentkit[google]"    # Google Gemini
 pip install "ni.agentkit[memory]"    # 记忆系统 (mem0)
+pip install "ni.agentkit[pdf]"       # PDF 知识库解析（可选）
 pip install "ni.agentkit[all]"       # 安装所有可选依赖
 ```
 

{ni_agentkit-0.7.2 → ni_agentkit-0.7.4}/docs/Reference.md

@@ -37,6 +37,8 @@
   - [PermissionPolicy](#permissionpolicy)
 - [记忆类](#记忆类)
   - [BaseMemoryProvider / Memory](#basememoryprovider)
+- [RAG 类](#rag-类)
+  - [SimpleRAGAgent](#simpleragagent)
 
 ---
 
@@ -575,6 +577,20 @@ from agentkit import LLMRegistry
 | `LLMRegistry.create_default()` | 创建默认模型实例 |
 | `LLMRegistry.register(prefix, adapter_class)` | 注册自定义适配器 |
 
+默认模型解析优先级：
+
+1. 若代码中调用过 `LLMRegistry.set_default(...)`，优先使用该默认配置。
+2. 否则会尝试从环境变量（或本地 `.env/.evn`）读取：`AGENTKIT_MODEL` → `AGENTKIT_DEFAULT_MODEL` → `AGENTKIT_STANDARD_MODEL` → `AGENTKIT_OLLAMA_MODEL`。
+3. 都未配置时回退到内置默认值。
+
+示例：
+
+```bash
+export AGENTKIT_DEFAULT_MODEL="ollama/qwen3.5:cloud"
+# 或在项目根目录写入 .env（无需额外依赖）
+# AGENTKIT_DEFAULT_MODEL=ollama/qwen3.5:cloud
+```
+
 **前缀路由表**：
 
 | 前缀 | 适配器 | 需要的包 |
@@ -746,13 +762,20 @@ class MyMemory(BaseMemoryProvider):
     async def delete(self, memory_id) -> bool: ...
 ```
 
-**内置实现**：`Mem0Provider`（需安装 `mem0ai`）
+**内置实现**：
+
+- `Mem0Provider`（需安装 `mem0ai`）
+- `SQLiteMemoryProvider`（轻量 SQLite 持久化实现，`SimpleRAGAgent` 默认使用）
 
 ```python
+from agentkit import SQLiteMemoryProvider
 from agentkit.memory.mem0_provider import Mem0Provider
 
 memory = Mem0Provider({"vector_store": {"provider": "qdrant", ...}})
 agent = Agent(memory=memory, ...)
+
+sqlite_memory = SQLiteMemoryProvider(".agentkit/rag/index.db")
+agent = Agent(memory=sqlite_memory, ...)
 ```
 
 Agent 会自动：
@@ -767,3 +790,57 @@ Agent 会自动：
 | `content` | `str` | 记忆内容 |
 | `metadata` | `dict` | 元数据 |
 | `score` | `float` | 相关性分数（检索时） |
+
+---
+
+## RAG 类
+
+### SimpleRAGAgent
+
+AgentKit 内置轻量 RAG 构建器：将本地知识库检索能力组合为标准 `Agent`。
+
+```python
+from agentkit import SimpleRAGAgent
+```
+
+**能力范围（V1）**：
+
+- 文档类型：`txt/md/markdown/pdf`
+- 检索器：`tfidf`、`bm25`、`vector`、`hybrid`
+- 存储：知识库源文件、chunks 与默认记忆统一写入 SQLite（默认 `./.agentkit/rag/index.db`）
+- 记忆：默认启用 `SQLiteMemoryProvider`，可通过 `enable_memory=False` 关闭
+- 模型：支持任意 AgentKit 可识别模型标识（`str | LLMConfig | BaseLLM`）
+- PDF：需额外安装 `ni.agentkit[pdf]` 或 `pypdf`
+
+**构造与工厂**：
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `__init__` | `(..., model, config=None, memory_provider=None, storage_path=None, enable_memory=None, memory_file=None)` | 直接构造；`memory_file` 为兼容参数，当前会映射为 SQLite 路径 |
+| `from_directory` | `(..., knowledge_dir, model, chunk_size=500, chunk_overlap=100, top_k=3, default_retriever="hybrid", storage_path=".agentkit/rag/index.db", enable_memory=True, memory_file=None, memory_provider=None)` | 推荐入口 |
+
+**实例方法**：
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `reload` | `() -> int` | 重新加载知识库并重建索引，返回 chunk 数 |
+| `search` | `(query, *, top_k=None, retriever=None) -> list[SearchHit]` | 程序化检索 |
+| `list_knowledge_files` | `() -> list[str]` | 列出知识库文件 |
+| `storage_path` | `() -> str` | 返回当前 SQLite 存储路径 |
+| `as_tools` | `() -> list[FunctionTool]` | 返回默认工具：`search_knowledge_base` / `list_knowledge_files` |
+| `build_agent` | `(*, name="simple-rag-assistant", instructions=None, tool_use_behavior="run_llm_again", memory_async_write=False, **kwargs) -> Agent` | 构建标准 Agent |
+
+**示例**：
+
+```python
+from agentkit import Runner, SimpleRAGAgent
+
+rag = SimpleRAGAgent.from_directory(
+    knowledge_dir="./knowledge_base",
+    model="ollama/qwen3.5:4b",
+    default_retriever="hybrid",
+    storage_path=".agentkit/rag/index.db",
+)
+agent = rag.build_agent(name="rag-assistant")
+print(Runner.run_sync(agent, input="这个项目是做什么的？").final_output)
+```

ni_agentkit-0.7.4/docs/TestReport.md

@@ -0,0 +1,64 @@
+# AgentKit 示例测试报告
+
+> 测试时间：`2026-06-15`  
+> 测试环境：`macOS (Apple Silicon)`  
+> 模型：`qwen/qwen3.6-flash` (DashScope)  
+> AgentKit 版本：v0.7.4  
+> Thinking 模式：开启（默认）  
+> LLM 调用模式：非流式（默认）  
+> 缓存：开启（默认）  
+> 执行脚本：`examples/test_standard.py`
+> 说明：本报告由 `examples/test_standard.py` 批跑生成，共覆盖 26 个样例；`20_simple_rag_agent.py` 不在自动批跑范围内。
+
+---
+
+## 测试结果
+
+| # | 示例 | 文件 | 耗时 | 状态 | 说明 |
+|---|------|------|-----:|:----:|------|
+| 1 | 01_basic_chat | `01_basic_chat.py` | 5.63s | ✅ | 运行通过 |
+| 2 | 02_tool_calling | `02_tool_calling.py` | 10.70s | ✅ | 运行通过 |
+| 3 | 03_skill_usage | `03_skill_usage.py` | 15.31s | ✅ | 运行通过 |
+| 4 | 03b_skill_tools_entry | `03b_skill_tools_entry.py` | 7.79s | ✅ | 运行通过 |
+| 5 | 04_multi_agent | `04_multi_agent.py` | 39.61s | ✅ | 运行通过 |
+| 6 | 05_guardrail | `05_guardrail.py` | 7.09s | ✅ | 运行通过 |
+| 7 | 05_human_in_the_loop | `05_human_in_the_loop.py` | 0.31s | ✅ | 运行通过 |
+| 8 | 06_orchestration | `06_orchestration.py` | 36.54s | ✅ | 运行通过 |
+| 9 | 07_sync_async_stream | `07_sync_async_stream.py` | 21.68s | ✅ | 运行通过 |
+| 10 | 08_memory | `08_memory.py` | 35.79s | ✅ | 运行通过 |
+| 11 | 08a_memory_simple_provider | `08a_memory_simple_provider.py` | 9.05s | ✅ | 运行通过 |
+| 12 | 08b_memory_mem0_provider | `08b_memory_mem0_provider.py` | 0.29s | ✅ | 运行通过 |
+| 13 | 08c_memory_file_provider | `08c_memory_file_provider.py` | 11.53s | ✅ | 运行通过 |
+| 14 | 09a_structured_data_sql | `09a_structured_data_sql.py` | 6.91s | ✅ | 运行通过 |
+| 15 | 09b_structured_data_graph | `09b_structured_data_graph.py` | 5.44s | ✅ | 运行通过 |
+| 16 | 09c_nebula_graph_tool | `09c_nebula_graph_tool.py` | 0.45s | ✅ | 运行通过 |
+| 17 | 10_skill_lifecycle | `10_skill_lifecycle.py` | 2.38s | ✅ | 运行通过 |
+| 18 | 11_orchestration_enhancement | `11_orchestration_enhancement.py` | 3.16s | ✅ | 运行通过 |
+| 19 | 12_run_context_serialization | `12_run_context_serialization.py` | 0.23s | ✅ | 运行通过 |
+| 20 | 13_human_in_the_loop | `13_human_in_the_loop.py` | 5.88s | ✅ | 运行通过 |
+| 21 | 14_event_standardization | `14_event_standardization.py` | 3.84s | ✅ | 运行通过 |
+| 22 | 15_multi_tenant_isolation | `15_multi_tenant_isolation.py` | 6.93s | ✅ | 运行通过 |
+| 23 | 16_lifecycle_hooks | `16_lifecycle_hooks.py` | 6.70s | ✅ | 运行通过 |
+| 24 | 17_checkpoint_handoff_resume | `17_checkpoint_handoff_resume.py` | 0.22s | ✅ | 运行通过 |
+| 25 | 18_model_cosplay | `18_model_cosplay.py` | 0.26s | ✅ | 运行通过 |
+| 26 | 19_hitl_deterministic | `19_hitl_deterministic.py` | 0.25s | ✅ | 运行通过 |
+| | **合计** | | **243.97s** | **26/26** | |
+
+## 耗时分析
+
+- **最快示例**：17_checkpoint_handoff_resume (0.22s)
+- **最慢示例**：04_multi_agent (39.61s)
+- **性能改进**：本次批跑合计 243.97s，耗时主要集中在 04_multi_agent / 06_orchestration / 08_memory 等编排类示例。
+
+## 已知问题
+
+| 问题 | 严重程度 | 说明 |
+|------|:--------:|------|
+| 运行异常 | - | 无，26 个示例全部通过 |
+
+## 运行方式
+
+```bash
+# 在 agentkit 目录执行
+python examples/test_standard.py
+```

ni_agentkit-0.7.4/examples/ollama/20_simple_rag_agent.py

@@ -0,0 +1,34 @@
+"""
+示例 20：SimpleRAGAgent（Ollama 本地版）
+
+运行前：
+  ollama serve
+  ollama pull qwen3.5:4b
+  mkdir -p ./knowledge_base
+  echo "AgentKit 支持 Tool、Skill、Memory 与多模型适配。" > ./knowledge_base/intro.txt
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Runner, SimpleRAGAgent
+from model_config import resolve_model
+
+
+def main() -> None:
+    rag = SimpleRAGAgent.from_directory(
+        knowledge_dir="./knowledge_base",
+        model=resolve_model("qwen3.5:4b"),
+        top_k=3,
+    )
+    agent = rag.build_agent(name="simple-rag-ollama")
+    result = Runner.run_sync(agent, input="AgentKit 有哪些核心能力？")
+    print("✅ 回复:", result.final_output)
+
+
+if __name__ == "__main__":
+    main()

{ni_agentkit-0.7.2 → ni_agentkit-0.7.4}/examples/ollama/README.md

@@ -46,6 +46,7 @@ pip install ni.agentkit
 | `17_checkpoint_handoff_resume.py` | Checkpoint 深度恢复 — Handoff 后挂起并原路径恢复 | 增强示例 |
 | `18_model_cosplay.py` | ModelCosplay — 运行时改写预设模型 | QuickStart 示例 18 |
 | `19_hitl_deterministic.py` | HITL 确定性触发（必现） | 扩展示例 |
+| `20_simple_rag_agent.py` | SimpleRAGAgent（本地文档检索 + 文件记忆） | 扩展示例 |
 
 ## 运行
 

ni_agentkit-0.7.4/examples/standard/05_human_in_the_loop.py

@@ -0,0 +1,42 @@
+"""
+示例 5（Playground/HITL 专用）：Human-in-the-loop Agent（标准版）
+
+用途：
+- 提供一个可被 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
+from model_config import resolve_model
+
+
+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。"
+    ),
+    model=resolve_model("gpt-4o-mini"),
+    tools=[confirm_tool, execute_tool],
+)

ni_agentkit-0.7.4/examples/standard/19_hitl_deterministic.py

@@ -0,0 +1,56 @@
+"""
+示例 19（Playground/HITL 专用）：确定性触发挂起（必现）
+
+用途：
+- 提供一个可被 AgentHub `entry` 直接加载的 `agent` 实例；
+- 首次运行必然发出 `suspend_requested`，便于 Playground 稳定演示 HITL 闭环。
+"""
+from __future__ import annotations
+
+import os
+import sys
+from typing import AsyncGenerator
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit.agents.base_agent import BaseAgent
+from agentkit.runner.context import RunContext
+from agentkit.runner.events import Event, EventType
+
+
+class DeterministicHITLAgent(BaseAgent):
+    async def _run_impl(self, ctx: RunContext) -> AsyncGenerator[Event, None]:
+        # 第一次进入会话时，确定性触发挂起。
+        if not ctx.state.get("deterministic_hitl_suspended_once"):
+            ctx.state["deterministic_hitl_suspended_once"] = True
+            suspension = ctx.register_suspension(
+                tool_call_id="det-hitl-1",
+                tool_name="manual_approval",
+                prompt="请审批该操作（approve/reject）",
+            )
+            yield Event(
+                agent=self.name,
+                type=EventType.SUSPEND_REQUESTED,
+                data={
+                    "suspension_id": suspension.suspension_id,
+                    "prompt": "请审批该操作（approve/reject）",
+                    "tool": "manual_approval",
+                    "tool_call_id": "det-hitl-1",
+                },
+            )
+            return
+
+        decision = "unknown"
+        for msg in reversed(ctx.messages):
+            if msg.get("role") == "tool" and msg.get("tool_call_id") == "det-hitl-1":
+                decision = msg.get("content", "unknown")
+                break
+
+        yield Event(
+            agent=self.name,
+            type=EventType.FINAL_OUTPUT,
+            data=f"已收到人工决策: {decision}",
+        )
+
+
+agent = DeterministicHITLAgent(name="deterministic-hitl-agent")

ni_agentkit-0.7.4/examples/standard/20_simple_rag_agent.py

@@ -0,0 +1,37 @@
+"""
+示例 20：SimpleRAGAgent（标准版）
+
+运行前：
+  export OPENAI_API_KEY="sk-..."
+  mkdir -p ./knowledge_base
+  echo "AgentKit 是一个 Python 原生 Agent 框架。" > ./knowledge_base/intro.txt
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Runner, SimpleRAGAgent
+from model_config import resolve_model
+
+
+def create_agent():
+    rag = SimpleRAGAgent.from_directory(
+        knowledge_dir="./knowledge_base",
+        model=resolve_model("gpt-4o-mini"),
+        top_k=3,
+    )
+    return rag.build_agent(name="simple-rag-standard")
+
+
+def main() -> None:
+    agent = create_agent()
+    result = Runner.run_sync(agent, input="AgentKit 是什么？")
+    print("✅ 回复:", result.final_output)
+
+
+if __name__ == "__main__":
+    main()