Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/beclab/olares --skill olares-filesAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
files (per-user files-backend)
Shared front door: load `../olares-shared/SKILL.md` for suite routing, active-profile selection, platform entry points, and the auth proceed/stop gate. Load its auth reference only when login, profile switching, token storage, or auth recovery is actually needed.
Load the shared platform model when the task depends on userspace backends, durability, uid 1000, or system-managed Home directories. Use olares-cli files <verb> --help for syntax.
When to use
- Address, read, write, move, delete, share, or transfer known Olares file paths.
- Compress/extract or manage their asynchronous task queue.
- Mount SMB/NFS servers or manage Seafile repositories.
Finding files by name/content (and what the index covers — filenames everywhere vs. full-text only in/Documents/) lives in `olares-search`; configure which directories get full-text indexing viasettings search dirsin `olares-settings`.
Fast paths
| Task | Read | First command |
|---|---|---|
| Put a local file in the user's Drive | collision decisions and cloud transfer | olares-cli files upload ./report.pdf drive/Home/Documents/ |
| See what is in a directory | this file | olares-cli files ls drive/Home/ -o json |
| Read one file's bytes | this file | olares-cli files cat drive/Home/Documents/report.pdf |
Address anything outside drive/Home | path grammar and namespace rules | olares-cli files ls sync/<repo_id>/ |
Paths and namespace support
Every resource is fileType/extend[/subPath], where fileType is one of drive, cache, sync, external, awss3, dropbox, google, tencent, share, internal, and extend is the volume, repo or account inside it — drive/Home, drive/Data, drive/Common, a node name, a Seafile repo id, a cloud account key. That much covers an ordinary Drive path.
Load path grammar and namespace rules when the target is outside drive/, or when you need to know whether the verb you are about to run supports that namespace at all — support is per verb, and several verbs refuse namespaces their neighbours accept.
Backend quirks that change decisions
- Directory creation may auto-rename on collision instead of returning conflict. Upload does not pre-create destination directories. If exact naming matters, inspect the parent and create it deliberately.
- Direct raw GET of a file resource may return HTTP 500. Use
files catorfiles download; do not retry the raw resource URL. external/<node>/is a virtual volume picker, not a write destination. Writes needexternal/<node>/<volume>/....- Eleven reserved names are system-managed at the first level under
drive/Home/.rename,rm, andmvas a source are refused before any request goes out;cpand everything nested stay editable. The refusal enumerates all eleven and is a platform invariant, not a permission error to retry — act on a child instead. The names are matched exactly, so a name that merely looks similar is not protected. cache/<node>/is valid storage but not a concrete dataset for share creation; sharecache/<node>/<sub>/.
Async task queue (compress / extract)
compressandextractenqueue server-side work and return a task id unless waiting.- Ctrl-C stops only the local poll. Cancel the server task explicitly if that is the user's intent.
- Tasks are per-node; retain the node printed when the task was queued.
task cancel --allaffects every task on the node, including work started elsewhere.
Version gate (Olares >= 1.12.6)
Archives, NFS, and drive/Common require Olares 1.12.6+. Treat daily builds by their major.minor.patch base. Follow the shared auth/version gate when the backend version cannot be established.
Verb index
| Verb | Read when triggered |
|---|---|
ls | listing and cloud shapes |
cat | Raw bytes to stdout, and the supported way to read one: a direct GET of the file resource answers 500 |
download | resume, overwrite, directory downloads |
upload | collision decisions, resume, concurrency; the second stage a cloud destination adds |
edit | text/size guards and writeback |
mkdir | parents, auto-rename, external depth |
rm | existence, directory intent, protected paths |
rename | in-place rename and protected paths |
cp, mv | destination and overwrite semantics |
chown | UID and namespace decisions |
compress | formats, conflicts, passwords, async task |
extract | destination, conflicts, passwords, async task |
archive | read-only archive inspection |
task | per-node cancel/pause/resume |
share | internal/public/SMB sharing |
smb | discovery, mount, history |
nfs | export discovery and mount |
repos | Sync (Seafile) libraries by id; the repo id is what a sync/ path is built from |
Safety and escalation
- Treat the user's requested file operation and named paths as task-scope authorisation. Ask again only when a target is ambiguous, bytes may be overwritten without explicit intent, deletion expands beyond the named target, or the action leaves that scope.
- For upload, first decide whether collision should overwrite, fail, or create a distinct name; backend auto-renaming is not an acceptable implicit decision.
- Do not retry a missing-path preflight by weakening safety flags.
- Confirm
task cancel --allseparately because it affects unrelated work on that node. - Never expose tokens or passwords. Use stdin-based secret input where available.
- Stop on ambiguous frontend paths, node/volume identity, overwrite intent, or concurrent deletion; re-list the parent and ask the user.
