huaweicloud-devkit 1.1.10 → 1.1.11

package/README.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![CI](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml/badge.svg)](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/huaweicloud-devkit)](https://www.npmjs.com/package/huaweicloud-devkit)
-[![Beta](https://img.shields.io/badge/beta-v1.1.10-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
+[![Beta](https://img.shields.io/badge/beta-v1.1.11-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
 
 **[中文](README.zh-CN.md) | English**
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![CI](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml/badge.svg)](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/huaweicloud-devkit)](https://www.npmjs.com/package/huaweicloud-devkit)
-[![Beta](https://img.shields.io/badge/beta-v1.1.10-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
+[![Beta](https://img.shields.io/badge/beta-v1.1.11-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
 
 **中文 | [English](README.md)**
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "kooCliVersion": "7.3.12",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",

package/plugins/huaweicloud-core/.claude-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.codex-plugin/plugin.json

@@ -20,7 +20,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "skills": "./skills/",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.cursor-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.hermes-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/.workbuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "name": "huaweicloud-devkit",
   "id": "huaweicloud-devkit",
   "displayName": "HuaweiCloud DevKit",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "family": "bundle-plugin",
   "bundleFormat": "codex",
   "description": "Guide coding agents to use Huawei Cloud safely — KooCLI, APIs, SDKs, 28 MCP tools, skills, and safety guardrails.",

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

@@ -1,6 +1,6 @@
 ---
 name: huawei-obs
-description: 'Use when creating, configuring, or managing OBS buckets and objects on Huawei Cloud. Covers bucket creation, lifecycle policies, versioning, static website hosting, CORS, access control (IAM/bucket policy/ACL), cross-region replication, event notifications, and presigned URLs. Triggers on: OBS, bucket, object storage, lifecycle, versioning, static website, CORS, presigned, replication. NOT for: EVS block storage (use huawei-ecs), SFS file storage, CBR backup (use huawei-cbr).'
+description: 'Use when creating, configuring, or managing OBS buckets and objects on Huawei Cloud. Covers bucket creation, lifecycle policies, versioning, static website hosting, CORS, access control (IAM/bucket policy/ACL), cross-region replication, event notifications, and presigned URLs. Triggers on: OBS, bucket, object storage, lifecycle, versioning, static website, CORS, presigned, replication, 浏览器直传, browser direct upload, 预签名上传, 直传 OBS. NOT for: EVS block storage (use huawei-ecs), SFS file storage, CBR backup (use huawei-cbr).'
 version: 1
 ---
 
@@ -62,21 +62,21 @@ hcloud OBS config -e=<endpoint> -i=<AK> -k=<SK> -t=token
 
 ## Common Workflows
 
-| Task                         | Command                                                                   |
-| ---------------------------- | ------------------------------------------------------------------------- |
-| Create bucket                | `hcloud OBS mb obs://<bucket> -location=<region>`                         |
-| List buckets/objects         | `hcloud OBS ls [obs://<bucket>]`                                          |
-| Upload file                  | `hcloud OBS cp <file> obs://<bucket>/<key>`                               |
-| Upload directory (recursive) | `hcloud OBS cp <dir>/ obs://<bucket>/ -r -f -flat`                        |
-| Download object              | `hcloud OBS cp obs://<bucket>/<key> <local-path>`                         |
-| Set bucket ACL               | `hcloud OBS chattri obs://<bucket> -acl=public-read`                      |
-| Set object ACL               | `hcloud OBS chattri obs://<bucket>/<key> -acl=public-read`                | Bucket ACL does NOT cascade — anonymous reads need both |
-| Set lifecycle                | `hcloud OBS lifecycle obs://<bucket> -method=put -localfile=<json>`       |
-| Set bucket policy            | `hcloud OBS bucketpolicy obs://<bucket> -method=put -localfile=<json>`    |
-| Set CORS                     | Not available via `hcloud OBS` — use API/SDK (`SetBucketCors`) or console |
-| Delete bucket                | `hcloud OBS rm obs://<bucket> -r` (must be empty)                         |
-| Presigned URL                | `hcloud OBS sign obs://<bucket>/<key> -e=<seconds>`                       |
-| Object metadata              | `hcloud OBS stat obs://<bucket>/<key>`                                    |
+| Task                         | Command                                                                                                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Create bucket                | `hcloud OBS mb obs://<bucket> -location=<region>`                                                                                                                   |
+| List buckets/objects         | `hcloud OBS ls [obs://<bucket>]`                                                                                                                                    |
+| Upload file                  | `hcloud OBS cp <file> obs://<bucket>/<key>`                                                                                                                         |
+| Upload directory (recursive) | `hcloud OBS cp <dir>/ obs://<bucket>/ -r -f -flat`                                                                                                                  |
+| Download object              | `hcloud OBS cp obs://<bucket>/<key> <local-path>`                                                                                                                   |
+| Set bucket ACL               | `hcloud OBS chattri obs://<bucket> -acl=public-read`                                                                                                                |
+| Set object ACL               | `hcloud OBS chattri obs://<bucket>/<key> -acl=public-read`                                                                                                          | Bucket ACL does NOT cascade — anonymous reads need both |
+| Set lifecycle                | `hcloud OBS lifecycle obs://<bucket> -method=put -localfile=<json>`                                                                                                 |
+| Set bucket policy            | `hcloud OBS bucketpolicy obs://<bucket> -method=put -localfile=<json>`                                                                                              |
+| Set CORS                     | `huaweicloud_obs_set_cors` (set/get/delete) — KooCLI OBS has no cors subcommand; the tool does AWS4-signed `PUT /?cors` internally. allowedMethod MUST include HEAD |
+| Delete bucket                | `hcloud OBS rm obs://<bucket> -r` (must be empty)                                                                                                                   |
+| Presigned URL                | `hcloud OBS sign obs://<bucket>/<key> -e=<seconds>`                                                                                                                 |
+| Object metadata              | `hcloud OBS stat obs://<bucket>/<key>`                                                                                                                              |
 
 ## Static Website Deployment Workflow
 
@@ -131,3 +131,4 @@ See `references/single-file-share.md` for the full workflow to host one file and
 - Static website: references/static-website.md
 - Single-file share: references/single-file-share.md
 - Lifecycle: references/bucket-lifecycle.md
+- Browser direct upload & CORS: references/common-pitfalls.md

package/plugins/huaweicloud-core/skills/huawei-obs/references/common-pitfalls.md

@@ -69,7 +69,7 @@ KooCLI OBS **不支持** `SetBucketWebsite` 命令。配置静态网站托管需
 
 **避坑方法**：
 
-1. **验证网页行为必须用 GET 直连**（`curl -s -D - -o NUL <url>` 或浏览器）——HEAD 和代理层会给出假象
+1. **验证网页行为必须用 GET 直连**（`curl -s -D - -o /dev/null <url>`，Windows 下为 `-o NUL`；或浏览器）——HEAD 和代理层会给出假象
 2. **官方解法**：绑定自定义域名接入 **CDN**，在"CDN 控制台 > 域名管理 > 高级设置 > HTTP header 配置"设置 `Content-Disposition: inline`（参见华为云 CDN 文档《如何在浏览器中在线预览 OBS 中的对象？》）
 3. 跨云对照：阿里云 OSS 同样策略（Bucket 域名访问 HTML 强制下载，绑定自定义域名即可在线预览）
 
@@ -126,3 +126,170 @@ hcloud OBS chattri obs://<bucket>/index.html -acl=public-read
 - SHOULD 开启访问日志
 - 预签名 URL 最大 7 天有效期
 - AK/SK 绝对不能写入 Bucket Policy
+
+## 浏览器直传（BrowserJS SDK）
+
+使用 OBS BrowserJS SDK（`esdk-obs-browserjs` 3.25.6）从浏览器直传 OBS 时的已知陷阱。**共享 AK/SK 的完整客户端代码严禁出现在浏览器端**——浏览器直传只允许「服务端生成预签名 URL / 临时凭证 + 浏览器携带凭证直传」模式。
+
+### p01 · CORS AllowedMethod 缺 HEAD → 探测请求被吞
+
+**现象**：浏览器端 `listObjects` 一律失败，DevTools 只显示 `Network Error`，无任何 OBS 错误体——因为没有 CORS 头，浏览器直接吞掉了响应。
+
+**根因**：BrowserJS SDK 3.25.6 默认开启签名协商（`isSignatureNegotiation=!0`），在发起 listObjects 前会先向桶发一个 `HEAD ?apiversion` 探测请求。若 CORS 规则的 AllowedMethod 不含 `HEAD`，这个预检/探测请求返回 403 `AccessForbidden` 且**响应不带 CORS 头**，浏览器按同源策略丢弃整个响应，最终只呈现 `Network Error`——真实错误（AccessForbidden）被完全掩盖。
+
+**修复**：CORS 规则的 AllowedMethod 必须包含 `HEAD`（连同 GET/PUT/POST/DELETE，完整五方法见下文「CORS 配置」章节的 JSON/XML 模板）。
+
+### p02 · `signature:'v4'` 被静默忽略
+
+**现象**：构造客户端时传 `signature:'v4'`，但生成的请求/预签名仍是 V2 签名，且无任何警告。
+
+**根因**：3.25.6 的 `initFactory` 未消费 `signature` 配置项，静默降级为默认 V2。想要 V4 预签名，必须手动注入 `signatureContext`：
+
+```js
+const client = new ObsClient({
+  access_key_id: '<AK>', // 临时凭证场景用 STS 临时 AK
+  secret_access_key: '<SK>',
+  server: 'https://obs.<region>.myhuaweicloud.com',
+  // signature: 'v4' 在 3.25.6 被静默忽略，不起作用 —— 见 p02
+  signatureContext: {
+    signature: 'v4',
+    headerPrefix: 'X-Amz-',
+    headerMetaPrefix: 'X-Amz-Meta-',
+    authPrefix: 'AWS4-HMAC-SHA256',
+  },
+});
+```
+
+### p03 · 预签名 URL 的 token 参数大小写陷阱
+
+**现象**：用临时凭证（STS token）生成 V4 预签名 URL，浏览器访问返回 403 `AccessDenied`。
+
+**根因**：SDK 3.25.6 拼预签名 query 时把安全令牌参数拼成混合大小写 `X-Amz-security-token`，而 OBS 服务端对 query 参数名**大小写敏感**，只认小写 `x-amz-security-token`，大小写不匹配 → 403 `AccessDenied`。
+
+**修复**：不要依赖 SDK 自动拼接 token，改为在生成预签名 URL 时以**小写**参数名手动传入 QueryParams：
+
+```js
+const { signedUrl } = await client.createSignedUrl({
+  Method: 'PUT',
+  Bucket: '<bucket>',
+  Key: '<object-key>',
+  Expires: 3600,
+  Headers: { 'x-amz-acl': 'public-read' },
+  QueryParams: {
+    'x-amz-security-token': '<security-token>', // 必须小写！SDK 自动拼的是 X-Amz-security-token（见 p03）
+  },
+});
+// 浏览器侧直接 fetch(signedUrl, { method: 'PUT', body: file })
+```
+
+### p04 · V4 头部签名在浏览器端不可用
+
+**现象**：给浏览器端客户端配了 V4 signatureContext 后，listObjects / deleteObject 等头部鉴权请求全部 403。
+
+**根因**：V4 头部签名依赖的派生/规范化逻辑在浏览器环境不完整（BrowserJS SDK 仅对**预签名 URL** 路径支持 V4）。
+
+**修复**——双客户端分工：
+
+- **列表/删除等 HTTP 头鉴权操作**：用 V2 头部签名客户端，并显式关闭签名协商（否则又踩 p01 的 HEAD 探测问题）：
+
+```js
+const v2Client = new ObsClient({
+  access_key_id: '<AK>',
+  secret_access_key: '<SK>',
+  server: 'https://obs.<region>.myhuaweicloud.com',
+  is_signature_negotiation: false, // 关闭协商，跳过 HEAD ?apiversion 探测（见 p01/p04）
+});
+await v2Client.listObjects({ Bucket: '<bucket>' });
+```
+
+- **展示/上传**：走 p02+p03 修正后的 V4 预签名 URL（`createSignedUrl`），浏览器侧用 `fetch` 直接 PUT/GET。
+
+### p05 · OBS 错误响应缺 CORS 头 → 浏览器吞错
+
+**现象**：任何 OBS 侧错误（AccessDenied、InvalidAccessKeyId、CORS 拒绝等）在浏览器里都只剩 `Network Error`，无法定位真实原因。
+
+**根因**：预检失败时 OBS 的错误响应本身不带 CORS 头，浏览器同源策略直接丢弃响应体。这是浏览器行为，不是 OBS 不可用。
+
+**诊断**（二选一，均可拿到真实状态码与错误体）：
+
+```bash
+# 方法①：curl 实测 OPTIONS 预检 —— 看 OBS 真实返回的状态码与错误体
+curl -i -X OPTIONS 'https://<bucket>.obs.<region>.myhuaweicloud.com/<object-key>' \
+  -H 'Origin: https://<your-app-origin>' \
+  -H 'Access-Control-Request-Method: PUT' \
+  -H 'Access-Control-Request-Headers: content-type,x-amz-acl'
+
+# 方法②：Node 环境（无 CORS 约束）复现同一请求 —— 用 node fetch 重放浏览器的完整请求
+node -e "fetch('<same-url>', {method:'PUT', headers:{'Origin':'https://<your-app-origin>'}}).then(r=>r.text().then(t=>console.log(r.status,t)))"
+```
+
+预检返回 403 `AccessForbidden` → CORS 规则缺方法/头部；返回 200 但带 `Access-Control-Allow-Origin: *` → CORS 已通，错误在别处（签名/ACL/策略）。
+
+## CORS 配置（浏览器直传前置条件）
+
+浏览器直传 OBS 前，桶必须先配置 CORS 规则，否则所有请求都会被预检拦截。
+
+**KooCLI 缺口**：KooCLI 的 OBS 包装层未暴露 obsutil 的 `cors` 子命令——执行 `hcloud OBS cors` 报 `No such command`（`hcloud OBS help` 列表中也无 cors）。
+
+**首选路径：MCP 工具 `huaweicloud_obs_set_cors`（#1003）**——内部 AWS4 签名调 OBS REST API（`PUT/GET/DELETE /?cors`），屏蔽签名细节。`action=set` 传 `rules` 数组（`allowedOrigin` / `allowedMethod[]` 必须含 HEAD / `allowedHeader[]` / `maxAgeSeconds`），工具在入参边界就拒绝缺 HEAD 的规则（p01 前置防线）；set/get 成功返回体自带 `verify` 命令（OPTIONS 预检）。SDK/控制台仅作降级路径。
+
+**降级路径 ①：REST API `PUT /?cors` + CORS XML**
+
+向桶 endpoint 发 `PUT /?cors`，body 为 CORSConfiguration XML；请求需带 AWS4 签名（Authorization 头，可用 SDK/工具生成，或使用插件内 `huaweicloud_obs_set_website_config` 同款的 AWS4 签名方式）。`PUT /?cors` 使用的 AllowedMethod 必须覆盖浏览器直传全部五个方法：
+
+```xml
+<CORSConfiguration>
+  <CORSRule>
+    <AllowedOrigin>https://<your-app-origin></AllowedOrigin>
+    <AllowedMethod>GET</AllowedMethod>
+    <AllowedMethod>PUT</AllowedMethod>
+    <AllowedMethod>POST</AllowedMethod>
+    <AllowedMethod>DELETE</AllowedMethod>
+    <AllowedMethod>HEAD</AllowedMethod> <!-- 缺 HEAD 会触发 p01：SDK 的 HEAD ?apiversion 探测被拒 -->
+    <AllowedHeader>*</AllowedHeader>
+    <MaxAgeSeconds>3000</MaxAgeSeconds>
+  </CORSRule>
+</CORSConfiguration>
+```
+
+**降级路径 ②：esdk-obs-python `setBucketCors`**
+
+服务端 Python 环境最小示例（凭证从环境变量读取，勿硬编码）：
+
+```python
+import os
+from obs import ObsClient
+
+client = ObsClient(
+    access_key_id=os.environ['HUAWEICLOUD_SDK_AK'],
+    secret_access_key=os.environ['HUAWEICLOUD_SDK_SK'],
+    server='https://obs.<region>.myhuaweicloud.com',
+)
+
+client.setBucketCors(
+    '<bucket>',
+    [
+        {
+            'allowedOrigin': 'https://<your-app-origin>',
+            'allowedMethod': ['GET', 'PUT', 'POST', 'DELETE', 'HEAD'],  # HEAD 必含，见 p01
+            'allowedHeader': ['*'],
+            'maxAgeSeconds': 3000,
+        }
+    ],
+)
+```
+
+JSON 形态（供 MCP 工具/自研封装消费）：
+
+```json
+[
+  {
+    "allowedOrigin": "https://<your-app-origin>",
+    "allowedMethod": ["GET", "PUT", "POST", "DELETE", "HEAD"],
+    "allowedHeader": ["*"],
+    "maxAgeSeconds": 3000
+  }
+]
+```
+
+配置完成后用 p05 的 curl OPTIONS 预检命令验证：预检应返回 200 且响应头含 `Access-Control-Allow-Origin`。走 `huaweicloud_obs_set_cors` 工具时，set/get 返回体的 `verify` 字段就是这条预检命令（含 `--noproxy '*'`，#1000 的注入代理陷阱同样适用于 OPTIONS 预检）。

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

@@ -63,6 +63,14 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 | `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                            |
 
+### Tunnel Persistence (public URL lifetime)
+
+| Tool                                     | Purpose                                                                                                                                                                                                    |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `huaweicloud_sandbox_expose_tunnel`      | Expose a port → public tunnel URL (auth, pre-clean, health check; `expiry_hours` 1-720, def 72). **AUTO-enrolls into the keepalive watchdog** (merged into existing coverage; `keepalive: false` opts out) |
+| `huaweicloud_sandbox_renew_tunnel`       | Renew a tunnel lifetime (`update -e`, rolling window; returns absolute expiresAt)                                                                                                                          |
+| `huaweicloud_sandbox_keepalive_watchdog` | Install/replace the 3-layer watchdog: host re-attach + daily 720h renewal + 5-min health check                                                                                                             |
+
 ### Terminal Execution
 
 | Tool                                    | Purpose                                                                     |
@@ -86,6 +94,8 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 | Deployment scripts                 | `exec_one_shot+shot`               | Long script, fresh connection avoids session timeouts        |
 | nginx configuration                | `deploy_nginx`                     | Auto-generates correct template + permissions + reload       |
 | Deployment completeness check      | `deploy_check`                     | Verifies nginx, DevBridge, URL, QR before reporting success  |
+| Tunnel lifetime renewal            | `renew_tunnel`                     | Rolling-window renewal, same URL stays alive                 |
+| URL must outlive the session       | `keepalive_watchdog`               | Unattended host re-attach + daily renewal + health check     |
 | 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 |
 
@@ -235,7 +245,7 @@ Expose a deployed web app to a public URL and return that URL to the developer.
 **Check the version first.** Sandboxes created before Sep 2026 ship devbridge 0.1.13, whose hardcoded gateway (`cn-north-4-bridge.myhuaweicloud.com`) was migrated and now serves a 「服务已迁移」 placeholder page — 0.1.x can no longer connect:
 
 ```bash
-export PATH="$HOME/.huawei/bin:$PATH"   # PREPEND — appending lets a stale image binary in /usr/local/bin win
+export PATH="/workspace/.local/bin:$HOME/.huawei/bin:$PATH"   # PREPEND — appending lets a stale image binary in /usr/local/bin win
 devbridge version 2>/dev/null || echo "not installed"
 ```
 
@@ -256,39 +266,61 @@ DB_TARGET=$(grep -m1 'DEFAULT_VERSION=' /tmp/devbridge-install.sh | cut -d'"' -f
 if ! bash /tmp/devbridge-install.sh -s -u "https://gitcode.com/CloudDeveloperDepartment/devbrige/releases/download/${DB_TARGET}" -v "${DB_TARGET}"; then
   bash /tmp/devbridge-install.sh -s   # fallback: GitHub (baked-in URL)
 fi
-export PATH="$HOME/.huawei/bin:$PATH"   # PREPEND (session shells do not re-source ~/.bashrc)
+export PATH="/workspace/.local/bin:$HOME/.huawei/bin:$PATH"   # PREPEND (session shells do not re-source ~/.bashrc)
 
 # Layer 3 (both installer paths failed): direct GitHub release tar.gz.
 # Asset naming is fixed: devbridge_linux_arm64_<version>-release.tar.gz (the sandbox
 # is Linux aarch64). If DB_TARGET is empty the installer download itself failed —
 # resolve the latest tag from the GitHub releases API first.
+# Install to /workspace/.local/bin — /workspace is the sandbox's DATA disk and
+# survives reboots; ~/.huawei/bin lives on the SYSTEM disk and a reboot wipes it
+# back to the image state (measured 2026-10-22: an overnight reboot reverted
+# ~/.huawei/bin/devbridge 0.2.2 to the image's 0.1.13 — yesterday's success
+# replayed as today's unexplained failure). (#999)
 if ! command -v devbridge >/dev/null 2>&1; then
   [ -z "$DB_TARGET" ] && DB_TARGET=$(curl -fsSL --http1.1 --retry 2 --max-time 60 \
     https://api.github.com/repos/huaweicloud/devspace-devbridge/releases/latest | grep -m1 '"tag_name"' | cut -d'"' -f4)
-  mkdir -p "$HOME/.huawei/bin"
+  mkdir -p /workspace/.local/bin
   curl -fsSL --http1.1 --retry 3 --retry-all-errors --max-time 180 \
     "https://github.com/huaweicloud/devspace-devbridge/releases/download/${DB_TARGET}/devbridge_linux_arm64_${DB_TARGET}.tar.gz" \
     -o /tmp/devbridge.tar.gz \
     && rm -rf /tmp/devbridge-pkg && mkdir -p /tmp/devbridge-pkg \
     && tar -xzf /tmp/devbridge.tar.gz -C /tmp/devbridge-pkg \
-    && install -m 0755 /tmp/devbridge-pkg/devbridge "$HOME/.huawei/bin/devbridge"
-  export PATH="$HOME/.huawei/bin:$PATH"
+    && install -m 0755 /tmp/devbridge-pkg/devbridge /workspace/.local/bin/devbridge
+  export PATH="/workspace/.local/bin:$HOME/.huawei/bin:$PATH"
 fi
 devbridge version                     # must print 0.2.x-release
 
 # Remove the stale image-installed binary so only ONE version remains.
-# (Image sandboxes ship 0.1.x at /usr/local/bin/devbridge; the installer writes ~/.huawei/bin.
-#  Compare against the explicit ~/.huawei/bin path — never `command -v`, which can resolve
-#  to the stale binary itself when PATH order differs.)
-if [ -x "$HOME/.huawei/bin/devbridge" ] && [ -f /usr/local/bin/devbridge ] && [ "$(readlink -f /usr/local/bin/devbridge)" != "$(readlink -f "$HOME/.huawei/bin/devbridge")" ]; then
+# (Image sandboxes ship 0.1.x at /usr/local/bin/devbridge; the installer writes
+# /workspace/.local/bin. Compare against the explicit install path — never
+# `command -v`, which can resolve to the stale binary itself when PATH order differs.)
+if [ -f /usr/local/bin/devbridge ] && [ -x /workspace/.local/bin/devbridge ] && [ "$(readlink -f /usr/local/bin/devbridge)" != "$(readlink -f /workspace/.local/bin/devbridge)" ]; then
   rm -f /usr/local/bin/devbridge && echo "stale /usr/local/bin/devbridge removed"
 fi
+# A leftover 0.2.x in ~/.huawei/bin (installed by older docs) is valid until the
+# next reboot — deduplicate it against the /workspace copy so the version check
+# above can never report the image's 0.1.x.
+if [ -x "$HOME/.huawei/bin/devbridge" ] && [ -x /workspace/.local/bin/devbridge ] && [ "$(readlink -f "$HOME/.huawei/bin/devbridge")" != "$(readlink -f /workspace/.local/bin/devbridge)" ]; then
+  rm -f "$HOME/.huawei/bin/devbridge" && echo "stale ~/.huawei/bin/devbridge removed"
+fi
 ```
 
 - `-s` (silent) is **required** in the sandbox — without it the installer blocks reading `/dev/tty`.
 - **Old tunnels do not survive the upgrade**: 0.1.x-created tunnels are not registered on the s2 gateway — always rebuild the tunnel after upgrading (the expose flow below does this via pre-cleanup).
 - If `10006: quota exceeded` appears after upgrading, stale pre-upgrade tunnels still count against the quota — `devbridge delete-all` and retry.
 
+### Sandbox filesystem persistence: what survives a reboot (#999)
+
+| Path                                         | Type           | After a sandbox reboot                                                               |
+| -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
+| `/workspace` (incl. `/workspace/.local/bin`) | Data disk      | **Survives** — install project code and the devbridge 0.2.x binary here              |
+| `$HOME` (incl. `~/.huawei/bin`)              | System disk    | **Rolled back to the image state** — an installed binary is lost, 0.1.13 returns     |
+| `/usr/local/bin`                             | System disk    | Rolled back — the image-preinstalled 0.1.x returns                                   |
+| `/tmp`                                       | Session-scoped | Cleared — `/tmp/hw_creds.sh`, `/tmp/hw_api_key`, `/tmp/tunnel-keepalive.sh` are gone |
+
+Measured (2026-10-22): an overnight reboot reverted `~/.huawei/bin/devbridge` 0.2.2 to the image's 0.1.13 — **yesterday's successful operation replayed as today's unexplained failure**. Recovery after a reboot: re-run the Step 0 install (or just re-export the PATH to the surviving `/workspace/.local/bin`), re-run `huaweicloud_sandbox_credentials` to re-inject `/tmp` credentials, and re-run `huaweicloud_sandbox_keepalive_watchdog` to restore the keepalive loop.
+
 ### Step 1: Authenticate — verified waterfall, keyring first
 
 Authentication tries three credential sources in order, each verified with a real login + `auth status` before use; a failure falls through to the next tier:
@@ -300,7 +332,7 @@ Authentication tries three credential sources in order, each verified with a rea
 `huaweicloud_sandbox_expose_tunnel` runs this waterfall automatically and reports the winning mode (`API_KEY_KEYRING` / `AKSK_SUPPORTED` / `API_KEY_FILE`) or `NO_CREDENTIAL` with a non-sensitive per-tier `attempts` diagnostic. Manual equivalent:
 
 ```bash
-export PATH="$HOME/.huawei/bin:$PATH"
+export PATH="/workspace/.local/bin:$HOME/.huawei/bin:$PATH"
 export HOME="${HOME:-/root}"
 # Tier 1: platform-injected keyring key (stderr! prefix filter!)
 export DBUS_SESSION_BUS_ADDRESS="${DBUS_SESSION_BUS_ADDRESS:-unix:path=/run/dbus-session}"
@@ -361,7 +393,10 @@ sleep 10 && cat /tmp/host.log
 
 # 2. Extract tunnel URL and health-check before returning
 TUNNEL_URL=$(grep -oP 'Tunnel URL: \K.*' /tmp/host.log)
-HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")
+# --noproxy is MANDATORY (#1000): the sandbox injects an HTTP proxy that does NOT
+# route the tunnel domain — without it a working tunnel verifies as 502/404 and
+# sends you chasing credentials/version/port.
+HTTP_CODE=$(curl -s --noproxy '*' -o /dev/null -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")
 if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "304" ]; then
   echo "Tunnel verified: $TUNNEL_URL (HTTP $HTTP_CODE)"
 else
@@ -372,13 +407,15 @@ else
   disown 2>/dev/null || true
   sleep 10
   TUNNEL_URL=$(grep -oP 'Tunnel URL: \K.*' /tmp/host.log)
-  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")
+  HTTP_CODE=$(curl -s --noproxy '*' -o /dev/null -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")
   echo "Retry tunnel: $TUNNEL_URL (HTTP $HTTP_CODE)"
 fi
 ```
 
 **Never return a tunnel URL without verifying it first** — a stale URL (from a killed tunnel process) will silently fail. Always curl-check before giving the URL to the developer. Note: a migrated gateway serves its placeholder page with **HTTP 200** — a bare status check is not enough when diagnosing "200 but wrong content".
 
+**Proxy trap on verify commands (#1000)**: every curl against `*.hwtunnel.com` MUST pass `--noproxy '*'` — the sandbox injects an HTTP/HTTPS proxy that does not route the tunnel domain, so a proxied verify returns 502/404 fakes while the tunnel is actually serving. If a tunnel "fails" verification, re-test with `--noproxy '*'` BEFORE checking versions/credentials/ports (same trap on the SSH path: huawei-ecs skill references/windows-ssh.md §0.1).
+
 **Quota recovery**: if the tunnel creation fails with `10006: quota exceeded`:
 
 ```bash
@@ -404,10 +441,35 @@ This eliminates the most common deployment failure — historical tunnels from p
 
 **No local downgrade**: if the tunnel tooling cannot be installed in the sandbox, STOP and report a generic error ("无法生成访问地址") without technical detail. Never install it on the developer's local machine — a local install would defeat the purpose of sandbox deployment.
 
+### Step 3: Keep the URL alive (persistence & renewal)
+
+**AUTO-ENROLLMENT**: `huaweicloud_sandbox_expose_tunnel` automatically enrolls every exposed tunnel into the keepalive watchdog (merged into existing coverage — exposing a second tunnel never drops the first one's protection; `keepalive: false` opts out). The developer's requirement — "every tunnel deployed to the sandbox must be keepalive-protected" — is satisfied by the tool itself, not by remembering to call the watchdog.
+
+The tunnel URL is bound to the tunnel ID, not the host process — persistence is about **preventing expiry, never URL recovery**. `-e` accepts 1..720 hours (720 = the 30-day maximum); the expiry is a **rolling window** (renewal sets `expiration = now + hours` regardless of remaining time), so renewing before expiry keeps the same URL alive indefinitely.
+
+- **Renew** (same URL, extends lifetime): `huaweicloud_sandbox_renew_tunnel` (or `devbridge update <id> -e 720`). A renewal counts as ok only when the update succeeds AND `show <id> -v` reports the absolute `tunnelExpiration` — the management plane can lose a tunnel record (`10002 tunnel not found`) while the data plane keeps serving.
+- **Host process dies** → the watchdog re-attaches with `devbridge host <id>`; the URL does NOT change.
+- **Manual install / replacement / repair** → `huaweicloud_sandbox_keepalive_watchdog`: installs a setsid-detached loop (host watchdog + daily 720h renewal + 5-min health check) at `/tmp/tunnel-keepalive.sh`.
+
+Complete measured procedure and traps (OSC-escape port list, health-check URL, watchdog pgrep): see `references/tunnel-persistence.md`.
+
+## Full-Stack: REST API over PostgreSQL (PostgREST)
+
+When deploying a **full-stack workbench project** (前后端工作台) or asking for a database-backed REST API inside the sandbox (postgres, postgrest, 数据库, RESTful 接口, 工作台后端):
+
+1. **PostgreSQL 16 from PGDG** — the OS repo only ships PG 13, and PostgREST 16.x requires PG ≥ 14. HCE is NOT el8-lib-compatible: hand-write the repo file (the el8 path is `rhel-8-aarch64` WITH a hyphen), install the RPMs one-per-call with `--nodeps`, and shim the sonames — including the REAL `libicu-60` package (ICU symlinks load but crash on versioned symbols).
+2. **PostgREST `linux-static-aarch64`** — dynamic Ubuntu builds fail on HCE glibc. Create the schema and a read-only `api_user` role (the anon role gates all writes; POST/PATCH → 401).
+3. **Nginx single-origin** — `/` serves the frontend, `/api/` reverse-proxies to PostgREST (no CORS, same origin). The frontend dir needs `chmod o+x` on the whole path chain or nginx returns 403.
+4. **Expose + keep alive (automatic)** — `huaweicloud_sandbox_expose_tunnel` with the nginx port; it AUTO-enrolls the tunnel into the keepalive watchdog (merged into existing coverage). Prefer `expiry_hours: 720` for long-lived workbench deployments.
+
+Complete measured procedure (with the full command chain): see `references/fullstack-postgrest.md`.
+
 ## Web Application Deployment
 
 When deploying a web application to the sandbox, build the app inside the sandbox before exposing it. Source code is uploaded, dependencies installed, and the framework built in the sandbox environment.
 
+**Backend present?** If the project includes a PostgreSQL + PostgREST backend (or the developer asks for one), set up the backend FIRST by following [Full-Stack: REST API over PostgreSQL](#full-stack-rest-api-over-postgresql-postgrest) — install PostgreSQL/PostgREST, create the schema, and point the frontend's nginx `/api/` location at PostgREST — then continue with the steps below. Every tunnel exposed afterwards is auto-enrolled into the keepalive watchdog.
+
 **沙箱无 systemd（实测 #935 报告3 问题3）**：沙箱为无 systemd 的容器环境，`systemctl` 全部失效（`System has not been booted with systemd`）—— 不要用 `systemctl start/reload/restart nginx`。Nginx 配置变更直接使用 `nginx -t` 验证 + `nginx -s reload` 热加载，或直接执行 nginx 二进制（`sudo nginx` 启动 / `nginx -s stop` 停止）。`huaweicloud_sandbox_deploy_nginx` 工具返回的 nextStep 文案与该语义一致（配置写入后自动回验存在性与 `nginx -t`，通过后即生效，无需 systemctl）。
 
 ### Step 1: Detect Framework Locally
@@ -980,7 +1042,7 @@ Returns `complete: true/false`, `score`, and `nextStep` to fix missing items.
 | Never expose tunnel details            | Do not mention "DevBridge"/"tunnel"/"devbridge" to the developer — say "正在生成访问地址..." and hand over only the URL                                                                                                                                                                                                                                                                                                                                               |
 | devbridge auth: probe the build        | `0.2.2-release` has two builds: image builds retain AK/SK login + env auto-read (fully automatic via `/tmp/hw_creds.sh`); release builds accept only API Key (`/tmp/hw_api_key`). Never assume — probe with `devbridge auth login --help 2>&1 \| grep -q -- '--access-key'` (Step 1 of "Expose the deployed app")                                                                                                                                                     |
 | devbridge 0.1.x is dead                | Sandboxes created before Sep 2026 ship 0.1.13, which connects to a migrated gateway serving a 「服务已迁移」 placeholder with HTTP 200. Check `devbridge version` first and upgrade in place (Step 0) — old tunnels never survive the upgrade                                                                                                                                                                                                                         |
-| CLI PATH                               | The installer only writes `~/.bashrc`; run `export PATH="$HOME/.huawei/bin:$PATH"` (prepend) in the session before using `devbridge` — appending lets a stale image binary in `/usr/local/bin` win                                                                                                                                                                                                                                                                    |
+| CLI PATH                               | The installer only writes `~/.bashrc`; run `export PATH="/workspace/.local/bin:$HOME/.huawei/bin:$PATH"` (prepend) in the session before using `devbridge` — appending lets a stale image binary in `/usr/local/bin` win. `/workspace/.local/bin` survives sandbox reboots; `~/.huawei/bin` is on the system disk and is wiped on reboot (#999)                                                                                                                       |
 | 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                                                                                                                                                                                                                                                                                                                                                                                     |
 | Deploy is not just nginx               | Configuring nginx does NOT complete the deployment. Steps 7 (DevBridge expose) and deploy_check are REQUIRED — `deploy_nginx` returns `nextStep: expose_via_devbridge` as a reminder. Do not stop after nginx.                                                                                                                                                                                                                                                        |