@glodon-aiot/workspace-sandbox 0.2.0-alpha.0 → 0.2.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +70 -0
  2. package/package.json +4 -2
package/README.md ADDED
@@ -0,0 +1,70 @@
1
+ # @glodon-aiot/workspace-sandbox
2
+
3
+ 供端侧宿主调用:在工程目录内读写文件,并在 Microsoft Execution Containers 里执行命令和脚本。
4
+
5
+ 需要 Node.js 24。宿主启动本进程并转发请求。页面协议里没有本地绝对路径。
6
+
7
+ ## 启动
8
+
9
+ 常驻模式。stdin 每行一个 JSON 请求,stdout 每行一个 JSON 响应,用 `id` 对应。不监听端口。
10
+
11
+ ```bash
12
+ workspace-sandbox --serve
13
+ ```
14
+
15
+ 文件操作可以同时进行。`exec` 和 `run_python` 一次只能跑一个,第二个返回 `AbortError`。
16
+
17
+ 也可以不带 `--serve`,把单个 JSON 写到 stdin,stdout 返回一个 JSON。
18
+
19
+ ```bash
20
+ workspace-sandbox --manifest
21
+ workspace-sandbox --check
22
+ ```
23
+
24
+ `--manifest` 打印包名、版本、协议号、平台和 Node 版本。`--check` 在临时目录里跑 shell、Python、Node 和断网检查,失败时退出码为 1。
25
+
26
+ ## root
27
+
28
+ `root` 由宿主写成自己选定的工程目录绝对路径。请求里的其他路径都相对这个目录。
29
+
30
+ 本进程信任 `root`。能往 stdin 写 JSON 的一方,可以在该目录里列出、读取、写入和删除。文件操作在本进程内完成,不进入隔离容器。
31
+
32
+ ## 请求
33
+
34
+ `protocol` 可省略;写出时必须是 `1`。`op` 省略时按 `run_python` 处理。
35
+
36
+ 路径用 `/`,相对工程根。空字符串和 `.` 表示工程根。不能含 `..`、盘符、反斜杠或绝对路径。`input`、`output`、`uploads`、`tmp` 这些目录名不可用。
37
+
38
+ 成功时为 `{ "protocol": 1, "ok": true, ... }`。失败时为 `{ "protocol": 1, "ok": false, "name", "message" }`。`--serve` 下若请求带了字符串 `id`,响应里会原样带回。
39
+
40
+ | op | 请求字段 | 成功时多出的字段 |
41
+ | --- | --- | --- |
42
+ | `list` | `path` | `entries`:`{ name, kind: "file" \| "directory", size?, lastModified? }[]` |
43
+ | `stat` | `path` | `entry`:同样的字段 |
44
+ | `read` | `path` | `contentBase64`。单文件不超过 50 MB |
45
+ | `write` | `path`、`contentBase64`、`createDirectories` | 无 |
46
+ | `mkdir` | `path` | 无 |
47
+ | `remove` | `path`、`recursive` | 无。非空目录要 `recursive: true` |
48
+ | `move` | `from`、`to` | 无 |
49
+ | `exec` | `cwd`、`command` 或 `argv`、`timeoutMs`、`python` | `exitCode`、`timedOut`、`stdout`、`stderr`、`cwd?` |
50
+ | `run_python` | `script`、`args`、`timeoutMs`、`python` | `exitCode`、`timedOut`、`stdout`、`stderr`、`warnings` |
51
+
52
+ `lastModified` 是 Unix 毫秒,`size` 是字节。`timeoutMs` 默认 20 秒,最大 120 秒。命令输出超过 16000 个字符会截断。
53
+
54
+ `exec` 的 `command` 和 `argv` 二选一。`argv` 第一项只能是 `python3`、`node` 或 `sh`,第二项是工程内的脚本路径。Windows 上 `exec` 暂不可用。
55
+
56
+ `run_python` 的 `script` 必须是工程内的 `.py` 相对路径。`python` 由宿主写成解释器的绝对路径。macOS 和 Linux 上可以省略,此时使用系统里的 `python3`。
57
+
58
+ ```json
59
+ { "id": "1", "protocol": 1, "op": "read", "root": "/path/to/project", "path": "notes/readme.txt" }
60
+ ```
61
+
62
+ ```json
63
+ { "id": "2", "protocol": 1, "op": "exec", "root": "/path/to/project", "cwd": ".", "command": "python3 scripts/hello.py" }
64
+ ```
65
+
66
+ ## 命令隔离
67
+
68
+ `exec` 和 `run_python` 在 Microsoft Execution Containers 里执行:macOS 用 Seatbelt,Windows 用 ProcessContainer,Linux 用 Bubblewrap。工程目录可读写。工程外的符号链接和出站网络会被拒绝。子进程不继承宿主的环境变量。返回的 `stdout`、`stderr` 和 `cwd` 里,工程真实路径换成相对路径,用户主目录换成 `~`。
69
+
70
+ 工程根目录可以放 `sandbox-requirements.txt`。每行一个包名,可以写 extras 和版本,最多 20 行。网址、git 和本地路径会被拒绝。执行 Python 前把这些包装进该工程专用的虚拟环境,安装只访问 `pypi.org`、`files.pythonhosted.org` 和 `pypi.python.org` 的 443 端口。脚本运行时不再联网。
package/package.json CHANGED
@@ -1,10 +1,12 @@
1
1
  {
2
2
  "name": "@glodon-aiot/workspace-sandbox",
3
- "version": "0.2.0-alpha.0",
3
+ "version": "0.2.0-alpha.1",
4
4
  "description": "供端侧宿主调用:在工程目录内读写文件,并在 Microsoft Execution Containers 里执行命令和脚本。",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
- "bin": "./bin/workspace-sandbox.mjs",
7
+ "bin": {
8
+ "workspace-sandbox": "./bin/workspace-sandbox.mjs"
9
+ },
8
10
  "files": [
9
11
  "bin",
10
12
  "src"