浏览、预览与上传附件
使用目标
在同一附件管理页查看本地与服务器文件,用分组组织资料,按需下载原件。
开始前
简化服务器设置、自动断点续扫和独立下载页从 LeafLoom 0.1.5 提供。升级前备份知识库并保留原应用数据。附件服务器可选:未配置时文件保存在本机 _attachments,打开 附件管理 并初始化本机目录缓存即可浏览、预览和上传。
远端附件在 设置 → 附件服务器 添加地址、账号和密码,点击 保存并连接。HTTP(S) 地址使用 WebDAV;smb://主机/共享目录/子目录 或 Windows 共享路径使用 SMB2/3,无需选品牌或系统挂载。公网 WebDAV 使用 HTTPS,已有数字内网/VPN HTTP 地址仍可使用。官方客户端桥接仍要求对应客户端及配置端口可用。优先让 Tailscale 显示 direct(避免 DERP 中继);同网时把地址改成 NAS 局域网 IP 与端口。测试连接会显示往返时延。在 附件管理 选 本地 可快速只看本机列表;对远程项用 缓存到本地 写入知识库附件缓存,不会发明新的目录库成员。
成员可切换为服务器资料目录下的 应用写入目录库(…/attachments/v1/members/)。在 同步状态 对当前 NAS 树执行一次 导入现有文件到目录库 后,LeafLoom 不再自动全树发现,只认应用上传/迁移与目录库 pull。导入只登记成员,不会下载原件。配置了默认远程服务器时,中央粘贴/上传会短暂落入 _attachments 并后台晋升:笔记尺寸的图片保留为本机缓存以便正文插图快速打开;较大与非图片暂存会删除本机原件,列表只显示轻量缩略图/预览。其他整文件留在服务器,直到你 缓存到本地 或打开它们。慢链路与断线会退避续跑直到完成;仅认证失败会暂停自动重试。
同一页的 服务器上传与迁移任务 可将本地 _attachments 迁到所选服务器。可按行填写知识库相对路径,留空则预览整个附件目录;已注册 HTML 项目树与设计/项目资源不参与服务器迁移。确认后再执行,失败或断线只对同一任务点 继续此迁移。校验后权威原件在服务器,迁移完成后移除本地原件,保留轻量预览;需要完整本地内容时使用 缓存到本地 或打开文件,清理已下载缓存不删除 NAS 原件。预览若为 0 个文件且只有排除项,展开排除项查看本机规则原因(不是「服务器已有所以扫不到」)。外出用 Tailscale 100.x、小批次(约 50–200 个路径)并防休眠;在家优先局域网地址。详见完整指南。
仍在 _attachments 下的已注册 HTML 项目可用一次性脚本 scripts/localize_html_attachments.py 迁出(默认预览,关闭 LeafLoom 后加 --apply 写入):项目迁到 Web/<名称>/,项目外的中央依赖迁到各项目的 assets/,并改写静态 HTML/CSS 引用;脚本生成的引用会列为阻断项。
多人共用 DUFS 服务器时,每人使用自己的账号目录地址和凭据。管理员配置及保留原密码的 DJ 切换步骤见单容器多账号指南。
操作步骤
- 本地使用本地文件名索引和原件,不读取服务器目录缓存。全部先显示本地附件,再合入已保存的服务器目录,并统一按当前选择排序。服务器及指定服务器只读取各自已保存的目录;打开列表不会初始化索引或扫描服务器。服务器目录不可用时,本地结果保留当前筛选条件并独立分页,重试后回到最新的第一页。外部文件变化在本地索引更新后反映。
- 搜索名称/路径,按类型、排序和网格/列表浏览。分组可手动添加,也可按来源、目录、格式、分类与标签收录。切换时标题更新、旧列表清空并显示加载状态;失败后重试仍读取当前分组。
- 点击 附件信息 查看选中文件,详情默认折叠并记住偏好。图片、PDF、音视频继续使用原有预览;其他格式优先使用已有封面,不下载原附件。无封面或加载失败时提供文件图标与下载入口。 预览和缩略图立即使用有效的本地文件或分段缓存,服务器版本在后台校验;未缓存的内容按需下载。确认版本变化后,后续读取使用新版本,正在返回的内容不会混合不同版本。下载保留原有同步校验。
- 在这里上传或拖入文件,同名原件保留。新笔记、目录和文件导入使用文件目录操作。服务器卡片可编辑、停用或设为新附件默认位置,不会搬动已有附件。
- 点击 同步状态 查看附件数、已扫描/待扫描目录、复用数量与重试情况。本机断点支持断线和重启续扫;自动来源串行运行,每台最多同时读取两个目录。稳定归档目录逐步延长检查间隔,最长一周;上传目录保持约两小时检查,到期子目录独立核对。完整核对 绕过缓存,不下载原文件。
- 在 下载 页查看原件准备与 ZIP 任务。服务器文件校验完成后可保存到设备,暂存容量在下载设置中管理;释放暂存只移除本机临时副本,不删除服务器原件。重命名、移动、回收仍校验引用和版本,服务器支持的操作可能不同。
资料、AI 范围与服务器规则
分类、标签、个人笔记、来源资料与真实封面直接丰富同一文件列表。原固定商品视图由分组替代,兼容商品工具与可选 Unity 采集仍保留。分组和资料通过已验证的服务器记录同步,冲突需明确处理。活动 SQLite、待上传队列与缓存保存在设备应用数据目录,不应当作普通缓存同步或删除。
只在希望 AI 检索的分组中勾选 用于 AI 素材检索;未选择时不回退到全库。AI 可查询资料/预览并请求交付校验过的原件到指定本机目录,不会自动导入 Unity 或验证购买权属。详见完整指南。
服务器根目录或子目录可放可见的 leafloom.ignore,使用 Gitignore 风格规则排除附件。首行必须精确为 # leafloom-ignore v1,子规则和 ! 可重新纳入。读取规则不要求 NAS 写权限;完整成功后应用排除,保留原文件、ID 和既有引用。
通过 MCP 上传普通附件
Base64 一次上传需要包含此改动的源码版或后续版本。
知识库普通附件使用 vault_files_update,设置 request.action="upload"。ChatGPT 优先使用 source="files" 和宿主提供的顶层 files 数组。本地客户端也可用 source="base64"、name、data_base64、原始字节的 sha256 一次上传不超过 2 MiB 的文件;更大的文件使用 begin/chunk/commit。省略 folder 时使用配置的附件目录,也可指定知识库内相对目录,例如 Comics/Project/assets。
先从 vault_index_status 获取 workspace_revision,每次写入使用唯一 operation_id,相同请求重试时保留原 ID。上传结果返回实际路径、大小、SHA-256、版本及 markdown_link,图片另返回 markdown_embed。通过 vault_files 的 stat 和 source_note 获取相对文档的引用,再按当前文档版本写入 Markdown。同名原文件会保留。
如果客户端只显示 Design Studio 导入或飞书临时传输,检查服务端 tools/list 是否包含 vault_files 和 vault_files_update。更新后重启后端,并刷新/重新扫描客户端插件工具目录;仅重启 LeafLoom 不会刷新客户端缓存。另行检查知识库写入权限,无需为普通附件授权飞书。详见 MCP 文件工具。
附件文件类型
在 设置 → 附件服务器 → 附件文件类型 中编辑允许的后缀并点击 保存。本地文件、全部已配置服务器、附件管理上传、编辑器附件插入与 MCP 附件上传共用此白名单。默认包含常用图片(含 SVG)、PDF/Office、音视频、压缩包、字体、电子书和 .unitypackage,默认排除网页、脚本及其他源码;这些文件仍可通过普通文件导入。
后缀可用逗号、空格或换行分隔,PNG 会规范为 .png,自动去重且匹配不区分大小写。支持 .tar.gz 等复合后缀,不接受路径或通配符。留空表示不识别任何附件;恢复默认类型 会填入默认列表,检查后保存。设置按知识库保存在当前设备,不自动跨设备同步。
移除后缀会立即更新已有索引对应的附件列表、分组、AI 素材查询及数量/容量统计。新增后缀后,已有本地索引立即生效,服务器文件在下一次扫描后纳入,可复用目录缓存。服务器 leafloom.ignore 排除规则仍有效,! 不能绕过白名单。原件、资料、ID 和已有链接保留。待提交附件上传会再次检查类型,被禁用时保留恢复字节。附件迁移仍保留既有项目依赖保护和支持格式限制。
后台检查、目录库与扫描范围
启动直接显示已有附件列表。只认应用写入(目录库权威)时,后台主要 pull 成员目录库,不再全树发现;列表不等待该过程。仍处于 目录检查 模式时:上传目录约每 2 小时检查,稳定归档目录间隔可延长到最长一周。LeafLoom 上传后立即更新本机投影。商品资料与分组拉取在空闲时从 2 小时延长到最长 6 小时。传输失败会退避重试并跨断线/重启保留,直到成功或你取消;仅认证失败暂停自动续跑。
导入目录库之后,在 NAS 上用其他工具直接丢入的文件默认不会进列表,除非再次导入或暂时回到目录检查模式。用 立即同步 pull 目录库;完整核对 仅在仍为目录检查模式时可用。
完成后的表现
后台发现保留筛选、选择、滚动与资料草稿。分页快照过期时显示 列表已更新,查看最新内容,不会自动跳回首页。原件仍在原本的本机或服务器位置;概览区分原件与预览缓存,尚未建立本机索引时容量显示未知而不是零。
没有成功时
临时网络失败会自动重试,具体原因默认折叠;重连与当前资料同步状态会替代旧错误。认证失败需更新凭据,失败扫描保留已有记录。升级后首次扫描需建立断点;服务器没有变更日志时仍需定期查询。离线只能打开已有完整缓存,未缓存或部分缓存文件需要连接。
跨设备恢复引用时沿用已有服务器 ID、逻辑根目录和资料库绑定。切换默认上传位置不会自动搬迁原件或资料库。服务器迁移在 设置 → 附件服务器;本机目录整理入口仍隐藏,旧任务记录仍可用于恢复。