89 lines
8.3 KiB
Markdown
89 lines
8.3 KiB
Markdown
# 工作台 0.5.1：兼容、隔离与故障处理
|
||
|
||
适用源码：0.5.1。公开发布状态以 GitHub Release 为准。本文解释当前代码契约；验证范围与安装命令见 [包内说明](../01_content/README.md)。
|
||
|
||
## 0.5.1 改动与验证边界
|
||
|
||
0.5.0 的精确 engines.dsh 声明没有包含 0.2.1-rc.5，新宿主据此跳过工作台加载。0.5.1 精确增加 rc.5 兼容目标，将结束提醒改为中性“本轮已结束”、摘要限定为助手答复，并修复测试版版本比较及旧缓存造成的降级更新误报。既有安全、传输与存储契约保留；不包含旧会话 HTTP 400 修复，也不对其他插件作兼容豁免。
|
||
|
||
## 兼容范围与已有证据
|
||
|
||
版本声明仅覆盖 DSH **0.2.0-rc.2 / 0.2.1-rc.3 / 0.2.1-rc.5**。以下区分历史候选、隔离页面与用户实际确认，不把版本声明放行等同于功能验收。
|
||
|
||
| 环境 | 已有证据 | 不能外推 |
|
||
| --- | --- | --- |
|
||
| Windows Web / DSH 0.2.0-rc.2、0.2.1-rc.3 | 0.5.0 发布前候选的冷启动、页面、分栏、资源和鉴权隔离检查 | 全部模型任务、审批/子代理、所有自定义站点 |
|
||
| 官方 Windows Desktop / 0.2.1-rc.3 | 历史候选 dev.2 的项目打开、分栏缩放和侧栏设置弹窗获用户确认；新项目前轮已测 | 0.5.1 正式包在此宿主上完成完整桌面端验收 |
|
||
| Windows / Desktop 捆绑的 0.2.1-rc.5 运行时 Web UI | 0.5.1-dev.1 最终候选包在隔离环境通过 15 项 GUI 检查，覆盖入口、绑定、项目创建、分栏、侧栏弹层、身份与预览撤销 | 完整 Electron Desktop、模型任务、原生目录选择、真实审批/子代理与桌面终端全链路 |
|
||
| 官方 Windows Desktop / 0.2.1-rc.5 | 0.5.1-dev.3 安装文件与候选包一致、组件检查通过；用户确认降级更新误报消失、页面看起来正常 | 0.5.1 正式包全功能 GUI 验收、所有控制室业务与模型任务 |
|
||
| 旧 DSH 0.1.x、macOS、社区桌面壳 | 不在当前版本已测支持范围 | 不能因旧兼容分支仍在就声明支持 |
|
||
|
||
0.5.1 正式包须单独通过打包流水线的安装与回归门禁；已有 dev.3 页面确认不替代正式包全功能 GUI 验收。关闭并重新打开正式 DSH 由用户操作，不自动迁移会话或浏览器数据。
|
||
|
||
## 接口与访问身份
|
||
|
||
宿主直接注册的 WebServer 路由不自动继承宿主 API 登录保护。工作台用 `requestAuth.ts` 在每次私有 HTTP 请求及终端升级前调用当前宿主的 `connection.admit(req)`：
|
||
|
||
- 有 principal 的新宿主仅放行 owner；0.2.0 分支仅放行同一 operator 对象且无 principal。
|
||
- 未登录返回 401，非允许身份返回 403；安全服务缺失、抛错或响应不可确认返回 503。
|
||
- 不缓存一次登录为永久授权，不另建插件密码体系；无跳过校验开关。
|
||
- WS 建连后不逐字符重新鉴权；本轮未实现宿主撤权后立即断开已有连接。插件卸载会关闭自己的连接及 Shell。
|
||
|
||
| 路由 | 能力与身份 |
|
||
| --- | --- |
|
||
| GET /api/worktable/health | 公开，仅插件/版本/ok，不证明界面或模型业务通过 |
|
||
| /api/worktable/fs、git、file、write、mkdir、workspaces、template，以及旧 site 路由 | 宿主身份校验；原请求字段保持 |
|
||
| WS /api/worktable/term | 创建 PTY 前校验身份；缺少宿主 ws/node-pty 则降级 |
|
||
| POST /api/worktable/preview | 身份校验后创建/撤销目录预览 |
|
||
| GET/HEAD /api/worktable/preview-static/<临时令牌>/<相对资源> | 令牌允许的只读目录资源，不需宿主登录；令牌是临时访问能力，不能分享或持久保存 |
|
||
|
||
登录的工作台主页面可调用 `POST /api/worktable/preview`，JSON body 为 `{"root":"<绝对目录>"}`。返回 `{token,base}`；用 base 拼接经编码的相对资源路径。撤销使用同一路由及 `{"revoke":"<该次token>"}`。示例只表示字段契约，不提供真实 token。
|
||
|
||
不应从隔离页面访问这个创建接口，也不要为方便 curl 或模型 Shell 直调而关闭鉴权。普通未登录脚本得到 401 是预期变化。
|
||
|
||
## 网页隔离与资源流向
|
||
|
||
1. 客户端保存的是原始目标 URL，不保存临时访问能力。
|
||
2. 本地旧 site URL 被识别后，由主页面先申请只读目录预览；Desktop 通过宿主 Host HTTP 地址取资源，不能把 dsh-app://app 当 HTTP 主机。
|
||
3. browser/anim/iframe 窗格使用 `sandbox="allow-scripts allow-forms allow-downloads"`，不提供 allow-same-origin。
|
||
4. 静态响应附 CSP sandbox、no-store、no-referrer、nosniff 与允许无凭据资源读取的 CORS 头；HTML 不获得访问 DSH 主页面的同源身份。
|
||
|
||
目录先解析真实路径，拒绝已识别的越界路径与目录联接；访问范围包括子目录，并非只允许当前 HTML。页面仍可联网，**不是防外发保证**，不应挂载含敏感文件的目录。
|
||
|
||
读取绑定同一文件句柄，前后核对路径、文件身份（dev/ino）与大小/时间；最多读取 40 MiB + 1 字节用于判超，超限返回 413，替换/改写或读取中撤销则不返回内容。测试覆盖单次目录联接替换、文件替换和检查后增长。这是隔离网页的只读访问边界加固，不承诺抵御另一个恶意本地进程精确配合的 ABA 路径交换；不应将本插件作为限制本地 Agent/进程文件权限的操作系统沙箱。多个并发请求仍可能累积内存，40 MiB 不是总内存额度。
|
||
|
||
限制：最多 128 个挂载、每个资源最多 40 MiB、30 分钟闲置过期。关闭具体标签、刷新替换或卸载会撤销；项目切换/关闭沿用最多 6 个项目的保活池，不立即销毁其中仍挂载的页面。过期后刷新窗格重新申请。
|
||
|
||
## 对页面开发者的影响
|
||
|
||
- localStorage、IndexedDB、Cookie 登录、同源 fetch、页面内 iframe/object、弹窗/顶层跳转与标注自动取字可能受限。
|
||
- 相对 CSS、JS module 和 JSON fetch 已在夹具页面验证；不能据此保证所有前端库。
|
||
- **WebGL/Canvas 图片纹理**还要求图片请求与响应满足跨源条件。仅服务器返回 CORS 头未必足够；加载图片的代码/库也需正确请求。StarMap 的月球纹理路径已在其独立项目中通过 Blob 图片加载与保留隔离修复、验证；这不是工作台包内修复，也不证明所有旧网页纹理都已兼容。
|
||
- 自动标注可退为窗口级坐标/用户描述，不承诺从隔离 DOM 获取文字。
|
||
- React 组件插件与宿主权限是另一条边界；iframe 隔离不等同把所有已安装插件变成不可信代码沙箱。
|
||
|
||
## 常见故障
|
||
|
||
| 表现 | 检查与处置 |
|
||
| --- | --- |
|
||
| 401 / 403 | 在宿主主界面确认当前身份；不要复制浏览器凭据给脚本 |
|
||
| 503 Host authentication unavailable | 核对 DSH/插件版本与 connection 服务；不开放路由兜底 |
|
||
| 预览 400 | 查看目录是否绝对、存在且为目录，或是否超过挂载数量；创建仅接受 POST |
|
||
| 预览 404 | 可能已撤销、过期、文件不存在或越界；刷新后重试合法资源 |
|
||
| 413 | 预览资源超过 40 MiB；普通 file 路由上限为 20 MiB |
|
||
| WebGL texImage2D SecurityError | 记录具体纹理 URL、网络请求及完整错误，检查图片跨源加载，不去掉 sandbox |
|
||
| 收起侧栏后弹窗不见/出现双份 | 弹层必须共用一份，宽/窄各引用一次；运行 sidebar-popup 回归 |
|
||
| 拖动/缩放后分栏关闭 | 检查 CSSOM 读回基线与换根观察器；运行 anchor-dom 与 split-margin |
|
||
| link 安装终端不可用 | 核对实际宿主打包结构与 ABI；不能直接套社区桌面 resources/app 路径 |
|
||
|
||
## 回归与发布
|
||
|
||
从 `01_content` 执行 `npm run pack`；它评估最终临时安装包中的客户端工厂、锚点、弹层与真实 Chromium margin，并核对服务端数据目录和双资产 SHA。单独运行：
|
||
|
||
- `npm run test:sidebar`：当前构建产物的弹层回归；脚本可直接接受任意 client.js 路径。
|
||
- `node ../04_test/anchor-dom.test.mjs [client.js]`：14 场景，含 PR #16 的 6 个小数几何补充。
|
||
- `node ../04_test/split-margin.test.mjs [client.js]`：5 个真实 Chromium 场景。
|
||
- `npm run test:security`：鉴权、只读预览及生命周期；不等于完整渗透测试。
|
||
|
||
正式版本/公告需同步；源码、包内 README 或版本变化后必须重新打包。最终包验收通过并获得发布授权后上传，随后按最终 SHA 跑 verify:remote 并核对指定 tag 与 latest；同 tag 资产不覆盖。
|