docs(practice): add zh docs for practices

docs.json

@@ -371,6 +371,21 @@
                     ]
                   }
                 ]
+              },
+              {
+                "tab": "最佳实践",
+                "groups": [
+                  {
+                    "group": "部署场景",
+                    "pages": [
+                      "versions/2.0.5dev/zh/best-practices/architecture-overview",
+                      "versions/2.0.5dev/zh/best-practices/serverless",
+                      "versions/2.0.5dev/zh/best-practices/desktop",
+                      "versions/2.0.5dev/zh/best-practices/microservice",
+                      "versions/2.0.5dev/zh/best-practices/distributed"
+                    ]
+                  }
+                ]
               }
             ]
           },

versions/2.0.5dev/zh/best-practices/architecture-overview.mdx

@@ -0,0 +1,102 @@
+---
+title: "架构基础：可组合的部署模型"
+description: "了解 agentscope.app 的可插拔组件与扩展点，是选择部署方案的基础"
+---
+
+`agentscope.app` 的核心是 `create_app()` 工厂函数，通过构造注入三大可插拔组件来适配不同部署形态：
+
+| 组件 | 接口 | 职责 |
+|------|------|------|
+| `StorageBase` | 持久化 | Credential、Agent、Session、Message 的 CRUD |
+| `MessageBus` | 实时传输 | 分布式锁、Pub/Sub、Inbox 队列、SSE 事件流 |
+| `WorkspaceManagerBase` | 执行沙箱 | Agent 代码执行的文件系统/容器隔离 |
+
+扩展点：
+
+| 扩展点 | 用途 |
+|--------|------|
+| `extra_middlewares` | ASGI 层中间件（Auth、CORS、限流等） |
+| `extra_agent_middlewares` | Agent 层中间件工厂（审计、Quota、RAG 等） |
+| `extra_agent_tools` | 租户级工具注入 |
+| `resource_access_policy` | 跨租户资源访问策略 |
+| `knowledge_base_manager` + `blob_store` | RAG 知识库 |
+
+以下四种部署场景正是通过不同的组件组合和扩展配置来实现的：
+
+<CardGroup cols={2}>
+  <Card title="Serverless 部署" icon="cloud" href="/versions/2.0.5dev/zh/best-practices/serverless">
+    适用于 SaaS 平台、Demo 站点等多用户开箱即用场景
+  </Card>
+  <Card title="桌面应用" icon="desktop" href="/versions/2.0.5dev/zh/best-practices/desktop">
+    单用户本地运行，适用于个人 AI 助手等场景
+  </Card>
+  <Card title="微服务嵌入三方系统" icon="puzzle-piece" href="/versions/2.0.5dev/zh/best-practices/microservice">
+    将 AgentScope 作为 Agent 引擎嵌入企业系统
+  </Card>
+  <Card title="分布式部署" icon="server" href="/versions/2.0.5dev/zh/best-practices/distributed">
+    大规模多租户、多节点水平扩展与高可用
+  </Card>
+</CardGroup>
+
+## 已有组件 vs 需自行实现
+
+| 组件 | 已有实现（开箱即用） | 需自行实现 |
+|------|---------------------|-----------|
+| **Storage** | `RedisStorage` | SQLiteStorage（桌面场景理想选择，当前未实现） |
+| **MessageBus** | `InMemoryMessageBus`、`RedisMessageBus` | NatsMessageBus 等（如有特殊需求） |
+| **WorkspaceManager** | `Local`、`Docker`、`E2B`、`K8s`、`Daytona`、`OpenSandbox` | — |
+| **BlobStore** | `LocalBlobStore`、`S3BlobStore` | 企业自定义 OSS 适配（如非 S3 兼容） |
+| **VectorStore** | `QdrantStore`、`MilvusStore`、`MongoDBStore` | — |
+| **ResourceAccessPolicy** | `DenyAllResourceAccessPolicy`（默认全隔离） | 平台共享策略、企业 RBAC 策略 |
+| **认证** | `X-User-ID` Header（临时方案） | JWT 认证、三方 SSO 对接 |
+| **Agent 中间件** | `InboxMiddleware`、`StateChangeMiddleware`、`ToolOffloadMiddleware`、`RAGMiddleware` | 审计日志、Quota 限流、租户功能开关 |
+
+## 方案对比
+
+| 维度 | Serverless | 桌面应用 | 微服务嵌入 | 分布式部署 |
+|------|-----------|---------|-----------|-----------|
+| **用户规模** | 多用户 (SaaS) | 单用户 | 多租户 | 大规模多租户 |
+| **Storage** | Redis Cloud | Redis (本地) | Redis (企业) | Redis Cluster |
+| **MessageBus** | RedisMessageBus | InMemoryMessageBus | RedisMessageBus | RedisMessageBus |
+| **Workspace** | E2B / OpenSandbox | Local / Docker | Docker / K8s | K8s |
+| **Blob Store** | S3 | LocalBlobStore | S3 / 企业 OSS | S3 |
+| **Vector Store** | Qdrant Cloud | Qdrant (内存) | Qdrant / Milvus | Qdrant Cluster |
+| **认证** | API Gateway JWT | 固定用户 | 三方 JWT/SSO | JWT + OAuth |
+| **Credential** | 平台预置 + 用户自有 | 用户本地配置 | RBAC 控制 | RBAC + Quota |
+| **Index Worker** | 嵌入式 | 嵌入式 | 独立进程 | 独立集群 |
+| **运维复杂度** | 低 | 最低 | 较高 | 高 |
+| **成本模型** | 按调用计费 | 零（本地） | 企业内部分摊 | 固定 + 弹性 |
+| **冷启动** | 有（需优化） | 无 | 无 | 无 |
+| **SSE 支持** | 受限 | 完整 | 完整 | 完整 |
+
+## 关键决策树
+
+```
+需求分析
+├── 单用户、本地运行？
+│   └── → 桌面应用方案
+├── 多用户、已有企业系统需要集成？
+│   └── → 微服务嵌入方案
+├── 多用户、需要低运维 SaaS？
+│   └── → Serverless 方案
+└── 大规模多租户、需要水平扩展？
+    └── → 分布式部署方案
+```
+
+## 各方案的首要技术风险
+
+| 方案 | 首要风险 | 缓解措施 |
+|------|---------|---------|
+| Serverless | SSE 长连接受限、冷启动延迟 | 使用 Cloud Run（原生 HTTP streaming）、设置 min_instances=1 |
+| 桌面应用 | 强依赖 Redis 不够轻量 | 未来实现 SQLiteStorage；当前可用 Docker 内置 Redis |
+| 微服务嵌入 | 需对接三方用户认证（JWT/SSO → `get_current_user_id`）和权限体系（三方 RBAC/IAM → `ResourceAccessPolicyBase.list_accessible`/`can_edit`），涉及租户身份映射、跨系统资源授权等多环节集成 | 渐进实现：先用 `DenyAllResourceAccessPolicy` 实现租户完全隔离，再逐步对接三方 RBAC；认证层先信任网关转发的 Header，再迭代为直接校验 JWT |
+| 分布式 | Redis 单点 / SchedulerManager 重复触发 / Workspace 跨节点一致性 | Redis Cluster + Sentinel；K8s/E2B Workspace；如需精确调度可自行扩展单 scheduler 模式 |
+
+## MessageBus 选择指南
+
+| MessageBus | 适用场景 | 限制 |
+|------------|---------|------|
+| `InMemoryMessageBus` | 单进程（桌面应用、开发环境） | 分布式锁和 Pub/Sub 仅在本进程内生效，多进程/多节点**完全不可用** |
+| `RedisMessageBus` | 多进程、多节点、生产环境 | 依赖 Redis；所有节点必须连接同一 Redis 实例/集群 |
+
+> **关键规则**：只要使用 `uvicorn --workers > 1` 或多节点部署，就**必须**使用 `RedisMessageBus`。`InMemoryMessageBus` 会导致分布式锁失效（同一 Session 可能并发执行）、Wakeup/Cancel 信号丢失、SSE 事件无法跨进程传播。

versions/2.0.5dev/zh/best-practices/desktop.mdx

@@ -0,0 +1,242 @@
+---
+title: "桌面应用"
+description: "单用户、本地运行的 AgentScope 部署方案，适用于个人 AI 助手等场景"
+---
+
+## 场景定位
+
+单用户、本地运行，无需联网（除 LLM API 调用）。典型场景：个人 AI 助手、本地代码助手、离线办公 Agent。
+
+## 前置依赖
+
+```bash
+# 最小安装（service + storage）
+pip install "agentscope[service,storage]"
+
+# 启动本地 Redis（三选一）
+# 方式 A: Docker（推荐）
+docker run --rm -d -p 6379:6379 --name agentscope-redis redis:7
+
+# 方式 B: macOS Homebrew
+brew install redis && brew services start redis
+
+# 方式 C: Ubuntu/Debian
+sudo apt install redis-server && sudo systemctl start redis
+```
+
+## 关键约束
+
+- **单用户**：无租户隔离需求，`user_id` 固定为常量
+- **本地运行**：所有组件在本机进程内，无需分布式协调
+- **沙箱选择**：本地文件系统或 Docker（如有安全需求）
+- **最小依赖**：尽量避免外部服务（如 Redis）
+
+## 组件选型
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                       桌面应用架构                                 │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│   ┌─────────────┐    localhost:8000     ┌──────────────────┐     │
+│   │  Electron /  │◄──────────────────►  │  agentscope.app  │     │
+│   │  Tauri / Web │     HTTP + SSE       │  (FastAPI)       │     │
+│   │  Browser     │                      └────────┬─────────┘     │
+│   └─────────────┘                                │               │
+│                                    ┌─────────────┼──────────┐    │
+│                                    │             │          │    │
+│                               SQLite/Redis  InMemory    Local    │
+│                               (Storage)     MessageBus  Workspace│
+│                                                         ~/agent/ │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Storage：本地轻量存储
+
+桌面场景应避免强依赖 Redis 服务。有两种策略：
+
+| 方案 | 优点 | 缺点 | 推荐 |
+|------|------|------|------|
+| **嵌入式 Redis (via Docker)** | 完全兼容已有 `RedisStorage` | 需要 Docker 或嵌入 Redis 进程 | 快速方案 |
+| **实现 SQLite StorageBase** | 零依赖、单文件、便携 | 需要新增实现 | 长期方案 |
+| **Redis on localhost** | 现有代码直接用 | macOS/Linux 安装简单 | 开发期方案 |
+
+**快速方案**（使用本地 Redis）：
+
+```python
+storage = RedisStorage(
+    host="localhost",
+    port=6379,
+    # key_ttl 默认为 None，表示 key 永不过期。
+    # 桌面场景数据应永久保留，不要设置 key_ttl。
+)
+```
+
+**长期方案**（SQLiteStorage 接口设计，需新增实现）：
+
+```python
+# 未来实现 — 提供零依赖桌面体验
+# storage = SQLiteStorage(db_path="~/.agentscope/data.db")
+```
+
+### MessageBus：进程内消息总线
+
+单进程场景下 `InMemoryMessageBus` 完全满足需求，无需分布式能力：
+
+```python
+from agentscope.app.message_bus import InMemoryMessageBus
+
+message_bus = InMemoryMessageBus()
+```
+
+`InMemoryMessageBus` 已实现所有 `MessageBus` 接口（drain queue、replay log、broadcast、lock、registry），全部基于 `asyncio` 原语，零外部依赖。
+
+### Workspace：本地文件系统
+
+```python
+from agentscope.app.workspace_manager import LocalWorkspaceManager, IsolationPolicy
+
+workspace_manager = LocalWorkspaceManager(
+    basedir=os.path.expanduser("~/.agentscope/workspaces"),
+    # isolation 默认为 PER_AGENT（同一 Agent 的不同 Session 共享工作目录）
+    default_mcps=[
+        # 本地文件浏览器、终端等 MCP Server
+    ],
+)
+```
+
+如需代码执行安全隔离（Agent 执行不可信代码），改用 Docker：
+
+```python
+from agentscope.app.workspace_manager import DockerWorkspaceManager
+
+workspace_manager = DockerWorkspaceManager(
+    basedir=os.path.expanduser("~/.agentscope/workspaces"),
+    base_image="python:3.11-slim",
+    ttl=7200.0,       # 2 小时空闲后回收容器
+    sweep_interval=600.0,
+)
+```
+
+### 用户身份：固定单用户
+
+覆盖 `get_current_user_id`，始终返回固定用户名：
+
+```python
+from agentscope.app.deps import get_current_user_id
+
+DESKTOP_USER_ID = "local-user"
+
+async def desktop_user_id() -> str:
+    return DESKTOP_USER_ID
+
+app = create_app(...)
+app.dependency_overrides[get_current_user_id] = desktop_user_id
+```
+
+### 前端集成
+
+| 方案 | 技术栈 | 特点 |
+|------|--------|------|
+| **Electron + Web UI** | Electron 主进程管理后端进程 + 渲染进程加载 Web UI | 跨平台、最成熟 |
+| **Tauri + Web UI** | Rust 后端启动 Python 进程 + WebView 加载 UI | 轻量、安装包小 |
+| **系统浏览器** | 纯 Python 后端 + `webbrowser.open()` | 最简单 |
+
+Electron 集成示例（主进程启动后端）：
+
+```javascript
+// electron/main.js
+const { spawn } = require('child_process');
+const path = require('path');
+
+let backendProcess;
+
+function startBackend() {
+  backendProcess = spawn('python', [
+    path.join(__dirname, '../backend/desktop_main.py')
+  ], {
+    env: { ...process.env, AGENTSCOPE_MODE: 'desktop' }
+  });
+
+  backendProcess.stdout.on('data', (data) => {
+    if (data.toString().includes('Uvicorn running')) {
+      createWindow('http://localhost:8000');
+    }
+  });
+}
+```
+
+### 知识库（可选）
+
+桌面场景使用内存向量存储即可：
+
+```python
+from agentscope.rag import QdrantStore
+from agentscope.app.rag.knowledge_base_manager import CollectionPerKbManager
+from agentscope.app.rag.blob_store import LocalBlobStore
+
+knowledge_base_manager = CollectionPerKbManager(
+    storage=storage,
+    vector_store=QdrantStore(location=":memory:"),  # 或持久化到本地文件
+    # vector_store=QdrantStore(path="~/.agentscope/qdrant"),
+)
+blob_store = LocalBlobStore(root_dir=os.path.expanduser("~/.agentscope/blobs"))
+```
+
+### 完整启动代码
+
+```python
+# desktop_main.py — 可直接复制运行（需先启动本地 Redis）
+import os
+import uvicorn
+from agentscope.app import create_app
+from agentscope.app.storage import RedisStorage
+from agentscope.app.message_bus import InMemoryMessageBus
+from agentscope.app.workspace_manager import LocalWorkspaceManager
+from agentscope.app.deps import get_current_user_id
+
+DESKTOP_USER_ID = "local-user"
+DATA_DIR = os.path.expanduser("~/.agentscope")
+
+storage = RedisStorage(host="localhost", port=6379)
+
+app = create_app(
+    storage=storage,
+    message_bus=InMemoryMessageBus(),
+    workspace_manager=LocalWorkspaceManager(
+        basedir=os.path.join(DATA_DIR, "workspaces"),
+    ),
+    enable_index_worker=True,
+)
+
+
+async def desktop_user_id() -> str:
+    return DESKTOP_USER_ID
+
+
+app.dependency_overrides[get_current_user_id] = desktop_user_id
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+### 部署流程
+
+```
+1. 打包分发
+   ├── Python 环境打包（PyInstaller / conda-pack / 嵌入 Python）
+   ├── Redis 嵌入（redis-server 二进制 / Docker Compose）
+   └── 前端打包（Electron Builder / Tauri Build）
+
+2. 首次启动
+   ├── 创建 ~/.agentscope/ 目录结构
+   ├── 启动嵌入 Redis（或等待用户自行启动）
+   ├── 启动 FastAPI 后端（localhost:8000）
+   └── 打开前端界面
+
+3. 用户体验
+   ├── 无需注册/登录（固定 user_id）
+   ├── 在 UI 中配置自己的 LLM API Key (Credential)
+   ├── 创建 Agent → 开始对话
+   └── 数据完全本地，关闭应用即停止
+```