From a52588cd0fb43d00ef13ec9f66b883c90dabc8f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BE=90=E6=B6=9B?= Date: Sat, 4 Jul 2026 06:21:36 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20README=20=E5=AE=8C?= =?UTF-8?q?=E6=95=B4=E7=89=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 8 节结构：定位 / 快速上手 / 核心模块 / 架构图 / 依赖关系 / 环境变量 / 参考项目 / 许可证 - 快速上手代码段（MockProvider）已验证在外部 crate 离线可编译运行 - 核心模块表覆盖五大模块（llm / prompt / tools / memory / agent） - ASCII 架构关系图 + Mermaid 模块依赖关系图 + 依赖规则说明 - 环境变量表列出 simple_visit 示例所需变量与推荐值 - 参考项目章节引用 4 个公开 Agent Harness 项目（OpenClaw / Hermes / OpenHuman / OpenHarness） - 许可证章节同步改为 Apache-2.0 单协议，附标准 boilerplate 并指向 LICENSE 文件 --- README.md | 245 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 244 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 57480f8..3ea8c2f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,246 @@ # AG Core -AG Core是一个用于提供构建智能体的底层工具箱，其中提供的功能主要包括基础的大模型调用的完整周期，提示词的组合与优化，记忆检索与管理、MCP与工具的调用等。 +> AG Core 是一个用于构建 AI 智能体（Agent）的 Rust 工具箱，提供 LLM 调用、提示词工程、工具系统、记忆检索、Agent 运行时等核心能力，所有模块通过 trait 抽象、可插拔、可离线测试。 + +## 这是什么？ + +AG Core 不是 Agent 产品，而是 Agent 的**底层依赖库**：上层应用（TUI / Bot 网关 / 业务服务）基于 AG Core 装配出符合自身场景的 Agent。设计原则： + +- **模块化** —— 五大功能领域（LLM / Prompt / Tool / Memory / Agent）独立 crate-internal 模块，通过 trait 解耦 +- **可插拔** —— LLM Provider、记忆存储、工具注册全部通过 trait 抽象，可替换为自有实现 +- **可离线** —— 公开 `MockProvider`，所有示例与测试无需 API key 即可运行 +- **异步优先** —— 所有 IO API 均为 `async`，基于 tokio 运行时 + +适合用来： + +- 搭建支持多轮对话 + 工具调用的智能体服务 +- 接入多家 LLM（OpenAI / Anthropic / DeepSeek / Qwen 等） +- 在 Agent 中组合提示词模板、知识检索、MCP 工具 +- 在 Rust 中复用一套"业务无关"的 Agent 基础设施 + +## 快速上手 + +5 分钟上手，无需 API key（使用 `MockProvider` 预设响应）。 + +**1. 添加依赖** + +```toml +[dependencies] +agcore = "0.1" +tokio = { version = "1", features = ["macros", "rt-multi-thread"] } +``` + +**2. 第一个 Agent** + +```rust,no_run +use std::sync::Arc; + +use agcore::agent::{Agent, AgentBuilder, AgentSession}; +use agcore::llm::hooks::HookExecutor; +use agcore::llm::mock::MockProvider; +use agcore::llm::provider::LlmProvider; +use agcore::llm::types::message::{ContentBlock, Message}; +use agcore::llm::types::response_v2::{MessageResponse, StopReason}; +use agcore::llm::types::Usage; +use agcore::tools::ToolRegistry; + +struct Greeter; + +impl Agent for Greeter { + fn name(&self) -> &str { "greeter" } + fn system_prompt(&self) -> Option<&str> { Some("你是一个中文助手，回答简短。") } +} + +fn text_response(text: &str) -> MessageResponse { + MessageResponse { + id: "r".into(), + model: "mock".into(), + message: Message::Assistant { + content: vec![ContentBlock::Text { text: text.into() }], + }, + usage: Usage::from_input_output(2, text.chars().count() as u32), + stop_reason: StopReason::Stop, + extra: Default::default(), + } +} + +#[tokio::main] +async fn main() { + // 1. MockProvider：预设响应，无须 API key + let provider: Arc = + Arc::new(MockProvider::new(vec![text_response("你好，我是 agcore。")])); + + // 2. 装配 RuntimeBundle（必填：provider / tool_registry / hook_executor） + let bundle = Arc::new( + AgentBuilder::new() + .provider(provider) + .tool_registry(Arc::new(ToolRegistry::new())) + .hook_executor(Arc::new(HookExecutor::new())) + .build() + .expect("装配 RuntimeBundle 失败"), + ); + + // 3. 创建会话并提交首轮 + let agent: Arc = Arc::new(Greeter); + let mut session = AgentSession::new(agent, "demo", bundle); + let resp = session.submit_turn("你好").await.expect("submit_turn 失败"); + println!("LLM: {}", resp.text()); +} +``` + +跑起来： + +```bash +cargo run +# LLM: 你好，我是 agcore。 +``` + +接真实 Provider（如 OpenAI）只需把 `MockProvider` 换成： + +```rust,no_run +use agcore::llm::provider::{create_provider, ProviderConfig, ProviderType}; + +let provider = create_provider( + ProviderType::OpenaiChat, + ProviderConfig { + base_url: "https://api.openai.com/v1".into(), + api_key: std::env::var("OPENAI_API_KEY").expect("未设置 OPENAI_API_KEY"), + model: "gpt-4o-mini".into(), + }, +).expect("创建 Provider 失败"); +``` + +更多端到端示例见 [`examples/`](./examples/) 目录（共 7 个，全部可 `cargo run --example `）： + +| 示例 | 说明 | +|------|------| +| `agent_session_demo` | Agent + 会话 + SessionMemory 完整链路（MockProvider 离线） | +| `custom_tool` | 自定义工具注册、单次 / 并行调用、权限检查 | +| `prompt_composer` | 提示词模板与组合器（纯离线） | +| `task_agent_demo` | Plan 解析、Step 状态机、错误路径 | +| `conversation_memory_demo` | 对话记忆滑动窗口与隔离 | +| `knowledge_search_demo` | 知识页面关键词检索 | +| `streaming_events_demo` | LLM 流式响应事件消费（含错误路径） | + +## 核心模块 + +| 模块 | 一句话说明 | +|------|----------| +| `agcore::llm` | LLM 调用周期（`LlmProvider` trait + `LlmCycle` 重试/用量 + 流式事件 + auto-compaction + Hook + 公开 `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` 任务编排） | + +## 架构关系图 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 应用层 (TUI / Bot 网关 / 业务服务) │ +└───────────────────────────┬─────────────────────────────────┘ + │ 使用 +┌───────────────────────────▼─────────────────────────────────┐ +│ Agent Runtime (agcore::agent) │ +│ Agent / AgentBuilder / RuntimeBundle / AgentSession / │ +│ SessionMemory / Plan / Step │ +└─────┬───────────────┬───────────────┬───────────────┬───────┘ + │ │ │ │ +┌─────▼─────┐ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ +│ LLM │ │ Prompt │ │ Tool │ │ Memory │ +│ agcore:: │ │ agcore:: │ │ agcore:: │ │ agcore:: │ +│ llm │ │ prompt │ │ tools │ │ memory │ +└─────┬─────┘ └─────────────┘ └─────┬───────┘ └──────┬──────┘ + │ │ │ + └──────────────┬────────────────┘ │ + ▼ │ + ┌─────────────────┐ │ + │ Mock Provider │◄──────────────────────┘ + │ 公开 API │ 离线测试 / 示例 + └─────────────────┘ +``` + +## 模块依赖关系 + +```mermaid +graph BT + LLM["llm
Provider / Cycle /
Hooks / Stream /
Compact / Mock"]:::core + Prompt["prompt
Template / Composer"]:::core + Tool["tools
BaseTool / Registry /
Permission / MCP"]:::core + Memory["memory
Store / Conversation /
Knowledge / Retriever"]:::core + Agent["agent
Agent / Builder /
Session / Plan"]:::core + + Prompt --> LLM + Tool --> LLM + Memory --> LLM + Agent --> LLM + Agent --> Prompt + Agent --> Tool + Agent --> Memory + + classDef core fill:#60a5fa,stroke:#2563eb,color:#fff +``` + +**依赖规则**： + +- `llm` 是叶子，被其他四个模块使用 +- `prompt` / `tools` / `memory` 互相不依赖，可独立使用 +- `agent` 是聚合层，把前四者"装配"为可用 Agent Runtime +- 上层应用只应依赖 `agent` + 必要的子模块，不应跨层直接 `use` + +## 环境变量 + +> AG Core 库本身不读环境变量。下表是 [`examples/simple_visit.rs`](./examples/simple_visit.rs) 这一真实调用示例所使用的环境变量，以及通常推荐的取值。 + +| 变量 | 必填 | 推荐值 | 说明 | +|------|------|-------|------| +| `OPENAI_API_KEY` | 用 OpenAI 时 | — | OpenAI / 兼容 Provider（DeepSeek / Qwen）的 API key | +| `OPENAI_BASE_URL` | 是 | `https://api.openai.com/v1` | OpenAI 兼容端点 base URL（DeepSeek/Qwen 用对应地址） | +| `OPENAI_MODEL` | 是 | `gpt-4o-mini` | OpenAI 模型名 | +| `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` | +| `RUST_LOG` | 否 | `agcore=info` | tracing 日志级别（其他 crate 可加 `=debug`） | + +示例（运行 `examples/simple_visit.rs` 真实调用 OpenAI）： + +```bash +export OPENAI_API_KEY=sk-... +export OPENAI_BASE_URL=https://api.openai.com/v1 +export OPENAI_MODEL=gpt-4o-mini +export PROVIDER=openai +export RUST_LOG=agcore=debug +cargo run --example simple_visit +``` + +## 参考项目 + +AG Core 在 Phase 4 设计阶段调研了 4 个 2026 年公开的 AI Agent 项目（详见 [`docs/note-agent-harness-references.md`](./docs/note-agent-harness-references.md)）： + +| 项目 | 类型 | 语言 | 借鉴点 | +|------|------|------|-------| +| [OpenClaw](https://github.com/openclaw/openclaw) | 消息网关 | TypeScript | 多渠道适配模式 | +| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | 自主学习智能体 | Python | 实体与会话解耦 | +| [OpenHuman](https://github.com/tinyhumansai/openhuman) | 桌面助手 | Rust + Tauri | 记忆树与 Token 压缩 | +| [OpenHarness](https://github.com/HKUDS/OpenHarness) | Agent Harness 框架 | Python | 显式依赖注入容器 + 三级权限 | + +AG Core 不"抄代码"，只参考架构模式。当前实现已经采纳： + +- **OpenHarness 风格** —— 显式 `RuntimeBundle` 依赖注入容器 +- **Hermes 风格** —— `Agent` trait（角色）与 `AgentSession`（会话）解耦 + +后续 v0.2+ 计划借鉴 OpenHuman 的 Memory Tree / TokenJuice 模式。 + +## 许可证 + +本项目基于 **Apache License 2.0** 授权。完整文本见 [`LICENSE`](./LICENSE)。 + +``` +Copyright 2026 AG Core Contributors + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 +``` \ No newline at end of file