agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

ksadk/cli/cmd_replay.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+"""ksadk replay — 基于 RuntimeEvent store + session 级订阅的历史回放 (goal-16)。
+
+CLI 是消费 RuntimeAdapter/RuntimeEvent 的薄壳(不含 runtime 逻辑):replay 复用 goal-10
+``RuntimeEventStore`` 与 goal-12 共享 parser/replay,把某 session 的 RuntimeEvent 历史
+回放为确定性 transcript(text/reasoning/tool/artifact/run + a2ui/a2a extras)。
+
+注:回放的是经 RuntimeEvent 持久化的新事件模型(带 runtime marker);legacy SessionEvent
+(旧 assistant_message 等)不在本模型内,不回放。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import click
+
+from ksadk.cli.resource_common import CONTEXT_SETTINGS
+from ksadk.events.replay import replay_transcript
+from ksadk.events.store import RuntimeEventStore
+
+_HELP = dict(help_option_names=["-h", "--help"])
+
+
+@click.command(
+    "replay", context_settings=CONTEXT_SETTINGS, help="回放某 session 的 RuntimeEvent 历史"
+)
+@click.argument("session_id")
+@click.option(
+    "--after-seq-id", default=0, show_default=True, type=int, help="从该 seq cursor 之后回放"
+)
+@click.option("--before-seq-id", default=None, type=int, help="回放上界(不含该 seq)")
+@click.option(
+    "--format", "fmt", type=click.Choice(["json", "text"]), default="text", show_default=True
+)
+def replay(session_id: str, after_seq_id: int, before_seq_id: int | None, fmt: str):
+    """回放 session 的 RuntimeEvent 历史(text/reasoning/tool/artifact/run)。"""
+    asyncio.run(_run(session_id, after_seq_id=after_seq_id, before_seq_id=before_seq_id, fmt=fmt))
+
+
+async def _run(session_id: str, *, after_seq_id: int, before_seq_id: int | None, fmt: str) -> None:
+    from ksadk.sessions import resolve_session_service
+
+    store = RuntimeEventStore(resolve_session_service())
+    parser = await replay_transcript(
+        store, session_id, after_seq_id=after_seq_id, before_seq_id=before_seq_id
+    )
+    transcript = parser.transcript()
+    if fmt == "json":
+        click.echo(json.dumps(transcript, ensure_ascii=False, sort_keys=True))
+        return
+
+    items = transcript["items"]
+    if not items and not transcript["extras"]:
+        click.echo(f"session {session_id} 无 RuntimeEvent 历史(或该 session 未经新事件模型持久化)")
+        return
+    for item in items:
+        kind = item.get("kind")
+        if kind in ("text", "reasoning"):
+            marker = "▍final" if item.get("final") else "▍delta"
+            click.echo(f"[{kind}/{item.get('phase')}] {marker} {item.get('text')}")
+        elif kind == "tool_call":
+            done = "✓" if item.get("done") else "…"
+            click.echo(f"[tool] {done} {item.get('name')} ({item.get('call_id')})")
+        elif kind == "artifact":
+            click.echo(f"[artifact] {item.get('name')} v{item.get('version')}")
+    for inv, status in transcript["run_status"].items():
+        click.echo(f"[run] {inv}: {status}")
+    for extra in transcript["extras"]:
+        click.echo(f"[{extra['event_type']}] {json.dumps(extra['payload'], ensure_ascii=False)}")

ksadk/cli/cmd_run.py

@@ -5,19 +5,21 @@ ksadk run - 本地运行 Agent
 对于 LangChain/LangGraph/DeepAgents 项目，使用自己的实现
 """
 
-import click
-import asyncio
+import os
 import subprocess
 import sys
-import os
 from pathlib import Path
+
+import click
+import uvicorn
+
 from ksadk.cli.error_utils import ensure_json_output_supported, print_exception
 from ksadk.cli.local_runtime import reexec_with_project_venv_if_needed
+from ksadk.cli.runtime_bootstrap import create_runtime_web_app
 from ksadk.cli.ui import (
     print_error,
     print_info,
     print_kv,
-    print_rule,
     print_success,
     print_title,
     print_warn,
@@ -38,16 +40,28 @@ from ksadk.cli.ui import (
     is_flag=True,
     help="兼容参数；TUI 已默认使用 inline viewport 并保留终端 scrollback",
 )
-def run(agent_dir: str, port: int, interactive: bool, no_trace: bool, model: str, show_thinking: bool, no_stream: bool, no_alt_screen: bool):
+def run(
+    agent_dir: str,
+    port: int,
+    interactive: bool,
+    no_trace: bool,
+    model: str,
+    show_thinking: bool,
+    no_stream: bool,
+    no_alt_screen: bool,
+):
     """运行 Agent (支持 LangChain / LangGraph / DeepAgents / ADK)
 
     AGENT_DIR: Agent 项目目录 (默认: 当前目录)
     """
     ensure_json_output_supported(
         "agentengine run",
-        suggestion="请改用 `agentengine agent status --output json` 或 `agentengine build --output json` 获取结构化信息。",
+        suggestion=(
+            "请改用 `agentengine agent status --output json` 或 "
+            "`agentengine build --output json` 获取结构化信息。"
+        ),
     )
-    from ksadk.detection import FrameworkDetector, FrameworkType
+    from ksadk.detection import FrameworkDetector
 
     agent_path = Path(agent_dir).resolve()
     command_args = ["run", str(agent_path), "--port", str(port)]
@@ -91,7 +105,7 @@ def run(agent_dir: str, port: int, interactive: bool, no_trace: bool, model: str
         "langchain": "LangChain",
         "langgraph": "LangGraph",
         "deepagents": "DeepAgents",
-        "unknown": "Unknown"
+        "unknown": "Unknown",
     }
     framework_name = framework_map.get(result.type.value, result.type.value)
 
@@ -99,58 +113,50 @@ def run(agent_dir: str, port: int, interactive: bool, no_trace: bool, model: str
     print_kv("Agent 名称", str(result.name))
     print_kv("入口点", str(result.entry_point))
 
+    from ksadk.cli.cmd_web import configure_local_runtime_persistence
+
+    configure_local_runtime_persistence(agent_path, result.type.value)
+
     # 2. 根据框架类型选择处理方式
-    # 所有框架统一使用 _run_custom() 以支持 Langfuse 自动插桩
-    # (Langfuse instrumentation 需要在同一进程内生效)
-    _run_custom(result, agent_path, port, interactive, no_trace, show_thinking, no_stream, no_alt_screen)
+    # 所有框架统一使用 _run_custom()，让 OTel instrumentation 在同一进程生效。
+    _run_custom(
+        result, agent_path, port, interactive, no_trace, show_thinking, no_stream, no_alt_screen
+    )
 
 
 def _run_adk_cli(agent_path: Path, port: int = 8080, command: str = "run"):
-    """运行 ADK Agent，支持 Langfuse tracing
-
-    对于 Langfuse 集成，我们需要在同一进程内运行 ADK，
-    因为 OpenTelemetry instrumentation 只在进程内生效。
-    """
+    """运行 ADK Agent，使用标准 OTLP 配置。"""
     import os
 
-    has_langfuse = bool(os.getenv("LANGFUSE_PUBLIC_KEY"))
+    has_otlp = bool(
+        os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
+        or os.getenv("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
+        or os.getenv("CLOUD_MONITOR_OTLP_ENDPOINT")
+        or os.getenv("CLOUD_MONITOR_OTLP_TRACES_ENDPOINT")
+    )
 
     # 必须先初始化 Tracing（在导入 ADK 之前）
-    if has_langfuse:
+    if has_otlp:
         try:
             from ksadk.tracing import setup_tracing
 
             setup_tracing(
                 enable_inmemory=False,
-                enable_langfuse=True,
                 enable_adk_instrumentation=True,
             )
-            print_info("Tracing: Enabled (Langfuse + ADK Instrumentation)")
+            print_info("Tracing: Enabled (OTLP + ADK Instrumentation)")
         except Exception as e:
-            print_warn(f"Langfuse 初始化失败: {e}")
+            print_warn(f"OTLP tracing 初始化失败: {e}")
 
     print_kv("调用 ADK 原生 CLI", f"adk {command}")
 
-    # 使用 subprocess（Langfuse instrumentation 在子进程中不生效，但环境变量会传递）
-    # ADK CLI 本身不支持 Langfuse，需要用户在项目中集成
+    # 子进程继承标准 OTLP 环境变量；项目内 instrumentation 负责创建 spans。
     if command == "run":
         cmd = [sys.executable, "-m", "google.adk.cli", "run", "."]
     else:
         cmd = [sys.executable, "-m", "google.adk.cli", "web", ".", "--port", str(port)]
 
-    # 传递 Langfuse 环境变量
     env = os.environ.copy()
-    langfuse_vars = ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY", "LANGFUSE_BASE_URL"]
-    for var in langfuse_vars:
-        if var in os.environ:
-            env[var] = os.environ[var]
-
-    # 提示用户如何在 ADK 项目中启用 Langfuse
-    if has_langfuse:
-        print_rule("ADK 项目 Langfuse 集成提示")
-        print_info("在 agent.py 中添加以下代码:")
-        print_info("from openinference.instrumentation.google_adk import GoogleADKInstrumentor")
-        print_info("GoogleADKInstrumentor().instrument()")
 
     try:
         subprocess.run(cmd, cwd=str(agent_path), check=True, env=env)
@@ -172,68 +178,47 @@ def _run_custom(
     no_stream: bool = False,
     no_alt_screen: bool = False,
 ):
-    """使用自定义实现 (LangChain/LangGraph/DeepAgents)"""
-    from ksadk.runners.factory import create_runner
+    """Run one detected project through the canonical RuntimeAdapter composition."""
 
     # 初始化 Tracing
     if not no_trace:
         try:
-            from ksadk.tracing import setup_tracing
             import os
 
-            has_langfuse = bool(os.getenv("LANGFUSE_PUBLIC_KEY"))
+            from ksadk.tracing import setup_tracing
+
             has_otlp = bool(
                 os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
                 or os.getenv("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
             )
 
-            use_callback_only = os.getenv("LANGFUSE_USE_CALLBACK", "").strip().lower() in (
-                "1",
-                "true",
-                "yes",
-                "on",
-            )
-
             setup_tracing(
                 enable_inmemory=True,
                 enable_langfuse=None,
-                use_callback_only=use_callback_only,
             )
 
             if has_otlp:
                 print_info("Tracing: Enabled (InMemory + OTLP HTTP)")
-            elif has_langfuse:
-                print_info(f"Tracing: Enabled (InMemory + Langfuse, CallbackOnly={use_callback_only})")
             else:
                 print_info("Tracing: Enabled")
         except Exception as e:
             print_warn(f"Tracing 初始化失败: {e}")
 
-    # 创建 Runner
+    if interactive:
+        del show_thinking, no_stream, no_alt_screen
+        print_error(
+            "RuntimeAdapter TUI 尚未接通；请使用 `ksadk web` 或不带 --interactive 启动"
+        )
+        raise SystemExit(2)
+
     try:
-        print_info("初始化 Runner...")
-        runner = create_runner(result, str(agent_path))
-        runner.load_agent()
-        print_success("Agent 加载成功")
+        runtime_app = create_runtime_web_app(result, agent_path)
     except Exception as e:
-        print_exception("Agent 加载失败", e)
-        # import traceback
-        # traceback.print_exc()
+        print_exception("RuntimeAdapter 初始化失败", e)
         raise SystemExit(1)
 
-    # 运行
-    if interactive:
-        # TUI 交互模式
-        from ksadk.tui.loop import run_tui
-        run_tui(
-            runner,
-            show_thinking=show_thinking,
-            project_dir=str(agent_path),
-            no_alt_screen=no_alt_screen,
-        )
-    else:
-        print_success(f"Server running at http://0.0.0.0:{port}")
-        print_kv("API Docs", f"http://0.0.0.0:{port}/docs")
-        print_kv("Chat API", f"http://0.0.0.0:{port}/chat")
-        print_info("Press Ctrl+C to stop")
-        runner.run_server(port=port)
+    print_success(f"Server running at http://127.0.0.1:{port}")
+    print_kv("API Docs", f"http://127.0.0.1:{port}/docs")
+    print_kv("Chat API", f"http://127.0.0.1:{port}/chat")
+    print_info("Press Ctrl+C to stop")
+    uvicorn.run(runtime_app, host="127.0.0.1", port=port)

ksadk/cli/cmd_status.py

@@ -4,15 +4,17 @@ agentengine status - 查看 Agent 运行状态和 Endpoint
 支持 watch 模式实时刷新
 """
 
-import click
 import asyncio
 import time
-from pathlib import Path
 from datetime import datetime
+from pathlib import Path
 from typing import Sequence
+
+import click
+
 from ksadk.api.client import DryRunExit
 from ksadk.cli.agent_ref import merge_agent_inputs, resolve_agent_ref
-from ksadk.cli.dry_run import dry_run_option, run_async_with_dry_run, effective_dry_run
+from ksadk.cli.dry_run import dry_run_option, effective_dry_run, run_async_with_dry_run
 from ksadk.cli.error_utils import print_exception, resolution_error, usage_error
 from ksadk.cli.resource_common import (
     CONTEXT_SETTINGS,
@@ -24,14 +26,10 @@ from ksadk.cli.resource_common import (
 from ksadk.cli.ui import (
     get_console,
     is_json_output,
-    print_error,
     print_info,
-    print_kv,
-    print_title,
-    print_warn,
+    replica_rich_style,
     status_click_color,
     status_rich_style,
-    replica_rich_style,
     summary_panel,
 )
 
@@ -55,7 +53,9 @@ AGENT_LIST_HIDDEN_FRAMEWORK_LABELS = {
 @click.option("--watch", "-w", is_flag=True, help="Watch 模式，持续刷新")
 @click.option("--interval", "-i", default=2, help="Watch 刷新间隔 (秒)")
 @click.option("--region", "-r", default="cn-beijing-6", envvar="KSYUN_REGION", help="区域")
-@click.option("--account-id", envvar="KSYUN_ACCOUNT_ID", help="金山云账号 ID（可选；未设置时从 AK/SK 反查）")
+@click.option(
+    "--account-id", envvar="KSYUN_ACCOUNT_ID", help="金山云账号 ID（可选；未设置时从 AK/SK 反查）"
+)
 @dry_run_option()
 def status(
     agent_ref: str,
@@ -125,9 +125,12 @@ def run_status_command(
         if not resolved:
             raise resolution_error(
                 "请指定 Agent（--agent 或位置参数），或在当前目录提供可解析的本地配置",
-                hints=["自动解析顺序: .agentengine.state -> agentengine.yaml/ksadk.yaml", "请先执行 `agentengine agent list`。"],
+                hints=[
+                    "自动解析顺序: .agentengine.state -> agentengine.yaml/ksadk.yaml",
+                    "请先执行 `agentengine agent list`。",
+                ],
             )
-        agent = resolved.value
+        agent = str(resolved.value)
         if resolved.source != "cli":
             print_info(f"未显式指定 Agent，使用 {resolved.source_text}: {agent}")
 
@@ -136,23 +139,34 @@ def run_status_command(
     if watch and dry_run:
         raise usage_error("Watch 模式不支持 dry-run，请去掉 --watch 或取消 dry-run。")
     if watch and is_json_output():
-        raise usage_error("Watch 模式不支持 `--output json`。", hints=["请去掉 `--watch` 或改用 `agentengine agent status --output json`。"])
+        raise usage_error(
+            "Watch 模式不支持 `--output json`。",
+            hints=["请去掉 `--watch` 或改用 `agentengine agent status --output json`。"],
+        )
 
     # Dry Run 模式由 AgentEngineClient 处理
     # 只要传入 dry_run=True，底层 client 会抛出 DryRunExit 异常
 
+    resolved_account_id = account_id or ""
     if show_all:
         run_async_with_dry_run(
-            _list_all_agents(region, account_id, dry_run, page=page, size=size, framework=framework),
+            _list_all_agents(
+                region,
+                resolved_account_id,
+                dry_run,
+                page=page,
+                size=size,
+                framework=framework,
+            ),
             dry_run=dry_run,
             dry_run_resource="agent",
             dry_run_action="list",
         )
     elif watch:
-        _watch_status(agent, region, account_id, interval)
+        _watch_status(str(agent), region, resolved_account_id, interval)
     else:
         run_async_with_dry_run(
-            _show_agent_status(agent, region, account_id, dry_run),
+            _show_agent_status(str(agent), region, resolved_account_id, dry_run),
             dry_run=dry_run,
             dry_run_resource="agent",
             dry_run_action="status",
@@ -170,7 +184,7 @@ def _watch_status(agent: str, region: str, account_id: str, interval: int):
             click.clear()
 
             # 显示标题
-            click.secho(f"Agent Status Monitor", fg="blue", bold=True)
+            click.secho("Agent Status Monitor", fg="blue", bold=True)
             click.echo(f"   Agent: {agent}")
             click.echo(f"   Region: {region}")
             click.echo(f"   更新时间: {datetime.now().strftime('%H:%M:%S')}")
@@ -205,7 +219,9 @@ async def _show_agent_status(
         # 先按 ID 查询，失败后再按名称查询，避免依赖字符串前缀判断。
         result = await _get_agent_runtime(agent, region, account_id, dry_run, is_name=False)
         if result.get("status") == "Error":
-            result_by_name = await _get_agent_runtime(agent, region, account_id, dry_run, is_name=True)
+            result_by_name = await _get_agent_runtime(
+                agent, region, account_id, dry_run, is_name=True
+            )
             if result_by_name.get("status") != "Error":
                 result = result_by_name
 
@@ -219,14 +235,14 @@ async def _show_agent_status(
     langfuse_url = result.get("langfuseTraceUrl")
     from dateutil import parser
 
-    created_at = result.get('createdAt')
+    created_at = result.get("createdAt")
     if created_at:
         dt = parser.parse(created_at)
         created_at = dt.astimezone().isoformat()
     else:
         created_at = "-"
 
-    updated_at = result.get('updatedAt')
+    updated_at = result.get("updatedAt")
     if updated_at:
         dt = parser.parse(updated_at)
         updated_at = dt.astimezone().isoformat()
@@ -378,8 +394,8 @@ async def _list_all_agents(
     rows = []
     items = []
     for r in results:
-        agent_id = (r.get("agentRuntimeId") or "N/A")
-        name = (r.get("agentRuntimeName") or "N/A")
+        agent_id = r.get("agentRuntimeId") or "N/A"
+        name = r.get("agentRuntimeName") or "N/A"
         status_val = r.get("status", "Unknown")
         ready = int(r.get("readyReplicas", 0) or 0)
         replicas = int(r.get("replicas", 0) or 0)
@@ -419,8 +435,20 @@ async def _list_all_agents(
         columns=(
             {"header": "ID", "key": "id", "style": "#58a6ff", "no_wrap": True, "min_width": 24},
             {"header": "名称", "key": "name", "style": "#c9d1d9", "min_width": 20},
-            {"header": "状态", "key": "status", "no_wrap": True, "justify": "center", "min_width": 10},
-            {"header": "副本", "key": "replicas_display", "no_wrap": True, "justify": "center", "min_width": 8},
+            {
+                "header": "状态",
+                "key": "status",
+                "no_wrap": True,
+                "justify": "center",
+                "min_width": 10,
+            },
+            {
+                "header": "副本",
+                "key": "replicas_display",
+                "no_wrap": True,
+                "justify": "center",
+                "min_width": 8,
+            },
             {"header": "Endpoint", "key": "endpoint", "style": "#8b949e", "overflow": "ellipsis"},
         ),
         rows=rows,
@@ -446,7 +474,9 @@ async def _list_all_agents(
         ],
     )
     if not is_json_output():
-        console.print(summary_panel(total=len(results), healthy=running, attention=unhealthy, noun="Agent"))
+        console.print(
+            summary_panel(total=len(results), healthy=running, attention=unhealthy, noun="Agent")
+        )
 
 
 def _get_status_color(status: str) -> str:
@@ -454,19 +484,24 @@ def _get_status_color(status: str) -> str:
     return status_click_color(status)
 
 
-async def _get_agent_runtime(agent: str, region: str, account_id: str, dry_run: bool = False, is_name: bool = False) -> dict:
+async def _get_agent_runtime(
+    agent: str, region: str, account_id: str, dry_run: bool = False, is_name: bool = False
+) -> dict:
     """获取 Agent 运行时状态
 
     调用 AgentEngine Server API
     """
     from ksadk.api import AgentEngineClient
+
     try:
         extra_headers = {}
         # 传递 Account ID
         if account_id:
             extra_headers["X-Ksc-Account-Id"] = account_id
 
-        async with AgentEngineClient(region=region, dry_run=dry_run, extra_headers=extra_headers) as client:
+        async with AgentEngineClient(
+            region=region, dry_run=dry_run, extra_headers=extra_headers
+        ) as client:
             if is_name:
                 response = await client.get_agent(name=agent)
             else:
@@ -484,10 +519,21 @@ async def _get_agent_runtime(agent: str, region: str, account_id: str, dry_run:
                 "description": basic.get("description", "") or response.get("description", ""),
                 "status": basic.get("status", "") or response.get("status", "Unknown"),
                 "phase": basic.get("phase", "") or response.get("phase", ""),
-                "replicas": basic.get("replicas") if basic.get("replicas") is not None else response.get("replicas", deploy.get("scaling", {}).get("min_replicas", 1)),
-                "readyReplicas": basic.get("ready_replicas") if basic.get("ready_replicas") is not None else response.get("ready_replicas", 0),
-                "endpoint": quick.get("public_endpoint") or quick.get("private_endpoint") or response.get("endpoint", ""),
-                "langfuseTraceUrl": adv.get("observability_url", "") or response.get("langfuse_trace_url", ""),
+                "replicas": (
+                    basic.get("replicas")
+                    if basic.get("replicas") is not None
+                    else response.get("replicas", deploy.get("scaling", {}).get("min_replicas", 1))
+                ),
+                "readyReplicas": (
+                    basic.get("ready_replicas")
+                    if basic.get("ready_replicas") is not None
+                    else response.get("ready_replicas", 0)
+                ),
+                "endpoint": quick.get("public_endpoint")
+                or quick.get("private_endpoint")
+                or response.get("endpoint", ""),
+                "langfuseTraceUrl": adv.get("observability_url", "")
+                or response.get("langfuse_trace_url", ""),
                 "createdAt": basic.get("created_at", "") or response.get("created_at", ""),
                 "updatedAt": basic.get("updated_at", "") or response.get("updated_at", ""),
                 "message": basic.get("message", "") or response.get("message", ""),
@@ -517,13 +563,16 @@ async def _list_agent_runtimes(
     调用 AgentEngine Server API
     """
     from ksadk.api import AgentEngineClient
+
     try:
         extra_headers = {}
         # 传递 Account ID
         if account_id:
             extra_headers["X-Ksc-Account-Id"] = account_id
 
-        async with AgentEngineClient(region=region, dry_run=dry_run, extra_headers=extra_headers) as client:
+        async with AgentEngineClient(
+            region=region, dry_run=dry_run, extra_headers=extra_headers
+        ) as client:
             response = await client.list_agents(
                 region=region,
                 framework=framework,

ksadk/cli/cmd_studio.py

@@ -0,0 +1,110 @@
+"""agentengine studio - start the local-first Agent authoring control plane."""
+
+from __future__ import annotations
+
+import os
+import secrets
+import webbrowser
+from pathlib import Path
+
+import click
+import uvicorn
+
+from ksadk.cli.env_options import load_env_file
+from ksadk.cli.ui import print_info, print_kv, print_success, print_title
+from ksadk.studio.api import create_studio_app
+from ksadk.studio.service import StudioService
+
+_MODEL_ENV_KEYS = (
+    "OPENAI_API_BASE",
+    "OPENAI_API_KEY",
+    "OPENAI_MODEL_NAME",
+)
+
+
+@click.command(context_settings=dict(help_option_names=["-h", "--help"]))
+@click.argument("workspace", default=".", type=click.Path())
+@click.option("--port", "-p", default=8080, type=click.IntRange(1, 65535))
+@click.option("--no-open", is_flag=True, help="仅打印 URL，不自动打开浏览器")
+@click.option(
+    "--env-file",
+    type=click.Path(exists=True, dir_okay=False),
+    help="模型环境文件；只读取 OPENAI_API_BASE/API_KEY/MODEL_NAME",
+)
+@click.option(
+    "--codex-proxy",
+    type=click.Choice(["inherit", "auto", "forced", "direct"]),
+    default="inherit",
+    show_default=True,
+    help="Codex Responses→Chat 代理策略",
+)
+def studio(
+    workspace: str,
+    port: int,
+    no_open: bool,
+    env_file: str | None,
+    codex_proxy: str,
+) -> None:
+    """启动本地 AgentKit Studio。
+
+    \b
+    WORKSPACE: Agent 工作区目录，目录不存在时自动初始化。
+    """
+
+    root = Path(workspace).expanduser().resolve()
+    managed_keys = (*_MODEL_ENV_KEYS, "KSADK_CODEX_USE_PROXY")
+    previous = {key: os.environ.get(key) for key in managed_keys}
+    previously_present = {key for key in managed_keys if key in os.environ}
+    try:
+        if env_file:
+            try:
+                values = load_env_file(env_file)
+            except ValueError as exc:
+                raise click.ClickException(str(exc)) from exc
+            loaded = 0
+            for key, value in values.items():
+                if key not in _MODEL_ENV_KEYS or not value:
+                    continue
+                loaded += 1
+                if key not in os.environ:
+                    os.environ[key] = value
+            print_kv("模型环境", f"已安全加载 {loaded}/{len(_MODEL_ENV_KEYS)} 个字段")
+        if codex_proxy == "forced":
+            os.environ["KSADK_CODEX_USE_PROXY"] = "1"
+        elif codex_proxy == "direct":
+            os.environ["KSADK_CODEX_USE_PROXY"] = "0"
+        elif codex_proxy == "auto":
+            os.environ.pop("KSADK_CODEX_USE_PROXY", None)
+        session_token = os.environ.get("KSADK_STUDIO_SESSION_TOKEN") or secrets.token_urlsafe(32)
+        csrf_token = secrets.token_urlsafe(24)
+        service = StudioService(root)
+        app = create_studio_app(
+            root,
+            service=service,
+            session_token=session_token,
+            csrf_token=csrf_token,
+            security_enabled=os.environ.get("KSADK_STUDIO_NO_SECURITY") != "1",
+        )
+        base_url = f"http://127.0.0.1:{port}/"
+        launch_url = f"{base_url}#session={session_token}"
+
+        print_title("启动 AgentKit Local Studio")
+        print_kv("工作区", str(root))
+        print_kv("访问地址", launch_url, value_style="#58a6ff")
+        print_success("构建与运行均在本地执行")
+        print_info("按 Ctrl+C 停止")
+        if not no_open:
+            webbrowser.open(launch_url)
+        uvicorn.run(
+            app,
+            host="127.0.0.1",
+            port=port,
+            log_level="info",
+            access_log=False,
+        )
+    finally:
+        for key in managed_keys:
+            if key in previously_present:
+                os.environ[key] = previous[key] or ""
+            else:
+                os.environ.pop(key, None)