# 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 应包含：变更目的、影响范围、测试命令与结果；如果修改接口行为，补充示例请求或响应片段。

## 文档与协作规则

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