Merge pull request #74 from Integration-Automation/dev

JE-Chen · web-flow · commit ca59089fae4f · 2026-04-28T17:44:53.000+08:00
Slim docs landing page to a WebRunner-style intro
diff --git a/.github/workflows/ci-dev.yml b/.github/workflows/ci-dev.yml
@@ -37,7 +37,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.10", "3.11", "3.12" ]
+        python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
diff --git a/.github/workflows/ci-stable.yml b/.github/workflows/ci-stable.yml
@@ -37,7 +37,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.10", "3.11", "3.12" ]
+        python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
diff --git a/docs/source.zh-CN/index.rst b/docs/source.zh-CN/index.rst
@@ -3,159 +3,23 @@ automation_file
 
 语言：`English <../html/index.html>`_ | `繁體中文 <../html-zh-TW/index.html>`_ | **简体中文**
 
-以自动化为核心的模块化框架，涵盖本地文件 / 目录 / ZIP 操作、经 SSRF 校验的
-HTTP 下载、远程存储（Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP、
-WebDAV、SMB、fsspec），以及通过内建 TCP / HTTP 服务器执行的 JSON 动作。
-内置 PySide6 图形界面，把每一项功能以标签页形式呈现；所有公开功能统一从
-顶层 ``automation_file`` 外观模块重新导出。
+以 JSON 动作列表为核心的模块化文件自动化框架。
 
-功能亮点
---------
-
-**核心原语**
-
-* JSON 动作列表由共享的
-  :class:`~automation_file.core.action_executor.ActionExecutor` 执行，支持
-  校验、dry-run、并行、DAG。
-* 路径穿越防护（:func:`~automation_file.local.safe_paths.safe_join`）、
-  对外 URL 的 SSRF 校验、默认仅绑定 loopback 的 TCP / HTTP 服务器，
-  可选共享密钥验证与每动作 ACL。
-* 可靠性辅助：``retry_on_transient`` 装饰器、``Quota`` 流量与时间预算、
-  流式 checksum、可续传 HTTP 下载。
-
-**后端集成**
-
-* 本地文件 / 目录 / ZIP / tar 操作。
-* HTTP 下载：SSRF 防护、大小 / 超时上限、重试、续传、可选 SHA-256 校验。
-* 一等公民后端：Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP / FTPS、
-  WebDAV、SMB / CIFS、fsspec — 全部自动注册。
-* 跨后端复制，使用 URI 语法（``local://``、``s3://``、``drive://``、
-  ``sftp://``、``azure://``、``dropbox://``、``ftp://`` …）。
-
-**事件驱动**
+``automation_file`` 把本地文件 / 目录 / ZIP 操作、经 SSRF 校验的 HTTP 下载、
+远端存储后端（Google Drive、S3、Azure Blob、Dropbox、OneDrive、Box、SFTP、
+FTP、WebDAV、SMB、fsspec）以及通过内建 TCP / HTTP / MCP 服务器执行的 JSON
+动作列表统合为单一框架——全部通过共享的 ``ActionRegistry`` 调度，并由
+PySide6 桌面图形界面对外呈现。
 
-* 文件监听触发器 ``FA_watch_*`` — 路径变动时自动执行动作列表。
-* Cron 调度（``FA_schedule_*``）采用纯标准库的 5 字段解析器，
-  提供重叠保护，失败时自动通知。
-* 传输进度与取消 Token，通过 ``progress_name`` 对外暴露。
+文档按语言与内容类型拆分。每个语言手册以章节组织：入门、CLI、架构、
+本地操作、HTTP 传输、云端与 SFTP 后端、动作服务器、MCP 服务器、图形界面、
+可靠性、触发器与调度、通知、配置、DAG、插件。API 参考则是自动生成的
+Python 参考资料。
 
-**可观测性与集成**
-
-* 通知 Sink — webhook / Slack / SMTP / Telegram / Discord / Teams /
-  PagerDuty，每个 Sink 独立隔离错误，并采用滑动窗口去重。
-* Prometheus 指标导出器（``start_metrics_server``）、SQLite 审计日志、
-  文件完整性监视器。
-* HTMX 网页面板（``start_web_ui``）、MCP 服务器将注册表桥接到
-  Claude Desktop / MCP CLI，走 JSON-RPC 2.0。
-* PySide6 桌面 GUI（``python -m automation_file ui``）。
-
-**供应链**
-
-* 配置文件与机密信息 — 在 ``automation_file.toml`` 声明 sink 与默认值；
-  ``${env:…}`` / ``${file:…}`` 引用通过 Env / File / Chained provider
-  解析，避免把密钥写死在文件中。
-* 入口点插件 — 第三方包通过
-  ``[project.entry-points."automation_file.actions"]``
-  注册自己的 ``FA_*`` 动作。
-
-架构鸟瞰
+未来规划
 --------
 
-.. code-block:: text
-
-   用户 / CLI / JSON batch
-          │
-          ▼
-   ┌─────────────────────────────────────────┐
-   │  automation_file（外观）                │
-   │  execute_action、driver_instance、      │
-   │  start_autocontrol_socket_server、      │
-   │  start_http_action_server、Quota …      │
-   └─────────────────────────────────────────┘
-          │
-          ▼
-   ┌──────────────┐     ┌────────────────────┐
-   │  core        │────▶│ ActionRegistry     │
-   │  executor、  │     │ （FA_* 指令）      │
-   │  retry、     │     └────────────────────┘
-   │  quota、     │              │
-   │  progress    │              ▼
-   └──────────────┘     ┌────────────────────┐
-                        │ local / remote /   │
-                        │ server / triggers /│
-                        │ scheduler / ui     │
-                        └────────────────────┘
-
-完整的模块树与设计模式见 :doc:`architecture`。
-
-安装
-----
-
-.. code-block:: bash
-
-   pip install automation_file
-
-所有后端（S3、Azure Blob、Dropbox、SFTP、PySide6）都是一等运行期
-依赖，常见使用场景不需要额外的 extras。
-
-快速开始
---------
-
-用 CLI 执行 JSON 动作列表：
-
-.. code-block:: bash
-
-   python -m automation_file --execute_file my_actions.json
-
-直接从 Python 调用：
-
-.. code-block:: python
-
-   from automation_file import execute_action
-
-   execute_action([
-       ["FA_create_dir", {"dir_path": "build"}],
-       ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
-       ["FA_zip_dir", {"source": "build", "target": "build.zip"}],
-   ])
-
-执行前先校验动作列表，或并行执行：
-
-.. code-block:: python
-
-   from automation_file import executor
-
-   problems = executor.validate(actions)
-   if problems:
-       raise SystemExit("\n".join(problems))
-   executor.execute_action_parallel(actions, max_workers=4)
-
-启动 PySide6 图形界面：
-
-.. code-block:: bash
-
-   python -m automation_file ui
-
-以共享密钥在 loopback 提供 HTTP 动作服务器：
-
-.. code-block:: python
-
-   from automation_file import start_http_action_server
-
-   server = start_http_action_server(port=8765, shared_secret="s3kret")
-
-动作列表的格式
---------------
-
-一个动作是三种 list 形式之一，按名称通过注册表调度：
-
-.. code-block:: python
-
-   ["FA_create_dir"]                                  # 无参数
-   ["FA_create_dir", {"dir_path": "build"}]           # 关键字参数
-   ["FA_copy_file", ["src.txt", "dst.txt"]]           # 位置参数
-
-JSON 动作列表就是上述 list 的 list。
+项目跟踪：https://github.com/Integration-Automation/FileAutomation/issues
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/source.zh-TW/index.rst b/docs/source.zh-TW/index.rst
@@ -3,159 +3,23 @@ automation_file
 
 語言：`English <../html/index.html>`_ | **繁體中文** | `简体中文 <../html-zh-CN/index.html>`_
 
-以自動化為核心的模組化框架，涵蓋本地檔案 / 目錄 / ZIP 操作、經 SSRF 驗證的
-HTTP 下載、遠端儲存（Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP、
-WebDAV、SMB、fsspec），以及透過內建 TCP / HTTP 伺服器執行的 JSON 動作。
-內建 PySide6 圖形介面，把每一項功能以分頁形式呈現；所有公開功能統一從
-頂層 ``automation_file`` 外觀模組重新匯出。
+以 JSON 動作清單為核心的模組化檔案自動化框架。
 
-功能亮點
---------
-
-**核心原語**
-
-* JSON 動作清單由共用的
-  :class:`~automation_file.core.action_executor.ActionExecutor` 執行，支援
-  驗證、dry-run、平行、DAG。
-* 路徑穿越防護（:func:`~automation_file.local.safe_paths.safe_join`）、
-  對外 URL 的 SSRF 驗證、預設僅綁定 loopback 的 TCP / HTTP 伺服器，
-  可選共享金鑰驗證與每動作 ACL。
-* 可靠性輔助：``retry_on_transient`` 裝飾器、``Quota`` 流量與時間上限、
-  串流式 checksum、可續傳 HTTP 下載。
-
-**後端整合**
-
-* 本地檔案 / 目錄 / ZIP / tar 操作。
-* HTTP 下載：SSRF 防護、大小 / 逾時上限、重試、續傳、可選 SHA-256 驗證。
-* 第一方整合：Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP / FTPS、
-  WebDAV、SMB / CIFS、fsspec — 全部自動註冊。
-* 跨後端複製，使用 URI 語法（``local://``、``s3://``、``drive://``、
-  ``sftp://``、``azure://``、``dropbox://``、``ftp://`` …）。
-
-**事件驅動**
+``automation_file`` 把本地檔案 / 目錄 / ZIP 操作、經 SSRF 驗證的 HTTP 下載、
+遠端儲存後端（Google Drive、S3、Azure Blob、Dropbox、OneDrive、Box、SFTP、
+FTP、WebDAV、SMB、fsspec）以及透過內建 TCP / HTTP / MCP 伺服器執行的 JSON
+動作清單統合為單一框架——全部透過共用的 ``ActionRegistry`` 調度，並由
+PySide6 桌面圖形介面對外呈現。
 
-* 檔案監看觸發器 ``FA_watch_*`` — 路徑變動時自動執行動作清單。
-* Cron 排程（``FA_schedule_*``）採用純標準函式庫的 5 欄位解析器，
-  提供重疊保護，失敗時自動通知。
-* 傳輸進度與取消 Token，透過 ``progress_name`` 對外暴露。
+文件依語言與內容類型拆分。每個語言手冊以章節組織：入門、CLI、架構、
+本地操作、HTTP 傳輸、雲端與 SFTP 後端、動作伺服器、MCP 伺服器、圖形介面、
+可靠性、觸發器與排程、通知、設定、DAG、外掛。API 參考則是自動生成的
+Python 參考資料。
 
-**可觀測性與整合**
-
-* 通知 Sink — webhook / Slack / SMTP / Telegram / Discord / Teams /
-  PagerDuty，各 Sink 獨立隔離錯誤並採用滑動視窗去重。
-* Prometheus 指標匯出器（``start_metrics_server``）、SQLite 稽核日誌、
-  檔案完整性監視器。
-* HTMX 網頁面板（``start_web_ui``）、MCP 伺服器將註冊表橋接到
-  Claude Desktop / MCP CLI，走 JSON-RPC 2.0。
-* PySide6 桌面 GUI（``python -m automation_file ui``）。
-
-**供應鏈**
-
-* 設定檔與機敏資訊 — 在 ``automation_file.toml`` 宣告 sink 與預設值；
-  ``${env:…}`` / ``${file:…}`` 參考透過 Env / File / Chained provider
-  解析，避免把金鑰寫死在檔案裡。
-* 進入點外掛 — 第三方套件透過
-  ``[project.entry-points."automation_file.actions"]``
-  自行註冊 ``FA_*`` 動作。
-
-架構鳥瞰
+未來規劃
 --------
 
-.. code-block:: text
-
-   使用者 / CLI / JSON batch
-          │
-          ▼
-   ┌─────────────────────────────────────────┐
-   │  automation_file（外觀）                │
-   │  execute_action、driver_instance、      │
-   │  start_autocontrol_socket_server、      │
-   │  start_http_action_server、Quota …      │
-   └─────────────────────────────────────────┘
-          │
-          ▼
-   ┌──────────────┐     ┌────────────────────┐
-   │  core        │────▶│ ActionRegistry     │
-   │  executor、  │     │ （FA_* 指令）      │
-   │  retry、     │     └────────────────────┘
-   │  quota、     │              │
-   │  progress    │              ▼
-   └──────────────┘     ┌────────────────────┐
-                        │ local / remote /   │
-                        │ server / triggers /│
-                        │ scheduler / ui     │
-                        └────────────────────┘
-
-完整的模組樹與設計模式請見 :doc:`architecture`。
-
-安裝
-----
-
-.. code-block:: bash
-
-   pip install automation_file
-
-所有後端（S3、Azure Blob、Dropbox、SFTP、PySide6）皆為第一方執行期
-依賴，常見使用情境不需要額外 extras。
-
-快速開始
---------
-
-用 CLI 執行 JSON 動作清單：
-
-.. code-block:: bash
-
-   python -m automation_file --execute_file my_actions.json
-
-直接從 Python 呼叫：
-
-.. code-block:: python
-
-   from automation_file import execute_action
-
-   execute_action([
-       ["FA_create_dir", {"dir_path": "build"}],
-       ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
-       ["FA_zip_dir", {"source": "build", "target": "build.zip"}],
-   ])
-
-執行前先驗證動作清單，或以平行方式執行：
-
-.. code-block:: python
-
-   from automation_file import executor
-
-   problems = executor.validate(actions)
-   if problems:
-       raise SystemExit("\n".join(problems))
-   executor.execute_action_parallel(actions, max_workers=4)
-
-啟動 PySide6 圖形介面：
-
-.. code-block:: bash
-
-   python -m automation_file ui
-
-以共享金鑰在 loopback 提供 HTTP 動作伺服器：
-
-.. code-block:: python
-
-   from automation_file import start_http_action_server
-
-   server = start_http_action_server(port=8765, shared_secret="s3kret")
-
-動作清單的格式
---------------
-
-一個動作是三種 list 形式之一，依名稱透過註冊表調度：
-
-.. code-block:: python
-
-   ["FA_create_dir"]                                  # 無參數
-   ["FA_create_dir", {"dir_path": "build"}]           # 關鍵字參數
-   ["FA_copy_file", ["src.txt", "dst.txt"]]           # 位置參數
-
-JSON 動作清單就是上述 list 的 list。
+專案追蹤：https://github.com/Integration-Automation/FileAutomation/issues
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/source/index.rst b/docs/source/index.rst
