@delta-infra/cli 1.0.0

package/README.md

@@ -0,0 +1,211 @@
+# delta-cli
+
+Delta Infra 的命令行工具。
+
+## 安装
+
+### 方式一：直接下载 Binary（推荐）
+
+从 [GitHub Releases](https://github.com/yzailab/delta-infra-cli/releases) 下载对应平台的压缩包：
+
+```bash
+# macOS (Apple Silicon)
+curl -L https://github.com/yzailab/delta-infra-cli/releases/download/v1.0.0/delta-cli-darwin-arm64.tar.gz | tar -xz
+sudo mv delta-cli-darwin-arm64/delta-cli /usr/local/bin/
+
+# Linux (AMD64)
+curl -L https://github.com/yzailab/delta-infra-cli/releases/download/v1.0.0/delta-cli-linux-amd64.tar.gz | tar -xz
+sudo mv delta-cli-linux-amd64/delta-cli /usr/local/bin/
+
+# Windows (AMD64)
+# 下载 delta-cli-windows-amd64.zip 并解压
+```
+
+### 方式二：npm
+
+```bash
+npm install -g @delta-infra/cli
+```
+
+安装时会自动从 GitHub Release 下载当前平台的二进制文件并解压到本地。
+
+## 快速开始
+
+### 1. 初始化配置
+
+```bash
+delta-cli config init
+```
+
+配置文件保存在 `~/.delta-infra/config.json`（权限 0600），通过 `delta-cli config set base_url <url>` 配置服务端地址。也可通过环境变量覆盖：
+
+```bash
+export DELTA_INFRA_BASE_URL=<url>
+```
+
+### 2. 认证
+
+支持 API Key 或 Bearer Token：
+
+```bash
+# API Key
+delta-cli auth login --api-key <your-api-key>
+
+# Bearer Token
+delta-cli auth login --token <your-token>
+
+# 查看认证状态
+delta-cli auth status
+```
+
+### 3. Sandbox 生命周期
+
+```bash
+# 创建带 GPU 的 sandbox
+delta-cli sandbox create \
+  --image deltarouter/pytorch-cuda13:latest \
+  --cpu 4 --memory 16Gi --gpu 1
+
+# 运行训练命令
+delta-cli sandbox run <sandbox_id> \
+  --command "python /workspace/train.py" \
+  --timeout 3600
+
+# 读取结果文件
+delta-cli sandbox read <sandbox_id> --path /workspace/result.json
+
+# 销毁 sandbox
+delta-cli sandbox kill <sandbox_id>
+```
+
+## 命令列表
+
+### 全局命令
+
+| 命令 | 说明 |
+|------|------|
+| `delta-cli config init` | 初始化配置文件 |
+| `delta-cli config show` | 查看当前配置（敏感字段已脱敏） |
+| `delta-cli config set <key> <value>` | 修改配置项 |
+| `delta-cli auth login` | 交互式登录 |
+| `delta-cli auth login --api-key <key>` | API Key 认证 |
+| `delta-cli auth login --token <token>` | Token 认证 |
+| `delta-cli auth status` | 查看认证状态 |
+| `delta-cli update check` | 检查更新 |
+| `delta-cli update` | 安装最新版本 |
+| `delta-cli --version` | 显示版本 |
+
+### Sandbox 命令
+
+| 命令 | 说明 |
+|------|------|
+| `delta-cli sandbox create --image <img>` | 创建 sandbox 容器 |
+| `delta-cli sandbox connect <id>` | 连接 sandbox |
+| `delta-cli sandbox status <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 read <id> --path <path>` | 读取容器内文件 |
+| `delta-cli sandbox write <id> --path <path> --data "..."` | 写入文件 |
+| `delta-cli sandbox finish <id> --results '{...}'` | 标记完成并返回结果 |
+| `delta-cli sandbox kill <id>` | 销毁 sandbox |
+
+## 输出格式
+
+所有命令返回统一的 JSON envelope：
+
+```json
+// 成功
+{"ok":true,"data":{"id":"sb-xxx","status":"running"}}
+
+// 错误
+{"ok":false,"error":{"type":"auth","message":"not authenticated","hint":"run 'delta-cli auth login'"}}
+```
+
+错误类型及退出码：
+
+| Type | Exit Code | 场景 |
+|------|-----------|------|
+| validation | 2 | 参数错误 |
+| auth | 3 | 未认证 |
+| permission | 4 | 权限不足 |
+| not_found | 5 | 资源不存在 |
+| network | 6 | 网络错误 |
+| api | 7 | 服务端错误 |
+| internal | 10 | 客户端内部错误 |
+
+## AI Agent Skills
+
+delta-cli 内置 AI Agent 操作手册（Skills），帮助 Claude Code 等 AI 助手正确使用 CLI：
+
+```bash
+# 安装共享技能（认证、配置、通用规则）
+npx skills add delta-infra/delta-infra-cli -s delta-shared
+
+# 安装 sandbox 操作技能
+npx skills add delta-infra/delta-infra-cli -s delta-sandbox
+```
+
+Skill 文件位于 `skills/` 目录：
+- `delta-shared/` — 全局通用规则（认证、配置、错误处理）
+- `delta-sandbox/` — Sandbox 操作指南（生命周期、命令路由）
+
+## 开发
+
+```bash
+# 本地构建
+make build
+
+# 运行测试
+make test
+
+# 代码检查
+make lint
+
+# 跨平台发布构建（生成压缩包）
+make release
+
+# 安装到 GOPATH/bin
+make install
+```
+
+### 日常开发流程
+
+修改 `skills/` 或编译 `delta-cli` 后，需要同步到 Memento-S 项目才能生效：
+
+```bash
+# 1. 复制 skill 文档到 Memento-S（让 LLM 读到最新的约束规则）
+cp skills/delta-sandbox/SKILL.md skills/delta-sandbox/references/*.md \
+   <memento-s>/builtin/skills/delta-sandbox/
+cp skills/delta-shared/SKILL.md \
+   <memento-s>/builtin/skills/delta-shared/
+
+# 2. 用 Docker 编译 Windows 版本（本地无 Go toolchain 时）
+docker run --rm -v "$(pwd):/src" -w /src \
+  -e GOPROXY=https://goproxy.cn,direct \
+  golang:1.23 go build -buildvcs=false \
+    -ldflags "-X $(MODULE)/internal/build.Version=$(shell git describe --tags --always --dirty 2>/dev/null || echo dev)" \
+    -o bin/delta-cli-windows-amd64.exe ./cmd/delta-cli
+
+# 3. 将 delta-cli 放到 Memento-S 的 node_modules/.bin（替换旧版本）
+cp bin/delta-cli-windows-amd64.exe \
+   <memento-s>/electron_rebuild/node_modules/.bin/delta-cli
+
+# 4. 重启 Memento-S sidecar 使新 binary 生效
+#   在 Electron 界面中重新加载，或手动重启 sidecar 进程
+```
+
+> **注意**：`delta-cli` 替换后，Memento-S 的 `delta-sandbox` 技能默认使用内嵌 Bearer Token，无需再手动执行 `auth login`。
+
+## 技术栈
+
+- **语言**: Go 1.23+
+- **CLI 框架**: [Cobra](https://github.com/spf13/cobra)
+- **配置**: JSON 文件（`~/.delta-infra/config.json`，权限 0600）
+- **输出**: JSON envelope（AI-agent 友好，可脚本化）
+- **发布**: GitHub Release（tar.gz/zip） + npm wrapper
+- **架构**: 扁平静态命令树，Factory 依赖注入，惰性初始化
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@delta-infra/cli",
+  "version": "1.0.0",
+  "description": "Delta Sandbox CLI",
+  "bin": {
+    "delta-cli": "scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "files": [
+    "scripts/",
+    "skills/"
+  ],
+  "keywords": ["delta", "sandbox", "cli", "gpu", "compute"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yzailab/delta-infra-cli.git"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+
+const BINARY_NAME = 'delta-cli';
+const VERSION = require('../package.json').version;
+const RELEASE_BASE_URL = 'https://github.com/yzailab/delta-infra-cli/releases/download';
+
+const platformMap = {
+  darwin: 'darwin',
+  linux: 'linux',
+  win32: 'windows',
+};
+
+const archMap = {
+  x64: 'amd64',
+  arm64: 'arm64',
+};
+
+function resolveUrl(base, location) {
+  if (!location) return base;
+  if (location.startsWith('http://') || location.startsWith('https://')) {
+    return location;
+  }
+  const baseUrl = new URL(base);
+  return new URL(location, baseUrl).href;
+}
+
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+    const hash = crypto.createHash('sha256');
+
+    const cleanup = () => {
+      try { fs.unlinkSync(dest); } catch {}
+    };
+
+    https.get(url, (response) => {
+      if (response.statusCode >= 301 && response.statusCode <= 308 && response.headers.location) {
+        file.destroy();
+        cleanup();
+        download(resolveUrl(url, response.headers.location), dest).then(resolve).catch(reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        file.destroy();
+        cleanup();
+        reject(new Error(`Download failed: ${response.statusCode}`));
+        return;
+      }
+      response.pipe(file);
+      response.on('data', (chunk) => hash.update(chunk));
+      file.on('finish', () => {
+        file.close(() => resolve(hash.digest('hex')));
+      });
+    }).on('error', (err) => {
+      file.destroy();
+      cleanup();
+      reject(err);
+    });
+  });
+}
+
+function extract(archivePath, destDir, platform) {
+  if (platform === 'windows') {
+    execSync(`unzip -o "${archivePath}" -d "${destDir}"`, { stdio: 'inherit' });
+  } else {
+    execSync(`tar -xzf "${archivePath}" -C "${destDir}"`, { stdio: 'inherit' });
+  }
+}
+
+async function main() {
+  const platform = platformMap[process.platform];
+  const arch = archMap[process.arch];
+  if (!platform || !arch) {
+    console.error(`Unsupported platform: ${process.platform} ${process.arch}`);
+    process.exit(1);
+  }
+
+  const isWin = platform === 'windows';
+  const archiveExt = isWin ? '.zip' : '.tar.gz';
+  const binaryExt = isWin ? '.exe' : '';
+  const assetName = `${BINARY_NAME}-${platform}-${arch}${archiveExt}`;
+  const binDir = path.join(__dirname, '..', 'bin');
+  const archivePath = path.join(binDir, assetName);
+  const binaryPath = path.join(binDir, `${BINARY_NAME}${binaryExt}`);
+
+  fs.mkdirSync(binDir, { recursive: true });
+
+  const url = `${RELEASE_BASE_URL}/v${VERSION}/${assetName}`;
+  console.log(`Downloading ${assetName} from GitHub...`);
+
+  try {
+    const checksum = await download(url, archivePath);
+    console.log(`Downloaded archive, SHA256: ${checksum}`);
+    console.log(`Extracting to ${binDir}...`);
+    extract(archivePath, binDir, platform);
+    fs.chmodSync(binaryPath, 0o755);
+    fs.unlinkSync(archivePath);
+    console.log(`Installed to ${binaryPath}`);
+  } catch (err) {
+    console.error('Install failed:', err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/run.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+const path = require('path');
+const { spawn } = require('child_process');
+
+const platform = process.platform === 'win32' ? 'windows' : process.platform;
+const ext = platform === 'windows' ? '.exe' : '';
+const binary = path.join(__dirname, '..', 'bin', `delta-cli${ext}`);
+
+const child = spawn(binary, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true,
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start delta-cli:', err.message);
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});

package/skills/delta-sandbox/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: delta-sandbox
+version: 1.0.0
+description: "通过 Delta Sandbox HTTP API 运行 GPU/CPU 计算任务。适用于训练、微调、CUDA/PyTorch 推理等场景。认证/配置/权限错误转 delta-shared。"
+metadata:
+  requires:
+    bins: ["delta-cli"]
+  cliHelp: "delta-cli sandbox --help"
+---
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md)，其中包含认证、配置和通用错误处理**
+
+# delta-sandbox
+
+## 何时使用
+
+- 用户提到 sandbox、容器、GPU、CUDA、训练、推理、计算任务。
+- 用户需要创建/管理 sandbox 实例、在 sandbox 中运行命令、读写文件。
+- **不要**用于：认证、配置初始化、权限恢复、更新检查 → 转 `delta-shared`。
+
+## 使用边界
+
+- 所有 sandbox 操作使用 `delta-cli sandbox <subcommand>`。
+- delta-cli 不内嵌默认凭证，运行前必须按 `delta-shared` 完成认证配置。
+- sandbox_id 必须来自真实返回，不要凭用户口述猜测。
+
+## 强制规则（违规则任务视为失败）
+
+1. **必须使用 delta-cli**：所有 sandbox 操作必须通过 `delta-cli sandbox <subcommand>` 执行。**禁止**用 Python（urllib/httpx/requests）或任何 SDK 直接调用 HTTP API。delta-cli 提供类型化错误输出（`error.type`），是 AI agent 正确解析错误的唯一途径。
+2. **必须销毁**：每次 `sandbox create` 成功后，在当前任务的最终 `step_finish` 之前 **必须** 执行 `sandbox kill <id>` 或 `sandbox finish <id>` 销毁 sandbox。未销毁等价于任务失败。
+3. **异常时也必须销毁**：即使 sandbox 内命令失败、超时或报错，仍然 **必须** 执行 `sandbox kill <id>`。异常不是跳过销毁的理由。
+4. **不得依赖外部清理**：server 端 **没有** sandbox 的自动过期或 TTL 机制。不 kill → sandbox 永久占用 GPU 资源。
+5. **一条命令内完成**：从 `create` 到 `kill` 的完整生命周期必须在同一次执行中完成。不允许跨任务保留 sandbox。
+6. **禁止重复创建**：同一次任务中只允许存在一个活跃 sandbox。若命令失败需要重试，优先复用已创建的 `sandbox_id`；若确实需要重新创建，必须先 `sandbox kill <旧_sandbox_id>`，确认旧实例销毁后再执行新的 `sandbox create`。server 端没有 list 接口，AI agent 应通过任务上下文跟踪当前 `sandbox_id`，而不是反复 create。
+
+## 快速路由
+
+| 用户目标 | 命令 |
+|---------|------|
+| 查看可用镜像 | `sandbox images` |
+| 创建 sandbox | `sandbox create --image <image>` |
+| 连接 sandbox | `sandbox connect <id>` |
+| 查看状态 | `sandbox status <id>` |
+| 同步运行命令 | `sandbox run <id> --command "..."` |
+| 后台运行命令 | `sandbox run-bg <id> --command "..."` |
+| 查看日志 | `sandbox logs <id> --execution-id <exec_id>` |
+| 读取文件 | `sandbox read <id> --path <path>` |
+| 写入文件 | `sandbox write <id> --path <path> --data "..."` |
+| 完成 sandbox | `sandbox finish <id> --results '{...}'` |
+| 销毁 sandbox | `sandbox kill <id>` |
+
+## 完整生命周期
+
+1. **查看可用镜像**：`delta-cli sandbox images` — 查询服务端支持的镜像列表（含标签、最低资源要求、支持 provider），根据用户需求匹配镜像
+2. **创建**：`delta-cli sandbox create --image <img> --cpu 4 --memory 16Gi --gpu 1`（创建后 sandbox 立即可用，无需额外连接）。**同一次任务若已有 `sandbox_id`，禁止再次 create，必须优先复用。**
+3. **写入代码**：`delta-cli sandbox write <id> --path /workspace/train.py --data "..."`
+4. **运行**：`delta-cli sandbox run <id> --command "python /workspace/train.py" --timeout 3600`
+5. **读取结果**：`delta-cli sandbox read <id> --path /workspace/result.json`
+6. **销毁**：`delta-cli sandbox kill <id>`（如需保存结果，用 `sandbox finish --results '{...}'` 替代 kill，finish 会自动销毁 sandbox）
+
+详细步骤见 [lifecycle.md](references/lifecycle.md)。
+
+## 常见恢复
+
+| 错误 / 现象 | 恢复动作 |
+|-------------|----------|
+| `error.type: not_found` | 检查 sandbox_id 是否正确，是否已被 kill |
+| `error.type: network` | 检查 base_url 和网络连通性 |
+| `error.type: validation` | 检查参数格式和必填 flag |
+| `error.type: auth / permission` | 参考 delta-shared 的权限不足处理 |
+| `error.type: api`（5xx） | 服务端错误，检查 API 服务状态 |
+| 命令执行失败（exit_code ≠ 0） | 查看 `run` 返回的 stdout/stderr |
+| 命令超时 | 增加 `--timeout` 或使用 `run-bg` |

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

@@ -0,0 +1,17 @@
+> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
+
+# 命令速查表
+
+| 命令 | 说明 |
+|------|------|
+| `sandbox images` | 查看可用镜像列表 |
+| `sandbox create` | 创建 sandbox |
+| `sandbox connect` | 连接 sandbox |
+| `sandbox kill` | 直接销毁 sandbox，不保存结果（有结果要保存时用 finish 替代） |
+| `sandbox finish` | 保存结果后自动销毁 sandbox（二选一：finish 或 kill，不要同时调用） |
+| `sandbox status` | 查看状态 |
+| `sandbox run` | 同步运行命令 |
+| `sandbox run-bg` | 后台运行命令 |
+| `sandbox logs` | 获取日志 |
+| `sandbox read` | 读取文件 |
+| `sandbox write` | 写入文件 |

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

@@ -0,0 +1,21 @@
+> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
+
+# Delta Sandbox 生命周期
+
+## 完整流程
+
+1. **查看可用镜像** `delta-cli sandbox images` — 查询服务端支持的镜像列表，根据用户的 GPU/CPU 需求和标签匹配镜像
+2. **创建** `delta-cli sandbox create --image <image> ...`（创建后立即可用，无需连接）
+3. **写入代码/数据** `delta-cli sandbox write <id> --path /workspace/train.py --data "..."`
+4. **运行命令** `delta-cli sandbox run <id> --command "python /workspace/train.py"`
+5. **读取结果** `delta-cli sandbox read <id> --path /workspace/result.json`
+6. **销毁** `delta-cli sandbox kill <id>`（如需保存结果用 finish，finish 会自动销毁）
+
+## 后台任务
+
+对于长时间运行的训练：
+
+```bash
+delta-cli sandbox run-bg <id> --command "python train.py" --timeout 3600
+delta-cli sandbox logs <id> --execution-id <exec_id>
+```

package/skills/delta-shared/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: delta-shared
+version: 1.0.0
+description: "delta-cli 全局共享规则。使用于首次配置、认证登录、权限不足恢复、配置查看、遇到 JSON 输出中的 _notice 或通用错误处理时。"
+---
+
+# delta-cli 共享规则
+
+本技能指导你如何通过 delta-cli 操作 Delta Sandbox 及相关资源，以及所有命令域通用的注意事项。
+
+## 获取服务端地址（必须优先执行）
+
+所有操作的前提是知道 delta-sandbox-server 的地址。按以下步骤获取：
+
+1. 执行 `echo $DELTA_INFRA_BASE_URL` 检查环境变量是否已设置
+2. 如果输出非空，说明已配置，直接使用，无需额外操作
+3. 如果为空，**向用户询问真实地址**，然后运行 `delta-cli config set base_url <url>` 保存
+
+**不要猜测或虚构地址。不确认地址就执行任何操作会导致 network 错误。**
+
+## 配置初始化
+
+首次使用需运行 `delta-cli config init` 完成配置：
+
+```bash
+delta-cli config init
+```
+
+这会创建 `~/.delta-infra/config.json`，需按实际部署设置 base_url（`delta-cli config set base_url <url>`），也可通过环境变量 `DELTA_INFRA_BASE_URL` 覆盖。
+
+## 配置管理
+
+```bash
+delta-cli config show
+delta-cli config set base_url <url>
+delta-cli config set api_key <key>
+delta-cli config set token <token>
+delta-cli config remove api_key
+delta-cli config remove token
+```
+
+## 环境变量覆盖
+
+以下环境变量优先级高于配置文件：
+
+| 变量 | 说明 |
+|------|------|
+| `DELTA_INFRA_BASE_URL` | 覆盖 base_url |
+| `DELTA_SANDBOX_API_KEY` | 覆盖 api_key |
+| `DELTA_SANDBOX_TOKEN` | 覆盖 token |
+
+## 认证
+
+delta-cli **不再内嵌默认凭证**，使用前必须配置认证。
+
+支持两种认证方式，优先级从高到低：
+
+| 方式 | 命令 / 来源 | 适用场景 |
+|------|------------|----------|
+| API Key | `delta-cli auth login --api-key <key>` 或环境变量 `DELTA_SANDBOX_API_KEY` | 推荐 |
+| Bearer Token | `delta-cli auth login --token <token>` 或环境变量 `DELTA_SANDBOX_TOKEN` | 使用已有 token |
+
+### 默认认证说明
+
+- binary 中没有默认 token，第一次使用**必须**执行 `delta-cli auth login` 或设置环境变量。
+- 如需更换账号，重新执行 `delta-cli auth login --token <token>` 或 `delta-cli auth login --api-key <key>`。
+- 未配置时 `auth status` 会显示 `method: none`。
+
+### 查看认证状态
+
+```bash
+delta-cli auth status
+```
+
+### 权限不足处理
+
+遇到认证/权限错误时（`error.type: auth` 或 `permission`）：
+
+1. 先执行 `delta-cli auth status` 确认当前认证状态
+2. 如需更换认证，执行 `delta-cli auth login --token <token>` 或 `delta-cli auth login --api-key <key>`
+3. 如已认证但仍报错，检查 base_url 是否正确
+
+**禁止**：将 API Key 或 Token 输出到终端明文展示给用户。
+
+## 安全规则
+
+- **禁止输出密钥**：`api_key`、`token` 不得在日志、消息或终端中明文展示。
+- **写入/删除操作前必须确认用户意图**：`sandbox kill`、`sandbox finish`、`sandbox write` 等操作前需明确告知用户影响。
+- **配置文件权限**：`~/.delta-infra/config.json` 权限为 `0600`，严禁手动放宽。
+- **sandbox 必须销毁**：调用 `sandbox create` 后，当前任务结束前必须调用 `sandbox kill`。server 端无自动清理，不销毁 = 永久占用 GPU。即使遇到错误也不得跳过销毁。
+
+## JSON 输出约定
+
+所有命令输出遵循统一 JSON envelope：
+
+```json
+{"ok":true,"data":{...}}
+{"ok":false,"error":{"type":"auth","message":"...","hint":"..."}}
+```
+
+AI Agent 解析规则：
+- 始终检查 `ok` 字段，不要仅依赖 exit code
+- `error.type` 是稳定分支字段：`auth`, `permission`, `not_found`, `validation`, `network`, `api`, `internal`
+- `error.hint` 是可读修复建议，可展示给用户
+
+## 退出码约定
+
+| Type | Exit Code | 场景 |
+|------|-----------|------|
+| validation | 2 | flag 错误、参数缺失 |
+| auth | 3 | 未认证或认证失败 |
+| permission | 4 | 权限不足 |
+| not_found | 5 | sandbox/file 不存在 |
+| network | 6 | DNS、超时、连接失败 |
+| api | 7 | 服务端非 2xx 错误 |
+| internal | 10 | 客户端内部错误 |
+
+## 更新检查
+
+`delta-cli update check` 检查最新版本。
+
+**当你在 JSON 中看到 `_notice.update` 时**，完成用户当前请求后，主动提议更新：
+
+```bash
+delta-cli update
+```
+
+## 常见恢复
+
+| 错误 / 现象 | 恢复动作 |
+|-------------|----------|
+| `error.type: auth` | 先执行 `auth status` 确认；如无认证或需更换，执行 `auth login --token <token>` |
+| `error.type: not_found` | 检查 sandbox_id 或 path 是否正确 |
+| `error.type: network` | 检查 base_url 和网络连通性 |
+| `error.type: validation` | 检查必填 flag 和参数格式 |
+| 配置文件解析失败 | 检查 `~/.delta-infra/config.json` 是否为有效 JSON |