@tcb-sandbox/cli 0.3.8 → 0.4.0

package/docs/local-mode.md

@@ -3,21 +3,35 @@
 在本机进程里跑 **内置的 TRW**（和远端沙箱同一套 HTTP / MCP 面），**不需要**单独发布一个叫 TRW 的 npm 包。
 
 ```bash
-tcb-sandbox serve
-tcb-sandbox local    # 与 serve 完全等价，别名
+tcb-sandbox serve          # 单工作空间模式（默认）
+tcb-sandbox serve --multi-session  # 多会话模式
+tcb-sandbox local          # 与 serve 完全等价，别名
 ```
 
+## 两种工作空间模式
+
+| 模式 | 启动方式 | Session Header | 工作目录 | 默认路径 |
+|------|----------|---------------|----------|----------|
+| **单工作空间**（默认） | `tcb-sandbox serve` | 不需要 | `--workspace-root` 本身 | `~/.tcb-sandbox/workspace` |
+| **多会话** | `tcb-sandbox serve --multi-session` | `X-Cloudbase-Session-Id` | `workspace-root/<session-id>/` | `~/.tcb-sandbox/workspaces` |
+
+**单工作空间模式**最适合本地开发：不需要 session header，直接对着工作目录操作。
+
+**多会话模式**行为与远端 SCF 完全一致，适合需要多租户隔离的测试场景。
+
 ## 常用参数
 
 | 选项 | 默认 | 说明 |
 |------|------|------|
 | `--port` | `9000` | 监听端口 |
 | `--host` | `127.0.0.1` | 绑定地址；`0.0.0.0` 会暴露到局域网，仅在你清楚风险时用 |
-| `--workspace-root` | `~/.tcb-sandbox/workspaces` | 会话目录父路径；每个 session 对应 `<workspace-root>/<session-id>/` |
+| `--workspace-root` | 见上表 | 工作目录（单模式）或会话父目录（多会话） |
+| `--multi-session` | `false` | 启用多会话模式 |
 
 ## 会话与安全
 
-- 客户端带 **`X-Cloudbase-Session-Id`**（CLI 用 **`--session-id`**）。
+- **单工作空间模式**：无需 session header；内部使用固定 session ID `"default"`。
+- **多会话模式**：客户端带 **`X-Cloudbase-Session-Id`**（CLI 用 **`--session-id`**）。
 - 默认 **不做登录鉴权**；需要时应在 TRW 前面加网关。
 - **不是**云函数容器：没有冻结 / TTL / 唤醒语义；**Ctrl+C** 即停进程。
 
@@ -27,7 +41,7 @@ tcb-sandbox local    # 与 serve 完全等价，别名
 
 | 可写路径 | 说明 |
 |----------|------|
-| `<workspace-root>/` | 会话工作区（默认 `~/.tcb-sandbox/workspaces`） |
+| `<workspace-root>/` | 会话工作区 |
 | `/tmp`、`/private/tmp` | 系统临时目录 |
 | `/dev` | 设备文件（tty、null 等） |
 | `/private/var/folders` | macOS 用户缓存 |
@@ -70,7 +84,19 @@ pnpm --filter @tcb-sandbox/cli run build
 
 ## 启动之后
 
-TRW **七大门面**与探活/文档/预览见 **[quick-start.md](./quick-start.md)**。若只用 CLI 自测：
+TRW **七大门面**与探活/文档/预览见 **[quick-start.md](./quick-start.md)**。
+
+单工作空间模式自测：
+
+```bash
+# 不需要 --session-id
+tcb-sandbox --endpoint http://127.0.0.1:9000 health
+curl -X POST http://localhost:9000/api/tools/bash \
+  -H 'Content-Type: application/json' \
+  -d '{"command": "echo hello"}'
+```
+
+多会话模式自测：
 
 ```bash
 tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id my-local-session health
@@ -88,6 +114,7 @@ tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id my-local-session healt
 
 | 点 | 说明 |
 |----|------|
+| 工作空间模式 | 本地默认单工作空间（无 session）；远端始终多会话（SCF 网关注入 session） |
 | 符号链接相关用例 | 线上常有 **`WORKSPACE_SYMLINKS`**；随手 `serve` 没配可能和 trw-example 本地阶段表现不一致 |
 | 快照 / S3 | 本地常未配 S3；只要错误信息里提到配置即可视为预期 |
 | 预览里 `npm install` | TRW 进程要能访问外网 |

package/docs/quick-start.md

@@ -57,7 +57,7 @@ tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id demo-1 read hello.txt
 
 ## 6. E2B 兼容
 
-**路径前缀：** **`/e2b-compatible/*`**。常见用法是 **E2B SDK + @tcb-sandbox/e2b-sandbox-adapter** 把流量转到当前 TRW。见 TRW **[docs/e2b-usage.md](../../docs/e2b-usage.md)**。
+**根路径数据面：** E2B 兼容路由挂在**网关根**（`/files`、`/process.*` 等），使用 **E2B SDK `sandboxUrl` + `X-Cloudbase-Session-Id` 直连**即可，无需本地代理。见 **[docs/e2b-usage.md](../../docs/e2b-usage.md)**。
 
 ## 7. SDK
 

package/docs/thin-client.md

@@ -83,18 +83,9 @@ tcb-sandbox pty kill <ptyId> --signal SIGTERM
 
 把 `<ptyId>` 换成上一步 `create` 返回的 id。
 
-## 通用 `tools call`（旧形态）
+## 旧文档兼容说明
 
-有的文档仍写 `tools call …`。**有新子命令时优先用子命令**；没有对应子命令时再走下面形式。工具名、参数与 HTTP **`/api/tools/{tool}`** 一致。
+旧文档里可能出现 `tools call ...` 写法，但当前 CLI 已移除该入口。
 
-```bash
-tcb-sandbox tools call read --param path=README.md
-
-tcb-sandbox tools call write --data '{"path":"hello.txt","content":"hello"}'
-
-tcb-sandbox tools call bash --param command='echo hello' --param mode=dry_run
-```
-
-`bash`：**不写 `mode` 为执行**；`mode=dry_run` / `dryrun` 为干跑（带风险摘要与 `changeSet`）。
-
-其余如 `capability_list`、`list_mcp_servers`、`add_mcp_servers` 等，把工具名和 `--data` / `--param` 换成 `/api/docs` 中的定义即可，不再逐条罗列。
+- ✅ 请直接使用对应顶级子命令（`read` / `write` / `bash` / `capability-*` / `add-mcp-servers` 等）
+- ✅ 具体参数以 `tcb-sandbox --help` 与 `GET /api/docs` 为准

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tcb-sandbox/cli",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "Thin CLI client for tcb-remote-workspace HTTP API.",
   "type": "module",
   "packageManager": "pnpm@10.32.1",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@mongodb-js/zstd": "^7.0.0",
-    "@tcb-sandbox/sdk-js": "^0.1.1",
+    "@tcb-sandbox/sdk-js": "^0.2.0",
     "commander": "^14.0.3",
     "node-pty": "^1.1.0"
   },