tasklite-engine 1.4.2__tar.gz → 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/PKG-INFO +65 -43
  2. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/README.md +64 -42
  3. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/pyproject.toml +1 -0
  4. tasklite_engine-2.0.0/tasklite/__init__.py +202 -0
  5. tasklite_engine-2.0.0/tasklite/backend/__init__.py +23 -0
  6. tasklite_engine-2.0.0/tasklite/backend/base.py +381 -0
  7. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/backend/memory.py +131 -90
  8. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/backend/sqlite_backend.py +442 -324
  9. tasklite_engine-2.0.0/tasklite/contrib/__init__.py +7 -0
  10. tasklite_engine-2.0.0/tasklite/engine/__init__.py +21 -0
  11. tasklite_engine-2.0.0/tasklite/engine/admission.py +323 -0
  12. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/channel.py +195 -168
  13. tasklite_engine-2.0.0/tasklite/engine/completion.py +440 -0
  14. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/config.py +64 -55
  15. tasklite_engine-2.0.0/tasklite/engine/dispatch.py +628 -0
  16. tasklite_engine-1.4.2/tasklite/taxonomy.py → tasklite_engine-2.0.0/tasklite/engine/errorclass.py +323 -371
  17. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/governor.py +143 -110
  18. tasklite_engine-1.4.2/tasklite/engine/inflight.py → tasklite_engine-2.0.0/tasklite/engine/in_flight.py +46 -26
  19. tasklite_engine-1.4.2/tasklite/engine/console.py → tasklite_engine-2.0.0/tasklite/engine/ops.py +141 -87
  20. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/recovery.py +153 -89
  21. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/resource.py +131 -128
  22. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/runtime.py +175 -116
  23. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/scheduler.py +84 -79
  24. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/session.py +24 -12
  25. tasklite_engine-2.0.0/tasklite/engine/store.py +784 -0
  26. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/types.py +54 -40
  27. tasklite_engine-1.4.2/tasklite/engine/pacing.py → tasklite_engine-2.0.0/tasklite/engine/wait.py +13 -7
  28. tasklite_engine-2.0.0/tasklite/exceptions.py +66 -0
  29. tasklite_engine-2.0.0/tasklite/hooks.py +69 -0
  30. tasklite_engine-2.0.0/tasklite/models/__init__.py +11 -0
  31. tasklite_engine-2.0.0/tasklite/models/attempt.py +138 -0
  32. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/models/context.py +87 -89
  33. tasklite_engine-2.0.0/tasklite/models/job.py +437 -0
  34. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/models/state.py +36 -30
  35. tasklite_engine-2.0.0/tasklite/models/task.py +268 -0
  36. tasklite_engine-2.0.0/tasklite/pipeline.py +698 -0
  37. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/testing.py +8 -8
  38. tasklite_engine-2.0.0/tasklite/utils/__init__.py +4 -0
  39. tasklite_engine-2.0.0/tasklite/utils/clock.py +24 -0
  40. tasklite_engine-1.4.2/tasklite/utils/injective.py → tasklite_engine-2.0.0/tasklite/utils/encoding.py +79 -57
  41. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/utils/ipc.py +80 -38
  42. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/utils/jsonutil.py +17 -8
  43. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/utils/lockfile.py +25 -13
  44. tasklite_engine-2.0.0/tasklite/wrappers/__init__.py +19 -0
  45. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/wrappers/discovery.py +266 -187
  46. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/wrappers/http.py +355 -290
  47. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/PKG-INFO +65 -43
  48. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/SOURCES.txt +17 -7
  49. tasklite_engine-2.0.0/tests/test_encoding.py +533 -0
  50. tasklite_engine-2.0.0/tests/test_exceptions.py +99 -0
  51. tasklite_engine-2.0.0/tests/test_hooks.py +118 -0
  52. tasklite_engine-2.0.0/tests/test_jsonutil.py +97 -0
  53. tasklite_engine-2.0.0/tests/test_package_surface.py +246 -0
  54. tasklite_engine-2.0.0/tests/test_pipeline.py +970 -0
  55. tasklite_engine-2.0.0/tests/test_testing.py +187 -0
  56. tasklite_engine-1.4.2/tasklite/__init__.py +0 -139
  57. tasklite_engine-1.4.2/tasklite/backend/__init__.py +0 -12
  58. tasklite_engine-1.4.2/tasklite/backend/base.py +0 -256
  59. tasklite_engine-1.4.2/tasklite/contrib/__init__.py +0 -6
  60. tasklite_engine-1.4.2/tasklite/engine/__init__.py +0 -20
  61. tasklite_engine-1.4.2/tasklite/engine/completion.py +0 -380
  62. tasklite_engine-1.4.2/tasklite/engine/dispatch.py +0 -465
  63. tasklite_engine-1.4.2/tasklite/engine/policy.py +0 -448
  64. tasklite_engine-1.4.2/tasklite/engine/store.py +0 -692
  65. tasklite_engine-1.4.2/tasklite/exceptions.py +0 -54
  66. tasklite_engine-1.4.2/tasklite/hooks.py +0 -49
  67. tasklite_engine-1.4.2/tasklite/models/__init__.py +0 -6
  68. tasklite_engine-1.4.2/tasklite/models/job.py +0 -510
  69. tasklite_engine-1.4.2/tasklite/pipeline.py +0 -591
  70. tasklite_engine-1.4.2/tasklite/utils/__init__.py +0 -7
  71. tasklite_engine-1.4.2/tasklite/wrappers/__init__.py +0 -53
  72. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/LICENSE +0 -0
  73. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/setup.cfg +0 -0
  74. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/py.typed +0 -0
  75. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/dependency_links.txt +0 -0
  76. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/requires.txt +0 -0
  77. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/top_level.txt +0 -0
  78. {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tests/test_packaging.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tasklite-engine
3
- Version: 1.4.2
3
+ Version: 2.0.0
4
4
  Summary: A lightweight task orchestration engine with zero external dependencies, process isolation, and ACID persistence
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://github.com/CaptainLi321/tasklite
@@ -37,7 +37,7 @@ Dynamic: license-file
37
37
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
38
38
  [![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20external-brightgreen.svg)]()
39
39
  [![ACID Persistence](https://img.shields.io/badge/persistence-SQLite%20WAL%20(ACID)-orange.svg)]()
40
- [![Tests](https://img.shields.io/badge/tests-2000%2B%20passed-success.svg)]()
40
+ [![Tests](https://img.shields.io/badge/tests-2200%2B%20passed-success.svg)]()
41
41
 
42
42
  ---
43
43
 
@@ -51,7 +51,7 @@ Dynamic: license-file
51
51
  - **标准库进程池 (`multiprocessing.Pool` / `ProcessPoolExecutor`)**:
52
52
  - ❌ 缺乏内置状态持久化,程序中断后已完成进度丢失;
53
53
  - ❌ 子任务发生 C 扩展段错误 (SIGSEGV) 或内存泄露 (OOM) 时,容易导致主进程一同崩溃;
54
- - ❌ 缺少全局速率限制与服务熔断机制,缺乏 DAG 拓扑依赖与死信隔离。
54
+ - ❌ 缺少全局速率限制与服务熔断机制,缺乏 DAG 拓扑依赖与失败隔离。
55
55
  - **重型分布式任务队列 (`Celery` / `Airflow` / `Temporal`)**:
56
56
  - ❌ 强依赖 Redis、RabbitMQ、PostgreSQL 等外部服务,本地单机运行或轻量嵌入脚本时运维成本过高;
57
57
  - ❌ 架构较重,不适合作为随用随走的轻量批处理脚手架。
@@ -59,7 +59,7 @@ Dynamic: license-file
59
59
  **TaskLite 的设计定位**:
60
60
  **零依赖的单机批处理脚手架**——只需 `pip install tasklite-engine`。
61
61
  1. **多 Worker 并发加速**:多进程并行执行,充分利用多核算力,彻底解决单线程耗时长的问题;
62
- 2. **断点续跑防重跑**:以 SQLite WAL 事务表记录状态,已完成的任务自动跳过,失败任务进入死信队列或退避重试,杜绝因个别失败导致全量重跑;
62
+ 2. **断点续跑防重跑**:以 SQLite WAL 事务表记录状态,已完成的任务自动跳过,失败任务立即重入队重试、预算耗尽进失败档案,杜绝因个别失败导致全量重跑;
63
63
  3. **物理隔离与容灾**:主进程只负责调度,业务逻辑在独立子进程中运行并设超时强杀,即使子任务崩溃、死锁或系统断电,状态依然完整可恢复。
64
64
 
65
65
  ---
@@ -119,7 +119,7 @@ flowchart TD
119
119
 
120
120
  ### 2. ⚡ SQLite WAL 状态持久化 (ACID)
121
121
  - 基于 SQLite WAL + `synchronous=FULL` 模式;
122
- - 四集合状态机(Wall 已完成 / Queue 待办 / In-Flight 在途 / Failed 死信)在单次事务中原子转移;
122
+ - 状态机(Wall 成功档案 / Queue 待办 / In-Flight 在途 / Failed 失败档案)在单次事务中原子转移;
123
123
  - 遭遇中断或异常关机时,重启后支持 At-Least-Once 接续执行。
124
124
 
125
125
  ### 3. 🔍 函数式增量探索 (Functional Discovery)
@@ -132,7 +132,7 @@ flowchart TD
132
132
 
133
133
  ### 5. 🔗 DAG 拓扑依赖与级联熔断
134
134
  - 任务通过 `depends_on` 声明依赖;
135
- - 父任务失败进入死信队列时,所有下游依赖自动标记跳过 (`JOB_DEPENDENCY`),避免无效计算。
135
+ - 父任务失败进入失败档案时,所有下游依赖自动标记跳过 (`ERR_JOB_DEPENDENCY`),避免无效计算。
136
136
 
137
137
  ### 6. 📦 产物沙盒与自动清理
138
138
  - `ctx.declare_output()` 声明产出文件,内置路径遍历防御 (`../` 拒绝);
@@ -140,7 +140,7 @@ flowchart TD
140
140
 
141
141
  ### 7. 🌐 组合式 HTTP 网络工具与快照守卫 (HTTP Wrappers)
142
142
  - 开放 Callable 设计,支持原生 `urllib`、`requests`、`httpx` 或平台自定义签名 SDK;
143
- - `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线退避,收敛异常三分类;
143
+ - `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线挂起,收敛异常三分类;
144
144
  - `SQLiteSnapshotStore` 提供单射键原始响应快照持久化,支持全离线幂等重放;
145
145
  - 内置标准 Netscape `cookies.txt` 解析工具。
146
146
 
@@ -167,31 +167,31 @@ from tasklite import TaskLite, Job, RetryError, RateLimitResource
167
167
 
168
168
  logging.getLogger("tasklite").setLevel(logging.INFO)
169
169
 
170
- # 1. 定义任务处理器(在独立子进程中执行)
170
+ # 1. 定义任务处理器(在独立子进程中执行,必须模块级定义)
171
171
  def download_handler(job: Job, ctx):
172
172
  # 声明产出文件(失败时自动清理半残文件)
173
173
  out = ctx.declare_output(f"./downloads/{job.job_id}.jpg", cleanup_on_fail=True)
174
-
174
+
175
175
  # 模拟业务下载
176
176
  success = do_download(job.payload["url"], out)
177
177
  if not success:
178
- raise RetryError("网络抖动,触发指数退避重试")
179
-
178
+ raise RetryError("网络抖动,立即重入队重试")
179
+
180
180
  return True, {"size": 1024, "path": str(out)}
181
181
 
182
- # 2. 初始化引擎与配置资源
182
+ # 2. 初始化引擎(六步调用契约:初始化 → register_resource → register_task → enqueue → run → stop)
183
183
  pipeline = TaskLite(
184
184
  name="media_downloader",
185
185
  state_dir="./state", # 状态持久化目录(SQLite WAL)
186
186
  output_root="./downloads", # 产物沙盒根目录
187
- max_workers=4, # 并发子进程数
187
+ max_workers=4, # 并发子进程数(内部 __workers__ 容量资源,可覆盖)
188
188
  )
189
189
 
190
- # 3. 注册全局限速(每秒最多 2 次请求)与处理器
191
- pipeline.add_resource(RateLimitResource("api", interval_seconds=0.5))
192
- pipeline.register_handler("download", download_handler, default_resources={"api": 1.0})
190
+ # 3. 注册全局限速(每秒最多 2 次请求)与 Task 规格
191
+ pipeline.register_resource(RateLimitResource("api", interval_seconds=0.5))
192
+ pipeline.register_task("download", download_handler, default_resources={"api": 1.0})
193
193
 
194
- # 4. 入队并启动(阻塞直到队列全部完成)
194
+ # 4. 入队并启动(阻塞直到队列全部完成,返回 RunSummary)
195
195
  pipeline.enqueue([
196
196
  Job("download", "img_001", payload={"url": "https://example.com/1.jpg"}),
197
197
  Job("download", "img_002", payload={"url": "https://example.com/2.jpg"}),
@@ -201,6 +201,24 @@ pipeline.run()
201
201
 
202
202
  ---
203
203
 
204
+ ## 🧭 三层模型(Task / Job / Attempt)
205
+
206
+ 本引擎按实时系统理论建模为三层(设计总纲 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md),上位裁决 [ADR-0005](docs/adr/0005-v2-promotion.md)):
207
+
208
+ | 层 | 定义 | 持久化 |
209
+ |---|---|---|
210
+ | **Task(规格)** | 进程内注册的静态模板:task_type 名、handler、默认资源、payload_schema、默认 max_retries / timeout | 代码即规格,不落盘;注册于 `register_task` |
211
+ | **Job(逻辑实例)** | 一次有界激活;`uid = task_type::job_id` 身份不变 | queue 行 job_data JSON(uid 为主键) |
212
+ | **Attempt(执行轨迹)** | 一次物理执行的记录:attempt 序号、incarnation、起止时间、结局 | append-only 新表 `attempts` |
213
+
214
+ 任一 attempts 行可回溯「哪次激活的第几次执行、由哪个 run 派发、结局如何、当前终态在哪、规格是什么」——端到端追溯链完整。完整使用指南见 **[`docs/V2_GUIDE.md`](docs/V2_GUIDE.md)**(权威);v1 → v2 命名映射见 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md);未来演进方向(CLI 直达、make 式级联更新、调度策略族)见 [ROADMAP](docs/ROADMAP.md)。**v1 已退役**(git 历史与 `v1-final` 标签留档)。
215
+
216
+ ```python
217
+ from tasklite import TaskLite, Job, Task, AttemptRecord
218
+ ```
219
+
220
+ ---
221
+
204
222
  ## 🍳 实战 Recipes
205
223
 
206
224
  ### Recipe 1: 增量分页扫描器 (Discovery)
@@ -218,7 +236,7 @@ def item_id(post) -> str:
218
236
  return str(post["id"]) # 唯一内容 ID
219
237
 
220
238
  def process_item(job, ctx, post, content_id: str):
221
- # 发现新内容时派生子任务(content_id 已做单射净化)
239
+ # 发现新内容时派生子任务(content_id 已做单射编码)
222
240
  ctx.spawn(Job("download", content_id, payload={"url": post["url"]}))
223
241
 
224
242
  # 注册增量探索
@@ -259,7 +277,7 @@ from tasklite import RateLimitHit
259
277
  def fetch_handler(job, ctx):
260
278
  resp = requests.get(job.payload["url"])
261
279
  if resp.status_code == 429:
262
- # 全管线挂起 api 资源 1 小时,状态持久化到磁盘,随后抛出退避重试
280
+ # 全管线挂起 api 资源 1 小时,状态持久化到磁盘,随后抛出瞬态重试
263
281
  ctx.suspend_resource("api", seconds=3600)
264
282
  raise RateLimitHit("Triggered 429, suspending API for 1h")
265
283
  return True, resp.json()
@@ -286,8 +304,8 @@ def agent_worker(job: Job, ctx):
286
304
  return True, {"tokens": result.get("usage", 0)}
287
305
 
288
306
  pipeline = TaskLite(name="agent_batch", state_dir="./agent_state", max_workers=8)
289
- pipeline.add_resource(RateLimitResource("llm_rpm", interval_seconds=0.1))
290
- pipeline.register_handler("analyze", agent_worker, default_resources={"llm_rpm": 1.0})
307
+ pipeline.register_resource(RateLimitResource("llm_rpm", interval_seconds=0.1))
308
+ pipeline.register_task("analyze", agent_worker, default_resources={"llm_rpm": 1.0})
291
309
 
292
310
  # 入队海量任务,中途即使断网或意外中断,重启后自动跳过已完成任务接续执行
293
311
  pipeline.enqueue([
@@ -301,40 +319,43 @@ pipeline.run()
301
319
 
302
320
  ```python
303
321
  from tasklite import TaskLite, RateLimitResource
304
- from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, fetch_urllib
322
+ from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, urllib_fetch
305
323
 
306
324
  pipeline = TaskLite("crawler", state_dir="./states")
307
- pipeline.add_resource(RateLimitResource("api", interval_seconds=1.0))
325
+ pipeline.register_resource(RateLimitResource("api", interval_seconds=1.0))
308
326
 
309
327
  # 原始 HTTP 响应持久化快照(独立 snapshots.db,支持全离线重放与反爬保护)
310
328
  snapshot_store = SQLiteSnapshotStore("./snapshots.db")
311
- cached_fetch = snapshot_store.cached(fetch_urllib)
329
+ cached_fetch = snapshot_store.cached(urllib_fetch)
312
330
 
313
331
  def crawler_handler(job, ctx):
314
- # 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接 DLQ
332
+ # 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接进失败档案
315
333
  with http_guard(ctx=ctx, resource="api", default_suspend_ttl=60.0):
316
334
  resp = cached_fetch(job.payload["url"])
317
335
  return resp.json()
318
336
 
319
- pipeline.register_handler("fetch", crawler_handler, default_resources={"api": 1.0})
337
+ pipeline.register_task("fetch", crawler_handler, default_resources={"api": 1.0})
320
338
  ```
321
339
 
322
340
  ---
323
341
 
324
342
 
325
- ## 🛠️ 死信队列与运维 (DLQ & Ops)
343
+ ## 🛠️ 失败档案与运维 (Failed & Ops)
326
344
 
327
- 当任务重试超限或发生致命错误时,任务进入持久化死信队列 (DLQ)。可以通过标准 API 检查与清理:
345
+ 当任务重试预算耗尽或发生致命错误时,任务进入持久化**失败档案**(failed 表,与 wall 按 uid 互斥且唯一终态)。运维 API 仅限 `run()` 外调用:
328
346
 
329
347
  ```python
330
- # 1. 检查死信详情
331
- for entry in pipeline.list_dlq():
332
- print(f"UID: {entry.uid}, 错误类型: {entry.error_type}, 原因: {entry.error}")
348
+ # 1. 检查失败详情(条目携带原始业务 payload 快照,补跑自足)
349
+ for entry in pipeline.list_failures():
350
+ print(f"UID: {entry.uid}, 原因: {entry.error}, 元数据: {entry.meta}")
351
+
352
+ # 2. 清理指定类型的失败档案(默认保留 fatal 错误,可入队同名任务重跑)
353
+ pipeline.clear_failures(task_types=["download"], keep_fatal=False)
333
354
 
334
- # 2. 清理指定类型的 DLQ(默认保留 fatal 错误,可入队同名任务重跑)
335
- pipeline.clear_dlq(task_types=["download"], keep_fatal=False)
355
+ # 3. 单条人工补跑:移出档案、按档案 payload 快照队首重入队
356
+ pipeline.retry_failure("download::img_001")
336
357
 
337
- # 3. 精确或前缀清理历史(wall / failed)
358
+ # 4. 精确或前缀清理历史(wall / failed)
338
359
  pipeline.clear_history("download::")
339
360
  ```
340
361
 
@@ -350,25 +371,26 @@ tasklite/
350
371
  │ ├── runtime.py # 核心运行期深模块、主循环事件泵 (EngineRuntime)
351
372
  │ ├── config.py # RunConfig 静态装配快照、默认值唯一解析点
352
373
  │ ├── session.py # RunSession 单次 run 生命周期状态与钩子单一出口
353
- │ ├── pacing.py # 事件泵等待/空闲决策纯函数(decide_wait)
374
+ │ ├── wait.py # 事件泵等待/空闲决策纯函数
354
375
  │ ├── types.py # 引擎公共值对象单一真相源
355
376
  │ ├── store.py # 状态事务、3-strike 崩溃与死锁归因 (StateStore)
356
- │ ├── console.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
377
+ │ ├── ops.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
357
378
  │ ├── dispatch.py # 任务派发状态机 (DispatchMachine)
358
379
  │ ├── completion.py # 任务完成与提交 (CompletionMachine)
359
380
  │ ├── recovery.py # 崩溃检测与恢复 (RecoveryOrchestrator)
360
381
  │ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel / WorkerLaunchSpec)
361
- │ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler)
362
- │ ├── policy.py # 准入预检、重试退避与 rerun 决策 (ExecutionPolicy)
382
+ │ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy seam)
383
+ │ ├── admission.py # rerun 准入 (RerunPolicy) 与重入队节奏 (RequeuePolicy)
363
384
  │ ├── governor.py # 死锁归因仲裁与依赖宽限 (DeadlockGovernor)
364
- │ ├── inflight.py # 在途作业租约追踪 (InFlightTracker)
385
+ │ ├── in_flight.py # 在途作业租约追踪 (InFlightTracker)
386
+ │ ├── errorclass.py # 错误分类与校验分类深模块 (ErrorClassifier)
365
387
  │ └── resource.py # 令牌桶限速与并发容量资源
366
388
  ├── backend/ # SQLite WAL 强一致事务持久化后端
367
- ├── models/ # Job / TaskContext / PipelineState 数据模型
368
- ├── taxonomy.py # 错误分类法与校验分类深模块 (ErrorTaxonomy)
369
- ├── testing.py # fake_ctx:handler 单测的官方 TaskContext 构造器
389
+ ├── models/ # Task / Job / Attempt / PipelineState / JobContext 数据模型
390
+ ├── testing.py # fake_ctx:handler 单测的官方 JobContext 构造器
370
391
  ├── wrappers/ # discovery.py(增量扫描)/ http.py(网络守卫与快照)
371
- └── utils/ # injective(单射 %XX 转义)/ ipc(IPC 信号与降级落盘)/ jsonutil(禁NaN)/ lockfile
392
+ ├── contrib/ # 生态扩展套件与参考实现(核心不依赖)
393
+ └── utils/ # encoding(单射 %XX 转义)/ ipc(IPC 信号与降级落盘)/ clock / jsonutil(禁NaN)/ lockfile
372
394
  ```
373
395
 
374
396
  ---
@@ -8,7 +8,7 @@
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
9
9
  [![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20external-brightgreen.svg)]()
10
10
  [![ACID Persistence](https://img.shields.io/badge/persistence-SQLite%20WAL%20(ACID)-orange.svg)]()
11
- [![Tests](https://img.shields.io/badge/tests-2000%2B%20passed-success.svg)]()
11
+ [![Tests](https://img.shields.io/badge/tests-2200%2B%20passed-success.svg)]()
12
12
 
13
13
  ---
14
14
 
@@ -22,7 +22,7 @@
22
22
  - **标准库进程池 (`multiprocessing.Pool` / `ProcessPoolExecutor`)**:
23
23
  - ❌ 缺乏内置状态持久化,程序中断后已完成进度丢失;
24
24
  - ❌ 子任务发生 C 扩展段错误 (SIGSEGV) 或内存泄露 (OOM) 时,容易导致主进程一同崩溃;
25
- - ❌ 缺少全局速率限制与服务熔断机制,缺乏 DAG 拓扑依赖与死信隔离。
25
+ - ❌ 缺少全局速率限制与服务熔断机制,缺乏 DAG 拓扑依赖与失败隔离。
26
26
  - **重型分布式任务队列 (`Celery` / `Airflow` / `Temporal`)**:
27
27
  - ❌ 强依赖 Redis、RabbitMQ、PostgreSQL 等外部服务,本地单机运行或轻量嵌入脚本时运维成本过高;
28
28
  - ❌ 架构较重,不适合作为随用随走的轻量批处理脚手架。
@@ -30,7 +30,7 @@
30
30
  **TaskLite 的设计定位**:
31
31
  **零依赖的单机批处理脚手架**——只需 `pip install tasklite-engine`。
32
32
  1. **多 Worker 并发加速**:多进程并行执行,充分利用多核算力,彻底解决单线程耗时长的问题;
33
- 2. **断点续跑防重跑**:以 SQLite WAL 事务表记录状态,已完成的任务自动跳过,失败任务进入死信队列或退避重试,杜绝因个别失败导致全量重跑;
33
+ 2. **断点续跑防重跑**:以 SQLite WAL 事务表记录状态,已完成的任务自动跳过,失败任务立即重入队重试、预算耗尽进失败档案,杜绝因个别失败导致全量重跑;
34
34
  3. **物理隔离与容灾**:主进程只负责调度,业务逻辑在独立子进程中运行并设超时强杀,即使子任务崩溃、死锁或系统断电,状态依然完整可恢复。
35
35
 
36
36
  ---
@@ -90,7 +90,7 @@ flowchart TD
90
90
 
91
91
  ### 2. ⚡ SQLite WAL 状态持久化 (ACID)
92
92
  - 基于 SQLite WAL + `synchronous=FULL` 模式;
93
- - 四集合状态机(Wall 已完成 / Queue 待办 / In-Flight 在途 / Failed 死信)在单次事务中原子转移;
93
+ - 状态机(Wall 成功档案 / Queue 待办 / In-Flight 在途 / Failed 失败档案)在单次事务中原子转移;
94
94
  - 遭遇中断或异常关机时,重启后支持 At-Least-Once 接续执行。
95
95
 
96
96
  ### 3. 🔍 函数式增量探索 (Functional Discovery)
@@ -103,7 +103,7 @@ flowchart TD
103
103
 
104
104
  ### 5. 🔗 DAG 拓扑依赖与级联熔断
105
105
  - 任务通过 `depends_on` 声明依赖;
106
- - 父任务失败进入死信队列时,所有下游依赖自动标记跳过 (`JOB_DEPENDENCY`),避免无效计算。
106
+ - 父任务失败进入失败档案时,所有下游依赖自动标记跳过 (`ERR_JOB_DEPENDENCY`),避免无效计算。
107
107
 
108
108
  ### 6. 📦 产物沙盒与自动清理
109
109
  - `ctx.declare_output()` 声明产出文件,内置路径遍历防御 (`../` 拒绝);
@@ -111,7 +111,7 @@ flowchart TD
111
111
 
112
112
  ### 7. 🌐 组合式 HTTP 网络工具与快照守卫 (HTTP Wrappers)
113
113
  - 开放 Callable 设计,支持原生 `urllib`、`requests`、`httpx` 或平台自定义签名 SDK;
114
- - `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线退避,收敛异常三分类;
114
+ - `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线挂起,收敛异常三分类;
115
115
  - `SQLiteSnapshotStore` 提供单射键原始响应快照持久化,支持全离线幂等重放;
116
116
  - 内置标准 Netscape `cookies.txt` 解析工具。
117
117
 
@@ -138,31 +138,31 @@ from tasklite import TaskLite, Job, RetryError, RateLimitResource
138
138
 
139
139
  logging.getLogger("tasklite").setLevel(logging.INFO)
140
140
 
141
- # 1. 定义任务处理器(在独立子进程中执行)
141
+ # 1. 定义任务处理器(在独立子进程中执行,必须模块级定义)
142
142
  def download_handler(job: Job, ctx):
143
143
  # 声明产出文件(失败时自动清理半残文件)
144
144
  out = ctx.declare_output(f"./downloads/{job.job_id}.jpg", cleanup_on_fail=True)
145
-
145
+
146
146
  # 模拟业务下载
147
147
  success = do_download(job.payload["url"], out)
148
148
  if not success:
149
- raise RetryError("网络抖动,触发指数退避重试")
150
-
149
+ raise RetryError("网络抖动,立即重入队重试")
150
+
151
151
  return True, {"size": 1024, "path": str(out)}
152
152
 
153
- # 2. 初始化引擎与配置资源
153
+ # 2. 初始化引擎(六步调用契约:初始化 → register_resource → register_task → enqueue → run → stop)
154
154
  pipeline = TaskLite(
155
155
  name="media_downloader",
156
156
  state_dir="./state", # 状态持久化目录(SQLite WAL)
157
157
  output_root="./downloads", # 产物沙盒根目录
158
- max_workers=4, # 并发子进程数
158
+ max_workers=4, # 并发子进程数(内部 __workers__ 容量资源,可覆盖)
159
159
  )
160
160
 
161
- # 3. 注册全局限速(每秒最多 2 次请求)与处理器
162
- pipeline.add_resource(RateLimitResource("api", interval_seconds=0.5))
163
- pipeline.register_handler("download", download_handler, default_resources={"api": 1.0})
161
+ # 3. 注册全局限速(每秒最多 2 次请求)与 Task 规格
162
+ pipeline.register_resource(RateLimitResource("api", interval_seconds=0.5))
163
+ pipeline.register_task("download", download_handler, default_resources={"api": 1.0})
164
164
 
165
- # 4. 入队并启动(阻塞直到队列全部完成)
165
+ # 4. 入队并启动(阻塞直到队列全部完成,返回 RunSummary)
166
166
  pipeline.enqueue([
167
167
  Job("download", "img_001", payload={"url": "https://example.com/1.jpg"}),
168
168
  Job("download", "img_002", payload={"url": "https://example.com/2.jpg"}),
@@ -172,6 +172,24 @@ pipeline.run()
172
172
 
173
173
  ---
174
174
 
175
+ ## 🧭 三层模型(Task / Job / Attempt)
176
+
177
+ 本引擎按实时系统理论建模为三层(设计总纲 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md),上位裁决 [ADR-0005](docs/adr/0005-v2-promotion.md)):
178
+
179
+ | 层 | 定义 | 持久化 |
180
+ |---|---|---|
181
+ | **Task(规格)** | 进程内注册的静态模板:task_type 名、handler、默认资源、payload_schema、默认 max_retries / timeout | 代码即规格,不落盘;注册于 `register_task` |
182
+ | **Job(逻辑实例)** | 一次有界激活;`uid = task_type::job_id` 身份不变 | queue 行 job_data JSON(uid 为主键) |
183
+ | **Attempt(执行轨迹)** | 一次物理执行的记录:attempt 序号、incarnation、起止时间、结局 | append-only 新表 `attempts` |
184
+
185
+ 任一 attempts 行可回溯「哪次激活的第几次执行、由哪个 run 派发、结局如何、当前终态在哪、规格是什么」——端到端追溯链完整。完整使用指南见 **[`docs/V2_GUIDE.md`](docs/V2_GUIDE.md)**(权威);v1 → v2 命名映射见 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md);未来演进方向(CLI 直达、make 式级联更新、调度策略族)见 [ROADMAP](docs/ROADMAP.md)。**v1 已退役**(git 历史与 `v1-final` 标签留档)。
186
+
187
+ ```python
188
+ from tasklite import TaskLite, Job, Task, AttemptRecord
189
+ ```
190
+
191
+ ---
192
+
175
193
  ## 🍳 实战 Recipes
176
194
 
177
195
  ### Recipe 1: 增量分页扫描器 (Discovery)
@@ -189,7 +207,7 @@ def item_id(post) -> str:
189
207
  return str(post["id"]) # 唯一内容 ID
190
208
 
191
209
  def process_item(job, ctx, post, content_id: str):
192
- # 发现新内容时派生子任务(content_id 已做单射净化)
210
+ # 发现新内容时派生子任务(content_id 已做单射编码)
193
211
  ctx.spawn(Job("download", content_id, payload={"url": post["url"]}))
194
212
 
195
213
  # 注册增量探索
@@ -230,7 +248,7 @@ from tasklite import RateLimitHit
230
248
  def fetch_handler(job, ctx):
231
249
  resp = requests.get(job.payload["url"])
232
250
  if resp.status_code == 429:
233
- # 全管线挂起 api 资源 1 小时,状态持久化到磁盘,随后抛出退避重试
251
+ # 全管线挂起 api 资源 1 小时,状态持久化到磁盘,随后抛出瞬态重试
234
252
  ctx.suspend_resource("api", seconds=3600)
235
253
  raise RateLimitHit("Triggered 429, suspending API for 1h")
236
254
  return True, resp.json()
@@ -257,8 +275,8 @@ def agent_worker(job: Job, ctx):
257
275
  return True, {"tokens": result.get("usage", 0)}
258
276
 
259
277
  pipeline = TaskLite(name="agent_batch", state_dir="./agent_state", max_workers=8)
260
- pipeline.add_resource(RateLimitResource("llm_rpm", interval_seconds=0.1))
261
- pipeline.register_handler("analyze", agent_worker, default_resources={"llm_rpm": 1.0})
278
+ pipeline.register_resource(RateLimitResource("llm_rpm", interval_seconds=0.1))
279
+ pipeline.register_task("analyze", agent_worker, default_resources={"llm_rpm": 1.0})
262
280
 
263
281
  # 入队海量任务,中途即使断网或意外中断,重启后自动跳过已完成任务接续执行
264
282
  pipeline.enqueue([
@@ -272,40 +290,43 @@ pipeline.run()
272
290
 
273
291
  ```python
274
292
  from tasklite import TaskLite, RateLimitResource
275
- from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, fetch_urllib
293
+ from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, urllib_fetch
276
294
 
277
295
  pipeline = TaskLite("crawler", state_dir="./states")
278
- pipeline.add_resource(RateLimitResource("api", interval_seconds=1.0))
296
+ pipeline.register_resource(RateLimitResource("api", interval_seconds=1.0))
279
297
 
280
298
  # 原始 HTTP 响应持久化快照(独立 snapshots.db,支持全离线重放与反爬保护)
281
299
  snapshot_store = SQLiteSnapshotStore("./snapshots.db")
282
- cached_fetch = snapshot_store.cached(fetch_urllib)
300
+ cached_fetch = snapshot_store.cached(urllib_fetch)
283
301
 
284
302
  def crawler_handler(job, ctx):
285
- # 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接 DLQ
303
+ # 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接进失败档案
286
304
  with http_guard(ctx=ctx, resource="api", default_suspend_ttl=60.0):
287
305
  resp = cached_fetch(job.payload["url"])
288
306
  return resp.json()
289
307
 
290
- pipeline.register_handler("fetch", crawler_handler, default_resources={"api": 1.0})
308
+ pipeline.register_task("fetch", crawler_handler, default_resources={"api": 1.0})
291
309
  ```
292
310
 
293
311
  ---
294
312
 
295
313
 
296
- ## 🛠️ 死信队列与运维 (DLQ & Ops)
314
+ ## 🛠️ 失败档案与运维 (Failed & Ops)
297
315
 
298
- 当任务重试超限或发生致命错误时,任务进入持久化死信队列 (DLQ)。可以通过标准 API 检查与清理:
316
+ 当任务重试预算耗尽或发生致命错误时,任务进入持久化**失败档案**(failed 表,与 wall 按 uid 互斥且唯一终态)。运维 API 仅限 `run()` 外调用:
299
317
 
300
318
  ```python
301
- # 1. 检查死信详情
302
- for entry in pipeline.list_dlq():
303
- print(f"UID: {entry.uid}, 错误类型: {entry.error_type}, 原因: {entry.error}")
319
+ # 1. 检查失败详情(条目携带原始业务 payload 快照,补跑自足)
320
+ for entry in pipeline.list_failures():
321
+ print(f"UID: {entry.uid}, 原因: {entry.error}, 元数据: {entry.meta}")
322
+
323
+ # 2. 清理指定类型的失败档案(默认保留 fatal 错误,可入队同名任务重跑)
324
+ pipeline.clear_failures(task_types=["download"], keep_fatal=False)
304
325
 
305
- # 2. 清理指定类型的 DLQ(默认保留 fatal 错误,可入队同名任务重跑)
306
- pipeline.clear_dlq(task_types=["download"], keep_fatal=False)
326
+ # 3. 单条人工补跑:移出档案、按档案 payload 快照队首重入队
327
+ pipeline.retry_failure("download::img_001")
307
328
 
308
- # 3. 精确或前缀清理历史(wall / failed)
329
+ # 4. 精确或前缀清理历史(wall / failed)
309
330
  pipeline.clear_history("download::")
310
331
  ```
311
332
 
@@ -321,25 +342,26 @@ tasklite/
321
342
  │ ├── runtime.py # 核心运行期深模块、主循环事件泵 (EngineRuntime)
322
343
  │ ├── config.py # RunConfig 静态装配快照、默认值唯一解析点
323
344
  │ ├── session.py # RunSession 单次 run 生命周期状态与钩子单一出口
324
- │ ├── pacing.py # 事件泵等待/空闲决策纯函数(decide_wait)
345
+ │ ├── wait.py # 事件泵等待/空闲决策纯函数
325
346
  │ ├── types.py # 引擎公共值对象单一真相源
326
347
  │ ├── store.py # 状态事务、3-strike 崩溃与死锁归因 (StateStore)
327
- │ ├── console.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
348
+ │ ├── ops.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
328
349
  │ ├── dispatch.py # 任务派发状态机 (DispatchMachine)
329
350
  │ ├── completion.py # 任务完成与提交 (CompletionMachine)
330
351
  │ ├── recovery.py # 崩溃检测与恢复 (RecoveryOrchestrator)
331
352
  │ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel / WorkerLaunchSpec)
332
- │ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler)
333
- │ ├── policy.py # 准入预检、重试退避与 rerun 决策 (ExecutionPolicy)
353
+ │ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy seam)
354
+ │ ├── admission.py # rerun 准入 (RerunPolicy) 与重入队节奏 (RequeuePolicy)
334
355
  │ ├── governor.py # 死锁归因仲裁与依赖宽限 (DeadlockGovernor)
335
- │ ├── inflight.py # 在途作业租约追踪 (InFlightTracker)
356
+ │ ├── in_flight.py # 在途作业租约追踪 (InFlightTracker)
357
+ │ ├── errorclass.py # 错误分类与校验分类深模块 (ErrorClassifier)
336
358
  │ └── resource.py # 令牌桶限速与并发容量资源
337
359
  ├── backend/ # SQLite WAL 强一致事务持久化后端
338
- ├── models/ # Job / TaskContext / PipelineState 数据模型
339
- ├── taxonomy.py # 错误分类法与校验分类深模块 (ErrorTaxonomy)
340
- ├── testing.py # fake_ctx:handler 单测的官方 TaskContext 构造器
360
+ ├── models/ # Task / Job / Attempt / PipelineState / JobContext 数据模型
361
+ ├── testing.py # fake_ctx:handler 单测的官方 JobContext 构造器
341
362
  ├── wrappers/ # discovery.py(增量扫描)/ http.py(网络守卫与快照)
342
- └── utils/ # injective(单射 %XX 转义)/ ipc(IPC 信号与降级落盘)/ jsonutil(禁NaN)/ lockfile
363
+ ├── contrib/ # 生态扩展套件与参考实现(核心不依赖)
364
+ └── utils/ # encoding(单射 %XX 转义)/ ipc(IPC 信号与降级落盘)/ clock / jsonutil(禁NaN)/ lockfile
343
365
  ```
344
366
 
345
367
  ---
@@ -74,6 +74,7 @@ show_missing = true
74
74
  skip_covered = false
75
75
 
76
76
  [tool.mutmut]
77
+ # 变异测试目标:核心层与门面(contrib 不参与)
77
78
  source_paths = [
78
79
  "tasklite/backend/",
79
80
  "tasklite/engine/",