feat: add cookbook & fix bugs in cookbook

cookbook/new-zh/concept.md

@@ -0,0 +1,156 @@
+# 概念
+
+本章介绍了AgentScope Runtime的核心概念。
+
+## 架构
+
+AgentScope Runtime使用模块化架构，包含几个关键组件：
+
+```mermaid
+flowchart LR
+    %% 服务模块
+    subgraph Service["💼 服务"]
+        MS["记忆服务"]
+        SS["会话服务"]
+        STS["状态服务"]
+        SBS["沙箱服务"]
+    end
+
+    %% 沙箱模块
+    subgraph Sandbox["🐳 沙箱"]
+        BS["浏览器沙箱"]
+        FS["文件系统沙箱"]
+        GS["GUI 沙箱"]
+        CSB["云沙箱"]
+        MSB["移动端沙箱"]
+        ETC["更多..."]
+    end
+
+    %% 适配器模块（大块）
+    subgraph Adapter["🔌 适配器"]
+        MAD["记忆适配器"]
+        SAD["会话适配器"]
+        STAD["状态适配器"]
+        SBAD["沙箱工具适配器"]
+    end
+
+    %% Agent 模块（大块）
+    subgraph Agent["🤖 智能体"]
+        AG["AgentScope Java"]
+        AG_NOTE["（更多...）"]
+    end
+
+    %% 应用层
+    subgraph AgentAPP["📦 智能体应用"]
+        RA["运行器"]
+    end
+
+    %% 部署模块
+    subgraph Deployer["🚀 部署器"]
+        CT["容器部署"]
+        KD["K8s 部署"]
+        DP["云部署"]
+        LD["本地部署"]
+    end
+
+    %% 外部协议
+    OAI["OpenAI Responses API SDK"]:::ext
+    A2A["Google A2A 协议"]:::ext
+    CUS["自定义端点"]:::ext
+
+    MS --> MAD
+    SS --> SAD
+    STS --> STAD
+    SBS --> SBAD
+
+    BS --> SBS
+    FS --> SBS
+    GS --> SBS
+    CSB --> SBS
+    MSB --> SBS
+    ETC --> SBS
+
+    %% 大块到大块的连接
+    Adapter --> Agent
+
+    AG --> RA
+    RA --> CT
+    RA --> KD
+    RA --> DP
+    RA --> LD
+
+    %% 整个部署模块连接到外部协议
+    Deployer --> OAI
+    Deployer --> A2A
+    Deployer --> CUS
+
+    %% 样式
+    classDef small fill:#0066FF,stroke:#004CBE,color:#FFFFFF,font-weight:bold
+    classDef big fill:#99D6FF,stroke:#004CBE,color:#FFFFFF,font-weight:bold
+    classDef ext fill:#FFFFFF,stroke:#000000,color:#000000,font-weight:bold
+
+    class Tools,Service,Sandbox,Adapter,Agent,AgentAPP,Deployer big
+    class RT,ST,PT,MS,SS,STS,SBS,BS,FS,GS,CSB,MSB,ETC,TAD,MAD,SAD,STAD,SBAD,AG,AG_NOTE,RA,CT,KD,DP,LD small
+
+```
+
+- **Agent**：处理请求并生成响应的核心AI组件，在Runtime中，Agent的构建推荐使用AgentScope框架。
+- **AgentApp**: 作为智能体应用入口，负责对外提供 API 接口、路由注册、配置加载，并将请求交由 Runner 调用执行
+- **Runner**：在运行时编排智能体执行并管理部署。它处理智能体生命周期、会话管理、流式响应和服务部署。
+- **Deployer**：将Runner部署为服务，提供健康检查、监控、生命周期管理、使用SSE的实时响应流式传输、错误处理、日志记录和优雅关闭。
+- **Tool**: 提供开箱即用的沙箱工具支持。
+- **Service**：提供智能体所需要的管理服务，比如记忆管理，沙箱管理等。
+- **Adapter**：将Runtime提供的组件/模块适配到Agent框架的适配器
+
+### 关键组件
+
+#### 1. Agent
+
+`Agent` 是处理请求并生成响应的核心组件。市面上已有大量的开发框架包含了Agent类，Runtime本身不提供额外的Agent类，开发者可以使用AgentScope开发需要的Agent。
+
+#### 2. AgentApp
+
+`AgentApp` 是 AgentScope Runtime 中的 **应用入口点**，用于将 Agent 部署为可对外提供服务的 API 应用。
+
+它的职责是：
+
+- 初始化并绑定 **Agent** 和 **AgentScopeAgentHandler**，自动构建 **Runner**，将请求委托给运行时处理
+- 提供标准化的 **HTTP API 接口**（含健康检查）
+- 支持 **Server-Sent Events (SSE)** 以及标准 JSON 响应
+- 允许注册中间件、任务队列（Celery）以及自定义路由
+- 管理应用生命周期（支持 `before_start` / `after_finish` 钩子）
+- 将Agent应用部署为服务
+
+#### 3. AgentScopeAgentHandler
+
+`AgentScopeAgentHandler` 类提供灵活且可扩展的智能体执行逻辑。它管理：
+
+- 通过 `streamQuery` 支持用户自定义请求执行逻辑
+- 流式响应
+
+#### 4. Deployer
+
+`Deployer`（实现为 `deployer-maven-plugin`插件）提供生产级别的部署功能：
+
+- maven打包过程中自动**构建 Docker 镜像**
+- 可选推送至远程仓库、一键部署到 **K8s 集群**以及部署到 **AgentRun**
+
+#### 5. Sandbox & Tool
+
+Runtime提供两种工具接入方式
+- 即用型工具，即由服务提供商提供的开箱即用的服务，比如RAG
+- 工具沙箱，即运行在runtime里安全可控的工具，比如浏览器
+
+
+#### 6. Service
+
+`Service`包含如下几种：
+
+- `state_service` 状态服务
+- `memory_service` 智能体记忆服务
+- `sandbox_service` 即沙箱服务
+- `session_history_service` 即会话历史记录保存服务
+
+#### 7. Adapter
+
+`Adapter`按照不同Agent框架分类，包含记忆适配器、会话适配器、消息协议适配器等。

cookbook/new-zh/contribute.md

@@ -0,0 +1,92 @@
+# 如何贡献
+
+感谢您对AgentScope Runtime Java 项目的关注。
+
+AgentScope Runtime Java 是一个专注于智能体部署和安全工具执行的开源项目，拥有一个乐于帮助新贡献者的友好开发者社区。我们欢迎各种类型的贡献，从代码改进到文档编写。
+
+## 社区
+
+参与 AgentScope Runtime Java 项目的第一步是加入我们的讨论，通过不同的沟通渠道与我们联系。以下是与我们建立联系的几种方式：
+
+- **GitHub Discussions**: 提问和分享经验（请使用**英语**）
+- **Discord**: 加入我们的 [Discord频道](https://discord.gg/eYMpfnkG8h) 进行实时讨论
+- **DingTalk**: 中文用户可以加入我们的 [钉钉群](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)
+
+## 报告问题
+
+### Bugs
+
+如果您在 AgentScope Runtime Java 中发现了bug，请首先使用最新版本进行测试，确保您的问题尚未被修复。如果没有，请在 GitHub上搜索我们的问题列表，查看是否已有类似问题被提出。
+
+- 如果确认该 bug 尚未被报告，请在编写任何代码之前先提交一个 bug 问题。提交问题时，请包含：
+- 清晰的问题描述
+- 重现步骤
+- 代码/错误信息
+  - 环境详情（操作系统、JDK 版本）
+
+- 受影响的组件（例如 Engine 模块、Sandbox 模块等）
+
+### 安全问题
+
+如果您在 AgentScope Runtime Java 中发现安全问题，请通过 [阿里巴巴安全响应中心(ASRC)](https://security.alibaba.com/)向我们报告。
+
+## 功能需求
+
+如果您希望AgentScope Runtime Java 具有某个不存在的功能，请在 GitHub 上提交功能请求问题，描述
+
+- 功能及其目的
+- 应该如何工作
+- 安全考虑（如果适用）
+
+## 贡献代码
+
+如果您想为 AgentScope Runtime Java 贡献新功能或bug 修复，请首先在 GitHub 问题中讨论您的想法。如果没有相关问题，请创建一个。可能已经有人在处理它，或者它可能有特殊的复杂性（特别是 Sandbox 功能的安全考虑），您在开始编码之前应该了解这些。
+
+### Fork 和创建分支
+
+Fork [AgentScope Runtime Java 主分支代码](https://github.com/agentscope-ai/agentscope-runtime-java) 并将其克隆到本地机器。有关帮助，请参见 GitHub 帮助页面。
+
+创建一个具有描述性名称的分支。
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 进行更改
+
+- 编写清晰、注释良好的代码
+- 遵循现有代码风格
+- 为新功能/修复添加测试
+- 根据需要更新文档 Test Your Changes
+
+### 测试您的更改
+
+运行测试套件以确保您的更改不会破坏现有功能：
+
+```bash
+mvn test
+```
+
+### 提交您的更改
+
+1. 使用清晰的消息提交您的更改：
+
+```bash
+git commit -m "Add: brief description of your changes"
+```
+
+2. 推送到您的Fork：
+
+```bash
+git push origin feature/your-feature-name
+```
+
+3. 从您的分支向主仓库创建Pull Request (PR)，并提供**清晰的描述**
+
+### 代码审查流程
+
+- 所有 PR 都需要维护者的审查
+- 处理任何反馈或请求的更改
+- 一旦批准，您的 PR 将被合并
+
+感谢您为 AgentScope Runtime Java 做出贡献！

cookbook/new-zh/deployment.md

@@ -0,0 +1,76 @@
+# 部署
+
+本章节聚焦于如何在 AgentScope Runtime Java 上部署智能体。在完成概念与快速上手之后，部署是让实验性原型进入稳定运行的关键一步。我们将首先给出部署思路与整体流程，然后串联后续的服务、简单部署、进阶部署以及 React Agent 样例 子章节，帮助你快速定位适合的路径。
+
+## 为什么需要部署
+
+- **获得稳定的运维能力**：Runtime 提供标准化的服务生命周期、健康检查与扩展能力，简化监控与回滚。
+- **复用生态能力**：通过统一的部署方式，可以复用记忆、沙箱、状态等基础服务，避免重复造轮子。
+
+## 部署路径概览
+
+部署过程通常包含以下几个阶段：
+
+1. **准备工作**：安装 Runtime、准备模型与工具、配置环境变量与凭证。
+2. **基础服务启动**：根据业务需要选择记忆、会话、沙箱等服务实现。
+3. **Agent App 定义**：基于 `AgentApp` 模块编排智能体、工具与工作流逻辑，形成可部署的应用入口。
+4. **运行**：在本地、容器或云原生环境中启动 Runtime。
+5. **升级与扩展**：使用高级部署与 React Agent 能力实现多区域部署、混合编排或 UI 交互。
+
+## 前置准备清单
+
+- Java 环境（**JDK 17+**）及必要依赖。
+- 至少一个可用的大模型接入（例如 DashScope、OpenAI 或自建推理服务）。
+- 目标部署平台（本地、Docker、Kubernetes 等）的访问与权限。
+- 对应的工具/沙箱权限，如浏览器自动化、文件系统或自定义工具服务。
+
+## 子章节导读
+
+### 服务
+
+`Service` 章节介绍了 Runtime 内建的会话历史、记忆、沙箱、状态等基础服务，以及统一的生命周期接口。阅读该章节可以了解如何选择合适的实现（内存、Redis、Tablestore 等），以及如何通过 `start()`、`stop()`、`health()` 管理服务，确保部署环境具备稳定的支撑能力。
+详细文档见 [服务与适配器](service/service.md)。
+
+### 简单部署
+
+Runtime 包含一个简单的部署工具 `AgentApp` 。它是将多个智能体、工具与上下文串联的应用形态。子章节会说明：
+
+- 如何定义 `AgentApp` 配置、路由和会话管理。
+- 如何在部署阶段绑定服务、注入沙箱，并暴露 HTTP/gRPC/CLI 等接口。
+- 如何编写自定义 handler 与插件，满足不同业务流。
+
+在实际部署中，Agent App 通常作为主要入口进程，与基础服务共同组成运行时。
+完整示例可参考 [简单部署](deployment/agent_app.md)。
+
+### 高级部署
+
+当需要满足更高的可用性与可观测性要求时，可参考高级部署章节，内容包括：
+
+- 使用容器编排（如 Docker、Kubernetes）运行多服务拓扑。
+- 使用阿里云函数计算 AgentRun 运行函数化 Agent
+- 配置多地区/多模型冗余、灰度发布与扩缩策略。
+
+该章节适合有生产场景或需要多团队协作的读者。
+更多方案见 [高级部署](deployment/advanced_deployment.md)。
+
+### 参考: 完整部署样例
+
+完整部署样例章节介绍了一个完整包含沙箱服务的Agent部署的例子，内容包括：
+
+- 引入浏览器沙箱
+- 构建AgentApp
+- 服务启动
+
+如果想完整回顾部署的所有环节，该章节是重要参考。
+请参考 [参考：完整部署样例](deployment/react_agent.md) 获取具体步骤。
+
+## 下一步
+
+阅读本章节后，可按照以下顺序深入：
+
+1. 进入 [服务](service/service.md) 章节，确认需要的基础设施与实现。
+2. 在 [简单部署](deployment/agent_app.md) 中完成业务逻辑编排与本地验证。
+3. 根据规模需求选择 [高级部署](deployment/advanced_deployment.md) 指南，完成生产化配置。
+4. 若需要 Web 交互层，继续阅读 [完整部署样例](deployment/react_agent.md) 章节并完成前端部署。
+
+通过上述步骤，你可以渐进式地把智能体从实验环境部署到可观测、可维护、可扩展的生产系统。