lmstudiofixed/docs/handoff/HANDOFF-2026-06-09.md

Handoff: 2026-06-09 17:18

Summary

本次工作目标是梳理并实现一套围绕 LM Studio reasoning/toggle 问题的统一方案，包括分析模型与接口行为、实现一个可供 LiteLLM 使用的 LM Studio 原生适配服务、以及对整个项目目录做结构化整理。当前状态是：核心适配服务已经实现并完成本地验证，工具脚本与测试已按职责分区整理完成，文档也已补齐中文说明；项目当前不是 git 仓库，因此没有可记录的 branch/commit 信息。

Current State

• Complete:
  • 完成对 LM Studio OpenAI 兼容层与原生层 reasoning 行为的实测与对比
  • 实现独立服务 services/litellm-lmstudio-adapter/
  • 支持 chat/completions 非流式与流式
  • 支持 responses 非流式与流式
  • 支持 LM Studio 原生 /api/v1/*、/api/v0/* 透传
  • 将 wrapper 生成器与 probe 脚本整理到 tools/lmstudio/
  • 新增中文流程文档与工具说明文档
  • 顶层 README 已更新为新的目录结构
  • 相关测试全部通过
• In Progress:
  • 无明确功能开发中的 WIP
  • 当前更多是“已完成，可继续增强”的状态
• Blocked:
  • 项目目录不是 git 仓库，无法提供 branch/commit/base branch 信息
  • OpenAI 官方文档页面受 Cloudflare 限制，无法直接用普通 HTTP 拉取页面内容做补充引用

Key Decisions

Decision	Rationale	Alternative
保留 OpenAI 兼容接口，对内调用 LM Studio /api/v1/chat	兼容上游调用方式，同时保住 LM Studio 原生 reasoning 控制能力	直接依赖 LM Studio /v1/chat/completions，但实测 reasoning 开关不可靠
用独立服务项目承接 LiteLLM -> LM Studio 适配	这是长期运行组件，不应该和一次性工具混在一起	把代理继续留在通用脚本目录中
将 wrapper 生成器与 probe 脚本移动到 tools/lmstudio/	这些脚本本质上是工具，不是服务	继续放在旧的 scripts/ 目录
chat/completions 流式桥接采用 SSE block 解析	LM Studio 原生返回 event: + data: 的完整 SSE block，逐行猜测会丢事件或出协议错误	继续按逐行 data: 解析，实测会出现 incomplete chunked read
messages 转 LM Studio 原生 input 时采用 transcript 压平方案	避免依赖 LM Studio 未完全公开稳定的 message schema，提升兼容性	直接把 OpenAI messages 原样塞到 input，实测会被原生接口拒绝

Files Touched

File	Purpose	Status
README.md	顶层结构说明与测试命令	modified
tools/lmstudio/wrapper_generator.py	生成 LM Studio wrapper 的工具脚本	moved
tools/lmstudio/openai_reasoning_proxy.py	早期实验型 reasoning 代理	moved
tools/lmstudio/README.md	中文工具总览与用途说明	created
tools/lmstudio/probes/lmstudio_thinking_probe.py	LM Studio 原生/兼容 reasoning 行为探针	moved
tools/lmstudio/probes/lmstudio_openai_reasoning_probe.py	OpenAI 兼容 reasoning 字段批量探针	moved
tools/lmstudio/probes/llama_cpp_openai_probe.py	llama.cpp OpenAI 兼容探针	moved
tests/test_lmstudio_wrapper_generator.py	wrapper 生成器测试，已适配新路径	modified
tests/test_openai_reasoning_proxy.py	早期代理测试，已适配新路径	modified
services/litellm-lmstudio-adapter/litellm_lmstudio_adapter.py	正式适配服务主程序	created / moved / modified
services/litellm-lmstudio-adapter/README.md	服务使用说明	modified
services/litellm-lmstudio-adapter/docs/2026-06-09-启动与请求处理流程.md	中文详细流程说明	created / moved
services/litellm-lmstudio-adapter/tests/test_adapter.py	适配服务测试	created / moved

Next Steps (Priority Order)

1. 为 services/litellm-lmstudio-adapter/ 增加启动脚本 — 推荐补一个 run.bat 或 start.bat，方便本机长期使用
2. 为 tools/lmstudio/wrapper_generator.py 补一个更直接的示例文档或 bat 启动脚本 — 降低后续使用门槛
3. 继续做真实接口覆盖验证 — 特别是 embeddings、completions、原生透传路径的端到端验证
4. 如后续真要接 LiteLLM — 补一个可直接使用的 proxy_config.yaml 示例
5. 视需要清理 artifacts/ 中的旧实验产物 — 当前没有删除任何历史结果

Open Questions

• 是否要给 services/litellm-lmstudio-adapter/ 再补一份“部署与排障”中文文档 — 目前只有原理流程文档
• 是否要把 tools/lmstudio/openai_reasoning_proxy.py 标记为 deprecated — 当前它仍有价值，但正式服务已由 services/litellm-lmstudio-adapter/ 取代
• 是否要继续扩适配服务的 stub 接口（audio/images/files/moderations） — 目前只返回 501

Known Pitfalls

• LM Studio 原生流式事件不是简单的 data: 单行流，而是标准 SSE block，必须按 block 解析；此前逐行处理会导致流式协议错误
• LM Studio /api/v1/chat 不能直接吃 OpenAI messages 结构作为 input，需要先做消息压平或使用其可接受的原生格式
• 顶层目录不是 git 仓库，任何需要 branch/commit 的自动化逻辑都要先判断并优雅降级
• services/litellm-lmstudio-adapter 目录名包含连字符，因此测试建议用 unittest discover，不要依赖不稳的模块路径导入

Verification Run

• python -m unittest tests.test_lmstudio_wrapper_generator
• python -m unittest tests.test_openai_reasoning_proxy
• python -m unittest discover -s services/litellm-lmstudio-adapter/tests -p "test_*.py"

以上三组测试最近一次均通过。

Branch Info

• Branch: N/A — 当前目录不是 git 仓库
• Latest Commit: N/A — 当前目录不是 git 仓库
• Base Branch: N/A — 当前目录不是 git 仓库