@delta-infra/cli 1.0.82 → 1.0.84

package/skills/delta-sandbox/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Delta Sandbox 工作站"
-  short_description: "通过 Delta CLI 安全创建、运行并销毁隔离计算工作站"
-  default_prompt: "使用 $delta-sandbox 在隔离工作站中完成这项计算并返回结果。"
+interface:
+  display_name: "Delta Sandbox 工作站"
+  short_description: "通过 Delta CLI 安全创建、运行并销毁隔离计算工作站"
+  default_prompt: "使用 $delta-sandbox 在隔离工作站中完成这项计算并返回结果。"

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

@@ -1,56 +1,56 @@
-> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
-
-# 命令速查表
-
-## 发现
-
-| 命令 | 说明 |
-|------|------|
-| `sandbox list` | 列出当前用户创建的活跃 sandbox（与 `ls` 不同：这是列 **沙箱实例**） |
-| `sandbox providers` | 查看可用的计算后端（opensandbox / autodl） |
-| `sandbox images` | 查看可用镜像列表 |
-| `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] [--summary/--no-summary] [--artifacts]` | 同步运行命令；默认 `--summary` 开启，返回 JSON 中 `summary` 字段已含 stdout 末尾 JSON 提取结果；`--artifacts` 附带 workspace 产物清单 |
-| `sandbox run-bg <id> --command "..." [--timeout N] [--wait] [--summary/--no-summary] [--artifacts]` | 后台运行命令；不加 `--wait` 立即返回 `{execution_id, sandbox_id}`；加 `--wait` 等待完成返回含 `summary` 的完整结果 |
-| `sandbox logs <id> --execution-id <eid> [--tail N --grep <pattern> --context N]` | 获取后台命令日志；**默认返回 `stdout_tail`（末尾 800 字节）+ `stderr_tail`（末尾 200 字节）+ `stderr_size` + `cursor`**，总计约 1KB，避免上下文爆炸；`--tail N` 同时作用于 stdout 和 stderr（各取尾 N 行）；`--grep <pattern>` 同时过滤 stdout 和 stderr（正则）；`--context N` 提供 grep 匹配行前后 N 行上下文（同时用于 stdout 和 stderr）；**`cursor` 字段无 `omitempty`，0 也常驻响应**。 |
-| `sandbox cancel <id> --execution-id <eid>` | 中断正在运行的后台命令 |
-
-## 文件操作
-
-| 命令 | 说明 |
-|------|------|
-| `sandbox read <id> --path <path> [--output <本地路径>] [--tail N] [--grep <pattern>] [--offset N] [--limit N] [--context N] [--max-bytes N] [--parse-json]` | 读取文件；返回 `content` + `size` + `content_length`；`--output <path>` 保存到本地；`--tail/--grep` 用于过滤；非 UTF-8 文件 CLI 自动走 base64 fallback |
-| `sandbox write <id> --path <path> --source <文件名>` | 写入文件（推荐，相对路径） |
-| `sandbox write <id> --path <path> --data "..."` | 写入少量内联内容 |
-| `sandbox write-multiple <id> --entry <src=path> [--entry ...]` | 批量写入多个文件 |
-| `sandbox pull <id> --source <沙箱路径> --target <本地路径> [--recursive] [--pattern <glob>]` | 拉取文件/目录到本地（mirror of `upload`，flag 方向相反：`--source`=远程沙箱路径，`--target`=本地路径）；单文件自动识别；目录默认递归；CLI 端 + 服务端双向 sha1 完整性校验 |
-| `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，不会静默返回空内容
+> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
+
+# 命令速查表
+
+## 发现
+
+| 命令 | 说明 |
+|------|------|
+| `sandbox list` | 列出当前用户创建的活跃 sandbox（与 `ls` 不同：这是列 **沙箱实例**） |
+| `sandbox providers` | 查看可用的计算后端（opensandbox / autodl） |
+| `sandbox images` | 查看可用镜像列表 |
+| `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] [--summary/--no-summary] [--artifacts]` | 同步运行命令；默认 `--summary` 开启，返回 JSON 中 `summary` 字段已含 stdout 末尾 JSON 提取结果；`--artifacts` 附带 workspace 产物清单 |
+| `sandbox run-bg <id> --command "..." [--timeout N] [--wait] [--summary/--no-summary] [--artifacts]` | 后台运行命令；不加 `--wait` 立即返回 `{execution_id, sandbox_id}`；加 `--wait` 等待完成返回含 `summary` 的完整结果 |
+| `sandbox logs <id> --execution-id <eid> [--tail N --grep <pattern> --context N]` | 获取后台命令日志；**默认返回 `stdout_tail`（末尾 800 字节）+ `stderr_tail`（末尾 200 字节）+ `stderr_size` + `cursor`**，总计约 1KB，避免上下文爆炸；`--tail N` 同时作用于 stdout 和 stderr（各取尾 N 行）；`--grep <pattern>` 同时过滤 stdout 和 stderr（正则）；`--context N` 提供 grep 匹配行前后 N 行上下文（同时用于 stdout 和 stderr）；**`cursor` 字段无 `omitempty`，0 也常驻响应**。 |
+| `sandbox cancel <id> --execution-id <eid>` | 中断正在运行的后台命令 |
+
+## 文件操作
+
+| 命令 | 说明 |
+|------|------|
+| `sandbox read <id> --path <path> [--output <本地路径>] [--tail N] [--grep <pattern>] [--offset N] [--limit N] [--context N] [--max-bytes N] [--parse-json]` | 读取文件；返回 `content` + `size` + `content_length`；`--output <path>` 保存到本地；`--tail/--grep` 用于过滤；非 UTF-8 文件 CLI 自动走 base64 fallback |
+| `sandbox write <id> --path <path> --source <文件名>` | 写入文件（推荐，相对路径） |
+| `sandbox write <id> --path <path> --data "..."` | 写入少量内联内容 |
+| `sandbox write-multiple <id> --entry <src=path> [--entry ...]` | 批量写入多个文件 |
+| `sandbox pull <id> --source <沙箱路径> --target <本地路径> [--recursive] [--pattern <glob>]` | 拉取文件/目录到本地（mirror of `upload`，flag 方向相反：`--source`=远程沙箱路径，`--target`=本地路径）；单文件自动识别；目录默认递归；CLI 端 + 服务端双向 sha1 完整性校验 |
+| `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

@@ -1,92 +1,92 @@
-> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
-
-# Delta Sandbox 生命周期
-
-## 完整流程
-
-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` 可设置文件权限。写入后返回的 `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` (默认带 --summary，返回 JSON data.result_summary 已含 stdout 末尾 JSON 提取结果)
-   - **长任务 >60s**：`delta-cli sandbox run-bg <id> --command "<命令>" --timeout <秒> --wait` 后台执行（推荐），或 `run-bg` + `logs` 手动轮询 (run-bg --wait 默认带 --summary；不加 --wait 立即返回 {execution_id, sandbox_id})
-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 资源。请务必在任务结束后销毁。
-
-## 后台任务
-
-对于长时间运行的任务（>60 秒，如训练、编译、数据处理），使用 `run-bg` 在后台异步执行：
-
-### 方式一（推荐）：`--wait` 一次性等待完成
-
-```bash
-delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200 --wait
-```
-CLI 内部每 5 秒轮询一次，`finished=true` 时返回，结果中包含 `execution_id`。只消耗 **1 次 tool call**，适合不关心中间进度的场景。
-
-> `--wait` 默认带 `--summary`，返回的 JSON `data.result_summary` 字段已包含 stdout 末尾结构化 JSON 的提取结果。常用场景无需再调 `sandbox read` 二次解析 log_file。
-
-> ⚠️ **返回类型不对称**：`finished=true` 时返回 `CommandResult` 信封（含 `execution_id, sandbox_id, finished, exit_code, stderr_tail, stderr_size, log_file, result_summary, hints, error`）；若轮询 deadline 到了仍未 `finished=true`（即 `--timeout` 超时），CLI 会返回 `CommandLogsResult` 信封（**字段集合不同**：含 `cursor, running, finished, exit_code, stderr_tail, stderr_size, log_file?` 但**没有 `result_summary` / `hints` / `sandbox_id`**）。调用方解析 `run-bg --wait` 返回时应兼容两种 schema。从 `execution_id` 是否存在可粗略区分，更准确的信号是 `result_summary` 字段是否存在。
-
-### 方式二：手动轮询（需要看实时输出时）
-
-```bash
-# 1. 启动后台命令
-delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200
-# ↑ 返回 execution_id
-
-# 2. 手动轮询进度（可用 --tail N / --grep <pattern> 过滤大输出）
-delta-cli sandbox logs <id> --execution-id <exec_id>
-# ↑ 返回 {sandbox_id, execution_id, stderr_tail, stderr_size, cursor, running, finished, exit_code, log_file?}
-
-# 3. 完成后销毁
-delta-cli sandbox kill <id>
-```
-
-### 轮询判断逻辑
-
-`sandbox logs` 返回的数据结构为：
-
-```json
-{"ok":true,"data":{"sandbox_id":"...","execution_id":"...","stdout_tail":"...","stderr_tail":"...","stdout_size":1234,"stderr_size":1234,"cursor":5,"running":false,"finished":true,"exit_code":0,"log_file":"/tmp/delta-result-...json"}}
-```
-
-字段说明：
-- `sandbox_id` / `execution_id` — 与请求一致
-- `stdout_tail` — CLI 默认保留的 **最后 800 字节** stdout 片段，避免上下文爆炸
-- `stderr_tail` — CLI 默认保留的 **最后 200 字节** stderr 片段（CLI 硬编码 `tailString(s, n)` 按字节截取；ASCII 等同 n 字符，多字节 UTF-8 可能被截断），避免上下文爆炸。不传任何 range flag 时，CLI 会把原始 `stdout`/`stderr` 字段清空，只暴露 `stdout_tail`/`stderr_tail` 和 `stdout_size`/`stderr_size`
-- `stdout_size` — 原始 stdout 字节数（CLI 端计算）
-- `stderr_size` — 原始 stderr 字节数（CLI 端计算）
-- `cursor` — 服务端 stderr 行计数器；**该字段无 `omitempty`，永远出现在响应中**（即使为 0）。`cursor=0` 通常意味着服务端从 provider 还没读到任何 stderr 行
-- `running` — 命令是否仍在运行
-- `finished` — 命令是否已完成（`finished = not running`）
-- `exit_code` — 退出码（完成后才有值，运行中字段省略）
-- `log_file` — 仅 `finished=true` 时出现，是 run envelope 日志文件路径（含完整 stdout + stderr + exit_code + finished + command + error），需读它用 `delta-cli sandbox read <id> --path <log_file>`
-
-**stdout 路径说明**：`sandbox logs` 默认返回 stdout 末尾 800 字节（`stdout_tail`）提供实时中间进度预览，完整 stdout 仍在命令结束时被写入沙箱内的 `log_file`，需全文时用 `sandbox read` 读。CLI `run-bg --wait` 完成后默认开启 `--summary`，会自动 reverse-scan stdout 末尾 JSON 填入 `data.result_summary`，常用场景无需手动读 `log_file`。
-
-要用 `--tail/--grep/--context` 自定义切片：传任意一个 flag 时，CLI 会把过滤后的 stdout 和 stderr 分别写回 `stdout`/`stderr` 字段并更新 `stdout_size`/`stderr_size`；不传则保持 `stdout=""` + `stdout_tail` 末尾 800 字节预览 + `stderr=""` + `stderr_tail` 末尾 200 字节预览（总计约 1KB）。
-
-```bash
-# 看最后 50 行 stdout 和 stderr
-delta-cli sandbox logs <id> --execution-id <eid> --tail 50
-# 过滤 ERROR/warning 行（同时作用于 stdout 和 stderr）
-delta-cli sandbox logs <id> --execution-id <eid> --grep "ERROR|warning" --context 2
-```
-
-判断任务状态的规则（按优先顺序）：
-
-1. **`finished=true` + `exit_code=0`** → 正常完成，可以读取结果并销毁 sandbox
-2. **`finished=true` + `exit_code≠0`** → 命令执行失败，查看 stderr/error 信息
-3. **`running=true`** → 任务仍在运行，继续等待（建议每 15-30 秒查询一次）
-4. **连续 3 次 `running=true` 且 `stderr_tail`/`cursor` 无变化且距离提交超过 60 秒** → 任务可能挂起或无输出，用 `sandbox status <id>` 检查 sandbox 是否存活
-5. **`sandbox status` 返回正常但 logs 仍然无变化** → 用 `sandbox run <id> --command "ps aux | grep <进程名>" --timeout 15` 在容器内检查命令是否还在运行
-
-**注意**：
-- `sandbox logs` 只应配合 `sandbox run-bg` 使用；同步 `sandbox run` 的结果直接返回，不能也不应该调用 `logs`。
-- `sandbox run-bg` 不加 `--wait` 时，HTTP 请求本身会快速返回 `{execution_id, sandbox_id}`；命令若超时会以非零退出码结束，需后续通过 `logs` 拿 `exit_code`。
-- `sandbox run-bg --wait` 模式下，`--timeout` **同时**充当服务端命令执行超时和客户端轮询 deadline（默认 300s）；轮询间隔固定 5 秒；初始 `/run-background` POST 有独立的 60s HTTP timeout。
-- 后台命令可跨 tool call 轮次查询：保存 `sandbox_id` 和 `execution_id`，后续轮次通过 `sandbox status` / `sandbox logs` 获取结果。
+> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
+
+# Delta Sandbox 生命周期
+
+## 完整流程
+
+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` 可设置文件权限。写入后返回的 `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` (默认带 --summary，返回 JSON data.result_summary 已含 stdout 末尾 JSON 提取结果)
+   - **长任务 >60s**：`delta-cli sandbox run-bg <id> --command "<命令>" --timeout <秒> --wait` 后台执行（推荐），或 `run-bg` + `logs` 手动轮询 (run-bg --wait 默认带 --summary；不加 --wait 立即返回 {execution_id, sandbox_id})
+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 资源。请务必在任务结束后销毁。
+
+## 后台任务
+
+对于长时间运行的任务（>60 秒，如训练、编译、数据处理），使用 `run-bg` 在后台异步执行：
+
+### 方式一（推荐）：`--wait` 一次性等待完成
+
+```bash
+delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200 --wait
+```
+CLI 内部每 5 秒轮询一次，`finished=true` 时返回，结果中包含 `execution_id`。只消耗 **1 次 tool call**，适合不关心中间进度的场景。
+
+> `--wait` 默认带 `--summary`，返回的 JSON `data.result_summary` 字段已包含 stdout 末尾结构化 JSON 的提取结果。常用场景无需再调 `sandbox read` 二次解析 log_file。
+
+> **结果信封统一为 `CommandResult`**：`run-bg --wait` 始终返回同一 `CommandResult` 信封：`{execution_id, sandbox_id, finished, exit_code, stderr_tail, stderr_size, log_file, result_summary, hints, error}`，`finished` 键**始终存在**。`finished=true` 表示执行结束并带富化摘要（`result_summary`/`hints`）；`finished=false` 表示命令仍在运行（`exit_code` 与富化字段可能缺失），需用 `sandbox logs` 继续轮询或 `sandbox status` 查看。
+
+### 方式二：手动轮询（需要看实时输出时）
+
+```bash
+# 1. 启动后台命令
+delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200
+# ↑ 返回 execution_id
+
+# 2. 手动轮询进度（可用 --tail N / --grep <pattern> 过滤大输出）
+delta-cli sandbox logs <id> --execution-id <exec_id>
+# ↑ 返回 {sandbox_id, execution_id, stderr_tail, stderr_size, cursor, running, finished, exit_code, log_file?}
+
+# 3. 完成后销毁
+delta-cli sandbox kill <id>
+```
+
+### 轮询判断逻辑
+
+`sandbox logs` 返回的数据结构为：
+
+```json
+{"ok":true,"data":{"sandbox_id":"...","execution_id":"...","stdout_tail":"...","stderr_tail":"...","stdout_size":1234,"stderr_size":1234,"cursor":5,"running":false,"finished":true,"exit_code":0,"log_file":"/tmp/delta-result-...json"}}
+```
+
+字段说明：
+- `sandbox_id` / `execution_id` — 与请求一致
+- `stdout_tail` — CLI 默认保留的 **最后 800 字节** stdout 片段，避免上下文爆炸
+- `stderr_tail` — CLI 默认保留的 **最后 200 字节** stderr 片段（CLI 硬编码 `tailString(s, n)` 按字节截取；ASCII 等同 n 字符，多字节 UTF-8 可能被截断），避免上下文爆炸。不传任何 range flag 时，CLI 会把原始 `stdout`/`stderr` 字段清空，只暴露 `stdout_tail`/`stderr_tail` 和 `stdout_size`/`stderr_size`
+- `stdout_size` — 原始 stdout 字节数（CLI 端计算）
+- `stderr_size` — 原始 stderr 字节数（CLI 端计算）
+- `cursor` — 服务端 stderr 行计数器；**该字段无 `omitempty`，永远出现在响应中**（即使为 0）。`cursor=0` 通常意味着服务端从 provider 还没读到任何 stderr 行
+- `running` — 命令是否仍在运行
+- `finished` — 命令是否已完成（`finished = not running`）
+- `exit_code` — 退出码（完成后才有值，运行中字段省略）
+- `log_file` — 仅 `finished=true` 时出现，是 run envelope 日志文件路径（含完整 stdout + stderr + exit_code + finished + command + error），需读它用 `delta-cli sandbox read <id> --path <log_file>`
+
+**stdout 路径说明**：`sandbox logs` 默认返回 stdout 末尾 800 字节（`stdout_tail`）提供实时中间进度预览，完整 stdout 仍在命令结束时被写入沙箱内的 `log_file`，需全文时用 `sandbox read` 读。CLI `run-bg --wait` 完成后默认开启 `--summary`，会自动 reverse-scan stdout 末尾 JSON 填入 `data.result_summary`，常用场景无需手动读 `log_file`。
+
+要用 `--tail/--grep/--context` 自定义切片：传任意一个 flag 时，CLI 会把过滤后的 stdout 和 stderr 分别写回 `stdout`/`stderr` 字段并更新 `stdout_size`/`stderr_size`；不传则保持 `stdout=""` + `stdout_tail` 末尾 800 字节预览 + `stderr=""` + `stderr_tail` 末尾 200 字节预览（总计约 1KB）。
+
+```bash
+# 看最后 50 行 stdout 和 stderr
+delta-cli sandbox logs <id> --execution-id <eid> --tail 50
+# 过滤 ERROR/warning 行（同时作用于 stdout 和 stderr）
+delta-cli sandbox logs <id> --execution-id <eid> --grep "ERROR|warning" --context 2
+```
+
+判断任务状态的规则（按优先顺序）：
+
+1. **`finished=true` + `exit_code=0`** → 正常完成，可以读取结果并销毁 sandbox
+2. **`finished=true` + `exit_code≠0`** → 命令执行失败，查看 stderr/error 信息
+3. **`running=true`** → 任务仍在运行，继续等待（建议每 15-30 秒查询一次）
+4. **连续 3 次 `running=true` 且 `stderr_tail`/`cursor` 无变化且距离提交超过 60 秒** → 任务可能挂起或无输出，用 `sandbox status <id>` 检查 sandbox 是否存活
+5. **`sandbox status` 返回正常但 logs 仍然无变化** → 用 `sandbox run <id> --command "ps aux | grep <进程名>" --timeout 15` 在容器内检查命令是否还在运行
+
+**注意**：
+- `sandbox logs` 只应配合 `sandbox run-bg` 使用；同步 `sandbox run` 的结果直接返回，不能也不应该调用 `logs`。
+- `sandbox run-bg` 不加 `--wait` 时，HTTP 请求本身会快速返回 `{execution_id, sandbox_id}`；命令若超时会以非零退出码结束，需后续通过 `logs` 拿 `exit_code`。
+- `sandbox run-bg --wait` 模式下，`--timeout` **同时**充当服务端命令执行超时和客户端轮询 deadline（默认 300s）；轮询间隔固定 5 秒；初始 `/run-background` POST 有独立的 60s HTTP timeout。
+- 后台命令可跨 tool call 轮次查询：保存 `sandbox_id` 和 `execution_id`，后续轮次通过 `sandbox status` / `sandbox logs` 获取结果。

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

@@ -1,133 +1,133 @@
-# 标准任务请求模式
-
-本文件提供 `delta-sandbox` 处理常见任务时的推荐请求写法。这些示例是语言无关的模板，实际代码由 skill 在 sandbox 内部生成或写入。
-
-## Planner 调用本 skill 时的 required_outputs
-
-所有直接调用 `delta-sandbox` 的 plan step 都应该声明会落盘一个 `.json` 文件。这样 skill 运行命令后把 sandbox `log_file` 写入本地 `result.json` 时，host 可以正确通过 Phase-10B deliverable 校验。
-
-```yaml
-required_outputs:
-  - kind: file
-    extensions: [".json"]
-```
-
-> 说明：这是声明 skill 会创建 `.json` 结果文件，不是要求用户请求中出现 `.json`。用户请求仍按下面的模板使用中性动词。
-
-## 通用脚本输出模板
-
-为了让 skill 用同一套流程生成 `RESULT:` 并避免大模型去摘要长日志，推荐任何 sandbox 脚本在**执行结束时**打印一行结构化 JSON：
-
-```json
-{"status":"ok","key_metric_1":"value_1","key_metric_2":123}
-```
-
-> `sandbox run` / `run-bg --wait` 默认带 `--summary`，CLI 会自动 reverse-scan stdout 末尾的 JSON 并填入响应 `data.result_summary` 字段。脚本作者只需保证 stdout 最后一行是合法 JSON，skill 端无需再做提取。
-
-SKILL 会把它提取为 `result.json` 的 `summary`，并生成 `result_summary` 与最终 `RESULT:` 行。
-
-**不要**再输出 `FINAL_ANSWER: ...` 这样的标记行，也不要在 JSON 里使用 `final_answer` 字段。summary 里的语义字段（如 `output`、`result`、`generated_text`、`final_accuracy`）已经足够表达结果。
-
-不同任务的关键字段示例：
-
-- **CUDA 检查**：`status`, `torch_version`, `cuda_available`, `device_name`
-- **训练任务**：`status`, `epochs`, `final_loss`, `final_accuracy`, `model_file`
-- **推理任务**：`status`, `input_samples`, `output_file`, `avg_latency_ms`
-- **数据处理**：`status`, `input_rows`, `output_rows`, `output_file`
-- **编译/构建**：`status`, `build_time_s`, `output_binary`, `tests_passed`
-
-## 1. GPU / CUDA 可用性检查
-
-用户请求示例：
-
-```text
-在 GPU sandbox 中运行标准 PyTorch CUDA 自检脚本，返回 exit_code、torch 版本、CUDA 是否可用、CUDA/cuDNN 版本、GPU 名称与显存信息。
-```
-
-说明：
-
-- 不要在请求里出现 `torch.cuda.is_available()` 等完整代码 token，避免被 host 误判为 `.cuda` 文件承诺。对应的 plan step 仍按上面模板声明 `.json` 输出。
-- 推荐让脚本在 `stdout` 末尾输出一行结构化 JSON，例如：
-  ```json
-  {"torch_version":"2.7.0+cu128","cuda_available":true,"device_count":1,
-   "device_name":"NVIDIA GeForce RTX 3090","tensor_op":"[101.0]",
-   "memory_before_mb":{"allocated":0,"reserved":0,"max_allocated":0},
-   "memory_after_mb":{"allocated":0.0005,"reserved":2.0,"max_allocated":0.001}}
-  ```
-- skill 会从 `log_file` 提取这个 JSON 作为本地 `result.json` 的 `summary`，最终只输出一行 `RESULT: ...`。
-- 完整 `nvidia-smi` 原始输出保留在 sandbox 的 `log_file` 中。
-
-## 2. 运行用户已有的脚本
-
-```text
-在 sandbox <sandbox_id> 中运行 /workspace/train.py，参数为 --epochs 10 --batch-size 32。
-```
-
-说明：文件已存在，用中性动词 `运行`，不使用 `创建` 等承诺动词。
-
-## 3. 安装依赖并执行命令
-
-```text
-在 sandbox 中运行 pip install -r /workspace/requirements.txt，然后运行 python /workspace/app.py。
-```
-
-说明：依赖安装和命令执行都没有落盘新文件，使用中性动词描述。
-
-## 4. 训练并将指标落盘
-
-```text
-在 GPU sandbox 中运行训练脚本（例如基于 PyTorch 的 MNIST 训练），训练完成后在 stdout 末尾打印包含 epochs、final_loss、final_accuracy、model_file 的结构化 JSON。
-```
-
-说明：
-
-- 训练日志可能很长，不要让 skill 去读整段日志再摘要；让脚本自己输出关键指标。
-- 推荐脚本最终打印：`{"status":"ok","epochs":10,"final_loss":0.023,"final_accuracy":0.992,"model_file":"/workspace/model.pt"}`
-- skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, epochs=10, ...`。
-- 如需保存完整模型文件，可再用 `sandbox read` 或 `sandbox upload` 处理，不属于 `result.json` 的摘要范围。
-
-## 5. 通用数据处理
-
-```text
-在 sandbox 中运行数据处理命令，读取 /workspace/input.csv，输出 /workspace/output.csv，并在 stdout 末尾打印包含 input_rows、output_rows、output_file 的结构化 JSON。
-```
-
-说明：
-
-- 推荐脚本最终打印：`{"status":"ok","input_rows":10000,"output_rows":9876,"output_file":"/workspace/output.csv"}`
-- skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, input_rows=10000, output_rows=9876, output_file=/workspace/output.csv`。
-
-## 6. 模型推理（Qwen / LLM / 视觉等）
-
-用户请求示例：
-
-```text
-在 GPU sandbox 中用 ModelScope 上的 Qwen/Qwen2.5-0.5B-Instruct 运行一次推理，输入 "100+10"，返回模型的输出结果及 CUDA 可用性摘要。
-```
-
-说明：
-
-- 请求里不要贴完整 Python 代码，也不要指定宿主文件路径（如 `@ROOT/inference.py`、本地绝对路径等），更不要要求脚本输出 `FINAL_ANSWER:` 标记行。脚本内容、模型下载、执行路径都由 skill 内部通过 `delta-cli sandbox write` 写入 sandbox 后运行。
-- 推荐让脚本在 `stdout` 末尾打印一行结构化 JSON，例如：
-  ```json
-  {"status":"ok","cuda_available":true,"device":"cuda","model":"Qwen/Qwen2.5-0.5B-Instruct","input":"100+10","generated_text":"110"}
-  ```
-- skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, cuda_available=True, generated_text=110, ...`。
-
-## 注意事项
-
-- 尽量用自然语言描述任务，完整代码由 skill 内部处理。
-- 只有在 skill 会真实创建文件时，才在请求中显式写出 `*.py` / `*.json` / `*.csv` 等扩展名。
-- 不要使用 `脚本需输出...` 这类把代码片段直接跟在承诺动词后的句式。
-- **任务完成的标准是执行结果，不是脚本文件存在**。Planner 和 skill 都要以本地 `result.json` 的生成作为完成标志；`required_outputs` 必须声明 `.json`，不要只声明 `{"kind": "file"}`。
-- **`skill_request` 里不要出现完整代码块或宿主文件路径概念**（如 `@ROOT/...`、`/Users/...`）。脚本应通过 `delta-cli sandbox write` 进入 sandbox 内部路径 `/workspace/...`。
-
-## 本地 `result.json` 的内容约定
-
-- **默认路径**：`run` / `run-bg --wait` 返回 JSON 的 `data.result_summary` 字段已含 CLI 提取结果。写本地 `result.json` 时直接复用 `data.result_summary` 即可，无需再走 `sandbox read` 解析 `log_file`。
-- **fallback 路径**（用 `--no-summary` 时或 `summary` 为 null）：保留 `delta-cli sandbox read <id> --path <log_file>` + Python 解析的旧路。
-- 本地 `result.json` 是一份**精简摘要**，用于 host deliverable 校验，不是完整日志存档。
-- 必须包含 `result_summary` 字段，内容与最终 `RESULT:` 行一致，方便 Runner 直接读取结论。
-- 只写入关键字段（`exit_code`、`finished`、`summary`、`result_summary`、`error`）。**不要**额外添加 `final_answer` 等字段。
-- 不要把完整原始 `stdout` 塞进 `result.json`，否则 host 的 `read_file` 工具预览时会截断，Runner 可能误以为文件被截断。
-- 完整原始输出保留在 sandbox 的 `log_file` 中，需要时再 `sandbox read`。
+# 标准任务请求模式
+
+本文件提供 `delta-sandbox` 处理常见任务时的推荐请求写法。这些示例是语言无关的模板，实际代码由 skill 在 sandbox 内部生成或写入。
+
+## Planner 调用本 skill 时的 required_outputs
+
+所有直接调用 `delta-sandbox` 的 plan step 都应该声明会落盘一个 `.json` 文件。这样 skill 运行命令后把 sandbox `log_file` 写入本地 `result.json` 时，host 可以正确通过 Phase-10B deliverable 校验。
+
+```yaml
+required_outputs:
+  - kind: file
+    extensions: [".json"]
+```
+
+> 说明：这是声明 skill 会创建 `.json` 结果文件，不是要求用户请求中出现 `.json`。用户请求仍按下面的模板使用中性动词。
+
+## 通用脚本输出模板
+
+为了让 skill 用同一套流程生成 `RESULT:` 并避免大模型去摘要长日志，推荐任何 sandbox 脚本在**执行结束时**打印一行结构化 JSON：
+
+```json
+{"status":"ok","key_metric_1":"value_1","key_metric_2":123}
+```
+
+> `sandbox run` / `run-bg --wait` 默认带 `--summary`，CLI 会自动 reverse-scan stdout 末尾的 JSON 并填入响应 `data.result_summary` 字段。脚本作者只需保证 stdout 最后一行是合法 JSON，skill 端无需再做提取。
+
+SKILL 会把它提取为 `result.json` 的 `summary`，并生成 `result_summary` 与最终 `RESULT:` 行。
+
+**不要**再输出 `FINAL_ANSWER: ...` 这样的标记行，也不要在 JSON 里使用 `final_answer` 字段。summary 里的语义字段（如 `output`、`result`、`generated_text`、`final_accuracy`）已经足够表达结果。
+
+不同任务的关键字段示例：
+
+- **CUDA 检查**：`status`, `torch_version`, `cuda_available`, `device_name`
+- **训练任务**：`status`, `epochs`, `final_loss`, `final_accuracy`, `model_file`
+- **推理任务**：`status`, `input_samples`, `output_file`, `avg_latency_ms`
+- **数据处理**：`status`, `input_rows`, `output_rows`, `output_file`
+- **编译/构建**：`status`, `build_time_s`, `output_binary`, `tests_passed`
+
+## 1. GPU / CUDA 可用性检查
+
+用户请求示例：
+
+```text
+在 GPU sandbox 中运行标准 PyTorch CUDA 自检脚本，返回 exit_code、torch 版本、CUDA 是否可用、CUDA/cuDNN 版本、GPU 名称与显存信息。
+```
+
+说明：
+
+- 不要在请求里出现 `torch.cuda.is_available()` 等完整代码 token，避免被 host 误判为 `.cuda` 文件承诺。对应的 plan step 仍按上面模板声明 `.json` 输出。
+- 推荐让脚本在 `stdout` 末尾输出一行结构化 JSON，例如：
+  ```json
+  {"torch_version":"2.7.0+cu128","cuda_available":true,"device_count":1,
+   "device_name":"NVIDIA GeForce RTX 3090","tensor_op":"[101.0]",
+   "memory_before_mb":{"allocated":0,"reserved":0,"max_allocated":0},
+   "memory_after_mb":{"allocated":0.0005,"reserved":2.0,"max_allocated":0.001}}
+  ```
+- skill 会从 `log_file` 提取这个 JSON 作为本地 `result.json` 的 `summary`，最终只输出一行 `RESULT: ...`。
+- 完整 `nvidia-smi` 原始输出保留在 sandbox 的 `log_file` 中。
+
+## 2. 运行用户已有的脚本
+
+```text
+在 sandbox <sandbox_id> 中运行 /workspace/train.py，参数为 --epochs 10 --batch-size 32。
+```
+
+说明：文件已存在，用中性动词 `运行`，不使用 `创建` 等承诺动词。
+
+## 3. 安装依赖并执行命令
+
+```text
+在 sandbox 中运行 pip install -r /workspace/requirements.txt，然后运行 python /workspace/app.py。
+```
+
+说明：依赖安装和命令执行都没有落盘新文件，使用中性动词描述。
+
+## 4. 训练并将指标落盘
+
+```text
+在 GPU sandbox 中运行训练脚本（例如基于 PyTorch 的 MNIST 训练），训练完成后在 stdout 末尾打印包含 epochs、final_loss、final_accuracy、model_file 的结构化 JSON。
+```
+
+说明：
+
+- 训练日志可能很长，不要让 skill 去读整段日志再摘要；让脚本自己输出关键指标。
+- 推荐脚本最终打印：`{"status":"ok","epochs":10,"final_loss":0.023,"final_accuracy":0.992,"model_file":"/workspace/model.pt"}`
+- skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, epochs=10, ...`。
+- 如需保存完整模型文件，可再用 `sandbox read` 或 `sandbox upload` 处理，不属于 `result.json` 的摘要范围。
+
+## 5. 通用数据处理
+
+```text
+在 sandbox 中运行数据处理命令，读取 /workspace/input.csv，输出 /workspace/output.csv，并在 stdout 末尾打印包含 input_rows、output_rows、output_file 的结构化 JSON。
+```
+
+说明：
+
+- 推荐脚本最终打印：`{"status":"ok","input_rows":10000,"output_rows":9876,"output_file":"/workspace/output.csv"}`
+- skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, input_rows=10000, output_rows=9876, output_file=/workspace/output.csv`。
+
+## 6. 模型推理（Qwen / LLM / 视觉等）
+
+用户请求示例：
+
+```text
+在 GPU sandbox 中用 ModelScope 上的 Qwen/Qwen2.5-0.5B-Instruct 运行一次推理，输入 "100+10"，返回模型的输出结果及 CUDA 可用性摘要。
+```
+
+说明：
+
+- 请求里不要贴完整 Python 代码，也不要指定宿主文件路径（如 `@ROOT/inference.py`、本地绝对路径等），更不要要求脚本输出 `FINAL_ANSWER:` 标记行。脚本内容、模型下载、执行路径都由 skill 内部通过 `delta-cli sandbox write` 写入 sandbox 后运行。
+- 推荐让脚本在 `stdout` 末尾打印一行结构化 JSON，例如：
+  ```json
+  {"status":"ok","cuda_available":true,"device":"cuda","model":"Qwen/Qwen2.5-0.5B-Instruct","input":"100+10","generated_text":"110"}
+  ```
+- skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, cuda_available=True, generated_text=110, ...`。
+
+## 注意事项
+
+- 尽量用自然语言描述任务，完整代码由 skill 内部处理。
+- 只有在 skill 会真实创建文件时，才在请求中显式写出 `*.py` / `*.json` / `*.csv` 等扩展名。
+- 不要使用 `脚本需输出...` 这类把代码片段直接跟在承诺动词后的句式。
+- **任务完成的标准是执行结果，不是脚本文件存在**。Planner 和 skill 都要以本地 `result.json` 的生成作为完成标志；`required_outputs` 必须声明 `.json`，不要只声明 `{"kind": "file"}`。
+- **`skill_request` 里不要出现完整代码块或宿主文件路径概念**（如 `@ROOT/...`、`/Users/...`）。脚本应通过 `delta-cli sandbox write` 进入 sandbox 内部路径 `/workspace/...`。
+
+## 本地 `result.json` 的内容约定
+
+- **默认路径**：`run` / `run-bg --wait` 返回 JSON 的 `data.result_summary` 字段已含 CLI 提取结果。写本地 `result.json` 时直接复用 `data.result_summary` 即可，无需再走 `sandbox read` 解析 `log_file`。
+- **fallback 路径**（用 `--no-summary` 时或 `summary` 为 null）：保留 `delta-cli sandbox read <id> --path <log_file>` + Python 解析的旧路。
+- 本地 `result.json` 是一份**精简摘要**，用于 host deliverable 校验，不是完整日志存档。
+- 必须包含 `result_summary` 字段，内容与最终 `RESULT:` 行一致，方便 Runner 直接读取结论。
+- 只写入关键字段（`exit_code`、`finished`、`summary`、`result_summary`、`error`）。**不要**额外添加 `final_answer` 等字段。
+- 不要把完整原始 `stdout` 塞进 `result.json`，否则 host 的 `read_file` 工具预览时会截断，Runner 可能误以为文件被截断。
+- 完整原始输出保留在 sandbox 的 `log_file` 中，需要时再 `sandbox read`。