superserve-ai/superserve

## 快速入门 访问 [superserve.ai](https://www.superserve.ai/) 或直接查阅[文档](https://docs.superserve.ai/)。 ## 结构 ``` apps/ console/ # Sandbox Dashboard (Next.js 16, App Router) ui-docs/ # UI component docs (Vite) packages/ cli/ # TypeScript CLI (@superserve/cli) python-sdk/ # Python SDK (superserve on PyPI) — hand-crafted sdk/ # TypeScript SDK (@superserve/sdk on npm) — hand-crafted ui/ # Shared UI components (@superserve/ui) supabase/ # Supabase client factories typescript-config/ # Shared tsconfig presets tailwind-config/ # Shared Tailwind config docs/ # Mintlify documentation site tests/ sdk-e2e-ts/ # TypeScript SDK e2e tests (Vitest) sdk-e2e-py/ # Python SDK e2e tests (pytest) spec/ # Planning and design documents ``` ## 设置 本仓库是一个使用 [Bun workspaces](https://bun.sh/docs/install/workspaces)、[Turborepo](https://turbo.build/repo) 和 [uv workspaces](https://docs.astral.sh/uv/concepts/projects/workspaces/) 管理的 monorepo。 ``` bun install # install all JS/TS dependencies uv sync # install all Python dependencies ``` ## 开发 ### 所有包 从仓库根目录运行跨越每个包的任务： ``` bun run dev # start all dev servers bun run build # build all packages bun run lint # lint all packages bun run typecheck # type check all packages bun run test # unit/integration tests (fast, no credentials) bun run test:coverage # unit tests with coverage ``` ### 针对特定包 ``` bunx turbo run dev --filter=@superserve/console bunx turbo run build --filter=@superserve/sdk bunx turbo run test --filter=@superserve/console -- # vitest filter ``` ### 添加依赖 始终从仓库根目录使用 `--filter` 添加依赖： ``` bun add zod --filter @superserve/cli bun add react --filter @superserve/console bun add -d @types/node --filter @superserve/sdk ``` ## SDKs 两个 SDK 均为手工编写（非代码生成）。当前版本：**0.6.0**。 ### TypeScript SDK — `@superserve/sdk` ``` import { Sandbox } from "@superserve/sdk" const sandbox = await Sandbox.create({ name: "my-sandbox" }) const result = await sandbox.commands.run("echo hello") console.log(result.stdout) await sandbox.files.write("/app/data.txt", "content") const text = await sandbox.files.readText("/app/data.txt") await sandbox.kill() ``` **构建 / 类型检查：** ``` bunx turbo run build --filter=@superserve/sdk bunx turbo run typecheck --filter=@superserve/sdk ``` ### Python SDK — `superserve` ``` from superserve import Sandbox sandbox = Sandbox.create(name="my-sandbox") result = sandbox.commands.run("echo hello") print(result.stdout) sandbox.files.write("/app/data.txt", b"content") text = sandbox.files.read_text("/app/data.txt") sandbox.kill() ``` 异步变体：`AsyncSandbox` 提供了可 await 的方法。 **构建 / 类型检查 / lint：** ``` bunx turbo run build --filter=@superserve/python-sdk bunx turbo run typecheck --filter=@superserve/python-sdk bunx turbo run lint --filter=@superserve/python-sdk ``` ## 测试 ### 单元测试（无需凭证） ``` bun run test ``` ### E2E 测试（需要凭证，会请求真实 API） ``` SUPERSERVE_API_KEY=ss_live_... bun run test:e2e ``` 默认使用 staging 环境。可通过 `SUPERSERVE_BASE_URL` 覆盖： ``` # 生产环境 SUPERSERVE_API_KEY=ss_live_... \ SUPERSERVE_BASE_URL=https://api.superserve.ai \ bun run test:e2e # Local backend SUPERSERVE_API_KEY=ss_dev_... \ SUPERSERVE_BASE_URL=http://localhost:8080 \ bun run test:e2e ``` 仅运行某一种语言的测试： ``` SUPERSERVE_API_KEY=ss_live_... bunx turbo run e2e --filter=@superserve/test-sdk-e2e-ts SUPERSERVE_API_KEY=ss_live_... bunx turbo run e2e --filter=@superserve/test-sdk-e2e-py ``` 如果没有设置 `SUPERSERVE_API_KEY`，所有 e2e 测试将被干净地跳过（exit 0）。 ### 覆盖范围 | 套件 | 文件 | 覆盖内容 | |---|---|---| | TS e2e | `tests/sdk-e2e-ts/tests/{sandboxes,exec,files}.test.ts` | 生命周期，同步 + 流式 exec，文件写入/读取 | | Python e2e | `tests/sdk-e2e-py/test_{sandboxes,exec,files,async}.py` | 与 TS 相同 + AsyncSandbox 冒烟测试 | | Console 单元测试 | `apps/console/src/**/*.test.{ts,tsx}` | 认证流程、组件、API 代理 | | CLI 单元测试 | `packages/cli/tests/**` | 配置验证、部署逻辑 | ## 文档 位于 [docs.superserve.ai](https://docs.superserve.ai/) 的文档站点是使用 [Mintlify](https://mintlify.com) 基于 `docs/` 目录构建的。 ``` bun run docs:dev # local dev server, hot-reloads MDX changes bun run docs:build # validate the docs build ``` 导航在 `docs/docs.json` 中配置。SDK 参考页面位于 `docs/sdk/{typescript,python}/` 下。 部署由 Mintlify 在向 `main` 分支推送代码时自动处理（无需手动发布步骤）。 ## 发布 ### 将 TypeScript SDK 发布到 npm 从仓库根目录执行： ``` # 1. 更新 packages/sdk/package.json 版本 # 2. 构建 + 发布 bunx turbo run build --filter=@superserve/sdk cd packages/sdk NPM_CONFIG_TOKEN=npm_... bun publish --access public ``` 或者加载 `.env.release` 后执行： ``` source .env.release bunx turbo run build --filter=@superserve/sdk cd packages/sdk && bun publish --access public ``` ### 将 Python SDK 发布到 PyPI **重要提示：** `uv build` 必须从**仓库根目录**运行（uv workspaces 会将构建产物放在根目录的 `dist/` 中）。需要在两处更新版本号（保持它们一致）： 1. `packages/python-sdk/pyproject.toml` → `version = "..."` 2. `packages/python-sdk/src/superserve/__init__.py` → `__version__ = "..."` ``` uv build --package superserve UV_PUBLISH_TOKEN=pypi-... uv publish dist/superserve-* ``` 或者加载 `.env.release` 后执行： ``` source .env.release uv build --package superserve uv publish dist/superserve-* ``` ### 发布环境设置 将 `.env.release.example` 复制为 `.env.release`，填入 token，并在运行发布命令之前 `source` 它。`.env.release` 已被 gitignore。 | 环境变量 | 使用者 | 获取方式 | |---|---|---| | `NPM_CONFIG_TOKEN` | `bun publish` (TS SDK) | [npmjs.com](https://www.npmjs.com) → 账户 → access tokens → automation token | | `UV_PUBLISH_TOKEN` | `uv publish` (Python SDK) | [pypi.org](https://pypi.org/manage/account/) → 账户 → API tokens (以 `pypi-` 开头) | ### CI 工作流 | 工作流 | 触发条件 | 动作 | |---|---|---| | **Release SDKs** | 手动触发 (`workflow_dispatch`) | 更新版本、构建、发布至 npm 和/或 PyPI，提交并打标签。输入项：`package` (`ts` / `python` / `both`)，`version`。 | 所需的仓库密钥： | 密钥 | 使用者 | |---|---| | `NPM_TOKEN` | Release SDKs (ts) | | `PYPI_TOKEN` | Release SDKs (python) | ## 快速参考 | 任务 | 命令 | |---|---| | 安装依赖 | `bun install && uv sync` | | 开发 (所有) | `bun run dev` | | 构建 (所有) | `bun run build` | | Lint | `bun run lint` | | 类型检查 | `bun run typecheck` | | 单元测试 | `bun run test` | | E2E 测试 | `SUPERSERVE_API_KEY=... bun run test:e2e` | | 文档开发 | `bun run docs:dev` | | 文档构建 | `bun run docs:build` | | 构建 TS SDK | `bunx turbo run build --filter=@superserve/sdk` | | 构建 Python SDK | `uv build --package superserve` (从仓库根目录运行) | | 发布 TS SDK | `cd packages/sdk && bun publish --access public` | | 发布 Python SDK | `uv publish dist/superserve-*` (从仓库根目录运行) | ## 联系我们 - [发送邮件](mailto:engineering@superserve.ai) - [Twitter/X](https://x.com/superserve_ai) - [LinkedIn](https://www.linkedin.com/company/super-serve-ai) ## 贡献 欢迎贡献代码！请参阅 [CONTRIBUTING.md](https://github.com/superserve-ai/superserve/blob/main/CONTRIBUTING.md) 了解指南。 ## 许可证 Apache License 2.0 — 详见 [LICENSE](https://github.com/superserve-ai/superserve/blob/main/LICENSE) 文件。

标签：AI基础设施, Apache 2.0, Bun, CLI, Firecracker, GNU通用公共许可证, Node.js, Python, SOC Prime, Supabase, Turborepo, TypeScript, Vite, WiFi技术, 代码执行安全, 后端开发, 安全插件, 安全规则引擎, 安全隔离, 开发工具, 开源, 微虚拟机, 无后门, 沙箱, 逆向工具