# 🧩 PRD: Sandbox 多语言模板与 Go 运行能力

> 状态: Draft  
> 负责人: 待确认  
> 更新时间: 2026-04-29  

---

## 📌 1. 背景（Background）

- 当前现状：
  - Sandbox 当前缺少一个默认可用的多语言复合模板。用户新建沙箱后，无法直接获得 Python、Go、Bash 等常见语言的统一运行环境。
  - 系统当前未完整支持 Go 程序运行，限制了使用 `go run` 执行远程 Go 工具、本地 Go 项目和 Go 依赖下载的场景。
  - 仓库中已存在模板管理、会话创建、代码执行和 workspace 相关能力，本需求是在现有能力基础上增强默认模板和 Go 执行链路。

- 存在问题：
  - 用户需要在沙箱内运行 Go 工具时，无法直接执行 `go run <module>@<version>`，例如 `goimports` 或 `golangci-lint`。
  - 用户上传本地 Go 项目后，缺少从 zip 上传、解压、切换 workspace、下载依赖到执行 `go run .` 的完整后端能力。
  - 新建沙箱默认模板能力不足，调用方需要额外选择或定制镜像才能获得多语言运行环境。
  - 执行代码接口对 workspace 阶段性错误的返回不够明确，不利于定位上传、解压、切换目录或命令执行失败的原因。

- 触发原因 / 业务背景：
  - GitHub issue `kweaver-ai/kweaver-core#203` 提出需要支持默认多语言复合模板，并补齐 Go 运行与 workspace 级代码执行能力。
  - Go 的 `go run` 是官方工具链内置能力，支持固定版本或 `@latest` 方式显式指定远程模块版本，适合在沙箱环境中按需执行代码质量、格式化和分析工具。

---

## 🎯 2. 目标（Objectives）

- 业务目标：
  - 在本需求发布后，新建沙箱可通过默认配置使用多语言复合模板，减少用户为 Python、Go、Bash 常见任务准备自定义模板的成本。
  - 支持 Go 远程模块命令与本地 Go 项目执行，使 Go 代码处理场景能够在 Sandbox 内闭环完成。

- 产品目标：
  - 默认多语言模板中 `python`、`go`、`bash` 基础命令可用率达到 100%。
  - 验收样例中的远程 Go 模块命令执行成功率达到 100%。
  - 本地 Go 项目 zip 上传、解压、workspace 切换、`go mod download`、`go run .` 的验收链路成功率达到 100%。
  - 现有 Python/Bash 执行链路和已有模板能力无回归。
  - 性能阈值、压缩包大小上限、并发规模和 SLA 目标：待确认。

---

## 👤 3. 用户与场景（Users & Scenarios）

### 3.1 用户角色

| 角色 | 描述 |
|------|------|
| 终端用户 | 在 Sandbox 中上传代码、运行命令、查看执行结果的使用者，重点包括需要运行 Go 项目或 Go 工具的用户。 |
| 开发者 | 集成 Sandbox API、创建沙箱会话、提交代码执行请求、处理执行结果的业务系统开发者。 |
| 管理员 | 维护模板镜像、默认模板配置、网络策略、资源限制和运行时安全边界的运维或平台管理员。 |

---

### 3.2 用户故事（User Story）

- 作为终端用户，我希望新建沙箱后直接拥有 Python、Go、Bash 运行能力，从而无需为常见语言任务手动准备模板。
- 作为 Go 项目用户，我希望上传本地 Go 项目 zip 后在指定 workspace 中执行依赖下载和 `go run .`，从而验证项目是否能在沙箱内正常运行。
- 作为平台集成开发者，我希望执行代码接口支持指定 workspace 并返回分阶段错误，从而在上层系统中准确展示失败原因。
- 作为平台管理员，我希望通过配置项控制默认模板，从而在不同部署环境中按需启用或回退多语言模板。

---

### 3.3 使用场景

- 场景1：用户新建沙箱后执行 `go version`、`python --version`、`bash --version`，确认默认模板具备多语言基础能力。
- 场景2：用户在沙箱中执行 `go run golang.org/x/tools/cmd/goimports@v0.28.0 .`，对 workspace 中的 Go 代码运行格式化工具。
- 场景3：用户执行 `go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 run`，对 Go 项目运行代码检查。
- 场景4：用户上传本地 Go 项目 zip，系统解压到指定目录后切换 workspace，并执行 `go mod download` 和 `go run .`。

---

## 📦 4. 需求范围（Scope）

### ✅ In Scope

- 新增一个多语言复合模板，至少预装 Python 运行时、Golang 工具链和 Bash。
- 新增或调整配置项，使新建沙箱默认模板可配置为多语言复合模板。
- 支持 `go run .` 执行本地 Go 项目。
- 支持 `go run <module>@<version>` 执行远程 Go 模块命令，版本支持固定版本和 `@latest`。
- 支持通过文件上传接口上传 Go 项目 zip，并在沙箱 workspace 内安全解压。
- 支持指定或切换执行时 workspace，并在目标 workspace 下执行命令。
- 支持执行 `go mod download` 安装 Go 项目依赖。
- 返回上传、解压、workspace 切换、依赖下载、命令执行等阶段的结果与错误信息。
- 补充目录逃逸、非法 workspace、下载失败、命令超时等安全和异常处理。

### ❌ Out of Scope

- 不在本期新增完整前端 UI 流程。
- 不在本期支持除 Python、Go、Bash 以外的新增语言运行时。
- 不在本期引入 Go 官方工具链以外的自定义 Go 执行包装工具。
- 不在本期定义多租户计费、配额管理或高级审计策略。
- 不在本期承诺所有第三方 Go 模块在受限网络环境下均可下载成功。

---

## ⚙️ 5. 功能需求（Functional Requirements）

### 5.1 功能结构

    多语言默认模板能力
    ├── 多语言模板镜像
    ├── 默认模板配置
    └── 模板可用性验证
    Go 运行能力
    ├── 本地 Go 项目执行
    ├── 远程 Go 模块执行
    └── Go 依赖下载
    Workspace 级代码执行能力
    ├── zip 上传与解压
    ├── workspace 指定与切换
    └── 分阶段结果与错误返回

---

### 5.2 详细功能

#### 【FR-1】多语言复合模板

**描述：**  
提供一个默认可配置的多语言复合模板，使新建沙箱能够直接运行 Python、Go、Bash。

**用户价值：**  
用户无需额外选择或构建模板，即可覆盖常见脚本、Go 工具和 shell 命令执行场景。

**交互流程：**
1. 管理员构建并注册多语言复合模板。
2. 管理员通过配置项将新建沙箱默认模板指向该模板。
3. 用户创建新沙箱。
4. 系统使用配置项指定的默认模板启动执行环境。
5. 用户在沙箱内执行 Python、Go、Bash 基础命令。

**业务规则：**
- 模板至少包含 Python 运行时、Golang 工具链和 Bash。
- 默认模板选择必须通过配置项控制，不直接强制替换所有部署环境的现有模板。
- 配置项缺失或配置值无效时，系统必须返回明确配置错误，或使用既有默认策略；具体回退策略待确认。

**边界条件：**
- 模板镜像大小、基础镜像版本、Python 版本、Go 版本和 Bash 版本待确认。
- 模板必须保留现有 Python/Bash 执行链路的兼容性。

**异常处理：**
- 模板不存在时，创建沙箱请求返回模板不存在或配置错误。
- 模板启动失败时，返回容器或执行环境启动失败原因。
- 基础命令不可用时，验收不通过并阻止发布。

---

#### 【FR-2】远程 Go 模块执行

**描述：**  
支持在沙箱内通过 `go run <module>@<version>` 执行远程 Go 模块命令。

**用户价值：**  
用户可以直接运行 Go 官方生态工具，无需预装 `goimports`、`golangci-lint` 等命令。

**交互流程：**
1. 用户在执行接口中提交 Go 远程模块命令。
2. 系统在指定 workspace 下执行命令。
3. Go 工具链按模块路径和版本下载依赖并构建命令。
4. 系统返回 stdout、stderr、退出码、耗时和错误阶段。

**业务规则：**
- 支持固定版本，例如 `@v0.28.0`、`@v1.62.0`。
- 支持 `@latest`。
- 优先复用官方 Go 工具链内置能力，不额外引入包装工具。
- 网络访问、Go proxy、模块缓存路径、下载超时和安全限制由部署配置决定，具体策略待确认。

**边界条件：**
- 远程模块下载依赖外网或 Go module proxy，可因网络策略失败。
- 首次执行可能包含模块下载和构建耗时；缓存策略和耗时阈值待确认。

**异常处理：**
- 模块下载失败时，返回下载阶段错误和 Go 工具链输出。
- 版本不存在或模块路径非法时，返回命令执行失败并保留 stderr。
- 命令超时时，终止执行并返回超时阶段、超时阈值和已捕获输出。

---

#### 【FR-3】本地 Go 项目 zip 上传与执行

**描述：**  
支持用户上传本地 Go 项目 zip，系统在沙箱中解压到指定工作目录，并在该目录下执行 Go 依赖下载和运行命令。

**用户价值：**  
用户可以把本地 Go 项目带入沙箱环境中运行，不需要提前把代码制作成镜像或手工同步文件。

**交互流程：**
1. 用户通过文件上传接口上传 Go 项目 zip。
2. 系统校验 zip 文件大小、格式和路径安全性。
3. 系统将 zip 解压到允许的 workspace 子目录。
4. 用户或上层系统指定执行 workspace。
5. 系统在目标 workspace 下执行 `go mod download`。
6. 系统在目标 workspace 下执行 `go run .` 或用户指定命令。
7. 系统返回各阶段结果和最终执行输出。

**业务规则：**
- 解压目录必须限制在当前沙箱 workspace 允许范围内。
- zip 文件不得通过 `../`、绝对路径或符号链接逃逸目标目录。
- workspace 必须是沙箱 workspace 根目录下的合法相对路径或平台允许的路径表达。
- zip 文件大小上限、单文件数量上限和解压后总大小上限待确认。

**边界条件：**
- zip 中不存在 `go.mod` 时，`go mod download` 可能失败，系统应返回明确失败信息。
- Go 项目入口不在解压根目录时，用户必须指定正确 workspace。
- 依赖下载受网络策略、代理配置和超时限制影响。

**异常处理：**
- zip 格式非法时，返回文件校验失败。
- 解压路径逃逸时，拒绝解压并返回安全校验失败。
- workspace 不存在或不可访问时，拒绝执行并返回 workspace 错误。
- `go mod download` 失败时，不继续执行 `go run .`，并返回依赖下载阶段错误。

---

#### 【FR-4】执行代码接口 workspace 增强

**描述：**  
调整执行代码接口，使调用方能够指定执行 workspace，并获得上传、解压、切换目录、命令执行等阶段的结构化结果。

**用户价值：**  
上层系统可以准确控制代码执行位置，并向用户展示清晰的失败原因。

**交互流程：**
1. 调用方创建或选择沙箱会话。
2. 调用方上传代码包或直接提交执行命令。
3. 调用方在请求中指定 workspace。
4. 系统校验 workspace 是否合法并切换执行目录。
5. 系统执行命令并返回分阶段结果。

**业务规则：**
- workspace 参数必须被限制在当前沙箱可写工作区内。
- 未指定 workspace 时，默认在当前沙箱 workspace 根目录执行。
- 返回结果必须能区分上传、解压、workspace 校验、依赖下载、命令执行阶段。
- 现有未指定 workspace 的 Python/Bash 执行请求必须保持兼容。

**边界条件：**
- workspace 路径为空时使用默认 workspace 根目录。
- workspace 指向文件而非目录时返回参数错误。
- workspace 指向不存在目录时的自动创建策略待确认。

**异常处理：**
- workspace 参数非法时，不执行命令并返回校验失败。
- 切换目录失败时，返回 workspace 切换阶段错误。
- 命令执行失败时，返回退出码、stdout、stderr 和执行阶段错误。

---

## 🔄 6. 用户流程（User Flow）

    管理员配置默认多语言模板
      → 用户创建沙箱
      → 系统按配置启动多语言模板环境
      → 用户上传 Go 项目 zip 或提交 go run 命令
      → 系统校验文件与 workspace
      → 系统解压并切换到目标 workspace
      → 系统执行 go mod download 或 go run
      → 系统返回分阶段结果、输出和错误信息

---

## 🎨 7. 交互与体验（UX/UI）

### 7.1 页面 / 模块
- 本期不新增前端页面。
- 现有模板管理页面和执行页面不作为本期必改范围。
- 如后续补充前端需求，可基于现有模板管理和执行页面扩展上传 zip、选择 workspace、展示分阶段结果能力。

### 7.2 交互规则
- API 返回结果需要支持上层前端或集成方展示 loading、success、error 状态。
- 错误提示需要明确失败阶段，例如文件上传失败、zip 解压失败、workspace 校验失败、依赖下载失败、命令执行失败。
- 用户可见文案由调用方决定；后端需要提供稳定、可区分的错误码或错误阶段字段，具体字段命名待设计阶段确认。

---

## 🚀 8. 非功能需求（Non-functional Requirements）

### 8.1 性能
- `go version`、`python --version` 等基础命令应在正常执行超时阈值内完成。
- 远程 Go 模块首次执行耗时受下载和构建影响，目标阈值待确认。
- Go 模块缓存命中后的执行耗时目标待确认。
- zip 上传大小、解压耗时和执行并发阈值待确认。

### 8.2 可用性
- 新建沙箱默认模板配置错误时，应提供可诊断错误，避免静默降级造成环境不一致。
- 已有 Python/Bash 执行能力必须保持可用。
- SLA 目标待确认。

### 8.3 安全
- workspace 路径必须做白名单或根目录约束，禁止目录逃逸。
- zip 解压必须校验绝对路径、`../`、符号链接和覆盖敏感路径风险。
- 远程模块下载必须遵守部署环境网络访问策略。
- 执行命令继续受现有沙箱隔离、资源限制和超时控制约束。

### 8.4 可观测性
- 支持记录模板 ID、workspace、命令类型、执行阶段、耗时、退出码和错误原因。
- 支持 tracing 关联上传、解压、依赖下载和命令执行阶段。
- 支持日志排查网络下载失败、模块构建失败、路径校验失败和执行超时。

---

## 📊 9. 埋点与分析（Analytics）

| 事件 | 目的 |
|------|------|
| sandbox_template_selected | 分析新建沙箱是否使用多语言默认模板。 |
| sandbox_runtime_probe_completed | 统计 Python、Go、Bash 基础命令可用性。 |
| go_remote_module_run_completed | 分析远程 Go 模块命令执行成功率、耗时和失败原因。 |
| go_project_zip_uploaded | 统计 Go 项目 zip 上传量、大小分布和失败原因。 |
| workspace_execution_completed | 分析指定 workspace 执行成功率、耗时和错误阶段。 |

---

## ⚠️ 10. 风险与依赖（Risks & Dependencies）

### 风险
- Go 远程模块执行依赖外网或 Go module proxy，网络策略不明确会导致命令不可用。
- 模块下载和构建缓存会影响首次执行时延，若无缓存策略，用户体验可能不稳定。
- zip 上传和 workspace 切换扩大执行接口能力边界，必须补齐路径校验、解压安全和权限隔离。
- 默认模板配置变更可能影响依赖特定镜像能力的调用方，需要确认兼容策略和回退方式。
- 多语言模板镜像体积可能增加启动耗时和镜像分发成本。

### 依赖
- 外部系统：Go module registry、Go proxy、容器镜像仓库。
- 内部服务：Sandbox Control Plane、Runtime Executor、模板仓库或模板数据库、文件上传服务、workspace 存储。
- 配置依赖：默认模板配置项、网络访问策略、资源限制、执行超时、Go 缓存目录策略。

---

## 📅 11. 发布计划（Release Plan）

| 阶段 | 时间 | 内容 |
|------|------|------|
| 需求评审 | 待确认 | 确认模板策略、接口范围、安全边界、性能目标和发布风险。 |
| 开发 | 待确认 | 实现多语言模板、默认模板配置、Go 执行能力、zip/workspace 后端能力。 |
| 测试 | 待确认 | 覆盖基础命令、远程 Go 模块、本地 Go 项目 zip、异常路径和兼容性回归。 |
| 发布 | 待确认 | 灰度启用默认模板配置，观察执行成功率、错误率和镜像启动表现。 |

---

## ✅ 12. 验收标准（Acceptance Criteria）

    Given 管理员已注册多语言复合模板并将默认模板配置指向该模板
    When 用户新建沙箱
    Then 系统使用多语言复合模板启动沙箱环境

    Given 用户已进入默认多语言模板沙箱
    When 用户执行 go version、python --version、bash --version
    Then 三类基础命令均执行成功并返回版本信息

    Given 默认多语言模板沙箱网络策略允许下载 Go 模块
    When 用户执行 go run golang.org/x/tools/cmd/goimports@v0.28.0 .
    Then 命令执行成功或返回 Go 工具链产生的可诊断错误信息

    Given 默认多语言模板沙箱网络策略允许下载 Go 模块
    When 用户执行 go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 run
    Then 系统返回命令 stdout、stderr、退出码和执行阶段信息

    Given 用户上传合法 Go 项目 zip
    When 系统完成解压并切换到指定 workspace 后执行 go mod download 和 go run .
    Then 系统返回依赖下载和运行命令的成功结果

    Given 用户上传包含目录逃逸路径的 zip
    When 系统校验 zip 文件
    Then 系统拒绝解压并返回安全校验失败信息

    Given 用户指定非法 workspace
    When 用户提交执行请求
    Then 系统不执行命令，并返回 workspace 校验失败信息

    Given 现有 Python 或 Bash 执行请求未指定 workspace
    When 用户按旧方式提交执行请求
    Then 系统保持原有默认 workspace 行为且执行结果不回归

---

## 🔗 附录（Optional）

- 相关文档：
  - HLD 链接：待确认
  - LLD 链接：待确认

- 参考资料：
  - GitHub issue: https://github.com/kweaver-ai/kweaver-core/issues/203

---
