huaweicloud-devkit 1.0.2-next.2 → 1.0.2-next.21

package/plugins/huaweicloud-core/skills/huawei-rds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: huawei-rds
-description: "Use when creating, configuring, managing, or troubleshooting RDS instances on Huawei Cloud. Covers MySQL, PostgreSQL, SQL Server. Triggers: RDS, MySQL, PostgreSQL, database instance, backup, read replica. NOT for: GaussDB (use huawei-gaussdb), DDS (use huawei-dds-dcs)."
+description: 'Use when creating, configuring, managing, or troubleshooting RDS instances on Huawei Cloud. Covers MySQL, PostgreSQL, SQL Server. Triggers: RDS, MySQL, PostgreSQL, database instance, backup, read replica. NOT for: GaussDB (use huawei-gaussdb), DDS (use huawei-dds-dcs).'
 version: 1
 ---
 
@@ -13,6 +13,7 @@ Always run `hcloud RDS <Operation> --help` before constructing commands to disco
 ## Prerequisites
 
 Before creating an RDS instance, you MUST have:
+
 - A VPC and subnet (see `huawei-vpc`)
 - A security group with database port open (MySQL=3306, PostgreSQL=5432, SQL Server=1433)
 - Run `hcloud RDS ListFlavors --database_name=<engine> --cli-region=<r>` to get spec codes
@@ -23,32 +24,33 @@ Before creating an RDS instance, you MUST have:
 hcloud RDS <Operation> --cli-region=<region> [--key=value ...]
 ```
 
-| Rule | Detail |
-|------|--------|
-| Service name | `RDS` (uppercase) |
-| Operation | PascalCase: `ListInstances`, `CreateManualBackup` |
-| Params | `--key=value` format. JSON params: `--key='{"k":"v"}'` |
-| Array params | 1-based: `--instance_ids.1=xxx` |
+| Rule           | Detail                                                                            |
+| -------------- | --------------------------------------------------------------------------------- |
+| Service name   | `RDS` (uppercase)                                                                 |
+| Operation      | PascalCase: `ListInstances`, `CreateManualBackup`                                 |
+| Params         | `--key=value` format. JSON params: `--key='{"k":"v"}'`                            |
+| Array params   | 1-based: `--instance_ids.1=xxx`                                                   |
 | Password param | Conflicts with KooCLI system param; use `--cli-jsonInput` (see Critical Warnings) |
 
 ## Critical Warnings
 
-| Trap | Why |
-|------|-----|
-| Engine version immutable | Cannot change MySQL to PostgreSQL in-place |
-| Automated backups use OBS | Backup storage incurs separate charges. Set retention period explicitly |
-| Storage auto-scaling off by default | Enable before storage runs out or instance goes read-only |
-| `--password` conflicts with KooCLI | Use `--cli-jsonInput=<file>` with JSON file (see `--cli-jsonInput` section below). The `printf "b\n"` workaround is broken in KooCLI 7.2.12+ |
-| Volume type must match flavor | General→CLOUDSSD; Dedicated→CLOUDSSD\|ESSD; ARM→ULTRAHIGH |
-| Flavor not in region | Always `ListFlavors` first. Spec codes vary by region |
-| `database_name` is case-sensitive | Use `MySQL` / `PostgreSQL` / `SQLServer` / `MariaDB` — NOT lower-case `mysql` |
-| Instance creation takes 3–8 min | Status: BUILD→MODIFYING→ACTIVE. Poll every 15s: `hcloud RDS ListInstances --cli-region=<r> --instance_id=<id> \| jq '.instances[0].status'` |
-| Body `--region` is required | CreateInstance body requires `--region=<r>` (same as `--cli-region`) or `DBS.280243` |
-| Restore creates new instance | No in-place restore. Verify target flavor before restoring |
+| Trap                                | Why                                                                                                                                          |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Engine version immutable            | Cannot change MySQL to PostgreSQL in-place                                                                                                   |
+| Automated backups use OBS           | Backup storage incurs separate charges. Set retention period explicitly                                                                      |
+| Storage auto-scaling off by default | Enable before storage runs out or instance goes read-only                                                                                    |
+| `--password` conflicts with KooCLI  | Use `--cli-jsonInput=<file>` with JSON file (see `--cli-jsonInput` section below). The `printf "b\n"` workaround is broken in KooCLI 7.2.12+ |
+| Volume type must match flavor       | General→CLOUDSSD; Dedicated→CLOUDSSD\|ESSD; ARM→ULTRAHIGH                                                                                    |
+| Flavor not in region                | Always `ListFlavors` first. Spec codes vary by region                                                                                        |
+| `database_name` is case-sensitive   | Use `MySQL` / `PostgreSQL` / `SQLServer` / `MariaDB` — NOT lower-case `mysql`                                                                |
+| Instance creation takes 3–8 min     | Status: BUILD→MODIFYING→ACTIVE. Poll every 15s: `hcloud RDS ListInstances --cli-region=<r> --instance_id=<id> \| jq '.instances[0].status'`  |
+| Body `--region` is required         | CreateInstance body requires `--region=<r>` (same as `--cli-region`) or `DBS.280243`                                                         |
+| Restore creates new instance        | No in-place restore. Verify target flavor before restoring                                                                                   |
 
 ## Instance Management
 
 ### List
+
 ```bash
 hcloud RDS ListInstances --cli-region=<r>
 hcloud RDS ListFlavors --database_name=<engine> --cli-region=<r>
@@ -57,6 +59,7 @@ hcloud RDS ListEngineFlavors --instance_id=<id> --cli-region=<r>
 ```
 
 ### Create Instance
+
 ```bash
 hcloud RDS CreateInstance --cli-region=<r> \
   --region=<r> \
@@ -101,21 +104,22 @@ hcloud RDS CreateInstance --cli-region=<r> \
 
 > Save as `rds-create.json` then: `hcloud RDS CreateInstance --cli-jsonInput=rds-create.json`. For `project_id`, run `hcloud IAM KeystoneListProjects`.
 
-| Param | Required | Note |
-|-------|----------|------|
-| `--name` | Yes | Instance name |
-| `--datastore` | Yes | `--datastore.type=<engine> --datastore.version=<version>` |
-| `--flavor_ref` | Yes | From `ListFlavors` output |
-| `--volume` | Yes | Type matching: General→CLOUDSSD, Dedicated→CLOUDSSD\|ESSD, ARM→ULTRAHIGH |
-| `--vpc_id` | Yes | Must exist in target region |
-| `--subnet_id` | Yes | Must exist in target region |
-| `--security_group_id` | Yes | Must have DB port open |
-| `--availability_zone` | Yes | Use AZ code from `NovaListAvailabilityZones` |
-| `--charge_info` | No | `--charge_info.charge_mode=<mode>`. Default postPaid (pay-per-use). Run `--help` for options |
-| `--password` | Yes | 8-32 chars, uppercase+lowercase+digit+special |
-| `--port` | No | Default 3306 (MySQL) / 5432 (PG) / 1433 (SQL Server) |
+| Param                 | Required | Note                                                                                         |
+| --------------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `--name`              | Yes      | Instance name                                                                                |
+| `--datastore`         | Yes      | `--datastore.type=<engine> --datastore.version=<version>`                                    |
+| `--flavor_ref`        | Yes      | From `ListFlavors` output                                                                    |
+| `--volume`            | Yes      | Type matching: General→CLOUDSSD, Dedicated→CLOUDSSD\|ESSD, ARM→ULTRAHIGH                     |
+| `--vpc_id`            | Yes      | Must exist in target region                                                                  |
+| `--subnet_id`         | Yes      | Must exist in target region                                                                  |
+| `--security_group_id` | Yes      | Must have DB port open                                                                       |
+| `--availability_zone` | Yes      | Use AZ code from `NovaListAvailabilityZones`                                                 |
+| `--charge_info`       | No       | `--charge_info.charge_mode=<mode>`. Default postPaid (pay-per-use). Run `--help` for options |
+| `--password`          | Yes      | 8-32 chars, uppercase+lowercase+digit+special                                                |
+| `--port`              | No       | Default 3306 (MySQL) / 5432 (PG) / 1433 (SQL Server)                                         |
 
 ### Modify / Resize
+
 ```bash
 hcloud RDS StartInstanceRestartAction --instance_id=<id> --cli-region=<r>
 hcloud RDS StartResizeFlavorAction --instance_id=<id> --flavor_ref=<new-id> --cli-region=<r>
@@ -125,6 +129,7 @@ hcloud RDS UpdateInstanceAlias --instance_id=<id> --alias=<new-name> --cli-regio
 ```
 
 ### Delete
+
 ```bash
 hcloud RDS DeleteInstance --instance_id=<id> --cli-region=<r>
 ```
@@ -172,41 +177,41 @@ psql -h <private_ip> -p 5432 -U root -d postgres
 
 If a database client is not installed on the agent's machine, install one:
 
-| Platform | MySQL | PostgreSQL |
-|----------|-------|------------|
-| **Linux** | `apt install mysql-client` / `yum install mysql` | `apt install postgresql-client` |
-| **macOS** | `brew install mysql-client` | `brew install libpq` |
-| **Windows** | Download MySQL Workbench or `winget install Oracle.MySQL` | Download pgAdmin or `winget install PostgreSQL.PostgreSQL` |
+| Platform         | MySQL                                                        | PostgreSQL                                                     |
+| ---------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
+| **Linux**        | `apt install mysql-client` / `yum install mysql`             | `apt install postgresql-client`                                |
+| **macOS**        | `brew install mysql-client`                                  | `brew install libpq`                                           |
+| **Windows**      | Download MySQL Workbench or `winget install Oracle.MySQL`    | Download pgAdmin or `winget install PostgreSQL.PostgreSQL`     |
 | **Python (any)** | `pip install pymysql` then `python -c "import pymysql; ..."` | `pip install psycopg2` then `python -c "import psycopg2; ..."` |
-| **Docker (any)** | `docker run -it --rm mysql:8 mysql -h <ip> -u root -p` | `docker run -it --rm postgres:16 psql -h <ip> -U root` |
+| **Docker (any)** | `docker run -it --rm mysql:8 mysql -h <ip> -u root -p`       | `docker run -it --rm postgres:16 psql -h <ip> -U root`         |
 
 > If no client can be installed, use the Huawei Cloud **Data Studio** console: https://console.huaweicloud.com/dms/
 
 ## Mutating Operations (Require Approval)
 
-| Operation | Effect |
-|-----------|--------|
-| `CreateInstance` | New instance (billing starts) |
-| `DeleteInstance` | Irreversible data loss |
-| `StartResizeFlavorAction` | Brief interruption during switchover |
-| `StartInstanceEnlargeVolumeAction` | Online, but irreversible |
-| `StartFailover` | Primary-standby switchover |
-| `CreateRestoreInstance` | Creates new instance from backup |
-| `CreateManualBackup` | Incurs OBS storage charges |
-| `DeleteManualBackup` | Irreversible |
+| Operation                          | Effect                               |
+| ---------------------------------- | ------------------------------------ |
+| `CreateInstance`                   | New instance (billing starts)        |
+| `DeleteInstance`                   | Irreversible data loss               |
+| `StartResizeFlavorAction`          | Brief interruption during switchover |
+| `StartInstanceEnlargeVolumeAction` | Online, but irreversible             |
+| `StartFailover`                    | Primary-standby switchover           |
+| `CreateRestoreInstance`            | Creates new instance from backup     |
+| `CreateManualBackup`               | Incurs OBS storage charges           |
+| `DeleteManualBackup`               | Irreversible                         |
 
 ## Troubleshooting
 
-| Error | Root Cause -> Fix |
-|-------|-------------------|
-| Connection refused | SG missing DB port. Add ingress rule |
-| Storage full | Manual resize or enable auto-scaling |
-| DBS.280241 Invalid storage type | Volume type doesn't match flavor group |
-| DBS.280448 Sold out | Try different volume type or AZ |
-| Replication lag | Check `ShowReplicationStatus`. Consider read replica |
-| Instance stuck BUILDING | Check task status: `hcloud RDS ListTasks` |
-| SYS.0403 | SCP policy denies this operation (e.g. security group rules, EIP binding). See `huawei-vpc` troubleshooting |
-| EIP.7905 | EIP quota exceeded — cannot create new EIP for public access. See `huawei-vpc` troubleshooting |
+| Error                           | Root Cause -> Fix                                                                                           |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Connection refused              | SG missing DB port. Add ingress rule                                                                        |
+| Storage full                    | Manual resize or enable auto-scaling                                                                        |
+| DBS.280241 Invalid storage type | Volume type doesn't match flavor group                                                                      |
+| DBS.280448 Sold out             | Try different volume type or AZ                                                                             |
+| Replication lag                 | Check `ShowReplicationStatus`. Consider read replica                                                        |
+| Instance stuck BUILDING         | Check task status: `hcloud RDS ListTasks`                                                                   |
+| SYS.0403                        | SCP policy denies this operation (e.g. security group rules, EIP binding). See `huawei-vpc` troubleshooting |
+| EIP.7905                        | EIP quota exceeded — cannot create new EIP for public access. See `huawei-vpc` troubleshooting              |
 
 ## Security
 

package/plugins/huaweicloud-core/skills/huawei-sandbox/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: huawei-sandbox
-description: "Use when creating, connecting, or managing Huawei Cloud Sandbox instances and workspace terminals, or when a task needs a temporary runtime to deploy, run, or preview a web application. Covers sandbox lifecycle (check-user, sign-agreement, connect, release), session-based terminal execution, and credential injection. Triggers on: sandbox, workspace, terminal, web app deployment, deploy web app, preview app, deploy github, github repo, deploy repo, website, static site, web application, hwlink, devstation, hdkitservice, remote exec. NOT for: ECS instances (use huawei-ecs), CCE clusters (use huawei-cce)."
+description: 'Use when creating, connecting, or managing Huawei Cloud Sandbox instances and workspace terminals, or when a task needs a temporary runtime to deploy, run, or preview a web application. Covers sandbox lifecycle (check-user, sign-agreement, connect, release), session-based terminal execution, and credential injection. Triggers on: sandbox, workspace, terminal, web app deployment, deploy web app, preview app, deploy github, github repo, deploy repo, website, static site, web application, hwlink, devstation, hdkitservice, remote exec. NOT for: ECS instances (use huawei-ecs), CCE clusters (use huawei-cce).'
 version: 1
 ---
 
@@ -26,36 +26,114 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 
 ### User Verification (Prerequisites)
 
-| Tool | Purpose |
-|------|---------|
-| `huaweicloud_sandbox_check_user` | Check real-name verification and agreement signing status |
+| Tool                                 | Purpose                                                     |
+| ------------------------------------ | ----------------------------------------------------------- |
+| `huaweicloud_sandbox_check_user`     | Check real-name verification and agreement signing status   |
 | `huaweicloud_sandbox_sign_agreement` | Sign unsigned/outdated agreements (required before connect) |
 
 ### Sandbox Lifecycle
 
-| Tool | Purpose |
-|------|---------|
-| `huaweicloud_sandbox_connect` | Connect to sandbox (one user one instance, reuses existing if available) |
-| `huaweicloud_sandbox_credentials` | Inject temporary AK/SK into a running sandbox |
+| Tool                              | Purpose                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------ |
+| `huaweicloud_sandbox_connect`     | Connect to sandbox (one user one instance, reuses existing if available) |
+| `huaweicloud_sandbox_credentials` | Inject temporary AK/SK into a running sandbox                            |
 
 ### Terminal Execution
 
-| Tool | Purpose |
-|------|---------|
-| `huaweicloud_sandbox_exec_with_session` | Session-based execution (state persists) |
-| `huaweicloud_sandbox_close_session` | Close a persistent terminal session |
+| Tool                                    | Purpose                                                                     |
+| --------------------------------------- | --------------------------------------------------------------------------- |
+| `huaweicloud_sandbox_exec_with_session` | Session-based execution (state persists; best for interactive work)         |
+| `huaweicloud_sandbox_exec_one_shot`     | One-shot execution (fresh connection; best for long/heavy commands)         |
+| `huaweicloud_sandbox_upload_file`       | Upload a local file into the sandbox (chunked base64 write + md5 verify)    |
+| `huaweicloud_sandbox_upload_project`    | Upload a local project directory to sandbox (HTTP tunnel, tar.gz + extract) |
+| `huaweicloud_sandbox_close_session`     | Close a persistent terminal session                                         |
+
+### Tool Selection Guide
+
+| Scenario                           | Use                                | Why                                                          |
+| ---------------------------------- | ---------------------------------- | ------------------------------------------------------------ |
+| `cd`, env setup, command chains    | `exec_with_session`                | Needs shared shell state across calls                        |
+| `npm install`, `apt-get`, builds   | `exec_one_shot`                    | Long-running (>30s), no state needed, more stable            |
+| `curl`, health checks, quick tests | Either — `exec_one_shot` preferred | Stateless, fast                                              |
+| Server startup (background)        | `exec_with_session`                | Need to `nohup ... &` then check output in same session      |
+| Deployment scripts                 | `exec_one_shot+shot`               | Long script, fresh connection avoids session timeouts        |
+| Single file upload (<1MB)          | `upload_file`                      | Base64 chunked, reliable for small files                     |
+| Project directory upload (>1MB)    | `upload_project`                   | HTTP tunnel, much faster than base64 for multi-file projects |
+
+**Timeout tuning**: default is 120s. For commands expected to run longer (e.g. large builds), pass `timeout_ms` explicitly:
+
+```json
+{ "timeout_ms": 300000 }
+```
 
 ## Workflow
 
 Setup is a **plugin-side preflight** — the developer should be asked a question only once, when the agreement actually needs signing:
 
-1. **Check user** (transparent): `huaweicloud_sandbox_check_user` — verify `realnameVerified` and `agreementSigned`. Note: the tool may instead return an `HDKIT_NOT_AGREEMENT` error (e.g. `用户未签署最新版协议`) — treat that exactly the same as `agreementSigned=false`
-2. **Real-name verification** (only if `realnameVerified=false`): tell the developer once, "Huawei Cloud requires real-name verification before using the sandbox." and stop — do not retry `connect` in a loop
-3. **Sign agreement** (only if `agreementSigned=false`, or when step 1 returned an `HDKIT_NOT_AGREEMENT` error): **STOP and do NOT sign.** Tell the developer the sandbox requires signing the latest Huawei Cloud developer service agreement, then **wait for the developer to explicitly agree to sign** (e.g. the developer says "签署" / "sign it"). Only then call `huaweicloud_sandbox_sign_agreement`. **Never call `sign_agreement` on your own initiative** — the signing decision always belongs to the developer, and you must never sign a legal agreement on the developer's behalf without their explicit, unambiguous consent. Do not expose the underlying sandbox/DevBridge service as a separate entity the developer must understand or sign up for
-4. **Connect**: `huaweicloud_sandbox_connect` — returns `session_id`, `dev_stage_id`, `connection_id`, `connection_address`
-5. **Inject credentials** (optional): `huaweicloud_sandbox_credentials` — enables cloud API access from sandbox
-6. **Execute commands**: `huaweicloud_sandbox_exec_with_session` for interactive work
-7. **Expose the deployed app and return the public URL**: set up a public access link for the app port and give the URL to the developer as the final result (see "Expose the deployed app (public URL)") — this step uses an internal tunnel mechanism that must never be mentioned to the developer
+1. **Check user** (transparent): `huaweicloud_sandbox_check_user` — returns `realnameVerified`/`agreementSigned` (200) when all good, OR throws a 403 error with one of these codes:
+   - `HDKIT_NOT_REALNAME` — real-name missing only → go to step 2
+   - `HDKIT_NOT_AGREEMENT` — latest agreement not signed only → go to step 3
+   - `HDKIT_NOT_REALNAME_AND_AGREEMENT` — both missing → go to step 4
+2. **Real-name verification only** (`HDKIT_NOT_REALNAME`): tell the developer once, "Huawei Cloud requires real-name verification before using the sandbox — please complete it in the Huawei Cloud console (实名认证)." and stop — do not retry `connect` in a loop
+3. **Sign agreement only** (`HDKIT_NOT_AGREEMENT`): **STOP and do NOT sign on your own.** Ask the developer: "Huawei Cloud sandbox requires signing the latest developer service agreement. May I sign it for you?" Then **wait for the developer to explicitly agree** (e.g. "签署" / "确认" / "sign it"). Only after explicit consent call `huaweicloud_sandbox_sign_agreement` and return its result (`signed`/`signedCount`) to the developer. **Never sign a legal agreement on the developer's behalf without their explicit, unambiguous consent.** Do not expose the underlying sandbox/DevBridge service as a separate entity the developer must understand or sign up for
+4. **Both missing** (`HDKIT_NOT_REALNAME_AND_AGREEMENT`): present **both** requirements together in one message — the real-name verification steps (console, step 2) **and** the agreement-signing request (step 3, wait for explicit consent) — so the developer can complete both at once
+5. **Connect**: `huaweicloud_sandbox_connect` — returns `session_id`, `dev_stage_id`, `connection_id`, `connection_address`
+6. **Inject credentials** (optional): `huaweicloud_sandbox_credentials` — enables cloud API access from sandbox
+7. **Execute commands**: use `huaweicloud_sandbox_exec_with_session` for interactive work (cd, env setup), or `huaweicloud_sandbox_exec_one_shot` for long-running builds/installs. See [Tool Selection Guide](#tool-selection-guide).
+8. **Upload project** (if deploying local code): `huaweicloud_sandbox_upload_project` to transfer a local project directory into `/workspace/<name>` — uses HTTP tunnel, much faster than base64 for multi-file projects. Use `huaweicloud_sandbox_upload_file` for single files.
+9. **Expose the deployed app and return the public URL**: set up a public access link for the app port and give the URL to the developer as the final result (see "Expose the deployed app (public URL)") — this step uses an internal tunnel mechanism that must never be mentioned to the developer
+
+## File Transfer (local → sandbox)
+
+### upload_project (preferred for directories)
+
+`huaweicloud_sandbox_upload_project` packages a local directory as tar.gz, uploads it to the sandbox via HTTP tunnel, and extracts it. This is the fastest way to transfer multi-file projects.
+
+**Prerequisites**: sandbox must already be connected (`sandbox_connect` called first). The tool handles everything internally — no manual setup needed.
+
+```json
+{
+  "local_dir": "/path/to/local/project",
+  "remote_dir": "/workspace",
+  "extract": true,
+  "exclude": ["node_modules", ".git", "__pycache__"]
+}
+```
+
+- `local_dir` (required): local project directory
+- `remote_dir` (optional, default `/workspace`): parent directory on sandbox
+- `extract` (optional, default `true`): extract tar.gz after upload
+- `exclude` (optional): patterns to exclude from archive
+- Result includes `md5` and `md5Verified` for integrity check
+
+### upload_file (for single files)
+
+`huaweicloud_sandbox_upload_file` (local_path → remote_path) uploads a local file by base64-encoding it and writing it in small chunks through the terminal session, then decoding and verifying the md5 checksum. Use it for individual files, especially small ones (<1MB).
+
+### Exec channel size limit
+
+`huaweicloud_sandbox_exec_with_session` and `huaweicloud_sandbox_exec_one_shot` are fragile for long commands and large inline content. Do NOT paste a file's base64 directly into a single command:
+
+| Payload                     | Result                                 |
+| --------------------------- | -------------------------------------- |
+| ~30KB base64 in one command | exec timeout                           |
+| ~12KB base64 in one command | session crash (`session is not ready`) |
+| ~4–5KB normal command       | OK                                     |
+
+Keep individual exec commands small (≤ ~4KB). For larger content, use `huaweicloud_sandbox_upload_file` instead.
+
+### OBS transfer fallback
+
+When the upload tool is unavailable, transfer through OBS: upload to a public-read object locally, then pull it into the sandbox.
+
+```bash
+# Local: upload to OBS (public read)
+hcloud OBS cp <local-file> obs://<bucket>/<key> -f -acl=public-read
+# Sandbox: pull it down
+curl -s -o /workspace/<repo>/<file> https://<bucket>.obs.<region>.myhuaweicloud.com/<key>
+```
+
+> Requires OBS credentials (`huaweicloud_setup_obs_config`). Bucket ACL does not cascade to objects — set object-level `-acl=public-read` for anonymous reads.
 
 ## Expose the deployed app (public URL)
 
@@ -66,7 +144,11 @@ Expose a deployed web app to a public URL and return that URL to the developer.
 **Install** (internal tooling; skip if `devbridge version` already works):
 
 ```bash
-curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh | bash
+if command -v devbridge >/dev/null 2>&1; then
+  echo "devbridge already installed"
+else
+  curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh | bash
+fi
 export PATH=$PATH:$HOME/.huawei/bin   # installer only writes ~/.bashrc; session shells do not re-source it
 ```
 
@@ -95,20 +177,23 @@ sleep 10 && cat /tmp/host.log
 
 ## Critical Warnings
 
-| Trap | Why |
-|------|-----|
-| Agreement required first | `sandbox_connect` fails if the agreement isn't signed; the `sandbox_check_user` preflight detects this, so surface it to the developer only when signing is needed |
-| Real-name required | `sandbox_connect` fails if `realnameVerified=false`; tell the developer once and stop, don't loop on connect |
-| Never expose tunnel details | Do not mention "DevBridge"/"tunnel"/"devbridge" to the developer — say "正在生成访问地址..." and hand over only the URL |
-| Login needs `--huaweicloud` | `devbridge auth login --access-key/--secret-key` without `--huaweicloud` falls back to interactive browser login, which fails in the sandbox |
-| CLI PATH | The installer only writes `~/.bashrc`; run `export PATH=$PATH:$HOME/.huawei/bin` in the session before using `devbridge` |
-| Never install tunnel tooling locally | If the sandbox cannot install it, report a generic error and stop — installing on the developer's machine defeats sandbox deployment |
-| Return the deployment URL | Always hand the public URL from the host log to the developer as the final result |
-| Session state persists | `exec_with_session` preserves `cd`, env vars, aliases between calls |
-| Destructive commands blocked | `rm -rf /`, `mkfs`, `dd if=`, fork bombs are denied by safety policy |
-| Workspace ID = dev_stage_id | Use `dev_stage_id` from `sandbox_connect` as `workspace_id` for terminal exec |
-| Projects live in `/workspace` | Clone/install project code under `/workspace/<repo-name>` (filesystem-root workspace mount, not `$HOME/workspace`), never in `/tmp` — ephemeral locations lose the project when the sandbox session restarts |
-| Node.js >= 22 required | Sandbox terminal uses built-in WebSocket (globalThis.WebSocket); if Node.js is missing, install it from the Huawei Cloud mirror (see "Node.js in the sandbox") |
+| Trap                                 | Why                                                                                                                                                                                                          |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Agreement required first             | `sandbox_connect` fails if the agreement isn't signed; the `sandbox_check_user` preflight detects this, so surface it to the developer only when signing is needed                                           |
+| Real-name required                   | `sandbox_connect` fails if `realnameVerified=false`; tell the developer once and stop, don't loop on connect                                                                                                 |
+| Never expose tunnel details          | Do not mention "DevBridge"/"tunnel"/"devbridge" to the developer — say "正在生成访问地址..." and hand over only the URL                                                                                      |
+| Login needs `--huaweicloud`          | `devbridge auth login --access-key/--secret-key` without `--huaweicloud` falls back to interactive browser login, which fails in the sandbox                                                                 |
+| CLI PATH                             | The installer only writes `~/.bashrc`; run `export PATH=$PATH:$HOME/.huawei/bin` in the session before using `devbridge`                                                                                     |
+| Never install tunnel tooling locally | If the sandbox cannot install it, report a generic error and stop — installing on the developer's machine defeats sandbox deployment                                                                         |
+| Return the deployment URL            | Always hand the public URL from the host log to the developer as the final result                                                                                                                            |
+| Session state persists               | `exec_with_session` preserves `cd`, env vars, aliases between calls                                                                                                                                          |
+| Long commands prefer one-shot        | `exec_one_shot` creates a fresh connection per call — more stable for builds, installs, and scripts >30s. See [Tool Selection Guide](#tool-selection-guide).                                                 |
+| Destructive commands blocked         | `rm -rf /`, `mkfs`, `dd if=`, fork bombs are denied by safety policy                                                                                                                                         |
+| Workspace ID = dev_stage_id          | Use `dev_stage_id` from `sandbox_connect` as `workspace_id` for terminal exec                                                                                                                                |
+| Projects live in `/workspace`        | Clone/install project code under `/workspace/<repo-name>` (filesystem-root workspace mount, not `$HOME/workspace`), never in `/tmp` — ephemeral locations lose the project when the sandbox session restarts |
+| Upload project for local code        | Use `sandbox_upload_project` to transfer local projects — packages as tar.gz, uploads via HTTP tunnel, extracts on sandbox. Much faster than base64 for multi-file projects                                  |
+| Upload file for single files         | Use `sandbox_upload_file` for individual files — base64 chunked, reliable for small files (<1MB)                                                                                                             |
+| Node.js >= 22 required               | Sandbox terminal uses built-in WebSocket (globalThis.WebSocket); if Node.js is missing, install it from the Huawei Cloud mirror (see "Node.js in the sandbox")                                               |
 
 ## Node.js in the sandbox
 
@@ -125,11 +210,11 @@ node --version
 
 ## Environment Variables
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `HW_ACCESS_KEY` | Yes | Huawei Cloud AK |
-| `HW_SECRET_KEY` | Yes | Huawei Cloud SK |
-| `HW_SECURITY_TOKEN` | No | STS security token |
-| `HW_WORKSPACE_ID` | No | Default workspace ID |
-| `HDKITSERVICE_ENDPOINT` | No | hdkitservice API endpoint |
-| `HWLINK_ENDPOINT` | No | DevStation API endpoint |
+| Variable                | Required | Description                                                     |
+| ----------------------- | -------- | --------------------------------------------------------------- |
+| `HW_ACCESS_KEY`         | Yes      | Huawei Cloud AK                                                 |
+| `HW_SECRET_KEY`         | Yes      | Huawei Cloud SK                                                 |
+| `HW_SECURITY_TOKEN`     | No       | STS security token                                              |
+| `HW_WORKSPACE_ID`       | No       | Default workspace ID                                            |
+| `HDKITSERVICE_ENDPOINT` | No       | hdkitservice API endpoint (default: devkit.huaweicloud.com)     |
+| `HWLINK_ENDPOINT`       | No       | DevStation API endpoint (default: devstation.myhuaweicloud.com) |

package/plugins/huaweicloud-core/skills/huawei-smn-dms/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: huawei-smn-dms
-description: "Use when creating or managing SMN topics/subscriptions/messages or DMS Kafka/RabbitMQ/RocketMQ queues on Huawei Cloud. Triggers: SMN, DMS, notification, message queue, Kafka, RabbitMQ, RocketMQ, topic, subscription. NOT for: APIG (use huawei-apig), FunctionGraph triggers (use huawei-functiongraph)."
+description: 'Use when creating or managing SMN topics/subscriptions/messages or DMS Kafka/RabbitMQ/RocketMQ queues on Huawei Cloud. Triggers: SMN, DMS, notification, message queue, Kafka, RabbitMQ, RocketMQ, topic, subscription. NOT for: APIG (use huawei-apig), FunctionGraph triggers (use huawei-functiongraph).'
 version: 1
 ---
 
@@ -18,50 +18,50 @@ Domain expertise for SMN (Simple Message Notification) and DMS (Distributed Mess
 
 ## Critical Warnings
 
-| Trap | Why |
-|------|-----|
+| Trap                      | Why                                                           |
+| ------------------------- | ------------------------------------------------------------- |
 | Subscription confirmation | HTTP/HTTPS subscriptions need endpoint ping-back confirmation |
-| Email subscription delay | Email subscriptions require user to click confirmation link |
-| SMS charge per message | Template SMS incurs per-delivery charges |
+| Email subscription delay  | Email subscriptions require user to click confirmation link   |
+| SMS charge per message    | Template SMS incurs per-delivery charges                      |
 
 ### Common Workflows
 
-| Task | Operation |
-|------|-----------|
-| List topics | `ListTopics --cli-region=<r> --project_id=<p>` |
-| Create topic | `CreateTopic --cli-region=<r> --project_id=<p>` |
-| Add subscription | `AddSubscription --cli-region=<r> --project_id=<p>` |
-| List subscriptions | `ListSubscriptions --cli-region=<r> --project_id=<p>` |
+| Task                    | Operation                                                 |
+| ----------------------- | --------------------------------------------------------- |
+| List topics             | `ListTopics --cli-region=<r> --project_id=<p>`            |
+| Create topic            | `CreateTopic --cli-region=<r> --project_id=<p>`           |
+| Add subscription        | `AddSubscription --cli-region=<r> --project_id=<p>`       |
+| List subscriptions      | `ListSubscriptions --cli-region=<r> --project_id=<p>`     |
 | Create message template | `CreateMessageTemplate --cli-region=<r> --project_id=<p>` |
-| Publish message | `PublishMessage --cli-region=<r> --project_id=<p>` |
-| Delete topic | `DeleteTopic --cli-region=<r> --project_id=<p>` |
+| Publish message         | `PublishMessage --cli-region=<r> --project_id=<p>`        |
+| Delete topic            | `DeleteTopic --cli-region=<r> --project_id=<p>`           |
 
 ## DMS
 
 ### Service Types
 
-| Type | KooCLI Service |
-|------|---------------|
-| Kafka | `hcloud DMS` |
-| RabbitMQ | `hcloud DMS` |
-| RocketMQ | `hcloud DMS` |
+| Type     | KooCLI Service |
+| -------- | -------------- |
+| Kafka    | `hcloud DMS`   |
+| RabbitMQ | `hcloud DMS`   |
+| RocketMQ | `hcloud DMS`   |
 
 ### Common Workflows
 
-| Task | Operation |
-|------|-----------|
-| List instances | `ListInstances --cli-region=<r> --project_id=<p>` |
+| Task                  | Operation                                          |
+| --------------------- | -------------------------------------------------- |
+| List instances        | `ListInstances --cli-region=<r> --project_id=<p>`  |
 | Create Kafka instance | `CreateInstance --cli-region=<r> --project_id=<p>` |
-| List Kafka topics | `ListTopics --cli-region=<r> --project_id=<p>` |
+| List Kafka topics     | `ListTopics --cli-region=<r> --project_id=<p>`     |
 
 Discover exact parameters with `--help` before executing any command.
 
 ## Troubleshooting
 
-| Error | Fix |
-|-------|-----|
-| Subscription not confirmed | SMN subscriptions need endpoint/user confirmation |
-| DMS instance creation fails | Check VPC/subnet availability and engine version |
+| Error                       | Fix                                               |
+| --------------------------- | ------------------------------------------------- |
+| Subscription not confirmed  | SMN subscriptions need endpoint/user confirmation |
+| DMS instance creation fails | Check VPC/subnet availability and engine version  |
 
 ## Cross-Skill References