From 65e79de845e9fcf4e68f7fa412558313a54f7b5b Mon Sep 17 00:00:00 2001
From: Jason <farion1231@gmail.com>
Date: Tue, 6 Oct 2026 09:48:53 +0800
Subject: [PATCH] feat(claude): explain each quick toggle with a help tip

The quick toggles above the Claude config editor had no explanation,
except a native title tooltip on the auto mode one. Put the standard "?"
help tip after each label: one sentence on what the toggle does, why
you would want it, and whether it is global or follows the provider.

Render the toggles from one list so every entry gets the same
checkbox + help layout, with copy under claudeConfig.<key> and
claudeConfig.<key>Help. The help button sits outside the <label>, so
opening the tip never flips the checkbox.
---
 .../providers/forms/CommonConfigEditor.tsx    | 80 +++++++------------
 src/i18n/locales/en.json                      |  6 +-
 src/i18n/locales/ja.json                      |  6 +-
 src/i18n/locales/zh-TW.json                   |  6 +-
 src/i18n/locales/zh.json                      |  6 +-
 tests/components/CommonConfigEditor.test.tsx  | 22 +++++
 6 files changed, 69 insertions(+), 57 deletions(-)

diff --git a/src/components/providers/forms/CommonConfigEditor.tsx b/src/components/providers/forms/CommonConfigEditor.tsx
index 96224ed25..8d235ab73 100644
--- a/src/components/providers/forms/CommonConfigEditor.tsx
+++ b/src/components/providers/forms/CommonConfigEditor.tsx
@@ -1,11 +1,21 @@
 import { useTranslation } from "react-i18next";
 import { useEffect, useState, useCallback, useMemo } from "react";
 import { Label } from "@/components/ui/label";
+import { HelpTip } from "@/components/ui/help-tip";
 import JsonEditor from "@/components/JsonEditor";
 import type { ProviderEditorInactiveField } from "@/lib/api/providers";
 import { CLAUDE_AUTO_MODE_SERVER_ENV } from "@/utils/claudeEditorOverlay";
 import { InactiveFieldsPanel } from "./InactiveFieldsPanel";
 
+/** 编辑框上方的快捷开关，顺序即显示顺序；文案在 `claudeConfig.<key>` 和 `claudeConfig.<key>Help`。 */
+const QUICK_TOGGLES = [
+  "hideAttribution",
+  "enableToolSearch",
+  "disableAutoUpgrade",
+  "disableArtifact",
+  "disableAutoModeServer",
+] as const;
+
 interface CommonConfigEditorProps {
   value: string;
   onChange: (value: string) => void;
@@ -107,7 +117,7 @@ export function CommonConfigEditor({
   }, [localValue]);
 
   const handleToggle = useCallback(
-    (toggleKey: string, checked: boolean) => {
+    (toggleKey: (typeof QUICK_TOGGLES)[number], checked: boolean) => {
       try {
         const config = JSON.parse(localValue || "{}");
 
@@ -204,58 +214,22 @@ export function CommonConfigEditor({
         })}
       </p>
       <div className="flex flex-wrap items-center gap-x-4 gap-y-1">
-        <label className="inline-flex items-center gap-2 text-sm text-fg-2 cursor-pointer">
-          <input
-            type="checkbox"
-            checked={toggleStates.hideAttribution}
-            onChange={(e) => handleToggle("hideAttribution", e.target.checked)}
-            className="ui-checkbox"
-          />
-          <span>{t("claudeConfig.hideAttribution")}</span>
-        </label>
-        <label className="inline-flex items-center gap-2 text-sm text-fg-2 cursor-pointer">
-          <input
-            type="checkbox"
-            checked={toggleStates.enableToolSearch}
-            onChange={(e) => handleToggle("enableToolSearch", e.target.checked)}
-            className="ui-checkbox"
-          />
-          <span>{t("claudeConfig.enableToolSearch")}</span>
-        </label>
-        <label className="inline-flex items-center gap-2 text-sm text-fg-2 cursor-pointer">
-          <input
-            type="checkbox"
-            checked={toggleStates.disableAutoUpgrade}
-            onChange={(e) =>
-              handleToggle("disableAutoUpgrade", e.target.checked)
-            }
-            className="ui-checkbox"
-          />
-          <span>{t("claudeConfig.disableAutoUpgrade")}</span>
-        </label>
-        <label className="inline-flex items-center gap-2 text-sm text-fg-2 cursor-pointer">
-          <input
-            type="checkbox"
-            checked={toggleStates.disableArtifact}
-            onChange={(e) => handleToggle("disableArtifact", e.target.checked)}
-            className="ui-checkbox"
-          />
-          <span>{t("claudeConfig.disableArtifact")}</span>
-        </label>
-        <label
-          className="inline-flex items-center gap-2 text-sm text-fg-2 cursor-pointer"
-          title={t("claudeConfig.disableAutoModeServerHint")}
-        >
-          <input
-            type="checkbox"
-            checked={toggleStates.disableAutoModeServer}
-            onChange={(e) =>
-              handleToggle("disableAutoModeServer", e.target.checked)
-            }
-            className="ui-checkbox"
-          />
-          <span>{t("claudeConfig.disableAutoModeServer")}</span>
-        </label>
+        {QUICK_TOGGLES.map((key) => (
+          <span key={key} className="inline-flex items-center gap-1">
+            <label className="inline-flex items-center gap-2 text-sm text-fg-2 cursor-pointer">
+              <input
+                type="checkbox"
+                checked={toggleStates[key]}
+                onChange={(e) => handleToggle(key, e.target.checked)}
+                className="ui-checkbox"
+              />
+              <span>{t(`claudeConfig.${key}`)}</span>
+            </label>
+            <HelpTip title={t(`claudeConfig.${key}`)}>
+              {t(`claudeConfig.${key}Help`)}
+            </HelpTip>
+          </span>
+        ))}
       </div>
       <JsonEditor
         value={localValue}
diff --git a/src/i18n/locales/en.json b/src/i18n/locales/en.json
index 0f957026f..3629d9b49 100644
--- a/src/i18n/locales/en.json
+++ b/src/i18n/locales/en.json
@@ -71,11 +71,15 @@
     "configLabel": "Claude Code settings.json (JSON) *",
     "fullSettingsHint": "Full Claude Code settings.json content",
     "hideAttribution": "Hide AI Attribution",
+    "hideAttributionHelp": "Commits and PRs created by Claude Code no longer carry the Co-Authored-By trailer or the session link. Global: applies to every provider.",
     "enableToolSearch": "Enable Tool Search",
+    "enableToolSearchHelp": "Loads MCP tool definitions on demand to save context. Off by default on third-party endpoints; enable it only if the upstream supports tool_reference. Switches with the provider.",
     "disableAutoUpgrade": "Disable Auto-Upgrade",
+    "disableAutoUpgradeHelp": "Keeps Claude Code on its current version instead of updating automatically; run claude update yourself when needed. Global.",
     "disableArtifact": "Disable Artifact Tool",
+    "disableArtifactHelp": "Leaves the Artifact tool out of requests. Some third-party gateways reject its schema and return 400 on every request. Switches with the provider.",
     "disableAutoModeServer": "Disable Auto Mode Server Checks",
-    "disableAutoModeServerHint": "Third-party gateways can't run auto mode's server-side checks. When on, Claude Code uses its own checks and stops showing the \"this session isn't eligible\" notice in every session (CLAUDE_CODE_AUTO_MODE_SERVER=0). Leave off for the official endpoint.",
+    "disableAutoModeServerHelp": "Gateways can't run the server-side check, so auto mode pauses once per session with a \"not eligible\" notice, then falls back to the local check after you press Enter. Checked, it uses the local check right away with no notice. Leave it unchecked on official endpoints.",
     "keyFieldsHint": "Endpoint, key, models, context window and compatibility switches follow the provider; everything else is a global Claude Code setting and applies to every provider once saved.",
     "inactiveFieldsHint": "This provider still stores {{count}} field(s) that do not take effect when switching. Click one to add it to the global settings above; it is written to the config file on save, and the value stored in the provider is kept.",
     "addToGlobalSettings": "Add to global settings"
diff --git a/src/i18n/locales/ja.json b/src/i18n/locales/ja.json
index 9c881abf7..39b14dae2 100644
--- a/src/i18n/locales/ja.json
+++ b/src/i18n/locales/ja.json
@@ -71,11 +71,15 @@
     "configLabel": "Claude Code settings.json (JSON) *",
     "fullSettingsHint": "Claude Code の settings.json 全文",
     "hideAttribution": "AI署名を非表示",
+    "hideAttributionHelp": "Claude Code が作成するコミットと PR に Co-Authored-By 署名とセッションリンクを付けません。グローバル設定で、すべてのプロバイダーに適用されます。",
     "enableToolSearch": "Tool Search を有効化",
+    "enableToolSearchHelp": "MCP ツールが多いとき、ツール定義を必要に応じて読み込みコンテキストを節約します。サードパーティのエンドポイントでは既定でオフ。上流が tool_reference に対応している場合のみオンにしてください。プロバイダーに従って切り替わります。",
     "disableAutoUpgrade": "自動アップグレードを無効化",
+    "disableAutoUpgradeHelp": "Claude Code を現在のバージョンのままにし、自動更新しません。必要なときは claude update を手動で実行します。グローバル設定。",
     "disableArtifact": "Artifact ツールを無効化",
+    "disableArtifactHelp": "Artifact ツールをリクエストに含めません。一部のサードパーティゲートウェイはそのスキーマを拒否し、すべてのリクエストで 400 を返します。プロバイダーに従って切り替わります。",
     "disableAutoModeServer": "auto mode のサーバー側チェックを無効化",
-    "disableAutoModeServerHint": "サードパーティのゲートウェイは auto mode のサーバー側チェックに対応していません。オンにすると Claude Code は自前のチェックを使い、セッションごとの「このセッションは対象外です」という通知が出なくなります（CLAUDE_CODE_AUTO_MODE_SERVER=0）。公式エンドポイントではオフのままにしてください。",
+    "disableAutoModeServerHelp": "ゲートウェイはサーバー側チェックに対応していないため、auto mode はセッションごとに一度「対象外」の通知で止まり、Enter を押すとローカルチェックに切り替わります。オンにすると最初からローカルチェックを使い、通知は出ません。公式エンドポイントではオンにしないでください。",
     "keyFieldsHint": "エンドポイント、キー、モデル、コンテキストウィンドウ、互換スイッチはプロバイダーの切り替えに従います。それ以外のフィールドは Claude Code のグローバル設定で、保存するとすべてのプロバイダーに適用されます。",
     "inactiveFieldsHint": "このプロバイダーには、切り替えても反映されないフィールドが {{count}} 件保存されています。クリックすると上のグローバル設定に追加され、保存時に設定ファイルへ書き込まれます。プロバイダーに保存された元の値は削除されません。",
     "addToGlobalSettings": "グローバル設定に追加"
diff --git a/src/i18n/locales/zh-TW.json b/src/i18n/locales/zh-TW.json
index 5db5806b8..bc46e273a 100644
--- a/src/i18n/locales/zh-TW.json
+++ b/src/i18n/locales/zh-TW.json
@@ -71,11 +71,15 @@
     "configLabel": "Claude Code 設定 (JSON) *",
     "fullSettingsHint": "完整的 Claude Code settings.json 設定內容",
     "hideAttribution": "隱藏 AI 署名",
+    "hideAttributionHelp": "Claude Code 產生的提交和 PR 不再帶 Co-Authored-By 署名和工作階段連結。全域設定，對所有供應商生效。",
     "enableToolSearch": "啟用 Tool Search",
+    "enableToolSearchHelp": "MCP 工具多時按需載入工具定義，節省上下文。第三方位址預設關閉，上游支援 tool_reference 才能開。隨供應商切換。",
     "disableAutoUpgrade": "停用自動升級",
+    "disableAutoUpgradeHelp": "Claude Code 維持目前版本，不再自動更新，需要時手動執行 claude update。全域設定。",
     "disableArtifact": "停用 Artifact 工具",
+    "disableArtifactHelp": "不把 Artifact 工具送給模型。部分第三方閘道會因它的 schema 對每個請求回報 400。隨供應商切換。",
     "disableAutoModeServer": "停用 auto mode 伺服器端檢查",
-    "disableAutoModeServerHint": "第三方閘道不支援 auto mode 的伺服器端檢查。勾選後 Claude Code 改用自己的檢查，不再每個工作階段跳出「此工作階段不符合資格」的提示（CLAUDE_CODE_AUTO_MODE_SERVER=0）。官方端點請勿勾選。",
+    "disableAutoModeServerHelp": "閘道不支援伺服器端檢查，auto mode 每個工作階段會先停下提示一次「不符合條件」，按 Enter 後改用本機檢查。勾選後直接用本機檢查，不再提示。官方端點不要勾選。",
     "keyFieldsHint": "位址、Key、模型、上下文視窗和相容開關隨供應商切換；其餘欄位是 Claude Code 全域設定，儲存後對所有供應商生效。",
     "inactiveFieldsHint": "這個供應商還保存著 {{count}} 個不隨切換生效的欄位。點擊可加入上方的全域設定，儲存後寫入設定檔；供應商裡保存的原值不會刪除。",
     "addToGlobalSettings": "加入全域設定"
diff --git a/src/i18n/locales/zh.json b/src/i18n/locales/zh.json
index 6227b1baf..6aa0f0a17 100644
--- a/src/i18n/locales/zh.json
+++ b/src/i18n/locales/zh.json
@@ -71,11 +71,15 @@
     "configLabel": "Claude Code 配置 (JSON) *",
     "fullSettingsHint": "完整的 Claude Code settings.json 配置内容",
     "hideAttribution": "隐藏 AI 署名",
+    "hideAttributionHelp": "Claude Code 生成的提交和 PR 不再带 Co-Authored-By 署名和会话链接。全局设置，对所有供应商生效。",
     "enableToolSearch": "启用 Tool Search",
+    "enableToolSearchHelp": "MCP 工具多时按需加载工具定义，节省上下文。第三方地址默认关闭，上游支持 tool_reference 才能开。随供应商切换。",
     "disableAutoUpgrade": "禁用自动升级",
+    "disableAutoUpgradeHelp": "Claude Code 保持当前版本，不再自动更新，需要时手动运行 claude update。全局设置。",
     "disableArtifact": "禁用 Artifact 工具",
+    "disableArtifactHelp": "不把 Artifact 工具发给模型。部分第三方网关会因它的 schema 对每个请求报 400。随供应商切换。",
     "disableAutoModeServer": "关闭 auto mode 服务端检查",
-    "disableAutoModeServerHint": "第三方网关不支持 auto mode 的服务端检查。勾选后 Claude Code 改用自己的检查，不再每个会话弹出“本会话不符合条件”的提示（CLAUDE_CODE_AUTO_MODE_SERVER=0）。官方端点不要勾选。",
+    "disableAutoModeServerHelp": "网关不支持服务端检查，auto mode 每个会话会先停下提示一次「不符合条件」，回车后改用本机检查。勾选后直接用本机检查，不再提示。官方端点不要勾选。",
     "keyFieldsHint": "地址、Key、模型、上下文窗口和兼容开关随供应商切换；其余字段是 Claude Code 全局设置，保存后对所有供应商生效。",
     "inactiveFieldsHint": "这个供应商还保存着 {{count}} 个不随切换生效的字段。点击可加入上方的全局设置，保存后写入配置文件；供应商里保存的原值不会删除。",
     "addToGlobalSettings": "加入全局设置"
diff --git a/tests/components/CommonConfigEditor.test.tsx b/tests/components/CommonConfigEditor.test.tsx
index d79a79fee..2c6ab1869 100644
--- a/tests/components/CommonConfigEditor.test.tsx
+++ b/tests/components/CommonConfigEditor.test.tsx
@@ -139,3 +139,25 @@ describe("CommonConfigEditor auto mode server toggle", () => {
     expect(JSON.parse(onChange.mock.calls[0][0])).toEqual({});
   });
 });
+
+describe("CommonConfigEditor quick toggle help", () => {
+  it("gives every toggle a help button that does not toggle it", () => {
+    const onChange = renderEditor("{}");
+
+    for (const key of [
+      "hideAttribution",
+      "enableToolSearch",
+      "disableAutoUpgrade",
+      "disableArtifact",
+      "disableAutoModeServer",
+    ]) {
+      const help = screen.getByRole("button", { name: `claudeConfig.${key}` });
+      expect(help).toHaveAccessibleDescription(`claudeConfig.${key}Help`);
+      fireEvent.click(help);
+      expect(
+        screen.getByRole("checkbox", { name: `claudeConfig.${key}` }),
+      ).not.toBeChecked();
+    }
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});