agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk/configs/env_registry.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EnvVarSpec:
+    name: str
+    module: str
+    purpose: str
+    default: str = ""
+    sensitive: bool = False
+
+
+_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
+    EnvVarSpec("KSADK_ADK_SESSION_BACKEND", "sessions", "ADK-native session backend selector."),
+    EnvVarSpec("KSADK_ADK_SESSION_PATH", "sessions", "ADK-native SQLite session database path."),
+    EnvVarSpec("KSADK_ADK_SESSION_URL", "sessions", "ADK-native database session URL.", sensitive=True),
+    EnvVarSpec("KSADK_AICP_ENDPOINT_MODE", "platform", "AICP endpoint selection mode: auto, detect, inner, or public."),
+    EnvVarSpec("KSADK_ALLOWED_SUFFIXES", "builders", "Internal code package allowed suffix constant."),
+    EnvVarSpec(
+        "KSADK_ATTACHMENT_OCR_RUNTIME_REQUIREMENTS",
+        "builders",
+        "Internal bundled attachment OCR requirement constant.",
+    ),
+    EnvVarSpec(
+        "KSADK_ATTACHMENT_RUNTIME_REQUIREMENTS",
+        "builders",
+        "Internal bundled attachment requirement constant.",
+    ),
+    EnvVarSpec(
+        "KSADK_BUILD_ENABLE_ATTACHMENT_OCR",
+        "builders",
+        "Include local attachment OCR dependencies in source builds.",
+        "false",
+    ),
+    EnvVarSpec(
+        "KSADK_BUILD_ENABLE_MCP",
+        "builders",
+        "Include LangChain MCP adapter dependencies in source/container builds.",
+        "false",
+    ),
+    EnvVarSpec(
+        "KSADK_BUILD_ENABLE_POSTGRES_SESSION",
+        "builders",
+        "Include asyncpg dependency for PostgreSQL session backend in source/container builds.",
+        "false",
+    ),
+    EnvVarSpec(
+        "KSADK_BUILD_PIP_INSTALL_TIMEOUT_SECONDS",
+        "builders",
+        "pip install timeout seconds for source builds.",
+        "2700",
+    ),
+    EnvVarSpec(
+        "KSADK_BUILTIN_TOOLS_MODE",
+        "toolsets",
+        "Built-in tool injection mode: off, dispatcher, focused, or deferred.",
+        "off",
+    ),
+    EnvVarSpec(
+        "KSADK_BUILTIN_TOOLS_PROFILE",
+        "toolsets",
+        "Built-in tool profile selector, such as default or coding.",
+        "default",
+    ),
+    EnvVarSpec("KSADK_CHECKPOINT_BACKEND", "sessions", "LangGraph checkpoint backend selector.", "local"),
+    EnvVarSpec("KSADK_CHECKPOINT_PATH", "sessions", "Local SQLite checkpoint database path."),
+    EnvVarSpec("KSADK_COMMAND_", "sandbox", "Internal prefix for command policy environment controls."),
+    EnvVarSpec("KSADK_COMMAND_CWD", "sandbox", "Current working directory exported to command policy checks."),
+    EnvVarSpec("KSADK_COMPACT_MICROCOMPACT_COLD_ROUNDS", "runtime", "Groups older than this many rounds are compacted by L3 microcompact.", "3"),
+    EnvVarSpec("KSADK_COMPACT_MICROCOMPACT_ENABLED", "runtime", "Enable L3 microcompact deterministic cold-group compression in compaction pipeline.", "true"),
+    EnvVarSpec("KSADK_COMPACT_SNIP_ENABLED", "runtime", "Enable L2 snip deterministic redundancy removal in compaction pipeline.", "true"),
+    EnvVarSpec(
+        "KSADK_CORE_RUNTIME_REQUIREMENTS",
+        "builders",
+        "Internal bundled core requirement constant.",
+    ),
+    EnvVarSpec("KSADK_ENABLE_MCP_TOOLS", "mcp_runtime", "Enable ADK MCP tool injection.", "1"),
+    EnvVarSpec("KSADK_EVENTS_TABLE", "sessions", "Internal SQLite events table constant."),
+    EnvVarSpec("KSADK_FEISHU_APP_ID", "cli", "Feishu helper app id used by OpenClaw diagnostics."),
+    EnvVarSpec("KSADK_FEISHU_RESULT_PATH", "cli", "Feishu helper result file path."),
+    EnvVarSpec("KSADK_GLOBAL_CONFIG_ENV_KEYS", "cli", "Internal marker for env vars injected from global config."),
+    EnvVarSpec("KSADK_KB", "knowledge_base", "AICP knowledge-base connection prefix."),
+    EnvVarSpec("KSADK_KB_ACCESS_KEY", "knowledge_base", "Knowledge-base API access key.", sensitive=True),
+    EnvVarSpec("KSADK_KB_DATASET_ID", "knowledge_base", "Knowledge-base dataset id."),
+    EnvVarSpec("KSADK_KB_ENDPOINT", "knowledge_base", "Knowledge-base API endpoint.", "aicp.api.ksyun.com"),
+    EnvVarSpec("KSADK_KB_REGION", "knowledge_base", "Knowledge-base region.", "cn-beijing-6"),
+    EnvVarSpec("KSADK_KB_RERANKING_ENABLE", "knowledge_base", "Enable knowledge-base reranking.", "false"),
+    EnvVarSpec("KSADK_KB_SCORE_THRESHOLD", "knowledge_base", "Knowledge-base score threshold.", "0.0"),
+    EnvVarSpec("KSADK_KB_SEARCH_METHOD", "knowledge_base", "Knowledge-base search method.", "intelligence_search"),
+    EnvVarSpec("KSADK_KB_SECRET_KEY", "knowledge_base", "Knowledge-base API secret key.", sensitive=True),
+    EnvVarSpec("KSADK_KB_TOP_K", "knowledge_base", "Knowledge-base retrieval result count.", "5"),
+    EnvVarSpec("KSADK_LANGGRAPH_CHECKPOINT_DSN", "sessions", "LangGraph PostgreSQL checkpoint DSN.", sensitive=True),
+    EnvVarSpec("KSADK_LOCAL_SKILLS_DIR", "skills", "Local directory containing extracted Skill packages."),
+    EnvVarSpec("KSADK_LTM", "memory", "AICP long-term-memory connection prefix."),
+    EnvVarSpec("KSADK_LTM_ACCESS_KEY", "memory", "Long-term-memory API access key.", sensitive=True),
+    EnvVarSpec("KSADK_LTM_AGENT_ID", "memory", "Long-term-memory agent id."),
+    EnvVarSpec("KSADK_LTM_APP_NAME", "memory", "Long-term-memory application name override."),
+    EnvVarSpec(
+        "KSADK_LTM_AUTO_SAVE",
+        "memory",
+        "Auto-save completed conversation turns to SDK long-term memory.",
+        "true when KSADK_LTM_BACKEND=sdk and KSADK_LTM_NAMESPACE is set",
+    ),
+    EnvVarSpec("KSADK_LTM_BACKEND", "memory", "Long-term-memory backend selector.", "local"),
+    EnvVarSpec("KSADK_LTM_ENDPOINT", "memory", "Long-term-memory API endpoint."),
+    EnvVarSpec("KSADK_LTM_HTTP_TOKEN", "memory", "HTTP long-term-memory bearer token.", sensitive=True),
+    EnvVarSpec("KSADK_LTM_HTTP_URL", "memory", "HTTP long-term-memory service URL.", sensitive=True),
+    EnvVarSpec("KSADK_LTM_INDEX", "memory", "Long-term-memory index name."),
+    EnvVarSpec("KSADK_LTM_NAMESPACE", "memory", "Long-term-memory memory collection id."),
+    EnvVarSpec("KSADK_LTM_REGION", "memory", "Long-term-memory region.", "cn-beijing-6"),
+    EnvVarSpec("KSADK_LTM_SCENE_ID", "memory", "Long-term-memory scene id.", "_sys_general"),
+    EnvVarSpec("KSADK_LTM_SCHEME", "memory", "Long-term-memory API scheme.", "https"),
+    EnvVarSpec("KSADK_LTM_SECRET_KEY", "memory", "Long-term-memory API secret key.", sensitive=True),
+    EnvVarSpec("KSADK_LTM_TOP_K", "memory", "Long-term-memory retrieval result count.", "5"),
+    EnvVarSpec(
+        "KSADK_MCP_RUNTIME_REQUIREMENTS",
+        "builders",
+        "Internal bundled MCP adapter runtime requirement constant.",
+    ),
+    EnvVarSpec("KSADK_MCP_KEY", "mcp_runtime", "MCP service API key (also reused by ksyun web search provider).", sensitive=True),
+    EnvVarSpec("KSADK_MCP_SERVERS", "mcp_runtime", "JSON array of MCP server configs.", sensitive=True),
+    EnvVarSpec("KSADK_MEMORY_BACKEND", "memory", "Generic memory backend selector.", "memory"),
+    EnvVarSpec("KSADK_MEMORY_PREFIX", "memory", "Generic memory key prefix.", "ksadk:memory:"),
+    EnvVarSpec("KSADK_MEMORY_TTL", "memory", "Generic memory default TTL seconds."),
+    EnvVarSpec("KSADK_MEMORY_URL", "memory", "Generic memory backend URL.", sensitive=True),
+    EnvVarSpec("KSADK_PG_EVENTS_TABLE", "sessions", "Internal PostgreSQL events table constant."),
+    EnvVarSpec("KSADK_PG_SESSIONS_TABLE", "sessions", "Internal PostgreSQL sessions table constant."),
+    EnvVarSpec("KSADK_PG_STATES_TABLE", "sessions", "Internal PostgreSQL states table constant."),
+    EnvVarSpec(
+        "KSADK_POSTGRES_SESSION_REQUIREMENTS",
+        "builders",
+        "Internal bundled PostgreSQL session runtime requirement constant.",
+    ),
+    EnvVarSpec("KSADK_PROJECT_DIR", "sessions", "Project root used for local session/workspace state."),
+    EnvVarSpec("KSADK_PUBLIC_SKILL_ALLOWLIST", "skills", "Comma-separated public Skill names to load; empty loads all public skills."),
+    EnvVarSpec("KSADK_PUBLIC_SKILL_SPACE_IDS", "skills", "Comma-separated public Skill Space ids appended after user spaces."),
+    EnvVarSpec("KSADK_RESPONSES_SESSION_HEADER", "runners", "Header name for remote Responses session propagation."),
+    EnvVarSpec("KSADK_RUNTIME_PORT", "cli", "Runtime HTTP port exported to template runtimes.", "8080"),
+    EnvVarSpec("KSADK_RUNTIME_REQUIREMENTS", "builders", "Internal bundled runtime requirements constant."),
+    EnvVarSpec(
+        "KSADK_ALLOW_POD_PROCESS_TOOLS",
+        "sandbox",
+        "Explicit opt-in required before pod_process sandbox tools are enabled.",
+        "false",
+    ),
+    EnvVarSpec("KSADK_MAX_TURNS", "runtime", "Maximum conversation turns before runtime circuit breaker opens.", "0"),
+    EnvVarSpec("KSADK_MAX_TOOL_CALLS", "runtime", "Maximum tool calls before runtime circuit breaker opens.", "0"),
+    EnvVarSpec(
+        "KSADK_MAX_CONSECUTIVE_TOOL_FAILURES",
+        "runtime",
+        "Maximum consecutive failed tool results before runtime circuit breaker opens.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_MAX_CONSECUTIVE_APPROVAL_DENIALS",
+        "runtime",
+        "Maximum consecutive approval denials before runtime circuit breaker opens.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_MAX_CONSECUTIVE_COMPACT_FAILURES",
+        "runtime",
+        "Maximum consecutive compaction failures before runtime circuit breaker opens.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_MAX_CONSECUTIVE_SEMANTIC_FAILURES",
+        "runtime",
+        "Consecutive semantic LLM compaction failures before skipping semantic and using extractive; 0 disables the breaker (opt-in, default off to avoid permanent semantic disable from transient failures).",
+        "0",
+    ),
+    EnvVarSpec("KSADK_SAFE_", "tools", "Internal prefix for tool safety policy environment controls."),
+    EnvVarSpec("KSADK_SANDBOX_ALLOW_INTERNET_ACCESS", "sandbox", "Allow remote sandbox internet access.", "true"),
+    EnvVarSpec("KSADK_SANDBOX_BACKEND", "sandbox", "Generic sandbox backend selector.", "e2b"),
+    EnvVarSpec("KSADK_SANDBOX_IDLE_TTL_SECONDS", "sandbox", "Idle TTL seconds before sandbox registry reclaims inactive sessions; 0 disables idle reclamation.", "300"),
+    EnvVarSpec("KSADK_SANDBOX_MAX_SESSIONS", "sandbox", "Maximum active sandbox registry sessions.", "0"),
+    EnvVarSpec("KSADK_SANDBOX_SESSION_ID", "sandbox", "Explicit sandbox registry session id override."),
+    EnvVarSpec("KSADK_SANDBOX_STARTUP_RETRY_ATTEMPTS", "sandbox", "Sandbox startup readiness retry attempts.", "6"),
+    EnvVarSpec("KSADK_SANDBOX_STARTUP_RETRY_DELAY", "sandbox", "Sandbox startup readiness initial retry delay seconds.", "0.2"),
+    EnvVarSpec("KSADK_SANDBOX_SWEEP_INTERVAL_SECONDS", "sandbox", "Background sweep interval seconds for sandbox registry; 0 disables the background sweeper.", "60"),
+    EnvVarSpec("KSADK_SANDBOX_SYNC_MAX_FILE_BYTES", "sandbox", "Maximum single file size for workspace sync into sandbox."),
+    EnvVarSpec("KSADK_SANDBOX_SYNC_MAX_FILES", "sandbox", "Maximum file count for workspace sync into sandbox."),
+    EnvVarSpec("KSADK_SANDBOX_SYNC_MAX_TOTAL_BYTES", "sandbox", "Maximum total bytes for workspace sync into sandbox."),
+    EnvVarSpec("KSADK_SANDBOX_TEMPLATE_ID", "sandbox", "Sandbox console template id."),
+    EnvVarSpec("KSADK_SANDBOX_TIMEOUT", "sandbox", "Sandbox session timeout seconds.", "600"),
+    EnvVarSpec("KSADK_SANDBOX_TTL_SECONDS", "sandbox", "Hard TTL seconds for sandbox registry sessions.", "900"),
+    EnvVarSpec("KSADK_SANDBOX_TYPE", "sandbox", "Sandbox type: aio, code, browser, or private.", "aio"),
+    EnvVarSpec("KSADK_SELECTED_SKILL_NAMES", "skills", "Comma-separated Skill names selected by the outer agent."),
+    EnvVarSpec("KSADK_SESSIONS_TABLE", "sessions", "Internal SQLite sessions table constant."),
+    EnvVarSpec("KSADK_SESSION_BACKEND", "sessions", "Conversation session backend selector.", "local"),
+    EnvVarSpec("KSADK_SESSION_CONNECT_TIMEOUT", "sessions", "Conversation PostgreSQL connection timeout seconds.", "5"),
+    EnvVarSpec("KSADK_SESSION_DSN", "sessions", "Conversation session database DSN.", sensitive=True),
+    EnvVarSpec("KSADK_SESSION_NAMESPACE", "sessions", "Conversation session namespace."),
+    EnvVarSpec("KSADK_SESSION_PATH", "sessions", "Conversation local SQLite database path."),
+    EnvVarSpec("KSADK_SESSION_PG_CONNECT_TIMEOUT", "sessions", "Legacy PostgreSQL session connection timeout seconds.", "5"),
+    EnvVarSpec("KSADK_SKILLS_MODE", "skills", "Skill loading mode: auto, local, or sandbox.", "auto"),
+    EnvVarSpec(
+        "KSADK_SKILL_ALLOW_HASH_MISMATCH",
+        "skills",
+        "Allow loading legacy Skill archives when ContentHash verification fails.",
+        "false",
+    ),
+    EnvVarSpec("KSADK_SKILL_ARTIFACT_PROJECT", "skills", "Default artifact project name for the minimal Skill Runtime agent.", "ksadk-artifact"),
+    EnvVarSpec("KSADK_SKILL_CACHE_DIR", "skills", "Skill package download and extraction cache directory."),
+    EnvVarSpec("KSADK_SKILL_MANIFEST_LIMIT", "skills", "Maximum remote Skill manifests injected into agent instructions.", "30"),
+    EnvVarSpec("KSADK_SKILL_MANIFEST_TIMEOUT", "skills", "Remote Skill manifest listing timeout seconds.", "5"),
+    EnvVarSpec("KSADK_SKILL_OUTPUT_DIR", "skills", "Output directory exposed to local Skill workflow scripts."),
+    EnvVarSpec("KSADK_SKILL_ROOT_DIR", "skills", "Root directory of the Skill currently executed by the local workflow runner."),
+    EnvVarSpec("KSADK_SKILL_RUNTIME_AGENT_PATH", "skills", "Local process Skill Runtime agent path."),
+    EnvVarSpec("KSADK_SKILL_RUNTIME_ALLOW_INTERNET_ACCESS", "skills", "Allow remote Skill Runtime internet access.", "true"),
+    EnvVarSpec("KSADK_SKILL_RUNTIME_BACKEND", "skills", "Skill Runtime backend selector.", "disabled"),
+    EnvVarSpec("KSADK_SKILL_RUNTIME_TEMPLATE_ID", "skills", "Skill Runtime backend template id."),
+    EnvVarSpec("KSADK_SKILL_RUNTIME_TIMEOUT", "skills", "Skill Runtime workflow timeout seconds.", "900"),
+    EnvVarSpec("KSADK_SKILL_SERVICE", "skills", "Skill Service AICP connection environment prefix."),
+    EnvVarSpec("KSADK_SKILL_SERVICE_ACCESS_KEY", "skills", "Skill Service KOP access key.", sensitive=True),
+    EnvVarSpec("KSADK_SKILL_SERVICE_ACCOUNT_ID", "skills", "Skill Service tenant account id."),
+    EnvVarSpec("KSADK_SKILL_SERVICE_API_VERSION", "skills", "Skill Service KOP API version.", "2024-06-12"),
+    EnvVarSpec("KSADK_SKILL_SERVICE_ENDPOINT", "skills", "Skill Service AICP endpoint override."),
+    EnvVarSpec("KSADK_SKILL_SERVICE_REGION", "skills", "Skill Service KOP region.", "cn-beijing-6"),
+    EnvVarSpec("KSADK_SKILL_SERVICE_SCHEME", "skills", "Skill Service AICP URL scheme override."),
+    EnvVarSpec("KSADK_SKILL_SERVICE_SECRET_KEY", "skills", "Skill Service KOP secret key.", sensitive=True),
+    EnvVarSpec("KSADK_SKILL_SERVICE_SIGN_SERVICE", "skills", "Skill Service KOP signing service.", "aicp"),
+    EnvVarSpec("KSADK_SKILL_SERVICE_TOKEN", "skills", "Skill Service bearer token.", sensitive=True),
+    EnvVarSpec("KSADK_SKILL_SERVICE_URL", "skills", "Skill Service API base URL."),
+    EnvVarSpec("KSADK_SKILL_SPACE_IDS", "skills", "Comma-separated Skill Space ids."),
+    EnvVarSpec("KSADK_SKILL_WORKDIR", "skills", "Working directory for the minimal Skill Runtime agent."),
+    EnvVarSpec("KSADK_STATES_TABLE", "sessions", "Internal SQLite states table constant."),
+    EnvVarSpec("KSADK_STM_BACKEND", "sessions", "Short-term-memory session backend selector."),
+    EnvVarSpec("KSADK_STM_DB_PATH", "sessions", "Legacy short-term-memory SQLite path."),
+    EnvVarSpec("KSADK_STM_DB_URL", "sessions", "Legacy short-term-memory database URL.", sensitive=True),
+    EnvVarSpec("KSADK_STM_PATH", "sessions", "Short-term-memory SQLite path."),
+    EnvVarSpec("KSADK_STM_URL", "sessions", "Short-term-memory database URL.", sensitive=True),
+    EnvVarSpec("KSADK_TENANT_ID", "sessions", "Tenant id used for session namespace scoping."),
+    EnvVarSpec(
+        "KSADK_TERMINAL_EXEC_SUBCOMMAND_ALLOWLIST",
+        "terminal",
+        "Comma-separated remote terminal exec prefixes appended to the default allowlist; use * to allow all.",
+    ),
+    EnvVarSpec("KSADK_TOOL_APPROVAL_MODE", "tools", "Built-in tool approval mode: off or strict.", "off"),
+    EnvVarSpec("KSADK_TOOL_RESULT_DIR", "tools", "Directory used to persist oversized tool results."),
+    EnvVarSpec("KSADK_TOOL_RESULT_MAX_CHARS", "tools", "Maximum inline characters for budgeted tool outputs."),
+    EnvVarSpec("KSADK_TOOL_RESULT_PERSIST_THRESHOLD_CHARS", "tools", "Character threshold for persisting tool outputs."),
+    EnvVarSpec("KSADK_TOOL_RESULT_PREVIEW_CHARS", "tools", "Preview character count for persisted tool outputs."),
+    EnvVarSpec("KSADK_UPDATED_AT", "configs", "Internal config update timestamp field."),
+    EnvVarSpec("KSADK_VERSION", "configs", "Internal config version field."),
+    EnvVarSpec("KSADK_UI_BUNDLE_PATH", "web", "Custom agent UI bundle path relative to project root."),
+    EnvVarSpec("KSADK_UI_PATH", "web", "Custom agent UI mount path."),
+    EnvVarSpec("KSADK_UI_PROFILE", "web", "Agent UI profile selector, such as builtin or custom."),
+    EnvVarSpec("KSADK_UI_URL", "web", "External custom agent UI URL."),
+    EnvVarSpec("KSADK_WEB_CACHE_DIR", "web", "Directory used by hosted Web UI static asset sync cache."),
+    EnvVarSpec("KSADK_WEB_PACKAGE", "web", "KsADK Web npm package name.", "@kingsoftcloud/ksadk-web"),
+    EnvVarSpec("KSADK_WEB_RELEASE_URL", "web", "Optional KsADK Web tarball URL fallback."),
+    EnvVarSpec("KSADK_WEB_SEARCH_API_KEY", "web", "HTTP web search provider API key.", sensitive=True),
+    EnvVarSpec("KSADK_WEB_SEARCH_BASE_URL", "web", "HTTP web search provider base URL."),
+    EnvVarSpec("KSADK_WEB_SEARCH_PROVIDER", "web", "Web search provider selector, such as fake, http, or ksyun."),
+    EnvVarSpec("KSADK_WEB_SEARCH_SCOPE", "web", "ksyun provider search scope: webpage/document/scholar/podcast/video.", "webpage"),
+    EnvVarSpec("KSADK_WEB_SSRF_POLICY_JSON", "web", "JSON policy overrides for web_fetch SSRF checks."),
+    EnvVarSpec("KSADK_WEB_TARBALL_NAME", "web", "KsADK Web fallback tarball file name."),
+    EnvVarSpec("KSADK_WEB_VERSION", "web", "KsADK Web npm dist-tag or version.", "latest"),
+    EnvVarSpec("KSADK_WORKING_SET_MAX_FILES", "runtime", "Maximum recent files recorded in compaction working set metadata.", "5"),
+    EnvVarSpec("KSADK_USER_BACKEND_URL", "web", "User-facing backend URL used by hosted UI integrations."),
+    EnvVarSpec("KSADK_WORKFLOW_PROMPT", "skills", "Prompt text exposed to local Skill workflow scripts."),
+    EnvVarSpec("KSADK_WORKSPACE_ID", "sessions", "Workspace id used for session namespace scoping."),
+    EnvVarSpec("CLOUD_MONITOR_APP_KEY", "tracing", "CloudMonitor AppKey for optional OTLP ingestion.", sensitive=True),
+    EnvVarSpec(
+        "CLOUD_MONITOR_LANGFUSE_ENABLED",
+        "tracing",
+        "Enable or disable the CloudMonitor Langfuse SDK callback; defaults to enabled when keys and host are present.",
+    ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_LANGFUSE_HOST",
+        "tracing",
+        "CloudMonitor AppMonitor Langfuse SDK host.",
+    ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_LANGFUSE_PUBLIC_KEY",
+        "tracing",
+        "CloudMonitor AppMonitor Langfuse public key returned by the platform.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_LANGFUSE_SECRET_KEY",
+        "tracing",
+        "CloudMonitor AppMonitor Langfuse secret key returned by the platform.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_OTLP_ENABLED",
+        "tracing",
+        "Enable or disable the CloudMonitor OTLP exporter; defaults to enabled when endpoint and AppKey are present.",
+    ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_OTLP_ENDPOINT",
+        "tracing",
+        "CloudMonitor generic OTLP HTTP endpoint; KsADK derives /v1/traces when no traces endpoint is set.",
+    ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_OTLP_HEADERS",
+        "tracing",
+        "Additional CloudMonitor OTLP HTTP headers, comma-separated and URL-encoded.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_OTLP_PROTOCOL",
+        "tracing",
+        "CloudMonitor generic OTLP protocol; KsADK supports http/protobuf.",
+    ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_OTLP_TRACES_ENDPOINT",
+        "tracing",
+        "CloudMonitor OTLP HTTP traces endpoint; takes precedence over the generic endpoint.",
+    ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_OTLP_TRACES_PROTOCOL",
+        "tracing",
+        "CloudMonitor traces protocol; takes precedence over the generic protocol.",
+    ),
+    EnvVarSpec("OTEL_EXPORTER_OTLP_ENDPOINT", "tracing", "Generic OTLP HTTP endpoint used to derive the traces endpoint."),
+    EnvVarSpec("OTEL_EXPORTER_OTLP_HEADERS", "tracing", "Generic OTLP HTTP headers, comma-separated and URL-encoded.", sensitive=True),
+    EnvVarSpec("OTEL_EXPORTER_OTLP_PROTOCOL", "tracing", "Generic OTLP protocol; KsADK auto HTTP exporter supports http/protobuf."),
+    EnvVarSpec("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "tracing", "OTLP HTTP traces endpoint; takes precedence over the generic endpoint."),
+    EnvVarSpec("OTEL_EXPORTER_OTLP_TRACES_HEADERS", "tracing", "OTLP HTTP traces headers; takes precedence over generic headers.", sensitive=True),
+    EnvVarSpec("OTEL_EXPORTER_OTLP_TRACES_PROTOCOL", "tracing", "OTLP traces protocol; takes precedence over the generic protocol."),
+    EnvVarSpec("OTEL_RESOURCE_ATTRIBUTES", "tracing", "OpenTelemetry resource attributes in key=value comma-separated form."),
+    EnvVarSpec("OTEL_SERVICE_NAME", "tracing", "OpenTelemetry service name."),
+    EnvVarSpec(
+        "KSADK_OTLP_MAX_EXPORT_BATCH_SIZE",
+        "tracing",
+        "Maximum spans exported per OTLP batch to avoid oversized collector requests.",
+        "64",
+    ),
+)
+
+ENV_VAR_REGISTRY: tuple[EnvVarSpec, ...] = tuple(
+    sorted(_ENV_VAR_REGISTRY_ITEMS, key=lambda spec: spec.name)
+)
+
+
+def iter_env_vars() -> tuple[EnvVarSpec, ...]:
+    return ENV_VAR_REGISTRY

ksadk/configs/global_config.py

@@ -0,0 +1,200 @@
+"""
+全局配置管理模块
+
+管理 ~/.agentengine/settings.json 全局配置文件
+
+配置格式 v1.0 - 嵌套结构:
+{
+    "version": "1.0",
+    "model": {
+        "OPENAI_API_KEY": "sk-xxx",
+        "OPENAI_BASE_URL": "http://kspmas.ksyun.com/v1",
+        "OPENAI_MODEL_NAME": "glm-5.2"
+    },
+    "cloud": {
+        "KSYUN_ACCESS_KEY": "AKxxx",
+        "KSYUN_SECRET_KEY": "SKxxx",
+        "KSYUN_ACCOUNT_ID": "2000003485",
+        "KSYUN_REGION": "cn-beijing-6"
+    }
+}
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict
+
+# 当前配置版本
+CURRENT_CONFIG_VERSION = "1.0"
+
+# 配置分组定义
+CONFIG_GROUPS = {
+    "model": [
+        "OPENAI_API_KEY",
+        "OPENAI_BASE_URL",
+        "OPENAI_MODEL_NAME",
+    ],
+    "cloud": [
+        "KSYUN_ACCESS_KEY",
+        "KSYUN_SECRET_KEY",
+        "KSYUN_ACCOUNT_ID",
+        "KSYUN_REGION",
+        # 反查身份缓存：{ak_fingerprint: {user_uuid, main_account_id, ...}}
+        # 嵌套对象，get_env_from_global_config 跳过它（不当 env-var），build 保留它
+        "IDENTITY_CACHE",
+    ],
+    # 未来可扩展更多分组
+    # "observability": ["LANGFUSE_PUBLIC_KEY", ...],
+    # "plugins": {...},
+}
+
+
+def get_global_config_dir() -> Path:
+    """获取全局配置目录路径
+
+    Returns:
+        Path: ~/.agentengine/
+    """
+    return Path.home() / ".agentengine"
+
+
+def get_global_config_path() -> Path:
+    """获取全局配置文件路径
+
+    Returns:
+        Path: ~/.agentengine/settings.json
+    """
+    return get_global_config_dir() / "settings.json"
+
+
+def load_global_config() -> Dict[str, Any]:
+    """加载全局配置
+
+    Returns:
+        dict: 全局配置字典，如果文件不存在则返回空字典
+    """
+    config_path = get_global_config_path()
+    if not config_path.exists():
+        return {}
+
+    try:
+        # 使用 utf-8-sig 自动处理 BOM，确保 Windows 兼容性
+        with open(config_path, "r", encoding="utf-8-sig") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def save_global_config(config: Dict[str, Any]) -> bool:
+    """保存全局配置
+
+    Args:
+        config: 配置字典
+
+    Returns:
+        bool: 是否保存成功
+    """
+    config_dir = get_global_config_dir()
+    config_path = get_global_config_path()
+
+    try:
+        # 确保目录存在
+        config_dir.mkdir(parents=True, exist_ok=True)
+
+        # 添加版本号
+        config["version"] = CURRENT_CONFIG_VERSION
+
+        # 使用 utf-8-sig 编码写入，确保 Windows 兼容性
+        with open(config_path, "w", encoding="utf-8-sig") as f:
+            json.dump(config, f, indent=2, ensure_ascii=False)
+
+        return True
+    except IOError:
+        return False
+
+
+def global_config_exists() -> bool:
+    """检查全局配置是否存在
+
+    Returns:
+        bool: 是否存在全局配置文件
+    """
+    return get_global_config_path().exists()
+
+
+def get_env_from_global_config() -> Dict[str, str]:
+    """从全局配置获取环境变量格式的配置
+
+    返回可以直接写入 .env 文件的键值对
+    注意：不包含 Langfuse 配置，因为这些通常是项目级别的配置
+
+    Returns:
+        dict: 环境变量字典
+    """
+    config = load_global_config()
+    if not config:
+        return {}
+
+    env_vars = {}
+
+    # 从各分组中提取环境变量
+    for group_name, keys in CONFIG_GROUPS.items():
+        group_config = config.get(group_name, {})
+        for key in keys:
+            if key == "IDENTITY_CACHE":
+                # 嵌套对象，不作为 env-var 暴露（由 identity 模块直接读写）
+                continue
+            if key in group_config and group_config[key]:
+                env_vars[key] = group_config[key]
+
+    return env_vars
+
+
+def build_global_config_from_env(env_vars: Dict[str, str]) -> Dict[str, Any]:
+    """从环境变量字典构建全局配置结构
+
+    注意：不包含 Langfuse 配置，因为这些通常是项目级别的配置
+
+    Args:
+        env_vars: 环境变量字典
+
+    Returns:
+        dict: 全局配置结构 (嵌套格式)
+    """
+    config = {}
+
+    # 按分组构建嵌套结构
+    for group_name, keys in CONFIG_GROUPS.items():
+        group_config = {}
+        for key in keys:
+            if key == "IDENTITY_CACHE":
+                continue  # 由 identity 模块单独管理，不参与重建
+            if key in env_vars and env_vars[key]:
+                group_config[key] = env_vars[key]
+        if group_config:
+            config[group_name] = group_config
+
+    # 保留现有 settings.json 里不在 CONFIG_GROUPS 的未知字段（含 IDENTITY_CACHE 嵌套对象）
+    # 避免 config set/wizard 保存时丢失 identity 缓存
+    existing = load_global_config()
+    if isinstance(existing, dict):
+        for group_name, group_config in existing.items():
+            if group_name == "version":
+                continue
+            if group_name not in CONFIG_GROUPS:
+                config[group_name] = group_config
+                continue
+            merged = dict(config.get(group_name) or {})
+            for key, value in (group_config or {}).items():
+                if key not in CONFIG_GROUPS[group_name] and key not in merged:
+                    merged[key] = value
+            if merged:
+                config[group_name] = merged
+        # 保留 IDENTITY_CACHE（在 cloud 组但非 env-var，重建会丢，这里补回）
+        existing_cloud = existing.get("cloud") or {}
+        if isinstance(existing_cloud.get("IDENTITY_CACHE"), dict):
+            cloud_config = dict(config.get("cloud") or {})
+            cloud_config["IDENTITY_CACHE"] = existing_cloud["IDENTITY_CACHE"]
+            config["cloud"] = cloud_config
+
+    return config