tasklite-engine 2.1.0__tar.gz → 2.2.1__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 (74) hide show
  1. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/PKG-INFO +46 -85
  2. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/README.md +44 -84
  3. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/pyproject.toml +1 -1
  4. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/__init__.py +18 -14
  5. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/backend/base.py +87 -77
  6. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/backend/memory.py +150 -95
  7. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/backend/sqlite_backend.py +336 -255
  8. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/__init__.py +1 -1
  9. tasklite_engine-2.2.1/tasklite/engine/admission.py +203 -0
  10. tasklite_engine-2.2.1/tasklite/engine/channel.py +913 -0
  11. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/completion.py +157 -124
  12. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/config.py +31 -28
  13. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/dispatch.py +189 -192
  14. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/errorclass.py +63 -63
  15. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/governor.py +21 -16
  16. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/in_flight.py +39 -38
  17. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/ops.py +72 -72
  18. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/recovery.py +66 -162
  19. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/resource.py +39 -36
  20. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/runtime.py +32 -31
  21. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/scheduler.py +82 -55
  22. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/selection.py +13 -13
  23. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/session.py +16 -21
  24. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/store.py +265 -227
  25. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/types.py +19 -20
  26. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/engine/wait.py +3 -3
  27. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/exceptions.py +8 -0
  28. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/hooks.py +16 -16
  29. tasklite_engine-2.2.1/tasklite/models/artifact.py +80 -0
  30. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/models/attempt.py +17 -14
  31. tasklite_engine-2.2.1/tasklite/models/context.py +261 -0
  32. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/models/job.py +53 -73
  33. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/models/state.py +112 -142
  34. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/models/task.py +30 -19
  35. tasklite_engine-2.2.1/tasklite/models/trigger.py +18 -0
  36. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/pipeline.py +92 -101
  37. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/selection.py +20 -20
  38. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/testing.py +17 -11
  39. tasklite_engine-2.2.1/tasklite/triggers.py +46 -0
  40. tasklite_engine-2.2.1/tasklite/utils/artifact.py +203 -0
  41. tasklite_engine-2.2.1/tasklite/utils/clock.py +50 -0
  42. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/utils/encoding.py +6 -6
  43. tasklite_engine-2.2.1/tasklite/utils/ipc.py +632 -0
  44. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/utils/lockfile.py +8 -8
  45. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/wrappers/discovery.py +75 -80
  46. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite_engine.egg-info/PKG-INFO +46 -85
  47. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite_engine.egg-info/SOURCES.txt +6 -1
  48. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite_engine.egg-info/requires.txt +1 -0
  49. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tests/test_encoding.py +15 -15
  50. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tests/test_hooks.py +9 -9
  51. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tests/test_package_surface.py +17 -9
  52. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tests/test_packaging.py +9 -0
  53. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tests/test_pipeline.py +109 -123
  54. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tests/test_testing.py +22 -20
  55. tasklite_engine-2.2.1/tests/test_trigger_contract.py +298 -0
  56. tasklite_engine-2.1.0/tasklite/engine/admission.py +0 -323
  57. tasklite_engine-2.1.0/tasklite/engine/channel.py +0 -783
  58. tasklite_engine-2.1.0/tasklite/models/context.py +0 -278
  59. tasklite_engine-2.1.0/tasklite/utils/clock.py +0 -24
  60. tasklite_engine-2.1.0/tasklite/utils/ipc.py +0 -743
  61. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/LICENSE +0 -0
  62. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/setup.cfg +0 -0
  63. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/backend/__init__.py +0 -0
  64. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/contrib/__init__.py +0 -0
  65. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/models/__init__.py +0 -0
  66. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/py.typed +0 -0
  67. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/utils/__init__.py +0 -0
  68. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/utils/jsonutil.py +0 -0
  69. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/wrappers/__init__.py +0 -0
  70. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite/wrappers/http.py +0 -0
  71. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite_engine.egg-info/dependency_links.txt +0 -0
  72. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tasklite_engine.egg-info/top_level.txt +0 -0
  73. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tests/test_exceptions.py +0 -0
  74. {tasklite_engine-2.1.0 → tasklite_engine-2.2.1}/tests/test_jsonutil.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tasklite-engine
3
- Version: 2.1.0
3
+ Version: 2.2.1
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
@@ -25,6 +25,7 @@ Requires-Dist: mutmut>=3.0; extra == "dev"
25
25
  Requires-Dist: pytest-timeout>=2.0; extra == "dev"
26
26
  Requires-Dist: pytest-cov>=4.0; extra == "dev"
27
27
  Requires-Dist: requests>=2.28; extra == "dev"
28
+ Requires-Dist: mypy>=1.0; extra == "dev"
28
29
  Dynamic: license-file
29
30
 
30
31
  # ⚡ TaskLite — 零依赖、进程隔离的轻量任务编排引擎
@@ -37,7 +38,7 @@ Dynamic: license-file
37
38
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
38
39
  [![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20external-brightgreen.svg)]()
39
40
  [![ACID Persistence](https://img.shields.io/badge/persistence-SQLite%20WAL%20(ACID)-orange.svg)]()
40
- [![Tests](https://img.shields.io/badge/tests-2200%2B%20passed-success.svg)]()
41
+ [![Tests](https://img.shields.io/badge/tests-2500%2B%20passed-success.svg)]()
41
42
 
42
43
  ---
43
44
 
@@ -75,7 +76,7 @@ Dynamic: license-file
75
76
  | **抗漂移增量探索 (Discovery)** | **内置函数式无游标去重** | 无 | 无 | 需自定义传感器 |
76
77
  | **全局限速与持久化休眠** | **内置令牌桶 + 跨重启持久化** | 无 | 需 Redis 限流组件 | 需复杂调度配置 |
77
78
  | **DAG 依赖与级联熔断** | **内置拓扑依赖 + 自动跳过** | 无 | 需 Canvas 复杂编排 | 原生支持 |
78
- | **产物沙盒与失败自动清理** | **内置 declare_output** | 无 | 无 | 需自定义 Hook |
79
+ | **产物沙盒与显式清理授权** | **内置 declare_output** | 无 | 无 | 需自定义 Hook |
79
80
 
80
81
  ---
81
82
 
@@ -84,7 +85,7 @@ Dynamic: license-file
84
85
  ```mermaid
85
86
  flowchart TD
86
87
  subgraph Host ["主调度进程 (Master Scheduler) - 永不运行业务 Handler"]
87
- State[("SQLite WAL 状态机\n(Wall / Queue / Failed / In-Flight)")]
88
+ State[("SQLite WAL 状态机\n(Successes / Queue / Failed / In-Flight)")]
88
89
  Scheduler["JobScheduler (资源调度 / 拓扑依赖)"]
89
90
  Watchdog["进程看门狗 (超时 SIGKILL / 孤儿锁探测)"]
90
91
  end
@@ -97,15 +98,15 @@ flowchart TD
97
98
 
98
99
  Scheduler -->|"1. 检查资源 & 拓扑依赖"| State
99
100
  Scheduler -->|"2. Spawn 独立子进程 (隔离)"| Workers
100
- Workers -.->|"3. 原子落盘结果/信号 (.result.json)"| State
101
+ Workers -.->|"3. 独立单向 Pipe 传递声明/信号/结果"| State
101
102
  Watchdog -->|"4. 轮询超时 SIGKILL 强杀"| Workers
102
103
  State -->|"5. BEGIN IMMEDIATE 原子收尾"| State
103
104
  ```
104
105
 
105
106
  ### 三层崩溃恢复防线
106
- 1. **执行代标识 (Generation Tag)**:结果文件携带 `{uid}.{run_id}.{seq}`,前次崩溃的孤儿进程结果对新 Run 不可见;
107
- 2. **启动期残留消费**:启动时自动识别并提交崩溃前已落盘的有效结果,不重复执行;
108
- 3. **孤儿文件锁探测 (Lockfile Fencing)**:严格保证同一 UID 在全局只有一个物理执行体。
107
+ 1. **执行代标识与通道绑定 (Generation Fencing)**:每 worker 绑定独立单向 `Pipe` 与 `{run_id}.{dispatch_no}` 执行代标识,校验 `job_uid` 与 `execution_id`,旧执行与伪造消息无法污染状态机;
108
+ 2. **可信成功事务持久化**:IPC 仅负责本次运行的瞬时通信,已提交的成功档案、`attempts` 终态与资源挂起由 SQLite 强事务持久化,未提交在途任务重启后自动接续重做;
109
+ 3. **孤儿文件锁探测 (Lockfile Fencing)**:严格保证同一 UID 在全局只有一个物理执行体,主进程崩溃后孤儿持锁期间新 Run 自动避让。
109
110
 
110
111
  ---
111
112
 
@@ -119,12 +120,12 @@ flowchart TD
119
120
 
120
121
  ### 2. ⚡ SQLite WAL 状态持久化 (ACID)
121
122
  - 基于 SQLite WAL + `synchronous=FULL` 模式;
122
- - 状态机(Wall 成功档案 / Queue 待办 / In-Flight 在途 / Failed 失败档案)在单次事务中原子转移;
123
+ - 状态机(Successes 成功档案 / Queue 待办 / In-Flight 在途 / Failed 失败档案)在单次事务中原子转移;
123
124
  - 遭遇中断或异常关机时,重启后支持 At-Least-Once 接续执行。
124
125
 
125
126
  ### 3. 🔍 函数式增量探索 (Functional Discovery)
126
127
  - 针对数据同步、采集与拉取场景的无游标 (Cursor-less) 增量扫描;
127
- - 直接复用已完成集合 (Wall) 即时判定已见内容,整页命中自动刹车,天然免疫上游记录删除、插入导致的游标漂移。
128
+ - 直接复用成功档案 (Successes) 即时判定已见内容,整页命中自动刹车,天然免疫上游记录删除、插入导致的游标漂移。
128
129
 
129
130
  ### 4. ⏸️ 全局限流与配额熔断持久化休眠
130
131
  - 内置 `RateLimitResource`(速率限制)与 `CapacityResource`(并发限制);
@@ -134,22 +135,17 @@ flowchart TD
134
135
  - 任务通过 `depends_on` 声明依赖;
135
136
  - 父任务失败进入失败档案时,所有下游依赖自动标记跳过 (`ERR_JOB_DEPENDENCY`),避免无效计算。
136
137
 
137
- ### 6. 📦 产物沙盒与自动清理
138
- - `ctx.declare_output()` 声明产出文件,内置路径遍历防御 (`../` 拒绝);
139
- - 任务成功时校验物理产出完整性,任务失败时自动清理半成品文件,避免残留。
138
+ ### 6. 📦 具名磁盘产物与显式清理授权
139
+ - `ctx.declare_output(path, name=...)` 声明文件或目录产物并随成功事务原子发布,下游通过 `ctx.get_artifact_path(...)` 安全引用直接依赖的产物路径;
140
+ - 前置删除、失败清理与成功清理分别由 `delete_existing`、`delete_on_failure`、`delete_on_success` 显式授权(`declare_cache` 固定成败自动清理),收尾时先清理后提交。
140
141
 
141
142
  ### 7. 🌐 组合式 HTTP 网络工具与快照守卫 (HTTP Wrappers)
142
143
  - 开放 Callable 设计,支持原生 `urllib`、`requests`、`httpx` 或平台自定义签名 SDK;
143
- - `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线挂起,收敛异常三分类;
144
- - `SQLiteSnapshotStore` 提供单射键原始响应快照持久化,支持全离线幂等重放;
145
- - 内置标准 Netscape `cookies.txt` 解析工具。
144
+ - `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线挂起,配合 `SQLiteSnapshotStore` 支持原始响应快照持久化与全离线幂等重放。
146
145
 
147
- ### 8. 🎛️ 执行选择 (Selection):Exclude 延迟留队 + Skip 终态跳过
148
- - **第三类调度扩展 seam(候选准入/选择,与 OrderingPolicy / RequeuePolicy 并列,决策见 [ADR-0006](docs/adr/0006-selection-scheduling-seam.md))**:`pipeline.selection(Exclude(type="pdf_to_md"), Skip(type="ocr"))` 以方法调用配置 pipeline 级规则,两类语义严格区分:
149
- - `Exclude`(延迟):命中作业不派发、不消耗资源与重试预算,队列行原样保留;下游允许作业本次报 `ERR_DEPENDENCY_EXCLUDED` 并计入 `stats["excluded_blocked"]`,下一次 run 自动恢复执行;
150
- - `Skip`(终态):命中作业移出队列(不进 wall / 失败档案),下游整链级联跳过(attempt 记 `DEPENDENCY_SKIPPED`),下次运行不再重试;同一 task_type 同时命中时 Skip 优先。
151
- - 停摆仲裁用 **Kahn 入度消减**(波前 = wall ∪ excluded)严格区分「真死锁」(依赖环/缺口 → 既有归因熔断)与「仅被 Exclude 阻塞」(留队 + COMPLETED 收敛);不存在固定等待兜底与忙旋,混合真实死锁不会被选择规则掩盖;
152
- - 默认空规则与扩展前完全等价;`Rule` 协议要求 `matches_type(task_type)`(缺少则注册期 fail-loud),顶层导出 `Exclude` / `Selection` / `Skip`。
146
+ ### 8. 🎛️ 调度扩展 Seam(排序 / 重试节奏 / 执行选择)
147
+ - 核心零调度计算,提供 `OrderingPolicy`(候选访问序)、`RequeuePolicy`(重入队节奏)与 `Selection`(候选准入)三类正交扩展接缝;
148
+ - `pipeline.selection(Exclude(task_type="..."), Skip(task_type="..."))` 支持按任务类型配置**延迟留队(Exclude)**与**终态跳过(Skip)**。
153
149
 
154
150
  ---
155
151
 
@@ -177,7 +173,7 @@ logging.getLogger("tasklite").setLevel(logging.INFO)
177
173
  # 1. 定义任务处理器(在独立子进程中执行,必须模块级定义)
178
174
  def download_handler(job: Job, ctx):
179
175
  # 声明产出文件(失败时自动清理半残文件)
180
- out = ctx.declare_output(f"./downloads/{job.job_id}.jpg", cleanup_on_fail=True)
176
+ out = ctx.declare_output(f"./downloads/{job.job_id}.jpg", delete_on_failure=True)
181
177
 
182
178
  # 模拟业务下载
183
179
  success = do_download(job.payload["url"], out)
@@ -190,13 +186,13 @@ def download_handler(job: Job, ctx):
190
186
  pipeline = TaskLite(
191
187
  name="media_downloader",
192
188
  state_dir="./state", # 状态持久化目录(SQLite WAL)
193
- output_root="./downloads", # 产物沙盒根目录
189
+ output_roots="./downloads", # 产物沙盒根目录
194
190
  max_workers=4, # 并发子进程数(内部 __workers__ 容量资源,可覆盖)
195
191
  )
196
192
 
197
193
  # 3. 注册全局限速(每秒最多 2 次请求)与 Task 规格
198
194
  pipeline.register_resource(RateLimitResource("api", interval_seconds=0.5))
199
- pipeline.register_task("download", download_handler, default_resources={"api": 1.0})
195
+ pipeline.register_task("download", download_handler, resources={"api": 1.0})
200
196
 
201
197
  # 4. 入队并启动(阻塞直到队列全部完成,返回 RunSummary)
202
198
  pipeline.enqueue([
@@ -206,27 +202,11 @@ pipeline.enqueue([
206
202
  pipeline.run()
207
203
  ```
208
204
 
209
- ---
210
-
211
- ## 🧭 三层模型(Task / Job / Attempt)
212
-
213
- 本引擎按实时系统理论建模为三层(设计总纲 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md),上位裁决 [ADR-0005](docs/adr/0005-v2-promotion.md)):
214
-
215
- | 层 | 定义 | 持久化 |
216
- |---|---|---|
217
- | **Task(规格)** | 进程内注册的静态模板:task_type 名、handler、默认资源、payload_schema、默认 max_retries / timeout | 代码即规格,不落盘;注册于 `register_task` |
218
- | **Job(逻辑实例)** | 一次有界激活;`uid = task_type::job_id` 身份不变 | queue 行 job_data JSON(uid 为主键) |
219
- | **Attempt(执行轨迹)** | 一次物理执行的记录:attempt 序号、incarnation、起止时间、结局 | append-only 新表 `attempts` |
220
-
221
- 任一 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` 标签留档)。
222
-
223
- ```python
224
- from tasklite import TaskLite, Job, Task, AttemptRecord
225
- ```
205
+ > 引擎采用 **Task(静态规格) / Job(逻辑实例) / Attempt(执行轨迹)** 三层模型,完整 API 签名、触发器(Trigger)、产物授权、失败档案与调度扩展 seam 请查阅 **[`docs/GUIDE.md`](docs/GUIDE.md)**(使用手册)。
226
206
 
227
207
  ---
228
208
 
229
- ## 🍳 实战 Recipes
209
+ ## 🍳 常见场景速览 (Recipes)
230
210
 
231
211
  ### Recipe 1: 增量分页扫描器 (Discovery)
232
212
 
@@ -236,17 +216,14 @@ from tasklite import TaskLite, Job, Task, AttemptRecord
236
216
  from tasklite.wrappers.discovery import register_discovery
237
217
 
238
218
  def fetch_page(job, ctx, page: int):
239
- # 从第 1 页开始逐页获取列表,返回空列表表示翻页结束
240
219
  return api.get_author_posts(author_id=job.payload["author_id"], page=page)
241
220
 
242
221
  def item_id(post) -> str:
243
- return str(post["id"]) # 唯一内容 ID
222
+ return str(post["id"])
244
223
 
245
224
  def process_item(job, ctx, post, content_id: str):
246
- # 发现新内容时派生子任务(content_id 已做单射编码)
247
225
  ctx.spawn(Job("download", content_id, payload={"url": post["url"]}))
248
226
 
249
- # 注册增量探索
250
227
  register_discovery(
251
228
  pipeline,
252
229
  task_type="discover_author",
@@ -254,22 +231,22 @@ register_discovery(
254
231
  id_func=item_id,
255
232
  process_item_func=process_item,
256
233
  process_task_type="download",
257
- default_resources={"api": 1.0},
234
+ resources={"api": 1.0},
258
235
  )
259
236
  ```
260
237
 
261
- ### Recipe 2: 视频转码与 DAG 依赖级联
238
+ ### Recipe 2: DAG 依赖级联与按输入 `mtime` 自动重跑
262
239
 
263
- 下载完成后自动触发转码,下载若失败则自动跳过转码:
240
+ 通过 `depends_on` 声明拓扑依赖,配合 `trigger="on_input_change"` 与 `ctx.declare_input(path)` 实现 make 式级联更新(完整可运行示例见 [`examples/trigger_chain.py`](examples/trigger_chain.py)):
264
241
 
265
242
  ```python
266
- # 构造具有拓扑依赖的任务链
267
243
  download_job = Job("download", "video_101", payload={"url": "https://example.com/v.mp4"})
268
244
  transcode_job = Job(
269
245
  "transcode",
270
246
  "video_101",
271
247
  payload={"preset": "1080p"},
272
- depends_on=[download_job.uid], # 依赖 download::video_101
248
+ depends_on=[download_job.uid], # 上游本批就绪后再判定下游,上游失败则自动级联阻断
249
+ trigger="on_input_change", # 输入文件 mtime 晚于上次可信成功完成时间才重跑
273
250
  )
274
251
 
275
252
  pipeline.enqueue([download_job, transcode_job])
@@ -292,29 +269,21 @@ def fetch_handler(job, ctx):
292
269
 
293
270
  ### Recipe 4: AI Agent / 大模型批量任务断点续跑
294
271
 
295
- 批量调用大模型处理数千条文本,多进程并发加速 + 速率控制 + 自动断点续跑:
296
-
297
272
  ```python
298
273
  import json
299
274
  from pathlib import Path
300
275
  from tasklite import TaskLite, Job, RateLimitResource
301
276
 
302
277
  def agent_worker(job: Job, ctx):
303
- # 模拟 Agent 分析并生成结果
304
- prompt = job.payload["prompt"]
305
- result = call_llm(prompt)
306
-
307
- # declare_output 返回解析后的绝对路径字符串(str),用 Path 包装后写文件,
308
- # 保证写入位置与框架校验/清理位置一致
309
- out_path = Path(ctx.declare_output(f"./results/{job.job_id}.json", cleanup_on_fail=True))
278
+ result = call_llm(job.payload["prompt"])
279
+ out_path = Path(ctx.declare_output(f"./results/{job.job_id}.json", delete_on_failure=True))
310
280
  out_path.write_text(json.dumps(result, ensure_ascii=False))
311
281
  return True, {"tokens": result.get("usage", 0)}
312
282
 
313
283
  pipeline = TaskLite(name="agent_batch", state_dir="./agent_state", max_workers=8)
314
284
  pipeline.register_resource(RateLimitResource("llm_rpm", interval_seconds=0.1))
315
- pipeline.register_task("analyze", agent_worker, default_resources={"llm_rpm": 1.0})
285
+ pipeline.register_task("analyze", agent_worker, resources={"llm_rpm": 1.0})
316
286
 
317
- # 入队海量任务,中途即使断网或意外中断,重启后自动跳过已完成任务接续执行
318
287
  pipeline.enqueue([
319
288
  Job("analyze", f"doc_{i}", payload={"prompt": f"分析文本 {i}"})
320
289
  for i in range(1000)
@@ -331,40 +300,32 @@ from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, urllib_fetch
331
300
  pipeline = TaskLite("crawler", state_dir="./states")
332
301
  pipeline.register_resource(RateLimitResource("api", interval_seconds=1.0))
333
302
 
334
- # 原始 HTTP 响应持久化快照(独立 snapshots.db,支持全离线重放与反爬保护)
335
303
  snapshot_store = SQLiteSnapshotStore("./snapshots.db")
336
304
  cached_fetch = snapshot_store.cached(urllib_fetch)
337
305
 
338
306
  def crawler_handler(job, ctx):
339
- # 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接进失败档案
340
307
  with http_guard(ctx=ctx, resource="api", default_suspend_ttl=60.0):
341
308
  resp = cached_fetch(job.payload["url"])
342
309
  return resp.json()
343
310
 
344
- pipeline.register_task("fetch", crawler_handler, default_resources={"api": 1.0})
311
+ pipeline.register_task("fetch", crawler_handler, resources={"api": 1.0})
345
312
  ```
346
313
 
347
314
  ---
348
315
 
316
+ ## 📚 文档导航与职责划分
349
317
 
350
- ## 🛠️ 失败档案与运维 (Failed & Ops)
351
-
352
- 当任务重试预算耗尽或发生致命错误时,任务进入持久化**失败档案**(failed 表,与 wall 按 uid 互斥且唯一终态)。运维 API 仅限 `run()` 外调用:
353
-
354
- ```python
355
- # 1. 检查失败详情(条目携带原始业务 payload 快照,补跑自足)
356
- for entry in pipeline.list_failures():
357
- print(f"UID: {entry.uid}, 原因: {entry.error}, 元数据: {entry.meta}")
318
+ 仓库内各文档按受众与职责严格正交划分,避免重复维护:
358
319
 
359
- # 2. 清理指定类型的失败档案(默认保留 fatal 错误,可入队同名任务重跑)
360
- pipeline.clear_failures(task_types=["download"], keep_fatal=False)
361
-
362
- # 3. 单条人工补跑:移出档案、按档案 payload 快照队首重入队
363
- pipeline.retry_failure("download::img_001")
364
-
365
- # 4. 精确或前缀清理历史(wall / failed)
366
- pipeline.clear_history("download::")
367
- ```
320
+ | 文档 | 定位与职责 |
321
+ | :--- | :--- |
322
+ | **[`README.md`](README.md)** | **项目门户与快速上手**:解决痛点、架构概览、安装与最小示例、常见场景 Recipes 速览、目录结构 |
323
+ | **[`docs/GUIDE.md`](docs/GUIDE.md)** | **使用手册**:公开导入面、三层模型与 Schema 5、触发器与恢复边界、`JobContext` 与产物清理授权、失败档案运维 API、三类调度扩展 seam |
324
+ | **[`CONTEXT.md`](CONTEXT.md)** | **领域通用语言词典**:核心领域模型与引擎内部组件的标准术语定义及禁用词表 |
325
+ | **[`docs/adr/`](docs/adr/)** | **架构决策记录(ADR)**:关键架构演进、设计取舍与边界裁决依据 |
326
+ | **[`docs/ROADMAP.md`](docs/ROADMAP.md)** | **未来演进路线图**:已分析但尚未立项实施的储备方向(实施前须立项 ADR) |
327
+ | **[`AGENTS.md`](AGENTS.md)** | **研发红线与工作流规范**:测试门槛、原子提交纪律、分层依赖红线与注释规范 |
328
+ | **[`CHANGELOG.md`](CHANGELOG.md)** | **版本变更日志**:各发布版本的显著特性与破坏性变更记录 |
368
329
 
369
330
  ---
370
331
 
@@ -388,7 +349,7 @@ tasklite/
388
349
  │ ├── recovery.py # 崩溃检测与恢复 (RecoveryOrchestrator)
389
350
  │ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel / WorkerLaunchSpec)
390
351
  │ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy 排序 seam / Selection 候选准入 seam)
391
- │ ├── admission.py # rerun 准入 (RerunPolicy) 与重入队节奏 (RequeuePolicy seam)
352
+ │ ├── admission.py # trigger 注册与求值 (TriggerRegistry) 与重入队节奏 (RequeuePolicy seam)
392
353
  │ ├── governor.py # 死锁归因仲裁与依赖宽限,消费选择停摆事实 (DeadlockGovernor)
393
354
  │ ├── selection.py # Skip 闭包与选择停摆图事实 (SelectionMachine)
394
355
  │ ├── in_flight.py # 在途作业租约追踪 (InFlightTracker)
@@ -399,7 +360,7 @@ tasklite/
399
360
  ├── testing.py # fake_ctx:handler 单测的官方 JobContext 构造器
400
361
  ├── wrappers/ # discovery.py(增量扫描)/ http.py(网络守卫与快照)
401
362
  ├── contrib/ # 生态扩展套件与参考实现(核心不依赖)
402
- └── utils/ # encoding(单射 %XX 转义)/ ipc(IPC 信号与降级落盘)/ clock / jsonutil(禁NaN)/ lockfile
363
+ └── utils/ # encoding(单射 %XX 转义)/ ipc(瞬时 Pipe 通道与产物清理原语)/ clock / jsonutil(禁NaN)/ lockfile
403
364
  ```
404
365
 
405
366
  ---
@@ -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-2200%2B%20passed-success.svg)]()
11
+ [![Tests](https://img.shields.io/badge/tests-2500%2B%20passed-success.svg)]()
12
12
 
13
13
  ---
14
14
 
@@ -46,7 +46,7 @@
46
46
  | **抗漂移增量探索 (Discovery)** | **内置函数式无游标去重** | 无 | 无 | 需自定义传感器 |
47
47
  | **全局限速与持久化休眠** | **内置令牌桶 + 跨重启持久化** | 无 | 需 Redis 限流组件 | 需复杂调度配置 |
48
48
  | **DAG 依赖与级联熔断** | **内置拓扑依赖 + 自动跳过** | 无 | 需 Canvas 复杂编排 | 原生支持 |
49
- | **产物沙盒与失败自动清理** | **内置 declare_output** | 无 | 无 | 需自定义 Hook |
49
+ | **产物沙盒与显式清理授权** | **内置 declare_output** | 无 | 无 | 需自定义 Hook |
50
50
 
51
51
  ---
52
52
 
@@ -55,7 +55,7 @@
55
55
  ```mermaid
56
56
  flowchart TD
57
57
  subgraph Host ["主调度进程 (Master Scheduler) - 永不运行业务 Handler"]
58
- State[("SQLite WAL 状态机\n(Wall / Queue / Failed / In-Flight)")]
58
+ State[("SQLite WAL 状态机\n(Successes / Queue / Failed / In-Flight)")]
59
59
  Scheduler["JobScheduler (资源调度 / 拓扑依赖)"]
60
60
  Watchdog["进程看门狗 (超时 SIGKILL / 孤儿锁探测)"]
61
61
  end
@@ -68,15 +68,15 @@ flowchart TD
68
68
 
69
69
  Scheduler -->|"1. 检查资源 & 拓扑依赖"| State
70
70
  Scheduler -->|"2. Spawn 独立子进程 (隔离)"| Workers
71
- Workers -.->|"3. 原子落盘结果/信号 (.result.json)"| State
71
+ Workers -.->|"3. 独立单向 Pipe 传递声明/信号/结果"| State
72
72
  Watchdog -->|"4. 轮询超时 SIGKILL 强杀"| Workers
73
73
  State -->|"5. BEGIN IMMEDIATE 原子收尾"| State
74
74
  ```
75
75
 
76
76
  ### 三层崩溃恢复防线
77
- 1. **执行代标识 (Generation Tag)**:结果文件携带 `{uid}.{run_id}.{seq}`,前次崩溃的孤儿进程结果对新 Run 不可见;
78
- 2. **启动期残留消费**:启动时自动识别并提交崩溃前已落盘的有效结果,不重复执行;
79
- 3. **孤儿文件锁探测 (Lockfile Fencing)**:严格保证同一 UID 在全局只有一个物理执行体。
77
+ 1. **执行代标识与通道绑定 (Generation Fencing)**:每 worker 绑定独立单向 `Pipe` 与 `{run_id}.{dispatch_no}` 执行代标识,校验 `job_uid` 与 `execution_id`,旧执行与伪造消息无法污染状态机;
78
+ 2. **可信成功事务持久化**:IPC 仅负责本次运行的瞬时通信,已提交的成功档案、`attempts` 终态与资源挂起由 SQLite 强事务持久化,未提交在途任务重启后自动接续重做;
79
+ 3. **孤儿文件锁探测 (Lockfile Fencing)**:严格保证同一 UID 在全局只有一个物理执行体,主进程崩溃后孤儿持锁期间新 Run 自动避让。
80
80
 
81
81
  ---
82
82
 
@@ -90,12 +90,12 @@ flowchart TD
90
90
 
91
91
  ### 2. ⚡ SQLite WAL 状态持久化 (ACID)
92
92
  - 基于 SQLite WAL + `synchronous=FULL` 模式;
93
- - 状态机(Wall 成功档案 / Queue 待办 / In-Flight 在途 / Failed 失败档案)在单次事务中原子转移;
93
+ - 状态机(Successes 成功档案 / Queue 待办 / In-Flight 在途 / Failed 失败档案)在单次事务中原子转移;
94
94
  - 遭遇中断或异常关机时,重启后支持 At-Least-Once 接续执行。
95
95
 
96
96
  ### 3. 🔍 函数式增量探索 (Functional Discovery)
97
97
  - 针对数据同步、采集与拉取场景的无游标 (Cursor-less) 增量扫描;
98
- - 直接复用已完成集合 (Wall) 即时判定已见内容,整页命中自动刹车,天然免疫上游记录删除、插入导致的游标漂移。
98
+ - 直接复用成功档案 (Successes) 即时判定已见内容,整页命中自动刹车,天然免疫上游记录删除、插入导致的游标漂移。
99
99
 
100
100
  ### 4. ⏸️ 全局限流与配额熔断持久化休眠
101
101
  - 内置 `RateLimitResource`(速率限制)与 `CapacityResource`(并发限制);
@@ -105,22 +105,17 @@ flowchart TD
105
105
  - 任务通过 `depends_on` 声明依赖;
106
106
  - 父任务失败进入失败档案时,所有下游依赖自动标记跳过 (`ERR_JOB_DEPENDENCY`),避免无效计算。
107
107
 
108
- ### 6. 📦 产物沙盒与自动清理
109
- - `ctx.declare_output()` 声明产出文件,内置路径遍历防御 (`../` 拒绝);
110
- - 任务成功时校验物理产出完整性,任务失败时自动清理半成品文件,避免残留。
108
+ ### 6. 📦 具名磁盘产物与显式清理授权
109
+ - `ctx.declare_output(path, name=...)` 声明文件或目录产物并随成功事务原子发布,下游通过 `ctx.get_artifact_path(...)` 安全引用直接依赖的产物路径;
110
+ - 前置删除、失败清理与成功清理分别由 `delete_existing`、`delete_on_failure`、`delete_on_success` 显式授权(`declare_cache` 固定成败自动清理),收尾时先清理后提交。
111
111
 
112
112
  ### 7. 🌐 组合式 HTTP 网络工具与快照守卫 (HTTP Wrappers)
113
113
  - 开放 Callable 设计,支持原生 `urllib`、`requests`、`httpx` 或平台自定义签名 SDK;
114
- - `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线挂起,收敛异常三分类;
115
- - `SQLiteSnapshotStore` 提供单射键原始响应快照持久化,支持全离线幂等重放;
116
- - 内置标准 Netscape `cookies.txt` 解析工具。
114
+ - `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线挂起,配合 `SQLiteSnapshotStore` 支持原始响应快照持久化与全离线幂等重放。
117
115
 
118
- ### 8. 🎛️ 执行选择 (Selection):Exclude 延迟留队 + Skip 终态跳过
119
- - **第三类调度扩展 seam(候选准入/选择,与 OrderingPolicy / RequeuePolicy 并列,决策见 [ADR-0006](docs/adr/0006-selection-scheduling-seam.md))**:`pipeline.selection(Exclude(type="pdf_to_md"), Skip(type="ocr"))` 以方法调用配置 pipeline 级规则,两类语义严格区分:
120
- - `Exclude`(延迟):命中作业不派发、不消耗资源与重试预算,队列行原样保留;下游允许作业本次报 `ERR_DEPENDENCY_EXCLUDED` 并计入 `stats["excluded_blocked"]`,下一次 run 自动恢复执行;
121
- - `Skip`(终态):命中作业移出队列(不进 wall / 失败档案),下游整链级联跳过(attempt 记 `DEPENDENCY_SKIPPED`),下次运行不再重试;同一 task_type 同时命中时 Skip 优先。
122
- - 停摆仲裁用 **Kahn 入度消减**(波前 = wall ∪ excluded)严格区分「真死锁」(依赖环/缺口 → 既有归因熔断)与「仅被 Exclude 阻塞」(留队 + COMPLETED 收敛);不存在固定等待兜底与忙旋,混合真实死锁不会被选择规则掩盖;
123
- - 默认空规则与扩展前完全等价;`Rule` 协议要求 `matches_type(task_type)`(缺少则注册期 fail-loud),顶层导出 `Exclude` / `Selection` / `Skip`。
116
+ ### 8. 🎛️ 调度扩展 Seam(排序 / 重试节奏 / 执行选择)
117
+ - 核心零调度计算,提供 `OrderingPolicy`(候选访问序)、`RequeuePolicy`(重入队节奏)与 `Selection`(候选准入)三类正交扩展接缝;
118
+ - `pipeline.selection(Exclude(task_type="..."), Skip(task_type="..."))` 支持按任务类型配置**延迟留队(Exclude)**与**终态跳过(Skip)**。
124
119
 
125
120
  ---
126
121
 
@@ -148,7 +143,7 @@ logging.getLogger("tasklite").setLevel(logging.INFO)
148
143
  # 1. 定义任务处理器(在独立子进程中执行,必须模块级定义)
149
144
  def download_handler(job: Job, ctx):
150
145
  # 声明产出文件(失败时自动清理半残文件)
151
- out = ctx.declare_output(f"./downloads/{job.job_id}.jpg", cleanup_on_fail=True)
146
+ out = ctx.declare_output(f"./downloads/{job.job_id}.jpg", delete_on_failure=True)
152
147
 
153
148
  # 模拟业务下载
154
149
  success = do_download(job.payload["url"], out)
@@ -161,13 +156,13 @@ def download_handler(job: Job, ctx):
161
156
  pipeline = TaskLite(
162
157
  name="media_downloader",
163
158
  state_dir="./state", # 状态持久化目录(SQLite WAL)
164
- output_root="./downloads", # 产物沙盒根目录
159
+ output_roots="./downloads", # 产物沙盒根目录
165
160
  max_workers=4, # 并发子进程数(内部 __workers__ 容量资源,可覆盖)
166
161
  )
167
162
 
168
163
  # 3. 注册全局限速(每秒最多 2 次请求)与 Task 规格
169
164
  pipeline.register_resource(RateLimitResource("api", interval_seconds=0.5))
170
- pipeline.register_task("download", download_handler, default_resources={"api": 1.0})
165
+ pipeline.register_task("download", download_handler, resources={"api": 1.0})
171
166
 
172
167
  # 4. 入队并启动(阻塞直到队列全部完成,返回 RunSummary)
173
168
  pipeline.enqueue([
@@ -177,27 +172,11 @@ pipeline.enqueue([
177
172
  pipeline.run()
178
173
  ```
179
174
 
180
- ---
181
-
182
- ## 🧭 三层模型(Task / Job / Attempt)
183
-
184
- 本引擎按实时系统理论建模为三层(设计总纲 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md),上位裁决 [ADR-0005](docs/adr/0005-v2-promotion.md)):
185
-
186
- | 层 | 定义 | 持久化 |
187
- |---|---|---|
188
- | **Task(规格)** | 进程内注册的静态模板:task_type 名、handler、默认资源、payload_schema、默认 max_retries / timeout | 代码即规格,不落盘;注册于 `register_task` |
189
- | **Job(逻辑实例)** | 一次有界激活;`uid = task_type::job_id` 身份不变 | queue 行 job_data JSON(uid 为主键) |
190
- | **Attempt(执行轨迹)** | 一次物理执行的记录:attempt 序号、incarnation、起止时间、结局 | append-only 新表 `attempts` |
191
-
192
- 任一 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` 标签留档)。
193
-
194
- ```python
195
- from tasklite import TaskLite, Job, Task, AttemptRecord
196
- ```
175
+ > 引擎采用 **Task(静态规格) / Job(逻辑实例) / Attempt(执行轨迹)** 三层模型,完整 API 签名、触发器(Trigger)、产物授权、失败档案与调度扩展 seam 请查阅 **[`docs/GUIDE.md`](docs/GUIDE.md)**(使用手册)。
197
176
 
198
177
  ---
199
178
 
200
- ## 🍳 实战 Recipes
179
+ ## 🍳 常见场景速览 (Recipes)
201
180
 
202
181
  ### Recipe 1: 增量分页扫描器 (Discovery)
203
182
 
@@ -207,17 +186,14 @@ from tasklite import TaskLite, Job, Task, AttemptRecord
207
186
  from tasklite.wrappers.discovery import register_discovery
208
187
 
209
188
  def fetch_page(job, ctx, page: int):
210
- # 从第 1 页开始逐页获取列表,返回空列表表示翻页结束
211
189
  return api.get_author_posts(author_id=job.payload["author_id"], page=page)
212
190
 
213
191
  def item_id(post) -> str:
214
- return str(post["id"]) # 唯一内容 ID
192
+ return str(post["id"])
215
193
 
216
194
  def process_item(job, ctx, post, content_id: str):
217
- # 发现新内容时派生子任务(content_id 已做单射编码)
218
195
  ctx.spawn(Job("download", content_id, payload={"url": post["url"]}))
219
196
 
220
- # 注册增量探索
221
197
  register_discovery(
222
198
  pipeline,
223
199
  task_type="discover_author",
@@ -225,22 +201,22 @@ register_discovery(
225
201
  id_func=item_id,
226
202
  process_item_func=process_item,
227
203
  process_task_type="download",
228
- default_resources={"api": 1.0},
204
+ resources={"api": 1.0},
229
205
  )
230
206
  ```
231
207
 
232
- ### Recipe 2: 视频转码与 DAG 依赖级联
208
+ ### Recipe 2: DAG 依赖级联与按输入 `mtime` 自动重跑
233
209
 
234
- 下载完成后自动触发转码,下载若失败则自动跳过转码:
210
+ 通过 `depends_on` 声明拓扑依赖,配合 `trigger="on_input_change"` 与 `ctx.declare_input(path)` 实现 make 式级联更新(完整可运行示例见 [`examples/trigger_chain.py`](examples/trigger_chain.py)):
235
211
 
236
212
  ```python
237
- # 构造具有拓扑依赖的任务链
238
213
  download_job = Job("download", "video_101", payload={"url": "https://example.com/v.mp4"})
239
214
  transcode_job = Job(
240
215
  "transcode",
241
216
  "video_101",
242
217
  payload={"preset": "1080p"},
243
- depends_on=[download_job.uid], # 依赖 download::video_101
218
+ depends_on=[download_job.uid], # 上游本批就绪后再判定下游,上游失败则自动级联阻断
219
+ trigger="on_input_change", # 输入文件 mtime 晚于上次可信成功完成时间才重跑
244
220
  )
245
221
 
246
222
  pipeline.enqueue([download_job, transcode_job])
@@ -263,29 +239,21 @@ def fetch_handler(job, ctx):
263
239
 
264
240
  ### Recipe 4: AI Agent / 大模型批量任务断点续跑
265
241
 
266
- 批量调用大模型处理数千条文本,多进程并发加速 + 速率控制 + 自动断点续跑:
267
-
268
242
  ```python
269
243
  import json
270
244
  from pathlib import Path
271
245
  from tasklite import TaskLite, Job, RateLimitResource
272
246
 
273
247
  def agent_worker(job: Job, ctx):
274
- # 模拟 Agent 分析并生成结果
275
- prompt = job.payload["prompt"]
276
- result = call_llm(prompt)
277
-
278
- # declare_output 返回解析后的绝对路径字符串(str),用 Path 包装后写文件,
279
- # 保证写入位置与框架校验/清理位置一致
280
- out_path = Path(ctx.declare_output(f"./results/{job.job_id}.json", cleanup_on_fail=True))
248
+ result = call_llm(job.payload["prompt"])
249
+ out_path = Path(ctx.declare_output(f"./results/{job.job_id}.json", delete_on_failure=True))
281
250
  out_path.write_text(json.dumps(result, ensure_ascii=False))
282
251
  return True, {"tokens": result.get("usage", 0)}
283
252
 
284
253
  pipeline = TaskLite(name="agent_batch", state_dir="./agent_state", max_workers=8)
285
254
  pipeline.register_resource(RateLimitResource("llm_rpm", interval_seconds=0.1))
286
- pipeline.register_task("analyze", agent_worker, default_resources={"llm_rpm": 1.0})
255
+ pipeline.register_task("analyze", agent_worker, resources={"llm_rpm": 1.0})
287
256
 
288
- # 入队海量任务,中途即使断网或意外中断,重启后自动跳过已完成任务接续执行
289
257
  pipeline.enqueue([
290
258
  Job("analyze", f"doc_{i}", payload={"prompt": f"分析文本 {i}"})
291
259
  for i in range(1000)
@@ -302,40 +270,32 @@ from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, urllib_fetch
302
270
  pipeline = TaskLite("crawler", state_dir="./states")
303
271
  pipeline.register_resource(RateLimitResource("api", interval_seconds=1.0))
304
272
 
305
- # 原始 HTTP 响应持久化快照(独立 snapshots.db,支持全离线重放与反爬保护)
306
273
  snapshot_store = SQLiteSnapshotStore("./snapshots.db")
307
274
  cached_fetch = snapshot_store.cached(urllib_fetch)
308
275
 
309
276
  def crawler_handler(job, ctx):
310
- # 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接进失败档案
311
277
  with http_guard(ctx=ctx, resource="api", default_suspend_ttl=60.0):
312
278
  resp = cached_fetch(job.payload["url"])
313
279
  return resp.json()
314
280
 
315
- pipeline.register_task("fetch", crawler_handler, default_resources={"api": 1.0})
281
+ pipeline.register_task("fetch", crawler_handler, resources={"api": 1.0})
316
282
  ```
317
283
 
318
284
  ---
319
285
 
286
+ ## 📚 文档导航与职责划分
320
287
 
321
- ## 🛠️ 失败档案与运维 (Failed & Ops)
322
-
323
- 当任务重试预算耗尽或发生致命错误时,任务进入持久化**失败档案**(failed 表,与 wall 按 uid 互斥且唯一终态)。运维 API 仅限 `run()` 外调用:
324
-
325
- ```python
326
- # 1. 检查失败详情(条目携带原始业务 payload 快照,补跑自足)
327
- for entry in pipeline.list_failures():
328
- print(f"UID: {entry.uid}, 原因: {entry.error}, 元数据: {entry.meta}")
288
+ 仓库内各文档按受众与职责严格正交划分,避免重复维护:
329
289
 
330
- # 2. 清理指定类型的失败档案(默认保留 fatal 错误,可入队同名任务重跑)
331
- pipeline.clear_failures(task_types=["download"], keep_fatal=False)
332
-
333
- # 3. 单条人工补跑:移出档案、按档案 payload 快照队首重入队
334
- pipeline.retry_failure("download::img_001")
335
-
336
- # 4. 精确或前缀清理历史(wall / failed)
337
- pipeline.clear_history("download::")
338
- ```
290
+ | 文档 | 定位与职责 |
291
+ | :--- | :--- |
292
+ | **[`README.md`](README.md)** | **项目门户与快速上手**:解决痛点、架构概览、安装与最小示例、常见场景 Recipes 速览、目录结构 |
293
+ | **[`docs/GUIDE.md`](docs/GUIDE.md)** | **使用手册**:公开导入面、三层模型与 Schema 5、触发器与恢复边界、`JobContext` 与产物清理授权、失败档案运维 API、三类调度扩展 seam |
294
+ | **[`CONTEXT.md`](CONTEXT.md)** | **领域通用语言词典**:核心领域模型与引擎内部组件的标准术语定义及禁用词表 |
295
+ | **[`docs/adr/`](docs/adr/)** | **架构决策记录(ADR)**:关键架构演进、设计取舍与边界裁决依据 |
296
+ | **[`docs/ROADMAP.md`](docs/ROADMAP.md)** | **未来演进路线图**:已分析但尚未立项实施的储备方向(实施前须立项 ADR) |
297
+ | **[`AGENTS.md`](AGENTS.md)** | **研发红线与工作流规范**:测试门槛、原子提交纪律、分层依赖红线与注释规范 |
298
+ | **[`CHANGELOG.md`](CHANGELOG.md)** | **版本变更日志**:各发布版本的显著特性与破坏性变更记录 |
339
299
 
340
300
  ---
341
301
 
@@ -359,7 +319,7 @@ tasklite/
359
319
  │ ├── recovery.py # 崩溃检测与恢复 (RecoveryOrchestrator)
360
320
  │ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel / WorkerLaunchSpec)
361
321
  │ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy 排序 seam / Selection 候选准入 seam)
362
- │ ├── admission.py # rerun 准入 (RerunPolicy) 与重入队节奏 (RequeuePolicy seam)
322
+ │ ├── admission.py # trigger 注册与求值 (TriggerRegistry) 与重入队节奏 (RequeuePolicy seam)
363
323
  │ ├── governor.py # 死锁归因仲裁与依赖宽限,消费选择停摆事实 (DeadlockGovernor)
364
324
  │ ├── selection.py # Skip 闭包与选择停摆图事实 (SelectionMachine)
365
325
  │ ├── in_flight.py # 在途作业租约追踪 (InFlightTracker)
@@ -370,7 +330,7 @@ tasklite/
370
330
  ├── testing.py # fake_ctx:handler 单测的官方 JobContext 构造器
371
331
  ├── wrappers/ # discovery.py(增量扫描)/ http.py(网络守卫与快照)
372
332
  ├── contrib/ # 生态扩展套件与参考实现(核心不依赖)
373
- └── utils/ # encoding(单射 %XX 转义)/ ipc(IPC 信号与降级落盘)/ clock / jsonutil(禁NaN)/ lockfile
333
+ └── utils/ # encoding(单射 %XX 转义)/ ipc(瞬时 Pipe 通道与产物清理原语)/ clock / jsonutil(禁NaN)/ lockfile
374
334
  ```
375
335
 
376
336
  ---
@@ -30,7 +30,7 @@ Homepage = "https://github.com/CaptainLi321/tasklite"
30
30
  Repository = "https://github.com/CaptainLi321/tasklite"
31
31
 
32
32
  [project.optional-dependencies]
33
- dev = ["pytest", "hypothesis>=6.0", "mutmut>=3.0", "pytest-timeout>=2.0", "pytest-cov>=4.0", "requests>=2.28"]
33
+ dev = ["pytest", "hypothesis>=6.0", "mutmut>=3.0", "pytest-timeout>=2.0", "pytest-cov>=4.0", "requests>=2.28", "mypy>=1.0"]
34
34
 
35
35
  [tool.setuptools.packages.find]
36
36
  include = ["tasklite", "tasklite.*"]