Current Problem / 当前问题
PR #653 updated all visible UI labels and i18n strings in the Smart Routing settings panel to use provider-neutral language (e.g. OpenAI API Key → LLM Provider API Key). However, the underlying backend and frontend code still uses OpenAI-specific field names in types, interfaces, controllers, services, and configuration objects. This creates an inconsistency between what users see in the UI and the actual internal naming of the code, which can be confusing for contributors and maintainers.
The following internal field names need to be renamed to match the provider-neutral intent already reflected in the UI:
| Current internal name |
Proposed neutral name |
openaiApiKey |
llmProviderApiKey |
openaiApiBaseUrl |
llmProviderBaseUrl |
openaiApiEmbeddingModel |
embeddingModel |
The environment variable OPENAI_API_KEY (referenced in src/utils/smartRouting.ts) and OPENAI_API_EMBEDDING_MODEL should also be reviewed for backward-compatible aliasing.
Note: Azure-specific fields (azureOpenaiApiKey, azureOpenaiEndpoint, azureOpenaiApiVersion, azureOpenaiEmbeddingDeployment) are intentionally scoped to Azure and do not need renaming as part of this task.
PR #653 中,Smart Routing 设置面板中所有可见的 UI 标签和 i18n 字符串已更新为与提供商无关的语言(例如 OpenAI API Key → LLM Provider API Key)。然而,后端和前端代码中的类型、接口、控制器、服务和配置对象仍使用 OpenAI 特定的字段名称。这在 UI 中向用户展示的内容与代码内部命名之间造成了不一致,可能会给贡献者和维护者带来困惑。
Proposed Solution / 建议方案
Rename the three provider-generic fields listed above across all affected files. The following files must be updated:
src/utils/smartRouting.ts — SmartRoutingConfig interface definition and getSmartRoutingConfig() function body
src/controllers/serverController.ts — all reads, writes, and comparisons of these fields
src/services/vectorSearchService.ts — all usages when building the OpenAI-compatible client config
frontend/src/services/configService.ts — the SmartRoutingConfig TypeScript interface on the frontend side
src/types/index.ts (and any relevant DAO, DB entity, or repository files per the DAO layer guidelines in AGENTS.md) — if these fields are part of a persisted type
mcp_settings.json and example config files under examples/ — update any field name references
- Migration script (
src/utils/migration.ts) — if the fields are persisted in the JSON settings file or PostgreSQL, add backward-compatible migration to rename old field keys to new ones
对上述三个与提供商无关的字段在所有受影响的文件中进行重命名。
Alternatives / 替代方案
- Keep the current internal names and simply add code comments noting that these fields are provider-neutral despite being named after OpenAI. This avoids risk but leaves a permanent inconsistency between UI terminology and source code.
- Rename only the TypeScript/frontend interface definitions (public-facing types) while leaving internal variable names unchanged. This is a partial improvement and still causes confusion.
保留当前内部名称,仅添加代码注释说明这些字段尽管以 OpenAI 命名,但实际上是与提供商无关的。这可以避免风险,但会在 UI 术语和源代码之间留下永久性不一致。
Additional Context / 补充说明
This task was agreed upon in the PR #653 comment thread:
This is a refactoring task — no functional behavior changes are expected. A thorough search-and-replace across the codebase (backend + frontend) followed by running pnpm lint, pnpm backend:build, pnpm test:ci, and pnpm build should be sufficient to validate the changes.
⚠️ Backward compatibility: If mcp_settings.json already stores openaiApiKey, openaiApiBaseUrl, or openaiApiEmbeddingModel as JSON keys for existing deployments, a migration step must be included (read old keys → write new keys) to avoid breaking existing configurations on upgrade.
此任务在 PR #653 的评论中达成一致。这是一项重构任务 — 不会改变任何功能行为。需要注意的是:如果现有部署的 mcp_settings.json 中已存储旧字段名,必须包含迁移步骤,以避免升级时破坏现有配置。
Current Problem / 当前问题
PR #653 updated all visible UI labels and i18n strings in the Smart Routing settings panel to use provider-neutral language (e.g.
OpenAI API Key→LLM Provider API Key). However, the underlying backend and frontend code still uses OpenAI-specific field names in types, interfaces, controllers, services, and configuration objects. This creates an inconsistency between what users see in the UI and the actual internal naming of the code, which can be confusing for contributors and maintainers.The following internal field names need to be renamed to match the provider-neutral intent already reflected in the UI:
openaiApiKeyllmProviderApiKeyopenaiApiBaseUrlllmProviderBaseUrlopenaiApiEmbeddingModelembeddingModelThe environment variable
OPENAI_API_KEY(referenced insrc/utils/smartRouting.ts) andOPENAI_API_EMBEDDING_MODELshould also be reviewed for backward-compatible aliasing.Note: Azure-specific fields (
azureOpenaiApiKey,azureOpenaiEndpoint,azureOpenaiApiVersion,azureOpenaiEmbeddingDeployment) are intentionally scoped to Azure and do not need renaming as part of this task.PR #653 中,Smart Routing 设置面板中所有可见的 UI 标签和 i18n 字符串已更新为与提供商无关的语言(例如
OpenAI API Key→LLM Provider API Key)。然而,后端和前端代码中的类型、接口、控制器、服务和配置对象仍使用 OpenAI 特定的字段名称。这在 UI 中向用户展示的内容与代码内部命名之间造成了不一致,可能会给贡献者和维护者带来困惑。Proposed Solution / 建议方案
Rename the three provider-generic fields listed above across all affected files. The following files must be updated:
src/utils/smartRouting.ts—SmartRoutingConfiginterface definition andgetSmartRoutingConfig()function bodysrc/controllers/serverController.ts— all reads, writes, and comparisons of these fieldssrc/services/vectorSearchService.ts— all usages when building the OpenAI-compatible client configfrontend/src/services/configService.ts— theSmartRoutingConfigTypeScript interface on the frontend sidesrc/types/index.ts(and any relevant DAO, DB entity, or repository files per the DAO layer guidelines inAGENTS.md) — if these fields are part of a persisted typemcp_settings.jsonand example config files underexamples/— update any field name referencessrc/utils/migration.ts) — if the fields are persisted in the JSON settings file or PostgreSQL, add backward-compatible migration to rename old field keys to new ones对上述三个与提供商无关的字段在所有受影响的文件中进行重命名。
Alternatives / 替代方案
保留当前内部名称,仅添加代码注释说明这些字段尽管以 OpenAI 命名,但实际上是与提供商无关的。这可以避免风险,但会在 UI 术语和源代码之间留下永久性不一致。
Additional Context / 补充说明
This task was agreed upon in the PR #653 comment thread:
openaiApiKey,openaiApiBaseUrl, etc.) had not been modified in PR feat: use provider-neutral labels in Smart Routing settings UI #653 since the issue was scoped to UI labels only, and asked whether internal naming should also be updated.This is a refactoring task — no functional behavior changes are expected. A thorough search-and-replace across the codebase (backend + frontend) followed by running
pnpm lint,pnpm backend:build,pnpm test:ci, andpnpm buildshould be sufficient to validate the changes.此任务在 PR #653 的评论中达成一致。这是一项重构任务 — 不会改变任何功能行为。需要注意的是:如果现有部署的
mcp_settings.json中已存储旧字段名,必须包含迁移步骤,以避免升级时破坏现有配置。