@clawos-dev/clawd 0.2.693 → 0.2.694

package/README.md

@@ -9,15 +9,29 @@ npx @clawos-dev/clawd@latest
 npx @clawos-dev/clawd@latest --port 28790
 npx @clawos-dev/clawd@latest --data-dir /path/to/data
 npx @clawos-dev/clawd@latest --tunnel
+npx @clawos-dev/clawd@latest --web
 ```
 
 也可全局安装后运行 `clawd`。默认监听 `127.0.0.1:18790`，数据目录为 `~/.clawd`；参数与配置的当前定义见 [config.ts](./src/config.ts)。完整参数用 `clawd --help` 查看。
 
 常用选项：`--port`、`--data-dir`、`--config`、`--log-level`、`--tunnel`、`--clawos-api`、`--auth-token`、`--no-log-shipping`。环境变量由 `resolveConfig` 解析，不根据旧示例猜测支持范围。
 
+## 浏览器管理网页（`--web`）
+
+`clawd --web` 启动（或复用已在运行的）本机 daemon，并在默认浏览器打开 daemon 内置的管理网页 `/app/`，无需安装桌面 App。
+
+- **前台运行**：CLI 自己启动的 daemon 随终端退出而停止（Ctrl-C）；复用已运行的 daemon 时，CLI 打开页面后立即退出，不影响它。
+- **固定端口**：未指定 `--port` 且配置文件没有端口时，同一数据目录首次选 18790（被占用则选一个空闲端口）并记录在 `<data-dir>/web-port.json`，之后不再变化——浏览器的存储按来源隔离，端口变了就等于换了一个页面。记录的端口被无关进程占用时直接报错，不会悄悄换端口。显式 `--port` 按原样使用，不写记录。
+- **登录方式**：CLI 通过已认证的 `web:open` 取得一次性启动链接（随机 256 bit、60 秒、只能用一次、票据在 URL fragment 里），页面立即清除 fragment 并换取网页会话（7 天，绑定页面来源，服务端只存摘要，存放在 `<data-dir>/web-sessions.json`，权限 0600）。会话 token 只放在该标签页的 `sessionStorage`，关闭标签页后重新运行命令。长期 owner token 不会通过协议帧下发给页面（ready / info 里的 `httpToken` 换成该会话自己的 token）。注意：网页会话本身是 owner 等价的，同源脚本能做 owner 能做的事，所以预览内容必须保持沙箱隔离；`Origin` 校验只防浏览器，本机其他进程可以伪造请求头，这与本机 loopback 信任边界一致。会话没有吊销入口，到期或删除 `web-sessions.json` 才失效；已建立的 WebSocket 连接不会在会话到期时被断开。启动链接会出现在浏览器启动进程的参数里（约 60 秒内有效）。
+- **不兼容的旧 daemon**：已有 daemon 版本过旧或不应答时，命令会给出明确提示并退出，不会替换别人启动的进程。
+- **打开失败**：找不到浏览器或启动器退出失败时明确报错；日志里只会出现不含票据的基础地址。`BROWSER` 可指定启动器可执行文件，启动器应在把链接交给浏览器后退出，以非零退出码报告失败。
+- 首版边界：macOS + Chrome；不含后台服务安装、Windows 支持；`--tunnel` 下的公网来源不支持网页登录。
+
 ## 鉴权与远程接入
 
 - **WebSocket**：无 tunnel 时 loopback 连接可豁免首帧鉴权；启用 tunnel 后 loopback 也要求鉴权。需要鉴权的客户端发送 `{"type":"auth","token":"<token>"}` 并等待 `auth:ok` 后再发送业务帧。凭据决定 owner / guest 身份与权限，不由客户端自报身份。
+- **浏览器来源**：带 `Origin` 头的 WebSocket 连接（即网页）即使来自 loopback 也必须鉴权，不能借用本机免认证；无 `Origin` 的 native / CLI 客户端保持原行为。旧桌面端的 `file://`（`Origin: null`）连接持有效 owner token 时照常可用。本地用 Vite 开发（`pnpm dev`）时，需用环境变量 `CLAWD_WEB_DEV_ORIGINS=http://localhost:5173`（逗号分隔，可多个）启动 daemon，把开发页面来源显式列为豁免。
+- **文件预览隔离**：`/files/*` 与 `/session/*/files` 返回的 HTML / SVG 一律带 `Content-Security-Policy: sandbox allow-scripts`——脚本可以运行以便预览，但页面处于不透明来源，读不到管理页的存储，也不能操作 opener / parent、弹窗或导航顶层。前端 Blob 预览仅允许被动图片和视频 MIME；SVG 不走 Blob 内嵌预览，伪装成媒体文件名的 SVG/HTML/XML 响应也会被拒绝，避免转换为同源 Blob 时丢失沙箱保护。
 - **HTTP RPC**：无论是否启用 tunnel 都使用已解析的 Bearer token。WebSocket 的本机豁免不适用于 HTTP。
 - `--tunnel` 注册公网隧道并启动 frpc，使手机和授权的远端客户端能连接本机 daemon。连接串包含凭据，只交给授权客户端，不贴入诊断报告。
 

package/dist/app-builder-plugin/mcp-server.cjs

@@ -34382,6 +34382,10 @@ var METHOD_DOCS = {
     summary: "\u5217\u51FA\u767B\u5F55\u8BBF\u95EE\u8FC7\u672C\u673A public persona \u7684 web \u8BBF\u5BA2\u3002owner-only",
     args: NO_ARGS
   },
+  "web:open": {
+    summary: "\u7B7E\u53D1\u4E00\u6B21\u6027\u542F\u52A8 URL\uFF0C\u7528\u6D4F\u89C8\u5668\u6253\u5F00 daemon \u5185\u7F6E\u7684\u7BA1\u7406\u7F51\u9875\uFF08/app/\uFF09\u3002\u7968\u636E\u653E URL fragment\u300160 \u79D2\u5185\u5355\u6B21\u6709\u6548\uFF0C\u5151\u6362\u540E\u6362\u6210\u7F51\u9875\u4F1A\u8BDD token\u3002owner-only\uFF0C\u7F51\u9875\u4F1A\u8BDD\u81EA\u8EAB\u4E0D\u80FD\u518D\u7B7E\u53D1",
+    args: NO_ARGS
+  },
   whoami: {
     summary: "\u8FD4\u56DE\u672C\u8FDE\u63A5\u7684\u8EAB\u4EFD\uFF1Aowner \u663E\u793A\u540D + capability wire \u5F62\u6001 + \u88AB\u6388\u6743\u7684 persona \u5217\u8868\u3002\u4EFB\u4F55 authed \u8FDE\u63A5\u53EF\u8C03",
     args: NO_ARGS
@@ -34592,6 +34596,19 @@ var VisitorRecordSchema = external_exports.object({
 });
 var VisitorListResultSchema = external_exports.object({ visitors: external_exports.array(VisitorRecordSchema) });
 
+// ../protocol/src/web-schemas.ts
+var WebOpenResultSchema = external_exports.object({
+  type: external_exports.literal("web:open"),
+  /** Launch URL; the one-time ticket travels in the URL fragment so it never reaches server logs. */
+  url: external_exports.string().min(1),
+  expiresAt: external_exports.number()
+});
+var WebSessionExchangeBodySchema = external_exports.object({ ticket: external_exports.string().min(1) }).strict();
+var WebSessionExchangeResultSchema = external_exports.object({
+  token: external_exports.string().min(1),
+  expiresAt: external_exports.number()
+});
+
 // ../protocol/src/dispatch-format.ts
 var INNER_TAG_NAMES = "clawd-dispatch-task|clawd-dispatch-result|brief|detail|files";
 var INNER_TAG_ESCAPE_RE = new RegExp(`<(\\\\*)(/?)(${INNER_TAG_NAMES})\\b`, "g");