chore: agfs-client默认切到binding-client模式

CONTRIBUTING.md

@@ -51,7 +51,7 @@ source .venv/bin/activate  # Linux/macOS
 
 #### Local Development & AGFS Compilation
 
-If you modify the **AGFS (Go)** code or **C++ extensions**, you need to re-compile and re-install them to make the changes take effect in your environment. Run the following command in the project root:
+OpenViking defaults to `binding-client` mode for AGFS, which requires a pre-built shared library. If you modify the **AGFS (Go)** code or **C++ extensions**, or if the pre-built library is not found, you need to re-compile and re-install them. Run the following command in the project root:
 
 ```bash
 uv pip install -e . --force-reinstall

CONTRIBUTING_CN.md

@@ -51,7 +51,7 @@ source .venv/bin/activate  # Linux/macOS
 
 #### 本地开发与 AGFS 编译
 
-如果你修改了 **AGFS (Go)** 代码或 **C++ 扩展**，你需要重新编译并安装它们，以使更改在本地环境中生效。在项目根目录下运行以下命令：
+OpenViking 默认使用 `binding-client` 模式，这需要一个预先构建的共享库。如果你修改了 **AGFS (Go)** 代码或 **C++ 扩展**，或者预编译库未找到，你需要重新编译并安装它们，以使更改在本地环境中生效。在项目根目录下运行以下命令：
 
 ```bash
 uv pip install -e . --force-reinstall

README.md

@@ -60,6 +60,8 @@ With OpenViking, developers can build an Agent's brain just like managing local
 Before starting with OpenViking, please ensure your environment meets the following requirements:
 
 - **Python Version**: 3.10 or higher
+- **Go Version**: 1.19 or higher (Required for building AGFS components)
+- **C++ Compiler**: GCC 9+ or Clang 11+ (Required for building core extensions)
 - **Operating System**: Linux, macOS, Windows
 - **Network Connection**: A stable network connection is required (for downloading dependencies and accessing model services)
 

README_CN.md

@@ -59,6 +59,8 @@
 在开始使用 OpenViking 之前，请确保您的环境满足以下要求：
 
 - **Python 版本**：3.10 或更高版本
+- **Go 版本**：1.19 或更高（从源码构建 AGFS 组件需要）
+- **C++ 编译器**：GCC 9+ 或 Clang 11+（构建核心扩展需要，必须支持 C++17）
 - **操作系统**：Linux、macOS、Windows
 - **网络连接**：需要稳定的网络连接（用于下载依赖和访问模型服务）
 

docs/en/faq/faq.md

@@ -56,11 +56,25 @@ viking://
 ### What are the environment requirements?
 
 - **Python Version**: 3.10 or higher
+- **Build Tools** (if installing from source or on unsupported platforms): Go 1.19+, GCC 9+ or Clang 11+
 - **Required Dependencies**: Embedding model (Volcengine Doubao recommended)
 - **Optional Dependencies**:
   - VLM (Vision Language Model): For multimodal content processing and semantic extraction
   - Rerank model: For improved retrieval precision
 
+### What are `binding-client` and `http-client`? Which one should I choose?
+
+- **`binding-client` (Default)**: Runs AGFS logic directly within the Python process via CGO bindings. Advantages: extremely high performance, zero network latency; Disadvantages: requires a compiled AGFS shared library locally.
+- **`http-client`**: Communicates with a standalone `agfs-server` via HTTP. Advantages: decoupled deployment, no local Go compilation needed; Disadvantages: some network communication overhead.
+
+If your environment supports Go compilation or you've installed a Wheel package containing pre-compiled libraries, the default `binding-client` is recommended.
+
+### What should I do if I encounter "AGFS binding library not found"?
+
+This usually means the AGFS shared library is not pre-built in your environment. You can:
+1. **Re-compile and install**: Run `pip install -e . --force-reinstall` in the project root (requires Go environment).
+2. **Switch to HTTP mode**: Set `storage.agfs.mode = "http-client"` in your `ov.conf` and ensure an `agfs-server` is running.
+
 ### How do I install/upgrade OpenViking?
 
 ```bash

docs/zh/faq/faq.md

@@ -56,11 +56,25 @@ viking://
 ### 环境要求是什么？
 
 - **Python 版本**：3.10 或更高
+- **编译工具**（如果从源码安装或在不支持的平台上）：Go 1.19+, GCC 9+ 或 Clang 11+
 - **必需依赖**：Embedding 模型（推荐火山引擎 Doubao）
 - **可选依赖**：
   - VLM（视觉语言模型）：用于多模态内容处理和语义提取
   - Rerank 模型：用于提升检索精度
 
+### 什么是 `binding-client` 和 `http-client`？我该选哪个？
+
+- **`binding-client`（默认值）**：通过 CGO 绑定直接在 Python 进程内运行 AGFS 逻辑。优点是性能极高，无网络延迟；缺点是需要本地有编译好的 AGFS 共享库。
+- **`http-client`**：通过 HTTP 协议与独立的 `agfs-server` 通信。优点是部署解耦，不需要本地编译 Go 代码；缺点是有一定的网络通信开销。
+
+如果你的环境支持编译 Go 代码，或者安装了包含预编译库的 Wheel 包，推荐使用默认的 `binding-client`。
+
+### 遇到 "AGFS binding library not found" 错误怎么办？
+
+这通常是因为本地没有编译好的 AGFS 共享库。你可以：
+1. **重新编译安装**：在项目根目录运行 `pip install -e . --force-reinstall`（需要 Go 环境）。
+2. **切换到 HTTP 模式**：在 `ov.conf` 中设置 `storage.agfs.mode = "http-client"`，并确保有一个正在运行的 `agfs-server`。
+
 ### 如何安装 OpenViking？
 
 ```bash

openviking_cli/utils/config/agfs_config.py

@@ -85,7 +85,7 @@ class AGFSConfig(BaseModel):
     )
 
     mode: str = Field(
-        default="http-client",
+        default="binding-client",
         description="AGFS client mode: 'http-client' | 'binding-client'",
     )
 

tests/agfs/test_fs_local.py

@@ -15,7 +15,12 @@
 
 # 1. Direct configuration for testing
 AGFS_CONF = AGFSConfig(
-    path="/tmp/ov-test", backend="local", port=1833, url="http://localhost:1833", timeout=10
+    path="/tmp/ov-test",
+    backend="local",
+    port=1833,
+    mode="http-client",
+    url="http://localhost:1833",
+    timeout=10,
 )
 
 # clean up test directory if it exists