Feat/support subpath deployment (#2)

* feat: 支持 MaxKB 子路径部署并优化配置说明

主要改进：
1. 新增 MAXKB_API_PREFIX 环境变量，支持子路径部署（如 /mk）
2. 修复 _build_api_path 函数，正确处理 /chat/ 路径（不需要 API 前缀）
3. 更新 .env.example 添加详细配置说明和示例
4. 所有 HTTP 请求函数统一使用 _build_api_path 处理路径

修复问题：
- 修复了子路径部署时 /chat/api/ 路径错误添加前缀的问题
- 修复了登录 API 路径硬编码问题
- 优化了环境变量配置的文档说明

测试验证：
- ✅ /api/... 路径正确添加前缀 → /mk/api/...
- ✅ /chat/... 路径保持原样 → /chat/...
- ✅ 智能体列表获取正常
- ✅ 对话功能正常

* docs: 在 README 中补充 MAXKB_API_PREFIX 配置说明

- 新增 MAXKB_API_PREFIX 环境变量的详细说明
- 添加子路径部署场景的配置示例
- 说明路径处理规则（/chat/ 路径不添加前缀）
- 更新快速开始中的配置示例

* feat: 优化 MAXKB_API_PREFIX 默认值为 /admin

- 将 MAXKB_API_PREFIX 默认值从空字符串改为 /admin
- 更新 .env.example 配置示例
- 更新 README 文档说明
- 添加 4 种部署场景的配置示例

适用场景：
- 标准 MaxKB 部署：使用默认值 /admin
- 子路径部署：配置为子路径（如 /mk）
- 根路径无前缀：配置为空字符串

* docs: 优化 README 环境变量说明

- 添加必填/选填标记（✅/❌/⚠️）
- 明确 MAXKB_API_PREFIX 为选填参数
- 说明认证方式的优先级
- 更新 .env 配置示例，分类为必填/选填/认证
- 添加更清晰的配置提示

* 修复登录 API 路径，支持子路径部署

---------

Co-authored-by: OpenClaw <openclaw@local>

Author: hao65103940

.env.example

@@ -1,5 +1,22 @@
+# MaxKB 服务地址（必填）
+# 示例：http://localhost:8080 或 https://maxkb.example.com
 MAXKB_DOMAIN=<maxkb_domain>
+
+# MaxKB API 前缀（可选）
+# 默认值：/admin（标准 MaxKB 部署）
+# 如果 MaxKB 部署在子路径下（如 http://example.com/mk），配置此项为 /mk
+# 如果 MaxKB 部署在根路径且无 /admin 前缀，留空即可
+MAXKB_API_PREFIX=/admin
+
+# MaxKB 认证 Token（二选一：Token 或 用户名密码）
+# 优先级：用户名密码 > Token
 MAXKB_TOKEN=
-MAXKB_WORKSPACE_ID=default
+
+# MaxKB 登录用户名（二选一：Token 或 用户名密码）
 MAXKB_USERNAME=admin
-MAXKB_PASSWORD=admin123
+
+# MaxKB 登录密码（二选一：Token 或 用户名密码）
+MAXKB_PASSWORD=admin123
+
+# MaxKB 工作空间 ID（可选，默认为 default）
+MAXKB_WORKSPACE_ID=default

README.md

@@ -71,13 +71,36 @@ cp .env.example .env
 编辑 `.env`：
 
 ```env
-MAXKB_DOMAIN=<maxkb_domain>
+# ==================== 必填配置 ====================
+
+# MaxKB 服务地址（必填）
+MAXKB_DOMAIN=http://localhost:8080
+
+# ==================== 选填配置 ====================
+
+# MaxKB API 前缀（选填，默认 /admin）
+# - 标准 MaxKB 部署：无需配置（默认 /admin）
+# - 子路径部署（如 http://example.com/mk）：配置为 /mk
+# - 根路径无前缀：配置为空字符串 ""
+MAXKB_API_PREFIX=/admin
+
+# MaxKB 工作空间 ID（选填，默认 default）
+MAXKB_WORKSPACE_ID=default
+
+# ==================== 认证配置（二选一）====================
+
+# 方式 1：用户名 + 密码（优先级高）
 MAXKB_USERNAME=admin
 MAXKB_PASSWORD=admin123
-MAXKB_WORKSPACE_ID=default
+
+# 方式 2：Token（如果配置了用户名密码，此项被忽略）
+# MAXKB_TOKEN=your_token_here
 ```
 
-> **提示**：用户名/密码与 Token 可同时配置，用户名/密码优先级更高。
+> **提示**：
+> - `MAXKB_API_PREFIX`：标准部署无需修改，只有非标准部署才需要配置
+> - 认证方式：推荐配置用户名密码，系统会自动登录获取 Token
+> - 如果同时配置了用户名密码和 Token，系统会使用用户名密码登录
 
 ### 2. 列出已发布智能体
 
@@ -113,13 +136,57 @@ python3 scripts/main.py "Python 里如何读取文件？" "代码助手"
 
 ## 环境变量
 
-| 变量                 | 说明                              | 默认值                    |
-|----------------------|-----------------------------------|---------------------------|
-| `MAXKB_DOMAIN`       | MaxKB 服务地址                    | `<maxkb_domain>`          | 
-| `MAXKB_TOKEN`        | Bearer Token（管理员 API Key）    | —                         |
-| `MAXKB_WORKSPACE_ID` | 工作空间 ID                       | `default`                 |
-| `MAXKB_USERNAME`     | 登录用户名（优先于 `MAXKB_TOKEN`）| —                         |
-| `MAXKB_PASSWORD`     | 登录密码（优先于 `MAXKB_TOKEN`）  | —                         |
+| 变量                 | 必填 | 说明                              | 默认值                    |
+|----------------------|------|-----------------------------------|---------------------------|
+| `MAXKB_DOMAIN`       | ✅ 是 | MaxKB 服务地址                    | `<maxkb_domain>`          | 
+| `MAXKB_API_PREFIX`   | ❌ 否 | API 路径前缀，适用于子路径部署     | `/admin` |
+| `MAXKB_TOKEN`        | ⚠️ 二选一 | Bearer Token（管理员 API Key）    | —                         |
+| `MAXKB_USERNAME`     | ⚠️ 二选一 | 登录用户名（优先于 `MAXKB_TOKEN`）| —                         |
+| `MAXKB_PASSWORD`     | ⚠️ 二选一 | 登录密码（优先于 `MAXKB_TOKEN`）  | —                         |
+| `MAXKB_WORKSPACE_ID` | ❌ 否 | 工作空间 ID                       | `default`                 |
+
+**说明**：
+- `MAXKB_API_PREFIX`：标准 MaxKB 部署无需配置（默认 `/admin`），子路径部署需配置（如 `/mk`）
+- 认证方式：配置 `MAXKB_USERNAME` + `MAXKB_PASSWORD` **或** `MAXKB_TOKEN`，前者优先级更高
+
+### MAXKB_API_PREFIX 使用说明
+
+**使用场景**：当 MaxKB 部署在子路径下时（非根路径），需要配置此项。
+
+**默认值**：`/admin`（标准 MaxKB 部署）
+
+**示例**：
+
+```bash
+# 场景 1：标准 MaxKB 部署（默认值）
+# http://localhost:8080/admin/api/...
+MAXKB_DOMAIN=http://localhost:8080
+MAXKB_API_PREFIX=/admin
+
+# 场景 2：MaxKB 部署在子路径
+# http://example.com/mk/api/...
+MAXKB_DOMAIN=http://example.com
+MAXKB_API_PREFIX=/mk
+
+# 场景 3：MaxKB 部署在根路径且无 /admin 前缀
+# http://localhost:8080/api/...
+MAXKB_DOMAIN=http://localhost:8080
+MAXKB_API_PREFIX=""
+
+# 场景 4：MaxKB 部署在多级子路径
+# http://example.com/ai/maxkb/api/...
+MAXKB_DOMAIN=http://example.com
+MAXKB_API_PREFIX=/ai/maxkb
+```
+
+**路径处理规则**：
+
+| API 类型 | 原始路径 | 配置 `MAXKB_API_PREFIX=/mk` 后 |
+|----------|----------|-------------------------------|
+| 数据 API | `/api/workspace/...` | `/mk/api/workspace/...` |
+| 对话 API | `/chat/api/...` | `/chat/api/...` (不变) |
+
+> **注意**：`/chat/` 开头的路径是 MaxKB 前端路由，不会添加 API 前缀。
 
 **认证优先级**：若同时配置了 `MAXKB_USERNAME` + `MAXKB_PASSWORD` 和 `MAXKB_TOKEN`，系统将使用用户名/密码登录获取 Token，忽略 `MAXKB_TOKEN`。
 

scripts/main.py

@@ -40,11 +40,29 @@ def load_dotenv(dotenv_path=None):
     load_dotenv(ENV_FILE)
 
 MAXKB_DOMAIN = os.environ.get("MAXKB_DOMAIN", "<maxkb_domain>")
+# MaxKB API 路径前缀，默认为 /admin（标准 MaxKB 部署）
+# 如果 MaxKB 部署在子路径下（如 http://example.com/mk），配置为 /mk
+# 如果 MaxKB 部署在根路径且无 /admin 前缀，留空即可
+MAXKB_API_PREFIX = os.environ.get("MAXKB_API_PREFIX", "/admin").rstrip("/")
 MAXKB_TOKEN = os.environ.get("MAXKB_TOKEN", "")
 MAXKB_WORKSPACE_ID = os.environ.get("MAXKB_WORKSPACE_ID", "default")
 MAXKB_USERNAME = os.environ.get("MAXKB_USERNAME", "")
 MAXKB_PASSWORD = os.environ.get("MAXKB_PASSWORD", "")
 
+def _build_api_path(path: str) -> str:
+    """Build full API path with optional prefix (e.g. /mk)
+    
+    注意：/chat/ 开头的路径是 MaxKB 前端路由，不需要添加 API 前缀
+    - /api/... → /mk/api/...
+    - /chat/... → /chat/... (不变)
+    """
+    if MAXKB_API_PREFIX and not path.startswith(MAXKB_API_PREFIX):
+        # /chat/ 路径不需要前缀（MaxKB 特殊设计）
+        if path.startswith("/chat/"):
+            return path
+        return f"{MAXKB_API_PREFIX}{path}"
+    return path
+
 
 # ── 内部 HTTP 工具 ────────────────────────────────────────────────────
 
@@ -63,7 +81,8 @@ def _chat_headers(token: str) -> dict:
 
 
 def _get(path: str, token: str = None) -> dict:
-    url = f"{MAXKB_DOMAIN}{path}"
+    api_path = _build_api_path(path)
+    url = f"{MAXKB_DOMAIN}{api_path}"
     headers = _headers() if token is None else _chat_headers(token)
     req = request.Request(url=url, headers=headers, method="GET")
     try:
@@ -78,7 +97,8 @@ def _get(path: str, token: str = None) -> dict:
 
 
 def _post_json(path: str, body: dict, token: str = None) -> dict:
-    url = f"{MAXKB_DOMAIN}{path}"
+    api_path = _build_api_path(path)
+    url = f"{MAXKB_DOMAIN}{api_path}"
     data = json.dumps(body).encode("utf-8")
     headers = _headers() if token is None else _chat_headers(token)
     req = request.Request(url=url, data=data, headers=headers, method="POST")
@@ -98,7 +118,8 @@ def _post_sse(path: str, body: dict, token: str) -> str:
     发送 POST 请求并逐行解析 SSE（Server-Sent Events）流。
     收集所有 operate==true 的 content 片段，直到 is_end==true。
     """
-    url = f"{MAXKB_DOMAIN}{path}"
+    api_path = _build_api_path(path)
+    url = f"{MAXKB_DOMAIN}{api_path}"
     data = json.dumps(body).encode("utf-8")
     req = request.Request(url=url, data=data, headers=_chat_headers(token), method="POST")
     chunks = []
@@ -129,7 +150,7 @@ def _post_sse(path: str, body: dict, token: str) -> str:
 def _login() -> str:
     if MAXKB_USERNAME and  MAXKB_PASSWORD:
         resp = _post_json(
-            "/admin/api/user/login",
+            "/api/user/login",
             {"username": MAXKB_USERNAME, "password": MAXKB_PASSWORD},
         )
         token = resp.get("data", {}).get("token", "")
@@ -145,7 +166,7 @@ def _login() -> str:
 def get_published_agents() -> list:
     """返回所有已发布智能体，每条包含 id / name / desc。"""
     resp = _get(
-        f"/admin/api/workspace/{MAXKB_WORKSPACE_ID}/application/1/10000"
+        f"/api/workspace/{MAXKB_WORKSPACE_ID}/application/1/10000"
     )
     records = resp.get("data", {}).get("records", [])
     agents = [
@@ -185,10 +206,10 @@ def chat_with_agent(agent_id: str, question: str) -> str:
     对指定智能体发起一次对话并返回回答文本。
     """
     # 获取 access_token（匿名会话）
-    token_resp = _get(f"/admin/api/workspace/{MAXKB_WORKSPACE_ID}/application/{agent_id}/access_token")
+    token_resp = _get(f"/api/workspace/{MAXKB_WORKSPACE_ID}/application/{agent_id}/access_token")
     access_token = token_resp.get("data", {}).get("access_token", "")
 
-    # 创建会话
+    # 创建会话（注意：chat API 路径不以 /api 开头）
     chat_resp = _post_json(
         f"/chat/api/auth/anonymous",
         {"access_token": access_token},