docs: 完善 README 完整版

- 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

@@ -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<dyn LlmProvider> =
+        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<dyn Agent> = 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 <name>`）：
+
+| 示例 | 说明 |
+|------|------|
+| `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["<b>llm</b><br/>Provider / Cycle /<br/>Hooks / Stream /<br/>Compact / 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
+
+    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
+```