mmc/lingma-proxy-compose

Fork 0

Files

lutc5 1c349227a3 Rename product to Lingma Proxy

2026-05-06 15:03:04 +08:00

7.6 KiB

Raw Blame History

Lingma Proxy 架构文档

本文档描述 Lingma Proxy 的当前架构，覆盖两种后端模式：

remote：默认推荐模式，使用探测到的登录态直接调用 Lingma 远端 HTTP API
ipc：兼容模式，桥接本地 Lingma IDE 插件传输层

1. 系统总览

flowchart LR
    A["客户端<br/>Claude Code / Hermes / Cline / Continue / OpenAI SDK / Anthropic SDK"]
    B["internal/httpapi<br/>OpenAI + Anthropic 兼容路由"]
    C["internal/service<br/>请求归一化 / 会话策略 / 流式输出 / 兜底"]
    D["internal/toolemulation<br/>工具提示词注入 + action block 解析"]
    E["internal/lingmaipc<br/>WebSocket / 命名管道"]
    F["internal/remote<br/>登录态探测 / 模型列表 / Chat / SSE"]
    G["Lingma 插件本地进程"]
    H["Lingma 远端 API"]
    I["桌面端 GUI<br/>Wails / 日志 / Token 统计 / 持久化状态"]

    A --> B
    I --> B
    B --> C
    C --> D
    C --> E
    C --> F
    E --> G
    F --> H

2. 运行模式

2.1 Remote API 模式

backend=remote

从配置、环境变量或本地 Lingma 日志中解析远端域名
加载认证信息：
- 显式指定的 remote_auth_file
- 或自动探测 Lingma 登录缓存
直接请求远端模型列表和聊天接口
支持远端超时 / 429 / 5xx 的模型兜底切换
不依赖本地插件会话环境参数
避免 IDE / 插件 IPC 会话生命周期、工作目录和扩展环境限制

2.2 IPC 插件模式

backend=ipc

读取本地 Lingma 插件传输信息
通过以下方式连接：
- macOS / Linux：WebSocket
- Windows：Named Pipe
复用 Lingma 插件自身的 session 语义
桌面端里“会话与环境”相关配置只在这里生效
该模式基于 coolxll/lingma-ipc-proxy 的 IPC 协议发现思路

3. 模块职责

3.1 `cmd/lingma-ipc-proxy`

入口与配置装配层。

职责：

解析命令行参数
合并配置文件 / 环境变量 / CLI flags
选择后端模式
构建 service.Config
启动 internal/httpapi.Server

关键配置字段：

backend
transport
websocket_url
pipe
remote_base_url
remote_auth_file
remote_version
remote_fallback_enabled
remote_fallback_models

3.2 `internal/httpapi`

OpenAI / Anthropic 兼容层。

主要路由：

GET /v1/models
POST /v1/chat/completions
POST /v1/messages
GET /health
GET /props

职责：

把 OpenAI / Anthropic 请求归一化为 service.ChatRequest
把 service 结果重新编码成 OpenAI / Anthropic 响应
输出 SSE 流
记录调试用请求 / 响应摘要

3.3 `internal/service`

核心编排层。

职责：

选择当前 backend
backend 预热
拉取模型列表
非流式生成
流式生成
IPC 模式下的 session 复用策略
工具模拟注入与解析
图片输入归一化
远端 fallback 顺序控制

分支逻辑：

IPC 路径走 internal/lingmaipc
Remote 路径走 internal/remote

3.4 `internal/lingmaipc`

本地 Lingma 插件 IPC 客户端。

职责：

自动探测 WebSocket / pipe 端点
建立连接与重连
发送 RPC：
- session/new
- session/prompt
- session/set_model
- chat/deleteSessionById
消费 session/update 通知

3.5 `internal/remote`

Lingma 远端 HTTP 客户端。

职责：

解析远端 base URL
加载并校验登录态
生成远端请求所需身份信息
获取远端模型列表
调用远端聊天接口
处理远端 SSE 流式响应

3.6 `internal/toolemulation`

工具调用模拟层。

职责：

从 OpenAI / Anthropic 请求中提取工具定义
将工具契约注入 prompt
从模型文本里解析 JSON action block
回投为：
- Anthropic tool_use
- OpenAI tool_calls

4. 请求主流程

4.1 通用入口

sequenceDiagram
    participant Client as Client
    participant HTTP as httpapi
    participant Service as service

    Client->>HTTP: OpenAI / Anthropic 请求
    HTTP->>HTTP: 归一化请求
    HTTP->>Service: Generate / GenerateStream

4.2 IPC 后端流程

sequenceDiagram
    participant Service as service
    participant Tool as toolemulation
    participant IPC as lingmaipc
    participant Plugin as Lingma 插件

    Service->>Tool: 按需注入工具契约
    Service->>IPC: ensure connected
    Service->>IPC: 创建/复用 session
    Service->>IPC: session/prompt
    IPC->>Plugin: RPC
    Plugin-->>IPC: session/update chunk
    IPC-->>Service: 流式事件
    Service-->>Service: 解析工具 block / 图片 / stop reason

4.3 Remote 后端流程

sequenceDiagram
    participant Service as service
    participant Remote as remote client
    participant API as Lingma 远端 API

    Service->>Remote: 加载登录态 / 初始化 client
    Service->>Remote: 需要时拉取模型列表
    Service->>Remote: 发送 chat 请求
    Remote->>API: HTTPS
    API-->>Remote: JSON 或 SSE
    Remote-->>Service: 归一化结果
    Service-->>Service: 按条件执行 fallback

5. 远端兜底策略

仅在以下条件同时满足时启用：

backend=remote
remote_fallback_enabled=true
还没有向客户端输出任何流式 token
上游错误属于 timeout / 429 / 5xx

当前默认顺序：

kmodel
mmodel
dashscope_qwen3_coder
dashscope_qmodel
dashscope_qwen_max_latest
dashscope_qwen_plus_20250428_thinking

实际执行前，service 会先拿远端 /v1/models 的真实结果过滤一遍，只保留当前账号真的可用的模型。

6. 桌面端架构

Wails 桌面端不是简单预览壳，而是本地代理的运维控制台。

职责：

启动 / 停止 / 重启代理
展示当前 backend、监听地址、探测结果
持久化：
- 请求历史
- 日志
- Token 统计
编辑配置并保存后按需重启

本地持久化路径：

配置：~/.config/lingma-proxy/config.json
旧配置兼容读取：~/.config/lingma-ipc-proxy/config.json
GUI 运行状态：~/.config/lingma-ipc-proxy/app-state.json

打包要求：

生产包不自动打开 Inspector / 调试入口
本地开发可通过 LINGMA_DESKTOP_DEBUG=1 显式开启

7. 关键设计决策

7.1 为什么同时保留 IPC 和 Remote？

因为两种模式解决的问题不同：

Remote 模式避免插件运行时耦合，通常更适合第三方 Agent 客户端。
IPC 模式保留插件会话语义，适合明确需要本地插件上下文或插件模型列表的场景。

7.2 为什么 Remote 也保留 Tool Emulation？

因为 Lingma 暴露出来的模型能力并不保证始终稳定兼容 OpenAI / Anthropic 原生 tools 协议。代理层必须对外提供稳定契约，不能把上游模型差异直接泄露给客户端。

7.3 为什么桌面端要持久化请求和 Token？

因为这个 GUI 已经是运维面板，不是一次性调试页。重启后仍然需要保留最近请求、日志和 usage 统计，便于排障和观察模型表现。

8. 当前边界

IPC 模式仍然受本地 Lingma 插件运行态影响
Remote 登录态探测依赖本地 Lingma 缓存结构
图片类请求在本地持久化时会做裁剪/脱敏，避免状态文件过大
Remote 模式下如果启用了 fallback，最近一次“聊天模型”可能与客户端最初指定模型不同

9. 代码入口建议

如果要继续扩展，优先看这些文件：

cmd/lingma-ipc-proxy/main.go
internal/httpapi/server.go
internal/service/service.go
internal/lingmaipc/*
internal/remote/*
desktop/app.go
desktop/main.go

文档版本：2026-05-06

7.6 KiB Raw Blame History Unescape Escape