Nocobase File Manager

Goal

Configure and use NocoBase file storage safely from the user's point of view: choose a storage engine, create or update it, model first-class file collections, relate business records to those files, and verify storage and file lifecycle behavior through supported nb api commands.

Scope

• Inspect, create, update, verify, and safely delete local, s3, ali-oss, tx-cos, and optional s3-compatible (S3 Pro) storage records.
• Explain NocoBase URL, original URL, public access, signed URL, upload rules, renaming, default storage, and physical-file retention.
• Inspect, create, and verify a template: "file" collection and ordinary relation fields that point to it.
• Inspect, create metadata for, update, list, and safely delete records in file collections.
• Use nb api resource for ordinary resource CRUD and the high-level data-modeling commands for file collections and relations.
• Read the live file-manager Swagger before relying on optional or version-specific actions.

Non-Goals

• Do not create new fields with the deprecated attachment interface or model new business data against the shared attachments collection.
• Do not handle generic collection/relation modeling whose primary intent is unrelated to file storage.
• Do not delete file collections or relation fields; use the data-modeling workflow after their dependencies and migration impact are explicitly scoped.
• Do not migrate physical objects between storage backends, rewrite historical object keys, or mutate the database directly.
• Do not configure an object-storage provider's bucket, IAM policy, DNS, CDN, or CORS outside NocoBase.
• Do not invent a binary-upload nb api resource flag; generic resource create accepts JSON records, not local file bytes.
• Do not use curl or direct HTTP while an applicable nb api command exists.
• Do not expose, echo, or persist plaintext access keys in command arguments, logs, generated files, or final output.

Input Contract

Rules:

• Valid action-target combinations are:
  • storage: inspect/create/update/verify/delete;
  • file-collection: inspect/create/verify;
  • relation: inspect/create/verify;
  • file-record: inspect/finalize/update/verify/delete.
• Reject any other combination instead of reinterpreting it as a nearby operation.
• If a required input or capability is missing, stop mutation and ask for it.
• If the user says "you decide", inspect only; do not create storage, change access, alter defaults, create relations, or delete records.
• Resolve identifiers from live list/get results. Never guess storage IDs, collection names, field names, or record IDs.
• Never translate a request for files into interface: "attachment". Create a file collection first, then create an ordinary relation to it.
• Treat nb api resource create --resource <fileCollection> as metadata finalization only when the object already exists in storage; it is not a binary upload.

Mandatory Clarification Gate

• Max clarification rounds: 2.
• Max questions per round: 3.
• Before any mutation, confirm environment, exact target, current state, intended result, and required plugin capability.
• Before storage create/update, confirm that credential values are environment placeholders such as {{env.FILE_S3_SECRET_ACCESS_KEY}}, never plaintext.
• Before changing default, URL mode, public access, signed-URL behavior, storage binding, paranoid, rename mode, path, or upload rules, show the exact access or lifecycle impact and obtain fresh secondary confirmation.
• Before every storage or file-record deletion, show the exact target, referencing file collections/records, physical-object impact, and rollback limit, then obtain fresh secondary confirmation immediately before that deletion.
• If live Swagger, nb api resource, data-modeling commands, authentication, or the required storage type is unavailable, stop before writing.

Workflow

1. Resolve the action-target combination, environment, exact identifier, required inputs, and installed capability. Reject unsupported combinations before any mutation.
2. Run nb env current, nb env update <env> --verbose, and only the relevant --help commands. Fetch plugins/file-manager Swagger only for optional or version-specific behavior.
3. Load references by task:
   • storage inspection/configuration: command map, plus storage engines only when choosing or configuring an engine;
   • file collection/relation work: command map and file modeling;
   • file-record CRUD: the file-record section of command map;
   • access, lifecycle, deletion, or troubleshooting: operations and safety plus the relevant command section.
4. Inspect only the current state needed for the chosen target. Exclude secret-bearing storage fields, resolve identifiers uniquely, and capture safe rollback state before mutation.
5. Execute the selected supported operation: storage CRUD, file collection/relation creation, or file-record inspect/finalize/update/delete. Never delete a file collection or relation field through this skill.
6. If the user asks to upload local bytes, inspect live Swagger/CLI help. When no generated multipart command exists, direct them to the NocoBase UI or report the external/direct-upload requirement; do not treat JSON record creation as upload.
7. Read back every write and verify only the applicable collection template, storage, relation keys, file storageId, URL behavior, rules, and physical-deletion expectations.
8. Report API success separately from object-storage reachability or asynchronous external behavior.

Reference Loading Map

Safety Gate

High-impact actions:

• deleting a storage engine or file record;
• changing the default storage or a file collection's storage binding;
• changing NocoBase URL/original URL, public access, or S3 Pro signed-URL behavior;
• changing paranoid, rename mode none, storage path, MIME rules, or size limits;
• creating/updating credential-bearing storage options;
• finalizing a file record for an externally uploaded object.

File collection and relation deletion are outside this skill and must not be inferred from the generic delete action.

Secondary confirmation template:

• "Confirm execution: <action> on <exact target> in <env>. Expected impact: <access, upload, relation, record, and physical-object impact>. Rollback: <available or unavailable>. Type confirm to continue."

Rollback guidance:

• For create failures, preserve the storage or file record until its dependencies and physical objects are understood; deletion needs its own fresh confirmation.
• For update mismatch, restore the safe fields captured before mutation. Credential values must be re-supplied as environment placeholders.
• A deleted physical object is not restored by recreating its database record. Use an object-store version/snapshot or backup when available.
• Changing a file collection's storage affects later uploads; existing records retain their own storageId. Roll back the collection binding separately from historical records.
• Never claim rollback of an external upload, bucket ACL, CORS rule, CDN cache, or object-store operation performed outside NocoBase.

Verification Checklist

• Target environment is current, reachable, authenticated, and confirmed.
• File manager is enabled; S3 Pro is enabled before using s3-compatible.
• Live storage type, ID, system name, safe fields, and default state are uniquely resolved.
• No plaintext credential appears in argv, logs, temporary files, readback, or output.
• Storage create/update is read back through nb api resource with options and settings excluded.
• Exactly the intended storage is default after a default change.
• File collection readback reports template: "file" and the intended storage system name.
• Business collection uses an ordinary m2o, o2m, or m2m relation targeting the file collection; no new attachment interface exists.
• Relation direction, foreign key, through table, reverse field, and readable title field match the intended ownership.
• Upload rules use bytes for size and valid MIME patterns; a denied file type/size remains denied.
• File record storageId, filename/path semantics, stable URL/original URL choice, and preview behavior match the engine.
• Every write has immediate readback and at least one allowed and one guarded/denied behavior is checked.
• Before deletion, referencing collections and records are inspected and physical-object impact is stated.
• Errors, partial success, external-provider uncertainty, rollback limits, and remaining work are reported separately.

Minimal Test Scenarios

1. Inspect-only: list safe storage fields and file collections without exposing options or mutating data.
2. Happy path: create a local storage with safe values, create a file collection, add an o2m/m2o relation pair, and read all objects back.
3. Missing/invalid input: omit storage type, relation ownership, or exact identifier, or request an invalid action-target pair, and verify mutation is blocked.
4. Auth/capability failure: file-manager/S3 Pro, Swagger, or API authorization is unavailable and the skill stops with recovery guidance.
5. High-risk case: request an access-mode/default change or deletion and verify fresh exact-target confirmation is required immediately before execution.

Output Contract

Final response must include:

• target environment, requested action, exact storage/collection/field/record identifiers;
• engine choice and non-secret configuration summary, when applicable;
• commands executed with secrets redacted or represented only as environment placeholders;
• storage, file collection, relation, and file-record readback as applicable;
• URL/access mode, upload rules, retention, and physical-object impact;
• guarded operations, denied cases, partial success, external-provider uncertainty, and rollback limits;
• defaults and assumptions applied, including any CLI binary-upload capability gap.

References

• NocoBase file manager documentation: use when checking current user-facing storage and file collection behavior. [verified: 2026-07-30]
• NocoBase repository: use when checking the current open-source implementation and Swagger contract. [verified: 2026-07-30]
• Command map: use for exact supported CLI operations and readback.
• Storage engines: use for engine selection and payload fields.
• File modeling: use for file collections, relations, and record semantics.
• Operations and safety: use for access, deletion, retention, and troubleshooting.