agentscope-ai · RerankerGuo · Jul 16, 2026
diff --git a/docs/import-worker.md b/docs/import-worker.md
@@ -299,8 +299,7 @@ Create a Worker directly with a model and optional built-in skills, no ZIP neede
 
 ```bash
 bash hiclaw-import.sh worker --name bob --model claude-sonnet-4-6 \
-    --skills github-operations,git-delegation \
-    --mcp-servers github
+    --skills github-operations,git-delegation
 ```
 
 Or via YAML (preferred for repeatable deployments):
@@ -380,7 +379,6 @@ bash hiclaw-import.sh -f <resource.yaml>   # forwards to hiclaw-apply.sh (same f
 | `--package <uri>` | Remote package URI (`nacos://`, `http://`, `oss://`) | — |
 | `--model <model>` | LLM model ID | `qwen3.5-plus` |
 | `--skills <s1,s2>` | Comma-separated built-in skills | — |
-| `--mcp-servers <m1,m2>` | Comma-separated MCP servers | — |
 | `--runtime <runtime>` | Agent runtime (`openclaw`\|`copaw`\|`hermes`) | `openclaw` |
 | `--yes` | Skip interactive confirmations (swallowed by wrapper when unsupported) | off |
 
@@ -389,23 +387,26 @@ bash hiclaw-import.sh -f <resource.yaml>   # forwards to hiclaw-apply.sh (same f
 ### hiclaw-import.ps1 (PowerShell — Windows)
 
 ```powershell
-.\hiclaw-import.ps1 worker -Name <name> [-Zip <path-or-url>] [-Package <uri>] [-Model MODEL] [-Skills s1,s2] [-McpServers m1,m2] [-Runtime rt] [-Yes]
+.\hiclaw-import.ps1 worker -Name <name> [-Zip <path-or-url>] [-Package <uri>] [-Model MODEL] [-Skills s1,s2] [-Runtime rt] [-Yes]
 .\hiclaw-import.ps1 -File <resource.yaml>
 ```
 
-Parameters mirror the Bash version (no `-Prune`/`-DryRun` on YAML path).
+Parameters mirror the Bash version (no `-Prune`/`-DryRun` on YAML path). Configure
+`mcpServers` through a YAML manifest because each entry requires structured
+`name`, `url`, and `transport` fields.
 
 ### hiclaw-apply.sh (Bash — macOS/Linux)
 
 ```bash
-bash hiclaw-apply.sh -f <resource.yaml> [-- additional args passed to hiclaw apply]
+bash hiclaw-apply.sh -f <resource.yaml>
 ```
 
 | Option | Description | Default |
 |--------|-------------|---------|
 | `-f <path>` | YAML resource file (required) | — |
 
-The install script header may mention **`--prune` / `--dry-run` / `--watch`** — those are **not** implemented in `hiclaw apply` today; use explicit deletes instead.
+The wrapper advertises only `-f`/`--file`. **`--prune`**, **`--dry-run`**, and
+**`--watch`** are not implemented in `hiclaw apply`; use explicit deletes instead.
 
 ## Troubleshooting
 

diff --git a/docs/zh-cn/declarative-resource-management.md b/docs/zh-cn/declarative-resource-management.md
@@ -653,7 +653,7 @@ bash install/hiclaw-import.sh worker --name alice --package nacos://host:8848/ns
 
 # 不带包，直接创建
 bash install/hiclaw-import.sh worker --name bob --model claude-sonnet-4-6 \
-    --skills github-operations,git-delegation --mcp-servers github
+    --skills github-operations,git-delegation
 ```
 
 ### hiclaw CLI — 容器内管理

diff --git a/docs/zh-cn/import-worker.md b/docs/zh-cn/import-worker.md
@@ -296,8 +296,7 @@ bash hiclaw-import.sh worker --name devops-alice --package nacos://host:8848/nam
 
 ```bash
 bash hiclaw-import.sh worker --name bob --model claude-sonnet-4-6 \
-    --skills github-operations,git-delegation \
-    --mcp-servers github
+    --skills github-operations,git-delegation
 ```
 
 或通过 YAML（推荐用于可重复部署）：
@@ -377,7 +376,6 @@ bash hiclaw-import.sh -f <resource.yaml>   # 转发到 hiclaw-apply.sh（与 app
 | `--package <URI>` | 远程包 URI（`nacos://`、`http://`、`oss://`） | — |
 | `--model <模型>` | LLM 模型 ID | `qwen3.5-plus` |
 | `--skills <s1,s2>` | 逗号分隔的内置技能 | — |
-| `--mcp-servers <m1,m2>` | 逗号分隔的 MCP Server | — |
 | `--runtime <运行时>` | Agent 运行时（`openclaw`\|`copaw`\|`hermes`） | `openclaw` |
 | `--yes` | 跳过交互确认（包装脚本可能在底层吞掉） | 关闭 |
 
@@ -386,23 +384,25 @@ bash hiclaw-import.sh -f <resource.yaml>   # 转发到 hiclaw-apply.sh（与 app
 ### hiclaw-import.ps1（PowerShell — Windows）
 
 ```powershell
-.\hiclaw-import.ps1 worker -Name <名称> [-Zip <路径或URL>] [-Package <URI>] [-Model 模型] [-Skills s1,s2] [-McpServers m1,m2] [-Runtime rt] [-Yes]
+.\hiclaw-import.ps1 worker -Name <名称> [-Zip <路径或URL>] [-Package <URI>] [-Model 模型] [-Skills s1,s2] [-Runtime rt] [-Yes]
 .\hiclaw-import.ps1 -File <resource.yaml>
 ```
 
-参数与 Bash 版本一致（YAML 路径无 `-Prune`/`-DryRun`）。
+参数与 Bash 版本一致（YAML 路径无 `-Prune`/`-DryRun`）。`mcpServers` 的每个
+条目都需要结构化的 `name`、`url` 和 `transport` 字段，因此请通过 YAML 清单配置。
 
 ### hiclaw-apply.sh（Bash — macOS/Linux）
 
 ```bash
-bash hiclaw-apply.sh -f <resource.yaml> [-- 其余参数原样传给 hiclaw apply]
+bash hiclaw-apply.sh -f <resource.yaml>
 ```
 
 | 选项 | 说明 | 默认值 |
 |------|------|--------|
 | `-f <路径>` | YAML 资源文件（必需） | — |
 
-安装脚本头部若仍提到 **`--prune` / `--dry-run` / `--watch`**，请以当前 **`hiclaw apply` 实现为准**（未实现上述开关），改用显式 `hiclaw delete`。
+包装脚本只公开 `-f`/`--file`。当前 **`hiclaw apply`** 未实现
+**`--prune`**、**`--dry-run`** 或 **`--watch`**，请改用显式 `hiclaw delete`。
 
 ## 故障排查
 

diff --git a/install/hiclaw-apply.sh b/install/hiclaw-apply.sh
@@ -6,9 +6,9 @@
 #
 # Usage:
 #   ./hiclaw-apply.sh -f resource.yaml              # incremental apply
-#   ./hiclaw-apply.sh -f resource.yaml --prune      # full sync (delete extras)
-#   ./hiclaw-apply.sh -f resource.yaml --dry-run    # show diff only
-#   ./hiclaw-apply.sh -f resource.yaml --watch      # watch file changes
+#
+# The current `hiclaw apply` command supports -f/--file only. Delete stale
+# resources explicitly with `hiclaw delete`.
 #
 # Environment:
 #   AGENTTEAMS_CONTAINER_CMD   Override container runtime (docker/podman)

diff --git a/install/hiclaw-import.ps1 b/install/hiclaw-import.ps1
@@ -7,8 +7,8 @@
 #   .\hiclaw-import.ps1 worker -Name <name> -Zip <path-or-url>
 #   .\hiclaw-import.ps1 worker -Name <name> -Package <nacos://...> [-Model MODEL]
 #   .\hiclaw-import.ps1 worker -Name <name>                        # auto-imports package <name>
-#   .\hiclaw-import.ps1 worker -Name <name> -Model MODEL [-Skills s1,s2] [-McpServers m1,m2]
-#   .\hiclaw-import.ps1 -File <resource.yaml> [-Prune] [-DryRun]
+#   .\hiclaw-import.ps1 worker -Name <name> -Model MODEL [-Skills s1,s2] [-Runtime RUNTIME]
+#   .\hiclaw-import.ps1 -File <resource.yaml>
 
 param(
     [Parameter(Position = 0)]
@@ -19,11 +19,8 @@ param(
     [string]$Zip = "",
     [string]$Package = "",
     [string]$Skills = "",
-    [string]$McpServers = "",
     [string]$Runtime = "",
     [string]$File = "",
-    [switch]$Prune,
-    [switch]$DryRun,
     [switch]$Yes
 )
 
@@ -81,8 +78,6 @@ if ($File) {
     Write-Host "[AgentTeams Import] Copied $FileName -> container:/tmp/import/" -ForegroundColor Cyan
 
     $hiclawArgs = @("apply", "-f", "/tmp/import/$FileName")
-    if ($Prune) { $hiclawArgs += "--prune" }
-    if ($DryRun) { $hiclawArgs += "--dry-run" }
     # Accept -Yes for wrapper compatibility, but do not forward it because the
     # container-internal hiclaw CLI does not support --yes.
 
@@ -141,9 +136,7 @@ switch ($ResourceType) {
         if ($Model) { $hiclawArgs += @("--model", $Model) }
         if ($Package) { $hiclawArgs += @("--package", $Package) }
         if ($Skills) { $hiclawArgs += @("--skills", $Skills) }
-        if ($McpServers) { $hiclawArgs += @("--mcp-servers", $McpServers) }
         if ($Runtime) { $hiclawArgs += @("--runtime", $Runtime) }
-        if ($DryRun) { $hiclawArgs += "--dry-run" }
 
         & $ContainerCmd exec agentteams-manager hiclaw @hiclawArgs
         exit $LASTEXITCODE
@@ -154,8 +147,8 @@ switch ($ResourceType) {
         Write-Host "  .\hiclaw-import.ps1 worker -Name <name> -Zip <path-or-url>"
         Write-Host "  .\hiclaw-import.ps1 worker -Name <name> -Package <nacos://...> [-Model MODEL]"
         Write-Host "  .\hiclaw-import.ps1 worker -Name <name>                        # auto-import package <name>"
-        Write-Host "  .\hiclaw-import.ps1 worker -Name <name> -Model MODEL [-Skills s1,s2] [-McpServers m1,m2]"
-        Write-Host "  .\hiclaw-import.ps1 -File <resource.yaml> [-Prune] [-DryRun]"
+        Write-Host "  .\hiclaw-import.ps1 worker -Name <name> -Model MODEL [-Skills s1,s2] [-Runtime RUNTIME]"
+        Write-Host "  .\hiclaw-import.ps1 -File <resource.yaml>"
         exit 0
     }
 

diff --git a/install/hiclaw-import.sh b/install/hiclaw-import.sh
@@ -8,8 +8,8 @@
 #   ./hiclaw-import.sh worker --name <name> --zip <path-or-url> [--yes]
 #   ./hiclaw-import.sh worker --name <name> --package <nacos://...> [--model MODEL]
 #   ./hiclaw-import.sh worker --name <name>                         # auto-imports package <name>
-#   ./hiclaw-import.sh worker --name <name> --model MODEL [--skills s1,s2] [--mcp-servers m1,m2]
-#   ./hiclaw-import.sh -f <resource.yaml> [--prune] [--dry-run]
+#   ./hiclaw-import.sh worker --name <name> --model MODEL [--skills s1,s2] [--runtime RUNTIME]
+#   ./hiclaw-import.sh -f <resource.yaml>
 #
 # Environment variables (for automation):
 #   AGENTTEAMS_NON_INTERACTIVE       Skip all prompts (same as --yes)
@@ -84,10 +84,8 @@ case "${RESOURCE_TYPE}" in
                     PACKAGE_URI="$2"
                     AGENTTEAMS_ARGS+=("$1" "$2")
                     shift 2 ;;
-                --model|--skills|--mcp-servers|--runtime)
+                --model|--skills|--runtime)
                     AGENTTEAMS_ARGS+=("$1" "$2"); shift 2 ;;
-                --dry-run)
-                    AGENTTEAMS_ARGS+=("$1"); shift ;;
                 --yes)
                     shift ;;
                 *) echo "Unknown option: $1"; exit 1 ;;
@@ -125,8 +123,8 @@ case "${RESOURCE_TYPE}" in
         echo "  $0 worker --name <name> --zip <path-or-url>"
         echo "  $0 worker --name <name> --package <nacos://...> [--model MODEL]"
         echo "  $0 worker --name <name>                         # auto-import package <name>"
-        echo "  $0 worker --name <name> --model MODEL [--skills s1,s2] [--mcp-servers m1,m2]"
-        echo "  $0 -f <resource.yaml> [--prune] [--dry-run]"
+        echo "  $0 worker --name <name> --model MODEL [--skills s1,s2] [--runtime RUNTIME]"
+        echo "  $0 -f <resource.yaml>"
         exit 0
         ;;
 

diff --git a/install/tests/test-import-wrapper-contract.sh b/install/tests/test-import-wrapper-contract.sh
@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+BASH_IMPORT="${ROOT_DIR}/install/hiclaw-import.sh"
+POWERSHELL_IMPORT="${ROOT_DIR}/install/hiclaw-import.ps1"
+TEST_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/agentteams-import-contract.XXXXXX")"
+trap 'rm -rf "${TEST_ROOT}"' EXIT
+
+FAKE_BIN="${TEST_ROOT}/bin"
+FAKE_DOCKER_CAPTURE="${TEST_ROOT}/docker-args.txt"
+TEST_HOME="${TEST_ROOT}/home"
+mkdir -p "${FAKE_BIN}" "${TEST_HOME}/cache" "${TEST_HOME}/config" "${TEST_HOME}/data"
+export FAKE_DOCKER_CAPTURE
+
+cat > "${FAKE_BIN}/docker" <<'EOF'
+#!/usr/bin/env bash
+set -e
+
+case "${1:-}" in
+    info)
+        exit 0
+        ;;
+    ps)
+        printf '%s\n' agentteams-manager
+        exit 0
+        ;;
+    cp)
+        exit 0
+        ;;
+    exec)
+        if [ "${3:-}" = "mkdir" ]; then
+            exit 0
+        fi
+        printf '%s\n' "$@" > "${FAKE_DOCKER_CAPTURE}"
+        exit 0
+        ;;
+esac
+
+printf 'unexpected docker invocation: %s\n' "$*" >&2
+exit 1
+EOF
+chmod +x "${FAKE_BIN}/docker"
+
+PASS=0
+FAIL=0
+RUN_OUTPUT=""
+RUN_RC=0
+
+pass() {
+    printf 'PASS: %s\n' "$1"
+    PASS=$((PASS + 1))
+}
+
+fail() {
+    printf 'FAIL: %s\n' "$1" >&2
+    FAIL=$((FAIL + 1))
+}
+
+run_bash_import() {
+    set +e
+    RUN_OUTPUT="$(PATH="${FAKE_BIN}:${PATH}" bash "${BASH_IMPORT}" "$@" 2>&1)"
+    RUN_RC=$?
+    set -e
+}
+
+run_powershell_import() {
+    local pwsh_bin="$1"
+    shift
+    set +e
+    RUN_OUTPUT="$(
+        HOME="${TEST_HOME}" \
+        XDG_CACHE_HOME="${TEST_HOME}/cache" \
+        XDG_CONFIG_HOME="${TEST_HOME}/config" \
+        XDG_DATA_HOME="${TEST_HOME}/data" \
+        POWERSHELL_TELEMETRY_OPTOUT=1 \
+        PATH="${FAKE_BIN}:${PATH}" \
+        "${pwsh_bin}" -NoProfile -File "${POWERSHELL_IMPORT}" "$@" 2>&1
+    )"
+    RUN_RC=$?
+    set -e
+}
+
+assert_rejected() {
+    local label="$1"
+    local expected="$2"
+    if [ "${RUN_RC}" -ne 0 ] && [[ "${RUN_OUTPUT}" == *"${expected}"* ]]; then
+        pass "${label}"
+    else
+        fail "${label}: rc=${RUN_RC}, output=${RUN_OUTPUT}"
+    fi
+}
+
+assert_not_advertised() {
+    local label="$1"
+    local flag="$2"
+    if [[ "${RUN_OUTPUT}" != *"${flag}"* ]]; then
+        pass "${label}"
+    else
+        fail "${label}: help still contains ${flag}"
+    fi
+}
+
+run_bash_import worker --name alice --skills github-operations
+if [ "${RUN_RC}" -eq 0 ] && grep -Fxq -- '--skills' "${FAKE_DOCKER_CAPTURE}"; then
+    pass "Bash forwards supported worker flags"
+else
+    fail "Bash did not forward supported worker flags"
+fi
+
+run_bash_import worker --name alice --mcp-servers github
+assert_rejected "Bash rejects removed --mcp-servers" "Unknown option: --mcp-servers"
+
+run_bash_import worker --name alice --dry-run
+assert_rejected "Bash rejects unimplemented --dry-run" "Unknown option: --dry-run"
+
+run_bash_import --help
+assert_not_advertised "Bash help omits removed MCP flag" "--mcp-servers"
+assert_not_advertised "Bash help omits unimplemented dry-run flag" "--dry-run"
+assert_not_advertised "Bash help omits unimplemented prune flag" "--prune"
+
+if grep -Eq -- '--prune|--dry-run|--watch' "${ROOT_DIR}/install/hiclaw-apply.sh"; then
+    fail "Bash apply wrapper still advertises unimplemented flags"
+else
+    pass "Bash apply wrapper omits unimplemented flags"
+fi
+
+PWSH_BIN="${PWSH_BIN:-$(command -v pwsh || true)}"
+if [ -n "${PWSH_BIN}" ]; then
+    run_powershell_import "${PWSH_BIN}" worker -Name alice -Skills github-operations
+    if [ "${RUN_RC}" -eq 0 ] && grep -Fxq -- '--skills' "${FAKE_DOCKER_CAPTURE}"; then
+        pass "PowerShell forwards supported worker parameters"
+    else
+        fail "PowerShell did not forward supported worker parameters"
+    fi
+
+    run_powershell_import "${PWSH_BIN}" worker -Name alice -McpServers github
+    assert_rejected "PowerShell rejects removed -McpServers" "parameter name 'McpServers'"
+
+    run_powershell_import "${PWSH_BIN}" worker -Name alice -DryRun
+    assert_rejected "PowerShell rejects unimplemented -DryRun" "parameter name 'DryRun'"
+
+    run_powershell_import "${PWSH_BIN}" worker -Name alice -Prune
+    assert_rejected "PowerShell rejects unimplemented -Prune" "parameter name 'Prune'"
+
+    run_powershell_import "${PWSH_BIN}"
+    assert_not_advertised "PowerShell help omits removed MCP parameter" "McpServers"
+    assert_not_advertised "PowerShell help omits unimplemented dry-run parameter" "DryRun"
+    assert_not_advertised "PowerShell help omits unimplemented prune parameter" "Prune"
+else
+    printf 'SKIP: pwsh is unavailable; PowerShell runtime assertions skipped\n'
+fi
+
+printf '\nResults: %d passed, %d failed\n' "${PASS}" "${FAIL}"
+if [ "${FAIL}" -ne 0 ]; then
+    exit 1
+fi