olares-files

files（按用户区分的文件后端）

**共享入口：**加载 ../olares-shared/SKILL.md，了解套件路由、活动配置文件选择、平台入口，以及认证继续/停止关卡。仅当确实需要登录、切换配置文件、存储令牌或恢复认证时，才加载其认证参考文档。

如果任务涉及用户空间后端、持久性、uid 1000 或系统管理的 Home 目录，请加载共享的平台模型。使用 olares-cli files <verb> --help 查看语法。

适用场景

• 访问、读取、写入、移动、删除、共享或传输已知的 Olares 文件路径。
• 压缩/解压文件，或管理其异步任务队列。
• 挂载 SMB/NFS 服务，或管理 Seafile 仓库。

按名称/内容查找文件（以及索引范围——文件名覆盖所有位置，还是仅 /Documents/ 中的全文内容）请参阅 olares-search；通过 olares-settings 中的 settings search dirs 配置哪些目录进行全文索引。

快速入口

任务	阅读	首条命令
将本地文件放入用户的 Drive	冲突处理决策与云传输	olares-cli files upload ./report.pdf drive/Home/Documents/
查看目录内容	本文件	olares-cli files ls drive/Home/ -o json
读取单个文件的字节内容	本文件	olares-cli files cat drive/Home/Documents/report.pdf
访问 drive/Home 以外的内容	路径语法与命名空间规则	olares-cli files ls sync/<repo_id>/

路径与命名空间支持

每个资源都采用 fileType/extend[/subPath] 格式，其中 fileType 是 drive、cache、sync、external、awss3、dropbox、google、tencent、share、internal 之一，extend 则是其中的卷、仓库或账户，例如 drive/Home、drive/Data、drive/Common、节点名称、Seafile 仓库 ID 或云账户密钥。普通 Drive 路径只需了解这些内容。

如果目标位于 drive/ 之外，或者需要确认即将运行的动词是否支持该命名空间，请加载路径语法与命名空间规则——支持情况因动词而异，且有些动词不支持其相邻动词接受的命名空间。

会影响决策的后端特性

• 目录创建遇到重名时可能自动重命名，而不是返回冲突。上传不会预先创建目标目录。如果名称必须精确匹配，请检查父目录并主动创建目录。
• **直接对文件资源执行原始 GET 可能返回 HTTP 500。**请使用 files cat 或 files download；不要重试原始资源 URL。
• external/<node>/ 是虚拟卷选择器，不能作为写入目标。写入需要使用 external/<node>/<volume>/...。
• drive/Home/ 下的第一级目录中有十一个保留名称由系统管理。发出请求前，rename、rm 和作为源路径的 mv 都会被拒绝；cp 和所有嵌套内容仍可编辑。拒绝提示会列出全部十一个名称。这是平台不变量，不是可通过重试解决的权限错误——请改为操作子项。名称按完全匹配判断，因此仅仅看起来相似的名称不会受到保护。
• cache/<node>/ 是有效存储位置，但不能作为创建共享的具体数据集；请共享 cache/<node>/<sub>/。

异步任务队列（压缩/解压）

• compress 和 extract 会将工作加入服务端队列；除非指定等待，否则会返回任务 ID。
• Ctrl-C 只会停止本地轮询。如果用户想取消任务，请显式取消服务端任务。
• 任务按节点区分；请保留任务入队时显示的节点名称。
• task cancel --all 会影响该节点上的所有任务，包括从其他位置启动的任务。

版本门槛（Olares >= 1.12.6）

归档、NFS 和 drive/Common 需要 Olares 1.12.6+。将每日构建版本视为其 major.minor.patch 基础版本。无法确认后端版本时，请遵循通用的身份验证/版本门槛。

动词索引

动词	触发时阅读
ls	列表和云端路径形式
cat	将原始字节输出到标准输出，以及读取文件的受支持方式：直接 GET 文件资源会返回 500
download	续传、覆盖、目录下载
upload	冲突处理、续传、并发；云端目标地址增加的第二阶段
edit	文本/大小限制和写回
mkdir	父目录、自动重命名、外部深度
rm	存在性、目录意图、受保护路径
rename	就地重命名和受保护路径
cp, mv	目标地址和覆盖语义
chown	UID 和命名空间决策
compress	格式、冲突、密码、异步任务
extract	目标地址、冲突、密码、异步任务
archive	只读归档检查
task	按节点取消/暂停/恢复
share	内部/公开/SMB 共享
smb	发现、挂载、历史记录
nfs	导出发现和挂载
repos	按 ID 同步（Seafile）库；sync/ 路径由仓库 ID 构建

安全与升级处理

• 将用户请求的文件操作和指定路径视为任务范围内的授权。仅当目标含糊不清、可能在未明确授权的情况下覆盖字节、删除范围超出指定目标，或操作超出该范围时，才再次询问。
• 对于上传，首先决定遇到冲突时应覆盖、失败还是创建不同名称；不得将后端自动重命名作为默认决策。
• 路径预检未找到目标时，不要通过放宽安全标记来重试。
• 单独确认 task cancel --all，因为它会影响该节点上的其他无关工作。
• 切勿泄露令牌或密码。可用时，通过基于 stdin 的方式输入机密信息。
• 遇到前端路径、节点/卷身份、覆盖意图或并发删除存在歧义时，请停止操作；重新列出父目录并询问用户。