多格式文件转 Markdown｜AI 阅读优化器

概述

Local File to Markdown for WorkBuddy

Locally preprocess only the files the user supplied or roots they explicitly authorized. The Markdown is private task scratch for WorkBuddy reading, not a persistent conversion product.

First activation in every new task

Run python scripts/local_reader.py probe before handling input. Use its capabilities.converters list as the complete current-format list; never replace it with a static or theoretical list.

Then give the full onboarding once:

• Conversion and preprocessing use local scripts and verified on-device capabilities. They do not call independent cloud conversion, OCR, or transcription services.
• WorkBuddy receives the files, and the selected model reads the prepared Markdown under WorkBuddy's, the model provider's, and the user's account policies. With a cloud model, relevant content may be sent to that model. Local preprocessing does not make model inference local.
• Source files are read only. Nothing is written beside them or anywhere in their directory tree. Normal completion, ordinary failure, and confirmed cancellation clean task scratch automatically. If process-tree termination cannot be confirmed, report cleanup-pending and preserve authenticated scratch for later guarded cleanup.
• Show exactly the formats returned by this probe. Mention native OCR/transcription only if the corresponding extensions are present.
• Say that normalization may improve reading, locating, and reuse efficiency and may reduce unnecessary Token or credit use. Never promise a saving, percentage, speedup, or benefit for every format.
• Give examples: summarize an uploaded document; search an explicitly authorized document folder; transcribe a .wav recording only when the probe advertises .wav. Compressed audio and video (.mp3, .m4a, .mp4, .mov, .mkv, .avi) are unavailable in this release and must never be passed to a decoder or cloud fallback.

If no file or directory was supplied, stop after this explanation and wait. Do not scan Desktop, Downloads, a home directory, or any default location.

Required lifecycle

1. Recover and authorize. probe first performs a guarded sweep. Use only explicit input paths and explicit authorized roots. Do not follow links, junctions, mount points, hidden directories, or paths outside those roots.
2. Prepare. Run prepare with every authorized root as --authorize and every selected file/folder as --path. Task output stays only in the Skill-owned private OS-temporary workspace. Each task has a 12-hour lease and an OS-level task lock; process exit alone never makes a prepared task stale. If native probing returns cleanup-pending, stop before discovery/conversion and retain the authenticated probe scratch and cleanup identity.
3. Report. Read the JSON result and tell the user each file's converted, partial, skipped, failed, or cancelled status, including every reason and warning. A mixed batch is not a full success.
4. Authenticated read. Keep the returned task_id and nonce private. Run read for index first, then only the manifest-listed chunks relevant to the request. Each authenticated read refreshes the lease. Never read arbitrary temporary paths or load all chunks unless the request requires the full contents.
5. Optional export. Only after the user explicitly requests persistent Markdown, run export --task-id ... --nonce ... --target .... The target must resolve outside every manifest-authorized/source tree. Export is atomic and does not overwrite unless the user explicitly authorizes --overwrite.
6. Cleanup. Put cleanup --task-id ... --nonce ... in the finalization path after the answer, failure, cancellation, or export. A prior cleanup-pending state is retryable. If cleanup still returns cleanup-pending, report completed_with_issues; do not claim complete cleanup. sweep takes a nonblocking task lock and deletes only identity-revalidated tasks whose 12-hour lease expired.

The sequence is always prepare -> authenticated read -> cleanup. A per-file failure does not authorize a different route.

Non-negotiable boundaries

• Never write Markdown, caches, thumbnails, logs, locks, profiles, or temporary files into the source tree.
• Never use online OCR, cloud transcription, remote URLs, telemetry, model downloads, or another cloud converter as fallback. When probe does not advertise a format, report skipped/local-capability-unavailable.
• Never retain task caches for convenience or future questions. Normal cleanup is mandatory.
• Never imply that local conversion prevents WorkBuddy or a cloud model from processing the Markdown under their own data policies.
• Enforce the built-in budgets: 1,000 supported files, 256 MiB Markdown, 4 GiB task scratch, 8 GiB global task root, 4 GiB cumulative reads/expansion, 10 minutes per conversion worker, and 12 hours per task. Read bytes are budgeted before hashing and counted through discovery and streamed snapshots. Scratch is reserved under a root-wide lock and monitored while workers run. Enumeration/access truncation, timeout, cancellation, decoding replacement, and cleanup problems are explicit non-success results.

Persistent Markdown exists only through the authenticated export command after the user confirms a destination. With no safe external destination, return skipped/no-safe-export-destination. Otherwise leave no persistent output.

This artifact remains a verified prototype. Do not claim WorkBuddy-native compatibility until real WorkBuddy import, authorized-path handoff, read, and cleanup smoke tests pass.

Read [format support](references/format-support.md) for routing limits, [privacy and permissions](references/privacy-and-permissions.md) for boundaries, and [the result contract](references/result-contract.md) for status handling.