xg-cli 1.0__py3-none-any.whl

xg/config/provider_service.py

@@ -0,0 +1,267 @@
+"""Provider 配置服务：inline 斜杠命令与 TUI 面板共享的 CRUD 入口。
+
+设计口径：
+- config.json 是 provider 定义与 API Key 的唯一存储，不再写 .env。
+- 写 config.json 复用 :class:`xg.config.manager.ConfigManager` 的分层读写。
+- 所有写入在保存前经过校验（api_base 合法、default_model 必填、name 合法、
+  key 非占位值），并把错误前移到输入阶段。
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+from xg.config.manager import ConfigManager, _is_placeholder, mask_key
+
+_NAME_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
+_ALLOWED_FIELDS = ("api_base", "default_model", "display_name")
+
+
+@dataclass
+class OpResult:
+    ok: bool
+    message: str
+    data: object | None = None
+
+
+def validate_api_base(url: str) -> str | None:
+    """校验 api_base；非法时返回错误提示，合法返回 None（对齐反引号坑 J6）。"""
+    if not url or url != url.strip():
+        return "api_base 不能为空或包含首尾空白"
+    if any(ch in url for ch in ("`", " ")):
+        return "api_base 含非法字符（如反引号或空格），请去掉后重试"
+    try:
+        parsed = urlsplit(url)
+    except ValueError as exc:
+        return f"api_base 无法解析为 URL: {exc}"
+    if parsed.scheme not in ("http", "https") or not parsed.netloc:
+        return "api_base 必须是合法的 http(s) URL（如 https://gateway.my.com/v1）"
+    return None
+
+
+def validate_name(name: str) -> str | None:
+    """校验 provider 名称；非法时返回提示。"""
+    if not name:
+        return "provider 名称不能为空"
+    if not _NAME_RE.fullmatch(name):
+        return "provider 名称只能包含字母、数字、下划线或连字符，且不含空格"
+    return None
+
+
+def validate_model(model: str) -> str | None:
+    """校验模型名；非法时返回提示（非法字符/空白）。"""
+    if not model or model != model.strip():
+        return "模型名不能为空或包含首尾空白"
+    if any(ch in model for ch in ("`", " ")):
+        return "模型名含非法字符（如反引号或空格），请去掉后重试"
+    return None
+
+
+class ProviderConfigService:
+    """面向界面的 provider 管理服务（无内置预设，纯用户自定义）。"""
+
+    def __init__(self, manager: ConfigManager, settings: object | None = None) -> None:
+        self.manager = manager
+        self.settings = settings
+
+    # ---------- 读取 ----------
+
+    def _active_provider(self) -> str:
+        if self.settings is not None and getattr(self.settings, "provider", ""):
+            return str(self.settings.provider)
+        try:
+            return self.manager.active().provider_name
+        except Exception:
+            return ""
+
+    def list(self) -> list[dict]:
+        """返回每个 provider 的视图：脱敏、来源层、是否 base、key 是否已配置。"""
+        active = self._active_provider()
+        rows = []
+        for name in self.manager.provider_names():
+            provider = self.manager.resolve_provider(name)
+            if provider is None:
+                continue
+            raw = provider.api_key
+            configured = bool(raw) and not _is_placeholder(raw)
+            rows.append(
+                {
+                    "name": name,
+                    "display_name": provider.display_name,
+                    "api_base": provider.api_base,
+                    "default_model": provider.default_model,
+                    "models": list(provider.models),
+                    "has_key": configured,
+                    "is_base": name == active,
+                    "layer": self.manager.provider_layer(name) or "user",
+                }
+            )
+        return rows
+
+    def get(self, name: str) -> dict | None:
+        provider = self.manager.resolve_provider(name)
+        if provider is None:
+            return None
+        raw = provider.api_key
+        configured = bool(raw) and not _is_placeholder(raw)
+        return {
+            "name": name,
+            "display_name": provider.display_name,
+            "api_base": provider.api_base,
+            "default_model": provider.default_model,
+            "models": list(provider.models),
+            "api_key": raw if configured else "",
+            "api_key_masked": mask_key(raw if configured else ""),
+            "has_key": configured,
+            "is_base": name == self._active_provider(),
+            "layer": self.manager.provider_layer(name) or "user",
+        }
+
+    def referenced_by(self, name: str) -> list[str]:
+        """返回引用该 provider 的 SmartRouter 档位名（缺省空）。"""
+        tiers = (self.manager.smart_router_config().get("tiers") or {})
+        return [t for t, cfg in tiers.items() if cfg.get("provider") == name]
+
+    # ---------- 写入 ----------
+
+    def add(
+        self,
+        name: str,
+        api_base: str,
+        default_model: str,
+        display_name: str | None = None,
+        api_key: str | None = None,
+    ) -> OpResult:
+        if self.manager.resolve_provider(name) is not None:
+            return OpResult(False, f"provider 已存在: {name}，如需修改请用 update/set（J4）")
+        err = self._validate_fields(api_base, default_model)
+        if err:
+            return OpResult(False, err)
+        fields = {
+            "api_base": api_base.strip(),
+            "default_model": default_model.strip(),
+            "display_name": display_name.strip() if display_name else None,
+        }
+        layer = self.manager.upsert_provider(name, fields)
+        out = f"已添加 provider: {name}（写入 {layer} 配置）"
+        if api_key:
+            key_result = self.set_api_key(name, api_key)
+            if not key_result.ok:
+                out += f"{key_result.message}"
+        return OpResult(True, out, {"layer": layer})
+
+    def update(self, name: str, fields: dict) -> OpResult:
+        provider = self.manager.resolve_provider(name)
+        if provider is None:
+            return OpResult(False, f"未知 provider: {name}，可用: {', '.join(self.manager.provider_names()) or '（无）'}")
+        unknown = [k for k in fields if k not in _ALLOWED_FIELDS]
+        if unknown:
+            return OpResult(False, f"不支持字段: {', '.join(unknown)}；可用: {', '.join(_ALLOWED_FIELDS)}")
+        api_base = fields.get("api_base")
+        if api_base is not None:
+            err = validate_api_base(str(api_base))
+            if err:
+                return OpResult(False, err)
+        default_model = fields.get("default_model")
+        if default_model is not None and not str(default_model).strip():
+            return OpResult(False, "default_model 必填，不能为空（J7）")
+        normalized = {}
+        if api_base is not None:
+            normalized["api_base"] = str(api_base).strip()
+        if default_model is not None:
+            normalized["default_model"] = str(default_model).strip()
+        if "display_name" in fields:
+            normalized["display_name"] = (
+                str(fields["display_name"]).strip() if fields["display_name"] or fields["display_name"] == "" else None
+            )
+        layer = self.manager.upsert_provider(name, normalized)
+        return OpResult(True, f"已更新 provider: {name}（写入 {layer} 配置）")
+
+    def remove(self, name: str, *, yes: bool = False) -> OpResult:
+        provider = self.manager.resolve_provider(name)
+        if provider is None:
+            return OpResult(False, f"未知 provider: {name}")
+        if name == self._active_provider():
+            return OpResult(
+                False,
+                f"不能删除当前 base provider: {name}（否则没有可用 base）。请先 /provider switch <其它> 再删。",
+            )
+        referenced = self.referenced_by(name)
+        warnings = []
+        if referenced:
+            warnings.append(f"被 SmartRouter 档位引用：{', '.join(referenced)}（删除后这些档位会回落 base）")
+        if not yes:
+            head = "；".join(warnings) + "。" if warnings else "此操作会删除该 provider。"
+            return OpResult(False, f"{head} 确认请加 --yes（/provider remove {name} --yes）")
+        self.manager.delete_provider(name)
+        msg = f"已删除 provider: {name}"
+        if warnings:
+            msg += "（" + "；".join(warnings) + "）"
+        return OpResult(True, msg)
+
+    def switch(self, name: str, model: str | None = None) -> OpResult:
+        provider = self.manager.resolve_provider(name)
+        if provider is None:
+            return OpResult(False, f"未知 provider: {name}，可用: {', '.join(self.manager.provider_names()) or '（无）'}")
+        target_model = (model or "").strip() or provider.default_model
+        self.manager.set_active(provider.name, target_model)
+        return OpResult(True, f"base 已切换: {provider.name} / {target_model}")
+
+    def set_api_key(self, name: str, key: str, *, overwrite: bool = False, yes: bool = False) -> OpResult:
+        provider = self.manager.resolve_provider(name)
+        if provider is None:
+            return OpResult(False, f"未知 provider: {name}")
+        if _is_placeholder(key):
+            return OpResult(False, "占位值（如 sk-xxx）视为未配置，已拒绝写入")
+        existing = provider.api_key
+        if existing and not _is_placeholder(existing) and not overwrite:
+            if not yes:
+                return OpResult(
+                    False,
+                    f"{name} 已配置 key {mask_key(existing)}，覆盖请加 --yes（/provider key {name} <KEY> --yes）",
+                )
+            overwrite = True
+        self.manager.upsert_provider(name, {"api_key": key})
+        status = "已写入" if (existing and existing != key) or not existing else "未改动"
+        extra = f"（覆盖旧值 {mask_key(existing)}）" if existing and existing != key else ""
+        return OpResult(True, f"{status} providers.{name}.api_key -> config.json，仅显示 {mask_key(key)}{extra}")
+
+    def add_model(self, name: str, model: str) -> OpResult:
+        """把模型加入 provider 的模型列表（去重；写入生效层）。"""
+        provider = self.manager.resolve_provider(name)
+        if provider is None:
+            return OpResult(False, f"未知 provider: {name}，可用: {', '.join(self.manager.provider_names()) or '（无）'}")
+        err = validate_model(model)
+        if err:
+            return OpResult(False, err)
+        model = model.strip()
+        current = list(provider.models)
+        if model in current:
+            return OpResult(False, f"模型已存在: {name} 的列表中已有 {model}")
+        current.append(model)
+        layer = self.manager.upsert_provider(name, {"models": current})
+        return OpResult(True, f"已为 {name} 添加模型: {model}（写入 {layer} 配置。可用: /model {model} 切换）")
+
+    def remove_model(self, name: str, model: str) -> OpResult:
+        """把模型从 provider 的模型列表移除。"""
+        provider = self.manager.resolve_provider(name)
+        if provider is None:
+            return OpResult(False, f"未知 provider: {name}，可用: {', '.join(self.manager.provider_names()) or '（无）'}")
+        model = model.strip()
+        if model not in provider.models:
+            return OpResult(False, f"模型不在列表: {name} 的模型列表中没有 {model}")
+        remaining = [m for m in provider.models if m != model]
+        layer = self.manager.upsert_provider(name, {"models": remaining})
+        return OpResult(True, f"已从 {name} 移除模型: {model}（写入 {layer} 配置）")
+
+    # ---------- 校验 ----------
+
+    def _validate_fields(self, api_base: str, default_model: str) -> str | None:
+        err = validate_api_base(str(api_base))
+        if err:
+            return err
+        if not str(default_model).strip():
+            return "default_model 必填，不能为空（J7）"
+        return None

xg/config/providers.py

@@ -0,0 +1,46 @@
+"""Provider 数据模型与注册表。
+
+provider 不内置预设，全部由用户在配置（config.json 的 ``providers`` 节）
+中自定义 name / api_base / default_model / api_key 等；API Key 与 provider
+的一切配置都写入 config.json，不再走 ``.env``。能力参数（window / cache /
+vision）为可选预设值。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Provider:
+    name: str                 # 用户自定义名称
+    display_name: str
+    api_base: str             # base url（来自 config.json）
+    default_model: str
+    models: tuple[str, ...] = ()   # 该 provider 可切换的模型列表（config.json 的 providers.<name>.models）
+    api_key: str = ""         # API Key（明文存于 config.json 的 providers.<name>.api_key）
+    api_key_env: str = ""     # 兼容保留项：旧「环境变量读取」模式，现已不使用
+    context_window: int = 0   # 上下文窗口（token），用于预算控制
+    supports_cache: bool = False   # 是否支持 prompt cache（预留）
+    supports_vision: bool = False  # 是否支持图片输入（预留）
+
+
+class ProviderRegistry:
+    """用户自定义 provider 的注册表（无内置预设，初始为空）。"""
+
+    def __init__(self, providers: list[Provider] | None = None) -> None:
+        self._providers: dict[str, Provider] = {
+            p.name: p for p in (providers if providers is not None else [])
+        }
+
+    def get(self, name: str) -> Provider | None:
+        return self._providers.get(name)
+
+    def all(self) -> list[Provider]:
+        return list(self._providers.values())
+
+    def names(self) -> list[str]:
+        return list(self._providers)
+
+    def register(self, provider: Provider) -> None:
+        self._providers[provider.name] = provider

xg/config/settings.py

@@ -0,0 +1,258 @@
+"""运行时配置快照与加载。
+
+Settings 是解析后的运行时快照（provider / model / key / 窗口等），
+由 ConfigManager 按「默认 < 用户级 < 项目级 < 环境变量」合并产出。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from xg.config.manager import ConfigManager, ProviderNotConfigured
+from xg.config.skills import SkillConfigManager
+from xg.tui.i18n import UiLanguage, normalize_language
+
+
+@dataclass
+class Settings:
+    """运行时配置快照。provider / model 可被 /model 命令运行时修改。"""
+
+    provider: str = ""
+    api_base: str = ""
+    api_key: str = ""
+    model: str = ""
+    context_window: int = 128_000
+    tool_steps: int = 20
+    # LLM transient request retry policy.
+    llm_retry_enabled: bool = True
+    llm_max_retries: int = 2
+    llm_retry_base_delay: float = 1.0
+    llm_retry_max_delay: float = 8.0
+    llm_retry_jitter: float = 0.25
+    llm_retry_total_timeout: float = 30.0
+    llm_respect_retry_after: bool = True
+    # token 预算阈值：messages 估算 token 超过 window * budget_ratio 时终止循环
+    budget_ratio: float = 0.8
+    # 第 5 期：自动压缩时保留的最近完整对话轮次
+    context_keep_recent_turns: int = 4
+    # 第 5 期：摘要输出动态预留上限
+    context_summary_max_tokens: int = 4096
+    # 第 5 期：自动注入长期记忆的字符上限
+    memory_prompt_max_chars: int = 8000
+    # 第 5 期：单个 XG.md/XG.local.md 的读取字符上限
+    project_memory_max_chars: int = 32000
+    # 工具输出超出该字符数则截断，防止撑爆上下文
+    max_tool_output_chars: int = 20_000
+    # 并行工具执行并发数（第 3 期）
+    max_parallel: int = 4
+    # 单工具执行超时（秒，第 3 期）
+    tool_timeout: float = 120.0
+    # HITL 审批默认开启（第 3 期）
+    hitl: bool = True
+    # 计划模式（第 4 期）：子任务数上限
+    plan_max_subtasks: int = 12
+    # 计划模式：每个子任务的最大工具步数
+    plan_subtask_steps: int = 10
+    # 计划模式：计划级允许的子任务失败数（超出终止剩余批次）
+    plan_max_failures: int = 3
+    # 第 10 期：Team 协作限制
+    team_max_agents: int = 4
+    team_max_repairs: int = 2
+    # 第 V3 期：Plan/Team 任务自然语言断点续跑
+    # 单个任务最多自动恢复次数（防「失败→继续→失败」死循环消耗预算）
+    task_max_resumes: int = 3
+    # 恢复意图是否用 LLM 识别；关闭后仅用关键词白名单
+    resume_intent_llm: bool = True
+    # Reviewer 输出协议重试次数；与 API 重试和 Repairer 次数分离。
+    team_review_output_retries: int = 1
+    # Team Worker role-specific execution budgets. None keeps the legacy fallback.
+    team_researcher_steps: int | None = None
+    team_reviewer_steps: int | None = None
+    team_coder_steps: int | None = None
+    team_tester_steps: int | None = None
+    team_repairer_steps: int | None = None
+    team_synthesizer_steps: int | None = None
+    team_max_steps: int = 40
+    team_recovery_steps: int = 10
+    team_max_recoveries: int = 1
+    team_review: bool = True
+    # Textual TUI 最大刷新频率（第 6 期）
+    tui_refresh_fps: int = 20
+    # 第 7 期：MCP 客户端与资源限制
+    mcp_enabled: bool = True
+    mcp_startup_timeout: float = 15.0
+    mcp_request_timeout: float = 120.0
+    mcp_shutdown_timeout: float = 5.0
+    mcp_max_servers: int = 32
+    mcp_max_tools: int = 256
+    mcp_max_resources: int = 512
+    mcp_max_message_bytes: int = 2_097_152
+    mcp_resource_max_chars: int = 32_000
+    mcp_resource_total_chars: int = 64_000
+    mcp_log_lines: int = 200
+    # 第 8 期：只读 Web 能力限制
+    web_enabled: bool = True
+    web_search_provider: str = "none"
+    web_timeout: float = 15.0
+    web_max_results: int = 5
+    web_max_response_bytes: int = 2_097_152
+    web_fetch_max_chars: int = 32_000
+    web_max_redirects: int = 5
+    web_rate_limit_per_minute: int = 30
+    # 第 9 期：Skill 索引和按需加载限制
+    skills_enabled: bool = True
+    skills_max_index_items: int = 20
+    skills_max_index_chars: int = 4_096
+    skills_max_chars: int = 32_000
+    skills_max_reference_chars: int = 16_000
+    skills_max_loaded_chars: int = 64_000
+    # 输入历史：只影响本地 Composer/inline 输入，不进入 Agent 上下文
+    input_history_enabled: bool = True
+    input_history_persist: bool = True
+    input_history_max_entries: int = 100
+    input_history_max_chars: int = 8_000
+    input_history_max_bytes: int = 1_048_576
+    extra: dict[str, str] = field(default_factory=dict)
+    # Inspector UI language; this does not affect Agent prompts or responses.
+    ui_language: UiLanguage = "en"
+    # SmartRouter（phase-01）：智能路由开关，默认关闭；开启后每轮输入自动路由换档。
+    # 路由结果只改内存中的 provider/model，不写回 active_provider/active_model。
+    smart_router_enabled: bool = False
+    # 开启前的手动模型快照 (provider, model)，/smartRouter off 时恢复；未开启时为 None。
+    smart_router_saved: tuple[str, str] | None = None
+    # base provider 未配置时置 True（active() 触发 ProviderNotConfigured），供启动提示。
+    provider_missing: bool = False
+
+    @property
+    def token_budget(self) -> int:
+        return int(self.context_window * self.budget_ratio)
+
+    def estimate_tokens(self, text: str) -> int:
+        """字符近似估算：ASCII 约 4 字符/token，非 ASCII（如中文）约 1 字符/token。"""
+        if not text:
+            return 0
+        ascii_chars = sum(1 for ch in text if ord(ch) < 128)
+        non_ascii = len(text) - ascii_chars
+        return ascii_chars // 4 + non_ascii
+
+
+def load_settings(manager: ConfigManager | None = None) -> Settings:
+    """加载配置并产出运行时快照。"""
+    manager = manager or ConfigManager()
+    try:
+        active = manager.active()
+        provider_missing = False
+    except ProviderNotConfigured:
+        active = None
+        provider_missing = True
+    skill_config = SkillConfigManager(
+        user_dir=manager.user_dir,
+        project_root=manager.project_dir.parent,
+        env=manager.env,
+    ).load()
+    return Settings(
+        provider=active.provider_name if active else "",
+        api_base=active.api_base if active else "",
+        api_key=active.api_key if active else "",
+        model=active.model if active else "",
+        context_window=active.context_window if active else 128_000,
+        provider_missing=provider_missing,
+        tool_steps=_get_int(manager.env, "XG_TOOL_STEPS", 20),
+        llm_retry_enabled=manager.env.get("XG_LLM_RETRY_ENABLED", "on").lower() not in ("off", "0", "false"),
+        llm_max_retries=max(0, _get_int(manager.env, "XG_LLM_MAX_RETRIES", 2)),
+        llm_retry_base_delay=max(0.0, _get_float(manager.env, "XG_LLM_RETRY_BASE_DELAY", 1.0)),
+        llm_retry_max_delay=max(0.0, _get_float(manager.env, "XG_LLM_RETRY_MAX_DELAY", 8.0)),
+        llm_retry_jitter=_clamp_float(_get_float(manager.env, "XG_LLM_RETRY_JITTER", 0.25), 0.0, 1.0),
+        llm_retry_total_timeout=max(0.0, _get_float(manager.env, "XG_LLM_RETRY_TOTAL_TIMEOUT", 30.0)),
+        llm_respect_retry_after=manager.env.get("XG_LLM_RESPECT_RETRY_AFTER", "on").lower() not in ("off", "0", "false"),
+        budget_ratio=_clamp_float(_get_float(manager.env, "XG_CONTEXT_BUDGET_RATIO", 0.8), 0.5, 0.9),
+        context_keep_recent_turns=max(0, _get_int(manager.env, "XG_CONTEXT_KEEP_RECENT_TURNS", 4)),
+        context_summary_max_tokens=max(512, _get_int(manager.env, "XG_CONTEXT_SUMMARY_MAX_TOKENS", 4096)),
+        memory_prompt_max_chars=max(256, _get_int(manager.env, "XG_MEMORY_PROMPT_MAX_CHARS", 8000)),
+        project_memory_max_chars=max(256, _get_int(manager.env, "XG_PROJECT_MEMORY_MAX_CHARS", 32000)),
+        max_parallel=_get_int(manager.env, "XG_MAX_PARALLEL", 4),
+        tool_timeout=_get_float(manager.env, "XG_TOOL_TIMEOUT", 120.0),
+        hitl=manager.env.get("XG_HITL", "on").lower() not in ("off", "0", "false"),
+        plan_max_subtasks=_get_int(manager.env, "XG_PLAN_MAX_SUBTASKS", 12),
+        plan_subtask_steps=_get_int(manager.env, "XG_PLAN_SUBTASK_STEPS", 10),
+        plan_max_failures=_get_int(manager.env, "XG_PLAN_MAX_FAILURES", 3),
+        task_max_resumes=max(1, _get_int(manager.env, "XG_TASK_MAX_RESUMES", 3)),
+        resume_intent_llm=manager.env.get("XG_RESUME_INTENT_LLM", "on").lower() not in ("off", "0", "false"),
+        team_max_agents=max(1, _get_int(manager.env, "XG_TEAM_MAX_AGENTS", 4)),
+        team_max_repairs=max(0, _get_int(manager.env, "XG_TEAM_MAX_REPAIRS", 2)),
+        team_review_output_retries=max(0, _get_int(manager.env, "XG_TEAM_REVIEW_OUTPUT_RETRIES", 1)),
+        team_researcher_steps=_get_optional_positive_int(manager.env, "XG_TEAM_RESEARCHER_STEPS"),
+        team_reviewer_steps=_get_optional_positive_int(manager.env, "XG_TEAM_REVIEWER_STEPS"),
+        team_coder_steps=_get_optional_positive_int(manager.env, "XG_TEAM_CODER_STEPS"),
+        team_tester_steps=_get_optional_positive_int(manager.env, "XG_TEAM_TESTER_STEPS"),
+        team_repairer_steps=_get_optional_positive_int(manager.env, "XG_TEAM_REPAIRER_STEPS"),
+        team_synthesizer_steps=_get_optional_positive_int(manager.env, "XG_TEAM_SYNTHESIZER_STEPS"),
+        team_max_steps=max(1, _get_int(manager.env, "XG_TEAM_MAX_STEPS", 40)),
+        team_recovery_steps=max(1, _get_int(manager.env, "XG_TEAM_RECOVERY_STEPS", 10)),
+        team_max_recoveries=max(0, _get_int(manager.env, "XG_TEAM_MAX_RECOVERIES", 1)),
+        team_review=manager.env.get("XG_TEAM_REVIEW", "on").lower() not in ("off", "0", "false"),
+        tui_refresh_fps=max(5, min(60, _get_int(manager.env, "XG_TUI_REFRESH_FPS", 20))),
+        ui_language=normalize_language(manager.get_ui_language()),
+        mcp_enabled=manager.env.get("XG_MCP_ENABLED", "on").lower() not in ("off", "0", "false"),
+        mcp_startup_timeout=max(0.1, _get_float(manager.env, "XG_MCP_STARTUP_TIMEOUT", 15.0)),
+        mcp_request_timeout=max(0.1, _get_float(manager.env, "XG_MCP_REQUEST_TIMEOUT", 120.0)),
+        mcp_shutdown_timeout=max(0.1, _get_float(manager.env, "XG_MCP_SHUTDOWN_TIMEOUT", 5.0)),
+        mcp_max_servers=max(1, _get_int(manager.env, "XG_MCP_MAX_SERVERS", 32)),
+        mcp_max_tools=max(1, _get_int(manager.env, "XG_MCP_MAX_TOOLS", 256)),
+        mcp_max_resources=max(1, _get_int(manager.env, "XG_MCP_MAX_RESOURCES", 512)),
+        mcp_max_message_bytes=max(1024, _get_int(manager.env, "XG_MCP_MAX_MESSAGE_BYTES", 2_097_152)),
+        mcp_resource_max_chars=max(256, _get_int(manager.env, "XG_MCP_RESOURCE_MAX_CHARS", 32_000)),
+        mcp_resource_total_chars=max(256, _get_int(manager.env, "XG_MCP_RESOURCE_TOTAL_CHARS", 64_000)),
+        mcp_log_lines=max(10, _get_int(manager.env, "XG_MCP_LOG_LINES", 200)),
+        web_enabled=manager.env.get("XG_WEB_ENABLED", "on").lower() not in ("off", "0", "false"),
+        web_search_provider=manager.env.get("XG_WEB_SEARCH_PROVIDER", "none").lower() or "none",
+        web_timeout=max(0.1, _get_float(manager.env, "XG_WEB_TIMEOUT", 15.0)),
+        web_max_results=max(1, min(10, _get_int(manager.env, "XG_WEB_MAX_RESULTS", 5))),
+        web_max_response_bytes=max(1024, _get_int(manager.env, "XG_WEB_MAX_RESPONSE_BYTES", 2_097_152)),
+        web_fetch_max_chars=max(256, _get_int(manager.env, "XG_WEB_FETCH_MAX_CHARS", 32_000)),
+        web_max_redirects=max(0, _get_int(manager.env, "XG_WEB_MAX_REDIRECTS", 5)),
+        web_rate_limit_per_minute=max(1, _get_int(manager.env, "XG_WEB_RATE_LIMIT_PER_MINUTE", 30)),
+        skills_enabled=skill_config.enabled,
+        skills_max_index_items=skill_config.max_index_items,
+        skills_max_index_chars=skill_config.max_index_chars,
+        skills_max_chars=skill_config.max_skill_chars,
+        skills_max_reference_chars=skill_config.max_reference_chars,
+        skills_max_loaded_chars=skill_config.max_loaded_chars,
+        input_history_enabled=manager.env.get("XG_INPUT_HISTORY_ENABLED", "on").lower() not in ("off", "0", "false"),
+        input_history_persist=manager.env.get("XG_INPUT_HISTORY_PERSIST", "on").lower() not in ("off", "0", "false"),
+        input_history_max_entries=max(1, _get_int(manager.env, "XG_INPUT_HISTORY_MAX_ENTRIES", 100)),
+        input_history_max_chars=max(256, _get_int(manager.env, "XG_INPUT_HISTORY_MAX_CHARS", 8_000)),
+        input_history_max_bytes=max(4_096, _get_int(manager.env, "XG_INPUT_HISTORY_MAX_BYTES", 1_048_576)),
+        smart_router_enabled=bool(manager.smart_router_config().get("enabled", False)),
+    )
+
+
+def _get_float(env: dict[str, str], name: str, default: float) -> float:
+    raw = env.get(name, "")
+    try:
+        return float(raw) if raw else default
+    except ValueError:
+        return default
+
+
+def _get_int(env: dict[str, str], name: str, default: int) -> int:
+    raw = env.get(name, "")
+    try:
+        return int(raw) if raw else default
+    except ValueError:
+        return default
+
+
+def _get_optional_positive_int(env: dict[str, str], name: str) -> int | None:
+    raw = env.get(name, "")
+    if not raw:
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        return None
+    return value if value > 0 else None
+
+
+def _clamp_float(value: float, low: float, high: float) -> float:
+    return max(low, min(high, value))

xg/config/skills.py

@@ -0,0 +1,100 @@
+"""User/project Skill configuration and environment overrides."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from xg.skill.models import SkillConfig
+
+
+SKILLS_CONFIG_FILE = "skills.json"
+
+
+def _merge(base: dict, override: dict) -> dict:
+    result = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = _merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+class SkillConfigManager:
+    def __init__(self, *, user_dir: str | Path | None = None,
+                 project_root: str | Path | None = None,
+                 env: dict[str, str] | None = None) -> None:
+        self.user_dir = Path(user_dir) if user_dir else Path.home() / ".xg"
+        self.project_root = (Path(project_root) if project_root else Path.cwd()).resolve()
+        self.user_config_path = self.user_dir / SKILLS_CONFIG_FILE
+        self.project_config_path = self.project_root / ".xg" / SKILLS_CONFIG_FILE
+        self.env = env if env is not None else os.environ
+        self.errors: list[str] = []
+
+    def _read(self, path: Path) -> dict:
+        if not path.is_file():
+            return {}
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            self.errors.append(f"{path}: JSON 配置读取失败")
+            return {}
+        if not isinstance(data, dict):
+            self.errors.append(f"{path}: 顶层必须是 JSON 对象")
+            return {}
+        return data
+
+    @staticmethod
+    def _bool(value: Any, default: bool) -> bool:
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return value.lower() not in {"off", "false", "0", "no"}
+        return default
+
+    @staticmethod
+    def _int(value: Any, default: int, minimum: int = 1) -> int:
+        try:
+            return max(minimum, int(value))
+        except (TypeError, ValueError):
+            return default
+
+    def load(self) -> SkillConfig:
+        self.errors.clear()
+        user = self._read(self.user_config_path)
+        project = self._read(self.project_config_path)
+        raw = _merge(user, project)
+        env = self.env
+        return SkillConfig(
+            enabled=self._bool(env.get("XG_SKILLS_ENABLED", raw.get("enabled", True)), True),
+            default_enabled=self._bool(raw.get("default_enabled", True), True),
+            max_index_items=self._int(env.get("XG_SKILLS_MAX_INDEX_ITEMS", raw.get("max_index_items", 20)), 20),
+            max_index_chars=self._int(env.get("XG_SKILLS_MAX_INDEX_CHARS", raw.get("max_index_chars", 4_096)), 4_096),
+            max_skill_chars=self._int(env.get("XG_SKILLS_MAX_CHARS", raw.get("max_skill_chars", 32_000)), 32_000),
+            max_reference_chars=self._int(env.get("XG_SKILLS_MAX_REFERENCE_CHARS", raw.get("max_reference_chars", 16_000)), 16_000),
+            max_loaded_chars=self._int(env.get("XG_SKILLS_MAX_LOADED_CHARS", raw.get("max_loaded_chars", 64_000)), 64_000),
+            max_references=self._int(raw.get("max_references", 8), 8),
+        )
+
+    def enabled_overrides(self) -> dict[str, bool]:
+        raw = _merge(self._read(self.user_config_path), self._read(self.project_config_path))
+        enabled = raw.get("enabled", {})
+        return {str(name): bool(value) for name, value in enabled.items()} if isinstance(enabled, dict) else {}
+
+    def set_enabled(self, name: str, enabled: bool, *, project: bool = True) -> None:
+        path = self.project_config_path if project else self.user_config_path
+        data = self._read(path)
+        mapping = data.setdefault("enabled", {})
+        if not isinstance(mapping, dict):
+            mapping = {}
+            data["enabled"] = mapping
+        mapping[name] = bool(enabled)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def load_skill_config(*, user_dir=None, project_root=None, env=None) -> SkillConfig:
+    return SkillConfigManager(user_dir=user_dir, project_root=project_root, env=env).load()