@delta-infra/cli 1.0.20 → 1.0.21

package/README.md

@@ -157,19 +157,35 @@ delta-cli sandbox kill <sandbox_id>
 
 ### Sandbox 命令
 
+> **提示**：`sandbox list`（列沙箱实例）与 `sandbox ls <id>`（列目录）不同，注意区分。
+
 | 命令 | 说明 |
 |------|------|
-| `delta-cli sandbox list` | 列出当前用户的 sandbox |
+| `delta-cli sandbox list` | 列出当前用户的 sandbox 实例 |
+| `delta-cli sandbox providers` | 查看可用计算后端 |
+| `delta-cli sandbox images` | 查看可用镜像列表 |
+| `delta-cli sandbox recommend --cpu N --memory XGi` | 获取资源配置推荐 |
 | `delta-cli sandbox create --image <img>` | 创建 sandbox 容器 |
 | `delta-cli sandbox connect <id>` | 连接 sandbox |
 | `delta-cli sandbox status <id>` | 查看 sandbox 状态 |
+| `delta-cli sandbox finish <id>` | 保存结果并销毁 |
+| `delta-cli sandbox kill <id>` | 销毁 sandbox |
 | `delta-cli sandbox run <id> --command "..."` | 同步运行命令 |
 | `delta-cli sandbox run-bg <id> --command "..."` | 后台运行命令 |
 | `delta-cli sandbox logs <id> --execution-id <eid>` | 查看后台日志 |
+| `delta-cli sandbox status bg <id> --execution-id <eid>` | 查询后台命令状态 |
+| `delta-cli sandbox cancel <id> --execution-id <eid>` | 中断后台命令 |
 | `delta-cli sandbox read <id> --path <path>` | 读取容器内文件 |
-| `delta-cli sandbox write <id> --path <path> --source <source_path>` | 写入文件 |
-| `delta-cli sandbox finish <id> --results '{...}'` | 标记完成并返回结果 |
-| `delta-cli sandbox kill <id>` | 销毁 sandbox |
+| `delta-cli sandbox write <id> --path <path> --source <本地路径>` | 写入文件 |
+| `delta-cli sandbox write-multiple <id> --entry <远程路径>=<本地路径>` | 批量写入 |
+| `delta-cli sandbox ls <id> --path <path>` | 列出目录 |
+| `delta-cli sandbox stat <id> --path <path>` | 文件元数据 |
+| `delta-cli sandbox mv <id> --entry <src=dest>` | 移动/重命名 |
+| `delta-cli sandbox replace <id> --path <path> --old <文本> --new <文本>` | 替换内容 |
+| `delta-cli sandbox chmod <id> --path <path> --mode <八进制>` | 修改权限 |
+| `delta-cli sandbox rm <id> --path <path>` | 删除文件 |
+| `delta-cli sandbox mkdir <id> --path <路径>` | 创建目录 |
+| `delta-cli sandbox search <id> --path <根目录> --pattern <glob>` | 搜索文件 |
 
 ## 输出格式
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delta-infra/cli",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "Delta Sandbox CLI",
   "bin": {
     "delta-cli": "scripts/run.js"

package/skills/delta-sandbox/SKILL.md

@@ -36,14 +36,22 @@ metadata:
 6. **禁止重复创建**：同一次任务中只允许存在一个活跃 sandbox。若命令失败需要重试，优先复用已创建的 `sandbox_id`；若确实需要重新创建，必须先 `sandbox kill <旧_sandbox_id>`，确认旧实例销毁后再执行新的 `sandbox create`。可用 `delta-cli sandbox list` 查询当前用户的活跃 sandbox，但 **禁止** 用 list 来绕过“同一次任务只保留一个 sandbox”的规则。
 
 7. **长任务必须后台执行**：预计执行时间超过 60 秒的任务（例如下载模型、训练、微调、长推理、大规模数据处理），**必须**使用 `delta-cli sandbox run-bg <id> --command "..." --timeout <秒>` 提交为后台任务，禁止使用同步的 `sandbox run`。
-   - 轮询用 `delta-cli sandbox logs <id> --execution-id <exec_id>`，每 15-30 秒一次。
-   - 完成判断（按优先级）：
-     a) `finished=true` + `exit_code=0` → 正常完成
-     b) `finished=true` + `exit_code!=0` → 命令执行失败，查看 stderr
-     c) `running=true` → 仍在运行，继续等待
-   - 也可用 `delta-cli sandbox status bg <id> --execution-id <exec_id>` 直接查询后台命令的运行状态和退出码。
-   - **只消耗一次 tool call 的等待方式**：`delta-cli sandbox run-bg <id> --command "<命令>" --timeout <秒> --wait` — CLI 在内部轮询直到完成，一次性返回结果。适用于不想多次调用 `logs` 轮询的场景。
-   - 故障诊断：连续 3 次 `running=true` 且 `content`/`cursor` 无变化且距离提交超过 60 秒 → 用 `sandbox status <id>` 检查 sandbox 是否存活。如果 sandbox 正常但 logs 无输出，用 `sandbox run <id> --command "ps aux" --timeout 15` 在容器内检查进程状态。
+
+   **推荐方式（1 次 tool call 等完成）**：
+   ```bash
+   delta-cli sandbox run-bg <id> --command "<命令>" --timeout <秒> --wait
+   ```
+   CLI 在内部每 5 秒轮询一次 `logs`，直到 `finished=true` 或超时，然后一次性返回 `{running, finished, exit_code, content}`。适合只关心最终结果、不需要查看中间进度的场景。
+
+   **手动轮询（需要查看中间进度时）**：
+   如果不加 `--wait` 或需要查看实时输出，用 `sandbox logs <id> --execution-id <exec_id>` 手动轮询：
+   - `finished=true` + `exit_code=0` → 完成
+   - `finished=true` + `exit_code!=0` → 失败  
+   - `running=true` → 仍运行
+   快速查询：`sandbox status bg <id> --execution-id <exec_id>`（只含状态，不含日志内容）
+
+   **故障诊断**：连续 3 次 `running=true` 且 `content`/`cursor` 无变化且距离提交超过 60 秒 → 用 `sandbox status <id>` 检查 sandbox 是否存活。
+
    - 后台任务成功后仍需按规则 2/3 销毁 sandbox。
 
 8. **写入文件禁止使用路径或 Shell 变量，仅允许文件名**：
@@ -56,31 +64,51 @@ metadata:
 
 ## 快速路由
 
+> ⚠️ **`list` 与 `ls` 区分**：`sandbox list` 列出用户的 **沙箱实例**（与 `docker ps` 类似），`sandbox ls <id>` 列出 **沙箱内目录**（与 `ls` 命令类似）。Tab 补全时注意区分。
+
 | 用户目标 | 命令 |
 |---------|------|
+| **发现** | |
 | 查看可用镜像 | `sandbox images` |
+| 查看可用 provider | `sandbox providers` |
+| 获取资源推荐 | `sandbox recommend --cpu N --memory XGi [--gpu N] [--gpu-mem N]` |
 | 列出当前用户的 sandbox | `sandbox list` |
-| 创建 sandbox | `sandbox create --image <image>` |
+| **生命周期** | |
+| 创建 sandbox | `sandbox create --image <image> [--cpu N --memory XGi --gpu N --gpu-mem N --max-life M]` |
 | 连接 sandbox | `sandbox connect <id>` |
 | 查看状态 | `sandbox status <id>` |
-| 同步运行命令 | `sandbox run <id> --command "..."` |
-| 后台运行命令 | `sandbox run-bg <id> --command "..."` |
-| 查看后台日志 | `sandbox logs <id> --execution-id <exec_id>`（仅用于 `run-bg`） |
-| 查询命令状态 | `sandbox status bg <id> --execution-id <exec_id>` |
+| 完成 sandbox | `sandbox finish <id> [--results '{...}']` |
+| 销毁 sandbox | `sandbox kill <id>` |
+| **命令执行** | |
+| 同步运行命令（≤60s） | `sandbox run <id> --command "..." [--timeout <秒>]` |
+| 后台运行命令（>60s） | `sandbox run-bg <id> --command "..." [--timeout <秒>] [--wait]` |
+| 查看后台日志 | `sandbox logs <id> --execution-id <exec_id>` |
+| 查询后台状态 | `sandbox status bg <id> --execution-id <exec_id>` |
+| 中断后台命令 | `sandbox cancel <id> --execution-id <exec_id>` |
+| **文件操作** | |
 | 读取文件 | `sandbox read <id> --path <path>` |
 | 写入文件 | `sandbox write <id> --path <path> --source <文件名>`（推荐）|
-| 文件信息 | `sandbox stat <id> --path <path>` |
-| 列出目录 | `sandbox ls <id> --path <路径>` |
-| 完成 sandbox | `sandbox finish <id> --results '{...}'` |
-| 销毁 sandbox | `sandbox kill <id>` |
+| 批量写入 | `sandbox write-multiple <id> --entry <src=path> [--entry ...]` |
+| 列出目录 | `sandbox ls <id> --path <路径>`（默认 `.`）|
+| 文件元数据 | `sandbox stat <id> --path <path>` |
+| 移动/重命名 | `sandbox mv <id> --entry <src=dest> [--entry ...]` |
+| 替换内容 | `sandbox replace <id> --path <path> --old <文本> --new <文本>` |
+| 修改权限 | `sandbox chmod <id> --path <path> --mode <八进制>` |
+| 删除文件 | `sandbox rm <id> --path <path> [--path ...]` |
+| 创建目录 | `sandbox mkdir <id> --path <路径> [--path ...]` |
+| 搜索文件 | `sandbox search <id> --path <根目录> --pattern <glob>` |
 
 ## 完整生命周期
 
-1. **选择镜像并查看可用镜像**：`delta-cli sandbox images` — 查询服务端支持的镜像列表，根据用户需求的编程语言和工具链匹配镜像。例如 `deltarouter/python:latest`（Python）、`node:20`（Node.js）、`golang:1.23`（Go），镜像决定了容器内可用的语言/运行时环境。
+1. **选择 Provider 和镜像**：
+   - `delta-cli sandbox providers` — 查看可用的计算后端（`opensandbox` / `autodl`）
+   - `delta-cli sandbox images` — 查询服务端支持的镜像列表，根据用户需求的编程语言和工具链匹配镜像。例如 `deltarouter/python:latest`（Python）、`node:20`（Node.js）、`golang:1.23`（Go），镜像决定了容器内可用的语言/运行时环境。
+   - `delta-cli sandbox recommend --cpu N --memory XGi [--gpu N]` — 获取资源配置推荐（自动选择 provider 和镜像）
 2. **创建**：`delta-cli sandbox create --image <img> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120`（创建后 sandbox 立即可用，无需额外连接）。**同一次任务若已有 `sandbox_id`，禁止再次 create，必须优先复用。**
    - --max-life 指定 sandbox 最大存活时间（分钟），默认 30。长任务请调高，确保 sandbox 在命令执行期间不被回收。
    - 这是 `sandbox create` 支持的完整资源参数集合，不存在其它“更正确”的资源 flag，不要发明不存在的参数。
-3. **写入代码/数据**：`delta-cli sandbox write <id> --path /workspace/<filename> --source <文件名>` — **必须**使用相对路径（如 `--source train.py`），**禁止**使用 `"$WORKSPACE_ROOT/train.py"` 或 `$(pwd)/train.py` 等 Shell 变量路径。`--source` 让 CLI 自行读取本地文件，不会经过 Shell 展开，是最安全的方式。少量配置（<20 行）可用 `--data "..."`。文件路径和扩展名由镜像中的运行时决定。
+3. **写入代码/数据**：`delta-cli sandbox write <id> --path /workspace/<filename> --source <文件名>` — **必须**使用相对路径（如 `--source train.py`），**禁止**使用 `"$WORKSPACE_ROOT/train.py"` 或 `$(pwd)/train.py` 等 Shell 变量路径。`--source` 让 CLI 自行读取本地文件，不会经过 Shell 展开，是最安全的方式。写入后返回的 `size` 字段是实际磁盘字节数（来自 stat 验证），可对比确认写入完整性。批量写入用 `sandbox write-multiple <id> --entry <远程路径>=<本地路径>`。少量配置（<20 行）可用 `--data "..."`。文件路径和扩展名由镜像中的运行时决定。
+   - **写后验证**：`sandbox stat <id> --path <path>` 确认文件存在且 size 符合预期；`sandbox read <id> --path <path>` 读取内容并对比返回的 `size`（磁盘字节）和 `content_length`（字符长度）判断是否有编码偏差。
 4. **运行命令**：
    - **短任务（预计 ≤ 60 秒）**：`delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` 同步执行，结果（`stdout` / `stderr` / `exit_code`）直接返回，**不要**再调用 `sandbox logs`。根据镜像中的运行时构造命令，常见示例：
      - Python：`python /workspace/train.py`
@@ -91,7 +119,7 @@ metadata:
      - `delta-cli sandbox logs <id> --execution-id <execution_id>` — 返回 `content`、`cursor`、`running`、`finished`、`exit_code`。当 `finished=true` 时认为完成。
      - `delta-cli sandbox status bg <id> --execution-id <execution_id>` — 返回 `running`、`finished`、`exit_code`。
      禁止对长任务使用同步 `sandbox run`
-5. **读取结果**：`delta-cli sandbox read <id> --path /workspace/result.json`
+5. **读取结果**：`delta-cli sandbox read <id> --path /workspace/result.json` — 返回 `content`（内容）、`size`（磁盘字节数，来自 stat 验证）、`content_length`（内存字符长度）。对比 `size` 与 `content_length` 可判断文件是否为纯文本。读不存在的文件会返回 error，不会静默返回空内容。
 6. **销毁**：`delta-cli sandbox kill <id>`（如需保存结果，用 `sandbox finish --results '{...}'` 替代 kill，finish 会自动销毁 sandbox）
 
 详细步骤见 [lifecycle.md](references/lifecycle.md)。

package/skills/delta-sandbox/references/commands.md

@@ -2,17 +2,55 @@
 
 # 命令速查表
 
+## 发现
+
 | 命令 | 说明 |
 |------|------|
+| `sandbox list` | 列出当前用户创建的活跃 sandbox（与 `ls` 不同：这是列 **沙箱实例**） |
+| `sandbox providers` | 查看可用的计算后端（opensandbox / autodl） |
 | `sandbox images` | 查看可用镜像列表 |
-| `sandbox list` | 列出当前用户创建的活跃 sandbox |
-| `sandbox create` | 创建 sandbox |
-| `sandbox connect` | 连接 sandbox |
-| `sandbox kill` | 直接销毁 sandbox，不保存结果（有结果要保存时用 finish 替代） |
-| `sandbox finish` | 保存结果后自动销毁 sandbox（二选一：finish 或 kill，不要同时调用） |
-| `sandbox status` | 查看状态 |
-| `sandbox run` | 同步运行命令，结果直接返回 |
-| `sandbox run-bg` | 后台运行命令 |
-| `sandbox logs` | 获取后台命令日志（仅配合 `run-bg`） |
-| `sandbox read` | 读取文件 |
-| `sandbox write` | 写入文件 |
+| `sandbox recommend --cpu N --memory XGi [--gpu N] [--gpu-mem N]` | 获取资源配置推荐 |
+
+## 生命周期
+
+| 命令 | 说明 |
+|------|------|
+| `sandbox create --image <img> [--cpu N --memory XGi --gpu N --gpu-mem N --max-life M --provider P]` | 创建 sandbox 容器 |
+| `sandbox connect <id>` | 连接已有 sandbox |
+| `sandbox status <id>` | 查看 sandbox 状态（running / done） |
+| `sandbox finish <id> [--results '{...}']` | 保存结果后自动销毁 |
+| `sandbox kill <id>` | 直接销毁 sandbox（不保存结果） |
+
+## 命令执行
+
+| 命令 | 说明 |
+|------|------|
+| `sandbox run <id> --command "..." [--timeout N]` | 同步运行命令，结果直接返回 |
+| `sandbox run-bg <id> --command "..." [--timeout N] [--wait]` | 后台运行命令，返回 execution_id |
+| `sandbox logs <id> --execution-id <eid>` | 获取后台命令日志 |
+| `sandbox status bg <id> --execution-id <eid>` | 查询后台命令状态（不含日志内容） |
+| `sandbox cancel <id> --execution-id <eid>` | 中断正在运行的后台命令 |
+
+## 文件操作
+
+| 命令 | 说明 |
+|------|------|
+| `sandbox read <id> --path <path>` | 读取文件；返回 `content` + `size`（磁盘字节）+ `content_length`（字符长度） |
+| `sandbox write <id> --path <path> --source <文件名>` | 写入文件（推荐，相对路径） |
+| `sandbox write <id> --path <path> --data "..."` | 写入少量内联内容 |
+| `sandbox write-multiple <id> --entry <src=path> [--entry ...]` | 批量写入多个文件 |
+| `sandbox ls <id> --path <path>` | 列出目录内容（默认 `.`） |
+| `sandbox stat <id> --path <path>` | 获取文件元数据（size / mode / owner / group） |
+| `sandbox mv <id> --entry <source=dest> [--entry ...]` | 移动或重命名文件 |
+| `sandbox replace <id> --path <path> --old <文本> --new <文本> [--regex] [--ignore-case]` | 替换文件内容 |
+| `sandbox chmod <id> --path <path> --mode <八进制>` | 修改文件权限 |
+| `sandbox rm <id> --path <path> [--path ...]` | 删除文件 |
+| `sandbox mkdir <id> --path <路径> [--path ...]` | 创建目录（mkdir -p） |
+| `sandbox search <id> --path <根目录> --pattern <glob>` | 搜索文件 |
+
+## 注意事项
+
+- `list` ≠ `ls`：`sandbox list` 列沙箱实例，`sandbox ls <id>` 列沙箱内目录
+- 写文件后返回的 `size` 是 stat 验证后的实际磁盘字节数
+- 读文件返回 `size`（磁盘字节，来自 stat）和 `content_length`（内存字符数），对比可判断编码偏差
+- 读不存在的文件会返回 error，不会静默返回空内容

package/skills/delta-sandbox/references/lifecycle.md

@@ -7,10 +7,11 @@
 1. **查看可用镜像** `delta-cli sandbox images` — 查询服务端支持的镜像列表。镜像决定了容器内的语言运行时（Python / Node.js / Go / Java / Rust 等），根据用户的技术栈和 GPU/CPU 需求匹配。
 2. **列出现有 sandbox（可选）** `delta-cli sandbox list` — 查看当前用户已创建的活跃 sandbox，避免重复创建
 3. **创建** `delta-cli sandbox create --image <image> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120`（创建后立即可用，无需连接；--max-life 指定 sandbox 最大存活时间（分钟），默认 30；这些是 `create` 全部资源参数，不要发明其它 flag。`--provider autodl` 可指定使用 AutoDL 后端。）
-4. **写入代码/数据** `delta-cli sandbox write <id> --path /workspace/<filename> --source <文件名>` — 将本地文件直接写入 sandbox。**必须**使用相对路径（如 `--source infer.py`），禁止使用 `"$WORKSPACE_ROOT/<filename>"`。也可用 `--data "..."` 写入少量内联内容，`--mode 755` 可设置文件权限。文件路径和扩展名由镜像中的运行时决定。
-5. **运行命令** `delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` — 根据镜像中的运行时构造命令，常见示例：`python /workspace/train.py`（Python）、`node /workspace/app.js`（Node.js）、`go run /workspace/main.go`（Go）、`bash /workspace/run.sh`（Shell）
-   - `sandbox run` 是同步执行，返回结果里直接包含 `stdout`、`stderr`、`exit_code`，**不要**再调 `sandbox logs`
-6. **读取结果** `delta-cli sandbox read <id> --path /workspace/result.json`
+4. **写入代码/数据** `delta-cli sandbox write <id> --path /workspace/<filename> --source <文件名>` — 将本地文件直接写入 sandbox。**必须**使用相对路径（如 `--source infer.py`），禁止使用 `"$WORKSPACE_ROOT/<filename>"`。也可用 `--data "..."` 写入少量内联内容，`--mode 755` 可设置文件权限。写入后返回的 `size` 字段是 stat 验证后的实际磁盘字节数，可确认写入完整。批量写入用 `write-multiple`。文件路径和扩展名由镜像中的运行时决定。
+5. **运行命令** — 根据镜像中的运行时构造命令，常见示例：`python /workspace/train.py`（Python）、`node /workspace/app.js`（Node.js）、`go run /workspace/main.go`（Go）、`bash /workspace/run.sh`（Shell）
+   - **短任务 ≤60s**：`delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` 同步执行，返回 `stdout`/`stderr`/`exit_code`
+   - **长任务 >60s**：`delta-cli sandbox run-bg <id> --command "<命令>" --timeout <秒> --wait` 后台执行（推荐），或 `run-bg` + `logs` 手动轮询
+6. **读取结果** `delta-cli sandbox read <id> --path /workspace/result.json` — 返回 `content`（内容）、`size`（磁盘字节，来自 stat）、`content_length`（字符数）。读不存在的文件返回 error 而非空内容。
 7. **销毁** `delta-cli sandbox kill <id>`（如需保存结果用 finish，finish 会自动销毁）
 
 > **注意**：server 端没有 sandbox 的自动过期或 TTL 机制，不 kill 会永久占用 GPU 资源。请务必在任务结束后销毁。
@@ -19,18 +20,25 @@
 
 对于长时间运行的任务（>60 秒，如训练、编译、数据处理），使用 `run-bg` 在后台异步执行：
 
+### 方式一（推荐）：`--wait` 一次性等待完成
+
 ```bash
-# 1. 启动后台命令（立即返回，不阻塞）
-# delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200
-# 或用 `--wait` 让 CLI 内部等待完成（只消耗一次 tool call）：
-# delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200 --wait
+delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200 --wait
+```
+CLI 内部每 5 秒轮询一次，`finished=true` 时返回。只消耗 **1 次 tool call**，适合不关心中间进度的场景。
 
-# ↑ 返回数据中包含 execution_id，请保存以便后续查询
+### 方式二：手动轮询（需要看实时输出时）
+
+```bash
+# 1. 启动后台命令
+delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200
+# ↑ 返回 execution_id
 
-# 2. 轮询日志判断任务状态（可在后续 tool call 轮次执行）
+# 2. 手动轮询进度
 delta-cli sandbox logs <id> --execution-id <exec_id>
+# ↑ 返回 {content, cursor, running, finished, exit_code}
 
-# 3. 全部完成后销毁 sandbox
+# 3. 完成后销毁
 delta-cli sandbox kill <id>
 ```
 
@@ -54,8 +62,8 @@ delta-cli sandbox kill <id>
 1. **`finished=true` + `exit_code=0`** → 正常完成，可以读取结果并销毁 sandbox
 2. **`finished=true` + `exit_code≠0`** → 命令执行失败，查看 stderr/error 信息
 3. **`running=true`** → 任务仍在运行，继续等待（建议每 15-30 秒查询一次）
-5. **连续 3 次 `running=true` 且 `content`/`cursor` 无变化且距离提交超过 60 秒** → 任务可能挂起或无输出，用 `sandbox status <id>` 检查 sandbox 是否存活；也可用 `sandbox status bg <id> --execution-id <exec_id>` 查后台命令状态
-6. **`sandbox status` 返回正常但 logs 仍然无变化** → 用 `sandbox run <id> --command "ps aux | grep <进程名>" --timeout 15` 在容器内检查命令是否还在运行
+4. **连续 3 次 `running=true` 且 `content`/`cursor` 无变化且距离提交超过 60 秒** → 任务可能挂起或无输出，用 `sandbox status <id>` 检查 sandbox 是否存活；也可用 `sandbox status bg <id> --execution-id <exec_id>` 查后台命令状态
+5. **`sandbox status` 返回正常但 logs 仍然无变化** → 用 `sandbox run <id> --command "ps aux | grep <进程名>" --timeout 15` 在容器内检查命令是否还在运行
 
 **注意**：
 - `sandbox logs` 只应配合 `sandbox run-bg` 使用；同步 `sandbox run` 的结果直接返回，不能也不应该调用 `logs`。