automation_file 简体中文文档

简中手册按典型读者旅程拆分为章节：安装 → 执行 JSON 动作 → 操作本地文件 → 串接远端存储 → 对外开服务器 → 规模化自动化。可使用左侧目录，或直接跳到下方任一章节。

第 1 章 — 入门 

安装 automation_file、执行第一份 JSON 动作列表，并理解注册器与执行器之间的分工。

入门

快速开始

第 2 章 — CLI 

使用 python -m automation_file argparse 派发器驱动框架——子命令、旧版标志与 JSON 文件执行。

CLI

CLI

第 3 章 — 架构 

分层架构、设计模式（Facade、Registry、Command、Strategy、Template Method、Singleton、Builder），以及执行器与注册器的交互方式。

架构

架构

由 local/ 策略模块提供的文件、目录、ZIP、tar 与压缩档操作； safe_join 路径穿越防护；感知 OS 索引的 fast_find；流式 file_checksum 与 find_duplicates；sync_dir rsync 风格镜像；目录差异比对与文本 patch；JSON / YAML / CSV / JSONL / Parquet 编辑; MIME 检测；模板渲染；回收站发送 / 还原；文件版本控制；条件式执行；变量替换；带超时的 shell 子进程；以及 AES-256-GCM 文件加密。

本地操作

本地文件操作

第 5 章 — HTTP 传输 

经 SSRF 校验的对外 HTTP 下载，并通过 http_download 设下大小、超时、重试与 expected_sha256 上限。可通过 Range: 续传到 <target>.part，并提供实时进度快照。

HTTP 传输

HTTP 传输
- 可续传 HTTP 下载
- 传输进度与取消

第 6 章 — 云端与 SFTP 后端 

Google Drive、S3、Azure Blob、Dropbox、OneDrive、Box、SFTP、FTP / FTPS、 WebDAV、SMB 与 fsspec——皆由 build_default_registry 自动注册。 copy_between 可按 URI 前缀在不同后端间搬运数据。

云端与 SFTP 后端

云与 SFTP 后端

第 7 章 — 动作服务器 

默认仅绑定 loopback 的 TCP 与 HTTP 服务器，接受 JSON 动作列表，可选择启用共享密钥认证、ActionACL 白名单、GET /healthz / GET /readyz 健康检查、GET /openapi.json、GET /progress WebSocket，以及带类型的 HTTPActionClient SDK。

动作服务器

动作服务器
- TCP 动作服务器
- HTTP 动作服务器

第 8 章 — MCP 服务器 

MCPServer 通过 stdio 上的换行分隔 JSON-RPC 2.0，把注册器桥接到任意 Model Context Protocol 主机（Claude Desktop、Claude Code、MCP CLI）。

MCP 服务器

MCP 服务器（Claude Desktop / Claude Code）

第 9 章 — 图形界面 

PySide6 桌面控制界面——分页布局、日志面板，以及 ActionWorker 线程池模型。

图形界面

GUI（PySide6）

第 10 章 — 可靠性 

带上限的指数退避 retry_on_transient、Quota 大小与时间预算、 CircuitBreaker、RateLimiter、FileLock / SQLiteLock、持久化的 ActionQueue、SQLite AuditLog、用于周期清单比对的 IntegrityMonitor，以及带类型的 FileAutomationException 层级。