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

ksadk/cli/cmd_build.py

@@ -1,23 +1,29 @@
 """
 agentengine build - 构建 Agent 应用
 
-支持两种模式:
+支持三种模式:
+- managed: 仅打包系统无关 runtime manifest
 - code: 打包 zip + 依赖 → 上传 KS3 (默认)
 - container: 构建 Docker 镜像
 """
 
 import asyncio
-import click
 import time
 from datetime import datetime
 from pathlib import Path
-from ksadk.cli.error_utils import abort_with_cli_error, is_debug_mode_enabled, remote_error, validation_error
-from ksadk.cli.workflow_common import print_workflow_header, render_workflow_result
+
+import click
+import yaml
+
+from ksadk.cli.error_utils import (
+    abort_with_cli_error,
+    is_debug_mode_enabled,
+    remote_error,
+    validation_error,
+)
 from ksadk.cli.ui import (
     capture_standard_output,
     is_json_output,
-    output_option as cli_output_option,
-    print_error,
     print_info,
     print_kv,
     print_next_steps,
@@ -25,6 +31,10 @@ from ksadk.cli.ui import (
     print_success,
     print_warn,
 )
+from ksadk.cli.ui import (
+    output_option as cli_output_option,
+)
+from ksadk.cli.workflow_common import print_workflow_header, render_workflow_result
 
 
 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
@@ -32,16 +42,32 @@ from ksadk.cli.ui import (
 @click.option(
     "--mode",
     "-m",
-    type=click.Choice(["container", "code"]),
-    default="code",
-    help="构建模式: code (默认, zip+KS3) 或 container (Docker)",
+    type=click.Choice(["auto", "managed", "container", "code"]),
+    default="auto",
+    help="构建模式: auto (按配置推断)、managed、code 或 container",
 )
 @click.option("--tag", "-t", help="镜像标签 (container 模式)")
 @click.option("--registry", help="镜像仓库地址 (container 模式)")
-@click.option("--push", is_flag=True, help="构建后推送 (镜像到仓库 / zip到KS3)")
-@click.option("--no-cache", is_flag=True, help="强制重新构建，不使用缓存 (code: 忽略已有 zip；container: docker --no-cache)")
-@click.option("--repackage", is_flag=True, help="Code 模式复用依赖缓存，但强制重新打包当前代码/runtime")
-@click.option("--region", "-r", default="cn-beijing-6", envvar="KSYUN_REGION", help="KS3 区域 (code 模式)")
+@click.option(
+    "--push",
+    is_flag=True,
+    help="构建后推送（仅 Container 镜像或 Code zip；ManagedRuntime 不支持）",
+)
+@click.option(
+    "--no-cache",
+    is_flag=True,
+    help="强制重新构建，不使用缓存 (code: 忽略已有 zip；container: docker --no-cache)",
+)
+@click.option(
+    "--repackage", is_flag=True, help="Code 模式复用依赖缓存，但强制重新打包当前代码/runtime"
+)
+@click.option(
+    "--region",
+    "-r",
+    default="cn-beijing-6",
+    envvar="KSYUN_REGION",
+    help="Code 的 KS3 区域，或 ManagedRuntime catalog 查询区域",
+)
 @click.option("--ks3-bucket", help="KS3 bucket 名称 (code 模式, 默认: agentengine-{region})")
 @cli_output_option()
 def build(
@@ -63,7 +89,9 @@ def build(
 
     \b
     模式:
-        code:      打包 zip + 依赖，上传 KS3 (默认)
+        auto:      按 artifact_type 推断 (默认)
+        managed:   只打包 ManagedRuntime manifest
+        code:      打包 zip + 依赖，上传 KS3
         container: 构建 Docker 镜像
 
     \b
@@ -77,22 +105,29 @@ def build(
     """
     _ = output_mode
     agent_path = Path(agent_dir).resolve()
+    effective_mode = _resolve_build_mode(agent_path, mode)
     try:
         with capture_standard_output():
             print_workflow_header(
                 title="Agent 构建",
-                subtitle=f"mode: {mode}",
+                subtitle=f"mode: {effective_mode}",
                 project_dir=agent_path,
                 target="build",
-                region=region if mode == "code" else None,
+                region=region if effective_mode in {"code", "managed"} else None,
                 mode_label="构建模式",
-                mode_value=mode,
+                mode_value=effective_mode,
             )
 
-            if mode == "container":
+            if effective_mode == "container":
                 result = _build_container(agent_path, tag, registry, push, no_cache)
+            elif effective_mode == "managed":
+                result = asyncio.run(
+                    _build_managed_runtime(agent_path, push, region, ks3_bucket)
+                )
             else:
-                result = asyncio.run(_build_code(agent_path, push, region, ks3_bucket, no_cache, repackage))
+                result = asyncio.run(
+                    _build_code(agent_path, push, region, ks3_bucket, no_cache, repackage)
+                )
     except Exception as e:
         if is_debug_mode_enabled():
             raise
@@ -103,6 +138,91 @@ def build(
         render_workflow_result(action="build", result=result)
 
 
+def _load_build_config(agent_path: Path) -> dict:
+    config_path = agent_path / "agentengine.yaml"
+    if not config_path.exists():
+        config_path = agent_path / "ksadk.yaml"
+    if not config_path.exists():
+        return {}
+    with config_path.open(encoding="utf-8-sig") as stream:
+        loaded = yaml.safe_load(stream)
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def _resolve_build_mode(agent_path: Path, requested_mode: str) -> str:
+    normalized = str(requested_mode or "auto").strip().lower()
+    if normalized != "auto":
+        return normalized
+    config = _load_build_config(agent_path)
+    artifact_type = str(config.get("artifact_type") or "").strip().lower()
+    return "managed" if artifact_type == "managedruntime" else "code"
+
+
+async def _build_managed_runtime(
+    agent_path: Path,
+    push: bool,
+    region: str,
+    ks3_bucket: str | None = None,
+):
+    """Build a local, system-independent runtime manifest for review/audit.
+
+    ManagedRuntime deployment is an inline server contract.  Its optional local
+    zip is deliberately never published to KS3; the server receives the
+    normalized manifest and resolves the managed image itself.
+    """
+    import json
+    from dataclasses import asdict
+
+    from ksadk.builders import ManagedRuntimeBuilder
+    from ksadk.managed_runtime import resolve_managed_runtime
+
+    if push or ks3_bucket:
+        raise validation_error(
+            "ManagedRuntime 不使用 KS3；请移除 --push 和 --ks3-bucket。"
+            "构建出的本地 zip 仅用于审计，直接执行 `ksadk deploy .` 即可部署。"
+        )
+
+    config = _load_build_config(agent_path)
+    resolved = await resolve_managed_runtime(config, region=region)
+    builder = ManagedRuntimeBuilder(agent_path, runtime_version=resolved.version)
+    result = builder.build()
+    if not result.success or result.artifact_path is None:
+        raise validation_error(result.error_message or "ManagedRuntime manifest 构建失败")
+
+    metadata_file = agent_path / ".agentengine" / "build-metadata.json"
+    metadata_file.parent.mkdir(parents=True, exist_ok=True)
+    data = asdict(result)
+    metadata_file.write_text(
+        json.dumps(
+            data,
+            ensure_ascii=False,
+            indent=2,
+            default=lambda value: str(value) if isinstance(value, Path) else value,
+        ),
+        encoding="utf-8",
+    )
+
+    _print_summary("ManagedRuntime", result, show_next_step=True)
+    return {
+        "framework": str(result.metadata.get("framework") or "codex"),
+        "artifact_type": "managedruntime",
+        "artifact_source": "built",
+        "artifact_reused": False,
+        "artifact_built": True,
+        "artifact_reference": str(result.artifact_path),
+        "artifact_path": str(result.artifact_path),
+        "artifact_size_mb": float(result.artifact_size_mb),
+        "ks3_path": "",
+        "ks3_public_url": "",
+        "ks3_internal_url": "",
+        "runtime_name": resolved.name,
+        "runtime_version": resolved.version,
+        "runtime_version_source": resolved.source,
+        "manifest_sha256": str(result.metadata.get("manifest_sha256") or ""),
+        "push": False,
+    }
+
+
 def _build_container(agent_path: Path, tag: str, registry: str, push: bool, no_cache: bool):
     """Container 模式构建"""
     from ksadk.builders import ContainerBuilder
@@ -126,7 +246,10 @@ def _build_container(agent_path: Path, tag: str, registry: str, push: bool, no_c
             )
 
         print_next_steps(
-            [f"agentengine deploy --target serverless --image {result.metadata['image']} --artifact-type Container"]
+            [
+                "agentengine deploy --target serverless "
+                f"--image {result.metadata['image']} --artifact-type Container"
+            ]
         )
 
     # 摘要
@@ -147,14 +270,16 @@ async def _build_code(
     agent_path: Path,
     push: bool,
     region: str,
-    ks3_bucket: str = None,
+    ks3_bucket: str | None = None,
     no_cache: bool = False,
     repackage: bool = False,
 ):
     """Code 模式构建"""
     from ksadk.builders import CodeBuilder, KS3Uploader
 
-    builder = CodeBuilder(project_dir=agent_path, config={"no_cache": no_cache, "repackage": repackage})
+    builder = CodeBuilder(
+        project_dir=agent_path, config={"no_cache": no_cache, "repackage": repackage}
+    )
     result = builder.build()
 
     if not result.success:
@@ -167,17 +292,19 @@ async def _build_code(
     ks3_internal_url = None
 
     if push:
+        if result.artifact_path is None:
+            raise validation_error("构建成功但未生成代码包路径")
         print_rule("上传到 KS3")
         upload_started_at = time.monotonic()
-        
+
         # 预发特殊逻辑: region 为 pre-online 时，资源上传到 cn-beijing-6
         upload_region = "cn-beijing-6" if region == "pre-online" else region
-        
+
         if region == "pre-online":
             print_warn("预发环境: 资源将上传到 cn-beijing-6 region")
-        
+
         uploader = KS3Uploader(region=upload_region, bucket=ks3_bucket)
-        
+
         # 使用时间戳确保每次上传的代码包路径唯一，支持真正的版本回滚
         timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
         object_key = f"agents/{agent_name}/code_{timestamp}.zip"
@@ -189,7 +316,7 @@ async def _build_code(
             # 更新 metadata 以便持久化
             result.metadata["ks3_path"] = ks3_path
             result.metadata["pushed"] = True
-            
+
             ks3_public_url = uploader.get_public_url_by_key(object_key)
             ks3_internal_url = uploader.get_internal_url_by_key(object_key)
             print_kv("公网地址", ks3_public_url or "-")
@@ -206,7 +333,7 @@ async def _build_code(
     try:
         import json
         from dataclasses import asdict
-        
+
         # 自定义序列化: 处理 Path 对象
         def default_serializer(obj):
             if isinstance(obj, Path):
@@ -228,7 +355,9 @@ async def _build_code(
     return {
         "framework": result.metadata.get("framework", "unknown"),
         "artifact_type": "code",
-        "artifact_source": "built_and_uploaded" if push and result.metadata.get("ks3_path") else "built",
+        "artifact_source": (
+            "built_and_uploaded" if push and result.metadata.get("ks3_path") else "built"
+        ),
         "artifact_reused": bool(result.metadata.get("reused", False)),
         "artifact_built": True,
         "artifact_reference": str(result.metadata.get("ks3_path") or result.artifact_path or ""),

ksadk/cli/cmd_completion.py

@@ -7,8 +7,10 @@ agentengine completion - Shell 自动补全安装
 import os
 import re
 import sys
-import click
 from pathlib import Path
+
+import click
+
 from ksadk.cli.error_utils import ensure_json_output_supported, print_exception
 from ksadk.cli.resource_common import CONTEXT_SETTINGS
 from ksadk.cli.ui import (
@@ -63,7 +65,12 @@ def _resolve_bash_rc_file(home: Path) -> Path:
 
 
 def _has_zsh_compinit(rc_content: str) -> bool:
-    return re.search(r"(?m)^\s*(?:autoload\s+-Uz\s+compinit(?:\s*&&\s*compinit)?|compinit)\s*$", rc_content) is not None
+    return (
+        re.search(
+            r"(?m)^\s*(?:autoload\s+-Uz\s+compinit(?:\s*&&\s*compinit)?|compinit)\s*$", rc_content
+        )
+        is not None
+    )
 
 
 def _rewrite_zsh_rc(rc_content: str, completion_file: Path, init_line: str) -> tuple[str, bool]:
@@ -72,7 +79,9 @@ def _rewrite_zsh_rc(rc_content: str, completion_file: Path, init_line: str) -> t
 
     # 清理旧的 AgentEngine 自动补全配置，避免重复 source / eval。
     updated = re.sub(
-        r'(?ms)^\s*if command -v agentengine >/dev/null 2>&1; then\s*\n\s*eval "\$\(_AGENTENGINE_COMPLETE=zsh_source agentengine\)"\s*\n\s*fi\s*\n?',
+        r"(?ms)^\s*if command -v agentengine >/dev/null 2>&1; then\s*\n"
+        r'\s*eval "\$\(_AGENTENGINE_COMPLETE=zsh_source agentengine\)"\s*\n'
+        r"\s*fi\s*\n?",
         "",
         rc_content,
     )
@@ -87,7 +96,7 @@ def _rewrite_zsh_rc(rc_content: str, completion_file: Path, init_line: str) -> t
         updated,
     )
     updated = re.sub(
-        r'(?m)^\s*# AgentEngine CLI 自动补全\s*$\n?',
+        r"(?m)^\s*# AgentEngine CLI 自动补全\s*$\n?",
         "",
         updated,
     )
@@ -116,9 +125,9 @@ def _rewrite_bash_rc(rc_content: str, completion_file: Path) -> str:
         rc_content,
     )
     updated = re.sub(
-        r'(?m)^\s*if command -v agentengine >/dev/null 2>&1; then\s*$\n?'
+        r"(?m)^\s*if command -v agentengine >/dev/null 2>&1; then\s*$\n?"
         r'^\s*eval "\$\(_AGENTENGINE_COMPLETE=bash_source agentengine\)"\s*$\n?'
-        r'^\s*fi\s*$\n?',
+        r"^\s*fi\s*$\n?",
         "",
         updated,
     )
@@ -128,7 +137,7 @@ def _rewrite_bash_rc(rc_content: str, completion_file: Path) -> str:
         updated,
     )
     updated = re.sub(
-        r'(?m)^\s*# AgentEngine CLI 自动补全\s*$\n?',
+        r"(?m)^\s*# AgentEngine CLI 自动补全\s*$\n?",
         "",
         updated,
     )
@@ -140,7 +149,7 @@ def _rewrite_bash_rc(rc_content: str, completion_file: Path) -> str:
 @completion.command("bash", context_settings=CONTEXT_SETTINGS)
 def completion_bash():
     """输出 Bash 补全脚本"""
-    script = '''
+    script = """
 _agentengine_completion() {
     local IFS=$'\\n'
     local line
@@ -165,14 +174,14 @@ _agentengine_completion() {
 }
 
 complete -o default -F _agentengine_completion agentengine
-'''
+"""
     click.echo(script.strip())
 
 
 @completion.command("zsh", context_settings=CONTEXT_SETTINGS)
 def completion_zsh():
     """输出 Zsh 补全脚本"""
-    script = '''
+    script = """
 #compdef agentengine
 
 _agentengine() {
@@ -201,18 +210,22 @@ _agentengine() {
 }
 
 compdef _agentengine agentengine
-'''
+"""
     click.echo(script.strip())
 
 
 @completion.command("install", context_settings=CONTEXT_SETTINGS)
-@click.option("--shell", type=click.Choice(["bash", "zsh", "auto"]), default="auto", 
-              help="指定 Shell 类型")
+@click.option(
+    "--shell", type=click.Choice(["bash", "zsh", "auto"]), default="auto", help="指定 Shell 类型"
+)
 def completion_install(shell: str):
     """自动安装补全脚本到 Shell 配置文件"""
     ensure_json_output_supported(
         "agentengine completion install",
-        suggestion="请直接使用 `agentengine completion bash` 或 `agentengine completion zsh` 获取脚本内容。",
+        suggestion=(
+            "请直接使用 `agentengine completion bash` 或 `agentengine completion zsh` "
+            "获取脚本内容。"
+        ),
     )
     print_title("安装自动补全")
 
@@ -224,59 +237,57 @@ def completion_install(shell: str):
         print_info("请使用 --shell=bash 或 --shell=zsh 指定")
         return
     shell = resolved_shell
-    
+
     home = Path.home()
-    
+
     if shell == "zsh":
         rc_file = home / ".zshrc"
         completion_file = home / ".agentengine-complete.zsh"
-        completion_cmd = '_AGENTENGINE_COMPLETE=zsh_source agentengine'
+        completion_cmd = "_AGENTENGINE_COMPLETE=zsh_source agentengine"
         init_line = "autoload -Uz compinit && compinit"
     else:  # bash
         rc_file = _resolve_bash_rc_file(home)
         completion_file = home / ".agentengine-complete.bash"
-        completion_cmd = '_AGENTENGINE_COMPLETE=bash_source agentengine'
+        completion_cmd = "_AGENTENGINE_COMPLETE=bash_source agentengine"
         init_line = None
-    
+
     print_kv("目标 Shell", shell, value_style="#58a6ff")
-    print_kv("配置文件", rc_file, value_style="#58a6ff")
+    print_kv("配置文件", str(rc_file), value_style="#58a6ff")
     print_info("正在安装补全脚本...")
-    
+
     # 生成补全脚本
     try:
         import subprocess
+
         env = os.environ.copy()
         env["_AGENTENGINE_COMPLETE"] = f"{shell}_source"
-        
+
         result = subprocess.run(
-            [sys.executable, "-m", "ksadk.cli"],
-            env=env,
-            capture_output=True,
-            text=True
+            [sys.executable, "-m", "ksadk.cli"], env=env, capture_output=True, text=True
         )
-        
+
         completion_script = result.stdout
-        
+
         if not completion_script.strip():
             print_error("生成补全脚本失败")
             print_info("请尝试手动安装:")
             print_info(f"{completion_cmd} > {completion_file}")
-            print_info(f'echo \'source "{completion_file}"\' >> {rc_file}')
+            print_info(f"echo 'source \"{completion_file}\"' >> {rc_file}")
             return
-        
+
         # 写入补全脚本文件
         with open(completion_file, "w") as f:
             f.write(completion_script)
-        
+
         print_success(f"补全脚本已保存到: {completion_file}")
-        
+
     except Exception as e:
         print_exception("生成补全脚本失败", e)
         print_info("请尝试手动安装:")
         print_info(f"{completion_cmd} > {completion_file}")
-        print_info(f'echo \'source "{completion_file}"\' >> {rc_file}')
+        print_info(f"echo 'source \"{completion_file}\"' >> {rc_file}")
         return
-    
+
     # 检查并更新 rc 文件
     rc_content = ""
     if rc_file.exists():
@@ -284,6 +295,7 @@ def completion_install(shell: str):
             rc_content = f.read()
 
     if shell == "zsh":
+        assert init_line is not None
         updated_rc, added_compinit = _rewrite_zsh_rc(rc_content, completion_file, init_line)
         if added_compinit:
             print_success("已添加 compinit 初始化")
@@ -297,7 +309,7 @@ def completion_install(shell: str):
             f.write(updated_rc)
     else:
         print_info("补全配置已存在，跳过")
-    
+
     print_success("安装完成")
     print_info("请运行以下命令使其生效:")
     print_kv("命令", f"source {rc_file}", value_style="#58a6ff")