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