@tcb-sandbox/cli 0.3.7 → 0.3.8

package/docs/README.md

@@ -2,7 +2,7 @@
 
 | 文档 | 适合谁 | 内容 |
 |------|--------|------|
-| [quick-start.md](./quick-start.md) | 已经 `serve` 起来的人 | TRW **六大门面**（HTTP API、`/mcp`、`/mcp_user_define`、CLI、Skills、E2B）+ 健康/文档/预览辅助入口。 |
+| [quick-start.md](./quick-start.md) | 已经 `serve` 起来的人 | TRW **七大门面**（HTTP API、`/mcp`、`/mcp_user_define`、CLI、Skills、E2B、SDK）+ 健康/文档/预览辅助入口。 |
 | [thin-client.md](./thin-client.md) | 只连已有 TRW、不起服务 | 全局参数、子命令；环境变量省 `--endpoint` / `--session-id`。 |
 | [local-mode.md](./local-mode.md) | 用本机内置 TRW | `serve` / `local`、端口与数据目录、与线上一致性。 |
 
@@ -10,4 +10,4 @@
 
 **推荐顺序：** `quick-start` →（需要时再）`thin-client` 或 `local-mode`。
 
-**服务侧同一口径：** 仓库根 [README.md](../../README.md)「六大门面」、[docs/access-surfaces.md](../../docs/access-surfaces.md)。
+**服务侧同一口径：** 仓库根 [README.md](../../README.md)「七大门面」、[docs/access-surfaces.md](../../docs/access-surfaces.md)。

package/docs/local-mode.md

@@ -21,6 +21,26 @@ tcb-sandbox local    # 与 serve 完全等价，别名
 - 默认 **不做登录鉴权**；需要时应在 TRW 前面加网关。
 - **不是**云函数容器：没有冻结 / TTL / 唤醒语义；**Ctrl+C** 即停进程。
 
+## 文件写入沙箱（macOS）
+
+在 macOS 上，`serve` 自动通过 **`sandbox-exec`** 限制 TRW 进程的**文件写入**范围：
+
+| 可写路径 | 说明 |
+|----------|------|
+| `<workspace-root>/` | 会话工作区（默认 `~/.tcb-sandbox/workspaces`） |
+| `/tmp`、`/private/tmp` | 系统临时目录 |
+| `/dev` | 设备文件（tty、null 等） |
+| `/private/var/folders` | macOS 用户缓存 |
+
+**所有其他路径均为只读**——TRW 的 `bash`、`write`、`edit` 等工具无法在工作区外创建或修改文件。
+
+- **文件读取**：不限制，用户可以正常读取 `~/.ssh`、`~/.aws` 等目录。
+- **网络**：不限制，预览代理、`npm install` 等正常工作。
+- **进程**：不限制，`bash`、`node-pty` 等正常创建子进程。
+- **降级**：若 `sandbox-exec` 不可用（非 macOS 或被系统移除），静默跳过，不影响启动。
+
+启动横幅中 **`Sandbox`** 行会显示当前状态（`active` / `skipped`）。
+
 ## 内置的是什么
 
 发布包内包含：
@@ -50,7 +70,7 @@ pnpm --filter @tcb-sandbox/cli run build
 
 ## 启动之后
 
-TRW **六大门面**与探活/文档/预览见 **[quick-start.md](./quick-start.md)**。若只用 CLI 自测：
+TRW **七大门面**与探活/文档/预览见 **[quick-start.md](./quick-start.md)**。若只用 CLI 自测：
 
 ```bash
 tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id my-local-session health

package/docs/quick-start.md

@@ -8,7 +8,7 @@ tcb-sandbox serve
 
 服务一般在 **`http://127.0.0.1:9000`**（改过 `--host` / `--port` 的请替换下文地址）。
 
-TRW 产品上的 **六大门面** 是：**HTTP API**、`/mcp`、**`/mcp_user_define`**、**CLI**、**Skills**、**E2B**（与仓库根 README、`CLAUDE.md` 一致）。下面按这六条写「最小怎么接」；**健康检查、Scalar 文档、预览反代** 放在最后一节。
+TRW 产品上的 **七大门面** 是：**HTTP API**、`/mcp`、**`/mcp_user_define`**、**CLI**、**Skills**、**E2B**、**SDK**（与仓库根 README、`CLAUDE.md` 一致）。下面按这七条写「最小怎么接」；**健康检查、Scalar 文档、预览反代** 放在最后一节。
 
 ---
 
@@ -17,7 +17,7 @@ TRW 产品上的 **六大门面** 是：**HTTP API**、`/mcp`、**`/mcp_user_def
 | 项 | 说明 |
 |----|------|
 | **Base URL** | 下文用 `http://127.0.0.1:9000`。 |
-| **会话** | 六大门面里凡**真正干活**的调用都要 **`X-Cloudbase-Session-Id`**；CLI 写 **`--session-id`**。 |
+| **会话** | 七大门面里凡**真正干活**的调用都要 **`X-Cloudbase-Session-Id`**；CLI 写 **`--session-id`**。 |
 
 ---
 
@@ -59,6 +59,23 @@ tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id demo-1 read hello.txt
 
 **路径前缀：** **`/e2b-compatible/*`**。常见用法是 **E2B SDK + @tcb-sandbox/e2b-sandbox-adapter** 把流量转到当前 TRW。见 TRW **[docs/e2b-usage.md](../../docs/e2b-usage.md)**。
 
+## 7. SDK
+
+**TypeScript：** **`@tcb-sandbox/sdk-js`**；**Python：** **`tcb-sandbox-sdk-py`**。由 Fern 从 OpenAPI spec 自动生成，类型安全，覆盖全部 HTTP API。
+
+```typescript
+import { TcbSandboxClient } from "@tcb-sandbox/sdk-js";
+
+const client = new TcbSandboxClient({
+  environment: "http://127.0.0.1:9000",
+  cloudbaseSessionId: "demo-1",
+});
+
+const result = await client.fileOperations.read({ path: "hello.txt" });
+```
+
+发布流程见 **[sdks/README.md](../../sdks/README.md)**。
+
 ---
 
 ## 辅助：健康检查、文档、预览

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tcb-sandbox/cli",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Thin CLI client for tcb-remote-workspace HTTP API.",
   "type": "module",
   "packageManager": "pnpm@10.32.1",
@@ -13,7 +13,7 @@
     "build": "tsc -p tsconfig.json",
     "build:embed": "tsc -p tsconfig.json && node scripts/embed-trw.mjs",
     "test": "pnpm run build && vitest run tests/cli-mock.test.ts",
-    "prepublishOnly": "pnpm run build",
+    "prepublishOnly": "pnpm run build:embed && node scripts/check-sourcemap-safety.mjs && node scripts/check-pack-safety.mjs",
     "pack:dry-run": "pnpm pack --dry-run",
     "pack:safety": "node scripts/check-pack-safety.mjs"
   },