@coboot/headless 0.2.2-rc.6 → 0.2.2-rc.8

package/README.md

@@ -6,10 +6,30 @@ Headless 业务运行时要求 Node.js 20+；当入口检测到 Node.js 18/19
 首次启动只需一次性设备 token：
 
 ```bash
-npx -y @coboot/headless@0.2.2-rc.6 '<device-token>'
+npx -y @coboot/headless@0.2.2-rc.8 '<device-token>'
 ```
 
-命令会把运行时安装到 `/data/coboot/.siboot`，在客户端鉴权和运行时初始化完成后启动
+Siboot 和 Coboot 都继承入口进程的运行身份：入口是 root 就以 root 运行，入口是普通用户就以该用户运行。
+不会根据 `ANY_USERNAME`、`COBOOT_RUN_UID`、`HEADLESS_RUN_AS_USER` 或 sudo 来源自动切换身份、
+改写 HOME、复制到普通用户缓存或移交数据目录属主。
+后续 start／restart／update／status／stop 应保持相同运行用户和 XDG／HOME；切换账号不会自动
+查找另一用户的安装或凭据。
+
+
+
+新用户默认数据目录为 `${XDG_DATA_HOME:-$HOME/.local/share}/coboot-headless`，由当前普通用户创建，无需 sudo，不要求机器存在 `/data`。
+以 root 启动时仍以 root 创建和使用数据目录，默认使用该入口的 XDG／HOME（通常为
+`/root/.local/share/coboot-headless`）；不查找登录用户、不自动 chown 已有目录。
+需要普通用户运行时，应先切换到该用户再执行命令，不要使用 `sudo npx`。
+日常安装、设备注册、启动、管理和更新都不需要 sudo；Node LTS 引导、包内 Linux sandbox 和
+浏览器下载使用用户可写目录，不安装全局 npm 包、不修改系统配置。
+普通命令与 sudo 命令不要混用：sudo 保持 root，HOME／XDG 由 sudo 的环境策略决定，可能操作
+另一份安装或留下 root 属主的文件。只有补浏览器系统动态库等管理员操作时才考虑 sudo。
+凭证、程序版本和日志位于数据根下的 `.coboot/`；不检测、迁移或兼容旧目录。
+目录不可写时明确失败；请指定可写的应用数据目录，不要将项目目录用作应用数据目录。
+
+
+命令会把运行时安装到 `${XDG_DATA_HOME:-$HOME/.local/share}/coboot-headless` 下的私有运行目录，在客户端鉴权和运行时初始化完成后启动
 detached daemon 并退出。不需要设置 `BACKEND_URL`、`CLIENT_UID`。终端、文件等非浏览器能力不要求
 目标机安装 Chromium。
 
@@ -18,10 +38,10 @@ detached daemon 并退出。不需要设置 `BACKEND_URL`、`CLIENT_UID`。终
 并重新启动旧 client，不会让两个 Headless 进程争抢同一台物理机的 Driver 锁。
 
 ```bash
-npx -y @coboot/headless@0.2.2-rc.6 status
-npx -y @coboot/headless@0.2.2-rc.6 logs
-npx -y @coboot/headless@0.2.2-rc.6 restart
-npx -y @coboot/headless@0.2.2-rc.6 stop
+npx -y @coboot/headless@0.2.2-rc.8 status
+npx -y @coboot/headless@0.2.2-rc.8 logs
+npx -y @coboot/headless@0.2.2-rc.8 restart
+npx -y @coboot/headless@0.2.2-rc.8 stop
 ```
 
 更新到 npm `latest` 并重启：
@@ -33,8 +53,28 @@ npx -y @coboot/headless@latest update
 `update` 会先完成 Node.js 版本、设备凭证和新包完整性预检，再停止旧进程并切换版本；新版本启动失败时
 会自动恢复并重启旧版本。`restart` 只重启已经安装的版本，不再隐式替换运行时。
 
-默认数据根目录可通过 `SIBOOT_DATA_ROOT` 修改。该设置不会写入配置，首次安装以及后续的
-`status`、`logs`、`restart`、`update`、`stop` 都必须传入同一个值，否则 CLI 会操作 edition 默认目录。
+一般不需要修改数据目录。确需放到其他位置时，用 `COBOOT_DATA_ROOT` 指定一个当前用户可写的绝对路径。
+
+
+
+Coboot 将安装位置写入用户默认应用目录的 `installation.json`（不含凭据），后续 `status`、`logs`、
+`start`、`restart`、`update`、`stop` 无需重复传变量。
+首次安装指定 `COBOOT_DATA_ROOT=/自定义应用目录` 即可保存该位置。
+记录损坏时需要先修复记录；已经登记的安装不允许用一个参数静默切换到另一数据根。
+停止和查看状态不写记录，项目目录已删除时仍可停止进程。
+
+Agent 默认工作目录可在首次绑定或重启时单独指定，必须是已存在的绝对目录：
+
+```bash
+npx -y @coboot/headless@0.2.2-rc.8 '<device-token>' --workspace-dir /home/demo/project
+npx -y @coboot/headless@0.2.2-rc.8 restart --workspace-dir /home/demo/another-project
+```
+
+该设置会保存；任务明确选中的本机目录优先于安装默认值。Bash cwd 和相对文件路径使用同一默认值，
+仍受既有文件权限与沙箱策略限制。凭据、日志和后台进程 cwd 留在应用目录，不写入项目。
+显式 `$COBOOT_WORKSPACE` 和托管会话产物目录仍使用原有布局，不被此参数重定位。
+项目不可访问时启动／更新预检失败，不先停止正在运行的实例。`status` 可查看数据根和默认工作目录。
+
 
 
 ## Coboot 浏览器
@@ -45,13 +85,13 @@ Coboot daemon 默认禁用 updater 和浏览器预热，第一次调用 `browser
 
 ```bash
 HEADLESS_BROWSER_EXECUTABLE=/absolute/path/to/chrome \
-  npx -y @coboot/headless@0.2.2-rc.6 '<device-token>'
+  npx -y @coboot/headless@0.2.2-rc.8 '<device-token>'
 ```
 
 需要安装浏览器时，由用户执行：
 
 ```bash
-npx -y @coboot/headless@0.2.2-rc.6 install-browser
+npx -y @coboot/headless@0.2.2-rc.8 install-browser
 ```
 
 该命令不需要设备 token，也不要求 root。它会先检查现有浏览器并执行启动验证；浏览器已经可用时
@@ -61,9 +101,9 @@ npx -y @coboot/headless@0.2.2-rc.6 install-browser
   生效。镜像没有可用包管理器、源里没有 Chromium 或机器离线时，自动回退到下面的下载安装。
 - **非 root**：直接下载安装，不需要 sudo。
 
-下载安装用包内 `playwright-core` 把 Chromium 取到 `/data/coboot/.siboot/browsers`，需要访问
-`cdn.playwright.dev`。这个目录不是用户 HOME，daemon 启动时会指向同一个路径，因此换一个账号跑
-daemon 也不会失配，也不需要设置任何环境变量。用 `PLAYWRIGHT_BROWSERS_PATH` 可以改写该路径，
+下载安装用包内 `playwright-core` 把 Chromium 取到 `${XDG_DATA_HOME:-$HOME/.local/share}/coboot-headless` 下的私有浏览器目录，需要访问
+`cdn.playwright.dev`。浏览器缓存不直接使用 `~/.cache`，同一安装的 daemon 会指向同一个路径，
+无需另设环境变量；不同账号不会自动共享安装记录或凭据。用 `PLAYWRIGHT_BROWSERS_PATH` 可以改写该路径，
 但改写后启动或重启 daemon 必须带上同一个值。
 
 两条路径最后都会用包内 `playwright-core` 按 daemon 的真实启动参数做一次启动检查，因此可以安全
@@ -89,7 +129,7 @@ dnf/yum 先试仓库中的 `chromium`，x86_64 回退到官方 RPM 并关闭 wea
 自动化或排障需要显式表达重新注册时，也可以使用：
 
 ```bash
-npx -y @coboot/headless@0.2.2-rc.6 --force-enroll '<device-token>'
+npx -y @coboot/headless@0.2.2-rc.8 --force-enroll '<device-token>'
 ```
 
 当本地已经存在设备身份时，该命令与再次传入 positional token 使用同一套事务式替换流程。
@@ -107,8 +147,8 @@ session 级 `COBOOT_WORKSPACE` 时，将 `COBOOT_WORKSPACE/.home` 作为 Bash
 session workspace，则删除继承的 `HOME`。两种情况都会清理 `BASH_ENV` / `ENV`，不会读取宿主
 账号的 shell 启动脚本。
 
-Coboot Linux Headless 会把整个 `SIBOOT_DATA_ROOT`（默认 `/data/coboot`）作为可写根，其中
-`.siboot` 运行状态目录仍由 hard deny 遮蔽。这同时允许访问同机其他 team/agent/session 的数据，
+Coboot Linux Headless 会把整个 `COBOOT_DATA_ROOT`（默认 `${XDG_DATA_HOME:-$HOME/.local/share}/coboot-headless`）作为可写根，其中
+私有运行目录仍由 hard deny 遮蔽。这同时允许访问同机其他 team/agent/session 的数据，
 只适用于部署侧接受该权限边界的独占目标机；结构化文件工具仍继续执行自身的 ACL。
 
 
@@ -117,7 +157,7 @@ Coboot Linux Headless 会把整个 `SIBOOT_DATA_ROOT`（默认 `/data/coboot`）
 - Edition：`coboot`，在构建期写入，启动时不能切换。
 - 默认 HTTP 服务：`https://www.coboot.com`。
 - 默认 WebSocket 服务：`wss://www.coboot.com/wsschat`。
-- 默认数据根目录：`/data/coboot`。
+- 默认数据根目录：`${XDG_DATA_HOME:-$HOME/.local/share}/coboot-headless`。
 
 npm CLI 默认清理父进程遗留的 endpoint 环境变量。仅本地联调或自建环境可显式开启覆盖，且
 HTTP 与 WebSocket 必须同域并与设备 token 匹配：
@@ -126,7 +166,7 @@ HTTP 与 WebSocket 必须同域并与设备 token 匹配：
 HEADLESS_ALLOW_ENDPOINT_OVERRIDE=1 \
 BACKEND_URL=https://example.com \
 WS_URL=wss://example.com/wsschat \
-npx -y @coboot/headless@0.2.2-rc.6 '<device-token>'
+npx -y @coboot/headless@0.2.2-rc.8 '<device-token>'
 ```
 
 WebSocket 覆盖变量名是 `WS_URL`，不是 `WSS_URL`。
@@ -140,7 +180,7 @@ endpoint 覆盖同样不会写入配置；后续执行 `restart` 时必须再次
 CU_EDITION=coboot \
 PKG_NAME=@coboot/headless \
 PKG_BIN_NAME=coboot-headless \
-PKG_VERSION=0.2.2-rc.6 \
+PKG_VERSION=0.2.2-rc.8 \
 pnpm build:headless:npm
 ```
 
@@ -148,8 +188,8 @@ pnpm build:headless:npm
 
 ```bash
 npm pack --dry-run --json ./dist-headless
-tar -xOf dist-headless/coboot-headless-0.2.2-rc.6.tgz package/package.json
-sha256sum dist-headless/coboot-headless-0.2.2-rc.6.tgz
+tar -xOf dist-headless/coboot-headless-0.2.2-rc.8.tgz package/package.json
+sha256sum dist-headless/coboot-headless-0.2.2-rc.8.tgz
 ```