Skip to content

Commit dcd5914

Browse files
JE-ChenJE-Chen
committed
Expand docs landing pages across all three languages
1 parent b063e63 commit dcd5914

File tree

3 files changed

+409
-23
lines changed

3 files changed

+409
-23
lines changed

‎docs/source.zh-CN/index.rst‎

Lines changed: 135 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,111 @@ automation_file
33

44
语言：`English <../html/index.html>`_ | `繁體中文 <../html-zh-TW/index.html>`_ | **简体中文**
55

6-
以自动化为核心的 Python 库，涵盖本地文件 / 目录 / zip 操作、HTTP 下载
7-
以及远程存储（Google Drive、S3、Azure Blob、Dropbox、SFTP）。内置 PySide6 图形界面，
8-
把每一项功能以标签页的形式呈现。所有动作以 JSON 描述，统一通过
9-
:class:`~automation_file.core.action_registry.ActionRegistry` 调度。
6+
以自动化为核心的模块化框架，涵盖本地文件 / 目录 / ZIP 操作、经 SSRF 校验的
7+
HTTP 下载、远程存储（Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP、
8+
WebDAV、SMB、fsspec），以及通过内建 TCP / HTTP 服务器执行的 JSON 动作。
9+
内置 PySide6 图形界面，把每一项功能以标签页形式呈现；所有公开功能统一从
10+
顶层 ``automation_file`` 外观模块重新导出。
1011

11-
快速开始
12+
功能亮点
1213
--------
1314

14-
从 PyPI 安装并执行 JSON 动作列表：
15+
**核心原语**
16+
17+
* JSON 动作列表由共享的
18+
:class:`~automation_file.core.action_executor.ActionExecutor` 执行，支持
19+
校验、dry-run、并行、DAG。
20+
* 路径穿越防护（:func:`~automation_file.local.safe_paths.safe_join`）、
21+
对外 URL 的 SSRF 校验、默认仅绑定 loopback 的 TCP / HTTP 服务器，
22+
可选共享密钥验证与每动作 ACL。
23+
* 可靠性辅助：``retry_on_transient`` 装饰器、``Quota`` 流量与时间预算、
24+
流式 checksum、可续传 HTTP 下载。
25+
26+
**后端集成**
27+
28+
* 本地文件 / 目录 / ZIP / tar 操作。
29+
* HTTP 下载：SSRF 防护、大小 / 超时上限、重试、续传、可选 SHA-256 校验。
30+
* 一等公民后端：Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP / FTPS、
31+
WebDAV、SMB / CIFS、fsspec — 全部自动注册。
32+
* 跨后端复制，使用 URI 语法（``local://``、``s3://``、``drive://``、
33+
``sftp://``、``azure://``、``dropbox://``、``ftp://`` …）。
34+
35+
**事件驱动**
36+
37+
* 文件监听触发器 ``FA_watch_*`` — 路径变动时自动执行动作列表。
38+
* Cron 调度（``FA_schedule_*``）采用纯标准库的 5 字段解析器，
39+
提供重叠保护，失败时自动通知。
40+
* 传输进度与取消 Token，通过 ``progress_name`` 对外暴露。
41+
42+
**可观测性与集成**
43+
44+
* 通知 Sink — webhook / Slack / SMTP / Telegram / Discord / Teams /
45+
PagerDuty，每个 Sink 独立隔离错误，并采用滑动窗口去重。
46+
* Prometheus 指标导出器（``start_metrics_server``）、SQLite 审计日志、
47+
文件完整性监视器。
48+
* HTMX 网页面板（``start_web_ui``）、MCP 服务器将注册表桥接到
49+
Claude Desktop / MCP CLI，走 JSON-RPC 2.0。
50+
* PySide6 桌面 GUI（``python -m automation_file ui``）。
51+
52+
**供应链**
53+
54+
* 配置文件与机密信息 — 在 ``automation_file.toml`` 声明 sink 与默认值；
55+
``${env:…}`` / ``${file:…}`` 引用通过 Env / File / Chained provider
56+
解析，避免把密钥写死在文件中。
57+
* 入口点插件 — 第三方包通过
58+
``[project.entry-points."automation_file.actions"]``
59+
注册自己的 ``FA_*`` 动作。
60+
61+
架构鸟瞰
62+
--------
63+
64+
.. code-block:: text
65+
66+
用户 / CLI / JSON batch
67+
│
68+
▼
69+
┌─────────────────────────────────────────┐
70+
│ automation_file（外观） │
71+
│ execute_action、driver_instance、 │
72+
│ start_autocontrol_socket_server、 │
73+
│ start_http_action_server、Quota … │
74+
└─────────────────────────────────────────┘
75+
│
76+
▼
77+
┌──────────────┐ ┌────────────────────┐
78+
│ core │────▶│ ActionRegistry │
79+
│ executor、 │ │ （FA_* 指令） │
80+
│ retry、 │ └────────────────────┘
81+
│ quota、 │ │
82+
│ progress │ ▼
83+
└──────────────┘ ┌────────────────────┐
84+
│ local / remote / │
85+
│ server / triggers /│
86+
│ scheduler / ui │
87+
└────────────────────┘
88+
89+
完整的模块树与设计模式见 :doc:`architecture`。
90+
91+
安装
92+
----
1593

1694
.. code-block:: bash
1795
1896
pip install automation_file
97+
98+
所有后端（S3、Azure Blob、Dropbox、SFTP、PySide6）都是一等运行期
99+
依赖，常见使用场景不需要额外的 extras。
100+
101+
快速开始
102+
--------
103+
104+
用 CLI 执行 JSON 动作列表：
105+
106+
.. code-block:: bash
107+
19108
python -m automation_file --execute_file my_actions.json
20109
21-
或直接通过 Python 代码调用：
110+
直接从 Python 调用：
22111

23112
.. code-block:: python
24113
@@ -27,8 +116,47 @@ automation_file
27116
execute_action([
28117
["FA_create_dir", {"dir_path": "build"}],
29118
["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
119+
["FA_zip_dir", {"source": "build", "target": "build.zip"}],
30120
])
31121
122+
执行前先校验动作列表，或并行执行：
123+
124+
.. code-block:: python
125+
126+
from automation_file import executor
127+
128+
problems = executor.validate(actions)
129+
if problems:
130+
raise SystemExit("\n".join(problems))
131+
executor.execute_action_parallel(actions, max_workers=4)
132+
133+
启动 PySide6 图形界面：
134+
135+
.. code-block:: bash
136+
137+
python -m automation_file ui
138+
139+
以共享密钥在 loopback 提供 HTTP 动作服务器：
140+
141+
.. code-block:: python
142+
143+
from automation_file import start_http_action_server
144+
145+
server = start_http_action_server(port=8765, shared_secret="s3kret")
146+
147+
动作列表的格式
148+
--------------
149+
150+
一个动作是三种 list 形式之一，按名称通过注册表调度：
151+
152+
.. code-block:: python
153+
154+
["FA_create_dir"] # 无参数
155+
["FA_create_dir", {"dir_path": "build"}] # 关键字参数
156+
["FA_copy_file", ["src.txt", "dst.txt"]] # 位置参数
157+
158+
JSON 动作列表就是上述 list 的 list。
159+
32160
.. toctree::
33161
:maxdepth: 2
34162
:caption: 目录

‎docs/source.zh-TW/index.rst‎

Lines changed: 135 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,111 @@ automation_file
33

44
語言：`English <../html/index.html>`_ | **繁體中文** | `简体中文 <../html-zh-CN/index.html>`_
55

6-
以自動化為核心的 Python 函式庫，涵蓋本地檔案 / 目錄 / zip 操作、HTTP 下載
7-
與遠端儲存（Google Drive、S3、Azure Blob、Dropbox、SFTP）。內建 PySide6 圖形介面，
8-
把每一項功能以分頁形式呈現。所有動作以 JSON 描述，統一透過
9-
:class:`~automation_file.core.action_registry.ActionRegistry` 調度。
6+
以自動化為核心的模組化框架，涵蓋本地檔案 / 目錄 / ZIP 操作、經 SSRF 驗證的
7+
HTTP 下載、遠端儲存（Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP、
8+
WebDAV、SMB、fsspec），以及透過內建 TCP / HTTP 伺服器執行的 JSON 動作。
9+
內建 PySide6 圖形介面，把每一項功能以分頁形式呈現；所有公開功能統一從
10+
頂層 ``automation_file`` 外觀模組重新匯出。
1011

11-
快速開始
12+
功能亮點
1213
--------
1314

14-
從 PyPI 安裝並執行 JSON 動作清單：
15+
**核心原語**
16+
17+
* JSON 動作清單由共用的
18+
:class:`~automation_file.core.action_executor.ActionExecutor` 執行，支援
19+
驗證、dry-run、平行、DAG。
20+
* 路徑穿越防護（:func:`~automation_file.local.safe_paths.safe_join`）、
21+
對外 URL 的 SSRF 驗證、預設僅綁定 loopback 的 TCP / HTTP 伺服器，
22+
可選共享金鑰驗證與每動作 ACL。
23+
* 可靠性輔助：``retry_on_transient`` 裝飾器、``Quota`` 流量與時間上限、
24+
串流式 checksum、可續傳 HTTP 下載。
25+
26+
**後端整合**
27+
28+
* 本地檔案 / 目錄 / ZIP / tar 操作。
29+
* HTTP 下載：SSRF 防護、大小 / 逾時上限、重試、續傳、可選 SHA-256 驗證。
30+
* 第一方整合：Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP / FTPS、
31+
WebDAV、SMB / CIFS、fsspec — 全部自動註冊。
32+
* 跨後端複製，使用 URI 語法（``local://``、``s3://``、``drive://``、
33+
``sftp://``、``azure://``、``dropbox://``、``ftp://`` …）。
34+
35+
**事件驅動**
36+
37+
* 檔案監看觸發器 ``FA_watch_*`` — 路徑變動時自動執行動作清單。
38+
* Cron 排程（``FA_schedule_*``）採用純標準函式庫的 5 欄位解析器，
39+
提供重疊保護，失敗時自動通知。
40+
* 傳輸進度與取消 Token，透過 ``progress_name`` 對外暴露。
41+
42+
**可觀測性與整合**
43+
44+
* 通知 Sink — webhook / Slack / SMTP / Telegram / Discord / Teams /
45+
PagerDuty，各 Sink 獨立隔離錯誤並採用滑動視窗去重。
46+
* Prometheus 指標匯出器（``start_metrics_server``）、SQLite 稽核日誌、
47+
檔案完整性監視器。
48+
* HTMX 網頁面板（``start_web_ui``）、MCP 伺服器將註冊表橋接到
49+
Claude Desktop / MCP CLI，走 JSON-RPC 2.0。
50+
* PySide6 桌面 GUI（``python -m automation_file ui``）。
51+
52+
**供應鏈**
53+
54+
* 設定檔與機敏資訊 — 在 ``automation_file.toml`` 宣告 sink 與預設值；
55+
``${env:…}`` / ``${file:…}`` 參考透過 Env / File / Chained provider
56+
解析，避免把金鑰寫死在檔案裡。
57+
* 進入點外掛 — 第三方套件透過
58+
``[project.entry-points."automation_file.actions"]``
59+
自行註冊 ``FA_*`` 動作。
60+
61+
架構鳥瞰
62+
--------
63+
64+
.. code-block:: text
65+
66+
使用者 / CLI / JSON batch
67+
│
68+
▼
69+
┌─────────────────────────────────────────┐
70+
│ automation_file（外觀） │
71+
│ execute_action、driver_instance、 │
72+
│ start_autocontrol_socket_server、 │
73+
│ start_http_action_server、Quota … │
74+
└─────────────────────────────────────────┘
75+
│
76+
▼
77+
┌──────────────┐ ┌────────────────────┐
78+
│ core │────▶│ ActionRegistry │
79+
│ executor、 │ │ （FA_* 指令） │
80+
│ retry、 │ └────────────────────┘
81+
│ quota、 │ │
82+
│ progress │ ▼
83+
└──────────────┘ ┌────────────────────┐
84+
│ local / remote / │
85+
│ server / triggers /│
86+
│ scheduler / ui │
87+
└────────────────────┘
88+
89+
完整的模組樹與設計模式請見 :doc:`architecture`。
90+
91+
安裝
92+
----
1593

1694
.. code-block:: bash
1795
1896
pip install automation_file
97+
98+
所有後端（S3、Azure Blob、Dropbox、SFTP、PySide6）皆為第一方執行期
99+
依賴，常見使用情境不需要額外 extras。
100+
101+
快速開始
102+
--------
103+
104+
用 CLI 執行 JSON 動作清單：
105+
106+
.. code-block:: bash
107+
19108
python -m automation_file --execute_file my_actions.json
20109
21-
或直接從 Python 程式碼呼叫：
110+
直接從 Python 呼叫：
22111

23112
.. code-block:: python
24113
@@ -27,8 +116,47 @@ automation_file
27116
execute_action([
28117
["FA_create_dir", {"dir_path": "build"}],
29118
["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
119+
["FA_zip_dir", {"source": "build", "target": "build.zip"}],
30120
])
31121
122+
執行前先驗證動作清單，或以平行方式執行：
123+
124+
.. code-block:: python
125+
126+
from automation_file import executor
127+
128+
problems = executor.validate(actions)
129+
if problems:
130+
raise SystemExit("\n".join(problems))
131+
executor.execute_action_parallel(actions, max_workers=4)
132+
133+
啟動 PySide6 圖形介面：
134+
135+
.. code-block:: bash
136+
137+
python -m automation_file ui
138+
139+
以共享金鑰在 loopback 提供 HTTP 動作伺服器：
140+
141+
.. code-block:: python
142+
143+
from automation_file import start_http_action_server
144+
145+
server = start_http_action_server(port=8765, shared_secret="s3kret")
146+
147+
動作清單的格式
148+
--------------
149+
150+
一個動作是三種 list 形式之一，依名稱透過註冊表調度：
151+
152+
.. code-block:: python
153+
154+
["FA_create_dir"] # 無參數
155+
["FA_create_dir", {"dir_path": "build"}] # 關鍵字參數
156+
["FA_copy_file", ["src.txt", "dst.txt"]] # 位置參數
157+
158+
JSON 動作清單就是上述 list 的 list。
159+
32160
.. toctree::
33161
:maxdepth: 2
34162
:caption: 目錄

0 commit comments

Comments
 (0)