Imported from cjbbtohye/SSResearcher (
clients/AGENTS.md). Install upstream withnpx skills add cjbbtohye/SSResearcher --skill clients. Copyright stays with the author.
CLIENTS MODULE
OVERVIEW
clients/ 是 LLM provider 契约层：负责 provider 默认值、config.json 读取、API key 解析、OpenAI-compatible client 封装，以及工具调用返回结构。
WHERE TO LOOK
| Task | File | Notes |
|---|---|---|
| provider 默认值 / config 合并 | config.py |
DEFAULT_PROVIDERS、load_config_file()、get_all_providers() |
| API key 解析优先级 | config.py |
直接参数 > config.json > 环境变量 |
| provider 选择 / 名称枚举 | providers.py |
Provider、resolve_provider() |
| OpenAI-compatible client | openai_client.py |
chat / structured chat / tool call 适配 |
| 类型契约 | types.py |
ToolDef、ToolCall、AgentResponse |
| 本地配置模板 | config.json.template |
复制成 config.json 后填 API key |
CONVENTIONS
clients/config.json.template是配置模板；本地运行前复制为clients/config.json。config.py保持“JSON 配置 + DEFAULT_PROVIDERS fallback”模型；不要把 provider 默认值散落到 UI / Web / core 各处。get_api_key()的优先级固定为：显式传参 >config.json> 环境变量。openai_client.py是统一 LLM client 封装层；其他模块应通过这里消费 structured chat / tool calls，而不是各自拼 SDK 请求。- provider/model 的展示层（CLI/TUI/Web）可以读取这里的 helper，但不要反向把展示逻辑塞回
clients/。
ANTI-PATTERNS
- 把 secret 直接写进文档或 AGENTS；配置应留在
config.json/ 环境变量。 - 在
ui/、web/、core/里各自维护一份 provider 默认值，导致和DEFAULT_PROVIDERS漂移。 - 绕过
OpenAIClient直接在业务层拼 OpenAI SDK 请求，破坏统一的 structured/tool-call 行为。 - 修改
config.json.template/ProviderConfig字段，却不同步README.md、clients/config.py和相关 tests。
COMMANDS
cp clients/config.json.template clients/config.json
uv run python -m pytest tests/unit/test_openai_client.py tests/unit/test_structured_helper_routing.pyNOTES
clients/config.json可能是本地真实配置；检查改动时注意不要提交凭据。mimo、openai等 provider 是否出现在 UI/Web 列表，不由DEFAULT_PROVIDERS单独决定，还要看config.json的显式 provider 配置与消费层过滤。