feat(litellm): 增加智谱 GLM Coding Plan 上游支持并完善文档

- 在 LiteLLM 网关配置中新增智谱 GLM Coding Plan 上游支持，包括环境变量、compose 配置和路由规则
- 新增容器端口暴露治理指南，详细说明 localhost 绑定与防火墙策略的区别及最佳实践
- 新增 Docker 端口绑定 localhost 操作速查文档，提供具体配置示例和迁移指导
- 修复 Sync-ClaudeConfig 脚本中复制符号链接时可能中断的问题，增强备份鲁棒性
- 更新相关文档链接和说明，保持文档间引用一致

Author: mudssky

ai/coding/claude/Sync-ClaudeConfig.ps1

@@ -264,7 +264,67 @@ function Copy-DirectoryContents {
     }
 
     foreach ($item in Get-ChildItem -LiteralPath $SourcePath -Force) {
-        Copy-Item -LiteralPath $item.FullName -Destination (Join-Path $DestinationPath $item.Name) -Recurse -Force
+        Copy-FileSystemEntry -Item $item -DestinationPath (Join-Path $DestinationPath $item.Name)
+    }
+}
+
+function Copy-FileSystemEntry {
+    param(
+        [Parameter(Mandatory)]
+        [System.IO.FileSystemInfo]$Item,
+
+        [Parameter(Mandatory)]
+        [string]$DestinationPath
+    )
+
+    # 旧版 ~/.claude 整目录软链接里可能混入 runtime 生成的符号链接。
+    # 单独分流可避免 Copy-Item -Recurse 在失效链接上中断整个迁移。
+    if ($Item.Attributes.HasFlag([System.IO.FileAttributes]::ReparsePoint)) {
+        Copy-ReparsePointItem -Item $Item -DestinationPath $DestinationPath
+        return
+    }
+
+    if ($Item.PSIsContainer) {
+        if (-not (Test-Path -LiteralPath $DestinationPath)) {
+            New-Item -ItemType Directory -Path $DestinationPath -Force | Out-Null
+        }
+
+        Copy-DirectoryContents -SourcePath $Item.FullName -DestinationPath $DestinationPath
+        return
+    }
+
+    Copy-Item -LiteralPath $Item.FullName -Destination $DestinationPath -Force
+}
+
+function Copy-ReparsePointItem {
+    param(
+        [Parameter(Mandatory)]
+        [System.IO.FileSystemInfo]$Item,
+
+        [Parameter(Mandatory)]
+        [string]$DestinationPath
+    )
+
+    $linkTarget = Get-LinkTargetText -Item $Item
+    if ($Item.PSIsContainer) {
+        # 目录链接可能指向外部目录或形成环；迁移旧 ~/.claude 时跳过它们，
+        # 可以避免把整个备份流程拖进循环或无权限路径。
+        Write-Warning "备份时跳过目录链接：$($Item.FullName) -> $linkTarget"
+        return
+    }
+
+    try {
+        # 对文件链接优先复制当前可解析的内容，这样像 latest.log 之类的快捷入口
+        # 若仍然有效，就会在备份中落成普通文件；若链接已失效则只告警不失败。
+        Copy-Item -LiteralPath $Item.FullName -Destination $DestinationPath -Force -ErrorAction Stop
+    }
+    catch {
+        if ([string]::IsNullOrWhiteSpace($linkTarget)) {
+            Write-Warning "备份时跳过无法解析目标的链接：$($Item.FullName)"
+            return
+        }
+
+        Write-Warning "备份时跳过无法复制的链接：$($Item.FullName) -> $linkTarget。$($_.Exception.Message)"
     }
 }
 

ai/gateway/litellm/.env.example

@@ -6,6 +6,10 @@ LITELLM_HOST_PORT=34000
 NEWAPI_API_BASE=http://new-api.example.com/v1
 # NewAPI 上游鉴权密钥；LiteLLM 会透传它请求 `/chat/completions`、`/models` 等接口。
 NEWAPI_KEY=sk-newapi-dev-xxxx
+# 智谱 GLM Coding Plan OpenAI 兼容端点；默认建议使用官方专属地址。
+Z_AI_CODING_API_BASE=https://open.bigmodel.cn/api/coding/paas/v4
+# 智谱 GLM Coding Plan 上游密钥；LiteLLM 会用它转发 `GLM-*` 请求。
+Z_AI_API_KEY=sk-zai-dev-xxxx
 # LiteLLM 自身的网关密钥；客户端访问 LiteLLM 时使用这个 key。
 LITELLM_MASTER_KEY=sk-litellm-123456
 # LiteLLM 元数据数据库；未显式设置时 compose 会使用默认本地 PostgreSQL 地址。

ai/gateway/litellm/.env.production.example

@@ -6,6 +6,10 @@ LITELLM_HOST_PORT=34000
 NEWAPI_API_BASE=https://new-api.internal.example.com/v1
 # 生产环境 NewAPI 密钥；建议由密钥管理系统注入。
 NEWAPI_KEY=sk-newapi-prod-change-me
+# 生产环境智谱 Coding Plan 端点；如需代理或专线可在此覆盖。
+Z_AI_CODING_API_BASE=https://open.bigmodel.cn/api/coding/paas/v4
+# 生产环境智谱密钥；建议由密钥管理系统注入。
+Z_AI_API_KEY=sk-zai-prod-change-me
 # LiteLLM 对外暴露的网关密钥；客户端通过它访问 LiteLLM。
 LITELLM_MASTER_KEY=sk-litellm-prod-change-me
 # 生产环境建议使用独立数据库账号，并限制到最小权限。

ai/gateway/litellm/compose.yaml

@@ -15,9 +15,12 @@ services:
       # 这样可以避免把 `.env.local` 中与 LiteLLM 无关的变量一并注入容器。
       # 通过 compose 插值保留当前默认数据库地址；start.ps1 会在存在 .env.local 时传入 --env-file 以支持本地覆盖。
       DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:12345678@host.docker.internal:5432/litellm}
-      # 当前本地配置走 NewAPI OpenAI 兼容接口；变量必须显式注入容器，LiteLLM 才能解析 os.environ/...。
+      # 当前本地配置同时走 NewAPI 与智谱 OpenAI 兼容接口；变量必须显式注入容器，LiteLLM 才能解析 os.environ/...。
       NEWAPI_API_BASE: ${NEWAPI_API_BASE:-}
       NEWAPI_KEY: ${NEWAPI_KEY:-}
+      # 智谱 GLM Coding Plan 走独立 OpenAI 兼容端点，默认指向官方专属地址。
+      Z_AI_CODING_API_BASE: ${Z_AI_CODING_API_BASE:-https://open.bigmodel.cn/api/coding/paas/v4}
+      Z_AI_API_KEY: ${Z_AI_API_KEY:-}
       LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:-}
       # 保留旧变量，避免切回 qwen.yaml 等历史配置时还要额外补环境变量。
       DASHSCOPE_API_KEY: ${DASHSCOPE_API_KEY:-}

ai/gateway/litellm/litellm.md

@@ -1,16 +1,16 @@
 # LiteLLM 网关说明
 
-这个目录用于启动一个基于 LiteLLM Proxy 的 OpenAI 兼容网关，当前默认通过 NewAPI 转发请求到上游模型服务。
+这个目录用于启动一个基于 LiteLLM Proxy 的 OpenAI 兼容网关，当前默认同时支持 NewAPI 与智谱 GLM Coding Plan 两类上游。
 
 相关文件职责如下：
 
-- `litellm.local.yaml`：本地默认配置，定义 LiteLLM 的 wildcard 路由与上游 NewAPI 连接方式。
+- `litellm.local.yaml`：本地默认配置，定义 LiteLLM 的显式模型、GLM 专属路由与上游连接方式。
 - `qwen.yaml`：历史示例配置，保留了固定模型与降级策略写法，可作为按模型显式映射时的参考。
 - `compose.yaml`：LiteLLM 容器模板，定义镜像、端口、挂载和默认环境变量。
 - `start.ps1`：统一入口，封装常用 `docker compose` 操作。
 - `.env.example`：开发环境变量示例。
 - `.env.production.example`：生产环境变量示例。
-- `.env.local`：本地私有环境变量，保存 `NEWAPI_API_BASE`、`NEWAPI_KEY`、`LITELLM_MASTER_KEY`、可选 `DATABASE_URL`。
+- `.env.local`：本地私有环境变量，保存 `NEWAPI_API_BASE`、`NEWAPI_KEY`、`Z_AI_CODING_API_BASE`、`Z_AI_API_KEY`、`LITELLM_MASTER_KEY`、可选 `DATABASE_URL`。
 
 固定常量如 `PORT=4000`、`CONFIG_FILE_PATH=/app/config.yaml` 保留在 `compose.yaml` 内部；环境差异值建议集中在 `.env.local`，再通过 `start.ps1` 追加的 `--env-file` 和 `compose.yaml` 的 `environment` 白名单注入到容器。
 
@@ -23,6 +23,8 @@ LITELLM_IMAGE=docker.litellm.ai/berriai/litellm:main-latest
 LITELLM_HOST_PORT=34000
 NEWAPI_API_BASE=http://new-api.example.com/v1
 NEWAPI_KEY=sk-newapi-dev-xxxx
+Z_AI_CODING_API_BASE=https://open.bigmodel.cn/api/coding/paas/v4
+Z_AI_API_KEY=sk-zai-dev-xxxx
 LITELLM_MASTER_KEY=sk-litellm-123456
 DATABASE_URL=postgresql://postgres:12345678@host.docker.internal:5432/litellm
 ```
@@ -33,6 +35,8 @@ DATABASE_URL=postgresql://postgres:12345678@host.docker.internal:5432/litellm
 - `LITELLM_HOST_PORT`：宿主机暴露端口，默认 `34000`。
 - `NEWAPI_API_BASE`：NewAPI 的 OpenAI 兼容接口地址，建议带上 `/v1`。
 - `NEWAPI_KEY`：LiteLLM 转发到 NewAPI 时使用的上游密钥。
+- `Z_AI_CODING_API_BASE`：智谱 GLM Coding Plan 的 OpenAI 兼容接口地址，默认建议使用官方专属端点。
+- `Z_AI_API_KEY`：LiteLLM 转发 `GLM-*` 请求到智谱 Coding Plan 时使用的上游密钥。
 - `LITELLM_MASTER_KEY`：LiteLLM Proxy 对外暴露的网关密钥。
 - `DATABASE_URL`：LiteLLM 的数据库连接串；如果未配置，会回退到默认的宿主机 PostgreSQL 地址。
 - `DASHSCOPE_API_KEY` / `DASHSCOPE_API_BASE`：可选兼容项；只有切回 `qwen.yaml` 或其他百炼配置时才需要提供。
@@ -112,6 +116,15 @@ curl http://127.0.0.1:34000/v1/chat/completions `
   -d "{\"model\":\"gemini-2.5-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}]}"
 ```
 
+如果你想通过 LiteLLM 调用 GLM Coding Plan，可直接传官方模型名，例如：
+
+```powershell
+curl http://127.0.0.1:34000/v1/chat/completions `
+  -H "Content-Type: application/json" `
+  -H "Authorization: Bearer sk-litellm-123456" `
+  -d "{\"model\":\"GLM-5.1\",\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}]}"
+```
+
 ## 模型查询
 
 如果你想查看 LiteLLM 当前暴露的路由名，可调用：
@@ -121,14 +134,16 @@ curl "http://127.0.0.1:34000/models?return_wildcard_routes=true" `
   -H "x-litellm-api-key: sk-litellm-123456"
 ```
 
-当前 `litellm.local.yaml` 默认显式注册了 `gpt-5.4`、`gemini-3.1-pro`、`claude-opus-4-6` 三个主模型，并在末尾保留了一条 `*` fallback 路由。因此 `/models` 会返回显式模型加上一条通配兜底路由。默认会看到类似下面的结果：
+当前 `litellm.local.yaml` 默认显式注册了 `gpt-5.4`、`gemini-3.1-pro`、`claude-opus-4-6`、`GLM-5.1` 四个主模型，并在末尾保留 `GLM-*` 与 `*` 两条 fallback 路由。因此 `/models` 会返回显式模型加上两条通配兜底路由。默认会看到类似下面的结果：
 
 ```json
 {
   "data": [
     {"id": "gpt-5.4", "object": "model"},
     {"id": "gemini-3.1-pro", "object": "model"},
     {"id": "claude-opus-4-6", "object": "model"},
+    {"id": "GLM-5.1", "object": "model"},
+    {"id": "GLM-*", "object": "model"},
     {"id": "*", "object": "model"}
   ],
   "object": "list"
@@ -142,18 +157,29 @@ curl "$env:NEWAPI_API_BASE/models" `
   -H "Authorization: Bearer $env:NEWAPI_KEY"
 ```
 
+如果你想获取智谱 Coding Plan 实际可用的模型名，请直接调用对应上游：
+
+```powershell
+curl "$env:Z_AI_CODING_API_BASE/models" `
+  -H "Authorization: Bearer $env:Z_AI_API_KEY"
+```
+
 说明：
 
 - 不要在当前配置下使用 `only_model_access_groups=true`，因为默认没有配置 model access groups，请求结果会是空数组。
 - 如果客户端直接传 `model=qwen-plus` 之类的名称，前提是该名称必须真实存在于 NewAPI 的 `/models` 返回结果中。
-- 显式注册之外的模型不会自动展开进 `/models` 列表；它们会通过 `*` fallback 透传到 NewAPI。
+- 如果客户端直接传 `model=GLM-4.7` 之类的官方名称，前提是该名称必须真实存在于智谱 Coding Plan 的 `/models` 返回结果中。
+- 显式注册之外的 GLM 模型不会自动展开进 LiteLLM 的 `/models` 列表；它们会优先通过 `GLM-*` fallback 转发到智谱上游。
+- 其它显式注册之外的非 GLM 模型，仍然通过最后的 `*` fallback 透传到 NewAPI。
 
 ## 配置说明
 
 当前 `litellm.local.yaml` 的关键点：
 
-- `model_list`：显式注册 `gpt-5.4`、`gemini-3.1-pro`、`claude-opus-4-6` 三个主模型，并追加 `*` 作为最后兜底。
+- `model_list`：显式注册 `gpt-5.4`、`gemini-3.1-pro`、`claude-opus-4-6`、`GLM-5.1` 四个主模型，并追加 `GLM-*` 与 `*` 两层兜底。
 - 显式模型优先：常用模型可以稳定出现在 `/models` 里，也方便客户端按固定名称接入。
-- `*` fallback：对 NewAPI 已存在但未显式注册的模型保留透传能力，减少频繁改本地配置的成本。
-- `litellm_params.model`：显式模型映射到 `openai/<模型名>`，fallback 映射到 `openai/*`，继续通过 NewAPI 的 OpenAI 兼容接口转发请求。
+- `GLM-*` fallback：对智谱 Coding Plan 已存在但未显式注册的 GLM 官方模型保留透传能力，同时避免误落到 NewAPI。
+- `*` fallback：对 NewAPI 已存在但未显式注册的非 GLM 模型保留透传能力，减少频繁改本地配置的成本。
+- `litellm_params.model`：显式模型和通配规则都映射到 `openai/<模型名>` 形式，继续通过 OpenAI 兼容接口转发到各自上游。
 - `master_key`：开启 LiteLLM 网关鉴权，避免任何能访问端口的客户端都直接调用上游。
+- `Codex` 直连：当前 `ai/coding/codex/config.toml` 里的 `z.ai` provider 保持不变；本目录改动只补充 LiteLLM 网关入口。

ai/gateway/litellm/newapi.yaml

@@ -20,6 +20,20 @@ model_list:
       model: "openai/claude-opus-4-6"
       api_base: "os.environ/NEWAPI_API_BASE"  # 从环境变量读 NewAPI 地址
       api_key: "os.environ/NEWAPI_KEY"        # 从环境变量读密钥
+  # 显式注册 GLM Coding Plan 主模型，便于 `/models` 稳定暴露官方模型名。
+  - model_name: "GLM-5.1"
+    litellm_params:
+      # 智谱 Coding Plan 走独立 OpenAI 兼容端点，继续复用 LiteLLM 的 OpenAI provider。
+      model: "openai/GLM-5.1"
+      api_base: "os.environ/Z_AI_CODING_API_BASE"  # 从环境变量读智谱 Coding Plan 地址
+      api_key: "os.environ/Z_AI_API_KEY"           # 从环境变量读智谱密钥
+  # 为其它官方 GLM 模型保留专属兜底，避免误落到最后的全局 `* -> NewAPI`。
+  - model_name: "GLM-*"
+    litellm_params:
+      # 由 LiteLLM 按请求中的官方模型名透传，例如 `GLM-4.7`。
+      model: "openai/GLM-*"
+      api_base: "os.environ/Z_AI_CODING_API_BASE"  # 从环境变量读智谱 Coding Plan 地址
+      api_key: "os.environ/Z_AI_API_KEY"           # 从环境变量读智谱密钥
   # 把 wildcard 路由放在最后，优先命中显式模型，其余上游模型再走透传兜底。
   - model_name: "*"
     litellm_params: