用途与实际影响
这项功能怎样使用
为什么需要它
项目任务需要防止根目录被替换或越界；所有者文件管理又不能因为任务不在某个项目里就失去用户本来拥有的磁盘权限。把两者混在一起会既不安全又不好用。
举个实际例子
我想从手机把另一块磁盘上的文件加进任务，目标位置却已有同名文件。历史产品会停下来让我明确是否覆盖；当前 Remote 冻结不可用，本页只展示当时的文件边界和图证，不浏览、上传、复制或删除任何真实文件。
最后我会得到什么
可阅读旧版文件范围、覆盖确认与删除边界；当前不会从手机读取、上传、移动或删除任何真实文件。
正常时
历史上，选定项目、文件位置和覆盖选择都确认后才执行文件动作。
发现问题时
旧设计遇到同名文件或被占用文件会停下交回实际结果；当前不查询文件。
入口不可用或证据不足时
当前控制入口冻结且不可用，只能阅读获准的历史材料；恢复须由本人另行明确启动独立项目并重新验收。
从哪里开始
当前入口冻结且不可用，不能在手机浏览、上传或修改电脑文件；本页只保留历史文件工作台范围。
需要准备什么
- 想了解的历史项目或文件场景；当前不能读写
从开始到拿到结果
- 1
历史先选根
原设计按登记项目或隔离无项目工作区限定文件范围。
- 2
历史逐文件确认
预览、上传、编辑、移动和删除曾要求具体路径及覆盖选择，并在动作后重新列目录。
- 3
当前无文件动作
冻结期间不读真实文件，也不因历史记录推断临时文件还能取回。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
当前控制入口不可用且冻结；文件合同、操作测试和历史上传 SHA 证据保留，不通过 Remote 浏览或修改本机文件关键规则与设计选择
任务项目根和所有者文件根使用不同身份。
浏览器只发送 opaque root id 与相对路径。
同名目标默认冲突，覆盖必须明确选择。
删除默认进入回收站，永久删除单独确认。
本模块用到的名词
- registered project（已登记项目）
- 由本机明确记录 canonical root 的任务工作区。
- opaque root id（不透明根标识）
- 浏览器使用的磁盘/根引用，不直接把绝对根路径当 API 参数。
- path traversal（路径越界）
- 使用 ..、设备路径、junction（目录联接） 等逃离获准根的尝试。
- recycle-bin deletion（回收站删除）
- 默认可恢复删除；永久删除需要额外明确确认。
专业定义
历史设计分开登记项目/无项目任务与 Windows 所有者文件工作台；当前冻结，浏览、预览、上传、编辑、移动和删除均不可调用。
解决什么
解决路径 traversal、junction（目录联接） 逃逸、绝对路径裸链、无意覆盖、永久删除误触和项目权限与电脑权限混写。
当前怎样实现
- project access 绑定登记时的 canonical path 与目录身份；根漂移后拒绝新任务。
- host-files 枚举当前 Windows 身份可访问磁盘，不额外按扩展名或隐藏属性降权。
- 路径层拒绝绝对路径、UNC、设备路径、ADS、保留名称和 ..。
- 文本、Markdown、图片和 PDF 使用有界预览；下载仍需登录。
- 任务正文绝对路径换成短时 opaque grant，再通过认证解析。
执行流程
- 1
以下是已保留源码所定义的历史流程，用于理解曾经做成的能力，不是当前操作步骤；运行时冻结期间不执行、不探测，也不因旧测试或截图解除冻结。
- 2
选择登记项目或无项目任务。
- 3
校验项目根的路径和目录身份。
- 4
在文件页选择 root id 和相对路径。
- 5
预览或准备上传、编辑、复制、移动。
- 6
遇到同名目标时取得明确覆盖选择。
- 7
删除优先进入回收站。
- 8
动作完成后重新列目录并核对结果。
边界
- 当前控制入口不可用且冻结：不调用 Status、Open、Close、重启、登记、回滚、dispatcher（分派器）、计划任务、Sidecar（认证侧车）、Broker（共享代理）或公网端点，也不走替代启动路径。仅可只读查看获准的具名源码、文档、测试定义与历史图片；恢复须由用户另行明确启动独立项目并重新完成端到端验收。
- 文件工作台不是任务 sandbox，也不是多用户权限系统。
- Windows ACL、BitLocker、挂载和占用仍决定真实结果。
- 临时文件已被系统删除时，历史消息不能恢复其字节。
- 不公开真实私人文件内容或可复用授权。
失败与恢复
- 当前入口冻结
- 当前控制入口不可用且冻结：不调用 Status、Open、Close、重启、登记、回滚、dispatcher（分派器）、计划任务、Sidecar（认证侧车）、Broker（共享代理）或公网端点，也不走替代启动路径。仅可只读查看获准的具名源码、文档、测试定义与历史图片；恢复须由用户另行明确启动独立项目并重新完成端到端验收。
- 项目根身份漂移
- 拒绝在该根创建新任务，要求本机重新登记。
- 同名目标存在
- 返回冲突，等待明确覆盖或改名。
- 跨盘移动中断
- 保留源，回读目标和临时状态后再决定。
- 短时文件授权过期
- 拒绝下载，重新从已登录文件页生成。
真实入口
apps/sidecar/src/host-files.ts实现所有者文件枚举、路径解析、预览和写动作。
apps/sidecar/src/host-files.test.ts覆盖隐藏文件、全部写操作、越界、覆盖、删除、预览与下载。
apps/web/src/file-link.ts解析任务中的文件引用与短时授权。
如何验证
- host-files 测试覆盖 create/edit/upload/rename/copy/move/overwrite/recycle/permanent delete。
- 历史真实验收核对过浏览器上传 PNG 的 bytes 与 SHA-256。
- 本轮只使用公开源码和获准截图，没有访问真实本机文件 API。
与其他模块的关系
它把任务工作区与所有者文件能力分开；共享架构负责传递操作，安全模块负责会话、路径、覆盖与删除确认。