@mokuyoaxis/dsh-iris 0.1.0

package/docs/file-access-across-environments.md

@@ -0,0 +1,78 @@
+# 文件访问与跨环境
+
+Iris 可以从浏览器上传、会话附件或宿主文件路径读取媒体。三种方式适合的场景不同；如果不确定，优先使用上传。
+
+## 推荐顺序
+
+1. **浏览器上传**
+   适合图片、音频和中小型视频。文件内容会传到运行 DeepSeek Harness 的宿主，因此不要求浏览器和宿主共享文件系统。
+
+2. **会话附件**
+   适合复用当前会话中已有的图片或 Iris 生成的产物。附件引用比手动复制路径更稳定。
+
+3. **宿主路径**
+   适合宿主本地的大文件，可以避免再次复制。路径必须从宿主进程的视角填写，浏览器能看到并不代表宿主也能读取。
+
+## 环境差异
+
+| 环境 | 推荐方式 | 路径注意事项 |
+|---|---|---|
+| 原生 Linux | 上传、附件或宿主路径 | 浏览器与宿主通常共享同一文件系统 |
+| 原生 Windows | 上传、附件或宿主路径 | 使用 Windows 绝对路径，例如 `C:\Media\video.mp4` |
+| WSL | 优先上传或附件 | Windows 文件在 WSL 中通常映射为 `/mnt/c/...`，不能直接使用 Windows 路径 |
+| 容器或远程宿主 | 上传或附件 | 浏览器本地路径通常对远端进程不可见 |
+| Android + PRoot | 优先上传 | 共享存储是否可读取决于挂载方式和 Android 权限 |
+
+浏览器文件选择器交给 Iris 的是文件内容，而不是一个可供宿主读取的本地路径。因此，它也适用于 WSL、远程部署和 Android 文件选择器返回 `content://` URI 的情况。
+
+## 上传文件
+
+上传文件保存在：
+
+    $DSH_HOME/iris/v1/uploads/
+
+上传流程具有以下约束：
+
+- 单文件上限为 64 MB。
+- 数据以流式方式写入，不会先完整缓存在内存中。
+- 写入期间使用 `.part` 临时文件，成功后再原子改名。
+- 文件权限设为 0600。
+- 中断、超限或失败时会清理临时文件。
+- 上传副本默认保留 7 天，并在插件启动或后续上传时清理过期内容。
+
+上传目录是 Iris 的工作目录，不是长期归档位置。需要长期保留的原始文件应继续存放在用户自己的文件库中。
+
+## 会话附件
+
+文件选择器会列出当前会话可用的附件，包括较早的任务产物。选择附件后，Iris 会解析其持久引用或导出为宿主可读文件，再交给对应工具。
+
+如果附件已经从宿主存储中删除，只有历史任务记录并不能恢复文件内容，此时需要重新上传原文件。
+
+## 宿主路径
+
+选择宿主路径时，请先确认：
+
+- 路径是绝对路径。
+- DeepSeek Harness 进程有读取权限。
+- 路径属于宿主文件系统，而不是浏览器所在设备的文件系统。
+- 大文件所在磁盘有足够的读取性能和临时处理空间。
+
+在 WSL 中，Windows 文件 `C:\Media\video.mp4` 通常应写成 `/mnt/c/Media/video.mp4`。在容器部署中，还需要确保目标目录已经挂载到容器内。
+
+## 常见问题
+
+### 为什么网页里选到的路径不能直接使用？
+
+现代浏览器不会把可供服务器读取的真实本地路径交给网页。文件选择器通过上传文件内容解决这一问题。
+
+### 大视频应该上传还是填路径？
+
+宿主本地文件优先填路径，可以避免复制。浏览器与宿主不在同一环境时只能上传，必要时应先调整部署侧的上传限制。
+
+### 上传后的文件为什么不在相册或下载目录？
+
+上传副本保存在 Iris 的私有工作目录中，供工具读取。它不会自动写回浏览器设备的相册或下载目录。
+
+### HTML 或表单中能否直接使用 `content://`？
+
+不能把 `content://` 当作宿主路径读取。应通过浏览器文件选择器上传，由浏览器负责读取该 URI 对应的内容。