From d9dffbb8ba57a38b68d69208a5df1c6a0986a709 Mon Sep 17 00:00:00 2001
From: GitHub Actions <actions@github.com>
Date: Sat, 18 Apr 2026 10:36:17 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20restructure=20README=20+=20add=20DESIGN?=
 =?UTF-8?q?.md=20(=E4=BA=8C=E5=BC=80=E7=99=BD=E7=9B=92=E6=89=8B=E5=86=8C)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README 重写为分层结构：架构速览 + 快速开始 + 按主题分组的配置表 +
API 参考 + 常用场景 + 升级注意 + 故障排查 + 二开入口。相比旧版：
更好导航，破坏性改动显式标注升级路径，故障排查能覆盖生产常见坑。

DESIGN.md 是全新的工程手册，覆盖：项目目标/非目标、组件数据流、
模块职责表、6 个核心流程的 ASCII 图解（启动、非流式/流式 chat、
子进程 + LSP、bundle、自动登录、关闭）、11 条关键设计决策
（每条带问题/方案/权衡/未选其他方案原因）、扩展指引（常见需求 → 改哪些文件）、
已知问题 / TODO、完整迭代历程（M1~M4 + M3 性能 bug 根因）、
Lingma LSP 协议速查。

目标：新成员或几个月后的自己能在一天内理清全项目。

Made-with: Cursor
---
 DESIGN.md | 655 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 525 ++++++++++++++++++++++++-------------------
 2 files changed, 953 insertions(+), 227 deletions(-)
 create mode 100644 DESIGN.md

diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..7cd214b
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,655 @@
+# Lingma OpenAI Gateway — 架构与二开手册
+
+> 这份文档是项目的"白盒"。读完应该能回答：
+>
+> - 为什么项目长这样，而不是别的样子？
+> - 每个模块各自的职责和边界是什么？
+> - 想加/改一个功能，应该从哪下手？
+> - 历史上踩过什么坑，现在的做法解决了什么问题？
+>
+> 代码本身是最权威文档，这里只解释**"为什么"**和**"怎么一起工作"**。
+
+---
+
+## 目录
+
+- [1. 项目目标与非目标](#1-项目目标与非目标)
+- [2. 整体架构](#2-整体架构)
+- [3. 模块职责表](#3-模块职责表)
+- [4. 核心流程](#4-核心流程)
+  - [4.1 启动](#41-启动)
+  - [4.2 非流式 chat](#42-非流式-chat-请求)
+  - [4.3 流式 chat + session cache 命中](#43-流式-chat--session-cache-命中)
+  - [4.4 子进程与 LSP 通信](#44-lingma-子进程与-lsp-通信)
+  - [4.5 Session bundle 导入/导出](#45-session-bundle-导入导出)
+  - [4.6 自动登录](#46-自动登录-playwright)
+  - [4.7 关闭](#47-关闭)
+- [5. 关键设计决策](#5-关键设计决策)
+- [6. 扩展指引](#6-扩展指引要做-x-改哪里)
+- [7. 已知问题 / 未完成项](#7-已知问题--未完成项)
+- [8. 迭代历程](#8-迭代历程)
+- [9. 上游协议速查](#9-lingma-lsp-协议速查)
+
+---
+
+## 1. 项目目标与非目标
+
+### 目标
+
+1. **OpenAI 协议兼容**：任何支持 OpenAI 的客户端（curl、Cursor、Dify、LangChain、LiteLLM…）不改代码就能接入 Lingma。
+2. **单节点生产可用**：自用场景下能长期跑 7×24，包含合理的观测、鉴权、背压、错误恢复。
+3. **最大化利用单账号 / 多账号的配额**：通过多实例池 + 会话复用把后端吞吐做到接近原始 VSCode 插件水平。
+4. **降低运维成本**：首次登录成功后，可以导出一份 bundle 永久复用，彻底摆脱浏览器自动化的不稳定性。
+5. **保持可读**：总代码量控制在数千行，新人（或几个月后的自己）能在一天内理清。
+
+### 非目标
+
+- **逆向 Lingma 后端协议**：之前评估过（曾经的"B1 终极方案"），需要反编译二进制，维护成本高、政策风险大，放弃。
+- **多租户 / 水平扩缩**：单容器即可；真要大规模部署 → 套层反代 + N 个网关副本就够，不在进程内解决。
+- **完整 function calling / tools**：OpenAI schema 里保留了字段，但目前不透传给 Lingma（Lingma 侧没有等价能力）。
+- **多模态**：请求里的 image/audio 会被降级成占位符 `[image]` / `[audio]`，因为 Lingma chat 不支持。
+
+---
+
+## 2. 整体架构
+
+### 组件与数据流
+
+```
+                   HTTP请求                 背压票                      选实例
+   客户端 ───▶ FastAPI(main)──▶ auth ──▶ InFlightGuard ──▶ SessionCache ──▶ LingmaPool.pick()
+                                                │
+                                                ▼
+                                            (hit?) ─── yes ───▶ 复用 sessionId + 只发最后一条 user 消息
+                                                │  no
+                                                ▼
+                                            发全量历史 + 新 sessionId
+
+                                 挑到 PoolInstance
+                                     │
+                                     ▼
+                             LingmaGatewayClient.chat_stream
+                                     │
+                                     ▼ notify("chat/ask", payload)     异步上行
+                             LspWsRpcClient (WebSocket)   ◀─── chat/answer / chat/finish ───┐
+                                     │                                                       │
+                                     ▼ LSP 帧                                                 │
+                             Lingma 子进程 (Popen)   ───────── KV cache / Qwen 推理 ──────────┘
+```
+
+### 关键不变量
+
+- **每个 Lingma 进程 ↔ 一个独立 workDir**。多实例时绝不共用 `workDir`，避免 `.info` 互相覆盖。
+- **一个 request → 精确一个 Lingma 实例**。中途不迁移（因为上游 session 跟实例绑定）。
+- **Ticket 流转**：`InFlightGuard.try_acquire()` 发一张 `InFlightTicket`，由路由代码或 stream 的 `finally` 负责 `release()`。release 幂等，多次调用无害。
+- **Session 绑定**：`SessionCache` 里每个 entry 记 `instance_name`。命中后路由粘性到同实例；若该实例不再健康，主动失效并重新分配。
+
+---
+
+## 3. 模块职责表
+
+| 文件 | 行数 | 职责 | 被谁调用 | 调用谁 |
+|---|---|---|---|---|
+| `main.py` | 777 | FastAPI 路由；request 级编排；生命周期 (`lifespan`) | 外部 HTTP | 所有 app/*.py |
+| `lingma_pool.py` | 333 | N 实例池；`pick()` 负载均衡 + 粘性路由；启动期 bundle 注入 | `main.py` | `lingma_client.py`, `auto_login.py`, `session_bundle.py` |
+| `lingma_client.py` | 758 | 单实例 Lingma 进程 + LSP-over-WS 通信；LSP 帧编解码；重连循环；子进程回收 | `lingma_pool.py` | `websockets` 库 + `subprocess` |
+| `session_cache.py` | 165 | LRU+TTL 缓存：会话前缀哈希 → 上游 `sessionId`；指标暴露 | `main.py` | — |
+| `session_bundle.py` | 175 | Lingma cache 目录 pack/unpack（`tar.gz` + base64）；路径穿越防护 | `main.py`, `lingma_pool.py` | 纯标准库 |
+| `concurrency.py` | 121 | `InFlightGuard`：基于 `asyncio.Semaphore` 的背压+排队+队列超时；ticket 幂等 release | `main.py` | — |
+| `auto_login.py` | 241 | Playwright 无头登录；重试 + 验证钩子 | `main.py`, `lingma_pool.py` | `playwright` |
+| `auth.py` | 147 | 三档鉴权：`require_bearer`（chat）/ `require_metrics_access` / `require_admin_access` | `main.py` | — |
+| `config.py` | 178 | env → `Settings` dataclass；`LINGMA_ACCOUNTS` 多格式解析；bundle 字段归一化 | `main.py` | — |
+| `model_map.py` | 84 | Lingma 模型 `key ↔ displayName` 双向映射；请求 `model` 解析（`id` 或 `name` 都认） | `main.py` | — |
+| `openai_schema.py` | 91 | OpenAI 请求/响应 Pydantic；多模态内容 `flatten_content` 降级 | `main.py`, `session_cache.py` | — |
+| `stats.py` | 85 | 请求次数 / token 估算 / Prometheus 文本 | `main.py` | — |
+| `logging_config.py` | 56 | 结构化 JSON logger；`request_id` 通过 `ContextVar` 注入每行 | 所有模块 | — |
+| `bootstrap_lingma.py` | 199 | 启动时从 Marketplace / VSIX 提取 Lingma 二进制到 `data/bin/` | 容器启动脚本 | — |
+
+---
+
+## 4. 核心流程
+
+### 4.1 启动
+
+```
+Docker ENTRYPOINT
+  │
+  ▼
+bootstrap_lingma.py (按需下载 VSIX → 提取 Lingma 二进制)
+  │
+  ▼
+uvicorn app.main:app
+  │
+  ▼
+FastAPI lifespan.__enter__
+  │
+  ├─ load_settings()                     # env → Settings
+  ├─ LingmaPool.build(...)               # N 个 PoolInstance + InstanceConfig
+  │     └─ 为每个账号创建 LingmaGatewayClient + AutoLoginManager
+  ├─ _log_auth_posture()                 # 警告裸奔的鉴权配置
+  └─ await pool.start()                  # 并行启动 N 个实例
+        └─ 每个实例：
+              1. _maybe_apply_session_bundle(inst)
+                 └─ 如果 workDir 没登录态 且 有 bundle 配置 → 解包到 workDir
+              2. client.start() (非阻塞 failure)
+                    └─ _connect(initial=True)
+                          ├─ 读 .info（如果已有预热端口就跳过 spawn）
+                          ├─ Popen(Lingma, stderr=PIPE)
+                          ├─ 启动 _drain_stderr 后台任务
+                          ├─ 轮询等 .info 文件写出 → 读取端口
+                          ├─ websockets.connect(ws://127.0.0.1:port)
+                          ├─ LSP initialize + initialized notify
+                          └─ state → ready
+```
+
+**关键点：**
+- `pool.start()` 内部用 `asyncio.gather` 并发起每个实例，N=2 时启动时间约等于 max(单实例启动) 而非求和。
+- 任何一个实例启动失败**不会**让 `lifespan` 崩溃；对应 client 进入 `failed` 状态，`ensure_ready()` 在第一个请求到来时重试 `_connect`。
+- bundle 注入是幂等的：workDir 已登录就跳过；注入失败打 warning 然后 fallback 到 Playwright。
+
+### 4.2 非流式 chat 请求
+
+```
+POST /v1/chat/completions  stream=false
+  │
+  ▼
+auth_guard(API_KEYS)
+  │
+  ▼
+[构建 messages_dump + api_key 提取]
+  │
+  ▼
+reuse_eligible = session_reuse_enabled AND ask_mode=="chat" AND len(messages) >= 2
+  │
+  ▼
+if reuse_eligible:
+    lookup_key  = session_cache.build_key(api_key, messages[:-1])
+    write_key   = session_cache.build_key(api_key, messages)
+    entry       = await session_cache.get(lookup_key)
+    if entry:
+        cached_session_id    = entry.session_id
+        cached_instance_name = entry.instance_name
+  │
+  ▼
+inst = pool.pick(affinity_key = cached_instance_name or _affinity_key_for(req))
+  │                                                        # user > system-hash > first-msg-hash
+  ▼
+if cached_instance_name AND inst.name != cached_instance_name:
+    # 路由迁移：原实例不再 healthy；丢弃 cached session（另一个进程不认这个 sessionId）
+    cached_session_id = None
+    await session_cache.invalidate(lookup_key)
+  │
+  ▼
+await _ensure_instance_logged_in(inst)
+  │
+  ▼
+models   = await inst.client.query_models()
+model    = resolve_model(req.model, available_keys, default, name_map)
+prompt   = _last_user_text(messages) if cached_session_id else _messages_to_prompt(messages)
+is_reply = bool(cached_session_id)
+  │
+  ▼
+ticket = await chat_guard.try_acquire()            # 超时 → 429 + Retry-After
+inst.in_flight += 1
+  │
+  ▼
+try:
+    result = await inst.client.chat_complete(
+        prompt, model, ask_mode,
+        session_id=cached_session_id,
+        is_reply=is_reply,
+    )
+except:
+    stats_collector.record(success=False)
+    if cached_session_id: await session_cache.invalidate(lookup_key)  # 坏 session 不留
+    raise 502
+  │
+  ▼
+stats_collector.record(success=True)
+if write_key: await session_cache.put(write_key, result["sessionId"], inst.name)
+  │
+  ▼
+return ChatCompletionResponse(... served_by=inst.name, usage=..., latency=...)
+  │
+finally:
+    inst.in_flight -= 1
+    ticket.release()                                # 幂等
+```
+
+**路径为什么是这样：**
+
+- `reuse_eligible` 条件里 `len(messages) >= 2` 的原因：首轮对话 `messages[:-1]` 是空，没有"上下文前缀"可缓存。
+- `lookup_key` = 不含最后一条 user 消息的前缀；`write_key` = 完整 messages。下一轮请求时，它的 `messages[:-1]` **就是**这一轮的完整 `messages`，天然命中。
+- 失败路径主动 `invalidate`：避免把坏 session 一直喂给后续请求（dead-session 死循环）。
+
+### 4.3 流式 chat + session cache 命中
+
+```
+POST /v1/chat/completions  stream=true
+  │
+  ▼
+[前半段路由 + session lookup + 选实例 + 构造 prompt 跟 4.2 一致]
+  │
+  ▼
+ticket = await chat_guard.try_acquire()
+inst.in_flight += 1
+completion_id         = f"chatcmpl-{uuid}"
+stream_meta           = {}            # chat_stream 会把 sessionId 写回来
+completion_tokens_holder = {"n": 0}
+  │
+  ▼
+ticket_transferred = True             # 所有权移交给 event_stream 的 finally
+return StreamingResponse(event_stream(), media_type="text/event-stream")
+  │
+  ▼  (后台消费)
+async def event_stream():
+    success = False
+    try:
+        async for chunk in inst.client.chat_stream(
+            prompt, model, ask_mode,
+            session_id=cached_session_id,
+            is_reply=is_reply,
+            out_meta=stream_meta,
+        ):
+            completion_tokens_holder["n"] += estimate_tokens(chunk)
+            yield f"data: {chunk SSE payload}\n\n"
+        yield "data: [DONE]\n\n"
+        success = True
+    except asyncio.CancelledError:     # 客户端断开
+        raise
+    except:
+        logger.warn
+    finally:
+        # 只有 clean finish 才写回 cache（半截流不能复用 session）
+        if success and write_key:
+            sid = stream_meta.get("session_id")
+            if sid: await session_cache.put(write_key, sid, inst.name)
+        await stats_collector.record_chat(...)
+        inst.in_flight -= 1
+        ticket.release()
+```
+
+**两个细节：**
+
+1. `ticket_transferred=True` 一旦设成 true，外层 `finally` 就不会 release ticket；责任转交给 `event_stream()` 的 finally。否则会 release 两次（虽然幂等，但会把 in_flight 计成 -1）。
+2. `chat_stream` 走的是 JSON-RPC **notify** 而非 request。早期版本用 request 会等 30s 才下第一个字节（见决策 5.1）。
+
+### 4.4 Lingma 子进程与 LSP 通信
+
+```
+LingmaGatewayClient._connect(initial: bool)
+  │
+  ▼
+state -> starting
+  │
+  ▼
+port_prewarmed = (socket_port > 0) AND _is_port_open(...)
+  │
+  ├─ yes: 直接复用（单实例容器重启场景）
+  ▼  no:
+  clean up 老的 .info
+  await _terminate_proc()           # 先杀掉上次残留的 Popen
+  self._proc = subprocess.Popen(
+      [bin, "start", "--workDir", workdir],
+      stderr=PIPE,
+  )
+  asyncio.create_task(_drain_stderr(self._proc))    # 子线程 readline → logger.debug
+  port, pid, info_path = _wait_info_any([...], timeout)
+  self.socket_port = port
+  │
+  ▼
+await port open            # 二次确认 TCP listener 起来
+  │
+  ▼
+self._ws  = await websockets.connect(f"ws://127.0.0.1:{port}", max_size=10MB)
+self._rpc = LspWsRpcClient(self._ws, on_disconnect=self._on_disconnect)
+await self._rpc.start()     # 启动 _reader_loop
+  │
+  ▼
+await self._rpc.request("initialize", {processId, clientInfo, rootUri=None}, timeout=rpc_timeout)
+await self._rpc.notify("initialized", {})
+state -> ready
+```
+
+**LSP 帧结构（WebSocket 载荷）：**
+
+```
+Content-Length: <N>\r\n
+\r\n
+{"jsonrpc":"2.0", "id":1, "method":"...", "params":{...}}   (N 字节 JSON)
+```
+
+一个 WS 消息可能粘多个帧，`_parse_lsp_frames` 用一个累加的 `_rx_buffer` 实现状态机。
+
+**request vs notify：**
+
+- `request(method, params, timeout)`：分配自增 `id`，放 `_pending[id] = future`，收到同 id 响应时 `fut.set_result(msg)`。超时则 `pop` 并抛 `TimeoutError`。
+- `notify(method, params)`：不带 `id`，发出去就忘。`chat/ask` 必须用 notify，见 5.1。
+
+**`chat/answer` 与 `chat/finish` 处理：**
+
+- server → client 的消息通过 `_handle_server_message` 分发。
+- `chat/answer` 里的 `text` 被塞进 `_chat_streams[requestId]["chunks"]` 队列；第一个 chunk 来的时候标 `first_chunk_at` 做 TTFB 统计。
+- `chat/finish` 触发 `done.set() + chunks.put_nowait(None)`，`consume_stream` 看到 `None` 就 break。
+- 这两个消息都会带 `params.sessionId`（Lingma 自己分配的真实 session，可能跟 client 传的 hint 不一样），`chat_stream` 的 `finally` 里用 `get_stream_result()` 取到并写进 `out_meta`。
+
+**重连：**
+
+`_reader_loop` 捕获到 WS 断开（异常或 close）调 `on_disconnect(exc)`，启动 `_reconnect_loop`：backoff 从 1s 指数增长到 30s，最多 20 次。成功重连后不自动重放 in-flight 请求（状态丢失），但后续新请求会正常工作。
+
+**子进程生命周期：**
+
+```
+close()
+  ├─ _reconnect_task.cancel()
+  ├─ _rpc.close()                     # 拒绝所有 pending futures, 结束 reader loop
+  ├─ _ws.close()
+  └─ _terminate_proc()
+         └─ proc.terminate() → asyncio.to_thread(proc.wait, 5s)
+              └─ TimeoutError → proc.kill() → wait(3s)
+              └─ finally: proc.stderr.close()
+```
+
+_之前版本用 `start_new_session=True`，Lingma 会变孤儿进程；容器 stop 后宿主机上还残留着。现在保留 session 归属 + 显式 terminate，退出干净。_
+
+### 4.5 Session bundle 导入/导出
+
+**导出（`POST /internal/session/export`）：**
+
+```
+admin_auth_guard ──▶ 选实例 ──▶ auth_status() 必须 logged_in=true
+  │
+  ▼
+pack_workdir(target.work_dir):
+    读 cache/{id,user,quota,config.json} → tar.gz BytesIO → bytes
+    size cap: 4 MiB
+    raise if cache/user empty（防止导出空包）
+  │
+  ▼
+encode_bundle(raw) → base64 字符串
+  │
+  ▼
+return {instance, account, raw_bytes, bundle_b64}
+```
+
+**注入（`LingmaPool._maybe_apply_session_bundle`）：**
+
+```
+if is_logged_in_workdir(workdir):       # cache/user 存在且非空
+    return              # 绝不覆盖活跃登录态
+  │
+  ▼
+b64 = resolve_bundle_b64(inline, file_path)    # inline 优先
+if not b64: return
+  │
+  ▼
+raw = decode_bundle(b64)    # base64 + size cap
+  │
+  ▼
+apply_bundle_to_workdir(workdir, raw):
+    for member in tar:
+        _is_safe_member(member)?   # 白名单 4 个文件 + 非目录 + 非 symlink + 无路径穿越
+        写入 workdir/cache/X
+        chmod 0600 for "user", 0644 others
+    return [restored file names]
+  │
+  ▼
+logger.info("pool X: applied session bundle (4 files: ...)")
+```
+
+**安全考量：**
+
+- 白名单：只接受 `cache/{id,user,quota,config.json}` 4 个文件名，任何其他成员被静默跳过并 warn。
+- 路径穿越：`../`、绝对路径、symlink、hardlink、非 regular file 全部拒绝。
+- 大小上限：encode 前 / decode 后都限 4 MiB（实际 payload 通常 < 10 KB）。
+- bundle 不出现在任何 log（`logger.info` 只打文件数和字节数，不打内容）。
+
+### 4.6 自动登录 (Playwright)
+
+仅在**没有** bundle 且 workDir 未登录时触发。
+
+```
+_ensure_instance_logged_in(inst)
+  │
+  ▼
+status = await client.auth_status()
+if status.id: return status     # 已登录
+  │
+  ▼
+if not auto_login_enabled: raise 401
+  │
+  ▼
+(可选) 切 dedicated_domain_url
+  │
+  ▼
+login_url = await client.generate_login_url()
+  │
+  ▼
+await auto_login.ensure_started(login_url)      # 启 Playwright 后台任务（幂等）
+await auto_login.wait_done(timeout)
+  │
+  ▼
+status = await client.auth_status()
+if not status.id: raise 401
+return status
+```
+
+`AutoLoginManager._run()` 的细节在 `app/auto_login.py`。关键点：Playwright 配了 `headless=True` + `verify_logged_in` 钩子做二次确认（避免误报登录成功）。
+
+### 4.7 关闭
+
+FastAPI `lifespan` 退出 → `pool.close()` → 每个 `client.close()` → 进程回收链。整个路径在 [4.4](#44-lingma-子进程与-lsp-通信) 末尾。
+
+---
+
+## 5. 关键设计决策
+
+每条都写出**问题 / 方案 / 权衡 / 为何没选其他**，方便二开时评估能不能推翻。
+
+### 5.1 chat/ask 走 JSON-RPC notify 而非 request
+
+- **问题**：早期版本用 `rpc.request("chat/ask", ...)` 在 `await` 响应，但 Lingma 压根不回 response，只用 `chat/answer` + `chat/finish` 异步推流。导致首字节延迟 = `rpc_timeout` (30s)。
+- **方案**：改用 `notify()`，发出去不等 response；响应完全靠 `_reader_loop` 里的 `_handle_server_message` 分发到 `_chat_streams[requestId]` 的队列。
+- **权衡**：放弃"RPC 层超时"的简单性，换到"stream-level 超时"（`consume_stream` 的 idle timeout）。值得。
+- **其他方案**：伪造 request 响应？不行，Lingma 侧没有可预期的 id 回执。
+
+### 5.2 多实例池独立 workDir，而不是共享
+
+- **问题**：最初考虑多实例共享 `~/.lingma/.info`，让一个 Lingma 服务多个 client。但 Lingma 的 `.info` 文件每次启动覆写，N 个进程会互相踩端口。
+- **方案**：每个 PoolInstance 一个独立 `data/.lingma/pool/inst-<i>/`，各自的 `.info` 只看自己的目录。
+- **权衡**：多账号登录态没法共享，bundle 机制弥补（可以导出一份用在所有实例）。磁盘占用多出 N 份，单实例约 50 MB，实际不是问题。
+- **其他方案**：改 Lingma 命令行让它支持独立 info path？Lingma 是闭源二进制，不可行。
+
+### 5.3 session cache 只哈希 user/system/developer 消息
+
+- **问题**：OpenAI 客户端常常会规范化 / 裁剪 assistant 消息（例如 trim 末尾空白、去掉思考内容），导致下一轮的 `messages[:-1]` 跟上一轮的 `messages` 不完全字节相等。
+- **方案**：`hash_user_context` 只对 `system / user / developer` 三种 role 做 SHA1；assistant/tool 不参与。只要**用户输入路径**稳定，哈希就稳定。
+- **权衡**：理论上客户端篡改 assistant 语义（比如把模型的回答改成相反的）时，cache 依然命中，但 Lingma 侧自己持有 session 原版历史，下一轮还是按原版继续。对用户意图的偏离不可见。这是 OK 的——客户端本来就不该篡改 assistant 内容。
+
+### 5.4 session cache 写入用 `write_key = hash(messages)`，查询用 `lookup_key = hash(messages[:-1])`
+
+- **问题**：cache 要能被下一轮命中。
+- **推导**：当前轮完成后写入的 key 是 "当前完整 messages"；下一轮请求到来时它的 "前缀"（`messages[:-1]`，去掉当前这轮新的 user 消息）**正是**上一轮的完整 `messages`。所以下一轮 lookup 必中。
+- **权衡**：只能命中严格 append-only 的对话模式。客户端如果重写历史就会 miss，这是预期行为。
+
+### 5.5 session 失败路径主动 `invalidate`
+
+- **问题**：如果 Lingma 侧主动回收了某个 session，我们这边还在命中 cache 反复用死 session，会造成死循环 502。
+- **方案**：chat_complete/stream 抛异常 或 stream 未 clean finish 时，**不写回**当前 session；如果是用了 cached_session_id 失败的，直接 `invalidate(lookup_key)`，让下一轮重新开 session。
+- **权衡**：偶尔会浪费一轮 KV cache 重建。实测下来单次延迟增加 < 300ms，可接受。
+
+### 5.6 Session bundle 只打 4 个文件
+
+- **问题**：Lingma workDir 里文件很多：`cache/`, `db/`, `logs/`, `index/`, `.lock`, `.info`, `diagnosis.bin`...
+- **方案**：实验发现只有 `cache/{id,user,quota,config.json}` 是恢复登录必要的。其他都是 Lingma 启动时按需重建的。
+- **权衡**：
+  - bundle 小（< 10KB），传输友好
+  - 如果 Lingma 新版本引入新的必需文件，bundle 会 silently 坏掉——加了兼容层（注入失败 fallback 到 Playwright），而不是直接崩。
+  - `_is_safe_member` 白名单强制，新版本多写了文件也不会被偷渡进来。
+
+### 5.7 auth 三档：chat / admin / metrics
+
+- **问题**：单一 API_KEY 权限太粗。调用方只需要 chat 能力，不该有 session 导出权。
+- **方案**：三把独立 token：
+  - `API_KEYS`（多把）：只能 chat 和看 models
+  - `ADMIN_TOKEN`（一把）：`/internal/*` 管理面
+  - `METRICS_TOKEN`（一把）：`/metrics` 观测面
+- **权衡（兼容性）**：三把 token 全配置是理想状态，但单租户用户嫌麻烦，所以保留 fallback：admin/metrics 未配置时退化到 API_KEYS。启动时 `_log_auth_posture()` 对"全空"和"admin 回落"发 WARN，提示用户显式配。
+
+### 5.8 /metrics 默认严格（v0.3 破坏性改动）
+
+- **问题**：最初 `/metrics` 在无 token 配置时是公开的。这在单节点加反代时没问题，但容器直接暴露公网就泄露 pool 拓扑（账号名、账号数、实例健康度）。
+- **方案**：默认拒绝，要么配 token 要么显式 `METRICS_PUBLIC=true` 才放开。
+- **权衡**：破坏兼容；但通过启动 WARN + README 升级段，升级路径明确。
+
+### 5.9 子进程 stderr 走 PIPE + 独立线程读
+
+- **问题**：`DEVNULL` 下 Lingma native 崩溃的原因完全黑箱，只能靠堆 `strace`。
+- **方案**：`subprocess.Popen(stderr=PIPE)` + `asyncio.to_thread(readline loop)`，逐行 log 到 `DEBUG`。
+- **权衡**：`DEBUG` 日志稍增，但不开 debug 不影响。一定要是 `to_thread` 包装，因为 `readline()` 阻塞，直接用 `asyncio.subprocess` 需要整个 `_connect` 改写，改动太大。
+
+### 5.10 least-in-flight + affinity 的调度顺序
+
+- **问题**：粘性 affinity 和负载均衡哪个优先？
+- **方案**：affinity 的 bucket 优先，但要求目标实例 healthy；unhealthy 时退到 least-in-flight；全不健康时 round-robin 兜底（让 `ensure_ready()` 驱动重连）。
+- **权衡**：粘性优先让 session cache 命中率最大化；只有实例挂了才强制迁移，这时也必然会 miss cache（session 跟着进程死）。
+
+### 5.11 子进程 handle 保存到 `LingmaGatewayClient` 而非 pool
+
+- **问题**：pool 知道实例，但不知道单进程生命周期；放哪边？
+- **方案**：`client._proc` + `client._terminate_proc()`。pool 只负责 `client.start()` / `client.close()` 的调度，进程操作封装在 client 内部。
+- **权衡**：client 文件变长，但边界清晰——pool 只看状态和在途数，具体进程是 client 的事。
+
+---
+
+## 6. 扩展指引（要做 X 改哪里）
+
+| 需求 | 改哪些文件 | 关键入口 |
+|---|---|---|
+| 加一个新的 OpenAI 端点（如 embeddings） | `main.py`, `openai_schema.py` | 仿照 `v1_models` 加 `@app.post("/v1/embeddings", dependencies=[Depends(auth_guard)])` |
+| 加一种新的实例调度策略（如加权轮询） | `lingma_pool.py::pick()` | 当前是 affinity → least-in-flight → round-robin |
+| 改认证为 JWT / OAuth | `auth.py` | 三个 `require_*` 函数是全部入口；`main.py` 里只有 `*_guard` 代理 |
+| 增加限流（按 api_key 配额） | `concurrency.py` 加 `PerKeyGuard`；`main.py` 在 `chat_guard.try_acquire()` 后再来一层 | 注意 ticket 释放顺序（内层先释放） |
+| 支持请求级别的 session_id 穿透 | `main.py`（读 req header） + `lingma_client.py::chat_stream(session_id=...)` 已支持 | 只需把 header 值塞进 `cached_session_id` 分支 |
+| 改 Prometheus 指标名 | 所有 `prometheus_lines()` 或 `prometheus_text()` | 注意生态兼容；更名要在 README 留 alias |
+| 接入 Jaeger / OpenTelemetry | `logging_config.py` 加 OTel instrumentation；`main.py::request_id_middleware` 注入 traceid | request_id 可以复用为 span_id |
+| 加一个 Lingma 新方法调用（比如 code/complete） | `lingma_client.py` 仿照 `query_models`：`await self.ensure_ready(); return await self.rpc.request("code/complete", ...)` | 原始上游响应形态需抓包确认 |
+| 支持 function calling（假设 Lingma 将来支持） | `openai_schema.py` 已保留 `tools` / `tool_choice` 字段；`lingma_client.py::_build_payload` 加 `extra.tools` | 上游协议 TBD |
+| 多模态穿透 | `openai_schema.py::flatten_content` 不再降级；`lingma_client.py` payload 传 url | 前提：Lingma 支持（目前不支持） |
+| 换 session_cache 后端（如 Redis） | 实现同样接口的 `RedisSessionCache`，`main.py` 初始化换实现 | 接口是 `get / put / invalidate / stats / prometheus_lines / build_key / enabled`，内存换远端成本不高 |
+| 多容器副本（水平扩） | 外面套反代 + sticky session（根据 `Authorization` 或 `x-user` 做 hash）；session cache 改 Redis | 或直接接受多副本 cache 独立，轻微浪费 KV cache 命中率 |
+
+### 本地开发调试
+
+```bash
+pip install -r requirements.txt
+# 在容器外跑，需要自己准备 Lingma 二进制
+export LINGMA_BIN=/path/to/Lingma
+export API_KEYS=sk-dev
+uvicorn app.main:app --reload --port 8317
+```
+
+主要断点位置：
+- `main.py::v1_chat_completions` —— 请求编排
+- `lingma_client.py::_connect` —— 连接建立过程
+- `lingma_client.py::_handle_server_message` —— 上游推送
+- `session_cache.py::get` / `put` —— 会话复用决策
+
+---
+
+## 7. 已知问题 / 未完成项
+
+| 标签 | 描述 | 影响 | 计划 |
+|---|---|---|---|
+| D1 | `config.py` 还是纯 `dataclass` + `os.getenv`，未迁 `pydantic-settings` | 类型校验靠自己 cast | 低优，收益有限，有精力再做 |
+| D3 | 无单元测试骨架 | 重构要靠 deploy 验证 | 想加 CI 时优先补 |
+| Docker non-root | 容器还是 root 跑 | 容器逃逸时影响宿主 | 需要加 `gosu` + chown entrypoint，涉及数据迁移，谨慎推进 |
+| ADMIN_TOKEN 轮换 | 没有过期机制，只能重启 | 自用场景不影响 | 接 Vault / sops 时一并做 |
+| Lingma 版本漂移 | 新版 Lingma 改 LSP 方法或新增必需 cache 文件时会无声崩 | 注入失败会 fallback，但 chat 不回话题型的错误不易定位 | 加一个 `/internal/smoke` 端点做端到端自检 |
+| `estimate_tokens` 粗略 | 按字节 / 4 估算，中文误差大 | 只影响 usage 字段和 Prometheus token 计数 | 接 `tiktoken` 即可，但包体积会涨 |
+| Lingma agent 模式未深入验证 | `model: "agent"` 切 ask_mode，但 session reuse 被禁用 | agent 多轮不享受 KV 复用 | agent 语义跟 chat 不同（会触发 tool use），需要单独设计 |
+
+---
+
+## 8. 迭代历程
+
+一条时间线，方便理解每层功能的动机。
+
+### M1 — 基础生产可用 (`A2` + `D2`)
+
+- 背压：`InFlightGuard` + `429 Retry-After` + 排队超时
+- 结构化 JSON 日志 + `request_id` 贯穿
+- `auth.py` 抽离；`require_metrics_access` 独立通道
+- Prometheus 文本格式 + `/internal/stats`
+- 目的：单点网关能稳定跑，能被 Prometheus 抓，能看到 request 级链路。
+
+### M2 — 多账号池 + Session bundle (`A1` + `B3` + `C1`)
+
+- `LingmaPool`：N 个独立 Lingma 子进程，每个独立 `workDir`
+- 路由：粘性 affinity + least-in-flight + 不健康兜底 round-robin
+- Pool-level `/healthz` / `/internal/stats` / Prometheus gauges
+- **Session bundle**：`session_bundle.py` 把 Lingma `cache/` 打 tar.gz，允许从一个已登录实例导出、在任意新实例上一键注入，彻底跳过 Playwright。
+- Bundle 机制包含：路径穿越防护、4 MiB 大小上限、文件权限规整、注入失败 fallback 到自动登录、不覆盖活跃登录态。
+- 服务器上落盘 `secrets/lingma-session.b64` 加 docker-compose `:ro` 挂载。
+
+### M3 — 性能优化
+
+**问题**：用户反馈对话首 token 慢，甚至比原 VSCode 插件明显慢（2-3s vs < 500ms）。
+
+**根因 1（P0）**：`chat/ask` 用了 JSON-RPC `request`，等 `result` 超时 30s 才下第一个 `chat/answer`。实际上 Lingma 永远不会回 result。
+**修复**：`_kick_chat_ask()` 改用 `notify`。TTFB 从 `rpc_timeout` 下降到 ~2s（纯 Lingma 推理）。
+
+**根因 2（P1）**：多轮对话每次都拼接完整历史发给 Lingma，上游 KV cache 没被利用。
+**修复**：`SessionCache`（LRU + TTL）+ `chat_complete/stream` 增加 `session_id` + `is_reply` 参数；命中时只发最后一条 user 消息，服务端识别为增量输入，命中 Qwen 的 prefix caching。
+
+收益：单轮没有显著改变（推理仍然花最多时间），但第 2 轮起 TTFB 降 40%~60%，视 prompt 长度。
+
+### M4 — 生产硬化包（commit `2febc37`）
+
+用户代号"选项 A"。
+
+- **权限分层**：`ADMIN_TOKEN` / `METRICS_TOKEN` / `METRICS_PUBLIC` 独立；/metrics 和 /internal/* 默认严格（全空 → 503）；启动 WARN 裸奔配置。
+- **子进程生命周期**：不再 `start_new_session=True`；保存 `Popen` handle；`stderr=PIPE` 读到 DEBUG log；关闭走 SIGTERM → 5s → SIGKILL。杜绝孤儿 Lingma。
+- **并行池启动**：`pool.start()` 用 `asyncio.gather`。N=2 启动省 ~startup_timeout 秒。
+- **HEALTHCHECK**：Dockerfile 加 30s 间隔 `/healthz` 探针，仅当 `pool_ready>0` 算 healthy。
+
+---
+
+## 9. Lingma LSP 协议速查
+
+不是完整文档，只列本项目用到的方法。真实协议通过观察 Lingma 行为 + 抓包逆推。
+
+| 方向 | 方法 | 载荷（精简） | 返回 / 说明 |
+|---|---|---|---|
+| → | `initialize` | `{processId, clientInfo, rootUri:null, capabilities:{}, workspaceFolders:[]}` | LSP 标准握手 |
+| → | `initialized` (notify) | `{}` | LSP 标准 |
+| → | `auth/status` | `{}` | `{id, nickname, ...}` or `{}` |
+| → | `config/queryModels` | `{}` | `{chat:[{key,displayName,...}], assistant:[...], developer:[...], inline:[...]}` |
+| → | `config/getEndpoint` | `{}` | `{endpoint}` |
+| → | `config/updateEndpoint` | `{endpoint}` | ok |
+| → | `login/generateUrl` | `{}` | `str` 或 `{loginUrl/url}` |
+| → | `chat/ask` (notify!) | 见 `_build_payload` | 不回 result；通过 server push 下推 |
+| ← | `chat/answer` | `{requestId, text, content}` | 流式 token |
+| ← | `chat/finish` | `{requestId, sessionId, ...其它元数据}` | 结束信号，含上游真实 sessionId |
+
+**`chat/ask` payload 关键字段**：
+
+```
+requestId              # 我们这边用 uuid4
+sessionId              # 我们分配或从 cache 复用；Lingma 可能在 chat/finish 里返回不同的
+sessionType            # "chat" 或 "developer"（agent 模式）
+mode                   # "chat" / "agent"
+stream                 # true
+source                 # 1
+isReply                # 会话复用命中时 true；让上游走 KV cache 路径
+content / text / message / questionText  # 都是 prompt，冗余填（Lingma 不同版本用不同字段）
+extra.modelConfig.key  # 模型 key
+pluginPayloadConfig    # {isEnableAskAgent, isEnableAutoMemory}
+chatContext            # {text, preferredLanguage: "zh-CN", ...}
+```
+
+**发现新方法的方法**：开 `LOG_LEVEL=DEBUG` 并打开 `_reader_loop` 里的 `msg` 打印；用真实 VSCode 插件操作一次，就能观察到 Lingma 上行的完整方法列表。
+
+---
+
+_文档版本_：对应 `main` 分支 commit `2febc37` 之后。后续大改请同步更新本文件，尤其是决策记录和模块职责表。
diff --git a/README.md b/README.md
index 97217ea..e0fffe6 100644
--- a/README.md
+++ b/README.md
@@ -1,282 +1,353 @@
 # Lingma OpenAI Gateway
 
-把本地 Lingma 能力封装为 OpenAI 兼容接口，支持：
+把本地 Lingma 插件封装成 OpenAI 兼容接口。任何能调 OpenAI 的客户端（Cursor、Dify、LangChain、curl…）都能直接接入。
 
-- `GET /v1/models`
-- `POST /v1/chat/completions`
-- `stream=true`（SSE）
-- Bearer API Key 鉴权
+**支持：** `GET /v1/models` / `POST /v1/chat/completions`（含 SSE 流式） / Bearer 鉴权 / Prometheus / 多账号实例池 / 会话复用 / 免浏览器登录态注入。
 
-## 1. 准备目录
+> 想看架构、模块划分、设计决策、二开路线图 → 直接读 [`DESIGN.md`](./DESIGN.md)。
 
-```bash
-mkdir -p data
+---
+
+## 架构速览
+
+```
+ ┌─────────────┐   OpenAI 协议    ┌─────────────────────────────────────────┐
+ │  任意客户端  │  ───────────▶    │  FastAPI (app/main.py)                  │
+ │  (curl/     │                  │  ├─ auth_guard / admin_guard            │
+ │   Cursor/   │                  │  ├─ chat_guard (InFlightGuard 背压)     │
+ │   Dify…)    │                  │  ├─ SessionCache (LRU+TTL, KV 复用)     │
+ └─────────────┘                  │  └─ StatsCollector + Prometheus         │
+                                  └────────────────┬────────────────────────┘
+                                                   │ 选实例 (least-in-flight + affinity)
+                                  ┌────────────────▼────────────────────────┐
+                                  │  LingmaPool (app/lingma_pool.py)        │
+                                  │  ├─ inst-0  inst-1  inst-N …            │
+                                  │  └─ 启动前自动 restore session bundle   │
+                                  └────────────────┬────────────────────────┘
+                                                   │
+                           ┌───────────────────────┼───────────────────────┐
+                           ▼                       ▼                       ▼
+                ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐
+                │ LingmaGatewayClient│  │        …           │  │        …           │
+                │ (LSP over WS)      │  │                    │  │                    │
+                │ ├─ Popen (PID管理) │  │                    │  │                    │
+                │ ├─ reconnect loop  │  │                    │  │                    │
+                │ └─ ws://:PORT      │  │                    │  │                    │
+                └──────────┬─────────┘  └────────────────────┘  └────────────────────┘
+                           │ spawn + ws
+                ┌──────────▼─────────┐
+                │   Lingma 二进制     │
+                │   --workDir /…     │
+                └────────────────────┘
 ```
 
-说明：
+---
 
-- 启动时会自动获取最新插件并提取 `Lingma` 到 `data/bin`。
-- 默认通过 VSCode Marketplace 查询最新版本，再下载对应 VSIX。
-- 登录态与运行数据统一写入 `data/.lingma`。
-
-## 2. 配置环境变量
+## 一、快速开始
 
 ```bash
+git clone <repo>
+cd lingma-openai-gateway
 cp .env.example .env
+# 至少填 API_KEYS + LINGMA_USERNAME + LINGMA_PASSWORD（或 session bundle）
+mkdir -p data secrets
+docker compose up -d --build
+docker compose logs -f   # 看到 "Uvicorn running on..." 就 OK
 ```
 
-至少修改：
+冒烟测试：
 
-- `API_KEYS`
-- `LINGMA_USERNAME`
-- `LINGMA_PASSWORD`
+```bash
+API_KEY=$(grep '^API_KEYS=' .env | cut -d= -f2 | cut -d, -f1)
+curl -s http://127.0.0.1:8317/healthz
+curl -s http://127.0.0.1:8317/v1/models -H "Authorization: Bearer $API_KEY"
+curl -s http://127.0.0.1:8317/v1/chat/completions \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"org_auto","messages":[{"role":"user","content":"hi"}]}'
+```
 
-如果你的 Lingma 路径不同，修改：
+---
 
-- `LINGMA_BIN`
+## 二、配置参考
 
-可选（企业专属域）：
+`.env.example` 是权威说明，这里按主题分组。
 
-- `DEDICATED_DOMAIN_URL`
+### 2.1 核心
 
-### `.env` 字段说明（简版）
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `HOST` / `PORT` | `0.0.0.0` / `8317` | 网关监听地址与端口 |
+| `API_KEYS` | — | Bearer key，多个逗号分隔；**留空则 /v1/\* 无鉴权**，启动会 warn |
+| `LOG_LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR`，日志为结构化 JSON，含 `request_id` |
+| `DEFAULT_MODEL` | `org_auto` | 模型无法映射时兜底 |
+| `DEFAULT_ASK_MODE` | `chat` | `chat` 或 `agent`（传 `model: "agent"` 时自动切） |
+| `DEDICATED_DOMAIN_URL` | — | 企业专属域（可空） |
 
-- `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。具体见下方"跳过自动登录"章节
+### 2.2 权限分层（生产建议全配）
 
-### `.env` 最小必填示例
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `ADMIN_TOKEN` | — | `/internal/*` 专属 token；未配置时 fallback 到 `API_KEYS`（兼容）；都为空 → 503 |
+| `METRICS_TOKEN` | — | `/metrics` 专属 token；未配置时 fallback 到 `API_KEYS` |
+| `METRICS_PUBLIC` | `false` | 显式公开 `/metrics`（仅用于私网采集器） |
+
+> `ADMIN_TOKEN` / `METRICS_TOKEN` / `API_KEYS` 三者都为空时，`/metrics` 和 `/internal/*` 会返回 503（拒绝裸奔）。
+
+### 2.3 并发与背压
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `GATEWAY_MAX_IN_FLIGHT` | `4` | 并发上限；`<=0` 表示不限 |
+| `GATEWAY_QUEUE_TIMEOUT_SEC` | `30` | 排队超时；超时直接返回 `429 + Retry-After` |
+
+### 2.4 Lingma 进程
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `LINGMA_BIN` | `/app/data/bin/Lingma` | 容器内二进制路径 |
+| `LINGMA_SOURCE_TYPE` | `marketplace` | `marketplace` 或 `vsix` |
+| `LINGMA_MARKETPLACE_PUBLISHER` | `Alibaba-Cloud` | Marketplace 发布者 |
+| `LINGMA_MARKETPLACE_EXTENSION` | `tongyi-lingma` | Marketplace 扩展名 |
+| `LINGMA_VSIX_URL` | 官方地址 | 兜底 VSIX 下载地址 |
+| `LINGMA_BOOTSTRAP_ALWAYS` | `true` | 启动时总是尝试刷新二进制 |
+| `LINGMA_FORCE_REFRESH` | `false` | 强制忽略本地缓存重新下载 |
+| `LINGMA_WORK_DIR` | `/app/data/.lingma/vscode/sharedClientCache` | 登录态/缓存所在目录 |
+| `LINGMA_SOCKET_PORT` | `36510` | 单实例模式下的 Lingma WS 端口 |
+| `LINGMA_STARTUP_TIMEOUT` | `40` | 启动超时秒 |
+| `LINGMA_RPC_TIMEOUT` | `30` | 单次 RPC 超时秒 |
+
+### 2.5 多账号 / 多实例池
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `LINGMA_ACCOUNTS` | — | `u1:p1,u2:p2` 或 JSON 数组；配置后每个账号 = 一个独立 Lingma 子进程 |
+| `LINGMA_INSTANCE_COUNT` | 账号数 | 显式指定实例数；不足账号循环复用并打 warn |
+| `LINGMA_USERNAME` / `LINGMA_PASSWORD` | — | 单实例兼容模式（仅 `LINGMA_ACCOUNTS` 为空时生效） |
+
+### 2.6 会话复用（KV cache 优化）
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `SESSION_REUSE_ENABLED` | `true` | 多轮对话命中时只发增量 user 消息 + 复用上游 `sessionId` |
+| `SESSION_CACHE_MAX_ENTRIES` | `256` | LRU 容量 |
+| `SESSION_CACHE_TTL_SEC` | `1800` | TTL（秒），避免命中已回收的 session |
+
+### 2.7 登录态注入（跳过 Playwright）
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `LINGMA_SESSION_BUNDLE` | — | base64 格式的 bundle（inline，适合短字符串） |
+| `LINGMA_SESSION_BUNDLE_FILE` | — | bundle 文件路径（推荐，避免 env 过长） |
+
+### 2.8 自动登录
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `AUTO_LOGIN_ENABLED` | `true` | 未登录时自动启 Playwright |
+| `AUTO_LOGIN_HEADLESS` | `true` | 无头浏览器 |
+| `AUTO_LOGIN_TIMEOUT` | `180` | 登录超时秒 |
+| `AUTO_LOGIN_MAX_RETRY` | `2` | 登录失败重试次数 |
+
+---
+
+## 三、API 参考
+
+### 3.1 公共（`API_KEYS`）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/healthz` | 免鉴权；返回 `ok` / `pool_size` / `pool_ready` / 每实例状态 |
+| GET | `/v1/models` | OpenAI 兼容；`id` 是 Lingma 原 key，`name` 是可读名 |
+| POST | `/v1/chat/completions` | OpenAI 兼容；`stream=true` 走 SSE；`model: "agent"` 切 agent 模式 |
+
+**chat 请求示例（非流式）**
+
+```bash
+curl -s http://127.0.0.1:8317/v1/chat/completions \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{"model":"dashscope_qmodel","messages":[{"role":"user","content":"你好"}]}'
+```
+
+**chat 请求示例（流式 + usage）**
+
+```bash
+curl -N http://127.0.0.1:8317/v1/chat/completions \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{
+    "model":"dashscope_qmodel",
+    "stream":true,
+    "stream_options":{"include_usage":true},
+    "messages":[{"role":"user","content":"介绍一下你自己"}]
+  }'
+```
+
+### 3.2 观测（`METRICS_TOKEN` 或 `API_KEYS`）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/metrics` | Prometheus 文本；含池每实例 gauge、并发、session cache 命中率、token 计数 |
+
+### 3.3 管理（`ADMIN_TOKEN` 或 fallback 到 `API_KEYS`）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/internal/stats` | JSON：`stats` + `concurrency` + `pool` + `session_cache` |
+| GET | `/internal/auto-login/status` | 每实例登录态与 auto_login 状态 |
+| POST | `/internal/auto-login/start?instance=inst-0` | 主动触发某实例登录（可不传，由 pool.pick 选） |
+| POST | `/internal/session/export?instance=inst-0` | 把已登录实例的 cache 打包成 base64 bundle |
+| GET | `/internal/models/raw?instance=inst-0` | Lingma 原始 `config/queryModels` 响应（displayName / isReasoning / isVl 等） |
+
+---
+
+## 四、常用场景
+
+### 4.1 多账号池
 
 ```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=
+LINGMA_ACCOUNTS=user1:pass1,user2:pass2,user3:pass3
+# LINGMA_INSTANCE_COUNT=3   # 不写默认=账号数
 ```
 
-### 数据目录说明
+- 每个账号一个独立 Lingma 子进程 + 独立 `workDir`（`data/.lingma/pool/inst-<i>/`）。
+- 路由：同 `user` 字段或同 system prompt 的请求**粘性**分到同一实例；其他按**最小在途**分配。
+- 一个实例挂掉不影响整体，`/healthz.pool_ready` 下降，自动重连。
 
-- 本项目所有持久化数据都在 `./data`：
-  - `data/bin/Lingma`：自动提取的 Lingma 二进制
-  - `data/.lingma/...`：Lingma 登录态、缓存、日志（单实例模式）
-  - `data/.lingma/pool/inst-<i>/...`：多实例模式下每个实例独立的登录态/缓存
+### 4.2 跳过 Playwright（session bundle）
 
-### 多实例池（方案乙：多账号）
-
-启用方式：在 `.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 上执行）：
+**从已登录实例导出：**
 
 ```bash
 curl -sS -X POST \
-  -H "Authorization: Bearer $API_KEY" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
   "http://host:port/internal/session/export" \
-  | jq -r '.bundle_b64' > lingma-session.b64
+  | jq -r '.bundle_b64' > secrets/lingma-session.b64
+chmod 600 secrets/lingma-session.b64
 ```
 
-可选 `?instance=inst-0` 指定从哪个实例导出（多实例场景）。
-
-**注入**（新部署的 `.env` 三选一）：
+**在新部署注入（选一种）：**
 
 ```env
-# 方式 1：直接塞 base64
-LINGMA_SESSION_BUNDLE=H4sIAAAA...
-
-# 方式 2：从文件读（推荐，避免 env 过长）
+# 文件注入（推荐）—— 需要在 docker-compose.yml 挂载 secrets 目录
 LINGMA_SESSION_BUNDLE_FILE=/secrets/lingma-session.b64
 
-# 方式 3：多账号模式，每个账号独立 bundle（JSON 模式）
+# 或 inline（适合小 bundle）
+LINGMA_SESSION_BUNDLE=H4sIAAAA...
+
+# 多账号 JSON 模式，每账号独立 bundle
 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，**按密钥保管**，不要写入公共仓库。
+- 只在目标 `workDir` 空（`cache/user` 不存在或 empty）时才注入；不会覆盖活跃登录态。
+- 注入失败（损坏/权限）自动 fallback 到 Playwright。
+- bundle 只含 `cache/{id,user,quota,config.json}` 4 个文件；大小上限 4 MiB，实际通常 < 10 KB。
+- **bundle 等同于密钥**，落盘需 `chmod 600`，不要进 git。
 
-## 3. Docker 运行
+### 4.3 Prometheus 接入
 
-```bash
-docker compose up -d --build
+```yaml
+# prometheus scrape_configs 片段
+- job_name: lingma-gateway
+  bearer_token: <METRICS_TOKEN>
+  static_configs: [{targets: ['host:8317']}]
+  metrics_path: /metrics
 ```
 
-说明：
+关键指标：
 
-- 构建阶段已默认使用腾讯云 PyPI 镜像（`mirrors.cloud.tencent.com`）。
-- 如需自定义镜像源，可在 `docker-compose.yml` 的 `build.args` 中修改。
+| 指标 | 类型 | 意义 |
+|---|---|---|
+| `gateway_in_flight` / `gateway_queued` | gauge | 并发 / 排队 |
+| `gateway_rejected_total` | counter | 背压拒绝（429）累计 |
+| `gateway_pool_instance_ready{name}` | gauge | 每实例是否就绪（0/1） |
+| `gateway_pool_instance_in_flight{name}` | gauge | 每实例在途 |
+| `gateway_session_cache_hit_total` / `_miss_total` | counter | 会话复用命中率原料 |
+| `gateway_chat_requests_success` / `_error` | counter | chat 成功率 |
 
-查看日志：
+---
 
-```bash
-docker compose logs -f
+## 五、升级注意事项
+
+从旧版本升级时注意**破坏性变更**（每一项都有 fallback，默认不会炸，但建议显式配置）：
+
+| 版本 | 变更 | 应对 |
+|---|---|---|
+| v0.3 | `/metrics` 裸奔时（无 token / 无 key）由公开改为 503 | 显式配 `METRICS_PUBLIC=true` 或 `METRICS_TOKEN` |
+| v0.3 | `/internal/*` 引入 `ADMIN_TOKEN` | 未配置自动 fallback 到 `API_KEYS`，生产建议单独配 |
+| v0.2 | 默认会话复用（多轮对话只发增量） | 如果你的客户端裁剪了历史导致语义不连续，设 `SESSION_REUSE_ENABLED=false` |
+| v0.2 | Chat 请求走 JSON-RPC `notify` 而非 `request`（修复 30s TTFB bug） | 无需行动 |
+| v0.2 | 多实例池（`LINGMA_ACCOUNTS` 存在时启用） | 不配则保持单实例行为 |
+
+---
+
+## 六、故障排查（FAQ）
+
+| 症状 | 排查方向 |
+|---|---|
+| `/healthz` 返回 `ok=false` / `pool_ready=0` | 查 `docker logs`，关键字 `lingma spawned` / `state ... -> ready`；若卡在 `starting` → Lingma 二进制或 workDir 权限问题 |
+| 返回 `401` 且带 `Invalid admin token` | 你用了 `API_KEYS` 去打 `/internal/*`，但服务端已设了 `ADMIN_TOKEN`；用 `ADMIN_TOKEN` 或清空 `ADMIN_TOKEN` |
+| 返回 `503 metrics scraping disabled` | 三个 env 全空，按 "权限分层" 章节配任一 |
+| 返回 `429 Too many in-flight` | 并发超过 `GATEWAY_MAX_IN_FLIGHT`；增大或客户端加重试 |
+| 首 token 延迟 2-3 秒 | Lingma 侧常态；多轮对话第二轮起，会话复用命中后 TTFB 明显降低（看 `gateway_session_cache_hit_total`） |
+| Playwright 登录失败 | 导出一个已登录 bundle 注入（见 4.2），彻底跳过浏览器 |
+| 容器重启后 Lingma 要重新登录 | `data/` 没挂在卷上或被清过；确认 `./data:/app/data` 挂载 + bundle fallback |
+| 升级后 `/metrics` 返回 503 | v0.3 默认严格；按表格 5.1 配置 |
+
+开 `LOG_LEVEL=DEBUG` 可以看到 Lingma 子进程的 stderr 输出，便于定位 native 崩溃。
+
+---
+
+## 七、开发与二开
+
+项目本身是单仓 FastAPI，3400 行 Python。推荐阅读路径：
+
+1. **先读 [`DESIGN.md`](./DESIGN.md)** —— 架构、模块职责、关键设计决策、二开指引。
+2. 再按需读对应模块：
+   - 想改请求入口 / 路由 → `app/main.py`
+   - 想加实例调度策略 → `app/lingma_pool.py::pick()`
+   - 想改 Lingma 通信协议 → `app/lingma_client.py`
+   - 想扩展会话复用 → `app/session_cache.py` + `main.py` 的 reuse 块
+   - 想做认证改造 → `app/auth.py` + `main.py::*_guard`
+3. 本地跑：`pip install -r requirements.txt && uvicorn app.main:app --reload`。
+
+---
+
+## 八、目录结构
+
+```
+lingma-openai-gateway/
+├── app/                        # 主代码（见 DESIGN.md 模块一览）
+│   ├── main.py                 # FastAPI 入口 + 路由
+│   ├── lingma_pool.py          # N 实例池
+│   ├── lingma_client.py        # LSP over WS + 子进程管理
+│   ├── session_cache.py        # 多轮对话 sessionId 复用
+│   ├── session_bundle.py       # 登录态 export/import
+│   ├── concurrency.py          # InFlightGuard 背压
+│   ├── auto_login.py           # Playwright 登录
+│   ├── auth.py                 # Bearer / admin / metrics 三档鉴权
+│   ├── config.py               # 环境变量 → dataclass
+│   ├── model_map.py            # 模型 key ↔ displayName
+│   ├── openai_schema.py        # OpenAI 请求/响应 Pydantic
+│   ├── stats.py                # StatsCollector + Prometheus
+│   ├── logging_config.py       # 结构化 JSON log + request_id 上下文
+│   └── bootstrap_lingma.py     # 启动时下载/提取 Lingma 二进制
+├── data/                       # 持久化（Lingma 二进制 + workDir），不进 git
+├── secrets/                    # 注入的 bundle 等敏感文件，不进 git
+├── Dockerfile                  # Playwright base + HEALTHCHECK
+├── docker-compose.yml
+├── .env.example                # 配置权威文档
+├── requirements.txt
+├── README.md                   # 本文件
+└── DESIGN.md                   # 架构与二开手册
 ```
 
-## 4. 调用示例
+---
 
-### 模型列表
+## License
 
-```bash
-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`
-
-### 非流式聊天
-
-```bash
-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"}
-    ]
-  }'
-```
-
-### 流式聊天
-
-```bash
-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 文本格式）
-
-示例：
-
-```bash
-curl -s http://127.0.0.1:8317/internal/stats \
-  -H "Authorization: Bearer sk-xxx"
-```
-
-```bash
-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）。
-
-你可以主动触发：
-
-```bash
-curl -s -X POST http://127.0.0.1:8317/internal/auto-login/start \
-  -H "Authorization: Bearer sk-your-api-key"
-```
-
-查看状态：
-
-```bash
-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 模式。
-
-```bash
-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": "分析这个项目目录结构"}
-    ]
-  }'
-```
+内部使用，按需调整。