Add experimental Lingma remote backend

2026-04-30 12:09:51 +08:00
parent 1c188fcf17
commit 2bcb0a6715
15 changed files with 1543 additions and 37 deletions
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -9,9 +9,14 @@
 - **CLI 代理服务**：适合后台常驻、脚本化和服务器式运行。
 - **跨平台桌面 App**：适合日常可视化管理，支持 macOS 和 Windows。

+代理后端支持两种模式：
+
+- **IPC 插件模式（默认）**：连接本机 Lingma IDE 插件的 WebSocket / Named Pipe。优点是更接近 IDE 插件上下文，适合日常稳定使用。
+- **远端 API 模式（实验）**：读取 Lingma 本地登录缓存或显式凭据，直接调用 Lingma 远端接口。优点是不依赖 IDE 插件窗口和 IPC 会话，体验更像官方 API；缺点是依赖本地登录态字段和非公开接口，未来可能失效。
+
 ## 当前版本

-当前桌面端版本线：`v1.3.2`
+当前桌面端版本线：`v1.4.0`

 GitHub Actions 会在 Release 中产出：

@@ -47,6 +52,7 @@ GitHub Actions 会在 Release 中产出：
 | 多轮 Agent 工具循环 | 支持 |
 | 图片输入 | 支持 base64、data URL、HTTP URL |
 | 请求 / 响应完整日志 | 桌面端支持完整查看和复制 |
+| 后端模式切换 | 支持 IPC 插件模式 / 远端 API 模式 |
 | macOS WebSocket 自动探测 | 支持 |
 | Windows Named Pipe / WebSocket 探测 | 支持 |
 | 日间 / 夜间 / 跟随系统主题 | 桌面端支持 |
@@ -85,10 +91,12 @@ GitHub Actions 会在 Release 中产出：

 | 端点 | 方法 | 说明 |
 | --- | --- | --- |
-| `/` | GET | 健康检查 |
-| `/health` | GET | 健康检查 |
+| `/` | GET / HEAD | 健康检查；`HEAD /` 用于兼容 Claude Code 等客户端的基础探测 |
+| `/health` | GET / HEAD | 健康检查 |
 | `/v1/models` | GET | 获取 Lingma 可用模型列表 |
 | `/capabilities` / `/v1/capabilities` | GET | 能力探测，给第三方 Agent 识别协议、工具、图片能力 |
+| `/debug/requests` / `/debug/logs` | GET | 查询最近 HTTP 请求记录，用于本地调试 |
+| `/api/requests` / `/api/logs` | GET | 请求 / 日志调试接口别名 |
 | `/api/v1/models` / `/api/tags` / `/props` | GET | LM Studio / Ollama / llama.cpp / vLLM 风格探测兼容 |
 | `/v1/chat/completions` | POST | OpenAI Chat Completions 兼容接口 |
 | `/api/v1/chat/completions` | POST | OpenAI Chat Completions 别名 |
@@ -102,6 +110,7 @@ GitHub Actions 会在 Release 中产出：
 - **工具结果接力**：支持多轮 Agent 工具调用，把工具结果继续回灌给 Lingma 生成最终回答。
 - **工具稳定性增强**：代理层自动生成工具路由表，给 `read_file` / `search_files` / `terminal` / `web_search` 注入专门示例；当模型说“无法访问 / 请手动运行 / 请粘贴文件”时自动重试工具调用。
 - **工具别名映射**：兼容常见模型输出的 `Bash` -> `terminal`、`Read` -> `read_file`、`Grep` -> `search_files`、`Edit` -> `patch`。
+- **Anthropic 流式工具调用增强**：当 Claude Code 这类客户端使用 `stream=true` 并携带 tools 时，代理会先在内部完成工具 action block 解析和拒绝重试，再输出标准 `tool_use` 流，避免提前把“请你自己运行命令”这类文本发给客户端。
 - **图片输入**：兼容 OpenAI `image_url` 和 Anthropic base64 image block。
 - **本地图片路径兼容**：OpenAI `image_url.url` 支持 data URL、HTTP URL、`file://`、绝对路径和 `~/` 路径。
 - **图片自动压缩**：大图会自动缩放并转 JPEG，避免 Lingma 被超大 base64 卡死。
@@ -167,11 +176,14 @@ flowchart LR
  Service --> Tooling["工具调用模拟"]
  Service --> Model["模型探测"]
  Service --> Recorder["请求 / 日志记录"]
-  Service --> Transport["Lingma 传输层"]
+  Service --> Backend{"后端模式"}
+  Backend --> Transport["IPC 插件传输层"]
+  Backend --> Remote["远端 API 客户端"]
  Transport --> Pipe["Windows Named Pipe"]
  Transport --> WS["WebSocket"]
  Pipe --> Lingma["通义灵码 IDE 插件"]
  WS --> Lingma
+  Remote --> Cloud["Lingma 远端接口"]
 ```

 ### 目录结构
@@ -182,6 +194,7 @@ flowchart LR
 | `internal/httpapi` | OpenAI / Anthropic 路由、请求解析、SSE 流式响应、请求记录 |
 | `internal/service` | 业务编排、会话生命周期、模型探测、代理运行状态 |
 | `internal/lingmaipc` | Lingma JSON-RPC 通信，Named Pipe / WebSocket 传输 |
+| `internal/remote` | Lingma 远端 API 登录态读取、签名、模型列表和流式响应解析 |
 | `internal/toolemulation` | 工具定义注入、动作块解析、工具结果回灌 |
 | `desktop` | Wails 桌面壳、窗口命令、代理生命周期桥接 |
 | `desktop/frontend` | Vue 前端页面，包含仪表盘、请求流、模型、设置、日志 |
@@ -194,8 +207,8 @@ flowchart LR
 2. HTTP 层识别 OpenAI / Anthropic 请求格式。
 3. Service 层归一化消息、图片、工具定义和参数。
 4. Session 管理层决定复用会话、创建新会话或使用自动策略。
-5. Transport 层连接 Lingma 插件的 Named Pipe 或 WebSocket。
-6. Lingma 返回增量事件或最终响应。
+5. Service 根据 `backend` 选择 IPC 插件传输或 Lingma 远端 API。
+6. Lingma 插件或远端接口返回增量事件 / 最终响应。
 7. HTTP 层转换成 OpenAI SSE、Anthropic SSE 或普通 JSON。
 8. 桌面端同步记录请求、响应、耗时、状态码和日志。

@@ -220,6 +233,66 @@ lingma-ipc-proxy --transport websocket --ws-url ws://127.0.0.1:36510 --port 8095
 lingma-ipc-proxy --transport pipe --pipe '\\.\pipe\lingma-ipc'
 ```

+## 后端模式
+
+### IPC 插件模式（默认）
+
+IPC 模式通过本机 Lingma IDE 插件通信：
+
+```bash
+lingma-ipc-proxy --backend ipc --transport auto --port 8095
+```
+
+适合已经打开 VS Code / Lingma 插件、希望使用插件当前会话环境、并优先使用插件探测模型列表的场景。
+
+### 远端 API 模式（实验）
+
+远端模式直接调用 Lingma 远端接口：
+
+```bash
+lingma-ipc-proxy --backend remote --port 8095
+```
+
+默认会只读导入：
+
+```text
+~/.lingma/cache/user
+~/.lingma/cache/id
+~/.lingma/logs/lingma.log
+```
+
+也可以指定显式凭据文件：
+
+```bash
+lingma-ipc-proxy \
+  --backend remote \
+  --remote-base-url https://lingma.alibabacloud.com \
+  --remote-auth-file ~/.config/lingma-ipc-proxy/credentials.json
+```
+
+`credentials.json` 格式：
+
+```json
+{
+  "source": "manual",
+  "token_expire_time": "1777520000000",
+  "auth": {
+    "cosy_key": "xxx",
+    "encrypt_user_info": "xxx",
+    "user_id": "123",
+    "machine_id": "xxxxxxxxxxxxxxxx"
+  }
+}
+```
+
+说明：
+
+- 远端模式不会写入或迁移你的登录态，只会读取本机 Lingma 缓存或你指定的凭据文件。
+- 如果 Lingma 插件配置过专属域名，可以通过 `--remote-base-url`、`LINGMA_REMOTE_BASE_URL` 或配置文件显式指定。
+- 远端模式的 `/v1/models` 返回的是远端接口模型 key，不一定等同于 IPC 插件模式里看到的 `MiniMax-M2.7`、`Kimi-K2.6` 等展示名。
+- 当前本机实测：`/health`、`/v1/models`、OpenAI 流式 / 非流式、Claude Code Anthropic + Bash 工具调用均可用；Claude Code 完整工具链耗时明显高于简单 OpenAI 请求。
+- 该模式参考了 [ZipperCode/lingma2api](https://github.com/ZipperCode/lingma2api) 对 Lingma 远端接口、签名和登录态结构的探索，本仓库将其作为可切换后端集成到现有 OpenAI / Anthropic / 桌面 App 架构中。
+
 ## 快速开始

 ### 前置条件
@@ -343,7 +416,11 @@ export ANTHROPIC_API_KEY="any"
 {
  "host": "127.0.0.1",
  "port": 8095,
+  "backend": "ipc",
  "transport": "auto",
+  "remote_base_url": "",
+  "remote_auth_file": "",
+  "remote_version": "",
  "mode": "agent",
  "shell_type": "zsh",
  "session_mode": "auto",
@@ -399,6 +476,7 @@ Lingma 插件本身没有公开标准 OpenAI / Anthropic Tools 协议，所以
 - 对 `read_file`、`search_files`、`terminal`、`web_search` 注入专门示例。
 - 当模型回答“无法访问文件 / 无法联网 / 请手动运行 / 请粘贴内容”时，代理会自动追加强制工具调用提示并重试一次。
 - 自动归一化常见工具名别名：`Bash`、`Shell`、`Read`、`Grep`、`Edit`、`Fetch` 等。
+- Anthropic `stream=true` 且请求包含 tools 时，会先内部完成生成和重试，再流式输出最终 `tool_use` 事件，避免 Claude Code 这类客户端先收到普通拒绝文本。

 本地压测结果：`MiniMax-M2.7`、`Kimi-K2.6`、`Qwen3.6-Plus`、`Qwen3-Coder` 均通过 read/search/terminal/web/patch/vision 烟测；其中 `MiniMax-M2.7` 平均延迟最低，所以作为默认推荐。

@@ -418,6 +496,23 @@ Lingma 插件本身没有公开标准 OpenAI / Anthropic Tools 协议，所以

 请求体和响应体不会再用无意义的展开 / 收起按钮截断展示；内容过长时会在详情区域内部滚动，并隐藏滚动条，便于小窗口下查看完整内容。

+除了桌面端页面，HTTP 服务本身也提供只读调试接口，方便后续排查 Claude Code、Hermes、Cline 等客户端到底传了什么请求：
+
+```bash
+curl http://127.0.0.1:8095/health
+curl -I http://127.0.0.1:8095/
+curl 'http://127.0.0.1:8095/debug/requests?limit=20'
+curl 'http://127.0.0.1:8095/debug/logs?limit=20'
+```
+
+说明：
+
+- `/debug/requests` 和 `/debug/logs` 返回最新记录在前。
+- 每条记录包含时间、HTTP 方法、路径、状态码、耗时、脱敏后的请求体和响应体。
+- 服务端最多保留最近 200 条 HTTP 记录，只保存在内存中，重启后清空。
+- 图片 payload 和大段 base64 会被标记脱敏，超长请求 / 响应会截断，避免日志页面被撑爆。
+- 这些接口用于本机调试，不建议暴露到不可信网络。
+
 ## 本地构建桌面端

 安装 Wails：
@@ -455,8 +550,8 @@ Lingma IPC Proxy
 发布方式：

 ```bash
-git tag v1.3.2
-git push origin v1.3.2
+git tag v1.4.0
+git push origin v1.4.0
 ```

 也可以在 GitHub Actions 页面手动运行 `Release` workflow，并输入 tag。