feat(harness): update same-name runtime in place + keep deploy creds off the runtime

deploy --harness now resolves a name collision instead of always failing:
- single existing harness runtime -> prompt (or --yes) to update it in place;
  the platform releases a new version. Echoes the version before and after.
- non-harness same-name runtime, or multiple matches -> fast-fail.
- non-interactive (no tty) without --yes -> fast-fail.

build_agentkit_config gains a runtime_id arg (Auto = create, real id = update,
which the runner routes to UpdateRuntime/ReleaseRuntime).

Credential safety: a local .env is loaded for deploy auth, but the Volcengine
deploy credentials in it are no longer uploaded into the runtime environment
(the runtime authenticates via its IAM role). Implemented via an opt-in
COMPAT_ENV_EXCLUDE applied to the veADK-compat env layer; other .env keys and
spec-provided credentials are unaffected.

Docs: HARNESS_QUICKSTART.md updated (--yes, same-name update, credential note).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: yaozheng-fang

HARNESS_QUICKSTART.md

@@ -0,0 +1,228 @@
+# AgentKit Harness 全流程
+
+## 1. init —— 初始化项目
+
+用 harness 模板在当前目录创建项目脚手架（含 `.env.example`、`Dockerfile`）。
+
+```bash
+agentkit init my-harness -t harness
+```
+
+## 2. add harness —— 生成 Harness 配置
+
+创建/更新 `<name>.harness.json`，设置模型、工具、技能、系统提示等。
+
+```bash
+agentkit add harness --name my-harness \
+  --model-name doubao-seed-1-6-250615 \
+  --tools web_search \
+  --system-prompt "You are a helpful assistant."
+```
+
+### 2.1 通过 OAuth（用户池）鉴权部署
+
+默认情况下 harness 部署后用 API Key（`key_auth`）鉴权。
+若希望用火山引擎**用户池**签发的 JWT 来网关鉴权（`custom_jwt`），
+在 `add harness` 时传入用户池的 `--discovery-url` 和允许的客户端 `--allowed-id`。
+二者会被写入 `<name>.harness.json` 的 `auth` 块，
+后续 `deploy` 会自动据此把运行时切换为 OAuth2/JWT 鉴权。
+
+```bash
+agentkit add harness --name my-harness \
+  --model-name doubao-seed-1-6-250615 \
+  --discovery-url "https://userpool-<userpool-id>.userpool.auth.id.cn-beijing.volces.com/.well-known/openid-configuration" \
+  --allowed-id "<client-id-1>,<client-id-2>"
+```
+
+- `--discovery-url`：用户池的 OIDC discovery 地址，其中 `<userpool-id>` 即在火山引擎身份中心创建的用户池 ID。
+- `--allowed-id`：允许访问该运行时的客户端 ID（即 JWT 的 audience），逗号分隔。
+
+写入后 `my-harness.harness.json` 会包含：
+
+```json
+{
+  "harness_name": "my-harness",
+  "auth": {
+    "discovery_url": "https://userpool-<userpool-id>.userpool.auth.id.cn-beijing.volces.com/.well-known/openid-configuration",
+    "allowed_ids": ["<client-id-1>", "<client-id-2>"]
+  }
+}
+```
+
+说明：
+
+- 用户池、客户端、外部 IdP 需先在火山引擎身份中心控制台创建；CLI 只引用它们的 ID，不涉及任何密钥。
+- `discovery_url` 与 `allowed_ids` 必须同时提供，否则部署时快速失败。
+- 也可在部署时用 `agentkit deploy --harness my-harness --discovery-url ... --allowed-id ...` 临时覆盖 `auth` 块。
+- 采用 OAuth2/JWT 后，调用时不再使用 API Key，而需携带用户池签发的 JWT：`agentkit invoke harness my-harness -ak <jwt> "..."`（CLI 不负责签发该 JWT）。
+
+## 3. deploy —— 部署为云端运行时
+
+读取 `my-harness.harness.json` 做云端构建并创建运行时，结果记录到 `harness.json`。
+
+```bash
+agentkit deploy --harness my-harness
+```
+
+完整参数：
+
+- `--harness <name>` 部署 `<name>.harness.json`（云端构建+部署），而非 `agentkit.yaml`
+- `--config-file <path>` 配置文件，默认 `agentkit.yaml`
+- `--region <region>` AgentKit 区域（harness 部署）
+- `--volcengine-access-key <ak>` Volcengine 访问密钥（harness 部署）
+- `--volcengine-secret-key <sk>` Volcengine 密钥（harness 部署）
+- `--discovery-url <url>` OIDC discovery URL，启用 OAuth2/JWT 鉴权
+- `--allowed-id <ids>` 允许的 client ID，逗号分隔（OAuth2/JWT）
+- `--yes, -y` 存在同名 harness 时直接更新为新版本，不再交互询问（CI / 非交互场景）
+
+> AK/SK 未显式传入时，会自动从环境变量或 `.env` 读取（见各命令通用的凭证解析）。
+
+### 3.1 同名处理：新建 or 更新
+
+部署前会按名称在云端查重，据此决定行为：
+
+- **无同名** → 新建运行时（版本从 `v1` 开始）；
+- **已存在同名 harness** → 回显其当前版本号并询问是否更新（`[y/N]`，或用 `--yes` 跳过）；
+  确认后**原地更新**同一运行时（`runtime_id` 不变，平台发布为新版本），完成后回显新版本号；
+- **同名但不是 harness** 应用（无 `agentkit:agenttype=harness` 标签）→ 拒绝部署，避免误改非 harness 运行时；
+- **存在多个同名** → 报错，需先清理后再部署；
+- **非交互**（无 TTY）且未带 `--yes` → 直接快速失败，不阻塞管道。
+
+```bash
+# 同名已存在时，直接更新为新版本（不询问）
+agentkit deploy --harness my-harness --yes
+```
+
+更新成功时会看到类似：
+
+```text
+Updating Runtime: r-ye9j62wydcn****hsoa
+✅ Harness 'my-harness' updated to version v2.
+```
+
+### 3.2 凭证安全：`.env` 的火山 AK/SK 不会上云
+
+当前目录的 `.env` 仅用于**本地部署鉴权**。其中的火山引擎部署凭证
+（`VOLCENGINE_ACCESS_KEY` / `VOLCENGINE_SECRET_KEY` 等）**不会**被写入云端运行时的环境变量——
+运行时通过自身 IAM 角色（`RUNTIME_IAM_ROLE_TRN`）鉴权。`.env` 中的其它变量仍会正常合并进运行时环境。
+
+> 若 harness 确实需要在运行时使用某些火山凭证（例如 Viking 知识库），应在 `<name>.harness.json`
+> 的对应组件中显式声明，而不是依赖 `.env`——它们的优先级更高，不受上述排除影响。
+
+## 4. list harness —— 列出已部署的 Harness 运行时
+
+使用环境变量中的火山引擎凭证（AK/SK）列出**所有可见的运行时**，再筛选出在部署时被打上 harness 标签（`agentkit:agenttype=harness`，由 `deploy` 自动写入）的运行时并展示。
+
+```bash
+agentkit list harness
+```
+
+表格输出包含 `RuntimeId`、`Name`、`Status`、`Version`（当前发布版本号 `CurrentVersionNumber`）、`ProjectName`、`UpdatedAt` 等列：
+
+```text
+                       Harness Runtimes (Count: 1)
+┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ RuntimeId             ┃ Name       ┃ Status┃ Version ┃ ProjectName ┃ UpdatedAt           ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│ r-ye9j62wydcn****hsoa │ my-harness │ Ready │ 1       │ default     │ 2026-06-18 10:24:01 │
+└───────────────────────┴────────────┴───────┴─────────┴─────────────┴─────────────────────┘
+```
+
+完整选项：
+
+- `--region <region>` 区域覆盖（如 `cn-beijing`、`cn-shanghai`），默认取 `VOLCENGINE_AGENTKIT_REGION` / `VOLCENGINE_REGION` / 全局配置
+- `--output <fmt>` 输出格式：`table`（默认）、`json`、`yaml`
+- `--quiet, -q` 仅打印 `RuntimeId`（便于脚本消费）
+- `--no-color, -nc` 关闭彩色输出
+- `--limit, -l <n>` 翻页时每批拉取的运行时数量（默认 `50`），命令始终遍历全部分页
+
+```bash
+# 仅打印 RuntimeId
+agentkit list harness --quiet
+
+# JSON 输出并指定区域
+agentkit list harness --output json --region cn-beijing
+```
+
+> 该命令会自动按 `NextToken` 游标翻页，遍历全部运行时后再做筛选，因此位于任意分页上的 harness 运行时都不会遗漏。
+
+## 5. invoke —— 测试调用
+
+按名称向已部署的 harness 发送一条 prompt 进行验证。
+
+```bash
+agentkit invoke harness my-harness "你好，帮我算 2+2"
+```
+
+位置参数（必填）：
+
+- `NAME` 已部署的 harness 名称（从 `harness.json` 注册表查找）
+- `MESSAGE` 要发送的 prompt
+
+完整选项（覆写仅对本次调用生效，不会持久化；只发送显式传入的字段）：
+
+- `--directory <dir>` `harness.json` 所在目录，默认 `.`
+- `--user-id <id>` 本次运行的 user_id，默认 `agentkit_user`
+- `--session-id <id>` 本次运行的 session_id，默认 `agentkit_sample_session`
+- `--max-llm-calls <n>` 覆写本次调用的最大 LLM 调用数
+- `--system-prompt <text>` 覆写系统提示
+- `--model-name <name>` 覆写模型名
+- `--tools <list>` 覆写工具，逗号分隔（增量添加）
+- `--skills <list>` 覆写技能，逗号分隔（增量添加）
+- `--runtime <name>` 覆写 runtime 后端
+- `--apikey, -ak <token>` Bearer token（如 custom_jwt harness 的 OAuth JWT）
+- `--raw` 打印原始 `InvokeHarnessResponse` JSON
+
+```bash
+# 单次覆写示例
+agentkit invoke harness my-harness --system-prompt "Be terse." "What is 2+2?"
+agentkit invoke harness my-harness --max-llm-calls 10 "Plan a trip."
+```
+
+## 6. logs —— 查询运行时日志
+
+查询该 harness 运行时的日志（默认最近 15 分钟、最多 200 条）；普通 Agent 应用会提示「非 Harness 应用，无法查询日志」。
+
+```bash
+# 默认查询（最近 15 分钟）
+agentkit logs --harness my-harness
+
+# 相对时间窗口 + 写入文件（--since 支持 1h/30m/2d/1h30m，与 --start 互斥）
+agentkit logs --harness my-harness --since 1h --output ./logs/my-harness.log
+
+# 调整条数与排序
+agentkit logs --harness my-harness --limit 50 --sort asc
+```
+
+## 7. skill —— 安装/管理技能
+
+管理单个 Skill。`--skill-space` 为可选项：以 `ss-` 开头按 ID 处理，否则按名称解析；不传则只作用于 Skill 本身。
+
+安装：先获取临时 TOS URL，再创建 Skill。带 `--skill-space` 时额外加入该 SkillSpace。
+新建后处于 `creating`，默认轮询至 `running`（`--no-wait` 可跳过）。
+
+```bash
+# 仅创建 Skill
+agentkit skill install theme-factory
+
+# 创建并加入 SkillSpace（名称或 ss- ID 均可）
+agentkit skill install theme-factory --skill-space agentkit_skill_space_hehy8dw
+```
+
+列出：不带 space 列出全部 Skill；带 space 列出该 SkillSpace 内的 Skill。
+
+```bash
+agentkit skill list
+agentkit skill list --skill-space agentkit_skill_space_hehy8dw
+```
+
+卸载：带 `--skill-space` 仅从该 SkillSpace 移除（保留 Skill）。
+不带 space 则删除整个 Skill（需确认，`--force` 跳过）。
+
+```bash
+# 仅从 SkillSpace 移除
+agentkit skill uninstall theme-factory --skill-space agentkit_skill_space_hehy8dw
+
+# 删除整个 Skill
+agentkit skill uninstall theme-factory --force
+```

agentkit/toolkit/cli/cli_deploy.py

@@ -15,7 +15,7 @@
 """AgentKit CLI - Deploy command implementation."""
 
 from pathlib import Path
-from typing import Optional
+from typing import Callable, Dict, Optional
 
 import typer
 from rich.console import Console
@@ -25,6 +25,17 @@
 console = Console()
 
 
+def _prompt_harness_update(info: Dict) -> bool:
+    """Interactive [y/N] confirmation to update an existing same-name harness."""
+    version = info.get("version")
+    version_label = f"v{version}" if version is not None else "unknown"
+    return typer.confirm(
+        f"Harness '{info['name']}' already exists (current version "
+        f"{version_label}). Update it to a new version?",
+        default=False,
+    )
+
+
 def deploy_command(
     config_file: Path = typer.Option("agentkit.yaml", help="Configuration file"),
     harness: Optional[str] = typer.Option(
@@ -52,6 +63,12 @@ def deploy_command(
         "--allowed-id",
         help="Comma-separated allowed client IDs for OAuth2/JWT auth (harness deploy).",
     ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Harness deploy: update an existing same-name harness without prompting.",
+    ),
 ):
     """Deploy the Agent to target environment."""
     from agentkit.toolkit.executors import DeployExecutor
@@ -66,6 +83,7 @@ def deploy_command(
             secret_key=volcengine_secret_key,
             discovery_url=discovery_url,
             allowed_id=allowed_id,
+            assume_yes=yes,
         )
         return
 
@@ -107,9 +125,12 @@ def _deploy_harness(
     secret_key,
     discovery_url,
     allowed_id,
+    assume_yes: bool = False,
 ):
     """Deploy a harness spec <name>.harness.json from the current directory."""
-    from agentkit.toolkit.sdk import deploy_harness
+    import sys
+
+    from agentkit.toolkit.sdk import deploy_harness, HarnessDeployAborted
     from agentkit.toolkit.cli.console_reporter import ConsoleReporter
     from agentkit.toolkit.context import ExecutionContext
 
@@ -118,6 +139,16 @@ def _deploy_harness(
     reporter = ConsoleReporter()
     ExecutionContext.set_reporter(reporter)
 
+    # Decide how a same-name harness collision is resolved:
+    #   --yes        -> update without prompting
+    #   tty          -> prompt [y/N]
+    #   non-tty      -> on_conflict=None, so deploy_harness fast-fails
+    on_conflict: Optional[Callable[[Dict], bool]] = None
+    if assume_yes:
+        on_conflict = lambda info: True  # noqa: E731
+    elif sys.stdin.isatty():
+        on_conflict = _prompt_harness_update
+
     # Surface fast-fail input/validation errors (missing spec, missing creds,
     # name collision) as a clean CLI error + exit code, not a raw traceback.
     try:
@@ -129,7 +160,11 @@ def _deploy_harness(
             discovery_url=discovery_url,
             allowed_id=allowed_id,
             reporter=reporter,
+            on_conflict=on_conflict,
         )
+    except HarnessDeployAborted:
+        console.print("[yellow]Harness deploy cancelled.[/yellow]")
+        return
     except (ValueError, FileNotFoundError, NotADirectoryError) as exc:
         console.print(f"[red]❌ Harness deploy failed: {exc}[/red]")
         raise typer.Exit(1)

agentkit/toolkit/config/utils.py

@@ -82,13 +82,26 @@ def load_veadk_yaml_file(project_dir: Path) -> Dict[str, str]:
         return {}
 
 
+# Opt-in denylist of env keys to drop from the veADK-compat (.env / config.yaml)
+# layer before it is merged into a runtime's uploaded environment. Empty by
+# default (no-op). A deploy flow may populate it (scoped, restored afterwards) to
+# keep deploy-only secrets in a local `.env` from leaking into the cloud runtime;
+# e.g. harness deploy excludes the Volcengine deploy credentials here. Compared
+# case-insensitively. Higher-priority sources (agentkit.yaml runtime_envs) are
+# unaffected, so a value explicitly set there still reaches the runtime.
+COMPAT_ENV_EXCLUDE: set = set()
+
+
 def load_compat_config_files(project_dir: Optional[Path] = None) -> Dict[str, str]:
     """Load compatibility configuration files (.env and veADK config.yaml).
 
     This function loads external configuration files for veADK compatibility:
     1. Load standard .env file if exists (higher priority)
     2. Load veADK config.yaml file if exists and flatten nested structure (lower priority)
 
+    Keys listed in :data:`COMPAT_ENV_EXCLUDE` are dropped from the result (used to
+    keep deploy-only credentials out of the uploaded runtime environment).
+
     Args:
         project_dir: Project directory to search for files. If None, uses current working directory.
 
@@ -102,6 +115,10 @@ def load_compat_config_files(project_dir: Optional[Path] = None) -> Dict[str, st
     veadk_envs.update(load_veadk_yaml_file(project_dir))
     veadk_envs.update(load_dotenv_file(project_dir))
 
+    if COMPAT_ENV_EXCLUDE:
+        excluded = {k.upper() for k in COMPAT_ENV_EXCLUDE}
+        veadk_envs = {k: v for k, v in veadk_envs.items() if k.upper() not in excluded}
+
     return veadk_envs
 
 

agentkit/toolkit/harness/__init__.py

@@ -15,12 +15,13 @@
 """Harness deploy support: flatten a layered harness spec and deploy it as a runtime."""
 
 from .config_builder import build_agentkit_config
-from .deploy import deploy_harness, load_harness_registry
+from .deploy import HarnessDeployAborted, deploy_harness, load_harness_registry
 from .env_mapping import to_runtime_env
 
 __all__ = [
     "to_runtime_env",
     "build_agentkit_config",
     "deploy_harness",
     "load_harness_registry",
+    "HarnessDeployAborted",
 ]