共享线程池和协作式取消

.github/workflows/benchmark.yml

@@ -19,10 +19,10 @@ jobs:
     timeout-minutes: 15
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v7
       with:
         python-version: '3.14'
 
@@ -49,7 +49,7 @@ jobs:
 
     - name: Upload Benchmark Report
       if: always()
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: benchmark-report
         path: PERFORMANCE_REPORT.md

.github/workflows/close_specific_pr.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Close PR
         run: |
@@ -36,4 +36,4 @@ jobs:
           gh pr comment ${{ github.event.pull_request.number }} --repo ${{ github.repository }} --body '${{ env.comment }}'
           gh pr close ${{ github.event.pull_request.number }} --repo ${{ github.repository }}
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/download.yml

@@ -29,9 +29,9 @@ jobs:
       UPLOAD_NAME: 'Click me to download'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Set up Python 3.11
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.11"
 
@@ -69,7 +69,7 @@ jobs:
           mv "../$ZIP_NAME" .
 
       - name: 上传结果
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: ${{ env.UPLOAD_NAME }}
           path: ${{ env.JM_DOWNLOAD_DIR }}/${{ env.ZIP_NAME }}

.github/workflows/download_dispatch.yml

@@ -108,9 +108,11 @@ jobs:
       JM_DOWNLOAD_DIR: /home/runner/work/jmcomic/download/
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
       - name: Set up Python 3.11
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.11"
 
@@ -153,7 +155,7 @@ jobs:
           mv "../$ZIP_NAME" .
 
       - name: 上传结果
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: ${{ env.UPLOAD_NAME }}
           path: ${{ env.JM_DOWNLOAD_DIR }}/${{ env.ZIP_NAME }}

.github/workflows/export_favorites.yml

@@ -48,9 +48,11 @@ jobs:
       ZIP_FP: /home/runner/work/jmcomic/download/export.7z
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
       - name: Set up Python 3.11
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.11"
 
@@ -71,7 +73,7 @@ jobs:
           python workflow_export_favorites.py
 
       - name: 上传结果
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: '导出的收藏夹'
           path: ${{ env.ZIP_FP }}

.github/workflows/release.yml

@@ -13,10 +13,12 @@ jobs:
       id-token: write
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Set up Python 3.11
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.11"
 
@@ -31,7 +33,7 @@ jobs:
           python -m build
 
       - name: Create Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:

.github/workflows/release_auto.yml

@@ -14,10 +14,12 @@ jobs:
       contents: write
     if: startsWith(github.event.head_commit.message, 'v')
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Set up Python 3.11
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.11"
 
@@ -33,7 +35,7 @@ jobs:
           python -m build
 
       - name: Create Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:

.github/workflows/test_api.yml

@@ -27,10 +27,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
 

.github/workflows/test_html.yml

@@ -27,10 +27,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
 

CHANGELOG.md

@@ -5,6 +5,18 @@
 条目分类参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [2.7.6] - 2026-09-06
+
+### Added
+- 新增 `JmSimpleRuntime`、`JmSyncRuntime` 与 `JmAsyncRuntime`；裸同步 Downloader 的局部调度使用单池 Runtime，顶层同步 API 或自定义同步调度可复用 `id/photo/image` 三层线程池，异步下载可复用 `decode` 线程池。
+- 新增 `DownloadControl` 和 `DownloadCancelledException`，支持通过任务上下文协作式取消同步与异步下载。
+- 新增 `JTC` (Jm Task Context) 门面类，统一提供上下文、Runtime、Option 及取消控制器的快捷读取方法。
+
+### Changed
+- Python 3.9 保留安装兼容，但不再纳入 CI。
+- 下载调度统一使用标准库 Executor；顶层 API 和裸同步 Downloader 的临时调度显式关闭自己创建的 Runtime，`jm_task_context` 只传播字段；外部 Runtime 和 Executor 仍由调用方关闭。
+- 顶层下载会把 Runtime 和 Option 作为公开字段直接放入任务上下文；Runtime 不依赖 Context 或 Option，未配置的层级由实际调用点传入默认 worker 数。
+
 ## [2.7.5] - 2026-08-25
 
 ### Summary

assets/docs/mkdocs.yml

@@ -58,6 +58,7 @@ nav:
     - tutorial/12_domain_strategy.md
     - tutorial/13_export_and_feature.md
     - tutorial/14_async_usage.md
+    - tutorial/16_shared_executors.md
     - tutorial/15_download_progress.md
 
 plugins:

assets/docs/sources/api/download.md

@@ -17,3 +17,37 @@
     options:
       members:
       - JmAsyncDownloader
+
+::: jmcomic.jm_downloader
+    options:
+      members:
+      - BaseDownloader
+      - JmDownloader
+
+::: jmcomic.jm_runtime
+    options:
+      members:
+      - JmRuntime
+      - JmSimpleRuntime
+      - JmSyncRuntime
+      - JmAsyncRuntime
+
+::: jmcomic.jm_exception
+    options:
+      members:
+      - DownloadCancelledException
+
+::: jmcomic.jm_task_context
+    options:
+      members:
+      - DownloadControl
+      - jm_task_context
+      - bind_jm_task_context
+
+::: jmcomic.jm_task_context.JTC
+    options:
+      members:
+      - get_runtime
+      - get_option
+      - get_control
+      - get_context

assets/docs/sources/tutorial/0_common_usage.md

@@ -440,11 +440,61 @@ cl = JmApiClient(
 ```
 
 
+## 取消下载
+
+> 如果你想中途取消下载，最简单粗暴的方式是直接杀死进程，比如 `ctrl+c`，关闭终端窗口 等
+> 
+> 但是在 GUI、Web服务这类场景里，就不适合这么关闭。 
+> 
+> 于是，jmcomic 提供了一种优雅停止的写法，可以使用 `DownloadControl` 这个类。
+> 
+> 这种写法更加可控：
+> 
+> - **不影响主程序**：只停当前下载，GUI 界面或 Web 服务依然正常运作。
+> - **多任务统一取消**：多个本子一起下载时，可以被统一取消。
+> - **可携带取消理由**：调用 `cancel()` 传入的原因可以直接捕获，方便做提示和日志。
+
+写法就两步：
+
+1. 创建 DownloadControl 对象，传入任务上下文
+2. 调用 DownloadControl 类的 cancel() 方法
+
+```python
+from threading import Thread
+from time import sleep
+from jmcomic import DownloadCancelledException, DownloadControl, download_album, jm_task_context
+
+# 创建取消控制器
+my_control = DownloadControl()
+
+def run_download():
+    try:
+        # 使用 with jm_task_context 创建任务上下文，并传入 control 参数
+        with jm_task_context(control=my_control):
+            # 这里还可以写多个 download_album(xxx)，都会统一被取消，因为属于同一个 任务上下文
+            download_album('123456')
+    except DownloadCancelledException as e:
+        print(f'下载已取消: {e.reason}')
+
+# 使用单独的下载线程执行下载
+# 主线程负责取消
+t = Thread(target=run_download)
+t.start()
+
+# 模拟一段时间后，需要取消下载
+sleep(2)
+# 可以传入取消原因，下载线程可通过上面的 e.reason 获取
+my_control.cancel("不想要了，取消掉吧") 
+# 等待下载线程结束
+t.join()
+```
+
+
 ## 下载返回值
 
 `download_album` 和 `download_photo` 下载完成后，单个 ID 返回 `DownloadResult`，多个 ID 返回 `BatchResult`。
 
-从 `result.detail` 可以取得下载的本子/章节的实体类：
+从 `DownloadResult` 的 `detail` 字段可以取得下载的本子/章节的实体类：
 
 ```python
 from jmcomic import download_album, download_photo
@@ -544,24 +594,26 @@ print('长图导出文件:', png_filepath_list)
 
 ### 批量下载的返回值
 
-传入多个 ID 时，返回值是 `BatchResult`。每一项成功下载对应一个 `DownloadResult`，失败任务则记录在 `failed` 中：
+传入多个 ID 时，返回值是 `BatchResult`，通过这个对象可以取得成功和失败的下载结果：
 
 <details markdown="1">
 <summary>完整示例：处理批量下载结果</summary>
 
 ```python
-from jmcomic import download_album
+from jmcomic import download_album, DownloadResult
 
 # 同时下载多个本子
 batch_result = download_album(['123', '456', '789'])
 
-# BatchResult 继承 set，成功结果没有输入顺序保证
+# BatchResult 继承 set，直接遍历是只遍历成功结果
 for result in batch_result:
+    result: DownloadResult
+    # result 的用法同上    
     album = result.detail
-    # 通过实体 ID 识别当前结果，不要用遍历位置对应输入列表
     print(f'JM{album.id} 下载到: {album.save_path}')
 
-# failed 的键是下载失败的 ID，值是记录失败原因的异常对象
+# failed 负责存放失败的下载结果，类型是dict
+# key是下载失败的 ID，value是记录失败原因的异常对象
 for album_id, error in batch_result.failed.items():
     print(f'JM{album_id} 下载失败: {error}')
 
@@ -572,7 +624,8 @@ print('是否全部成功:', batch_result.all_succeeded)
 
 </details>
 
-下载单个 ID 时，请求本子失败会直接抛出异常；如果只有部分章节或图片失败，会在任务结束后汇总抛出 `PartialDownloadFailedException`，此时不会返回 `DownloadResult`。批量下载则继续执行其他任务，并把失败项集中放进 `batch_result.failed`。
+---
+
 
 ### 速查表