@tcb-sandbox/cli 0.3.7

package/dist/trw-version.json

@@ -0,0 +1 @@
+{"version":"0.2.0"}

package/docs/README.md

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

package/docs/local-mode.md

@@ -0,0 +1,76 @@
+# 本地模式：`serve` / `local`
+
+在本机进程里跑 **内置的 TRW**（和远端沙箱同一套 HTTP / MCP 面），**不需要**单独发布一个叫 TRW 的 npm 包。
+
+```bash
+tcb-sandbox serve
+tcb-sandbox local    # 与 serve 完全等价，别名
+```
+
+## 常用参数
+
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `--port` | `9000` | 监听端口 |
+| `--host` | `127.0.0.1` | 绑定地址；`0.0.0.0` 会暴露到局域网，仅在你清楚风险时用 |
+| `--workspace-root` | `~/.tcb-sandbox/workspaces` | 会话目录父路径；每个 session 对应 `<workspace-root>/<session-id>/` |
+
+## 会话与安全
+
+- 客户端带 **`X-Cloudbase-Session-Id`**（CLI 用 **`--session-id`**）。
+- 默认 **不做登录鉴权**；需要时应在 TRW 前面加网关。
+- **不是**云函数容器：没有冻结 / TTL / 唤醒语义；**Ctrl+C** 即停进程。
+
+## 内置的是什么
+
+发布包内包含：
+
+- **`dist/trw-embedded.js`** — TRW 生产 bundle（esbuild）
+- **`dist/trw-version.json`** — 启动横幅里用的版本信息
+
+**node-pty**、**@mongodb-js/zstd** 在包的 `dependencies` 里：bundle 里用动态 `import()` 加载它们。
+
+## 换成本地自己编的 TRW（可选）
+
+```bash
+TCB_SANDBOX_TRW_ENTRY=/path/to/tcb-remote-workspace/dist/index.js tcb-sandbox serve
+```
+
+路径指向你 `build:prod` 等产物即可。
+
+## 仓库里怎么重打 embedded
+
+在 **tcb-remote-workspace** 根目录：
+
+```bash
+pnpm --filter @tcb-sandbox/cli run build
+```
+
+会跑 TRW 的 **`build:prod`**，再把结果拷进 **`@tcb-sandbox/cli/dist/trw-embedded.js`**。
+
+## 启动之后
+
+TRW **六大门面**与探活/文档/预览见 **[quick-start.md](./quick-start.md)**。若只用 CLI 自测：
+
+```bash
+tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id my-local-session health
+```
+
+---
+
+## 本地和线上一致吗？
+
+**本包自带的测试**（`pnpm test` → Vitest + mock HTTP）只验证 CLI 参数、请求头、少量路径；**不验证**真实 TRW、不验证 `serve`、不验证 embedded bundle。把它当成 **客户端契约回归** 即可。
+
+**要对齐「像真线上那样」**，用 sibling 仓库 **trw-example** 的 **`pnpm start`**：在典型 monorepo 布局下会先跑 **本机 embedded**，再跑 **`.env` 里的远端**，对照两张矩阵表。
+
+**和云镜像常见的差异（不是 CLI 写错）：**
+
+| 点 | 说明 |
+|----|------|
+| 符号链接相关用例 | 线上常有 **`WORKSPACE_SYMLINKS`**；随手 `serve` 没配可能和 trw-example 本地阶段表现不一致 |
+| 快照 / S3 | 本地常未配 S3；只要错误信息里提到配置即可视为预期 |
+| 预览里 `npm install` | TRW 进程要能访问外网 |
+| 网关 500 类问题 | 远端可能需要 `SKIP_UNTIL_TCB_GATEWAY_STATUS_FIX`；本地往往不需要 |
+
+**TRW 仓库里的 `pnpm run test:full`** 会跑 **本包 test**，但**不会**自动跑 trw-example；完整 HTTP/MCP/E2B/CLI 矩阵仍以 trw-example 为准。

package/docs/quick-start.md

@@ -0,0 +1,82 @@
+# 本地启动之后怎么用
+
+默认你已经执行：
+
+```bash
+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 文档、预览反代** 放在最后一节。
+
+---
+
+## 两条约定
+
+| 项 | 说明 |
+|----|------|
+| **Base URL** | 下文用 `http://127.0.0.1:9000`。 |
+| **会话** | 六大门面里凡**真正干活**的调用都要 **`X-Cloudbase-Session-Id`**；CLI 写 **`--session-id`**。 |
+
+---
+
+## 1. HTTP API
+
+**形态：** `POST /api/tools/{工具名}`，`Content-Type: application/json`，Body 见 **`GET /api/docs`** 里对应工具的 `input_schema`。
+
+```bash
+curl -sS -X POST "http://127.0.0.1:9000/api/tools/write" \
+  -H "Content-Type: application/json" \
+  -H "X-Cloudbase-Session-Id: demo-1" \
+  -d '{"path":"hello.txt","content":"hi"}'
+```
+
+## 2. `POST /mcp`
+
+**无状态** MCP Streamable HTTP；URL：`http://127.0.0.1:9000/mcp`，Header 带 session。接入说明见 TRW **[docs/mcp-usage.md](../../docs/mcp-usage.md)**。
+
+## 3. `/mcp_user_define`
+
+**有状态**动态 MCP：工具来自会话 **`.mcporter/mcporter.json`** 里配置的 stdio 服务，文件变更会 **热刷新**。路径统一为 **`/mcp_user_define`**（GET 常用来建 SSE、POST 走 JSON-RPC，以你所用 MCP 客户端为准）。与 `/mcp` **不是**同一套工具列表。细节见 TRW **[docs/feature-tree.md](../../docs/feature-tree.md)**。
+
+## 4. CLI（`tcb-sandbox`）
+
+**不监听端口**，只是 HTTP API 的封装。另开终端：
+
+```bash
+tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id demo-1 health
+tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id demo-1 read hello.txt
+```
+
+可设 **`TCB_SANDBOX_ENDPOINT`**、**`TCB_SANDBOX_SESSION_ID`** 少打字。子命令见 [thin-client.md](./thin-client.md)。
+
+## 5. Skills
+
+**没有单独的 `http://…/skills` 路由。** 技能包在 TRW 仓库的 **`skills/`**（例如内置 **`skills/tcb-sandbox/`**），通过 **`capability_list` / `capability_describe` / `capability_register`**（`kind=skill`）发现与注册，由 Agent 在 sandbox 内按包内说明执行。见 TRW **[docs/capability-overview.md](../../docs/capability-overview.md)**。
+
+## 6. E2B 兼容
+
+**路径前缀：** **`/e2b-compatible/*`**。常见用法是 **E2B SDK + @tcb-sandbox/e2b-sandbox-adapter** 把流量转到当前 TRW。见 TRW **[docs/e2b-usage.md](../../docs/e2b-usage.md)**。
+
+---
+
+## 辅助：健康检查、文档、预览
+
+| 用途 | 说明 |
+|------|------|
+| 探活 | `GET /health`（一般**不要** session） |
+| 人读文档 | 浏览器打开 **`/reference`** |
+| 机器读契约 | **`/openapi.json`**、**`/api/docs`** |
+| 预览 / Web 终端 | 先调 HTTP 工具 **`preview_ports` / `preview_url`**（或 capability **preview-service**），再访问 **`/preview/{port}/...`** |
+
+---
+
+## 和另外两篇怎么配合
+
+- **只当客户端连任意 TRW：** [thin-client.md](./thin-client.md)
+- **只关心本机 `serve` 参数、内置 bundle：** [local-mode.md](./local-mode.md)
+
+## 完整矩阵验收
+
+跨门面的大表在独立仓库 **trw-example**（`pnpm start`）。本包 **`pnpm test`** 不包含那套实时矩阵。

package/docs/thin-client.md

@@ -0,0 +1,100 @@
+# 薄客户端：连已有 TRW
+
+除 **`serve` / `local`** 外，其余子命令都是在调 **TRW 的 HTTP API**：不启动服务，只发请求。
+
+## 前提
+
+1. 已经有一个在跑的 TRW（云上、内网、或 [本机 serve](./local-mode.md)）。
+2. 知道 **`--endpoint`**（或环境变量 **`TCB_SANDBOX_ENDPOINT`**）。
+3. 几乎所有调用都要 **`--session-id`**（或 **`TCB_SANDBOX_SESSION_ID`**）。只有打在未带会话限制的路由上时可以省略（例如部分部署下未鉴权的 `health`，以实际网关为准）。
+
+## 少打字的写法
+
+在 shell 里先导出一次，后面命令可以省略 `--endpoint` / `--session-id`：
+
+```bash
+export TCB_SANDBOX_ENDPOINT=http://127.0.0.1:9000
+export TCB_SANDBOX_SESSION_ID=demo
+tcb-sandbox health
+tcb-sandbox read README.md
+```
+
+额外 HTTP 头可用 **`-H 'Name: value'`** 重复写，或 **`TCB_SANDBOX_HEADERS_JSON='{"Name":"value"}'`**。
+
+## 全局选项
+
+| 选项 | 含义 |
+|------|------|
+| `-e, --endpoint` | TRW 根 URL |
+| `-s, --session-id` | 会话 id |
+| `-H, --header` | 附加头，可重复 |
+| `--timeout` | 超时毫秒（默认 600000） |
+| `-o, --output` | `json` \| `pretty` |
+| `--log-level` | `debug` \| `info` \| `warn` \| `error`（默认 warn） |
+| `--log-format` | `text` \| `json` |
+| `--verbose` / `--debug` / `--quiet` | 日志档位快捷方式 |
+
+HTTP：**Accept** 默认包含 problem+json、json 等；**非 2xx** 时尽量按 RFC 9457 返回问题详情（可能有 `error_code`、`retry_after`）。
+
+## 子命令一览
+
+```text
+health   docs   read   write   edit   bash   grep   glob   ls   batch   git-push
+mcporter   add-mcp-servers   remove-mcp-servers   list-mcp-servers
+capability-list   capability-describe   capability-install   capability-register
+capability-remove   capability-invoke
+snapshot (create|status|restore)
+secrets (set|get|list|delete)
+files (upload|download)
+preview (ports|url|open)
+pty (create|send-input|resize|read-output|kill)
+```
+
+`docs` 优先请求 **`GET /api/docs`**；连不上时 CLI 可能用内置文档快照。
+
+## 示例：密钥
+
+```bash
+tcb-sandbox secrets set OPENAI_API_KEY --value-stdin
+tcb-sandbox secrets get OPENAI_API_KEY
+tcb-sandbox secrets list
+tcb-sandbox secrets delete OPENAI_API_KEY
+```
+
+（若未导出环境变量，请在每条命令前加上 `--endpoint` 与 `--session-id`。）
+
+## 示例：预览
+
+```bash
+tcb-sandbox preview ports
+tcb-sandbox preview url 3000
+tcb-sandbox preview open 3000 --print-only
+```
+
+## 示例：PTY
+
+```bash
+tcb-sandbox pty create --command bash --args -lc 'sleep 60'
+tcb-sandbox pty send-input <ptyId> --text 'echo hello\n'
+tcb-sandbox pty resize <ptyId> --cols 120 --rows 40
+tcb-sandbox pty read-output <ptyId> --after-seq 0 --limit 64
+tcb-sandbox pty kill <ptyId> --signal SIGTERM
+```
+
+把 `<ptyId>` 换成上一步 `create` 返回的 id。
+
+## 通用 `tools call`（旧形态）
+
+有的文档仍写 `tools call …`。**有新子命令时优先用子命令**；没有对应子命令时再走下面形式。工具名、参数与 HTTP **`/api/tools/{tool}`** 一致。
+
+```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` 中的定义即可，不再逐条罗列。

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@tcb-sandbox/cli",
+  "version": "0.3.7",
+  "description": "Thin CLI client for tcb-remote-workspace HTTP API.",
+  "type": "module",
+  "packageManager": "pnpm@10.32.1",
+  "bin": {
+    "tcb-sandbox": "dist/cli.js",
+    "@tcb-sandbox/cli": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "scripts": {
+    "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",
+    "pack:dry-run": "pnpm pack --dry-run",
+    "pack:safety": "node scripts/check-pack-safety.mjs"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "tcb",
+    "sandbox",
+    "cli",
+    "remote-workspace"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@mongodb-js/zstd": "^7.0.0",
+    "@tcb-sandbox/sdk-js": "^0.1.1",
+    "commander": "^14.0.3",
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
+  }
+}