Feat/sandbox

.vite-hooks/pre-commit

@@ -15,6 +15,8 @@ git add \
   skills/bailian-finetune/reference \
   skills/bailian-managed-agent/SKILL.md \
   skills/bailian-managed-agent/reference \
+  skills/bailian-sandbox/SKILL.md \
+  skills/bailian-sandbox/reference \
   skills/bailian-web-search/SKILL.md
 
 vp staged

AGENTS.md

@@ -36,7 +36,7 @@ packages/core/src/auth/            # apiKey / console credential 解析与落盘
 packages/core/src/client/          # HTTP client / endpoints / console gateway
 ```
 
-Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐 registry 中全部 `bailian-*`，含共享协议 `bailian-protocol`）。业务 skill（`bailian-cli` / `bailian-gen` / `bailian-finetune` / `bailian-managed-agent` / `bailian-web-search`）执行前读 `skills/bailian-protocol/`；不要依赖 frontmatter `companions`（安装器不强制）。`tools/generate-reference.ts` 从 **`packages/cli/src/commands.ts`** 按一级命令归属表分流写入各 `skills/<skill>/reference/`(纳入 git);`tools/sync-skill-metadata.ts` 从 `packages/cli/package.json` 同步各 `skills/*/SKILL.md` 的 `metadata.version`。两者由根脚本 `pnpm run sync:skill-assets` 和 `.vite-hooks/pre-commit` 执行。hub `bailian-cli` 的路由表不复述领域命令明细；SKILL 文案 / 安装约定 / hand-off 见 [docs/agents/skill-change.md](docs/agents/skill-change.md)。
+Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐 registry 中全部 `bailian-*`，含共享协议 `bailian-protocol`）。业务 skill（`bailian-cli` / `bailian-gen` / `bailian-finetune` / `bailian-managed-agent` / `bailian-sandbox` / `bailian-web-search`）执行前读 `skills/bailian-protocol/`；不要依赖 frontmatter `companions`（安装器不强制）。`tools/generate-reference.ts` 从 **`packages/cli/src/commands.ts`** 按一级命令归属表分流写入各 `skills/<skill>/reference/`(纳入 git);`tools/sync-skill-metadata.ts` 从 `packages/cli/package.json` 同步各 `skills/*/SKILL.md` 的 `metadata.version`。两者由根脚本 `pnpm run sync:skill-assets` 和 `.vite-hooks/pre-commit` 执行。hub `bailian-cli` 的路由表不复述领域命令明细；SKILL 文案 / 安装约定 / hand-off 见 [docs/agents/skill-change.md](docs/agents/skill-change.md)。
 
 约定:
 

CHANGELOG.md

@@ -6,6 +6,24 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 [中文版](CHANGELOG.zh.md) · [README](README.md) · [Contributing](CONTRIBUTING.md)
 
+## [1.24.0] - 2026-09-11
+
+### Added
+
+- Sandbox instance and template lifecycle commands, with automatic build polling and `--async` submission.
+- `bl sandbox official-images` and template `--image` presets for Code Interpreter, Browser, and All-in-One.
+- `bl sandbox file upload` uploads template mount files with `source=sandbox_template`; use the returned File ID in `mntConfig`.
+- Sandbox supports shared `--base-url`, environment and Profile configuration, with workspace-based endpoint fallback.
+- Dedicated `bailian-sandbox` Skill with command references and instance connection guidance.
+
+### Fixed
+
+- Preserve submitted `templateID` and `buildID` when template-build polling fails, so users can check the existing build before resubmitting.
+
+### Security
+
+- Sandbox REST calls use Bailian Bearer authentication without an E2B SDK or E2B API key. Connection credentials and dry-run environment values are redacted by default.
+
 ## [1.23.0] - 2026-09-10
 
 ### Added

CHANGELOG.zh.md

@@ -6,6 +6,24 @@
 
 [English](CHANGELOG.md) · [README](README.zh.md) · [参与贡献](CONTRIBUTING.zh.md)
 
+## [1.24.0] - 2026-09-11
+
+### 新增
+
+- Sandbox 实例与模版生命周期命令，支持自动轮询构建状态和 `--async` 异步提交。
+- `bl sandbox official-images` 与模版 `--image` 参数，内置代码解释器、浏览器和全能型镜像预设。
+- `bl sandbox file upload` 使用 `source=sandbox_template` 上传模版挂载文件，返回的 File ID 可用于 `mntConfig`。
+- Sandbox 复用 `--base-url`、环境变量和 Profile 配置，未配置时通过工作空间拼接接入地址。
+- 独立的 `bailian-sandbox` Skill，提供命令参考和实例连接指南。
+
+### 修复
+
+- 模版构建轮询失败时保留已提交的 `templateID` 和 `buildID`，便于先查询已有构建，避免重复提交。
+
+### 安全
+
+- Sandbox REST 调用使用百炼 Bearer 鉴权，不依赖 E2B SDK 或 E2B API Key；连接凭据和 dry-run 环境变量默认脱敏。
+
 ## [1.23.0] - 2026-09-10
 
 ### 新增

docs/agents/skill-change.md

@@ -56,6 +56,7 @@ bailian-gen      bailian-finetune  bailian-managed-agent   bailian-web-search
 ### C. 归属与生成
 
 - [ ] 新一级命令组归属领域时：改 `tools/generate-reference.ts` 的 `GROUP_OWNER_SKILL`，并更新**拥有方** skill 的路由表；hub 最多加一行 hand-off
+- [ ] 新增领域目录时：补齐 `SKILL.md`（含 `metadata.version`），同步 `packages/cli/package.json` 的 reference 格式化路径、`.vite-hooks/pre-commit` 的生成物暂存清单、`tools/release/check.mjs` 的生成物校验清单；同步 hub 与共享协议的领域路由
 - [ ] 跑 `pnpm run sync:skill-assets`（或 commit 走 pre-commit），提交生成的 `reference/` 与 version 同步结果
 - [ ] 高风险命令生成的 reference 必须包含 `Risk` / `Risk message` 和简短 Agent safety 提示；带 `--yes` 的示例必须标注只能在确认后执行，不要手改生成物
 - [ ] 默认模型若写在领域路由表（如 `bailian-gen`）：与命令 default / [model-add-remove.md](model-add-remove.md) 一并核对

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "CLI for Aliyun Model Studio (DashScope) AI Platform.",
   "keywords": [
     "agent",
@@ -41,7 +41,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "generate:reference": "tsx ../../tools/generate-reference.ts && sh -c 'cd ../.. && vp check --fix skills/bailian-cli/reference skills/bailian-gen/reference skills/bailian-finetune/reference skills/bailian-managed-agent/reference'",
+    "generate:reference": "tsx ../../tools/generate-reference.ts && sh -c 'cd ../.. && vp check --fix skills/bailian-cli/reference skills/bailian-gen/reference skills/bailian-finetune/reference skills/bailian-managed-agent/reference skills/bailian-sandbox/reference'",
     "sync:skill-version": "tsx ../../tools/sync-skill-metadata.ts",
     "build": "vp pack",
     "dev": "tsx src/main.ts",

packages/cli/src/commands.ts

@@ -211,6 +211,21 @@ import {
   managedAgentFileSearch,
   managedAgentFileDownload,
   managedAgentFileDelete,
+  sandboxCreate,
+  sandboxOfficialImages,
+  sandboxFileUpload,
+  sandboxList,
+  sandboxGet,
+  sandboxConnect,
+  sandboxPause,
+  sandboxResume,
+  sandboxDelete,
+  sandboxTemplateCreate,
+  sandboxTemplateList,
+  sandboxTemplateGet,
+  sandboxTemplateUpdate,
+  sandboxTemplateBuildStatus,
+  sandboxTemplateDelete,
 } from "bailian-cli-commands";
 
 // Full bailian-cli product: every command, exposed under the `bl` binary.
@@ -433,6 +448,21 @@ export const commands: Record<string, AnyCommand> = {
   "managed-agent file search": managedAgentFileSearch,
   "managed-agent file download": managedAgentFileDownload,
   "managed-agent file delete": managedAgentFileDelete,
+  "sandbox create": sandboxCreate,
+  "sandbox official-images": sandboxOfficialImages,
+  "sandbox file upload": sandboxFileUpload,
+  "sandbox list": sandboxList,
+  "sandbox get": sandboxGet,
+  "sandbox connect": sandboxConnect,
+  "sandbox pause": sandboxPause,
+  "sandbox resume": sandboxResume,
+  "sandbox delete": sandboxDelete,
+  "sandbox template create": sandboxTemplateCreate,
+  "sandbox template list": sandboxTemplateList,
+  "sandbox template get": sandboxTemplateGet,
+  "sandbox template update": sandboxTemplateUpdate,
+  "sandbox template build-status": sandboxTemplateBuildStatus,
+  "sandbox template delete": sandboxTemplateDelete,
 };
 
 /**

packages/cli/tests/skill-sandbox-reference.test.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateSkillDir } from "bailian-cli-core";
+import { expect, test } from "vite-plus/test";
+import { parse } from "yaml";
+import { commands } from "../src/commands.ts";
+
+const repositoryRoot = join(dirname(fileURLToPath(import.meta.url)), "../../..");
+const sandboxSkillDirectory = join(repositoryRoot, "skills/bailian-sandbox");
+
+test("Sandbox is a valid standalone skill aligned with the CLI version", () => {
+  const metadata = validateSkillDir(sandboxSkillDirectory, "bailian-sandbox");
+  expect(metadata.name).toBe("bailian-sandbox");
+
+  const skillMarkdown = readFileSync(join(sandboxSkillDirectory, "SKILL.md"), "utf8");
+  const frontmatter = parse(skillMarkdown.split(/^---\s*$/m)[1]) as {
+    metadata: { version: string };
+  };
+  const cliPackage = JSON.parse(
+    readFileSync(join(repositoryRoot, "packages/cli/package.json"), "utf8"),
+  ) as { version: string };
+  expect(frontmatter.metadata.version).toBe(cliPackage.version);
+
+  for (const link of skillMarkdown.matchAll(/\]\(([^)]+)\)/g)) {
+    expect(existsSync(join(sandboxSkillDirectory, link[1]))).toBe(true);
+  }
+});
+
+test("Sandbox reference contains every registered Sandbox command only in its owning skill", () => {
+  const expectedCommands = Object.keys(commands)
+    .filter((commandPath) => commandPath.startsWith("sandbox "))
+    .map((commandPath) => `bl ${commandPath}`)
+    .sort();
+  expect(expectedCommands.length).toBeGreaterThan(0);
+
+  const reference = readFileSync(join(sandboxSkillDirectory, "reference/sandbox.md"), "utf8");
+  const documentedCommands = [...reference.matchAll(/^### `([^`]+)`/gm)]
+    .map((match) => match[1])
+    .sort();
+  expect(documentedCommands).toEqual(expectedCommands);
+
+  const index = readFileSync(join(sandboxSkillDirectory, "reference/index.md"), "utf8");
+  for (const commandPath of expectedCommands) {
+    expect(index).toContain(`\`${commandPath}\``);
+  }
+  expect(existsSync(join(repositoryRoot, "skills/bailian-cli/reference/sandbox.md"))).toBe(false);
+  const hubIndex = readFileSync(
+    join(repositoryRoot, "skills/bailian-cli/reference/index.md"),
+    "utf8",
+  );
+  expect(hubIndex).not.toContain("`bl sandbox ");
+});

packages/commands/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli-commands",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Command library for bailian-cli products (knowledge, memory, media, …). See https://www.npmjs.com/package/bailian-cli for usage.",
   "homepage": "https://bailian.console.aliyun.com/cli",
   "bugs": {

packages/commands/src/commands/sandbox/file.ts

@@ -0,0 +1,113 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import {
+  agentStudioFilesPath,
+  BailianError,
+  defineCommand,
+  detectOutputFormat,
+  ExitCode,
+  sandboxBaseUrl,
+} from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { redactConnectionCredentials, resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const UPLOAD_SOURCE = "sandbox_template";
+
+export const sandboxFileUpload = defineCommand({
+  description: {
+    "en-US": "Upload a workspace file for Sandbox template mounts",
+    "zh-CN": "上传工作空间文件，供 Sandbox 模版挂载使用",
+  },
+  auth: "apiKey",
+  usageArgs: "--path <path> [--filename <name>] [--mime-type <type>]",
+  flags: {
+    ...WORKSPACE_FLAG,
+    path: {
+      type: "string",
+      valueHint: "<path>",
+      required: true,
+      description: { "en-US": "Local file path", "zh-CN": "本地文件路径" },
+    },
+    filename: {
+      type: "string",
+      valueHint: "<name>",
+      description: { "en-US": "Remote filename override", "zh-CN": "覆盖远端文件名" },
+    },
+    mimeType: {
+      type: "string",
+      valueHint: "<type>",
+      description: {
+        "en-US": "Multipart file MIME type (default: application/octet-stream)",
+        "zh-CN": "Multipart 文件部分的 MIME 类型（默认：application/octet-stream）",
+      },
+    },
+  },
+  exampleArgs: [
+    "--path ./config.json --output json",
+    "--path ./config.json --quiet",
+    "--path ./notes.txt --filename notes.txt --mime-type text/plain --dry-run --output json",
+  ],
+  notes: [
+    {
+      "en-US":
+        "POST /api/v1/agentstudio/files with multipart fields file and source=sandbox_template. Uses a Bailian Bearer API Key, not Console authentication or an E2B key; no agents.yaml is needed.",
+      "zh-CN":
+        "向 /api/v1/agentstudio/files 发送 multipart 字段 file 和 source=sandbox_template。使用百炼 Bearer API Key，不使用 Console 鉴权或 E2B Key；无需 agents.yaml。",
+    },
+    {
+      "en-US":
+        "Base URL follows Sandbox: --base-url > DASHSCOPE_BASE_URL > login/profile base_url. Without one, --workspace-id > BAILIAN_WORKSPACE_ID > config workspace_id selects the cn-beijing origin. The upload path has no /sandbox prefix.",
+      "zh-CN":
+        "Base URL 沿用 Sandbox：--base-url > DASHSCOPE_BASE_URL > 登录/Profile 的 base_url。未配置时，按 --workspace-id > BAILIAN_WORKSPACE_ID > 配置项 workspace_id 选择 cn-beijing 地址。上传路径不带 /sandbox 前缀。",
+    },
+    {
+      "en-US":
+        "Returns the upload response immediately; --quiet prints only its id. Upload does not wait for security review: status=checking is not ready to mount. Use an available file's id as mntConfig[].originFileId in template create/update --body, together with mountPath and optional originFileName, in the same workspace. This does not transfer files into a running instance.",
+      "zh-CN":
+        "上传响应返回后立即输出，--quiet 仅输出 id。不会等待安全审核：status=checking 不代表已可挂载。在同一工作空间的 template create/update --body 中，将可用文件的 id 填入 mntConfig[].originFileId，同时传入 mountPath 和可选的 originFileName。此命令不向运行中的实例传文件。",
+    },
+    {
+      "en-US":
+        "--dry-run previews the endpoint, source, and local path without reading or uploading the file. The service detects the MIME type and enforces upload limits.",
+      "zh-CN":
+        "--dry-run 仅预览 Endpoint、source 和本地路径，不读取或上传文件。MIME 类型检测和上传限制由服务端执行。",
+    },
+  ],
+  async run(ctx) {
+    const endpoint = ctx.client.url(agentStudioFilesPath(), () =>
+      sandboxBaseUrl(resolveWorkspaceId(ctx)),
+    );
+    const filename = ctx.flags.filename ?? basename(ctx.flags.path);
+    const mimeType = ctx.flags.mimeType ?? "application/octet-stream";
+    const format = detectOutputFormat(ctx.settings.output);
+    if (ctx.settings.dryRun) {
+      emitResult(
+        {
+          method: "POST",
+          endpoint,
+          request: { source: UPLOAD_SOURCE, file: { path: ctx.flags.path, filename, mimeType } },
+        },
+        format,
+      );
+      return;
+    }
+
+    const content = new Uint8Array(await readFile(ctx.flags.path));
+    const form = new FormData();
+    form.append("source", UPLOAD_SOURCE);
+    form.append("file", new Blob([content], { type: mimeType }), filename);
+    const file = await ctx.client.requestJson<Record<string, unknown>>({
+      method: "POST",
+      path: endpoint,
+      body: form,
+    });
+    if (!file || typeof file.id !== "string" || !file.id.trim()) {
+      throw new BailianError(
+        "Upload response did not contain a File ID. / 上传响应未包含 File ID。",
+        ExitCode.GENERAL,
+      );
+    }
+    if (ctx.settings.quiet) emitBare(file.id);
+    else emitResult(redactConnectionCredentials(file), format);
+  },
+});