Merge pull request #311 from aliyun/codex/ros-agent-cli-modes

feat(skill): support local and remote aliyun CLI modes

Author: guima-why

skills/alicloud-ros-agent/SKILL.md

@@ -5,7 +5,7 @@ description: Use Alibaba Cloud ROS Agent through its StartChat API for remote in
 
 # Alibaba Cloud ROS Agent
 
-Use the bridge at `scripts/ros_agent.py`. Its default code transport uses Alibaba Cloud credentials and Tea OpenAPI V3 signing to send ROS RPCs directly and consume StartChat SSE incrementally. Unless local policy pins a CLI Profile, it first uses a complete AK/SK pair from the same environment-variable aliases and precedence as aliyun CLI, including an optional STS token; only when no environment AK/SK is present does it use the selected CLI Profile. A pinned Profile is exclusive and never falls back to environment credentials or another Profile. A direct OAuth Profile reuses its unexpired cached STS credential without starting the CLI; when that credential is missing or expired, native aliyun CLI performs its own expiration check and refresh before the SDK reads the refreshed temporary credential. Credentials exist only inside the request path and are never accepted as bridge arguments, persisted in job state, or returned. An optional compatibility transport lets the native CLI execute the whole RPC without requiring any Python package. Run the bridge with `python3` on macOS/Linux or `py -3` on Windows.
+Use the bridge at `scripts/ros_agent.py`. Its default code transport uses Alibaba Cloud credentials and Tea OpenAPI V3 signing to send ROS RPCs directly and consume StartChat SSE incrementally. Unless local policy pins a CLI Profile, it first uses a complete AK/SK pair from the same environment-variable aliases and precedence as aliyun CLI, including an optional STS token; only when no environment AK/SK is present does it use the selected CLI Profile. A pinned Profile is exclusive and never falls back to environment credentials or another Profile. A direct OAuth Profile reuses its unexpired cached STS credential without starting the CLI; when that credential is missing or expired, native aliyun CLI performs its own expiration check and refresh before the SDK reads the refreshed temporary credential. Credentials exist only inside the request path and are never accepted as bridge arguments, persisted in job state, or returned. An optional dependency-free transport invokes the ROS CLI plugin's `start-chat` and `stop-chat` commands. Run the bridge with `python3` on macOS/Linux or `py -3` on Windows.
 
 ## Required interaction contract
 
@@ -27,13 +27,15 @@ While a Pipeline has `wireState: TASK_STATE_WORKING`, `follow` is the only obser
 
 ## Prerequisites
 
-The selected credential must be allowed to call `ros:StartChat`. Explicit cancellation additionally requires `ros:StopChat`; it is not required for an ordinary completed conversation. The default code transport requires the packages pinned in `requirements-code.txt` to be installed for the Python interpreter that runs the bridge. It does not require Alibaba Cloud CLI when complete environment AK/SK credentials are available; a CLI Profile requires its local configuration, and an expired or missing OAuth STS credential additionally requires the native CLI for refresh. The `aliyun_cli` transport has no Python package dependency and requires the installed CLI. This is installation-time setup; do not install packages or reconfigure credentials during an infrastructure task. Run the bridge check once before the first StartChat call:
+The selected credential must be allowed to call `ros:StartChat`. Explicit cancellation additionally requires `ros:StopChat`; it is not required for an ordinary completed conversation. The default code transport requires the packages pinned in `requirements-code.txt` to be installed for the Python interpreter that runs the bridge. It does not require Alibaba Cloud CLI when complete environment AK/SK credentials are available; a CLI Profile requires its local configuration, and an expired or missing OAuth STS credential additionally requires the native CLI for refresh. The `aliyun_cli` transport has no Python package dependency. Its local execution mode requires the installed CLI and a ROS plugin that provides `start-chat` and `stop-chat`; its remote execution mode expects the host's same-name `aliyun` command to forward those API invocations to a cloud CLI sandbox. Run the bridge check once before the first StartChat call:
 
 ```text
 python3 <absolute-bridge-path>/ros_agent.py check
 ```
 
-The bounded JSON result includes the effective `transport`, endpoint, Agent modes, Thinking policy, configured Profile policy, effective region, and only these non-secret fields from the credential source: `configured`, `name`, `mode`, `regionId`, and `language`. `cli` and `version` are null when the code transport does not need the CLI. In code mode, `mode: Environment` means a complete environment AK/SK pair is selected and no Profile credential is used. Use this result as the sole local readiness source. Never run `aliyun configure`, any `aliyun configure *` subcommand, enumerate profiles, or read Alibaba Cloud CLI configuration files yourself. The check deliberately excludes credential values and does not prove that a token is still accepted by ROS; the StartChat response is authoritative for authentication and authorization failures.
+The bounded JSON result includes the effective `transport`, `aliyunCLIExecutionMode`, endpoint, Agent modes, Thinking policy, configured Profile policy, effective region when locally available, and only non-secret credential metadata. `cli` and `version` are null when the code transport does not need the CLI. In code mode, `mode: Environment` means a complete environment AK/SK pair is selected and no Profile credential is used. In local CLI mode, `rosPluginReady`, `pluginAutoInstallEnabled`, and `pluginInstallRequired` describe plugin readiness. If and only if `pluginInstallRequired` is true, visibly report that the required ROS CLI plugin is being installed, run exactly `aliyun plugin install --name ros`, and then rerun `check`; never add a version, package URL, mirror, or source override. If the plugin is absent but CLI automatic plugin installation is enabled, `pluginInstallRequired` is false and the first `start-chat` invocation may install it. In remote CLI mode, `check` deliberately does not run CLI management commands or inspect local Profiles/plugins.
+
+Use the check result as the sole readiness source. Except for the one local-mode plugin install command directed by `pluginInstallRequired`, never run `aliyun configure`, `aliyun plugin`, or other discovery/management commands, enumerate profiles, or read Alibaba Cloud CLI configuration files yourself. The check deliberately excludes credential values and does not prove that a token is still accepted by ROS; the StartChat response is authoritative for authentication and authorization failures.
 
 The returned `transport` is installation policy, not an Agent choice. If `check` fails—especially with `sdk_not_installed` in code mode—report that exact readiness problem and stop. Never edit `config.json`, propose or attempt another transport, pass a transport override, or fall back to `aliyun_cli` to bypass the failure. Only the user or installation administrator may change this policy outside the infrastructure task, after which a new `check` is required.
 
@@ -54,12 +56,15 @@ The bridge reads an optional `config.json` beside this `SKILL.md`. If it is abse
 }
 ```
 
-- `transport` accepts exactly `code` or `aliyun_cli`. `code` is the default: it prefers CLI-compatible environment AK/SK credentials, otherwise loads the selected CLI Profile; an unexpired OAuth STS value is reused locally, expired or missing OAuth STS refresh is delegated to native aliyun CLI, and other supported Profile modes use the credentials SDK. It signs and sends StartChat or StopChat to the configured endpoint while exposing SSE events as they arrive. `aliyun_cli` preserves the dependency-free compatibility path in which the native CLI performs the whole RPC; its output may not become visible until the response stream ends. SDK imports are lazy and never occur in `aliyun_cli` mode. There is no silent fallback between transports. A partial environment AK/SK pair fails closed instead of falling back to another identity.
+When `transport` is `aliyun_cli`, add `"aliyunCLIExecutionMode": "local"` or `"remote"`; do not add that field to a `code` transport configuration.
+
+- `transport` accepts exactly `code` or `aliyun_cli`. `code` is the default: it prefers CLI-compatible environment AK/SK credentials, otherwise loads the selected CLI Profile; an unexpired OAuth STS value is reused locally, expired or missing OAuth STS refresh is delegated to native aliyun CLI, and other supported Profile modes use the credentials SDK. It signs and sends StartChat or StopChat to the configured endpoint while exposing SSE events as they arrive. `aliyun_cli` is the dependency-free path and invokes only the ROS plugin's validated `start-chat` and `stop-chat` operations. SDK imports are lazy and never occur in `aliyun_cli` mode. There is no silent fallback between transports. A partial environment AK/SK pair fails closed instead of falling back to another identity.
+- `aliyunCLIExecutionMode` accepts exactly `local` or `remote`, defaults to `local`, and is valid only with `transport: "aliyun_cli"`. `local` uses the native local CLI, Profile, and plugin installation. `remote` treats the same-name `aliyun` executable as a cloud-sandbox forwarder: the bridge may invoke only `aliyun ros start-chat` and `aliyun ros stop-chat`, never CLI management or another API operation. Remote mode does not read or pass a local Profile, does not infer a local region, rejects `aliyunCLIProfile`, and requires a public `*.aliyuncs.com` endpoint. All prompt and response payloads are passed inline; never pass a file-backed CLI parameter to the remote command.
 - `endpoint` fixes the ROS endpoint for every StartChat and StopChat request in a managed job. A conflicting `--endpoint` is rejected, so do not try to override this local policy. Public endpoints must be `*.aliyuncs.com` hostnames. For local integration tests only, `localhost:<port>` and `127.0.0.1:<port>` are accepted; both transports use HTTPS and skip certificate verification only for those loopback addresses.
 - `allowedAgentModes` is a non-empty allowlist containing `normal`, `pipeline`, or both. Do not invoke or suggest a mode excluded by this list.
 - `managerIdleSeconds` is an integer from 1 through 86400. It defaults to 60. The countdown starts only when no StartChat SSE worker is running—including a concurrent Sub Pipeline permission-response worker—and is refreshed by each manager request; after exit, any managed command starts a new manager automatically while preserving job state.
 - `enableThinking` is a boolean and defaults to `true`. It fixes `EnableThinking` for the whole managed job; do not pass `--no-thinking` or try to override it per request.
-- `aliyunCLIProfile` is an empty or exact CLI Profile name and defaults to empty. Empty preserves code-mode environment-AK precedence and otherwise selects the CLI's effective current Profile. A non-empty value pins that Profile for both transports, ignores environment AK/Profile selectors, and fails instead of falling back when the Profile is unavailable. Do not pass a conflicting `--profile`.
+- `aliyunCLIProfile` is an empty or exact CLI Profile name and defaults to empty. Empty preserves code-mode environment-AK precedence and otherwise selects the local CLI's effective current Profile. A non-empty value pins that Profile for code transport or local CLI execution, ignores environment AK/Profile selectors, and fails instead of falling back when the Profile is unavailable. It is invalid in remote CLI execution. Do not pass a conflicting `--profile`.
 
 Unknown fields, invalid values, and duplicate modes fail closed. Never edit `config.json` during an infrastructure task or store credentials in it; it is an administrator/user installation policy.
 
@@ -96,7 +101,7 @@ Unknown fields, invalid values, and duplicate modes fail closed. Never edit `con
 
    This invokes the ROS `StopChat` OpenAPI through the job's selected transport; it does not send a StartChat query or a natural-language cancellation message. Present the returned status immediately. `Stopped` means cancellation completed, `Stopping` means it was accepted and the existing job should be observed with `follow` from its current cursor, and `NoActiveStream` means there was no active remote stream to stop. Never call `cancel` merely because `follow` timed out, a local tool call was interrupted, or the outer Agent turn ended.
 
-Without a configured endpoint, the bridge defaults to `ros.aliyuncs.com`. Use `--endpoint <ROS endpoint>` only when the user's ROS region or network requires a different endpoint and `config.json` does not fix one. The code transport sends a generic ROS RPC with API version `2019-09-10` and `ACS3-HMAC-SHA256` signing, so it does not depend on generated StartChat metadata. The `aliyun_cli` transport requires CLI metadata for StartChat and StopChat and does not bypass API validation. Both transports identify every StartChat and StopChat request with the user-agent segment `AlibabaCloud-Agent-Skills/alibabacloud-ros-agent`.
+Without a configured endpoint, the bridge defaults to `ros.aliyuncs.com`. Use `--endpoint <ROS endpoint>` only when the user's ROS region or network requires a different endpoint and `config.json` does not fix one. The code transport sends a generic ROS RPC with API version `2019-09-10` and `ACS3-HMAC-SHA256` signing, so it does not depend on generated StartChat metadata. The `aliyun_cli` transport uses the installed/remote ROS plugin's published `start-chat` and `stop-chat` commands and does not bypass plugin validation. Both transports identify every StartChat and StopChat request with the user-agent segment `AlibabaCloud-Agent-Skills/alibabacloud-ros-agent`.
 
 ## Architecture before deployment confirmation
 
@@ -114,7 +119,7 @@ Present the deployment summary, fenced Mermaid block, and confirmation question
 
 ## Optional context and images
 
-Use `--client-context-file <json-file>` for a JSON object accepted by StartChat. Keep this file inside the workspace and exclude secrets.
+With the `code` transport only, use `--client-context-file <json-file>` for a JSON object accepted by StartChat. Keep this file inside the workspace and exclude secrets. The ROS CLI plugin does not expose ClientContext, so the bridge rejects this option for both local and remote `aliyun_cli` execution.
 
 Use `--attachments-file <json-file>` for up to five OSS-backed images. The file must be a JSON array such as: