automation_file English Manual
The English manual is split into chapters that follow a typical reader journey: install → run JSON actions → drive locally → reach remote storage → expose servers → automate at scale. Use the table of contents on the left, or jump straight to a chapter below.
Chapter 1 — Getting Started
Install automation_file, run your first JSON action list, and
understand the registry-and-executor split.
Chapter 2 — CLI
Drive the framework from the python -m automation_file argparse
dispatcher — subcommands, legacy flags, and JSON file execution.
CLI
Chapter 3 — Architecture
The layered architecture, design patterns (Facade, Registry, Command, Strategy, Template Method, Singleton, Builder), and how the executor talks to the registry.
Chapter 4 — Local Operations
File, directory, ZIP, tar, and archive operations exposed by the local/
strategy modules; the safe_join path-traversal guard; OS-index-aware
fast_find; streaming file_checksum and find_duplicates;
sync_dir rsync-style mirror; directory diffs and text patches; JSON /
YAML / CSV / JSONL / Parquet edits; MIME detection; templates; trash send /
restore; file versioning; conditional execution; variable substitution;
shell subprocess with timeout; and AES-256-GCM file encryption.
Chapter 5 — HTTP Transfers
SSRF-validated outbound HTTP downloads with size, timeout, retry, and
expected_sha256 caps via http_download. Resumable Range:
downloads to <target>.part and live progress snapshots.
Chapter 6 — Cloud and SFTP Backends
Google Drive, S3, Azure Blob, Dropbox, OneDrive, Box, SFTP, FTP / FTPS,
WebDAV, SMB, and fsspec — auto-registered through build_default_registry.
copy_between moves data across backends via URI prefixes.
Cloud and SFTP Backends
Chapter 7 — Action Servers
Loopback-only TCP and HTTP servers that accept JSON action lists, with
optional shared-secret authentication, ActionACL allow lists,
GET /healthz / GET /readyz probes, GET /openapi.json, a
GET /progress WebSocket, and the typed HTTPActionClient SDK.
Action Servers
Chapter 8 — MCP Server
MCPServer bridges the registry to any Model Context Protocol host
(Claude Desktop, Claude Code, MCP CLIs) over newline-delimited JSON-RPC
2.0 on stdio.
Chapter 9 — GUI
The PySide6 desktop control surface — tabbed layout, log panel, and
ActionWorker thread-pool model.
GUI
Chapter 10 — Reliability
retry_on_transient with capped exponential back-off, Quota size
and time budgets, CircuitBreaker, RateLimiter, FileLock /
SQLiteLock, persistent ActionQueue, SQLite AuditLog,
IntegrityMonitor for periodic manifest verification, and the typed
FileAutomationException hierarchy.
Reliability
Chapter 11 — Triggers and Scheduler
File-watcher triggers (FA_watch_*) run an action list on a filesystem
event; the cron-style scheduler (FA_schedule_*) runs an action list on
a recurring schedule with overlap protection.
Triggers and Scheduler
Chapter 12 — Notifications
Slack, Email (SMTP), Discord, Telegram, Microsoft Teams, PagerDuty, and
generic webhook sinks composed by a NotificationManager with per-sink
error isolation and sliding-window dedup.
Notifications
Chapter 13 — Configuration and Secrets
Declare sinks and defaults in automation_file.toml; ${env:…} /
${file:…} references resolve through chained EnvSecretProvider /
FileSecretProvider; ConfigWatcher polls and hot-reloads the file
without restart.
Configuration and Secrets
Chapter 14 — DAG Action Executor
Run action lists as a DAG with declared dependencies, topological parallel fan-out, and per-branch skip-on-failure.
DAG Action Executor
Chapter 15 — Plugins
Third-party packages register their own FA_* actions through
[project.entry-points."automation_file.actions"]; PackageLoader
imports a Python package and registers its top-level members as
<package>_<member>.