feat: improve tool-call bridging and env documentation

.env.example

@@ -1,22 +1,14 @@
+# ==================== 必要配置（先填这部分） ====================
+
 # 网关监听地址
 HOST=0.0.0.0
 # 网关监听端口
 PORT=8317
-# API Key，可配置多个（逗号分隔）。空 = 不鉴权（启动会打 warning），仅用于本地 dev
-API_KEYS=sk-your-api-key
-# 独立的 /metrics 鉴权 token（留空则退化为 API_KEYS 亦可访问；若与 API_KEYS 同时为空，/metrics 默认 503）
-METRICS_TOKEN=
-# 显式把 /metrics 设为公开（仅在私网采集器场景使用）
-METRICS_PUBLIC=false
-# 独立的 /internal/* 管理 token（留空则退化为 API_KEYS）；强烈建议生产环境单独配置
-ADMIN_TOKEN=
-# 日志级别（DEBUG / INFO / WARNING / ERROR）
-LOG_LEVEL=INFO
 
-# /v1/chat/completions 并发上限（<=0 表示不限流）
-GATEWAY_MAX_IN_FLIGHT=4
-# 排队等待超时秒数，超过后返回 429 + Retry-After
-GATEWAY_QUEUE_TIMEOUT_SEC=30
+# API Key，可配置多个（逗号分隔）。空 = 不鉴权（仅建议本地 dev）
+API_KEYS=sk-your-api-key
+# /internal/* 管理 token（留空则退化为 API_KEYS）
+ADMIN_TOKEN=
 
 # 容器内 Lingma 二进制路径
 LINGMA_BIN=/app/data/bin/Lingma
@@ -26,12 +18,11 @@ LINGMA_SOURCE_TYPE=marketplace
 LINGMA_MARKETPLACE_PUBLISHER=Alibaba-Cloud
 # Marketplace 扩展名
 LINGMA_MARKETPLACE_EXTENSION=tongyi-lingma
-# VSIX 下载地址（最新优先）
-LINGMA_VSIX_URL=https://tongyi-code.oss-cn-hangzhou.aliyuncs.com/vscode/tongyi-lingma-latest.vsix
 # 启动时总是尝试从 VSIX 刷新二进制
 LINGMA_BOOTSTRAP_ALWAYS=true
 # 强制刷新（true 时忽略本地缓存）
 LINGMA_FORCE_REFRESH=false
+
 # Lingma 工作目录（登录/会话数据）
 LINGMA_WORK_DIR=/app/data/.lingma/vscode/sharedClientCache
 # Lingma WebSocket 端口
@@ -43,11 +34,39 @@ LINGMA_RPC_TIMEOUT=30
 
 # 默认模型（无法映射时使用）
 DEFAULT_MODEL=org_auto
-# 默认模式：chat 或 agent
-DEFAULT_ASK_MODE=chat
+# 默认模式：chat 或 agent（工具调用建议 agent）
+DEFAULT_ASK_MODE=agent
 
-# 请求侧 tools/tool_choice 透传到 Lingma（默认开启，可显式关闭）
+# 请求侧 tools/tool_choice 透传到 Lingma（工具调用建议开启）
 TOOL_FORWARD_ENABLED=true
+
+# 登录方式（二选一）
+# A. 账号密码（单实例）
+LINGMA_USERNAME=
+LINGMA_PASSWORD=
+# B. 会话 bundle（推荐生产）
+# LINGMA_SESSION_BUNDLE=
+# LINGMA_SESSION_BUNDLE_FILE=/secrets/lingma-session.b64
+
+
+# ==================== 可选配置（按需） ====================
+
+# 独立的 /metrics 鉴权 token（留空则退化为 API_KEYS 亦可访问）
+METRICS_TOKEN=
+# 显式把 /metrics 设为公开（仅私网采集器场景）
+METRICS_PUBLIC=false
+
+# 日志级别（DEBUG / INFO / WARNING / ERROR）
+LOG_LEVEL=INFO
+
+# /v1/chat/completions 并发上限（<=0 表示不限流）
+GATEWAY_MAX_IN_FLIGHT=4
+# 排队等待超时秒数，超过后返回 429 + Retry-After
+GATEWAY_QUEUE_TIMEOUT_SEC=30
+
+# VSIX 下载地址（仅 LINGMA_SOURCE_TYPE=vsix 或 marketplace 回退时使用）
+LINGMA_VSIX_URL=https://tongyi-code.oss-cn-hangzhou.aliyuncs.com/vscode/tongyi-lingma-latest.vsix
+
 # 可选：允许透传的工具名白名单，逗号分隔；为空表示不额外限制
 TOOL_ALLOWLIST=
 
@@ -63,41 +82,15 @@ AUTO_LOGIN_TIMEOUT=180
 # 自动登录重试次数
 AUTO_LOGIN_MAX_RETRY=2
 
-# Lingma 登录用户名（仅当 LINGMA_ACCOUNTS 为空时生效，单实例模式）
-LINGMA_USERNAME=
-# Lingma 登录密码（仅当 LINGMA_ACCOUNTS 为空时生效）
-LINGMA_PASSWORD=
-
-# ==== 多实例池（方案乙：多账号） ====
+# ==== 多实例池（可选） ====
 # 多账号列表，支持两种格式：
 #   CSV:  user1:pass1,user2:pass2
 #   JSON: [{"username":"u1","password":"p1"},{"username":"u2","password":"p2"}]
-# 配置后每个账号对应一个独立 Lingma 实例（独立 workDir + 独立自动登录）
 LINGMA_ACCOUNTS=
-# 实例数量：默认等于 LINGMA_ACCOUNTS 数；显式指定时账号不足会循环复用并打 warning
+# 实例数量：默认等于 LINGMA_ACCOUNTS 数；显式指定时账号不足会循环复用
 LINGMA_INSTANCE_COUNT=
 
-# ==== 登录态注入：跳过 Playwright 自动登录 ====
-# 方式 1：base64 字符串，内容 = tar.gz(workDir/cache/{id,user,quota,config.json})
-#        通过 `POST /internal/session/export` 从另一个已登录实例导出得到。
-#        配了这个就可以不填 LINGMA_USERNAME / LINGMA_PASSWORD。
-# LINGMA_SESSION_BUNDLE=
-
-# 方式 2：指向宿主机上的 bundle 文件路径（文件内容即 base64 字符串）
-# LINGMA_SESSION_BUNDLE_FILE=/secrets/lingma-session.b64
-
-# 多账号时走 JSON 模式，每个账号可以独立带 session_bundle：
-# LINGMA_ACCOUNTS=[
-#   {"username":"u1","password":"p1","session_bundle":"H4sI..."},
-#   {"username":"u2","password":"p2","session_bundle_file":"/secrets/u2.b64"}
-# ]
-# 注意：一旦 workDir 里已经有登录态（cache/user 非空），bundle 会被跳过，
-# 你手动登录的 / 旧容器的登录态不会被覆盖。
-
-# ==== 会话复用（多轮对话命中上游 KV cache，减少首 token 延迟） ====
-# 开关（默认开）
+# ==== 会话复用（可选，默认开） ====
 SESSION_REUSE_ENABLED=true
-# 最多缓存多少条会话 (LRU)
 SESSION_CACHE_MAX_ENTRIES=256
-# 会话 TTL 秒数；超时自动失效，避免 Lingma 侧早已回收还在命中
 SESSION_CACHE_TTL_SEC=1800