refactor: 提取 api_enabled 至公共模块并优化同步逻辑

Author: i-stack

env/platforms/claude.json

@@ -7,7 +7,10 @@
         "ANTHROPIC_AUTH_TOKEN": "${claude.token}",
         "ANTHROPIC_BASE_URL": "${claude.url}",
         "CLAUDE_CODE_EFFORT_LEVEL": "medium",
-        "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
+        "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
+        "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8",
+        "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
+        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001-thinking"
     },
     "preamble": {
         "target": "CLAUDE.md",

sync/cli/validate_env_schema.py

@@ -12,6 +12,9 @@
 import json
 from pathlib import Path
 
+from platforms.claude import _HOST_SKIP as _CLAUDE_HOST_SKIP
+from platforms.codex import _HOST_SKIP as _CODEX_HOST_SKIP
+
 REPO_ROOT = Path(__file__).resolve().parents[2]
 ENV_DIR = REPO_ROOT / "env"
 MCP_DIR = ENV_DIR / "mcp"
@@ -87,38 +90,22 @@ def validate_mcp_file(path: Path) -> list[str]:
 }
 
 PLATFORM_FIELDS = {
-    # Claude-specific
+    # Claude-specific: team-shared fields not covered by _HOST_SKIP, unioned
+    # with the platform's own host-specific set (kept in sync with the real
+    # skip list instead of hand-duplicating it — see platforms/claude.py).
     "claude": {
         "model", "effortLevel", "alwaysThinkingEnabled", "outputStyle",
         "includeGitInstructions", "respectGitignore", "fileCheckpointingEnabled",
         "autoCompactEnabled", "autoMemoryEnabled", "respondToBashCommands",
         "permissions", "hooks", "_hostSettings",
-        "apiKeyHelper", "theme", "tui", "editorMode", "preferredNotifChannel",
-        "statusLine", "voice", "voiceEnabled", "viewMode", "prefersReducedMotion",
-        "syntaxHighlightingDisabled", "terminalProgressBarEnabled",
-        "wheelScrollAccelerationEnabled", "axScreenReaderRender", "showTurnDuration",
-        "showThinkingSummaries", "showClearContextOnPlanAccept", "autoScrollEnabled",
-        "spinnerTipsEnabled", "spinnerTipsOverride", "spinnerVerbs", "companyAnnouncements",
-        "footerLinksRegexes", "language", "ultracode", "fastModePerSessionOptIn",
-        "autoConnectIde", "autoInstallIdeExtension", "externalEditorContext",
-        "fileSuggestion", "feedbackSurveyRate", "cleanupPeriodDays", "defaultShell",
-        "prUrlTemplate", "autoUpdatesChannel", "sshConfigs", "worktree", "plansDirectory",
-        "autoMemoryDirectory", "teammateMode", "teammateDefaultModel", "disableAgentView",
-        "agent", "agentPushNotifEnabled", "inputNeededNotifEnabled", "remoteControlAtStartup",
-        "awsAuthRefresh", "awsCredentialExport", "gcpAuthRefresh", "otelHeadersHelper",
-        "claudeMd", "claudeMdExcludes", "policyHelper", "skipWebFetchPreflight",
-    },
-    # Codex-specific
+    } | _CLAUDE_HOST_SKIP,
+    # Codex-specific: team-shared fields not covered by _HOST_SKIP, unioned
+    # with the platform's own host-specific set (see platforms/codex.py).
     "codex": {
-        "model", "model_provider", "model_providers", "personality",
-        "model_reasoning_effort", "model_verbosity", "model_reasoning_summary",
-        "plan_mode_reasoning_effort", "sandbox_mode", "approval_policy",
-        "allow_login_shell", "default_permissions", "project_doc_max_bytes",
-        "project_doc_fallback_filenames", "sandbox_workspace_write", "features",
-        "projects", "hide_agent_reasoning", "web_search", "file_opener", "history",
-        "tools", "shell_environment_policy", "tui", "agents", "memories",
-        "analytics", "feedback",
-    },
+        "model", "model_provider", "model_providers", "sandbox_mode",
+        "approval_policy", "allow_login_shell", "default_permissions",
+        "sandbox_workspace_write", "projects",
+    } | _CODEX_HOST_SKIP,
     # CodeBuddy-specific
     "codebuddy": {"models", "availableModels"},
     # Qwen-specific

sync/cli/validate_platform_keys.py

@@ -27,34 +27,6 @@
     "continue": {"path", "recall"},
 }
 
-# Canonical host-specific (personal) keys per platform. A key from this set that
-# appears in env/platforms/<platform>.json but is NOT declared in the platform's
-# _HOST_SKIP would leak into team-shared settings. Keep in sync with each
-# platform module's _HOST_SKIP / host-specific definitions.
-HOST_SPECIFIC_KEYS = {
-    "claude": {
-        "apiKeyHelper", "theme", "tui", "editorMode", "preferredNotifChannel",
-        "statusLine", "voice", "voiceEnabled", "viewMode", "prefersReducedMotion",
-        "syntaxHighlightingDisabled", "terminalProgressBarEnabled",
-        "wheelScrollAccelerationEnabled", "axScreenReaderRender", "showTurnDuration",
-        "showThinkingSummaries", "showClearContextOnPlanAccept", "autoScrollEnabled",
-        "spinnerTipsEnabled", "spinnerTipsOverride", "spinnerVerbs", "companyAnnouncements",
-        "footerLinksRegexes", "language", "ultracode", "fastModePerSessionOptIn",
-        "autoConnectIde", "autoInstallIdeExtension", "externalEditorContext",
-        "fileSuggestion", "feedbackSurveyRate", "cleanupPeriodDays", "defaultShell",
-        "prUrlTemplate", "autoUpdatesChannel", "sshConfigs", "worktree", "plansDirectory",
-        "autoMemoryDirectory", "teammateMode", "teammateDefaultModel", "disableAgentView",
-        "agent", "agentPushNotifEnabled", "inputNeededNotifEnabled", "remoteControlAtStartup",
-        "awsAuthRefresh", "awsCredentialExport", "gcpAuthRefresh", "otelHeadersHelper",
-        "claudeMd", "claudeMdExcludes", "policyHelper", "skipWebFetchPreflight",
-    },
-    "codex": {
-        "hide_agent_reasoning", "web_search", "file_opener", "history", "tools",
-        "shell_environment_policy", "tui", "agents", "memories", "analytics", "feedback",
-    },
-}
-
-
 def load_platform_json(platform: str) -> dict:
     path = REPO_ROOT / "env" / "platforms" / f"{platform}.json"
     if not path.is_file():
@@ -78,19 +50,19 @@ def check_platform(platform: str) -> list[str]:
       - internal (starts with '_'),
       - engine-handled (e.g. env, hooks, export_env_to_zshrc, _hostSettings),
       - declared in the platform's _HOST_SKIP (excluded from team settings),
-      - a known host-specific key that IS in _HOST_SKIP (leak guard),
       - a known team-shared key for this platform.
 
     Any other key (unknown/typo, or a host-specific key missing from _HOST_SKIP)
-    produces a warning, making the check fail-closed instead of always passing.
+    produces a warning through the schema allowlist, making the check
+    fail-closed instead of relying on another hand-maintained host-specific
+    list.
     """
     cfg = load_platform_json(platform)
     if not cfg:
         return [f"  {platform}: no config file found"]
 
     warnings: list[str] = []
     host_skip = get_host_skip(platform)
-    host_specific = HOST_SPECIFIC_KEYS.get(platform, set())
     engine_handled = ENGINE_HANDLED_KEYS | ENGINE_HANDLED_BY_PLATFORM.get(platform, set())
     known_fields = known_fields_for_platform(platform)
 
@@ -106,12 +78,6 @@ def check_platform(platform: str) -> list[str]:
         if key in host_skip:
             skip_count += 1
             continue
-        if key in host_specific:
-            warnings.append(
-                f"  {platform}: key '{key}' is host-specific but NOT in _HOST_SKIP "
-                f"— would leak to team-shared settings."
-            )
-            continue
         if key not in known_fields:
             warnings.append(
                 f"  {platform}: key '{key}' is not in the schema allowlist and not in "

sync/core/common.py

@@ -384,6 +384,19 @@ def merge_object(existing: Any, updates: dict[str, Any]) -> dict[str, Any]:
     return {**base, **updates}
 
 
+def api_enabled(cfg: dict[str, Any]) -> bool:
+    """Third-party API sync toggle, shared by every platform's sync engine.
+
+    A missing ``api`` block or missing ``api.enabled`` defaults to enabled,
+    preserving the historical always-sync behavior. Only an explicit
+    ``false`` disables synced API fields.
+    """
+    api = cfg.get("api")
+    if not isinstance(api, dict):
+        return True
+    return api.get("enabled", True) is True
+
+
 # ── Path helpers (imported from centralized paths module) ────────────────────
 
 from .paths import (  # noqa: F401

sync/platforms/claude.py

@@ -3,6 +3,7 @@
 from typing import Any
 
 from core.common import (
+    api_enabled as _api_enabled,
     merge_object,
     prune_managed_keys_via_sidecar,
     read_json_object,
@@ -33,12 +34,6 @@ def _repo_hooks_dir() -> Path:
 _API_SIDECAR = ".managed_api_fields.json"
 
 
-def _api_enabled(cfg: dict[str, Any]) -> bool:
-    api = cfg.get("api")
-    if not isinstance(api, dict):
-        return True
-    return api.get("enabled", True) is True
-
 # ── Host-specific keys ──
 # These keys are kept in env/platforms/claude.json as reference but excluded
 # from managed (team-shared) settings — each developer sets them individually.

sync/platforms/cline.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 from typing import Any
 
-from core.common import read_json_object, write_json
+from core.common import api_enabled as _api_enabled, read_json_object, write_json
 from core.paths import (
     claude_skills_base,
     cline_data_dir,
@@ -53,20 +53,6 @@ def _save_managed_keys(global_state_keys: set[str], secret_keys: set[str]) -> No
     })
 
 
-def _api_enabled(cfg: dict[str, Any]) -> bool:
-    """Cline third-party API sync toggle.
-
-    Missing ``api`` block or missing ``api.enabled`` defaults to enabled,
-    preserving the historical always-sync behavior (Cline previously always
-    merged globalState + secrets). Only an explicit ``false`` disables synced
-    API fields (globalState + secrets) and cleans the keys the syncer owns.
-    """
-    api = cfg.get("api")
-    if not isinstance(api, dict):
-        return True
-    return api.get("enabled", True) is True
-
-
 def _sync_mcp(servers: dict[str, Any]) -> None:
     targets = [p for p in cline_mcp_candidate_paths() if p.parent.exists()]
     if not targets:
@@ -94,9 +80,29 @@ def _sync_skills() -> None:
             continue
 
         dest = cline_skills_dir / skill_dir.name
+        tmp = cline_skills_dir / f".{skill_dir.name}.tmp-sync"
+        backup = cline_skills_dir / f".{skill_dir.name}.backup-sync"
+
+        if tmp.exists():
+            shutil.rmtree(tmp)
+        if backup.exists():
+            shutil.rmtree(backup)
+
+        shutil.copytree(skill_dir, tmp)
+
         if dest.exists():
-            shutil.rmtree(dest)
-        shutil.copytree(skill_dir, dest)
+            dest.rename(backup)
+        try:
+            tmp.rename(dest)
+        except OSError:
+            if backup.exists() and not dest.exists():
+                backup.rename(dest)
+            raise
+        finally:
+            if tmp.exists():
+                shutil.rmtree(tmp)
+            if backup.exists():
+                shutil.rmtree(backup)
         synced.append(skill_dir.name)
 
     print(f"Synced {len(synced)} skills to {cline_skills_dir}: {', '.join(synced) or '(none)'}.")

sync/platforms/codebuddy.py

@@ -3,7 +3,7 @@
 from typing import Any
 
 from core import recall
-from core.common import read_json_object, sync_json_mcp, write_json
+from core.common import api_enabled as _api_enabled, read_json_object, sync_json_mcp, write_json
 from core.paths import (
     claude_skills_base,
     codebuddy_mcp_path,
@@ -54,19 +54,6 @@ def _merge_recall_block(target: Path, block: str) -> None:
     recall.merge_recall_block_markdown(target, block)
 
 
-def _api_enabled(cfg: dict[str, Any]) -> bool:
-    """CodeBuddy third-party API sync toggle.
-
-    Like Claude, a missing ``api`` block or missing ``api.enabled`` defaults to
-    enabled so the historical always-sync behavior is preserved. Only an explicit
-    ``false`` disables synced API model fields.
-    """
-    api = cfg.get("api")
-    if not isinstance(api, dict):
-        return True
-    return api.get("enabled", True) is True
-
-
 def _validate_model_entries(value: Any) -> list[dict[str, Any]]:
     if not isinstance(value, list):
         raise ValueError("platforms.codebuddy.models must be a list.")

sync/platforms/codex.py

@@ -3,6 +3,7 @@
 from typing import Any
 
 from core.common import (
+    api_enabled as _api_enabled,
     codex_config_path,
     codex_root_dir,
     load_platform_config,
@@ -35,19 +36,6 @@
 )
 
 
-def _api_enabled(cfg: dict[str, Any]) -> bool:
-    """Codex third-party API sync toggle.
-
-    A missing ``api`` block or missing ``api.enabled`` defaults to enabled,
-    preserving the historical always-sync behavior. Only an explicit
-    ``false`` disables synced API fields.
-    """
-    api = cfg.get("api")
-    if not isinstance(api, dict):
-        return True
-    return api.get("enabled", True) is True
-
-
 def generate_mcp_toml(servers: dict[str, Any]) -> str:
     """Generate TOML for MCP servers (platform-agnostic)."""
     lines: list[str] = ["# AUTOGENERATED from env/mcp/", ""]

sync/platforms/continue.py

@@ -4,6 +4,7 @@
 from typing import Any
 
 from core import recall
+from core.common import api_enabled as _api_enabled
 from core.paths import continue_root_dir
 
 
@@ -311,19 +312,6 @@ def _repo_root() -> Path:
     return here.parents[2]
 
 
-def _api_enabled(cfg: dict[str, Any]) -> bool:
-    """Continue third-party API sync toggle.
-
-    Missing ``api`` or missing ``api.enabled`` defaults to enabled, preserving
-    the historical always-sync behavior for the managed ``models`` block. Only
-    an explicit ``false`` disables synced API model fields.
-    """
-    api = cfg.get("api")
-    if not isinstance(api, dict):
-        return True
-    return api.get("enabled", True) is True
-
-
 def _remove_yaml_root_key(yaml_text: str, key_name: str) -> str:
     """Remove a top-level key (and its nested block) from YAML text.
 

sync/platforms/gemini.py

@@ -1,7 +1,12 @@
 from pathlib import Path
 from typing import Any
 
-from core.common import prune_managed_keys_via_sidecar, read_json_object, write_json
+from core.common import (
+    api_enabled as _api_enabled,
+    prune_managed_keys_via_sidecar,
+    read_json_object,
+    write_json,
+)
 from core.paths import (
     gemini_root_dir,
     gemini_settings_path,
@@ -19,19 +24,6 @@
 _API_MODEL_FIELDS = {"model"}
 
 
-def _api_enabled(cfg: dict[str, Any]) -> bool:
-    """Gemini third-party API sync toggle.
-
-    Missing ``api`` or missing ``api.enabled`` defaults to enabled, preserving
-    the historical always-sync behavior. Only an explicit ``false`` disables
-    synced API fields.
-    """
-    api = cfg.get("api")
-    if not isinstance(api, dict):
-        return True
-    return api.get("enabled", True) is True
-
-
 def _extract_settings(cfg: dict[str, Any], api_enabled: bool = True) -> dict[str, Any]:
     """Extract Gemini CLI settings from platform config, stripping internal keys.