local-file-organizer

Local File Organizer

The deliverable of organizing is not "looking tidy," but a system that is explainable, rollback-capable, and maintainable going forward.

Choose a branch

Only follow the branch the user needs, and stop once it is complete:

• Inventory: read-only inspection with a proposed structure, naming, and cleanup plan.
• Execute: after inventory, move, rename, or deduplicate according to the authorized change ledger.
• Review: only when the user explicitly requests it, extract life and work threads from the inspected materials. Read review rules; do not generate automatically just because files were organized.

Choose organizing depth

• Standard mode: suitable for quick sorting or very large volumes of homogeneous material; grouping by explainable rules is allowed.
• Atomic deep mode: recurse to the safe minimum unit, understanding, classifying, and naming each file individually. Use when the user requests "deep sorting," "break everything down," "down to each individual file," or does not preserve the original directory; this mode prohibits substituting sampling for item-by-item conclusions.

The safe minimum unit is usually a single file; code repositories, application bundles, photo libraries, design projects, media projects, or dependency directories with internal path references areintegrity packages. First treat an integrity package as one atom; only after the user explicitly authorizes unpacking should its internal files be analyzed further.

Safety contract

• First resolve the target's absolute path, exclusions, and the purpose of each space. Existing directories are clues, not classification truth.
• Keep reversible by default. Put uncertain items into Review or PendingDelete; prefer the system trash when available.
• Separately flag symbolic links, hard links, cloud placeholder files, integrity packages, permission boundaries, and cross-volume moves.
• Distinguish content ownership from filesystem ownership. By default preserve UID/GID, ACLs, permissions, extended attributes, and time information; organizing does not constitute chown、chmod or authorization to transfer rights.
• Read only the minimum content needed to complete classification. Omit sensitive details such as ID numbers, addresses, accounts, health, and contracts from reports.
• Permanent deletion requires separate authorization for explicitly specified categories in the current inventory. "Clean it up" does not constitute deletion authorization.
• For cross-volume or cloud drive operations, copy and verify first, then handle the source files; until the destination is verified, the source files remain unchanged.

Workflow

1. Establish the space contract

Determine one primary responsibility for each root directory, such as CurrentWork、Inbox、Archive、 MediaWork or PersonalVault. If the responsibility cannot be reliably determined from the request, provide 2–3 options in plain text, marking the recommended one and a one-sentence tradeoff.

Record:

• Target and exclusion paths
• Space responsibilities
• Whether the user wants inventory, execution, or review
• Standard mode or atomic deep mode
• Acceptable scope for renaming, moving, and deletion

Completion criteria: each root directory has only one primary responsibility, and boundaries and authorization are unambiguous.

2. Establish the evidence inventory

Start with a read-only inventory. Go deeper step by step along the evidence ladder, and stop once the evidence is sufficient to determine purpose:

1. Original path, name, type, logical size, and time;
2. UID/GID, permissions, ACLs, extended attributes, links, and cloud status;
3. Format metadata such as EXIF, media tags, document properties, PDF metadata, and project manifests;
4. Content inspection such as text extraction, OCR, image visual analysis, and audio/video transcription;
5. Relationships with adjacent files, versions, projects, and timelines.

• First determine the actual purpose, then decide the destination; the original directory name only provides context.
• Record content ownership/rights and technical owner separately. Content ownership may use Personal、Employer/Company、Client/Collaborator、Family/Shared、 ThirdParty/Licensed or Unknown, and adjust according to the actual materials.
• Standard mode may create evidence groups for homogeneous files, but deletion decisions must not rely on sampling.
• Atomic deep mode recursively enumerates every leaf file and integrity package; each item is recorded separately, and no vague grouping such as "not read because there are too many" is retained.
• Similar file names only produce "suspected duplicates"; only after sizes match and content hashes confirm them are they "exact duplicates."
• Similar photos, different exports, draft versions, and in-project copies are independent review items and are not merged into exact duplicates.

Completion criteria: in standard mode, every item is recorded or falls into a rule-based, quantified evidence group; in atomic deep mode, every leaf file or un-split integrity package has a stable ID, purpose, content ownership, evidence, proposed name, and target location. Items that cannot be determined, such as permissions, encryption, or corruption, are explicitly marked as Unknown, and must not be silently skipped.

3. Sharded read-only analysis

When the number of files is large, formats are diverse, and the host supports sub-agents, content judgment can be divided into non-overlapping read-only batches:

• The main agent first freezes the scope, classification vocabulary, stable IDs, and output fields, then slices by directory, format, or time.
• Each sub-agent receives only the necessary context rather than the full conversation history, reads the assigned list, and returns evidence, purpose, content ownership/rights, suggested name, target location, confidence, and open questions.
• Sub-agents do not move, rename, or delete files, nor do they expand the scope on their own.
• The main agent merges the single ledger and reviews low-confidence, sensitive, conflicting, and high-risk items.

Completion criteria: all shards have returned or explicitly failed; IDs have no omissions and no overlaps; conflicts are adjudicated uniformly by the main agent.

4. Design structure and change ledger

Each directory level uses only one primary retrieval axis:

1. The root level is by spatial responsibility;
2. The next level is by domain or project;
3. Only when time is the primary retrieval method should it be layered by time.

In atomic deep mode, original paths are retained only in evidence and rollback mappings, and are not inherited as the target structure. Re-aggregate by actual purpose, content ownership, and retrieval method, avoiding mixing "company, project, person, time" in the same level where they compete.

Follow the user's existing concise naming style. Use it only when fixed sorting or bilingual recognition is truly needed NN_EnglishTag_中文说明; date directories use YYYYMMDD_主题. File renaming is based on identifiable subject, date, project, or content ownership, and preserves extensions; names inside integrity packages are not changed without authorization.

First submit the target tree and change ledger. The ledger must at least include:

ID	Source	Purpose	Content ownership/rights	Technical owner	Suggested name/target	Evidence/confidence	Action	Risk/reversibility	Size

Additional list:

• Complete duplicates, suspected duplicates, generated artifacts/cache, expired candidates;
• Naming conflicts, package boundaries, cross-volume or cloud projects;
• Items explicitly retained, not yet handled, and requiring confirmation;
• Rollback method and estimated space to be freed.

Completion criteria: each action has a unique target; coverage, same-name conflicts, and high-risk items have handling decisions; all pending items remain unchanged.

5. Pass the authorization gate

• The user only requested an inventory or plan: remain read-only.
• The user has explicitly requested execution, and the ledger falls entirely within the confirmed boundaries: reversible actions may be executed.
• The scope, classification strategy, or target location has materially changed: confirm the updated ledger first.
• Permanent deletion: show the specific category, file count, path range, and logical size, and execute only after obtaining separate authorization.

Authorization covers only the current ledger. New actions return to this step.

6. Execute in batches and verify

Before the first change, save the item-by-item source-to-target mapping to the target space or a user-specified persistent log location. Then:

1. Check target volume space, write permissions, and whether the target has no overwrite conflicts;
2. Create target directories;
3. Execute low-risk moves and renames in small batches, updating the ledger after each batch and verifying owners, permissions, and extended attributes;
4. After cross-volume file copies, verify counts, sizes, and key metadata; for key files or complete duplicates, also verify hashes;
5. For uncertain items, preserve relative paths and move them to a review area;
6. Only after all descendants have been accounted for and the directory is confirmed empty, clean up old empty directories as authorized;
7. When encountering target changes, verification failures, permission anomalies, or unplanned conflicts, stop the affected batch.

When encountering overwrite conflicts, preserve both source and target and record them; distinguish partial success from full success according to the ledger status.

Completion criteria: every item in the ledger has 完成、失败 or 未执行 status; the targets of completed items actually exist, cross-volume copies have been verified, and the source files of failed items remain recoverable.

7. Close out

Report:

• The counts and locations of completed, failed, not executed, and intentionally retained items;
• The content ownership/rights category of each item,Unknown items and technical owner anomalies;
• The handling results for complete duplicates, suspected duplicates, and deletion candidates;
• The method to roll back or restore from the trash;
• Usage rules for the new structure and the minimal next step.

Distinguish space accounting:

• Files still on disk, in the review area, or in the trash:待释放空间；
• Already permanently removed:已删除的逻辑大小；
• Only after measurement through the file system may it be called实际释放空间。