xt/agcore
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 增补 README 介绍内容并对齐至 v0.3 实际实现

Browse Source 
- 版本号 0.2 → 0.3
- 示例数量 10 → 18，追加 8 个示例条目
- 模块表新增 engine / document，扩展 llm / memory / agent 描述
- 架构图新增 Engine 层、Document 模块、Memory 子模块展开
- 依赖关系图新增 Engine / Document 节点，修正依赖规则
- 环境变量 PROVIDER 移除未实现的 openai-response，新增 ollama
- 修正示例行数描述与参考项目段措辞
This commit is contained in:
徐涛
2026-07-17 16:53:43 +08:00
parent 28d6a1c166
commit 385560a1dd
1 changed files with 49 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -22
View File
@@ -26,7 +26,7 @@ AG Core 不是 Agent 产品，而是 Agent 的**底层依赖库**：上层应用
```toml
[dependencies]
agcore = "0.2"
agcore = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```
@@ -110,11 +110,11 @@ let provider = create_provider(
).expect("创建 Provider 失败");
```
更多端到端示例见 [`examples/`](./examples/) 目录（共 10 个，全部可 `cargo run --example <name>`）：
更多端到端示例见 [`examples/`](./examples/) 目录（共 18 个，全部可 `cargo run --example <name>`）：
| 示例 | 说明 |
|------|------|
| `quick_start` | **30 行最小示例**：MockProvider + EchoTool + submit_turn，新用户 5 分钟上手 |
| `quick_start` | **最短可运行示例**：MockProvider + EchoTool + submit_turn，新用户 5 分钟上手 |
| `end_to_end` | **完整集成示例**：3 工具 + 3 轮对话 + SqliteStore 持久化跨连接验证 |
| `agent_session_demo` | Agent + 会话 + SessionMemory 完整链路（MockProvider 离线） |
| `custom_tool` | 自定义工具注册、单次 / 并行调用、权限检查 |
@@ -124,16 +124,26 @@ let provider = create_provider(
| `knowledge_search_demo` | 知识页面关键词检索 |
| `streaming_events_demo` | LLM 流式响应事件消费（含错误路径） |
| `simple_visit` | 真实 LLM 调用（OpenAI / Anthropic，设置 `OPENAI_*` / `ANTHROPIC_*` 环境变量） |
| `document_demo` | 文档分割：RecursiveCharacterSplitter 将长文本切分为可嵌入片段 |
| `knowledge_graph_demo` | 知识图谱：实体-关系 CRUD、BFS 遍历、关键词/标签检索 |
| `context_slot_demo` | 多上下文分区：ContextSlot 分区管理、FocusedConfig 聚焦策略 |
| `sub_agent_dispatch_demo` | 子任务分发：SubTask 异步执行与结果汇聚 |
| `dispatch_stream_demo` | 分发流式输出：SubTaskStreamEvent 实时消费 |
| `engine_demo` | Agent 执行引擎：SessionManager 会话树 + Checkpointer 快照恢复 |
| `bridge_keys_demo` | 桥接键：Agent 间上下文键值透传 |
| `agent_switch_demo` | Agent 热切换：会话中动态切换 Agent 角色 |
## 核心模块
| 模块 | 一句话说明 |
|------|----------|
| `agcore::llm` | LLM 调用周期（`LlmProvider` trait + `LlmCycle` 重试/用量 + 流式事件 + auto-compaction + Hook + 公开 `MockProvider`） |
| `agcore::llm` | LLM 调用周期（`LlmProvider` trait + `LlmCycle` 重试/用量 + 流式工具循环 + auto-compaction + Hook + `Embedding` trait + 公开 `MockProvider`） |
| `agcore::prompt` | 提示词工程（`PromptTemplate` 变量插值 + `PromptTemplateRegistry` + `PromptComposer` 多角色消息构造 + `validate_messages`） |
| `agcore::tools` | 工具系统（`BaseTool` trait + `ToolRegistry` 注册/调用 + `PermissionChecker` 黑白名单 + MCP stdio 客户端） |
| `agcore::memory` | 记忆系统（`MemoryStore` trait + `InMemoryStore` 默认实现 + `ConversationMemory` 滑动窗口 + `KnowledgeStore` + `MemoryRetriever`） |
| `agcore::agent` | Agent 运行时（`Agent` trait 角色定义 + `AgentBuilder` + `RuntimeBundle` 依赖注入 + `AgentSession` 会话 + `SessionMemory` + `Plan`/`Step` 任务编排） |
| `agcore::memory` | 记忆系统（`MemoryStore` trait + `InMemoryStore` / `SqliteStore` + `ConversationMemory` 滑动窗口 + `KnowledgeStore` + `KnowledgeGraph` 图谱 + `VectorStore` 向量 + `RagPipeline` + `MemoryRetriever` 混合检索） |
| `agcore::agent` | Agent 运行时（`Agent` trait + `AgentBuilder` + `RuntimeBundle` + `AgentSession` + 多上下文分区 + 摘要自动生成 + 快照恢复 + `Plan`/`Step` 任务编排） |
| `agcore::engine` | Agent 执行引擎（`SessionManager` 会话树 + `Checkpointer` time-travel 快照 + 子任务分发 + Agent 热切换） |
| `agcore::document` | 文档分割（`Document` 类型 + `RecursiveCharacterSplitter` 递归字符级分割） |
## 架构关系图
@@ -143,9 +153,14 @@ let provider = create_provider(
└───────────────────────────┬─────────────────────────────────┘
│ 使用
┌───────────────────────────▼─────────────────────────────────┐
│ Agent Runtime (agcore::agent) │
│ Agent Engine (agcore::engine) │
│ SessionManager / Checkpointer / SubTask 分发 / Agent 切换 │
└───────────────────────────┬─────────────────────────────────┘
│ 编排
┌───────────────────────────▼─────────────────────────────────┐
│ Agent Runtime (agcore::agent) │
│ Agent / AgentBuilder / RuntimeBundle / AgentSession / │
│ SessionMemory / Plan / Step │
│ ContextSlot / SummaryConfig / Plan / Step │
└─────┬───────────────┬───────────────┬───────────────┬───────┘
│ │ │ │
┌─────▼─────┐ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
@@ -154,10 +169,15 @@ let provider = create_provider(
│ llm │ │ prompt │ │ tools │ │ memory │
└─────┬─────┘ └─────────────┘ └─────┬───────┘ └──────┬──────┘
│ │ │
└──────────────┬────────────────┘ │
▼ │
┌─────────────────┐ │
│ Mock Provider │◄──────────────────────┘
│ ┌──────────┐ │ ┌───────────┴──────┐
│ │ Document │ │ │ Graph / Vector │
│ │ agcore:: │ │ │ RagPipeline │
│ │ document │ │ │ Retriever │
│ └──────────┘ │ └──────────────────┘
└──────────────┬────────────────┘
▼
┌─────────────────┐
│ Mock Provider │
│ 公开 API │ 离线测试 / 示例
└─────────────────┘
```
@@ -166,28 +186,35 @@ let provider = create_provider(
```mermaid
graph BT
LLM["<b>llm</b><br/>Provider / Cycle /<br/>Hooks / Stream /<br/>Compact / Mock"]:::core
LLM["<b>llm</b><br/>Provider / Cycle /<br/>Hooks / Stream /<br/>Compact / Embedding /<br/>Mock"]:::core
Prompt["<b>prompt</b><br/>Template / Composer"]:::core
Tool["<b>tools</b><br/>BaseTool / Registry /<br/>Permission / MCP"]:::core
Memory["<b>memory</b><br/>Store / Conversation /<br/>Knowledge / Retriever"]:::core
Agent["<b>agent</b><br/>Agent / Builder /<br/>Session / Plan"]:::core
Tool["<b>tools</b><br/>BaseTool / Registry /<br/>MCP"]:::core
Memory["<b>memory</b><br/>Store / Conversation /<br/>Knowledge / Graph /<br/>VectorStore / RagPipeline /<br/>Retriever"]:::core
Agent["<b>agent</b><br/>Agent / Builder /<br/>Session / ContextSlot /<br/>Summary / Plan"]:::core
Engine["<b>engine</b><br/>SessionManager /<br/>Checkpointer /<br/>SubTask / Switch"]:::phase
Document["<b>document</b><br/>Splitter"]:::phase
Prompt --> LLM
Tool --> LLM
Memory --> LLM
Memory --> Document
Document --> LLM
Agent --> LLM
Agent --> Tool
Agent --> Memory
Engine --> Agent
classDef core fill:#60a5fa,stroke:#2563eb,color:#fff
classDef phase fill:#a78bfa,stroke:#7c3aed,color:#fff
```
**依赖规则**：
- `llm` 是叶子，被其他四个模块使用
- `prompt` / `tools` / `memory` 互相不依赖，可独立使用
- `agent` 编译期依赖 `llm` / `tools` / `memory`，与 `prompt` 无直接编译依赖（system prompt 以 `&str` 形式传入）
- 上层应用只应依赖 `agent` + 必要的子模块，不应跨层直接 `use`
- `llm` 被 `agent` / `engine` 使用，同时 `llm::cycle` 依赖 `tools::ToolRegistry`（用于工具调用循环）
- `prompt` / `tools` 互不依赖，可独立使用；`memory` 依赖 `document`（向量存储的分割器）和 `llm`（embedding trait）
- `agent` 编译期依赖 `llm` / `tools` / `memory`，与 `prompt` / `document` 无直接编译依赖（system prompt 以 `&str` 形式传入，文档分割由应用层处理）
- `engine` 编译期依赖 `agent`，提供会话树管理和快照恢复能力
- 上层应用通常依赖 `engine`（完整能力）或 `agent`（轻量场景），不应跨层直接 `use`
## 环境变量
@@ -201,7 +228,7 @@ graph BT
| `ANTHROPIC_API_KEY` | 用 Anthropic 时 | — | Anthropic Claude API key |
| `ANTHROPIC_BASE_URL` | 是 | `https://api.anthropic.com` | Anthropic 兼容端点 base URL |
| `ANTHROPIC_MODEL` | 是 | `claude-3-5-sonnet-latest` | Claude 模型名 |
| `PROVIDER` | 否 | `openai` | Provider 类型：`openai` / `openai-response` / `anthropic` / `deepseek` / `qwen` |
| `PROVIDER` | 否 | `openai` | Provider 类型：`openai` / `anthropic` / `deepseek` / `qwen` / `ollama` |
| `RUST_LOG` | 否 | `agcore=info` | tracing 日志级别（其他 crate 可加 `=debug`） |
示例（运行 `examples/simple_visit.rs` 真实调用 OpenAI）：
@@ -226,7 +253,7 @@ AG Core 在 Phase 4 设计阶段调研了 4 个 2026 年公开的 AI Agent 项
| [OpenHuman](https://github.com/tinyhumansai/openhuman) | 桌面助手 | Rust + Tauri | 记忆树与 Token 压缩 |
| [OpenHarness](https://github.com/HKUDS/OpenHarness) | Agent Harness 框架 | Python | 显式依赖注入容器 + 三级权限 |
AG Core 不"抄代码"，只参考架构模式。当前实现已经采纳：
AG Core 借鉴了以下架构模式（不直接复用代码）：
- **OpenHarness 风格** —— 显式 `RuntimeBundle` 依赖注入容器
- **Hermes 风格** —— `Agent` trait（角色）与 `AgentSession`（会话）解耦