Lingma OpenAI Gateway

把本地 Lingma 能力封装为 OpenAI 兼容接口，支持：

• GET /v1/models
• POST /v1/chat/completions
• stream=true（SSE）
• Bearer API Key 鉴权

1. 准备目录

mkdir -p data

说明：

• 启动时会自动获取最新插件并提取 Lingma 到 data/bin。
• 默认通过 VSCode Marketplace 查询最新版本，再下载对应 VSIX。
• 登录态与运行数据统一写入 data/.lingma。

2. 配置环境变量

cp .env.example .env

至少修改：

• API_KEYS
• LINGMA_USERNAME
• LINGMA_PASSWORD

如果你的 Lingma 路径不同，修改：

• LINGMA_BIN

可选（企业专属域）：

• DEDICATED_DOMAIN_URL

.env 字段说明（简版）

• HOST：网关监听地址（通常 0.0.0.0）
• PORT：网关监听端口（外部调用端口）
• API_KEYS：Bearer Key，多个用逗号分隔
• LINGMA_BIN：容器内 Lingma 路径
• LINGMA_SOURCE_TYPE：二进制来源（marketplace/vsix）
• LINGMA_MARKETPLACE_PUBLISHER：Marketplace 发布者
• LINGMA_MARKETPLACE_EXTENSION：Marketplace 扩展名
• LINGMA_VSIX_URL：VSIX 下载地址（最新优先）
• LINGMA_BOOTSTRAP_ALWAYS：启动时是否总尝试刷新 Lingma
• LINGMA_FORCE_REFRESH：是否强制刷新（忽略本地缓存）
• LINGMA_WORK_DIR：Lingma 工作目录（登录与会话数据）
• LINGMA_SOCKET_PORT：Lingma 本地 WS 端口
• LINGMA_STARTUP_TIMEOUT：Lingma 启动等待秒数
• LINGMA_RPC_TIMEOUT：单次 RPC 超时秒数
• DEFAULT_MODEL：默认模型（无法映射时兜底）
• DEFAULT_ASK_MODE：默认模式（chat/agent）
• DEDICATED_DOMAIN_URL：企业专属域（可留空）
• AUTO_LOGIN_ENABLED：未登录时自动登录开关
• AUTO_LOGIN_HEADLESS：自动登录是否无头浏览器
• AUTO_LOGIN_TIMEOUT：自动登录超时秒数
• AUTO_LOGIN_MAX_RETRY：自动登录重试次数
• LINGMA_USERNAME：Lingma 登录用户名
• LINGMA_PASSWORD：Lingma 登录密码
• METRICS_TOKEN：/metrics 独立鉴权 token（留空则 API_KEYS 也可访问；两者皆空时 /metrics 默认 503，除非显式开 METRICS_PUBLIC=true）
• METRICS_PUBLIC：显式把 /metrics 设为公开，仅在私网采集器场景使用（默认 false）
• ADMIN_TOKEN：/internal/* 管理端点独立鉴权 token（留空则退化为 API_KEYS）。生产环境建议单独配置，这样轮换 API_KEYS 不需要重新颁发 session bundle 导出权限
• LOG_LEVEL：日志级别（默认 INFO，输出结构化 JSON，包含 request_id）
• GATEWAY_MAX_IN_FLIGHT：/v1/chat/completions 并发上限（默认 4，<=0 表示不限流）
• GATEWAY_QUEUE_TIMEOUT_SEC：排队等待超时秒数（默认 30，超过后直接 429 + Retry-After）
• LINGMA_ACCOUNTS：多账号实例池，格式 u1:p1,u2:p2 或 JSON 数组；配置后每个账号起一个独立 Lingma 子进程
• LINGMA_INSTANCE_COUNT：实例数（默认等于账号数；显式指定且不足时账号会循环复用）
• SESSION_REUSE_ENABLED：多轮对话复用上游 sessionId（默认 true）。命中时只把最新一条 user 消息发给 Lingma，命中上游 KV cache，显著降低第 2 轮及以后的首 token 延迟
• SESSION_CACHE_MAX_ENTRIES：会话缓存容量（LRU，默认 256）
• SESSION_CACHE_TTL_SEC：会话缓存 TTL 秒数（默认 1800；超时自动失效，避免复用到已被 Lingma 回收的 session）
• LINGMA_SESSION_BUNDLE / LINGMA_SESSION_BUNDLE_FILE：已登录态注入，跳过 Playwright。具体见下方"跳过自动登录"章节

.env 最小必填示例

PORT=8317
API_KEYS=sk-your-api-key
LINGMA_USERNAME=your-username
LINGMA_PASSWORD=your-password
LINGMA_BIN=/app/data/bin/Lingma
LINGMA_WORK_DIR=/app/data/.lingma/vscode/sharedClientCache
LINGMA_SOURCE_TYPE=marketplace
LINGMA_MARKETPLACE_PUBLISHER=Alibaba-Cloud
LINGMA_MARKETPLACE_EXTENSION=tongyi-lingma
LINGMA_VSIX_URL=https://tongyi-code.oss-cn-hangzhou.aliyuncs.com/vscode/tongyi-lingma-latest.vsix
DEDICATED_DOMAIN_URL=

数据目录说明

• 本项目所有持久化数据都在 ./data：
  • data/bin/Lingma：自动提取的 Lingma 二进制
  • data/.lingma/...：Lingma 登录态、缓存、日志（单实例模式）
  • data/.lingma/pool/inst-<i>/...：多实例模式下每个实例独立的登录态/缓存

多实例池（方案乙：多账号）

启用方式：在 .env 里配置 LINGMA_ACCOUNTS=u1:p1,u2:p2，重启容器即可。

• 每个账号对应一个独立 Lingma 子进程，各自独立登录、独立 workDir。
• 路由策略：同一 user 字段或同一 system prompt 的请求粘性路由到同一实例；其余按 least-in-flight 分配。
• 一个实例挂了/断连不影响整体，/healthz 汇报 pool_ready 计数。
• /internal/stats.pool 按实例粒度暴露状态，/metrics 增加 gateway_pool_instance_in_flight{name} / gateway_pool_instance_ready{name}。
• 未配置 LINGMA_ACCOUNTS 时自动退化为单实例模式（沿用 LINGMA_USERNAME/LINGMA_PASSWORD），向下兼容。

跳过自动登录（session bundle 注入）

Playwright 登录偶尔会因为反爬虫策略失败。如果你已经有一个登录好的 Lingma workDir（本项目任意历史部署、或 VSCode 插件的 shared cache），可以直接把那 份登录态导出成 "bundle" 注入到新的部署，完全跳过浏览器。

导出（在一个已登录的 gateway 上执行）：

curl -sS -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "http://host:port/internal/session/export" \
  | jq -r '.bundle_b64' > lingma-session.b64

可选 ?instance=inst-0 指定从哪个实例导出（多实例场景）。

注入（新部署的 .env 三选一）：

# 方式 1：直接塞 base64
LINGMA_SESSION_BUNDLE=H4sIAAAA...

# 方式 2：从文件读（推荐，避免 env 过长）
LINGMA_SESSION_BUNDLE_FILE=/secrets/lingma-session.b64

# 方式 3：多账号模式，每个账号独立 bundle（JSON 模式）
LINGMA_ACCOUNTS=[
  {"username":"u1","password":"p1","session_bundle_file":"/secrets/u1.b64"},
  {"username":"u2","password":"p2","session_bundle":"H4sIAAAA..."}
]

行为：

• bundle 只在目标 workDir 没有 已有登录态（即 cache/user 为空或不存在）时才注入，不会覆盖活跃的登录。
• 注入成功后 Lingma 启动时直接 ready，auth_status() 命中已登录，跳过 Playwright。
• 注入失败（bundle 损坏、权限不足等）自动 fallback 到原有 Playwright 流程。
• bundle 只打包 cache/{id,user,quota,config.json} 四个文件，不包含 db/logs/index，体积通常 < 10 KB。
• bundle 含敏感 token，按密钥保管，不要写入公共仓库。

3. Docker 运行

docker compose up -d --build

说明：

• 构建阶段已默认使用腾讯云 PyPI 镜像（mirrors.cloud.tencent.com）。
• 如需自定义镜像源，可在 docker-compose.yml 的 build.args 中修改。

查看日志：

docker compose logs -f

4. 调用示例

模型列表

curl -s http://127.0.0.1:8317/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

说明：

• id 保持 Lingma 原始模型 key（兼容 OpenAI 客户端）
• name 提供可读名称（如 qwen3.6-plus）
• 调用 /v1/chat/completions 时，model 既可传 id，也可直接传 name

非流式聊天

curl -s http://127.0.0.1:8317/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dashscope_qmodel",
    "messages": [
      {"role": "user", "content": "写一个 python hello world"}
    ]
  }'

流式聊天

curl -N http://127.0.0.1:8317/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dashscope_qmodel",
    "stream": true,
    "messages": [
      {"role": "user", "content": "介绍一下你自己"}
    ]
  }'

5. 统计与监控

支持调用次数与 token（估算值）统计：

• GET /internal/stats（需 Bearer）
• GET /metrics（Prometheus 文本格式）

示例：

curl -s http://127.0.0.1:8317/internal/stats \
  -H "Authorization: Bearer sk-xxx"

curl -s http://127.0.0.1:8317/metrics \
  -H "Authorization: Bearer ${METRICS_TOKEN:-sk-your-api-key}"

说明：

• usage.prompt_tokens/completion_tokens 为估算值（按字节近似换算）。
• 非流式响应里会附带 usage 字段。
• 流式响应可传 stream_options: {"include_usage": true} 让最后一帧返回 usage。
• /metrics 默认需要 Bearer 鉴权：优先匹配 METRICS_TOKEN，否则接受 API_KEYS 里任意一个；两者皆未配置时返回 503，显式 METRICS_PUBLIC=true 才公开。
• /internal/* 管理端点（auto-login, session export, models/raw, stats）默认走 ADMIN_TOKEN，未配置时退化为 API_KEYS；两者都未配置则 503。

6. 容器内自动登录

已内置自动登录能力（Playwright + Chromium）。

你可以主动触发：

curl -s -X POST http://127.0.0.1:8317/internal/auto-login/start \
  -H "Authorization: Bearer sk-your-api-key"

查看状态：

curl -s http://127.0.0.1:8317/internal/auto-login/status \
  -H "Authorization: Bearer sk-your-api-key"

说明：

• 若未登录，/v1/models 与 /v1/chat/completions 也会尝试自动登录。
• 账号密码来自 .env（LINGMA_USERNAME / LINGMA_PASSWORD）。
• 建议仅在受控环境使用，并妥善保护 .env。

7. agent 模式

在 v1 中，若 model 传 agent 或 lingma-agent，会走 agent 模式。

curl -s http://127.0.0.1:8317/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent",
    "messages": [
      {"role": "user", "content": "分析这个项目目录结构"}
    ]
  }'