lmstudiofixed/AGENTS.md

Repository Guidelines

项目结构与模块组织

本仓库围绕 LM Studio reasoning/toggle 问题组织为三块：

• tools/lmstudio/：一次性工具、wrapper 生成器、协议探针。
• services/litellm-lmstudio-adapter/：长期运行的 FastAPI 适配服务。
• tests/：顶层工具测试；服务自身测试位于 services/litellm-lmstudio-adapter/tests/。
• docs/：规格、分析与交接文档。
• artifacts/：实验输出、日志与探针结果，不放业务源码。

新增代码时，优先延续现有分层，不要把服务逻辑混入 tools/。

构建、测试与开发命令

• python -m unittest tests.test_lmstudio_wrapper_generator
  • 运行 wrapper 生成器测试。
• python -m unittest tests.test_openai_reasoning_proxy
  • 运行早期 reasoning 代理测试。
• python -m unittest discover -s services/litellm-lmstudio-adapter/tests -p "test_*.py"
  • 运行适配服务测试。
• python services/litellm-lmstudio-adapter/litellm_lmstudio_adapter.py
  • 本地直接启动适配服务，适合快速验证。

提交前至少运行受影响模块对应的测试；修改服务时，优先补跑完整服务测试集。

编码风格与命名约定

仓库以 Python 为主，使用 4 空格缩进，遵循标准库优先和清晰胜过技巧的原则。文件、函数、变量使用 snake_case；测试文件命名为 test_*.py。目录名沿用现状，例如 litellm-lmstudio-adapter，避免无必要重命名。仅在复杂协议转换处添加简短注释。

测试规范

测试框架为 unittest。新增功能或修复缺陷时，应同时补充回归测试。顶层工具测试放在 tests/，服务内部行为测试放在 services/litellm-lmstudio-adapter/tests/。优先覆盖请求转换、流式 SSE 处理、以及 LM Studio 原生透传路径。

提交与合并请求规范

当前历史很短，现有提交风格为简短前缀式摘要，例如 init: 初始化项目。后续建议保持 type: 简述 格式，如 fix: 修复 SSE block 解析。PR 应包含：变更目的、影响范围、测试命令与结果；如果修改接口行为，补充示例请求或响应片段。

文档与协作规则

本仓库新增文档、说明、注释性使用示例，以及协作回复默认使用中文；仅在外部接口字段、协议名、或第三方术语必须保留英文时例外。编写代理说明或交接文档时，也应优先使用中文，并引用具体路径与命令，避免空泛描述。